feat(terminal): Ctrl+C copies the selection, interrupts when nothing is selected

Closes #211. Copying from the terminal only worked through the browser
context menu, because 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, toasts, 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
falls through: an explicit copy that interrupts a running agent because the
selection happened to be empty would be a footgun.

Three details that keep the interrupt safe:

- The decision lives in attachCustomKeyEventHandler (terminal-ui.js) and the
  no-selection path returns true WITHOUT preventDefault. xterm calls the
  custom handler before its own cancel(), so returning false alone does not
  cancel the event; the copy path therefore calls preventDefault explicitly,
  or the browser would run its native copy on top of ours.
- copy-selection is a full registry entry (rebindable and disableable in App
  Settings) whose action is deliberately absent from SHORTCUT_ACTIONS, the
  same trick command-palette uses: the generic capture loop preventDefaults
  every match it dispatches, which would cost the user the interrupt key.
- The gate is keydown-only, since the custom handler also runs for keypress
  and keyup.

Copy goes through _copyText (Clipboard API, then hidden-textarea +
execCommand) rather than 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.

Tests: test/terminal-copy-selection.test.ts pins the gate and the
SHORTCUT_ACTIONS invariant; test/terminal-copy-shortcut.test.ts drives real
key presses in chromium and asserts on the clipboard plus the bytes xterm
emitted (browser-driven, so excluded from test:ci like the other Playwright
suites). Verified manually on an isolated beta instance before landing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -236,7 +236,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 +260,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
 

README.md

@@ -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                                            |

README.zh-CN.md

@@ -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`                  | 切换语音输入                                             |

config/vitest.ci.config.ts

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

docs/architecture-invariants.md

@@ -138,6 +138,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.

docs/terminal-copy-shortcut-plan.md

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

src/web/public/app.js

@@ -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',

src/web/public/i18n.js

@@ -451,6 +451,7 @@
     'Respawn Blocked': '重生已阻止',
     'Task Complete': '任务完成',
     'Copied to clipboard': '已复制到剪贴板',
+    'Failed to copy': '复制失败',
     'Checking…': '正在检查…',
     'Starting…': '正在启动…',
     'Starting update…': '正在开始更新…',

src/web/public/index.html

@@ -639,6 +639,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>

src/web/public/terminal-ui.js

@@ -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') {
@@ -2612,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;

test/help-modal-shortcuts.test.ts

@@ -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');

test/keyboard-shortcuts.test.ts

@@ -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`');
+  });
 });

test/terminal-copy-selection.test.ts

@@ -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');
+  });
+});

test/terminal-copy-shortcut.test.ts

@@ -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');
+  });
+});