chore: version packages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.github/SECURITY.md

@@ -4,7 +4,7 @@ Codeman launches AI coding sessions with `--dangerously-skip-permissions`, so th
 web UI is **by design a remote-code-execution surface for whoever can reach it**.
 The entire security model exists to control *who* that is. Please read this before
 exposing an instance beyond `localhost`. The full model lives in
-[`docs/security-architecture.md`](docs/security-architecture.md).
+[`docs/security-architecture.md`](../docs/security-architecture.md).
 
 ## Supported versions
 
@@ -75,4 +75,4 @@ subscribe and send time), and tmux session names discovered on the shared socket
 are validated against the safe-name pattern before reaching any shell call site.
 
 For the detailed rationale, defenses, and recommended secure setups, see
-[`docs/security-architecture.md`](docs/security-architecture.md).
+[`docs/security-architecture.md`](../docs/security-architecture.md).

.github/workflows/release.yml

@@ -52,12 +52,20 @@ jobs:
           OLD_TAG="aicodeman@${VERSION}"
           NEW_TAG="codeman@${VERSION}"
 
-          # Update the GitHub release BEFORE deleting the old tag
+          # Update the GitHub release BEFORE deleting the old tag.
+          # make_latest pins the "Latest" badge to the Codeman release. This repo
+          # publishes TWO packages (aicodeman + xterm-zerolag-input), changesets
+          # creates a GitHub release for each, and GitHub awards "Latest" to
+          # whichever was published LAST. That is a race: 1.9.2 kept the badge,
+          # 1.9.4 lost it to xterm-zerolag-input@0.1.7 by two seconds. All package
+          # releases already exist by the time this step runs, so setting it here
+          # is deterministic.
           RELEASE_ID=$(gh release view "$OLD_TAG" --json databaseId -q .databaseId 2>/dev/null || true)
           if [ -n "$RELEASE_ID" ]; then
             gh api -X PATCH "repos/${{ github.repository }}/releases/${RELEASE_ID}" \
               -f tag_name="$NEW_TAG" \
-              -f name="$NEW_TAG"
+              -f name="$NEW_TAG" \
+              -f make_latest=true
           fi
 
           # Retag

.gitignore

@@ -68,6 +68,9 @@ design-explorations/
 # Artifacts that should not be tracked
 test-results/
 tmp/
+# Machine-local working files (never meant for git). ANCHORED so only the root
+# dir matches.
+/pr/
 # Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
 # with a leading slash so it does NOT also match src/web/public (a bare `public`
 # would swallow the whole web UI source dir and silently un-stage any new asset

.prettierignore

@@ -26,3 +26,6 @@ src/web/public/terminal-ui.js
 src/web/public/voice-input.js
 src/web/public/upload.html
 scripts/remotion/
+
+# Hand-maintained; Prettier escapes underscores in glob paths and corrupts paragraphs.
+CLAUDE.md

.prettierrc

@@ -1,8 +0,0 @@
-{
-  "singleQuote": true,
-  "semi": true,
-  "tabWidth": 2,
-  "printWidth": 120,
-  "trailingComma": "es5",
-  "endOfLine": "lf"
-}

CHANGELOG.md

@@ -1,5 +1,352 @@
 # aicodeman
 
+## 1.12.0
+
+### Minor Changes
+
+- Terminal scrollback overhaul (issue #205), fixing every reported scroll failure across shell and CLI sessions, desktop and mobile:
+  - Shell, OpenCode and Antigravity sessions finally have working scrollback: tmux's own client-side alternate-screen switch is stripped for tmux-backed sessions (narrow strip: alt-screen toggles only, keeping `clear`'s 3J and mouse DECSETs), so xterm stays in the normal buffer instead of a scrollback-less alt buffer where the wheel turned into shell history cycling and touch scrolling did nothing. Direct-PTY fallback sessions are untouched so fullscreen apps (vim/less/htop) keep the alt screen there.
+  - The wheel listener now runs in capture phase and owns the scroll: xterm's internal vscode-style viewport scroller consumed wheel events whenever local scrollback existed (and goes deaf entirely after a tab switch or replay resets the terminal), which silently killed wheel forwarding, made scrolling break after reload/tab switches, and let the CLI's input box scroll away. Local scrolling goes through buffer-level scrollLines and keeps working after resets; mouse-tracking apps and alternate-buffer sessions are passed through untouched.
+  - Wheel AND touch scrolling now forward to the CLI's own transcript for Codex and Claude 2.1.187+, at any scroll position (the viewport snaps home first), so the input box stays pinned on desktop and phones alike. Shift+wheel and the "Wheel scrolls local history" setting still pin local scrollback.
+  - Smooth scrolling: local wheel scrolling glides with an ease-out animation (fractional line accumulation, so slow trackpad drags track the finger instead of running ahead).
+  - Full tmux history on demand: the full-scrollback replay is now per session instead of once per page load, and scrolling up at the top of the buffer re-pulls the complete tmux history, recovering everything tmux's repaint bursts or tab switches removed from the browser's copy.
+  - Firefox wheel speed: wheel deltas are normalized by deltaMode (Firefox reports line units, previously read as pixels and slowed ~4x).
+  - Remote SSH Claude sessions now probe the CLI version over ssh (same connection options and login-shell wrapper as the real launch), so wheel forwarding works for them too instead of silently staying off.
+
+  Docs: scrollback analysis and fix plan recorded in docs/, architecture invariants updated (strip flavors, capture-phase wheel ownership, per-session full-history replay); docker agent-image rebuild warning and integration-guide link fixes from the preceding docs commits.
+
+## 1.11.2
+
+### Patch Changes
+
+- Make Antigravity (`agy`) a first-class CLI everywhere, and stop presenting Gemini CLI as a consumer product now that it is enterprise-only.
+
+  Antigravity was already wired into the session layer, schemas, run-mode menu and remote/Docker command maps, but the surfaces around it were never updated. Gemini keeps full support; Antigravity now sits beside it.
+
+  Fixes:
+  - **Docker cases with `mode: 'antigravity'` were broken.** `docker/agent.Dockerfile` installs its CLIs from npm, and `agy` is not an npm package, so the binary was never in the image and the container died on command-not-found. It now gets its own installer step. The `--dir /usr/local/bin` flag is load-bearing: the installer's default `$HOME/.local/bin` resolves to root's home at build time and would be unreachable by the `agent` user the container runs as. Note the binary is roughly 190MB, making it the largest layer in the image, so rebuild with `node scripts/build-agent-image.mjs` when convenient.
+  - **Welcome screen** gained a "Run Antigravity" action, gated on `agy` being present like the other CLI buttons, styled with the same cyan identity as the toolbar run button and run-mode dot.
+  - **`install.sh`** now detects `agy` (search paths mirroring `antigravity-cli-resolver.ts`), counts it as a satisfying AI CLI so an Antigravity-only box is not told it has none, and recommends it instead of Gemini in the install hints.
+
+  Documentation corrections where it had become factually wrong: `architecture-invariants.md` described `isExternalCliMode()` as opencode/codex/gemini when the code has included antigravity for some time, said "all three modes", and omitted `ANTIGRAVITY_*` from the env-prefix allowlist row; the `agentType` enum in `cron-guide.md`, `SessionMode` in `cron-discovery.md`, and `RemoteCommandMode` in `remote-sessions.md` were all stale.
+
+  Also updated both READMEs (five CLIs, Gemini marked enterprise-only), the `antigravity` npm keyword, and comment drift in eight places. Test coverage added for the new welcome button.
+
+  Antigravity stores its state under `~/.gemini/antigravity-cli/` rather than a `~/.antigravity` directory, so the existing `.gemini` Docker credential seed already covers it. That is now recorded in a code comment so no dead configuration gets added later.
+
+- b982c5d: Keep the brief Response Viewer output inside the same message card and Markdown wrapper used by the full conversation view, so opening the viewer without clicking More preserves the same readable formatting.
+
+## 1.11.1
+
+### Patch Changes
+
+- fix(history): Past Sessions data quality, and gate the phone run picker on CLI availability
+
+  **Past Sessions data quality (#215).** Three bugs in the transcript scanner behind
+  the Cmd+K Session Manager and the phone overview's PAST SESSIONS list:
+  - Automated/SDK-driven transcripts (CI review bots and other tooling, which Claude
+    Code stamps with a non-`cli` `entrypoint`) were listed alongside real interactive
+    sessions even though they were never resumable. They are now excluded. Detection
+    scans every entrypoint-bearing message rather than stopping at the first, so a
+    transcript that began under an older Claude Code build and only later picked up a
+    non-`cli` entrypoint is no longer wrongly hidden.
+  - A resumed session could show a same-directory sibling's preview text as its own.
+    The `workingDir` backfill in `mergeUnifiedSessions()` now only ever applies to rows
+    that have no history entry of their own, so it can no longer overwrite a row's real
+    content with another conversation's.
+  - Sessions restarted many times accumulated enough bookkeeping lines to push the real
+    first prompt past the scanner's 16KB head-read window, leaving a blank row. The read
+    is now two-tier: 16KB first, escalating to 128KB only when that was not enough, which
+    is both correct and cheaper than reading 128KB unconditionally (measured on a real
+    transcript tree: 36% fewer bytes read, roughly 17.5% faster than the unconditional
+    version). Also restores the tail-read fallback for a file whose head read failed
+    outright (for example `EMFILE` while scanning hundreds of files), which had been
+    silently dropping the session from history.
+
+  Follow-up hardening on top of the above: the automated-transcript exclusion now
+  blocklists the SDK entrypoint shape (`sdk`, `sdk-cli`, `sdk-py`) instead of allowlisting
+  the exact value `cli`. Because the check hides rows, an allowlist failed closed on any
+  value Claude Code has not shipped yet: a future rename of the interactive entrypoint,
+  or a second interactive host, would have blanked the entire Past Sessions list with
+  nothing in the UI to explain it. An unrecognized automated entrypoint now costs a few
+  noisy rows instead, which is the annoyance this filter set out to fix rather than a
+  broken feature.
+
+  **Phone overview run picker (#214).** The "C" logo home screen's Run picker listed all
+  six backends regardless of what was installed, so tapping an uninstalled one produced a
+  failed launch instead of the entry simply not being offered. It is now gated on
+  `isCliAvailable()` exactly like the desktop toolbar's run-mode dropdown (shell exempt,
+  since it has no external CLI dependency and keeps the menu from ever being empty). The
+  picker is a hardcoded duplicate of the toolbar menu rather than a shared render, which
+  is why it never picked up the earlier gating work; a test now asserts that every mode
+  the picker offers is gated, so a newly added backend cannot silently drift again.
+
+- 73315bc: fix(web): stop the Claude response viewer from following another session's conversation
+
+  The viewer re-derived a pane's live conversation by taking the newest
+  `~/.claude/history.jsonl` entry for the pane's cwd. A cwd is shared with every
+  other Codeman tab on it, with tabs long since closed, and with any plain
+  `claude` run in the user's own terminal, so the eye followed whichever of those
+  was typed into last — and the adoption was written back to the session, so the
+  mispin persisted. Entries are now credited to a pane only when they land within
+  10s of that pane's own Enter and no other pane on the cwd submitted closer, the
+  same last-submit correlation the Codex locator already uses.
+
+  That correlation also has to survive a restart. `start()` resets
+  `claudeSessionId` to the launch id even when re-attaching to a mux session whose
+  CLI has since moved on via `/clear`, so a recovered pane pointed the viewer at
+  its pre-`/clear` transcript — and with the anchor itself living only in memory,
+  nothing corrected it until the user happened to type again. `lastSubmitAt` is
+  now persisted in `SessionState` and restored on boot recovery, so the viewer
+  re-derives the live conversation on its first poll.
+
+## 1.11.0
+
+### Minor Changes
+
+- Two user-facing features since 1.10.0.
+
+  **Terminal: Ctrl+C copies the selection, interrupts when nothing is selected** (#211). Copying from the terminal previously worked only through the browser context menu: xterm turns Ctrl+C into 0x03 and cancels the keydown, so the muscle-memory copy failed silently and read as "no copy-paste at all". With a selection, Ctrl+C now copies it, shows the "Copied to clipboard" toast, clears the selection and sends nothing to the PTY; with no selection it falls through unchanged, so the interrupt is intact. Ctrl+Shift+C is an explicit copy chord that never interrupts. The shortcut is a normal registry entry (`copy-selection`), so it can be rebound or disabled in App Settings, and disabling it restores plain always-interrupt Ctrl+C. Copy goes through the Clipboard API with a hidden-textarea fallback, so it also works on plain-HTTP LAN installs.
+
+  **File Viewer: edit mode for text files** (#212). The file-preview overlay can now edit workspace text files in place, phone-first: `GET /api/sessions/:id/file-content?edit=1` reads for edit without the 500-line preview truncation (saving a truncated buffer would silently delete the rest) and returns a sha256 hash plus the detected EOL; `PUT /api/sessions/:id/file-content` saves. Edit-in-place only: there is no O_CREAT anywhere in the handler, so "never create, never delete" is structural. Confinement inherits the read path (realpath plus workspace boundary, ownership scoping) and adds sensitive-path and attachment-guard blocklists, a `.git/` subtree deny, and an extension allowlist (`svg` and `env` deliberately excluded). Optimistic concurrency is by content hash, so a file changed on disk mid-edit returns 409 with an overwrite option rather than clobbering. Writes are atomic (`wx` temp, fchmod, fsync, rename) which closes the validate-then-write TOCTOU window and cannot follow a pre-existing symlink. Binary and latin-1 content are refused via a NUL sniff plus a UTF-8 round-trip compare, and EOL is re-applied server-side so a textarea's LF normalization cannot turn a two-line edit of a CRLF file into a whole-file diff.
+
+## 1.10.0
+
+### Minor Changes
+
+- Codeman 1.10.0.
+
+  **Every surface that offers a CLI now checks the CLI is actually there** (#200, #201). The welcome-screen run buttons, the run-mode dropdown and the App Settings "Codex CLI" tab used to be shown unconditionally, so picking one on a box without the binary spawned a session that errored out immediately. All of them now gate on a single server-injected availability object covering Claude, OpenCode, Codex, Gemini, Antigravity and cloudflared, so nothing flickers in after paint and the dropdown costs no round trips to open. Shell is never gated, which is what keeps the menu non-empty on a box with nothing installed, and unknown availability reads as available so a stale page can never leave a working install with nothing to click. Adds `isClaudeAvailable()` and `GET /api/claude/status`, the one CLI that had no availability check despite being the default. The Cloudflare Tunnel welcome button and its scan-to-connect QR are gated on `cloudflared` rather than shown regardless.
+
+  **Shell and remote-SSH sessions now launch a real login shell** (#209, #210). Local shell tabs match what tmux itself does for a pane with no `default-command`, picking up the `/etc/profile` and `/etc/profile.d/*` entries a systemd `--user` service never sourced. On remote SSH, `claude`/`opencode`/`codex`/`gemini`/`agy` are routed through the remote user's interactive login shell, fixing agent CLIs that silently failed with "command not found" because ssh's remote-command execution sees only sshd's minimal default PATH and not the `~/.local/bin` or `~/.opencode/bin` entries where those CLIs actually live. Shell mode uses the remote user's real shell instead of hardcoded bash. The login flags are applied only to shells verified to accept them, so an exotic passwd entry (nushell, elvish, xonsh) cannot produce a dead pane on arrival.
+
+  **A crashed remote pane is kept for diagnosis** (#210), which is how the PATH failure above was found: it previously destroyed the pane, the window and the whole remote session on exit, tearing the local ssh attach down with it and leaving a flap loop with no evidence. Scoped to `remain-on-exit failed`, so a clean `exit` still tears the session down and only a non-zero exit strands anything, and applied last in the tmux command chain so a remote tmux older than 3.2 cannot drop the other session options with it.
+
+  **Resumed sessions under a hidden directory get the right working directory** (#202). Claude Code's project-key encoder maps both `/` and `.` to `-`, and the decoder could not reconstruct a dot-prefixed component, so every session under `~/.codeman` (or any project nested beneath any dotdir) silently resolved to bare `$HOME`. The wrong `workingDir` then propagated into `state.json` and everything trusting it: CLAUDE.md lookup, paste-image directory, subagent and image watchers. A same-named non-dot sibling could also produce a doubled-slash path that failed every later string comparison.
+
+  **Launching a session no longer wipes the terminal you are looking at** (#180). All six run modes route through the shared ownership helpers instead of clearing and writing into whatever session happened to be active, Antigravity included.
+
+  **Codex terminal animations are configurable** (#181), and the App Settings "Codex CLI" tab appears only where the `codex` binary resolves, since both settings on it are handed to `codex` at launch.
+
+## 1.9.9
+
+### Patch Changes
+
+- Two bug fixes.
+
+  **Plain shell sessions could not start when the server process had no `SHELL` (#208).** The tmux pane command for `mode: 'shell'` was the literal string `$SHELL`. That string is embedded in the `bash -c "..."` argument of the `respawn-pane` line, which is run through `/bin/sh -c`, so it was expanded by the _server_ process's shell against the _server_ process's environment rather than inside the pane. Containers and system-level systemd units do not set `SHELL`, so it expanded to nothing and the pane command ended in a dangling `&&`, giving `bash: -c: line 1: syntax error: unexpected end of file` and a pane that died instantly (status 2) while tmux session creation still reported success. The shell is now resolved in Node (`$SHELL`, then the passwd entry, then `/bin/bash`, `/bin/zsh`, `/bin/sh`), requiring an absolute path to an executable and skipping `nologin`-style stubs, then shell-quoted. Only local shell sessions were affected: agent CLI modes emit a real command, and Docker/remote-SSH cases already used a literal `exec bash -l`.
+
+  **A session name typed into the tab options could be silently dropped.** Two independent paths. In the Session Options modal, the Session Name input saves on blur while every autosave handler bails on a null `editingSessionId`, and `closeSessionOptions()` cleared that id before hiding the modal (hiding is what blurs the input), so the save always ran too late; Escape and backdrop-click lost the name with no PUT at all, and only the X button worked because mousedown blurs first. The focused modal field is now blurred before the id is cleared, which also covers the auto-compact prompt. Separately, the right-click inline rename could be destroyed mid-keystroke: the `_inlineRenameActive` guard was missing from `_renderSessionTabsImmediate()`, so a render queued just before the rename opened still rewrote the tab name's innerHTML, committing a truncated name or closing the rename outright. The debounced executor is now guarded too.
+
+## 1.9.8
+
+### Patch Changes
+
+- **Fixed: sessions failed to start on macOS with `Error: posix_spawnp failed.`** (issues #6 and #204)
+
+  `node-pty@1.1.0` publishes its macOS prebuilt helper as `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit. macOS launches every PTY through that helper, so a stock install failed on every session start. The bug is macOS-only: `spawn-helper` is a mac-only gyp target and node-pty ships no Linux prebuild, so Linux always compiles a correctly-permissioned helper from source.
+
+  The previous fix chmodded only `build/Release/spawn-helper`, which on macOS does not exist (the prebuild is used, so node-gyp never runs), and it derived that path from `require.resolve('node-pty')`, landing on `<pkg>/lib/build/Release/...`. It was a no-op on every platform.
+  - New `scripts/fix-node-pty.mjs` (also `npm run fix:node-pty`) chmods every `spawn-helper` it finds, in `build/Release`, `build/Debug` and each `prebuilds/*/`, then verifies the result by actually opening a PTY. A `require()` alone passes on a broken install, because the helper is only touched at spawn time.
+  - `postinstall` no longer force-rebuilds node-pty from source on Node 22+. That step needed Xcode command line tools, cost 30-120s on every install, and deleted the `prebuilds/` tree before compiling, so a Mac without a compiler was left with no working binary at all. A rebuild now happens only when the chmod plus spawn probe still fails, and the prebuilds tree is backed up and restored around it.
+  - New `spawnPtyWithHelperRepair()` (`src/utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts`, so an install that is already broken repairs itself on the first failed spawn and retries in-process instead of showing a dead session. Unrelated spawn errors are rethrown untouched; a second failure carries the `npm run fix:node-pty` hint.
+  - `scripts/fix-node-pty.mjs` is now in the published `files` list, so global npm installs get the repair too.
+  - Direct-PTY Claude spawns use the resolved absolute binary path (new `getClaudeBinaryPath()`) instead of the bare name `claude`, so a CLI installed outside the server's PATH still launches.
+
+  Verified end to end on macOS 26.4 arm64: a stock `npm i` reproduces `posix_spawnp failed.`, and after the fix the same install spawns a PTY successfully with the prebuilds preserved.
+
+  **Added: phone home screen (session overview)**
+
+  Under 430px the "C" logo now opens a session overview (current sessions, past sessions, spaces) instead of the welcome overlay: on a small screen "which session needs me" beats "how do I start one". Rows resume a session in place, and "New session here" goes through the normal quick-start path so remote and Docker cases keep their routing. Per-device setting `mobileOverviewEnabled` (phones only, default ON) in App Settings. Tablet and desktop are unchanged.
+
+  **Added: guided Tailscale setup in `install.sh`**
+
+  The network-access prompt is now 3-way: Tailscale, LAN, or local-only. The Tailscale path binds loopback and walks through installing Tailscale, logging in, the operator grant, the tailnet HTTPS-certificates toggle, and `tailscale serve --bg <port>`, then verifies the result end to end with curl. That gives HTTPS on a real certificate with no app password and no `0.0.0.0` bind, which is also what PWA install and web push need. `install.sh tailscale` retrofits it onto an existing install, and `CODEMAN_TAILSCALE=1` presets the choice. Serve state is detected from `tailscale serve status --json`; the installer never runs `tailscale serve reset` and never touches serve mappings other than 443 to Codeman's port. README and `docs/security-architecture.md` updated to match.
+
+  **Docs**: replaced a real tailnet hostname with placeholders in `docs/web-tabs-fixes-plan.md`.
+
+  **xterm-zerolag-input**: npm description and keywords only, no code change.
+
+## 1.9.7
+
+### Patch Changes
+
+- Antigravity run mode, plus opt-in entrance animations.
+
+  **Antigravity CLI backend (#207).** Antigravity (`agy`) joins Claude Code, shell, OpenCode, Codex and Gemini as a sixth session backend, following the same pluggable-resolver pattern: `utils/antigravity-cli-resolver.ts` resolves the CLI and `GET /api/antigravity/status` reports availability and path. `ANTIGRAVITY_*` is added to the `ALLOWED_ENV_PREFIXES` allowlist so env overrides stay CLI-scoped rather than blanket-forwarded. Like the other external CLIs it requires tmux with no direct PTY fallback, because secrets are injected through socket-scoped `tmux setenv` and never on the spawn command line. The UI gains a Run-dropdown entry, an agent-type option, an `ag` tab badge and toolbar colours; `runAntigravity()` routes remote and docker cases through `POST /api/quick-start` and skips the local status probe for them.
+
+  **Entrance animations (opt-in, OFF by default).** Optional animations for the four things that appear when work starts: session tabs, the terminal pane a session's CLI runs in, floating agent windows, and the connection lines tying a window back to its parent tab. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. Choose a look in App Settings > Appearance > Entrance Animations (per-device, stored in localStorage rather than the settings payload); `?animlab=1` opens a per-surface picker with a live preview that fakes tabs, a pane, a window and a line so styles can be compared without spawning sessions.
+
+  Three implementation notes worth knowing if you touch this: tabs and connection lines are destroyed mid-animation on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML, `_updateConnectionLinesImmediate()` clears the SVG), so both are tracked by id and re-applied to the fresh element with a negative `animation-delay` that resumes rather than restarts them; terminal-pane styles animate transform, opacity and clip-path only, because xterm's FitAddon derives rows and columns from the untransformed layout box and animating width or height there would resize the PTY; and window styles that transform also move the rect their connection line aims at, which is why the `beam` style animates opacity and filter only.
+
+  Also fixes an agent window spawning hidden (its agent belongs to a background tab): being `display:none` it never ran its animation, so `animationend` never fired and the entrance class plus its inline custom property stuck to the window permanently. Hidden windows now skip the entrance entirely.
+
+## 1.9.6
+
+### Patch Changes
+
+- Two fixes from community PRs (thanks @Lint111):
+  - fix(transcripts): complete tools from user-entry results (#177). Claude transcripts record tool requests in assistant entries but commonly carry their results in user-role entries; the transcript watcher only completed tools from the older assistant-entry path, so Codeman could keep showing a tool as running after it had finished. The watcher now recognizes `tool_result` blocks in user entries, ends the active tool state, and emits `transcript:tool_end` with the correct tool name and error status. Watcher tests also moved from fixed sleeps to condition-based `vi.waitFor` assertions.
+  - fix(notifications): quiet lifecycle hook noise (#178). Notification preferences move to schema version 5: the drawer-only "Response complete" (stop) default is now off, and the migration disables only the legacy drawer-only shape, preserving any explicit browser, audio, or push delivery the user opted into. Teammate-idle and task-completed hooks now map to the existing opt-in subagent categories instead of the broadly enabled idle/stop alerts, so normal agent activity no longer floods the drawer. Local and server-hydrated preferences are normalized through the same migration path (server hydration used to revive the retired default on fresh browsers), and the notification storage key now uses the stable handheld identity so an unfolded foldable keeps its mobile defaults and storage key (tablets and desktops unaffected).
+
+## 1.9.5
+
+### Patch Changes
+
+- Background-Bash rewake hook, hooks self-heal that preserves user hooks, and test-harness isolation.
+  - New `PostToolUse(Bash)` hook (PR #176): a self-contained `node -e` helper watches the session transcript for a background command's completion notification and uses Claude Code's `asyncRewake` to wake an idle agent (exit code 2), without injecting terminal input that could submit a user's draft. Works on Claude Code 2.1.207+; older CLIs strip the fields harmlessly.
+  - Hooks self-heal (`refreshStaleHookSecret` renamed to `refreshStaleCodemanHooks`) now replaces only Codeman-owned handlers, preserving user events, matchers, and sibling handlers in mixed configurations; `writeHooksConfig` merges instead of clobbering the hooks key at case creation (PR #176).
+  - Rewake helper hardening: self-terminates on its own 6h deadline and when orphaned; the marker is versioned (V2) with a version-agnostic ownership prefix so future script updates replace older handlers instead of duplicating them.
+  - Hook timeout units fixed: the hook `timeout` field is seconds (the CLI multiplies by 1000), so `HOOK_TIMEOUT_MS = 10000` gave curl hooks a ~2.8-hour effective timeout; now `HOOK_TIMEOUT_SECONDS = 10`.
+  - Test-harness isolation (PR #175): every test file gets a temporary `HOME`/`USERPROFILE` so tests cannot touch real Codeman state or delete real case directories, and `Session` attaches a raw-mode echo PTY instead of a real tmux client under Vitest. Fixes the quick-start suite deleting the real `~/codeman-cases/testcase`.
+  - CI stability: drain console-log rpc forwards before worker teardown (fixes a run-failing `EnvironmentTeardownError` with all tests passing); `test/webview-proxy.test.ts` no longer accidentally runs under the jsdom environment via a directive named in a comment.
+  - Release workflow pins the GitHub "Latest" badge to the Codeman release.
+
+## 1.9.4
+
+### Patch Changes
+
+- Fix a latent bug where a partial settings PUT silently reset live service state, and trim the `xterm-zerolag-input` README callout.
+  - **`PUT /api/settings` no longer resets watchers on a partial body.** The three `toggleService` calls (subagent watcher, workflow-run watcher, image watcher) read the raw request body with `??` defaults, so every key a caller omitted was treated as "apply the default". A body of just `{statusLineTelemetry:true}` would START the subagent watcher and STOP the workflow and image watchers, undoing the persisted config. They now resolve from `merged` (persisted settings + incoming), the same convention the `tmuxHistoryLimit` branch in that handler already used, so any PUT reconciles services to the effective stored state. Nothing triggered this in practice because every shipped client sends a full settings payload rebuilt from the DOM, but it was a trap for the next partial-update caller.
+  - **Regression test**: `test/routes/system-routes-settings-partial-put.test.ts` (4 cases) pins both directions, omitted keys preserve state and explicit keys still take effect. Verified to fail against the pre-fix handler.
+  - **CLAUDE.md** records the rule under "Adding Features → App setting": anything acting on a setting in that handler must resolve from `merged`, never the request body.
+  - **`xterm-zerolag-input` README**: removed the links line (getcodeman.com / install one-liner / star link) from the Codeman callout above the demo GIF. The callout keeps its links in the heading and body.
+
+## 1.9.3
+
+### Patch Changes
+
+- Plan-usage chip now defaults ON on desktop, plus the reworked `xterm-zerolag-input` README.
+  - **Plan-usage chip defaults ON (desktop).** The `showPlanUsageLimits` chip (live 5-hour and weekly plan usage from the Claude statusline) used to be opt-in and default OFF, so most users never saw it. Desktop now defaults ON; handhelds still default OFF so the phone header stays minimal and the `mobile-header-buttons-policy` guard keeps passing. Devices with an explicitly stored preference keep whatever they chose, so nobody's OFF gets overridden.
+  - **One resolver behind the chip.** Added `planUsageChipEnabled()` in settings-ui.js and routed all three call sites through it: the App Settings checkbox, the chip's visibility, and the create-time `statusLineTelemetry` flag in session-ui.js. Those three had independent `?? false` / `=== true` defaults, and a chip revealed without the telemetry flag renders `—` forever, so a default flip on one site alone would have shipped a permanently empty chip.
+  - **Cron button comment corrected.** The App Settings comment claimed "Cron button defaults ON" while the code, the template (`btn-cron--hidden`) and the CSS all default it OFF. Verified against a fresh browser profile: the button is hidden and its checkbox unchecked out of the box. Comment now matches, and states why the two halves stay consistent.
+  - **Docs.** CLAUDE.md, `docs/architecture-invariants.md` and `docs/usage-limits-display-plan.md` updated for the new default and the single-resolver rule; the stale `styles.css` comment claiming the server strips the chip's hidden class at render was corrected (display is per-device, so the client reveals it).
+  - **`xterm-zerolag-input` README rework** (0.1.5 shipped the content; this republishes with the graphic and promo changes): replaced the misaligned 8-line keystroke-flow diagram with a two-line stock-vs-zerolag contrast, added a Codeman callout above the demo GIF with links to getcodeman.com and the repo, and rewrote the Origin section so it argues the extraction story instead of repeating the promo.
+
+## 1.9.2
+
+### Patch Changes
+
+- Rewrite the `xterm-zerolag-input` package README as a value-first document and correct the drift that had accumulated against the source.
+  - Added the side-by-side phone demo GIF (`docs/images/zerolag-demo-20260728.gif`) as the hero image, referenced by absolute raw URL so it renders on npmjs.com as well as GitHub. The two-phone comparison shows 0ms local echo next to a 600ms-2.7s server echo on the same session.
+  - New "Why this one" comparison table, an explicit list of target use cases (SSH web clients, cloud IDEs, mobile terminals, container consoles), and a bundle-size badge (6.1 kB gzipped, measured from the ESM build).
+  - Corrected the test-count badge from 78 to the actual 175 tests across 5 files, in both the package README and the Published Packages section of the root README.
+  - Removed the stale "Unicode/emoji rendered at single-cell width" limitation. CJK, fullwidth forms and emoji have had double-width rendering and visual-column positioning since the wide-character fix; the honest remaining caveat (per-code-point width summing over-counts ZWJ grapheme clusters) replaces it.
+  - Documented the previously undocumented public `setPrompt()` method for switching prompt strategies at runtime, and the new "Wide characters (CJK, emoji)" integration section covering the optional `Unicode11Addon` path and the built-in range-table fallback.
+  - Documented `backgroundColor: 'transparent'`, corrected the `foregroundColor` default, and updated the grid-alignment math to reflect visual-column positioning rather than character index.
+
+  No source changes, docs only.
+
+## 1.9.1
+
+### Patch Changes
+
+- Narrow the Run dropdown, and close the last two gaps in web-tab asset rewriting.
+
+  **The Run dropdown was pinned at its full width.** It capped at 300px, and the recent-session rows wanted 326px, so it always rendered at the cap and reached further across the terminal than it needed to. Now 250px, chosen as the width at which a `~/<dir>/<repo>` + timestamp row still fits whole, since identifying a session to resume is what that list is for. Three fixes were needed to make the narrower menu degrade instead of clip: the saved-URL label now has its own element, because `text-overflow` on the row button did nothing (a bare text node inside a flex container becomes an anonymous flex item that ellipsis cannot reach); `.hist-dir` got `min-width: 0`, without which a flex item refuses to shrink below its own text and pushes the date out of the box; and history rows are held to the container width, because the list's `overflow-y: auto` implicitly makes `overflow-x: auto` and let each row size to its own content and scroll sideways. Phone and tablet widths are unchanged, being set separately in `mobile.css`.
+
+  **A dashboard's own `/api/...` assets are relayed again.** The `Referer`-keyed 404 fallback, which rescues a root-absolute asset that no rewrite layer could reach, refused everything under `/api` outright. Dashboards commonly serve their assets from exactly that namespace, so those requests had no rescue at all. The refusal is now precise: the relay runs before the API-shaped 404, and the auth exemption refuses only paths that resolve to a REAL Codeman route, with `/ws/` and `/q/` still refused by prefix.
+
+  Two findings shaped that fence, both from probing Fastify rather than reading it. `hasRoute()` matches the registered PATTERN literally, so `/api/sessions/abc` reports no match against a registered `/api/sessions/:id` and would have granted an unauthenticated exemption on a live session-scoped route; `findRoute()` performs the real lookup and is what the fence uses. And `@fastify/static` is mounted at `/`, so it registers a root catch-all matching every path, which has to count as "no real route" or the fence would refuse every referer-form request and break the rescue that already worked. A root catch-all is distinguishable because it is the only route whose wildcard param comes back equal to the whole request path. The fence fails closed, and both edges are pinned in `test/webview-auth-exemption.test.ts`.
+
+  **`url()` inside runtime CSS is rewritten.** Measuring the fallback against a purpose-built dashboard showed one sink no relay can reach: a `<style>` element built by page script has no URL of its own, so the browser sends an EMPTY `Referer` with the image request it triggers. The injected URL shim now rewrites root-absolute `url()` in `<style>` blocks, both as markup and when a `<style>` node is inserted. Verified in Chromium: a stylesheet-only `/api/hero.png` and a runtime `<style>` `/api/late.png` both load, where both previously failed. The remaining known gap is self-navigation via `location.href`, which cannot be patched because `Location.href` is unforgeable.
+
+## 1.9.0
+
+### Minor Changes
+
+- 2667150: feat(mobile): browse and insert local file and folder paths
+
+  Add a root-confined filesystem picker to Link Existing and the extended mobile
+  keyboard bar. Selected paths remain editable at the active prompt, supported
+  images/documents/text files open in a safe inline preview, and a new one-tap
+  action clears only the current unsent input without invoking `/clear`.
+
+### Patch Changes
+
+- 3cff98f: Fix two multi-user scoping holes in the new filesystem path picker. `GET /api/filesystem/browse` and `GET /api/filesystem/preview` accept an optional `sessionId` that contributes the session's working directory as a browse root, but they resolved it straight off the session map without an ownership check, unlike the nine other session-scoped handlers in the same route file. A non-admin could therefore pin another user's working directory as a root simply by passing their session id, then list and preview files under it. Both endpoints now run `canAccessOwned` and report 404, which also avoids confirming that a session id exists.
+
+  Separately, `Home` and `CASES_DIR` were unconditional browse roots for every caller. Per-user spaces live at `<USER_SPACES_DIR>/<username>`, which is inside `homedir()`, so the `Home` root alone exposed every other user's workspace to any authenticated user. In multi-user mode a non-admin now gets only their own space plus anything explicitly listed in `CODEMAN_FILE_PICKER_ROOTS`; `/mnt/d` is no longer offered by default, since a broad host mount should be an explicit operator decision in a multi-user deployment. Admins keep the host-wide roots, and single-user mode is unchanged.
+
+  Both holes are regression-guarded in `test/routes/file-routes.test.ts`, verified to fail against the previous code. Multi-user mode is opt-in and off by default, so single-user installs were never affected.
+
+- Web tabs: delete saved URLs from the Run dropdown, and fix images in proxied dashboards.
+
+  **Saved URLs are now manageable from the dropdown.** Each row under "Web / URL" gains a gear and an `x`, so a URL can be edited or deleted without first opening it as a tab. Previously the only delete path ran through the gear on an open tab, which was a dead end for a URL you no longer wanted open at all. Both controls stay permanently visible rather than hover-revealed, because the same menu is used on touch, and they get a larger hit box there. Deleting leaves the dropdown open on the remaining rows, and deleting the dashboard that is currently open also closes its tab and unmounts its frame.
+
+  **Runtime-injected images no longer 404.** A dashboard that renders its own markup from script (`card.innerHTML = '<img src="/api/hero?slug=x">'`, `img.src = '/api/slide'`) escaped every rewrite layer at once: `<base href>` never applies to a root-absolute URL, the server-side attribute rewrite only ever sees the initial document, and `runtimeUrlShim()` patched only `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource`. Those requests landed on Codeman's own root and 404'd, with a symptom that reads as an upstream fault: the dashboard's data loaded while every image stayed broken.
+
+  The shim now also covers the DOM URL sinks, so the request is never emitted in the first place and neither the `/api` fence in the 404 fallback nor the one in the auth middleware had to move. It wraps `innerHTML`, `outerHTML`, `insertAdjacentHTML` (including on `ShadowRoot`), `setAttribute`/`setAttributeNS`, and the `src`/`srcset`/`href`/`poster`/`data`/`action` property setters on img, source, media, video poster, script, iframe, embed, track, link, anchor, area, object and form, with a `MutationObserver` as a last net for sinks not patched above. Every rewrite routes through the same idempotent helper, which matters because unlike the server-side rewrite this one sees markup that may already be proxied, and a page re-injecting its own `outerHTML` would otherwise double-prefix. Everything is defensively guarded and marked so a double injection cannot wrap an already-wrapped setter.
+
+  Measured against a real dashboard: 693 image elements, 0 of them under the proxy prefix and 0 of 23 in-viewport images decoded before, 693 and 23 of 23 after. Covered by a new jsdom suite over the shim's DOM half and a new frontend suite over the dropdown rows. Known remaining gaps are documented in `docs/web-tabs.md`: a root-absolute `url()` inside a stylesheet injected at runtime, and self-navigation via `location.href`, which cannot be patched because `Location.href` is unforgeable.
+
+  Also in this release: a value-first README overhaul pointing at getcodeman.com, and the QR-auth distribution test now uses a chi-square check instead of a max-deviation threshold that failed on random variance.
+
+- bca56b4: Normalize Claude conversations in the response viewer. A Claude transcript is an append-only event log, so one logical exchange spans many JSONL rows: tool-result rows, meta/image/skill rows, compact summaries, task and team notifications, sidechains, replayed assistant snapshots, and multi-block assistant output. The viewer rendered a card per row, which produced duplicate and truncated cards that read as lost responses. Cards are now built at real human-turn boundaries, replayed assistant snapshots are deduplicated, and sidechain rows (which belong to subagents, not the main conversation) no longer leak in. An identical prompt that legitimately recurs after an assistant reply is still kept as its own turn.
+
+  Measured over 40 real transcripts: 3108 cards became 621, duplicate cards dropped from 74 to 8 (all of them genuinely repeated turns), no assistant text was lost, and the non-`context=full` last-response text was byte-identical on every file.
+
+  Also rebinds recovered sessions to their transcript. `reconcileSessions()` can recover a lost mux session as a `restored-<uuid8>` placeholder with a stale working directory, which made transcript lookup by cwd find nothing. The placeholder still carries the first eight characters of the conversation UUID, so the viewer now rebinds to the matching top-level transcript when exactly one candidate matches.
+
+## 1.8.3
+
+### Patch Changes
+
+- 8c089a4: Add four light UI and terminal skins: Paper Gray, Solarized Light, Catppuccin Latte, and Rosé Pine Dawn. The Skin picker now groups Light and Dark options, and each light skin ships a matching xterm ANSI palette plus `color-scheme: light` so native selects, date pickers and scrollbars stop rendering as dark OS widgets on a light page. Terminals set `minimumContrastRatio: 4.5` under a light skin (main terminal and teammate terminals both), which keeps CLI output that assumes a dark background readable, and `applyTerminalSkin()` now refreshes the zero-lag input overlay so typed-but-unflushed text does not keep the previous theme's colors.
+
+  Elevated surfaces (modals, command palette, dropdowns, subagent and ultracode windows, file preview, attachment tray, mobile sheets) now resolve through shared `--floating-bg` / `--control-*` / `--banner-bg-*` / `--modal-backdrop` / `--elevated-shadow` tokens instead of hardcoded near-black rgba, so they follow whichever skin is active. On the Daylight skins this lifts modals slightly off the page background; OG Codeman pins its own near-black value to keep that palette neutral.
+
+  Also defines twelve CSS compatibility aliases (`--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--text-primary`, `--text-secondary`, `--border-color`, `--accent-color`, `--success`, `--error`, `--danger`, `--font-mono`, `--shadow-lg`) that panels and overlays already referenced in about 79 places but which were never actually declared, so those rules silently resolved to nothing. Status badges and accent-tinted pills (search filter chips and result badges, session tab mode pills, respawn state, Ralph priority and circuit-breaker badges, tunnel and voice status, mobile case picker) no longer keep their pale light-on-dark ink under a light skin, where it measured 1.0 to 1.9:1 and made the search filter chips invisible.
+
+  New static regression `test/skin-themes.test.ts` guards the four-way parity between the CSS token block, the xterm palette, the pre-paint allowlist and the Settings picker.
+
+## 1.8.2
+
+### Patch Changes
+
+- Web tabs: open dashboard URLs as tabs beside agent sessions, plus terminal link fixes.
+
+  **Web tabs.** The Run dropdown gains a "Web / URL" section. A saved URL renders as a tab in the same strip as Claude/Codex/Gemini sessions, with the same Alt+1-9 numbering, an icon picker, and per-device tab order. Frames stay mounted while hidden (LRU-bounded), so switching tabs never reloads a dashboard.
+
+  Dashboards are proxied through Codeman's own origin, because a direct iframe fails three ways at once: an HTTPS Codeman cannot embed a plain-HTTP target (mixed content, with no override at all on iOS Safari), many dashboards send `X-Frame-Options: DENY`, and Codeman's own `default-src 'self'` CSP blocks cross-origin frames. Proxying dissolves all three and leaves the production CSP unchanged. The fetch happens server-side, so a tailnet-only or localhost-only dashboard is reachable from any device that can reach Codeman.
+
+  The proxy is not an API surface: it authenticates on a 192-bit capability in the path (memory-only, rolling TTL, bound to the minting user, revoked on edit or delete) and is exempt from the cookie and Origin checks, because a sandboxed iframe is opaque-origin and sends neither. The Host allowlist is never bypassed. Iframes omit `allow-same-origin` unless a URL is explicitly marked trusted, and `Authorization` plus the session cookie are stripped upstream in both modes so `CODEMAN_PASSWORD` cannot leak into a dashboard. Includes an HTTP and WebSocket proxy, redirect/cookie/`<base>` rewriting, a runtime URL shim for requests built by dashboard JavaScript, and CORS handling for the opaque-origin frame. New endpoints under `/api/webviews`, storage in `~/.codeman/webviews.json`, user guide in `docs/web-tabs.md`.
+
+  **Terminal links no longer truncate.** Three separate cuts, each producing a link that opened the wrong target or none at all:
+  - A single `&` ended the match, so every query string was cut. A WordPress edit link resolved to `?post=1479` and Claude Code's own `/login` URL was unusable. `&` is now part of a URL while `&&` remains a boundary.
+  - Links wider than the terminal were cut at the row boundary. The link provider now stitches continuation rows into one logical line and maps offsets back across rows. Handles both soft wraps (emulator, `isWrapped`) and hard wraps (a program wrapping its own output and emitting a newline, as Ink does), the latter being why the `/login` URL grew longer as the window was widened.
+  - Image and PDF paths were not matched at all, so pasted-screenshot paths rendered as plain text. They now link and open the file preview, which renders images inline.
+
+  **Also fixes** a pre-existing bug where `.toolbar`'s `backdrop-filter` created a stacking context that trapped the Run menu's z-index, letting the welcome overlay cover it: with no session open, every item in that menu (Claude Code included) was unclickable.
+
+## 1.8.1
+
+### Patch Changes
+
+- Mobile toolbar: a dedicated Enter button, and Shell moves into the Run dropdown.
+
+  Submitting is a constant need on a touch keyboard, so on phones (≤430px) the toolbar slot that held "Shell" now holds a dark blue **Enter** button. Starting a shell, the far rarer action, moves into the expandable Run dropdown as `Terminal / Shell` (the Run button then reads "Run SH"). Desktop and tablet are unchanged: the green Run Shell button stays exactly where it was.
+
+  Enter is replayed through the terminal's own input path rather than posted to the input API. This matters because local echo is on by default on touch devices: the characters you type are buffered client-side and have not yet reached the PTY, so sending a bare carriage return would submit an empty line and leave your text stranded on screen. Replaying the keypress flushes the buffered text first, then submits.
+
+  Installer: re-runs and updates now preserve the existing network binding instead of silently reverting it, so upgrading no longer changes how the dashboard is reachable.
+
+  Default desktop header is cleaner: the file viewer is shown by default and the plan-usage chip is unchanged, while the token-count chip and lifecycle-log button now default off. Stored preferences are still honored.
+
+  Docs and repo housekeeping: fresh phone screenshots and a new hero GIF in both READMEs, contributor and total-commit badges, and a much shorter repo root. `SECURITY.md` moved to `.github/` (GitHub resolves it there, so the Security policy tab is unaffected), `SPEEDRUN.md` to `docs/`, the knip config to `config/`, and Prettier's config into the `"prettier"` key of `package.json`. `CLAUDE.md` was split so the always-loaded guidance is roughly half its former size, with the deep implementation detail preserved verbatim in `docs/architecture-invariants.md`.
+
+## 1.8.0
+
+### Minor Changes
+
+- Installer: choose your network binding, with LAN access as the new guided default.
+
+  The install script now asks at the end of setup how the dashboard should be reachable:
+  1. Any device on your network (0.0.0.0), the default. The installer prompts for a dashboard password (hidden input, confirmed twice); declining a password requires an explicit confirmation and the install ends with a prominent warning explaining the exposure.
+  2. This machine only (127.0.0.1), the safer option for tunnel/Tailscale setups.
+
+  The choice is wired into the generated systemd unit and launchd plist (values escaped for each format), the run-now launch path, and the printed URLs, which now include the detected LAN IP for instant phone access. Non-interactive installs keep the safe loopback default unless CODEMAN_HOST is preset, and the server binary's own default binding (127.0.0.1) is unchanged, so npm and manual installs behave exactly as before. New installer env presets: CODEMAN_HOST and CODEMAN_PASSWORD skip the prompts for automation.
+
 ## 1.7.1
 
 ### Patch Changes

README.md

@@ -5,7 +5,7 @@
 <h2 align="center">Mission control for AI coding agents</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; Terminal - One Dashboard &bull; Any Device</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
 <p align="center">
@@ -13,9 +13,10 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
   <a href="https://www.npmjs.com/package/aicodeman"><img src="https://img.shields.io/npm/v/aicodeman?style=flat-square&label=npm&color=22c55e" alt="npm version"></a>
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
 <p align="center">
@@ -23,33 +24,51 @@
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo.gif" alt="Codeman — parallel subagent visualization" width="900">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
 </p>
 
-**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, or Gemini CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
+**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, or Gemini CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
 
-- **One dashboard, four CLIs** - run [Claude Code, OpenCode, Codex, or Gemini](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
+Get started in one line (macOS & Linux, Windows via WSL):
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+```
+
+```bash
+codeman web
+# Open http://localhost:3000 and start your first session
+```
+
+The installer asks before every system change, and re-running the same line updates in place. Full details: [Quick Start - Installation](#quick-start---installation).
+
+- **One dashboard, five CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, or Gemini](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
 - **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
 - **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
 - **See your agents think** - [live floating windows](#live-agent-visualization) for every subagent and teammate, with real-time transcripts
 - **Nothing gets lost** - tmux persistence across restarts and network drops, exactly-once input delivery, full-scrollback replay
-- **Self-hosted and boring on purpose** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
+- **Self-hosted and private** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman dashboard tour: session tabs per case, one-click Run for new agents, live plan usage in the header" width="900">
+</p>
 
 ---
 
 ## Quick Start - Installation
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+curl -fsSL https://getcodeman.com/install | bash
 ```
 
 This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
 
 - **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
+- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
 - **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
 - **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
 
-You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (any combination works). The installer detects whichever of the four is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the five is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
 
 ```bash
 codeman web
@@ -129,15 +148,67 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 <summary><strong>Windows (WSL)</strong></summary>
 
 ```powershell
-wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
 
 </details>
 
 ---
 
+## Mobile-Optimized Web UI
+
+The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.
+
+<table>
+<tr>
+<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="300"></td>
+<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="440"></td>
+</tr>
+<tr>
+<td align="center"><em>Answering prompts by touch</em></td>
+<td align="center"><em>Accessory bar + dedicated Enter button</em></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th>Terminal Apps</th>
+<th>Codeman Mobile</th>
+</tr>
+<tr><td>200-300ms input lag over remote</td><td><b>Local echo — instant feedback</b></td></tr>
+<tr><td>Tiny text, no context</td><td>Full xterm.js terminal</td></tr>
+<tr><td>No session management</td><td>Swipe between sessions</td></tr>
+<tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr>
+<tr><td>Manual reconnect</td><td>tmux persistence</td></tr>
+<tr><td>No agent visibility</td><td>Background agents in real-time</td></tr>
+<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr>
+<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
+</table>
+
+- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
+- **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
+- **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
+- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
+
+```bash
+codeman web --https
+# Open on your phone: https://<your-ip>:3000
+```
+
+> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended): the installer can set it up for you (choose **Tailscale** at the network-access prompt, or run `bash ~/.codeman/app/install.sh tailscale` on an existing install). That gives you `https://<your-machine>.<tailnet>.ts.net` with a real certificate: private to your tailnet, no password required, and PWA install + push notifications work on your phone.
+
+### Secure QR Code Authentication
+
+Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
+
+Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
+
+The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+---
+
 ## Using Codeman — A Human's Guide
 
 A start-to-finish walkthrough for driving Codeman from the browser. If you just installed, this is where to begin.
@@ -160,7 +231,7 @@ Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in
 | Field                        | What it does                                                                                                        |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers.                           |
-| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Gemini`, or `Terminal` (plain shell).                                     |
+| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Antigravity`, `Gemini`, or `Terminal` (plain shell).                       |
 | **Model**                    | Per-session model (App Settings → Claude Model). A soft default — `/model` still works in-session.                  |
 | **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
 
@@ -170,7 +241,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 - **Tabs (top)** — one per session. `Alt+1`-`9` to jump, `Ctrl+Tab` for next, drag to reorder (tab order syncs across your devices).
 - **Terminal (center)** — a real `xterm.js` terminal; full TUIs render correctly. Type directly and press **Enter** to send. `Shift+Enter` inserts a newline.
-- **Side panels** — Respawn, Ralph, Orchestrator, Cron, Subagents, Settings (toggled from the toolbar).
+- **Side panels** — Respawn, Orchestrator, Cron, Subagents, Settings (toggled from the toolbar).
 
 ### 4. Talk to the agent
 
@@ -184,7 +255,6 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 | Mode             | Use it for                                                                                                                        | Where                                                               |
 | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | **Respawn**      | Long unattended runs — auto-restarts the CLI on idle/limit, with adaptive timing. Presets: `solo-work`, `overnight-autonomous`, … | Respawn tab                                                         |
-| **Ralph / Todo** | A self-driving loop that tracks a todo list and keeps working until done.                                                         | Ralph tab                                                           |
 | **Orchestrator** | Turn one goal into a phased plan and drive it to completion across agents.                                                        | Orchestrator panel                                                  |
 | **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Display → Header Displays)_ |
 | **Auto-resume**  | Automatically continue after a subscription rate-limit resets.                                                                    | Respawn tab (top)                                                   |
@@ -205,87 +275,10 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 ---
 
-## Mobile-Optimized Web UI
-
-The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.
-
-<table>
-<tr>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="Mobile — landing page with QR auth" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="Mobile — idle session with keyboard accessory" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="Mobile — active agent session" width="260"></td>
-</tr>
-<tr>
-<td align="center"><em>Landing page with QR auth</em></td>
-<td align="center"><em>Keyboard accessory bar</em></td>
-<td align="center"><em>Agent working in real-time</em></td>
-</tr>
-</table>
-
-<table>
-<tr>
-<th>Terminal Apps</th>
-<th>Codeman Mobile</th>
-</tr>
-<tr><td>200-300ms input lag over remote</td><td><b>Local echo — instant feedback</b></td></tr>
-<tr><td>Tiny text, no context</td><td>Full xterm.js terminal</td></tr>
-<tr><td>No session management</td><td>Swipe between sessions</td></tr>
-<tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr>
-<tr><td>Manual reconnect</td><td>tmux persistence</td></tr>
-<tr><td>No agent visibility</td><td>Background agents in real-time</td></tr>
-<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr>
-<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
-</table>
-
-### Secure QR Code Authentication
-
-Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
-
-Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
-
-The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
-
-### Touch-Optimized Interface
-
-- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard. Destructive commands (`/clear`, `/compact`) require a double-press to confirm — first tap arms the button, second tap executes — so you never fire one by accident on a bumpy commute
-- **Swipe navigation** — left/right on the terminal to switch sessions (80px threshold, 300ms)
-- **Smart keyboard handling** — toolbar and terminal shift up when keyboard opens (uses `visualViewport` API with 100px threshold for iOS address bar drift)
-- **Safe area support** — respects iPhone notch and home indicator via `env(safe-area-inset-*)`
-- **44px touch targets** — all buttons meet iOS Human Interface Guidelines minimum sizes
-- **Bottom sheet case picker** — slide-up modal replaces the desktop dropdown
-- **Native momentum scrolling** — `-webkit-overflow-scrolling: touch` for buttery scroll
-
-```bash
-codeman web --https
-# Open on your phone: https://<your-ip>:3000
-```
-
-> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended) — it provides a private network so you can access `http://<tailscale-ip>:3000` from your phone without TLS certificates.
-
----
-
-## Live Agent Visualization
-
-Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.
-
-<p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="Subagent Visualization" width="900">
-</p>
-
-- **Floating terminal windows** — draggable, resizable panels for each agent with a live activity log showing every tool call, file read, and progress update as it happens
-- **Connection lines** — animated green lines linking parent sessions to their child agents, updating in real-time as agents spawn and complete
-- **Status & model badges** — green (active), yellow (idle), blue (completed) indicators with Haiku/Sonnet/Opus model color coding
-- **Auto-behavior** — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
-- **Nested agents** — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)
-
-**Agent Teams** — first-class support for Claude Code's native multi-agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). `TeamWatcher` polls `~/.claude/teams/`, matches teammates to their lead session, and surfaces them as live subagent windows with **team-aware idle detection** — so the Respawn Controller won't fire while teammates are still working. See [`docs/agent-teams/`](docs/agent-teams/).
-
----
-
 ## Zero-Lag Input Overlay
 
 <p align="center">
-  <img src="docs/images/zerolag-demo.gif" alt="Zerolag Demo — local echo vs server echo side-by-side" width="900">
+  <img src="docs/images/zerolag-demo-20260728.gif" alt="Zerolag demo: instant local echo next to 600ms-2.7s server echo, side by side on two phones" width="900">
 </p>
 
 When accessing your coding agent remotely (VPN, Tailscale, SSH tunnel), every keystroke normally takes 200-300ms to round-trip. Codeman implements a **Mosh-inspired local echo system** that makes typing feel instant regardless of latency.
@@ -302,6 +295,30 @@ A pixel-perfect DOM overlay inside xterm.js renders keystrokes at 0ms. Backgroun
 
 ---
 
+## Live Agent Visualization
+
+Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.
+
+<p align="center">
+  <img src="docs/images/subagent-windows-20260724.png" alt="Subagent Visualization: three parallel Explore agents as floating windows with live tool-call feeds" width="900">
+</p>
+
+- **Floating terminal windows** — draggable, resizable panels for each agent with a live activity log showing every tool call, file read, and progress update as it happens
+- **Connection lines** — animated green lines linking parent sessions to their child agents, updating in real-time as agents spawn and complete
+- **Status & model badges** — green (active), yellow (idle), blue (completed) indicators with Haiku/Sonnet/Opus model color coding
+- **Auto-behavior** — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
+- **Nested agents** — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)
+
+Multi-agent Workflow runs ("ultracode") get the same treatment: a floating run window tracks the whole workflow live, with phases, per-agent token counts, and the current tool of every agent:
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode workflow visualization: a live run window with per-agent tokens and phases" width="900">
+</p>
+
+**Agent Teams** — first-class support for Claude Code's native multi-agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). `TeamWatcher` polls `~/.claude/teams/`, matches teammates to their lead session, and surfaces them as live subagent windows with **team-aware idle detection** — so the Respawn Controller won't fire while teammates are still working. See [`docs/agent-teams/`](docs/agent-teams/).
+
+---
+
 ## Respawn Controller
 
 The core of autonomous work. When the agent goes idle, the Respawn Controller detects it, sends a continue prompt, cycles context management commands for fresh context, and resumes — running **24+ hours** completely unattended.
@@ -328,7 +345,7 @@ Beyond single-session respawn, the **Orchestrator** turns a high-level goal into
 - **Crash-safe** — full state persists under the `orchestrator` key in `state.json`, so it survives restarts
 - **Driven from the UI or API** — the Orchestrator panel, or `POST /api/orchestrator/start` → `/approve` → `/status` (10 endpoints)
 
-> Distinct from Ralph (a single-session autonomous loop): the orchestrator coordinates multi-phase, multi-agent execution. Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
+> Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
 
 ---
 
@@ -336,10 +353,6 @@ Beyond single-session respawn, the **Orchestrator** turns a high-level goal into
 
 Run **20 parallel sessions** with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.
 
-<p align="center">
-  <img src="docs/screenshots/multi-session-dashboard.png" alt="Multi-Session Dashboard" width="800">
-</p>
-
 ### Persistent Sessions
 
 Every session runs inside **tmux** — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Managed sessions are environment-tagged so the agent won't kill its own session.
@@ -374,14 +387,6 @@ The title is templated into the served HTML on first byte, so it's correct from
 
 Real-time desktop alerts when sessions need attention — `permission_prompt` and `elicitation_dialog` trigger critical red tab blinks, `idle_prompt` triggers yellow blinks. Click any notification to jump directly to the affected session. Hooks auto-configured per case directory.
 
-### Ralph / Todo Tracking
-
-Auto-detects Ralph Loops, `<promise>` tags, TodoWrite progress (`4/9 complete`), and iteration counters (`[5/50]`) with real-time progress rings and elapsed time tracking.
-
-<p align="center">
-  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph Loop Tracking" width="800">
-</p>
-
 ### Run Summary
 
 Click the chart icon on any session tab to see a timeline of everything that happened — respawn cycles, token milestones, auto-compact triggers, idle/working transitions, hook events, errors, and more.
@@ -399,7 +404,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 ## More Features
 
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
-- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
 - **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
 - **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
@@ -421,7 +426,7 @@ Run a case inside its own hardened Docker container instead of directly on your
 - **Resource templates** — expand the checkbox for a **Small / Medium / Large / GPU** preset (memory, CPUs, GPU), or set your own. **Disk is elastic** — storage grows as data flows in, no fixed cap.
 - **Shared per-case container** — many sessions can `docker exec` into the same container; killing one session never tears the container out from under the others.
 - **Hardened by default** — non-root, `--cap-drop ALL`, `no-new-privileges`, PID/memory caps, never `--privileged` or the docker socket; a **sealed** profile (no host credentials, network off) is one toggle away.
-- **Seamless auth, isolated credentials** — your host Claude / Codex / Gemini / OpenCode logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
+- **Seamless auth, isolated credentials** — your host Claude / Codex / Antigravity / Gemini / OpenCode logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
 - **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
 - **Durable** — reconnect after a restart lands back in the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript.
 
@@ -586,11 +591,11 @@ When someone authenticates via QR, the desktop shows a notification toast with t
 
 ## Security
 
-By default Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control _who_ that is. (The startup permission mode is configurable; see below.) Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **Found a vulnerability?** See [`SECURITY.md`](SECURITY.md) for private disclosure and the list of known limitations.
+By default Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control _who_ that is. (The startup permission mode is configurable; see below.) Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **Found a vulnerability?** See [`SECURITY.md`](.github/SECURITY.md) for private disclosure and the list of known limitations.
 
 ### Network & access
 
-- **Loopback by default** — binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box. Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
+- **Loopback by default** — the server binary binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box (the guided installer asks about network access and configures the binding + password for you). Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
 - **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
 - **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers _immediately_ even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
 - **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Claude CLI → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
@@ -607,7 +612,7 @@ These run for **every** request — before auth, even on the default no-password
 
 ### Input, files & headers
 
-- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env-prefix allowlist gates which settings each CLI can receive
+- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `ANTIGRAVITY_*` / `GEMINI_*` / `GOOGLE_*` env-prefix allowlist gates which settings each CLI can receive
 - **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 50 MB raw & download; `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
 - **Security headers** — `Content-Security-Policy` (`default-src 'self'`, every exception enumerated), `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, HSTS over HTTPS, and CORS reflected **only** for `localhost` / `127.0.0.1` / `::1`
 
@@ -646,6 +651,8 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 | `Alt/Option+[` / `Alt/Option+]` | Previous / next session                                       |
 | `Alt/Option+1`-`Alt/Option+9`   | Switch to tab N (physical keys, so macOS Option layouts work) |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right                                  |
+| `Ctrl/Cmd+C`                    | Copy selection, or interrupt when nothing is selected         |
+| `Ctrl+Shift+C`                  | Copy selection (never interrupts)                             |
 | `Ctrl/Cmd+L`                    | Clear terminal                                                |
 | `Ctrl+Shift+R`                  | Restore terminal size                                         |
 | `Ctrl+Shift+V`                  | Toggle voice input                                            |
@@ -729,7 +736,6 @@ 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 ralph start --min-hours 8        # (r)  launch the autonomous loop
 codeman attach <path>                     #      attach a Claude hook context
 ```
 
@@ -766,13 +772,6 @@ REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE str
 | `POST` | `/api/sessions/:id/respawn/stop`   | Stop controller            |
 | `PUT`  | `/api/sessions/:id/respawn/config` | Update config              |
 
-### Ralph / Todo
-
-| Method | Endpoint                         | Description            |
-| ------ | -------------------------------- | ---------------------- |
-| `GET`  | `/api/sessions/:id/ralph-state`  | Get loop state + todos |
-| `POST` | `/api/sessions/:id/ralph-config` | Configure tracking     |
-
 ### Orchestrator
 
 | Method | Endpoint                    | Description                     |
@@ -813,6 +812,8 @@ REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE str
 | `POST` | `/api/clipboard`                | Push text to all connected browsers (`{text}`) |
 | `GET`  | `/api/sessions/:id/run-summary` | Timeline + stats                               |
 
+> **Building something on top of Codeman?** [`docs/extending-codeman.md`](docs/extending-codeman.md) is the integration guide: render your own UI as a tab, subscribe to the SSE event stream to react when an agent needs you, drive Codeman from a script, and the traps worth knowing before you start. Codeman has no plugin runtime on purpose, so an integration is just your own process talking HTTP.
+
 ---
 
 ## Architecture
@@ -835,7 +836,6 @@ flowchart TB
         end
 
         subgraph Detection["Detection Layer"]
-            RT["Ralph Tracker"]
             SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
             TW["Team Watcher<br/><small>~/.claude/teams/*</small>"]
         end
@@ -846,7 +846,7 @@ flowchart TB
         end
 
         subgraph External["External"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini</small>"]
             BG["Background Agents<br/><small>(Task tool)</small>"]
         end
     end
@@ -859,7 +859,6 @@ flowchart TB
     SM --> RC
     SM --> ORC
     SM --> SS
-    S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
@@ -908,7 +907,7 @@ Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-stru
 
 [![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
 
-Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, configurable prompt detection, full state machine with 78 tests.
+Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 6.1 kB gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 175 tests.
 
 ```bash
 npm install xterm-zerolag-input

README.zh-CN.md

@@ -5,7 +5,7 @@
 <h2 align="center">AI 编程智能体的任务控制中心</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
 </p>
 
 <p align="center">
@@ -17,21 +17,39 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo.gif" alt="Codeman — 并行子智能体可视化" width="900">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — 并行子智能体可视化" width="900">
+</p>
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman 仪表盘导览：按项目分组的会话标签页、一键 Run 启动新智能体、页头实时用量" width="900">
 </p>
 
 > 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
 
+一行命令即可安装（macOS 和 Linux，Windows 通过 WSL）：
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+```
+
+```bash
+codeman web
+# 打开 http://localhost:3000，开启你的第一个会话
+```
+
+安装器在每次系统改动前都会先询问；重跑同一条命令即可原地更新。详见[快速开始 — 安装](#快速开始--安装)。
+
 ---
 
 ## 快速开始 — 安装
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+curl -fsSL https://getcodeman.com/install | bash
 ```
 
 该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。几点须知：
@@ -40,7 +58,7 @@ curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | b
 - **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。也可以使用 `install.sh update` 与 `install.sh uninstall`。
 - **CI / 无终端环境：** 没有终端时，涉及系统改动的步骤会带着说明中止，而不是静默执行；在自动化场景设置 `CODEMAN_NONINTERACTIVE=1` 即可批准这些步骤。
 
-你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)（任意组合均可）。安装器会自动检测这四个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)（任意组合均可；自 Google 面向消费者停售后，Gemini CLI 仅限企业版，Antigravity 是其继任者）。安装器会自动检测这五个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
 
 ```bash
 codeman web
@@ -120,15 +138,67 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 <summary><strong>Windows（WSL）</strong></summary>
 
 ```powershell
-wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
 
 </details>
 
 ---
 
+## 移动端优化的 Web UI
+
+在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
+
+<table>
+<tr>
+<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="300"></td>
+<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="440"></td>
+</tr>
+<tr>
+<td align="center"><em>触控回答提示</em></td>
+<td align="center"><em>配件栏 + 独立 Enter 按钮</em></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th>普通终端 App</th>
+<th>Codeman 移动端</th>
+</tr>
+<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
+<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
+<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
+<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
+<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
+<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
+<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
+<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
+</table>
+
+- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触
+- **独立的 Enter 按钮** —— 以按键方式回放，先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上
+- **滑动导航与智能键盘处理** —— 左右滑动切换会话；键盘弹出时工具栏与终端整体上移（`visualViewport` API）
+- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
+
+```bash
+codeman web --https
+# 在手机上打开：https://<你的IP>:3000
+```
+
+> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
+
+### 安全的二维码认证
+
+在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
+
+每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
+
+该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+---
+
 ## 使用 Codeman —— 人类操作指南
 
 从头到尾走一遍如何在浏览器里驾驭 Codeman。如果你刚装好，就从这里开始。
@@ -151,7 +221,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 | 字段                   | 作用                                                                                        |
 | ---------------------- | ------------------------------------------------------------------------------------------- |
 | **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。                           |
-| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Gemini` 或 `Terminal`（普通 shell）。               |
+| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Antigravity`、`Gemini` 或 `Terminal`（普通 shell）。 |
 | **模型**               | 每会话模型（App Settings → Claude Model）。软默认值 —— 会话内 `/model` 依然有效。           |
 | **Effort / Ultracode** | 推理力度（`low`–`max`），或用 `ultracode` 开启动态多智能体工作流。随时可用 `/effort` 切换。 |
 
@@ -161,7 +231,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 - **标签（顶部）** —— 每个会话一个。`Alt+1`–`9` 跳转，`Ctrl+Tab` 下一个，拖拽排序（标签顺序会跨设备同步）。
 - **终端（中央）** —— 真实的 `xterm.js` 终端；完整 TUI 正常渲染。直接输入并按 **Enter** 发送。`Shift+Enter` 插入换行。
-- **侧边面板** —— Respawn、Ralph、Orchestrator、Cron、Subagents、Settings（从工具栏切换）。
+- **侧边面板** —— Respawn、Orchestrator、Cron、Subagents、Settings（从工具栏切换）。
 
 ### 4. 与智能体对话
 
@@ -175,7 +245,6 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 | 模式             | 用途                                                                                                      | 位置                                                               |
 | ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | **Respawn**      | 长时间无人值守运行 —— 空闲/限额时自动重启 CLI，带自适应时序。预设：`solo-work`、`overnight-autonomous` 等 | Respawn 标签页                                                     |
-| **Ralph / Todo** | 一个自驱循环，跟踪 todo 列表并持续工作直到完成。                                                          | Ralph 标签页                                                       |
 | **Orchestrator** | 把一个目标变成分阶段计划，并跨多个智能体推动完成。                                                        | 编排器面板                                                         |
 | **Cron**         | 已保存的、命名的定时任务（`once`/`interval`/`daily`/`weekly`），到期时拉起会话并发送提示。                | ⏰ Cron 按钮（可选启用：App Settings → Display → Header Displays） |
 | **Auto-resume**  | 订阅限额重置后自动继续。                                                                                  | Respawn 标签页（顶部）                                             |
@@ -196,87 +265,10 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 ---
 
-## 移动端优化的 Web UI
-
-在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
-
-<table>
-<tr>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="移动端 — 带键盘配件栏的空闲会话" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
-</tr>
-<tr>
-<td align="center"><em>带二维码认证的登录页</em></td>
-<td align="center"><em>键盘配件栏</em></td>
-<td align="center"><em>智能体实时工作中</em></td>
-</tr>
-</table>
-
-<table>
-<tr>
-<th>普通终端 App</th>
-<th>Codeman 移动端</th>
-</tr>
-<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
-<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
-<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
-<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
-<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
-<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
-<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
-<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
-</table>
-
-### 安全的二维码认证
-
-在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
-
-每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
-
-该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
-
-### 触控优化界面
-
-- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮。破坏性命令（`/clear`、`/compact`）需双击确认 —— 第一次点击「上膛」，第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
-- **滑动导航** —— 在终端上左右滑动切换会话（阈值 80px，300ms）
-- **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移（使用 `visualViewport` API，并对 iOS 地址栏漂移设置 100px 阈值）
-- **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
-- **44px 触控目标** —— 所有按钮均满足 iOS 人机界面指南的最小尺寸
-- **底部抽屉式 case 选择器** —— 用上滑模态框替代桌面端下拉菜单
-- **原生惯性滚动** —— `-webkit-overflow-scrolling: touch`，丝滑流畅
-
-```bash
-codeman web --https
-# 在手机上打开：https://<你的IP>:3000
-```
-
-> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
-
----
-
-## 实时智能体可视化
-
-实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
-
-<p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="子智能体可视化" width="900">
-</p>
-
-- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
-- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
-- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
-- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
-- **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
-
-**智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
-
----
-
 ## 零延迟输入叠加层
 
 <p align="center">
-  <img src="docs/images/zerolag-demo.gif" alt="Zerolag 演示 —— 本地回显与服务端回显并排对比" width="900">
+  <img src="docs/images/zerolag-demo-20260728.gif" alt="Zerolag 演示：两台手机并排对比，即时本地回显与 600ms-2.7s 服务端回显" width="900">
 </p>
 
 远程访问你的编程智能体时（VPN、Tailscale、SSH 隧道），每次按键通常需要 200–300 毫秒往返。Codeman 实现了一套**受 Mosh 启发的本地回显系统**，无论延迟多高，打字都感觉即时。
@@ -293,6 +285,30 @@ xterm.js 内部一个像素级精准的 DOM 叠加层以 0ms 渲染按键。后
 
 ---
 
+## 实时智能体可视化
+
+实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
+
+<p align="center">
+  <img src="docs/images/subagent-windows-20260724.png" alt="子智能体可视化 —— 三个并行 Explore 智能体的浮动窗口与实时工具调用日志" width="900">
+</p>
+
+- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
+- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
+- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
+- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
+- **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
+
+多智能体 Workflow 运行（「ultracode」）同样可视化：一个浮动运行窗口实时跟踪整个工作流，展示阶段、各智能体的 token 用量与当前工具：
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode 工作流可视化 —— 实时运行窗口，含各智能体 token 与阶段" width="900">
+</p>
+
+**智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
+
+---
+
 ## 重生控制器（Respawn Controller）
 
 自主工作的核心。当智能体进入空闲，重生控制器会检测到，发送继续提示，循环执行上下文管理命令以获得全新上下文，然后恢复工作 —— 可完全无人值守运行 **24 小时以上**。
@@ -319,7 +335,7 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 - **崩溃安全** —— 完整状态持久化在 `state.json` 的 `orchestrator` 键下，可在重启后存续
 - **可从 UI 或 API 驱动** —— 编排器面板，或 `POST /api/orchestrator/start` → `/approve` → `/status`（共 10 个端点）
 
-> 与 Ralph（单会话自主循环）不同：编排器协调多阶段、多智能体执行。完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
+> 完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
 
 ---
 
@@ -327,10 +343,6 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 
 运行 **20 个并行会话**且全程可见 —— 60fps 的实时 xterm.js 终端、按会话的 token 与成本跟踪、基于标签的导航，以及一键管理。
 
-<p align="center">
-  <img src="docs/screenshots/multi-session-dashboard.png" alt="多会话仪表盘" width="800">
-</p>
-
 ### 持久化会话
 
 每个会话都运行在 **tmux** 内 —— 会话可在服务器重启、网络中断与机器休眠后存续。启动时自动恢复，具备双重冗余。幽灵会话发现机制能找到孤立的 tmux 会话。受管会话带有环境标签，因此智能体不会杀掉自己的会话。
@@ -365,14 +377,6 @@ codeman web --title-hostname dev-box       # codeman:dev-box（用于覆盖嘈
 
 当会话需要关注时实时桌面提醒 —— `permission_prompt` 与 `elicitation_dialog` 触发关键的红色标签闪烁，`idle_prompt` 触发黄色闪烁。点击任意通知即可直接跳转到相关会话。Hook 按 case 目录自动配置。
 
-### Ralph / Todo 跟踪
-
-自动检测 Ralph 循环、`<promise>` 标签、TodoWrite 进度（`4/9 complete`）以及迭代计数器（`[5/50]`），并提供实时进度环与已用时间跟踪。
-
-<p align="center">
-  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph 循环跟踪" width="800">
-</p>
-
 ### 运行摘要（Run Summary）
 
 点击任意会话标签上的图表图标，即可看到所发生一切的时间线 —— 重生周期、token 里程碑、自动 compact 触发、空闲/工作切换、hook 事件、错误等等。
@@ -390,7 +394,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 ## 更多特性
 
 - **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
-- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex** 或 **Gemini**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex**、**Antigravity** 或 **Gemini**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*`、`ANTIGRAVITY_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
 - **Docker 会话** —— 在隔离且加固的容器中运行案例。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一案例的多个会话共享一个容器；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
 - **远程 SSH 会话**：把案例指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
@@ -412,7 +416,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 - **资源模板** —— 展开复选框可选 **Small / Medium / Large / GPU** 预设（内存、CPU、GPU），也可以完全自定义。**磁盘是弹性的** —— 存储随数据增长，没有固定上限。
 - **按案例共享容器** —— 多个会话可以 `docker exec` 进同一个容器；结束某个会话绝不会影响其他会话所在的容器。
 - **默认加固** —— 非 root、`--cap-drop ALL`、`no-new-privileges`、PID/内存上限，绝不使用 `--privileged` 或 docker socket；**密封（sealed）** 配置（不注入主机凭据、关闭网络）只需一个开关。
-- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Gemini / OpenCode 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
+- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Antigravity / Gemini / OpenCode 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
 - **迁移到另一台机器** —— 把容器的完整环境（工具链 + 工作区）导出为可移植的 `.tar.gz`，在另一台机器上导入到新案例即可继续。
 - **持久耐用** —— Codeman 重启后重连会回到同一个存活的智能体；容器停止/重启后则从绑定挂载的转录恢复对话。
 
@@ -577,7 +581,7 @@ URL 被刻意保持精简（`/q/` 路径 + 6 字符码 ≈ 53–56 个字符）
 
 ## 安全
 
-Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。（启动权限模式可配置，见下文。）近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。**发现了漏洞？** 私下披露方式与已知限制清单见 [`SECURITY.md`](SECURITY.md)。
+Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。（启动权限模式可配置，见下文。）近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。**发现了漏洞？** 私下披露方式与已知限制清单见 [`SECURITY.md`](.github/SECURITY.md)。
 
 ### 网络与访问
 
@@ -598,7 +602,7 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 
 ### 输入、文件与响应头
 
-- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `ANTIGRAVITY_*` / `GEMINI_*` / `GOOGLE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
 - **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 50 MB 原始与下载；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
 - **安全响应头** —— `Content-Security-Policy`（`default-src 'self'`，每个例外都逐条列举）、`X-Content-Type-Options: nosniff`、`X-Frame-Options: SAMEORIGIN`、HTTPS 下的 HSTS，以及**仅**对 `localhost` / `127.0.0.1` / `::1` 反射的 CORS
 
@@ -637,6 +641,8 @@ sc -l           # 列出会话
 | `Alt/Option+[` / `Alt/Option+]` | 上一个 / 下一个会话                                      |
 | `Alt/Option+1`–`Alt/Option+9`   | 切换到第 N 个标签（按物理键位，macOS Option 布局也适用） |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移                                    |
+| `Ctrl/Cmd+C`                    | 复制选中内容；未选中时中断代理                           |
+| `Ctrl+Shift+C`                  | 复制选中内容（永不中断）                                 |
 | `Ctrl/Cmd+L`                    | 清屏                                                     |
 | `Ctrl+Shift+R`                  | 恢复终端尺寸                                             |
 | `Ctrl+Shift+V`                  | 切换语音输入                                             |
@@ -720,7 +726,6 @@ codeman session start -d /path/to/repo   # (s)  启动会话
 codeman session list                     #      列出会话
 codeman session logs <id>                #      查看输出
 codeman task add "fix the failing test"  # (t)  排入任务
-codeman ralph start --min-hours 8        # (r)  启动自主循环
 codeman attach <path>                    #      附着 Claude hook 上下文
 ```
 
@@ -757,13 +762,6 @@ Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission
 | `POST` | `/api/sessions/:id/respawn/stop`   | 停止控制器           |
 | `PUT`  | `/api/sessions/:id/respawn/config` | 更新配置             |
 
-### Ralph / Todo
-
-| 方法   | 端点                             | 说明                 |
-| ------ | -------------------------------- | -------------------- |
-| `GET`  | `/api/sessions/:id/ralph-state`  | 获取循环状态 + todos |
-| `POST` | `/api/sessions/:id/ralph-config` | 配置跟踪             |
-
 ### 编排器（Orchestrator）
 
 | 方法   | 端点                        | 说明            |
@@ -804,6 +802,8 @@ Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission
 | `POST` | `/api/clipboard`                | 把文本推送到所有已连接浏览器（`{text}`） |
 | `GET`  | `/api/sessions/:id/run-summary` | 时间线 + 统计                            |
 
+> **想在 Codeman 之上做集成？**[`docs/extending-codeman.md`](docs/extending-codeman.md)（英文）是集成指南：把你自己的界面作为标签页嵌入、订阅 SSE 事件流以便在 agent 需要你时做出响应、用脚本驱动 Codeman，以及动手前值得先了解的那些坑。Codeman 刻意不提供插件运行时，所以一个集成就是你自己的进程在讲 HTTP。
+
 ---
 
 ## 架构
@@ -826,7 +826,6 @@ flowchart TB
         end
 
         subgraph Detection["检测层"]
-            RT["Ralph 跟踪器"]
             SW["子智能体监视器<br/><small>~/.claude/projects/*/subagents</small>"]
             TW["团队监视器<br/><small>~/.claude/teams/*</small>"]
         end
@@ -837,7 +836,7 @@ flowchart TB
         end
 
         subgraph External["外部"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini</small>"]
             BG["后台智能体<br/><small>(Task 工具)</small>"]
         end
     end
@@ -850,7 +849,6 @@ flowchart TB
     SM --> RC
     SM --> ORC
     SM --> SS
-    S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR

config/vitest.ci.config.ts

@@ -24,6 +24,7 @@ export default defineConfig({
       'test/inline-rename.test.ts', // browser (Playwright)
       'test/opencode-resize.test.ts', // browser (Playwright)
       'test/webgl-fallback.test.ts', // browser (Playwright)
+      'test/terminal-copy-shortcut.test.ts', // browser (Playwright)
     ],
     setupFiles: ['./test/setup.ts'],
     fileParallelism: false,

docker/agent.Dockerfile

@@ -26,8 +26,8 @@ RUN apt-get update \
       openssh-client \
  && rm -rf /var/lib/apt/lists/*
 
-# The agent CLIs (all four backends Codeman supports). Pinning is left to the
-# rebuild cadence (see docs/docker-cases-plan.md, user-decision 2).
+# The npm-published agent CLIs. Pinning is left to the rebuild cadence (see
+# docs/docker-cases-plan.md, user-decision 2).
 RUN npm install -g \
       @anthropic-ai/claude-code \
       @openai/codex \
@@ -35,6 +35,15 @@ RUN npm install -g \
       opencode-ai \
  && npm cache clean --force
 
+# Antigravity (`agy`) is NOT on npm — Google ships a standalone binary through its
+# own installer, so it needs its own step. `--dir /usr/local/bin` is load-bearing:
+# the installer's default target is `$HOME/.local/bin`, which at build time is
+# root's home and would be unreachable by the `agent` user the container runs as.
+# ⚠️ This binary is ~190MB on its own; it is the single largest layer in the image.
+RUN curl -fsSL https://antigravity.google/cli/install.sh | bash -s -- --dir /usr/local/bin \
+ && chmod 755 /usr/local/bin/agy \
+ && agy --version
+
 # `agent` user (gid 0) with an arbitrary-uid-writable HOME. The uid is
 # auto-assigned (node:22-slim already occupies uid 1000 with its `node` user); at
 # runtime Codeman overrides with `--user <hostUid>:0` on Linux, so the baked uid
@@ -50,7 +59,8 @@ ENV HOME=/home/agent
 # dirs: tokens/settings/config are seeded in as writable copies and each CLI's runtime
 # state (backups, tasks, refreshed tokens) stays container-local, while ONLY the shared
 # transcript/rollout dirs (`.claude/projects`, `.codex/sessions`) are bind-mounted from
-# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir.)
+# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir;
+# Antigravity nests its state inside `.gemini/antigravity-cli`, so it rides that seed.)
 RUN useradd -g 0 -m -d /home/agent -s /bin/bash agent \
  && mkdir -p /home/agent/.npm /home/agent/.cache /home/agent/.config /home/agent/.codeman \
       /home/agent/.claude/projects /home/agent/.codex/sessions \

docs/claude-code-hooks-reference.md

@@ -2,14 +2,18 @@
 
 > Official documentation for Claude Code hooks system, extracted from [code.claude.com](https://code.claude.com/docs/en/hooks).
 
-**Last Updated**: 2026-01-24
+**Last Updated**: 2026-07-25
 **Source**: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
 
+> This is a maintained summary, not an exhaustive copy of the upstream reference.
+> Check the source link for event-specific schemas before adding a new hook.
+
 ---
 
 ## Overview
 
 Hooks are automated scripts that execute at specific events during your Claude Code session. They allow you to:
+
 - Validate, modify, or block tool usage
 - Add context to prompts
 - Implement custom workflows
@@ -21,12 +25,12 @@ Hooks are automated scripts that execute at specific events during your Claude C
 
 Hooks are configured in settings files:
 
-| File | Scope |
-|------|-------|
-| `~/.claude/settings.json` | User (global) |
-| `.claude/settings.json` | Project |
+| File                          | Scope                      |
+| ----------------------------- | -------------------------- |
+| `~/.claude/settings.json`     | User (global)              |
+| `.claude/settings.json`       | Project                    |
 | `.claude/settings.local.json` | Local project (gitignored) |
-| Plugin hook files | Plugin-specific |
+| Plugin hook files             | Plugin-specific            |
 
 ### Basic Structure
 
@@ -49,8 +53,9 @@ Hooks are configured in settings files:
 ```
 
 **Key Fields**:
+
 - `matcher`: Pattern to match tool names (case-sensitive, supports regex like `Edit|Write` or `*` for all)
-- `type`: `"command"` for bash or `"prompt"` for LLM-based evaluation
+- `type`: `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` where the event supports it
 - `command`: Bash command to execute
 - `prompt`: LLM prompt for evaluation (prompt-based hooks only)
 - `timeout`: Optional timeout in seconds (default: 60)
@@ -59,6 +64,10 @@ Hooks are configured in settings files:
 
 ## Hook Events
 
+Claude Code's current event surface is broader than the detailed subset below. In
+particular, `TeammateIdle` and `TaskCompleted` are supported lifecycle events used
+by Codeman; they are not stale or plugin-defined event names.
+
 ### PreToolUse
 
 **When**: After Claude creates tool parameters, before processing the tool call.
@@ -66,15 +75,17 @@ Hooks are configured in settings files:
 **Use Cases**: Approval, denial, or modification of tool calls.
 
 **Common Matchers**:
+
 - `Bash` - Shell commands
 - `Write` - File writing
 - `Edit` - File editing
 - `Read` - File reading
-- `Task` - Subagent tasks
+- `Agent` - Subagent tasks
 - `WebFetch`, `WebSearch` - Web operations
 - `mcp__<server>__<tool>` - MCP tools
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -96,13 +107,14 @@ Hooks are configured in settings files:
 **Use Cases**: Auto-approve or deny permissions.
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "PermissionRequest",
     "decision": {
       "behavior": "allow|deny",
-      "updatedInput": { },
+      "updatedInput": {},
       "message": "deny reason",
       "interrupt": false
     }
@@ -117,6 +129,7 @@ Hooks are configured in settings files:
 **Use Cases**: Provide feedback, run formatters/linters, log operations.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -128,15 +141,30 @@ Hooks are configured in settings files:
 }
 ```
 
+#### Asynchronous Rewake
+
+Command hooks can set `"asyncRewake": true` to run asynchronously and wake an
+idle Claude turn when the hook exits with code 2. The hook's stderr is delivered
+to Claude as a system reminder. This implies `"async": true`; ordinary async
+hooks do not wake an idle turn, and their output waits for the next interaction.
+
+Codeman uses this on `PostToolUse(Bash)`: a self-contained Node helper extracts
+the background task ID from the Bash result, watches the session transcript for
+the matching completion notification, and exits 2. It does not send terminal
+input, so it cannot submit a user's partially written prompt.
+
 ### Notification
 
 **When**: When Claude Code sends notifications.
 
 **Matchers**:
+
 - `permission_prompt`
 - `idle_prompt`
 - `auth_success`
 - `elicitation_dialog`
+- `elicitation_complete`
+- `elicitation_response`
 
 ### UserPromptSubmit
 
@@ -145,6 +173,7 @@ Hooks are configured in settings files:
 **Use Cases**: Add context, validate, or block prompts.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -165,6 +194,7 @@ Hooks are configured in settings files:
 **Use Cases**: **Ralph Wiggum loops** - block exit and refeed prompt.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -173,6 +203,7 @@ Hooks are configured in settings files:
 ```
 
 Or to allow exit:
+
 ```json
 {
   "continue": true,
@@ -184,15 +215,32 @@ Or to allow exit:
 
 ### SubagentStop
 
-**When**: When a subagent (Task tool call) finishes responding.
+**When**: When a subagent (Agent tool call) finishes responding.
 
 **Use Cases**: Control nested loops, verify subagent output.
 
+### TeammateIdle
+
+**When**: When an agent-team teammate is about to go idle.
+
+**Use Cases**: Reassign work, continue a teammate loop, or notify an orchestrator.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
+### TaskCompleted
+
+**When**: When a task is about to be marked completed.
+
+**Use Cases**: Validate completion or forward team progress to an external UI.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
 ### PreCompact
 
 **When**: Before a compact operation.
 
 **Matchers**:
+
 - `manual` - Invoked from `/compact`
 - `auto` - Invoked from auto-compact
 
@@ -201,6 +249,7 @@ Or to allow exit:
 **When**: When Claude Code starts or resumes a session.
 
 **Matchers**:
+
 - `startup` - Fresh start
 - `resume` - From `--resume`, `--continue`, or `/resume`
 - `clear` - From `/clear`
@@ -209,6 +258,7 @@ Or to allow exit:
 **Use Cases**: Load development context, set environment variables.
 
 **Persisting Environment Variables**:
+
 ```bash
 #!/bin/bash
 if [ -n "$CLAUDE_ENV_FILE" ]; then
@@ -219,6 +269,7 @@ exit 0
 ```
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -233,6 +284,7 @@ exit 0
 **When**: When a session ends.
 
 **Reason Values**:
+
 - `clear`
 - `logout`
 - `prompt_input_exit`
@@ -254,7 +306,7 @@ Hooks receive JSON via stdin with common fields:
   "permission_mode": "default",
   "hook_event_name": "PreToolUse",
   "tool_name": "Bash",
-  "tool_input": { },
+  "tool_input": {},
   "tool_use_id": "toolu_01ABC123..."
 }
 ```
@@ -262,6 +314,7 @@ Hooks receive JSON via stdin with common fields:
 ### Tool-Specific Input
 
 **Bash**:
+
 ```json
 {
   "tool_name": "Bash",
@@ -274,6 +327,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Write**:
+
 ```json
 {
   "tool_name": "Write",
@@ -285,6 +339,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Edit**:
+
 ```json
 {
   "tool_name": "Edit",
@@ -302,11 +357,11 @@ Hooks receive JSON via stdin with common fields:
 
 ### Exit Codes
 
-| Code | Behavior |
-|------|----------|
-| 0 | Success. `stdout` processed (shown in verbose or added as context) |
-| 2 | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
-| Other | Non-blocking error. `stderr` shown in verbose, execution continues |
+| Code  | Behavior                                                              |
+| ----- | --------------------------------------------------------------------- |
+| 0     | Success. `stdout` processed (shown in verbose or added as context)    |
+| 2     | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
+| Other | Non-blocking error. `stderr` shown in verbose, execution continues    |
 
 ### JSON Output (Exit Code 0)
 
@@ -323,7 +378,12 @@ Hooks receive JSON via stdin with common fields:
 
 ## Prompt-Based Hooks
 
-For Stop and SubagentStop events, you can use LLM-based evaluation:
+Prompt and agent handlers are supported by decision-oriented events including
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`,
+`PostToolBatch`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `TaskCreated`, and
+`TaskCompleted`. Check the upstream reference before choosing a handler type.
+
+For example, a Stop event can use LLM-based evaluation:
 
 ```json
 {
@@ -344,6 +404,7 @@ For Stop and SubagentStop events, you can use LLM-based evaluation:
 ```
 
 **LLM Response Format**:
+
 ```json
 {
   "ok": true,
@@ -362,17 +423,18 @@ Hooks can be defined in Skills, Agents, and Slash Commands using frontmatter:
 name: secure-operations
 hooks:
   PreToolUse:
-    - matcher: "Bash"
+    - matcher: 'Bash'
       hooks:
         - type: command
-          command: "./scripts/security-check.sh"
+          command: './scripts/security-check.sh'
 ---
 ```
 
 These hooks:
+
 - Are scoped to the component's lifecycle
 - Only run when that component is active
-- Support: PreToolUse, PostToolUse, Stop
+- Support all hook events; a subagent-scoped `Stop` is converted to `SubagentStop`
 
 ---
 
@@ -550,11 +612,11 @@ exit 0
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `CLAUDE_PROJECT_DIR` | Project root directory |
-| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI |
-| `CLAUDE_ENV_FILE` | Path to write persistent env vars (SessionStart) |
+| Variable             | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `CLAUDE_PROJECT_DIR` | Project root directory                           |
+| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI                  |
+| `CLAUDE_ENV_FILE`    | Path to write persistent env vars (SessionStart) |
 
 ---
 
@@ -593,4 +655,4 @@ Use `/hooks` command to view registered hooks and make changes.
 
 ---
 
-*Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)*
+_Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)_

docs/cron-discovery.md

@@ -44,9 +44,9 @@ records), kept distinct from the existing `ScheduledRun`.
 
 ## 2. Where agent/session types are defined
 
-- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`
+- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity'`
   (`src/types/session.ts:43-44`). `shell` covers the brief's "Terminal/custom".
-- CLI availability resolvers in `src/utils/{claude,codex,gemini,opencode}-cli-resolver.ts`.
+- CLI availability resolvers in `src/utils/{claude,codex,gemini,antigravity,opencode}-cli-resolver.ts`.
 - **Integration point:** the job's `agentType` reuses `SessionMode` verbatim.
 
 ## 3. Where input is sent into a session

docs/cron-guide.md

@@ -1,7 +1,7 @@
 # Cron Jobs — User & Operator Guide
 
 Codeman's **Cron** feature lets you save named, recurring jobs that automatically
-spin up a Claude (or shell / OpenCode / Codex / Gemini) session on a schedule and
+spin up a Claude (or shell / OpenCode / Codex / Antigravity / Gemini) session on a schedule and
 feed it a prompt. Think "cron for agent sessions": _"every weekday at 3am, open a
 Claude session in `~/proj` and tell it to update dependencies and open a PR."_
 
@@ -91,7 +91,7 @@ These map 1:1 to `CronJobSchema` (`src/web/schemas.ts`) and the `CronJob` type
 | Field                      | Required    | Values / limits                                          | Notes                                                                                                                                                                                      |
 | -------------------------- | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `name`                     | ✅          | 1–200 chars                                              | Display name; also used as the created session's name.                                                                                                                                     |
-| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal.                                                                                                                                |
+| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` \| `antigravity` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal.                                                                                                                                |
 | `workingDir`               | ✅          | valid path (allowlist-validated)                         | Validated at **create/update** (must exist, be a directory, and not resolve into a blocked tree — `/etc`, `/root`, `/proc`, `/sys`, `/dev`, or `/` itself) and again **at fire time**.     |
 | `launchCommand`            | —           | ≤ 2000 chars, single line                                | `shell` mode only: sent as the **first input line** once the shell is up, before the prompt. Ignored for other agent types.                                                                |
 | `promptMode`               | ✅          | `inline_text` \| `prompt_file_path`                      | See §5.                                                                                                                                                                                    |

docs/docker-cases.md

@@ -2,7 +2,7 @@
 
 Run a case inside an **isolated Docker container** instead of directly on the host. Any number of Codeman sessions can share one container (it is scoped to the case, not the session), so a whole project lives in a sandbox with its own network, resource caps, and filesystem, and you can **export the container to move it to another machine**.
 
-Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` all work inside the container.
+Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` / `antigravity` all work inside the container.
 
 ## One-time setup: build the base image
 
@@ -15,6 +15,21 @@ node scripts/build-agent-image.mjs          # builds codeman/agent:base
 
 The image is **secret-free**: credentials are delivered at runtime (bind mounts or `docker exec --env`), never baked in, so exports never leak them.
 
+⚠️ **Re-build with `--no-cache`, always.** The CLIs are installed in a single `RUN npm install -g` layer, so a plain rebuild re-uses it from the Docker layer cache and the CLIs stay frozen at whatever versions the image was **first** built with, however long ago that was. Editing the Dockerfile does not help unless the edit lands at or above that line: a change appended below it leaves the npm layer cached and only runs the new step. Observed 2026-08-06: a rebuild silently kept a stale `@openai/codex@0.144.6` whose aliased platform binary had not installed, so every `codex` docker case died with `Missing optional dependency @openai/codex-linux-x64` while the build itself reported success.
+
+```bash
+node scripts/build-agent-image.mjs --no-cache
+```
+
+A zero exit code only proves the layers ran, not that the toolchain works. Verify by actually executing each CLI in the image, and check the build log for `Using cache` lines:
+
+```bash
+docker run --rm codeman/agent:base bash -lc \
+  'for c in claude codex gemini opencode agy; do printf "%-9s " $c; $c --version 2>&1 | head -1; done'
+```
+
+Antigravity (`agy`) is the one CLI not installed from npm (Google ships a standalone binary), so it has its own Dockerfile step and adds roughly 190MB; a full image lands near 1.6GB.
+
 ## Quickest path: one-click "Run in Docker"
 
 On the **New case → Create New** tab there's a **🐳 Run in an isolated Docker container** checkbox. Checking it alone is enough: Codeman creates the case folder in `~/codeman-cases/<name>`, spins up a hardened container with sensible defaults (auto-provisioning a shared `default` host), and starts the session inside it. No host/image/network fields to fill in.

docs/extending-codeman.md

@@ -0,0 +1,255 @@
+# Extending Codeman
+
+Codeman has no plugin runtime, and that is a deliberate choice rather than a
+missing feature. A plugin runtime means running third-party code inside a process
+that spawns agents with your credentials, on a server people routinely expose
+over a tunnel or Tailscale. Codeman's security model is one of its reasons to
+exist, so it does not hand that away for an extension mechanism.
+
+Instead there are four seams that already work, from any language, with nothing
+installed:
+
+| You want to | Use | Runs where |
+| --- | --- | --- |
+| Show your own UI inside Codeman | [Web tabs](#seam-1-web-tabs) | Your own process, rendered as a tab |
+| React when an agent needs you | [SSE events](#seam-2-sse-events) | Anywhere that can hold an HTTP connection |
+| Drive Codeman from a script | [HTTP API](#seam-3-http-api-and-cli) or the `codeman` CLI | Anywhere |
+| React inside a Claude session | [Hooks](#seam-4-hooks) | The agent's own machine |
+
+Everything below is covered by the stability promise in
+[`versioning-policy.md`](versioning-policy.md): endpoint paths, the response
+envelope, `errorCode` values, and SSE event names are stable. Additive changes
+(new endpoints, new optional fields, new events) are non-breaking. Breaking
+changes ship under a new prefix (`/api/v2`).
+
+## Before you start
+
+**Base URL.** `http://127.0.0.1:3000` by default. Prefer the versioned prefix
+`/api/v1/...` for anything you publish; the unversioned `/api/...` is an alias.
+
+**Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic on every request, or
+authenticate once and keep the `codeman_session` cookie. With no password set,
+Codeman is loopback-only and unauthenticated.
+
+```bash
+curl -u admin:$CODEMAN_PASSWORD http://127.0.0.1:3000/api/v1/sessions
+```
+
+**Envelope.** Every response is `{"success": true, "data": ...}` or
+`{"success": false, "error": "...", "errorCode": "..."}`. Check the HTTP status
+or `body.success`, then read `body.data`. The full `errorCode` to status mapping
+is in [`api-reference.md`](api-reference.md).
+
+⚠️ A few legacy GETs (`/api/away-digest` among them) return a bare-ish body with
+the payload at the top level rather than under `data`. Read defensively with
+`body.data ?? body`.
+
+**Already driving Codeman from an agent?** The README's
+[Programmatic Guide](../README.md#driving-codeman-from-an-agent--programmatic-guide)
+covers the in-session case: the `CODEMAN_MUX`, `CODEMAN_API_URL`,
+`CODEMAN_SESSION_ID` and `CODEMAN_HOOK_SECRET_FILE` variables that let a CLI
+running inside Codeman find the API and avoid acting on itself. This page is for
+code running *outside* a session.
+
+## Seam 1: Web tabs
+
+The highest-leverage seam. Any web app you can serve locally becomes a tab beside
+your agent sessions. You write a normal web page; Codeman handles embedding it.
+
+```bash
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/webviews \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"My Dashboard","url":"http://127.0.0.1:8787","icon":"📊"}'
+```
+
+Fields: `name` (1 to 60 chars), `url`, and optionally `icon` (a single glyph, max
+8 code units), `embedMode` (`proxy` by default, or `direct`), and `trusted`.
+
+Related endpoints: `GET /api/v1/webviews`, `PATCH /api/v1/webviews/:id`,
+`DELETE /api/v1/webviews/:id`, `POST /api/v1/webviews/probe` (reachability and
+framing check), `POST /api/v1/webviews/:id/open`.
+
+### Why it is proxied
+
+By default your page is served through Codeman's own origin at `/webview/:cap/*`
+rather than framed directly. A direct iframe fails three ways at once: production
+is HTTPS so `http://` targets are blocked as mixed content, many dashboards send
+`X-Frame-Options: DENY`, and Codeman's own `default-src 'self'` CSP blocks
+cross-origin frames. Proxying solves all three without weakening the CSP.
+
+### The two things that will confuse you
+
+A proxied frame is sandboxed and therefore **opaque-origin** unless you set
+`trusted: true`. Two consequences look like bugs in your own app:
+
+1. **Root-absolute URLs built at runtime** (`/assets/x.png` assembled in JS)
+   escape the injected `<base>` tag. Codeman injects a `runtimeUrlShim()` that
+   patches the common DOM sinks, but if you construct URLs in an unusual way,
+   prefer relative paths.
+2. **Same-host `fetch` and `XHR` are CORS-checked with `Origin: null`.** Codeman
+   handles this with `buildProxyCorsHeaders()`, and the proxy is exempt from the
+   global `OPTIONS` short-circuit. If you see "Failed to fetch" while the page
+   itself renders fine, this is the area to look at.
+
+⚠️ `trusted: true` opts out of the sandbox. A proxied page is served from
+Codeman's origin, so `allow-same-origin` lets it read the Codeman page and call
+the API that spawns agents. Only mark your own trusted code.
+
+## Seam 2: SSE events
+
+`GET /api/v1/events` is a Server-Sent Events stream. Each message is
+`event: <name>` plus `data: <json>`. There are 149 event names following a
+`domain:action` convention, registered in `src/web/sse-events.ts`.
+
+The ones most integrations want:
+
+| Event | Meaning |
+| --- | --- |
+| `session:created`, `session:deleted` | A session appeared or went away |
+| `session:idle` | The agent stopped working |
+| `session:completion` | A completion message was detected |
+| `session:exit`, `session:error` | The session ended or failed |
+| `hook:permission_prompt` | The agent is asking for permission |
+| `hook:idle_prompt`, `hook:stop` | The agent is waiting on you, or stopped |
+| `hook:task_completed`, `task:completed` | Work finished |
+| `subagent:discovered`, `subagent:completed` | Background agent lifecycle |
+| `mux:died` | A multiplexer session died unexpectedly |
+| `cron:runCreated`, `cron:runUpdated` | Scheduled job activity |
+
+### Filtering
+
+`?sessions=id1,id2` suppresses only the high-volume `session:terminal` stream for
+sessions you did not list. Lifecycle and metadata events are always delivered, so
+you cannot accidentally filter away the thing you are listening for.
+
+Pass `?clientId=<uuid>` to enable live filter updates through
+`POST /api/v1/events/subscribe` without reconnecting the stream.
+
+### Example: notify when any agent needs you
+
+```js
+const res = await fetch('http://127.0.0.1:3000/api/v1/events', {
+  headers: { Authorization: 'Basic ' + btoa(`admin:${process.env.CODEMAN_PASSWORD}`) },
+});
+const reader = res.body.getReader();
+const decoder = new TextDecoder();
+let buf = '';
+const WANTED = new Set(['hook:permission_prompt', 'hook:idle_prompt', 'session:idle']);
+
+for (;;) {
+  const { value, done } = await reader.read();
+  if (done) break;
+  buf += decoder.decode(value, { stream: true });
+  const frames = buf.split('\n\n');
+  buf = frames.pop() ?? '';
+  for (const frame of frames) {
+    const name = frame.match(/^event: (.+)$/m)?.[1];
+    const data = frame.match(/^data: (.+)$/m)?.[1];
+    if (name && WANTED.has(name)) notify(name, JSON.parse(data ?? '{}'));
+  }
+}
+```
+
+## Seam 3: HTTP API and CLI
+
+Around 199 handlers across 21 route files cover sessions, cases, files, cron,
+respawn, Ralph, the orchestrator, search, and admin. Each route module carries an
+`@fileoverview` describing its endpoints.
+
+The common ones:
+
+```bash
+# List sessions (live + persisted + transcript history, deduped)
+curl -u admin:$PASS http://127.0.0.1:3000/api/v1/sessions/unified
+
+# Create a session
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"workingDir":"/home/me/project","mode":"claude"}'
+
+# Send a prompt (single-line only)
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/sessions/$ID/input \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"run the tests","useMux":true}'
+```
+
+`POST .../input` also accepts `clientId` (stable per client, max 128 chars) and
+`seq` (monotonic per session). Send both and the server applies each pair
+at-most-once, so retrying after a dropped connection cannot type the prompt
+twice. Omit them entirely rather than sending `null`.
+
+For shell scripting, the `codeman` CLI is the same surface without the HTTP
+plumbing:
+
+```
+codeman session start|stop|list|logs     codeman task add|list|status|remove|clear
+codeman ralph start|stop|status|reset    codeman users add|passwd|list
+codeman status | list | attach <path>    codeman doctor
+```
+
+## Seam 4: Hooks
+
+Claude Code hooks post to `POST /api/v1/hook-event` from inside an agent session.
+Codeman installs its own hooks automatically, but the endpoint is open to yours.
+
+```json
+{ "event": "task_completed", "sessionId": "abc123", "data": { "any": "json" } }
+```
+
+`event` must be one of `permission_prompt`, `elicitation_dialog`, `idle_prompt`,
+`stop`, `teammate_idle`, `task_completed`. Each becomes the matching `hook:*` SSE
+event.
+
+⚠️ This endpoint skips Basic auth so hooks keep working, but when auth is active
+the loopback bypass requires the `X-Codeman-Hook-Secret` header
+(`~/.codeman/hook-secret`) unconditionally.
+
+## Gotchas
+
+Every one of these has cost somebody real time.
+
+- **CORS is localhost-only.** `Access-Control-Allow-Origin` is echoed only for
+  `localhost`, `127.0.0.1`, and `::1`. A browser app on any other origin cannot
+  call the API. Integrate server-side.
+- **A missing `Origin` header is allowed**, which is why curl, CLIs, and hooks
+  work. Cross-site origins are blocked by the CSRF guard.
+- **Reverse-proxy domains are rejected** by the anti-DNS-rebinding Host allowlist
+  unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`.
+- **`null` is not `undefined`.** Request schemas use Zod `.optional()`, which
+  accepts `undefined` only. `JSON.stringify({ field: null })` keeps the null on
+  the wire and fails with `INVALID_INPUT`. Omit the key instead. This has caused
+  shipped bugs more than once.
+- **`text/plain` bodies stay raw.** Auto-parsing them as JSON enabled
+  simple-request CSRF, so it is deliberate. Send `application/json`.
+- **Prompts are single-line.** With `useMux: true` the server delivers your text
+  and then Enter as two separate writes, so you do not append `\r` yourself. A
+  multi-line string breaks the agent's Ink-based input handling: send one line,
+  or split it across calls.
+- **Unwrap the envelope** before reading fields. `data` is not the response body.
+
+## Publishing your integration
+
+There is no registry and no review queue. Add the GitHub topic
+**`codeman-integration`** to your public repository so others can find it, and
+link back to Codeman in your README.
+
+If a real ecosystem of these appears, a manifest format and an install command
+become worth building. Until then, these four seams are the contract, and they
+require nothing of you but HTTP.
+
+## What Codeman deliberately does not have
+
+- **No in-process plugin runtime.** See the reasoning at the top of this page.
+- **No build or startup hooks** for third-party code. Run your own process.
+- **No per-plugin config or state directories.** Manage your own files.
+- **No sandbox for integration code**, because Codeman never launches it. Your
+  integration is your own process, started by you, with your permissions,
+  talking HTTP.
+
+That last point is about integration code specifically, not about Codeman.
+Sandboxing lives on a different axis here: the thing worth isolating is the
+**agent**, and you isolate it per case with
+[Docker cases](docker-cases.md), which run the agent in a hardened container with
+a bind-mounted workspace and seeded (not shared) credentials. An integration that
+creates or drives a Docker-backed session inherits that isolation for free, since
+it is a property of the session rather than of the caller.

docs/file-viewer-edit-plan.md

@@ -0,0 +1,432 @@
+# File Viewer edit mode (issue #212)
+
+Plan only. No implementation yet.
+
+Goal: close the loop "agent writes a file, you review it in the viewer, tweak two lines, save, tell the
+agent to continue" without hopping into the terminal, with the phone as the primary target.
+
+Scope from the issue: an Edit toggle on text previews, a write endpoint that inherits the read path's
+confinement, text-only, edit-in-place (no create, no delete, no rename), no editing through the
+Docker/remote overlays.
+
+---
+
+## 1. What exists today
+
+**Read path (backend), all in `src/web/routes/file-routes.ts`:**
+
+| Route                                | Line   | Notes                                                              |
+| ------------------------------------ | ------ | ------------------------------------------------------------------ |
+| `GET /api/sessions/:id/files`        | `741`  | Tree scan of `session.workingDir`, hidden files off by default      |
+| `GET /api/sessions/:id/file-content` | `865`  | The text/preview classifier. `findSessionOrFail` + `validateSessionFilePath` |
+| `GET /api/sessions/:id/file-raw`     | `1018` | Bytes, 50MB cap                                                    |
+| `GET /api/sessions/:id/file-preview` | `1254` | DOCX/PPTX to PDF, everything else redirects to `file-raw`           |
+| `GET /api/download`                  | `1384` | The only read route that also runs `isSensitivePath()`              |
+
+`file-content` classification order (`file-routes.ts:881-1011`): extension buckets (image / video / audio /
+known-binary) return metadata only; otherwise the bytes are read, sniffed for a NUL in the first 8KB, and
+either reported as `type:'binary'` or decoded as UTF-8 and **truncated to `lines` (default 500, hard cap
+10000)**. Caps: `MAX_TEXT_FILE_SIZE` 10MB.
+
+Confinement is `validateSessionFilePath()` (`src/web/route-helpers.ts:67`): `resolve()` then `realpathSync()`
+then reject if the result is not under `workingDir`. Because it realpaths the *full* path, a symlink whose
+target escapes the workspace is already rejected. Ownership is `findSessionOrFail()` which runs
+`canAccessOwned()` (`route-helpers.ts:102`), a no-op outside multi-user mode.
+
+**Read path (frontend), `src/web/public/panels-ui.js`:**
+
+- `loadFileBrowser()` `2947`, `renderFileBrowserTree()` `2978`, click to `openFilePreview()` `3056`.
+- `openFilePreview(filePath, sessionId, attachmentId)` `3193`: attachment-id branch, then docx/pptx, pdf,
+  svg branches, then the generic `file-content` fetch at `3274` with **`&lines=500` hardcoded**, rendering
+  text as `<pre><code>${escapeHtml(...)}</code></pre>` at `3298` and stashing `this.filePreviewContent`.
+- `closeFilePreview()` `3308`, `copyFilePreviewContent()` `3751`.
+- Markup: `src/web/public/index.html:420-432` (`filePreviewOverlay` / `-Title` / `-Body` / `-Footer`, two
+  header buttons: copy and close).
+- CSS: `src/web/public/styles.css:9320-9430`. Overlay `z-index: 2000`, window `80vw/80vh`, capped
+  `900x700`. There are **no `.file-preview-*` rules in `mobile.css` at all**.
+
+**Reachability on phones.** The header File Viewer button is hidden below 430px
+(`mobile.css:482`, locked by `KNOWN_PHONE_HIDDEN` in `test/mobile-header-buttons-policy.test.ts`), so on a
+phone the preview overlay is reached through:
+
+1. an attachment card's **Preview** button (`panels-ui.js:3451`), which is exactly the "agent just wrote a
+   file" path the issue describes,
+2. the attachment-history drawer (`panels-ui.js:3709`),
+3. App Settings to Panels to **File Browser** (`showFileBrowser`, applied in `settings-ui.js:2202`; the
+   panel is mobile-styled at `mobile.css:1868`).
+
+So edit mode is reachable on a phone today via (1) and (2) without touching the header policy. Improving
+the entry point is listed as an open decision in section 10, not assumed.
+
+---
+
+## 2. Threat model, stated honestly
+
+Anyone who can call this API can already reach `POST /api/sessions/:id/input` and type an arbitrary prompt
+into an agent running with `--dangerously-skip-permissions`. A workspace-confined write endpoint therefore
+does not create a new privilege tier for an authenticated caller.
+
+What it *would* create if built carelessly is a **new host-write primitive reachable by path**, so the
+things this plan actually defends against are:
+
+1. **Path traversal / symlink escape** writing outside the workspace.
+2. **TOCTOU**: a path component that becomes a symlink between validation and write.
+3. **Cross-user writes** in multi-user mode (`canAccessOwned`).
+4. **Silent data loss**, which is the highest-probability real-world failure here and gets its own section.
+
+CSRF is already covered: `registerHostGuard()` (`src/web/middleware/auth.ts:555-578`) rejects any
+non-safe-method request whose `Origin` is cross-site. The webview-capability exemption at that gate is
+fenced to `GET`/`HEAD` for the Referer form (`auth.ts:161`) and to `/webview/:cap/*` paths for the path
+form, so a proxied dashboard cannot reach a new `PUT /api/...`. Using `PUT` + `application/json` also
+forces a preflight for any cross-origin attempt.
+
+---
+
+## 3. Backend design
+
+### 3.1 New policy module: `src/config/file-editing.ts`
+
+Pure, unit-testable, no IO (config lives in `src/config/`, no barrel, import the file directly).
+
+```ts
+export const MAX_EDITABLE_BYTES = 512 * 1024;      // content cap, both directions
+export const EDITABLE_EXTENSIONS: ReadonlySet<string>;  // ts,tsx,js,jsx,mjs,cjs,json,jsonc,md,mdx,txt,
+                                                        // css,scss,less,html,htm,xml,svg?,yml,yaml,toml,
+                                                        // ini,cfg,conf,env?,sh,bash,zsh,fish,py,rb,go,rs,
+                                                        // java,kt,swift,c,h,cpp,hpp,cs,php,sql,graphql,
+                                                        // proto,lua,pl,r,jl,tf,gradle,csv,tsv,log,diff,patch
+export const EDITABLE_BASENAMES: ReadonlySet<string>;   // Dockerfile, Makefile, LICENSE, .gitignore,
+                                                        // .prettierignore, .editorconfig, .nvmrc, ...
+export function isEditableFileName(fileName: string): boolean;
+export function isDeniedEditRelativePath(rel: string): boolean;  // `.git/` subtree
+export function detectEol(text: string): 'lf' | 'crlf';
+export function applyEol(text: string, eol: 'lf' | 'crlf'): string;
+```
+
+Decisions baked in:
+
+- **Allowlist, not blocklist**, per the issue and per the existing attachment-guard precedent.
+- `svg` and `env` are deliberately marked with `?` above: `svg` is served as an untrusted octet-stream on
+  the read side (`file-routes.ts:118`) so allowing an edit is defensible, but I recommend **excluding
+  both** in v1. `.env` files are matched by `isSensitivePath()` anyway and would be rejected downstream;
+  excluding them at the allowlist keeps a single obvious refusal.
+- `isDeniedEditRelativePath` blocks the `.git/` subtree: `.git/hooks/*` is code execution and a corrupt
+  index is unrecoverable-looking to a user who only wanted to fix a typo. Other dotfiles stay allowed but
+  are not reachable from the tree UI anyway (`showHidden=false`).
+
+### 3.2 Read-for-edit: extend the existing GET
+
+`GET /api/sessions/:id/file-content?path=<rel>&edit=1`
+
+When `edit=1`:
+
+- skip line truncation entirely (a truncated buffer must never become an edit buffer, see section 4.1),
+- enforce `MAX_EDITABLE_BYTES` instead of `MAX_TEXT_FILE_SIZE` and answer 413 over it (as a structured
+  throw with `statusCode: 413`, the `throwFilesystemPickerError` pattern, since the central errorCode-to-
+  status map has no 413 entry; see the error-mechanics note in 3.3),
+- run the editability gate (`isEditableFileName`, `isDeniedEditRelativePath`, `isSensitivePath`,
+  `isBlockedAttachmentPath`) and the content gate (NUL sniff plus UTF-8 round-trip, see 4.3),
+- return `{ content, size, mtimeMs, totalLines, truncated: false, extension, editable: true, hash, eol }`.
+  `hash` is `sha256` hex of the exact on-disk bytes.
+
+Non-`edit` responses gain **only** `editable: boolean` (additive, no shape change for existing consumers),
+which is all the UI needs to decide whether to show the Edit button. No `hash` on plain reads: the Edit
+action re-fetches with `edit=1` anyway (section 4.1), which is where the hash comes from, and hashing every
+casual 10MB preview would be pure waste.
+
+### 3.3 Write: `PUT /api/sessions/:id/file-content`
+
+Body (new `FileWriteSchema` in `src/web/schemas.ts`, Zod v4):
+
+```ts
+{ path: string, content: string, baseHash: string, eol?: 'lf'|'crlf', force?: boolean }
+```
+
+Registered with an explicit route option `{ bodyLimit: 4 * 1024 * 1024 }`. **Fastify's default `bodyLimit`
+is 1MB and this repo configures none**, and JSON escaping expands content: 2x for a file full of quotes or
+backslashes, up to 6x for control characters (each serialized as a `\uXXXX` escape), so 512KB of content
+can legitimately exceed 1MB on the wire; blowing the limit produces a raw `FST_ERR_CTP_BODY_TOO_LARGE`, not an `ApiResponse` envelope. Two
+related sizing notes: `z.string().max()` counts **UTF-16 code units, not bytes**, so the schema's `.max()`
+is only a coarse pre-filter and the real cap is an explicit `Buffer.byteLength(content, 'utf8')` check in
+the handler (step 7a below); and 4MB comfortably bounds the worst-case expansion of a 512KB file without
+inviting multi-MB bodies elsewhere.
+
+**Error mechanics** (matters for both prod behavior and testability): a handler that *returns* a
+`{success:false, errorCode}` envelope gets its HTTP status assigned centrally by the preSerialization hook
+in `server.ts` (`httpStatusForErrorCode()`, `src/types/api.ts`), but the route-test harness
+(`test/routes/_route-test-utils.ts`) installs only `installRouteErrorHandler`, **not** that hook, so
+returned envelopes surface as HTTP 200 in tests. The PUT handler should therefore use the same
+structured-**throw** pattern as the filesystem picker (`throwFilesystemPickerError`, `file-routes.ts:411`):
+thrown `{statusCode, body}` errors are rendered identically in prod and in the harness, and they allow the
+one status the code map cannot express (413). The error envelope itself is strictly
+`{success:false, error, errorCode}`, **it has no data arm**, so no error response may carry extra payload.
+
+Handler order (each step is a test case):
+
+1. `findSessionOrFail(ctx, id, req)` (live sessions only, matching the read route, and it carries the
+   multi-user ownership check).
+2. `parseBody(FileWriteSchema, req.body)`, then `Buffer.byteLength(content, 'utf8') <= MAX_EDITABLE_BYTES`
+   or 413 (the schema `.max()` alone cannot enforce a byte cap, see the sizing note above).
+3. `validateSessionFilePath(session.workingDir, path)` or 404 (do not distinguish "outside workspace" from
+   "missing", matching the read route).
+4. `isSensitivePath(resolvedPath) || isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)` or 403.
+5. `isDeniedEditRelativePath(relativePath)` or 403.
+6. `isEditableFileName(basename(resolvedPath))` or 400.
+7. `stat`: must be `isFile()`, size within `MAX_EDITABLE_BYTES`, else 400/413. **No `O_CREAT` anywhere in
+   this handler**, which is what enforces edit-in-place.
+8. Read current bytes, compute `hash`, run the NUL sniff and the UTF-8 round-trip check, else 400.
+9. `hash !== baseHash && !force` gives **409 CONFLICT** (`ApiErrorCode.CONFLICT`, plain envelope; the error
+   arm carries no data, see the error-mechanics note). The client's conflict dialog gets fresh state by
+   re-fetching `edit=1`, which it needs for its Reload action anyway.
+10. Build the output buffer: `applyEol(content, eol ?? detected-from-original)`; re-check
+    `Buffer.byteLength` against the cap.
+11. Write atomically in the resolved parent directory:
+    `fs.open(<dir>/.<name>.codeman-tmp-<rand>, 'wx', stat.mode & 0o777)`, then `fchmod(stat.mode & 0o777)`
+    (open's mode argument is masked by the process umask, so the chmod is what actually preserves an
+    unusual mode), write, `fsync`, close, `fs.rename(tmp, resolvedPath)`, unlink the temp on any failure.
+12. Re-stat, return `{ success: true, data: { path, size, mtimeMs, hash, totalLines } }`.
+
+Why `O_EXCL` temp plus rename rather than truncate-in-place:
+
+- `wx` cannot follow a pre-existing symlink, which closes the TOCTOU window from step 3 to step 11 without
+  needing `O_NOFOLLOW` gymnastics.
+- `rename()` does not follow a symlink in the final component, so even if `resolvedPath` were swapped for a
+  symlink after validation, the symlink itself is replaced and the swap target is untouched.
+- A crash mid-write leaves the original intact.
+
+Caveat to document in the code comment: rename replaces the inode, so hardlinks to the file keep the old
+content. That is the same trade-off vim makes by default and is preferable to a truncate window here.
+
+No SSE event in v1. Nothing else in the app needs to know: `image-watcher.ts` only reacts to
+`.png/.jpg/.jpeg/.gif/.webp/.bmp/.svg/.pdf/.docx/.pptx` adds (`image-watcher.ts:23-25`), none of which are
+editable text, and the temp filename does not match either.
+
+---
+
+## 4. The five traps
+
+These are the parts that turn a "small write endpoint" into a bug report.
+
+### 4.1 Truncation (the data-loss trap)
+
+The frontend fetches `&lines=500` (`panels-ui.js:3274`). Saving that buffer back would **delete every line
+past 500**. Worse, the content hash of the full file would still match, so an optimistic-concurrency check
+cannot catch it.
+
+Mitigations, all three:
+
+- The Edit affordance is only offered when the loaded payload came from `edit=1` (which never truncates).
+  Tapping Edit on an already-rendered preview **re-fetches** with `edit=1` before swapping in the editor.
+- The read-for-edit path 413s above `MAX_EDITABLE_BYTES` rather than truncating, so "too big to edit here"
+  is an explicit refusal with a message, never a silent partial buffer.
+- A test asserts `edit=1` never returns `truncated: true`.
+
+### 4.2 Line endings
+
+A `<textarea>`'s `.value` normalizes to LF. Saving a CRLF file naively rewrites every line, producing a
+whole-file diff for a two-line change. So: the read returns the detected `eol`, the client echoes it back
+unchanged, and the server re-applies it. Mixed-EOL files use the dominant style, which is lossy for the
+minority lines; call that out in the response and accept it in v1.
+
+### 4.3 Encoding
+
+`buf.toString('utf-8')` on a latin-1 or otherwise non-UTF-8 file yields U+FFFD replacement characters, and
+writing that back **corrupts the file**. The check is a round-trip:
+`Buffer.from(decoded, 'utf8').equals(buf)`. If it fails, `editable: false` and the write is refused. This
+also catches binary content that the NUL sniff misses. A UTF-8 BOM survives because it round-trips as a
+leading U+FEFF; do not strip it.
+
+### 4.4 Concurrency with the agent
+
+The whole use case is editing a file the agent just wrote and may write again. `baseHash` plus 409 is the
+guard. Do not use mtime alone: agents rewrite files within a single filesystem timestamp tick, and an
+identical rewrite should not be reported as a conflict.
+
+### 4.5 Symlinks and TOCTOU
+
+Covered by `validateSessionFilePath` (escape) plus `wx` temp and `rename` (post-validation swap). One
+intentional allowance: a symlink whose target is *inside* the workspace is edited through to its target,
+because `validateSessionFilePath` returns the realpath. That matches what a user tapping the file expects.
+
+---
+
+## 5. Frontend design
+
+All in `panels-ui.js` (prettier-exempt, hand-formatted; match the surrounding style), `index.html`,
+`styles.css`, `mobile.css`.
+
+### 5.1 State
+
+```js
+filePreviewEdit = { active, sessionId, path, baseHash, eol, original, dirty }
+```
+
+Reset in `closeFilePreview()` and on every `openFilePreview()` entry.
+
+### 5.2 Markup (`index.html:420-432`)
+
+Add one header button (pencil, `btn-icon-sm`, `id="filePreviewEditBtn"`, hidden by default) next to the
+copy button, and an edit bar inside the footer region holding Save / Cancel / a dirty dot. Keep the
+existing footer text element; the edit bar is a sibling toggled by class so the read-mode footer is
+untouched.
+
+### 5.3 Behavior
+
+- `openFilePreview()` shows the Edit button only when the response has `editable: true` and the render took
+  the text branch. Attachment-id previews, media, binary, pdf, docx/pptx and svg all leave it hidden.
+- **Enter edit**: re-fetch with `edit=1`; on 413 or `editable:false`, toast the reason and stay in read
+  mode. This fetch must **parse the error envelope on non-ok responses**: the existing generic
+  `if (!res.ok) throw new Error('Failed to load file')` pattern (`panels-ui.js:3275`) would swallow the
+  specific "too large to edit here" message, since error envelopes arrive with real 4xx statuses in prod. On success replace the body with `<textarea class="file-preview-editor" spellcheck="false"
+  autocapitalize="off" autocorrect="off" autocomplete="off" wrap="off">` and assign `.value = content`
+  (never `innerHTML`, so no escaping question arises). Do **not** autofocus: on a phone that opens the
+  keyboard before the user has picked a line.
+- `input` sets `dirty` and enables Save.
+- **Save**: `PUT` with `baseHash`, `eol`, and `content`. On success update `baseHash`/`original` from the
+  response, leave edit mode, re-render the read view from the local editor value (the response carries
+  metadata only, not content), toast "Saved". On **409** offer `Reload (discard mine)` / `Overwrite`:
+  Reload re-fetches `edit=1` and replaces the buffer; Overwrite re-sends with `force: true`. The 409 body
+  itself carries no state (section 3.3, step 9).
+- **Cancel / close / Escape while dirty**: `confirm('Discard unsaved changes?')`, consistent with the
+  existing `window.confirm` usage in this codebase (`panels-ui.js:4323`, `app.js:4176`). Note the global
+  Escape handler (`app.js:999-1007`) closes other panels via `closeAllPanels()` but does not touch this
+  overlay today; if Escape-to-close is wired up as part of this work it must go through the same dirty
+  guard.
+- `copyFilePreviewContent()` copies the live editor value while editing.
+
+⚠️ Repo gotcha to respect at the fetch call: **Zod `.optional()` rejects `null`**. Build the body with
+`eol: eol ?? undefined` (or declare `.nullish()`), or the PUT fails `INVALID_INPUT`. This has shipped as a
+real bug twice.
+
+### 5.4 Mobile
+
+- **Sizing.** The window is `80vw/80vh` centered with no mobile override, so when the keyboard opens on iOS
+  the lower half sits behind it. Add a `@media (max-width: 430px)` block using
+  `height: var(--app-height, 100vh)`, full width, no border radius. `--app-height` is already maintained
+  against `visualViewport` by `KeyboardHandler.handleViewportResize()` (`mobile-handlers.js:283-317`), so
+  the editor tracks the keyboard for free.
+- **iOS zoom.** The editor font must be >= 16px on phones; there is an existing zoom-prevention block at
+  `mobile.css` under `@media (max-width: 768px)`. Verify it covers `textarea` and do not override it with a
+  smaller `rem` value.
+- **Accessory bar.** Focusing any input fires `KeyboardHandler.onKeyboardShow()`, which calls
+  `KeyboardAccessoryBar.show()` and refits/resizes the terminal (`mobile-handlers.js:407+`). The bar's keys
+  target the **terminal**, not the editor, so an Esc or clear-input tap while editing goes to the agent.
+  The overlay's `z-index: 2000` covers the bar's `51`, so it is not visible, but confirm it is not
+  interactive underneath and consider an explicit `KeyboardAccessoryBar.hide()` while the editor holds
+  focus. This is the item most likely to look "fine on desktop, wrong on the phone".
+- No header-policy change is needed (section 1), so
+  `test/mobile-header-buttons-policy.test.ts` stays untouched.
+
+### 5.5 i18n
+
+`i18n.js` already skips `textarea`, `pre`, `code` and `.file-preview-content` in its `SKIP_SELECTOR`
+(`i18n.js:20-38`), so file content is never translated. Add zh-CN entries for the new chrome: Edit, Save,
+Cancel, Unsaved changes, Discard unsaved changes?, File changed on disk, Reload, Overwrite, Saved,
+Too large to edit here.
+
+---
+
+## 6. Docker and remote cases
+
+Out of scope per the issue, and the current behavior already degrades correctly:
+
+- **Docker cases**: the workspace is a host directory bind-mounted at the same absolute path, so a host-side
+  write is visible in the container immediately. Edit mode works and needs nothing special. Worth one line
+  in the docs.
+- **Remote SSH cases**: `workingDir` is a path on the remote host. `validateSessionFilePath` realpaths it
+  locally, which fails, so the write returns 404 exactly like the read routes do today. Confirm the viewer
+  shows a clean empty/error state rather than an unexplained failure, and do not attempt an SFTP path.
+
+---
+
+## 7. Tests
+
+| File                                        | Kind        | Covers                                                                 |
+| ------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `test/file-editing-policy.test.ts`          | pure unit   | `isEditableFileName` (allow + deny + basenames), `isDeniedEditRelativePath`, `detectEol`/`applyEol` round-trip incl. mixed EOL, BOM preservation |
+| `test/routes/file-write-routes.test.ts`     | `app.inject` | The handler order in 3.3, against a **real temp dir** (do not `vi.mock('node:fs')` in this file; set `MockSession.workingDir`, `test/mocks/mock-session.ts:14`) |
+| extend `test/routes/file-routes.test.ts`    | `app.inject` | `edit=1` never truncates; `editable` present on the plain read          |
+
+Status-code caveat for all of these: the route-test harness does not install the server's preSerialization
+envelope hook, so a handler that *returns* an error envelope answers 200 in tests. The statuses below are
+only assertable because the plan has the handler **throw** structured errors (section 3.3, error
+mechanics), which `installRouteErrorHandler` renders identically in prod and in the harness.
+
+Route cases to assert explicitly:
+
+1. happy path writes the bytes and returns a new hash
+2. `../` and absolute paths give 404
+3. symlink pointing outside the workspace gives 404
+4. symlink pointing inside is written through to the target
+5. non-allowlisted extension gives 400
+6. `.git/config` gives 403
+7. a `.env` in the workspace gives 403 (sensitive-path)
+8. a file with a NUL byte gives 400
+9. a latin-1 file that fails the UTF-8 round-trip gives 400
+10. stale `baseHash` gives 409 (`CONFLICT` envelope, no data); `force:true` then succeeds
+11. over `MAX_EDITABLE_BYTES` gives 413
+12. a path that does not exist gives 404 and creates nothing (no `O_CREAT`)
+13. multi-user: `authUser: {role:'user'}` against another user's session gives 404 (pass `authUser` to
+    `createRouteTestHarness`, otherwise the synthetic admin makes the test pass vacuously)
+14. CRLF file edited and saved stays CRLF
+15. file mode is preserved across the temp-plus-rename
+
+Run with `npm test -- test/routes/file-write-routes.test.ts`, never bare `npm test`.
+
+**End-to-end verification before any deploy** (unit tests passing is not sufficient here):
+
+- `curl -sk https://localhost:3000/...` against a **throwaway** session created for the purpose, never
+  `w1`/`w2`/`w3`; delete it by exact id afterwards.
+- Playwright on a phone profile: open a preview, tap Edit, type with `page.keyboard.type()`, Save, then
+  assert the bytes on disk changed. Assert real state, not HTTP 200.
+
+---
+
+## 8. Docs and release
+
+- This plan lives at `docs/file-viewer-edit-plan.md`.
+- `docs/architecture-invariants.md`: new anchor `#file-viewer-edit-mode` covering the write confinement
+  chain, the truncation invariant, and why temp-plus-rename.
+- `CLAUDE.md`: one line under the **Filesystem path picker** neighborhood noting that the File Viewer now
+  has a **third** file surface and that it is the only one that writes, plus its confinement rules.
+  Remember `CLAUDE.md` is prettier-ignored on purpose.
+- `docs/api-reference.md`: the new `PUT` and the `edit=1` query.
+- Release: a normal COM applies (the 1.10.0 batch hold is over). This is a new user-facing feature plus an
+  additive API surface, so **COM minor** when it ships.
+
+Formatting note: `panels-ui.js`, `styles.css`, `mobile.css`, `index.html` are all in `.prettierignore` and
+are hand-formatted; new TypeScript (`src/config/file-editing.ts`, route + schema edits) is prettier-enforced
+and must pass `npm run format:check`.
+
+---
+
+## 9. Implementation order
+
+Each phase is independently reviewable and leaves the tree working.
+
+1. **Policy module + tests.** `src/config/file-editing.ts` and `test/file-editing-policy.test.ts`. Pure, no
+   route wiring. (Small.)
+2. **Read-for-edit.** `edit=1` (returning `hash`/`eol`) plus the additive `editable` flag on plain reads,
+   tests. Nothing consumes it yet. (Small.)
+3. **Write endpoint.** `FileWriteSchema`, `PUT` handler, `test/routes/file-write-routes.test.ts`. Fully
+   testable by curl before any UI exists. (Medium, the security-relevant part.)
+4. **Desktop UI.** Edit button, textarea swap, Save/Cancel, dirty guard, 409 flow. (Medium.)
+5. **Mobile pass.** `mobile.css` sizing against `--app-height`, font size, accessory-bar interaction,
+   real-device check. (Small but the part that decides whether the feature is actually usable.)
+6. **Docs, i18n strings, changeset.**
+
+---
+
+## 10. Open decisions
+
+1. **Editor widget.** Recommend a plain `<textarea>` for v1: zero dependencies, no CSP question, no bundle
+   growth, and it is the only thing guaranteed to behave with the iOS keyboard. CodeMirror-light with
+   syntax highlighting is a clean follow-up once the write path is proven. The issue allows either.
+2. **Phone entry point.** Edit mode is reachable on a phone through attachment cards and the history
+   drawer without changing anything. A dedicated toolbar or overview affordance for "browse this session's
+   files" would make it discoverable, but it is a separate UX change and would need a decision against the
+   deliberately minimal phone header policy. Recommend deferring it and revisiting after the feature ships.
+3. **`svg` editability.** Recommend excluded in v1 (it is deliberately treated as untrusted on the read
+   side). Easy to add later.
+4. **Create / delete / rename.** Explicitly out of scope per the issue. Note that keeping `O_CREAT` out of
+   the handler is what makes that a structural property rather than a convention.

docs/remote-sessions.md

@@ -1,7 +1,7 @@
 # Remote Sessions (SSH)
 
 Codeman can run a session's agent on a **remote host over SSH** instead of the
-local machine. The agent (Claude, OpenCode, Codex, Gemini, or a plain shell)
+local machine. The agent (Claude, OpenCode, Codex, Antigravity, Gemini, or a plain shell)
 runs inside a `tmux` server **on the remote host**, so it survives the SSH
 connection dropping; Codeman attaches to it the same way it attaches to a local
 managed session.
@@ -30,7 +30,7 @@ Types live in `src/types/session.ts`; persistence in `src/remote-hosts.ts`.
 | `RemoteHost` (extends `RemoteSshOptions`) | A saved host: `id`, `label`, `host`, `username`, `port?`, `commands?` (per-mode launch command override). |
 | `RemoteCase` | A working directory on a host: `name`, `type: 'remote'`, `hostId`, `remotePath`. |
 | `SessionRemote` (extends `RemoteSshOptions`) | The resolved bundle stamped onto a live session: host coordinates + `remotePath` + `commands`, plus **`owned?`** and **`remoteSessionName?`** (COD-105 — see [Ownership](#ownership-launched-vs-discovered-and-attached-cod-105)). Built by `toSessionRemote(host, case)` (sets `owned: true`) for the launch path, or `toAttachedSessionRemote(host, name, path)` (sets `owned: false`) for the attach path. Both copy the advanced SSH options through so every connection is identical. |
-| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini'>` — the modes that can run remotely. |
+| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini' \| 'antigravity'>` — the modes that can run remotely. |
 | `RemoteSessionInfo` (COD-105) | One discovered remote tmux session: `name` (always `codeman-*`), `attached` (a client is connected), `created` (epoch s), `windows`. Returned by `listRemoteCodemanSessions()`. |
 
 Persistence is two flat JSON arrays in the instance data dir:
@@ -115,7 +115,7 @@ Key points:
 - **`exec <cli>`** replaces the pane shell with the agent, so the pane PID *is*
   the agent. The per-mode command comes from `remote.commands?.[mode]` or
   `defaultRemoteCommandForMode(mode)` (`exec claude` / `exec opencode` /
-  `exec codex` / `exec gemini` / `exec bash -l`).
+  `exec codex` / `exec gemini` / `exec agy` / `exec bash -l`).
 - The **whole tmux invocation is a single shell-quoted ssh argument**, and the
   pane command is independently quoted, so a `remotePath` with spaces is safe.
 - Connection options come from the **same `buildSshConnectionArgs(remote)`** as

docs/scrollback-fix-plan.md

@@ -0,0 +1,112 @@
+# Scrollback fix plan (issue #205)
+
+Status: IMPLEMENTED on `fix/scrollback-shell-alt-screen` (2026-08-07), with one deliberate
+divergence from the recommendation below. Kept for the diagnosis record; the measured evidence
+behind it is `docs/scrollback-issues-analysis.md`, and the mechanisms as shipped are documented
+in `docs/architecture-invariants.md` (§ Full-scrollback replay, § Terminal scrollback: strip
+flavors and wheel/touch forwarding).
+
+What shipped vs. what this doc proposed:
+
+- **Bug A (deltaMode)**: implemented as specified (`_wheelScrollLines()` normalizes
+  line/page/pixel units, Shift-axis trap kept).
+- **Bug B (shell scrollback)**: implemented via the NARROW alt-screen strip for tmux-backed
+  shell/opencode/antigravity plus the scroll-to-top `full=1` re-pull, NOT the recommended
+  approach (a) `tmux mouse on`. The measurements in the analysis doc showed the alt buffer
+  comes from tmux's own client-side `smcup` at attach (tmux never forwards a pane program's
+  alt-screen toggles), so stripping that one sequence fixes both symptoms with no selection
+  tradeoff, keeps vim/less/htop untouched, and the re-pull also covers the repaint-burst
+  history loss that `mouse on` would not have addressed.
+- **Invariant change**: the "viewport-at-bottom gate stays" invariant below was deliberately
+  DROPPED for forwarding modes: a repaint-mode CLI keeps no real terminal scrollback, so the
+  gate pinned users to a buffer of stale frames whenever the viewport parked off-bottom.
+  Forwarding now snaps to bottom first; Shift+wheel and the opt-out setting keep local
+  scrollback reachable. Touch forwards through the same gate (the mobile half of the fix).
+- **Finding 5 (remote probe)**: implemented (`probeRemoteCliVersion` over ssh, deferred at
+  session start, same login-shell wrapper as the launch).
+
+Original plan follows.
+
+## Reports
+
+- **Issue #205** (https://github.com/Ark0N/Codeman/issues/205), OPEN:
+  - **jonocodes** (author, 2026-08-03): SHELL session. Host Mac M4, brew tmux. On Android, touch-scrolling the terminal does nothing. On desktop, the mouse wheel cycles shell command history (acts like Up/Down arrows) instead of scrolling the screen.
+  - **mtiller** (comment, 2026-08-06): "similar issue just with scrolling backward to see agent output. This is with Firefox on MacOS." (Claude session implied.)
+- **Reddit r/selfhosted** comment `p21x6ts` by mmtiller (= mtiller on GitHub): scrolling broken enough across phone/iPad/laptop that they fall back to Claude's own remote-control feature. Churn-risk user who otherwise loves the product; fixing this has promo value beyond the bug itself.
+
+## How scrolling works today (read this before touching anything)
+
+Three independent paths, all in `src/web/public/terminal-ui.js` unless noted:
+
+1. **Desktop wheel** (container `wheel` listener, ~line 421): ALWAYS `preventDefault()`s, then either
+   - forwards synthetic SGR wheel reports to the app (`_sendSyntheticSgrWheel`, coalesced every 40ms, fire-and-forget) when `_shouldForwardWheelToApp(ev)` (~line 2823) passes: no Shift held, opt-out setting `terminalWheelLocalScrollback` off, xterm `mouseTrackingMode === 'none'`, session mode is `claude` with `cliVersion >= 2.1.187` or `codex`, and viewport is at bottom;
+   - otherwise scrolls xterm's LOCAL scrollback via `terminal.scrollLines(lines)`.
+   - `lines` comes from `_wheelScrollLines(ev)` (~line 2818): `delta / 25`, i.e. it assumes PIXEL deltas.
+   - NOTE: xterm.js's own internal wheel handler sits on an element INSIDE the container, so it runs FIRST (bubble order) and is not suppressed by the container's `preventDefault`.
+2. **Touch** (touchstart/move/end, ~lines 441-585): converts touch deltas to `terminal.scrollLines()` with momentum. Touch is ALWAYS local-scrollback, never forwarded to the app. Tap-to-position (touchend, ~line 533) is separate and already handles both mouse-tracking-on and server-strip cases.
+3. **Server-side strip** (`_handleTerminalOutput`, `src/session.ts:1384`): for modes in `isAltScreenStripMode()` (`src/session.ts:179` = `codex | claude | gemini`), strips alt-screen switches (`?47/?1047/?1049`), scrollback erase (`3J`), and mouse-tracking DECSETs (`?1000-?1007` except `?1004` focus) so content stays in xterm's normal buffer with scrollback intact. Includes a chunk-boundary carry so split sequences can't leak. `shell` and `opencode` (and `antigravity`) are deliberately EXCLUDED: arbitrary shell programs (vim/less/htop) legitimately need the alt screen. There is a parity copy of this strip on the replay path (`src/web/routes/session-routes.ts`, ~line 1697) and a frontend parity check `_sessionUsesServerMouseStrip()` (terminal-ui.js ~line 2751). All three must stay in sync.
+4. Related: full-scrollback replay (`GET .../terminal?full=1` on first buffer load) fills xterm local scrollback; client scrollback is hardcoded 50k (`DEFAULT_SCROLLBACK`, constants.js) vs tmux 100k.
+
+## Diagnosis
+
+### Bug A: Firefox wheel deltas (mtiller's desktop case)
+
+`_wheelScrollLines()` divides by 25 assuming `WheelEvent.deltaY` is pixels (`deltaMode === 0`, Chrome/Safari behavior). Firefox commonly fires `deltaMode === 1` (LINE units, deltaY around 1-3 per notch), so `Math.round(3/25) = 0` and the `|| ±1` fallback yields 1 line per event. With a discrete mouse wheel that is 1 line per notch: scrolling feels dead/broken. This hits BOTH the local-scroll path and the forwarded path, since both use the same function.
+
+**Fix**: normalize by `ev.deltaMode` in `_wheelScrollLines()`:
+- `deltaMode 0` (pixels): current behavior, `delta / 25`.
+- `deltaMode 1` (lines): use the delta directly (round, keep sign fallback).
+- `deltaMode 2` (pages): `delta * terminal.rows` (or a sane page size).
+Keep the existing Shift-axis trap intact: on macOS trackpads Shift+two-finger scroll arrives as a HORIZONTAL wheel (deltaX carries the magnitude, deltaY ~0); that's why the function reads deltaX when Shift is held (issue #154). Don't lose it.
+
+**Verify**: don't trust this diagnosis blindly. First reproduce in real Firefox on macOS and log `deltaMode`/`deltaY` (Firefox trackpad input can arrive as pixels; external mouse as lines). Also confirm the session's `cliVersion` probe succeeded (a failed probe disables forwarding entirely, which would point elsewhere). Unit-test by dispatching synthetic `WheelEvent`s with explicit `deltaMode` values; a Playwright `firefox` project pass is the end-to-end check.
+
+### Bug B: shell mode has NO working scrollback at all (jonocodes)
+
+Chain: shell mode is excluded from the alt-screen strip (correctly) → tmux attaches on the alternate screen → xterm's alt buffer has zero scrollback. Consequences:
+- **Wheel**: xterm's own internal wheel handler runs first and, in the alt buffer, converts wheel ticks into Up/Down arrow keys (alternateScroll behavior). The shell receives arrows → command history cycles. That is jonocodes' exact desktop symptom. The container handler's `scrollLines()` afterwards is a no-op (no scrollback in alt buffer).
+- **Touch**: the touch handler's `scrollLines()` is equally a no-op → "scrolling does nothing" on Android. Exact symptom two.
+- The real history exists the whole time in tmux's 100k-line buffer; nothing exposes it.
+
+**Fix, recommended approach (a): enable tmux `mouse on` for shell sessions.**
+- Server-side, set `mouse on` scoped to shell sessions' tmux sessions (`tmux set-option -t <session> mouse on` at create + on attach of recovered sessions). Do NOT set it globally on the socket: claude/codex/gemini sessions rely on the DECSET strip and must not change.
+- What this buys, all natively: tmux enables mouse tracking on the outer terminal → xterm `mouseTrackingMode` goes non-none → the container handler stands down (line ~2830 check) and xterm's own encoder forwards wheel as SGR reports → tmux scrolls its OWN copy-mode history on wheel-up, auto-exits at bottom. The alt-scroll arrow conversion disappears too (tracking mode takes precedence). Desktop is fully fixed with no new endpoints.
+- **Touch**: still needs one small client change: in the touchmove path, when the active session is `shell` AND `mouseTrackingMode !== 'none'`, convert accumulated lines to `_sendSyntheticSgrWheel(x, y, lines)` instead of `scrollLines()`. The 40ms coalescing already prevents the tmux process storm (each send is a tmux send-keys server-side; unbatched flicks would spawn dozens of processes: this constraint is documented at `_sendSyntheticSgrWheel`, do not bypass it).
+- **Selection tradeoff to verify**: with tracking on, xterm hands drag events to tmux instead of doing local browser selection. Shift+drag still does local selection (xterm shift-override). Verify this UX on desktop before shipping; if it's unacceptable, fall back to approach (b).
+- **Also verify**: vim/less/htop inside the shell still behave (they'll now receive real mouse events via tmux, generally an improvement); remote shell sessions run tmux on the REMOTE host (`tmux -L codeman-remote`) and need the same option set there if remote shells are in scope (fine to defer, note it in the changeset if skipped).
+
+**Fallback approach (b), only if (a)'s selection tradeoff fails testing**: keep mouse off; when a shell session is in the alt buffer, have the client send scroll intents to a small server endpoint that drives `tmux copy-mode -e -t <pane>` + `send-keys -X -N <n> scroll-up/down`. Preserves selection semantics exactly, but needs a new endpoint, server-side batching, AND suppression of xterm's native alt-scroll arrow conversion (capture-phase wheel listener with `stopPropagation`, or `attachCustomWheelEventHandler` if the vendored xterm version has it). More moving parts; (a) should be tried first.
+
+**Not acceptable**: adding `shell` to `isAltScreenStripMode()`. vim/less/htop need the alt screen; that exclusion is deliberate and documented.
+
+### Bug C: mtiller's phone/iPad case — UNREPRODUCED, do not guess
+
+Touch is always-local by design, and Claude sessions keep content in the normal buffer (strip), so touch scrollback "should" work there. Before coding anything: build a repro matrix (iPhone Safari / iPad Safari / Android Chrome × claude / shell) on the current release. Plausible candidates if it does reproduce: auto-scroll-to-bottom fighting user scrolls (`_noteTerminalUserScroll`, ~line 2004), or they were in shell sessions on mobile too (then Bug B covers it). Ask mtiller on #205 for session mode + Codeman version if the matrix comes up clean.
+
+## Invariants the implementation MUST respect
+
+- Shift+wheel always scrolls local scrollback; the trackpad Shift-axis handling from #154 stays.
+- The `terminalWheelLocalScrollback` opt-out setting keeps working (pins plain wheel to local).
+- The viewport-at-bottom gate stays: once the user scrolled up locally, wheel stays local until they return to bottom.
+- 40ms SGR coalescing: never send per-event writes to the server.
+- Strip parity triangle: `session.ts` live strip ↔ `session-routes.ts` replay strip ↔ `_sessionUsesServerMouseStrip()` in the frontend. If you touch mode lists, update all three.
+- Don't add `opencode`/`antigravity` to any strip/forward list; their TUI wheel behavior is unverified (documented at `_shouldForwardWheelToApp`).
+- The chunk-boundary sequence carry in `_handleTerminalOutput` must not be weakened.
+
+## Testing (per repo rules)
+
+- `npm test -- test/<file>.test.ts` only; never bare `npm test`. New test ports 3150+, never 3000.
+- Browser-test traps (documented in CLAUDE.md Testing): drive input/scroll through real events (`page.mouse.wheel`, real touch), not app internals; headless Chromium reports `isTouchDevice()` false even with `hasTouch: true`; assert on real state (xterm viewport position, `tmux -L codeman capture-pane`), not HTTP 200.
+- Shell-mode E2E: create a throwaway shell session, `seq 1 500`, then (1) wheel up on desktop shows earlier lines, not history cycling; (2) touch-scroll on a phone shows earlier lines; (3) `vim` + `less` still enter/leave the alt screen cleanly; (4) Shift+drag still selects text.
+- Firefox E2E: Playwright `firefox` project, wheel over a Claude session's finished output, assert viewport moved more than 1 line per notch.
+- End-to-end against the REAL environment before claiming done (standing user rule). w1/w2/w3 tmux sessions are the user's live sessions: never send input to them; create your own throwaway session and DELETE it by exact id when done.
+
+## Related observation (not a reported bug, worth a look while in there)
+
+The `claude --version` probe that feeds the forwarding gate runs only for local and docker sessions (`src/session.ts:1490` gates `!this._remote`; docker handled at :1507). Remote Claude sessions therefore never get `cliVersion` and silently keep local-only wheel. Harmless (local scrollback works) but inconsistent; cheap to fix by probing over ssh, or document as intended.
+
+## Rollout
+
+1. Bug A (deltaMode) is small and independent: can ship alone as a patch.
+2. Bug B (shell scrollback) is the headline fix for #205: patch or minor per COM flow.
+3. After deploy + verification: comment on #205 (what was fixed, what needs their retest), then reply to the Reddit comment `p21x6ts` with the release version. Both reporters gave environment details; address them specifically.

docs/scrollback-issues-analysis.md

@@ -0,0 +1,255 @@
+# Scrollback issues: analysis and test evidence
+
+Covers GitHub issue **#205** ("Scrollback in terminal not working", jonocodes, shell mode,
+Android + macOS desktop) and the follow-up comment on it from **mtiller** (Firefox on macOS,
+"scrolling backward to see agent output"). Related closed issue: **#154** (fixed in 1.3.3).
+
+Status: **analysis only, nothing implemented.** Measured against the live 1.11.2 instance on
+2026-08-06 with throwaway `zz-*` shell sessions (all deleted afterwards; the user's `w*`
+sessions were never touched).
+
+---
+
+## TL;DR
+
+Five distinct problems, not one. #205 is fully explained by finding 1; findings 2 and 3 are
+independent and hit **every** mode including Claude, and are the likely substance of the
+"similar issue" follow-up.
+
+| # | Problem | Modes affected | Severity | Confirmed |
+| - | ------- | -------------- | -------- | --------- |
+| 1 | xterm parked in the **alternate buffer** for the whole session, so there is no scrollback at all and the wheel is translated into Up/Down arrow keys | `shell`, `opencode`, `antigravity` | High | Reproduced end to end |
+| 2 | **Bursty output silently destroys a screenful** of the browser's scrollback and adds ~1 row | all | High | Measured |
+| 3 | **Tab switch collapses scrollback** to roughly one screen (`full=1` fires once per page load) | all | Medium | Measured |
+| 4 | `deltaMode` is never read, so Firefox scrolls ~4x slower per notch | all, Firefox | Low | Static, needs reporter data |
+| 5 | **Remote SSH Claude cases get no `claude --version` probe**, so wheel forwarding silently stays off (residual #154) | `claude` + remote | Medium | Static |
+
+---
+
+## Finding 1: shell / opencode / antigravity are stuck in xterm's alternate buffer
+
+### Root cause
+
+The local tmux **client** (the `tmux attach` that node-pty spawns) emits `smcup` as its very
+first bytes on attach. Captured from a real PTY:
+
+```
+b'\x1b[?1049h\x1b[22;0;0t\x1b[?1h\x1b=\x1b[H\x1b[2J\x1b[?12l\x1b[?25h\x1b[?1000l...'
+ ^^^^^^^^^^ enter alternate screen              ^^^^^ application cursor keys ON
+```
+
+`Session._handleTerminalOutput()` strips `\x1b[?1049h` from the live stream, but only when
+`isAltScreenStripMode(mode)` is true, and that is `claude | codex | gemini` only
+(`src/session.ts:179`). For `shell`, `opencode` and `antigravity` the sequence reaches the
+browser verbatim and xterm switches to the alternate buffer, where:
+
+1. `buffer.active.type === 'alternate'` and `baseY` is pinned at 0, so there is **no
+   scrollback to reach**. `terminal.scrollLines()` is a no-op, which is why touch scrolling
+   on Android "does nothing".
+2. xterm's own wheel listener takes over. From the vendored bundle
+   (`src/web/public/vendor/xterm.min.js`):
+
+   ```js
+   if (!this.buffer.hasScrollback) {
+     if (ev.deltaY === 0) return false;
+     if (coreMouseService.consumeWheelEvent(...) === 0) return this.cancel(ev, true);
+     const seq = ESC + (decPrivateModes.applicationCursorKeys ? 'O' : '[') + (ev.deltaY < 0 ? 'A' : 'B');
+     coreService.triggerDataEvent(seq, true);
+     return this.cancel(ev, true);
+   }
+   ```
+
+   tmux also set `\x1b[?1h`, so the emitted sequence is `\x1bOA`, i.e. **Up arrow**, straight
+   into the shell's readline. That is exactly the reported "the mouse wheel scrolls back
+   through previous commands, like pressing up".
+
+3. `cancel(ev, true)` calls `preventDefault()` **and `stopPropagation()`**, and xterm's
+   listener sits on `terminal.element` (a child of Codeman's container). So Codeman's own
+   container wheel handler, `_shouldForwardWheelToApp` and `_wheelScrollLines` included, is
+   **never reached** for these modes. That whole path is dead code for shell.
+
+### Reproduction (live instance, real browser)
+
+Create a shell session with the page already open, print 150 lines, then dispatch 8 wheel-up
+events over `.xterm-screen`:
+
+```
+t+1500 after shell start       {"type":"alternate","length":35,"baseY":0}
+t+3000 after shell start       {"type":"alternate","length":35,"baseY":0}
+after 150 live lines           {"type":"alternate","length":35,"baseY":0}
+WHEEL on live shell: {"ptyBytes":["OA","OA","OA","OA",
+                                  "OA","OA","OA","OA"],
+                     "before":0,"after":0,"type":"alternate"}
+```
+
+Both reported symptoms, one root cause.
+
+### Why it looks intermittent
+
+The alternate-screen sequence only ever reaches the browser through the **live stream at
+attach**. Neither replay path carries it:
+
+- `?full=1` returns `capture-pane` output (`source: mux-full-history`), verified 0 hits for
+  `\x1b[?1049h`.
+- `?tail=` returns the visible pane frame (`source: mux-visible`), also 0 hits; the shell byte
+  buffer was empty in every probe.
+- `_resetTerminalForReplay()` calls `terminal.reset()`, which returns xterm to the normal
+  buffer.
+
+So: watching a shell from creation leaves you in the alternate buffer until you reload or
+switch tabs, at which point it silently starts working again. Then the next PTY attach (a
+restart, or the auto-reattach in `selectSession()`) puts you back.
+
+### Is stripping safe for shell? Probably yes when tmux-backed, and the current code comment is wrong about why
+
+`src/session.ts:1404` says *"shell must keep the alt screen for vim/less/htop"*. For a
+**tmux-backed** shell that reasoning does not hold: tmux is a full terminal emulator and never
+forwards a pane's alternate-screen toggles to its client, it repaints instead. Measured per
+phase on a real attach:
+
+| phase | bytes | `?1049h` | `?1049l` | `?47/1047` |
+| ----- | ----: | -------: | -------: | ---------: |
+| attach | 772 | **1** | 0 | 0 |
+| `seq 1 60` echo | 1402 | 0 | 0 | 0 |
+| `less` open / end / quit | 284 / 230 / 321 | 0 | 0 | 0 |
+| `vim` open / quit | 2200 / 646 | 0 | 0 | 0 |
+
+`vim` and `less` inside tmux emit **zero** alternate-screen sequences to the client.
+
+The caveat that does matter: `startShell()` falls back to a **direct PTY with no tmux** when
+mux creation fails (`src/session.ts:1961`, `this._useMux = false`). In that path the inner
+app's own `?1049h` does reach xterm, and a blanket strip would break vim/less/htop for real.
+Any fix has to be conditional on `_useMux`, which is known server-side.
+
+Second caveat: stripping alone buys less than it looks like, because of finding 2. It fixes
+the wheel (no more phantom Up arrows) and it makes the `full=1` replay reachable, but live
+output still will not accumulate.
+
+---
+
+## Finding 2: bursty output silently overwrites a screenful of browser scrollback
+
+Independent of the alternate buffer, and it hits Claude sessions too.
+
+tmux decides per flush whether to emit real linefeeds (which push rows into the outer
+terminal's scrollback) or to repaint the pane rectangle with cursor addressing (which
+overwrites the visible rows in place). When output outpaces its flush interval it coalesces
+into a repaint, and one screenful of the browser's history is **destroyed**.
+
+Measured on one session, same page, `rows = 36`:
+
+| step | `baseY` | rows containing SEED | BURST | SLOW |
+| ---- | ------: | -------------------: | ----: | ---: |
+| after `?full=1` replay (120 seeded lines) | 86 | 120 | 0 | 0 |
+| after 60 lines emitted as fast as possible | **87** (+1) | **86** (-34) | 35 | 0 |
+| after 60 lines at ~16/s (`sleep 0.06`) | **148** (+61) | 86 | 35 | 60 |
+
+The burst added **one** row of scrollback and ate **34** rows of existing history. The slow
+run behaved correctly. So "I printed a bunch of lines and now I cannot scroll back" reproduces
+without the alternate buffer being involved at all, and it is rate dependent, which is exactly
+the kind of thing that reads as random flakiness.
+
+Consequence: the browser's scrollback is effectively frozen at whatever the last `?full=1`
+replay produced, minus a screen per burst. tmux's own history is fine throughout
+(`history_size` kept growing, `history-limit` 2000), so the data is never actually lost
+server-side, it just never reaches the browser again until a reload.
+
+---
+
+## Finding 3: switching tabs collapses a session's scrollback
+
+`_initialFullBufferLoad` is true for the **first buffer load after a page load only**
+(`app.js:4374`). Everything after that uses `?tail=`, which returns byte history plus the
+visible pane frame. Worse, the snapshot restore path deliberately throws away the restored
+xterm snapshot (which does carry scrollback) and replaces it with that frame
+(`app.js:4316-4328` plus `needsRewrite`).
+
+Measured, switching away from session A and back:
+
+```
+A: initial full=1 load           {"len":152,"baseY":116,"AAA":150}
+A: after switch away and back    {"len": 87,"baseY": 51,"AAA": 59}
+```
+
+150 lines of history down to 59. Note also that the page's single `full=1` is consumed by
+whichever session auto-selects at load, so **every other tab starts life with one frame of
+history**.
+
+---
+
+## Finding 4: `deltaMode` is never read (Firefox)
+
+`grep -rn "deltaMode" src/web/public packages` returns nothing. `_wheelScrollLines()`
+(`terminal-ui.js:2818`) treats `deltaY` as pixels unconditionally:
+
+```js
+return Math.round(delta / 25) || (delta > 0 ? 1 : -1);
+```
+
+Chrome/WebKit report `deltaMode: 0` with `deltaY` around 100 to 120 px per notch, so about 4
+to 5 lines. Firefox reports `deltaMode: 1` (`DOM_DELTA_LINE`) with `deltaY` around 3, so
+`Math.round(3/25) === 0` and the `|| ±1` fallback yields **1 line per notch**, roughly 4x
+slower. In Claude mode the same value caps the forwarded SGR report at 1 tick per event
+instead of 4, so the transcript crawls too.
+
+This is sluggishness, not breakage, so it is a plausible but unproven contributor to the
+mtiller report. No Firefox build is installed under `~/.cache/ms-playwright` (chromium and
+webkit only), so this was not measured. Worth asking the reporter for `deltaMode` / `deltaY`
+from a live wheel event before acting on it.
+
+---
+
+## Finding 5: remote SSH Claude cases still have no version probe
+
+`src/session.ts:1490` deliberately skips the deterministic `claude --version` probe for
+remote sessions and defers to the startup-banner scrape, which the same comment block
+describes as unreliable ("newer Claude Code builds don't print the banner and resumed sessions
+never show it"). That is precisely the condition #154 was filed for: `cliVersion` empty means
+`_shouldForwardWheelToApp()` returns false, wheel forwarding is off, and the user is left with
+local scrollback that (per finding 2) does not accumulate.
+
+Local and Docker Claude sessions are fine; verified all 7 live sessions report
+`cliVersion=2.1.223`, so the 1.3.3 fix is still working there.
+
+---
+
+## Candidate directions (not decided)
+
+Roughly in order of value per unit of risk.
+
+1. **Extend the alternate-screen strip to tmux-backed `shell` / `opencode` / `antigravity`.**
+   Gate on `_useMux` so the direct-PTY fallback keeps vim/less/htop working. Kills the phantom
+   Up arrows and makes replayed history reachable. `isAltScreenStripMode()` currently takes
+   only `mode`, so it would need the mux flag threaded in, and
+   `test/claude-scrollback-strip.test.ts:16-17` plus `test/antigravity-mode.test.ts:116` pin
+   the current answers and would need updating.
+
+2. **Re-pull `?full=1` when the user scrolls to the top of the buffer.** Directly addresses
+   findings 2 and 3 with machinery that already exists and is already proven to return
+   complete history (200/200 lines in the probe). Needs a guard against refetch storms.
+
+3. **Stop discarding the xterm snapshot on tab switch**, or request `full=1` on the first load
+   per session rather than per page. Cheaper partial fix for finding 3 alone.
+
+4. **Read `ev.deltaMode`** in `_wheelScrollLines()` and normalise line/page deltas to lines.
+   Small, self-contained, worth doing regardless of whether it is mtiller's actual bug.
+
+5. **Probe the CLI version over SSH for remote Claude cases**, mirroring the deferred
+   in-container probe that Docker cases already use.
+
+Option 1 alone does not fix #205's "print a bunch of lines then scroll" complaint; that needs
+2 as well.
+
+## Reproduction assets
+
+Scripts used, in the session scratchpad
+(`/tmp/claude-1000/-home-arkon-default-claudeman/597ffc9f-.../scratchpad/`):
+
+- `ptycap.py` / `ptycap2.py`: PTY-level capture of the tmux client stream, per phase counts of
+  alternate-screen and mouse-tracking sequences.
+- `sim.mjs`: replays a captured stream through `@xterm/headless` with and without the strip.
+- `browser-test*.mjs`: Playwright against the live instance, reports `buffer.active.type`,
+  `baseY`, row content and the exact bytes xterm sends to the PTY on a wheel event.
+
+`@xterm/headless` was installed with `npm i --no-save`, so `package.json` and the lockfile are
+untouched.

docs/security-architecture.md

@@ -249,16 +249,28 @@ Ordered most‑to‑least recommended:
 
 ### A. Tailscale serve (recommended)
 
-Bind loopback, let Tailscale front it on your tailnet with a real cert:
+Bind loopback, let Tailscale front it on your tailnet with a real cert. **The
+installer sets this up for you**: choose **Tailscale** at the network-access
+prompt, or retrofit an existing install with:
 
 ```bash
-codeman web --https            # binds 127.0.0.1:3000
-tailscale serve --bg https / http://127.0.0.1:3000
+bash ~/.codeman/app/install.sh tailscale
 ```
 
-Only devices on your tailnet can reach it; Tailscale handles identity. No app
-password and no `0.0.0.0` bind required. (This is the maintainer's production
-setup.)
+The guided flow installs Tailscale if needed, walks through login and the
+tailnet HTTPS-certificates toggle, and configures the equivalent of:
+
+```bash
+codeman web                    # binds 127.0.0.1:3000 (plain HTTP is fine here)
+tailscale serve --bg 3000      # HTTPS at https://<node>.<tailnet>.ts.net
+```
+
+Only devices on your tailnet can reach it; Tailscale handles identity and
+terminates TLS with a real Let's Encrypt certificate (so PWA install and web
+push work). No app password and no `0.0.0.0` bind required. (This is the
+maintainer's production setup.) `CODEMAN_TAILSCALE=1` presets the choice for
+automation; the installer never runs `tailscale serve reset` and never touches
+serve mappings other than `443 -> Codeman's port`.
 
 ### B. Authenticated cloudflared tunnel + password
 
@@ -477,7 +489,7 @@ production layout (`~/.codeman`, `-L codeman`, port 3000).
 Docker cases (1.4.0) run a session inside a per‑case container instead of on the host. The security posture:
 
 - **Hardened create flags, always** — `--cap-drop ALL`, `--security-opt no-new-privileges`, `--pids-limit` (fork‑bomb guard), `--memory` == `--memory-swap` (a real OOM cap), `--init`, and non‑root: `--user <hostUid>:0` on Linux (host uid → workspace files stay host‑owned; GID 0 keeps `$HOME` writable), `--userns=keep-id` on rootless Podman. **Never** `--privileged`, and **never** the docker socket — the pure builder in `docker-hosts.ts` cannot emit them and the schema cannot represent them.
-- **Credentials never enter an image** — the convenient default bind‑mounts host cred dirs (`~/.claude`, `~/.codex`, `~/.gemini`, `~/.config/{gcloud,opencode}`) read‑write. Bind mounts are physically excluded from `docker commit`, so exported images are secret‑free. API‑key CLIs get their key as an exec‑time NAME‑ONLY `--env OPENAI_API_KEY` (no `=value`, no `ps` leak, never committed); a create‑time `-e` for a secret is never used. The **sealed** profile (`mountCredentials:false` + `network:none`) drops the host mounts; full‑image export is then refused (an in‑container login would ride the committed layer) unless a pre‑commit scrub is opted into.
+- **Credentials never enter an image** — the convenient default bind‑mounts host cred dirs (`~/.claude`, `~/.codex`, `~/.gemini` — which also carries Antigravity's `antigravity-cli/` state — and `~/.config/{gcloud,opencode}`) read‑write. Bind mounts are physically excluded from `docker commit`, so exported images are secret‑free. API‑key CLIs get their key as an exec‑time NAME‑ONLY `--env OPENAI_API_KEY` (no `=value`, no `ps` leak, never committed); a create‑time `-e` for a secret is never used. The **sealed** profile (`mountCredentials:false` + `network:none`) drops the host mounts; full‑image export is then refused (an in‑container login would ride the committed layer) unless a pre‑commit scrub is opted into.
 - **Blast radius — accept it explicitly** — the convenient profile mounts an arbitrary host workspace RW plus the host credential dirs RW into a network‑enabled container, so container‑run agent code can read/modify those host trees and reach the network at once. Still a net improvement over today's on‑host `--dangerously-skip-permissions` execution; use the sealed profile for genuinely untrusted work.
 - **Import is untrusted‑bundle‑safe** — `/api/docker-cases/import` validates the manifest + per‑member SHA‑256 before extraction, rejects absolute / `..` tar members (traversal guard), and re‑tags the loaded image into a quarantined namespace so it can never overwrite `codeman/agent:base` or a pre‑existing tag.
 - **Host guard & the bridge‑hooks listener** — in‑container hook callbacks carry `Host: host.docker.internal` / `host.containers.internal`; both are on the always‑on host‑header allowlist (`DOCKER_HOST_GATEWAY_ALIASES`) and resolve to the host only from inside a container netns, so they are not a browser DNS‑rebinding surface. On a loopback‑only server, in‑container hooks are opt‑in via `CODEMAN_DOCKER_BRIDGE_HOOKS=1`, which binds a SECOND listener on the docker bridge gateway serving **only** the hook endpoints (every other path → `403`) into the same hook‑secret‑gated pipeline. The bridge is host‑internal (containers + host), not the LAN, so it does not widen network exposure; the hook secret is bind‑mounted read‑only and referenced by path.
@@ -500,6 +512,16 @@ Full feature guide: [`docker-cases.md`](docker-cases.md).
 
 ---
 
+## 10b. Web tabs (dashboard proxy)
+
+A saved dashboard URL renders as a tab, served through Codeman's own origin at `/webview/<capability>/`. User guide: [`web-tabs.md`](web-tabs.md). Three properties carry the security weight:
+
+- **The proxy is exempt from cookie auth and the Origin/CSRF guard, and that is deliberate.** The iframe is sandboxed without `allow-same-origin`, so it is opaque‑origin: its requests are cross‑site, meaning the `SameSite=lax` session cookie is never attached and its writes and WS upgrades arrive with `Origin: null`. The credential is instead a 192‑bit capability in the path, minted only by an authenticated `POST /api/webviews/:id/open`, held in memory (a restart invalidates every one), rolling TTL, bound to the minting user, and granting nothing but "relay bytes to this one saved URL". ⚠️ **The Host allowlist is NOT bypassed**, so DNS‑rebinding protection is unaffected. A second `Referer`‑keyed form exists for root‑absolute assets and is the only exemption decided by a request‑supplied header, so it is fenced to safe methods on non‑`/api`, non‑`/ws`, non‑`/q` paths. Edges pinned by `test/webview-auth-exemption.test.ts`.
+- **Sandboxed by default; `allow-same-origin` is an explicit per‑dashboard opt‑in.** A proxied page is same‑origin with Codeman, so without the sandbox its JavaScript could read the Codeman document and call the agent‑spawning API. ⚠️ In BOTH modes the `Authorization` header and the `codeman_session` cookie are stripped before the upstream request, because a trusted (same‑origin) frame makes the browser attach Codeman's own Basic‑auth credentials to every proxied request; forwarding them would hand `CODEMAN_PASSWORD` to the dashboard.
+- **Not an open relay, and not a privilege boundary.** `resolveUpstreamUrl()` refuses anything leaving the saved origin, and cross‑origin redirects are handed back unchanged rather than followed. The proxy does reach whatever the SERVER can reach, which is not an escalation for someone who already commands `--dangerously-skip-permissions` agents, but in multi‑user mode it means a non‑admin's dashboard is fetched from the server's network position. Saved URLs are validated to plain http(s) with no embedded credentials, and there is deliberately **no magic‑link path**: terminal output can never create a webview (the mistake the attachment scanner had to be walled off from).
+
+---
+
 ## 11. Quick reference
 
 | Env / flag | Effect |

docs/tailscale-installer-plan.md

@@ -0,0 +1,236 @@
+# Tailscale Setup in the Installer (Plan)
+
+Goal: make "Codeman over Tailscale, with real HTTPS" a first-class, guided path in
+`install.sh`, instead of a one-line hint pointing at the docs. Today the safest
+recommended deployment (loopback bind + `tailscale serve`) is exactly what the
+maintainer's own prod runs, but a new user has to discover and wire it by hand.
+The installer should do it for them.
+
+Status: IMPLEMENTED (2026-08-04). `install.sh` carries the 3-way network
+prompt, the guided Tailscale flow, and the `tailscale` subcommand; README,
+`docs/security-architecture.md` section A, and CLAUDE.md are updated. Verified
+live on the maintainer's prod host: `install.sh tailscale` took the idempotent
+kept-as-is path against the existing serve mapping (recognizing the legacy
+`https+insecure://` target), verified `https://<node>.ts.net/api/status`
+end-to-end, and left `tailscale serve status` byte-identical. Items 1-4, 7,
+and 10-12 of the manual matrix below still need a fresh machine to exercise.
+
+## Why this is low-hanging fruit
+
+Everything on the app side already works; this is almost purely installer UX:
+
+- `.ts.net` is already in `DEFAULT_TRUSTED_HOST_SUFFIXES`
+  (`src/web/network-auth-policy.ts`), so the always-on Host/Origin guard accepts
+  `tailscale serve` traffic with zero configuration. No `CODEMAN_ALLOWED_HOSTS`
+  needed.
+- The loopback bind is the server default and prints no warning; nothing to
+  acknowledge, no `CODEMAN_PASSWORD` strictly required (the tailnet is the auth
+  boundary; Tailscale authenticates the device before a packet ever reaches us).
+- `tailscale serve` terminates TLS with a real Let's Encrypt certificate for
+  `<node>.<tailnet>.ts.net`. That gives users valid HTTPS with no self-signed
+  cert warnings, and (because it is a proper secure context) working service
+  worker, PWA install, and web push on phones. This is strictly better than
+  `codeman web --https` for remote access.
+- SSE and WebSockets work through serve (proven by prod:
+  `https://tnode.tailf80371.ts.net` fronting `127.0.0.1:3000` daily).
+- `docs/security-architecture.md` section "A. Tailscale serve (recommended)"
+  already documents this as the preferred setup; the installer just does not
+  implement it.
+
+## UX design
+
+### 1. The network-access prompt grows a Tailscale option
+
+`choose_network_binding()` (install.sh:1051) currently offers two choices. New
+menu, with Tailscale first when it can be recommended:
+
+```
+  Network access
+
+  How should the Codeman dashboard be reachable?
+
+    1) Tailscale (recommended)
+       Private VPN access from your phone/laptop, real HTTPS,
+       no password needed. Works from anywhere, not just your Wi-Fi.
+    2) Any device on your network (0.0.0.0)
+       Open it straight from your phone or laptop on the same Wi-Fi.
+       Less safe: set a password so only you control your agents.
+    3) This machine only (127.0.0.1)
+       Safest. Reach it remotely via Tailscale or a tunnel later.
+```
+
+Choice mapping:
+
+- Option 1 = bind `127.0.0.1` (unchanged server posture) + configure
+  `tailscale serve`. Internally it is option 3 plus the serve setup, so all
+  existing binding plumbing (`BIND_HOST`, service files, `read_existing_binding`)
+  is untouched.
+- Options 2 and 3 behave exactly as today (renumbered).
+- Default choice: 1 when tailscale is installed and logged in, or when an
+  existing serve mapping for our port is detected; otherwise keep today's
+  defaults (1 -> 2, 2 -> 3 renumbering, preserving the "existing setup wins"
+  rule). If tailscale is not installed, option 1 is still shown (the installer
+  offers to install it), but the default stays on the current behavior so a
+  bare Enter never pulls in new software.
+- Password: after choosing Tailscale, offer the password prompt as optional
+  defense in depth with default skip ("the tailnet already authenticates your
+  devices; add one anyway?"). No `BIND_ACK` needed since the bind is loopback.
+
+### 2. The Tailscale flow (state machine)
+
+New `setup_tailscale_access()` runs after the binding choice, before service
+setup, handling each state in order:
+
+1. **Not installed.**
+   - Linux: offer to run the official installer
+     (`curl -fsSL https://tailscale.com/install.sh | sh`), which handles all
+     distros and enables `tailscaled` at boot. This mirrors our own
+     curl-pipe-bash story and avoids maintaining per-distro logic like the six
+     `install_cloudflared_*` functions.
+   - macOS: do not auto-install (the GUI app needs an interactive login).
+     Offer `brew install --cask tailscale` when brew exists, else print the
+     download link, then wait-and-retry or let the user skip.
+   - Declined install => fall back to plain loopback (option 3 behavior) and
+     print how to redo this later (`install.sh tailscale`, see below).
+2. **Installed but logged out** (`tailscale status --json` ->
+   `.BackendState == "NeedsLogin"` or `"Stopped"`).
+   - Run `tailscale up` (via `run_as_root` if needed). It prints an auth URL
+     that works headless (user opens it on any device). Poll
+     `.BackendState == "Running"` with a friendly spinner + timeout; on
+     timeout, skip gracefully with re-run instructions.
+3. **Running: grant operator (Linux).** `sudo tailscale set --operator=$USER`
+   so serve configuration (now and in the future) does not need root. Skip
+   silently if we are already operator (probe: `tailscale serve status`
+   exits 0) or sudo is declined; fall back to `run_as_root tailscale serve ...`.
+4. **HTTPS availability check.** `.CertDomains` empty or
+   `.CurrentTailnet.MagicDNSEnabled == false` means the tailnet has not enabled
+   MagicDNS / HTTPS certificates. Print the exact two toggles with the admin
+   URL (https://login.tailscale.com/admin/dns: enable MagicDNS, then enable
+   HTTPS Certificates), then offer "I enabled it, re-check" / "skip for now".
+   No silent HTTP fallback: the pitch is real HTTPS, and a plain-HTTP serve
+   would break the PWA/push story. Skipping falls back to loopback + re-run
+   instructions.
+5. **Existing serve config check** (`tailscale serve status --json`).
+   - Already proxying to our port (443 -> `127.0.0.1:$PORT`): keep it, report
+     it, done. Re-running the installer must be idempotent.
+   - Port 443 occupied by a DIFFERENT target: never clobber it. Ask whether to
+     replace it or skip. (Prod itself has a second serve on :5000; blind
+     `tailscale serve reset` would destroy user config. NEVER use `reset`.)
+6. **Configure.** `tailscale serve --bg $PORT` where `$PORT` is the install's
+   Codeman port (default 3000; honor a preset `CODEMAN_PORT`). Serve targets
+   plain HTTP on loopback; TLS terminates at tailscaled with the real cert.
+   The `--bg` config persists in tailscaled state across reboots, so no extra
+   service unit is needed.
+   (Note: do NOT combine this with `codeman web --https`; that is what forces
+   the awkward `https+insecure://` proxy target prod historically used. New
+   installs should keep Codeman on plain HTTP behind serve.)
+7. **Verify end-to-end.** Derive the URL from `.Self.DNSName` (strip the
+   trailing dot) and curl `https://<dnsname>/api/status` after the service is
+   up, retrying for ~30s: the first request can be slow while the Let's
+   Encrypt cert is issued. Print success with the URL, or the observed error
+   with `tailscale serve status` output on failure. This follows the "always
+   test before claiming it works" rule; a blind "done!" is not acceptable.
+
+### 3. Closing summary and security notice
+
+- The final summary gains a "Remote Access (Tailscale)" block, printed above
+  the cloudflared block, showing the actual URL:
+
+  ```
+    Remote Access (Tailscale):
+      https://tnode.tailf80371.ts.net    (any device on your tailnet, HTTPS)
+      tailscale serve status             # inspect
+  ```
+
+- `print_security_notice()` third branch (loopback) gets a variant: when a
+  serve mapping for our port is detected, lead with "reachable on your tailnet
+  at https://... (HTTPS, tailnet-only)" instead of the generic "do ONE of"
+  list. Detection is dynamic (query `tailscale serve status --json` at print
+  time), no marker persisted anywhere: tailscaled's own state is the single
+  source of truth, so external changes never drift against a stale flag.
+
+### 4. Standalone entry point: `install.sh tailscale`
+
+Add a `tailscale` subcommand next to `update` / `uninstall` in the existing
+dispatch. It runs `setup_tailscale_access()` against the already-installed
+service (reads the port from the service file, requires an existing install).
+This serves:
+
+- existing installs that predate the feature,
+- users who picked "this machine only" and changed their mind,
+- every "skip for now" branch above, all of which print this exact command.
+
+One implementation, two entry points. No separate `scripts/tailscale-setup.sh`
+(unlike cloudflared, there is no long-running process for a `tunnel.sh`-style
+start/stop wrapper to manage; tailscaled owns the lifecycle).
+
+### 5. Non-interactive / automation
+
+- `CODEMAN_TAILSCALE=1` presets choice 1 (analogous to presetting
+  `CODEMAN_HOST`). In non-interactive runs it only proceeds through states
+  that need no human (already installed + logged in + HTTPS-enabled tailnet);
+  anything requiring interaction (login URL, admin-console toggle, replacing a
+  foreign serve mapping) warns and falls back to loopback. It never installs
+  tailscale non-interactively.
+- `CODEMAN_NONINTERACTIVE=1` with an existing serve mapping: preserve it, same
+  "never silently loosen/change" policy as `read_existing_binding`.
+- Document both in the header comment block of install.sh (the env-var
+  reference at the top) and in the README.
+
+## Edge cases and decisions
+
+| Case | Decision |
+| ---- | -------- |
+| macOS GUI app without `tailscale` on PATH | `get_tailscale_path()` helper mirroring `get_cloudflared_path()`: check PATH, then `/Applications/Tailscale.app/Contents/MacOS/Tailscale`. All calls go through it. |
+| Tailnet HTTPS certs disabled | Guided admin-console instructions + re-check loop; skip falls back to loopback. Never configure plain-HTTP serve. |
+| Port 443 serve exists for another app | Prompt replace/skip; never `tailscale serve reset` (destroys unrelated mappings). |
+| First cert issuance latency | Verify step retries ~30s and says why the first load may be slow. |
+| `tailscale up` needs auth | Print the auth URL prominently, poll with timeout, skip gracefully. Works headless. |
+| Custom `CODEMAN_PORT` | Serve target uses the actual port; `install.sh tailscale` re-reads it from the service file. |
+| Funnel (public internet) | OUT OF SCOPE for v1. If ever added it must mirror the tunnel guard: refuse without `CODEMAN_PASSWORD` (`isUnauthenticatedNetworkAcknowledged`). Funnel exposes to the whole internet and is a different risk class than tailnet-only serve. Mention `tailscale funnel` in docs only, with the password warning. |
+| Uninstall | Best effort: if `serve status --json` shows 443 proxying to our port, run the targeted `tailscale serve --https=443 off` (still accepted by current CLIs); if the CLI rejects it, print manual instructions. Never touch other mappings, never uninstall tailscale itself. |
+| User already fronting Codeman some other way (reverse proxy etc.) | The serve check only looks at tailscale state; other proxies are invisible and unaffected (same stance as the loopback-exemption note in security-architecture). |
+
+## What does NOT change
+
+- Server code: no changes required. Host guard already trusts `.ts.net`,
+  loopback bind is already the default, SSE/WS already work through serve.
+- The two existing binding options and their semantics, `read_existing_binding`
+  preservation, and the LAN+password flow.
+- `scripts/tunnel.sh` / cloudflared support (stays as the "no Tailscale
+  account" alternative).
+- The security model: this feature only ever narrows exposure (loopback +
+  authenticated overlay), never widens it.
+
+## Files touched (implementation inventory)
+
+| File | Change |
+| ---- | ------ |
+| `install.sh` | New: `check_tailscale`, `get_tailscale_path`, `tailscale_status_field` (jq-free JSON field extraction; the installer cannot assume jq: use `sed`/`grep` like existing helpers or `tailscale status --json` piped to `node -e` since node is guaranteed post-install), `offer_install_tailscale`, `ensure_tailscale_login`, `ensure_tailscale_operator`, `ensure_tailnet_https`, `setup_tailscale_serve`, `verify_tailscale_access`, `setup_tailscale_access` (orchestrator). Modified: `choose_network_binding` (3-way menu), summary block, `print_security_notice`, subcommand dispatch (`tailscale`), `uninstall` (targeted serve removal), header env-var docs (`CODEMAN_TAILSCALE`). |
+| `README.md` | Remote-access section: promote the Tailscale path with the one-liner and `install.sh tailscale`; keep the tailscale-IP HTTP note for non-serve users but recommend serve + HTTPS. |
+| `docs/security-architecture.md` | Section A gains "the installer can set this up for you" + `install.sh tailscale` pointer. |
+| `CLAUDE.md` | One line in Scripts & Tunnel: installer offers Tailscale setup (`install.sh tailscale` to redo). |
+| `test/` | No unit tests possible for interactive bash + a live tailnet; guard with `shellcheck install.sh` (already the norm) and the manual matrix below. |
+
+## Manual test matrix (before release)
+
+1. Linux + tailscale absent: install offered, declined => loopback fallback + hint.
+2. Linux + tailscale absent: install accepted => full flow => URL verified.
+3. Logged out => auth URL flow => Running => serve configured.
+4. Tailnet with HTTPS certs disabled => guided instructions => re-check => success; and the skip branch.
+5. Re-run installer with serve already configured => idempotent, preserved, reported.
+6. Second serve mapping on another port present => untouched (prod-like state).
+7. Port 443 already proxying another target => replace/skip prompt honored.
+8. `install.sh tailscale` on an existing loopback install (the retrofit path).
+9. `CODEMAN_NONINTERACTIVE=1` re-run => preserves everything, no prompts.
+10. macOS (Mac mini `arbbot` box): GUI-app CLI path detection + full flow.
+11. Uninstall removes only our 443 mapping, leaves others.
+12. Phone check: PWA install + push from the `https://*.ts.net` origin.
+
+## Release
+
+Changeset: `minor` (new documented installer capability + new `CODEMAN_TAILSCALE`
+env var). The feature is installer-only, so it ships with zero risk to running
+servers; `install.sh update` does not invoke the new flow (updates never rewrite
+access config), only fresh installs and the explicit `install.sh tailscale`
+subcommand do.

docs/terminal-copy-shortcut-plan.md

@@ -0,0 +1,303 @@
+# Terminal smart copy (Ctrl+C) plan
+
+Issue: [#211](https://github.com/Ark0N/Codeman/issues/211) "Terminal: Ctrl+C should copy when text is selected (interrupt otherwise)".
+Origin: r/selfhosted feedback, "Biggest stumbling block is apparent lack of copy-paste in the terminal."
+
+Status: **implemented and shipped** on 2026-08-05 (this document is kept as the rationale record). It was first served as an isolated beta over Tailscale for manual sign-off, then landed. Section 2 is the research that shaped the design, sections 4 to 6 describe what was built.
+
+---
+
+## 1. What the issue asks for
+
+- Text selected in the terminal + `Ctrl+C` -> copy the selection, toast, clear the selection, do NOT send the byte to the PTY.
+- No selection + `Ctrl+C` -> unchanged, the interrupt (`0x03`) reaches the PTY.
+- `Ctrl+Shift+C` as an explicit copy chord.
+- The selection check must run before the shortcut registry dispatch so a rebind cannot cost the user their interrupt key.
+- Paste is out of scope (it already works via `Ctrl+V`, which terminal-ui.js routes to the image/text paste trap).
+
+## 2. Verified current behavior
+
+### 2.1 xterm cancels the Ctrl+C keydown, so no copy can happen
+
+`src/web/public/vendor/xterm.min.js` (xterm 6.x), `_keyDown`:
+
+```js
+_keyDown(x){ if(this._keyDownHandled=!1, this._keyDownSeen=!0,
+  this._customKeyEventHandler && this._customKeyEventHandler(x)===!1) return !1;
+  ... evaluateKeyboardEvent(...) ... this.cancel(x) ... }
+```
+
+Two consequences that shape the design:
+
+1. The custom handler runs **first**, before xterm evaluates the key. Returning `false` exits before `cancel(x)`, so returning `false` does **not** call `preventDefault()` for us.
+2. When the handler returns `true`, xterm turns Ctrl+C into `0x03` and cancels the event, which is why the browser's own copy command never runs.
+
+Probe (headless chromium against an isolated server on port 3174, selection active, real focus on `.xterm-helper-textarea`, synthetic Ctrl+C keydown):
+
+```json
+{ "hasSelection": true, "defaultPrevented": true, "dataSeen": ["\"\\u0003\""],
+  "clipboardAfter": "SENTINEL-BEFORE", "stillHasSelection": false }
+```
+
+So today: interrupt byte sent, clipboard untouched, and xterm drops the selection anyway. The last point matters, "copy then clear the selection" is not a behavior change in how the selection feels, it is what already happens on any keypress.
+
+### 2.2 Why right-click Copy works today
+
+xterm registers a `copy` listener on its root element that substitutes the selection text:
+
+```js
+this._register(addDisposableListener(this.element,"copy",(k=>{ this.hasSelection() && copyHandler(k,this._selectionService) })))
+```
+
+Second probe (port 3175, real `page.keyboard.press('Control+c')`, custom handler patched to return `false` for Ctrl+C without `preventDefault`):
+
+```json
+{ "dataSeen": [], "copyEvents": ["xterm-element"],
+  "clipboardAfter": "native-copy-probe-line\n...", "stillHasSelection": true }
+```
+
+So a "return false and let the browser copy" implementation would also work in Chromium. It is rejected below (section 3.3) because it gives no toast, does not clear the selection, and leans on per-browser behavior of the copy command when the focused element is xterm's empty helper textarea.
+
+### 2.3 The document-level capture handler will not interfere
+
+`setupEventListeners()` in `src/web/public/app.js:989` runs on document capture, before xterm's textarea listener. Its registry loop skips any entry whose action is not in the local `SHORTCUT_ACTIONS` map:
+
+```js
+if (shortcut.disabled || !shortcut.action) continue;
+const action = SHORTCUT_ACTIONS[shortcut.action];
+if (!action) continue;
+```
+
+This is exactly how `command-palette` already behaves: it is a full registry entry (rebindable and disableable in App Settings) whose dispatch happens in a dedicated, focus-aware gate rather than the generic loop. The new copy entry follows that pattern, so the capture handler falls through untouched and the terminal handler owns the decision.
+
+### 2.4 Registry matching rules that constrain the bindings
+
+`matchesShortcutEvent()` (`app.js:4890`):
+
+- Ctrl and Cmd are interchangeable as the primary modifier, so a `['ctrl']` binding also matches Cmd+C on macOS. That is fine here: with a selection it copies (same result the native macOS path gives today), without one it falls through.
+- Every other modifier must be declared exactly: `if (mods.includes('shift') !== !!e.shiftKey) return false`. So `Ctrl+Shift+C` needs its own binding, a plain `ctrl+c` binding will never swallow it.
+- `binding.code` wins when present, otherwise `binding.key` is compared case-insensitively.
+
+### 2.5 Where selection is actually possible
+
+- The server strips mouse-tracking DECSETs for `claude`, `codex`, and `gemini` (`isAltScreenStripMode`, `src/session.ts:179`), which is why plain drag-select works in those tabs even though the TUI has mouse tracking on.
+- `shell`, `opencode`, and `antigravity` keep mouse reporting, so xterm requires `Shift`+drag to force a selection there. Worth one line in the docs, it is not a code change.
+- Touch devices deliberately disable selection entirely (`body.touch-device .terminal-container .xterm{user-select:none !important}`, `styles.css:3196`), and phones have no Ctrl key. This feature is desktop and hardware-keyboard only, with no mobile regression surface.
+
+### 2.6 Helpers that already exist and should be reused
+
+| Need | Existing code |
+| --- | --- |
+| Clipboard write with an HTTP-safe fallback | `_copyText(text)` in `app.js:1887` (Clipboard API, then hidden textarea + `execCommand`) |
+| Toast | `showToast(message, type)` in `panels-ui.js:4385` |
+| Translated string | `'Copied to clipboard'` already in `i18n.js:453` |
+| Focus-aware chord gate to copy the shape of | `shouldOpenCommandPaletteFromShortcut(e)` in `panels-ui.js:285` |
+| Buffer-wide copy (currently unreferenced) | `copyTerminal()` in `terminal-ui.js:2615` |
+
+`_copyText` matters more than it looks: `install.sh`'s LAN option serves plain HTTP, where `navigator.clipboard` is undefined. The issue's suggested `navigator.clipboard.writeText` alone would silently do nothing for those users, the `execCommand` fallback covers them.
+
+## 3. Design
+
+### 3.1 Behavior
+
+| Chord | Selection present | No selection |
+| --- | --- | --- |
+| `Ctrl+C` (and Cmd+C, per registry equivalence) | copy, toast, clear selection, swallow the key | fall through, xterm sends `0x03` (interrupt) |
+| `Ctrl+Shift+C` | copy, toast, clear selection, swallow the key | swallow, no-op (see 3.2) |
+| Shortcut disabled in App Settings | never copies, `Ctrl+C` is always the interrupt | unchanged |
+| Rebound to another chord | that chord copies when a selection exists | plain `Ctrl+C` is always the interrupt |
+
+### 3.2 Why `Ctrl+Shift+C` with no selection is swallowed rather than forwarded
+
+Today `Ctrl+Shift+C` produces `0x03` as well (the shift is irrelevant to the control byte), so forwarding would be "no regression". But once the chord is advertised as *the explicit copy key*, letting it interrupt a running agent when the selection happens to be empty is a footgun with no upside. Swallowing costs nothing: a user who wants to interrupt has `Ctrl+C` right there.
+
+The rule in code is "no selection and the matched chord had Shift -> swallow", not a hardcoded key check, so it stays correct under rebinds.
+
+### 3.3 Why an explicit clipboard write rather than falling through to the native copy
+
+Probe 2 showed the native path works in Chromium, but the explicit write is chosen because it:
+
+- gives the "Copied to clipboard" toast, which is the discoverability half of the issue,
+- clears the selection so a second `Ctrl+C` interrupts (the smart-copy contract),
+- works on plain-HTTP LAN installs through `_copyText`'s `execCommand` fallback,
+- does not depend on how each browser treats a copy command issued while an empty textarea has focus.
+
+### 3.4 Why no new app setting
+
+Per-shortcut enable/disable and rebinding already exist in App Settings -> Shortcuts and are driven by the registry. A user who wants "Ctrl+C is always interrupt" unchecks one box. Adding a `terminalSmartCopy` setting would duplicate that and would drag in the per-device vs synced decision (`displayKeys` + `.strict()` `SettingsUpdateSchema`) for no gain.
+
+## 4. Code changes, file by file
+
+### 4.1 `src/web/public/app.js`, registry entry
+
+Add to `DEFAULT_SHORTCUTS` (after the `clear-terminal` entry, ~line 351) so the Terminal group stays together:
+
+```js
+{
+  id: 'copy-selection',
+  group: 'Terminal',
+  label: 'Copy Selection',
+  bindings: [
+    { modifiers: ['ctrl'], key: 'c' },
+    { modifiers: ['ctrl', 'shift'], key: 'C' },
+  ],
+  // Dispatched by shouldCopyTerminalSelectionFromShortcut() in terminal-ui.js,
+  // deliberately NOT in SHORTCUT_ACTIONS: the generic capture loop always
+  // preventDefaults, which would cost the user the interrupt key.
+  action: 'copyTerminalSelection',
+},
+```
+
+Match on `key`, not `code`. xterm decides what byte to emit from the produced character, so intercepting the physical `KeyC` on a layout where it does not produce "c" would diverge from what xterm would have sent.
+
+The `action` string is required for App Settings to render the row as configurable (`configurable = !!shortcut.action && Array.isArray(shortcut.bindings)`, `settings-ui.js:2624`). Do **not** add `copyTerminalSelection` to `SHORTCUT_ACTIONS`.
+
+### 4.2 `src/web/public/terminal-ui.js`, the gate
+
+New prototype method, modeled on `shouldOpenCommandPaletteFromShortcut`:
+
+```js
+shouldCopyTerminalSelectionFromShortcut(ev) {
+  if (!ev || ev.type !== 'keydown') return false;          // the handler also runs for keypress/keyup
+  if (!ev.ctrlKey && !ev.metaKey && !ev.altKey) return false;  // hot path: plain typing exits here
+  const registryAvailable =
+    typeof this.getShortcutRegistry === 'function' && typeof this.matchesShortcutEvent === 'function';
+  const entry = registryAvailable
+    ? this.getShortcutRegistry().find((s) => s.id === 'copy-selection')
+    : null;
+  if (entry) return !entry.disabled && this.matchesShortcutEvent(ev, entry);
+  return (ev.key || '').toLowerCase() === 'c' && !ev.altKey; // fallback for isolated harnesses
+}
+```
+
+### 4.3 `src/web/public/terminal-ui.js`, the branch
+
+Inside `attachCustomKeyEventHandler` (`terminal-ui.js:133`), after the command-palette gate and before the `Ctrl+V` branch:
+
+```js
+// Smart copy (#211): with a selection, Ctrl+C copies instead of sending ^C.
+// With no selection it MUST fall through (return true, no preventDefault) or
+// the interrupt key is lost. Ctrl+Shift+C is the explicit chord and never
+// falls through: an "explicit copy" that interrupts the agent is a footgun.
+if (this.shouldCopyTerminalSelectionFromShortcut?.(ev)) {
+  const selection = this.terminal.hasSelection?.() ? this.terminal.getSelection() : '';
+  if (selection) {
+    ev.preventDefault();
+    void this.copyTerminalSelection(selection);
+    return false;
+  }
+  if (ev.shiftKey) {
+    ev.preventDefault();
+    return false;
+  }
+  return true;
+}
+```
+
+`preventDefault()` is explicit because returning `false` alone does not cancel the event (section 2.1), and without it the browser would run its own copy on top of ours.
+
+### 4.4 `src/web/public/terminal-ui.js`, the copy action
+
+```js
+async copyTerminalSelection(text) {
+  const selection = text ?? (this.terminal.hasSelection?.() ? this.terminal.getSelection() : '');
+  if (!selection) return false;
+  const ok = await this._copyText(selection);
+  if (ok) {
+    this.terminal.clearSelection?.();
+    this.showToast('Copied to clipboard', 'success');
+  } else {
+    this.showToast('Failed to copy', 'error');
+  }
+  // _copyText's execCommand fallback focuses a temp textarea; restore the
+  // terminal (this.terminal.focus is the CJK-aware router, not xterm's raw focus).
+  this.terminal.focus();
+  return ok;
+}
+```
+
+The selection text is captured **before** the first `await`, and `navigator.clipboard.writeText` is reached in the same task as the keydown, so user activation still holds.
+
+### 4.5 `src/web/public/i18n.js`
+
+`'Copied to clipboard'` exists. Add `'Failed to copy': '复制失败'` (the error path is new to this surface).
+
+### 4.6 Documentation
+
+| File | Change |
+| --- | --- |
+| `README.md` shortcut table (~line 648) | `\| `Ctrl/Cmd+C` \| Copy selection (interrupts when nothing is selected) \|` and a `Ctrl+Shift+C` row |
+| `src/web/public/index.html` help modal, Terminal section (~line 641) | `<div><kbd>Ctrl</kbd>+<kbd>C</kbd></div><div>Copy Selection / Interrupt</div>` plus the Ctrl+Shift+C row. Keep the existing negative assertion in `help-modal-shortcuts.test.ts` in mind (it forbids `Ctrl+K`, `C` is fine) |
+| `CLAUDE.md` "Keyboard shortcuts" line | add `Ctrl+C` (copy selection, else interrupt) and `Ctrl+Shift+C` |
+| `docs/architecture-invariants.md` -> "Command palette and shortcut registry" | append the invariant: the no-selection path must return `true` without `preventDefault`, the branch is keydown-only, and `copyTerminalSelection` must stay out of `SHORTCUT_ACTIONS` |
+
+The shortcut overlay (`Ctrl+?`) and App Settings -> Shortcuts are registry-driven and pick the entry up with no edit.
+
+## 5. Edge cases and risks
+
+| Case | Handling |
+| --- | --- |
+| Handler also fires for `keypress`/`keyup` | gated on `ev.type === 'keydown'`. xterm's `_keyPress` bails on ctrl combos anyway, so no stray byte |
+| CJK IME composing | the existing `isComposing || keyCode === 229` guard is the first line of the handler and stays first |
+| Local echo overlay has unsent `pendingText` | the copy branch returns before `onData`, so `pendingText`, flushed offsets and the durable input queue are untouched. The no-selection path is byte-identical to today, including the "control char flushes buffered text then sends `0x03`" logic at `terminal-ui.js:895` |
+| Plain HTTP (LAN install) | `_copyText` falls back to `execCommand`, then focus is restored |
+| Clipboard write rejected (permissions policy, no gesture) | error toast, right-click Copy still available |
+| Whitespace-only or empty selection | `getSelection()` empty string is treated as "no selection", so Ctrl+C still interrupts |
+| macOS Cmd+C | registry treats ctrl/meta as interchangeable, so with a selection it takes our path (same visible result as today's native copy), without one it falls through |
+| Chrome/Firefox `Ctrl+Shift+C` is the devtools inspect chord | browser-level and may still toggle devtools, our copy runs regardless. Document as a caveat, `Ctrl+C` is the primary path |
+| Selection in a tab whose TUI owns the mouse (`shell`/`opencode`/`antigravity`) | unchanged, `Shift`+drag selects, then Ctrl+C copies |
+| Web tab (iframe dashboard) focused | xterm handler never runs, browser-native copy inside the iframe |
+| Teammate/subagent terminals (`panels-ui.js:2268`, `onData` wired) | same limitation exists there, out of scope for this PR (section 8) |
+
+## 6. Test plan
+
+New file `test/terminal-copy-selection.test.ts` (node env, `vm` harness in the style of `test/command-palette-ui.test.ts`), covering `shouldCopyTerminalSelectionFromShortcut` in isolation:
+
+1. Ctrl+C keydown -> true, keyup/keypress of the same chord -> false.
+2. Ctrl+Shift+C -> true, plain `c` -> false, Ctrl+K -> false.
+3. Registry entry `disabled: true` -> false for every chord.
+4. Rebound entry (for example Alt+Y) -> true for the rebind, false for Ctrl+C.
+5. Missing registry (harness without `getShortcutRegistry`) -> falls back to the `c` check.
+
+Static assertions appended to `test/keyboard-shortcuts.test.ts` (this suite already pins the xterm-handler chokepoint):
+
+6. `DEFAULT_SHORTCUTS` contains `id: 'copy-selection'` and `SHORTCUT_ACTIONS` does **not** contain `copyTerminalSelection` (the interrupt-safety invariant).
+7. `terminal-ui.js` contains the `shouldCopyTerminalSelectionFromShortcut` branch and a `return true` no-selection fall-through.
+8. README + help modal rows exist (mirrors the existing palette/Alt-nav doc assertions).
+
+`test/help-modal-shortcuts.test.ts`: add `expectShortcut(helpModal, ['Ctrl', 'C'], 'Copy Selection')`.
+
+New browser test `test/terminal-copy-shortcut.test.ts` (Playwright, port **3174**, free per a scan of `test/`), following `test/webgl-fallback.test.ts`: boot `WebServer`, grant `clipboard-read`/`clipboard-write`, `terminal.write()` a known line, `selectLines()`, real `page.keyboard.press('Control+c')`, then assert clipboard content, empty `onData` capture, cleared selection and the toast. Second case: no selection, assert `onData` saw `\u0003` and the clipboard is unchanged.
+Per repo convention, browser suites are excluded from CI, so add the filename to the exclude list in `config/vitest.ci.config.ts` and run it locally.
+
+Regression runs: `npm test -- test/keyboard-shortcuts.test.ts`, `test/help-modal-shortcuts.test.ts`, `test/command-palette-ui.test.ts`, `test/input-send-order.test.ts`, then `npm run test:ci`.
+
+## 7. Manual verification before COM (CLAUDE.md rule)
+
+Against a throwaway session on the live instance (`curl -sk https://localhost:3000/...`, never w1/w2/w3):
+
+1. Select output with the mouse, press Ctrl+C, confirm the toast, paste elsewhere, confirm the agent did not stop.
+2. Press Ctrl+C again with nothing selected, confirm the agent interrupts.
+3. Type a few characters with local echo on (phone or `localEchoEnabled` forced), press Ctrl+C with no selection, confirm buffered text plus interrupt behave as before.
+4. Uncheck the shortcut in App Settings -> Shortcuts, confirm Ctrl+C always interrupts even with a selection.
+5. Rebind it, confirm the new chord copies and Ctrl+C reverts to pure interrupt.
+6. Repeat 1 and 2 in an `opencode` or `shell` tab using Shift+drag to select.
+7. Load over plain HTTP (`--host` LAN or `http://127.0.0.1:<port>`) and confirm the `execCommand` fallback copies and focus returns to the terminal.
+8. Mobile smoke: confirm nothing changed (selection is CSS-disabled, no Ctrl key).
+
+## 8. Out of scope, follow-ups worth filing separately
+
+- **Teammate/subagent terminals** (`panels-ui.js:2268`) have the same blocked-copy problem. One `attachCustomKeyEventHandler` reusing `copyTerminalSelection` would fix them, but it touches a different surface and deserves its own change.
+- **A mobile copy affordance.** Selection is disabled on touch, so phones still cannot copy terminal text. The unreferenced `copyTerminal()` (whole buffer) plus a keyboard-accessory "Copy" button would be the cheapest answer.
+- **Right-click context menu** with Copy/Paste, better discoverability than any chord, but a bigger UI surface.
+- **`copyTerminal()` cleanup**: it uses raw `navigator.clipboard` rather than `_copyText`, so it would fail on plain HTTP if ever wired up.
+
+## 9. PR mechanics
+
+- Branch off `master` (verify with `git branch --show-current`, the tree is shared), stage explicit paths only.
+- Files touched: `src/web/public/app.js`, `src/web/public/terminal-ui.js`, `src/web/public/i18n.js`, `src/web/public/index.html`, `README.md`, `CLAUDE.md`, `docs/architecture-invariants.md`, `docs/terminal-copy-shortcut-plan.md`, three test files, `config/vitest.ci.config.ts`.
+- `index.html`, `app.js` and `terminal-ui.js` are `.prettierignore`d hand-formatted assets, match the surrounding style by hand. `npm run check:public-assets` and `npm run check:frontend-syntax` are the guards.
+- No changeset in this PR: a merged, unconsumed changeset turns the Release workflow red until the next COM, and the COM flow writes release notes covering everything since the last tag (current version is 1.10.0).
+- Close #211 from the PR body.
+
+Rough size: about 60 lines of product code, most of the work is the tests and the four documentation surfaces.

docs/usage-limits-display-plan.md

@@ -1,6 +1,6 @@
 # Plan Usage Limits Display — Design & As-Built
 
-> **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** Opt-in via App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`, default OFF). Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
+> **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`). **Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via `planUsageChipEnabled()`.** The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
 >
 > Two surfaces from one `statusLine` callback:
 > - **Header chip** (top-right) — account-wide **plan limits**: `5h 35% · 7d 38%`, per-window green/yellow/red.

docs/versioning-policy.md

@@ -75,5 +75,5 @@ allowance. The commitments above take effect at `1.0.0`.
 ## See also
 
 - `CLAUDE.md` — the COM release workflow (changesets, version bump, deploy)
-- `SECURITY.md` — security reporting and the supported-version policy
+- `.github/SECURITY.md` — security reporting and the supported-version policy
 - `docs/security-architecture.md` — the full trust model

docs/vm-cases-plan.md

@@ -0,0 +1,201 @@
+<!-- Design doc drafted 2026-07-28 from WWDC26 session 224 research. STATUS: PLANNED, NOT IMPLEMENTED. Blocked on macOS 27 "Golden Gate" (beta now, GA expected fall 2026). -->
+
+# VM Cases (macOS Virtualization framework), Implementation Plan
+
+## Status
+
+PLANNED, nothing implemented. This is the design + phased execution plan for a native-macOS VM isolation tier for cases ("the VM subsystem"), modeled on Docker cases (`docs/docker-cases-plan.md`). Testbed prerequisite: a macOS 27 host (see Section 8).
+
+**⚠ DESIGN DIRECTION (owner, 2026-07-29): the subsystem is GUI-first.** Users want real macOS desktops, not headless SSH machines. Guests may be macOS (GUI-only in practice) or Linux (GUI or headless). Key decision 3 below carries the full consequences; anything in this doc that reads as "Linux-first / headless-first" predates this and has been revised.
+
+**2026-07-29: Phase 0 substantially validated on the beta testbed; full Apple-stack reference now lives in [`docs/vm-subsystem-apple-stack.md`](vm-subsystem-apple-stack.md)** (API surfaces, beta bugs, our empirical results, and design implications). Plan-relevant corrections from that work: vmnet's topology/port-forwarding APIs are macOS 26 (only the loopback fix is 27); guest provisioning is macOS-guests-only (Linux stays cloud-init, proven working); DiskImageKit has NO flatten/merge, so the `export` subcommand ships the layer chain (or flattens in-guest) instead of flattening; seed ISOs are base-build-time only, never attached at case runtime; per-case EFI variable stores are mandatory; guest health checks read DHCP leases, never serial/ping.
+
+## 1. Context and motivation
+
+WWDC 2026 session 224 ("Expand the Capabilities of your Virtualization App", https://developer.apple.com/videos/play/wwdc2026/224/) shipped the missing pieces for programmatic, fleet-style VM management on macOS:
+
+- **`VZMacGuestProvisioningOptions`**: automated first-boot setup of a macOS guest (user account, auto-login, SSH enabled) with zero interactive setup.
+- **DiskImageKit**: stacked disk images on the Apple Sparse Image Format (ASIF): a read-only base layer plus cheap per-VM cache/overlay layers. Direct analog of Docker image layers + writable container layer.
+- **vmnet framework**: custom network topologies and port forwarding from the host process.
+- **`VZCustomVirtioDevice`**: custom low-latency host<->guest channels (Linux guests).
+- **AccessoryAccess**: USB passthrough (not relevant to Codeman, out of scope).
+
+Codeman's isolation story today is Docker cases. On macOS, Docker means Docker Desktop / a Linux VM anyway, with weaker fidelity and a heavyweight dependency. The Virtualization framework gives hardware-virtualized per-case sandboxes natively, with a layered-image story that mirrors what `scripts/build-agent-image.mjs` does for Docker. This is the premium native-macOS tier ON TOP of Docker cases, never a replacement (Docker remains the cross-platform story; the Linux prod box cannot use any of this).
+
+## 2. Platform reality (hard constraints)
+
+| Constraint                | Detail                                                                                                                                              |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Host OS                   | macOS 27 "Golden Gate" required for the new APIs (dev beta since 2026-06-08, public beta since 2026-07-13, GA expected fall 2026)                    |
+| Host hardware             | Apple Silicon only (macOS 27 dropped Intel). Testbed: the owner's dedicated MacBook (Section 8); the M4 Mac mini (macOS 26.4, runs the second Codeman install) stays on stable + untouched |
+| Guest provisioning        | `VZMacGuestProvisioningOptions` needs macOS 27 on BOTH host and guest. Linux guests provision via cloud-init instead                                 |
+| macOS guest concurrency   | **Hard kernel cap: 2 concurrent macOS VMs per host. MEASURED on 27 beta 4 (2026-07-29), not inferred**: the 3rd VM is refused instantly with `VZErrorDomain` code 6 while 39% of RAM is free, so more hardware does NOT raise it. Since macOS GUI guests are the headline use case, this is a real product capacity limit to schedule around and surface in the UI. Linux guests are uncapped (resource-bound only) |
+| Language                  | Virtualization framework is Swift/ObjC only; Node cannot call it. Requires a Swift helper binary (Key decision 2)                                    |
+| Entitlement               | Host process needs `com.apple.security.virtualization`. Fine for a locally built dev binary; distribution needs signing thought (Section 9)          |
+| Nested virtualization     | Linux-guest-only on M3+. A macOS 27 VM cannot dependably host its own guests, so the host-side APIs must be tested on bare-metal 27 (dual-boot)      |
+| CI                        | Cannot run in CI (needs beta macOS on Apple Silicon). Same answer as tmux/docker: no-op all VM IO under `VITEST`, unit-test the pure parts            |
+
+## 3. Goal and user stories
+
+Add "VM cases" to Codeman: a case can point at a per-case virtual machine on a macOS host, and any CLI backend runs inside it over the existing remote-SSH session machinery. A LOCATION OVERLAY on cases, exactly like remote-SSH and Docker cases, NEVER a sixth `SessionMode`.
+
+- As a Mac user, I link a case to a VM so an autonomous run executes behind a hardware virtualization boundary (stronger than Docker's shared kernel) while file viewing, transcripts, and hooks keep working.
+- Per-case VMs are instant and cheap: a shared provisioned base image plus a per-case overlay, not a full image copy per case.
+- Killing a session kills only its in-guest tmux; the VM stays up while sibling sessions remain; case delete tears the VM down.
+- I export a case's VM overlay as a portable artifact (mirror of `docker-exports/`), secrets excluded.
+- On a non-mac host, or a Mac without the helper, the feature is invisible: zero UI, zero probes, zero errors.
+
+Non-goals for the MVP: USB passthrough, custom Virtio channels (Phase 3 candidate), macOS-guest fleets (capped at 2 anyway), Kubernetes-style orchestration, Intel Macs.
+
+## 4. Architecture
+
+```
+Codeman (Node, unchanged session layer)
+  |  JSON over stdout (same pattern as shelling out to docker/tmux)
+  v
+codeman-vm  (Swift package: CLI + per-VM GUI runner app in the console session)
+  |  Virtualization / DiskImageKit / vmnet
+  v
+per-case VM (macOS or Linux)
+      |-- GUI mode: VZVirtualMachineView in a window  --> guest screen sharing --> browser (noVNC)
+      |-- shell:    SSH on vmnet IP                   --> existing remote-SSH tmux machinery
+      ^ VirtioFS: host case dir mounted at the SAME absolute path
+```
+
+Note the runner is a **GUI app in the console user's session**, not a detached daemon: a daemon-launched VM cannot render, which is fatal for macOS guests and for Linux desktop cases.
+
+### Key decision 1: location overlay, not a mode
+
+Identical reasoning to Docker/remote-SSH (see CLAUDE.md): the session layer, respawn, Ralph, recovery, and quick-start plumbing all stay untouched. `SessionMode` stays five-valued. State mirrors the Docker pair: `~/.codeman/vm-hosts.json` + `vm-cases.json`, new `src/vm-hosts.ts` with the storage + pure helpers split.
+
+### Key decision 2: Swift helper CLI (`codeman-vm`)
+
+The framework is Swift-only, so all VM work lives in a SwiftPM package (`packages/codeman-vm/`), a CLI with a stable JSON contract:
+
+- `create-base --guest linux|macos`: build the shared base image. Linux: boot an arm64 cloud image with EFI + cloud-init, install Node 22 + tmux + the four CLIs (same inventory as `docker/agent.Dockerfile`), seal as base ASIF. macOS: IPSW restore + `VZMacGuestProvisioningOptions` (agent user, SSH on), then **desktop-readiness baking**, which is mandatory for GUI guests: suppress the per-user first-login assistant (`com.apple.SetupAssistant` keys + the User Template), enable auto-login (`autoLoginUser` + `/etc/kcpassword`), disable screensaver/lock/display-sleep, and set a static wallpaper (animated "aerials" wallpaper is unusable over remote display). ⚠ Use RAW (not ASIF) for macOS guest disks until the beta's macOS-guest space-reclamation bug is fixed.
+- `create <case>`: DiskImageKit stacked image: shared read-only base + fresh per-case overlay. Near-instant, space-efficient.
+- `start <case>` / `stop` / `status` / `ip`: lifecycle + vmnet NAT; `ip` reports the guest SSH endpoint.
+- `export <case>` / `import`: flatten overlay + workspace tar + manifest, credentials excluded (mirror of docker-export).
+
+A VM dies with its owning process, so `start` spawns a DETACHED per-VM runner process (analog of the detached `scripts/self-update.sh` trick) rather than a monolithic daemon; `status` talks to it over a unix socket in the instance data dir (`dataPath()`, never a hardcoded `~/.codeman` path).
+
+### Key decision 3: multi-guest, and GUI is a first-class mode (REVISED 2026-07-29 by the repo owner)
+
+The subsystem supports both macOS and Linux guests, and a guest runs in one of two **display modes**:
+
+| | macOS guest | Linux guest |
+| --- | --- | --- |
+| **GUI mode** | **the point of the feature**; a real macOS desktop. Mandatory: nothing renders without an attached `VZVirtualMachineView` in an unlocked host session | supported (EFI + virtio-gpu framebuffer) for desktop Linux cases |
+| **Headless mode** | not offered: a macOS guest with no view renders nothing, so a "headless macOS desktop" is a contradiction. SSH-only macOS is possible but is not what this feature is for | supported and cheap; the natural mode for agent/CI work, driven over SSH |
+
+Consequences that flow from GUI being first-class:
+- VM processes are **GUI apps in the console user's session** (LaunchAgent / `launchctl asuser`), never daemons. A daemon-launched VM cannot render.
+- **The host is part of the product surface**: it must auto-login, never lock, never sleep, and keep a live WindowServer. Host lock == every VM's screen goes black, so the screen lock is effectively a global kill switch for every VM display on the machine. The product must own these host settings rather than treat them as user preference.
+- **FileVault conflicts with unattended GUI hosting** and the trade-off must be a deliberate choice: FileVault disables auto-login, so a full-disk-encrypted host needs a human at a keyboard (or a remote screen-sharing session) after every reboot before any VM can render. Options are (a) FileVault on, accept manual login per boot, (b) FileVault off on a dedicated VM host so it boots straight into a rendering session, or (c) FileVault on plus a remote-unlock runbook. Codeman should detect the state and tell the user which one they are in instead of silently serving black screens.
+- **Guests must be desktop-ready, not just booted**: auto-login, no screensaver/lock, and the per-user first-login assistant pre-suppressed at base-image time (`com.apple.SetupAssistant` keys, plus the User Template so later accounts inherit it). Otherwise the user connects to a login prompt or a setup wizard, which is exactly what happened during the first hands-on run.
+- **Capacity is capped for macOS**: at most 2 concurrent macOS VMs per host, confirmed by our own test on 27 beta 4 (3rd refused with `VZErrorDomain` 6 at 39% free RAM; it is a kernel quota, so bigger hardware does not help). Scheduling must queue or evict beyond 2, the UI must explain why, and the scheduler should tolerate the acknowledged slot-leak bug (a slot occupied with nothing running, host-reboot to clear). Linux guests are uncapped and bounded only by host resources, which is the lever for scaling case counts on one machine.
+- **Access is via the guest's own screen**, viewable in a browser through the noVNC chain (see `docs/vm-subsystem-apple-stack.md` §8), so no client-version or client-install requirements land on the user.
+
+Provisioning per guest type: `VZMacGuestProvisioningOptions` for macOS (needs 27-on-27, first-boot-only, and does NOT skip the per-user wizard), cloud-init NoCloud seed ISO for Linux (proven working).
+
+### Key decision 3b: the GUI VM host profile, and supervision that catches black screens
+
+GUI hosting only works if the host is configured for it and supervised. This profile was derived the hard way on the testbed (prototyped there 2026-07-30) and should be what `codeman-vm` installs and verifies:
+
+**Host profile** (the product should own these, not leave them to preference):
+1. **No login barrier.** Either FileVault off + auto-login (a dedicated VM host boots straight into a rendering session, fully unattended), or FileVault on and remote reboots done with `sudo fdesetup authrestart`, where the pre-boot unlock *is* the login so the machine returns already logged in with encryption intact. **`authrestart` is VERIFIED on the testbed (2026-07-30): the host rebooted remotely and came back with a live logged-in console session, FileVault still enabled, no password prompt** — this is the recommended pattern for an encrypted GUI VM host. Plain reboots on a FileVault host always need a human, so Codeman should detect that combination and warn instead of serving black screens.
+2. **Never lock**: lock policy off (needs the account password, so it is a setup step, not a scriptable one) plus `caffeinate -d -i -m -u` re-armed per session.
+3. **Never sleep**: `pmset -a sleep 0 displaysleep 0 disablesleep 1`; a physical display is NOT required (a lid-closed laptop renders fine, only an unlocked session matters). Note OS updates reset these.
+4. **Session-independent control plane**: run VPN/remote access as a system service, never a session app, and keep the access chain (forwards, VNC proxies, web endpoints) in LaunchDaemons so a session restart cannot sever operator access.
+
+**Supervision** must be a **root LaunchDaemon**, not a user LaunchAgent. This is the load-bearing detail: a user agent cannot launch a GUI app into the Aqua session, so its restart attempts fail *silently* (the child dies instantly, leaving an empty log while the supervisor cheerfully reports success). A root daemon can, via `launchctl asuser <uid> sudo -u <user> …`, and those launches persist. Prototyped and verified on the testbed 2026-07-30; a working supervisor runs on a short interval and:
+
+- Restarts the runner when the process is gone **or when its log shows `WindowServer event port death`**, which means it is permanently blind while still looking alive.
+- Defers restarts while the console is at the login window, and launches into whichever session actually exists (resolve the console user with `stat -f %Su /dev/console`, never a hardcoded one).
+- Re-points the guest port-forward whenever the guest's NAT lease changes, which happens on **every guest boot** under plain NAT. A vmnet DHCP reservation for a stable per-case IP is the better long-term answer.
+- **Re-applies host power settings**, because `pmset -a disablesleep 1` does NOT survive a reboot (caught on the supervisor's first run after a real reboot) and OS updates reset it too.
+- Re-arms the keep-awake helper, which dies with its session.
+- Ideally also samples the guest framebuffer for non-black content, since a black screen is the one symptom common to every failure mode here.
+
+`pgrep` alone is worthless for health: every failure mode in this session presented as a healthy process.
+
+### Key decision 4: sessions ride the existing remote-SSH machinery
+
+A provisioned guest is literally an SSH host on a vmnet IP. Session launch = the remote-SSH flow with the host swapped in: durable remote `tmux -L codeman-remote`, session names failing `SAFE_MUX_NAME_PATTERN` on purpose, EVERY ssh command line through `buildSshConnectionArgs()` (command-injection invariant), run flows through `POST /api/quick-start` (never `POST /api/sessions`, which stat-validates `workingDir` locally). What is genuinely new is only lifecycle (create/start/stop/export) and the vm-hosts/vm-cases overlay state.
+
+### Key decision 5: workspace via VirtioFS at the same absolute path
+
+Mirror the Docker bind-mount invariant: the case workspace is a real host directory shared into the guest via VirtioFS and mounted at the SAME absolute path. That keeps file-routes/watchers on real host bytes and makes the in-guest transcript projHash match the host. Without this, transcripts/attachments/file viewer all silently degrade.
+
+### Key decision 6: credentials seeded, hooks bridged
+
+- Credentials are SEEDED (read-only share, copied into the guest once at create), never shared read-write, and excluded from exports: byte-for-byte the Docker cases rule and rationale.
+- Hooks: on the loopback-only prod bind a guest cannot reach `127.0.0.1:3000`. Mirror `CODEMAN_DOCKER_BRIDGE_HOOKS` with a `CODEMAN_VM_BRIDGE_HOOKS` opt-in listener on the vmnet gateway IP; otherwise idle detection falls back to output-based, same as Docker.
+
+### Key decision 7: drift and teardown copy Docker semantics verbatim
+
+Config hash label on the VM (guest type, cpu/mem, share list); a drifted launch is REFUSED, never silently launched stale. One VM per case shared by all sessions; session kill = in-guest tmux kill only; case delete = stop + remove overlay; instance-scoped boot reaper for orphaned runner processes.
+
+## 5. Implementation phases
+
+**Phase 0, testbed (no repo code):** dedicated MacBook on the macOS 27 beta, remotely accessible over the tailnet (setup protocol in Section 8), Xcode 27 beta, then a throwaway Swift script proving the loop: create base -> overlay -> boot -> ssh in. This validates 80% of the design before any Codeman code.
+
+**Phase 1, `codeman-vm` helper:** SwiftPM package, the six subcommands above, JSON contract doc, detached runner + unix-socket status, Linux base image build. Deliverable is testable entirely without Codeman.
+
+**Phase 2, Codeman integration:** types (`VmHost`/`VmCase`/`SessionVm`), `src/vm-hosts.ts` (+ pure helpers: config hash, arg building, endpoint parsing), Zod schemas, `case-routes` link/unlink + listing, `quick-start` vm branch reusing the remote-SSH launch path, `Session` threading + recovery round-trip, `VITEST` no-op layer, unit tests. Feature-detect: darwin + arm64 + helper binary present, else invisible.
+
+**Phase 3, polish:** export/import UI, frontend Create Case "VM" tab + case-picker labels, SSE `vm:*` events, macOS-guest opt-in with cap surfaced, custom-Virtio input channel exploration, CLAUDE.md Key Pattern + `docs/vm-cases.md` + COM.
+
+## 6. Testing
+
+- Pure helpers unit-tested (ports pattern from `docker-hosts.ts`: 26 tests there, aim similar).
+- All helper-invoking IO no-ops under `VITEST` (the `IS_TEST_MODE` pattern in `tmux-manager.ts`).
+- End-to-end verification happens ON the beta MacBook, per the always-end-to-end rule: real base build, real per-case overlay boot, real quick-start into the guest, workspace round-trip through VirtioFS, session-delete keeps VM up, case-delete removes it.
+- CI never runs the real path; the static guards are type-level + unit-level only.
+
+## 7. Risks
+
+1. **Beta API churn**: everything here targets beta SDKs; symbol/behavior changes are likely before fall GA. Mitigation: Phase 0/1 are throwaway-tolerant; no Codeman-side commitment until the helper contract survives a beta cycle.
+2. **New artifact class**: Codeman ships pure TypeScript today; a Swift binary changes build/distribution (build-on-install via `xcrun swift build` on macs with Xcode CLT? prebuilt signed binary per release?). Needs an owner decision; local dev build is fine for the whole beta period.
+3. **Entitlement/signing**: `com.apple.security.virtualization` is trivial for local dev, real for distribution.
+4. **Adoption gating**: users need macOS 27 + Apple Silicon for months after GA. Docker cases remain the default recommendation; VM cases ship dark (feature-detected) with zero cost to everyone else.
+
+## 8. Beta testbed plan: dedicated MacBook (actionable now)
+
+Testbed is a dedicated MacBook the owner sacrifices to the beta (after a full backup). This supersedes the earlier dual-boot-the-Mini idea (git history has it): a dedicated machine means no OS-switching, no downtime for the Mini's live Codeman, and no FileVault pre-boot headaches.
+
+**Sequencing rule that makes it headless: configure ALL remote access on the CURRENT macOS first, THEN upgrade in place.** An in-place beta upgrade preserves Remote Login, Tailscale, user accounts, and auto-login, so there is no Setup Assistant and no post-install physical step. (A fresh install would boot into GUI-only Setup Assistant with no SSH, which on a headless box is a dead end.)
+
+Confirmed hardware (2026-07-28): MacBook, M3, 16 GB RAM, 256 GB disk with ~100 GB free. Verdict: green. M3 = eligible + nested-virt capable; 16 GB = host + 2-3 concurrent Linux guests (macOS guest = one at a time); 100 GB = fits with discipline: install Xcode 27 beta with the macOS platform only (skipping iOS/watchOS/tvOS simulators saves 15-20 GB), and defer any macOS guest base (~30 GB) to an external SSD or until actually needed. Linux guests + sparse ASIF overlays are the comfortable path.
+
+### Pre-upgrade checklist (owner, physical, once)
+
+1. Full backup (Time Machine or clone); the machine should be considered beta-only afterwards.
+2. Tailscale: install, sign into the tailnet, confirm it appears in `tailscale status` from another node.
+3. System Settings -> General -> Sharing: **Remote Login ON** (SSH) and **Screen Sharing ON** (for the rare GUI-only moments: Xcode license, Apple Account dialogs).
+4. **FileVault stays ON** (owner decision 2026-07-28, security over convenience). Consequences: auto-login is unavailable, but FileVault's pre-boot unlock doubles as login, so an unlocked boot still lands in a live GUI session; planned remote reboots go through `sudo fdesetup authrestart` (unlocks for exactly one restart); an UNPLANNED reboot (beta kernel panic, battery drain) parks the machine at the pre-boot screen, no SSH/Tailscale, until the password is typed physically. If the testbed goes silent, suspect this first. Keep it on AC so the battery absorbs power blips.
+5. Beta enrollment (manual): sign into the Apple Account in System Settings; System Settings -> General -> Software Update -> **Beta Updates** -> select the **macOS 27 Developer Beta** (preferred: framework fixes land weeks earlier than public beta; free since 2023 after accepting the agreement once at developer.apple.com; public-beta alternative: enroll at beta.apple.com). Then run the offered upgrade: plugged in, lid open, trusted network.
+6. Send over: tailnet name/IP, username, and a first-login password (key install + lockdown happens remotely right after).
+
+### Post-upgrade setup (remote, over the tailnet)
+
+1. Verify: `sw_vers` reports 27.x, SSH reachable.
+2. Server-ize the laptop: `sudo pmset -a sleep 0 disksleep 0 disablesleep 1` (lid-closed operation without an external display), `womp 1` (wake on network), `sudo systemsetup -setrestartpowerfailure on`. Keep on AC power.
+3. Install the controlling host's SSH key, then disable password auth.
+4. Xcode 27 beta install (the one step needing the owner's Apple Account sign-in once, doable via Screen Sharing from anywhere); `xcode-select`, license accept, verify `swift --version` + the 27 SDK (`xcrun --show-sdk-version`).
+5. Phase 0 prototype loop, all remote from here: Linux guest base image (no 27-on-27 provisioning dependency), DiskImageKit overlay, boot, vmnet NAT, ssh into the guest, run `claude --version` inside.
+6. Only after that loop works: start Phase 1 in `packages/codeman-vm/`.
+
+## 9. Open decisions (owner)
+
+1. Linux base distro/image for the default guest (proposal: Ubuntu 24.04 arm64 cloud image, matching the docker agent image's userland).
+2. Helper distribution for GA: build-on-install vs prebuilt signed binary vs "bring your own Xcode".
+3. Ship dark behind `CODEMAN_VM_CASES=1` for the first release, or feature-detect only?
+4. Export format parity with docker-exports (one manifest schema for both?).
+
+## References
+
+- Session 224: https://developer.apple.com/videos/play/wwdc2026/224/
+- Fleet-angle writeup: https://bitrise.io/blog/post/wwdc26-the-virtualization-framework-updates-that-matter-for-large-mac-fleets
+- Beta timeline: https://www.macworld.com/article/3189014/apple-july-2026-ios-ipados-macos-27-public-betas-tv-arcade-releases.html
+- Internal analogs: `docs/docker-cases-plan.md` (architecture template), `docs/remote-sessions.md` (session transport), `docs/architecture-invariants.md#docker-cases`

docs/vm-subsystem-apple-stack.md

@@ -0,0 +1,281 @@
+<!-- Reference doc for the VM subsystem (Codeman VM cases). Compiled 2026-07-29 from: Apple DocC JSON backend, macOS 27 beta 4 SDK on the testbed, a multi-source web research sweep, and hands-on prototyping on a MacBook Air M3 running macOS 27.0 beta (26A5388g). Companion to vm-cases-plan.md (the Codeman integration plan). -->
+
+# The VM Subsystem: Apple Virtualization Stack Reference (macOS 27 "Golden Gate")
+
+"VM subsystem" is the working name for Codeman's native-macOS VM isolation tier and everything under it. This document is the single place for what the Apple stack actually provides, what we have verified ourselves on the beta, and what is known-broken. The Codeman-side design lives in `docs/vm-cases-plan.md`.
+
+**Research method note:** Apple's HTML doc pages are JS-rendered and come back empty to fetchers. The working route is the DocC JSON backend: `https://developer.apple.com/tutorials/data/documentation/<path>.json` (page content) and `https://developer.apple.com/tutorials/data/index/<framework>` (full symbol tree with per-symbol `beta` flags). Everything below marked "Apple docs" was parsed from that backend directly.
+
+## 1. Component map and minimum OS versions
+
+| Component | What it is | Min host OS | Notes |
+| --- | --- | --- | --- |
+| Virtualization.framework core | VMs, EFI/Linux boot, virtio devices, VirtioFS | macOS 11-13 era | Unchanged basics; our prototype uses nothing newer than macOS 13 APIs except the DiskImageKit bridge |
+| **DiskImageKit** | ASIF + raw disk images, layered stacks | **macOS 27** | Swift-only, no ObjC headers. Section 2 |
+| **Guest provisioning** | First-boot account/SSH setup for macOS guests | **macOS 27 host AND guest** | Mac guests only as of beta 4. Section 3 |
+| vmnet topology/port-forward/DHCP APIs | Custom networks, port forwarding | **macOS 26** (NOT 27) | 27 adds exactly one fix: loopback port forwarding. Section 4 |
+| `VZVmnetNetworkDeviceAttachment` | In-process vmnet attach | macOS 26 | |
+| **`VZCustomVirtioDevice`** family | Custom paravirt devices | **macOS 27** | Linux guests only, custom guest driver required. Section 5 |
+| AccessoryAccess (USB passthrough) | USB claim + attach to VMs | macOS 27 | Requires paid-team provisioning profile, Dock app. Out of scope for Codeman. Section 6 |
+
+Corrections to the WWDC-session framing we started with: vmnet's topology family is a macOS 26 story (129 symbols, zero beta-flagged in 27); provisioning does NOT currently extend beyond macOS guests despite the generic-looking `VZGuestProvisioningOptions` base class; DiskImageKit has no attach/mount API at all (it is a file-format library that hands `DiskImage` objects to Virtualization, no `/dev/diskN`, no root needed, no entitlement documented).
+
+## 2. DiskImageKit (macOS 27, Swift-only)
+
+Public framework, `/System/Library/Frameworks/DiskImageKit.framework`. No ObjC headers; the API surface lives in the `.swiftinterface`. Verified present in the CLT 27 beta 4 SDK, and our prototype compiled against it with plain `swiftc` on the first attempt.
+
+### API surface (complete as of beta 4)
+
+```swift
+class DiskImage {
+  convenience init(creating: some DiskImage.CreationConfiguration) throws
+  convenience init(opening: some OpenConfigurationProtocol) throws
+  func appending(any DiskImage.CreationConfiguration & DiskImage.StackableLayer) throws -> any StackedImage
+  func appending(consuming DiskImage) throws -> any StackedImage   // reattach an existing layer; validates parentUUID
+  func truncate(blockCount: Int) throws                            // stacked: affects top layer; does NOT resize guest fs
+  var blockCount, blockSize, format, layerType, layerUUID, parentUUID, openMode, size, url
+}
+protocol StackedImage: DiskImage { var layers: [DiskImage] }
+struct OpenConfiguration { init(url:mode:); Mode = automatic | readOnly | readWrite }
+// CreationConfiguration statics: .asif(url:blockCount:blockSize:), .asifLayer(url:type:), .raw(url:blockCount:)
+// DiskImage.LayerType: .cache | .overlay | .overlay(blockCount:)
+// DiskImage.BlockSize: .bytes512 | .bytes4096
+// Errors: CorruptedImageError, IncompatibleStackingError(reason), InvalidBlockCountError, UnsupportedFormatError
+```
+
+Bridge into Virtualization is a new beta convenience init on the existing attachment class. Note there is no `readOnly:` parameter; read-only-ness comes from each layer's own `openMode`:
+
+```swift
+VZDiskImageStorageDeviceAttachment(diskImage: stack, cachingMode: .automatic, synchronizationMode: .full)
+```
+
+### Stacking rules (Apple docs, verbatim where quoted)
+
+- ASIF works standalone or stacked. "You can only use RAW images as standalone images or as **base** images in stacked configurations." Upper layers are always ASIF.
+- **One cache layer per stack**, any number of overlays conceptually, "shallow stacks perform better" (WWDC 224). No published max-depth guidance.
+- "Layers are processed from bottom (base) to top. The **topmost layer determines the stack's size and receives all writes**." `.overlay(blockCount:)` therefore also grows the virtual disk.
+- UUID chaining: appending sets the child's `parentUUID` to the parent's `layerUUID`. Raw bases have no UUID. "The layer UUID **changes if the layer is written to**", and reattaching a mismatched layer throws `IncompatibleStackingError`. This is the mechanism that makes a shared read-only base safe.
+- Base sharing across multiple VMs is the stated design intent ("can be shared across multiple VMs"), with the WWDC caveat that per-VM auxiliary files (EFI variable store, macOS auxiliary storage) must be duplicated per VM, never shared.
+- **There is no flatten/merge.** An overlay cannot be merged back into its base (confirmed by Howard Oakley's coverage plus an independent hands-on report). Export/move flows must ship the layer chain, or flatten inside a guest (dd to a fresh attached image).
+
+### Known issues and adoption
+
+- **ASIF space reclamation is broken for macOS guests on the beta** (deleted files never return space, survives reboots). Linux guests reclaim correctly on both raw and ASIF via `fstrim -av`. Single detailed field report, unrefuted. Since the VM subsystem targets macOS guests, the practical rule until this is fixed is: back macOS guest disks with RAW, and revisit ASIF stacking for macOS guests each beta (stacking still works, the disks just never shrink).
+- **Zero shipping adopters anywhere.** tart has a design issue with no activity; nobody has published working DiskImageKit code. Everything must be treated as field-untested (and our own testing bears that out, Section 8).
+- Framework binary grew every beta (588 → 598 across betas 1-4); expect churn until GA.
+- Release notes list no DiskImageKit known issues in any beta, which given the above says more about the notes than the framework.
+
+## 3. Guest provisioning (macOS guests only)
+
+```swift
+class VZGuestProvisioningOptions: NSObject { func validate() throws }   // "use one of its subclasses"
+class VZMacGuestProvisioningOptions: VZGuestProvisioningOptions {
+  var fullName, username, password: String
+  var logsInAutomatically: Bool
+  var enablesRemoteLogin: Bool   // SSH
+}
+// Wiring: VZMacOSVirtualMachineStartOptions.guestProvisioningOptions (Mac-typed)
+//         .setGuestProvisioning(_:) throws  (validating setter)
+```
+
+- **Requires macOS 27 on host AND guest.** Older guests **silently ignore** the options (no error).
+- **First boot after restore only.** Cannot reconfigure an already-provisioned VM; property changes after start are no-ops.
+- The base class is forward-looking scaffolding; its only subclass is Mac. A Linux/cloud-init analogue may come later; do not assume it lands in 27.0. For Linux guests, cloud-init NoCloud seed ISOs remain the provisioning path (proven working, Section 8).
+- Field-verified behavior (third-party hands-on, beta 3): provisioned account gets full admin + sudo; Setup Assistant fully skipped; SSH reachable ~48 s after first boot. **Race**: the account is created late in first boot (~T+54 s), after LaunchDaemons start (~T+33 s), so anything at daemon-level must wait for the account to exist.
+- Open Apple-acknowledged bug: provisioned users are invisible to `CSIdentityQueryExecute()` (FB23716201).
+- IPSW acquisition gotcha for automation: `VZMacOSRestoreImage.latestSupported` tracks the latest *release* (returned 26.5.2), not the installed beta; beta IPSWs must be fetched from the seed CDN explicitly.
+
+## 4. vmnet: a macOS 26 feature set, one macOS 27 fix
+
+Everything interesting shipped in macOS 26: `vmnet_network_create`, `vmnet_network_configuration_create`, `..._add_port_forwarding_rule`, `..._add_dhcp_reservation`, subnet/prefix/MTU/external-interface setters, NAT44/NAT66/DHCP/DNS-proxy/RA disables, plus serialization (`vmnet_network_copy_serialization` / `_create_with_serialization`) for handing networks across processes. `VZVmnetNetworkDeviceAttachment` is macOS 26.
+
+macOS 27's only change (beta 4 release notes, verbatim): "The vmnet port forwarding APIs now support port forwarding when communicating over loopback." That closes the old gap where the host could not reach its own forwarded ports via 127.0.0.1 (confirmed working by the original bug reporter). Directly relevant to Codeman's loopback-bound production server talking to per-case guests.
+
+Gotchas:
+- vmnet networks are **not persisted**; they die with the owning process. Persist settings yourself and recreate (or serialize across processes).
+- The `com.apple.vm.networking` entitlement is still restricted ("contact your Apple representative", though DTS says most requests are approved). The plain `VZNATNetworkDeviceAttachment` needs no special entitlement and is what our prototype uses.
+- Ecosystem signal: tart's maintainer is not adopting in-process vmnet (prefers their separate-process softnet), so field testing of these APIs is thin.
+
+## 5. VZCustomVirtioDevice (macOS 27, Linux guests only)
+
+14 new types (`VZCustomVirtioDevice(+Configuration/Delegate/Provider)`, `VZVirtioQueue(+Element)`, `VZVirtioFeatureSet`, shared-memory-region types, `VZGuestMemoryMapping`), wired via `VZVirtualMachineConfiguration.customVirtioDevices`. Mandatory for guest discovery: `deviceID`, `pciClassID`, `pciSubclassID`, `virtioQueueCount`. You must write the Linux guest driver (Virtio spec 1.3/1.4). Threading contract: the framework calls the device/delegate on a serial queue (`deviceQueue`, defaulting to the VM's queue). Zero public adopters. For the VM subsystem this is a Phase 3+ option for a low-latency host-guest channel; SSH over NAT is proven and sufficient for now.
+
+## 6. Signing and entitlements
+
+- **Core loop (VZ + DiskImageKit + provisioning): ad-hoc signing with only `com.apple.security.virtualization` suffices.** Verified by us on beta 4 (plain `codesign --entitlements ... -s -` on a `swiftc` binary) and independently by third parties on beta 3. DiskImageKit documents no entitlement at all.
+- **Over-entitling is the actual trap.** Adding `com.apple.application-identifier`/team-identifier keys without an embedded provisioning profile hangs the process before `main` (watchdog kill); shipping `com.apple.vm.networking` unauthorized gets AMFI SIGKILL at exec (exit 137, no crash report, even for `--version`). Keep the entitlements plist to exactly the one key.
+- **USB passthrough breaks the ad-hoc story**: `com.apple.developer.accessory-access.usb` is profile-restricted (any paid team, no ad-hoc), additionally requires `com.apple.security.device.usb`, and `AAUSBAccessoryManager` presents UI, so it wants a Dock app, not a headless CLI. Out of scope for Codeman.
+- No Xcode required for any of the above: the CLT beta (~500 MB via `softwareupdate`) carries the full macOS 27 SDK including DiskImageKit and compiles/signs everything.
+
+## 7. Ecosystem state (July 2026)
+
+- **tart is now `openai/tart`** (moved from cirruslabs, mid-2026) and **relicensed to FSL-1.1-ALv2** (no longer permissive). Provisioning support shipped in 2.33.0. Old cirruslabs URLs and license assumptions are stale.
+- VirtualBuddy shipped provisioning ("Skip Setup Assistant") in 2.2 betas; had to add account-detail validation and a workaround installer for the cross-version bug below.
+- lima is deliberately waiting for GA before touching macOS 27 APIs.
+- **Code-Hex/vz (Go bindings) is dormant** (no commits since Feb 2026, no macOS 27 APIs), so the entire Go ecosystem (podman-machine, colima) currently has no path to these APIs. Swift is the only realistic binding today, which validates the VM subsystem's Swift-helper design.
+- Useful pattern if ever supporting older SDKs: resolve new classes via `NSClassFromString` at runtime (no link-time dependency), fail gracefully when absent.
+- **Cross-version restore bug**: installing a macOS 27 guest from IPSW on a macOS 26 host fails at 77-78% (`VZErrorDomain 10007`); fixed in 26.6b3 + Xcode 27b4 era, with a nasty MobileDevice.pkg trap (installing it from Xcode 27 beta on a 26 host requires a full macOS reinstall to undo). Not relevant to our 27-host testbed, very relevant to anyone on a 26 host.
+
+## 8. Our empirical results (beta 4, 26A5388g, MacBook Air M3, 2026-07-29)
+
+Prototype tooling, all in `~/vm-lab/` on the testbed, compiled with CLT-only `swiftc` and ad-hoc signed with the single virtualization entitlement:
+
+| Tool | Purpose |
+| --- | --- |
+| `vzboot.swift` | Linux guest: EFI boot + virtio disk/net/entropy + NAT + optional cloud-init seed ISO + serial on stdio |
+| `vzstack.swift` | Same, but boots a DiskImageKit stack (read-only raw base + ASIF overlay) |
+| `vzmac.swift` | macOS guest: `install` (IPSW restore into a bundle) and `run` (boot, `--provision` for first-boot account/SSH) |
+| `vzmacgui.swift` | macOS guest in a real window via `VZVirtualMachineView` (required for the guest to render at all) |
+| `setup-seed.sh` | Builds a cloud-init NoCloud seed ISO with `hdiutil makehybrid` (volume label `cidata`) |
+| `vncproxy.py` | RFB proxy that advertises only security type 2, so version-skewed/browser clients can authenticate |
+| noVNC + `websockify` | Browser access; `websockify --web noVNC-<ver> 0.0.0.0:<port> 127.0.0.1:<proxy>` |
+| `vmwatchdog.sh` + `vmaccess.sh` | Supervision: root LaunchDaemon that restarts a blind/dead runner, re-points the forward, re-applies `pmset`, re-arms keep-awake; plus a keeper for the proxy/web endpoints |
+
+Host-side diagnostics written during this work (in the session scratchpad, not on the testbed): `vnclogin.py` (Apple DH auth + session open, distinguishes "credentials rejected" from "authorized but session refused"), `vncshot.py` (decodes the raw framebuffer to PNG and reports non-black pixel counts, plus optional synthetic wake input), `relay.py` (plain TCP relay used to bridge a tailnet peer to a LAN-only host), `sshpw.py` (pty-driven password SSH for the one-time key bootstrap into a freshly provisioned guest).
+
+### Proven working
+
+1. **Boot**: Debian 12 arm64 cloud images (nocloud and genericcloud variants) boot under `VZEFIBootLoader` + `VZGenericPlatformConfiguration`.
+2. **Networking**: `VZNATNetworkDeviceAttachment` gives the guest a `192.168.64.x` DHCP lease from the host's bootpd (leases visible in `/var/db/dhcpd_leases`, bridge is `bridge100`).
+3. **cloud-init provisioning**: NoCloud seed ISO (built with `hdiutil makehybrid -iso -joliet -default-volume-name cidata`) created a `codeman` user with SSH key + passwordless sudo on first boot; `ssh codeman@<lease-ip>` from the host works with key auth.
+4. **DiskImageKit stack mechanics**: opening a raw base `.readOnly`, appending an ASIF overlay (`ASIFCreationConfiguration.layer(url:type:.overlay)`), attaching via `init(diskImage:)`, and booting it. The overlay received ~44 MB of boot-time writes while the **base file's SHA-256 stayed bit-identical**, which is the write-isolation property the whole per-case design rests on.
+5. **Reattach**: reopening an existing overlay and `appending(consuming:)` onto the same base passes UUID validation.
+6. **macOS guest install (added later the same day)**: `VZMacOSInstaller` restore of the 27.0 IPSW (26A5388g, fetched from the seed CDN via appledb; same build as host) into a sparse 64 GiB raw disk + auxiliary storage: INSTALL-OK on the first attempt, ~25 minutes.
+7. **Headless guest provisioning WORKS**: `VZMacGuestProvisioningOptions` via `setGuestProvisioning` (username, password, `enablesRemoteLogin`, `logsInAutomatically=false`) produced, with zero GUI interaction: an account with full admin (groups include `80(admin)`, `com.apple.access_ssh`), Remote Login on from first boot, port 22 reachable ~140 s after first-boot start, hostname auto-derived from the account ("Codemans-Virtual-Machine"). SSH password auth is on by default, so the bootstrap path is: pty-driven password login once to install `authorized_keys`, key auth thereafter. Note the provisioned account's sudo is NOT passwordless (`echo <pass> | sudo -S ...`), and provisioning is first-boot-only (later boots take no options and just boot).
+8. **Slot-leak bug NOT reproduced on 26A5388g**: a guest-initiated `shutdown -h now` fired `guestDidStop` cleanly and an immediate relaunch started fine (SSH-ready again in ~75 s), so FB22967193 (VM slot leaked on guest-initiated shutdown, host reboot to recover) did not manifest after one cycle. Either fixed in beta 4 or needs more cycles to trigger.
+
+### Unstable / under investigation (beta-quality territory)
+
+Boot reliability degraded over a ~15-VM session on one host boot, ending with reproducible silent hangs (VM process alive, 0% CPU, no DHCP, no ARP, nothing on serial):
+
+- A genericcloud base that had been booted read-write once (cloud-init first boot) subsequently hung on every boot **with the seed ISO still attached**, while booting **without** the seed succeeded, then later runs failed in both configurations. The seed correlation is strong but was observed while host state was already suspect, so it needs a retest from a clean baseline.
+- The first stack-boot "success" that later wedged turned out (via DHCP lease timestamp arithmetic) never to have reached the network at all; its overlay growth was pre-network boot writes.
+- Working hypothesis, matching a class of acknowledged beta bugs (e.g. the VM-slot counter that leaks on guest-initiated shutdown, FB22967193, where only a host reboot recovers): accumulated hypervisor/vmnet state on the host degrades boots. Requires a host reboot + a disciplined retest matrix to confirm.
+
+### Display rendering: the single most important operational finding
+
+**A VZ macOS guest renders nothing unless a `VZVirtualMachineView` is attached AND the host session is actually drawing.** Verified byte-for-byte: the guest's own screen sharing serves an all-zero framebuffer (0 non-black bytes across 400 KB samples, with a sane pixel format: `rmax/gmax/bmax = 255`, shifts 16/8/0), in-guest `screencapture` fails with "could not create image from display", and no `IODisplayWrangler` shows up in the guest's `ioreg`. Three distinct states all produce black:
+
+1. **Headless** (VM run with no view attached).
+2. **View attached, host session locked.** The lock screen suspends drawing and the guest's virtual GPU produces no frames.
+3. **View attached, but the app lost its WindowServer connection** (see the incident below): black permanently until the app is restarted.
+
+**Consequence for the VM subsystem: rendering is a first-class requirement, not an optional extra (owner decision 2026-07-29).** The product serves GUI desktops: mandatory for macOS guests, optional-but-supported for Linux guests (which can also run headless over SSH). Any VM in GUI mode must be launched by an app that attaches a `VZVirtualMachineView`, from inside a host GUI session that is logged in and unlocked. That makes the following non-negotiable parts of the design, not workarounds:
+
+- VMs run as **GUI apps in the console user's session** (launched via a LaunchAgent or `launchctl asuser`), never as daemons.
+- The **host must auto-login and never lock or sleep**; a locked host is equivalent to a powered-off display for every VM on it.
+- The **guest must auto-login, never lock, and have its first-login assistant pre-suppressed**, or the "desktop" a user connects to is a password prompt or a setup wizard.
+- A VM app that loses its WindowServer connection is **permanently blind** and must be restarted; supervision has to detect that, not just check that the process is alive.
+- The **2-concurrent-macOS-VM cap** becomes a real capacity limit for the product, so it must be surfaced in the UI and tested (still untested worldwide as of this writing).
+
+### Incident 2026-07-29: `killall -HUP loginwindow` (never do this on a remote Mac)
+
+Applying a wallpaper change on the testbed with `killall -HUP loginwindow` restarted the host's login session. Three consequences:
+
+1. **The Mac dropped off the tailnet entirely.** Tailscale's App Store build is a GUI app living in the user session, so killing the session killed the VPN; remote access was gone until someone logged in. Recovery came from a second machine on the same LAN: it could still SSH in, and then relay ports back over the tailnet (a plain TCP relay on a tailnet-connected LAN peer is a good out-of-band path worth keeping ready).
+2. **The VM app lost its WindowServer connection** (`HIToolbox: received notification of WindowServer event port death`) while surviving as a process. Every later black screen traced to this, and nothing guest-side could fix it; only restarting the app restored rendering.
+3. The session's `caffeinate` died, so the host resumed auto-locking.
+
+Rule: on a remote Mac, never run session-level commands (`killall -HUP loginwindow`, `pkill -u <user>`, logout, fast user switching). `killall WallpaperAgent` alone is session-safe. Before any such command, enumerate what depends on that session: VPN, VM processes, port forwards, keep-awake helpers.
+
+### Keeping host and guest usable unattended
+
+- **Host**: `caffeinate -d -i -m -u` prevents display sleep but does NOT override the lock policy. "Require password after screen saver begins or display is turned off → Never" must be set in System Settings; it needs the account password, so a passwordless-sudo shell cannot script it, and turning it off does NOT dismiss a lock that is already engaged (one more unlock is always needed). `pmset -a disablesleep 1` keeps a lid-closed laptop awake but **does not survive a reboot**, and OS updates reset it too, so a supervisor should re-apply it rather than assume it sticks.
+- **Rebooting an encrypted host**: use `sudo fdesetup authrestart`. FileVault's pre-boot unlock doubles as the login, so the machine returns with a **live logged-in console session** and encryption intact, no password prompt, and supervision can then bring the VMs back by itself. Verified 2026-07-30. A plain `reboot` parks at the lock screen and blacks out every VM until a human logs in.
+- **Guest**: set `autoLoginUser` plus a valid `/etc/kcpassword` (XOR-obfuscated password file, key `7D 89 52 23 D2 BC DE A3`, payload zero-padded to a multiple of 12). `sysadminctl -autologin` fails with `SACSetAutoLoginPassword error:22` on provisioned accounts, and a fresh guest has no Python, so generate the bytes on the controlling host and copy them in. Then `pmset -a displaysleep 0 sleep 0 disablesleep 1`, `defaults -currentHost write com.apple.screensaver idleTime 0`, `defaults write com.apple.screensaver askForPassword 0`, and `caffeinate` inside the guest. ⚠ `autoLoginUser` was observed being wiped by failed `sysadminctl -autologin` attempts; verify it after each boot until stable.
+- **Wallpaper**: animated "aerials" wallpaper is brutal over VNC. The provider lives in `~/Library/Application Support/com.apple.wallpaper/Store/Index.plist` under several keys (`AllSpacesAndDisplays:Desktop`, `:Idle`, and `SystemDefault:*` which is what the login/lock screen uses). Switch each `Provider` to `com.apple.wallpaper.choice.solid-color` with PlistBuddy and restart `WallpaperAgent`. The login-window copy is cached and only refreshes on a later login cycle.
+
+### Remote GUI/SSH access to a guest (recipe, verified 2026-07-29)
+
+The guest lives on the host-private NAT bridge, so remote access is guest-service + host-forward:
+
+1. **In the macOS guest** (over ssh), use ONE mechanism, fully activated. The reliable form is Remote Management in a single kickstart call:
+   ```
+   sudo .../RemoteManagement/ARDAgent.app/Contents/Resources/kickstart \
+     -activate -configure -access -on \
+     -clientopts -setvnclegacy -vnclegacy yes -setvncpw -vncpw <8-char-pw> \
+     -allowAccessFor -allUsers -privs -all -restart -agent -menu
+   ```
+   ⚠ **Half-configured states authenticate but refuse the session.** Loading `com.apple.screensharing` while Remote Management is deactivated (or vice versa) produces an Apple-client error that names the wrong culprit: *"Screen Sharing is not permitted on <host>. Disable and re-enable Screen Sharing or Remote Management in System Settings"*. A raw-protocol client can still authenticate AND open a framebuffer in that state, so protocol-level tests pass while every Apple client fails. The remedy is exactly what the dialog says, done over ssh: `launchctl unload -w …screensharing.plist`, `kickstart -deactivate -configure -access -off`, `pkill screensharingd`, then the single activate call above.
+   Notes: `launchctl enable system/com.apple.screensharing` fails with "Could not find service" on this build; `load -w` is the plain-Screen-Sharing path if you deliberately want it instead of Remote Management. Apple clients negotiate `RSA-SRP` (auth type 33) and the guest logs `Authentication: SUCCEEDED :: User Name: … :: Type: RSA-SRP` on success, which is the definitive server-side confirmation.
+2. **On the host**: a gateway port-forward makes the guest's 5900 reachable from the whole tailnet without per-client tunnels: self-authorize the host's own key, then `ssh -N -g -L 0.0.0.0:5901:<guest-ip>:5900 <user>@localhost` (nohup'd).
+   ⚠⚠ **NEVER forward on host port 5900.** If the host has Screen Sharing enabled (our testbed does, from the pre-upgrade checklist), launchd already owns 5900 socket-activated. The `ssh -L` bind then fails with "Address already in use" **while the tunnel process keeps running**, so every symptom of success is present (process alive, port answers, real RFB banner) yet **every connection reaches the HOST's login window, not the guest**. This cost us an hour: guest credentials failed against the host's screensharingd, which reads exactly like broken guest auth, and we chased the (real, but irrelevant) provisioned-account identity bug. Diagnostics that would have caught it instantly: `sudo lsof -nP -iTCP:5900 -sTCP:LISTEN` showing `launchd` rather than `ssh`, or the guest's own logs showing NO auth attempts during a failed login. Always use a distinct host port and verify with `lsof` that the forward owns it.
+   ⚠ `-g` binds all interfaces, so the forward is also visible on the host's LAN; the VNC layer still requires the account or VNC password. ⚠ The forward pins the guest IP, which changes per boot under plain NAT; re-point it after a guest reboot (the proper fix is a vmnet DHCP reservation, macOS 26 API, once we move off plain `VZNATNetworkDeviceAttachment`).
+   Verified working: with the forward on 5901, both a provisioned account and a `sysadminctl`-created one authenticate successfully (RFB `SecurityResult` = 0) against the guest. The guest offers security types `[30, 33, 36, 2, 35]`, i.e. Apple DH/SRP **plus classic type 2**, so non-Apple VNC clients work with the legacy password once ARD's `-setvnclegacy` is set. (The host's screensharingd, by contrast, offered no type 2, which is itself a tell that you are talking to the wrong machine.)
+3. **SSH from any tailnet device**: `ssh -J <host-user>@<host> codeman@<guest-ip>` (jump through the host), after adding the connecting machine's key to the guest's `authorized_keys`.
+
+**Client-version incompatibility (macOS 27 servers vs older Screen Sharing clients)**: an older Mac's Screen Sharing client fails Apple's `RSA-SRP` handshake against macOS 27 servers, logging `Authentication: FAILED :: User Name: <user> :: Type: RSA-SRP` server-side, while a macOS 27 client authenticates against the same servers without issue. This was verified against BOTH a macOS 27 guest and a macOS 27 host with the operator's own account, so it is a client-side version skew, not configuration, and no server-side change fixes it. Same family as the documented "macOS 26 host cannot install a 27 guest" bug. Practical workaround: bypass Apple auth entirely with classic VNC auth (security type 2), which macOS offers only when Remote Management legacy VNC is enabled. Two ways to consume it: any third-party VNC client, or a browser via noVNC.
+
+**Browser-based access chain (zero client install, version-proof)**, all hosted on the Mac:
+```
+browser --HTTP/WS--> websockify (+ noVNC static files)
+                       --> type-2-only proxy   # rewrites the server's security-type list to [2]
+                         --> ssh -L forward     # loopback hop; see the Local Network note below
+                           --> guest:5900
+```
+Notes learned the hard way: (a) **never bind the forward on host port 5900** (see the launchd warning above); (b) a Python proxy cannot reach the guest subnet directly because macOS **Local Network privacy** denies headless CLI binaries, surfacing as `No route to host`, so point the proxy at a loopback `ssh -L` forward instead (Apple-signed `ssh` is unaffected); (c) noVNC needs `?resize=scale` or Scaling Mode → Local Scaling, otherwise a Retina host screen (2940x1912) is unusable in a browser window; (d) noVNC speaks security type 2 only, which is exactly why the proxy rewrite is needed.
+
+**Debugging technique that settled all of this**: a ~80-line Python RFB client (scratchpad `vnclogin.py`) that implements Apple DH auth (security type 30) and continues through `ClientInit`/`ServerInit`. It reports the server's `SecurityResult` plus the framebuffer size and desktop name, which separates "credentials rejected" from "authorized but session refused" without any GUI client. Pair it with `log stream --predicate 'process == "screensharingd"'` inside the guest, and drive a REAL Apple client headlessly from the host with `sudo launchctl asuser <uid> sudo -u <user> osascript -e 'tell application "Screen Sharing" to open location "vnc://user:pass@host:port"'`, verifying the result via `lsof -nP -iTCP -a -p <pid>` (an ESTABLISHED socket to the target) since `screencapture` fails on a lid-closed laptop ("could not create image from display"). Tailscale was never implicated: both the raw client and Apple's client work over the tailnet address once the guest service is fully activated.
+
+### Hard-won operational lessons (write these into any tooling)
+
+- **Silent serial is normal, not failure.** Debian's GRUB/kernel log to the graphics console; nothing attaches a getty to hvc0 by default. The reliable boot signal is the DHCP lease (or passive `tcpdump -i bridge100`), never the serial port and never a quick ping (BSD ping's first packet often dies to ARP latency; passive capture showed "dead" guests alive).
+- **DHCP lease entries carry truth**: `name=` shows the guest hostname, and the lease timestamps order events; stale entries linger, so compare timestamps before attributing a lease to a boot.
+- **Never boot a base image read-write.** Every RW boot mutates it (dhclient lease cache, journal, cloud-init state) and destroys experiment reproducibility, exactly why the production design only ever boots bases under overlays. Provision INTO the base once at base-build time, or provision per-case overlays with the seed, then detach the seed.
+- **A killed SSH client does not kill a remote `nohup`'d VM**, and the survivor holds the EFI variable store lock: "The EFI variable store is already in use" (`VZErrorDomain 50002`) means a zombie VM process, `pkill` it.
+- **EFI variable stores are per-VM state.** Fresh stores boot reliably; reuse across different VM instances is at minimum suspect on this beta (Apple's own guidance for cloned VMs is one store per VM). Cheap policy: one store per case, created with the overlay, deleted with it.
+- **Downloads from cloud.debian.org mirrors truncate silently**; always verify byte count against origin `Content-Length` and resume with `curl -C -`.
+- The remote host's default shell is zsh: `=` -prefixed words (`echo ===`) explode via zsh's `=cmd` expansion; keep separators zsh-safe in automation.
+
+### The 2-concurrent-macOS-VM cap: TESTED AND CONFIRMED on macOS 27 beta 4 (2026-07-29)
+
+We measured it, which as far as we can tell nobody had published for macOS 27. Method: `cp -c -R` the guest bundle (APFS clonefile, instant and **zero additional disk**), regenerate the machine identifier per clone (`VZMacMachineIdentifier()` written to `machine.id`; the hardware model is reused), then launch VMs until one is refused.
+
+Result: VM #1 (8 GB, GUI) and VM #2 (4 GB, headless) ran concurrently without complaint. VM #3 was refused **instantly** at `vm.start`:
+
+```
+VZErrorDomain Code=6 "The maximum supported number of active virtual machines has been reached."
+NSLocalizedFailure = "The number of virtual machines exceeds the limit."
+```
+
+**This is a licensing/kernel quota, not a resource limit**: the refusal came with **39% of system memory free** on a 16 GB host, and adding RAM or CPU cannot raise it. It matches the pre-27 behavior (`hv_apple_isa_vm_quota`), so nothing changed in 27 despite the framework's other additions. Linux guests are unaffected and are bounded only by host resources.
+
+Design consequences: macOS-guest capacity per host is **hard-capped at 2**, so a GUI-macOS-per-case product must schedule around it (queue, evict idle VMs, or scale across hosts) and surface it in the UI. Also relevant: the acknowledged slot-leak bug (a guest-initiated shutdown failing to release a slot, recoverable only by host reboot) is far more damaging under a cap of 2 than it sounds; we did not reproduce it on beta 4, but any scheduler should treat "slot appears used but nothing is running" as a real state.
+
+### Not yet tested
+- Cache layers (`LayerType.cache`), `.overlay(blockCount:)` disk growth, stack depth performance, VirtioFS + stack combination, `truncate`, ASIF disks for macOS guests (raw used so far; ASIF has the reclamation bug).
+- One more scripting lesson from this session: inner `ssh` calls inside a piped `sh -s` script MUST use `-n`, or they consume the remainder of the script from stdin and it silently never runs.
+
+### Session timeline (what was actually established, 2026-07-29)
+
+Linux path: base image download (with resume, mirrors truncate) → `vzboot` compiles against the beta SDK first try → EFI boot → NAT DHCP lease → cloud-init seed provisions a user with the host's SSH key → `ssh` into the guest works → DiskImageKit stack boots with an ASIF overlay taking all writes while the base stays SHA-identical. Later Linux boots became unreliable on an un-rebooted host (silent hangs, 0% CPU, no DHCP); a clean-baseline retest is still pending.
+
+macOS path: seed-CDN IPSW (matched to the host build) → `VZMacOSInstaller` restore, ~25 min, first try → first boot with `VZMacGuestProvisioningOptions` creates an admin account with Remote Login on, no interaction needed, SSH reachable ~140 s later → key bootstrap over a one-time password login → guest shutdown/relaunch clean (the slot-leak bug did not reproduce) → GUI access fought through a port collision, a client-version incompatibility, the rendering dependency, and a self-inflicted session kill, ending with a browser-based path plus a guest hardened to auto-login and never lock.
+
+**Lifecycle verified (stop → start), 2026-07-30**: an in-guest `shutdown -h now` fires `guestDidStop` and the runner app exits on its own; relaunching from the same bundle boots the guest in ~2 minutes straight into an auto-logged-in desktop, and the VM slot is released cleanly (an immediate restart works, so the slot-leak bug did not bite). Two operational notes: the guest takes a **new NAT lease on every boot**, so any port-forward must be re-pointed (or use a vmnet DHCP reservation), and a host reboot resets `pmset -a disablesleep`.
+
+⚠ **Provisioning does NOT skip the per-user first-login assistant.** `VZMacGuestProvisioningOptions` skips the initial Setup Assistant (account creation, region, Apple Account) so the machine is immediately reachable, but the first time anyone actually logs into a desktop, macOS still presents its per-user wizard (Apple Intelligence, Siri, privacy, appearance, Touch ID). The operator hit exactly this. For a GUI-first product this MUST be pre-suppressed during base-image creation by writing `com.apple.SetupAssistant` keys for every account that will log in, and into `/System/Library/User Template/English.lproj/Library/Preferences/` so accounts created later inherit it.
+
+⚠ **A partial key list is worse than none**, because the wizard simply shows the panes you missed and the operator has to click through them again after every fresh login (we hit this twice). The set that finally silenced macOS 27 beta 4: `DidSeeCloudSetup`, `DidSeeSiriSetup`, `DidSeePrivacy`, `DidSeeAppearanceSetup`, `DidSeeTouchIDSetup`, `DidSeeAvatarSetup`, `DidSeeScreenTime`, `DidSeeApplePaySetup`, `DidSeeSafariImport`, `DidSeeAccessibility`, **`DidSeeActivationLock`, `DidSeeAppStore`, `DidSeeLockdownMode`** (the three easy to miss), plus the Express-Settings flags **`SkipExpressSettingsUpdating`** and **`SkipFirstLoginOptimization`**, and the version markers `LastSeenCloudProductVersion` / `LastSeenBuddyBuildVersion` / `PreviousSystemVersion` / `PreviousBuildVersion` matching the guest build. Verify afterwards by reading the domain back and checking that no `DidSee*` key is still `0`. Note these keys change between macOS releases, so base-image creation should re-verify per OS version rather than trust a hardcoded list.
+
+## 9. Design implications for Codeman's VM subsystem
+
+0. **GUI is a first-class mode, and for macOS guests it is the whole point (owner decision, 2026-07-29).** The subsystem serves real desktops, not only headless SSH boxes. macOS guests are GUI-only in practice (nothing renders without an attached view). Linux guests are supported in BOTH modes: GUI when the case wants a desktop, headless-over-SSH when it wants a cheap agent sandbox. The costs of the GUI path are in §8 "Display rendering": VMs as GUI apps in a live session, a host that never locks, guests that auto-login with their first-login wizard pre-suppressed, and the macOS concurrency cap as a real capacity limit.
+1. **The macOS-specific liabilities are accepted costs, not reasons to avoid macOS guests**: provisioning is macOS-only and first-boot-only, ASIF space reclamation is broken for macOS guests on the beta (use RAW disks for macOS guests until fixed), and the 2-VM cap applies. Plan around each: RAW-backed macOS disks, provisioning baked into base-image creation, and capacity limits surfaced in the UI.
+2. **Base immutability is not just hygiene, it is load-bearing**: DiskImageKit's UUID invalidation plus our sha-stability proof make a read-only shared base per image-generation the core artifact. Bases are built once (seed attached), then only ever opened `.readOnly` under per-case overlays.
+3. **Seed ISOs are a base-build-time tool only.** Never attach a seed to a routine case boot (correlated with boot hangs on the beta, and semantically wrong anyway since cloud-init already ran).
+4. **Per-case files**: overlay ASIF + EFI variable store live and die together with the case.
+5. **Export = ship the layer chain** (base ref + overlay + manifest), not flatten; there is no flatten API. In-guest `dd` to a fresh image is the fallback for a true single-file export.
+6. **Health checking must be lease/API based**, not serial/ping based, and Codeman's `codeman-vm status` should read `/var/db/dhcpd_leases` (or use vmnet DHCP reservations for deterministic per-case IPs, a macOS 26 API).
+7. **Run `fstrim` periodically in Linux guests** (or mount with discard) so overlays stay sparse.
+8. **Entitlements plist stays minimal** (exactly `com.apple.security.virtualization`) to dodge the AMFI/watchdog traps.
+9. **Expect beta churn**: pin findings to build numbers (this doc: 26A5388g) and retest each beta; the framework binaries changed every beta so far.
+10. **A macOS guest is only "ready" when its desktop is ready**, which is a stricter bar than "the VM booted". Readiness means: VM app running with a live WindowServer connection, guest auto-logged-in (not at a login or lock screen), first-login assistant suppressed, and the guest's screen sharing serving a non-black framebuffer. Health checks should sample the framebuffer for non-black content, because every failure mode in this session (headless run, locked host, dead WindowServer, locked guest, setup wizard) presents as a perfectly healthy-looking process with a black or useless screen.
+10b. **Supervision must run as a root LaunchDaemon.** A user LaunchAgent cannot launch a GUI app into the Aqua session; its restarts fail silently (child dies instantly, empty log, supervisor reports success). Root + `launchctl asuser <uid> sudo -u <user> …` works and the launched process persists. This bit us on the first supervisor implementation and is easy to repeat.
+
+11. **Remote-access plumbing belongs in the helper CLI, not in ad-hoc shell**: a `codeman-vm` implementation should own port selection (never 5900), forward lifecycle across guest IP changes (or better, vmnet DHCP reservations for stable per-case IPs), and a documented browser path, because every failure in this session came from hand-rolled plumbing rather than from the Virtualization APIs themselves.
+12. **Never let control-plane connectivity depend on a GUI session** on a remote Mac host: prefer a Tailscale system service over the App Store app, and keep a LAN-adjacent peer able to relay as an out-of-band recovery path.
+
+## Sources
+
+Apple DocC JSON backend (diskimagekit, virtualization, vmnet trees; macOS 27 release notes) | WWDC26 session 224 https://developer.apple.com/videos/play/wwdc2026/224/ | eclecticlight.co ASIF/virtualization coverage | developer.apple.com/forums threads 839343 (CSIdentity bug), 830118 (cross-version restore), 830119 (VM-slot leak), 830383 (VM cap), 834822 + 831902 (USB entitlements), 822658 (vmnet loopback) | openai/tart issues 1261/1263/1268/1269/1285 | Spooky-Labs provisioning design doc | VirtualBuddy 2.2 release notes | lima-vm discussions | our own test transcripts on the testbed (`~/vm-lab/*.log`, this repo's session)

docs/web-tabs-fixes-plan.md

@@ -0,0 +1,190 @@
+# Web tabs: two fixes (planned + implemented 2026-07-28)
+
+Both found against the saved dashboard
+`https://<your-host>.<your-tailnet>.ts.net:4000` (Bio-Hacking-Dashboard).
+Kept because the root-cause analysis of the second one is not obvious from the
+resulting diff.
+
+Status: **both implemented and verified end-to-end.** The one deliberate
+non-change is recorded at the bottom.
+
+---
+
+## Bug 1: saved URLs could not be deleted from the Run dropdown
+
+### What happened
+
+The "Web / URL" section of the Run dropdown listed every saved dashboard as a
+single clickable row whose only action was "open". Deleting required opening the
+dashboard as a tab, clicking the tab's gear, then Delete in the modal, so a URL
+you no longer wanted open at all could not be removed without first opening it.
+
+### What shipped
+
+- `renderWebviewMenuItems()` (`src/web/public/webview-tabs.js`) now renders each
+  saved URL as a `.run-mode-row--web` flex row: the open button, a gear
+  (`showWebviewModal`), and an `x` (`deleteWebviewById`). Nested buttons are
+  invalid HTML, hence the wrapper rather than a button inside a button.
+- `deleteWebview()` split into the modal entry point, the new row entry point
+  `deleteWebviewById(id)`, and the shared `_confirmAndDeleteWebview(id)`.
+- Both side buttons call `event.stopPropagation()` so the click does not also
+  open the dashboard.
+- The dropdown's outside-click handler (`session-ui.js`) closes when the click
+  target is not inside `#runModeMenu`, and the row is gone by the time the delete
+  resolves, so `deleteWebviewById` re-asserts `.active` on the menu. Verified in a
+  browser: deleting one of several URLs leaves you looking at the rest of the list.
+- CSS in `styles.css` (`.run-mode-row--web`, `.run-mode-row-btn`) plus a larger
+  touch target in `mobile.css`. The side buttons are permanently visible rather
+  than hover-revealed, because this menu is used on touch.
+
+No server change: `DELETE /api/webviews/:id` already existed, owner-scoped, and
+already revoked the capability and broadcast `WebviewChanged`.
+
+---
+
+## Bug 2: images did not load in a proxied dashboard
+
+### Reproduction (before the fix)
+
+```
+CAP=<from POST /api/webviews/<id>/open>
+# A) upstream direct                       -> 200 image/jpeg 118150
+curl -sk "https://<your-host>.<your-tailnet>.ts.net:4000/api/hero?slug=120-minutes-in-nature"
+# B) through the proxy prefix              -> 200 image/jpeg 118150
+curl -sk "https://localhost:3000/webview/$CAP/api/hero?slug=120-minutes-in-nature"
+# C) what the browser ACTUALLY requested   -> 404 {"errorCode":"NOT_FOUND"}
+curl -sk -H "Referer: https://localhost:3000/webview/$CAP/" \
+     "https://localhost:3000/api/hero?slug=120-minutes-in-nature"
+# D) same shape but NOT under /api         -> 200 (referer fallback rescues it)
+curl -sk -H "Referer: https://localhost:3000/webview/$CAP/" "https://localhost:3000/styles.css"
+```
+
+The proxy itself was fine (B). The failure was entirely about which URL the
+browser ended up requesting (C).
+
+### Root cause
+
+The dashboard builds its image markup at runtime with root-absolute URLs:
+`c.innerHTML = '<img class="thumb" src="/api/hero?slug=...">'`, `img.src =
+slideSrc(...)` returning `/api/slide?owner=...`, `/api/story`, `/api/video`, and a
+nested `<iframe src="/api/preview?slug=...">`.
+
+All three rewrite layers missed that shape:
+
+1. `<base href="/webview/<cap>/">` only affects **relative** URLs. A root-absolute
+   `/api/hero` ignores the base path and resolves against Codeman's origin.
+2. `rewriteHtml()` only runs over the **initial HTML document**. This markup is
+   created later by page script. (The static header `<img src="/api/logo">` DID
+   work, having been rewritten at proxy time, which is why only the
+   runtime-injected images were broken.)
+3. `runtimeUrlShim()` patched only `fetch`, `XMLHttpRequest.open`, `WebSocket` and
+   `EventSource`, so the dashboard's **data** loaded while its **pictures** did
+   not.
+
+The safety net was fenced off from `/api` in two places, both deliberate:
+`server.ts`'s not-found handler returns the API-envelope 404 before reaching
+`tryWebviewRefererFallback`, and `middleware/auth.ts` refuses the Referer-form
+auth exemption for `/api/`, `/ws/`, `/q/`.
+
+### What shipped
+
+`runtimeUrlShim()` in `src/web/webview-proxy.ts` now also covers the DOM sinks, so
+a root-absolute `/api/...` request is never emitted in the first place and neither
+security fence had to move:
+
+- `innerHTML` / `outerHTML` / `insertAdjacentHTML` (and `ShadowRoot.innerHTML`),
+- `setAttribute` / `setAttributeNS`,
+- the `src`/`srcset`/`href`/`poster`/`data`/`action` property setters on img,
+  source, media, video poster, script, iframe, embed, track, link, anchor, area,
+  object and form,
+- a `MutationObserver` as a last net for any sink not patched above (it costs one
+  wasted 404 per node, since the browser starts fetching on insert, so it is a net
+  and not the mechanism).
+
+Two details that mattered:
+
+- Every rewrite routes through the existing idempotent `rw()` rather than a blind
+  prefix concat. The first draft used the server-side regex shape and
+  double-prefixed markup that was already proxied (a page re-injecting its own
+  `outerHTML`); the jsdom test caught it.
+- Everything stays inside `try`/`catch` and is marked `__cmrw`, so a double
+  injection cannot wrap an already-wrapped setter, and nothing can throw into a
+  page we do not control.
+
+### Verification
+
+- `test/webview-proxy.test.ts` gained a jsdom `runtimeUrlShim DOM sinks` block:
+  innerHTML, insertAdjacentHTML, property setters, setAttribute, srcset candidate
+  lists, the MutationObserver net via an unpatched sink
+  (`createContextualFragment`), idempotence, re-injected markup, empty `src`, and
+  the pass-throughs (relative, cross-origin, `#hash`, `data:`). 73 tests pass.
+- End-to-end in a real browser against an isolated instance
+  (`CODEMAN_INSTANCE=wvtest`, port 3151), with prod's old build as the negative
+  control:
+
+  | | before (prod, old build) | after (fixed) |
+  | --- | --- | --- |
+  | images found | 693 | 693 |
+  | src under the proxy prefix | 0 | 693 |
+  | in-viewport images decoded | 0 / 23 | 23 / 23 |
+  | sample src | `/api/hero?slug=...` | `/webview/<cap>/api/hero?slug=...` |
+
+  (The dashboard marks thumbs `loading="lazy"`, so only in-viewport images are
+  ever fetched. All 27 proxied image responses returned 200.)
+
+---
+
+## Follow-up (same day): the `/api` referer fallback, done safely
+
+Originally deferred, then implemented on request. Both gates had to move, and the
+auth one is the security-sensitive half: auth runs in `onRequest`, before routing,
+so it cannot tell a real Codeman API route from a 404, and simply dropping the
+`/api` fence would let a page holding a capability forge a `Referer` and reach
+Codeman's **real** API unauthenticated.
+
+What shipped:
+
+- `server.ts`: `tryWebviewRefererFallback` is tried **before** the API-shaped 404.
+  Reaching that handler already proves no route matched, and the relay declines
+  unless the `Referer` carries a live capability, so unknown `/api` paths still
+  get the envelope.
+- `middleware/auth.ts`: the `/api/` prefix refusal is replaced by
+  `matchesRegisteredRoute()`, which refuses the exemption for any path that
+  resolves to a real route. `/ws/` and `/q/` stay refused by prefix.
+
+Two findings that decided the implementation, both established by probing Fastify
+rather than by reading its docs:
+
+- **`hasRoute()` is the wrong tool and would have been a hole.** It matches the
+  registered PATTERN literally, so `hasRoute({url: '/api/sessions/abc'})` returns
+  false against a registered `/api/sessions/:id` and would have handed out an
+  exemption on a live, session-scoped API route. `findRoute()` performs the real
+  radix-tree lookup and is what the fence uses.
+- **`@fastify/static` is mounted at `/`, so it registers a root catch-all that
+  matches every path.** A match on it means "heading for the 404 handler", not
+  "real route", and it is distinguishable because a root catch-all is the only
+  route whose `*` param comes back equal to the whole request path. Without that
+  carve-out the fence would have refused every referer-form request and broken the
+  rescue that already worked.
+
+The fence fails closed, and `test/webview-auth-exemption.test.ts` pins both edges
+(a concrete URL onto a parametric API route stays 401; the dashboard's own
+`/api/...` namespace is served).
+
+### And the CSS gap, which the fallback could NOT close
+
+Testing the fallback against a purpose-built upstream showed the runtime-injected
+stylesheet case is unreachable by any relay: a `<style>` element has no URL of its
+own, so Chromium sends an **empty `Referer`** with the image request it triggers
+and there is nothing to key on. Measured directly:
+
+| sink | Referer the browser sends | fixed by |
+| --- | --- | --- |
+| `url()` in a proxied `.css` | the stylesheet's proxied URL | the referer relay |
+| `url()` in a runtime `<style>` | *empty* | `rwCss()` in the shim |
+
+So the shim also rewrites `url()` inside `<style>` blocks, both when they arrive as
+markup and when a `<style>` node is inserted (via the existing MutationObserver).
+
+The only gap left is self-navigation via `location.href = '/x'`, which cannot be
+patched because `Location.href` is unforgeable.

docs/web-tabs.md

@@ -0,0 +1,155 @@
+# Web Tabs (dashboards as Codeman tabs)
+
+Open any dashboard you run, Grafana, Uptime Kuma, Portainer, a status page on port
+4000, as a tab beside your Claude/Codex/Antigravity sessions. Codeman becomes one mission
+control instead of Codeman plus a pile of browser tabs.
+
+## Using it
+
+1. Click the chevron next to **Run** to expand the dropdown.
+2. Under **Web / URL**, pick **Add dashboard...**
+3. Give it a name and a URL, optionally hit **Test**, then **Save**.
+
+The dashboard opens as a tab immediately, and appears in the Run dropdown from then
+on. Web tabs sit in the same strip as session tabs, continue the same `Alt+1..9`
+numbering, and carry a globe icon so they never read as a running agent.
+
+Closing a tab (the `x`) only closes it. The saved dashboard stays in the dropdown.
+To delete it for good, use the `x` on its **dropdown row** (the tab's own `x` is
+close, not delete). Each dropdown row also has a gear for editing, so a saved URL
+can be changed or removed without opening it first.
+
+Switching tabs does **not** reload a dashboard. Frames stay alive in the background,
+so a dashboard that took a while to authenticate is still there when you come back.
+Past six live frames the least-recently-viewed one is dropped to bound memory
+(`CODEMAN_MAX_LIVE_WEBVIEW_FRAMES`).
+
+## Why dashboards are proxied
+
+A plain `<iframe src="http://your-box:4000">` does not work in the setup Codeman
+actually ships in, for three separate reasons:
+
+| Blocker             | What happens                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| **Mixed content**   | Production serves HTTPS (behind `tailscale serve`). Browsers hard-block `http://` iframes on an HTTPS page, with no override, and none at all on iOS Safari. |
+| **Framing refusal** | Grafana, Portainer, Home Assistant and many others send `X-Frame-Options: DENY` or `frame-ancestors 'none'`. |
+| **Codeman's CSP**   | `default-src 'self'` means `frame-src` falls back to `'self'`, so a cross-origin iframe is blocked before it starts. |
+
+Serving the dashboard **through Codeman's own origin** dissolves all three. So by
+default a web tab loads `/webview/<capability>/` on Codeman, and Codeman relays to
+the dashboard: stripping the framing refusal, rewriting redirects, cookies and
+root-absolute URLs, and relaying WebSockets so live panels actually update.
+
+A useful consequence: the dashboard is fetched **from the Codeman server**, so a
+tailnet-only or `localhost`-only dashboard works from any device that can reach
+Codeman, including a phone that is not on the tailnet.
+
+`direct` mode (a plain cross-origin iframe) still exists and is cheaper, but it only
+works for an HTTPS dashboard that permits framing. The **Test** button probes from
+the server and tells you which mode applies.
+
+## The sandbox, and when to turn it off
+
+Because a proxied dashboard is served from Codeman's own address, it is
+*same-origin with Codeman* as far as the browser is concerned. Left unchecked, its
+JavaScript could read the Codeman page and call the API that spawns agents.
+
+So the iframe is sandboxed **without** `allow-same-origin` by default. The page runs
+in an opaque origin: it cannot touch Codeman, and it gets no cookies or
+`localStorage` of its own.
+
+Unchecking **Open sandboxed** grants `allow-same-origin`. Do that only for a
+dashboard you fully trust, and only if you need it, which in practice means a
+dashboard with its own login that stores a session in a cookie or `localStorage`.
+
+Even in trusted mode, Codeman never forwards its own credentials upstream: the
+`Authorization` header and the `codeman_session` cookie are stripped on the way out,
+so `CODEMAN_PASSWORD` cannot leak into a dashboard.
+
+## How the proxy authenticates
+
+A sandboxed iframe is opaque-origin, so every request it makes is cross-site: the
+`SameSite=lax` session cookie is not sent, and writes and WebSocket upgrades arrive
+with `Origin: null`. Cookie auth cannot work.
+
+Instead, opening a dashboard mints a **capability**: 192 bits of entropy in the URL
+path, held in memory only, with a rolling 12-hour TTL, bound to the user who minted
+it, and granting exactly one thing, relaying bytes to that one saved URL. Editing or
+deleting a dashboard revokes it, and a server restart invalidates every outstanding
+capability (tabs re-mint transparently on next click).
+
+## Limits and env vars
+
+| Variable                             | Default | Meaning                                    |
+| ------------------------------------ | ------- | ------------------------------------------ |
+| `CODEMAN_MAX_WEBVIEWS`               | 50      | Saved dashboards per owner                 |
+| `CODEMAN_MAX_LIVE_WEBVIEW_FRAMES`    | 6       | Iframes kept mounted at once               |
+| `CODEMAN_WEBVIEW_CAPABILITY_TTL_MS`  | 12h     | Rolling capability lifetime                |
+| `CODEMAN_WEBVIEW_TIMEOUT_MS`         | 30000   | Upstream request timeout                   |
+| `CODEMAN_WEBVIEW_PROBE_TIMEOUT_MS`   | 8000    | Timeout for the Test button                |
+| `CODEMAN_MAX_WEBVIEW_HTML_BYTES`     | 8MB     | Largest HTML document rewritten            |
+| `CODEMAN_MAX_WEBVIEW_SOCKETS`        | 8       | Concurrent proxied WebSockets per dashboard |
+
+Saved dashboards live in `~/.codeman/webviews.json`. Which tabs you have open is
+per-device (`localStorage`), since that is workspace layout rather than config.
+
+## How a dashboard's own API calls keep working
+
+Worth knowing, because it is where this feature does its least obvious work. Three
+layers cooperate so a dashboard talking to its own backend just works:
+
+1. `<base href>` handles relative URLs in the markup.
+2. Attribute rewriting handles root-absolute `src`/`href`/`action` in the page the
+   proxy serves.
+3. A small injected script rebases URLs built at **runtime**, which the first two
+   cannot see: `fetch('/api/data')` and `new WebSocket('/live')`, but equally
+   `card.innerHTML = '<img src="/api/hero">'`, `img.src = '/api/slide'`, and
+   `url(/img.png)` inside a `<style>` the page injects. That second group is why
+   images are covered too. A dashboard that renders its thumbnails from script
+   would otherwise show all its data and none of its pictures, because `<base>`
+   does not apply to root-absolute URLs and the attribute rewriting only ever saw
+   the initial document.
+4. As a last resort, a request that still lands on Codeman's own root is relayed
+   using its `Referer` to identify the dashboard. This only fires for a request
+   that already missed every Codeman route, and never for one that resolves to a
+   real route, which is what keeps it from being an authentication bypass.
+
+On top of that, the proxy answers those requests with CORS headers. That sounds
+wrong for same-host requests, but a sandboxed iframe has an *opaque* origin, so the
+browser treats every one of its `fetch`/XHR calls as cross-origin even though the
+URL is on Codeman itself. Without those headers, a dashboard renders perfectly and
+then every API call fails, which looks like the dashboard being broken.
+
+## Known limits
+
+- **Exotic loaders.** The layers above cover normal `fetch`/XHR/WebSocket/
+  EventSource, normal markup, the DOM sinks a page uses to build markup at runtime,
+  and `url()` inside stylesheets. Something that constructs requests by an unusual
+  route can still slip through. Symptom: the page renders but a panel stays empty.
+- **Root-absolute `location` navigation.** A dashboard that navigates itself with
+  `location.href = '/login'` escapes the prefix, because `Location.href` is
+  unforgeable and cannot be patched the way the other sinks are. A relative
+  `location.href = 'login'` is fine (`<base>` covers it).
+- **Cross-origin redirects are not followed.** If a dashboard bounces to a different
+  host (an external SSO provider, say), the proxy hands the redirect back unchanged
+  rather than relaying it, because relaying would make this an open proxy. Use
+  **Open in new tab** for those.
+- **Login-protected dashboards need trusted mode**, since a sandboxed frame has no
+  cookie jar. A server-side per-dashboard cookie jar would lift this and is the
+  natural next step if it becomes annoying.
+- **Not a security boundary.** The proxy reaches whatever the Codeman server can
+  reach. That is not an escalation for someone who already commands
+  `--dangerously-skip-permissions` agents, but in multi-user mode it does mean a
+  non-admin user's dashboard is fetched from the server's network position.
+
+## Where the code lives
+
+| Concern                  | File                                    |
+| ------------------------ | --------------------------------------- |
+| Pure rewrite helpers     | `src/web/webview-proxy.ts`              |
+| Routes + proxy + sockets | `src/web/routes/webview-routes.ts`      |
+| Capability tokens        | `src/webview-capabilities.ts`           |
+| Persistence              | `src/webview-store.ts`                  |
+| Limits                   | `src/config/webview-limits.ts`          |
+| Frontend                 | `src/web/public/webview-tabs.js`        |
+| Auth exemption           | `src/web/middleware/auth.ts`             |

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.7.1",
+  "version": "1.12.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.7.1",
+      "version": "1.12.0",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -34,6 +34,7 @@
         "qrcode": "^1.5.4",
         "uuid": "^14.0.0",
         "web-push": "^3.6.7",
+        "ws": "^8.21.0",
         "zod": "^4.3.6"
       },
       "bin": {
@@ -12332,7 +12333,7 @@
       }
     },
     "packages/xterm-zerolag-input": {
-      "version": "0.1.4",
+      "version": "0.1.8",
       "license": "MIT",
       "devDependencies": {
         "jsdom": "^24.1.3",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.7.1",
+  "version": "1.12.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",
@@ -22,6 +22,7 @@
     "test:coverage": "vitest run --config config/vitest.config.ts --coverage",
     "test:ci": "vitest run --config config/vitest.ci.config.ts",
     "check:frontend-syntax": "node scripts/check-frontend-syntax.mjs",
+    "fix:node-pty": "node scripts/fix-node-pty.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint --config config/eslint.config.js 'src/**/*.ts'",
     "lint:fix": "eslint --config config/eslint.config.js 'src/**/*.ts' --fix",
@@ -32,25 +33,45 @@
     "changeset": "changeset",
     "version-packages": "changeset version && npm install --package-lock-only && node scripts/check-lockfile-sync.mjs",
     "check:lockfile": "node scripts/check-lockfile-sync.mjs",
-    "knip": "npx --yes knip@latest",
+    "knip": "npx --yes knip@latest --config config/knip.json",
     "release": "changeset publish"
   },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "tabWidth": 2,
+    "printWidth": 120,
+    "trailingComma": "es5",
+    "endOfLine": "lf"
+  },
   "workspaces": [
     ".",
     "packages/*"
   ],
   "keywords": [
-    "claude",
     "claude-code",
+    "claude-ai",
+    "claude",
     "anthropic",
-    "ai-agent",
-    "automation",
+    "opencode",
+    "codex",
+    "antigravity",
+    "gemini-cli",
+    "ai-agents",
+    "agent",
     "session-manager",
+    "self-hosted",
+    "developer-tools",
+    "tmux",
     "terminal",
+    "xterm",
+    "docker",
+    "mosh",
+    "local-echo",
+    "web-dashboard",
     "cli",
     "llm",
-    "autonomous-agent",
-    "ralph-loop"
+    "automation"
   ],
   "author": "arkon",
   "license": "MIT",
@@ -75,6 +96,7 @@
     "qrcode": "^1.5.4",
     "uuid": "^14.0.0",
     "web-push": "^3.6.7",
+    "ws": "^8.21.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -136,6 +158,7 @@
   "files": [
     "dist",
     "scripts/postinstall.js",
+    "scripts/fix-node-pty.mjs",
     "LICENSE",
     "README.md"
   ]

packages/xterm-zerolag-input/CHANGELOG.md

@@ -1,5 +1,69 @@
 # xterm-zerolag-input
 
+## 0.1.8
+
+### Patch Changes
+
+- **Fixed: sessions failed to start on macOS with `Error: posix_spawnp failed.`** (issues #6 and #204)
+
+  `node-pty@1.1.0` publishes its macOS prebuilt helper as `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit. macOS launches every PTY through that helper, so a stock install failed on every session start. The bug is macOS-only: `spawn-helper` is a mac-only gyp target and node-pty ships no Linux prebuild, so Linux always compiles a correctly-permissioned helper from source.
+
+  The previous fix chmodded only `build/Release/spawn-helper`, which on macOS does not exist (the prebuild is used, so node-gyp never runs), and it derived that path from `require.resolve('node-pty')`, landing on `<pkg>/lib/build/Release/...`. It was a no-op on every platform.
+  - New `scripts/fix-node-pty.mjs` (also `npm run fix:node-pty`) chmods every `spawn-helper` it finds, in `build/Release`, `build/Debug` and each `prebuilds/*/`, then verifies the result by actually opening a PTY. A `require()` alone passes on a broken install, because the helper is only touched at spawn time.
+  - `postinstall` no longer force-rebuilds node-pty from source on Node 22+. That step needed Xcode command line tools, cost 30-120s on every install, and deleted the `prebuilds/` tree before compiling, so a Mac without a compiler was left with no working binary at all. A rebuild now happens only when the chmod plus spawn probe still fails, and the prebuilds tree is backed up and restored around it.
+  - New `spawnPtyWithHelperRepair()` (`src/utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts`, so an install that is already broken repairs itself on the first failed spawn and retries in-process instead of showing a dead session. Unrelated spawn errors are rethrown untouched; a second failure carries the `npm run fix:node-pty` hint.
+  - `scripts/fix-node-pty.mjs` is now in the published `files` list, so global npm installs get the repair too.
+  - Direct-PTY Claude spawns use the resolved absolute binary path (new `getClaudeBinaryPath()`) instead of the bare name `claude`, so a CLI installed outside the server's PATH still launches.
+
+  Verified end to end on macOS 26.4 arm64: a stock `npm i` reproduces `posix_spawnp failed.`, and after the fix the same install spawns a PTY successfully with the prebuilds preserved.
+
+  **Added: phone home screen (session overview)**
+
+  Under 430px the "C" logo now opens a session overview (current sessions, past sessions, spaces) instead of the welcome overlay: on a small screen "which session needs me" beats "how do I start one". Rows resume a session in place, and "New session here" goes through the normal quick-start path so remote and Docker cases keep their routing. Per-device setting `mobileOverviewEnabled` (phones only, default ON) in App Settings. Tablet and desktop are unchanged.
+
+  **Added: guided Tailscale setup in `install.sh`**
+
+  The network-access prompt is now 3-way: Tailscale, LAN, or local-only. The Tailscale path binds loopback and walks through installing Tailscale, logging in, the operator grant, the tailnet HTTPS-certificates toggle, and `tailscale serve --bg <port>`, then verifies the result end to end with curl. That gives HTTPS on a real certificate with no app password and no `0.0.0.0` bind, which is also what PWA install and web push need. `install.sh tailscale` retrofits it onto an existing install, and `CODEMAN_TAILSCALE=1` presets the choice. Serve state is detected from `tailscale serve status --json`; the installer never runs `tailscale serve reset` and never touches serve mappings other than 443 to Codeman's port. README and `docs/security-architecture.md` updated to match.
+
+  **Docs**: replaced a real tailnet hostname with placeholders in `docs/web-tabs-fixes-plan.md`.
+
+  **xterm-zerolag-input**: npm description and keywords only, no code change.
+
+## 0.1.7
+
+### Patch Changes
+
+- Fix a latent bug where a partial settings PUT silently reset live service state, and trim the `xterm-zerolag-input` README callout.
+  - **`PUT /api/settings` no longer resets watchers on a partial body.** The three `toggleService` calls (subagent watcher, workflow-run watcher, image watcher) read the raw request body with `??` defaults, so every key a caller omitted was treated as "apply the default". A body of just `{statusLineTelemetry:true}` would START the subagent watcher and STOP the workflow and image watchers, undoing the persisted config. They now resolve from `merged` (persisted settings + incoming), the same convention the `tmuxHistoryLimit` branch in that handler already used, so any PUT reconciles services to the effective stored state. Nothing triggered this in practice because every shipped client sends a full settings payload rebuilt from the DOM, but it was a trap for the next partial-update caller.
+  - **Regression test**: `test/routes/system-routes-settings-partial-put.test.ts` (4 cases) pins both directions, omitted keys preserve state and explicit keys still take effect. Verified to fail against the pre-fix handler.
+  - **CLAUDE.md** records the rule under "Adding Features → App setting": anything acting on a setting in that handler must resolve from `merged`, never the request body.
+  - **`xterm-zerolag-input` README**: removed the links line (getcodeman.com / install one-liner / star link) from the Codeman callout above the demo GIF. The callout keeps its links in the heading and body.
+
+## 0.1.6
+
+### Patch Changes
+
+- Plan-usage chip now defaults ON on desktop, plus the reworked `xterm-zerolag-input` README.
+  - **Plan-usage chip defaults ON (desktop).** The `showPlanUsageLimits` chip (live 5-hour and weekly plan usage from the Claude statusline) used to be opt-in and default OFF, so most users never saw it. Desktop now defaults ON; handhelds still default OFF so the phone header stays minimal and the `mobile-header-buttons-policy` guard keeps passing. Devices with an explicitly stored preference keep whatever they chose, so nobody's OFF gets overridden.
+  - **One resolver behind the chip.** Added `planUsageChipEnabled()` in settings-ui.js and routed all three call sites through it: the App Settings checkbox, the chip's visibility, and the create-time `statusLineTelemetry` flag in session-ui.js. Those three had independent `?? false` / `=== true` defaults, and a chip revealed without the telemetry flag renders `—` forever, so a default flip on one site alone would have shipped a permanently empty chip.
+  - **Cron button comment corrected.** The App Settings comment claimed "Cron button defaults ON" while the code, the template (`btn-cron--hidden`) and the CSS all default it OFF. Verified against a fresh browser profile: the button is hidden and its checkbox unchecked out of the box. Comment now matches, and states why the two halves stay consistent.
+  - **Docs.** CLAUDE.md, `docs/architecture-invariants.md` and `docs/usage-limits-display-plan.md` updated for the new default and the single-resolver rule; the stale `styles.css` comment claiming the server strips the chip's hidden class at render was corrected (display is per-device, so the client reveals it).
+  - **`xterm-zerolag-input` README rework** (0.1.5 shipped the content; this republishes with the graphic and promo changes): replaced the misaligned 8-line keystroke-flow diagram with a two-line stock-vs-zerolag contrast, added a Codeman callout above the demo GIF with links to getcodeman.com and the repo, and rewrote the Origin section so it argues the extraction story instead of repeating the promo.
+
+## 0.1.5
+
+### Patch Changes
+
+- Rewrite the `xterm-zerolag-input` package README as a value-first document and correct the drift that had accumulated against the source.
+  - Added the side-by-side phone demo GIF (`docs/images/zerolag-demo-20260728.gif`) as the hero image, referenced by absolute raw URL so it renders on npmjs.com as well as GitHub. The two-phone comparison shows 0ms local echo next to a 600ms-2.7s server echo on the same session.
+  - New "Why this one" comparison table, an explicit list of target use cases (SSH web clients, cloud IDEs, mobile terminals, container consoles), and a bundle-size badge (6.1 kB gzipped, measured from the ESM build).
+  - Corrected the test-count badge from 78 to the actual 175 tests across 5 files, in both the package README and the Published Packages section of the root README.
+  - Removed the stale "Unicode/emoji rendered at single-cell width" limitation. CJK, fullwidth forms and emoji have had double-width rendering and visual-column positioning since the wide-character fix; the honest remaining caveat (per-code-point width summing over-counts ZWJ grapheme clusters) replaces it.
+  - Documented the previously undocumented public `setPrompt()` method for switching prompt strategies at runtime, and the new "Wide characters (CJK, emoji)" integration section covering the optional `Unicode11Addon` path and the built-in range-table fallback.
+  - Documented `backgroundColor: 'transparent'`, corrected the `foregroundColor` default, and updated the grid-alignment math to reflect visual-column positioning rather than character index.
+
+  No source changes, docs only.
+
 ## 0.1.4
 
 ### Patch Changes

packages/xterm-zerolag-input/README.md

@@ -1,45 +1,64 @@
 <p align="center">
   <h1 align="center">xterm-zerolag-input</h1>
   <p align="center">
-    Instant keystroke feedback overlay for <a href="https://xtermjs.org/">xterm.js</a><br>
-    <em>Eliminates perceived input latency over high-RTT connections</em>
+    <strong>Make typing feel instant in <a href="https://xtermjs.org/">xterm.js</a>, no matter how far away the server is.</strong><br>
+    <em>A pixel-perfect local echo overlay. Client-side only. Zero dependencies.</em>
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/xterm-zerolag-input"><img src="https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e" alt="npm"></a>
     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="MIT"></a>
-    <img src="https://img.shields.io/badge/Dependencies-0-22c55e?style=flat-square" alt="Zero deps">
-    <img src="https://img.shields.io/badge/Tests-78-22c55e?style=flat-square" alt="78 tests">
-    <img src="https://img.shields.io/badge/xterm.js-v5%20%7C%20v7+-3b82f6?style=flat-square" alt="xterm.js">
+    <img src="https://img.shields.io/badge/Dependencies-0-22c55e?style=flat-square" alt="Zero dependencies">
+    <img src="https://img.shields.io/badge/Size-6.1%20kB%20gzip-22c55e?style=flat-square" alt="6.1 kB gzipped">
+    <img src="https://img.shields.io/badge/Tests-175-22c55e?style=flat-square" alt="175 tests">
+    <img src="https://img.shields.io/badge/xterm.js-v5%20%7C%20v7+-3b82f6?style=flat-square" alt="xterm.js v5 and v7+">
   </p>
 </p>
 
+> ### Made for [**Codeman**](https://getcodeman.com)
+>
+> This overlay is the local echo engine of [**Codeman**](https://github.com/Ark0N/Codeman), mission control for AI coding agents: run and monitor a dozen Claude Code, Codex, OpenCode and Antigravity sessions at once, watch their subagents work in live floating windows, let them run autonomously overnight, and drive all of it from your phone.
+>
+> That last part is why this library exists. The demo below is a real Codeman session on two phones.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/zerolag-demo-20260728.gif" alt="Side-by-side phones typing into the same remote session: with zerolag the text appears at 0ms, without it every keystroke waits 600ms to 2.7s for the server echo" width="900">
+</p>
+
+<p align="center">
+  <em>Two phones, the same remote session, the same slow link.<br>
+  Left: the zerolag overlay paints every keystroke at <strong>0ms</strong>. Right: stock xterm.js waits <strong>600ms to 2.7s</strong> for the server to echo it back.</em>
+</p>
+
 ---
 
-## The Problem
+## The 30-second version
 
-When using xterm.js over a remote connection (SSH web clients, cloud IDEs, mobile terminals), every keystroke takes a full round-trip to the server before appearing on screen. At 100-500ms RTT, typing feels sluggish and unresponsive. Users type blind, make mistakes they can't see, and the experience feels broken.
-
-## The Solution
-
-`xterm-zerolag-input` renders typed characters **immediately** as a pixel-perfect DOM overlay positioned on the terminal's character grid. The overlay covers the terminal canvas at the prompt location, showing characters instantly while the server echo travels back. Once the server responds, the overlay seamlessly disappears and the real terminal text takes over.
+Over a remote connection, xterm.js shows you a character only after it has flown to the server and back. At 100-500ms RTT that reads as broken: you type ahead of the screen, you cannot see your typos, and you start pecking one key at a time to stay in sync.
 
 ```
-Keystroke Flow:
-                                    ┌─── DOM overlay (instant, 0ms)
-User types 'h' ─── onData('h') ───┤
-                                    └─── Your app sends to PTY ──→ Server
-                                                                      │
-Server echoes 'h' ←──────────────────────────────────────────────────┘
-         │                                                  (200-500ms RTT)
-         └──→ terminal.write('h') ──→ overlay.clear()
-              (server output replaces overlay — seamless transition)
+  stock xterm.js   keypress ─────── 300 ms ───────→ character appears
+  with zerolag     keypress → character appears  ·  echo lands later, unseen
 ```
 
-**No changes to your backend needed.** The addon is purely client-side.
+Same keystroke, same link. The only difference is who you wait for: the server, or nobody.
 
-## Origin
+`xterm-zerolag-input` paints your keystrokes **immediately**, as an absolutely-positioned DOM overlay locked to the terminal's character grid. The byte still goes to the PTY exactly as before, so nothing about your shell changes. When the server echo lands 300ms later, the overlay clears and the real terminal text takes over on the same pixels. The handoff is invisible.
 
-This library was extracted from [Codeman](https://github.com/Ark0N/Codeman), mission control for AI coding agents — multi-session management, real-time agent visualization, autonomous respawn loops, and a mobile-first web UI for Claude Code, OpenCode, and Codex. The local echo system was built to make mobile and remote access feel instant, then battle-tested across thousands of hours of real usage. After 3 deep code audits, it was extracted into this standalone library with 78 tests covering every state transition.
+**No backend changes. No protocol. No server support.** It is a client-side addon that never touches the wire.
+
+## Why this one
+
+| | |
+|---|---|
+| **Survives full-screen TUIs** | Ink, blessed, and friends repaint the whole screen constantly. The overlay is a separate DOM layer they cannot reach, so it does not get clobbered. |
+| **Pixel-matched to the canvas** | Each character is its own absolutely-positioned `<span>` at exact cell coordinates, so it does not drift out of the grid like normal DOM text flow. |
+| **Wide characters included** | CJK, fullwidth forms and emoji render double-width and position by visual column, using the terminal's Unicode addon when one is loaded. |
+| **Backspace that actually works** | A three-layer cascade (unsent, in-flight, already on screen) tells you exactly what to forward to the PTY, so editing works through any mix of typed, flushed and tab-completed text. |
+| **You keep control of input** | The addon never hooks `onData` for you. You decide what gets echoed and what gets forwarded, which is what makes char-at-a-time, buffered, and multi-session tab switching all possible. |
+| **Small and self-contained** | 6.1 kB gzipped, zero runtime dependencies, dual CJS/ESM with full type declarations. |
+| **Proven under load** | Extracted from [Codeman](https://getcodeman.com), hardened over thousands of hours of real remote and mobile usage, 175 tests over every state transition. |
+
+Built for anything that puts a terminal behind a network hop: SSH web clients, cloud IDEs, mobile terminals, Kubernetes and container consoles, remote agent dashboards, browser-based dev environments.
 
 ## Install
 
@@ -47,12 +66,9 @@ This library was extracted from [Codeman](https://github.com/Ark0N/Codeman), mis
 npm install xterm-zerolag-input
 ```
 
-- **Zero runtime dependencies**
-- Compatible with both `xterm` (pre-5.4) and `@xterm/xterm` (5.4+)
-- Dual CJS/ESM build with full TypeScript declarations
-- Works with canvas, WebGL, and DOM renderers
+Works with both `xterm` (pre-5.4) and `@xterm/xterm` (5.4+), and with the canvas, WebGL and DOM renderers.
 
-## Quick Start
+## Quick start
 
 ```typescript
 import { Terminal } from '@xterm/xterm';
@@ -61,7 +77,7 @@ import { ZerolagInputAddon } from 'xterm-zerolag-input';
 const terminal = new Terminal();
 terminal.open(document.getElementById('terminal')!);
 
-// 1. Create addon with your prompt character
+// 1. Create the addon with your prompt character
 const zerolag = new ZerolagInputAddon({
   prompt: { type: 'character', char: '$', offset: 2 },
 });
@@ -75,7 +91,7 @@ terminal.onData((data) => {
     ws.send(text + '\r');
   } else if (data === '\x7f') {
     const source = zerolag.removeChar();
-    if (source === 'flushed') ws.send(data); // only backspace text already in PTY
+    if (source === 'flushed') ws.send(data); // only backspace text already in the PTY
   } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
     zerolag.addChar(data);
   }
@@ -87,26 +103,29 @@ terminal.onWriteParsed(() => {
 });
 ```
 
-## Why This Is Hard
+That is the whole integration. Everything below is for tuning it.
 
-Most terminal UIs can't do local echo because:
+## Why this is hard
 
-1. **Buffer writes corrupt**: Frameworks like [Ink](https://github.com/vadimdemedes/ink) (React for terminals) redraw the entire screen on every state change. Writing directly to the terminal buffer gets immediately overwritten.
+Most terminal UIs cannot do local echo, for three reasons:
 
-2. **Cursor position lies**: In Ink, `buffer.cursorY` reflects internal state (near the status bar), not the visible prompt. You can't trust it.
+1. **Buffer writes get corrupted.** Frameworks like [Ink](https://github.com/vadimdemedes/ink) (React for terminals) redraw the entire screen on every state change. Anything written straight into the terminal buffer is overwritten immediately.
 
-3. **Font matching**: Canvas/WebGL renderers use their own text shaping. A DOM overlay must pixel-match the canvas grid — normal DOM text flow drifts due to sub-pixel glyph width differences.
+2. **Cursor position lies.** In Ink, `buffer.cursorY` reflects internal render state (often near a status bar), not the visible prompt. You cannot trust it.
 
-This library solves all three by:
-- Using a **DOM overlay** that Ink can't touch (separate z-index layer)
-- **Scanning the buffer** bottom-up for the prompt character instead of trusting cursor position
-- Rendering each character as an **absolutely-positioned `<span>`** at exact cell-grid coordinates
+3. **Fonts do not line up.** Canvas and WebGL renderers do their own text shaping. A DOM overlay has to pixel-match that grid, and normal DOM text flow drifts as sub-pixel glyph widths accumulate.
+
+This library answers all three:
+
+- a **DOM overlay** on its own z-index layer, which Ink cannot touch
+- **bottom-up buffer scanning** for the prompt instead of trusting the cursor
+- **one absolutely-positioned `<span>` per character** at exact cell-grid coordinates
 
 ---
 
-## Prompt Detection
+## Prompt detection
 
-The addon needs to know where user input starts. It scans the terminal buffer bottom-up for the prompt. Three strategies:
+The addon needs to know where user input starts. It scans the terminal buffer bottom-up. Three strategies:
 
 ### Character (default)
 
@@ -118,17 +137,17 @@ The addon needs to know where user input starts. It scans the terminal buffer bo
 { type: 'character', char: '%', offset: 2 }
 
 // Fish / Starship: ❯
-{ type: 'character', char: '\u276f', offset: 2 }
+{ type: 'character', char: '❯', offset: 2 }
 
 // Simple arrow: >
 { type: 'character', char: '>', offset: 2 }
 ```
 
-`offset` = characters between the prompt marker and where user input begins (e.g., `"$ "` = 2).
+`offset` = characters between the prompt marker and where user input begins (`"$ "` = 2).
 
 ### Regex
 
-For complex prompts. The `g` flag is safely stripped to prevent `lastIndex` mutation.
+For complex prompts. The `g` flag is stripped safely, so there is no `lastIndex` mutation.
 
 ```typescript
 { type: 'regex', pattern: /\$\s*$/, offset: 2 }
@@ -150,77 +169,88 @@ Full control:
 }
 ```
 
+### Switching prompts at runtime
+
+If one terminal hosts several CLIs with different prompts, swap the strategy in place:
+
+```typescript
+zerolag.setPrompt({ type: 'character', char: '❯', offset: 2 });
+```
+
+`setPrompt()` clears the cached prompt position and re-renders if anything is pending, so a mode switch cannot leave the overlay pinned to the old column.
+
 ---
 
-## API Reference
+## API reference
 
 ### `ZerolagInputAddon`
 
-Implements xterm.js `ITerminalAddon`. The addon does **not** hook `terminal.onData()` — you wire your own input handler and call these methods. This gives you full control over which keystrokes are echoed vs forwarded.
+Implements the xterm.js `ITerminalAddon` interface. It deliberately does **not** hook `terminal.onData()`: you wire your own handler and call these methods, which is what gives you control over which keystrokes are echoed and which are forwarded.
 
 ### Input
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `addChar(char)` | `void` | Add a single printable character. Auto-detects existing buffer text on first keystroke. |
+| `addChar(char)` | `void` | Add a single printable character. Auto-detects existing buffer text on the first keystroke. |
 | `appendText(text)` | `void` | Append multiple characters (paste). |
-| `removeChar()` | `'pending'` \| `'flushed'` \| `false` | Remove last char. See [backspace handling](#backspace-handling). |
-| `clear()` | `void` | Clear all state, hide overlay. Call on Enter/Ctrl+C/Escape. |
+| `removeChar()` | `'pending'` \| `'flushed'` \| `false` | Remove the last character. See [backspace handling](#backspace-handling). |
+| `clear()` | `void` | Clear all state and hide the overlay. Call on Enter, Ctrl+C, Escape. |
 
-### Backspace Handling
+### Backspace handling
 
 `removeChar()` cascades through three layers and tells you what it removed:
 
 | Return | Source | Your action |
 |--------|--------|-------------|
-| `'pending'` | Unsent text (never transmitted to PTY) | Do nothing |
-| `'flushed'` | Text already sent to PTY | Send `\x7f` backspace to PTY |
+| `'pending'` | Unsent text (never transmitted to the PTY) | Do nothing |
+| `'flushed'` | Text already sent to the PTY | Send `\x7f` to the PTY |
 | `false` | Nothing to remove | Do nothing |
 
-The cascade: pending text first, then flushed text, then auto-detect buffer text (handles tab completion). This means backspace "just works" through any combination of typed, flushed, and tab-completed text.
+The cascade order is pending text, then flushed text, then auto-detected buffer text (which is what makes backspace work after tab completion). Backspace "just works" across any combination of typed, in-flight and completed text.
 
-### Flushed Text
+### Flushed text
 
-"Flushed" = sent to PTY but echo hasn't arrived yet. Happens during tab switches and tab completion.
+"Flushed" means sent to the PTY but the echo has not arrived yet. This happens during tab switches and tab completion.
 
 | Method | Description |
 |--------|-------------|
-| `setFlushed(count, text, render?)` | Mark text as flushed. Pass `render=false` during tab-switch restore (buffer not loaded yet). |
+| `setFlushed(count, text, render?)` | Mark text as flushed. Pass `render=false` during tab-switch restore, when the buffer is not loaded yet. |
 | `getFlushed()` | Returns `{ count, text }`. |
-| `clearFlushed()` | Clear flushed state when server echo arrives. |
+| `clearFlushed()` | Clear flushed state once the server echo arrives. |
 
-### Buffer Detection
+### Buffer detection
 
-Scan the terminal for text that exists after the prompt but wasn't typed through the overlay.
+Finds text that exists after the prompt but was never typed through the overlay.
 
 | Method | Description |
 |--------|-------------|
-| `detectBufferText()` | Scan and return detected text (or `null`). Sets it as flushed. Guarded: runs once per `clear()` cycle. |
+| `detectBufferText()` | Scan and return the detected text (or `null`), marking it flushed. Guarded: runs once per `clear()` cycle. |
 | `resetBufferDetection()` | Re-enable detection. |
-| `suppressBufferDetection()` | Block detection until next `clear()`. Use for sessions with UI framework text after the prompt. |
-| `undoDetection()` | Undo last detection — clears flushed state, re-enables detection. For tab completion retry. |
+| `suppressBufferDetection()` | Block detection until the next `clear()`. Use for sessions that render UI framework text after the prompt. |
+| `undoDetection()` | Undo the last detection: clears flushed state and re-enables detection. For tab-completion retries. |
 
 ### Rendering
 
 | Method | Description |
 |--------|-------------|
-| `rerender()` | Force re-render. Call after buffer reloads, screen redraws, resizes, reconnects. |
-| `refreshFont()` | Re-cache font properties from terminal. Call after font size or theme changes. |
+| `rerender()` | Force a re-render. Call after buffer reloads, screen redraws, resizes and reconnects. |
+| `refreshFont()` | Re-cache font and color properties from the terminal. Call after a font size or theme change. |
 
-### Prompt Utilities
+### Prompt
 
 | Method | Description |
 |--------|-------------|
-| `findPrompt()` | Find prompt position. Returns `{ row, col }` or `null`. |
-| `readPromptText()` | Read text after prompt marker. Returns string or `null`. |
+| `setPrompt(finder)` | Replace the prompt detection strategy at runtime. |
+| `findPrompt()` | Find the prompt position. Returns `{ row, col }` or `null`. |
+| `readPromptText()` | Read the text after the prompt marker. Returns a string or `null`. |
 
 ### State
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `pendingText` | `string` | Unacknowledged text (read-only) |
-| `hasPending` | `boolean` | `true` if overlay has any content |
-| `state` | `ZerolagInputState` | Full snapshot: pendingText, flushedLength, flushedText, visible, promptPosition |
+| `hasPending` | `boolean` | `true` if the overlay has any content |
+| `state` | `ZerolagInputState` | Full snapshot: `pendingText`, `flushedLength`, `flushedText`, `visible`, `promptPosition` |
 
 ### Options
 
@@ -228,23 +258,23 @@ Scan the terminal for text that exists after the prompt but wasn't typed through
 {
   prompt?: PromptFinder,       // Default: { type: 'character', char: '>', offset: 2 }
   zIndex?: number,             // Default: 7
-  backgroundColor?: string,    // Default: from terminal theme
-  foregroundColor?: string,    // Default: from computed .xterm-rows style
+  backgroundColor?: string,    // Default: terminal theme background ('transparent' to disable)
+  foregroundColor?: string,    // Default: terminal theme / computed .xterm-rows style
   showCursor?: boolean,        // Default: true
-  cursorColor?: string,        // Default: from terminal theme
+  cursorColor?: string,        // Default: terminal theme cursor
   scrollDebounceMs?: number,   // Default: 50
 }
 ```
 
 ---
 
-## Integration Patterns
+## Integration patterns
 
-### Buffered Input (hold until Enter)
+### Buffered input (hold until Enter)
 
-The quick start example above. Characters accumulate in the overlay and are sent on Enter. Best for remote shells where you want to batch input.
+The quick start above. Characters accumulate in the overlay and go out on Enter. Best for remote shells where you want to batch input.
 
-### Char-at-a-Time (send immediately)
+### Char-at-a-time (send immediately)
 
 ```typescript
 terminal.onData((data) => {
@@ -256,12 +286,14 @@ terminal.onData((data) => {
     ws.send(data);
   } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
     zerolag.addChar(data);
-    ws.send(data); // send immediately — overlay shows while echo travels back
+    ws.send(data); // overlay shows the char while the echo travels back
   }
 });
 ```
 
-### Tab Switching (multi-session)
+This is the mode that keeps shell features intact: tab completion, `Ctrl+R` history search, and readline bindings all still work, because every byte still reaches the PTY.
+
+### Tab switching (multi-session)
 
 ```typescript
 function switchToSession(newId: string) {
@@ -280,19 +312,19 @@ function switchToSession(newId: string) {
   const saved = savedState.get(newId);
   if (saved) zerolag.setFlushed(saved.count, saved.text, false); // silent
 
-  // Render after buffer loads
+  // Render after the buffer loads
   terminal.write('', () => zerolag.rerender());
 }
 ```
 
-### Tab Completion
+### Tab completion
 
 ```typescript
 const baseline = zerolag.readPromptText();
 zerolag.clear();
 sendToPty('\t');
 
-// After response:
+// After the response:
 zerolag.resetBufferDetection();
 const detected = zerolag.detectBufferText();
 if (detected && detected !== baseline) {
@@ -302,7 +334,7 @@ if (detected && detected !== baseline) {
 }
 ```
 
-### Resize / Font / Reconnect
+### Resize, font, reconnect
 
 ```typescript
 fitAddon.fit();
@@ -311,14 +343,31 @@ zerolag.rerender();
 terminal.options.fontSize = 18;
 zerolag.refreshFont();
 
-function onReconnect() { zerolag.rerender(); }
+function onReconnect() {
+  zerolag.rerender();
+}
 ```
 
+### Wide characters (CJK, emoji)
+
+Wide characters work out of the box: the overlay measures each character's cell width, renders double-width spans for wide ones, and positions later characters by visual column instead of character index. Line wrapping is computed in columns too, so a wrapped Japanese or Chinese line lands on the same cells the server will use.
+
+For exact Unicode 11+ widths, load xterm's Unicode addon and the overlay will defer to it:
+
+```typescript
+import { Unicode11Addon } from '@xterm/addon-unicode11';
+
+terminal.loadAddon(new Unicode11Addon());
+terminal.unicode.activeVersion = '11';
+```
+
+Without it, a built-in range table covers Hangul, Kana, CJK Unified (including Ext A through G), fullwidth forms and the emoji planes.
+
 ---
 
-## How It Works
+## How it works
 
-### DOM Structure
+### DOM structure
 
 ```
 div.xterm-screen (position: relative)
@@ -326,53 +375,61 @@ div.xterm-screen (position: relative)
   ├── div.xterm-selection (z-index: 1)
   ├── div.xterm-helpers (z-index: 5)
   ├── div.xterm-decoration-container (z-index: 6-7)
-  └── div[zerolag overlay] (z-index: 7)  ← our overlay (invisible to Ink)
+  └── div[zerolag overlay] (z-index: 7)  ← our overlay, invisible to Ink
 ```
 
-### Per-Character Grid Alignment
+### Per-character grid alignment
 
 Each character is an absolutely-positioned `<span>`:
 
 ```
-left  = charIndex * cellWidth   (CSS pixels)
-top   = lineIndex * cellHeight  (CSS pixels)
-width = cellWidth               (exact cell width)
+left  = visualColumn * cellWidth   (CSS pixels)
+top   = lineIndex    * cellHeight  (CSS pixels)
+width = cellWidth * charCellWidth  (1 cell, or 2 for wide characters)
 ```
 
-This avoids sub-pixel drift from normal DOM text flow.
+Positioning by visual column instead of letting the browser lay out text is what removes sub-pixel drift.
 
-### Font Matching
+### Font matching
 
 1. `fontFamily`, `fontSize`, `fontWeight` from `terminal.options`
-2. `letterSpacing` from computed style of `.xterm-rows`
-3. `-webkit-font-smoothing: antialiased` (matches canvas grayscale)
+2. `letterSpacing` from the computed style of `.xterm-rows`
+3. `-webkit-font-smoothing: antialiased` (matches canvas grayscale AA)
 4. `font-feature-settings: 'liga' 0, 'calt' 0` (no ligatures)
 5. `text-rendering: geometricPrecision`
 
-### Cell Dimensions
+### Cell dimensions
 
 - **xterm.js v5.x**: `terminal._core._renderService.dimensions.css.cell` (private API)
 - **xterm.js v7+**: `terminal.dimensions.css.cell` (public API, auto-detected)
 
-### Prompt Column Locking
+### Prompt column locking
 
-When flushed text exists, the prompt column is locked to prevent jitter from full-screen redraws. Row changes are allowed (output can scroll the prompt).
+While flushed text exists the prompt column is locked, so a full-screen redraw cannot make the overlay jitter sideways. Row changes are still allowed, because output legitimately scrolls the prompt.
 
-### Scroll Awareness
+### Scroll awareness
 
-Overlay hides when scrolled up (`viewportY !== baseY`). Debounced re-render when scrolling back to bottom.
+The overlay hides when the viewport is scrolled up (`viewportY !== baseY`) and re-renders, debounced, when you scroll back to the bottom.
 
 ---
 
-## Known Limitations
+## Known limitations
 
-- **Canvas/WebGL font mismatch**: Minor sub-pixel differences possible. Per-character absolute positioning minimizes this.
-- **Unicode/emoji**: Multi-byte characters occupy variable cell widths — rendered at single-cell width, causing misalignment.
-- **Password prompts**: Overlay shows characters that aren't echoed. Call `clear()` when you detect no-echo mode.
-- **Prompt in output**: If `$` appears in command output, prompt detection may find the wrong position. Use regex or custom finder.
+- **Canvas and WebGL font mismatch**: minor sub-pixel differences are still possible. Per-character absolute positioning keeps them small.
+- **Grapheme clusters**: widths are summed per code point, so ZWJ emoji sequences (for example 👨‍👩‍👧) and combining marks can be over-counted. Single-code-point emoji and CJK are correct.
+- **Password prompts**: the overlay will happily show characters the server is not echoing. Call `clear()` when you detect a no-echo prompt.
+- **Prompt characters in output**: if your prompt marker also appears in command output, detection can latch onto the wrong line. Use a regex or a custom finder.
 
 ---
 
+## Origin
+
+[Codeman](https://getcodeman.com) needed this before anyone else did. A coding agent you drive from your phone over a tunnel is unusable if every keystroke costs a round trip.
+
+So the overlay was built there, ran in production for thousands of hours, and survived three deep code audits before being pulled out into this standalone library with its tests intact. Nothing was reimplemented for the extraction: the engine here is the one Codeman ships.
+
+Want the whole thing? [**getcodeman.com**](https://getcodeman.com) · [github.com/Ark0N/Codeman](https://github.com/Ark0N/Codeman)
+
 ## License
 
-MIT — [Codeman](https://github.com/Ark0N/Codeman) Contributors
+MIT, [Codeman](https://github.com/Ark0N/Codeman) Contributors

packages/xterm-zerolag-input/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xterm-zerolag-input",
-  "version": "0.1.4",
-  "description": "Instant keystroke feedback overlay for xterm.js — eliminates perceived input latency over high-RTT connections",
+  "version": "0.1.8",
+  "description": "Instant keystroke feedback overlay for xterm.js: Mosh-inspired local echo that removes perceived input latency over SSH, tunnels and other high-RTT connections",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -26,8 +26,16 @@
     "xterm",
     "xterm.js",
     "terminal",
+    "web-terminal",
     "local-echo",
+    "local echo",
+    "mosh",
     "input-latency",
+    "latency",
+    "zero-lag",
+    "keystroke",
+    "ssh",
+    "remote-terminal",
     "overlay",
     "addon"
   ],

scripts/capture-readme-real.mjs

@@ -50,7 +50,7 @@ async function newCtx(browser) {
       try {
         localStorage.setItem('codeman:skin', skin);
         localStorage.setItem('codeman-font-size', String(font));
-        const blob = { skin, showFileBrowser: false, showProjectInsights: false };
+        const blob = { skin, showFileBrowser: false, showProjectInsights: false, showTokenCount: false };
         // Don't auto-hide subagent windows that belong to a non-active tab — the
         // subagent scene re-homes agents and needs both windows visible at once.
         blob.subagentActiveTabOnly = false;

scripts/capture-real-overview.mjs

@@ -79,6 +79,7 @@ const main = async () => {
           showMonitor: false,
           showSubagents: false,
           showProjectInsights: false,
+          showTokenCount: false,
         };
         if (planUsage) blob.showPlanUsageLimits = true;
         localStorage.setItem('codeman-app-settings', JSON.stringify(blob));

scripts/capture-subagent-gif.mjs

@@ -126,6 +126,7 @@ async function capture() {
         showMonitor: false,
         showProjectInsights: false,
         showFileBrowser: false,
+        showTokenCount: false,
       });
       localStorage.setItem('codeman-app-settings', JSON.stringify(existing));
     });
@@ -230,6 +231,7 @@ async function capture() {
         showMonitor: false,
         showProjectInsights: false,
         showFileBrowser: false,
+        showTokenCount: false,
       });
       localStorage.setItem('codeman-app-settings', JSON.stringify(existing));
     });

scripts/capture-subagent-screenshots.mjs

@@ -221,6 +221,7 @@ async function configureSettings(page) {
       subagentTrackingEnabled: true,
       subagentActiveTabOnly: false, // Show all subagents regardless of active tab
       showMonitor: true,
+      showTokenCount: false,
     };
     localStorage.setItem('codeman-app-settings', JSON.stringify(settings));
   });

scripts/fix-node-pty.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Repairs node-pty's macOS `spawn-helper` and verifies that a PTY
+ * can really be spawned. Called by `scripts/postinstall.js` on every install and
+ * exposed as `npm run fix:node-pty` for repairing an install after the fact.
+ *
+ * Why this exists (issues #6 and #204):
+ *
+ * node-pty@1.1.0 publishes its macOS prebuilt helper as
+ * `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit.
+ * On macOS node-pty launches every PTY through that helper with posix_spawnp,
+ * which then fails EACCES and surfaces as `Error: posix_spawnp failed.` on every
+ * session start.
+ *
+ * It is macOS-exclusive twice over: `spawn-helper` is an `OS=="mac"` gyp target,
+ * and pty.cc only spawns it under `#if defined(__APPLE__)`. node-pty ships
+ * prebuilds for darwin and win32 only, so Linux always compiles from source
+ * (which produces an executable helper) and never sees the bug.
+ *
+ * The repair is a chmod, NOT a rebuild: the prebuilt binary itself is fine, and
+ * requiring a from-source rebuild would make every macOS install depend on Xcode
+ * command line tools. A rebuild is attempted only when a chmod plus a real spawn
+ * probe still can't get a working PTY, and the prebuilds tree is backed up first
+ * so a failed rebuild can never leave the install worse than it started.
+ */
+
+import { chmodSync, cpSync, existsSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** Errors that mean "the native module or its helper is unusable", i.e. worth a rebuild. */
+const NATIVE_FAILURE_PATTERN = /posix_spawnp|spawn-helper|Failed to load native module|Cannot find module/i;
+
+/**
+ * Locates the installed node-pty package directory.
+ *
+ * @returns {string|null} Absolute path to the package root, or null if not installed.
+ */
+export function findNodePtyDir() {
+    // package.json first: node-pty declares no "exports" map, so the subpath resolves,
+    // and it lands on the package root directly. require.resolve('node-pty') would give
+    // <pkg>/lib/index.js, which is one directory deeper than callers expect.
+    try {
+        return dirname(require.resolve('node-pty/package.json'));
+    } catch {
+        /* fall through */
+    }
+    try {
+        return join(dirname(require.resolve('node-pty')), '..');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Lists every `spawn-helper` shipped in a node-pty install.
+ *
+ * node-pty's own loader (lib/utils.js) checks `build/Release`, `build/Debug` and
+ * then `prebuilds/<platform>-<arch>`, and takes the helper from whichever
+ * directory the native module loaded out of, so all of them must be executable,
+ * not just the one this machine happens to use today.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {string[]} Absolute paths of the helpers that exist on disk.
+ */
+export function listSpawnHelpers(ptyDir) {
+    const dirs = [join(ptyDir, 'build', 'Release'), join(ptyDir, 'build', 'Debug')];
+
+    const prebuilds = join(ptyDir, 'prebuilds');
+    if (existsSync(prebuilds)) {
+        try {
+            for (const entry of readdirSync(prebuilds, { withFileTypes: true })) {
+                if (entry.isDirectory()) dirs.push(join(prebuilds, entry.name));
+            }
+        } catch {
+            /* unreadable prebuilds dir: nothing to repair there */
+        }
+    }
+
+    return dirs.map((d) => join(d, 'spawn-helper')).filter((p) => existsSync(p));
+}
+
+/**
+ * Adds the execute bit to every `spawn-helper` that is missing it.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {{ repaired: string[], failed: Array<{ path: string, error: string }> }}
+ */
+export function repairSpawnHelpers(ptyDir) {
+    const repaired = [];
+    const failed = [];
+
+    for (const helper of listSpawnHelpers(ptyDir)) {
+        try {
+            const mode = statSync(helper).mode & 0o777;
+            if ((mode & 0o111) === 0o111) continue; // already executable by all
+            chmodSync(helper, mode | 0o755);
+            repaired.push(helper);
+        } catch (err) {
+            failed.push({ path: helper, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+
+    return { repaired, failed };
+}
+
+/**
+ * Proves node-pty works by actually opening a PTY, which is the only check that
+ * exercises the spawn-helper path that breaks. A `require` alone would pass on a
+ * broken install, because the helper is only touched at spawn time.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {{ ok: boolean, error?: string, nativeFailure?: boolean }}
+ */
+export function verifyPtySpawn(ptyDir) {
+    let child;
+    try {
+        const pty = require(ptyDir); // directory require → node-pty's "main" (lib/index.js)
+        const file = process.platform === 'win32' ? process.env.COMSPEC || 'cmd.exe' : '/bin/echo';
+        const args = process.platform === 'win32' ? ['/c', 'exit'] : ['codeman-node-pty-check'];
+        child = pty.spawn(file, args, {
+            name: 'xterm-color',
+            cols: 80,
+            rows: 24,
+            cwd: tmpdir(),
+            env: process.env,
+        });
+        return { ok: true };
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: message, nativeFailure: NATIVE_FAILURE_PATTERN.test(message) };
+    } finally {
+        try {
+            child?.kill();
+        } catch {
+            /* the probe child exits on its own anyway */
+        }
+    }
+}
+
+/**
+ * Rebuilds node-pty from source, preserving the prebuilds tree across a failure.
+ *
+ * node-pty's install script deletes `prebuilds/` as soon as
+ * `npm_config_build_from_source` is set and only then shells out to node-gyp, so
+ * a machine without a compiler toolchain would otherwise be left with neither a
+ * prebuilt nor a compiled binary.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @param {string} cwd Directory to run npm from (the package root that owns node_modules).
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function rebuildFromSource(ptyDir, cwd) {
+    const prebuilds = join(ptyDir, 'prebuilds');
+    const backup = join(ptyDir, '.prebuilds-codeman-backup');
+
+    let backedUp = false;
+    if (existsSync(prebuilds)) {
+        try {
+            rmSync(backup, { recursive: true, force: true });
+            cpSync(prebuilds, backup, { recursive: true });
+            backedUp = true;
+        } catch {
+            /* best effort: proceed without a safety net rather than skip the repair */
+        }
+    }
+
+    try {
+        execSync('npm rebuild node-pty --build-from-source', { cwd, stdio: 'pipe', timeout: 300000 });
+        return { ok: true };
+    } catch (err) {
+        if (backedUp && !existsSync(prebuilds)) {
+            try {
+                cpSync(backup, prebuilds, { recursive: true });
+            } catch {
+                /* nothing further we can do */
+            }
+        }
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    } finally {
+        rmSync(backup, { recursive: true, force: true });
+    }
+}
+
+/**
+ * Full repair flow: chmod, verify, and only rebuild if a working PTY still can't
+ * be opened.
+ *
+ * @param {object} [options]
+ * @param {(line: string) => void} [options.log] Progress sink (default: silent).
+ * @param {(line: string) => void} [options.warn] Warning sink (default: same as log).
+ * @param {boolean} [options.allowRebuild] Permit a from-source rebuild (default: true).
+ * @returns {Promise<{ ok: boolean, repaired: string[], rebuilt: boolean, reason?: string }>}
+ */
+export async function fixNodePty(options = {}) {
+    const log = options.log ?? (() => {});
+    const warn = options.warn ?? log;
+    const allowRebuild = options.allowRebuild ?? true;
+
+    const ptyDir = findNodePtyDir();
+    if (!ptyDir) {
+        return { ok: false, repaired: [], rebuilt: false, reason: 'node-pty is not installed' };
+    }
+
+    const { repaired, failed } = repairSpawnHelpers(ptyDir);
+    for (const f of failed) warn(`could not chmod ${f.path}: ${f.error}`);
+    if (repaired.length > 0) {
+        log(`made node-pty spawn-helper executable (${repaired.length} file${repaired.length === 1 ? '' : 's'})`);
+    }
+
+    const first = verifyPtySpawn(ptyDir);
+    if (first.ok) return { ok: true, repaired, rebuilt: false };
+
+    if (!allowRebuild || !first.nativeFailure) {
+        return { ok: false, repaired, rebuilt: false, reason: first.error };
+    }
+
+    warn(`node-pty could not open a PTY (${first.error}), rebuilding from source...`);
+    const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+    const rebuild = rebuildFromSource(ptyDir, projectRoot);
+    if (!rebuild.ok) {
+        return { ok: false, repaired, rebuilt: false, reason: `rebuild failed: ${rebuild.error}` };
+    }
+
+    const after = repairSpawnHelpers(ptyDir);
+    repaired.push(...after.repaired);
+
+    const second = verifyPtySpawn(ptyDir);
+    return second.ok
+        ? { ok: true, repaired, rebuilt: true }
+        : { ok: false, repaired, rebuilt: true, reason: second.error };
+}
+
+// ---------------------------------------------------------------------------
+// CLI: node scripts/fix-node-pty.mjs [--quiet]
+// ---------------------------------------------------------------------------
+
+const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isDirectRun) {
+    const quiet = process.argv.includes('--quiet');
+    const say = (line) => {
+        if (!quiet) console.log(line);
+    };
+
+    const result = await fixNodePty({ log: say, warn: (line) => console.warn(line) });
+
+    if (result.ok) {
+        say(result.repaired.length > 0 || result.rebuilt ? 'node-pty repaired, PTY spawning works' : 'node-pty is healthy');
+        process.exit(0);
+    }
+
+    console.error(`node-pty is not usable: ${result.reason}`);
+    console.error('Try:  cd node_modules/node-pty && npx node-gyp rebuild');
+    process.exit(1);
+}

scripts/postinstall.js

@@ -6,7 +6,7 @@
  */
 
 import { execSync, spawn } from 'child_process';
-import { chmodSync, existsSync } from 'fs';
+import { existsSync } from 'fs';
 import { homedir, platform } from 'os';
 import { join } from 'path';
 import { createRequire } from 'module';
@@ -148,35 +148,32 @@ if (majorVersion < MIN_NODE_VERSION) {
 }
 
 // ----------------------------------------------------------------------------
-// 1b. Fix node-pty spawn-helper permissions (macOS posix_spawnp fix)
+// 1b. Repair + verify node-pty (macOS posix_spawnp fix, issues #6 and #204)
+//
+// node-pty ships its macOS spawn-helper without the execute bit, which breaks
+// every session start on macOS. fixNodePty() chmods it, then proves a PTY can
+// actually be opened, and only falls back to a from-source rebuild if that
+// still fails. See scripts/fix-node-pty.mjs for the full story.
 // ----------------------------------------------------------------------------
 
 try {
-    const require = createRequire(import.meta.url);
-    const ptyPath = join(require.resolve('node-pty'), '..');
-    const spawnHelper = join(ptyPath, 'build', 'Release', 'spawn-helper');
-    if (existsSync(spawnHelper)) {
-        chmodSync(spawnHelper, 0o755);
-        console.log(colors.green('✓ node-pty spawn-helper permissions fixed'));
-    }
-} catch {
-    // Non-critical — only affects macOS with prebuilt binaries
-}
+    const { fixNodePty } = await import('./fix-node-pty.mjs');
+    const result = await fixNodePty({
+        log: (line) => console.log(colors.dim(`  ${line}`)),
+        warn: (line) => console.log(colors.yellow(`⚠ ${line}`)),
+    });
 
-// ----------------------------------------------------------------------------
-// 1c. Rebuild node-pty from source for Node.js 22+ compatibility
-// ----------------------------------------------------------------------------
-
-if (majorVersion >= 22) {
-    try {
-        console.log(colors.dim('  Rebuilding node-pty from source for Node.js 22+...'));
-        execSync('npm rebuild node-pty --build-from-source', { stdio: 'pipe', timeout: 120000 });
-        console.log(colors.green('✓ node-pty rebuilt from source'));
-    } catch {
+    if (result.ok) {
+        console.log(colors.green('✓ node-pty verified') + colors.dim(' (PTY spawn works)'));
+    } else {
         hasWarnings = true;
-        console.log(colors.yellow('⚠ Failed to rebuild node-pty from source'));
-        console.log(colors.dim('  You may need to run: npm rebuild node-pty --build-from-source'));
+        console.log(colors.yellow(`⚠ node-pty is not usable: ${result.reason}`));
+        console.log(colors.dim('  Sessions will fail to start. Try: ') + colors.cyan('npm run fix:node-pty'));
     }
+} catch (err) {
+    hasWarnings = true;
+    console.log(colors.yellow(`⚠ Could not verify node-pty: ${err.message}`));
+    console.log(colors.dim('  If sessions fail to start, run: ') + colors.cyan('npm run fix:node-pty'));
 }
 
 // ----------------------------------------------------------------------------

src/config/auth-config.ts

@@ -31,5 +31,10 @@ export const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
 // Hooks
 // ============================================================================
 
-/** Timeout for Claude Code hook curl commands (ms) */
-export const HOOK_TIMEOUT_MS = 10000;
+/**
+ * Timeout for Claude Code hook curl commands, in SECONDS: the hook `timeout`
+ * field is seconds (the CLI multiplies by 1000). The predecessor constant
+ * `HOOK_TIMEOUT_MS = 10000` fed the same field, so those hooks effectively had a
+ * ~2.8-hour timeout; 10 seconds is the originally intended budget.
+ */
+export const HOOK_TIMEOUT_SECONDS = 10;

src/config/dependency-registry.ts

@@ -98,6 +98,14 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
     usedBy: ['Gemini sessions'],
     resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['gemini'], versionArg: '--version' } }],
   },
+  {
+    id: 'antigravity',
+    label: 'Antigravity CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Antigravity sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['agy'], versionArg: '--version' } }],
+  },
   {
     id: 'libreoffice',
     label: 'LibreOffice',

src/config/file-editing.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview File Viewer edit-mode policy (issue #212).
+ *
+ * Pure, IO-free policy for which workspace files the in-viewer editor may read
+ * for editing and write back. Consumed by the `edit=1` branch of
+ * `GET /api/sessions/:id/file-content` and by `PUT /api/sessions/:id/file-content`
+ * in `src/web/routes/file-routes.ts`.
+ *
+ * Design (docs/file-viewer-edit-plan.md):
+ * - ALLOWLIST of text extensions/basenames, not a blocklist — matching the
+ *   attachment-guard precedent. `svg` and `env` are deliberately absent: svg is
+ *   treated as untrusted on the read side, and `.env` is sensitive-path blocked
+ *   anyway; excluding them here keeps a single obvious refusal.
+ * - The `.git/` subtree is denied outright: `.git/hooks/*` is code execution and
+ *   a corrupted index looks unrecoverable to a user who wanted to fix a typo.
+ * - EOL helpers exist because a browser <textarea> normalizes to LF; the server
+ *   re-applies the file's original ending so a two-line edit of a CRLF file does
+ *   not become a whole-file diff. Mixed-EOL files normalize to the dominant
+ *   style (documented lossy edge).
+ */
+
+/** Hard cap for edit-mode reads AND writes (bytes of file content). */
+export const MAX_EDITABLE_BYTES = 512 * 1024;
+
+/** Lowercase extensions (no dot) the editor will open and save. */
+export const EDITABLE_EXTENSIONS: ReadonlySet<string> = new Set([
+  // JS/TS ecosystem
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'mjs',
+  'cjs',
+  'json',
+  'jsonc',
+  // Docs / plain text
+  'md',
+  'mdx',
+  'txt',
+  'rst',
+  'adoc',
+  // Web
+  'css',
+  'scss',
+  'less',
+  'html',
+  'htm',
+  'xml',
+  // Config
+  'yml',
+  'yaml',
+  'toml',
+  'ini',
+  'cfg',
+  'conf',
+  'properties',
+  // Shell
+  'sh',
+  'bash',
+  'zsh',
+  'fish',
+  // Languages
+  'py',
+  'rb',
+  'go',
+  'rs',
+  'java',
+  'kt',
+  'swift',
+  'c',
+  'h',
+  'cpp',
+  'hpp',
+  'cc',
+  'cs',
+  'php',
+  'sql',
+  'graphql',
+  'proto',
+  'lua',
+  'pl',
+  'r',
+  'jl',
+  'tf',
+  'gradle',
+  // Data / misc text
+  'csv',
+  'tsv',
+  'log',
+  'diff',
+  'patch',
+]);
+
+/** Extensionless (or dot-led) file names that are still editable text. */
+export const EDITABLE_BASENAMES: ReadonlySet<string> = new Set([
+  'dockerfile',
+  'makefile',
+  'license',
+  'readme',
+  'changelog',
+  'authors',
+  'codeowners',
+  'procfile',
+  '.gitignore',
+  '.gitattributes',
+  '.dockerignore',
+  '.prettierignore',
+  '.prettierrc',
+  '.editorconfig',
+  '.nvmrc',
+  '.npmrc',
+  '.eslintignore',
+]);
+
+/** Whether a file name (basename only) is eligible for in-viewer editing. */
+export function isEditableFileName(fileName: string): boolean {
+  const lower = fileName.toLowerCase();
+  if (EDITABLE_BASENAMES.has(lower)) return true;
+  const dot = lower.lastIndexOf('.');
+  // No extension (or a bare dotfile like `.bashrc`): only the basename list applies.
+  if (dot <= 0) return false;
+  return EDITABLE_EXTENSIONS.has(lower.slice(dot + 1));
+}
+
+/**
+ * Whether a workspace-relative path is denied for editing regardless of its
+ * extension. Currently: anything inside a `.git` directory at any depth.
+ */
+export function isDeniedEditRelativePath(relativePath: string): boolean {
+  return relativePath.split('/').some((segment) => segment === '.git');
+}
+
+export type FileEol = 'lf' | 'crlf';
+
+/** Dominant line-ending style of a text buffer (LF when tied or single-line). */
+export function detectEol(text: string): FileEol {
+  let crlf = 0;
+  let lf = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) {
+      if (i > 0 && text.charCodeAt(i - 1) === 13) crlf++;
+      else lf++;
+    }
+  }
+  return crlf > lf ? 'crlf' : 'lf';
+}
+
+/** Normalize every line ending in `text` to the requested style. */
+export function applyEol(text: string, eol: FileEol): string {
+  const normalized = text.replace(/\r\n/g, '\n');
+  return eol === 'crlf' ? normalized.replace(/\n/g, '\r\n') : normalized;
+}

src/config/webview-limits.ts

@@ -0,0 +1,49 @@
+/**
+ * Limits and timeouts for web tabs (dashboards embedded as Codeman tabs).
+ *
+ * Every value here bounds something an untrusted-ish upstream controls: how many
+ * dashboards can be saved, how long the server will wait on one, how much of a
+ * response it will buffer before rewriting HTML, and how many sockets a single
+ * dashboard may hold open. Env-overridable in the same style as the other config
+ * modules.
+ */
+
+function envInt(name: string, fallback: number): number {
+  const parsed = parseInt(process.env[name] || '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/** Max saved webviews (per owner in multi-user mode). */
+export const MAX_WEBVIEWS = envInt('CODEMAN_MAX_WEBVIEWS', 50);
+
+/**
+ * Max iframes kept mounted at once. Switching tabs must not reload a dashboard,
+ * so frames stay alive while hidden; past this many, the least-recently-viewed
+ * frame is evicted. Consumed by the frontend via `GET /api/webviews`.
+ */
+export const MAX_LIVE_WEBVIEW_FRAMES = envInt('CODEMAN_MAX_LIVE_WEBVIEW_FRAMES', 6);
+
+/** How long a minted proxy capability stays valid (rolling, refreshed on use). */
+export const WEBVIEW_CAPABILITY_TTL_MS = envInt('CODEMAN_WEBVIEW_CAPABILITY_TTL_MS', 12 * 60 * 60 * 1000);
+
+/** Max concurrent capabilities held in memory before the oldest are dropped. */
+export const MAX_WEBVIEW_CAPABILITIES = 200;
+
+/** Upstream request timeout for a proxied HTTP request. */
+export const WEBVIEW_UPSTREAM_TIMEOUT_MS = envInt('CODEMAN_WEBVIEW_TIMEOUT_MS', 30_000);
+
+/** Shorter timeout for the editor's "Test" probe, which a human is waiting on. */
+export const WEBVIEW_PROBE_TIMEOUT_MS = envInt('CODEMAN_WEBVIEW_PROBE_TIMEOUT_MS', 8_000);
+
+/**
+ * Max bytes of an HTML response buffered for `<base>` injection and link
+ * rewriting. Larger HTML documents stream through untouched: the rewrite is a
+ * convenience, and buffering an unbounded upstream body is a memory hazard.
+ */
+export const MAX_WEBVIEW_HTML_REWRITE_BYTES = envInt('CODEMAN_MAX_WEBVIEW_HTML_BYTES', 8 * 1024 * 1024);
+
+/** Max concurrent proxied WebSockets per webview (mirrors MAX_WS_PER_SESSION). */
+export const MAX_WEBVIEW_SOCKETS = envInt('CODEMAN_MAX_WEBVIEW_SOCKETS', 8);
+
+/** URL path prefix the proxy is mounted at. Single source of truth. */
+export const WEBVIEW_PROXY_PREFIX = '/webview';

src/docker-hosts.ts

@@ -143,6 +143,7 @@ export function defaultDockerCommandForMode(mode: SessionMode): string {
     opencode: 'exec opencode',
     codex: 'exec codex',
     gemini: 'exec gemini',
+    antigravity: 'exec agy',
   };
   return commands[mode as DockerCommandMode] || commands.shell;
 }
@@ -595,6 +596,9 @@ interface CredStorePolicy {
 
 const CRED_STORES: CredStorePolicy[] = [
   { rel: '.codex', shareDirs: ['sessions'], shareFiles: ['history.jsonl'], seedFiles: ['auth.json', 'config.toml'] },
+  // Also covers Antigravity: `agy` nests its whole state (auth `jetski_state.pbtxt`,
+  // `conversations/`, `knowledge/`) under `~/.gemini/antigravity-cli/`, so it needs no
+  // entry of its own. There is no `~/.antigravity` credential dir to add.
   { rel: '.gemini', seedWhole: true },
   { rel: '.config/gcloud', seedWhole: true },
   { rel: '.config/opencode', seedWhole: true },

src/hooks-config.ts

@@ -16,9 +16,9 @@
  * `stop`, `teammate_idle`, `task_completed`
  *
  * Hook categories: `Notification` (3 matchers), `Stop` (1), `TeammateIdle` (1),
- * `TaskCompleted` (1)
+ * `TaskCompleted` (1), `PostToolUse` (1 self-contained background Bash rewake)
  *
- * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_MS)
+ * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_SECONDS)
  * @consumedby web/server (session creation), session-cli-builder (env setup)
  *
  * @module hooks-config
@@ -29,7 +29,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { HookEventType } from './types.js';
-import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
+import { HOOK_TIMEOUT_SECONDS } from './config/auth-config.js';
 
 /**
  * Serializes read-modify-write access to a `settings.local.json` path. Every
@@ -40,6 +40,104 @@ import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
  * are independent; the map self-prunes when a path's chain goes idle.
  */
 const settingsWriteLocks = new Map<string, Promise<unknown>>();
+/**
+ * Version-agnostic ownership prefix: every rewake script version embeds a marker
+ * starting with this, and `isCodemanHookHandler` matches on the prefix. That way a
+ * version bump replaces the old handler instead of duplicating it (matching on the
+ * full versioned marker would disown every older script).
+ */
+const BACKGROUND_WAKE_MARKER_PREFIX = 'CODEMAN_BACKGROUND_REWAKE_V';
+/**
+ * Current script version. Bump the suffix whenever `generateBackgroundWakeScript`
+ * changes: `refreshStaleCodemanHooks` treats the absence of the CURRENT marker as
+ * stale, so healed cases pick up the new script on next launch.
+ */
+const BACKGROUND_WAKE_MARKER = `${BACKGROUND_WAKE_MARKER_PREFIX}2`;
+const BACKGROUND_WAKE_TIMEOUT_SECONDS = 6 * 60 * 60;
+
+/**
+ * Inline Node helper for Claude Code's `asyncRewake` hook.
+ *
+ * A background Bash tool returns immediately with a task ID, then Claude writes
+ * its completion as a queue-operation in the transcript. Watching that durable
+ * record avoids injecting terminal input (which could submit a user's draft).
+ * The helper is embedded in settings via `node -e`, so it has no script path
+ * that can go stale after an install or plugin-cache cleanup.
+ *
+ * Self-terminating: Claude Code enforces the hook timeout, but the helper does not
+ * rely on it. It exits on its own deadline (same budget) and when orphaned
+ * (`ppid === 1`), so a dead session cannot leave a poller stat-ing the transcript
+ * forever. The ppid check misses subreaper setups; the deadline is the backstop.
+ */
+export function generateBackgroundWakeScript(): string {
+  return [
+    "const fs = require('node:fs');",
+    `const ${BACKGROUND_WAKE_MARKER} = true;`,
+    `const deadline = Date.now() + ${BACKGROUND_WAKE_TIMEOUT_SECONDS} * 1000;`,
+    'let input = {};',
+    "try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }",
+    'function findTaskId(value) {',
+    "  const idKeys = new Set(['taskId', 'task_id', 'shellId', 'shell_id', 'backgroundTaskId', 'background_task_id']);",
+    '  const stack = [value];',
+    '  const seen = new Set();',
+    '  while (stack.length > 0) {',
+    '    const current = stack.pop();',
+    "    if (!current || typeof current !== 'object' || seen.has(current)) continue;",
+    '    seen.add(current);',
+    '    for (const [key, nested] of Object.entries(current)) {',
+    "      if (idKeys.has(key) && typeof nested === 'string' && /^[A-Za-z0-9_-]+$/.test(nested)) return nested;",
+    "      if (nested && typeof nested === 'object') stack.push(nested);",
+    '    }',
+    '  }',
+    "  const serialized = JSON.stringify(value ?? '');",
+    '  const messageMatch = serialized.match(/Command running in background with ID:\\s*([A-Za-z0-9_-]+)/i);',
+    '  if (messageMatch) return messageMatch[1];',
+    '  const pathMatch = serialized.match(/[\\\\/]tasks[\\\\/]([A-Za-z0-9_-]+)\\.output/i);',
+    '  return pathMatch ? pathMatch[1] : null;',
+    '}',
+    'const taskId = findTaskId(input.tool_response);',
+    "const transcriptPath = typeof input.transcript_path === 'string' ? input.transcript_path : '';",
+    'if (!taskId || !transcriptPath) process.exit(0);',
+    'let position = 0;',
+    'try { position = Math.max(0, fs.statSync(transcriptPath).size - 262144); } catch { process.exit(0); }',
+    "let carry = '';",
+    'function inspect(text) {',
+    '  for (const line of text.split(/\\r?\\n/)) {',
+    '    if (!line.includes(taskId)) continue;',
+    '    let entry;',
+    '    try { entry = JSON.parse(line); } catch { continue; }',
+    "    if (entry.type !== 'queue-operation' || typeof entry.content !== 'string') continue;",
+    "    if (!entry.content.includes('<task-id>' + taskId + '</task-id>')) continue;",
+    '    const status = entry.content.match(/<status>(completed|failed|killed|error)<\\/status>/i);',
+    '    if (!status) continue;',
+    '    const output = entry.content.match(/<output-file>([^<]+)<\\/output-file>/i);',
+    "    const location = output ? ' Read ' + output[1] + ' and' : '';",
+    "    console.error('Background command ' + taskId + ' ' + status[1].toLowerCase() + '.' + location + ' continue the task.');",
+    '    process.exit(2);',
+    '  }',
+    '}',
+    'function poll() {',
+    '  if (Date.now() > deadline || process.ppid === 1) process.exit(0);',
+    '  try {',
+    '    const size = fs.statSync(transcriptPath).size;',
+    "    if (size < position) { position = 0; carry = ''; }",
+    '    if (size > position) {',
+    '      const length = Math.min(size - position, 1048576);',
+    '      const buffer = Buffer.allocUnsafe(length);',
+    "      const fd = fs.openSync(transcriptPath, 'r');",
+    '      const bytes = fs.readSync(fd, buffer, 0, length, position);',
+    '      fs.closeSync(fd);',
+    '      position += bytes;',
+    "      carry = (carry + buffer.subarray(0, bytes).toString('utf8')).slice(-262144);",
+    '      inspect(carry);',
+    '    }',
+    '  } catch {}',
+    '  setTimeout(poll, 1000);',
+    '}',
+    'poll();',
+  ].join('\n');
+}
+
 function withSettingsLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
   const prev = settingsWriteLocks.get(path) ?? Promise.resolve();
   const run = prev.then(fn, fn); // run after the prior writer, regardless of its outcome
@@ -86,36 +184,118 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
       Notification: [
         {
           matcher: 'idle_prompt',
-          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'permission_prompt',
-          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'elicitation_dialog',
-          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       Stop: [
         {
-          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TeammateIdle: [
         {
-          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TaskCompleted: [
         {
-          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_SECONDS }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: 'node',
+              args: ['-e', generateBackgroundWakeScript()],
+              asyncRewake: true,
+              timeout: BACKGROUND_WAKE_TIMEOUT_SECONDS,
+            },
+          ],
         },
       ],
     },
   };
 }
 
+function isCodemanHookHandler(value: unknown): boolean {
+  try {
+    const serialized = JSON.stringify(value);
+    // Prefix, not the versioned marker: older script versions must still be ours.
+    return serialized.includes('/api/hook-event') || serialized.includes(BACKGROUND_WAKE_MARKER_PREFIX);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace only Codeman-owned command handlers while preserving user events,
+ * matcher entries, and sibling handlers in mixed entries.
+ */
+function mergeCodemanHooks(existingValue: unknown, generated: Record<string, unknown[]>): Record<string, unknown[]> {
+  const existing =
+    existingValue && typeof existingValue === 'object' && !Array.isArray(existingValue)
+      ? (existingValue as Record<string, unknown>)
+      : {};
+  const merged: Record<string, unknown[]> = {};
+
+  for (const eventName of new Set([...Object.keys(existing), ...Object.keys(generated)])) {
+    const existingEntries = Array.isArray(existing[eventName]) ? (existing[eventName] as unknown[]) : [];
+    const generatedEntries = generated[eventName];
+    if (!generatedEntries) {
+      merged[eventName] = existingEntries;
+      continue;
+    }
+
+    const entries: unknown[] = [];
+    let insertedGenerated = false;
+    for (const entry of existingEntries) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        if (!isCodemanHookHandler(entry)) entries.push(entry);
+        continue;
+      }
+
+      const record = entry as Record<string, unknown>;
+      if (!Array.isArray(record.hooks)) {
+        if (isCodemanHookHandler(record)) {
+          if (!insertedGenerated) {
+            entries.push(...generatedEntries);
+            insertedGenerated = true;
+          }
+        } else {
+          entries.push(entry);
+        }
+        continue;
+      }
+
+      const retainedHandlers = record.hooks.filter((handler) => !isCodemanHookHandler(handler));
+      const removedCodemanHandler = retainedHandlers.length !== record.hooks.length;
+      if (removedCodemanHandler && !insertedGenerated) {
+        entries.push(...generatedEntries);
+        insertedGenerated = true;
+      }
+      if (retainedHandlers.length > 0 || !removedCodemanHandler) {
+        entries.push(retainedHandlers.length === record.hooks.length ? entry : { ...record, hooks: retainedHandlers });
+      }
+    }
+
+    if (!insertedGenerated) entries.push(...generatedEntries);
+    merged[eventName] = entries;
+  }
+
+  return merged;
+}
+
 /**
  * Remove a subset of env keys from .claude/settings.local.json.env if present.
  * Used during the disk→tmux-setenv migration: when the caller is actively setting
@@ -237,29 +417,31 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
     }
 
     const hooksConfig = generateHooksConfig();
-    const merged = { ...existing, ...hooksConfig };
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, hooksConfig.hooks),
+    };
 
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }
 
 /**
- * Self-heal a case's hooks block so the COD-91 unconditional hook-secret gate keeps
- * accepting its hook events.
+ * Self-heal a case's Codeman-owned hooks block.
  *
  * `writeHooksConfig` only runs when a case is first CREATED. Cases created before the
  * X-Codeman-Hook-Secret header was added (COD-54, 2026-06-10) keep hook curls in their
  * settings.local.json that POST to /api/hook-event WITHOUT the secret — which, once the
- * gate requires it unconditionally (COD-91), silently 401 on a password-protected
- * install. This refreshes the hooks block so those stale curls regain the header.
+ * gate requires it unconditionally (COD-91), silently 401 on a password-protected install.
+ * Older Codeman blocks also lack the background Bash async-rewake hook. Refresh either
+ * stale shape on launch so existing cases gain both current behaviors.
  *
  * Deliberately surgical: regenerates ONLY when settings.local.json already contains
- * Codeman's own hook curls (they target `/api/hook-event`) that lack the secret header.
- * No-op when the file/hooks are absent (we never impose hooks on a user who removed
- * them), when the hooks aren't ours, or when the secret is already present — so it never
- * clobbers a user's customizations and is cheap enough to call on every Claude spawn.
+ * Codeman's own hook curls (they target `/api/hook-event`) and they are stale. No-op
+ * when the file/hooks are absent (we never impose hooks on a user who removed them) or
+ * when the hooks aren't ours, so it is cheap enough to call on every Claude spawn.
  */
-export async function refreshStaleHookSecret(casePath: string): Promise<void> {
+export async function refreshStaleCodemanHooks(casePath: string): Promise<void> {
   const settingsPath = join(casePath, '.claude', 'settings.local.json');
   if (!existsSync(settingsPath)) return;
   await withSettingsLock(settingsPath, async () => {
@@ -274,8 +456,13 @@ export async function refreshStaleHookSecret(casePath: string): Promise<void> {
     // The generated curl carries this header literal (see generateHooksConfig); its
     // absence on our own hooks means they predate COD-54 and need regenerating.
     const hasSecret = hooksJson.includes('X-Codeman-Hook-Secret');
-    if (!isOurs || hasSecret) return;
-    const merged = { ...existing, ...generateHooksConfig() };
+    const hasBackgroundWake = hooksJson.includes(BACKGROUND_WAKE_MARKER);
+    if (!isOurs || (hasSecret && hasBackgroundWake)) return;
+    const generated = generateHooksConfig();
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, generated.hooks),
+    };
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }

src/mux-interface.ts

@@ -17,6 +17,7 @@ import type {
   CodexConfig,
   EffortLevel,
   GeminiConfig,
+  AntigravityConfig,
   SessionRemote,
   SessionDocker,
 } from './types.js';
@@ -74,6 +75,7 @@ export interface CreateSessionOptions {
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
   geminiConfig?: GeminiConfig;
+  antigravityConfig?: AntigravityConfig;
   /** When restoring after reboot, resume a previous Claude conversation by its session ID */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
@@ -102,6 +104,7 @@ export interface RespawnPaneOptions {
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
   geminiConfig?: GeminiConfig;
+  antigravityConfig?: AntigravityConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (preserved across respawns). */

src/remote-hosts.ts

@@ -58,16 +58,61 @@ export async function writeRemoteCases(configDir: string, cases: RemoteCase[]):
   await writeJsonArray(configDir, remoteCasesPath(configDir), cases);
 }
 
+/**
+ * The remote user's login shell, defaulted and quoted.
+ *
+ * The default is belt-and-braces, not a live bug: an empty `$SHELL` would expand
+ * to `exec  -i -l`, which the shell reads as `exec -i` — "not found", pane dead on
+ * arrival, the #208 failure all over again (verified: `sh -c 'exec $SHELL -i -l'`
+ * with SHELL unset prints `exec: -i: not found`). In practice tmux always exports
+ * SHELL into a pane from its own `default-shell` option, so the command as USED
+ * here is safe either way (also verified). The default matters because these
+ * strings are the seed values a per-host `commands.*` override is edited from, and
+ * nothing constrains where an edited one ends up running. Quoted for a shell path
+ * containing spaces. `/bin/sh` exists on every POSIX host.
+ */
+const REMOTE_LOGIN_SHELL = '"${SHELL:-/bin/sh}"';
+
+/**
+ * Run `command` through the remote user's interactive login shell, so per-user
+ * PATH entries (~/.local/bin, ~/.opencode/bin, …) are resolved before the CLI name
+ * is looked up. ssh's remote-command execution is neither interactive nor login,
+ * so a bare `exec claude` sees only sshd's minimal default PATH and dies with
+ * "command not found" (exit 127).
+ *
+ * Shells that take neither flag (nushell, elvish, …) cannot be detected from here
+ * the way `loginShellArgs()` detects them locally, since the shell is whatever the
+ * REMOTE passwd says. A host like that is what the per-host `commands.*` override
+ * is for.
+ */
+export function remoteLoginShellCommand(command: string): string {
+  return `exec ${REMOTE_LOGIN_SHELL} -i -l -c ${shellescape(command)}`;
+}
+
 export function defaultRemoteCommandForMode(mode: SessionMode): string {
+  // Agent CLIs (claude/opencode/codex/gemini/antigravity) are typically installed
+  // under per-user paths like ~/.local/bin or ~/.opencode/bin, added to PATH only by
+  // the remote user's interactive-login shell startup files (~/.zshrc etc.). ssh's
+  // remote-command execution is neither interactive nor login, so a bare `exec
+  // claude` sees only sshd's minimal default PATH and fails with "command not
+  // found" (exit 127) — confirmed via `tmux capture-pane` on the
+  // remain-on-exit-preserved dead pane. Route through `$SHELL -i -l -c`, the same
+  // fix already used for shell mode below, so PATH is fully resolved before the
+  // CLI name is looked up.
   const commands: Record<RemoteCommandMode, string> = {
-    shell: 'exec bash -l',
+    // $SHELL, not a hardcoded bash: sshd sets it from the remote user's
+    // /etc/passwd entry, so this launches their actual login shell (zsh,
+    // fish, etc.). -i -l so it sources rc files (~/.zshrc etc.), matching
+    // the local shell-mode launch.
+    shell: `exec ${REMOTE_LOGIN_SHELL} -i -l`,
     // Mirror the LOCAL claude default so the remote agent runs non-interactively
     // (no trust-folder/permission prompt that nothing on the remote answers). The
     // per-host `commands.claude` override stays the escape hatch.
-    claude: 'exec claude --dangerously-skip-permissions',
-    opencode: 'exec opencode',
-    codex: 'exec codex',
-    gemini: 'exec gemini',
+    claude: remoteLoginShellCommand('claude --dangerously-skip-permissions'),
+    opencode: remoteLoginShellCommand('opencode'),
+    codex: remoteLoginShellCommand('codex'),
+    gemini: remoteLoginShellCommand('gemini'),
+    antigravity: remoteLoginShellCommand('agy'),
   };
   return commands[mode as RemoteCommandMode] || commands.shell;
 }
@@ -211,6 +256,69 @@ export async function checkRemoteTmuxAvailable(
   }
 }
 
+/**
+ * The CLI binary each session mode runs on the remote host. Antigravity's
+ * binary is `agy` (the mode name is not the command); shell has no CLI to
+ * probe, so it is absent.
+ */
+const REMOTE_CLI_BIN: Partial<Record<SessionMode, string>> = {
+  claude: 'claude',
+  opencode: 'opencode',
+  codex: 'codex',
+  gemini: 'gemini',
+  antigravity: 'agy',
+};
+
+/**
+ * Build the SSH command that reads the remote CLI's version (`claude --version`
+ * on the remote host). The version query is routed through
+ * `remoteLoginShellCommand` (the SAME `$SHELL -i -l -c` wrapper the real
+ * launch uses), because agent CLIs live on PATH only after the remote user's
+ * interactive-login startup files run (see defaultRemoteCommandForMode); a bare
+ * `claude --version` over ssh exits 127. Connection options come from the
+ * shared `buildSshConnectionArgs`, so the probe reaches exactly the hosts the
+ * launch can reach. Returns null for modes with no CLI (shell).
+ */
+export function buildRemoteCliVersionProbeCommand(
+  host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions,
+  mode: SessionMode
+): string | null {
+  const bin = REMOTE_CLI_BIN[mode];
+  if (!bin) return null;
+  return [
+    ...buildSshConnectionArgs(host),
+    remoteSshTarget(host),
+    shellescape(remoteLoginShellCommand(`${bin} --version`)),
+  ].join(' ');
+}
+
+/**
+ * Read the CLI version installed ON THE REMOTE HOST. Feeds Session.cliVersion
+ * for remote sessions: the deterministic local probe deliberately skips them
+ * (it would report the LOCAL host's claude), and the startup-banner scrape is
+ * unreliable (newer Claude Code builds print no banner; resumed sessions never
+ * do), which left cliVersion undefined and silently disabled wheel-forwarding
+ * to the CLI transcript (residual #154, noted in the #205 analysis). The
+ * version is parsed as the first semver in stdout, never raw output: an
+ * interactive-login shell may echo rc-file noise around it. Returns undefined
+ * on any failure. No-op under VITEST (mirrors checkRemoteTmuxAvailable).
+ */
+export async function probeRemoteCliVersion(
+  host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions,
+  mode: SessionMode
+): Promise<string | undefined> {
+  if (process.env.VITEST) return undefined;
+  const command = buildRemoteCliVersionProbeCommand(host, mode);
+  if (!command) return undefined;
+  try {
+    const { stdout } = await execAsync(command, { timeout: 15_000 });
+    const match = stdout.match(/\d+\.\d+\.\d+/);
+    return match ? match[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * COD-105 — build the SSH command that lists `codeman-*` tmux sessions on a
  * remote host's canonical `-L codeman` socket.

src/services/unified-session-service.ts

@@ -226,6 +226,16 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
   // different UUID. Backfill from the already-passed history: first try the claudeSessionId
   // join, then the newest transcript in the same workingDir. Never overwrite a non-empty
   // firstPrompt (so rows keyed to their own transcript are untouched).
+  //
+  // The workingDir guess is a last resort and MUST be skipped for any item that
+  // already has its own 'history' entry (step 1 above already gave it a real,
+  // direct scan of its own transcript). Without this guard, a history row whose
+  // OWN extraction genuinely failed (oversized first message, etc.) silently
+  // inherited the newest OTHER session's opening line from the same directory —
+  // not a blank, but actively wrong: old sessions displayed today's conversation
+  // as if it were their own. A row with no 'history' source at all (its
+  // transcript hasn't been linked/scanned under its own id yet) has no such
+  // direct attempt to prefer, so the guess remains a reasonable stand-in there.
   const firstPromptByUuid = new Map<string, string>();
   const firstPromptByWorkingDir = new Map<string, { prompt: string; ms: number }>();
   // COD-145: lastPrompt rides the same backfill (build parallel indexes; never overwrite).
@@ -254,12 +264,13 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
     }
   }
   for (const item of map.values()) {
+    const hasOwnHistoryEntry = item.sources.includes('history');
     if (!item.firstPrompt) {
       // never overwrite an existing non-empty prompt
       const byUuid = item.claudeSessionId ? firstPromptByUuid.get(item.claudeSessionId) : undefined;
       if (byUuid) {
         item.firstPrompt = byUuid;
-      } else if (item.workingDir) {
+      } else if (item.workingDir && !hasOwnHistoryEntry) {
         const byDir = firstPromptByWorkingDir.get(item.workingDir);
         if (byDir) item.firstPrompt = byDir.prompt;
       }
@@ -268,7 +279,7 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
       const byUuid = item.claudeSessionId ? lastPromptByUuid.get(item.claudeSessionId) : undefined;
       if (byUuid) {
         item.lastPrompt = byUuid;
-      } else if (item.workingDir) {
+      } else if (item.workingDir && !hasOwnHistoryEntry) {
         const byDir = lastPromptByWorkingDir.get(item.workingDir);
         if (byDir) item.lastPrompt = byDir.prompt;
       }

src/session.ts

@@ -49,10 +49,12 @@ import {
   type CodexConfig,
   type EffortLevel,
   type GeminiConfig,
+  type AntigravityConfig,
   type SessionRemote,
   type SessionDocker,
 } from './types.js';
 import { probeDockerCliVersion } from './docker-hosts.js';
+import { probeRemoteCliVersion } from './remote-hosts.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
 import { TaskTracker, type BackgroundTask } from './task-tracker.js';
 import { RalphTracker } from './ralph-tracker.js';
@@ -65,6 +67,9 @@ import {
   MAX_SESSION_TOKENS,
   execPattern,
   getClaudeCliVersion,
+  getClaudeBinaryPath,
+  spawnPtyWithHelperRepair,
+  resolveLocalShell,
 } from './utils/index.js';
 import {
   MAX_TERMINAL_BUFFER_SIZE,
@@ -140,7 +145,7 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;
 
 /** True for external-CLI run modes (non-Claude) that use their own TUI and output format. */
 export function isExternalCliMode(mode: SessionMode): boolean {
-  return mode === 'opencode' || mode === 'codex' || mode === 'gemini';
+  return mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity';
 }
 
 function getModeLabel(mode: SessionMode): string {
@@ -151,6 +156,8 @@ function getModeLabel(mode: SessionMode): string {
       return 'Codex';
     case 'gemini':
       return 'Gemini';
+    case 'antigravity':
+      return 'Antigravity';
     case 'shell':
       return 'Shell';
     case 'claude':
@@ -174,14 +181,54 @@ export function isAltScreenStripMode(mode: SessionMode): boolean {
   return mode === 'codex' || mode === 'claude' || mode === 'gemini';
 }
 
+/**
+ * Modes that need the NARROW strip: alt-screen toggles only, leaving `\x1b[3J`
+ * and the mouse-tracking DECSETs alone. Applies to every mode `isAltScreenStripMode`
+ * excludes, but ONLY when the session is tmux-backed (`useMux`).
+ *
+ * The bug (issue #205): the tmux CLIENT emits `smcup` (`\x1b[?1049h`) as its first
+ * bytes on attach, before any program has run. Unstripped, xterm.js parks in the
+ * alternate buffer for the whole session, where `baseY` is pinned at 0 (no
+ * scrollback to reach, so touch scrolling is a no-op) and xterm's own wheel handler
+ * translates the wheel into `\x1bOA`/`\x1bOB` cursor keys — which readline receives
+ * as shell history navigation. Both reported symptoms, one sequence.
+ *
+ * Why this is safe under tmux, despite the old "shell must keep the alt screen for
+ * vim/less/htop" reasoning: tmux is a full terminal emulator and NEVER forwards a
+ * pane's alt-screen toggles to its client, it repaints instead. Captured from a real
+ * attach, `\x1b[?1049h` appears exactly once (at attach) and vim/less/htop sessions
+ * inside the pane emit zero. So the only thing stripped here is tmux's own smcup.
+ *
+ * Why it is gated on `useMux`: `startShell()`/`startInteractive()` fall back to a
+ * DIRECT PTY when mux creation fails. There the inner program's `\x1b[?1049h` really
+ * does reach xterm, and stripping it would break vim/less/htop for real.
+ *
+ * Why it is narrower than the full strip: with tmux `mouse off`, a mouse-aware
+ * program in the pane (htop, vim with `set mouse=a`) still gets its DECSETs passed
+ * through to the client, so stripping those would break its mouse support. And
+ * `\x1b[3J` from a user's own `clear` is a deliberate "wipe my scrollback".
+ */
+export function isMuxAltScreenOnlyStripMode(mode: SessionMode, useMux: boolean): boolean {
+  return useMux && !isAltScreenStripMode(mode);
+}
+
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)
 
 /** PTY fallback geometry when tmux can't be queried (matches pre-#80 hardcoded values). */
 const DEFAULT_PTY_COLS = 120;
 const DEFAULT_PTY_ROWS = 40;
 const TMUX_DISPLAY_TIMEOUT_MS = 2000;
+const IS_TEST_MODE = !!process.env.VITEST;
+/**
+ * Echo transport for the test-mode PTY attach. Raw mode disables the tty line
+ * discipline, so each input byte flows back exactly once and immediately; without
+ * it, tty echo doubles every line and canonical buffering holds bytes until Enter.
+ */
+const TEST_PTY_SCRIPT = 'if (process.stdin.isTTY) process.stdin.setRawMode(true); process.stdin.pipe(process.stdout);';
 /** Delay before the in-container Claude CLI version probe (lets the container start). */
 const DOCKER_CLI_VERSION_PROBE_DELAY_MS = 3000;
+/** Delay before the over-ssh Claude CLI version probe (keeps session start off the ssh round-trip). */
+const REMOTE_CLI_VERSION_PROBE_DELAY_MS = 3000;
 
 /**
  * Ask tmux for the current window geometry of `muxName` so a re-attaching PTY
@@ -396,6 +443,8 @@ export class Session extends EventEmitter {
   private _codexConfig: CodexConfig | undefined;
   // Gemini configuration (only for mode === 'gemini')
   private _geminiConfig: GeminiConfig | undefined;
+  // Antigravity configuration (only for mode === 'antigravity')
+  private _antigravityConfig: AntigravityConfig | undefined;
   private _resumeSessionId: string | undefined;
 
   // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -482,6 +531,8 @@ export class Session extends EventEmitter {
       codexConfig?: CodexConfig;
       /** Gemini configuration (only for mode === 'gemini') */
       geminiConfig?: GeminiConfig;
+      /** Antigravity configuration (only for mode === 'antigravity') */
+      antigravityConfig?: AntigravityConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
       /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
@@ -492,6 +543,8 @@ export class Session extends EventEmitter {
       tmuxHistoryLimit?: number;
       /** Restored per-session attachment history. May include server-private external paths. */
       attachmentHistory?: SessionAttachmentHistoryItem[];
+      /** Restored wall-clock ms of the pane's last Enter (see `lastSubmitAt`). */
+      lastSubmitAt?: number;
       /** Remote execution metadata for sessions launched through SSH inside local tmux. */
       remote?: SessionRemote;
       /** Docker execution metadata for sessions launched inside a container via local tmux. */
@@ -518,6 +571,12 @@ export class Session extends EventEmitter {
     this._lastActivityAt = this.createdAt;
     // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
     this._claudeSessionId = config.resumeSessionId || this.id;
+    // Restored from state.json on boot recovery. start() resets _claudeSessionId
+    // to the launch id even when re-attaching to a mux session whose CLI has
+    // moved on (a `/clear` before the restart), so this anchor is what lets the
+    // response viewer re-derive the live conversation without waiting for the
+    // user to type again.
+    this._lastSubmitAt = config.lastSubmitAt ?? 0;
     this._mux = config.mux || null;
     this._useMux = config.useMux ?? (this._mux !== null && this._mux.isAvailable());
     this._muxSession = config.muxSession || null;
@@ -555,6 +614,11 @@ export class Session extends EventEmitter {
       this._geminiConfig = config.geminiConfig;
     }
 
+    // Apply Antigravity configuration
+    if (config.antigravityConfig) {
+      this._antigravityConfig = config.antigravityConfig;
+    }
+
     // Apply env overrides (exported at spawn, not persisted to disk).
     // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
     // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
@@ -703,6 +767,15 @@ export class Session extends EventEmitter {
     return this._muxSession?.muxName ?? null;
   }
 
+  /**
+   * True when this session's PTY is a tmux client rather than the program itself.
+   * Read by the replay-side alt-screen strip, which must apply the same
+   * `useMux` gate as the live strip (isMuxAltScreenOnlyStripMode).
+   */
+  get usesMux(): boolean {
+    return this._useMux;
+  }
+
   get totalCost(): number {
     return this._totalCost;
   }
@@ -1104,6 +1177,7 @@ export class Session extends EventEmitter {
       openCodeConfig: this._openCodeConfig,
       codexConfig: this._codexConfig,
       geminiConfig: this._geminiConfig,
+      antigravityConfig: this._antigravityConfig,
       resumeSessionId: this._resumeSessionId,
       effort: this._effort,
       // COD-118: runtime-only — surfaced so the frontend can require explicit user
@@ -1112,6 +1186,7 @@ export class Session extends EventEmitter {
       // recovery can re-attach.
       respawnBlocked: this._respawnBlocked || undefined,
       attachmentHistory: this.attachmentHistory.length > 0 ? this.attachmentHistory : undefined,
+      lastSubmitAt: this._lastSubmitAt || undefined,
       // envOverrides intentionally NOT on the public SessionState type — they must not
       // leak into SSE / GET /api/sessions broadcasts (schema allows OPENCODE_*, which
       // can carry secrets). For disk persistence, session-manager calls
@@ -1248,24 +1323,33 @@ export class Session extends EventEmitter {
       // No extra sleep — createSession() already waits for tmux readiness
     }
 
-    // Attach to the mux session via PTY
-    // Prevent tmux from letting the newest browser attach dictate global window
-    // size; accepted Codeman resize events update it explicitly below.
-    mux.setManualWindowSize?.(this._muxSession!.muxName);
+    // Integration tests need a live input/output transport without attaching to
+    // the host's tmux server or agent CLI. Production still uses the real mux.
+    if (!IS_TEST_MODE) {
+      // Prevent tmux from letting the newest browser attach dictate global window
+      // size; accepted Codeman resize events update it explicitly below.
+      mux.setManualWindowSize?.(this._muxSession!.muxName);
+    }
     // Query existing tmux window size so re-attach matches (avoids flicker from 120x40 default).
     // MUST go through the dedicated socket (mux.muxSocket); a bare `tmux display` hits the
     // default server, always fails for our socketed sessions, and silently falls back to 120x40.
-    const { cols: ptyCols, rows: ptyRows } = queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const { cols: ptyCols, rows: ptyRows } = IS_TEST_MODE
+      ? { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS }
+      : queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const attachCommand = IS_TEST_MODE ? process.execPath : mux.getAttachCommand();
+    const attachArgs = IS_TEST_MODE ? ['-e', TEST_PTY_SCRIPT] : mux.getAttachArgs(this._muxSession!.muxName);
     try {
-      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
-        name: 'xterm-256color',
-        cols: ptyCols,
-        rows: ptyRows,
-        cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
-        // COD-75: codex/gemini get COLORTERM=truecolor — mirrors buildEnvExports()
-        // in tmux-manager.ts so the attach client and the tmux session agree.
-        env: buildMuxAttachEnv(this.mode === 'codex' || this.mode === 'gemini'),
-      });
+      this.ptyProcess = spawnPtyWithHelperRepair(() =>
+        pty.spawn(attachCommand, attachArgs, {
+          name: 'xterm-256color',
+          cols: ptyCols,
+          rows: ptyRows,
+          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
+          // COD-75: codex/gemini/antigravity get COLORTERM=truecolor — mirrors buildEnvExports()
+          // in tmux-manager.ts so the attach client and the tmux session agree.
+          env: buildMuxAttachEnv(this.mode === 'codex' || this.mode === 'gemini' || this.mode === 'antigravity'),
+        })
+      );
     } catch (spawnErr) {
       console.error(`[Session] Failed to spawn PTY for ${options.spawnErrLabel}:`, spawnErr);
       this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
@@ -1329,6 +1413,7 @@ export class Session extends EventEmitter {
       openCodeConfig: this._openCodeConfig,
       codexConfig: this._codexConfig,
       geminiConfig: this._geminiConfig,
+      antigravityConfig: this._antigravityConfig,
       resumeSessionId: this._resumeSessionId,
       envOverrides: this._envOverrides,
       effort: this._effort,
@@ -1359,9 +1444,16 @@ export class Session extends EventEmitter {
     // SSE/WS stream carries them, keeping everything in the main buffer with
     // scrollback intact. These are controlled TUIs whose cursor-positioned
     // redraws overwrite only the cells they target, so non-erased rows keep
-    // their content. Gated to Codex/Claude (isAltScreenStripMode) — shell must
-    // keep the alt screen for vim/less/htop.
-    if (isAltScreenStripMode(this.mode)) {
+    // their content. Gated to Codex/Claude/Gemini (isAltScreenStripMode).
+    //
+    // Every OTHER mode (shell/opencode/antigravity) gets the NARROW strip when it
+    // is tmux-backed: alt-screen toggles only, because the sequence that breaks
+    // scrollback there is tmux's own client-side smcup at attach, not anything the
+    // program in the pane emitted (issue #205, see isMuxAltScreenOnlyStripMode).
+    // 3J and the mouse DECSETs stay, so `clear` and mouse-aware TUIs keep working.
+    const fullStrip = isAltScreenStripMode(this.mode);
+    const altOnlyStrip = !fullStrip && isMuxAltScreenOnlyStripMode(this.mode, this._useMux);
+    if (fullStrip || altOnlyStrip) {
       // Reassemble sequences split across PTY chunk boundaries first: a chunk
       // ending mid-sequence ('\x1b[?104' now, '9h' next) would slip past the
       // strip below and leave xterm stuck in the scrollback-less alt buffer
@@ -1377,13 +1469,15 @@ export class Session extends EventEmitter {
         data = data.slice(0, -splitTail[0].length);
         if (!data) return;
       }
-      data = data
-        // eslint-disable-next-line no-control-regex
-        .replace(/\x1b\[\?(?:47|1047|1049)[hl]/g, '')
-        // 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, '');
+      // eslint-disable-next-line no-control-regex
+      data = data.replace(/\x1b\[\?(?:47|1047|1049)[hl]/g, '');
+      if (fullStrip) {
+        data = data
+          // 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, '');
+      }
     }
 
     // Scan terminal output for attachment requests. `codeman://attach?...` is an
@@ -1443,8 +1537,8 @@ export class Session extends EventEmitter {
     // never show it — which left cliVersion undefined and silently disabled
     // wheel-forwarding to Claude's own transcript (the only route to history in
     // repaint/alt-screen mode; issue #154). Remote sessions run claude on
-    // another host, so a local probe wouldn't reflect their version — skip them
-    // and let the banner scrape handle those. Cached process-wide, best-effort.
+    // another host, so a local probe wouldn't reflect their version; they get
+    // their own over-ssh probe below. Cached process-wide, best-effort.
     if (this.mode === 'claude' && !this._remote && !this._docker && !this._cliVersion) {
       const probedVersion = getClaudeCliVersion();
       if (probedVersion) {
@@ -1483,6 +1577,32 @@ export class Session extends EventEmitter {
       }, DOCKER_CLI_VERSION_PROBE_DELAY_MS);
     }
 
+    // Remote sessions run claude on ANOTHER HOST, so neither the local nor the
+    // docker probe applies, and the banner-scrape fallback they were left with
+    // is the unreliable path #154 was filed for, so remote Claude cases silently
+    // never got wheel-forwarding (noted in the #205 analysis). Probe over ssh,
+    // deferred so session start never waits on the ssh round-trip.
+    if (this.mode === 'claude' && this._remote && !this._cliVersion) {
+      const remoteMeta = this._remote;
+      setTimeout(() => {
+        if (this._isStopped || this._cliVersion) return;
+        void probeRemoteCliVersion(remoteMeta, this.mode)
+          .then((version) => {
+            if (!version || this._isStopped || this._cliVersion) return;
+            this._cliVersion = version;
+            this.emit('cliInfoUpdated', {
+              version: this._cliVersion,
+              model: this._cliModel,
+              accountType: this._cliAccountType,
+              latestVersion: this._cliLatestVersion,
+            });
+          })
+          .catch(() => {
+            /* best-effort */
+          });
+      }, REMOTE_CLI_VERSION_PROBE_DELAY_MS);
+    }
+
     // If mux wrapping is enabled, create or attach to a mux session
     if (this._useMux && this._mux) {
       try {
@@ -1501,6 +1621,7 @@ export class Session extends EventEmitter {
             openCodeConfig: this._openCodeConfig,
             codexConfig: this._codexConfig,
             geminiConfig: this._geminiConfig,
+            antigravityConfig: this._antigravityConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
@@ -1582,18 +1703,24 @@ export class Session extends EventEmitter {
       if (this.mode === 'gemini') {
         throw new Error('Gemini sessions require tmux. Direct PTY fallback is not supported.');
       }
+      // Antigravity sessions require tmux for env override injection via setenv
+      if (this.mode === 'antigravity') {
+        throw new Error('Antigravity sessions require tmux. Direct PTY fallback is not supported.');
+      }
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab
         const args = buildInteractiveArgs(this.id, this._claudeMode, this._model, this._allowedTools, this._effort);
-        this.ptyProcess = pty.spawn('claude', args, {
-          name: 'xterm-256color',
-          cols: 120,
-          rows: 40,
-          cwd: this.workingDir,
-          // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
-          env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
-        });
+        this.ptyProcess = spawnPtyWithHelperRepair(() =>
+          pty.spawn(getClaudeBinaryPath(), args, {
+            name: 'xterm-256color',
+            cols: 120,
+            rows: 40,
+            cwd: this.workingDir,
+            // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+            env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
+          })
+        );
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn Claude PTY:', spawnErr);
         this._status = 'stopped';
@@ -1859,8 +1986,9 @@ export class Session extends EventEmitter {
 
     this._resetBuffers();
 
-    // Use user's default shell or bash
-    const shell = process.env.SHELL || '/bin/bash';
+    // Use user's default shell, falling back to a shell that actually exists.
+    // Shared with the tmux pane command so both paths launch the same binary.
+    const shell = resolveLocalShell();
     console.log(
       '[Session] Starting shell session with:',
       shell + (this._useMux ? ` (with ${this._mux!.backend})` : '')
@@ -1916,13 +2044,15 @@ export class Session extends EventEmitter {
     // Fallback to direct PTY if mux is not used
     if (!this.ptyProcess) {
       try {
-        this.ptyProcess = pty.spawn(shell, [], {
-          name: 'xterm-256color',
-          cols: 120,
-          rows: 40,
-          cwd: this.workingDir,
-          env: buildShellEnv(this.id),
-        });
+        this.ptyProcess = spawnPtyWithHelperRepair(() =>
+          pty.spawn(shell, [], {
+            name: 'xterm-256color',
+            cols: 120,
+            rows: 40,
+            cwd: this.workingDir,
+            env: buildShellEnv(this.id),
+          })
+        );
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn shell PTY:', spawnErr);
         this._status = 'stopped';
@@ -2022,14 +2152,16 @@ export class Session extends EventEmitter {
         const args = buildPromptArgs(prompt, model, this._claudeMode, this._allowedTools);
 
         try {
-          this.ptyProcess = pty.spawn('claude', args, {
-            name: 'xterm-256color',
-            cols: 120,
-            rows: 40,
-            cwd: this.workingDir,
-            // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
-            env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
-          });
+          this.ptyProcess = spawnPtyWithHelperRepair(() =>
+            pty.spawn(getClaudeBinaryPath(), args, {
+              name: 'xterm-256color',
+              cols: 120,
+              rows: 40,
+              cwd: this.workingDir,
+              // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+              env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
+            })
+          );
         } catch (spawnErr) {
           console.error('[Session] Failed to spawn Claude PTY for runPrompt:', spawnErr);
           this.emit(
@@ -2498,26 +2630,28 @@ export class Session extends EventEmitter {
    * ```
    */
   write(data: string): void {
-    this._trackCodexSubmit(data);
+    this._trackSubmit(data);
     if (this.ptyProcess) {
       this.ptyProcess.write(data);
     }
   }
 
-  // ── Codex thread tracking ─────────────────────────────────────────────
-  // When a codex pane last submitted a message (Enter). The response-viewer
-  // correlates this against ~/.codex/history.jsonl entry timestamps to find
-  // the thread the pane is ACTUALLY on — the only signal that survives
-  // /resume, /new and /fork typed inside the codex TUI itself.
-  private _codexLastSubmitAt = 0;
+  // ── Conversation tracking ─────────────────────────────────────────────
+  // When this pane last submitted a message (Enter). The response-viewer
+  // correlates this against the CLI's own history.jsonl entry timestamps to
+  // find the conversation the pane is ACTUALLY on — the only signal that
+  // survives /clear, /resume, /new and /fork typed inside the TUI itself,
+  // none of which announce themselves on the PTY's stdout.
+  private _lastSubmitAt = 0;
 
-  get codexLastSubmitAt(): number {
-    return this._codexLastSubmitAt;
+  /** Wall-clock ms of this pane's last Enter; 0 if it has never submitted. */
+  get lastSubmitAt(): number {
+    return this._lastSubmitAt;
   }
 
-  private _trackCodexSubmit(data: string): void {
-    if (this.mode === 'codex' && (data.includes('\r') || data.includes('\n'))) {
-      this._codexLastSubmitAt = Date.now();
+  private _trackSubmit(data: string): void {
+    if (data.includes('\r') || data.includes('\n')) {
+      this._lastSubmitAt = Date.now();
     }
   }
 
@@ -2574,7 +2708,7 @@ export class Session extends EventEmitter {
    * ```
    */
   async writeViaMux(data: string): Promise<boolean> {
-    this._trackCodexSubmit(data);
+    this._trackSubmit(data);
     if (this._mux && this._muxSession) {
       return this._mux.sendInput(this.id, data);
     }
@@ -2683,7 +2817,7 @@ export class Session extends EventEmitter {
     if (this.ptyProcess && (dimsChanged || options.force)) {
       this._ptyCols = cols;
       this._ptyRows = rows;
-      if (this._mux && this._muxSession) {
+      if (!IS_TEST_MODE && this._mux && this._muxSession) {
         this._mux.resizeWindow?.(this._muxSession.muxName, cols, rows);
       }
       this.ptyProcess.resize(cols, rows);

src/tmux-manager.ts

@@ -43,12 +43,18 @@ import {
   type CodexConfig,
   type EffortLevel,
   type GeminiConfig,
+  type AntigravityConfig,
   type SessionRemote,
   type SessionDocker,
   type DockerCommandMode,
 } from './types.js';
 import { buildEffortCliArgs } from './session-cli-builder.js';
-import { buildSshConnectionArgs, defaultRemoteCommandForMode, remoteSshTarget } from './remote-hosts.js';
+import {
+  buildSshConnectionArgs,
+  defaultRemoteCommandForMode,
+  remoteLoginShellCommand,
+  remoteSshTarget,
+} from './remote-hosts.js';
 import {
   buildDockerBaseArgs,
   buildDockerCreateArgs,
@@ -69,6 +75,9 @@ import {
   resolveOpenCodeDir,
   resolveCodexDir,
   resolveGeminiDir,
+  resolveAntigravityDir,
+  resolveLocalShell,
+  loginShellArgs,
 } from './utils/index.js';
 import type {
   TerminalMultiplexer,
@@ -640,6 +649,10 @@ export function buildCodexCommand(config?: CodexConfig): string {
     parts.push('--dangerously-bypass-approvals-and-sandbox');
   }
 
+  if (config?.animations !== undefined) {
+    parts.push('--config', `tui.animations=${config.animations ? 'true' : 'false'}`);
+  }
+
   if (config?.model) {
     const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
     if (safeModel) parts.push('--model', safeModel);
@@ -682,6 +695,34 @@ function buildGeminiCommand(config?: GeminiConfig): string {
   return parts.join(' ');
 }
 
+/**
+ * Build the Antigravity CLI (agy) command with appropriate flags.
+ *
+ * Unlike gemini's yolo default, `--dangerously-skip-permissions` is only added
+ * when the config explicitly asks for it (the frontend sends it for parity with
+ * Codeman's Claude default; the multi-user clamp strips it for non-granted owners,
+ * and an ABSENT config stays at agy's own prompting default — safe like Codex).
+ */
+function buildAntigravityCommand(config?: AntigravityConfig): string {
+  const parts = ['agy'];
+
+  if (config?.dangerouslySkipPermissions) {
+    parts.push('--dangerously-skip-permissions');
+  }
+
+  if (config?.model) {
+    const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  if (config?.resumeConversationId) {
+    const safeId = /^[a-zA-Z0-9._-]+$/.test(config.resumeConversationId) ? config.resumeConversationId : undefined;
+    if (safeId) parts.push('--conversation', safeId);
+  }
+
+  return parts.join(' ');
+}
+
 /**
  * Build the spawn command for any session mode.
  * Shared by createSession() and respawnPane() to avoid duplication.
@@ -709,6 +750,7 @@ export function buildSpawnCommand(options: {
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
   geminiConfig?: GeminiConfig;
+  antigravityConfig?: AntigravityConfig;
   resumeSessionId?: string;
   effort?: EffortLevel;
 }): string {
@@ -739,7 +781,24 @@ export function buildSpawnCommand(options: {
   if (options.mode === 'gemini') {
     return buildGeminiCommand(options.geminiConfig);
   }
-  return '$SHELL';
+  if (options.mode === 'antigravity') {
+    return buildAntigravityCommand(options.antigravityConfig);
+  }
+  // #208: NOT the literal '$SHELL'. This string is embedded in the `bash -c "…"`
+  // argument of the respawn-pane line, which execSync runs through `/bin/sh -c`,
+  // so a `$SHELL` here is expanded by the SERVER process's shell against the
+  // SERVER process's env — empty in containers and system systemd units, leaving
+  // the pane command ending in a dangling `&&` ("syntax error: unexpected end of
+  // file", pane dead on arrival). Resolve it in Node and quote the result.
+  // #209: launch it as a LOGIN shell, which is what tmux itself does for a pane
+  // with no `default-command`, so a Codeman shell tab matches a hand-started tmux
+  // one. That is what picks up /etc/profile and /etc/profile.d/* — a systemd
+  // --user service never sourced them, so its PATH is what every pane inherited.
+  // The flags come from loginShellArgs() rather than being hardcoded: they are
+  // appended to a path that ultimately comes from the passwd entry, and a shell
+  // that rejects an unknown flag exits on the spot, which is #208 all over again.
+  const shell = resolveLocalShell();
+  return `${shellescape(shell)}${loginShellArgs(shell)}`;
 }
 
 /**
@@ -811,13 +870,14 @@ export function buildRemoteLaunchCommand(options: {
   // hardcoding --dangerously-skip-permissions, so a non-granted multi-user user's
   // downgraded 'auto' actually reaches the remote agent (the default command otherwise
   // ignored claudeMode). A per-host `commands.claude` override stays authoritative
-  // (admin's explicit choice). For the DEFAULT single-user config (skip), the emitted
-  // command is byte-identical to before. Non-claude modes are unchanged.
+  // (admin's explicit choice). Wrapped in `$SHELL -i -l -c` for the same reason as
+  // `defaultRemoteCommandForMode`: `claude` lives under a per-user PATH entry that
+  // only an interactive login shell resolves (see that function's comment).
   const override = remote.commands?.[mode];
   const modeCommand = override
     ? override
     : mode === 'claude'
-      ? `exec claude${buildClaudePermissionFlags(claudeMode, allowedTools)}`
+      ? remoteLoginShellCommand(`claude${buildClaudePermissionFlags(claudeMode, allowedTools)}`)
       : defaultRemoteCommandForMode(mode);
   const remoteName = remoteTmuxSessionName(sessionId);
 
@@ -843,6 +903,24 @@ export function buildRemoteLaunchCommand(options: {
     // Per-session scoped (`set -t <name>`, matching #145's hardening) so a shared
     // remote tmux server's other sessions keep their own sizing behavior.
     `set -t ${remoteName} window-size latest`,
+    // #210: keep a CRASHED pane so the failure is still on screen. Without this,
+    // tmux destroys the pane -> window -> session (and, being the only session,
+    // the whole remote server) the instant the pane command exits, which tears the
+    // local `ssh -t` attach down with it; reconnect's `-A` then builds a fresh
+    // session and the cycle can repeat as a flap loop with no evidence surviving.
+    // That is how the exit-127 PATH bug fixed above stayed invisible.
+    //
+    // `failed`, NOT `on`: `on` keeps the pane on a CLEAN exit too, so typing
+    // `exit` in a remote shell leaves a dead pane behind, the session outlives it,
+    // and the next launch's `-A` reattaches to that corpse ("Pane is dead (status
+    // 0)") instead of starting a shell — verified against a real tmux. `failed`
+    // keeps the pane only on a non-zero exit, which is exactly the diagnostic case.
+    //
+    // LAST in the chain on purpose: tmux aborts the remaining commands of a `\;`
+    // sequence once one errors (also verified), and `failed` needs tmux >= 3.2 on
+    // the REMOTE host. Trailing, a rejection costs only this option; leading, it
+    // would silently drop status/mouse/prefix/escape-time/window-size with it.
+    `set -t ${remoteName} remain-on-exit failed`,
   ].join(' \\; ');
 
   // ssh runs its trailing args through the remote login shell, so the entire
@@ -904,7 +982,7 @@ export function dockerTmuxSessionName(sessionId: string): string {
 const RESUME_ID_SAFE = /^[A-Za-z0-9._-]+$/;
 
 /**
- * Append the CLI-specific resume flag to a pane command (codex/gemini). Only fires
+ * Append the CLI-specific resume flag to a pane command (codex/gemini/antigravity). Only fires
  * when the in-container tmux is RE-CREATED (`new-session -A` makes the flag inert
  * on a live reattach), i.e. exactly when the previous live agent was lost and we
  * want to resume the conversation from the bind-mounted transcript. Claude mode
@@ -917,6 +995,8 @@ function appendResumeFlag(modeCommand: string, mode: SessionMode, resumeId: stri
       return `${modeCommand} --resume ${resumeId}`;
     case 'codex':
       return `${modeCommand} resume ${resumeId}`;
+    case 'antigravity':
+      return `${modeCommand} --conversation ${resumeId}`;
     default:
       return modeCommand; // shell / opencode: no resume
   }
@@ -1485,8 +1565,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const exports = [
       'export LANG=en_US.UTF-8',
       'export LC_ALL=en_US.UTF-8',
-      mode === 'codex' || mode === 'gemini' ? 'export COLORTERM=truecolor' : 'unset COLORTERM',
-      ...(mode === 'codex' || mode === 'gemini' ? ['unset NO_COLOR'] : []),
+      mode === 'codex' || mode === 'gemini' || mode === 'antigravity'
+        ? 'export COLORTERM=truecolor'
+        : 'unset COLORTERM',
+      ...(mode === 'codex' || mode === 'gemini' || mode === 'antigravity' ? ['unset NO_COLOR'] : []),
       // Stamp each Codex pane with a unique originator so the response-viewer
       // can locate THIS pane's rollout exactly — codex writes the value into
       // session_meta.originator of every rollout it creates. Without it,
@@ -1569,6 +1651,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       const dir = resolveGeminiDir();
       return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
     }
+    if (mode === 'antigravity') {
+      const dir = resolveAntigravityDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
     return { pathExport: '', dir: null };
   }
 
@@ -1616,6 +1702,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       codexConfig,
       geminiConfig,
+      antigravityConfig,
       resumeSessionId,
       envOverrides,
       effort,
@@ -1667,6 +1754,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (mode === 'gemini' && !cliDir) {
       throw new Error('Gemini CLI not found. Install with: npm install -g @google/gemini-cli');
     }
+    if (mode === 'antigravity' && !cliDir) {
+      throw new Error(
+        'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
+      );
+    }
 
     const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
@@ -1679,6 +1771,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       codexConfig,
       geminiConfig,
+      antigravityConfig,
       resumeSessionId,
       effort,
     });
@@ -1901,6 +1994,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       codexConfig,
       geminiConfig,
+      antigravityConfig,
       resumeSessionId,
       envOverrides,
       effort,
@@ -1938,6 +2032,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       codexConfig,
       geminiConfig,
+      antigravityConfig,
       resumeSessionId,
       effort,
     });

src/transcript-watcher.ts

@@ -40,6 +40,7 @@ interface TranscriptContentBlock {
   text?: string;
   name?: string;
   input?: Record<string, unknown>;
+  tool_use_id?: string;
   content?: string;
   is_error?: boolean;
 }
@@ -328,10 +329,7 @@ export class TranscriptWatcher extends EventEmitter {
         this.handleResultEntry(entry);
         break;
       case 'user':
-        // User message means new turn, reset some state
-        this.state.isComplete = false;
-        this.state.hasError = false;
-        this.state.errorMessage = null;
+        this.handleUserEntry(entry);
         break;
       case 'system':
         // System messages are informational
@@ -360,23 +358,42 @@ export class TranscriptWatcher extends EventEmitter {
           this.state.currentTool = block.name;
           this.emit('transcript:tool_start', block.name);
         } else if (block.type === 'tool_result') {
-          // Tool completed
-          const wasError = block.is_error === true;
-          const toolName = this.state.currentTool;
-          this.state.toolExecuting = false;
-          this.state.currentTool = null;
-          if (toolName) {
-            this.emit('transcript:tool_end', toolName, wasError);
-          }
-          if (wasError && block.content) {
-            this.state.hasError = true;
-            this.state.errorMessage = String(block.content).slice(0, 200);
-          }
+          this.handleToolResult(block);
         }
       }
     }
   }
 
+  private handleUserEntry(entry: TranscriptEntry): void {
+    // A user-authored prompt starts a turn, while Claude tool results also use
+    // user entries. Reset turn state first, then close any completed tool.
+    this.state.isComplete = false;
+    this.state.hasError = false;
+    this.state.errorMessage = null;
+
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'tool_result') {
+        this.handleToolResult(block);
+      }
+    }
+  }
+
+  private handleToolResult(block: TranscriptContentBlock): void {
+    const wasError = block.is_error === true;
+    const toolName = this.state.currentTool;
+    this.state.toolExecuting = false;
+    this.state.currentTool = null;
+    if (toolName) {
+      this.emit('transcript:tool_end', toolName, wasError);
+    }
+    if (wasError && block.content) {
+      this.state.hasError = true;
+      this.state.errorMessage = String(block.content).slice(0, 200);
+    }
+  }
+
   private handleResultEntry(entry: TranscriptEntry): void {
     // Result entry indicates completion
     this.state.isComplete = true;

src/tunnel-manager.ts

@@ -15,10 +15,8 @@
 
 import { EventEmitter } from 'node:events';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
+import { resolveCloudflaredPath } from './utils/cloudflared-resolver.js';
 import {
   QR_TOKEN_TTL_MS,
   QR_TOKEN_GRACE_MS,
@@ -95,23 +93,10 @@ export class TunnelManager extends EventEmitter {
   private resolveCloudflared(): string | null {
     if (this.cloudflaredPath) return this.cloudflaredPath;
 
-    // Check ~/.local/bin first (common user install location)
-    const localBin = join(homedir(), '.local', 'bin', 'cloudflared');
-    if (existsSync(localBin)) {
-      this.cloudflaredPath = localBin;
-      return localBin;
-    }
-
-    // Check /usr/local/bin
-    const usrLocalBin = '/usr/local/bin/cloudflared';
-    if (existsSync(usrLocalBin)) {
-      this.cloudflaredPath = usrLocalBin;
-      return usrLocalBin;
-    }
-
-    // Fall back to PATH
-    this.cloudflaredPath = 'cloudflared';
-    return 'cloudflared';
+    // Shared with the welcome-screen availability check, so the button and the
+    // spawn can never disagree about where cloudflared lives.
+    this.cloudflaredPath = resolveCloudflaredPath() ?? 'cloudflared';
+    return this.cloudflaredPath;
   }
 
   /** Clear all pending timers */

src/types/common.ts

@@ -9,6 +9,7 @@
  * - CleanupRegistration / CleanupResourceType — entries for the centralized CleanupManager
  * - NiceConfig / DEFAULT_NICE_CONFIG — process priority settings for `nice`/`ionice`
  * - ProcessStats — memory/CPU/child-count snapshot for resource monitoring
+ * - FilesystemBrowseData — bounded path-picker directory listing returned to the web UI
  */
 
 /**
@@ -68,6 +69,50 @@ export interface ProcessStats {
   updatedAt: number;
 }
 
+/** A selectable entry returned by the filesystem path-picker API. */
+export type FilesystemPreviewKind = 'image' | 'text' | 'document';
+
+export interface FilesystemBrowseEntry {
+  name: string;
+  path: string;
+  type: 'file' | 'directory';
+  size?: number;
+  symlink?: boolean;
+  previewKind?: FilesystemPreviewKind;
+}
+
+/** A named root the path picker may browse without escaping its allowlist. */
+export interface FilesystemBrowseRoot {
+  label: string;
+  path: string;
+}
+
+/** Response payload for `GET /api/filesystem/browse`. */
+export interface FilesystemBrowseData {
+  path: string;
+  parent: string | null;
+  root: string;
+  roots: FilesystemBrowseRoot[];
+  entries: FilesystemBrowseEntry[];
+  truncated: boolean;
+}
+
+/** Response payload for `PUT /api/sessions/:id/file-content` (File Viewer edit mode). */
+export interface FileWriteData {
+  /** Workspace-relative path as submitted */
+  path: string;
+  /** Size of the written content in bytes */
+  size: number;
+  /** mtime of the file after the write */
+  mtimeMs: number;
+  /** sha256 hex of the written bytes — the client's next baseHash */
+  hash: string;
+  /** Line count of the written content */
+  totalLines: number;
+  /** Line-ending style that was applied */
+  eol: 'lf' | 'crlf';
+}
+
 export type CleanupResourceType = 'timer' | 'interval' | 'watcher' | 'listener' | 'stream';
 
 /**

src/types/index.ts

@@ -70,3 +70,4 @@ export * from './update.js';
 export * from './workflow-run.js';
 export * from './search.js';
 export * from './user.js';
+export * from './webview.js';

src/types/session.ts

@@ -8,12 +8,13 @@
  * - SessionConfig — creation-time config (id, workingDir, createdAt)
  * - SessionOutput — captured stdout/stderr/exitCode
  * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
- * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' (which CLI backend)
+ * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' (which CLI backend)
  * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools')
  * - SessionColor — visual differentiation color
  * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
  * - CodexConfig — Codex (OpenAI CLI)-specific settings (model, resumeSessionId)
  * - GeminiConfig — Gemini CLI-specific settings (model, approvalMode, resumeSession)
+ * - AntigravityConfig — Antigravity CLI (agy) settings (model, dangerouslySkipPermissions, resumeConversationId)
  *
  * Cross-domain relationships:
  * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
@@ -42,9 +43,12 @@ export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
 export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools';
 
 /** Session mode: which CLI backend a session runs */
-export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini';
+export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity';
 
-export type RemoteCommandMode = Extract<SessionMode, 'shell' | 'claude' | 'opencode' | 'codex' | 'gemini'>;
+export type RemoteCommandMode = Extract<
+  SessionMode,
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity'
+>;
 
 /**
  * Advanced SSH connection options shared by RemoteHost and SessionRemote.
@@ -150,7 +154,10 @@ export interface RemoteSessionInfo {
 // into the same long-lived container. See `docs/docker-cases-plan.md`.
 
 /** Which CLI backends a Docker case can run (same set as remote). */
-export type DockerCommandMode = Extract<SessionMode, 'shell' | 'claude' | 'opencode' | 'codex' | 'gemini'>;
+export type DockerCommandMode = Extract<
+  SessionMode,
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity'
+>;
 
 /** Container engine. Docker and Podman differ in the uid/userns + host-gateway alias. */
 export type DockerEngine = 'docker' | 'podman';
@@ -298,6 +305,8 @@ export interface CodexConfig {
   resumeSessionId?: string;
   /** Bypass approval prompts (passes --dangerously-bypass-approvals-and-sandbox) */
   dangerouslyBypassApprovals?: boolean;
+  /** Enable Codex's decorative TUI animations. Disable to reduce remote terminal redraws. */
+  animations?: boolean;
   /** Browser rendering strategy for Codex sessions. Hybrid TUI is the only supported mode. */
   renderMode?: CodexRenderMode;
 }
@@ -312,6 +321,16 @@ export interface GeminiConfig {
   resumeSession?: string;
 }
 
+/** Antigravity CLI (agy) session configuration */
+export interface AntigravityConfig {
+  /** Model identifier. Passed via --model. */
+  model?: string;
+  /** Auto-approve all tool permission requests (passes --dangerously-skip-permissions). Absent = agy's default prompting. */
+  dangerouslySkipPermissions?: boolean;
+  /** Resume a previous conversation by ID (passed via --conversation). */
+  resumeConversationId?: string;
+}
+
 /**
  * Configuration for creating a new session
  */
@@ -453,12 +472,23 @@ export interface SessionState {
   codexConfig?: CodexConfig;
   /** Gemini-specific configuration (only for mode === 'gemini') */
   geminiConfig?: GeminiConfig;
+  /** Antigravity-specific configuration (only for mode === 'antigravity') */
+  antigravityConfig?: AntigravityConfig;
   /** Claude conversation session ID to resume after reboot (set by restore script) */
   resumeSessionId?: string;
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
   effort?: EffortLevel;
   /** Sanitized per-session attachment history. */
   attachmentHistory?: SessionAttachmentHistoryItem[];
+  /**
+   * Wall-clock ms of this pane's last Enter (Session.lastSubmitAt). Persisted
+   * because it is the response-viewer's only anchor for re-deriving the pane's
+   * live conversation after a Codeman restart: `start()` resets
+   * `claudeSessionId` to the launch id even when re-attaching to a mux session
+   * whose CLI has since moved on via `/clear`, and the correlation cannot run
+   * again until the pane's own Enter is known.
+   */
+  lastSubmitAt?: number;
   /**
    * PTY-exit circuit breaker tripped — respawn blocked until an explicit restart
    * (COD-118). Runtime-only: never restored on boot (fresh server = fresh breaker).

src/types/webview.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Web tab (dashboard) types.
+ *
+ * A "webview" is a saved URL that Codeman renders as a tab alongside agent
+ * sessions: Grafana on :3000, a Uptime-Kuma on :4000, an internal status page.
+ * It is deliberately NOT a sixth `SessionMode`, it has no PTY, no tmux, no
+ * respawn and no idle detection. Same reasoning that keeps Docker and remote-SSH
+ * as case overlays rather than modes.
+ *
+ * Key exports:
+ * - Webview, the persisted record (`~/.codeman/webviews.json`).
+ * - WebviewEmbedMode, 'proxy' (served through Codeman's origin) or 'direct'
+ *   (a plain cross-origin iframe, only viable for HTTPS targets that allow framing).
+ * - WebviewProbe, the result of the server-side reachability/framing probe.
+ * - WebviewOpenData, what `POST /api/webviews/:id/open` hands the browser.
+ *
+ * No I/O here. Persistence lives in `src/webview-store.ts`, capability minting in
+ * `src/webview-capabilities.ts`, the proxy helpers in `src/web/webview-proxy.ts`.
+ */
+
+/**
+ * How the browser should embed a webview.
+ *
+ * - `proxy`: the iframe points at `/webview/<capability>/` on Codeman's own
+ *   origin and the server relays to the target. Required whenever the target is
+ *   plain HTTP (an HTTPS Codeman page cannot embed it: mixed content) or refuses
+ *   framing via `X-Frame-Options` / `frame-ancestors`.
+ * - `direct`: the iframe points at the target URL itself. Cheaper, but only works
+ *   for HTTPS targets that permit framing, and needs the target origin added to
+ *   the page CSP's `frame-src`.
+ */
+export type WebviewEmbedMode = 'proxy' | 'direct';
+
+/** A saved dashboard, persisted to `~/.codeman/webviews.json`. */
+export interface Webview {
+  id: string;
+  /** Display name shown on the tab. */
+  name: string;
+  /** Absolute target URL. `http:` / `https:` only, never with embedded credentials. */
+  url: string;
+  /** Optional single-glyph tab icon (emoji or letter). */
+  icon?: string;
+  /** Default embed strategy for this dashboard. */
+  embedMode: WebviewEmbedMode;
+  /**
+   * When false (the default) the iframe is sandboxed WITHOUT `allow-same-origin`,
+   * so a proxied page runs in an opaque origin and cannot read the Codeman page or
+   * call its API. Setting this to true trades that isolation for the page's own
+   * cookies/localStorage, only for dashboards the user fully trusts.
+   */
+  trusted: boolean;
+  /** Multi-user owner (username). Undefined in single-user mode. */
+  owner?: string;
+  createdAt: number;
+  lastOpenedAt?: number;
+}
+
+/** Result of the server-side probe used by the "Test" button in the editor. */
+export interface WebviewProbe {
+  /** True when the server could complete an HTTP request to the target. */
+  reachable: boolean;
+  /** Upstream status code, when a response came back. */
+  status?: number;
+  /** Raw `X-Frame-Options` value, if the target sent one. */
+  xFrameOptions?: string;
+  /** The `frame-ancestors` directive extracted from the target's CSP, if any. */
+  frameAncestors?: string;
+  /** True when the target permits being framed cross-origin by this Codeman. */
+  framable: boolean;
+  /** Strategy the UI should default to for this URL. */
+  recommendedMode: WebviewEmbedMode;
+  /** Human-readable explanation of the recommendation (or the failure). */
+  reason: string;
+}
+
+/** Payload of `POST /api/webviews/:id/open`. */
+export interface WebviewOpenData {
+  /** The webview being opened (echoed so the client can refresh its copy). */
+  webview: Webview;
+  /**
+   * Same-origin path the iframe should load. Present for `proxy` mode only;
+   * `direct` mode uses `webview.url` instead.
+   */
+  embedUrl?: string;
+  /** Epoch ms at which the capability behind `embedUrl` stops working. */
+  expiresAt?: number;
+}

src/utils/antigravity-cli-resolver.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Resolve the Antigravity CLI (`agy`) binary across common install paths.
+ *
+ * Mirrors gemini-cli-resolver.ts. Google's installer (antigravity.google/cli/install.sh)
+ * places the binary at ~/.local/bin/agy; the other locations cover manual installs.
+ *
+ * @module utils/antigravity-cli-resolver
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.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(), 'bin'),
+];
+
+/** Cached directory containing the agy binary (empty string = searched but not found) */
+let _antigravityDir: string | null = null;
+
+/**
+ * Finds the directory containing the `agy` binary.
+ * Checks `which agy` first, then falls back to common install locations.
+ *
+ * @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;
+}
+
+/**
+ * Check if the Antigravity CLI is available on the system.
+ */
+export function isAntigravityAvailable(): boolean {
+  return resolveAntigravityDir() !== null;
+}

src/utils/claude-cli-resolver.ts

@@ -26,6 +26,15 @@ const CLAUDE_SEARCH_DIRS = [
 /** Cached directory containing the claude binary (empty string = searched but not found) */
 let _claudeDir: string | null = null;
 
+/**
+ * Returns true if the Claude CLI binary can be located (via `which` or one of
+ * the common install directories). Mirrors `isGeminiAvailable`/`isAntigravityAvailable`/`isOpenCodeAvailable`/
+ * `isCodexAvailable` in the sibling resolvers.
+ */
+export function isClaudeAvailable(): boolean {
+  return findClaudeDir() !== null;
+}
+
 /**
  * Finds the directory containing the `claude` binary.
  * Checks `which claude` first, then falls back to common install locations.
@@ -59,6 +68,21 @@ export function findClaudeDir(): string | null {
   return null;
 }
 
+/**
+ * Returns an absolute path to the `claude` binary, falling back to the bare
+ * name `'claude'` when it cannot be located (so PATH resolution still gets a
+ * chance).
+ *
+ * Preferred over passing `'claude'` to `pty.spawn()`: a PTY child resolves the
+ * command against the environment it is handed, and an install that lives in
+ * `~/.local/bin` or `~/.claude/local` is frequently absent from the PATH the
+ * server process inherited (issue #6).
+ */
+export function getClaudeBinaryPath(): string {
+  const dir = findClaudeDir();
+  return dir ? join(dir, 'claude') : 'claude';
+}
+
 /** Cached augmented PATH string */
 let _augmentedPath: string | null = null;
 

src/utils/cloudflared-resolver.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Resolve the `cloudflared` binary across common install paths.
+ *
+ * Mirrors the CLI resolvers (antigravity-cli-resolver.ts et al), for the same reason
+ * they exist: the welcome screen should not offer a button whose only possible
+ * outcome is an error toast.
+ *
+ * The search list is deliberately the SAME one `TunnelManager.resolveCloudflared()`
+ * has always used, and that method now delegates here so the two can never drift.
+ * The difference is the fallback: this module answers "is it installed?" honestly
+ * with null, while the tunnel manager keeps falling back to the bare name so a
+ * cloudflared that only exists somewhere on the tunnel process's PATH still
+ * starts. A stricter answer there would turn a working tunnel into a refusal.
+ *
+ * @module utils/cloudflared-resolver
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+
+/** Common directories where the cloudflared binary may be installed */
+const CLOUDFLARED_SEARCH_DIRS = [join(homedir(), '.local', 'bin'), '/usr/local/bin'];
+
+/** Cached path to the cloudflared binary (empty string = searched but not found) */
+let _cloudflaredPath: string | null = null;
+
+/**
+ * Finds the `cloudflared` binary.
+ *
+ * @returns Absolute path, or null if not found
+ */
+export function resolveCloudflaredPath(): string | null {
+  if (_cloudflaredPath !== null) return _cloudflaredPath || null;
+
+  for (const dir of CLOUDFLARED_SEARCH_DIRS) {
+    const candidate = join(dir, 'cloudflared');
+    if (existsSync(candidate)) {
+      _cloudflaredPath = candidate;
+      return candidate;
+    }
+  }
+
+  try {
+    const result = execSync('which cloudflared', { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }).trim();
+    if (result && existsSync(result)) {
+      _cloudflaredPath = result;
+      return result;
+    }
+  } catch {
+    // Not on PATH either.
+  }
+
+  _cloudflaredPath = ''; // mark as searched, not found
+  return null;
+}
+
+/**
+ * Check if cloudflared is available on the system.
+ */
+export function isCloudflaredAvailable(): boolean {
+  return resolveCloudflaredPath() !== null;
+}

src/utils/index.ts

@@ -26,7 +26,10 @@ export { isSafePushEndpoint } from './push-endpoint-validation.js';
 export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
 export { assertNever } from './type-safety.js';
 export { wrapWithNice } from './nice-wrapper.js';
-export { findClaudeDir, getAugmentedPath, getClaudeCliVersion } from './claude-cli-resolver.js';
+export { resolveLocalShell, loginShellArgs } from './shell-resolver.js';
+export { findClaudeDir, getAugmentedPath, getClaudeCliVersion, getClaudeBinaryPath } 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';

src/utils/node-pty-repair.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Runtime self-heal for node-pty's macOS `spawn-helper`.
+ *
+ * node-pty@1.1.0 ships its macOS prebuilt helper as
+ * `prebuilds/darwin-<arch>/spawn-helper` with mode 0644 (no execute bit). On
+ * macOS every PTY is launched through that helper via posix_spawnp, so a
+ * non-executable helper turns every session start into
+ * `Error: posix_spawnp failed.` (issues #6 and #204). The bug is macOS-only:
+ * `spawn-helper` is an `OS=="mac"` gyp target and pty.cc only spawns it under
+ * `#if defined(__APPLE__)`, and node-pty ships no Linux prebuild, so Linux always
+ * compiles a correctly-permissioned helper from source.
+ *
+ * `scripts/fix-node-pty.mjs` fixes this at install time. This module is the
+ * safety net for installs that are already broken: the first PTY spawn that
+ * fails this way is repaired and retried in-process, so the user never sees a
+ * dead session. If the retry still fails, the thrown error carries the manual
+ * repair command instead of a bare "posix_spawnp failed".
+ *
+ * @module utils/node-pty-repair
+ */
+
+import { chmodSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+/** The one-line fix appended to errors we could not repair automatically. */
+export const SPAWN_HELPER_FIX_HINT =
+  'node-pty cannot execute its spawn-helper. Repair it with: npm run fix:node-pty ' +
+  '(or: chmod +x node_modules/node-pty/prebuilds/*/spawn-helper)';
+
+/** Set once a repair has been attempted, so a genuinely broken install cannot chmod-storm. */
+let repairAttempted = false;
+
+/**
+ * True when an error is node-pty failing to launch its spawn-helper.
+ *
+ * The native throw site is `throw Napi::Error::New(napiEnv, "posix_spawnp failed.")`
+ * in pty.cc, reached only on Apple platforms.
+ */
+export function isSpawnHelperFailure(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err ?? '');
+  return /posix_spawnp|spawn-helper/i.test(message);
+}
+
+/** Locates the installed node-pty package root, or null when it can't be resolved. */
+export function findNodePtyDir(): string | null {
+  // node-pty declares no "exports" map, so the package.json subpath resolves and
+  // lands on the package root. require.resolve('node-pty') would return
+  // <pkg>/lib/index.js, one level deeper than callers need.
+  try {
+    return dirname(require.resolve('node-pty/package.json'));
+  } catch {
+    /* fall through */
+  }
+  try {
+    return join(dirname(require.resolve('node-pty')), '..');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lists every `spawn-helper` present in a node-pty install.
+ *
+ * node-pty's loader checks `build/Release`, `build/Debug`, then
+ * `prebuilds/<platform>-<arch>`, and takes the helper from whichever directory
+ * the native module loaded out of, so every copy has to be executable, not just
+ * the one this machine happens to use.
+ */
+export function listSpawnHelpers(ptyDir: string): string[] {
+  const dirs = [join(ptyDir, 'build', 'Release'), join(ptyDir, 'build', 'Debug')];
+
+  const prebuilds = join(ptyDir, 'prebuilds');
+  if (existsSync(prebuilds)) {
+    try {
+      for (const entry of readdirSync(prebuilds, { withFileTypes: true })) {
+        if (entry.isDirectory()) dirs.push(join(prebuilds, entry.name));
+      }
+    } catch {
+      /* unreadable prebuilds dir: nothing to repair there */
+    }
+  }
+
+  return dirs.map((d) => join(d, 'spawn-helper')).filter((p) => existsSync(p));
+}
+
+/**
+ * Adds the execute bit to every `spawn-helper` missing it.
+ *
+ * @param ptyDir - node-pty package root; resolved automatically when omitted.
+ * @returns Paths actually changed (empty when nothing needed repair, or node-pty
+ *   is missing, or the files are not writable).
+ */
+export function repairSpawnHelperPermissions(ptyDir?: string): string[] {
+  const dir = ptyDir ?? findNodePtyDir();
+  if (!dir) return [];
+
+  const repaired: string[] = [];
+  for (const helper of listSpawnHelpers(dir)) {
+    try {
+      const mode = statSync(helper).mode & 0o777;
+      if ((mode & 0o111) === 0o111) continue;
+      chmodSync(helper, mode | 0o755);
+      repaired.push(helper);
+    } catch {
+      // Read-only install (or not ours to chmod): fall through to the hint.
+    }
+  }
+  return repaired;
+}
+
+/** Wraps an error so the message carries the actionable repair command. */
+function withFixHint(err: unknown): Error {
+  const message = err instanceof Error ? err.message : String(err);
+  return new Error(`${message}. ${SPAWN_HELPER_FIX_HINT}`, { cause: err });
+}
+
+/**
+ * Runs a `pty.spawn()` call, repairing a non-executable spawn-helper and
+ * retrying once if that is why it failed.
+ *
+ * Any unrelated spawn error is rethrown untouched, so this stays invisible on
+ * every platform but a broken macOS install.
+ *
+ * @param spawn - The `pty.spawn(...)` call to run.
+ * @param ptyDir - node-pty package root; resolved automatically when omitted.
+ */
+export function spawnPtyWithHelperRepair<T>(spawn: () => T, ptyDir?: string): T {
+  try {
+    return spawn();
+  } catch (err) {
+    if (!isSpawnHelperFailure(err)) throw err;
+    if (repairAttempted) throw withFixHint(err);
+
+    repairAttempted = true;
+    const repaired = repairSpawnHelperPermissions(ptyDir);
+    if (repaired.length === 0) throw withFixHint(err);
+
+    console.warn(`[node-pty] spawn-helper was not executable, repaired ${repaired.join(', ')} and retrying`);
+    try {
+      return spawn();
+    } catch (retryErr) {
+      throw withFixHint(retryErr);
+    }
+  }
+}
+
+/** Test seam: forget that a repair was already attempted in this process. */
+export function resetSpawnHelperRepairState(): void {
+  repairAttempted = false;
+}

src/utils/shell-resolver.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Resolve a real, launchable login shell for `mode: 'shell'` sessions.
+ *
+ * The tmux pane command for a local shell session used to be the literal string
+ * `$SHELL`. That string is embedded in the `bash -c "…"` argument of the
+ * `respawn-pane` line, which `execSync` hands to `/bin/sh -c` — so `$SHELL` was
+ * expanded by the SERVER process's shell (not the pane's), against the SERVER
+ * process's env. Containers and system-level systemd units do not set `SHELL`,
+ * so the expansion produced an empty string and the pane command ended in a
+ * dangling `&&`:
+ *
+ *   bash -c "cd \"/case\" && ulimit … && export … && "
+ *   -> bash: -c: line 1: syntax error: unexpected end of file
+ *
+ * The pane then died instantly (status 2) while tmux creation itself reported
+ * success, which is exactly what issue #208 saw. Resolving the shell HERE, in
+ * Node, removes the shell-expansion layer entirely and guarantees a non-empty
+ * absolute path.
+ *
+ * @module utils/shell-resolver
+ */
+
+import { accessSync, constants } from 'node:fs';
+import { userInfo } from 'node:os';
+
+/** Last-resort shells, in preference order. `/bin/sh` exists on every POSIX host. */
+const FALLBACK_SHELLS = ['/bin/bash', '/bin/zsh', '/bin/sh'];
+
+/**
+ * Shells that exist and are executable but immediately exit — a service account's
+ * passwd entry commonly points at one, which would look identical to the crash
+ * this module exists to prevent.
+ */
+const NON_INTERACTIVE_SHELLS = new Set(['nologin', 'false', 'true', 'sync']);
+
+/**
+ * Shells verified to accept BOTH `-i` and `-l`. Deliberately an allowlist, not a
+ * blocklist: a shell that rejects an unknown flag exits immediately, which is the
+ * dead-pane-on-arrival failure this module exists to prevent (#208). The passwd
+ * entry is user data and can name anything — nushell, elvish, and xonsh all take
+ * neither flag in this form, so they get a bare launch instead of a dead tab.
+ *
+ * csh/tcsh are excluded on purpose: tcsh honors `-l` only when it is the ONLY
+ * flag, so `-i -l` would silently not be a login shell there anyway.
+ */
+const LOGIN_FLAG_SHELLS = new Set(['sh', 'bash', 'dash', 'ash', 'zsh', 'ksh', 'ksh93', 'mksh', 'pdksh', 'fish']);
+
+function isUsableShell(candidate: string): boolean {
+  if (!candidate.startsWith('/')) return false;
+  const base = candidate.slice(candidate.lastIndexOf('/') + 1);
+  if (NON_INTERACTIVE_SHELLS.has(base)) return false;
+  try {
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve an absolute path to an interactive shell, preferring the user's own.
+ *
+ * Order: `$SHELL` -> the passwd entry -> `/bin/bash` -> `/bin/zsh` -> `/bin/sh`.
+ * Every candidate must be an absolute path to an executable that is not a
+ * nologin-style stub. Always returns a non-empty string.
+ */
+export function resolveLocalShell(): string {
+  const candidates: string[] = [];
+
+  const envShell = process.env.SHELL?.trim();
+  if (envShell) candidates.push(envShell);
+
+  try {
+    // Throws when the uid has no /etc/passwd entry (common for `--user` containers).
+    const passwdShell = userInfo().shell?.trim();
+    if (passwdShell) candidates.push(passwdShell);
+  } catch {
+    /* no passwd entry — fall through to the static fallbacks */
+  }
+
+  candidates.push(...FALLBACK_SHELLS);
+
+  for (const candidate of candidates) {
+    if (isUsableShell(candidate)) return candidate;
+  }
+
+  // Nothing was verifiable (exotic/read-restricted image). /bin/sh is still the
+  // best guess and is far better than emitting an empty command.
+  return '/bin/sh';
+}
+
+/**
+ * Flags that make `shellPath` a login shell, or `''` when it takes none we trust.
+ *
+ * A tmux pane already hands the shell a tty, so it is interactive with or without
+ * `-i` (verified: `$-` contains `i` for a bare `/bin/bash` in a pane, which is why
+ * `~/.bashrc` has always been sourced). The flag that actually changes anything is
+ * `-l`: it makes the pane a LOGIN shell, matching what tmux itself does when it
+ * spawns a pane with no `default-command`, and picking up the `/etc/profile` and
+ * `/etc/profile.d/*` PATH entries that a systemd-spawned server never sourced.
+ *
+ * `-i` is kept alongside it because for bash the two select different files —
+ * login reads `~/.bash_profile`, interactive-non-login reads `~/.bashrc` — and
+ * asking for both is the closest thing to "the shell the user actually gets".
+ *
+ * Returns a string ready to append to an already-escaped shell path.
+ */
+export function loginShellArgs(shellPath: string): string {
+  const base = shellPath.slice(shellPath.lastIndexOf('/') + 1);
+  return LOGIN_FLAG_SHELLS.has(base) ? ' -i -l' : '';
+}

src/web/middleware/auth.ts

@@ -22,6 +22,8 @@ import {
 import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { findUser, setPassword, touchLastLogin, verifyPassword } from '../../user-store.js';
+import { webviewCapabilities } from '../../webview-capabilities.js';
+import { capabilityFromProxyPath, capabilityFromReferer } from '../webview-proxy.js';
 import { ApiErrorCode, createErrorResponse, type AuthUser } from '../../types.js';
 
 // Request-scoped identity (multi-user). Single-user leaves it undefined and the
@@ -120,6 +122,85 @@ function isPasswordChangeExempt(req: FastifyRequest): boolean {
   return !url.startsWith('/api/');
 }
 
+/**
+ * Whether this request carries a VALID web-tab proxy capability.
+ *
+ * Requests under `/webview/<cap>/` cannot authenticate the normal way. The iframe
+ * rendering a dashboard is sandboxed without `allow-same-origin`, so it runs in an
+ * opaque origin: every request it makes is cross-site, meaning the `SameSite=lax`
+ * `codeman_session` cookie is never attached, and non-GET requests and WebSocket
+ * upgrades arrive with `Origin: null`. Both the cookie check and the CSRF Origin
+ * guard would therefore reject a perfectly legitimate dashboard asset load.
+ *
+ * The capability in the path is the credential instead: 192 bits of entropy, held
+ * in memory only (a restart invalidates it), rolling TTL, bound to the user who
+ * minted it through an already-authenticated `POST /api/webviews/:id/open`, and
+ * granting nothing but "relay bytes to this one saved URL".
+ *
+ * The exemption is deliberately narrow: it requires the capability to RESOLVE, so
+ * a bare `/webview/anything` reaches nothing, and a `/webviewfoo` path does not
+ * match the prefix at all. The Host allowlist is NOT bypassed, so DNS-rebinding
+ * protection still applies to these requests.
+ */
+function hasValidWebviewCapability(req: FastifyRequest): boolean {
+  const url = (req.url ?? '').split('?')[0];
+
+  const fromPath = capabilityFromProxyPath(url);
+  if (fromPath) return webviewCapabilities.resolve(fromPath) !== undefined;
+
+  // Referer form: a dashboard subresource requested with a ROOT-ABSOLUTE URL, which
+  // lands on Codeman's root and is relayed by the 404 fallback. Without this the
+  // asset would be rejected here, before the fallback ever runs.
+  //
+  // This is the only exemption decided by a header the request itself supplies, so
+  // it is fenced in hard: safe methods only, and never for Codeman's own functional
+  // surfaces. Without those fences a page could present a webview Referer and skip
+  // auth on /api. It is not a privilege escalation even so, holding a live
+  // capability already implies an authenticated `POST /api/webviews/:id/open`, but
+  // the exemption should stay no wider than the problem it solves.
+  if (req.method !== 'GET' && req.method !== 'HEAD') return false;
+  if (url.startsWith('/ws/') || url.startsWith('/q/')) return false;
+  // Anything that resolves to a REAL Codeman route is refused, which is the fence
+  // that keeps this from being an auth bypass. `/api/` used to be refused by prefix
+  // instead, but dashboards legitimately serve assets from their own `/api/...`
+  // namespace (`<img src="/api/hero?slug=x">`), and those requests were the one
+  // class the 404 relay could never rescue. See matchesRegisteredRoute.
+  if (matchesRegisteredRoute(req, url)) return false;
+
+  const fromReferer = capabilityFromReferer(typeof req.headers.referer === 'string' ? req.headers.referer : undefined);
+  return !!fromReferer && webviewCapabilities.resolve(fromReferer) !== undefined;
+}
+
+/**
+ * Whether `url` resolves to a route Codeman actually registered.
+ *
+ * `hasRoute()` is the wrong tool: it matches the registered PATTERN literally, so
+ * `/api/sessions/abc` reports false against a registered `/api/sessions/:id` and
+ * would hand out an exemption on a live API route. `findRoute()` performs the real
+ * radix-tree lookup and fills in `params`, which is what this needs.
+ *
+ * The one complication is `@fastify/static`, mounted at `/`, which registers a
+ * root-level catch-all that matches EVERY path. A match on that means "no real
+ * route, this is heading for the 404 handler", and it is distinguishable because a
+ * root catch-all is the only route whose `*` param comes back equal to the entire
+ * request path. `test/webview-auth-exemption.test.ts` pins both halves of that.
+ *
+ * Fails CLOSED: anything unexpected counts as a real route, which merely denies the
+ * exemption and restores the previous behavior.
+ */
+function matchesRegisteredRoute(req: FastifyRequest, url: string): boolean {
+  try {
+    const found = req.server.findRoute({ method: req.method as 'GET' | 'HEAD', url });
+    if (!found) return false;
+    const params = found.params ?? {};
+    const keys = Object.keys(params);
+    const isRootCatchAll = keys.length === 1 && keys[0] === '*' && `/${params['*']}` === url;
+    return !isRootCatchAll;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Register HTTP Basic Auth middleware with session cookies and rate limiting.
  * Only active when CODEMAN_PASSWORD is set.
@@ -211,6 +292,12 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
       return;
     }
 
+    // Web-tab proxy, authenticated by the capability in the path, not the cookie.
+    if (hasValidWebviewCapability(req)) {
+      done();
+      return;
+    }
+
     const clientIp = req.ip;
 
     // Check session cookie first (avoids re-sending credentials on every request)
@@ -341,6 +428,12 @@ function registerMultiUserAuthHook(
     // QR redemption path — handled by the route itself.
     if (req.url?.startsWith('/q/')) return;
 
+    // Web-tab proxy, authenticated by the capability in the path, not the cookie.
+    // `req.authUser` stays undefined here on purpose: the proxy handler enforces
+    // ownership against the identity BOUND TO THE CAPABILITY, which is stricter
+    // than re-deriving it from a request that carries no credentials.
+    if (hasValidWebviewCapability(req)) return;
+
     const clientIp = req.ip;
 
     // 1. Cookie session (carries identity + mustChangePassword snapshot).
@@ -466,7 +559,17 @@ export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPol
       reply.code(403).send('Forbidden: host not allowed');
       return;
     }
-    if (!SAFE_HTTP_METHODS.has(req.method) && !isAllowedRequestOrigin(req.headers.origin, policy)) {
+    // The Host allowlist above is NEVER bypassed. The Origin (CSRF) check is,
+    // but only for a request carrying a valid web-tab capability: a sandboxed
+    // dashboard is opaque-origin, so its form posts and uploads arrive with
+    // `Origin: null`, which this guard rejects by design. The capability is the
+    // credential in that case, and it is unguessable, see
+    // hasValidWebviewCapability.
+    if (
+      !SAFE_HTTP_METHODS.has(req.method) &&
+      !isAllowedRequestOrigin(req.headers.origin, policy) &&
+      !hasValidWebviewCapability(req)
+    ) {
       reply.code(403).send('Forbidden: cross-site request blocked');
       return;
     }
@@ -521,8 +624,17 @@ export function registerSecurityHeaders(app: FastifyInstance, https: boolean): v
       }
     }
 
-    // Handle CORS preflight
-    if (req.method === 'OPTIONS') {
+    // Handle CORS preflight.
+    //
+    // EXCEPT for the web-tab proxy, which must answer its own preflight. A
+    // sandboxed dashboard iframe is opaque-origin, so it sends `Origin: null`;
+    // the CORS block above only emits headers for localhost origins, so a bare
+    // 204 from here carries no `Access-Control-Allow-Origin` and the browser
+    // rejects the preflight. Every dashboard fetch then fails with an opaque
+    // net::ERR_FAILED while the page itself renders fine (script/css/img loads
+    // are not CORS-checked). Falling through lets the proxy route reply with the
+    // right headers.
+    if (req.method === 'OPTIONS' && !hasValidWebviewCapability(req)) {
       reply.code(204).send();
       done();
       return;

src/web/public/app.js

@@ -294,6 +294,9 @@ const _SSE_HANDLER_MAP = [
 
   // Session order (global tab order sync, COD-131)
   [SSE_EVENTS.SESSION_ORDER_CHANGED, '_onSessionOrderChanged'],
+
+  // Web tabs (dashboard URLs)
+  [SSE_EVENTS.WEBVIEW_CHANGED, '_onWebviewChanged'],
 ];
 
 
@@ -346,6 +349,22 @@ const DEFAULT_SHORTCUTS = [
     bindings: [{ modifiers: ['ctrl'], key: 'l' }],
     action: 'clearTerminal',
   },
+  {
+    id: 'copy-selection',
+    group: 'Terminal',
+    label: 'Copy Selection',
+    // Bindings match on `key`, not `code`: xterm decides which byte to emit from the
+    // PRODUCED character, so intercepting a physical KeyC that doesn't produce "c"
+    // would diverge from the chord that actually sends ^C.
+    bindings: [
+      { modifiers: ['ctrl'], key: 'c' },
+      { modifiers: ['ctrl', 'shift'], key: 'C' },
+    ],
+    // Dispatched by shouldCopyTerminalSelectionFromShortcut() in terminal-ui.js and
+    // deliberately absent from SHORTCUT_ACTIONS: the generic capture loop always
+    // preventDefaults on a match, which would cost the user the interrupt key.
+    action: 'copyTerminalSelection',
+  },
   {
     id: 'increase-font',
     group: 'Terminal',
@@ -492,7 +511,14 @@ 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
-    this._initialFullBufferLoad = true; // first buffer load after a page load fetches full tmux scrollback (COD-47)
+    // 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).
+    this._fullHistoryLoaded = new Set();
+    // Cooldown per session for the scroll-to-top "load more history" re-pull.
+    this._fullHistoryRepullAt = new Map(); // Map<sessionId, timestamp>
+    this._fullHistoryRepullInFlight = false;
     this.terminalLoadStates = new Map(); // Map<sessionId, { generation, phase }>
     this.respawnStatus = {};
     this.respawnTimers = {}; // Track timed respawn timers
@@ -797,6 +823,10 @@ class CodemanApp {
     this.applyLocalization();
     this.applyTabWrapSettings();
     this.applyMonitorVisibility();
+    // Must run before the first session:created can arrive: markSessionTabEntering()
+    // ignores ids until this sets up its state, which is what keeps the tabs
+    // restored on page load from animating.
+    this.initEntranceAnimations?.();
     // Remove mobile-init class now that JS has applied visibility settings.
     // The inline <script> in <head> added this to prevent flash-of-content on mobile.
     document.documentElement.classList.remove('mobile-init');
@@ -821,6 +851,7 @@ class CodemanApp {
     const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null).catch(() => null);
     this.loadQuickStartCases(null, settingsPromise);
     this._initRunMode();
+    this.initWebviews?.();
     this.setupEventListeners();
     // Mobile: ensure button taps register even when keyboard is visible.
     // On mobile, tapping a button while the soft keyboard is up causes the
@@ -1007,9 +1038,18 @@ class CodemanApp {
         const digitMatch = code.match(/^Digit([1-9])$/);
         if (digitMatch) {
           const idx = parseInt(digitMatch[1], 10) - 1;
+          // Sessions occupy 1..N and web tabs continue from N+1, matching the
+          // numbers actually painted on the tabs.
           if (idx < this.sessionOrder.length) {
             e.preventDefault();
             this.selectSession(this.sessionOrder[idx]);
+          } else {
+            const webIdx = idx - this.sessionOrder.length;
+            const webId = (this.webviewOrder || [])[webIdx];
+            if (webId) {
+              e.preventDefault();
+              this.openWebview(webId);
+            }
           }
           return;
         }
@@ -1550,6 +1590,12 @@ class CodemanApp {
       this.sessionOrder.push(data.id);
       this.saveSessionOrder();
     }
+    // Idempotent per id: the POST response and the session:created event both
+    // land here, and a batch launched together cascades in creation order.
+    this.markSessionTabEntering?.(data.id);
+    // The pane is one shared element, so it is only marked here and played when
+    // this session is actually selected (see selectSession).
+    this.markTerminalEntering?.(data.id);
     this.renderSessionTabs();
     this.updateCost();
     // Start stats polling when first session appears
@@ -1884,6 +1930,37 @@ class CodemanApp {
     }
   }
 
+  /** Build one response-viewer message so the brief and full views share markup and CSS. */
+  _buildResponseViewerMessage(text, role, agentLabel) {
+    const div = document.createElement('div');
+    const isUser = role === 'user';
+    div.className = 'rv-message ' + (isUser ? 'rv-msg-user' : 'rv-msg-assistant');
+
+    const roleBadge = document.createElement('div');
+    roleBadge.className = 'rv-role ' + (isUser ? 'rv-role-user' : 'rv-role-assistant');
+    roleBadge.textContent = isUser ? 'You' : agentLabel;
+    div.appendChild(roleBadge);
+
+    const renderedText = document.createElement('div');
+    renderedText.className = 'rv-text';
+    renderedText.innerHTML = this._renderMarkdown(text);
+    div.appendChild(renderedText);
+    return div;
+  }
+
+  _getResponseViewerAgentLabel() {
+    const mode = this.sessions.get(this.activeSessionId)?.mode;
+    return mode === 'codex'
+      ? 'Codex'
+      : mode === 'gemini'
+        ? 'Gemini'
+        : mode === 'antigravity'
+          ? 'Antigravity'
+          : mode === 'opencode'
+            ? 'OpenCode'
+            : 'Claude';
+  }
+
   async toggleResponseViewer() {
     const viewer = document.getElementById('responseViewer');
     const backdrop = document.getElementById('responseViewerBackdrop');
@@ -1906,7 +1983,7 @@ class CodemanApp {
       // Source 2: Terminal buffer fallback — strip ANSI, drop Claude CLI chrome.
       // Claude + shell only: _cleanTerminalBuffer knows Claude CLI's output, and
       // shell sessions have no transcript source at all; for TUI modes
-      // (codex/opencode/gemini) it yields repaint garbage, so a clear
+      // (codex/opencode/gemini/antigravity) it yields repaint garbage, so a clear
       // placeholder beats a messy screen dump there.
       const sessionMode = this.sessions.get(this.activeSessionId)?.mode || 'claude';
       if (!lastResponse && (sessionMode === 'claude' || sessionMode === 'shell')) {
@@ -1919,7 +1996,11 @@ class CodemanApp {
 
       const body = document.getElementById('responseViewerBody');
       if (lastResponse) {
-        body.innerHTML = this._renderMarkdown(lastResponse);
+        // Keep the brief view inside the same message wrapper as the full
+        // conversation view. The wrapper supplies the card, role badge and
+        // descendant markdown styles that direct body children do not get.
+        body.innerHTML = '';
+        body.appendChild(this._buildResponseViewerMessage(lastResponse, 'assistant', this._getResponseViewerAgentLabel()));
         this._bindResponseViewerInteractions(body);
       } else {
         body.textContent =
@@ -1959,26 +2040,10 @@ class CodemanApp {
       }
 
       // Render conversation thread
-      const mode = this.sessions.get(this.activeSessionId)?.mode;
-      const agentLabel =
-        mode === 'codex' ? 'Codex' : mode === 'gemini' ? 'Gemini' : mode === 'opencode' ? 'OpenCode' : 'Claude';
+      const agentLabel = this._getResponseViewerAgentLabel();
       body.innerHTML = '';
       for (const msg of messages) {
-        const div = document.createElement('div');
-        const isUser = msg.role === 'user';
-        div.className = 'rv-message ' + (isUser ? 'rv-msg-user' : 'rv-msg-assistant');
-
-        const role = document.createElement('div');
-        role.className = 'rv-role ' + (isUser ? 'rv-role-user' : 'rv-role-assistant');
-        role.textContent = isUser ? 'You' : agentLabel;
-        div.appendChild(role);
-
-        const text = document.createElement('div');
-        text.className = 'rv-text';
-        text.innerHTML = this._renderMarkdown(msg.text);
-        div.appendChild(text);
-
-        body.appendChild(div);
+        body.appendChild(this._buildResponseViewerMessage(msg.text, msg.role, agentLabel));
       }
       this._bindResponseViewerInteractions(body);
 
@@ -3267,14 +3332,33 @@ class CodemanApp {
   }
 
   _renderSessionTabsImmediate() {
+    // Same guard as renderSessionTabs()/_fullRenderSessionTabs(): the incremental
+    // branch below rewrites .tab-name's innerHTML, which destroys the inline rename
+    // <input> mid-keystroke. Guarding only the scheduler is not enough: a render
+    // debounced just BEFORE the rename opened still fires ~100ms later and lands
+    // here directly. finishRename() re-renders on both commit and cancel, so a
+    // render dropped here is picked back up when the rename settles.
+    if (this._inlineRenameActive) return;
     const container = this.$('sessionTabs');
     const existingTabs = container.querySelectorAll('.session-tab[data-id]');
     const existingIds = new Set([...existingTabs].map(t => t.dataset.id));
     const currentIds = new Set(this.sessions.keys());
 
-    // Check if we can do incremental update (same session IDs)
+    // Web tabs live in the same strip but are not in this.sessions, so they need
+    // their own change check. Without it, the session-only comparison below is
+    // vacuously "unchanged" whenever session count is stable — most visibly with
+    // ZERO sessions (0 === 0), where opening a dashboard would never draw its tab.
+    const existingWebIds = [...container.querySelectorAll('.session-tab[data-webview-id]')].map(
+      t => t.dataset.webviewId
+    );
+    const wantedWebIds = (this.webviewOrder || []).filter(id => this.webviews?.has(id));
+    const webTabsUnchanged =
+      existingWebIds.length === wantedWebIds.length && existingWebIds.every((id, i) => id === wantedWebIds[i]);
+
+    // Check if we can do incremental update (same session IDs and same web tabs)
     const canIncremental = existingIds.size === currentIds.size &&
-      [...existingIds].every(id => currentIds.has(id));
+      [...existingIds].every(id => currentIds.has(id)) &&
+      webTabsUnchanged;
 
     if (canIncremental) {
       // Incremental update - only modify changed properties
@@ -3282,7 +3366,12 @@ class CodemanApp {
         const tab = container.querySelector(`.session-tab[data-id="${id}"]`);
         if (!tab) continue;
 
-        const isActive = id === this.activeSessionId;
+        // A web tab owns the active state while one is open. activeSessionId stays
+        // set (the terminal keeps streaming underneath, and switching back is
+        // instant): only the highlight moves. Without this the debounced render
+        // re-marks the session tab active moments after a web tab was selected,
+        // leaving two tabs lit at once.
+        const isActive = id === this.activeSessionId && !this.activeWebviewId;
         const status = session.status || 'idle';
         const name = this.getSessionName(session);
         const taskStats = session.taskStats || { running: 0, total: 0 };
@@ -3413,6 +3502,13 @@ class CodemanApp {
     }
 
     this.updateTabOverflowMode();
+    // After the wrap measurement: the `unroll` style starts tabs at max-width 0,
+    // so measuring mid-animation would decide the wrap on collapsed widths.
+    this._applyTabEntrances?.();
+    // Phone overview rides on this one call: every state change it cares about
+    // (create, delete, idle, working, exit, hook alerts via updateTabAlertFromHooks)
+    // already funnels through here. No-ops unless that surface is showing.
+    this._refreshMobileOverviewIfVisible?.();
   }
 
   // Auto-wrap desktop session tabs to a second row when they overflow one row,
@@ -3469,7 +3565,9 @@ class CodemanApp {
       const session = this.sessions.get(id);
       if (!session) continue; // Skip if session was removed
 
-      const isActive = id === this.activeSessionId;
+      // See the note in the incremental path: a web tab owns the active highlight
+      // while one is open, even though activeSessionId stays set.
+      const isActive = id === this.activeSessionId && !this.activeWebviewId;
       const status = session.status || 'idle';
       const name = this.getSessionName(session);
       const mode = session.mode || 'claude';
@@ -3500,7 +3598,7 @@ class CodemanApp {
           <span class="tab-status ${status}" aria-hidden="true"></span>
           <span class="tab-info">
             <span class="tab-name-row">
-              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : ''}
+              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : ''}
               <span class="tab-name" data-session-id="${id}">${(() => { const p = parseSessionPrefix(name); return p && p.suffix ? '<span class="tab-prefix">' + escapeHtml(p.prefix) + '</span><span class="tab-suffix">: ' + escapeHtml(p.suffix) + '</span>' : escapeHtml(name); })()}</span>
               <span class="tab-detached-badge" aria-hidden="true">detached</span>
             </span>
@@ -3516,6 +3614,11 @@ class CodemanApp {
       _tabIdx++;
     }
 
+    // Web tabs (dashboard URLs) render after the session tabs, continuing the
+    // Alt+N numbering. They carry data-webview-id instead of data-id, so every
+    // session-tab code path above (drag-and-drop, alerts, badges) skips them.
+    parts.push(this.renderWebviewTabs ? this.renderWebviewTabs(_tabIdx) : '');
+
     container.innerHTML = parts.join('');
 
     // Set up drag-and-drop handlers for tab reordering
@@ -3532,6 +3635,9 @@ class CodemanApp {
     // toggle (applyTabWrapSettings calls this) which would otherwise leave a stale
     // tabs-auto-wrap class until the next content render.
     this.updateTabOverflowMode();
+    // Newly created tabs animate in; a re-render mid-cascade resumes them rather
+    // than restarting, since this rebuild just destroyed the animating elements.
+    this._applyTabEntrances?.();
   }
 
   // Set up arrow key navigation for session tabs (accessibility)
@@ -3999,6 +4105,58 @@ class CodemanApp {
     this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
   }
 
+  /**
+   * "Load more history": re-pull the whole tmux scrollback when the user scrolls up
+   * while already at the top of what the browser has.
+   *
+   * xterm's buffer is only ever a WINDOW onto tmux's real history, and two things
+   * shrink it. tmux repaints the pane rectangle instead of emitting linefeeds
+   * whenever output outpaces its flush interval, which OVERWRITES already-rendered
+   * scrollback rather than pushing rows into it (measured: a 60-line burst added 1
+   * row and destroyed 34, while the same 60 lines emitted slowly added all 60). And
+   * a tab switch replays only the visible frame. Either way tmux still holds
+   * everything (history-limit 100k by default), so the fix is to go ask for it with
+   * the same `?full=1` capture a page reload uses (issue #205).
+   *
+   * On demand rather than automatic because that capture is unbounded-ish work: at
+   * the default history limit it can be megabytes, which is fine to pay when the
+   * user is explicitly reaching for history and not fine on every tab switch.
+   */
+  async _maybeRefetchFullHistory() {
+    const sessionId = this.activeSessionId;
+    if (!sessionId || this._fullHistoryRepullInFlight || this._isLoadingBuffer) return;
+    if (this.detachedSessions?.has(sessionId)) 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.
+    if (now - (this._fullHistoryRepullAt.get(sessionId) || 0) < 4000) return;
+    this._fullHistoryRepullAt.set(sessionId, now);
+    this._fullHistoryRepullInFlight = true;
+    try {
+      const res = await fetch(`/api/sessions/${sessionId}/terminal?full=1`);
+      const buffer = (await res.json())?.data?.terminalBuffer;
+      // 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;
+      const rowsBefore = this.terminal.buffer.active.length;
+      this._resetTerminalForReplay();
+      await this.chunkedTerminalWrite(buffer, TERMINAL_CHUNK_SIZE, sessionId);
+      if (this.activeSessionId !== sessionId) return;
+      this.terminalBufferCache.set(sessionId, buffer);
+      // 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;
+      if (delta > 0) this.terminal.scrollToLine(delta);
+      else this.terminal.scrollToTop();
+    } catch {
+      // Transient (offline, 5xx) — the next scroll-up past the cooldown retries.
+    } finally {
+      this._fullHistoryRepullInFlight = false;
+    }
+  }
+
   _shouldFocusTerminalForTabSwitch() {
     if (typeof MobileDetection === 'undefined' || !MobileDetection.isTouchDevice()) {
       return true;
@@ -4050,6 +4208,9 @@ class CodemanApp {
       return; // newer tab switch won
     }
 
+    // A session tab takes the stage back from any active web tab.
+    this._hideWebviewLayer?.();
+
     this._cleanupPreviousSession(sessionId);
     this.activeSessionId = sessionId;
     try { localStorage.setItem('codeman-active-session', sessionId); } catch {}
@@ -4060,6 +4221,10 @@ class CodemanApp {
     // selectSession or reconnect catches up.
     this._updateSseSubscription(sessionId);
     this.hideWelcome();
+    // Terminal-pane entrance: plays for a freshly created session, and on every
+    // switch when that option is on. Transform/opacity/clip-path only, xterm's
+    // FitAddon reads the untransformed layout box, so this cannot reach the PTY.
+    this.playTerminalEntrance?.(sessionId);
     // Clear idle hooks on view, but keep action hooks until user interacts
     this.clearPendingHooks(sessionId, 'idle_prompt');
     // Instant active-class toggle (no 100ms debounce), then schedule full render for badges/status
@@ -4175,7 +4340,7 @@ class CodemanApp {
       // (viewport + scrollback + colors) for an instant first paint. For codex
       // this is also a correctness fix — its byte-stream replay shows only the
       // latest TUI frame (the idle welcome banner) because codex doesn't include
-      // earlier conversation in its current redraw. For claude/opencode/gemini
+      // earlier conversation in its current redraw. For claude/opencode/gemini/antigravity
       // the replay is already complete, so the snapshot is purely a faster,
       // scroll-preserving first paint before the canonical fetch reconciles.
       //
@@ -4262,11 +4427,14 @@ class CodemanApp {
 
       this._setTerminalLoadState(sessionId, selectGen, 'fetching');
       _crashDiag.log('FETCH_START');
-      // The FIRST buffer load after a page load requests the full tmux scrollback
-      // (?full=1, COD-47) so history that scrolled off the server's byte buffer
-      // comes back after a reload. Tab switches keep the fast ?tail= frame path.
-      const useFullHistory = this._initialFullBufferLoad === true;
-      this._initialFullBufferLoad = false;
+      // 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);
+      if (useFullHistory) this._fullHistoryLoaded.add(sessionId);
       const res = await fetch(
         useFullHistory
           ? `/api/sessions/${sessionId}/terminal?full=1`
@@ -4570,7 +4738,9 @@ class CodemanApp {
           ? 'Kill Tmux & Codex'
           : session.mode === 'gemini'
             ? 'Kill Tmux & Gemini'
-            : 'Kill Tmux & Claude Code';
+            : session.mode === 'antigravity'
+              ? 'Kill Tmux & Antigravity'
+              : 'Kill Tmux & Claude Code';
     }
 
     document.getElementById('closeConfirmModal').classList.add('active');

src/web/public/constants.js

@@ -494,6 +494,9 @@ const SSE_EVENTS = {
 
   // Session order (global tab order sync)
   SESSION_ORDER_CHANGED: 'session:orderChanged',
+
+  // Web tabs (dashboard URLs)
+  WEBVIEW_CHANGED: 'webview:changed',
 };
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/entrance-animations.js

@@ -0,0 +1,754 @@
+/**
+ * @fileoverview Entrance animations for the four things that appear when work
+ * starts: session TABS, the main TERMINAL pane a session's CLI runs in, floating
+ * agent WINDOWS, and the CONNECTION LINES tying a window back to its parent tab.
+ * One picker per surface, plus themes that set all four to a matching look.
+ *
+ * Everything is OFF by default (the `legacy` theme), so an untouched install
+ * behaves exactly as it did before this module existed. Opt in via App Settings
+ * → Appearance → Entrance Animations.
+ *
+ * Four constraints shape the design:
+ *
+ * 1. `_fullRenderSessionTabs()` replaces the tab strip's entire innerHTML, and
+ *    `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''` and rebuilds
+ *    every path. Both run constantly while sessions and agents are spawning, so
+ *    an animating tab or line element is DESTROYED mid-flight. Those two are
+ *    therefore tracked by id in `_tabEnterActive` / `_lineEnterActive` and
+ *    re-applied to the fresh element with a NEGATIVE animation-delay, resuming at
+ *    the same offset instead of restarting or snapping to the end. Windows are
+ *    stable DOM and need none of this.
+ * 2. Connection-line geometry comes from `getBoundingClientRect()` on the window.
+ *    A window entrance that starts with a transform would move that rect, so the
+ *    `beam` style (which must hold still while its line draws toward it) animates
+ *    opacity and filter only. Every other style refreshes the lines when it ends.
+ * 3. The terminal pane is ONE shared element, so its entrance is marked at
+ *    session creation but played at selection: a session created in the
+ *    background must not animate the pane the user is currently looking at. Its
+ *    styles are also restricted to transform/opacity/clip-path (see below).
+ * 4. Nothing may animate on page load or reconnect replay. Only ids that pass
+ *    through `markSessionTabEntering()` animate, and `_tabEnterSeen` makes that
+ *    once-per-id even though the POST response and the SSE event both call
+ *    `_onSessionCreated`.
+ *
+ * Styles are selected by `data-tab-anim` / `data-term-anim` / `data-win-anim` /
+ * `data-line-anim` on <html>; the keyframes live in styles.css. `?animlab=1`
+ * opens a floating picker that fakes tabs, a pane replay, a window and a line,
+ * so styles can be compared without spawning real sessions or agents.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (tab render pipeline), subagent-windows.js (window + line hooks)
+ * @dependency constants.js (escapeHtml)
+ * @loadorder 12.6 of 16, after webview-tabs.js, before ralph-wizard.js
+ */
+
+/** Tab entrance styles. `key` doubles as the `data-tab-anim` value. */
+const TAB_ANIM_STYLES = [
+  { key: 'slide', label: 'Slide', blurb: 'Drifts in from the right.', duration: 380 },
+  { key: 'pop', label: 'Pop', blurb: 'Springs past full size, then settles.', duration: 460 },
+  { key: 'crt', label: 'CRT', blurb: 'Snaps open as a hot line, then unfolds.', duration: 520 },
+  { key: 'unroll', label: 'Unroll', blurb: 'The strip makes room and the tab widens in.', duration: 480 },
+  { key: 'boot', label: 'Boot', blurb: 'Flickers on under a green scan sweep.', duration: 720 },
+  { key: 'flip', label: 'Flip', blurb: 'Drops in as a card hinged on its top edge.', duration: 520 },
+  { key: 'off', label: 'Off', blurb: 'Tabs just appear.', duration: 0 },
+];
+
+/**
+ * Window entrance styles. `fly` is the pre-existing behaviour (the window flies
+ * out of its parent tab via a JS transition in subagent-windows.js); every other
+ * style positions the window at its resting spot and runs a CSS animation there.
+ */
+const WIN_ANIM_STYLES = [
+  { key: 'fly', label: 'Fly from tab', blurb: 'Current behaviour: flies out of the tab, scaling up.', duration: 400 },
+  { key: 'crt', label: 'CRT', blurb: 'Bursts open as a hot line, then unfolds vertically.', duration: 560 },
+  { key: 'materialize', label: 'Materialize', blurb: 'Resolves out of a blur with a short glitch.', duration: 620 },
+  { key: 'unfold', label: 'Unfold', blurb: 'Hinges down from its top edge in 3D.', duration: 560 },
+  { key: 'beam', label: 'Beam down', blurb: 'Waits for its line to reach it, then materializes.', duration: 620 },
+  { key: 'pop', label: 'Pop', blurb: 'Springs open from its centre.', duration: 460 },
+  { key: 'off', label: 'Off', blurb: 'Windows just appear.', duration: 0 },
+];
+
+/** Connection-line entrance styles. `key` doubles as the `data-line-anim` value. */
+const LINE_ANIM_STYLES = [
+  { key: 'draw', label: 'Draw', blurb: 'Draws itself from the tab down to the window.', duration: 420 },
+  { key: 'packet', label: 'Packet', blurb: 'Line fades in, then a bright packet runs down it.', duration: 700 },
+  { key: 'fade', label: 'Fade', blurb: 'Simply fades in.', duration: 300 },
+  { key: 'off', label: 'Off', blurb: 'Lines just appear.', duration: 0 },
+];
+
+/**
+ * Main-terminal entrance styles: the pane a session's CLI actually runs in.
+ *
+ * ⚠ These may only animate transform, opacity and clip-path. xterm's FitAddon
+ * derives rows/cols from `getComputedStyle(parent).width/height`, which reports
+ * the untransformed layout box, so transforms are safe, but animating width,
+ * height or padding would feed wrong dimensions into `resize()` and through to
+ * the PTY. Colour washes go on `.terminal-container::before`, never a `filter`
+ * on the container: that would blur a full-screen WebGL canvas every frame.
+ */
+const TERM_ANIM_STYLES = [
+  { key: 'crt', label: 'CRT', blurb: 'Power-on: a hot line that expands to full height.', duration: 560 },
+  { key: 'boot', label: 'Boot', blurb: 'Flickers on under a green scan sweep.', duration: 760 },
+  { key: 'wipe', label: 'Wipe', blurb: 'Reveals top-to-bottom behind a bright edge.', duration: 520 },
+  { key: 'slide', label: 'Slide up', blurb: 'Rises into place from below.', duration: 420 },
+  { key: 'fade', label: 'Fade', blurb: 'Quiet fade with a touch of scale.', duration: 340 },
+  { key: 'off', label: 'Off', blurb: 'Current behaviour: the pane just appears.', duration: 0 },
+];
+
+/** How long a `beam` window waits before materializing. Just under the line draw. */
+const BEAM_HOLD_MS = 360;
+
+/** One-click combinations that read as a single look. */
+const ANIM_THEMES = [
+  { key: 'terminal', label: 'Terminal', tab: 'crt', win: 'crt', line: 'draw', term: 'crt' },
+  { key: 'beamdown', label: 'Beam down', tab: 'crt', win: 'beam', line: 'draw', term: 'wipe' },
+  { key: 'quiet', label: 'Quiet', tab: 'slide', win: 'materialize', line: 'fade', term: 'fade' },
+  { key: 'playful', label: 'Playful', tab: 'pop', win: 'pop', line: 'packet', term: 'slide' },
+  { key: 'legacy', label: 'Legacy', tab: 'off', win: 'fly', line: 'off', term: 'off' },
+];
+
+/**
+ * Defaults are the `legacy` theme: every entrance OFF, and agent windows on the
+ * `fly` behaviour Codeman already had before this module existed. So a user who
+ * never opens the picker sees exactly the pre-existing UI, and each mark/apply
+ * hook short-circuits on its first line. Opt in via App Settings → Appearance →
+ * Entrance Animations, which persists to the localStorage keys below.
+ */
+const TAB_ANIM_DEFAULT = 'off';
+const WIN_ANIM_DEFAULT = 'fly';
+const LINE_ANIM_DEFAULT = 'off';
+const TERM_ANIM_DEFAULT = 'off';
+const TAB_ANIM_STAGGER_DEFAULT = 90;
+/** A new id joins the current cascade if it arrives within this of the last one. */
+const TAB_ANIM_BATCH_WINDOW_MS = 600;
+
+const ANIM_KEYS = {
+  tab: 'codeman:tabAnim',
+  win: 'codeman:winAnim',
+  line: 'codeman:lineAnim',
+  term: 'codeman:termAnim',
+  termSwitch: 'codeman:termAnimOnSwitch',
+  stagger: 'codeman:tabAnimStagger',
+  speed: 'codeman:tabAnimSpeed',
+};
+
+Object.assign(CodemanApp.prototype, {
+  // ── Setup ─────────────────────────────────────────────────────────────────
+
+  /** Resolve every style/timing and stamp them on <html>. Called once at startup. */
+  initEntranceAnimations() {
+    this._tabEnterSeen = new Set();
+    this._tabEnterActive = new Map();
+    this._lineEnterActive = new Map();
+    this._tabEnterBatchIndex = 0;
+    this._tabEnterLastMarkTs = 0;
+
+    const params = new URLSearchParams(location.search);
+    // ?tabanim= / ?winanim= / ?lineanim= win for a single load, so a style can be
+    // tried without persisting over whatever is saved.
+    const pick = (param, styles, storeKey, fallback) => {
+      const fromUrl = params.get(param);
+      if (styles.some((s) => s.key === fromUrl)) return fromUrl;
+      return this._animRead(storeKey, fallback);
+    };
+
+    this.setTabAnimStyle(pick('tabanim', TAB_ANIM_STYLES, ANIM_KEYS.tab, TAB_ANIM_DEFAULT), { persist: false });
+    this.setWinAnimStyle(pick('winanim', WIN_ANIM_STYLES, ANIM_KEYS.win, WIN_ANIM_DEFAULT), { persist: false });
+    this.setLineAnimStyle(pick('lineanim', LINE_ANIM_STYLES, ANIM_KEYS.line, LINE_ANIM_DEFAULT), { persist: false });
+    this.setTermAnimStyle(pick('termanim', TERM_ANIM_STYLES, ANIM_KEYS.term, TERM_ANIM_DEFAULT), { persist: false });
+    this.setTermAnimOnSwitch(this._animRead(ANIM_KEYS.termSwitch, '0') === '1', { persist: false });
+
+    this.setTabAnimStagger(Number(this._animRead(ANIM_KEYS.stagger, TAB_ANIM_STAGGER_DEFAULT)), { persist: false });
+    this.setAnimSpeed(Number(this._animRead(ANIM_KEYS.speed, 1)), { persist: false });
+
+    if (params.get('animlab') === '1' || params.get('tabanimlab') === '1') this.openAnimLab();
+  },
+
+  _animRead(key, fallback) {
+    try {
+      const raw = localStorage.getItem(key);
+      return raw === null || raw === '' ? fallback : raw;
+    } catch {
+      return fallback;
+    }
+  },
+
+  _animWrite(key, value) {
+    try {
+      localStorage.setItem(key, String(value));
+    } catch {
+      /* private mode / quota, the in-memory value still applies for this load */
+    }
+  },
+
+  _setAnimStyle(prop, key, styles, fallback, attr, storeKey, persist) {
+    const style = styles.some((s) => s.key === key) ? key : fallback;
+    this[prop] = style;
+    document.documentElement.setAttribute(attr, style);
+    if (persist) this._animWrite(storeKey, style);
+    // Keep the lab's highlight honest when a style is set from anywhere other
+    // than the lab's own buttons (a theme, a URL param, the console).
+    this._syncAnimLab?.();
+  },
+
+  setTabAnimStyle(key, { persist = true } = {}) {
+    // prettier-ignore
+    this._setAnimStyle('_tabAnimStyle', key, TAB_ANIM_STYLES, TAB_ANIM_DEFAULT, 'data-tab-anim', ANIM_KEYS.tab, persist);
+  },
+
+  setWinAnimStyle(key, { persist = true } = {}) {
+    // prettier-ignore
+    this._setAnimStyle('_winAnimStyle', key, WIN_ANIM_STYLES, WIN_ANIM_DEFAULT, 'data-win-anim', ANIM_KEYS.win, persist);
+  },
+
+  setLineAnimStyle(key, { persist = true } = {}) {
+    // prettier-ignore
+    this._setAnimStyle('_lineAnimStyle', key, LINE_ANIM_STYLES, LINE_ANIM_DEFAULT, 'data-line-anim', ANIM_KEYS.line, persist);
+  },
+
+  setTermAnimStyle(key, { persist = true } = {}) {
+    // prettier-ignore
+    this._setAnimStyle('_termAnimStyle', key, TERM_ANIM_STYLES, TERM_ANIM_DEFAULT, 'data-term-anim', ANIM_KEYS.term, persist);
+  },
+
+  /** Replay the terminal entrance on every tab switch, not just on a new session. */
+  setTermAnimOnSwitch(on, { persist = true } = {}) {
+    this._termAnimOnSwitch = !!on;
+    if (persist) this._animWrite(ANIM_KEYS.termSwitch, on ? '1' : '0');
+    this._syncAnimLab?.();
+  },
+
+  /** Apply a theme: one look across tabs, windows, lines and the terminal. */
+  setAnimTheme(themeKey) {
+    const theme = ANIM_THEMES.find((t) => t.key === themeKey);
+    if (!theme) return;
+    this.setTabAnimStyle(theme.tab);
+    this.setWinAnimStyle(theme.win);
+    this.setLineAnimStyle(theme.line);
+    this.setTermAnimStyle(theme.term);
+    this._syncEntranceAnimSetting?.();
+  },
+
+  /** The theme matching the four current styles, or 'custom' for a lab mix. */
+  currentAnimTheme() {
+    const match = ANIM_THEMES.find(
+      (t) =>
+        t.tab === this._tabAnimStyle &&
+        t.win === this._winAnimStyle &&
+        t.line === this._lineAnimStyle &&
+        t.term === this._termAnimStyle
+    );
+    return match ? match.key : 'custom';
+  },
+
+  // ── App Settings picker ───────────────────────────────────────────────────
+  //
+  // Wired straight to setAnimTheme() rather than through saveAppSettings(): the
+  // styles live in their own localStorage keys, so they stay per-device and never
+  // reach `PUT /api/settings`, whose schema is .strict() and would reject them.
+
+  _syncEntranceAnimSetting() {
+    const sel = document.getElementById('appSettingsEntranceAnim');
+    if (!sel) return;
+    sel.value = this.currentAnimTheme();
+    if (!sel.dataset.bound) {
+      sel.dataset.bound = '1';
+      sel.addEventListener('change', () => {
+        // 'custom' is a readout of a lab mix, not something you can select into.
+        if (sel.value === 'custom') sel.value = this.currentAnimTheme();
+        else this.setAnimTheme(sel.value);
+      });
+    }
+  },
+
+  setTabAnimStagger(ms, { persist = true } = {}) {
+    const value = Number.isFinite(ms) ? Math.max(0, Math.min(400, Math.round(ms))) : TAB_ANIM_STAGGER_DEFAULT;
+    this._tabAnimStagger = value;
+    if (persist) this._animWrite(ANIM_KEYS.stagger, value);
+  },
+
+  setAnimSpeed(multiplier, { persist = true } = {}) {
+    const value = Number.isFinite(multiplier) ? Math.max(0.25, Math.min(3, multiplier)) : 1;
+    this._animSpeed = value;
+    // Every keyframe block reads this, so one variable retimes all of them.
+    document.documentElement.style.setProperty('--anim-enter-scale', String(1 / value));
+    if (persist) this._animWrite(ANIM_KEYS.speed, value);
+  },
+
+  _styleDuration(styles, key) {
+    return (styles.find((s) => s.key === key)?.duration || 0) / (this._animSpeed || 1);
+  },
+
+  _tabAnimDuration() {
+    return this._styleDuration(TAB_ANIM_STYLES, this._tabAnimStyle);
+  },
+
+  _winAnimDuration() {
+    return this._styleDuration(WIN_ANIM_STYLES, this._winAnimStyle);
+  },
+
+  _lineAnimDuration() {
+    return this._styleDuration(LINE_ANIM_STYLES, this._lineAnimStyle);
+  },
+
+  _termAnimDuration() {
+    return this._styleDuration(TERM_ANIM_STYLES, this._termAnimStyle);
+  },
+
+  // ── Tabs ──────────────────────────────────────────────────────────────────
+
+  /** Queue a session id to animate on its next render. Idempotent per id. */
+  markSessionTabEntering(id) {
+    if (!id || this._tabAnimStyle === 'off') return;
+    if (!this._tabEnterSeen) return; // initEntranceAnimations() has not run yet
+    if (this._tabEnterSeen.has(id)) return;
+    this._tabEnterSeen.add(id);
+
+    const now = performance.now();
+    // A launch landing well after the previous one starts its own cascade rather
+    // than inheriting a large stale offset.
+    if (now - this._tabEnterLastMarkTs > TAB_ANIM_BATCH_WINDOW_MS) this._tabEnterBatchIndex = 0;
+    this._tabEnterLastMarkTs = now;
+
+    this._tabEnterActive.set(id, {
+      startTs: now,
+      staggerMs: this._tabEnterBatchIndex * this._tabAnimStagger,
+    });
+    this._tabEnterBatchIndex += 1;
+  },
+
+  /** Attach (or resume) the entrance animation on freshly rendered tabs. */
+  _applyTabEntrances() {
+    const active = this._tabEnterActive;
+    if (!active || active.size === 0) return;
+    if (this._tabAnimStyle === 'off') {
+      active.clear();
+      return;
+    }
+
+    const container = this.$('sessionTabs');
+    if (!container) return;
+
+    const now = performance.now();
+    const duration = this._tabAnimDuration();
+
+    for (const [id, state] of active) {
+      const elapsed = now - state.startTs;
+      // Ran to completion while the element was detached, nothing left to show.
+      if (elapsed > state.staggerMs + duration + 50) {
+        active.delete(id);
+        continue;
+      }
+
+      const tab = container.querySelector(`.session-tab[data-id="${CSS.escape(id)}"]`);
+      if (!tab) continue; // not rendered yet; a later render picks it up
+      // Already running on this element. Re-stamping the delay would jump it, and
+      // the incremental render path can reach here for the same element.
+      if (tab.classList.contains('tab-enter')) continue;
+
+      // Negative delay resumes mid-animation, so an unrelated re-render mid-cascade
+      // does not restart the tab or make it snap.
+      tab.style.setProperty('--tab-enter-delay', `${state.staggerMs - elapsed}ms`);
+      tab.classList.add('tab-enter');
+      const done = () => {
+        tab.classList.remove('tab-enter');
+        tab.style.removeProperty('--tab-enter-delay');
+        this._tabEnterActive?.delete(id);
+      };
+      tab.addEventListener('animationend', done, { once: true });
+      tab.addEventListener('animationcancel', done, { once: true });
+    }
+  },
+
+  // ── Main terminal ─────────────────────────────────────────────────────────
+
+  /**
+   * Queue the terminal pane to animate the first time this session is shown.
+   * Marked at creation but PLAYED at selection, because the pane is one shared
+   * element: a session created in the background must not animate the pane the
+   * user is currently looking at.
+   */
+  markTerminalEntering(id) {
+    if (!id || this._termAnimStyle === 'off') return;
+    if (!this._termEnterPending) this._termEnterPending = new Set();
+    this._termEnterPending.add(id);
+  },
+
+  /** Play the terminal entrance for `sessionId`, if it is owed one. */
+  playTerminalEntrance(sessionId) {
+    const style = this._termAnimStyle || TERM_ANIM_DEFAULT;
+    if (style === 'off') return;
+
+    const owed = sessionId && this._termEnterPending?.delete(sessionId);
+    if (!owed && !this._termAnimOnSwitch) return;
+
+    const el = this.$('terminalContainer');
+    if (!el) return;
+
+    // Restart cleanly when switching tabs faster than the animation runs.
+    el.classList.remove('term-enter');
+    void el.offsetWidth;
+    el.classList.add('term-enter');
+
+    clearTimeout(this._termEnterTimer);
+    const done = () => {
+      el.classList.remove('term-enter');
+      clearTimeout(this._termEnterTimer);
+    };
+    el.addEventListener('animationend', done, { once: true });
+    el.addEventListener('animationcancel', done, { once: true });
+    // Backstop: a backgrounded tab never fires animationend, which would leave
+    // the pane stuck at its 0% keyframe (invisible) when you come back to it.
+    this._termEnterTimer = setTimeout(done, this._termAnimDuration() + 900);
+  },
+
+  // ── Windows ───────────────────────────────────────────────────────────────
+
+  /**
+   * True when the window should be parked on its parent tab and flown to its
+   * resting spot by subagent-windows.js. False for every CSS-animated style,
+   * which needs the window to start at its final position.
+   */
+  windowEntranceFliesFromTab() {
+    return (this._winAnimStyle || WIN_ANIM_DEFAULT) === 'fly';
+  },
+
+  /**
+   * Run the window entrance on an already-positioned window.
+   * @param {HTMLElement} win a .subagent-window or .ultracode-window
+   */
+  applyWindowEntrance(win) {
+    if (!win) return;
+    const style = this._winAnimStyle || WIN_ANIM_DEFAULT;
+    if (style === 'off' || style === 'fly') return;
+
+    // `beam` holds the window still (opacity/filter only) while its line draws
+    // toward it, then materializes. Everything else starts immediately.
+    if (style === 'beam') win.style.setProperty('--win-enter-delay', `${BEAM_HOLD_MS / (this._animSpeed || 1)}ms`);
+
+    win.classList.add('win-enter');
+    const done = () => {
+      win.classList.remove('win-enter');
+      win.style.removeProperty('--win-enter-delay');
+      // A transformed window reports a transformed rect, so lines drawn while it
+      // was animating are slightly off. Redraw once it has settled.
+      this.updateConnectionLines?.();
+    };
+    win.addEventListener('animationend', done, { once: true });
+    win.addEventListener('animationcancel', done, { once: true });
+  },
+
+  // ── Connection lines ──────────────────────────────────────────────────────
+
+  /** Queue an agent's connection line to draw itself on the next line rebuild. */
+  markConnectionLineEntering(agentId) {
+    if (!agentId || this._lineAnimStyle === 'off') return;
+    if (!this._lineEnterActive) return;
+    if (this._lineEnterActive.has(agentId)) return;
+    this._lineEnterActive.set(agentId, { startTs: performance.now() });
+  },
+
+  /**
+   * Attach (or resume) the draw-in animation on freshly rebuilt paths. Called at
+   * the end of `_updateConnectionLinesImmediate()`, which has just thrown away
+   * and recreated every path element.
+   */
+  _applyLineEntrances(svg) {
+    const active = this._lineEnterActive;
+    if (!active || active.size === 0 || !svg) return;
+    const style = this._lineAnimStyle || LINE_ANIM_DEFAULT;
+    if (style === 'off') {
+      active.clear();
+      return;
+    }
+
+    const now = performance.now();
+    const duration = this._lineAnimDuration();
+
+    for (const [agentId, state] of active) {
+      const elapsed = now - state.startTs;
+      if (elapsed > duration + 50) {
+        active.delete(agentId);
+        continue;
+      }
+
+      const path = svg.querySelector(`path[data-agent-id="${CSS.escape(agentId)}"]`);
+      if (!path) continue;
+
+      const len = Math.max(1, Math.round(path.getTotalLength()));
+      path.style.setProperty('--line-len', `${len}px`);
+      path.style.setProperty('--line-enter-delay', `${-elapsed}ms`);
+      path.classList.add('line-enter');
+
+      // `packet` rides a bright dash ON TOP of the normal dashed line, so the base
+      // line keeps its look instead of being taken over by the animation.
+      if (style === 'packet') {
+        const packet = path.cloneNode(false);
+        packet.removeAttribute('data-agent-id');
+        packet.setAttribute('class', 'connection-line-packet');
+        packet.style.setProperty('--line-len', `${len}px`);
+        packet.style.setProperty('--line-enter-delay', `${-elapsed}ms`);
+        svg.appendChild(packet);
+      }
+    }
+  },
+
+  // ── Lab (compare styles without spawning sessions or agents) ───────────────
+
+  /** Floating picker: switch styles per surface and replay fake entrances. */
+  openAnimLab() {
+    if (document.getElementById('animLab')) return;
+
+    const group = (title, styles, attr) => `
+      <div class="anim-lab-group">
+        <div class="anim-lab-group-title">${title}</div>
+        ${styles
+          .map(
+            (s) => `<button type="button" class="anim-lab-style" data-attr="${attr}" data-style="${s.key}">
+                 <strong>${escapeHtml(s.label)}</strong><em>${escapeHtml(s.blurb)}</em>
+               </button>`
+          )
+          .join('')}
+      </div>`;
+
+    const panel = document.createElement('div');
+    panel.id = 'animLab';
+    panel.className = 'anim-lab';
+    panel.innerHTML = `
+      <div class="anim-lab-head">
+        <span>Entrance lab</span>
+        <button type="button" class="anim-lab-close" aria-label="Close">&times;</button>
+      </div>
+      <div class="anim-lab-themes">
+        ${ANIM_THEMES.map((t) => `<button type="button" data-theme="${t.key}">${escapeHtml(t.label)}</button>`).join('')}
+      </div>
+      <div class="anim-lab-scroll">
+        ${group('Tabs', TAB_ANIM_STYLES, 'tab')}
+        ${group('Terminal pane', TERM_ANIM_STYLES, 'term')}
+        <label class="anim-lab-check">
+          <input type="checkbox" data-check="termSwitch"> Also on every tab switch
+        </label>
+        ${group('Agent windows', WIN_ANIM_STYLES, 'win')}
+        ${group('Connection lines', LINE_ANIM_STYLES, 'line')}
+      </div>
+      <label class="anim-lab-range">Tab stagger <output data-out="stagger"></output>
+        <input type="range" data-range="stagger" min="0" max="260" step="10">
+      </label>
+      <label class="anim-lab-range">Speed <output data-out="speed"></output>
+        <input type="range" data-range="speed" min="0.5" max="2" step="0.1">
+      </label>
+      <div class="anim-lab-demo">
+        <span>Replay</span>
+        <button type="button" data-demo="tabs">Tabs</button>
+        <button type="button" data-demo="term">Pane</button>
+        <button type="button" data-demo="window">Window</button>
+        <button type="button" data-demo="all">All</button>
+      </div>
+      <p class="anim-lab-hint">Fake tabs, window and line, removed after the run. Real launches use the same timing.</p>
+    `;
+    document.body.appendChild(panel);
+
+    panel.querySelector('.anim-lab-close').addEventListener('click', () => this.closeAnimLab());
+    panel.querySelectorAll('button[data-theme]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        this.setAnimTheme(btn.dataset.theme);
+        this._syncAnimLab();
+        this.demoEntrance('all');
+      });
+    });
+    panel.querySelectorAll('.anim-lab-style').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        const { attr, style } = btn.dataset;
+        if (attr === 'tab') this.setTabAnimStyle(style);
+        else if (attr === 'win') this.setWinAnimStyle(style);
+        else if (attr === 'term') this.setTermAnimStyle(style);
+        else this.setLineAnimStyle(style);
+        this._syncAnimLab();
+        this.demoEntrance({ tab: 'tabs', term: 'term' }[attr] || 'all');
+      });
+    });
+    panel.querySelector('input[data-check="termSwitch"]').addEventListener('change', (e) => {
+      this.setTermAnimOnSwitch(e.target.checked);
+    });
+    panel.querySelectorAll('input[data-range]').forEach((input) => {
+      input.addEventListener('input', () => {
+        if (input.dataset.range === 'stagger') this.setTabAnimStagger(Number(input.value));
+        else this.setAnimSpeed(Number(input.value));
+        this._syncAnimLab();
+      });
+      input.addEventListener('change', () => this.demoEntrance('all'));
+    });
+    panel.querySelectorAll('button[data-demo]').forEach((btn) => {
+      btn.addEventListener('click', () => this.demoEntrance(btn.dataset.demo));
+    });
+
+    this._syncAnimLab();
+  },
+
+  closeAnimLab() {
+    document.getElementById('animLab')?.remove();
+    this._clearEntranceDemo();
+  },
+
+  _syncAnimLab() {
+    const panel = document.getElementById('animLab');
+    if (!panel) return;
+    const current = {
+      tab: this._tabAnimStyle,
+      win: this._winAnimStyle,
+      line: this._lineAnimStyle,
+      term: this._termAnimStyle,
+    };
+    panel.querySelectorAll('.anim-lab-style').forEach((btn) => {
+      btn.classList.toggle('selected', current[btn.dataset.attr] === btn.dataset.style);
+    });
+    panel.querySelectorAll('button[data-theme]').forEach((btn) => {
+      const t = ANIM_THEMES.find((x) => x.key === btn.dataset.theme);
+      btn.classList.toggle('selected', !!t && ['tab', 'win', 'line', 'term'].every((k) => t[k] === current[k]));
+    });
+    const check = panel.querySelector('input[data-check="termSwitch"]');
+    if (check) check.checked = !!this._termAnimOnSwitch;
+    panel.querySelector('input[data-range="stagger"]').value = String(this._tabAnimStagger);
+    panel.querySelector('output[data-out="stagger"]').textContent = `${this._tabAnimStagger}ms`;
+    panel.querySelector('input[data-range="speed"]').value = String(this._animSpeed);
+    panel.querySelector('output[data-out="speed"]').textContent = `${this._animSpeed.toFixed(1)}x`;
+  },
+
+  _clearEntranceDemo() {
+    clearTimeout(this._animDemoTimer);
+    clearTimeout(this._animDemoWindowTimer);
+    document.querySelectorAll('.session-tab[data-demo]').forEach((el) => el.remove());
+    document.querySelectorAll('.subagent-window[data-demo]').forEach((el) => el.remove());
+    document.getElementById('animLabLines')?.remove();
+  },
+
+  /**
+   * The demo line gets its OWN svg overlay rather than sharing #connectionLines.
+   * That overlay is rebuilt from real windows via `svg.innerHTML = ''`, so a fake
+   * path dropped into it is erased the moment anything triggers a redraw -
+   * including the demo window's own entrance finishing.
+   */
+  _demoLineSvg() {
+    let svg = document.getElementById('animLabLines');
+    if (!svg) {
+      svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      svg.id = 'animLabLines';
+      svg.setAttribute('class', 'connection-lines-svg');
+      document.body.appendChild(svg);
+    }
+    return svg;
+  },
+
+  /** @param {'tabs'|'term'|'window'|'all'} what */
+  demoEntrance(what = 'all') {
+    this._clearEntranceDemo();
+
+    // The pane is a real, shared element rather than a throwaway, so replay it
+    // through the same entry point a real launch uses (bypassing the owed-id
+    // check, which only exists to keep background sessions from hijacking it).
+    if (what === 'term' || what === 'all') {
+      const wasOnSwitch = this._termAnimOnSwitch;
+      this._termAnimOnSwitch = true;
+      this.playTerminalEntrance(null);
+      this._termAnimOnSwitch = wasOnSwitch;
+    }
+    if (what === 'term') return;
+
+    const tabCount = what === 'window' ? 1 : 4;
+    const tabs = this._demoTabs(tabCount);
+    let total = Math.max(this._tabAnimDuration() + tabCount * this._tabAnimStagger, this._termAnimDuration());
+
+    if (what !== 'tabs') {
+      // Give the tab cascade a beat, so the window reads as coming out of it.
+      const lead = what === 'all' ? Math.min(320, this._tabAnimStagger * 2) : 0;
+      this._animDemoWindowTimer = setTimeout(() => this._demoWindow(tabs[0]), lead);
+      total = Math.max(total, lead + this._winAnimDuration() + this._lineAnimDuration() + BEAM_HOLD_MS);
+    }
+
+    this._animDemoTimer = setTimeout(() => this._clearEntranceDemo(), total + 1800);
+  },
+
+  /** Append `count` throwaway tabs and run the tab entrance on them. */
+  _demoTabs(count) {
+    const container = this.$('sessionTabs');
+    if (!container) return [];
+    const made = [];
+    const base = this.sessions?.size || 0;
+
+    for (let i = 0; i < count; i++) {
+      const tab = document.createElement('div');
+      tab.className = 'session-tab';
+      tab.dataset.demo = '1';
+      tab.dataset.color = ['green', 'blue', 'purple', 'orange', 'pink', 'yellow', 'red'][i % 7];
+      tab.innerHTML = `
+        <span class="tab-number">${base + i + 1}</span>
+        <span class="tab-status idle" aria-hidden="true"></span>
+        <span class="tab-info"><span class="tab-name-row">
+          <span class="tab-name">w${base + i + 1}-demo</span>
+        </span></span>`;
+      container.appendChild(tab);
+      made.push(tab);
+      if (this._tabAnimStyle !== 'off') {
+        tab.style.setProperty('--tab-enter-delay', `${i * this._tabAnimStagger}ms`);
+        void tab.offsetWidth; // force layout so the class add starts a fresh run
+        tab.classList.add('tab-enter');
+      }
+    }
+    return made;
+  },
+
+  /** Append a throwaway agent window under `originTab`, plus its connection line. */
+  _demoWindow(originTab) {
+    const tabRect = originTab?.getBoundingClientRect();
+    const win = document.createElement('div');
+    win.className = 'subagent-window';
+    win.dataset.demo = '1';
+    win.style.width = '360px';
+    win.style.height = '220px';
+    win.style.left = `${Math.max(24, (tabRect?.left ?? 120) - 40)}px`;
+    win.style.top = `${(tabRect?.bottom ?? 60) + 160}px`;
+    win.style.zIndex = '1001';
+    win.innerHTML = `
+      <div class="subagent-window-header">
+        <div class="subagent-window-title"><span class="icon">&#129302;</span><span class="id">demo-agent</span>
+          <span class="status running">running</span></div>
+      </div>
+      <div class="subagent-window-body"><div class="subagent-empty">Preview window</div></div>`;
+    document.body.appendChild(win);
+    this.applyWindowEntrance(win);
+    this._demoLine(tabRect, win);
+  },
+
+  /** Draw a fake tab→window line into the lab's own overlay and animate it. */
+  _demoLine(tabRect, win) {
+    if (!tabRect) return;
+    const svg = this._demoLineSvg();
+    const winRect = win.getBoundingClientRect();
+    const x1 = tabRect.left + tabRect.width / 2;
+    const y1 = tabRect.bottom;
+    const x2 = winRect.left + winRect.width / 2;
+    const y2 = winRect.top;
+    const midY = (y1 + y2) / 2;
+
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', `M ${x1} ${y1} C ${x1} ${midY}, ${x2} ${midY}, ${x2} ${y2}`);
+    path.setAttribute('class', 'connection-line');
+    path.dataset.demo = '1';
+    svg.appendChild(path);
+
+    if ((this._lineAnimStyle || LINE_ANIM_DEFAULT) === 'off') return;
+    const len = Math.max(1, Math.round(path.getTotalLength()));
+    path.style.setProperty('--line-len', `${len}px`);
+    path.style.setProperty('--line-enter-delay', '0ms');
+    path.classList.add('line-enter');
+
+    if (this._lineAnimStyle === 'packet') {
+      const packet = path.cloneNode(false);
+      packet.setAttribute('class', 'connection-line-packet');
+      packet.dataset.demo = '1';
+      packet.style.setProperty('--line-len', `${len}px`);
+      packet.style.setProperty('--line-enter-delay', '0ms');
+      svg.appendChild(packet);
+    }
+  },
+});

src/web/public/i18n.js

@@ -103,6 +103,7 @@
     'Run Claude Code': '运行 Claude Code',
     'Run OpenCode': '运行 OpenCode',
     'Run Gemini': '运行 Gemini',
+    'Run Antigravity': '运行 Antigravity',
     'Run Shell': '运行 Shell',
     'Select AI backend': '选择 AI 后端',
     'Create New Case': '新建案例',
@@ -349,6 +350,26 @@
     'Show Shortcuts': '显示快捷键',
     'Full shortcut reference': '完整快捷键参考',
 
+    // Mobile overview (phone home screen)
+    'Needs you': '需要你',
+    'Current sessions': '当前会话',
+    'Past sessions': '历史会话',
+    'Show all past sessions': '显示全部历史会话',
+    'Show fewer': '收起',
+    'Choose what to run': '选择运行方式',
+    'Web / URL': '网页 / 链接',
+    'Add URL…': '添加链接…',
+    'Nothing running. Hit Run to start something.': '当前没有运行中的会话。点击“运行”开始。',
+    'No past conversations yet': '尚无历史对话',
+    'Loading…': '加载中…',
+    // Status pills are deliberately NOT listed: they are single generic words
+    // ("idle", "done", "error") that also appear as state strings elsewhere, so
+    // they carry data-i18n-skip in the DOM instead of a translation entry here.
+    'Overview Home Screen': '概览主页',
+    'On phones, the C logo opens a session overview (needs you / spaces / idle) instead of the welcome screen':
+      '在手机上，点击 C 图标打开会话概览（需要你 / 空间 / 空闲），而不是欢迎页',
+    Phone: '手机',
+
     // Session/case dialogs
     'Session Options': '会话选项',
     'Session Name': '会话名称',
@@ -430,6 +451,7 @@
     'Respawn Blocked': '重生已阻止',
     'Task Complete': '任务完成',
     'Copied to clipboard': '已复制到剪贴板',
+    'Failed to copy': '复制失败',
     'Checking…': '正在检查…',
     'Starting…': '正在启动…',
     'Starting update…': '正在开始更新…',
@@ -579,6 +601,9 @@
     'Select a run to view its agents': '选择一次运行以查看其智能体',
     'Source type filter': '来源类型筛选',
     'Copy content': '复制内容',
+    'Edit file': '编辑文件',
+    'Unsaved changes': '未保存的更改',
+    Saved: '已保存',
     'Export as JSON': '导出为 JSON',
     'Export as Markdown': '导出为 Markdown',
     'Mark all read': '全部标为已读',

src/web/public/index.html

@@ -45,20 +45,20 @@
   <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
   <script>if(window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024))document.documentElement.classList.add('mobile-init');</script>
   <!-- Synchronous skin selection — runs before first paint to prevent theme flash -->
-  <script>try{var s=localStorage.getItem('codeman:skin');if(s!=='og'&&s!=='daylight-green'&&s!=='daylight-blue')s='daylight-blue';document.documentElement.dataset.skin=s;window.__codemanSkin=s;}catch(e){document.documentElement.dataset.skin='daylight-blue';window.__codemanSkin='daylight-blue';}</script>
+  <script>try{var s=localStorage.getItem('codeman:skin'),a=['og','daylight-green','daylight-blue','paper-gray','solarized-light','catppuccin-latte','rose-pine-dawn'];if(a.indexOf(s)<0)s='daylight-blue';document.documentElement.dataset.skin=s;window.__codemanSkin=s;}catch(e){document.documentElement.dataset.skin='daylight-blue';window.__codemanSkin='daylight-blue';}</script>
   <!-- Apply the saved per-device language before first paint. The full translation
        layer loads below; setting lang/dir here prevents an English accessibility
        tree from flashing while the deferred scripts start. -->
   <script>try{var m=window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024);var k=m?'codeman-app-settings-mobile':'codeman-app-settings';var l=JSON.parse(localStorage.getItem(k)||'{}').language;l=l==='zh-CN'?'zh-CN':'en';document.documentElement.lang=l;window.__codemanLanguage=l;}catch(e){document.documentElement.lang='en';window.__codemanLanguage='en';}</script>
   <!-- Inline critical CSS for instant skeleton paint (before styles.css loads) -->
   <style>
-    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#11151c}
-    .skeleton-header{height:40px;background:rgba(31,38,48,0.85);border-bottom:1px solid rgba(255,255,255,0.08);display:flex;align-items:center;padding:0 12px}
-    .skeleton-brand{color:#38b6f0;font-size:14px;font-weight:700;font-family:'Manrope',-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.85}
+    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:var(--bg-dark,#11151c)}
+    .skeleton-header{height:40px;background:var(--glass-bg,rgba(31,38,48,0.85));border-bottom:1px solid var(--glass-border,rgba(255,255,255,0.08));display:flex;align-items:center;padding:0 12px}
+    .skeleton-brand{color:var(--accent,#38b6f0);font-size:14px;font-weight:700;font-family:'Manrope',-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.85}
     .skeleton-tabs{display:flex;gap:4px;margin-left:16px}
-    .skeleton-tab{width:80px;height:24px;background:rgba(255,255,255,0.04);border-radius:6px}
-    .skeleton-terminal{flex:1;background:#161b23}
-    .skeleton-toolbar{height:42px;background:rgba(31,38,48,0.85);border-top:1px solid rgba(255,255,255,0.08)}
+    .skeleton-tab{width:80px;height:24px;background:var(--control-bg,rgba(255,255,255,0.04));border-radius:6px}
+    .skeleton-terminal{flex:1;background:var(--term-bg,#161b23)}
+    .skeleton-toolbar{height:42px;background:var(--glass-bg,rgba(31,38,48,0.85));border-top:1px solid var(--glass-border,rgba(255,255,255,0.08))}
     .app-loaded .loading-skeleton{display:none}
   </style>
 </head>
@@ -134,7 +134,7 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
           <span class="attachment-history-badge" id="attachmentHistoryBadge" style="display:none;">0</span>
         </button>
-        <button class="btn-icon-header btn-file-viewer btn-file-viewer--hidden" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
+        <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
         <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
@@ -142,9 +142,9 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
           <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
         </button>
-        <button class="btn-icon-header btn-lifecycle-log" onclick="app.openLifecycleLog()" title="Session Lifecycle Log" aria-label="Open session lifecycle log"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg></button>
+        <button class="btn-icon-header btn-lifecycle-log" style="display: none" onclick="app.openLifecycleLog()" title="Session Lifecycle Log" aria-label="Open session lifecycle log"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg></button>
         <button class="btn-icon-header btn-settings" onclick="app.openAppSettings()" title="App Settings" aria-label="Open app settings"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg></button>
-        <div class="header-tokens" id="headerTokens" title="Total tokens across all sessions">0 tokens</div>
+        <div class="header-tokens" id="headerTokens" style="display: none" title="Total tokens across all sessions">0 tokens</div>
       </div>
     </header>
 
@@ -300,25 +300,34 @@
           autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
       </div>
 
+      <!-- Web tab layer: one iframe per open dashboard, shown in place of the
+           terminal while a web tab is active. Frames stay mounted while hidden so
+           switching tabs does not reload (and re-authenticate) a dashboard. -->
+      <div class="webview-layer" id="webviewLayer"></div>
+
       <!-- Welcome Overlay (shown when no session active) -->
       <div class="welcome-overlay" id="welcomeOverlay">
         <div class="welcome-content">
           <h1 class="welcome-title">Codeman</h1>
           <p class="welcome-desc">Manage AI Coding tools in persistent tmux sessions.</p>
           <div class="welcome-actions">
-            <button class="welcome-btn welcome-btn-claude" onclick="app.setRunMode('claude'); app.runClaude()">
+            <button class="welcome-btn welcome-btn-claude" id="welcomeClaudeBtn" style="display: none;" onclick="app.setRunMode('claude'); app.runClaude()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               Run Claude Code
             </button>
-            <button class="welcome-btn welcome-btn-tunnel" id="welcomeTunnelBtn" onclick="app.toggleTunnelFromWelcome()">
+            <button class="welcome-btn welcome-btn-tunnel" id="welcomeTunnelBtn" style="display: none;" onclick="app.toggleTunnelFromWelcome()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>
               Cloudflare Tunnel
             </button>
-            <button class="welcome-btn welcome-btn-opencode" onclick="app.setRunMode('opencode'); app.runOpenCode()">
+            <button class="welcome-btn welcome-btn-opencode" id="welcomeOpencodeBtn" style="display: none;" onclick="app.setRunMode('opencode'); app.runOpenCode()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               Run OpenCode
             </button>
-            <button class="welcome-btn welcome-btn-gemini" onclick="app.setRunMode('gemini'); app.runGemini()">
+            <button class="welcome-btn welcome-btn-antigravity" id="welcomeAntigravityBtn" style="display: none;" onclick="app.setRunMode('antigravity'); app.runAntigravity()">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              Run Antigravity
+            </button>
+            <button class="welcome-btn welcome-btn-gemini" id="welcomeGeminiBtn" style="display: none;" onclick="app.setRunMode('gemini'); app.runGemini()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               Run Gemini
             </button>
@@ -374,6 +383,12 @@
           <button class="welcome-ralph-link" onclick="app.showRalphWizard()">Start Ralph Loop &rarr;</button>
         </div>
       </div>
+
+      <!-- Mobile Overview (phone home screen, shown in place of the welcome
+           overlay when the "C" logo is tapped). Ships `hidden`: only
+           mobile-overview.js removes it, and only when the phone gate passes, so
+           desktop (which never loads mobile.css) can never render it. -->
+      <div class="mobile-overview" id="mobileOverview" hidden></div>
     </main>
 
     <!-- Project Insights Panel (shows file-viewing Bash commands) -->
@@ -411,11 +426,18 @@
         <div class="file-preview-header">
           <span class="file-preview-title" id="filePreviewTitle">file.ts</span>
           <div class="file-preview-actions">
+            <button class="btn-icon-sm file-preview-edit-btn" id="filePreviewEditBtn" onclick="app.enterFilePreviewEdit()" title="Edit file" aria-label="Edit file" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5z"/></svg></button>
             <button class="btn-icon-sm" onclick="app.copyFilePreviewContent()" title="Copy content">&#x2398;</button>
             <button class="btn-icon-sm" onclick="app.closeFilePreview()" title="Close">&times;</button>
           </div>
         </div>
         <div class="file-preview-body" id="filePreviewBody"></div>
+        <div class="file-preview-editbar" id="filePreviewEditBar" hidden>
+          <span class="file-preview-dirty" id="filePreviewDirty" hidden>Unsaved changes</span>
+          <span class="file-preview-editbar-spacer"></span>
+          <button class="file-preview-editbar-btn" onclick="app.cancelFilePreviewEdit()">Cancel</button>
+          <button class="file-preview-editbar-btn file-preview-editbar-btn--save" id="filePreviewSaveBtn" onclick="app.saveFilePreviewEdit()" disabled>Save</button>
+        </div>
         <div class="file-preview-footer" id="filePreviewFooter"></div>
       </div>
     </div>
@@ -459,6 +481,21 @@
               <button class="run-mode-option" data-mode="gemini" onclick="app.setRunMode('gemini')">
                 <span class="run-mode-dot gemini"></span>Gemini
               </button>
+              <button class="run-mode-option" data-mode="antigravity" onclick="app.setRunMode('antigravity')">
+                <span class="run-mode-dot antigravity"></span>Antigravity
+              </button>
+              <div class="run-mode-sep"></div>
+              <button class="run-mode-option" data-mode="shell" onclick="app.setRunMode('shell')">
+                <span class="run-mode-dot shell"></span>Terminal / Shell
+              </button>
+              <div class="run-mode-sep"></div>
+              <!-- Web tabs: dashboards open as tabs beside agent sessions. These do NOT
+                   set runMode: the Run button always means "start an agent". -->
+              <div class="run-mode-header">Web / URL</div>
+              <div class="run-mode-webviews" id="runModeWebviews"></div>
+              <button class="run-mode-option run-mode-option--add" onclick="app.showWebviewModal()">
+                <span class="run-mode-dot web"></span>Add URL&hellip;
+              </button>
               <div class="run-mode-sep"></div>
               <div class="run-mode-header">Recent Sessions</div>
               <div class="run-mode-history" id="runModeHistory"></div>
@@ -475,6 +512,12 @@
           <button class="btn-toolbar btn-shell" onclick="app.runShell()" title="Run Shell">
             Run Shell
           </button>
+          <!-- Phone-only: replaces the Shell button on ≤430px (Shell moves into the Run
+               dropdown there). Sends a bare Enter to the active session, the complement
+               to the accessory bar's Esc. Hidden everywhere else — see styles.css. -->
+          <button class="btn-toolbar btn-enter" onclick="app.sendEnterKey()" title="Send Enter">
+            Enter
+          </button>
           <div class="tab-count-group" title="Instance count">
             <button class="tab-count-btn" onclick="app.decrementShellCount()">−</button>
             <input type="number" id="shellCount" class="tab-count-input" value="1" min="1" max="20" readonly>
@@ -607,6 +650,8 @@
           <section class="shortcut-section">
             <h4>Terminal</h4>
             <div class="shortcuts-grid">
+              <div><kbd>Ctrl</kbd>+<kbd>C</kbd></div><div>Copy Selection (interrupts when nothing is selected)</div>
+              <div><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd></div><div>Copy Selection</div>
               <div><kbd>Ctrl</kbd>+<kbd>L</kbd></div><div>Clear Terminal</div>
               <div><kbd>Ctrl</kbd>+<kbd>+</kbd></div><div>Increase Font</div>
               <div><kbd>Ctrl</kbd>+<kbd>-</kbd></div><div>Decrease Font</div>
@@ -629,6 +674,56 @@
       </div>
     </div>
 
+    <!-- Web Tab (dashboard URL) editor -->
+    <div class="modal" id="webviewModal">
+      <div class="modal-backdrop" onclick="app.closeWebviewModal()"></div>
+      <div class="modal-content">
+        <div class="modal-header">
+          <h3 id="webviewModalTitle">Add URL</h3>
+          <button class="modal-close" onclick="app.closeWebviewModal()" aria-label="Close URL editor">&times;</button>
+        </div>
+        <div class="modal-body">
+          <div class="form-row">
+            <label for="webviewName">Name</label>
+            <input type="text" id="webviewName" placeholder="Grafana" autocomplete="off" spellcheck="false">
+          </div>
+          <div class="form-row">
+            <label for="webviewUrl">URL</label>
+            <input type="text" id="webviewUrl" placeholder="http://100.70.56.18:4000/" autocomplete="off"
+                   autocapitalize="off" spellcheck="false">
+            <span class="form-hint">
+              Reached from the Codeman server, so a tailnet or localhost address works even when
+              this browser cannot see it. Plain HTTP is fine: the dashboard is proxied through
+              Codeman, which is also what gets past dashboards that refuse to be embedded.
+            </span>
+          </div>
+          <div class="form-row">
+            <label for="webviewIcon">Icon</label>
+            <!-- Click to pick; the field stays editable so any emoji still works. -->
+            <div class="webview-icon-picker" id="webviewIconPicker" role="group" aria-label="Choose an icon"></div>
+            <input type="text" id="webviewIcon" placeholder="Or paste any emoji" maxlength="8" autocomplete="off">
+          </div>
+          <div class="form-row">
+            <label class="checkbox-row"><input type="checkbox" id="webviewSandboxed" checked> Open sandboxed</label>
+            <span class="form-hint">
+              Recommended. A proxied dashboard is served from Codeman's own address, so unchecking
+              this lets its JavaScript read this page and call the API that starts agents. Uncheck
+              only for a dashboard you fully trust, or one whose own login needs cookies.
+            </span>
+          </div>
+          <div class="form-row">
+            <button class="btn-secondary" onclick="app.testWebviewUrl()">Test</button>
+            <span class="form-hint webview-probe-result" id="webviewProbeResult"></span>
+          </div>
+        </div>
+        <div class="form-actions webview-modal-actions">
+          <button class="btn-danger" id="webviewDeleteBtn" onclick="app.deleteWebview()">Delete</button>
+          <button class="btn-secondary" onclick="app.closeWebviewModal()">Cancel</button>
+          <button class="btn-primary" onclick="app.saveWebview()">Save</button>
+        </div>
+      </div>
+    </div>
+
     <!-- Cron Jobs Modal -->
     <div class="modal" id="cronModal">
       <div class="modal-backdrop" onclick="app.closeCron()"></div>
@@ -660,6 +755,7 @@
                 <option value="opencode">OpenCode</option>
                 <option value="codex">Codex</option>
                 <option value="gemini">Gemini</option>
+                <option value="antigravity">Antigravity</option>
               </select>
             </div>
             <div class="form-row"><label>Working Directory</label><input type="text" id="schWorkingDir" placeholder="/absolute/path"></div>
@@ -1190,9 +1286,31 @@
               <div class="settings-item settings-item-skin" title="Visual theme for this device (not synced)">
                 <span class="settings-item-label">Skin</span>
                 <select id="appSettingsSkin" class="form-select">
-                  <option value="daylight-blue">Daylight Blue</option>
-                  <option value="daylight-green">Daylight Green</option>
-                  <option value="og">OG Codeman</option>
+                  <optgroup label="Light">
+                    <option value="paper-gray">Paper Gray</option>
+                    <option value="solarized-light">Solarized Light</option>
+                    <option value="catppuccin-latte">Catppuccin Latte</option>
+                    <option value="rose-pine-dawn">Rosé Pine Dawn</option>
+                  </optgroup>
+                  <optgroup label="Dark">
+                    <option value="daylight-blue">Daylight Blue</option>
+                    <option value="daylight-green">Daylight Green</option>
+                    <option value="og">OG Codeman</option>
+                  </optgroup>
+                </select>
+              </div>
+              <div class="settings-item settings-item-multiline" title="How new session tabs, the terminal pane, agent windows and their connection lines appear. This device only. For per-surface control and a live preview, add ?animlab=1 to the URL.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Entrance Animations</span>
+                  <span class="settings-item-desc">How new tabs, panes and agent windows arrive</span>
+                </div>
+                <select id="appSettingsEntranceAnim" class="form-select settings-inline-select">
+                  <option value="legacy">Off (default)</option>
+                  <option value="terminal">Terminal (CRT)</option>
+                  <option value="beamdown">Beam down</option>
+                  <option value="quiet">Quiet</option>
+                  <option value="playful">Playful</option>
+                  <option value="custom">Custom (set in the lab)</option>
                 </select>
               </div>
               <div class="settings-item" id="appSettingsWebglRendererItem" title="Use the GPU-accelerated WebGL terminal renderer (desktop only). Turn off to force the DOM renderer if you hit GPU glitches. Codeman also auto-falls-back to the DOM renderer after repeated GPU stalls.">
@@ -1343,6 +1461,16 @@
                 </label>
               </div>
 
+              <!-- Phone Section (only meaningful under 430px, hidden elsewhere by settings-ui.js) -->
+              <div class="settings-section-header" id="appSettingsPhoneSection">Phone</div>
+              <div class="settings-item" id="appSettingsMobileOverviewItem" title="On phones, the C logo opens a session overview (needs you / spaces / idle) instead of the welcome screen">
+                <span class="settings-item-label">Overview Home Screen</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsMobileOverview" checked>
+                  <span class="slider"></span>
+                </label>
+              </div>
+
               <!-- Tab Bar Section -->
               <div class="settings-section-header">Tab Bar</div>
               <div class="settings-item" title="Show folder path below tab name and allow tab bar to wrap into multiple rows">
@@ -1573,6 +1701,14 @@
               </label>
               <span class="form-hint">Start new Codex sessions with --dangerously-bypass-approvals-and-sandbox</span>
             </div>
+            <div class="form-row form-row-switch">
+              <label>Animated Status Effects</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsCodexAnimations">
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Decorative Codex TUI motion for new local sessions. Leave off to reduce remote and mobile redraws.</span>
+            </div>
           </div>
           <!-- Models Tab -->
           <div class="modal-tab-content hidden" id="settings-models">
@@ -1767,7 +1903,7 @@
               <input type="checkbox" id="eventIdleAudio">
 
               <div class="event-label">Response complete</div>
-              <input type="checkbox" id="eventStopEnabled" checked>
+              <input type="checkbox" id="eventStopEnabled">
               <input type="checkbox" id="eventStopBrowser">
               <input type="checkbox" id="eventStopPush">
               <input type="checkbox" id="eventStopAudio">
@@ -1962,8 +2098,11 @@
             </div>
             <div class="form-row">
               <label>Folder Path</label>
-              <input type="text" id="linkCasePath" placeholder="/home/user/projects/my-project" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
-              <span class="form-hint">Absolute path to an existing project folder, e.g. /home/you/my-project</span>
+              <div class="path-input-group">
+                <input type="text" id="linkCasePath" placeholder="/mnt/d/AI/my-project" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false">
+                <button type="button" class="btn path-input-browse" onclick="app.openLinkCasePathPicker()">Browse&hellip;</button>
+              </div>
+              <span class="form-hint">Choose an existing folder from this computer or enter its absolute path</span>
             </div>
           </div>
           <!-- Remote Tab -->
@@ -2057,7 +2196,7 @@
             <div class="form-row">
               <label>Image</label>
               <input type="text" id="dockerImage" placeholder="codeman/agent:base" autocomplete="off" autocapitalize="off" spellcheck="false">
-              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini + tmux.</span>
+              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini/opencode/agy + tmux.</span>
             </div>
             <div class="form-row">
               <label>Network</label>
@@ -2541,6 +2680,9 @@
   <script defer src="ultracode-panel.js"></script>
   <script defer src="admin-ui.js"></script>
   <script defer src="session-ui.js"></script>
+  <script defer src="webview-tabs.js"></script>
+  <script defer src="mobile-overview.js"></script>
+  <script defer src="entrance-animations.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
   <script defer src="subagent-windows.js"></script>

src/web/public/keyboard-accessory.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Mobile keyboard accessory bar and modal focus trap.
  *
- * Defines two exports:
+ * Defines three exports:
  *
  * - KeyboardAccessoryBar (singleton object) — Quick action buttons shown above the virtual
  *   keyboard on mobile: arrow up/down, /init, /clear, /compact, paste, Esc, and dismiss.
@@ -10,12 +10,15 @@
  *   Destructive actions (/clear, /compact) require double-tap confirmation (2s amber state).
  *   Commands are sent as text + Enter separately for Ink compatibility.
  *   Only initializes on touch devices (MobileDetection.isTouchDevice guard).
+ * - PathPicker (singleton object) — Lazy server-side file/folder browser shared
+ *   by Link Existing and the extended mobile keyboard bar.
  *
  * - FocusTrap (class) — Traps Tab/Shift+Tab keyboard focus within a modal element.
  *   Saves and restores previously focused element on deactivate. Used by Ralph wizard
  *   and other modal dialogs.
  *
  * @globals {object} KeyboardAccessoryBar
+ * @globals {object} PathPicker
  * @globals {class} FocusTrap
  *
  * @dependency mobile-handlers.js (MobileDetection.isTouchDevice)
@@ -26,6 +29,338 @@
 // Codeman — Keyboard accessory bar and focus trap for modals
 // Loaded after mobile-handlers.js, before app.js
 
+// ═══════════════════════════════════════════════════════════════
+// Shared Filesystem Path Picker
+// ═══════════════════════════════════════════════════════════════
+
+const PathPicker = {
+  overlay: null,
+  _options: null,
+  _selectedPath: '',
+  _previousFocus: null,
+  _keydownHandler: null,
+  _loadSequence: 0,
+  _previewOverlay: null,
+  _previewRequestSequence: 0,
+  _previewPreviousFocus: null,
+
+  /**
+   * Open the lazy filesystem browser.
+   * @param {{sessionId?: string, initialPath?: string, directoriesOnly?: boolean,
+   *   title?: string, onSelect: (path: string) => void}} options
+   */
+  open(options) {
+    this.close(false);
+    this._options = options;
+    this._selectedPath = '';
+    this._previousFocus = document.activeElement;
+    this._previousFocus?.blur?.();
+
+    const overlay = document.createElement('div');
+    overlay.className = 'path-picker-overlay';
+    overlay.setAttribute('role', 'dialog');
+    overlay.setAttribute('aria-modal', 'true');
+    overlay.setAttribute('aria-label', options.title || 'Select a path');
+    overlay.innerHTML = `
+      <div class="path-picker-dialog">
+        <div class="path-picker-header">
+          <strong class="path-picker-title"></strong>
+          <button type="button" class="path-picker-close" aria-label="Close">&times;</button>
+        </div>
+        <div class="path-picker-roots-row">
+          <label for="pathPickerRoot">Location</label>
+          <select id="pathPickerRoot" class="path-picker-roots"></select>
+        </div>
+        <div class="path-picker-nav">
+          <button type="button" class="path-picker-up" title="Parent folder" aria-label="Parent folder">&#x2191;</button>
+          <div class="path-picker-current" title="Current folder"></div>
+          <button type="button" class="path-picker-refresh" title="Refresh" aria-label="Refresh">&#x21BB;</button>
+        </div>
+        <div class="path-picker-status" aria-live="polite">Loading...</div>
+        <div class="path-picker-list" role="listbox"></div>
+        <div class="path-picker-selection">
+          <span class="path-picker-selection-label">Selected</span>
+          <span class="path-picker-selection-value">None</span>
+        </div>
+        <div class="path-picker-actions">
+          <button type="button" class="path-picker-current-select">Select Current Folder</button>
+          <span class="path-picker-action-spacer"></span>
+          <button type="button" class="path-picker-cancel">Cancel</button>
+          <button type="button" class="path-picker-confirm" disabled>Select</button>
+        </div>
+      </div>`;
+
+    this.overlay = overlay;
+    overlay.querySelector('.path-picker-title').textContent = options.title || 'Select a Path';
+    overlay.querySelector('.path-picker-close').addEventListener('click', () => this.close(true));
+    overlay.querySelector('.path-picker-cancel').addEventListener('click', () => this.close(true));
+    overlay.querySelector('.path-picker-confirm').addEventListener('click', () => this.confirm());
+    overlay.querySelector('.path-picker-current-select').addEventListener('click', () => {
+      const current = overlay.querySelector('.path-picker-current').textContent;
+      if (current) this.select(current);
+    });
+    overlay.querySelector('.path-picker-refresh').addEventListener('click', () => this.load());
+    overlay.querySelector('.path-picker-up').addEventListener('click', () => {
+      const parent = overlay.querySelector('.path-picker-up').dataset.parent;
+      if (parent) this.load(parent);
+    });
+    overlay.querySelector('.path-picker-roots').addEventListener('change', (event) => this.load(event.target.value));
+    overlay.addEventListener('click', (event) => {
+      if (event.target === overlay) this.close(true);
+    });
+    this._keydownHandler = (event) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        if (this._previewOverlay) this.closePreview(true);
+        else this.close(true);
+      }
+    };
+    document.addEventListener('keydown', this._keydownHandler);
+    document.body.appendChild(overlay);
+    this.load(options.initialPath || '');
+  },
+
+  async load(path) {
+    if (!this.overlay || !this._options) return;
+    const loadSequence = ++this._loadSequence;
+    const list = this.overlay.querySelector('.path-picker-list');
+    const status = this.overlay.querySelector('.path-picker-status');
+    list.replaceChildren();
+    status.textContent = 'Loading...';
+
+    const params = new URLSearchParams();
+    if (path) params.set('path', path);
+    if (this._options.sessionId) params.set('sessionId', this._options.sessionId);
+    try {
+      const response = await fetch(`/api/filesystem/browse?${params.toString()}`);
+      const result = await response.json();
+      if (!response.ok || !result.success) throw new Error(result.error || 'Failed to browse this folder');
+      if (!this.overlay || loadSequence !== this._loadSequence) return;
+      this.render(result.data);
+    } catch (error) {
+      if (!this.overlay || loadSequence !== this._loadSequence) return;
+      if (path) {
+        this.load('');
+        return;
+      }
+      status.textContent = error.message || 'Failed to browse this folder';
+      status.classList.add('error');
+    }
+  },
+
+  render(data) {
+    const rootSelect = this.overlay.querySelector('.path-picker-roots');
+    rootSelect.replaceChildren();
+    for (const root of data.roots) {
+      const option = document.createElement('option');
+      option.value = root.path;
+      option.textContent = `${root.label} — ${root.path}`;
+      option.selected = data.path === root.path || data.root === root.path;
+      rootSelect.appendChild(option);
+    }
+
+    this.overlay.querySelector('.path-picker-current').textContent = data.path;
+    const up = this.overlay.querySelector('.path-picker-up');
+    up.dataset.parent = data.parent || '';
+    up.disabled = !data.parent;
+    const status = this.overlay.querySelector('.path-picker-status');
+    status.classList.remove('error');
+    status.textContent = data.entries.length === 0
+      ? 'This folder is empty'
+      : `${data.entries.length} item${data.entries.length === 1 ? '' : 's'}${data.truncated ? ' (first 500)' : ''}`;
+
+    const list = this.overlay.querySelector('.path-picker-list');
+    list.replaceChildren();
+    for (const entry of data.entries) {
+      const row = document.createElement('div');
+      row.className = 'path-picker-item';
+      if (entry.type === 'file' && this._options.directoriesOnly && !entry.previewKind) {
+        row.classList.add('not-selectable');
+      }
+      row.dataset.path = entry.path;
+      row.dataset.type = entry.type;
+      row.setAttribute('role', 'option');
+
+      const open = document.createElement('button');
+      open.type = 'button';
+      open.className = 'path-picker-item-main';
+      const icon = document.createElement('span');
+      icon.className = 'path-picker-item-icon';
+      icon.textContent = entry.type === 'directory' ? '\uD83D\uDCC1' : '\uD83D\uDCC4';
+      const name = document.createElement('span');
+      name.className = 'path-picker-item-name';
+      name.textContent = entry.name;
+      open.append(icon, name);
+      if (entry.symlink) {
+        const link = document.createElement('span');
+        link.className = 'path-picker-item-link';
+        link.textContent = '\u2197';
+        open.appendChild(link);
+      }
+      if (entry.type === 'directory') {
+        const chevron = document.createElement('span');
+        chevron.className = 'path-picker-item-chevron';
+        chevron.textContent = '\u203A';
+        open.appendChild(chevron);
+        open.addEventListener('click', () => this.load(entry.path));
+      } else if (entry.previewKind) {
+        const preview = document.createElement('span');
+        preview.className = 'path-picker-item-preview';
+        preview.textContent = '\uD83D\uDC41';
+        open.appendChild(preview);
+        open.title = `Preview ${entry.name}`;
+        open.setAttribute('aria-label', `Preview ${entry.name}`);
+        open.addEventListener('click', () => this.openPreview(entry));
+      } else if (!this._options.directoriesOnly) {
+        open.addEventListener('click', () => this.select(entry.path));
+      } else {
+        open.disabled = true;
+      }
+      row.appendChild(open);
+
+      if (entry.type === 'directory' || !this._options.directoriesOnly) {
+        const choose = document.createElement('button');
+        choose.type = 'button';
+        choose.className = 'path-picker-item-select';
+        choose.textContent = 'Choose';
+        choose.addEventListener('click', () => this.select(entry.path));
+        row.appendChild(choose);
+      }
+      list.appendChild(row);
+    }
+  },
+
+  select(path) {
+    if (!this.overlay) return;
+    this._selectedPath = path;
+    this.overlay.querySelector('.path-picker-selection-value').textContent = path;
+    this.overlay.querySelector('.path-picker-confirm').disabled = false;
+    this.overlay.querySelectorAll('.path-picker-item').forEach((row) => {
+      const selected = row.dataset.path === path;
+      row.classList.toggle('selected', selected);
+      row.setAttribute('aria-selected', selected ? 'true' : 'false');
+    });
+  },
+
+  openPreview(entry) {
+    this.closePreview(false);
+    this._previewPreviousFocus = document.activeElement;
+    const requestSequence = ++this._previewRequestSequence;
+    const params = new URLSearchParams({ path: entry.path });
+    if (this._options?.sessionId) params.set('sessionId', this._options.sessionId);
+    const previewUrl = `/api/filesystem/preview?${params.toString()}`;
+
+    const overlay = document.createElement('div');
+    overlay.className = 'path-preview-overlay';
+    overlay.setAttribute('role', 'dialog');
+    overlay.setAttribute('aria-modal', 'true');
+    overlay.setAttribute('aria-label', `Preview ${entry.name}`);
+    overlay.innerHTML = `
+      <div class="path-preview-dialog">
+        <div class="path-preview-header">
+          <div class="path-preview-heading">
+            <strong class="path-preview-title"></strong>
+            <span class="path-preview-path"></span>
+          </div>
+          <a class="path-preview-open" target="_blank" rel="noopener noreferrer">Open</a>
+          <button type="button" class="path-preview-close" aria-label="Close preview">&times;</button>
+        </div>
+        <div class="path-preview-body"><div class="path-preview-loading">Loading preview...</div></div>
+      </div>`;
+    overlay.querySelector('.path-preview-title').textContent = entry.name;
+    overlay.querySelector('.path-preview-path').textContent = entry.path;
+    overlay.querySelector('.path-preview-open').href = previewUrl;
+    overlay.querySelector('.path-preview-close').addEventListener('click', () => this.closePreview(true));
+    overlay.addEventListener('click', (event) => {
+      if (event.target === overlay) this.closePreview(true);
+    });
+    document.body.appendChild(overlay);
+    this._previewOverlay = overlay;
+
+    const body = overlay.querySelector('.path-preview-body');
+    if (entry.previewKind === 'image') {
+      const image = document.createElement('img');
+      image.className = 'path-preview-image';
+      image.alt = entry.name;
+      image.addEventListener('load', () => body.querySelector('.path-preview-loading')?.remove());
+      image.addEventListener('error', () => this.showPreviewError('Image preview failed to load'));
+      image.src = previewUrl;
+      body.appendChild(image);
+    } else if (entry.previewKind === 'text') {
+      fetch(previewUrl)
+        .then(async (response) => {
+          const content = await response.text();
+          if (!response.ok) {
+            let message = 'Text preview failed to load';
+            try {
+              message = JSON.parse(content).error || message;
+            } catch {}
+            throw new Error(message);
+          }
+          return content;
+        })
+        .then((content) => {
+          if (!this._previewOverlay || requestSequence !== this._previewRequestSequence) return;
+          const pre = document.createElement('pre');
+          pre.className = 'path-preview-text';
+          pre.textContent = content;
+          body.replaceChildren(pre);
+        })
+        .catch((error) => {
+          if (requestSequence === this._previewRequestSequence) this.showPreviewError(error.message);
+        });
+    } else {
+      const frame = document.createElement('iframe');
+      frame.className = 'path-preview-frame';
+      frame.title = entry.name;
+      frame.addEventListener('load', () => body.querySelector('.path-preview-loading')?.remove());
+      frame.src = previewUrl;
+      body.appendChild(frame);
+    }
+    overlay.querySelector('.path-preview-close').focus();
+  },
+
+  showPreviewError(message) {
+    const body = this._previewOverlay?.querySelector('.path-preview-body');
+    if (!body) return;
+    const error = document.createElement('div');
+    error.className = 'path-preview-error';
+    error.textContent = message || 'Preview failed to load';
+    body.replaceChildren(error);
+  },
+
+  closePreview(restoreFocus = true) {
+    this._previewRequestSequence += 1;
+    this._previewOverlay?.remove();
+    this._previewOverlay = null;
+    const previousFocus = this._previewPreviousFocus;
+    this._previewPreviousFocus = null;
+    if (restoreFocus) previousFocus?.focus?.();
+  },
+
+  confirm() {
+    if (!this._selectedPath || !this._options) return;
+    const selectedPath = this._selectedPath;
+    const onSelect = this._options.onSelect;
+    this.close(false);
+    onSelect(selectedPath);
+  },
+
+  close(restoreFocus = true) {
+    if (this._keydownHandler) document.removeEventListener('keydown', this._keydownHandler);
+    this._keydownHandler = null;
+    this._loadSequence += 1;
+    this.closePreview(false);
+    this.overlay?.remove();
+    this.overlay = null;
+    const previousFocus = this._previousFocus;
+    this._previousFocus = null;
+    this._options = null;
+    this._selectedPath = '';
+    if (restoreFocus) previousFocus?.focus?.();
+  },
+};
+
 // ═══════════════════════════════════════════════════════════════
 // Mobile Keyboard Accessory Bar
 // ═══════════════════════════════════════════════════════════════
@@ -92,6 +427,8 @@ const KeyboardAccessoryBar = {
           <rect x="8" y="2" width="8" height="4" rx="1" ry="1"/>
         </svg>
       </button>
+      <button class="accessory-btn" data-action="pick-path" title="Insert a file or folder path">&#x1F4C1; Path</button>
+      <button class="accessory-btn" data-action="clear-input" title="Clear the current unsent input">&#x232B; All</button>
       <button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
       <button class="accessory-btn" data-action="shift-tab" title="Shift+Tab">⇧Tab</button>
       <button class="accessory-btn" data-action="effort-max" title="/effort max">Max</button>
@@ -128,7 +465,7 @@ const KeyboardAccessoryBar = {
       this.handleAction(action, btn);
 
       // Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
-      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max']);
+      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max', 'clear-input']);
       if (refocusActions.has(action) ||
           ((action === 'clear' || action === 'compact') && this._confirmAction)) {
         if (typeof app !== 'undefined' && app.terminal) {
@@ -207,6 +544,12 @@ const KeyboardAccessoryBar = {
       case 'paste':
         this.pasteFromClipboard();
         break;
+      case 'pick-path':
+        this.pickPath();
+        break;
+      case 'clear-input':
+        app.clearTerminalInput?.();
+        break;
       case 'dismiss':
         // Blur active element to dismiss keyboard
         document.activeElement?.blur();
@@ -265,6 +608,22 @@ const KeyboardAccessoryBar = {
     }).catch(() => {});
   },
 
+  /** Browse the active session's workspace and insert a selected path without Enter. */
+  pickPath() {
+    if (!app.activeSessionId) return;
+    const session = app.sessions?.get(app.activeSessionId);
+    PathPicker.open({
+      title: 'Insert File or Folder Path',
+      sessionId: app.activeSessionId,
+      initialPath: session?.workingDir || '',
+      directoriesOnly: false,
+      onSelect: (path) => {
+        app.insertTerminalText?.(path);
+        setTimeout(() => app.terminal?.focus(), 100);
+      },
+    });
+  },
+
   /** Show a paste overlay for iOS compatibility.
    *  Handles three input paths from one dialog:
    *   - Text: long-press the textarea → Paste → Send (unchanged).

src/web/public/mobile-overview.js

@@ -0,0 +1,690 @@
+/**
+ * @fileoverview Phone home screen: a scrolling overview of what every session is
+ * doing, shown instead of the welcome overlay when the "C" logo is tapped.
+ *
+ * The welcome screen answers "how do I start something"; on a phone the more
+ * urgent question is "which of my sessions is blocked on me". This surface
+ * answers that first: NEEDS YOU (pending permission/question/idle hooks and
+ * errored sessions), then SPACES (cases, expandable to their sessions), then
+ * WORKING and IDLE / DONE.
+ *
+ * PHONE ONLY. The gate is `shouldUseMobileOverview()` (viewport < 430px, not a
+ * popped-out solo window, per-device setting on). Tablet and desktop keep the
+ * welcome overlay untouched. The container ships with the `hidden` attribute and
+ * only this module removes it, so desktop (which never loads mobile.css) cannot
+ * render an unstyled overview even if a class rule leaked.
+ *
+ * Everything renders from state the page already holds (`this.sessions`,
+ * `this.cases`, `this.pendingHooks`) — no endpoint, no SSE event, no schema.
+ * `buildMobileOverviewModel()` is pure and unit-tested (test/mobile-overview.test.ts).
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (this.sessions, this.cases, this.pendingHooks, selectSession, run)
+ * @dependency mobile-handlers.js (MobileDetection)
+ * @dependency session-ui.js (selectQuickStartCase for "New session here")
+ * @loadorder 12.55 of 16, after webview-tabs.js, before entrance-animations.js
+ */
+
+/** Viewport width that counts as a phone. Matches the mobile.css phone block. */
+const MOBILE_OVERVIEW_PHONE_QUERY = '(max-width: 430px)';
+
+/** Sort rank per state: the most demanding thing sorts first inside a section. */
+const MOBILE_OVERVIEW_STATE_RANK = {
+  needs: 0,
+  error: 1,
+  waiting: 2,
+  working: 3,
+  idle: 4,
+  done: 5,
+};
+
+/** How many past conversations show before the "Show all" toggle. */
+const MOBILE_OVERVIEW_PAST_LIMIT = 8;
+
+/**
+ * Backends offered by the Run picker, mirroring the toolbar's run-mode menu
+ * (`#runModeMenu` in index.html). `short` is the badge on the Run button itself.
+ */
+const MOBILE_OVERVIEW_RUN_MODES = [
+  { mode: 'claude', label: 'Claude Code', short: 'Claude' },
+  { mode: 'opencode', label: 'OpenCode', short: 'OpenCode' },
+  { mode: 'codex', label: 'Codex', short: 'Codex' },
+  { mode: 'gemini', label: 'Gemini', short: 'Gemini' },
+  { mode: 'antigravity', label: 'Antigravity', short: 'Antigravity' },
+  { mode: 'shell', label: 'Terminal / Shell', short: 'Shell' },
+];
+
+/** Pill copy per state. Kept short: a phone row has ~90px for it. */
+const MOBILE_OVERVIEW_PILL_LABEL = {
+  needs: 'needs you',
+  error: 'error',
+  waiting: 'waiting',
+  working: 'working',
+  idle: 'idle',
+  done: 'done',
+};
+
+Object.assign(CodemanApp.prototype, {
+  // ═══════════════════════════════════════════════════════════════
+  // Model (pure)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Classify one session.
+   * Order matters: an action hook outranks everything (it is literally blocking
+   * the agent), and a pending idle_prompt outranks a stale 'busy' status because
+   * the hook is the newer signal.
+   * @param {object} session session state from this.sessions
+   * @param {Set<string>|undefined} hooks pending hook types for that session
+   * @returns {'needs'|'error'|'waiting'|'working'|'idle'|'done'}
+   */
+  _mobileOverviewState(session, hooks) {
+    if (hooks && (hooks.has('permission_prompt') || hooks.has('elicitation_dialog'))) return 'needs';
+    if (session.status === 'error') return 'error';
+    if (hooks && hooks.has('idle_prompt')) return 'waiting';
+    if (session.status === 'busy') return 'working';
+    if (session.status === 'stopped') return 'done';
+    return 'idle';
+  },
+
+  /**
+   * Longest-prefix match of a workingDir against the case list, so a session
+   * started in a subdirectory still belongs to its case. Mirrors the matching in
+   * `_resolveCaseLabel()` (terminal-ui.js) but returns the case itself.
+   * @returns {object|null} the matching case, or null when the dir is outside every case
+   */
+  _mobileOverviewCaseFor(workingDir, cases) {
+    if (!workingDir) return null;
+    let best = null;
+    for (const c of cases || []) {
+      if (!c || !c.path) continue;
+      if (workingDir === c.path) return c;
+      if (workingDir.startsWith(c.path + '/') && (!best || c.path.length > best.path.length)) {
+        best = c;
+      }
+    }
+    return best;
+  },
+
+  /**
+   * Build the whole overview model. PURE: reads only its argument, touches no DOM
+   * and no `this` state, so it can be unit-tested against plain objects.
+   *
+   * @param {object} input
+   * @param {Map<string, object>|Array} input.sessions live sessions (this.sessions)
+   * @param {Array} input.cases case list (this.cases)
+   * @param {Array<string>} [input.sessionOrder] the user's tab order, used as the tiebreak
+   * @param {Map<string, Set<string>>} [input.pendingHooks] this.pendingHooks
+   * @param {Array} [input.history] unified session items (GET /api/sessions/unified)
+   * @returns {{needsYou: Array, current: Array, past: Array, sessionCount: number}}
+   */
+  buildMobileOverviewModel(input) {
+    const cases = Array.isArray(input && input.cases) ? input.cases : [];
+    const order = Array.isArray(input && input.sessionOrder) ? input.sessionOrder : [];
+    const pendingHooks = (input && input.pendingHooks) || new Map();
+    const raw = (input && input.sessions) || [];
+    const sessions = typeof raw.values === 'function' ? Array.from(raw.values()) : Array.from(raw);
+
+    const rows = sessions.map((session) => {
+      const matched = this._mobileOverviewCaseFor(session.workingDir, cases);
+      const state = this._mobileOverviewState(session, pendingHooks.get && pendingHooks.get(session.id));
+      const orderIndex = order.indexOf(session.id);
+      return {
+        id: session.id,
+        name: this.getSessionName ? this.getSessionName(session) : session.name || session.id.slice(0, 8),
+        mode: session.mode || 'claude',
+        caseName: matched ? matched.name : '',
+        dir: this._shortenHomePath ? this._shortenHomePath(session.workingDir) : session.workingDir || '',
+        state,
+        pill: MOBILE_OVERVIEW_PILL_LABEL[state] || state,
+        orderIndex: orderIndex === -1 ? Number.MAX_SAFE_INTEGER : orderIndex,
+      };
+    });
+
+    const bySeverityThenOrder = (a, b) => {
+      const rank = MOBILE_OVERVIEW_STATE_RANK[a.state] - MOBILE_OVERVIEW_STATE_RANK[b.state];
+      return rank !== 0 ? rank : a.orderIndex - b.orderIndex;
+    };
+
+    const inSection = (states) => rows.filter((r) => states.includes(r.state)).sort(bySeverityThenOrder);
+
+    // Past = conversations from the unified list that are not currently live.
+    // The endpoint already folds a transcript into its owning session (via the
+    // claudeSessionId alias map), so a plain id check is enough to avoid listing
+    // a running session twice.
+    const liveIds = new Set(rows.map((r) => r.id));
+    const past = (Array.isArray(input && input.history) ? input.history : [])
+      .filter((item) => item && item.sessionId && !liveIds.has(item.sessionId))
+      .map((item) => {
+        const matched = this._mobileOverviewCaseFor(item.workingDir, cases);
+        const dir = item.workingDir || '';
+        // The transcript reader emits the literal "(no content)" for a
+        // conversation it could not pull a prompt from; that is not a title.
+        const prompt = (item.firstPrompt || '').trim();
+        const title = prompt && prompt !== '(no content)' ? prompt : '';
+        return {
+          id: item.sessionId,
+          claudeSessionId: item.claudeSessionId || '',
+          workingDir: dir,
+          name: item.name || '',
+          title: title || item.name || dir.split('/').pop() || item.sessionId.slice(0, 8),
+          mode: item.mode || 'claude',
+          caseName: matched ? matched.name : '',
+          dir: this._shortenHomePath ? this._shortenHomePath(dir) : dir,
+          at: item.lastActivityAt || item.createdAt || 0,
+        };
+      })
+      .sort((a, b) => b.at - a.at);
+
+    return {
+      needsYou: inSection(['needs', 'error', 'waiting']),
+      current: inSection(['working', 'idle', 'done']),
+      past,
+      sessionCount: rows.length,
+    };
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Gate + visibility
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Phone-only gate. Width-driven (not `isHandheldDevice()`): this is a LAYOUT
+   * decision, and an unfolded foldable with a tablet-width viewport should get
+   * the tablet welcome screen. Per-device settings identity is a separate
+   * question and deliberately stays handheld-based.
+   */
+  shouldUseMobileOverview() {
+    if (this.isSoloWindow) return false;
+    const settings = this.loadAppSettingsFromStorage ? this.loadAppSettingsFromStorage() : {};
+    if (settings.mobileOverviewEnabled === false) return false;
+    if (typeof MobileDetection !== 'undefined' && MobileDetection.getDeviceType) {
+      return MobileDetection.getDeviceType() === 'mobile';
+    }
+    return !!(window.matchMedia && window.matchMedia(MOBILE_OVERVIEW_PHONE_QUERY).matches);
+  },
+
+  /** True while the overview is the visible home surface. */
+  isMobileOverviewVisible() {
+    const el = document.getElementById('mobileOverview');
+    return !!el && el.classList.contains('visible');
+  },
+
+  showMobileOverview() {
+    const el = document.getElementById('mobileOverview');
+    if (!el) return;
+    el.hidden = false;
+    el.classList.add('visible');
+    this._wireMobileOverview(el);
+    this.renderMobileOverview();
+    void this.loadMobileOverviewHistory();
+  },
+
+  hideMobileOverview() {
+    const el = document.getElementById('mobileOverview');
+    if (!el) return;
+    this._closeMobileOverviewRunMenu();
+    el.classList.remove('visible');
+    el.hidden = true;
+  },
+
+  /**
+   * Past conversations, fetched once per home-screen visit. The unified list is
+   * the same source the welcome screen resumes from, so a row resumed here and a
+   * row resumed there behave identically. Failures leave the section out rather
+   * than showing an error: the live sessions above it are the important part.
+   */
+  async loadMobileOverviewHistory() {
+    if (this._mobileOverviewHistoryLoading) return;
+    this._mobileOverviewHistoryLoading = true;
+    try {
+      this._mobileOverviewHistory = await this._fetchUnifiedSessions(60);
+    } catch (err) {
+      console.warn('[mobile-overview] history load failed:', err);
+      this._mobileOverviewHistory = this._mobileOverviewHistory || [];
+    } finally {
+      this._mobileOverviewHistoryLoading = false;
+      if (this.isMobileOverviewVisible()) this.renderMobileOverview();
+    }
+  },
+
+  /** Re-render only when the surface is actually showing (called from the tab renderer). */
+  _refreshMobileOverviewIfVisible() {
+    if (!this.isMobileOverviewVisible()) return;
+    this._debouncedCall('mobileOverview', () => this.renderMobileOverview(), 150);
+  },
+
+  /**
+   * One delegated click listener for every row, plus a breakpoint listener so
+   * rotating or unfolding while on the home screen swaps to the right surface
+   * instead of stranding a phone layout on a tablet-width viewport.
+   */
+  _wireMobileOverview(el) {
+    if (this._mobileOverviewWired) return;
+    this._mobileOverviewWired = true;
+
+    el.addEventListener('click', (event) => {
+      const target = event.target && event.target.closest && event.target.closest('[data-mo-action]');
+      if (!target) return;
+      const action = target.dataset.moAction;
+      if (action === 'session') {
+        this._closeMobileOverviewRunMenu();
+        void this.selectSession(target.dataset.moSession);
+      } else if (action === 'resume') {
+        this._closeMobileOverviewRunMenu();
+        void this.resumeMobileOverviewSession(target.dataset.moSession);
+      } else if (action === 'more-past') {
+        this._mobileOverviewShowAllPast = !this._mobileOverviewShowAllPast;
+        this.renderMobileOverview();
+      } else if (action === 'run') {
+        this._closeMobileOverviewRunMenu();
+        void this.run();
+      } else if (action === 'run-menu') {
+        this._toggleMobileOverviewRunMenu();
+      } else if (action === 'run-mode') {
+        // Picking a backend both selects it (so the Run button keeps meaning what
+        // you last chose, exactly like the toolbar) and launches it: on a phone
+        // the pick IS the intent to start.
+        this._closeMobileOverviewRunMenu();
+        this.setRunMode(target.dataset.moMode);
+        void this.run();
+      } else if (action === 'run-webview') {
+        this._closeMobileOverviewRunMenu();
+        void this.openWebviewFromMenu(target.dataset.moWebview);
+      } else if (action === 'run-add-url') {
+        this._closeMobileOverviewRunMenu();
+        this.showWebviewModal();
+      }
+    });
+
+    if (window.matchMedia) {
+      const mq = window.matchMedia(MOBILE_OVERVIEW_PHONE_QUERY);
+      const onChange = () => {
+        // Only relevant while a home surface is up; entering a session re-decides
+        // through hideWelcome()/showWelcome() anyway.
+        if (this.activeSessionId) return;
+        if (typeof this.showWelcome === 'function') this.showWelcome();
+      };
+      if (mq.addEventListener) mq.addEventListener('change', onChange);
+      else if (mq.addListener) mq.addListener(onChange);
+    }
+  },
+
+  _toggleMobileOverviewRunMenu() {
+    this._mobileOverviewRunMenuOpen = !this._mobileOverviewRunMenuOpen;
+    this.renderMobileOverview();
+  },
+
+  _closeMobileOverviewRunMenu() {
+    if (!this._mobileOverviewRunMenuOpen) return;
+    this._mobileOverviewRunMenuOpen = false;
+    if (this.isMobileOverviewVisible()) this.renderMobileOverview();
+  },
+
+  /**
+   * Resume a past conversation. Delegates to the same resumeHistorySession() the
+   * welcome screen's Resume list uses, so name synthesis, envOverrides and the
+   * resumeSessionId wiring stay in one place.
+   */
+  async resumeMobileOverviewSession(sessionId) {
+    const row = (this._mobileOverviewPastRows || []).find((r) => r.id === sessionId);
+    if (!row || !row.workingDir) return;
+    await this.resumeHistorySession(row.claudeSessionId || row.id, row.workingDir, row.name || undefined);
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Render
+  // ═══════════════════════════════════════════════════════════════
+
+  renderMobileOverview() {
+    const el = document.getElementById('mobileOverview');
+    if (!el) return;
+
+    const model = this.buildMobileOverviewModel({
+      sessions: this.sessions,
+      cases: this.cases,
+      sessionOrder: this.sessionOrder,
+      pendingHooks: this.pendingHooks,
+      history: this._mobileOverviewHistory,
+    });
+    // Resume needs the workingDir/claudeSessionId off the row the user tapped.
+    this._mobileOverviewPastRows = model.past;
+
+    el.replaceChildren();
+    el.appendChild(this._buildMobileOverviewTop());
+
+    if (model.needsYou.length) {
+      el.appendChild(
+        this._buildMobileOverviewSection(
+          'Needs you',
+          model.needsYou.length,
+          model.needsYou.map((r) => this._buildMobileOverviewRow(r))
+        )
+      );
+    }
+
+    el.appendChild(
+      this._buildMobileOverviewSection(
+        'Current sessions',
+        model.current.length,
+        model.current.map((r) => this._buildMobileOverviewRow(r)),
+        'Nothing running. Hit Run to start something.'
+      )
+    );
+
+    el.appendChild(
+      this._buildMobileOverviewSection(
+        'Past sessions',
+        model.past.length,
+        this._buildMobileOverviewPast(model),
+        this._mobileOverviewHistory ? 'No past conversations yet' : 'Loading…'
+      )
+    );
+  },
+
+  /**
+   * Past conversations, newest first and capped: the unified list can run to
+   * dozens, and this section sits below the live ones on purpose.
+   */
+  _buildMobileOverviewPast(model) {
+    const showAll = !!this._mobileOverviewShowAllPast;
+    const visible = showAll ? model.past : model.past.slice(0, MOBILE_OVERVIEW_PAST_LIMIT);
+    const children = visible.map((r) => this._buildMobileOverviewPastRow(r));
+    const hiddenCount = model.past.length - visible.length;
+    if (hiddenCount > 0 || showAll) {
+      const toggle = document.createElement('button');
+      toggle.type = 'button';
+      toggle.className = 'mobile-overview-more';
+      toggle.dataset.moAction = 'more-past';
+      const label = document.createElement('span');
+      label.textContent = showAll ? 'Show fewer' : 'Show all past sessions';
+      toggle.appendChild(label);
+      if (!showAll) {
+        const count = document.createElement('span');
+        count.className = 'mobile-overview-more-count';
+        count.setAttribute('data-i18n-skip', '');
+        count.textContent = String(hiddenCount);
+        toggle.appendChild(count);
+      }
+      children.push(toggle);
+    }
+    return children;
+  },
+
+  _buildMobileOverviewTop() {
+    const wrap = document.createElement('div');
+    wrap.className = 'mobile-overview-header';
+
+    const top = document.createElement('div');
+    top.className = 'mobile-overview-top';
+
+    const brand = document.createElement('span');
+    brand.className = 'mobile-overview-brand';
+    brand.textContent = (window.CodemanI18n && window.CodemanI18n.displayName) || 'Codeman';
+    brand.setAttribute('data-i18n-skip', '');
+    top.appendChild(brand);
+
+    // Split button carrying the TOOLBAR's own classes (`btn-toolbar btn-run
+    // mode-<mode>` / `btn-run-gear`), so the per-backend gradient, border and
+    // text color come from the same rules as the Run button in the toolbar and
+    // stay in sync with it for free. mobile.css only sizes it.
+    const group = document.createElement('div');
+    group.className = 'mobile-overview-run-group';
+
+    const mode = this.runMode || 'claude';
+    const run = document.createElement('button');
+    run.className = `btn-toolbar btn-run mode-${mode} mobile-overview-run`;
+    run.type = 'button';
+    run.dataset.moAction = 'run';
+    const runLabel = document.createElement('span');
+    runLabel.textContent = 'Run';
+    run.appendChild(runLabel);
+    const runMode = document.createElement('span');
+    runMode.className = 'mobile-overview-run-mode';
+    runMode.setAttribute('data-i18n-skip', '');
+    runMode.textContent = MOBILE_OVERVIEW_RUN_MODES.find((m) => m.mode === mode)?.short || mode;
+    run.appendChild(runMode);
+    group.appendChild(run);
+
+    const caret = document.createElement('button');
+    caret.className = `btn-toolbar btn-run-gear mode-${mode} mobile-overview-run-caret`;
+    caret.type = 'button';
+    caret.dataset.moAction = 'run-menu';
+    caret.setAttribute('aria-label', 'Choose what to run');
+    caret.setAttribute('aria-expanded', String(!!this._mobileOverviewRunMenuOpen));
+    // An SVG chevron, not a "⌄" glyph: the character carries its own baseline
+    // offset, so it sits visibly low in a flex-centered box no matter what the
+    // line-height says. A path is centered by geometry. Same shape the toolbar's
+    // run-mode gear uses.
+    caret.appendChild(this._buildMobileOverviewChevron());
+    group.appendChild(caret);
+
+    top.appendChild(group);
+    wrap.appendChild(top);
+
+    if (this._mobileOverviewRunMenuOpen) wrap.appendChild(this._buildMobileOverviewRunMenu());
+    return wrap;
+  },
+
+  /** Down chevron as SVG (see the note at its call site). */
+  _buildMobileOverviewChevron() {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '2.5');
+    svg.setAttribute('stroke-linecap', 'round');
+    svg.setAttribute('stroke-linejoin', 'round');
+    svg.setAttribute('aria-hidden', 'true');
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', 'M6 9l6 6 6-6');
+    svg.appendChild(path);
+    return svg;
+  },
+
+  /**
+   * The Run picker: the same backends as the toolbar's run-mode menu, plus saved
+   * web tabs. Deliberately no "Recent Sessions" block, unlike the toolbar menu:
+   * past conversations have their own section further down this screen.
+   *
+   * Gated the same way as the toolbar's #runModeMenu (isCliAvailable(), shell
+   * exempt) — this list is a separate, hardcoded duplicate of the toolbar's menu
+   * rather than a shared render, so it never picked up #201's gating and offered
+   * every backend regardless of what's actually installed.
+   */
+  _buildMobileOverviewRunMenu() {
+    const menu = document.createElement('div');
+    menu.className = 'mobile-overview-run-menu';
+    const current = this.runMode || 'claude';
+
+    for (const entry of MOBILE_OVERVIEW_RUN_MODES) {
+      if (entry.mode !== 'shell' && !this.isCliAvailable(entry.mode)) continue;
+      const option = document.createElement('button');
+      option.type = 'button';
+      option.className = 'mobile-overview-run-option' + (entry.mode === current ? ' selected' : '');
+      option.dataset.moAction = 'run-mode';
+      option.dataset.moMode = entry.mode;
+      const dot = document.createElement('span');
+      dot.className = 'run-mode-dot ' + entry.mode;
+      dot.setAttribute('aria-hidden', 'true');
+      option.appendChild(dot);
+      const label = document.createElement('span');
+      label.textContent = entry.label;
+      option.appendChild(label);
+      menu.appendChild(option);
+    }
+
+    const header = document.createElement('div');
+    header.className = 'mobile-overview-run-header';
+    header.textContent = 'Web / URL';
+    menu.appendChild(header);
+
+    for (const webview of this.webviews ? this.webviews.values() : []) {
+      const option = document.createElement('button');
+      option.type = 'button';
+      option.className = 'mobile-overview-run-option';
+      option.dataset.moAction = 'run-webview';
+      option.dataset.moWebview = webview.id;
+      const dot = document.createElement('span');
+      dot.className = 'run-mode-dot web';
+      dot.setAttribute('aria-hidden', 'true');
+      option.appendChild(dot);
+      const label = document.createElement('span');
+      // A dashboard name is user content.
+      label.className = 'case-name';
+      label.textContent = webview.name;
+      option.appendChild(label);
+      menu.appendChild(option);
+    }
+
+    const add = document.createElement('button');
+    add.type = 'button';
+    add.className = 'mobile-overview-run-option mobile-overview-run-option--add';
+    add.dataset.moAction = 'run-add-url';
+    const addDot = document.createElement('span');
+    addDot.className = 'run-mode-dot web';
+    addDot.setAttribute('aria-hidden', 'true');
+    add.appendChild(addDot);
+    const addLabel = document.createElement('span');
+    addLabel.textContent = 'Add URL…';
+    add.appendChild(addLabel);
+    menu.appendChild(add);
+
+    return menu;
+  },
+
+  _buildMobileOverviewSection(title, count, children, emptyText) {
+    const section = document.createElement('section');
+    section.className = 'mobile-overview-section';
+
+    const heading = document.createElement('h2');
+    heading.className = 'mobile-overview-heading';
+    const label = document.createElement('span');
+    label.textContent = title;
+    heading.appendChild(label);
+    const badge = document.createElement('span');
+    badge.className = 'mobile-overview-heading-count';
+    badge.textContent = String(count);
+    badge.setAttribute('data-i18n-skip', '');
+    heading.appendChild(badge);
+    section.appendChild(heading);
+
+    if (!children.length && emptyText) {
+      const empty = document.createElement('p');
+      empty.className = 'mobile-overview-empty';
+      empty.textContent = emptyText;
+      section.appendChild(empty);
+      return section;
+    }
+    for (const child of children) section.appendChild(child);
+    return section;
+  },
+
+  /**
+   * A session row. The state class drives the same visual language as the
+   * session tabs: green dot when it is fine (pulsing while working), a yellow
+   * blinking row when it wants input, a red blinking row when it asked a
+   * question. Anything else here would mean two different meanings for the same
+   * colors on one screen.
+   */
+  _buildMobileOverviewRow(row) {
+    const item = document.createElement('button');
+    item.type = 'button';
+    item.className = 'mobile-overview-row mobile-overview-row--' + row.state;
+    item.dataset.moAction = 'session';
+    item.dataset.moSession = row.id;
+
+    const dot = document.createElement('span');
+    dot.className = 'mobile-overview-dot mobile-overview-dot--' + row.state;
+    dot.setAttribute('aria-hidden', 'true');
+    item.appendChild(dot);
+
+    const body = document.createElement('span');
+    body.className = 'mobile-overview-row-body';
+
+    const line1 = document.createElement('span');
+    line1.className = 'mobile-overview-row-title';
+    const name = document.createElement('span');
+    // .session-name is in the i18n skip list: a session name is user content.
+    name.className = 'session-name';
+    name.textContent = row.name;
+    line1.appendChild(name);
+    if (row.caseName) {
+      const meta = document.createElement('span');
+      meta.className = 'mobile-overview-row-case case-name';
+      meta.textContent = ' · ' + row.caseName;
+      line1.appendChild(meta);
+    }
+    body.appendChild(line1);
+
+    const line2 = document.createElement('span');
+    line2.className = 'mobile-overview-row-sub';
+    line2.setAttribute('data-i18n-skip', '');
+    line2.textContent = row.mode + (row.dir ? ' · ' + row.dir : '');
+    body.appendChild(line2);
+
+    item.appendChild(body);
+
+    const pill = document.createElement('span');
+    pill.className = 'mobile-overview-pill mobile-overview-pill--' + row.state;
+    // Skipped by i18n on purpose: the labels are generic single words ("idle",
+    // "done", "error") that collide with state strings on other surfaces.
+    pill.setAttribute('data-i18n-skip', '');
+    pill.textContent = row.pill;
+    item.appendChild(pill);
+
+    const chevron = document.createElement('span');
+    chevron.className = 'mobile-overview-chevron';
+    chevron.setAttribute('aria-hidden', 'true');
+    chevron.textContent = '›';
+    item.appendChild(chevron);
+
+    return item;
+  },
+
+  /** A past conversation. Tapping it resumes, which creates a fresh session. */
+  _buildMobileOverviewPastRow(row) {
+    const item = document.createElement('button');
+    item.type = 'button';
+    item.className = 'mobile-overview-row mobile-overview-row--past';
+    item.dataset.moAction = 'resume';
+    item.dataset.moSession = row.id;
+
+    const dot = document.createElement('span');
+    dot.className = 'mobile-overview-dot mobile-overview-dot--past';
+    dot.setAttribute('aria-hidden', 'true');
+    item.appendChild(dot);
+
+    const body = document.createElement('span');
+    body.className = 'mobile-overview-row-body';
+
+    const title = document.createElement('span');
+    // A first prompt is user content, never app copy.
+    title.className = 'mobile-overview-row-title session-name';
+    title.textContent = row.title;
+    body.appendChild(title);
+
+    const sub = document.createElement('span');
+    sub.className = 'mobile-overview-row-sub';
+    sub.setAttribute('data-i18n-skip', '');
+    const when = row.at && this._formatTimeAgo ? this._formatTimeAgo(row.at) : '';
+    sub.textContent = [row.caseName || row.dir, when].filter(Boolean).join(' · ');
+    body.appendChild(sub);
+
+    item.appendChild(body);
+
+    const pill = document.createElement('span');
+    pill.className = 'mobile-overview-pill mobile-overview-pill--past';
+    pill.textContent = 'resume';
+    pill.setAttribute('data-i18n-skip', '');
+    item.appendChild(pill);
+
+    const chevron = document.createElement('span');
+    chevron.className = 'mobile-overview-chevron';
+    chevron.setAttribute('aria-hidden', 'true');
+    chevron.textContent = '›';
+    item.appendChild(chevron);
+
+    return item;
+  },
+});

src/web/public/mobile.css

@@ -839,6 +839,20 @@ html.mobile-init .file-browser-panel {
     border-color: rgba(96, 165, 250, 0.5);
   }
 
+  /* Antigravity mode colors on mobile */
+  .btn-toolbar.btn-run.mode-antigravity,
+  .btn-toolbar.btn-run-gear.mode-antigravity {
+    background: #0b2b33;
+    border-color: rgba(34, 211, 238, 0.3);
+    color: #cffafe;
+  }
+
+  .btn-toolbar.btn-run.mode-antigravity:active,
+  .btn-toolbar.btn-run-gear.mode-antigravity:active {
+    background: #0e7490;
+    border-color: rgba(34, 211, 238, 0.5);
+  }
+
   /* Run mode dropdown menu — positioned above toolbar on mobile */
   .run-mode-menu {
     bottom: 100%;
@@ -855,6 +869,17 @@ html.mobile-init .file-browser-panel {
     -webkit-tap-highlight-color: rgba(255, 255, 255, 0.1);
   }
 
+  /* Per-URL edit/delete in the Web / URL list need a real touch target, and they
+     sit next to the row's own tap area, so they get sized up rather than relying
+     on the 24px desktop hit box. */
+  .run-mode-row-btn {
+    width: 34px;
+    height: 34px;
+    font-size: 1rem;
+    -webkit-tap-highlight-color: rgba(255, 255, 255, 0.1);
+  }
+  .run-mode-webview-delete { font-size: 1.2rem; }
+
   .run-mode-history {
     -webkit-overflow-scrolling: touch;
     touch-action: manipulation;
@@ -875,19 +900,44 @@ html.mobile-init .file-browser-panel {
     margin-right: 0;
   }
 
-  /* Secondary action - Run Shell - right side */
+  /* Shell is NOT a toolbar button on phones — it moved into the Run dropdown
+     (Terminal / Shell), freeing this slot for Enter. Starting a shell is a rare,
+     deliberate act; sending Enter is a constant one, so the scarce phone real
+     estate goes to Enter. */
   .btn-toolbar.btn-shell {
-    flex: 0 0 auto;
-    background: transparent;
-    border: 1px solid rgba(255, 255, 255, 0.2);
-    color: #9ca3af;
-    order: 4; /* Right position */
+    display: none !important;
   }
 
-  .btn-toolbar.btn-shell:hover,
-  .btn-toolbar.btn-shell:active {
-    background: rgba(255, 255, 255, 0.1);
-    color: #fff;
+  /* Secondary action - Enter - right side. Takes the slot (and the order) the
+     Shell button used to hold, so the toolbar rhythm is unchanged. */
+  .btn-toolbar.btn-enter {
+    display: flex !important;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    min-width: 54px;
+    width: 54px;
+    white-space: nowrap;
+    padding: 0 8px !important;
+    overflow: hidden;
+    font-size: 0.65rem;
+    font-weight: 600;
+    letter-spacing: 0.01em;
+    /* !important is REQUIRED here, not defensive habit: styles.css nests its skin
+       overrides inside `html:not([data-skin="og"]) { … }`, so a plain `.btn-toolbar`
+       in that block resolves to (0,2,1) and outranks this (0,2,0) rule. Without
+       !important the button silently renders in generic toolbar grey. */
+    background: rgba(30, 58, 95, 0.85) !important;
+    border: 1px solid rgba(59, 130, 246, 0.45) !important;
+    color: #dbeafe !important;
+    order: 4; /* Right position — same slot Shell used to occupy */
+  }
+
+  .btn-toolbar.btn-enter:hover,
+  .btn-toolbar.btn-enter:active {
+    background: rgba(37, 74, 122, 0.95) !important;
+    border-color: rgba(59, 130, 246, 0.7) !important;
+    color: #fff !important;
   }
 
   /* Hide case selector on mobile - simplified toolbar */
@@ -895,27 +945,12 @@ html.mobile-init .file-browser-panel {
     display: none !important;
   }
 
-  /* Simplified toolbar layout — Run, Shell, and Case */
+  /* Simplified toolbar layout — Run, Enter, and Case */
   .toolbar-left .toolbar-group:first-child {
     width: 100%;
     gap: 8px;
   }
 
-  .btn-toolbar.btn-shell {
-    flex: 0 0 auto;
-    min-width: 54px;
-    width: 54px;
-    white-space: nowrap;
-    padding: 0 8px !important;
-    overflow: hidden;
-    font-size: 0 !important;
-  }
-
-  .btn-toolbar.btn-shell::after {
-    content: "Shell";
-    font-size: 0.65rem;
-  }
-
   /* Mobile case button - visible on mobile */
   .btn-toolbar.btn-case-mobile {
     display: flex !important;
@@ -1836,6 +1871,33 @@ html.mobile-init .file-browser-panel {
     bottom: calc(44px + 2rem + var(--safe-area-bottom));
   }
 
+  /* File preview window: full screen on phones. --app-height tracks the visual
+     viewport (KeyboardHandler), so the edit textarea + Save bar stay above the
+     OS keyboard instead of hiding behind it. Footer/edit bar pad for the home
+     indicator. */
+  .file-preview-window {
+    width: 100vw;
+    max-width: 100vw;
+    height: var(--app-height, 100vh);
+    max-height: var(--app-height, 100vh);
+    border-radius: 0;
+    border-left: none;
+    border-right: none;
+  }
+
+  .file-preview-editbar {
+    padding-bottom: calc(0.4rem + var(--safe-area-bottom));
+  }
+
+  .file-preview-overlay .file-preview-footer {
+    padding-bottom: calc(0.35rem + var(--safe-area-bottom));
+  }
+
+  /* >=16px or iOS Safari auto-zooms the page on focus */
+  .file-preview-body textarea.file-preview-editor {
+    font-size: 16px;
+  }
+
   /* Notification drawer - full width on mobile, includes safe area padding */
   .notification-drawer {
     width: 100%;
@@ -2224,6 +2286,501 @@ html.mobile-init .file-browser-panel {
     border-radius: 8px;
     transform: none !important;
   }
+
+  /* ---- Mobile Overview (phone home screen) ----
+     Shown in place of the welcome overlay when the C logo is tapped. Styled only
+     with :root tokens so every skin, including the four light ones, works with
+     no override block. Never give .mobile-overview itself a display value: the
+     element ships with [hidden] and only .visible may turn it on. */
+
+  .mobile-overview.visible {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 10;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    padding: 0.75rem 0.6rem calc(1rem + var(--safe-area-bottom));
+    background: var(--bg-dark);
+    overflow-y: auto;
+    -webkit-overflow-scrolling: touch;
+    overscroll-behavior: contain;
+  }
+
+  /* No side padding: the wordmark's left edge lines up with the session cards
+     below it, and the Run button's right edge with theirs. */
+  .mobile-overview-top {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    padding: 0;
+  }
+
+  /* Same accent as the "C" in the header (`.logo` uses --accent-hover), and the
+     same 48px box as the Run button opposite it, so the two are centered on one
+     line by construction rather than by eye. */
+  .mobile-overview-brand {
+    display: inline-flex;
+    align-items: center;
+    min-height: 48px;
+    font-size: 1.5rem;
+    font-weight: 800;
+    line-height: 1;
+    color: var(--accent-hover);
+    letter-spacing: -0.02em;
+  }
+
+  /* Split Run button. Colors come from the toolbar's own
+     `.btn-toolbar.btn-run.mode-<backend>` rules in styles.css (the element
+     carries those classes), so this button and the one in the toolbar are the
+     same control in two places. Only size/shape is set here, and NOTHING that
+     would override the mode gradient. */
+  .mobile-overview-header {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .mobile-overview-run-group {
+    display: flex;
+    align-items: stretch;
+    flex-shrink: 0;
+  }
+
+  /* Sized well past the 44px touch minimum: this is the primary action on the
+     home screen, and the caret is a separate target right next to it.
+     ⚠️ The !important is required, not decorative: the phone block clamps every
+     .btn-toolbar to `height/min-height/max-height: 26px !important`, and this
+     button deliberately carries .btn-toolbar to inherit the run-mode gradient.
+     Without matching !important (max-height included) it renders 26px tall. */
+  .mobile-overview-run-group .mobile-overview-run {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    min-height: 48px !important;
+    height: 48px !important;
+    max-height: 48px !important;
+    padding: 0 1.15rem !important;
+    font-size: 0.95rem !important;
+    line-height: 1;
+    font-weight: 700;
+    font-family: inherit;
+    border-radius: 10px 0 0 10px !important;
+  }
+
+  .mobile-overview-run-mode {
+    font-weight: 600;
+    font-size: 0.85rem;
+    opacity: 0.8;
+  }
+
+  .mobile-overview-run-group .mobile-overview-run-caret {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 48px !important;
+    height: 48px !important;
+    max-height: 48px !important;
+    min-width: 48px !important;
+    width: 48px !important;
+    padding: 0 !important;
+    line-height: 1;
+    font-family: inherit;
+    border-radius: 0 10px 10px 0 !important;
+  }
+
+  /* The phone block shrinks every run-gear glyph to 10px; this one is a 48px
+     tap target, so it gets a proportionate chevron. `display:block` drops the
+     inline-baseline gap that would otherwise push it a pixel low. */
+  .mobile-overview-run-group .mobile-overview-run-caret svg {
+    display: block;
+    width: 20px !important;
+    height: 20px !important;
+    margin: 0 !important;
+  }
+
+  .mobile-overview-run-menu {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    margin: 0.5rem 0 0;
+    padding: 0.35rem;
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    background: var(--floating-bg);
+    box-shadow: var(--elevated-shadow);
+  }
+
+  .mobile-overview-run-option {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    min-height: 44px;
+    padding: 0 0.6rem;
+    border: none;
+    border-radius: 8px;
+    background: transparent;
+    color: var(--text);
+    font-family: inherit;
+    font-size: 0.82rem;
+    text-align: left;
+  }
+
+  .mobile-overview-run-option.selected {
+    background: var(--control-bg-hover);
+  }
+
+  .mobile-overview-run-option:active {
+    background: var(--bg-hover);
+  }
+
+  .mobile-overview-run-option--add {
+    color: var(--accent);
+  }
+
+  .mobile-overview-run-header {
+    padding: 0.4rem 0.6rem 0.2rem;
+    font-size: 0.6rem;
+    font-weight: 700;
+    letter-spacing: 0.09em;
+    text-transform: uppercase;
+    color: var(--text-muted);
+  }
+
+  .mobile-overview-section {
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+  }
+
+  /* Flush left with the wordmark and the cards: one left edge down the screen. */
+  .mobile-overview-heading {
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+    margin: 0.35rem 0 0;
+    padding: 0;
+    font-size: 0.65rem;
+    font-weight: 700;
+    letter-spacing: 0.09em;
+    text-transform: uppercase;
+    color: var(--text-muted);
+  }
+
+  .mobile-overview-heading-count {
+    color: var(--text-dim);
+    font-weight: 600;
+  }
+
+  .mobile-overview-empty {
+    margin: 0;
+    padding: 0.5rem 0;
+    font-size: 0.75rem;
+    color: var(--text-muted);
+  }
+
+  /* Row: 56px tap target, dot + two-line body + pill + chevron */
+  .mobile-overview-row {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    width: 100%;
+    min-height: 56px;
+    padding: 0.5rem 0.7rem;
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    background: var(--bg-card);
+    color: var(--text);
+    font-family: inherit;
+    text-align: left;
+  }
+
+  .mobile-overview-row:active {
+    background: var(--bg-hover);
+  }
+
+  /* Attention states mirror the session tabs exactly: red blink when the agent
+     asked something (permission / question), yellow blink when it is waiting for
+     a prompt. Same hues and same cadence as tab-blink-red / tab-blink-yellow in
+     styles.css; the keyframes are re-declared here only because a tab's resting
+     background is transparent while a row's is the card color. */
+  .mobile-overview-row--needs {
+    border-color: var(--red);
+    animation: mobile-overview-blink-red 2.5s ease-in-out infinite;
+  }
+
+  .mobile-overview-row--waiting {
+    border-color: var(--yellow);
+    animation: mobile-overview-blink-yellow 3.5s ease-in-out infinite;
+  }
+
+  .mobile-overview-row--error {
+    border-color: var(--red);
+  }
+
+  @keyframes mobile-overview-blink-red {
+    0%,
+    100% {
+      background: var(--bg-card);
+      border-color: var(--border);
+    }
+    50% {
+      background: rgba(239, 68, 68, 0.14);
+      border-color: var(--red);
+    }
+  }
+
+  @keyframes mobile-overview-blink-yellow {
+    0%,
+    100% {
+      background: var(--bg-card);
+      border-color: var(--border);
+    }
+    50% {
+      background: rgba(234, 179, 8, 0.12);
+      border-color: var(--yellow);
+    }
+  }
+
+  .mobile-overview-row-body {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    flex: 1;
+    min-width: 0;
+  }
+
+  .mobile-overview-row-title {
+    display: block;
+    font-size: 0.9rem;
+    font-weight: 600;
+    color: var(--text);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .mobile-overview-row-case {
+    color: var(--text-dim);
+    font-weight: 500;
+  }
+
+  .mobile-overview-row-sub {
+    display: block;
+    font-size: 0.68rem;
+    color: var(--text-muted);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .mobile-overview-dot {
+    flex-shrink: 0;
+    width: 9px;
+    height: 9px;
+    border-radius: 50%;
+    background: var(--text-muted);
+  }
+
+  .mobile-overview-dot--needs,
+  .mobile-overview-dot--error {
+    background: var(--red);
+  }
+
+  .mobile-overview-dot--waiting {
+    background: var(--yellow);
+  }
+
+  /* Same as .session-tab .tab-status: green when the session is fine, and the
+     shared `pulse` keyframes while it is working. */
+  .mobile-overview-dot--working {
+    background: var(--green);
+    animation: pulse 1.5s infinite;
+    will-change: opacity;
+  }
+
+  .mobile-overview-dot--idle {
+    background: var(--green);
+  }
+
+  .mobile-overview-dot--done {
+    background: var(--text-muted);
+    opacity: 0.5;
+  }
+
+  .mobile-overview-pill {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.2rem 0.45rem;
+    border: 1px solid var(--border-light);
+    border-radius: 999px;
+    font-size: 0.62rem;
+    font-weight: 600;
+    color: var(--text-dim);
+    white-space: nowrap;
+  }
+
+  .mobile-overview-pill--needs,
+  .mobile-overview-pill--error {
+    border-color: var(--red);
+    color: var(--red);
+  }
+
+  .mobile-overview-pill--waiting {
+    border-color: var(--yellow);
+    color: var(--yellow);
+  }
+
+  .mobile-overview-pill--idle,
+  .mobile-overview-pill--working {
+    border-color: var(--green);
+    color: var(--green);
+  }
+
+  .mobile-overview-chevron {
+    flex-shrink: 0;
+    color: var(--text-muted);
+    font-size: 1rem;
+    line-height: 1;
+  }
+
+  /* Past conversations: quieter than a live row, since tapping one starts work */
+  .mobile-overview-row--past {
+    background: transparent;
+    border-style: dashed;
+  }
+
+  .mobile-overview-row--past .mobile-overview-row-title {
+    font-weight: 500;
+    color: var(--text-dim);
+  }
+
+  .mobile-overview-dot--past {
+    background: transparent;
+    border: 1px solid var(--border-light);
+  }
+
+  .mobile-overview-pill--past {
+    border-color: var(--border-light);
+    color: var(--text-muted);
+  }
+
+  .mobile-overview-more {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.35rem;
+    min-height: 40px;
+    border: none;
+    border-radius: 10px;
+    background: var(--control-bg);
+    color: var(--text-dim);
+    font-family: inherit;
+    font-size: 0.72rem;
+    font-weight: 600;
+  }
+
+  .mobile-overview-more-count {
+    padding: 0.05rem 0.35rem;
+    border-radius: 999px;
+    background: var(--control-bg-hover);
+    color: var(--text-muted);
+  }
+}
+
+/* The overview's attention blink is an alert, so it stays visible without
+   motion: hold the alert color instead of animating to it. */
+@media (prefers-reduced-motion: reduce) {
+  .mobile-overview-row--needs,
+  .mobile-overview-row--waiting {
+    animation: none;
+  }
+
+  .mobile-overview-row--needs {
+    background: rgba(239, 68, 68, 0.14);
+  }
+
+  .mobile-overview-row--waiting {
+    background: rgba(234, 179, 8, 0.12);
+  }
+
+  .mobile-overview-dot--working {
+    animation: none;
+  }
+}
+
+/* Light-skin compatibility for mobile-only chrome. These components predate
+   the shared skin system and intentionally retain their original dark values
+   for the three dark skins above. */
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.header, .toolbar, .keyboard-accessory-bar) {
+  background: var(--glass-bg);
+  border-color: var(--glass-border);
+  color: var(--text);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile, .btn-settings-mobile, .btn-toolbar.btn-shell, .toolbar .btn-case-add, .accessory-btn) {
+  background: var(--control-bg);
+  border-color: var(--control-border);
+  color: var(--text-dim);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile:active, .btn-settings-mobile:active, .btn-toolbar.btn-shell:hover, .btn-toolbar.btn-shell:active, .btn-case-add:hover, .btn-case-add:active, .accessory-btn:active) {
+  background: var(--control-bg-hover);
+  border-color: var(--control-border-hover);
+  color: var(--text);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-claude, .btn-toolbar.btn-run-gear.mode-claude) {
+  background: linear-gradient(135deg, var(--accent-grad-a), var(--accent-grad-b));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-opencode, .btn-toolbar.btn-run-gear.mode-opencode) {
+  background: linear-gradient(135deg, var(--accent-d), var(--accent-grad-b));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-gemini, .btn-toolbar.btn-run-gear.mode-gemini) {
+  background: linear-gradient(135deg, #174ea6, #4f46e5);
+  border-color: #315fc3;
+  color: #ffffff;
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-antigravity, .btn-toolbar.btn-run-gear.mode-antigravity) {
+  background: linear-gradient(135deg, #0e7490, #0891b2);
+  border-color: #155e75;
+  color: #ffffff;
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) .btn-toolbar.btn-run-gear {
+  border-left-color: var(--control-border-hover) !important;
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.case-settings-popover-mobile, .mobile-case-picker-sheet) {
+  background: var(--floating-bg);
+  border-color: var(--control-border);
+  color: var(--text);
+  box-shadow: var(--elevated-shadow);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.case-settings-popover-mobile .checkbox-inline, #createCaseModal .form-row label) {
+  color: var(--text);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) .case-settings-popover-mobile .form-hint {
+  color: var(--text-muted);
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) .mobile-case-picker .modal-backdrop {
+  background: var(--modal-backdrop);
 }
 
 

src/web/public/notification-manager.js

@@ -9,7 +9,7 @@
  *   5. Audio alerts (Web Audio API beep, user-opt-in)
  *
  * Features:
- * - Per-event-type preferences (enabled, browser, audio, push) with v1→v4 migration
+ * - Per-event-type preferences (enabled, browser, audio, push) with v1→v5 migration
  * - Device-specific defaults (notifications disabled on mobile by default)
  * - 5s notification grouping window to batch rapid-fire events
  * - 100-notification cap with oldest eviction
@@ -21,7 +21,7 @@
  * @param {CodemanApp} app - Reference to the main app instance
  *
  * @dependency constants.js (STUCK_THRESHOLD_DEFAULT_MS, timing constants)
- * @dependency mobile-handlers.js (MobileDetection.getDeviceType for device-specific defaults)
+ * @dependency mobile-handlers.js (MobileDetection stable handheld identity/device type)
  * @loadorder 4 of 15 — loaded after voice-input.js, before keyboard-accessory.js
  */
 
@@ -65,12 +65,19 @@ class NotificationManager {
     });
   }
 
-  loadPreferences() {
+  _usesMobilePreferences() {
+    return (
+      MobileDetection.isHandheldDevice?.() ??
+      MobileDetection.getDeviceType() === 'mobile'
+    );
+  }
+
+  getDefaultPreferences() {
     const defaultEventTypes = {
       permission_prompt: { enabled: true, browser: true, audio: true, push: false },
       elicitation_dialog: { enabled: true, browser: true, audio: true, push: false },
       idle_prompt: { enabled: true, browser: true, audio: false, push: false },
-      stop: { enabled: true, browser: false, audio: false, push: false },
+      stop: { enabled: false, browser: false, audio: false, push: false },
       session_error: { enabled: true, browser: true, audio: false, push: false },
       respawn_cycle: { enabled: true, browser: false, audio: false, push: false },
       token_milestone: { enabled: true, browser: false, audio: false, push: false },
@@ -80,8 +87,8 @@ class NotificationManager {
     };
 
     // Device-specific defaults: mobile has notifications disabled by default
-    const isMobile = MobileDetection.getDeviceType() === 'mobile';
-    const defaults = {
+    const isMobile = this._usesMobilePreferences();
+    return {
       enabled: !isMobile, // Disabled on mobile by default
       browserNotifications: !isMobile,
       audioAlerts: false,
@@ -92,51 +99,97 @@ class NotificationManager {
       muteInfo: false,
       // Per-event-type preferences
       eventTypes: defaultEventTypes,
-      _version: 4,
+      _version: 5,
     };
+  }
+
+  /**
+   * Apply the complete v1→v5 migration to either local or server-hydrated
+   * preferences. Keeping one normalization path prevents fresh browsers from
+   * reviving retired drawer-only hook defaults.
+   */
+  normalizePreferences(rawPreferences) {
+    const defaults = this.getDefaultPreferences();
+    if (
+      !rawPreferences ||
+      typeof rawPreferences !== 'object' ||
+      Array.isArray(rawPreferences)
+    ) {
+      return defaults;
+    }
+
+    const prefs = {
+      ...rawPreferences,
+      eventTypes:
+        rawPreferences.eventTypes &&
+        typeof rawPreferences.eventTypes === 'object' &&
+        !Array.isArray(rawPreferences.eventTypes)
+          ? Object.fromEntries(
+              Object.entries(rawPreferences.eventTypes).map(([key, value]) => [
+                key,
+                value && typeof value === 'object' ? { ...value } : value,
+              ])
+            )
+          : undefined,
+    };
+    const version = Number.isInteger(prefs._version) ? prefs._version : 0;
+
+    // Migrate: v1 had browserNotifications defaulting to false
+    if (version < 2) {
+      prefs.browserNotifications = true;
+    }
+    // Migrate: v2 -> v3 adds eventTypes
+    if (version < 3) {
+      prefs.eventTypes = { ...defaults.eventTypes };
+    }
+    // Migrate: v3 -> v4 adds push field to all eventTypes
+    if (version < 4 && prefs.eventTypes) {
+      for (const key of Object.keys(prefs.eventTypes)) {
+        if (prefs.eventTypes[key] && prefs.eventTypes[key].push === undefined) {
+          prefs.eventTypes[key].push = false;
+        }
+      }
+    }
+    // Migrate: v4 -> v5 removes the drawer-only Response Complete default.
+    // Preserve users who opted into any external delivery channel.
+    if (version < 5) {
+      const stopPref = prefs.eventTypes?.stop;
+      if (
+        stopPref?.enabled === true &&
+        !stopPref.browser &&
+        !stopPref.audio &&
+        !stopPref.push
+      ) {
+        stopPref.enabled = false;
+      }
+    }
+
+    return {
+      ...defaults,
+      ...prefs,
+      eventTypes: { ...defaults.eventTypes, ...prefs.eventTypes },
+      _version: 5,
+    };
+  }
+
+  loadPreferences() {
     try {
       const storageKey = this.getStorageKey();
       const saved = localStorage.getItem(storageKey);
       if (saved) {
-        const prefs = JSON.parse(saved);
-        // Migrate: v1 had browserNotifications defaulting to false
-        if (!prefs._version || prefs._version < 2) {
-          prefs.browserNotifications = true;
-          prefs._version = 2;
-        }
-        // Migrate: v2 -> v3 adds eventTypes
-        if (prefs._version < 3) {
-          prefs.eventTypes = defaultEventTypes;
-          prefs._version = 3;
-          localStorage.setItem(storageKey, JSON.stringify(prefs));
-        }
-        // Migrate: v3 -> v4 adds push field to all eventTypes
-        if (prefs._version < 4) {
-          if (prefs.eventTypes) {
-            for (const key of Object.keys(prefs.eventTypes)) {
-              if (prefs.eventTypes[key] && prefs.eventTypes[key].push === undefined) {
-                prefs.eventTypes[key].push = false;
-              }
-            }
-          }
-          prefs._version = 4;
-          localStorage.setItem(storageKey, JSON.stringify(prefs));
-        }
-        // Merge with defaults to ensure all eventTypes exist
-        return {
-          ...defaults,
-          ...prefs,
-          eventTypes: { ...defaultEventTypes, ...prefs.eventTypes },
-        };
+        const normalized = this.normalizePreferences(JSON.parse(saved));
+        localStorage.setItem(storageKey, JSON.stringify(normalized));
+        return normalized;
       }
     } catch (_e) { /* ignore */ }
-    return defaults;
+    return this.getDefaultPreferences();
   }
 
   // Get storage key for notification prefs (device-specific)
   getStorageKey() {
-    const isMobile = MobileDetection.getDeviceType() === 'mobile';
-    return isMobile ? 'codeman-notification-prefs-mobile' : 'codeman-notification-prefs';
+    return this._usesMobilePreferences()
+      ? 'codeman-notification-prefs-mobile'
+      : 'codeman-notification-prefs';
   }
 
   savePreferences() {
@@ -163,8 +216,10 @@ class NotificationManager {
       'exit-gate': 'ralph_complete',
       'subagent-spawn': 'subagent_spawn',
       'subagent-complete': 'subagent_complete',
-      'hook-teammate-idle': 'idle_prompt',
-      'hook-task-completed': 'stop',
+      // Team lifecycle hooks are agent activity, not session-idle/stop alerts.
+      // Reuse the existing opt-in agent categories instead of making them noisy.
+      'hook-teammate-idle': 'subagent_spawn',
+      'hook-task-completed': 'subagent_complete',
     };
     const eventTypeKey = categoryToEventType[category] || category;
 

src/web/public/panels-ui.js

@@ -426,7 +426,7 @@ Object.assign(CodemanApp.prototype, {
 
   _buildCommandPaletteNewSessionItem(query = '') {
     const mode = this.runMode || this._runMode || 'claude';
-    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini' };
+    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini', antigravity: 'Antigravity' };
     const caseName = this._findCommandPaletteCaseMatch(query) || document.getElementById('quickStartCase')?.value || 'testcase';
     return {
       id: 'new-session',
@@ -2267,6 +2267,7 @@ Object.assign(CodemanApp.prototype, {
 
       const terminal = new Terminal({
         theme: { ...window.codemanCurrentXtermTheme() },
+        minimumContrastRatio: window.codemanCurrentSkinIsLight() ? 4.5 : 1,
         fontFamily: '"Fira Code", "Cascadia Code", "JetBrains Mono", "SF Mono", Monaco, monospace',
         fontSize: 12,
         lineHeight: 1.2,
@@ -3199,6 +3200,9 @@ Object.assign(CodemanApp.prototype, {
 
     if (!overlay || !bodyEl) return;
 
+    // Edit mode: reset any prior editor state whenever a preview (re)loads.
+    this._resetFilePreviewEdit();
+
     // Show overlay with loading state
     overlay.classList.add('visible');
     titleEl.textContent = filePath;
@@ -3297,6 +3301,13 @@ Object.assign(CodemanApp.prototype, {
         bodyEl.innerHTML = `<pre><code>${escapeHtml(data.content)}</code></pre>`;
         const truncNote = data.truncated ? ` (showing 500/${data.totalLines} lines)` : '';
         footerEl.textContent = `${data.totalLines} lines \u2022 ${this.formatFileSize(data.size)}${truncNote}`;
+        // Edit affordance only when the server says an edit=1 re-fetch would
+        // succeed (workspace text file inside the allowlist and size cap).
+        if (data.editable) {
+          this.filePreviewEditTarget = { sessionId, filePath };
+          const editBtn = this.$('filePreviewEditBtn');
+          if (editBtn) editBtn.hidden = false;
+        }
       }
     } catch (err) {
       console.error('Failed to preview file:', err);
@@ -3305,6 +3316,8 @@ Object.assign(CodemanApp.prototype, {
   },
 
   closeFilePreview() {
+    if (this.filePreviewEdit?.dirty && !confirm('Discard unsaved changes?')) return;
+    this._resetFilePreviewEdit();
     const overlay = this.$('filePreviewOverlay');
     if (overlay) {
       overlay.classList.remove('visible');
@@ -3312,6 +3325,172 @@ Object.assign(CodemanApp.prototype, {
     this.filePreviewContent = '';
   },
 
+  // ═══════════════════════════════════════════════════════════════
+  // File Viewer edit mode (issue #212 — docs/file-viewer-edit-plan.md)
+  // ═══════════════════════════════════════════════════════════════
+
+  _resetFilePreviewEdit() {
+    this.filePreviewEdit = null;
+    this.filePreviewEditTarget = null;
+    const editBtn = this.$('filePreviewEditBtn');
+    if (editBtn) editBtn.hidden = true;
+    const editBar = this.$('filePreviewEditBar');
+    if (editBar) editBar.hidden = true;
+    const dirtyEl = this.$('filePreviewDirty');
+    if (dirtyEl) dirtyEl.hidden = true;
+    const saveBtn = this.$('filePreviewSaveBtn');
+    if (saveBtn) {
+      saveBtn.disabled = true;
+      saveBtn.textContent = 'Save';
+    }
+  },
+
+  async enterFilePreviewEdit() {
+    const target = this.filePreviewEditTarget;
+    if (!target || this.filePreviewEdit) return;
+    const bodyEl = this.$('filePreviewBody');
+    const footerEl = this.$('filePreviewFooter');
+    if (!bodyEl) return;
+
+    // Always re-fetch with edit=1: the preview buffer may be line-truncated and
+    // a truncated buffer must never become an edit buffer. Parse the envelope
+    // even on non-ok responses so the specific refusal ("too large to edit
+    // here") reaches the toast instead of a generic failure.
+    let data;
+    try {
+      const res = await fetch(
+        `/api/sessions/${target.sessionId}/file-content?path=${encodeURIComponent(target.filePath)}&edit=1`
+      );
+      const result = await res.json().catch(() => null);
+      if (!result || result.success !== true) {
+        throw new Error(result?.error || `Failed to load file for editing (HTTP ${res.status})`);
+      }
+      data = result.data;
+    } catch (err) {
+      this.showToast(err.message, 'error');
+      return;
+    }
+
+    this.filePreviewEdit = {
+      sessionId: target.sessionId,
+      filePath: target.filePath,
+      baseHash: data.hash,
+      eol: data.eol,
+      original: data.content,
+      dirty: false,
+      saving: false,
+    };
+
+    const textarea = document.createElement('textarea');
+    textarea.className = 'file-preview-editor';
+    textarea.spellcheck = false;
+    textarea.setAttribute('autocapitalize', 'off');
+    textarea.setAttribute('autocorrect', 'off');
+    textarea.setAttribute('autocomplete', 'off');
+    textarea.wrap = 'off';
+    textarea.value = data.content;
+    textarea.addEventListener('input', () => this._onFilePreviewEditInput());
+    bodyEl.innerHTML = '';
+    bodyEl.appendChild(textarea);
+    // Deliberately no autofocus: on phones that would pop the OS keyboard
+    // before the user has scrolled to the line they want to change.
+
+    const editBtn = this.$('filePreviewEditBtn');
+    if (editBtn) editBtn.hidden = true;
+    const editBar = this.$('filePreviewEditBar');
+    if (editBar) editBar.hidden = false;
+    if (footerEl) {
+      const eolNote = data.eol === 'crlf' ? ' • CRLF' : '';
+      footerEl.textContent = `Editing • ${data.totalLines} lines • ${this.formatFileSize(data.size)}${eolNote}`;
+    }
+  },
+
+  _onFilePreviewEditInput() {
+    const edit = this.filePreviewEdit;
+    if (!edit) return;
+    const textarea = this.$('filePreviewBody')?.querySelector('textarea.file-preview-editor');
+    if (!textarea) return;
+    edit.dirty = textarea.value !== edit.original;
+    const dirtyEl = this.$('filePreviewDirty');
+    if (dirtyEl) dirtyEl.hidden = !edit.dirty;
+    const saveBtn = this.$('filePreviewSaveBtn');
+    if (saveBtn) saveBtn.disabled = !edit.dirty || edit.saving;
+  },
+
+  cancelFilePreviewEdit() {
+    const edit = this.filePreviewEdit;
+    if (!edit) return;
+    if (edit.dirty && !confirm('Discard unsaved changes?')) return;
+    const { sessionId, filePath } = edit;
+    this._resetFilePreviewEdit();
+    this.openFilePreview(filePath, sessionId);
+  },
+
+  async saveFilePreviewEdit(force = false) {
+    const edit = this.filePreviewEdit;
+    if (!edit || edit.saving) return;
+    const textarea = this.$('filePreviewBody')?.querySelector('textarea.file-preview-editor');
+    if (!textarea) return;
+
+    edit.saving = true;
+    const saveBtn = this.$('filePreviewSaveBtn');
+    if (saveBtn) {
+      saveBtn.disabled = true;
+      saveBtn.textContent = 'Saving…';
+    }
+    const restoreSaveState = () => {
+      edit.saving = false;
+      if (saveBtn) saveBtn.textContent = 'Save';
+      this._onFilePreviewEditInput();
+    };
+
+    let result = null;
+    let status = 0;
+    try {
+      const res = await fetch(`/api/sessions/${edit.sessionId}/file-content`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          path: edit.filePath,
+          content: textarea.value,
+          baseHash: edit.baseHash,
+          eol: edit.eol ?? undefined, // Zod .optional() rejects null
+          force: force || undefined,
+        }),
+      });
+      status = res.status;
+      result = await res.json().catch(() => null);
+    } catch (err) {
+      restoreSaveState();
+      this.showToast(`Save failed: ${err.message}`, 'error');
+      return;
+    }
+
+    if (status === 409 || result?.errorCode === 'CONFLICT') {
+      restoreSaveState();
+      if (
+        confirm(
+          'File changed on disk since you loaded it.\nOK overwrites it with your version; Cancel keeps your draft open.'
+        )
+      ) {
+        this.saveFilePreviewEdit(true);
+      }
+      return;
+    }
+    if (!result || result.success !== true) {
+      restoreSaveState();
+      this.showToast(`Save failed: ${result?.error || `HTTP ${status}`}`, 'error');
+      return;
+    }
+
+    const { sessionId, filePath } = edit;
+    this._resetFilePreviewEdit();
+    this.showToast('Saved', 'success');
+    // Re-open in read mode — re-fetching shows the truth on disk (including the
+    // server-side EOL normalization) rather than trusting the local buffer.
+    this.openFilePreview(filePath, sessionId);
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // Attachment Cards (detected documents/images)
   // ═══════════════════════════════════════════════════════════════
@@ -3748,8 +3927,13 @@ Object.assign(CodemanApp.prototype, {
   },
 
   copyFilePreviewContent() {
-    if (this.filePreviewContent) {
-      navigator.clipboard.writeText(this.filePreviewContent).then(() => {
+    // While editing, copy the live editor buffer (not the stale preview text).
+    const editTextarea = this.filePreviewEdit
+      ? this.$('filePreviewBody')?.querySelector('textarea.file-preview-editor')
+      : null;
+    const content = editTextarea ? editTextarea.value : this.filePreviewContent;
+    if (content) {
+      navigator.clipboard.writeText(content).then(() => {
         this.showToast('Copied to clipboard', 'success');
       }).catch(() => {
         this.showToast('Failed to copy', 'error');

src/web/public/respawn-ui.js

@@ -848,6 +848,18 @@ Object.assign(CodemanApp.prototype, {
   },
 
   closeSessionOptions() {
+    // Commit the field the user was still editing BEFORE editingSessionId is
+    // cleared. The Session Name input saves on blur (and the auto-compact prompt
+    // on change), and every autosave handler bails out on `!this.editingSessionId`.
+    // Hiding the modal blurs the focused input on its own, but that happens after
+    // the id is gone, so Escape / backdrop-click silently dropped what was typed.
+    // (Clicking the X worked only because mousedown blurs the input first.)
+    const modal = document.getElementById('sessionOptionsModal');
+    const focused = document.activeElement;
+    if (focused && modal && modal.contains(focused) && typeof focused.blur === 'function') {
+      focused.blur();
+    }
+
     this.editingSessionId = null;
     // Stop run summary auto-refresh if it was running
     this.stopRunSummaryAutoRefresh();

src/web/public/session-ui.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini),
+ * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini/Antigravity),
  * session options modal (per-session settings, color picker, rename),
  * session options tabs (Ralph config tab), case settings (CRUD, links),
  * create case modal, and mobile case picker.
@@ -316,6 +316,9 @@ Object.assign(CodemanApp.prototype, {
         select.dataset.listenerAdded = 'true';
       }
       this.setupQuickStartCasePicker();
+      // The phone overview labels rows with their case name, and a case rename or
+      // link does not go through the session-tab renderer.
+      this._refreshMobileOverviewIfVisible?.();
     } catch (err) {
       console.error('Failed to load cases:', err);
     }
@@ -370,7 +373,7 @@ Object.assign(CodemanApp.prototype, {
     this._renderSessionTabsImmediate?.();
   },
 
-  /** Run using the selected mode (Claude Code, OpenCode, Codex, or Gemini) */
+  /** Run using the selected mode (Claude Code, OpenCode, Codex, Gemini, or Antigravity) */
   async run() {
     if (this._runInFlight) return;
 
@@ -394,6 +397,12 @@ Object.assign(CodemanApp.prototype, {
       if (mode === 'gemini') {
         return await this.runGemini();
       }
+      if (mode === 'antigravity') {
+        return await this.runAntigravity();
+      }
+      if (mode === 'shell') {
+        return await this.runShell();
+      }
       return await this.runClaude();
     } finally {
       const remaining = minLockMs - (Date.now() - startedAt);
@@ -432,6 +441,7 @@ Object.assign(CodemanApp.prototype, {
     // Load history sessions when menu opens
     if (menu.classList.contains('active')) {
       this._loadRunModeHistory();
+      this._refreshRunModeAvailability(menu);
       const close = (ev) => {
         if (!menu.contains(ev.target)) {
           menu.classList.remove('active');
@@ -442,6 +452,25 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * #201: hides run-mode dropdown entries for CLIs that aren't installed, so
+   * picking one doesn't spawn a session that immediately errors out.
+   *
+   * Shell has no external CLI dependency and is never gated, which is also what
+   * guarantees the menu is never empty. Scoped to `menu` rather than the document:
+   * `.run-mode-option` is also the class the saved-dashboard rows and the history
+   * rows use, and a bare querySelector would find whichever came first in the DOM.
+   *
+   * Antigravity is in this list even though #201 predates it — it is a run mode
+   * like the rest, and `agy` is the LEAST likely of the five to be installed.
+   */
+  _refreshRunModeAvailability(menu) {
+    for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity']) {
+      const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`);
+      if (btn) btn.style.display = this.isCliAvailable(mode) ? 'flex' : 'none';
+    }
+  },
+
   async _loadRunModeHistory() {
     const container = document.getElementById('runModeHistory');
     if (!container) return;
@@ -500,10 +529,32 @@ Object.assign(CodemanApp.prototype, {
       gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
     }
     if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'antigravity' ? 'Run AG' : mode === 'shell' ? 'Run SH' : 'Run';
     }
   },
 
+  /** Send Enter to the active session (phone toolbar button).
+   *
+   *  MUST go through xterm's onData path, NOT straight to sendInput()/the API.
+   *  With local echo on (the mobile default) the characters you typed are still
+   *  buffered in the LocalEchoOverlay and have NEVER reached the PTY. The onData
+   *  Enter branch (terminal-ui.js) is what flushes that pending text and only
+   *  then sends \r. Send a bare \r instead and you submit an empty line while the
+   *  typed text stays stranded on screen — which reads as "the button does
+   *  nothing". triggerDataEvent replays it exactly as if the key were pressed,
+   *  so overlay flush, flushed-offset cleanup and ordering are all reused. */
+  sendEnterKey() {
+    if (!this.activeSessionId) return;
+    const coreService = this.terminal?._core?.coreService;
+    if (coreService && typeof coreService.triggerDataEvent === 'function') {
+      coreService.triggerDataEvent('\r', true);
+      return;
+    }
+    // Fallback only if xterm's private core API moves: correct when local echo
+    // is off, and still better than doing nothing.
+    this.sendInput('\r');
+  },
+
   _initRunMode() {
     try { this._runMode = localStorage.getItem('codeman_runMode') || 'claude'; } catch { this._runMode = 'claude'; }
     this._applyRunMode();
@@ -551,13 +602,43 @@ Object.assign(CodemanApp.prototype, {
     return startNumber;
   },
 
+  /**
+   * Launch progress may use the terminal only on the session-less home screen.
+   * When another session is active, mutating the shared xterm would serialize
+   * launch chrome into that session's snapshot during the subsequent switch.
+   */
+  _beginSessionLaunchStatus(message, ansiColor = '1;32') {
+    const ownsTerminal = !this.activeSessionId;
+    if (ownsTerminal) {
+      this.terminal.clear();
+      this.terminal.writeln(`\x1b[${ansiColor}m ${message}\x1b[0m`);
+      this.terminal.writeln('');
+    } else {
+      this.showToast?.(message, 'info');
+    }
+    return ownsTerminal;
+  },
+
+  _appendSessionLaunchStatus(ownsTerminal, message, ansiColor = '90') {
+    if (!ownsTerminal || this.activeSessionId) return;
+    this.terminal.writeln(`\x1b[${ansiColor}m ${message}\x1b[0m`);
+  },
+
+  _reportSessionLaunchError(ownsTerminal, message) {
+    if (ownsTerminal && !this.activeSessionId) {
+      this.terminal.writeln(`\x1b[1;31m Error: ${message}\x1b[0m`);
+    } else {
+      this.showToast?.(message, 'error');
+    }
+  },
+
   async runClaude() {
     const caseName = document.getElementById('quickStartCase').value || 'testcase';
     const tabCount = Math.min(20, Math.max(1, parseInt(document.getElementById('tabCount').value) || 1));
 
-    this.terminal.clear();
-    this.terminal.writeln(`\x1b[1;32m Starting ${tabCount} Claude session(s) in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(
+      `Starting ${tabCount} Claude session(s) in ${caseName}...`
+    );
     // Focus terminal NOW, in the synchronous user-gesture context (button click).
     // iOS Safari ignores programmatic focus() after any await, so this must happen
     // before the first async call. The keyboard opens here and stays open through
@@ -640,7 +721,7 @@ Object.assign(CodemanApp.prototype, {
           await this._ensureCreatedSessionVisible(data.data.sessionId, data.data.session);
           remoteIds.push(data.data.sessionId);
         }
-        this.terminal.writeln(`\x1b[90m All ${tabCount} remote session(s) ready\x1b[0m`);
+        this._appendSessionLaunchStatus(ownsLaunchTerminal, `All ${tabCount} remote session(s) ready`);
         if (remoteIds[0]) {
           await this.selectSession(remoteIds[0]);
           this.loadQuickStartCases();
@@ -675,7 +756,7 @@ Object.assign(CodemanApp.prototype, {
       const modelOverride = globalSettings.claudeModel || (useOpus1m ? 'opus[1m]' : '');
 
       // Step 1: Create all sessions in parallel
-      this.terminal.writeln(`\x1b[90m Creating ${tabCount} session(s)...\x1b[0m`);
+      this._appendSessionLaunchStatus(ownsLaunchTerminal, `Creating ${tabCount} session(s)...`);
       const createPromises = sessionNames.map(name =>
         fetch('/api/sessions', {
           method: 'POST',
@@ -691,7 +772,7 @@ Object.assign(CodemanApp.prototype, {
             // is shared by sibling sessions, so create-with-false must not yank it
             // — see the comment in session-routes create). Disabling the setting
             // removes it via the App Settings toggle path (system-routes), not here.
-            statusLineTelemetry: globalSettings.showPlanUsageLimits === true,
+            statusLineTelemetry: this.planUsageChipEnabled(globalSettings),
           })
         }).then(r => r.json())
       );
@@ -716,12 +797,12 @@ Object.assign(CodemanApp.prototype, {
       ));
 
       // Step 3: Start all sessions in parallel (biggest speedup)
-      this.terminal.writeln(`\x1b[90m Starting ${tabCount} session(s) in parallel...\x1b[0m`);
+      this._appendSessionLaunchStatus(ownsLaunchTerminal, `Starting ${tabCount} session(s) in parallel...`);
       await Promise.all(sessionIds.map(id =>
         fetch(`/api/sessions/${id}/interactive`, { method: 'POST' })
       ));
 
-      this.terminal.writeln(`\x1b[90m All ${tabCount} sessions ready\x1b[0m`);
+      this._appendSessionLaunchStatus(ownsLaunchTerminal, `All ${tabCount} sessions ready`);
 
       // Auto-switch to the new session using selectSession (does proper refresh)
       if (firstSessionId) {
@@ -731,7 +812,7 @@ Object.assign(CodemanApp.prototype, {
 
       this.terminal.focus();
     } catch (err) {
-      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
     }
   },
 
@@ -774,9 +855,10 @@ Object.assign(CodemanApp.prototype, {
     const caseName = document.getElementById('quickStartCase').value || 'testcase';
     const shellCount = Math.min(20, Math.max(1, parseInt(document.getElementById('shellCount').value) || 1));
 
-    this.terminal.clear();
-    this.terminal.writeln(`\x1b[1;33m Starting ${shellCount} Shell session(s) in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(
+      `Starting ${shellCount} Shell session(s) in ${caseName}...`,
+      '1;33'
+    );
 
     try {
       // Get the case path
@@ -882,7 +964,7 @@ Object.assign(CodemanApp.prototype, {
 
       this.terminal.focus();
     } catch (err) {
-      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
     }
   },
 
@@ -893,9 +975,7 @@ Object.assign(CodemanApp.prototype, {
     const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
     const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
 
-    this.terminal.clear();
-    this.terminal.writeln(`\x1b[1;32m Starting OpenCode session in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting OpenCode session in ${caseName}...`);
     // Focus in sync gesture context (see runClaude comment)
     this.terminal.focus();
 
@@ -905,8 +985,10 @@ Object.assign(CodemanApp.prototype, {
         const statusRes = await fetch('/api/opencode/status');
         const status = (await statusRes.json()).data;
         if (!status.available) {
-          this.terminal.writeln('\x1b[1;31m OpenCode CLI not found.\x1b[0m');
-          this.terminal.writeln('\x1b[90m Install with: curl -fsSL https://opencode.ai/install | bash\x1b[0m');
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash'
+          );
           return;
         }
       }
@@ -939,7 +1021,7 @@ Object.assign(CodemanApp.prototype, {
 
       this.terminal.focus();
     } catch (err) {
-      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
     }
   },
 
@@ -950,9 +1032,7 @@ Object.assign(CodemanApp.prototype, {
     const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
     const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
 
-    this.terminal.clear();
-    this.terminal.writeln(`\x1b[1;32m Starting Codex session in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Codex session in ${caseName}...`);
     this.terminal.focus();
 
     try {
@@ -960,8 +1040,10 @@ Object.assign(CodemanApp.prototype, {
         const statusRes = await fetch('/api/codex/status');
         const status = (await statusRes.json()).data;
         if (!status.available) {
-          this.terminal.writeln('\x1b[1;31m Codex CLI not found.\x1b[0m');
-          this.terminal.writeln('\x1b[90m Install with: npm install -g @openai/codex\x1b[0m');
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Codex CLI not found. Install with: npm install -g @openai/codex'
+          );
           return;
         }
       }
@@ -978,6 +1060,7 @@ Object.assign(CodemanApp.prototype, {
           ...(isRemote ? {} : {
             codexConfig: {
               dangerouslyBypassApprovals: globalSettings.codexDangerouslyBypassApprovals ?? false,
+              animations: globalSettings.codexAnimationsEnabled ?? false,
               renderMode: 'hybrid',
             },
             ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
@@ -996,7 +1079,7 @@ Object.assign(CodemanApp.prototype, {
 
       this.terminal.focus();
     } catch (err) {
-      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
     }
   },
 
@@ -1007,9 +1090,7 @@ Object.assign(CodemanApp.prototype, {
     const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
     const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
 
-    this.terminal.clear();
-    this.terminal.writeln(`\x1b[1;32m Starting Gemini session in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Gemini session in ${caseName}...`);
     this.terminal.focus();
 
     try {
@@ -1017,8 +1098,10 @@ Object.assign(CodemanApp.prototype, {
         const statusRes = await fetch('/api/gemini/status');
         const status = (await statusRes.json()).data;
         if (!status.available) {
-          this.terminal.writeln('\x1b[1;31m Gemini CLI not found.\x1b[0m');
-          this.terminal.writeln('\x1b[90m Install with: npm install -g @google/gemini-cli\x1b[0m');
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
+          );
           return;
         }
       }
@@ -1047,7 +1130,58 @@ Object.assign(CodemanApp.prototype, {
 
       this.terminal.focus();
     } catch (err) {
-      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
+  },
+
+  async runAntigravity() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // Remote/docker cases run agy on the OTHER side — skip the local status probe and the
+    // local-only config/env below (quick-start rejects them for remote cases).
+    const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
+    const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
+
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Antigravity session in ${caseName}...`);
+    this.terminal.focus();
+
+    try {
+      if (!isRemote) {
+        const statusRes = await fetch('/api/antigravity/status');
+        const status = (await statusRes.json()).data;
+        if (!status.available) {
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
+          );
+          return;
+        }
+      }
+
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'antigravity',
+          sessionName: `w${this._nextCaseSessionStartNumber(caseName)}-${caseName}`,
+          ...(isRemote ? {} : {
+            antigravityConfig: { dangerouslySkipPermissions: true },
+            ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          }),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start Antigravity');
+      await this._ensureCreatedSessionVisible(data.data.sessionId, data.data.session);
+
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
     }
   },
 
@@ -1063,7 +1197,7 @@ Object.assign(CodemanApp.prototype, {
     this.editingSessionId = sessionId;
 
     // Reset to an appropriate tab — Summary for external CLIs (Respawn/Ralph are Claude-only)
-    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini';
+    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity';
     this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');
 
     // Update respawn status display and buttons
@@ -1093,7 +1227,7 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Hide Claude-specific options for external CLI sessions
-    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini';
+    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity';
     const claudeOnlyEls = document.querySelectorAll('[data-claude-only]');
     claudeOnlyEls.forEach(el => { el.style.display = isExternalCli ? 'none' : ''; });
 
@@ -1863,6 +1997,25 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  openLinkCasePathPicker() {
+    const pathInput = document.getElementById('linkCasePath');
+    PathPicker.open({
+      title: 'Select Existing Project Folder',
+      initialPath: pathInput.value.trim(),
+      directoriesOnly: true,
+      onSelect: (path) => {
+        pathInput.value = path;
+        const nameInput = document.getElementById('linkCaseName');
+        if (!nameInput.value.trim()) {
+          const folderName = path.split('/').filter(Boolean).pop() || '';
+          if (/^[\p{L}\p{N}_-]+$/u.test(folderName)) nameInput.value = folderName;
+        }
+        pathInput.focus();
+        pathInput.setSelectionRange(path.length, path.length);
+      },
+    });
+  },
+
   async linkRemoteCase() {
     const name = document.getElementById('remoteCaseName').value.trim();
     const remotePath = document.getElementById('remoteCasePath').value.trim();
@@ -2494,6 +2647,8 @@ Object.defineProperty(CodemanApp.prototype, 'runMode', {
   },
   set(mode) {
     this._runMode =
-      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'claude' ? mode : 'claude';
+      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'claude'
+        ? mode
+        : 'claude';
   },
 });

src/web/public/settings-ui.js

@@ -307,11 +307,15 @@ Object.assign(CodemanApp.prototype, {
     // Header visibility settings
     document.getElementById('appSettingsShowFontControls').checked = settings.showFontControls ?? defaults.showFontControls ?? false;
     document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? defaults.showSystemStats ?? true;
-    document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? true;
+    document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     document.getElementById('appSettingsShowResponseViewer').checked = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
-    document.getElementById('appSettingsShowFileViewerButton').checked = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? false;
+    document.getElementById('appSettingsShowFileViewerButton').checked = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? true;
     document.getElementById('appSettingsShowAttachmentsButton').checked = settings.showAttachmentsButton ?? defaults.showAttachmentsButton ?? false;
     document.getElementById('appSettingsSkin').value = settings.skin ?? defaults.skin ?? 'daylight-blue';
+    // Entrance animations. Deliberately NOT part of the settings payload: the
+    // styles persist to their own localStorage keys via setAnimTheme(), which
+    // keeps them per-device without touching the .strict() SettingsUpdateSchema.
+    this._syncEntranceAnimSetting?.();
     // WebGL renderer (desktop only — mobile always uses the DOM renderer, so hide
     // the toggle there so it can't promise something that won't apply).
     document.getElementById('appSettingsWebglRenderer').checked = settings.webglRendererEnabled ?? defaults.webglRendererEnabled ?? true;
@@ -325,9 +329,19 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsUltracodeFloatingWindows').checked =
       settings.ultracodeFloatingWindows ?? defaults.ultracodeFloatingWindows ?? false;
     document.getElementById('appSettingsShowMultiMonitorButton').checked = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
-    document.getElementById('appSettingsShowPlanUsageLimits').checked = settings.showPlanUsageLimits ?? defaults.showPlanUsageLimits ?? false;
+    document.getElementById('appSettingsShowPlanUsageLimits').checked = this.planUsageChipEnabled(settings);
     document.getElementById('appSettingsShowRedrawButton').checked = settings.showRedrawButton ?? defaults.showRedrawButton ?? false;
-    // Session Manager + Away Digest buttons default OFF; Cron button defaults ON.
+    // Phone overview home screen: only meaningful under 430px, so the row is
+    // hidden elsewhere rather than offering a toggle that changes nothing.
+    document.getElementById('appSettingsMobileOverview').checked = settings.mobileOverviewEnabled ?? defaults.mobileOverviewEnabled ?? false;
+    const phoneOnly = MobileDetection.getDeviceType() === 'mobile' ? '' : 'none';
+    const mobileOverviewItem = document.getElementById('appSettingsMobileOverviewItem');
+    if (mobileOverviewItem) mobileOverviewItem.style.display = phoneOnly;
+    const phoneSection = document.getElementById('appSettingsPhoneSection');
+    if (phoneSection) phoneSection.style.display = phoneOnly;
+    // Session Manager, Away Digest and Cron buttons all default OFF (opt-in under
+    // Display → Header Displays; the Cron button also ships with btn-cron--hidden
+    // in the template, so an unchecked box and a hidden button stay consistent).
     document.getElementById('appSettingsShowSessionButton').checked = settings.showSessionButton ?? defaults.showSessionButton ?? false;
     document.getElementById('appSettingsShowAwayDigestButton').checked = settings.showAwayDigestButton ?? defaults.showAwayDigestButton ?? false;
     document.getElementById('appSettingsShowCronButton').checked = settings.showCronButton ?? defaults.showCronButton ?? false;
@@ -359,9 +373,15 @@ Object.assign(CodemanApp.prototype, {
     claudeModeSelect.onchange = () => {
       allowedToolsRow.style.display = claudeModeSelect.value === 'allowedTools' ? '' : 'none';
     };
-    // Codex CLI settings
+    // Codex CLI settings. The inputs are always populated (and always read back
+    // by saveAppSettings), even when the tab is hidden below, so a user without
+    // codex installed can never silently wipe the codex prefs of an instance
+    // that does have it.
     document.getElementById('appSettingsCodexDangerouslyBypassApprovals').checked =
       settings.codexDangerouslyBypassApprovals ?? false;
+    document.getElementById('appSettingsCodexAnimations').checked =
+      settings.codexAnimationsEnabled ?? false;
+    this._applyCodexSettingsVisibility();
     // Claude Permissions settings
     document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
     document.getElementById('appSettingsClaudeModel').value = settings.claudeModel ?? '';
@@ -408,7 +428,7 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('eventIdleAudio').checked = idlePref.audio ?? false;
     // Response complete (stop)
     const stopPref = eventTypes.stop || {};
-    document.getElementById('eventStopEnabled').checked = stopPref.enabled ?? true;
+    document.getElementById('eventStopEnabled').checked = stopPref.enabled ?? false;
     document.getElementById('eventStopBrowser').checked = stopPref.browser ?? false;
     document.getElementById('eventStopPush').checked = stopPref.push ?? false;
     document.getElementById('eventStopAudio').checked = stopPref.audio ?? false;
@@ -471,6 +491,29 @@ Object.assign(CodemanApp.prototype, {
     this.activeFocusTrap.activate();
   },
 
+  /**
+   * Show the App Settings "Codex CLI" tab only on instances where the codex
+   * binary actually resolves. Both settings on it (approval bypass, animated
+   * status effects) are passed to `codex` at launch, so on a box without codex
+   * the tab is a promise nothing can keep.
+   *
+   * Availability comes from the injected `window.__codemanCliAvailable`, shared
+   * with the welcome buttons and the run-mode dropdown, so the tab never flickers
+   * in and back out. Only the tab BUTTON is toggled: the panel already carries
+   * `.modal-tab-content.hidden` unless it is the selected tab, and
+   * openAppSettings() always reopens on Display, so an unreachable button is
+   * enough to keep the panel unreachable.
+   *
+   * Note the inverted default versus the run buttons: an UNKNOWN flag hides this
+   * tab. Hiding a settings tab costs a user nothing (the values stay in the DOM
+   * and are still saved), whereas hiding a run button would leave a working
+   * install with nothing to click.
+   */
+  _applyCodexSettingsVisibility() {
+    const btn = document.querySelector('#appSettingsModal .modal-tab-btn[data-tab="settings-codex"]');
+    if (btn) btn.style.display = window.__codemanCliAvailable?.codex === true ? '' : 'none';
+  },
+
   switchSettingsTab(tabName) {
     const modal = document.getElementById('appSettingsModal');
     // Toggle active class on tab buttons
@@ -680,6 +723,43 @@ Object.assign(CodemanApp.prototype, {
     this._updatePollTimer = setInterval(poll, 1500);
   },
 
+  /**
+   * Is `tool` installed on the server? Reads `window.__codemanCliAvailable`,
+   * injected by renderIndexHtml (see the comment there for why this is injected
+   * rather than fetched per surface).
+   *
+   * Unknown reads as AVAILABLE. A missing flag means the page was rendered by a
+   * build that predates the injection, or by a solo popup: hiding every run
+   * button on a doubt would leave nothing to click, and the pre-existing failure
+   * mode for a genuinely missing CLI is just an error toast.
+   */
+  isCliAvailable(tool) {
+    const flags = window.__codemanCliAvailable;
+    if (!flags || typeof flags !== 'object') return true;
+    return flags[tool] !== false;
+  },
+
+  /**
+   * #200: show a welcome-screen button only where the thing it launches exists.
+   * The markup ships them hidden, so an old cached page can never flash a button
+   * for a tool this server does not have.
+   */
+  applyWelcomeCliVisibility() {
+    const buttons = [
+      ['welcomeClaudeBtn', 'claude'],
+      ['welcomeOpencodeBtn', 'opencode'],
+      ['welcomeAntigravityBtn', 'antigravity'],
+      ['welcomeGeminiBtn', 'gemini'],
+      // Not a run mode, same reasoning: offering a Cloudflare Tunnel on a box
+      // without cloudflared can only ever produce "cloudflared not found".
+      ['welcomeTunnelBtn', 'cloudflared'],
+    ];
+    for (const [id, tool] of buttons) {
+      const btn = document.getElementById(id);
+      if (btn) btn.style.display = this.isCliAvailable(tool) ? 'flex' : 'none';
+    }
+  },
+
   async loadTunnelStatus() {
     try {
       const res = await fetch('/api/tunnel/status');
@@ -1447,6 +1527,7 @@ Object.assign(CodemanApp.prototype, {
       showMultiMonitorButton: document.getElementById('appSettingsShowMultiMonitorButton').checked,
       showPlanUsageLimits: document.getElementById('appSettingsShowPlanUsageLimits').checked,
       showRedrawButton: document.getElementById('appSettingsShowRedrawButton').checked,
+      mobileOverviewEnabled: document.getElementById('appSettingsMobileOverview').checked,
       showSessionButton: document.getElementById('appSettingsShowSessionButton').checked,
       showAwayDigestButton: document.getElementById('appSettingsShowAwayDigestButton').checked,
       showCronButton: document.getElementById('appSettingsShowCronButton').checked,
@@ -1467,6 +1548,7 @@ Object.assign(CodemanApp.prototype, {
       allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(),
       // Codex CLI settings
       codexDangerouslyBypassApprovals: document.getElementById('appSettingsCodexDangerouslyBypassApprovals').checked,
+      codexAnimationsEnabled: document.getElementById('appSettingsCodexAnimations').checked,
       // Claude Permissions settings
       agentTeamsEnabled: document.getElementById('appSettingsAgentTeams').checked,
       claudeModel: document.getElementById('appSettingsClaudeModel').value,
@@ -1587,7 +1669,7 @@ Object.assign(CodemanApp.prototype, {
           audio: document.getElementById('eventSubagentAudio').checked,
         },
       },
-      _version: 4,
+      _version: 5,
     };
     if (this.notificationManager) {
       this.notificationManager.preferences = notifPrefsToSave;
@@ -1610,6 +1692,10 @@ Object.assign(CodemanApp.prototype, {
     // Apply CJK input visibility immediately
     this._updateCjkInputState();
 
+    // The phone home surface (overview vs welcome) may have just been toggled.
+    // Only re-decide while a home screen is actually up.
+    if (!this.activeSessionId) this.showWelcome();
+
     // Apply keyboard bar mode
     KeyboardAccessoryBar.setMode(settings.extendedKeyboardBar ? 'extended' : 'simple');
 
@@ -1640,6 +1726,8 @@ Object.assign(CodemanApp.prototype, {
       showSessionButton: _ssb,
       showAwayDigestButton: _adb,
       showCronButton: _crb,
+      // Phone-only home surface, and absent from SettingsUpdateSchema (.strict()).
+      mobileOverviewEnabled: _mov,
       ...serverSettings
     } = settings;
     try {
@@ -1798,6 +1886,9 @@ Object.assign(CodemanApp.prototype, {
         showUltracodeAgents: false,
         ultracodeFloatingWindows: false,
         showMultiMonitorButton: false,
+        // Desktop defaults this ON (see planUsageChipEnabled); handhelds keep it
+        // OFF so the phone header stays minimal and the mobile-header-buttons
+        // policy guard keeps passing.
         showPlanUsageLimits: false,
         showAttachmentsButton: false,
         showFileViewerButton: false,
@@ -1805,6 +1896,10 @@ Object.assign(CodemanApp.prototype, {
         showSessionButton: false,
         showAwayDigestButton: false,
         showCronButton: false,
+        // Phone home screen: the C logo opens the session overview instead of the
+        // welcome screen. ON by default here, and the escape hatch if it ever
+        // misbehaves on a device (the gate treats only an explicit false as off).
+        mobileOverviewEnabled: true,
         // Remote auto-reconnect (COD-108) — on by default
         remoteAutoReconnect: true,
         // Input
@@ -1866,6 +1961,8 @@ Object.assign(CodemanApp.prototype, {
     const skin = settings.skin ?? defaults.skin ?? 'daylight-blue';
     document.documentElement.setAttribute('data-skin', skin);
     window.__codemanSkin = skin;
+    const themeColor = getComputedStyle(document.documentElement).getPropertyValue('--bg-dark').trim();
+    if (themeColor) document.querySelector('meta[name="theme-color"]')?.setAttribute('content', themeColor);
     try {
       localStorage.setItem('codeman:skin', skin);
     } catch (_e) {
@@ -1887,13 +1984,27 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  // Resolved per-device state of the plan-usage chip. Desktop defaults ON,
+  // handhelds default OFF (the mobile block in getDefaultSettings() sets false,
+  // and the mobile-header-buttons-policy guard depends on that staying false).
+  // Single source of truth for THREE call sites that must never disagree: the
+  // App Settings checkbox, the chip's visibility, and the statusLineTelemetry
+  // flag sent on session create. A chip shown without telemetry renders "—"
+  // forever, which is exactly the drift this helper prevents.
+  planUsageChipEnabled(settings = null) {
+    const s = settings ?? this.loadAppSettingsFromStorage();
+    return s.showPlanUsageLimits ?? this.getDefaultSettings().showPlanUsageLimits ?? true;
+  },
+
   applyHeaderVisibilitySettings() {
     const settings = this.loadAppSettingsFromStorage();
     const defaults = this.getDefaultSettings();
     const compactHeader = MobileDetection.getDeviceType() !== 'desktop';
     const showFontControls = compactHeader ? false : (settings.showFontControls ?? defaults.showFontControls ?? false);
     const showSystemStats = compactHeader ? false : (settings.showSystemStats ?? defaults.showSystemStats ?? true);
-    const showTokenCount = compactHeader ? false : (settings.showTokenCount ?? defaults.showTokenCount ?? true);
+    // Default OFF: the header stays gear + usage chips + files button unless a
+    // stored preference explicitly re-enables the token chip (no UI toggle exists).
+    const showTokenCount = compactHeader ? false : (settings.showTokenCount ?? defaults.showTokenCount ?? false);
 
     const fontControlsEl = document.querySelector('.header-font-controls');
     const systemStatsEl = document.getElementById('headerSystemStats');
@@ -1910,7 +2021,9 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Hide lifecycle log button when setting is disabled
-    const showLifecycleLog = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? true;
+    // Default OFF: the lifecycle-log document icon is opt-in; the default header
+    // keeps only WS/CPU/MEM, the file-viewer folder, usage chips, and the gear.
+    const showLifecycleLog = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     const lifecycleBtn = document.querySelector('.btn-lifecycle-log');
     if (lifecycleBtn) {
       lifecycleBtn.style.display = showLifecycleLog ? '' : 'none';
@@ -1934,7 +2047,9 @@ Object.assign(CodemanApp.prototype, {
 
     // File Viewer header button — opt-in, default OFF. Marker class (base is
     // display:inline-flex !important); clicking it toggles the file browser panel.
-    const showFileViewerButton = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? false;
+    // Default ON (desktop): the folder button is part of the standard header now;
+    // phones still hide it via mobile.css (btn-file-viewer in the phone-hidden set).
+    const showFileViewerButton = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? true;
     const fileViewerBtn = document.querySelector('.btn-file-viewer');
     if (fileViewerBtn) {
       fileViewerBtn.classList.toggle('btn-file-viewer--hidden', !showFileViewerButton);
@@ -1959,11 +2074,13 @@ Object.assign(CodemanApp.prototype, {
       ultracodeBtn.classList.toggle('btn-ultracode-agents--hidden', !showUltracodeAgents);
     }
 
-    // Plan-usage chip — hidden by default (App Settings → Display → "Plan Usage
-    // Limits"). Server renders the initial state on reload; this handles a live
-    // toggle from a settings save. Marker class (base is display:inline-flex
-    // !important), matching the response-viewer/multimonitor pattern.
-    const showPlanUsageLimits = settings.showPlanUsageLimits ?? defaults.showPlanUsageLimits ?? false;
+    // Plan-usage chip — shown by default on desktop, OFF on handhelds (App
+    // Settings → Display → "Plan Usage Limits"). The template always ships it
+    // hidden because display is per-device and the server cannot know a
+    // localStorage value, so THIS is what reveals it on every load as well as
+    // on a live toggle. Marker class (base is display:inline-flex !important),
+    // matching the response-viewer/multimonitor pattern.
+    const showPlanUsageLimits = this.planUsageChipEnabled(settings);
     const planUsageChip = document.getElementById('planUsageChip');
     if (planUsageChip) {
       planUsageChip.classList.toggle('header-plan-usage--hidden', !showPlanUsageLimits);
@@ -2238,10 +2355,12 @@ Object.assign(CodemanApp.prototype, {
           'language',
           'terminalWheelLocalScrollback',
           'showSessionButton', 'showAwayDigestButton', 'showCronButton',
+          'mobileOverviewEnabled',
         ]);
-        // The plan-usage chip is a PER-DEVICE display setting (default OFF): desktop
-        // can show it while mobile stays hidden. It used to sync, so an older
-        // server.json may still carry `true` — drop it so the server value is NEVER
+        // The plan-usage chip is a PER-DEVICE display setting (desktop default ON,
+        // handheld default OFF): desktop can show it while mobile stays hidden. It
+        // used to sync, so an older server.json may still carry a value — drop it
+        // so the server value is NEVER
         // seeded into a device that didn't explicitly enable it (collection is handled
         // separately via the statusLineTelemetry action, not this display flag).
         delete appSettings.showPlanUsageLimits;
@@ -2267,7 +2386,8 @@ Object.assign(CodemanApp.prototype, {
         if (notificationPreferences && this.notificationManager) {
           const localNotifPrefs = localStorage.getItem(this.notificationManager.getStorageKey());
           if (!localNotifPrefs) {
-            this.notificationManager.preferences = notificationPreferences;
+            this.notificationManager.preferences =
+              this.notificationManager.normalizePreferences(notificationPreferences);
             this.notificationManager.savePreferences();
           }
         }

src/web/public/subagent-windows.js

@@ -465,6 +465,10 @@ Object.assign(CodemanApp.prototype, {
     if (typeof this._appendUltracodeAgentConnectionLines === 'function') {
       this._appendUltracodeAgentConnectionLines(svg, rects);
     }
+
+    // Every path above was just created from scratch, so any line entrance in
+    // flight has to be re-attached here (resumed via a negative animation-delay).
+    this._applyLineEntrances?.(svg);
   },
 
   // ═══════════════════════════════════════════════════════════════
@@ -729,12 +733,17 @@ Object.assign(CodemanApp.prototype, {
       </div>
     `;
 
+    // Only the `fly` entrance style parks the window on its parent tab; every
+    // CSS-animated style (entrance-animations.js) needs it to start at its
+    // resting position, or the animation would play at the wrong place.
+    const flyFromTab = !!parentTab && !isMobile && this.windowEntranceFliesFromTab?.() !== false;
+
     // If we have a parent tab, start window at tab position for spawn animation
     if (isMobile) {
       // Mobile: position using top (keyboard-aware positioning calculated above)
       win.style.top = `${finalY}px`;
       win.style.bottom = 'auto';
-    } else if (parentTab) {
+    } else if (flyFromTab) {
       const tabRect = parentTab.getBoundingClientRect();
       win.style.left = `${tabRect.left}px`;
       win.style.top = `${tabRect.bottom}px`;
@@ -812,7 +821,7 @@ Object.assign(CodemanApp.prototype, {
     this.subagentWindows.get(agentId).resizeObserver = resizeObserver;
 
     // Animate to final position if spawning from tab (desktop only)
-    if (parentTab && !isMobile) {
+    if (flyFromTab) {
       requestAnimationFrame(() => {
         win.style.transition = 'all 0.4s cubic-bezier(0.34, 1.56, 0.64, 1)';
         win.style.left = `${finalX}px`;
@@ -824,11 +833,26 @@ Object.assign(CodemanApp.prototype, {
         setTimeout(() => {
           win.style.transition = '';
           win.classList.remove('spawning');
+          // The line only becomes meaningful once the window has landed, so its
+          // draw-in starts here rather than at spawn.
+          this.markConnectionLineEntering?.(agentId);
           this.updateConnectionLines();
         }, 400);
       });
     } else {
-      // No animation (mobile uses CSS positioning), just update connection lines
+      // CSS-animated entrance styles (and mobile) run in place. The window is
+      // already at its resting position, so the connection line can be drawn
+      // against a correct rect right away and animate alongside it.
+      //
+      // Skipped when the window spawns hidden (its agent belongs to a background
+      // tab): a display:none element never runs its animation, so `animationend`
+      // would never fire and the entrance class plus its inline custom property
+      // would stick to the window forever. Nothing is visible to animate anyway,
+      // and revealing it later is a tab switch, not a spawn.
+      if (!shouldHide) {
+        this.applyWindowEntrance?.(win);
+        this.markConnectionLineEntering?.(agentId);
+      }
       this.updateConnectionLines();
     }
 

src/web/public/terminal-ui.js

@@ -40,11 +40,22 @@
     og: { background: '#0d0d0d', foreground: '#e0e0e0', cursor: '#e0e0e0', cursorAccent: '#0d0d0d', selection: 'rgba(255,255,255,0.3)', black: '#0d0d0d', red: '#ff6b6b', green: '#51cf66', yellow: '#ffd43b', blue: '#339af0', magenta: '#cc5de8', cyan: '#22b8cf', white: '#e0e0e0', brightBlack: '#495057', brightRed: '#ff8787', brightGreen: '#69db7c', brightYellow: '#ffe066', brightBlue: '#5c7cfa', brightMagenta: '#da77f2', brightCyan: '#66d9e8', brightWhite: '#ffffff' },
     'daylight-green': { background: '#161b23', foreground: '#dfe6ef', cursor: '#2fd3aa', cursorAccent: '#161b23', selection: 'rgba(47,211,170,0.22)', black: '#161b23', red: '#ff8585', green: '#34d8a0', yellow: '#f0c25a', blue: '#5cc6e8', magenta: '#c79af2', cyan: '#2bcbbb', white: '#dfe6ef', brightBlack: '#5b6675', brightRed: '#ffa0a0', brightGreen: '#5fe6b8', brightYellow: '#ffd884', brightBlue: '#82d4ee', brightMagenta: '#d6b3f7', brightCyan: '#5ee0d4', brightWhite: '#f3f6fa' },
     'daylight-blue': { background: '#161b23', foreground: '#dfe6ef', cursor: '#38b6f0', cursorAccent: '#161b23', selection: 'rgba(56,182,240,0.22)', black: '#161b23', red: '#ff8585', green: '#34d8a0', yellow: '#f0c25a', blue: '#5cc6e8', magenta: '#c79af2', cyan: '#2bcbbb', white: '#dfe6ef', brightBlack: '#5b6675', brightRed: '#ffa0a0', brightGreen: '#5fe6b8', brightYellow: '#ffd884', brightBlue: '#82d4ee', brightMagenta: '#d6b3f7', brightCyan: '#5ee0d4', brightWhite: '#f3f6fa' },
+    'paper-gray': { background: '#f6f8fa', foreground: '#1f2328', cursor: '#0969da', cursorAccent: '#ffffff', selection: 'rgba(9,105,218,0.2)', black: '#24292f', red: '#cf222e', green: '#1a7f37', yellow: '#9a6700', blue: '#0969da', magenta: '#8250df', cyan: '#1b7c83', white: '#59636e', brightBlack: '#6e7781', brightRed: '#a40e26', brightGreen: '#116329', brightYellow: '#7d4e00', brightBlue: '#0550ae', brightMagenta: '#6639ba', brightCyan: '#116b75', brightWhite: '#1f2328' },
+    'solarized-light': { background: '#fdf6e3', foreground: '#586e75', cursor: '#147ba3', cursorAccent: '#fdf6e3', selection: 'rgba(38,139,210,0.2)', black: '#eee8d5', red: '#dc322f', green: '#758600', yellow: '#9b7800', blue: '#147ba3', magenta: '#d33682', cyan: '#2a9189', white: '#073642', brightBlack: '#93a1a1', brightRed: '#cb4b16', brightGreen: '#657b83', brightYellow: '#586e75', brightBlue: '#268bd2', brightMagenta: '#6c71c4', brightCyan: '#2aa198', brightWhite: '#002b36' },
+    'catppuccin-latte': { background: '#eff1f5', foreground: '#4c4f69', cursor: '#1e66f5', cursorAccent: '#ffffff', selection: 'rgba(30,102,245,0.18)', black: '#5c5f77', red: '#d20f39', green: '#3b8f2b', yellow: '#a86605', blue: '#1e66f5', magenta: '#8839ef', cyan: '#177f86', white: '#6c6f85', brightBlack: '#7c7f93', brightRed: '#b50930', brightGreen: '#2f7622', brightYellow: '#8b5604', brightBlue: '#174fbf', brightMagenta: '#6f2bc5', brightCyan: '#116b71', brightWhite: '#4c4f69' },
+    'rose-pine-dawn': { background: '#faf4ed', foreground: '#575279', cursor: '#286983', cursorAccent: '#fffaf3', selection: 'rgba(40,105,131,0.2)', black: '#575279', red: '#b4637a', green: '#286983', yellow: '#96681f', blue: '#477f91', magenta: '#907aa9', cyan: '#3f7f8b', white: '#6e6a86', brightBlack: '#797593', brightRed: '#984d66', brightGreen: '#1f5266', brightYellow: '#7d5417', brightBlue: '#386b7c', brightMagenta: '#765f90', brightCyan: '#326b76', brightWhite: '#575279' },
   };
+  const CODEMAN_LIGHT_SKINS = new Set(['paper-gray', 'solarized-light', 'catppuccin-latte', 'rose-pine-dawn']);
+  function currentSkin() {
+    return (typeof document !== 'undefined' && document.documentElement.dataset.skin) || 'daylight-blue';
+  }
   function currentXtermTheme() {
-    const skin = (typeof document !== 'undefined' && document.documentElement.dataset.skin) || 'daylight-blue';
+    const skin = currentSkin();
     return CODEMAN_XTERM_THEMES[skin] || CODEMAN_XTERM_THEMES['daylight-blue'];
   }
+  function currentSkinIsLight(skin = currentSkin()) {
+    return CODEMAN_LIGHT_SKINS.has(skin);
+  }
 
   global.CodemanTerminalInput = {
     isTerminalQueryResponse,
@@ -54,6 +65,7 @@
   };
   global.CODEMAN_XTERM_THEMES = CODEMAN_XTERM_THEMES;
   global.codemanCurrentXtermTheme = currentXtermTheme;
+  global.codemanCurrentSkinIsLight = currentSkinIsLight;
 })(window);
 
 Object.assign(CodemanApp.prototype, {
@@ -75,6 +87,7 @@ Object.assign(CodemanApp.prototype, {
       lineHeight: 1.2,
       cursorBlink: false,
       cursorStyle: 'block',
+      minimumContrastRatio: window.codemanCurrentSkinIsLight() ? 4.5 : 1,
       scrollback: scrollback,
       allowTransparency: true,
       allowProposedApi: true,
@@ -145,6 +158,30 @@ Object.assign(CodemanApp.prototype, {
         return false;
       }
 
+      // Smart copy (#211): with a selection, Ctrl+C copies it instead of sending
+      // ^C. With NO selection the branch must fall through (return true, and no
+      // preventDefault) or the interrupt key is lost, which is the whole reason
+      // the selection check runs before any registry dispatch. Ctrl+Shift+C is
+      // the explicit copy chord and never falls through: an "explicit copy" that
+      // interrupts a running agent because the selection happened to be empty is
+      // a footgun with no upside.
+      // NOTE: returning false does NOT cancel the event (xterm's _keyDown calls
+      // this handler before its own cancel()), so preventDefault is explicit:
+      // without it the browser runs its native copy on top of ours.
+      if (this.shouldCopyTerminalSelectionFromShortcut?.(ev)) {
+        const selection = this.terminal.hasSelection?.() ? this.terminal.getSelection() : '';
+        if (selection) {
+          ev.preventDefault();
+          void this.copyTerminalSelection(selection);
+          return false;
+        }
+        if (ev.shiftKey) {
+          ev.preventDefault();
+          return false;
+        }
+        return true;
+      }
+
       // Ctrl+V / Cmd+V: intercept before xterm sends ^V to PTY.
       // Route through our paste trap which handles both images and text.
       if ((ev.ctrlKey || ev.metaKey) && ev.key === 'v' && ev.type === 'keydown') {
@@ -378,31 +415,71 @@ Object.assign(CodemanApp.prototype, {
     // ignores wheel reports); older versions DO capture wheel as option
     // navigation, so they keep the local wheel.
     // Shift+wheel always scrolls xterm's local scrollback (Codeman's restored
-    // history lives there), and once the viewport left the bottom the wheel
-    // stays local until the user scrolls back down — so both scrollbacks stay
-    // reachable without a mode switch.
+    // history lives there); the plain wheel stays on the CLI's transcript for
+    // those modes regardless of scroll position, so the CLI's input box never
+    // slides off the screen (see _shouldForwardWheelToApp).
+    //
+    // CAPTURE phase, deliberately, and Codeman owns the scroll. xterm's
+    // viewport is a vscode-style ScrollableElement that consumes wheel events
+    // itself (preventDefault + stopPropagation) whenever it believes a
+    // scrollbar exists, does NOT consult attachCustomWheelEventHandler, and —
+    // measured on the live instance — goes DEAF after terminal.reset(): a tab
+    // switch or full-history replay leaves its scroll dimensions stale, after
+    // which wheel events neither scroll nor propagate reliably. A bubble-phase
+    // listener here therefore never fired once local scrollback existed
+    // (measured: _shouldForwardWheelToApp call count stayed 0 while xterm
+    // scrolled), and after a tab switch NOTHING scrolled at all — the "input
+    // box scrolls up then it fights", "works at first, breaks after a tab
+    // switch" reports on #205.
+    //
+    // So: capture runs ancestors-first; this handler sees every wheel first
+    // and stops propagation, keeping xterm's scroller out of it entirely.
+    // Local scrolling goes through terminal.scrollLines() — buffer-level, so
+    // it keeps working after resets — with our own deltaMode normalization
+    // (_wheelScrollLines) covering Firefox's line-unit wheels. Two cases still
+    // belong to xterm and are passed through untouched:
+    //  - mouseTrackingMode active: xterm's own encoder forwards the wheel to
+    //    the PTY (htop/vim with mouse on in a shell pane);
+    //  - alternate buffer (direct-PTY fallback running vim/less): xterm's
+    //    alt-scroll handling converts the wheel to cursor keys, which is what
+    //    those apps expect.
     container.addEventListener(
       'wheel',
       (ev) => {
+        const trackingMode = this.terminal?.modes?.mouseTrackingMode;
+        if (trackingMode && trackingMode !== 'none') return;
+        if (this.terminal?.buffer?.active?.type === 'alternate') return;
         ev.preventDefault();
-        const lines = this._wheelScrollLines(ev);
+        ev.stopPropagation();
         if (this._shouldForwardWheelToApp(ev)) {
-          this._sendSyntheticSgrWheel(ev.clientX, ev.clientY, lines);
+          this._forwardScrollToApp(ev.clientX, ev.clientY, this._wheelScrollLines(ev));
           return;
         }
+        // Local scrolling accumulates FRACTIONAL lines: a macOS trackpad emits
+        // a stream of tiny pixel deltas, and rounding each one to a whole line
+        // (the ±1 fallback) made slow drags scroll faster than the finger.
+        const lines = this._wheelScrollLinesFloat(ev);
         this._noteTerminalUserScroll(lines);
-        this.terminal.scrollLines(lines);
+        this._smoothScrollBy(lines);
       },
-      { passive: false }
+      { passive: false, capture: true }
     );
 
     // Touch scrolling — use terminal.scrollLines() for all devices.
     // xterm.js DOM renderer doesn't populate xterm-viewport's scroll area,
     // so native CSS scrolling (overflow-y: scroll + touch-action: pan-y)
     // has nothing to scroll. Instead, convert touch deltas into scrollLines()
-    // calls, matching the wheel handler above.
+    // calls, matching the wheel handler above, including the forwarding
+    // branch: for the sessions whose wheel goes to the CLI's own transcript
+    // (_shouldForwardWheelToApp), a touch drag must go there too, or every
+    // phone/tablet swipe scrolls the local buffer of stale repaint frames and
+    // drags the CLI's pinned input box off the screen (issue #205's mobile
+    // half). Same gate, so Shift has no touch analog but the local-scrollback
+    // opt-out setting and the CLI-version gate apply to touch exactly as they
+    // do to the wheel.
     {
       const cellHeight = () => this.terminal._core?._renderService?.dimensions?.css?.cell?.height || 13;
+      let touchLastX = 0;
       let touchLastY = 0;
       let velocity = 0;
       let lastTime = 0;
@@ -416,7 +493,16 @@ Object.assign(CodemanApp.prototype, {
         if (!isTouching && Math.abs(velocity) > 0.3) {
           // Momentum phase — convert pixel velocity to lines
           const lines = Math.round(velocity / cellHeight());
-          if (lines !== 0) this.terminal.scrollLines(lines);
+          if (lines !== 0) {
+            if (this._shouldForwardWheelToApp({ shiftKey: false })) {
+              // Flick momentum keeps feeding the CLI's transcript from the last
+              // touch point; the 40ms coalescer batches the per-frame reports.
+              this._forwardScrollToApp(touchLastX, touchLastY, lines);
+            } else {
+              this.terminal.scrollLines(lines);
+              this._maybeLoadMoreHistoryOnScroll(lines);
+            }
+          }
           velocity *= 0.92;
           scrollFrame = requestAnimationFrame(scrollLoop);
         } else if (!isTouching) {
@@ -437,6 +523,7 @@ Object.assign(CodemanApp.prototype, {
         'touchstart',
         (ev) => {
           if (ev.touches.length === 1) {
+            touchLastX = ev.touches[0].clientX;
             touchLastY = ev.touches[0].clientY;
             touchStartY = touchLastY;
             velocity = 0;
@@ -472,13 +559,19 @@ Object.assign(CodemanApp.prototype, {
             const delta = touchLastY - touchY; // positive = scroll down
             pixelAccum += delta;
             velocity = delta * 1.2;
+            touchLastX = ev.touches[0].clientX;
             touchLastY = touchY;
             // Convert accumulated pixels to whole lines
             const ch = cellHeight();
             const lines = Math.trunc(pixelAccum / ch);
             if (lines !== 0) {
-              this._noteTerminalUserScroll(lines);
-              this.terminal.scrollLines(lines);
+              if (this._shouldForwardWheelToApp({ shiftKey: false })) {
+                this._forwardScrollToApp(touchLastX, touchLastY, lines);
+              } else {
+                this._noteTerminalUserScroll(lines);
+                this.terminal.scrollLines(lines);
+                this._maybeLoadMoreHistoryOnScroll(lines);
+              }
               pixelAccum -= lines * ch;
             }
           }
@@ -969,8 +1062,66 @@ Object.assign(CodemanApp.prototype, {
           return;
         }
 
-        // Get line text - translateToString handles wrapped lines
-        const lineText = line.translateToString(true);
+        // Stitch the LOGICAL line back together.
+        //
+        // xterm invokes this provider per visible ROW, and translateToString returns
+        // that row alone (the old comment here claimed otherwise). A URL or path
+        // longer than the terminal is wide therefore matched only as far as the row
+        // boundary, and the link opened a PREFIX of the real target. Walk out to both
+        // ends of the continuation, match against the joined text, and map offsets
+        // back to (x, y) so a link can span rows.
+        //
+        // Two different kinds of continuation, and handling only the first is not
+        // enough:
+        //   1. SOFT wrap: the emulator ran out of columns and flags the next row
+        //      `isWrapped`.
+        //   2. HARD wrap: the program did its own wrapping and emitted a real
+        //      newline, so nothing is flagged. Ink does this, which is why Claude
+        //      Code's own `/login` URL was cut at the window edge, and why the
+        //      clickable part grew when the window was widened.
+        // A row that fills the full width is treated as continuing into the next:
+        // that is the signal a hard wrap leaves behind, and a line that genuinely
+        // ended would stop short of the last column.
+        const cols = self.terminal.cols;
+        const rowAt = (r) => buffer.getLine(r - 1);
+        const continuesPrevious = (r) => {
+          if (r <= 1) return false;
+          if (rowAt(r)?.isWrapped) return true;
+          const prev = rowAt(r - 1);
+          return !!prev && prev.translateToString(true).length >= cols;
+        };
+
+        // Bounded so a screenful of full-width output (wide tables, box drawing)
+        // cannot make every hover stitch and re-scan the entire viewport.
+        const MAX_STITCHED_ROWS = 12;
+        let startRow = bufferLineNumber;
+        while (startRow > 1 && bufferLineNumber - startRow < MAX_STITCHED_ROWS && continuesPrevious(startRow)) {
+          startRow--;
+        }
+        let endRow = bufferLineNumber;
+        while (endRow < buffer.length && endRow - startRow < MAX_STITCHED_ROWS && continuesPrevious(endRow + 1)) {
+          endRow++;
+        }
+
+        const rowTexts = [];
+        for (let r = startRow; r <= endRow; r++) {
+          const row = rowAt(r);
+          if (!row) break;
+          // Only the final row may be trimmed. Continuation rows fill the width by
+          // definition, and trimming one would shift every later offset.
+          rowTexts.push(row.translateToString(r === endRow));
+        }
+        const lineText = rowTexts.join('');
+
+        /** Map an offset in the stitched text back to a 1-based terminal cell. */
+        const coordAt = (index) => {
+          let rest = index;
+          for (let i = 0; i < rowTexts.length - 1; i++) {
+            if (rest < rowTexts[i].length) return { x: rest + 1, y: startRow + i };
+            rest -= rowTexts[i].length;
+          }
+          return { x: rest + 1, y: startRow + rowTexts.length - 1 };
+        };
 
         if (!lineText || !lineText.includes('/')) {
           callback(undefined);
@@ -980,22 +1131,27 @@ Object.assign(CodemanApp.prototype, {
         const links = [];
 
         // Pattern 0: URLs (https://, http://) — matched first so they take priority
-        const urlPattern = /https?:\/\/[^\s"'<>|;&)\]\x00-\x1f]+/g;
+        //
+        // A single `&` is PART of the URL: it separates query parameters, so excluding
+        // it truncated every real query string (`?post=1479&action=edit` linked only
+        // through `1479`, landing on the wrong page). `&&` is still a boundary, since
+        // that is the shell operator and never appears inside a URL. A lone trailing
+        // `&` is trimmed below with the other trailing punctuation.
+        const urlPattern = /https?:\/\/(?:[^\s"'<>|;&)\]\x00-\x1f]|&(?!&))+/g;
 
         const addUrlLink = (url, matchIndex) => {
           // Strip trailing punctuation that's likely not part of the URL
-          const cleaned = url.replace(/[.,;:!?)]+$/, '');
+          const cleaned = url.replace(/[.,;:!?)&]+$/, '');
           const startCol = lineText.indexOf(cleaned, matchIndex);
           if (startCol === -1) return;
 
-          if (links.some((l) => l.range.start.x === startCol + 1)) return;
+          const start = coordAt(startCol);
+          const end = coordAt(startCol + cleaned.length);
+          if (links.some((l) => l.range.start.x === start.x && l.range.start.y === start.y)) return;
 
           links.push({
             text: cleaned,
-            range: {
-              start: { x: startCol + 1, y: bufferLineNumber },
-              end: { x: startCol + cleaned.length + 1, y: bufferLineNumber },
-            },
+            range: { start, end },
             decorations: { pointerCursor: true, underline: true },
             activate(_event, text) {
               window.open(text, '_blank', 'noopener,noreferrer');
@@ -1017,31 +1173,43 @@ Object.assign(CodemanApp.prototype, {
         // the whole tab on hover. Non-empty token + bounded reps is O(n).
         const cmdPattern = /\b(tail|cat|head|less|grep|watch|vim|nano)\s+(?:[^\s\/]+\s+){0,4}(\/[^\s"'<>|;&\n\x00-\x1f]+)/g;
 
-        // Pattern 2: Paths with common extensions
+        // Pattern 2: Paths with common extensions.
+        // Image/PDF extensions are included so pasted-attachment paths
+        // (`.claude-images/paste-*.png`) are clickable; they open the file preview
+        // rather than the log viewer (see addLink).
         const extPattern =
-          /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js))\b/g;
+          /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js|png|jpe?g|gif|webp|bmp|svg|pdf))\b/g;
 
         // Pattern 3: Bash() tool output
         const bashPattern = /Bash\([^)]*?(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\)\n\x00-\x1f]+)/g;
 
+        /** Extensions that should open the image/document preview, not the log viewer. */
+        const PREVIEW_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg', 'pdf']);
+
         const addLink = (filePath, matchIndex) => {
           const startCol = lineText.indexOf(filePath, matchIndex);
           if (startCol === -1) return;
 
+          const start = coordAt(startCol);
+          const end = coordAt(startCol + filePath.length);
           // Skip if already have link at this position
-          if (links.some((l) => l.range.start.x === startCol + 1)) return;
+          if (links.some((l) => l.range.start.x === start.x && l.range.start.y === start.y)) return;
 
           links.push({
             text: filePath,
-            range: {
-              start: { x: startCol + 1, y: bufferLineNumber }, // 1-based
-              end: { x: startCol + filePath.length + 1, y: bufferLineNumber },
-            },
+            range: { start, end }, // 1-based, may span wrapped rows
             decorations: {
               pointerCursor: true,
               underline: true,
             },
             activate(event, text) {
+              // Tailing a PNG in the log viewer shows binary noise; the file preview
+              // already renders images and PDFs inline.
+              const ext = (text.split('.').pop() || '').toLowerCase();
+              if (PREVIEW_EXTS.has(ext)) {
+                self.openFilePreview(text, self.activeSessionId);
+                return;
+              }
               self.openLogViewerWindow(text, self.activeSessionId);
             },
             hover() {
@@ -1090,10 +1258,24 @@ Object.assign(CodemanApp.prototype, {
   },
 
   showWelcome() {
+    // Phones get the session overview instead of the welcome screen: on a small
+    // screen "which session is blocked on me" beats "how do I start one". The
+    // gate lives in mobile-overview.js; every other device falls through
+    // unchanged. Both surfaces are toggled here so a breakpoint change (rotate,
+    // unfold) swaps cleanly instead of showing both.
+    if (this.shouldUseMobileOverview?.()) {
+      const overlay = document.getElementById('welcomeOverlay');
+      if (overlay) overlay.classList.remove('visible');
+      this.showMobileOverview();
+      this._updateCjkInputState?.();
+      return;
+    }
+    this.hideMobileOverview?.();
     const overlay = document.getElementById('welcomeOverlay');
     if (overlay) {
       overlay.classList.add('visible');
       this.loadTunnelStatus();
+      this.applyWelcomeCliVisibility();
       this.loadHistorySessions();
       this.initSearchPanel();
     }
@@ -1103,6 +1285,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   hideWelcome() {
+    this.hideMobileOverview?.();
     const overlay = document.getElementById('welcomeOverlay');
     if (overlay) {
       overlay.classList.remove('visible');
@@ -1281,7 +1464,7 @@ Object.assign(CodemanApp.prototype, {
     }
     titleSpan.appendChild(document.createTextNode(s.name || s.firstPrompt || shortDir));
 
-    // Badge row: mode (claude/codex/opencode/gemini/shell) + a LIVE pill.
+    // Badge row: mode (claude/codex/opencode/gemini/antigravity/shell) + a LIVE pill.
     const badgeRow = document.createElement('div');
     badgeRow.className = 'history-item-badges';
     if (s.mode) {
@@ -1882,6 +2065,73 @@ 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.
+   */
+  _maybeLoadMoreHistoryOnScroll(lines) {
+    if (lines >= 0) return;
+    if (this.terminal?.buffer?.active?.viewportY === 0) this._maybeRefetchFullHistory?.();
+  },
+
+  /**
+   * Ease-out smooth scrolling for the local wheel path. The capture-phase
+   * wheel handler owns local scrolling (xterm's own smooth scroller is
+   * bypassed, see the listener comment), so without this every notch was an
+   * instant multi-line jump. Wheel deltas accumulate into a pending line
+   * count (fractional — see _wheelScrollLinesFloat) and drain ~22% per
+   * animation frame with a one-line floor, so a single notch starts with a
+   * gentle step and glides to an exact landing; more notches mid-glide deepen
+   * the pending count, which reads as natural acceleration. A sub-line
+   * residual stays pending until further input pushes it past a whole line
+   * (that is what makes slow trackpad drags track the finger). Direction
+   * reversals cancel arithmetically. The pending amount is dropped when the
+   * active session changes mid-glide — leftover momentum must never scroll
+   * the tab the user just switched to.
+   */
+  _smoothScrollBy(lines) {
+    if (!lines) return;
+    this._smoothScrollPending = (this._smoothScrollPending || 0) + lines;
+    this._smoothScrollSession = this.activeSessionId;
+    if (this._smoothScrollFrame) return;
+    const step = () => {
+      this._smoothScrollFrame = null;
+      const pending = this._smoothScrollPending || 0;
+      if (!pending) return;
+      if (this.activeSessionId !== this._smoothScrollSession) {
+        this._smoothScrollPending = 0;
+        return;
+      }
+      if (Math.abs(pending) < 1) return; // sub-line residual: wait for more input
+      const eased = pending * 0.22;
+      const move = pending > 0 ? Math.max(1, Math.floor(eased)) : Math.min(-1, Math.ceil(eased));
+      this._smoothScrollPending = pending - move;
+      this.terminal.scrollLines(move);
+      this._maybeLoadMoreHistoryOnScroll(move);
+      if (Math.abs(this._smoothScrollPending) >= 1) this._smoothScrollFrame = requestAnimationFrame(step);
+    };
+    this._smoothScrollFrame = requestAnimationFrame(step);
+  },
+
+  /**
+   * Hand a scroll gesture (wheel tick or touch drag, already converted to
+   * lines) to the CLI as synthetic SGR wheel reports. SGR coordinates address
+   * the LIVE screen (the bottom `rows` of the buffer), so a report computed
+   * from a scrolled-up viewport would hit-test a different row entirely, and
+   * forwarding while the user stares at stale scrollback looks like the
+   * gesture is dead. Snap back first: the gesture then always acts on what the
+   * CLI is drawing now.
+   */
+  _forwardScrollToApp(clientX, clientY, lines) {
+    if (!this._terminalViewportAtBottom()) this.terminal.scrollToBottom();
+    this._sendSyntheticSgrWheel(clientX, clientY, lines);
+  },
+
   _hasRecentUserScrollUp() {
     if (typeof this._lastUserScrollUpAt !== 'number') return false;
     return performance.now() - this._lastUserScrollUpAt < window.CodemanTerminalInput.USER_SCROLL_STICKY_SUPPRESS_MS;
@@ -2418,6 +2668,50 @@ Object.assign(CodemanApp.prototype, {
     this.terminal.clear();
   },
 
+  /** Insert editable text at the active prompt without pressing Enter. */
+  insertTerminalText(text) {
+    if (!this.activeSessionId || !text) return;
+    if (this._localEchoEnabled && this._localEchoOverlay) {
+      this._localEchoOverlay.appendText(text);
+    } else {
+      this.sendInput(text).catch(() => {});
+    }
+    this.terminal?.focus();
+  },
+
+  /**
+   * Clear only the current editable prompt. This is intentionally distinct
+   * from Ctrl+L (clear display) and the agent's destructive `/clear` command.
+   */
+  clearTerminalInput() {
+    if (!this.activeSessionId) return;
+
+    if (typeof CjkInput !== 'undefined') CjkInput.clear();
+    if (this._inputFlushTimeout) {
+      clearTimeout(this._inputFlushTimeout);
+      this._inputFlushTimeout = null;
+    }
+    this._pendingInput = '';
+
+    if (this._localEchoEnabled && this._localEchoOverlay) {
+      const flushed = this._localEchoOverlay.getFlushed?.() || { count: 0, text: '' };
+      this._localEchoOverlay.clear();
+      this._localEchoOverlay.suppressBufferDetection();
+      this._flushedOffsets?.delete(this.activeSessionId);
+      this._flushedTexts?.delete(this.activeSessionId);
+      if (flushed.count > 0) {
+        this.sendInput('\x7f'.repeat(flushed.count)).catch(() => {});
+      }
+    } else {
+      // In non-local-echo mode the TUI already owns the editable buffer. Ctrl+U
+      // is the conventional kill-line key supported by shells and agent TUIs.
+      this.sendInput('\x15').catch(() => {});
+    }
+
+    this.showToast?.('Input cleared', 'success');
+    this.terminal?.focus();
+  },
+
   /**
    * Restore terminal size to match web UI dimensions.
    * Use this after mobile screen attachment has squeezed the terminal.
@@ -2465,6 +2759,46 @@ Object.assign(CodemanApp.prototype, {
     // intentionally empty
   },
 
+  // Registry-aware gate for the smart-copy chord (#211). Mirrors
+  // shouldOpenCommandPaletteFromShortcut(): honors a rebound or disabled
+  // 'copy-selection' entry, and falls back to the default chord when the
+  // registry isn't available (isolated test harnesses).
+  // Returning true only means "this chord asked to copy", the CALLER decides
+  // what happens when there is no selection, so the interrupt stays intact.
+  shouldCopyTerminalSelectionFromShortcut(ev) {
+    // The custom key handler also runs for keypress/keyup; only keydown decides.
+    if (!ev || ev.type !== 'keydown') return false;
+    // Hot path: every dispatchable chord needs Ctrl/Cmd/Alt, so plain typing
+    // exits before any registry work.
+    if (!ev.ctrlKey && !ev.metaKey && !ev.altKey) return false;
+    const registryAvailable =
+      typeof this.getShortcutRegistry === 'function' && typeof this.matchesShortcutEvent === 'function';
+    const entry = registryAvailable ? this.getShortcutRegistry().find((s) => s.id === 'copy-selection') : null;
+    if (entry) return !entry.disabled && this.matchesShortcutEvent(ev, entry);
+    return !ev.altKey && (ev.key || '').toLowerCase() === 'c';
+  },
+
+  // Copy the current terminal selection. Goes through _copyText (Clipboard API,
+  // then a hidden-textarea + execCommand fallback) because install.sh's LAN
+  // option serves plain HTTP, where navigator.clipboard is undefined.
+  async copyTerminalSelection(text) {
+    const selection = text ?? (this.terminal.hasSelection?.() ? this.terminal.getSelection() : '');
+    if (!selection) return false;
+    const ok = await this._copyText(selection);
+    if (ok) {
+      // Clearing is what makes a second Ctrl+C an interrupt (and xterm already
+      // drops the selection on any keypress, so this matches existing feel).
+      this.terminal.clearSelection?.();
+      this.showToast('Copied to clipboard', 'success');
+    } else {
+      this.showToast('Failed to copy', 'error');
+    }
+    // The execCommand fallback focuses a temp textarea, so hand focus back. This
+    // is the CJK-aware focus router, not xterm's raw focus().
+    this.terminal.focus();
+    return ok;
+  },
+
   async copyTerminal() {
     try {
       const buffer = this.terminal.buffer.active;
@@ -2604,9 +2938,29 @@ Object.assign(CodemanApp.prototype, {
   // deltaY≈0 collapses to a fixed ±1 line/tick and the gesture can't page through
   // history on a trackpad (issue #154). Non-Shift and mouse-wheel paths are
   // unchanged (they carry deltaY). The `|| ±1` keeps sub-25px deltas moving.
+  //
+  // `deltaMode` says what UNIT the delta is in, and ignoring it made every
+  // non-pixel browser scroll ~4x too slowly: Firefox reports DOM_DELTA_LINE (1)
+  // with deltaY≈3 per notch, so the pixel math rounded to 0 and fell through to
+  // the ±1 fallback — one line per notch, versus 4-5 for Chrome's ~110px. In
+  // Claude mode the same value also capped the forwarded SGR report at one tick.
   _wheelScrollLines(ev) {
+    const lines = this._wheelScrollLinesFloat(ev);
+    if (!lines) return 0; // pure horizontal swipe: don't fall through to -1
+    return Math.round(lines) || (lines > 0 ? 1 : -1);
+  },
+
+  /** Unrounded variant for the smooth local-scroll path, which accumulates
+   *  sub-line fractions across events instead of forcing every tiny trackpad
+   *  delta to a whole ±1 line. Same unit handling and Shift-axis trap. */
+  _wheelScrollLinesFloat(ev) {
     const delta = ev.shiftKey && Math.abs(ev.deltaX) > Math.abs(ev.deltaY) ? ev.deltaX : ev.deltaY;
-    return Math.round(delta / 25) || (delta > 0 ? 1 : -1);
+    if (!delta) return 0;
+    return ev.deltaMode === 1 // DOM_DELTA_LINE (Firefox mouse wheel)
+      ? delta
+      : ev.deltaMode === 2 // DOM_DELTA_PAGE
+        ? delta * (this.terminal?.rows || 24)
+        : delta / 25; // DOM_DELTA_PIXEL (Chrome/WebKit, and every trackpad)
   },
 
   _shouldForwardWheelToApp(ev) {
@@ -2625,7 +2979,23 @@ Object.assign(CodemanApp.prototype, {
     } else if (sessionMode !== 'codex') {
       return false;
     }
-    return this._terminalViewportAtBottom();
+    // Deliberately NOT gated on _terminalViewportAtBottom(). It used to be, so
+    // that leaving the bottom handed the wheel back to local scrollback and both
+    // histories stayed reachable without a mode switch. In practice that inverted
+    // the behavior users actually want: a repaint-mode CLI keeps NO terminal
+    // scrollback of its own (tmux reports history_size=0 for a Claude pane), so
+    // xterm's buffer holds only Codeman's REPLAYED repaint frames. Scrolling that
+    // locally drags the CLI's own pinned furniture (the prompt box, the status
+    // line) up the screen and shows stale frames underneath, which reads as "the
+    // window scrolled away" rather than "I am reading history".
+    //
+    // And it was easy to fall into: scrollToLastNonEmptyLine() parks the viewport
+    // `rows - 2` above the last non-empty row, so any tab switch onto a session
+    // with trailing blank rows left the viewport off-bottom and every later wheel
+    // went local. Forwarding unconditionally keeps the CLI's transcript as the
+    // plain wheel's target and its input box fixed in place; local scrollback is
+    // still on Shift+wheel and on the "Wheel scrolls local history" opt-out above.
+    return true;
   },
 
   // Encode wheel ticks as SGR reports (button 64 = up, 65 = down) at the pointer
@@ -2846,8 +3216,14 @@ Object.assign(CodemanApp.prototype, {
   // DOM and WebGL renderers) plus a belt-and-suspenders refresh().
   applyTerminalSkin(skin) {
     const theme = { ...(window.CODEMAN_XTERM_THEMES[skin] || window.CODEMAN_XTERM_THEMES['daylight-blue']) };
+    const minimumContrastRatio = window.codemanCurrentSkinIsLight(skin) ? 4.5 : 1;
     if (this.terminal) {
+      this.terminal.options.minimumContrastRatio = minimumContrastRatio;
       this.terminal.options.theme = theme;
+      // The zero-lag typing overlay caches the xterm foreground/background.
+      // Refresh it on live skin changes so typed text never keeps the prior
+      // theme's dark backing surface or foreground color.
+      this._localEchoOverlay?.refreshFont();
       try {
         this.terminal.refresh(0, this.terminal.rows - 1);
       } catch {}
@@ -2855,6 +3231,7 @@ Object.assign(CodemanApp.prototype, {
     if (this.teammateTerminals) {
       for (const [, entry] of this.teammateTerminals) {
         if (entry && entry.terminal) {
+          entry.terminal.options.minimumContrastRatio = minimumContrastRatio;
           entry.terminal.options.theme = { ...theme };
           try {
             entry.terminal.refresh(0, entry.terminal.rows - 1);

src/web/public/ultracode-windows.js

@@ -210,6 +210,9 @@ Object.assign(CodemanApp.prototype, {
     document.body.appendChild(win);
     // Drop the spawn class on the next frame so the transition runs.
     requestAnimationFrame(() => win.classList.remove('spawning'));
+    // Then hand over to the chosen entrance style (no-op for `fly`/`off`, which
+    // leave the small scale-in transition above as the whole animation).
+    this.applyWindowEntrance?.(win);
 
     const header = win.querySelector('.ultracode-window-header');
     const dragListeners = this.makeWindowDraggable(win, header);
@@ -586,6 +589,7 @@ Object.assign(CodemanApp.prototype, {
 
     document.body.appendChild(win);
     requestAnimationFrame(() => win.classList.remove('spawning'));
+    this.applyWindowEntrance?.(win);
 
     const header = win.querySelector('.ultracode-window-header');
     const dragListeners = this.makeWindowDraggable(win, header);