Refine libghostty session ownership and restore

README.md

@@ -124,15 +124,22 @@ browser (xterm.js panes)
 
 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
-snapshot repaint plus replayed scrollback rather than a redraw, several browsers
-can watch and drive one session at once (they share one grid, sized to the
-smallest), and agent state is read from the grid instead of shelling out per
-session. A resize is a request too: the browser measures itself and asks, the
-backend applies the size once the asking stops and then repaints every viewer
-from the grid — so a window drag costs one PTY resize instead of one per frame,
-each of which would push another copy of a TUI's screen into the scrollback. Sessions survive browser disconnects but NOT a backend restart, and not
-a Space sleep/rebuild; with storage the working dir and CLI state persist, so a
-re-opened session resumes its own conversation. Claude
+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
@@ -144,11 +151,8 @@ conversations.
 |---|---|---|
 | `PORT` | `7860` | HTTP + WS port (HF `app_port`) |
 | `DATA_DIR` | `/data` | Durable root (mounted private Storage Bucket) |
-| `AM_SCROLLBACK` | `20000` | Scrollback lines kept per session grid |
-| `AM_REPLAY_BYTES` | `262144` | PTY bytes replayed to a reattaching browser |
+| `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 |
-| `AM_RESIZE_CARRY` | `1` | `0` reflows on resize like a plain terminal (duplicates scrollback) |
-| `AM_RESIZE_ARCHIVE_MS` | `700` | Grace period for an app to repaint before rows a shrink pushed off are archived |
 | `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) |

server/migration.test.mjs

@@ -1,13 +1,13 @@
-// End-to-end check of the tmux -> libghostty session migration.
+// 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';
 
-// DATA_DIR must be ABSOLUTE: cleanRelPath() resolves against WORKSPACES_DIR and
-// compares strings, so a relative root makes every path look like an escape.
-const DATA_DIR = path.resolve('./.mig');
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-migration-'));
 
 const PORT = 7893;
 const CTRL = '\x00\x00AM:';
@@ -28,7 +28,7 @@ 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. */
+/** 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}`);
@@ -36,6 +36,7 @@ function view(id, cols = 100, rows = 30) {
       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 {} },
@@ -84,6 +85,7 @@ try {
   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'),
@@ -103,12 +105,12 @@ try {
   });
   await sleep(1600);
 
-  // --- reattach: restore frame + replayed scrollback ------------------------
+  // --- 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 replays earlier scrollback', b.bytes.includes('hello-from-viewer-a'),
+  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]'));
@@ -129,8 +131,8 @@ try {
   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() used to shell out to `tmux capture-pane`; it reads the held
-  // grid instead. Same shape (plain text, screen + scrollback above it).
+  // 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));
@@ -141,7 +143,7 @@ try {
     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, nobody is kicked -------------------------
+  // --- two viewers share one grid with one explicit controller --------------
   const c = await view(id, 150, 40);
   await sleep(400);
   c.resize(150, 40);
@@ -154,19 +156,30 @@ try {
   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 smallest viewer', !!bGrid && bGrid.cols === 40 && bGrid.rows === 20,
+  check('grid follows the controller, not the smallest viewer', !!bGrid && bGrid.cols === 40 && bGrid.rows === 20,
     bGrid && `${bGrid.cols}x${bGrid.rows}`);
-  check('grid is flagged shared', !!bGrid && bGrid.shared === true && bGrid.viewers === 2);
+  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();
-  await sleep(1000);
-  const grown = c.lastFrame('grid');
-  check('grid grows back when a viewer leaves', !!grown && grown.cols === 150 && grown.rows === 40,
-    grown && `${grown.cols}x${grown.rows}`);
 
   // --- stopping is explicit ------------------------------------------------
   await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
@@ -184,6 +197,7 @@ try {
   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/resize.test.mjs

@@ -1,35 +1,19 @@
-// Resize behaviour of a server-held grid.
+// Invariants for the server-held terminal model.
 //
-// The bug this pins down: resizing a pane duplicated content in the scrollback
-// (the same lines re-wrapped at every width the pane passed through) and left
-// the browser's buffer disagreeing with the grid. Three causes, all here:
-//
-//   * REFLOW. Narrowing rewraps the outgoing screen — a 119-column row becomes
-//     two rows at 110 — and the excess scrolls up into scrollback, where the
-//     TUI's repaint of that same screen leaves it stranded as a copy. One copy
-//     per resize, so one per zoom click. Fixed by clearing the screen before the
-//     reflow and carrying it across by hand.
-//   * a resize STORM — ResizeObserver fires per animation frame while a window
-//     is dragged, and every tick used to resize the PTY, so one drag paid the
-//     above dozens of times. Fixed by coalescing.
-//   * the browser reflowing ITSELF (fit.fit()) before the server confirmed, so
-//     its scrollback was a byte log wrapped at mixed widths while the grid held
-//     a properly reflowed one. Fixed by making the browser ask, not act.
-//
-// Every duplication check has teeth: AM_RESIZE_CARRY=0 restores plain reflow and
-// the zoom checks fail (63 duplicated tokens in the grid, 101 in the browser).
-//
-// fixtures/repaint-tui.mjs stands in for an agent TUI and repaints exactly the
-// way Claude Code does, so this costs no agent tokens.
+// These tests intentionally avoid classifying foreground applications or
+// counting "acceptable" duplicate rows. The contract is smaller and firmer:
+// Ghostty owns retained state, a resize is ordered ordinary reflow, and exactly
+// one viewer controls input and PTY geometry. Full serialization is attach-only.
 //   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';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const DATA_DIR = path.join(HERE, '.resize');
-const FIXTURE = path.join(HERE, 'fixtures', 'repaint-tui.mjs');
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-resize-'));
 const PORT = 7895;
 const CTRL = '\x00\x00AM:';
 const base = `http://localhost:${PORT}`;
@@ -39,7 +23,15 @@ 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 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,
@@ -47,65 +39,58 @@ const srv = spawn('node', ['src/index.js'], {
   stdio: ['ignore', 'pipe', 'pipe'],
 });
 let log = '';
-srv.stdout.on('data', (d) => { log += d; });
-srv.stderr.on('data', (d) => { log += d; });
+srv.stdout.on('data', (data) => { log += data; });
+srv.stderr.on('data', (data) => { log += data; });
 
-// The browser's own emulator, so a viewer can be checked the way a user sees it
-// rather than only through the grid. Optional: it is a devDependency, and the
-// suite still runs (minus those checks) in a production install.
 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}`);
-    // A stand-in for TerminalPane, mirroring its message handling EXACTLY — the
-    // point is to catch the ordering hazard in it: xterm's write is asynchronous,
-    // so a resize applied outside the write callback can overtake the bytes that
-    // were sent before it.
     const term = mirror && Headless
       ? new Headless({ cols, rows, scrollback: 20000, allowProposedApi: true })
       : null;
     const v = {
       bytes: '', frames: [], term,
-      type: (d) => ws.send(JSON.stringify({ t: 'i', d })),
-      resize: (c, r) => ws.send(JSON.stringify({ t: 'r', cols: c, rows: r })),
-      lastFrame: (t) => [...v.frames].reverse().find((f) => f.t === t) || null,
-      countFrames: (t) => v.frames.filter((f) => f.t === t).length,
+      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 {} },
-      // Everything the viewer has: scrollback above the screen, then the screen.
       screenText: async () => {
         if (!term) return '';
-        await new Promise((r) => term.write('', r));
-        const buf = term.buffer.active;
-        const out = [];
-        for (let i = 0; i < buf.length; i++) out.push(buf.getLine(i)?.translateToString(true) ?? '');
-        return out.join('\n');
-      },
-      // Just the visible screen — what the app is displaying right now.
-      viewportText: async () => {
-        if (!term) return '';
-        await new Promise((r) => term.write('', r));
+        await new Promise((done) => term.write('', done));
         const buf = term.buffer.active;
-        const out = [];
-        for (let i = buf.baseY; i < buf.baseY + term.rows; i++) out.push(buf.getLine(i)?.translateToString(true) ?? '');
-        return out.join('\n');
+        const lines = [];
+        for (let i = 0; i < buf.length; i++) lines.push(buf.getLine(i)?.translateToString(true) ?? '');
+        return lines.join('\n');
       },
     };
     ws.on('message', (data) => {
-      const s = data.toString('utf8');
-      if (s.startsWith(CTRL)) {
-        let m = null;
-        try { m = JSON.parse(s.slice(CTRL.length)); } catch { return; }
-        v.frames.push(m);
-        if (term && (m.t === 'grid' || m.t === 'restore') && m.cols > 0 && m.rows > 0
-            && (term.cols !== m.cols || term.rows !== m.rows)) {
-          if (m.clear) term.write('', () => term.resize(m.cols, m.rows));
-          else term.resize(m.cols, m.rows);
+      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);
+        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 += s;
-        if (term) term.write(s);
+        v.bytes += text;
+        if (term) term.write(text);
       }
     });
     ws.on('open', () => resolve(v));
@@ -113,18 +98,6 @@ function view(id, cols, rows, mirror = false) {
   });
 }
 
-/** Tokens the fixture prints are unique, so a repeat is a duplicated line. */
-function duplicateTokens(text) {
-  const counts = new Map();
-  for (const m of text.matchAll(/\b\d{3}\.\d{2}\b/g)) counts.set(m[0], (counts.get(m[0]) || 0) + 1);
-  return [...counts.values()].filter((n) => n > 1).length;
-}
-
-const gridText = async (id) => {
-  const r = await (await fetch(`${base}/api/agents/${id}/tail?lines=500`)).json();
-  return typeof r === 'string' ? r : (r.text || '');
-};
-
 async function session(name) {
   const created = await (await fetch(`${base}/api/sessions`, {
     method: 'POST', headers: { 'content-type': 'application/json' },
@@ -134,350 +107,145 @@ async function session(name) {
   return created.id;
 }
 
-/** A pane showing the fixture, painted and settled. */
-async function paintedFixture(name, cols = 120, rows = 40, mirror = false) {
-  const id = await session(name);
-  const v = await view(id, cols, rows, mirror);
-  v.resize(cols, rows);
-  await sleep(900);
-  v.type(`node ${FIXTURE}\r`);
-  await sleep(1500);
-  return { id, v };
-}
+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 || '');
+};
+
+const stop = async (id) => {
+  await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' }).catch(() => {});
+  await sleep(250);
+};
 
 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 { if ((await fetch(`${base}/api/health`)).ok) { up = true; break; } } catch {}
-    await sleep(250);
-  }
-  if (!up) throw new Error(`server never came up:\n${log.slice(-800)}`);
+  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)}`);
 
-  // --- one deliberate resize -----------------------------------------------
+  // 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, v } = await paintedFixture('resize once');
-    const before = duplicateTokens(await gridText(id));
-    check('a painted fixture starts with no duplicated lines', before === 0, `${before} duplicated tokens`);
-
-    v.resize(80, 30);
-    await sleep(1200);
-    const after = duplicateTokens(await gridText(id));
-    // One repaint at a new width cannot avoid leaving the rows the shrink pushed
-    // into scrollback, so a handful is expected; a copy of the whole screen is
-    // not.
-    check('one resize duplicates at most a few lines', after <= 12, `${after} duplicated tokens`);
-    check('the fixture followed the resize', (await gridText(id)).includes('[fixture 80x30]'));
+    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 fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+    await stop(id);
   }
 
-  // --- a drag: ResizeObserver fires every frame ----------------------------
+  // A drag should issue one final resize, not one SIGWINCH per animation frame.
   {
-    const { id, v } = await paintedFixture('resize storm');
-    // 16 sizes in ~500ms is a slow drag; a real one is faster.
+    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(30);
+      await sleep(25);
     }
     v.resize(88, 24);
-    await sleep(1500);
-
-    const dupes = duplicateTokens(await gridText(id));
-    check('a drag does not multiply scrollback', dupes <= 12, `${dupes} duplicated tokens`);
-    check('the grid settles at the final size', (await gridText(id)).includes('[fixture 88x24]'));
-    // Every viewer must be told the size that was actually applied, and the
-    // coalescing must not swallow the last one.
-    const last = v.lastFrame('grid');
-    check('the last grid frame matches the final size', !!last && last.cols === 88 && last.rows === 24,
-      last && `${last.cols}x${last.rows}`);
-    check('the storm is coalesced into few PTY resizes', v.countFrames('grid') <= 4,
-      `${v.countFrames('grid')} grid frames`);
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- the browser is repainted from the grid after a resize ---------------
-  // An app that ignores SIGWINCH (a bash prompt, an agent sitting idle) would
-  // otherwise leave the viewer showing its own reflow of a byte log, which is
-  // exactly where the two disagree.
-  {
-    const { id, v } = await paintedFixture('resize repaint');
-    const beforeBytes = v.bytes.length;
-    v.resize(70, 26);
-    await sleep(1200);
-    const sent = v.bytes.slice(beforeBytes);
-    check('a settled resize repaints the viewer from the grid', sent.includes('\x1b[2J'),
-      `${sent.length}B after resize`);
-    // The size must arrive BEFORE the bytes that assume it.
-    check('the grid frame precedes the repaint',
-      v.frames.some((f) => f.t === 'grid' && f.cols === 70 && f.rows === 26));
+    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 fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+    await stop(id);
   }
 
-  // --- zooming: a sequence of deliberate, settled resizes ------------------
-  // Each zoom click is a real resize, so coalescing cannot help here. What keeps
-  // scrollback clean is clearing the screen before the reflow (nothing left to
-  // rewrap into history) and carrying it across by hand instead.
+  // 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, v } = await paintedFixture('resize zoom');
-    // The first resize is the one that teaches the host this app repaints (a
-    // shell session is assumed not to), so measure from after it.
-    v.resize(110, 36);
-    await sleep(900);
-    const learned = duplicateTokens(await gridText(id));
-
-    for (const [c, r] of [[100, 32], [90, 28], [80, 24], [90, 28], [100, 32], [110, 36]]) {
-      v.resize(c, r);
-      await sleep(400);
-    }
-    await sleep(1200);
-    const after = duplicateTokens(await gridText(id));
-    check('zooming in and out adds no duplicated lines', after <= learned,
-      `${learned} before, ${after} after six zoom steps`);
-    check('the zoomed grid still shows the fixture', (await gridText(id)).includes('[fixture 110x36]'));
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- what the BROWSER ends up holding ------------------------------------
-  // The grid being clean is only half the fix: the duplication a user sees is in
-  // xterm's buffer, which reflows harder than libghostty does. This drives the
-  // real emulator through the real protocol.
-  if (!Headless) {
-    console.log('SKIP  browser-side checks (@xterm/headless not installed)');
-  } else {
-    const { id, v } = await paintedFixture('resize browser', 120, 40, true);
-    v.resize(110, 36);
-    await sleep(900);
-    const learned = duplicateTokens(await v.screenText());
-    for (const [c, r] of [[100, 32], [90, 28], [80, 24], [90, 28], [100, 32], [110, 36]]) {
-      v.resize(c, r);
-      await sleep(400);
-    }
-    await sleep(1200);
-    const seen = await v.screenText();
-    check("zooming leaves no duplicates in the browser's own buffer", duplicateTokens(seen) <= learned,
-      `${learned} before, ${duplicateTokens(seen)} after six zoom steps`);
-    check('the browser ends at the grid size', v.term.cols === 110 && v.term.rows === 36,
-      `${v.term.cols}x${v.term.rows}`);
-    // Ordering: if resize overtook the repaint, the screen would be torn or stale.
-    check('the browser shows the fixture at the final size', seen.includes('[fixture 110x36]'));
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- scrolling back still reaches everything -----------------------------
-  // The first version of the carry cleared the screen and dropped the rows that
-  // no longer fitted, so every zoom-in quietly ate history: a 40->24 shrink took
-  // 16 lines with it and the pane could no longer scroll all the way up. Rows
-  // that fall off the top have to be ARCHIVED, not discarded.
-  if (!Headless) {
-    console.log('SKIP  scrollback checks (@xterm/headless not installed)');
-  } else {
-    const id = await session('resize history');
-    const v = await view(id, 120, 40, true);
-    v.resize(120, 40);
-    await sleep(900);
-    // Teach the host that this session repaints, so the carry path is the one
-    // under test, then leave a real log behind — that is what must survive.
-    v.type(`node ${FIXTURE}\r`);
-    await sleep(1500);
-    v.resize(118, 38);
-    await sleep(800);
-    v.type('\x03');
-    await sleep(800);
-    // The trailing blank lines are load-bearing. Bash redraws its prompt on every
-    // SIGWINCH and, when that prompt is wrapped, draws over the rows above it —
-    // verified identical with AM_RESIZE_CARRY=0, so it is bash's doing and not the
-    // resize path's. Without the padding this test would be asserting something no
-    // terminal delivers.
-    v.type('for i in $(seq 1 200); do echo "hist-$i"; done; echo; echo; echo\r');
-    await sleep(2000);
-
-    const missing = (text) => {
-      const gone = [];
-      for (let i = 1; i <= 200; i++) if (!new RegExp(`hist-${i}(?!\\d)`).test(text)) gone.push(i);
-      return gone;
-    };
-    const before = missing(await v.screenText());
-    check('the log is complete before zooming', before.length === 0, `${before.length} lines missing`);
-
-    for (const [c, r] of [[100, 30], [90, 24], [100, 30], [110, 34], [120, 40], [90, 24]]) {
-      v.resize(c, r);
-      await sleep(400);
-    }
-    await sleep(1200);
-    // The grid is the authority and has to be exact.
-    const gridGone = missing(await gridText(id));
-    check('zooming loses no scrollback in the grid', gridGone.length === 0,
-      gridGone.length ? `${gridGone.length} lines gone, e.g. hist-${gridGone.slice(0, 5).join(', hist-')}` : '');
-    // xterm's own reflow drops a couple of lines over a cycle this violent no
-    // matter what we do — AM_RESIZE_CARRY=0 loses three in the same run, from the
-    // same region — so this is a bound, not a promise. A reattach repaints the
-    // pane from the grid, which is why the grid check above is the strict one.
-    const after = missing(await v.screenText());
-    check('zooming loses no more browser scrollback than plain reflow does', after.length <= 4,
-      after.length ? `${after.length} lines gone, e.g. hist-${after.slice(0, 5).join(', hist-')}` : 'none');
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- zooming OUT gives back the top, it does not copy it -----------------
-  // Growing the screen pulls history back down out of scrollback to fill the new
-  // rows. The carry used to paint the outgoing screen over exactly those rows, so
-  // zooming out destroyed the history it had just recovered and left the old
-  // screen stranded above the app's repaint: "I can't scroll all the way to the
-  // top, and zooming out further duplicates at the top."
-  if (!Headless) {
-    console.log('SKIP  zoom-out checks (@xterm/headless not installed)');
-  } else {
-    const id = await session('resize zoom out');
-    const v = await view(id, 120, 40, true);
-    v.resize(120, 40);
-    await sleep(900);
-    v.type(`node ${FIXTURE}\r`);
-    await sleep(1500);
-    v.type('\x03');
-    await sleep(800);
-    v.type('for i in $(seq 1 120); do echo "out-$i"; done; echo; echo; echo\r');
-    await sleep(2000);
-
-    const count = (text, n) => (text.match(new RegExp(`out-${n}(?!\\d)`, 'g')) || []).length;
-    // Zoom in, then back out past where it started.
-    for (const [c, r] of [[100, 26], [90, 20], [100, 26], [110, 34], [120, 44]]) {
-      v.resize(c, r);
-      await sleep(500);
-    }
-    await sleep(1200);
-    const seen = await v.screenText();
-    const grid = await gridText(id);
-    const lost = [];
-    const doubled = [];
-    for (let i = 1; i <= 120; i++) {
-      if (count(grid, i) === 0) lost.push(i);
-      if (count(grid, i) > 1) doubled.push(i);
+    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-'));
     }
-    check('zooming out keeps every line it recovered', lost.length === 0,
-      lost.length ? `${lost.length} gone, e.g. out-${lost.slice(0, 5).join(', out-')}` : '');
-    check('zooming out copies nothing to the top', doubled.length === 0,
-      doubled.length ? `${doubled.length} doubled, e.g. out-${doubled.slice(0, 5).join(', out-')}` : '');
-    const browserDoubled = [];
-    for (let i = 1; i <= 120; i++) if (count(seen, i) > 1) browserDoubled.push(i);
-    check('and copies nothing in the browser either', browserDoubled.length === 0,
-      browserDoubled.length ? `${browserDoubled.length} doubled, e.g. out-${browserDoubled.slice(0, 5).join(', out-')}` : '');
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+    b.close();
+    await stop(id);
   }
 
-  // --- an app whose frame overflows the pane -------------------------------
-  // The case a real agent pane hits on zoom, and the one thing here that is NOT
-  // ours to fix: an agent renders the tail of its conversation, narrowing wraps
-  // those lines, and the frame becomes taller than the screen. Printing it scrolls
-  // the overflow into scrollback, where it is a copy of what the frame also shows.
-  // Any terminal does this; measured here at 251 duplicated tokens with the carry
-  // on and 371 with AM_RESIZE_CARRY=0, so what we can prevent, we do.
-  //
-  // The copies are one per print: the app painted an overflowing frame three times
-  // here (once on launch, once per resize) and rows appear up to three times, with
-  // the carry on and off alike. What the carry removes is OUR share — the rewrapped
-  // copy reflow would archive on top — which is the whole 371-vs-251 difference.
-  // The bound below is what catches that share coming back.
-  if (!Headless) {
-    console.log('SKIP  overflow checks (@xterm/headless not installed)');
-  } else {
-    const id = await session('resize overflow');
-    const v = await view(id, 150, 40, true);
-    v.resize(150, 40);
-    await sleep(900);
-    v.type(`FIXED_LINES=30 node ${FIXTURE}\r`);
-    await sleep(2000);
-    v.resize(148, 38);          // teaches host.repaints = true
-    await sleep(1000);
-    v.resize(100, 26);          // 100% -> 150%: wraps the frame past the screen
-    await sleep(2000);
-
-    const buffer = await v.screenText();
-    const counts = new Map();
-    for (const m of buffer.matchAll(/\b\d{3}\.\d{2}\b/g)) counts.set(m[0], (counts.get(m[0]) || 0) + 1);
-    const values = [...counts.values()];
-    const dupes = values.filter((n) => n > 1).length;
-    const most = Math.max(0, ...values);
-    // 251 with the carry, 371 without it. The gap is the rewrap copy, and 300 sits
-    // in it: this fails if the resize path starts archiving a screen again.
-    check('an overflowing frame duplicates only what the app itself printed', dupes <= 300,
-      `${dupes} duplicated tokens, up to ${most} copies each (app printed 3 frames)`);
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- the screen survives a resize the app ignores ------------------------
-  // Clearing before the reflow is only safe because the screen is re-painted
-  // afterwards. An app that never answers SIGWINCH is the case that proves it:
-  // here the fixture teaches the host that this session repaints, then exits, so
-  // the shell prompt below it gets the carry treatment while redrawing nothing.
+  // 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, v } = await paintedFixture('resize carry');
-    v.resize(110, 36);          // teaches host.repaints = true
-    await sleep(900);
-    v.type('\x03');             // Ctrl-C: the fixture dies, prompt comes back
-    await sleep(800);
-    v.type('printf "carry-%s\\n" 1 2 3 4 5\r');
-    await sleep(800);
-    check('the lines are on screen before the resize', (await gridText(id)).includes('carry-5'));
-    v.resize(84, 30);
-    await sleep(1200);
-    const text = await gridText(id);
-    check('a screen the app never repaints survives the resize', text.includes('carry-5'),
-      text.includes('carry-1') ? '' : 'lost the earlier lines too');
-    check('and is not duplicated by the carry', (text.match(/carry-5/g) || []).length === 1,
-      `${(text.match(/carry-5/g) || []).length} copies`);
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+    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);
   }
 
-  // --- a shell's rewrapped scrollback is the log, not a duplicate ----------
-  // Nothing repaints it, so reflow is the only thing preserving it: the clear
-  // must stay off until an app proves it repaints.
+  // Focus and unrelated layout events may re-report the same preference.
   {
-    const id = await session('resize shell log');
-    const v = await view(id, 120, 40);
-    v.resize(120, 40);
-    await sleep(900);
-    v.type('for i in $(seq 1 60); do echo "log-line-$i"; done\r');
-    await sleep(1200);
-    v.resize(90, 30);
-    await sleep(1200);
-    const text = await gridText(id);
-    check('a shell keeps its scrolled-off output across a resize', text.includes('log-line-5'),
-      text.includes('log-line-55') ? '' : 'lost recent lines too');
-    v.close();
-    await fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
-  }
-
-  // --- a viewer that only re-asks for the same size costs nothing ----------
-  // Tab focus and unrelated layout changes call resync() constantly.
-  {
-    const { id, v } = await paintedFixture('resize noop');
-    const framesBefore = v.countFrames('grid');
-    for (let i = 0; i < 5; i++) { v.resize(120, 40); await sleep(120); }
-    await sleep(600);
-    check('re-requesting the current size changes nothing', v.countFrames('grid') === framesBefore,
-      `${v.countFrames('grid') - framesBefore} extra grid frames`);
-    check('no duplication from no-op resyncs', duplicateTokens(await gridText(id)) === 0);
+    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 fetch(`${base}/api/sessions/${id}/stop`, { method: 'POST' });
+    await stop(id);
   }
 } catch (err) {
   check('no exceptions', false, String(err && err.message ? err.message : err));
-  console.log('--- server log tail ---\n' + log.slice(-1200));
+  console.log('--- server log tail ---\n' + log.slice(-1600));
 } finally {
   srv.kill('SIGTERM');
-  await sleep(600);
+  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/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/index.js

@@ -259,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' });
@@ -278,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
@@ -984,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
@@ -2153,35 +2152,30 @@ wss.on('connection', (ws, req) => {
     if (d.length) ws.send(d);
   });
   handle.onExit(() => {
-    // Only ONE reason to close now: the agent process itself exited. There is no
-    // handover any more — the grid is shared, so a second device attaching does
-    // not take the session away from the first. Still no auto-reconnect on 4000,
-    // or we would respawn the agent in a loop.
+    // 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) {
       try { ws.close(4000, 'exited'); } catch { ws.close(); }
     }
   });
-  // The shared grid moved (a viewer joined, left, or asked for a different size).
-  // Every viewer is told, so nobody keeps drawing into a stale geometry.
-  // `clear` says the backend cleared its screen before reflowing and is sending a
-  // repaint: the browser has to do the same, or its emulator archives a rewrapped
-  // copy of the screen that ours deliberately did not.
-  handle.onGrid((cols_, rows_, shared, viewers, clear) => {
+  // 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_, shared, viewers, clear })); } catch {}
+    try { ws.send(TERM_CTRL + JSON.stringify({ t: 'grid', cols: cols_, rows: rows_, controller, viewers, reset })); } catch {}
   });
 
-  // Hand the screen back immediately: replayed scrollback, then a snapshot
-  // repaint on top as the authority. No tmux redraw, and nothing is asked of the
-  // agent's TUI — which is why this works even while it sits idle.
+  // 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, shared: restore.shared,
+        viewers: restore.viewers, controller: restore.controller, reset: true,
       }));
-      if (restore.replay) ws.send(restore.replay);
       ws.send(restore.ansi);
     } catch {}
   }
@@ -2191,8 +2185,7 @@ wss.on('connection', (ws, req) => {
     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);
-    // 'copy' is gone: scrollback now lives in the browser (it is replayed on
-    // attach), so a selection is local and needs no round trip to tmux.
+    else if (msg.t === 'claim') handle.claim();
   });
 
   // Detaching a viewer, NOT stopping the session.

server/src/runner.js

@@ -6,7 +6,7 @@ import { remoteState, setPaused } from './remote.js';
 import { cliById, WORKSPACES_DIR, isRemote } from './config.js';
 import { update, list } from './sessions.js';
 import { captureOpencodeSession } from './traces.js';
-import { buildPaletteIndex, rowsToAnsi, snapshotToAnsi, snapshotToRows } from './snapshot.js';
+import { buildPaletteIndex, snapshotToRestoreAnsi } from './snapshot.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
@@ -40,10 +40,10 @@ const bashLaunch = `exec bash --rcfile ${BASHRC} -i`;
 // 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 a snapshot repaint plus replayed scrollback,
+//   * 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 and drive the same session at once, so the old
-//     one-device-at-a-time handover is gone;
+//   * 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.
 //
@@ -55,28 +55,20 @@ const bashLaunch = `exec bash --rcfile ${BASHRC} -i`;
 const BUSY_SECS = 4;
 // Re-rendering the grid to text on every chunk during a burst is wasteful.
 const SAMPLE_THROTTLE_MS = 250;
-// Scrollback replayed to a reattaching browser, as raw PTY bytes. snapshot()
-// returns history as plain LINES, so replaying that would hand back colourless
-// scrollback under a fully styled screen.
-const REPLAY_BYTES = Number(process.env.AM_REPLAY_BYTES || 256 * 1024);
-const SCROLLBACK_LINES = Number(process.env.AM_SCROLLBACK || 20000);
-// A resize is only worth acting on once it stops changing. ResizeObserver fires
-// per animation frame while a window is dragged, and every applied size costs a
-// rewrap of the outgoing screen and a full TUI repaint (see carryScreen for what
-// that leaves behind). Coalescing a drag into one resize is what keeps the
-// scrollback from filling with the same screen re-wrapped a dozen ways.
+// 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);
-// Escape hatch for carryScreen: with AM_RESIZE_CARRY=0 a resize reflows the way a
-// plain terminal does, duplication and all. Kept because carrying the screen by
-// hand is the one part of a resize that makes an assumption about the app.
-const RESIZE_CARRY = process.env.AM_RESIZE_CARRY !== '0';
-// How long an app gets to answer SIGWINCH before the rows a shrink pushed off the
-// screen are treated as history rather than as a copy (see settleArchive).
-// Generous on purpose: an agent TUI that debounces SIGWINCH must not be mistaken
-// for one that ignored it, and waiting costs nothing a user can see because the
-// rows in question are off-screen either way. A repaint that arrives sooner ends
-// the wait immediately.
-const ARCHIVE_SETTLE_MS = Number(process.env.AM_RESIZE_ARCHIVE_MS || 700);
 
 const hosts = new Map(); // session id -> host
 
@@ -149,220 +141,51 @@ export function peek(id) {
 
 // ---------- the shared grid ----------
 //
-// One session, one grid, however many viewers. A client may REQUEST a size but
-// never imposes one: letting each client size itself is what garbles a second
-// device, because the phone resizes the PTY while the laptop keeps drawing into
-// its old geometry. The grid follows the smallest attached viewer so the content
-// fits everywhere, and grows back as viewers leave.
+// 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) {
-  if (!host.sizes.size) return { cols: host.cols, rows: host.rows };
-  let cols = Infinity;
-  let rows = Infinity;
-  for (const s of host.sizes.values()) {
-    cols = Math.min(cols, s.cols);
-    rows = Math.min(rows, s.rows);
-  }
-  return { cols, rows };
-}
-
-/**
- * Re-frame a snapshot for a different geometry, so it can be painted into one.
- *
- * BOTTOM-anchored, in both directions, because that is what the emulator does on
- * its own. Growing the screen pulls history back DOWN out of scrollback to fill
- * the new rows from the top (measured: 12 rows -> 30 brought 18 lines back), so a
- * top-anchored paint lands right on top of them — which destroyed the history and
- * left the old screen stranded above the app's fresh repaint. Anchoring at the
- * bottom puts the carried screen exactly where the emulator already put it, with
- * the recovered history above it untouched.
- *
- * On a shrink the rows that fall off the top are not in here at all —
- * settleArchive decides what becomes of those.
- */
-function fitSnapshot(snap, cols, rows) {
-  const shift = snap.rows - rows; // > 0 shrinking, < 0 growing
-  return {
-    cols,
-    rows,
-    isAltScreen: snap.isAltScreen,
-    cursorRow: Math.max(0, Math.min(rows - 1, snap.cursorRow - shift)),
-    cursorCol: Math.max(0, Math.min(cols - 1, snap.cursorCol)),
-    cells: (snap.cells || [])
-      .filter((c) => c.row - shift >= 0 && c.row - shift < rows && c.col < cols)
-      .map((c) => (shift ? { ...c, row: c.row - shift } : c)),
-  };
-}
-
-/**
- * Carry the current screen across a resize by hand, instead of letting reflow do
- * it — the whole reason a resize duplicated scrollback.
- *
- * Reflow is not wrong, it is just redundant here: narrowing rewraps every row of
- * the outgoing screen (a 119-column row becomes two at 110), which scrolls the
- * excess up into scrollback — and then the app repaints that same screen, so the
- * rewrapped copy is left above it forever. Six zoom clicks, six copies.
- *
- * So the screen is cleared BEFORE the reflow, which leaves it nothing to archive,
- * and re-painted after: snapshotToAnsi positions every row absolutely and emits
- * no newline, so the paint itself cannot wrap or scroll either.
- *
- * The rows that no longer fit cannot be settled here, which took two tries to
- * see. Dropping them ate real history — a 40->24 shrink lost 16 lines a user
- * could previously scroll back to. Archiving them brought the duplication
- * straight back, because for a repainting TUI those rows ARE the screen it is
- * about to reprint. Whether they are redundant depends on what the app does
- * NEXT, so they are handed to settleArchive to decide once that is known.
- *
- * Returns { pre, ansi, dropped }: bytes for before the resize and after it (both
- * of which every viewer needs too) plus the rows in limbo. Null when reflow
- * should be left alone (see host.repaints).
- */
-function carryScreen(host, cols, rows) {
-  if (!RESIZE_CARRY || !host.repaints) return null;
-  let snap;
-  let ansi;
-  try {
-    snap = host.vt.snapshot({ includeCells: true });
-    // Rows only, no erase: on a grow the emulator has already refilled the top of
-    // the screen from scrollback, and that history has to survive this paint.
-    ansi = snapshotToRows(fitSnapshot(snap, cols, rows));
-  } catch { return null; }
-
-  const drop = Math.max(0, snap.rows - rows);
-  const pre = '\x1b[0m\x1b[H\x1b[2J';
-  try { host.vt.feed(pre); } catch { return null; }
-  return { pre, ansi, dropped: drop ? rowsToAnsi(snap, 0, drop) : [] };
-}
-
-/**
- * Put lines into scrollback without disturbing the screen.
- *
- * Printing is the only way in — there is no API for "append to history" — so the
- * lines are printed at the top and then pushed off it, and the screen is painted
- * back from the grid afterwards. Costs one repaint, which is why it only happens
- * when nothing else repainted.
- */
-function archiveLines(host, lines) {
-  let restore;
-  try { restore = snapshotToAnsi(host.vt.snapshot({ includeCells: true })); } catch { return; }
-  let bytes = '\x1b[0m\x1b[H\x1b[2J\x1b[1;1H' + lines.join('\r\n');
-  // A newline on the LAST row is what moves a row into scrollback, and it moves
-  // the top row — not the one just printed. Enough of them to clear the screen
-  // archives every line, whether they all fitted on it or not.
-  bytes += `\x1b[0m\x1b[${host.rows};1H` + '\r\n'.repeat(Math.min(lines.length, host.rows));
-  bytes += restore;
-  try { host.vt.feed(bytes); } catch { return; }
-  for (const sub of host.subs) sub.onData(bytes);
+  return host.controller?.want || { cols: host.cols, rows: host.rows };
 }
 
-/**
- * Decide what the rows a shrink pushed off the screen were: a copy, or history.
- *
- * A screenful of output within the window means the app answered SIGWINCH by
- * reprinting its screen, so those rows are about to appear again and archiving
- * them is what filled the scrollback with duplicates. Silence means they were the
- * only copy — a shell's log, a TUI that exited, an agent sitting idle — and
- * dropping them is what stopped a pane from scrolling all the way up.
- *
- * Deciding afterwards is the point: at resize time this is not yet knowable, and
- * both guesses are wrong for somebody. Waiting costs nothing visible — the rows in
- * question are off-screen either way — so the window is generous rather than tight,
- * because an agent TUI that debounces SIGWINCH must not be mistaken for one that
- * ignored it. A repaint that does arrive cancels this immediately (see onData).
- *
- * Only a session that stayed silent through TWO resizes stops being treated as
- * repainting: one slow frame would otherwise drop a Claude pane onto the plain
- * reflow path for good, which is the duplication this all started with.
- */
-function settleArchive(host) {
-  host.archiveTimer = null;
-  const pending = host.pendingArchive;
-  host.pendingArchive = null;
-  if (!pending) return;
-  host.silentResizes += 1;
-  if (host.silentResizes >= 2) host.repaints = false;
-  if (pending.length) archiveLines(host, pending);
+function notifyGrid(host, reset = false) {
+  for (const sub of host.subs) {
+    sub.onGrid(host.cols, host.rows, host.controller === sub, host.subs.size, reset);
+  }
 }
 
 /**
  * Move the session to the size its viewers imply.
  *
- * The grid is resized BEFORE the PTY: the app's SIGWINCH repaint then lands in a
- * grid that already has the new geometry, instead of one line of its frame being
- * measured against the old one.
- *
- * Every viewer is then repainted from the grid. A resize is the one moment the
- * browser's own reflow of its byte log is guaranteed to disagree with us, and an
- * app that doesn't repaint on SIGWINCH at all (a bash prompt, an agent sitting
- * idle) would otherwise leave that disagreement on screen until it next drew
- * something. Repainting from the grid costs one screen of bytes and makes the
- * pane authoritative again — the same argument as the repaint on attach.
+ * Ghostty performs ordinary terminal reflow. We deliberately do not clear,
+ * classify, carry, or synthesize history around it: those policies cannot know
+ * whether the foreground app will repaint and can destroy real output. Viewers
+ * receive the confirmed geometry before subsequent PTY output and perform the
+ * same ordinary reflow; full history serialization is reserved for attachment.
  */
 function applyGrid(host) {
   const { cols, rows } = effectiveGrid(host);
   if (cols === host.cols && rows === host.rows) return false;
-  // Only a screen that gets SMALLER in some dimension archives anything: rows are
-  // pushed off the top, or a narrower width rewraps them until they overflow. A
-  // screen that only grows takes rows back out of scrollback instead, and needs no
-  // help doing it — interfering there is what painted over the history a zoom-out
-  // had just recovered. So growing is left entirely alone, right down to not
-  // repainting: each emulator recovers its own rows, and the app's own repaint (or
-  // the next attach) settles any difference.
-  const shrinking = cols < host.cols || rows < host.rows;
   host.cols = cols;
   host.rows = rows;
-  const carried = shrinking ? carryScreen(host, cols, rows) : null;
-  // Viewers get the erase BEFORE they resize, in the same order the grid saw it,
-  // so their emulators skip the same reflow ours did.
-  if (carried) for (const sub of host.subs) sub.onData(carried.pre);
   try { host.vt.resize(cols, rows); } catch {}
   try { host.pty.resize(cols, rows); } catch {}
-  host.resizedAt = Date.now();
-  host.resizeBytes = 0;
-  if (carried) {
-    // Painted straight away, not deferred. Holding it back until the app had its
-    // say was tried, on the theory that an app reprinting its own frame makes our
-    // copy redundant — measured, it changes nothing, because such an app erases
-    // the screen before it prints. All deferring bought was a blank pane.
-    try { host.vt.feed(carried.ansi); } catch {}
-    for (const sub of host.subs) sub.onData(carried.ansi);
-    // Oldest first: a second resize before the verdict lands adds to the same
-    // batch rather than replacing it.
-    host.pendingArchive = [...(host.pendingArchive || []), ...carried.dropped];
-    if (host.archiveTimer) clearTimeout(host.archiveTimer);
-    host.archiveTimer = setTimeout(() => settleArchive(host), ARCHIVE_SETTLE_MS);
-    if (host.archiveTimer.unref) host.archiveTimer.unref();
-  }
-  let ansi = null;
-  if (!carried && shrinking) { try { ansi = snapshotToAnsi(host.vt.snapshot({ includeCells: true })); } catch {} }
-  for (const sub of host.subs) {
-    // `carried` doubles as the flag: the viewer's own emulator has to skip its
-    // reflow exactly when we skipped ours, or it archives what we did not — and it
-    // must not resize until the bytes above have been parsed at the OLD size.
-    sub.onGrid(cols, rows, host.subs.size > 1, host.subs.size, !!carried);
-    if (ansi) sub.onData(ansi);
-  }
+  notifyGrid(host, false);
   return true;
 }
 
 /**
- * Apply the grid once the requests stop arriving. The viewers that asked are
- * remembered so a request the grid can't honour (a big laptop attached beside a
- * phone) is still answered with the size that actually applies — a client that
- * hears nothing back would sit there drawing into a geometry it doesn't have.
+ * 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, sub) {
-  if (sub) host.pendingSizes.add(sub);
+function scheduleGrid(host) {
   if (host.gridTimer) clearTimeout(host.gridTimer);
   host.gridTimer = setTimeout(() => {
     host.gridTimer = null;
-    const pending = [...host.pendingSizes];
-    host.pendingSizes.clear();
-    if (applyGrid(host)) return; // applyGrid told everyone
-    for (const s of pending) {
-      if (host.subs.has(s)) s.onGrid(host.cols, host.rows, host.subs.size > 1, host.subs.size);
-    }
+    if (!applyGrid(host)) notifyGrid(host, false);
   }, RESIZE_SETTLE_MS);
   if (host.gridTimer.unref) host.gridTimer.unref();
 }
@@ -855,33 +678,16 @@ export function ensureRunning(session, cols = 120, rows = 34) {
   const term = pty.spawn('bash', ['-lc', full], {
     name: 'xterm-256color', cols, rows, cwd: workdir, env,
   });
-  const vt = ghostty.createTerminal({ cols, rows, scrollbackLimit: SCROLLBACK_LINES });
-  const isShell = (cliById(session.cli) || cliById('shell')).id === 'shell';
-
+  const vt = ghostty.createTerminal({ cols, rows, scrollbackLimit: SCROLLBACK_BYTES });
   const host = {
     id: session.id,
     pty: term,
     vt,
     cols,
     rows,
-    // Does this app reprint its screen after SIGWINCH? That decides whether the
-    // reflow on resize archives a duplicate of the screen or archives the log
-    // (see carryScreen). Every agent TUI repaints; a shell prompt does not, and
-    // its rewrapped scrollback is the real thing, not a copy. The guess is
-    // corrected below, because `vim` or a hand-typed `claude` breaks it.
-    repaints: !isShell,
-    resizedAt: 0,
-    resizeBytes: 0,
-    pendingArchive: null,
-    archiveTimer: null,
-    silentResizes: 0,
     subs: new Set(),
-    sizes: new Map(), // sub -> the grid that viewer can display
-    pendingSizes: new Set(), // subs whose request hasn't been answered yet
+    controller: null,
     gridTimer: null,
-    history: [],
-    historyBytes: 0,
-    historyDropped: false,
     startedAt: Date.now(),
     screenChangedAt: Date.now(),
     bells: 0,
@@ -890,27 +696,6 @@ export function ensureRunning(session, cols = 120, rows = 34) {
   term.onData((chunk) => {
     try { vt.feed(chunk); } catch (e) { console.error('[runner] vt.feed', e && e.message); }
 
-    // A screenful arriving after a resize means the app answered SIGWINCH by
-    // reprinting its screen. That settles the question settleArchive was waiting on
-    // — the rows it holds are about to be printed again, so archiving them would
-    // duplicate them — and it settles it NOW, whenever the frame happens to arrive,
-    // instead of when a timer says so.
-    if (host.resizedAt) {
-      if (Date.now() - host.resizedAt > ARCHIVE_SETTLE_MS + 150) host.resizedAt = 0;
-      else {
-        host.resizeBytes += chunk.length;
-        // A quarter screen of bytes is far more than a shell prompt redrawing
-        // itself and far less than a TUI frame.
-        if (host.resizeBytes > (host.cols * host.rows) / 4) {
-          host.resizedAt = 0;
-          host.repaints = true; // also catches `vim` or a hand-typed `claude` in a shell pane
-          host.silentResizes = 0;
-          host.pendingArchive = null; // a copy after all
-          if (host.archiveTimer) { clearTimeout(host.archiveTimer); host.archiveTimer = null; }
-        }
-      }
-    }
-
     // State detection rides the feed path: the grid is already current, so there
     // is nothing to poll and no subprocess to spawn.
     sampleScreen(host);
@@ -918,20 +703,12 @@ export function ensureRunning(session, cols = 120, rows = 34) {
       if (chunk.charCodeAt(i) === 7) { host.bells++; host.lastBellAt = Date.now(); }
     }
 
-    host.history.push(chunk);
-    host.historyBytes += chunk.length;
-    while (host.historyBytes > REPLAY_BYTES && host.history.length > 1) {
-      host.historyBytes -= host.history.shift().length;
-      host.historyDropped = true;
-    }
-
     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.archiveTimer) { clearTimeout(host.archiveTimer); host.archiveTimer = null; }
     try { vt.dispose(); } catch {}
     for (const sub of host.subs) sub.onExit();
     host.subs.clear();
@@ -945,25 +722,14 @@ export function ensureRunning(session, cols = 120, rows = 34) {
   return true;
 }
 
-/**
- * The bytes to replay for scrollback. A ring that has wrapped almost certainly
- * starts mid-escape-sequence, so drop everything before the first newline — the
- * repaint that follows is the authority for the visible screen either way.
- */
-function replayBytes(host) {
-  const joined = host.history.join('');
-  if (!host.historyDropped) return joined;
-  const nl = joined.indexOf('\n');
-  return nl >= 0 ? joined.slice(nl + 1) : joined;
-}
-
 /**
  * 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 the bytes that rebuild the screen: replayed
- * scrollback first, then a snapshot repaint on top as the authority.
+ * `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 attach(session, cols, rows) {
   ensureRunning(session, cols, rows);
@@ -974,48 +740,64 @@ export function attach(session, cols, rows) {
     onData: () => {},
     onExit: () => {},
     onGrid: () => {},
+    want: {
+      cols: Math.max(20, Math.min(400, Math.round(Number.isFinite(cols) ? cols : host.cols))),
+      rows: Math.max(5, Math.min(200, Math.round(Number.isFinite(rows) ? rows : host.rows))),
+    },
   };
   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, shared, viewers, clear) => { try { cb(c, r, shared, viewers, clear); } catch {} }; },
-    write: (d) => { try { host.pty.write(d); } catch {} },
-    // A request, not a command: the shared grid is recomputed from all viewers,
-    // and only once the requests settle.
+    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 = {
         cols: Math.max(20, Math.min(400, Math.round(c))),
         rows: Math.max(5, Math.min(200, Math.round(r))),
       };
-      const had = host.sizes.get(sub);
-      host.sizes.set(sub, want);
-      // A resync that changes nothing (tab focus, an unrelated pane opening) must
-      // not schedule anything — but the FIRST request from a viewer is always
-      // worth answering, so it learns the grid it joined.
+      const had = sub.want;
+      sub.want = want;
       if (had && had.cols === want.cols && had.rows === want.rows) return;
-      scheduleGrid(host, sub);
+      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 }); } catch { return null; }
+      try { snap = host.vt.snapshot({ includeCells: true, includeScrollback: true }); } catch { return null; }
       return {
-        replay: replayBytes(host),
-        ansi: snapshotToAnsi(snap),
+        ansi: snapshotToRestoreAnsi(snap),
         cols: snap.cols,
         rows: snap.rows,
         viewers: host.subs.size,
-        shared: host.subs.size > 1,
+        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);
-      host.sizes.delete(sub);
-      host.pendingSizes.delete(sub);
-      scheduleGrid(host); // the grid grows back for whoever is left
+      if (controlled) host.controller = host.subs.values().next().value || null;
+      notifyGrid(host, false);
+      if (controlled && host.controller) scheduleGrid(host);
     },
   };
 }

server/src/snapshot.js

@@ -116,48 +116,12 @@ function renderRow(cells, cols) {
   return out;
 }
 
-/**
- * Rows `from`..`to` as styled lines, ready to be PRINTED rather than placed —
- * for putting rows into scrollback, where a line has to be written and scrolled
- * off rather than positioned. Blank rows are kept as empty strings so the
- * archived block keeps its shape.
- */
-export function rowsToAnsi(snap, from, to) {
-  const grid = cellGrid(snap);
-  const out = [];
-  for (let row = Math.max(0, from); row < Math.min(snap.rows, to); row++) {
-    out.push(renderRow(grid[row], snap.cols));
-  }
-  return out;
-}
-
-/**
- * The rows placed absolutely, with NO erase and no buffer switch — for painting
- * into a screen whose other rows must survive.
- *
- * That is the case after a resize: growing pulls history back down out of
- * scrollback into the top rows, and erasing before painting would throw exactly
- * that away. The caller erased before the resize instead, so everything this does
- * not cover is already blank.
- */
-export function snapshotToRows(snap) {
-  const grid = cellGrid(snap);
-  let out = '\x1b[?25l\x1b[0m';
-  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\x1b[?25h`;
-  return out;
-}
-
 export function snapshotToAnsi(snap) {
   const grid = cellGrid(snap);
 
-  // Normalise the buffer first: a byte replay can leave the receiver on the
-  // alternate screen (or off it), and the repaint alone would then land on the
-  // wrong buffer. Reset attributes so nothing leaks in from what was showing,
-  // and hide the cursor so the repaint doesn't strobe across the screen.
+  // 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';
 
@@ -170,3 +134,27 @@ export function snapshotToAnsi(snap) {
   out += '\x1b[?25h';
   return out;
 }
+
+/**
+ * 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) => line.text || '');
+  let out = '\x1b[?1049l\x1b[?25l\x1b[0m\x1b[H\x1b[2J';
+  if (history.length) {
+    out += history.join('\r\n');
+    out += `\x1b[${snap.rows};1H` + '\r\n'.repeat(Math.min(history.length, snap.rows));
+  }
+  out += snapshotToAnsi(snap);
+  return out;
+}

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?.();
@@ -96,15 +88,6 @@ function selectionText(term: Terminal): string {
 // socket with this leading NUL sentinel, which real pty output never begins with.
 const MODE_CTRL = '\x00\x00AM:';
 
-// OSC 52 used to arrive constantly, because tmux emitted it for every mouse
-// selection in copy mode — hence a gate that only let a write through right
-// after a real Cmd/Ctrl+C. With tmux gone the only source is the AGENT itself
-// deliberately writing the clipboard, and nothing grants that permission
-// automatically: the text is stashed and the user's next Cmd+C copies it.
-function consumeOsc52CopyPermission(): boolean {
-  return false;
-}
-
 function legacyCopy(text: string): boolean {
   const prev = document.activeElement as HTMLElement | null;
   try {
@@ -162,22 +145,19 @@ export default function TerminalPane({
 }) {
   const hostRef = useRef<HTMLDivElement>(null);
   const termRef = useRef<Terminal | null>(null);
-  const resyncRef = useRef<() => void>(() => {});
+  const localLayoutRef = 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);
   // 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); // legacy tmux copy-mode hint
-  // How many browsers share this session's grid. >1 means the size is a
-  // compromise, which is worth showing rather than leaving as a mystery.
-  const [viewers, setViewers] = useState(0);
+  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.
@@ -223,30 +203,27 @@ export default function TerminalPane({
       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
@@ -259,104 +236,90 @@ export default function TerminalPane({
     // 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;
+      // 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' });
+    };
+    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;
       }
-      // There is no tmux copy-mode selection to fetch any more: scrollback is
-      // replayed into this terminal on attach, so every selection is local.
-      if ((e.metaKey || e.ctrlKey) && (e.key === 'c' || e.key === 'C') && tmuxSelectionPending) {
-        copyTmuxSelection();
+      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 */ }
+    let layoutFrame = 0;
+    const syncLocalLayout = () => {
+      cancelAnimationFrame(layoutFrame);
+      layoutFrame = requestAnimationFrame(() => {
+        const box = hostRef.current;
+        const root = box?.querySelector<HTMLElement>('.xterm');
+        const screen = box?.querySelector<HTMLElement>('.xterm-screen');
+        if (!box || !root || !screen) return;
+        const style = getComputedStyle(box);
+        const innerWidth = box.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+        const innerHeight = box.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom);
+        root.style.width = `${Math.max(innerWidth, Math.ceil(screen.getBoundingClientRect().width))}px`;
+        root.style.height = `${Math.max(innerHeight, Math.ceil(screen.getBoundingClientRect().height))}px`;
+      });
+    };
+    localLayoutRef.current = syncLocalLayout;
+    syncLocalLayout();
     // Re-measure once the webfont is ready (glyph width changes vs the fallback).
-    document.fonts?.ready.then(() => resync());
+    document.fonts?.ready.then(() => { resync(); syncLocalLayout(); });
 
     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.
@@ -387,6 +350,8 @@ export default function TerminalPane({
       setBooting(false);
     };
     const connect = () => {
+      controllerRef.current = false;
+      setController(false);
       setConn('connecting');
       setBooting(true);
       bootLive = true;
@@ -408,24 +373,28 @@ export default function TerminalPane({
         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);
-            // The server owns the grid and tells every viewer its size. Conform
-            // instead of assuming our own fit won: if a second device is
-            // attached the grid follows the smaller of us, and drawing into our
-            // own geometry instead would garble the screen.
-            else if (m.t === 'grid' || m.t === 'restore') {
-              if (m.cols > 0 && m.rows > 0 && (term.cols !== m.cols || term.rows !== m.rows)) {
-                // m.clear: the backend already sent us the bytes that erase this
-                // screen and archive the rows about to fall off it, so skip our own
-                // reflow — xterm rewraps the outgoing screen into scrollback harder
-                // than the grid does (119 lines against 80 over one drag), and that
-                // copy is the duplication. The empty write is a barrier: writes are
-                // asynchronous, so resizing outside its callback would apply the new
-                // size to bytes that were written for the old one.
-                if (m.clear) term.write('', () => { try { term.resize(m.cols, m.rows); } catch { /* ignore */ } });
-                else try { term.resize(m.cols, m.rows); } catch { /* ignore */ }
-              }
-              setViewers(m.viewers > 1 ? m.viewers : 0);
+            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 {
+                  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);
+                  }
+                  syncLocalLayout();
+                } 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;
@@ -442,12 +411,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);
@@ -457,40 +423,24 @@ 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;
-    };
-    resumeRef.current = () => { takeBack(); };
-
-    // Measure this pane and REQUEST that size. Deliberately does not call
-    // fit.fit(): resizing ourselves reflows our buffer against a geometry the
-    // session may never adopt (the grid follows the smallest viewer), and the
-    // in-flight bytes were written for the size we just left — so the screen is
-    // drawn twice, at two widths, and the difference lands in the scrollback.
-    // The server owns the grid; we conform when it tells us what it applied.
+    // 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 = () => {
-      if (handedOff) return;
-      // A collapsed or hidden pane measures as a couple of cells, and the grid
-      // follows the SMALLEST viewer — so asking from one would shrink the session
-      // for everybody actually looking at it.
       const box = hostRef.current;
       if (!box || box.clientWidth < 40 || box.clientHeight < 40) return;
       try {
         const d = fit.proposeDimensions();
-        if (d && d.cols > 0 && d.rows > 0) send({ t: 'r', cols: d.cols, rows: d.rows });
+        // Zoom is local presentation, not PTY geometry. Normalize the measured
+        // cells back to the 13px canonical font before sending a preference.
+        const scale = (Number(term.options.fontSize) || 13) / 13;
+        const cols = d ? Math.max(1, Math.floor(d.cols * scale)) : 0;
+        const rows = d ? Math.max(1, Math.floor(d.rows * scale)) : 0;
+        if (cols > 0 && rows > 0) send({ t: 'r', cols, rows });
       } catch { /* layout not ready */ }
     };
     // ResizeObserver fires every frame while a window is dragged or the sidebar
@@ -499,30 +449,27 @@ export default function TerminalPane({
       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(); };
+    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.
+    // Touch scrolling prefers browser-retained history. At the live bottom an
+    // app that tracks the mouse receives SGR wheel events from the controller.
     let touchY: number | null = null;
-    const onTouchStart = (e: TouchEvent) => { takeBack(); touchY = e.touches[0].clientY; };
+    const onTouchStart = (e: TouchEvent) => { touchY = e.touches[0].clientY; };
     const onTouchMove = (e: TouchEvent) => {
       if (touchY == null) return;
       const y = e.touches[0].clientY;
@@ -534,7 +481,11 @@ export default function TerminalPane({
         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` });
+          const inHistory = term.buffer.active.viewportY < term.buffer.active.baseY;
+          if (tracking && !inHistory) {
+            claimControl();
+            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);
         }
       }
@@ -553,12 +504,10 @@ export default function TerminalPane({
       if (bootTimer) clearTimeout(bootTimer);
       if (bootCheck) clearTimeout(bootCheck);
       if (resyncTimer) clearTimeout(resyncTimer);
+      cancelAnimationFrame(layoutFrame);
       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);
@@ -571,6 +520,7 @@ export default function TerminalPane({
       try { ws?.close(); } catch { /* ignore */ }
       term.dispose();
       termRef.current = null;
+      localLayoutRef.current = () => {};
     };
   }, [session.id]);
 
@@ -579,12 +529,13 @@ export default function TerminalPane({
     if (termRef.current) termRef.current.options.theme = THEMES[theme];
   }, [theme]);
 
-  // Zoom: adjust font size (100% = 13px) and refit.
+  // Zoom changes only this viewer. The canonical terminal rows/columns stay
+  // fixed, and the host becomes a two-dimensional viewport when cells grow.
   useEffect(() => {
     const t = termRef.current;
     if (!t) return;
     t.options.fontSize = Math.round((13 * zoom) / 100);
-    resyncRef.current();
+    localLayoutRef.current();
   }, [zoom]);
 
   // Move keyboard focus into the terminal whenever this pane becomes the active
@@ -631,6 +582,11 @@ 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>
@@ -638,9 +594,6 @@ export default function TerminalPane({
       <div className="term-host">
         <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
@@ -699,21 +652,7 @@ 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>
-        </div>
-      )}
-      {booting && conn !== 'exited' && conn !== 'handedoff' && (
+      {booting && conn !== 'exited' && (
         <div className="term-boot mono">
           {conn === 'connecting' ? 'connecting' : `starting ${cli?.label || session.cli}`}<span className="et-cursor" />
         </div>

web/src/styles.css

@@ -489,13 +489,6 @@ 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; }
-
 /* 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 +545,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 +558,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; padding: 10px 8px 8px 12px; background: var(--term-bg); overflow: auto; overscroll-behavior: contain; }
+/* 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 +588,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 { min-width: 100%; min-height: 100%; }
 .xterm .xterm-viewport { scrollbar-width: none; }
 .xterm .xterm-viewport::-webkit-scrollbar { width: 0; height: 0; display: none; }