chore: version packages

scripts/tmux-chooser.sh is deleted. codeman tui replaces it and does the
job better: sc numbered its entries globally but only accepted a single
[1-9] keypress, so sessions 10+ were listed and unselectable, and it
inferred nothing about what an agent was doing. The tui carries the
server's real states, answers permission dialogs, and leaves an attach
with one key.

install.sh no longer creates the tmux-chooser symlink or the sc alias.
It now sweeps both up instead, on update AND uninstall, so an update
cannot leave a symlink pointing at a script this version stopped
shipping. The alias removal is marker-owned: it matches the exact line
the installer wrote, so someone's own 'alias sc=' for another tool is
never touched, and it rewrites through 'cat >' so the profile keeps its
mode and ownership. Verified against three profile shapes.

BREAKING CHANGE: the 'sc' command and the 'tmux-chooser' symlink are
gone. Use 'codeman tui' (and 'codeman tui --list' / 'codeman tui <n>').

.gitignore

@@ -93,8 +93,6 @@ packages/gesture-control/.vite/
 # Claude Code plan tracking
 plan.json
 
-# Unfinished TUI (local development only)
-src/tui/
 .claude/
 media-assets/
 commands

CHANGELOG.md

@@ -1,5 +1,71 @@
 # aicodeman
 
+## 1.21.0
+
+### Minor Changes
+
+- **`codeman tui`: a terminal dashboard for your sessions.** For the times you are in SSH or Termius instead of a browser. The web UI remains the primary surface and bare `codeman` still prints help, so the dashboard itself is strictly additive.
+
+  Sessions are grouped NEEDS YOU / WORKING / IDLE / RECENT in the same status language as the web tabs and the phone overview, and the states come from the server (hooks, idle confirmation, the approvals inbox) over the existing HTTP/SSE API rather than being screen-scraped. That is what lets the dashboard answer a permission dialog instead of only reporting one.
+  - `↑↓`/`j`/`k` select; `1`-`9`, `[`/`]` and `Tab` switch between sessions
+  - `Enter` attaches and hands the terminal to tmux; **`F1` comes back**, one key, no modifier. Inside the pane a bar across the top carries the session strip and `Alt+1`..`Alt+9` switch without returning to the dashboard first
+  - `Enter` on a RECENT row resumes that conversation; on a session whose pane has died it refuses and offers `r` to resume it in a fresh pane
+  - `y`/`n`/digits answer the selected session's pending permission or question card (the server re-captures the pane first, so a keystroke can never land in the composer)
+  - `p` sends a one-line prompt without attaching, `x` kills (`y` confirms), `n` starts a session and opens straight into it
+  - `/` cross-session search, `g` away digest, `?` help, live preview pane, plan-usage chip in the header, a terminal bell when a new approval arrives
+  - `codeman tui --list` and `codeman tui <n>` are scriptable fast paths; with no server running it lists panes straight from the instance's tmux socket, attach-only, and upgrades live when the server comes back
+
+  Narrow terminals (under 72 columns, a phone SSH client) drop the preview and get a single-column layout. `NO_COLOR`, non-UTF-8 glyph fallback and a non-TTY refusal are all handled. Zero new dependencies: hand-rolled ANSI over chalk and commander. User guide: `docs/tui.md`.
+
+  **Breaking: the `sc` tmux chooser is retired.** `scripts/tmux-chooser.sh` is deleted and `install.sh` no longer creates the `tmux-chooser` symlink or the `sc` alias; it sweeps both up instead, on update and on uninstall. `codeman tui` replaces it and does the job better: `sc` numbered its entries globally but only accepted a single `[1-9]` keypress, so sessions 10+ were listed and could not be selected, and it inferred nothing about what an agent was doing. The alias cleanup is marker-owned, matching the exact line the installer wrote, so a user's own `alias sc=` for another tool is untouched.
+
+  **CLI polish that came with it.**
+  - New shared style kit (`src/cli-style.ts`) used across the CLI: semantic palette, glyphs, width-aware table, spinner, confirm.
+  - `codeman doctor` is colorized and its table is measured, so the "Antigravity CLI" label no longer pushes its row out of column. `--json` output is unchanged.
+  - `codeman web` no longer prints its "running at" line twice, and the server's non-loopback security warning is painted like the CLI's (chalk degrades off a TTY, so journald and `web.log` stay free of escape codes).
+  - Spinners on the silent up-to-30s waits in `codeman web -d`, `codeman web --stop` and `codeman service install`.
+  - `codeman reset` asks a real y/N confirmation on a TTY; non-interactive callers keep the old `--force` refusal.
+  - `codeman list` and `codeman session list` share one renderer instead of drifting copies.
+  - `codeman attach` is described correctly in the README (it shows an attachment card for a local file).
+  - `test/cli-commands.test.ts` now derives its inventory from the real commander program instead of a hand-written fixture that had drifted.
+
+  **Internal.** New `tmux -L` callers resolve the socket through `resolveTmuxSocketName()`, now exported from `config/instance.ts`, so a second process can never point a beta instance at prod's panes. CLAUDE.md and `docs/architecture-invariants.md` both record the rule.
+
+  ### Thanks
+
+  The TUI went through seven rounds of beta testing over PuTTY/SSH by **@Ark0N**, which is where the way out of an attach, the session strip, the preview repaint handling and the glyph set all came from.
+
+## 1.20.1
+
+### Patch Changes
+
+- Terminal input and scrollback fixes (PRs #327, #331):
+  - IME punctuation preserved (#327): keyCode 229 / `Process` key events are now delegated to xterm's CompositionHelper instead of being suppressed, so an active Chinese IME committing numbers and full-width punctuation (，。！？ and friends) reaches the terminal correctly. The CJK input field sends the browser's committed text instead of guessing from `KeyboardEvent.key`, and the redundant Android orphan-input fallback is removed so xterm is the single input owner.
+  - Shell history replay bounded (#331): selecting a Shell session loads a bounded 1 MiB tail instead of replaying the entire multi-megabyte tmux scrollback on xterm's main thread; full history stays available via the explicit "Load full history" action. tmux history limits now apply correctly on both legacy tmux (global default set in the same command queue before pane creation) and tmux 3.7+ (per-pane targeting that never resizes or trims unrelated live panes). Also adds `Server-Timing` and `[TERMINAL-PERF]` timing stages for terminal loads, fixes `scrollToLastNonEmptyLine` double-counting scrollback rows, and keeps live output ordered behind snapshot replays.
+
+  ### Thanks
+  - @dignfei for both fixes: the IME punctuation root-cause fix (#327) and the bounded shell history replay with the tmux history-limit correctness work (#331).
+
+## 1.20.0
+
+### Minor Changes
+
+- Response viewer for OpenCode, Gemini, Antigravity and Pi sessions (#326). External CLIs render their own TUIs, so the viewer used to come up empty for them; a new transcript parser (`response-viewer-transcript.ts`) reconstructs the conversation from the pane text instead, and the `?context=full` view now tags every block with a role so prompts render as "You" and agent output as the assistant. The divider normalizer was rewritten as a linear scan after review found catastrophic backtracking on agent-controlled input (minutes of stall on a long dash run), with an equivalence corpus pinning the old accept set.
+
+  CLIs installed via nvm or Homebrew are now found when Codeman runs as a service (#329). A shared resolver falls back to a login-shell probe when the direct PATH lookup misses, so systemd and LaunchAgent installs no longer report every CLI as missing. Review hardening on top: a failed resolution is negative-cached with doubling backoff instead of re-spawning a login shell on every request, all probes pass `killSignal: 'SIGKILL'` (interactive bash shrugs off SIGTERM, and a blocking `.bash_profile` could have hung the server indefinitely), the resolvers are inert under vitest again so test suites cannot execute binaries found on the dev box, and the improved not-found guidance is wired into both the session-create errors and the per-CLI status endpoints.
+
+  `GET /api/system/repo-status` reports branch, upstream, ahead/behind and remote reachability for git-clone installs (#328). Review hardening: the git network calls moved off the synchronous path onto a single-flight 45s cache (one slow remote could previously freeze the whole server for up to a minute per request), remote URLs and git stderr are credential-redacted before they leave the server, the spawns use the same non-interactive git env as the clone path, and a local-branch upstream no longer parses into garbage.
+
+  Auto Copy for the terminal (#325, opt-in, per-device): a finished selection (mouse drag, double or triple click, or a phone long-press) lands on the clipboard by itself, so select-then-copy becomes select. Alongside it, hand-encoded tap reports are now gated on the server-observed `cliMouseTracking` state, so a pane that has fallen back to a plain shell no longer receives `[<0;88;20M` junk on tap.
+
+  The Ralph loop no longer stops polling after two ticks (#330): the reschedule guard read a stale timer handle that the timer callback never cleared, so the loop silently died while its status stayed `running`. The handle is now nulled as the callback's first statement, and a regression test pins the bug.
+
+  The red "needs you" tab alert clears when a dialog is answered in the terminal instead of surviving until the end of the turn: the post-hook re-capture could erase the parsed dialog options that the staleness sweep relies on (`applyCapture` is now add-only for options), and a delayed staleness pass now runs while a page is open. The unreachable `copyTerminal()` was removed, closing out #322.
+
+  ### Thanks
+  - @aakhter contributed the external-CLI response viewer (#326), the repo-status endpoint (#328), the login-shell CLI resolution (#329) and the Ralph reschedule fix (#330)
+  - @rounakdatta reported the mobile copy gap (#322) closed out in this release
+
 ## 1.19.7
 
 ### Patch Changes

README.md

@@ -285,7 +285,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 - **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
 - **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
-- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+- **SSH** — `codeman tui` is a full-screen dashboard in the terminal (`codeman tui --list` to list, `codeman tui 2` to attach straight to one).
 
 ### 7. Operate & maintain
 
@@ -658,17 +658,19 @@ These run for **every** request — before auth, even on the default no-password
 
 ---
 
-## SSH Alternative (`sc`)
+## Terminal UI (`codeman tui`)
 
-If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
+A full-screen dashboard for your sessions, in the terminal. Same states as the web UI, because it is a client of the same server:
 
 ```bash
-sc              # Interactive chooser
-sc 2            # Quick attach to session 2
-sc -l           # List sessions
+codeman tui              # the dashboard
+codeman tui --list       # numbered session list, then exit (scriptable)
+codeman tui 2            # attach straight to session 2 of that list
 ```
 
-Single-digit selection (1-9), color-coded status, token counts, auto-refresh. Detach with `Ctrl+A D`.
+Sessions are grouped **NEEDS YOU → WORKING → IDLE → RECENT**, longest-waiting first. `↑↓`/`j`/`k` select, `1`-`9` and `[`/`]` switch between sessions, `Enter` attaches into the tmux pane (**`F1`** to come back). Inside a pane the bar across the top keeps the session strip visible and `Alt+1`-`Alt+9` switch without leaving. `y`/`n`/digit answer a pending permission dialog right from the list, `p` sends a one-line prompt, `n` starts a session and opens straight into it, `x` kills one (`y` confirms), `/` searches, `g` shows the away digest, `?` is help, `q` quits. Below 72 columns it drops the preview pane and becomes a single-column list, so it stays usable in Termius on a phone. With no server running it still starts in attach-only degraded mode.
+
+The web UI remains the primary surface; see **[docs/tui.md](docs/tui.md)** for the full guide.
 
 ---
 
@@ -893,7 +895,9 @@ codeman session start -d /path/to/repo   # (s)  start a session
 codeman session list                     #      list sessions
 codeman session logs <id>                #      tail output
 codeman task add "fix the failing test"  # (t)  queue a task
-codeman attach <path>                     #      attach a Claude hook context
+codeman attach <path>                    #      show an attachment card for a local file
+codeman tui --list                       #      numbered session list (plain text when piped)
+codeman tui 3                            #      attach to session 3 of that list
 ```
 
 ### Hooks (events flowing _back_ to Codeman)

README.zh-CN.md

@@ -253,7 +253,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 - **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
 - **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
-- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+- **SSH** —— `codeman tui` 是终端里的全屏会话面板（`codeman tui --list` 列出，`codeman tui 2` 直接附着到某个会话）。
 
 ### 7. 运维与维护
 
@@ -615,20 +615,6 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 
 ---
 
-## SSH 替代方案（`sc`）
-
-如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
-
-```bash
-sc              # 交互式选择器
-sc 2            # 快速附着到会话 2
-sc -l           # 列出会话
-```
-
-单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
-
----
-
 ## 键盘快捷键
 
 > Ctrl 绑定在 macOS 上也接受 Cmd。

docs/architecture-invariants.md

@@ -14,7 +14,7 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Instance isolation and the multi-instance attach danger
 
-**Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.
+**Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`, and any new `tmux -L` caller through `resolveTmuxSocketName()` (same module): it applies the `CODEMAN_TMUX_SOCKET` override only when the name is safe and falls back to `DEFAULT_TMUX_SOCKET` otherwise. `TmuxManager` was the only such caller until `codeman tui` shelled out to tmux from a SECOND process for its degraded-mode listing and its attach handoff; a hardcoded `codeman` there would have pointed a beta instance straight at prod's panes.
 
 ## Session launch modes
 
@@ -92,13 +92,15 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Full-scrollback replay
 
-**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load OF EACH SESSION per page load requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other tab one frame of history); later switches keep the cheap `?tail=` visible-frame path. On top of that, scrolling up while already at the TOP of the buffer re-pulls `full=1` on demand (`_maybeRefetchFullHistory`, 4s per-session cooldown, in-flight + tab-switch guards, viewport position held across the replay). The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`.
+**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other TUI tab one frame of history). Shell sessions instead load a bounded 1 MiB `?tail=` window on every selection: a 100k-line shell capture can be tens of MiB, and automatically parsing it makes tab-switch latency scale with the entire session. Shell full history is therefore explicit-button-only; reaching the top during an ordinary wheel/touch gesture must not reset xterm and replay the multi-megabyte capture on its main thread. Other modes may still re-pull `full=1` at the TOP, and pressing **Load full history** forces the request for any recoverably truncated session (`_maybeRefetchFullHistory`, 4s per-session gesture cooldown, in-flight + tab-switch guards, viewport position held across the replay); Shell full pulls are not retained in the tab cache, so the next switch stays bounded. Chunked replay enqueues 32 KiB pieces across safe yields, appends an xterm parse marker, then releases the live-output gate; output arriving after that release stays ordered behind the snapshot, while the marker callback supplies accurate parse timing without extending the pre-existing queued-event discard window. The route exposes capture/prepare totals in `Server-Timing`, while `[TERMINAL-PERF]` separates TTFB, body/JSON, reset+parse and total time for both selection and on-demand full pulls; parse completion is not a browser compositor/GPU paint measurement. The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`.
 
 ### Terminal scrollback: strip flavors and wheel/touch forwarding
 
-**Two strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. Every other mode (shell/opencode/antigravity/pi) gets the NARROW strip (`isMuxAltScreenOnlyStripMode`) — alt-screen toggles ONLY — and only when tmux-backed (`useMux`). Rationale: the tmux CLIENT emits `smcup` as its first bytes at attach, before any program runs, parking xterm in the scrollback-less alternate buffer for the whole session (touch scrolling no-ops; xterm's own wheel handler converts the wheel to Up/Down arrows = readline history cycling — both #205 symptoms). tmux never forwards a pane program's alt-screen toggles to its client (it repaints instead; measured — vim/less inside a pane emit zero to the client), so the only thing the narrow strip ever removes is tmux's own smcup. It keeps `3J` (a user's `clear` is a deliberate scrollback wipe) and the mouse DECSETs (tmux passes those through even with `mouse off`; stripping them would break htop/vim mouse support). ⚠️ The `useMux` gate is load-bearing: `startShell()`/`startInteractive()` fall back to a DIRECT PTY when mux creation fails, and there the inner program's own `?1049h` really does reach xterm — stripping it would break vim/less/htop for real. The replay path (`session-routes.ts`, via `session.usesMux`) applies the same narrow branch; the frontend `_sessionUsesServerMouseStrip()` mirror stays claude/codex/gemini because only the FULL strip touches mouse DECSETs. The chunk-boundary carry (`_altScreenSeqCarry`) runs for both flavors. Tests: `test/claude-scrollback-strip.test.ts`.
+**Two strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. Every other mode (shell/opencode/antigravity/pi) gets the NARROW strip (`isMuxAltScreenOnlyStripMode`) — alt-screen toggles ONLY — and only when tmux-backed (`useMux`). Rationale: the tmux CLIENT emits `smcup` as its first bytes at attach, before any program runs, parking xterm in the scrollback-less alternate buffer for the whole session (touch scrolling no-ops; xterm's own wheel handler converts the wheel to Up/Down arrows = readline history cycling — both #205 symptoms). tmux never forwards a pane program's alt-screen toggles to its client (it repaints instead; measured — vim/less inside a pane emit zero to the client), so the only thing the narrow strip ever removes is tmux's own smcup. It keeps `3J` (a user's `clear` is a deliberate scrollback wipe) and the mouse DECSETs (tmux passes those through even with `mouse off`; stripping them would break htop/vim mouse support). ⚠️ The `useMux` gate is load-bearing: `startShell()`/`startInteractive()` fall back to a DIRECT PTY when mux creation fails, and there the inner program's own `?1049h` really does reach xterm — stripping it would break vim/less/htop for real. The replay path (`session-routes.ts`, via `session.usesMux`) applies the same narrow branch; the frontend mirror (`_shouldReportMouseToCli()`) stays claude/codex/gemini because only the FULL strip touches mouse DECSETs. The chunk-boundary carry (`_altScreenSeqCarry`) runs for both flavors. Tests: `test/claude-scrollback-strip.test.ts`.
 
-**Only claude ≥ 2.1.187 forwards the wheel; every other mode scrolls local scrollback** (#227 follow-up, `terminal-ui.js:_shouldForwardWheelToApp`). Codex was in the forward list until a reporter hit a completely dead wheel in codex tabs while the scrollbar drag worked. Measured against codex-cli 0.147.0 in a bare tmux: it never enables mouse tracking (`mouse_any_flag=0`) and SGR wheel reports fed to its PTY change nothing on screen, because it runs an INLINE viewport (`alternate_on=0`) and pushes its transcript into the terminal's own scrollback (tmux `history_size` grows) instead of paging in-app. So for codex, local scrollback IS the transcript and forwarding swallowed every tick. ⚠️ "The TUI is a strip mode" is NOT evidence that it consumes wheel reports — verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR TAPS stay enabled for codex (`_sessionUsesServerMouseStrip`); measured, they are no-ops that insert nothing, so click-to-position is simply unavailable there rather than harmful.
+⚠️ **What the full strip removes, it must REMEMBER.** Stripping the mouse DECSETs means xterm's `modes.mouseTrackingMode` is permanently `'none'` for those modes, so the browser hand-encodes click reports to compensate (`_sendSyntheticSgrTap`). With no state to consult it did that on EVERY click, which delivered mouse reports to programs that never asked for them: the same pane runs a plain shell whenever the CLI has exited or a `shell` was started inside a claude-mode session, and a shell prints the report as literal text (`[<0;88;20M`), garbling the next line typed. `_recordStrippedMouseMode()` therefore records each stripped sequence as it goes and publishes `cliMouseTracking` through `toState()`, and `_shouldReportMouseToCli()` requires it. ⚠️ Only the TRACKING modes count (1000/1001/1002/1003): 1005/1006 select an ENCODING and 1007 is alt-scroll, and counting those would put the stray reports straight back. ⚠️ The change broadcasts IMMEDIATELY rather than through `broadcastSessionStateDebounced`, because the flag flips when a dialog opens and the user can click that dialog inside the 500ms debounce window. Measured on a live claude 2.x: the CLI holds a tracking mode on continuously (so clicks keep being reported exactly as before), while a bash prompt in the same stripped mode reports nothing. Fails toward silence: after a server restart the flag is false until the CLI re-emits, which tmux does at client attach.
+
+**Only claude ≥ 2.1.187 forwards the wheel; every other mode scrolls local scrollback** (#227 follow-up, `terminal-ui.js:_shouldForwardWheelToApp`). Codex was in the forward list until a reporter hit a completely dead wheel in codex tabs while the scrollbar drag worked. Measured against codex-cli 0.147.0 in a bare tmux: it never enables mouse tracking (`mouse_any_flag=0`) and SGR wheel reports fed to its PTY change nothing on screen, because it runs an INLINE viewport (`alternate_on=0`) and pushes its transcript into the terminal's own scrollback (tmux `history_size` grows) instead of paging in-app. So for codex, local scrollback IS the transcript and forwarding swallowed every tick. ⚠️ "The TUI is a strip mode" is NOT evidence that it consumes wheel reports — verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR TAPS are gated by `_shouldReportMouseToCli()` (strip mode AND the server-observed `cliMouseTracking` flag, recorded by `_recordStrippedMouseMode` in session.ts as it strips): codex never enables mouse tracking, so since #325 no tap report is sent there at all — click-to-position was already a measured no-op in codex, and a pane that has fallen back to a shell no longer receives `[<0;88;20M` junk.
 
 **Wheel/touch forwarding is NOT gated on viewport-at-bottom** (#205, `terminal-ui.js:_shouldForwardWheelToApp`): for sessions verified to scroll their own transcript on SGR wheel reports (claude ≥ 2.1.187 — version via the local/docker/remote `--version` probes), the plain wheel AND touch drags forward as coalesced SGR reports (`_forwardScrollToApp` → `_sendSyntheticSgrWheel`, 40ms batches, 5-tick cap, 512-byte queue bound). It used to gate on the viewport being at the bottom so both scrollbacks stayed reachable, but a repaint-mode CLI keeps NO terminal scrollback of its own — xterm's buffer holds only replayed repaint frames, so local scrolling drags the CLI's pinned prompt box up the screen over stale frames; and `scrollToLastNonEmptyLine()` routinely parked the viewport off-bottom, silently pinning the wheel to local. Forwarding now snaps the viewport home first (SGR coordinates address the LIVE screen — a report computed from a scrolled-up viewport would hit-test the wrong row). Local scrollback remains on Shift+wheel and the `terminalWheelLocalScrollback` opt-out (both also cover touch via the shared gate; touch has no Shift, so the setting is its only local pin). `_wheelScrollLines()` normalizes `deltaMode` (Firefox fires LINE deltas ≈3/notch — read as pixels that rounded to 0 and fell to the ±1 fallback, ~4× too slow; PAGE deltas scale by `terminal.rows`) while keeping the #154 Shift-axis trap (macOS trackpads put Shift+scroll magnitude on deltaX). Tests: `test/terminal-touch-tap.test.ts`.
 
@@ -258,6 +260,22 @@ Invariants:
 
 Copy goes through `_copyText()` (Clipboard API, then hidden-textarea + `execCommand`), not raw `navigator.clipboard`, because `install.sh`'s LAN option serves plain HTTP where `navigator.clipboard` is undefined; the fallback steals focus, so the terminal is refocused afterwards. Related: xterm registers its own `copy` listener on the terminal element gated on `hasSelection()`, which is why right-click → Copy has always worked. Selection itself is unavailable on touch devices by design (`user-select: none` on the terminal subtree), and in `shell`/`opencode`/`antigravity` tabs the TUI owns the mouse, so selecting there needs Shift+drag. Tests: `test/terminal-copy-selection.test.ts` (gate + wiring invariants), `test/terminal-copy-shortcut.test.ts` (browser, real key presses).
 
+### Auto Copy (copy-on-select)
+
+**Auto Copy** (`autoCopySelection`, per-device, default OFF) puts a finished terminal selection on the clipboard without a keystroke. It is a thin layer over the smart-copy machinery above and shares `_copyText()` with it, but the two paths differ in every decision that matters:
+
+- **It fires at the END of a gesture, never on selection change.** `onSelectionChange` runs for every cell a drag crosses, so copying there would be one clipboard write per mouse move. The callback only ARMS `_autoCopyPending`; the flush is a document-level `mouseup` listener installed once in `initTerminal`, plus explicit calls from the touch selection path.
+- **The flush is synchronous inside the handler.** Both clipboard paths need user activation: Firefox gates `navigator.clipboard.writeText` on it, and `document.execCommand('copy')` (the plain-HTTP fallback that `install.sh`'s LAN option lands on) has to run in the gesture's own task. Deferring to a timer or waiting for `onSelectionChange` loses it, and the failure is browser-specific and invisible in Chrome.
+- **The listener is on `document`, not the terminal container**, because a drag that ends outside the terminal (sweeping up past the header) delivers its mouseup to the document. Unrelated mouseups elsewhere on the page are filtered by the decision helper, not by the listener's target.
+- **Touch has its own entry point.** `_endTouchSelectionGesture()` and `_selectTouchSelectionLine()` call the flush directly, because the touch path `preventDefault()`s its touchend (that is what stops the compat mouse pair from stealing the selection back), so no mouseup ever reaches the document there. Without those two calls the toggle is simply dead on a phone.
+- **It must NOT do what `copyTerminalSelection()` does.** That one clears the selection (so a second `Ctrl+C` is an interrupt) and focuses the terminal. Clearing would make text vanish from under the cursor that just highlighted it, and focusing opens the on-screen keyboard over it on a phone. Focus is instead RESTORED to whatever held it before the copy, which only matters for the `execCommand` fallback (it focuses a temp textarea on the way through); the Clipboard API path never moves focus at all.
+
+`decideAutoCopy()` (constants.js, pure) holds the guards: setting off, blank or whitespace-only text (what a drag across empty cells produces), and a `AUTO_COPY_MAX_CHARS` (1M) cap. ⚠️ The cap is not decoration: a drag off the top of the viewport autoscrolls, so one gesture can sweep the whole 50k-line scrollback. Past it the copy is REFUSED rather than truncated, with a toast pointing at `Ctrl+C`, which still copies everything through the explicit path.
+
+⚠️ **Two dedupe rules, and both earn their place.** A genuine selection change (`pending`) always copies, so re-selecting the same text after copying something else in between still works. Otherwise only text differing from the last auto-copy does, which is what stops an unrelated mouseup from re-copying a stale selection AND what makes the first copy of a drag work at all: xterm fires `onSelectionChange` from its own document `mouseup` handler, and listener order between the two is registration order, not something this code controls. Gating on `pending` alone silently drops that first copy.
+
+Feedback is silent on success except ONCE per page load (a feature that works by doing nothing visible cannot otherwise be told from a dead toggle); failures and refusals toast, throttled to 10s so a permanently blocked clipboard cannot paint a toast on every drag. The setting is per-device on both counts required by the settings rule: it is in `displayKeys` AND absent from the `.strict()` `SettingsUpdateSchema` (clipboard access differs by device and by origin, and the plain-HTTP LAN install has no `navigator.clipboard` at all). Tests: `test/terminal-auto-copy.test.ts`.
+
 ### Settings surface: App Settings, Session Options, Add Case
 
 **One visual language, three modals.** `#appSettingsModal`, `#sessionOptionsModal` and `#createCaseModal` share the `set-*` surface (left rail, sections of grouped row cards, label + description on the left, control pinned right) through a single `:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal)` scope in `styles.css`. An `:is()` list takes the specificity of its **most specific argument**, and all three arguments are ids, so every rule kept exactly the weight it had when the block was `#appSettingsModal`-only: nothing downstream shifted in the cascade. That property is what let the surface absorb Session Options and then Add Case in two separate commits without a cascade audit each time.
@@ -359,7 +377,7 @@ Anatomy: `.set-shell` → `.set-shell-head` (title + `.set-head-actions`) + `.se
 
 ### Buffers, uploads, and terminal history
 
-Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired live); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). tmux <3.7 allocates history at pane creation, so `createSession()` sets the global default in the same command queue immediately before `new-session`; tmux 3.7+ instead creates the session and targets only that pane, because changing the global option can resize and trim unrelated live panes. A settings change resizes tracked panes only on 3.7+ and otherwise affects future panes; no version can recover lines already evicted. Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
 
 ## Local packages and build artifacts
 

docs/pi-integration.md

@@ -139,7 +139,7 @@ set -g extended-keys-format csi-u
 
 Codeman's browser input path sends `\r` for submit, so basic use works
 unconfigured — what degrades is newline-in-editor, mostly when you attach to the
-pane directly (`sc`).
+pane directly (`codeman tui`).
 
 ⚠️ Upstream notes the setting may need a full `tmux kill-server` to take effect.
 **Never run `tmux kill-server` on Codeman's socket** — it would kill every live

docs/tui-plan.md

@@ -0,0 +1,219 @@
+# Codeman TUI Rework Plan
+
+Status: **phases 0-2 implemented** on `feat/tui`; phases 3-4 remain follow-ups. The user guide is [`docs/tui.md`](tui.md); this document stays the design record.
+
+- Phase 0: `src/cli-style.ts` (palette, glyphs, `heading`/`kv`/`table`/`spinner`/`confirm`) plus the mechanical fixes of §5, and `test/cli-commands.test.ts` now derives its inventory from the real commander `program` instead of parsing a fixture.
+- Phases 1-2: `src/tui/`. `tui-app.ts` (main loop, attach handoff, verbs) and `tui-client.ts` (API, SSE, degraded enumeration) are the only IO; `tui-model`, `tui-layout`, `tui-render`, `tui-keys`, `tui-ansi`, `tui-composer`, `tui-approvals`, `tui-digest`, `tui-sse` and `tui-types` are pure and unit-tested, with an E2E suite driving the real binary under node-pty.
+- Deferred with the rest of phase 3: `r` (resume a RECENT row) is not wired up, so the help overlay does not advertise it.
+- Not started: phase 3 (mouse, `--pick` popup switcher, opt-in attach status line, OSC 9) and phase 4 (retiring the bash choosers).
+
+The goal: replace Codeman's scattered terminal surfaces with one first-class TUI, `codeman tui`, that gives SSH/terminal users the same at-a-glance awareness the web UI gives browsers. The reference point is herdr (herdr.dev), the trending Rust "agent multiplexer" whose defining feature is a live agent-state sidebar. Codeman can match and beat that sidebar in the terminal because the states herdr infers from screen-scraping heuristics are states our server already computes from hooks, pane probing, and the approvals inbox.
+
+---
+
+## 1. What we have today (inventory)
+
+Three disconnected surfaces, three visual idioms, two data sources:
+
+| Surface | What it is | Data source | Idiom |
+| --- | --- | --- | --- |
+| `codeman` CLI (`src/cli.ts`, 1214 lines) | commander + chalk, ~20 commands | HTTP API + state files | `✓`/`✗` line-per-fact, no interactivity |
+| `sc` (`scripts/tmux-chooser.sh`, 663 lines) | bash number-menu chooser, mobile-tuned (44 cols) | `tmux -L codeman` + `state.json` via jq | 256-color, numbered, full repaint per key |
+| `scripts/tmux-manager.sh` (529 lines) | bash cursor TUI with kill/info | `mux-sessions.json` (and writes it back) | 8-color, box-drawn, arrow keys |
+
+Weaknesses found in the audit (file:line refs verified 2026-08-16):
+
+1. **No interactive picker in the Node CLI at all.** Every `session stop`, `task status`, `session logs` requires a pasted UUID prefix. There is no `codeman attach <session>`; `codeman attach` is actually the attachment-card command (and `README.md:895` describes it wrongly).
+2. **`sc` cannot reach sessions 10+ interactively**: entries are numbered globally (`tmux-chooser.sh:343`) but input accepts a single `[1-9]` keypress (`:487-493`). Page 2 shows items 8-14 that mostly cannot be selected.
+3. **No cursor/selection concept in `sc`** (`BG_SEL` at `:90` is dead code); arrows only page.
+4. The two bash tools can disagree about which sessions exist (different data files), and only `sc` is on PATH.
+5. **Zero live feedback anywhere**: `codeman web -d` and `service install` block silently up to 30s (`daemon-control.ts:395-412`); no spinner exists in the codebase.
+6. Styling drift: `doctor` is the only table and is deliberately monochrome with a colorize hook nobody wired up (`dependency-report.ts:5-7`); `codeman web` prints its "running at" line twice (colored `cli.ts:934`, plain `server.ts:2366`); the server's security warning is colorless `console.warn` while the CLI's version of the same warning is yellow; `tmux-manager.sh`'s header box is visibly misaligned; `padEnd(14)` overflows on "Antigravity CLI".
+7. Bash TUIs emit raw escapes unconditionally (no TTY/NO_COLOR gate); `install.sh` and `postinstall.js` do it right.
+8. Detach hint inconsistency: chooser says Ctrl+B D, `README.md:671` says Ctrl+A D.
+9. Inside an attached session there is **no chrome at all**: Codeman turns the tmux status bar off (`tmux-manager.ts:1978`), so an SSH user in a pane has no session identity, no state, no way back to a picker except detach.
+10. `test/cli-commands.test.ts` asserts against a hand-written fixture, not the real `program`, and that fixture already lists a `tui` command that does not exist (`:57-61`). The name is pre-approved by our own test file.
+
+## 2. Research: how herdr does it
+
+herdr (github.com/herdrdev/herdr, ~30k stars, single Rust binary, pre-1.0) is a background terminal multiplexer "your coding agents live on". What matters for us:
+
+- **The agent-state sidebar is the product.** Every pane is classified live as `working` / `blocked` / `done` / `idle` and grouped in a sidebar, so you see who needs you without switching tabs. Reviews unanimously call this "the killer feature tmux can't match".
+- **Detection is heuristic-first**: process-name matching + screen-manifest TOML rules parsing the visible frame; optional per-agent "integration install" adds lifecycle hooks over JSON-RPC on a unix socket for accurate states. Claude Code there is on the heuristic path and reviewers note blocked-state lag.
+- **Model**: workspaces → tabs → panes, tmux-style prefix keys (Ctrl+B V split, arrows navigate, D detach), mouse-first (click select, drag resize, right-click menus, touch over SSH), adapts to narrow widths.
+- **Agent-shaped API**: socket API with `pane read` (visible/recent/detection), `send-text`/`send-keys`/`run`, `agent start|prompt|wait|explain`, `pane wait-output` with regex, plugins placed as overlay/split/tab/popup.
+- **Persistence**: sessions survive disconnects, reattach from any terminal / SSH.
+- Weaknesses reviewers cite: pre-1.0 churn, bus factor 1, no session resurrection, rendering lag with many panes.
+
+What is striking is how much of herdr Codeman already has, server-side: our hooks give exact `permission_prompt`/`stop`/`idle_prompt` events (herdr's "integration" path, but installed by default), `_confirmIdle()` does the screen-probe fallback, the approvals inbox parses the actual dialog options, and the agent skill + wait primitives are our socket API. What we lack is purely the presentation layer in the terminal.
+
+Prior art for the architecture we want: **agent-deck** (Bubble Tea + tmux) proves the "TUI list + attach into tmux" model works great: session list with live glyphs (● ◐ ○ ✕), Enter attaches into a tmux pane, status polling, groups, fuzzy search. We take the shape, not the code.
+
+Licensing note: herdr is reported variously as Apache-2.0/AGPL-3.0. Irrelevant either way: we copy concepts, never code.
+
+### What we take / what we skip
+
+Take: the four-state sidebar as the organizing principle; grouping by "needs you first"; narrow-width adaptation; mouse support; tmux-familiar keys; the "attention at a glance" framing.
+
+Skip: being a multiplexer. tmux already backs every Codeman session and is a hard dependency; herdr had to build pane management because it owns terminals, we do not. Also skip (for now): plugin marketplace, split layouts, pane drag. Our TUI is a **dashboard + switchboard over tmux**, not a tmux replacement.
+
+## 3. Design: `codeman tui`
+
+One command, one full-screen client of the existing HTTP/SSE API.
+
+**Positioning (owner decision, 2026-08-16): the web UI remains THE primary surface.** The TUI is strictly additive, for users who want a terminal workflow (SSH, Termius, tmux die-hards). Bare `codeman` keeps printing help; nothing existing changes behavior. The `sc` bash chooser also stays untouched for now; flipping its alias to `codeman tui` is deferred to a follow-up release once the TUI has mileage.
+
+### Layout (≥100 cols)
+
+```
+ codeman  tnode · v1.19.0 · 6 sessions · 5h ▂▂▅ 32% wk 61%                    ? help  q quit
+ ────────────────────────────────────────────────────────────────────────────────────────────
+  NEEDS YOU ──────────────────────────┐ ┌ w4-api-refactor ── claude · ~/dev/api ────────────
+  ▶ 1 w4-api-refactor  ⚠ approval  2m │ │ ✻ Actualizing… (2m 14s · ↓ 12.3k tokens)
+    2 w6-docs          ✋ waiting  11m │ │
+                                      │ │ ⚠ Claude requests: Bash(git push origin main)
+  WORKING ────────────────────────────┤ │   1. Yes  2. Yes, don't ask again  3. No
+    3 w1-codeman       ✻ 17m    45.2k │ │
+    4 w2-gallery       ✻ 3m      8.1k │ │ [y] approve   [n] deny   [Enter] attach
+  IDLE ───────────────────────────────┤ │
+    5 w3-promo         ○ 2h           │ │  …live tail of the selected session's
+  RECENT ─────────────────────────────┤ │   terminal (ANSI colors preserved),
+    · api-hotfix       ✔ done Fri     │ │   updating while you browse the list…
+ ────────────────────────────────────────────────────────────────────────────────────────────
+  ↑↓ select · ⏎ attach · 1-9 jump · y/n answer · p prompt · n new · x kill · / search · g digest
+```
+
+- **Header**: hostname/instance, server version, session count, plan-usage chip (same telemetry that feeds the web chip, when available). Degrades gracefully when the server is down (see §3.6).
+- **Sidebar**: sessions grouped `NEEDS YOU` → `WORKING` → `IDLE` → `RECENT` (past sessions from the unified list, resumable). Within groups, reuse the activity ordering already built for the home screens in PR #303 (blocked first, running longest, quiet newest); that logic is pure and shared.
+- **Preview pane**: live tail of the selected session, SGR colors preserved, cursor-movement stripped. When the selected session has a pending approval, the parsed dialog is rendered as a card above the tail with one-key answer bindings.
+- **Footer**: contextual keymap (changes when a dialog/confirm is active).
+
+### States and vocabulary
+
+Exactly the web's language so the two surfaces read the same:
+
+| Group | Glyph | Color | Source |
+| --- | --- | --- | --- |
+| NEEDS YOU (question/permission) | `⚠` | red, blinking row | approvals inbox / `permission_prompt` |
+| NEEDS YOU (waiting for input) | `✋` | yellow | `idle_prompt` / waiting classification |
+| WORKING | `✻` animating through `· ✢ ✳ ∗ ✻ ✽` at 2Hz | green | working classification (the same glyph family Claude itself draws, a deliberate nod) |
+| IDLE | `○` | muted | idle |
+| RECENT / done | `✔` | muted green | unified list history rows |
+
+Nerd-font/glyph fallback exactly like `sc` does today (`[!] [w] [*] [-] [ok]` when the terminal is not known-capable), plus full NO_COLOR / `tput colors` degradation (8-color and mono renderings are designed, not accidental).
+
+### Keymap
+
+- `↑/↓` or `j/k` select · `Enter` attach · `1-9` jump-attach (parity with `sc`, but now the cursor covers 10+)
+- `y`/`n` (or the digit keys) answer the selected session's pending approval right from the dashboard, via `POST /api/approvals/:id/answer`. The server already re-captures the pane and 409s if the dialog is gone, so this is safe by construction.
+- `p` send a one-line prompt to the selected session without attaching (`POST /input` with `\r`, the composer opens in the footer)
+- `n` new session (case picker → mode picker, drives `POST /api/quick-start`) · `x` kill with typed confirm (never bulk; refuses the session hosting the TUI itself, like tmux-manager.sh does)
+- `/` fuzzy search across sessions/history/attachments (`GET /api/search`) · `g` away digest (`GET /api/away-digest`) rendered as a panel
+- `r` resume selected RECENT row (unified list `resume-session` flow) · `?` help overlay · `q` quit
+- Mouse (phase 3): SGR mouse reporting, click selects, wheel scrolls list/preview, click on footer keys triggers them. Works over SSH, same as herdr's touch story.
+
+### Responsive behavior
+
+The `sc` design constraint survives: below ~72 cols (Termius, iPhone portrait) the preview pane drops and the TUI is a single-column list with two-line rows, nearly identical to today's `sc` but with a cursor, live states, and the answer/prompt/new/kill verbs. The layout switch is width-driven at draw time, no mode flag.
+
+### Attach model
+
+Enter suspends the TUI (restore main screen + cooked mode), then hands the terminal to `tmux -L <socket> attach-session -t <name>` with `stdio: inherit`. On tmux exit/detach, the TUI resumes and refreshes. Full fidelity (mouse, paste, colors) is tmux's, we never proxy bytes.
+
+- Inside tmux already: same socket → `switch-client -t`; different socket → warn about nesting and offer detach-first. `$TMUX` + `CODEMAN_MUX` detection.
+- **Return path**: a tmux binding installed for codeman sessions (opt-in) runs `codeman tui --pick` inside `tmux display-popup -E`, a minimal picker-only mode (list + jump, no preview) so switching sessions from inside a pane is one keystroke, fzf-style.
+- Optional per-attach chrome (opt-in setting, default off since `status off` at `tmux-manager.ts:1978` is deliberate): a minimal codeman-styled tmux status line showing `name · state · alert`, set on attach, restored on detach.
+
+### Notifications
+
+While the TUI is open and a session flips to NEEDS YOU: flash the row, ring BEL, and optionally emit OSC 9 (desktop notification in kitty/WezTerm/iTerm2, and it traverses SSH). This is the herdr sidebar promise delivered even when the terminal is backgrounded.
+
+### Degraded mode (server down)
+
+`sc` works without the server today and the TUI must too: when no server answers, enumerate `tmux -L codeman list-sessions` + read `state.json` (read-only), show a "server not running" header line, and offer attach only (no states, no approvals). This keeps the "web server crashed, get me to my sessions" path alive.
+
+## 4. Architecture
+
+### A client of the server, not a second brain
+
+Everything live comes from the API the web UI already uses:
+
+| Need | Endpoint |
+| --- | --- |
+| Session list + history | `GET /api/sessions/unified` |
+| Live updates | SSE `GET /api/events` (heartbeat `sse:heartbeat` already exists; fall back to 2s polling) |
+| Pending approvals + parsed options | `GET /api/approvals`, answer via `POST /api/approvals/:id/answer` |
+| Preview tail | `GET /api/sessions/:id/terminal?tail=N` (throttled to the selected session only) |
+| Prompt send | `POST /api/sessions/:id/input` (single line + `\r`, per the composer contract) |
+| New session | `POST /api/quick-start` (routes remote/docker cases correctly) |
+| Search | `GET /api/search` |
+| Away digest | `GET /api/away-digest` |
+| Plan usage chip | latest status-telemetry snapshot (`plan-usage-latest`) |
+
+Server discovery and auth reuse what exists: instance config from `src/config/instance.ts` (`CODEMAN_INSTANCE`, `CODEMAN_PORT`), the probe logic from `daemon-control.ts`, credentials from `~/.codeman/.env` (the established `codeman attach` pattern), self-signed HTTPS accepted for loopback probes (the hooks-on-HTTPS lesson). Multi-user scoping comes free: the API only returns what the authenticated user owns.
+
+### Renderer: hand-rolled, zero new dependencies (decision)
+
+Options considered:
+
+- **Ink (React for CLIs)**: what Claude Code uses. Pros: layout engine, ecosystem. Cons: pulls React into a CLI that today ships only commander+chalk; rerender model fights the two things we care most about (a raw-ANSI preview region and 2Hz glyph animation without flicker); version-pins React for every `npm i -g aicodeman`.
+- **blessed/neo-blessed**: unmaintained, skip.
+- **Hand-rolled screen core** (recommended): this repo hand-rolls ANSI everywhere already and has the expertise (regex-patterns, stripAnsi, the xterm work). The core is small and boring: alt screen + raw mode + cursor-home full-frame repaint from an off-screen string buffer, throttled to state changes and the 2Hz animation tick, wrapped in DECSET 2026 (synchronized output) where supported so repaints are atomic in modern terminals (tmux, kitty, WezTerm, iTerm2). No diffing needed at these frame rates.
+
+The one genuinely tricky pure function: SGR-aware line clipping for the preview (keep colors, strip cursor movement/OSC/DECSET, clip to width while carrying SGR state, reset at EOL). That is a pure module with exhaustive unit tests, and it is exactly the kind of function Ink would not have given us anyway.
+
+### Module layout
+
+```
+src/tui/
+  tui-app.ts        entry + main loop + attach handoff (IO)
+  tui-client.ts     API + SSE client, degraded-mode enumeration (IO)
+  tui-model.ts      pure: state store, grouping, ordering (reuses PR #303 helpers)
+  tui-layout.ts     pure: responsive layout math, row building
+  tui-render.ts     pure: model+layout -> frame string (palette, glyphs, fallbacks)
+  tui-keys.ts       pure: byte stream -> key/mouse events (incl. SGR mouse decode)
+  tui-ansi.ts       pure: SGR-aware clip/filter for the preview
+```
+
+Pure modules unit-test with no TTY. `cli.ts` gains one thin `tui` command registration (and `--list`/`<n>` fast paths for `sc -l` / `sc 2` parity, which must stay fast: they short-circuit before any screen setup).
+
+## 5. CLI-wide polish (the rest of "make it much nicer")
+
+A shared style kit, `src/cli-style.ts`: one palette (mirroring the web's status colors), one glyph set with fallback, `heading()`, `kv()`, `table()` (width-aware, fixes the Antigravity overflow), `spinner()` (finally: the 30s silent daemon/service waits get a live line), `confirm()` (used by `reset --force`'s missing prompt and `x` in the TUI). Then the mechanical fixes from §1: colorize `doctor` through the hook that already exists for it, dedupe the `codeman web` startup line, colorize the server's security warning, fix the README `codeman attach` description and the Ctrl+B/Ctrl+A detach drift, TTY/NO_COLOR gates everywhere.
+
+## 6. Phasing
+
+| Phase | Contents | Size |
+| --- | --- | --- |
+| 0 | `cli-style.ts` + mechanical fixes (§5), real CLI tests (retire the fixture parser in `test/cli-commands.test.ts`) | S |
+| 1 | `codeman tui` core: list + states via SSE, cursor + 1-9, attach/return loop, kill w/ confirm, new session, narrow mode, degraded mode, `sc` alias flip + `--list`/`<n>` parity | M/L |
+| 2 | Preview pane (SGR clip), approvals answering, prompt composer, search, digest, resume, plan-usage header | M |
+| 3 | Mouse support, `--pick` popup switcher + tmux binding, opt-in attach status line, BEL/OSC 9 notifications | M |
+| 4 | Retire `tmux-chooser.sh`/fold `tmux-manager.sh` (keep as thin wrappers for one release), docs/README/wiki, screenshots for promo | S |
+
+Phases 0-1 are the useful minimum; 2 is where it beats herdr's sidebar (answering approvals from the dashboard); 3 is delight.
+
+## 7. Testing
+
+- Pure modules (`tui-model/layout/render/keys/ansi`): plain vitest, frame snapshots as stripped strings plus targeted ANSI assertions.
+- Interactive E2E: spawn the built TUI under `node-pty` (already a dependency), feed keys, assert on captured frames; the vitest tmux mock (`IS_TEST_MODE`) keeps attach paths inert. Port rules per CLAUDE.md (3150+, `app.inject()` where possible by testing `tui-client` against injected routes).
+- Manual: Termius/iPhone portrait (the 44-col case), tmux nesting, server-down mode, NO_COLOR, non-nerd-font terminal.
+
+## 8. Invariants this plan respects
+
+- tmux socket and data dir always via instance config (`dataPath()`, `-L codeman`); a beta instance TUI sees only its own world.
+- Never bulk kill, always confirm, never touch another session implicitly, refuse killing the session the TUI runs in (w1/w2/w3 are sacred).
+- Input is single-line with `\r`, via the server (never raw tmux send-keys from the TUI while the server owns the session).
+- Approvals answering goes through the server's re-capture + 409 path, never blind keystrokes.
+- `status off` on panes stays the default; any chrome is opt-in.
+- No new runtime dependencies; the npm package stays light.
+
+## 9. Decisions (resolved 2026-08-16)
+
+1. **Bare `codeman` does NOT open the TUI** (owner decision): the web UI is the main thing, the TUI is additional. `codeman tui` only.
+2. **`sc` stays the bash chooser for now**; the alias flip is a follow-up once the TUI has mileage. `codeman tui --list` / `codeman tui <n>` provide the same fast paths for people who want to switch.
+3. Opt-in tmux status line: deferred to phase 3 along with the `--pick` popup switcher.
+4. Preview tail goes over the API (auth/multi-user/remote-consistent); previews are simply unavailable in degraded server-down mode.
+5. Name is `codeman tui` (the test fixture historically expected it).
+
+Initial PR scope: phases 0-2. Phase 3 (mouse, popup switcher, status line, OSC 9) and phase 4 (bash chooser retirement) are follow-ups.

docs/tui.md

@@ -0,0 +1,278 @@
+# Terminal UI (`codeman tui`)
+
+`codeman tui` is a full-screen dashboard for your Codeman sessions, in the terminal.
+It shows every session grouped by whether it needs you, lets you answer a permission
+dialog or send a prompt without switching anywhere, and puts you inside a session's
+tmux pane with one keystroke.
+
+It is **additional, not a replacement**: the web UI stays the primary surface and
+gets every feature first. The TUI exists for the terminal workflow (SSH, Termius,
+a tmux window you keep open all day), and it is a *client* of the running server,
+so the two surfaces can never disagree about what a session is doing. It is also
+not a multiplexer: tmux still owns every pane, and attaching hands the terminal to
+tmux rather than proxying bytes.
+
+## Starting it
+
+```bash
+codeman tui              # the dashboard
+codeman tui --list       # print the numbered session list and exit
+codeman tui 2            # attach straight to session 2 of that list
+```
+
+The two fast paths are the scriptable ones.
+Neither sets up a screen, so both are as quick as the one API call they make, and
+`--list` prints plain text when piped, so it composes with `grep`/`awk`.
+
+What it needs:
+
+| Needs | What you get |
+| --- | --- |
+| **Full features** | A running Codeman server (states, approvals, preview, prompts, search, digest). The TUI finds it the way `codeman attach` does: `CODEMAN_API_URL`, else loopback on `CODEMAN_PORT` for this `CODEMAN_INSTANCE`. The self-signed certificate an `--https` install generates is accepted, as it is everywhere else in the CLI. |
+| **Server down** | It still starts, in **degraded mode**: sessions are enumerated straight from `tmux -L codeman` plus a read-only peek at `state.json`, and attach is the only verb. See [Troubleshooting](#troubleshooting). |
+| **A terminal** | `codeman tui` refuses to run when stdin/stdout are not a TTY, and says to use `--list` instead. A cron job or a pipe therefore fails loudly rather than emitting escape codes into a log. |
+
+## What it looks like
+
+A real frame at 100x30 (`NO_COLOR`, trailing blank rows trimmed). The selected
+session has a pending permission dialog, so the preview pane leads with the card:
+
+```
+ codeman  ⚠ 2  tnode · v1.19.0 · 5 sessions · 5h 32% · wk 61%                        ? help  q quit
+ NEEDS YOU ─────────────────────────│ w4-api-refactor · claude · /home/you/dev/api · blocked
+  1 w6-docs                   ✋ 11m│ ⚠ requests: Bash(git push origin main)
+▶ 2 w4-api-refactor             ⚠ 2m│   1. Yes
+ WORKING ───────────────────────────│   2. Yes, and do not ask again
+  3 w1-codeman                  ∗ 1h│   3. No, tell Claude what to do
+  4 w2-gallery                 ∗ 15m│ y approve · n deny · digit chooses
+ IDLE ──────────────────────────────│
+  5 w3-promo shell              ○ 2h│ > refactor the api routes onto the shared port interface
+ RECENT ────────────────────────────│
+  6 api-hotfix                  ✔ 3d│   Read src/web/ports/session-port.ts (48 lines)
+                                    │   Read src/api/routes.ts (312 lines)
+                                    │   Edit src/api/routes.ts
+                                    │    1  -import { SessionManager } from "../session-manager.js";
+                                    │    2  +import type { SessionPort } from "../web/ports/session-
+                                    │
+                                    │   Bash(npm run typecheck)
+                                    │   └ tsc --noEmit: no errors
+                                    │
+                                    │ ✻ Actualizing… (2m 14s · ↓ 12.3k tokens)
+ ↑↓ select · ⏎ attach · y approve · n deny · 1-9 option · p prompt · x kill · / search · g digest ·
+```
+
+- **Header**: the machine, the server version, how many sessions are live, and the
+  plan-usage chip (the same statusLine telemetry that feeds the web chip, when the
+  server has a snapshot). A `⚠ n` badge counts pending approvals.
+- **Sidebar**: every session, grouped and numbered.
+- **Preview**: a live tail of the selected session, its own colors preserved, with
+  the parsed dialog card on top when that session is blocked.
+- **Footer**: only the keys that work right now. `n` reads `n new` normally and
+  `n deny` when the selected session has a dialog, because it cannot be both.
+
+The same world through `--list`:
+
+```
+  1 waiting w6-docs         /home/you/dev/docs
+  2 blocked w4-api-refactor /home/you/dev/api
+  3 working w1-codeman      /home/you/dev/codeman
+  4 working w2-gallery      /home/you/dev/gallery
+  5 idle    w3-promo        /home/you/dev/promo
+  6 done    api-hotfix      /home/you/dev/api
+```
+
+The numbers are the same on both surfaces, so `codeman tui --list` then
+`codeman tui 4` is one thought.
+
+## The four groups
+
+Groups are always in this order, and a session is in exactly one of them:
+
+| Group | Glyph | Means | Comes from |
+| --- | --- | --- | --- |
+| **NEEDS YOU** | `⚠` | A permission or question dialog is blocking the agent | The approvals inbox (`permission_prompt` hooks, with the on-screen options parsed) |
+| | `✋` | Waiting for your next instruction, or errored | `idle_prompt`, or an errored session (equally something only a human clears) |
+| **WORKING** | `✻` animating | A turn is running | The same working classification the web dashboard uses |
+| **IDLE** | `○` | Live, but sitting there | |
+| **RECENT** | `✔` | A past session from the unified list | History rows, no live pane |
+
+Ordering inside a group is "the one that has waited longest, first": blocked
+sessions sort by how long the dialog has been up, working sessions by when their
+turn started (the pane's last Enter, since a working pane repaints every second
+and would otherwise always look freshly started), and quiet ones by last activity.
+That is the ordering the web home screens already use.
+
+The cursor sticks to a **session**, not a row number, so a session that jumps to
+NEEDS YOU does not drag your selection with it. The number beside each row is what
+`1-9` and `codeman tui <n>` mean, and it is renumbered on every re-sort.
+
+When a new dialog appears, the terminal bell rings once, for that dialog only: the
+same item announced twice does not ring twice.
+
+## Keymap
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` or `j` `k` | Move the cursor. PageUp/PageDown jump five rows. |
+| `Enter` | Attach to the selected session (see [Attaching](#attaching)) |
+| `1`-`9` | Jump to that row and attach. When a dialog is on screen, a digit answers it instead (see below). |
+| `y` | Approve the selected session's dialog |
+| `n` | Deny it, or **start a new session** when there is no dialog |
+| `p` | Send one line to the selected session without attaching |
+| `x` | Kill the selected session; `y` confirms, any other key cancels |
+| `/` | Search sessions, events and files |
+| `g` | Away digest: what happened while you were gone |
+| `?` | Help overlay |
+| `Esc` | Close whatever overlay is open |
+| `q` or `Ctrl+C` | Quit, restoring the screen you started with |
+
+Inside the `p` composer and the `/` query: `←` `→` `Home` `End` `Delete`
+`Backspace` plus `Ctrl+A` / `Ctrl+E` / `Ctrl+U` / `Ctrl+W`, `Enter` to send or open,
+`Esc` (or `Ctrl+C`) to cancel. In the kill confirmation you retype the session name;
+anything else cancels. In the `n` pickers, type to filter, `Enter` chooses.
+
+Verbs that need the server (`y`/`n`/`p`/`x`/`/`/`g`) say so in degraded mode
+instead of failing silently; `Enter` and `1-9` keep working.
+
+### `p` sends exactly one line
+
+The composer is a single line by design, ending in a carriage return: that is the
+input contract every Codeman path follows, because multi-line text breaks the
+agent's own composer. Pasted newlines become spaces rather than being rejected, so
+a paste cannot silently run a different command than the one you read.
+
+## Answering approvals
+
+This is the thing the terminal could not do before. Select a blocked session and:
+
+- `y` approves.
+- `n` picks the parsed "No" option, or sends Esc when the dialog did not parse one.
+- A digit picks that numbered option, **but only a digit the dialog actually
+  offers**. A digit with no matching option falls through to the list's own
+  jump-and-attach binding, so it can never be typed at whatever has focus.
+
+The answer goes through `POST /api/approvals/:id/answer`, which **re-captures the
+pane before it types anything**. If the dialog is no longer on screen (you answered
+it in tmux a moment ago, or the agent moved on), the server refuses with a 409 and
+the TUI says `that dialog is no longer on screen` rather than pressing a key into a
+live composer. The answer is scoped to the options the server parsed off the actual
+frame, never to a guess.
+
+An idle prompt (`✋`) is not a dialog: there is nothing to approve, so `p` is the
+reply path and the footer says `p reply` instead of `p prompt`.
+
+## Attaching
+
+`Enter` suspends the dashboard (main screen back, cooked mode back) and hands the
+terminal to tmux with `stdio: inherit`. Colors, mouse and paste are tmux's, at full
+fidelity.
+
+**Press `F1` to come back.** One key, no modifier to hold or release, nothing to
+type in a particular order. tmux's own way out is a chord — press the prefix, let
+go, then a letter — and beta testing showed that is genuinely hard to convey: the
+bar first named the wrong letter (tmux binds lowercase `d` to `detach-client` and
+capital `D` to `choose-client`), and once corrected it still failed for anyone who
+kept Ctrl held, because that sends `Ctrl+D`, which tmux leaves unbound. So the TUI
+claims `F1` in tmux's prefix-less key table for the length of the attach and gives
+it back afterwards. The chord still works; it is simply not what you are told to
+press.
+
+You do not have to remember any of it. For as long as the attach lasts the pane
+wears a bar across the top:
+
+```
+ 1 w3-codeman-…  2 w4-codeman-…  3 testcase …     alt+1-9 switch · F1 back to the codeman dashboard
+```
+
+That is the **session strip**: the other sessions stay visible from inside a pane,
+numbered exactly as the dashboard numbers them, with the one you are in inverted.
+`Alt+1`..`Alt+9` switch between them without going back to the dashboard first. With
+more sessions than fit, the strip shows a window around the current one and marks
+each cut end with `…`; the way-out hint is measured first and always keeps its space.
+
+Codeman keeps the status bar off on its panes (the web UI carries that information
+around the terminal instead), so the TUI turns it on for the attach and puts it back
+exactly as it was on detach, along with each window's size. Every session the strip
+can switch to is dressed and sized the same way, so switching is instant and lands
+in a pane that already fills your terminal.
+
+Detaching leaves the agent running; typing `exit` or pressing `Ctrl+D` would end it,
+which is the difference the bar exists to make obvious. If an agent does exit, its
+pane stays as a corpse: the TUI refuses to attach to a dead pane and offers `r` to
+resume the conversation in a fresh one instead.
+
+Three cases:
+
+| Where you are | What happens |
+| --- | --- |
+| Not in tmux | `tmux -L codeman attach-session` |
+| Already in tmux on Codeman's socket | `switch-client`, so you do not nest |
+| In tmux on a **different** socket | Refused, with an explanation: detach from that tmux first, then run `codeman tui` again |
+
+A direct-PTY session has no pane to attach to, and says so.
+
+**`Enter` on a RECENT row resumes that conversation** instead: there is no pane to
+attach to, so the TUI creates a new claude session carrying the old transcript
+(`resumeSessionId`, exactly what the web UI's "Resume Conversation" list does), in
+the directory it originally ran in and under its old name, then attaches to it. It
+is claude-only, and a row with no working directory or no conversation id says why
+rather than resuming something else.
+
+`x` never bulk-kills: it kills one session, only after you retype its name, never a
+history row, and never the session the TUI itself is running in.
+
+## Over SSH, and on a phone
+
+The TUI is an ordinary terminal program with no local dependencies beyond tmux, so
+`ssh box` then `codeman tui` works exactly like running it locally. There is no
+separate remote mode.
+
+Below 72 columns (Termius, an iPhone in portrait) the preview pane is dropped and
+rows take two lines each, keeping the cursor, the live states and the
+answer/prompt/kill verbs. The switch is
+width-driven at draw time, so unfolding a foldable or resizing a window re-lays out
+immediately; there is no mode flag to set.
+
+## Troubleshooting
+
+**"The Codeman server rejected these credentials."** The server has
+`CODEMAN_PASSWORD` set. Export `CODEMAN_PASSWORD` (and `CODEMAN_USERNAME` if it is
+not `admin`), or put them in the data dir's `.env` (`~/.codeman/.env`), which is
+where `codeman attach` already reads them from.
+
+**`server not running: attach only`** in a yellow banner. Nothing answered on the
+expected port, so the TUI fell back to enumerating tmux. You get names and attach;
+you do not get states, approvals or previews, because those only exist on the
+server. Start the server (`codeman web -d`, or `systemctl --user start codeman-web`)
+and the banner clears on its own: the TUI keeps re-probing.
+
+**It found the wrong server, or none.** Discovery is instance-scoped. A beta
+instance (`CODEMAN_INSTANCE=beta`) has its own data dir *and* its own tmux socket,
+so its TUI sees only its own sessions. Set `CODEMAN_PORT` or `CODEMAN_API_URL`
+explicitly when you run more than one.
+
+**"this terminal is already inside tmux on socket ..."** You are in a tmux session
+on a socket that is not Codeman's, so attaching would nest two multiplexers whose
+prefix keys collide. Detach from that tmux and run `codeman tui` from outside.
+
+**Boxes and glyphs render as garbage.** The TUI picks a glyph tier from the
+environment: no `TERM` (or `dumb`), or a non-UTF-8 locale, gets the ASCII set
+(`[!] [w] [*] [-]`, `+`/`-`/`|` frames). Force it either way with
+`CODEMAN_TUI_GLYPHS=ascii|unicode|nerd`.
+
+**Colors.** Standard `NO_COLOR` / `FORCE_COLOR` handling (chalk's, the same as the
+rest of the CLI). Under `NO_COLOR` the frame is cursor addressing and text only,
+and the preview's own colors are stripped too, so a session's output cannot repaint
+the dashboard.
+
+**It refuses to open at all**, saying it needs an interactive terminal. stdout or
+stdin is not a TTY. That is the guard: use `codeman tui --list`.
+
+## Related
+
+- [`docs/tui-plan.md`](tui-plan.md): the design record. Why hand-rolled ANSI, why a
+  client and not a second brain, and what is deliberately deferred.
+- [`docs/approvals-inbox-plan.md`](approvals-inbox-plan.md): where the parsed
+  dialogs and the answer endpoint come from.
+- [`docs/remote-sessions.md`](remote-sessions.md): remote-SSH cases, which the TUI
+  lists like any other session.

docs/wiki/Core-Concepts.md

@@ -88,7 +88,7 @@ would. That indirection buys:
 - **Real scrollback.** History is held by tmux, so reconnecting replays what happened while
   you were gone instead of starting from blank.
 - **Attach from anywhere else.** The same session is reachable from a terminal over SSH
-  with the `sc` chooser, or plain `tmux -L codeman attach`.
+  with `codeman tui`, or plain `tmux -L codeman attach`.
 - **Secrets off the command line.** Environment overrides are injected with socket-scoped
   `tmux setenv` rather than being visible in the spawn command.
 

docs/wiki/FAQ.md

@@ -73,8 +73,10 @@ features are Claude-only; [Agent CLIs](Agent-CLIs) lists exactly which.
 
 ### Can I attach to a session from a terminal instead of the browser?
 
-Yes. `sc` is an interactive chooser (`sc 2` attaches directly, `sc -l` lists), or use tmux
-directly on the `codeman` socket. Detach with `Ctrl+A D`.
+Yes. `codeman tui` is a full-screen dashboard of your sessions, with the same
+NEEDS YOU / WORKING / IDLE grouping the web UI uses. `codeman tui --list` prints the
+numbered list and exits, and `codeman tui 2` attaches straight to session 2. `Enter`
+attaches, `F1` comes back. You can also use tmux directly on the `codeman` socket.
 
 ## Running unattended
 

docs/wiki/Remote-Access.md

@@ -179,16 +179,19 @@ the same IP, which matters because all tunnel traffic arrives from one loopback
 
 ## Terminal alternatives
 
-You do not have to use a browser. `sc` is a thumb-friendly session chooser for SSH clients
-like Termius or Blink:
+You do not have to use a browser. `codeman tui` is a full-screen session dashboard that
+works well in SSH clients like Termius or Blink:
 
 ```bash
-sc          # interactive chooser
-sc 2        # attach to session 2
-sc -l       # list
+codeman tui           # the dashboard
+codeman tui 2         # attach straight to session 2
+codeman tui --list    # numbered list, then exit
 ```
 
-Detach with `Ctrl+A D`. The sessions are the same ones the dashboard shows.
+`Enter` attaches into the pane and `F1` comes back. Under 72 columns it drops the preview
+and becomes a single-column list, so it stays usable on a phone. The sessions are the same
+ones the dashboard shows. See [docs/tui.md](https://github.com/Ark0N/Codeman/blob/master/docs/tui.md)
+for the full guide.
 
 ## Common problems
 

docs/wiki/Settings-Reference.md

@@ -45,6 +45,7 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
 | CJK Input                     | Off                  | IME composition through a dedicated text field.                        |
 | Extended Keyboard Bar         | Per device           | Which accessory bar phones get. Shell sessions override it while they are active. |
 | Wheel Scrolls Local History   | Off                  | Keeps the wheel on the local buffer instead of forwarding it to the CLI. |
+| Auto Copy Selection           | Off                  | Copies highlighted terminal text to the clipboard the moment you finish selecting it. Ctrl+C still copies on demand. |
 | WebGL Renderer                | On                   | With a GPU-stall watchdog that falls back to DOM rendering.            |
 | Gesture Control               | Off                  | Camera hand tracking. Also needs `CODEMAN_GESTURE=1` on the server.    |
 

docs/wiki/The-Dashboard.md

@@ -133,8 +133,10 @@ TUIs render correctly.
 
 Worth knowing:
 
-- **Scrollback.** The first time you open a session, Codeman pulls the entire tmux
-  scrollback, not just the recent tail. Scrolling to the very top pulls again on demand.
+- **Scrollback.** Agent/TUI sessions pull their entire tmux scrollback on first open.
+  Shell sessions open from a bounded recent tail so a large transcript cannot stall tab
+  switching; press **Load full history** to pull the rest explicitly. Ordinary Shell scrolling
+  stays within the bounded browser buffer so dragging upward remains responsive.
 - **Wheel and touch scrolling** are forwarded into Claude's own transcript on recent Claude
   versions, so the wheel scrolls the conversation rather than the terminal. `Shift+Wheel` is
   always local scrollback. Other CLIs scroll locally.

install.sh

@@ -1072,21 +1072,28 @@ add_to_path() {
     success "Added to $profile"
 }
 
-setup_sc_alias() {
+# The `sc` bash chooser was retired in favour of `codeman tui`, which reaches
+# sessions 10+, carries the server's real states and leaves an attach with one
+# key. Older installers wrote this alias, so take it back out.
+#
+# Marker-owned on purpose: it matches the exact line WE wrote, so a user's own
+# `alias sc=` for something entirely different is never touched. The rewrite
+# goes through `cat >` rather than `mv` so the profile keeps its own mode and
+# ownership.
+remove_sc_alias() {
     local profile
     profile=$(detect_shell_profile)
+    [[ -f "$profile" ]] || return 0
+    grep -qE "^alias sc='tmux-chooser'\$" "$profile" 2>/dev/null || return 0
 
-    # Check if alias already exists
-    if [[ -f "$profile" ]] && grep -qE "^alias sc=" "$profile" 2>/dev/null; then
-        info "Alias 'sc' already configured in $profile"
-        return 0
+    local tmp
+    tmp=$(mktemp 2>/dev/null) || return 0
+    if sed -e "/^alias sc='tmux-chooser'\$/d" \
+           -e '/^# Codeman tmux session shortcut$/d' "$profile" > "$tmp" 2>/dev/null; then
+        cat "$tmp" > "$profile"
+        info "Removed the retired 'sc' alias from $profile (use: codeman tui)"
     fi
-
-    echo "" >> "$profile"
-    echo "# Codeman tmux session shortcut" >> "$profile"
-    echo "alias sc='tmux-chooser'" >> "$profile"
-
-    info "Added 'sc' alias for tmux-chooser"
+    rm -f "$tmp"
 }
 
 # ============================================================================
@@ -2243,13 +2250,14 @@ main() {
         ln -sf "$INSTALL_DIR/dist/index.js" "$symlink_dir/codeman"
         info "Created symlink: $symlink_dir/codeman"
 
-        # Install tmux-chooser as 'tmux-chooser' command
-        if [[ -f "$INSTALL_DIR/scripts/tmux-chooser.sh" ]]; then
-            ln -sf "$INSTALL_DIR/scripts/tmux-chooser.sh" "$symlink_dir/tmux-chooser"
-            info "Created symlink: $symlink_dir/tmux-chooser"
-            # Add 'sc' alias for quick access
-            setup_sc_alias
+        # tmux-chooser/`sc` is retired; `codeman tui` replaces it. Sweep up what
+        # an older installer left behind, so an update does not leave a symlink
+        # pointing at a script this version no longer ships.
+        if [[ -L "$symlink_dir/tmux-chooser" ]]; then
+            rm -f "$symlink_dir/tmux-chooser"
+            info "Removed the retired tmux-chooser symlink (use: codeman tui)"
         fi
+        remove_sc_alias
 
         # Add ~/.local/bin to PATH if not already there
         if [[ ":$PATH:" != *":$symlink_dir:"* ]]; then
@@ -2450,9 +2458,9 @@ main() {
 
     echo -e "  ${BOLD}Mobile Access (Termius/SSH):${NC}"
     echo ""
-    echo -e "    ${CYAN}sc${NC}              # Interactive tmux session chooser"
-    echo -e "    ${CYAN}sc 2${NC}            # Quick attach to session 2"
-    echo -e "    ${CYAN}sc -h${NC}           # Help"
+    echo -e "    ${CYAN}codeman tui${NC}     # Full-screen session dashboard"
+    echo -e "    ${CYAN}codeman tui 2${NC}   # Attach straight to session 2"
+    echo -e "    ${CYAN}codeman tui -l${NC}  # Numbered list, then exit"
     echo ""
 
     echo -e "  ${BOLD}Documentation:${NC}"
@@ -2620,6 +2628,7 @@ uninstall() {
         rm -f "$symlink_dir/tmux-chooser"
         success "Removed symlink: $symlink_dir/tmux-chooser"
     fi
+    remove_sc_alias
 
     # Remove install directory
     if [[ -d "$INSTALL_DIR" ]]; then

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.19.7",
+  "version": "1.21.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.19.7",
+      "version": "1.21.0",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.19.7",
+  "version": "1.21.0",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",

scripts/tmux-chooser.sh

@@ -1,662 +0,0 @@
-#!/bin/bash
-# ============================================================================
-# Codeman Sessions - Mobile-friendly Tmux Session Chooser
-# Optimized for iPhone/Termius (portrait ~45 chars, landscape ~95 chars)
-# ============================================================================
-#
-# Design principles:
-#   - Single-digit selection (1-9) for fast thumb typing
-#   - Compact display, no wasted space
-#   - Color-coded status for quick scanning
-#   - Names pulled from Codeman state.json
-#   - Minimal keystrokes to attach
-#
-# Usage:
-#   tmux-chooser          # Interactive chooser
-#   tmux-chooser 1        # Quick attach to session 1
-#   tmux-chooser -l       # List only (non-interactive)
-#   tmux-chooser -h       # Help
-#
-# Alias: alias sc='tmux-chooser'
-#   Then: sc      (interactive)
-#         sc 2    (attach session 2)
-#
-# ============================================================================
-
-set -e
-
-# ============================================================================
-# Configuration
-# ============================================================================
-
-CODEMAN_STATE="$HOME/.codeman/state.json"
-CODEMAN_SESSIONS="$HOME/.codeman/mux-sessions.json"
-
-# Dedicated tmux socket all Codeman sessions live on. MUST match
-# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
-# otherwise list-sessions would enumerate the user's default tmux server
-# (missing the real Codeman sessions, surfacing unrelated ones).
-CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
-TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
-
-
-# iPhone 17 Pro portrait width (conservative)
-MAX_WIDTH=44
-MAX_NAME_LEN=28
-
-# Page size for pagination (leave room for header/footer)
-PAGE_SIZE=7
-
-# Auto-refresh timeout (seconds) - 0 to disable
-AUTO_REFRESH=60
-
-# ============================================================================
-# Icon Detection (Nerd Fonts vs ASCII)
-# ============================================================================
-
-detect_icons() {
-    if [[ "$TERM_PROGRAM" == "iTerm"* ]] || \
-       [[ "$TERM" == "xterm-kitty" ]] || \
-       [[ -n "$WEZTERM_PANE" ]] || \
-       [[ "$LC_TERMINAL" == "iTerm2" ]]; then
-        ICON_SESSION="󰆍"
-        ICON_ATTACHED="●"
-        ICON_DETACHED="○"
-        ICON_UNKNOWN="◌"
-    else
-        ICON_SESSION="[T]"
-        ICON_ATTACHED="*"
-        ICON_DETACHED="-"
-        ICON_UNKNOWN="?"
-    fi
-}
-
-detect_icons
-
-# ============================================================================
-# Colors - ANSI 256 for better Termius compatibility
-# ============================================================================
-
-R='\033[0m'        # Reset
-B='\033[1m'        # Bold
-D='\033[2m'        # Dim
-GREEN='\033[38;5;82m'
-YELLOW='\033[38;5;220m'
-BLUE='\033[38;5;75m'
-CYAN='\033[38;5;87m'
-RED='\033[38;5;203m'
-GRAY='\033[38;5;245m'
-WHITE='\033[38;5;255m'
-BG_SEL='\033[48;5;236m'
-
-# ============================================================================
-# Utilities
-# ============================================================================
-
-truncate() {
-    local str="$1"
-    local max="$2"
-    local len=${#str}
-
-    if [ "$len" -le "$max" ]; then
-        echo "$str"
-        return
-    fi
-
-    if [[ "$str" == *"/"* ]]; then
-        echo "..${str: -$((max-2))}"
-    else
-        echo "${str:0:$((max-1))}…"
-    fi
-}
-
-find_full_session_id() {
-    local short_id="$1"
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local full_id
-        full_id=$(jq -r --arg short "$short_id" '
-            .sessions | keys[] | select(startswith($short))
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$full_id" ]; then
-            echo "$full_id"
-            return
-        fi
-    fi
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local full_id
-        full_id=$(jq -r --arg short "$short_id" '
-            .[] | select(.sessionId | startswith($short)) | .sessionId
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$full_id" ]; then
-            echo "$full_id"
-            return
-        fi
-    fi
-
-    echo "$short_id"
-}
-
-get_session_name() {
-    local session_id="$1"
-    local name=""
-    local workdir=""
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local result
-        result=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | "\(.name // "")\t\(.workingDir // "")"
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$result" ]; then
-            name="${result%%	*}"
-            workdir="${result#*	}"
-        fi
-    fi
-
-    if [ -z "$name" ] && [ -f "$CODEMAN_STATE" ]; then
-        local result
-        result=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) | "\(.value.name // "")\t\(.value.workingDir // "")"
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$result" ]; then
-            name="${result%%	*}"
-            [ -z "$workdir" ] && workdir="${result#*	}"
-        fi
-    fi
-
-    if [ -n "$name" ]; then
-        echo "$name"
-        return
-    fi
-
-    if [ -n "$workdir" ]; then
-        echo "${workdir##*/}"
-        return
-    fi
-
-    echo "${session_id:0:8}"
-}
-
-get_working_dir() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local dir
-        dir=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | .workingDir // empty
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$dir" ] && [ "$dir" != "null" ]; then
-            echo "${dir/#$HOME/~}"
-            return
-        fi
-    fi
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local dir
-        dir=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) | .value.workingDir // empty
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$dir" ] && [ "$dir" != "null" ]; then
-            echo "${dir/#$HOME/~}"
-            return
-        fi
-    fi
-    echo ""
-}
-
-get_tokens() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local tokens
-        tokens=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) |
-            ((.value.inputTokens // 0) + (.value.outputTokens // 0))
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-
-        if [ -n "$tokens" ] && [ "$tokens" != "null" ] && [ "$tokens" -gt 0 ] 2>/dev/null; then
-            if [ "$tokens" -gt 1000 ]; then
-                echo "$((tokens / 1000))k"
-            else
-                echo "${tokens}"
-            fi
-            return
-        fi
-    fi
-    echo ""
-}
-
-get_respawn_status() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local respawn_enabled
-        respawn_enabled=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | .respawnConfig.enabled // false
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-
-        if [ "$respawn_enabled" = "true" ]; then
-            echo "R"
-            return
-        fi
-    fi
-    echo ""
-}
-
-check_deps() {
-    if ! command -v jq &>/dev/null; then
-        echo -e "${YELLOW}Note: Install jq for session names${R}"
-        echo ""
-    fi
-}
-
-# ============================================================================
-# Tmux Session Parser
-# ============================================================================
-
-declare -a SESSION_PIDS
-declare -a MUX_NAMES
-declare -a SESSION_STATES
-declare -a SESSION_IDS
-declare -a DISPLAY_NAMES
-declare -a WORKING_DIRS
-declare -a TOKEN_COUNTS
-declare -a RESPAWN_STATUS
-
-parse_sessions() {
-    SESSION_PIDS=()
-    MUX_NAMES=()
-    SESSION_STATES=()
-    SESSION_IDS=()
-    DISPLAY_NAMES=()
-    WORKING_DIRS=()
-    TOKEN_COUNTS=()
-    RESPAWN_STATUS=()
-
-    local i=0
-
-    # Parse tmux list-sessions output
-    while IFS= read -r line; do
-        local session_name="${line%%:*}"
-
-        # Only show codeman sessions
-        if [[ "$session_name" != codeman-* ]]; then
-            continue
-        fi
-
-        # Check if attached
-        local state="Detached"
-        if [[ "$line" == *"(attached)"* ]]; then
-            state="Attached"
-        fi
-
-        # Get PID from tmux
-        local pid
-        pid=$("${TMUX_CMD[@]}" display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")
-
-        SESSION_PIDS+=("$pid")
-        MUX_NAMES+=("$session_name")
-        SESSION_STATES+=("$state")
-
-        # Extract session ID from codeman session name
-        local session_id=""
-        local cm_regex='^codeman-(.+)$'
-        if [[ "$session_name" =~ $cm_regex ]]; then
-            session_id="${BASH_REMATCH[1]}"
-        fi
-        SESSION_IDS+=("$session_id")
-
-        # Get display name and metadata
-        if [ -n "$session_id" ]; then
-            DISPLAY_NAMES+=("$(get_session_name "$session_id")")
-            WORKING_DIRS+=("$(get_working_dir "$session_id")")
-            TOKEN_COUNTS+=("$(get_tokens "$session_id")")
-            RESPAWN_STATUS+=("$(get_respawn_status "$session_id")")
-        else
-            DISPLAY_NAMES+=("$session_name")
-            WORKING_DIRS+=("")
-            TOKEN_COUNTS+=("")
-            RESPAWN_STATUS+=("")
-        fi
-
-        i=$((i + 1))
-    done < <("${TMUX_CMD[@]}" list-sessions 2>/dev/null || true)
-}
-
-# ============================================================================
-# Display Functions
-# ============================================================================
-
-clear_screen() {
-    printf '\033[2J\033[H'
-}
-
-print_header() {
-    local count=${#SESSION_PIDS[@]}
-    echo -e "${B}${CYAN}Codeman Sessions${R} ${D}($count)${R}"
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-}
-
-print_entry() {
-    local idx="$1"
-    local num=$((idx + 1))
-    local name="${DISPLAY_NAMES[$idx]}"
-    local state="${SESSION_STATES[$idx]}"
-    local dir="${WORKING_DIRS[$idx]}"
-    local tokens="${TOKEN_COUNTS[$idx]}"
-    local respawn="${RESPAWN_STATUS[$idx]}"
-
-    local name_max=$MAX_NAME_LEN
-    [ -n "$respawn" ] && name_max=$((name_max - 2))
-    [ -n "$tokens" ] && name_max=$((name_max - 4))
-    name=$(truncate "$name" $name_max)
-
-    local status_icon status_color
-    if [[ "$state" == *"Attached"* ]]; then
-        status_icon="$ICON_ATTACHED"
-        status_color="$GREEN"
-    elif [[ "$state" == *"Detached"* ]]; then
-        status_icon="$ICON_DETACHED"
-        status_color="$GRAY"
-    else
-        status_icon="$ICON_UNKNOWN"
-        status_color="$YELLOW"
-    fi
-
-    local num_str="${B}${WHITE}${num})${R}"
-    local name_str="${B}${WHITE}${name}${R}"
-    local status_str="${status_color}${status_icon}${R}"
-
-    local respawn_str=""
-    if [ -n "$respawn" ]; then
-        respawn_str=" ${GREEN}${respawn}${R}"
-    fi
-
-    local token_str=""
-    if [ -n "$tokens" ]; then
-        token_str=" ${D}${tokens}${R}"
-    fi
-
-    echo -e " ${num_str} ${name_str} ${status_str}${respawn_str}${token_str}"
-
-    if [ -n "$dir" ]; then
-        dir=$(truncate "$dir" $((MAX_NAME_LEN - 2)))
-        echo -e "    ${D}${dir}${R}"
-    fi
-}
-
-print_footer() {
-    local page="$1"
-    local total_pages="$2"
-
-    echo ""
-    echo -e "${D}────────────────────────────────${R}"
-
-    if [ "$total_pages" -gt 1 ]; then
-        echo -e " ${D}Page $((page+1))/$total_pages${R}  ${GRAY}[${WHITE}n${GRAY}]ext [${WHITE}p${GRAY}]rev${R}"
-    fi
-
-    echo -e " ${GRAY}[${WHITE}1-9${GRAY}]attach [${WHITE}r${GRAY}]efresh [${WHITE}q${GRAY}]uit${R}"
-}
-
-print_no_sessions() {
-    clear_screen
-    echo -e "${B}${CYAN}Codeman Sessions${R}"
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-    echo ""
-    echo -e "  ${YELLOW}No tmux sessions found${R}"
-    echo ""
-    echo -e "  ${D}Start one with:${R}"
-    echo -e "  ${WHITE}codeman web${R}"
-    echo ""
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-    echo -e " ${GRAY}[${WHITE}r${GRAY}]efresh [${WHITE}q${GRAY}]uit${R}"
-}
-
-# ============================================================================
-# Main Display Loop
-# ============================================================================
-
-current_page=0
-
-render() {
-    clear_screen
-    parse_sessions
-
-    local count=${#SESSION_PIDS[@]}
-
-    if [ "$count" -eq 0 ]; then
-        print_no_sessions
-        return
-    fi
-
-    local total_pages=$(( (count + PAGE_SIZE - 1) / PAGE_SIZE ))
-
-    if [ "$current_page" -ge "$total_pages" ]; then
-        current_page=$((total_pages - 1))
-    fi
-    if [ "$current_page" -lt 0 ]; then
-        current_page=0
-    fi
-
-    local start=$((current_page * PAGE_SIZE))
-    local end=$((start + PAGE_SIZE))
-    if [ "$end" -gt "$count" ]; then
-        end=$count
-    fi
-
-    print_header
-    echo ""
-
-    for ((i = start; i < end; i++)); do
-        print_entry $i
-    done
-
-    print_footer $current_page $total_pages
-}
-
-attach_session() {
-    local idx="$1"
-    local mux_name="${MUX_NAMES[$idx]}"
-
-    if [ -z "$mux_name" ]; then
-        return 1
-    fi
-
-    clear_screen
-    echo -e "${GREEN}Attaching to ${B}${DISPLAY_NAMES[$idx]}${R}${GREEN}...${R}"
-    echo -e "${D}(Ctrl+B D to detach)${R}"
-    sleep 0.3
-
-    "${TMUX_CMD[@]}" attach-session -t "$mux_name"
-
-    return 0
-}
-
-# ============================================================================
-# Input Handler
-# ============================================================================
-
-handle_input() {
-    local key="$1"
-    local count=${#SESSION_PIDS[@]}
-    local total_pages=$(( (count + PAGE_SIZE - 1) / PAGE_SIZE ))
-
-    case "$key" in
-        [1-9])
-            local idx=$((key - 1))
-            if [ "$idx" -lt "$count" ]; then
-                attach_session "$idx"
-                return 0
-            fi
-            ;;
-
-        $'\e')
-            read -rsn2 -t 0.1 seq 2>/dev/null || true
-            case "$seq" in
-                '[A'|'[D')
-                    if [ "$total_pages" -gt 1 ]; then
-                        current_page=$(( (current_page - 1 + total_pages) % total_pages ))
-                    fi
-                    ;;
-                '[B'|'[C')
-                    if [ "$total_pages" -gt 1 ]; then
-                        current_page=$(( (current_page + 1) % total_pages ))
-                    fi
-                    ;;
-            esac
-            ;;
-
-        n|N|j|J)
-            if [ "$total_pages" -gt 1 ]; then
-                current_page=$(( (current_page + 1) % total_pages ))
-            fi
-            ;;
-
-        p|P|k|K)
-            if [ "$total_pages" -gt 1 ]; then
-                current_page=$(( (current_page - 1 + total_pages) % total_pages ))
-            fi
-            ;;
-
-        r|R)
-            ;;
-
-        q|Q)
-            clear_screen
-            exit 0
-            ;;
-
-        '')
-            if [ "$count" -eq 1 ]; then
-                attach_session 0
-                return 0
-            fi
-            ;;
-    esac
-
-    return 0
-}
-
-# ============================================================================
-# List Mode
-# ============================================================================
-
-list_mode() {
-    parse_sessions
-    local count=${#SESSION_PIDS[@]}
-
-    if [ "$count" -eq 0 ]; then
-        echo "No tmux sessions"
-        exit 0
-    fi
-
-    for ((i = 0; i < count; i++)); do
-        local num=$((i + 1))
-        local name="${DISPLAY_NAMES[$i]}"
-        local state="${SESSION_STATES[$i]}"
-        local respawn="${RESPAWN_STATUS[$i]}"
-        local indicator="-"
-        [[ "$state" == *"Attached"* ]] && indicator="*"
-        [ -n "$respawn" ] && indicator="${indicator}R"
-
-        echo "$num) $name [$indicator]"
-    done
-}
-
-# ============================================================================
-# Quick Attach
-# ============================================================================
-
-quick_attach() {
-    local num="$1"
-    parse_sessions
-
-    local count=${#SESSION_PIDS[@]}
-    local idx=$((num - 1))
-
-    if [ "$idx" -lt 0 ] || [ "$idx" -ge "$count" ]; then
-        echo -e "${RED}Invalid session: $num${R}"
-        echo "Available: 1-$count"
-        exit 1
-    fi
-
-    attach_session "$idx"
-}
-
-# ============================================================================
-# Help
-# ============================================================================
-
-show_help() {
-    cat << 'EOF'
-Codeman Sessions - Mobile-friendly Tmux Session Chooser
-
-USAGE:
-  sc              Interactive chooser
-  sc <number>     Quick attach to session N
-  sc -l           List sessions (non-interactive)
-  sc -h           Show this help
-
-INTERACTIVE KEYS:
-  1-9      Attach to session
-  n/j/↓    Next page
-  p/k/↑    Previous page
-  r        Refresh
-  q        Quit
-
-INDICATORS:
-  * / ●    Attached (someone connected)
-  - / ○    Detached (available)
-  R        Respawn enabled
-  45k      Token count
-
-TIPS:
-  - Detach from tmux: Ctrl+B D
-  - Session names from Codeman state
-  - Optimized for Termius/iPhone
-
-EOF
-}
-
-# ============================================================================
-# Main
-# ============================================================================
-
-main() {
-    case "${1:-}" in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        -l|--list)
-            list_mode
-            exit 0
-            ;;
-        [1-9]|[1-9][0-9])
-            quick_attach "$1"
-            exit $?
-            ;;
-    esac
-
-    check_deps
-
-    render
-
-    while true; do
-        local timeout_opt=""
-        if [ "$AUTO_REFRESH" -gt 0 ]; then
-            timeout_opt="-t $AUTO_REFRESH"
-        fi
-
-        if read -rsn1 $timeout_opt key 2>/dev/null; then
-            handle_input "$key"
-        fi
-        render
-    done
-}
-
-trap 'clear_screen; exit 0' INT
-
-main "$@"

src/cli-style.ts

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview One style vocabulary for everything the `codeman` CLI prints:
+ * palette, glyphs, the small block helpers (heading/rule/kv), width-aware table
+ * layout, a stderr spinner and a y/N confirm.
+ *
+ * Color detection is chalk's alone. It already honors NO_COLOR, FORCE_COLOR,
+ * TERM=dumb and TTY-ness, and a second detector here would disagree with it on
+ * some terminal with no way to tell which one was right.
+ *
+ * The layout math is pure and exported separately from anything that touches a
+ * terminal, which is what lets it be unit-tested with no TTY and reused by
+ * `utils/dependency-report.ts` while that file stays color-free.
+ *
+ * @module cli-style
+ */
+
+import chalk, { type ChalkInstance } from 'chalk';
+import { createInterface } from 'node:readline';
+// Direct import, not the `utils` barrel: the barrel pulls in node-pty and every
+// CLI resolver, which a style module has no business loading.
+import { stripAnsi } from './utils/regex-patterns.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Palette and glyphs
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Semantic roles, mirroring the web UI's status language (green fine, yellow waiting, red blocked). */
+export const palette = {
+  ok: chalk.green,
+  warn: chalk.yellow,
+  err: chalk.red,
+  info: chalk.cyan,
+  muted: chalk.gray,
+  emph: chalk.bold,
+  accent: chalk.magenta,
+} as const satisfies Record<string, ChalkInstance>;
+
+/** The glyph vocabulary the CLI already used, in one place. */
+export const GLYPH = {
+  ok: '✓',
+  fail: '✗',
+  warn: '⚠',
+  idle: '○',
+  dot: '●',
+  arrow: '→',
+} as const;
+
+/** Spinner frames (braille, one cell wide in every terminal we support). */
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;
+
+/** What a line is reporting, independent of how it is painted. */
+export type Tone = 'ok' | 'warn' | 'err' | 'idle' | 'info';
+
+const TONE_GLYPH: Record<Tone, string> = {
+  ok: GLYPH.ok,
+  warn: GLYPH.warn,
+  err: GLYPH.fail,
+  idle: GLYPH.idle,
+  info: GLYPH.dot,
+};
+
+const TONE_STYLE: Record<Tone, ChalkInstance> = {
+  ok: palette.ok,
+  warn: palette.warn,
+  err: palette.err,
+  idle: palette.muted,
+  info: palette.info,
+};
+
+/** Glyph for a tone. Pure, so the mapping is testable without a terminal. */
+export function glyphFor(tone: Tone): string {
+  return TONE_GLYPH[tone];
+}
+
+/** Paint text in a tone's color. */
+export function tint(tone: Tone, text: string): string {
+  return TONE_STYLE[tone](text);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Blocks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Section heading. The blank line above it is part of the existing block idiom. */
+export function heading(text: string): string {
+  return `\n${palette.emph(text)}`;
+}
+
+/** Horizontal rule under a title. */
+export function rule(width = 40): string {
+  return palette.muted('─'.repeat(Math.max(0, width)));
+}
+
+/**
+ * Indented `Label: value` line. `pad` aligns the values of a block by padding
+ * the label column (including its colon), for blocks whose labels differ in
+ * length.
+ */
+export function kv(label: string, value: string, pad = 0): string {
+  const key = pad > 0 ? padCell(`${label}:`, pad) : `${label}:`;
+  return `  ${key} ${value}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Width-aware layout (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Printed width of a cell: ANSI sequences take no columns. */
+export function displayWidth(text: string): number {
+  return stripAnsi(text).length;
+}
+
+export type CellAlign = 'left' | 'right';
+
+/** Pad to `width` columns, measuring by display width so colored cells still align. */
+export function padCell(text: string, width: number, align: CellAlign = 'left'): string {
+  const fill = ' '.repeat(Math.max(0, width - displayWidth(text)));
+  return align === 'right' ? `${fill}${text}` : `${text}${fill}`;
+}
+
+/**
+ * Pad AFTER the paint, so the fill stays outside the color run and a trailing
+ * empty column can be trimmed away instead of ending in a reset sequence with
+ * invisible spaces before it.
+ */
+export function padStyled(text: string, width: number, paint: (t: string) => string): string {
+  return `${paint(text)}${' '.repeat(Math.max(0, width - displayWidth(text)))}`;
+}
+
+/** Widest cell per column. Short rows count as empty cells, never as narrower columns. */
+export function columnWidths(rows: readonly (readonly string[])[]): number[] {
+  const widths: number[] = [];
+  for (const row of rows) {
+    for (let i = 0; i < row.length; i++) {
+      widths[i] = Math.max(widths[i] ?? 0, displayWidth(row[i] ?? ''));
+    }
+  }
+  return widths;
+}
+
+export interface TableOptions {
+  /** Per-column alignment; missing entries are left-aligned. */
+  align?: readonly CellAlign[];
+  /** Spaces between columns. */
+  gap?: number;
+  /** Prefix for every row. */
+  indent?: string;
+}
+
+/**
+ * Lay rows out in columns sized to their widest cell. The last cell of a row is
+ * never padded, so no line carries trailing whitespace.
+ */
+export function layoutTable(rows: readonly (readonly string[])[], options: TableOptions = {}): string[] {
+  const { align = [], gap = 1, indent = '' } = options;
+  const widths = columnWidths(rows);
+  const separator = ' '.repeat(Math.max(0, gap));
+  return rows.map((row) => {
+    const cells = row.map((cell, i) => (i === row.length - 1 ? cell : padCell(cell, widths[i], align[i] ?? 'left')));
+    return `${indent}${cells.join(separator)}`;
+  });
+}
+
+/** `layoutTable()` as one printable block. */
+export function table(rows: readonly (readonly string[])[], options: TableOptions = {}): string {
+  return layoutTable(rows, options).join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spinner
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\x1b[K';
+
+/** The slice of a stream a spinner needs; `process.stderr` satisfies it. */
+export interface SpinnerStream {
+  isTTY?: boolean;
+  write(chunk: string): unknown;
+}
+
+export interface Spinner {
+  start(): Spinner;
+  /** Change the text mid-flight. Silent on a non-TTY, which prints once and stops. */
+  setText(text: string): void;
+  /** Clear the line, restore the cursor and optionally print a final line. */
+  stop(finalLine?: string): void;
+}
+
+export interface SpinnerOptions {
+  stream?: SpinnerStream;
+  intervalMs?: number;
+}
+
+/**
+ * In-place progress line on stderr, for the calls that block for tens of seconds
+ * (daemon start, service install). Only a TTY gets the animation: piped output
+ * and journald get the text once, so a log file never fills with `\r` frames.
+ */
+export function spinner(text: string, options: SpinnerOptions = {}): Spinner {
+  const stream = options.stream ?? process.stderr;
+  const intervalMs = options.intervalMs ?? 90;
+  const animated = Boolean(stream.isTTY);
+  let label = text;
+  let frame = 0;
+  let timer: NodeJS.Timeout | null = null;
+  let started = false;
+  let stopped = false;
+
+  const restoreCursor = () => {
+    if (animated) stream.write(SHOW_CURSOR);
+  };
+
+  const render = () => {
+    stream.write(`\r${palette.info(SPINNER_FRAMES[frame % SPINNER_FRAMES.length])} ${label}${CLEAR_LINE}`);
+    frame++;
+  };
+
+  const handle: Spinner = {
+    start() {
+      if (started || stopped) return handle;
+      started = true;
+      if (!animated) {
+        stream.write(`${label}\n`);
+        return handle;
+      }
+      stream.write(HIDE_CURSOR);
+      // A hidden cursor left behind by a Ctrl+C outlives the process, so the
+      // exit hook is not optional.
+      process.once('exit', restoreCursor);
+      render();
+      // Unref'd: a spinner must never be the reason the process stays alive.
+      timer = setInterval(render, intervalMs);
+      timer.unref();
+      return handle;
+    },
+    setText(next: string) {
+      label = next;
+      if (animated && started && !stopped) render();
+    },
+    stop(finalLine?: string) {
+      if (stopped) return;
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (animated && started) {
+        stream.write(`\r${CLEAR_LINE}`);
+        restoreCursor();
+        process.off('exit', restoreCursor);
+      }
+      if (finalLine && animated) stream.write(`${finalLine}\n`);
+    },
+  };
+  return handle;
+}
+
+/** Run `work` with a spinner up, stopping it however `work` ends. */
+export async function withSpinner<T>(text: string, work: () => Promise<T>, options?: SpinnerOptions): Promise<T> {
+  const handle = spinner(text, options).start();
+  try {
+    return await work();
+  } finally {
+    handle.stop();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Confirm
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Is there a human on the other end of both halves of the terminal? */
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+/**
+ * y/N prompt. Answers `false` immediately when stdin is not a TTY (a script
+ * piping into the CLI must never hang on an invisible question), so callers
+ * that support a `--force` flag can branch on `isInteractive()` to keep printing
+ * their "pass --force" hint instead.
+ */
+export async function confirm(question: string): Promise<boolean> {
+  if (!isInteractive()) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise<string>((resolve) => {
+      rl.once('SIGINT', () => resolve(''));
+      rl.question(`${question} ${palette.muted('[y/N]')} `, resolve);
+    });
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+    // readline resumes stdin; a still-flowing stdin keeps the process alive.
+    process.stdin.pause();
+  }
+}

src/cli.ts

@@ -8,7 +8,6 @@
  */
 
 import { Command } from 'commander';
-import chalk from 'chalk';
 import { createRequire } from 'module';
 import http from 'node:http';
 import https from 'node:https';
@@ -26,6 +25,9 @@ import { isSupportedAttachmentExtension } from './attachment-registry.js';
 import { daemonStatus, startDaemon, stopDaemon, type WebLaunchOptions } from './daemon-control.js';
 import { installService, serviceStatus, uninstallService } from './service-installer.js';
 import { isLoopbackBindHost, isUnauthenticatedNetworkAcknowledged } from './web/network-auth-policy.js';
+import { confirm, heading, isInteractive, kv, palette, rule, tint, withSpinner, type Tone } from './cli-style.js';
+import type { ToolResult } from './utils/dependency-checker.js';
+import type { ReportStyle } from './utils/dependency-report.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json') as { version: string };
@@ -107,14 +109,14 @@ program
   .action(async (filePath, options) => {
     const extension = String(filePath).split('.').pop()?.toLowerCase() || '';
     if (!isAbsolute(filePath) || !isSupportedAttachmentExtension(extension)) {
-      console.error(chalk.red('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
+      console.error(palette.err('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
       process.exit(1);
     }
 
     const sessionId = options.session || process.env.CODEMAN_SESSION_ID;
     const apiUrl = options.url || process.env.CODEMAN_API_URL || 'https://127.0.0.1:3000';
     if (sessionId && (await postAttachment(apiUrl, sessionId, filePath))) {
-      console.log(chalk.green('✓ Attachment card requested'));
+      console.log(palette.ok('✓ Attachment card requested'));
       return;
     }
 
@@ -174,7 +176,7 @@ export function resolveSkillTargetPath(options: {
 function resolveSkillTarget(options: { case?: string }): string {
   const resolved = resolveSkillTargetPath(options);
   if (resolved.missingCase !== undefined) {
-    console.error(chalk.red(`✗ Case not found: ${resolved.missingCase}`));
+    console.error(palette.err(`✗ Case not found: ${resolved.missingCase}`));
     process.exit(1);
   }
   return resolved.target;
@@ -199,9 +201,9 @@ function reportSkillResult(result: AgentSkillApplyResult, target: string): void
   };
   const message = messages[result];
   if (message.ok) {
-    console.log(chalk.green(`✓ ${message.text}`));
+    console.log(palette.ok(`✓ ${message.text}`));
   } else {
-    console.error(chalk.red(`✗ ${message.text}`));
+    console.error(palette.err(`✗ ${message.text}`));
     process.exit(1);
   }
 }
@@ -220,7 +222,7 @@ skillCmd
       const target = resolveSkillTarget(options);
       reportSkillResult(await installAgentSkillInto(target), target);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to install agent skill: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to install agent skill: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -235,7 +237,7 @@ skillCmd
       const target = resolveSkillTarget(options);
       reportSkillResult(await removeAgentSkillFrom(target), target);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to remove agent skill: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to remove agent skill: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -252,11 +254,11 @@ sessionCmd
     try {
       const manager = getSessionManager();
       const session = await manager.createSession(options.dir);
-      console.log(chalk.green(`✓ Session started: ${session.id}`));
+      console.log(palette.ok(`✓ Session started: ${session.id}`));
       console.log(`  Working directory: ${session.workingDir}`);
       console.log(`  PID: ${session.pid}`);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to start session: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to start session: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -268,70 +270,81 @@ sessionCmd
     try {
       const manager = getSessionManager();
       await manager.stopSession(id);
-      console.log(chalk.green(`✓ Session stopped: ${id}`));
+      console.log(palette.ok(`✓ Session stopped: ${id}`));
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to stop session: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to stop session: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
 
+/** Session status in the shared vocabulary: idle is fine, busy is working, anything else is a problem. */
+function sessionStatusLabel(status: string): string {
+  if (status === 'idle') return palette.ok('idle');
+  if (status === 'busy') return palette.warn('busy');
+  return palette.err(status);
+}
+
+/**
+ * The one session listing. `codeman list` used to be a copy of this that had
+ * drifted (it lost the stopped and web-server sections), so it now calls the
+ * same renderer and only opts out of those two sections.
+ */
+function printSessionList(options: { includeStored: boolean }): void {
+  const manager = getSessionManager();
+  const sessions = manager.getAllSessions();
+  const stored = manager.getStoredSessions();
+
+  if (sessions.length === 0 && Object.keys(stored).length === 0) {
+    console.log(palette.warn('No sessions found'));
+    return;
+  }
+
+  console.log(heading('Active Sessions:'));
+  if (sessions.length === 0) {
+    console.log('  (none)');
+  } else {
+    for (const session of sessions) {
+      console.log(
+        `  ${palette.info(session.id.slice(0, 8))} ${sessionStatusLabel(session.status)} ${session.workingDir}`
+      );
+    }
+  }
+
+  if (options.includeStored) {
+    const stoppedSessions = Object.values(stored).filter((s) => s.status === 'stopped');
+    if (stoppedSessions.length > 0) {
+      console.log(heading('Stopped Sessions:'));
+      for (const session of stoppedSessions) {
+        const name = session.name ? ` (${session.name})` : '';
+        console.log(
+          `  ${palette.muted(session.id.slice(0, 8))} ${palette.muted('stopped')}${name} ${session.workingDir}`
+        );
+      }
+    }
+
+    // Sessions the web server owns: this process has no PTY for them, so they
+    // only exist in the shared state file.
+    const activeSessions = Object.values(stored).filter((s) => s.status !== 'stopped');
+    if (sessions.length === 0 && activeSessions.length > 0) {
+      console.log(heading('Active Sessions (from web server):'));
+      for (const session of activeSessions) {
+        const name = session.name ? ` (${session.name})` : '';
+        const mode = session.mode === 'shell' ? palette.muted(' [shell]') : '';
+        const cost = session.totalCost ? palette.muted(` $${session.totalCost.toFixed(4)}`) : '';
+        console.log(
+          `  ${palette.info(session.id.slice(0, 8))} ${sessionStatusLabel(session.status)}${name}${mode}${cost} ${session.workingDir}`
+        );
+      }
+    }
+  }
+  console.log('');
+}
+
 sessionCmd
   .command('list')
   .alias('ls')
   .description('List all sessions')
-  .action(() => {
-    const manager = getSessionManager();
-    const sessions = manager.getAllSessions();
-    const stored = manager.getStoredSessions();
-
-    if (sessions.length === 0 && Object.keys(stored).length === 0) {
-      console.log(chalk.yellow('No sessions found'));
-      return;
-    }
-
-    console.log(chalk.bold('\nActive Sessions:'));
-    if (sessions.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const session of sessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status} ${session.workingDir}`);
-      }
-    }
-
-    const stoppedSessions = Object.values(stored).filter((s) => s.status === 'stopped');
-    if (stoppedSessions.length > 0) {
-      console.log(chalk.bold('\nStopped Sessions:'));
-      for (const session of stoppedSessions) {
-        const name = session.name ? ` (${session.name})` : '';
-        console.log(`  ${chalk.gray(session.id.slice(0, 8))} ${chalk.gray('stopped')}${name} ${session.workingDir}`);
-      }
-    }
-
-    // Show active sessions from state (when web server manages them)
-    const activeSessions = Object.values(stored).filter((s) => s.status !== 'stopped');
-    if (sessions.length === 0 && activeSessions.length > 0) {
-      console.log(chalk.bold('\nActive Sessions (from web server):'));
-      for (const session of activeSessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        const name = session.name ? ` (${session.name})` : '';
-        const mode = session.mode === 'shell' ? chalk.gray(' [shell]') : '';
-        const cost = session.totalCost ? chalk.gray(` $${session.totalCost.toFixed(4)}`) : '';
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status}${name}${mode}${cost} ${session.workingDir}`);
-      }
-    }
-    console.log('');
-  });
+  .action(() => printSessionList({ includeStored: true }));
 
 sessionCmd
   .command('logs <id>')
@@ -342,12 +355,12 @@ sessionCmd
     const output = options.errors ? manager.getSessionError(id) : manager.getSessionOutput(id);
 
     if (output === null) {
-      console.log(chalk.yellow(`Session ${id} not found or not active`));
+      console.log(palette.warn(`Session ${id} not found or not active`));
       return;
     }
 
     if (output === '') {
-      console.log(chalk.gray('(no output)'));
+      console.log(palette.muted('(no output)'));
       return;
     }
 
@@ -374,7 +387,7 @@ taskCmd
       completionPhrase: options.completion,
       timeoutMs: options.timeout ? parseInt(options.timeout, 10) : undefined,
     });
-    console.log(chalk.green(`✓ Task added: ${task.id}`));
+    console.log(palette.ok(`✓ Task added: ${task.id}`));
     console.log(`  Prompt: ${prompt.slice(0, 50)}${prompt.length > 50 ? '...' : ''}`);
     console.log(`  Priority: ${task.priority}`);
   });
@@ -393,26 +406,28 @@ taskCmd
     }
 
     if (tasks.length === 0) {
-      console.log(chalk.yellow('No tasks found'));
+      console.log(palette.warn('No tasks found'));
       return;
     }
 
     const statusColors = {
-      pending: chalk.gray,
-      running: chalk.yellow,
-      completed: chalk.green,
-      failed: chalk.red,
+      pending: palette.muted,
+      running: palette.warn,
+      completed: palette.ok,
+      failed: palette.err,
     };
 
-    console.log(chalk.bold('\nTasks:'));
+    console.log(palette.emph('\nTasks:'));
     for (const task of tasks) {
       const color = statusColors[task.status];
       const prompt = task.prompt.slice(0, 40) + (task.prompt.length > 40 ? '...' : '');
-      console.log(`  ${chalk.cyan(task.id.slice(0, 8))} ${color(task.status.padEnd(10))} [${task.priority}] ${prompt}`);
+      console.log(
+        `  ${palette.info(task.id.slice(0, 8))} ${color(task.status.padEnd(10))} [${task.priority}] ${prompt}`
+      );
     }
 
     const counts = queue.getCount();
-    console.log(chalk.bold('\nSummary:'));
+    console.log(palette.emph('\nSummary:'));
     console.log(
       `  Pending: ${counts.pending}, Running: ${counts.running}, Completed: ${counts.completed}, Failed: ${counts.failed}`
     );
@@ -427,11 +442,11 @@ taskCmd
     const task = queue.getTask(id);
 
     if (!task) {
-      console.log(chalk.red(`Task ${id} not found`));
+      console.log(palette.err(`Task ${id} not found`));
       return;
     }
 
-    console.log(chalk.bold('\nTask Details:'));
+    console.log(palette.emph('\nTask Details:'));
     console.log(`  ID: ${task.id}`);
     console.log(`  Status: ${task.status}`);
     console.log(`  Priority: ${task.priority}`);
@@ -441,10 +456,10 @@ taskCmd
       console.log(`  Session: ${task.assignedSessionId}`);
     }
     if (task.error) {
-      console.log(`  Error: ${chalk.red(task.error)}`);
+      console.log(`  Error: ${palette.err(task.error)}`);
     }
     if (task.output) {
-      console.log(chalk.bold('\nOutput:'));
+      console.log(palette.emph('\nOutput:'));
       console.log(task.output.slice(0, 500) + (task.output.length > 500 ? '...' : ''));
     }
     console.log('');
@@ -457,9 +472,9 @@ taskCmd
   .action((id) => {
     const queue = getTaskQueue();
     if (queue.removeTask(id)) {
-      console.log(chalk.green(`✓ Task removed: ${id}`));
+      console.log(palette.ok(`✓ Task removed: ${id}`));
     } else {
-      console.log(chalk.red(`Task ${id} not found`));
+      console.log(palette.err(`Task ${id} not found`));
     }
   });
 
@@ -474,13 +489,13 @@ taskCmd
 
     if (options.all) {
       count = queue.clearAll();
-      console.log(chalk.green(`✓ Cleared ${count} tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} tasks`));
     } else if (options.failed) {
       count = queue.clearFailed();
-      console.log(chalk.green(`✓ Cleared ${count} failed tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} failed tasks`));
     } else {
       count = queue.clearCompleted();
-      console.log(chalk.green(`✓ Cleared ${count} completed tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} completed tasks`));
     }
   });
 
@@ -503,38 +518,38 @@ ralphCmd
     }
 
     if (loop.isRunning()) {
-      console.log(chalk.yellow('Ralph loop is already running'));
+      console.log(palette.warn('Ralph loop is already running'));
       return;
     }
 
     loop.on('taskAssigned', (taskId, sessionId) => {
-      console.log(chalk.cyan(`→ Task ${taskId.slice(0, 8)} assigned to session ${sessionId.slice(0, 8)}`));
+      console.log(palette.info(`→ Task ${taskId.slice(0, 8)} assigned to session ${sessionId.slice(0, 8)}`));
     });
 
     loop.on('taskCompleted', (taskId) => {
-      console.log(chalk.green(`✓ Task ${taskId.slice(0, 8)} completed`));
+      console.log(palette.ok(`✓ Task ${taskId.slice(0, 8)} completed`));
     });
 
     loop.on('taskFailed', (taskId, error) => {
-      console.log(chalk.red(`✗ Task ${taskId.slice(0, 8)} failed: ${error}`));
+      console.log(palette.err(`✗ Task ${taskId.slice(0, 8)} failed: ${error}`));
     });
 
     loop.on('stopped', () => {
-      console.log(chalk.yellow('\nRalph loop stopped'));
+      console.log(palette.warn('\nRalph loop stopped'));
       printStats(loop.getStats());
       process.exit(0);
     });
 
     await loop.start();
-    console.log(chalk.green('✓ Ralph loop started'));
+    console.log(palette.ok('✓ Ralph loop started'));
     if (options.minHours) {
       console.log(`  Minimum duration: ${options.minHours} hours`);
     }
-    console.log(chalk.gray('  Press Ctrl+C to stop\n'));
+    console.log(palette.muted('  Press Ctrl+C to stop\n'));
 
     // Keep process running
     process.on('SIGINT', () => {
-      console.log(chalk.yellow('\nStopping Ralph loop...'));
+      console.log(palette.warn('\nStopping Ralph loop...'));
       loop.stop();
     });
   });
@@ -545,11 +560,11 @@ ralphCmd
   .action(() => {
     const loop = getRalphLoop();
     if (!loop.isRunning()) {
-      console.log(chalk.yellow('Ralph loop is not running'));
+      console.log(palette.warn('Ralph loop is not running'));
       return;
     }
     loop.stop();
-    console.log(chalk.green('✓ Ralph loop stopped'));
+    console.log(palette.ok('✓ Ralph loop stopped'));
   });
 
 ralphCmd
@@ -562,9 +577,10 @@ ralphCmd
   });
 
 function printStats(stats: ReturnType<ReturnType<typeof getRalphLoop>['getStats']>) {
-  const statusColor = stats.status === 'running' ? chalk.green : stats.status === 'paused' ? chalk.yellow : chalk.gray;
+  const statusColor =
+    stats.status === 'running' ? palette.ok : stats.status === 'paused' ? palette.warn : palette.muted;
 
-  console.log(chalk.bold('\nRalph Loop Status:'));
+  console.log(palette.emph('\nRalph Loop Status:'));
   console.log(`  Status: ${statusColor(stats.status)}`);
   console.log(`  Elapsed: ${stats.elapsedHours.toFixed(2)} hours`);
   if (stats.minDurationMs) {
@@ -574,14 +590,14 @@ function printStats(stats: ReturnType<ReturnType<typeof getRalphLoop>['getStats'
     );
   }
 
-  console.log(chalk.bold('\nTasks:'));
+  console.log(palette.emph('\nTasks:'));
   console.log(`  Pending: ${stats.pending}`);
   console.log(`  Running: ${stats.running}`);
   console.log(`  Completed: ${stats.completed} (${stats.tasksCompleted} this session)`);
   console.log(`  Failed: ${stats.failed}`);
   console.log(`  Generated: ${stats.tasksGenerated}`);
 
-  console.log(chalk.bold('\nSessions:'));
+  console.log(palette.emph('\nSessions:'));
   console.log(`  Active: ${stats.activeSessions}`);
   console.log(`  Idle: ${stats.idleSessions}`);
   console.log(`  Busy: ${stats.busySessions}`);
@@ -695,20 +711,20 @@ program
       }
     }
 
-    console.log(chalk.bold('\nCodeman Status'));
-    console.log('─'.repeat(40));
+    console.log(heading('Codeman Status'));
+    console.log(rule(40));
 
-    console.log(chalk.bold('\nWeb Server:'));
+    console.log(heading('Web Server:'));
     if (probe.reachable) {
       const version = probe.version ? ` (v${probe.version})` : '';
-      console.log(`  Status: ${chalk.green('running')}${version} at ${probe.url}`);
+      console.log(kv('Status', `${palette.ok('running')}${version} at ${probe.url}`));
       if (probe.authRequired) {
-        console.log(chalk.gray('  (answers 401: set CODEMAN_PASSWORD/CODEMAN_USERNAME to see session details)'));
+        console.log(palette.muted('  (answers 401: set CODEMAN_PASSWORD/CODEMAN_USERNAME to see session details)'));
       }
     } else {
-      console.log(`  Status: ${chalk.red('not reachable')} at ${candidates.join(' or ')}`);
+      console.log(kv('Status', `${palette.err('not reachable')} at ${candidates.join(' or ')}`));
       console.log(
-        chalk.gray('  (start it with `codeman web`, or check your service: systemctl --user status codeman-web)')
+        palette.muted('  (start it with `codeman web`, or check your service: systemctl --user status codeman-web)')
       );
     }
 
@@ -716,26 +732,26 @@ program
     // as such, so the numbers are never silently a different thing.
     if (probe.sessions) {
       const live = probe.sessions;
-      console.log(chalk.bold('\nSessions (live, from the server):'));
-      console.log(`  Total: ${live.length}`);
-      console.log(`  Idle: ${live.filter((s) => s.status === 'idle').length}`);
-      console.log(`  Busy: ${live.filter((s) => s.status === 'busy').length}`);
+      console.log(heading('Sessions (live, from the server):'));
+      console.log(kv('Total', String(live.length)));
+      console.log(kv('Idle', String(live.filter((s) => s.status === 'idle').length)));
+      console.log(kv('Busy', String(live.filter((s) => s.status === 'busy').length)));
     } else {
       const manager = getSessionManager();
       const storedValues = Object.values(manager.getStoredSessions());
-      console.log(chalk.bold('\nSessions (from saved state):'));
-      console.log(`  Active: ${storedValues.filter((s) => s.status !== 'stopped').length}`);
-      console.log(`  Idle: ${storedValues.filter((s) => s.status === 'idle').length}`);
-      console.log(`  Busy: ${storedValues.filter((s) => s.status === 'busy').length}`);
+      console.log(heading('Sessions (from saved state):'));
+      console.log(kv('Active', String(storedValues.filter((s) => s.status !== 'stopped').length)));
+      console.log(kv('Idle', String(storedValues.filter((s) => s.status === 'idle').length)));
+      console.log(kv('Busy', String(storedValues.filter((s) => s.status === 'busy').length)));
     }
 
     const taskCounts = getTaskQueue().getCount();
-    console.log(chalk.bold('\nTasks:'));
-    console.log(`  Total: ${taskCounts.total}`);
-    console.log(`  Pending: ${taskCounts.pending}`);
-    console.log(`  Running: ${taskCounts.running}`);
-    console.log(`  Completed: ${taskCounts.completed}`);
-    console.log(`  Failed: ${taskCounts.failed}`);
+    console.log(heading('Tasks:'));
+    console.log(kv('Total', String(taskCounts.total)));
+    console.log(kv('Pending', String(taskCounts.pending)));
+    console.log(kv('Running', String(taskCounts.running)));
+    console.log(kv('Completed', String(taskCounts.completed)));
+    console.log(kv('Failed', String(taskCounts.failed)));
     console.log('');
   });
 
@@ -745,9 +761,17 @@ program
   .option('-f, --force', 'Skip confirmation')
   .action(async (options) => {
     if (!options.force) {
-      console.log(chalk.yellow('This will stop all sessions and clear all state.'));
-      console.log(chalk.yellow('Use --force to confirm.'));
-      return;
+      console.log(palette.warn('This will stop all sessions and clear all state.'));
+      // Non-interactive callers keep the old refusal: a script piping into the
+      // CLI must never be able to reset state by hanging on an unseen question.
+      if (!isInteractive()) {
+        console.log(palette.warn('Use --force to confirm.'));
+        return;
+      }
+      if (!(await confirm('Reset all Codeman state?'))) {
+        console.log(palette.muted('○ Cancelled, nothing was changed'));
+        return;
+      }
     }
 
     const manager = getSessionManager();
@@ -756,7 +780,7 @@ program
     await manager.stopAllSessions();
     store.reset();
 
-    console.log(chalk.green('✓ All state reset'));
+    console.log(palette.ok('✓ All state reset'));
   });
 
 // Shorthand commands at root level
@@ -767,38 +791,45 @@ program
   .action(async (options) => {
     const manager = getSessionManager();
     const session = await manager.createSession(options.dir);
-    console.log(chalk.green(`✓ Session started: ${session.id}`));
+    console.log(palette.ok(`✓ Session started: ${session.id}`));
   });
 
 program
   .command('list')
   .alias('ls')
-  .description('List all sessions (shorthand)')
-  .action(() => {
-    const manager = getSessionManager();
-    const sessions = manager.getAllSessions();
-    const stored = manager.getStoredSessions();
+  .description('List active sessions (shorthand; `codeman session list` also shows stopped ones)')
+  .action(() => printSessionList({ includeStored: false }));
 
-    if (sessions.length === 0 && Object.keys(stored).length === 0) {
-      console.log(chalk.yellow('No sessions found'));
+// ============ TUI ============
+
+program
+  .command('tui')
+  .argument('[n]', 'attach straight to the nth session of `codeman tui --list`')
+  .description('Terminal dashboard for your sessions (the web UI remains the primary surface)')
+  .option('-l, --list', 'Print the numbered session list and exit, instead of opening the dashboard')
+  .action(async (position: string | undefined, options: { list?: boolean }) => {
+    // Imported here, not at the top: the dashboard pulls in the whole TUI core,
+    // and every other command would pay for it at startup.
+    const { runTui, runTuiAttach, runTuiList } = await import('./tui/tui-app.js');
+
+    if (options.list) {
+      process.exitCode = await runTuiList();
       return;
     }
-
-    console.log(chalk.bold('\nActive Sessions:'));
-    if (sessions.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const session of sessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status} ${session.workingDir}`);
+    if (position !== undefined) {
+      const n = Number.parseInt(position, 10);
+      if (!Number.isSafeInteger(n) || n < 1) {
+        console.error(palette.err(`"${position}" is not a session number.`));
+        console.error(`Run ${palette.info('codeman tui --list')} to see them.`);
+        process.exitCode = 1;
+        return;
       }
+      process.exitCode = await runTuiAttach(n);
+      return;
     }
-    console.log('');
+    // The dashboard owns the terminal until it quits; exiting explicitly keeps a
+    // stray handle (a socket mid-close) from stranding the user's shell.
+    process.exit(await runTui());
   });
 
 // ============ Web / daemon / service Commands ============
@@ -831,7 +862,7 @@ function toWebLaunchOptions(options: {
 }): WebLaunchOptions {
   const port = parseInt(options.port, 10);
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    console.error(chalk.red(`✗ Invalid port: ${options.port}`));
+    console.error(palette.err(`✗ Invalid port: ${options.port}`));
     process.exit(1);
   }
   return {
@@ -852,11 +883,11 @@ function warnIfUnauthenticatedNetwork(launch: WebLaunchOptions): void {
   if (isLoopbackBindHost(launch.host)) return;
   if (isUnauthenticatedNetworkAcknowledged(launch.allowUnauthenticatedNetwork)) return;
   console.log(
-    chalk.yellow(
+    palette.warn(
       `⚠ Binding ${launch.host} without CODEMAN_PASSWORD: anyone who can reach this port gets terminal control.`
     )
   );
-  console.log(chalk.yellow('  Set CODEMAN_PASSWORD, or bind 127.0.0.1 and front it with tailscale serve.'));
+  console.log(palette.warn('  Set CODEMAN_PASSWORD, or bind 127.0.0.1 and front it with tailscale serve.'));
 }
 
 // Web interface command
@@ -872,17 +903,18 @@ webCmd.action(async (options) => {
   const launch = toWebLaunchOptions(options);
 
   if (options.stop) {
-    const result = await stopDaemon(launch);
+    // stopDaemon waits for the process to actually exit (up to 15s).
+    const result = await withSpinner('Stopping Codeman...', () => stopDaemon(launch));
     if (result.ok && result.reason === 'not-running') {
-      console.log(chalk.gray(`○ ${result.message}`));
+      console.log(palette.muted(`○ ${result.message}`));
       return;
     }
     if (result.ok) {
-      console.log(chalk.green(`✓ ${result.message ?? `Stopped Codeman (pid ${result.pid})`}`));
-      console.log(chalk.gray('  Your agents keep running in tmux.'));
+      console.log(palette.ok(`✓ ${result.message ?? `Stopped Codeman (pid ${result.pid})`}`));
+      console.log(palette.muted('  Your agents keep running in tmux.'));
       return;
     }
-    console.error(chalk.red(`✗ ${result.message ?? 'Could not stop the server'}`));
+    console.error(palette.err(`✗ ${result.message ?? 'Could not stop the server'}`));
     process.exit(1);
   }
 
@@ -890,31 +922,33 @@ webCmd.action(async (options) => {
     const status = await daemonStatus(launch);
     if (status.responding) {
       const version = status.version ? ` (v${status.version})` : '';
-      console.log(chalk.green(`✓ Responding at ${status.url}${version}`));
+      console.log(palette.ok(`✓ Responding at ${status.url}${version}`));
     } else {
-      console.log(chalk.yellow(`○ Nothing answering at ${status.url}`));
+      console.log(palette.warn(`○ Nothing answering at ${status.url}`));
     }
-    console.log(`  Daemon pid:  ${status.running ? chalk.green(String(status.pid)) : chalk.gray('not running')}`);
-    console.log(chalk.gray(`  Pidfile:     ${status.pidFile}`));
-    console.log(chalk.gray(`  Log:         ${status.logPath}`));
+    console.log(kv('Daemon pid', status.running ? palette.ok(String(status.pid)) : palette.muted('not running'), 11));
+    console.log(palette.muted(kv('Pidfile', status.pidFile, 11)));
+    console.log(palette.muted(kv('Log', status.logPath, 11)));
     if (!status.running && status.responding) {
-      console.log(chalk.gray('  (running, but not started with --daemon: probably a service or a foreground run)'));
+      console.log(palette.muted('  (running, but not started with --daemon: probably a service or a foreground run)'));
     }
     return;
   }
 
   if (options.daemon) {
     warnIfUnauthenticatedNetwork(launch);
-    console.log(chalk.cyan('Starting Codeman in the background...'));
-    const result = await startDaemon(launch);
+    // The start polls /api/status for up to 30s; without this the shell just sits there.
+    const result = await withSpinner('Starting Codeman in the background, waiting for it to answer...', () =>
+      startDaemon(launch)
+    );
     if (result.ok) {
-      console.log(chalk.green(`\n✓ Codeman is running at ${result.url} (pid ${result.pid})`));
-      console.log(chalk.gray(`  Logs: ${result.logPath}`));
-      console.log(chalk.gray('  Stop it with: codeman web --stop'));
-      console.log(chalk.gray('  Want it back after a reboot? codeman service install'));
+      console.log(palette.ok(`\n✓ Codeman is running at ${result.url} (pid ${result.pid})`));
+      console.log(palette.muted(`  Logs: ${result.logPath}`));
+      console.log(palette.muted('  Stop it with: codeman web --stop'));
+      console.log(palette.muted('  Want it back after a reboot? codeman service install'));
       return;
     }
-    console.error(chalk.red(`\n✗ ${result.message ?? 'Failed to start'}`));
+    console.error(palette.err(`\n✗ ${result.message ?? 'Failed to start'}`));
     process.exit(1);
   }
 
@@ -924,29 +958,29 @@ webCmd.action(async (options) => {
   const https = launch.https;
   const titleHostname = options.titleHostname;
   const allowUnauthenticatedNetwork = launch.allowUnauthenticatedNetwork ?? false;
-  const protocol = https ? 'https' : 'http';
   const displayHost = host === '0.0.0.0' ? 'localhost' : host;
 
-  console.log(chalk.cyan(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
+  console.log(palette.info(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
 
   try {
+    // The server prints its own "running at" line (it also covers the daemon and
+    // service launch paths), so this one used to be a duplicate of it.
     const server = await startWebServer(port, https, false, host, titleHostname, allowUnauthenticatedNetwork);
-    console.log(chalk.green(`\n✓ Web interface running at ${protocol}://${displayHost}:${port}`));
     if (https) {
-      console.log(chalk.yellow('  Note: Accept the self-signed certificate in your browser on first visit'));
+      console.log(palette.warn('  Note: Accept the self-signed certificate in your browser on first visit'));
     }
-    console.log(chalk.gray('  Press Ctrl+C to stop\n'));
+    console.log(palette.muted('  Press Ctrl+C to stop\n'));
 
     // Graceful shutdown handler — flush state and clean up on SIGTERM/SIGINT
     let shuttingDown = false;
     const shutdown = async (signal: string) => {
       if (shuttingDown) return;
       shuttingDown = true;
-      console.log(chalk.yellow(`\n${signal} received, shutting down gracefully...`));
+      console.log(palette.warn(`\n${signal} received, shutting down gracefully...`));
       try {
         await server.stop();
       } catch (err) {
-        console.error(chalk.red(`Error during shutdown: ${getErrorMessage(err)}`));
+        console.error(palette.err(`Error during shutdown: ${getErrorMessage(err)}`));
       }
       process.exit(0);
     };
@@ -954,7 +988,7 @@ webCmd.action(async (options) => {
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGHUP', () => shutdown('SIGHUP'));
   } catch (err) {
-    console.error(chalk.red(`✗ Failed to start web server: ${getErrorMessage(err)}`));
+    console.error(palette.err(`✗ Failed to start web server: ${getErrorMessage(err)}`));
     process.exit(1);
   }
 });
@@ -970,20 +1004,23 @@ addWebLaunchOptions(
 ).action(async (options) => {
   const launch = toWebLaunchOptions(options);
   warnIfUnauthenticatedNetwork(launch);
-  console.log(chalk.cyan('Installing the Codeman service...'));
 
-  const result = await installService(launch);
-  for (const warning of result.warnings ?? []) console.log(chalk.yellow(`⚠ ${warning}`));
+  // Install polls the new unit's /api/status for up to 30s before it can honestly
+  // report success, so the wait needs a visible heartbeat.
+  const result = await withSpinner('Installing the Codeman service, waiting for it to answer...', () =>
+    installService(launch)
+  );
+  for (const warning of result.warnings ?? []) console.log(palette.warn(`⚠ ${warning}`));
 
   if (!result.ok) {
-    console.error(chalk.red(`✗ ${result.message}`));
+    console.error(palette.err(`✗ ${result.message}`));
     process.exit(1);
   }
-  console.log(chalk.green(`✓ ${result.message}`));
-  console.log(chalk.gray(`  Unit: ${result.unitPath}`));
+  console.log(palette.ok(`✓ ${result.message}`));
+  console.log(palette.muted(`  Unit: ${result.unitPath}`));
   if (process.env.CODEMAN_PASSWORD) {
     console.log(
-      chalk.yellow(
+      palette.warn(
         '  Note: CODEMAN_PASSWORD was NOT copied into the unit file. Add it there yourself if the service needs auth.'
       )
     );
@@ -996,10 +1033,10 @@ serviceCmd
   .action(() => {
     const result = uninstallService();
     if (!result.ok) {
-      console.error(chalk.red(`✗ ${result.message}`));
+      console.error(palette.err(`✗ ${result.message}`));
       process.exit(1);
     }
-    console.log(chalk.green(`✓ ${result.message}`));
+    console.log(palette.ok(`✓ ${result.message}`));
   });
 
 addWebLaunchOptions(
@@ -1007,15 +1044,15 @@ addWebLaunchOptions(
 ).action(async (options) => {
   const status = await serviceStatus(toWebLaunchOptions(options));
   if (!status.kind) {
-    console.log(chalk.yellow(`No supported supervisor on ${process.platform}. Use \`codeman web -d\` instead.`));
+    console.log(palette.warn(`No supported supervisor on ${process.platform}. Use \`codeman web -d\` instead.`));
     return;
   }
   console.log(`  Supervisor: ${status.kind} (${status.name})`);
-  console.log(`  Unit file:  ${status.installed ? chalk.green(status.unitPath) : chalk.gray('not installed')}`);
-  console.log(`  Loaded:     ${status.loaded ? chalk.green('yes') : chalk.gray('no')}`);
+  console.log(`  Unit file:  ${status.installed ? palette.ok(status.unitPath) : palette.muted('not installed')}`);
+  console.log(`  Loaded:     ${status.loaded ? palette.ok('yes') : palette.muted('no')}`);
   const version = status.version ? ` (v${status.version})` : '';
   console.log(
-    `  Responding: ${status.responding ? chalk.green(`yes at ${status.url}${version}`) : chalk.gray(`no at ${status.url}`)}`
+    `  Responding: ${status.responding ? palette.ok(`yes at ${status.url}${version}`) : palette.muted(`no at ${status.url}`)}`
   );
 });
 
@@ -1085,7 +1122,7 @@ usersCmd
   .action(async (name, options) => {
     const { createUser, isValidUsername } = await import('./user-store.js');
     if (!isValidUsername(name)) {
-      console.error(chalk.red('✗ Username must be lowercase, start alphanumeric, 2-32 chars ([a-z0-9_-])'));
+      console.error(palette.err('✗ Username must be lowercase, start alphanumeric, 2-32 chars ([a-z0-9_-])'));
       process.exit(1);
     }
     try {
@@ -1096,18 +1133,18 @@ usersCmd
         password = await promptHiddenPassword('New password: ');
         const confirm = await promptHiddenPassword('Confirm password: ');
         if (password !== confirm) {
-          console.error(chalk.red('✗ Passwords do not match'));
+          console.error(palette.err('✗ Passwords do not match'));
           process.exit(1);
         }
       }
       if (!password || password.length < 8) {
-        console.error(chalk.red('✗ Password must be at least 8 characters'));
+        console.error(palette.err('✗ Password must be at least 8 characters'));
         process.exit(1);
       }
       const user = await createUser({ username: name, role: options.admin ? 'admin' : 'user', password });
-      console.log(chalk.green(`✓ Created ${user.role} "${user.username}"`));
+      console.log(palette.ok(`✓ Created ${user.role} "${user.username}"`));
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -1126,14 +1163,14 @@ usersCmd
         password = await promptHiddenPassword('New password: ');
         const confirm = await promptHiddenPassword('Confirm password: ');
         if (password !== confirm) {
-          console.error(chalk.red('✗ Passwords do not match'));
+          console.error(palette.err('✗ Passwords do not match'));
           process.exit(1);
         }
       }
       await setPassword(name, password, { mustChangePassword: false });
-      console.log(chalk.green(`✓ Password updated for "${name}"`));
+      console.log(palette.ok(`✓ Password updated for "${name}"`));
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -1146,17 +1183,17 @@ usersCmd
     const { readUsers } = await import('./user-store.js');
     const users = await readUsers(true);
     if (users.length === 0) {
-      console.log(chalk.yellow('No users defined (run: codeman users add <name> --admin)'));
+      console.log(palette.warn('No users defined (run: codeman users add <name> --admin)'));
       return;
     }
-    console.log(chalk.bold('\nUsers:'));
+    console.log(palette.emph('\nUsers:'));
     for (const u of users) {
-      const role = u.role === 'admin' ? chalk.magenta('admin') : chalk.cyan('user ');
-      const state = u.disabled ? chalk.red('disabled') : chalk.green('enabled ');
+      const role = u.role === 'admin' ? palette.accent('admin') : palette.info('user ');
+      const state = u.disabled ? palette.err('disabled') : palette.ok('enabled ');
       const flags = [u.mustChangePassword ? 'must-change-pw' : '', u.canBypassPermissions ? 'can-bypass' : '']
         .filter(Boolean)
         .join(' ');
-      console.log(`  ${role} ${state} ${u.username}${flags ? chalk.gray(`  [${flags}]`) : ''}`);
+      console.log(`  ${role} ${state} ${u.username}${flags ? palette.muted(`  [${flags}]`) : ''}`);
     }
     console.log('');
   });
@@ -1171,16 +1208,43 @@ usersCmd
       await deleteUser(name);
       if (options.deleteSpace) {
         await deleteUserSpace(name);
-        console.log(chalk.green(`✓ Deleted user "${name}" and their space`));
+        console.log(palette.ok(`✓ Deleted user "${name}" and their space`));
       } else {
-        console.log(chalk.green(`✓ Deleted user "${name}" (space left on disk)`));
+        console.log(palette.ok(`✓ Deleted user "${name}" (space left on disk)`));
       }
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
 
+/**
+ * Missing REQUIRED tools are failures; a missing optional one or a skipped check
+ * is just absence, so it stays muted rather than shouting red at everyone
+ * without LibreOffice installed.
+ */
+function dependencyTone(result: ToolResult): Tone {
+  if (result.status === 'ok') return 'ok';
+  if (result.status === 'skipped') return 'idle';
+  return result.required ? 'err' : 'idle';
+}
+
+/**
+ * The colorize hook `dependency-report.ts` was written for. Versions stay in the
+ * default color (they are data, not a verdict); everything that IS a verdict is
+ * painted, and the supporting detail is muted so the glyph column reads first.
+ */
+const DOCTOR_STYLE: ReportStyle = {
+  title: (text) => palette.emph(text),
+  heading: (text) => palette.emph(palette.info(text)),
+  glyph: (result, glyph) => tint(dependencyTone(result), glyph),
+  label: (text) => text,
+  status: (result, text) => (result.status === 'ok' ? text : tint(dependencyTone(result), text)),
+  path: (text) => palette.muted(text),
+  meta: (text) => palette.muted(text),
+  summary: (text) => palette.emph(text),
+};
+
 program
   .command('doctor')
   .alias('check-deps')
@@ -1204,9 +1268,10 @@ program
     const results = checkAll(registry, host);
 
     if (options.json) {
+      // Raw JSON, never styled: this output is parsed, not read.
       console.log(JSON.stringify(renderJson(results, host.environment), null, 2));
     } else {
-      console.log(renderTable(results, host.environment));
+      console.log(renderTable(results, host.environment, DOCTOR_STYLE));
     }
     process.exit(computeExitCode(results));
   });

src/config/instance.ts

@@ -40,6 +40,21 @@ const INSTANCE_SUFFIX = CODEMAN_INSTANCE ? `-${CODEMAN_INSTANCE}` : '';
 /** Default tmux socket for this instance. `CODEMAN_TMUX_SOCKET` still overrides. */
 export const DEFAULT_TMUX_SOCKET = `codeman${INSTANCE_SUFFIX}`;
 
+/** Characters tmux accepts in a `-L` socket name. */
+export const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+
+/**
+ * This instance's tmux socket: the `CODEMAN_TMUX_SOCKET` override when it is a
+ * safe name, else the instance default. Every process that runs `tmux -L` has
+ * to resolve it through here (the server via TmuxManager, the TUI for its
+ * degraded-mode listing), or a beta instance ends up driving prod's sessions.
+ */
+export function resolveTmuxSocketName(): string {
+  const raw = process.env.CODEMAN_TMUX_SOCKET;
+  if (raw !== undefined && SAFE_TMUX_SOCKET_PATTERN.test(raw)) return raw;
+  return DEFAULT_TMUX_SOCKET;
+}
+
 let _ensured = false;
 
 /**

src/config/terminal-history.ts

@@ -8,7 +8,8 @@
  * src/web/public/constants.js and deliberately stays at 50k — 100k xterm lines per tab
  * is a mobile-memory hazard — so DEFAULT_TERMINAL_SCROLLBACK_LINES stays 50,000 to match.
  * The terminalScrollbackLines/terminalBufferMaxBytes/terminalBufferTrimBytes settings keys
- * remain schema-validated but inert (a follow-up wires them); only tmuxHistoryLimit is live.
+ * remain schema-validated but inert (a follow-up wires them); only tmuxHistoryLimit is wired.
+ * tmux <3.7 applies it to new panes; tmux 3.7+ can also resize live panes.
  * All values remain env- and settings-overridable and bounds-clamped via
  * resolveTerminalHistoryConfig().
  */

src/git-clone.ts

@@ -479,14 +479,23 @@ export function gitNonInteractiveEnv(base: NodeJS.ProcessEnv = process.env): Nod
 
 // ─── Pure: output handling ───────────────────────────────────────────────────
 
+/**
+ * Redact any `scheme://user:secret@host` credential pair embedded in text — a
+ * remote URL stored with an inline token, or git stderr echoing such a URL
+ * back. Shared by the clone error path (`sanitizeGitOutput`) and the
+ * repository-status card fields (`web/repo-status.ts`).
+ */
+export function redactGitCredentials(text: string): string {
+  return text.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@\s]*:[^/@\s]*@/g, '$1***:***@');
+}
+
 /**
  * Make git's stderr safe to show in the browser: strip ANSI/control bytes,
  * redact any `scheme://user:secret@host` that a credential helper echoed back,
  * and keep only the tail (the last lines are the ones that say why it failed).
  */
 export function sanitizeGitOutput(text: string, maxBytes = MAX_STDERR_BYTES): string {
-  const redacted = text
-    .replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@\s]*:[^/@\s]*@/g, '$1***:***@')
+  const redacted = redactGitCredentials(text)
     // eslint-disable-next-line no-control-regex -- deliberate: strip C0/C1 and DEL.
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '')
     .trim();

src/mux-interface.ts

@@ -84,7 +84,7 @@ export interface CreateSessionOptions {
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level, injected as a `--settings` soft default (overridable via /effort in-session) */
   effort?: EffortLevel;
-  /** tmux history-limit (scrollback lines) to set for this session. */
+  /** tmux history-limit (scrollback lines) allocated when this session is created. */
   historyLimit?: number;
   /** Remote execution metadata for local tmux sessions wrapping SSH */
   remote?: SessionRemote;
@@ -116,7 +116,7 @@ export interface RespawnPaneOptions {
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level (preserved across respawns, injected via `--settings`) */
   effort?: EffortLevel;
-  /** tmux history-limit (scrollback lines) to set for this session after respawn. */
+  /** Original tmux history-limit retained for config parity; respawn cannot resize the existing pane. */
   historyLimit?: number;
   /** Remote execution metadata for local tmux sessions wrapping SSH */
   remote?: SessionRemote;
@@ -216,7 +216,7 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Update Ralph enabled state for a session */
   updateRalphEnabled(sessionId: string, enabled: boolean): void;
 
-  /** Apply a tmux history-limit to all tracked sessions. */
+  /** Apply history-limit to live panes where tmux supports it, otherwise to future panes. */
   setHistoryLimit(limit: number): Promise<void>;
 
   // ========== Discovery ==========

src/ralph-loop.ts

@@ -281,7 +281,14 @@ export class RalphLoop extends EventEmitter {
         // Guard: only reschedule if still running AND no timer is pending
         // (prevents race where stop() clears timer between our check and setTimeout)
         if (this._status === 'running' && this.loopTimer === null) {
-          this.loopTimer = setTimeout(() => this.runLoop(), this.pollIntervalMs);
+          // Null the handle when the timer fires, BEFORE re-entering runLoop —
+          // otherwise the `loopTimer === null` guard above stays false on the
+          // next pass and the loop stops rescheduling after 2 ticks.
+          // Mirrors the orchestrator-loop reschedule pattern.
+          this.loopTimer = setTimeout(() => {
+            this.loopTimer = null;
+            this.runLoop();
+          }, this.pollIntervalMs);
         }
       });
   }

src/session.ts

@@ -415,6 +415,15 @@ export class Session extends EventEmitter {
   // sequences split across PTY chunks can't slip past the alt-screen/scrollback
   // strip (see _handleTerminalOutput / isAltScreenStripMode)
   private _altScreenSeqCarry: string = '';
+
+  /**
+   * Mouse-tracking DECSET modes the CLI currently has ON, as observed while
+   * STRIPPING them out of the stream below. Kept as a set rather than a boolean
+   * because a TUI may enable 1002 and later disable 1000 (a mode it never
+   * enabled); tracking is on while any of them is.
+   */
+  private _cliMouseModes = new Set<number>();
+  private _cliMouseTracking = false;
   private resolvePromise: ((value: { result: string; cost: number }) => void) | null = null;
   private rejectPromise: ((reason: Error) => void) | null = null;
   private _promptResolved: boolean = false; // Guard against race conditions in runPrompt
@@ -510,7 +519,7 @@ export class Session extends EventEmitter {
   // the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session.
   private _effort: EffortLevel | undefined;
 
-  // tmux history-limit (scrollback lines) applied to this session's pane.
+  // tmux history-limit (scrollback lines) allocated when this session's pane is created.
   private readonly _tmuxHistoryLimit: number;
 
   // Remote execution metadata, present when this session runs over SSH through local tmux.
@@ -600,7 +609,7 @@ export class Session extends EventEmitter {
       envOverrides?: Record<string, string>;
       /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
       effort?: EffortLevel;
-      /** tmux history-limit (scrollback lines) for this session's pane. */
+      /** tmux history-limit (scrollback lines) allocated when this session's pane is created. */
       tmuxHistoryLimit?: number;
       /** Restored per-session attachment history. May include server-private external paths. */
       attachmentHistory?: SessionAttachmentHistoryItem[];
@@ -1285,6 +1294,7 @@ export class Session extends EventEmitter {
       niceValue: this._niceConfig.niceValue,
       color: this._color,
       flickerFilterEnabled: this._flickerFilterEnabled,
+      cliMouseTracking: this._cliMouseTracking || undefined,
       cliVersion: this._cliVersion || undefined,
       cliModel: this._cliModel || undefined,
       cliAccountType: this._cliAccountType || undefined,
@@ -1546,6 +1556,46 @@ export class Session extends EventEmitter {
     };
   }
 
+  /**
+   * Remember whether the CLI currently wants to be told about mouse clicks.
+   *
+   * The strip in {@link _handleTerminalOutput} is the ONLY place these sequences
+   * exist. After it, neither the browser nor xterm can ever learn that the CLI
+   * asked for mouse tracking, so `terminal.modes.mouseTrackingMode` is
+   * permanently 'none' for a stripped mode. The browser hand-encodes SGR reports
+   * to compensate (`_sendSyntheticSgrTap` in terminal-ui.js), and with no state
+   * to consult it had to do that on EVERY click, delivering mouse reports to a
+   * CLI that never asked for them. Publishing this through `toState()` is what
+   * lets the browser report a click only when the CLI is listening.
+   *
+   * Only the TRACKING modes count. 1005/1006 select an encoding and 1007 is
+   * alt-scroll; a CLI that picks SGR encoding without turning a tracking mode on
+   * is not asking about clicks, and counting those would put the stray reports
+   * straight back.
+   *
+   * This must stay in lockstep with the strip regex that calls it: a sequence
+   * removed from the stream but not recorded here is one the browser can neither
+   * see nor be told about.
+   */
+  private _recordStrippedMouseMode(seq: string): void {
+    // eslint-disable-next-line no-control-regex
+    const match = /\x1b\[\?(\d+)([hl])$/.exec(seq);
+    if (!match) return;
+    const mode = Number(match[1]);
+    if (mode !== 1000 && mode !== 1001 && mode !== 1002 && mode !== 1003) return;
+    if (match[2] === 'h') this._cliMouseModes.add(mode);
+    else this._cliMouseModes.delete(mode);
+    this._syncCliMouseTracking();
+  }
+
+  /** Emit only on a real transition: a TUI re-emitting its enable on every repaint costs nothing. */
+  private _syncCliMouseTracking(): void {
+    const active = this._cliMouseModes.size > 0;
+    if (active === this._cliMouseTracking) return;
+    this._cliMouseTracking = active;
+    this.emit('mouseTrackingChanged', active);
+  }
+
   private _handleTerminalOutput(data: string): void {
     // Codex AND Claude Code emit sequences that wipe xterm.js scrollback, plus
     // mouse-tracking enables that hijack the scroll wheel so the user can't reach
@@ -1598,7 +1648,10 @@ export class Session extends EventEmitter {
           // eslint-disable-next-line no-control-regex
           .replace(/\x1b\[3J/g, '')
           // eslint-disable-next-line no-control-regex
-          .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, '');
+          .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, (seq) => {
+            this._recordStrippedMouseMode(seq);
+            return '';
+          });
       }
     }
 
@@ -2525,6 +2578,11 @@ export class Session extends EventEmitter {
     this._messages = [];
     this._lineBuffer = '';
     this._altScreenSeqCarry = '';
+    // A restarted pane starts with no mouse mode: the new program has not asked
+    // for one yet, and carrying the old CLI's state over would report clicks
+    // into a program that never enabled tracking.
+    this._cliMouseModes.clear();
+    this._syncCliMouseTracking();
     this._markActivity(true);
   }
 

src/tmux-manager.ts

@@ -31,7 +31,13 @@ import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { writeFile, rename } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { dataPath, DEFAULT_TMUX_SOCKET, CODEMAN_INSTANCE } from './config/instance.js';
+import {
+  dataPath,
+  DEFAULT_TMUX_SOCKET,
+  CODEMAN_INSTANCE,
+  SAFE_TMUX_SOCKET_PATTERN,
+  resolveTmuxSocketName,
+} from './config/instance.js';
 import {
   ProcessStats,
   PersistedRespawnConfig,
@@ -75,11 +81,17 @@ import {
   SAFE_PATH_PATTERN,
   findClaudeDir,
   getClaudeCliVersion,
+  getClaudeNotFoundMessage,
   resolveOpenCodeDir,
+  getOpenCodeNotFoundMessage,
   resolveCodexDir,
+  getCodexNotFoundMessage,
   resolveGeminiDir,
+  getGeminiNotFoundMessage,
   resolveAntigravityDir,
+  getAntigravityNotFoundMessage,
   resolvePiDir,
+  getPiNotFoundMessage,
   resolveLocalShell,
   loginShellArgs,
 } from './utils/index.js';
@@ -194,9 +206,6 @@ const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;
  *  `codeman` for prod, `codeman-beta` on the beta branch). */
 const DEFAULT_CODEMAN_TMUX_SOCKET = DEFAULT_TMUX_SOCKET;
 
-/** Regex to validate tmux socket names passed to `tmux -L`. */
-const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
-
 /**
  * Separator used in `tmux list-panes -F` output between session name and pid.
  *
@@ -591,9 +600,8 @@ function resolveConfiguredTmuxSocket(): string {
   const raw = process.env.CODEMAN_TMUX_SOCKET ?? DEFAULT_CODEMAN_TMUX_SOCKET;
   if (!SAFE_TMUX_SOCKET_PATTERN.test(raw)) {
     console.warn(`[TmuxManager] Ignoring invalid CODEMAN_TMUX_SOCKET: ${JSON.stringify(raw)}`);
-    return DEFAULT_CODEMAN_TMUX_SOCKET;
   }
-  return raw;
+  return resolveTmuxSocketName();
 }
 
 /** Build the `tmux -L <socket>` command prefix. Socket name is shell-escaped. */
@@ -1562,6 +1570,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   private reconnectGuard: Set<string> = new Set();
 
   private trueColorConfigured = false;
+  /** tmux 3.7+ can resize pane history after creation; older releases cannot. */
+  private liveHistoryResizeSupported: boolean | null = null;
 
   constructor() {
     super();
@@ -1580,6 +1590,26 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     return tmuxCommand(this.tmuxSocket);
   }
 
+  private supportsLiveHistoryResize(): boolean {
+    if (this.liveHistoryResizeSupported !== null) return this.liveHistoryResizeSupported;
+
+    try {
+      const output = execSync(`${this.tmux()} -V`, {
+        encoding: 'utf8',
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const match = output.match(/(?:^|\D)(\d+)\.(\d+)/);
+      const major = match ? Number(match[1]) : 0;
+      const minor = match ? Number(match[2]) : 0;
+      this.liveHistoryResizeSupported = major > 3 || (major === 3 && minor >= 7);
+    } catch {
+      // Unknown versions take the legacy path required by tmux <3.7.
+      this.liveHistoryResizeSupported = false;
+    }
+    return this.liveHistoryResizeSupported;
+  }
+
   // Load saved sessions from disk (NEVER called in test mode)
   private loadSessions(): void {
     if (IS_TEST_MODE) return;
@@ -1853,29 +1883,28 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       return session;
     }
 
-    // Resolve CLI binary directory based on mode
+    // Resolve CLI binary directory based on mode. The not-found messages come
+    // from the resolvers (formatCliNotFoundMessage) so the error names WHERE it
+    // looked — server PATH, login shell, checked directories — instead of just
+    // asserting the CLI is missing (the classic systemd/launchd PATH trap).
     const { pathExport, dir: cliDir } = this.buildPathExport(mode);
     if (mode === 'claude' && !cliDir) {
-      throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
+      throw new Error(getClaudeNotFoundMessage());
     }
     if (mode === 'opencode' && !cliDir) {
-      throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
+      throw new Error(getOpenCodeNotFoundMessage());
     }
     if (mode === 'codex' && !cliDir) {
-      throw new Error('Codex CLI not found. Install with: npm install -g @openai/codex');
+      throw new Error(getCodexNotFoundMessage());
     }
     if (mode === 'gemini' && !cliDir) {
-      throw new Error('Gemini CLI not found. Install with: npm install -g @google/gemini-cli');
+      throw new Error(getGeminiNotFoundMessage());
     }
     if (mode === 'antigravity' && !cliDir) {
-      throw new Error(
-        'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
-      );
+      throw new Error(getAntigravityNotFoundMessage());
     }
     if (mode === 'pi' && !cliDir) {
-      throw new Error(
-        'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
-      );
+      throw new Error(getPiNotFoundMessage());
     }
 
     const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
@@ -1921,7 +1950,16 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // launched in TMUX_LAUNCH_CWD (/tmp) rather than the real workingDir: a FUSE/rclone
       // mount that isn't ready yet makes `getcwd` fail and breaks the spawn (see #110). The
       // pane cd's into workingDir below via respawn-pane.
-      execSync(`${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD}`, {
+      // tmux <3.7 allocates history only at pane creation, so its global default
+      // must be set immediately BEFORE new-session. tmux 3.7+ can resize a pane
+      // after creation; target only the new session there because changing the
+      // global option can resize (and when lowered, trim) unrelated live panes.
+      const safeHistoryLimit =
+        Number.isSafeInteger(historyLimit) && historyLimit > 0 ? Math.trunc(historyLimit) : DEFAULT_TMUX_HISTORY_LIMIT;
+      const createSessionCommand = this.supportsLiveHistoryResize()
+        ? `${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD} \\; set-option -t "${muxName}" history-limit ${safeHistoryLimit}`
+        : `${this.tmux()} set-option -g history-limit ${safeHistoryLimit} \\; new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD} \\; set-option -t "${muxName}" history-limit ${safeHistoryLimit}`;
+      execSync(createSessionCommand, {
         cwd: TMUX_LAUNCH_CWD,
         timeout: EXEC_TIMEOUT_MS,
         stdio: 'ignore',
@@ -1986,16 +2024,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
           .catch(() => {
             /* Already set globally as fallback */
           }),
-        // Raise tmux scrollback from its 2000-line default so re-attach preserves
-        // more context. Intentionally exceeds the xterm-side DEFAULT_SCROLLBACK (50k
-        // in constants.js), which stays lower to protect browser/mobile memory.
-        execAsync(`${this.tmux()} set-option -t "${muxName}" history-limit ${historyLimit}`, {
-          timeout: EXEC_TIMEOUT_MS,
-        })
-          .then(() => {})
-          .catch(() => {
-            /* Non-critical — falls back to tmux default */
-          }),
       ];
 
       // Enable 24-bit true color passthrough — server-wide, set once per lifetime
@@ -2119,7 +2147,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       resumeSessionId,
       envOverrides,
       effort,
-      historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
       remote,
       docker,
       name,
@@ -2130,16 +2157,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
 
-    // Re-apply the configured tmux history-limit after respawn (kept in sync
-    // with the live setting via setHistoryLimit()).
-    if (!IS_TEST_MODE) {
-      await execAsync(`${this.tmux()} set-option -t ${shellescape(muxName)} history-limit ${historyLimit}`, {
-        timeout: EXEC_TIMEOUT_MS,
-      }).catch(() => {
-        /* Non-critical — keeps existing tmux history-limit */
-      });
-    }
-
     // Resolve CLI binary directory based on mode
     const { pathExport } = this.buildPathExport(mode);
 
@@ -2998,9 +3015,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   }
 
   /**
-   * Apply a tmux history-limit to all tracked sessions (e.g. when the user
-   * changes the terminal-history setting). Invalid limits fall back to the
-   * default. Best-effort per session.
+   * Apply a tmux history limit. tmux 3.7+ safely targets tracked live sessions;
+   * older releases can only change the global default for future panes. Invalid
+   * limits fall back to the default.
    */
   async setHistoryLimit(limit: number): Promise<void> {
     const safeLimit = Number.isSafeInteger(limit) && limit > 0 ? Math.trunc(limit) : DEFAULT_TMUX_HISTORY_LIMIT;
@@ -3009,12 +3026,22 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       return;
     }
 
-    const updates = Array.from(this.sessions.values()).map((session) =>
-      execAsync(`${this.tmux()} set-option -t ${shellescape(session.muxName)} history-limit ${safeLimit}`, {
-        timeout: EXEC_TIMEOUT_MS,
-      })
-    );
-    await Promise.allSettled(updates);
+    if (this.supportsLiveHistoryResize()) {
+      const updates = Array.from(this.sessions.values()).map((session) =>
+        execAsync(`${this.tmux()} set-option -t ${shellescape(session.muxName)} history-limit ${safeLimit}`, {
+          timeout: EXEC_TIMEOUT_MS,
+        })
+      );
+      await Promise.allSettled(updates);
+      return;
+    }
+
+    await execAsync(`${this.tmux()} set-option -g history-limit ${safeLimit}`, {
+      timeout: EXEC_TIMEOUT_MS,
+    }).catch(() => {
+      // No tmux server yet is fine: legacy createSession sets the same default
+      // immediately before it creates the first pane.
+    });
   }
 
   /**

src/tui/tui-ansi.ts

@@ -0,0 +1,598 @@
+/**
+ * @fileoverview Pure ANSI helpers for the TUI preview pane.
+ *
+ * The preview shows the tail of a session's raw terminal stream, which is
+ * xterm-bound bytes: SGR colors, cursor jumps, OSC titles, DECSET modes and
+ * carriage-return repaints. This is NOT a terminal emulator. It reconstructs a
+ * readable, color-preserving tail: SGR survives, everything else that steers a
+ * cursor is dropped, and a `\r` is honored as "back to column 0" so a spinner
+ * that repaints its line 200 times contributes one line instead of 200.
+ *
+ * CURSOR ADDRESSING (`ESC [ r ; c H`) is honored too, and it has to be: an Ink
+ * TUI like Claude Code repaints by ROW and emits almost no newlines, so
+ * dropping those sequences collapses a whole screen into one unreadable line
+ * (measured against a live pane, 2026-08-16). A jump to column 1 starts a new
+ * display line, a jump within a row moves the write position, which is the same
+ * reading `normalizeCapturedFrame` in `web/approval-inbox.ts` takes of the same
+ * kind of frame.
+ *
+ * Two approximations are deliberate, because the alternative is an emulator:
+ * a carriage-return overwrite counts CODE POINTS, not display columns (so a
+ * repaint over CJK text can land one cell off), and tab stops are counted the
+ * same way. Neither can corrupt output, they only shift a repaint's alignment.
+ * Absolute ROW numbers are ignored as well: rows arrive in the order they are
+ * painted, which for a tail is the order worth reading.
+ *
+ * @module tui/tui-ansi
+ */
+
+const ESC = 0x1b;
+const BEL = 0x07;
+const ST_C1 = 0x9c;
+const DEL = 0x7f;
+
+/** SGR reset, appended by `clipStyledLine` so a clipped line cannot bleed. */
+export const SGR_RESET = '\x1b[0m';
+
+const TAB_WIDTH = 8;
+/** Cap on remembered SGR sequences per cell, so a pathological stream cannot grow one unboundedly. */
+const MAX_ACTIVE_SGR = 32;
+/** Ceiling on a display line's cells: a stream may address column 99999, a terminal has none. */
+const MAX_LINE_CELLS = 1000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Escape-sequence scanning
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface EscapeScan {
+  /** Index just past the sequence; `text.length` for a truncated one. */
+  next: number;
+  /** The sequence itself, only when it is SGR (`CSI ... m`) and therefore kept. */
+  sgr?: string;
+  /** 1-based column of a cursor-position sequence (`CSI r ; c H` or `f`). */
+  column?: number;
+  /** 1-based row of that same sequence. Row 1 means a repaint is starting. */
+  row?: number;
+}
+
+/** The row and column a `CSI r ; c H` addresses. Both parameters default to 1. */
+function cursorPosition(params: string): { row: number; column: number } {
+  const parts = params.split(';');
+  const read = (index: number): number => {
+    const value = Number.parseInt(parts[index] ?? '', 10);
+    return Number.isSafeInteger(value) && value > 0 ? value : 1;
+  };
+  return { row: read(0), column: read(1) };
+}
+
+/** Scan a CSI body starting at `from` (params, then intermediates, then a final byte). */
+function readCsi(text: string, start: number, from: number, keepSgr: boolean): EscapeScan {
+  let j = from;
+  while (j < text.length && text.charCodeAt(j) >= 0x30 && text.charCodeAt(j) <= 0x3f) j++;
+  while (j < text.length && text.charCodeAt(j) >= 0x20 && text.charCodeAt(j) <= 0x2f) j++;
+  if (j >= text.length) return { next: text.length };
+  const next = j + 1;
+  if (keepSgr && text[j] === 'm') return { next, sgr: text.slice(start, next) };
+  if (keepSgr && (text[j] === 'H' || text[j] === 'f')) {
+    return { next, ...cursorPosition(text.slice(from, j)) };
+  }
+  return { next };
+}
+
+/** Scan an OSC/DCS/PM/APC body: everything up to BEL, C1 ST or `ESC \`. */
+function readStringSequence(text: string, from: number): number {
+  let j = from;
+  while (j < text.length) {
+    const code = text.charCodeAt(j);
+    if (code === BEL || code === ST_C1) return j + 1;
+    if (code === ESC && text[j + 1] === '\\') return j + 2;
+    j++;
+  }
+  return text.length;
+}
+
+/** Scan the escape sequence starting at `i` (which must be an ESC). */
+function readEscape(text: string, i: number): EscapeScan {
+  const second = text[i + 1];
+  if (second === undefined) return { next: text.length };
+  if (second === '[') return readCsi(text, i, i + 2, true);
+  if (second === ']' || second === 'P' || second === 'X' || second === '^' || second === '_') {
+    return { next: readStringSequence(text, i + 2) };
+  }
+  // Charset / character-set selection: one more byte belongs to the sequence.
+  if (second === '(' || second === ')' || second === '*' || second === '+' || second === '#' || second === '%') {
+    return { next: Math.min(text.length, i + 3) };
+  }
+  return { next: i + 2 };
+}
+
+/** Scan a single-byte C1 control at `i` (0x80-0x9f). */
+function readC1(text: string, i: number): number {
+  const code = text.charCodeAt(i);
+  if (code === 0x9b) return readCsi(text, i, i + 1, false).next;
+  if (code === 0x90 || code === 0x9d || code === 0x9e || code === 0x9f) return readStringSequence(text, i + 1);
+  return i + 1;
+}
+
+function isC1(code: number): boolean {
+  return code >= 0x80 && code <= 0x9f;
+}
+
+/** `CSI 0 m`, `CSI m` and `CSI 0;0 m` all mean "back to plain". */
+function isSgrReset(seq: string): boolean {
+  const params = seq.slice(2, -1);
+  return params === '' || /^0(?:;0)*$/.test(params);
+}
+
+/**
+ * Fold one SGR sequence into the active set. Sequences accumulate in arrival
+ * order (a later color simply wins when replayed), a reset clears them, and a
+ * repeat moves rather than duplicates.
+ */
+function applySgr(active: string[], seq: string): string[] {
+  if (isSgrReset(seq)) return [];
+  const next = active.filter((s) => s !== seq);
+  next.push(seq);
+  return next.length > MAX_ACTIVE_SGR ? next.slice(-MAX_ACTIVE_SGR) : next;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Display width
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Combining marks, variation selectors and other zero-advance code points.
+ * Pragmatic, not exhaustive: enough that accents and emoji modifiers do not
+ * inflate a measured width.
+ */
+const ZERO_WIDTH_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0x0300, 0x036f],
+  [0x0483, 0x0489],
+  [0x0591, 0x05bd],
+  [0x05bf, 0x05bf],
+  [0x0610, 0x061a],
+  [0x064b, 0x065f],
+  [0x0670, 0x0670],
+  [0x06d6, 0x06dc],
+  [0x0e31, 0x0e31],
+  [0x0e34, 0x0e3a],
+  [0x0e47, 0x0e4e],
+  [0x200b, 0x200f],
+  [0x2028, 0x202e],
+  [0x2060, 0x2064],
+  [0x20d0, 0x20f0],
+  [0xfe00, 0xfe0f],
+  [0xfe20, 0xfe2f],
+  [0xfeff, 0xfeff],
+];
+
+/**
+ * East Asian Wide + Fullwidth, plus the standalone code points UAX #11 marks
+ * Wide because they are emoji-presentation by default. This repo ships a zh-CN
+ * locale, so CJK correctness is the point; exhaustive Unicode is not required,
+ * but the scattered BMP entries below are not optional either: `✋` (U+270B) is
+ * one of them and it is a glyph this TUI draws in every waiting row, so getting
+ * it wrong mis-pads a column on every frame.
+ */
+const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0x1100, 0x115f],
+  [0x231a, 0x231b],
+  [0x23e9, 0x23ec],
+  [0x23f0, 0x23f0],
+  [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe],
+  [0x2614, 0x2615],
+  [0x2648, 0x2653],
+  [0x267f, 0x267f],
+  [0x2693, 0x2693],
+  [0x26a1, 0x26a1],
+  [0x26aa, 0x26ab],
+  [0x26bd, 0x26be],
+  [0x26c4, 0x26c5],
+  [0x26ce, 0x26ce],
+  [0x26d4, 0x26d4],
+  [0x26ea, 0x26ea],
+  [0x26f2, 0x26f3],
+  [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa],
+  [0x26fd, 0x26fd],
+  [0x2705, 0x2705],
+  [0x270a, 0x270b],
+  [0x2728, 0x2728],
+  [0x274c, 0x274c],
+  [0x274e, 0x274e],
+  [0x2753, 0x2755],
+  [0x2757, 0x2757],
+  [0x2795, 0x2797],
+  [0x27b0, 0x27b0],
+  [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c],
+  [0x2b50, 0x2b50],
+  [0x2b55, 0x2b55],
+  [0x2e80, 0x303e],
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf],
+  [0xa960, 0xa97f],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe10, 0xfe19],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f004, 0x1f004],
+  [0x1f0cf, 0x1f0cf],
+  [0x1f18e, 0x1f18e],
+  [0x1f191, 0x1f19a],
+  [0x1f200, 0x1f320],
+  [0x1f32d, 0x1f335],
+  [0x1f337, 0x1f37c],
+  [0x1f37e, 0x1f393],
+  [0x1f3a0, 0x1f3ca],
+  [0x1f3cf, 0x1f3d3],
+  [0x1f3e0, 0x1f3f0],
+  [0x1f3f4, 0x1f3f4],
+  [0x1f3f8, 0x1f43e],
+  [0x1f440, 0x1f440],
+  [0x1f442, 0x1f4fc],
+  [0x1f4ff, 0x1f53d],
+  [0x1f54b, 0x1f54e],
+  [0x1f550, 0x1f567],
+  [0x1f57a, 0x1f57a],
+  [0x1f595, 0x1f596],
+  [0x1f5a4, 0x1f5a4],
+  [0x1f5fb, 0x1f64f],
+  [0x1f680, 0x1f6c5],
+  [0x1f6cc, 0x1f6cc],
+  [0x1f6d0, 0x1f6d2],
+  [0x1f6eb, 0x1f6ec],
+  [0x1f6f4, 0x1f6fc],
+  [0x1f7e0, 0x1f7eb],
+  [0x1f90c, 0x1f93a],
+  [0x1f93c, 0x1f945],
+  [0x1f947, 0x1f9ff],
+  [0x1fa70, 0x1faff],
+  [0x20000, 0x2fffd],
+  [0x30000, 0x3fffd],
+];
+
+function inRanges(cp: number, ranges: ReadonlyArray<readonly [number, number]>): boolean {
+  for (const [lo, hi] of ranges) {
+    if (cp < lo) return false;
+    if (cp <= hi) return true;
+  }
+  return false;
+}
+
+/** Columns one code point advances the cursor by: 0, 1 or 2. */
+export function charWidth(codePoint: number): number {
+  if (codePoint < 0x20 || (codePoint >= DEL && codePoint <= 0x9f)) return 0;
+  if (inRanges(codePoint, ZERO_WIDTH_RANGES)) return 0;
+  if (inRanges(codePoint, WIDE_RANGES)) return 2;
+  return 1;
+}
+
+/** Display width of a string: escape sequences take no columns, CJK takes two. */
+export function visibleWidth(text: string): number {
+  let width = 0;
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === ESC) {
+      i = readEscape(text, i).next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(text, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = text.codePointAt(i) as number;
+    i += cp > 0xffff ? 2 : 1;
+    width += charWidth(cp);
+  }
+  return width;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Raw stream to display lines
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One printed code point (plus any combining marks) and the SGR state under it. */
+interface Cell {
+  text: string;
+  sgr: string;
+}
+
+/**
+ * Replay cells into a string, emitting an SGR change only where the state
+ * actually changes and closing the line so it is self-contained.
+ */
+function renderCells(cells: Cell[]): string {
+  let out = '';
+  let active = '';
+  for (const cell of cells) {
+    if (cell.sgr !== active) {
+      if (active !== '') out += SGR_RESET;
+      out += cell.sgr;
+      active = cell.sgr;
+    }
+    out += cell.text;
+  }
+  if (active !== '') out += SGR_RESET;
+  return out;
+}
+
+/**
+ * Turn a raw terminal stream into display lines: SGR preserved, every other
+ * escape sequence dropped, `\r` treated as a return to column 0 (the following
+ * text overwrites what is there), tabs expanded, other control characters
+ * dropped.
+ *
+ * Splitting matches `String.split('\n')`, so `''` yields `['']` and a trailing
+ * newline yields a trailing empty line.
+ */
+/**
+ * Glyphs a CLI draws as chrome that a plain terminal font very often has no
+ * coverage for, and the ASCII that means the same thing.
+ *
+ * ⚠️ This is NOT a substitute for the glyph TIER. The tier answers "can this
+ * terminal do Unicode at all", which is a locale question, and it says yes for
+ * exactly the terminals this table exists for: a beta tester's font rendered
+ * `·`, `─`, `│` and `▶` perfectly while drawing claude's `❯` prompt and its
+ * `⏵⏵` mode marker as empty boxes. Coverage is per-glyph and undetectable from
+ * here, so the rare ones are folded and the common ones are left alone.
+ *
+ * Kept deliberately SHORT. Every entry is a glyph seen rendering as tofu in a
+ * real terminal, not a guess, and each maps to the arrow it already looks like.
+ */
+const PREVIEW_GLYPH_FOLD: ReadonlyMap<string, string> = new Map([
+  ['\u276F', '>'], // ❯ heavy right-pointing angle quotation mark (claude, starship, zsh prompts)
+  ['\u276E', '<'], // ❮
+  ['\u23F5', '>'], // ⏵ black medium right-pointing triangle (claude's bypass-permissions marker)
+  ['\u23F4', '<'], // ⏴
+  ['\u23F6', '^'], // ⏶
+  ['\u23F7', 'v'], // ⏷
+  ['\u2771', '>'], // ❱
+  ['\u2770', '<'], // ❰
+  // claude's own working/done spinner cycles through these, and they are the
+  // same sparse-Dingbats class as `❯`: the animated line is exactly where a
+  // reader looks, so tofu there is the most visible kind.
+  ['\u2722', '*'], // ✢
+  ['\u2733', '*'], // ✳
+  ['\u2217', '*'], // ∗
+  ['\u273B', '*'], // ✻
+  ['\u273D', '*'], // ✽
+  ['\u2734', '*'], // ✴
+  ['\u26A0', '!'], // ⚠ Misc Symbols, and emoji-presentation on many terminals
+]);
+
+/**
+ * Replace preview glyphs a plain font is likely to draw as an empty box.
+ *
+ * Applied to ANOTHER program's output on its way into the preview pane, never
+ * to the TUI's own chrome, and skipped at the `nerd` tier where the user has
+ * declared a font that can draw anything.
+ */
+export function foldPreviewGlyphs(line: string): string {
+  let out = '';
+  for (const char of line) out += PREVIEW_GLYPH_FOLD.get(char) ?? char;
+  return out;
+}
+
+export function toDisplayLines(raw: string): string[] {
+  const lines: string[] = [];
+  let cells: Cell[] = [];
+  let col = 0;
+  let active: string[] = [];
+  let sgr = '';
+
+  const endLine = (): void => {
+    lines.push(renderCells(cells));
+    cells = [];
+    col = 0;
+  };
+
+  /**
+   * Park the write position at a column, padding the gap so the cell array
+   * never grows a hole (a hole would crash the replay, and a stream can address
+   * any column it likes).
+   */
+  const moveTo = (column: number): void => {
+    const target = Math.min(column, MAX_LINE_CELLS);
+    while (cells.length < target) cells.push({ text: ' ', sgr: '' });
+    col = target;
+  };
+
+  const write = (text: string, width: number): void => {
+    if (width === 0) {
+      // A combining mark belongs to the character it follows, never to a cell
+      // of its own: keeping them together is what stops a clip from severing
+      // an accent from its base letter.
+      if (col > 0) cells[col - 1].text += text;
+      return;
+    }
+    cells[col] = { text, sgr };
+    col++;
+  };
+
+  let i = 0;
+  while (i < raw.length) {
+    const code = raw.charCodeAt(i);
+    if (code === ESC) {
+      const scan = readEscape(raw, i);
+      if (scan.sgr !== undefined) {
+        active = applySgr(active, scan.sgr);
+        sgr = active.join('');
+      } else if (scan.row === 1 && scan.column === 1) {
+        // ⚠️ A HOME is a full-screen app announcing that it is repainting from
+        // the top, and everything already on screen is about to be overwritten
+        // in place. This replay is line-based and cannot overwrite, so the
+        // faithful equivalent is to start over — without it every repaint was
+        // APPENDED, and a claude pane's tail carried fifty stacked copies of
+        // the same frame. The preview then showed the last N lines, which on a
+        // tall terminal spanned two of them (reported from the beta as the
+        // overview showing the session twice).
+        lines.length = 0;
+        cells = [];
+        col = 0;
+      } else if (scan.column !== undefined) {
+        // Column 1 is a fresh row, which is the only thing a repainting TUI
+        // gives us to split lines on.
+        if (scan.column <= 1) endLine();
+        else moveTo(scan.column - 1);
+      }
+      i = scan.next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(raw, i);
+      continue;
+    }
+    if (code === 0x0a) {
+      endLine();
+      i++;
+      continue;
+    }
+    if (code === 0x0d) {
+      col = 0;
+      i++;
+      continue;
+    }
+    if (code === 0x09) {
+      const stop = TAB_WIDTH - (col % TAB_WIDTH);
+      for (let n = 0; n < stop; n++) write(' ', 1);
+      i++;
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = raw.codePointAt(i) as number;
+    const text = String.fromCodePoint(cp);
+    i += text.length;
+    write(text, charWidth(cp));
+  }
+  endLine();
+  return lines;
+}
+
+/**
+ * The parameter bytes plus final byte of a CSI sequence whose `ESC [` was cut
+ * off. Requires at least one parameter byte, so ordinary text starting with a
+ * letter is never mistaken for one.
+ */
+const SEVERED_CSI = /^[0-9;?:<>=]+[A-Za-z]/;
+
+/**
+ * Drop the remains of an escape sequence a byte-sliced tail begins in the
+ * middle of.
+ *
+ * `GET /api/sessions/:id/terminal?tail=N` cuts the buffer at a byte offset, so
+ * a tail can start inside `ESC [ 12 ; 1 H` and hand the parser `;1H` as text,
+ * which is exactly what it then prints (observed against a live Claude pane).
+ * Only the severed head is dropped, never a whole line.
+ */
+export function dropSeveredEscape(raw: string): string {
+  return raw.replace(SEVERED_CSI, '');
+}
+
+/**
+ * Drop every escape sequence, keeping the visible text. Needed because the
+ * preview carries the session's OWN colors: under NO_COLOR the frame must not
+ * smuggle them back in.
+ */
+export function stripStyles(text: string): string {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === ESC) {
+      i = readEscape(text, i).next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(text, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = text.codePointAt(i) as number;
+    const size = cp > 0xffff ? 2 : 1;
+    out += text.slice(i, i + size);
+    i += size;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Clipping and padding
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Clip a line that carries SGR to `width` display columns, keeping the styling
+ * that is active up to the clip point and closing it with a reset. Never splits
+ * a code point, a combining sequence or an escape sequence, and never emits
+ * half of a double-width character (the cell is dropped instead).
+ */
+export function clipStyledLine(line: string, width: number): string {
+  if (width <= 0) return '';
+  let out = '';
+  let used = 0;
+  let active: string[] = [];
+  // Styles are emitted lazily, right before the character that wears them, so a
+  // sequence sitting exactly on the clip boundary is not carried into a line it
+  // no longer styles.
+  let emitted = '';
+  let i = 0;
+  while (i < line.length) {
+    const code = line.charCodeAt(i);
+    if (code === ESC) {
+      const scan = readEscape(line, i);
+      if (scan.sgr !== undefined) active = applySgr(active, scan.sgr);
+      i = scan.next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(line, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = line.codePointAt(i) as number;
+    const w = charWidth(cp);
+    if (used + w > width) break;
+    const style = active.join('');
+    if (style !== emitted) {
+      if (emitted !== '') out += SGR_RESET;
+      out += style;
+      emitted = style;
+    }
+    out += String.fromCodePoint(cp);
+    used += w;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return emitted !== '' ? out + SGR_RESET : out;
+}
+
+/**
+ * Pad or clip to exactly `width` display columns. A clip that lands on a
+ * double-width boundary leaves one column short, so the pad runs after it.
+ */
+export function padDisplay(text: string, width: number): string {
+  if (width <= 0) return '';
+  const w = visibleWidth(text);
+  if (w === width) return text;
+  if (w < width) return text + ' '.repeat(width - w);
+  const clipped = clipStyledLine(text, width);
+  return clipped + ' '.repeat(Math.max(0, width - visibleWidth(clipped)));
+}

src/tui/tui-approvals.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Pure reading of an approvals-inbox item: what the card says,
+ * which keys are live for it, and which of them just appeared.
+ *
+ * This is the half of "answer the dialog from the dashboard" that can be stated
+ * as a function of the item. The IO half (`POST /api/approvals/:id/answer`)
+ * lives in `tui-client.ts`, and the server re-captures the pane before it aims
+ * any keystroke, so a card that went stale is refused rather than mis-answered.
+ *
+ * The key matrix is deliberately narrow, because the alternative is typing a
+ * digit into whatever now has focus:
+ *
+ * | kind       | y            | n                      | 1-9                       |
+ * | ---------- | ------------ | ---------------------- | ------------------------- |
+ * | permission | approve      | the parsed "No" option, | only digits the server     |
+ * | question   | approve      | else Esc               | actually parsed off screen |
+ * | idle       | not a dialog: `p` (the composer) is the reply path      |
+ *
+ * A digit that is not among the parsed options returns null, which is what lets
+ * the caller fall back to the list's own 1-9 jump instead of sending a keystroke
+ * the dialog has no answer for.
+ *
+ * PURE: no IO, no timers, no `process.*`.
+ *
+ * @module tui/tui-approvals
+ */
+
+import type { ApprovalItem, ApprovalOption } from '../web/approval-inbox.js';
+import type { TuiApprovalAnswer } from './tui-client.js';
+
+/** Card severity, in the same red/yellow vocabulary the web inbox uses. */
+export type TuiApprovalTone = 'err' | 'warn';
+
+export interface TuiApprovalCard {
+  tone: TuiApprovalTone;
+  /** One line: what is being asked. */
+  title: string;
+  /** Extra context, one entry per line, already trimmed. May be empty. */
+  detail: string[];
+  /** Numbered choices parsed off the pane, empty when the frame did not parse. */
+  options: ApprovalOption[];
+  /** What the user can press right now, in words. */
+  hint: string;
+}
+
+/** Longest single line the card contributes before the renderer clips it. */
+const MAX_CARD_TEXT = 400;
+
+function clean(text: string | undefined): string {
+  return (text ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_CARD_TEXT);
+}
+
+export function approvalTone(item: ApprovalItem): TuiApprovalTone {
+  return item.kind === 'idle' ? 'warn' : 'err';
+}
+
+/**
+ * What the card says. Permission prompts lead with the tool (that is the whole
+ * question), questions lead with their message, and an idle prompt says what it
+ * is, since there is nothing to approve.
+ */
+export function approvalCard(item: ApprovalItem): TuiApprovalCard {
+  const options = item.options ?? [];
+  const message = clean(item.message);
+  const summary = clean(item.toolSummary) || clean(item.toolName);
+
+  if (item.kind === 'idle') {
+    return {
+      tone: 'warn',
+      title: message || 'waiting for your reply',
+      detail: [],
+      options: [],
+      hint: 'p to reply',
+    };
+  }
+
+  const title =
+    item.kind === 'permission'
+      ? `requests: ${summary || 'permission'}`
+      : message || `question: ${summary || 'Claude is asking'}`;
+  const detail: string[] = [];
+  if (item.kind === 'permission' && message && message !== summary) detail.push(message);
+
+  return {
+    tone: 'err',
+    title,
+    detail,
+    options,
+    hint: options.length > 0 ? 'y approve · n deny · digit chooses' : 'y approve · n deny',
+  };
+}
+
+/**
+ * The parsed option that means "no". Claude renders it as `3. No, tell Claude
+ * what to do (esc)`, and answering with its digit is the same keystroke the
+ * dialog itself is waiting for; without a parsed one the answer route's `deny`
+ * sends Esc, which every dialog understands.
+ */
+export function approvalDenyOption(item: ApprovalItem): number | null {
+  const match = (item.options ?? []).find((option) => /^no\b/i.test(option.label));
+  return match ? match.n : null;
+}
+
+/**
+ * The answer one key produces, or null when that key means nothing here (so the
+ * caller can let its normal binding through).
+ */
+export function approvalAnswerForKey(item: ApprovalItem, key: string): TuiApprovalAnswer | null {
+  // An idle prompt has no dialog on screen: a digit or a `1` would land in the
+  // composer as text. The card points at `p` instead.
+  if (item.kind === 'idle') return null;
+  if (key === 'y') return { action: 'approve' };
+  if (key === 'n') {
+    const deny = approvalDenyOption(item);
+    return deny === null ? { action: 'deny' } : { action: 'option', option: deny };
+  }
+  if (key >= '1' && key <= '9') {
+    const option = Number.parseInt(key, 10);
+    return (item.options ?? []).some((entry) => entry.n === option) ? { action: 'option', option } : null;
+  }
+  return null;
+}
+
+/**
+ * Ids in `items` that `seen` has not recorded. The bell rings for these and for
+ * nothing else, which is what keeps a repaint (or a refetch that returns the
+ * same pending item) silent.
+ *
+ * Answered ids stay in `seen` on purpose: the inbox restores an item under its
+ * ORIGINAL id when a write fails, and re-ringing for a prompt the user already
+ * heard about is worse than missing one.
+ */
+export function newApprovalIds(seen: ReadonlySet<string>, items: readonly ApprovalItem[]): string[] {
+  const fresh: string[] = [];
+  for (const item of items) if (!seen.has(item.id) && !fresh.includes(item.id)) fresh.push(item.id);
+  return fresh;
+}

src/tui/tui-composer.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Pure single-line editor behind the TUI's prompt composer (`p`)
+ * and search query (`/`).
+ *
+ * Text is held as CODE POINTS rather than a string, because every operation
+ * here is index-based and a cursor that can land inside a surrogate pair
+ * eventually deletes half an emoji. Combining marks are their own entries: they
+ * are zero-width, so they neither move the cursor's column nor cost a cell, and
+ * backspace peeling one off a base letter is what a terminal editor does.
+ *
+ * Scrolling is derived, never remembered implicitly: `composerScroll()` takes
+ * the width and returns the state whose window holds the cursor, which is what
+ * keeps "what the footer shows" a function of the state plus the terminal width
+ * rather than of the order the user pressed keys in.
+ *
+ * PURE: no IO, no timers, no `process.*`. Enter and Escape are reported as
+ * `submit`/`cancel` rather than acted on, since only the caller knows whether
+ * Enter means "send this prompt" or "open the highlighted search result".
+ *
+ * @module tui/tui-composer
+ */
+
+import { charWidth } from './tui-ansi.js';
+import type { TuiInputEvent } from './tui-keys.js';
+
+export interface TuiComposerState {
+  /** Code points. `chars.join('')` is the text. */
+  readonly chars: readonly string[];
+  /** 0..chars.length. The cursor sits BEFORE `chars[cursor]`. */
+  readonly cursor: number;
+  /** First visible code point, as `composerScroll()` last resolved it. */
+  readonly scroll: number;
+}
+
+export function createComposer(text = ''): TuiComposerState {
+  const chars = [...text];
+  return { chars, cursor: chars.length, scroll: 0 };
+}
+
+export function composerText(state: TuiComposerState): string {
+  return state.chars.join('');
+}
+
+function withChars(chars: readonly string[], cursor: number, scroll: number): TuiComposerState {
+  const clampedCursor = Math.min(Math.max(0, cursor), chars.length);
+  return { chars, cursor: clampedCursor, scroll: Math.min(Math.max(0, scroll), chars.length) };
+}
+
+/** Insert typed text at the cursor. Newlines are stripped: this is one line. */
+export function composerInsert(state: TuiComposerState, value: string): TuiComposerState {
+  const inserted = [...value.replace(/[\r\n]+/g, ' ')];
+  if (inserted.length === 0) return state;
+  const chars = [...state.chars.slice(0, state.cursor), ...inserted, ...state.chars.slice(state.cursor)];
+  return withChars(chars, state.cursor + inserted.length, state.scroll);
+}
+
+/** Delete the code point before the cursor. */
+export function composerBackspace(state: TuiComposerState): TuiComposerState {
+  if (state.cursor === 0) return state;
+  const chars = [...state.chars.slice(0, state.cursor - 1), ...state.chars.slice(state.cursor)];
+  return withChars(chars, state.cursor - 1, state.scroll);
+}
+
+/** Delete the code point under the cursor (the Delete key). */
+export function composerDelete(state: TuiComposerState): TuiComposerState {
+  if (state.cursor >= state.chars.length) return state;
+  const chars = [...state.chars.slice(0, state.cursor), ...state.chars.slice(state.cursor + 1)];
+  return withChars(chars, state.cursor, state.scroll);
+}
+
+/** Delete back to the start of the word before the cursor (Ctrl+W). */
+export function composerDeleteWord(state: TuiComposerState): TuiComposerState {
+  let start = state.cursor;
+  while (start > 0 && state.chars[start - 1] === ' ') start--;
+  while (start > 0 && state.chars[start - 1] !== ' ') start--;
+  if (start === state.cursor) return state;
+  const chars = [...state.chars.slice(0, start), ...state.chars.slice(state.cursor)];
+  return withChars(chars, start, state.scroll);
+}
+
+export function composerMove(state: TuiComposerState, delta: number): TuiComposerState {
+  const cursor = Math.min(Math.max(0, state.cursor + Math.trunc(delta)), state.chars.length);
+  return cursor === state.cursor ? state : withChars(state.chars, cursor, state.scroll);
+}
+
+export function composerHome(state: TuiComposerState): TuiComposerState {
+  return state.cursor === 0 ? state : withChars(state.chars, 0, state.scroll);
+}
+
+export function composerEnd(state: TuiComposerState): TuiComposerState {
+  return state.cursor === state.chars.length ? state : withChars(state.chars, state.chars.length, state.scroll);
+}
+
+export function composerClear(state: TuiComposerState): TuiComposerState {
+  return state.chars.length === 0 ? state : { chars: [], cursor: 0, scroll: 0 };
+}
+
+/** Display columns of `chars[from..to)`. */
+function widthOf(chars: readonly string[], from: number, to: number): number {
+  let width = 0;
+  for (let i = from; i < to; i++) width += charWidth(chars[i].codePointAt(0) ?? 0);
+  return width;
+}
+
+/**
+ * Resolve `scroll` so the cursor is inside a window `width` columns wide,
+ * scrolling the minimum needed. One column is reserved for the cursor itself,
+ * so a cursor at the end of the text still has a cell to sit in instead of
+ * hanging one past the edge where the terminal would wrap it.
+ */
+export function composerScroll(state: TuiComposerState, width: number): TuiComposerState {
+  const usable = Math.max(0, Math.trunc(width) - 1);
+  let scroll = Math.min(Math.max(0, state.scroll), state.cursor);
+  while (scroll < state.cursor && widthOf(state.chars, scroll, state.cursor) > usable) scroll++;
+  return scroll === state.scroll ? state : { chars: state.chars, cursor: state.cursor, scroll };
+}
+
+export interface TuiComposerWindow {
+  /** The visible slice of the text. */
+  text: string;
+  /** Cursor offset in display columns from the start of `text`. */
+  cursorColumn: number;
+  /** Resolved first visible code point (may differ from `state.scroll`). */
+  scroll: number;
+}
+
+/**
+ * The slice the footer draws plus where the terminal cursor belongs. The scroll
+ * is resolved here too, so a renderer that never writes state back still shows
+ * the cursor.
+ */
+export function composerWindow(state: TuiComposerState, width: number): TuiComposerWindow {
+  const columns = Math.max(1, Math.trunc(width));
+  const scrolled = composerScroll(state, columns);
+  const { chars, cursor, scroll } = scrolled;
+  let used = 0;
+  let end = scroll;
+  while (end < chars.length) {
+    const next = charWidth(chars[end].codePointAt(0) ?? 0);
+    if (used + next > columns) break;
+    used += next;
+    end++;
+  }
+  return {
+    text: chars.slice(scroll, Math.max(end, cursor)).join(''),
+    cursorColumn: widthOf(chars, scroll, cursor),
+    scroll,
+  };
+}
+
+export type TuiComposerStep =
+  | { kind: 'edit'; state: TuiComposerState }
+  | { kind: 'submit'; text: string }
+  | { kind: 'cancel' }
+  | { kind: 'ignore' };
+
+/**
+ * One keystroke. Enter and Escape are REPORTED rather than applied: `p` sends
+ * the line while `/` opens the highlighted result, and only the caller knows
+ * which.
+ */
+export function composerStep(state: TuiComposerState, event: TuiInputEvent): TuiComposerStep {
+  switch (event.type) {
+    case 'char':
+      return { kind: 'edit', state: composerInsert(state, event.value) };
+    case 'backspace':
+      return { kind: 'edit', state: composerBackspace(state) };
+    case 'enter':
+      return { kind: 'submit', text: composerText(state) };
+    case 'escape':
+      return { kind: 'cancel' };
+    case 'key':
+      switch (event.name) {
+        case 'left':
+          return { kind: 'edit', state: composerMove(state, -1) };
+        case 'right':
+          return { kind: 'edit', state: composerMove(state, 1) };
+        case 'home':
+          return { kind: 'edit', state: composerHome(state) };
+        case 'end':
+          return { kind: 'edit', state: composerEnd(state) };
+        case 'delete':
+          return { kind: 'edit', state: composerDelete(state) };
+        default:
+          return { kind: 'ignore' };
+      }
+    case 'ctrl':
+      switch (event.key) {
+        case 'c':
+          return { kind: 'cancel' };
+        case 'a':
+          return { kind: 'edit', state: composerHome(state) };
+        case 'e':
+          return { kind: 'edit', state: composerEnd(state) };
+        case 'u':
+          return { kind: 'edit', state: composerClear(state) };
+        case 'w':
+          return { kind: 'edit', state: composerDeleteWord(state) };
+        default:
+          return { kind: 'ignore' };
+      }
+    default:
+      return { kind: 'ignore' };
+  }
+}

src/tui/tui-digest.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Pure formatting of `GET /api/away-digest` into the lines the
+ * `g` overlay scrolls.
+ *
+ * The digest answers "what happened while I was away", so it is read top-down
+ * and never studied: every entry is one line (age, session, what happened), a
+ * long section is capped with a "… n more" tail rather than allowed to push the
+ * next section off screen, and the counts that matter live in the first line
+ * where they are visible without scrolling at all.
+ *
+ * PURE: no IO, no clock of its own (the caller passes `now`), no `process.*`.
+ *
+ * @module tui/tui-digest
+ */
+
+import { formatElapsed, formatTokens } from './tui-render.js';
+import type { AwayDigestItem, AwayDigestResponse, AwayDigestSectionName } from '../web/away-digest.js';
+
+/** Entries per section before the tail takes over. */
+export const DIGEST_SECTION_LIMIT = 6;
+
+const SECTION_ORDER: ReadonlyArray<readonly [AwayDigestSectionName, string]> = [
+  ['needsAttention', 'NEEDS ATTENTION'],
+  ['completed', 'COMPLETED'],
+  ['stillRunning', 'STILL RUNNING'],
+  ['idle', 'IDLE'],
+  ['informational', 'INFO'],
+];
+
+const RANGE_WORDS: Record<string, string> = {
+  'since-last-visit': 'since your last visit',
+  '1h': 'the last hour',
+  today: 'today',
+  '24h': 'the last 24 hours',
+  custom: 'the selected window',
+};
+
+export interface TuiDigestOptions {
+  now: number;
+  sectionLimit?: number;
+}
+
+function ageColumn(item: AwayDigestItem, now: number): string {
+  const age = item.timestamp > 0 ? formatElapsed(now - item.timestamp) : '';
+  return age.padEnd(4);
+}
+
+function itemLine(item: AwayDigestItem, now: number): string {
+  const who = item.sessionName ?? item.sessionId?.slice(0, 8) ?? '';
+  const what = [item.title, item.detail].filter((part) => part && part.trim() !== '').join(' · ');
+  return `  ${ageColumn(item, now)} ${[who, what].filter((part) => part !== '').join('  ')}`.replace(/\s+$/, '');
+}
+
+/**
+ * The digest as display lines. The first line is the summary, then one block
+ * per non-empty section, then the token totals when the range had any.
+ */
+export function formatAwayDigest(digest: AwayDigestResponse, options: TuiDigestOptions): string[] {
+  const limit = Math.max(1, Math.trunc(options.sectionLimit ?? DIGEST_SECTION_LIMIT));
+  const { totals } = digest;
+  const lines: string[] = [
+    [
+      RANGE_WORDS[digest.range.range] ?? 'recently',
+      `${totals.sessionsCreated} started`,
+      `${totals.sessionsExited} exited`,
+      `${totals.activeSessions} running`,
+    ].join(' · '),
+  ];
+
+  let entries = 0;
+  for (const [key, label] of SECTION_ORDER) {
+    const items = digest.sections[key] ?? [];
+    if (items.length === 0) continue;
+    entries += items.length;
+    lines.push('', `${label} (${items.length})`);
+    for (const item of items.slice(0, limit)) lines.push(itemLine(item, options.now));
+    if (items.length > limit) lines.push(`  … ${items.length - limit} more`);
+  }
+
+  if (entries === 0) lines.push('', 'nothing happened while you were away');
+
+  const tokens = [
+    formatTokens(totals.inputTokens ?? 0) ? `${formatTokens(totals.inputTokens ?? 0)} in` : '',
+    formatTokens(totals.outputTokens ?? 0) ? `${formatTokens(totals.outputTokens ?? 0)} out` : '',
+    typeof totals.estimatedCost === 'number' && totals.estimatedCost > 0 ? `$${totals.estimatedCost.toFixed(2)}` : '',
+  ].filter((part) => part !== '');
+  if (tokens.length > 0) lines.push('', `tokens: ${tokens.join(' · ')}`);
+
+  return lines;
+}

src/tui/tui-keys.ts

@@ -0,0 +1,240 @@
+/**
+ * @fileoverview Pure byte-stream to input-event parser for raw-mode stdin.
+ *
+ * Stateful (a sequence can arrive split across reads, and a UTF-8 character can
+ * be split mid-code-point) but pure: it owns a byte buffer and nothing else, no
+ * stdin, no timers. The one timing decision a terminal forces on us stays with
+ * the caller: a lone ESC is indistinguishable from the start of an arrow key
+ * until something either follows it or does not, so the parser HOLDS a trailing
+ * ESC and the caller calls `flush()` after ~30ms of silence to turn it into an
+ * Escape event.
+ *
+ * Unknown sequences are swallowed rather than leaked as text: a stray
+ * `CSI 200~` must never end up typed into a prompt composer.
+ *
+ * @module tui/tui-keys
+ */
+
+/** Keys with a name rather than a character. */
+export type TuiNamedKey =
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'home'
+  | 'end'
+  | 'pageup'
+  | 'pagedown'
+  | 'delete'
+  | 'insert';
+
+export type TuiMouseKind = 'press' | 'release' | 'wheel-up' | 'wheel-down';
+
+/** Discriminated union, exhaustive-switch friendly (see `utils/assertNever`). */
+export type TuiInputEvent =
+  | { type: 'char'; value: string }
+  | { type: 'enter' }
+  | { type: 'tab' }
+  | { type: 'backspace' }
+  | { type: 'escape' }
+  | { type: 'ctrl'; key: string }
+  | { type: 'alt'; value: string }
+  | { type: 'key'; name: TuiNamedKey }
+  | { type: 'mouse'; kind: TuiMouseKind; x: number; y: number; button: number };
+
+export interface TuiKeyParser {
+  /** Decode a chunk. Incomplete tails are held for the next call. */
+  feed(chunk: Buffer | string): TuiInputEvent[];
+  /** Resolve a held ESC (the caller's disambiguation timer fired). */
+  flush(): TuiInputEvent[];
+  /** Bytes currently held back. Exposed for the ESC timer and for tests. */
+  pending(): number;
+}
+
+/**
+ * An unterminated sequence longer than this is not a sequence: the held bytes
+ * are dropped whole, so a garbage burst can neither wedge the parser nor leak
+ * its bytes into a prompt as typed characters.
+ */
+const MAX_PENDING_BYTES = 64;
+
+/** Bytes in a UTF-8 sequence given its lead byte; 0 for a byte that cannot lead one. */
+function utf8SequenceLength(lead: number): number {
+  if (lead < 0x80) return 1;
+  if (lead >= 0xc2 && lead <= 0xdf) return 2;
+  if (lead >= 0xe0 && lead <= 0xef) return 3;
+  if (lead >= 0xf0 && lead <= 0xf4) return 4;
+  return 0;
+}
+
+const CSI_FINAL_KEYS: Record<string, TuiNamedKey> = {
+  A: 'up',
+  B: 'down',
+  C: 'right',
+  D: 'left',
+  H: 'home',
+  F: 'end',
+};
+
+/** `CSI <n> ~` keys, by their first numeric parameter. */
+const CSI_TILDE_KEYS: Record<number, TuiNamedKey> = {
+  1: 'home',
+  2: 'insert',
+  3: 'delete',
+  4: 'end',
+  5: 'pageup',
+  6: 'pagedown',
+  7: 'home',
+  8: 'end',
+};
+
+/** Result of trying to parse one sequence off the front of the buffer. */
+type ParseStep = { consumed: number; events: TuiInputEvent[] } | 'incomplete';
+
+const NOTHING: TuiInputEvent[] = [];
+
+export function createKeyParser(): TuiKeyParser {
+  let buf: Buffer = Buffer.alloc(0);
+
+  /** Parse the CSI/SS3 sequence that starts at buf[0] === ESC. */
+  const parseEscape = (): ParseStep => {
+    if (buf.length < 2) return 'incomplete';
+    const second = buf[1];
+
+    // SS3 (`ESC O <final>`): the arrows/Home/End of application-cursor mode.
+    if (second === 0x4f) {
+      if (buf.length < 3) return 'incomplete';
+      const name = CSI_FINAL_KEYS[String.fromCharCode(buf[2])];
+      return { consumed: 3, events: name ? [{ type: 'key', name }] : NOTHING };
+    }
+
+    // ESC followed by a printable character IN THE SAME READ is Alt+that key:
+    // that is how every terminal sends a meta chord. A lone Esc cannot look
+    // like this, because a buffer holding only ESC returns 'incomplete' above
+    // and is flushed as `escape` when the read ends, which is the standard way
+    // to tell the two apart without a timer.
+    //
+    // ⚠️ Three characters are deliberately NOT treated as Alt chords, because
+    // the terminal uses them to introduce sequences and a chord is
+    // indistinguishable from one: `[` (CSI) and `O` (SS3) would swallow every
+    // arrow key, and `]` (OSC) would swallow a terminal's colour-query reply.
+    // Alt+[ and Alt+] therefore cannot exist in a terminal at all, which is why
+    // the list binds bare `[` and `]` for the same job.
+    if (second !== 0x5b) {
+      if (second >= 0x20 && second <= 0x7e && second !== 0x4f && second !== 0x5d) {
+        return { consumed: 2, events: [{ type: 'alt', value: String.fromCharCode(second) }] };
+      }
+      return { consumed: 1, events: [{ type: 'escape' }] };
+    }
+
+    let j = 2;
+    while (j < buf.length && buf[j] >= 0x30 && buf[j] <= 0x3f) j++;
+    while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x2f) j++;
+    if (j >= buf.length) return 'incomplete';
+    const final = String.fromCharCode(buf[j]);
+    const params = buf.subarray(2, j).toString('latin1');
+    const consumed = j + 1;
+
+    // X10 mouse (`CSI M` + 3 raw bytes): swallowed, but its payload bytes must
+    // be consumed or they would surface as typed characters.
+    if (params === '' && final === 'M') {
+      if (buf.length < consumed + 3) return 'incomplete';
+      return { consumed: consumed + 3, events: NOTHING };
+    }
+
+    if (params.startsWith('<') && (final === 'M' || final === 'm')) {
+      return { consumed, events: parseSgrMouse(params.slice(1), final) };
+    }
+
+    if (final === '~') {
+      const name = CSI_TILDE_KEYS[Number.parseInt(params, 10)];
+      return { consumed, events: name ? [{ type: 'key', name }] : NOTHING };
+    }
+
+    // Modified arrows (`CSI 1;5A`) carry the same final byte; the modifier is
+    // dropped rather than exposed, since nothing in the keymap wants it yet.
+    const named = CSI_FINAL_KEYS[final];
+    return { consumed, events: named ? [{ type: 'key', name: named }] : NOTHING };
+  };
+
+  const parseSgrMouse = (params: string, final: string): TuiInputEvent[] => {
+    const parts = params.split(';');
+    if (parts.length < 3) return NOTHING;
+    const button = Number.parseInt(parts[0], 10);
+    const x = Number.parseInt(parts[1], 10);
+    const y = Number.parseInt(parts[2], 10);
+    if (!Number.isFinite(button) || !Number.isFinite(x) || !Number.isFinite(y)) return NOTHING;
+    if (button >= 64) {
+      // 64 = wheel up, 65 = wheel down (the low bit is the direction).
+      const kind: TuiMouseKind = (button & 1) === 1 ? 'wheel-down' : 'wheel-up';
+      return [{ type: 'mouse', kind, x, y, button }];
+    }
+    // Motion reports (bit 32) would fire on every pixel of a drag; nothing in
+    // the keymap consumes them, so they are swallowed here rather than upstream.
+    if ((button & 32) === 32) return NOTHING;
+    return [{ type: 'mouse', kind: final === 'M' ? 'press' : 'release', x, y, button }];
+  };
+
+  /** Parse one non-escape byte (or one UTF-8 character) off the front. */
+  const parseByte = (): ParseStep => {
+    const b = buf[0];
+    // LF counts as Enter because some terminals send it for Return; the cost is
+    // that Ctrl+J is not bindable, which no key in the plan's keymap wants.
+    if (b === 0x0d || b === 0x0a) return { consumed: 1, events: [{ type: 'enter' }] };
+    if (b === 0x09) return { consumed: 1, events: [{ type: 'tab' }] };
+    if (b === 0x7f || b === 0x08) return { consumed: 1, events: [{ type: 'backspace' }] };
+    if (b === 0x00) return { consumed: 1, events: [{ type: 'ctrl', key: '@' }] };
+    if (b >= 0x01 && b <= 0x1a) {
+      return { consumed: 1, events: [{ type: 'ctrl', key: String.fromCharCode(b + 0x60) }] };
+    }
+    if (b >= 0x1c && b <= 0x1f) {
+      return { consumed: 1, events: [{ type: 'ctrl', key: String.fromCharCode(b + 0x40) }] };
+    }
+    const length = utf8SequenceLength(b);
+    if (length === 0) return { consumed: 1, events: NOTHING };
+    if (buf.length < length) return 'incomplete';
+    const value = buf.subarray(0, length).toString('utf8');
+    // A lead byte followed by junk decodes to U+FFFD; that is corruption on the
+    // wire, not something to type into a composer. Only the bad lead byte is
+    // dropped, so whatever valid input followed it still decodes.
+    if (value.includes('�')) return { consumed: 1, events: NOTHING };
+    return { consumed: length, events: [{ type: 'char', value }] };
+  };
+
+  /** Drain the buffer, stopping at the first incomplete sequence. */
+  const drain = (events: TuiInputEvent[]): void => {
+    while (buf.length > 0) {
+      const step = buf[0] === 0x1b ? parseEscape() : parseByte();
+      if (step === 'incomplete') {
+        if (buf.length > MAX_PENDING_BYTES) buf = Buffer.alloc(0);
+        return;
+      }
+      for (const event of step.events) events.push(event);
+      buf = buf.subarray(step.consumed);
+    }
+  };
+
+  return {
+    feed(chunk: Buffer | string): TuiInputEvent[] {
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+      buf = buf.length === 0 ? Buffer.from(bytes) : Buffer.concat([buf, bytes]);
+      const events: TuiInputEvent[] = [];
+      drain(events);
+      return events;
+    },
+
+    flush(): TuiInputEvent[] {
+      const events: TuiInputEvent[] = [];
+      if (buf.length > 0 && buf[0] === 0x1b) {
+        events.push({ type: 'escape' });
+        buf = buf.subarray(1);
+        drain(events);
+      }
+      return events;
+    },
+
+    pending(): number {
+      return buf.length;
+    },
+  };
+}

src/tui/tui-layout.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Pure responsive layout math for the TUI frame.
+ *
+ * One rule decides the shape: below 72 columns (Termius, iPhone portrait) the
+ * preview pane is gone and rows take two lines, which is the constraint the
+ * `sc` chooser was built around and the reason it is still usable on a phone.
+ * Above it, a clamped sidebar carries the session list and the preview takes
+ * the rest.
+ *
+ * Rectangles are 1-based (row 1, column 1 is the top-left cell) because that is
+ * what `ESC [ <row>;<col> H` takes, and every region is clamped to a
+ * non-negative size so a 5x5 terminal degrades instead of producing negative
+ * widths that would crash the renderer.
+ *
+ * @module tui/tui-layout
+ */
+
+import type { TuiConnectionStatus } from './tui-types.js';
+
+/** Width at which the preview pane is dropped and rows become two lines. */
+export const NARROW_BREAKPOINT = 72;
+/** Sidebar clamp: narrower than this and a session name stops being readable. */
+export const SIDEBAR_MIN_WIDTH = 34;
+/** Sidebar clamp: wider than this is wasted on a list of short names. */
+export const SIDEBAR_MAX_WIDTH = 44;
+/** A preview thinner than this shows nothing useful, so the layout goes narrow instead. */
+export const PREVIEW_MIN_WIDTH = 24;
+/** Share of the width the sidebar aims for between the clamps. */
+const SIDEBAR_RATIO = 0.36;
+
+export interface TuiRect {
+  /** 1-based terminal row of the first line. */
+  row: number;
+  /** 1-based terminal column of the first cell. */
+  col: number;
+  width: number;
+  height: number;
+}
+
+export interface TuiLayoutOptions {
+  /**
+   * Reserve one line under the header for the connection banner. The caller
+   * decides with `needsBanner(model.connection)`, so layout stays pure math.
+   */
+  banner?: boolean;
+}
+
+export interface TuiLayout {
+  cols: number;
+  rows: number;
+  /** No preview pane, two-line rows. */
+  narrow: boolean;
+  /** Terminal lines one session row occupies. */
+  rowHeight: 1 | 2;
+  header: TuiRect;
+  /** Connection banner, when the caller asked for one and there was room. */
+  banner: TuiRect | null;
+  /** Everything between header and footer, banner included. */
+  body: TuiRect;
+  /** The session list. */
+  list: TuiRect;
+  /** The one-column rule between list and preview; null in narrow mode. */
+  divider: TuiRect | null;
+  /** The preview pane; null in narrow mode. */
+  preview: TuiRect | null;
+  footer: TuiRect;
+}
+
+/** Which connection states get a banner line under the header. */
+export function needsBanner(connection: TuiConnectionStatus): boolean {
+  return connection !== 'connected';
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/**
+ * Rectangles for one frame at `cols` x `rows`.
+ *
+ * The header always exists; the footer appears from 2 rows up; the body is
+ * whatever is left, which may legitimately be zero lines high.
+ */
+export function computeLayout(cols: number, rows: number, options: TuiLayoutOptions = {}): TuiLayout {
+  const width = Math.max(1, Math.floor(cols) || 1);
+  const height = Math.max(1, Math.floor(rows) || 1);
+
+  const headerHeight = 1;
+  const footerHeight = height >= 2 ? 1 : 0;
+  const bodyHeight = Math.max(0, height - headerHeight - footerHeight);
+  const bodyRow = headerHeight + 1;
+
+  const header: TuiRect = { row: 1, col: 1, width, height: headerHeight };
+  const footer: TuiRect = { row: height, col: 1, width, height: footerHeight };
+  const body: TuiRect = { row: bodyRow, col: 1, width, height: bodyHeight };
+
+  const bannerHeight = options.banner === true && bodyHeight > 0 ? 1 : 0;
+  const banner: TuiRect | null = bannerHeight > 0 ? { row: bodyRow, col: 1, width, height: 1 } : null;
+
+  const contentRow = bodyRow + bannerHeight;
+  const contentHeight = Math.max(0, bodyHeight - bannerHeight);
+
+  const sidebarTarget = Math.floor(width * SIDEBAR_RATIO);
+  const sidebarWidth = clamp(sidebarTarget, SIDEBAR_MIN_WIDTH, SIDEBAR_MAX_WIDTH);
+  const previewWidth = width - sidebarWidth - 1;
+  const narrow = width < NARROW_BREAKPOINT || previewWidth < PREVIEW_MIN_WIDTH;
+
+  if (narrow) {
+    return {
+      cols: width,
+      rows: height,
+      narrow: true,
+      rowHeight: 2,
+      header,
+      banner,
+      body,
+      list: { row: contentRow, col: 1, width, height: contentHeight },
+      divider: null,
+      preview: null,
+      footer,
+    };
+  }
+
+  return {
+    cols: width,
+    rows: height,
+    narrow: false,
+    rowHeight: 1,
+    header,
+    banner,
+    body,
+    list: { row: contentRow, col: 1, width: sidebarWidth, height: contentHeight },
+    divider: { row: contentRow, col: sidebarWidth + 1, width: 1, height: contentHeight },
+    preview: { row: contentRow, col: sidebarWidth + 2, width: previewWidth, height: contentHeight },
+    footer,
+  };
+}

src/tui/tui-model.ts

@@ -0,0 +1,562 @@
+/**
+ * @fileoverview Pure state, classification and grouping for the TUI dashboard.
+ *
+ * Classification speaks the web UI's language on purpose (red blocked, yellow
+ * waiting, green working, muted idle), because a user who has both surfaces
+ * open must never have to translate between them. The inputs are the ones the
+ * server already computes: a unified-list row and, when the session is blocked,
+ * the approvals-inbox item that blocks it. Nothing here screen-scrapes.
+ *
+ * Selection is tracked by session id, never by row index: rows re-sort under
+ * the cursor constantly (a session starts working, an approval lands), and an
+ * index-tracked cursor would silently move the selection to a different
+ * session between two keystrokes.
+ *
+ * PURE: no IO, no timers, no `process.*`. The store mutates its own state and
+ * nothing else.
+ *
+ * @module tui/tui-model
+ */
+
+import type { SearchResultGroup, SearchSourceType } from '../types/search.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type {
+  TuiConfirmState,
+  TuiConnectionStatus,
+  TuiDigestState,
+  TuiGroup,
+  TuiGroupKey,
+  TuiHeaderInfo,
+  TuiMessage,
+  TuiPickerState,
+  TuiPreview,
+  TuiPromptState,
+  TuiRenderModel,
+  TuiRow,
+  TuiSearchEntry,
+  TuiSearchState,
+  TuiSessionRow,
+  TuiSessionState,
+  TuiUiMode,
+} from './tui-types.js';
+
+/** How many history rows the RECENT group shows before it stops being a dashboard. */
+export const DEFAULT_RECENT_LIMIT = 8;
+
+export const GROUP_ORDER: readonly TuiGroupKey[] = ['needs-you', 'working', 'idle', 'recent'];
+
+export const GROUP_LABELS: Record<TuiGroupKey, string> = {
+  'needs-you': 'NEEDS YOU',
+  working: 'WORKING',
+  idle: 'IDLE',
+  recent: 'RECENT',
+};
+
+const STATE_GROUP: Record<TuiSessionState, TuiGroupKey> = {
+  'blocked-question': 'needs-you',
+  'blocked-permission': 'needs-you',
+  waiting: 'needs-you',
+  working: 'working',
+  idle: 'idle',
+  recent: 'recent',
+};
+
+/** A row is live when the unified merge saw it in the in-memory session map. */
+export function isLiveRow(session: TuiSessionRow): boolean {
+  return Array.isArray(session.sources) && session.sources.includes('live');
+}
+
+/**
+ * Classify one row.
+ *
+ * Order matters and mirrors `_mobileOverviewState()` in the web UI: a pending
+ * prompt outranks everything (it is literally blocking the agent), and it
+ * outranks a stale `busy` status because the hook is the newer signal. An
+ * errored session has no state of its own here and joins the waiting tier,
+ * since it is equally something only a human can clear.
+ */
+export function classifySession(session: TuiSessionRow, approval?: ApprovalItem): TuiSessionState {
+  if (!isLiveRow(session)) return 'recent';
+  if (approval) {
+    if (approval.kind === 'permission') return 'blocked-permission';
+    if (approval.kind === 'question') return 'blocked-question';
+    return 'waiting';
+  }
+  if (session.status === 'error') return 'waiting';
+  if (session.isWorking === true || session.status === 'busy') return 'working';
+  return 'idle';
+}
+
+/**
+ * Epoch ms the session entered its current state, which is what the intra-group
+ * ordering sorts on. 0 when nothing usable is known.
+ *
+ * A WORKING pane repaints about once a second, so its `lastActivityAt` is
+ * always "now" and would report every running turn as freshly started; the
+ * turn's own start is the pane's last Enter.
+ */
+export function stateSince(state: TuiSessionState, session: TuiSessionRow, approval?: ApprovalItem): number {
+  if (approval) return approval.createdAt;
+  if (state === 'working') return session.lastSubmitAt ?? session.createdAt ?? 0;
+  return session.lastActivityAt ?? session.createdAt ?? 0;
+}
+
+/** Classify a batch of rows against the pending approvals, keyed by session id. */
+export function buildRows(
+  sessions: readonly TuiSessionRow[],
+  approvals: ReadonlyMap<string, ApprovalItem> = new Map()
+): TuiRow[] {
+  return sessions.map((session) => {
+    const approval = approvals.get(session.sessionId);
+    const state = classifySession(session, approval);
+    const row: TuiRow = {
+      session,
+      state,
+      group: STATE_GROUP[state],
+      since: stateSince(state, session, approval),
+    };
+    if (approval) row.approval = approval;
+    return row;
+  });
+}
+
+function compareIds(a: TuiRow, b: TuiRow): number {
+  if (a.session.sessionId < b.session.sessionId) return -1;
+  if (a.session.sessionId > b.session.sessionId) return 1;
+  return 0;
+}
+
+/** Longest first: the oldest anchor wins, and an unknown anchor sorts last. */
+function compareLongestFirst(a: TuiRow, b: TuiRow): number {
+  const left = a.since || Number.MAX_SAFE_INTEGER;
+  const right = b.since || Number.MAX_SAFE_INTEGER;
+  return left !== right ? left - right : compareIds(a, b);
+}
+
+/** Newest first: the freshest anchor wins, and an unknown anchor sorts last. */
+function compareNewestFirst(a: TuiRow, b: TuiRow): number {
+  const left = a.since || 0;
+  const right = b.since || 0;
+  return left !== right ? right - left : compareIds(a, b);
+}
+
+export interface GroupOptions {
+  /** RECENT is a tail, not a list: everything past this is dropped. */
+  recentLimit?: number;
+}
+
+/**
+ * Split classified rows into the four display groups.
+ *
+ * Always returns all four in display order (empty ones included) so callers
+ * never have to guess the shape; the renderer skips the empty ones.
+ *
+ * NEEDS YOU and WORKING are ordered by how long they have been in that state
+ * (longest first: the thing that has waited longest for you is the thing to
+ * look at). IDLE and RECENT are ordered by recency, newest first.
+ */
+export function groupSessions(rows: readonly TuiRow[], options: GroupOptions = {}): TuiGroup[] {
+  const recentLimit = Math.max(0, Math.floor(options.recentLimit ?? DEFAULT_RECENT_LIMIT));
+  const buckets: Record<TuiGroupKey, TuiRow[]> = {
+    'needs-you': [],
+    working: [],
+    idle: [],
+    recent: [],
+  };
+  for (const row of rows) buckets[row.group].push(row);
+
+  buckets['needs-you'].sort(compareLongestFirst);
+  buckets.working.sort(compareLongestFirst);
+  buckets.idle.sort(compareNewestFirst);
+  buckets.recent.sort(compareNewestFirst);
+  buckets.recent = buckets.recent.slice(0, recentLimit);
+
+  return GROUP_ORDER.map((key) => ({ key, label: GROUP_LABELS[key], rows: buckets[key] }));
+}
+
+/** The cursor's list: group headers are chrome, only sessions are selectable. */
+export function flattenRows(groups: readonly TuiGroup[]): TuiRow[] {
+  const rows: TuiRow[] = [];
+  for (const group of groups) rows.push(...group.rows);
+  return rows;
+}
+
+/**
+ * Fold an incoming row into a known one. Defined fields win, `undefined` never
+ * clobbers (a live SSE payload carries no transcript fields, a unified refresh
+ * carries no token counters), but a non-empty `sources` list REPLACES rather
+ * than unions: a session that ended must be able to lose its `live` source and
+ * fall to RECENT.
+ */
+export function mergeSessionRow(existing: TuiSessionRow, incoming: TuiSessionRow): TuiSessionRow {
+  const merged: TuiSessionRow = { ...existing };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value === undefined) continue;
+    (merged as unknown as Record<string, unknown>)[key] = value;
+  }
+  merged.sources = incoming.sources?.length ? [...incoming.sources] : [...(existing.sources ?? [])];
+  return merged;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Search results (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SEARCH_GROUP_LABELS: Record<SearchSourceType, string> = {
+  session: 'SESSIONS',
+  event: 'EVENTS',
+  file: 'FILES',
+};
+
+/**
+ * A session snippet opens with the session's own name, which the row already
+ * shows in its first column (`search-service.ts` builds it as
+ * `w1-alpha <em dash> /tmp/alpha`, hence the separator in the pattern).
+ * Dropping the repeat is what keeps a result row from reading as a stutter.
+ */
+function withoutLabelPrefix(snippet: string, label: string): string {
+  const rest = snippet.startsWith(label) ? snippet.slice(label.length) : snippet;
+  return rest === snippet ? snippet : rest.replace(/^\s*(?:[—:-]\s*)?/, '');
+}
+
+/**
+ * Flatten `GET /api/search`'s typed groups into the overlay's lines: a header
+ * per group, then its results. Only a result row carries a session id, which is
+ * what the cursor uses to skip headers.
+ *
+ * `isLive` decides which rows can hand the dashboard a session: a history hit
+ * has a session id too, but selecting it would move the cursor to a row that is
+ * not on the list.
+ */
+export function buildSearchEntries(
+  groups: readonly SearchResultGroup[],
+  isLive: (sessionId: string) => boolean
+): TuiSearchEntry[] {
+  const entries: TuiSearchEntry[] = [];
+  for (const group of groups) {
+    if (group.results.length === 0) continue;
+    entries.push({ kind: 'header', text: SEARCH_GROUP_LABELS[group.type] ?? group.type.toUpperCase() });
+    for (const result of group.results) {
+      const live = result.jumpTo.kind === 'session' && isLive(result.sessionId);
+      const label = result.jumpTo.relativePath ?? result.sessionName ?? result.sessionId.slice(0, 8);
+      entries.push({
+        kind: 'result',
+        text: label,
+        detail: withoutLabelPrefix(result.snippet, label),
+        sessionId: result.sessionId,
+        live,
+      });
+    }
+  }
+  return entries;
+}
+
+/** First selectable row, or -1 when the list is all headers (or empty). */
+export function firstSearchIndex(entries: readonly TuiSearchEntry[]): number {
+  return entries.findIndex((entry) => entry.kind === 'result');
+}
+
+/**
+ * Move the search cursor by `delta` result rows, skipping headers and stopping
+ * at both ends (wrapping a search result list scrolls past the answer the user
+ * was reading).
+ */
+export function moveSearchIndex(entries: readonly TuiSearchEntry[], index: number, delta: number): number {
+  const step = Math.trunc(delta);
+  if (step === 0) return index;
+  const direction = step > 0 ? 1 : -1;
+  let current = index;
+  for (let remaining = Math.abs(step); remaining > 0; remaining--) {
+    let next = current + direction;
+    while (next >= 0 && next < entries.length && entries[next].kind !== 'result') next += direction;
+    if (next < 0 || next >= entries.length) break;
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * The dashboard's state. Update methods mutate in place (one store per TUI
+ * process, no subscribers) and every derived view is recomputed from scratch,
+ * which keeps "what is on screen" a pure function of the stored facts.
+ */
+export class TuiModelStore implements TuiRenderModel {
+  private sessionsById = new Map<string, TuiSessionRow>();
+  private approvalsBySession = new Map<string, ApprovalItem>();
+  private _revision = 0;
+
+  selectedId: string | null = null;
+  connection: TuiConnectionStatus = 'connected';
+  mode: TuiUiMode = 'list';
+  header: TuiHeaderInfo = {};
+  preview: TuiPreview | null = null;
+  message: TuiMessage | null = null;
+  confirm: TuiConfirmState | null = null;
+  picker: TuiPickerState | null = null;
+  prompt: TuiPromptState | null = null;
+  search: TuiSearchState | null = null;
+  digest: TuiDigestState | null = null;
+  recentLimit: number;
+
+  constructor(options: GroupOptions = {}) {
+    this.recentLimit = Math.max(0, Math.floor(options.recentLimit ?? DEFAULT_RECENT_LIMIT));
+  }
+
+  /**
+   * Bumped by every mutating method. The app layer repaints when this changed
+   * (plus on resize and on the animation tick), which is what keeps an idle
+   * dashboard from redrawing itself. Writing a public field directly bypasses
+   * it, so state changes go through the methods below.
+   */
+  get revision(): number {
+    return this._revision;
+  }
+
+  private touch(): void {
+    this._revision++;
+  }
+
+  // ── Data ───────────────────────────────────────────────────────────────────
+
+  upsertSession(session: TuiSessionRow): void {
+    this.mutate(() => {
+      const existing = this.sessionsById.get(session.sessionId);
+      this.sessionsById.set(session.sessionId, existing ? mergeSessionRow(existing, session) : { ...session });
+    });
+  }
+
+  removeSession(sessionId: string): void {
+    this.mutate(() => {
+      this.sessionsById.delete(sessionId);
+      this.approvalsBySession.delete(sessionId);
+    });
+  }
+
+  /** Full refresh (a `GET /api/sessions/unified` poll): the server is authoritative. */
+  replaceSessions(sessions: readonly TuiSessionRow[]): void {
+    this.mutate(() => {
+      this.sessionsById.clear();
+      for (const session of sessions) this.sessionsById.set(session.sessionId, { ...session });
+    });
+  }
+
+  setApprovals(items: readonly ApprovalItem[]): void {
+    this.mutate(() => {
+      this.approvalsBySession.clear();
+      // One active item per session is an inbox invariant; the newest wins if
+      // that ever stops being true.
+      for (const item of items) this.approvalsBySession.set(item.sessionId, item);
+    });
+  }
+
+  sessions(): TuiSessionRow[] {
+    return [...this.sessionsById.values()];
+  }
+
+  // ── Chrome ─────────────────────────────────────────────────────────────────
+
+  setConnection(status: TuiConnectionStatus): void {
+    if (this.connection === status) return;
+    this.connection = status;
+    this.touch();
+  }
+
+  setHeader(header: TuiHeaderInfo): void {
+    this.header = { ...this.header, ...header };
+    this.touch();
+  }
+
+  setPreview(preview: TuiPreview | null): void {
+    this.preview = preview;
+    this.touch();
+  }
+
+  setMode(mode: TuiUiMode): void {
+    if (this.mode === mode) return;
+    this.mode = mode;
+    this.touch();
+  }
+
+  setMessage(message: TuiMessage | null): void {
+    this.message = message;
+    this.mode = message ? 'message' : 'list';
+    this.touch();
+  }
+
+  /** Show (or clear) the overlay chooser. Setting one takes the keyboard. */
+  setPicker(picker: TuiPickerState | null): void {
+    this.picker = picker;
+    this.mode = picker ? 'new-session' : 'list';
+    this.touch();
+  }
+
+  /** Open (or close) the one-line prompt composer. Setting one takes the keyboard. */
+  setPrompt(prompt: TuiPromptState | null): void {
+    this.prompt = prompt;
+    this.mode = prompt ? 'prompt' : 'list';
+    this.touch();
+  }
+
+  /** Replace the composer's editor state, keeping the target session. */
+  updatePrompt(composer: TuiPromptState['composer']): void {
+    if (!this.prompt || this.prompt.composer === composer) return;
+    this.prompt = { ...this.prompt, composer };
+    this.touch();
+  }
+
+  setSearch(search: TuiSearchState | null): void {
+    this.search = search;
+    this.mode = search ? 'search' : 'list';
+    this.touch();
+  }
+
+  /** Fold a partial update into the open search overlay. No-op when it is closed. */
+  updateSearch(patch: Partial<TuiSearchState>): void {
+    if (!this.search) return;
+    this.search = { ...this.search, ...patch };
+    this.touch();
+  }
+
+  setDigest(digest: TuiDigestState | null): void {
+    this.digest = digest;
+    this.mode = digest ? 'digest' : 'list';
+    this.touch();
+  }
+
+  /**
+   * Scroll the digest by `delta` lines. `capacity` is how many lines the box
+   * shows, so the last page cannot scroll into empty space.
+   */
+  scrollDigest(delta: number, capacity: number): void {
+    if (!this.digest) return;
+    const room = Math.max(0, this.digest.lines.length - Math.max(1, Math.trunc(capacity)));
+    const offset = Math.min(Math.max(0, this.digest.offset + Math.trunc(delta)), room);
+    if (offset === this.digest.offset) return;
+    this.digest = { ...this.digest, offset };
+    this.touch();
+  }
+
+  /**
+   * Arm the typed-name confirmation for `x` (kill). Whether what the user typed
+   * AUTHORIZES the kill is `confirmAccepts()` in tui-app, which owns that rule
+   * for every caller: a second copy here answered the same question differently
+   * (it refused the id prefix a mux name carries) and nothing consulted it.
+   */
+  beginConfirmKill(row: TuiRow, label: string): void {
+    this.confirm = {
+      sessionId: row.session.sessionId,
+      // ⚠️ Passed in, not derived here. `row.session.name ?? id.slice(0,8)`
+      // used to compute it, and `??` falls back only on null/undefined: a
+      // session whose name is the EMPTY STRING (every session the server did
+      // not name) sailed through it and the dialog read "Kill ?". A destructive
+      // prompt that cannot say what it is about to destroy is worse than no
+      // prompt, and it is now one keystroke. The caller passes the same label
+      // the LIST shows, so the dialog names the row the user is looking at.
+      name: label,
+    };
+    this.mode = 'confirm-kill';
+    this.touch();
+  }
+
+  /** Drop whatever overlay owns the keyboard and go back to the list. */
+  closeOverlay(): void {
+    this.confirm = null;
+    this.message = null;
+    this.picker = null;
+    this.prompt = null;
+    this.search = null;
+    this.digest = null;
+    this.mode = 'list';
+    this.touch();
+  }
+
+  // ── Derived views ──────────────────────────────────────────────────────────
+
+  groups(): TuiGroup[] {
+    return groupSessions(buildRows(this.sessions(), this.approvalsBySession), { recentLimit: this.recentLimit });
+  }
+
+  rows(): TuiRow[] {
+    return flattenRows(this.groups());
+  }
+
+  get sessionCount(): number {
+    let count = 0;
+    for (const session of this.sessionsById.values()) if (isLiveRow(session)) count++;
+    return count;
+  }
+
+  // ── Cursor ─────────────────────────────────────────────────────────────────
+
+  selectedSession(): TuiRow | null {
+    if (!this.selectedId) return null;
+    return this.rows().find((row) => row.session.sessionId === this.selectedId) ?? null;
+  }
+
+  /** Select a session by id. Returns false when it is not on screen. */
+  select(sessionId: string): boolean {
+    if (!this.rows().some((row) => row.session.sessionId === sessionId)) return false;
+    this.moveTo(sessionId);
+    return true;
+  }
+
+  /** Move by `delta` rows, skipping group headers and wrapping at both ends. */
+  moveCursor(delta: number): void {
+    const rows = this.rows();
+    if (rows.length === 0) {
+      this.moveTo(null);
+      return;
+    }
+    const current = this.indexOfSelected(rows);
+    if (current < 0) {
+      this.moveTo(rows[delta >= 0 ? 0 : rows.length - 1].session.sessionId);
+      return;
+    }
+    const step = Math.trunc(delta);
+    const next = (((current + step) % rows.length) + rows.length) % rows.length;
+    this.moveTo(rows[next].session.sessionId);
+  }
+
+  /** The 1-9 jump: `n` is the 1-based position in the flattened list. */
+  cursorToIndex(n: number): boolean {
+    const rows = this.rows();
+    const index = Math.trunc(n) - 1;
+    if (index < 0 || index >= rows.length) return false;
+    this.moveTo(rows[index].session.sessionId);
+    return true;
+  }
+
+  private moveTo(sessionId: string | null): void {
+    if (this.selectedId === sessionId) return;
+    this.selectedId = sessionId;
+    this.touch();
+  }
+
+  private indexOfSelected(rows: readonly TuiRow[] = this.rows()): number {
+    if (!this.selectedId) return -1;
+    return rows.findIndex((row) => row.session.sessionId === this.selectedId);
+  }
+
+  /**
+   * Run a data mutation and keep the cursor sane afterwards: the selected
+   * session stays selected wherever it moved to, and a session that vanished
+   * hands the cursor to whatever now occupies its place.
+   */
+  private mutate(apply: () => void): void {
+    const previousIndex = this.indexOfSelected();
+    apply();
+    this.touch();
+    const rows = this.rows();
+    if (rows.length === 0) {
+      this.moveTo(null);
+      return;
+    }
+    if (this.selectedId !== null && rows.some((row) => row.session.sessionId === this.selectedId)) return;
+    const index = Math.min(Math.max(previousIndex, 0), rows.length - 1);
+    this.moveTo(rows[index].session.sessionId);
+  }
+}
+
+export function createTuiModel(options: GroupOptions = {}): TuiModelStore {
+  return new TuiModelStore(options);
+}

src/tui/tui-render.ts

@@ -0,0 +1,921 @@
+/**
+ * @fileoverview Pure frame renderer: model + layout in, one string out.
+ *
+ * The frame is absolute-addressed, one `ESC [ <row>;1 H` per line followed by
+ * `ESC [ K`, so nothing ever scrolls and a repaint cannot leave debris. The
+ * caller wraps the result in synchronized-output brackets (DECSET 2026) where
+ * the terminal supports it; that is an IO decision and stays out of here.
+ *
+ * Color is decided by the caller and passed in, never detected here: chalk's
+ * auto-detection is the right answer for the one-shot CLI (see `cli-style.ts`)
+ * but it would make a frame non-deterministic, and "same inputs, same string"
+ * is what makes this module testable. The palette below is the same semantic
+ * vocabulary chalk gives `cli-style` (ok green, warn yellow, err red, info
+ * cyan, muted gray, emph bold), written as raw SGR so the mapping is fixed.
+ *
+ * With `color: false` the frame contains no escape sequences at all beyond the
+ * cursor addressing that puts each line in place.
+ *
+ * @module tui/tui-render
+ */
+
+import { clipStyledLine, padDisplay, stripStyles, visibleWidth } from './tui-ansi.js';
+import { approvalCard } from './tui-approvals.js';
+import { composerText, composerWindow } from './tui-composer.js';
+import type { TuiLayout, TuiRect } from './tui-layout.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type { StatusTelemetry } from '../usage-telemetry.js';
+import type {
+  TuiDigestState,
+  TuiGlyphTier,
+  TuiGroup,
+  TuiPickerState,
+  TuiPromptState,
+  TuiRenderModel,
+  TuiRow,
+  TuiSearchState,
+  TuiSessionRow,
+  TuiSessionState,
+} from './tui-types.js';
+
+export interface TuiRenderOptions {
+  /** Emit SGR color. False is NO_COLOR: cursor addressing and nothing else. */
+  color: boolean;
+  glyphs: TuiGlyphTier;
+  /** Animation counter. The WORKING glyph cycles with it. */
+  tick: number;
+  /** Wall clock for elapsed times, passed in so a frame is reproducible. */
+  now: number;
+  /**
+   * Footer entries, already labelled, joined here with the separator glyph.
+   * The app layer passes the keys that actually do something right now (which
+   * verbs are wired up, whether a server is answering); omitting it falls back
+   * to the full keymap below.
+   */
+  footerKeys?: readonly string[];
+  /**
+   * `[key, what it does]` pairs for the help overlay, same reasoning as
+   * `footerKeys`: the app layer knows which verbs are wired up. Omitting it
+   * falls back to the full keymap.
+   */
+  helpKeys?: ReadonlyArray<readonly [string, string]>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Palette and glyphs
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SGR = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  inverse: '\x1b[7m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+} as const;
+
+/**
+ * One word per state, shared by the preview title and the `--list` output so
+ * both surfaces call a session the same thing.
+ */
+export const STATE_WORDS: Record<TuiSessionState, string> = {
+  'blocked-permission': 'blocked',
+  'blocked-question': 'blocked',
+  waiting: 'waiting',
+  working: 'working',
+  idle: 'idle',
+  recent: 'done',
+};
+
+const STATE_COLOR: Record<TuiSessionState, string> = {
+  'blocked-permission': SGR.red,
+  'blocked-question': SGR.red,
+  waiting: SGR.yellow,
+  working: SGR.green,
+  idle: SGR.gray,
+  recent: SGR.gray,
+};
+
+export interface TuiGlyphSet {
+  blockedPermission: string;
+  blockedQuestion: string;
+  waiting: string;
+  /** WORKING animates through Claude's own glyph family, a deliberate nod. */
+  working: readonly string[];
+  idle: string;
+  recent: string;
+  cursor: string;
+  rule: string;
+  divider: string;
+  boxTopLeft: string;
+  boxTopRight: string;
+  boxBottomLeft: string;
+  boxBottomRight: string;
+  boxHorizontal: string;
+  boxVertical: string;
+  enter: string;
+  updown: string;
+  separator: string;
+  ellipsis: string;
+}
+
+/**
+ * ⚠️ Every glyph here must clear TWO bars that are easy to miss, and both were
+ * failed at once by the first version of this table.
+ *
+ * WIDTH: the renderer addresses cells by column, so a glyph the terminal draws
+ * two cells wide shifts everything after it. `east_asian_width` W or F is
+ * therefore disqualifying. `✋` (U+270B) was Wide, and being an emoji is also
+ * why fonts render it at emoji size in the middle of a text row.
+ *
+ * COVERAGE: a plain terminal font carries far less than the unicode TIER
+ * implies. The tier answers "is the locale UTF-8", which says nothing about
+ * whether a given codepoint has a glyph.
+ *
+ * One beta tester's font mapped the blocks like this, and it is the profile to
+ * design against because it is an ordinary terminal font, not a broken one:
+ *
+ *   RENDERS   Latin-1 (·), Box Drawing (─ │), Block Elements (█ ▛ ▐),
+ *             Geometric Shapes (○ ▶), General Punctuation (…), Arrows
+ *   TOFU      Misc Technical (⏎ U+23CE, ⏵ U+23F5), the sparse end of
+ *             Dingbats (❯ U+276F)
+ *
+ * So: draw from the blocks on the first line. Dingbats, Miscellaneous
+ * Technical, Miscellaneous Symbols and anything with emoji presentation are
+ * out — that class produced three separate "why are there boxes" reports, one
+ * per glyph, because each was fixed on its own instead of as a class.
+ */
+const UNICODE_GLYPHS: TuiGlyphSet = {
+  blockedPermission: '▲',
+  blockedQuestion: '▲',
+  waiting: '!',
+  // Quadrant blocks, which rotate as a spinner and live in the same block as
+  // the `▛█▐` art claude itself draws — proven to render on the font that
+  // failed the dingbats this used to use.
+  working: ['▖', '▘', '▝', '▗'],
+  idle: '○',
+  recent: '✔',
+  cursor: '▶',
+  rule: '─',
+  divider: '│',
+  boxTopLeft: '┌',
+  boxTopRight: '┐',
+  boxBottomLeft: '└',
+  boxBottomRight: '┘',
+  boxHorizontal: '─',
+  boxVertical: '│',
+  enter: '↵',
+  updown: '↑↓',
+  separator: '·',
+  ellipsis: '…',
+};
+
+/**
+ * The lowest tier, for terminals that are not known-capable. Every state token
+ * is three columns wide so rows still line up, mirroring what `sc` falls back
+ * to today.
+ */
+const ASCII_GLYPHS: TuiGlyphSet = {
+  blockedPermission: '[!]',
+  blockedQuestion: '[?]',
+  waiting: '[w]',
+  working: ['[*]', '[+]', '[x]', '[+]'],
+  idle: '[-]',
+  recent: '[v]',
+  cursor: '>',
+  rule: '-',
+  divider: '|',
+  boxTopLeft: '+',
+  boxTopRight: '+',
+  boxBottomLeft: '+',
+  boxBottomRight: '+',
+  boxHorizontal: '-',
+  boxVertical: '|',
+  enter: 'enter',
+  updown: 'up/dn',
+  separator: '-',
+  ellipsis: '..',
+};
+
+/**
+ * Glyphs for a tier. `nerd` currently renders like `unicode`: the tier exists
+ * so detection has somewhere to land and a nerd-font-only set has a home,
+ * without shipping glyphs nobody has reviewed on a real font.
+ */
+export function glyphsFor(tier: TuiGlyphTier): TuiGlyphSet {
+  return tier === 'ascii' ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}
+
+/**
+ * Glyph tier from the environment. IO-ish by nature (it reads env), so it takes
+ * the env as an argument and the app layer calls it once at startup. The
+ * known-capable list is a TERM allowlist, plus a UTF-8 locale check and an
+ * explicit override.
+ */
+export function detectGlyphTier(env: Record<string, string | undefined>): TuiGlyphTier {
+  const override = env.CODEMAN_TUI_GLYPHS;
+  if (override === 'ascii' || override === 'unicode' || override === 'nerd') return override;
+  const term = env.TERM ?? '';
+  if (term === '' || term === 'dumb') return 'ascii';
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+  if (!/utf-?8/i.test(locale)) return 'ascii';
+  const termProgram = env.TERM_PROGRAM ?? '';
+  if (termProgram.startsWith('iTerm') || term === 'xterm-kitty' || env.WEZTERM_PANE || env.LC_TERMINAL === 'iTerm2') {
+    return 'nerd';
+  }
+  return 'unicode';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatting helpers (pure, exported for tests and for the app layer)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Compact age: `45s`, `11m`, `2h`, `3d`. Empty when the anchor is unknown. */
+export function formatElapsed(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return '';
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+function trimTrailingZero(value: string): string {
+  return value.endsWith('.0') ? value.slice(0, -2) : value;
+}
+
+/** Compact token count: `842`, `45.2k`, `1.2M`. Empty when there is nothing to show. */
+export function formatTokens(total: number): string {
+  if (!Number.isFinite(total) || total <= 0) return '';
+  if (total < 1000) return String(Math.floor(total));
+  if (total < 1_000_000) return `${trimTrailingZero((total / 1000).toFixed(1))}k`;
+  return `${trimTrailingZero((total / 1_000_000).toFixed(1))}M`;
+}
+
+/**
+ * The header's plan-usage chip: `5h 32% · wk 61%`, the same two windows the web
+ * chip shows (the statusline telemetry carries no others). Empty when the
+ * account reports neither, so the header shows no placeholder for a fact that
+ * does not exist. The separator is passed in because the header's own comes
+ * from the glyph tier, and an ASCII terminal must not get a stray `·`.
+ */
+export function formatPlanUsage(usage: StatusTelemetry | null | undefined, separator = ' · '): string {
+  if (!usage) return '';
+  const parts: string[] = [];
+  if (typeof usage.fiveHour?.usedPercentage === 'number') {
+    parts.push(`5h ${Math.round(usage.fiveHour.usedPercentage)}%`);
+  }
+  if (typeof usage.sevenDay?.usedPercentage === 'number') {
+    parts.push(`wk ${Math.round(usage.sevenDay.usedPercentage)}%`);
+  }
+  return parts.join(separator);
+}
+
+/**
+ * What a row is called. Same rule as the web history rows, including the
+ * "(no content)" placeholder the transcript reader emits, which is not a title.
+ */
+export function rowLabel(session: TuiSessionRow): string {
+  if (session.name) return session.name;
+  const base = (session.workingDir ?? '').split('/').filter(Boolean).pop();
+  // ⚠️ A LIVE pane (it has a mux name) is identified by WHERE it runs, never by
+  // a line scraped out of its transcript. A session created before the user has
+  // typed anything has no prompt to be named after, so the fallback took
+  // whatever the CLI happened to print first: a beta tester's new session
+  // appeared in the list called "Login interrupted", which reads like a failure
+  // report and was in fact a healthy session. A history row is the opposite
+  // case, where the prompt IS the identity, so it keeps the old order.
+  if (session.muxName && base) return base;
+  const prompt = (session.firstPrompt ?? '').trim();
+  if (prompt && prompt !== '(no content)') return prompt;
+  return base || session.sessionId.slice(0, 8);
+}
+
+/** Keep the tail of a path: the last segments identify it, the root never does. */
+function truncatePathLeft(path: string, width: number, ellipsis: string): string {
+  if (width <= 0) return '';
+  if (visibleWidth(path) <= width) return path;
+  const keep = Math.max(0, width - visibleWidth(ellipsis));
+  return ellipsis + path.slice(path.length - keep);
+}
+
+function tokensOf(session: TuiSessionRow): number {
+  return (session.inputTokens ?? 0) + (session.outputTokens ?? 0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Painting
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Painter = (text: string, code: string) => string;
+
+function painterFor(enabled: boolean): Painter {
+  return enabled ? (text, code) => (text === '' ? text : `${code}${text}${SGR.reset}`) : (text) => text;
+}
+
+function stateGlyph(row: TuiRow, glyphs: TuiGlyphSet, tick: number): string {
+  switch (row.state) {
+    case 'blocked-permission':
+      return glyphs.blockedPermission;
+    case 'blocked-question':
+      return glyphs.blockedQuestion;
+    case 'waiting':
+      return glyphs.waiting;
+    case 'working': {
+      const frames = glyphs.working;
+      const index = ((Math.trunc(tick) % frames.length) + frames.length) % frames.length;
+      return frames[index];
+    }
+    case 'idle':
+      return glyphs.idle;
+    case 'recent':
+      return glyphs.recent;
+  }
+}
+
+function centered(text: string, width: number): string {
+  const pad = Math.max(0, Math.floor((width - visibleWidth(text)) / 2));
+  return padDisplay(`${' '.repeat(pad)}${text}`, width);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rows and groups
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RowContext {
+  width: number;
+  /** 1-based position in the flattened list; only 1-9 get a jump digit. */
+  index: number;
+  selected: boolean;
+  twoLine: boolean;
+  glyphs: TuiGlyphSet;
+  opts: TuiRenderOptions;
+}
+
+function renderRowLines(row: TuiRow, ctx: RowContext): string[] {
+  // A selected row is one inverse-video block, so its parts are built unpainted:
+  // an inner reset would punch a hole in the highlight.
+  const inverse = ctx.selected && ctx.opts.color;
+  const paint = painterFor(ctx.opts.color && !inverse);
+  const { session } = row;
+
+  const marker = ctx.selected ? padDisplay(ctx.glyphs.cursor, 2) : '  ';
+  const digit = ctx.index >= 1 && ctx.index <= 9 ? `${ctx.index} ` : '  ';
+
+  const glyph = paint(stateGlyph(row, ctx.glyphs, ctx.opts.tick), STATE_COLOR[row.state]);
+  const elapsed = row.since > 0 ? formatElapsed(ctx.opts.now - row.since) : '';
+  const tokens = formatTokens(tokensOf(session));
+  const rightParts = [glyph, paint(elapsed, SGR.gray)];
+  if (!ctx.twoLine && tokens) rightParts.push(paint(tokens, SGR.gray));
+  const right = rightParts.filter((part) => part !== '').join(' ');
+
+  const mode = session.mode && session.mode !== 'claude' ? session.mode : '';
+  const nameWidth = Math.max(4, ctx.width - visibleWidth(marker + digit) - visibleWidth(right) - 1);
+  const label = rowLabel(session);
+  const name = mode ? `${label} ${paint(mode, SGR.magenta)}` : label;
+
+  const first = padDisplay(`${marker}${digit}${padDisplay(name, nameWidth)} ${right}`, ctx.width);
+  const lines = [first];
+
+  if (ctx.twoLine) {
+    const detail = [truncatePathLeft(session.workingDir ?? '', Math.max(0, ctx.width - 8), ctx.glyphs.ellipsis)];
+    if (mode) detail.push(mode);
+    if (tokens) detail.push(tokens);
+    const text = detail.filter((part) => part !== '').join(` ${ctx.glyphs.separator} `);
+    lines.push(padDisplay(`    ${paint(text, SGR.gray)}`, ctx.width));
+  }
+
+  return inverse ? lines.map((line) => `${SGR.inverse}${line}${SGR.reset}`) : lines;
+}
+
+function renderGroupHeader(group: TuiGroup, width: number, glyphs: TuiGlyphSet, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const label = ` ${group.label} `;
+  const fill = Math.max(0, width - visibleWidth(label));
+  return padDisplay(`${paint(label, SGR.bold)}${paint(glyphs.rule.repeat(fill), SGR.gray)}`, width);
+}
+
+export interface TuiListEntry {
+  text: string;
+  /** Set on the lines that belong to a session row, so the window can chase the cursor. */
+  sessionId?: string;
+}
+
+function buildListEntries(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): TuiListEntry[] {
+  const glyphs = glyphsFor(opts.glyphs);
+  const width = layout.list.width;
+  const entries: TuiListEntry[] = [];
+  let index = 0;
+  for (const group of model.groups()) {
+    if (group.rows.length === 0) continue;
+    entries.push({ text: renderGroupHeader(group, width, glyphs, opts) });
+    for (const row of group.rows) {
+      index++;
+      const ctx: RowContext = {
+        width,
+        index,
+        selected: row.session.sessionId === model.selectedId,
+        twoLine: layout.rowHeight === 2,
+        glyphs,
+        opts,
+      };
+      for (const text of renderRowLines(row, ctx)) entries.push({ text, sessionId: row.session.sessionId });
+    }
+  }
+  return entries;
+}
+
+/**
+ * First visible entry, scrolling the minimum needed to keep the selected row on
+ * screen. Deterministic on purpose: the window is derived, never remembered, so
+ * two identical models render identically.
+ */
+export function computeListWindow(
+  entries: readonly TuiListEntry[],
+  capacity: number,
+  selectedId: string | null
+): number {
+  if (capacity <= 0 || entries.length <= capacity) return 0;
+  const maxStart = entries.length - capacity;
+  if (!selectedId) return 0;
+  const first = entries.findIndex((entry) => entry.sessionId === selectedId);
+  if (first < 0) return 0;
+  let last = first;
+  while (last + 1 < entries.length && entries[last + 1].sessionId === selectedId) last++;
+  let start = 0;
+  if (last >= capacity) start = Math.min(last - capacity + 1, maxStart);
+  if (first < start) start = first;
+  return start;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Preview
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The pending dialog, drawn above the tail: the question, the parsed options
+ * with their digits, and the keys that answer them. Red for a permission or
+ * question prompt, yellow for an idle one, the same severity vocabulary the web
+ * inbox uses.
+ */
+export function renderApprovalCard(
+  item: ApprovalItem,
+  width: number,
+  glyphs: TuiGlyphSet,
+  opts: TuiRenderOptions
+): string[] {
+  const paint = painterFor(opts.color);
+  const card = approvalCard(item);
+  const color = card.tone === 'err' ? SGR.red : SGR.yellow;
+  const glyph = card.tone === 'err' ? glyphs.blockedPermission : glyphs.waiting;
+  const lines: string[] = [];
+  const push = (text: string, style: string): void => {
+    lines.push(padDisplay(paint(clipStyledLine(text, width), style), width));
+  };
+
+  push(` ${glyph} ${card.title}`, color);
+  for (const detail of card.detail) push(`   ${detail}`, SGR.gray);
+  for (const option of card.options) push(`   ${option.n}. ${option.label}`, '');
+  push(` ${card.hint}`, SGR.gray);
+  return lines;
+}
+
+/** The card may take half the pane at most: the tail is why the pane exists. */
+function cardCapacity(height: number): number {
+  return Math.max(0, Math.floor((height - 1) / 2));
+}
+
+/**
+ * `name · mode · dir · state`, with the DIRECTORY absorbing the squeeze: the
+ * state word is the one fact the pane exists to confirm, so it must survive a
+ * narrow preview that a full path would push off the end.
+ */
+function previewTitle(row: TuiRow, width: number, glyphs: TuiGlyphSet): string {
+  const { session } = row;
+  const sep = ` ${glyphs.separator} `;
+  const head = ` ${rowLabel(session)}${sep}${session.mode ?? 'claude'}`;
+  const tail = `${sep}${STATE_WORDS[row.state]}`;
+  const dirBudget = width - visibleWidth(head) - visibleWidth(tail) - visibleWidth(sep);
+  const dir = session.workingDir ? truncatePathLeft(session.workingDir, Math.max(0, dirBudget), glyphs.ellipsis) : '';
+  return clipStyledLine(dir ? `${head}${sep}${dir}${tail}` : `${head}${tail}`, width);
+}
+
+function buildPreviewLines(model: TuiRenderModel, rect: TuiRect, opts: TuiRenderOptions): string[] {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const lines: string[] = [];
+  const selected = model.selectedId
+    ? (model
+        .groups()
+        .flatMap((group) => group.rows)
+        .find((row) => row.session.sessionId === model.selectedId) ?? null)
+    : null;
+
+  if (!selected) {
+    lines.push(padDisplay(paint(' no session selected', SGR.gray), rect.width));
+  } else {
+    lines.push(padDisplay(paint(previewTitle(selected, rect.width, glyphs), SGR.bold), rect.width));
+  }
+
+  const budget = cardCapacity(rect.height);
+  if (selected?.approval && budget > 0) {
+    for (const line of renderApprovalCard(selected.approval, rect.width, glyphs, opts).slice(0, budget)) {
+      lines.push(line);
+    }
+    if (lines.length < rect.height) lines.push(' '.repeat(rect.width));
+  }
+
+  const body = previewBody(model, selected, rect, opts, rect.height - lines.length);
+  for (const line of body) lines.push(line);
+  while (lines.length < rect.height) lines.push(' '.repeat(rect.width));
+  return lines.slice(0, Math.max(0, rect.height));
+}
+
+function previewBody(
+  model: TuiRenderModel,
+  selected: TuiRow | null,
+  rect: TuiRect,
+  opts: TuiRenderOptions,
+  capacity: number
+): string[] {
+  const paint = painterFor(opts.color);
+  if (capacity <= 0) return [];
+  const hint = (text: string): string[] => [padDisplay(paint(` ${text}`, SGR.gray), rect.width)];
+
+  if (!selected) return [];
+  if (model.connection === 'degraded' || model.connection === 'down') {
+    return hint('preview unavailable while the server is down');
+  }
+  const preview = model.preview;
+  if (!preview || preview.sessionId !== selected.session.sessionId) return hint('loading preview…');
+  if (preview.note) return hint(preview.note);
+  if (preview.error) return hint(preview.error);
+
+  const trimmed = [...preview.lines];
+  while (trimmed.length > 0 && trimmed[trimmed.length - 1].trim() === '') trimmed.pop();
+  if (trimmed.length === 0) return hint('(no output yet)');
+  // The tail carries the session's OWN colors, which is the point of the pane,
+  // but under NO_COLOR they must go too.
+  return trimmed
+    .slice(-capacity)
+    .map((line) => padDisplay(` ${clipStyledLine(opts.color ? line : stripStyles(line), rect.width - 1)}`, rect.width));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Chrome
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Sessions with a prompt waiting on a human, which is what the badge counts. */
+export function pendingApprovalCount(model: TuiRenderModel): number {
+  let count = 0;
+  for (const group of model.groups()) for (const row of group.rows) if (row.approval) count++;
+  return count;
+}
+
+function renderHeaderLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const { hostname, instance, version, planUsage } = model.header;
+  const facts = [
+    instance ? `${hostname ?? ''}:${instance}` : (hostname ?? ''),
+    version ? `v${version}` : '',
+    `${model.sessionCount} session${model.sessionCount === 1 ? '' : 's'}`,
+    planUsage ?? '',
+  ].filter((part) => part !== '');
+
+  const pending = pendingApprovalCount(model);
+  const badge = pending > 0 ? `${paint(`${glyphs.blockedPermission} ${pending}`, SGR.red)}  ` : '';
+  const left = ` ${paint('codeman', SGR.bold)}  ${badge}${paint(facts.join(` ${glyphs.separator} `), SGR.gray)}`;
+  const right = paint('? help  q quit ', SGR.gray);
+  const gap = layout.cols - visibleWidth(left) - visibleWidth(right);
+  if (gap < 1) return padDisplay(left, layout.cols);
+  return `${left}${' '.repeat(gap)}${right}`;
+}
+
+function renderBannerLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const [text, color] =
+    model.connection === 'degraded'
+      ? ['server not running: attach only', SGR.yellow]
+      : model.connection === 'reconnecting'
+        ? ['reconnecting to the server…', SGR.yellow]
+        : ['server unreachable', SGR.red];
+  return padDisplay(paint(` ${glyphs.blockedPermission} ${text}`, color), layout.cols);
+}
+
+const FOOTER_KEYS: Record<string, (glyphs: TuiGlyphSet) => string> = {
+  list: (g) =>
+    [
+      `${g.updown} select`,
+      `${g.enter} attach`,
+      '1-9 switch',
+      'y/n answer',
+      'p prompt',
+      'n new',
+      'x kill',
+      '/ search',
+      'g digest',
+      '? help',
+      'q quit',
+    ].join(` ${g.separator} `),
+  help: (g) => `esc ${g.separator} ? close`,
+  'confirm-kill': (g) => `y kill ${g.separator} any other key cancels`,
+  message: () => 'esc dismiss',
+  prompt: (g) => `${g.enter} send ${g.separator} esc cancel`,
+  search: (g) => `${g.updown} results ${g.separator} ${g.enter} open ${g.separator} esc close`,
+  digest: (g) => `j/k ${g.separator} ${g.updown} scroll ${g.separator} esc close`,
+  'new-session': (g) => `${g.updown} select ${g.separator} ${g.enter} choose ${g.separator} esc cancel`,
+};
+
+/**
+ * The composer's prefix. Fixed width on purpose: the terminal cursor is placed
+ * by column arithmetic (`composerCursorCell`), and a prefix that changed with
+ * the session name would move the cursor with it.
+ */
+export const COMPOSER_PREFIX = ' > ';
+
+function renderComposerLine(prompt: TuiPromptState, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const window = composerWindow(prompt.composer, Math.max(1, layout.cols - visibleWidth(COMPOSER_PREFIX)));
+  return padDisplay(`${paint(COMPOSER_PREFIX, SGR.cyan)}${window.text}`, layout.cols);
+}
+
+/**
+ * Where the terminal's own cursor belongs, or null when nothing is being typed
+ * into a single-line editor. The app shows the cursor there and hides it
+ * otherwise, because a blinking cursor parked in a dashboard reads as a bug.
+ */
+export function composerCursorCell(model: TuiRenderModel, layout: TuiLayout): { row: number; col: number } | null {
+  if (model.mode !== 'prompt' || !model.prompt || layout.footer.height <= 0) return null;
+  const prefix = visibleWidth(COMPOSER_PREFIX);
+  const window = composerWindow(model.prompt.composer, Math.max(1, layout.cols - prefix));
+  return { row: layout.footer.row, col: Math.min(layout.cols, prefix + 1 + window.cursorColumn) };
+}
+
+function renderFooterLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  if (model.mode === 'prompt' && model.prompt) return renderComposerLine(model.prompt, layout, opts);
+  const text = opts.footerKeys
+    ? opts.footerKeys.join(` ${glyphs.separator} `)
+    : (FOOTER_KEYS[model.mode] ?? FOOTER_KEYS.list)(glyphs);
+  return padDisplay(paint(clipStyledLine(` ${text}`, layout.cols), SGR.gray), layout.cols);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Overlays
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface OverlayContent {
+  title: string;
+  lines: string[];
+  /**
+   * Floor for the box's inner width. The search and digest panels are lists
+   * people scan, so they keep a stable width instead of snapping around their
+   * longest current line.
+   */
+  minWidth?: number;
+}
+
+function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [];
+  const out: string[] = [];
+  let line = '';
+  for (const word of text.split(/\s+/).filter((part) => part !== '')) {
+    const candidate = line === '' ? word : `${line} ${word}`;
+    if (visibleWidth(candidate) > width && line !== '') {
+      out.push(line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line !== '') out.push(line);
+  return out.length > 0 ? out : [''];
+}
+
+function helpLines(glyphs: TuiGlyphSet, custom?: ReadonlyArray<readonly [string, string]>): string[] {
+  const pairs: ReadonlyArray<readonly [string, string]> = custom ?? [
+    [`${glyphs.updown} / j k`, 'select'],
+    [glyphs.enter, 'attach'],
+    ['1-9', 'jump'],
+    ['y / n', 'answer the pending approval'],
+    ['p', 'send a prompt'],
+    ['n', 'new session'],
+    ['x', 'kill (typed confirmation)'],
+    ['/', 'search'],
+    ['g', 'away digest'],
+    ['?', 'this help'],
+    ['q', 'quit'],
+  ];
+  const keyWidth = Math.max(...pairs.map(([key]) => visibleWidth(key)));
+  return pairs.map(([key, description]) => `${padDisplay(key, keyWidth)}  ${description}`);
+}
+
+/** Longest item list a picker overlay shows, however tall the terminal is. */
+const PICKER_MAX_ROWS = 10;
+
+/**
+ * A picker's lines: hint, a window of items around the cursor, then the filter
+ * echo. Windowed rather than clipped, so the selected item is always visible in
+ * a long case list.
+ */
+function pickerLines(picker: TuiPickerState, glyphs: TuiGlyphSet, capacity: number): string[] {
+  const head: string[] = picker.hint ? [picker.hint, ''] : [];
+  const tail: string[] = picker.filter === undefined ? [] : ['', `filter: ${picker.filter}_`];
+  if (picker.items.length === 0) return [...head, '(nothing to choose)', ...tail];
+
+  const budget = Math.max(1, Math.min(PICKER_MAX_ROWS, capacity - head.length - tail.length));
+  const first = Math.max(0, Math.min(picker.index - Math.floor(budget / 2), picker.items.length - budget));
+  const rows = picker.items.slice(first, first + budget).map((item, i) => {
+    const marker = first + i === picker.index ? glyphs.cursor : ' '.repeat(visibleWidth(glyphs.cursor));
+    return `${marker} ${item.label}${item.detail ? `  ${item.detail}` : ''}`;
+  });
+  return [...head, ...rows, ...tail];
+}
+
+/**
+ * The `/` overlay: the query with a caret, one status line, then the results.
+ *
+ * The caret is a trailing `_` rather than the terminal's own cursor, and that is
+ * why the search keymap leaves left/right to the result list: a caret that
+ * cannot move is honest, an invisible one that can is not.
+ */
+function searchLines(state: TuiSearchState, glyphs: TuiGlyphSet, capacity: number): string[] {
+  const head = [`${composerText(state.composer)}_`];
+  if (state.note) head.push(state.note);
+  head.push('');
+
+  const budget = Math.max(1, capacity - head.length);
+  if (state.entries.length === 0) {
+    return [...head, state.status === 'searching' ? 'searching…' : '(type to search sessions, events and files)'];
+  }
+  const first = Math.max(0, Math.min(state.index - Math.floor(budget / 2), state.entries.length - budget));
+  const rows = state.entries.slice(first, first + budget).map((entry, i) => {
+    if (entry.kind === 'header') return entry.text;
+    const marker = first + i === state.index ? glyphs.cursor : ' '.repeat(visibleWidth(glyphs.cursor));
+    return `${marker} ${entry.text}${entry.detail ? `  ${entry.detail}` : ''}`;
+  });
+  return [...head, ...rows];
+}
+
+/** Lines an overlay box can show inside its border, given the body's height. */
+function overlayCapacity(height: number): number {
+  return Math.max(1, height - 2);
+}
+
+/**
+ * How many digest lines fit. Exported because the app scrolls by pages and must
+ * not scroll the last page into empty space, which needs this exact number.
+ */
+export function digestCapacity(layout: TuiLayout): number {
+  return overlayCapacity(layout.body.height);
+}
+
+function digestLines(state: TuiDigestState, capacity: number): string[] {
+  const offset = Math.min(Math.max(0, state.offset), Math.max(0, state.lines.length - 1));
+  return state.lines.slice(offset, offset + capacity);
+}
+
+function overlayContent(
+  model: TuiRenderModel,
+  opts: TuiRenderOptions,
+  width: number,
+  height: number
+): OverlayContent | null {
+  const glyphs = glyphsFor(opts.glyphs);
+  const panelWidth = Math.max(20, Math.min(width - 8, 72));
+  switch (model.mode) {
+    case 'help':
+      return { title: 'Keys', lines: helpLines(glyphs, opts.helpKeys) };
+    case 'search': {
+      if (!model.search) return null;
+      return {
+        title: 'Search',
+        lines: searchLines(model.search, glyphs, overlayCapacity(height)),
+        minWidth: panelWidth,
+      };
+    }
+    case 'digest': {
+      if (!model.digest) return null;
+      return {
+        title: model.digest.title,
+        lines: digestLines(model.digest, overlayCapacity(height)),
+        minWidth: panelWidth,
+      };
+    }
+    case 'new-session': {
+      if (!model.picker) return null;
+      return { title: model.picker.title, lines: pickerLines(model.picker, glyphs, Math.max(1, height - 2)) };
+    }
+    case 'confirm-kill': {
+      if (!model.confirm) return null;
+      return {
+        title: 'Kill session',
+        lines: [`Kill ${model.confirm.name}?`, '', 'press y to kill, any other key cancels'],
+      };
+    }
+    case 'message':
+      if (!model.message) return null;
+      return {
+        title: model.message.tone === 'err' ? 'Error' : model.message.tone === 'warn' ? 'Warning' : 'Notice',
+        lines: wrapText(model.message.text, Math.max(8, width - 8)),
+      };
+    default:
+      return null;
+  }
+}
+
+/** Paint an overlay box over the body, centered, replacing whole terminal rows. */
+function applyOverlay(lines: string[], model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): void {
+  const body = layout.body;
+  if (body.height < 3 || body.width < 12) return;
+  const content = overlayContent(model, opts, body.width, body.height);
+  if (!content) return;
+
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const maxInner = body.width - 4;
+  const visible = content.lines.slice(0, Math.max(1, body.height - 2));
+  const inner = Math.min(
+    maxInner,
+    Math.max(content.minWidth ?? 0, visibleWidth(content.title) + 2, ...visible.map((line) => visibleWidth(line)))
+  );
+  const boxWidth = inner + 4;
+  const boxHeight = visible.length + 2;
+  const left = body.col + Math.max(0, Math.floor((body.width - boxWidth) / 2));
+  const top = body.row + Math.max(0, Math.floor((body.height - boxHeight) / 2));
+
+  const titleText = ` ${content.title} `;
+  const titleFill = Math.max(0, inner + 2 - visibleWidth(titleText));
+  const boxLines = [
+    `${glyphs.boxTopLeft}${titleText}${glyphs.boxHorizontal.repeat(titleFill)}${glyphs.boxTopRight}`,
+    ...visible.map((line) => `${glyphs.boxVertical} ${padDisplay(line, inner)} ${glyphs.boxVertical}`),
+    `${glyphs.boxBottomLeft}${glyphs.boxHorizontal.repeat(inner + 2)}${glyphs.boxBottomRight}`,
+  ];
+
+  for (let i = 0; i < boxLines.length; i++) {
+    const row = top + i - 1;
+    if (row < 0 || row >= lines.length) continue;
+    lines[row] = `${' '.repeat(left - 1)}${paint(boxLines[i], SGR.cyan)}`;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frame
+// ─────────────────────────────────────────────────────────────────────────────
+
+function writeBody(lines: string[], model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): void {
+  const { list, preview, divider } = layout;
+  if (list.height <= 0) return;
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+
+  const entries = buildListEntries(model, layout, opts);
+  if (entries.length === 0) {
+    const hint = paint('No sessions. n to start one, q to quit.', SGR.gray);
+    const row = list.row + Math.floor((list.height - 1) / 2);
+    lines[row - 1] = centered(hint, layout.cols);
+    return;
+  }
+
+  const start = computeListWindow(entries, list.height, model.selectedId);
+  const previewLines = preview ? buildPreviewLines(model, preview, opts) : [];
+
+  for (let i = 0; i < list.height; i++) {
+    const left = entries[start + i]?.text ?? ' '.repeat(list.width);
+    if (!preview || !divider) {
+      lines[list.row - 1 + i] = left;
+      continue;
+    }
+    const right = previewLines[i] ?? ' '.repeat(preview.width);
+    lines[list.row - 1 + i] = `${left}${paint(glyphs.divider, SGR.gray)}${right}`;
+  }
+}
+
+/**
+ * The whole frame as one string: absolute cursor addressing per line, each line
+ * closed with an erase-to-end so a shorter line cannot leave the previous
+ * frame's tail behind.
+ */
+export function renderFrame(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const lines: string[] = new Array<string>(layout.rows).fill('');
+  lines[0] = renderHeaderLine(model, layout, opts);
+  if (layout.banner) lines[layout.banner.row - 1] = renderBannerLine(model, layout, opts);
+  writeBody(lines, model, layout, opts);
+  if (layout.footer.height > 0) lines[layout.footer.row - 1] = renderFooterLine(model, layout, opts);
+  applyOverlay(lines, model, layout, opts);
+
+  let frame = '';
+  for (let i = 0; i < lines.length; i++) {
+    frame += `\x1b[${i + 1};1H${clipStyledLine(lines[i], layout.cols)}\x1b[K`;
+  }
+  return frame;
+}

src/tui/tui-sse.ts

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Pure SSE wire parsing, event classification and reconnect math.
+ *
+ * Node has no `EventSource`, so the TUI reads `GET /api/events` as a raw stream
+ * and decodes the wire format here. Everything in this module is pure: bytes
+ * (as decoded strings) in, frames out. The socket, the timers and the backoff
+ * loop live in `tui-client.ts`.
+ *
+ * Three wire details this parser exists to get right:
+ *
+ * 1. **Frames split across chunk boundaries.** A TCP read can end anywhere,
+ *    including between the `\r` and the `\n` of a CRLF, so a lone trailing
+ *    `\r` is held back rather than treated as a line end.
+ * 2. **Comments are not frames.** The server appends a `:pppp…` padding line
+ *    after a frame while a Cloudflare tunnel is up (it flushes the proxy
+ *    buffer) and that line carries no blank line after it. Dispatch happens on
+ *    a blank line and on nothing else, so padding cannot split a frame.
+ * 3. **The keepalive is a NAMED event** (`sse:heartbeat`), because an SSE
+ *    comment is invisible to a browser `EventSource` by spec. We treat ANY
+ *    inbound bytes as liveness, comments included, which is why comments need
+ *    no representation in the returned frames.
+ *
+ * @module tui/tui-sse
+ */
+
+import {
+  ApprovalPending,
+  ApprovalResolved,
+  ApprovalUpdated,
+  Heartbeat,
+  Init,
+  MuxCreated,
+  MuxDied,
+  MuxKilled,
+  RemoteSessionDropped,
+  RemoteSessionReconnected,
+  SessionCliInfo,
+  SessionCompletion,
+  SessionCreated,
+  SessionDeleted,
+  SessionError,
+  SessionExit,
+  SessionIdle,
+  SessionInteractive,
+  SessionPinned,
+  SessionRunning,
+  SessionStatusTelemetry,
+  SessionUpdated,
+  SessionWorking,
+} from '../web/sse-events.js';
+
+/** One dispatched SSE frame. `event` defaults to `message` per the spec. */
+export interface SseFrame {
+  event: string;
+  data: string;
+  id?: string;
+  retry?: number;
+}
+
+/**
+ * Ceiling on the unterminated tail the parser will hold. The `init` frame
+ * carries the whole light state and is legitimately large, so this is not a
+ * frame-size limit but a guard against a non-SSE endpoint streaming something
+ * with no line terminators at all.
+ */
+export const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/** Incremental decoder. One instance per connection; `reset()` on reconnect. */
+export class SseFrameParser {
+  private buffer = '';
+  private eventName = '';
+  private dataLines: string[] = [];
+  private lastId: string | undefined;
+  private retry: number | undefined;
+
+  /** Decode one chunk, returning every frame it completed (possibly none). */
+  feed(chunk: string): SseFrame[] {
+    this.buffer += chunk;
+    const frames: SseFrame[] = [];
+    let start = 0;
+
+    for (let i = 0; i < this.buffer.length; i++) {
+      const ch = this.buffer[i];
+      if (ch !== '\n' && ch !== '\r') continue;
+      // A trailing CR may be the first half of a CRLF the next chunk finishes.
+      if (ch === '\r' && i === this.buffer.length - 1) break;
+      const line = this.buffer.slice(start, i);
+      if (ch === '\r' && this.buffer[i + 1] === '\n') i++;
+      start = i + 1;
+      const frame = this.consumeLine(line);
+      if (frame) frames.push(frame);
+    }
+
+    this.buffer = this.buffer.slice(start);
+    if (this.buffer.length > MAX_PENDING_BYTES) this.reset();
+    return frames;
+  }
+
+  /** Drop every partial frame. Called when a connection is torn down. */
+  reset(): void {
+    this.buffer = '';
+    this.eventName = '';
+    this.dataLines = [];
+    this.lastId = undefined;
+    this.retry = undefined;
+  }
+
+  private consumeLine(line: string): SseFrame | null {
+    if (line === '') return this.dispatch();
+    if (line.startsWith(':')) return null;
+
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? '' : line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+
+    switch (field) {
+      case 'event':
+        this.eventName = value;
+        break;
+      case 'data':
+        this.dataLines.push(value);
+        break;
+      case 'id':
+        this.lastId = value;
+        break;
+      case 'retry': {
+        const ms = Number.parseInt(value, 10);
+        if (Number.isSafeInteger(ms) && ms >= 0) this.retry = ms;
+        break;
+      }
+      default:
+        break;
+    }
+    return null;
+  }
+
+  /**
+   * A blank line ends a frame. Per the spec an empty data buffer dispatches
+   * nothing (it still clears the event name), which is what makes a bare
+   * `event:` line or a stray blank line harmless.
+   */
+  private dispatch(): SseFrame | null {
+    if (this.dataLines.length === 0) {
+      this.eventName = '';
+      return null;
+    }
+    const frame: SseFrame = {
+      event: this.eventName || 'message',
+      data: this.dataLines.join('\n'),
+    };
+    if (this.lastId !== undefined) frame.id = this.lastId;
+    if (this.retry !== undefined) frame.retry = this.retry;
+    this.eventName = '';
+    this.dataLines = [];
+    return frame;
+  }
+}
+
+/** What the app layer should do with a frame. */
+export type SseEventClass = 'init' | 'heartbeat' | 'resync' | 'approval' | 'plan-usage' | 'ignore';
+
+/**
+ * Events that change WHICH sessions exist or WHAT state they are in.
+ *
+ * The TUI never patches a single row from a payload: it re-fetches the unified
+ * list, which is the only source that also carries history rows, so this set
+ * only has to answer "is a refetch worth it". `session:terminal` is
+ * deliberately absent (it is the bulk of the stream and the preview pane pulls
+ * its own tail), as are the ralph/respawn/subagent/orchestrator families, which
+ * change nothing the dashboard draws.
+ */
+const RESYNC_EVENTS: ReadonlySet<string> = new Set<string>([
+  SessionCreated,
+  SessionUpdated,
+  SessionDeleted,
+  SessionExit,
+  SessionError,
+  SessionIdle,
+  SessionWorking,
+  SessionCompletion,
+  SessionInteractive,
+  SessionRunning,
+  SessionPinned,
+  SessionCliInfo,
+  MuxCreated,
+  MuxKilled,
+  MuxDied,
+  RemoteSessionDropped,
+  RemoteSessionReconnected,
+]);
+
+const APPROVAL_EVENTS: ReadonlySet<string> = new Set<string>([ApprovalPending, ApprovalUpdated, ApprovalResolved]);
+
+/** Which approval event this is, or null when the name is not one. */
+export function approvalEventKind(name: string): 'pending' | 'updated' | 'resolved' | null {
+  if (name === ApprovalPending) return 'pending';
+  if (name === ApprovalUpdated) return 'updated';
+  if (name === ApprovalResolved) return 'resolved';
+  return null;
+}
+
+/** Route one event name. Unknown names are ignored, never a resync. */
+export function classifySseEvent(name: string): SseEventClass {
+  if (name === Init) return 'init';
+  if (name === Heartbeat) return 'heartbeat';
+  if (APPROVAL_EVENTS.has(name)) return 'approval';
+  if (name === SessionStatusTelemetry) return 'plan-usage';
+  if (RESYNC_EVENTS.has(name)) return 'resync';
+  return 'ignore';
+}
+
+/**
+ * Silence that means the stream is dead even though the socket never errored.
+ * The server heartbeats every 15s, so three missed beats is the signal.
+ */
+export const SSE_STALE_TIMEOUT_MS = 45_000;
+
+/** Reconnect delay ceiling. A local server is back in milliseconds, not minutes. */
+export const SSE_MAX_BACKOFF_MS = 15_000;
+
+/** First reconnect delay; doubles per consecutive failure up to the ceiling. */
+export const SSE_BASE_BACKOFF_MS = 500;
+
+/**
+ * Delay before reconnect attempt `attempt` (1-based). Deterministic, with no
+ * jitter on purpose: one client talks to one loopback server, so there is no
+ * herd to spread out and a reproducible delay is testable.
+ */
+export function sseBackoffDelay(attempt: number, base = SSE_BASE_BACKOFF_MS, max = SSE_MAX_BACKOFF_MS): number {
+  const step = Math.max(1, Math.trunc(attempt));
+  const exponent = Math.min(step - 1, 30);
+  return Math.min(max, base * 2 ** exponent);
+}

src/tui/tui-types.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Shared types for the `codeman tui` pure core.
+ *
+ * The TUI is a client of the server, never a second brain: its rows are the
+ * rows `GET /api/sessions/unified` already returns (`UnifiedSessionItem`) and
+ * its blocked states are the items `GET /api/approvals` already parsed
+ * (`ApprovalItem`). Both are imported as TYPES only, so nothing here pulls the
+ * server, node-pty or the utils barrel into a CLI process.
+ *
+ * Everything in `src/tui/*` except `tui-app.ts` / `tui-client.ts` is pure:
+ * deterministic outputs from inputs, no `process.*`, no timers, no IO.
+ *
+ * @module tui/tui-types
+ */
+
+import type { UnifiedSessionItem } from '../services/unified-session-service.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type { TuiComposerState } from './tui-composer.js';
+
+/**
+ * A unified-list row plus the few live-only extras the dashboard shows.
+ *
+ * The unified list is the spine (it is the only source that carries history
+ * rows), but it has no token counters and no turn-start stamp, so the client
+ * merges those from the live session payload (`GET /api/sessions` /
+ * `session_updated` SSE) when a row is live. History rows simply lack them.
+ */
+export interface TuiSessionRow extends UnifiedSessionItem {
+  /**
+   * Wall-clock ms of the pane's last Enter (`SessionState.lastSubmitAt`). The
+   * only usable "working since" anchor: a working pane repaints about once a
+   * second, so its `lastActivityAt` is always "now".
+   */
+  lastSubmitAt?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  /**
+   * tmux session name to attach to (`codeman-<first 8 of the id>`).
+   *
+   * The unified list does not carry it (no server view merges the mux name into
+   * a row), so the app layer fills it in from the local tmux enumeration, which
+   * is also the only thing that proves the pane really exists. A row without one
+   * cannot be attached: it is either history or a direct-PTY session.
+   */
+  muxName?: string;
+}
+
+/**
+ * Row state, in the web UI's vocabulary so both surfaces read the same.
+ *
+ * There is deliberately no `error` member: an errored session is something a
+ * human has to look at, so it classifies as `waiting` and lands in NEEDS YOU
+ * rather than growing a fifth color nobody designed.
+ */
+export type TuiSessionState = 'blocked-question' | 'blocked-permission' | 'waiting' | 'working' | 'idle' | 'recent';
+
+/** The four display groups, in display order. */
+export type TuiGroupKey = 'needs-you' | 'working' | 'idle' | 'recent';
+
+/** A classified session: what the cursor moves over and the renderer paints. */
+export interface TuiRow {
+  session: TuiSessionRow;
+  state: TuiSessionState;
+  group: TuiGroupKey;
+  /** The pending prompt that blocks this session, when it has one. */
+  approval?: ApprovalItem;
+  /** Epoch ms the session entered `state`; the intra-group sort key. 0 when unknown. */
+  since: number;
+}
+
+export interface TuiGroup {
+  key: TuiGroupKey;
+  label: string;
+  rows: TuiRow[];
+}
+
+/** How the client currently sees the server. */
+export type TuiConnectionStatus = 'connected' | 'reconnecting' | 'degraded' | 'down';
+
+/** Which overlay (if any) owns the keyboard. */
+export type TuiUiMode = 'list' | 'help' | 'confirm-kill' | 'prompt' | 'search' | 'digest' | 'message' | 'new-session';
+
+/**
+ * Glyph capability tier. Detection is env-driven and therefore lives in a tiny
+ * function the app layer calls (`detectGlyphTier`); the renderer only ever
+ * takes the resolved tier as an input.
+ */
+export type TuiGlyphTier = 'nerd' | 'unicode' | 'ascii';
+
+/** Header facts, all optional: the header degrades to just the product name. */
+export interface TuiHeaderInfo {
+  hostname?: string;
+  instance?: string;
+  version?: string;
+  /** Plan-usage chip text, e.g. `5h 32% · wk 61%`. */
+  planUsage?: string;
+}
+
+/** The selected session's terminal tail, already run through `toDisplayLines()`. */
+export interface TuiPreview {
+  sessionId: string;
+  /** Display lines, oldest first. */
+  lines: string[];
+  /** Set instead of lines when the tail could not be fetched. */
+  error?: string;
+  /**
+   * Set instead of lines when there is nothing to fetch (a history row has no
+   * live buffer). Distinct from `error`: nothing failed, so it must not read
+   * like something did.
+   */
+  note?: string;
+}
+
+export interface TuiMessage {
+  text: string;
+  tone: 'info' | 'warn' | 'err';
+}
+
+/** Typed-confirmation state for `x` (kill): the user retypes the session name. */
+export interface TuiConfirmState {
+  sessionId: string;
+  name: string;
+}
+
+export interface TuiPickerItem {
+  /** What choosing this item means to the caller; never shown. */
+  id: string;
+  label: string;
+  /** Second column, dimmed (a case path, a mode description). */
+  detail?: string;
+}
+
+/**
+ * A one-column chooser drawn as an overlay (the case and mode pickers behind
+ * `n`). Items are already filtered: the app owns the unfiltered list, the
+ * renderer only paints what it is given.
+ */
+export interface TuiPickerState {
+  title: string;
+  items: TuiPickerItem[];
+  /** Index into `items`; -1 when the list is empty. */
+  index: number;
+  /** Current filter text, when the picker filters as you type. */
+  filter?: string;
+  /** One line above the list: what is being chosen, or why the list is empty. */
+  hint?: string;
+}
+
+/** The `p` composer: one line aimed at one session. */
+export interface TuiPromptState {
+  sessionId: string;
+  /** What the session is called on screen, for the footer prefix. */
+  label: string;
+  composer: TuiComposerState;
+}
+
+/**
+ * One line of the `/` overlay. Group headers are chrome (the API returns typed
+ * groups), so only `result` rows are selectable.
+ */
+export interface TuiSearchEntry {
+  kind: 'header' | 'result';
+  text: string;
+  detail?: string;
+  sessionId?: string;
+  /** The row can hand the dashboard a session that is open right now. */
+  live?: boolean;
+}
+
+export interface TuiSearchState {
+  composer: TuiComposerState;
+  /** The query `entries` answer. Lags the composer while a search is in flight. */
+  query: string;
+  entries: TuiSearchEntry[];
+  /** Index into `entries`, always a `result` row; -1 when none is selectable. */
+  index: number;
+  status: 'idle' | 'searching' | 'done' | 'error';
+  /** One line under the query: what happened, or why there is nothing. */
+  note?: string;
+}
+
+/** The `g` overlay: pre-formatted lines plus where the window starts. */
+export interface TuiDigestState {
+  title: string;
+  lines: string[];
+  offset: number;
+}
+
+/**
+ * What `renderFrame()` reads. The store implements it; a test can hand-build
+ * one, which is what keeps the renderer testable without the model.
+ */
+export interface TuiRenderModel {
+  groups(): TuiGroup[];
+  readonly selectedId: string | null;
+  readonly connection: TuiConnectionStatus;
+  readonly mode: TuiUiMode;
+  readonly header: TuiHeaderInfo;
+  readonly preview: TuiPreview | null;
+  readonly message: TuiMessage | null;
+  readonly confirm: TuiConfirmState | null;
+  /** Optional so a test can hand-build a model without one. */
+  readonly picker?: TuiPickerState | null;
+  readonly prompt?: TuiPromptState | null;
+  readonly search?: TuiSearchState | null;
+  readonly digest?: TuiDigestState | null;
+  /** Live sessions only (RECENT rows are history, not sessions you have open). */
+  readonly sessionCount: number;
+}

src/types/session.ts

@@ -500,6 +500,14 @@ export interface SessionState {
   color?: SessionColor;
   /** Flicker filter enabled (buffers output after screen clears) */
   flickerFilterEnabled?: boolean;
+  /**
+   * True while the CLI in the pane has a mouse-tracking DECSET on, as observed
+   * by the server on its way out of the stream (those sequences are stripped for
+   * claude/codex/gemini, so the browser can never see them itself). The browser
+   * hand-encodes a click report ONLY when this is true; without it, every click
+   * sent mouse reports to a CLI that never asked for them.
+   */
+  cliMouseTracking?: boolean;
   /** Claude Code CLI version (parsed from terminal, e.g., "2.1.27") */
   cliVersion?: string;
   /** Claude model in use (parsed from terminal, e.g., "Opus 4.5") */

src/types/update.ts

@@ -98,3 +98,52 @@ export interface UpdateCheckResult {
   source: 'github-api' | 'git-ls-remote' | 'none';
   error?: string;
 }
+
+/**
+ * Role of a remote in the repository-status view.
+ * - `tracking`: the current branch's `@{upstream}` remote (where `git pull` goes).
+ * - `upstream`: the canonical project (a remote named `origin`/`upstream` that is
+ *   not the tracking remote).
+ * - `other`: anything else explicitly requested via `CODEMAN_UPDATE_REMOTES`.
+ */
+export type RepoRemoteRole = 'tracking' | 'upstream' | 'other';
+
+/** A single incoming commit — present on the remote ref but not in local HEAD. */
+export interface RepoIncomingCommit {
+  /** Abbreviated SHA. */
+  sha: string;
+  /** Commit subject (first line). */
+  subject: string;
+}
+
+/** Ahead/behind + incoming summary for local HEAD vs one remote's compare ref. */
+export interface RepoRemoteStatus {
+  /** Remote name, e.g. `origin`, `bitbucket`. */
+  name: string;
+  /** Remote URL (best-effort; empty if unresolved). */
+  url: string;
+  role: RepoRemoteRole;
+  /** Ref HEAD is compared against, e.g. `origin/master`, `bitbucket/local`. */
+  compareRef: string;
+  /** Commits in local HEAD not on the remote ref (local-only / unpushed). */
+  ahead: number;
+  /** Commits on the remote ref not in local HEAD (incoming). */
+  behind: number;
+  /** Up to N most recent incoming commits (newest first). */
+  incoming: RepoIncomingCommit[];
+  /** Set when this remote could not be fetched/compared. */
+  error?: string;
+}
+
+/** Result of the repository-status check across the configured remotes. */
+export interface RepositoryStatusResult {
+  /** epoch ms of the check. */
+  checkedAt: number;
+  /** False when this is not a git install (then `remotes` is empty + `error` set). */
+  isGit: boolean;
+  /** Current running version, for display. */
+  currentVersion: string;
+  remotes: RepoRemoteStatus[];
+  /** Top-level error (e.g. not a git install, or no remotes resolved). */
+  error?: string;
+}

src/utils/antigravity-cli-resolver.ts

@@ -7,22 +7,37 @@
  * @module utils/antigravity-cli-resolver
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import {
+  createCliExecutableResolver,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from './cli-executable-resolver.js';
 
 /** Common directories where the Antigravity CLI binary may be installed */
 const ANTIGRAVITY_SEARCH_DIRS = [
   join(homedir(), '.local', 'bin'),
   join(homedir(), '.antigravity', 'bin'),
   '/usr/local/bin',
+  join(homedir(), '.bun', 'bin'),
+  join(homedir(), '.npm-global', 'bin'),
   join(homedir(), 'bin'),
 ];
 
-/** Cached directory containing the agy binary (empty string = searched but not found) */
-let _antigravityDir: string | null = null;
+const ANTIGRAVITY_NOT_FOUND =
+  'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash';
+
+function createAntigravityResolver(host?: CliResolverHost, now?: () => number) {
+  return createCliExecutableResolver({ binary: 'agy', searchDirs: ANTIGRAVITY_SEARCH_DIRS, now }, host);
+}
+
+/** Creates an isolated Antigravity wrapper around an injected resolver host and clock. */
+export function createAntigravityResolverForTest(host: CliResolverHost, now?: () => number) {
+  return createAntigravityResolver(host, now);
+}
+
+const antigravityResolver = createAntigravityResolver();
 
 /**
  * Finds the directory containing the `agy` binary.
@@ -31,30 +46,7 @@ let _antigravityDir: string | null = null;
  * @returns Directory path, or null if not found
  */
 export function resolveAntigravityDir(): string | null {
-  if (_antigravityDir !== null) return _antigravityDir || null;
-
-  try {
-    const result = execSync('which agy', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      _antigravityDir = dirname(result);
-      return _antigravityDir;
-    }
-  } catch {
-    // agy not in PATH, will check common locations
-  }
-
-  for (const dir of ANTIGRAVITY_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'agy'))) {
-      _antigravityDir = dir;
-      return _antigravityDir;
-    }
-  }
-
-  _antigravityDir = '';
-  return null;
+  return antigravityResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -63,3 +55,7 @@ export function resolveAntigravityDir(): string | null {
 export function isAntigravityAvailable(): boolean {
   return resolveAntigravityDir() !== null;
 }
+
+export function getAntigravityNotFoundMessage(): string {
+  return formatCliNotFoundMessage(ANTIGRAVITY_NOT_FOUND, antigravityResolver.diagnostics());
+}

src/utils/claude-cli-resolver.ts

@@ -8,11 +8,11 @@
  * @module utils/claude-cli-resolver
  */
 
-import { execSync, execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { delimiter, join } from 'node:path';
 import { homedir } from 'node:os';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
 
 /** Common directories where the Claude CLI binary may be installed */
 const CLAUDE_SEARCH_DIRS = [
@@ -23,8 +23,8 @@ const CLAUDE_SEARCH_DIRS = [
   join(homedir(), 'bin'),
 ];
 
-/** Cached directory containing the claude binary (empty string = searched but not found) */
-let _claudeDir: string | null = null;
+const claudeResolver = createCliExecutableResolver({ binary: 'claude', searchDirs: CLAUDE_SEARCH_DIRS });
+const CLAUDE_NOT_FOUND = 'Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash';
 
 /**
  * Returns true if the Claude CLI binary can be located (via `which` or one of
@@ -43,29 +43,11 @@ export function isClaudeAvailable(): boolean {
  * @returns Directory path, or null if not found
  */
 export function findClaudeDir(): string | null {
-  if (_claudeDir !== null) return _claudeDir || null;
+  return claudeResolver.resolve()?.directory ?? null;
+}
 
-  // Try `which` first (respects current PATH)
-  try {
-    const result = execSync('which claude', { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }).trim();
-    if (result && existsSync(result)) {
-      _claudeDir = dirname(result);
-      return _claudeDir;
-    }
-  } catch {
-    // Claude not in PATH, will check common locations
-  }
-
-  // Fallback: check common installation directories
-  for (const dir of CLAUDE_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'claude'))) {
-      _claudeDir = dir;
-      return _claudeDir;
-    }
-  }
-
-  _claudeDir = ''; // mark as searched, not found
-  return null;
+export function getClaudeNotFoundMessage(): string {
+  return formatCliNotFoundMessage(CLAUDE_NOT_FOUND, claudeResolver.diagnostics());
 }
 
 /**
@@ -99,7 +81,9 @@ export function getAugmentedPath(): string {
   const currentPath = process.env.PATH || '';
   const claudeDir = findClaudeDir();
 
-  if (claudeDir && !currentPath.split(delimiter).includes(claudeDir)) {
+  if (!claudeDir) return currentPath;
+
+  if (!currentPath.split(delimiter).includes(claudeDir)) {
     _augmentedPath = `${claudeDir}${delimiter}${currentPath}`;
     return _augmentedPath;
   }
@@ -193,6 +177,9 @@ function probeClaudeCliVersion(): string | null {
     encoding: 'utf-8',
     timeout: EXEC_TIMEOUT_MS,
     env: { ...process.env, PATH: getAugmentedPath() },
+    // execFileSync's timeout only SENDS the signal and then keeps waiting; a
+    // child that ignores SIGTERM would block the server thread permanently.
+    killSignal: 'SIGKILL',
   });
   const match = out.match(/(\d+\.\d+\.\d+)/);
   return match ? match[1] : null;

src/utils/cli-executable-resolver.ts

@@ -0,0 +1,301 @@
+/**
+ * @fileoverview Shared CLI executable resolution for the per-CLI resolvers.
+ *
+ * One lookup chain behind all six *-cli-resolver modules (claude, opencode,
+ * codex, gemini, antigravity, pi): the server process PATH first, then the
+ * CLI's common install directories in order, then — last, because it is the
+ * only step that spawns anything — an interactive login shell, which is what
+ * finds nvm/Homebrew/user-npm installs when Codeman runs as a systemd/launchd
+ * service with a minimal PATH (launchd hands a job `/usr/bin:/bin:/usr/sbin:/sbin`).
+ *
+ * Caching is asymmetric, same shape as `resolveClaudeCliVersion` in
+ * claude-cli-resolver.ts: a successful resolution is cached for the process
+ * lifetime, a MISS is negative-cached and retried only after a doubling backoff
+ * (`cliResolveRetryDelayMs`). The callers are request-facing (the per-CLI
+ * status endpoints in system-routes.ts, the availability gates in
+ * session-routes.ts, and tmux-manager's spawn path), and the login-shell probe
+ * is a SYNCHRONOUS spawn bounded by `EXEC_TIMEOUT_MS` — without the negative
+ * cache, a missing CLI re-ran the whole chain and stalled the event loop for up
+ * to 5s on every request, forever.
+ *
+ * Test hermeticity: under vitest (`process.env.VITEST`) the production host
+ * short-circuits — IO primitives that were not injected become inert stubs, so
+ * a suite can never scan the machine's PATH or spawn login shells (the same
+ * rule as `IS_TEST_MODE` in tmux-manager and the VITEST gate in
+ * `getClaudeCliVersion`). Tests opt back in through the injection hooks
+ * (`runCommand`/`isExecutableFile` fakes do no real IO by construction) or, for
+ * fixtures that need the real filesystem predicate against their own temp
+ * files, via `allowRealIoUnderVitest`.
+ *
+ * @module utils/cli-executable-resolver
+ */
+
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { basename, delimiter, dirname, isAbsolute, join } from 'node:path';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { loginShellArgs, resolveLocalShell } from './shell-resolver.js';
+
+const SAFE_BINARY_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const LOGIN_SHELL_BEGIN_MARKER = '__CODEMAN_CLI_RESOLVE_BEGIN__';
+const LOGIN_SHELL_END_MARKER = '__CODEMAN_CLI_RESOLVE_END__';
+/** Maximum rendered length of each bounded diagnostic field, excluding its label. */
+const DIAGNOSTIC_FIELD_MAX_LENGTH = 1024;
+
+/** First retry window after a full-chain resolution miss. */
+const RESOLVE_RETRY_BASE_MS = 60_000;
+/**
+ * Ceiling for the doubling backoff. Deliberately shorter than the 15min cap on
+ * the claude version probe: that one is cosmetic, while this gates the Run
+ * flow, and "installing a CLI while the server is running is picked up without
+ * a restart" should stay true within minutes.
+ */
+const RESOLVE_RETRY_MAX_MS = 5 * 60_000;
+
+/**
+ * How long to wait before re-running the resolution chain after `failures`
+ * consecutive misses: 1min, 2min, 4min… capped at 5min. Mirrors
+ * `claudeVersionRetryDelayMs` in claude-cli-resolver.ts. Exported for tests.
+ */
+export function cliResolveRetryDelayMs(failures: number): number {
+  if (failures <= 0) return 0;
+  return Math.min(RESOLVE_RETRY_BASE_MS * 2 ** (failures - 1), RESOLVE_RETRY_MAX_MS);
+}
+
+export type CliResolutionSource = 'process-path' | 'common-directory' | 'login-shell';
+
+export interface CliResolutionDiagnostics {
+  binary: string;
+  processPath: string;
+  shellPath: string;
+  shellArgs: string[];
+  searchDirs: string[];
+}
+
+export interface CliResolverHost {
+  processPath: string;
+  shellPath: string;
+  shellArgs: string[];
+  findOnProcessPath(binary: string): string | null;
+  findInLoginShell(binary: string): string | null;
+  exists(path: string): boolean;
+}
+
+export interface CandidateValidation<T> {
+  accepted: boolean;
+  metadata?: T;
+}
+
+export interface CliResolution<T = undefined> {
+  binaryPath: string;
+  directory: string;
+  source: CliResolutionSource;
+  metadata?: T;
+}
+
+export interface CliExecutableResolver<T = undefined> {
+  resolve(): CliResolution<T> | null;
+  diagnostics(): CliResolutionDiagnostics;
+}
+
+export interface CliResolverCommandOptions {
+  encoding: 'utf8';
+  timeout: number;
+  stdio: ['ignore', 'pipe', 'ignore'];
+  killSignal: 'SIGKILL';
+}
+
+export type CliResolverCommandRunner = (file: string, args: string[], options: CliResolverCommandOptions) => string;
+
+export interface ProductionCliResolverHostOptions {
+  processPath?: string;
+  shellPath?: string;
+  shellArgs?: string[];
+  runCommand?: CliResolverCommandRunner;
+  isExecutableFile?: (path: string) => boolean;
+  /**
+   * Test-only escape hatch: keep the REAL IO primitives even under vitest.
+   * For tests that exercise `isExecutableRegularFile` against their own temp
+   * fixtures. Such a test must still inject `runCommand` if it can reach the
+   * login-shell step, or it would spawn a real interactive shell.
+   */
+  allowRealIoUnderVitest?: boolean;
+}
+
+function isExecutableRegularFile(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseLoginShellResult(output: string, binary: string): string | null {
+  const lines = output.split(/\r?\n/).map((line) => line.trim());
+  const begin = lines.indexOf(LOGIN_SHELL_BEGIN_MARKER);
+  if (begin === -1) return null;
+  const end = lines.indexOf(LOGIN_SHELL_END_MARKER, begin + 1);
+  if (end === -1) return null;
+
+  for (const candidate of lines.slice(begin + 1, end)) {
+    if (isAbsolute(candidate) && basename(candidate) === binary) return candidate;
+  }
+  return null;
+}
+
+function loginShellCommand(binary: string): string {
+  return [
+    `printf '%s\\n' '${LOGIN_SHELL_BEGIN_MARKER}'`,
+    `command -v -- ${binary}`,
+    `printf '%s\\n' '${LOGIN_SHELL_END_MARKER}'`,
+  ].join('; ');
+}
+
+export function createProductionCliResolverHost(options: ProductionCliResolverHostOptions = {}): CliResolverHost {
+  const shellPath = options.shellPath ?? resolveLocalShell();
+  const shellArgs = options.shellArgs ?? loginShellArgs(shellPath).trim().split(/\s+/).filter(Boolean);
+  const processPath = options.processPath ?? process.env.PATH ?? '';
+  // Hermeticity gate (see @fileoverview): under vitest, any IO primitive the
+  // caller did not inject is replaced by an inert stub. The suites must never
+  // depend on — or execute — whatever happens to be installed on the machine
+  // running them, and route tests hitting the per-CLI status endpoints would
+  // otherwise scan the real PATH and spawn real login shells on CI.
+  const inert = Boolean(process.env.VITEST) && options.allowRealIoUnderVitest !== true;
+  const isExecutableFile = options.isExecutableFile ?? (inert ? () => false : isExecutableRegularFile);
+  const runCommand: CliResolverCommandRunner =
+    options.runCommand ?? (inert ? () => '' : (file, args, commandOptions) => execFileSync(file, args, commandOptions));
+  const run = (file: string, args: string[]): string => {
+    try {
+      return runCommand(file, args, {
+        encoding: 'utf8',
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        // SIGKILL is load-bearing: execFileSync's `timeout` only SENDS the kill
+        // signal and then keeps waiting for the child to exit. Interactive bash
+        // ignores SIGTERM (the default), so a login shell stuck in a blocking
+        // .bash_profile would survive the timeout and block the server forever.
+        killSignal: 'SIGKILL',
+      });
+    } catch {
+      return '';
+    }
+  };
+
+  return {
+    processPath,
+    shellPath,
+    shellArgs: [...shellArgs],
+    findOnProcessPath: (binary) => {
+      if (!SAFE_BINARY_NAME.test(binary)) return null;
+      for (const directory of processPath.split(delimiter).filter(Boolean)) {
+        const candidate = join(directory, binary);
+        if (isAbsolute(candidate) && isExecutableFile(candidate)) return candidate;
+      }
+      return null;
+    },
+    findInLoginShell: (binary) => {
+      if (!SAFE_BINARY_NAME.test(binary)) return null;
+      const candidate = parseLoginShellResult(run(shellPath, [...shellArgs, '-c', loginShellCommand(binary)]), binary);
+      return candidate && isExecutableFile(candidate) ? candidate : null;
+    },
+    exists: isExecutableFile,
+  };
+}
+
+export function createCliExecutableResolver<T = undefined>(
+  options: {
+    binary: string;
+    searchDirs: string[];
+    validateCandidate?: (path: string) => CandidateValidation<T>;
+    /** Clock injection for tests driving the failure backoff. Defaults to `Date.now`. */
+    now?: () => number;
+  },
+  host: CliResolverHost = createProductionCliResolverHost()
+): CliExecutableResolver<T> {
+  if (!SAFE_BINARY_NAME.test(options.binary)) {
+    throw new Error(`Unsafe CLI binary name: ${options.binary}`);
+  }
+
+  const now = options.now ?? Date.now;
+  /** Successful resolution, cached for the process lifetime. */
+  let cached: CliResolution<T> | null = null;
+  /** Consecutive full-chain misses (drives the retry backoff). */
+  let failures = 0;
+  /** Timestamp of the most recent miss. */
+  let lastFailureAt = 0;
+  const accept = (path: string | null, source: CliResolutionSource): CliResolution<T> | null => {
+    if (!path || !isAbsolute(path) || !host.exists(path)) return null;
+    const validation = options.validateCandidate?.(path) ?? ({ accepted: true } as CandidateValidation<T>);
+    if (!validation.accepted) return null;
+    return {
+      binaryPath: path,
+      directory: dirname(path),
+      source,
+      metadata: validation.metadata,
+    };
+  };
+
+  return {
+    resolve() {
+      if (cached) return cached;
+      // Negative cache: a miss is remembered and the chain — whose login-shell
+      // tail is a synchronous 5s-bounded spawn — is not re-run until the
+      // backoff elapses. Without this, every status poll and Run click against
+      // a missing CLI froze the event loop for the full probe, forever.
+      if (failures > 0 && now() - lastFailureAt < cliResolveRetryDelayMs(failures)) return null;
+
+      cached = accept(host.findOnProcessPath(options.binary), 'process-path');
+      if (!cached) {
+        for (const dir of options.searchDirs) {
+          cached = accept(join(dir, options.binary), 'common-directory');
+          if (cached) break;
+        }
+      }
+      if (!cached) {
+        cached = accept(host.findInLoginShell(options.binary), 'login-shell');
+      }
+
+      if (cached) {
+        failures = 0;
+        lastFailureAt = 0;
+        return cached;
+      }
+      failures += 1;
+      lastFailureAt = now();
+      return null;
+    },
+    diagnostics: () => ({
+      binary: options.binary,
+      processPath: host.processPath,
+      shellPath: host.shellPath,
+      shellArgs: [...host.shellArgs],
+      searchDirs: [...options.searchDirs],
+    }),
+  };
+}
+
+function sanitizeDiagnosticField(value: string, emptyMarker: string): string {
+  const flattened = Array.from(value, (character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    const isControl = codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+    return isControl || codePoint === 0x2028 || codePoint === 0x2029 ? ' ' : character;
+  })
+    .join('')
+    .replace(/ +/g, ' ')
+    .trim();
+  if (!flattened) return emptyMarker;
+  if (flattened.length <= DIAGNOSTIC_FIELD_MAX_LENGTH) return flattened;
+  return `${flattened.slice(0, DIAGNOSTIC_FIELD_MAX_LENGTH - 1)}…`;
+}
+
+export function formatCliNotFoundMessage(base: string, diagnostics: CliResolutionDiagnostics): string {
+  const processPath = sanitizeDiagnosticField(diagnostics.processPath, '(empty)');
+  const shell = sanitizeDiagnosticField(
+    [diagnostics.shellPath, ...diagnostics.shellArgs].filter(Boolean).join(' '),
+    '(none)'
+  );
+  const dirs = sanitizeDiagnosticField(diagnostics.searchDirs.join(', '), '(none)');
+  return `${base}\nServer PATH: ${processPath}\nLogin shell: ${shell}\nChecked directories: ${dirs}`;
+}

src/utils/codex-cli-resolver.ts

@@ -7,11 +7,9 @@
  * @module utils/codex-cli-resolver
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
 
 /** Common directories where the Codex CLI binary may be installed */
 const CODEX_SEARCH_DIRS = [
@@ -23,8 +21,8 @@ const CODEX_SEARCH_DIRS = [
   join(homedir(), 'bin'), // User bin
 ];
 
-/** Cached directory containing the codex binary (empty string = searched but not found) */
-let _codexDir: string | null = null;
+const codexResolver = createCliExecutableResolver({ binary: 'codex', searchDirs: CODEX_SEARCH_DIRS });
+const CODEX_NOT_FOUND = 'Codex CLI not found. Install with: npm install -g @openai/codex';
 
 /**
  * Finds the directory containing the `codex` binary.
@@ -34,31 +32,7 @@ let _codexDir: string | null = null;
  * @returns Directory path, or null if not found
  */
 export function resolveCodexDir(): string | null {
-  if (_codexDir !== null) return _codexDir || null;
-
-  // Try `which` first (respects current PATH)
-  try {
-    const result = execSync('which codex', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      _codexDir = dirname(result);
-      return _codexDir;
-    }
-  } catch {
-    // Codex not in PATH, will check common locations
-  }
-
-  for (const dir of CODEX_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'codex'))) {
-      _codexDir = dir;
-      return _codexDir;
-    }
-  }
-
-  _codexDir = ''; // mark as searched, not found
-  return null;
+  return codexResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -67,3 +41,7 @@ export function resolveCodexDir(): string | null {
 export function isCodexAvailable(): boolean {
   return resolveCodexDir() !== null;
 }
+
+export function getCodexNotFoundMessage(): string {
+  return formatCliNotFoundMessage(CODEX_NOT_FOUND, codexResolver.diagnostics());
+}

src/utils/dependency-report.ts

@@ -1,17 +1,50 @@
 /**
  * @fileoverview Renders ToolResult[] from the dependency checker into a
  * human-readable grouped table or JSON, and computes the process exit code.
- * Plain text only (no color) so output is stable and snapshot-friendly; the
- * CLI layer may colorize.
+ * Plain text by default (no color) so output is stable and snapshot-friendly;
+ * the CLI layer passes a `ReportStyle` to paint it (see `cli.ts`, `doctor`).
+ *
+ * Column widths are measured, not hardcoded: "Antigravity CLI" is 15 characters
+ * and the old `padEnd(14)` pushed its whole row one column right.
  *
  * @module utils/dependency-report
  */
 
+import { columnWidths, padStyled } from '../cli-style.js';
 import type { ProbeEnvironment, ToolCategory } from '../config/dependency-registry.js';
 import type { ToolResult, ToolStatus } from './dependency-checker.js';
 
 const CATEGORY_ORDER: ToolCategory[] = ['core', 'office', 'other'];
 
+/**
+ * Paint hooks for the CLI layer. Every hook is identity by default, so this
+ * module never decides anything about color and its output stays byte-stable
+ * for tests.
+ */
+export interface ReportStyle {
+  title(text: string): string;
+  heading(text: string): string;
+  glyph(result: ToolResult, glyph: string): string;
+  label(text: string): string;
+  status(result: ToolResult, text: string): string;
+  path(text: string): string;
+  meta(text: string): string;
+  summary(text: string): string;
+}
+
+const identity = (text: string): string => text;
+
+const PLAIN_STYLE: ReportStyle = {
+  title: identity,
+  heading: identity,
+  glyph: (_result, glyph) => glyph,
+  label: identity,
+  status: (_result, text) => text,
+  path: identity,
+  meta: identity,
+  summary: identity,
+};
+
 function glyph(r: ToolResult): string {
   if (r.status === 'ok') return '✓';
   if (r.status === 'skipped') return '○';
@@ -33,24 +66,34 @@ export function computeExitCode(results: ToolResult[]): number {
   return failed ? 1 : 0;
 }
 
-export function renderTable(results: ToolResult[], environment: ProbeEnvironment): string {
-  const lines: string[] = [`Codeman dependency check — ${environment}`, ''];
+export function renderTable(
+  results: ToolResult[],
+  environment: ProbeEnvironment,
+  style: ReportStyle = PLAIN_STYLE
+): string {
+  // Widths are taken across ALL categories so the groups line up with each other.
+  const [labelWidth, statusWidth] = columnWidths(results.map((r) => [r.label, statusText(r)]));
+  const lines: string[] = [style.title(`Codeman dependency check — ${environment}`), ''];
   for (const category of CATEGORY_ORDER) {
     const rows = results.filter((r) => r.category === category);
     if (rows.length === 0) continue;
-    lines.push(category.toUpperCase());
+    lines.push(style.heading(category.toUpperCase()));
     for (const r of rows) {
-      const detail = r.path ? `  ${r.path}` : '';
-      lines.push(`  ${glyph(r)} ${r.label.padEnd(14)} ${statusText(r).padEnd(22)}${detail}`);
-      if (r.usedBy.length) lines.push(`        used by: ${r.usedBy.join(', ')}`);
-      if (r.installHint) lines.push(`        install: ${r.installHint}`);
+      const label = padStyled(r.label, labelWidth ?? 0, style.label);
+      const status = padStyled(statusText(r), statusWidth ?? 0, (text) => style.status(r, text));
+      const detail = r.path ? `  ${style.path(r.path)}` : '';
+      lines.push(`  ${style.glyph(r, glyph(r))} ${label} ${status}${detail}`.trimEnd());
+      if (r.usedBy.length) lines.push(style.meta(`        used by: ${r.usedBy.join(', ')}`));
+      if (r.installHint) lines.push(style.meta(`        install: ${r.installHint}`));
     }
     lines.push('');
   }
   const ok = results.filter((r) => r.status === 'ok').length;
   const requiredMissing = results.filter((r) => r.required && r.status !== 'ok' && r.status !== 'skipped').length;
   const optionalMissing = results.filter((r) => !r.required && r.status === 'missing').length;
-  lines.push(`Summary: ${ok} ok · ${requiredMissing} required missing · ${optionalMissing} optional missing`);
+  lines.push(
+    style.summary(`Summary: ${ok} ok · ${requiredMissing} required missing · ${optionalMissing} optional missing`)
+  );
   return lines.join('\n');
 }
 

src/utils/gemini-cli-resolver.ts

@@ -7,11 +7,9 @@
  * @module utils/gemini-cli-resolver
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
 
 /** Common directories where the Gemini CLI binary may be installed */
 const GEMINI_SEARCH_DIRS = [
@@ -23,8 +21,8 @@ const GEMINI_SEARCH_DIRS = [
   join(homedir(), 'bin'),
 ];
 
-/** Cached directory containing the gemini binary (empty string = searched but not found) */
-let _geminiDir: string | null = null;
+const geminiResolver = createCliExecutableResolver({ binary: 'gemini', searchDirs: GEMINI_SEARCH_DIRS });
+const GEMINI_NOT_FOUND = 'Gemini CLI not found. Install with: npm install -g @google/gemini-cli';
 
 /**
  * Finds the directory containing the `gemini` binary.
@@ -33,30 +31,7 @@ let _geminiDir: string | null = null;
  * @returns Directory path, or null if not found
  */
 export function resolveGeminiDir(): string | null {
-  if (_geminiDir !== null) return _geminiDir || null;
-
-  try {
-    const result = execSync('which gemini', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      _geminiDir = dirname(result);
-      return _geminiDir;
-    }
-  } catch {
-    // Gemini not in PATH, will check common locations
-  }
-
-  for (const dir of GEMINI_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'gemini'))) {
-      _geminiDir = dir;
-      return _geminiDir;
-    }
-  }
-
-  _geminiDir = '';
-  return null;
+  return geminiResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -65,3 +40,7 @@ export function resolveGeminiDir(): string | null {
 export function isGeminiAvailable(): boolean {
   return resolveGeminiDir() !== null;
 }
+
+export function getGeminiNotFoundMessage(): string {
+  return formatCliNotFoundMessage(GEMINI_NOT_FOUND, geminiResolver.diagnostics());
+}

src/utils/index.ts

@@ -28,12 +28,22 @@ export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-si
 export { assertNever } from './type-safety.js';
 export { wrapWithNice } from './nice-wrapper.js';
 export { resolveLocalShell, loginShellArgs } from './shell-resolver.js';
-export { findClaudeDir, getAugmentedPath, getClaudeCliVersion, getClaudeBinaryPath } from './claude-cli-resolver.js';
+export {
+  findClaudeDir,
+  getAugmentedPath,
+  getClaudeCliVersion,
+  getClaudeBinaryPath,
+  getClaudeNotFoundMessage,
+} from './claude-cli-resolver.js';
 export { spawnPtyWithHelperRepair } from './node-pty-repair.js';
-export { resolveOpenCodeDir } from './opencode-cli-resolver.js';
-export { resolveCodexDir, isCodexAvailable } from './codex-cli-resolver.js';
-export { resolveGeminiDir, isGeminiAvailable } from './gemini-cli-resolver.js';
-export { resolveAntigravityDir, isAntigravityAvailable } from './antigravity-cli-resolver.js';
-export { resolvePiDir, isPiAvailable, getPiCliVersion } from './pi-cli-resolver.js';
+export { resolveOpenCodeDir, getOpenCodeNotFoundMessage } from './opencode-cli-resolver.js';
+export { resolveCodexDir, isCodexAvailable, getCodexNotFoundMessage } from './codex-cli-resolver.js';
+export { resolveGeminiDir, isGeminiAvailable, getGeminiNotFoundMessage } from './gemini-cli-resolver.js';
+export {
+  resolveAntigravityDir,
+  isAntigravityAvailable,
+  getAntigravityNotFoundMessage,
+} from './antigravity-cli-resolver.js';
+export { resolvePiDir, isPiAvailable, getPiCliVersion, getPiNotFoundMessage } from './pi-cli-resolver.js';
 export { compileFileQuery, matchFileQuery } from './file-query.js';
 export type { FileQueryMatcher } from './file-query.js';

src/utils/opencode-cli-resolver.ts

@@ -7,11 +7,9 @@
  * @module utils/opencode-cli-resolver
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
 
 /** Common directories where the OpenCode CLI binary may be installed */
 const OPENCODE_SEARCH_DIRS = [
@@ -24,8 +22,8 @@ const OPENCODE_SEARCH_DIRS = [
   join(homedir(), 'bin'), // User bin
 ];
 
-/** Cached directory containing the opencode binary (empty string = searched but not found) */
-let _openCodeDir: string | null = null;
+const openCodeResolver = createCliExecutableResolver({ binary: 'opencode', searchDirs: OPENCODE_SEARCH_DIRS });
+const OPENCODE_NOT_FOUND = 'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash';
 
 /**
  * Finds the directory containing the `opencode` binary.
@@ -35,32 +33,7 @@ let _openCodeDir: string | null = null;
  * @returns Directory path, or null if not found
  */
 export function resolveOpenCodeDir(): string | null {
-  if (_openCodeDir !== null) return _openCodeDir || null;
-
-  // Try `which` first (respects current PATH)
-  try {
-    const result = execSync('which opencode', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      _openCodeDir = dirname(result);
-      return _openCodeDir;
-    }
-  } catch {
-    // OpenCode not in PATH, will check common locations
-  }
-
-  // Fallback: check common installation directories
-  for (const dir of OPENCODE_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'opencode'))) {
-      _openCodeDir = dir;
-      return _openCodeDir;
-    }
-  }
-
-  _openCodeDir = ''; // mark as searched, not found
-  return null;
+  return openCodeResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -69,3 +42,7 @@ export function resolveOpenCodeDir(): string | null {
 export function isOpenCodeAvailable(): boolean {
   return resolveOpenCodeDir() !== null;
 }
+
+export function getOpenCodeNotFoundMessage(): string {
+  return formatCliNotFoundMessage(OPENCODE_NOT_FOUND, openCodeResolver.diagnostics());
+}

src/utils/pi-cli-resolver.ts

@@ -15,11 +15,15 @@
  * @module utils/pi-cli-resolver
  */
 
-import { execFileSync, execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import {
+  createCliExecutableResolver,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from './cli-executable-resolver.js';
 
 /** Common directories where the Pi CLI binary may be installed */
 const PI_SEARCH_DIRS = [
@@ -45,10 +49,7 @@ const PI_SEARCH_DIRS = [
  */
 export const PI_VERSION_REGEX = /(?:^|\s)(\d+\.\d+\.\d+)/;
 
-/** Cached directory containing the pi binary (empty string = searched but not found) */
-let _piDir: string | null = null;
-/** Cached version string reported by the resolved binary (empty string = probed, unusable) */
-let _piVersion: string | null = null;
+const PI_NOT_FOUND = 'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent';
 
 /**
  * Run `pi --version` on a candidate path and return the trimmed version when it
@@ -57,7 +58,12 @@ let _piVersion: string | null = null;
  * (which is how an unrelated `pi` on PATH gets rejected).
  *
  * Never runs under vitest: the suites must stay hermetic and must not depend on
- * whether the dev box happens to have pi installed.
+ * whether the dev box happens to have pi installed — and since `pi` is a short
+ * GENERIC name, this probe would EXECUTE whatever binary of that name the
+ * machine carries. The shared resolver host is already inert under vitest, so
+ * this gate is defense in depth for any opted-in host that still carries the
+ * default probe; tests drive resolution via `createPiResolverForTest`, whose
+ * injected probe bypasses it. Pinned by test/pi-cli-resolver.test.ts.
  */
 function probePiVersion(binPath: string): string | null {
   if (process.env.VITEST) return null;
@@ -66,6 +72,9 @@ function probePiVersion(binPath: string): string | null {
       encoding: 'utf-8',
       timeout: EXEC_TIMEOUT_MS,
       stdio: ['ignore', 'pipe', 'ignore'],
+      // A stuck or hostile `pi` that ignores SIGTERM would survive the timeout
+      // and block the server (execFileSync keeps waiting after the signal).
+      killSignal: 'SIGKILL',
     }).trim();
     // Upstream prints a bare version today; tolerate a `pi 0.84.1` style prefix too.
     const candidate = PI_VERSION_REGEX.exec(out)?.[1];
@@ -77,6 +86,34 @@ function probePiVersion(binPath: string): string | null {
   return null;
 }
 
+type PiVersionProbe = (binPath: string) => string | null;
+
+function createPiResolver(host?: CliResolverHost, versionProbe: PiVersionProbe = probePiVersion, now?: () => number) {
+  return createCliExecutableResolver<string>(
+    {
+      binary: 'pi',
+      searchDirs: PI_SEARCH_DIRS,
+      validateCandidate: (binPath) => {
+        const version = versionProbe(binPath);
+        return version ? { accepted: true, metadata: version } : { accepted: false };
+      },
+      now,
+    },
+    host
+  );
+}
+
+/**
+ * Creates an isolated Pi wrapper around an injected host, version probe and
+ * clock. Omitting `versionProbe` keeps the ambient (VITEST-gated) probe, which
+ * is exactly what the hermeticity test exercises.
+ */
+export function createPiResolverForTest(host: CliResolverHost, versionProbe?: PiVersionProbe, now?: () => number) {
+  return createPiResolver(host, versionProbe ?? probePiVersion, now);
+}
+
+const piResolver = createPiResolver();
+
 /**
  * Finds the directory containing a verified `pi` binary.
  * Checks `which pi` first, then falls back to common install locations. Every
@@ -86,46 +123,7 @@ function probePiVersion(binPath: string): string | null {
  * @returns Directory path, or null if not found
  */
 export function resolvePiDir(): string | null {
-  if (_piDir !== null) return _piDir || null;
-
-  const accept = (binPath: string): string | null => {
-    // Under vitest the probe never runs, so existence alone decides (keeps the
-    // suites hermetic and matches how the sibling resolvers behave there).
-    if (process.env.VITEST) {
-      _piDir = dirname(binPath);
-      _piVersion = '';
-      return _piDir;
-    }
-    const version = probePiVersion(binPath);
-    if (!version) return null;
-    _piDir = dirname(binPath);
-    _piVersion = version;
-    return _piDir;
-  };
-
-  try {
-    const result = execSync('which pi', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      const dir = accept(result);
-      if (dir) return dir;
-    }
-  } catch {
-    // pi not in PATH, will check common locations
-  }
-
-  for (const dir of PI_SEARCH_DIRS) {
-    const binPath = join(dir, 'pi');
-    if (!existsSync(binPath)) continue;
-    const accepted = accept(binPath);
-    if (accepted) return accepted;
-  }
-
-  _piDir = '';
-  _piVersion = '';
-  return null;
+  return piResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -135,12 +133,14 @@ export function isPiAvailable(): boolean {
   return resolvePiDir() !== null;
 }
 
+export function getPiNotFoundMessage(): string {
+  return formatCliNotFoundMessage(PI_NOT_FOUND, piResolver.diagnostics());
+}
+
 /**
- * Version reported by the resolved `pi` binary, or null when pi is unavailable
- * (or when the probe was skipped, i.e. under vitest). Surfaced through
- * `GET /api/pi/status` so a misresolution is diagnosable from the UI.
+ * Version reported by the resolved `pi` binary, or null when pi is unavailable.
+ * Surfaced through `GET /api/pi/status` so a misresolution is diagnosable from the UI.
  */
 export function getPiCliVersion(): string | null {
-  resolvePiDir();
-  return _piVersion || null;
+  return piResolver.resolve()?.metadata ?? null;
 }

src/web/approval-inbox.ts

@@ -22,14 +22,14 @@
  * - Acknowledgement (`acknowledge()`, idle items only) is NOT resolution: the
  *   item stays pending, it just stops arming the tab alert on every client.
  *
- * @dependencies utils (stripAnsi)
+ * @dependencies utils (stripAnsi, CLAUDE_WORKING_LINE_PATTERN)
  * @consumedby web/routes/hook-event-routes (notePrompt/resolve), web/routes/approval-routes,
  *   web/session-listener-wiring (working/exit resolution), web/server (emit callbacks + stop)
  *
  * @module web/approval-inbox
  */
 
-import { stripAnsi } from '../utils/index.js';
+import { stripAnsi, CLAUDE_WORKING_LINE_PATTERN } from '../utils/index.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -106,6 +106,12 @@ const ITEM_TTL_MS = 12 * 60 * 60 * 1000;
  * single delayed re-capture picks up the frame the immediate capture missed.
  */
 const RECAPTURE_DELAY_MS = 600;
+/**
+ * Delayed staleness pass for the late-hook case (see notePrompt). Comfortably
+ * clear of RECAPTURE_DELAY_MS so a dialog Ink has not painted yet is never
+ * mistaken for one that is gone.
+ */
+const STALE_CHECK_DELAY_MS = 3000;
 /** Context kept per item: enough for a dialog plus a few lines above it. */
 const MAX_CONTEXT_CHARS = 4000;
 const MAX_CONTEXT_LINES = 30;
@@ -195,7 +201,8 @@ export function parseDialogOptions(context: string | undefined): ApprovalOption[
 export class ApprovalInbox {
   /** Keyed by sessionId; the one-active-item-per-session invariant lives here. */
   private items = new Map<string, ApprovalItem>();
-  private recaptureTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Post-capture timers per item id (re-capture + the delayed staleness check). */
+  private itemTimers = new Map<string, ReturnType<typeof setTimeout>[]>();
   /** Capture callbacks kept for answer-time re-verification; dropped on remove. */
   private captures = new Map<string, () => string | null>();
   private seq = 0;
@@ -229,31 +236,55 @@ export class ApprovalInbox {
     if (args.capture) this.captures.set(args.sessionId, args.capture);
     this.onPending?.(item);
     if (args.capture && !this.stopped) {
-      const timer = setTimeout(() => {
-        this.recaptureTimers.delete(item.id);
-        // Only update the item if it is still the live one for the session.
-        if (this.items.get(args.sessionId)?.id !== item.id) return;
+      // Pass 1 (600ms): enrich the card with the painted frame.
+      this.scheduleForItem(item, RECAPTURE_DELAY_MS, () => {
         this.applyCapture(item, args.capture);
         this.onUpdated?.(item);
-      }, RECAPTURE_DELAY_MS);
-      this.recaptureTimers.set(item.id, timer);
+      });
+      // Pass 2: the late-hook staleness check. Claude Code fires the
+      // Notification behind the dialog, so a prompt answered before the hook
+      // lands creates an item for a dialog that is ALREADY gone: nothing ever
+      // parsed, so the "options vanished" test can never fire, `stop` may have
+      // gone by already, and the red alert then outlived reloads until the 12h
+      // TTL. This pass re-reads the pane and resolves when the frame proves no
+      // dialog is up. Deliberately LATER than the re-capture, whose whole
+      // reason for existing is that Ink may not have painted the dialog yet:
+      // resolving inside that window could clear the alert for a dialog that
+      // was about to appear.
+      this.scheduleForItem(item, STALE_CHECK_DELAY_MS, () => {
+        this.verifyStillAnswerable(item.id);
+      });
     }
     return item;
   }
 
   /**
    * Answer-time guard: re-capture the pane and check the dialog is still on
-   * screen before keystrokes are sent at it. Only conclusive when the ORIGINAL
-   * frame parsed options: if a fresh capture then parses none, the dialog is
-   * gone (answered in the terminal moments ago), so the item resolves and the
-   * answer must be refused, because the digit would land in whatever now has
-   * focus. Unparseable-from-the-start items stay answerable (approve/deny
-   * only), same risk the terminal user already carries.
+   * screen before keystrokes are sent at it. If the dialog is gone (answered in
+   * the terminal moments ago) the item resolves and the answer is refused,
+   * because the digit would land in whatever now has focus.
+   *
+   * A fresh frame that parses NO options is conclusive in two cases, and only
+   * those; anything else stays answerable, so an unreadable capture keeps the
+   * alert rather than losing a live dialog:
+   *
+   * 1. The item HAD parsed options. They cannot vanish while the dialog is up.
+   * 2. The frame shows Claude actively running a turn. A modal dialog BLOCKS
+   *    the turn, so a working line and a dialog cannot coexist — measured on
+   *    v2.1.237: a live-dialog frame carries neither the `… (13s` timer nor
+   *    even the `esc to interrupt` footer, which the dialog replaces with
+   *    `Enter to select · ↑/↓ to navigate · Esc to cancel`.
+   *
+   * Case 2 is what closes the late-hook hole. Claude Code fires the
+   * Notification behind the dialog, so a prompt answered before the hook lands
+   * produces an item whose FIRST capture already has no dialog in it — never
+   * parsed, so case 1 can never fire, and the red alert then outlived even
+   * `stop` (which had already fired) and survived reloads until the 12h TTL.
    */
   verifyStillAnswerable(id: string): boolean {
     const item = this.getById(id);
     if (!item) return false;
-    if (item.kind === 'idle' || !item.options) return true;
+    if (item.kind === 'idle') return true;
     const capture = this.captures.get(item.sessionId);
     if (!capture) return true;
     let raw: string | null = null;
@@ -266,14 +297,39 @@ export class ApprovalInbox {
     if (!context) return true;
     const options = parseDialogOptions(context);
     if (!options) {
-      this.remove(item, 'resolved_in_terminal');
-      return false;
+      if (item.options || CLAUDE_WORKING_LINE_PATTERN.test(context)) {
+        this.remove(item, 'resolved_in_terminal');
+        return false;
+      }
+      return true; // never parsed and the pane is not visibly working: unreadable, not gone
     }
     item.context = context;
     item.options = options;
     return true;
   }
 
+  /**
+   * "This session's pane started moving again": re-verify its pending DIALOG
+   * item against the screen and resolve it if the dialog is gone.
+   *
+   * The staleness check itself lived only in `GET /api/approvals`, which
+   * nothing calls while a page is open (`seedApprovals()` runs on init and
+   * reconnect), so a dialog answered in the terminal kept its red tab alert for
+   * the whole rest of the turn. The `working` signal is exactly the moment an
+   * answer lands, and routing it through `verifyStillAnswerable` is what makes
+   * it safe to act on for a permission/question item: `working` is heuristic
+   * and can flap, but it only decides WHEN to look — the pane decides the
+   * outcome, and an unreadable capture keeps the alert.
+   *
+   * Cheap by construction: a Map miss unless a dialog item is actually pending,
+   * and the item is gone after the first successful resolve.
+   */
+  resolveIfDialogGone(sessionId: string): void {
+    const item = this.getForSession(sessionId);
+    if (!item || item.kind === 'idle') return;
+    this.verifyStillAnswerable(item.id);
+  }
+
   /** Pending item for a session, TTL-checked. */
   getForSession(sessionId: string): ApprovalItem | undefined {
     const item = this.items.get(sessionId);
@@ -359,12 +415,27 @@ export class ApprovalInbox {
   /** Clear all timers (shutdown/tests). Items become inert; no events fire after this. */
   stop(): void {
     this.stopped = true;
-    for (const timer of this.recaptureTimers.values()) clearTimeout(timer);
-    this.recaptureTimers.clear();
+    for (const timers of this.itemTimers.values()) for (const timer of timers) clearTimeout(timer);
+    this.itemTimers.clear();
     this.items.clear();
     this.captures.clear();
   }
 
+  /**
+   * Run `fn` after `delayMs` if the item is still the live one for its session,
+   * tracking the timer so `remove()`/`stop()` can cancel it.
+   */
+  private scheduleForItem(item: ApprovalItem, delayMs: number, fn: () => void): void {
+    const timer = setTimeout(() => {
+      const timers = this.itemTimers.get(item.id)?.filter((t) => t !== timer) ?? [];
+      if (timers.length > 0) this.itemTimers.set(item.id, timers);
+      else this.itemTimers.delete(item.id);
+      if (this.items.get(item.sessionId)?.id !== item.id) return;
+      fn();
+    }, delayMs);
+    this.itemTimers.set(item.id, [...(this.itemTimers.get(item.id) ?? []), timer]);
+  }
+
   private applyCapture(item: ApprovalItem, capture?: () => string | null): void {
     if (!capture) return;
     let raw: string | null = null;
@@ -377,17 +448,30 @@ export class ApprovalInbox {
     if (!context) return;
     item.context = context;
     // Idle prompts are not dialogs; never offer digit answers for them.
-    if (item.kind !== 'idle') item.options = parseDialogOptions(context);
+    if (item.kind === 'idle') return;
+    const options = parseDialogOptions(context);
+    // ⚠️ ADD-ONLY: a re-capture that parses NOTHING must never erase options a
+    // previous capture found. Claude Code delays the Notification hook behind
+    // the dialog (measured 6s here, up to ~30s), so the 600ms re-capture very
+    // often lands AFTER the user has already answered in the terminal, on a
+    // frame with no dialog in it. Clearing the field there was the whole bug:
+    // `verifyStillAnswerable` reads a MISSING `options` as "never parsed" and
+    // keeps such an item answerable by design, so a cleared field made the item
+    // permanently unsweepable — the red "needs you" alert then survived every
+    // `GET /api/approvals` and every page reload and only went away on `stop`
+    // (owner report 2026-08-20: a confirmed question left a tab flowing red for
+    // ~8 minutes while the turn ran on), and the stale card still accepted an
+    // answer, typing a bare `1` into a composer with no dialog under it.
+    // Keeping the parse means a later capture is CONCLUSIVE: options present +
+    // fresh frame without them == answered in the terminal.
+    if (options) item.options = options;
   }
 
   private remove(item: ApprovalItem, resolution: ApprovalResolution): void {
     this.items.delete(item.sessionId);
     this.captures.delete(item.sessionId);
-    const timer = this.recaptureTimers.get(item.id);
-    if (timer) {
-      clearTimeout(timer);
-      this.recaptureTimers.delete(item.id);
-    }
+    for (const timer of this.itemTimers.get(item.id) ?? []) clearTimeout(timer);
+    this.itemTimers.delete(item.id);
     if (!this.stopped) {
       this.onResolved?.({ id: item.id, sessionId: item.sessionId, kind: item.kind, resolution });
     }

src/web/public/app.js

@@ -536,10 +536,10 @@ class CodemanApp {
     this._initGeneration = 0;     // dedup concurrent handleInit calls
     this._initFallbackTimer = null; // fallback timer if SSE init doesn't arrive
     this._selectGeneration = 0;   // cancel stale selectSession loads
-    // Sessions whose full tmux scrollback has already been replayed this page load
-    // (COD-47). Tracked PER SESSION rather than as a single "first load" flag: the
-    // flag was consumed by whichever session auto-selected at page load, so every
-    // OTHER tab started life with one visible frame of history (issue #205).
+    // Non-shell sessions whose full tmux scrollback has already been replayed this
+    // page load (COD-47). Shells deliberately start from a bounded tail because
+    // their scrollback can be very large; full history stays available on demand.
+    // Tracked PER SESSION rather than as a single "first load" flag (issue #205).
     this._fullHistoryLoaded = new Set();
     // Cooldown per session for the scroll-to-top "load more history" re-pull.
     this._fullHistoryRepullAt = new Map(); // Map<sessionId, timestamp>
@@ -5268,6 +5268,22 @@ class CodemanApp {
     this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
   }
 
+  _recordTerminalLoadTiming(timing) {
+    this._lastTerminalLoadTiming = timing;
+    console.info('[TERMINAL-PERF]', timing);
+    const resetAndParseMs =
+      (timing.cacheResetAndParseMs || 0) +
+      (timing.freshResetAndParseMs || 0) +
+      (timing.resetAndParseMs || 0);
+    const totalMs = timing.selectDoneMs ?? timing.totalMs ?? timing.selectToReplayCompleteMs ?? 0;
+    _crashDiag.log(
+      `TERMINAL_LOAD: ${timing.trigger} ${timing.full ? 'full' : 'tail'} ${timing.chars} chars ` +
+      `ttfb=${timing.ttfbMs.toFixed(0)}ms body+json=${timing.bodyAndJsonMs.toFixed(0)}ms ` +
+      `reset+parse=${resetAndParseMs.toFixed(0)}ms total=${totalMs.toFixed(0)}ms ` +
+      `server="${timing.serverTiming}"${timing.refused ? ' refused-downgrade' : ''}`
+    );
+  }
+
   /**
    * "Load more history": re-pull the whole tmux scrollback when the user scrolls up
    * while already at the top of what the browser has.
@@ -5296,6 +5312,11 @@ class CodemanApp {
     const sessionId = this.activeSessionId;
     if (!sessionId || this._fullHistoryRepullInFlight || this._isLoadingBuffer) return;
     if (this.detachedSessions?.has(sessionId)) return;
+    const session = this.sessions.get(sessionId);
+    // A shell's full capture can be many megabytes. Replaying it from an
+    // ordinary scroll gesture blocks xterm's main thread, so keep that cost
+    // behind the explicit "Load full history" button.
+    if (!force && session?.mode === 'shell') return;
     const now = Date.now();
     // Momentum scrolling fires this dozens of times per flick, and a burst of new
     // output is the normal reason to want a re-pull, so cooldown rather than latch.
@@ -5307,13 +5328,32 @@ class CodemanApp {
     this._fullHistoryRepullAt.set(sessionId, now);
     this._fullHistoryRepullInFlight = true;
     try {
+      const requestStartedAt = performance.now();
       const res = await fetch(`/api/sessions/${sessionId}/terminal?full=1`);
+      const headersReceivedAt = performance.now();
       const payload = (await res.json())?.data ?? {};
+      const bodyParsedAt = performance.now();
       const buffer = payload.terminalBuffer;
+      const timing = {
+        trigger: force ? 'full-history-button' : 'full-history-scroll',
+        mode: session?.mode || 'unknown',
+        full: true,
+        source: payload.source || 'unknown',
+        chars: buffer?.length || 0,
+        ttfbMs: headersReceivedAt - requestStartedAt,
+        bodyAndJsonMs: bodyParsedAt - headersReceivedAt,
+        resetAndParseMs: 0,
+        totalMs: 0,
+        serverTiming: res.headers?.get?.('server-timing') || '',
+        refused: false,
+      };
       // Bail on a tab switch mid-fetch: writing here would paint another session's
       // history into the terminal the user is now looking at.
       if (!buffer || this.activeSessionId !== sessionId) return;
       if (this._replayWouldShrinkBuffer(buffer)) {
+        timing.refused = true;
+        timing.totalMs = performance.now() - requestStartedAt;
+        this._recordTerminalLoadTiming(timing);
         (this._fullHistoryRepullUseless ||= new Set()).add(sessionId);
         this._logScrollRouting?.('repull-refused-downgrade');
         // The browser already holds more than tmux can give back, so there is
@@ -5324,17 +5364,32 @@ class CodemanApp {
       this._setHistoryTruncation(sessionId, payload);
       this._fullHistoryRepullUseless?.delete(sessionId);
       const rowsBefore = this.terminal.buffer.active.length;
+      const replayStartedAt = performance.now();
       this._resetTerminalForReplay();
-      await this.chunkedTerminalWrite(buffer, TERMINAL_CHUNK_SIZE, sessionId);
-      if (this.activeSessionId !== sessionId) return;
-      this.terminalBufferCache.set(sessionId, buffer);
+      const {
+        parsedAt,
+        bufferLength: parsedBufferLength,
+        completed,
+      } = await this.chunkedTerminalWrite(buffer, TERMINAL_CHUNK_SIZE, sessionId);
+      timing.resetAndParseMs = parsedAt - replayStartedAt;
+      if (!completed || this.activeSessionId !== sessionId) return;
+      // Keep shell tab restores bounded too. A user-triggered full-history pull
+      // may be tens of MB; caching it would replay that whole payload again on
+      // the next tab switch before the normal 1MB tail fetch replaces it.
+      if (this.sessions.get(sessionId)?.mode !== 'shell') {
+        this.terminalBufferCache.set(sessionId, buffer);
+      } else {
+        this.terminalBufferCache.delete(sessionId);
+      }
       // Hold the user's place. The replay is a superset that grew the buffer
       // UPWARD, so what used to be row 0 (what they were looking at) is now `delta`
       // rows down; scrolling there reveals the recovered history above it instead
       // of teleporting them to the bottom the way a normal buffer load does.
-      const delta = this.terminal.buffer.active.length - rowsBefore;
+      const delta = parsedBufferLength - rowsBefore;
       if (delta > 0) this.terminal.scrollToLine(delta);
       else this.terminal.scrollToTop();
+      timing.totalMs = performance.now() - requestStartedAt;
+      this._recordTerminalLoadTiming(timing);
     } catch {
       // Transient (offline, 5xx) — the next scroll-up past the cooldown retries.
     } finally {
@@ -5614,6 +5669,7 @@ class CodemanApp {
     // COD-144: track whether the load painted nothing (empty fetch + no cache).
     // For that just-created-session case we flush (not discard) queued SSE events.
     let bufferWasEmpty = false;
+    let cacheResetAndParseMs = 0;
     try {
       // Fit terminal to container BEFORE writing any buffer data.
       // If the browser was resized while viewing another session, the terminal
@@ -5691,23 +5747,30 @@ class CodemanApp {
       // blank and rewrites with fresh data. Skip the cache and write the fresh
       // buffer once for a single clean transition.
       const cachedBuffer = this.terminalBufferCache.get(sessionId);
-      let clearedForBusy = false;
-      if (cachedBuffer && !sessionIsBusy && !restoredSnapshot) {
+      let clearedBeforeFresh = false;
+      if (cachedBuffer && !sessionIsBusy && !restoredSnapshot && session?.mode !== 'shell') {
         _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
         this._setTerminalLoadState(sessionId, selectGen, 'replaying');
+        const cacheReplayStartedAt = performance.now();
         this._resetTerminalForReplay();
-        await this.chunkedTerminalWrite(cachedBuffer, TERMINAL_CHUNK_SIZE, bufferLoadOwner);
+        const { parsedAt: cacheParsedAt } = await this.chunkedTerminalWrite(
+          cachedBuffer,
+          TERMINAL_CHUNK_SIZE,
+          bufferLoadOwner
+        );
+        cacheResetAndParseMs = cacheParsedAt - cacheReplayStartedAt;
         if (this._isStaleSelect(selectGen)) {
           this._clearTerminalLoadState(sessionId, selectGen);
           return;
         }
         this.terminal.scrollToBottom();
         _crashDiag.log('CACHE_DONE');
-      } else if (sessionIsBusy) {
-        // Clear stale content immediately — fresh buffer is being fetched
+      } else if (sessionIsBusy || session?.mode === 'shell') {
+        // Busy sessions have stale caches. Shell sessions deliberately skip even
+        // an idle cache so a changed 1MB tail cannot cause two back-to-back parses.
         this._resetTerminalForReplay();
-        clearedForBusy = true;
-        _crashDiag.log('CACHE_SKIP_BUSY');
+        clearedBeforeFresh = true;
+        _crashDiag.log(session?.mode === 'shell' ? 'CACHE_SKIP_SHELL' : 'CACHE_SKIP_BUSY');
       }
 
       // Give TUI sessions a short chance to redraw after resize before the
@@ -5725,26 +5788,29 @@ class CodemanApp {
 
       this._setTerminalLoadState(sessionId, selectGen, 'fetching');
       _crashDiag.log('FETCH_START');
-      // The first load OF EACH SESSION this page load requests the full tmux
-      // scrollback (?full=1, COD-47) so history that scrolled off the server's byte
-      // buffer comes back. Later switches to an already-replayed session keep the
-      // fast ?tail= frame path, which is why this is a Set and not a flag: the flag
-      // version gave the full replay to the auto-selected tab and one frame of
-      // history to every other one (issue #205).
-      const useFullHistory = !this._fullHistoryLoaded.has(sessionId);
+      // TUI sessions still get one canonical full replay per page (COD-47/#205).
+      // A shell can retain hundreds of thousands of plain scrollback lines, so
+      // automatically replaying all of them makes tab selection scale with the
+      // entire session. Load its bounded 1MB tail first; the existing truncation
+      // banner action fetches ?full=1 when the user explicitly asks for it.
+      const useFullHistory = session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId);
       if (useFullHistory) this._fullHistoryLoaded.add(sessionId);
+      const fetchStartedAt = performance.now();
       const res = await fetch(
         useFullHistory
           ? `/api/sessions/${sessionId}/terminal?full=1`
           : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`
       );
+      const headersReceivedAt = performance.now();
       if (this._isStaleSelect(selectGen)) {
         this._clearTerminalLoadState(sessionId, selectGen);
         return;
       }
       const data = (await res.json())?.data ?? {};
+      const bodyParsedAt = performance.now();
       _crashDiag.log(`FETCH_DONE: ${data.terminalBuffer ? (data.terminalBuffer.length/1024).toFixed(0) + 'KB' : 'empty'} truncated=${data.truncated}`);
 
+      let freshResetAndParseMs = 0;
       if (data.terminalBuffer) {
         // Skip rewrite if fresh buffer matches cache — avoids visible clear+rewrite flash.
         // On slow connections (mobile 5G), the gap between clear() and chunkedWrite() is
@@ -5753,10 +5819,11 @@ class CodemanApp {
         // something other than the cache, so the fetched buffer must be
         // replayed even when it byte-matches the cache.
         const needsRewrite =
-          restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer;
+          restoredSnapshot || clearedBeforeFresh || data.terminalBuffer !== cachedBuffer;
         if (needsRewrite) {
           _crashDiag.log(`REWRITE: ${(data.terminalBuffer.length/1024).toFixed(0)}KB`);
           this._setTerminalLoadState(sessionId, selectGen, 'replaying');
+          const replayStartedAt = performance.now();
           this._resetTerminalForReplay();
           // Truncation is reported OUT OF BAND (#258). This used to write a grey
           // "... earlier output truncated ..." line into the
@@ -5764,7 +5831,12 @@ class CodemanApp {
           // cannot be actioned, and is indistinguishable from real CLI output.
           this._setHistoryTruncation(sessionId, data);
           // Use chunked write for large buffers to avoid UI jank
-          await this.chunkedTerminalWrite(data.terminalBuffer, TERMINAL_CHUNK_SIZE, bufferLoadOwner);
+          const { parsedAt: freshParsedAt } = await this.chunkedTerminalWrite(
+            data.terminalBuffer,
+            TERMINAL_CHUNK_SIZE,
+            bufferLoadOwner
+          );
+          freshResetAndParseMs = freshParsedAt - replayStartedAt;
           if (this._isStaleSelect(selectGen)) {
             this._clearTerminalLoadState(sessionId, selectGen);
             return;
@@ -5773,22 +5845,42 @@ class CodemanApp {
           this.terminal.scrollToBottom();
         }
 
-        // Update cache (cap at 20 entries)
-        this.terminalBufferCache.set(sessionId, data.terminalBuffer);
-        if (this.terminalBufferCache.size > 20) {
-          // Evict oldest entry (first key in Map iteration order)
-          const oldest = this.terminalBufferCache.keys().next().value;
-          this.terminalBufferCache.delete(oldest);
+        // Shell selection always uses a fresh bounded tail, so retaining its
+        // payload only wastes memory and can evict useful TUI caches.
+        if (session?.mode === 'shell') {
+          this.terminalBufferCache.delete(sessionId);
+        } else {
+          // Update cache (cap at 20 entries)
+          this.terminalBufferCache.set(sessionId, data.terminalBuffer);
+          if (this.terminalBufferCache.size > 20) {
+            // Evict oldest entry (first key in Map iteration order)
+            const oldest = this.terminalBufferCache.keys().next().value;
+            this.terminalBufferCache.delete(oldest);
+          }
         }
-      } else if (!cachedBuffer) {
-        // No fresh buffer and no cache — clear any stale content
-        this._resetTerminalForReplay();
+      } else if (!cachedBuffer || clearedBeforeFresh) {
+        // Nothing was painted. If this path was not already cleared above,
+        // clear stale content now; either way queued live output must be flushed.
+        if (!clearedBeforeFresh) this._resetTerminalForReplay();
         bufferWasEmpty = true;
       }
 
+      const terminalLoadTiming = {
+        trigger: 'session-select',
+        mode: session?.mode || 'unknown',
+        full: useFullHistory,
+        source: data.source || 'unknown',
+        chars: data.terminalBuffer?.length || 0,
+        ttfbMs: headersReceivedAt - fetchStartedAt,
+        bodyAndJsonMs: bodyParsedAt - headersReceivedAt,
+        cacheResetAndParseMs,
+        freshResetAndParseMs,
+        selectToReplayCompleteMs: performance.now() - _selStart,
+        serverTiming: res.headers?.get?.('server-timing') || '',
+      };
       // Buffer load complete — unblock live SSE writes. chunkedTerminalWrite calls
-      // _finishBufferLoad internally (discarding queued events to prevent duplicate
-      // content); if we skipped the write (cache hit or empty), call it here.
+      // _finishBufferLoad after ordering the fetched snapshot in xterm; if we skipped
+      // the write (cache hit or empty), call it here.
       // COD-144: when the load painted nothing, FLUSH the queued events instead of
       // discarding — a new session's prompt arrives only as a queued SSE event.
       if (this._isLoadingBuffer) {
@@ -5917,9 +6009,12 @@ class CodemanApp {
       if (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) {
         KeyboardHandler.onKeyboardShow();
       }
+      const selectDoneMs = performance.now() - _selStart;
+      terminalLoadTiming.selectDoneMs = selectDoneMs;
+      this._recordTerminalLoadTiming(terminalLoadTiming);
       this._clearTerminalLoadState(sessionId, selectGen);
-      _crashDiag.log(`SELECT_DONE: ${(performance.now() - _selStart).toFixed(0)}ms`);
-      console.log(`[CRASH-DIAG] selectSession DONE: ${sessionId.slice(0,8)} in ${(performance.now() - _selStart).toFixed(0)}ms`);
+      _crashDiag.log(`SELECT_DONE: ${selectDoneMs.toFixed(0)}ms`);
+      console.log(`[CRASH-DIAG] selectSession DONE: ${sessionId.slice(0,8)} in ${selectDoneMs.toFixed(0)}ms`);
     } catch (err) {
       if (this._isLoadingBuffer) this._finishBufferLoad(bufferLoadOwner);
       this._restoringFlushedState = false;

src/web/public/constants.js

@@ -562,6 +562,55 @@ function resolveTerminalFontFamily(custom) {
   return `${families.join(', ')}, ${TERMINAL_FONT_DEFAULT_STACK}`;
 }
 
+// ---------------------------------------------------------------------------
+// Auto Copy (copy-on-select). Pure decision, so every guard below is testable
+// without a terminal, a clipboard, or a browser.
+// ---------------------------------------------------------------------------
+
+/**
+ * Upper bound on an AUTO-copied selection.
+ *
+ * A drag that runs off the top of the viewport autoscrolls, so one gesture can
+ * sweep the entire 50k-line scrollback (millions of characters), and writing
+ * that to the clipboard on every mouseup is a real hazard on a phone. Past the
+ * cap the copy is REFUSED rather than truncated (half a selection on the
+ * clipboard is worse than none) and the user is told to press Ctrl+C, which
+ * still copies the whole thing through the explicit path.
+ */
+const AUTO_COPY_MAX_CHARS = 1_000_000;
+
+/**
+ * What an auto-copy attempt should do at the end of a selection gesture.
+ *
+ * `pending` is set by xterm's onSelectionChange and cleared on every flush;
+ * `lastCopied` is the text this surface auto-copied last. Either one alone is
+ * wrong, which is why both are here:
+ *
+ *  - onSelectionChange does not reliably fire BEFORE the mouseup that ends the
+ *    drag (xterm fires it from its own document-level mouseup handler, and
+ *    listener order between the two is registration order, not something this
+ *    code controls). Gating on `pending` alone would silently drop the first
+ *    copy of a drag-selection.
+ *  - Gating on `text !== lastCopied` alone drops a deliberate re-selection of
+ *    the same text after the user copied something else in between, and it
+ *    would let any unrelated mouseup on the page re-copy a stale selection.
+ *
+ * So: a genuine selection change (`pending`) always copies, and otherwise only
+ * text that differs from the last auto-copy does.
+ *
+ * @param {{enabled?: boolean, text?: string, lastCopied?: string, pending?: boolean}} params
+ * @returns {'copy'|'skip'|'too-large'}
+ */
+function decideAutoCopy({ enabled, text, lastCopied, pending } = {}) {
+  if (!enabled) return 'skip';
+  // Whitespace-only is what a drag across blank cells produces; putting a wall
+  // of spaces on the clipboard is never what the gesture meant.
+  if (typeof text !== 'string' || !text.trim()) return 'skip';
+  if (!pending && text === lastCopied) return 'skip';
+  if (text.length > AUTO_COPY_MAX_CHARS) return 'too-large';
+  return 'copy';
+}
+
 if (typeof window !== 'undefined') {
   window.WEBGL_FALLBACK = WEBGL_FALLBACK;
   window.evaluateWebGLLongTaskTrip = evaluateWebGLLongTaskTrip;
@@ -595,6 +644,10 @@ if (typeof window !== 'undefined') {
     compare: compareSessionActivity,
     sort: sortSessionsByActivity,
   };
+  window.CodemanAutoCopy = {
+    decide: decideAutoCopy,
+    MAX_CHARS: AUTO_COPY_MAX_CHARS,
+  };
   window.CodemanTerminalFont = {
     DEFAULT_STACK: TERMINAL_FONT_DEFAULT_STACK,
     resolve: resolveTerminalFontFamily,

src/web/public/i18n.js

@@ -335,6 +335,11 @@
     'Extended Keyboard Bar': '扩展键盘栏',
     'Gesture Control (beta)': '手势控制（测试版）',
     'Wheel Scrolls Local History': '滚轮滚动本地历史',
+    'Auto Copy Selection': '自动复制选中内容',
+    'Selection & clipboard': '选中与剪贴板',
+    'Auto Copy: selection copied': '自动复制：已复制选中内容',
+    'Auto Copy failed: the browser blocked clipboard access': '自动复制失败：浏览器阻止了剪贴板访问',
+    'Selection too large to copy automatically. Press Ctrl+C.': '选中内容过大，无法自动复制。请按 Ctrl+C。',
     'Instant typing feedback with local echo': '通过本地回显即时显示输入',
     'Dedicated IME input field for CJK languages': '为中日韩语言提供专用输入法文本框',
     'Extra keys: Tab, Esc, arrows, Ctrl+O': '附加按键：Tab、Esc、方向键、Ctrl+O',

src/web/public/index.html

@@ -1627,6 +1627,19 @@
                 </div>
               </div>
 
+              <div class="set-group">
+                <div class="set-group-head"><h4>Selection &amp; clipboard</h4><span class="set-scope">device</span></div>
+                <div class="set-group-body">
+                  <div class="set-row" data-search="auto copy selection clipboard highlight copy on select mouse">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Auto Copy Selection</span>
+                      <span class="set-row-desc">Put highlighted terminal text on the clipboard as soon as you finish selecting it, with mouse, double-click or long-press. Ctrl+C still copies on demand, and nothing outside the terminal is copied.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsAutoCopySelection"><span class="slider"></span></label>
+                  </div>
+                </div>
+              </div>
+
               <div class="set-group">
                 <div class="set-group-head"><h4>Font</h4><span class="set-scope">device</span></div>
                 <div class="set-group-body">

src/web/public/input-cjk.js

@@ -27,8 +27,8 @@
  *
  * Solution: outside composition, flush is DEBOUNCED (200ms). The entire
  * delete→reinsert cycle collapses into one flush of the final textarea value.
- * Keyboard typing of single printable characters still goes through the
- * keydown handler (immediate, no debounce).
+ * Physical-keyboard commits are flushed immediately after the input event
+ * exposes the final browser/IME text; keydown never guesses that text.
  *
  * ## Phantom character for Android backspace
  *
@@ -56,8 +56,7 @@ const CjkInput = (() => {
   let _compositionFlushTimer = null;
   let _dictationActive = false;
   let _dictationDecayTimer = null;
-  let _keydownSentAt = 0;
-  let _keydownSentText = '';
+  let _printableKeydownAt = null;
   const _listeners = {};
 
   const PHANTOM = '​';
@@ -197,6 +196,7 @@ const CjkInput = (() => {
 
       _send = send;
       _composing = false;
+      _printableKeydownAt = null;
       _flushTimer = null;
       _textarea = document.getElementById('cjkInput');
       if (!_textarea) return this;
@@ -234,6 +234,7 @@ const CjkInput = (() => {
       };
       _listeners.blur = () => {
         _t(`blur composing=${_composing} ${_vdesc(_textarea.value)}`);
+        _printableKeydownAt = null;
         // Keep cjkActive while CJK input is visible — iOS dictation and system
         // UI may steal focus temporarily, and clearing the flag during that
         // window lets xterm's onData process duplicated input.
@@ -253,6 +254,7 @@ const CjkInput = (() => {
       _listeners.compositionstart = () => {
         _t(`compstart ${_vdesc(_textarea.value)}`);
         _composing = true;
+        _printableKeydownAt = null;
         _cancelDebouncedFlush();
         // Leave textarea.value untouched — programmatic changes during
         // compositionstart cancel the IME composition on iOS Safari.
@@ -277,6 +279,7 @@ const CjkInput = (() => {
       // ── Keydown: special keys work REGARDLESS of composition state ──
       _listeners.keydown = (e) => {
         _t(`keydown ${_kdesc(e.key)} kc=${e.keyCode} ic=${e.isComposing} c=${_composing}`);
+        _printableKeydownAt = null;
         if (e.key === 'Enter') {
           e.preventDefault();
           _composing = false;
@@ -325,16 +328,11 @@ const CjkInput = (() => {
           return;
         }
 
-        // Single printable character: send immediately to PTY.
-        // Third-party IMEs on iOS may ignore preventDefault, so the char
-        // still enters the textarea and fires an input event — _keydownSentAt
-        // tells the input handler to skip that echo.
+        // A printable KeyboardEvent.key is the physical key, not necessarily
+        // the committed text. Let the browser/IME produce the input event so
+        // full-width punctuation and other layout transforms are preserved.
         if (e.key.length === 1 && !e.ctrlKey && !e.altKey && !e.metaKey && _isEffectivelyEmpty()) {
-          e.preventDefault();
-          _send(e.key);
-          _keydownSentAt = performance.now();
-          _keydownSentText = e.key;
-          _resetToPhantom();
+          _printableKeydownAt = performance.now();
           return;
         }
       };
@@ -343,6 +341,8 @@ const CjkInput = (() => {
       // ── Input event: primary path for virtual keyboards + dictation ──
       _listeners.input = (e) => {
         _t(`input ${e.inputType || '?'} ic=${e.isComposing} c=${_composing} ${_vdesc(_textarea.value)}`);
+        const printableKeydownAt = _printableKeydownAt;
+        _printableKeydownAt = null;
         // ── Stuck-composition recovery ──
         // Some IMEs (WeChat/Sogou keyboards) fire compositionstart without a
         // matching compositionend. A stale _composing=true blocks every flush
@@ -388,18 +388,18 @@ const CjkInput = (() => {
 
         if (_composing) return;
 
-        // Keydown handler already sent this character — clear the textarea
-        // echo that the IME inserted despite preventDefault. Content-checked:
-        // only a value matching the sent char is an echo. Anything else (e.g.
-        // an IME committing CJK text right after a keydown-sent char) is real
-        // input and must flow through to the debounced flush, not be dropped.
-        if (performance.now() - _keydownSentAt < 100) {
-          const cur = _strip(_textarea.value);
-          if (cur === '' || cur === _keydownSentText) {
-            _t('echo-drop');
-            _resetToPhantom();
-            return;
-          }
+        // A recent physical printable key makes this insertText a keyboard
+        // commit, so keep the old zero-latency path. Send the textarea's final
+        // Unicode value, never KeyboardEvent.key, because the IME may have
+        // transformed punctuation or the active layout may differ.
+        if (
+          e.inputType === 'insertText' &&
+          printableKeydownAt !== null &&
+          performance.now() - printableKeydownAt < 100
+        ) {
+          _cancelDebouncedFlush();
+          _flush();
+          return;
         }
 
         // Outside composition: keyboard typing or voice dictation.
@@ -425,6 +425,7 @@ const CjkInput = (() => {
       clearTimeout(_compositionFlushTimer);
       _compositionFlushTimer = null;
       _composing = false;
+      _printableKeydownAt = null;
       _resetToPhantom();
     },
 
@@ -446,6 +447,7 @@ const CjkInput = (() => {
       }
       window.cjkActive = false;
       _composing = false;
+      _printableKeydownAt = null;
       for (const key of Object.keys(_listeners)) delete _listeners[key];
       _initialized = false;
     },

src/web/public/settings-ui.js

@@ -41,8 +41,17 @@ Object.assign(CodemanApp.prototype, {
   _onHookElicitationComplete(data) {
     // Question answered in the terminal: clear the action alert without
     // waiting for `stop` (the turn may keep running for a long time).
+    // ⚠️ BOTH action kinds, matching the server's APPROVAL_RESOLVING_EVENTS,
+    // which resolves a session's pending item whatever its kind. An
+    // AskUserQuestion dialog arrives as `permission_prompt` (only MCP
+    // elicitation is `elicitation_dialog`), so clearing just the elicitation
+    // entry left the red alert armed on exactly the dialog these events are
+    // most often about. Normally the server's `approval:resolved` broadcast
+    // clears it too; this is the path that still works when the store holds no
+    // item for the session (restart, superseded).
     if (data.sessionId) {
       this.clearPendingHooks(data.sessionId, 'elicitation_dialog');
+      this.clearPendingHooks(data.sessionId, 'permission_prompt');
     }
   },
 
@@ -381,6 +390,10 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsTunnelEnabled').checked = settings.tunnelEnabled ?? false;
     this.loadTunnelStatus();
     document.getElementById('appSettingsLocalEcho').checked = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
+    // Auto Copy (copy-on-select): per-device, default OFF everywhere. It quietly
+    // overwrites the system clipboard on a gesture the user may have meant only as
+    // a way to read, so it is opt-in rather than a default anyone has to discover.
+    document.getElementById('appSettingsAutoCopySelection').checked = settings.autoCopySelection === true;
     document.getElementById('appSettingsTerminalFont').value = settings.terminalFontFamily || '';
     document.getElementById('appSettingsTerminalWheelLocal').checked =
       settings.terminalWheelLocalScrollback ?? defaults.terminalWheelLocalScrollback ?? false;
@@ -2007,6 +2020,7 @@ Object.assign(CodemanApp.prototype, {
       imageWatcherEnabled: document.getElementById('appSettingsImageWatcherEnabled').checked,
       tunnelEnabled: document.getElementById('appSettingsTunnelEnabled').checked,
       localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
+      autoCopySelection: document.getElementById('appSettingsAutoCopySelection').checked,
       terminalFontFamily: document.getElementById('appSettingsTerminalFont').value.trim(),
       terminalWheelLocalScrollback: document.getElementById('appSettingsTerminalWheelLocal').checked,
       cjkInputEnabled: document.getElementById('appSettingsCjkInput').checked,
@@ -2203,6 +2217,11 @@ Object.assign(CodemanApp.prototype, {
       showFileViewerButton: _fvb,
       webglRendererEnabled: _wgl,
       terminalWheelLocalScrollback: _twls,
+      // Copy-on-select. Per-device (clipboard access differs by device and by
+      // origin: the plain-HTTP LAN install has no navigator.clipboard at all)
+      // and absent from SettingsUpdateSchema (.strict()), so sending it would
+      // 400 the whole settings PUT.
+      autoCopySelection: _acs,
       // Per-device by nature (the font must exist on the device) and absent
       // from SettingsUpdateSchema (.strict()) — sending it would 400 the PUT.
       terminalFontFamily: _tff,
@@ -2883,6 +2902,7 @@ Object.assign(CodemanApp.prototype, {
           'terminalFontFamily',
           'language',
           'terminalWheelLocalScrollback',
+          'autoCopySelection',
           'showSessionButton', 'showAwayDigestButton', 'showCronButton',
           'showTabDetachButton',
           'mobileOverviewEnabled',

src/web/public/terminal-ui.js

@@ -287,11 +287,12 @@ Object.assign(CodemanApp.prototype, {
     this._installMobileTapMouseGuard();
     this._installTouchSelectionFocusGuard();
 
-    // Suppress xterm key handling during CJK IME composition.
-    // Without this, xterm processes raw keyDown events (e.g., "Process" key)
-    // during composition, causing duplicate or garbled input.
+    // Let xterm's CompositionHelper own IME key events. In particular, a
+    // non-composing keyCode 229 is how an active IME commits numbers and
+    // punctuation; returning false here would stop xterm before it can diff
+    // the helper textarea and emit the committed Unicode text.
     this.terminal.attachCustomKeyEventHandler((ev) => {
-      if (ev.isComposing || ev.keyCode === 229) return false;
+      if (ev.isComposing || ev.key === 'Process' || ev.keyCode === 229) return true;
 
       // Let the app's Alt/Option session-nav and Command Palette shortcuts reach the document keydown handler
       // (app.js switches tabs by PHYSICAL e.code) instead of xterm injecting ESC<char> into
@@ -399,72 +400,6 @@ Object.assign(CodemanApp.prototype, {
       return true;
     });
 
-    // Android virtual keyboard fix: catch non-composition input events.
-    // On Android Chrome, typing symbols (e.g., "/" from Gboard's symbol keyboard)
-    // sends keyCode 229 + input event WITHOUT compositionstart/end wrapping.
-    // The custom key handler above returns false for keyCode 229, telling xterm
-    // to ignore the keydown. xterm.js expects the character to arrive via
-    // composition events, but since there's no composition, the character is lost.
-    // This listener catches those orphaned input events and forwards them to onData.
-    {
-      const xtermTextarea = container.querySelector('.xterm-helper-textarea');
-      if (xtermTextarea && MobileDetection.isTouchDevice()) {
-        let composing = false;
-        let lastKeydownHandled = 0;
-        xtermTextarea.addEventListener('compositionstart', () => { composing = true; });
-        xtermTextarea.addEventListener('compositionend', () => { composing = false; });
-        // Track when xterm handles a keydown normally (non-229 keyCode).
-        // If xterm processed the keydown, it will emit onData itself --
-        // the input event handler below must NOT re-send the character.
-        xtermTextarea.addEventListener('keydown', (e) => {
-          if (!e.isComposing && e.keyCode !== 229) {
-            lastKeydownHandled = Date.now();
-          }
-        });
-        xtermTextarea.addEventListener('input', (e) => {
-          // Only handle insertText events outside of composition -- these are
-          // the ones xterm.js misses on Android virtual keyboards.
-          if (composing || e.isComposing) return;
-          if (e.inputType !== 'insertText' || !e.data) return;
-          // If xterm just handled a keydown (within 50ms), it already sent the
-          // char via onData. Skip to avoid double-send (e.g., Shift+A => AA).
-          if (Date.now() - lastKeydownHandled < 50) return;
-          // xterm.js may have already processed this via its own input handler.
-          // Check if the textarea was cleared by xterm (value is empty or just
-          // whitespace) -- if so, xterm handled it and we should not double-send.
-          // Use a microtask to check after xterm's own handlers have run.
-          const data = e.data;
-          const pendingBefore = this._localEchoOverlay?.pendingText || '';
-          Promise.resolve().then(() => {
-            if (
-              this._lastTerminalData?.data === data &&
-              performance.now() - this._lastTerminalData.time < 100
-            ) {
-              xtermTextarea.value = '';
-              return;
-            }
-            const pendingAfter = this._localEchoOverlay?.pendingText || '';
-            if (
-              this._localEchoEnabled &&
-              pendingAfter.length > pendingBefore.length &&
-              pendingAfter.endsWith(data)
-            ) {
-              xtermTextarea.value = '';
-              return;
-            }
-            // If xterm cleared the textarea, it processed the input -- skip.
-            const val = xtermTextarea.value;
-            if (!val || (val.trim() === '' && data !== ' ')) return;
-            // xterm didn't process it -- forward to terminal as if typed.
-            // Emit via onData path by writing to terminal's input handler.
-            this.terminal._core.coreService.triggerDataEvent(data, true);
-            // Clear the textarea to prevent xterm from processing it later.
-            xtermTextarea.value = '';
-          });
-        });
-      }
-    }
-
     // WebGL renderer for GPU-accelerated terminal rendering.
     // Previously caused "page unresponsive" crashes from synchronous GPU stalls,
     // but the mode-aware 32/64KB frame cap in flushPendingWrites() now prevents
@@ -592,9 +527,35 @@ Object.assign(CodemanApp.prototype, {
         this._touchSelectionActive = false;
         this._touchSelectionAnchor = null;
         this._hideTouchSelectionBar();
+        // Nothing highlighted, nothing for Auto Copy to flush. xterm drops the
+        // selection on any keypress, so without this a keystroke would leave a
+        // stale flush armed for the next unrelated mouseup.
+        this._autoCopyPending = false;
+        return;
       }
+      // Auto Copy arms here and fires at the END of the gesture (below). This
+      // callback runs on EVERY cell the drag crosses, so copying here would be
+      // one clipboard write per mouse move.
+      this._autoCopyPending = true;
     });
 
+    // Auto Copy (copy-on-select, per-device `autoCopySelection`, default OFF).
+    //
+    // ⚠️ The flush is SYNCHRONOUS inside the mouseup handler, deliberately: both
+    // clipboard paths need user activation (Firefox gates navigator.clipboard
+    // .writeText on it, and Safari requires document.execCommand('copy'), the
+    // plain-HTTP fallback install.sh's LAN option lands on, to run inside the
+    // gesture's own task). Deferring to a timer or to onSelectionChange loses it.
+    //
+    // ⚠️ document-level, because a drag that ends outside the terminal (the user
+    // sweeps up past the header) delivers its mouseup to the document, not to
+    // the container. Unrelated mouseups elsewhere on the page are filtered by
+    // decideAutoCopy, not by the listener's target.
+    if (!this._autoCopyListenerInstalled) {
+      this._autoCopyListenerInstalled = true;
+      document.addEventListener('mouseup', () => this._flushAutoCopySelection());
+    }
+
     // Mouse wheel: forward to the TUI only for sessions verified to handle SGR
     // wheel reports (claude 2.1.187+ — see _shouldForwardWheelToApp), local
     // scrollback otherwise. Claude Code 2.1.187+ scrolls its own
@@ -1892,6 +1853,11 @@ Object.assign(CodemanApp.prototype, {
     this._suppressTrustedTapMouseEvents();
     this._armTouchSelectionFocusGuard();
     this._positionTouchSelectionBar();
+    // Auto Copy's other entry point. The touchend that ends this gesture is
+    // preventDefault()ed (that is what stops the compat mouse pair from
+    // stealing the selection back), so the document mouseup listener never sees
+    // this surface at all, so a phone would have a dead toggle without this call.
+    this._flushAutoCopySelection();
   },
 
   /** Whole logical line under the anchor — the common case a word selection just missed. */
@@ -1912,6 +1878,9 @@ Object.assign(CodemanApp.prototype, {
     this._touchSelectionAnchor = { index, length };
     this._applyTouchSelection(index, length);
     this._positionTouchSelectionBar();
+    // Widening to the whole line is a new selection the user asked for, and the
+    // button's click carries the activation both clipboard paths need.
+    this._flushAutoCopySelection();
   },
 
   /** Copy through the shared path: Clipboard API, else execCommand (plain-HTTP installs). */
@@ -3012,12 +2981,12 @@ Object.assign(CodemanApp.prototype, {
 
   /**
    * Post-scroll companion to _noteTerminalUserScroll: hitting the TOP of the
-   * buffer while scrolling up is the user reaching for history the browser does
-   * not have, so pull the rest of tmux's scrollback (issue #205, see
-   * _maybeRefetchFullHistory). Must be called AFTER scrollLines(), since the
-   * check is on the resulting position, and it is deliberately not folded into
-   * _noteTerminalUserScroll for exactly that reason. Cheap: one integer compare
-   * per scroll event, and the pull itself is cooldown-guarded.
+   * buffer while scrolling up gives the app a chance to pull the rest of tmux's
+   * scrollback (issue #205, see _maybeRefetchFullHistory). Shell sessions decline
+   * automatic pulls because their captures can be large; their banner button is
+   * the explicit path. Must be called AFTER scrollLines(), since the check is on
+   * the resulting position, and it is deliberately not folded into
+   * _noteTerminalUserScroll for exactly that reason.
    */
   _maybeLoadMoreHistoryOnScroll(lines) {
     if (lines >= 0) return;
@@ -3571,7 +3540,9 @@ Object.assign(CodemanApp.prototype, {
     }
 
     const buffer = this.terminal.buffer.active;
-    const totalLines = buffer.baseY + buffer.length;
+    // `length` already includes scrollback + viewport rows. Adding baseY scans
+    // every scrollback row twice, starting with thousands of out-of-range calls.
+    const totalLines = buffer.length;
     let lastNonEmptyLine = -1;
 
     for (let lineIndex = totalLines - 1; lineIndex >= 0; lineIndex--) {
@@ -3601,8 +3572,8 @@ Object.assign(CodemanApp.prototype, {
    * Uses _safeYield to spread work across frames; falls back to setTimeout
    * and a tick-Worker so progress continues on occluded / idle-throttled tabs.
    * @param {string} buffer - The full terminal buffer to write
-   * @param {number} chunkSize - Size of each chunk (default 128KB for smooth 60fps)
-   * @returns {Promise<void>} - Resolves when all chunks written
+   * @param {number} chunkSize - Size of each chunk (default 32KB)
+   * @returns {Promise<{parsedAt: number, bufferLength: number, completed: boolean}>} Parse marker snapshot
    */
   chunkedTerminalWrite(buffer, chunkSize = TERMINAL_CHUNK_SIZE, loadOwner) {
     // Generation counter: if a newer chunkedTerminalWrite starts (tab switch),
@@ -3611,9 +3582,14 @@ Object.assign(CodemanApp.prototype, {
     const bufferLoadOwner = this._beginBufferLoad(loadOwner);
 
     return new Promise((resolve) => {
+      const parseSnapshot = (completed = this._chunkedWriteGen === writeGen) => ({
+        parsedAt: performance.now(),
+        bufferLength: this.terminal?.buffer?.active?.length ?? 0,
+        completed,
+      });
       if (!buffer || buffer.length === 0) {
         this._finishBufferLoad(bufferLoadOwner);
-        resolve();
+        resolve(parseSnapshot());
         return;
       }
 
@@ -3621,53 +3597,45 @@ Object.assign(CodemanApp.prototype, {
       // (from historical SSE data that was stored with markers)
       const cleanBuffer = buffer.replace(DEC_SYNC_STRIP_RE, '');
 
-      const finish = () => {
-        // Only finish if we're still the active write — a newer write owns buffer load state
-        if (this._chunkedWriteGen === writeGen) {
-          this._finishBufferLoad(bufferLoadOwner);
-        }
-        resolve();
-      };
-
       // For small buffers, write directly — single-frame render is fast enough
       if (cleanBuffer.length <= chunkSize) {
-        this.terminal.write(cleanBuffer, finish);
+        this.terminal.write(cleanBuffer, () => resolve(parseSnapshot()));
+        // The write is now ordered in xterm's queue. Release live output before
+        // parsing completes; subsequent writes stay behind it without being lost.
+        this._finishBufferLoad(bufferLoadOwner);
         return;
       }
 
-      // Large buffers: write in chunks across animation frames.
-      // Each 32KB chunk keeps per-frame WebGL render work under ~5ms,
-      // avoiding GPU stalls without needing to toggle the renderer.
+      // Large buffers: enqueue paced chunks, then append an empty marker whose
+      // callback fires after xterm parses every preceding chunk. The live-output
+      // gate is released as soon as that marker is ordered, not after parsing, so
+      // new output queues behind history instead of being held or dropped.
       let offset = 0;
       const _chunkStart = performance.now();
       let _chunkCount = 0;
       const writeChunk = () => {
         // Abort if a newer chunked write started (user switched tabs)
         if (this._chunkedWriteGen !== writeGen) {
-          resolve();
+          resolve(parseSnapshot(false));
           return;
         }
 
-        if (offset >= cleanBuffer.length) {
-          const _totalMs = performance.now() - _chunkStart;
-          console.log(
-            `[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`
-          );
-          // Wait one more frame for xterm to finish rendering before resolving
-          this._safeYield(finish);
-          return;
-        }
-
-        const _ct0 = performance.now();
         const chunk = cleanBuffer.slice(offset, offset + chunkSize);
-        this.terminal.write(chunk);
-        const _cdt = performance.now() - _ct0;
+        offset += chunk.length;
         _chunkCount++;
-        if (_cdt > 50)
-          console.warn(
-            `[CRASH-DIAG] chunk #${_chunkCount} write took ${_cdt.toFixed(0)}ms (${chunk.length} bytes at offset ${offset})`
-          );
-        offset += chunkSize;
+        this.terminal.write(chunk);
+        if (offset >= cleanBuffer.length) {
+          this.terminal.write('', () => {
+            const result = parseSnapshot();
+            const _totalMs = result.parsedAt - _chunkStart;
+            console.log(
+              `[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms parsed`
+            );
+            resolve(result);
+          });
+          this._finishBufferLoad(bufferLoadOwner);
+          return;
+        }
 
         // Schedule next chunk; rAF if possible, else setTimeout/Worker
         // fallback so progress doesn't stall on occluded/unfocused windows.
@@ -3878,21 +3846,98 @@ Object.assign(CodemanApp.prototype, {
     return ok;
   },
 
-  async copyTerminal() {
+  /**
+   * Auto Copy's ON/OFF, read at flush time from the CACHED settings object
+   * (loadAppSettingsFromStorage memoizes, so this is not a localStorage hit).
+   *
+   * Reading it here rather than mirroring it into a field is deliberate: there
+   * is then no apply-path a future settings save can forget to call, and the
+   * toggle takes effect on the very next selection instead of the next reload.
+   */
+  _autoCopySelectionEnabled() {
     try {
-      const buffer = this.terminal.buffer.active;
-      let text = '';
-      for (let i = 0; i < buffer.length; i++) {
-        const line = buffer.getLine(i);
-        if (line) text += line.translateToString(true) + '\n';
-      }
-      await navigator.clipboard.writeText(text.replace(/\n+$/, '\n'));
-      this.showToast('Copied to clipboard', 'success');
-    } catch (err) {
-      this.showToast('Failed to copy', 'error');
+      return this.loadAppSettingsFromStorage?.()?.autoCopySelection === true;
+    } catch {
+      return false;
     }
   },
 
+  /**
+   * Copy the current terminal selection because the user finished highlighting
+   * it. Called at the end of a selection GESTURE: the document mouseup
+   * installed in initTerminal, and the touch-selection gesture end (a touchend
+   * the touch path preventDefaults, so no mouseup ever arrives there).
+   *
+   * ⚠️ This is NOT copyTerminalSelection(): that one clears the selection (so a
+   * second Ctrl+C is an interrupt) and hands focus back to the terminal. Both
+   * are wrong here: clearing would make the text vanish from under the cursor
+   * that just highlighted it, and focusing opens the on-screen keyboard over
+   * the text on a phone. Focus is instead RESTORED to whatever held it, which
+   * only matters for the execCommand fallback (it focuses a temp textarea on
+   * the way through); the Clipboard API path never moves focus at all.
+   */
+  async _flushAutoCopySelection() {
+    const decide = window.CodemanAutoCopy?.decide;
+    if (!decide || !this.terminal) return;
+    const text = this.terminal.hasSelection?.() ? this.terminal.getSelection() : '';
+    const verdict = decide({
+      enabled: this._autoCopySelectionEnabled(),
+      text,
+      lastCopied: this._autoCopyLastText,
+      pending: !!this._autoCopyPending,
+    });
+    this._autoCopyPending = false;
+    if (verdict === 'skip') return;
+    if (verdict === 'too-large') {
+      this._autoCopyNotify('Selection too large to copy automatically. Press Ctrl+C.', 'warning');
+      return;
+    }
+
+    this._autoCopyLastText = text;
+    const focusedBefore = document.activeElement;
+    const ok = await this._copyText(text);
+    if (
+      focusedBefore &&
+      focusedBefore !== document.activeElement &&
+      focusedBefore.isConnected &&
+      typeof focusedBefore.focus === 'function'
+    ) {
+      try {
+        focusedBefore.focus();
+      } catch {}
+    }
+    if (!ok) {
+      // Let the next gesture retry the same text rather than dedupe itself into
+      // silence after a transient clipboard refusal.
+      this._autoCopyLastText = '';
+      this._autoCopyNotify('Auto Copy failed: the browser blocked clipboard access', 'error');
+      return;
+    }
+    // Silent on success, like every terminal emulator's copy-on-select, except
+    // ONCE per page load: a feature that works by doing nothing visible needs to
+    // say so the first time, or the user cannot tell it from a dead toggle.
+    if (!this._autoCopyHintShown) {
+      this._autoCopyHintShown = true;
+      this.showToast('Auto Copy: selection copied', 'success');
+    }
+  },
+
+  /**
+   * Failure/refusal toast, throttled. Auto Copy fires per gesture, so an
+   * install where the clipboard is permanently blocked would otherwise paint a
+   * toast on every drag, which trains the user to ignore toasts everywhere.
+   */
+  _autoCopyNotify(message, type) {
+    const now = Date.now();
+    const last = this._autoCopyNotifiedAt;
+    // `last === undefined` is checked rather than falling back to 0: the first
+    // failure must always be reported, and a `now - 0 < throttle` comparison
+    // only happens to hold because the wall clock is a big number.
+    if (last !== undefined && now - last < 10_000) return;
+    this._autoCopyNotifiedAt = now;
+    this.showToast(message, type);
+  },
+
   _syncMobileHelperTextareaToCursor() {
     if (!MobileDetection.isTouchDevice() || !this.terminal?.element) return;
     try {
@@ -3933,7 +3978,7 @@ Object.assign(CodemanApp.prototype, {
 
     const mouseMode = this.terminal.modes?.mouseTrackingMode;
     const mouseTrackingOn = !!mouseMode && mouseMode !== 'none';
-    if (!mouseTrackingOn && !this._sessionUsesServerMouseStrip()) return 'input';
+    if (!mouseTrackingOn && !this._shouldReportMouseToCli()) return 'input';
 
     const buffer = this.terminal.buffer?.active;
     if (!buffer?.getLine) return 'input';
@@ -4233,9 +4278,10 @@ Object.assign(CodemanApp.prototype, {
       // xterm's mouse encoder owns live DECSET modes. The synthetic DOM click
       // follows the same path as a desktop click.
       this._dispatchSyntheticTerminalClick(touch.clientX, touch.clientY);
-    } else if (shouldActivate && this._sessionUsesServerMouseStrip()) {
+    } else if (shouldActivate && this._shouldReportMouseToCli()) {
       // Claude/Codex/Gemini DECSETs are stripped from the browser stream, so
-      // report directly to the PTY while retaining local touch scrollback.
+      // report directly to the PTY while retaining local touch scrollback. Only
+      // while the CLI actually has tracking on (see _shouldReportMouseToCli).
       this._sendSyntheticSgrTap(touch.clientX, touch.clientY);
     }
 
@@ -4303,9 +4349,32 @@ Object.assign(CodemanApp.prototype, {
   // output stream has mouse-tracking DECSET sequences stripped before reaching the
   // browser. For these, xterm's live mouseTrackingMode is useless as a gate — the
   // PTY-side TUI keeps tracking enabled, we just never see the enable sequence.
-  _sessionUsesServerMouseStrip() {
-    const mode = this.sessions?.get(this.activeSessionId)?.mode || 'claude';
-    return mode === 'claude' || mode === 'codex' || mode === 'gemini';
+  /**
+   * True when the browser has to hand-encode a click report for the CLI.
+   *
+   * Two conditions, and dropping either one is a bug that has already happened:
+   *
+   * 1. The session's mode is one whose mouse DECSETs the server STRIPS out of
+   *    the stream (claude/codex/gemini, `isAltScreenStripMode`), which is why
+   *    xterm's own encoder is permanently idle here and something has to stand
+   *    in for it.
+   * 2. The CLI actually has a mouse-tracking mode on right now. The server
+   *    records that as it strips (`_recordStrippedMouseMode` in session.ts) and
+   *    publishes it as `cliMouseTracking`. Without this half the browser
+   *    reported EVERY click, so a CLI sitting at its composer with no dialog
+   *    open, or a pane that has fallen back to a shell prompt, received mouse
+   *    reports it never asked for. A shell prints those as literal text
+   *    (`[<0;88;20M`) and they garble the next line typed.
+   *
+   * Fails toward silence: an unknown or stale flag reports nothing rather than
+   * injecting bytes. After a server restart the flag is false until the CLI
+   * re-emits its DECSET, which closing and reopening a dialog does.
+   */
+  _shouldReportMouseToCli() {
+    const session = this.sessions?.get(this.activeSessionId);
+    const mode = session?.mode || 'claude';
+    if (mode !== 'claude' && mode !== 'codex' && mode !== 'gemini') return false;
+    return session?.cliMouseTracking === true;
   },
 
   // True when xterm's viewport shows the live PTY screen (not scrolled up into
@@ -4571,7 +4640,7 @@ Object.assign(CodemanApp.prototype, {
 
   // Desktop counterpart of the touchend tap branch: hand-encode an SGR report
   // for a plain left-click when the server strips mouse DECSETs (see
-  // _sessionUsesServerMouseStrip). Every skip below is a click that already has
+  // _shouldReportMouseToCli). Every skip below is a click that already has
   // a meaning elsewhere: synthetic/compat clicks after a touch tap (touchend
   // reported already), modified clicks (shift keeps xterm's selection
   // override), double/triple clicks (word/line selection), drag-selections,
@@ -4585,7 +4654,7 @@ Object.assign(CodemanApp.prototype, {
     if (ev.shiftKey || ev.altKey || ev.ctrlKey || ev.metaKey) return;
     const mode = this.terminal.modes?.mouseTrackingMode;
     if (mode && mode !== 'none') return;
-    if (!this._sessionUsesServerMouseStrip()) return;
+    if (!this._shouldReportMouseToCli()) return;
     if (this.terminal.hasSelection?.()) return;
     if (this._linkHovered) return; // link provider hover/leave callbacks (registerFilePathLinkProvider)
     if (performance.now() <= (this._trustedTapMouseSuppressUntil || 0)) return;

src/web/repo-status.ts

@@ -0,0 +1,397 @@
+/**
+ * @fileoverview Repository-status check (App Settings → Updates → "Repository
+ * status").
+ *
+ * INFORMATIONAL companion to the release-tag self-updater (`self-update.ts`).
+ * Where the updater answers "is there a newer published release tag, and do you
+ * want to `git checkout` it", this module answers "where does my local checkout
+ * sit relative to the upstream project AND my own fork" — by commit ahead/behind
+ * count plus a short list of the incoming commits.
+ *
+ * This needs the actual commits locally, so it does a READ-ONLY `git fetch` of
+ * the compared ref per remote (updates only remote-tracking refs under `.git`,
+ * never the working tree), then `git rev-list`/`git log`. Works uniformly for
+ * GitHub and non-GitHub remotes (e.g. Bitbucket) — no release tags required.
+ *
+ * Remote selection (generalizable): by default the union of `origin` and the
+ * current branch's `@{upstream}` tracking remote, deduped. Override with the
+ * `CODEMAN_UPDATE_REMOTES` env var (comma-separated remote names) for any other
+ * layout (e.g. the common `origin`=fork / `upstream`=canonical convention).
+ *
+ * Split PURE helpers (parsing + remote-set/role/compare-ref decisions, unit
+ * tested) from the IO wrapper `getRepositoryStatus()` (touches git).
+ *
+ * PERFORMANCE: every git invocation is ASYNC (`execFile`), never `execFileSync`
+ * — the fetch path can spend `2 × FETCH_TIMEOUT_MS` per remote on the network,
+ * and a synchronous version froze the whole event loop (SSE, PTY streaming) for
+ * up to a minute per request. The computation is additionally single-flight
+ * with a short TTL cache: concurrent requests share one in-flight promise, and
+ * a fresh-enough result is served without spawning git at all.
+ *
+ * SECURITY: remote URLs (and git stderr echoing them) can embed
+ * `scheme://user:token@host` credentials, so every `url`/`error` field is
+ * passed through `redactGitCredentials()` (shared with `git-clone.ts`) before
+ * it reaches a client.
+ *
+ * @module web/repo-status
+ */
+
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { promisify } from 'node:util';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { gitNonInteractiveEnv, redactGitCredentials } from '../git-clone.js';
+import { getInstallInfo } from './self-update.js';
+import type { RepoIncomingCommit, RepoRemoteRole, RepoRemoteStatus, RepositoryStatusResult } from '../types/update.js';
+
+const require = createRequire(import.meta.url);
+const { version: APP_VERSION } = require('../../package.json') as { version: string };
+const execFileAsync = promisify(execFile);
+
+/** Network/git timeout for the fetch path (longer than EXEC_TIMEOUT_MS — hits network). */
+const FETCH_TIMEOUT_MS = 15_000;
+/** Max incoming commit subjects to list per remote. */
+const MAX_INCOMING = 10;
+/** Fresh-enough window for a cached status — repeated UI polls reuse it instead of re-running git. */
+const STATUS_CACHE_TTL_MS = 45_000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PURE helpers (unit tested, no IO)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse `git rev-list --left-right --count HEAD...<ref>` output.
+ * Git prints two tab-separated counts: LEFT (commits in HEAD not in ref → ahead)
+ * and RIGHT (commits in ref not in HEAD → behind). Returns null on malformed input.
+ */
+export function parseAheadBehind(out: string): { ahead: number; behind: number } | null {
+  const m = out.trim().match(/^(\d+)\s+(\d+)$/);
+  if (!m) return null;
+  return { ahead: parseInt(m[1], 10), behind: parseInt(m[2], 10) };
+}
+
+/**
+ * Parse `git log --oneline` output into commits. Each non-empty line is
+ * `<sha> <subject>`; the first whitespace-delimited token is the SHA.
+ */
+export function parseLogLines(out: string): RepoIncomingCommit[] {
+  const commits: RepoIncomingCommit[] = [];
+  for (const line of out.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const idx = trimmed.indexOf(' ');
+    if (idx === -1) {
+      commits.push({ sha: trimmed, subject: '' });
+    } else {
+      commits.push({ sha: trimmed.slice(0, idx), subject: trimmed.slice(idx + 1).trim() });
+    }
+  }
+  return commits;
+}
+
+/**
+ * Extract the default branch name from `git ls-remote --symref <remote> HEAD`
+ * output (a line like `ref: refs/heads/master\tHEAD`). Returns null if absent.
+ *
+ * SECURITY: this parses UNTRUSTED remote output, and the result flows into a
+ * later `git fetch <remote> <branch>` positional. The capture is constrained to
+ * start with an alphanumeric (no leading `-`) so a hostile remote can't return
+ * `ref: refs/heads/--upload-pack=<cmd>\tHEAD` and smuggle an argv flag (RCE) —
+ * see `isSafeGitPositional` for the defense-in-depth re-check at the call site.
+ */
+export function parseSymrefDefaultBranch(out: string): string | null {
+  const m = out.match(/^ref:\s+refs\/heads\/([A-Za-z0-9_./][A-Za-z0-9_./+-]*)\s+HEAD$/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Reject a value that would be unsafe as a git positional argument (remote name
+ * or branch). A leading `-` lets untrusted ls-remote/symref output or a stray
+ * `CODEMAN_UPDATE_REMOTES` entry inject an option (e.g. `--upload-pack=<cmd>`)
+ * into a subsequent `git fetch`. Empty values are rejected too.
+ */
+export function isSafeGitPositional(value: string | null | undefined): value is string {
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('-');
+}
+
+/** Split a comma-separated env value into trimmed, non-empty names. */
+export function parseRemotesEnv(value: string | null | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Decide which remote NAMES the status view covers, in display order.
+ *
+ * - If `envRemotes` is non-empty, use exactly those that actually exist (order
+ *   preserved). This is the full-control escape hatch.
+ * - Otherwise the union of `origin` (if it exists) and the tracking remote (if
+ *   any), deduped. The tracking remote is listed first when it isn't `origin`,
+ *   so "your fork" leads and "upstream" follows.
+ */
+export function resolveRemoteSet(opts: {
+  existingRemotes: string[];
+  trackingRemote: string | null;
+  envRemotes: string[];
+}): string[] {
+  const exists = new Set(opts.existingRemotes);
+  if (opts.envRemotes.length > 0) {
+    return dedupe(opts.envRemotes.filter((n) => exists.has(n)));
+  }
+  const out: string[] = [];
+  if (opts.trackingRemote && exists.has(opts.trackingRemote) && opts.trackingRemote !== 'origin') {
+    out.push(opts.trackingRemote);
+  }
+  if (exists.has('origin')) out.push('origin');
+  if (opts.trackingRemote && exists.has(opts.trackingRemote)) out.push(opts.trackingRemote);
+  return dedupe(out);
+}
+
+/** Classify a remote's role relative to the tracking remote. */
+export function roleForRemote(name: string, trackingRemote: string | null): RepoRemoteRole {
+  if (trackingRemote && name === trackingRemote) return 'tracking';
+  if (name === 'origin' || name === 'upstream') return 'upstream';
+  return 'other';
+}
+
+function dedupe(names: string[]): string[] {
+  return [...new Set(names)];
+}
+
+/**
+ * Extract the remote name from an `@{upstream}` short ref like `origin/master`.
+ *
+ * A ref with NO slash is a LOCAL-branch upstream (`git branch -u otherbranch`):
+ * `rev-parse --abbrev-ref @{upstream}` prints just the branch name, and there
+ * is no remote in it — the old `slice(0, indexOf('/'))` became `slice(0, -1)`
+ * there and yielded garbage like `maste`. Returns null for that case (treated
+ * as "no tracking remote"), and for empty/degenerate refs.
+ */
+export function parseTrackingRemote(trackingRef: string | null | undefined): string | null {
+  if (!trackingRef) return null;
+  const idx = trackingRef.indexOf('/');
+  if (idx <= 0) return null;
+  return trackingRef.slice(0, idx);
+}
+
+/**
+ * Redact embedded `scheme://user:secret@host` credentials from the fields of
+ * one remote's status that can carry them: the remote URL itself, and the
+ * error string (which may include git stderr echoing that URL back).
+ */
+export function redactRemoteStatus(status: RepoRemoteStatus): RepoRemoteStatus {
+  const out: RepoRemoteStatus = { ...status, url: redactGitCredentials(status.url) };
+  if (out.error !== undefined) out.error = redactGitCredentials(out.error);
+  return out;
+}
+
+/**
+ * Single-flight TTL cache around an async compute: concurrent callers await
+ * the SAME in-flight promise, and a result younger than `ttlMs` is returned
+ * without recomputing. A rejected compute is never cached, so the next call
+ * retries. `now` is injectable for deterministic TTL tests.
+ */
+export function createSingleFlightCache<T>(
+  ttlMs: number,
+  compute: () => Promise<T>
+): { get(now?: number): Promise<T> } {
+  let cachedAt = 0;
+  let cachedValue: T | undefined;
+  let hasValue = false;
+  let inFlight: Promise<T> | null = null;
+  return {
+    get(now = Date.now()): Promise<T> {
+      if (hasValue && now - cachedAt < ttlMs) return Promise.resolve(cachedValue as T);
+      if (inFlight) return inFlight;
+      inFlight = compute().then(
+        (value) => {
+          cachedValue = value;
+          hasValue = true;
+          cachedAt = Date.now();
+          inFlight = null;
+          return value;
+        },
+        (err: unknown) => {
+          inFlight = null;
+          throw err;
+        }
+      );
+      return inFlight;
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IO wrapper
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface GitResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Run git non-interactively (no credential or SSH prompts — a missing key/cred
+ * fails fast instead of hanging; env via the shared `gitNonInteractiveEnv()`,
+ * which also closes the askpass/GCM/DISPLAY prompt paths). ASYNC on purpose:
+ * the fetch path hits the network for up to `FETCH_TIMEOUT_MS`, and a sync
+ * spawn would block the event loop for the whole wait.
+ */
+async function runGit(args: string[], cwd: string, timeout = EXEC_TIMEOUT_MS): Promise<GitResult> {
+  try {
+    const { stdout } = await execFileAsync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout,
+      env: gitNonInteractiveEnv(),
+    });
+    return { ok: true, stdout: stdout.trim(), stderr: '' };
+  } catch (err: unknown) {
+    const e = err as { stdout?: Buffer | string; stderr?: Buffer | string };
+    return {
+      ok: false,
+      stdout: e.stdout ? String(e.stdout).trim() : '',
+      stderr: e.stderr ? String(e.stderr).trim() : '',
+    };
+  }
+}
+
+/** First line of stderr, trimmed — a compact human-readable failure reason. */
+function firstLine(s: string): string {
+  return (
+    s
+      .split('\n')
+      .find((l) => l.trim())
+      ?.trim() ?? 'git command failed'
+  );
+}
+
+/** Compute ahead/behind + incoming commits for one already-selected remote. */
+async function statusForRemote(
+  dir: string,
+  name: string,
+  trackingRemote: string,
+  trackingRef: string | null
+): Promise<RepoRemoteStatus> {
+  const role = roleForRemote(name, trackingRemote);
+  const url = (await runGit(['remote', 'get-url', name], dir)).stdout || '';
+  const base: RepoRemoteStatus = { name, url, role, compareRef: '', ahead: 0, behind: 0, incoming: [] };
+
+  // SECURITY: the remote name reaches git as a positional; reject a `-` prefix
+  // (e.g. a stray CODEMAN_UPDATE_REMOTES entry) before it can act as a flag.
+  if (!isSafeGitPositional(name)) {
+    return { ...base, error: `Refusing unsafe remote name "${name}".` };
+  }
+
+  // Resolve the compare ref + the remote branch to fetch.
+  let branch: string | null;
+  if (role === 'tracking' && trackingRef) {
+    // e.g. trackingRef = "bitbucket/local" → branch = "local"
+    branch = trackingRef.slice(name.length + 1) || null;
+  } else {
+    const symref = await runGit(['ls-remote', '--symref', name, 'HEAD'], dir, FETCH_TIMEOUT_MS);
+    branch = symref.ok ? parseSymrefDefaultBranch(symref.stdout) : null;
+    if (!branch && !symref.ok) {
+      return { ...base, error: `Could not reach ${name}: ${firstLine(symref.stderr)}` };
+    }
+    branch = branch ?? 'master';
+  }
+  if (!branch) return { ...base, error: `Could not resolve a branch on ${name}.` };
+  // SECURITY: defense-in-depth — `branch` may come from untrusted symref output
+  // or a tracking-ref slice; never let a `-`-prefixed value reach `git fetch`.
+  if (!isSafeGitPositional(branch)) {
+    return { ...base, error: `Refusing unsafe branch name "${branch}" from ${name}.` };
+  }
+  const compareRef = `${name}/${branch}`;
+
+  // Read-only fetch of just that ref so the local rev-list/log can see it.
+  // `--` ends option parsing so neither `name` nor `branch` can be read as a flag.
+  const fetched = await runGit(['fetch', '--no-tags', name, '--', branch], dir, FETCH_TIMEOUT_MS);
+  if (!fetched.ok) {
+    return { ...base, compareRef, error: `Could not fetch ${compareRef}: ${firstLine(fetched.stderr)}` };
+  }
+
+  const counts = await runGit(['rev-list', '--left-right', '--count', `HEAD...${compareRef}`], dir);
+  if (!counts.ok) {
+    return { ...base, compareRef, error: `Could not compare against ${compareRef}: ${firstLine(counts.stderr)}` };
+  }
+  const ab = parseAheadBehind(counts.stdout);
+  if (!ab) return { ...base, compareRef, error: `Unexpected git output comparing ${compareRef}.` };
+
+  const log = await runGit(['log', '--oneline', '-n', String(MAX_INCOMING), `HEAD..${compareRef}`], dir);
+  const incoming = log.ok ? parseLogLines(log.stdout) : [];
+
+  return { ...base, compareRef, ahead: ab.ahead, behind: ab.behind, incoming };
+}
+
+/** The uncached computation behind `getRepositoryStatus()`. */
+async function computeRepositoryStatus(): Promise<RepositoryStatusResult> {
+  const checkedAt = Date.now();
+  const info = getInstallInfo();
+  const base: RepositoryStatusResult = {
+    checkedAt,
+    isGit: info.installKind === 'git',
+    currentVersion: info.currentVersion || APP_VERSION,
+    remotes: [],
+  };
+  if (info.installKind !== 'git') {
+    return { ...base, error: 'Not a git install — repository status is unavailable.' };
+  }
+
+  const dir = info.installDir;
+
+  // Tracking ref of the current branch, e.g. "bitbucket/local" (empty if none).
+  const trackingRef =
+    (await runGit(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], dir)).stdout || null;
+  const trackingRemote = parseTrackingRemote(trackingRef);
+  // A local-branch upstream (no slash) carries no remote — drop the ref too, so
+  // nothing downstream can mistake a bare branch name for a remote-tracking ref.
+  const remoteTrackingRef = trackingRemote ? trackingRef : null;
+
+  const remotesOut = await runGit(['remote'], dir);
+  const existingRemotes = remotesOut.ok
+    ? remotesOut.stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  const selected = resolveRemoteSet({
+    existingRemotes,
+    trackingRemote,
+    envRemotes: parseRemotesEnv(process.env.CODEMAN_UPDATE_REMOTES),
+  });
+
+  if (selected.length === 0) {
+    return { ...base, error: 'No comparable remotes found (set CODEMAN_UPDATE_REMOTES to choose).' };
+  }
+
+  // Sequential on purpose: concurrent `git fetch` in one repo can contend on
+  // ref locks, and the event loop no longer cares how long this takes.
+  const remotes: RepoRemoteStatus[] = [];
+  for (const name of selected) {
+    // SECURITY: redact `scheme://user:token@host` credentials from the URL and
+    // any error string (git stderr echoes the URL back) before they leave the server.
+    remotes.push(redactRemoteStatus(await statusForRemote(dir, name, trackingRemote ?? '', remoteTrackingRef)));
+  }
+  return { ...base, remotes };
+}
+
+const statusCache = createSingleFlightCache(STATUS_CACHE_TTL_MS, computeRepositoryStatus);
+
+/**
+ * Inspect how the local checkout sits relative to the configured remotes.
+ * Each remote is fetched + compared independently; a single unreachable remote
+ * surfaces as that card's `error` and never fails the whole call.
+ *
+ * Single-flight + TTL-cached: concurrent requests share one in-flight
+ * computation, and a result younger than `STATUS_CACHE_TTL_MS` is served
+ * without spawning git.
+ */
+export function getRepositoryStatus(): Promise<RepositoryStatusResult> {
+  return statusCache.get();
+}

src/web/response-viewer-transcript.ts

@@ -0,0 +1,361 @@
+export type ResponseViewerTranscriptKind = 'prompt' | 'response' | 'status' | 'tool';
+
+export interface ResponseViewerTranscriptBlock {
+  kind: ResponseViewerTranscriptKind;
+  label: 'Prompt' | 'Response' | 'Status' | 'Tool';
+  /** What the frontend renders by: 'user' gets the "You" badge, everything else the agent badge. */
+  role: 'user' | 'assistant';
+  text: string;
+}
+
+// Keep in lockstep with isExternalCliMode() in src/session.ts. Importing it here
+// would drag node-pty and the whole session layer into this pure module, so the
+// list is duplicated and test/response-viewer-transcript.test.ts pins the parity.
+const EXTERNAL_CLI_MODES = new Set(['codex', 'gemini', 'opencode', 'antigravity', 'pi']);
+
+function isPromptLine(line: string): boolean {
+  return /^\s*›\s*/.test(line);
+}
+
+function isDividerDashChar(ch: string): boolean {
+  return ch === '─' || ch === '-';
+}
+
+function isWhitespaceChar(ch: string): boolean {
+  return /\s/.test(ch);
+}
+
+// Linear-time equivalent of the old /^[─-]+\s*(.+?)\s*[─-]{3,}$/. The lazy
+// middle of that pattern backtracked catastrophically on a long dash run that
+// does NOT end in 3+ dashes (measured >2min at 8,000 chars) — and pane text is
+// agent-controlled with buffers up to 32MB, so this ran on hostile input. Same
+// accept set and same captured content, computed with counters; equivalence is
+// pinned char-for-char against the old regex by the brute-force corpus test in
+// test/response-viewer-transcript.test.ts.
+function normalizeDividerStatusLine(line: string): string | null {
+  const s = line.trim();
+  const n = s.length;
+  // Minimum match: 1 leading dash + 1 content char + 3 trailing dashes.
+  if (n < 5) return null;
+
+  let lead = 0;
+  while (lead < n && isDividerDashChar(s.charAt(lead))) lead += 1;
+  if (lead === 0) return null;
+
+  let trail = 0;
+  while (trail < n && isDividerDashChar(s.charAt(n - 1 - trail))) trail += 1;
+  if (trail < 3) return null;
+
+  // The regex was greedy on the leading run but gave dashes back until at least
+  // one content char plus the 3-dash tail fit (an all-dash line matched with a
+  // single leftover dash as its "content"), so the content window starts at the
+  // end of the leading run, clamped to leave 4 chars.
+  const contentStart = Math.min(lead, n - 4);
+  let ws = 0;
+  while (contentStart + ws < n - 4 && isWhitespaceChar(s.charAt(contentStart + ws))) ws += 1;
+  const from = contentStart + ws;
+
+  // The lazy middle stopped at the first position from which "optional
+  // whitespace, then dashes to end-of-line" matches: the start of the
+  // whitespace padding in front of the trailing dash run (never before the
+  // first content char).
+  const tailStart = n - trail;
+  let padded = tailStart;
+  while (padded > 0 && isWhitespaceChar(s.charAt(padded - 1))) padded -= 1;
+  const end = Math.max(from + 1, padded);
+
+  return s.slice(from, end).trim() || null;
+}
+
+function isDividerOnlyLine(line: string): boolean {
+  return /^[\s─-]{8,}$/.test(line.trim());
+}
+
+// COD-227: unambiguous Codex tool-call markers. These only ever appear as internal
+// activity, never as ordinary assistant prose, so they are always a Tool block.
+function isToolActivityMarker(line: string): boolean {
+  return /^\s*[•*-]\s+(Calling|Called)\b/.test(line.trim());
+}
+
+// COD-227: action verbs that ALSO occur in ordinary assistant prose (e.g.
+// "• Created COD-226: …"). These are a Tool header only when corroborated by a
+// box-drawing result tree on the next non-blank line (see the caller); the verb
+// alone is not sufficient.
+function isToolVerbBullet(line: string): boolean {
+  return /^\s*[•*-]\s+(Explored|Viewed|Read|Edited|Updated|Created|Deleted|Ran|Searched|Opened|Listed|Found|Applied|Patched|Used|Wrote|Executed|Modified|Analyzed|Compared|Fetched|Installed)\b/.test(
+    line.trim()
+  );
+}
+
+// A genuine Codex tool block renders its result as a box-drawing tree (└ │ ├).
+function isBoxDrawingLine(line: string): boolean {
+  return /^[│├└]/.test(line.trim());
+}
+
+// Look past blank lines from `fromIndex + 1` for the next non-blank line and report
+// whether it is a box-drawing tool-result line — the signal that a verb bullet is a
+// real tool block rather than assistant prose that happens to start with a verb.
+function nextNonBlankIsBoxDrawing(lines: string[], fromIndex: number): boolean {
+  for (let j = fromIndex + 1; j < lines.length; j += 1) {
+    const trimmed = (lines[j] || '').trim();
+    if (!trimmed) continue;
+    return isBoxDrawingLine(trimmed);
+  }
+  return false;
+}
+
+function isToolContinuationLine(line: string, currentKind: ResponseViewerTranscriptKind | null): boolean {
+  if (currentKind !== 'tool') return false;
+  const trimmed = line.trimEnd();
+  if (!trimmed) return true;
+  return /^\s*[│├└]/.test(trimmed) || /^\s{2,}\S/.test(line);
+}
+
+function isStatusLine(line: string, mode: string): boolean {
+  if (!EXTERNAL_CLI_MODES.has(mode)) return false;
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  if (normalizeDividerStatusLine(trimmed)) return true;
+  if (/^(model|directory):\s+/i.test(trimmed)) return true;
+  if (/\bContext\b.*\bleft\b/i.test(trimmed)) return true;
+  if (/\b\/model to change\b/i.test(trimmed)) return true;
+  if (/\bReady\b/i.test(trimmed) && /·/.test(trimmed)) return true;
+  if (/^(gpt|o\d|claude|gemini)\b/i.test(trimmed) && /·/.test(trimmed)) return true;
+  if (/^Tip:/i.test(trimmed)) return true;
+  if (/^\s*[•*-]\s+(Working|Thinking|Loading|Starting\b|Waiting\b)/i.test(trimmed)) return true;
+  return false;
+}
+
+function isStandaloneMarkdownLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  if (/^#{1,6}\s/.test(trimmed)) return true;
+  if (/^>\s/.test(trimmed)) return true;
+  if (/^(```|~~~)/.test(trimmed)) return true;
+  if (/^[-*+]\s/.test(trimmed)) return true;
+  if (/^\d+[.)]\s/.test(trimmed)) return true;
+  if (/^\|/.test(trimmed)) return true;
+  if (/^\s{4,}\S/.test(line)) return true;
+  return false;
+}
+
+function shouldJoinWrappedLine(previous: string, next: string): boolean {
+  const prev = previous.trimEnd();
+  const curr = next.trim();
+  if (!prev || !curr) return false;
+  if (/[.!?]$/.test(prev)) return false;
+  if (/[:;]$/.test(prev)) return false;
+  if (isStandaloneMarkdownLine(curr)) return false;
+  if (/^[a-z(]/.test(curr)) return true;
+  if (prev.length >= 72 && /^[A-Za-z0-9"'(]/.test(curr)) return true;
+  return false;
+}
+
+function normalizeWrappedText(lines: string[]): string {
+  const out: string[] = [];
+  let paragraph = '';
+
+  const flushParagraph = () => {
+    if (!paragraph) return;
+    out.push(paragraph);
+    paragraph = '';
+  };
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    const trimmed = line.trim();
+    if (!trimmed) {
+      flushParagraph();
+      if (out[out.length - 1] !== '') out.push('');
+      continue;
+    }
+    if (isStandaloneMarkdownLine(line)) {
+      flushParagraph();
+      out.push(trimmed);
+      continue;
+    }
+    if (!paragraph) {
+      paragraph = trimmed;
+      continue;
+    }
+    if (shouldJoinWrappedLine(paragraph, trimmed)) {
+      paragraph += ` ${trimmed}`;
+      continue;
+    }
+    flushParagraph();
+    paragraph = trimmed;
+  }
+
+  flushParagraph();
+  return out
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function cleanTerminalTranscript(buffer: string): string {
+  // Stripping ANSI/OSC/DCS escape sequences and stray C0/C1 control bytes
+  // legitimately requires control characters in these patterns.
+  /* eslint-disable no-control-regex */
+  return String(buffer || '')
+    .replace(/\x1b\[[\x30-\x3F]*[\x20-\x2F]*[\x40-\x7E]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b[PX^_][^\x1b]*\x1b\\/g, '')
+    .replace(/\x1b[NO()][A-Z0-9]?/g, '')
+    .replace(/\x1b[>=<78cDEHM]/g, '')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/[ \t]+$/gm, '')
+    .trim();
+  /* eslint-enable no-control-regex */
+}
+
+function trimLeadingStartup(lines: string[]): string[] {
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index] || '';
+    const trimmed = line.trim();
+    if (!trimmed) {
+      index += 1;
+      continue;
+    }
+    if (/^[╭╰│─].*[╮╯│]?$/.test(trimmed)) {
+      index += 1;
+      continue;
+    }
+    if (/^>_\s*OpenAI Codex/i.test(trimmed)) {
+      index += 1;
+      continue;
+    }
+    if (/^(model|directory):\s+/i.test(trimmed)) {
+      index += 1;
+      continue;
+    }
+    break;
+  }
+  return lines.slice(index);
+}
+
+function pushBlock(
+  blocks: ResponseViewerTranscriptBlock[],
+  kind: ResponseViewerTranscriptKind | null,
+  lines: string[]
+): void {
+  if (!kind || lines.length === 0) return;
+  const normalizedLines =
+    kind === 'status'
+      ? lines.map((line) => normalizeDividerStatusLine(line) || line.trim()).filter((line) => line.length > 0)
+      : lines;
+  const text =
+    kind === 'tool' || kind === 'status'
+      ? normalizedLines
+          .join('\n')
+          .replace(/\n{3,}/g, '\n\n')
+          .trim()
+      : normalizeWrappedText(normalizedLines);
+  if (!text) return;
+  const label = (kind.charAt(0).toUpperCase() + kind.slice(1)) as ResponseViewerTranscriptBlock['label'];
+  // The frontend's loadFullContext() renders via msg.role — a block without it
+  // lost the "You" badge on prompts and rendered every block as the agent.
+  blocks.push({ kind, label, role: kind === 'prompt' ? 'user' : 'assistant', text });
+}
+
+export function isExternalCliTranscriptMode(mode: string | null | undefined): boolean {
+  return EXTERNAL_CLI_MODES.has(String(mode || ''));
+}
+
+export function parseExternalCliTranscript(
+  buffer: string,
+  mode: string | null | undefined
+): ResponseViewerTranscriptBlock[] {
+  const resolvedMode = String(mode || '');
+  if (!isExternalCliTranscriptMode(resolvedMode)) return [];
+
+  const cleaned = cleanTerminalTranscript(buffer);
+  if (!cleaned) return [];
+
+  const lines = trimLeadingStartup(cleaned.split('\n'));
+  const blocks: ResponseViewerTranscriptBlock[] = [];
+  let currentKind: ResponseViewerTranscriptKind | null = null;
+  let currentLines: string[] = [];
+
+  const flush = () => {
+    pushBlock(blocks, currentKind, currentLines);
+    currentKind = null;
+    currentLines = [];
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? '';
+    // COD-226: within a prompt, the 2-space Codex gutter is authoritative. Blank
+    // lines and gutter-indented (2+ leading spaces) continuation lines stay in the
+    // Prompt block ahead of every structural detector below, so multiline prompts —
+    // including bullets, indented dividers, and literal › lines — are not
+    // misclassified as responses. Only a non-blank, non-gutter line ends the prompt
+    // and falls through (a column-0 › then opens a NEW prompt).
+    if (currentKind === 'prompt') {
+      if (!line.trim()) {
+        currentLines.push('');
+        continue;
+      }
+      if (/^ {2,}\S/.test(line)) {
+        currentLines.push(line);
+        continue;
+      }
+    }
+
+    if (isDividerOnlyLine(line)) {
+      flush();
+      continue;
+    }
+
+    if (isPromptLine(line)) {
+      flush();
+      currentKind = 'prompt';
+      currentLines = [line.replace(/^\s*›\s*/, '').trim()];
+      continue;
+    }
+
+    // COD-227: • Calling / • Called are always tool markers; the other action verbs
+    // are a tool header only when a box-drawing result tree follows on the next
+    // non-blank line — otherwise the verb bullet is ordinary assistant prose.
+    if (isToolActivityMarker(line) || (isToolVerbBullet(line) && nextNonBlankIsBoxDrawing(lines, i))) {
+      if (currentKind !== 'tool') flush();
+      currentKind = 'tool';
+      currentLines.push(line.trimEnd());
+      continue;
+    }
+
+    if (isToolContinuationLine(line, currentKind)) {
+      currentLines.push(line.trimEnd());
+      continue;
+    }
+
+    if (isStatusLine(line, resolvedMode)) {
+      if (currentKind !== 'status') flush();
+      currentKind = 'status';
+      currentLines.push(line.trim());
+      continue;
+    }
+
+    if (!line.trim()) {
+      currentLines.push('');
+      continue;
+    }
+
+    if (currentKind !== 'response') flush();
+    currentKind = 'response';
+    currentLines.push(line);
+  }
+
+  flush();
+  return blocks.filter((block) => block.text.trim().length > 0);
+}
+
+export function getLastTranscriptResponse(blocks: ResponseViewerTranscriptBlock[]): string {
+  for (let i = blocks.length - 1; i >= 0; i -= 1) {
+    if (blocks[i]?.kind === 'response') return blocks[i].text;
+  }
+  return '';
+}

src/web/routes/session-routes.ts

@@ -12,6 +12,7 @@ import { existsSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import fs from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
 import {
   ApiErrorCode,
   createErrorResponse,
@@ -131,6 +132,11 @@ import {
   toSessionDocker,
 } from '../../docker-hosts.js';
 import { LRUMap } from '../../utils/lru-map.js';
+import {
+  getLastTranscriptResponse,
+  isExternalCliTranscriptMode,
+  parseExternalCliTranscript,
+} from '../response-viewer-transcript.js';
 
 // Path to linked-cases registry (same file used by case-routes resolveCasePath)
 const LINKED_CASES_FILE = dataPath('linked-cases.json');
@@ -797,54 +803,42 @@ export function registerSessionRoutes(
       }
     }
 
-    // Check OpenCode availability if requested
+    // Check OpenCode availability if requested. The error text comes from the
+    // resolver (formatCliNotFoundMessage) so it names where resolution looked —
+    // server PATH, login shell, common directories — same for the modes below.
     if (body.mode === 'opencode') {
-      const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
+      const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } = await import('../../utils/opencode-cli-resolver.js');
       if (!isOpenCodeAvailable()) {
-        return createErrorResponse(
-          ApiErrorCode.OPERATION_FAILED,
-          'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash'
-        );
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getOpenCodeNotFoundMessage());
       }
     }
 
     // Check Codex availability if requested
     if (body.mode === 'codex') {
-      const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
+      const { isCodexAvailable, getCodexNotFoundMessage } = await import('../../utils/codex-cli-resolver.js');
       if (!isCodexAvailable()) {
-        return createErrorResponse(
-          ApiErrorCode.OPERATION_FAILED,
-          'Codex CLI not found. Install with: npm install -g @openai/codex'
-        );
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getCodexNotFoundMessage());
       }
     }
 
     // Check Gemini availability if requested
     if (body.mode === 'gemini') {
-      const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
+      const { isGeminiAvailable, getGeminiNotFoundMessage } = await import('../../utils/gemini-cli-resolver.js');
       if (!isGeminiAvailable()) {
-        return createErrorResponse(
-          ApiErrorCode.OPERATION_FAILED,
-          'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
-        );
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getGeminiNotFoundMessage());
       }
     }
     if (body.mode === 'antigravity') {
-      const { isAntigravityAvailable } = await import('../../utils/antigravity-cli-resolver.js');
+      const { isAntigravityAvailable, getAntigravityNotFoundMessage } =
+        await import('../../utils/antigravity-cli-resolver.js');
       if (!isAntigravityAvailable()) {
-        return createErrorResponse(
-          ApiErrorCode.OPERATION_FAILED,
-          'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
-        );
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage());
       }
     }
     if (body.mode === 'pi') {
-      const { isPiAvailable } = await import('../../utils/pi-cli-resolver.js');
+      const { isPiAvailable, getPiNotFoundMessage } = await import('../../utils/pi-cli-resolver.js');
       if (!isPiAvailable()) {
-        return createErrorResponse(
-          ApiErrorCode.OPERATION_FAILED,
-          'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
-        );
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getPiNotFoundMessage());
       }
     }
 
@@ -1898,6 +1892,22 @@ export function registerSessionRoutes(
       return await readCodexLastResponse(session, codexQuery.context === 'full');
     }
 
+    // OpenCode / Gemini / Antigravity / Pi render their own TUIs and write no
+    // Claude transcript, so the scan below finds nothing and the response viewer
+    // renders permanently empty for them. Segment the terminal buffer instead —
+    // the pane IS the transcript for these CLIs. Codex is already handled above,
+    // where a real rollout file is the better source.
+    if (isExternalCliTranscriptMode(session.mode)) {
+      const externalQuery = req.query as { context?: string };
+      const blocks = parseExternalCliTranscript(session.terminalBuffer, session.mode);
+      return {
+        text: getLastTranscriptResponse(blocks),
+        timestamp: '',
+        hasContext: blocks.length > 0,
+        messages: externalQuery.context === 'full' ? blocks : undefined,
+      };
+    }
+
     // Scan ~/.claude/projects/*/ for the transcript file
     const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects');
 
@@ -2270,18 +2280,17 @@ export function registerSessionRoutes(
 
   // Query params:
   //   tail=<bytes> - Only return last N bytes (faster initial load)
-  //   full=1       - Full page reload: replay the entire tmux scrollback (COD-47)
-  app.get('/api/sessions/:id/terminal', async (req) => {
+  //   full=1       - Explicitly request the entire tmux scrollback (COD-47)
+  app.get('/api/sessions/:id/terminal', async (req, reply) => {
+    const routeStartedAt = performance.now();
     const { id } = req.params as { id: string };
     const query = req.query as { tail?: string; full?: string };
     const session = findSessionOrFail(ctx, id, req);
 
-    // `full=1` is the EXPLICIT full-reload signal (COD-47): the browser reloaded
-    // the page and wants the whole scroll history back, so we capture the ENTIRE
-    // tmux scrollback and the user gets back history that scrolled off Codeman's
-    // byte buffer. Requests WITHOUT it — tab switches (`tail=`) and the legacy
-    // no-param callers (response-viewer fallback, clearTerminal refresh) — keep
-    // the fast visible-frame capture.
+    // `full=1` is the EXPLICIT full-history signal (COD-47): capture the ENTIRE
+    // tmux scrollback so history beyond the server byte buffer can be recovered.
+    // Requests WITHOUT it — shell selection/tab switches (`tail=`) and legacy
+    // no-param callers — keep the fast visible-frame capture.
     const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
     const isFullReload = query.full === '1' || query.full === 'true';
     const { tmuxHistoryLimit, terminalBufferMaxBytes } = await ctx.getTerminalHistoryConfig();
@@ -2294,6 +2303,7 @@ export function registerSessionRoutes(
     // overlap. `captureActivePaneBuffer` is a no-op ('') under test mode and
     // returns null when unavailable, in which case we fall back to history.
     const muxName = session.muxName;
+    const captureStartedAt = performance.now();
     const liveMuxBuffer =
       muxName && typeof ctx.mux.captureActivePaneBuffer === 'function'
         ? ctx.mux.captureActivePaneBuffer(
@@ -2303,6 +2313,7 @@ export function registerSessionRoutes(
               : undefined
           )
         : null;
+    const captureFinishedAt = performance.now();
     const hasLiveMuxBuffer = liveMuxBuffer !== null && liveMuxBuffer.length > 0;
     const source: 'history' | 'mux-visible' | 'mux-full-history' = hasLiveMuxBuffer
       ? isFullReload
@@ -2406,6 +2417,14 @@ export function registerSessionRoutes(
     // Remove Ctrl+L and leading whitespace (cheap on tailed subset)
     cleanBuffer = cleanBuffer.replace(CTRL_L_PATTERN, '').replace(LEADING_WHITESPACE_PATTERN, '');
 
+    const finishedAt = performance.now();
+    reply.header(
+      'Server-Timing',
+      `capture;dur=${(captureFinishedAt - captureStartedAt).toFixed(1)}, ` +
+        `prepare;dur=${(finishedAt - captureFinishedAt).toFixed(1)}, ` +
+        `total;dur=${(finishedAt - routeStartedAt).toFixed(1)}`
+    );
+
     return {
       terminalBuffer: cleanBuffer,
       status: session.status,
@@ -2806,58 +2825,46 @@ export function registerSessionRoutes(
         dockerResumeId = dockerCase.lastClaudeSessionId;
       }
     } else {
-      // Check OpenCode availability if requested
+      // Check OpenCode availability if requested. Error text comes from the
+      // resolver so it carries the resolution diagnostics; same for the modes below.
       if (mode === 'opencode') {
-        const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
+        const { isOpenCodeAvailable, getOpenCodeNotFoundMessage } =
+          await import('../../utils/opencode-cli-resolver.js');
         if (!isOpenCodeAvailable()) {
-          return createErrorResponse(
-            ApiErrorCode.OPERATION_FAILED,
-            'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash'
-          );
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getOpenCodeNotFoundMessage());
         }
       }
 
       // Check Codex availability if requested
       if (mode === 'codex') {
-        const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
+        const { isCodexAvailable, getCodexNotFoundMessage } = await import('../../utils/codex-cli-resolver.js');
         if (!isCodexAvailable()) {
-          return createErrorResponse(
-            ApiErrorCode.OPERATION_FAILED,
-            'Codex CLI not found. Install with: npm install -g @openai/codex'
-          );
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getCodexNotFoundMessage());
         }
       }
 
       // Check Gemini availability if requested
       if (mode === 'gemini') {
-        const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
+        const { isGeminiAvailable, getGeminiNotFoundMessage } = await import('../../utils/gemini-cli-resolver.js');
         if (!isGeminiAvailable()) {
-          return createErrorResponse(
-            ApiErrorCode.OPERATION_FAILED,
-            'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
-          );
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getGeminiNotFoundMessage());
         }
       }
 
       // Check Antigravity availability if requested
       if (mode === 'antigravity') {
-        const { isAntigravityAvailable } = await import('../../utils/antigravity-cli-resolver.js');
+        const { isAntigravityAvailable, getAntigravityNotFoundMessage } =
+          await import('../../utils/antigravity-cli-resolver.js');
         if (!isAntigravityAvailable()) {
-          return createErrorResponse(
-            ApiErrorCode.OPERATION_FAILED,
-            'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
-          );
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getAntigravityNotFoundMessage());
         }
       }
 
       // Check Pi availability if requested
       if (mode === 'pi') {
-        const { isPiAvailable } = await import('../../utils/pi-cli-resolver.js');
+        const { isPiAvailable, getPiNotFoundMessage } = await import('../../utils/pi-cli-resolver.js');
         if (!isPiAvailable()) {
-          return createErrorResponse(
-            ApiErrorCode.OPERATION_FAILED,
-            'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
-          );
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getPiNotFoundMessage());
         }
       }
 

src/web/routes/system-routes.ts

@@ -48,6 +48,7 @@ import {
 } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import { getInstallInfo, checkForUpdate, startUpdate, getUpdateStatusForApi } from '../self-update.js';
+import { getRepositoryStatus } from '../repo-status.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { QR_AUTH_FAILURE_MAX } from '../../config/tunnel-config.js';
@@ -354,6 +355,11 @@ export function registerSystemRoutes(
   // Poll target for update progress — survives the restart the update triggers.
   app.get('/api/system/update/status', async () => getUpdateStatusForApi());
 
+  // Informational companion to the release-tag updater above: what this CHECKOUT
+  // looks like against its own remotes (ahead/behind, incoming commits), which a
+  // release tag cannot answer for a git install tracking a branch.
+  app.get('/api/system/repo-status', async () => getRepositoryStatus());
+
   // Kick off a detached update to the latest release. Returns immediately; the
   // browser then polls /api/system/update/status across the service restart.
   app.post('/api/system/update', async (_req, reply) => {
@@ -722,7 +728,8 @@ export function registerSystemRoutes(
       const merged = { ...existing, ...settingsToStore };
       await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2));
 
-      // Apply a changed tmux history-limit to all live sessions immediately.
+      // tmux 3.7+ resizes tracked panes; older versions apply this to new panes.
+      // Already-evicted history cannot be recovered on either version.
       if (settings.tmuxHistoryLimit !== undefined) {
         await ctx.mux.setHistoryLimit(resolveTerminalHistoryConfig(merged).tmuxHistoryLimit);
       }

src/web/server.ts

@@ -41,6 +41,7 @@ import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
 import { hostname as getHostname } from 'node:os';
 import { dataPath, getDataDir, CODEMAN_INSTANCE } from '../config/instance.js';
+import { GLYPH, palette } from '../cli-style.js';
 import { getHookSecret } from '../config/hook-secret.js';
 import { EventEmitter } from 'node:events';
 import { Session, isExternalCliMode, type BackgroundTask } from '../session.js';
@@ -2395,7 +2396,9 @@ export class WebServer extends EventEmitter {
     await this.app.listen({ port: this.port, host: this.host });
     const protocol = this.https ? 'https' : 'http';
     const displayHost = this.host === '0.0.0.0' ? 'localhost' : this.host;
-    console.log(`Codeman web interface running at ${protocol}://${displayHost}:${this.port}`);
+    // The only startup banner: `codeman web` used to print its own copy of this
+    // line, but the daemon and service launch paths never go through the CLI.
+    console.log(palette.ok(`${GLYPH.ok} Codeman web interface running at ${protocol}://${displayHost}:${this.port}`));
 
     // Opt-in: also serve the HOOK endpoints on the docker bridge gateway so
     // in-container hooks (permission/idle/stop callbacks) can reach a loopback-bound
@@ -2425,20 +2428,30 @@ export class WebServer extends EventEmitter {
     // without CODEMAN_PASSWORD (every person has their own credential).
     const authActive = !!process.env.CODEMAN_PASSWORD || (isMultiUserMode() && (await hasUsers()));
     if (!isLoopbackBindHost(this.host) && !authActive) {
+      // Painted like the CLI's copy of the same warning. chalk degrades to plain
+      // text off a TTY, so journald and web.log stay free of escape codes.
       if (this.allowUnauthenticatedNetwork) {
         console.warn(
-          `\n⚠  Codeman is reachable WITHOUT a password on ${displayHost}:${this.port} ` +
-            '(explicitly allowed). Anyone who can reach it can control your Claude sessions.\n'
+          palette.warn(
+            `\n${GLYPH.warn}  Codeman is reachable WITHOUT a password on ${displayHost}:${this.port} ` +
+              '(explicitly allowed). Anyone who can reach it can control your Claude sessions.\n'
+          )
         );
       } else {
-        console.warn(`\n⚠  WARNING: Codeman is bound to a non-loopback host (${this.host}) with NO password.`);
-        console.warn(`   Anyone who can reach ${displayHost}:${this.port} can control your Claude sessions.`);
-        console.warn('   Secure it with ONE of:');
-        console.warn('     • set CODEMAN_PASSWORD=<password>   (HTTP Basic auth), or');
-        console.warn('     • bind loopback only: --host 127.0.0.1, then front it with an');
-        console.warn('       authenticated tunnel (cloudflared) or `tailscale serve`, or');
-        console.warn('     • keep this bind and accept the risk: --allow-unauthenticated-network');
-        console.warn('   See docs/security-architecture.md for details.\n');
+        console.warn(
+          palette.err(
+            `\n${GLYPH.warn}  WARNING: Codeman is bound to a non-loopback host (${this.host}) with NO password.`
+          )
+        );
+        console.warn(
+          palette.err(`   Anyone who can reach ${displayHost}:${this.port} can control your Claude sessions.`)
+        );
+        console.warn(palette.warn('   Secure it with ONE of:'));
+        console.warn(palette.warn('     • set CODEMAN_PASSWORD=<password>   (HTTP Basic auth), or'));
+        console.warn(palette.warn('     • bind loopback only: --host 127.0.0.1, then front it with an'));
+        console.warn(palette.warn('       authenticated tunnel (cloudflared) or `tailscale serve`, or'));
+        console.warn(palette.warn('     • keep this bind and accept the risk: --allow-unauthenticated-network'));
+        console.warn(palette.muted('   See docs/security-architecture.md for details.\n'));
       }
     }
 

src/web/session-listener-wiring.ts

@@ -52,6 +52,7 @@ export interface SessionListenerRefs {
   limitResumeCancelled: (data: { reason: string }) => void;
   respawnBreakerTripped: (data: { count: number }) => void;
   cliInfoUpdated: (data: { version?: string; model?: string; accountType?: string; latestVersion?: string }) => void;
+  mouseTrackingChanged: (active: boolean) => void;
   ralphLoopUpdate: (state: RalphTrackerState) => void;
   ralphTodoUpdate: (todos: RalphTodoItem[]) => void;
   ralphCompletionDetected: (phrase: string) => void;
@@ -219,10 +220,18 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
       // An idle-prompt inbox item means "composer is waiting"; any working
       // transition means input arrived, so the item is moot. ONLY the idle
       // kind: `working` is heuristic and can flap mid-turn, so clearing a
-      // pending permission/question dialog on it would false-clear real
-      // approvals (those resolve via stop / elicitation hooks / answer-time
-      // re-capture instead).
+      // pending permission/question dialog on the signal ALONE would
+      // false-clear real approvals.
       approvalInbox.resolveForSession(session.id, 'resolved_in_terminal', ['idle']);
+      // A permission/question dialog gets the pane-VERIFIED variant instead:
+      // the signal only decides when to look, `verifyStillAnswerable` re-reads
+      // the screen and resolves only when the dialog is really gone. Without
+      // this, answering a dialog in the terminal left its red "needs you" alert
+      // armed for the rest of the turn, because the only other staleness check
+      // lives in `GET /api/approvals` and nothing calls that while a page is
+      // open. `stop` was the first thing to clear it, which on a long turn is
+      // minutes away.
+      approvalInbox.resolveIfDialogGone(session.id);
       deps.broadcast(SseEvent.SessionWorking, { id: session.id });
       // Full state ride-along: the home screens sort the running group on
       // lastSubmitAt, and without this the browser keeps the stamp it loaded
@@ -342,6 +351,20 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
       deps.broadcastSessionStateDebounced(session.id);
     },
 
+    /**
+     * The CLI turned mouse tracking on or off (observed while stripping the
+     * DECSETs out of the stream). Rides the full session state so the browser
+     * learns it through the session object it already merges, with no new SSE
+     * event to keep in sync across the two registries.
+     *
+     * Broadcast IMMEDIATELY, not debounced: this flips when a dialog opens, and
+     * a user can click that dialog inside the 500ms debounce window, which is
+     * exactly the click that has to be reported.
+     */
+    mouseTrackingChanged: () => {
+      deps.broadcast(SseEvent.SessionUpdated, { session: deps.getSessionStateWithRespawn(session) });
+    },
+
     // ─── Ralph Tracking Events ──────────────────────────────
 
     /** Broadcasts `session:ralphLoopUpdate` — Ralph tracker loop state changed (iteration, phase) */
@@ -453,6 +476,7 @@ export function attachSessionListeners(session: Session, refs: SessionListenerRe
   session.on('limitResumeCancelled', refs.limitResumeCancelled);
   session.on('respawnBreakerTripped', refs.respawnBreakerTripped);
   session.on('cliInfoUpdated', refs.cliInfoUpdated);
+  session.on('mouseTrackingChanged', refs.mouseTrackingChanged);
   session.on('ralphLoopUpdate', refs.ralphLoopUpdate);
   session.on('ralphTodoUpdate', refs.ralphTodoUpdate);
   session.on('ralphCompletionDetected', refs.ralphCompletionDetected);
@@ -487,6 +511,7 @@ export function detachSessionListeners(session: Session, refs: SessionListenerRe
   session.off('limitResumeCancelled', refs.limitResumeCancelled);
   session.off('respawnBreakerTripped', refs.respawnBreakerTripped);
   session.off('cliInfoUpdated', refs.cliInfoUpdated);
+  session.off('mouseTrackingChanged', refs.mouseTrackingChanged);
   session.off('ralphLoopUpdate', refs.ralphLoopUpdate);
   session.off('ralphTodoUpdate', refs.ralphTodoUpdate);
   session.off('ralphCompletionDetected', refs.ralphCompletionDetected);

test/antigravity-cli-resolver.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Tests for the Antigravity CLI resolver wrapper.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAntigravityResolverForTest, isAntigravityAvailable } from '../src/utils/antigravity-cli-resolver.js';
+import {
+  cliResolveRetryDelayMs,
+  type CliResolution,
+  type CliResolverHost,
+} from '../src/utils/cli-executable-resolver.js';
+
+const availabilityResolution = vi.hoisted(() => ({ current: null as CliResolution | null }));
+
+vi.mock('../src/utils/cli-executable-resolver.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/utils/cli-executable-resolver.js')>();
+  return {
+    ...actual,
+    createCliExecutableResolver: (options: { binary: string; searchDirs: string[] }, host?: CliResolverHost) =>
+      host
+        ? actual.createCliExecutableResolver(options, host)
+        : {
+            resolve: () => availabilityResolution.current,
+            diagnostics: () => ({
+              binary: options.binary,
+              processPath: '/service/bin',
+              shellPath: '/bin/zsh',
+              shellArgs: ['-l'],
+              searchDirs: [...options.searchDirs],
+            }),
+          },
+  };
+});
+
+function createHost(
+  options: {
+    processPathResult?: string | null;
+    loginShellResults?: Array<string | null>;
+    existingPaths?: string[];
+  } = {}
+): CliResolverHost {
+  const loginShellResults = [...(options.loginShellResults ?? [])];
+  const existingPaths = new Set(options.existingPaths ?? []);
+  return {
+    processPath: '/service/bin',
+    shellPath: '/bin/zsh',
+    shellArgs: ['-l'],
+    findOnProcessPath: () => options.processPathResult ?? null,
+    findInLoginShell: () => loginShellResults.shift() ?? null,
+    exists: (path) => existingPaths.has(path),
+  };
+}
+
+describe('Antigravity CLI resolver', () => {
+  beforeEach(() => {
+    availabilityResolution.current = null;
+  });
+
+  it('resolves agy from the service PATH', () => {
+    const binaryPath = '/service/bin/agy';
+    const resolver = createAntigravityResolverForTest(
+      createHost({ processPathResult: binaryPath, existingPaths: [binaryPath] })
+    );
+
+    expect(resolver.resolve()?.directory).toBe('/service/bin');
+  });
+
+  it('falls back to a common install directory', () => {
+    const binaryPath = join(homedir(), '.local', 'bin', 'agy');
+    const resolver = createAntigravityResolverForTest(createHost({ existingPaths: [binaryPath] }));
+
+    expect(resolver.resolve()?.directory).toBe(join(homedir(), '.local', 'bin'));
+  });
+
+  it('resolves agy found only by the login shell', () => {
+    const binaryPath = '/login-shell/bin/agy';
+    const resolver = createAntigravityResolverForTest(
+      createHost({ loginShellResults: [binaryPath], existingPaths: [binaryPath] })
+    );
+
+    expect(resolver.resolve()?.directory).toBe('/login-shell/bin');
+  });
+
+  it('returns null when agy is unavailable', () => {
+    const resolver = createAntigravityResolverForTest(createHost());
+
+    expect(resolver.resolve()).toBeNull();
+  });
+
+  it('retries a failed lookup after the backoff and caches the first successful login-shell discovery', () => {
+    const binaryPath = '/late-login-shell/bin/agy';
+    let now = 0;
+    const resolver = createAntigravityResolverForTest(
+      createHost({ loginShellResults: [null, binaryPath], existingPaths: [binaryPath] }),
+      () => now
+    );
+
+    expect(resolver.resolve()).toBeNull();
+    // A miss is negative-cached: within the backoff window nothing re-runs the
+    // chain (its login-shell tail is a synchronous bounded spawn in production).
+    expect(resolver.resolve()).toBeNull();
+    now = cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()?.binaryPath).toBe(binaryPath);
+    expect(resolver.resolve()?.binaryPath).toBe(binaryPath);
+  });
+
+  it('reports the public wrapper as available when agy resolves', () => {
+    availabilityResolution.current = {
+      binaryPath: '/service/bin/agy',
+      directory: '/service/bin',
+      source: 'process-path',
+    };
+
+    expect(isAntigravityAvailable()).toBe(true);
+  });
+
+  it('reports the public wrapper as unavailable when agy does not resolve', () => {
+    expect(isAntigravityAvailable()).toBe(false);
+  });
+});

test/approval-inbox.test.ts

@@ -40,6 +40,39 @@ const ASK_USER_QUESTION_FRAME = [
   'Enter to select · ↑/↓ to navigate · Esc to cancel',
 ].join('\n');
 
+// Both frames captured off a live Claude Code v2.1.237 pane. They are the
+// discriminator behind the late-hook resolution: a modal dialog BLOCKS the
+// turn, so a working line and a dialog cannot coexist. Note the dialog frame
+// carries no `esc to interrupt` footer either — the dialog replaces it.
+const LIVE_DIALOG_FRAME = [
+  '● Bash(sleep 12; echo "slept 12s")',
+  '  ⎿  slept 12s',
+  '────────────────────────────────────────',
+  ' ☐ Proceed',
+  '',
+  'Proceed?',
+  '',
+  '❯ 1. Yes',
+  '     Go ahead and proceed.',
+  '  2. No',
+  '     Do not proceed.',
+  '  3. Type something.',
+  '────────────────────────────────────────',
+  '  4. Chat about this',
+  '',
+  'Enter to select · ↑/↓ to navigate · Esc to cancel',
+].join('\n');
+
+const WORKING_FRAME = [
+  '● Bash(sleep 25)',
+  '  ⎿  Tip: Use git worktrees to run multiple Claude sessions in parallel.',
+  '✢ Clauding… (13s · ↓ 1.4k tokens)',
+  '────────────────────────────────────────',
+  '❯',
+  '────────────────────────────────────────',
+  '  ⏵⏵ bypass permissions on (shift+tab to cycle) · esc to interrupt · ← for agents',
+].join('\n');
+
 function collect(inbox: ApprovalInbox) {
   const pending: ApprovalItem[] = [];
   const updated: ApprovalItem[] = [];
@@ -333,6 +366,186 @@ describe('ApprovalInbox', () => {
     });
   });
 
+  describe('answered-in-the-terminal staleness', () => {
+    // Claude Code delays the Notification hook behind the dialog (measured 6s
+    // on v2.1.237, documented up to ~30s), so the 600ms re-capture routinely
+    // lands on a frame the user has ALREADY answered. Erasing `options` there
+    // made the item permanently unsweepable, because a missing `options` is how
+    // "we never could read this dialog" is expressed, and such items stay
+    // answerable on purpose. The red tab alert then survived every
+    // `GET /api/approvals` and every reload, clearing only on `stop`.
+    it('a re-capture taken after the answer does not erase parsed options', () => {
+      const { updated } = collect(inbox);
+      let frame = ASK_USER_QUESTION_FRAME;
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => frame,
+      });
+      expect(item.options).toHaveLength(5);
+
+      // Answered in the terminal before the re-capture fires.
+      frame = "● User answered Claude's questions:\n  ⎿  · Which color do you prefer? → Red\n\n✶ Cooking… (6s)";
+      vi.advanceTimersByTime(600);
+
+      expect(updated).toHaveLength(1);
+      expect(inbox.getById(item.id)?.context).toContain('User answered');
+      expect(inbox.getById(item.id)?.options).toHaveLength(5);
+      // ...which keeps the staleness check conclusive instead of inconclusive.
+      expect(inbox.verifyStillAnswerable(item.id)).toBe(false);
+      expect(inbox.getById(item.id)).toBeUndefined();
+    });
+
+    it('resolveIfDialogGone resolves a dialog answered in the terminal', () => {
+      const { resolved } = collect(inbox);
+      let frame = PERMISSION_FRAME;
+      const item = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'permission', capture: () => frame });
+      frame = 'the dialog is gone, claude is typing';
+
+      inbox.resolveIfDialogGone('s1');
+
+      expect(inbox.getById(item.id)).toBeUndefined();
+      expect(resolved.at(-1)).toMatchObject({ id: item.id, resolution: 'resolved_in_terminal' });
+    });
+
+    it('resolveIfDialogGone keeps a dialog that is still on screen', () => {
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => PERMISSION_FRAME,
+      });
+      inbox.resolveIfDialogGone('s1');
+      expect(inbox.getById(item.id)).toBeDefined();
+    });
+
+    it('resolveIfDialogGone never touches an idle item (that is the working signal job)', () => {
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'idle',
+        capture: () => 'composer is empty',
+      });
+      inbox.resolveIfDialogGone('s1');
+      expect(inbox.getById(item.id)).toBeDefined();
+    });
+
+    // The late-hook hole: Claude Code fires the Notification behind the dialog,
+    // so a prompt answered before the hook lands produces an item whose FIRST
+    // capture already has no dialog in it. Nothing ever parsed, so "options
+    // vanished" can never fire, and `stop` had already gone by too — the red
+    // alert then survived reloads until the 12h TTL.
+    it('resolves an item that never parsed options once the pane is visibly working', () => {
+      const { resolved } = collect(inbox);
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => WORKING_FRAME,
+      });
+      expect(item.options).toBeUndefined();
+
+      expect(inbox.verifyStillAnswerable(item.id)).toBe(false);
+      expect(inbox.getById(item.id)).toBeUndefined();
+      expect(resolved.at(-1)).toMatchObject({ id: item.id, resolution: 'resolved_in_terminal' });
+    });
+
+    it('keeps an unreadable dialog answerable when the pane is NOT visibly working', () => {
+      // The conservative rule this fix must not loosen: no options and no proof
+      // the turn is running means "we cannot read it", not "it is gone".
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => 'some dialog shape we cannot parse',
+      });
+      expect(item.options).toBeUndefined();
+      expect(inbox.verifyStillAnswerable(item.id)).toBe(true);
+      expect(inbox.getById(item.id)).toBeDefined();
+    });
+
+    it('a real live-dialog frame carries no working line, so it is never false-resolved', () => {
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => LIVE_DIALOG_FRAME,
+      });
+      expect(item.options).toHaveLength(4);
+      expect(inbox.verifyStillAnswerable(item.id)).toBe(true);
+      expect(inbox.getById(item.id)).toBeDefined();
+    });
+
+    it('resolveIfDialogGone clears a late-hook item on the next working signal', () => {
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => WORKING_FRAME,
+      });
+      inbox.resolveIfDialogGone('s1');
+      expect(inbox.getById(item.id)).toBeUndefined();
+    });
+
+    it('the delayed staleness pass resolves a late-hook item with no working signal needed', () => {
+      const { resolved } = collect(inbox);
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => WORKING_FRAME,
+      });
+      expect(item.options).toBeUndefined();
+
+      vi.advanceTimersByTime(600); // re-capture: enrichment only, never resolves
+      expect(inbox.getById(item.id)).toBeDefined();
+
+      vi.advanceTimersByTime(2400); // the delayed staleness pass
+      expect(inbox.getById(item.id)).toBeUndefined();
+      expect(resolved.at(-1)).toMatchObject({ id: item.id, resolution: 'resolved_in_terminal' });
+    });
+
+    it('a dialog Ink paints late is NOT resolved by the delayed pass', () => {
+      // The paint race the re-capture exists for: the hook can beat Ink to the
+      // screen. Resolving inside that window would clear the alert for a dialog
+      // that was about to appear, so the frame is what decides, every time.
+      let frame = WORKING_FRAME;
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => frame,
+      });
+      frame = LIVE_DIALOG_FRAME; // Ink finishes painting
+
+      vi.advanceTimersByTime(600);
+      expect(inbox.getById(item.id)?.options).toHaveLength(4);
+      vi.advanceTimersByTime(2400);
+      expect(inbox.getById(item.id)).toBeDefined();
+    });
+
+    it('resolving cancels both pending timers', () => {
+      const { updated } = collect(inbox);
+      const item = inbox.notePrompt({
+        sessionId: 's1',
+        sessionName: 'w1',
+        kind: 'permission',
+        capture: () => PERMISSION_FRAME,
+      });
+      inbox.dismiss(item.id);
+      vi.advanceTimersByTime(5000);
+      expect(updated).toHaveLength(0);
+      expect(inbox.listPending()).toHaveLength(0);
+    });
+
+    it('resolveIfDialogGone is a no-op for a session with nothing pending', () => {
+      const { resolved } = collect(inbox);
+      expect(() => inbox.resolveIfDialogGone('nobody')).not.toThrow();
+      expect(resolved).toHaveLength(0);
+    });
+  });
+
   it('stop() clears items and silences events', () => {
     const { resolved } = collect(inbox);
     inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'permission' });

test/claude-scrollback-strip.test.ts

@@ -147,3 +147,94 @@ describe('tmux-backed shell: strip tmux’s own client smcup, keep everything el
     }
   });
 });
+
+/**
+ * Whatever the strip removes, the server has to remember, because after it runs
+ * nothing downstream can ever see it. The browser hand-encodes click reports for
+ * these modes (`_sendSyntheticSgrTap`), and with no state to consult it did that
+ * on EVERY click, delivering mouse reports to a CLI that never asked for them.
+ */
+describe('stripped mouse-tracking state', () => {
+  const trackingOf = (session: Session) => session.toState().cliMouseTracking;
+
+  it('starts off, and stays off for output that never enables tracking', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    expect(trackingOf(session)).toBeUndefined();
+
+    handleOutput(session, 'plain output\x1b[?1049h\x1b[3J');
+
+    expect(trackingOf(session)).toBeUndefined();
+  });
+
+  it('follows the CLI enabling and disabling a tracking mode', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    const changes: boolean[] = [];
+    session.on('mouseTrackingChanged', (active: boolean) => changes.push(active));
+
+    handleOutput(session, '\x1b[?1002hdialog');
+    expect(trackingOf(session)).toBe(true);
+
+    handleOutput(session, '\x1b[?1002ldismissed');
+    expect(trackingOf(session)).toBeUndefined();
+    expect(changes).toEqual([true, false]);
+  });
+
+  it('ignores encoding and alt-scroll modes, which do not ask about clicks', () => {
+    // 1005/1006 pick an ENCODING and 1007 is alt-scroll. Counting them would put
+    // the stray reports straight back: a CLI can select SGR encoding without ever
+    // asking to be told where the user clicked.
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    handleOutput(session, '\x1b[?1006h\x1b[?1005h\x1b[?1007h');
+
+    expect(trackingOf(session)).toBeUndefined();
+  });
+
+  it('stays on until the LAST tracking mode goes away', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    handleOutput(session, '\x1b[?1000h\x1b[?1002h\x1b[?1006h');
+    expect(trackingOf(session)).toBe(true);
+
+    // A TUI may disable a mode it never enabled; that must not clear the rest.
+    handleOutput(session, '\x1b[?1003l');
+    expect(trackingOf(session)).toBe(true);
+
+    handleOutput(session, '\x1b[?1000l');
+    expect(trackingOf(session)).toBe(true);
+
+    handleOutput(session, '\x1b[?1002l');
+    expect(trackingOf(session)).toBeUndefined();
+  });
+
+  it('emits only on a real transition, so a repainting TUI costs nothing', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+    const changes: boolean[] = [];
+    session.on('mouseTrackingChanged', (active: boolean) => changes.push(active));
+
+    handleOutput(session, '\x1b[?1002h\x1b[?1002h\x1b[?1002h');
+
+    expect(changes).toEqual([true]);
+  });
+
+  it('sees a sequence split across PTY chunks, like the strip that carries it', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude' });
+
+    handleOutput(session, 'before\x1b[?100');
+    handleOutput(session, '2h after');
+
+    expect(session.terminalBuffer).toBe('before after');
+    expect(trackingOf(session)).toBe(true);
+  });
+
+  it('tracks nothing for a mode whose DECSETs are never stripped', () => {
+    // shell keeps its mouse DECSETs, so xterm sees them and owns the reporting.
+    // A flag set here would mean a SECOND, hand-encoded report on every click.
+    const session = new Session({ workingDir: '/tmp', mode: 'shell', useMux: true });
+
+    handleOutput(session, '\x1b[?1002hhtop');
+
+    expect(trackingOf(session)).toBeUndefined();
+    expect(session.terminalBuffer).toBe('\x1b[?1002hhtop');
+  });
+});

test/cli-executable-resolver.test.ts

@@ -0,0 +1,400 @@
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { EXEC_TIMEOUT_MS } from '../src/config/exec-timeout.js';
+import {
+  cliResolveRetryDelayMs,
+  createCliExecutableResolver,
+  createProductionCliResolverHost,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from '../src/utils/cli-executable-resolver.js';
+
+// Pass-through spy on execFileSync so the vitest-hermeticity test below can
+// PROVE the un-injected production host never spawns anything.
+const { execFileSyncSpy } = vi.hoisted(() => ({ execFileSyncSpy: vi.fn() }));
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  execFileSyncSpy.mockImplementation(actual.execFileSync as (...args: unknown[]) => unknown);
+  return { ...actual, execFileSync: execFileSyncSpy };
+});
+
+const BEGIN_MARKER = '__CODEMAN_CLI_RESOLVE_BEGIN__';
+const END_MARKER = '__CODEMAN_CLI_RESOLVE_END__';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function host(overrides: Partial<CliResolverHost> = {}): CliResolverHost {
+  return {
+    processPath: '/usr/bin:/bin',
+    shellPath: '/bin/bash',
+    shellArgs: ['-i', '-l'],
+    findOnProcessPath: vi.fn(() => null),
+    findInLoginShell: vi.fn(() => null),
+    exists: vi.fn(() => false),
+    ...overrides,
+  };
+}
+
+describe('createCliExecutableResolver', () => {
+  it('prefers the server process PATH over common directories and the login shell', () => {
+    const h = host({
+      findOnProcessPath: vi.fn(() => '/process/bin/codex'),
+      findInLoginShell: vi.fn(() => '/shell/bin/codex'),
+      exists: vi.fn(() => true),
+    });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: ['/known/bin'] }, h);
+
+    expect(resolver.resolve()).toMatchObject({ binaryPath: '/process/bin/codex', source: 'process-path' });
+    expect(h.exists).toHaveBeenCalledTimes(1);
+    expect(h.findInLoginShell).not.toHaveBeenCalled();
+  });
+
+  it('prefers common directories in order over the login shell', () => {
+    const h = host({
+      findInLoginShell: vi.fn(() => '/shell/bin/codex'),
+      exists: vi.fn((path) => path === '/second/bin/codex' || path === '/shell/bin/codex'),
+    });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: ['/first/bin', '/second/bin'] }, h);
+
+    expect(resolver.resolve()).toMatchObject({ binaryPath: '/second/bin/codex', source: 'common-directory' });
+    expect(h.exists).toHaveBeenNthCalledWith(1, '/first/bin/codex');
+    expect(h.exists).toHaveBeenNthCalledWith(2, '/second/bin/codex');
+    expect(h.findInLoginShell).not.toHaveBeenCalled();
+  });
+
+  it('finds an executable exposed only by the interactive login shell', () => {
+    const h = host({
+      findInLoginShell: vi.fn(() => '/home/u/.nvm/versions/node/v22/bin/codex'),
+      exists: vi.fn((path) => path === '/home/u/.nvm/versions/node/v22/bin/codex'),
+    });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: ['/known/bin'] }, h);
+
+    expect(resolver.resolve()).toMatchObject({
+      binaryPath: '/home/u/.nvm/versions/node/v22/bin/codex',
+      directory: '/home/u/.nvm/versions/node/v22/bin',
+      source: 'login-shell',
+    });
+  });
+
+  it('continues after a validator rejects an earlier candidate', () => {
+    const h = host({
+      findOnProcessPath: vi.fn(() => '/usr/bin/pi'),
+      findInLoginShell: vi.fn(() => '/home/u/.npm/bin/pi'),
+      exists: vi.fn(() => true),
+    });
+    const resolver = createCliExecutableResolver(
+      {
+        binary: 'pi',
+        searchDirs: [],
+        validateCandidate: (path) =>
+          path.includes('.npm') ? { accepted: true, metadata: '0.84.1' } : { accepted: false },
+      },
+      h
+    );
+
+    expect(resolver.resolve()).toMatchObject({
+      binaryPath: '/home/u/.npm/bin/pi',
+      source: 'login-shell',
+      metadata: '0.84.1',
+    });
+  });
+
+  it('caches success, and retries a miss only after the backoff elapses', () => {
+    let now = 0;
+    const findInLoginShell = vi.fn<() => string | null>().mockReturnValueOnce(null).mockReturnValue('/new/bin/codex');
+    const h = host({ findInLoginShell, exists: vi.fn((path) => path === '/new/bin/codex') });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: [], now: () => now }, h);
+
+    expect(resolver.resolve()).toBeNull();
+    // Within the backoff window the miss is answered from the negative cache:
+    // the chain — whose login-shell tail is a synchronous 5s-bounded spawn —
+    // must NOT re-run per call, or a missing CLI stalls every status request.
+    now = cliResolveRetryDelayMs(1) - 1;
+    expect(resolver.resolve()).toBeNull();
+    expect(findInLoginShell).toHaveBeenCalledTimes(1);
+
+    // Once the backoff elapses the retry runs, so installing a CLI while the
+    // server is up is still picked up without a restart.
+    now = cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()?.binaryPath).toBe('/new/bin/codex');
+    expect(resolver.resolve()?.binaryPath).toBe('/new/bin/codex');
+    expect(findInLoginShell).toHaveBeenCalledTimes(2);
+  });
+
+  it('doubles the retry delay per consecutive miss and caps it at five minutes', () => {
+    let now = 0;
+    const findInLoginShell = vi.fn(() => null);
+    const resolver = createCliExecutableResolver(
+      { binary: 'codex', searchDirs: [], now: () => now },
+      host({ findInLoginShell })
+    );
+
+    expect(cliResolveRetryDelayMs(0)).toBe(0);
+    expect(cliResolveRetryDelayMs(1)).toBe(60_000);
+    expect(cliResolveRetryDelayMs(2)).toBe(120_000);
+    expect(cliResolveRetryDelayMs(3)).toBe(240_000);
+    expect(cliResolveRetryDelayMs(4)).toBe(300_000);
+    expect(cliResolveRetryDelayMs(60)).toBe(300_000);
+
+    // Consecutive misses stack: after the second miss the SECOND delay applies.
+    expect(resolver.resolve()).toBeNull();
+    now += cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()).toBeNull();
+    expect(findInLoginShell).toHaveBeenCalledTimes(2);
+    now += cliResolveRetryDelayMs(2) - 1;
+    expect(resolver.resolve()).toBeNull();
+    expect(findInLoginShell).toHaveBeenCalledTimes(2);
+    now += 1;
+    expect(resolver.resolve()).toBeNull();
+    expect(findInLoginShell).toHaveBeenCalledTimes(3);
+  });
+
+  it('rejects unsafe binary names', () => {
+    const h = host();
+
+    expect(() => createCliExecutableResolver({ binary: 'codex;id', searchDirs: [] }, h)).toThrow(
+      'Unsafe CLI binary name'
+    );
+    expect(() => createCliExecutableResolver({ binary: '../codex', searchDirs: [] }, h)).toThrow(
+      'Unsafe CLI binary name'
+    );
+  });
+
+  it('rejects relative and nonexistent candidates', () => {
+    let now = 0;
+    const findInLoginShell = vi
+      .fn<() => string | null>()
+      .mockReturnValueOnce('relative/codex')
+      .mockReturnValue('/missing/codex');
+    const h = host({ findInLoginShell, exists: vi.fn(() => false) });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: [], now: () => now }, h);
+
+    expect(resolver.resolve()).toBeNull();
+    now = cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()).toBeNull();
+    expect(h.exists).toHaveBeenCalledTimes(1);
+    expect(h.exists).toHaveBeenCalledWith('/missing/codex');
+  });
+});
+
+describe('formatCliNotFoundMessage', () => {
+  it('includes only the base install hint and bounded resolution diagnostics', () => {
+    const base = 'Codex CLI not found. Install with: npm install -g @openai/codex';
+    const diagnostics = {
+      binary: 'codex',
+      processPath: '/usr/bin:/bin',
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      searchDirs: ['/home/u/.local/bin', '/usr/local/bin'],
+      API_KEY: 'super-secret',
+    };
+    const message = formatCliNotFoundMessage(base, diagnostics);
+
+    expect(message).toContain(base);
+    expect(message).toContain('Server PATH: /usr/bin:/bin');
+    expect(message).toContain('Login shell: /bin/bash -i -l');
+    expect(message).toContain('Checked directories: /home/u/.local/bin, /usr/local/bin');
+    expect(message).not.toContain('API_KEY');
+    expect(message).not.toContain('super-secret');
+  });
+
+  it('marks empty diagnostic values without dumping arbitrary environment data', () => {
+    const message = formatCliNotFoundMessage('Missing CLI', {
+      binary: 'codex',
+      processPath: '',
+      shellPath: '',
+      shellArgs: [],
+      searchDirs: [],
+    });
+
+    expect(message).toBe('Missing CLI\nServer PATH: (empty)\nLogin shell: (none)\nChecked directories: (none)');
+    expect(message).not.toContain('HOME=');
+    expect(message).not.toContain('TOKEN=');
+  });
+
+  it('flattens control characters and bounds every diagnostic field', () => {
+    const pathological = `first\r\nforged label: value\u0000${'x'.repeat(10_000)}`;
+    const message = formatCliNotFoundMessage('Missing CLI', {
+      binary: 'codex',
+      processPath: pathological,
+      shellPath: pathological,
+      shellArgs: [pathological],
+      searchDirs: [pathological, pathological],
+    });
+    const lines = message.split('\n');
+
+    expect(lines).toHaveLength(4);
+    expect(lines[1]).toMatch(/^Server PATH: first forged label: value x+…$/);
+    expect(lines[2]).toMatch(/^Login shell: first forged label: value x+…$/);
+    expect(lines[3]).toMatch(/^Checked directories: first forged label: value x+…$/);
+    expect(lines.slice(1).every((line) => line.length <= 1_050)).toBe(true);
+  });
+});
+
+describe('createProductionCliResolverHost', () => {
+  // Hermeticity gate (the guards PR #329 deleted, restored shared): under
+  // vitest an un-injected host must neither scan the machine nor spawn a login
+  // shell — route tests hitting the per-CLI status endpoints would otherwise
+  // walk the real PATH and execute real binaries on whatever box runs the suite.
+  it('never scans the machine or spawns a login shell under vitest without injected IO', () => {
+    const root = mkdtempSync(join(tmpdir(), 'codeman-cli-vitest-gate-'));
+    temporaryDirectories.push(root);
+    writeFileSync(join(root, 'codex'), '#!/bin/sh\n');
+    chmodSync(join(root, 'codex'), 0o755);
+    execFileSyncSpy.mockClear();
+
+    const gatedHost = createProductionCliResolverHost({
+      processPath: root,
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+    });
+
+    // The real, executable candidate is invisible: the filesystem predicate is inert.
+    expect(gatedHost.findOnProcessPath('codex')).toBeNull();
+    expect(gatedHost.exists(join(root, 'codex'))).toBe(false);
+    // The login-shell step yields nothing and never reaches execFileSync.
+    expect(gatedHost.findInLoginShell('codex')).toBeNull();
+    expect(execFileSyncSpy).not.toHaveBeenCalled();
+
+    // The same fixture through the test-only real-IO opt-in IS found, proving
+    // the nulls above come from the vitest gate rather than from the fixture.
+    const optedInHost = createProductionCliResolverHost({
+      processPath: root,
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      runCommand: () => '',
+      allowRealIoUnderVitest: true,
+    });
+    expect(optedInHost.findOnProcessPath('codex')).toBe(join(root, 'codex'));
+  });
+
+  it('resolves through injected IO hooks under vitest (injection is the opt-in)', () => {
+    const runCommand = vi.fn(() => `${BEGIN_MARKER}\n/home/u/.nvm/bin/codex\n${END_MARKER}`);
+    const productionHost = createProductionCliResolverHost({
+      processPath: '',
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      runCommand,
+      isExecutableFile: () => true,
+    });
+    const resolver = createCliExecutableResolver({ binary: 'codex', searchDirs: [] }, productionHost);
+
+    expect(resolver.resolve()).toMatchObject({
+      binaryPath: '/home/u/.nvm/bin/codex',
+      source: 'login-shell',
+    });
+    expect(runCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('searches the captured process PATH directly in directory order without running a command', () => {
+    const runCommand = vi.fn(() => '');
+    const isExecutableFile = vi.fn((path: string) => path === '/second/bin/codex');
+    const productionHost = createProductionCliResolverHost({
+      processPath: '/first/bin:/second/bin:/third/bin',
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      runCommand,
+      isExecutableFile,
+    });
+
+    expect(productionHost.findOnProcessPath('codex')).toBe('/second/bin/codex');
+    expect(isExecutableFile).toHaveBeenNthCalledWith(1, '/first/bin/codex');
+    expect(isExecutableFile).toHaveBeenNthCalledWith(2, '/second/bin/codex');
+    expect(runCommand).not.toHaveBeenCalled();
+  });
+
+  it('accepts only executable regular files with the production predicate', () => {
+    const root = mkdtempSync(join(tmpdir(), 'codeman-cli-resolver-'));
+    temporaryDirectories.push(root);
+    const executableDirectory = join(root, 'executable');
+    const plainDirectory = join(root, 'plain');
+    const directoryCandidate = join(root, 'directory');
+    mkdirSync(executableDirectory);
+    mkdirSync(plainDirectory);
+    mkdirSync(directoryCandidate);
+    writeFileSync(join(executableDirectory, 'codex'), '#!/bin/sh\n');
+    chmodSync(join(executableDirectory, 'codex'), 0o755);
+    writeFileSync(join(plainDirectory, 'codex'), '#!/bin/sh\n');
+    mkdirSync(join(directoryCandidate, 'codex'));
+    const productionHost = createProductionCliResolverHost({
+      processPath: [directoryCandidate, plainDirectory, executableDirectory].join(':'),
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      // This test exists to exercise the REAL executable-regular-file predicate
+      // against its own temp fixtures, so it opts out of the vitest inert-IO
+      // gate; the stubbed runCommand keeps the login-shell path inert anyway.
+      runCommand: () => '',
+      allowRealIoUnderVitest: true,
+    });
+
+    expect(productionHost.findOnProcessPath('codex')).toBe(join(executableDirectory, 'codex'));
+  });
+
+  it('uses the resolved shell, allowlisted args, tagged command, and bounded timeout', () => {
+    const runCommand = vi.fn(() =>
+      ['/profile/absolute-noise', BEGIN_MARKER, '/home/u/.nvm/bin/codex', END_MARKER, '/exit-trap/absolute-noise'].join(
+        '\n'
+      )
+    );
+    const productionHost = createProductionCliResolverHost({
+      processPath: '',
+      shellPath: '/usr/bin/fish',
+      shellArgs: ['-i', '-l'],
+      runCommand,
+      isExecutableFile: () => true,
+    });
+
+    expect(productionHost.findInLoginShell('codex')).toBe('/home/u/.nvm/bin/codex');
+    expect(runCommand).toHaveBeenCalledWith(
+      '/usr/bin/fish',
+      ['-i', '-l', '-c', `printf '%s\\n' '${BEGIN_MARKER}'; command -v -- codex; printf '%s\\n' '${END_MARKER}'`],
+      {
+        encoding: 'utf8',
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        // SIGKILL is load-bearing: interactive bash ignores SIGTERM, and
+        // execFileSync's timeout only sends the signal, then keeps waiting.
+        killSignal: 'SIGKILL',
+      }
+    );
+  });
+
+  it.each([
+    ['mismatched basename', `${BEGIN_MARKER}\n/opt/bin/not-codex\n${END_MARKER}`],
+    ['missing begin marker', `/opt/bin/codex\n${END_MARKER}`],
+    ['missing end marker', `${BEGIN_MARKER}\n/opt/bin/codex`],
+    ['absolute output outside markers', `/profile/codex\n${BEGIN_MARKER}\nrelative/codex\n${END_MARKER}\n/exit/codex`],
+  ])('rejects malformed tagged shell output: %s', (_name, output) => {
+    const productionHost = createProductionCliResolverHost({
+      processPath: '',
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      runCommand: () => output,
+      isExecutableFile: () => true,
+    });
+
+    expect(productionHost.findInLoginShell('codex')).toBeNull();
+  });
+
+  it('returns null when the shell command throws', () => {
+    const productionHost = createProductionCliResolverHost({
+      processPath: '',
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'],
+      runCommand: () => {
+        throw new Error('exit 1');
+      },
+      isExecutableFile: () => true,
+    });
+
+    expect(productionHost.findInLoginShell('codex')).toBeNull();
+  });
+});

test/cli-style.test.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Unit tests for the pure half of the CLI style kit: display-width
+ * math, column layout, kv padding, glyph selection, and the spinner's non-TTY
+ * behavior. Nothing here needs a terminal.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  GLYPH,
+  SPINNER_FRAMES,
+  columnWidths,
+  confirm,
+  displayWidth,
+  glyphFor,
+  isInteractive,
+  kv,
+  layoutTable,
+  padCell,
+  padStyled,
+  palette,
+  spinner,
+  table,
+  tint,
+  type SpinnerStream,
+} from '../src/cli-style.js';
+
+/** Recording stand-in for `process.stderr`. */
+function fakeStream(isTTY: boolean): SpinnerStream & { writes: string[] } {
+  const writes: string[] = [];
+  return {
+    isTTY,
+    writes,
+    write(chunk: string) {
+      writes.push(chunk);
+      return true;
+    },
+  };
+}
+
+describe('displayWidth', () => {
+  it('counts printable columns, not bytes', () => {
+    expect(displayWidth('tmux')).toBe(4);
+    expect(displayWidth('')).toBe(0);
+  });
+
+  it('ignores ANSI sequences', () => {
+    expect(displayWidth('\x1b[32mok\x1b[39m')).toBe(2);
+    expect(displayWidth(palette.ok('ok'))).toBe(2);
+  });
+});
+
+describe('padCell', () => {
+  it('pads to the requested column count', () => {
+    expect(padCell('ab', 5)).toBe('ab   ');
+    expect(padCell('ab', 5, 'right')).toBe('   ab');
+  });
+
+  it('never truncates a cell that is already too wide', () => {
+    expect(padCell('Antigravity CLI', 4)).toBe('Antigravity CLI');
+  });
+
+  it('pads a colored cell by its printed width', () => {
+    const padded = padCell(palette.ok('ok'), 6);
+    expect(displayWidth(padded)).toBe(6);
+  });
+});
+
+describe('padStyled', () => {
+  it('keeps the fill outside the paint so trailing space can be trimmed', () => {
+    const cell = padStyled('ok', 6, (t) => `<${t}>`);
+    expect(cell).toBe('<ok>    ');
+    expect(cell.trimEnd()).toBe('<ok>');
+  });
+});
+
+describe('columnWidths', () => {
+  it('measures the widest cell per column', () => {
+    expect(
+      columnWidths([
+        ['tmux', '3.4'],
+        ['Antigravity CLI', 'not found'],
+      ])
+    ).toEqual([15, 9]);
+  });
+
+  it('treats missing cells as empty, never as a narrower column', () => {
+    expect(columnWidths([['a', 'bbb'], ['a']])).toEqual([1, 3]);
+  });
+});
+
+describe('layoutTable', () => {
+  // The bug this replaces: `padEnd(14)` with a 15-character label ("Antigravity
+  // CLI") pushed that row's remaining columns one column right.
+  const rows = [
+    ['✓', 'tmux', '3.4'],
+    ['✓', 'Antigravity CLI', '1.1.12'],
+    ['○', 'Pi CLI', 'not found'],
+  ];
+
+  it('starts every column at the same offset regardless of cell length', () => {
+    const lines = layoutTable(rows, { indent: '  ' });
+    expect(lines[0].indexOf('3.4')).toBe(lines[1].indexOf('1.1.12'));
+    expect(lines[1].indexOf('1.1.12')).toBe(lines[2].indexOf('not found'));
+    // Widest label (15) + indent (2) + glyph column (1) + two gaps.
+    expect(lines[1].indexOf('1.1.12')).toBe(2 + 1 + 1 + 15 + 1);
+  });
+
+  it('leaves no trailing whitespace on the last column', () => {
+    for (const line of layoutTable(rows)) {
+      expect(line).toBe(line.trimEnd());
+    }
+  });
+
+  it('honors indent, gap and right alignment', () => {
+    const lines = layoutTable(
+      [
+        ['a', '1'],
+        ['bbb', '22'],
+      ],
+      { indent: '> ', gap: 3, align: ['right'] }
+    );
+    expect(lines[0]).toBe('>   a   1');
+    expect(lines[1]).toBe('> bbb   22');
+  });
+
+  it('aligns colored cells by printed width', () => {
+    const lines = layoutTable([
+      [palette.ok('✓'), palette.emph('tmux'), '3.4'],
+      [palette.err('✗'), 'Antigravity CLI', 'not found'],
+    ]);
+    expect(lines[0].indexOf('3.4')).toBe(lines[1].indexOf('not found'));
+  });
+});
+
+describe('table', () => {
+  it('joins the laid-out rows', () => {
+    expect(
+      table([
+        ['a', 'b'],
+        ['cc', 'd'],
+      ])
+    ).toBe('a  b\ncc d');
+  });
+});
+
+describe('kv', () => {
+  it('indents and appends the colon', () => {
+    expect(kv('Status', 'running')).toBe('  Status: running');
+  });
+
+  it('aligns a block when a pad width is given', () => {
+    const lines = [kv('Daemon pid', '42', 11), kv('Log', '/tmp/web.log', 11)];
+    expect(lines[0].indexOf('42')).toBe(lines[1].indexOf('/tmp/web.log'));
+  });
+});
+
+describe('glyphs', () => {
+  it('maps tones to the CLI glyph vocabulary', () => {
+    expect(glyphFor('ok')).toBe(GLYPH.ok);
+    expect(glyphFor('err')).toBe(GLYPH.fail);
+    expect(glyphFor('warn')).toBe(GLYPH.warn);
+    expect(glyphFor('idle')).toBe(GLYPH.idle);
+    expect(glyphFor('info')).toBe(GLYPH.dot);
+  });
+
+  it('tints without changing the printed text', () => {
+    expect(displayWidth(tint('err', 'nope'))).toBe(4);
+    expect(tint('err', 'nope')).toContain('nope');
+  });
+});
+
+describe('spinner', () => {
+  it('prints the text once and stays silent when the stream is not a TTY', () => {
+    const stream = fakeStream(false);
+    const handle = spinner('waiting', { stream }).start();
+    handle.setText('still waiting');
+    handle.stop('done');
+    expect(stream.writes).toEqual(['waiting\n']);
+  });
+
+  it('animates in place on a TTY and restores the cursor on stop', () => {
+    const stream = fakeStream(true);
+    const handle = spinner('waiting', { stream, intervalMs: 60_000 }).start();
+    expect(stream.writes[0]).toBe('\x1b[?25l');
+    expect(stream.writes[1]).toContain(SPINNER_FRAMES[0]);
+    expect(stream.writes[1]).toContain('waiting');
+
+    handle.stop();
+    const tail = stream.writes.join('');
+    expect(tail).toContain('\r\x1b[K');
+    expect(tail).toContain('\x1b[?25h');
+  });
+
+  it('ignores a second stop', () => {
+    const stream = fakeStream(true);
+    const handle = spinner('waiting', { stream, intervalMs: 60_000 }).start();
+    handle.stop();
+    const afterFirst = stream.writes.length;
+    handle.stop();
+    expect(stream.writes.length).toBe(afterFirst);
+  });
+
+  it('does nothing at all when it was never started', () => {
+    const stream = fakeStream(true);
+    spinner('waiting', { stream }).stop();
+    expect(stream.writes).toEqual([]);
+  });
+});
+
+describe('confirm', () => {
+  it('answers no without blocking when stdin is not a TTY', async () => {
+    const original = process.stdin.isTTY;
+    try {
+      process.stdin.isTTY = false;
+      expect(isInteractive()).toBe(false);
+      await expect(confirm('Reset all Codeman state?')).resolves.toBe(false);
+    } finally {
+      process.stdin.isTTY = original;
+    }
+  });
+});

test/codex-snapshot-replay.test.ts

@@ -32,7 +32,7 @@ describe('xterm snapshot/replay (codex tab-switch)', () => {
     const declaration = source.indexOf('let restoredSnapshot = false;', selectStart);
     const snapshotBranch = source.indexOf("if (snapshot && !sessionIsBusy && session?.mode !== 'shell')", selectStart);
     const rewriteDecision = source.indexOf(
-      'restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer',
+      'restoredSnapshot || clearedBeforeFresh || data.terminalBuffer !== cachedBuffer',
       selectStart
     );
 
@@ -58,7 +58,9 @@ describe('xterm snapshot/replay (codex tab-switch)', () => {
     // Snapshot restore must NOT short-circuit the canonical fetch.
     expect(snapshotBlock).not.toContain('this._finishBufferLoad();');
     expect(postSnapshotRestore).toContain('restoredSnapshot');
-    expect(postSnapshotRestore).toContain('restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer');
+    expect(postSnapshotRestore).toContain(
+      'restoredSnapshot || clearedBeforeFresh || data.terminalBuffer !== cachedBuffer'
+    );
   });
 
   it('forces replay after clearing a busy tab even when the fetched frame matches cache', () => {
@@ -71,8 +73,8 @@ describe('xterm snapshot/replay (codex tab-switch)', () => {
     expect(cacheRestore).toBeGreaterThan(-1);
     expect(busyClear).toBeGreaterThan(cacheRestore);
     expect(needsRewrite).toBeGreaterThan(busyClear);
-    expect(replayBlock).toContain('clearedForBusy');
-    expect(replayBlock).toContain('restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer');
+    expect(replayBlock).toContain('clearedBeforeFresh');
+    expect(replayBlock).toContain('restoredSnapshot || clearedBeforeFresh || data.terminalBuffer !== cachedBuffer');
   });
 
   it('loads the SerializeAddon and keeps a per-session snapshot map', () => {

test/config/instance.test.ts

@@ -18,7 +18,7 @@ vi.mock('node:fs', async (orig) => {
   return { ...actual, mkdirSync: vi.fn() };
 });
 
-const ENV_KEYS = ['CODEMAN_INSTANCE', 'CODEMAN_DATA_DIR'] as const;
+const ENV_KEYS = ['CODEMAN_INSTANCE', 'CODEMAN_DATA_DIR', 'CODEMAN_TMUX_SOCKET'] as const;
 const ORIG: Record<string, string | undefined> = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
 
 async function load(env: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>> = {}) {
@@ -77,3 +77,22 @@ describe('config/instance', () => {
     expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-beta');
   });
 });
+
+describe('resolveTmuxSocketName', () => {
+  it('is the instance socket when no override is set', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'beta', CODEMAN_TMUX_SOCKET: undefined });
+    expect(m.resolveTmuxSocketName()).toBe('codeman-beta');
+  });
+
+  it('honours a safe CODEMAN_TMUX_SOCKET override', async () => {
+    const m = await load({ CODEMAN_INSTANCE: undefined, CODEMAN_TMUX_SOCKET: 'codeman-test.1' });
+    expect(m.resolveTmuxSocketName()).toBe('codeman-test.1');
+  });
+
+  it('ignores an override that could not be passed to `tmux -L` safely', async () => {
+    // A socket name reaches a command line, so anything outside the pattern
+    // falls back to the instance default rather than being escaped.
+    const m = await load({ CODEMAN_INSTANCE: undefined, CODEMAN_TMUX_SOCKET: 'bad; rm -rf /' });
+    expect(m.resolveTmuxSocketName()).toBe('codeman');
+  });
+});

test/dependency-report.test.ts

@@ -61,6 +61,48 @@ describe('renderTable', () => {
     expect(out).toContain('document preview');
     expect(out).toContain('sudo apt install tmux');
   });
+
+  it('stays color-free unless the caller passes a style', () => {
+    // eslint-disable-next-line no-control-regex
+    expect(renderTable(results, 'linux')).not.toMatch(/\x1b\[/);
+  });
+
+  it('aligns the status column past a label wider than the old padEnd(14)', () => {
+    const wide: ToolResult[] = [
+      ...results,
+      { id: 'agy', label: 'Antigravity CLI', category: 'core', required: false, usedBy: [], status: 'missing' },
+    ];
+    const lines = renderTable(wide, 'linux').split('\n');
+    const nodeLine = lines.find((l) => l.includes('Node.js'))!;
+    const agyLine = lines.find((l) => l.includes('Antigravity CLI'))!;
+    expect(nodeLine.indexOf('22.22.1')).toBe(agyLine.indexOf('not found'));
+  });
+
+  it('applies the caller-supplied paint hooks without shifting the columns', () => {
+    const plain = renderTable(results, 'linux').split('\n');
+    const styled = renderTable(results, 'linux', {
+      title: (t) => `T{${t}}`,
+      heading: (t) => `H{${t}}`,
+      glyph: (_r, g) => `G{${g}}`,
+      label: (t) => `L{${t}}`,
+      status: (_r, t) => `S{${t}}`,
+      path: (t) => `P{${t}}`,
+      meta: (t) => `M{${t}}`,
+      summary: (t) => `Z{${t}}`,
+    }).split('\n');
+    expect(styled[0]).toBe(`T{${plain[0]}}`);
+    expect(styled.find((l) => l.includes('CORE'))).toBe('H{CORE}');
+    const nodeLine = styled.find((l) => l.includes('Node.js'))!;
+    expect(nodeLine).toContain('G{✓}');
+    expect(nodeLine).toContain('L{Node.js}');
+    expect(nodeLine).toContain('S{22.22.1}');
+    expect(nodeLine).toContain('P{/n}');
+    expect(styled.some((l) => l.startsWith('M{        used by:'))).toBe(true);
+    expect(styled[styled.length - 1]).toBe(`Z{${plain[plain.length - 1]}}`);
+    // Padding lives outside the paint, so a row with no path detail ends at its
+    // status text rather than trailing invisible spaces inside a color run.
+    expect(styled.find((l) => l.includes('S{n/a}'))!.endsWith('S{n/a}')).toBe(true);
+  });
 });
 
 describe('renderJson', () => {

test/history-truncation-notice.test.ts

@@ -122,6 +122,18 @@ describe('the in-terminal truncation line is gone (static guard)', () => {
     expect(app).not.toContain('earlier output truncated for performance');
   });
 
+  it('loads a bounded shell tail first and keeps full history user-triggered', () => {
+    const app = readFileSync(resolve(PUBLIC, 'app.js'), 'utf8');
+    expect(app).toContain("session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId)");
+    expect(app).toContain("!restoredSnapshot && session?.mode !== 'shell'");
+    expect(app).toContain('`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`');
+    expect(app).toContain('fetch(`/api/sessions/${sessionId}/terminal?full=1`)');
+    expect(app).toContain("if (this.sessions.get(sessionId)?.mode !== 'shell')");
+    expect(app).toContain("if (session?.mode === 'shell')");
+    expect(app).toContain("if (!force && session?.mode === 'shell') return;");
+    expect(app).toContain("trigger: force ? 'full-history-button' : 'full-history-scroll'");
+  });
+
   it('renders the banner through textContent, never innerHTML', () => {
     const app = readFileSync(resolve(PUBLIC, 'app.js'), 'utf8');
     const start = app.indexOf('_renderHistoryTruncationBanner() {');

test/input-cjk.test.ts

@@ -5,7 +5,7 @@
  * composition/keydown/input event sequences against a stub textarea.
  * Focus: the intermittent "Chinese characters silently lost" failure modes —
  * stuck composition state, deferred flush racing the next composition, and
- * the keydown-echo suppression window swallowing a real IME commit.
+ * physical-key punctuation transformed into full-width IME output.
  */
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -116,6 +116,36 @@ describe('CJK input module', () => {
     expect(textarea.value).toBe(PHANTOM);
   });
 
+  it('lets the IME transform printable keys before sending full-width punctuation', () => {
+    const { textarea, sent } = loadCjkHarness();
+    const committed = Array.from('，。！？；：“”、《》、（）');
+    const physicalKeys = [',', '.', '!', '?', ';', ':', '"', '"', '\\', '<', '>', '\\', '(', ')'];
+
+    textarea.fire('compositionstart');
+    textarea.value = PHANTOM + '中文';
+    textarea.fire('input', { isComposing: true, inputType: 'insertCompositionText' });
+    textarea.fire('compositionend');
+    vi.advanceTimersByTime(10);
+    vi.advanceTimersByTime(1000);
+
+    for (const [index, punctuation] of committed.entries()) {
+      const preventDefault = vi.fn();
+      textarea.fire('keydown', {
+        key: physicalKeys[index],
+        ctrlKey: false,
+        altKey: false,
+        metaKey: false,
+        preventDefault,
+      });
+      expect(preventDefault).not.toHaveBeenCalled();
+
+      textarea.value = PHANTOM + punctuation;
+      textarea.fire('input', { isComposing: false, inputType: 'insertText' });
+    }
+
+    expect(sent).toEqual(['中文', ...committed]);
+  });
+
   it('recovers committed text when compositionend never fires (stuck composition)', () => {
     const { textarea, sent } = loadCjkHarness();
 
@@ -124,6 +154,7 @@ describe('CJK input module', () => {
     textarea.value = PHANTOM + '你好';
     // The commit arrives as a plain input event outside composition.
     textarea.fire('input', { isComposing: false, inputType: 'insertText' });
+    expect(sent).toEqual([]);
     vi.advanceTimersByTime(200);
 
     expect(sent).toEqual(['你好']);
@@ -151,30 +182,28 @@ describe('CJK input module', () => {
     expect(sent).toEqual(['你好世界']);
   });
 
-  it('does not discard an IME commit landing inside the keydown echo window', () => {
+  it('sends the transformed IME commit that follows a printable keydown', () => {
     const { textarea, sent } = loadCjkHarness();
 
-    // English char goes out immediately via keydown.
+    vi.advanceTimersByTime(1000);
+    // The physical key is not committed text and must not be sent by itself.
     textarea.fire('keydown', { key: 'a', ctrlKey: false, altKey: false, metaKey: false });
-    expect(sent).toEqual(['a']);
+    expect(sent).toEqual([]);
 
-    // Within 100ms the IME commits Chinese via a bare input event.
+    // The browser/IME supplies the canonical text in the following input.
     vi.advanceTimersByTime(50);
     textarea.value = PHANTOM + '你好';
     textarea.fire('input', { isComposing: false, inputType: 'insertText' });
-    vi.advanceTimersByTime(200);
 
-    expect(sent).toEqual(['a', '你好']);
+    expect(sent).toEqual(['你好']);
   });
 
-  it('still suppresses the true textarea echo of a keydown-sent character', () => {
+  it('sends a printable physical key exactly once after its input event', () => {
     const { textarea, sent } = loadCjkHarness();
 
     textarea.fire('keydown', { key: 'a', ctrlKey: false, altKey: false, metaKey: false });
-    expect(sent).toEqual(['a']);
+    expect(sent).toEqual([]);
 
-    // Third-party IME ignored preventDefault — the same char echoes into
-    // the textarea. It must be dropped, not sent twice.
     vi.advanceTimersByTime(10);
     textarea.value = PHANTOM + 'a';
     textarea.fire('input', { isComposing: false, inputType: 'insertText' });
@@ -242,6 +271,8 @@ describe('CJK input module', () => {
     vi.advanceTimersByTime(10);
 
     textarea.fire('keydown', { key: '囍', ctrlKey: false, altKey: false, metaKey: false });
+    textarea.value = PHANTOM + '囍';
+    textarea.fire('input', { isComposing: false, inputType: 'insertText' });
     textarea.value = PHANTOM + '秘密';
     textarea.fire('blur');
     expect(sent).toEqual(['秘密口令', '囍']);

test/pi-cli-resolver.test.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Tests for the Pi CLI resolver wrapper.
+ *
+ * Pi is the resolver with a version probe: `pi` is a short, generic binary
+ * name, so a resolved path is only accepted once `pi --version` prints a
+ * semver-shaped string. The probe EXECUTES the candidate, which is exactly why
+ * it must never run under vitest — the hermeticity test below pins that gate
+ * with a real executable fixture that would make the test fail loudly if the
+ * gate were deleted again (as PR #329 once did).
+ */
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createPiResolverForTest } from '../src/utils/pi-cli-resolver.js';
+import {
+  cliResolveRetryDelayMs,
+  createProductionCliResolverHost,
+  type CliResolverHost,
+} from '../src/utils/cli-executable-resolver.js';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function createHost(
+  options: {
+    processPathResult?: string | null;
+    loginShellResults?: Array<string | null>;
+    existingPaths?: string[];
+  } = {}
+): CliResolverHost {
+  const loginShellResults = [...(options.loginShellResults ?? [])];
+  const existingPaths = new Set(options.existingPaths ?? []);
+  return {
+    processPath: '/service/bin',
+    shellPath: '/bin/zsh',
+    shellArgs: ['-l'],
+    findOnProcessPath: () => options.processPathResult ?? null,
+    findInLoginShell: () => loginShellResults.shift() ?? null,
+    exists: (path) => existingPaths.has(path),
+  };
+}
+
+describe('Pi CLI resolver', () => {
+  it('accepts a candidate the version probe verifies and carries the version as metadata', () => {
+    const binaryPath = '/service/bin/pi';
+    const probe = vi.fn(() => '0.84.1');
+    const resolver = createPiResolverForTest(
+      createHost({ processPathResult: binaryPath, existingPaths: [binaryPath] }),
+      probe
+    );
+
+    expect(resolver.resolve()).toMatchObject({
+      binaryPath,
+      directory: '/service/bin',
+      source: 'process-path',
+      metadata: '0.84.1',
+    });
+    expect(probe).toHaveBeenCalledWith(binaryPath);
+  });
+
+  it('rejects a candidate the probe refuses and falls through to a later one', () => {
+    // An unrelated `pi` on the service PATH (probe returns null) must not mask
+    // the real coding agent found by the login shell.
+    const impostor = '/service/bin/pi';
+    const genuine = '/login-shell/bin/pi';
+    const probe = vi.fn((binPath: string) => (binPath === genuine ? '0.84.1' : null));
+    const resolver = createPiResolverForTest(
+      createHost({
+        processPathResult: impostor,
+        loginShellResults: [genuine],
+        existingPaths: [impostor, genuine],
+      }),
+      probe
+    );
+
+    expect(resolver.resolve()).toMatchObject({ binaryPath: genuine, source: 'login-shell', metadata: '0.84.1' });
+  });
+
+  it('negative-caches a miss and retries only after the backoff elapses', () => {
+    const binaryPath = '/late/bin/pi';
+    let now = 0;
+    const probe = vi.fn(() => '0.84.1');
+    const resolver = createPiResolverForTest(
+      createHost({ loginShellResults: [null, binaryPath], existingPaths: [binaryPath] }),
+      probe,
+      () => now
+    );
+
+    expect(resolver.resolve()).toBeNull();
+    expect(resolver.resolve()).toBeNull(); // within the backoff: no re-run
+    expect(probe).not.toHaveBeenCalled();
+    now = cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()?.metadata).toBe('0.84.1');
+    expect(resolver.resolve()?.binaryPath).toBe(binaryPath);
+  });
+
+  it('never executes a pi candidate under vitest (the ambient probe is VITEST-gated)', () => {
+    // A REAL executable fixture that prints a valid version. If the guard in
+    // probePiVersion is ever removed again, the probe runs this script, the
+    // resolution SUCCEEDS, and this test fails — pinning hermeticity by
+    // behavior rather than by source text. (The suites must never execute
+    // whatever `pi` binary the machine running them happens to carry.)
+    const root = mkdtempSync(join(tmpdir(), 'codeman-pi-vitest-gate-'));
+    temporaryDirectories.push(root);
+    const binaryPath = join(root, 'pi');
+    writeFileSync(binaryPath, '#!/bin/sh\necho 0.99.0\n');
+    chmodSync(binaryPath, 0o755);
+    const hostOptions = {
+      processPath: root,
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'] as string[],
+      runCommand: () => '',
+      isExecutableFile: (path: string) => path === binaryPath,
+    };
+
+    // Default (ambient) probe: the candidate is found but never executed, so
+    // the VITEST gate reports it unusable and resolution misses.
+    const gated = createPiResolverForTest(createProductionCliResolverHost(hostOptions));
+    expect(gated.resolve()).toBeNull();
+
+    // Control: identical setup with an injected probe resolves, proving the
+    // null above comes from the gate, not from the fixture or the host.
+    const control = createPiResolverForTest(createProductionCliResolverHost(hostOptions), () => '0.99.0');
+    expect(control.resolve()).toMatchObject({ binaryPath, metadata: '0.99.0' });
+  });
+});

test/ralph-loop.test.ts

@@ -129,6 +129,36 @@ describe('RalphLoop', () => {
     vi.useRealTimers();
   });
 
+  describe('reschedule loop (regression)', () => {
+    // tick() is the only path that calls setRalphLoopState with lastCheckAt and
+    // no status field; start() carries status:'running', stop() status:'stopped'.
+    const countTicks = () =>
+      (mockState.store.setRalphLoopState as any).mock.calls.filter(
+        (c: any[]) => c[0]?.lastCheckAt !== undefined && c[0]?.status === undefined
+      ).length;
+
+    it('keeps rescheduling past the second tick', async () => {
+      // Real timers + a tiny poll interval: tick()'s async internals settle
+      // naturally on the event loop, avoiding fake-timer microtask fragility.
+      vi.useRealTimers();
+      loop.destroy();
+      // Keep the loop in the "running, should keep polling" state so it actually
+      // exercises the reschedule path: min duration unreached + autoGenerate on
+      // makes shouldStop() false (idle sessions are mocked empty, so nothing is
+      // actually generated). Otherwise an empty queue self-stops after 1 tick.
+      loop = new RalphLoop({ pollIntervalMs: 5, minDurationMs: 60_000, autoGenerateTasks: true });
+
+      await loop.start();
+      await new Promise((resolve) => setTimeout(resolve, 80)); // ~16 poll intervals
+      loop.stop();
+
+      // The bug: the loopTimer handle is never nulled in the setTimeout callback,
+      // so the `loopTimer === null` reschedule guard is false after the first fire
+      // and the loop dies at exactly 2 ticks. Fixed -> many ticks.
+      expect(countTicks()).toBeGreaterThanOrEqual(3);
+    });
+  });
+
   describe('initial state', () => {
     it('should start in stopped status', () => {
       expect(loop.status).toBe('stopped');
@@ -296,11 +326,7 @@ describe('RalphLoop', () => {
   describe('getStats', () => {
     it('should return complete stats object', async () => {
       const mockRunningTask = { id: '2', status: 'running', isTimedOut: () => false };
-      mockState.taskQueue.tasks = [
-        { id: '1', status: 'pending' },
-        mockRunningTask,
-        { id: '3', status: 'completed' },
-      ];
+      mockState.taskQueue.tasks = [{ id: '1', status: 'pending' }, mockRunningTask, { id: '3', status: 'completed' }];
       mockState.taskQueue.getRunningTasks.mockReturnValue([mockRunningTask]);
 
       await loop.start();

test/repo-status.test.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Unit tests for the repository-status pure helpers: ahead/behind
+ * + log + symref parsing, env parsing, the remote-set / role / tracking-remote
+ * decisions, credential redaction of the returned fields, and the single-flight
+ * TTL cache that keeps the async status computation off the git hot path.
+ * No IO, no git, no port — safe to run individually.
+ *
+ * npm test -- test/repo-status.test.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseAheadBehind,
+  parseLogLines,
+  parseSymrefDefaultBranch,
+  parseRemotesEnv,
+  parseTrackingRemote,
+  resolveRemoteSet,
+  roleForRemote,
+  isSafeGitPositional,
+  redactRemoteStatus,
+  createSingleFlightCache,
+} from '../src/web/repo-status.js';
+import { redactGitCredentials } from '../src/git-clone.js';
+import type { RepoRemoteStatus } from '../src/types/update.js';
+
+describe('parseAheadBehind', () => {
+  it('parses tab-separated left/right counts as ahead/behind', () => {
+    expect(parseAheadBehind('3\t14')).toEqual({ ahead: 3, behind: 14 });
+  });
+  it('parses space-separated counts', () => {
+    expect(parseAheadBehind('0 0')).toEqual({ ahead: 0, behind: 0 });
+  });
+  it('tolerates surrounding whitespace/newline', () => {
+    expect(parseAheadBehind('  5   2 \n')).toEqual({ ahead: 5, behind: 2 });
+  });
+  it('returns null on malformed output', () => {
+    expect(parseAheadBehind('')).toBeNull();
+    expect(parseAheadBehind('abc')).toBeNull();
+    expect(parseAheadBehind('1')).toBeNull();
+  });
+});
+
+describe('parseLogLines', () => {
+  it('splits each line into sha + subject', () => {
+    const out = 'a1b2c3 fix: thing\nd4e5f6 COD-9 add digest';
+    expect(parseLogLines(out)).toEqual([
+      { sha: 'a1b2c3', subject: 'fix: thing' },
+      { sha: 'd4e5f6', subject: 'COD-9 add digest' },
+    ]);
+  });
+  it('handles a subject with no space (sha only)', () => {
+    expect(parseLogLines('deadbee')).toEqual([{ sha: 'deadbee', subject: '' }]);
+  });
+  it('ignores blank lines', () => {
+    expect(parseLogLines('\n  \nabc123 hi\n')).toEqual([{ sha: 'abc123', subject: 'hi' }]);
+  });
+  it('returns [] for empty input', () => {
+    expect(parseLogLines('')).toEqual([]);
+  });
+});
+
+describe('parseSymrefDefaultBranch', () => {
+  it('extracts the default branch from ls-remote --symref output', () => {
+    const out = 'ref: refs/heads/master\tHEAD\n0123abc\tHEAD';
+    expect(parseSymrefDefaultBranch(out)).toBe('master');
+  });
+  it('handles main', () => {
+    expect(parseSymrefDefaultBranch('ref: refs/heads/main\tHEAD')).toBe('main');
+  });
+  it('returns null when no symref line present', () => {
+    expect(parseSymrefDefaultBranch('0123abc\tHEAD')).toBeNull();
+  });
+  it('rejects a hostile branch that would smuggle a git flag (argv injection)', () => {
+    // A malicious remote sets HEAD to a `-`-leading "branch"; the capture must
+    // not start with `-`, so this yields null rather than `--upload-pack=...`.
+    expect(parseSymrefDefaultBranch('ref: refs/heads/--upload-pack=touch\tHEAD')).toBeNull();
+  });
+});
+
+describe('isSafeGitPositional', () => {
+  it('accepts normal remote/branch names', () => {
+    expect(isSafeGitPositional('origin')).toBe(true);
+    expect(isSafeGitPositional('feature/foo')).toBe(true);
+  });
+  it('rejects flag-injecting and empty values', () => {
+    expect(isSafeGitPositional('--upload-pack=touch /tmp/x')).toBe(false);
+    expect(isSafeGitPositional('-x')).toBe(false);
+    expect(isSafeGitPositional('')).toBe(false);
+    expect(isSafeGitPositional(null)).toBe(false);
+    expect(isSafeGitPositional(undefined)).toBe(false);
+  });
+});
+
+describe('parseRemotesEnv', () => {
+  it('splits comma list, trims, drops empties', () => {
+    expect(parseRemotesEnv('origin, bitbucket ,, fork')).toEqual(['origin', 'bitbucket', 'fork']);
+  });
+  it('returns [] for null/undefined/empty', () => {
+    expect(parseRemotesEnv(null)).toEqual([]);
+    expect(parseRemotesEnv(undefined)).toEqual([]);
+    expect(parseRemotesEnv('')).toEqual([]);
+  });
+});
+
+describe('resolveRemoteSet', () => {
+  it('defaults to tracking-remote first, then origin (the maintainer-fork layout)', () => {
+    // local branch tracks bitbucket; origin is the canonical upstream.
+    const set = resolveRemoteSet({
+      existingRemotes: ['bitbucket', 'fork', 'origin'],
+      trackingRemote: 'bitbucket',
+      envRemotes: [],
+    });
+    expect(set).toEqual(['bitbucket', 'origin']);
+  });
+
+  it('collapses to a single entry when origin IS the tracking remote', () => {
+    const set = resolveRemoteSet({
+      existingRemotes: ['origin'],
+      trackingRemote: 'origin',
+      envRemotes: [],
+    });
+    expect(set).toEqual(['origin']);
+  });
+
+  it('falls back to just origin when there is no tracking remote', () => {
+    const set = resolveRemoteSet({
+      existingRemotes: ['origin', 'fork'],
+      trackingRemote: null,
+      envRemotes: [],
+    });
+    expect(set).toEqual(['origin']);
+  });
+
+  it('honors CODEMAN_UPDATE_REMOTES order and filters to existing remotes', () => {
+    const set = resolveRemoteSet({
+      existingRemotes: ['origin', 'bitbucket', 'fork'],
+      trackingRemote: 'bitbucket',
+      envRemotes: ['fork', 'origin', 'ghost'],
+    });
+    expect(set).toEqual(['fork', 'origin']); // 'ghost' dropped (does not exist)
+  });
+
+  it('returns [] when env names none of the existing remotes', () => {
+    const set = resolveRemoteSet({
+      existingRemotes: ['origin'],
+      trackingRemote: null,
+      envRemotes: ['nope'],
+    });
+    expect(set).toEqual([]);
+  });
+});
+
+describe('roleForRemote', () => {
+  it('labels the tracking remote as tracking even if named origin', () => {
+    expect(roleForRemote('origin', 'origin')).toBe('tracking');
+    expect(roleForRemote('bitbucket', 'bitbucket')).toBe('tracking');
+  });
+  it('labels origin/upstream (when not tracking) as upstream', () => {
+    expect(roleForRemote('origin', 'bitbucket')).toBe('upstream');
+    expect(roleForRemote('upstream', 'origin')).toBe('upstream');
+  });
+  it('labels anything else as other', () => {
+    expect(roleForRemote('fork', 'bitbucket')).toBe('other');
+  });
+});
+
+describe('parseTrackingRemote', () => {
+  it('extracts the remote name from a remote-tracking short ref', () => {
+    expect(parseTrackingRemote('origin/master')).toBe('origin');
+    expect(parseTrackingRemote('bitbucket/feature/nested')).toBe('bitbucket');
+  });
+  it('returns null for a LOCAL-branch upstream (ref with no slash)', () => {
+    // `git branch -u otherbranch` makes @{upstream} a bare branch name; the old
+    // slice(0, indexOf('/')) turned "master" into "maste" here.
+    expect(parseTrackingRemote('master')).toBeNull();
+    expect(parseTrackingRemote('main')).toBeNull();
+  });
+  it('returns null for null/empty/degenerate refs', () => {
+    expect(parseTrackingRemote(null)).toBeNull();
+    expect(parseTrackingRemote(undefined)).toBeNull();
+    expect(parseTrackingRemote('')).toBeNull();
+    expect(parseTrackingRemote('/leading-slash')).toBeNull();
+  });
+});
+
+describe('credential redaction', () => {
+  it('redactGitCredentials masks scheme://user:secret@host pairs', () => {
+    expect(redactGitCredentials('https://user:ghp_token123@github.com/o/r.git')).toBe(
+      'https://***:***@github.com/o/r.git'
+    );
+    expect(redactGitCredentials('plain text, no url')).toBe('plain text, no url');
+    expect(redactGitCredentials('https://github.com/o/r.git')).toBe('https://github.com/o/r.git');
+  });
+
+  it('redactRemoteStatus masks the url field', () => {
+    const status: RepoRemoteStatus = {
+      name: 'origin',
+      url: 'https://alice:s3cret@example.com/repo.git',
+      role: 'upstream',
+      compareRef: 'origin/master',
+      ahead: 1,
+      behind: 2,
+      incoming: [{ sha: 'abc', subject: 'hi' }],
+    };
+    const out = redactRemoteStatus(status);
+    expect(out.url).toBe('https://***:***@example.com/repo.git');
+    // Everything else passes through untouched.
+    expect(out.name).toBe('origin');
+    expect(out.compareRef).toBe('origin/master');
+    expect(out.ahead).toBe(1);
+    expect(out.behind).toBe(2);
+    expect(out.incoming).toEqual([{ sha: 'abc', subject: 'hi' }]);
+    expect(out.error).toBeUndefined();
+  });
+
+  it('redactRemoteStatus masks credentials echoed into the error string by git stderr', () => {
+    const status: RepoRemoteStatus = {
+      name: 'origin',
+      url: 'https://alice:s3cret@example.com/repo.git',
+      role: 'upstream',
+      compareRef: '',
+      ahead: 0,
+      behind: 0,
+      incoming: [],
+      error: "Could not reach origin: fatal: unable to access 'https://alice:s3cret@example.com/repo.git/'",
+    };
+    const out = redactRemoteStatus(status);
+    expect(out.error).toBe("Could not reach origin: fatal: unable to access 'https://***:***@example.com/repo.git/'");
+    expect(out.error).not.toContain('s3cret');
+    expect(out.url).not.toContain('s3cret');
+  });
+});
+
+describe('createSingleFlightCache', () => {
+  it('shares one in-flight computation across concurrent callers', async () => {
+    let calls = 0;
+    let release!: (v: string) => void;
+    const cache = createSingleFlightCache(60_000, () => {
+      calls++;
+      return new Promise<string>((resolve) => {
+        release = resolve;
+      });
+    });
+    const a = cache.get();
+    const b = cache.get();
+    release('result');
+    expect(await a).toBe('result');
+    expect(await b).toBe('result');
+    expect(calls).toBe(1);
+  });
+
+  it('serves a fresh-enough cached result without recomputing', async () => {
+    let calls = 0;
+    const cache = createSingleFlightCache(60_000, async () => ++calls);
+    expect(await cache.get()).toBe(1);
+    expect(await cache.get()).toBe(1);
+    expect(calls).toBe(1);
+  });
+
+  it('recomputes once the TTL has elapsed', async () => {
+    let calls = 0;
+    const cache = createSingleFlightCache(60_000, async () => ++calls);
+    expect(await cache.get()).toBe(1);
+    // Inject a "now" past the TTL instead of sleeping.
+    expect(await cache.get(Date.now() + 60_001)).toBe(2);
+    expect(calls).toBe(2);
+  });
+
+  it('does not cache a rejected computation — the next call retries', async () => {
+    let calls = 0;
+    const cache = createSingleFlightCache(60_000, async () => {
+      calls++;
+      if (calls === 1) throw new Error('boom');
+      return 'ok';
+    });
+    await expect(cache.get()).rejects.toThrow('boom');
+    expect(await cache.get()).toBe('ok');
+    expect(calls).toBe(2);
+  });
+});

test/response-viewer-transcript.test.ts

@@ -0,0 +1,462 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getLastTranscriptResponse,
+  isExternalCliTranscriptMode,
+  parseExternalCliTranscript,
+} from '../src/web/response-viewer-transcript.js';
+import { isExternalCliMode } from '../src/session.js';
+import type { SessionMode } from '../src/types.js';
+
+describe('response viewer transcript parser', () => {
+  it('extracts structured COD transcript blocks and keeps labeled status/tool entries', () => {
+    const transcript = `
+╭──────────────────────────────────────────────────────╮
+│ >_ OpenAI Codex (v0.143.0)                           │
+│ model:     gpt-5.4 medium   /model to change         │
+│ directory: /mnt/c/Users/aakhter/.../kb              │
+╰──────────────────────────────────────────────────────╯
+
+Tip: Use /side to start a side conversation in a temporary fork without polluting the main thread.
+
+› i need to create a naming recommendation for project helix
+
+gpt-5.4 medium · kb · main · Ready · Context 100% left
+
+• Explored
+  └ Read SKILL.md
+
+Subject: Naming Recommendation for Project Helix
+
+The product helps customers move virtual machine workloads between hypervisors while keeping operations
+stable. It improves visibility into application dependencies, supports pre-migration validation, and reduces
+the risk
+and effort involved in moving workloads.
+
+› Improve documentation in @filename
+
+gpt-5.4 medium · kb · main · Ready · Context 92% left
+`.trim();
+
+    const blocks = parseExternalCliTranscript(transcript, 'codex');
+
+    expect(blocks.map((block) => block.kind)).toEqual([
+      'status',
+      'prompt',
+      'status',
+      'tool',
+      'response',
+      'prompt',
+      'status',
+    ]);
+    expect(blocks[0]?.label).toBe('Status');
+    expect(blocks[3]?.label).toBe('Tool');
+    expect(blocks[4]?.text).toContain('reduces the risk and effort involved');
+    expect(blocks[4]?.text).not.toContain('reduces\nthe risk');
+
+    // The frontend's loadFullContext() renders via msg.role: 'user' gets the
+    // "You" badge, everything else the agent badge. A block without role
+    // rendered every prompt as the agent.
+    expect(blocks[1]?.role).toBe('user');
+    expect(blocks[5]?.role).toBe('user');
+    expect(blocks[0]?.role).toBe('assistant');
+    expect(blocks[3]?.role).toBe('assistant');
+    expect(blocks[4]?.role).toBe('assistant');
+  });
+
+  it('returns the most recent completed response when the last block is a new prompt', () => {
+    const transcript = `
+› say again
+
+Final polished answer
+With two lines
+
+› Improve documentation in @filename
+
+gpt-5.4 medium · kb · main · Ready · Context 92% left
+`.trim();
+
+    const blocks = parseExternalCliTranscript(transcript, 'codex');
+
+    expect(getLastTranscriptResponse(blocks)).toBe('Final polished answer\nWith two lines');
+  });
+
+  it('drops box-drawing dividers from the last response and treats worked-for lines as status', () => {
+    const transcript = `
+────────────────────────────────────────────────────────────────────────
+
+• The launcher supports CODEMAN_APP_DIR, so I can deploy this exact worktree without merging it back first.
+
+────────────────────────────────────────────────────────────────────────
+
+• Deployed.
+
+The local Codeman service is now running from the worktree at app/.worktrees/cod-215-response-viewer on
+commit 8bbcf77bafbdbf01a34653386c256b685898ad06.
+
+Verified:
+
+- process pid: 2708947
+- HTTPS health: https://127.0.0.1:3000/ returned 401 as expected
+
+One detail: I had to restart it outside the sandbox because the sandboxed launch path could not see tmux.
+
+─ Worked for 1m 51s ───────────────────────────────────────────────────
+
+› what are these lines in the middle column?
+`.trim();
+
+    const blocks = parseExternalCliTranscript(transcript, 'codex');
+
+    expect(getLastTranscriptResponse(blocks)).toContain('• Deployed.');
+    expect(getLastTranscriptResponse(blocks)).not.toContain('────────────────');
+    expect(getLastTranscriptResponse(blocks)).not.toContain('Worked for 1m 51s');
+    expect(blocks.some((block) => block.kind === 'status' && block.text === 'Worked for 1m 51s')).toBe(true);
+  });
+
+  // COD-226: multiline prompt continuations (2-space Codex gutter) must stay in the
+  // Prompt block, not be misclassified as Response. The gutter is authoritative ahead
+  // of every structural detector (divider, prompt-marker, tool, status).
+  describe('COD-226 multiline prompt gutter is authoritative', () => {
+    it('keeps bullet/prose continuations and internal blank lines in the Prompt block', () => {
+      const transcript = `
+› i think we can improve this slide. or maybe a follow on slide. here is what i'm thinking:
+  * left hand side: current AI stack (frontier model, cloud hosted, sovereign concerns)
+  right hand -> future enterprise stack: frontier model (optional, cloud), on-prem model router, OSS models
+
+  make the point that the right hand side addresses the concerns.
+
+gpt-5.4 medium · kb · main · Ready · Context 100% left
+
+• Explored
+  └ Read SKILL.md
+
+Here is the actual assistant answer that starts at column zero and is a real response.
+
+› next prompt
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      // Exactly two prompts, and the first holds the whole multiline prompt.
+      expect(promptBlocks).toHaveLength(2);
+      expect(promptBlocks[0]?.text).toContain('left hand side');
+      expect(promptBlocks[0]?.text).toContain('right hand');
+      expect(promptBlocks[0]?.text).toContain('make the point that the right hand side');
+
+      // The continuation must NOT have leaked into a Response block.
+      const responseBlocks = blocks.filter((b) => b.kind === 'response');
+      expect(responseBlocks.some((b) => b.text.includes('make the point'))).toBe(false);
+      expect(getLastTranscriptResponse(blocks)).toContain('actual assistant answer');
+      expect(getLastTranscriptResponse(blocks)).not.toContain('make the point');
+    });
+
+    it('does not let an indented divider inside a prompt flush the Prompt block', () => {
+      const transcript = `
+› compare these two layouts
+  first layout uses a single column
+  ────────────────────────────
+  second layout uses two columns
+
+The response begins here at column zero.
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      expect(promptBlocks).toHaveLength(1);
+      expect(promptBlocks[0]?.text).toContain('first layout');
+      expect(promptBlocks[0]?.text).toContain('second layout uses two columns');
+      expect(getLastTranscriptResponse(blocks)).toBe('The response begins here at column zero.');
+    });
+
+    it('treats a gutter-indented literal › as prompt content, not a new prompt', () => {
+      const transcript = `
+› here is my question about the ui
+  › should this arrow start a new prompt?
+  no it should not — it is part of my question
+
+Answer at column zero.
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      // The gutter-indented › must NOT open a second prompt.
+      expect(promptBlocks).toHaveLength(1);
+      expect(promptBlocks[0]?.text).toContain('here is my question');
+      expect(promptBlocks[0]?.text).toContain('no it should not');
+      expect(getLastTranscriptResponse(blocks)).toBe('Answer at column zero.');
+    });
+
+    // The two exact live roadmap-tab examples from the ticket (AC: use both verbatim).
+    it('live example 1: two-line prompt keeps the gutter continuation in the Prompt block', () => {
+      const transcript = `
+› create uid for each feature so it's easy to ref.
+  for the p200 - why is diffentiation only 2/5?
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      expect(promptBlocks).toHaveLength(1);
+      expect(promptBlocks[0]?.text).toContain('create uid for each feature');
+      expect(promptBlocks[0]?.text).toContain('for the p200 - why is diffentiation only 2/5?');
+      // The continuation must not have leaked into a Response block.
+      expect(blocks.some((b) => b.kind === 'response')).toBe(false);
+    });
+
+    it('live example 2: five-line prompt (bullet + prose + blank + prose) stays one Prompt block', () => {
+      const transcript = `
+› i think we can improve this slide. or maybe a follow on slide. here is what i'm thinking:
+  * left hand side... current AI stack: (frontier model), large component cloud hosted, soverign concerns etc.
+  right hand -> future-enterprise-stack: frontier-model (optional, in cloud), on-prem: model router, OSS models, rest of stack (gpus, data, etc.)
+
+  make the point that the right hand side addresses the concerns.
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      expect(promptBlocks).toHaveLength(1);
+      expect(promptBlocks[0]?.text).toContain('left hand side');
+      expect(promptBlocks[0]?.text).toContain('right hand -> future-enterprise-stack');
+      expect(promptBlocks[0]?.text).toContain('make the point that the right hand side addresses the concerns');
+      expect(blocks.some((b) => b.kind === 'response')).toBe(false);
+    });
+
+    it('still separates a single-line prompt from a column-zero response (no regression)', () => {
+      const transcript = `
+› say again
+
+Final polished answer at column zero.
+
+› next
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+      const promptBlocks = blocks.filter((b) => b.kind === 'prompt');
+
+      expect(promptBlocks).toHaveLength(2);
+      expect(promptBlocks[0]?.text).toBe('say again');
+      expect(getLastTranscriptResponse(blocks)).toBe('Final polished answer at column zero.');
+    });
+  });
+
+  // COD-227: Last Response must return the final assistant answer, not tool logs.
+  // A response bullet beginning with a tool-like verb (• Created …) must not be
+  // classified as Tool, and genuine • Calling / • Called blocks must be classified
+  // as Tool. Disambiguator: a verb-bullet is a tool header only when followed by a
+  // box-drawing result tree (└│├); Calling/Called are always tool markers.
+  describe('COD-227 tool-header vs response disambiguation', () => {
+    const MINIMAL_REPRO = `
+› new jira issue
+
+• The fresh read shows a formatting problem.
+
+• Calling
+└ atlassian.jira_update_issue({})
+
+• Called atlassian.jira_get_issue({})
+└ { result: true }
+
+• Created COD-226: View Response → More misclassifies multiline prompt continuations as responses.
+
+  It includes:
+
+  - Two concrete failures
+  - Regression-test criteria
+`.trim();
+
+    it('returns the final • Created … answer, not the Jira Calling/Called tool log', () => {
+      const blocks = parseExternalCliTranscript(MINIMAL_REPRO, 'codex');
+      const last = getLastTranscriptResponse(blocks);
+
+      expect(last).toContain('Created COD-226');
+      expect(last).toContain('Two concrete failures');
+      // Must exclude tool invocations, raw results, and earlier commentary.
+      expect(last).not.toContain('atlassian.jira');
+      expect(last).not.toContain('Calling');
+      expect(last).not.toContain('Called');
+      expect(last).not.toContain('fresh read');
+    });
+
+    it('classifies genuine • Calling / • Called (with box-drawing results) as Tool', () => {
+      const blocks = parseExternalCliTranscript(MINIMAL_REPRO, 'codex');
+      const toolText = blocks
+        .filter((b) => b.kind === 'tool')
+        .map((b) => b.text)
+        .join('\n');
+
+      expect(toolText).toContain('Calling');
+      expect(toolText).toContain('Called');
+      expect(toolText).toContain('atlassian.jira_update_issue');
+      // The final answer must not have been swallowed into the tool block.
+      expect(toolText).not.toContain('Created COD-226');
+    });
+
+    it('labels the repro chronologically: Prompt, Response (commentary), Tool, Response (final)', () => {
+      const blocks = parseExternalCliTranscript(MINIMAL_REPRO, 'codex');
+
+      expect(blocks.map((b) => b.kind)).toEqual(['prompt', 'response', 'tool', 'response']);
+      expect(blocks[1]?.text).toContain('fresh read');
+      expect(blocks[3]?.text).toContain('Created COD-226');
+    });
+
+    it('does not classify a verb-prefixed prose bullet as Tool when no result tree follows', () => {
+      const transcript = `
+› do it
+
+• Created COD-999: a brand new issue with a descriptive title.
+
+  Follow-up prose that belongs to the same answer.
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+
+      expect(blocks.some((b) => b.kind === 'tool')).toBe(false);
+      expect(getLastTranscriptResponse(blocks)).toContain('Created COD-999');
+      expect(getLastTranscriptResponse(blocks)).toContain('Follow-up prose');
+    });
+
+    it('does not regress a genuine verb tool block that has a box-drawing continuation', () => {
+      const transcript = `
+› look around
+
+• Explored
+  └ Read SKILL.md
+
+Here is the assistant answer at column zero.
+`.trim();
+
+      const blocks = parseExternalCliTranscript(transcript, 'codex');
+
+      expect(blocks.some((b) => b.kind === 'tool' && b.text.includes('Explored'))).toBe(true);
+      expect(getLastTranscriptResponse(blocks)).toBe('Here is the assistant answer at column zero.');
+    });
+  });
+
+  // The divider-status detector used to be /^[─-]+\s*(.+?)\s*[─-]{3,}$/, whose
+  // lazy middle backtracked catastrophically on a long dash run that does not
+  // end in 3+ dashes (measured >2min at 8,000 chars). Pane text is
+  // agent-controlled and buffers reach 32MB, so the pattern was replaced by a
+  // linear counter walk. Same approach as the glob-matcher ReDoS fix (68ae9a8):
+  // the hostile input below fails by timeout with the RegExp version.
+  describe('divider-status ReDoS hardening', () => {
+    it('classifies a hostile 10k dash run in linear time', () => {
+      const hostile = '-'.repeat(10_000) + '>';
+      const started = Date.now();
+      const blocks = parseExternalCliTranscript(`› q\n${hostile}`, 'opencode');
+      const elapsed = Date.now() - started;
+
+      expect(elapsed).toBeLessThan(2_000);
+      // No 3-dash tail, so the line is not a status divider — it stays prose.
+      expect(blocks.some((b) => b.kind === 'response' && b.text.includes('>'))).toBe(true);
+      expect(blocks.some((b) => b.kind === 'status')).toBe(false);
+    });
+
+    // The counter walk must keep the EXACT accept set and captured content of
+    // the old regex (including its backtracking quirks on all-dash lines), so
+    // brute-force both against a corpus. The old regex is safe here: probes are
+    // capped at 24 chars, far below the blowup threshold.
+    it('matches the old regex char-for-char on a brute-force corpus', () => {
+      const oldNormalize = (line: string): string | null => {
+        const trimmed = line.trim();
+        const matched = trimmed.match(/^[─-]+\s*(.+?)\s*[─-]{3,}$/);
+        if (!matched) return null;
+        return matched[1]?.trim() || null;
+      };
+
+      // Observe the private normalizeDividerStatusLine through the parser: after
+      // a prompt, a column-zero probe from this alphabet is a status block iff
+      // the divider detector matched, and the status text is its return value.
+      // (The alphabet triggers no other status arm; letters are limited to 'x'.)
+      const observedStatusText = (probe: string): string | null => {
+        const blocks = parseExternalCliTranscript(`› q\n${probe}`, 'opencode');
+        const status = blocks.find((b) => b.kind === 'status');
+        return status ? status.text : null;
+      };
+
+      const directed = [
+        '──── Status ────',
+        '─ Worked for 1m 51s ───────',
+        '---',
+        '----',
+        '-----',
+        '------',
+        '-------',
+        '---- ---',
+        '-    ---',
+        '--x',
+        'x---',
+        '----x',
+        '----x--',
+        '----x---',
+        '─x───',
+        '- x ---',
+        '--- x -',
+        '─── ──',
+        '-\tx\t---',
+        '--->----',
+        '─-─- x x ─-─',
+        '- x x x ----',
+      ];
+
+      // Deterministic LCG so a failure reproduces byte-identically.
+      let seed = 0x2f6e2b1;
+      const rand = () => {
+        seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+        return seed / 0x80000000;
+      };
+      const alphabet = ['-', '-', '─', '─', ' ', ' ', '\t', 'x', '>'];
+      const probes = [...directed];
+      for (let i = 0; i < 3000; i += 1) {
+        const len = Math.floor(rand() * 25);
+        let probe = '';
+        for (let j = 0; j < len; j += 1) {
+          probe += alphabet[Math.floor(rand() * alphabet.length)];
+        }
+        probes.push(probe);
+      }
+
+      for (const raw of probes) {
+        const probe = raw.trim();
+        // Divider-only lines (8+ dash/whitespace chars) are consumed by
+        // isDividerOnlyLine before the status detector ever runs, in both the
+        // old and new worlds — the detector is unobservable there.
+        if (!probe || /^[\s─-]{8,}$/.test(probe)) continue;
+        expect(observedStatusText(probe), `probe: ${JSON.stringify(probe)}`).toBe(oldNormalize(probe));
+      }
+    });
+  });
+
+  // EXTERNAL_CLI_MODES is a local duplicate of isExternalCliMode() in
+  // src/session.ts (importing session.ts would drag node-pty and the whole
+  // session layer into the pure transcript module). This pin is what keeps the
+  // two from drifting — 'pi' was missing here while isExternalCliMode() had it,
+  // which left pi sessions with the exact empty-viewer symptom the transcript
+  // branch exists to fix.
+  describe('mode parity with isExternalCliMode()', () => {
+    // Exhaustive by construction: adding a SessionMode without deciding its
+    // transcript behavior fails to compile here.
+    const ALL_SESSION_MODES: Record<SessionMode, true> = {
+      claude: true,
+      shell: true,
+      opencode: true,
+      codex: true,
+      gemini: true,
+      antigravity: true,
+      pi: true,
+    };
+
+    it('agrees with isExternalCliMode() for every SessionMode', () => {
+      for (const mode of Object.keys(ALL_SESSION_MODES) as SessionMode[]) {
+        expect(isExternalCliTranscriptMode(mode), `mode: ${mode}`).toBe(isExternalCliMode(mode));
+      }
+    });
+
+    it('covers pi', () => {
+      expect(isExternalCliTranscriptMode('pi')).toBe(true);
+    });
+  });
+});

test/routes/session-routes-external-cli-last-response.test.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview Tests for the external-CLI branch of GET /api/sessions/:id/last-response.
+ *
+ * Uses app.inject() — no real HTTP ports needed.
+ * Port: N/A (app.inject doesn't open ports)
+ *
+ * OpenCode / Gemini / Antigravity / Pi render their own TUIs and never write a
+ * Claude transcript under ~/.claude/projects, so before this branch existed the
+ * handler fell through to the Claude scan, found nothing, and the response viewer
+ * was permanently empty for those modes. These tests pin:
+ *   - the pane buffer is segmented and the LAST response is returned
+ *   - ?context=full carries the parsed blocks, and the short form omits them
+ *   - ?context=full blocks carry role — the frontend renders via msg.role, so a
+ *     block without it lost the "You" badge on prompts
+ *   - a pane that has produced no output reports hasContext: false rather than 404ing
+ *   - Claude mode still takes the Claude path (regression guard)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { createMockRouteContext, createMockSession, type MockRouteContext } from '../mocks/index.js';
+import { ApiErrorCode, httpStatusForErrorCode } from '../../src/types.js';
+import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
+
+interface LocalHarness {
+  app: FastifyInstance;
+  ctx: MockRouteContext;
+}
+
+/** Mirror of the production uniform-envelope hook (server.ts), as in the sibling suites. */
+async function createEnvelopeHarness(
+  registerFn: (app: FastifyInstance, ctx: MockRouteContext) => void
+): Promise<LocalHarness> {
+  const app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+
+  const ctx = createMockRouteContext();
+  registerFn(app, ctx);
+
+  app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
+    if (!req.url.startsWith('/api')) return done(null, payload);
+    if (payload === null || typeof payload !== 'object') return done(null, payload);
+    if (Buffer.isBuffer(payload) || typeof (payload as { pipe?: unknown }).pipe === 'function') {
+      return done(null, payload);
+    }
+    const p = payload as { success?: unknown; errorCode?: unknown };
+    if (p.success === false) {
+      if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
+        reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
+      }
+      return done(null, payload);
+    }
+    if (p.success === true) return done(null, payload);
+    return done(null, { success: true, data: payload });
+  });
+
+  await app.ready();
+  return { app, ctx };
+}
+
+// A pane as one of these CLIs actually leaves it: banner, a `›` prompt line, a
+// status divider, a tool-activity marker, then the assistant's prose.
+const PANE = `
+╭──────────────────────────────────────────────────────╮
+│ >_ OpenCode                                          │
+│ directory: /workspace/project                        │
+╰──────────────────────────────────────────────────────╯
+
+› summarise the retry logic
+
+model · project · main · Ready · Context 100% left
+
+• Explored
+  └ Read src/retry.ts
+
+The retry helper backs off exponentially and gives up after five attempts.
+
+› now document it
+
+model · project · main · Ready · Context 92% left
+
+• Called write_file
+
+Documented the helper in docs/retry.md, including the five-attempt ceiling.
+`.trim();
+
+describe('GET /api/sessions/:id/last-response — external CLI panes', () => {
+  let harness: LocalHarness;
+  let session: ReturnType<typeof createMockSession>;
+
+  beforeEach(async () => {
+    harness = await createEnvelopeHarness(registerSessionRoutes);
+    session = harness.ctx._session;
+  });
+
+  async function lastResponse(full = false) {
+    const res = await harness.app.inject({
+      method: 'GET',
+      url: `/api/sessions/${session.id}/last-response${full ? '?context=full' : ''}`,
+    });
+    return { res, body: JSON.parse(res.body) };
+  }
+
+  for (const mode of ['opencode', 'gemini', 'antigravity', 'pi'] as const) {
+    it(`returns the last assistant response from the ${mode} pane buffer`, async () => {
+      session.mode = mode;
+      session.terminalBuffer = PANE;
+
+      const { res, body } = await lastResponse();
+
+      expect(res.statusCode).toBe(200);
+      // The LAST response, not the first — the viewer shows the current turn.
+      expect(body.data.text).toContain('Documented the helper in docs/retry.md');
+      expect(body.data.text).not.toContain('backs off exponentially');
+      expect(body.data.hasContext).toBe(true);
+      // Short form stays short: blocks only travel under ?context=full.
+      expect(body.data.messages).toBeUndefined();
+    });
+  }
+
+  it('carries the parsed blocks under ?context=full', async () => {
+    session.mode = 'opencode';
+    session.terminalBuffer = PANE;
+
+    const { body } = await lastResponse(true);
+
+    const kinds = body.data.messages.map((block: { kind: string }) => block.kind);
+    expect(kinds).toContain('prompt');
+    expect(kinds).toContain('response');
+    expect(kinds).toContain('tool');
+    // Both user turns survive segmentation, so the viewer can show the exchange.
+    const prompts = body.data.messages.filter((b: { kind: string }) => b.kind === 'prompt');
+    expect(prompts).toHaveLength(2);
+    expect(prompts[1].text).toContain('now document it');
+
+    // loadFullContext() renders via msg.role — without it every block got the
+    // agent badge and the user's own prompts lost their "You" attribution.
+    for (const block of body.data.messages as Array<{ kind: string; role: string }>) {
+      expect(block.role).toBe(block.kind === 'prompt' ? 'user' : 'assistant');
+    }
+  });
+
+  it('reports hasContext false for a pane that has produced no output', async () => {
+    session.mode = 'gemini';
+    // Session created but nothing rendered yet. Any non-prompt line counts as
+    // prose to the parser, so the empty pane is the honest no-context case.
+    session.terminalBuffer = '';
+
+    const { res, body } = await lastResponse();
+
+    expect(res.statusCode).toBe(200);
+    expect(body.data.text).toBe('');
+    expect(body.data.hasContext).toBe(false);
+  });
+
+  it('leaves Claude mode on the Claude transcript path', async () => {
+    // Regression guard: a claude pane must NOT be segmented off its terminal
+    // buffer, or a real transcript would be shadowed by scraped pane text.
+    session.mode = 'claude';
+    session.terminalBuffer = PANE;
+
+    const { res, body } = await lastResponse();
+
+    expect(res.statusCode).toBe(200);
+    expect(body.data.text).not.toContain('Documented the helper');
+  });
+});

test/routes/session-routes.test.ts

@@ -789,6 +789,7 @@ describe('session-routes', () => {
       expect(body.data.terminalBuffer).toContain(lastLine);
       expect(body.data.source).toBe('mux-full-history');
       expect(typeof body.data.fullSize).toBe('number');
+      expect(res.headers['server-timing']).toMatch(/^capture;dur=\d+\.\d, prepare;dur=\d+\.\d, total;dur=\d+\.\d$/);
     });
 
     it('full reload (?full=1) returns the tmux capture ALONE — byte history is not duplicated', async () => {

test/terminal-auto-copy.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Auto Copy (copy-on-select) guards.
+ *
+ * The feature is invisible when it works, so every bug in it is silent: a
+ * clipboard that quietly stops updating, or one that quietly overwrites itself
+ * on an unrelated click. These tests drive the SHIPPED decision helper
+ * (constants.js) and the SHIPPED flush (terminal-ui.js), plus the settings
+ * wiring that decides whether the toggle reaches the code at all.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+const publicDir = resolve(import.meta.dirname, '../src/web/public');
+const read = (name: string) => readFileSync(resolve(publicDir, name), 'utf8');
+
+function loadHarness() {
+  const CodemanApp = function CodemanApp(this: any) {};
+  const windowRef: Record<string, any> = {};
+  const documentListeners = new Map<string, ((ev: any) => void)[]>();
+  let activeElement: any = null;
+  let now = 1_000;
+
+  const RealDate = Date;
+  const DateStub: any = function DateStub(this: any, ...args: any[]) {
+    return new (RealDate as any)(...args);
+  };
+  DateStub.now = () => now;
+
+  const context = vm.createContext({
+    window: windowRef,
+    document: {
+      body: { classList: { contains: () => false } },
+      get activeElement() {
+        return activeElement;
+      },
+      getElementById: () => null,
+      addEventListener: (type: string, listener: (ev: any) => void) => {
+        const list = documentListeners.get(type) ?? [];
+        list.push(listener);
+        documentListeners.set(type, list);
+      },
+    },
+    CodemanApp,
+    console: { warn: vi.fn(), log: vi.fn(), debug: vi.fn() },
+    _crashDiag: { log: vi.fn() },
+    Date: DateStub,
+    performance: { now: () => now },
+    requestAnimationFrame: (_fn: () => void) => 1,
+    setTimeout: (_fn: () => void) => 1,
+    Blob: function Blob() {},
+    URL: { createObjectURL: () => 'blob:yield', revokeObjectURL: () => {} },
+    Worker: function Worker(this: any) {
+      this.postMessage = () => {};
+    },
+    MobileDetection: { isTouchDevice: () => false },
+    KeyboardHandler: { keyboardVisible: false },
+    DEC_SYNC_STRIP_RE: /\x1b\[\?2026[hl]/g,
+    TERMINAL_CHUNK_SIZE: 32 * 1024,
+  });
+
+  vm.runInContext(read('constants.js'), context, { filename: 'constants.js' });
+  vm.runInContext(read('terminal-ui.js'), context, { filename: 'terminal-ui.js' });
+
+  const app = new (CodemanApp as any)();
+  const toasts: { message: string; type: string }[] = [];
+  app.showToast = (message: string, type: string) => toasts.push({ message, type });
+  app._copyText = vi.fn(async () => true);
+  app.loadAppSettingsFromStorage = () => ({ autoCopySelection: true });
+  app.terminal = {
+    hasSelection: () => true,
+    getSelection: () => 'copied text',
+    clearSelection: vi.fn(),
+    focus: vi.fn(),
+  };
+
+  return {
+    app,
+    windowRef,
+    toasts,
+    setNow: (value: number) => {
+      now = value;
+    },
+    setActiveElement: (element: any) => {
+      activeElement = element;
+    },
+  };
+}
+
+describe('decideAutoCopy', () => {
+  const decide = (params: Record<string, unknown>) => loadHarness().windowRef.CodemanAutoCopy.decide(params);
+
+  it('does nothing while the setting is off', () => {
+    expect(decide({ enabled: false, text: 'hello', pending: true })).toBe('skip');
+  });
+
+  it('ignores a blank or whitespace-only selection', () => {
+    // A drag across empty cells; a wall of spaces is never what the gesture meant.
+    expect(decide({ enabled: true, text: '   \n  ', pending: true })).toBe('skip');
+    expect(decide({ enabled: true, text: '', pending: true })).toBe('skip');
+  });
+
+  it('copies a genuine selection change even when the text repeats', () => {
+    // Re-selecting the same text after copying something else in between is a
+    // deliberate act, so `pending` outranks the text dedupe.
+    expect(decide({ enabled: true, text: 'same', lastCopied: 'same', pending: true })).toBe('copy');
+  });
+
+  it('copies changed text when onSelectionChange has not fired yet', () => {
+    // xterm fires onSelectionChange from its OWN document mouseup handler, and
+    // listener order between the two is not something the app controls, so the
+    // first copy of a drag must not depend on `pending`.
+    expect(decide({ enabled: true, text: 'fresh', lastCopied: 'stale', pending: false })).toBe('copy');
+  });
+
+  it('leaves an unchanged selection alone on an unrelated mouseup', () => {
+    expect(decide({ enabled: true, text: 'same', lastCopied: 'same', pending: false })).toBe('skip');
+  });
+
+  it('refuses a selection past the size cap instead of truncating it', () => {
+    const { windowRef } = loadHarness();
+    const huge = 'x'.repeat(windowRef.CodemanAutoCopy.MAX_CHARS + 1);
+    expect(windowRef.CodemanAutoCopy.decide({ enabled: true, text: huge, pending: true })).toBe('too-large');
+  });
+});
+
+describe('_flushAutoCopySelection', () => {
+  it('copies the selection without clearing it or stealing focus', async () => {
+    const { app } = loadHarness();
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).toHaveBeenCalledWith('copied text');
+    // The two things copyTerminalSelection does and this path must not: clearing
+    // makes the text vanish under the cursor that highlighted it, and focusing
+    // opens the on-screen keyboard over it on a phone.
+    expect(app.terminal.clearSelection).not.toHaveBeenCalled();
+    expect(app.terminal.focus).not.toHaveBeenCalled();
+  });
+
+  it('starts the copy synchronously, inside the gesture that triggered it', () => {
+    // Both clipboard paths need user activation: Firefox gates
+    // navigator.clipboard.writeText on it, and execCommand('copy') (the
+    // plain-HTTP fallback) must run in the gesture's own task.
+    const { app } = loadHarness();
+    app._autoCopyPending = true;
+
+    void app._flushAutoCopySelection();
+
+    expect(app._copyText).toHaveBeenCalledTimes(1);
+  });
+
+  it('stays silent while the setting is off', async () => {
+    const { app, toasts } = loadHarness();
+    app.loadAppSettingsFromStorage = () => ({ autoCopySelection: false });
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).not.toHaveBeenCalled();
+    expect(toasts).toEqual([]);
+  });
+
+  it('treats a missing setting as off', async () => {
+    const { app } = loadHarness();
+    app.loadAppSettingsFromStorage = () => ({});
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).not.toHaveBeenCalled();
+  });
+
+  it('announces itself once per page load, then goes quiet', async () => {
+    const { app, toasts } = loadHarness();
+    let text = 'first';
+    app.terminal.getSelection = () => text;
+
+    app._autoCopyPending = true;
+    await app._flushAutoCopySelection();
+    text = 'second';
+    app._autoCopyPending = true;
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).toHaveBeenCalledTimes(2);
+    expect(toasts).toEqual([{ message: 'Auto Copy: selection copied', type: 'success' }]);
+  });
+
+  it('disarms the pending flag so the next unrelated mouseup copies nothing', async () => {
+    const { app } = loadHarness();
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+    await app._flushAutoCopySelection();
+
+    expect(app._autoCopyPending).toBe(false);
+    expect(app._copyText).toHaveBeenCalledTimes(1);
+  });
+
+  it('hands focus back when the execCommand fallback took it', async () => {
+    const { app, setActiveElement } = loadHarness();
+    const terminalTextarea = { focus: vi.fn(), isConnected: true };
+    setActiveElement(terminalTextarea);
+    // The fallback appends a temp textarea, selects it, then removes it, which
+    // leaves the document with no focused element at all.
+    app._copyText = vi.fn(async () => {
+      setActiveElement(null);
+      return true;
+    });
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(terminalTextarea.focus).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves focus alone when the clipboard API never moved it', async () => {
+    const { app, setActiveElement } = loadHarness();
+    const terminalTextarea = { focus: vi.fn(), isConnected: true };
+    setActiveElement(terminalTextarea);
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(terminalTextarea.focus).not.toHaveBeenCalled();
+  });
+
+  it('reports a blocked clipboard and lets the next gesture retry the same text', async () => {
+    const { app, toasts } = loadHarness();
+    app._copyText = vi.fn(async () => false);
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+    expect(toasts).toEqual([{ message: 'Auto Copy failed: the browser blocked clipboard access', type: 'error' }]);
+
+    // Without the reset, the dedupe would swallow every retry of the same text.
+    app._autoCopyPending = false;
+    await app._flushAutoCopySelection();
+    expect(app._copyText).toHaveBeenCalledTimes(2);
+  });
+
+  it('throttles the failure toast so a blocked clipboard cannot spam every drag', async () => {
+    const { app, toasts, setNow } = loadHarness();
+    app._copyText = vi.fn(async () => false);
+
+    app._autoCopyPending = true;
+    await app._flushAutoCopySelection();
+    setNow(2_000);
+    app._autoCopyPending = true;
+    await app._flushAutoCopySelection();
+    expect(toasts).toHaveLength(1);
+
+    setNow(1_000 + 10_001);
+    app._autoCopyPending = true;
+    await app._flushAutoCopySelection();
+    expect(toasts).toHaveLength(2);
+  });
+
+  it('refuses an oversized selection and says how to copy it anyway', async () => {
+    const { app, toasts, windowRef } = loadHarness();
+    const huge = 'x'.repeat(windowRef.CodemanAutoCopy.MAX_CHARS + 1);
+    app.terminal.getSelection = () => huge;
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).not.toHaveBeenCalled();
+    expect(toasts).toEqual([{ message: 'Selection too large to copy automatically. Press Ctrl+C.', type: 'warning' }]);
+  });
+
+  it('does nothing when the selection was already dropped', async () => {
+    const { app } = loadHarness();
+    app.terminal.hasSelection = () => false;
+    app._autoCopyPending = true;
+
+    await app._flushAutoCopySelection();
+
+    expect(app._copyText).not.toHaveBeenCalled();
+  });
+});
+
+describe('Auto Copy wiring', () => {
+  const terminalUi = read('terminal-ui.js');
+  const settingsUi = read('settings-ui.js');
+  const html = read('index.html');
+  const schemas = readFileSync(resolve(import.meta.dirname, '../src/web/schemas.ts'), 'utf8');
+
+  it('arms on a selection change and disarms when the selection is dropped', () => {
+    const start = terminalUi.indexOf('this.terminal.onSelectionChange?.(');
+    expect(start).toBeGreaterThan(-1);
+    const body = terminalUi.slice(start, start + 1200);
+    expect(body).toContain('this._autoCopyPending = false;');
+    expect(body).toContain('this._autoCopyPending = true;');
+  });
+
+  it('flushes from the document mouseup, not from the selection change', () => {
+    // Copying inside onSelectionChange would be one clipboard write per cell the
+    // drag crosses.
+    expect(terminalUi).toContain("document.addEventListener('mouseup', () => this._flushAutoCopySelection());");
+    const start = terminalUi.indexOf('this.terminal.onSelectionChange?.(');
+    const body = terminalUi.slice(start, terminalUi.indexOf('_autoCopyListenerInstalled', start));
+    expect(body).not.toContain('_flushAutoCopySelection');
+  });
+
+  it('flushes from the touch gesture end, which never produces a mouseup', () => {
+    // The touch path preventDefaults its touchend to stop the compat mouse pair
+    // from stealing the selection back, so phones need their own call.
+    const start = terminalUi.indexOf('_endTouchSelectionGesture() {');
+    expect(start).toBeGreaterThan(-1);
+    expect(terminalUi.slice(start, start + 900)).toContain('this._flushAutoCopySelection();');
+  });
+
+  it('keeps the toggle per-device: display key, stripped from the PUT, absent from the schema', () => {
+    const displayKeys = settingsUi.slice(
+      settingsUi.indexOf('const displayKeys = new Set(['),
+      settingsUi.indexOf('])', settingsUi.indexOf('const displayKeys = new Set(['))
+    );
+    expect(displayKeys).toContain("'autoCopySelection'");
+    // SettingsUpdateSchema is .strict(), so a key it does not declare 400s the
+    // whole settings PUT if the client sends it.
+    expect(settingsUi).toContain('autoCopySelection: _acs,');
+    expect(schemas).not.toContain('autoCopySelection');
+  });
+
+  it('keeps the control loadable and savable by id', () => {
+    expect(html).toContain('id="appSettingsAutoCopySelection"');
+    expect(settingsUi).toContain(
+      "document.getElementById('appSettingsAutoCopySelection').checked = settings.autoCopySelection === true;"
+    );
+    expect(settingsUi).toContain("autoCopySelection: document.getElementById('appSettingsAutoCopySelection').checked,");
+  });
+});

test/terminal-copy-shortcut.test.ts

@@ -12,7 +12,7 @@
  * emitted through onData (the bytes that would reach the PTY).
  *
  * Browser-driven, so it is excluded from `npm run test:ci` like the other
- * Playwright suites. Run locally: npm test -- test/terminal-copy-shortcut.test.ts
+ * Playwright suites. Run locally: npm run test:browser -- test/terminal-copy-shortcut.test.ts
  *
  * Port: 3174 (per MEMORY.md, ports 3150+ for tests)
  */
@@ -23,6 +23,7 @@ import { WebServer } from '../src/web/server.js';
 
 const PORT = 3174;
 const BASE_URL = `http://localhost:${PORT}`;
+const IME_PUNCTUATION = '，。！？；：“”、《》、（）';
 
 describe('terminal Ctrl+C smart copy', () => {
   let server: WebServer;
@@ -102,6 +103,59 @@ describe('terminal Ctrl+C smart copy', () => {
     }));
   }
 
+  async function captureImeInput(targetPage: Page) {
+    await targetPage.waitForFunction(() => (window as any).app?.terminal, null, { timeout: 30000 });
+    await targetPage.evaluate(() => {
+      const term = (window as any).app.terminal;
+      (window as any).__data = [];
+      if (!(window as any).__dataHooked) {
+        term.onData((d: string) => (window as any).__data.push(d));
+        (window as any).__dataHooked = true;
+      }
+      (document.querySelector('.xterm-helper-textarea') as HTMLElement).focus();
+    });
+
+    const cdp = await targetPage.context().newCDPSession(targetPage);
+    await cdp.send('Input.imeSetComposition', { text: '中文', selectionStart: 2, selectionEnd: 2 });
+    await cdp.send('Input.insertText', { text: '中文' });
+    await targetPage.waitForFunction(() => (window as any).__data.join('') === '中文', null, { polling: 10 });
+
+    let expected = '中文';
+    for (const punctuation of Array.from(IME_PUNCTUATION)) {
+      // Keep keydown -> DOM mutation -> input in one browser task, as a
+      // native key default action does. Separate CDP calls can let xterm's
+      // zero-delay textarea diff run before Input.insertText reaches the page.
+      await targetPage.evaluate((text) => {
+        const textarea = document.querySelector('.xterm-helper-textarea') as HTMLTextAreaElement;
+        const down = new KeyboardEvent('keydown', {
+          key: 'Process',
+          code: 'Unidentified',
+          bubbles: true,
+          cancelable: true,
+          composed: true,
+        });
+        Object.defineProperties(down, { keyCode: { value: 229 }, which: { value: 229 } });
+        textarea.dispatchEvent(down);
+        if (!document.execCommand('insertText', false, text)) throw new Error('browser rejected insertText');
+        const up = new KeyboardEvent('keyup', {
+          key: 'Process',
+          code: 'Unidentified',
+          bubbles: true,
+          cancelable: true,
+          composed: true,
+        });
+        Object.defineProperties(up, { keyCode: { value: 229 }, which: { value: 229 } });
+        textarea.dispatchEvent(up);
+      }, punctuation);
+      expected += punctuation;
+      await targetPage.waitForFunction((text) => (window as any).__data.join('') === text, expected, {
+        polling: 10,
+      });
+    }
+
+    return targetPage.evaluate(() => (window as any).__data as string[]);
+  }
+
   it('copies the selection and sends nothing to the PTY', async () => {
     await setup('COPY-CASE-SELECTED', true);
     await page.keyboard.press('Control+c');
@@ -163,4 +217,20 @@ describe('terminal Ctrl+C smart copy', () => {
     expect(res.data.join('')).toContain('SENTINEL'); // pasted text, not ^V
     expect(res.data.join('')).not.toContain('\x16');
   });
+
+  it('forwards full-width punctuation after a Chinese IME composition', async () => {
+    await setup('IME-PUNCTUATION', false);
+    const desktopChunks = await captureImeInput(page);
+    expect(desktopChunks.join('')).toBe('中文' + IME_PUNCTUATION);
+
+    const touchContext = await browser.newContext({ hasTouch: true });
+    try {
+      const touchPage = await touchContext.newPage();
+      await touchPage.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
+      const touchChunks = await captureImeInput(touchPage);
+      expect(touchChunks.join('')).toBe('中文' + IME_PUNCTUATION);
+    } finally {
+      await touchContext.close();
+    }
+  });
 });

test/terminal-flush-budget.test.ts

@@ -89,7 +89,7 @@ describe('terminal flush budget', () => {
     expect(app.pendingWrites.join('')).toHaveLength(32 * 1024);
   });
 
-  it('waits for xterm to process small buffer replays before completing buffer load', async () => {
+  it('releases the live-output gate but waits for xterm to parse a small replay', async () => {
     const { app, writes } = loadTerminalUiHarness('codex');
     let writeDone: (() => void) | undefined;
     let resolved = false;
@@ -109,13 +109,90 @@ describe('terminal flush budget', () => {
     expect(writes).toEqual(['fresh tmux pane frame']);
     expect(writeDone).toBeTypeOf('function');
     expect(resolved).toBe(false);
-    expect(finishBufferLoad).not.toHaveBeenCalled();
+    expect(finishBufferLoad).toHaveBeenCalledOnce();
 
     writeDone?.();
     await promise;
 
     expect(resolved).toBe(true);
-    expect(finishBufferLoad).toHaveBeenCalledOnce();
+  });
+
+  it('paces a large enqueue and releases live output before the parse marker completes', async () => {
+    const { app, writes } = loadTerminalUiHarness('shell');
+    const scheduled: Array<() => void> = [];
+    let parseDone: (() => void) | undefined;
+    let resolved = false;
+    let result: { parsedAt: number; bufferLength: number; completed: boolean } | undefined;
+    app._safeYield = (callback: () => void) => scheduled.push(callback);
+    app.isTerminalAtBottom = () => true;
+    app.terminal.buffer = { active: { length: 37 } };
+    app.terminal.write = (data: string, callback?: () => void) => {
+      writes.push(data);
+      if (callback) parseDone = callback;
+    };
+
+    const promise = app.chunkedTerminalWrite('x'.repeat(3 * 32 * 1024)).then((value: typeof result) => {
+      result = value;
+      resolved = true;
+    });
+    expect(writes).toEqual([]);
+    expect(scheduled).toHaveLength(1);
+
+    scheduled.shift()?.();
+    expect(writes.map((write) => write.length)).toEqual([32 * 1024]);
+    expect(scheduled).toHaveLength(1);
+
+    scheduled.shift()?.();
+    expect(writes.map((write) => write.length)).toEqual([32 * 1024, 32 * 1024]);
+    expect(resolved).toBe(false);
+
+    scheduled.shift()?.();
+    expect(writes.map((write) => write.length)).toEqual([32 * 1024, 32 * 1024, 32 * 1024, 0]);
+    expect(app._isLoadingBuffer).toBe(false);
+    expect(resolved).toBe(false);
+
+    app.batchTerminalWrite('new output after snapshot');
+    expect(app._loadBufferQueue).toBe(null);
+    expect(app.pendingWrites).toEqual(['new output after snapshot']);
+
+    parseDone?.();
+    app.terminal.buffer.active.length = 42;
+    await promise;
+    expect(resolved).toBe(true);
+    expect(result?.bufferLength).toBe(37);
+    expect(result?.completed).toBe(true);
+  });
+
+  it('marks a parse callback stale when a newer replay supersedes it', async () => {
+    const { app } = loadTerminalUiHarness('shell');
+    let parseDone: (() => void) | undefined;
+    app.terminal.write = (_data: string, callback?: () => void) => {
+      parseDone = callback;
+    };
+
+    const firstReplay = app.chunkedTerminalWrite('old snapshot');
+    app._chunkedWriteGen += 1;
+    parseDone?.();
+
+    await expect(firstReplay).resolves.toMatchObject({ completed: false });
+  });
+
+  it('scans xterm rows from buffer.length instead of double-counting baseY', () => {
+    const { app } = loadTerminalUiHarness('shell');
+    const getLine = vi.fn((index: number) =>
+      index === 99 || index === 77 ? { translateToString: () => 'content' } : undefined
+    );
+    app.terminal = {
+      rows: 24,
+      buffer: { active: { baseY: 76, length: 100, getLine } },
+      scrollToBottom: vi.fn(),
+      scrollToLine: vi.fn(),
+    };
+
+    app.scrollToLastNonEmptyLine();
+
+    expect(getLine.mock.calls[0]?.[0]).toBe(99);
+    expect(app.terminal.scrollToLine).toHaveBeenCalledWith(77);
   });
 
   it('keeps stale buffer load owners from finishing a newer load', () => {

test/terminal-touch-tap.test.ts

@@ -140,7 +140,7 @@ describe('terminal touch tap mouse guard', () => {
   it('routes a readback row to the TUI while keeping the prompt row as keyboard input', () => {
     const { app } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'codex' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'codex', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(
       ['Agent readback mentions › inline', '  tap to collapse', '', '', '› ask', 'gpt-5 · Context 80% left'],
       4
@@ -155,7 +155,7 @@ describe('terminal touch tap mouse guard', () => {
   it('classifies Claude background-agent status as content rather than keyboard input', () => {
     const { app } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude', cliVersion: '2.1.220' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliVersion: '2.1.220', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(
       ['', '', '', '• Working (1m 50s • esc to ', 'interrupt) · 1 background teammate', ''],
       4,
@@ -168,7 +168,7 @@ describe('terminal touch tap mouse guard', () => {
   it('keeps the live cursor focusable when Claude temporarily omits its prompt glyph', () => {
     const { app } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(['Prior response', '', 'ready for input', '', 'status footer', ''], 2);
 
     expect(app._classifyMobileTerminalTap(9, 33)).toBe('input');
@@ -178,7 +178,7 @@ describe('terminal touch tap mouse guard', () => {
   it('treats a highlighted numbered choice as TUI content, not an input prompt', () => {
     const { app } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(['Would you like to proceed?', '', '❯ 1. Yes', '  2. No', '', ''], 2);
 
     expect(app._classifyMobileTerminalTap(9, 33)).toBe('content');
@@ -193,7 +193,7 @@ describe('terminal touch tap mouse guard', () => {
     // commits an answer) as the only thing a phone could do.
     const { app, setActiveElement } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(
       ['Do you want to proceed?', '', '❯ 1. Yes', '  2. No, tell Claude what to do', '', ''],
       2
@@ -219,7 +219,7 @@ describe('terminal touch tap mouse guard', () => {
   it('collapses TUI readback content without opening or retaining the keyboard', () => {
     const { app, setActiveElement } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'codex' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'codex', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(
       ['Agent readback', '  tap to collapse', '', '', '› ask', 'gpt-5 · Context 80% left'],
       4
@@ -252,7 +252,7 @@ describe('terminal touch tap mouse guard', () => {
   it('closes the keyboard on a second tap of INERT transcript content', () => {
     const { app, setActiveElement } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app.terminal = createTerminalGrid(['transcript line', '', '', '', '❯ ', ''], 4);
     app._sendInputAsync = vi.fn();
 
@@ -328,7 +328,7 @@ describe('terminal touch tap mouse guard', () => {
     const { app } = loadTerminalUiHarness();
     const sent: Array<{ id: string; data: string }> = [];
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app._sendInputAsync = (id: string, data: string) => sent.push({ id, data });
     app.terminal = {
       cols: 80,
@@ -339,7 +339,7 @@ describe('terminal touch tap mouse guard', () => {
       _core: { _renderService: { dimensions: { css: { cell: { width: 8, height: 16 } } } } },
     };
 
-    expect(app._sessionUsesServerMouseStrip()).toBe(true);
+    expect(app._shouldReportMouseToCli()).toBe(true);
     // touch at x=10+8*20+1, y=20+16*5+1 → col 21, row 6 (1-based)
     app._sendSyntheticSgrTap(171, 101);
 
@@ -366,19 +366,60 @@ describe('terminal touch tap mouse guard', () => {
     expect(sent).toEqual(['\x1b[<0;1;24M\x1b[<0;1;24m']);
   });
 
-  it('does not treat shell sessions as server-mouse-strip mode', () => {
+  it('never hand-reports for a shell session, even with tracking somehow set', () => {
+    // Shell DECSETs are NOT stripped (narrow strip), so xterm's own encoder owns
+    // the mouse there and a second, hand-encoded report would double-report.
     const { app } = loadTerminalUiHarness();
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'shell' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'shell', cliMouseTracking: true }]]);
 
-    expect(app._sessionUsesServerMouseStrip()).toBe(false);
+    expect(app._shouldReportMouseToCli()).toBe(false);
+  });
+
+  it('hand-reports only while the CLI actually has mouse tracking on', () => {
+    // The server strips the DECSETs, so xterm can never see them and the browser
+    // reported EVERY click. A claude pane sitting at its composer, or one that
+    // fell back to a shell prompt, was receiving mouse reports it never asked
+    // for; a shell prints those as literal text and they garble the next line.
+    const { app } = loadTerminalUiHarness();
+    app.activeSessionId = 'sess-1';
+
+    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    expect(app._shouldReportMouseToCli()).toBe(false);
+
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: false }]]);
+    expect(app._shouldReportMouseToCli()).toBe(false);
+
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
+    expect(app._shouldReportMouseToCli()).toBe(true);
+  });
+
+  it('desktop click: sends nothing while the CLI has no mouse mode on', () => {
+    const { app } = loadTerminalUiHarness();
+    const sent: string[] = [];
+    app.activeSessionId = 'sess-1';
+    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app._sendInputAsync = (_id: string, data: string) => sent.push(data);
+    app.terminal = createTerminalGrid(['some output', '', '\u276f '], 2);
+    app._linkHovered = false;
+
+    app._handleDesktopTerminalClick({
+      isTrusted: true,
+      button: 0,
+      detail: 1,
+      clientX: 40,
+      clientY: 10,
+      target: { closest: (sel: string) => (sel === '.xterm-screen' ? {} : null) },
+    });
+
+    expect(sent).toEqual([]);
   });
 
   it('desktop click: encodes SGR press+release for a plain left-click in strip mode', () => {
     const { app } = loadTerminalUiHarness();
     const sent: Array<{ id: string; data: string }> = [];
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app._sendInputAsync = (id: string, data: string) => sent.push({ id, data });
     app.terminal = {
       cols: 80,
@@ -453,7 +494,7 @@ describe('terminal touch tap mouse guard', () => {
     const { app } = loadTerminalUiHarness();
     const sent: string[] = [];
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app._sendInputAsync = (_id: string, data: string) => sent.push(data);
     app.terminal = {
       cols: 80,
@@ -487,7 +528,7 @@ describe('terminal touch tap mouse guard', () => {
     const { app, setNow } = loadTerminalUiHarness();
     const sent: string[] = [];
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app._sendInputAsync = (_id: string, data: string) => sent.push(data);
     app.terminal = {
       cols: 80,
@@ -771,7 +812,7 @@ describe('terminal link tap', () => {
     const { app, windowRef } = harness;
     const sent: string[] = [];
     app.activeSessionId = 'sess-1';
-    app.sessions = new Map([['sess-1', { mode: 'claude' }]]);
+    app.sessions = new Map([['sess-1', { mode: 'claude', cliMouseTracking: true }]]);
     app._sendInputAsync = (_id: string, data: string) => sent.push(data);
     app.terminal = createTerminalGrid(lines, cursorY);
     app.terminal.registerLinkProvider = vi.fn();
@@ -802,7 +843,7 @@ describe('terminal link tap', () => {
     const line = 'see https://example.com/x for more';
     const { app, sent } = linkHarness([line, '', '❯ ']);
 
-    expect(app._sessionUsesServerMouseStrip()).toBe(true);
+    expect(app._shouldReportMouseToCli()).toBe(true);
     app._handleMobileTerminalTap(at(line.indexOf('https')), false, 'content');
 
     expect(sent).toEqual([]);

test/tmux-manager.test.ts

@@ -675,6 +675,7 @@ describe('TmuxManager (unit)', () => {
           sessionId: 'abc12345-1234-5678-90ab-cdef12345678',
           workingDir: '/mnt/gdrive/project with spaces',
           mode: 'shell',
+          historyLimit: 250_000,
         });
 
         expect(session.workingDir).toBe('/mnt/gdrive/project with spaces');
@@ -683,7 +684,9 @@ describe('TmuxManager (unit)', () => {
         const newSessionCall = mockedExecSync.mock.calls.find(
           ([cmd]) => typeof cmd === 'string' && cmd.includes(' new-session ')
         );
-        expect(newSessionCall?.[0]).toBe(`tmux -L 'codeman' new-session -ds "codeman-abc12345" -c /tmp`);
+        expect(newSessionCall?.[0]).toBe(
+          `tmux -L 'codeman' set-option -g history-limit 250000 \\; new-session -ds "codeman-abc12345" -c /tmp \\; set-option -t "codeman-abc12345" history-limit 250000`
+        );
         expect(newSessionCall?.[1]).toEqual(expect.objectContaining({ cwd: '/tmp' }));
 
         const respawnCall = mockedExecSync.mock.calls.find(
@@ -696,6 +699,59 @@ describe('TmuxManager (unit)', () => {
       }
     });
 
+    it('changes the global history default on tmux versions that cannot resize panes', async () => {
+      const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+      const nonTestManager = new NonTestTmuxManager();
+
+      try {
+        await nonTestManager.setHistoryLimit(200_000);
+        const historyCall = mockedExec.mock.calls.find(
+          ([cmd]) => typeof cmd === 'string' && cmd.includes(' history-limit ')
+        );
+        expect(historyCall?.[0]).toBe(`tmux -L 'codeman' set-option -g history-limit 200000`);
+        expect(historyCall?.[0]).not.toContain(' -t ');
+      } finally {
+        nonTestManager.destroy();
+      }
+    });
+
+    it('targets only the new and tracked sessions on tmux 3.7+', async () => {
+      mockedExecSync.mockImplementation((cmd: string) => {
+        if (typeof cmd === 'string' && cmd.endsWith(' -V')) return 'tmux 3.7b\n';
+        if (typeof cmd === 'string' && cmd.includes('which tmux')) return '/usr/bin/tmux\n';
+        if (typeof cmd === 'string' && cmd.includes('display-message') && cmd.includes('#{pane_pid}')) return '4242\n';
+        return '';
+      });
+      const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+      const nonTestManager = new NonTestTmuxManager();
+
+      try {
+        await nonTestManager.createSession({
+          sessionId: 'def67890-1234-5678-90ab-cdef12345678',
+          workingDir: '/project',
+          mode: 'shell',
+          historyLimit: 250_000,
+        });
+        const newSessionCall = mockedExecSync.mock.calls.find(
+          ([cmd]) => typeof cmd === 'string' && cmd.includes(' new-session ')
+        );
+        expect(newSessionCall?.[0]).toBe(
+          `tmux -L 'codeman' new-session -ds "codeman-def67890" -c /tmp \\; set-option -t "codeman-def67890" history-limit 250000`
+        );
+        expect(newSessionCall?.[0]).not.toContain('set-option -g');
+
+        mockedExec.mockClear();
+        await nonTestManager.setHistoryLimit(200_000);
+        const historyCall = mockedExec.mock.calls.find(
+          ([cmd]) => typeof cmd === 'string' && cmd.includes(' history-limit ')
+        );
+        expect(historyCall?.[0]).toBe(`tmux -L 'codeman' set-option -t 'codeman-def67890' history-limit 200000`);
+        expect(historyCall?.[0]).not.toContain('set-option -g');
+      } finally {
+        nonTestManager.destroy();
+      }
+    });
+
     it('respawns existing panes from /tmp and cd-bounces into the requested workspace', async () => {
       const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
       const nonTestManager = new NonTestTmuxManager();

test/tui/tui-ansi.test.ts

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Unit tests for the TUI's SGR-aware preview helpers
+ * (toDisplayLines / clipStyledLine / visibleWidth / padDisplay / stripStyles).
+ *
+ * The invariants under test are the ones a preview pane fails visibly on: color
+ * survives, cursor steering does not, a carriage-return repaint collapses to
+ * one line, and no clip ever cuts a code point, a wide character or an escape
+ * sequence in half.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  clipStyledLine,
+  dropSeveredEscape,
+  padDisplay,
+  stripStyles,
+  toDisplayLines,
+  visibleWidth,
+  charWidth,
+  foldPreviewGlyphs,
+} from '../../src/tui/tui-ansi.js';
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+describe('toDisplayLines', () => {
+  it('splits like String.split, trailing newline included', () => {
+    expect(toDisplayLines('a\nb')).toEqual(['a', 'b']);
+    expect(toDisplayLines('a\n')).toEqual(['a', '']);
+    expect(toDisplayLines('')).toEqual(['']);
+  });
+
+  it('preserves SGR and closes an open style at end of line', () => {
+    expect(toDisplayLines(`${RED}red${RESET} done`)).toEqual([`${RED}red${RESET} done`]);
+    expect(toDisplayLines(`${BOLD}bold`)).toEqual([`${BOLD}bold${RESET}`]);
+  });
+
+  it('accumulates SGR state across a line', () => {
+    expect(toDisplayLines(`${BOLD}a${RED}b`)).toEqual([`${BOLD}a${RESET}${BOLD}${RED}b${RESET}`]);
+  });
+
+  it('strips OSC sequences (BEL and ST terminated)', () => {
+    expect(toDisplayLines('\x1b]0;window title\x07text')).toEqual(['text']);
+    expect(toDisplayLines('\x1b]0;window title\x1b\\text')).toEqual(['text']);
+  });
+
+  it('strips DECSET/DECRST, relative cursor movement and charset selection', () => {
+    expect(toDisplayLines('\x1b[?25lvisible\x1b[?25h')).toEqual(['visible']);
+    expect(toDisplayLines('a\x1b[5Cb')).toEqual(['ab']);
+    expect(toDisplayLines('\x1b(0lqk\x1b(B')).toEqual(['lqk']);
+    expect(toDisplayLines('\x1b=app\x1b>')).toEqual(['app']);
+  });
+
+  it('splits a row-addressed repaint into lines, which is how an Ink TUI paints', () => {
+    // Claude Code emits almost no newlines: without this the whole screen is
+    // one line and nothing in the preview is readable.
+    expect(toDisplayLines('\x1b[1;1Hfirst\x1b[2;1Hsecond\x1b[3;1Hthird')).toEqual(['first', 'second', 'third']);
+    // A jump inside a row is a write position, not a new line.
+    expect(toDisplayLines('\x1b[1;1Hab\x1b[1;5Hcd')).toEqual(['ab  cd']);
+    expect(toDisplayLines('\x1b[1;1Habcdef\x1b[1;2HXY')).toEqual(['aXYdef']);
+    expect(toDisplayLines('a\x1b[3;1fb')).toEqual(['a', 'b']);
+  });
+
+  it('starts a new frame at a cursor HOME, instead of stacking repaints', () => {
+    // ⚠️ A home is a full-screen app announcing a repaint from the top, and
+    // everything on screen is about to be overwritten in place. This replay is
+    // line-based and cannot overwrite, so starting over is the faithful
+    // equivalent. Without it every repaint was APPENDED: a real claude pane's
+    // 198KB tail replayed as FIFTY stacked copies of the same frame, and the
+    // preview showed the last N lines, which on a tall terminal spanned two of
+    // them — the overview appeared to show the session twice.
+    expect(toDisplayLines('old frame\x1b[1;1Hnew frame')).toEqual(['new frame']);
+    // Both parameters default to 1, so a bare CUP is a home too.
+    expect(toDisplayLines('a\x1b[Hb')).toEqual(['b']);
+    // Only row 1 column 1. Any other address is a write position within the
+    // frame being painted, and resetting on those would erase live content.
+    expect(toDisplayLines('keep\x1b[2;1Hnext')).toEqual(['keep', 'next']);
+    expect(toDisplayLines('keep\x1b[1;3Hxx')).toEqual(['kexx']);
+  });
+
+  it('refuses to allocate a line for a column no terminal has', () => {
+    const lines = toDisplayLines('\x1b[1;99999Hx');
+    expect(lines).toHaveLength(1);
+    expect(visibleWidth(lines[0])).toBeLessThanOrEqual(1001);
+  });
+
+  it('strips C1 controls and their sequences', () => {
+    expect(toDisplayLines('a\x9b31mb')).toEqual(['ab']);
+    expect(toDisplayLines('a\x9d0;title\x9cb')).toEqual(['ab']);
+  });
+
+  it('drops control characters but keeps tabs as spaces', () => {
+    expect(toDisplayLines('a\x07b\x00c')).toEqual(['abc']);
+    expect(toDisplayLines('a\tb')).toEqual(['a       b']);
+    expect(toDisplayLines('\tx')).toEqual(['        x']);
+  });
+
+  it('treats a bare \\r as a return to column zero (spinner repaint)', () => {
+    expect(toDisplayLines('abcdef\rXY')).toEqual(['XYcdef']);
+    expect(toDisplayLines('long line here\rshort')).toEqual(['shortline here']);
+    expect(toDisplayLines('\rWorking 1%\rWorking 99%')).toEqual(['Working 99%']);
+  });
+
+  it('keeps \\r\\n as a plain newline', () => {
+    expect(toDisplayLines('a\r\nb')).toEqual(['a', 'b']);
+  });
+
+  it('carries the overwriting text style, not the overwritten one', () => {
+    expect(toDisplayLines(`${RED}aaa\r${RESET}b`)).toEqual([`b${RED}aa${RESET}`]);
+  });
+
+  it('keeps whole code points and attaches combining marks to their base', () => {
+    expect(toDisplayLines('a\u{1f600}b')).toEqual(['a\u{1f600}b']);
+    expect(toDisplayLines('éx')).toEqual(['éx']);
+  });
+
+  it('does not throw on truncated or malformed escapes', () => {
+    expect(toDisplayLines('abc\x1b')).toEqual(['abc']);
+    expect(toDisplayLines('abc\x1b[')).toEqual(['abc']);
+    expect(toDisplayLines('abc\x1b[31')).toEqual(['abc']);
+    expect(toDisplayLines('\x1b]0;no terminator')).toEqual(['']);
+    expect(() => toDisplayLines('\x1b\x1b\x1b[[[m')).not.toThrow();
+  });
+});
+
+describe('dropSeveredEscape', () => {
+  it('drops the remains of a sequence a byte-sliced tail starts inside', () => {
+    expect(dropSeveredEscape(';1Hstill here')).toBe('still here');
+    expect(dropSeveredEscape('12;3Htext')).toBe('text');
+    expect(dropSeveredEscape('31mred')).toBe('red');
+  });
+
+  it('leaves ordinary text alone', () => {
+    expect(dropSeveredEscape('hello world')).toBe('hello world');
+    expect(dropSeveredEscape('\x1b[31mred')).toBe('\x1b[31mred');
+    expect(dropSeveredEscape('')).toBe('');
+  });
+});
+
+describe('visibleWidth', () => {
+  it('ignores escape sequences', () => {
+    expect(visibleWidth(`${RED}abc${RESET}`)).toBe(3);
+    expect(visibleWidth('\x1b]0;title\x07abc')).toBe(3);
+  });
+
+  it('counts East Asian wide characters as two columns', () => {
+    expect(visibleWidth('中文')).toBe(4);
+    expect(visibleWidth('a中b')).toBe(4);
+    expect(visibleWidth('ｆｕｌｌ')).toBe(8);
+    expect(visibleWidth('\u{1f600}')).toBe(2);
+  });
+
+  it('counts combining marks and zero-width joiners as nothing', () => {
+    expect(visibleWidth('é')).toBe(1);
+    expect(visibleWidth('a‍b')).toBe(2);
+    expect(visibleWidth('')).toBe(0);
+  });
+
+  it('agrees with charWidth on the boundaries', () => {
+    expect(charWidth(0x41)).toBe(1);
+    expect(charWidth(0x4e00)).toBe(2);
+    expect(charWidth(0x0301)).toBe(0);
+    expect(charWidth(0x07)).toBe(0);
+  });
+});
+
+describe('clipStyledLine', () => {
+  it('clips plain text by display width', () => {
+    expect(clipStyledLine('abcdef', 3)).toBe('abc');
+    expect(clipStyledLine('abc', 10)).toBe('abc');
+    expect(clipStyledLine('abc', 0)).toBe('');
+    expect(clipStyledLine('abc', -4)).toBe('');
+  });
+
+  it('keeps the SGR state active at the clip point and closes it', () => {
+    expect(clipStyledLine(`${RED}abcdef${RESET}`, 3)).toBe(`${RED}abc${RESET}`);
+    expect(clipStyledLine(`${BOLD}${RED}abcdef`, 2)).toBe(`${BOLD}${RED}ab${RESET}`);
+  });
+
+  it('adds no reset when the kept part already reset', () => {
+    expect(clipStyledLine(`${RED}ab${RESET}cdef`, 4)).toBe(`${RED}ab${RESET}cd`);
+  });
+
+  it('never emits half of a double-width character', () => {
+    expect(clipStyledLine('中文abc', 3)).toBe('中');
+    expect(clipStyledLine('中文', 4)).toBe('中文');
+    expect(visibleWidth(clipStyledLine('中文abc', 3))).toBe(2);
+  });
+
+  it('never splits a surrogate pair or a combining sequence', () => {
+    expect(clipStyledLine('\u{1f600}x', 2)).toBe('\u{1f600}');
+    expect(clipStyledLine('\u{1f600}x', 1)).toBe('');
+    expect(clipStyledLine('éx', 1)).toBe('é');
+  });
+
+  it('drops escape sequences that sit past the clip point', () => {
+    expect(clipStyledLine(`ab${RED}cd`, 2)).toBe('ab');
+  });
+});
+
+describe('padDisplay', () => {
+  it('pads short text and clips long text', () => {
+    expect(padDisplay('ab', 5)).toBe('ab   ');
+    expect(padDisplay('abcdef', 3)).toBe('abc');
+    expect(padDisplay('abc', 3)).toBe('abc');
+    expect(padDisplay('abc', 0)).toBe('');
+  });
+
+  it('pads to the exact display width around a wide-character boundary', () => {
+    expect(visibleWidth(padDisplay('中文', 3))).toBe(3);
+    expect(padDisplay('中文', 3)).toBe('中 ');
+    expect(visibleWidth(padDisplay(`${RED}中${RESET}x`, 6))).toBe(6);
+  });
+});
+
+describe('stripStyles', () => {
+  it('removes every escape sequence and control character', () => {
+    expect(stripStyles(`${RED}red${RESET}`)).toBe('red');
+    expect(stripStyles('\x1b]0;t\x07a\x1b[?25lb')).toBe('ab');
+    expect(stripStyles('a\u{1f600}中')).toBe('a\u{1f600}中');
+  });
+});
+
+describe('foldPreviewGlyphs', () => {
+  it("turns claude's prompt and mode markers into the arrows they look like", () => {
+    // Exactly what a beta tester photographed as empty boxes.
+    expect(foldPreviewGlyphs('\u276F Try "how does report_agent.py work?"')).toBe(
+      '> Try "how does report_agent.py work?"'
+    );
+    expect(foldPreviewGlyphs('  \u23F5\u23F5 bypass permissions on')).toBe('  >> bypass permissions on');
+  });
+
+  it('leaves the glyphs that plain fonts DO render', () => {
+    // The same terminal drew all of these correctly, so folding them would be a
+    // downgrade for everyone to fix a problem nobody has.
+    const kept = '\u00B7 \u2500 \u2502 \u25B6 \u25CB \u2714 \u2192';
+    expect(foldPreviewGlyphs(kept)).toBe(kept);
+  });
+
+  it('leaves ordinary text and box drawing exactly alone', () => {
+    const line = '  1 tui-demo-shell shell   \u25CB 4m\u2502';
+    expect(foldPreviewGlyphs(line)).toBe(line);
+    expect(foldPreviewGlyphs('')).toBe('');
+  });
+
+  it('preserves length, so preview column arithmetic is unaffected', () => {
+    const line = '\u276F hello \u23F5\u23F5 world';
+    expect(foldPreviewGlyphs(line)).toHaveLength([...line].length);
+  });
+});

test/tui/tui-app.test.ts

@@ -0,0 +1,786 @@
+/**
+ * @fileoverview Unit tests for the decisions `codeman tui` makes, without a
+ * terminal.
+ *
+ * Everything the app does that can be stated as a function of its inputs is
+ * exported from `tui-app.ts` for exactly this reason: the attach handoff (which
+ * changes shape inside tmux), the typed kill confirmation, the footer's honest
+ * key inventory, the repaint test and the row building for degraded mode. The
+ * full-screen loop itself is covered end-to-end under node-pty in
+ * `tui-e2e.test.ts`.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  applyLiveMetrics,
+  applyMuxNames,
+  buildAttachBanner,
+  buildListLines,
+  confirmKillStep,
+  detachChord,
+  heldCtrlAlias,
+  ONE_KEY_DETACH,
+  buildAttachTabs,
+  nextSessionName,
+  footerKeysFor,
+  formatPrefixKey,
+  helpKeysFor,
+  isSelfSession,
+  planAttach,
+  planResume,
+  previewIntervalMs,
+  previewNoteFor,
+  resyncDelayMs,
+  sameFrame,
+  samePreview,
+  shouldAnimate,
+  shouldFetchPreview,
+  tmuxRowsToSessions,
+  tmuxSocketFromEnv,
+} from '../../src/tui/tui-app.js';
+import { createTuiModel, stateSince } from '../../src/tui/tui-model.js';
+import { glyphsFor } from '../../src/tui/tui-render.js';
+import type { TuiLiveSessionMetrics, TuiTmuxSession } from '../../src/tui/tui-client.js';
+import type { TuiConfirmState, TuiRow, TuiSessionRow } from '../../src/tui/tui-types.js';
+
+const GLYPHS = glyphsFor('unicode');
+
+function tmuxSession(overrides: Partial<TuiTmuxSession> & { muxName: string }): TuiTmuxSession {
+  return {
+    sessionIdPrefix: overrides.muxName.replace(/^codeman-/, ''),
+    attached: false,
+    ...overrides,
+  };
+}
+
+function row(state: TuiRow['state'], sessionId = 'abcdef0123'): TuiRow {
+  const session: TuiSessionRow = { sessionId, sources: ['live'] };
+  return { session, state, group: state === 'working' ? 'working' : 'idle', since: 0 };
+}
+
+describe('tmuxSocketFromEnv', () => {
+  it('reads the socket name out of a $TMUX value', () => {
+    expect(tmuxSocketFromEnv('/tmp/tmux-1000/codeman,31415,0')).toBe('codeman');
+    expect(tmuxSocketFromEnv('/tmp/tmux-1000/codeman-beta,7,2')).toBe('codeman-beta');
+    // A bare default socket is still the name a `-L` comparison needs.
+    expect(tmuxSocketFromEnv('/tmp/tmux-1000/default,7,2')).toBe('default');
+  });
+
+  it('reports "not inside tmux" for an absent or empty value', () => {
+    expect(tmuxSocketFromEnv(undefined)).toBeNull();
+    expect(tmuxSocketFromEnv('')).toBeNull();
+    expect(tmuxSocketFromEnv('   ')).toBeNull();
+  });
+});
+
+describe('planAttach', () => {
+  it('attaches with the instance socket when the terminal is not inside tmux', () => {
+    const plan = planAttach('codeman-abcdef01', { socket: 'codeman' });
+    expect(plan).toEqual({
+      kind: 'attach',
+      file: 'tmux',
+      args: ['-L', 'codeman', 'attach-session', '-t', 'codeman-abcdef01'],
+    });
+  });
+
+  it('switches the current client when already inside tmux on the same socket', () => {
+    const plan = planAttach('codeman-abcdef01', { socket: 'codeman', tmux: '/tmp/tmux-1000/codeman,31415,0' });
+    expect(plan).toEqual({
+      kind: 'switch',
+      file: 'tmux',
+      args: ['-L', 'codeman', 'switch-client', '-t', 'codeman-abcdef01'],
+    });
+  });
+
+  it('refuses to nest when the surrounding tmux is a different server', () => {
+    const plan = planAttach('codeman-abcdef01', { socket: 'codeman', tmux: '/tmp/tmux-1000/default,31415,0' });
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind !== 'refuse') throw new Error('expected a refusal');
+    expect(plan.reason).toBe('nested-foreign-socket');
+    expect(plan.message).toContain('default');
+    expect(plan.message).toContain('codeman');
+  });
+
+  it('refuses a row with no tmux session behind it', () => {
+    for (const name of [undefined, '', '   ']) {
+      const plan = planAttach(name, { socket: 'codeman' });
+      expect(plan.kind).toBe('refuse');
+      if (plan.kind !== 'refuse') throw new Error('expected a refusal');
+      expect(plan.reason).toBe('no-mux-name');
+    }
+  });
+
+  it('never builds a shell string: every field is its own argv entry', () => {
+    const plan = planAttach('codeman-abcdef01', { socket: 'codeman' });
+    if (plan.kind !== 'attach') throw new Error('expected an attach');
+    expect(plan.args.some((arg) => arg.includes(' '))).toBe(false);
+  });
+});
+
+describe('isSelfSession', () => {
+  const id = 'abcdef01-2345-6789-abcd-ef0123456789';
+
+  it('recognizes the session the TUI runs in, however the id was truncated', () => {
+    expect(isSelfSession(id, { CODEMAN_SESSION_ID: id })).toBe(true);
+    expect(isSelfSession(id, { CODEMAN_SESSION_ID: 'abcdef01' })).toBe(true);
+    expect(isSelfSession('abcdef01', { CODEMAN_SESSION_ID: id })).toBe(true);
+  });
+
+  it('is false for another session, and for env that identifies nothing', () => {
+    expect(isSelfSession(id, { CODEMAN_SESSION_ID: 'ffffffff' })).toBe(false);
+    expect(isSelfSession(id, {})).toBe(false);
+    expect(isSelfSession(id, { CODEMAN_SESSION_ID: 'abc' })).toBe(false);
+  });
+});
+
+describe('the kill confirmation', () => {
+  const state: TuiConfirmState = { sessionId: 'abcdef01-2345', name: 'w4-api', typed: '' };
+
+  it('kills on y, upper or lower', () => {
+    // Was: type the session's full name. The tester's verdict on that was
+    // "thats stupid, just make me type Y to confirm", and they were right —
+    // `x` then `y` is already two deliberate keystrokes on a selected row.
+    expect(confirmKillStep(state, { type: 'char', value: 'y' })).toEqual({ kind: 'confirm' });
+    expect(confirmKillStep(state, { type: 'char', value: 'Y' })).toEqual({ kind: 'confirm' });
+  });
+
+  it('cancels on every other key, rather than leaving the prompt armed', () => {
+    // A dialog that ignores unknown keys sits there consuming whatever the
+    // user types next, which for a destructive prompt is the wrong default.
+    expect(confirmKillStep(state, { type: 'char', value: 'n' })).toEqual({ kind: 'cancel' });
+    expect(confirmKillStep(state, { type: 'char', value: 'x' })).toEqual({ kind: 'cancel' });
+    expect(confirmKillStep(state, { type: 'escape' })).toEqual({ kind: 'cancel' });
+    expect(confirmKillStep(state, { type: 'ctrl', key: 'c' })).toEqual({ kind: 'cancel' });
+  });
+
+  it('does NOT kill on Enter, the key most likely to be hit by reflex', () => {
+    expect(confirmKillStep(state, { type: 'enter' })).toEqual({ kind: 'cancel' });
+  });
+});
+
+describe('footerKeysFor', () => {
+  it('advertises only the verbs this build implements', () => {
+    const keys = footerKeysFor('list', GLYPHS, { server: true }).join(' ');
+    expect(keys).toContain('attach');
+    expect(keys).toContain('1-9 switch');
+    expect(keys).toContain('n new');
+    expect(keys).toContain('p prompt');
+    expect(keys).toContain('/ search');
+    expect(keys).toContain('g digest');
+    expect(keys).toContain('x kill');
+    expect(keys).toContain('q quit');
+    // Resuming a RECENT row is still phase 3.
+    expect(keys).not.toContain('resume');
+  });
+
+  it('swaps in the answer keys while a dialog is on the selected row', () => {
+    const keys = footerKeysFor('list', GLYPHS, { server: true, approval: 'menu' }).join(' ');
+    expect(keys).toContain('y approve');
+    expect(keys).toContain('n deny');
+    expect(keys).toContain('1-9 option');
+    // `n` cannot mean two things at once, and denying is what it does here.
+    expect(keys).not.toContain('n new');
+    expect(keys).not.toContain('1-9 switch');
+  });
+
+  it('sends an idle prompt to the composer instead of offering approve/deny', () => {
+    const keys = footerKeysFor('list', GLYPHS, { server: true, approval: 'idle' }).join(' ');
+    expect(keys).toContain('p reply');
+    expect(keys).toContain('n new');
+    expect(keys).not.toContain('y approve');
+  });
+
+  it('drops the server-only verbs in degraded mode', () => {
+    const keys = footerKeysFor('list', GLYPHS, { server: false }).join(' ');
+    expect(keys).toContain('attach');
+    expect(keys).not.toContain('kill');
+    expect(keys).not.toContain('new');
+    expect(keys).not.toContain('search');
+  });
+
+  it('keeps the help overlay to the same inventory', () => {
+    const help = helpKeysFor(GLYPHS, { server: true });
+    expect(help.map(([, description]) => description)).toEqual(
+      expect.arrayContaining([
+        'attach — on a RECENT row, resume that conversation',
+        'new session',
+        'kill (y to confirm)',
+        'quit',
+      ])
+    );
+    expect(help.flat().join(' ')).toContain('search');
+    const degraded = helpKeysFor(GLYPHS, { server: false }).flat().join(' ');
+    expect(degraded).not.toContain('kill');
+    expect(degraded).not.toContain('search');
+  });
+
+  it('follows the overlay that owns the keyboard', () => {
+    expect(footerKeysFor('help', GLYPHS, { server: true })).toEqual(['esc close']);
+    expect(footerKeysFor('confirm-kill', GLYPHS, { server: true }).join(' ')).toContain('y kill');
+    expect(footerKeysFor('message', GLYPHS, { server: true })).toEqual(['esc dismiss']);
+    expect(footerKeysFor('new-session', GLYPHS, { server: true }).join(' ')).toContain('type to filter');
+    expect(footerKeysFor('prompt', GLYPHS, { server: true }).join(' ')).toContain('send');
+    expect(footerKeysFor('search', GLYPHS, { server: true }).join(' ')).toContain('open');
+    expect(footerKeysFor('digest', GLYPHS, { server: true }).join(' ')).toContain('scroll');
+  });
+});
+
+describe('the preview policy', () => {
+  const live: TuiRow = { ...row('idle', 'aaaaaaaa11'), group: 'idle' };
+  const history: TuiRow = { ...row('recent', 'bbbbbbbb22'), group: 'recent' };
+
+  it('polls a live row only while the plain list is on screen and wide', () => {
+    const base = { mode: 'list' as const, narrow: false, connection: 'connected' as const, row: live };
+    expect(shouldFetchPreview(base)).toBe(true);
+    expect(shouldFetchPreview({ ...base, mode: 'prompt' })).toBe(false);
+    expect(shouldFetchPreview({ ...base, mode: 'search' })).toBe(false);
+    expect(shouldFetchPreview({ ...base, narrow: true })).toBe(false);
+    expect(shouldFetchPreview({ ...base, connection: 'degraded' })).toBe(false);
+    expect(shouldFetchPreview({ ...base, row: history })).toBe(false);
+    expect(shouldFetchPreview({ ...base, row: null })).toBe(false);
+  });
+
+  it('explains a history row instead of polling one', () => {
+    expect(previewNoteFor(history, 'connected')).toContain('not running');
+    expect(previewNoteFor(live, 'connected')).toBeNull();
+    // The renderer already says why a degraded server has no preview.
+    expect(previewNoteFor(history, 'degraded')).toBeNull();
+    expect(previewNoteFor(null, 'connected')).toBeNull();
+  });
+
+  it('treats an unchanged tail as nothing to repaint', () => {
+    const preview = { sessionId: 'a', lines: ['one', 'two'] };
+    expect(samePreview(preview, { sessionId: 'a', lines: ['one', 'two'] })).toBe(true);
+    expect(samePreview(preview, { sessionId: 'a', lines: ['one', 'three'] })).toBe(false);
+    expect(samePreview(preview, { sessionId: 'a', lines: ['one'] })).toBe(false);
+    expect(samePreview(preview, { sessionId: 'b', lines: ['one', 'two'] })).toBe(false);
+    expect(samePreview(preview, { sessionId: 'a', lines: ['one', 'two'], error: 'boom' })).toBe(false);
+    expect(samePreview(preview, { sessionId: 'a', lines: ['one', 'two'], note: 'history' })).toBe(false);
+    expect(samePreview(null, null)).toBe(true);
+    expect(samePreview(null, preview)).toBe(false);
+  });
+});
+
+describe('the refetch and tail-read cadence', () => {
+  it('debounces a burst but paces a stream, measured from the last start', () => {
+    // Nothing has been refetched yet: pay the debounce and nothing more.
+    expect(resyncDelayMs(10_000, 0, 250, 3_000)).toBe(250);
+    // A refetch that started 2.9s ago: wait out the rest of the floor.
+    expect(resyncDelayMs(10_000, 9_900, 250, 3_000)).toBe(2_900);
+    // Past the floor: back to the debounce, never below it.
+    expect(resyncDelayMs(10_000, 6_000, 250, 3_000)).toBe(250);
+    expect(resyncDelayMs(10_000, 1_000, 250, 3_000)).toBe(250);
+  });
+
+  it('reads a printing pane every second and a quiet one every five', () => {
+    expect(previewIntervalMs(0, 1_000, 5_000)).toBe(1_000);
+    expect(previewIntervalMs(1, 1_000, 5_000)).toBe(2_000);
+    expect(previewIntervalMs(2, 1_000, 5_000)).toBe(4_000);
+    // The ceiling holds however long the pane stays quiet, and a silly counter
+    // cannot overflow the doubling into Infinity.
+    expect(previewIntervalMs(3, 1_000, 5_000)).toBe(5_000);
+    expect(previewIntervalMs(50, 1_000, 5_000)).toBe(5_000);
+    expect(previewIntervalMs(-5, 1_000, 5_000)).toBe(1_000);
+  });
+});
+
+describe('the repaint test', () => {
+  const key = { revision: 3, cols: 100, rows: 30, tick: 0 };
+
+  it('repaints on a first frame, a state change, a resize and a tick', () => {
+    expect(sameFrame(null, key)).toBe(false);
+    expect(sameFrame(key, { ...key, revision: 4 })).toBe(false);
+    expect(sameFrame(key, { ...key, cols: 80 })).toBe(false);
+    expect(sameFrame(key, { ...key, rows: 24 })).toBe(false);
+    expect(sameFrame(key, { ...key, tick: 1 })).toBe(false);
+  });
+
+  it('writes nothing when nothing changed', () => {
+    expect(sameFrame(key, { ...key })).toBe(true);
+  });
+
+  it('only animates while a WORKING row is on screen', () => {
+    expect(shouldAnimate([row('idle'), row('recent')])).toBe(false);
+    expect(shouldAnimate([row('idle'), row('working', 'bbbb1111')])).toBe(true);
+    expect(shouldAnimate([])).toBe(false);
+  });
+});
+
+describe('degraded-mode rows', () => {
+  const sessions: TuiTmuxSession[] = [
+    tmuxSession({ muxName: 'codeman-abcdef01', sessionId: 'abcdef01-2345', name: 'w4-api', workingDir: '/dev/api' }),
+    tmuxSession({ muxName: 'codeman-99887766', createdAt: 1_000_000 }),
+  ];
+
+  it('keeps the tmux name and falls back to it as the row key', () => {
+    const rows = tmuxRowsToSessions(sessions);
+    expect(rows[0]).toMatchObject({
+      sessionId: 'abcdef01-2345',
+      muxName: 'codeman-abcdef01',
+      name: 'w4-api',
+      workingDir: '/dev/api',
+    });
+    // No state.json entry: the mux name is the only identity there is.
+    expect(rows[1].sessionId).toBe('codeman-99887766');
+    expect(rows[1].muxName).toBe('codeman-99887766');
+  });
+
+  it('classifies a running pane as IDLE rather than history', () => {
+    const model = createTuiModel();
+    model.replaceSessions(tmuxRowsToSessions(sessions));
+    const groups = model.groups();
+    expect(groups.find((group) => group.key === 'idle')?.rows).toHaveLength(2);
+    expect(groups.find((group) => group.key === 'recent')?.rows).toHaveLength(0);
+    expect(model.sessionCount).toBe(2);
+  });
+});
+
+describe('applyMuxNames', () => {
+  const tmux: TuiTmuxSession[] = [
+    tmuxSession({ muxName: 'codeman-abcdef01', sessionId: 'abcdef01-2345-6789' }),
+    tmuxSession({ muxName: 'codeman-99887766' }),
+  ];
+
+  it('joins on the 8-character prefix a mux name carries', () => {
+    const rows = applyMuxNames(
+      [
+        { sessionId: 'abcdef01-2345-6789', sources: ['live'] },
+        { sessionId: '99887766-0000-1111', sources: ['live'] },
+        { sessionId: 'deadbeef-0000-1111', sources: ['history'] },
+      ],
+      tmux
+    );
+    expect(rows[0].muxName).toBe('codeman-abcdef01');
+    expect(rows[1].muxName).toBe('codeman-99887766');
+    // Nothing in tmux backs it, so attach has to refuse rather than guess.
+    expect(rows[2].muxName).toBeUndefined();
+  });
+
+  it('copies rather than mutating its input, and survives an empty tmux list', () => {
+    const input: TuiSessionRow[] = [{ sessionId: 'abcdef01-2345-6789', sources: ['live'] }];
+    const rows = applyMuxNames(input, []);
+    expect(rows[0]).not.toBe(input[0]);
+    expect(rows[0].muxName).toBeUndefined();
+    expect(input[0].muxName).toBeUndefined();
+  });
+});
+
+describe('applyLiveMetrics', () => {
+  const metrics: TuiLiveSessionMetrics[] = [
+    { sessionId: 'aaaa1111', lastSubmitAt: 5_000, inputTokens: 900, outputTokens: 100 },
+    { sessionId: 'bbbb2222', lastSubmitAt: 0, inputTokens: 0, outputTokens: 0 },
+  ];
+
+  it('folds the turn stamp and the token totals onto the matching row', () => {
+    const rows = applyLiveMetrics(
+      [
+        { sessionId: 'aaaa1111', sources: ['live'] },
+        { sessionId: 'cccc3333', sources: ['live'] },
+      ],
+      metrics
+    );
+    expect(rows[0]).toMatchObject({ lastSubmitAt: 5_000, inputTokens: 900, outputTokens: 100 });
+    // No live counterpart (a history row): nothing to fold, nothing invented.
+    expect(rows[1].lastSubmitAt).toBeUndefined();
+    expect(rows[1].inputTokens).toBeUndefined();
+  });
+
+  it('treats a zero as unknown, so a never-submitted session is not dated to the epoch', () => {
+    const [merged] = applyLiveMetrics([{ sessionId: 'bbbb2222', sources: ['live'], createdAt: 1_000 }], metrics);
+    expect(merged.lastSubmitAt).toBeUndefined();
+    expect(merged.inputTokens).toBeUndefined();
+    expect(stateSince('working', merged)).toBe(1_000);
+  });
+
+  it('copies rather than mutating its input, and survives an empty metrics list', () => {
+    const input: TuiSessionRow[] = [{ sessionId: 'aaaa1111', sources: ['live'] }];
+    const rows = applyLiveMetrics(input, []);
+    expect(rows[0]).not.toBe(input[0]);
+    expect(rows[0].lastSubmitAt).toBeUndefined();
+    expect(input[0].lastSubmitAt).toBeUndefined();
+  });
+
+  it('orders the WORKING group by when the turn started, not by session age', () => {
+    // The regression this merge exists for: `old` was created a day before
+    // `fresh` but started its turn a minute AFTER it, so `fresh` has been
+    // working longer and has to lead. Without the merge both fall back to
+    // createdAt and `old` wins.
+    const unified: TuiSessionRow[] = [
+      { sessionId: 'old00000', name: 'old', sources: ['live'], isWorking: true, createdAt: 1_000 },
+      { sessionId: 'fresh000', name: 'fresh', sources: ['live'], isWorking: true, createdAt: 500_000 },
+    ];
+    const turns: TuiLiveSessionMetrics[] = [
+      { sessionId: 'old00000', lastSubmitAt: 900_000 },
+      { sessionId: 'fresh000', lastSubmitAt: 600_000 },
+    ];
+
+    const before = createTuiModel();
+    before.replaceSessions(unified);
+    expect(before.rows().map((r) => r.session.name)).toEqual(['old', 'fresh']);
+
+    const after = createTuiModel();
+    after.replaceSessions(applyLiveMetrics(unified, turns));
+    expect(after.rows().map((r) => r.session.name)).toEqual(['fresh', 'old']);
+    expect(after.rows()[0].since).toBe(600_000);
+  });
+});
+
+describe('buildListLines', () => {
+  it('numbers rows in the dashboard order, so `tui <n>` and `tui --list` agree', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      { sessionId: 'aaaa1111', name: 'quiet', sources: ['live'], lastActivityAt: 10 },
+      { sessionId: 'bbbb2222', name: 'busy', sources: ['live'], isWorking: true, lastSubmitAt: 5 },
+      { sessionId: 'cccc3333', name: 'past', sources: ['history'], lastActivityAt: 1 },
+    ]);
+    expect(buildListLines(model.rows())).toEqual([
+      { index: 1, state: 'working', label: 'busy', workingDir: '' },
+      { index: 2, state: 'idle', label: 'quiet', workingDir: '' },
+      { index: 3, state: 'recent', label: 'past', workingDir: '' },
+    ]);
+  });
+
+  it('truncates the label so one long prompt cannot pad the whole table', () => {
+    const model = createTuiModel();
+    model.replaceSessions([{ sessionId: 'aaaa1111', firstPrompt: 'x'.repeat(200), sources: ['history'] }]);
+    const [line] = buildListLines(model.rows(), 20);
+    expect(line.label).toHaveLength(20);
+    expect(line.label.endsWith('…')).toBe(true);
+  });
+});
+
+describe('the dead-row resume offer', () => {
+  it('advertises r on the message footer only while an offer is armed', () => {
+    const base = { server: true } as const;
+    expect(footerKeysFor('message', GLYPHS, { ...base, resumeOffer: true })).toEqual(['r resume', 'esc dismiss']);
+    // Without an offer the card is a plain notice, and a footer promising `r`
+    // would be advertising a key that does nothing.
+    expect(footerKeysFor('message', GLYPHS, base)).toEqual(['esc dismiss']);
+  });
+});
+
+describe('the one-key way out', () => {
+  it('names a single key with no modifier at all', () => {
+    // The whole point: three beta rounds died on a chord that had to be typed
+    // in the right order with the modifier released at the right moment. F1
+    // rather than F12 so it sits beside Esc, where a hand backing out goes.
+    expect(ONE_KEY_DETACH).toBe('F1');
+    expect(ONE_KEY_DETACH).not.toContain('C-');
+    expect(ONE_KEY_DETACH).not.toContain('+');
+  });
+
+  it('advertises alt+1-9 only once those keys were really claimed', () => {
+    // Same rule as the way-out key: never name a key that does nothing. That
+    // is the bug this whole series started with.
+    const withSwitch = buildAttachBanner({ oneKey: 'F1', switchKeys: true, cols: 150 })['status-format[0]'];
+    expect(withSwitch).toContain('alt+1-9 switch');
+    expect(withSwitch).toContain('back to the codeman dashboard');
+    expect(buildAttachBanner({ oneKey: 'F1', cols: 150 })['status-format[0]']).not.toContain('alt+1-9');
+  });
+
+  it('still fits the strip once the switch hint has taken its space', () => {
+    for (const cols of [80, 100, 120, 190]) {
+      const bar = buildAttachBanner({
+        oneKey: 'F1',
+        switchKeys: true,
+        cols,
+        tabs: Array.from({ length: 12 }, (_, i) => ({
+          index: i + 1,
+          label: `w${i + 1}-session-name`,
+          active: i === 1,
+        })),
+      })['status-format[0]'];
+      const visible = bar.replace(/#\[[^\]]*\]/g, '');
+      expect({ cols, fits: visible.length <= cols }).toEqual({ cols, fits: true });
+      expect(visible).toContain('alt+1-9 switch');
+      expect(visible).toContain('back to the codeman dashboard');
+    }
+  });
+
+  it('puts ONE instruction on the bar, not a menu of ways out', () => {
+    const banner = buildAttachBanner({ prefix: 'C-b', detachKey: 'd', heldAlias: 'C-d', oneKey: 'F1' });
+    const bar = banner['status-format[0]'];
+    expect(bar).toContain('#[bold]F1#[nobold] back to the codeman dashboard');
+    // Even though both fallbacks still work, the bar must not offer them: a bar
+    // listing three ways to leave is what the tester called way too complicated.
+    expect(bar).not.toContain('Ctrl+B');
+    expect(bar).not.toContain('or Ctrl+D');
+  });
+
+  it('falls back to the chord when the key could not be claimed', () => {
+    // Never advertise a key we did not get: a bar naming an inert key is the
+    // original bug, in a new costume.
+    const bar = buildAttachBanner({ prefix: 'C-b', detachKey: 'd', heldAlias: 'C-d' })['status-format[0]'];
+    expect(bar).toContain('Ctrl+B then d');
+    expect(bar).toContain('(or Ctrl+D)');
+    expect(bar).not.toContain('F12');
+  });
+});
+
+describe('the attach tab strip', () => {
+  const tabs = (count: number, activeIndex: number) =>
+    Array.from({ length: count }, (_, i) => ({ index: i + 1, label: `w${i + 1}-case`, active: i === activeIndex }));
+
+  it('draws every session when they all fit, numbered as the dashboard numbers them', () => {
+    const strip = buildAttachTabs(tabs(3, 1));
+    expect(strip).toContain('1 w1-case');
+    expect(strip).toContain('2 w2-case');
+    expect(strip).toContain('3 w3-case');
+    expect(strip).not.toContain('…');
+  });
+
+  it('inverts the session you are actually in', () => {
+    const strip = buildAttachTabs(tabs(3, 1));
+    expect(strip).toContain('#[reverse] 2 w2-case #[noreverse]');
+    expect(strip).not.toContain('#[reverse] 1 w1-case');
+  });
+
+  it('windows around the active tab rather than overflowing the bar', () => {
+    // Overflow would push the way-out hint off the end, which is the one thing
+    // on the bar that must survive.
+    const strip = buildAttachTabs(tabs(20, 9), 6);
+    expect(strip).toContain('10 w10-case');
+    expect(strip.startsWith('…')).toBe(true);
+    expect(strip.endsWith('…')).toBe(true);
+    expect(strip).not.toContain('1 w1-case ');
+  });
+
+  it('marks only the end that is actually cut', () => {
+    const first = buildAttachTabs(tabs(20, 0), 6);
+    expect(first.startsWith('…')).toBe(false);
+    expect(first.endsWith('…')).toBe(true);
+    const last = buildAttachTabs(tabs(20, 19), 6);
+    expect(last.startsWith('…')).toBe(true);
+    expect(last.endsWith('…')).toBe(false);
+  });
+
+  it('truncates a long session name instead of eating the whole strip', () => {
+    const strip = buildAttachTabs([{ index: 1, label: 'w1-an-extremely-long-session-name', active: true }]);
+    expect(strip).toContain('…');
+    expect(strip.length).toBeLessThan(60);
+  });
+
+  it('is empty with no sessions, so the bar falls back to the plain label', () => {
+    expect(buildAttachTabs([])).toBe('');
+  });
+
+  it('escapes a name that would otherwise open a tmux format', () => {
+    expect(buildAttachTabs([{ index: 1, label: 'fix #42', active: false }])).toContain('fix ##42');
+  });
+});
+
+describe('the held-Ctrl detach alias', () => {
+  it('names the key a user produces when they never let go of Ctrl', () => {
+    // The failure this exists for: "Ctrl+B then d" typed as one held chord
+    // sends 0x02 then 0x04, and tmux leaves C-d unbound, so nothing happens.
+    expect(heldCtrlAlias('d')).toBe('C-d');
+  });
+
+  it('lowercases, so a rebound uppercase key still yields the chord it produces', () => {
+    expect(heldCtrlAlias('Q')).toBe('C-q');
+  });
+
+  it('has no alias for a key with no held-Ctrl form', () => {
+    expect(heldCtrlAlias('F1')).toBeNull();
+    expect(heldCtrlAlias('C-d')).toBeNull();
+    expect(heldCtrlAlias('')).toBeNull();
+    expect(heldCtrlAlias('1')).toBeNull();
+  });
+
+  it('advertises the alias on the bar only once it has been claimed', () => {
+    const withAlias = buildAttachBanner({ prefix: 'C-b', detachKey: 'd', heldAlias: 'C-d' });
+    expect(withAlias['status-format[0]']).toContain('Ctrl+B then d');
+    expect(withAlias['status-format[0]']).toContain('(or Ctrl+D)');
+    // Not claimed (the key was already bound to something of the user's) means
+    // not advertised: a bar naming a key that does nothing is the original bug.
+    expect(buildAttachBanner({ prefix: 'C-b', detachKey: 'd' })['status-format[0]']).not.toContain('or Ctrl');
+  });
+});
+
+describe('naming a session the TUI starts', () => {
+  it("follows the web UI's w<n>-<case> convention", () => {
+    expect(nextSessionName('mirofish', [])).toBe('w1-mirofish');
+    expect(nextSessionName('mirofish', ['w1-codeman', 'w2-codeman'])).toBe('w3-mirofish');
+  });
+
+  it('counts past names that are not w<n>- at all', () => {
+    // A session named by hand, or by another surface, must not reset the run.
+    expect(nextSessionName('demo', ['tui-demo-agent', 'w4-codeman', ''])).toBe('w5-demo');
+  });
+
+  it('never returns an empty name, which is what caused the bad label', () => {
+    // An unnamed session falls through rowLabel() to the transcript's first
+    // line, which put "Login interrupted" in the list as a session name.
+    expect(nextSessionName('c', [])).not.toBe('');
+    expect(nextSessionName('c', ['w9007199254740991-x'])).toMatch(/^w\d+-c$/);
+  });
+});
+
+describe('the way out of an attach', () => {
+  it('spells the prefix the way a human reads it, and never assumes C-b', () => {
+    expect(formatPrefixKey('C-b')).toBe('Ctrl+B');
+    // A user who remapped the prefix must not be told to press Ctrl+B.
+    expect(formatPrefixKey('C-a')).toBe('Ctrl+A');
+    expect(formatPrefixKey('M-x')).toBe('Alt+X');
+    // Nothing to go on: the tmux default is the honest guess.
+    expect(formatPrefixKey(undefined)).toBe('Ctrl+B');
+    expect(formatPrefixKey('   ')).toBe('Ctrl+B');
+    // A shape we do not recognise passes through rather than being mangled.
+    expect(formatPrefixKey('F1')).toBe('F1');
+  });
+
+  it('names the chord, not just the prefix', () => {
+    expect(detachChord('C-a', 'd')).toBe('Ctrl+A then d');
+    expect(detachChord()).toBe('Ctrl+B then d');
+  });
+
+  it('names the LOWERCASE detach key, because capital D is choose-client', () => {
+    // Regression: the bar shipped reading `Ctrl+B D`, and a beta tester pressing
+    // exactly that landed in tmux's client chooser while staying attached. tmux
+    // key tables are case-sensitive and `D` is bound to a different command.
+    expect(detachChord()).not.toContain(' D');
+    expect(detachChord()).toMatch(/ then d$/);
+    expect(buildAttachBanner({})['status-format[0]']).not.toContain('#[bold]Ctrl+B D#[nobold]');
+  });
+
+  it('prints a rebound detach key verbatim, never uppercased like the prefix', () => {
+    // formatPrefixKey() uppercases (`C-a` → `Ctrl+A`); running the detach key
+    // through it would reintroduce the same class of bug on a rebound tmux.
+    expect(detachChord('C-a', 'q')).toBe('Ctrl+A then q');
+    expect(buildAttachBanner({ prefix: 'C-a', detachKey: 'q' })['status-format[0]']).toContain('Ctrl+A then q');
+  });
+
+  it('builds ONE status-format option, so tmux draws no window list beside it', () => {
+    const banner = buildAttachBanner({ prefix: 'C-b', label: 'w3-codeman' });
+    expect(Object.keys(banner).sort()).toEqual(['status', 'status-format[0]', 'status-position', 'status-style']);
+    expect(banner.status).toBe('on');
+    // Top, where the web UI keeps its tabs.
+    expect(banner['status-position']).toBe('top');
+    expect(banner['status-format[0]']).toContain('#[bold]Ctrl+B then d#[nobold]');
+    // With no strip to draw, the session's own name is the fallback.
+    expect(banner['status-format[0]']).toContain('w3-codeman');
+  });
+
+  it('sets status-style, or tmux paints its stock green bar under the bar', () => {
+    // Regression: styling only status-format[0] left tmux's default
+    // `bg=green,fg=black` status-style underneath, which a beta tester saw as a
+    // full-width bright green slab across the bottom of the pane.
+    const banner = buildAttachBanner({ prefix: 'C-b' });
+    expect(banner['status-style']).toBe('bg=default,fg=default');
+    expect(banner['status-format[0]']).not.toContain('#[reverse]');
+  });
+
+  it('carries the remapped prefix into the bar', () => {
+    expect(buildAttachBanner({ prefix: 'C-a' })['status-format[0]']).toContain('Ctrl+A then d');
+  });
+
+  it('escapes a label that would otherwise open a tmux format', () => {
+    const banner = buildAttachBanner({ label: 'fix #42 #[bold]' });
+    expect(banner['status-format[0]']).toContain('fix ##42 ##[bold]');
+  });
+
+  it('truncates a long label instead of pushing the instruction off the bar', () => {
+    const banner = buildAttachBanner({ label: 'w12-codeman: a very long session label indeed' });
+    const left = (banner['status-format[0]'].split('#[align=right]')[0] ?? '').replace('#[align=left]', '');
+    // 28 characters of label plus the space either side.
+    expect(left.length).toBeLessThanOrEqual(30);
+    expect(left).toContain('…');
+    expect(banner['status-format[0]']).toContain('back to the codeman dashboard');
+  });
+
+  it('always keeps the way out on the bar, whatever else is on it', () => {
+    // The hint is the one thing that must never be crowded off: it is the only
+    // instruction a user gets while tmux owns the terminal.
+    const crowded = buildAttachBanner({
+      oneKey: 'F1',
+      tabs: Array.from({ length: 20 }, (_, i) => ({
+        index: i + 1,
+        label: `w${i + 1}-a-long-session-name`,
+        active: i === 9,
+      })),
+    });
+    expect(crowded['status-format[0]']).toContain('#[bold]F1#[nobold] back to the codeman dashboard');
+  });
+
+  it('fits the strip to the terminal, measuring VISIBLE columns not format bytes', () => {
+    // The test above only checks the hint is in the format STRING, which it
+    // always was. tmux truncates what it cannot fit and drops the right-aligned
+    // segment, so on a real terminal the hint vanished at every width tested
+    // while that assertion stayed green.
+    const hint = ' F1 back to the codeman dashboard ';
+    for (const cols of [80, 100, 120, 176]) {
+      const bar = buildAttachBanner({
+        oneKey: 'F1',
+        cols,
+        tabs: Array.from({ length: 12 }, (_, i) => ({
+          index: i + 1,
+          label: `w${i + 1}-session-name`,
+          active: i === 1,
+        })),
+      })['status-format[0]'];
+      const visible = bar.replace(/#\[[^\]]*\]/g, '');
+      expect({ cols, fits: visible.length <= cols }).toEqual({ cols, fits: true });
+      expect(visible.length).toBeGreaterThanOrEqual(hint.length);
+    }
+  });
+
+  it('keeps at least one tab even when the hint eats almost the whole bar', () => {
+    const bar = buildAttachBanner({
+      oneKey: 'F1',
+      cols: 40,
+      tabs: [{ index: 1, label: 'w1-case', active: true }],
+    })['status-format[0]'];
+    expect(bar).toContain('1 w1-case');
+    expect(bar).toContain('back to the codeman dashboard');
+  });
+
+  it("tells the help overlay how to get back, in the socket's own prefix", () => {
+    const keys = helpKeysFor(GLYPHS, { server: true, detach: 'Ctrl+A then d' });
+    const detach = keys.find(([key]) => key === 'Ctrl+A then d');
+    expect(detach?.[1]).toContain('detach');
+    // Degraded mode still attaches, so it still needs the way out.
+    expect(helpKeysFor(GLYPHS, { server: false }).map(([key]) => key)).toContain('Ctrl+B then d');
+  });
+});
+
+describe('planResume', () => {
+  const base = { sessionId: 'aaaaaaaa-1111-2222-3333-444444444444', sources: ['transcript'] } as const;
+
+  it('resumes the CONVERSATION id, not the row id', () => {
+    const plan = planResume({
+      ...base,
+      claudeSessionId: 'bbbbbbbb-5555-6666-7777-888888888888',
+      workingDir: '/home/dev/codeman',
+      name: 'w7-codeman',
+    });
+    expect(plan).toEqual({
+      kind: 'resume',
+      workingDir: '/home/dev/codeman',
+      resumeSessionId: 'bbbbbbbb-5555-6666-7777-888888888888',
+      sessionName: 'w7-codeman',
+    });
+  });
+
+  it('falls back to the row id when the row IS the transcript', () => {
+    const plan = planResume({ ...base, workingDir: '/home/dev/codeman' });
+    expect(plan).toMatchObject({ kind: 'resume', resumeSessionId: base.sessionId });
+    // No name to keep: the server names it rather than the TUI inventing one.
+    expect(plan).not.toHaveProperty('sessionName');
+  });
+
+  it('refuses a row with nowhere to run', () => {
+    expect(planResume({ ...base })).toMatchObject({ kind: 'refuse' });
+  });
+
+  it('refuses a non-claude row, since resume is a Claude Code feature', () => {
+    const plan = planResume({ ...base, workingDir: '/home/dev/codeman', mode: 'codex' });
+    expect(plan.kind).toBe('refuse');
+    if (plan.kind === 'refuse') expect(plan.message).toContain('codex');
+  });
+
+  it('refuses an id the server would reject anyway', () => {
+    // The route validates `/^[a-f0-9-]+$/`; a mux-derived row id is not that.
+    expect(planResume({ ...base, sessionId: 'codeman-w1', workingDir: '/home/dev' })).toMatchObject({
+      kind: 'refuse',
+    });
+  });
+});

test/tui/tui-approvals.test.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Unit tests for reading an approvals-inbox item.
+ *
+ * The key matrix is the part worth pinning: a digit the server did not parse
+ * off the pane must NOT produce an answer (it would be typed at a dialog that
+ * has no such option), and an idle prompt must produce none at all, since there
+ * is no dialog on screen and every keystroke would land in the composer.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  approvalAnswerForKey,
+  approvalCard,
+  approvalDenyOption,
+  approvalTone,
+  newApprovalIds,
+} from '../../src/tui/tui-approvals.js';
+import type { ApprovalItem } from '../../src/web/approval-inbox.js';
+
+const NOW = 1_700_000_000_000;
+
+function item(overrides: Partial<ApprovalItem> = {}): ApprovalItem {
+  return {
+    id: 'sess:1',
+    sessionId: 'sess',
+    sessionName: 'w4-api',
+    kind: 'permission',
+    createdAt: NOW,
+    toolName: 'Bash',
+    toolSummary: 'Bash(git push origin main)',
+    options: [
+      { n: 1, label: 'Yes' },
+      { n: 2, label: "Yes, don't ask again" },
+      { n: 3, label: 'No, tell Claude what to do (esc)' },
+    ],
+    ...overrides,
+  };
+}
+
+describe('approvalCard', () => {
+  it('leads a permission prompt with the tool it wants to run', () => {
+    const card = approvalCard(item());
+    expect(card.tone).toBe('err');
+    expect(card.title).toContain('Bash(git push origin main)');
+    expect(card.options).toHaveLength(3);
+    expect(card.hint).toContain('y approve');
+    expect(card.hint).toContain('digit');
+  });
+
+  it('leads a question with its message', () => {
+    const card = approvalCard(item({ kind: 'question', message: 'Which color?', toolSummary: undefined }));
+    expect(card.title).toBe('Which color?');
+    expect(card.tone).toBe('err');
+  });
+
+  it('says an idle prompt is answered by typing, not by approving', () => {
+    const card = approvalCard(item({ kind: 'idle', message: 'waiting for input', options: undefined }));
+    expect(card.tone).toBe('warn');
+    expect(card.options).toEqual([]);
+    expect(card.hint).toBe('p to reply');
+  });
+
+  it('drops the approve/deny-only hint when the frame did not parse', () => {
+    const card = approvalCard(item({ options: undefined }));
+    expect(card.options).toEqual([]);
+    expect(card.hint).toBe('y approve · n deny');
+  });
+
+  it('keeps the message as detail when it says more than the tool line', () => {
+    expect(approvalCard(item({ message: 'about to force-push' })).detail).toEqual(['about to force-push']);
+    expect(approvalCard(item({ message: 'Bash(git push origin main)' })).detail).toEqual([]);
+  });
+
+  it('collapses whitespace so a wrapped hook field cannot break the card', () => {
+    expect(approvalCard(item({ toolSummary: 'Bash(git\n  push)' })).title).toBe('requests: Bash(git push)');
+  });
+});
+
+describe('approvalTone', () => {
+  it('is red for a dialog and yellow for a waiting prompt', () => {
+    expect(approvalTone(item())).toBe('err');
+    expect(approvalTone(item({ kind: 'question' }))).toBe('err');
+    expect(approvalTone(item({ kind: 'idle' }))).toBe('warn');
+  });
+});
+
+describe('approvalAnswerForKey', () => {
+  it('approves with y', () => {
+    expect(approvalAnswerForKey(item(), 'y')).toEqual({ action: 'approve' });
+  });
+
+  it('denies with the parsed No option when there is one', () => {
+    expect(approvalDenyOption(item())).toBe(3);
+    expect(approvalAnswerForKey(item(), 'n')).toEqual({ action: 'option', option: 3 });
+  });
+
+  it('falls back to Esc semantics when no No option parsed', () => {
+    expect(approvalDenyOption(item({ options: undefined }))).toBeNull();
+    expect(approvalAnswerForKey(item({ options: undefined }), 'n')).toEqual({ action: 'deny' });
+    expect(
+      approvalAnswerForKey(
+        item({
+          options: [
+            { n: 1, label: 'Red' },
+            { n: 2, label: 'Blue' },
+          ],
+        }),
+        'n'
+      )
+    ).toEqual({
+      action: 'deny',
+    });
+  });
+
+  it('answers with a digit only when the server parsed that option', () => {
+    expect(approvalAnswerForKey(item(), '2')).toEqual({ action: 'option', option: 2 });
+    expect(approvalAnswerForKey(item(), '4')).toBeNull();
+    expect(approvalAnswerForKey(item({ options: undefined }), '1')).toBeNull();
+  });
+
+  it('makes no key an answer for an idle prompt', () => {
+    const idle = item({ kind: 'idle', options: undefined });
+    for (const key of ['y', 'n', '1', '2', '9']) expect(approvalAnswerForKey(idle, key)).toBeNull();
+  });
+
+  it('leaves every other key to the list', () => {
+    for (const key of ['j', 'k', 'q', 'x', 'p', '/', 'g', '0']) {
+      expect(approvalAnswerForKey(item(), key)).toBeNull();
+    }
+  });
+});
+
+describe('newApprovalIds', () => {
+  it('reports only ids the set has not seen', () => {
+    const seen = new Set(['sess:1']);
+    expect(newApprovalIds(seen, [item(), item({ id: 'other:7', sessionId: 'other' })])).toEqual(['other:7']);
+    expect(newApprovalIds(seen, [item()])).toEqual([]);
+    expect(newApprovalIds(new Set(), [])).toEqual([]);
+  });
+
+  it('reports one id once even when it arrives twice', () => {
+    expect(newApprovalIds(new Set(), [item(), item()])).toEqual(['sess:1']);
+  });
+});

test/tui/tui-client-sse.test.ts

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview Integration tests for the TUI's live-update stream.
+ *
+ * These run against a real loopback `text/event-stream` endpoint rather than a
+ * mocked socket, because the behaviours that matter here are all socket-level:
+ * a stream that ENDS, a stream that goes SILENT without erroring (the failure
+ * mode `EventSource` cannot see, which is why the server heartbeats), and a
+ * teardown that must leave no timer behind.
+ */
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import http from 'node:http';
+import { TuiClient, type TuiApprovalEvent, type TuiSseStatusDetail } from '../../src/tui/tui-client.js';
+
+const PORT = 3242;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+
+interface Connection {
+  url: string;
+  headers: http.IncomingHttpHeaders;
+  res: http.ServerResponse;
+}
+
+const connections: Connection[] = [];
+/** Flipped by a test that wants every connect attempt to fail. */
+let refuse = false;
+
+let server: http.Server;
+let client: TuiClient | null = null;
+
+function frame(event: string, data: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+async function until(predicate: () => boolean, timeoutMs = 3000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error('condition not met before the deadline');
+}
+
+beforeAll(async () => {
+  server = http.createServer((req, res) => {
+    if (!req.url?.startsWith('/api/events')) {
+      res.writeHead(404).end();
+      return;
+    }
+    if (refuse) {
+      res.writeHead(503).end('busy');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
+    // Node holds headers back until the first body write; the real server sends
+    // an `init` frame immediately, so flush to match it. Without this the
+    // client never sees a response and every test here waits forever.
+    res.flushHeaders();
+    connections.push({ url: req.url, headers: req.headers, res });
+  });
+  await new Promise<void>((resolve) => server.listen(PORT, '127.0.0.1', resolve));
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+beforeEach(() => {
+  connections.length = 0;
+  refuse = false;
+});
+
+afterEach(() => {
+  client?.close();
+  client = null;
+  for (const connection of connections) connection.res.end();
+});
+
+describe('subscribeEvents', () => {
+  it('routes each frame to the handler that owns it', async () => {
+    const resyncs: string[] = [];
+    const approvals: TuiApprovalEvent[] = [];
+    let planUsage: unknown = null;
+    let init: unknown = null;
+
+    client = new TuiClient({ baseUrl: BASE_URL, password: 's3cret' });
+    client.subscribeEvents({
+      onInit: (state) => {
+        init = state;
+      },
+      onResync: (event) => resyncs.push(event),
+      onApproval: (event) => approvals.push(event),
+      onPlanUsage: (usage) => {
+        planUsage = usage;
+      },
+    });
+
+    await until(() => connections.length === 1);
+    const { res } = connections[0];
+    res.write(frame('init', { version: '9.9.9', planUsage: { fiveHour: { usedPercentage: 5, resetAt: 1 } } }));
+    res.write(frame('session:created', { id: 'a' }));
+    // Split across writes on purpose: the parser must not need frame-aligned reads.
+    res.write('event: approval:pending\ndata: {"id":"a:1","sessionId":"a",');
+    res.write('"kind":"permission","createdAt":7}\n\n');
+    res.write(frame('session:terminal', { id: 'a', data: 'noise' }));
+    res.write(frame('sse:heartbeat', { t: 1 }));
+    res.write(frame('session:statusTelemetry', { sessionId: 'a', fiveHour: { usedPercentage: 41, resetAt: 2 } }));
+
+    await until(() => planUsage !== null);
+    expect(init).toEqual({ version: '9.9.9', planUsage: { fiveHour: { usedPercentage: 5, resetAt: 1 } } });
+    expect(approvals).toEqual([
+      { kind: 'pending', item: { id: 'a:1', sessionId: 'a', kind: 'permission', createdAt: 7 } },
+    ]);
+    expect(planUsage).toEqual({ sessionId: 'a', fiveHour: { usedPercentage: 41, resetAt: 2 } });
+    // The approval also regrouped a row, so it resyncs too. Terminal and
+    // heartbeat frames never do.
+    expect(resyncs).toEqual(['session:created', 'approval:pending']);
+  });
+
+  it('suppresses the terminal firehose by default and carries the auth header', async () => {
+    client = new TuiClient({ baseUrl: BASE_URL, password: 's3cret' });
+    client.subscribeEvents({});
+    await until(() => connections.length === 1);
+    expect(connections[0].url).toBe('/api/events?sessions=tui-no-terminal');
+    expect(connections[0].headers.authorization).toBe(`Basic ${Buffer.from('admin:s3cret').toString('base64')}`);
+    expect(connections[0].headers.accept).toBe('text/event-stream');
+  });
+
+  it('subscribes to the terminal stream of named sessions when asked', async () => {
+    client = new TuiClient({ baseUrl: BASE_URL });
+    client.subscribeEvents({}, { sessionIds: ['a', 'b'] });
+    await until(() => connections.length === 1);
+    expect(connections[0].url).toBe('/api/events?sessions=a%2Cb');
+  });
+
+  it('reconnects when the stream ends', async () => {
+    const statuses: Array<[string, TuiSseStatusDetail]> = [];
+    client = new TuiClient({ baseUrl: BASE_URL });
+    const stream = client.subscribeEvents(
+      { onStatus: (status, detail) => statuses.push([status, detail]) },
+      { baseBackoffMs: 10, maxBackoffMs: 20 }
+    );
+
+    await until(() => stream.status === 'connected');
+    connections[0].res.end();
+    await until(() => connections.length === 2 && stream.status === 'connected');
+    expect(statuses.map(([status]) => status)).toEqual(['connected', 'reconnecting', 'connected']);
+    expect(statuses[1][1].message).toBeTruthy();
+  });
+
+  it('reconnects when a live stream goes silent, which no socket error reports', async () => {
+    client = new TuiClient({ baseUrl: BASE_URL });
+    client.subscribeEvents({}, { staleTimeoutMs: 150, checkIntervalMs: 25, baseBackoffMs: 10, maxBackoffMs: 20 });
+
+    await until(() => connections.length === 1);
+    // The server holds the connection open and says nothing: exactly the case
+    // the watchdog exists for.
+    await until(() => connections.length === 2);
+    expect(connections).toHaveLength(2);
+  });
+
+  it('recommends polling once connecting keeps failing', async () => {
+    refuse = true;
+    const details: TuiSseStatusDetail[] = [];
+    client = new TuiClient({ baseUrl: BASE_URL });
+    const stream = client.subscribeEvents(
+      { onStatus: (_status, detail) => details.push(detail) },
+      { baseBackoffMs: 10, maxBackoffMs: 20, pollingAfterFailures: 2 }
+    );
+
+    await until(() => details.length >= 2);
+    expect(details[0]).toMatchObject({ attempt: 1, recommendPolling: false });
+    expect(details[1]).toMatchObject({ attempt: 2, recommendPolling: true });
+    expect(stream.recommendPolling).toBe(true);
+    expect(stream.status).toBe('reconnecting');
+  });
+
+  it('stops reconnecting after close, so the process can exit', async () => {
+    client = new TuiClient({ baseUrl: BASE_URL });
+    const stream = client.subscribeEvents({}, { baseBackoffMs: 10, maxBackoffMs: 20 });
+    await until(() => connections.length === 1);
+
+    connections[0].res.end();
+    stream.close();
+    const seen = connections.length;
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    expect(connections.length).toBe(seen);
+  });
+
+  it('closes every stream the client opened', async () => {
+    client = new TuiClient({ baseUrl: BASE_URL });
+    client.subscribeEvents({});
+    client.subscribeEvents({});
+    await until(() => connections.length === 2);
+
+    client.close();
+    await until(() => connections.every((connection) => connection.res.socket === null || connection.res.destroyed));
+    const seen = connections.length;
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    expect(connections.length).toBe(seen);
+  });
+
+  it('refuses to subscribe before the client knows where the server is', () => {
+    const disconnected = new TuiClient({ port: 3999 });
+    expect(() => disconnected.subscribeEvents({})).toThrow(/connect\(\)/);
+  });
+});

test/tui/tui-client.test.ts

@@ -0,0 +1,925 @@
+/**
+ * @fileoverview Unit tests for the TUI's IO layer: discovery, credentials, the
+ * typed API surface and degraded-mode tmux enumeration.
+ *
+ * The API calls run against a real loopback HTTP server that answers in the
+ * shapes the routes really produce (the `{success,data}` envelope, plus
+ * away-digest's legacy top-level `digest`), so an envelope change breaks these
+ * tests rather than the dashboard. tmux is never executed: the exec function is
+ * injected, and `test/setup.ts` gives this file its own HOME, so the state file
+ * it reads is a fixture of its own making.
+ */
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import http from 'node:http';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { dataPath } from '../../src/config/instance.js';
+import {
+  TuiApiError,
+  TuiClient,
+  basicAuthHeader,
+  enumerateTmuxSessions,
+  parseEnvFile,
+  arrayOptionBase,
+  parseSessionOptions,
+  parseDetachKey,
+  parsePrefixBinding,
+  ATTACH_BANNER_MARKER,
+  parseTmuxSessionList,
+  parseWindowSizing,
+  readCodemanCredentials,
+  tuiServerCandidates,
+  type TuiExecFile,
+} from '../../src/tui/tui-client.js';
+
+const PORT = 3241;
+/** Nothing ever listens here: the "no server" path. */
+const DEAD_PORT = 3243;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+
+interface Recorded {
+  method: string;
+  url: string;
+  headers: http.IncomingHttpHeaders;
+  body: string;
+}
+
+const recorded: Recorded[] = [];
+type Responder = (req: http.IncomingMessage, res: http.ServerResponse, body: string) => void;
+
+/** Per-test override; falls back to `defaultResponder`. */
+let responder: Responder | null = null;
+
+function sendJson(res: http.ServerResponse, status: number, payload: unknown): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(payload));
+}
+
+const defaultResponder: Responder = (req, res) => {
+  const url = req.url ?? '';
+  if (url.startsWith('/api/status')) {
+    return sendJson(res, 200, {
+      success: true,
+      data: { version: '9.9.9', planUsage: { fiveHour: { usedPercentage: 32, resetAt: 1000 } } },
+    });
+  }
+  if (url.startsWith('/api/sessions/unified')) {
+    return sendJson(res, 200, {
+      success: true,
+      data: { sessions: [{ sessionId: 'abc', name: 'w1-codeman', sources: ['live'] }], total: 1 },
+    });
+  }
+  if (url === '/api/sessions' || url.startsWith('/api/sessions?')) {
+    // The light state, plus the two rows the narrowing has to discard.
+    return sendJson(res, 200, {
+      success: true,
+      data: [
+        { id: 'abc', lastSubmitAt: 4000, inputTokens: 900, outputTokens: 100, status: 'busy' },
+        { id: '', lastSubmitAt: 7000 },
+        { id: 'zzz', lastSubmitAt: '5', inputTokens: null },
+      ],
+    });
+  }
+  if (url.startsWith('/api/approvals')) {
+    return sendJson(res, 200, {
+      success: true,
+      data: { approvals: [{ id: 'abc:1', sessionId: 'abc', sessionName: 'w1', kind: 'permission', createdAt: 5 }] },
+    });
+  }
+  if (url.includes('/terminal')) {
+    return sendJson(res, 200, { success: true, data: { terminalBuffer: 'tail bytes', status: 'idle' } });
+  }
+  if (url.endsWith('/input')) {
+    return sendJson(res, 200, { success: true, data: {} });
+  }
+  if (url.startsWith('/api/quick-start')) {
+    return sendJson(res, 200, { success: true, data: { sessionId: 'new-1', casePath: '/cases/x', caseName: 'x' } });
+  }
+  if (url.startsWith('/api/cases')) {
+    return sendJson(res, 200, { success: true, data: [{ name: 'x', path: '/cases/x', location: 'local' }] });
+  }
+  if (url.startsWith('/api/search')) {
+    return sendJson(res, 200, {
+      success: true,
+      data: { query: 'foo', groups: [], totalResults: 0, truncated: false },
+    });
+  }
+  if (url.startsWith('/api/away-digest')) {
+    // Legacy shape: the payload sits at the TOP level, not under `data`.
+    return sendJson(res, 200, { success: true, digest: { totals: { activeSessions: 2 } } });
+  }
+  if (req.method === 'DELETE') {
+    return sendJson(res, 200, { success: true, data: {} });
+  }
+  return sendJson(res, 404, { success: false, error: 'no route', errorCode: 'NOT_FOUND' });
+};
+
+function client(overrides: Record<string, unknown> = {}): TuiClient {
+  return new TuiClient({ baseUrl: BASE_URL, timeoutMs: 4000, ...overrides });
+}
+
+let server: http.Server;
+const originalApiUrl = process.env.CODEMAN_API_URL;
+const originalPort = process.env.CODEMAN_PORT;
+
+beforeAll(async () => {
+  // This suite runs inside a Codeman-managed session, which exports
+  // CODEMAN_API_URL pointing at the LIVE server. Discovery consults it, so it
+  // has to be out of the way before any test calls connect().
+  delete process.env.CODEMAN_API_URL;
+  delete process.env.CODEMAN_PORT;
+
+  server = http.createServer((req, res) => {
+    let body = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk: string) => {
+      body += chunk;
+    });
+    req.on('end', () => {
+      recorded.push({ method: req.method ?? '', url: req.url ?? '', headers: req.headers, body });
+      (responder ?? defaultResponder)(req, res, body);
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(PORT, '127.0.0.1', resolve));
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  if (originalApiUrl !== undefined) process.env.CODEMAN_API_URL = originalApiUrl;
+  if (originalPort !== undefined) process.env.CODEMAN_PORT = originalPort;
+});
+
+beforeEach(() => {
+  recorded.length = 0;
+  responder = null;
+});
+
+describe('parseEnvFile', () => {
+  it('reads plain assignments and skips comments and blanks', () => {
+    expect(parseEnvFile('# comment\n\nCODEMAN_USERNAME=bob\nCODEMAN_PASSWORD=hunter2\n')).toEqual({
+      CODEMAN_USERNAME: 'bob',
+      CODEMAN_PASSWORD: 'hunter2',
+    });
+  });
+
+  it('strips one layer of matching quotes', () => {
+    expect(parseEnvFile('A="quoted"\nB=\'single\'\nC="mismatched\'')).toEqual({
+      A: 'quoted',
+      B: 'single',
+      C: '"mismatched\'',
+    });
+  });
+
+  it('ignores lines that are not assignments', () => {
+    expect(parseEnvFile('not an assignment\n1BAD=x\nGOOD=y')).toEqual({ GOOD: 'y' });
+  });
+});
+
+describe('readCodemanCredentials', () => {
+  it('falls back to the data dir .env when the environment has nothing', () => {
+    const envPath = dataPath('.env');
+    mkdirSync(dirname(envPath), { recursive: true });
+    writeFileSync(envPath, 'CODEMAN_USERNAME=fileuser\nCODEMAN_PASSWORD=filepass\n', 'utf-8');
+    expect(readCodemanCredentials()).toEqual({ username: 'fileuser', password: 'filepass' });
+  });
+
+  it('lets the environment win over the file', () => {
+    const envPath = dataPath('.env');
+    writeFileSync(envPath, 'CODEMAN_USERNAME=fileuser\nCODEMAN_PASSWORD=filepass\n', 'utf-8');
+    process.env.CODEMAN_PASSWORD = 'envpass';
+    try {
+      expect(readCodemanCredentials()).toEqual({ username: 'fileuser', password: 'envpass' });
+    } finally {
+      delete process.env.CODEMAN_PASSWORD;
+    }
+  });
+
+  it('reports admin with no password when nothing is configured', () => {
+    expect(readCodemanCredentials('/nonexistent/codeman/.env')).toEqual({ username: 'admin' });
+  });
+});
+
+describe('basicAuthHeader', () => {
+  it('is absent without a password and base64 with one', () => {
+    expect(basicAuthHeader({ username: 'admin' })).toBeUndefined();
+    expect(basicAuthHeader({ username: 'admin', password: 's3cret' })).toBe(
+      `Basic ${Buffer.from('admin:s3cret').toString('base64')}`
+    );
+  });
+});
+
+describe('tuiServerCandidates', () => {
+  it('prefers an explicit API url and trims its trailing slash', () => {
+    expect(tuiServerCandidates({ apiUrl: 'https://box:8443/' })).toEqual(['https://box:8443']);
+  });
+
+  it('probes both schemes on loopback, https first', () => {
+    expect(tuiServerCandidates({ port: 5000 })).toEqual(['https://127.0.0.1:5000', 'http://127.0.0.1:5000']);
+  });
+
+  it('falls back to port 3000 for junk', () => {
+    expect(tuiServerCandidates({ port: 'not-a-port' })).toEqual(['https://127.0.0.1:3000', 'http://127.0.0.1:3000']);
+  });
+});
+
+describe('TuiClient envelope handling', () => {
+  it('unwraps the sessions list', async () => {
+    const sessions = await client().fetchUnifiedSessions(10);
+    expect(sessions).toEqual([{ sessionId: 'abc', name: 'w1-codeman', sources: ['live'] }]);
+    expect(recorded[0].url).toBe('/api/sessions/unified?limit=10');
+  });
+
+  it('unwraps pending approvals', async () => {
+    const approvals = await client().fetchApprovals();
+    expect(approvals).toHaveLength(1);
+    expect(approvals[0].id).toBe('abc:1');
+  });
+
+  it('turns a success:false envelope into a typed error carrying the code', async () => {
+    responder = (_req, res) =>
+      sendJson(res, 404, { success: false, error: 'Session not found', errorCode: 'NOT_FOUND' });
+    await expect(client().fetchTerminalTail('gone', 1000)).rejects.toMatchObject({
+      name: 'TuiApiError',
+      status: 404,
+      errorCode: 'NOT_FOUND',
+      message: 'Session not found',
+    });
+  });
+
+  it('turns a non-JSON failure into a typed error too', async () => {
+    responder = (_req, res) => {
+      res.writeHead(502, { 'Content-Type': 'text/plain' });
+      res.end('bad gateway');
+    };
+    const err = await client()
+      .fetchApprovals()
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TuiApiError);
+    expect((err as TuiApiError).status).toBe(502);
+  });
+
+  it('sends Basic auth when a password is configured, and none when it is not', async () => {
+    await client({ username: 'admin', password: 's3cret' }).fetchApprovals();
+    expect(recorded[0].headers.authorization).toBe(`Basic ${Buffer.from('admin:s3cret').toString('base64')}`);
+
+    recorded.length = 0;
+    await client({ envFilePath: '/nonexistent/codeman/.env' }).fetchApprovals();
+    expect(recorded[0].headers.authorization).toBeUndefined();
+  });
+});
+
+describe('TuiClient.answerApproval', () => {
+  it('reports success', async () => {
+    responder = (_req, res) =>
+      sendJson(res, 200, { success: true, data: { id: 'abc:1', sessionId: 'abc', action: 'approve' } });
+    await expect(client().answerApproval('abc:1', { action: 'approve' })).resolves.toEqual({
+      ok: true,
+      id: 'abc:1',
+      sessionId: 'abc',
+      action: 'approve',
+    });
+  });
+
+  it('reports a 409 as a typed "gone" result, not an exception', async () => {
+    responder = (_req, res) =>
+      sendJson(res, 409, { success: false, error: 'The dialog is no longer on screen', errorCode: 'CONFLICT' });
+    const result = await client().answerApproval('abc:1', { action: 'option', option: 2 });
+    expect(result).toEqual({ ok: false, reason: 'gone', message: 'The dialog is no longer on screen' });
+  });
+
+  it('separates "already resolved" from "digit rejected"', async () => {
+    responder = (_req, res) => sendJson(res, 404, { success: false, error: 'gone', errorCode: 'NOT_FOUND' });
+    expect((await client().answerApproval('x', { action: 'deny' })).ok).toBe(false);
+    expect(await client().answerApproval('x', { action: 'deny' })).toMatchObject({ reason: 'not-found' });
+
+    responder = (_req, res) => sendJson(res, 400, { success: false, error: 'bad option', errorCode: 'INVALID_INPUT' });
+    expect(await client().answerApproval('x', { action: 'option', option: 9 })).toMatchObject({ reason: 'rejected' });
+  });
+
+  it('posts the answer body verbatim', async () => {
+    responder = (_req, res) => sendJson(res, 200, { success: true, data: { id: 'a', sessionId: 'b', action: 'text' } });
+    await client().answerApproval('a b/c', { action: 'text', text: 'yes please' });
+    expect(recorded[0].method).toBe('POST');
+    expect(recorded[0].url).toBe('/api/approvals/a%20b%2Fc/answer');
+    expect(JSON.parse(recorded[0].body)).toEqual({ action: 'text', text: 'yes please' });
+  });
+});
+
+describe('TuiClient.sendInput', () => {
+  it('always terminates with a carriage return and never sends a bare newline', async () => {
+    await client().sendInput('abc', 'hello world');
+    expect(JSON.parse(recorded[0].body)).toMatchObject({ input: 'hello world\r', useMux: true });
+  });
+
+  it('collapses embedded newlines into spaces (multi-line breaks Ink)', async () => {
+    await client().sendInput('abc', 'echo A\necho B\r\nline three  ');
+    expect(JSON.parse(recorded[0].body).input).toBe('echo A echo B line three\r');
+  });
+
+  it('tags every send with a stable clientId and a monotonic seq', async () => {
+    const c = client();
+    await c.sendInput('abc', 'one');
+    await c.sendInput('abc', 'two');
+    await c.sendInput('def', 'three');
+    const bodies = recorded.map((entry) => JSON.parse(entry.body) as { clientId: string; seq: number });
+    expect(bodies.map((b) => b.seq)).toEqual([1, 2, 3]);
+    expect(new Set(bodies.map((b) => b.clientId)).size).toBe(1);
+    expect(bodies[0].clientId).toMatch(/^codeman-tui-\d+$/);
+    expect(c.lastInputSeq).toBe(3);
+  });
+});
+
+describe('TuiClient remaining API surface', () => {
+  it('fetches a terminal tail by byte count', async () => {
+    await expect(client().fetchTerminalTail('abc', 4096)).resolves.toBe('tail bytes');
+    expect(recorded[0].url).toBe('/api/sessions/abc/terminal?tail=4096');
+  });
+
+  it('reads the turn stamp and token counters off the light session state', async () => {
+    const metrics = await client().fetchLiveSessionMetrics();
+    expect(recorded[0].url).toBe('/api/sessions');
+    // Narrowed to the three fields, keyed by id: a row with no usable id is
+    // dropped rather than folded in under an empty key, and a field of the
+    // wrong type is left absent rather than merged as a string.
+    expect(metrics).toEqual([
+      { sessionId: 'abc', lastSubmitAt: 4000, inputTokens: 900, outputTokens: 100 },
+      { sessionId: 'zzz' },
+    ]);
+  });
+
+  it('reports an unreadable session list as empty rather than throwing', async () => {
+    responder = (_req, res) => sendJson(res, 200, { success: true, data: { sessions: 'not an array' } });
+    await expect(client().fetchLiveSessionMetrics()).resolves.toEqual([]);
+  });
+
+  it('starts sessions through quick-start', async () => {
+    const result = await client().quickStart({ caseName: 'x', mode: 'claude', parentSessionId: 'abc' });
+    expect(result.sessionId).toBe('new-1');
+    expect(recorded[0].url).toBe('/api/quick-start');
+    expect(JSON.parse(recorded[0].body)).toEqual({ caseName: 'x', mode: 'claude', parentSessionId: 'abc' });
+  });
+
+  it('lists cases', async () => {
+    await expect(client().fetchCases()).resolves.toEqual([{ name: 'x', path: '/cases/x', location: 'local' }]);
+  });
+
+  it('deletes a session by exact id', async () => {
+    await client().deleteSession('abc');
+    expect(recorded[0].method).toBe('DELETE');
+    expect(recorded[0].url).toBe('/api/sessions/abc');
+  });
+
+  it('searches with an encoded query', async () => {
+    await client().search('a b', 5);
+    expect(recorded[0].url).toBe('/api/search?q=a+b&limit=5');
+  });
+
+  it('reads the away digest from its legacy top-level shape', async () => {
+    await expect(client().fetchAwayDigest('24h')).resolves.toEqual({ totals: { activeSessions: 2 } });
+    expect(recorded[0].url).toBe('/api/away-digest?range=24h');
+  });
+
+  it('reads plan usage off the status snapshot', async () => {
+    await expect(client().fetchPlanUsage()).resolves.toEqual({ fiveHour: { usedPercentage: 32, resetAt: 1000 } });
+  });
+
+  it('reports a missing plan-usage snapshot as null rather than throwing', async () => {
+    responder = (_req, res) => sendJson(res, 200, { success: true, data: { version: '1.0.0', planUsage: null } });
+    await expect(client().fetchPlanUsage()).resolves.toBeNull();
+  });
+});
+
+describe('TuiClient.connect', () => {
+  it('discovers the loopback server and reports its identity', async () => {
+    const info = await new TuiClient({ port: PORT, probeTimeoutMs: 1000 }).connect();
+    expect(info?.baseUrl).toBe(BASE_URL);
+    expect(info?.version).toBe('9.9.9');
+    expect(info?.hostname).toBeTruthy();
+    expect(info?.authRequired).toBeUndefined();
+  });
+
+  it('reports a server that rejects our credentials instead of calling it down', async () => {
+    responder = (_req, res) => {
+      res.writeHead(401, { 'WWW-Authenticate': 'Basic realm="codeman"' });
+      res.end('Unauthorized');
+    };
+    const info = await new TuiClient({ port: PORT, probeTimeoutMs: 1000 }).connect();
+    expect(info?.baseUrl).toBe(BASE_URL);
+    expect(info?.authRequired).toBe(true);
+  });
+
+  it('returns null when nothing answers', async () => {
+    await expect(new TuiClient({ port: DEAD_PORT, probeTimeoutMs: 500 }).connect()).resolves.toBeNull();
+  });
+
+  it('refuses to talk to an unconnected client', async () => {
+    await expect(new TuiClient({ port: DEAD_PORT }).fetchApprovals()).rejects.toThrow(/not connected/);
+  });
+});
+
+describe('degraded-mode tmux enumeration', () => {
+  const listing = [
+    'codeman-1a2b3c4d\t1\t1700000000\t1',
+    'codeman-deadbeef\t0\t1700000100\t2',
+    'claudeman-cafe0001\t0\t1700000200\t1',
+    'my-own-tmux-session\t1\t1700000300\t1',
+    'codeman-ssh-abc\t0\t1700000400\t1',
+  ].join('\n');
+
+  it('parses the list format and keeps only Codeman-owned names', () => {
+    const rows = parseTmuxSessionList(listing);
+    expect(rows.map((row) => row.muxName)).toEqual(['codeman-1a2b3c4d', 'codeman-deadbeef', 'claudeman-cafe0001']);
+    expect(rows[0]).toMatchObject({ sessionIdPrefix: '1a2b3c4d', attached: true, createdAt: 1_700_000_000_000 });
+    expect(rows[1]).toMatchObject({ attached: false, windows: 2 });
+  });
+
+  it('never shells out: the tmux call is an argv array on the instance socket', async () => {
+    const calls: Array<{ file: string; args: readonly string[] }> = [];
+    const exec: TuiExecFile = async (file, args) => {
+      calls.push({ file, args });
+      return { stdout: listing, stderr: '' };
+    };
+    await enumerateTmuxSessions({ exec, socket: 'codeman-beta', statePath: '/nonexistent/state.json' });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].file).toBe('tmux');
+    expect(calls[0].args.slice(0, 4)).toEqual(['-L', 'codeman-beta', 'list-sessions', '-F']);
+  });
+
+  it('decorates rows with names and dirs from state.json, matching on the id prefix', async () => {
+    const statePath = dataPath('state.json');
+    writeFileSync(
+      statePath,
+      JSON.stringify({
+        sessions: {
+          '1a2b3c4d-1111-2222-3333-444444444444': {
+            name: 'w1-codeman',
+            workingDir: '/home/dev/codeman',
+            mode: 'claude',
+          },
+        },
+      }),
+      'utf-8'
+    );
+    const exec: TuiExecFile = async () => ({ stdout: listing, stderr: '' });
+    const rows = await enumerateTmuxSessions({ exec, statePath });
+    expect(rows[0]).toMatchObject({
+      sessionId: '1a2b3c4d-1111-2222-3333-444444444444',
+      name: 'w1-codeman',
+      workingDir: '/home/dev/codeman',
+      mode: 'claude',
+    });
+    // No state entry: the row still exists, it just has no decoration.
+    expect(rows[1].sessionId).toBeUndefined();
+    expect(rows[1].name).toBeUndefined();
+  });
+
+  it('refuses to guess when two ids share a prefix', async () => {
+    const statePath = dataPath('ambiguous-state.json');
+    writeFileSync(
+      statePath,
+      JSON.stringify({
+        sessions: {
+          '1a2b3c4d-aaaa': { name: 'first' },
+          '1a2b3c4d-bbbb': { name: 'second' },
+        },
+      }),
+      'utf-8'
+    );
+    const exec: TuiExecFile = async () => ({ stdout: 'codeman-1a2b3c4d\t0\t1700000000\t1', stderr: '' });
+    const rows = await enumerateTmuxSessions({ exec, statePath });
+    expect(rows[0].name).toBeUndefined();
+  });
+
+  it('treats a dead tmux server as an empty list', async () => {
+    const exec: TuiExecFile = async () => {
+      throw new Error('no server running on /tmp/tmux-1000/codeman');
+    };
+    await expect(enumerateTmuxSessions({ exec })).resolves.toEqual([]);
+  });
+});
+
+describe('attach window sizing', () => {
+  /** A client that only ever needs its injected exec: none of this talks to a server. */
+  function sizingClient(exec: TuiExecFile): TuiClient {
+    return new TuiClient({ baseUrl: BASE_URL, socket: 'codeman-beta', exec });
+  }
+
+  it('parses the sizing format, and rejects a window tmux could not measure', () => {
+    expect(parseWindowSizing('183\t38\tmanual\n')).toEqual({ cols: 183, rows: 38, mode: 'manual' });
+    expect(parseWindowSizing('120\t40\tlatest')).toEqual({ cols: 120, rows: 40, mode: 'latest' });
+    // No mode reported (an ancient tmux) still yields a usable size.
+    expect(parseWindowSizing('120\t40\t')).toEqual({ cols: 120, rows: 40, mode: 'manual' });
+    expect(parseWindowSizing('')).toBeNull();
+    expect(parseWindowSizing("can't find window\n")).toBeNull();
+  });
+
+  it('reads the sizing with an argv array on the client socket', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = sizingClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '120\t40\tmanual', stderr: '' };
+    });
+    await expect(client.readWindowSizing('codeman-1a2b3c4d')).resolves.toEqual({
+      cols: 120,
+      rows: 40,
+      mode: 'manual',
+    });
+    expect(calls[0].slice(0, 6)).toEqual(['-L', 'codeman-beta', 'display-message', '-p', '-t', 'codeman-1a2b3c4d']);
+  });
+
+  it('hands the window to the attaching client with window-size latest', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = sizingClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await expect(client.followAttachingClient('codeman-1a2b3c4d')).resolves.toBe(true);
+    expect(calls[0]).toEqual([
+      '-L',
+      'codeman-beta',
+      'set-window-option',
+      '-t',
+      'codeman-1a2b3c4d',
+      'window-size',
+      'latest',
+    ]);
+  });
+
+  it('restores a manual window with resize-window alone, which re-pins the mode itself', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = sizingClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await client.restoreWindowSizing('codeman-1a2b3c4d', { cols: 120, rows: 40, mode: 'manual' });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual([
+      '-L',
+      'codeman-beta',
+      'resize-window',
+      '-t',
+      'codeman-1a2b3c4d',
+      '-x',
+      '120',
+      '-y',
+      '40',
+    ]);
+  });
+
+  it('restores a non-manual window by putting its mode back', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = sizingClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await client.restoreWindowSizing('codeman-1a2b3c4d', { cols: 120, rows: 40, mode: 'latest' });
+    expect(calls).toEqual([
+      ['-L', 'codeman-beta', 'set-window-option', '-t', 'codeman-1a2b3c4d', 'window-size', 'latest'],
+    ]);
+  });
+
+  it('never targets a name Codeman does not own', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = sizingClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '120\t40\tmanual', stderr: '' };
+    });
+    await expect(client.readWindowSizing('codeman-ssh-prod')).resolves.toBeNull();
+    await expect(client.followAttachingClient('other-session')).resolves.toBe(false);
+    await client.restoreWindowSizing('codeman-dkr-box', { cols: 80, rows: 24, mode: 'manual' });
+    expect(calls).toEqual([]);
+  });
+
+  it('swallows a dead tmux: an attach must never fail over cosmetics', async () => {
+    const client = sizingClient(async () => {
+      throw new Error('no server running on /tmp/tmux-1000/codeman-beta');
+    });
+    await expect(client.readWindowSizing('codeman-1a2b3c4d')).resolves.toBeNull();
+    await expect(client.followAttachingClient('codeman-1a2b3c4d')).resolves.toBe(false);
+    await expect(
+      client.restoreWindowSizing('codeman-1a2b3c4d', { cols: 120, rows: 40, mode: 'manual' })
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe('TuiClient.bindSwitchKey', () => {
+  it('escapes the command separator, or tmux runs the second command instead of binding it', () => {
+    // ⚠️ A bare `;` argument is a command separator to tmux's OWN parser: it
+    // ends the bind-key and executes what follows immediately. That bound only
+    // `switch-client` and ran `window-size latest` against every session at
+    // attach time, which is why sessions were left on `latest` after a detach —
+    // the sizing snapshot was taken from already-corrupted state. Verified
+    // against real tmux both ways before this test was written.
+    const calls: string[][] = [];
+    const exec: TuiExecFile = async (_file, args) => {
+      calls.push([...args]);
+      return { stdout: '', stderr: '' };
+    };
+    const client = new TuiClient({ baseUrl: BASE_URL, socket: 'codeman-beta', exec });
+    return client.bindSwitchKey('M-2', 'codeman-aaaa1111').then(() => {
+      const bind = calls.find((args) => args.includes('bind-key'));
+      expect(bind).toBeDefined();
+      expect(bind).toContain('\\;');
+      expect(bind).not.toContain(';');
+      // Both commands have to be in the ONE binding.
+      expect(bind?.join(' ')).toContain('switch-client -t codeman-aaaa1111');
+      expect(bind?.join(' ')).toContain('window-size latest');
+    });
+  });
+});
+
+describe('parsePrefixBinding', () => {
+  const REAL = [
+    'bind-key    -T prefix d       detach-client',
+    'bind-key    -T prefix D       choose-client -Z',
+    'bind-key    -T prefix C-b     send-prefix',
+  ].join('\n');
+
+  it('reports what a key is bound to, verbatim', () => {
+    expect(parsePrefixBinding(REAL, 'd')).toBe('detach-client');
+    expect(parsePrefixBinding(REAL, 'D')).toBe('choose-client -Z');
+  });
+
+  it('is null for a key nothing claims, which is what makes it safe to claim', () => {
+    expect(parsePrefixBinding(REAL, 'C-d')).toBeNull();
+  });
+
+  it('is case-sensitive, like tmux itself', () => {
+    expect(parsePrefixBinding('bind-key -T prefix D choose-client', 'd')).toBeNull();
+  });
+
+  it('reads the prefix-less root table too, where the one-key exit lives', () => {
+    const root = ['bind-key -T root MouseDown1Pane select-pane -t =', 'bind-key -T root F12 detach-client'].join('\n');
+    expect(parsePrefixBinding(root, 'F12', 'root')).toBe('detach-client');
+    // Stock tmux has no F12 there, which is what makes it safe to claim.
+    expect(parsePrefixBinding('bind-key -T root MouseDown1Pane select-pane -t =', 'F12', 'root')).toBeNull();
+    // A prefix binding must not be mistaken for a root one.
+    expect(parsePrefixBinding('bind-key -T prefix F12 detach-client', 'F12', 'root')).toBeNull();
+  });
+});
+
+describe('TuiClient.clearLeakedAttachBanners', () => {
+  const OURS = `#[align=left] press #[bold]Ctrl+B then d#[nobold] to detach, ${ATTACH_BANNER_MARKER} #[default]`;
+
+  function sweeper(formats: Record<string, string>): { client: TuiClient; calls: string[][] } {
+    const calls: string[][] = [];
+    const exec: TuiExecFile = async (_file, args) => {
+      calls.push([...args]);
+      if (args.includes('list-sessions')) return { stdout: Object.keys(formats).join('\n'), stderr: '' };
+      if (args.includes('show-options')) {
+        const name = args[args.indexOf('-t') + 1] ?? '';
+        return { stdout: formats[name] ?? '', stderr: '' };
+      }
+      return { stdout: '', stderr: '' };
+    };
+    return { client: new TuiClient({ baseUrl: BASE_URL, socket: 'codeman-beta', exec }), calls };
+  }
+
+  it('takes down a bar a killed TUI left behind, and puts status back off', async () => {
+    // The case that produced this: the tester closed the terminal window while
+    // attached, so restore() never ran and the bar stayed pinned.
+    const { client, calls } = sweeper({ 'codeman-aaaa1111': OURS });
+    expect(await client.clearLeakedAttachBanners()).toBe(1);
+    const sets = calls.filter((args) => args.includes('set-option'));
+    // The array whole, never one index: unsetting `status-format[0]` alone
+    // leaves an EMPTY array, which renders as a blank bar.
+    expect(sets.some((args) => args.includes('-u') && args.includes('status-format'))).toBe(true);
+    expect(sets.some((args) => args.includes('-u') && args.includes('status-style'))).toBe(true);
+    // ⚠️ Every option the banner writes must be undone by the pass that
+    // recognises it. `status-position` was missing, so a sweep removed the
+    // marker and left the position behind — and with no marker the leftover
+    // stopped matching, making it permanently unsweepable.
+    expect(sets.some((args) => args.includes('-u') && args.includes('status-position'))).toBe(true);
+    expect(sets.some((args) => args.join(' ').endsWith('status off'))).toBe(true);
+    expect(sets.every((args) => !args.includes('status-format[0]'))).toBe(true);
+  });
+
+  it('never touches a status bar that is not ours', async () => {
+    const { client, calls } = sweeper({ 'codeman-bbbb2222': '#[align=right] my own bar ' });
+    expect(await client.clearLeakedAttachBanners()).toBe(0);
+    expect(calls.filter((args) => args.includes('set-option'))).toEqual([]);
+  });
+
+  it('sweeps only the sessions that leaked, leaving the rest alone', async () => {
+    const { client } = sweeper({
+      'codeman-aaaa1111': OURS,
+      'codeman-bbbb2222': '',
+      'codeman-cccc3333': OURS,
+    });
+    expect(await client.clearLeakedAttachBanners()).toBe(2);
+  });
+
+  it('reports nothing rather than throwing when there is no tmux server', async () => {
+    const exec: TuiExecFile = async () => {
+      throw new Error('no server running on /tmp/tmux-1000/codeman-beta');
+    };
+    const client = new TuiClient({ baseUrl: BASE_URL, socket: 'codeman-beta', exec });
+    await expect(client.clearLeakedAttachBanners()).resolves.toBe(0);
+  });
+});
+
+describe('parseDetachKey', () => {
+  // Verbatim from `tmux -L codeman list-keys -T prefix` on tmux 3.4, trimmed to
+  // the two lines that matter. They differ only by case, which is the whole
+  // point: `D` is choose-client and advertising it leaves the tester attached.
+  const REAL_TMUX_34 = [
+    'bind-key    -T prefix C-b     send-prefix',
+    'bind-key    -T prefix d       detach-client',
+    'bind-key    -T prefix D       choose-client -Z',
+    'bind-key    -T prefix x       confirm-before -p "kill-pane #P? (y/n)" kill-pane',
+  ].join('\n');
+
+  it('picks the lowercase detach-client binding out of real tmux output', () => {
+    expect(parseDetachKey(REAL_TMUX_34)).toBe('d');
+  });
+
+  it('follows a rebound detach key rather than assuming d', () => {
+    expect(parseDetachKey('bind-key -T prefix Q detach-client')).toBe('Q');
+  });
+
+  it('tolerates the -r repeat flag ahead of -T', () => {
+    expect(parseDetachKey('bind-key -r -T prefix d detach-client')).toBe('d');
+  });
+
+  it('ignores detach-client bindings that carry arguments', () => {
+    // `-a` detaches OTHER clients and `-P` kills the pane's process; neither is
+    // what the bar promises, so a socket with only those reports nothing.
+    expect(parseDetachKey('bind-key -T prefix X detach-client -a')).toBeNull();
+    expect(parseDetachKey('bind-key -T prefix Y detach-client -P')).toBeNull();
+  });
+
+  it('prefers a single-character binding over a named key', () => {
+    const both = 'bind-key -T prefix F1 detach-client\nbind-key -T prefix d detach-client';
+    expect(parseDetachKey(both)).toBe('d');
+  });
+
+  it('is null when nothing detaches, so the caller can fall back', () => {
+    expect(parseDetachKey('')).toBeNull();
+    expect(parseDetachKey('bind-key -T prefix D choose-client -Z')).toBeNull();
+  });
+});
+
+describe('attach status bar options', () => {
+  function optionsClient(exec: TuiExecFile): TuiClient {
+    return new TuiClient({ baseUrl: BASE_URL, socket: 'codeman-beta', exec });
+  }
+
+  const SHOW = [
+    'history-limit 100000',
+    'mouse off',
+    'status off',
+    'status-format[0] "#[reverse] left "',
+    'status-format[1] "#[align=right] second line "',
+    'status-left " plain #[bold]value\\" quoted "',
+  ].join('\n');
+
+  it('reads session-level options, unquoting what tmux quoted', () => {
+    const parsed = parseSessionOptions(SHOW, ['status', 'status-left', 'status-right']);
+    expect(parsed.status).toBe('off');
+    expect(parsed['status-left']).toBe(' plain #[bold]value" quoted ');
+    // Not set on this session: restoring must UNSET it, not write a value back.
+    expect(parsed['status-right']).toBeNull();
+  });
+
+  it('captures a whole array when one index is asked for', () => {
+    const parsed = parseSessionOptions(SHOW, ['status-format[0]']);
+    expect(parsed['status-format[0]']).toBe('#[reverse] left ');
+    // The second status line the user configured comes along, or the restore
+    // would silently delete it.
+    expect(parsed['status-format[1]']).toBe('#[align=right] second line ');
+  });
+
+  it('knows an array element from a plain option', () => {
+    expect(arrayOptionBase('status-format[0]')).toBe('status-format');
+    expect(arrayOptionBase('status')).toBeNull();
+  });
+
+  it('reads the prefix from the session, falling back to the global one', () => {
+    const calls: Array<readonly string[]> = [];
+    const client = optionsClient(async (_file, args) => {
+      calls.push(args);
+      // Session level says nothing; the global answer is the real one.
+      return { stdout: args.includes('-gv') ? 'C-a\n' : '\n', stderr: '' };
+    });
+    return expect(client.readPrefixKey('codeman-1a2b3c4d'))
+      .resolves.toBe('C-a')
+      .then(() => {
+        expect(calls).toHaveLength(2);
+        expect(calls[1]).toContain('-gv');
+      });
+  });
+
+  it('restores an array by dropping it FIRST, then writing the captured indices', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = optionsClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await client.restoreSessionOptions('codeman-1a2b3c4d', {
+      status: 'off',
+      'status-format[0]': null,
+      'status-format[1]': '#[align=right] second ',
+    });
+    // Unsetting one index leaves an EMPTY array (a blank status bar), so the
+    // base option goes first and the survivors are written back on top.
+    expect(calls[0].slice(2)).toEqual(['set-option', '-u', '-t', 'codeman-1a2b3c4d', 'status-format']);
+    expect(calls.map((args) => args.slice(2))).toContainEqual([
+      'set-option',
+      '-t',
+      'codeman-1a2b3c4d',
+      'status',
+      'off',
+    ]);
+    expect(calls.map((args) => args.slice(2))).toContainEqual([
+      'set-option',
+      '-t',
+      'codeman-1a2b3c4d',
+      'status-format[1]',
+      '#[align=right] second ',
+    ]);
+    // The null index is covered by the array drop; it never gets its own unset.
+    expect(calls.some((args) => args.includes('status-format[0]'))).toBe(false);
+  });
+
+  it('unsets a plain option that was not set on the session', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = optionsClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await client.restoreSessionOptions('codeman-1a2b3c4d', { status: null });
+    expect(calls[0].slice(2)).toEqual(['set-option', '-u', '-t', 'codeman-1a2b3c4d', 'status']);
+  });
+
+  it('writes the banner one option at a time, and never at a foreign session', async () => {
+    const calls: Array<readonly string[]> = [];
+    const client = optionsClient(async (_file, args) => {
+      calls.push(args);
+      return { stdout: '', stderr: '' };
+    });
+    await client.applySessionOptions('codeman-1a2b3c4d', { status: 'on', 'status-format[0]': 'x' });
+    expect(calls).toHaveLength(2);
+    expect(calls[0].slice(2)).toEqual(['set-option', '-t', 'codeman-1a2b3c4d', 'status', 'on']);
+    calls.length = 0;
+    await client.applySessionOptions('codeman-ssh-prod', { status: 'on' });
+    await client.restoreSessionOptions('codeman-dkr-box', { status: null });
+    await expect(client.readPrefixKey('other-thing')).resolves.toBeNull();
+    expect(calls).toEqual([]);
+  });
+
+  it('keeps going when tmux rejects one option', async () => {
+    let seen = 0;
+    const client = optionsClient(async (_file, args) => {
+      seen += 1;
+      if (args.includes('status-format[0]')) throw new Error('unknown option');
+      return { stdout: '', stderr: '' };
+    });
+    await client.applySessionOptions('codeman-1a2b3c4d', { 'status-format[0]': 'x', status: 'on' });
+    expect(seen).toBe(2);
+  });
+});
+
+describe('resumeSession', () => {
+  it('creates with resumeSessionId and then starts the pane', async () => {
+    recorded.length = 0;
+    responder = (req, res) => {
+      if (req.url === '/api/sessions') {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ success: true, data: { session: { id: 'new-session-id' } } }));
+        return;
+      }
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ success: true, data: {} }));
+    };
+    const id = await client().resumeSession({
+      workingDir: '/home/dev/codeman',
+      resumeSessionId: 'bbbbbbbb-5555-6666-7777-888888888888',
+      sessionName: 'w7-codeman',
+    });
+    expect(id).toBe('new-session-id');
+    expect(recorded.map((entry) => `${entry.method} ${entry.url}`)).toEqual([
+      'POST /api/sessions',
+      // Creating a session gives it no pane; without this the resumed row would
+      // sit in the list unattachable.
+      'POST /api/sessions/new-session-id/interactive',
+    ]);
+    expect(JSON.parse(recorded[0].body)).toMatchObject({
+      workingDir: '/home/dev/codeman',
+      resumeSessionId: 'bbbbbbbb-5555-6666-7777-888888888888',
+      mode: 'claude',
+      name: 'w7-codeman',
+    });
+  });
+
+  it('does not start a pane when creation answered without an id', async () => {
+    recorded.length = 0;
+    responder = (_req, res) => {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ success: true, data: {} }));
+    };
+    await expect(client().resumeSession({ workingDir: '/home/dev', resumeSessionId: 'aaaa-bbbb' })).rejects.toThrow(
+      /no session id/
+    );
+    expect(recorded).toHaveLength(1);
+  });
+});

test/tui/tui-composer.test.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Unit tests for the single-line editor behind `p` and `/`.
+ *
+ * The interesting parts are the ones a terminal makes hard to see: a cursor
+ * that must not split a surrogate pair, a combining mark that belongs to the
+ * character before it, and the scroll window, which is the only reason a long
+ * prompt stays typeable in a footer one line tall.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  composerBackspace,
+  composerDelete,
+  composerDeleteWord,
+  composerEnd,
+  composerHome,
+  composerInsert,
+  composerMove,
+  composerScroll,
+  composerStep,
+  composerText,
+  composerWindow,
+  createComposer,
+} from '../../src/tui/tui-composer.js';
+
+describe('editing', () => {
+  it('inserts at the cursor and keeps it after the insertion', () => {
+    let state = createComposer('abc');
+    expect(composerText(state)).toBe('abc');
+    expect(state.cursor).toBe(3);
+
+    state = composerMove(state, -1);
+    state = composerInsert(state, 'XY');
+    expect(composerText(state)).toBe('abXYc');
+    expect(state.cursor).toBe(4);
+  });
+
+  it('never lets a newline into a single-line editor', () => {
+    const state = composerInsert(createComposer(), 'one\ntwo\r\nthree');
+    expect(composerText(state)).toBe('one two three');
+  });
+
+  it('deletes whole characters, not code units', () => {
+    const state = composerBackspace(createComposer('a🙂'));
+    expect(composerText(state)).toBe('a');
+    expect(state.cursor).toBe(1);
+  });
+
+  it('deletes forward under the cursor and stops at the end', () => {
+    const state = composerHome(createComposer('abc'));
+    expect(composerText(composerDelete(state))).toBe('bc');
+    expect(composerText(composerDelete(createComposer('abc')))).toBe('abc');
+  });
+
+  it('deletes a word back over its trailing spaces', () => {
+    expect(composerText(composerDeleteWord(createComposer('fix the bug   ')))).toBe('fix the ');
+    expect(composerText(composerDeleteWord(createComposer('word')))).toBe('');
+    expect(composerText(composerDeleteWord(createComposer('')))).toBe('');
+  });
+
+  it('clamps the cursor at both ends', () => {
+    const state = createComposer('abc');
+    expect(composerMove(state, 10).cursor).toBe(3);
+    expect(composerMove(state, -10).cursor).toBe(0);
+    expect(composerHome(state).cursor).toBe(0);
+    expect(composerEnd(composerHome(state)).cursor).toBe(3);
+  });
+
+  it('leaves a no-op edit as the same object, so nothing repaints', () => {
+    const state = createComposer('abc');
+    const atStart = composerHome(state);
+    expect(composerInsert(state, '')).toBe(state);
+    expect(composerMove(state, 1)).toBe(state);
+    expect(composerBackspace(atStart)).toBe(atStart);
+  });
+});
+
+describe('the scroll window', () => {
+  it('shows the whole text while it fits', () => {
+    const window = composerWindow(createComposer('short'), 20);
+    expect(window.text).toBe('short');
+    expect(window.cursorColumn).toBe(5);
+    expect(window.scroll).toBe(0);
+  });
+
+  it('scrolls just far enough to keep the cursor visible', () => {
+    // 10 columns of room, one reserved for the cursor itself.
+    const state = composerScroll(createComposer('0123456789abcdef'), 10);
+    const window = composerWindow(state, 10);
+    expect(window.scroll).toBe(7);
+    expect(window.text).toBe('789abcdef');
+    expect(window.cursorColumn).toBe(9);
+  });
+
+  it('scrolls back when the cursor moves left out of the window', () => {
+    let state = composerScroll(createComposer('0123456789abcdef'), 10);
+    expect(state.scroll).toBe(7);
+    state = composerScroll(composerHome(state), 10);
+    expect(state.scroll).toBe(0);
+    expect(composerWindow(state, 10).cursorColumn).toBe(0);
+  });
+
+  it('counts a double-width character as the two columns it takes', () => {
+    const state = composerScroll(createComposer('日本語です'), 6);
+    const window = composerWindow(state, 6);
+    // Five wide characters = 10 columns; the window holds the last three (6
+    // columns) minus the cell the cursor needs.
+    expect(window.cursorColumn).toBeLessThanOrEqual(5);
+    expect(window.text.length).toBeLessThanOrEqual(5);
+    expect(composerText(state)).toBe('日本語です');
+  });
+
+  it('survives a width of one', () => {
+    const state = composerScroll(createComposer('abc'), 1);
+    expect(() => composerWindow(state, 1)).not.toThrow();
+    expect(composerWindow(state, 1).cursorColumn).toBe(0);
+  });
+});
+
+describe('composerStep', () => {
+  const state = createComposer('ab');
+
+  it('reports Enter and Escape instead of acting on them', () => {
+    expect(composerStep(state, { type: 'enter' })).toEqual({ kind: 'submit', text: 'ab' });
+    expect(composerStep(state, { type: 'escape' })).toEqual({ kind: 'cancel' });
+    expect(composerStep(state, { type: 'ctrl', key: 'c' })).toEqual({ kind: 'cancel' });
+  });
+
+  it('maps the editing keys', () => {
+    expect(composerStep(state, { type: 'char', value: 'c' })).toEqual({
+      kind: 'edit',
+      state: expect.objectContaining({ cursor: 3 }),
+    });
+    expect(composerStep(state, { type: 'key', name: 'left' })).toEqual({
+      kind: 'edit',
+      state: expect.objectContaining({ cursor: 1 }),
+    });
+    expect(composerStep(state, { type: 'ctrl', key: 'u' })).toEqual({
+      kind: 'edit',
+      state: expect.objectContaining({ cursor: 0 }),
+    });
+    expect(composerText((composerStep(state, { type: 'ctrl', key: 'u' }) as { state: never }).state)).toBe('');
+  });
+
+  it('ignores keys that mean nothing to an editor', () => {
+    expect(composerStep(state, { type: 'tab' })).toEqual({ kind: 'ignore' });
+    expect(composerStep(state, { type: 'key', name: 'pageup' })).toEqual({ kind: 'ignore' });
+    expect(composerStep(state, { type: 'ctrl', key: 'x' })).toEqual({ kind: 'ignore' });
+    expect(composerStep(state, { type: 'mouse', kind: 'press', x: 1, y: 1, button: 0 })).toEqual({ kind: 'ignore' });
+  });
+});

test/tui/tui-digest.test.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Unit tests for the away digest's compact rendering.
+ *
+ * The digest is read top-down and never studied, so the promises worth pinning
+ * are: the counts sit in the first line, every entry is exactly one line, and a
+ * long section is capped with a tail rather than pushing the next section off
+ * the overlay.
+ */
+import { describe, it, expect } from 'vitest';
+import { formatAwayDigest } from '../../src/tui/tui-digest.js';
+import type { AwayDigestItem, AwayDigestResponse } from '../../src/web/away-digest.js';
+
+const NOW = 1_700_000_000_000;
+
+function entry(overrides: Partial<AwayDigestItem> = {}): AwayDigestItem {
+  return {
+    id: 'e1',
+    timestamp: NOW - 120_000,
+    category: 'needs_attention',
+    severity: 'warning',
+    title: 'permission prompt',
+    source: 'lifecycle',
+    sessionName: 'w4-api',
+    ...overrides,
+  };
+}
+
+function digest(overrides: Partial<AwayDigestResponse> = {}): AwayDigestResponse {
+  return {
+    range: { range: '24h', since: NOW - 86_400_000, until: NOW },
+    generatedAt: NOW,
+    dataFreshness: {
+      lifecyclePersisted: true,
+      tokenStatsPersisted: true,
+      runSummariesLiveOnly: true,
+      subagentsLiveOnly: true,
+    },
+    totals: {
+      sessionsCreated: 3,
+      sessionsExited: 1,
+      activeSessions: 2,
+      needsAttention: 1,
+      completed: 1,
+      errors: 0,
+      warnings: 1,
+      tokenWindowPrecision: 'day',
+    },
+    sections: { needsAttention: [], completed: [], stillRunning: [], idle: [], informational: [] },
+    ...overrides,
+  };
+}
+
+describe('formatAwayDigest', () => {
+  it('opens with the range and the counts', () => {
+    const lines = formatAwayDigest(digest(), { now: NOW });
+    expect(lines[0]).toBe('the last 24 hours · 3 started · 1 exited · 2 running');
+  });
+
+  it('names the range the way the API labels it', () => {
+    const since = digest({ range: { range: 'since-last-visit', since: NOW - 1000, until: NOW } });
+    expect(formatAwayDigest(since, { now: NOW })[0]).toContain('since your last visit');
+  });
+
+  it('gives every entry one line, with its age and session', () => {
+    const lines = formatAwayDigest(
+      digest({
+        sections: {
+          needsAttention: [entry({ detail: 'Bash(git push)' })],
+          completed: [],
+          stillRunning: [],
+          idle: [],
+          informational: [],
+        },
+      }),
+      { now: NOW }
+    );
+    expect(lines).toContain('NEEDS ATTENTION (1)');
+    expect(lines).toContain('  2m   w4-api  permission prompt · Bash(git push)');
+  });
+
+  it('caps a long section instead of burying the next one', () => {
+    const many = Array.from({ length: 9 }, (_, i) => entry({ id: `e${i}`, title: `event ${i}` }));
+    const lines = formatAwayDigest(
+      digest({
+        sections: {
+          needsAttention: many,
+          completed: [entry({ id: 'c1', category: 'completed', title: 'finished' })],
+          stillRunning: [],
+          idle: [],
+          informational: [],
+        },
+      }),
+      { now: NOW, sectionLimit: 3 }
+    );
+    expect(lines).toContain('NEEDS ATTENTION (9)');
+    expect(lines).toContain('  … 6 more');
+    expect(lines).toContain('COMPLETED (1)');
+  });
+
+  it('says so when nothing happened', () => {
+    expect(formatAwayDigest(digest(), { now: NOW })).toContain('nothing happened while you were away');
+  });
+
+  it('adds the token totals only when the range had any', () => {
+    expect(formatAwayDigest(digest(), { now: NOW }).join('\n')).not.toContain('tokens:');
+    const withTokens = digest({
+      totals: { ...digest().totals, inputTokens: 45_200, outputTokens: 12_100, estimatedCost: 1.234 },
+    });
+    expect(formatAwayDigest(withTokens, { now: NOW })).toContain('tokens: 45.2k in · 12.1k out · $1.23');
+  });
+
+  it('drops the age column for an entry with no usable timestamp', () => {
+    const lines = formatAwayDigest(
+      digest({
+        sections: {
+          needsAttention: [entry({ timestamp: 0, sessionName: undefined, sessionId: 'abcdef1234' })],
+          completed: [],
+          stillRunning: [],
+          idle: [],
+          informational: [],
+        },
+      }),
+      { now: NOW }
+    );
+    expect(lines).toContain('       abcdef12  permission prompt');
+  });
+});

test/tui/tui-e2e.test.ts

@@ -0,0 +1,782 @@
+/**
+ * @fileoverview End-to-end test for `codeman tui` in a real terminal.
+ *
+ * The dashboard is spawned under node-pty against a fake API server, so this
+ * covers everything the pure tests cannot: raw-mode key decoding, the frame
+ * actually reaching a terminal, SSE-driven refresh, and the exit sequence that
+ * has to restore the user's screen. Frames are addressed absolutely rather than
+ * newline-separated, so the assertions parse the LAST frame out of the captured
+ * bytes and read its list column.
+ *
+ * Every verb that leaves the process is asserted on the REQUEST the fake server
+ * received, not on the frame: a prompt has to arrive as one line ending in a
+ * carriage return, and an approval as the exact action and option digit, both
+ * of which a rendered frame would happily lie about.
+ *
+ * The child gets its own data dir and a tmux socket name nothing runs on, which
+ * keeps the enumeration that degraded mode and the attach path use from seeing
+ * the machine's real sessions. Nothing here attaches, kills or writes anything.
+ *
+ * TIMING: the tests share one long-lived dashboard, so each one leaves the list
+ * in focus for the next. Where a notice can still be up (it clears itself after
+ * ~1.5s), the wait is on the FOOTER showing the keys that must be live, because
+ * an overlay would swallow the next keystroke as a dismissal.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import * as pty from 'node-pty';
+import { computeLayout } from '../../src/tui/tui-layout.js';
+import type { UnifiedSessionItem } from '../../src/services/unified-session-service.js';
+import type { SearchResponseData } from '../../src/types/search.js';
+import type { ApprovalItem } from '../../src/web/approval-inbox.js';
+import type { AwayDigestResponse } from '../../src/web/away-digest.js';
+
+const PORT = 3244;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const ROOT = resolve(import.meta.dirname, '..', '..');
+const COLS = 100;
+const ROWS = 30;
+const LIST_WIDTH = computeLayout(COLS, ROWS).list.width;
+
+const NOW = Date.now();
+
+const ALPHA = 'aaaa1111-0000-0000-0000-000000000000';
+/** The id the fake server hands back for a resumed conversation. */
+const RESUMED = 'dddd4444-0000-0000-0000-000000000000';
+const BETA = 'bbbb2222-0000-0000-0000-000000000000';
+
+/** Mutable so a test can add a session and announce it over SSE. */
+let sessions: UnifiedSessionItem[] = [];
+/** What the dashboard can answer: pending items, keyed the way the inbox keys them. */
+let approvals: ApprovalItem[] = [];
+/** Terminal buffers the preview pane polls, by session id. */
+const terminals = new Map<string, string>();
+/**
+ * The LIGHT session state (`GET /api/sessions`), which is where the turn stamp
+ * and the token counters come from: the unified list carries neither, so w2-beta
+ * is deliberately a session created 10 minutes ago whose turn started one minute
+ * ago. A row dated by the wrong one of those reads `10m` instead of `1m`.
+ */
+let liveState: Array<Record<string, unknown>> = [];
+/**
+ * Tail reads the preview pane has asked for. On the real server that route runs
+ * two synchronous tmux calls and normalizes the whole byte buffer, so how often
+ * a quiet pane is re-read is a property worth pinning.
+ */
+let terminalReads = 0;
+/** Everything the TUI posted, so a test can assert on the exact body. */
+const answered: Array<{ id: string; body: Record<string, unknown> }> = [];
+/** `POST /api/sessions` bodies: resuming a RECENT row is the only thing that sends one. */
+const created: Array<Record<string, unknown>> = [];
+/** Sessions the TUI asked to start a pane for, in order. */
+const started: string[] = [];
+const inputs: Array<{ sessionId: string; body: Record<string, unknown> }> = [];
+
+const PLAN_USAGE = {
+  fiveHour: { usedPercentage: 32, resetAt: NOW + 3_600_000 },
+  sevenDay: { usedPercentage: 61, resetAt: NOW + 86_400_000 },
+};
+
+const SEARCH_RESULTS: SearchResponseData = {
+  query: 'alpha',
+  groups: [
+    {
+      type: 'session',
+      results: [
+        {
+          type: 'session',
+          sessionId: ALPHA,
+          sessionName: 'w1-alpha',
+          timestamp: NOW,
+          snippet: '/tmp/alpha',
+          exactMatch: true,
+          jumpTo: { kind: 'session', sessionId: ALPHA },
+        },
+      ],
+    },
+    {
+      type: 'file',
+      results: [
+        {
+          type: 'file',
+          sessionId: ALPHA,
+          sessionName: 'w1-alpha',
+          timestamp: NOW,
+          snippet: 'alpha notes',
+          exactMatch: false,
+          jumpTo: { kind: 'file-preview', sessionId: ALPHA, relativePath: 'docs/alpha.md' },
+        },
+      ],
+    },
+  ],
+  totalResults: 2,
+  truncated: false,
+};
+
+const DIGEST: AwayDigestResponse = {
+  range: { range: '24h', since: NOW - 86_400_000, until: NOW },
+  generatedAt: NOW,
+  dataFreshness: {
+    lifecyclePersisted: true,
+    tokenStatsPersisted: true,
+    runSummariesLiveOnly: true,
+    subagentsLiveOnly: true,
+  },
+  totals: {
+    sessionsCreated: 4,
+    sessionsExited: 1,
+    activeSessions: 3,
+    needsAttention: 1,
+    completed: 1,
+    errors: 0,
+    warnings: 1,
+    tokenWindowPrecision: 'day',
+  },
+  sections: {
+    needsAttention: [
+      {
+        id: 'd1',
+        sessionId: BETA,
+        sessionName: 'w2-beta',
+        timestamp: NOW - 300_000,
+        category: 'needs_attention',
+        severity: 'warning',
+        title: 'waited for approval',
+        source: 'lifecycle',
+      },
+    ],
+    completed: [],
+    stillRunning: [],
+    idle: [],
+    informational: [],
+  },
+};
+
+function permissionApproval(id: string): ApprovalItem {
+  return {
+    id,
+    sessionId: BETA,
+    sessionName: 'w2-beta',
+    kind: 'permission',
+    createdAt: Date.now(),
+    toolName: 'Bash',
+    toolSummary: 'Bash(git push origin main)',
+    options: [
+      { n: 1, label: 'Yes' },
+      { n: 2, label: 'Yes, and do not ask again' },
+      { n: 3, label: 'No, tell Claude what to do' },
+    ],
+  };
+}
+
+function resetSessions(): void {
+  sessions = [
+    {
+      sessionId: BETA,
+      name: 'w2-beta',
+      mode: 'claude',
+      sources: ['live'],
+      isWorking: true,
+      workingDir: '/tmp/beta',
+      createdAt: NOW - 600_000,
+      lastActivityAt: NOW,
+    },
+    {
+      sessionId: ALPHA,
+      name: 'w1-alpha',
+      mode: 'claude',
+      sources: ['live'],
+      status: 'idle',
+      workingDir: '/tmp/alpha',
+      createdAt: NOW - 900_000,
+      lastActivityAt: NOW - 60_000,
+    },
+    {
+      sessionId: 'cccc3333-0000-0000-0000-000000000000',
+      name: 'w3-gamma',
+      sources: ['history'],
+      workingDir: '/tmp/gamma',
+      lastActivityAt: NOW - 3_600_000,
+    },
+  ];
+  liveState = [
+    { id: BETA, status: 'busy', lastSubmitAt: NOW - 60_000, inputTokens: 42_000, outputTokens: 3_200 },
+    { id: ALPHA, status: 'idle', lastSubmitAt: NOW - 60_000 },
+  ];
+}
+
+let server: http.Server;
+const sseClients = new Set<http.ServerResponse>();
+let dataDir = '';
+
+function sendJson(res: http.ServerResponse, payload: unknown): void {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(payload));
+}
+
+function pushEvent(event: string, data: unknown): void {
+  for (const client of sseClients) client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+
+function childEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) if (value !== undefined) env[key] = value;
+  // The suite runs inside a Codeman-managed tmux pane, whose environment would
+  // otherwise point the child at the LIVE server and make it think it is nested.
+  delete env.TMUX;
+  delete env.TMUX_PANE;
+  delete env.CODEMAN_SESSION_ID;
+  delete env.FORCE_COLOR;
+  delete env.CODEMAN_PORT;
+  return {
+    ...env,
+    CODEMAN_API_URL: BASE_URL,
+    CODEMAN_DATA_DIR: dataDir,
+    CODEMAN_TMUX_SOCKET: 'codeman-tui-e2e',
+    CODEMAN_TUI_GLYPHS: 'ascii',
+    NO_COLOR: '1',
+    TERM: 'xterm-256color',
+    LANG: 'C.UTF-8',
+  };
+}
+
+/** The session id in `/api/sessions/<id>/<what>`, or null. */
+function sessionRoute(url: string, what: string): string | null {
+  const match = url.match(new RegExp(`^/api/sessions/([^/?]+)/${what}`));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+function readBody(req: http.IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((done) => {
+    let raw = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk: string) => {
+      raw += chunk;
+    });
+    req.on('end', () => {
+      try {
+        done(JSON.parse(raw || '{}') as Record<string, unknown>);
+      } catch {
+        done({});
+      }
+    });
+  });
+}
+
+beforeAll(async () => {
+  dataDir = mkdtempSync(join(tmpdir(), 'codeman-tui-e2e-'));
+  resetSessions();
+  server = http.createServer((req, res) => {
+    const url = req.url ?? '';
+    if (url.startsWith('/api/events')) {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write(`event: init\ndata: ${JSON.stringify({ version: '9.9.9', planUsage: PLAN_USAGE })}\n\n`);
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+      return;
+    }
+    if (url.startsWith('/api/status')) {
+      return sendJson(res, { success: true, data: { version: '9.9.9', planUsage: PLAN_USAGE } });
+    }
+    if (url.startsWith('/api/sessions/unified')) return sendJson(res, { success: true, data: { sessions } });
+    if (url === '/api/sessions' || url.startsWith('/api/sessions?')) {
+      if (req.method === 'POST') {
+        void readBody(req).then((body) => {
+          created.push(body);
+          sendJson(res, { success: true, data: { session: { id: RESUMED } } });
+        });
+        return;
+      }
+      return sendJson(res, { success: true, data: liveState });
+    }
+
+    const startFor = sessionRoute(url, 'interactive');
+    if (startFor) {
+      started.push(startFor);
+      return sendJson(res, { success: true, data: {} });
+    }
+
+    const previewFor = sessionRoute(url, 'terminal');
+    if (previewFor) {
+      terminalReads++;
+      return sendJson(res, { success: true, data: { terminalBuffer: terminals.get(previewFor) ?? '' } });
+    }
+
+    const inputFor = sessionRoute(url, 'input');
+    if (inputFor) {
+      void readBody(req).then((body) => {
+        inputs.push({ sessionId: inputFor, body });
+        sendJson(res, { success: true, data: { delivered: true } });
+      });
+      return;
+    }
+
+    const answerMatch = url.match(/^\/api\/approvals\/([^/?]+)\/answer/);
+    if (answerMatch) {
+      const id = decodeURIComponent(answerMatch[1]);
+      void readBody(req).then((body) => {
+        const item = approvals.find((entry) => entry.id === id);
+        if (!item) {
+          res.writeHead(409, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({ success: false, error: 'The dialog is no longer on screen', errorCode: 'CONFLICT' })
+          );
+          return;
+        }
+        answered.push({ id, body });
+        approvals = approvals.filter((entry) => entry.id !== id);
+        sendJson(res, { success: true, data: { id, sessionId: item.sessionId, action: body.action } });
+        pushEvent('approval:resolved', { id, sessionId: item.sessionId, kind: item.kind, resolution: 'answered' });
+      });
+      return;
+    }
+
+    if (url.startsWith('/api/approvals')) return sendJson(res, { success: true, data: { approvals } });
+    if (url.startsWith('/api/search')) return sendJson(res, { success: true, data: SEARCH_RESULTS });
+    // The away digest predates the envelope: its payload sits at the top level.
+    if (url.startsWith('/api/away-digest')) return sendJson(res, { success: true, digest: DIGEST });
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ success: false, error: 'no route', errorCode: 'NOT_FOUND' }));
+  });
+  await new Promise<void>((done) => server.listen(PORT, '127.0.0.1', done));
+});
+
+afterAll(async () => {
+  for (const client of sseClients) client.destroy();
+  sseClients.clear();
+  await new Promise<void>((done) => server.close(() => done()));
+  if (dataDir) rmSync(dataDir, { recursive: true, force: true });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frame parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ANSI = /\u001b\[[0-9;?]*[a-zA-Z]/g;
+
+/**
+ * The last COMPLETE frame, one entry per terminal row. Frames start at
+ * `ESC [ 1;1 H` and address every row absolutely, so splitting on the
+ * addressing sequences reconstructs the lines. The pty delivers a frame in
+ * several chunks, so the newest one is often half-written: taking it would make
+ * every assertion that indexes a line racy.
+ */
+function frameLines(raw: string): string[] {
+  const frames = raw.split('\u001b[1;1H').slice(1);
+  for (let i = frames.length - 1; i >= 0; i--) {
+    const lines = frames[i].split(/\u001b\[\d+;1H/).map((line) => line.replace(ANSI, '').replace(/\s+$/, ''));
+    if (lines.length >= ROWS) return lines.slice(0, ROWS);
+  }
+  return [];
+}
+
+/** Just the sidebar column, so a name in the preview pane cannot answer for a row. */
+function listLines(raw: string): string[] {
+  return frameLines(raw).map((line) => line.slice(0, LIST_WIDTH).replace(/\s+$/, ''));
+}
+
+/** Just the preview column, for the same reason in reverse. */
+function previewText(raw: string): string {
+  return frameLines(raw)
+    .map((line) => line.slice(LIST_WIDTH + 1).replace(/\s+$/, ''))
+    .join('\n');
+}
+
+function rowFor(raw: string, name: string): string {
+  return listLines(raw).find((line) => line.includes(name)) ?? '';
+}
+
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 15_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (predicate()) return;
+    if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`);
+    await new Promise((done) => setTimeout(done, 50));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The dashboard
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('codeman tui (under a pty)', () => {
+  let term: pty.IPty;
+  let output = '';
+  let exitCode: number | null = null;
+
+  beforeAll(async () => {
+    terminals.set(BETA, '\x1b[32mready\x1b[0m\nbeta is thinking\n');
+    terminals.set(ALPHA, 'alpha has been quiet\n');
+    term = pty.spawn('npx', ['tsx', 'src/index.ts', 'tui'], {
+      name: 'xterm-256color',
+      cols: COLS,
+      rows: ROWS,
+      cwd: ROOT,
+      env: childEnv(),
+    });
+    term.onData((data) => {
+      output += data;
+    });
+    term.onExit(({ exitCode: code }) => {
+      exitCode = code;
+    });
+    await waitFor(() => output.includes('w2-beta'), 'the first frame', 25_000);
+  }, 40_000);
+
+  afterAll(() => {
+    if (exitCode === null) term.kill();
+  });
+
+  /**
+   * Walk the cursor onto a row by name. Rows re-sort when an approval lands, so
+   * a test can never assume a position; `j` wraps, so this always terminates.
+   */
+  async function selectRow(name: string): Promise<void> {
+    for (let i = 0; i < 12 && !rowFor(output, name).startsWith('>'); i++) {
+      term.write('j');
+      await new Promise((done) => setTimeout(done, 120));
+    }
+    await waitFor(() => rowFor(output, name).startsWith('>'), `${name} to be selected`);
+  }
+
+  it('enters the alternate screen and hides the cursor', () => {
+    expect(output).toContain('\u001b[?1049h');
+    expect(output).toContain('\u001b[?25l');
+  });
+
+  it('groups the sessions the way the dashboard promises', () => {
+    const lines = listLines(output);
+    const index = (needle: string) => lines.findIndex((line) => line.includes(needle));
+    expect(index('WORKING')).toBeGreaterThan(0);
+    expect(index('WORKING')).toBeLessThan(index('w2-beta'));
+    expect(index('w2-beta')).toBeLessThan(index('IDLE'));
+    expect(index('IDLE')).toBeLessThan(index('w1-alpha'));
+    expect(index('w1-alpha')).toBeLessThan(index('RECENT'));
+    expect(index('RECENT')).toBeLessThan(index('w3-gamma'));
+  });
+
+  it('dates a working row by its turn, not by the session age', () => {
+    // w2-beta was created 10 minutes ago and pressed Enter one minute ago, and
+    // only `GET /api/sessions` knows the second number. `1m` proves the merge
+    // ran end to end; `10m` would mean the row fell back to createdAt.
+    const beta = rowFor(output, 'w2-beta');
+    expect(beta).toMatch(/\b1m\b/);
+    expect(beta).not.toMatch(/\b10m\b/);
+    // The token column rides the same read.
+    expect(beta).toContain('45.2k');
+  });
+
+  it('shows the header facts and only the keys that work', () => {
+    const lines = frameLines(output);
+    expect(lines[0]).toContain('codeman');
+    expect(lines[0]).toContain('v9.9.9');
+    // Two live rows; the history row is not a session you have open.
+    expect(lines[0]).toContain('2 sessions');
+    // The plan-usage chip, punctuated with this tier's separator.
+    expect(lines[0]).toContain('5h 32%');
+    expect(lines[0]).toContain('wk 61%');
+    const footer = lines[ROWS - 1];
+    expect(footer).toContain('attach');
+    expect(footer).toContain('x kill');
+    expect(footer).toContain('p prompt');
+    expect(footer).toContain('/ search');
+  });
+
+  it('shows the selected session tail and follows it as it changes', async () => {
+    await waitFor(() => previewText(output).includes('beta is thinking'), 'the preview tail');
+    expect(previewText(output)).toContain('w2-beta');
+    expect(previewText(output)).toContain('/tmp/beta');
+
+    terminals.set(BETA, '\x1b[32mready\x1b[0m\nbeta is thinking\nbeta finished the job\n');
+    await waitFor(() => previewText(output).includes('beta finished the job'), 'the tail to refresh');
+  });
+
+  it('starts with the first row selected and moves the cursor with j / k', async () => {
+    expect(rowFor(output, 'w2-beta').startsWith('>')).toBe(true);
+
+    term.write('j');
+    await waitFor(() => rowFor(output, 'w1-alpha').startsWith('>'), 'j to select the next row');
+    expect(rowFor(output, 'w2-beta').startsWith('>')).toBe(false);
+
+    term.write('k');
+    await waitFor(() => rowFor(output, 'w2-beta').startsWith('>'), 'k to select the previous row');
+  });
+
+  it('moves the cursor with the arrow keys', async () => {
+    term.write('\u001b[B');
+    await waitFor(() => rowFor(output, 'w1-alpha').startsWith('>'), 'the down arrow to move the cursor');
+    term.write('\u001b[A');
+    await waitFor(() => rowFor(output, 'w2-beta').startsWith('>'), 'the up arrow to move the cursor');
+  });
+
+  it('keeps re-reading the tail, but backs off while the pane stays quiet', async () => {
+    await selectRow('w2-beta');
+    // Let the selection's own immediate read land, then measure a window in
+    // which nothing writes to the pane.
+    await new Promise((done) => setTimeout(done, 400));
+    const before = terminalReads;
+    await new Promise((done) => setTimeout(done, 6_000));
+    const reads = terminalReads - before;
+    // Still following: a chain that forgot to re-arm would freeze the pane at
+    // whatever it last showed, which no frame assertion would notice.
+    expect(reads).toBeGreaterThan(0);
+    // A fixed one-second poll would be six. The ladder (1s, 2s, 4s, then the
+    // 5s ceiling) cannot exceed four in this window.
+    expect(reads).toBeLessThanOrEqual(4);
+  }, 20_000);
+
+  it('picks up a session announced over SSE', async () => {
+    sessions = [
+      ...sessions,
+      {
+        sessionId: 'dddd4444-0000-0000-0000-000000000000',
+        name: 'w4-delta',
+        mode: 'shell',
+        sources: ['live'],
+        status: 'idle',
+        workingDir: '/tmp/delta',
+        createdAt: NOW,
+        lastActivityAt: NOW,
+      },
+    ];
+    pushEvent('session:created', { id: 'dddd4444-0000-0000-0000-000000000000' });
+    await waitFor(() => listLines(output).some((line) => line.includes('w4-delta')), 'the new session to appear');
+    expect(frameLines(output)[0]).toContain('3 sessions');
+  });
+
+  it('opens and closes the help overlay', async () => {
+    term.write('?');
+    await waitFor(() => frameLines(output).some((line) => line.includes('Keys')), 'the help overlay');
+    expect(frameLines(output).join('\n')).toContain('kill (y to confirm)');
+
+    term.write('\u001b');
+    await waitFor(() => !frameLines(output).some((line) => line.includes('Keys')), 'escape to close the overlay');
+  });
+
+  it('asks for a y before killing anything, and names what it would kill', async () => {
+    term.write('x');
+    await waitFor(() => frameLines(output).some((line) => line.includes('Kill session')), 'the kill confirmation');
+    const overlay = frameLines(output).join('\n');
+    expect(overlay).toContain('press y to kill');
+    expect(overlay).toContain('w2-beta');
+
+    term.write('\u001b');
+    await waitFor(() => !frameLines(output).some((line) => line.includes('Kill session')), 'escape to cancel the kill');
+  });
+
+  it('cancels the kill on any key that is not y, and kills nothing', async () => {
+    term.write('x');
+    await waitFor(() => frameLines(output).some((line) => line.includes('Kill session')), 'the kill confirmation');
+    term.write('n');
+    await waitFor(() => !frameLines(output).some((line) => line.includes('Kill session')), 'the dialog to close');
+    // The session is still listed: `n` cancelled rather than killed.
+    await waitFor(() => frameLines(output).some((line) => line.includes('w2-beta')), 'w2-beta to still be listed');
+  });
+
+  it('sends a one-line prompt with p', async () => {
+    term.write('p');
+    await waitFor(() => frameLines(output)[ROWS - 1].startsWith(' >'), 'the composer to open');
+
+    term.write('deploy the thing');
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('deploy the thing'), 'the typed line');
+    // Backspace edits the line rather than moving the list cursor.
+    term.write('\u007f'.repeat(5));
+    await waitFor(() => !frameLines(output)[ROWS - 1].includes('thing'), 'backspace to edit the line');
+
+    term.write('\r');
+    await waitFor(() => inputs.length > 0, 'the input POST');
+    expect(inputs[0].sessionId).toBe(BETA);
+    // Single line, ended with a carriage return, or the server never presses Enter.
+    expect(inputs[0].body.input).toBe('deploy the\r');
+    expect(String(inputs[0].body.input)).not.toContain('\n');
+    expect(inputs[0].body.clientId).toBeTruthy();
+
+    await waitFor(() => frameLines(output).join('\n').includes('sent'), 'the sent notice');
+    await waitFor(() => !frameLines(output).join('\n').includes('Notice'), 'the notice to clear itself', 5_000);
+  });
+
+  it('searches with / and selects a live result', async () => {
+    term.write('/');
+    await waitFor(() => frameLines(output).join('\n').includes('Search'), 'the search overlay');
+
+    term.write('alpha');
+    await waitFor(() => frameLines(output).join('\n').includes('2 results'), 'the debounced search to answer');
+    const overlay = frameLines(output).join('\n');
+    expect(overlay).toContain('alpha_');
+    expect(overlay).toContain('SESSIONS');
+    expect(overlay).toContain('w1-alpha');
+    expect(overlay).toContain('docs/alpha.md');
+
+    term.write('\r');
+    await waitFor(() => !frameLines(output).join('\n').includes('Search'), 'the overlay to close');
+    await waitFor(() => rowFor(output, 'w1-alpha').startsWith('>'), 'the searched session to be selected');
+  });
+
+  it('shows the away digest with g', async () => {
+    term.write('g');
+    await waitFor(() => frameLines(output).join('\n').includes('Away digest'), 'the digest overlay');
+    const panel = frameLines(output).join('\n');
+    expect(panel).toContain('the last 24 hours');
+    expect(panel).toContain('4 started');
+    expect(panel).toContain('NEEDS ATTENTION (1)');
+    expect(panel).toContain('waited for approval');
+
+    term.write('\u001b');
+    await waitFor(() => !frameLines(output).join('\n').includes('Away digest'), 'escape to close the digest');
+  });
+
+  it('renders the pending dialog as a card and rings the bell once for it', async () => {
+    await selectRow('w2-beta');
+    const before = output.length;
+
+    approvals = [permissionApproval(`${BETA}:1`)];
+    pushEvent('approval:pending', approvals[0]);
+    await waitFor(() => previewText(output).includes('requests: Bash(git push origin main)'), 'the approval card');
+    const card = previewText(output);
+    expect(card).toContain('1. Yes');
+    expect(card).toContain('3. No, tell Claude what to do');
+    expect(card).toContain('y approve');
+    expect(frameLines(output)[0]).toContain('[!] 1');
+
+    // The same item announced twice is one prompt, so it must not ring twice.
+    pushEvent('approval:pending', approvals[0]);
+    await new Promise((done) => setTimeout(done, 1_200));
+    expect(output.slice(before).split('\u0007')).toHaveLength(2);
+  });
+
+  it('answers the dialog with the option digit and clears the card', async () => {
+    // The footer is the honest signal that the list has the keyboard: a notice
+    // still on screen would swallow the digit as a dismissal.
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('y approve'), 'the answer keys in the footer');
+    expect(frameLines(output)[ROWS - 1]).toContain('1-9 option');
+
+    term.write('1');
+    await waitFor(() => answered.length > 0, 'the answer POST');
+    expect(answered[0]).toEqual({ id: `${BETA}:1`, body: { action: 'option', option: 1 } });
+    await waitFor(() => !previewText(output).includes('requests: Bash'), 'the card to clear');
+  });
+
+  it('approves with y', async () => {
+    approvals = [permissionApproval(`${BETA}:2`)];
+    pushEvent('approval:pending', approvals[0]);
+    await waitFor(() => previewText(output).includes('requests: Bash(git push origin main)'), 'the second card');
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('y approve'), 'the answer keys in the footer');
+
+    term.write('y');
+    await waitFor(() => answered.length > 1, 'the approve POST');
+    expect(answered[1]).toEqual({ id: `${BETA}:2`, body: { action: 'approve' } });
+  });
+
+  it('says so when the dialog has already left the screen', async () => {
+    approvals = [permissionApproval(`${BETA}:3`)];
+    pushEvent('approval:pending', approvals[0]);
+    await waitFor(() => previewText(output).includes('requests: Bash(git push origin main)'), 'the third card');
+
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('y approve'), 'the answer keys in the footer');
+    // Answered in tmux a moment ago: the server 409s and the TUI explains.
+    approvals = [];
+    term.write('y');
+    await waitFor(() => frameLines(output).join('\n').includes('no longer on screen'), 'the gone-dialog message');
+    term.write('\u001b');
+    await waitFor(() => !frameLines(output).join('\n').includes('no longer on screen'), 'escape to dismiss it');
+  });
+
+  it('resumes a RECENT row exactly ONCE, however long its pane takes to appear', async () => {
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('attach'), 'the list to have focus');
+    for (let i = 0; i < 8 && !rowFor(output, 'w3-gamma').startsWith('>'); i++) {
+      term.write('\u001b[B');
+      await new Promise((done) => setTimeout(done, 120));
+    }
+    await waitFor(() => rowFor(output, 'w3-gamma').startsWith('>'), 'the history row to be selected');
+
+    term.write('\r');
+    await waitFor(() => created.length > 0, 'the resume POST');
+    expect(created[0]).toMatchObject({
+      // The conversation, in the directory it ran in, as a claude session.
+      resumeSessionId: 'cccc3333-0000-0000-0000-000000000000',
+      workingDir: '/tmp/gamma',
+      mode: 'claude',
+      name: 'w3-gamma',
+    });
+    await waitFor(() => started.includes(RESUMED), 'the resumed session to be started');
+
+    // The pane never appears here (the child runs on an empty tmux socket), which
+    // is precisely the case that used to re-enter the resume: one session per
+    // second until something killed it. One press must stay one session.
+    await new Promise((done) => setTimeout(done, 2_500));
+    expect(created).toHaveLength(1);
+    expect(started).toEqual([RESUMED]);
+
+    term.write('\u001b');
+    await waitFor(() => frameLines(output)[ROWS - 1].includes('attach'), 'the list to take focus back');
+  });
+
+  it('quits on q and restores the screen it took over', async () => {
+    term.write('q');
+    await waitFor(() => exitCode !== null, 'the TUI to exit', 10_000);
+    expect(exitCode).toBe(0);
+    expect(output).toContain('\u001b[?25h');
+    expect(output).toContain('\u001b[?1049l');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The non-interactive fast paths
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RunResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Run the CLI with pipes, which is exactly the "not a TTY" case. */
+function runPiped(args: string[]): Promise<RunResult> {
+  return new Promise((done) => {
+    const child = spawn('npx', ['tsx', 'src/index.ts', ...args], { cwd: ROOT, env: childEnv() });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf-8');
+    child.stderr.setEncoding('utf-8');
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on('close', (code) => done({ code, stdout, stderr }));
+  });
+}
+
+describe('codeman tui --list', () => {
+  it('prints the numbered list and exits 0 when piped', async () => {
+    const result = await runPiped(['tui', '--list']);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('w2-beta');
+    expect(result.stdout).toContain('w1-alpha');
+    expect(result.stdout).toContain('/tmp/alpha');
+    // Same ordering as the dashboard: WORKING first, history last.
+    expect(result.stdout.indexOf('w2-beta')).toBeLessThan(result.stdout.indexOf('w1-alpha'));
+    expect(result.stdout.indexOf('w1-alpha')).toBeLessThan(result.stdout.indexOf('w3-gamma'));
+    expect(result.stdout).toMatch(/^\s+1\s+working\s+w2-beta/m);
+  }, 30_000);
+});
+
+describe('codeman tui without a terminal', () => {
+  it('refuses to open the dashboard and points at the fast paths', async () => {
+    const result = await runPiped(['tui']);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('interactive terminal');
+    expect(result.stderr).toContain('--list');
+    expect(result.stdout).not.toContain('\u001b[?1049h');
+  }, 30_000);
+});

test/tui/tui-keys.test.ts

@@ -0,0 +1,245 @@
+/**
+ * @fileoverview Unit tests for the raw-mode key parser.
+ *
+ * The two failure modes that matter are covered explicitly: a sequence that
+ * arrives split across reads must decode identically at EVERY split position
+ * (a terminal is free to break a chunk anywhere), and an unknown sequence must
+ * be swallowed rather than leaked as typed text.
+ */
+import { describe, it, expect } from 'vitest';
+import { createKeyParser, type TuiInputEvent } from '../../src/tui/tui-keys.js';
+
+/** Feed a whole sequence in one go. */
+function decode(input: string | Buffer): TuiInputEvent[] {
+  return createKeyParser().feed(input);
+}
+
+/** Feed the same bytes split at `at`, so a torn read must not change the result. */
+function decodeSplit(bytes: Buffer, at: number): TuiInputEvent[] {
+  const parser = createKeyParser();
+  return [...parser.feed(bytes.subarray(0, at)), ...parser.feed(bytes.subarray(at))];
+}
+
+describe('printable input', () => {
+  it('emits one event per code point', () => {
+    expect(decode('ab')).toEqual([
+      { type: 'char', value: 'a' },
+      { type: 'char', value: 'b' },
+    ]);
+  });
+
+  it('decodes multi-byte UTF-8', () => {
+    expect(decode('é中')).toEqual([
+      { type: 'char', value: 'é' },
+      { type: 'char', value: '中' },
+    ]);
+    expect(decode('\u{1f600}')).toEqual([{ type: 'char', value: '\u{1f600}' }]);
+  });
+
+  it('holds a UTF-8 character split across chunks', () => {
+    const bytes = Buffer.from('中', 'utf8');
+    const parser = createKeyParser();
+    expect(parser.feed(bytes.subarray(0, 1))).toEqual([]);
+    expect(parser.pending()).toBe(1);
+    expect(parser.feed(bytes.subarray(1, 2))).toEqual([]);
+    expect(parser.feed(bytes.subarray(2))).toEqual([{ type: 'char', value: '中' }]);
+    expect(parser.pending()).toBe(0);
+  });
+
+  it('decodes a 4-byte character at every split position', () => {
+    const bytes = Buffer.from('\u{1f600}', 'utf8');
+    for (let at = 0; at <= bytes.length; at++) {
+      expect(decodeSplit(bytes, at)).toEqual([{ type: 'char', value: '\u{1f600}' }]);
+    }
+  });
+
+  it('swallows invalid UTF-8 rather than typing a replacement character', () => {
+    expect(decode(Buffer.from([0xc3, 0x28]))).toEqual([{ type: 'char', value: '(' }]);
+  });
+});
+
+describe('control keys', () => {
+  it('maps Enter, Tab and Backspace', () => {
+    expect(decode('\r')).toEqual([{ type: 'enter' }]);
+    expect(decode('\n')).toEqual([{ type: 'enter' }]);
+    expect(decode('\t')).toEqual([{ type: 'tab' }]);
+    expect(decode('\x7f')).toEqual([{ type: 'backspace' }]);
+    expect(decode('\x08')).toEqual([{ type: 'backspace' }]);
+  });
+
+  it('maps Ctrl+letter, keeping Ctrl+I and Ctrl+M as Tab and Enter', () => {
+    expect(decode('\x03')).toEqual([{ type: 'ctrl', key: 'c' }]);
+    expect(decode('\x17')).toEqual([{ type: 'ctrl', key: 'w' }]);
+    expect(decode('\x01')).toEqual([{ type: 'ctrl', key: 'a' }]);
+    expect(decode('\x09')).toEqual([{ type: 'tab' }]);
+    expect(decode('\x0d')).toEqual([{ type: 'enter' }]);
+    expect(decode('\x00')).toEqual([{ type: 'ctrl', key: '@' }]);
+  });
+});
+
+describe('escape sequences', () => {
+  it('decodes CSI arrows, Home and End', () => {
+    expect(decode('\x1b[A')).toEqual([{ type: 'key', name: 'up' }]);
+    expect(decode('\x1b[B')).toEqual([{ type: 'key', name: 'down' }]);
+    expect(decode('\x1b[C')).toEqual([{ type: 'key', name: 'right' }]);
+    expect(decode('\x1b[D')).toEqual([{ type: 'key', name: 'left' }]);
+    expect(decode('\x1b[H')).toEqual([{ type: 'key', name: 'home' }]);
+    expect(decode('\x1b[F')).toEqual([{ type: 'key', name: 'end' }]);
+  });
+
+  it('decodes the SS3 variants application-cursor mode sends', () => {
+    expect(decode('\x1bOA')).toEqual([{ type: 'key', name: 'up' }]);
+    expect(decode('\x1bOD')).toEqual([{ type: 'key', name: 'left' }]);
+    expect(decode('\x1bOH')).toEqual([{ type: 'key', name: 'home' }]);
+    expect(decode('\x1bOP')).toEqual([]);
+  });
+
+  it('decodes the numbered CSI keys', () => {
+    expect(decode('\x1b[2~')).toEqual([{ type: 'key', name: 'insert' }]);
+    expect(decode('\x1b[3~')).toEqual([{ type: 'key', name: 'delete' }]);
+    expect(decode('\x1b[5~')).toEqual([{ type: 'key', name: 'pageup' }]);
+    expect(decode('\x1b[6~')).toEqual([{ type: 'key', name: 'pagedown' }]);
+    expect(decode('\x1b[1~')).toEqual([{ type: 'key', name: 'home' }]);
+    expect(decode('\x1b[4~')).toEqual([{ type: 'key', name: 'end' }]);
+  });
+
+  it('ignores modifiers on an arrow rather than dropping the key', () => {
+    expect(decode('\x1b[1;5A')).toEqual([{ type: 'key', name: 'up' }]);
+  });
+
+  it('swallows unknown sequences instead of leaking them as text', () => {
+    expect(decode('\x1b[Z')).toEqual([]);
+    expect(decode('\x1b[999~')).toEqual([]);
+    expect(decode('\x1b[?1049h')).toEqual([]);
+    expect(decode('\x1b[200~hi\x1b[201~')).toEqual([
+      { type: 'char', value: 'h' },
+      { type: 'char', value: 'i' },
+    ]);
+  });
+
+  it('consumes the payload of an X10 mouse report', () => {
+    expect(decode('\x1b[M !!x')).toEqual([{ type: 'char', value: 'x' }]);
+  });
+
+  it('reads ESC followed by a letter as the Alt chord it is', () => {
+    // Changed deliberately: this used to decode as Escape + `x`, which made
+    // Alt+N unreachable. A lone Esc is still separable because it is HELD until
+    // the caller's timer flushes it (see the 'lone escape' suite).
+    expect(decode('\x1bx')).toEqual([{ type: 'alt', value: 'x' }]);
+  });
+});
+
+describe('lone escape', () => {
+  it('holds a trailing ESC until the caller flushes', () => {
+    const parser = createKeyParser();
+    expect(parser.feed('\x1b')).toEqual([]);
+    expect(parser.pending()).toBe(1);
+    expect(parser.flush()).toEqual([{ type: 'escape' }]);
+    expect(parser.pending()).toBe(0);
+  });
+
+  it('completes the sequence instead when the rest arrives', () => {
+    const parser = createKeyParser();
+    expect(parser.feed('\x1b')).toEqual([]);
+    expect(parser.feed('[A')).toEqual([{ type: 'key', name: 'up' }]);
+    expect(parser.flush()).toEqual([]);
+  });
+
+  it('turns a half-typed sequence into Escape plus its characters', () => {
+    const parser = createKeyParser();
+    expect(parser.feed('\x1b[')).toEqual([]);
+    expect(parser.flush()).toEqual([{ type: 'escape' }, { type: 'char', value: '[' }]);
+  });
+});
+
+describe('SGR mouse', () => {
+  it('decodes press and release with 1-based coordinates', () => {
+    expect(decode('\x1b[<0;12;34M')).toEqual([{ type: 'mouse', kind: 'press', x: 12, y: 34, button: 0 }]);
+    expect(decode('\x1b[<0;12;34m')).toEqual([{ type: 'mouse', kind: 'release', x: 12, y: 34, button: 0 }]);
+  });
+
+  it('decodes the wheel', () => {
+    expect(decode('\x1b[<64;3;4M')).toEqual([{ type: 'mouse', kind: 'wheel-up', x: 3, y: 4, button: 64 }]);
+    expect(decode('\x1b[<65;3;4M')).toEqual([{ type: 'mouse', kind: 'wheel-down', x: 3, y: 4, button: 65 }]);
+  });
+
+  it('swallows drag/motion reports', () => {
+    expect(decode('\x1b[<32;5;6M')).toEqual([]);
+  });
+
+  it('swallows a malformed report', () => {
+    expect(decode('\x1b[<0;12M')).toEqual([]);
+  });
+});
+
+describe('torn reads', () => {
+  const cases: Array<[string, TuiInputEvent[]]> = [
+    ['\x1b[A', [{ type: 'key', name: 'up' }]],
+    ['\x1b[6~', [{ type: 'key', name: 'pagedown' }]],
+    ['\x1b[<64;3;4M', [{ type: 'mouse', kind: 'wheel-up', x: 3, y: 4, button: 64 }]],
+    ['\x1bOB', [{ type: 'key', name: 'down' }]],
+    ['\x1b[1;5C', [{ type: 'key', name: 'right' }]],
+  ];
+
+  for (const [sequence, expected] of cases) {
+    it(`decodes ${JSON.stringify(sequence)} at every split position`, () => {
+      const bytes = Buffer.from(sequence, 'utf8');
+      for (let at = 0; at <= bytes.length; at++) {
+        expect(decodeSplit(bytes, at)).toEqual(expected);
+      }
+    });
+  }
+
+  it('decodes a mixed burst split anywhere', () => {
+    const bytes = Buffer.from('a\x1b[Bx\r\x1b[<65;1;1M', 'utf8');
+    const expected: TuiInputEvent[] = [
+      { type: 'char', value: 'a' },
+      { type: 'key', name: 'down' },
+      { type: 'char', value: 'x' },
+      { type: 'enter' },
+      { type: 'mouse', kind: 'wheel-down', x: 1, y: 1, button: 65 },
+    ];
+    for (let at = 0; at <= bytes.length; at++) {
+      expect(decodeSplit(bytes, at)).toEqual(expected);
+    }
+  });
+
+  it('drops a garbage burst whole instead of wedging or leaking it', () => {
+    const parser = createKeyParser();
+    expect(parser.feed(`\x1b[${'1'.repeat(200)}`)).toEqual([]);
+    expect(parser.pending()).toBe(0);
+    expect(parser.feed('\x1b[A')).toEqual([{ type: 'key', name: 'up' }]);
+  });
+});
+
+describe('Alt chords', () => {
+  it('reads ESC + a printable character in one read as Alt+that key', () => {
+    expect(decode('\x1b1')).toEqual([{ type: 'alt', value: '1' }]);
+    expect(decode('\x1bk')).toEqual([{ type: 'alt', value: 'k' }]);
+  });
+
+  it('never steals the sequence introducers, or every arrow key would break', () => {
+    // ESC [ is CSI and ESC O is SS3: both are Up, not Alt+[ / Alt+O.
+    expect(decode('\x1b[A')).toEqual([{ type: 'key', name: 'up' }]);
+    expect(decode('\x1bOA')).toEqual([{ type: 'key', name: 'up' }]);
+  });
+
+  it('leaves ESC ] alone, so a terminal colour reply is never read as a chord', () => {
+    // OSC introducer: decoded as Escape then `]`, exactly as before.
+    expect(decode('\x1b]')).toEqual([{ type: 'escape' }, { type: 'char', value: ']' }]);
+  });
+
+  it('keeps a lone ESC held, which is what separates it from a chord', () => {
+    const parser = createKeyParser();
+    expect(parser.feed('\x1b')).toEqual([]);
+    expect(parser.flush()).toEqual([{ type: 'escape' }]);
+  });
+
+  it('decodes a chord torn across two reads as Escape then the character', () => {
+    // The unavoidable ambiguity, resolved the standard way: same read = chord.
+    const parser = createKeyParser();
+    expect(parser.feed('\x1b')).toEqual([]);
+    expect(parser.flush()).toEqual([{ type: 'escape' }]);
+    expect(parser.feed('1')).toEqual([{ type: 'char', value: '1' }]);
+  });
+});

test/tui/tui-layout.test.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Unit tests for the responsive layout math.
+ *
+ * Two things are pinned here because the renderer trusts them blindly: the
+ * regions tile the screen exactly (no gaps, no overlap, full coverage), and no
+ * region is ever negative, however small or absurd the terminal gets.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  computeLayout,
+  needsBanner,
+  NARROW_BREAKPOINT,
+  SIDEBAR_MAX_WIDTH,
+  SIDEBAR_MIN_WIDTH,
+  type TuiLayout,
+} from '../../src/tui/tui-layout.js';
+
+function rects(layout: TuiLayout) {
+  return [layout.header, layout.banner, layout.body, layout.list, layout.divider, layout.preview, layout.footer];
+}
+
+function expectSane(layout: TuiLayout): void {
+  for (const rect of rects(layout)) {
+    if (!rect) continue;
+    expect(rect.width).toBeGreaterThanOrEqual(0);
+    expect(rect.height).toBeGreaterThanOrEqual(0);
+    expect(rect.row).toBeGreaterThanOrEqual(1);
+    expect(rect.col).toBeGreaterThanOrEqual(1);
+    expect(rect.col + rect.width - 1).toBeLessThanOrEqual(Math.max(1, layout.cols));
+    if (rect.height > 0) expect(rect.row + rect.height - 1).toBeLessThanOrEqual(layout.rows);
+  }
+  expect(layout.header.height + layout.body.height + layout.footer.height).toBe(layout.rows);
+}
+
+describe('computeLayout', () => {
+  it('stacks header, body and footer with no gap', () => {
+    const layout = computeLayout(100, 30);
+    expect(layout.header).toEqual({ row: 1, col: 1, width: 100, height: 1 });
+    expect(layout.body.row).toBe(2);
+    expect(layout.body.height).toBe(28);
+    expect(layout.footer).toEqual({ row: 30, col: 1, width: 100, height: 1 });
+    expectSane(layout);
+  });
+
+  it('splits a wide body into sidebar, divider and preview covering every column', () => {
+    const layout = computeLayout(100, 30);
+    expect(layout.narrow).toBe(false);
+    expect(layout.rowHeight).toBe(1);
+    expect(layout.list.width).toBe(36);
+    expect(layout.divider).toEqual({ row: 2, col: 37, width: 1, height: 28 });
+    expect(layout.preview).toEqual({ row: 2, col: 38, width: 63, height: 28 });
+    expect(layout.list.width + 1 + (layout.preview?.width ?? 0)).toBe(layout.cols);
+  });
+
+  it('clamps the sidebar at both ends', () => {
+    expect(computeLayout(NARROW_BREAKPOINT, 30).list.width).toBe(SIDEBAR_MIN_WIDTH);
+    expect(computeLayout(200, 30).list.width).toBe(SIDEBAR_MAX_WIDTH);
+    expect(computeLayout(400, 30).list.width).toBe(SIDEBAR_MAX_WIDTH);
+  });
+
+  it('drops the preview and doubles the row height below the breakpoint', () => {
+    const narrow = computeLayout(NARROW_BREAKPOINT - 1, 24);
+    expect(narrow.narrow).toBe(true);
+    expect(narrow.rowHeight).toBe(2);
+    expect(narrow.preview).toBeNull();
+    expect(narrow.divider).toBeNull();
+    expect(narrow.list.width).toBe(NARROW_BREAKPOINT - 1);
+    expect(computeLayout(NARROW_BREAKPOINT, 24).narrow).toBe(false);
+    expectSane(narrow);
+  });
+
+  it('carves the banner out of the top of the body when asked', () => {
+    const plain = computeLayout(100, 30);
+    const banner = computeLayout(100, 30, { banner: true });
+    expect(plain.banner).toBeNull();
+    expect(banner.banner).toEqual({ row: 2, col: 1, width: 100, height: 1 });
+    expect(banner.body.height).toBe(plain.body.height);
+    expect(banner.list.row).toBe(plain.list.row + 1);
+    expect(banner.list.height).toBe(plain.list.height - 1);
+    expectSane(banner);
+  });
+
+  it('degrades on a tiny terminal without producing negative sizes', () => {
+    for (const [cols, rows] of [
+      [5, 5],
+      [1, 1],
+      [1, 2],
+      [3, 3],
+      [80, 2],
+      [80, 1],
+    ] as const) {
+      const layout = computeLayout(cols, rows, { banner: true });
+      expectSane(layout);
+      // The shape is width-driven, never height-driven: an 80x1 terminal is
+      // still a wide one, it just has nowhere to put the body.
+      expect(layout.narrow).toBe(cols < NARROW_BREAKPOINT);
+    }
+    const one = computeLayout(1, 1);
+    expect(one.body.height).toBe(0);
+    expect(one.footer.height).toBe(0);
+    const two = computeLayout(40, 2);
+    expect(two.body.height).toBe(0);
+    expect(two.banner).toBeNull();
+    expect(two.footer.height).toBe(1);
+  });
+
+  it('clamps nonsense dimensions to one cell', () => {
+    for (const [cols, rows] of [
+      [0, 0],
+      [-10, -10],
+      [Number.NaN, Number.NaN],
+    ] as const) {
+      const layout = computeLayout(cols, rows);
+      expect(layout.cols).toBe(1);
+      expect(layout.rows).toBe(1);
+      expectSane(layout);
+    }
+  });
+
+  it('floors fractional dimensions', () => {
+    expect(computeLayout(100.9, 30.9).cols).toBe(100);
+    expect(computeLayout(100.9, 30.9).rows).toBe(30);
+  });
+});
+
+describe('needsBanner', () => {
+  it('is the caller-side rule for reserving the banner row', () => {
+    expect(needsBanner('connected')).toBe(false);
+    expect(needsBanner('reconnecting')).toBe(true);
+    expect(needsBanner('degraded')).toBe(true);
+    expect(needsBanner('down')).toBe(true);
+  });
+});

test/tui/tui-model.test.ts

@@ -0,0 +1,402 @@
+/**
+ * @fileoverview Unit tests for TUI classification, grouping and the cursor.
+ *
+ * Rows are built in the shape `GET /api/sessions/unified` really returns
+ * (`UnifiedSessionItem`, `sources` and all), and approvals in the shape the
+ * approvals inbox really emits, so a change to either surface breaks these
+ * tests rather than the dashboard.
+ */
+import { describe, it, expect } from 'vitest';
+import type { ApprovalItem } from '../../src/web/approval-inbox.js';
+import type { SearchResultGroup } from '../../src/types/search.js';
+import { createComposer } from '../../src/tui/tui-composer.js';
+import {
+  buildRows,
+  buildSearchEntries,
+  classifySession,
+  createTuiModel,
+  firstSearchIndex,
+  flattenRows,
+  groupSessions,
+  mergeSessionRow,
+  moveSearchIndex,
+} from '../../src/tui/tui-model.js';
+import type { TuiSessionRow } from '../../src/tui/tui-types.js';
+
+const NOW = 1_700_000_000_000;
+
+function session(overrides: Partial<TuiSessionRow> & { sessionId: string }): TuiSessionRow {
+  return {
+    sources: ['live'],
+    name: overrides.sessionId,
+    mode: 'claude',
+    status: 'idle',
+    workingDir: '/home/dev/case',
+    createdAt: NOW - 60_000,
+    lastActivityAt: NOW - 60_000,
+    ...overrides,
+  };
+}
+
+function approval(overrides: Partial<ApprovalItem> & { sessionId: string }): ApprovalItem {
+  return {
+    id: `${overrides.sessionId}:1`,
+    sessionName: overrides.sessionId,
+    kind: 'permission',
+    createdAt: NOW - 30_000,
+    ...overrides,
+  };
+}
+
+function approvalMap(items: ApprovalItem[]): Map<string, ApprovalItem> {
+  return new Map(items.map((item) => [item.sessionId, item]));
+}
+
+describe('classifySession', () => {
+  it('classifies live sessions by status', () => {
+    expect(classifySession(session({ sessionId: 'a', status: 'busy' }))).toBe('working');
+    expect(classifySession(session({ sessionId: 'a', status: 'idle', isWorking: true }))).toBe('working');
+    expect(classifySession(session({ sessionId: 'a', status: 'idle' }))).toBe('idle');
+    expect(classifySession(session({ sessionId: 'a', status: 'stopped' }))).toBe('idle');
+  });
+
+  it('puts an errored session in the needs-you tier', () => {
+    expect(classifySession(session({ sessionId: 'a', status: 'error' }))).toBe('waiting');
+  });
+
+  it('classifies by the pending prompt, which outranks a stale busy status', () => {
+    const row = session({ sessionId: 'a', status: 'busy' });
+    expect(classifySession(row, approval({ sessionId: 'a', kind: 'permission' }))).toBe('blocked-permission');
+    expect(classifySession(row, approval({ sessionId: 'a', kind: 'question' }))).toBe('blocked-question');
+    expect(classifySession(row, approval({ sessionId: 'a', kind: 'idle' }))).toBe('waiting');
+  });
+
+  it('classifies a row the server no longer has live as history', () => {
+    expect(classifySession(session({ sessionId: 'a', sources: ['history'], status: 'busy' }))).toBe('recent');
+    expect(classifySession(session({ sessionId: 'a', sources: ['persisted', 'lifecycle'] }))).toBe('recent');
+    expect(classifySession(session({ sessionId: 'a', sources: ['history', 'live'] }))).toBe('idle');
+  });
+});
+
+describe('groupSessions', () => {
+  it('always returns the four groups in display order', () => {
+    expect(groupSessions([]).map((group) => group.key)).toEqual(['needs-you', 'working', 'idle', 'recent']);
+    expect(groupSessions([]).map((group) => group.label)).toEqual(['NEEDS YOU', 'WORKING', 'IDLE', 'RECENT']);
+  });
+
+  it('orders NEEDS YOU by how long each has been blocked, longest first', () => {
+    const sessions = [session({ sessionId: 'fresh' }), session({ sessionId: 'old' }), session({ sessionId: 'middle' })];
+    const approvals = approvalMap([
+      approval({ sessionId: 'fresh', createdAt: NOW - 5_000 }),
+      approval({ sessionId: 'old', createdAt: NOW - 900_000, kind: 'idle' }),
+      approval({ sessionId: 'middle', createdAt: NOW - 60_000, kind: 'question' }),
+    ]);
+    const groups = groupSessions(buildRows(sessions, approvals));
+    expect(groups[0].rows.map((row) => row.session.sessionId)).toEqual(['old', 'middle', 'fresh']);
+  });
+
+  it('orders WORKING by turn start, longest-running first', () => {
+    const sessions = [
+      session({ sessionId: 'short', status: 'busy', lastSubmitAt: NOW - 10_000, lastActivityAt: NOW }),
+      session({ sessionId: 'long', status: 'busy', lastSubmitAt: NOW - 3_600_000, lastActivityAt: NOW }),
+      session({ sessionId: 'nosubmit', status: 'busy', createdAt: NOW - 500, lastActivityAt: NOW }),
+    ];
+    const groups = groupSessions(buildRows(sessions));
+    expect(groups[1].rows.map((row) => row.session.sessionId)).toEqual(['long', 'short', 'nosubmit']);
+  });
+
+  it('orders IDLE and RECENT newest first', () => {
+    const sessions = [
+      session({ sessionId: 'i-old', lastActivityAt: NOW - 900_000 }),
+      session({ sessionId: 'i-new', lastActivityAt: NOW - 1_000 }),
+      session({ sessionId: 'h-old', sources: ['history'], lastActivityAt: NOW - 86_400_000 }),
+      session({ sessionId: 'h-new', sources: ['history'], lastActivityAt: NOW - 3_600_000 }),
+    ];
+    const groups = groupSessions(buildRows(sessions));
+    expect(groups[2].rows.map((row) => row.session.sessionId)).toEqual(['i-new', 'i-old']);
+    expect(groups[3].rows.map((row) => row.session.sessionId)).toEqual(['h-new', 'h-old']);
+  });
+
+  it('caps RECENT', () => {
+    const sessions = Array.from({ length: 20 }, (_, i) =>
+      session({ sessionId: `h${i}`, sources: ['history'], lastActivityAt: NOW - i * 1000 })
+    );
+    expect(groupSessions(buildRows(sessions))[3].rows).toHaveLength(8);
+    expect(groupSessions(buildRows(sessions), { recentLimit: 3 })[3].rows.map((r) => r.session.sessionId)).toEqual([
+      'h0',
+      'h1',
+      'h2',
+    ]);
+    expect(groupSessions(buildRows(sessions), { recentLimit: 0 })[3].rows).toEqual([]);
+  });
+
+  it('sorts deterministically when the anchors tie', () => {
+    const sessions = [
+      session({ sessionId: 'b', lastActivityAt: NOW }),
+      session({ sessionId: 'a', lastActivityAt: NOW }),
+    ];
+    expect(groupSessions(buildRows(sessions))[2].rows.map((row) => row.session.sessionId)).toEqual(['a', 'b']);
+  });
+
+  it('sorts an unknown anchor last in both directions', () => {
+    const withAnchor = session({ sessionId: 'known', lastActivityAt: NOW - 1000 });
+    const without = session({ sessionId: 'unknown', lastActivityAt: undefined, createdAt: undefined });
+    const idle = groupSessions(buildRows([without, withAnchor]))[2];
+    expect(idle.rows.map((row) => row.session.sessionId)).toEqual(['known', 'unknown']);
+  });
+});
+
+describe('mergeSessionRow', () => {
+  it('keeps fields the incoming row does not carry', () => {
+    const existing = session({ sessionId: 'a', firstPrompt: 'hello', inputTokens: 10 });
+    const merged = mergeSessionRow(existing, { sessionId: 'a', sources: ['live'], status: 'busy' });
+    expect(merged.firstPrompt).toBe('hello');
+    expect(merged.inputTokens).toBe(10);
+    expect(merged.status).toBe('busy');
+  });
+
+  it('lets a session lose its live source when the server drops it', () => {
+    const existing = session({ sessionId: 'a', sources: ['live', 'persisted'] });
+    const merged = mergeSessionRow(existing, { sessionId: 'a', sources: ['history'] });
+    expect(merged.sources).toEqual(['history']);
+    expect(classifySession(merged)).toBe('recent');
+  });
+});
+
+describe('the store', () => {
+  it('selects the first row as soon as there is one', () => {
+    const model = createTuiModel();
+    expect(model.selectedSession()).toBeNull();
+    model.replaceSessions([session({ sessionId: 'a' }), session({ sessionId: 'b' })]);
+    expect(model.selectedId).toBe(model.rows()[0].session.sessionId);
+  });
+
+  it('moves the cursor over rows only, wrapping at both ends', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      session({ sessionId: 'needs' }),
+      session({ sessionId: 'work', status: 'busy', lastSubmitAt: NOW - 1000 }),
+      session({ sessionId: 'idle' }),
+      session({ sessionId: 'past', sources: ['history'] }),
+    ]);
+    model.setApprovals([approval({ sessionId: 'needs' })]);
+    // One row per group: the cursor must cross the group headers without stopping.
+    expect(model.rows().map((row) => row.session.sessionId)).toEqual(['needs', 'work', 'idle', 'past']);
+
+    model.select('needs');
+    model.moveCursor(1);
+    expect(model.selectedId).toBe('work');
+    model.moveCursor(-1);
+    expect(model.selectedId).toBe('needs');
+    model.moveCursor(-1);
+    expect(model.selectedId).toBe('past');
+    model.moveCursor(1);
+    expect(model.selectedId).toBe('needs');
+  });
+
+  it('jumps by 1-based index and refuses one that is off the list', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      session({ sessionId: 'a', lastActivityAt: NOW }),
+      session({ sessionId: 'b', lastActivityAt: NOW - 1 }),
+      session({ sessionId: 'c', lastActivityAt: NOW - 2 }),
+    ]);
+    expect(model.cursorToIndex(3)).toBe(true);
+    expect(model.selectedId).toBe('c');
+    expect(model.cursorToIndex(9)).toBe(false);
+    expect(model.selectedId).toBe('c');
+    expect(model.cursorToIndex(0)).toBe(false);
+  });
+
+  it('keeps the selection on its session when the rows re-sort under it', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      session({ sessionId: 'a', lastActivityAt: NOW }),
+      session({ sessionId: 'b', lastActivityAt: NOW - 1000 }),
+    ]);
+    model.select('b');
+    expect(model.rows()[1].session.sessionId).toBe('b');
+
+    // b becomes blocked and jumps to the top of the list.
+    model.setApprovals([approval({ sessionId: 'b' })]);
+    expect(model.rows()[0].session.sessionId).toBe('b');
+    expect(model.selectedId).toBe('b');
+    expect(model.selectedSession()?.state).toBe('blocked-permission');
+  });
+
+  it('hands the cursor to whatever takes the place of a removed session', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      session({ sessionId: 'a', lastActivityAt: NOW }),
+      session({ sessionId: 'b', lastActivityAt: NOW - 1 }),
+      session({ sessionId: 'c', lastActivityAt: NOW - 2 }),
+    ]);
+    model.select('b');
+    model.removeSession('b');
+    expect(model.selectedId).toBe('c');
+    model.replaceSessions([session({ sessionId: 'a', lastActivityAt: NOW })]);
+    expect(model.selectedId).toBe('a');
+    model.replaceSessions([]);
+    expect(model.selectedId).toBeNull();
+    expect(model.selectedSession()).toBeNull();
+  });
+
+  it('merges an SSE update into the row it already has', () => {
+    const model = createTuiModel();
+    model.replaceSessions([session({ sessionId: 'a', firstPrompt: 'first thing' })]);
+    model.upsertSession({ sessionId: 'a', sources: ['live'], status: 'busy', inputTokens: 5 });
+    const row = model.rows()[0];
+    expect(row.state).toBe('working');
+    expect(row.session.firstPrompt).toBe('first thing');
+    expect(row.session.inputTokens).toBe(5);
+  });
+
+  it('counts only live sessions', () => {
+    const model = createTuiModel();
+    model.replaceSessions([
+      session({ sessionId: 'a' }),
+      session({ sessionId: 'b' }),
+      session({ sessionId: 'h', sources: ['history'] }),
+    ]);
+    expect(model.sessionCount).toBe(2);
+    expect(flattenRows(model.groups())).toHaveLength(3);
+  });
+
+  // Whether the typed text AUTHORIZES the kill is `confirmAccepts()` in
+  // tui-app, tested there; the store only carries what was typed.
+  it('tracks the confirm-kill overlay, keyed to the name it showed', () => {
+    const model = createTuiModel();
+    model.replaceSessions([session({ sessionId: 'a', name: 'w4-api' })]);
+    model.beginConfirmKill(model.rows()[0], 'w4-api');
+    expect(model.mode).toBe('confirm-kill');
+    // The name is the whole payload: it is what the dialog shows so the user
+    // knows WHICH session a `y` is about to destroy.
+    expect(model.confirm).toEqual({ sessionId: 'a', name: 'w4-api' });
+
+    // Regression: the label is supplied by the caller. Deriving it here with
+    // `name ?? id` let an EMPTY name through, and the dialog read "Kill ?".
+    model.replaceSessions([session({ sessionId: 'b', name: '' })]);
+    model.beginConfirmKill(model.rows()[0], 'mirofish');
+    expect(model.confirm?.name).toBe('mirofish');
+    model.closeOverlay();
+    expect(model.mode).toBe('list');
+    expect(model.confirm).toBeNull();
+  });
+
+  it('drops a session approval along with the session, and never resurrects it', () => {
+    const model = createTuiModel();
+    model.replaceSessions([session({ sessionId: 'a' })]);
+    model.setApprovals([approval({ sessionId: 'a' })]);
+    expect(model.rows()[0].approval).toBeDefined();
+    model.removeSession('a');
+    expect(model.rows()).toHaveLength(0);
+    // The same id coming back must not inherit the dead session's dialog.
+    model.upsertSession(session({ sessionId: 'a' }));
+    expect(model.rows()[0].approval).toBeUndefined();
+    expect(model.rows()[0].state).toBe('idle');
+  });
+});
+
+describe('the phase-2 overlays', () => {
+  it('gives one overlay the keyboard at a time and clears them together', () => {
+    const model = createTuiModel();
+    model.setPrompt({ sessionId: 'a', label: 'w4-api', composer: createComposer('hi') });
+    expect(model.mode).toBe('prompt');
+    model.setSearch({ composer: createComposer(), query: '', entries: [], index: -1, status: 'idle' });
+    expect(model.mode).toBe('search');
+    model.setDigest({ title: 'Away digest', lines: ['a', 'b'], offset: 0 });
+    expect(model.mode).toBe('digest');
+    model.closeOverlay();
+    expect(model.mode).toBe('list');
+    expect([model.prompt, model.search, model.digest]).toEqual([null, null, null]);
+  });
+
+  it('keeps the composer pointed at its session while the text changes', () => {
+    const model = createTuiModel();
+    model.setPrompt({ sessionId: 'a', label: 'w4-api', composer: createComposer() });
+    const revision = model.revision;
+    model.updatePrompt(createComposer('deploy'));
+    expect(model.prompt?.sessionId).toBe('a');
+    expect(model.revision).toBeGreaterThan(revision);
+  });
+
+  it('scrolls the digest without running off either end', () => {
+    const model = createTuiModel();
+    model.setDigest({ title: 'Away digest', lines: Array.from({ length: 10 }, (_, i) => `line ${i}`), offset: 0 });
+    model.scrollDigest(3, 4);
+    expect(model.digest?.offset).toBe(3);
+    model.scrollDigest(100, 4);
+    expect(model.digest?.offset).toBe(6);
+    model.scrollDigest(-100, 4);
+    expect(model.digest?.offset).toBe(0);
+  });
+});
+
+describe('search results', () => {
+  const groups: SearchResultGroup[] = [
+    {
+      type: 'session',
+      results: [
+        {
+          type: 'session',
+          sessionId: 'live-1',
+          sessionName: 'w1-alpha',
+          timestamp: NOW,
+          snippet: 'w1-alpha — /tmp/alpha',
+          exactMatch: true,
+          jumpTo: { kind: 'session', sessionId: 'live-1' },
+        },
+        {
+          type: 'session',
+          sessionId: 'past-1',
+          sessionName: 'w9-old',
+          timestamp: NOW - 1000,
+          snippet: '/tmp/old',
+          exactMatch: false,
+          jumpTo: { kind: 'resume-session', sessionId: 'past-1' },
+        },
+      ],
+    },
+    {
+      type: 'file',
+      results: [
+        {
+          type: 'file',
+          sessionId: 'live-1',
+          sessionName: 'w1-alpha',
+          timestamp: NOW,
+          snippet: 'notes.md',
+          exactMatch: false,
+          jumpTo: { kind: 'file-preview', sessionId: 'live-1', relativePath: 'docs/notes.md' },
+        },
+      ],
+    },
+  ];
+
+  it('flattens the typed groups into headers and rows', () => {
+    const entries = buildSearchEntries(groups, (id) => id === 'live-1');
+    expect(entries.map((entry) => entry.kind)).toEqual(['header', 'result', 'result', 'header', 'result']);
+    expect(entries[0].text).toBe('SESSIONS');
+    expect(entries[1]).toMatchObject({ text: 'w1-alpha', sessionId: 'live-1', live: true });
+    // The snippet opens with the session name, which the row already shows.
+    expect(entries[1].detail).toBe('/tmp/alpha');
+    // A session that is not on the list cannot be selected into.
+    expect(entries[2]).toMatchObject({ text: 'w9-old', live: false });
+    expect(entries[4]).toMatchObject({ text: 'docs/notes.md', live: false });
+  });
+
+  it('drops an empty group instead of printing a header with nothing under it', () => {
+    expect(buildSearchEntries([{ type: 'event', results: [] }], () => false)).toEqual([]);
+  });
+
+  it('starts on the first result and never lands on a header', () => {
+    const entries = buildSearchEntries(groups, () => true);
+    expect(firstSearchIndex(entries)).toBe(1);
+    expect(moveSearchIndex(entries, 1, 1)).toBe(2);
+    expect(moveSearchIndex(entries, 2, 1)).toBe(4);
+    // Both ends stop rather than wrap: a result list is read, not cycled.
+    expect(moveSearchIndex(entries, 4, 1)).toBe(4);
+    expect(moveSearchIndex(entries, 1, -1)).toBe(1);
+    expect(firstSearchIndex([])).toBe(-1);
+  });
+});

test/tui/tui-render.test.ts

@@ -0,0 +1,684 @@
+/**
+ * @fileoverview Unit tests for the frame renderer.
+ *
+ * The structural expectations below are full frames with the escapes stripped,
+ * which is what makes a layout regression readable in a diff; the escape
+ * sequences themselves are asserted separately, including the promise that
+ * NO_COLOR leaves nothing but cursor addressing behind.
+ */
+import { describe, it, expect } from 'vitest';
+import { charWidth, stripStyles, toDisplayLines, visibleWidth } from '../../src/tui/tui-ansi.js';
+import { composerMove, createComposer } from '../../src/tui/tui-composer.js';
+import { computeLayout, needsBanner } from '../../src/tui/tui-layout.js';
+import { createTuiModel, type TuiModelStore } from '../../src/tui/tui-model.js';
+import {
+  composerCursorCell,
+  detectGlyphTier,
+  digestCapacity,
+  formatElapsed,
+  formatPlanUsage,
+  formatTokens,
+  glyphsFor,
+  renderFrame,
+  rowLabel,
+  type TuiRenderOptions,
+} from '../../src/tui/tui-render.js';
+
+const NOW = 1_700_000_000_000;
+
+const PLAIN: TuiRenderOptions = { color: false, glyphs: 'unicode', tick: 4, now: NOW };
+
+function fixture(): TuiModelStore {
+  const model = createTuiModel();
+  model.setHeader({ hostname: 'tnode', version: '1.19.0', planUsage: '5h 32% wk 61%' });
+  model.replaceSessions([
+    {
+      sessionId: 'aaa1',
+      name: 'w4-api-refactor',
+      mode: 'claude',
+      status: 'busy',
+      isWorking: true,
+      workingDir: '/home/dev/api',
+      createdAt: NOW - 9_000_000,
+      lastActivityAt: NOW - 1_000,
+      lastSubmitAt: NOW - 134_000,
+      inputTokens: 9_000,
+      outputTokens: 3_300,
+      sources: ['live', 'persisted'],
+    },
+    {
+      sessionId: 'bbb2',
+      name: 'w6-docs',
+      mode: 'claude',
+      status: 'idle',
+      workingDir: '/home/dev/docs',
+      createdAt: NOW - 8_000_000,
+      lastActivityAt: NOW - 660_000,
+      sources: ['live'],
+    },
+    {
+      sessionId: 'ccc3',
+      name: 'w1-codeman',
+      mode: 'claude',
+      status: 'busy',
+      isWorking: true,
+      workingDir: '/home/dev/codeman',
+      createdAt: NOW - 10_000_000,
+      lastActivityAt: NOW,
+      lastSubmitAt: NOW - 1_020_000,
+      inputTokens: 40_000,
+      outputTokens: 5_200,
+      sources: ['live'],
+    },
+    {
+      sessionId: 'ddd4',
+      name: 'w2-gallery',
+      mode: 'codex',
+      status: 'idle',
+      workingDir: '/home/dev/gallery',
+      createdAt: NOW - 6_000_000,
+      lastActivityAt: NOW - 7_200_000,
+      sources: ['live'],
+    },
+    {
+      sessionId: 'eee5',
+      firstPrompt: 'fix the release script',
+      workingDir: '/home/dev/api',
+      lastActivityAt: NOW - 3 * 86_400_000,
+      sources: ['history'],
+    },
+  ]);
+  model.setApprovals([
+    { id: 'bbb2:1', sessionId: 'bbb2', sessionName: 'w6-docs', kind: 'idle', createdAt: NOW - 680_000 },
+    {
+      id: 'aaa1:2',
+      sessionId: 'aaa1',
+      sessionName: 'w4-api-refactor',
+      kind: 'permission',
+      createdAt: NOW - 120_000,
+      toolName: 'Bash',
+      toolSummary: 'Bash(git push origin main)',
+      options: [
+        { n: 1, label: 'Yes' },
+        { n: 2, label: "Yes, don't ask again" },
+        { n: 3, label: 'No, tell Claude what to do' },
+      ],
+    },
+  ]);
+  model.select('aaa1');
+  model.setPreview({
+    sessionId: 'aaa1',
+    lines: toDisplayLines('\x1b[32mActualizing...\x1b[0m (2m 14s)\nrunning tests\n\x1b[31mwarning\x1b[0m here\n'),
+  });
+  return model;
+}
+
+function render(model: TuiModelStore, cols: number, rows: number, opts: Partial<TuiRenderOptions> = {}): string {
+  const layout = computeLayout(cols, rows, { banner: needsBanner(model.connection) });
+  return renderFrame(model, layout, { ...PLAIN, ...opts });
+}
+
+/** The frame as visible lines: escapes stripped, trailing padding trimmed. */
+function frameLines(frame: string): string[] {
+  return frame
+    .split(/\x1b\[\d+;1H/)
+    .slice(1)
+    .map((part) => stripStyles(part).trimEnd());
+}
+
+describe('renderFrame structure', () => {
+  it('paints the wide layout at 100x30', () => {
+    expect(frameLines(render(fixture(), 100, 30))).toEqual([
+      ' codeman  ▲ 2  tnode · v1.19.0 · 4 sessions · 5h 32% wk 61%                          ? help  q quit',
+      ' NEEDS YOU ─────────────────────────│ w4-api-refactor · claude · /home/dev/api · blocked',
+      '  1 w6-docs                    ! 11m│ ▲ requests: Bash(git push origin main)',
+      '▶ 2 w4-api-refactor       ▲ 2m 12.3k│   1. Yes',
+      " WORKING ───────────────────────────│   2. Yes, don't ask again",
+      '  3 w1-codeman           ▖ 17m 45.2k│   3. No, tell Claude what to do',
+      ' IDLE ──────────────────────────────│ y approve · n deny · digit chooses',
+      '  4 w2-gallery codex            ○ 2h│',
+      ' RECENT ────────────────────────────│ Actualizing... (2m 14s)',
+      '  5 fix the release script      ✔ 3d│ running tests',
+      '                                    │ warning here',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      '                                    │',
+      ' ↑↓ select · ↵ attach · 1-9 switch · y/n answer · p prompt · n new · x kill · / search · g digest ·',
+    ]);
+  });
+
+  it('paints the narrow two-line layout at 44x20', () => {
+    expect(frameLines(render(fixture(), 44, 20))).toEqual([
+      ' codeman  ▲ 2  tnode · v1.19.0 · 4 sessions',
+      ' NEEDS YOU ─────────────────────────────────',
+      '  1 w6-docs                            ! 11m',
+      '    /home/dev/docs',
+      '▶ 2 w4-api-refactor                     ▲ 2m',
+      '    /home/dev/api · 12.3k',
+      ' WORKING ───────────────────────────────────',
+      '  3 w1-codeman                         ▖ 17m',
+      '    /home/dev/codeman · 45.2k',
+      ' IDLE ──────────────────────────────────────',
+      '  4 w2-gallery codex                    ○ 2h',
+      '    /home/dev/gallery · codex',
+      ' RECENT ────────────────────────────────────',
+      '  5 fix the release script              ✔ 3d',
+      '    /home/dev/api',
+      '',
+      '',
+      '',
+      '',
+      ' ↑↓ select · ↵ attach · 1-9 switch · y/n ans',
+    ]);
+  });
+
+  it('addresses every line absolutely and erases its tail', () => {
+    const frame = render(fixture(), 100, 30);
+    const addresses = [...frame.matchAll(/\x1b\[(\d+);1H/g)].map((match) => Number(match[1]));
+    expect(addresses).toEqual(Array.from({ length: 30 }, (_, i) => i + 1));
+    expect(frame.split('\x1b[K')).toHaveLength(31);
+    expect(frame).not.toContain('\n');
+  });
+
+  it('never lets a line exceed the terminal width', () => {
+    for (const [cols, rows] of [
+      [100, 30],
+      [44, 20],
+      [72, 8],
+      [30, 6],
+    ] as const) {
+      for (const line of frameLines(render(fixture(), cols, rows))) {
+        expect(visibleWidth(line)).toBeLessThanOrEqual(cols);
+      }
+    }
+  });
+
+  it('is deterministic for identical inputs', () => {
+    expect(render(fixture(), 100, 30)).toBe(render(fixture(), 100, 30));
+  });
+
+  it('degrades to a header-only frame on a 5x5 terminal without throwing', () => {
+    expect(() => render(fixture(), 5, 5)).not.toThrow();
+    expect(frameLines(render(fixture(), 5, 5))).toHaveLength(5);
+  });
+});
+
+describe('color', () => {
+  it('paints states and chrome when color is on', () => {
+    const model = fixture();
+    model.select('eee5');
+    const frame = render(model, 100, 30, { color: true });
+    expect(frame).toContain('\x1b[32m▖');
+    expect(frame).toContain('\x1b[31m▲');
+    expect(frame).toContain('\x1b[33m!');
+    expect(frame).toContain('\x1b[1mcodeman');
+  });
+
+  it('paints the selected row as one inverse block with no styling inside it', () => {
+    // An inner reset would punch a hole in the highlight, so the selected row
+    // is built unpainted and wrapped instead.
+    const frame = render(fixture(), 100, 30, { color: true });
+    const highlighted = frame.split('\x1b[7m')[1]?.split('\x1b[0m')[0] ?? '';
+    expect(highlighted).toContain('w4-api-refactor');
+    expect(highlighted).toContain('▲');
+    expect(highlighted).not.toContain('\x1b[');
+  });
+
+  it('emits nothing but cursor addressing when color is off', () => {
+    const frame = render(fixture(), 100, 30, { color: false });
+    const withoutAddressing = frame.replace(/\x1b\[\d+;1H/g, '').replace(/\x1b\[K/g, '');
+    expect(withoutAddressing).not.toContain('\x1b');
+  });
+
+  it('strips the session own colors out of the preview under NO_COLOR', () => {
+    const model = fixture();
+    model.setPreview({ sessionId: 'aaa1', lines: toDisplayLines('\x1b[31mred tail\x1b[0m') });
+    expect(render(model, 100, 30, { color: false })).not.toContain('\x1b[31m');
+    expect(render(model, 100, 30, { color: true })).toContain('\x1b[31m');
+  });
+});
+
+describe('glyph tiers', () => {
+  it('falls back to bracketed ASCII tokens', () => {
+    const lines = frameLines(render(fixture(), 100, 30, { glyphs: 'ascii' }));
+    const list = lines.map((line) => line.split('|')[0]);
+    expect(list[2]).toContain('[w]');
+    expect(list[3]).toContain('[!]');
+    expect(list[5]).toContain('[*]');
+    expect(list[7]).toContain('[-]');
+    expect(list[9]).toContain('[v]');
+    expect(list[3].startsWith('>')).toBe(true);
+    expect(lines.join('')).not.toContain('▝');
+    expect(lines.join('')).not.toContain('─');
+  });
+
+  it('animates the working glyph with the tick, and cycles', () => {
+    const model = fixture();
+    const frames = [0, 1, 2, 3, 4, 5].map((tick) => frameLines(render(model, 100, 30, { tick }))[5]);
+    // Quadrant blocks, rotating. Four of them, so the tick wraps every four
+    // frames rather than every six.
+    expect(frames[0]).toContain('▖');
+    expect(frames[1]).toContain('▘');
+    expect(frames[2]).toContain('▝');
+    expect(frames[3]).toContain('▗');
+    expect(frames[4]).toBe(frames[0]);
+    expect(frames[5]).toBe(frames[1]);
+    expect(new Set(frames).size).toBe(4);
+  });
+
+  it('detects a tier from the environment', () => {
+    expect(detectGlyphTier({ TERM: 'xterm-256color', LANG: 'en_US.UTF-8' })).toBe('unicode');
+    expect(detectGlyphTier({ TERM: 'xterm-kitty', LANG: 'en_US.UTF-8' })).toBe('nerd');
+    expect(detectGlyphTier({ TERM: 'xterm-256color', TERM_PROGRAM: 'iTerm.app', LANG: 'en_US.UTF-8' })).toBe('nerd');
+    expect(detectGlyphTier({ TERM: 'xterm-256color', LANG: 'C' })).toBe('ascii');
+    expect(detectGlyphTier({ TERM: 'dumb' })).toBe('ascii');
+    expect(detectGlyphTier({})).toBe('ascii');
+    expect(detectGlyphTier({ TERM: 'xterm-kitty', LANG: 'en_US.UTF-8', CODEMAN_TUI_GLYPHS: 'ascii' })).toBe('ascii');
+  });
+});
+
+describe('overlays', () => {
+  it('draws the help box over the body', () => {
+    const model = fixture();
+    model.setMode('help');
+    const lines = frameLines(render(model, 100, 30));
+    expect(lines.join('\n')).toContain('┌ Keys ');
+    expect(lines.some((line) => line.includes('attach'))).toBe(true);
+    expect(lines[lines.length - 1]).toContain('close');
+  });
+
+  it('names what a kill would destroy, and asks for one key', () => {
+    const model = fixture();
+    model.beginConfirmKill(model.rows()[0], 'w6-docs');
+    const text = frameLines(render(model, 100, 30)).join('\n');
+    expect(text).toContain('Kill w6-docs?');
+    expect(text).toContain('press y to kill, any other key cancels');
+    // The name is the point of the dialog: it is what tells the user WHICH
+    // session a keystroke is about to destroy.
+    expect(text).not.toContain('Type the name to confirm');
+  });
+
+  it('draws a message box', () => {
+    const model = fixture();
+    model.setMessage({ text: 'session refused to start: tmux is not installed', tone: 'err' });
+    const text = frameLines(render(model, 100, 30)).join('\n');
+    expect(text).toContain('Error');
+    expect(text).toContain('tmux is not installed');
+  });
+
+  it('skips the overlay when the body is too small to hold a box', () => {
+    const model = fixture();
+    model.setMode('help');
+    expect(frameLines(render(model, 100, 4)).join('\n')).not.toContain('Keys');
+  });
+});
+
+describe('connection states', () => {
+  it('banners a degraded server and says the preview is gone', () => {
+    const model = fixture();
+    model.setConnection('degraded');
+    const lines = frameLines(render(model, 100, 30));
+    expect(lines[1]).toContain('server not running: attach only');
+    expect(lines.join('\n')).toContain('preview unavailable while the server is down');
+  });
+
+  it('banners reconnecting and down differently', () => {
+    const model = fixture();
+    model.setConnection('reconnecting');
+    expect(frameLines(render(model, 100, 30))[1]).toContain('reconnecting');
+    model.setConnection('down');
+    expect(frameLines(render(model, 100, 30))[1]).toContain('server unreachable');
+  });
+});
+
+describe('empty and partial states', () => {
+  it('shows the empty hint when there are no sessions', () => {
+    const model = createTuiModel();
+    const lines = frameLines(render(model, 100, 30));
+    expect(lines.join('\n')).toContain('No sessions. n to start one, q to quit.');
+    expect(lines[1]).not.toContain('NEEDS YOU');
+  });
+
+  it('says the preview is still loading when it belongs to another session', () => {
+    const model = fixture();
+    model.setPreview({ sessionId: 'bbb2', lines: ['other session'] });
+    const text = frameLines(render(model, 100, 30)).join('\n');
+    expect(text).toContain('loading preview…');
+    expect(text).not.toContain('other session');
+  });
+
+  it('surfaces a preview error instead of a stale tail', () => {
+    const model = fixture();
+    model.setPreview({ sessionId: 'aaa1', lines: [], error: 'terminal capture failed' });
+    expect(frameLines(render(model, 100, 30)).join('\n')).toContain('terminal capture failed');
+  });
+
+  it('scrolls the list so the selected row stays visible', () => {
+    const model = createTuiModel();
+    model.replaceSessions(
+      Array.from({ length: 30 }, (_, i) => ({
+        sessionId: `s${String(i).padStart(2, '0')}`,
+        name: `session-${String(i).padStart(2, '0')}`,
+        sources: ['live'],
+        status: 'idle',
+        lastActivityAt: NOW - i * 1000,
+      }))
+    );
+    model.select('s29');
+    const text = frameLines(render(model, 100, 12)).join('\n');
+    expect(text).toContain('session-29');
+    expect(text).not.toContain('session-00');
+  });
+});
+
+describe('formatting helpers', () => {
+  it('formats elapsed time compactly', () => {
+    expect(formatElapsed(0)).toBe('0s');
+    expect(formatElapsed(45_000)).toBe('45s');
+    expect(formatElapsed(11 * 60_000)).toBe('11m');
+    expect(formatElapsed(2 * 3_600_000)).toBe('2h');
+    expect(formatElapsed(3 * 86_400_000)).toBe('3d');
+    expect(formatElapsed(-1)).toBe('');
+    expect(formatElapsed(Number.NaN)).toBe('');
+  });
+
+  it('formats token counts compactly', () => {
+    expect(formatTokens(0)).toBe('');
+    expect(formatTokens(842)).toBe('842');
+    expect(formatTokens(45_200)).toBe('45.2k');
+    expect(formatTokens(45_000)).toBe('45k');
+    expect(formatTokens(1_200_000)).toBe('1.2M');
+  });
+
+  it('names a row the way the web history list does', () => {
+    expect(rowLabel({ sessionId: 'abcdef12', name: 'w1', sources: [] })).toBe('w1');
+    expect(rowLabel({ sessionId: 'abcdef12', firstPrompt: 'do the thing', sources: [] })).toBe('do the thing');
+    expect(rowLabel({ sessionId: 'abcdef12', firstPrompt: '(no content)', workingDir: '/a/b/case', sources: [] })).toBe(
+      'case'
+    );
+    expect(rowLabel({ sessionId: 'abcdef1234', sources: [] })).toBe('abcdef12');
+  });
+
+  it('names a LIVE pane after its case, never after scraped output', () => {
+    // Regression: a session started from the TUI before the user typed anything
+    // had no name and no prompt, so the fallback took the CLI's first line of
+    // output. A healthy new session showed up in the list called
+    // "Login interrupted", which reads like a failure.
+    expect(
+      rowLabel({
+        sessionId: 'abcdef12',
+        firstPrompt: 'Login interrupted',
+        workingDir: '/home/u/codeman-cases/mirofish',
+        muxName: 'codeman-abcdef12',
+        sources: [],
+      })
+    ).toBe('mirofish');
+  });
+
+  it('still names a HISTORY row by its prompt, where the prompt IS the identity', () => {
+    expect(
+      rowLabel({
+        sessionId: 'abcdef12',
+        firstPrompt: 'do the thing',
+        workingDir: '/home/u/codeman-cases/mirofish',
+        sources: [],
+      })
+    ).toBe('do the thing');
+  });
+
+  it('prefers a real name over both, on a live row and a history row alike', () => {
+    const base = { sessionId: 'abcdef12', firstPrompt: 'Login interrupted', workingDir: '/a/b/case', sources: [] };
+    expect(rowLabel({ ...base, name: 'w2-case' })).toBe('w2-case');
+    expect(rowLabel({ ...base, name: 'w2-case', muxName: 'codeman-abcdef12' })).toBe('w2-case');
+  });
+});
+
+describe('the approval card', () => {
+  it('draws the dialog above the tail, with its digits', () => {
+    const text = frameLines(render(fixture(), 100, 30)).join('\n');
+    expect(text).toContain('▲ requests: Bash(git push origin main)');
+    expect(text).toContain('1. Yes');
+    expect(text).toContain('3. No, tell Claude what to do');
+    expect(text).toContain('y approve · n deny · digit chooses');
+    // The tail is still there, below the card.
+    expect(text).toContain('Actualizing...');
+  });
+
+  it('paints a dialog red and a waiting prompt yellow', () => {
+    const model = fixture();
+    const frame = render(model, 100, 30, { color: true });
+    expect(frame).toContain('\x1b[31m ▲ requests');
+
+    model.select('bbb2');
+    const idle = render(model, 100, 30, { color: true });
+    expect(idle).toContain('\x1b[33m !');
+    expect(idle).toContain('p to reply');
+  });
+
+  it('never lets the card push the tail off the pane', () => {
+    const model = fixture();
+    const lines = frameLines(render(model, 100, 10));
+    // 8 body lines: the card gets at most half, so some tail survives.
+    expect(lines.join('\n')).toContain('warning here');
+  });
+
+  it('counts pending prompts in the header badge', () => {
+    expect(frameLines(render(fixture(), 100, 30))[0]).toContain('▲ 2');
+    const model = createTuiModel();
+    model.replaceSessions([{ sessionId: 'aaa1', name: 'w1', sources: ['live'], status: 'idle' }]);
+    expect(frameLines(render(model, 100, 30))[0]).not.toContain('▲');
+  });
+});
+
+describe('the preview title', () => {
+  it('names the session, its CLI, its directory and its state', () => {
+    expect(frameLines(render(fixture(), 100, 30))[1]).toContain('w4-api-refactor · claude · /home/dev/api · blocked');
+  });
+
+  it('sacrifices the path rather than the state word when the pane is narrow', () => {
+    const model = fixture();
+    model.setApprovals([]);
+    model.select('ccc3');
+    const title = frameLines(render(model, 80, 30))[1];
+    expect(title).toContain('w1-codeman');
+    expect(title).toContain('working');
+  });
+
+  it('says a history row has nothing to show rather than claiming to load it', () => {
+    const model = fixture();
+    model.select('eee5');
+    model.setPreview({ sessionId: 'eee5', lines: [], note: 'this session is not running: no live output to show' });
+    expect(frameLines(render(model, 100, 30)).join('\n')).toContain('no live output to show');
+  });
+});
+
+describe('the prompt composer', () => {
+  function composing(text: string, cursorAt?: number): TuiModelStore {
+    const model = fixture();
+    let composer = createComposer(text);
+    if (cursorAt !== undefined) composer = composerMove(composer, cursorAt - text.length);
+    model.setPrompt({ sessionId: 'aaa1', label: 'w4-api-refactor', composer });
+    return model;
+  }
+
+  it('replaces the footer keys with the line being typed', () => {
+    const lines = frameLines(render(composing('deploy the thing'), 100, 30));
+    expect(lines[lines.length - 1]).toBe(' > deploy the thing');
+  });
+
+  it('puts the terminal cursor where the caret is', () => {
+    const layout = computeLayout(100, 30);
+    expect(composerCursorCell(composing('abc'), layout)).toEqual({ row: 30, col: 7 });
+    expect(composerCursorCell(composing('abc', 1), layout)).toEqual({ row: 30, col: 5 });
+    // No composer, no cursor: a blinking cursor in a dashboard reads as a bug.
+    expect(composerCursorCell(fixture(), layout)).toBeNull();
+  });
+
+  it('scrolls a long line so the caret stays on screen', () => {
+    const long = 'x'.repeat(200);
+    const lines = frameLines(render(composing(long), 100, 30));
+    const footer = lines[lines.length - 1];
+    expect(visibleWidth(footer)).toBeLessThanOrEqual(100);
+    const cursor = composerCursorCell(composing(long), computeLayout(100, 30));
+    expect(cursor?.col).toBeLessThanOrEqual(100);
+  });
+});
+
+describe('the search overlay', () => {
+  function searching(): TuiModelStore {
+    const model = fixture();
+    model.setSearch({
+      composer: createComposer('alpha'),
+      query: 'alpha',
+      status: 'done',
+      note: '2 results',
+      index: 1,
+      entries: [
+        { kind: 'header', text: 'SESSIONS' },
+        { kind: 'result', text: 'w1-alpha', detail: '/tmp/alpha', sessionId: 'aaa1', live: true },
+        { kind: 'result', text: 'w9-old', detail: '/tmp/old', sessionId: 'zzz9', live: false },
+      ],
+    });
+    return model;
+  }
+
+  it('shows the query with a caret, the count and the rows', () => {
+    const text = frameLines(render(searching(), 100, 30)).join('\n');
+    expect(text).toContain('┌ Search ');
+    expect(text).toContain('alpha_');
+    expect(text).toContain('2 results');
+    expect(text).toContain('SESSIONS');
+    expect(text).toContain('▶ w1-alpha  /tmp/alpha');
+    expect(text).toContain('w9-old');
+  });
+
+  it('invites a query before anything has been typed', () => {
+    const model = fixture();
+    model.setSearch({ composer: createComposer(), query: '', entries: [], index: -1, status: 'idle' });
+    expect(frameLines(render(model, 100, 30)).join('\n')).toContain('type to search');
+  });
+});
+
+describe('the digest overlay', () => {
+  it('windows the lines it was given and scrolls with the offset', () => {
+    const model = fixture();
+    const lines = Array.from({ length: 40 }, (_, i) => `digest line ${i}`);
+    model.setDigest({ title: 'Away digest', lines, offset: 0 });
+    const top = frameLines(render(model, 100, 12)).join('\n');
+    expect(top).toContain('┌ Away digest ');
+    expect(top).toContain('digest line 0');
+    expect(top).not.toContain('digest line 30');
+
+    model.scrollDigest(30, digestCapacity(computeLayout(100, 12)));
+    const scrolled = frameLines(render(model, 100, 12)).join('\n');
+    expect(scrolled).toContain('digest line 30');
+    expect(scrolled).not.toContain('digest line 0\n');
+  });
+});
+
+describe('formatPlanUsage', () => {
+  it('mirrors the web chip, both windows and either alone', () => {
+    expect(
+      formatPlanUsage({ fiveHour: { usedPercentage: 32.4, resetAt: 1 }, sevenDay: { usedPercentage: 61, resetAt: 2 } })
+    ).toBe('5h 32% · wk 61%');
+    expect(formatPlanUsage({ fiveHour: { usedPercentage: 5, resetAt: 1 } })).toBe('5h 5%');
+    expect(formatPlanUsage({ sevenDay: { usedPercentage: 90, resetAt: 1 } })).toBe('wk 90%');
+  });
+
+  it('punctuates with the separator it is given, so an ASCII terminal gets none', () => {
+    const usage = { fiveHour: { usedPercentage: 32, resetAt: 1 }, sevenDay: { usedPercentage: 61, resetAt: 2 } };
+    expect(formatPlanUsage(usage, ' - ')).toBe('5h 32% - wk 61%');
+  });
+
+  it('is empty when there is nothing to report, so the header shows no placeholder', () => {
+    expect(formatPlanUsage(null)).toBe('');
+    expect(formatPlanUsage(undefined)).toBe('');
+    expect(formatPlanUsage({})).toBe('');
+  });
+});
+
+describe('the unicode glyph set is safe to render', () => {
+  // Two failures this pins, both found on one beta tester's terminal:
+  // a double-width glyph shifting every cell after it, and a codepoint their
+  // font had no glyph for at all.
+  const UNICODE = glyphsFor('unicode');
+  const every = [
+    UNICODE.blockedPermission,
+    UNICODE.blockedQuestion,
+    UNICODE.waiting,
+    ...UNICODE.working,
+    UNICODE.idle,
+    UNICODE.recent,
+    UNICODE.cursor,
+    UNICODE.rule,
+    UNICODE.divider,
+    UNICODE.boxTopLeft,
+    UNICODE.boxTopRight,
+    UNICODE.boxBottomLeft,
+    UNICODE.boxBottomRight,
+    UNICODE.boxHorizontal,
+    UNICODE.boxVertical,
+    UNICODE.enter,
+    UNICODE.updown,
+    UNICODE.separator,
+    UNICODE.ellipsis,
+  ];
+
+  it('has no double-width glyph, which would shift every cell after it', () => {
+    for (const glyph of every) {
+      for (const char of glyph) {
+        expect({ glyph, width: charWidth(char.codePointAt(0) ?? 0) }).toEqual({ glyph, width: 1 });
+      }
+    }
+  });
+
+  it('uses the arrow-block return symbol, not the one fonts lack', () => {
+    // U+23CE rendered as an empty box on a font that drew everything else here.
+    expect(UNICODE.enter).toBe('\u21B5');
+    expect(UNICODE.enter).not.toBe('\u23CE');
+  });
+
+  it('draws only from blocks a plain terminal font actually carries', () => {
+    // The rule, as a CLASS rather than one glyph at a time. Three separate
+    // "why are there boxes" reports came from this list, each fixed alone:
+    // ❯ (U+276F, sparse Dingbats), ⏵ (U+23F5) and ⏎ (U+23CE, both Misc
+    // Technical). The same font drew Box Drawing, Block Elements, Geometric
+    // Shapes and Latin-1 perfectly, so those are what the set may use.
+    const BANNED: Array<[number, number, string]> = [
+      [0x2300, 0x23ff, 'Miscellaneous Technical'],
+      [0x2600, 0x26ff, 'Miscellaneous Symbols'],
+      [0x2700, 0x27bf, 'Dingbats'],
+    ];
+    // U+2714 is the one Dingbat kept: it was observed rendering on the very
+    // font that failed the others, and it is the list's "done" mark.
+    const ALLOWED = new Set([0x2714]);
+    for (const glyph of every) {
+      for (const char of glyph) {
+        const cp = char.codePointAt(0) ?? 0;
+        if (ALLOWED.has(cp)) continue;
+        const banned = BANNED.find(([lo, hi]) => cp >= lo && cp <= hi);
+        expect({ glyph, block: banned?.[2] ?? null }).toEqual({ glyph, block: null });
+      }
+    }
+  });
+
+  it('has no emoji where a text glyph belongs', () => {
+    // U+270B is Wide AND emoji-presentation: it drew at emoji size mid-row.
+    expect(every.join('')).not.toContain('\u270B');
+  });
+});

test/tui/tui-sse.test.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Unit tests for the TUI's SSE wire decoding and reconnect math.
+ *
+ * The frames here are byte-for-byte what `sse-stream-manager.ts` writes
+ * (`event: <name>\ndata: <json>\n\n`, plus the `:pppp…` tunnel padding line),
+ * so a change to the server's writer breaks these tests rather than the
+ * dashboard.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  MAX_PENDING_BYTES,
+  SSE_MAX_BACKOFF_MS,
+  SseFrameParser,
+  approvalEventKind,
+  classifySseEvent,
+  sseBackoffDelay,
+} from '../../src/tui/tui-sse.js';
+
+/** Feed a whole stream one character at a time: every boundary is a split. */
+function feedByChar(parser: SseFrameParser, text: string) {
+  const frames = [];
+  for (const ch of text) frames.push(...parser.feed(ch));
+  return frames;
+}
+
+describe('SseFrameParser', () => {
+  it('decodes a plain named frame', () => {
+    const frames = new SseFrameParser().feed('event: session:created\ndata: {"id":"a"}\n\n');
+    expect(frames).toEqual([{ event: 'session:created', data: '{"id":"a"}' }]);
+  });
+
+  it('defaults the event name to message', () => {
+    expect(new SseFrameParser().feed('data: hello\n\n')).toEqual([{ event: 'message', data: 'hello' }]);
+  });
+
+  it('survives a frame split across every possible chunk boundary', () => {
+    const parser = new SseFrameParser();
+    const frames = feedByChar(
+      parser,
+      'event: session:updated\ndata: {"id":"b","n":1}\n\nevent: sse:heartbeat\ndata: {}\n\n'
+    );
+    expect(frames).toEqual([
+      { event: 'session:updated', data: '{"id":"b","n":1}' },
+      { event: 'sse:heartbeat', data: '{}' },
+    ]);
+  });
+
+  it('joins multi-line data with newlines and strips one leading space per line', () => {
+    const frames = new SseFrameParser().feed('event: x\ndata: line one\ndata: line two\ndata:  indented\n\n');
+    expect(frames).toEqual([{ event: 'x', data: 'line one\nline two\n indented' }]);
+  });
+
+  it('ignores comments, including the tunnel padding that trails a frame', () => {
+    const parser = new SseFrameParser();
+    const padding = ':' + 'p'.repeat(64) + '\n';
+    const frames = parser.feed(`event: a\ndata: 1\n\n${padding}event: b\ndata: 2\n\n`);
+    expect(frames).toEqual([
+      { event: 'a', data: '1' },
+      { event: 'b', data: '2' },
+    ]);
+  });
+
+  it('handles CRLF, including a CR that lands at the end of a chunk', () => {
+    const parser = new SseFrameParser();
+    expect(parser.feed('event: a\r')).toEqual([]);
+    expect(parser.feed('\ndata: 1\r\n\r\n')).toEqual([{ event: 'a', data: '1' }]);
+  });
+
+  it('treats a bare CR as a line end, once a following byte proves it is not half a CRLF', () => {
+    const parser = new SseFrameParser();
+    expect(parser.feed('event: a\rdata: 1\r\r')).toEqual([]);
+    expect(parser.feed('event: b\rdata: 2\r\r\n')).toEqual([
+      { event: 'a', data: '1' },
+      { event: 'b', data: '2' },
+    ]);
+  });
+
+  it('dispatches nothing for a frame with no data, and clears the event name', () => {
+    const parser = new SseFrameParser();
+    expect(parser.feed('event: a\n\n')).toEqual([]);
+    expect(parser.feed('data: 1\n\n')).toEqual([{ event: 'message', data: '1' }]);
+  });
+
+  it('carries id and retry when the server sends them', () => {
+    const frames = new SseFrameParser().feed('id: 7\nretry: 2500\nevent: a\ndata: 1\n\n');
+    expect(frames).toEqual([{ event: 'a', data: '1', id: '7', retry: 2500 }]);
+  });
+
+  it('accepts a field with no colon at all', () => {
+    // Per spec `data` alone means an empty data line, which still dispatches.
+    expect(new SseFrameParser().feed('data\n\n')).toEqual([{ event: 'message', data: '' }]);
+  });
+
+  it('drops a partial frame on reset so a reconnect cannot splice two streams', () => {
+    const parser = new SseFrameParser();
+    parser.feed('event: a\ndata: half');
+    parser.reset();
+    expect(parser.feed('data: whole\n\n')).toEqual([{ event: 'message', data: 'whole' }]);
+  });
+
+  it('discards a pending tail that grows past the guard', () => {
+    const parser = new SseFrameParser();
+    parser.feed('x'.repeat(MAX_PENDING_BYTES + 1));
+    expect(parser.feed('data: after\n\n')).toEqual([{ event: 'message', data: 'after' }]);
+  });
+});
+
+describe('classifySseEvent', () => {
+  it('routes the events the dashboard reacts to', () => {
+    expect(classifySseEvent('init')).toBe('init');
+    expect(classifySseEvent('sse:heartbeat')).toBe('heartbeat');
+    expect(classifySseEvent('approval:pending')).toBe('approval');
+    expect(classifySseEvent('approval:resolved')).toBe('approval');
+    expect(classifySseEvent('session:statusTelemetry')).toBe('plan-usage');
+    expect(classifySseEvent('session:created')).toBe('resync');
+    expect(classifySseEvent('session:deleted')).toBe('resync');
+    expect(classifySseEvent('mux:died')).toBe('resync');
+  });
+
+  it('ignores the high-volume and irrelevant families', () => {
+    // session:terminal is most of the stream and the preview pulls its own tail.
+    expect(classifySseEvent('session:terminal')).toBe('ignore');
+    expect(classifySseEvent('respawn:log')).toBe('ignore');
+    expect(classifySseEvent('subagent:progress')).toBe('ignore');
+    expect(classifySseEvent('something:invented')).toBe('ignore');
+  });
+});
+
+describe('approvalEventKind', () => {
+  it('names the three approval events and nothing else', () => {
+    expect(approvalEventKind('approval:pending')).toBe('pending');
+    expect(approvalEventKind('approval:updated')).toBe('updated');
+    expect(approvalEventKind('approval:resolved')).toBe('resolved');
+    expect(approvalEventKind('session:created')).toBeNull();
+  });
+});
+
+describe('sseBackoffDelay', () => {
+  it('doubles from the base and stops at the ceiling', () => {
+    expect(sseBackoffDelay(1)).toBe(500);
+    expect(sseBackoffDelay(2)).toBe(1000);
+    expect(sseBackoffDelay(3)).toBe(2000);
+    expect(sseBackoffDelay(6)).toBe(15_000);
+    expect(sseBackoffDelay(50)).toBe(SSE_MAX_BACKOFF_MS);
+  });
+
+  it('treats a zero or negative attempt as the first one', () => {
+    expect(sseBackoffDelay(0)).toBe(500);
+    expect(sseBackoffDelay(-4)).toBe(500);
+  });
+});