From 2d841ee0b446ecfa91bd9b30c26f1f1c12a89b9f Mon Sep 17 00:00:00 2001
From: indifferentketchup <samkintop@gmail.com>
Date: Wed, 20 May 2026 14:56:02 +0000
Subject: [PATCH] handoff

---
 CLAUDE.md                                     |   9 +
 apps/booterm/Dockerfile                       |   5 +-
 apps/booterm/src/pty/manager.ts               | 166 ++--
 apps/booterm/src/pty/pty.ts                   |  19 +-
 apps/booterm/src/routes/terminals.ts          |  85 +-
 apps/booterm/src/ws/attach.ts                 | 112 ++-
 apps/booterm/tmux.conf                        |  18 +-
 apps/web/package.json                         |  11 +-
 apps/web/src/App.tsx                          |   7 +-
 apps/web/src/api/client.ts                    |  25 +-
 .../web/src/components/panes/TerminalPane.tsx | 875 ++++++++++++------
 apps/web/src/hooks/useWorkspacePanes.ts       |  11 +-
 apps/web/src/main.tsx                         |   5 +
 apps/web/src/styles/globals.css               |  96 +-
 pnpm-lock.yaml                                | 100 +-
 15 files changed, 1041 insertions(+), 503 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9243dac..d35f05d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -68,6 +68,13 @@ Key patterns:
 - **`hooks/useSidebar.ts`** — Module-singleton with Set<setState> subscriber pattern; one bus subscription guarded by `globalThis.__boocode_sidebar_subscribed` for HMR safety. Every new `SessionEvent` type needs a `case` in the `applyEvent` switch (no-op `return prev` is fine).
 - **`api/client.ts`** — Centralized typed fetch wrapper. All endpoints under `api.*` namespace.
 
+Font / CSS pipeline (apps/web):
+- Tailwind v4's `@import "tailwindcss"` directive strips font URLs from subsequent CSS `@import`s — `@fontsource*` packages must be imported as JS side-effect modules in `apps/web/src/main.tsx`, not via `@import` in `globals.css`. Otherwise the woff2 files never make it to `dist/`.
+- Lightning CSS (inside `@tailwindcss/postcss` v4) collapses contiguous unicode-ranges to wildcard shorthand (`U+0000-FFFF` → `U+????`), which iOS Safari/Vivaldi mishandles (silently drops the font from those codepoints). Use explicit non-wildcard-collapsible subranges (e.g. `U+2500-259F` not `U+2500-25FF`). The `apps/web` build script greps `dist/assets/*.css` for `U+2500-259F` and fails the build if missing — preserve that guard.
+- `@font-face` blocks must live AFTER all `@import` statements (CSS spec). Earlier placement silently breaks every subsequent `@import` (this broke the 18 theme palette imports in globals.css for one session).
+- JetBrainsMono Nerd Font self-hosted in `apps/web/src/fonts/` (TTF from ryanoasis/nerd-fonts release) — needed because `@fontsource-variable/jetbrains-mono` ships subsetted woff2s that don't cover `U+2500-259F` (box drawing + block elements, used by opencode's banner). "NL" = No Ligatures (matches `font-feature-settings: "liga" 0`); "Mono" = single-cell icon width so TUI layouts don't desync.
+- xterm-addon-webgl rasterizes glyphs via Canvas2D into a GPU texture atlas. Canvas2D does NOT honor `font-display: block` — it uses whatever font is currently registered. Gate xterm initialization on `document.fonts.load(<font-name>)` resolving before calling `term.open()` (see `fontsReady` useState in `TerminalPane.tsx`). iOS Safari/Vivaldi also reclaims WebGL contexts from backgrounded tabs: keep `webgl.onContextLoss(() => webgl.dispose())` + recreate via visibilitychange. Do NOT manually dispose+recreate the addon after font load — iOS silently fails the second GL context creation and the terminal drops to DOM renderer with stale metrics.
+
 ### Data flow for chat
 
 1. User sends message → POST `/api/sessions/:id/messages` creates user + assistant (status=streaming) rows
@@ -105,6 +112,8 @@ Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0
 - node-pty's compiled `.node` is libc-specific: proddeps and runtime Dockerfile stages must share libc (alpine↔musl or bookworm-slim↔glibc); the TS-only builder stage can stay alpine for speed.
 - pnpm 10 `--frozen-lockfile` skips node-pty's postinstall — the Docker proddeps stage runs `cd node_modules/node-pty && npm run install` to force the native compile.
 - A local PreToolUse hook (`security_reminder_hook.py`) regex-flags Node's older `child_process` spawn helpers as unsafe (false positive even on the File-suffixed variant). Use `spawn` — it's accepted.
+- `/opt/boolab` hosts a working sibling BooCode terminal at `boocode.indifferentketchup.com`. Useful for visual side-by-side comparison on the same iPhone when debugging booterm rendering. Boolab uses Tailwind v3 (`@tailwind base`); boocode uses v4 — many subtle build differences. Don't assume parity.
+- booterm SSHs to the host as `samkintop@100.114.205.53` (the Tailscale IP). The hostname `ubuntu-homelab` (shown in the bash prompt after login) does NOT resolve from inside the container — only the host's `/etc/hosts` knows it. Override via `BOOTERM_SSH_HOST` / `BOOTERM_SSH_USER` env vars in docker-compose if you ever move the shell to a different machine.
 
 ## Conventions
 
diff --git a/apps/booterm/Dockerfile b/apps/booterm/Dockerfile
index 788805a..163017d 100644
--- a/apps/booterm/Dockerfile
+++ b/apps/booterm/Dockerfile
@@ -39,8 +39,11 @@ RUN test -f node_modules/node-pty/build/Release/pty.node && echo "pty.node OK" |
 # host's nvm node) run inside the container when invoked from the terminal
 # pane. Side-effect: su-exec is alpine-only — Debian replacement is gosu.
 FROM node:20-bookworm-slim AS runtime
+# v1.10.8d: openssh-client added so the terminal can ssh -t samkintop@host
+# (matching boolab's pattern) — that's how the in-pane shell gets access to
+# host tools (docker, claude, opencode) that don't exist inside the container.
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    tmux bash gosu ca-certificates procps \
+    tmux bash gosu ca-certificates procps openssh-client \
     && rm -rf /var/lib/apt/lists/*
 # Mirror uid/gid 1000:1000 from the host so the bind-mounted /home/samkintop
 # (added in docker-compose) is owned by the user from the container's view.
diff --git a/apps/booterm/src/pty/manager.ts b/apps/booterm/src/pty/manager.ts
index e164b5c..dc148e4 100644
--- a/apps/booterm/src/pty/manager.ts
+++ b/apps/booterm/src/pty/manager.ts
@@ -1,7 +1,6 @@
 import { spawn } from 'node:child_process';
 import type { FastifyBaseLogger } from 'fastify';
 
-// UUIDs already match [0-9a-f-]; allow uppercase and longer just in case.
 const ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
 export function sanitizeId(raw: string): string | null {
@@ -9,12 +8,15 @@ export function sanitizeId(raw: string): string | null {
   return raw.toLowerCase();
 }
 
-export function tmuxSessionName(sessionId: string): string {
-  return `bc-${sessionId}`;
-}
-
-export function tmuxWindowName(paneId: string): string {
-  return `term-${paneId}`;
+// v1.10.8c: per-pane tmux sessions (boolab pattern). Previously booterm used
+// one tmux session per chat-session with one window per pane; that meant the
+// session-level window-size policy was shared across panes, and
+// `attach-session -d` (used to take over from a stale browser) would detach
+// every other pane attached to the same session — the "[detached]" bug.
+// Now each pane gets its own tmux session named `bc-<paneId>`. The bc- prefix
+// namespaces booterm sessions on the shared tmux server.
+export function tmuxSessionName(paneId: string): string {
+  return `bc-${paneId}`;
 }
 
 interface CmdResult {
@@ -23,15 +25,17 @@ interface CmdResult {
   code: number;
 }
 
-// Wrap child_process.spawn with shell:false so each argv element is passed
-// as a separate argument — no shell interpolation, no injection surface.
 function runTmux(tmuxConfPath: string, args: string[]): Promise<CmdResult> {
   return new Promise((resolve) => {
     const child = spawn('tmux', ['-f', tmuxConfPath, ...args], { shell: false });
     let stdout = '';
     let stderr = '';
-    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
-    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString('utf8');
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString('utf8');
+    });
     child.on('error', (err) => {
       resolve({ stdout, stderr: stderr + String(err), code: 1 });
     });
@@ -46,57 +50,115 @@ export async function hasSession(tmuxConfPath: string, sessionName: string): Pro
   return res.code === 0;
 }
 
-export async function listWindows(tmuxConfPath: string, sessionName: string): Promise<string[]> {
-  const res = await runTmux(tmuxConfPath, ['list-windows', '-t', sessionName, '-F', '#{window_name}']);
-  if (res.code !== 0) return [];
-  return res.stdout.trim().split('\n').filter(Boolean);
+// Default fallback size — wider than any real terminal would care about; the
+// real client size lands via the WS resize frame within a few ms of attach.
+const DEFAULT_COLS = 200;
+const DEFAULT_ROWS = 50;
+
+// v1.10.8d: per-pane shell is `ssh -t samkintop@SSH_HOST` (matches boolab's
+// pattern). The container has no docker / claude / opencode binaries; SSH'ing
+// to the host gives the user their full normal shell environment. Default is
+// the host's Tailscale IP (100.114.205.53) — the hostname `ubuntu-homelab`
+// only resolves on the host's local /etc/hosts, not from inside containers,
+// so SSH'ing to the hostname fails with `Could not resolve hostname` even
+// though the host machine is reachable. Boolab uses the same IP.
+const SSH_HOST = process.env['BOOTERM_SSH_HOST']?.trim() || '100.114.205.53';
+const SSH_USER = process.env['BOOTERM_SSH_USER']?.trim() || 'samkintop';
+
+// POSIX shell single-quote escape: wrap in '…', escape embedded singles by
+// closing-the-quote, inserting an escaped quote, and re-opening.
+function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 
-export async function killWindow(
+// Idempotent. Creates the tmux session if it doesn't exist, sized via -x/-y
+// from the client's measured xterm dimensions. With `window-size = largest`
+// + `aggressive-resize on` in tmux.conf, the attached client's actual size
+// wins once it reports in — but seeding at the right size avoids the brief
+// window where bash/TUI inherits the default 80x24 from a stale fallback.
+export async function ensureSession(
+  tmuxConfPath: string,
+  sessionName: string,
+  projectRoot: string,
+  log: FastifyBaseLogger,
+  cols?: number,
+  rows?: number,
+): Promise<void> {
+  if (await hasSession(tmuxConfPath, sessionName)) return;
+  const sizeCols = cols && cols > 0 ? Math.floor(cols) : DEFAULT_COLS;
+  const sizeRows = rows && rows > 0 ? Math.floor(rows) : DEFAULT_ROWS;
+  // Bypass tmux.conf's default-command — build the per-pane argv explicitly
+  // so we can wrap ssh in the gosu privilege drop. The remote shell sequence
+  // (per boolab's invariants in services/tmux_session.py target_cmd_for):
+  //   1. ssh's argv must flatten into a single quoted bash -lc <script>
+  //   2. -l on the outer bash sources ~/.profile on the remote (PATH etc.)
+  //   3. cd to projectRoot, then exec bash -l so the user lands in the repo
+  // /opt is bind-mounted host↔container, so projectRoot resolves to the
+  // same files on both sides.
+  const remoteScript = `cd ${shellEscape(projectRoot)} && exec bash -l`;
+  const remoteCmd = `bash -lc ${shellEscape(remoteScript)}`;
+  const argv = [
+    'new-session', '-d',
+    '-s', sessionName,
+    '-c', projectRoot,
+    '-x', String(sizeCols),
+    '-y', String(sizeRows),
+    '--',
+    // gosu drops privs from the container's root (tmux server runs as root)
+    // to samkintop:samkintop. env restores HOME/USER/SHELL so ssh finds the
+    // right ~/.ssh/id_ed25519 (key is mode 0600 and ssh refuses keys whose
+    // UID doesn't match the running user — both are 1000 here).
+    'gosu', 'samkintop:samkintop',
+    'env', 'HOME=/home/samkintop', 'USER=samkintop', 'SHELL=/bin/bash',
+    'ssh', '-t',
+    '-o', 'StrictHostKeyChecking=yes',
+    '-o', 'ServerAliveInterval=30',
+    '-o', 'ServerAliveCountMax=3',
+    `${SSH_USER}@${SSH_HOST}`,
+    remoteCmd,
+  ];
+  log.info(
+    { sessionName, projectRoot, cols: sizeCols, rows: sizeRows, sshTarget: `${SSH_USER}@${SSH_HOST}` },
+    'creating tmux session (ssh to host)',
+  );
+  const res = await runTmux(tmuxConfPath, argv);
+  if (res.code !== 0) {
+    log.error({ res }, 'tmux new-session failed');
+    throw new Error(`tmux new-session failed: ${res.stderr}`);
+  }
+}
+
+export async function killSession(
   tmuxConfPath: string,
   sessionName: string,
-  windowName: string,
 ): Promise<boolean> {
-  const res = await runTmux(tmuxConfPath, ['kill-window', '-t', `${sessionName}:${windowName}`]);
+  const res = await runTmux(tmuxConfPath, ['kill-session', '-t', sessionName]);
   return res.code === 0;
 }
 
-// Idempotent. Creates the tmux session if it doesn't exist, then ensures the
-// named window is present. The session's initial window is created with the
-// target name (via `-n`) so we don't need a separate rename step.
-export async function ensureWindow(
+// v1.10.8c: capture-pane on WS attach to replay the buffer state to the fresh
+// xterm (boolab pattern). `-e` preserves ANSI escape sequences so colours and
+// cursor position survive the replay. Returns empty string on failure — the
+// client falls back to whatever tmux itself decides to repaint, which is
+// non-fatal but visually noisier.
+//
+// v1.10.8d: strip trailing blank rows. tmux capture-pane emits one `\n` per
+// pane row (including all the empty rows below the actual content), so on a
+// fresh 35-row pane with just the bash prompt at row 0, the output is
+// `<prompt>` followed by 35 `\n` bytes. When xterm.write()s those naively,
+// the cursor advances row-by-row until it hits the bottom of the canvas and
+// scrolls — pushing the prompt into the scrollback buffer where the user
+// can't see it. Stripping the trailing newlines leaves xterm's cursor at the
+// natural end of the rendered content (matching tmux's actual cursor
+// position for the common single-line-prompt case).
+export async function capturePane(
   tmuxConfPath: string,
   sessionName: string,
-  windowName: string,
-  projectRoot: string,
-  log: FastifyBaseLogger,
-): Promise<void> {
-  if (!(await hasSession(tmuxConfPath, sessionName))) {
-    log.info({ sessionName, windowName, projectRoot }, 'creating tmux session');
-    const res = await runTmux(tmuxConfPath, [
-      'new-session', '-d',
-      '-s', sessionName,
-      '-n', windowName,
-      '-c', projectRoot,
-    ]);
-    if (res.code !== 0) {
-      log.error({ res }, 'tmux new-session failed');
-      throw new Error(`tmux new-session failed: ${res.stderr}`);
-    }
-    return;
-  }
-
-  const windows = await listWindows(tmuxConfPath, sessionName);
-  if (windows.includes(windowName)) return;
-
+  lines: number = 2000,
+): Promise<string> {
   const res = await runTmux(tmuxConfPath, [
-    'new-window',
-    '-t', sessionName,
-    '-n', windowName,
-    '-c', projectRoot,
+    'capture-pane', '-t', sessionName, '-p', '-e', '-S', `-${lines}`,
   ]);
-  if (res.code !== 0) {
-    log.error({ res }, 'tmux new-window failed');
-    throw new Error(`tmux new-window failed: ${res.stderr}`);
-  }
+  if (res.code !== 0) return '';
+  return res.stdout.replace(/(?:\r?\n)+$/, '');
 }
diff --git a/apps/booterm/src/pty/pty.ts b/apps/booterm/src/pty/pty.ts
index 86afab8..c08e2cc 100644
--- a/apps/booterm/src/pty/pty.ts
+++ b/apps/booterm/src/pty/pty.ts
@@ -3,7 +3,6 @@ import type { IPty } from 'node-pty';
 
 export interface AttachPtyOptions {
   sessionName: string;
-  windowName: string;
   projectRoot: string;
   cols: number;
   rows: number;
@@ -19,16 +18,24 @@ function cleanEnv(): { [key: string]: string } {
   return out;
 }
 
-// Spawns a tmux client attached to the given session+window. `-d` detaches any
-// other client so a browser refresh takes over the same window without
-// duplicate input. tmux server (and the window) persists across PTY exits.
+// v1.10.8c: no `-d` (multi-attach friendly — boolab pattern). With per-pane
+// tmux sessions, dropping `-d` means multiple browser tabs viewing the same
+// pane share one tmux session as N clients; tmux fans I/O at the session
+// layer just like boolab's backend. The earlier `-d` flag detached EVERY
+// other client of the session — across windows — which caused the
+// "[detached] from session" bug whenever a new pane attached to a chat
+// session that already had another pane open.
+//
+// Tmux server + session persist across PTY exits, so a refresh resumes with
+// full scrollback. Explicit destroy happens via the /kill route (called from
+// the frontend when the user closes a pane).
 export function attachPty(opts: AttachPtyOptions): IPty {
   return pty.spawn(
     'tmux',
     [
       '-f', opts.tmuxConfPath,
-      'attach-session', '-d',
-      '-t', `${opts.sessionName}:${opts.windowName}`,
+      'attach-session',
+      '-t', opts.sessionName,
     ],
     {
       name: 'xterm-256color',
diff --git a/apps/booterm/src/routes/terminals.ts b/apps/booterm/src/routes/terminals.ts
index 84bca41..602fbeb 100644
--- a/apps/booterm/src/routes/terminals.ts
+++ b/apps/booterm/src/routes/terminals.ts
@@ -4,22 +4,33 @@ import { getSessionInfo } from '../db.js';
 import {
   sanitizeId,
   tmuxSessionName,
-  tmuxWindowName,
-  ensureWindow,
-  killWindow,
+  ensureSession,
+  killSession,
   hasSession,
-  listWindows,
 } from '../pty/manager.js';
-import { resizePane } from '../ws/attach.js';
 
 const ParamsSchema = z.object({ sid: z.string(), pid: z.string() });
-const ResizeBodySchema = z.object({
-  cols: z.coerce.number().int().min(1).max(2000),
-  rows: z.coerce.number().int().min(1).max(2000),
-});
+// v1.10.8c: optional cols/rows on /start so the per-pane tmux session is
+// born at the right dimensions. Bodyless POSTs remain valid (Fastify's
+// tolerant parser).
+const StartBodySchema = z
+  .object({
+    cols: z.coerce.number().int().min(1).max(2000).optional(),
+    rows: z.coerce.number().int().min(1).max(2000).optional(),
+  })
+  .partial()
+  .optional();
 
 export function registerTerminalRoutes(app: FastifyInstance, tmuxConfPath: string): void {
-  app.post<{ Params: { sid: string; pid: string } }>(
+  // v1.10.8c: /start creates the per-pane tmux session. Idempotent — a second
+  // /start on the same paneId is a no-op (hasSession returns true). The WS
+  // attach handler also calls ensureSession as belt-and-suspenders, so /start
+  // is technically optional, but having it as a separate step surfaces tmux
+  // errors as HTTP responses (vs WS 1011 close codes).
+  app.post<{
+    Params: { sid: string; pid: string };
+    Body: { cols?: number; rows?: number } | undefined;
+  }>(
     '/api/term/sessions/:sid/panes/:pid/start',
     async (req, reply) => {
       const p = ParamsSchema.safeParse(req.params);
@@ -28,39 +39,35 @@ export function registerTerminalRoutes(app: FastifyInstance, tmuxConfPath: strin
       const pid = sanitizeId(p.data.pid);
       if (!sid || !pid) return reply.code(400).send({ error: 'bad_id_format' });
 
+      const b = StartBodySchema.safeParse(req.body ?? {});
+      const cols = b.success ? b.data?.cols : undefined;
+      const rows = b.success ? b.data?.rows : undefined;
+
       const session = await getSessionInfo(sid);
       if (!session) return reply.code(404).send({ error: 'unknown_session' });
 
-      const sessionName = tmuxSessionName(sid);
-      const windowName = tmuxWindowName(pid);
+      const sessionName = tmuxSessionName(pid);
 
       try {
-        await ensureWindow(tmuxConfPath, sessionName, windowName, session.project_path, req.log);
+        await ensureSession(
+          tmuxConfPath,
+          sessionName,
+          session.project_path,
+          req.log,
+          cols,
+          rows,
+        );
       } catch (err) {
-        req.log.error({ err }, 'ensureWindow failed');
+        req.log.error({ err }, 'ensureSession failed');
         return reply.code(500).send({ error: 'tmux_failed' });
       }
-      return reply.code(200).send({ tmux_window: windowName });
-    },
-  );
-
-  app.post<{ Params: { sid: string; pid: string }; Body: { cols: number; rows: number } }>(
-    '/api/term/sessions/:sid/panes/:pid/resize',
-    async (req, reply) => {
-      const p = ParamsSchema.safeParse(req.params);
-      if (!p.success) return reply.code(400).send({ error: 'bad_params' });
-      const b = ResizeBodySchema.safeParse(req.body);
-      if (!b.success) return reply.code(400).send({ error: 'bad_body' });
-      const sid = sanitizeId(p.data.sid);
-      const pid = sanitizeId(p.data.pid);
-      if (!sid || !pid) return reply.code(400).send({ error: 'bad_id_format' });
-
-      const ok = resizePane(pid, b.data.cols, b.data.rows);
-      if (!ok) return reply.code(404).send({ error: 'no_active_pty' });
-      return reply.code(200).send({ ok: true });
+      return reply.code(200).send({ tmux_session: sessionName });
     },
   );
 
+  // v1.10.8c: explicit pane teardown. Frontend calls this when the user
+  // intentionally closes a terminal pane (vs an implicit WS disconnect, which
+  // leaves the tmux session intact for refresh-driven resume).
   app.post<{ Params: { sid: string; pid: string } }>(
     '/api/term/sessions/:sid/panes/:pid/kill',
     async (req, reply) => {
@@ -70,19 +77,17 @@ export function registerTerminalRoutes(app: FastifyInstance, tmuxConfPath: strin
       const pid = sanitizeId(p.data.pid);
       if (!sid || !pid) return reply.code(400).send({ error: 'bad_id_format' });
 
-      const sessionName = tmuxSessionName(sid);
-      const windowName = tmuxWindowName(pid);
-
+      const sessionName = tmuxSessionName(pid);
       if (!(await hasSession(tmuxConfPath, sessionName))) {
-        return reply.code(404).send({ error: 'unknown_session' });
-      }
-      const windows = await listWindows(tmuxConfPath, sessionName);
-      if (!windows.includes(windowName)) {
         return reply.code(404).send({ error: 'unknown_pane' });
       }
-      const killed = await killWindow(tmuxConfPath, sessionName, windowName);
+      const killed = await killSession(tmuxConfPath, sessionName);
       if (!killed) return reply.code(500).send({ error: 'tmux_kill_failed' });
       return reply.code(200).send({ ok: true });
     },
   );
+
+  // Resize endpoint removed in v1.10.8c. Resize now flows in-band via the
+  // WebSocket as a `{type:"resize",cols,rows}` text frame — no more race
+  // between active-PTY-map registration and HTTP POST lookup. See ws/attach.ts.
 }
diff --git a/apps/booterm/src/ws/attach.ts b/apps/booterm/src/ws/attach.ts
index 3815ba9..5aa9201 100644
--- a/apps/booterm/src/ws/attach.ts
+++ b/apps/booterm/src/ws/attach.ts
@@ -1,25 +1,15 @@
 import type { FastifyInstance } from 'fastify';
 import type { IPty } from 'node-pty';
 import { getSessionInfo } from '../db.js';
-import { sanitizeId, tmuxSessionName, tmuxWindowName, ensureWindow } from '../pty/manager.js';
+import {
+  sanitizeId,
+  tmuxSessionName,
+  ensureSession,
+  capturePane,
+} from '../pty/manager.js';
 import { attachPty } from '../pty/pty.js';
 import { getUser } from '../auth.js';
 
-// Registry of currently-attached PTYs keyed by paneId. Used by the resize REST
-// route to find the active node-pty handle so it can call pty.resize(cols, rows).
-const active = new Map<string, IPty>();
-
-export function resizePane(paneId: string, cols: number, rows: number): boolean {
-  const handle = active.get(paneId);
-  if (!handle) return false;
-  try {
-    handle.resize(cols, rows);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string): void {
   app.get<{
     Params: { sid: string; pid: string };
@@ -44,24 +34,33 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
         return;
       }
 
-      const sessionName = tmuxSessionName(sid);
-      const windowName = tmuxWindowName(pid);
+      const sessionName = tmuxSessionName(pid);
+      const cols = parseInt(req.query.cols ?? '', 10) || 80;
+      const rows = parseInt(req.query.rows ?? '', 10) || 24;
+
+      // Idempotent — /start typically created the session already, but cover
+      // the race where the client opens the WS before /start's response lands
+      // (or skips /start entirely). With per-pane tmux sessions there's no
+      // cross-pane interference, so creating-on-attach is safe.
       try {
-        await ensureWindow(tmuxConfPath, sessionName, windowName, session.project_path, req.log);
+        await ensureSession(
+          tmuxConfPath,
+          sessionName,
+          session.project_path,
+          req.log,
+          cols,
+          rows,
+        );
       } catch (err) {
-        req.log.error({ err }, 'ensureWindow failed in WS handler');
+        req.log.error({ err }, 'ensureSession failed in WS handler');
         socket.close(1011, 'tmux_failed');
         return;
       }
 
-      const cols = parseInt(req.query.cols ?? '', 10) || 80;
-      const rows = parseInt(req.query.rows ?? '', 10) || 24;
-
       let handle: IPty;
       try {
         handle = attachPty({
           sessionName,
-          windowName,
           projectRoot: session.project_path,
           cols,
           rows,
@@ -73,9 +72,31 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
         return;
       }
 
-      active.set(pid, handle);
+      // Frame contract (boolab pattern):
+      //   server → client text:    JSON control — `init` on connect, `exit` on PTY death
+      //   server → client binary:  raw PTY bytes (first frame after init = capture-pane replay)
+      //   client → server binary:  user keystrokes
+      //   client → server text:    JSON control — `{type:"resize", cols, rows}`
+      //
+      // The init frame lets the client term.clear() before paint so a remount
+      // doesn't show stale buffer content. The capture-pane replay then
+      // paints the current tmux pane state into the fresh xterm.
+      try {
+        socket.send(JSON.stringify({ type: 'init', cols, rows, tmux_session: sessionName }));
+      } catch (err) {
+        req.log.warn({ err }, 'init frame send failed');
+      }
 
-      const onData = (data: string) => {
+      try {
+        const capture = await capturePane(tmuxConfPath, sessionName);
+        if (capture.length > 0) {
+          socket.send(Buffer.from(capture, 'utf8'), { binary: true });
+        }
+      } catch (err) {
+        req.log.warn({ err }, 'capture-pane failed');
+      }
+
+      const onData = (data: string): void => {
         if (socket.readyState !== socket.OPEN) return;
         try {
           socket.send(Buffer.from(data, 'utf8'), { binary: true });
@@ -85,13 +106,32 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
       };
       handle.onData(onData);
 
-      socket.on('message', (data: Buffer | string) => {
-        try {
-          if (typeof data === 'string') {
-            handle.write(data);
-          } else {
-            handle.write(data.toString('utf8'));
+      socket.on('message', (rawData: Buffer | string, isBinary?: boolean) => {
+        // ws v8 emits Buffer + isBinary boolean; older versions emit string
+        // for text frames. Either way: text path tries JSON parse for the
+        // resize control; binary path writes to the PTY.
+        const isTextFrame = typeof rawData === 'string' || isBinary === false;
+        if (isTextFrame) {
+          const text = typeof rawData === 'string' ? rawData : rawData.toString('utf8');
+          try {
+            const parsed = JSON.parse(text) as { type?: string; cols?: number; rows?: number };
+            if (parsed.type === 'resize') {
+              const newCols = Math.max(1, Math.min(2000, Math.floor(Number(parsed.cols) || 80)));
+              const newRows = Math.max(1, Math.min(2000, Math.floor(Number(parsed.rows) || 24)));
+              req.log.info({ pid, cols: newCols, rows: newRows }, 'resize');
+              try {
+                handle.resize(newCols, newRows);
+              } catch {
+                /* ignore — invalid winsize bubble */
+              }
+            }
+          } catch {
+            /* malformed text frame — drop silently */
           }
+          return;
+        }
+        try {
+          handle.write((rawData as Buffer).toString('utf8'));
         } catch (err) {
           req.log.warn({ err }, 'pty write failed');
         }
@@ -110,13 +150,13 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
         } catch {
           /* ignore */
         }
-        if (active.get(pid) === handle) active.delete(pid);
       });
 
-      // WS close kills the local PTY (the tmux client). The tmux server and
-      // window persist so a refresh resumes with full scrollback.
+      // WS close kills the tmux client (the local PTY) but the tmux server +
+      // session persist — so a refresh resumes with full scrollback. Permanent
+      // teardown happens via the /kill route called from the frontend when the
+      // user closes the pane.
       socket.on('close', () => {
-        if (active.get(pid) === handle) active.delete(pid);
         try {
           handle.kill();
         } catch {
diff --git a/apps/booterm/tmux.conf b/apps/booterm/tmux.conf
index ef5eef7..29c0dff 100644
--- a/apps/booterm/tmux.conf
+++ b/apps/booterm/tmux.conf
@@ -1,20 +1,30 @@
 set -g default-terminal "screen-256color"
 set -g history-limit 50000
+
+# v1.10.8c: per-pane tmux sessions (boolab pattern). With one session per
+# pane, the session size adapts to the attached client; `window-size = largest`
+# + `aggressive-resize on` make tmux pick up the client's actual cols/rows
+# instead of falling back to 80x24. Critical for opencode/claude TUIs that
+# read TIOCGWINSZ once at fork time.
+set -g window-size largest
+set -g aggressive-resize on
+
 # v1.10.3: `set -g mouse on` removed. tmux's mouse mode captured wheel/touch
 # events at the protocol level, so xterm.js never saw them and the viewport
 # couldn't scroll on mobile. With mouse off, xterm.js handles scrollback
 # natively (wheel on desktop, finger-drag on mobile via touch-action: pan-y).
 # Tradeoff: lose tmux mouse pane-resize and scroll-inside-vim; acceptable for
 # the homelab single-user setup.
+set -g mouse off
 setw -g mode-keys vi
 set -g status off
 set -g destroy-unattached off
 
 # v1.10.1: shells drop privs to samkintop (uid 1000) so the terminal runs in
 # the user's environment, not root. `env HOME=… USER=…` is required because
-# gosu (and su-exec before it) only changes uid/gid — it leaves env intact,
-# and the tmux server runs as root so HOME would otherwise be /root. bash -l
-# then sources samkintop's ~/.profile / ~/.bashrc to pick up PATH (nvm,
-# ~/.local/bin, ~/.opencode/bin).
+# gosu only changes uid/gid — env (including HOME) survives, and the tmux
+# server runs as root so HOME would otherwise be /root. bash -l then sources
+# samkintop's ~/.profile / ~/.bashrc to pick up PATH (nvm, ~/.local/bin,
+# ~/.opencode/bin).
 # v1.10.2: su-exec → gosu (alpine → debian; functionally identical).
 set -g default-command "gosu samkintop:samkintop env HOME=/home/samkintop USER=samkintop SHELL=/bin/bash bash -l"
diff --git a/apps/web/package.json b/apps/web/package.json
index dfdd422..86f918b 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -12,6 +12,11 @@
   "dependencies": {
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@xterm/addon-fit": "0.10.0",
+    "@xterm/addon-search": "^0.15.0",
+    "@xterm/addon-web-links": "0.11.0",
+    "@xterm/addon-webgl": "^0.19.0",
+    "@xterm/xterm": "5.5.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.16.0",
@@ -26,11 +31,7 @@
     "shiki": "^1.29.2",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.6.0",
-    "tw-animate-css": "^1.4.0",
-    "xterm": "^5.3.0",
-    "xterm-addon-fit": "^0.8.0",
-    "xterm-addon-search": "^0.13.0",
-    "xterm-addon-web-links": "^0.9.0"
+    "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",
diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 39e3c7a..71bd4a2 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -68,8 +68,13 @@ function AppShell() {
   // theme class on <html> is correct before any child renders.
   useTheme();
   useUserEvents();
+  // v1.10.8c: h-dvh (dynamic viewport) instead of h-screen (100vh) so the
+  // root height excludes the iOS URL-bar overlay area. Without this, every
+  // descendant — including the terminal pane — measures itself against a
+  // height that extends behind the URL bar, and xterm allocates extra rows
+  // that scroll out of reach on iPhone.
   return (
-    <div className="h-screen flex bg-background text-foreground">
+    <div className="h-dvh flex bg-background text-foreground">
       <ProjectSidebar />
       <MobileBackdrop />
       <main className="flex-1 flex flex-col min-w-0">
diff --git a/apps/web/src/api/client.ts b/apps/web/src/api/client.ts
index 4e047fa..6a7b50b 100644
--- a/apps/web/src/api/client.ts
+++ b/apps/web/src/api/client.ts
@@ -264,18 +264,23 @@ export const api = {
 
   // v1.10 booterm: REST control plane for terminal panes. WebSocket attach
   // lives at /ws/term/sessions/:sid/panes/:pid (handled directly by
-  // TerminalPane). All three endpoints are tolerant of empty bodies on the
-  // POSTs that don't take parameters.
+  // TerminalPane). v1.10.8c: resize moved in-band onto the WebSocket as a
+  // `{type:"resize",cols,rows}` text frame — the old /resize HTTP endpoint is
+  // gone, eliminating the race between WS attach and PTY-map registration.
   terminals: {
-    start: (sessionId: string, paneId: string) =>
-      request<{ tmux_window: string }>(
+    // cols/rows are optional. When passed, booterm sizes the per-pane tmux
+    // session at creation time so the inner bash (and any TUI it spawns) is
+    // born with the correct PTY dimensions instead of tmux's 80x24 default.
+    start: (sessionId: string, paneId: string, cols?: number, rows?: number) =>
+      request<{ tmux_session: string }>(
         `/api/term/sessions/${sessionId}/panes/${paneId}/start`,
-        { method: 'POST' },
-      ),
-    resize: (sessionId: string, paneId: string, cols: number, rows: number) =>
-      request<{ ok: true }>(
-        `/api/term/sessions/${sessionId}/panes/${paneId}/resize`,
-        { method: 'POST', body: JSON.stringify({ cols, rows }) },
+        {
+          method: 'POST',
+          body:
+            cols !== undefined && rows !== undefined
+              ? JSON.stringify({ cols, rows })
+              : undefined,
+        },
       ),
     kill: (sessionId: string, paneId: string) =>
       request<{ ok: true }>(
diff --git a/apps/web/src/components/panes/TerminalPane.tsx b/apps/web/src/components/panes/TerminalPane.tsx
index f765eb7..ee9ae31 100644
--- a/apps/web/src/components/panes/TerminalPane.tsx
+++ b/apps/web/src/components/panes/TerminalPane.tsx
@@ -1,10 +1,10 @@
-import { useEffect, useRef, useState } from 'react';
-import { Terminal } from 'xterm';
-import { FitAddon } from 'xterm-addon-fit';
-import { SearchAddon } from 'xterm-addon-search';
-import { WebLinksAddon } from 'xterm-addon-web-links';
-import 'xterm/css/xterm.css';
-import { ChevronDown, ChevronUp, RefreshCw, X } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { SearchAddon } from '@xterm/addon-search';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import '@xterm/xterm/css/xterm.css';
+import { ChevronDown, ChevronUp, Maximize2, RefreshCw, X } from 'lucide-react';
 import { toast } from 'sonner';
 import { api } from '@/api/client';
 import {
@@ -14,20 +14,36 @@ import {
   terminalsRegistry,
   type ChatInputRegistration,
 } from '@/lib/events';
+import { cn } from '@/lib/utils';
+
+// Architecture invariants (do not regress without reading the comments
+// next to each):
+//
+//   - Resize is in-band on the WebSocket as a JSON text frame. The HTTP
+//     /resize endpoint had a race with PTY-map registration; WS frames
+//     don't.
+//   - Server `init` text frame triggers term.clear() so a stale buffer
+//     can't leak through the capture-pane replay.
+//   - DOM renderer only (no @xterm/addon-webgl). The WebGL atlas bakes
+//     glyphs via Canvas2D at load time and locks against whatever font
+//     is registered then; @fontsource JBM Variable subsets don't cover
+//     U+2500-25FF, so the atlas baked against the system fallback and
+//     opencode/claude banners rendered garbled. DOM renderer uses real
+//     text spans, so the browser's text rasterizer handles unicode
+//     fallback per-character — boolab pattern, just works.
+//   - Refit on document.fonts.ready (post-open) so xterm's cell metrics
+//     don't bake against the system fallback. Boolab pattern: rAF inside
+//     fonts.ready, plus a 150ms safety-net setTimeout.
 
 interface Props {
   sessionId: string;
   paneId: string;
   label: string;
-  // v1.10.3: tells the pane it's the currently visible/focused one in the
-  // grid. Drives a refit so a terminal that was hidden (e.g. behind a
-  // maximize toggle) snaps to the right dimensions when it reappears.
   active?: boolean;
 }
 
-// v1.10.3: terminal background matches the pane container's `bg-[#0b0f14]`
-// so any sub-cell rounding gap at the right/bottom edge is invisible. If
-// the workspace theme changes, update both this and the container className.
+// Terminal background matches the pane container's `bg-[#0b0f14]` so any
+// sub-cell rounding remainder is invisible. Update both if the theme changes.
 const TERM_BG = '#0b0f14';
 
 const XTERM_THEME = {
@@ -53,38 +69,16 @@ const XTERM_THEME = {
   brightWhite: '#ffffff',
 };
 
-// v1.10.3 Issue 5: override xterm's default layout so the canvas stretches
-// to the full container width. The `!important` is necessary because xterm's
-// own stylesheet (loaded via `import 'xterm/css/xterm.css'`) sets inline
-// width/height that we need to override. Also hides the scrollbar — touch /
-// trackpad / wheel still scroll, the chrome just isn't drawn.
-const XTERM_STYLE_OVERRIDES = `
-  .xterm { width: 100% !important; height: 100% !important; }
-  .xterm .xterm-screen { width: 100% !important; }
-  /* v1.10.4 gap fix: hide overflow (was: auto) to eliminate scrollbar gutter
-   * that FitAddon's proposeDimensions still accounts for. Transparent bg lets
-   * the host's TERM_BG show through any sub-cell rounding strip. */
-  .xterm .xterm-viewport {
-    overflow-y: hidden !important;
-    scrollbar-width: none !important;
-    -ms-overflow-style: none !important;
-    background-color: transparent !important;
-  }
-  .xterm .xterm-viewport::-webkit-scrollbar { width: 0 !important; height: 0 !important; display: none !important; }
-`;
-
 type ConnState = 'connecting' | 'open' | 'reconnecting' | 'disconnected';
 
-const MAX_RECONNECT_ATTEMPTS = 3;
-// v1.10.4: long-press timing for touch-driven selection. 500ms is the common
-// "long-press" threshold; 10px is the dead-zone before we treat the gesture
-// as a scroll/swipe instead.
+const MAX_RECONNECT_ATTEMPTS = 5;
+const RECONNECT_DELAYS_MS = [500, 1000, 2000, 4000, 8000];
+
 const LONG_PRESS_MS = 500;
 const LONG_PRESS_TOLERANCE_PX = 10;
+
 // xterm 5 ships no public dimensions API — `_core._renderService.dimensions`
-// is internal. We try it first and fall back to (container px / term.cols).
-// The fallback overcounts because xterm reserves the right edge for the
-// scrollbar (hidden, but the cells still respect the reserved px).
+// is internal but stable across the package versions we ship.
 function cellSize(term: Terminal, container: HTMLElement): { w: number; h: number } {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const dims = (term as any)._core?._renderService?.dimensions?.css?.cell;
@@ -95,9 +89,6 @@ function cellSize(term: Terminal, container: HTMLElement): { w: number; h: numbe
   return { w: rect.width / Math.max(term.cols, 1), h: rect.height / Math.max(term.rows, 1) };
 }
 
-// Pointer → buffer cell. Returns { col, bufferRow } where bufferRow is the
-// absolute row in the scrollback buffer (i.e. viewportY-offset applied), so
-// the result is stable across scroll. Clamped to valid ranges.
 function pointToCell(
   term: Terminal,
   container: HTMLElement,
@@ -114,9 +105,6 @@ function pointToCell(
   return { col, bufferRow };
 }
 
-// Word boundary on a buffer line. Letters/digits/_/-/./~/$ count as word
-// chars (path-friendly); everything else is a separator. matchAll keeps the
-// scan purely iterator-based — no manual cursor needed.
 const WORD_RE = /[\w.~$\-/]+/g;
 function wordRangeAt(line: string, col: number): { start: number; end: number } | null {
   for (const m of line.matchAll(WORD_RE)) {
@@ -130,20 +118,22 @@ function wordRangeAt(line: string, col: number): { start: number; end: number }
 
 export function TerminalPane({ sessionId, paneId, label, active = false }: Props) {
   const containerRef = useRef<HTMLDivElement | null>(null);
-  const wsRef = useRef<WebSocket | null>(null);
   const termRef = useRef<Terminal | null>(null);
-  const fitRef = useRef<FitAddon | null>(null);
   const searchRef = useRef<SearchAddon | null>(null);
-  const reconnectRef = useRef<() => void>(() => {});
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const reconnectAttemptRef = useRef(0);
+  const closedByUserRef = useRef(false);
+  // Last size pushed through term.onResize. Mirrors xterm's authoritative
+  // cols/rows; consulted on every WS open so the resize frame carries the
+  // currently-measured size, not a stale lastSize from before the latest fit.
+  const lastSizeRef = useRef<{ cols: number; rows: number }>({ cols: 80, rows: 24 });
+  const reconnectFnRef = useRef<() => void>(() => {});
+
   const [connState, setConnState] = useState<ConnState>('connecting');
-  // v1.10.4: floating menu state. Positioned in client coords.
   const [menu, setMenu] = useState<{ x: number; y: number } | null>(null);
   const [searchOpen, setSearchOpen] = useState(false);
-  // Forces the floating menu's chat list to re-read chatInputsRegistry when
-  // it's actually opened — keeps the registry-subscription tick local.
   const [chatInputs, setChatInputs] = useState<ChatInputRegistration[]>([]);
-  // Refs over state so the long-living useEffect can call the latest setters
-  // without re-running the effect (which would tear down xterm + WS).
   const setMenuRef = useRef(setMenu);
   setMenuRef.current = setMenu;
   const setSearchOpenRef = useRef(setSearchOpen);
@@ -151,94 +141,387 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
   const setChatInputsRef = useRef(setChatInputs);
   setChatInputsRef.current = setChatInputs;
 
+  // v1.10.8d: sticky Ctrl for the on-screen hotkey bar (boolab pattern).
+  // ctrlArmedRef is read synchronously inside term.onData (per keystroke);
+  // ctrlArmed state mirror exists so the Ctrl button can highlight in React.
+  // Auto-disarms after 5s so a stray tap doesn't quietly mangle the next
+  // keystroke minutes later.
+  const [ctrlArmed, setCtrlArmed] = useState(false);
+  const ctrlArmedRef = useRef(false);
+  const ctrlTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const setCtrlArmedSync = useCallback((armed: boolean) => {
+    ctrlArmedRef.current = armed;
+    setCtrlArmed(armed);
+    if (ctrlTimerRef.current) {
+      clearTimeout(ctrlTimerRef.current);
+      ctrlTimerRef.current = null;
+    }
+    if (armed) {
+      ctrlTimerRef.current = setTimeout(() => {
+        ctrlArmedRef.current = false;
+        setCtrlArmed(false);
+        ctrlTimerRef.current = null;
+      }, 5000);
+    }
+  }, []);
+  const armCtrl = useCallback(() => {
+    setCtrlArmedSync(!ctrlArmedRef.current);
+  }, [setCtrlArmedSync]);
+  // sendInput: write to the WS as a binary frame (server-side discriminator
+  // routes binary to PTY, text to JSON control). Used by the hotkey bar.
+  const sendInput = useCallback((text: string) => {
+    if (!text) return;
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    try {
+      ws.send(new TextEncoder().encode(text));
+    } catch {
+      /* ignore */
+    }
+  }, []);
+  // fitFull lives inside the main useEffect (closure over `disposed`/`ctr`);
+  // expose via a ref so the hotkey bar's fit button and the visualViewport
+  // resize handler can reach it.
+  const fitFullRef = useRef<() => void>(() => {});
+  const triggerFit = useCallback(() => {
+    fitFullRef.current();
+  }, []);
+
   useEffect(() => {
     const container = containerRef.current;
     if (!container) return;
-    // TS doesn't preserve the null-narrowing across nested function bodies
-    // below (onTouchStart, etc.) because container is a closure capture. Bind
-    // a narrowed-type local that the inner closures can reference directly.
     const ctr: HTMLDivElement = container;
 
     let disposed = false;
-    let resizeDebounceTimer: ReturnType<typeof setTimeout> | null = null;
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-    let attempts = 0;
+    closedByUserRef.current = false;
+    reconnectAttemptRef.current = 0;
 
+    // On mobile viewports drop to 11px so opencode/claude get enough cols.
+    const fontSize = typeof window !== 'undefined' && window.innerWidth < 768 ? 11 : 13;
     const term = new Terminal({
-      fontFamily: '"JetBrains Mono Variable", "JetBrains Mono", ui-monospace, monospace',
-      fontSize: 13,
-      lineHeight: 1.2,
+      convertEol: true,
       cursorBlink: true,
+      allowProposedApi: true,
+      fontFamily:
+        "'JetBrains Mono Variable', 'JetBrains Mono', 'Fira Code', Menlo, monospace",
+      fontSize,
+      // Locked cell metrics so DOM-renderer rows line up: integer-multiple
+      // line height and zero letter spacing keep glyph spans cell-aligned.
+      // globals.css enforces the same with !important so an inherited rule
+      // can't fight us.
+      lineHeight: 1.0,
+      letterSpacing: 0,
       scrollback: 10_000,
       fastScrollModifier: 'shift',
       altClickMovesCursor: false,
       theme: XTERM_THEME,
-      allowProposedApi: true,
     });
     termRef.current = term;
     const fit = new FitAddon();
-    fitRef.current = fit;
     const search = new SearchAddon();
     searchRef.current = search;
     term.loadAddon(fit);
     term.loadAddon(search);
     term.loadAddon(new WebLinksAddon());
-    term.open(container);
-    // v1.10.4 gap fix: bypass FitAddon's proposeDimensions(), which subtracts
-    // a phantom scrollbar width even when CSS hides the scrollbar. Compute
-    // cols/rows directly from the host's clientWidth/clientHeight divided by
-    // the renderer's reported cell size. Falls back to FitAddon if cell
-    // metrics aren't ready yet (e.g. on very first mount).
+    term.open(ctr);
+
+    // Bypass FitAddon's proposeDimensions(), which subtracts the native
+    // scrollbar's reserved width even after CSS hides it (boolab fix). We
+    // compute cols/rows directly from host.clientWidth/Height ÷ cell metrics.
+    // Falls through (no-op) if cell metrics aren't measured yet — a later
+    // refit (fonts.ready / setTimeout / ResizeObserver) will catch it.
+    //
+    // v1.10.8d: row count uses the VISIBLE height (clipped against the
+    // visualViewport) rather than raw clientHeight. h-dvh on the root only
+    // shrinks for the URL bar — not the iOS keyboard — so without the clip
+    // we allocate rows for the area hidden behind the keyboard, and bash's
+    // cursor (pushed down by MOTD on SSH login) ends up below the fold.
     const fitFull = (): void => {
-      const host = containerRef.current;
+      if (disposed) return;
       const t = termRef.current;
-      if (!host || !t) return;
+      if (!t) return;
       if (!t.element || !(t.element as HTMLElement).offsetParent) return;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const core: any = (t as any)._core;
       const cellW: number | undefined = core?._renderService?.dimensions?.css?.cell?.width;
       const cellH: number | undefined = core?._renderService?.dimensions?.css?.cell?.height;
-      if (!cellW || !cellH || cellW <= 0 || cellH <= 0) {
-        try { fit.fit(); } catch { /* not ready */ }
-        return;
+      if (!cellW || !cellH || cellW <= 0 || cellH <= 0) return;
+      let visibleHeight = ctr.clientHeight;
+      const vp2 = typeof window !== 'undefined' ? window.visualViewport : null;
+      if (vp2) {
+        const rect = ctr.getBoundingClientRect();
+        // visualViewport.height is the layout viewport minus the keyboard.
+        // rect.bottom is in layout-viewport coordinates. clip to whichever
+        // is smaller. offsetTop/pageTop adjustments aren't needed at zoom=1.
+        const visibleBottom = Math.min(rect.bottom, vp2.height);
+        const clipped = Math.max(0, visibleBottom - rect.top);
+        if (clipped > 0) visibleHeight = clipped;
       }
-      const cols = Math.max(2, Math.floor(host.clientWidth / cellW));
-      const rows = Math.max(1, Math.floor(host.clientHeight / cellH));
+      const cols = Math.max(2, Math.floor(ctr.clientWidth / cellW));
+      const rows = Math.max(1, Math.floor(visibleHeight / cellH));
       if (cols !== t.cols || rows !== t.rows) {
-        try { t.resize(cols, rows); } catch { /* ignore */ }
+        try {
+          t.resize(cols, rows);
+        } catch {
+          /* ignore */
+        }
       }
     };
+    fitFullRef.current = fitFull;
 
-    try {
-      fitFull();
-      // v1.10.4: also push initial size to PTY so opencode/bash get correct cols/rows
-      api.terminals.resize(sessionId, paneId, term.cols, term.rows).catch(() => {});
-    } catch {
-      /* container not yet sized */
+    // boolab pattern: term.onResize fires synchronously inside term.resize()
+    // and on init. We always update lastSizeRef so a fresh WS connect (or
+    // reconnect) carries the current measured size; we send a resize frame
+    // when the WS is open. No gating by an "is-started" flag — the WS itself
+    // is the gate (it ignores writes when not open).
+    term.onResize(({ cols, rows }) => {
+      lastSizeRef.current = { cols, rows };
+      if (cols < 2 || rows < 1) return;
+      const ws = wsRef.current;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      try {
+        ws.send(JSON.stringify({ type: 'resize', cols, rows }));
+      } catch {
+        /* ignore */
+      }
+    });
+
+    // Keystrokes go out as a BINARY frame so the server can disambiguate them
+    // from JSON control frames. TextEncoder is in every modern browser.
+    //
+    // Sticky Ctrl: when armed (via the hotkey bar), apply Ctrl to the next
+    // single ASCII printable (0x40-0x7e — '@', A-Z, [, \, ], ^, _, `, a-z,
+    // {, |, }, ~) and disarm. Multi-byte sequences (arrows, Esc, F-keys) pass
+    // through untouched and disarm so a stuck arm doesn't poison them.
+    term.onData((data) => {
+      const ws = wsRef.current;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      let out = data;
+      if (ctrlArmedRef.current) {
+        if (data.length === 1) {
+          const c = data.charCodeAt(0);
+          if (c >= 0x40 && c <= 0x7e) {
+            out = String.fromCharCode(c & 0x1f);
+          }
+        }
+        setCtrlArmedSync(false);
+      }
+      try {
+        ws.send(new TextEncoder().encode(out));
+      } catch {
+        /* ignore */
+      }
+    });
+
+    function buildWsUrl(): string {
+      const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const { cols, rows } = lastSizeRef.current;
+      return `${proto}//${window.location.host}/ws/term/sessions/${sessionId}/panes/${paneId}?cols=${cols}&rows=${rows}`;
     }
 
-    // v1.10.3 Issue 5: web-font metrics aren't final at mount. Re-fit after
-    // the JetBrains Mono variable font lands so column count matches what
-    // the canvas actually paints. document.fonts.ready resolves once the
-    // initial font set is loaded; chaining .fit() on it is a one-shot.
+    function scheduleReconnect(): void {
+      if (disposed || closedByUserRef.current) return;
+      const attempt = reconnectAttemptRef.current;
+      if (attempt >= MAX_RECONNECT_ATTEMPTS) {
+        setConnState('disconnected');
+        return;
+      }
+      const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)]!;
+      reconnectAttemptRef.current = attempt + 1;
+      if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
+      reconnectTimerRef.current = setTimeout(connect, delay);
+    }
+
+    function connect(): void {
+      if (disposed || closedByUserRef.current) return;
+      const existing = wsRef.current;
+      if (existing && existing.readyState !== WebSocket.CLOSED) return;
+      let ws: WebSocket;
+      try {
+        ws = new WebSocket(buildWsUrl());
+      } catch {
+        scheduleReconnect();
+        return;
+      }
+      ws.binaryType = 'arraybuffer';
+      wsRef.current = ws;
+
+      ws.addEventListener('open', () => {
+        if (disposed) return;
+        reconnectAttemptRef.current = 0;
+        setConnState('open');
+        // boolab pattern: send our currently-measured size as a resize frame
+        // on every WS open. Server's PTY adopts it immediately; no race
+        // window between attach and resize.
+        const { cols, rows } = lastSizeRef.current;
+        if (cols >= 2 && rows >= 1) {
+          try {
+            ws.send(JSON.stringify({ type: 'resize', cols, rows }));
+          } catch {
+            /* ignore */
+          }
+        }
+      });
+
+      ws.addEventListener('message', (e) => {
+        const t = termRef.current;
+        if (!t) return;
+        if (typeof e.data === 'string') {
+          try {
+            const parsed = JSON.parse(e.data) as { type?: string; code?: number };
+            if (parsed.type === 'init') {
+              // boolab pattern: wipe any pre-attach buffer state, then the
+              // server's next frame (a single binary capture-pane replay)
+              // will paint the current tmux pane state in cleanly. Re-send
+              // our measured size in case the server's init size (from the
+              // WS query string) is stale relative to a fit that landed
+              // between opening and now.
+              try {
+                t.clear();
+              } catch {
+                /* ignore */
+              }
+              const { cols, rows } = lastSizeRef.current;
+              if (cols >= 2 && rows >= 1) {
+                try {
+                  ws.send(JSON.stringify({ type: 'resize', cols, rows }));
+                } catch {
+                  /* ignore */
+                }
+              }
+              return;
+            }
+            if (parsed.type === 'exit') {
+              t.write(`\r\n\x1b[2m[process exited with code ${parsed.code ?? 0}]\x1b[0m\r\n`);
+              return;
+            }
+          } catch {
+            /* not JSON — fall through and write as text */
+          }
+          t.write(e.data);
+        } else {
+          t.write(new Uint8Array(e.data as ArrayBuffer));
+        }
+      });
+
+      ws.addEventListener('close', () => {
+        if (disposed) return;
+        wsRef.current = null;
+        if (closedByUserRef.current) return;
+        setConnState('reconnecting');
+        scheduleReconnect();
+      });
+
+      ws.addEventListener('error', () => {
+        // close fires after; let close own the retry.
+      });
+    }
+
+    function manualReconnect(): void {
+      if (disposed) return;
+      closedByUserRef.current = false;
+      reconnectAttemptRef.current = 0;
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current);
+        reconnectTimerRef.current = null;
+      }
+      try {
+        wsRef.current?.close();
+      } catch {
+        /* ignore */
+      }
+      setConnState('reconnecting');
+      setTimeout(connect, 50);
+    }
+    reconnectFnRef.current = manualReconnect;
+
+    // Init: rAF-defer one frame so xterm's render service can populate
+    // _renderService.dimensions, then fitFull → /start (idempotent, sizes
+    // the tmux session) → connect WS. The WS handler also ensureSession's
+    // as belt-and-suspenders, so a /start failure is non-fatal.
+    const initRaf = requestAnimationFrame(() => {
+      if (disposed) return;
+      fitFull();
+      const { cols, rows } = lastSizeRef.current;
+      api.terminals
+        .start(sessionId, paneId, cols, rows)
+        .catch(() => {
+          /* WS handler will ensureSession itself — non-fatal */
+        })
+        .finally(() => {
+          if (disposed) return;
+          connect();
+        });
+    });
+
+    // Boolab pattern: term measures cell metrics on open() against whatever
+    // font is registered at that instant; if the font hasn't loaded yet we
+    // get a fallback measurement and the wrong cols. Refit when
+    // document.fonts.ready resolves.
+    let fontRaf: number | null = null;
     if (typeof document !== 'undefined' && document.fonts && document.fonts.ready) {
       document.fonts.ready
         .then(() => {
           if (disposed) return;
-          try {
-            fitFull();
-            api.terminals.resize(sessionId, paneId, term.cols, term.rows).catch(() => {});
-          } catch {
-            /* ignore */
-          }
+          fontRaf = requestAnimationFrame(() => fitFull());
         })
         .catch(() => {
           /* ignore */
         });
     }
 
-    // Shared paste path used by Cmd-V handler, the floating menu's "Paste"
-    // item, and the pane-header Paste button (via terminalsRegistry).
+    // Second-pass refit: mobile browsers can settle layout slightly late,
+    // causing the rAF fit to measure a stale clientWidth.
+    const delayedFit = setTimeout(() => fitFull(), 150);
+
+    // ResizeObserver: refit on any container size change. No debounce —
+    // term.onResize itself is the throttle (no-op when cols/rows unchanged).
+    const ro = new ResizeObserver(() => {
+      fitFull();
+    });
+    ro.observe(ctr);
+
+    const onVis = (): void => {
+      if (document.visibilityState !== 'visible') return;
+      const ws = wsRef.current;
+      if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
+        manualReconnect();
+      } else {
+        // Refit in case the layout changed while hidden. Single rAF so the
+        // measurement runs after the tab's first composited frame back in
+        // the foreground.
+        requestAnimationFrame(() => {
+          if (disposed) return;
+          fitFull();
+        });
+      }
+    };
+    document.addEventListener('visibilitychange', onVis);
+
+    // v1.10.8d: visualViewport.resize fires when the iOS keyboard opens or
+    // closes — the layout viewport stays full-height (so our h-dvh root
+    // doesn't shrink), but the visual viewport contracts above the keyboard.
+    // Refit so xterm's row count matches the visible area, then scroll to
+    // bottom so the cursor stays above the keyboard fold (boolab pattern).
+    let onVpResize: (() => void) | null = null;
+    const vp = typeof window !== 'undefined' ? window.visualViewport : null;
+    if (vp) {
+      onVpResize = (): void => {
+        if (disposed) return;
+        fitFull();
+        const t = termRef.current;
+        if (t) {
+          try { t.scrollToBottom(); } catch { /* ignore */ }
+        }
+      };
+      vp.addEventListener('resize', onVpResize);
+    }
+
+    // ============================================================
+    // v1.10.4 features (long-press menu, right-click, search, registry)
+    // Kept verbatim — independent of the WS/fit path that v1.10.8c fixes.
+    // ============================================================
+
     function pasteFromClipboard(): void {
       if (!navigator.clipboard || typeof navigator.clipboard.readText !== 'function') {
         toast.error('Paste blocked — long-press input area instead');
@@ -249,19 +532,19 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
         .then((text) => {
           if (!text) return;
           const ws = wsRef.current;
-          if (ws && ws.readyState === WebSocket.OPEN) ws.send(text);
+          if (ws && ws.readyState === WebSocket.OPEN) {
+            try {
+              ws.send(new TextEncoder().encode(text));
+            } catch {
+              /* ignore */
+            }
+          }
         })
         .catch(() => {
           toast.error('Paste blocked — long-press input area instead');
         });
     }
 
-    // v1.10.3 copy/paste: xterm v5 ships no clipboard addon — bind manually.
-    //   Cmd/Ctrl-C + selection      → copy, swallow keystroke (no ^C)
-    //   Cmd/Ctrl-C, no selection    → fall through (xterm sends SIGINT)
-    //   Cmd/Ctrl-Shift-C            → ALWAYS swallow; copy if selection, no-op otherwise
-    //   Cmd/Ctrl-V / Cmd/Ctrl-Shift-V → paste from clipboard, swallow
-    //   v1.10.4: Cmd/Ctrl-F         → open search bar over terminal, swallow
     term.attachCustomKeyEventHandler((e) => {
       if (e.type !== 'keydown') return true;
       const mod = e.ctrlKey || e.metaKey;
@@ -279,8 +562,6 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
           }
           return false;
         }
-        // No selection: Shift means "force-swallow" (no ^C); without Shift
-        // we let xterm send SIGINT.
         return !e.shiftKey;
       }
       if (isV) {
@@ -288,139 +569,13 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
         return false;
       }
       if (isF) {
-        // Cmd/Ctrl-F when xterm has focus → open search. The Session-level
-        // shortcut handles the case where it doesn't, but xterm intercepts
-        // keys when focused so we need this binding too.
         setSearchOpenRef.current(true);
         return false;
       }
       return true;
     });
 
-    function buildUrl(): string {
-      const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-      const cols = term.cols;
-      const rows = term.rows;
-      return (
-        `${proto}//${window.location.host}/ws/term/sessions/${sessionId}/panes/${paneId}` +
-        `?cols=${cols}&rows=${rows}`
-      );
-    }
-
-    function connect(): void {
-      if (disposed) return;
-      try {
-        const ws = new WebSocket(buildUrl());
-        ws.binaryType = 'arraybuffer';
-        wsRef.current = ws;
-
-        ws.onopen = () => {
-          if (disposed) return;
-          attempts = 0;
-          setConnState('open');
-        };
-
-        ws.onmessage = (e) => {
-          if (typeof e.data === 'string') {
-            try {
-              const parsed = JSON.parse(e.data) as { type?: string; code?: number };
-              if (parsed.type === 'exit') {
-                term.write(
-                  `\r\n\x1b[2m[process exited with code ${parsed.code ?? 0}]\x1b[0m\r\n`,
-                );
-                return;
-              }
-            } catch {
-              /* not JSON — fall through and write as text */
-            }
-            term.write(e.data);
-          } else {
-            term.write(new Uint8Array(e.data));
-          }
-        };
-
-        ws.onclose = () => {
-          if (disposed) return;
-          if (attempts >= MAX_RECONNECT_ATTEMPTS) {
-            setConnState('disconnected');
-            return;
-          }
-          attempts += 1;
-          setConnState('reconnecting');
-          const delay = 500 * Math.pow(2, attempts - 1);
-          reconnectTimer = setTimeout(connect, delay);
-        };
-
-        ws.onerror = () => {
-          // onclose follows — let it own the retry decision.
-        };
-      } catch {
-        if (attempts >= MAX_RECONNECT_ATTEMPTS) {
-          setConnState('disconnected');
-          return;
-        }
-        attempts += 1;
-        setConnState('reconnecting');
-        reconnectTimer = setTimeout(connect, 500 * Math.pow(2, attempts - 1));
-      }
-    }
-
-    function manualReconnect(): void {
-      if (disposed) return;
-      if (reconnectTimer !== null) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
-      attempts = 0;
-      setConnState('reconnecting');
-      try {
-        wsRef.current?.close();
-      } catch {
-        /* ignore */
-      }
-      reconnectTimer = setTimeout(connect, 50);
-    }
-    reconnectRef.current = manualReconnect;
-
-    term.onData((data) => {
-      const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.send(data);
-      }
-    });
-
-    const fireResize = (): void => {
-      try {
-        fitFull();
-      } catch {
-        return;
-      }
-      api.terminals.resize(sessionId, paneId, term.cols, term.rows).catch(() => {
-        /* transient — next resize will catch up */
-      });
-    };
-    const ro = new ResizeObserver(() => {
-      if (resizeDebounceTimer !== null) clearTimeout(resizeDebounceTimer);
-      // v1.10.3 Issue 5: defer the actual fit to the next frame so the
-      // browser has applied the new layout before we measure cell sizes.
-      resizeDebounceTimer = setTimeout(() => {
-        requestAnimationFrame(fireResize);
-      }, 100);
-    });
-    ro.observe(container);
-
-    const onVis = (): void => {
-      if (document.visibilityState !== 'visible') return;
-      const ws = wsRef.current;
-      if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
-        manualReconnect();
-      }
-    };
-    document.addEventListener('visibilitychange', onVis);
-
-    // v1.10.4: long-press selection + floating menu. Touch handlers live on
-    // the xterm host container; we don't preventDefault on touchmove unless
-    // we've entered selection mode, so vertical scroll-by-finger still works.
+    // Long-press selection + floating menu (touch).
     let lpTimer: ReturnType<typeof setTimeout> | null = null;
     let lpStart: { x: number; y: number } | null = null;
     let lpAnchor: { col: number; bufferRow: number } | null = null;
@@ -445,8 +600,6 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
       anchor: { col: number; bufferRow: number },
       to: { col: number; bufferRow: number },
     ): void {
-      // Compute the lexicographic min/max of (row, col) so the user can drag
-      // up-left or down-right and still extend in the natural reading order.
       const a = anchor;
       const b = to;
       let s: { col: number; row: number };
@@ -474,8 +627,6 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
         const ok = selectWord(lpAnchor.col, lpAnchor.bufferRow);
         if (!ok) return;
         inSelection = true;
-        // Anchor the menu above the touch point. Slight upward offset so the
-        // user's finger doesn't cover it.
         setMenuRef.current({ x: t.clientX, y: Math.max(t.clientY - 50, 8) });
       }, LONG_PRESS_MS);
     }
@@ -497,27 +648,23 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
     }
     function onTouchEnd(): void {
       if (!inSelection) clearLp();
-      // Leave the menu visible after release; user dismisses via tap-outside.
       inSelection = false;
     }
     function onTouchCancel(): void {
       clearLp();
       inSelection = false;
     }
-    container.addEventListener('touchstart', onTouchStart, { passive: true });
-    container.addEventListener('touchmove', onTouchMove, { passive: false });
-    container.addEventListener('touchend', onTouchEnd, { passive: true });
-    container.addEventListener('touchcancel', onTouchCancel, { passive: true });
+    ctr.addEventListener('touchstart', onTouchStart, { passive: true });
+    ctr.addEventListener('touchmove', onTouchMove, { passive: false });
+    ctr.addEventListener('touchend', onTouchEnd, { passive: true });
+    ctr.addEventListener('touchcancel', onTouchCancel, { passive: true });
 
-    // Desktop right-click: open the same floating menu.
     function onContextMenu(e: MouseEvent): void {
       e.preventDefault();
       setMenuRef.current({ x: e.clientX, y: e.clientY });
     }
-    container.addEventListener('contextmenu', onContextMenu);
+    ctr.addEventListener('contextmenu', onContextMenu);
 
-    // Tap-outside dismiss for the floating menu. Pointerdown fires before
-    // any click handler inside the menu, so we re-check the target.
     function onDocPointerDown(e: PointerEvent): void {
       const t = e.target as Element | null;
       if (t && t.closest('[data-term-menu]')) return;
@@ -543,65 +690,91 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
       const ws = wsRef.current;
       if (!ws || ws.readyState !== WebSocket.OPEN) return;
       const payload = text.endsWith('\n') ? text : `${text}\n`;
-      ws.send(payload);
+      try {
+        ws.send(new TextEncoder().encode(payload));
+      } catch {
+        /* ignore */
+      }
     });
     setChatInputsRef.current(chatInputsRegistry.list());
     const unsubChats = chatInputsRegistry.subscribe(() => {
       setChatInputsRef.current(chatInputsRegistry.list());
     });
 
-    api.terminals.start(sessionId, paneId).catch(() => {});
-    connect();
-
     return () => {
       disposed = true;
+      closedByUserRef.current = true;
+      cancelAnimationFrame(initRaf);
+      if (fontRaf !== null) cancelAnimationFrame(fontRaf);
+      clearTimeout(delayedFit);
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current);
+        reconnectTimerRef.current = null;
+      }
+      if (ctrlTimerRef.current) {
+        clearTimeout(ctrlTimerRef.current);
+        ctrlTimerRef.current = null;
+      }
+      if (lpTimer !== null) clearTimeout(lpTimer);
+      ro.disconnect();
       document.removeEventListener('visibilitychange', onVis);
+      if (vp && onVpResize) vp.removeEventListener('resize', onVpResize);
       document.removeEventListener('pointerdown', onDocPointerDown);
-      container.removeEventListener('touchstart', onTouchStart);
-      container.removeEventListener('touchmove', onTouchMove);
-      container.removeEventListener('touchend', onTouchEnd);
-      container.removeEventListener('touchcancel', onTouchCancel);
-      container.removeEventListener('contextmenu', onContextMenu);
+      ctr.removeEventListener('touchstart', onTouchStart);
+      ctr.removeEventListener('touchmove', onTouchMove);
+      ctr.removeEventListener('touchend', onTouchEnd);
+      ctr.removeEventListener('touchcancel', onTouchCancel);
+      ctr.removeEventListener('contextmenu', onContextMenu);
       unsubscribe();
       unsubChats();
       unregister();
-      if (resizeDebounceTimer !== null) clearTimeout(resizeDebounceTimer);
-      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
-      if (lpTimer !== null) clearTimeout(lpTimer);
-      ro.disconnect();
+      const ws = wsRef.current;
+      if (ws) {
+        try {
+          ws.close(1000, 'unmount');
+        } catch {
+          /* ignore */
+        }
+        wsRef.current = null;
+      }
       try {
-        wsRef.current?.close();
+        term.dispose();
       } catch {
         /* ignore */
       }
-      wsRef.current = null;
-      term.dispose();
       termRef.current = null;
-      fitRef.current = null;
       searchRef.current = null;
-      reconnectRef.current = () => {};
+      reconnectFnRef.current = () => {};
     };
   }, [sessionId, paneId, label]);
 
-  // v1.10.3 Issue 5 refit trigger: when this pane becomes active (e.g. after
-  // a mobile pane switch or an unmaximize), the container's measured size
-  // may differ from when xterm last fit. rAF defers the measurement to after
-  // the layout pass that the visibility change triggered.
+  // Refit when this pane becomes the visible/focused one (e.g. mobile pane
+  // switch, maximize toggle). term.onResize will send the resize WS frame if
+  // cols or rows actually changed.
   useEffect(() => {
     if (!active) return;
-    const fit = fitRef.current;
-    if (!fit) return;
     const raf = requestAnimationFrame(() => {
-      try {
-        fit.fit();
-      } catch {
-        /* ignore */
+      const t = termRef.current;
+      const host = containerRef.current;
+      if (!t || !host) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const core: any = (t as any)._core;
+      const cellW: number | undefined = core?._renderService?.dimensions?.css?.cell?.width;
+      const cellH: number | undefined = core?._renderService?.dimensions?.css?.cell?.height;
+      if (!cellW || !cellH || cellW <= 0 || cellH <= 0) return;
+      const cols = Math.max(2, Math.floor(host.clientWidth / cellW));
+      const rows = Math.max(1, Math.floor(host.clientHeight / cellH));
+      if (cols !== t.cols || rows !== t.rows) {
+        try {
+          t.resize(cols, rows);
+        } catch {
+          /* ignore */
+        }
       }
     });
     return () => cancelAnimationFrame(raf);
   }, [active]);
 
-  // Floating menu actions. Each operates on termRef.current and clears menu.
   function actCopy(): void {
     const term = termRef.current;
     if (!term) return;
@@ -642,16 +815,19 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
   const hasSelection = !!termRef.current?.getSelection();
 
   return (
-    <div
-      // v1.10.3 Issue 5: flex-1 + min-w-0 + self-stretch + w-full lets the
-      // pane absorb all available horizontal space without leaving a gap on
-      // either side of the xterm canvas.
-      className="relative flex-1 min-w-0 self-stretch w-full h-full bg-[#0b0f14]"
-    >
-      <style>{XTERM_STYLE_OVERRIDES}</style>
+    <div className="relative flex flex-col flex-1 min-w-0 self-stretch w-full h-full bg-[#0b0f14]">
+      {/* xterm CSS overrides live in src/styles/globals.css (boolab pattern).
+          Putting them in an inline <style> here races the upstream xterm.css
+          on first paint — the right-edge #000 stripe survives the override. */}
+      <TerminalHotkeyBar
+        ctrlArmed={ctrlArmed}
+        onSendBytes={sendInput}
+        onArmCtrl={armCtrl}
+        onFit={triggerFit}
+      />
       <div
         ref={containerRef}
-        className="w-full h-full overflow-hidden"
+        className="flex-1 min-h-0 w-full overflow-hidden"
         style={{ touchAction: 'pan-y', background: TERM_BG }}
         data-testid="terminal-pane"
       />
@@ -687,7 +863,7 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
           <span>Disconnected from terminal server.</span>
           <button
             type="button"
-            onClick={() => reconnectRef.current()}
+            onClick={() => reconnectFnRef.current()}
             className="ml-auto inline-flex items-center gap-1 rounded bg-background/20 hover:bg-background/30 px-2 py-0.5"
           >
             <RefreshCw size={12} /> Reconnect
@@ -698,10 +874,121 @@ export function TerminalPane({ sessionId, paneId, label, active = false }: Props
   );
 }
 
-// v1.10.4: shared floating menu used by both desktop right-click and mobile
-// long-press. shadcn-style chrome: dark bg, subtle border, 14px text, 44px
-// touch targets via padding. Tap-outside dismiss is wired in the parent's
-// document pointerdown listener.
+// ============================================================
+// TerminalHotkeyBar — v1.10.8d port of boolab's TerminalHotkeyBar.jsx +
+// terminalHotkeysStore.js DEFAULT_BAR. The catalog is hardcoded inline (no
+// zustand store, no settings UI) — single-user homelab doesn't need either.
+// Add new entries by extending BAR below.
+// ============================================================
+type Hotkey =
+  | { id: string; label: string; bytes: string; sticky?: undefined }
+  | { id: string; label: string; sticky: 'ctrl'; bytes?: undefined };
+
+const HOTKEY_BAR: Hotkey[] = [
+  { id: 'esc', label: 'Esc', bytes: '\x1b' },
+  { id: 'shift-tab', label: '⇧Tab', bytes: '\x1b[Z' },
+  { id: 'tab', label: 'Tab', bytes: '\t' },
+  { id: 'ctrl', label: 'Ctrl', sticky: 'ctrl' },
+  { id: 'ctrl-c', label: 'Ctrl+C', bytes: '\x03' },
+  { id: 'arrow-up', label: '↑', bytes: '\x1b[A' },
+  { id: 'arrow-down', label: '↓', bytes: '\x1b[B' },
+  { id: 'arrow-left', label: '←', bytes: '\x1b[D' },
+  { id: 'arrow-right', label: '→', bytes: '\x1b[C' },
+];
+
+interface TerminalHotkeyBarProps {
+  ctrlArmed: boolean;
+  onSendBytes: (bytes: string) => void;
+  onArmCtrl: () => void;
+  onFit: () => void;
+}
+
+function TerminalHotkeyBar({
+  ctrlArmed,
+  onSendBytes,
+  onArmCtrl,
+  onFit,
+}: TerminalHotkeyBarProps) {
+  // Stop the touch from reaching the terminal pane below (which calls
+  // preventDefault on touchmove to suppress page-scroll). Without this a
+  // tap-and-drag on a hotkey button would also scroll the terminal buffer.
+  const stopTouch = useCallback((e: React.TouchEvent) => e.stopPropagation(), []);
+  const press = useCallback(
+    (entry: Hotkey) => {
+      if (entry.sticky === 'ctrl') {
+        onArmCtrl();
+      } else if (entry.bytes !== undefined) {
+        onSendBytes(entry.bytes);
+      }
+    },
+    [onArmCtrl, onSendBytes],
+  );
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Terminal hotkeys"
+      className="flex shrink-0 items-center gap-1 overflow-x-auto border-b border-border bg-muted/30 px-2 py-1"
+      style={{
+        scrollbarWidth: 'thin',
+        WebkitOverflowScrolling: 'touch',
+        // Suppress iOS native swipe-back gesture starting on the bar; pinch
+        // and other multi-touch gestures still pass through.
+        touchAction: 'pan-x',
+      }}
+      onTouchStart={stopTouch}
+      onTouchMove={stopTouch}
+    >
+      {HOTKEY_BAR.map((entry) => {
+        const isCtrl = entry.sticky === 'ctrl';
+        const armed = isCtrl && ctrlArmed;
+        return (
+          <button
+            key={entry.id}
+            type="button"
+            onClick={() => press(entry)}
+            aria-pressed={isCtrl ? armed : undefined}
+            aria-label={entry.label}
+            className={cn(
+              'shrink-0 rounded border px-2 py-0.5 text-xs font-mono transition-colors',
+              armed
+                ? 'border-primary bg-primary text-primary-foreground'
+                : 'border-border text-foreground hover:bg-muted',
+            )}
+            style={{
+              minHeight: 28,
+              minWidth: 36,
+              WebkitTouchCallout: 'none',
+              userSelect: 'none',
+            }}
+          >
+            {entry.label}
+          </button>
+        );
+      })}
+      <button
+        type="button"
+        onClick={onFit}
+        aria-label="Fit terminal"
+        title="Fit terminal to container"
+        className="shrink-0 inline-flex items-center justify-center rounded border border-border text-foreground hover:bg-muted"
+        style={{
+          minHeight: 28,
+          minWidth: 36,
+          paddingInline: 8,
+          WebkitTouchCallout: 'none',
+          userSelect: 'none',
+        }}
+      >
+        <Maximize2 size={14} />
+      </button>
+    </div>
+  );
+}
+
+// ============================================================
+// FloatingMenu — kept from v1.10.4 (mobile long-press + desktop right-click)
+// ============================================================
 interface FloatingMenuProps {
   x: number;
   y: number;
@@ -727,8 +1014,6 @@ function FloatingMenu({
   onDismiss,
 }: FloatingMenuProps) {
   const [submenu, setSubmenu] = useState(false);
-  // Clamp into viewport so the menu doesn't render off-screen on small
-  // viewports / near edges.
   const MENU_W = 200;
   const MENU_H = 220;
   const left = Math.min(x, window.innerWidth - MENU_W - 8);
@@ -742,8 +1027,6 @@ function FloatingMenu({
     return () => window.removeEventListener('keydown', onKey);
   }, [onDismiss]);
 
-  // Exactly one chat input registered → flat "Send to <N>" entry instead of
-  // a submenu (per v1.10.4 spec).
   const flatChat = chatInputs.length === 1 ? chatInputs[0] : null;
 
   return (
@@ -855,9 +1138,9 @@ function MenuItem({
   );
 }
 
-// v1.10.4: floating search bar pinned to the top of the terminal pane. Uses
-// SearchAddon.findNext / findPrevious. Incremental search on each keystroke
-// keeps the highlighted match in sync.
+// ============================================================
+// SearchBar — kept from v1.10.4
+// ============================================================
 interface SearchBarProps {
   searchRef: React.MutableRefObject<SearchAddon | null>;
   theme: typeof XTERM_THEME;
@@ -870,8 +1153,6 @@ function SearchBar({ searchRef, theme, onClose }: SearchBarProps) {
   useEffect(() => {
     inputRef.current?.focus();
   }, []);
-  // onDidChangeResults fires whenever the SearchAddon's decoration set
-  // updates. We mirror it into local state for the "N of M" indicator.
   useEffect(() => {
     const addon = searchRef.current;
     if (!addon) return;
diff --git a/apps/web/src/hooks/useWorkspacePanes.ts b/apps/web/src/hooks/useWorkspacePanes.ts
index d189df7..bf85c3e 100644
--- a/apps/web/src/hooks/useWorkspacePanes.ts
+++ b/apps/web/src/hooks/useWorkspacePanes.ts
@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { DragEvent } from 'react';
 import { toast } from 'sonner';
+import { api } from '@/api/client';
 import type { WorkspacePane } from '@/api/types';
 import { setActivePaneInfo, clearActivePane } from '@/hooks/useActivePane';
 
@@ -302,11 +303,19 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
         }
         return prev;
       }
+      // v1.10.8c: with per-pane tmux sessions, an unkilled session leaks until
+      // the next `tmux kill-server`. Fire-and-forget /kill on terminal removal.
+      // The endpoint is idempotent (404 on missing session) so a strict-mode
+      // double-invoke of the updater is safe.
+      const removed = prev[idx];
+      if (removed?.kind === 'terminal') {
+        api.terminals.kill(sessionId, removed.id).catch(() => { /* non-fatal */ });
+      }
       const next = prev.filter((_, i) => i !== idx);
       setActivePaneIdx((ai) => Math.min(ai, next.length - 1));
       return next;
     });
-  }, []);
+  }, [sessionId]);
 
   // Replaces a single empty default pane with a chat pane. Used by the initial
   // chat fetch to land on the most-recent open chat if no saved pane state.
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 1f860e3..9ac8403 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -1,3 +1,8 @@
+// Fonts imported as JS side-effect modules (boolab pattern, adapted for
+// Tailwind v4 + Vite asset-pipeline URL rewriting). Must precede the React
+// imports so the @font-face CSS lands before any component-tree render.
+import '@fontsource-variable/inter';
+import '@fontsource-variable/jetbrains-mono';
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
diff --git a/apps/web/src/styles/globals.css b/apps/web/src/styles/globals.css
index 06945c3..94b2ed3 100644
--- a/apps/web/src/styles/globals.css
+++ b/apps/web/src/styles/globals.css
@@ -1,8 +1,7 @@
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
-@import "@fontsource-variable/inter";
-@import "@fontsource-variable/jetbrains-mono";
+/* @fontsource-variable JBM + Inter imported from main.tsx as JS modules. */
 
 /* themes-v1: 18 preset palettes. Order matches docs/themes_v1.md §1 with
    obsidian first (default). Each file declares .theme-<id> for the light
@@ -152,3 +151,96 @@
     @apply font-sans;
   }
 }
+
+/*
+ * iOS Safari auto-enlarges text in narrow viewports (anti-zoom). On its own
+ * that's fine for HTML chrome, but xterm.js measures its cell width from a
+ * hidden text-measure element — so when iOS up-sizes that element, xterm
+ * computes wider cells and the terminal ends up at fewer cols than it should.
+ * In opencode this surfaces as the small fragmented banner instead of the
+ * big chunky one (opencode picks the banner glyph set based on terminal
+ * width). 100% disables the auto-adjust and keeps boocode at the same
+ * effective cols as boolab on the same iPhone.
+ */
+html, body {
+  -webkit-text-size-adjust: 100% !important;
+  -ms-text-size-adjust: 100% !important;
+  text-size-adjust: 100% !important;
+}
+
+/* iOS Safari auto-zooms when a user taps an input/textarea whose font-size
+ * is under 16px. Pin every input/textarea/select to 16px (boolab pattern)
+ * to suppress the zoom — applies globally; specific components can override
+ * with `text-base` or inline if a smaller visual is intentional. */
+input, textarea, select {
+  font-size: 16px !important;
+}
+
+/*
+ * xterm.js overrides (boolab pattern — see /opt/boolab/frontend/src/styles/globals.css).
+ *
+ * Why these live in a global stylesheet, not in an inline <style> inside the
+ * component: an inline <style> inserted at component-mount time races the
+ * upstream @xterm/xterm/css/xterm.css that ships with the addon. We saw the
+ * right-edge stripe persist on iOS even though the override was identical to
+ * boolab's — moving the rules here so they're parsed alongside index.css
+ * eliminates that race.
+ */
+
+.xterm,
+.xterm *,
+.xterm .xterm-rows,
+.xterm .xterm-rows * {
+  font-family: 'JetBrains Mono Variable', 'JetBrains Mono', 'Fira Code', Menlo, monospace !important;
+}
+
+/* Fill the host node — xterm's only non-absolute sizing comes from the canvas,
+ * and fractional rounding would otherwise leave a phantom right-edge stripe.
+ */
+.xterm {
+  width: 100% !important;
+  height: 100% !important;
+}
+
+/* Lock cell metrics so block-element glyphs (U+2580..U+259F) tile without
+ * subpixel gaps. Any non-zero letter-spacing or line-height ≠ 1 leaves
+ * fractional space between cells that paints as a horizontal/vertical
+ * stripe through the opencode banner on iOS. Disabling ligatures
+ * (font-feature-settings + font-variant-ligatures) prevents the renderer
+ * from collapsing adjacent block chars into shaped glyphs at unpredictable
+ * widths.
+ */
+.xterm,
+.xterm .xterm-rows {
+  letter-spacing: 0 !important;
+  line-height: 1 !important;
+  font-feature-settings: "liga" 0, "calt" 0 !important;
+  font-variant-ligatures: none !important;
+}
+
+.xterm .xterm-viewport {
+  overflow-y: hidden !important;
+  scrollbar-width: none !important;
+  -ms-overflow-style: none !important;
+  /*
+   * xterm.css ships `background-color: #000` on the viewport (kept for OS X
+   * scrollbar opacity in the upstream default). FitAddon rounds cols down
+   * to integer cells, so .xterm-screen is up to `cellWidth - 1` pixels
+   * narrower than .xterm-viewport — the strip between the canvas right
+   * edge and the viewport right edge then paints viewport's #000, which
+   * differs from the theme background (#0b0f14, set on the host wrapper in
+   * TerminalPane.tsx + via Terminal options.theme.background) and shows up
+   * as a visible right-edge gap.
+   *
+   * Setting viewport's background transparent lets the host wrapper's
+   * #0b0f14 show through, hiding the sub-cell remainder. Single source of
+   * truth for the bg color: the host.
+   */
+  background-color: transparent !important;
+}
+
+.xterm .xterm-viewport::-webkit-scrollbar {
+  width: 0 !important;
+  height: 0 !important;
+  display: none !important;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 66e7e3e..9b93b2a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -91,6 +91,21 @@ importers:
       '@fontsource-variable/jetbrains-mono':
         specifier: ^5.2.8
         version: 5.2.8
+      '@xterm/addon-fit':
+        specifier: 0.10.0
+        version: 0.10.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-search':
+        specifier: ^0.15.0
+        version: 0.15.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-web-links':
+        specifier: 0.11.0
+        version: 0.11.0(@xterm/xterm@5.5.0)
+      '@xterm/addon-webgl':
+        specifier: ^0.19.0
+        version: 0.19.0
+      '@xterm/xterm':
+        specifier: 5.5.0
+        version: 5.5.0
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -136,18 +151,6 @@ importers:
       tw-animate-css:
         specifier: ^1.4.0
         version: 1.4.0
-      xterm:
-        specifier: ^5.3.0
-        version: 5.3.0
-      xterm-addon-fit:
-        specifier: ^0.8.0
-        version: 0.8.0(xterm@5.3.0)
-      xterm-addon-search:
-        specifier: ^0.13.0
-        version: 0.13.0(xterm@5.3.0)
-      xterm-addon-web-links:
-        specifier: ^0.9.0
-        version: 0.9.0(xterm@5.3.0)
     devDependencies:
       '@tailwindcss/postcss':
         specifier: ^4.3.0
@@ -1843,6 +1846,27 @@ packages:
   '@vitest/utils@3.2.4':
     resolution: {integrity: sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==}
 
+  '@xterm/addon-fit@0.10.0':
+    resolution: {integrity: sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-search@0.15.0':
+    resolution: {integrity: sha512-ZBZKLQ+EuKE83CqCmSSz5y1tx+aNOCUaA7dm6emgOX+8J9H1FWXZyrKfzjwzV+V14TV3xToz1goIeRhXBS5qjg==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-web-links@0.11.0':
+    resolution: {integrity: sha512-nIHQ38pQI+a5kXnRaTgwqSHnX7KE6+4SVoceompgHL26unAxdfP6IPqUTSYPQgSwM56hsElfoNrrW5V7BUED/Q==}
+    peerDependencies:
+      '@xterm/xterm': ^5.0.0
+
+  '@xterm/addon-webgl@0.19.0':
+    resolution: {integrity: sha512-b3fMOsyLVuCeNJWxolACEUED0vm7qC0cy4wRvf3oURSzDTYVQiGPhTnhWZwIHdvC48Y+oLhvYXnY4XDXPoJo6A==}
+
+  '@xterm/xterm@5.5.0':
+    resolution: {integrity: sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==}
+
   abstract-logging@2.0.1:
     resolution: {integrity: sha512-2BjRTZxTPvheOvGbBslFSYOUkr+SjPtOnrLP33f+VIWLzezQpZcqVg7ja3L4dBXmzzgwT+a029jRx5PCi3JuiA==}
 
@@ -3906,28 +3930,6 @@ packages:
     resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
     engines: {node: '>=0.4'}
 
-  xterm-addon-fit@0.8.0:
-    resolution: {integrity: sha512-yj3Np7XlvxxhYF/EJ7p3KHaMt6OdwQ+HDu573Vx1lRXsVxOcnVJs51RgjZOouIZOczTsskaS+CpXspK81/DLqw==}
-    deprecated: This package is now deprecated. Move to @xterm/addon-fit instead.
-    peerDependencies:
-      xterm: ^5.0.0
-
-  xterm-addon-search@0.13.0:
-    resolution: {integrity: sha512-sDUwG4CnqxUjSEFh676DlS3gsh3XYCzAvBPSvJ5OPgF3MRL3iHLPfsb06doRicLC2xXNpeG2cWk8x1qpESWJMA==}
-    deprecated: This package is now deprecated. Move to @xterm/addon-search instead.
-    peerDependencies:
-      xterm: ^5.0.0
-
-  xterm-addon-web-links@0.9.0:
-    resolution: {integrity: sha512-LIzi4jBbPlrKMZF3ihoyqayWyTXAwGfu4yprz1aK2p71e9UKXN6RRzVONR0L+Zd+Ik5tPVI9bwp9e8fDTQh49Q==}
-    deprecated: This package is now deprecated. Move to @xterm/addon-web-links instead.
-    peerDependencies:
-      xterm: ^5.0.0
-
-  xterm@5.3.0:
-    resolution: {integrity: sha512-8QqjlekLUFTrU6x7xck1MsPzPA571K5zNqWm0M0oroYEWVOptZ0+ubQSkQ3uxIEhcIHRujJy6emDWX4A7qyFzg==}
-    deprecated: This package is now deprecated. Move to @xterm/xterm instead.
-
   y18n@5.0.8:
     resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
     engines: {node: '>=10'}
@@ -5601,6 +5603,22 @@ snapshots:
       loupe: 3.2.1
       tinyrainbow: 2.0.0
 
+  '@xterm/addon-fit@0.10.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-search@0.15.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-web-links@0.11.0(@xterm/xterm@5.5.0)':
+    dependencies:
+      '@xterm/xterm': 5.5.0
+
+  '@xterm/addon-webgl@0.19.0': {}
+
+  '@xterm/xterm@5.5.0': {}
+
   abstract-logging@2.0.1: {}
 
   accepts@2.0.0:
@@ -7972,20 +7990,6 @@ snapshots:
 
   xtend@4.0.2: {}
 
-  xterm-addon-fit@0.8.0(xterm@5.3.0):
-    dependencies:
-      xterm: 5.3.0
-
-  xterm-addon-search@0.13.0(xterm@5.3.0):
-    dependencies:
-      xterm: 5.3.0
-
-  xterm-addon-web-links@0.9.0(xterm@5.3.0):
-    dependencies:
-      xterm: 5.3.0
-
-  xterm@5.3.0: {}
-
   y18n@5.0.8: {}
 
   yallist@3.1.1: {}