chore: version packages

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merge pull request #213 from Ark0N/feat/file-viewer-edit-mode
2026-10-01 13:09:42 +02:00 · 2026-08-05 09:01:45 +02:00 · 2026-08-05 09:00:22 +02:00 · 2026-08-05 08:44:47 +02:00 · 2026-08-05 02:38:57 +02:00 · 2026-08-05 02:10:55 +02:00
49 changed files with 3408 additions and 103 deletions
@@ -1,5 +1,33 @@
 # aicodeman

+## 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
@@ -74,7 +74,7 @@ When user says "COM":

 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.

-**Version**: 1.9.9 (must match `package.json`)
+**Version**: 1.11.0 (must match `package.json`)

 ## Project Overview

@@ -214,6 +214,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Filesystem path picker** (Link Existing "Browse" + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file. Inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping** — it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)

+**File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place — `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that WRITES**: read-path confinement (realpath + workspace + ownership) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md`
+
 **Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)

 **Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
@@ -236,7 +238,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 **Phone overview home screen** (`mobile-overview.js`, phones only, per-device `mobileOverviewEnabled`, default ON): under 430px the "C" logo shows a session overview (NEEDS YOU / CURRENT SESSIONS / PAST SESSIONS) instead of the welcome overlay; tablet and desktop are unchanged. The branch lives in `showWelcome()`/`hideWelcome()` (terminal-ui.js) behind `shouldUseMobileOverview()`, which is **width-driven** (`getDeviceType() === 'mobile'`) because this is a layout decision, unlike the settings namespace which stays handheld-based. ⚠️ The container ships with the `hidden` attribute and only this module removes it: never give `.mobile-overview` a bare `display` rule, since desktop does not load `mobile.css` (`media="(max-width: 1023px)"`) and would then render it unstyled. Live re-renders ride on the tail of `_renderSessionTabsImmediate()` (every state change it needs already funnels there); PAST rows come from one `_fetchUnifiedSessions(60)` per home-screen visit and resume through the shared `resumeHistorySession()`, so they behave exactly like the welcome screen's Resume list. ⚠️ Two things must stay in lockstep with surfaces outside this module, because divergence reads as a bug rather than a style: the split Run button carries the **toolbar's own classes** (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) so the per-backend gradient and the light-skin overrides apply unchanged (mobile.css must therefore set no `background`/`color` on it), and row status uses the **session-tab language** (green dot when fine, `pulse` while working, yellow blinking row when waiting for input, red blinking row when a question is pending, mirroring `tab-alert-idle`/`tab-alert-action`). The picker mirrors the toolbar run-mode menu (`setRunMode()` + `run()`, `openWebviewFromMenu()` for saved dashboards) and deliberately omits its Recent-Sessions block, since PAST SESSIONS is that. Status pills carry `data-i18n-skip` (generic words like "idle" collide with state strings elsewhere).

-**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)
+**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. ⚠️ **Smart copy (`Ctrl+C`)** lives in that same handler: with a selection it copies, with none it must `return true` **without** `preventDefault()` or the interrupt is lost. `copyTerminalSelection` is deliberately absent from `SHORTCUT_ACTIONS` because the generic capture loop preventDefaults every match it dispatches. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)

 **Per-device vs synced settings**: the `displayKeys` set in settings-ui.js is a **client-side merge policy**, not a wire filter. A display key seeds from the server only when localStorage has no value for it, which is what prevents one device overwriting another; `showPlanUsageLimits` is additionally `delete`d from the incoming payload outright. Separately, `SettingsUpdateSchema` is `.strict()` and simply **does not declare** `skin`, `showFileViewerButton`, `showCronButton`, `webglRendererEnabled`, `localEchoEnabled`, `cjkInputEnabled`, or `extendedKeyboardBar`, so sending one of those is a validation error. The rest (`showResponseViewer`, `showPlanUsageLimits`, `language`, and most `show*` keys) ARE in the schema and do persist server-side; they are per-device by client policy only. ⚠️ Adding a new per-device setting means deciding **both** questions: membership in `displayKeys`, and presence in the schema.

@@ -260,7 +262,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).

-**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry.
+**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+C (copy selection, else interrupt) / Ctrl+Shift+C (copy, never interrupts), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry.

 ### Security

@@ -651,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                                            |
@@ -641,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`                  | 切换语音输入                                             |
@@ -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,
@@ -87,6 +87,19 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough

 The general rule: **any new endpoint that turns a caller-supplied `sessionId` into a filesystem path is an ownership boundary**, whether or not it goes through `findSessionOrFail`.

+### File Viewer edit mode
+
+**File Viewer edit mode** (issue #212, design in `docs/file-viewer-edit-plan.md`): the file-preview overlay can edit workspace text files in place — `GET /api/sessions/:id/file-content?edit=1` (read-for-edit) + `PUT /api/sessions/:id/file-content` (save), policy in `src/config/file-editing.ts`, UI in `panels-ui.js`. This is the **only file surface that writes**, so it carries every rule the read surfaces have plus its own:
+
+- **Confinement is the read path's, plus write-only gates.** `findSessionOrFail` (ownership) → `validateSessionFilePath` (realpath + workspace boundary; escapes report as 404, same as reads) → sensitive-path + attachment-guard blocklists (403) → `.git/` subtree deny (403 — `.git/hooks/*` is code execution) → extension **allowlist** (400; `svg` and `env` deliberately excluded). ⚠️ **There is no `O_CREAT` anywhere in the handler** — that absence is what makes "edit-in-place only, never create" a structural property instead of a convention. Do not add a create path without treating it as a new security surface.
+- **A truncated buffer must never become an edit buffer.** The plain preview truncates to `lines` (default 500); saving such a buffer would silently delete everything past the cut, and the hash check cannot catch it (the loaded prefix hashes differently from the full file, which reads as an ordinary conflict at best). `edit=1` therefore never truncates — it 413s over `MAX_EDITABLE_BYTES` (512KB) instead — and the frontend always re-fetches with `edit=1` before swapping in the textarea, even though the preview already holds content.
+- **Concurrency is optimistic by content hash, not mtime.** The client echoes the sha256 it loaded (`baseHash`); mismatch → 409 CONFLICT (plain envelope — the error arm carries no data; the client re-fetches `edit=1` for fresh state) unless `force:true`. mtime alone is wrong: agents rewrite files within one timestamp tick.
+- **Writes are `wx` temp + `fchmod` + `fsync` + `rename` in the target's directory.** `wx` cannot follow a pre-existing symlink and `rename()` replaces (not follows) a symlink final component, which closes the validate-then-write TOCTOU window; `fchmod` because `open()`'s mode argument is masked by the umask; a symlink whose target is *inside* the workspace is deliberately written through (validation returns the realpath). Trade-off (same as vim): the inode changes, so hardlinks keep old content.
+- **Corruption guards**: NUL-sniff + UTF-8 **round-trip compare** (`Buffer.from(buf.toString('utf8'), 'utf8').equals(buf)`) refuse binary and non-UTF-8 files — decoding latin-1 yields U+FFFD replacements and writing those back destroys the original bytes. EOL is detected server-side and re-applied on save because a `<textarea>` normalizes to LF (a two-line edit of a CRLF file must not become a whole-file diff).
+- **Two size caps on the wire**: the Zod `.max()` counts UTF-16 code units (coarse pre-filter, 400) while the handler's `Buffer.byteLength` check enforces the real byte cap (413); the route sets `bodyLimit: 4MB` because JSON escaping can expand 512KB of content past Fastify's 1MB default. Error paths **throw** structured `{statusCode, body}` errors (`throwFileEditError`) rather than returning envelopes — the central preSerialization status-mapping hook is absent from the route-test harness, and 413 has no errorCode mapping at all.
+
+Tests: `test/file-editing-policy.test.ts` (pure policy), `test/routes/file-write-routes.test.ts` (deliberately **unmocked fs** against a real temp workspace — symlink/TOCTOU/mode behavior must be exercised for real).
+
 ### Ultracode and workflow-run visualization

 **Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a COMPLETION artifact per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json` (written only at run end); LIVE in-flight runs exist only as transcript dirs at `…/subagents/workflows/wf_<id>/` (journal.jsonl + `agent-*.jsonl`). `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; separate singleton, though it independently reads the same `subagents/workflows/` tree) scans BOTH sources via periodic poll + per-directory chokidar watchers with per-source mtime skip (LRU agentStatCache + journalCache), synthesizing ACTIVE runs (live per-agent tokens/tools/state from transcripts, title/phases from the workflow script) until the completion `wf_*.json` appears and supersedes, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is started when **either** `showUltracodeAgents` **or** `ultracodeFloatingWindows` is on (`server.ts` `isWorkflowAgentTrackingEnabled()` returns `(showUltracodeAgents ?? false) || (ultracodeFloatingWindows ?? false)`). Served via `GET /api/workflows` (optional `?minutes=` filter) and `GET /api/workflows/:runId`. Frontend `ultracode-panel.js` renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side `agentId` join). **Additionally**, `ultracode-windows.js` auto-pops a draggable **floating window per active run** (gated on a **DEDICATED** `ultracodeFloatingWindows` toggle, default OFF — independent of the dock panel's `showUltracodeAgents`; see `_ultracodeFloatingEnabled()`), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines` SVG from the tail of `_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Clicking an agent card opens an **in-page** connected transcript window (not a browser popup); both run and transcript windows minimize **into** the originating session tab as a merged `ULTRA` badge (🧬 runs / 📄 transcripts) with a restore/dismiss dropdown — minimized runs are skipped by auto-pop. Gesture beta: floating subagent/ultracode windows are pinch-draggable (a `window` grab kind in `entry.ts`). Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
@@ -138,6 +151,14 @@ The general rule: **any new endpoint that turns a caller-supplied `sessionId` in

 **Command palette + shortcut registry** (COD-151/153/157/192, #146): `Ctrl/Cmd/Alt+K` opens the session palette (fuzzy search over live sessions; "Browse all sessions" → the Session Manager modal backed by `GET /api/sessions/unified`); the quick-start case `<select>` is fronted by a searchable picker (`buildCasePickerOptions`/`formatCasePickerLabel` — remote cases render `name @ hostId`). Shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js; overrides persist under `settings.shortcutOverrides` via `saveAppSettingsToStorage`); App Settings → Shortcuts renders capture/disable rows; `Ctrl+?` opens the registry-driven overlay (footer links to the full `#helpModal` reference). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM — keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over.

+**Terminal smart copy** (#211): `Ctrl+C` copies the selection when there is one and stays the interrupt when there isn't. Three rules keep that split honest, and breaking any of them silently costs the user their interrupt key:
+
+1. The branch lives in `attachCustomKeyEventHandler` (terminal-ui.js) and the **no-selection path returns `true` with no `preventDefault()`**, so xterm still evaluates `Ctrl+C` into `0x03`. Returning `false` alone does not cancel the event either way: xterm's `_keyDown` calls the custom handler *before* its own `cancel()`, which is exactly why the copy path calls `preventDefault()` explicitly (otherwise the browser also runs its native copy on top).
+2. `copyTerminalSelection` is a registry `action` **deliberately missing from `SHORTCUT_ACTIONS`** (same trick as `command-palette`): the entry stays rebindable and disableable in App Settings, while the generic document-capture loop, which `preventDefault()`s every match it dispatches, skips it and lets the terminal handler decide.
+3. The gate is keydown-only (the custom handler also runs for `keypress`/`keyup`), and `Ctrl+Shift+C` never falls through to the PTY: an "explicit copy" chord that interrupts a running agent because the selection happened to be empty is a footgun with no upside.
+
+Copy goes through `_copyText()` (Clipboard API, then hidden-textarea + `execCommand`), not raw `navigator.clipboard`, because `install.sh`'s LAN option serves plain HTTP where `navigator.clipboard` is undefined; the fallback steals focus, so the terminal is refocused afterwards. Related: xterm registers its own `copy` listener on the terminal element gated on `hasSelection()`, which is why right-click → Copy has always worked. Selection itself is unavailable on touch devices by design (`user-select: none` on the terminal subtree), and in `shell`/`opencode`/`antigravity` tabs the TUI owns the mouse, so selecting there needs Shift+drag. Tests: `test/terminal-copy-selection.test.ts` (gate + wiring invariants), `test/terminal-copy-shortcut.test.ts` (browser, real key presses).
+
 ### WebGL renderer toggle

 **WebGL renderer toggle** (#140, `webglRendererEnabled`): per-device (`displayKeys` set, stripped from the server payload — NOT in `SettingsUpdateSchema`, which is `.strict()`). The GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads; it's cleared only by an explicit OFF→ON save transition or `?webgl=force` (`shouldSkipWebGL` in constants.js). `?nowebgl` still forces the DOM renderer per-load.
@@ -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.
@@ -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.
@@ -1,12 +1,12 @@
 {
  "name": "aicodeman",
-  "version": "1.9.9",
+  "version": "1.11.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "aicodeman",
-      "version": "1.9.9",
+      "version": "1.11.0",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "1.9.9",
+  "version": "1.11.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",
@@ -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;
+}
@@ -58,17 +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',
-    antigravity: 'exec agy',
+    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;
 }
@@ -49,7 +49,12 @@ import {
  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,
@@ -72,6 +77,7 @@ import {
  resolveGeminiDir,
  resolveAntigravityDir,
  resolveLocalShell,
+  loginShellArgs,
 } from './utils/index.js';
 import type {
  TerminalMultiplexer,
@@ -643,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);
@@ -780,7 +790,15 @@ export function buildSpawnCommand(options: {
  // 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.
-  return shellescape(resolveLocalShell());
+  // #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)}`;
 }

 /**
@@ -852,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);

@@ -884,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
@@ -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 */
@@ -97,6 +97,22 @@ export interface FilesystemBrowseData {
  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';

 /**
@@ -305,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;
 }
@@ -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`/`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.
@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Resolve the `cloudflared` binary across common install paths.
+ *
+ * Mirrors the CLI resolvers (gemini-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;
+}
@@ -26,7 +26,7 @@ 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 { resolveLocalShell } from './shell-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';
@@ -33,6 +33,18 @@ const FALLBACK_SHELLS = ['/bin/bash', '/bin/zsh', '/bin/sh'];
 */
 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);
@@ -76,3 +88,24 @@ export function resolveLocalShell(): string {
  // 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' : '';
+}
@@ -349,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',
@@ -451,6 +451,7 @@
    'Respawn Blocked': '重生已阻止',
    'Task Complete': '任务完成',
    'Copied to clipboard': '已复制到剪贴板',
+    'Failed to copy': '复制失败',
    'Checking…': '正在检查…',
    'Starting…': '正在启动…',
    'Starting update…': '正在开始更新…',
@@ -600,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': '全部标为已读',
@@ -311,19 +311,19 @@
          <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-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>
@@ -422,11 +422,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>
@@ -639,6 +646,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>
@@ -1688,6 +1697,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">
@@ -1871,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%;
@@ -3200,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;
@@ -3298,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);
@@ -3306,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');
@@ -3313,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)
  // ═══════════════════════════════════════════════════════════════
@@ -3749,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');
@@ -441,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');
@@ -451,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;
@@ -582,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
@@ -671,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();
@@ -706,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',
@@ -747,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) {
@@ -762,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);
    }
  },

@@ -805,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
@@ -913,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);
    }
  },

@@ -924,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();

@@ -936,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;
        }
      }
@@ -970,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);
    }
  },

@@ -981,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 {
@@ -991,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;
        }
      }
@@ -1009,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 } : {}),
@@ -1027,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);
    }
  },

@@ -1038,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 {
@@ -1048,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;
        }
      }
@@ -1078,7 +1130,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);
    }
  },

@@ -1089,9 +1141,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 Antigravity session in ${caseName}...\x1b[0m`);
-    this.terminal.writeln('');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Antigravity session in ${caseName}...`);
    this.terminal.focus();

    try {
@@ -1099,8 +1149,10 @@ Object.assign(CodemanApp.prototype, {
        const statusRes = await fetch('/api/antigravity/status');
        const status = (await statusRes.json()).data;
        if (!status.available) {
-          this.terminal.writeln('\x1b[1;31m Antigravity CLI not found.\x1b[0m');
-          this.terminal.writeln('\x1b[90m Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash\x1b[0m');
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
+          );
          return;
        }
      }
@@ -1129,7 +1181,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);
    }
  },

@@ -373,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 ?? '';
@@ -485,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
@@ -694,6 +723,42 @@ 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'],
+      ['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');
@@ -1482,6 +1547,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,
@@ -9430,6 +9430,84 @@ kbd {
  flex-shrink: 0;
 }

+/* ---- File Viewer edit mode (issue #212) ---- */
+
+.file-preview-body textarea.file-preview-editor {
+  display: block;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0.75rem;
+  border: none;
+  outline: none;
+  resize: none;
+  background: var(--bg-dark);
+  color: var(--text);
+  font-family: var(--font-mono);
+  font-size: 0.8rem;
+  line-height: 1.5;
+  white-space: pre;
+  overflow-wrap: normal;
+  overflow: auto;
+  tab-size: 4;
+}
+
+.file-preview-editbar {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.4rem 0.75rem;
+  border-top: 1px solid var(--border);
+  background: var(--bg-input);
+  flex-shrink: 0;
+}
+
+.file-preview-editbar[hidden] {
+  display: none;
+}
+
+.file-preview-editbar-spacer {
+  flex: 1;
+}
+
+.file-preview-dirty {
+  font-size: 0.7rem;
+  color: var(--warning, #e5c07b);
+}
+
+.file-preview-dirty::before {
+  content: '\25CF  ';
+}
+
+.file-preview-editbar-btn {
+  padding: 0.3rem 0.9rem;
+  font-size: 0.75rem;
+  border-radius: 6px;
+  border: 1px solid var(--control-border);
+  background: var(--bg-input);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.file-preview-editbar-btn:hover {
+  background: var(--bg-hover, rgba(255, 255, 255, 0.08));
+}
+
+.file-preview-editbar-btn--save {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.file-preview-editbar-btn--save:hover {
+  background: var(--accent-hover);
+}
+
+.file-preview-editbar-btn--save:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
 /* ========== Log Viewer Windows (Floating) ========== */

 .log-viewer-window {
@@ -158,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') {
@@ -1195,6 +1219,7 @@ Object.assign(CodemanApp.prototype, {
    if (overlay) {
      overlay.classList.add('visible');
      this.loadTunnelStatus();
+      this.applyWelcomeCliVisibility();
      this.loadHistorySessions();
      this.initSearchPanel();
    }
@@ -2611,6 +2636,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;
@@ -1,12 +1,16 @@
 /**
 * @fileoverview File browser and streaming routes.
- * Provides directory listing, file content preview, raw file serving, and tail streaming.
+ * Provides directory listing, file content preview, raw file serving, tail
+ * streaming, and the File Viewer edit-mode write path (edit=1 read +
+ * PUT /api/sessions/:id/file-content; policy in src/config/file-editing.ts,
+ * design in docs/file-viewer-edit-plan.md).
 */

 import { FastifyInstance, type FastifyReply } from 'fastify';
-import { basename as pathBasename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { basename as pathBasename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { createReadStream, realpathSync, type ReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
+import { createHash, randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import type {
  ApiResponse,
@@ -14,6 +18,7 @@ import type {
  FilesystemBrowseEntry,
  FilesystemBrowseRoot,
  FilesystemPreviewKind,
+  FileWriteData,
 } from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import { fileStreamManager } from '../../file-stream-manager.js';
@@ -44,7 +49,14 @@ import type { SessionAttachmentHistoryItem, SessionState } from '../../types/ses
 import { isSensitivePath } from '../sensitive-path.js';
 import { SseEvent } from '../sse-events.js';
 import type { ConfigPort, EventPort, SessionPort } from '../ports/index.js';
-import { FilesystemBrowseQuerySchema, FilesystemPreviewQuerySchema } from '../schemas.js';
+import { FilesystemBrowseQuerySchema, FilesystemPreviewQuerySchema, FileWriteSchema } from '../schemas.js';
+import {
+  MAX_EDITABLE_BYTES,
+  applyEol,
+  detectEol,
+  isDeniedEditRelativePath,
+  isEditableFileName,
+} from '../../config/file-editing.js';

 const MIME_TYPES: Record<string, string> = {
  png: 'image/png',
@@ -453,6 +465,71 @@ function appendDownloadFlag(url: string): string {
  return `${url}${url.includes('?') ? '&' : '?'}download=true`;
 }

+// ===== File Viewer edit mode (issue #212) =====
+// Policy lives in src/config/file-editing.ts; design in docs/file-viewer-edit-plan.md.
+
+function sha256Hex(buf: Buffer): string {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/** NUL byte in the first 8KB — same binary signal the plain read path uses. */
+function sniffsBinary(buf: Buffer): boolean {
+  const sniffLength = Math.min(buf.length, 8192);
+  for (let i = 0; i < sniffLength; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Structured-throw variant for the edit read/write paths. Identical mechanics to
+ * throwFilesystemPickerError (rendered by the central route error handler both
+ * in prod and in the app.inject() test harness); a separate name only so edit
+ * failures grep distinctly.
+ */
+function throwFileEditError(statusCode: number, code: ApiErrorCode, message: string): never {
+  throw Object.assign(new Error(message), {
+    statusCode,
+    body: createErrorResponse(code, message),
+  });
+}
+
+/**
+ * Gate a resolved workspace file for edit-mode read/write. Throws a structured
+ * error when the file may not be edited; returns void when it may. Order
+ * matters for the message a user sees: confinement (the caller's 404) →
+ * sensitive/blocked (403) → .git (403) → extension allowlist (400).
+ */
+function assertEditableTarget(resolvedPath: string, relativePath: string, blockedTrees: readonly string[]): void {
+  if (isSensitivePath(resolvedPath) || isBlockedAttachmentPath(resolvedPath, blockedTrees)) {
+    throwFileEditError(403, ApiErrorCode.FORBIDDEN, 'Editing this file is blocked');
+  }
+  if (isDeniedEditRelativePath(relativePath)) {
+    throwFileEditError(403, ApiErrorCode.FORBIDDEN, 'Files under .git cannot be edited');
+  }
+  if (!isEditableFileName(pathBasename(resolvedPath))) {
+    throwFileEditError(400, ApiErrorCode.INVALID_INPUT, 'This file type is not editable');
+  }
+}
+
+/**
+ * Decode a candidate edit buffer, refusing binary and non-UTF-8 content. The
+ * round-trip compare is what protects against silent corruption: decoding
+ * latin-1 (or any non-UTF-8) bytes yields U+FFFD replacements, and writing
+ * those back would destroy the original bytes. A UTF-8 BOM round-trips and is
+ * deliberately preserved.
+ */
+function decodeEditableText(buf: Buffer): string {
+  if (sniffsBinary(buf)) {
+    throwFileEditError(400, ApiErrorCode.INVALID_INPUT, 'Binary files cannot be edited');
+  }
+  const text = buf.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(buf)) {
+    throwFileEditError(400, ApiErrorCode.INVALID_INPUT, 'Only UTF-8 text files can be edited');
+  }
+  return text;
+}
+
 function getSessionAttachmentHistory(
  ctx: SessionPort & ConfigPort,
  sessionId: string,
@@ -864,7 +941,12 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
  // Get file content for preview (File Browser)
  app.get('/api/sessions/:id/file-content', async (req) => {
    const { id } = req.params as { id: string };
-    const { path: filePath, lines, raw } = req.query as { path?: string; lines?: string; raw?: string };
+    const {
+      path: filePath,
+      lines,
+      raw,
+      edit,
+    } = req.query as { path?: string; lines?: string; raw?: string; edit?: string };
    const session = findSessionOrFail(ctx, id, req);

    if (!filePath) {
@@ -876,7 +958,52 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
    if (!validated) {
      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found');
    }
-    const { resolvedPath } = validated;
+    const { resolvedPath, relativePath } = validated;
+
+    // Read-for-edit: never truncated (a truncated buffer must never become an
+    // edit buffer), tighter size cap, full editability gate, and the hash/eol
+    // the client must echo back on PUT. Outside the shared try/catch below so
+    // its structured errors keep their status codes instead of collapsing into
+    // OPERATION_FAILED.
+    if (edit === '1' || edit === 'true') {
+      const guard = await loadAttachmentGuardConfig();
+      assertEditableTarget(resolvedPath, relativePath, guard.blockedTrees);
+
+      let editStat;
+      try {
+        editStat = await fs.stat(resolvedPath);
+      } catch {
+        throwFileEditError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+      }
+      if (!editStat.isFile()) {
+        throwFileEditError(400, ApiErrorCode.INVALID_INPUT, 'Only regular files can be edited');
+      }
+      if (editStat.size > MAX_EDITABLE_BYTES) {
+        throwFileEditError(
+          413,
+          ApiErrorCode.INVALID_INPUT,
+          `File too large to edit here (${Math.ceil(editStat.size / 1024)}KB > ${MAX_EDITABLE_BYTES / 1024}KB limit)`
+        );
+      }
+
+      const editBuf = await fs.readFile(resolvedPath);
+      const editText = decodeEditableText(editBuf);
+      return {
+        success: true,
+        data: {
+          path: filePath,
+          content: editText,
+          size: editBuf.length,
+          mtimeMs: editStat.mtimeMs,
+          totalLines: editText.split('\n').length,
+          truncated: false,
+          extension: filePath.split('.').pop()?.toLowerCase() || '',
+          editable: true,
+          hash: sha256Hex(editBuf),
+          eol: detectEol(editText),
+        },
+      };
+    }

    try {
      const stat = await fs.stat(resolvedPath);
@@ -998,6 +1125,19 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
      const truncatedContent = allLines.length > maxLines;
      const displayContent = truncatedContent ? allLines.slice(0, maxLines).join('\n') : content;

+      // Additive edit-mode advertisement: whether an edit=1 re-fetch would
+      // succeed. The UTF-8 round-trip compare is a cheap memcmp and mirrors
+      // decodeEditableText; no hash here — the Edit action re-fetches with
+      // edit=1, which is where the baseHash comes from.
+      const guard = await loadAttachmentGuardConfig();
+      const editable =
+        isEditableFileName(pathBasename(resolvedPath)) &&
+        !isDeniedEditRelativePath(relativePath) &&
+        !isSensitivePath(resolvedPath) &&
+        !isBlockedAttachmentPath(resolvedPath, guard.blockedTrees) &&
+        stat.size <= MAX_EDITABLE_BYTES &&
+        Buffer.from(content, 'utf8').equals(buf);
+
      return {
        success: true,
        data: {
@@ -1007,6 +1147,7 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
          totalLines: allLines.length,
          truncated: truncatedContent,
          extension: ext,
+          editable,
        },
      };
    } catch (err) {
@@ -1014,6 +1155,121 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & Even
    }
  });

+  // File Viewer edit mode: save a text file back into the session workspace.
+  // Edit-in-place ONLY — there is deliberately no O_CREAT path in this handler,
+  // so it can never create, and it never deletes. Confinement is identical to
+  // the read path (realpath + workspace boundary + ownership via
+  // findSessionOrFail), plus the sensitive-path/attachment-guard blocklists and
+  // the extension allowlist. Concurrency is optimistic: the client echoes the
+  // sha256 it loaded (baseHash) and a mismatch is a 409 unless force is set.
+  // bodyLimit: JSON escaping can expand content up to ~6x (each control char
+  // becomes \uXXXX), so the 512KB content cap needs headroom over Fastify's
+  // 1MB default.
+  app.put(
+    '/api/sessions/:id/file-content',
+    { bodyLimit: 4 * 1024 * 1024 },
+    async (req): Promise<ApiResponse<FileWriteData>> => {
+      const { id } = req.params as { id: string };
+      const session = findSessionOrFail(ctx, id, req);
+      const body = parseBody(FileWriteSchema, req.body);
+
+      // Exact byte cap — the schema's .max() counts UTF-16 code units and is
+      // only a coarse pre-filter.
+      if (Buffer.byteLength(body.content, 'utf8') > MAX_EDITABLE_BYTES) {
+        throwFileEditError(413, ApiErrorCode.INVALID_INPUT, `Content too large (${MAX_EDITABLE_BYTES / 1024}KB limit)`);
+      }
+
+      const validated = validateSessionFilePath(session.workingDir, body.path);
+      if (!validated) {
+        // Covers missing files, traversal, and symlink escapes alike — a write
+        // target that fails confinement is reported identically to a missing
+        // one, matching the read route.
+        throwFileEditError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+      }
+      const { resolvedPath, relativePath } = validated;
+
+      const guard = await loadAttachmentGuardConfig();
+      assertEditableTarget(resolvedPath, relativePath, guard.blockedTrees);
+
+      let stat;
+      try {
+        stat = await fs.stat(resolvedPath);
+      } catch {
+        throwFileEditError(404, ApiErrorCode.NOT_FOUND, 'File not found');
+      }
+      if (!stat.isFile()) {
+        throwFileEditError(400, ApiErrorCode.INVALID_INPUT, 'Only regular files can be edited');
+      }
+      if (stat.size > MAX_EDITABLE_BYTES) {
+        throwFileEditError(
+          413,
+          ApiErrorCode.INVALID_INPUT,
+          `File too large to edit here (${MAX_EDITABLE_BYTES / 1024}KB limit)`
+        );
+      }
+
+      const currentBuf = await fs.readFile(resolvedPath);
+      const currentText = decodeEditableText(currentBuf);
+      const currentHash = sha256Hex(currentBuf);
+      if (currentHash !== body.baseHash && !body.force) {
+        throwFileEditError(
+          409,
+          ApiErrorCode.CONFLICT,
+          'File changed on disk since it was loaded — reload it or overwrite'
+        );
+      }
+
+      // Re-apply the file's original line endings (a <textarea> normalizes to
+      // LF; without this a two-line edit of a CRLF file rewrites every line).
+      const eol = body.eol ?? detectEol(currentText);
+      const outText = applyEol(body.content, eol);
+      const outBuf = Buffer.from(outText, 'utf8');
+      if (outBuf.length > MAX_EDITABLE_BYTES) {
+        throwFileEditError(413, ApiErrorCode.INVALID_INPUT, `Content too large (${MAX_EDITABLE_BYTES / 1024}KB limit)`);
+      }
+
+      // Atomic replace: O_EXCL temp in the same directory, then rename.
+      // 'wx' cannot follow a pre-existing symlink and rename() replaces (not
+      // follows) a symlink in the final component, which closes the
+      // validate-then-write TOCTOU window. fchmod because open()'s mode is
+      // masked by the process umask; fsync so the rename never publishes a
+      // partially-durable file. Trade-off (same as vim's default): the inode
+      // changes, so hardlinks keep the old content.
+      const fileMode = stat.mode & 0o777;
+      const tmpPath = join(
+        dirname(resolvedPath),
+        `.${pathBasename(resolvedPath)}.codeman-tmp-${randomBytes(6).toString('hex')}`
+      );
+      let handle;
+      try {
+        handle = await fs.open(tmpPath, 'wx', fileMode);
+        await handle.chmod(fileMode);
+        await handle.writeFile(outBuf);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(tmpPath, resolvedPath);
+      } catch (err) {
+        if (handle) await handle.close().catch(() => {});
+        await fs.unlink(tmpPath).catch(() => {});
+        throwFileEditError(500, ApiErrorCode.OPERATION_FAILED, `Failed to save file: ${getErrorMessage(err)}`);
+      }
+
+      const newStat = await fs.stat(resolvedPath).catch(() => undefined);
+      return {
+        success: true,
+        data: {
+          path: body.path,
+          size: outBuf.length,
+          mtimeMs: newStat?.mtimeMs ?? Date.now(),
+          hash: sha256Hex(outBuf),
+          totalLines: outText.split('\n').length,
+          eol,
+        },
+      };
+    }
+  );
+
  // Serve raw file content (for images/binary files)
  app.get('/api/sessions/:id/file-raw', async (req, reply) => {
    const { id } = req.params as { id: string };
@@ -2551,7 +2551,12 @@ export function registerSessionRoutes(
      for (let end = maxLook - 1; end >= idx; end--) {
        const candidates: string[] = [];
        if (end === idx) {
-          candidates.push(segments[idx]);
+          // Skip an EMPTY segment: `isDir(current + '/' + '')` stats `current + '/'`,
+          // which always succeeds, so the empty candidate would match unconditionally
+          // and swallow the doubled dash that is the whole signature of a dotdir. It
+          // then resolves "/home/x/.sib" to "/home/x//sib" whenever a non-dot sibling
+          // exists, and shadows the dotdir branch below in every other case.
+          if (segments[idx] !== '') candidates.push(segments[idx]);
        } else {
          candidates.push(segments.slice(idx, end + 1).join('-'));
          candidates.push(segments.slice(idx, end + 1).join('_'));
@@ -2564,6 +2569,25 @@ export function registerSessionRoutes(
          }
        }
      }
+      // The encoder maps both '/' and '.' to '-', so a literal '.' in the
+      // original path (e.g. "/home/timkjr/.codeman") collapses into an empty
+      // split segment here. Retry this window as a dotdir/dotfile: ".<join>".
+      if (segments[idx] === '' && idx + 1 < segments.length) {
+        const dotMaxLook = Math.min(idx + 1 + 4, segments.length);
+        for (let end = dotMaxLook - 1; end >= idx + 1; end--) {
+          const dotCandidates =
+            end === idx + 1
+              ? [segments[idx + 1]]
+              : [segments.slice(idx + 1, end + 1).join('-'), segments.slice(idx + 1, end + 1).join('_')];
+          for (const child of dotCandidates) {
+            const candidate = current + '/.' + child;
+            if (await isDir(candidate)) {
+              const result = await tryDecode(end + 1, candidate);
+              if (result) return result;
+            }
+          }
+        }
+      }
      return null;
    }

@@ -2581,7 +2605,10 @@ export function registerSessionRoutes(
      for (let end = i; end < maxLook; end++) {
        const candidates: string[] = [];
        if (end === i) {
-          candidates.push(segments[i]);
+          // Same empty-segment skip as tryDecode above. This loop is shortest-match
+          // first, so without it the empty candidate matches on the very first try
+          // and sets `matched`, leaving the dotdir branch below permanently dead.
+          if (segments[i] !== '') candidates.push(segments[i]);
        } else {
          candidates.push(segments.slice(i, end + 1).join('_'));
          candidates.push(segments.slice(i, end + 1).join('-'));
@@ -2597,9 +2624,41 @@ export function registerSessionRoutes(
        }
        if (matched) break;
      }
+      if (!matched && segments[i] === '' && i + 1 < segments.length) {
+        const dotMaxLook = Math.min(i + 1 + 4, segments.length);
+        for (let end = i + 1; end < dotMaxLook; end++) {
+          const dotCandidates =
+            end === i + 1
+              ? [segments[i + 1]]
+              : [segments.slice(i + 1, end + 1).join('_'), segments.slice(i + 1, end + 1).join('-')];
+          for (const child of dotCandidates) {
+            const candidate = current + '/.' + child;
+            if (await isDir(candidate)) {
+              current = candidate;
+              i = end + 1;
+              matched = true;
+              break;
+            }
+          }
+          if (matched) break;
+        }
+      }
      if (!matched) {
-        current = current + '/' + segments[i];
-        i++;
+        if (segments[i] === '') {
+          // Nothing on disk matched (the usual reason this fallback runs at all is
+          // that the directory was deleted). An empty segment still means the
+          // encoder ate a literal '.', so guess the dotdir form rather than
+          // appending a bare '/' and emitting a "//" path.
+          if (i + 1 < segments.length) {
+            current = current + '/.' + segments[i + 1];
+            i += 2;
+          } else {
+            i++;
+          }
+        } else {
+          current = current + '/' + segments[i];
+          i++;
+        }
      }
    }
    const finalExists = await fs
@@ -374,9 +374,19 @@ export function registerSystemRoutes(
  });

  // ═══════════════════════════════════════════════════════════════
-  // CLI Integrations (OpenCode, Codex, Gemini, Antigravity)
+  // CLI Integrations (Claude, OpenCode, Codex, Gemini, Antigravity)
  // ═══════════════════════════════════════════════════════════════

+  // ========== Claude ==========
+
+  app.get('/api/claude/status', async () => {
+    const { isClaudeAvailable, findClaudeDir } = await import('../../utils/claude-cli-resolver.js');
+    return {
+      available: isClaudeAvailable(),
+      path: findClaudeDir(),
+    };
+  });
+
  // ========== OpenCode ==========

  app.get('/api/opencode/status', async () => {
@@ -16,6 +16,7 @@ import {
  MIN_TERMINAL_BUFFER_BYTES,
  MIN_TERMINAL_SCROLLBACK_LINES,
 } from '../config/terminal-history.js';
+import { MAX_EDITABLE_BYTES } from '../config/file-editing.js';

 // ========== Path Validation ==========

@@ -83,6 +84,30 @@ export const FilesystemPreviewQuerySchema = z.object({
    .optional(),
 });

+/**
+ * Body validation for `PUT /api/sessions/:id/file-content` (File Viewer edit
+ * mode). `content.max()` counts UTF-16 code units, which for UTF-8 output is
+ * always <= the byte length, so it is a coarse pre-filter that never rejects
+ * valid content; the handler enforces the exact MAX_EDITABLE_BYTES byte cap.
+ * Workspace containment and symlink resolution are enforced by the route via
+ * validateSessionFilePath after parsing.
+ */
+export const FileWriteSchema = z
+  .object({
+    path: z
+      .string()
+      .min(1)
+      .max(4096)
+      .refine((p) => !p.includes('\0') && !p.includes('\n') && !p.includes('\r'), {
+        message: 'Invalid path',
+      }),
+    content: z.string().max(MAX_EDITABLE_BYTES),
+    baseHash: z.string().regex(/^[a-f0-9]{64}$/, 'baseHash must be a sha256 hex digest'),
+    eol: z.enum(['lf', 'crlf']).optional(),
+    force: z.boolean().optional(),
+  })
+  .strict();
+
 // ========== Env Var Allowlist ==========

 /** Allowlisted env var key prefixes */
@@ -182,6 +207,7 @@ const CodexConfigSchema = z
      .regex(/^[a-zA-Z0-9_-]+$/)
      .optional(),
    dangerouslyBypassApprovals: z.boolean().optional(),
+    animations: z.boolean().optional(),
    renderMode: z
      .enum(['scrollback', 'hybrid'])
      .optional()
@@ -776,6 +802,7 @@ export const SettingsUpdateSchema = z
    allowedTools: z.string().max(2000).optional(),
    // Codex CLI settings
    codexDangerouslyBypassApprovals: z.boolean().optional(),
+    codexAnimationsEnabled: z.boolean().optional(),
    // Terminal history and retention
    terminalScrollbackLines: z
      .number()
@@ -1288,6 +1288,49 @@ export class WebServer extends EventEmitter {
    // actual on/off. We expose `__codemanGestureAvailable` so the settings UI can
    // show the toggle only when the feature is available, and inject the bundle
    // (served same-origin from /gesture/, so 'self' covers it) only when enabled.
+    // Tool availability (#200/#201): the welcome-screen run buttons, the run-mode
+    // dropdown entries and the App Settings "Codex CLI" tab are all offers that a
+    // box without the binary cannot keep — picking one spawns a session that
+    // errors out immediately. One object answers all three.
+    //
+    // INJECTED, not fetched per surface. The `/api/<cli>/status` routes exist and
+    // stay (they mirror each other and are a fine API surface), but as the source
+    // for UI gating they buy nothing: every resolver memoizes its PATH probe on
+    // the server, so a fetch is exactly as stale as an injected value, while
+    // costing a round trip each time the dropdown opens and leaving the welcome
+    // buttons to flicker in after paint. Installing a CLI later needs a server
+    // restart either way. Memoized probes also make this cheap per render.
+    //
+    // Solo popups skip it: no settings modal, no welcome screen, no run menu.
+    if (!soloSessionId) {
+      const [
+        { isClaudeAvailable },
+        { isOpenCodeAvailable },
+        { isCodexAvailable },
+        { isGeminiAvailable },
+        { isAntigravityAvailable },
+        { isCloudflaredAvailable },
+      ] = await Promise.all([
+        import('../utils/claude-cli-resolver.js'),
+        import('../utils/opencode-cli-resolver.js'),
+        import('../utils/codex-cli-resolver.js'),
+        import('../utils/gemini-cli-resolver.js'),
+        import('../utils/antigravity-cli-resolver.js'),
+        import('../utils/cloudflared-resolver.js'),
+      ]);
+      const available = {
+        claude: isClaudeAvailable(),
+        opencode: isOpenCodeAvailable(),
+        codex: isCodexAvailable(),
+        gemini: isGeminiAvailable(),
+        antigravity: isAntigravityAvailable(),
+        cloudflared: isCloudflaredAvailable(),
+      };
+      html = html.replace(
+        '</head>',
+        `<script>window.__codemanCliAvailable=${JSON.stringify(available)};</script>\n</head>`
+      );
+    }
    if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
      html = html.replace('</head>', `<script>window.__codemanGestureAvailable=true;</script>\n</head>`);
      if (settings.gestureControlEnabled === true) {
@@ -118,6 +118,8 @@ describe('Antigravity mode gates', () => {

  it('has docker/remote default commands', () => {
    expect(defaultDockerCommandForMode('antigravity')).toBe('exec agy');
-    expect(defaultRemoteCommandForMode('antigravity')).toBe('exec agy');
+    // Routed through an interactive login shell so per-user PATH entries resolve —
+    // same fix as the other remote agent CLIs (see defaultRemoteCommandForMode).
+    expect(defaultRemoteCommandForMode('antigravity')).toBe('exec "${SHELL:-/bin/sh}" -i -l -c \'agy\'');
  });
 });
@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Unit tests for the File Viewer edit-mode policy module.
+ *
+ * Pure functions only — no IO, no server.
+ * Port: N/A (no server)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  MAX_EDITABLE_BYTES,
+  applyEol,
+  detectEol,
+  isDeniedEditRelativePath,
+  isEditableFileName,
+} from '../src/config/file-editing.js';
+
+describe('file-editing policy', () => {
+  describe('isEditableFileName', () => {
+    it('allows common text extensions', () => {
+      for (const name of ['a.ts', 'b.md', 'c.json', 'd.py', 'style.css', 'notes.txt', 'x.yml', 'Q.SQL']) {
+        expect(isEditableFileName(name), name).toBe(true);
+      }
+    });
+
+    it('allows well-known basenames regardless of case', () => {
+      for (const name of ['Dockerfile', 'Makefile', 'LICENSE', '.gitignore', '.editorconfig', '.nvmrc']) {
+        expect(isEditableFileName(name), name).toBe(true);
+      }
+    });
+
+    it('rejects binary/media/document extensions', () => {
+      for (const name of ['a.png', 'b.pdf', 'c.docx', 'd.zip', 'e.woff2', 'f.mp4', 'g.exe']) {
+        expect(isEditableFileName(name), name).toBe(false);
+      }
+    });
+
+    it('rejects svg and env (deliberate v1 exclusions)', () => {
+      expect(isEditableFileName('image.svg')).toBe(false);
+      expect(isEditableFileName('config.env')).toBe(false);
+    });
+
+    it('rejects extensionless and unknown-dotfile names not on the basename list', () => {
+      expect(isEditableFileName('somebinary')).toBe(false);
+      expect(isEditableFileName('.bashrc')).toBe(false);
+      expect(isEditableFileName('archive.xyz')).toBe(false);
+    });
+  });
+
+  describe('isDeniedEditRelativePath', () => {
+    it('denies anything inside a .git directory at any depth', () => {
+      expect(isDeniedEditRelativePath('.git/config')).toBe(true);
+      expect(isDeniedEditRelativePath('.git/hooks/pre-commit')).toBe(true);
+      expect(isDeniedEditRelativePath('sub/module/.git/HEAD')).toBe(true);
+    });
+
+    it('allows non-.git paths, including names merely containing "git"', () => {
+      expect(isDeniedEditRelativePath('src/index.ts')).toBe(false);
+      expect(isDeniedEditRelativePath('.github/workflows/ci.yml')).toBe(false);
+      expect(isDeniedEditRelativePath('digits/file.md')).toBe(false);
+      expect(isDeniedEditRelativePath('.gitignore')).toBe(false);
+    });
+  });
+
+  describe('detectEol / applyEol', () => {
+    it('detects LF, CRLF, and defaults to LF for single-line text', () => {
+      expect(detectEol('a\nb\nc')).toBe('lf');
+      expect(detectEol('a\r\nb\r\nc')).toBe('crlf');
+      expect(detectEol('no newline at all')).toBe('lf');
+      expect(detectEol('')).toBe('lf');
+    });
+
+    it('picks the dominant style for mixed-EOL text', () => {
+      expect(detectEol('a\r\nb\r\nc\nd')).toBe('crlf');
+      expect(detectEol('a\nb\nc\r\nd')).toBe('lf');
+    });
+
+    it('applyEol round-trips a textarea-normalized (LF) buffer back to CRLF', () => {
+      const original = 'line1\r\nline2\r\nline3';
+      const textareaValue = original.replace(/\r\n/g, '\n');
+      expect(applyEol(textareaValue, detectEol(original))).toBe(original);
+    });
+
+    it('applyEol is idempotent and never doubles CR', () => {
+      expect(applyEol('a\r\nb', 'crlf')).toBe('a\r\nb');
+      expect(applyEol('a\r\nb', 'lf')).toBe('a\nb');
+      expect(applyEol('a\nb', 'lf')).toBe('a\nb');
+    });
+
+    it('preserves a UTF-8 BOM through the EOL rewrite', () => {
+      const withBom = 'hello\nworld';
+      expect(applyEol(withBom, 'crlf')).toBe('hello\r\nworld');
+    });
+  });
+
+  it('exposes a sane editable-bytes cap', () => {
+    expect(MAX_EDITABLE_BYTES).toBe(512 * 1024);
+  });
+});
@@ -52,6 +52,8 @@ describe('help modal shortcuts', () => {
  });

  it('documents terminal input shortcuts without advertising stale run shortcuts', () => {
+    expectShortcut(helpModal, ['Ctrl', 'C'], 'Copy Selection');
+    expectShortcut(helpModal, ['Ctrl', 'Shift', 'C'], 'Copy Selection');
    expectShortcut(helpModal, ['Ctrl', 'L'], 'Clear Terminal');
    expectShortcut(helpModal, ['Ctrl', '+'], 'Increase Font');
    expectShortcut(helpModal, ['Ctrl', '-'], 'Decrease Font');
@@ -58,4 +58,22 @@ describe('keyboard shortcuts', () => {
    expect(appSource).toContain('if (this.matchesShortcutEvent(e, shortcut))');
    expect(appSource).toContain('if (shortcut.disabled || !shortcut.action) continue;');
  });
+
+  it('keeps the interrupt when Ctrl+C copies a selection (#211)', () => {
+    // The xterm handler owns this decision, and the no-selection path must fall
+    // through with NO preventDefault so xterm still evaluates Ctrl+C into 0x03.
+    expect(terminalUiSource).toContain('this.shouldCopyTerminalSelectionFromShortcut?.(ev)');
+    expect(terminalUiSource).toMatch(
+      /const selection = this\.terminal\.hasSelection\?\.\(\) \? this\.terminal\.getSelection\(\) : '';/
+    );
+    expect(terminalUiSource).toContain('void this.copyTerminalSelection(selection);');
+    expect(appSource).toContain("id: 'copy-selection'");
+  });
+
+  it('documents the terminal copy shortcut in help and README', () => {
+    expect(helpHtml).toContain('<kbd>Ctrl</kbd>+<kbd>C</kbd>');
+    expect(helpHtml).toContain('<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd>');
+    expect(readme).toContain('`Ctrl/Cmd+C`');
+    expect(readme).toContain('`Ctrl+Shift+C`');
+  });
 });
@@ -55,10 +55,15 @@ describe('remote-hosts domain', () => {
  });

  it('returns safe mode defaults and remote display values', () => {
-    expect(defaultRemoteCommandForMode('shell')).toBe('exec bash -l');
-    expect(defaultRemoteCommandForMode('codex')).toBe('exec codex');
+    expect(defaultRemoteCommandForMode('shell')).toBe('exec "${SHELL:-/bin/sh}" -i -l');
+    // Routed through an interactive login shell so per-user PATH entries (e.g.
+    // ~/.local/bin, ~/.opencode/bin) resolve — a bare `exec codex` sees only
+    // sshd's minimal default PATH and fails with "command not found".
+    expect(defaultRemoteCommandForMode('codex')).toBe('exec "${SHELL:-/bin/sh}" -i -l -c \'codex\'');
    // Mirrors the local claude default so the remote agent runs non-interactively.
-    expect(defaultRemoteCommandForMode('claude')).toBe('exec claude --dangerously-skip-permissions');
+    expect(defaultRemoteCommandForMode('claude')).toBe(
+      'exec "${SHELL:-/bin/sh}" -i -l -c \'claude --dangerously-skip-permissions\''
+    );
    expect(remoteSshTarget({ id: 'h1', label: 'H1', host: 'box.local', username: 'aamer' })).toBe('aamer@box.local');
    expect(remoteDisplayPath({ username: 'aamer', host: 'box.local', path: '/opt/work' })).toBe(
      'aamer@box.local:/opt/work'
@@ -150,7 +150,7 @@ describe('COD-107 buildRemoteLaunchCommand — threads connection args', () => {
    const sh = (s: string) => "'" + s.replace(/'/g, "'\\''") + "'";
    const remoteName = `codeman-ssh-${SESSION_ID.slice(0, 8)}`;
    const path = sh('/home/ubuntu/work');
-    const paneCommand = `cd ${path} && exec bash -l`;
+    const paneCommand = `cd ${path} && exec "\${SHELL:-/bin/sh}" -i -l`;
    const tmuxInvocation = [
      `tmux -L codeman-remote new-session -A -s ${remoteName} -c ${path} ${sh(paneCommand)}`,
      `set -t ${remoteName} status off`,
@@ -159,6 +159,10 @@ describe('COD-107 buildRemoteLaunchCommand — threads connection args', () => {
      'set -s escape-time 0',
      // COD-106 — shared/collaborative sizing, per-session scoped (never -g).
      `set -t ${remoteName} window-size latest`,
+      // #210 — keep a CRASHED pane for diagnosis. `failed` (not `on`, which would
+      // also strand a pane after a clean `exit`), and LAST because tmux aborts the
+      // remaining commands of a `\;` chain on error and `failed` needs tmux >= 3.2.
+      `set -t ${remoteName} remain-on-exit failed`,
    ].join(' \\; ');
    // Connection args (with the default -o ConnectTimeout=10) sit after -t.
    const expected = `ssh -o BatchMode=yes -t -o ConnectTimeout=10 ${remoteSshTarget(baseRemote)} ${sh(tmuxInvocation)}`;
@@ -12,6 +12,40 @@
 */
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { WebServer } from '../src/web/server.js';
+import { isClaudeAvailable } from '../src/utils/claude-cli-resolver.js';
+import { isOpenCodeAvailable } from '../src/utils/opencode-cli-resolver.js';
+import { isCodexAvailable } from '../src/utils/codex-cli-resolver.js';
+import { isGeminiAvailable } from '../src/utils/gemini-cli-resolver.js';
+import { isAntigravityAvailable } from '../src/utils/antigravity-cli-resolver.js';
+import { isCloudflaredAvailable } from '../src/utils/cloudflared-resolver.js';
+
+// renderIndexHtml probes the real PATH for every CLI, which would make the
+// assertions below depend on whatever happens to be installed on the machine
+// running the suite. Default them all to "not installed" and opt in per test.
+vi.mock('../src/utils/claude-cli-resolver.js', () => ({
+  isClaudeAvailable: vi.fn(() => false),
+  findClaudeDir: vi.fn(() => null),
+}));
+vi.mock('../src/utils/opencode-cli-resolver.js', () => ({
+  isOpenCodeAvailable: vi.fn(() => false),
+  resolveOpenCodeDir: vi.fn(() => null),
+}));
+vi.mock('../src/utils/codex-cli-resolver.js', () => ({
+  isCodexAvailable: vi.fn(() => false),
+  resolveCodexDir: vi.fn(() => null),
+}));
+vi.mock('../src/utils/gemini-cli-resolver.js', () => ({
+  isGeminiAvailable: vi.fn(() => false),
+  resolveGeminiDir: vi.fn(() => null),
+}));
+vi.mock('../src/utils/antigravity-cli-resolver.js', () => ({
+  isAntigravityAvailable: vi.fn(() => false),
+  resolveAntigravityDir: vi.fn(() => null),
+}));
+vi.mock('../src/utils/cloudflared-resolver.js', () => ({
+  isCloudflaredAvailable: vi.fn(() => false),
+  resolveCloudflaredPath: vi.fn(() => null),
+}));

 const TEMPLATE = [
  '<head>',
@@ -86,6 +120,55 @@ describe('WebServer.renderIndexHtml', () => {
    expect(html).toContain('gesture-codeman.js');
  });

+  it('reports every tool the welcome buttons, run menu and Codex tab gate on', async () => {
+    vi.mocked(isClaudeAvailable).mockReturnValue(true);
+    vi.mocked(isOpenCodeAvailable).mockReturnValue(false);
+    vi.mocked(isCodexAvailable).mockReturnValue(true);
+    vi.mocked(isGeminiAvailable).mockReturnValue(false);
+    vi.mocked(isAntigravityAvailable).mockReturnValue(false);
+    vi.mocked(isCloudflaredAvailable).mockReturnValue(true);
+    const { server } = makeServer({});
+    const html = await render(server);
+    const flags = JSON.parse(html.match(/window\.__codemanCliAvailable=(\{.*?\});/)![1]);
+    // Every key must be PRESENT, not merely truthy where installed: the client
+    // treats a missing key as available, so a dropped key silently un-gates.
+    expect(flags).toEqual({
+      claude: true,
+      opencode: false,
+      codex: true,
+      gemini: false,
+      antigravity: false,
+      cloudflared: true,
+    });
+  });
+
+  it('still emits the object when nothing at all is installed', async () => {
+    // The all-false case is the one that matters most and the easiest to get
+    // wrong by only injecting when something resolves.
+    for (const probe of [
+      isClaudeAvailable,
+      isOpenCodeAvailable,
+      isCodexAvailable,
+      isGeminiAvailable,
+      isAntigravityAvailable,
+      isCloudflaredAvailable,
+    ]) {
+      vi.mocked(probe).mockReturnValue(false);
+    }
+    const { server } = makeServer({});
+    const html = await render(server);
+    expect(html).toContain('window.__codemanCliAvailable=');
+    const flags = JSON.parse(html.match(/window\.__codemanCliAvailable=(\{.*?\});/)![1]);
+    expect(Object.values(flags).every((v) => v === false)).toBe(true);
+  });
+
+  it('skips the probe for a solo window, which has no welcome screen or run menu', async () => {
+    vi.mocked(isCodexAvailable).mockReturnValue(true);
+    const { server } = makeServer({});
+    const html = await render(server, 'sess-123');
+    expect(html).not.toContain('__codemanCliAvailable');
+  });
+
  it('does not expose gesture at all when CODEMAN_GESTURE is unset', async () => {
    delete process.env.CODEMAN_GESTURE;
    const { server } = makeServer({ gestureControlEnabled: true });
@@ -0,0 +1,354 @@
+/**
+ * @fileoverview File Viewer edit mode — read-for-edit (`edit=1`) and
+ * `PUT /api/sessions/:id/file-content` (issue #212).
+ *
+ * Deliberately does NOT mock node:fs — every case runs against a real temp
+ * workspace so the confinement (realpath + workspace boundary), the symlink
+ * behavior, the atomic temp+rename write, and mode preservation are exercised
+ * for real, not against a mock's assumptions.
+ *
+ * Uses app.inject() — no real HTTP ports needed.
+ * Port: N/A (app.inject doesn't open ports)
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  symlinkSync,
+  chmodSync,
+  statSync,
+  realpathSync,
+  readdirSync,
+  rmSync,
+  existsSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerFileRoutes } from '../../src/web/routes/file-routes.js';
+import { MAX_EDITABLE_BYTES } from '../../src/config/file-editing.js';
+
+function sha256(data: string | Buffer): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+describe('file viewer edit mode (real fs)', () => {
+  let harness: RouteTestHarness;
+  let workDir: string;
+  let outsideDir: string;
+  const sessionId = 'test-session-1';
+
+  const putFile = (path: string, body: Record<string, unknown>) =>
+    harness.app.inject({
+      method: 'PUT',
+      url: `/api/sessions/${sessionId}/file-content`,
+      payload: { path, ...body },
+    });
+
+  const getEdit = (path: string) =>
+    harness.app.inject({
+      method: 'GET',
+      url: `/api/sessions/${sessionId}/file-content?path=${encodeURIComponent(path)}&edit=1`,
+    });
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerFileRoutes);
+    // realpath: on some hosts tmpdir() contains a symlinked component, which
+    // would make validateSessionFilePath's relative() check misfire.
+    workDir = realpathSync(mkdtempSync(join(tmpdir(), 'codeman-edit-ws-')));
+    outsideDir = realpathSync(mkdtempSync(join(tmpdir(), 'codeman-edit-out-')));
+    harness.ctx._session.workingDir = workDir;
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+    rmSync(workDir, { recursive: true, force: true });
+    rmSync(outsideDir, { recursive: true, force: true });
+  });
+
+  // ========== GET ?edit=1 ==========
+
+  describe('GET /api/sessions/:id/file-content?edit=1', () => {
+    it('returns the FULL content (never truncated) with hash and eol', async () => {
+      const content = Array.from({ length: 800 }, (_, i) => `line ${i + 1}`).join('\n');
+      writeFileSync(join(workDir, 'long.md'), content);
+
+      const res = await getEdit('long.md');
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.success).toBe(true);
+      expect(body.data.content).toBe(content);
+      expect(body.data.truncated).toBe(false);
+      expect(body.data.totalLines).toBe(800);
+      expect(body.data.editable).toBe(true);
+      expect(body.data.hash).toBe(sha256(content));
+      expect(body.data.eol).toBe('lf');
+    });
+
+    it('reports crlf for a CRLF file', async () => {
+      writeFileSync(join(workDir, 'dos.txt'), 'a\r\nb\r\nc');
+      const res = await getEdit('dos.txt');
+      expect(res.json().data.eol).toBe('crlf');
+    });
+
+    it('413s above MAX_EDITABLE_BYTES instead of truncating', async () => {
+      writeFileSync(join(workDir, 'big.log'), 'x'.repeat(MAX_EDITABLE_BYTES + 1));
+      const res = await getEdit('big.log');
+      expect(res.statusCode).toBe(413);
+      expect(res.json().success).toBe(false);
+    });
+
+    it('400s for a non-allowlisted extension', async () => {
+      writeFileSync(join(workDir, 'data.xyz'), 'text');
+      const res = await getEdit('data.xyz');
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('400s for binary content even with a text extension', async () => {
+      writeFileSync(join(workDir, 'fake.txt'), Buffer.from([0x68, 0x00, 0x69]));
+      const res = await getEdit('fake.txt');
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('plain read editable flag', () => {
+    it('advertises editable:true for an editable text file', async () => {
+      writeFileSync(join(workDir, 'notes.md'), 'hello');
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${sessionId}/file-content?path=notes.md`,
+      });
+      expect(res.json().data.editable).toBe(true);
+    });
+
+    it('advertises editable:false for a non-allowlisted extension', async () => {
+      writeFileSync(join(workDir, 'schema.xsd'), '<xml/>');
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${sessionId}/file-content?path=schema.xsd`,
+      });
+      const data = res.json().data;
+      expect(data.content).toBeDefined();
+      expect(data.editable).toBe(false);
+    });
+  });
+
+  // ========== PUT ==========
+
+  describe('PUT /api/sessions/:id/file-content', () => {
+    it('happy path: writes the bytes, returns new hash, leaves no temp files', async () => {
+      const original = 'line one\nline two\n';
+      writeFileSync(join(workDir, 'notes.md'), original);
+
+      const updated = 'line one EDITED\nline two\n';
+      const res = await putFile('notes.md', { content: updated, baseHash: sha256(original) });
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.success).toBe(true);
+      expect(body.data.hash).toBe(sha256(updated));
+      expect(body.data.eol).toBe('lf');
+      expect(body.data.size).toBe(Buffer.byteLength(updated));
+
+      expect(readFileSync(join(workDir, 'notes.md'), 'utf8')).toBe(updated);
+      const leftovers = readdirSync(workDir).filter((n) => n.includes('codeman-tmp'));
+      expect(leftovers).toEqual([]);
+    });
+
+    it('404s on ../ traversal without touching the outside file', async () => {
+      const target = join(outsideDir, 'victim.md');
+      writeFileSync(target, 'safe');
+      // Build a relative path that resolves outside the workspace.
+      const traversal = `..${target.startsWith('/') ? target : `/${target}`}`;
+      const res = await putFile(traversal, { content: 'pwned', baseHash: sha256('safe') });
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(target, 'utf8')).toBe('safe');
+    });
+
+    it('404s on an absolute path outside the workspace', async () => {
+      const target = join(outsideDir, 'victim2.md');
+      writeFileSync(target, 'safe');
+      const res = await putFile(target, { content: 'pwned', baseHash: sha256('safe') });
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(target, 'utf8')).toBe('safe');
+    });
+
+    it('404s a symlink pointing outside the workspace and never follows it', async () => {
+      const target = join(outsideDir, 'secret.md');
+      writeFileSync(target, 'outside');
+      symlinkSync(target, join(workDir, 'sneaky.md'));
+
+      const res = await putFile('sneaky.md', { content: 'pwned', baseHash: sha256('outside') });
+      expect(res.statusCode).toBe(404);
+      expect(readFileSync(target, 'utf8')).toBe('outside');
+    });
+
+    it('writes THROUGH a symlink whose target is inside the workspace', async () => {
+      writeFileSync(join(workDir, 'real.md'), 'original');
+      symlinkSync(join(workDir, 'real.md'), join(workDir, 'alias.md'));
+
+      const res = await putFile('alias.md', { content: 'via alias', baseHash: sha256('original') });
+      expect(res.statusCode).toBe(200);
+      expect(readFileSync(join(workDir, 'real.md'), 'utf8')).toBe('via alias');
+    });
+
+    it('400s a non-allowlisted extension', async () => {
+      writeFileSync(join(workDir, 'blob.xyz'), 'text');
+      const res = await putFile('blob.xyz', { content: 'nope', baseHash: sha256('text') });
+      expect(res.statusCode).toBe(400);
+      expect(readFileSync(join(workDir, 'blob.xyz'), 'utf8')).toBe('text');
+    });
+
+    it('403s inside .git even for an allowlisted-looking name', async () => {
+      mkdirSync(join(workDir, '.git'));
+      writeFileSync(join(workDir, '.git', 'config.ini'), '[core]');
+      const res = await putFile('.git/config.ini', { content: 'x', baseHash: sha256('[core]') });
+      expect(res.statusCode).toBe(403);
+    });
+
+    it('rejects a .env file (allowlist first, sensitive-path as backstop)', async () => {
+      writeFileSync(join(workDir, '.env'), 'SECRET=1');
+      const res = await putFile('.env', { content: 'SECRET=2', baseHash: sha256('SECRET=1') });
+      expect([400, 403]).toContain(res.statusCode);
+      expect(readFileSync(join(workDir, '.env'), 'utf8')).toBe('SECRET=1');
+    });
+
+    it('400s when the current file contains a NUL byte', async () => {
+      writeFileSync(join(workDir, 'weird.txt'), Buffer.from([0x61, 0x00, 0x62]));
+      const res = await putFile('weird.txt', { content: 'ab', baseHash: sha256(Buffer.from([0x61, 0x00, 0x62])) });
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('400s when the current file is not valid UTF-8 (latin-1)', async () => {
+      const latin1 = Buffer.from('caf\xe9 au lait', 'latin1');
+      writeFileSync(join(workDir, 'legacy.txt'), latin1);
+      const res = await putFile('legacy.txt', { content: 'cafe au lait', baseHash: sha256(latin1) });
+      expect(res.statusCode).toBe(400);
+      expect(readFileSync(join(workDir, 'legacy.txt'))).toEqual(latin1);
+    });
+
+    it('409s on a stale baseHash and succeeds with force:true', async () => {
+      writeFileSync(join(workDir, 'contested.md'), 'agent version');
+
+      const res = await putFile('contested.md', { content: 'my version', baseHash: sha256('older version') });
+      expect(res.statusCode).toBe(409);
+      expect(res.json().errorCode).toBe('CONFLICT');
+      expect(readFileSync(join(workDir, 'contested.md'), 'utf8')).toBe('agent version');
+
+      const forced = await putFile('contested.md', {
+        content: 'my version',
+        baseHash: sha256('older version'),
+        force: true,
+      });
+      expect(forced.statusCode).toBe(200);
+      expect(readFileSync(join(workDir, 'contested.md'), 'utf8')).toBe('my version');
+    });
+
+    it('rejects oversized ASCII content at the schema pre-filter (400)', async () => {
+      writeFileSync(join(workDir, 'small.md'), 'ok');
+      const res = await putFile('small.md', {
+        content: 'x'.repeat(MAX_EDITABLE_BYTES + 1),
+        baseHash: sha256('ok'),
+      });
+      expect(res.statusCode).toBe(400);
+      expect(readFileSync(join(workDir, 'small.md'), 'utf8')).toBe('ok');
+    });
+
+    it('413s multibyte content that passes the code-unit pre-filter but exceeds the byte cap', async () => {
+      writeFileSync(join(workDir, 'small.md'), 'ok');
+      // '€' is 1 UTF-16 code unit but 3 UTF-8 bytes: 200k units (< 512Ki cap)
+      // becomes ~586KB on disk, so only the handler's byteLength check catches it.
+      const res = await putFile('small.md', {
+        content: '€'.repeat(200_000),
+        baseHash: sha256('ok'),
+      });
+      expect(res.statusCode).toBe(413);
+      expect(readFileSync(join(workDir, 'small.md'), 'utf8')).toBe('ok');
+    });
+
+    it('404s a missing file and creates nothing (edit-in-place only)', async () => {
+      const res = await putFile('brand-new.md', { content: 'hello', baseHash: sha256('hello') });
+      expect(res.statusCode).toBe(404);
+      expect(existsSync(join(workDir, 'brand-new.md'))).toBe(false);
+    });
+
+    it('400s a malformed baseHash at the schema layer', async () => {
+      writeFileSync(join(workDir, 'a.md'), 'x');
+      const res = await putFile('a.md', { content: 'y', baseHash: 'not-a-hash' });
+      expect(res.statusCode).toBe(400);
+      expect(res.json().errorCode).toBe('INVALID_INPUT');
+    });
+
+    it('preserves CRLF line endings across a textarea-normalized save', async () => {
+      const original = 'first\r\nsecond\r\nthird';
+      writeFileSync(join(workDir, 'dos.txt'), original);
+
+      // Client sends LF-normalized content + the eol it was told at load time.
+      const res = await putFile('dos.txt', {
+        content: 'first\nsecond EDITED\nthird',
+        baseHash: sha256(original),
+        eol: 'crlf',
+      });
+      expect(res.statusCode).toBe(200);
+      expect(readFileSync(join(workDir, 'dos.txt'), 'utf8')).toBe('first\r\nsecond EDITED\r\nthird');
+    });
+
+    it('re-applies the original EOL even when the client omits eol', async () => {
+      const original = 'a\r\nb';
+      writeFileSync(join(workDir, 'implicit.txt'), original);
+      const res = await putFile('implicit.txt', { content: 'a\nb\nc', baseHash: sha256(original) });
+      expect(res.statusCode).toBe(200);
+      expect(readFileSync(join(workDir, 'implicit.txt'), 'utf8')).toBe('a\r\nb\r\nc');
+    });
+
+    it('preserves the file mode across the temp+rename', async () => {
+      const p = join(workDir, 'script.sh');
+      writeFileSync(p, '#!/bin/sh\necho hi\n');
+      chmodSync(p, 0o750);
+
+      const res = await putFile('script.sh', {
+        content: '#!/bin/sh\necho bye\n',
+        baseHash: sha256('#!/bin/sh\necho hi\n'),
+      });
+      expect(res.statusCode).toBe(200);
+      expect(statSync(p).mode & 0o777).toBe(0o750);
+    });
+
+    it('rejects unknown body keys (.strict() schema)', async () => {
+      writeFileSync(join(workDir, 'a.md'), 'x');
+      const res = await putFile('a.md', { content: 'y', baseHash: sha256('x'), evil: true });
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  // ========== multi-user scoping ==========
+
+  describe('multi-user ownership', () => {
+    it("404s a non-admin writing to a session they don't own", async () => {
+      const prev = process.env.CODEMAN_MULTIUSER;
+      process.env.CODEMAN_MULTIUSER = '1';
+      try {
+        const scoped = await createRouteTestHarness(registerFileRoutes, {
+          authUser: { username: 'mallory', role: 'user' },
+        });
+        scoped.ctx._session.workingDir = workDir;
+        writeFileSync(join(workDir, 'owned.md'), 'admin file');
+
+        const res = await scoped.app.inject({
+          method: 'PUT',
+          url: `/api/sessions/${sessionId}/file-content`,
+          payload: { path: 'owned.md', content: 'stolen', baseHash: sha256('admin file') },
+        });
+        expect(res.statusCode).toBe(404);
+        expect(readFileSync(join(workDir, 'owned.md'), 'utf8')).toBe('admin file');
+        await scoped.app.close();
+      } finally {
+        if (prev === undefined) delete process.env.CODEMAN_MULTIUSER;
+        else process.env.CODEMAN_MULTIUSER = prev;
+      }
+    });
+  });
+});
@@ -18,7 +18,7 @@ import Fastify, { type FastifyInstance } from 'fastify';
 import fastifyCookie from '@fastify/cookie';
 import fastifyMultipart from '@fastify/multipart';
 import { join } from 'node:path';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
 import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
@@ -1288,6 +1288,68 @@ describe('session-routes', () => {
      const body = JSON.parse(res.body);
      expect(body.data.sessions.length).toBeLessThanOrEqual(50);
    });
+
+    it('decodes a dotdir working directory (e.g. ~/.codeman) instead of falling back to $HOME', async () => {
+      // Claude Code's project-key encoding maps both '/' and '.' to '-', so
+      // "/home/x/.dotcase" and "/home/x/dotcase" collapse to the same-looking
+      // dash run except for a doubled dash. decodeProjectKey() must still
+      // recover the real (dotdir) path rather than silently falling back to
+      // bare $HOME (COD bug: 2026-08-01, ~/.codeman resumed sessions got
+      // workingDir "/home/timkjr" instead of "/home/timkjr/.codeman").
+      const home = process.env.HOME as string;
+      const realDir = join(home, '.dotcase');
+      await mkdir(realDir, { recursive: true });
+
+      const projectKey = realDir.replace(/\//g, '-').replace(/\./g, '-');
+      const projDir = join(home, '.claude', 'projects', projectKey);
+      await mkdir(projDir, { recursive: true });
+
+      const sessionId = '12345678-1234-1234-1234-123456789012';
+      const transcriptLine = JSON.stringify({ type: 'user', message: { role: 'user', content: 'hello world' } }) + '\n';
+      // scanProjectDir skips files under 4000 bytes.
+      const padding = '#'.repeat(4200 - transcriptLine.length);
+      await writeFile(join(projDir, `${sessionId}.jsonl`), transcriptLine + padding);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/history/sessions?projectKey=${projectKey}`,
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      const row = body.data.sessions.find((s: { sessionId: string }) => s.sessionId === sessionId);
+      expect(row).toBeDefined();
+      expect(row.workingDir).toBe(realDir);
+      expect(row.workingDir).not.toBe(home);
+    });
+
+    it('prefers the dotdir over a same-named non-dot sibling, and never emits a "//" path', async () => {
+      // A doubled dash also lets the decoder read the empty split segment as a
+      // directory NAME. `isDir(current + '/' + '')` stats `current + '/'`, which
+      // always succeeds, so `~/.sib` + `~/sib` both existing used to resolve to
+      // "/home/x//sib": the wrong directory, spelled with a double slash that
+      // then fails every string comparison against session.workingDir. The empty
+      // candidate is never a real path component, so it is skipped outright,
+      // which is also what lets the dotdir branch below it run at all.
+      const home = process.env.HOME as string;
+      const dotDir = join(home, '.sib');
+      await mkdir(dotDir, { recursive: true });
+      await mkdir(join(home, 'sib'), { recursive: true });
+
+      const projectKey = dotDir.replace(/\//g, '-').replace(/\./g, '-');
+      const projDir = join(home, '.claude', 'projects', projectKey);
+      await mkdir(projDir, { recursive: true });
+
+      const sessionId = '22222222-2222-2222-2222-222222222222';
+      const line = JSON.stringify({ type: 'user', message: { role: 'user', content: 'hello world' } }) + '\n';
+      await writeFile(join(projDir, `${sessionId}.jsonl`), line + '#'.repeat(4200 - line.length));
+
+      const res = await harness.app.inject({ method: 'GET', url: `/api/history/sessions?projectKey=${projectKey}` });
+      expect(res.statusCode).toBe(200);
+      const row = JSON.parse(res.body).data.sessions.find((s: { sessionId: string }) => s.sessionId === sessionId);
+      expect(row).toBeDefined();
+      expect(row.workingDir).toBe(dotDir);
+      expect(row.workingDir).not.toContain('//');
+    });
  });

  // ========== POST /api/sessions (with resumeSessionId) ==========
@@ -84,6 +84,101 @@ describe('run mode UI', () => {
 });

 describe('Run launch synchronization', () => {
+  it('keeps launch progress out of an active session terminal', () => {
+    const CodemanApp = function CodemanApp(this: any) {};
+    const context = vm.createContext({
+      CodemanApp,
+      localStorage: { getItem: () => null, setItem: () => {} },
+      document: { getElementById: () => null },
+      console,
+    });
+    const sessionUi = readFileSync(resolve(import.meta.dirname, '../src/web/public/session-ui.js'), 'utf8');
+    vm.runInContext(sessionUi, context, { filename: 'session-ui.js' });
+
+    const app = new (CodemanApp as any)();
+    app.activeSessionId = 'existing-session';
+    app.terminal = {
+      clear: vi.fn(),
+      writeln: vi.fn(),
+    };
+    app.showToast = vi.fn();
+
+    const ownsTerminal = app._beginSessionLaunchStatus('Starting Codex session', '1;32');
+    app._appendSessionLaunchStatus(ownsTerminal, 'Creating session');
+    app._reportSessionLaunchError(ownsTerminal, 'Launch failed');
+
+    expect(ownsTerminal).toBe(false);
+    expect(app.terminal.clear).not.toHaveBeenCalled();
+    expect(app.terminal.writeln).not.toHaveBeenCalled();
+    expect(app.showToast).toHaveBeenNthCalledWith(1, 'Starting Codex session', 'info');
+    expect(app.showToast).toHaveBeenNthCalledWith(2, 'Launch failed', 'error');
+  });
+
+  it('still renders launch progress in the terminal on the session-less home screen', () => {
+    const CodemanApp = function CodemanApp(this: any) {};
+    const context = vm.createContext({
+      CodemanApp,
+      localStorage: { getItem: () => null, setItem: () => {} },
+      document: { getElementById: () => null },
+      console,
+    });
+    const sessionUi = readFileSync(resolve(import.meta.dirname, '../src/web/public/session-ui.js'), 'utf8');
+    vm.runInContext(sessionUi, context, { filename: 'session-ui.js' });
+
+    const app = new (CodemanApp as any)();
+    app.activeSessionId = null; // home screen: nothing else owns the terminal
+    app.terminal = { clear: vi.fn(), writeln: vi.fn() };
+    app.showToast = vi.fn();
+
+    const ownsTerminal = app._beginSessionLaunchStatus('Starting Codex session', '1;32');
+    app._appendSessionLaunchStatus(ownsTerminal, 'Creating session');
+    app._reportSessionLaunchError(ownsTerminal, 'Launch failed');
+
+    expect(ownsTerminal).toBe(true);
+    expect(app.terminal.clear).toHaveBeenCalledTimes(1);
+    expect(app.terminal.writeln.mock.calls.map((c: string[]) => c[0]).join('\n')).toContain('Starting Codex session');
+    expect(app.terminal.writeln.mock.calls.map((c: string[]) => c[0]).join('\n')).toContain('Creating session');
+    expect(app.terminal.writeln.mock.calls.map((c: string[]) => c[0]).join('\n')).toContain('Error: Launch failed');
+    expect(app.showToast).not.toHaveBeenCalled();
+  });
+
+  /**
+   * Static guard over session-ui.js itself. The helpers above can be perfectly
+   * correct while a run*() entry point still writes to the shared xterm
+   * directly, which is the actual bug: a launch started while another session
+   * is active wipes that session's terminal, and _cleanupPreviousSession()
+   * then serializes the wiped view into its restore snapshot. Asserting on the
+   * helpers alone cannot see that, so pin the call sites here. This also
+   * covers run modes added later, which is how runAntigravity was caught.
+   */
+  it('routes every run mode through the ownership helpers, never the terminal directly', () => {
+    const src = readFileSync(resolve(import.meta.dirname, '../src/web/public/session-ui.js'), 'utf8');
+
+    // Methods live in one Object.assign(prototype, {...}) block at a fixed
+    // 2-space indent, so `\n  },` reliably closes the one we are inside.
+    const bodies = new Map<string, string>();
+    const header = /^ {2}async (run[A-Za-z]*)\(\) \{$/gm;
+    for (let m = header.exec(src); m; m = header.exec(src)) {
+      const start = m.index + m[0].length;
+      const end = src.indexOf('\n  },', start);
+      expect(end, `could not find the end of ${m[1]}()`).toBeGreaterThan(start);
+      bodies.set(m[1], src.slice(start, end));
+    }
+
+    // Fail loudly if the scan matched nothing: a silently empty scan would make
+    // every assertion below vacuously true.
+    expect([...bodies.keys()]).toEqual(
+      expect.arrayContaining(['runClaude', 'runShell', 'runOpenCode', 'runCodex', 'runGemini', 'runAntigravity'])
+    );
+
+    for (const [name, body] of bodies) {
+      expect(body, `${name}() must not clear a terminal it may not own`).not.toContain('this.terminal.clear(');
+      expect(body, `${name}() must not write launch status straight to the terminal`).not.toContain(
+        'this.terminal.writeln('
+      );
+    }
+  });
+
  it('coalesces overlapping Run activations and disables the button while the request is active', async () => {
    const runBtn = {
      disabled: false,
@@ -188,14 +283,169 @@ describe('Codex quick start settings', () => {
      /<div class="modal-tab-content hidden" id="settings-claude">([\s\S]*?)<!-- Codex CLI Tab -->/
    );
    expect(claudeTab?.[1]).not.toContain('appSettingsCodexDangerouslyBypassApprovals');
+    expect(claudeTab?.[1]).not.toContain('appSettingsCodexAnimations');

    const codexTab = html.match(
      /<div class="modal-tab-content hidden" id="settings-codex">([\s\S]*?)<\/div>\s*<!-- Models Tab -->/
    );
    expect(codexTab?.[1]).toContain('appSettingsCodexDangerouslyBypassApprovals');
+    expect(codexTab?.[1]).toContain('appSettingsCodexAnimations');
    expect(codexTab?.[1]).not.toContain('appSettingsCodexRenderMode');
  });

+  describe('Codex CLI tab visibility', () => {
+    // Both settings on the tab are handed to `codex` at launch, so on an instance
+    // where the binary does not resolve the tab is a promise nothing can keep.
+    // renderIndexHtml injects window.__codemanCliAvailable; this pins the client
+    // half. Coupled test: it drives the REAL settings-ui.js against a stub button,
+    // so deleting the call in openAppSettings() is what it is meant to catch.
+    function loadSettingsUi(codexAvailable: boolean | undefined) {
+      const codexTabBtn = { dataset: { tab: 'settings-codex' }, style: { display: 'PRISTINE' } };
+      const CodemanApp = function CodemanApp(this: any) {};
+      const context: any = vm.createContext({
+        CodemanApp,
+        MobileDetection: { getDeviceType: () => 'desktop', isTouchDevice: () => false, isHandheldDevice: () => false },
+        localStorage: { getItem: () => null, setItem: () => {} },
+        document: {
+          getElementById: () => null,
+          querySelector: (sel: string) => (sel.includes('[data-tab="settings-codex"]') ? codexTabBtn : null),
+        },
+        console,
+      });
+      context.window = context;
+      if (codexAvailable !== undefined) context.__codemanCliAvailable = { codex: codexAvailable };
+      const settingsUi = readFileSync(resolve(import.meta.dirname, '../src/web/public/settings-ui.js'), 'utf8');
+      vm.runInContext(settingsUi, context, { filename: 'settings-ui.js' });
+      return { app: new (CodemanApp as any)(), codexTabBtn };
+    }
+
+    it('hides the Codex tab when the codex binary is not available', () => {
+      const { app, codexTabBtn } = loadSettingsUi(false);
+      app._applyCodexSettingsVisibility();
+      expect(codexTabBtn.style.display).toBe('none');
+    });
+
+    it('hides the Codex tab when the availability flag was never injected', () => {
+      const { app, codexTabBtn } = loadSettingsUi(undefined);
+      app._applyCodexSettingsVisibility();
+      expect(codexTabBtn.style.display).toBe('none');
+    });
+
+    it('shows the Codex tab when codex is available', () => {
+      const { app, codexTabBtn } = loadSettingsUi(true);
+      app._applyCodexSettingsVisibility();
+      expect(codexTabBtn.style.display).toBe('');
+    });
+
+    it('applies the gating from openAppSettings, not just in isolation', () => {
+      const src = readFileSync(resolve(import.meta.dirname, '../src/web/public/settings-ui.js'), 'utf8');
+      const open = src.slice(src.indexOf('\n  openAppSettings() {'));
+      const body = open.slice(0, open.indexOf('\n  },'));
+      expect(body).toContain('_applyCodexSettingsVisibility()');
+    });
+  });
+
+  describe('CLI availability gating (#200/#201)', () => {
+    // Drives the REAL settings-ui.js + session-ui.js against stub elements, so an
+    // added run mode that nobody wires up here is what these are meant to catch.
+    function loadUi(flags: Record<string, boolean> | undefined) {
+      const CodemanApp = function CodemanApp(this: any) {};
+      const welcomeBtns: Record<string, { style: { display: string } }> = {};
+      for (const id of ['welcomeClaudeBtn', 'welcomeOpencodeBtn', 'welcomeGeminiBtn', 'welcomeTunnelBtn']) {
+        welcomeBtns[id] = { style: { display: 'PRISTINE' } };
+      }
+      const modeBtns: Record<string, { style: { display: string } }> = {};
+      for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'shell']) {
+        modeBtns[mode] = { style: { display: 'PRISTINE' } };
+      }
+      const menu = {
+        querySelector: (sel: string) => {
+          const m = sel.match(/data-mode="([^"]+)"/);
+          return m ? (modeBtns[m[1]] ?? null) : null;
+        },
+      };
+      const context: any = vm.createContext({
+        CodemanApp,
+        MobileDetection: { getDeviceType: () => 'desktop', isTouchDevice: () => false, isHandheldDevice: () => false },
+        localStorage: { getItem: () => null, setItem: () => {} },
+        document: { getElementById: (id: string) => welcomeBtns[id] ?? null, querySelector: () => null },
+        console,
+      });
+      context.window = context;
+      if (flags !== undefined) context.__codemanCliAvailable = flags;
+      for (const file of ['settings-ui.js', 'session-ui.js']) {
+        const src = readFileSync(resolve(import.meta.dirname, `../src/web/public/${file}`), 'utf8');
+        vm.runInContext(src, context, { filename: file });
+      }
+      return { app: new (CodemanApp as any)(), welcomeBtns, modeBtns, menu };
+    }
+
+    const ALL_OFF = {
+      claude: false,
+      opencode: false,
+      codex: false,
+      gemini: false,
+      antigravity: false,
+      cloudflared: false,
+    };
+
+    it('hides each welcome button whose tool is missing, including the tunnel', () => {
+      const { app, welcomeBtns } = loadUi({ ...ALL_OFF, claude: true });
+      app.applyWelcomeCliVisibility();
+      expect(welcomeBtns.welcomeClaudeBtn.style.display).toBe('flex');
+      expect(welcomeBtns.welcomeOpencodeBtn.style.display).toBe('none');
+      expect(welcomeBtns.welcomeGeminiBtn.style.display).toBe('none');
+      // #200 originally DELETED the tunnel button and its QR outright; it is gated
+      // on cloudflared instead, so a box that has cloudflared keeps the feature.
+      expect(welcomeBtns.welcomeTunnelBtn.style.display).toBe('none');
+
+      const withTunnel = loadUi({ ...ALL_OFF, cloudflared: true });
+      withTunnel.app.applyWelcomeCliVisibility();
+      expect(withTunnel.welcomeBtns.welcomeTunnelBtn.style.display).toBe('flex');
+    });
+
+    it('gates every run mode in the dropdown, antigravity included, and never shell', () => {
+      const { app, modeBtns, menu } = loadUi({ ...ALL_OFF, claude: true, antigravity: true });
+      app._refreshRunModeAvailability(menu);
+      expect(modeBtns.claude.style.display).toBe('flex');
+      expect(modeBtns.antigravity.style.display).toBe('flex');
+      expect(modeBtns.opencode.style.display).toBe('none');
+      expect(modeBtns.codex.style.display).toBe('none');
+      expect(modeBtns.gemini.style.display).toBe('none');
+      // Shell needs no external CLI, and leaving it alone is what guarantees the
+      // menu is never empty on a box with nothing installed.
+      expect(modeBtns.shell.style.display).toBe('PRISTINE');
+    });
+
+    it('gates every mode the run-mode menu actually offers', () => {
+      // Catches a sixth run mode being added to index.html without being gated,
+      // which is exactly how antigravity slipped past #201.
+      const html = readFileSync(resolve(import.meta.dirname, '../src/web/public/index.html'), 'utf8');
+      const menuHtml = html.slice(html.indexOf('id="runModeMenu"'));
+      const offered = [...menuHtml.slice(0, menuHtml.indexOf('</div>')).matchAll(/data-mode="([^"]+)"/g)].map(
+        (m) => m[1]
+      );
+      expect(offered).toContain('antigravity');
+      const src = readFileSync(resolve(import.meta.dirname, '../src/web/public/session-ui.js'), 'utf8');
+      // Anchor on the DEFINITION, not the earlier call site in toggleRunModeMenu.
+      const fn = src.slice(src.indexOf('_refreshRunModeAvailability(menu) {'));
+      const gated = fn.slice(0, fn.indexOf('\n  },'));
+      for (const mode of offered.filter((m) => m !== 'shell')) {
+        expect(gated).toContain(`'${mode}'`);
+      }
+    });
+
+    it('shows everything when the flags were never injected', () => {
+      // A cached page from a build without the injection, or a solo popup. Hiding
+      // every run button on a doubt would leave a working install nothing to click.
+      const { app, welcomeBtns, modeBtns, menu } = loadUi(undefined);
+      app.applyWelcomeCliVisibility();
+      app._refreshRunModeAvailability(menu);
+      expect(welcomeBtns.welcomeClaudeBtn.style.display).toBe('flex');
+      expect(modeBtns.gemini.style.display).toBe('flex');
+    });
+  });
+
  it('passes global Codex settings into quick-start config for new sessions', async () => {
    const elements: Record<string, any> = {
      quickStartCase: { value: 'codex-case' },
@@ -232,6 +482,7 @@ describe('Codex quick start settings', () => {
    app.terminal = { clear: () => {}, writeln: () => {}, focus: () => {} };
    app.loadAppSettingsFromStorage = () => ({
      codexDangerouslyBypassApprovals: true,
+      codexAnimationsEnabled: false,
    });
    app.getCaseSettings = () => ({});
    app.buildEnvOverrides = () => ({});
@@ -250,7 +501,7 @@ describe('Codex quick start settings', () => {
      mode: 'codex',
      // tabs follow the w<n>-<case> naming convention (quick-start would otherwise auto-name codeman-<id>)
      sessionName: 'w1-codex-case',
-      codexConfig: { dangerouslyBypassApprovals: true, renderMode: 'hybrid' },
+      codexConfig: { dangerouslyBypassApprovals: true, animations: false, renderMode: 'hybrid' },
    });
    expect(selected).toEqual(['sess-1']);
  });
@@ -96,8 +96,16 @@ describe('WebServer index.html <title> templating (#82)', () => {

  it('only substitutes the <title> tag — the rest of the template is identical (modulo asset cache-busting)', async () => {
    // renderIndexHtml also appends ?v=<mtime> cache-bust params to same-origin
-    // .js/.css refs; strip them so the title remains the only other change.
-    const html = (await render('laptop')).replace(/(\.(?:js|css))\?v=[^"]*/g, '$1');
+    // .js/.css refs, and injects the CLI-availability flags before </head>; strip
+    // both so the title remains the only other change.
+    //
+    // The flag strip is what keeps this test environment-independent. It used to
+    // pass here by luck: the availability script was injected only where a CLI
+    // resolved, so the assertion held on a machine with none installed and would
+    // have failed on a developer's box that had them.
+    const html = (await render('laptop'))
+      .replace(/(\.(?:js|css))\?v=[^"]*/g, '$1')
+      .replace(/<script>window\.__codemanCliAvailable=\{.*?\};<\/script>\n/, '');
    const beforeTitle = rawTemplate.split('<title>Codeman</title>')[0];
    const afterTitle = rawTemplate.split('<title>Codeman</title>')[1];
    expect(html.startsWith(beforeTitle)).toBe(true);
@@ -17,7 +17,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { execFileSync } from 'node:child_process';
 import { buildSpawnCommand } from '../src/tmux-manager.js';
-import { resolveLocalShell } from '../src/utils/shell-resolver.js';
+import { loginShellArgs, resolveLocalShell } from '../src/utils/shell-resolver.js';

 describe('resolveLocalShell', () => {
  const originalShell = process.env.SHELL;
@@ -70,6 +70,40 @@ describe('resolveLocalShell', () => {
  });
 });

+describe('loginShellArgs (#209 login flags, allowlisted)', () => {
+  it('asks for a login shell on the POSIX-family shells that accept the flags', () => {
+    for (const shell of ['/bin/sh', '/bin/bash', '/bin/dash', '/usr/bin/zsh', '/usr/local/bin/fish', '/bin/ksh']) {
+      expect(loginShellArgs(shell)).toBe(' -i -l');
+    }
+  });
+
+  it('adds nothing for shells that take neither flag, so the pane cannot die on arrival', () => {
+    // The shell path can come from the passwd entry, which is user data and can
+    // name anything. A shell that rejects an unknown flag exits immediately —
+    // indistinguishable from the #208 dead-pane-on-arrival this module prevents.
+    // csh/tcsh are here too: tcsh honors -l only when it is the ONLY flag.
+    for (const shell of ['/usr/bin/nu', '/usr/bin/elvish', '/usr/bin/xonsh', '/bin/tcsh', '/bin/csh']) {
+      expect(loginShellArgs(shell)).toBe('');
+    }
+  });
+
+  it('really launches for every allowlisted shell present on this machine', () => {
+    // The whole point of the allowlist is that the flags are ACCEPTED, so prove it
+    // against the real binaries rather than trusting the set.
+    for (const shell of ['/bin/sh', '/bin/bash', '/bin/dash', '/usr/bin/zsh', '/bin/ksh']) {
+      let exists = true;
+      try {
+        execFileSync('/bin/sh', ['-c', `test -x ${shell}`]);
+      } catch {
+        exists = false;
+      }
+      if (!exists) continue;
+      const out = execFileSync('/bin/sh', ['-c', `${shell} -i -l -c 'echo ok' 2>/dev/null`], { encoding: 'utf8' });
+      expect(out).toContain('ok');
+    }
+  });
+});
+
 describe('shell-mode spawn command (issue #208)', () => {
  const originalShell = process.env.SHELL;

@@ -88,6 +122,16 @@ describe('shell-mode spawn command (issue #208)', () => {
    expect(cmd.trim()).not.toBe('');
  });

+  it('launches a LOGIN shell, matching what tmux does for a pane with no default-command', () => {
+    // A tmux pane already hands the shell a tty, so it is interactive either way
+    // (`$-` contains `i` for a bare /bin/bash in a pane, which is why ~/.bashrc has
+    // always been sourced). `-l` is the flag that changes anything: it is what
+    // picks up /etc/profile and /etc/profile.d/*, which a systemd --user service
+    // never sourced, so its minimal PATH is what every pane used to inherit.
+    const cmd = buildSpawnCommand({ mode: 'shell', sessionId: 'abc123de-0000-0000-0000-000000000000' });
+    expect(cmd.trim().endsWith('-i -l')).toBe(true);
+  });
+
  it('produces a launch command that parses after the outer sh -c expansion layer', () => {
    const cmd = buildSpawnCommand({ mode: 'shell', sessionId: 'abc123de-0000-0000-0000-000000000000' });
    // Mirrors tmux-manager: `… bash -c ${JSON.stringify(launchCmd)}` handed to `sh -c`.
@@ -0,0 +1,147 @@
+/**
+ * Smart-copy chord gate (#211).
+ *
+ * `Ctrl+C` has to keep meaning "interrupt" whenever nothing is selected, so the
+ * decision is split in two: `shouldCopyTerminalSelectionFromShortcut()` only
+ * answers "did this chord ask to copy", and the caller in the xterm custom key
+ * handler decides what to do when there is no selection. These tests pin the
+ * gate itself (registry-aware, keydown-only) plus the static invariants that
+ * keep the generic capture loop from ever swallowing the interrupt.
+ *
+ * Strategy: run terminal-ui.js in a vm with a stub CodemanApp, the same harness
+ * shape test/command-palette-ui.test.ts uses for panels-ui.js. No DOM, no xterm.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it } from 'vitest';
+
+const APP_SOURCE = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+
+type Shortcut = {
+  id: string;
+  disabled?: boolean;
+  bindings?: Array<{ modifiers?: string[]; key?: string; code?: string }>;
+};
+
+function loadTerminalHarness(registry?: Shortcut[]) {
+  const CodemanApp = function CodemanApp(this: unknown) {};
+  const context = vm.createContext({
+    CodemanApp,
+    window: {},
+    document: { getElementById: () => null, querySelector: () => null },
+    console,
+    MobileDetection: { isTouchDevice: () => false, getDeviceType: () => 'desktop' },
+    Object,
+  });
+  const terminalUi = readFileSync(resolve(import.meta.dirname, '../src/web/public/terminal-ui.js'), 'utf8');
+  vm.runInContext(terminalUi, context, { filename: 'terminal-ui.js' });
+
+  const app = new (CodemanApp as unknown as new () => Record<string, any>)();
+  if (registry) {
+    app.getShortcutRegistry = () => registry;
+    // Real implementation, copied by reference from app.js semantics: ctrl/meta are
+    // interchangeable, every other modifier must be declared by the binding.
+    app.matchesShortcutEvent = (e: any, shortcut: Shortcut) => {
+      if (!shortcut || !Array.isArray(shortcut.bindings)) return false;
+      return shortcut.bindings.some((binding) => {
+        const mods = binding.modifiers || [];
+        const wantsPrimary = mods.includes('ctrl') || mods.includes('meta');
+        if (wantsPrimary !== !!(e.ctrlKey || e.metaKey)) return false;
+        if (mods.includes('shift') !== !!e.shiftKey) return false;
+        if (mods.includes('alt') !== !!e.altKey) return false;
+        if (binding.code && e.code === binding.code) return true;
+        if (binding.key && typeof e.key === 'string' && e.key.toLowerCase() === binding.key.toLowerCase()) return true;
+        return false;
+      });
+    };
+  }
+  return app;
+}
+
+const DEFAULT_REGISTRY: Shortcut[] = [
+  {
+    id: 'copy-selection',
+    bindings: [
+      { modifiers: ['ctrl'], key: 'c' },
+      { modifiers: ['ctrl', 'shift'], key: 'C' },
+    ],
+  },
+];
+
+function keydown(over: Record<string, unknown> = {}) {
+  return {
+    type: 'keydown',
+    key: 'c',
+    code: 'KeyC',
+    ctrlKey: true,
+    shiftKey: false,
+    altKey: false,
+    metaKey: false,
+    ...over,
+  };
+}
+
+describe('terminal smart-copy gate', () => {
+  it('matches the default Ctrl+C and Ctrl+Shift+C chords', () => {
+    const app = loadTerminalHarness(DEFAULT_REGISTRY);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown())).toBe(true);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ key: 'C', shiftKey: true }))).toBe(true);
+    // Cmd+C on macOS: the registry treats ctrl/meta as interchangeable.
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ ctrlKey: false, metaKey: true }))).toBe(true);
+  });
+
+  it('ignores plain typing and unrelated chords', () => {
+    const app = loadTerminalHarness(DEFAULT_REGISTRY);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ ctrlKey: false }))).toBe(false);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ key: 'k', code: 'KeyK' }))).toBe(false);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ key: 'v', code: 'KeyV' }))).toBe(false);
+  });
+
+  it('only decides on keydown (the handler also runs for keypress and keyup)', () => {
+    const app = loadTerminalHarness(DEFAULT_REGISTRY);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ type: 'keypress' }))).toBe(false);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ type: 'keyup' }))).toBe(false);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(null)).toBe(false);
+  });
+
+  it('honors a disabled shortcut so Ctrl+C goes back to being the interrupt', () => {
+    const app = loadTerminalHarness([{ ...DEFAULT_REGISTRY[0], disabled: true }]);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown())).toBe(false);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ key: 'C', shiftKey: true }))).toBe(false);
+  });
+
+  it('honors a rebound chord and stops claiming the old one', () => {
+    const app = loadTerminalHarness([{ id: 'copy-selection', bindings: [{ modifiers: ['alt'], key: 'y' }] }]);
+    expect(
+      app.shouldCopyTerminalSelectionFromShortcut(keydown({ ctrlKey: false, altKey: true, key: 'y', code: 'KeyY' }))
+    ).toBe(true);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown())).toBe(false);
+  });
+
+  it('falls back to the default chord when no registry is available', () => {
+    const app = loadTerminalHarness(); // no getShortcutRegistry / matchesShortcutEvent
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown())).toBe(true);
+    expect(app.shouldCopyTerminalSelectionFromShortcut(keydown({ key: 'x', code: 'KeyX' }))).toBe(false);
+  });
+});
+
+describe('smart-copy wiring invariants', () => {
+  it('registers copy-selection in the shortcut registry', () => {
+    expect(APP_SOURCE).toContain("id: 'copy-selection'");
+    expect(APP_SOURCE).toContain("action: 'copyTerminalSelection'");
+  });
+
+  it('keeps copyTerminalSelection OUT of SHORTCUT_ACTIONS', () => {
+    // The generic capture loop preventDefaults on every match it dispatches. If
+    // the copy action were reachable from there, Ctrl+C would be swallowed with
+    // no selection and the user would lose the interrupt key.
+    const actionsBlock = APP_SOURCE.slice(
+      APP_SOURCE.indexOf('const SHORTCUT_ACTIONS = {'),
+      APP_SOURCE.indexOf('// Use capture to handle before terminal')
+    );
+    expect(actionsBlock.length).toBeGreaterThan(0);
+    expect(actionsBlock).not.toContain('copyTerminalSelection');
+  });
+});
@@ -0,0 +1,166 @@
+/**
+ * Smart copy in a real browser (#211).
+ *
+ * The gate itself is unit-tested in test/terminal-copy-selection.test.ts. What
+ * can only be proven in a browser is the half that decides whether the PTY sees
+ * an interrupt: xterm calls the custom key handler BEFORE its own cancel(), so
+ * returning false does not preventDefault, and a synthetic KeyboardEvent never
+ * triggers a browser default action. Both facts mean the copy/interrupt split
+ * has to be driven with real key presses.
+ *
+ * Assertions are on real state: what landed on the clipboard, and what xterm
+ * emitted through onData (the bytes that would reach the PTY).
+ *
+ * Browser-driven, so it is excluded from `npm run test:ci` like the other
+ * Playwright suites. Run locally: npm test -- test/terminal-copy-shortcut.test.ts
+ *
+ * Port: 3174 (per MEMORY.md, ports 3150+ for tests)
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { chromium, type Browser, type Page } from 'playwright';
+import { WebServer } from '../src/web/server.js';
+
+const PORT = 3174;
+const BASE_URL = `http://localhost:${PORT}`;
+
+describe('terminal Ctrl+C smart copy', () => {
+  let server: WebServer;
+  let browser: Browser;
+  let page: Page;
+
+  beforeAll(async () => {
+    server = new WebServer(PORT, false, true);
+    await server.start();
+    browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext({ permissions: ['clipboard-read', 'clipboard-write'] });
+    page = await context.newPage();
+    await page.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
+    await page.waitForFunction(() => (window as any).app?.terminal, null, { timeout: 30000 });
+    // The first write after load can be dropped while the app finishes wiring
+    // its render pipeline, so poll until one really lands in the buffer.
+    await page.waitForFunction(
+      async () => {
+        const term = (window as any).app.terminal;
+        await new Promise((r) => term.write('\r\nWARMUP\r\n', r));
+        const buf = term.buffer.active;
+        for (let i = 0; i < buf.length; i++) {
+          if (buf.getLine(i)?.translateToString(true).includes('WARMUP')) return true;
+        }
+        return false;
+      },
+      null,
+      { timeout: 20000, polling: 500 }
+    );
+  }, 90000);
+
+  afterAll(async () => {
+    if (browser) await browser.close();
+    if (server) await server.stop();
+  }, 60000);
+
+  /** Write a marker line, optionally select it, and reset the capture state. */
+  async function setup(line: string, select: boolean, overrides: Record<string, unknown> = {}) {
+    await page.evaluate(
+      async ({ line, select, overrides }) => {
+        const app = (window as any).app;
+        const term = app.terminal;
+        const settings = app.loadAppSettingsFromStorage();
+        settings.shortcutOverrides = overrides;
+        app.saveAppSettingsToStorage(settings);
+        (window as any).__data = [];
+        if (!(window as any).__dataHooked) {
+          term.onData((d: string) => (window as any).__data.push(d));
+          (window as any).__dataHooked = true;
+        }
+        await new Promise((r) => term.write('\r\n' + line + '\r\n', r));
+        term.clearSelection();
+        if (select) {
+          const buf = term.buffer.active;
+          let row = -1;
+          for (let i = 0; i < buf.length; i++) {
+            if (buf.getLine(i)?.translateToString(true).includes(line)) row = i;
+          }
+          if (row === -1) throw new Error('marker line not found in buffer');
+          term.select(0, row, line.length);
+          if (!(term.getSelection() || '').trim()) throw new Error('selection is empty');
+        }
+        document.querySelector('.xterm-helper-textarea')!.dispatchEvent(new Event('focus'));
+        (document.querySelector('.xterm-helper-textarea') as HTMLElement).focus();
+        await navigator.clipboard.writeText('SENTINEL');
+      },
+      { line, select, overrides }
+    );
+  }
+
+  async function outcome() {
+    await page.waitForTimeout(350);
+    return page.evaluate(async () => ({
+      data: (window as any).__data as string[],
+      clipboard: (await navigator.clipboard.readText()).trim(),
+      hasSelection: (window as any).app.terminal.hasSelection(),
+    }));
+  }
+
+  it('copies the selection and sends nothing to the PTY', async () => {
+    await setup('COPY-CASE-SELECTED', true);
+    await page.keyboard.press('Control+c');
+    const res = await outcome();
+    expect(res.clipboard).toBe('COPY-CASE-SELECTED');
+    expect(res.data).toEqual([]);
+    expect(res.hasSelection).toBe(false); // cleared, so a second Ctrl+C interrupts
+  });
+
+  it('still interrupts when nothing is selected', async () => {
+    await setup('COPY-CASE-UNSELECTED', false);
+    await page.keyboard.press('Control+c');
+    const res = await outcome();
+    expect(res.data).toEqual(['\x03']);
+    expect(res.clipboard).toBe('SENTINEL');
+  });
+
+  it('copies on the explicit Ctrl+Shift+C chord', async () => {
+    await setup('COPY-CASE-EXPLICIT', true);
+    await page.keyboard.press('Control+Shift+C');
+    const res = await outcome();
+    expect(res.clipboard).toBe('COPY-CASE-EXPLICIT');
+    expect(res.data).toEqual([]);
+  });
+
+  it('never interrupts on Ctrl+Shift+C with an empty selection', async () => {
+    await setup('COPY-CASE-EXPLICIT-EMPTY', false);
+    await page.keyboard.press('Control+Shift+C');
+    const res = await outcome();
+    expect(res.data).toEqual([]);
+    expect(res.clipboard).toBe('SENTINEL');
+  });
+
+  it('restores the plain interrupt when the shortcut is disabled', async () => {
+    await setup('COPY-CASE-DISABLED', true, { 'copy-selection': { disabled: true } });
+    await page.keyboard.press('Control+c');
+    const res = await outcome();
+    expect(res.data).toEqual(['\x03']);
+    expect(res.clipboard).toBe('SENTINEL');
+  });
+
+  it('follows a rebind, and Ctrl+C goes back to pure interrupt', async () => {
+    await setup('COPY-CASE-REBOUND', true, { 'copy-selection': { bindings: [{ modifiers: ['alt'], key: 'y' }] } });
+    await page.keyboard.press('Alt+y');
+    const rebound = await outcome();
+    expect(rebound.clipboard).toBe('COPY-CASE-REBOUND');
+    expect(rebound.data).toEqual([]);
+
+    await setup('COPY-CASE-REBOUND-2', true, { 'copy-selection': { bindings: [{ modifiers: ['alt'], key: 'y' }] } });
+    await page.keyboard.press('Control+c');
+    const res = await outcome();
+    expect(res.data).toEqual(['\x03']);
+  });
+
+  it('leaves Ctrl+V on the paste trap', async () => {
+    await setup('COPY-CASE-PASTE', false);
+    await page.keyboard.press('Control+v');
+    const res = await outcome();
+    expect(res.data.join('')).toContain('SENTINEL'); // pasted text, not ^V
+    expect(res.data.join('')).not.toContain('\x16');
+  });
+});
@@ -10,6 +10,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
  TmuxManager,
+  buildCodexCommand,
  buildRemoteKillCommand,
  buildRemoteLaunchCommand,
  formatPaneSnapshot,
@@ -98,6 +99,14 @@ describe('TmuxManager (unit)', () => {
    });
  });

+  describe('Codex command builder', () => {
+    it('controls decorative TUI animation through Codex config', () => {
+      expect(buildCodexCommand({ animations: false })).toBe('codex --config tui.animations=false');
+      expect(buildCodexCommand({ animations: true })).toBe('codex --config tui.animations=true');
+      expect(buildCodexCommand()).toBe('codex');
+    });
+  });
+
  describe('remote launch command builder', () => {
    it('wraps codex command overrides in ssh with remote tmux launch', () => {
      const command = buildRemoteLaunchCommand({
@@ -137,7 +146,16 @@ describe('TmuxManager (unit)', () => {
        sessionId: 'abc123def456',
      });

-      expect(command).toContain('exec bash -l');
+      expect(command).toContain('exec "${SHELL:-/bin/sh}" -i -l');
+      // `failed`, not `on`: `on` also keeps the pane after a CLEAN exit, so typing
+      // `exit` in a remote shell strands a dead pane that the next launch's `-A`
+      // reattaches to instead of starting a shell.
+      expect(command).toContain('remain-on-exit failed');
+      expect(command).not.toContain('remain-on-exit on');
+      // Last in the chain: tmux aborts the rest of a `\;` sequence after an error,
+      // and `failed` needs tmux >= 3.2 on the REMOTE host. Trailing, a rejection
+      // costs only this option instead of every setting after it.
+      expect(command.trimEnd().endsWith("remain-on-exit failed'")).toBe(true);
    });

    it('defaults claude to a non-interactive launch (--dangerously-skip-permissions)', () => {
@@ -146,7 +164,13 @@ describe('TmuxManager (unit)', () => {
        remote: { hostId: 'gpu-box', label: 'GPU Box', host: '10.0.0.42', username: 'ubuntu', remotePath: '/w' },
        sessionId: 'abc123def456',
      });
-      expect(command).toContain('exec claude --dangerously-skip-permissions');
+      // Routed through an interactive login shell so ~/.local/bin (where `claude`
+      // typically lives) is on PATH — ssh's remote-command execution is neither
+      // interactive nor login, so a bare `exec claude` fails with "command not found".
+      // The inner quoting is escaped twice over (once per shellescape() layer), so
+      // assert on the unescaped substrings rather than the literal quoted form.
+      expect(command).toContain('exec "${SHELL:-/bin/sh}" -i -l -c');
+      expect(command).toContain('claude --dangerously-skip-permissions');
    });
  });