Merge pull request #24 from huggingface/feat/libghostty-session-model

Dockerfile

@@ -10,7 +10,9 @@ RUN npm run build
 # Node 22+: required by OpenClaw (22.19+); everything else is version-agnostic.
 FROM node:22-bookworm AS runtime
 
-# System deps: tmux (session durability), git, build tools (node-pty native build),
+# System deps: git, build tools (node-pty native build),
+# tmux is still installed for AGENTS to use if they want it — the app itself no
+# longer runs sessions through it (see server/src/runner.js),
 # ripgrep (used by the coding CLIs), curl/ca-certs — plus everyday QoL tools
 # agents and humans reach for (jq/htop/sqlite3/editors/media, fonts so headless
 # Chromium screenshots don't render tofu).
@@ -118,14 +120,14 @@ RUN [ -x /home/node/.local/bin/hermes ] \
       || true
 USER node
 
-# App code + built frontend + runtime config (tmux + prompt rcfile).
+# App code + built frontend + runtime config (prompt rcfile).
 COPY --chown=node:node server/ server/
 # scripts/ is not developer-only: share.js runs scripts/share-session.mjs as a
 # child process to build a share bundle off the event loop, so it must ship.
 COPY --chown=node:node scripts/ scripts/
 COPY --chown=node:node --from=web /web/dist /app/public
 COPY --chown=node:node entrypoint.sh /app/entrypoint.sh
-COPY --chown=node:node tmux.conf session.bashrc /app/
+COPY --chown=node:node session.bashrc /app/
 
 ENV PORT=7860 \
     DATA_DIR=/data \

README.md

@@ -18,8 +18,9 @@ file browser, all in your browser. Each agent runs in a workspace folder you
 pick at creation (defaulting to where the last agent was created) — names are
 just labels, independent of folders, and several agents can share a folder.
 Groups are visual: they organize the sidebar and tile agents side by side.
-Sessions are
-tmux-backed, so they survive disconnects. A **Skills** page distributes reusable
+Sessions live in the
+backend, so they survive disconnects and can be watched from several devices at
+once. A **Skills** page distributes reusable
 `SKILL.md` files to every agent, and a **Usage** page shows tokens/cost and your
 5-hour / weekly quota.
 
@@ -117,14 +118,28 @@ and `CODEX_HOME` under `/data/state`).
 browser (xterm.js panes)
   └── WebSocket /ws?session=<id>          one connection per visible pane
         └── Node backend (Express + ws)
-              └── node-pty → tmux session per agent   ← survives disconnect/restart
+              └── node-pty per agent + a libghostty-vt grid   ← the live screen
                     └── claude | codex | gemini | opencode | hermes | bash
 ```
 
-Each agent is a long-lived `tmux` session (`am-<id>`) that survives browser
-disconnects and in-Space server restarts. It does not survive a Space
-sleep/rebuild (the container is torn down), but with storage the working dir and
-CLI state persist, so a re-opened session resumes its own conversation. Claude
+Each agent is a PTY held by the backend, with a **libghostty-vt** terminal fed
+from its output. That grid is the authoritative screen, so reopening a pane is a
+canonical serialization of its retained history and styled screen rather than a
+truncated PTY byte replay, and agent state is read from the grid instead of
+shelling out per session. Several browsers can watch the same session, but one
+explicit controller owns input and PTY dimensions; interacting with a watcher
+claims control. This prevents background tabs and small phones from resizing a
+desktop session, and prevents several browser emulators from all answering the
+same terminal query.
+
+A resize is a controller request. The backend coalesces window-drag bursts,
+allows Ghostty to perform normal reflow, then tells every viewer the confirmed
+geometry before more PTY output arrives. Full history serialization is reserved
+for attach/reconnect. Browser zoom is presentation-only: it changes cell size
+and pans locally without resizing the PTY. Sessions survive browser disconnects
+but not a backend restart or Space sleep/rebuild; with storage the working
+directory and CLI state persist, so a reopened session resumes its own
+conversation. Claude
 sessions are pinned to a per-session conversation id at creation; Codex sessions
 are pinned right after first launch (the id is captured from the rollout file
 Codex creates) — so agents sharing a folder never resume each other's
@@ -136,7 +151,8 @@ conversations.
 |---|---|---|
 | `PORT` | `7860` | HTTP + WS port (HF `app_port`) |
 | `DATA_DIR` | `/data` | Durable root (mounted private Storage Bucket) |
-| `USE_TMUX` | auto | `1`/`0` to force tmux on/off (off = direct PTY, no persistence) |
+| `AM_SCROLLBACK_BYTES` | `67108864` | Maximum Ghostty scrollback memory per session |
+| `AM_RESIZE_SETTLE_MS` | `120` | Quiet period before a resize is applied to the PTY |
 | `ANTHROPIC_API_KEY` | — | Claude Code / opencode / Hermes (Space **secret**) |
 | `OPENAI_API_KEY` / `CODEX_API_KEY` | — | Codex (Space secret) |
 | `GEMINI_API_KEY` | — | Gemini CLI (Space secret) |
@@ -147,7 +163,7 @@ Logging in interactively inside a terminal works too — credentials are written
 ## Local development
 
 ```bash
-# backend (no tmux locally → direct-PTY mode; only the Shell CLI works offline)
+# backend (needs node >= 20.19 for libghostty-vt; only the Shell CLI works offline)
 cd server && npm install && npm run dev
 
 # frontend (proxies /api and /ws to the backend on :7860)

server/fixtures/ink-tui.mjs

@@ -0,0 +1,63 @@
+// A stand-in for an agent TUI built the way Claude Code is: Ink (React) on the
+// PRIMARY screen, re-rendering its whole frame when the terminal resizes.
+//
+// This matters because Ink does not repaint by absolute positioning the way
+// fixtures/repaint-tui.mjs does. It PRINTS its frame — cursor up by the previous
+// frame's height, erase downward, print the lines — so a frame taller than the
+// screen scrolls the excess into scrollback, and a frame whose height changed
+// (which is exactly what a width change does, by rewrapping) erases the wrong
+// region and leaves the difference behind. That is the artifact a real agent pane
+// shows on zoom, and no hand-written repaint reproduces it.
+//
+// Every token is unique (`LLL.CC`), so a token appearing twice in the grid is a
+// real duplicate and not two identical filler lines.
+//
+// NOT wired into resize.test.mjs, and ink is deliberately NOT a dependency:
+// installing it here pruned @coder/libghostty-vt-node's native prebuild and broke
+// every session until `npm install` put it back. Run it out of tree instead —
+//
+//   mkdir /tmp/inkbox && cd /tmp/inkbox
+//   npm init -y && npm i ink react
+//   cp .../fixtures/ink-tui.mjs . && node ink-tui.mjs
+//
+// The finding it produced is recorded where it matters: Ink erases its previous
+// frame by height before reprinting, so an Ink app leaves no duplicates on resize.
+// The artifacts a real agent pane shows come from a frame that OVERFLOWS the
+// screen, which fixtures/repaint-tui.mjs reproduces with FIXED_LINES set.
+import React from 'react';
+import { render, Box, Text, useStdout } from 'ink';
+
+const TRANSCRIPT = Array.from({ length: 60 }, (_, i) =>
+  Array.from({ length: 22 }, (_, j) => `${String(i + 1).padStart(3, '0')}.${String(j).padStart(2, '0')}`).join(' '));
+
+function App() {
+  const { stdout } = useStdout();
+  const [size, setSize] = React.useState({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+  React.useEffect(() => {
+    const onResize = () => setSize({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+    stdout.on('resize', onResize);
+    return () => stdout.off('resize', onResize);
+  }, [stdout]);
+
+  // A fixed number of transcript lines, NOT trimmed to fit — the important part.
+  // An agent renders the tail of its conversation, so narrowing the pane wraps
+  // those lines and the frame becomes TALLER than the screen. Printing it then
+  // scrolls the overflow into scrollback, which is where the duplicates a user
+  // sees after zooming in actually come from.
+  const KEEP = 30;
+  return React.createElement(
+    Box,
+    { flexDirection: 'column' },
+    ...TRANSCRIPT.slice(-KEEP).map((line, i) => React.createElement(Text, { key: i }, line)),
+    React.createElement(
+      Box,
+      { borderStyle: 'round', paddingX: 1 },
+      React.createElement(Text, null, `[ink ${size.cols}x${size.rows}]`),
+    ),
+  );
+}
+
+render(React.createElement(App));
+// Stay up like an agent waiting for input, so a resize has something to answer.
+process.stdin.resume();
+setInterval(() => {}, 1 << 30);

server/fixtures/repaint-tui.mjs

@@ -0,0 +1,62 @@
+// A stand-in for an agent TUI, for the resize tests. Repaints the way Claude
+// Code does (measured from a live pane): hide the cursor, home, erase every
+// visible row with `\x1b[2K\x1b[1B`, home again, then print the tail of its
+// transcript wrapped to the CURRENT width — no screen clear, no scrollback
+// clear, no alternate screen. That is what makes a resize duplicate content:
+// rows the emulator pushed into scrollback while shrinking are printed again.
+//
+// Every token is unique (`LLL.CC`), so a token appearing twice in the grid is a
+// real duplicate and not two identical filler lines.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const COLS = () => process.stdout.columns || 80;
+const ROWS = () => process.stdout.rows || 24;
+
+const TRANSCRIPT = Array.from({ length: 60 }, (_, i) =>
+  Array.from({ length: 22 }, (_, j) => `${String(i + 1).padStart(3, '0')}.${String(j).padStart(2, '0')}`).join(' '));
+
+// With FIXED_LINES set, print that many transcript lines whatever the size —
+// which is what an agent showing the tail of a conversation does. Narrowing the
+// pane then WRAPS those lines, so the printed frame becomes taller than the screen
+// and printing it scrolls the overflow into scrollback. That overflow is a copy of
+// what the frame also shows, and it is the artifact a real agent pane leaves
+// behind on zoom. Without the variable, the frame is trimmed to fit and nothing
+// scrolls.
+const FIXED = Number(process.env.FIXED_LINES || 0);
+const HISTORY = Number(process.env.HISTORY_LINES || 0);
+
+function paint(limit = null) {
+  let out = '\x1b[?25l\x1b[H';
+  for (let r = 0; r < ROWS(); r++) out += '\x1b[2K\x1b[1B';
+  out += '\x1b[H';
+  // Print enough of the transcript to fill the screen at this width — the tail,
+  // like a TUI showing the most recent output above its input box.
+  const perLine = Math.max(1, Math.ceil(TRANSCRIPT[0].length / COLS()));
+  const fit = Math.max(1, Math.floor((ROWS() - 2) / perLine));
+  out += TRANSCRIPT.slice(-(limit ?? (FIXED || fit)))
+    .map((line, index) => `\x1b[38;5;${31 + (index % 6)}m${line}\x1b[0m`)
+    .join('\r\n');
+  out += `\r\n[fixture ${COLS()}x${ROWS()}]\x1b[?25h`;
+  process.stdout.write(out);
+}
+
+process.stdout.on('resize', paint);
+process.stdin.resume();
+if (HISTORY > 0) {
+  process.stdout.write(Array.from({ length: HISTORY }, (_, i) =>
+    `history-${String(i + 1).padStart(4, '0')}`).join('\r\n') + '\r\n');
+}
+const resumeDelay = Number(process.env.DELAY_RESUME_MS || 0);
+const launchMarker = path.join(process.cwd(), '.repaint-fixture-launched');
+if (resumeDelay > 0 && fs.existsSync(launchMarker)) {
+  // Claude can pause after the first part of its resumed screen. A startup
+  // capture must span that gap; otherwise the remainder is mistaken for new
+  // terminal history and duplicates the persisted transcript.
+  paint(1);
+  setTimeout(paint, resumeDelay);
+} else {
+  if (resumeDelay > 0) fs.writeFileSync(launchMarker, '1');
+  paint();
+}
+setInterval(() => {}, 1 << 30);

server/migration.test.mjs

@@ -0,0 +1,203 @@
+// End-to-end check of the libghostty-backed session model.
+// Uses a `shell` session so it costs no agent tokens.
+//   node migration.test.mjs
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { WebSocket } from 'ws';
+
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-migration-'));
+
+const PORT = 7893;
+const CTRL = '\x00\x00AM:';
+const base = `http://localhost:${PORT}`;
+
+let failures = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? `  ${detail}` : ''}`);
+  if (!ok) failures++;
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const srv = spawn('node', ['src/index.js'], {
+  env: { ...process.env, PORT: String(PORT), DATA_DIR, AM_BASHRC: '/nonexistent' },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+let bootLog = '';
+srv.stdout.on('data', (d) => { bootLog += d; });
+srv.stderr.on('data', (d) => { bootLog += d; });
+
+/** A viewer: collects raw bytes and control frames, can send input/resize/claim. */
+function view(id, cols = 100, rows = 30) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://localhost:${PORT}/ws?session=${id}&cols=${cols}&rows=${rows}`);
+    const v = {
+      bytes: '', frames: [], closes: [],
+      type: (d) => ws.send(JSON.stringify({ t: 'i', d })),
+      resize: (c, r) => ws.send(JSON.stringify({ t: 'r', cols: c, rows: r })),
+      claim: () => ws.send(JSON.stringify({ t: 'claim' })),
+      lastFrame: (t) => [...v.frames].reverse().find((f) => f.t === t) || null,
+      open: () => ws.readyState === 1,
+      close: () => { try { ws.close(); } catch {} },
+    };
+    ws.on('message', (data) => {
+      const s = data.toString('utf8');
+      if (s.startsWith(CTRL)) { try { v.frames.push(JSON.parse(s.slice(CTRL.length))); } catch {} }
+      else v.bytes += s;
+    });
+    ws.on('close', (code) => v.closes.push(code));
+    ws.on('open', () => resolve(v));
+    ws.on('error', () => resolve(v));
+  });
+}
+
+const stateOf = async (id) => {
+  const tree = await (await fetch(`${base}/api/tree`)).json();
+  return (tree.sessions || []).find((s) => s.id === id) || null;
+};
+
+try {
+  let up = false;
+  // Generous: importing the dependency tree off a cold FUSE-mounted workspace can
+  // take half a minute (express alone measured 32s), and a boot timeout looks
+  // exactly like a broken server.
+  for (let i = 0; i < 400; i++) {
+    try { const r = await fetch(`${base}/api/health`); if (r.ok) { up = true; break; } } catch {}
+    await sleep(250);
+  }
+  check('server boots without tmux', up);
+  if (!up) { console.log(bootLog.slice(-1500)); throw new Error('no boot'); }
+
+  const health = await (await fetch(`${base}/api/health`)).json();
+  check('health reports the libghostty engine', health.engine === 'libghostty' && health.ghostty === true,
+    health.ghosttyError || `engine=${health.engine} ghostty=${health.ghostty}`);
+
+  const created = await (await fetch(`${base}/api/sessions`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli: 'shell', name: 'mig test' }),
+  })).json();
+  check('session created', !!created.id, created.id || JSON.stringify(created).slice(0, 140));
+  const id = created.id;
+  if (!id) throw new Error('no session');
+
+  // --- attach, run something, verify output ---------------------------------
+  const a = await view(id);
+  check('viewer attaches', a.open());
+  await sleep(1500);
+  check('the first viewer controls the session', a.lastFrame('restore')?.controller === true);
+  a.type('echo hello-from-viewer-a\r');
+  await sleep(1300);
+  check('input reaches the PTY and output comes back', a.bytes.includes('hello-from-viewer-a'),
+    `${a.bytes.length}B received`);
+
+  // --- closing the browser must NOT kill the session ------------------------
+  a.close();
+  await sleep(700);
+  const survived = await stateOf(id);
+  check('session survives the viewer closing', !!survived && survived.state !== 'stopped',
+    survived ? `state=${survived.state}` : 'missing from tree');
+
+  // --- work continues with nobody attached ---------------------------------
+  await fetch(`${base}/api/sessions/${id}/input`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: 'echo ran-while-detached' }),
+  });
+  await sleep(1600);
+
+  // --- reattach: restore frame + canonical scrollback -----------------------
+  const b = await view(id);
+  await sleep(1000);
+  const restore = b.lastFrame('restore');
+  check('reattach sends a restore frame', !!restore, restore && `${restore.cols}x${restore.rows}`);
+  check('restore serializes earlier scrollback', b.bytes.includes('hello-from-viewer-a'),
+    `${b.bytes.length}B restored`);
+  check('restore includes work done while detached', b.bytes.includes('ran-while-detached'));
+  check('no tmux [exited] noise', !b.bytes.includes('[exited]'));
+
+  // --- state comes from the grid, no subprocess ----------------------------
+  b.type('for i in 1 2 3 4 5 6 7 8; do echo busy $i; sleep 0.4; done\r');
+  await sleep(1700);
+  const busy = await stateOf(id);
+  check('a busy session reads as working', busy && busy.state === 'working', busy && busy.state);
+  // Poll rather than guess: the loop above takes ~3.2s and the working
+  // threshold is 4s of unchanged text, so a fixed sleep races the transition.
+  let calm = null;
+  for (let i = 0; i < 30; i++) {
+    calm = await stateOf(id);
+    if (calm && calm.state === 'idle') break;
+    await sleep(500);
+  }
+  check('an idle shell settles back to idle', calm && calm.state === 'idle', calm && calm.state);
+
+  // --- the agent-watch API still works, now off the grid --------------------
+  // capturePane() reads the held grid directly. Same shape as the old endpoint:
+  // plain text, with screen and scrollback above it.
+  const tailRes = await fetch(`${base}/api/agents/${id}/tail?lines=200`);
+  const tail = await tailRes.json();
+  const tailText = typeof tail === 'string' ? tail : (tail.text || tail.tail || JSON.stringify(tail));
+  check('agent tail endpoint answers from the grid', tailRes.ok && tailText.length > 0,
+    `${tailText.length} chars`);
+  check('agent tail includes screen AND scrollback',
+    tailText.includes('hello-from-viewer-a') && tailText.includes('busy 8'),
+    tailText.includes('hello-from-viewer-a') ? 'has scrollback' : 'MISSING scrollback');
+  check('agent tail has no trailing blank padding', !/\n\s*\n\s*$/.test(tailText));
+
+  // --- two viewers share one grid with one explicit controller --------------
+  const c = await view(id, 150, 40);
+  await sleep(400);
+  c.resize(150, 40);
+  await sleep(500);
+  b.resize(40, 20);
+  await sleep(900);
+  check('both viewers stay connected (no handover)', b.open() && c.open());
+  const bGrid = b.lastFrame('grid');
+  const cGrid = c.lastFrame('grid');
+  check('both viewers are told the same grid',
+    !!bGrid && !!cGrid && bGrid.cols === cGrid.cols && bGrid.rows === cGrid.rows,
+    bGrid && cGrid ? `${bGrid.cols}x${bGrid.rows} vs ${cGrid.cols}x${cGrid.rows}` : 'missing grid frame');
+  check('grid follows the controller, not the smallest viewer', !!bGrid && bGrid.cols === 40 && bGrid.rows === 20,
+    bGrid && `${bGrid.cols}x${bGrid.rows}`);
+  check('viewer roles are explicit', !!bGrid && bGrid.controller === true && bGrid.viewers === 2
+    && cGrid?.controller === false && cGrid.viewers === 2);
+  c.type('echo ignored-watcher-input\r');
+  await sleep(500);
+  check('watcher input is ignored', !b.bytes.includes('ignored-watcher-input'));
+  c.claim();
+  await sleep(700);
+  const claimed = c.lastFrame('grid');
+  check('a watcher can explicitly claim control', !!claimed && claimed.controller === true
+    && claimed.cols === 150 && claimed.rows === 40,
+    claimed && `${claimed.cols}x${claimed.rows} controller=${claimed.controller}`);
+  c.type('echo seen-by-both\r');
+  await sleep(1100);
+  check('both viewers see the same live output',
+    b.bytes.includes('seen-by-both') && c.bytes.includes('seen-by-both'));
+
+  b.resize(60, 20);
+  await sleep(500);
+  const stays = c.lastFrame('grid');
+  check('a watcher resize cannot disturb the controller', !!stays && stays.cols === 150 && stays.rows === 40,
+    stays && `${stays.cols}x${stays.rows}`);
+  b.close();
+
+  // --- stopping is explicit ------------------------------------------------
+  await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+  await sleep(1000);
+  check('explicit stop closes viewers with the exit code', c.closes.includes(4000),
+    `codes=${JSON.stringify(c.closes)}`);
+  const after = await stateOf(id);
+  check('stopped session reports stopped', after && after.state === 'stopped', after && after.state);
+
+  await fetch(`${base}/api/sessions/${id}`, { method: 'DELETE' }).catch(() => {});
+} catch (err) {
+  check('no exceptions', false, String(err && err.message ? err.message : err));
+  console.log('--- server log tail ---\n' + bootLog.slice(-1200));
+} finally {
+  srv.kill('SIGTERM');
+  await sleep(600);
+  srv.kill('SIGKILL');
+  try { fs.rmSync(DATA_DIR, { recursive: true, force: true }); } catch {}
+  console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+  process.exit(failures ? 1 : 0);
+}

server/mobile.test.mjs

@@ -0,0 +1,612 @@
+// Browser-level mobile terminal invariants.
+//
+// This deliberately starts with a desktop controller so opening the same
+// session on a phone exercises the watcher -> controller handoff. Chromium's
+// visual viewport is replaced with a controllable EventTarget so the keyboard
+// test covers both viewport height and iOS's non-zero offsetTop.
+//
+//   npm run test:mobile
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import { WebSocket } from 'ws';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.dirname(HERE);
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-mobile-'));
+const PUBLIC_DIR = process.env.MOBILE_PUBLIC_DIR || path.join(DATA_DIR, 'public');
+const API = 'http://127.0.0.1:7896';
+const WEB = API;
+const CTRL = '\x00\x00AM:';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+let failures = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? `  ${detail}` : ''}`);
+  if (!ok) failures++;
+};
+const waitFor = async (fn, timeout = 15_000) => {
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    try { if (await fn()) return true; } catch {}
+    await sleep(100);
+  }
+  return false;
+};
+
+if (!process.env.MOBILE_PUBLIC_DIR) {
+  const build = spawnSync('npm', ['run', 'build', '--', '--outDir', PUBLIC_DIR], {
+    cwd: path.join(ROOT, 'web'), encoding: 'utf8',
+  });
+  if (build.status !== 0) {
+    throw new Error(`mobile test web build failed:\n${build.stdout}\n${build.stderr}`);
+  }
+}
+
+const backend = spawn('node', ['src/index.js'], {
+  cwd: HERE,
+  // Do not inherit the production Space hostname: this backend is deliberately
+  // reached through localhost, and the origin guard should validate it as such.
+  env: {
+    ...process.env,
+    PORT: '7896', DATA_DIR, PUBLIC_DIR, AM_BASHRC: '/nonexistent', SPACE_HOST: '',
+  },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+let logs = '';
+for (const child of [backend]) {
+  child.stdout.on('data', (data) => { logs += data; });
+  child.stderr.on('data', (data) => { logs += data; });
+}
+
+let browser;
+let desktop;
+let id;
+let secondId;
+try {
+  const ready = await waitFor(async () => {
+    return fetch(`${API}/api/health`).then((r) => r.ok).catch(() => false);
+  }, 60_000);
+  if (!ready) throw new Error(`test servers did not start:\n${logs.slice(-2000)}`);
+  await fetch(`${API}/api/welcome/seen`, { method: 'POST' });
+  const created = await (await fetch(`${API}/api/sessions`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli: 'shell', name: 'mobile-terminal-e2e', path: '.' }),
+  })).json();
+  id = created.id;
+  if (!id) throw new Error(`session creation failed: ${JSON.stringify(created)}`);
+  const second = await (await fetch(`${API}/api/sessions`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli: 'shell', name: 'mobile-terminal-second', path: '.' }),
+  })).json();
+  secondId = second.id;
+  if (!secondId) throw new Error(`second session creation failed: ${JSON.stringify(second)}`);
+
+  const desktopFrames = [];
+  desktop = new WebSocket(`ws://127.0.0.1:7896/ws?session=${id}&cols=140&rows=45`);
+  desktop.on('message', (raw) => {
+    const text = raw.toString();
+    if (text.startsWith(CTRL)) desktopFrames.push(JSON.parse(text.slice(CTRL.length)));
+  });
+  await new Promise((resolve, reject) => {
+    desktop.once('open', resolve);
+    desktop.once('error', reject);
+  });
+  await sleep(400);
+  desktop.send(JSON.stringify({
+    t: 'i',
+    d: "for i in $(seq 1 220); do printf 'MOBILE-HISTORY-%04d\\n' \"$i\"; done; printf '\\033[?1000h\\033[?1006h'\r",
+  }));
+  const historyReady = await waitFor(async () => {
+    const body = await (await fetch(`${API}/api/agents/${id}/tail?lines=400`)).json();
+    return body.text?.includes('MOBILE-HISTORY-0220');
+  });
+  if (!historyReady) throw new Error('history did not reach the terminal');
+
+  browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: 375, height: 667 },
+    screen: { width: 375, height: 667 },
+    deviceScaleFactor: 2,
+    hasTouch: true,
+    isMobile: true,
+    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148',
+  });
+  await context.addInitScript(() => {
+    const nativeWebSocket = window.WebSocket;
+    window.__terminalSockets = [];
+    class RecordedWebSocket extends nativeWebSocket {
+      constructor(url, protocols) {
+        super(url, protocols);
+        if (String(url).includes('/ws?session=')) {
+          const record = { url: String(url), sent: [], events: [] };
+          window.__terminalSockets.push(record);
+          this.addEventListener('open', () => record.events.push({ type: 'open' }));
+          this.addEventListener('close', (event) => record.events.push({
+            type: 'close', code: event.code, reason: event.reason,
+          }));
+          this.addEventListener('error', () => record.events.push({ type: 'error' }));
+          this.addEventListener('message', (event) => {
+            record.events.push({ type: 'message', dataType: typeof event.data });
+            if (typeof event.data === 'string' && event.data.startsWith('\x00\x00AM:')) {
+              try { record.lastFrame = JSON.parse(event.data.slice(5)); } catch {}
+            }
+          });
+          const nativeSend = this.send;
+          this.send = (data) => {
+            try { record.sent.push(JSON.parse(String(data))); } catch {}
+            return nativeSend.call(this, data);
+          };
+        }
+      }
+    }
+    class OfflineWebSocket extends EventTarget {
+      static CONNECTING = 0;
+      static OPEN = 1;
+      static CLOSING = 2;
+      static CLOSED = 3;
+      readyState = OfflineWebSocket.CONNECTING;
+      binaryType = 'blob';
+      send() {}
+      close() { this.readyState = OfflineWebSocket.CLOSED; }
+    }
+    let offline = false;
+    try { offline = localStorage.getItem('__am_test_offline_sockets') === '1'; } catch {}
+    window.WebSocket = offline ? OfflineWebSocket : RecordedWebSocket;
+
+    const viewport = new EventTarget();
+    Object.assign(viewport, {
+      width: 375, height: 667, offsetLeft: 0, offsetTop: 0,
+      pageLeft: 0, pageTop: 0, scale: 1,
+    });
+    Object.defineProperty(window, 'visualViewport', {
+      configurable: true, value: viewport,
+    });
+    const virtualKeyboard = new EventTarget();
+    virtualKeyboard.boundingRect = new DOMRect(0, 667, 375, 0);
+    Object.defineProperty(navigator, 'virtualKeyboard', {
+      configurable: true, value: virtualKeyboard,
+    });
+    window.__setVirtualKeyboard = (top, height, width = viewport.width) => {
+      virtualKeyboard.boundingRect = new DOMRect(0, top, width, height);
+      virtualKeyboard.dispatchEvent(new Event('geometrychange'));
+    };
+    window.__setVisualViewport = (height, offsetTop, width = viewport.width) => {
+      viewport.width = width;
+      viewport.height = height;
+      viewport.offsetTop = offsetTop;
+      viewport.pageTop = offsetTop;
+      viewport.dispatchEvent(new Event('resize'));
+      viewport.dispatchEvent(new Event('scroll'));
+    };
+    // Safari can fire with the final height but a stale zero offset, then update
+    // offsetTop without another event. Focus stabilization must catch that.
+    window.__setVisualViewportLate = (height, offsetTop, delay = 80) => {
+      viewport.height = height;
+      viewport.offsetTop = 0;
+      viewport.pageTop = 0;
+      viewport.dispatchEvent(new Event('resize'));
+      setTimeout(() => {
+        viewport.offsetTop = offsetTop;
+        viewport.pageTop = offsetTop;
+      }, delay);
+    };
+  });
+  const page = await context.newPage();
+  await page.goto(WEB, { waitUntil: 'domcontentloaded' });
+  await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
+
+  const latestGrid = () => [...desktopFrames].reverse().find((frame) =>
+    frame.t === 'grid' || frame.t === 'restore');
+  const mobileClaimed = await waitFor(() => desktopFrames.some((frame) =>
+    frame.t === 'grid' && frame.controller === false && frame.cols < 60));
+  const initialSocket = await page.evaluate(() => window.__terminalSockets.at(-1));
+  check('opening a session on mobile claims geometry before resizing',
+    mobileClaimed && initialSocket?.sent?.some((message) => message.t === 'claim'),
+    JSON.stringify({
+      mobileClaimed,
+      id,
+      mobileUrl: initialSocket?.url,
+      mobileFrame: initialSocket?.lastFrame,
+      mobileEvents: initialSocket?.events,
+      sent: initialSocket?.sent,
+      desktopState: desktop.readyState,
+      desktopLast: latestGrid(),
+    }));
+
+  const initialFit = await page.evaluate(() => {
+    const host = document.querySelector('.tile-terminal:not(.tile-cached) .term-host').getBoundingClientRect();
+    const screen = document.querySelector('.tile-terminal:not(.tile-cached) .xterm-screen').getBoundingClientRect();
+    return { host: { width: host.width, height: host.height }, screen: { width: screen.width, height: screen.height } };
+  });
+  check('the initial mobile terminal fits its panel in both dimensions',
+    initialFit.screen.width <= initialFit.host.width + 1
+      && initialFit.screen.height <= initialFit.host.height + 1,
+    JSON.stringify(initialFit));
+
+  // Switching to another session and back must retain the original xterm and
+  // WebSocket. A mobile Back alone was never sufficient to catch this: it only
+  // hides the whole stage without changing activeRef.
+  const firstSocketUrl = initialSocket.url;
+  await page.getByTitle('Back to list').click();
+  await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-second' }).first().click();
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
+  const secondOpened = await waitFor(() => page.evaluate(() => window.__terminalSockets.length === 2));
+  await page.getByTitle('Back to list').click();
+  await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
+  await sleep(250);
+  const retained = await page.evaluate((url) => {
+    const matching = window.__terminalSockets.filter((socket) => socket.url === url);
+    const cachedTiles = [...document.querySelectorAll('.tile-terminal')];
+    return {
+      matching: matching.length,
+      closed: matching.flatMap((socket) => socket.events).some((event) => event.type === 'close'),
+      terminals: document.querySelectorAll('.tile-terminal .xterm').length,
+      hidden: cachedTiles.filter((tile) => getComputedStyle(tile).display === 'none').length,
+    };
+  }, firstSocketUrl);
+  check('switching sessions reuses the original terminal and socket',
+    secondOpened && retained.matching === 1 && !retained.closed
+      && retained.terminals === 2 && retained.hidden === 1,
+    JSON.stringify({ secondOpened, retained }));
+  const hiddenMessagesBeforeZoom = await page.evaluate((sessionId) => {
+    const socket = window.__terminalSockets.find((item) => item.url.includes(`session=${sessionId}`));
+    return socket?.sent?.length ?? -1;
+  }, secondId);
+  await page.getByTitle('Zoom in').click();
+  await page.getByTitle('Zoom out').click();
+  await sleep(250);
+  const hiddenMessagesAfterZoom = await page.evaluate((sessionId) => {
+    const socket = window.__terminalSockets.find((item) => item.url.includes(`session=${sessionId}`));
+    return socket?.sent?.length ?? -1;
+  }, secondId);
+  check('zooming the active pane does not claim or resize a hidden cached pane',
+    hiddenMessagesBeforeZoom >= 0 && hiddenMessagesAfterZoom === hiddenMessagesBeforeZoom,
+    JSON.stringify({ hiddenMessagesBeforeZoom, hiddenMessagesAfterZoom }));
+
+  // If the initial-claim assertion failed, take control through the existing
+  // explicit zoom path so scrolling and keyboard assertions remain diagnostic.
+  if (!mobileClaimed) {
+    await page.getByTitle('Zoom in').click();
+    await page.getByTitle('Zoom out').click();
+    await waitFor(() => desktopFrames.some((frame) => frame.controller === false));
+  }
+  await sleep(500);
+
+  const portraitGrid = latestGrid();
+  await page.setViewportSize({ width: 667, height: 375 });
+  await page.evaluate(() => window.__setVisualViewport(375, 0, 667));
+  const landscapeResized = await waitFor(() => {
+    const frame = latestGrid();
+    return frame?.cols > portraitGrid.cols && frame?.rows < portraitGrid.rows;
+  });
+  const landscapeFit = await page.evaluate(() => {
+    const host = document.querySelector('.tile-terminal:not(.tile-cached) .term-host').getBoundingClientRect();
+    const screen = document.querySelector('.tile-terminal:not(.tile-cached) .xterm-screen').getBoundingClientRect();
+    return { host: { width: host.width, height: host.height }, screen: { width: screen.width, height: screen.height } };
+  });
+  check('orientation changes refit mobile rows and columns',
+    landscapeResized && landscapeFit.screen.width <= landscapeFit.host.width + 1
+      && landscapeFit.screen.height <= landscapeFit.host.height + 1,
+    JSON.stringify({ landscapeResized, portraitGrid, landscape: latestGrid(), landscapeFit }));
+  await page.setViewportSize({ width: 375, height: 667 });
+  await page.evaluate(() => window.__setVisualViewport(667, 0, 375));
+  await waitFor(() => {
+    const frame = latestGrid();
+    return frame?.cols === portraitGrid.cols && frame?.rows === portraitGrid.rows;
+  });
+
+  await waitFor(() => page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) =>
+    node.scrollHeight > node.clientHeight));
+  const returnedToBottom = await waitFor(() => page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) =>
+    Math.abs(node.scrollTop - (node.scrollHeight - node.clientHeight)) <= 1));
+  check('returning to portrait keeps a live terminal anchored at the bottom', returnedToBottom);
+
+  const beforeScroll = await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => ({
+    top: node.scrollTop, max: node.scrollHeight - node.clientHeight,
+    area: node.querySelector('.xterm-scroll-area')?.getBoundingClientRect().height || 0,
+  }));
+  const messagesBeforeScroll = await page.evaluate(() =>
+    window.__terminalSockets.reduce((count, socket) => count + socket.sent.length, 0));
+  await page.evaluate((sessionId) => {
+    const original = Storage.prototype.setItem;
+    window.__previewWritesDuringGesture = 0;
+    Storage.prototype.setItem = function instrumentPreviewWrite(key, value) {
+      if (key === `am-terminal-preview:${sessionId}`) window.__previewWritesDuringGesture++;
+      return original.call(this, key, value);
+    };
+  }, id);
+  const hostBox = await page.locator('.tile-terminal:not(.tile-cached) .term-host').boundingBox();
+  const x = hostBox.x + hostBox.width / 2;
+  const y = hostBox.y + Math.min(120, hostBox.height / 3);
+  const dragDistance = 96;
+  const dragSteps = 16;
+  await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchstart', {
+    touches: [{ identifier: 1, clientX: x, clientY: y }],
+  });
+  for (let step = 1; step <= dragSteps; step++) {
+    await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchmove', {
+      touches: [{
+        identifier: 1, clientX: x, clientY: y + (dragDistance * step / dragSteps),
+      }],
+    });
+    // Keep the gesture active beyond the preview debounce. A throttle would
+    // write synchronously during this loop; a true debounce must stay silent.
+    await sleep(60);
+  }
+  const writesBeforeTouchEnd = await page.evaluate(() => window.__previewWritesDuringGesture);
+  await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchend', { touches: [] });
+  await sleep(800);
+  const historyTop = await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => node.scrollTop);
+  const writesAfterTouchEnd = await page.evaluate(() => window.__previewWritesDuringGesture);
+  const messagesAfterScroll = await page.evaluate(() =>
+    window.__terminalSockets.reduce((count, socket) => count + socket.sent.length, 0));
+  const scrolledPixels = beforeScroll.top - historyTop;
+  check('small mobile touch moves track the finger through mouse-mode history',
+    beforeScroll.max > 0
+      && scrolledPixels >= dragDistance * 0.8
+      && scrolledPixels <= dragDistance * 1.2,
+    JSON.stringify({ beforeScroll, historyTop, scrolledPixels, dragDistance }));
+  check('terminal preview persistence waits until the touch gesture is idle',
+    writesBeforeTouchEnd === 0 && writesAfterTouchEnd >= 1,
+    JSON.stringify({ writesBeforeTouchEnd, writesAfterTouchEnd }));
+  check('local history scrolling sends no PTY control or resize messages',
+    messagesAfterScroll === messagesBeforeScroll,
+    JSON.stringify({ messagesBeforeScroll, messagesAfterScroll }));
+
+  await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchstart', {
+    touches: [{ identifier: 2, clientX: x, clientY: y + dragDistance }],
+  });
+  for (let step = 1; step <= dragSteps; step++) {
+    await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchmove', {
+      touches: [{
+        identifier: 2, clientX: x,
+        clientY: y + dragDistance - (dragDistance * step / dragSteps),
+      }],
+    });
+  }
+  await page.locator('.tile-terminal:not(.tile-cached) .term-host').dispatchEvent('touchend', { touches: [] });
+  await sleep(100);
+  const returnedScroll = await page.locator('.tile-terminal:not(.tile-cached) .xterm-viewport').evaluate((node) => ({
+    top: node.scrollTop, max: node.scrollHeight - node.clientHeight,
+  }));
+  check('the reverse touch drag returns to the live bottom',
+    Math.abs(returnedScroll.top - returnedScroll.max) < 2,
+    JSON.stringify(returnedScroll));
+
+  const fullKeyboardGrid = latestGrid();
+  await page.locator('.tile-terminal:not(.tile-cached) .term-host').click();
+  const mobileInputAnchor = await page.evaluate(() => {
+    const host = document.querySelector('.tile-terminal:not(.tile-cached) .term-host').getBoundingClientRect();
+    const node = document.querySelector('.tile-terminal:not(.tile-cached) .xterm-helper-textarea');
+    const input = node.getBoundingClientRect();
+    return {
+      ok: input.width >= 1 && input.height >= 1
+        && input.top >= host.bottom - 5 && input.left > host.left && input.right < host.right,
+      host: { top: host.top, right: host.right, bottom: host.bottom, left: host.left },
+      input: { top: input.top, right: input.right, bottom: input.bottom, left: input.left,
+        width: input.width, height: input.height },
+      style: node.getAttribute('style'),
+    };
+  });
+  check('the focused xterm input is anchored at the mobile terminal bottom',
+    mobileInputAnchor.ok, JSON.stringify(mobileInputAnchor));
+
+  // A direct .hf.space app receives real viewport geometry on the affected
+  // devices. Even if a test browser emits no change, focus alone must not
+  // invoke the Hub-iframe fallback outside an iframe.
+  await sleep(650);
+  const directNoSignalLayout = await page.locator('.app').evaluate((node) => ({
+    height: node.getBoundingClientRect().height,
+    strategy: document.documentElement.dataset.keyboardLayout ?? null,
+  }));
+  check('direct app does not guess a keyboard height without a browser signal',
+    Math.abs(directNoSignalLayout.height - 667) < 1 && directNoSignalLayout.strategy === null,
+    JSON.stringify(directNoSignalLayout));
+
+  // Embedded Chromium can leave the child visual viewport unchanged but expose
+  // the OSK rectangle. Ensure that independent signal clips the app and PTY.
+  await page.evaluate(() => window.__setVirtualKeyboard(430, 237));
+  const geometryResized = await waitFor(() => latestGrid()?.rows < fullKeyboardGrid.rows);
+  const geometryLayout = await page.locator('.app').evaluate((node) => {
+    const box = node.getBoundingClientRect();
+    const keybar = document.querySelector('.tile-terminal:not(.tile-cached) .term-keybar')?.getBoundingClientRect();
+    return { top: box.top, bottom: box.bottom, height: box.height, keybarBottom: keybar?.bottom ?? null };
+  });
+  check('keyboard geometry resizes an embedded mobile terminal without viewport changes',
+    geometryResized && Math.abs(geometryLayout.height - 430) < 1
+      && geometryLayout.keybarBottom <= 430,
+    JSON.stringify({ geometryResized, geometryLayout, grid: latestGrid() }));
+  await page.evaluate(() => window.__setVirtualKeyboard(667, 0));
+  const geometryClosed = await waitFor(() => latestGrid()?.rows >= fullKeyboardGrid.rows);
+  check('clearing embedded keyboard geometry restores the terminal', geometryClosed,
+    JSON.stringify(latestGrid()));
+
+  const beforeKeyboardGrid = latestGrid();
+  await page.evaluate(() => window.__setVisualViewportLate(360, 118));
+  const keyboardResized = await waitFor(() => {
+    const frame = latestGrid();
+    return frame?.controller === false && frame?.rows < beforeKeyboardGrid.rows;
+  });
+  const keyboardLayout = await page.evaluate(() => {
+    const rect = (selector) => {
+      const node = document.querySelector(selector);
+      if (!node) return null;
+      const box = node.getBoundingClientRect();
+      return {
+        top: box.top, right: box.right, bottom: box.bottom, left: box.left,
+        width: box.width, height: box.height,
+      };
+    };
+    const app = rect('.app');
+    const host = rect('.tile-terminal:not(.tile-cached) .term-host');
+    const keybar = rect('.tile-terminal:not(.tile-cached) .term-keybar');
+    return {
+      app,
+      hostBottom: host?.bottom ?? null,
+      keybarBottom: keybar?.bottom ?? null,
+      vvh: getComputedStyle(document.documentElement).getPropertyValue('--vvh').trim(),
+      vvtop: getComputedStyle(document.documentElement).getPropertyValue('--vv-top').trim(),
+      pageScroll: window.scrollY,
+    };
+  });
+  check('the app follows the keyboard-shrunken visual viewport',
+    Math.abs(keyboardLayout.app.top - 118) < 1
+      && Math.abs(keyboardLayout.app.height - 360) < 1
+      && Math.abs(keyboardLayout.app.bottom - 478) < 1
+      && Math.abs(keyboardLayout.app.left) < 1
+      && Math.abs(keyboardLayout.app.width - 375) < 1,
+    JSON.stringify(keyboardLayout));
+  check('terminal input controls remain above the keyboard',
+    keyboardResized && keyboardLayout.hostBottom <= 478 && keyboardLayout.keybarBottom <= 478,
+    JSON.stringify({ keyboardResized, beforeKeyboardGrid, after: latestGrid(), keyboardLayout }));
+
+  await page.evaluate(() => window.__setVisualViewport(667, 0));
+  const keyboardClosed = await waitFor(() => latestGrid()?.rows >= beforeKeyboardGrid.rows);
+  const restoredLayout = await page.locator('.app').evaluate((node) => {
+    const rect = node.getBoundingClientRect();
+    return { top: rect.top, height: rect.height };
+  });
+  check('closing the keyboard restores viewport and terminal geometry',
+    keyboardClosed && Math.abs(restoredLayout.top) < 1 && Math.abs(restoredLayout.height - 667) < 1,
+    JSON.stringify({ keyboardClosed, restoredLayout, grid: latestGrid() }));
+
+  // The huggingface.co Space page is a cross-origin wrapper around the actual
+  // app iframe. Mobile Safari does not propagate its keyboard viewport into
+  // that child, so verify the focus-derived fallback with every geometry signal
+  // deliberately left unchanged.
+  const embeddedPage = await context.newPage();
+  await embeddedPage.setContent(
+    `<style>html,body{margin:0}iframe{display:block;width:375px;height:667px;border:0}</style>`
+      + `<iframe src="${WEB}"></iframe>`,
+  );
+  const embeddedReady = await waitFor(() => embeddedPage.frames().some((frame) =>
+    frame !== embeddedPage.mainFrame() && frame.url().startsWith(WEB)));
+  const embeddedFrame = embeddedPage.frames().find((frame) =>
+    frame !== embeddedPage.mainFrame() && frame.url().startsWith(WEB));
+  if (!embeddedReady || !embeddedFrame) throw new Error('embedded app frame did not load');
+  await embeddedFrame.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
+  await embeddedFrame.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
+  await embeddedFrame.locator('.tile-terminal:not(.tile-cached) .term-host').click();
+  const embeddedFallback = await waitFor(() => embeddedFrame.evaluate(() =>
+    document.documentElement.dataset.keyboardLayout === 'focus-fallback'));
+  const embeddedLayout = await embeddedFrame.locator('.app').evaluate((node) => {
+    const app = node.getBoundingClientRect();
+    const keybar = document.querySelector('.tile-terminal:not(.tile-cached) .term-keybar')
+      ?.getBoundingClientRect();
+    return {
+      height: app.height,
+      bottom: app.bottom,
+      keybarBottom: keybar?.bottom ?? null,
+      strategy: document.documentElement.dataset.keyboardLayout ?? null,
+      visualViewportHeight: window.visualViewport?.height ?? null,
+      innerHeight: window.innerHeight,
+    };
+  });
+  check('Hub iframe uses a focus fallback when keyboard geometry is unavailable',
+    embeddedFallback
+      && Math.abs(embeddedLayout.height - 360) < 1
+      && embeddedLayout.keybarBottom <= embeddedLayout.bottom
+      && embeddedLayout.visualViewportHeight === 667
+      && embeddedLayout.innerHeight === 667,
+    JSON.stringify(embeddedLayout));
+  await embeddedFrame.locator('.xterm-helper-textarea').evaluate((node) => node.blur());
+  const embeddedRestored = await waitFor(() => embeddedFrame.evaluate(() => {
+    const app = document.querySelector('.app')?.getBoundingClientRect();
+    return !document.documentElement.dataset.keyboardLayout && Math.abs((app?.height ?? 0) - 667) < 1;
+  }));
+  check('blurring an embedded prompt restores the full iframe height', embeddedRestored);
+  await embeddedPage.close();
+
+  // A compact last-frame preview should survive a full page reload and remain
+  // available while the backend/Space is unavailable. This deliberately blocks
+  // terminal sockets after reload, so success cannot come from a fast restore.
+  const previewSaved = await waitFor(() => page.evaluate((sessionId) => {
+    try {
+      const saved = JSON.parse(localStorage.getItem(`am-terminal-preview:${sessionId}`) || 'null');
+      return saved?.rows?.some((line) => String(line).includes('MOBILE-HISTORY-0220'));
+    } catch { return false; }
+  }, id), 5_000);
+  await page.evaluate(() => localStorage.setItem('__am_test_offline_sockets', '1'));
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await page.locator('.sidebar .row').filter({ hasText: 'mobile-terminal-e2e' }).first().click();
+  const previewVisible = await page.locator('.term-preview').filter({ hasText: 'MOBILE-HISTORY-0220' })
+    .isVisible().catch(() => false);
+  check('the last terminal view survives reload while the backend is unavailable',
+    previewSaved && previewVisible, JSON.stringify({ previewSaved, previewVisible }));
+
+  await context.close();
+
+  // The pane deck is shared by desktop group layouts too. Put the two existing
+  // sessions in one group and verify explicit grid placement plus persistence
+  // across Overview and Settings (both used to tear terminal panes down).
+  const group = await (await fetch(`${API}/api/groups`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'cache-layout-group' }),
+  })).json();
+  for (const sessionId of [id, secondId]) {
+    await fetch(`${API}/api/move`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ ref: `s:${sessionId}`, to: { kind: 'into', groupId: group.id } }),
+    });
+  }
+  const desktopContext = await browser.newContext({ viewport: { width: 1200, height: 800 } });
+  const desktopPage = await desktopContext.newPage();
+  await desktopPage.goto(WEB, { waitUntil: 'domcontentloaded' });
+  await desktopPage.locator('.row.group-head').filter({ hasText: 'cache-layout-group' }).click();
+  const groupTerms = desktopPage.locator('.tile-terminal:not(.tile-cached) .xterm');
+  await groupTerms.first().waitFor({ state: 'visible' });
+  const groupReady = await waitFor(() => groupTerms.count().then((count) => count === 2));
+  const groupLayout = await desktopPage.locator('.tile-terminal:not(.tile-cached)').evaluateAll((tiles) =>
+    tiles.map((tile) => {
+      const box = tile.getBoundingClientRect();
+      tile.setAttribute('data-cache-probe', 'retained');
+      return { left: box.left, top: box.top, width: box.width, height: box.height };
+    }));
+  check('retained terminals occupy the desktop group grid', groupReady
+    && groupLayout.length === 2 && Math.abs(groupLayout[0].top - groupLayout[1].top) < 1
+    && groupLayout[1].left > groupLayout[0].left + groupLayout[0].width,
+  JSON.stringify(groupLayout));
+
+  await desktopPage.locator('.ov-row').click();
+  const overviewRetained = await desktopPage.locator('.tile-terminal[data-cache-probe="retained"]')
+    .count() === 2;
+  await desktopPage.locator('.row.group-head').filter({ hasText: 'cache-layout-group' }).click();
+  const groupRestored = await waitFor(() => desktopPage
+    .locator('.tile-terminal:not(.tile-cached)[data-cache-probe="retained"]')
+    .count().then((count) => count === 2));
+  check('Overview hides group terminals without recreating them', overviewRetained && groupRestored,
+    JSON.stringify({ overviewRetained, groupRestored }));
+
+  await desktopPage.getByTitle('Settings').click();
+  await desktopPage.locator('.app.settings').waitFor({ state: 'visible' });
+  const settingsRetained = await desktopPage
+    .locator('.app.app-suspended .tile-terminal[data-cache-probe="retained"] .xterm').count() === 2;
+  await desktopPage.locator('.app.settings').getByTitle('Back').click();
+  const settingsRestored = await waitFor(() => desktopPage
+    .locator('.tile-terminal:not(.tile-cached)[data-cache-probe="retained"] .xterm')
+    .count().then((count) => count === 2));
+  check('Settings hides group terminals without recreating them', settingsRetained && settingsRestored,
+    JSON.stringify({ settingsRetained, settingsRestored }));
+  await desktopContext.close();
+} catch (error) {
+  check('mobile browser test completes', false, String(error?.stack || error));
+  console.log(logs.slice(-3000));
+} finally {
+  try { desktop?.close(); } catch {}
+  try { await browser?.close(); } catch {}
+  if (id) await fetch(`${API}/api/sessions/${id}/stop`, { method: 'POST' }).catch(() => {});
+  if (secondId) await fetch(`${API}/api/sessions/${secondId}/stop`, { method: 'POST' }).catch(() => {});
+  backend.kill('SIGTERM');
+  await sleep(400);
+  backend.kill('SIGKILL');
+  try { fs.rmSync(DATA_DIR, { recursive: true, force: true }); } catch {}
+}
+
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

server/package-lock.json

@@ -7,13 +7,55 @@
     "": {
       "name": "agent-manager-server",
       "version": "0.1.0",
+      "license": "Apache-2.0",
       "dependencies": {
+        "@coder/libghostty-vt-node": "0.1.0-beta.0",
         "express": "^4.19.2",
         "node-pty": "^1.0.0",
         "web-push": "^3.6.7",
         "ws": "^8.18.0"
+      },
+      "devDependencies": {
+        "@xterm/headless": "^6.0.0",
+        "playwright": "^1.62.1"
+      },
+      "engines": {
+        "node": ">=20.19"
+      }
+    },
+    "node_modules/@coder/libghostty-vt-node": {
+      "version": "0.1.0-beta.0",
+      "resolved": "https://registry.npmjs.org/@coder/libghostty-vt-node/-/libghostty-vt-node-0.1.0-beta.0.tgz",
+      "integrity": "sha512-m0KqgBfEzD7G6DIFWe3OSGoa0muDHneXDKHDVz8sJdSYl2N8HN9W642H3LSw2YDkw9VuxxkbHqXdN98akkqwxQ==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^8.3.1",
+        "node-gyp-build": "^4.8.4"
+      },
+      "engines": {
+        "node": ">=20.19"
       }
     },
+    "node_modules/@coder/libghostty-vt-node/node_modules/node-addon-api": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.9.0.tgz",
+      "integrity": "sha512-ekZMeaaIzSQTSpr7X2X3iJM7lTzgnx8ahAG9pJfT/7+14mlEM8ZYQ9cgCDvSSRbReFK0oHli3WrZdCiRsgAT9Q==",
+      "license": "MIT",
+      "engines": {
+        "node": "^18 || ^20 || >= 21"
+      }
+    },
+    "node_modules/@xterm/headless": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@xterm/headless/-/headless-6.0.0.tgz",
+      "integrity": "sha512-5Yj1QINYCyzrZtf8OFIHi47iQtI+0qYFPHmouEfG8dHNxbZ9Tb9YGSuLcsEwj9Z+OL75GJqPyJbyoFer80a2Hw==",
+      "dev": true,
+      "license": "MIT",
+      "workspaces": [
+        "addons/*"
+      ]
+    },
     "node_modules/accepts": {
       "version": "1.3.8",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
@@ -357,6 +399,21 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/function-bind": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
@@ -657,6 +714,17 @@
       "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
       "license": "MIT"
     },
+    "node_modules/node-gyp-build": {
+      "version": "4.8.4",
+      "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.8.4.tgz",
+      "integrity": "sha512-LA4ZjwlnUblHVgq0oBF3Jl/6h/Nvs5fzBLwdEF4nuxnFdsfajde4WfxtJr3CaiH+F6ewcIB/q4jQ4UzPyid+CQ==",
+      "license": "MIT",
+      "bin": {
+        "node-gyp-build": "bin.js",
+        "node-gyp-build-optional": "optional.js",
+        "node-gyp-build-test": "build-test.js"
+      }
+    },
     "node_modules/node-pty": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz",
@@ -706,6 +774,38 @@
       "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==",
       "license": "MIT"
     },
+    "node_modules/playwright": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
+      "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.62.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
+      "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",

server/package.json

@@ -2,20 +2,31 @@
   "name": "agent-manager-server",
   "version": "0.1.0",
   "private": true,
-  "description": "Agent Manager backend (Express + ws + node-pty + tmux)",
+  "description": "Agent Manager backend (Express + ws + node-pty + libghostty-vt)",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "https://github.com/huggingface/agent-manager" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/huggingface/agent-manager"
+  },
   "type": "module",
   "main": "src/index.js",
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
-    "test": "node test/repin.test.mjs"
+    "test": "node test/repin.test.mjs && node migration.test.mjs && node resize.test.mjs"
+  },
+  "engines": {
+    "node": ">=20.19"
   },
   "dependencies": {
+    "@coder/libghostty-vt-node": "0.1.0-beta.0",
     "express": "^4.19.2",
     "node-pty": "^1.0.0",
     "web-push": "^3.6.7",
     "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@xterm/headless": "^6.0.0",
+    "playwright": "^1.62.1"
   }
 }

server/resize.test.mjs

@@ -0,0 +1,623 @@
+// Invariants for the server-held terminal model.
+//
+// The contract is explicit rather than heuristic: shell output uses ordinary
+// reflow, while known primary-screen agent TUIs settle their SIGWINCH repaint in
+// a scratch terminal so presentation bytes never become history. Exactly one
+// viewer controls input and PTY geometry; Ghostty remains the durable authority.
+//   node resize.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WebSocket } from 'ws';
+import {
+  TERMINAL_HISTORY_VERSION, createTerminalHistoryCheckpoint, loadTerminalHistory,
+  traceHistoryLines,
+} from './src/history-store.js';
+import { mergeRepaintArchive, repaintArchiveView } from './src/runner.js';
+import { snapshotToRestoreAnsi, styledTerminalRows } from './src/snapshot.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-resize-'));
+const FIXTURE = path.join(HERE, 'fixtures', 'repaint-tui.mjs');
+const PORT = 7895;
+const CTRL = '\x00\x00AM:';
+const base = `http://localhost:${PORT}`;
+
+let failures = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? `  ${detail}` : ''}`);
+  if (!ok) failures++;
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const waitFor = async (fn, timeout = 8000) => {
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    if (await fn()) return true;
+    await sleep(100);
+  }
+  return false;
+};
+
+const srv = spawn('node', ['src/index.js'], {
+  cwd: HERE,
+  env: {
+    ...process.env,
+    PORT: String(PORT),
+    DATA_DIR,
+    AM_BASHRC: '/nonexistent',
+    AM_HISTORY_SAVE_MS: '50',
+    AM_STARTUP_CAPTURE_IDLE_MS: '700',
+    AM_STARTUP_CAPTURE_MAX_MS: '3000',
+    AM_TEST_REPAINT_CMD: `env FIXED_LINES=30 HISTORY_LINES=2105 DELAY_RESUME_MS=400 ${JSON.stringify(process.execPath)} ${JSON.stringify(FIXTURE)}`,
+  },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+let log = '';
+srv.stdout.on('data', (data) => { log += data; });
+srv.stderr.on('data', (data) => { log += data; });
+
+let Headless = null;
+try { Headless = (await import('@xterm/headless')).default.Terminal; } catch {}
+
+function view(id, cols, rows, mirror = false) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://localhost:${PORT}/ws?session=${id}&cols=${cols}&rows=${rows}`);
+    const term = mirror && Headless
+      ? new Headless({ cols, rows, scrollback: 20000, allowProposedApi: true })
+      : null;
+    const v = {
+      bytes: '', frames: [], events: [], term,
+      type: (data) => ws.send(JSON.stringify({ t: 'i', d: data })),
+      resize: (nextCols, nextRows) => ws.send(JSON.stringify({ t: 'r', cols: nextCols, rows: nextRows })),
+      claim: () => ws.send(JSON.stringify({ t: 'claim' })),
+      lastFrame: (type) => [...v.frames].reverse().find((frame) => frame.t === type) || null,
+      countFrames: (type) => v.frames.filter((frame) => frame.t === type).length,
+      open: () => ws.readyState === WebSocket.OPEN,
+      close: () => { try { ws.close(); } catch {} },
+      screenText: async () => {
+        if (!term) return '';
+        await new Promise((done) => term.write('', done));
+        const buf = term.buffer.active;
+        let text = '';
+        for (let i = 0; i < buf.length; i++) {
+          const line = buf.getLine(i);
+          const row = line?.translateToString(true) ?? '';
+          // Snapshot restores use absolute cursor painting, which cannot carry
+          // xterm's private isWrapped bit. A full row is nevertheless a visual
+          // wrap and must be joined before checking transcript completeness.
+          if (i > 0 && !line?.isWrapped) {
+            const previous = buf.getLine(i - 1)?.translateToString(true) ?? '';
+            if (previous.length < term.cols) text += '\n';
+          }
+          text += row;
+        }
+        return text;
+      },
+      scrollsBack: async () => {
+        if (!term) return false;
+        await new Promise((done) => term.write('', done));
+        const buf = term.buffer.active;
+        const bottom = buf.baseY;
+        term.scrollToTop();
+        const top = buf.viewportY;
+        term.scrollToBottom();
+        return bottom > 0 && top < bottom && buf.viewportY === bottom;
+      },
+      bufferState: async () => {
+        if (!term) return null;
+        await new Promise((done) => term.write('', done));
+        const buf = term.buffer.active;
+        const initialViewport = buf.viewportY;
+        let coloredHistoryCells = 0;
+        for (let y = 0; y < buf.baseY; y++) {
+          const line = buf.getLine(y);
+          if (!line) continue;
+          for (let x = 0; x < line.length; x++) {
+            const cell = line.getCell(x);
+            if (cell?.getChars() && (!cell.isFgDefault() || !cell.isBgDefault())) {
+              coloredHistoryCells++;
+            }
+          }
+        }
+        term.scrollToTop();
+        const top = buf.viewportY;
+        term.scrollToBottom();
+        return {
+          historyRows: buf.baseY,
+          initialViewport,
+          atBottom: initialViewport === buf.baseY,
+          canReachBothEnds: buf.baseY > 0 && top === 0 && buf.viewportY === buf.baseY,
+          coloredHistoryCells,
+        };
+      },
+    };
+    ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      if (text.startsWith(CTRL)) {
+        let frame;
+        try { frame = JSON.parse(text.slice(CTRL.length)); } catch { return; }
+        v.frames.push(frame);
+        v.events.push({ type: 'frame', frame });
+        if (term && (frame.t === 'grid' || frame.t === 'restore')) {
+          const applyGrid = () => {
+            if (frame.reset) { term.reset(); term.clear(); }
+            if (frame.cols > 0 && frame.rows > 0
+                && (term.cols !== frame.cols || term.rows !== frame.rows)) {
+              term.resize(frame.cols, frame.rows);
+            }
+          };
+          const geometryChanged = frame.cols > 0 && frame.rows > 0
+            && (term.cols !== frame.cols || term.rows !== frame.rows);
+          if (frame.reset || geometryChanged) term.write('', applyGrid);
+          else applyGrid();
+        }
+      } else {
+        v.bytes += text;
+        v.events.push({ type: 'data', text });
+        if (term) term.write(text);
+      }
+    });
+    ws.on('open', () => resolve(v));
+    ws.on('error', () => resolve(v));
+  });
+}
+
+async function session(name, cli = 'shell') {
+  const created = await (await fetch(`${base}/api/sessions`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli, name }),
+  })).json();
+  if (!created.id) throw new Error(`no session: ${JSON.stringify(created).slice(0, 200)}`);
+  return created.id;
+}
+
+const gridText = async (id, lines = 2000) => {
+  const response = await fetch(`${base}/api/agents/${id}/tail?lines=${lines}`);
+  const body = await response.json();
+  return typeof body === 'string' ? body : (body.text || body.tail || '');
+};
+
+/** Every fixture token is unique, so repeats prove a frame entered history twice. */
+function duplicateTokens(text) {
+  const counts = new Map();
+  for (const match of text.matchAll(/\b\d{3}\.\d{2}\b/g)) {
+    counts.set(match[0], (counts.get(match[0]) || 0) + 1);
+  }
+  return [...counts.values()].filter((count) => count > 1).length;
+}
+
+const uniqueTokens = (text) => new Set(text.match(/\b\d{3}\.\d{2}\b/g) || []).size;
+
+const stop = async (id) => {
+  await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' }).catch(() => {});
+  await sleep(250);
+};
+
+try {
+  {
+    const directory = fs.mkdtempSync(path.join(DATA_DIR, 'history-schema-'));
+    const legacyFile = path.join(directory, 'legacy.json');
+    fs.writeFileSync(legacyFile, JSON.stringify({ version: 1, cols: 80, lines: ['old'] }));
+    check('legacy checkpoints remain readable for unaffected shell sessions',
+      loadTerminalHistory(directory, 'legacy')?.version === 1);
+
+    const checkpoint = createTerminalHistoryCheckpoint({
+      directory, id: 'current', delayMs: 1,
+      snapshot: () => ({
+        cols: 90, scrollbackLines: [{ text: 'clean', ansi: '\x1b[38;5;2mclean\x1b[0m' }],
+      }),
+      blocked: () => false,
+    });
+    checkpoint.flush();
+    const wrote = await waitFor(() => loadTerminalHistory(directory, 'current')?.version
+      === TERMINAL_HISTORY_VERSION);
+    check('new checkpoints use the clean startup generation', wrote);
+    check('checkpoints retain validated scrollback styling',
+      loadTerminalHistory(directory, 'current')?.lines[0]?.ansi
+      === '\x1b[38;5;2mclean\x1b[0m');
+
+    const styled = styledTerminalRows({
+      cols: 20, rows: 1,
+      scrollbackLines: [{ row: 0, text: 'red history' }],
+      visibleLines: [{ row: 0, text: 'live' }],
+    }, '<div style="font-family: monospace; white-space: pre;"><div style="display: inline;color: var(--vt-palette-1);">red history</div>\nlive</div>');
+    const restore = snapshotToRestoreAnsi({
+      cols: 20, rows: 1, cursorRow: 0, cursorCol: 0, cells: [],
+      scrollbackLines: styled.slice(0, 1),
+    });
+    check('Ghostty HTML scrollback colors convert back to ANSI',
+      styled[0].ansi?.includes('\x1b[38;5;1m')
+      && restore.includes('\x1b[38;5;1mred history'));
+  }
+
+  {
+    const recovered = traceHistoryLines({ turns: [
+      { role: 'user', blocks: [{ type: 'text', text: 'older prompt' }] },
+      { role: 'assistant', kind: 'final', blocks: [{ type: 'text', text: 'older answer' }] },
+      { role: 'user', blocks: [{ type: 'text', text: 'live prompt' }] },
+      { role: 'assistant', kind: 'final', blocks: [{ type: 'text', text: 'live answer' }] },
+    ] });
+    const text = recovered.map((line) => line.text).join('\n');
+    check('trace recovery seeds only turns older than the live viewport',
+      text.includes('older prompt') && text.includes('older answer')
+      && !text.includes('live prompt') && !text.includes('live answer'));
+
+    const alreadyVisible = traceHistoryLines({ turns: [
+      { role: 'user', blocks: [{ type: 'text', text: 'hi there' }] },
+      { role: 'assistant', kind: 'final', blocks: [{ type: 'text', text: 'Hey!' }] },
+      { role: 'user', blocks: [{ type: 'text', text: 'live prompt' }] },
+    ] }, '❯ hi there\n\n● Hey!');
+    check('trace recovery does not duplicate short turns replayed by the agent',
+      alreadyVisible.length === 0);
+
+    const archiveSeed = 'older unique turn\n❯ hi there\n\n● Hey!\n';
+    const wide = 'Claude welcome frame\nolder unique turn\n❯ hi there\n\n● Hey!\nnewer live turn\n';
+    const archive = mergeRepaintArchive(archiveSeed, wide);
+    check('a wide repaint merges recovered turns into one full archive',
+      archive === wide && archive.split('❯ hi there').length - 1 === 1);
+    check('a wide repaint needs no duplicate scrollback',
+      repaintArchiveView(archive, wide).history.length === 0);
+    const narrow = 'newer live turn\n';
+    const narrowView = repaintArchiveView(archive, narrow);
+    const narrowHistory = narrowView.history.map((line) => line.text).join('\n');
+    check('a narrow repaint restores the archive prefix above the viewport',
+      narrowHistory.includes('Claude welcome frame') && narrowHistory.includes('❯ hi there'));
+    check('a repaint replaces a volatile old footer after its transcript overlap',
+      repaintArchiveView('deep history\nshared transcript\n[old 160x40]\n',
+        'shared transcript\n[new 90x24]\n').archive
+      === 'deep history\nshared transcript\n[new 90x24]\n');
+    const poem = '❯ write me a poem about silicon\n\n● Silicon\n\n'
+      + 'Second most common thing underfoot, plain as the beach you forget while you walk it —\n'
+      + 'Someone thought to melt it, draw it out into a single perfect column, one lattice unbroken.\n';
+    const volatilePrefix = repaintArchiveView(
+      `older unique turn\n${poem}✻ Worked for 8s\n[old footer]\n`,
+      `✻ Worked for 2s\n${poem}✻ Worked for 8s\n[new footer]\n`,
+    ).archive;
+    check('a volatile leading status cannot anchor after and duplicate the repainted turn',
+      volatilePrefix.split('❯ write me a poem about silicon').length - 1 === 1
+      && volatilePrefix.includes('[new footer]') && !volatilePrefix.includes('[old footer]'));
+    check('zooming wide again exposes the archive without growing it',
+      repaintArchiveView(narrowView.archive, wide).archive === wide);
+  }
+
+  const up = await waitFor(async () => {
+    try { return (await fetch(`${base}/api/health`)).ok; } catch { return false; }
+  }, 100_000);
+  if (!up) throw new Error(`server never came up:\n${log.slice(-1200)}`);
+
+  // A long logical line must survive ordinary Ghostty reflow. The former
+  // screen-carry path cropped the right side before rebuilding a narrower grid.
+  {
+    const id = await session('long line reflow');
+    const v = await view(id, 110, 24, true);
+    await sleep(700);
+    v.type(`printf 'LONG-%s-END-SENTINEL\\n' "$(printf 'x%.0s' {1..90})"\r`);
+    const printed = await waitFor(async () => (await gridText(id)).includes('END-SENTINEL'));
+    check('long line is present before resize', printed);
+    v.resize(60, 24);
+    const resized = await waitFor(() => v.lastFrame('grid')?.cols === 60);
+    check('resize settles at the requested geometry', resized, JSON.stringify(v.lastFrame('grid')));
+    const after = await gridText(id);
+    check('narrowing does not crop the right side of a logical line', after.includes('END-SENTINEL'));
+    check('resize does not retransmit all history', v.lastFrame('grid')?.reset === false);
+    if (Headless) check('the ordered viewer reflow also retains the line', (await v.screenText()).includes('END-SENTINEL'));
+    v.close();
+    await stop(id);
+  }
+
+  // The geometry frame must precede output triggered by SIGWINCH. Otherwise a
+  // TUI's repaint is interpreted at the old size and only reflowed afterward,
+  // which can leave duplicate or displaced rows in a browser emulator.
+  {
+    const id = await session('ordered repaint');
+    const v = await view(id, 100, 30, true);
+    await sleep(500);
+    v.type(`trap 'printf "\\033[2J\\033[HRESIZE-AT-%sx%s\\n" "$COLUMNS" "$LINES"' WINCH; printf 'TRAP-READY\\n'\r`);
+    await waitFor(() => v.bytes.includes('TRAP-READY'));
+    v.events.length = 0;
+    v.resize(73, 21);
+    const repainted = await waitFor(() => v.events.some((event) => event.type === 'data'
+      && event.text.includes('RESIZE-AT-73x21')));
+    const gridAt = v.events.findIndex((event) => event.type === 'frame'
+      && event.frame.t === 'grid' && event.frame.cols === 73 && event.frame.rows === 21);
+    const repaintAt = v.events.findIndex((event) => event.type === 'data'
+      && event.text.includes('RESIZE-AT-73x21'));
+    check('SIGWINCH repaint arrives after the confirmed grid', repainted && gridAt >= 0 && gridAt < repaintAt,
+      `grid event ${gridAt}, repaint event ${repaintAt}`);
+    if (Headless) {
+      const screen = await v.screenText();
+      check('ordered repaint is rendered once', screen.split('RESIZE-AT-73x21').length - 1 === 1);
+    }
+    v.close();
+    await stop(id);
+  }
+
+  // Claude-style primary-screen TUIs print a complete frame on every SIGWINCH.
+  // Some frames are taller than the pane; streaming those repaint bytes would
+  // archive another welcome/conversation copy on every zoom step. Agent resizes
+  // therefore settle in a scratch terminal and commit only the final screen.
+  {
+    const id = await session('captured agent repaint', 'test-repaint');
+    const v = await view(id, 150, 40, true);
+    const painted = await waitFor(async () => (await gridText(id)).includes('[fixture 150x40]'));
+    check('Claude-style fixture paints its initial frame', painted);
+    const beforeGrid = duplicateTokens(await gridText(id));
+    const initialGridText = await gridText(id);
+    const initialBrowserText = Headless ? await v.screenText() : '';
+    const beforeBrowser = Headless ? duplicateTokens(initialBrowserText) : 0;
+    const initialGridTokens = uniqueTokens(initialGridText);
+    const initialBrowserTokens = Headless ? uniqueTokens(initialBrowserText) : 0;
+    check('fixture starts without duplicate history', beforeGrid === 0 && beforeBrowser === 0,
+      `grid=${beforeGrid}, browser=${beforeBrowser}`);
+    if (Headless) {
+      check('fixture starts with deep history', initialBrowserText.includes('history-0001'));
+      check('browser viewport can scroll through that history', await v.scrollsBack());
+      const state = await v.bufferState();
+      check('fixture starts at the live bottom', state?.atBottom, JSON.stringify(state));
+      check('fixture starts with styled history', state?.coloredHistoryCells > 0,
+        JSON.stringify(state));
+    }
+
+    for (const [cols, rows] of [[120, 32], [90, 24], [120, 32], [150, 40]]) {
+      v.resize(cols, rows);
+      const settled = await waitFor(() => v.lastFrame('grid')?.cols === cols
+        && v.lastFrame('grid')?.rows === rows);
+      check(`agent repaint settles at ${cols}x${rows}`, settled, JSON.stringify(v.lastFrame('grid')));
+      await sleep(150);
+      const stepGridText = await gridText(id);
+      check(`canonical history stays unique at ${cols}x${rows}`, duplicateTokens(stepGridText) === beforeGrid,
+        `${duplicateTokens(stepGridText)} duplicate tokens`);
+      if (Headless) {
+        const stepBrowserText = await v.screenText();
+        check(`browser history stays unique at ${cols}x${rows}`, duplicateTokens(stepBrowserText) === beforeBrowser,
+          `${duplicateTokens(stepBrowserText)} duplicate tokens`);
+        check(`browser history stays complete at ${cols}x${rows}`,
+          uniqueTokens(stepBrowserText) === initialBrowserTokens,
+          `${initialBrowserTokens} before, ${uniqueTokens(stepBrowserText)} after`);
+        check(`browser deep history survives at ${cols}x${rows}`,
+          stepBrowserText.includes('history-0001'));
+        const state = await v.bufferState();
+        check(`browser reaches both history ends at ${cols}x${rows}`,
+          state?.canReachBothEnds, JSON.stringify(state));
+        check(`browser remains at the live bottom at ${cols}x${rows}`,
+          state?.atBottom, JSON.stringify(state));
+        check(`styled history survives at ${cols}x${rows}`,
+          state?.coloredHistoryCells > 0, JSON.stringify(state));
+      }
+    }
+
+    const finalGridText = await gridText(id);
+    const afterGrid = duplicateTokens(finalGridText);
+    check('zoom round-trip adds no duplicate frame to canonical history', afterGrid === beforeGrid,
+      `${beforeGrid} before, ${afterGrid} after`);
+    check('zoom round-trip retains canonical history', uniqueTokens(finalGridText) === initialGridTokens,
+      `${initialGridTokens} before, ${uniqueTokens(finalGridText)} after`);
+    if (Headless) {
+      const finalBrowserText = await v.screenText();
+      const afterBrowser = duplicateTokens(finalBrowserText);
+      check('zoom round-trip adds no duplicate frame to browser history', afterBrowser === beforeBrowser,
+        `${beforeBrowser} before, ${afterBrowser} after`);
+      check('zoom round-trip retains browser history', uniqueTokens(finalBrowserText) === initialBrowserTokens,
+        `${initialBrowserTokens} before, ${uniqueTokens(finalBrowserText)} after`);
+    }
+    v.close();
+    await sleep(250);
+    const reattached = await view(id, 150, 40, true);
+    const restored = await waitFor(() => reattached.lastFrame('restore')?.cols === 150);
+    const restoredText = Headless ? await reattached.screenText() : '';
+    check('reattach remains free of resize-generated frames', restored
+      && (!Headless || duplicateTokens(restoredText) === beforeGrid),
+    Headless ? `${duplicateTokens(restoredText)} duplicate tokens` : '');
+    check('reattach retains complete and deep history', restored
+      && (!Headless || (uniqueTokens(restoredText) === initialBrowserTokens
+        && restoredText.includes('history-0001'))));
+    if (Headless) {
+      const state = await reattached.bufferState();
+      check('reattach reaches both history ends and starts at bottom',
+        state?.canReachBothEnds && state?.atBottom, JSON.stringify(state));
+      check('reattach retains styled history', state?.coloredHistoryCells > 0,
+        JSON.stringify(state));
+    }
+    reattached.close();
+    await stop(id);
+
+    // Stopping the PTY models a backend restart: a new host must load its
+    // durable checkpoint before the resumed TUI paints, without duplicating
+    // either the old frame or its welcome banner.
+    const checkpoint = path.join(DATA_DIR, 'state', 'terminal-history', `${id}.json`);
+    check('terminal history is checkpointed durably', await waitFor(() => fs.existsSync(checkpoint)));
+    // A mobile pane opens its socket with xterm's provisional 80x24 geometry,
+    // then reports the measured phone grid as soon as layout settles. Exercise
+    // that change while the resumed TUI is still repainting, not only after the
+    // startup transaction has committed.
+    const restarted = await view(id, 80, 24, true);
+    restarted.resize(40, 28);
+    const resumed = await waitFor(async () => (await gridText(id)).includes('[fixture 40x28]'));
+    const startupCommitted = await waitFor(() => restarted.frames.some((frame) =>
+      frame.t === 'grid' && frame.reset));
+    await sleep(350);
+    const restartedText = Headless ? await restarted.screenText() : '';
+    const restartDuplicates = Headless ? duplicateTokens(restartedText) : 0;
+    check('host restart restores deep scrollback', resumed
+      && (!Headless || restartedText.includes('history-0001')));
+    check('delayed startup repaint commits as one transaction', startupCommitted);
+    check('host restart does not duplicate delayed repaint content', !Headless
+      || restartDuplicates === beforeBrowser,
+    Headless ? `${restartDuplicates} duplicate tokens` : '');
+    if (Headless) {
+      check('host restart retains exact transcript cardinality',
+        uniqueTokens(restartedText) === initialBrowserTokens,
+        `${initialBrowserTokens} before, ${uniqueTokens(restartedText)} after`);
+      const state = await restarted.bufferState();
+      check('restored viewport reaches both ends and starts at bottom',
+        state?.canReachBothEnds && state?.atBottom, JSON.stringify(state));
+      check('host restart retains styled history', state?.coloredHistoryCells > 0,
+        JSON.stringify(state));
+    }
+
+    // Exercise the actual failure combination: after a delayed restart, a
+    // second viewer takes the geometry lease, zooms narrow, then zooms wide.
+    // Every transition must preserve the same transcript and scroll model.
+    const takeover = await view(id, 110, 28, true);
+    await sleep(150);
+    takeover.claim();
+    const claimed = await waitFor(() => takeover.lastFrame('grid')?.controller === true
+      && takeover.lastFrame('grid')?.cols === 110 && takeover.lastFrame('grid')?.rows === 28);
+    check('post-restart watcher claims the narrow zoom geometry', claimed,
+      JSON.stringify(takeover.lastFrame('grid')));
+    await sleep(150);
+    if (Headless) {
+      const narrowText = await takeover.screenText();
+      const state = await takeover.bufferState();
+      check('post-restart narrow zoom keeps one complete transcript',
+        duplicateTokens(narrowText) === beforeBrowser
+        && uniqueTokens(narrowText) === initialBrowserTokens,
+        `${duplicateTokens(narrowText)} duplicates, ${uniqueTokens(narrowText)} tokens`);
+      check('post-restart narrow zoom keeps scroll and styling',
+        state?.canReachBothEnds && state?.atBottom && state?.coloredHistoryCells > 0,
+        JSON.stringify(state));
+    }
+    takeover.resize(150, 40);
+    const widened = await waitFor(() => takeover.lastFrame('grid')?.cols === 150
+      && takeover.lastFrame('grid')?.rows === 40);
+    check('post-restart controller zooms wide again', widened,
+      JSON.stringify(takeover.lastFrame('grid')));
+    await sleep(150);
+    if (Headless) {
+      const wideText = await takeover.screenText();
+      const state = await takeover.bufferState();
+      check('post-restart wide zoom keeps one complete transcript',
+        duplicateTokens(wideText) === beforeBrowser
+        && uniqueTokens(wideText) === initialBrowserTokens,
+        `${duplicateTokens(wideText)} duplicates, ${uniqueTokens(wideText)} tokens`);
+      check('post-restart wide zoom keeps scroll and styling',
+        state?.canReachBothEnds && state?.atBottom && state?.coloredHistoryCells > 0,
+        JSON.stringify(state));
+    }
+    takeover.close();
+    restarted.close();
+    await stop(id);
+  }
+
+  // A drag should issue one final resize, not one SIGWINCH per animation frame.
+  {
+    const id = await session('resize storm');
+    const v = await view(id, 120, 40);
+    await sleep(400);
+    for (let i = 0; i < 16; i++) {
+      v.resize(120 - i * 2, 40 - i);
+      await sleep(25);
+    }
+    v.resize(88, 24);
+    const settled = await waitFor(() => v.lastFrame('grid')?.cols === 88 && v.lastFrame('grid')?.rows === 24);
+    check('resize storm settles at its final size', settled, JSON.stringify(v.lastFrame('grid')));
+    check('resize storm is coalesced', v.countFrames('grid') <= 3, `${v.countFrames('grid')} grid frames`);
+    v.close();
+    await stop(id);
+  }
+
+  // Low zoom on a large/high-DPI panel can legitimately exceed the former
+  // 400x200 cap. The safety bound must not create dead space in that range.
+  {
+    const id = await session('large panel');
+    const v = await view(id, 120, 40);
+    await sleep(300);
+    v.resize(640, 300);
+    const expanded = await waitFor(() => v.lastFrame('grid')?.cols === 640
+      && v.lastFrame('grid')?.rows === 300);
+    check('large low-zoom panel is not clipped to the legacy grid cap', expanded,
+      JSON.stringify(v.lastFrame('grid')));
+    v.close();
+    await stop(id);
+  }
+
+  // Reattachment is serialized from Ghostty state, not from a 256 KiB suffix
+  // of raw PTY traffic. Both the oldest and newest retained rows must return.
+  {
+    const id = await session('full canonical restore');
+    const a = await view(id, 110, 30);
+    await sleep(600);
+    a.type(`for i in $(seq 1 4500); do printf 'RESTORE-%04d-%070d\\n' "$i" "$i"; done\r`);
+    const complete = await waitFor(async () => (await gridText(id, 5000)).includes('RESTORE-4500-'), 20_000);
+    check('large history finishes printing', complete);
+    a.close();
+    await sleep(300);
+    const b = await view(id, 110, 30, true);
+    const restored = await waitFor(() => b.bytes.includes('RESTORE-4500-'), 12_000);
+    check('reattach receives the canonical restore', restored && !!b.lastFrame('restore'));
+    check('restore is not capped at the old raw replay limit', b.bytes.length > 262_144, `${b.bytes.length} bytes`);
+    check('restore includes the oldest retained output', b.bytes.includes('RESTORE-0001-'));
+    check('restore includes the newest retained output', b.bytes.includes('RESTORE-4500-'));
+    if (Headless) {
+      const rendered = await b.screenText();
+      check('a fresh emulator can scroll to the oldest restored output', rendered.includes('RESTORE-0001-'));
+      check('a fresh emulator contains the newest restored output', rendered.includes('RESTORE-4500-'));
+    }
+    b.close();
+    await stop(id);
+  }
+
+  // One viewer owns both input and size. A watcher has no effect until an
+  // explicit claim, after which the old controller becomes inert.
+  {
+    const id = await session('controller lease');
+    const a = await view(id, 120, 35);
+    await sleep(400);
+    const b = await view(id, 60, 20);
+    await sleep(400);
+    check('first viewer is the controller', a.lastFrame('grid')?.controller === true
+      && b.lastFrame('restore')?.controller === false);
+    b.resize(50, 15);
+    await sleep(400);
+    check('watcher size cannot shrink the session', b.lastFrame('restore')?.cols === 120
+      && !b.frames.some((frame) => frame.t === 'grid' && frame.cols === 50));
+    b.type('echo WATCHER-MUST-NOT-RUN\r');
+    await sleep(400);
+    check('watcher input is rejected by the server', !a.bytes.includes('WATCHER-MUST-NOT-RUN'));
+
+    b.claim();
+    const claimed = await waitFor(() => b.lastFrame('grid')?.controller === true
+      && b.lastFrame('grid')?.cols === 50 && b.lastFrame('grid')?.rows === 15);
+    check('watcher can claim input and geometry together', claimed, JSON.stringify(b.lastFrame('grid')));
+    b.type('echo CONTROLLER-RAN\r');
+    check('new controller input reaches every viewer', await waitFor(() => a.bytes.includes('CONTROLLER-RAN')
+      && b.bytes.includes('CONTROLLER-RAN')));
+    a.resize(140, 45);
+    await sleep(400);
+    check('old controller becomes an inert watcher', b.lastFrame('grid')?.cols === 50
+      && b.lastFrame('grid')?.rows === 15);
+
+    b.close();
+    const handed = await waitFor(() => a.lastFrame('grid')?.controller === true
+      && a.lastFrame('grid')?.cols === 140 && a.lastFrame('grid')?.rows === 45);
+    check('controller lease passes to a remaining viewer on disconnect', handed, JSON.stringify(a.lastFrame('grid')));
+    a.close();
+    await stop(id);
+  }
+
+  // Focus and unrelated layout events may re-report the same preference.
+  {
+    const id = await session('no-op size');
+    const v = await view(id, 80, 24);
+    await sleep(300);
+    const before = v.countFrames('grid');
+    for (let i = 0; i < 5; i++) v.resize(80, 24);
+    await sleep(500);
+    check('re-reporting the current size performs no reset', v.countFrames('grid') === before,
+      `${v.countFrames('grid') - before} extra frames`);
+    v.close();
+    await stop(id);
+  }
+} catch (err) {
+  check('no exceptions', false, String(err && err.message ? err.message : err));
+  console.log('--- server log tail ---\n' + log.slice(-1600));
+} finally {
+  srv.kill('SIGTERM');
+  await sleep(500);
+  srv.kill('SIGKILL');
+  try { fs.rmSync(DATA_DIR, { recursive: true, force: true }); } catch {}
+  console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+  process.exit(failures ? 1 : 0);
+}

server/src/config.js

@@ -46,16 +46,15 @@ export function refreshVersions() {
   }
 }
 
-export const TMUX_AVAILABLE = commandExists('tmux');
-export const USE_TMUX = process.env.USE_TMUX
-  ? process.env.USE_TMUX === '1'
-  : TMUX_AVAILABLE;
+// tmux is no longer part of the terminal path: sessions are PTYs held by this
+// process with a libghostty-vt grid as the authoritative screen (see runner.js).
 
 /**
  * CLI catalog.
  *  - `bin`  : binary checked on PATH to report availability
  *  - `run`  : command run inside the session shell on first launch
  *  - `cont` : command used to resume a prior conversation (null = no resume)
+ *  - `resizeMode: 'repaint'`: primary-screen TUI redraws its frame on SIGWINCH
  */
 // One setup story for every agent; only the accepted secret names differ.
 const setupHint = (...keys) =>
@@ -81,23 +80,27 @@ export const CLIS = [
   // nothing to launch HERE (that is the point), but unlike files/trace it holds
   // a conversation, so it gets a light and a digest like any other agent.
   { id: 'remote',   label: 'Remote agent', bin: null,      color: '#5ec2e0', run: null,             cont: null },
-  { id: 'claude',   label: 'Claude Code', bin: 'claude',   color: '#d97757', run: 'claude',         cont: 'claude --continue',
+  { id: 'claude',   label: 'Claude Code', bin: 'claude',   color: '#d97757', run: 'claude',         cont: 'claude --continue', resizeMode: 'repaint',
     withPrompt: (q) => `claude ${q}`,
     setup: setupHint('ANTHROPIC_API_KEY') },
-  { id: 'codex',    label: 'Codex',       bin: 'codex',    color: '#5eb6a6', run: 'codex',          cont: 'codex resume --last',
+  { id: 'codex',    label: 'Codex',       bin: 'codex',    color: '#5eb6a6', run: 'codex',          cont: 'codex resume --last', resizeMode: 'repaint',
     withPrompt: (q) => `codex ${q}`,
     setup: setupHint('OPENAI_API_KEY') },
-  { id: 'gemini',   label: 'Gemini CLI',  bin: 'gemini',   color: '#4796e3', run: 'gemini',         cont: null,
+  { id: 'gemini',   label: 'Gemini CLI',  bin: 'gemini',   color: '#4796e3', run: 'gemini',         cont: null, resizeMode: 'repaint',
     withPrompt: (q) => `gemini -i ${q}`, // -i = interactive session seeded with the prompt
     setup: setupHint('GEMINI_API_KEY') },
-  { id: 'opencode', label: 'opencode',    bin: 'opencode', color: '#8a93a0', run: 'opencode',       cont: 'opencode --continue',
+  { id: 'opencode', label: 'opencode',    bin: 'opencode', color: '#8a93a0', run: 'opencode',       cont: 'opencode --continue', resizeMode: 'repaint',
     withPrompt: (q) => `opencode --prompt ${q}`,
     setup: setupHint('ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY') },
-  { id: 'hermes',   label: 'Hermes',      bin: 'hermes',   color: '#a78bfa', run: 'hermes',         cont: 'hermes -c',
+  { id: 'hermes',   label: 'Hermes',      bin: 'hermes',   color: '#a78bfa', run: 'hermes',         cont: 'hermes -c', resizeMode: 'repaint',
     setup: setupHint('HF_TOKEN', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY', 'NOUS_API_KEY') },
   // `chat` = TUI in --local mode: embedded agent, no gateway/daemon needed.
-  { id: 'openclaw', label: 'OpenClaw',    bin: 'openclaw', color: '#c83636', run: 'openclaw chat',  cont: null,
+  { id: 'openclaw', label: 'OpenClaw',    bin: 'openclaw', color: '#c83636', run: 'openclaw chat',  cont: null, resizeMode: 'repaint',
     setup: setupHint('ANTHROPIC_API_KEY') },
+  // Test-only primary-screen repaint fixture. Absent from every normal runtime.
+  ...(process.env.AM_TEST_REPAINT_CMD
+    ? [{ id: 'test-repaint', label: 'Repaint fixture', bin: 'bash', color: '#8aa0ad', run: process.env.AM_TEST_REPAINT_CMD, cont: null, resizeMode: 'repaint' }]
+    : []),
 ];
 
 export function cliById(id) {

server/src/demo.js

@@ -1,7 +1,7 @@
 // Demo mode: a pure view filter. Activating snapshots the session and group IDs
 // that exist right now and hides them from the sidebar/overview, so the Space
 // reads like a fresh install (empty workspace + welcome). Nothing is deleted —
-// tmux sessions keep running, logins and secrets stay valid — and anything
+// live sessions keep running, logins and secrets stay valid — and anything
 // created *after* activation shows through (it isn't in the snapshot).
 // Deactivating clears the snapshot and every real session reappears untouched.
 import fs from 'fs';

server/src/history-store.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const fileFor = (directory, id) => path.join(
+  directory, `${String(id).replace(/[^a-zA-Z0-9._-]/g, '_')}.json`,
+);
+
+export const TERMINAL_HISTORY_VERSION = 8;
+
+const validAnsi = (ansi, text) => typeof ansi === 'string'
+  && ansi.replace(/\x1b\[[0-9;]*m/g, '') === text;
+
+/** Load a plain-text Ghostty scrollback checkpoint, ignoring old/bad schemas. */
+export function loadTerminalHistory(directory, id) {
+  try {
+    const body = fs.readFileSync(fileFor(directory, id), 'utf8');
+    const saved = JSON.parse(body);
+    if (![1, 2, 3, 4, 5, 6, 7, TERMINAL_HISTORY_VERSION].includes(saved?.version)
+        || !Number.isFinite(saved.cols) || !Array.isArray(saved.lines)) return null;
+    const lines = saved.lines.flatMap((line) => {
+      if (typeof line === 'string') return [{ text: line }];
+      if (!line || typeof line.text !== 'string') return [];
+      return [validAnsi(line.ansi, line.text)
+        ? { text: line.text, ansi: line.ansi } : { text: line.text }];
+    });
+    return lines.length ? {
+      version: saved.version, cols: Math.max(1, Math.round(saved.cols)), lines, body,
+    } : null;
+  } catch { return null; }
+}
+
+/**
+ * Debounced, atomic checkpoint writer for one held terminal.
+ *
+ * `snapshot` is deliberately injected: storage knows nothing about Ghostty or
+ * session hosts. `blocked` keeps an in-flight repaint transaction from saving
+ * a pre-commit grid. At most one write is active; a newer snapshot supersedes
+ * any queued one.
+ */
+export function createTerminalHistoryCheckpoint({
+  directory, id, delayMs, snapshot, blocked, persistedBody = null,
+}) {
+  let timer = null;
+  let pending = null;
+  let writing = false;
+  let lastBody = persistedBody;
+
+  const writePending = () => {
+    if (writing || !pending) return;
+    const next = pending;
+    pending = null;
+    if (next === lastBody) return;
+    writing = true;
+    const target = fileFor(directory, id);
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.promises.mkdir(directory, { recursive: true })
+      .then(() => fs.promises.writeFile(temporary, next))
+      .then(() => fs.promises.rename(temporary, target))
+      .then(() => { lastBody = next; })
+      .catch((error) => {
+        console.error('[runner] history checkpoint', error && error.message);
+        fs.promises.unlink(temporary).catch(() => {});
+      })
+      .finally(() => {
+        writing = false;
+        if (pending) writePending();
+      });
+  };
+
+  const schedule = () => {
+    if (timer) return;
+    timer = setTimeout(flush, delayMs);
+    if (timer.unref) timer.unref();
+  };
+
+  const flush = () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (blocked()) { schedule(); return; }
+    let snap;
+    try { snap = snapshot(); } catch { return; }
+    const lines = (snap.scrollbackLines || []).map((line) => {
+      const text = line.text || '';
+      return validAnsi(line.ansi, text) ? { text, ansi: line.ansi } : text;
+    });
+    pending = JSON.stringify({ version: TERMINAL_HISTORY_VERSION, cols: snap.cols, lines });
+    writePending();
+  };
+
+  return { schedule, flush };
+}
+
+const normalText = (text) => String(text || '').replace(/\s+/g, ' ').trim().toLowerCase();
+
+/**
+ * Render earlier conversational turns as plain terminal history.
+ *
+ * The latest user turn is deliberately omitted: the resumed TUI owns that
+ * viewport. Messages already visible in the live grid are omitted as well, so
+ * trace recovery cannot create a second copy of content Claude did repaint.
+ */
+export function traceHistoryLines(page, currentText = '', maxChars = 1024 * 1024) {
+  const turns = Array.isArray(page?.turns) ? page.turns : [];
+  let latestUser = -1;
+  for (let i = turns.length - 1; i >= 0; i--) {
+    if (turns[i]?.role === 'user') { latestUser = i; break; }
+  }
+  const current = normalText(currentText);
+  const currentLines = new Set(String(currentText || '').split(/\r?\n/)
+    .map(normalText).filter(Boolean));
+  const lines = [];
+  let chars = 0;
+  for (const turn of turns.slice(0, latestUser < 0 ? turns.length : latestUser)) {
+    if (turn?.role !== 'user' && turn?.role !== 'assistant') continue;
+    if (turn.role === 'assistant' && turn.kind && turn.kind !== 'final') continue;
+    const text = (turn.blocks || [])
+      .filter((block) => block?.type === 'text')
+      .map((block) => String(block.text || ''))
+      .join('\n')
+      .trim();
+    if (!text) continue;
+    const rendered = `${turn.role === 'user' ? '❯' : '●'} ${text}`;
+    // Prefix matching needs a minimum length to avoid accidental prose hits,
+    // but short prompts are safe to match as complete marked terminal rows.
+    if (!rendered.includes('\n') && currentLines.has(normalText(rendered))) continue;
+    const normalized = normalText(text);
+    const probe = normalized.slice(0, 80);
+    if (probe.length >= 12 && current.includes(probe)) continue;
+    const next = [...rendered.split('\n'), ''];
+    for (const line of next) { lines.push(line); chars += line.length + 1; }
+    while (chars > maxChars && lines.length) chars -= lines.shift().length + 1;
+  }
+  while (lines.at(-1) === '') lines.pop();
+  return lines.map((text) => ({ text }));
+}

server/src/index.js

@@ -8,7 +8,7 @@ import crypto from 'node:crypto';
 import express from 'express';
 import { WebSocketServer } from 'ws';
 import {
-  PORT, PUBLIC_DIR, DATA_DIR, WORKSPACES_DIR, SKILLS_DIR, USE_TMUX, TMUX_AVAILABLE,
+  PORT, PUBLIC_DIR, DATA_DIR, WORKSPACES_DIR, SKILLS_DIR,
   ensureDirs, cliCatalog, cliById, slugify, workspacePath, refreshVersions, PASSIVE_CLIS, isRemote,
 } from './config.js';
 import * as remote from './remote.js';
@@ -16,7 +16,12 @@ import * as store from './sessions.js';
 import * as groups from './groups.js';
 import * as order from './order.js';
 import * as demo from './demo.js';
-import { attach, agentInfo, deriveState, stop, ensureRunning, sendInput, copySelection, paneModes, isRunning, capturePane } from './runner.js';
+import { attach, agentInfo, deriveState, stop, stopAll, ensureRunning, sendInput, isRunning, capturePane, ghosttyReady, ghosttyError } from './runner.js';
+
+// Control frames ride the terminal socket behind a leading NUL pair, which real
+// PTY output never begins with. Same sentinel the old copy-mode hint used, so the
+// frontend's framing is unchanged.
+const TERM_CTRL = '\x00\x00AM:';
 import { buildUsage } from './usage.js';
 import { buildTraces, traceDigests, digestFor, traceLocation, readTrace, readTraceBundle, readTraceByPath, traceHarnessOf } from './traces.js';
 import { initPush, publicKey, deviceCount, addSubscription, removeSubscription, sendToAll } from './push.js';
@@ -130,6 +135,12 @@ await Promise.race([
 // terminal. An unhandled rejection from an async route, or an error emitted by
 // a dropped socket, would otherwise take the whole thing down. Log and keep
 // running instead of exiting.
+// No tmux to outlive us any more: kill the PTYs we hold on the way out so a
+// restart can't leave orphaned agents writing into the workspace.
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => { try { stopAll(); } catch {} process.exit(0); });
+}
+
 process.on('unhandledRejection', (e) => console.error('[unhandledRejection]', e));
 process.on('uncaughtException', (e) => console.error('[uncaughtException]', e));
 
@@ -150,7 +161,7 @@ app.use((req, res, next) => {
 app.get('/api/visibility', (_req, res) => res.json(visibility()));
 
 app.get('/api/health', (_req, res) =>
-  res.json({ ok: true, tmux: USE_TMUX, tmuxAvailable: TMUX_AVAILABLE }));
+  res.json({ ok: true, engine: 'libghostty', ghostty: ghosttyReady(), ghosttyError }));
 
 app.get('/api/clis', (_req, res) => res.json(cliCatalog()));
 
@@ -248,8 +259,8 @@ async function deliver(session, text, from) {
 }
 
 // Type a prompt into a session's terminal from the Overview — no pane needed.
-// If the agent is stopped, wake it first (detached tmux + resume) and give the
-// CLI a moment to boot before the keystrokes land.
+// If the agent is stopped, start its backend PTY and give the resumed CLI a
+// moment to boot before the keystrokes land.
 app.post('/api/sessions/:id/input', async (req, res) => {
   const s = store.get(req.params.id);
   if (!s) return res.status(404).json({ error: 'not found' });
@@ -267,9 +278,8 @@ app.post('/api/sessions/:id/input', async (req, res) => {
 // ---------- agent-to-agent API (/api/agents) ----------
 // Agents coordinate through the same primitives the operator drives from the
 // Overview: read the roster, watch a pane, send a prompt, wait, launch a peer,
-// stop one. This adds no capability — every agent in this container can already
-// `tmux send-keys` at its neighbours — it makes the capability legible,
-// attributed, and stable enough to document in the environment skill.
+// stop one. This makes container-local coordination legible, attributed, and
+// stable enough to document in the environment skill.
 //
 // The etiquette (check state before interrupting, don't ping-pong, don't stop
 // someone unasked, don't spawn armies) is TAUGHT in that skill rather than
@@ -707,7 +717,8 @@ app.get('/api/info', (_req, res) => res.json({
   home: process.env.HOME || null,
   spaceId: process.env.SPACE_ID || null,
   spaceHost: process.env.SPACE_HOST || null,
-  tmux: USE_TMUX,
+  engine: 'libghostty',
+  ghostty: ghosttyReady(),
   locked: isPublic(),
   lockReason: visibility().reason,
   lockBucket: visibility().bucket,
@@ -972,7 +983,7 @@ Hermes — alongside plain shells and a file browser.
 ## What persists (and what doesn't)
 - \`/data\` is **durable storage** (a mounted bucket). Files under \`/data/workspaces/…\` and \`/data/home/…\` survive restarts and sleep.
 - **Empty directories are not persisted** — only files. If a folder must exist, keep a file in it.
-- Sessions are **tmux-backed**: they keep running when the browser disconnects and can be resumed after the Space sleeps.
+- Sessions are held by the Agent Manager backend and keep running when the browser disconnects. A backend restart or Space sleep ends live processes; retained workspace files still persist.
 - Exception: OpenClaw runs with its own \`$HOME\` on local disk for filesystem compatibility; that state is backed up to the bucket every minute.
 
 ## You may not be alone
@@ -2136,77 +2147,54 @@ wss.on('connection', (ws, req) => {
     return;
   }
 
-  // tmux prints a bare "[exited]" line as its parting output — strip it (the
-  // client shows a styled stopped-state instead) but pass everything else.
-  const stripExit = (d) => (typeof d === 'string' ? d.replace(/(\r?\n)?\[exited\](\r?\n)?$/, '') : d);
   handle.onData((d) => {
     if (ws.readyState !== ws.OPEN) return;
-    const out = stripExit(d);
-    if (out.length) ws.send(out);
+    if (d.length) ws.send(d);
   });
   handle.onExit(() => {
+    // Only ONE reason to close now: the agent process itself exited. A second
+    // viewer does not detach the first; it starts as a watcher instead. Still no
+    // auto-reconnect on 4000, or we would respawn the agent in a loop.
     if (ws.readyState === ws.OPEN) {
-      // Our tmux client can die for two very different reasons, and the browser
-      // must react differently to each:
-      //   4001 = another device attached and tmux's -D detached us. The session
-      //          is alive and now belongs to that device, so this client goes
-      //          quiet instead of reconnecting (that would be a tug-of-war).
-      //   4000 = the agent process itself exited. Do NOT auto-reconnect (it
-      //          would respawn the agent in a loop); offer a Restart instead.
-      const handedOff = USE_TMUX && isRunning(session.id);
-      try {
-        ws.close(handedOff ? 4001 : 4000, handedOff ? 'handedoff' : 'exited');
-      } catch { ws.close(); }
+      try { ws.close(4000, 'exited'); } catch { ws.close(); }
     }
   });
+  // A session has one canonical grid and one viewer controls its dimensions.
+  // Watchers still report their preferred size so taking control is immediate.
+  // `reset` means an authoritative Ghostty snapshot follows this frame.
+  handle.onGrid((cols_, rows_, controller, viewers, reset) => {
+    if (ws.readyState !== ws.OPEN) return;
+    try { ws.send(TERM_CTRL + JSON.stringify({ t: 'grid', cols: cols_, rows: rows_, controller, viewers, reset })); } catch {}
+  });
 
+  // Register input before sending the initial restore. Browsers may issue a
+  // claim/resize from `onopen`, while this function is still serializing that
+  // restore. Installing the listener afterwards left a small window where the
+  // first mobile geometry request was silently lost.
   ws.on('message', (raw) => {
     let msg;
     try { msg = JSON.parse(raw.toString()); } catch { return; }
     if (msg.t === 'i') handle.write(msg.d);
     else if (msg.t === 'r') handle.resize(msg.cols, msg.rows);
-    else if (msg.t === 'copy') {
-      const osc52 = copySelection(session.id);
-      if (osc52 && ws.readyState === ws.OPEN) ws.send(osc52);
-    }
+    else if (msg.t === 'claim') handle.claim();
   });
 
-  // Register for copy-mode notifications (the frontend shows an overlay hint).
-  registerModeClient(session.id, ws);
-  ws.on('close', () => { handle.kill(); unregisterModeClient(session.id, ws); });
-});
-
-// Copy-mode indicator: tmux owns the mode (users scroll into it and find the
-// keyboard "dead"), so poll it — one call for all panes — and push changes to
-// attached clients as a control frame the terminal distinguishes from raw
-// output by its leading NUL sentinel. Only polls while clients are attached.
-const MODE_CTRL = '\x00\x00AM:'; // pty output never leads with this
-const modeClients = new Map(); // sessionId -> Set(ws)
-const lastMode = new Map();     // sessionId -> boolean
-let modeTimer = null;
-function registerModeClient(id, ws) {
-  if (!USE_TMUX) return;
-  if (!modeClients.has(id)) modeClients.set(id, new Set());
-  modeClients.get(id).add(ws);
-  // Send current state immediately so a client attaching mid-copy-mode is right.
-  try { ws.send(MODE_CTRL + JSON.stringify({ t: 'mode', copy: !!lastMode.get(id) })); } catch {}
-  if (!modeTimer) modeTimer = setInterval(pollModes, 350);
-}
-function unregisterModeClient(id, ws) {
-  const set = modeClients.get(id);
-  if (set) { set.delete(ws); if (!set.size) { modeClients.delete(id); lastMode.delete(id); } }
-  if (!modeClients.size && modeTimer) { clearInterval(modeTimer); modeTimer = null; }
-}
-function pollModes() {
-  const modes = paneModes();
-  for (const [id, set] of modeClients) {
-    const now = !!modes[id];
-    if (lastMode.get(id) === now) continue;
-    lastMode.set(id, now);
-    const frame = MODE_CTRL + JSON.stringify({ t: 'mode', copy: now });
-    for (const ws of set) if (ws.readyState === ws.OPEN) { try { ws.send(frame); } catch {} }
+  // Ghostty owns the durable terminal model. Reattachment receives one canonical
+  // serialization of its retained scrollback and current styled screen.
+  const restore = handle.restore();
+  if (restore) {
+    try {
+      ws.send(TERM_CTRL + JSON.stringify({
+        t: 'restore', cols: restore.cols, rows: restore.rows,
+        viewers: restore.viewers, controller: restore.controller, reset: true,
+      }));
+      ws.send(restore.ansi);
+    } catch {}
   }
-}
+
+  // Detaching a viewer, NOT stopping the session.
+  ws.on('close', () => handle.kill());
+});
 
 generateEnvSkill(loadSecretNotes()); // keep the environment skill current on boot
 
@@ -2223,7 +2211,7 @@ setTimeout(() => { traceDigests().catch(() => {}); }, 4000);
 startWatchdog();
 
 server.listen(PORT, () => {
-  console.log(`Agent Manager :${PORT}  tmux=${USE_TMUX}  data=${DATA_DIR}`);
+  console.log(`Agent Manager :${PORT}  engine=libghostty${ghosttyReady() ? '' : ' (UNAVAILABLE)'}  data=${DATA_DIR}`);
   console.log('⚠  No authentication: this app trusts whoever can reach it.');
   console.log('   Keep this Space PRIVATE — a public instance gives anyone a shell + your logged-in agents.');
 });

server/src/runner.js

@@ -1,12 +1,31 @@
 import os from 'node:os';
 import path from 'node:path';
 import pty from 'node-pty';
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
-import { USE_TMUX, cliById, WORKSPACES_DIR, isRemote } from './config.js';
-import { update, list } from './sessions.js';
-import { captureOpencodeSession } from './traces.js';
 import { remoteState, setPaused } from './remote.js';
+import { cliById, isRemote, STATE_DIR, WORKSPACES_DIR } from './config.js';
+import { update, list } from './sessions.js';
+import { captureOpencodeSession, readTrace } from './traces.js';
+import {
+  buildPaletteIndex, snapshotToRestoreAnsi, styledSnapshotLines, textColumns,
+} from './snapshot.js';
+import {
+  createTerminalHistoryCheckpoint, loadTerminalHistory, TERMINAL_HISTORY_VERSION,
+  traceHistoryLines,
+} from './history-store.js';
+
+// libghostty-vt ships prebuilts for linux x64/arm64 and macOS arm64. Loading it
+// is guarded so a platform without a prebuilt still boots and says so, rather
+// than taking the whole app down.
+let ghostty = null;
+export let ghosttyError = null;
+try {
+  ghostty = await import('@coder/libghostty-vt-node');
+  buildPaletteIndex(ghostty.createTerminal);
+} catch (err) {
+  ghosttyError = String(err && err.message ? err.message : err);
+  console.error('[runner] libghostty-vt unavailable:', ghosttyError);
+}
 
 const TERM_ENV = {
   ...process.env,
@@ -16,18 +35,74 @@ const TERM_ENV = {
 };
 
 const BASHRC = process.env.AM_BASHRC || '/app/session.bashrc';
-const TMUX_CONF = process.env.TMUX_CONF || '/app/tmux.conf';
 const AM_USER = process.env.SPACE_AUTHOR_NAME || process.env.AM_USER || os.userInfo().username || 'user';
 
 // Interactive bash that loads our prompt rcfile (bash ignores a missing rcfile,
 // so this is safe in local dev where /app/session.bashrc doesn't exist).
 const bashLaunch = `exec bash --rcfile ${BASHRC} -i`;
 
-const tmuxName = (id) => `am-${id}`;
+// ---------- session hosts (what replaced tmux) ----------
+//
+// Every session is one PTY held by THIS process, with a libghostty-vt terminal
+// fed from its output. That terminal is the authoritative screen, so:
+//
+//   * a browser attaching gets canonical history plus a snapshot repaint,
+//     instead of asking tmux to redraw and hoping the agent's TUI cooperates;
+//   * several browsers can watch the same session, with one explicit input/size
+//     controller instead of a one-device-at-a-time disconnect handover;
+//   * agent state is a property read rather than a `tmux capture-pane`
+//     subprocess per session per poll.
+//
+// PTYs still end with this process, but canonical scrollback is checkpointed to
+// durable storage below and rejoined with the CLI's resumed screen on relaunch.
 
-// If the rendered pane text hasn't changed for this long, it's not working.
+// Rendered text unchanged for this long means the agent isn't working.
 const BUSY_SECS = 4;
-const paneSig = new Map(); // id -> { sig, changedAt } (changedAt in unix seconds)
+// Re-rendering the grid to text on every chunk during a burst is wasteful.
+const SAMPLE_THROTTLE_MS = 250;
+// Despite the Node wrapper's `scrollbackLimit` name, Ghostty's native option is
+// a byte budget. Passing a line count such as 20,000 retains only a small native
+// allocation (about 700 ordinary rows). Keep the unit explicit at our boundary.
+const DEFAULT_SCROLLBACK_BYTES = 64 * 1024 * 1024;
+const configuredScrollback = process.env.AM_SCROLLBACK_BYTES === undefined
+  ? Number.NaN
+  : Number(process.env.AM_SCROLLBACK_BYTES);
+const SCROLLBACK_BYTES = Number.isFinite(configuredScrollback) && configuredScrollback >= 0
+  ? configuredScrollback
+  : DEFAULT_SCROLLBACK_BYTES;
+// A layout resize is only worth acting on once it stops changing. ResizeObserver
+// fires per animation frame while a window is dragged; coalescing that burst
+// avoids repeatedly reflowing the terminal and repeatedly sending SIGWINCH.
+const RESIZE_SETTLE_MS = Number(process.env.AM_RESIZE_SETTLE_MS || 120);
+// Primary-screen agent TUIs redraw their whole frame after SIGWINCH. Let that
+// burst settle in a scratch emulator, then merge its final frame once; streaming
+// the raw redraw would turn every overflow row into duplicate history.
+const RESIZE_CAPTURE_IDLE_MS = Number(process.env.AM_RESIZE_CAPTURE_IDLE_MS || 80);
+const RESIZE_CAPTURE_MAX_MS = Number(process.env.AM_RESIZE_CAPTURE_MAX_MS || 900);
+// A resumed agent paints through the same primary-screen protocol as a resize,
+// but may pause for seconds between its welcome frame and replayed transcript.
+// Keep that transaction distinct from the deliberately short resize debounce:
+// committing its first chunk makes every later chunk look like new history.
+const STARTUP_CAPTURE_IDLE_MS = Number(process.env.AM_STARTUP_CAPTURE_IDLE_MS || 5000);
+const STARTUP_CAPTURE_MAX_MS = Number(process.env.AM_STARTUP_CAPTURE_MAX_MS || 20000);
+// Unlike the PTY process, /data survives a Space rebuild. Checkpoint canonical
+// scrollback there so deploys and sleeps do not turn a resumed agent into a
+// terminal with only its freshly repainted viewport.
+const HISTORY_SAVE_MS = Number(process.env.AM_HISTORY_SAVE_MS || 5000);
+const HISTORY_DIR = path.join(STATE_DIR, 'terminal-history');
+// Claude's resume stream can pause between its welcome frame and replayed
+// conversation. Treat that as one startup transaction; hydrating during the
+// pause would seed a turn that Claude is about to print itself.
+const TRACE_HYDRATE_IDLE_MS = Number(process.env.AM_TRACE_HYDRATE_IDLE_MS || 5000);
+const TRACE_HYDRATE_MIN_MS = Number(process.env.AM_TRACE_HYDRATE_MIN_MS || 3000);
+// Bound untrusted WebSocket geometry without imposing the old 400x200 ceiling,
+// which left visible dead space on high-DPI displays at low zoom levels.
+const MIN_COLS = 20;
+const MIN_ROWS = 5;
+const MAX_COLS = 1000;
+const MAX_ROWS = 500;
+
+const hosts = new Map(); // session id -> host
 
 function djb2(s) {
   let h = 5381;
@@ -35,108 +110,46 @@ function djb2(s) {
   return h;
 }
 
-// In direct-PTY (no-tmux) mode we track live handles to report running status.
-const live = new Map(); // id -> Set(handle)
-const track = (id, h) => {
-  if (!live.has(id)) live.set(id, new Set());
-  live.get(id).add(h);
-};
-const untrack = (id, h) => {
-  const s = live.get(id);
-  if (s) {
-    s.delete(h);
-    if (!s.size) live.delete(id);
-  }
-};
-
 export function isRunning(id) {
-  if (USE_TMUX) {
-    try {
-      execFileSync('tmux', ['has-session', '-t', tmuxName(id)], { stdio: 'ignore' });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  return live.has(id);
+  return hosts.has(id);
 }
 
-// Which sessions have a pane in copy mode right now — one tmux call covers all
-// panes, so the server can push a copy-mode hint to attached clients cheaply.
-export function paneModes() {
-  const modes = {};
-  if (!USE_TMUX) return modes;
-  let out = '';
-  try {
-    // Mode first (a single 0/1), then the session name — which is `am-<id>`
-    // and never contains a space, so splitting on the first space is safe.
-    out = execFileSync('tmux', ['list-panes', '-a', '-F', '#{pane_in_mode} #{session_name}'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch { return modes; } // no tmux server yet
-  for (const line of out.split('\n')) {
-    const sp = line.indexOf(' ');
-    if (sp < 0) continue;
-    const name = line.slice(sp + 1);
-    if (!name.startsWith('am-')) continue;
-    const id = name.slice(3);
-    modes[id] = modes[id] || line.slice(0, sp) === '1';
+export function ghosttyReady() {
+  return !!ghostty;
+}
+
+/** Sample the grid's rendered text and record when it last changed. */
+function sampleScreen(host) {
+  const now = Date.now();
+  if (host.lastSampleAt && now - host.lastSampleAt < SAMPLE_THROTTLE_MS) return;
+  host.lastSampleAt = now;
+  let text = '';
+  try { text = host.vt.getVisibleText(); } catch { return; }
+  const sig = djb2(text);
+  if (host.screenSig !== sig) {
+    host.screenSig = sig;
+    host.screenChangedAt = now;
   }
-  return modes;
 }
 
 /**
- * Detect activity by DIFFING each pane's rendered text between polls. This
- * ignores colour-only animations (e.g. Codex's shimmering banner) that fooled a
- * raw output-activity check, while still catching spinners, streaming output and
- * elapsed-time counters (their text changes). Returns Map id -> { age } where
- * age is seconds since the pane text last changed.
+ * Activity per session, keyed like the old tmux sweep so callers don't change.
+ * No subprocess and no memo: the grid is already current, so this is a map build
+ * over held sessions.
  */
-let infoMemo = { ts: 0, map: new Map() };
-
 export function agentInfo() {
-  // The sweep shells out to tmux once per session, synchronously. Memoize it
-  // briefly so N browser tabs polling /api/tree don't multiply that cost.
-  if (Date.now() - infoMemo.ts < 1500) return infoMemo.map;
   const map = new Map();
-  infoMemo = { ts: Date.now(), map };
-  if (!USE_TMUX) return map;
-  let list;
-  try {
-    // stderr is dropped on every tmux call that already handles its own
-    // failure: with no server running (fresh container, or after the last
-    // session ends) tmux prints "error connecting to /tmp/tmux-1000/default"
-    // and the catch below treats that as "no sessions" — so the message is
-    // pure noise that made a healthy Space look broken in the log.
-    list = execFileSync('tmux', ['list-sessions', '-F', '#{session_name}'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch {
-    paneSig.clear();
-    return map; // no server / no sessions
-  }
-  const now = Math.floor(Date.now() / 1000);
-  const live = new Set();
-  for (const name of list.split('\n')) {
-    if (!name.startsWith('am-')) continue;
-    const id = name.slice(3);
-    live.add(id);
-    let text = '';
-    try {
-      text = execFileSync('tmux', ['capture-pane', '-p', '-t', name],
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-    } catch {}
-    const sig = djb2(text);
-    const prev = paneSig.get(id);
-    const changedAt = !prev || prev.sig !== sig ? now : prev.changedAt;
-    paneSig.set(id, { sig, changedAt });
-    map.set(id, { age: now - changedAt });
+  const now = Date.now();
+  for (const [id, host] of hosts) {
+    const changedAt = host.screenChangedAt || host.startedAt;
+    map.set(id, { age: Math.round((now - changedAt) / 1000), bells: host.bells || 0 });
   }
-  for (const id of [...paneSig.keys()]) if (!live.has(id)) paneSig.delete(id);
   return map;
 }
 
 /**
  * Map activity + the session's known CLI into a UI state:
- *   working  — pane text is actively changing (thinking / streaming / a command)
+ *   working  — screen text is actively changing (thinking / streaming / a command)
  *   waiting  — agent alive but its screen is static → it's your turn
  *   idle     — a plain shell sitting at its prompt
  *   stopped  — no live session
@@ -151,6 +164,492 @@ export function deriveState(session, info) {
   return session.cli === 'shell' ? 'idle' : 'waiting';
 }
 
+/** The visible screen as text, with no browser attached. */
+export function peek(id) {
+  const host = hosts.get(id);
+  if (!host) return null;
+  try { return host.vt.getVisibleText(); } catch { return null; }
+}
+
+// ---------- the shared grid ----------
+//
+// A PTY has exactly one geometry. One attached viewer therefore holds a size
+// lease (the controller); every other viewer watches the same grid without
+// changing it. A watcher can take the lease through an explicit interaction.
+// This prevents a phone or background tab from resizing a desktop session merely
+// by connecting.
+
+function effectiveGrid(host) {
+  return host.controller?.want || { cols: host.cols, rows: host.rows };
+}
+
+function preferredGrid(cols, rows, fallback) {
+  const c = Number.isFinite(cols) ? Math.round(cols) : fallback.cols;
+  const r = Number.isFinite(rows) ? Math.round(rows) : fallback.rows;
+  return {
+    cols: Math.max(MIN_COLS, Math.min(MAX_COLS, c)),
+    rows: Math.max(MIN_ROWS, Math.min(MAX_ROWS, r)),
+  };
+}
+
+function notifyGrid(host, reset = false) {
+  for (const sub of host.subs) {
+    sub.onGrid(host.cols, host.rows, host.controller === sub, host.subs.size, reset);
+  }
+}
+
+function clearCaptureTimers(txn) {
+  if (txn.idleTimer) clearTimeout(txn.idleTimer);
+  if (txn.maxTimer) clearTimeout(txn.maxTimer);
+  txn.idleTimer = null;
+  txn.maxTimer = null;
+}
+
+function logicalText(lines, cols) {
+  let text = '';
+  for (let line = 0; line < lines.length; line++) {
+    const row = lines[line].text || '';
+    text += row;
+    // A full terminal row is a soft wrap. Do not insert whitespace: Claude's
+    // words can be split at an arbitrary column between snapshots. A shorter
+    // row ended with a real line break, which must remain part of the overlap.
+    if (textColumns(row) < cols) {
+      text += '\n';
+    }
+  }
+  return text;
+}
+
+function logicalHistory(text) {
+  if (!text) return [];
+  const lines = text.split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  return lines.map((line) => ({ text: line }));
+}
+
+function visibleRows(vt) {
+  try { return vt.getVisibleText().split('\n').map((text) => ({ text })); } catch { return []; }
+}
+
+function longestPrefixOccurrence(pattern, text) {
+  const prefix = new Array(pattern.length).fill(0);
+  for (let i = 1, matched = 0; i < pattern.length; i++) {
+    while (matched && pattern[i] !== pattern[matched]) matched = prefix[matched - 1];
+    if (pattern[i] === pattern[matched]) matched++;
+    prefix[i] = matched;
+  }
+  let matched = 0, best = 0, bestEnd = -1;
+  for (let i = 0; i < text.length; i++) {
+    while (matched && text[i] !== pattern[matched]) matched = prefix[matched - 1];
+    if (text[i] === pattern[matched]) matched++;
+    if (matched > best) { best = matched; bestEnd = i; }
+    if (matched === pattern.length) matched = prefix[matched - 1];
+  }
+  return { length: best, end: bestEnd };
+}
+
+/**
+ * Merge a primary-screen repaint into the fullest transcript seen so far.
+ *
+ * A growing pane can reveal an archived suffix after a fresh welcome/header,
+ * so the overlap may occur inside the repaint rather than at its first byte.
+ * Searching the reversed strings finds the longest archive suffix anywhere in
+ * the repaint in linear time. The repaint prefix is inserted before that
+ * suffix, preserving a header without retaining two copies of the turns.
+ */
+export function mergeRepaintArchive(base, repaint) {
+  if (!base) return repaint;
+  if (!repaint) return base;
+  if (!base.trim()) return repaint;
+  if (!repaint.trim()) return base;
+  const reverse = (text) => {
+    let result = '';
+    for (let i = text.length - 1; i >= 0; i--) result += text[i];
+    return result;
+  };
+  // Shape 1: an archive suffix is revealed after a freshly painted header.
+  const suffix = longestPrefixOccurrence(
+    reverse(base.slice(-repaint.length)), reverse(repaint),
+  );
+  // Shape 2: the repaint starts in the archive, then replaces its volatile
+  // footer (dimensions, status line, prompt chrome) with the new one.
+  const prefix = longestPrefixOccurrence(repaint.slice(0, base.length), base);
+  const minimum = Math.min(12, base.trim().length, repaint.trim().length);
+  if (Math.max(suffix.length, prefix.length) < minimum) return base + repaint;
+  if (prefix.length > suffix.length) {
+    const baseOffset = prefix.end - prefix.length + 1;
+    return base.slice(0, baseOffset) + repaint;
+  }
+  const repaintOffset = repaint.length - 1 - suffix.end;
+  return repaint.slice(0, repaintOffset) + base
+    + repaint.slice(repaintOffset + suffix.length);
+}
+
+/**
+ * Replace the archive's old visible tail with a new repaint.
+ *
+ * Resize output is presentation, never appended terminal output. Match the
+ * longest prefix of the new visible grid inside the archive; everything before
+ * that point is the hidden prefix, and the new grid replaces everything after
+ * it (including dimension-dependent status/footer text).
+ */
+export function repaintArchiveView(archive, visible, fallbackHistory = '') {
+  if (!visible) return { archive, history: logicalHistory(archive) };
+  const leading = visible.match(/^(?:[ \t]*\n)*/)?.[0].length || 0;
+  const candidate = visible.slice(leading);
+  let match = candidate ? longestPrefixOccurrence(candidate, archive) : { length: 0, end: -1 };
+
+  // A few shared characters are not a safe repaint boundary in a substantial
+  // screen. Claude's randomized status lines, for example, all begin with
+  // "Worked for ". Anchoring a fresh screen there can retain the old turn that
+  // precedes a later status line, then append that same turn again. Require a
+  // meaningful overlap for long screens, while still accepting complete short
+  // prompts in small panes.
+  const archiveContentLength = archive.trim().length;
+  const confidence = (tail) => Math.min(
+    64,
+    archiveContentLength,
+    Math.max(12, Math.floor(tail.trim().length / 2)),
+  );
+  let minimum = confidence(candidate);
+
+  // A repaint may start with one volatile row before its stable transcript.
+  // If the first row offers only a weak match, advance by logical lines until
+  // the first substantial overlap is found. The visible grid is bounded to 500
+  // rows, and the cap keeps a maliciously fragmented screen from repeatedly
+  // scanning a large archive.
+  if (match.length < minimum) {
+    let offset = 0;
+    for (let attempts = 0; attempts < 32;) {
+      const newline = candidate.indexOf('\n', offset);
+      if (newline < 0) break;
+      offset = newline + 1;
+      const tail = candidate.slice(offset);
+      if (!tail.trim()) break;
+      const nextBreak = tail.indexOf('\n');
+      const firstLine = tail.slice(0, nextBreak < 0 ? undefined : nextBreak);
+      if (firstLine.trim().length < 12) continue;
+      attempts++;
+      const next = longestPrefixOccurrence(tail, archive);
+      const nextMinimum = confidence(tail);
+      if (next.length >= nextMinimum) {
+        match = next;
+        minimum = nextMinimum;
+        break;
+      }
+    }
+  }
+  let history = fallbackHistory;
+  if (match.length >= minimum && minimum > 0) {
+    const archiveOffset = match.end - match.length + 1;
+    history = archive.slice(0, archiveOffset);
+  }
+  return { archive: history + visible, history: logicalHistory(history) };
+}
+
+function terminalArchive(vt, snap) {
+  return logicalText([...(snap.scrollbackLines || []), ...visibleRows(vt)], snap.cols);
+}
+
+const MAX_HISTORY_STYLES = 50_000;
+
+function learnHistoryStyles(host, vt, snap) {
+  if (!host.historyStyles || typeof vt.formatHtml !== 'function') return;
+  const visibleHasStyle = (snap.cells || []).some((cell) => cell.bold || cell.italic
+    || cell.underline || cell.foreground || cell.background);
+  if (!visibleHasStyle && host.historyStyles.size === 0) return;
+  let styled;
+  try { styled = styledSnapshotLines(snap, vt.formatHtml()); } catch { return; }
+  for (const line of [...styled.rows, ...styled.logical]) {
+    if (!line.text || !line.ansi) continue;
+    // Refresh insertion order so frequently repainted transcript rows survive
+    // the bounded cache while old one-off status lines age out.
+    host.historyStyles.delete(line.text);
+    host.historyStyles.set(line.text, line.ansi);
+  }
+  while (host.historyStyles.size > MAX_HISTORY_STYLES) {
+    host.historyStyles.delete(host.historyStyles.keys().next().value);
+  }
+}
+
+function withHistoryStyles(host, lines) {
+  return (lines || []).map((line) => {
+    const ansi = line.ansi || host.historyStyles?.get(line.text || '');
+    return ansi ? { ...line, ansi } : line;
+  });
+}
+
+function styledSnapshot(host, vt, snap) {
+  learnHistoryStyles(host, vt, snap);
+  return { ...snap, scrollbackLines: withHistoryStyles(host, snap.scrollbackLines) };
+}
+
+/**
+ * Commit one captured agent repaint without duplicating its overflow rows.
+ *
+ * The pre-resize scrollback boundary and final repaint are merged once, then
+ * both the server terminal and every viewer are restored from that same state.
+ * Shell sessions never use this path.
+ */
+function finishCapturedGrid(host, txn) {
+  if (host.resizeCapture !== txn) return;
+  host.resizeCapture = null;
+  clearCaptureTimers(txn);
+
+  let snap = null;
+  let replacement = null;
+  let committedArchive = null;
+  if (txn.sawData) {
+    try { snap = txn.vt.snapshot({ includeCells: true, includeScrollback: true }); } catch {}
+    if (snap) {
+      try {
+        learnHistoryStyles(host, txn.vt, snap);
+        const visible = visibleRows(txn.vt);
+        const visibleText = logicalText(visible, txn.cols);
+        const view = repaintArchiveView(txn.archive, visibleText, txn.fallbackHistory);
+        committedArchive = view.archive;
+        replacement = ghostty.createTerminal({
+          cols: txn.cols,
+          rows: txn.rows,
+          scrollbackLimit: SCROLLBACK_BYTES,
+        });
+        replacement.feed(snapshotToRestoreAnsi({
+          ...snap, scrollbackLines: withHistoryStyles(host, view.history),
+        }));
+      } catch (error) {
+        console.error('[runner] resize capture commit', error && error.message);
+        try { replacement?.dispose(); } catch {}
+        replacement = null;
+        snap = null;
+      }
+    }
+  }
+
+  try {
+    if (!snap) {
+      // The foreground process ignored SIGWINCH. Ordinary reflow is the only
+      // faithful outcome because no repaint exists to replace the old screen.
+      host.vt.resize(txn.cols, txn.rows);
+      host.cols = txn.cols;
+      host.rows = txn.rows;
+      host.repaintArchive = null;
+      notifyGrid(host, false);
+    } else {
+      const previous = host.vt;
+      host.vt = replacement;
+      host.cols = txn.cols;
+      host.rows = txn.rows;
+      // The archive retains the full transcript even when a wide grid exposes
+      // all of it and therefore needs no scrollback. A later narrow repaint can
+      // derive the hidden prefix again instead of losing the oldest rows.
+      host.repaintArchive = committedArchive;
+      // Reset and restore one canonical snapshot. Keeping a browser's old
+      // scrollback while painting only the new viewport makes the two models
+      // diverge after a narrow zoom, even when the server history is correct.
+      notifyGrid(host, true);
+      const committed = host.vt.snapshot({ includeCells: true, includeScrollback: true });
+      const ansi = snapshotToRestoreAnsi(styledSnapshot(host, host.vt, committed));
+      for (const sub of host.subs) sub.onData(ansi);
+      try { previous.dispose(); } catch {}
+      sampleScreen(host);
+    }
+  } finally {
+    try { txn.vt.dispose(); } catch {}
+  }
+  host.historyCheckpoint.schedule();
+
+  // A newer controller preference may have arrived while the repaint settled.
+  const next = effectiveGrid(host);
+  if (next.cols !== host.cols || next.rows !== host.rows) scheduleGrid(host);
+}
+
+function armCapturedGrid(host, txn) {
+  if (txn.idleTimer) clearTimeout(txn.idleTimer);
+  txn.idleTimer = setTimeout(() => finishCapturedGrid(host, txn), txn.idleMs);
+  if (txn.idleTimer.unref) txn.idleTimer.unref();
+}
+
+/** Start or supersede the bounded repaint transaction for an agent TUI. */
+function startCapturedGrid(host, cols, rows, seed = null, resizePty = true) {
+  const previous = host.resizeCapture;
+  // A viewer can report its measured geometry before the resumed CLI emits
+  // its first byte. That resize is still part of startup, so claim the durable
+  // seed here rather than leaving it for a later output chunk.
+  const pendingStartup = !seed && !previous ? host.startupHistory : null;
+  if (pendingStartup) {
+    seed = {
+      history: pendingStartup.lines,
+      historyCols: pendingStartup.cols,
+      logical: true,
+    };
+  }
+  // Resizing during a startup capture supersedes its scratch grid, but must not
+  // downgrade its long idle window to the ordinary resize debounce. Otherwise
+  // a delayed resume repaint is committed later as duplicate terminal output.
+  const startupCapture = !!seed || !!previous?.startupCapture;
+  let archive = seed?.history
+    ? (seed.logical
+      ? `${seed.history.map((line) => line.text || '').join('\n')}\n`
+      : logicalText(seed.history, seed.historyCols || host.cols))
+    : host.repaintArchive;
+  let fallbackHistory = seed?.history ? archive : null;
+  if (previous) {
+    archive = previous.archive;
+    fallbackHistory = previous.fallbackHistory;
+    host.resizeCapture = null;
+    clearCaptureTimers(previous);
+    try { previous.vt.dispose(); } catch {}
+  }
+  try {
+    const source = host.vt.snapshot({ includeScrollback: true });
+    if (archive == null) {
+      archive = terminalArchive(host.vt, source);
+    }
+    if (fallbackHistory == null) {
+      fallbackHistory = logicalText(source.scrollbackLines || [], source.cols);
+    }
+  } catch { return false; }
+
+  let scratch;
+  try {
+    scratch = ghostty.createTerminal({ cols, rows, scrollbackLimit: 4 * 1024 * 1024 });
+  } catch (error) {
+    console.error('[runner] resize capture setup', error && error.message);
+    try { scratch?.dispose(); } catch {}
+    return false;
+  }
+
+  const txn = {
+    vt: scratch,
+    cols,
+    rows,
+    archive: archive || '',
+    fallbackHistory: fallbackHistory || '',
+    sawData: false,
+    startupCapture,
+    idleMs: startupCapture ? STARTUP_CAPTURE_IDLE_MS : RESIZE_CAPTURE_IDLE_MS,
+    maxMs: startupCapture ? STARTUP_CAPTURE_MAX_MS : RESIZE_CAPTURE_MAX_MS,
+    idleTimer: null,
+    maxTimer: null,
+  };
+  host.resizeCapture = txn;
+  if (pendingStartup) host.startupHistory = null;
+  if (resizePty) { try { host.pty.resize(cols, rows); } catch {} }
+  txn.maxTimer = setTimeout(() => finishCapturedGrid(host, txn), txn.maxMs);
+  if (txn.maxTimer.unref) txn.maxTimer.unref();
+  return true;
+}
+
+/**
+ * Move the session to the size its viewers imply.
+ *
+ * Shells use ordinary reflow: every row is real output. Known agent TUIs on the
+ * primary screen instead use a bounded scratch transaction because their full
+ * SIGWINCH redraw is presentation, not new history. Alternate-screen programs
+ * are already isolated from primary scrollback and use ordinary resize.
+ */
+function applyGrid(host) {
+  const { cols, rows } = effectiveGrid(host);
+  if (!host.resizeCapture && cols === host.cols && rows === host.rows) return false;
+  if (host.captureResize) {
+    let alt = false;
+    try { alt = !!host.vt.snapshot().isAltScreen; } catch {}
+    if (!alt && startCapturedGrid(host, cols, rows)) return true;
+  }
+  host.cols = cols;
+  host.rows = rows;
+  try { host.vt.resize(cols, rows); } catch {}
+  // Put the geometry frame on every viewer's ordered WebSocket stream before
+  // SIGWINCH can make the foreground application repaint at the new size.
+  // Otherwise those repaint bytes may be interpreted using the old grid and
+  // leave duplicated or displaced rows in the browser emulator.
+  notifyGrid(host, false);
+  try { host.pty.resize(cols, rows); } catch {}
+  return true;
+}
+
+/**
+ * Apply the controller's preferred grid once requests stop arriving. If a
+ * pending request clamps back to the current size, report that canonical size.
+ */
+function scheduleGrid(host) {
+  if (host.gridTimer) clearTimeout(host.gridTimer);
+  host.gridTimer = setTimeout(() => {
+    host.gridTimer = null;
+    if (!applyGrid(host)) notifyGrid(host, false);
+  }, RESIZE_SETTLE_MS);
+  if (host.gridTimer.unref) host.gridTimer.unref();
+}
+
+function armTraceHydration(host) {
+  if (!host.traceHistoryPage || host.traceHistoryTimer) return;
+  const readyAt = Math.max(
+    host.startedAt + TRACE_HYDRATE_MIN_MS,
+    (host.lastOutputAt || host.startedAt) + TRACE_HYDRATE_IDLE_MS,
+    host.resizeCapture ? Date.now() + TRACE_HYDRATE_IDLE_MS : 0,
+  );
+  host.traceHistoryTimer = setTimeout(() => {
+    host.traceHistoryTimer = null;
+    if (hosts.get(host.id) !== host || !host.traceHistoryPage) return;
+    if (host.resizeCapture || Date.now() < readyAt) { armTraceHydration(host); return; }
+
+    let snap;
+    try { snap = host.vt.snapshot({ includeCells: true, includeScrollback: true }); } catch { return; }
+    const visible = visibleRows(host.vt);
+    const visibleText = logicalText(visible, snap.cols);
+    const currentText = visible.map((line) => line.text || '').join('\n');
+    const recovered = traceHistoryLines(host.traceHistoryPage, currentText);
+    host.traceHistoryPage = null;
+    learnHistoryStyles(host, host.vt, snap);
+
+    let replacement = null;
+    try {
+      // The trace supplies missing older turns while the settled startup grid
+      // supplies the welcome and the newest live turn. Merge their overlap
+      // into one archive rather than appending either presentation verbatim.
+      const startup = terminalArchive(host.vt, snap);
+      const archive = mergeRepaintArchive(logicalText(recovered, snap.cols), startup);
+      const view = repaintArchiveView(archive, visibleText);
+      replacement = ghostty.createTerminal({
+        cols: host.cols, rows: host.rows, scrollbackLimit: SCROLLBACK_BYTES,
+      });
+      replacement.feed(snapshotToRestoreAnsi({
+        ...snap,
+        scrollbackLines: withHistoryStyles(host, view.history),
+      }));
+      const previous = host.vt;
+      host.vt = replacement;
+      host.repaintArchive = view.archive;
+      notifyGrid(host, true);
+      const committed = host.vt.snapshot({ includeCells: true, includeScrollback: true });
+      const ansi = snapshotToRestoreAnsi(styledSnapshot(host, host.vt, committed));
+      for (const sub of host.subs) sub.onData(ansi);
+      try { previous.dispose(); } catch {}
+      sampleScreen(host);
+      host.historyCheckpoint.schedule();
+    } catch (error) {
+      console.error('[runner] trace history restore', error && error.message);
+      try { replacement?.dispose(); } catch {}
+    }
+  }, Math.max(0, readyAt - Date.now()));
+  if (host.traceHistoryTimer.unref) host.traceHistoryTimer.unref();
+}
+
+async function hydrateTraceHistory(session, host) {
+  try {
+    let page = await readTrace(session, { offset: 0, limit: 500 });
+    if (page.total > page.turns.length) {
+      page = await readTrace(session, { offset: Math.max(0, page.total - 500), limit: 500 });
+    }
+    if (hosts.get(host.id) !== host) return;
+    host.traceHistoryPage = page;
+    armTraceHydration(host);
+  } catch {
+    // A new/onboarding session may not have a trace yet; live output remains
+    // authoritative and its first checkpoint will become the durable seed.
+  }
+}
+
 // ---------- Codex conversation pinning ----------
 // Codex picks its own conversation id at launch and doesn't accept one up
 // front — but it announces the pick immediately: a rollout file named
@@ -598,18 +1097,28 @@ function commandFor(session) {
   }
 
   // Other agents: resume when one likely exists, else a fresh launch. `exec` so
-  // the agent is the pane's foreground process; when it exits the tmux session
-  // ends — a clear "done" signal — and the fallback preserves that.
+  // the agent is the PTY's foreground process; when it exits the session ends —
+  // a clear "done" signal — and the fallback preserves that.
   if (session.everStarted && cli.cont) return `${cli.cont} || exec ${cli.run}`;
   if (q0 && cli.withPrompt) return `exec ${cli.withPrompt(q0)}`;
   return `exec ${cli.run}`;
 }
 
-/** Attach a new PTY client to the session (creating the tmux session if needed). */
-export function attach(session, cols, rows) {
-  // A remote agent has no terminal here by design — its harness runs on another
-  // machine. /ws catches this and says so in the pane.
-  if (isRemote(session.cli)) throw new Error('this pane has no terminal — it talks to an agent elsewhere');
+/**
+ * Start the session's PTY and its grid, without any browser attached. Returns
+ * true if it had to spawn. This is now the ONLY way a session starts, so the
+ * Overview reply box waking a stopped agent and a browser opening a pane take
+ * exactly the same path.
+ */
+export function ensureRunning(session, cols = 120, rows = 34) {
+  // Nothing to start: a remote agent starts itself, on its own machine. Both
+  // callers guard this too; keep the refusal here so no future one can spawn
+  // a PTY for a pane that can never use it.
+  if (isRemote(session.cli)) throw new Error('a remote agent runs on its own machine — nothing to start here');
+  const existing = hosts.get(session.id);
+  if (existing) return false;
+  if (!ghostty) throw new Error(`libghostty-vt unavailable: ${ghosttyError}`);
+
   // The recorded workspace-relative path ('' = the workspaces root itself).
   // If the folder was deleted or moved, mkdir simply recreates it empty — no
   // tracking, no magic.
@@ -617,160 +1126,265 @@ export function attach(session, cols, rows) {
   const workdir = path.join(WORKSPACES_DIR, folder);
   fs.mkdirSync(workdir, { recursive: true });
   const full = commandFor(session);
+  const captureResize = cliById(session.cli)?.resizeMode === 'repaint';
 
-  let term;
-  if (USE_TMUX) {
-    const args = [];
-    if (fs.existsSync(TMUX_CONF)) args.push('-f', TMUX_CONF);
-    args.push(
-      // -A: attach if it exists, else create. -D: detach any other client, so
-      // exactly ONE device drives the session at a time. Sharing it was worse:
-      // window-size=latest resized the shared window to whoever spoke last, and
-      // agent TUIs (which paint into the normal buffer, not the alt screen)
-      // re-emit their frame with erase math computed at the OLD width — so every
-      // phone/desktop flip left another copy of the same text in the scrollback,
-      // wrapped at the other device's width. The handover is sequential instead:
-      // the detached client is told the session lives on (close code 4001) and
-      // waits for a deliberate return before taking it back (see TerminalPane).
-      'new-session', '-A', '-D', '-s', tmuxName(session.id), '-c', workdir,
-      '-e', `AM_SESSION=${folder}`,
-      '-e', `AM_NAME=${session.name}`,
-      '-e', `AM_ID=${session.id}`,
-      '-e', `AM_USER=${AM_USER}`,
-      '-e', `AM_ROOT=${WORKSPACES_DIR}`, // prompt shows $PWD relative to this
-      'sh', '-lc', full,
-    );
-    term = pty.spawn('tmux', args, { name: 'xterm-256color', cols, rows, cwd: workdir, env: TERM_ENV });
-  } else {
-    const env = { ...TERM_ENV, AM_SESSION: folder, AM_NAME: session.name, AM_ID: session.id, AM_USER, AM_ROOT: WORKSPACES_DIR };
-    term = pty.spawn('bash', ['-lc', full], { name: 'xterm-256color', cols, rows, cwd: workdir, env });
+  const env = {
+    ...TERM_ENV,
+    AM_SESSION: folder,
+    AM_NAME: session.name,
+    AM_ID: session.id,
+    AM_USER,
+    AM_ROOT: WORKSPACES_DIR, // prompt shows $PWD relative to this
+  };
+  const term = pty.spawn('bash', ['-lc', full], {
+    name: 'xterm-256color', cols, rows, cwd: workdir, env,
+  });
+  const vt = ghostty.createTerminal({ cols, rows, scrollbackLimit: SCROLLBACK_BYTES });
+  const loadedHistory = loadTerminalHistory(HISTORY_DIR, session.id);
+  // Older agent checkpoints may contain startup repaint frames or a turn that
+  // trace hydration raced with Claude's own replay. Rebuild those once from
+  // the trace. Shell history never used that path and remains safe to restore.
+  const persistedHistory = captureResize
+    && loadedHistory?.version < TERMINAL_HISTORY_VERSION ? null : loadedHistory;
+  if (persistedHistory) {
+    try {
+      vt.feed(snapshotToRestoreAnsi({
+        cols, rows, cursorRow: 0, cursorCol: 0, isAltScreen: false, cells: [],
+        scrollbackLines: persistedHistory.lines,
+      }));
+    } catch (error) {
+      console.error('[runner] history restore', error && error.message);
+    }
   }
+  const host = {
+    id: session.id,
+    pty: term,
+    vt,
+    cols,
+    rows,
+    captureResize,
+    resizeCapture: null,
+    repaintArchive: null,
+    historyStyles: new Map((persistedHistory?.lines || [])
+      .filter((line) => line.text && line.ansi).map((line) => [line.text, line.ansi])),
+    startupHistory: captureResize ? persistedHistory : null,
+    historyCheckpoint: null,
+    traceHistoryPage: null,
+    traceHistoryTimer: null,
+    subs: new Set(),
+    controller: null,
+    gridTimer: null,
+    startedAt: Date.now(),
+    lastOutputAt: Date.now(),
+    screenChangedAt: Date.now(),
+    bells: 0,
+  };
+  host.historyCheckpoint = createTerminalHistoryCheckpoint({
+    directory: HISTORY_DIR,
+    id: host.id,
+    delayMs: HISTORY_SAVE_MS,
+    snapshot: () => {
+      const snap = host.vt.snapshot({ includeScrollback: true });
+      learnHistoryStyles(host, host.vt, snap);
+      if (!captureResize) {
+        return { ...snap, scrollbackLines: withHistoryStyles(host, snap.scrollbackLines) };
+      }
+      const archive = host.repaintArchive ?? terminalArchive(host.vt, snap);
+      return {
+        cols: host.cols,
+        scrollbackLines: withHistoryStyles(host, logicalHistory(archive)),
+      };
+    },
+    blocked: () => !!host.resizeCapture,
+    persistedBody: persistedHistory?.body || null,
+  });
+
+  term.onData((chunk) => {
+    host.lastOutputAt = Date.now();
+    if (host.traceHistoryTimer) {
+      clearTimeout(host.traceHistoryTimer);
+      host.traceHistoryTimer = null;
+    }
+    if (host.traceHistoryPage) armTraceHydration(host);
+    let txn = host.resizeCapture;
+    if (!txn && host.startupHistory) {
+      startCapturedGrid(host, host.cols, host.rows, null, false);
+      txn = host.resizeCapture;
+    }
+    if (txn) {
+      try { txn.vt.feed(chunk); } catch (e) { console.error('[runner] resize capture', e && e.message); }
+      txn.sawData = true;
+      for (let i = 0; i < chunk.length; i++) {
+        if (chunk.charCodeAt(i) === 7) { host.bells++; host.lastBellAt = Date.now(); }
+      }
+      armCapturedGrid(host, txn);
+      return;
+    }
+
+    // This is real output outside a resize transaction. It may have advanced
+    // scrollback, so the next transaction takes a fresh canonical boundary.
+    host.repaintArchive = null;
+    try { host.vt.feed(chunk); } catch (e) { console.error('[runner] vt.feed', e && e.message); }
+    host.historyCheckpoint.schedule();
+
+    // State detection rides the feed path: the grid is already current, so there
+    // is nothing to poll and no subprocess to spawn.
+    sampleScreen(host);
+    for (let i = 0; i < chunk.length; i++) {
+      if (chunk.charCodeAt(i) === 7) { host.bells++; host.lastBellAt = Date.now(); }
+    }
+
+    for (const sub of host.subs) sub.onData(chunk);
+  });
+
+  term.onExit(() => {
+    hosts.delete(session.id);
+    if (host.gridTimer) { clearTimeout(host.gridTimer); host.gridTimer = null; }
+    if (host.traceHistoryTimer) { clearTimeout(host.traceHistoryTimer); host.traceHistoryTimer = null; }
+    if (host.resizeCapture) {
+      clearCaptureTimers(host.resizeCapture);
+      try { host.resizeCapture.vt.dispose(); } catch {}
+      host.resizeCapture = null;
+    }
+    host.historyCheckpoint.flush();
+    try { host.vt.dispose(); } catch {}
+    for (const sub of host.subs) sub.onExit();
+    host.subs.clear();
+  });
 
+  hosts.set(session.id, host);
+  if (!persistedHistory && captureResize) hydrateTraceHistory(session, host);
   if (!session.everStarted) update(session.id, { everStarted: true, pendingPrompt: undefined });
   if (session.cli === 'codex') scheduleCodexCapture(session, workdir);
   if (session.cli === 'opencode') scheduleOpencodeCapture(session, workdir);
   if (session.cli === 'claude') scheduleClaudeCapture(session, workdir);
-
-  const handle = {
-    onData: (cb) => term.onData(cb),
-    onExit: (cb) => term.onExit(cb),
-    write: (d) => { try { term.write(d); } catch {} },
-    resize: (c, r) => { try { term.resize(c, r); } catch {} },
-    kill: () => { try { term.kill(); } catch {} },
-  };
-  track(session.id, handle);
-  term.onExit(() => untrack(session.id, handle));
-  return handle;
+  return true;
 }
 
 /**
- * Make sure the session's tmux process exists WITHOUT a browser pane attached
- * (used by the Overview reply box to wake a stopped agent). Returns true if it
- * had to spawn. Direct-PTY mode has no detached equivalent — throws if dead.
+ * Subscribe a viewer to a session, starting it if needed.
+ *
+ * Unlike the tmux version this does NOT spawn anything per viewer, and
+ * `handle.kill()` only unsubscribes — closing a tab must never stop an agent.
+ * `handle.restore()` returns a canonical snapshot: Ghostty's complete plain-text
+ * history followed by a styled visible-screen repaint. It never replays an
+ * arbitrary suffix of old PTY bytes at a new geometry.
  */
-export function ensureRunning(session) {
-  // Nothing to start: a remote agent starts itself, elsewhere. Callers that
-  // might see one must go through deliver() (index.js) instead of assuming a PTY.
-  if (isRemote(session.cli)) throw new Error('a remote agent runs on its own machine — nothing to start here');
-  if (isRunning(session.id)) return false;
-  if (!USE_TMUX) throw new Error('session is not running');
-  const folder = session.path ?? session.id;
-  const workdir = path.join(WORKSPACES_DIR, folder);
-  fs.mkdirSync(workdir, { recursive: true });
-  const args = [];
-  if (fs.existsSync(TMUX_CONF)) args.push('-f', TMUX_CONF);
-  args.push(
-    'new-session', '-d', '-s', tmuxName(session.id), '-c', workdir,
-    '-x', '200', '-y', '50', // sane size until a client attaches (window-size=latest)
-    '-e', `AM_SESSION=${folder}`,
-    '-e', `AM_NAME=${session.name}`,
-    '-e', `AM_ID=${session.id}`,
-    '-e', `AM_USER=${AM_USER}`,
-    '-e', `AM_ROOT=${WORKSPACES_DIR}`,
-    'sh', '-lc', commandFor(session),
-  );
-  execFileSync('tmux', args, { stdio: 'ignore', env: TERM_ENV });
-  if (!session.everStarted) update(session.id, { everStarted: true, pendingPrompt: undefined });
-  if (session.cli === 'codex') scheduleCodexCapture(session, workdir);
-  if (session.cli === 'opencode') scheduleOpencodeCapture(session, workdir);
-  if (session.cli === 'claude') scheduleClaudeCapture(session, workdir);
-  return true;
+export function attach(session, cols, rows) {
+  ensureRunning(session, cols, rows);
+  const host = hosts.get(session.id);
+  if (!host) throw new Error('session failed to start');
+
+  const sub = {
+    onData: () => {},
+    onExit: () => {},
+    onGrid: () => {},
+    want: preferredGrid(cols, rows, host),
+  };
+  host.subs.add(sub);
+  if (!host.controller) host.controller = sub;
+  // Existing viewers need to know that the session is now shared. The new
+  // viewer receives the same role/count in its restore frame below.
+  notifyGrid(host, false);
+  if (host.controller === sub && (sub.want.cols !== host.cols || sub.want.rows !== host.rows)) scheduleGrid(host);
+
+  return {
+    onData: (cb) => { sub.onData = (d) => { try { cb(d); } catch {} }; },
+    onExit: (cb) => { sub.onExit = () => { try { cb(); } catch {} }; },
+    onGrid: (cb) => { sub.onGrid = (c, r, controller, viewers, reset) => { try { cb(c, r, controller, viewers, reset); } catch {} }; },
+    // Input and terminal-query responses are accepted from one emulator only.
+    write: (d) => {
+      if (host.controller !== sub) return;
+      try { host.pty.write(d); } catch {}
+    },
+    // Every viewer remembers what it can display, but only the current
+    // controller's request changes the PTY.
+    resize: (c, r) => {
+      if (!Number.isFinite(c) || !Number.isFinite(r)) return;
+      const want = preferredGrid(c, r, host);
+      const had = sub.want;
+      sub.want = want;
+      if (had && had.cols === want.cols && had.rows === want.rows) return;
+      if (host.controller === sub) scheduleGrid(host);
+    },
+    claim: () => {
+      if (!host.subs.has(sub) || host.controller === sub) return;
+      host.controller = sub;
+      notifyGrid(host, false);
+      scheduleGrid(host);
+    },
+    restore: () => {
+      let snap;
+      try { snap = host.vt.snapshot({ includeCells: true, includeScrollback: true }); } catch { return null; }
+      return {
+        ansi: snapshotToRestoreAnsi(styledSnapshot(host, host.vt, snap)),
+        cols: snap.cols,
+        rows: snap.rows,
+        viewers: host.subs.size,
+        controller: host.controller === sub,
+      };
+    },
+    // Detach this viewer only. The session, its grid and its scrollback stay.
+    kill: () => {
+      const controlled = host.controller === sub;
+      host.subs.delete(sub);
+      if (controlled) host.controller = host.subs.values().next().value || null;
+      notifyGrid(host, false);
+      if (controlled && host.controller) scheduleGrid(host);
+    },
+  };
 }
 
 /** Type a line into the session's terminal (works with no browser attached). */
 export async function sendInput(id, text) {
+  const host = hosts.get(id);
+  if (!host) throw new Error('session is not running');
   // Multi-line prompts go in as a bracketed paste so the CLI's composer treats
   // the inner newlines as soft line breaks instead of submitting early.
   const payload = text.includes('\n') ? `\x1b[200~${text}\x1b[201~` : text;
   // The Enter must arrive as its OWN keypress: TUIs (codex) detect rapid input
   // bursts as a paste, and a CR inside the burst becomes a newline in the
   // composer instead of a submit. A short gap breaks the burst.
-  const gap = () => new Promise((r) => setTimeout(r, 300));
-  if (USE_TMUX) {
-    execFileSync('tmux', ['send-keys', '-t', tmuxName(id), '-l', '--', payload], { stdio: 'ignore' });
-    await gap();
-    execFileSync('tmux', ['send-keys', '-t', tmuxName(id), 'Enter'], { stdio: 'ignore' });
-    return;
-  }
-  const set = live.get(id);
-  if (!set || !set.size) throw new Error('session is not running');
-  const h = set.values().next().value;
-  h.write(payload);
-  await gap();
-  h.write('\r');
+  host.pty.write(payload);
+  await new Promise((r) => setTimeout(r, 300));
+  host.pty.write('\r');
 }
 
 /**
  * The session's rendered screen plus `lines` of scrollback above it — what a
  * human would see in the pane. Used by the agent API so one agent can watch
  * another's progress instead of spending a turn asking.
+ *
+ * Reads the grid we already hold, so it costs no subprocess. snapshot() returns
+ * history as plain text, which is exactly what the tmux `capture-pane -p` this
+ * replaced produced, so callers see the same shape.
  */
 export function capturePane(id, lines = 80) {
-  if (!USE_TMUX) return null;
+  const host = hosts.get(id);
+  if (!host) return null; // stopped
   const n = Math.max(0, Math.min(2000, lines));
-  let out;
-  try {
-    out = execFileSync('tmux', ['capture-pane', '-p', '-S', `-${n}`, '-t', tmuxName(id)],
-      { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
-  } catch { return null; } // no such session (stopped)
-  // capture-pane pads the pane to its full height with blank lines; drop them so
-  // a short screen doesn't arrive as 50 lines of nothing. -S already bounds the
-  // scrollback, so the caller decides whether to trim the visible screen too.
-  return out.replace(/\s+$/, '');
-}
-
-/** Return the last mouse selection for this session as a browser-consumable OSC 52. */
-export function copySelection(id) {
-  if (!USE_TMUX) return null;
-  const bufferName = `am-copy-${tmuxName(id)}`;
-  let text = '';
-  try {
-    text = execFileSync('tmux', ['save-buffer', '-b', bufferName, '-'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: TERM_ENV });
-  } catch {
-    try {
-      text = execFileSync('tmux', ['save-buffer', '-'],
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: TERM_ENV });
-    } catch {
-      return null;
-    }
-  }
-  if (!text) return null;
-  return `\x1b]52;c;${Buffer.from(text, 'utf8').toString('base64')}\x07`;
+  let snap;
+  try { snap = host.vt.snapshot({ includeScrollback: n > 0 }); } catch { return null; }
+  const history = (snap.scrollbackLines || []).slice(-n).map((l) => l.text);
+  const visible = (snap.visibleLines || []).map((l) => l.text);
+  // Trailing blank rows are padding, not content: a short screen should not
+  // arrive as 50 lines of nothing.
+  return [...history, ...visible].join('\n').replace(/\s+$/, '');
 }
 
-/** Stop a session entirely (kills the tmux session / the running process). */
+/** Stop a session entirely (kills the process; viewers get an exit close code). */
 export function stop(id) {
-  // A remote agent has no process to kill — "stopped" means disconnected, so the
-  // same button pauses it and closes its open polls.
-  const s = list().find((x) => x.id === id);
-  if (s && isRemote(s.cli)) { setPaused(s, true, 'stopped from the manager'); return; }
-  if (USE_TMUX) {
-    try {
-      execFileSync('tmux', ['kill-session', '-t', tmuxName(id)], { stdio: 'ignore' });
-    } catch {}
-  } else {
-    const s = live.get(id);
-    if (s) for (const h of s) h.kill();
+  const host = hosts.get(id);
+  if (!host) return;
+  try { host.pty.kill(); } catch {}
+}
+
+/**
+ * Kill every session. Without tmux nothing outlives this process, so a clean
+ * shutdown should not leave orphaned PTYs behind holding the workspace.
+ */
+export function stopAll() {
+  for (const host of hosts.values()) {
+    try { host.pty.kill(); } catch {}
   }
 }

server/src/snapshot.js

@@ -0,0 +1,281 @@
+/**
+ * Turn a libghostty-vt snapshot into an ANSI repaint.
+ *
+ * Deliberately renderer-agnostic: the output is just bytes, so the same restore
+ * works for xterm.js today and anything else that speaks VT later. That
+ * portability is the argument for holding the grid server-side: the browser
+ * stays a dumb renderer, and a reattaching client is repainted from our own
+ * grid instead of asking the agent's TUI to redraw itself.
+ *
+ * snapshot() omits blank cells entirely, so gaps are painted as spaces.
+ */
+
+/**
+ * snapshot() resolves palette colours to hex against libghostty's OWN default
+ * palette, so blindly emitting truecolor would repaint a restored screen in
+ * ghostty's greens and yellows instead of the theme the browser renders live
+ * with. Probe the library for its palette once, then emit indexed SGR whenever a
+ * colour came from it — the client re-maps those through its own theme, and only
+ * genuinely truecolor cells stay pinned.
+ */
+let paletteIndex = null;
+
+export function buildPaletteIndex(createTerminal) {
+  if (paletteIndex) return paletteIndex;
+  const map = new Map();
+  try {
+    const probe = createTerminal({ cols: 16, rows: 16, scrollbackLimit: 0 });
+    let out = '';
+    for (let i = 0; i < 256; i++) {
+      if (i % 16 === 0 && i > 0) out += '\r\n';
+      out += `\x1b[38;5;${i}mX`;
+    }
+    probe.feed(`${out}\x1b[0m`);
+    for (const cell of probe.snapshot({ includeCells: true }).cells || []) {
+      const idx = cell.row * 16 + cell.col;
+      // A cell with no explicit foreground rendered as the default, which has no
+      // stable index to map back to — leave those to truecolor.
+      if (idx < 256 && cell.foreground && !map.has(cell.foreground)) map.set(cell.foreground, idx);
+    }
+    probe.dispose();
+  } catch {
+    /* fall through to truecolor-only */
+  }
+  paletteIndex = map;
+  return map;
+}
+
+const hexToRgb = (hex) => {
+  const h = hex.replace('#', '');
+  if (h.length !== 6) return null;
+  const n = Number.parseInt(h, 16);
+  if (Number.isNaN(n)) return null;
+  return `${(n >> 16) & 255};${(n >> 8) & 255};${n & 255}`;
+};
+
+function colorSgr(hex, layer) {
+  const idx = paletteIndex && paletteIndex.get(hex);
+  if (idx !== undefined) return `\x1b[${layer};5;${idx}m`;
+  const rgb = hexToRgb(hex);
+  return rgb ? `\x1b[${layer};2;${rgb}m` : '';
+}
+
+function sgrFor(cell) {
+  let out = '';
+  if (cell.bold) out += '\x1b[1m';
+  if (cell.italic) out += '\x1b[3m';
+  if (cell.underline) out += '\x1b[4m';
+  if (cell.foreground) out += colorSgr(cell.foreground, 38);
+  if (cell.background) out += colorSgr(cell.background, 48);
+  return out;
+}
+
+/** Cells indexed by row, since snapshot() returns them as a flat sparse list. */
+function cellGrid(snap) {
+  const grid = Array.from({ length: snap.rows }, () => new Array(snap.cols).fill(null));
+  for (const cell of snap.cells || []) {
+    if (cell.row >= 0 && cell.row < snap.rows && cell.col >= 0 && cell.col < snap.cols) {
+      grid[cell.row][cell.col] = cell;
+    }
+  }
+  return grid;
+}
+
+/**
+ * One row as styled text, with no cursor positioning. Everything after the last
+ * drawn cell is dropped: trailing spaces are the bulk of a mostly-empty agent
+ * screen, and the caller has either just erased the line or is about to end it.
+ */
+function renderRow(cells, cols) {
+  let last = -1;
+  for (let col = cols - 1; col >= 0; col--) {
+    if (cells[col] && (cells[col].text !== ' ' || cells[col].background)) { last = col; break; }
+  }
+  if (last < 0) return '';
+
+  let out = '';
+  let style = '';
+  let col = 0;
+  while (col <= last) {
+    const cell = cells[col];
+    if (!cell) {
+      if (style) { out += '\x1b[0m'; style = ''; }
+      out += ' ';
+      col += 1;
+      continue;
+    }
+    const next = sgrFor(cell);
+    if (next !== style) {
+      out += '\x1b[0m' + next;
+      style = next;
+    }
+    out += cell.text;
+    col += Math.max(1, cell.width || 1);
+  }
+  if (style) out += '\x1b[0m';
+  return out;
+}
+
+export function snapshotToAnsi(snap) {
+  const grid = cellGrid(snap);
+
+  // Normalise the receiver's active buffer first. Reset attributes so nothing
+  // leaks in from what was showing, and hide the cursor so the repaint doesn't
+  // strobe across the screen.
+  let out = snap.isAltScreen ? '\x1b[?1049h' : '\x1b[?1049l';
+  out += '\x1b[?25l\x1b[0m\x1b[H\x1b[2J';
+
+  for (let row = 0; row < snap.rows; row++) {
+    const line = renderRow(grid[row], snap.cols);
+    if (line) out += `\x1b[${row + 1};1H` + line;
+  }
+
+  out += `\x1b[0m\x1b[${snap.cursorRow + 1};${snap.cursorCol + 1}H`;
+  out += '\x1b[?25h';
+  return out;
+}
+
+// Snapshot history is plain terminal text. Count its display columns closely
+// enough to know how many visual rows it occupies when restored at a different
+// width; using string.length loses wrapped rows (and then the screen repaint
+// overwrites them). Combining marks are zero-width, common CJK/emoji ranges are
+// two columns, and everything else is one.
+export function textColumns(text) {
+  let width = 0;
+  for (const char of text) {
+    const cp = char.codePointAt(0);
+    if (cp === 0x200d || cp === 0xfe0e || cp === 0xfe0f || /\p{Mark}/u.test(char)) continue;
+    const wide = cp >= 0x1100 && (
+      cp <= 0x115f || cp === 0x2329 || cp === 0x232a
+      || (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f)
+      || (cp >= 0xac00 && cp <= 0xd7a3)
+      || (cp >= 0xf900 && cp <= 0xfaff)
+      || (cp >= 0xfe10 && cp <= 0xfe19)
+      || (cp >= 0xfe30 && cp <= 0xfe6f)
+      || (cp >= 0xff00 && cp <= 0xff60)
+      || (cp >= 0xffe0 && cp <= 0xffe6)
+      || (cp >= 0x1f300 && cp <= 0x1faff)
+      || (cp >= 0x20000 && cp <= 0x3fffd)
+    );
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+function htmlEntities(text) {
+  return text
+    .replace(/&#x([0-9a-f]+);/gi, (_, value) => String.fromCodePoint(Number.parseInt(value, 16)))
+    .replace(/&#(\d+);/g, (_, value) => String.fromCodePoint(Number.parseInt(value, 10)))
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function cssColor(style, property, layer) {
+  const escaped = property.replace('-', '\\-');
+  const palette = style.match(new RegExp(`(?:^|;)${escaped}: var\\(--vt-palette-(\\d+)\\)`));
+  if (palette) return `${layer};5;${palette[1]}`;
+  const rgb = style.match(new RegExp(`(?:^|;)${escaped}: rgb\\((\\d+), (\\d+), (\\d+)\\)`));
+  return rgb ? `${layer};2;${rgb[1]};${rgb[2]};${rgb[3]}` : '';
+}
+
+function htmlStyleSgr(style) {
+  const codes = [];
+  const foreground = cssColor(style, 'color', 38);
+  const background = cssColor(style, 'background-color', 48);
+  if (foreground) codes.push(foreground);
+  if (background) codes.push(background);
+  if (style.includes('font-weight: bold')) codes.push('1');
+  if (style.includes('opacity: 0.5')) codes.push('2');
+  if (style.includes('font-style: italic')) codes.push('3');
+  if (/text-decoration-line:[^;]*underline/.test(style)) codes.push('4');
+  if (/text-decoration-line:[^;]*blink/.test(style)) codes.push('5');
+  if (style.includes('filter: invert(100%)')) codes.push('7');
+  if (/text-decoration-line:[^;]*line-through/.test(style)) codes.push('9');
+  if (/text-decoration-line:[^;]*overline/.test(style)) codes.push('53');
+  return codes.length ? `\x1b[${codes.join(';')}m` : '';
+}
+
+const hasAnsiStyle = (text) => text.replace(/\x1b\[0m/g, '').includes('\x1b[');
+
+/** Convert Ghostty's deterministic debug HTML into one ANSI string per visual row. */
+function htmlAnsiRows(html) {
+  if (typeof html !== 'string') return [];
+  const first = html.indexOf('>');
+  const last = html.lastIndexOf('</div>');
+  if (first < 0 || last <= first) return [];
+  const inner = html.slice(first + 1, last);
+  const ansi = inner
+    .replace(/<div style="([^"]*)">/g, (_, style) => htmlStyleSgr(style))
+    .replace(/<\/div>/g, '\x1b[0m');
+  return htmlEntities(ansi).split('\n');
+}
+
+/** Styled visual rows for the complete primary grid, including scrollback. */
+export function styledTerminalRows(snap, html) {
+  const plain = [...(snap.scrollbackLines || []), ...(snap.visibleLines || [])];
+  const ansi = htmlAnsiRows(html);
+  while (ansi.length < plain.length && !(plain[ansi.length]?.text || '')) ansi.push('');
+  if (ansi.length !== plain.length) return plain.map((line) => ({ text: line.text || '' }));
+  return plain.map((line, index) => {
+    const text = line.text || '';
+    const rendered = ansi[index] || '';
+    return hasAnsiStyle(rendered) ? { text, ansi: `${rendered}\x1b[0m` } : { text };
+  });
+}
+
+function joinStyledRows(rows, cols) {
+  const lines = [];
+  let text = '';
+  let ansi = '';
+  for (const row of rows) {
+    text += row.text || '';
+    ansi += row.ansi || row.text || '';
+    if (textColumns(row.text || '') < cols) {
+      lines.push(hasAnsiStyle(ansi) ? { text, ansi: `${ansi}\x1b[0m` } : { text });
+      text = '';
+      ansi = '';
+    }
+  }
+  if (text || ansi) lines.push(hasAnsiStyle(ansi) ? { text, ansi: `${ansi}\x1b[0m` } : { text });
+  return lines;
+}
+
+/** Styled logical lines, joining visual rows that were soft-wrapped. */
+export function styledLogicalLines(snap, html) {
+  return joinStyledRows(styledTerminalRows(snap, html), snap.cols);
+}
+
+/** Parse Ghostty's formatted state once when both visual and logical keys are needed. */
+export function styledSnapshotLines(snap, html) {
+  const rows = styledTerminalRows(snap, html);
+  return { rows, logical: joinStyledRows(rows, snap.cols) };
+}
+
+/**
+ * Rebuild a fresh viewer from Ghostty's canonical state.
+ *
+ * The binding currently exposes styled cells only for the visible screen, while
+ * scrollback is plain text. That is still a much stronger restore boundary than
+ * replaying a truncated raw PTY byte stream: it includes every retained history
+ * row, is already reflowed to the current geometry, and cannot begin halfway
+ * through an escape sequence.
+ *
+ * A line becomes scrollback only after it leaves the visible grid. Print the
+ * history on the primary screen, then scroll the remaining visible history rows
+ * off before painting the authoritative current screen.
+ */
+export function snapshotToRestoreAnsi(snap) {
+  const history = (snap.scrollbackLines || []).map((line) => ({
+    text: line.text || '', ansi: typeof line.ansi === 'string' ? line.ansi : '',
+  }));
+  let out = '\x1b[?1049l\x1b[?25l\x1b[0m\x1b[H\x1b[2J';
+  if (history.length) {
+    out += history.map((line) => line.ansi || line.text).join('\r\n');
+    const visualRows = history.reduce((total, line) =>
+      total + Math.max(1, Math.ceil(textColumns(line.text) / Math.max(1, snap.cols))), 0);
+    out += `\x1b[${snap.rows};1H` + '\r\n'.repeat(Math.min(visualRows, snap.rows));
+  }
+  out += snapshotToAnsi(snap);
+  return out;
+}

tmux.conf

@@ -1,163 +0,0 @@
-# Agent Manager tmux config (passed via `tmux -f`).
-set -g status off                 # hide the status bar at the bottom
-# Mouse ON: tmux only enables mouse reporting on the client when this is on, so
-# it's required to forward the wheel to apps that request the mouse (Claude Code
-# scrolls its own transcript) and to scroll tmux history in plain shells. The
-# cost is that a plain drag goes to tmux copy-mode; Cmd+C in the frontend asks
-# tmux to copy that selection explicitly.
-set -g mouse on
-set -g history-limit 100000       # deep scrollback
-set -g window-size latest         # size the window to the active client
-set -g destroy-unattached off     # keep sessions alive when no client attached
-set -g escape-time 10
-set -g mode-style "fg=#0e1217,bg=#5fd0d8"
-# tmux still uses OSC 52 as the transport for explicit browser Cmd+C copies.
-set -g set-clipboard on
-set -as terminal-features ',*:clipboard'
-# Mouse selection should not copy to the system clipboard by itself. Keep the
-# highlight active, but store the selected text for the browser's later Cmd+C.
-bind -T copy-mode    MouseDown1Pane send-keys -X cancel
-bind -T copy-mode-vi MouseDown1Pane send-keys -X cancel
-bind -T copy-mode    MouseDragEnd1Pane send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode    DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode-vi DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode    TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode-vi TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-no-clear "tmux load-buffer -b am-copy-#{session_name} -"
-bind -T copy-mode    C-c send-keys -X copy-pipe-no-clear
-bind -T copy-mode-vi C-c send-keys -X copy-pipe-no-clear
-
-# Typing beats modes: users scroll into copy mode (mouse wheel) and then
-# wonder why the keyboard is dead. Any printable key a command or prompt
-# would start with cancels copy mode and lands in the pane, so typing just
-# works. Scrolling keys (wheel/PgUp/arrows), Space (begin selection), q and
-# Escape keep their copy-mode roles; Cmd+C copies via the C-c binding above.
-# The frontend shows a "copy mode" overlay while a pane is in this mode.
-bind -T copy-mode    a { send-keys -X cancel ; send-keys -- 'a' }
-bind -T copy-mode-vi a { send-keys -X cancel ; send-keys -- 'a' }
-bind -T copy-mode    b { send-keys -X cancel ; send-keys -- 'b' }
-bind -T copy-mode-vi b { send-keys -X cancel ; send-keys -- 'b' }
-bind -T copy-mode    c { send-keys -X cancel ; send-keys -- 'c' }
-bind -T copy-mode-vi c { send-keys -X cancel ; send-keys -- 'c' }
-bind -T copy-mode    d { send-keys -X cancel ; send-keys -- 'd' }
-bind -T copy-mode-vi d { send-keys -X cancel ; send-keys -- 'd' }
-bind -T copy-mode    e { send-keys -X cancel ; send-keys -- 'e' }
-bind -T copy-mode-vi e { send-keys -X cancel ; send-keys -- 'e' }
-bind -T copy-mode    f { send-keys -X cancel ; send-keys -- 'f' }
-bind -T copy-mode-vi f { send-keys -X cancel ; send-keys -- 'f' }
-bind -T copy-mode    g { send-keys -X cancel ; send-keys -- 'g' }
-bind -T copy-mode-vi g { send-keys -X cancel ; send-keys -- 'g' }
-bind -T copy-mode    h { send-keys -X cancel ; send-keys -- 'h' }
-bind -T copy-mode-vi h { send-keys -X cancel ; send-keys -- 'h' }
-bind -T copy-mode    i { send-keys -X cancel ; send-keys -- 'i' }
-bind -T copy-mode-vi i { send-keys -X cancel ; send-keys -- 'i' }
-bind -T copy-mode    j { send-keys -X cancel ; send-keys -- 'j' }
-bind -T copy-mode-vi j { send-keys -X cancel ; send-keys -- 'j' }
-bind -T copy-mode    k { send-keys -X cancel ; send-keys -- 'k' }
-bind -T copy-mode-vi k { send-keys -X cancel ; send-keys -- 'k' }
-bind -T copy-mode    l { send-keys -X cancel ; send-keys -- 'l' }
-bind -T copy-mode-vi l { send-keys -X cancel ; send-keys -- 'l' }
-bind -T copy-mode    m { send-keys -X cancel ; send-keys -- 'm' }
-bind -T copy-mode-vi m { send-keys -X cancel ; send-keys -- 'm' }
-bind -T copy-mode    n { send-keys -X cancel ; send-keys -- 'n' }
-bind -T copy-mode-vi n { send-keys -X cancel ; send-keys -- 'n' }
-bind -T copy-mode    o { send-keys -X cancel ; send-keys -- 'o' }
-bind -T copy-mode-vi o { send-keys -X cancel ; send-keys -- 'o' }
-bind -T copy-mode    p { send-keys -X cancel ; send-keys -- 'p' }
-bind -T copy-mode-vi p { send-keys -X cancel ; send-keys -- 'p' }
-bind -T copy-mode    q { send-keys -X cancel ; send-keys -- 'q' }
-bind -T copy-mode-vi q { send-keys -X cancel ; send-keys -- 'q' }
-bind -T copy-mode    r { send-keys -X cancel ; send-keys -- 'r' }
-bind -T copy-mode-vi r { send-keys -X cancel ; send-keys -- 'r' }
-bind -T copy-mode    s { send-keys -X cancel ; send-keys -- 's' }
-bind -T copy-mode-vi s { send-keys -X cancel ; send-keys -- 's' }
-bind -T copy-mode    t { send-keys -X cancel ; send-keys -- 't' }
-bind -T copy-mode-vi t { send-keys -X cancel ; send-keys -- 't' }
-bind -T copy-mode    u { send-keys -X cancel ; send-keys -- 'u' }
-bind -T copy-mode-vi u { send-keys -X cancel ; send-keys -- 'u' }
-bind -T copy-mode    v { send-keys -X cancel ; send-keys -- 'v' }
-bind -T copy-mode-vi v { send-keys -X cancel ; send-keys -- 'v' }
-bind -T copy-mode    w { send-keys -X cancel ; send-keys -- 'w' }
-bind -T copy-mode-vi w { send-keys -X cancel ; send-keys -- 'w' }
-bind -T copy-mode    x { send-keys -X cancel ; send-keys -- 'x' }
-bind -T copy-mode-vi x { send-keys -X cancel ; send-keys -- 'x' }
-bind -T copy-mode    y { send-keys -X cancel ; send-keys -- 'y' }
-bind -T copy-mode-vi y { send-keys -X cancel ; send-keys -- 'y' }
-bind -T copy-mode    z { send-keys -X cancel ; send-keys -- 'z' }
-bind -T copy-mode-vi z { send-keys -X cancel ; send-keys -- 'z' }
-bind -T copy-mode    A { send-keys -X cancel ; send-keys -- 'A' }
-bind -T copy-mode-vi A { send-keys -X cancel ; send-keys -- 'A' }
-bind -T copy-mode    B { send-keys -X cancel ; send-keys -- 'B' }
-bind -T copy-mode-vi B { send-keys -X cancel ; send-keys -- 'B' }
-bind -T copy-mode    C { send-keys -X cancel ; send-keys -- 'C' }
-bind -T copy-mode-vi C { send-keys -X cancel ; send-keys -- 'C' }
-bind -T copy-mode    D { send-keys -X cancel ; send-keys -- 'D' }
-bind -T copy-mode-vi D { send-keys -X cancel ; send-keys -- 'D' }
-bind -T copy-mode    E { send-keys -X cancel ; send-keys -- 'E' }
-bind -T copy-mode-vi E { send-keys -X cancel ; send-keys -- 'E' }
-bind -T copy-mode    F { send-keys -X cancel ; send-keys -- 'F' }
-bind -T copy-mode-vi F { send-keys -X cancel ; send-keys -- 'F' }
-bind -T copy-mode    G { send-keys -X cancel ; send-keys -- 'G' }
-bind -T copy-mode-vi G { send-keys -X cancel ; send-keys -- 'G' }
-bind -T copy-mode    H { send-keys -X cancel ; send-keys -- 'H' }
-bind -T copy-mode-vi H { send-keys -X cancel ; send-keys -- 'H' }
-bind -T copy-mode    I { send-keys -X cancel ; send-keys -- 'I' }
-bind -T copy-mode-vi I { send-keys -X cancel ; send-keys -- 'I' }
-bind -T copy-mode    J { send-keys -X cancel ; send-keys -- 'J' }
-bind -T copy-mode-vi J { send-keys -X cancel ; send-keys -- 'J' }
-bind -T copy-mode    K { send-keys -X cancel ; send-keys -- 'K' }
-bind -T copy-mode-vi K { send-keys -X cancel ; send-keys -- 'K' }
-bind -T copy-mode    L { send-keys -X cancel ; send-keys -- 'L' }
-bind -T copy-mode-vi L { send-keys -X cancel ; send-keys -- 'L' }
-bind -T copy-mode    M { send-keys -X cancel ; send-keys -- 'M' }
-bind -T copy-mode-vi M { send-keys -X cancel ; send-keys -- 'M' }
-bind -T copy-mode    N { send-keys -X cancel ; send-keys -- 'N' }
-bind -T copy-mode-vi N { send-keys -X cancel ; send-keys -- 'N' }
-bind -T copy-mode    O { send-keys -X cancel ; send-keys -- 'O' }
-bind -T copy-mode-vi O { send-keys -X cancel ; send-keys -- 'O' }
-bind -T copy-mode    P { send-keys -X cancel ; send-keys -- 'P' }
-bind -T copy-mode-vi P { send-keys -X cancel ; send-keys -- 'P' }
-bind -T copy-mode    Q { send-keys -X cancel ; send-keys -- 'Q' }
-bind -T copy-mode-vi Q { send-keys -X cancel ; send-keys -- 'Q' }
-bind -T copy-mode    R { send-keys -X cancel ; send-keys -- 'R' }
-bind -T copy-mode-vi R { send-keys -X cancel ; send-keys -- 'R' }
-bind -T copy-mode    S { send-keys -X cancel ; send-keys -- 'S' }
-bind -T copy-mode-vi S { send-keys -X cancel ; send-keys -- 'S' }
-bind -T copy-mode    T { send-keys -X cancel ; send-keys -- 'T' }
-bind -T copy-mode-vi T { send-keys -X cancel ; send-keys -- 'T' }
-bind -T copy-mode    U { send-keys -X cancel ; send-keys -- 'U' }
-bind -T copy-mode-vi U { send-keys -X cancel ; send-keys -- 'U' }
-bind -T copy-mode    V { send-keys -X cancel ; send-keys -- 'V' }
-bind -T copy-mode-vi V { send-keys -X cancel ; send-keys -- 'V' }
-bind -T copy-mode    W { send-keys -X cancel ; send-keys -- 'W' }
-bind -T copy-mode-vi W { send-keys -X cancel ; send-keys -- 'W' }
-bind -T copy-mode    X { send-keys -X cancel ; send-keys -- 'X' }
-bind -T copy-mode-vi X { send-keys -X cancel ; send-keys -- 'X' }
-bind -T copy-mode    Y { send-keys -X cancel ; send-keys -- 'Y' }
-bind -T copy-mode-vi Y { send-keys -X cancel ; send-keys -- 'Y' }
-bind -T copy-mode    Z { send-keys -X cancel ; send-keys -- 'Z' }
-bind -T copy-mode-vi Z { send-keys -X cancel ; send-keys -- 'Z' }
-bind -T copy-mode    0 { send-keys -X cancel ; send-keys -- '0' }
-bind -T copy-mode-vi 0 { send-keys -X cancel ; send-keys -- '0' }
-bind -T copy-mode    1 { send-keys -X cancel ; send-keys -- '1' }
-bind -T copy-mode-vi 1 { send-keys -X cancel ; send-keys -- '1' }
-bind -T copy-mode    2 { send-keys -X cancel ; send-keys -- '2' }
-bind -T copy-mode-vi 2 { send-keys -X cancel ; send-keys -- '2' }
-bind -T copy-mode    3 { send-keys -X cancel ; send-keys -- '3' }
-bind -T copy-mode-vi 3 { send-keys -X cancel ; send-keys -- '3' }
-bind -T copy-mode    4 { send-keys -X cancel ; send-keys -- '4' }
-bind -T copy-mode-vi 4 { send-keys -X cancel ; send-keys -- '4' }
-bind -T copy-mode    5 { send-keys -X cancel ; send-keys -- '5' }
-bind -T copy-mode-vi 5 { send-keys -X cancel ; send-keys -- '5' }
-bind -T copy-mode    6 { send-keys -X cancel ; send-keys -- '6' }
-bind -T copy-mode-vi 6 { send-keys -X cancel ; send-keys -- '6' }
-bind -T copy-mode    7 { send-keys -X cancel ; send-keys -- '7' }
-bind -T copy-mode-vi 7 { send-keys -X cancel ; send-keys -- '7' }
-bind -T copy-mode    8 { send-keys -X cancel ; send-keys -- '8' }
-bind -T copy-mode-vi 8 { send-keys -X cancel ; send-keys -- '8' }
-bind -T copy-mode    9 { send-keys -X cancel ; send-keys -- '9' }
-bind -T copy-mode-vi 9 { send-keys -X cancel ; send-keys -- '9' }
-bind -T copy-mode    Enter { send-keys -X cancel ; send-keys Enter }
-bind -T copy-mode-vi Enter { send-keys -X cancel ; send-keys Enter }
-bind -T copy-mode    BSpace { send-keys -X cancel ; send-keys BSpace }
-bind -T copy-mode-vi BSpace { send-keys -X cancel ; send-keys BSpace }

web/src/App.tsx

@@ -14,7 +14,7 @@ import Locked from './components/Locked';
 import Welcome from './components/Welcome';
 import * as api from './api';
 import type { Cli, GridSpec, MoveTarget, OverviewFilter, Session, Tree } from './types';
-import { isPassive } from './types';
+import { isPassive, isRemote } from './types';
 import { GridGlyph, ListGlyph } from './components/icons';
 
 // Phone-sized viewport: the app becomes two full-screen views (list ⇄ pane).
@@ -40,6 +40,7 @@ function autoGrid(n: number): GridSpec {
 
 type SettingsPage = 'general' | 'usage' | 'skills';
 const ROOT_PATH = '.';
+const WARM_TERMINAL_LIMIT = 12;
 const normalizePath = (p?: string | null) => (p && p.trim() ? p : ROOT_PATH);
 
 function initialTheme(): 'light' | 'dark' {
@@ -103,15 +104,188 @@ export default function App() {
 
   // Track the visual viewport so the mobile layout can sit above the on-screen
   // keyboard (which shrinks visualViewport but not the layout viewport on iOS).
-  // --vvh drives the mobile app height (see styles.css).
+  // The CSS variables pin the app to that viewport's exact rectangle. The Hub
+  // page embeds the app in a cross-origin iframe; mobile Safari leaves that
+  // child viewport unchanged when its keyboard opens. In that one no-signal
+  // case, fall back to a conservative focus-derived visible height.
   useEffect(() => {
     const vv = window.visualViewport;
-    if (!vv) return;
-    const apply = () => document.documentElement.style.setProperty('--vvh', `${Math.round(vv.height)}px`);
+    type VirtualKeyboardLike = EventTarget & { boundingRect?: DOMRectReadOnly };
+    const keyboard = (navigator as Navigator & { virtualKeyboard?: VirtualKeyboardLike }).virtualKeyboard;
+    type ViewportBaseline = {
+      width: number;
+      height: number;
+      top: number;
+      innerHeight: number;
+    };
+    const root = document.documentElement;
+    const keyboardSignalThreshold = 80;
+    const embedded = window.self !== window.top;
+    let focusedInput: Element | null = null;
+    let focusBaseline: ViewportBaseline | null = null;
+    let focusFallback = false;
+    let focusFallbackTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const acceptsKeyboardInput = (target: Element | null): target is HTMLElement => {
+      if (!(target instanceof HTMLElement)) return false;
+      if (target.isContentEditable) return true;
+      if (target instanceof HTMLTextAreaElement) return !target.readOnly && !target.disabled;
+      if (!(target instanceof HTMLInputElement) || target.readOnly || target.disabled) return false;
+      return !['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit']
+        .includes(target.type);
+    };
+    const embeddedTouchLayout = () => embedded
+      && window.matchMedia('(max-width: 720px)').matches
+      && (navigator.maxTouchPoints > 0 || window.matchMedia('(pointer: coarse)').matches);
+    const captureViewport = (): ViewportBaseline => ({
+      width: vv?.width ?? document.documentElement.clientWidth,
+      height: vv?.height ?? window.innerHeight,
+      top: vv?.offsetTop ?? 0,
+      innerHeight: window.innerHeight,
+    });
+    const hasKeyboardGeometry = () => {
+      if (!focusBaseline) return false;
+      const keyboardHeight = keyboard?.boundingRect?.height ?? 0;
+      const visualHeight = vv?.height ?? window.innerHeight;
+      const visualShrink = focusBaseline.height - visualHeight;
+      const layoutShrink = focusBaseline.innerHeight - window.innerHeight;
+      return keyboardHeight >= keyboardSignalThreshold
+        || visualShrink >= keyboardSignalThreshold
+        || layoutShrink >= keyboardSignalThreshold;
+    };
+    const apply = () => {
+      const keyboardRect = keyboard?.boundingRect;
+      const left = vv?.offsetLeft ?? 0;
+      const top = vv?.offsetTop ?? 0;
+      const width = vv?.width ?? document.documentElement.clientWidth;
+      let height = vv?.height ?? window.innerHeight;
+      // Chromium can expose keyboard geometry even when an embedded document's
+      // visual viewport is unchanged. Never grow the visual viewport from it;
+      // only clip an actually overlapping keyboard.
+      if (keyboardRect && keyboardRect.height > 0 && keyboardRect.top > top) {
+        height = Math.min(height, keyboardRect.top - top);
+      }
+      if (hasKeyboardGeometry()) focusFallback = false;
+      if (focusFallback && focusBaseline && acceptsKeyboardInput(document.activeElement)) {
+        // The parent page owns the real visual viewport, but cross-origin frame
+        // isolation prevents us from reading it. A phone keyboard typically
+        // consumes roughly the lower half; 54% visible keeps the xterm prompt
+        // above it without disturbing direct-app browsers with real geometry.
+        const visibleRatio = focusBaseline.width > focusBaseline.height ? 0.48 : 0.54;
+        height = Math.min(height, Math.round(focusBaseline.height * visibleRatio));
+        root.dataset.keyboardLayout = 'focus-fallback';
+      } else if (hasKeyboardGeometry()) {
+        root.dataset.keyboardLayout = 'browser-geometry';
+      } else {
+        delete root.dataset.keyboardLayout;
+      }
+      root.style.setProperty('--vvw', `${Math.round(width)}px`);
+      root.style.setProperty('--vvh', `${Math.round(height)}px`);
+      root.style.setProperty('--vv-top', `${Math.round(top)}px`);
+      root.style.setProperty('--vv-left', `${Math.round(left)}px`);
+    };
+
+    // WebKit may dispatch the keyboard viewport event before offsetTop has its
+    // final value, then correct the property without another event. Re-read at
+    // the end of the event turn and while the focus animation settles.
+    const settleTimers = new Set<ReturnType<typeof setTimeout>>();
+    const focusTimers = new Set<ReturnType<typeof setTimeout>>();
+    const onViewportChange = () => {
+      apply();
+      for (const timer of settleTimers) clearTimeout(timer);
+      settleTimers.clear();
+      // One delayed read is still racy: WebKit can update offsetTop immediately
+      // after it fires. Sample the short animation tail without depending on a
+      // second browser event.
+      for (const delay of [50, 150, 300, 500]) {
+        const timer = setTimeout(() => { settleTimers.delete(timer); apply(); }, delay);
+        settleTimers.add(timer);
+      }
+    };
+    const stabilizeFocus = () => {
+      for (const timer of focusTimers) clearTimeout(timer);
+      focusTimers.clear();
+      for (const delay of [0, 50, 150, 300, 500, 800]) {
+        const timer = setTimeout(() => { focusTimers.delete(timer); apply(); }, delay);
+        focusTimers.add(timer);
+      }
+    };
+    const scheduleEmbeddedFallback = () => {
+      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
+      focusFallbackTimer = null;
+      if (!embeddedTouchLayout() || !acceptsKeyboardInput(document.activeElement)) return;
+      focusFallbackTimer = setTimeout(() => {
+        focusFallbackTimer = null;
+        if (document.activeElement === focusedInput && !hasKeyboardGeometry()) {
+          focusFallback = true;
+          apply();
+        }
+      }, 500);
+    };
+    const onFocusIn = (event: FocusEvent) => {
+      const target = event.target instanceof Element ? event.target : null;
+      if (acceptsKeyboardInput(target)) {
+        focusedInput = target;
+        focusBaseline = captureViewport();
+        focusFallback = false;
+        stabilizeFocus();
+        scheduleEmbeddedFallback();
+        return;
+      }
+      stabilizeFocus();
+    };
+    const onFocusOut = () => {
+      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
+      focusFallbackTimer = null;
+      const timer = setTimeout(() => {
+        focusTimers.delete(timer);
+        if (!acceptsKeyboardInput(document.activeElement)) {
+          focusedInput = null;
+          focusBaseline = null;
+          focusFallback = false;
+          apply();
+        }
+      }, 0);
+      focusTimers.add(timer);
+    };
+    const onOrientationChange = () => {
+      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
+      focusFallbackTimer = null;
+      focusFallback = false;
+      if (acceptsKeyboardInput(document.activeElement)) {
+        focusedInput = document.activeElement;
+        focusBaseline = captureViewport();
+      }
+      stabilizeFocus();
+      scheduleEmbeddedFallback();
+    };
     apply();
-    vv.addEventListener('resize', apply);
-    vv.addEventListener('scroll', apply);
-    return () => { vv.removeEventListener('resize', apply); vv.removeEventListener('scroll', apply); };
+    vv?.addEventListener('resize', onViewportChange);
+    vv?.addEventListener('scroll', onViewportChange);
+    vv?.addEventListener('scrollend', onViewportChange);
+    keyboard?.addEventListener('geometrychange', onViewportChange);
+    window.addEventListener('resize', onViewportChange);
+    window.addEventListener('orientationchange', onOrientationChange);
+    document.addEventListener('focusin', onFocusIn);
+    document.addEventListener('focusout', onFocusOut);
+    return () => {
+      for (const timer of settleTimers) clearTimeout(timer);
+      for (const timer of focusTimers) clearTimeout(timer);
+      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
+      vv?.removeEventListener('resize', onViewportChange);
+      vv?.removeEventListener('scroll', onViewportChange);
+      vv?.removeEventListener('scrollend', onViewportChange);
+      keyboard?.removeEventListener('geometrychange', onViewportChange);
+      window.removeEventListener('resize', onViewportChange);
+      window.removeEventListener('orientationchange', onOrientationChange);
+      document.removeEventListener('focusin', onFocusIn);
+      document.removeEventListener('focusout', onFocusOut);
+      root.style.removeProperty('--vvw');
+      root.style.removeProperty('--vvh');
+      root.style.removeProperty('--vv-top');
+      root.style.removeProperty('--vv-left');
+      delete root.dataset.keyboardLayout;
+    };
   }, []);
 
   // Refresh info while locked so flipping the Space to Private unlocks the UI
@@ -256,6 +430,38 @@ export default function App() {
   const visibleIds = visibleSessions.map((s) => s.id).join(',');
   const showZoom = visibleSessions.length > 0;
 
+  // Keep a small working set of terminal panes alive across navigation. The
+  // backend session already survives a viewer disconnect; retaining xterm and
+  // its socket as well makes switching back genuinely instant and preserves the
+  // exact local scroll/selection state. This is deliberately bounded: mounting
+  // every session would start stopped agents and turn a large sidebar into many
+  // live WebSockets and 20k-line browser buffers.
+  const visibleTerminalIds = (settingsOpen || (isMobile && !mobileStage) ? [] : visibleSessions)
+    .filter((s) => !isPassive(s.cli) && !isRemote(s.cli))
+    .map((s) => s.id);
+  const visibleTerminalKey = visibleTerminalIds.join(',');
+  const sessionIdsKey = tree.sessions.map((s) => s.id).join(',');
+  const [warmTerminalIds, setWarmTerminalIds] = useState<string[]>([]);
+  useEffect(() => {
+    const valid = new Set(tree.sessions
+      .filter((s) => !isPassive(s.cli) && !isRemote(s.cli))
+      .map((s) => s.id));
+    setWarmTerminalIds((previous) => {
+      const next = [...visibleTerminalIds, ...previous]
+        .filter((id, i, all) => valid.has(id) && all.indexOf(id) === i)
+        .slice(0, Math.max(WARM_TERMINAL_LIMIT, visibleTerminalIds.length));
+      return next.length === previous.length && next.every((id, i) => id === previous[i])
+        ? previous : next;
+    });
+  // Stable string keys avoid running this state update on every tree poll.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visibleTerminalKey, sessionIdsKey]);
+  // Include newly selected panes on the navigation render itself; the effect
+  // above retains them for later renders and applies the LRU bound.
+  const retainedTerminalIds = [...visibleTerminalIds, ...warmTerminalIds]
+    .filter((id, i, all) => !!sessById[id] && all.indexOf(id) === i)
+    .slice(0, Math.max(WARM_TERMINAL_LIMIT, visibleTerminalIds.length));
+
   // Pane rearrangement (drag a pane header onto another tile).
   const [paneDrag, setPaneDrag] = useState(false);
   const [overTile, setOverTile] = useState<number | null>(null);
@@ -474,21 +680,60 @@ export default function App() {
     const slotCount = activeGroup ? g.cols * g.rows : sessions.length;
     const slots = Array.from({ length: slotCount }, (_, i) => sessions[i] ?? null);
     const canDrag = !!activeGroup && groupSessions.length > 1;
+    const slotStyle = (i: number) => ({
+      gridColumn: (i % g.cols) + 1,
+      gridRow: Math.floor(i / g.cols) + 1,
+    });
+    const slotByTerminal = new Map(slots
+      .map((s, i) => [s, i] as const)
+      .filter(([s]) => s && !isPassive(s.cli) && !isRemote(s.cli))
+      .map(([s, i]) => [s!.id, i]));
+    const deckVisible = !settingsOpen && sessions.length > 0 && (!isMobile || mobileStage);
     // A sidebar session hovering a full grid still needs somewhere to land:
     // offer a ghost strip appended below the tiles.
     const ghost = sessionDragActive && !!activeGroup;
     return (
       <div
-        className={`tiles${paneDrag ? ' pane-dragging' : ''}${sessionDragActive && activeGroup ? ' session-dragging' : ''}`}
+        className={`tiles pane-deck${sessions.length ? '' : ' deck-hidden'}${paneDrag ? ' pane-dragging' : ''}${sessionDragActive && activeGroup ? ' session-dragging' : ''}`}
         style={{ gridTemplateColumns: `repeat(${g.cols}, 1fr)`, gridTemplateRows: `repeat(${g.rows}, minmax(0, 1fr))` }}
         onDragOver={activeGroup ? allowDrop : undefined}
         onDragLeave={() => setDropMain(false)}
         onDrop={activeGroup ? onDropMain : undefined}
       >
-        {slots.map((s, i) => (
+        {retainedTerminalIds.map((id) => {
+          const s = sessById[id];
+          if (!s) return null;
+          const slot = slotByTerminal.get(id);
+          const shown = slot !== undefined;
+          return (
+            <div
+              key={`terminal-${id}`}
+              className={`tile tile-terminal${shown ? '' : ' tile-cached'}`}
+              style={shown ? slotStyle(slot) : undefined}
+              {...(shown && activeGroup ? tileDnd(slot, true) : {})}
+            >
+              <TerminalPane
+                session={s}
+                cli={cliMap[s.cli]}
+                theme={theme}
+                zoom={zoom}
+                focused={shown && sessions.length > 1 && s.id === focusedId}
+                active={shown && deckVisible && s.id === focusedId}
+                dragId={shown && canDrag ? `p:${s.id}` : undefined}
+                isMobile={isMobile}
+                onDragActive={setPaneDrag}
+                onFocus={() => setFocusedId(s.id)}
+                onRename={(name) => renameSession(s.id, name)}
+                onClose={() => closePane(s.id)}
+              />
+            </div>
+          );
+        })}
+        {slots.map((s, i) => (s && !isPassive(s.cli) && !isRemote(s.cli) ? null : (
           <div
-            key={s ? s.id : `empty-${i}`}
+            key={s ? `passive-${s.id}` : `empty-${i}`}
             className={`tile${s ? '' : ' tile-empty'}${(paneDrag || sessionDragActive) && overTile === i ? ' tile-over' : ''}`}
+            style={slotStyle(i)}
             {...(activeGroup ? tileDnd(i, !!s) : {})}
           >
             {s && (s.cli === 'files' ? (
@@ -512,34 +757,19 @@ export default function App() {
                 onRename={(name) => renameSession(s.id, name)}
                 onClose={() => closePane(s.id)}
               />
-            ) : s.cli === 'trace' ? (
-              <TracePane
-                session={s}
-                zoom={zoom}
-                focused={visibleSessions.length > 1 && s.id === focusedId}
-                dragId={canDrag ? `p:${s.id}` : undefined}
-                onDragActive={setPaneDrag}
-                onFocus={() => setFocusedId(s.id)}
-                onClose={() => closePane(s.id)}
-              />
             ) : (
-              <TerminalPane
+              <TracePane
                 session={s}
-                cli={cliMap[s.cli]}
-                theme={theme}
                 zoom={zoom}
                 focused={visibleSessions.length > 1 && s.id === focusedId}
-                active={s.id === focusedId}
                 dragId={canDrag ? `p:${s.id}` : undefined}
-                isMobile={isMobile}
                 onDragActive={setPaneDrag}
                 onFocus={() => setFocusedId(s.id)}
-                onRename={(name) => renameSession(s.id, name)}
                 onClose={() => closePane(s.id)}
               />
             ))}
           </div>
-        ))}
+        )))}
         {ghost && (
           <div
             className={`tile tile-ghost${overTile === slots.length ? ' tile-over' : ''}`}
@@ -554,8 +784,9 @@ export default function App() {
 
   if (info?.locked) return <Locked spaceId={info.spaceId} reason={info.lockReason} bucket={info.lockBucket} />;
 
-  if (settingsOpen) {
-    return (
+  return (
+    <>
+      {settingsOpen && (
       <SettingsView
         page={settingsPage}
         onPage={setSettingsPage}
@@ -568,11 +799,8 @@ export default function App() {
         demoMode={!!info?.demoMode}
         onToggleDemo={toggleDemo}
       />
-    );
-  }
-
-  return (
-    <div className={`app${isMobile ? (mobileStage ? ' m-stage' : ' m-home') : ''}`}>
+      )}
+    <div className={`app${settingsOpen ? ' app-suspended' : ''}${isMobile ? (mobileStage ? ' m-stage' : ' m-home') : ''}`}>
       {showWelcome && <Welcome onClose={dismissWelcome} />}
       {toast && <div className="toast mono" role="alert">{toast}</div>}
       {shareId && sessById[shareId] && (
@@ -658,6 +886,14 @@ export default function App() {
           </div>
         )}
         <div className="stage">
+          {renderTiles(
+            isMobile && !mobileStage
+              ? []
+              : activeGroup && groupSessions.length > 0
+              ? pageSessions
+              : activeSingle ? [activeSingle] : [],
+            activeGroup && groupSessions.length > 0 ? grid : { cols: 1, rows: 1 },
+          )}
           {activeRef === 'overview' ? (
             <Overview
               clis={clis}
@@ -674,8 +910,7 @@ export default function App() {
                 openSession(sid, g?.id);
               }}
             />
-          ) : activeGroup ? (
-            groupSessions.length === 0 ? (
+          ) : activeGroup && groupSessions.length === 0 ? (
               <div
                 className={`empty-group${dropMain ? ' drop-over' : ''}`}
                 onDragOver={allowDrop}
@@ -688,17 +923,14 @@ export default function App() {
                   <div className="dropline">drop an agent here to add it to this group</div>
                 </div>
               </div>
-            ) : renderTiles(pageSessions, grid)
-          ) : activeSingle ? (
-            renderTiles([activeSingle], { cols: 1, rows: 1 })
-          ) : (
+          ) : !activeGroup && !activeSingle ? (
             <div className="empty-group">
               <EmptyPrompt
                 path="workspaces"
                 hints={['create an agent or a group from the sidebar', 'drag an agent onto another to group them']}
               />
             </div>
-          )}
+          ) : null}
         </div>
         {activeRef === 'overview' && (
           <div className="zoombar ov-bar">
@@ -735,5 +967,6 @@ export default function App() {
         )}
       </div>
     </div>
+    </>
   );
 }

web/src/components/SettingsView.tsx

@@ -13,7 +13,7 @@ const PAGES: { id: Page; label: string }[] = [
   { id: 'skills', label: 'Skills' },
 ];
 
-interface Info { dataDir?: string; home?: string; spaceId?: string | null; spaceHost?: string | null; tmux?: boolean; canRelaunch?: boolean; secrets?: string[]; bucketUnverified?: boolean; }
+interface Info { dataDir?: string; home?: string; spaceId?: string | null; spaceHost?: string | null; engine?: string; ghostty?: boolean; canRelaunch?: boolean; secrets?: string[]; bucketUnverified?: boolean; }
 
 function urlBase64ToUint8Array(base64: string) {
   const padding = '='.repeat((4 - (base64.length % 4)) % 4);
@@ -446,7 +446,7 @@ export default function SettingsView({
               <div><span>Space</span><b>{info?.spaceId || '—'}</b></div>
               <div><span>Durable storage</span><b className="mono">{info?.dataDir || '—'}</b></div>
               <div><span>Home</span><b className="mono">{info?.home || '—'}</b></div>
-              <div><span>tmux</span><b>{info?.tmux ? 'on' : 'off'}</b></div>
+              <div><span>terminal</span><b>{info?.ghostty ? 'libghostty' : 'unavailable'}</b></div>
             </div>
 
           </div>

web/src/components/TerminalPane.tsx

@@ -31,29 +31,21 @@ const THEMES: Record<'light' | 'dark', ITheme> = {
   },
 };
 
-type ConnState = 'connecting' | 'connected' | 'closed' | 'exited' | 'handedoff';
+type ConnState = 'connecting' | 'connected' | 'closed' | 'exited';
 
 // Close code the server uses when the session's process exited for real (vs a
 // transient drop). The client must NOT auto-reconnect on this, or it would
 // respawn the agent in a loop and trample an in-progress login flow.
 const EXIT_CODE = 4000;
 
-// Close code for "another device took this session over" (tmux attaches with
-// -D, so only one client drives a session at a time). The session is still
-// running: we must not reconnect on a timer, or this pane and the phone would
-// pull the session back and forth. We wait for the user to come back here.
-const HANDOFF_CODE = 4001;
-
 function workspaceLabel(p: string | null) {
   const rel = (p || '').replace(/^\.\/?/, '').replace(/^\/+|\/+$/g, '');
   return rel ? `workspace/${rel}/` : 'workspace/';
 }
 
 // Serialize the current selection, joining soft-wrapped rows instead of
-// emitting a newline per visual row. tmux repaints with explicit cursor moves,
-// so a wrapped logical line arrives as separate full-width rows that xterm's
-// default getSelection() would break with '\n'. We rejoin a row to the next
-// when xterm flags it wrapped OR it's filled to the last column (the tmux case).
+// emitting a newline per visual row. Some full-width rows painted with cursor
+// movement lack xterm's wrap flag, so a filled last cell is a second signal.
 function selectionText(term: Terminal): string {
   try {
     const pos = term.getSelectionPosition?.();
@@ -92,20 +84,56 @@ function selectionText(term: Terminal): string {
 //      and flush on the user's next click, so the copy lands when they return.
 // It must run synchronously inside the triggering event — deferring to a
 // setTimeout loses the activation that execCommand needs.
-const OSC52_COPY_WINDOW_MS = 1500;
-// Server → client control frames (copy-mode state) ride the terminal socket
-// with this leading NUL sentinel, which real pty output never begins with.
+// Server → client control frames (restore, shared-grid size) ride the terminal
+// socket with this leading NUL sentinel, which real pty output never begins with.
 const MODE_CTRL = '\x00\x00AM:';
-let osc52CopyAllowedUntil = 0;
 
-function allowNextOsc52Copy() {
-  osc52CopyAllowedUntil = Date.now() + OSC52_COPY_WINDOW_MS;
+type TerminalPreview = { version: 1; at: number; cols: number; rows: string[] };
+const PREVIEW_PREFIX = 'am-terminal-preview:';
+const PREVIEW_INDEX = 'am-terminal-preview-index';
+const MAX_PREVIEWS = 12;
+
+function loadTerminalPreview(id: string): TerminalPreview | null {
+  try {
+    const parsed = JSON.parse(localStorage.getItem(`${PREVIEW_PREFIX}${id}`) || 'null');
+    if (parsed?.version !== 1 || !Array.isArray(parsed.rows)
+        || !parsed.rows.some((line: unknown) => typeof line === 'string' && line.trim())) return null;
+    return {
+      version: 1,
+      at: Number(parsed.at) || 0,
+      cols: Math.max(1, Number(parsed.cols) || 80),
+      rows: parsed.rows.filter((line: unknown) => typeof line === 'string').slice(0, 80),
+    };
+  } catch { return null; }
 }
 
-function consumeOsc52CopyPermission(): boolean {
-  if (Date.now() > osc52CopyAllowedUntil) return false;
-  osc52CopyAllowedUntil = 0;
-  return true;
+// Keep only a compact rendering of the viewport, never the full 20k-line
+// scrollback. It is a loading preview, not a second terminal state model.
+function saveTerminalPreview(id: string, term: Terminal) {
+  try {
+    const buffer = term.buffer.active;
+    const rowCount = Math.min(term.rows, 80);
+    const colCount = Math.min(term.cols, 240);
+    const rows: string[] = [];
+    for (let y = 0; y < rowCount; y++) {
+      const line = buffer.getLine(buffer.viewportY + y);
+      rows.push((line?.translateToString(false, 0, colCount) || '').replace(/[ \t]+$/, ''));
+    }
+    if (!rows.some((line) => line.trim())) return;
+    const saved: TerminalPreview = { version: 1, at: Date.now(), cols: term.cols, rows };
+    localStorage.setItem(`${PREVIEW_PREFIX}${id}`, JSON.stringify(saved));
+
+    let previous: string[] = [];
+    try { previous = JSON.parse(localStorage.getItem(PREVIEW_INDEX) || '[]'); } catch {}
+    const next = [id, ...previous].filter((value, i, all) =>
+      typeof value === 'string' && all.indexOf(value) === i).slice(0, MAX_PREVIEWS);
+    localStorage.setItem(PREVIEW_INDEX, JSON.stringify(next));
+    for (const stale of previous) {
+      if (typeof stale === 'string' && !next.includes(stale)) {
+        localStorage.removeItem(`${PREVIEW_PREFIX}${stale}`);
+      }
+    }
+  } catch { /* storage may be disabled or full; previews are best-effort */ }
 }
 
 function legacyCopy(text: string): boolean {
@@ -164,20 +192,24 @@ export default function TerminalPane({
   onClose: () => void;
 }) {
   const hostRef = useRef<HTMLDivElement>(null);
+  const frameRef = useRef<HTMLDivElement>(null);
   const termRef = useRef<Terminal | null>(null);
   const resyncRef = useRef<() => void>(() => {});
+  const claimRef = useRef<() => void>(() => {});
   const reconnectRef = useRef<() => void>(() => {});
-  // Take a handed-off session back (bound inside the connection effect).
-  const resumeRef = useRef<() => void>(() => {});
+  const controllerRef = useRef(false);
+  const previousZoomRef = useRef(zoom);
+  const [preview] = useState<TerminalPreview | null>(() => loadTerminalPreview(session.id));
   // Send a raw byte string to the PTY (for the mobile key-bar: arrows, Esc…).
   const sendKeyRef = useRef<(d: string) => void>(() => {});
   const [conn, setConn] = useState<ConnState>('connecting');
-  // "starting…" cover while the CLI boots into an empty pane (attach on the
+  // "starting…" cover while the CLI boots into an empty pane (starting on the
   // Space can take seconds). Hidden only when the screen actually SHOWS
-  // something — byte counts lie, because tmux's attach repaint of a blank
-  // 200×50 screen is already kilobytes of escapes.
+  // something — byte counts lie because a blank-screen repaint can already be
+  // kilobytes of escape sequences.
   const [booting, setBooting] = useState(true);
-  const [copyMode, setCopyMode] = useState(false); // tmux copy/scrollback mode
+  const [controller, setController] = useState(false);
+  const [viewers, setViewers] = useState(1);
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState(session.name);
   // Fallback paste sheet: shown only when we can't read the clipboard directly.
@@ -219,34 +251,33 @@ export default function TerminalPane({
   useEffect(() => {
     const term = new Terminal({
       fontFamily: "'Geist Mono', ui-monospace, 'SF Mono', Menlo, 'Cascadia Code', monospace",
-      fontSize: 13,
+      // Start at the requested zoom so attachment does not briefly create a
+      // 100% grid and then force an avoidable reflow as the session boots.
+      fontSize: Math.round((13 * zoom) / 100),
       cursorBlink: true,
       scrollback: 20000,
       theme: THEMES[theme],
-      // Let users make a *local* selection even when the app (tmux / an agent
-      // TUI) has grabbed the mouse: ⌥-drag on macOS, Shift-drag elsewhere.
+      // Let users make a local selection even when an agent TUI has grabbed
+      // the mouse: ⌥-drag on macOS, Shift-drag elsewhere.
       macOptionClickForcesSelection: true,
     });
     const fit = new FitAddon();
     term.loadAddon(fit);
 
     let lastSelection = '';
-    let tmuxSelectionPending = false;
-    let tmuxSelectionText = '';
-    let tmuxSelectionAt = 0;
+    let osc52Text = '';
+    let osc52At = 0;
 
-    // tmux emits OSC 52 when copy-mode commits a mouse selection. Do not write
-    // the system clipboard there; stash the decoded text and wait for Cmd/C.
+    // An agent may deliberately emit OSC 52. Browsers generally reject an
+    // unsolicited clipboard write, so retain it briefly and let Cmd/C perform
+    // the write inside a real user gesture.
     const clipboardProvider = {
       readText: (sel: string) => (sel !== 'p' && navigator.clipboard?.readText ? navigator.clipboard.readText().catch(() => '') : ''),
       writeText: (sel: string, data: string) => {
-        const allowed = sel !== 'p' && consumeOsc52CopyPermission();
         if (sel !== 'p') {
-          tmuxSelectionText = data;
-          tmuxSelectionAt = Date.now();
-          tmuxSelectionPending = true;
+          osc52Text = data;
+          osc52At = Date.now();
         }
-        if (allowed) copyText(data);
       },
     };
     // addon-clipboard@0.1.0 has a (base64, provider) runtime constructor but
@@ -254,107 +285,122 @@ export default function TerminalPane({
     term.loadAddon(new (ClipboardAddon as unknown as new (b: Base64, p: typeof clipboardProvider) => ClipboardAddon)(new Base64(), clipboardProvider));
     term.open(hostRef.current!);
     termRef.current = term;
+    const host = hostRef.current!;
+
+    let previewTimer: ReturnType<typeof setTimeout> | null = null;
+    const persistPreview = () => {
+      if (previewTimer) { clearTimeout(previewTimer); previewTimer = null; }
+      saveTerminalPreview(session.id, term);
+    };
+    const schedulePreview = () => {
+      // Preview serialization reads every visible buffer row and writes
+      // localStorage synchronously. Debounce until output/scrolling is idle so
+      // it never lands in the middle of a mobile drag.
+      if (previewTimer) clearTimeout(previewTimer);
+      previewTimer = setTimeout(persistPreview, 700);
+    };
+
+    // xterm deliberately parks its real textarea far off-screen. That is fine
+    // with a hardware keyboard, but a mobile browser (especially a Space inside
+    // a cross-origin iframe) has no visible focus target to pan above the OSK.
+    // Keep the still-transparent 1px input at the bottom of the terminal so the
+    // browser's native focused-element avoidance can cross the iframe boundary.
+    const mobileInput = isMobile
+      ? host.querySelector<HTMLTextAreaElement>('.xterm-helper-textarea')
+      : null;
+    const anchorMobileInput = () => {
+      if (!mobileInput) return;
+      // xterm rewrites left/top whenever its cursor moves. Custom properties
+      // survive those writes and feed the mobile !important rules in CSS.
+      mobileInput.style.setProperty('--am-input-left', `${Math.max(1, Math.round(host.clientWidth / 2))}px`);
+      mobileInput.style.setProperty('--am-input-top', `${Math.max(1, host.clientHeight - 12)}px`);
+    };
+    anchorMobileInput();
+
+    // Track the user's semantic scroll state independently of the viewport's
+    // pixel scrollTop. During a row-count change xterm can transiently report
+    // the old pixel position against the new scroll height.
+    let followingBottom = true;
+    const scrollSub = term.onScroll(() => {
+      followingBottom = term.buffer.active.viewportY >= term.buffer.active.baseY;
+      schedulePreview();
+    });
 
     // Track the committed local xterm selection so Cmd/Ctrl+C can copy it
     // synchronously — deferring (setTimeout) would break execCommand's gesture.
     const selSub = term.onSelectionChange(() => {
       lastSelection = term.hasSelection() ? selectionText(term) : '';
-      if (lastSelection) tmuxSelectionPending = false;
     });
     const copySelection = () => {
       const text = term.hasSelection() ? selectionText(term) : lastSelection;
       if (text) copyText(text);
     };
-    const copyTmuxSelection = (e?: ClipboardEvent): boolean => {
-      const fresh = tmuxSelectionText && Date.now() - tmuxSelectionAt < 120_000;
-      if (!tmuxSelectionPending || !fresh) return false;
-      if (e?.clipboardData) {
-        e.clipboardData.setData('text/plain', tmuxSelectionText);
-        e.preventDefault();
-        e.stopPropagation();
-      } else {
-        copyText(tmuxSelectionText);
-      }
-      return true;
-    };
-    const host = hostRef.current!;
-    let mouseDragStart: { x: number; y: number } | null = null;
-    let mouseDragged = false;
-    const onPointerDown = (e: PointerEvent) => {
-      takeBack(); // clicking into a handed-off pane means "I'm working here now"
-      if (e.pointerType !== 'mouse' || e.button !== 0) return;
-      mouseDragStart = { x: e.clientX, y: e.clientY };
-      mouseDragged = false;
-    };
-    const onPointerMove = (e: PointerEvent) => {
-      if (!mouseDragStart || (e.buttons & 1) === 0) return;
-      if (Math.abs(e.clientX - mouseDragStart.x) > 3 || Math.abs(e.clientY - mouseDragStart.y) > 3) mouseDragged = true;
-    };
-    const onPointerUp = (e: PointerEvent) => {
-      if (e.pointerType !== 'mouse' || e.button !== 0) return;
-      if (mouseDragged && !term.hasSelection()) {
-        tmuxSelectionPending = true;
-      } else if (!term.hasSelection()) {
-        tmuxSelectionPending = false;
-      }
-      mouseDragStart = null;
-      mouseDragged = false;
-    };
-    const onClick = (e: MouseEvent) => {
-      if (e.detail >= 2 && !term.hasSelection()) {
-        tmuxSelectionPending = true;
-      }
-    };
-    host.addEventListener('pointerdown', onPointerDown, true);
-    host.addEventListener('pointermove', onPointerMove, true);
-    host.addEventListener('pointerup', onPointerUp, true);
-    host.addEventListener('click', onClick, true);
-
-    const onDocumentPointerDown = (e: PointerEvent) => {
-      if (!host.contains(e.target as Node)) tmuxSelectionPending = false;
-    };
     const onCopy = (e: ClipboardEvent) => {
-      copyTmuxSelection(e);
+      if (!term.hasSelection()) return;
+      const text = selectionText(term);
+      if (!text || !e.clipboardData) return;
+      e.clipboardData.setData('text/plain', text);
+      e.preventDefault();
     };
-    document.addEventListener('pointerdown', onDocumentPointerDown, true);
     document.addEventListener('copy', onCopy, true);
 
     let ws: WebSocket | null = null;
     const send = (o: unknown) => {
       if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(o));
     };
+    const claimControl = () => {
+      if (controllerRef.current) return;
+      // Activation can precede WebSocket.open when a pane is first mounted.
+      // Do not consume that claim locally: onopen will retry it once it can
+      // actually reach the server.
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      // Optimistic locally so the input event following this gesture is not
+      // dropped. WebSocket ordering guarantees claim reaches the server first.
+      controllerRef.current = true;
+      setController(true);
+      send({ t: 'claim' });
+    };
+    claimRef.current = claimControl;
+    const onPointerDown = (e: PointerEvent) => {
+      // A touch may only be inspecting local scrollback. Claim lazily below if
+      // the gesture actually needs to drive an application's mouse mode.
+      if (e.pointerType !== 'touch') claimControl();
+    };
+    const onPaste = () => claimControl();
+    host.addEventListener('pointerdown', onPointerDown, true);
+    host.addEventListener('paste', onPaste, true);
+
     // The mobile key-bar sends control sequences the on-screen keyboard can't.
-    sendKeyRef.current = (d: string) => { send({ t: 'i', d }); endBoot(); };
+    sendKeyRef.current = (d: string) => {
+      claimControl();
+      send({ t: 'i', d });
+      endBoot();
+    };
 
-    // ⌘/Ctrl+C copies selected text. With a tmux mouse selection, ask the server
-    // to run tmux's copy command; the resulting OSC 52 is accepted only because
-    // it follows this key gesture. Paste is left to xterm's native handler so
-    // bracketed-paste framing is preserved.
+    // ⌘/Ctrl+C copies a local selection. Without one, Ctrl+C remains SIGINT;
+    // Cmd+C may accept a recent OSC 52 payload deliberately emitted by the app.
     term.attachCustomKeyEventHandler((e) => {
       if (e.type !== 'keydown') return true;
       if ((e.metaKey || e.ctrlKey) && (e.key === 'c' || e.key === 'C') && term.hasSelection()) {
         copySelection();
         term.clearSelection();
-        tmuxSelectionPending = false;
         return false;
       }
-      if ((e.metaKey || e.ctrlKey) && (e.key === 'c' || e.key === 'C') && tmuxSelectionPending) {
-        if (!copyTmuxSelection()) {
-          allowNextOsc52Copy();
-          send({ t: 'copy' });
-        }
+      if (e.metaKey && (e.key === 'c' || e.key === 'C')) {
+        if (osc52Text && Date.now() - osc52At < 120_000) copyText(osc52Text);
         return false;
       }
-      if (e.metaKey && (e.key === 'c' || e.key === 'C')) return false;
-      if (e.key === 'Escape') tmuxSelectionPending = false;
+      claimControl();
       return true;
     });
+    // The only local fit: this terminal is still empty, so there is no buffer to
+    // reflow, and it gives the initial size we open the socket with. Every later
+    // size change goes through resync() as a REQUEST — see there.
     try { fit.fit(); } catch { /* layout not ready yet */ }
     // Re-measure once the webfont is ready (glyph width changes vs the fallback).
-    document.fonts?.ready.then(() => { try { fit.fit(); } catch { /* ignore */ } });
+    document.fonts?.ready.then(() => resync());
 
     let closedByUs = false;
-    let handedOff = false;
     let retry: ReturnType<typeof setTimeout> | null = null;
     // Reconnect with backoff: a sleeping/unreachable Space shouldn't be hammered
     // every second by every open pane. Reset once a connection succeeds.
@@ -385,11 +431,17 @@ export default function TerminalPane({
       setBooting(false);
     };
     const connect = () => {
+      controllerRef.current = false;
+      setController(false);
       setConn('connecting');
-      setBooting(true);
-      bootLive = true;
+      // A reconnect keeps the already-rendered xterm visible. On a fresh page,
+      // `booting` instead exposes the saved preview until canonical restore has
+      // painted real content.
+      const needsCover = !screenHasContent();
+      setBooting(needsCover);
+      bootLive = needsCover;
       if (bootTimer) clearTimeout(bootTimer);
-      bootTimer = setTimeout(endBoot, 20_000);
+      bootTimer = needsCover ? setTimeout(endBoot, 20_000) : null;
       const proto = location.protocol === 'https:' ? 'wss' : 'ws';
       const url = `${proto}://${location.host}/ws?session=${encodeURIComponent(session.id)}&cols=${term.cols}&rows=${term.rows}`;
       ws = new WebSocket(url);
@@ -397,18 +449,56 @@ export default function TerminalPane({
       ws.onopen = () => {
         setConn('connected');
         retryDelay = 1200;
-        try { fit.fit(); } catch { /* ignore */ }
-        send({ t: 'r', cols: term.cols, rows: term.rows });
+        // Selecting a terminal is an explicit foreground action on mobile.
+        // Claim before reporting its fit so an already-open desktop does not
+        // leave the phone rendering a clipped desktop-sized canonical grid.
+        if (isMobile && !document.hidden) claimControl();
+        requestSize();
       };
       ws.onmessage = (e) => {
         const d = typeof e.data === 'string' ? e.data : new Uint8Array(e.data as ArrayBuffer);
-        // Control frame (copy-mode changes): a leading NUL sentinel that raw
-        // pty output never produces — handle it instead of writing to the term.
+        // Control frame: a leading NUL sentinel that raw pty output never
+        // produces — handle it instead of writing to the term.
         if (typeof d === 'string' && d.startsWith(MODE_CTRL)) {
-          try { const m = JSON.parse(d.slice(MODE_CTRL.length)); if (m.t === 'mode') setCopyMode(!!m.copy); } catch { /* ignore */ }
+          try {
+            const m = JSON.parse(d.slice(MODE_CTRL.length));
+            if (m.t === 'grid' || m.t === 'restore') {
+              controllerRef.current = !!m.controller;
+              setController(!!m.controller);
+              setViewers(Math.max(1, Number(m.viewers) || 1));
+              const applyGrid = () => {
+                try {
+                  // xterm can retain the old pixel scrollTop when the viewport
+                  // gains rows (notably landscape -> portrait), which leaves a
+                  // formerly-live view stranded in history. Preserve the
+                  // semantic bottom anchor without disturbing someone who is
+                  // deliberately reading scrollback.
+                  const wasAtBottom = m.reset || followingBottom;
+                  if (m.reset) {
+                    term.reset();
+                    term.clear();
+                  }
+                  if (m.cols > 0 && m.rows > 0 && (term.cols !== m.cols || term.rows !== m.rows)) {
+                    term.resize(m.cols, m.rows);
+                  }
+                  if (wasAtBottom) {
+                    term.scrollToBottom();
+                    followingBottom = true;
+                  }
+                  schedulePreview();
+                } catch { /* ignore */ }
+              };
+              // Writes are asynchronous. A queued empty write is a barrier so
+              // resize/reset cannot reinterpret bytes from the preceding grid.
+              const geometryChanged = m.cols > 0 && m.rows > 0
+                && (term.cols !== m.cols || term.rows !== m.rows);
+              if (m.reset || geometryChanged) term.write('', applyGrid);
+              else applyGrid();
+            }
+          } catch { /* ignore */ }
           return;
         }
-        term.write(d);
+        term.write(d, schedulePreview);
         // Probe shortly after each burst (throttled; write() is async).
         if (bootLive && !bootCheck) {
           bootCheck = setTimeout(() => {
@@ -420,12 +510,9 @@ export default function TerminalPane({
       ws.onclose = (e) => {
         // A real process exit: stop here and let the user relaunch. Anything
         // else is a transient drop (sleep/wake, network) → auto-reconnect and
-        // reattach to the still-running tmux session.
+        // reattach to the still-running backend session.
         endBoot();
         if (e.code === EXIT_CODE) { setConn('exited'); return; }
-        // Another device took over: stay detached (no retry timer) until the
-        // user deliberately comes back to this pane — see takeBack().
-        if (e.code === HANDOFF_CODE) { handedOff = true; setConn('handedoff'); return; }
         setConn('closed');
         if (!closedByUs) {
           retry = setTimeout(connect, retryDelay);
@@ -435,77 +522,149 @@ export default function TerminalPane({
       ws.onerror = () => { try { ws?.close(); } catch { /* ignore */ } };
     };
     // Manual restart: clear the dead run's screen so the content probe watches
-    // the NEW process paint, not leftovers (tmux repaints the live screen).
+    // the new process paint, not leftovers.
     reconnectRef.current = () => { if (retry) clearTimeout(retry); retryDelay = 1200; try { term.reset(); } catch { /* ignore */ } connect(); };
 
-    // Take the session back from whichever device holds it now. Called ONLY for
-    // a deliberate return to this pane — the tab regaining focus/visibility, or
-    // a tap/click in the terminal — never on a timer, so the phone we just put
-    // down keeps the session while it sits in the background. Reattaching sizes
-    // tmux to this device, which is the point: each device gets a window that
-    // fits it, at the cost of one reflow per handover instead of per glance.
-    const takeBack = () => {
-      if (!handedOff || document.hidden) return false;
-      handedOff = false;
-      connect();
-      return true;
+    // Report the pane's preferred size without locally fitting its terminal.
+    // Only the current controller's preference changes the canonical grid;
+    // watchers retain theirs for a future claim.
+    let resyncTimer: ReturnType<typeof setTimeout> | null = null;
+    const requestSize = () => {
+      const box = hostRef.current;
+      if (!box || box.clientWidth < 40 || box.clientHeight < 40) return;
+      try {
+        const d = fit.proposeDimensions();
+        const cols = d ? Math.max(1, d.cols) : 0;
+        const rows = d ? Math.max(1, d.rows) : 0;
+        if (cols > 0 && rows > 0) send({ t: 'r', cols, rows });
+      } catch { /* layout not ready */ }
     };
-    resumeRef.current = () => { takeBack(); };
-
-    // Re-fit and tell the server our size. The attached client owns the tmux
-    // window, so this keeps it fitting this device exactly instead of leaving
-    // tmux's "dots" filler. Never reconnects: a layout change (another pane
-    // opening, the sidebar toggling) is not a reason to pull a session off the
-    // device the user is actually holding.
+    // ResizeObserver fires every frame while a window is dragged or the sidebar
+    // animates. Ask once, when it stops.
     const resync = () => {
-      if (handedOff) return;
-      try { fit.fit(); send({ t: 'r', cols: term.cols, rows: term.rows }); } catch { /* ignore */ }
+      anchorMobileInput();
+      if (resyncTimer) clearTimeout(resyncTimer);
+      resyncTimer = setTimeout(() => { resyncTimer = null; requestSize(); }, 80);
     };
-    // Returning to this tab IS deliberate — take the session back, or just
-    // re-sync the size if we still hold it.
-    const onReturn = () => { if (!takeBack()) resync(); };
+    resyncRef.current = resync;
+    const onReturn = () => resync();
     const onVisible = () => { if (!document.hidden) onReturn(); };
-    resyncRef.current = resync; // so the zoom control can refit
-
     // Typing means the user sees enough to interact — drop the boot cover.
     // Real keystrokes only (onKey): onData ALSO fires for xterm's automatic
     // replies to the TUI's terminal queries (DA/CPR), which arrive instantly
     // on attach and must not count as "the user typed".
-    const keySub = term.onKey(() => endBoot());
-    const dataSub = term.onData((d) => send({ t: 'i', d }));
+    const keySub = term.onKey(() => { claimControl(); endBoot(); });
+    // Watchers render output but do not answer terminal queries. This prevents
+    // N browser emulators from injecting N DA/CPR responses into one PTY.
+    const dataSub = term.onData((d) => {
+      if (controllerRef.current) send({ t: 'i', d });
+    });
     const ro = new ResizeObserver(resync);
     ro.observe(hostRef.current!);
     window.addEventListener('focus', onReturn);
     document.addEventListener('visibilitychange', onVisible);
 
-    // Touch scrolling: xterm doesn't translate touch gestures for applications
-    // that grabbed the mouse (tmux always does here), so swipes did nothing on
-    // phones. Convert drags into wheel steps: SGR mouse-wheel sequences when
-    // the app tracks the mouse (tmux scrolls its history), local scrollLines
-    // otherwise.
+    // A phone drag always navigates browser-retained terminal history. Passing
+    // it to an agent's mouse mode at the live bottom makes Claude consume the
+    // gesture without moving xterm's viewport, leaving no reliable way back
+    // through history on touch-only devices. xterm 5.5 registers no touch
+    // listeners of its own (verified against the bundled lib) and .term-host
+    // sets touch-action:none on mobile, so neither xterm nor the browser will
+    // pan: this is the only touch scrolling a phone has, in every pane.
+    //
+    // Convert the drag to whole rows and carry the remainder in `residual`.
+    // Quantising each event to a fixed notch instead silently drops whatever
+    // does not fill one — a 96px drag moved the view 68px — and that shortfall
+    // is what reads as lag, because the text trails the finger by design.
+    // scrollLines moves ydisp, the authority the viewport follows.
+    // The frame, not the inner measurement box: .term-host is what carries
+    // touch-action:none and what the user actually drags, and it stays the
+    // gesture target however the box inside it is nested.
+    const frame = frameRef.current ?? host;
+    const viewport = host.querySelector<HTMLElement>('.xterm-viewport');
     let touchY: number | null = null;
-    const onTouchStart = (e: TouchEvent) => { takeBack(); touchY = e.touches[0].clientY; };
+    let residual = 0;        // px of gesture not yet worth a whole row
+    let glideFrame = 0;
+    let velocity = 0;        // px/ms, signed like deltaY (positive scrolls down)
+    let lastMoveAt = 0;
+    // The scroll area spans every line in the buffer, so its height over that
+    // line count is the row height under whichever renderer is attached.
+    const scrollByPixels = (px: number) => {
+      const lines = term.buffer.active.length;
+      const cell = viewport && lines ? viewport.scrollHeight / lines : 0;
+      if (!cell) return 0;
+      residual += px;
+      const rows = Math.trunc(residual / cell);
+      if (!rows) return 0;
+      residual -= rows * cell;
+      term.scrollLines(rows);
+      return rows;
+    };
+    const stopGlide = () => { if (glideFrame) { cancelAnimationFrame(glideFrame); glideFrame = 0; } };
+    const onTouchStart = (e: TouchEvent) => {
+      stopGlide();               // a new touch takes over from any coasting
+      velocity = 0;
+      residual = 0;
+      touchY = e.touches[0].clientY;
+      lastMoveAt = e.timeStamp;
+    };
     const onTouchMove = (e: TouchEvent) => {
-      if (touchY == null) return;
+      if (touchY == null || !e.touches.length) return;
       const y = e.touches[0].clientY;
-      const dy = y - touchY;
-      const steps = Math.trunc(dy / 24); // ~one wheel notch per 24px of drag
-      if (steps !== 0) {
-        touchY = y;
-        let tracking = false;
-        try { tracking = ((term as unknown as { modes?: { mouseTrackingMode?: string } }).modes?.mouseTrackingMode ?? 'none') !== 'none'; } catch { /* older xterm */ }
-        const btn = steps > 0 ? 64 : 65; // drag down reveals earlier output = wheel up
-        for (let i = 0; i < Math.abs(steps); i++) {
-          if (tracking) send({ t: 'i', d: `\x1b[<${btn};${Math.max(1, Math.floor(term.cols / 2))};${Math.max(1, Math.floor(term.rows / 2))}M` });
-          else term.scrollLines(steps > 0 ? -1 : 1);
-        }
+      const deltaY = touchY - y;
+      touchY = y;
+      if (deltaY === 0) return;
+      const dt = e.timeStamp - lastMoveAt;
+      lastMoveAt = e.timeStamp;
+      // Weight the newest sample heavily: what matters is the speed at release,
+      // and a touch stream is noisy. Ignore a stale gap (a paused finger) and
+      // anything faster than a touch stream can legitimately be — a single
+      // coalesced jump over a 2ms gap is not a 48px/ms flick, and dividing by
+      // it would launch the glide clean through the buffer. A hand tops out
+      // around 4px/ms; real events arrive 8-16ms apart.
+      if (dt >= 4 && dt < 100) {
+        const sample = Math.max(-4, Math.min(4, deltaY / dt));
+        velocity = velocity * 0.3 + sample * 0.7;
       }
-      if (Math.abs(dy) > 4) e.preventDefault(); // keep the page from rubber-banding
+      scrollByPixels(deltaY);
+      if (e.cancelable) e.preventDefault(); // keep the page from rubber-banding
+      // This listener runs in capture before xterm's listener on the same host.
+      // stopPropagation alone would still allow that second handler.
+      e.stopImmediatePropagation();
     };
-    const onTouchEnd = () => { touchY = null; };
-    host.addEventListener('touchstart', onTouchStart, { passive: true });
-    host.addEventListener('touchmove', onTouchMove, { passive: false });
-    host.addEventListener('touchend', onTouchEnd);
+    const onTouchEnd = () => {
+      touchY = null;
+      const v0 = velocity;
+      velocity = 0;
+      // Only a flick coasts. A slow, deliberate drag through history must land
+      // exactly where the finger left it — drifting past the line someone was
+      // reading is worse than having no momentum at all. 0.4px/ms is about
+      // 400px/s: far above a careful drag, far below a real flick.
+      if (!viewport || Math.abs(v0) < 0.4) return;
+      let v = v0;
+      let previous = 0;
+      const glide = (now: number) => {
+        // Clamp the step so a dropped frame does not teleport the viewport.
+        const frame = previous ? Math.min(now - previous, 50) : 16;
+        previous = now;
+        const before = term.buffer.active.viewportY;
+        const rows = scrollByPixels(v * frame);
+        v *= 0.95 ** (frame / 16);      // ~5% per 60Hz frame, frame-rate neutral
+        // Stop at a standstill, or the moment a requested row does not move the
+        // view: that is either end of the buffer, and coasting into it drags.
+        if (Math.abs(v) < 0.02 || (rows !== 0 && term.buffer.active.viewportY === before)) {
+          glideFrame = 0;
+          return;
+        }
+        glideFrame = requestAnimationFrame(glide);
+      };
+      glideFrame = requestAnimationFrame(glide);
+    };
+    const onTouchCancel = () => { touchY = null; velocity = 0; stopGlide(); };
+    frame.addEventListener('touchstart', onTouchStart, { passive: true });
+    frame.addEventListener('touchmove', onTouchMove, { passive: false, capture: true });
+    frame.addEventListener('touchend', onTouchEnd);
+    frame.addEventListener('touchcancel', onTouchCancel);
 
     connect();
 
@@ -514,24 +673,28 @@ export default function TerminalPane({
       if (retry) clearTimeout(retry);
       if (bootTimer) clearTimeout(bootTimer);
       if (bootCheck) clearTimeout(bootCheck);
+      if (resyncTimer) clearTimeout(resyncTimer);
+      persistPreview();
       ro.disconnect();
       host.removeEventListener('pointerdown', onPointerDown, true);
-      host.removeEventListener('pointermove', onPointerMove, true);
-      host.removeEventListener('pointerup', onPointerUp, true);
-      host.removeEventListener('click', onClick, true);
-      document.removeEventListener('pointerdown', onDocumentPointerDown, true);
+      host.removeEventListener('paste', onPaste, true);
       document.removeEventListener('copy', onCopy, true);
-      host.removeEventListener('touchstart', onTouchStart);
-      host.removeEventListener('touchmove', onTouchMove);
-      host.removeEventListener('touchend', onTouchEnd);
+      frame.removeEventListener('touchstart', onTouchStart);
+      frame.removeEventListener('touchmove', onTouchMove, true);
+      frame.removeEventListener('touchend', onTouchEnd);
+      frame.removeEventListener('touchcancel', onTouchCancel);
+      stopGlide();
       window.removeEventListener('focus', onReturn);
       document.removeEventListener('visibilitychange', onVisible);
       dataSub.dispose();
       keySub.dispose();
+      scrollSub.dispose();
       selSub.dispose();
       try { ws?.close(); } catch { /* ignore */ }
       term.dispose();
       termRef.current = null;
+      resyncRef.current = () => {};
+      claimRef.current = () => {};
     };
   }, [session.id]);
 
@@ -540,19 +703,35 @@ export default function TerminalPane({
     if (termRef.current) termRef.current.options.theme = THEMES[theme];
   }, [theme]);
 
-  // Zoom: adjust font size (100% = 13px) and refit.
+  // Font size and PTY geometry move together. The controller asks the server
+  // for the grid that actually fits this pane; the confirmed grid then resizes
+  // every viewer in order with the PTY output stream.
   useEffect(() => {
     const t = termRef.current;
     if (!t) return;
+    const changed = previousZoomRef.current !== zoom;
+    previousZoomRef.current = zoom;
+    // Zoom is an explicit interaction outside the terminal element. If this
+    // pane is a watcher, take the geometry lease before reporting its newly
+    // fitted size; otherwise only the local glyphs grow and the canonical grid
+    // remains too large, clipping the bottom/right of the pane.
+    if (changed && active) claimRef.current();
     t.options.fontSize = Math.round((13 * zoom) / 100);
-    resyncRef.current();
-  }, [zoom]);
+    if (active) resyncRef.current();
+  }, [zoom, active]);
 
   // Move keyboard focus into the terminal whenever this pane becomes the active
   // one (e.g. selected from the sidebar, or newly created).
   useEffect(() => {
     if (!active) return;
-    const t = setTimeout(() => termRef.current?.focus(), 0);
+    // A retained pane may have spent time under display:none. Reclaim and
+    // remeasure only after its grid cell has layout again; hidden panes never
+    // get to resize the canonical PTY.
+    const t = setTimeout(() => {
+      claimRef.current();
+      resyncRef.current();
+      termRef.current?.focus();
+    }, 0);
     return () => clearTimeout(t);
   }, [active]);
 
@@ -592,16 +771,18 @@ export default function TerminalPane({
           <span className="ph-title" title={`${pathLabel} · double-click to rename`} onDoubleClick={() => { setDraft(session.name); setEditing(true); }}>{session.name}</span>
         )}
         <div className="ph-right">
+          {viewers > 1 && (
+            <span className={`ph-role${controller ? ' controller' : ''}`} title={controller ? 'This pane controls terminal input and size' : 'Interact with the terminal to take control'}>
+              {controller ? `${viewers} viewers` : 'watching'}
+            </span>
+          )}
           <span className="ph-path" title={pathLabel}>{pathLabel}</span>
           <button className="mini-btn ph-close" title="Close" onClick={(e) => { e.stopPropagation(); onClose(); }}><CloseGlyph /></button>
         </div>
       </div>
-      <div className="term-host">
+      <div className="term-host" ref={frameRef}>
         <div className="term-fill" ref={hostRef} />
       </div>
-      {copyMode && (
-        <div className="term-copy-hint mono">copy mode · scroll to read, press Esc or type to return</div>
-      )}
       {isMobile && conn === 'connected' && (
         // Control keys the phone keyboard lacks — needed for TUI menus (model
         // pickers, etc.). preventDefault keeps terminal focus so the keyboard
@@ -660,21 +841,13 @@ export default function TerminalPane({
           <button className="tp-x" onClick={() => { setPasteOpen(false); termRef.current?.focus(); }}>cancel</button>
         </div>
       )}
-      {conn === 'handedoff' && (
-        // The session is running elsewhere, not stopped — say so, and make the
-        // way back obvious (clicking the terminal works too).
-        <div className="term-exit mono">
-          <div className="tx-row">
-            <span>open on another device · still running</span>
-            <button
-              className="tx-btn"
-              onMouseDown={(e) => e.stopPropagation()}
-              onClick={(e) => { e.stopPropagation(); resumeRef.current(); }}
-            ><RefreshGlyph /> resume here</button>
-          </div>
+      {booting && preview && conn !== 'exited' && (
+        <div className="term-preview mono" aria-label="Restoring terminal">
+          <pre style={{ fontSize: `${Math.round((13 * zoom) / 100)}px` }}>{preview.rows.join('\n')}</pre>
+          <span>restoring last view…</span>
         </div>
       )}
-      {booting && conn !== 'exited' && conn !== 'handedoff' && (
+      {booting && !preview && conn !== 'exited' && (
         <div className="term-boot mono">
           {conn === 'connecting' ? 'connecting' : `starting ${cli?.label || session.cli}`}<span className="et-cursor" />
         </div>

web/src/styles.css

@@ -67,6 +67,7 @@ body {
 .mono { font-family: var(--font-mono); }
 
 .app { display: flex; height: 100%; }
+.app.app-suspended { display: none; }
 .sidebar { width: 282px; flex: none; background: var(--panel); border-right: 1px solid var(--border); display: flex; flex-direction: column; overflow: hidden; }
 .main { flex: 1; min-width: 0; padding: 12px; overflow: hidden; display: flex; flex-direction: column; }
 .stage { flex: 1; min-height: 0; }
@@ -440,6 +441,7 @@ body {
 
 /* main: tiles */
 .tiles { height: 100%; display: grid; gap: 12px; }
+.pane-deck.deck-hidden, .tile.tile-cached { display: none; }
 .tiles.drop-over { outline: 2px dashed var(--accent); outline-offset: -6px; border-radius: var(--r-xl); }
 .tile { display: flex; min-width: 0; min-height: 0; border-radius: var(--r-xl); }
 .tile > .slot { flex: 1; min-width: 0; min-height: 0; }
@@ -489,13 +491,9 @@ body {
 /* terminal boot cover ("connecting… / starting claude…") */
 .term-boot { position: absolute; inset: 0; top: 34px; display: flex; align-items: center; justify-content: center; background: var(--term-bg); color: var(--muted); font-size: 12.5px; z-index: 4; pointer-events: none; }
 .term-boot .et-cursor { height: 13px; width: 7px; margin-left: 7px; }
-/* copy-mode hint: a translucent banner just under the pane header while tmux is
-   in copy/scrollback mode, so a "dead" keyboard makes sense */
-.term-copy-hint { position: absolute; top: 40px; left: 50%; transform: translateX(-50%); z-index: 5; pointer-events: none;
-  padding: 3px 11px; border-radius: 999px; font-size: 11px; letter-spacing: 0.01em;
-  color: var(--accent-fg); background: color-mix(in srgb, var(--accent) 82%, transparent);
-  box-shadow: 0 2px 10px rgb(0 0 0 / 0.25); animation: rise-in 0.14s ease-out; white-space: nowrap; }
-
+.term-preview { position: absolute; inset: 34px 0 0; z-index: 4; overflow: hidden; background: var(--term-bg); color: var(--text); pointer-events: none; }
+.term-preview pre { height: 100%; margin: 0; padding: 10px 8px 8px 12px; overflow: hidden; font: inherit; line-height: 1.15; white-space: pre; }
+.term-preview > span { position: absolute; right: 9px; bottom: 7px; padding: 3px 6px; border: 1px solid var(--border); border-radius: var(--r-sm); background: color-mix(in srgb, var(--term-bg) 88%, transparent); color: var(--muted); font-size: 10px; }
 /* terminal "process exited" overlay */
 /* Non-blocking banner so the agent's last output (e.g. a login error) stays readable. */
 /* stopped state: quiet line centered in the pane, in the boot-cover's voice */
@@ -552,6 +550,8 @@ body {
 .pane-head .ph-left { grid-column: 1; justify-self: start; display: inline-flex; align-items: center; gap: 7px; }
 .pane-head .ph-title { grid-column: 2; min-width: 0; max-width: 100%; text-align: center; font-family: var(--font-mono); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: text; }
 .pane-head .ph-right { grid-column: 3; min-width: 0; display: inline-flex; align-items: center; justify-self: end; gap: 6px; }
+.pane-head .ph-role { flex: none; padding: 2px 6px; border: 1px solid var(--border); border-radius: 999px; color: var(--muted); font-family: var(--font-mono); font-size: 9.5px; line-height: 1.2; }
+.pane-head .ph-role.controller { color: var(--accent); border-color: color-mix(in srgb, var(--accent) 35%, var(--border)); }
 .pane-head .ph-path { min-width: 0; max-width: min(24vw, 220px); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-family: var(--font-mono); font-size: 10.5px; font-weight: 500; }
 .pane-head .ph-title-input { width: 100%; text-align: center; font: inherit; font-family: var(--font-mono); font-weight: 600; padding: 1px 6px; border: 1px solid var(--accent); border-radius: var(--r-sm); background: var(--panel-2); color: var(--text); min-width: 0; }
 .pane-head .ph-close { justify-self: end; }
@@ -563,14 +563,12 @@ body {
 .slot.focused { border-color: color-mix(in srgb, var(--accent) 45%, var(--border)); box-shadow: 0 4px 18px -10px rgba(0, 0, 0, 0.35); }
 .slot.focused .pane-head { background: color-mix(in srgb, var(--accent) 8%, var(--panel)); }
 
-.term-host { flex: 1; min-height: 0; padding: 10px 8px 8px 12px; background: var(--term-bg); }
-/* The terminal's own parent must carry NO padding. FitAddon sizes the grid from
-   getComputedStyle(parent).height, which under border-box INCLUDES padding — so
-   padding on the direct parent made it count one row (and one column) more than
-   fits, and the grid overflowed its clipped viewport: the bottom line rendered
-   sliced in half. Most visible with Codex, which paints its status line on the
-   very last row, where Claude leaves it blank. The frame keeps the padding; this
-   filler is the exact box the grid is measured against. */
+.term-host { flex: 1; min-height: 0; background: var(--term-bg); overflow: hidden; }
+/* The grid is measured against this filler, so it must stay unpadded: FitAddon
+   reads the PARENT's computed height and does NOT subtract its padding, so a
+   padded parent made the grid count a row that doesn't fit and the bottom line
+   rendered sliced (most visible with Codex, which paints its status line on the
+   very last row). The padding lives on .xterm, which FitAddon does subtract. */
 .term-fill { height: 100%; min-height: 0; }
 /* mobile control-key bar: the keys a phone keyboard lacks, pinned below the
    terminal so it rides just above the on-screen keyboard */
@@ -595,7 +593,7 @@ body {
 .term-paste .tp-input { width: 100%; box-sizing: border-box; resize: none; padding: 6px 8px; border: 1px solid var(--border-strong); border-radius: var(--r-md);
   background: var(--panel-2); color: var(--text); font-size: 13px; line-height: 1.35; }
 .term-paste .tp-input:focus { outline: none; border-color: var(--accent); }
-.term-host .xterm { height: 100%; }
+.term-host .xterm { width: 100%; height: 100%; padding: 10px 8px 8px 12px; }
 .xterm .xterm-viewport { scrollbar-width: none; }
 .xterm .xterm-viewport::-webkit-scrollbar { width: 0; height: 0; display: none; }
 
@@ -1039,10 +1037,28 @@ a.btn-ghost { text-decoration: none; }
 
 /* phones: two full-screen views — the sidebar list, or the selected pane */
 @media (max-width: 720px) {
-  /* Height follows the VISUAL viewport (set by App from window.visualViewport):
-     when the on-screen keyboard opens it shrinks the app so the terminal +
-     control bar stay above the keyboard instead of hiding behind it. */
-  .app { height: var(--vvh, 100dvh); overflow: hidden; }
+  /* Follow the VISUAL viewport rectangle (set from window.visualViewport):
+     when the on-screen keyboard opens it shrinks/moves the app so the terminal
+     and control bar stay above the keyboard instead of hiding behind it. */
+  html, body, #root { overflow: hidden; overscroll-behavior: none; }
+  .app {
+    position: fixed;
+    top: var(--vv-top, 0px);
+    left: var(--vv-left, 0px);
+    width: var(--vvw, 100%);
+    height: var(--vvh, 100dvh);
+    overflow: hidden;
+  }
+  .term-host { touch-action: none; overscroll-behavior: contain; }
+  /* Keep xterm's transparent real input at the visible prompt edge. xterm
+     normally parks/moves it for desktop IME behavior; on phones this element
+     is also the browser's only clue about what must remain above the OSK. */
+  .term-host .xterm-helper-textarea {
+    left: var(--am-input-left, 50%) !important;
+    top: var(--am-input-top, calc(100% - 2px)) !important;
+    width: 1px !important;
+    height: 1px !important;
+  }
   .app.m-home .main { display: none; }
   .app.m-home .sidebar { width: 100%; border-right: none; }
   .app.m-stage .sidebar { display: none; }