feat(settings): relocate Gesture Control into Input section + release 0.8.2

- Move the Gesture Control (beta) toggle into the existing Input section (alongside Local Echo / CJK Input / Extended Keyboard Bar); remove the duplicate "Input" section header. Hide only the toggle (not the whole section) when CODEMAN_GESTURE=1 is unset. - scripts/codeman-web.service: set CODEMAN_GESTURE=1 so the gesture feature is available on the local install (still gated by the default-OFF toggle). - CLAUDE.md: version sync to 0.8.2 + config/app.js structural-count fixes. - Version packages -> 0.8.2 (changeset covers detach, gesture overlay, multi-monitor, settings toggles, cache-busting). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Merge pull request #109 from Ark0N/fix/gesture-beta-label
2026-09-30 20:49:41 +02:00 · 2026-06-08 17:01:17 +02:00 · 2026-06-08 16:42:32 +02:00 · 2026-06-08 16:40:54 +02:00 · 2026-06-08 16:37:17 +02:00 · 2026-06-08 16:36:46 +02:00
76 changed files with 11143 additions and 833 deletions
@@ -34,6 +34,32 @@ jobs:
      - name: Format check
        run: npm run format:check

+      - name: Server boot smoke test
+        run: |
+          set -u
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+          npx tsx src/index.ts web --port 3151 > /tmp/boot.log 2>&1 &
+          SERVER_PID=$!
+          trap "kill $SERVER_PID 2>/dev/null || true" EXIT
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:3151/api/status -o /dev/null; then
+              echo "Server booted in ${i}s"
+              exit 0
+            fi
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "Server exited before becoming ready. Logs:"
+              cat /tmp/boot.log
+              exit 1
+            fi
+            sleep 1
+          done
+          echo "Server did not respond on /api/status within 30s. Logs:"
+          cat /tmp/boot.log
+          exit 1
+
 # Note: The test suite is intentionally excluded from CI.
 # Tests spawn real tmux sessions and require a full system environment.
 # Run tests locally with: npx vitest run test/<file>.test.ts
@@ -53,7 +53,17 @@ scripts/remotion/out/
 # Artifacts that should not be tracked
 test-results/
 tmp/
-public
+# Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
+# with a leading slash so it does NOT also match src/web/public (a bare `public`
+# would swallow the whole web UI source dir and silently un-stage any new asset
+# added there). No trailing slash so it still matches the symlink, not just dirs.
+/public
+
+# Opt-in gesture overlay runtime assets: large MediaPipe wasm + model (~27 MB)
+# fetched at build/install by scripts/fetch-gesture-assets.mjs, kept out of git.
+# (The gesture bundle itself, gesture-codeman.js, IS tracked.)
+src/web/public/gesture/wasm/
+src/web/public/gesture/*.task

 # Claude Code plan tracking
 plan.json
@@ -66,3 +76,6 @@ commands
 todo.md
@fix_plan.md
 readme-preview.mjs
+
+# Uploaded images land here under each session working dir (runtime artifact)
+.claude-images/
@@ -1,5 +1,141 @@
 # aicodeman

+## 0.8.2
+
+### Patch Changes
+
+- Session detach/undock, opt-in gesture-control overlay, multi-monitor spanning, new App-Settings toggles, and asset cache-busting.
+  - **Session detach/undock + instance isolation (#103):** Detach a session into its own solo (popup) window from the tab strip. Adds multi-instance isolation primitives in `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`) keyed off `CODEMAN_INSTANCE`, so a beta can run side-by-side with prod without discovering/attaching to prod's live tmux sessions or clobbering its `state.json`. `CODEMAN_INSTANCE` defaults to the production layout (`~/.codeman`, `-L codeman`, port 3000), so master installs are unaffected. Adds `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). The legacy `~/.claudeman` migration is now scoped to the default instance only. Hardened detach edge cases. Tests: `test/config/instance.test.ts`.
+  - **Gesture-control overlay (Phase 5, opt-in via `CODEMAN_GESTURE=1`):** Camera hand-tracking overlay (self-hosted MediaPipe — wasm + model fetched at install/build via `scripts/fetch-gesture-assets.mjs` rather than committed). `CODEMAN_GESTURE=1` makes the feature _available_ (CSP widening + `/gesture/` assets + `window.__codemanGestureAvailable`); the per-user **Gesture Control (beta)** toggle (App Settings → Display → Input, default OFF) is the actual on/off and reloads the page to inject/remove the bundle. Dashboard-only (not solo popups). Labeled "(beta)" (#109).
+  - **Multi-monitor button:** Header button (opt-in via App Settings → Display → Header Displays) that POSTs `/api/system/span-displays` to spawn `scripts/span-codeman.sh` — a maximized browser `--app` window sized to the union of all displays, so the gesture layer's floating panels can drag across the physical monitor seam. Tests: `test/routes/system-span-displays.test.ts`.
+  - **New App-Settings toggles (#105):** Gesture control and the multi-monitor button are both opt-in (default OFF), with live show/hide on save.
+  - **Asset cache-busting:** `renderIndexHtml` appends `?v=<mtime>` to every same-origin `.js`/`.css` reference; `index.html` is served `no-cache`, so a normal reload picks up edited modules/styles without a hard refresh. Tests: `test/render-index-html.test.ts`.
+  - **Gesture Control toggle placement:** the toggle now lives inside the existing **Input** settings section (alongside Local Echo / CJK Input / Extended Keyboard Bar) instead of a duplicate "Input" section; only the toggle itself is hidden when `CODEMAN_GESTURE=1` is unset, leaving the rest of the section intact.
+  - **Service env:** `scripts/codeman-web.service` now sets `CODEMAN_GESTURE=1` so the gesture feature is available on the local install (still gated behind the default-OFF per-user toggle).
+  - **Docs:** CLAUDE.md updated for the orchestrator loop, multi-monitor/span-displays, cache-busting, gesture/multi-monitor toggles, and structural-count fixes.
+
+## 0.8.1
+
+### Patch Changes
+
+- Thinking Effort now flows as a soft default the user can override in-session (PR #104, by @TeigenZhang).
+
+  Previously Codeman carried the effort setting as the `CLAUDE_CODE_EFFORT_LEVEL` env var, which Claude Code treats as a hard override — it locked effort for the whole session and rejected in-session `/effort` switching (including switching to `ultracode`). Effort is now injected at spawn time as a CLI soft default that `/effort` can still change freely in either direction:
+  - Regular levels (`low`/`medium`/`high`/`xhigh`/`max`) are passed via `claude --effort <level>` (the settings `effortLevel` key silently drops `max`, so the flag is used instead).
+  - `ultracode` (xhigh effort + standing dynamic-workflow orchestration) is passed via `claude --settings '{"ultracode":true}'`, since the `--effort` flag rejects it.
+
+  Details:
+  - New `effort` field on the create-session, quick-start, and Ralph-loop request schemas; threaded through `Session._effort` to both spawn paths (tmux `buildSpawnCommand` and direct-PTY `buildInteractiveArgs`), persisted in `SessionState.effort`, and restored on reboot recovery.
+  - `buildEffortCliArgs()` is the single, allowlist-validated source for both carriers (injection-safe).
+  - Settings UI adds an "Ultracode (multi-agent workflows)" option to the Thinking Effort dropdown; the frontend no longer emits `CLAUDE_CODE_EFFORT_LEVEL`.
+  - Legacy migration: sessions persisted with the old env var are auto-migrated into the new `effort` field, and the stale tmux env var is unset so respawned panes are no longer locked.
+  - Adds `test/effort-injection.test.ts` (13 cases) covering carrier mapping, injection guards, args building, and constructor migration.
+
+## 0.8.0
+
+### Minor Changes
+
+- Event-loop responsiveness fix, mobile image upload, response-viewer polish, and a mobile-UI trim.
+  - **fix: avoid event-loop stalls from synchronous tmux/ps calls (#100):** The session manager ran `execSync` for tmux mouse-mode toggles, `list-panes`, and `ps`/`pgrep` resource-stat queries on the main thread. Under multi-session / many-pane load these blocking spawns froze Node's single event loop, stalling SSE broadcasts and PTY I/O (the ":3000 briefly unreachable, process never restarts" class of incident). Converted those calls to async `execAsync` and updated all callers to `await`. Added a lightweight `utils/event-loop-monitor.ts` that samples loop-delay and logs when a stall threshold is exceeded, started on web-server boot and stopped on shutdown — so future regressions leave a timestamped, quantified log line instead of vanishing silently.
+  - **feat(web): mobile image upload to active session via paste dialog (#101):** The mobile keyboard-accessory paste dialog now attaches images, not just text — via a native picker (`accept=image/*` → camera / photo library / files) plus best-effort capture of images pasted into the textarea. Both paths reuse the existing `_uploadAndInsertImages()` → `POST /api/sessions/:id/paste-image` pipeline. Images are re-encoded client-side before upload (PNG→PNG to preserve transparency, everything else→JPEG, animated GIFs passed through untouched) so the bytes always match their declared extension — fixing the Android/MIUI case where a WebP/HEIF mislabeled as `image/jpeg` passed the extension allowlist but failed the server's magic-byte check. The server logs a precise diagnostic on any remaining magic-byte mismatch.
+  - **feat(web): response-viewer transcript fallback + code-block rendering (#102):** A substantial response-viewer styling overhaul — proportional prose font (monospace kept for code), refined heading/code/blockquote/list styling, readable max content width, and a smoother slide-in animation; the `.rv-text` rules now also apply to `.response-viewer-body` so transcript-missing fallback content gets the same typography. Plus a `_renderMarkdown` null-safety fix (`text` → `src = text || ''`).
+  - **feat(web): remove /compact button from the mobile keyboard accessory bar:** Dropped `/compact` from both the simple and extended accessory-bar layouts and the associated action handling. `/clear` retains its double-tap confirmation. Verified on a touch-emulated viewport that neither layout renders a compact action.
+
+## 0.7.1
+
+### Patch Changes
+
+- **fix(respawn): auto-accept now fires on plan approvals after `Worked for X` line, and on AskUserQuestion menus**
+
+  Two related blockers in the respawn controller's auto-accept path:
+  - Modern Claude Code emits `✻ Worked for Xm Ys` immediately before a plan-approval menu. `_detectCompletionMessage()` cancelled the auto-accept timer and `canAutoAccept()` then rejected on `completionMessageTime !== null`, so plan approvals **never** auto-accepted — the 10 s completion-confirm timer instead started a respawn cycle while the menu sat unanswered.
+  - The same logic in `signalElicitation()` set a hard flag that blocked auto-accept whenever Claude Code fired the `elicitation_dialog` hook, contradicting the in-UI hint ("Auto-accept presses Enter for plan approvals **and default question options**"). AskUserQuestion menus were therefore never auto-accepted either.
+
+  Fix:
+  - `_detectCompletionMessage()` no longer cancels the auto-accept timer; the auto-accept pre-filter is now the authoritative "is there a numbered selection menu?" gate.
+  - `canAutoAccept()` and the AI-plan-check callback both accept `'watching'` AND `'confirming_idle'` states (covers the single-PTY-burst case where `Worked for` and the menu arrive together — `_detectCompletionMessage` returns early before the substantial-output check can demote state back to watching). `sendAutoAcceptEnter()` self-transitions back to `'watching'` before sending Enter.
+  - `signalElicitation()` is now an affirmative hint that primes the auto-accept timer instead of blocking. Still gated on `config.autoAcceptPrompts` AND state ∈ {`watching`, `confirming_idle`} — never fires Enter when respawn is off or auto-accept is disabled.
+  - AI plan-check prompt broadened to recognize AskUserQuestion / elicitation menus as valid for auto-accept (the verdict name `PLAN_MODE` is preserved for compatibility but now means "auto-accept this selection menu").
+  - Removed the now-unused `elicitationDetected` field and its assignments.
+
+  Two new regression tests cover both the separate-PTY-chunk and single-PTY-chunk cases; the previously misleading "should NOT send Enter when completion message was detected" test was renamed and re-scoped to clarify it tests the **no-menu** path (which still correctly rejects via the pre-filter).
+
+  **docs(web): correct `sendPendingCtrlL` comment** — removed the stale "called by foo/bar" note from the dead-call-graph helper after #99.
+
+## 0.7.0
+
+### Minor Changes
+
+- Response viewer & terminal-stability improvements, plus test/error-handling hardening.
+  - **Copy button on code blocks (#98):** Every fenced code block in the response viewer now has a one-click copy button pinned to its top-right, outside the `<pre>` scroll container so it stays put during horizontal scroll. ASCII diagrams keep their line-wrap toggle alongside it. Copy prefers the async Clipboard API and falls back to a hidden-textarea + `execCommand` path, so it works over plain HTTP (tunnel) too, with a brief ✓/✕ feedback state.
+  - **Fix: stop auto-sending Ctrl+L from session-selection paths (#99):** A fast page refresh or SSE reconnect could fire two programmatic Ctrl+L (`\x0c`) sends within Claude Code 2.x's "clear conversation" confirmation window, silently wiping the active conversation. Removed the automatic Ctrl+L sends from `selectSession()`, `restoreTerminalSize()`, and the dead `sendPendingCtrlL()` path; redraws now rely on resize/SIGWINCH. User-initiated Ctrl+L still works. Trade-off: an occasional transient stale Ink frame right after refresh that self-heals on the next keypress — far preferable to silent data loss.
+  - **Test & error-handling hardening (#97):** Repaired route-test harness error rendering via a dedicated `route-error-handler.ts`, and stopped the AI idle/plan checkers from spawning real processes during tests.
+
+## 0.6.12
+
+### Patch Changes
+
+- Fix new-session crash after a tmux upgrade and isolate Codeman sessions on a dedicated tmux socket.
+  - **Pane file-descriptor limit**: raise `ulimit -Sn` before launching the CLI (in both the spawn and respawn paths) so the newer tmux + macOS launchd combination — which hands panes a low soft `nofile` limit (256) that recent Claude Code refuses to start under — no longer kills every freshly spawned session on startup.
+  - **Single-socket isolation**: all Codeman-owned tmux sessions now live on a dedicated socket (`tmux -L codeman`, overridable via `CODEMAN_TMUX_SOCKET`), fully separated from the user's default tmux server. The socket name is validated and shell-escaped at every call site.
+  - **Drop the drift-prone per-session `tmuxSocket` field**: session reconciliation collapses to a single `list-panes` query against the one socket, eliminating live sessions being wrongly marked dead ("session not found") and duplicate "Restored:" tabs. Stale per-session socket tags and duplicate records are cleaned from disk on load (dedup by `muxName`, keeping the real entry over `restored-` placeholders).
+  - **Route remaining bare-`tmux` call sites through the socket**: the window-size query on re-attach (previously fell back to 120×40 and lost scrollback) and the send-key route (Shift+Enter / Ctrl+Enter newline).
+  - **SSH chooser scripts** (`tmux-manager.sh`, `tmux-chooser.sh`) route every tmux call through the dedicated socket.
+
+## 0.6.11
+
+### Patch Changes
+
+- Resume Conversation: fixes and folder drill-down.
+  - **fix(history)**: `decodeProjectKey()` now uses longest-join-first backtracking with on-disk validation, so sibling directories sharing a prefix (e.g. `diary/` vs `diary-app/`) resolve to the correct path. Previously the greedy shortest-match decoder picked the shorter name and bailed, surfacing `$HOME` in the Resume Conversation list and resuming into the wrong folder. Greedy decode is kept as a fallback so history for deleted projects still resolves. (#92)
+  - **fix(tabs)**: Drop the client-side resurrection of ended-session tabs. The old code cached open tabs in `localStorage` and rebuilt them as grayed-out stubs whenever the server no longer knew them, which left phantom tabs after closing a session on another device. The server is now the single source of truth; legacy `localStorage` keys are purged on init. Net -44 / +6 lines. (#93)
+  - **feat(history)**: New "View all in this folder" drill-down on Resume Conversation. `GET /api/history/sessions` accepts `projectKey` (validated against `^[A-Za-z0-9_-]+$` before any filesystem access), `offset`, and `limit`; single-folder mode bypasses the 50-cap and returns `{ sessions, total }`. Frontend adds a modal listing 20 sessions per page with a "Show more" pagination button. Modal items omit their own "View all" button to prevent recursive entry points. (#94)
+
+## 0.6.10
+
+### Patch Changes
+
+- ## Security: paste-image endpoint hardening (#90)
+
+  Addresses seven findings from the dismissed review of #84. Most exposed in tunneled deployments where `CODEMAN_PASSWORD` is set but the server is reachable beyond localhost.
+  - **CSRF protection** on `POST /api/sessions/:id/paste-image`. Requires `Origin`/`Referer` to match `req.host`; non-browser clients (no `Origin` and no `Referer`) must send `X-Codeman-CSRF`. Defeats cross-origin `<form enctype="multipart/form-data">` submits that would otherwise plant arbitrary bytes into the victim's `.claude-images/` while their session cookie is live.
+  - **Magic-byte validation** on uploaded images. Sniffs the first 12 bytes against PNG/JPEG/GIF/WebP/BMP signatures and rejects 415 on mismatch. Polyglot HTML-or-SVG-with-image-MIME no longer round-trips through the endpoint.
+  - **Symlink-safe writes** on `.claude-images/`. `lstat` before the write, non-recursive `mkdir`, `O_EXCL|O_NOFOLLOW` on file open. A `node_modules` postinstall (or the agent itself) planting `.claude-images -> ~/.ssh/` no longer redirects pastes outside `workingDir`.
+  - **Multipart parser swap** to `@fastify/multipart` with `limits: { fileSize: 10MB, files: 1, fields: 4 }`. Replaces a hand-rolled boundary scanner that matched the literal boundary anywhere in the body, hard-coded `\r\n` (silently corrupting LF-only clients), and had no part-count cap.
+  - **Rate limit + GC**: token-bucket (30/min per IP+session) and hourly GC of `paste-*` files older than 7 days from each live session's `.claude-images/`. New `paste-image-gc.ts` started/stopped from `WebServer.start/stop`.
+  - **Collision-free filenames**: `paste-${Date.now()}-${randomBytes(4)}${ext}`. Two tabs pasting in the same millisecond no longer silently last-write-wins.
+  - **Bracketed-paste preservation**: text-only paste in `image-input.js` now goes through `terminal.paste(text)` instead of `sendInput(text)`, so xterm preserves `CSI 200~ ... CSI 201~` markers — Claude Code uses them as part of its prompt-injection defenses.
+
+  ## Fix: duplicate multipart parser conflict
+
+  Removed a duplicate multipart content-type parser left behind after the swap above. The duplicate registration conflicted with `@fastify/multipart`'s own parser; uploads now flow through the plugin exclusively.
+
+  ## WebGL renderer auto-fallback hardening (#91)
+
+  Follow-ups on the longtask auto-fallback shipped in #83.
+  - `PerformanceObserver` is now disconnected on `onContextLoss` as well as on the trip path. Previously the observer outlived its disposed addon after a context loss, holding a closure reference over every longtask the page emitted.
+  - Thresholds (`200ms / 3 longtasks / 30s window / 5s grace / 7d sticky-disable`) are hoisted to `WEBGL_FALLBACK` in `constants.js`. No more inline literals.
+  - New `evaluateWebGLLongTaskTrip()` pure helper splits the rolling-window arithmetic from the `PerformanceObserver` callback so the trip math is unit-testable. New `test/webgl-fallback.test.ts` (9 tests, port 3166): trip inside window, no-trip when spread, sub-threshold filtering, stale-entry pruning, cumulative counting across batches, observer-dispose idempotency.
+
+  ## CI: server boot smoke test
+
+  GitHub Actions now boots the server as a final step after typecheck/lint/format. Catches production-only ESM/CJS regressions that `tsx` masks in dev.
+
+  ## Docs
+
+  `CLAUDE.md` frontend-module table updated to include `image-input.js` (overlooked when #84 landed).
+
+## 0.6.9
+
+### Patch Changes
+
+- Terminal renderer hardening, SSE bandwidth cut, image paste, and a security tightening on the new live filter:
+  - **Multi-primitive yield for write pacing** (#85): replaces six raw `requestAnimationFrame` callsites in the xterm.js write pipeline with a yielding helper that races `requestAnimationFrame`, `setTimeout(50)`, and a tick Worker. Keeps the terminal responsive when the tab is backgrounded or occluded — Chrome's intensive-throttling no longer stalls long writes.
+  - **WebGL longtask auto-fallback** (#83): a `PerformanceObserver` watches for ≥200ms WebGL frames; three within a 30s window disposes the WebGL addon and falls back to the canvas renderer. Decision is persisted in localStorage for 7 days, and `?webgl=force` clears it.
+  - **Per-client live SSE subscription filter** (#86): each connected client gets a stable UUID and can narrow its terminal stream to one session via `POST /api/events/subscribe` — no EventSource reconnect on tab switches. Cuts SSE bandwidth roughly N× when N sessions are open. Lifecycle/metadata events (`session:*`, `case:*`, `ralph:*`, `hook:*`) now broadcast to every client so sidebars stay in sync.
+  - **Image paste and drag-and-drop into the terminal** (#84): `Ctrl+V` and dropped images upload to `POST /api/sessions/:id/paste-image`, save under `${workingDir}/.claude-images/paste-${ts}.${ext}` and type the path into the terminal. Hard 10MB cap, server-generated filename (no traversal), `.svg` deliberately excluded from the allowlist to avoid a same-origin XSS path through `file-raw`.
+  - **SSE clientId validation**: the per-client identifier introduced in #86 is now constrained to `[A-Za-z0-9_-]{8,64}` at both ingress points. Without this, an authenticated attacker could send another tab's clientId to silently evict it from broadcasts, mutate any clientId's session filter to blackhole the victim's terminal stream, or grow `sseClientsById` unboundedly via long IDs. The subscribe payload is also capped at 64 session entries of ≤128 chars each.
+
 ## 0.6.8

 ### Patch Changes
@@ -30,7 +30,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM

-The production server caches static files for 1 year (`maxAge: '1y'` in `server.ts`). After deploying frontend changes, users may need a hard refresh (Ctrl+Shift+R) to see updates.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an *absolute* URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.

 ## COM Shorthand (Deployment)

@@ -56,7 +56,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**: 0.6.8 (must match `package.json`)
+**Version**: 0.8.2 (must match `package.json`)

 ## Project Overview

@@ -72,7 +72,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 ## Additional Commands

-`npm run dev` = dev server. Default port: `3000`. Commands not in Quick Reference:
+`npm run dev` = dev server. Default port: `3000` (override with `--port` or the `CODEMAN_PORT` env var). To run this beta isolated alongside a prod Codeman, use `scripts/run-beta.sh` (sets `CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). Commands not in Quick Reference:

 | Task | Command |
 |------|---------|
@@ -95,9 +95,11 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly
 - **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
 - **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift
- **Dual-CLI prefix discipline** — Codeman supports both Claude Code and OpenCode (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward both prefixes
+- **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
+- **Dual-CLI prefix discipline** — Codeman supports both Claude Code and OpenCode (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward both prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
 - **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. Real bugs caused: 0.6.4 (`durationMinutes` for ∞ respawn), and the same shape pattern hit `opusContext1mEnabled` in 0.6.3
- **`xterm-zerolag-input` is duplicated** — the local-echo overlay lives in BOTH `packages/xterm-zerolag-input/src/` (published to npm as a standalone library for external consumers — see README "Published Packages") AND inline inside `src/web/public/app.js` (runtime copy the web UI actually loads, since the page ships as plain JS without a bundler). Any change to overlay behavior MUST be applied to both, or dev and prod diverge — and a public API break in the package warrants a separate version bump for `xterm-zerolag-input` in the changeset. Always test on mobile after touching it.
+- **`xterm-zerolag-input` is duplicated** — the local-echo overlay lives in BOTH `packages/xterm-zerolag-input/src/` (published to npm as a standalone library for external consumers — see README "Published Packages") AND inline inside `src/web/public/app.js` (runtime copy the web UI actually loads, since the page ships as plain JS without a bundler). Any change to overlay behavior MUST be applied to both, or dev and prod diverge — and a public API break in the package warrants a separate version bump for `xterm-zerolag-input` in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+- **Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.

 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.

@@ -109,7 +111,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 |--------|-----------|-------|
 | **Entry** | `src/index.ts`, `src/cli.ts` | |
 | **Session** | `src/session.ts` ★, `src/session-manager.ts`, `src/session-auto-ops.ts`, `src/session-cli-builder.ts`, `src/session-lifecycle-log.ts`, `src/session-task-cache.ts` | |
-| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` | |
+| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★ | |
 | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
 | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
 | **Orchestrator** | `src/orchestrator-loop.ts`, `src/orchestrator-planner.ts`, `src/orchestrator-verifier.ts` | Read `docs/orchestrator-loop-architecture.md` first |
@@ -120,14 +122,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
 | **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (15 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` (~2.9K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 4 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`) + `sw.js` | |
+| **Frontend** | `src/web/public/app.js` (~3.4K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | |
 | **Types** | `src/types/index.ts` (barrel) → 14 domain files; also `src/types.ts` root re-export | See `@fileoverview` in index.ts |

 ★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.

 **Local package**: `packages/xterm-zerolag-input/` — local echo overlay for xterm.js; copy embedded in `app.js`.

-**Config**: `src/config/` — 9 files. Import from specific files, not barrel.
+**Config**: `src/config/` — 10 files. Import from specific files, not barrel.

 **Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).

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

 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.

+**Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
+
 **Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`.

 **Agent Teams**: `TeamWatcher` polls `~/.claude/teams/`, matches to sessions via `leadSessionId`. Teammates are in-process threads appearing as subagents. Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. See `docs/agent-teams/`.
@@ -158,6 +162,10 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 **Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).

+**Multi-monitor button** (header, top-right; the notification bell it sits beside stays hidden — notifications live in Settings → Notifications). `app.launchMultiMonitor()` (in `panels-ui.js`) POSTs `/api/system/span-displays`, which spawns `scripts/span-codeman.sh` — a fresh, maximized browser `--app` window sized to the union of all displays (macOS; needs "Displays have separate Spaces" OFF). Supports the gesture layer's in-page floating session panels dragging across the physical monitor seam. **Opt-in:** hidden by default; enable under App Settings → Display → **Header Displays** ("Multi-monitor Button", `showMultiMonitorButton`). The button carries a `btn-multimonitor--hidden` class in the template; `renderIndexHtml` strips that class at render when the setting is on (a unique class token, not a brittle match on the aria-label/style copy), and `applyHeaderVisibilitySettings()` toggles the same class live on save. Solo (detached) windows hide it via `body.solo-mode`.
+
+**Gesture control** (the camera hand-tracking overlay) is **opt-in, default OFF**, under App Settings → Display → **Input** (`gestureControlEnabled`). `CODEMAN_GESTURE=1` makes the feature *available* on the instance (CSP widening + `/gesture/` assets) and sets `window.__codemanGestureAvailable` (the Input section only shows when set); the overlay bundle is injected by `renderIndexHtml` **only when the setting is enabled**, so that method is `async` and reads `settings.json` via `readSettings(true)` — the `true` forces a **fresh** read (bypassing the 2s `_settingsCache`), because a post-save reload happens within that TTL and the cached value would otherwise render the pre-toggle state. Toggling the setting reloads the page (the bundle is render-injected).
+
 **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+? (help), Ctrl+W (kill), Ctrl+Tab (next), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font).
@@ -181,7 +189,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 ### API Routes

-~128 handlers across 15 route files in `src/web/routes/`: system (36), sessions (27), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (5), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~130 handlers across 15 route files in `src/web/routes/`: system (37, incl. `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (5), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.

 ## Adding Features

@@ -216,7 +224,7 @@ Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pa

 **Ports**: Pick unique ports manually. Search `const PORT =` before adding new tests.

-**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject()` in `test/routes/`. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles).
+**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles).

 ## Debugging

@@ -1,3 +1,9 @@
+> **⚠️ ARCHIVED 2026-05-21 — superseded, kept for history.**
+> The headline items here were verified resolved: the P0 `{WORKING_DIR}` placeholder
+> is now replaced (`plan-orchestrator.ts:431`), and the "~66 dead functions in app.js"
+> are gone (app.js was modularized 15K→3K LOC). A fresh `npm run knip` sweep on
+> 2026-05-21 found only a handful of unused test helpers. Do not treat this as a live TODO.
+
 # Codebase Cleanup Findings

 Compiled from parallel analysis of the entire Codeman codebase by 3 research agents (2026-02-19).
@@ -1,3 +1,9 @@
+> **⚠️ ARCHIVED 2026-05-21 — superseded, kept for history.**
+> The "Critical" structural items here are done: `server.ts` 6,736→2,065 LOC,
+> `app.js` 15,196→3,083 LOC, `types.ts` 1,443→12 LOC (now a barrel → `src/types/`).
+> The phase plans that executed this work are in `docs/archive/phase*-plan.md`.
+> Do not treat this as a live TODO; see CLAUDE.md for current architecture.
+
 # Code Structure & Quality Findings

 **Date**: 2026-02-28
@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "0.6.8",
+  "version": "0.8.2",
  "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
  "type": "module",
  "main": "dist/index.js",
@@ -52,6 +52,7 @@
  "dependencies": {
    "@fastify/compress": "^8.3.1",
    "@fastify/cookie": "^11.0.2",
+    "@fastify/multipart": "^10.0.0",
    "@fastify/static": "^8.0.0",
    "@fastify/websocket": "^11.2.0",
    "@xterm/addon-fit": "^0.11.0",
@@ -32,6 +32,9 @@ run('chmod dist/index.js', 'chmod +x dist/index.js');
 // 2. Copy static assets (clean first to remove stale hashed files from previous builds)
 run('clean public', 'rm -rf dist/web/public');
 run('prepare dirs', 'mkdir -p dist/web dist/templates dist/web/public/vendor');
+// Fetch the opt-in gesture overlay's MediaPipe wasm + model into src/ (idempotent,
+// non-fatal, kept out of git) so the copy below carries them into dist/.
+run('gesture assets', 'node scripts/fetch-gesture-assets.mjs');
 run('copy web assets', 'cp -r src/web/public dist/web/');
 run('copy template', 'cp src/templates/case-template.md dist/templates/');

@@ -93,6 +96,7 @@ console.log('\n[build] content-hash cache busting');
    'ralph-wizard.js',
    'api-client.js',
    'subagent-windows.js',
+    'image-input.js',
    'vendor/xterm-zerolag-input.js',
  ];
  const manifest = {};
@@ -12,6 +12,10 @@ KillMode=process
 Environment=NODE_ENV=production
 Environment=HOME=/home/arkon
 Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache
+# Make the gesture-control overlay AVAILABLE (CSP widening + /gesture/ assets +
+# window.__codemanGestureAvailable). The actual on/off stays the per-user
+# `gestureControlEnabled` toggle in App Settings → Display → Input (default OFF).
+Environment=CODEMAN_GESTURE=1

 # Logging
 StandardOutput=journal
@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Fetch the gesture-overlay runtime assets (MediaPipe wasm + the
+ * gesture-recognizer model) into src/web/public/gesture/ so Codeman can serve
+ * them same-origin (a browser content-blocker otherwise blocks the public CDNs
+ * and the overlay fails to start). These are large binaries (~27 MB) kept OUT of
+ * git (ignored explicitly via `src/web/public/gesture/wasm/` + `*.task` in
+ * .gitignore); they are fetched here at install (postinstall) and build time.
+ *
+ * Idempotent: skips files already present. Non-fatal: the gesture overlay is
+ * opt-in (CODEMAN_GESTURE=1), so a fetch failure only warns — it must not break
+ * `npm install` / `npm run build`. The build then copies src/web/public into
+ * dist/ as usual, so prod gets these too.
+ *
+ * The @mediapipe/tasks-vision version MUST match the one bundled into the gesture
+ * overlay (Ark0N/codeman-gesture-control) so the wasm loader matches its JS API.
+ */
+import { mkdirSync, existsSync, statSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GESTURE = join(__dirname, '..', 'src', 'web', 'public', 'gesture');
+const WASM = join(GESTURE, 'wasm');
+
+const MP_VERSION = '0.10.21'; // keep in sync with the gesture overlay's @mediapipe/tasks-vision
+const WASM_BASE = `https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@${MP_VERSION}/wasm`;
+const MODEL_URL =
+  'https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task';
+
+const ASSETS = [
+  { url: `${WASM_BASE}/vision_wasm_internal.js`, path: join(WASM, 'vision_wasm_internal.js') },
+  { url: `${WASM_BASE}/vision_wasm_internal.wasm`, path: join(WASM, 'vision_wasm_internal.wasm') },
+  { url: `${WASM_BASE}/vision_wasm_nosimd_internal.js`, path: join(WASM, 'vision_wasm_nosimd_internal.js') },
+  { url: `${WASM_BASE}/vision_wasm_nosimd_internal.wasm`, path: join(WASM, 'vision_wasm_nosimd_internal.wasm') },
+  { url: MODEL_URL, path: join(GESTURE, 'gesture_recognizer.task') },
+];
+
+async function main() {
+  mkdirSync(WASM, { recursive: true });
+  let fetched = 0;
+  let skipped = 0;
+  for (const a of ASSETS) {
+    if (existsSync(a.path) && statSync(a.path).size > 0) {
+      skipped++;
+      continue;
+    }
+    const res = await fetch(a.url);
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${a.url}`);
+    writeFileSync(a.path, Buffer.from(await res.arrayBuffer()));
+    fetched++;
+  }
+  console.log(`[gesture] MediaPipe assets ready (${fetched} fetched, ${skipped} cached) → ${GESTURE}`);
+}
+
+main().catch((err) => {
+  // Non-fatal: opt-in feature. Warn and exit 0 so install/build still succeed.
+  console.warn(`[gesture] could not fetch MediaPipe assets — overlay disabled until fetched: ${err.message}`);
+});
@@ -312,6 +312,20 @@ if (isGlobalInstall) {
    }
 }

+// ----------------------------------------------------------------------------
+// 4b. Fetch gesture-overlay runtime assets (MediaPipe wasm + model) for dev mode
+//     (src/web/public/gesture/). Opt-in feature (CODEMAN_GESTURE=1); non-fatal.
+//     Large binaries kept out of git; the build copies them into dist/.
+// ----------------------------------------------------------------------------
+
+if (!isGlobalInstall) {
+    try {
+        execSync(`node "${join(import.meta.dirname, 'fetch-gesture-assets.mjs')}"`, { stdio: 'inherit' });
+    } catch {
+        // Non-fatal — the gesture overlay is opt-in.
+    }
+}
+
 // ----------------------------------------------------------------------------
 // 5. Install git pre-commit hook (format check)
 // ----------------------------------------------------------------------------
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# run-beta.sh — launch a BETA Codeman isolated from a production instance.
+#
+# Codeman's data dir (~/.codeman) and tmux socket (-L codeman) are process-wide
+# and shared by every instance on the machine. The code now DEFAULTS to that
+# production layout on port 3000 (safe for master / existing installs), so a beta
+# build no longer isolates itself automatically — this wrapper opts it in:
+#
+#   CODEMAN_INSTANCE=beta  → data dir ~/.codeman-beta + tmux socket codeman-beta
+#   CODEMAN_PORT=5000      → listen on 5000 instead of 3000
+#
+# Result: the beta runs side-by-side with prod and can never discover/attach to
+# prod's live tmux sessions or clobber prod's state.json. Override either var to
+# run additional named instances, e.g. CODEMAN_INSTANCE=foo CODEMAN_PORT=5050.
+#
+# Usage:  ./scripts/run-beta.sh [extra `codeman web` flags]
+# Build first (the beta runs the compiled dist):  npm run build
+
+set -euo pipefail
+
+export CODEMAN_INSTANCE="${CODEMAN_INSTANCE:-beta}"
+export CODEMAN_PORT="${CODEMAN_PORT:-5000}"
+
+DIST="$(cd "$(dirname "$0")/.." && pwd)/dist/index.js"
+if [ ! -f "$DIST" ]; then
+  echo "dist not found at $DIST — run 'npm run build' first." >&2
+  exit 1
+fi
+
+echo "Starting beta Codeman: instance='$CODEMAN_INSTANCE' (~/.codeman-$CODEMAN_INSTANCE, -L codeman-$CODEMAN_INSTANCE) on port $CODEMAN_PORT"
+exec node "$DIST" web "$@"
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+#
+# span-codeman.sh — open a Codeman window stretched across ALL displays, so that
+# in-page floating session panels can be dragged from one physical monitor to
+# the other. Spawned by the header "multi-monitor" button (POST
+# /api/system/span-displays), or run by hand at the desk.
+#
+# ── PREREQUISITE (one-time, manual) ──────────────────────────────────────────
+# System Settings → Desktop & Dock → turn OFF "Displays have separate Spaces",
+# then LOG OUT and back in. Until you do, macOS keeps every window on a single
+# display and this script's window will clamp to one monitor instead of spanning.
+# (Equivalent CLI: `defaults write com.apple.spaces spans-displays -bool true`,
+#  still needs a re-login. Revert with `-bool false`.)
+#
+# Why a maximized --app window and not fullscreen: browser fullscreen is
+# per-display and will NOT span. We size a windowed app to the union of all
+# displays instead. macOS only.
+#
+set -euo pipefail
+
+URL="${1:-http://localhost:5000}"
+
+# Union rect of all displays in top-left-origin points — exactly what Chromium's
+# --window-position/--window-size expect. Finder's desktop window bounds already
+# encloses every monitor (and handles a monitor placed left/above via a negative
+# origin), so no per-display math or coordinate flipping is needed.
+bounds=$(osascript -e 'tell application "Finder" to get bounds of window of desktop')
+X=$(echo "$bounds" | awk -F', *' '{print $1}')
+Y=$(echo "$bounds" | awk -F', *' '{print $2}')
+R=$(echo "$bounds" | awk -F', *' '{print $3}')
+B=$(echo "$bounds" | awk -F', *' '{print $4}')
+W=$((R - X))
+H=$((B - Y))
+echo "Display union: position ${X},${Y}  size ${W}x${H}"
+
+# Pick a Chromium-family browser. Brave leads the list — plain Google Chrome
+# bounced when launched this way on the desk machine (created its profile then
+# exited without a window). Force a specific one with, e.g.,
+# BROWSER="Google Chrome" ./span-codeman.sh
+app="${BROWSER:-}"
+if [ -z "$app" ]; then
+  for c in "Brave Browser" "Google Chrome" "Google Chrome Beta" "Chromium" "Microsoft Edge"; do
+    [ -x "/Applications/$c.app/Contents/MacOS/$c" ] && app="$c" && break
+  done
+fi
+bin="/Applications/$app.app/Contents/MacOS/$app"
+[ -n "$app" ] && [ -x "$bin" ] || { echo "No Chrome-family browser found (BROWSER='$app')" >&2; exit 1; }
+
+# A dedicated, PER-BROWSER profile forces a FRESH instance — an already-running
+# browser would hand the URL to itself and silently ignore the geometry flags.
+# Per-browser so a Chrome-made profile can't confuse Brave (or vice-versa).
+slug=$(echo "$app" | tr '[:upper:] ' '[:lower:]-')
+profile="$HOME/.codeman-gesture-$slug"
+
+echo "Browser: $bin"
+echo "URL:     $URL"
+
+# Detach so the caller (terminal / web server) isn't blocked for the window's life.
+nohup "$bin" \
+  --app="$URL" \
+  --user-data-dir="$profile" \
+  --window-position="${X},${Y}" \
+  --window-size="${W},${H}" \
+  --no-first-run \
+  --no-default-browser-check \
+  >/dev/null 2>&1 &
+
+echo "Launched spanning window (pid $!)."
+echo "If it filled only one monitor, the 'separate Spaces' prerequisite above"
+echo "isn't active yet — toggle it off, log out/in, and re-run."
@@ -32,6 +32,13 @@ set -e
 CODEMAN_STATE="$HOME/.codeman/state.json"
 CODEMAN_SESSIONS="$HOME/.codeman/mux-sessions.json"

+# Dedicated tmux socket all Codeman sessions live on. MUST match
+# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
+# otherwise list-sessions would enumerate the user's default tmux server
+# (missing the real Codeman sessions, surfacing unrelated ones).
+CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
+TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
+

 # iPhone 17 Pro portrait width (conservative)
 MAX_WIDTH=44
@@ -286,7 +293,7 @@ parse_sessions() {

        # Get PID from tmux
        local pid
-        pid=$(tmux display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")
+        pid=$("${TMUX_CMD[@]}" display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")

        SESSION_PIDS+=("$pid")
        MUX_NAMES+=("$session_name")
@@ -314,7 +321,7 @@ parse_sessions() {
        fi

        i=$((i + 1))
-    done < <(tmux list-sessions 2>/dev/null || true)
+    done < <("${TMUX_CMD[@]}" list-sessions 2>/dev/null || true)
 }

 # ============================================================================
@@ -462,7 +469,7 @@ attach_session() {
    echo -e "${D}(Ctrl+B D to detach)${R}"
    sleep 0.3

-    tmux attach-session -t "$mux_name"
+    "${TMUX_CMD[@]}" attach-session -t "$mux_name"

    return 0
 }
@@ -20,6 +20,13 @@ REVERSE='\033[7m'
 # Use the same path as codeman (src/tmux-manager.ts)
 SESSIONS_FILE="${HOME}/.codeman/mux-sessions.json"

+# Dedicated tmux socket all Codeman sessions live on. MUST match
+# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
+# otherwise this script would talk to the user's default tmux server and never
+# see (or could mis-target) Codeman's sessions.
+CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
+TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
+

 # Cached data
 CACHED_JSON=""
@@ -92,7 +99,7 @@ declare -A ALIVE_CACHE
 check_alive() {
    local mux_name=$1
    if [[ -z "${ALIVE_CACHE[$mux_name]+x}" ]]; then
-        if tmux has-session -t "$mux_name" 2>/dev/null; then
+        if "${TMUX_CMD[@]}" has-session -t "$mux_name" 2>/dev/null; then
            ALIVE_CACHE[$mux_name]=1
        else
            ALIVE_CACHE[$mux_name]=0
@@ -111,8 +118,10 @@ kill_session() {
    local mux_name=$(get_session_field $idx "muxName")
    local pid=$(get_session_field $idx "pid")

-    # SAFETY: Never kill own tmux session
-    local current_session=$(tmux display-message -p '#{session_name}' 2>/dev/null || echo "")
+    # SAFETY: Never kill own tmux session. Queried on the Codeman socket; if run
+    # from a session on a different socket this returns empty (no match), which
+    # is fine — you can't be "inside" a Codeman-socket session you didn't attach to.
+    local current_session=$("${TMUX_CMD[@]}" display-message -p '#{session_name}' 2>/dev/null || echo "")
    if [[ -n "$current_session" && "$mux_name" == "$current_session" ]]; then
        echo -e "${RED}BLOCKED: Cannot kill own tmux session: $mux_name${NC}"
        return 1
@@ -120,7 +129,7 @@ kill_session() {

    pkill -TERM -P $pid 2>/dev/null
    kill -TERM -$pid 2>/dev/null
-    tmux kill-session -t "$mux_name" 2>/dev/null
+    "${TMUX_CMD[@]}" kill-session -t "$mux_name" 2>/dev/null
    kill -KILL $pid 2>/dev/null

    # Remove from JSON
@@ -345,7 +354,7 @@ interactive_menu() {
                        clear
                        echo -e "${CYAN}Attaching... (Ctrl+B D to detach)${NC}"
                        sleep 0.3
-                        tmux attach-session -t "$mux_name"
+                        "${TMUX_CMD[@]}" attach-session -t "$mux_name"
                        tput civis
                        need_full_redraw=1
                        force_refresh
@@ -474,7 +483,7 @@ main() {
            [[ -z "${2:-}" ]] && { echo "Usage: $0 attach <N>"; exit 1; }
            force_refresh
            local mux_name=$(get_session_field $(($2-1)) "muxName")
-            check_alive "$mux_name" && tmux attach-session -t "$mux_name" || echo "Session dead or not found"
+            check_alive "$mux_name" && "${TMUX_CMD[@]}" attach-session -t "$mux_name" || echo "Session dead or not found"
            ;;
        kill)
            [[ -z "${2:-}" ]] && { echo "Usage: $0 kill <N|N,M|N-M>"; exit 1; }
@@ -492,8 +501,8 @@ main() {
            ;;
        kill-all)
            force_refresh
-            # SAFETY: Never kill own tmux session
-            local current_session=$(tmux display-message -p '#{session_name}' 2>/dev/null || echo "")
+            # SAFETY: Never kill own tmux session (queried on the Codeman socket)
+            local current_session=$("${TMUX_CMD[@]}" display-message -p '#{session_name}' 2>/dev/null || echo "")
            local killed=0
            for ((i=CACHED_COUNT-1; i>=0; i--)); do
                local mux_name=$(get_session_field $i "muxName")
@@ -64,20 +64,27 @@ const DEFAULT_PLAN_CHECK_CONFIG: AiPlanCheckConfig = {
 const VERDICT_PATTERN = /^\s*(PLAN_MODE|NOT_PLAN_MODE)\b/i;

 /** The prompt sent to the AI plan checker */
-const AI_PLAN_CHECK_PROMPT = `Analyze this terminal output from a running Claude Code session. Determine if the terminal is currently showing a PLAN MODE APPROVAL PROMPT or not.
+const AI_PLAN_CHECK_PROMPT = `Analyze this terminal output from a running Claude Code session. Determine if the terminal is currently showing a NUMBERED SELECTION MENU that is waiting for the user to press Enter on the highlighted default option.

-A plan mode approval prompt is a numbered selection menu that Claude Code shows when it wants the user to approve a plan before proceeding. It typically has these characteristics:
+A qualifying menu has all of these characteristics:
 - A numbered list of options (e.g., "1. Yes", "2. No", "3. Type your own")
- A selection indicator arrow (❯ or >) pointing to one of the options
- Text asking for approval like "Would you like to proceed?" or "Ready to implement?"
- The prompt appears at the BOTTOM of the output (most recent content)
+- A selection indicator arrow (❯ or >) pointing to one of the options (the default)
+- The menu appears at the BOTTOM of the output (most recent content)
+- It is asking the user to choose, not just displaying numbered information

-NOT a plan mode prompt:
+This includes BOTH:
+- Plan-mode approval prompts ("Would you like to proceed?" / "Ready to implement?")
+- AskUserQuestion / elicitation dialogs (Claude Code's numbered question menus)
+
+NOT a qualifying menu:
 - Claude actively working (spinners, "Thinking", tool execution)
- A completed response with no selection menu
- An AskUserQuestion/elicitation dialog (different format, free-text input)
+- A completed response with no selection menu visible
+- A free-text input field with no numbered options
+- A numbered LIST in the assistant's prose with no selection arrow
 - Network lag or mid-output pause
- Any state without a visible numbered selection menu
+- Any state without a visible selector arrow on a numbered option
+
+The verdict name PLAN_MODE is historical — it now means "auto-accept this selection menu by pressing Enter on the default".

 Terminal output (most recent at bottom):
 ---
@@ -483,7 +483,7 @@ program
 program
  .command('web')
  .description('Start the web interface')
-  .option('-p, --port <port>', 'Port to listen on', '3000')
+  .option('-p, --port <port>', 'Port to listen on (env: CODEMAN_PORT)', process.env.CODEMAN_PORT || '3000')
  .option('--https', 'Enable HTTPS with self-signed certificate (only needed for remote access, not localhost)')
  .option('--title-hostname <hostname>', 'Override the hostname shown in the browser title')
  .action(async (options) => {
@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Per-instance isolation: data directory + tmux socket.
+ *
+ * Codeman keeps all runtime state under `~/.codeman` and runs its tmux sessions
+ * on a dedicated socket (`tmux -L codeman`). Both are PROCESS-WIDE and SHARED by
+ * every Codeman instance on the machine — so a second instance pointed at the
+ * same socket will discover and attach to the first instance's live sessions,
+ * and two instances sharing `~/.codeman/state.json` will clobber each other.
+ *
+ * To let a beta build coexist with a production one, this module derives both
+ * the data dir and the tmux socket from a single "instance" name:
+ *   - default (unset/empty) → `~/.codeman`      + `tmux -L codeman`        (prod layout)
+ *   - `CODEMAN_INSTANCE=beta` → `~/.codeman-beta` + `tmux -L codeman-beta`
+ *   - `CODEMAN_INSTANCE=foo`  → `~/.codeman-foo`  + `tmux -L codeman-foo`
+ *
+ * The DEFAULT is the production layout so this is safe to ship to master: an
+ * existing install keeps reading `~/.codeman`. To run a beta ALONGSIDE prod,
+ * launch it with `CODEMAN_INSTANCE=beta` (and a distinct port, see below) —
+ * `scripts/run-beta.sh` does both. The port is unrelated to the instance and is
+ * set separately via `--port` / `CODEMAN_PORT` (see `src/cli.ts`).
+ *
+ * Individual overrides still win: `CODEMAN_DATA_DIR` (absolute data dir) and
+ * `CODEMAN_TMUX_SOCKET` (socket name, validated in tmux-manager).
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+/**
+ * Instance name. Empty string (the default) = production layout (`~/.codeman`,
+ * `-L codeman`), so this is safe on master and existing installs are untouched.
+ * Set `CODEMAN_INSTANCE=beta` (e.g. via `scripts/run-beta.sh`) to run an
+ * isolated beta alongside prod.
+ */
+export const CODEMAN_INSTANCE = process.env.CODEMAN_INSTANCE ?? '';
+
+const INSTANCE_SUFFIX = CODEMAN_INSTANCE ? `-${CODEMAN_INSTANCE}` : '';
+
+/** Default tmux socket for this instance. `CODEMAN_TMUX_SOCKET` still overrides. */
+export const DEFAULT_TMUX_SOCKET = `codeman${INSTANCE_SUFFIX}`;
+
+let _ensured = false;
+
+/**
+ * Absolute path to this instance's data directory (created on first use). All
+ * persisted state (`state.json`, `mux-sessions.json`, settings, push keys,
+ * lifecycle log, screenshots, certs, …) lives here.
+ */
+export function getDataDir(): string {
+  const dir = process.env.CODEMAN_DATA_DIR || join(homedir(), `.codeman${INSTANCE_SUFFIX}`);
+  if (!_ensured) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      _ensured = true;
+    } catch {
+      /* best-effort; individual writers also mkdir as needed */
+    }
+  }
+  return dir;
+}
+
+/** Join one or more segments onto this instance's data directory. */
+export function dataPath(...segments: string[]): string {
+  return join(getDataDir(), ...segments);
+}
@@ -14,6 +14,7 @@ import type {
  ClaudeMode,
  SessionMode,
  OpenCodeConfig,
+  EffortLevel,
 } from './types.js';

 /**
@@ -63,8 +64,10 @@ export interface CreateSessionOptions {
  openCodeConfig?: OpenCodeConfig;
  /** When restoring after reboot, resume a previous Claude conversation by its session ID */
  resumeSessionId?: string;
-  /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EFFORT_LEVEL). Ephemeral — not written to disk. */
+  /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
  envOverrides?: Record<string, string>;
+  /** Claude CLI effort level, injected as a `--settings` soft default (overridable via /effort in-session) */
+  effort?: EffortLevel;
 }

 /** Options for respawning a dead pane. */
@@ -81,6 +84,8 @@ export interface RespawnPaneOptions {
  resumeSessionId?: string;
  /** Extra env vars exported before launching the CLI (preserved across respawns). */
  envOverrides?: Record<string, string>;
+  /** Claude CLI effort level (preserved across respawns, injected via `--settings`) */
+  effort?: EffortLevel;
 }

 /**
@@ -98,6 +103,9 @@ export interface TerminalMultiplexer extends EventEmitter {
  /** Which backend this instance uses */
  readonly backend: 'tmux';

+  /** The dedicated tmux socket name all sessions live on (e.g. "codeman"). */
+  readonly muxSocket: string;
+
  // ========== Lifecycle ==========

  /**
@@ -8,12 +8,12 @@

 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import webpush from 'web-push';
 import type { VapidKeys, PushSubscriptionRecord } from './types.js';
 import { Debouncer } from './utils/index.js';
+import { getDataDir } from './config/instance.js';

-const DATA_DIR = join(homedir(), '.codeman');
+const DATA_DIR = getDataDir();
 const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
 const SUBS_FILE = join(DATA_DIR, 'push-subscriptions.json');
 const SAVE_DEBOUNCE_MS = 500;
@@ -513,7 +513,7 @@ const DEFAULT_CONFIG: RespawnConfig = {
  sendInit: true, // send /init after /clear
  completionConfirmMs: 10000, // 10 seconds of silence after completion message
  noOutputTimeoutMs: 30000, // 30 seconds fallback if no output at all
-  autoAcceptPrompts: true, // auto-accept plan mode prompts (not questions)
+  autoAcceptPrompts: true, // auto-accept numbered selection menus (plan approvals + question dialogs)
  autoAcceptDelayMs: 8000, // 8 seconds before auto-accepting
  aiIdleCheckEnabled: true, // use AI to confirm idle state
  aiIdleCheckModel: AI_CHECK_MODEL,
@@ -623,9 +623,6 @@ export class RespawnController extends EventEmitter {
  /** Whether any terminal output has been received since start/last-auto-accept */
  private hasReceivedOutput: boolean = false;

-  /** Whether an elicitation dialog (AskUserQuestion) was detected via hook signal */
-  private elicitationDetected: boolean = false;
-
  // ========== Hook-Based Detection State (Layer 0 - Highest Priority) ==========

  /** Whether a Stop hook was received (definitive idle signal from Claude Code) */
@@ -1369,7 +1366,12 @@ export class RespawnController extends EventEmitter {
    this.clearWorkingPatternWindow();
    this.workingDetected = false;
    this.completionMessageTime = now;
-    this.cancelAutoAcceptTimer(); // Normal idle flow handles this
+    // Don't cancel the auto-accept timer here — modern Claude Code emits "Worked for X"
+    // immediately before a plan-approval menu, and the auto-accept pre-filter is
+    // responsible for distinguishing menu-present from menu-absent. Cancelling here
+    // would silently block auto-accept for every plan approval and AskUserQuestion
+    // dialog. If no menu is in the buffer, the pre-filter rejects and the
+    // completion-confirm timer (started below) drives the normal idle flow.
    this.log(`Completion message detected: "${data.trim().substring(0, 50)}..."`);

    // In watching state, start completion confirmation timer
@@ -1417,7 +1419,6 @@ export class RespawnController extends EventEmitter {

    this.workingDetected = true;
    this.promptDetected = false;
-    this.elicitationDetected = false; // Clear on new work cycle
    this.resetHookState(); // Clear hook signals on new work
    this.lastWorkingPatternTime = now;

@@ -2222,11 +2223,11 @@ export class RespawnController extends EventEmitter {
   * @returns True if auto-accept should proceed to the AI confirmation stage
   */
  private canAutoAccept(): boolean {
-    // Only auto-accept in watching state (not during a respawn cycle)
-    if (this._state !== 'watching') return false;
-
-    // Don't auto-accept if a completion message was detected (normal idle handles it)
-    if (this.completionMessageTime !== null) return false;
+    // Allow auto-accept from 'watching' AND 'confirming_idle'. The latter is reached
+    // when "Worked for X" was detected — which Claude Code now emits in the same PTY
+    // burst as a plan-approval menu. `sendAutoAcceptEnter()` self-transitions back to
+    // 'watching' before sending Enter. Reject any other state (respawn cycle, etc.).
+    if (this._state !== 'watching' && this._state !== 'confirming_idle') return false;

    // Don't auto-accept if disabled
    if (!this.config.autoAcceptPrompts) return false;
@@ -2234,15 +2235,15 @@ export class RespawnController extends EventEmitter {
    // Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
    if (!this.hasReceivedOutput) return false;

-    // Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
-    if (this.elicitationDetected) {
-      this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
-      return false;
-    }
+    // Note: completionMessageTime and elicitationDetected used to block here, but both
+    // legitimately co-occur with selection menus (Claude Code emits "Worked for X"
+    // before plan approvals, and AskUserQuestion fires the elicitation hook). The
+    // pre-filter below is the authoritative gate for "is there a numbered menu?".

-    // Stage 1: Pre-filter — check if buffer looks like plan mode
+    // Stage 1: Pre-filter — check if buffer looks like a numbered selection menu
+    // (covers both plan-mode approvals and AskUserQuestion dialogs)
    if (!this.isPlanModePreFilterMatch(this.terminalBuffer.value)) {
-      this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
+      this.log('Skipping auto-accept: pre-filter did not match selection-menu patterns');
      return false;
    }

@@ -2308,8 +2309,10 @@ export class RespawnController extends EventEmitter {
        }

        if (result.verdict === 'PLAN_MODE') {
-          // Don't send Enter if state changed (e.g., AI idle check started or respawn cycle began)
-          if (this._state !== 'watching') {
+          // Don't send Enter if state moved into a respawn cycle while the check ran.
+          // 'watching' and 'confirming_idle' are both valid — sendAutoAcceptEnter()
+          // self-transitions to 'watching' before sending.
+          if (this._state !== 'watching' && this._state !== 'confirming_idle') {
            this.logAction('plan-check', `Verdict: PLAN_MODE but state is ${this._state}, not sending Enter`);
            return;
          }
@@ -2368,13 +2371,18 @@ export class RespawnController extends EventEmitter {

  /**
   * Signal that an elicitation dialog (AskUserQuestion) was detected via hook.
-   * This prevents auto-accept from firing, since the user needs to make a selection.
-   * The flag is cleared when working patterns are detected (new turn starts).
+   * Used as a positive hint that a numbered selection menu is about to render —
+   * we restart the auto-accept timer so the pre-filter gets a fresh shot at it
+   * once the menu finishes drawing. The actual gate is `isPlanModePreFilterMatch()`
+   * plus (optionally) the AI plan check; this hook just primes the timer.
+   * No-op if respawn isn't `'watching'`/`'confirming_idle'` or `autoAcceptPrompts`
+   * is off, so this can never fire Enter when the user has disabled auto-accept.
   */
  signalElicitation(): void {
-    this.elicitationDetected = true;
-    this.cancelAutoAcceptTimer();
-    this.log('Elicitation dialog signaled - auto-accept blocked until next work cycle');
+    this.log('Elicitation dialog signaled - auto-accept will trigger if pre-filter matches');
+    if (this.config.autoAcceptPrompts && (this._state === 'watching' || this._state === 'confirming_idle')) {
+      this.startAutoAcceptTimer();
+    }
  }

  /**
@@ -8,7 +8,8 @@
 * @module session-cli-builder
 */

-import type { ClaudeMode } from './types.js';
+import type { ClaudeMode, EffortLevel } from './types.js';
+import { isEffortLevel } from './types.js';
 import { getAugmentedPath } from './utils/index.js';

 /**
@@ -31,6 +32,23 @@ function buildPermissionArgs(claudeMode: ClaudeMode, allowedTools?: string): str
  }
 }

+/**
+ * Build the CLI args carrying the effort level as a SOFT default (switchable
+ * in-session via /effort). The CLAUDE_CODE_EFFORT_LEVEL env var is deliberately
+ * avoided — it hard-locks effort and blocks in-session `/effort` switching.
+ *
+ * Two carriers are needed because neither covers all levels:
+ * - regular levels (incl. `max`) → `--effort <level>` (the settings `effortLevel`
+ *   key is enum(["low","medium","high","xhigh"]) with .catch(undefined), so `max`
+ *   would be SILENTLY dropped there)
+ * - `ultracode` → `--settings '{"ultracode":true}'` (its own boolean settings key,
+ *   claude >= 2.1.154; rejected by the --effort flag)
+ */
+export function buildEffortCliArgs(effort?: EffortLevel): string[] {
+  if (!effort || !isEffortLevel(effort)) return [];
+  return effort === 'ultracode' ? ['--settings', '{"ultracode":true}'] : ['--effort', effort];
+}
+
 /**
 * Build args for an interactive Claude CLI session (direct PTY, non-mux fallback).
 *
@@ -38,16 +56,19 @@ function buildPermissionArgs(claudeMode: ClaudeMode, allowedTools?: string): str
 * @param claudeMode - Permission mode for the CLI
 * @param model - Optional model override (e.g., 'opus', 'sonnet')
 * @param allowedTools - Optional comma-separated allowed tools list
+ * @param effort - Optional effort level, injected via --settings (overridable in-session)
 * @returns Array of CLI arguments
 */
 export function buildInteractiveArgs(
  sessionId: string,
  claudeMode: ClaudeMode,
  model?: string,
-  allowedTools?: string
+  allowedTools?: string,
+  effort?: EffortLevel
 ): string[] {
  const args = [...buildPermissionArgs(claudeMode, allowedTools), '--session-id', sessionId];
  if (model) args.push('--model', model);
+  args.push(...buildEffortCliArgs(effort));
  return args;
 }

@@ -10,9 +10,9 @@

 import { appendFile, readFile, writeFile } from 'node:fs/promises';
 import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { dirname } from 'node:path';
 import type { LifecycleEventType, LifecycleEntry } from './types.js';
+import { dataPath } from './config/instance.js';

 const MAX_LINES = 10_000;
 const TRIM_TO = 8_000;
@@ -22,7 +22,7 @@ export class SessionLifecycleLog {
  private writeQueue: Promise<void> = Promise.resolve();

  constructor(filePath?: string) {
-    this.filePath = filePath || join(homedir(), '.codeman', 'session-lifecycle.jsonl');
+    this.filePath = filePath || dataPath('session-lifecycle.jsonl');
    const dir = dirname(this.filePath);
    if (!existsSync(dir)) {
      mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -42,9 +42,11 @@ import {
  NiceConfig,
  DEFAULT_NICE_CONFIG,
  getErrorMessage,
+  isEffortLevel,
  type ClaudeMode,
  type SessionMode,
  type OpenCodeConfig,
+  type EffortLevel,
 } from './types.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
 import { TaskTracker, type BackgroundTask } from './task-tracker.js';
@@ -133,15 +135,22 @@ const TMUX_DISPLAY_TIMEOUT_MS = 2000;
 * (tmux dead, muxName unknown, malformed output) — caller never has to
 * differentiate "tmux unreachable" from "size 120x40".
 *
+ * `socket` MUST be the same dedicated socket the session lives on (`mux.muxSocket`);
+ * querying the default server would never find the session and silently fall back.
+ *
 * Argv form (execFileSync, not execSync) keeps `muxName` out of any shell so
 * a hostile session name can't inject options.
 */
-export function queryTmuxWindowSize(muxName: string): { cols: number; rows: number } {
+export function queryTmuxWindowSize(muxName: string, socket: string): { cols: number; rows: number } {
  try {
-    const sizeStr = execFileSync('tmux', ['display', '-t', muxName, '-p', '#{window_width} #{window_height}'], {
-      timeout: TMUX_DISPLAY_TIMEOUT_MS,
-      encoding: 'utf8',
-    }).trim();
+    const sizeStr = execFileSync(
+      'tmux',
+      ['-L', socket, 'display', '-t', muxName, '-p', '#{window_width} #{window_height}'],
+      {
+        timeout: TMUX_DISPLAY_TIMEOUT_MS,
+        encoding: 'utf8',
+      }
+    ).trim();
    const [w, h] = sizeStr.split(' ').map(Number);
    if (w > 0 && h > 0) {
      return { cols: w, rows: h };
@@ -304,10 +313,15 @@ export class Session extends EventEmitter {
  private _openCodeConfig: OpenCodeConfig | undefined;
  private _resumeSessionId: string | undefined;

-  // Ephemeral env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL). Exported by tmux at spawn,
-  // preserved across respawns via persisted state. Not written to .claude/settings.local.json.
+  // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
+  // at spawn, preserved across respawns via persisted state. Not written to .claude/settings.local.json.
  private _envOverrides: Record<string, string> | undefined;

+  // Claude CLI effort level — injected as a `--settings` soft default at spawn so the
+  // user can still switch in-session via /effort (incl. ultracode). Never carried as
+  // the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session.
+  private _effort: EffortLevel | undefined;
+
  // Session color for visual differentiation
  private _color: import('./types.js').SessionColor = 'default';

@@ -369,6 +383,8 @@ export class Session extends EventEmitter {
      resumeSessionId?: string;
      /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
      envOverrides?: Record<string, string>;
+      /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
+      effort?: EffortLevel;
    }
  ) {
    super();
@@ -416,9 +432,19 @@ export class Session extends EventEmitter {
      this._openCodeConfig = config.openCodeConfig;
    }

-    // Apply env overrides (exported at spawn, not persisted to disk)
+    // Apply env overrides (exported at spawn, not persisted to disk).
+    // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
+    // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
+    // and never export it as an env var again. Explicit config.effort wins over legacy.
    if (config.envOverrides && Object.keys(config.envOverrides).length > 0) {
-      this._envOverrides = { ...config.envOverrides };
+      const { CLAUDE_CODE_EFFORT_LEVEL: legacyEffort, ...restOverrides } = config.envOverrides;
+      this._envOverrides = Object.keys(restOverrides).length > 0 ? restOverrides : undefined;
+      if (legacyEffort && isEffortLevel(legacyEffort)) {
+        this._effort = legacyEffort;
+      }
+    }
+    if (config.effort && isEffortLevel(config.effort)) {
+      this._effort = config.effort;
    }

    // Initialize task tracker and forward events (store handlers for cleanup)
@@ -840,6 +866,7 @@ export class Session extends EventEmitter {
      cliLatestVersion: this._cliLatestVersion || undefined,
      openCodeConfig: this._openCodeConfig,
      resumeSessionId: this._resumeSessionId,
+      effort: this._effort,
      // envOverrides intentionally NOT on the public SessionState type — they must not
      // leak into SSE / GET /api/sessions broadcasts (schema allows OPENCODE_*, which
      // can carry secrets). For disk persistence, session-manager calls
@@ -978,7 +1005,7 @@ export class Session extends EventEmitter {

    // Attach to the mux session via PTY
    // Query existing tmux window size so re-attach matches (avoids flicker from 120x40 default)
-    const { cols: ptyCols, rows: ptyRows } = queryTmuxWindowSize(this._muxSession!.muxName);
+    const { cols: ptyCols, rows: ptyRows } = queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
    try {
      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
        name: 'xterm-256color',
@@ -1031,6 +1058,7 @@ export class Session extends EventEmitter {
            openCodeConfig: this._openCodeConfig,
            resumeSessionId: this._resumeSessionId,
            envOverrides: this._envOverrides,
+            effort: this._effort,
          },
          createSessionOptions: {
            sessionId: this.id,
@@ -1044,6 +1072,7 @@ export class Session extends EventEmitter {
            openCodeConfig: this._openCodeConfig,
            resumeSessionId: this._resumeSessionId,
            envOverrides: this._envOverrides,
+            effort: this._effort,
          },
          spawnErrLabel: 'mux attachment',
        });
@@ -1113,7 +1142,7 @@ export class Session extends EventEmitter {
      try {
        // Pass --session-id to use the SAME ID as the Codeman session
        // This ensures subagents can be directly matched to the correct tab
-        const args = buildInteractiveArgs(this.id, this._claudeMode, this._model, this._allowedTools);
+        const args = buildInteractiveArgs(this.id, this._claudeMode, this._model, this._allowedTools, this._effort);
        this.ptyProcess = pty.spawn('claude', args, {
          name: 'xterm-256color',
          cols: 120,
@@ -39,6 +39,7 @@ import {
  TokenUsageEntry,
 } from './types.js';
 import { Debouncer, MAX_SESSION_TOKENS } from './utils/index.js';
+import { dataPath, CODEMAN_INSTANCE } from './config/instance.js';

 /** Debounce delay for batching state writes (ms) */
 const SAVE_DEBOUNCE_MS = 500;
@@ -89,8 +90,10 @@ export class StateStore {
  private _saveInFlight: Promise<void> | null = null;

  constructor(filePath?: string) {
-    // Migrate legacy data directory (~/.claudeman → ~/.codeman)
-    if (!filePath) {
+    // Migrate legacy data directory (~/.claudeman → ~/.codeman). Default (prod)
+    // instance only — a named instance (e.g. beta) must never touch the shared
+    // ~/.codeman / ~/codeman-cases layout, preserving instance isolation.
+    if (!filePath && !CODEMAN_INSTANCE) {
      const legacyDir = join(homedir(), '.claudeman');
      const newDir = join(homedir(), '.codeman');
      if (existsSync(legacyDir) && !existsSync(newDir)) {
@@ -105,7 +108,7 @@ export class StateStore {
      }
    }

-    this.filePath = filePath || join(homedir(), '.codeman', 'state.json');
+    this.filePath = filePath || dataPath('state.json');
    this.ralphStatePath = this.filePath.replace('.json', '-inner.json');
    this.state = this.load();
    this.state.config.stateFilePath = this.filePath;
@@ -28,8 +28,8 @@ import { promisify } from 'node:util';
 const execAsync = promisify(exec);
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { writeFile, rename } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { dataPath, DEFAULT_TMUX_SOCKET } from './config/instance.js';
 import {
  ProcessStats,
  PersistedRespawnConfig,
@@ -39,7 +39,9 @@ import {
  type ClaudeMode,
  type SessionMode,
  type OpenCodeConfig,
+  type EffortLevel,
 } from './types.js';
+import { buildEffortCliArgs } from './session-cli-builder.js';
 import { wrapWithNice, SAFE_PATH_PATTERN, findClaudeDir, resolveOpenCodeDir } from './utils/index.js';
 import type {
  TerminalMultiplexer,
@@ -71,6 +73,9 @@ const GRACEFUL_SHUTDOWN_WAIT_MS = 100;
 /** Default stats collection interval (2 seconds) */
 const DEFAULT_STATS_INTERVAL_MS = 2000;

+/** Claude Code native macOS recommendation for avoiding low nofile startup failures. */
+export const CLAUDE_CODE_NOFILE_LIMIT = 2147483646;
+
 /**
 * SAFETY: Test mode detection.
 * When running under vitest (VITEST env var is set automatically),
@@ -87,7 +92,7 @@ const DEFAULT_STATS_INTERVAL_MS = 2000;
 const IS_TEST_MODE = !!process.env.VITEST;

 /** Path to persisted mux session metadata */
-const MUX_SESSIONS_FILE = join(homedir(), '.codeman', 'mux-sessions.json');
+const MUX_SESSIONS_FILE = dataPath('mux-sessions.json');

 /** Regex to validate tmux session names (only allow safe characters) */
 const SAFE_MUX_NAME_PATTERN = /^codeman-[a-f0-9-]+$/;
@@ -98,6 +103,13 @@ const LEGACY_MUX_NAME_PATTERN = /^claudeman-[a-f0-9-]+$/;
 /** Regex to validate tmux pane targets (e.g., "%0", "%1", "0", "1") */
 const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;

+/** Dedicated tmux socket for new Codeman-owned sessions (instance-scoped:
+ *  `codeman` for prod, `codeman-beta` on the beta branch). */
+const DEFAULT_CODEMAN_TMUX_SOCKET = DEFAULT_TMUX_SOCKET;
+
+/** Regex to validate tmux socket names passed to `tmux -L`. */
+const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+
 /**
 * Separator used in `tmux list-panes -F` output between session name and pid.
 *
@@ -114,6 +126,19 @@ const PANE_LIST_SEP = '|';
 /** Format string for `tmux list-panes -F`. Keep in sync with {@link parsePaneList}. */
 const PANE_LIST_FORMAT = `#{session_name}${PANE_LIST_SEP}#{pane_pid}`;

+/**
+ * 构建 pane 启动前的 nofile 修复命令。
+ *
+ * macOS launchd/tmux 组合有时会让 pane 继承 256 的 soft nofile；
+ * 新版 Claude Code 会在这种环境下直接退出。这里避免使用 $变量
+ * 或命令替换，因为 fullCmd 目前经由双引号 bash -c 传递，外层
+ * shell 会提前展开它们。
+ */
+export function buildNofileLimitCommand(targetLimit = CLAUDE_CODE_NOFILE_LIMIT): string {
+  const safeLimit = Number.isSafeInteger(targetLimit) && targetLimit > 0 ? targetLimit : CLAUDE_CODE_NOFILE_LIMIT;
+  return `ulimit -Sn ${safeLimit} 2>/dev/null || ulimit -n ${safeLimit} 2>/dev/null || true`;
+}
+
 /**
 * Parse the output of `tmux list-panes -a -F '#{session_name}|#{pane_pid}'`
 * into a Map of session-name → pane pid. Exported for unit testing.
@@ -161,6 +186,31 @@ function isValidPath(path: string): boolean {
  return SAFE_PATH_PATTERN.test(path);
 }

+// ===========================================================================
+// Single-socket architecture: ALL Codeman sessions live on one dedicated tmux
+// socket (`tmux -L codeman`), isolated from the user's default tmux server.
+// The socket name is a process-wide constant (env-overridable for test/multi-
+// instance isolation) — it is never stored per-session, so it cannot drift.
+// ===========================================================================
+
+/**
+ * Resolve the process-wide Codeman tmux socket name. Always returns a valid
+ * name: `CODEMAN_TMUX_SOCKET` env override if safe, else the built-in default.
+ */
+function resolveConfiguredTmuxSocket(): string {
+  const raw = process.env.CODEMAN_TMUX_SOCKET ?? DEFAULT_CODEMAN_TMUX_SOCKET;
+  if (!SAFE_TMUX_SOCKET_PATTERN.test(raw)) {
+    console.warn(`[TmuxManager] Ignoring invalid CODEMAN_TMUX_SOCKET: ${JSON.stringify(raw)}`);
+    return DEFAULT_CODEMAN_TMUX_SOCKET;
+  }
+  return raw;
+}
+
+/** Build the `tmux -L <socket>` command prefix. Socket name is shell-escaped. */
+function tmuxCommand(socket: string): string {
+  return `tmux -L ${shellescape(socket)}`;
+}
+
 /**
 * Build Claude CLI permission flags for the tmux command string.
 * Validates allowedTools to prevent command injection.
@@ -212,6 +262,20 @@ function buildOpenCodeCommand(config?: OpenCodeConfig): string {
 * Build the spawn command for any session mode.
 * Shared by createSession() and respawnPane() to avoid duplication.
 */
+/**
+ * Build the shell fragment carrying the effort level as a SOFT default
+ * (see buildEffortCliArgs — `--effort <level>` for regular levels incl. max,
+ * `--settings '{"ultracode":true}'` for ultracode; deliberately not the
+ * CLAUDE_CODE_EFFORT_LEVEL env var, which hard-locks /effort switching).
+ *
+ * Injection-safe: effort is validated against the EFFORT_LEVELS allowlist inside
+ * buildEffortCliArgs, so the single-quoted values contain no user-controlled characters.
+ */
+function buildEffortSettingsFlag(effort?: EffortLevel): string {
+  const [flag, value] = buildEffortCliArgs(effort);
+  return flag && value ? ` ${flag} '${value}'` : '';
+}
+
 function buildSpawnCommand(options: {
  mode: SessionMode;
  sessionId: string;
@@ -220,11 +284,13 @@ function buildSpawnCommand(options: {
  allowedTools?: string;
  openCodeConfig?: OpenCodeConfig;
  resumeSessionId?: string;
+  effort?: EffortLevel;
 }): string {
  if (options.mode === 'claude') {
    // Validate model to prevent command injection
    const safeModel = options.model && /^[a-zA-Z0-9._\-[\]]+$/.test(options.model) ? options.model : undefined;
    const modelFlag = safeModel ? ` --model "${safeModel}"` : '';
+    const effortFlag = buildEffortSettingsFlag(options.effort);
    // Use --resume to restore a previous conversation, otherwise --session-id for new sessions.
    // Wrap --resume in a fallback: if it exits non-zero (session not found, corrupt, etc.),
    // fall back to a new session with --session-id so the pane doesn't die.
@@ -232,11 +298,11 @@ function buildSpawnCommand(options: {
      options.resumeSessionId && /^[a-f0-9-]+$/.test(options.resumeSessionId) ? options.resumeSessionId : undefined;
    const permFlags = buildClaudePermissionFlags(options.claudeMode, options.allowedTools);
    if (safeResumeId) {
-      const resumeCmd = `claude${permFlags} --resume "${safeResumeId}"${modelFlag}`;
-      const fallbackCmd = `claude${permFlags} --session-id "${options.sessionId}"${modelFlag}`;
+      const resumeCmd = `claude${permFlags} --resume "${safeResumeId}"${modelFlag}${effortFlag}`;
+      const fallbackCmd = `claude${permFlags} --session-id "${options.sessionId}"${modelFlag}${effortFlag}`;
      return `${resumeCmd} || ${fallbackCmd}`;
    }
-    return `claude${permFlags} --session-id "${options.sessionId}"${modelFlag}`;
+    return `claude${permFlags} --session-id "${options.sessionId}"${modelFlag}${effortFlag}`;
  }
  if (options.mode === 'opencode') {
    return buildOpenCodeCommand(options.openCodeConfig);
@@ -248,7 +314,7 @@ function buildSpawnCommand(options: {
 * Set sensitive environment variables on a tmux session via setenv.
 * These are inherited by panes but not visible in ps output or tmux history.
 */
-function setOpenCodeEnvVars(muxName: string): void {
+function setOpenCodeEnvVars(tmuxCmd: string, muxName: string): void {
  const sensitiveVars = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GOOGLE_API_KEY'];
  for (const key of sensitiveVars) {
    const val = process.env[key];
@@ -256,7 +322,7 @@ function setOpenCodeEnvVars(muxName: string): void {
      // Shell-escape: wrap in single quotes, escape any inner single quotes
      const escaped = val.replace(/'/g, "'\\''");
      try {
-        execSync(`tmux setenv -t '${muxName}' ${key} '${escaped}'`, {
+        execSync(`${tmuxCmd} setenv -t '${muxName}' ${key} '${escaped}'`, {
          encoding: 'utf8',
          timeout: EXEC_TIMEOUT_MS,
          stdio: ['pipe', 'pipe', 'pipe'],
@@ -272,7 +338,7 @@ function setOpenCodeEnvVars(muxName: string): void {
 * Set OPENCODE_CONFIG_CONTENT on a tmux session via setenv.
 * Uses tmux setenv to avoid shell metacharacter injection from user-supplied JSON.
 */
-function setOpenCodeConfigContent(muxName: string, config?: OpenCodeConfig): void {
+function setOpenCodeConfigContent(tmuxCmd: string, muxName: string, config?: OpenCodeConfig): void {
  if (!config) return;

  let jsonContent: string | undefined;
@@ -303,7 +369,7 @@ function setOpenCodeConfigContent(muxName: string, config?: OpenCodeConfig): voi
  if (jsonContent) {
    const escaped = jsonContent.replace(/'/g, "'\\''");
    try {
-      execSync(`tmux setenv -t '${muxName}' OPENCODE_CONFIG_CONTENT '${escaped}'`, {
+      execSync(`${tmuxCmd} setenv -t '${muxName}' OPENCODE_CONFIG_CONTENT '${escaped}'`, {
        encoding: 'utf8',
        timeout: EXEC_TIMEOUT_MS,
        stdio: ['pipe', 'pipe', 'pipe'],
@@ -336,6 +402,7 @@ function setOpenCodeConfigContent(muxName: string, config?: OpenCodeConfig): voi
 export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
  readonly backend = 'tmux' as const;
  private sessions: Map<string, MuxSession> = new Map();
+  private readonly tmuxSocket = resolveConfiguredTmuxSocket();
  private statsInterval: NodeJS.Timeout | null = null;
  private mouseSyncInterval: NodeJS.Timeout | null = null;
  /** Track last-known pane count per session to avoid unnecessary tmux set-option calls */
@@ -351,6 +418,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }
  }

+  /** The dedicated tmux socket all Codeman sessions live on (see {@link TerminalMultiplexer.muxSocket}). */
+  get muxSocket(): string {
+    return this.tmuxSocket;
+  }
+
+  private tmux(): string {
+    return tmuxCommand(this.tmuxSocket);
+  }
+
  // Load saved sessions from disk (NEVER called in test mode)
  private loadSessions(): void {
    if (IS_TEST_MODE) return;
@@ -360,8 +436,40 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
        const content = readFileSync(MUX_SESSIONS_FILE, 'utf-8');
        const data = JSON.parse(content);
        if (Array.isArray(data)) {
+          // Dedup by muxName: one live tmux session must map to exactly one
+          // tracked entry. A per-session socket-tag mismatch could historically
+          // let the same session be tracked twice — once under its real UUID and
+          // once under a "restored-<id>" placeholder — surfacing as duplicate tabs.
+          // Single-socket unification removed that failure mode; this pass stays
+          // to clean any stale duplicates already on disk. Keep the real (UUID)
+          // entry and drop placeholder twins.
+          let dropped = 0;
+          const keptByMuxName = new Map<string, string>(); // muxName -> kept sessionId
          for (const session of data) {
+            // Strip the obsolete per-session tmuxSocket tag (now a process-wide
+            // constant). Left in place it would be written back by saveSessions()
+            // and linger on disk as a zombie field forever.
+            delete (session as { tmuxSocket?: unknown }).tmuxSocket;
+            const muxName: string | undefined = session.muxName;
+            const priorId = muxName ? keptByMuxName.get(muxName) : undefined;
+            if (priorId) {
+              const incomingIsPlaceholder = String(session.sessionId).startsWith('restored-');
+              const priorIsPlaceholder = priorId.startsWith('restored-');
+              // Drop the incoming unless it's the real twin of a placeholder we kept.
+              if (incomingIsPlaceholder || !priorIsPlaceholder) {
+                dropped++;
+                continue;
+              }
+              this.sessions.delete(priorId);
+              dropped++;
+            }
            this.sessions.set(session.sessionId, session);
+            if (muxName) keptByMuxName.set(muxName, session.sessionId);
+          }
+          // Persist the cleaned list so the stale duplicates don't reload.
+          if (dropped > 0) {
+            console.log(`[TmuxManager] Dropped ${dropped} duplicate mux session record(s) on load`);
+            this.saveSessions();
          }
        }
      }
@@ -429,6 +537,18 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * shell-metachar injection even if upstream schema check is bypassed.
   */
  private applyEnvOverrides(muxName: string, envOverrides?: Record<string, string>): void {
+    // Legacy cleanup: pre-0.7.2 set CLAUDE_CODE_EFFORT_LEVEL via setenv, which persists
+    // on the tmux session and hard-locks /effort switching in every respawned pane.
+    // Effort now flows as a `--settings` soft default (see buildEffortSettingsFlag),
+    // so unconditionally unset the stale var before applying current overrides.
+    try {
+      execSync(`${this.tmux()} setenv -t ${shellescape(muxName)} -u CLAUDE_CODE_EFFORT_LEVEL`, {
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      /* Non-critical — var may not exist */
+    }
    if (!envOverrides) return;
    const VALID_KEY = /^[A-Z_][A-Z0-9_]*$/;
    for (const [key, value] of Object.entries(envOverrides)) {
@@ -438,7 +558,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
        continue;
      }
      try {
-        execSync(`tmux setenv -t ${shellescape(muxName)} ${key} ${shellescape(value)}`, {
+        execSync(`${this.tmux()} setenv -t ${shellescape(muxName)} ${key} ${shellescape(value)}`, {
          timeout: EXEC_TIMEOUT_MS,
          stdio: ['pipe', 'pipe', 'pipe'],
        });
@@ -471,8 +591,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * (not visible in ps output or tmux history, inherited by panes).
   */
  private _configureOpenCode(muxName: string, openCodeConfig?: OpenCodeConfig): void {
-    setOpenCodeEnvVars(muxName);
-    setOpenCodeConfigContent(muxName, openCodeConfig);
+    const tmuxCmd = this.tmux();
+    setOpenCodeEnvVars(tmuxCmd, muxName);
+    setOpenCodeConfigContent(tmuxCmd, muxName, openCodeConfig);
  }

  /**
@@ -492,6 +613,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      openCodeConfig,
      resumeSessionId,
      envOverrides,
+      effort,
    } = options;
    const muxName = `codeman-${sessionId.slice(0, 8)}`;

@@ -538,6 +660,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      allowedTools,
      openCodeConfig,
      resumeSessionId,
+      effort,
    });

    const config = niceConfig || DEFAULT_NICE_CONFIG;
@@ -545,7 +668,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

    try {
      // Build the full command to run inside tmux
-      const fullCmd = `${pathExport}${envExportsStr} && ${cmd}`;
+      const fullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;

      // Create tmux session in three steps to handle cold-start (no server running)
      // and avoid the race where the command exits before remain-on-exit is set:
@@ -556,7 +679,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // (Production uses systemd which has a clean env, but dev/test may be nested.)
      const cleanEnv = { ...process.env };
      delete cleanEnv.TMUX;
-      execSync(`tmux new-session -ds "${muxName}" -c "${workingDir}"`, {
+      execSync(`${this.tmux()} new-session -ds "${muxName}" -c "${workingDir}"`, {
        cwd: workingDir,
        timeout: EXEC_TIMEOUT_MS,
        stdio: 'ignore',
@@ -565,7 +688,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

      // Set remain-on-exit now that the server is running — must be before respawn-pane
      try {
-        execSync(`tmux set-option -t "${muxName}" remain-on-exit on`, {
+        execSync(`${this.tmux()} set-option -t "${muxName}" remain-on-exit on`, {
          timeout: EXEC_TIMEOUT_MS,
          stdio: 'ignore',
        });
@@ -584,7 +707,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      this.applyEnvOverrides(muxName, envOverrides);

      // Replace the shell with the actual command (no echo in terminal)
-      execSync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
+      execSync(`${this.tmux()} respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
        timeout: EXEC_TIMEOUT_MS,
        stdio: 'ignore',
      });
@@ -598,20 +721,20 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // It gets enabled dynamically when panes are split (agent teams).
      const configPromises: Promise<void>[] = [
        // Disable tmux status bar — Codeman's web UI provides session info
-        execAsync(`tmux set-option -t "${muxName}" status off`, { timeout: EXEC_TIMEOUT_MS })
+        execAsync(`${this.tmux()} set-option -t "${muxName}" status off`, { timeout: EXEC_TIMEOUT_MS })
          .then(() => {})
          .catch(() => {
            /* Non-critical — session still works with status bar */
          }),
        // Override global remain-on-exit with session-level setting
-        execAsync(`tmux set-option -t "${muxName}" remain-on-exit on`, { timeout: EXEC_TIMEOUT_MS })
+        execAsync(`${this.tmux()} set-option -t "${muxName}" remain-on-exit on`, { timeout: EXEC_TIMEOUT_MS })
          .then(() => {})
          .catch(() => {
            /* Already set globally as fallback */
          }),
        // Raise tmux scrollback from its 2000-line default so re-attach preserves
        // more context. Matches the xterm-side default in constants.js.
-        execAsync(`tmux set-option -t "${muxName}" history-limit 50000`, { timeout: EXEC_TIMEOUT_MS })
+        execAsync(`${this.tmux()} set-option -t "${muxName}" history-limit 50000`, { timeout: EXEC_TIMEOUT_MS })
          .then(() => {})
          .catch(() => {
            /* Non-critical — falls back to tmux default */
@@ -621,7 +744,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // Enable 24-bit true color passthrough — server-wide, set once per lifetime
      if (!this.trueColorConfigured) {
        configPromises.push(
-          execAsync(`tmux set-option -sa terminal-overrides ",*:Tc"`, { timeout: EXEC_TIMEOUT_MS })
+          execAsync(`${this.tmux()} set-option -sa terminal-overrides ",*:Tc"`, { timeout: EXEC_TIMEOUT_MS })
            .then(() => {
              this.trueColorConfigured = true;
            })
@@ -678,7 +801,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }

    try {
-      const output = execSync(`tmux display-message -t "${muxName}" -p '#{pane_pid}'`, {
+      const output = execSync(`${this.tmux()} display-message -t "${muxName}" -p '#{pane_pid}'`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      }).trim();
@@ -704,7 +827,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    if (IS_TEST_MODE) return false;
    if (!isValidMuxName(muxName)) return false;
    try {
-      const output = execSync(`tmux display-message -t "${muxName}" -p '#{pane_dead}'`, {
+      const output = execSync(`${this.tmux()} display-message -t "${muxName}" -p '#{pane_dead}'`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      }).trim();
@@ -731,6 +854,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      openCodeConfig,
      resumeSessionId,
      envOverrides,
+      effort,
    } = options;
    const session = this.sessions.get(sessionId);
    if (!session) return null;
@@ -751,10 +875,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      allowedTools,
      openCodeConfig,
      resumeSessionId,
+      effort,
    });
    const config = niceConfig || DEFAULT_NICE_CONFIG;
    const cmd = wrapWithNice(baseCmd, config);
-    const fullCmd = `${pathExport}${envExportsStr} && ${cmd}`;
+    const fullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;

    try {
      // For OpenCode: set sensitive env vars via tmux setenv before respawn
@@ -765,7 +890,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // Re-apply user env overrides before respawn so the new shell inherits them.
      this.applyEnvOverrides(muxName, envOverrides);

-      await execAsync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
+      await execAsync(`${this.tmux()} respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
        timeout: EXEC_TIMEOUT_MS,
      });
      // Wait for the respawned process to start
@@ -783,7 +908,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    if (IS_TEST_MODE) return false;

    try {
-      execSync(`tmux has-session -t "${muxName}" 2>/dev/null`, {
+      execSync(`${this.tmux()} has-session -t "${muxName}" 2>/dev/null`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -923,7 +1048,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

    // Strategy 3: Kill tmux session by name
    try {
-      execSync(`tmux kill-session -t "${session.muxName}" 2>/dev/null`, {
+      execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
        timeout: EXEC_TIMEOUT_MS,
      });
    } catch {
@@ -988,26 +1113,28 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const dead: string[] = [];
    const discovered: string[] = [];

-    // Batch: single tmux call to get all session names + pane PIDs (replaces N per-session subprocess calls)
-    let activeSessions = new Map<string, number>();
+    // Single batched query against the one socket Codeman owns. With a single
+    // socket a session's location is a constant, so there is no per-session
+    // socket tag to reconcile and no cross-socket ambiguity that could mark a
+    // live session dead (the root cause of vanished/duplicate tabs).
+    let active: Map<string, number>;
    try {
-      const output = execSync(`tmux list-panes -a -F '${PANE_LIST_FORMAT}' 2>/dev/null || true`, {
+      const output = execSync(`${this.tmux()} list-panes -a -F '${PANE_LIST_FORMAT}' 2>/dev/null || true`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      }).trim();
-      activeSessions = parsePaneList(output);
+      active = parsePaneList(output);
    } catch (err) {
      console.error('[TmuxManager] Failed to list tmux panes:', err);
+      active = new Map();
    }

-    // Check known sessions against the batch result (O(1) map lookup instead of subprocess per session)
+    // Check tracked sessions against the live pane list.
    for (const [sessionId, session] of this.sessions) {
-      const pid = activeSessions.get(session.muxName);
+      const pid = active.get(session.muxName);
      if (pid !== undefined) {
        alive.push(sessionId);
-        if (pid !== session.pid) {
-          session.pid = pid;
-        }
+        if (pid !== session.pid) session.pid = pid;
      } else {
        dead.push(sessionId);
        this.sessions.delete(sessionId);
@@ -1015,13 +1142,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      }
    }

-    // Discover unknown codeman/claudeman sessions from the same batch result
+    // Discover untracked codeman/claudeman sessions on our socket. Dedup by
+    // muxName (globally unique) so a name we already track never spawns a
+    // second "Restored:" entry.
    const knownMuxNames = new Set<string>();
    for (const session of this.sessions.values()) {
      knownMuxNames.add(session.muxName);
    }

-    for (const [sessionName, pid] of activeSessions) {
+    for (const [sessionName, pid] of active) {
      if (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-')) continue;
      if (knownMuxNames.has(sessionName)) continue;

@@ -1038,6 +1167,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
        name: `Restored: ${sessionName}`,
      };
      this.sessions.set(sessionId, session);
+      knownMuxNames.add(sessionName);
      discovered.push(sessionId);
      console.log(`[TmuxManager] Discovered unknown tmux session: ${sessionName} (PID ${pid})`);
    }
@@ -1058,19 +1188,23 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }

    try {
-      const psOutput = execSync(`ps -o rss=,pcpu= -p ${session.pid} 2>/dev/null || echo "0 0"`, {
-        encoding: 'utf-8',
-        timeout: EXEC_TIMEOUT_MS,
-      }).trim();
+      const psOutput = (
+        await execAsync(`ps -o rss=,pcpu= -p ${session.pid} 2>/dev/null || echo "0 0"`, {
+          encoding: 'utf-8',
+          timeout: EXEC_TIMEOUT_MS,
+        })
+      ).stdout.trim();

      const [rss, cpu] = psOutput.split(/\s+/).map((x) => parseFloat(x) || 0);

      let childCount = 0;
      try {
-        const childOutput = execSync(`pgrep -P ${session.pid} | wc -l`, {
-          encoding: 'utf-8',
-          timeout: EXEC_TIMEOUT_MS,
-        }).trim();
+        const childOutput = (
+          await execAsync(`pgrep -P ${session.pid} | wc -l`, {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          })
+        ).stdout.trim();
        childCount = parseInt(childOutput, 10) || 0;
      } catch {
        // No children or command failed
@@ -1107,13 +1241,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // Step 1: Get descendant PIDs
      const descendantMap = new Map<number, number[]>();

-      const pgrepOutput = execSync(
-        `for p in ${sessionPids.join(' ')}; do children=$(pgrep -P $p 2>/dev/null | tr '\\n' ','); echo "$p:$children"; done`,
-        {
-          encoding: 'utf-8',
-          timeout: EXEC_TIMEOUT_MS,
-        }
-      ).trim();
+      const pgrepOutput = (
+        await execAsync(
+          `for p in ${sessionPids.join(' ')}; do children=$(pgrep -P $p 2>/dev/null | tr '\\n' ','); echo "$p:$children"; done`,
+          {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          }
+        )
+      ).stdout.trim();

      for (const line of pgrepOutput.split('\n')) {
        const [pidStr, childrenStr] = line.split(':');
@@ -1138,10 +1274,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // Step 3: Single ps call
      const pidArray = Array.from(allPids);
      if (pidArray.length > 0) {
-        const psOutput = execSync(`ps -o pid=,rss=,pcpu= -p ${pidArray.join(',')} 2>/dev/null || true`, {
-          encoding: 'utf-8',
-          timeout: EXEC_TIMEOUT_MS,
-        }).trim();
+        const psOutput = (
+          await execAsync(`ps -o pid=,rss=,pcpu= -p ${pidArray.join(',')} 2>/dev/null || true`, {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          })
+        ).stdout.trim();

        const processStats = new Map<number, { rss: number; cpu: number }>();
        for (const line of psOutput.split('\n')) {
@@ -1229,11 +1367,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      clearInterval(this.mouseSyncInterval);
    }

-    this.mouseSyncInterval = setInterval(() => {
+    this.mouseSyncInterval = setInterval(async () => {
      if (IS_TEST_MODE) return;

      for (const session of this.sessions.values()) {
-        const panes = this.listPanes(session.muxName);
+        const panes = await this.listPanes(session.muxName);
        const count = panes.length;
        if (count === 0) continue;

@@ -1242,12 +1380,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

        // Pane count changed — toggle mouse mode
        if (count > 1) {
-          if (this.enableMouseMode(session.muxName)) {
+          if (await this.enableMouseMode(session.muxName)) {
            this.lastPaneCount.set(session.muxName, count);
          }
          // If enableMouseMode fails, DON'T update lastPaneCount — retry next poll
        } else {
-          if (this.disableMouseMode(session.muxName)) {
+          if (await this.disableMouseMode(session.muxName)) {
            this.lastPaneCount.set(session.muxName, count);
          }
        }
@@ -1345,21 +1483,21 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
        // Ink (Claude CLI's terminal framework) needs them split — sending both in a
        // single tmux invocation (via \;) causes Ink to interpret Enter as a newline
        // character in the input buffer rather than as form submission.
-        await execAsync(`tmux send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
+        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
          timeout: EXEC_TIMEOUT_MS,
        });
        await new Promise((resolve) => setTimeout(resolve, 50));
-        await execAsync(`tmux send-keys -t "${session.muxName}" Enter`, {
+        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
          timeout: EXEC_TIMEOUT_MS,
        });
      } else if (textPart) {
        // Text only, no Enter
-        await execAsync(`tmux send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
+        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" -l ${shellescape(textPart)}`, {
          timeout: EXEC_TIMEOUT_MS,
        });
      } else if (hasCarriageReturn) {
        // Enter only
-        await execAsync(`tmux send-keys -t "${session.muxName}" Enter`, {
+        await execAsync(`${this.tmux()} send-keys -t "${session.muxName}" Enter`, {
          timeout: EXEC_TIMEOUT_MS,
        });
      }
@@ -1378,7 +1516,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * Allows clicking to select panes in agent team split-pane layouts.
   * When mouse mode is on, tmux intercepts mouse events (slow selection, no browser copy).
   */
-  enableMouseMode(muxName: string): boolean {
+  async enableMouseMode(muxName: string): Promise<boolean> {
    if (IS_TEST_MODE) return true;
    if (!isValidMuxName(muxName)) {
      console.error('[TmuxManager] Invalid session name in enableMouseMode:', muxName);
@@ -1386,7 +1524,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }

    try {
-      execSync(`tmux set-option -t "${muxName}" mouse on`, {
+      await execAsync(`${this.tmux()} set-option -t "${muxName}" mouse on`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -1402,7 +1540,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * Disable mouse mode for an existing tmux session.
   * Restores native xterm.js text selection and browser clipboard copy.
   */
-  disableMouseMode(muxName: string): boolean {
+  async disableMouseMode(muxName: string): Promise<boolean> {
    if (IS_TEST_MODE) return true;
    if (!isValidMuxName(muxName)) {
      console.error('[TmuxManager] Invalid session name in disableMouseMode:', muxName);
@@ -1410,7 +1548,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }

    try {
-      execSync(`tmux set-option -t "${muxName}" mouse off`, {
+      await execAsync(`${this.tmux()} set-option -t "${muxName}" mouse off`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -1427,9 +1565,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * Called by TeamWatcher when teammates spawn/despawn panes.
   * Uses `tmux list-panes` for bulletproof detection — counts actual panes, not config.
   */
-  syncMouseMode(muxName: string): boolean {
+  async syncMouseMode(muxName: string): Promise<boolean> {
    if (IS_TEST_MODE) return true;
-    const panes = this.listPanes(muxName);
+    const panes = await this.listPanes(muxName);
    if (panes.length > 1) {
      return this.enableMouseMode(muxName);
    } else {
@@ -1441,7 +1579,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   * List all panes in a tmux session.
   * Returns structured info for each pane.
   */
-  listPanes(muxName: string): PaneInfo[] {
+  async listPanes(muxName: string): Promise<PaneInfo[]> {
    if (IS_TEST_MODE) return [];
    if (!isValidMuxName(muxName)) {
      console.error('[TmuxManager] Invalid session name in listPanes:', muxName);
@@ -1449,10 +1587,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    }

    try {
-      const output = execSync(
-        `tmux list-panes -t "${muxName}" -F '#{pane_id}:#{pane_index}:#{pane_pid}:#{pane_width}:#{pane_height}'`,
-        { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }
-      ).trim();
+      const output = (
+        await execAsync(
+          `${this.tmux()} list-panes -t "${muxName}" -F '#{pane_id}:#{pane_index}:#{pane_pid}:#{pane_width}:#{pane_height}'`,
+          { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }
+        )
+      ).stdout.trim();

      return output
        .split('\n')
@@ -1489,27 +1629,28 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

    // Build target: sessionName.paneId (e.g., "codeman-abc12345.%1")
    const target = paneTarget.startsWith('%') ? `${muxName}.${paneTarget}` : `${muxName}.%${paneTarget}`;
+    const tmux = this.tmux();

    try {
      const hasCarriageReturn = input.includes('\r');
      const textPart = input.replace(/\r/g, '').replace(/\n/g, '').trimEnd();

      if (textPart && hasCarriageReturn) {
-        execSync(`tmux send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
+        execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
          encoding: 'utf-8',
          timeout: EXEC_TIMEOUT_MS,
        });
-        execSync(`tmux send-keys -t ${shellescape(target)} Enter`, {
+        execSync(`${tmux} send-keys -t ${shellescape(target)} Enter`, {
          encoding: 'utf-8',
          timeout: EXEC_TIMEOUT_MS,
        });
      } else if (textPart) {
-        execSync(`tmux send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
+        execSync(`${tmux} send-keys -t ${shellescape(target)} -l ${shellescape(textPart)}`, {
          encoding: 'utf-8',
          timeout: EXEC_TIMEOUT_MS,
        });
      } else if (hasCarriageReturn) {
-        execSync(`tmux send-keys -t ${shellescape(target)} Enter`, {
+        execSync(`${tmux} send-keys -t ${shellescape(target)} Enter`, {
          encoding: 'utf-8',
          timeout: EXEC_TIMEOUT_MS,
        });
@@ -1540,7 +1681,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const target = paneTarget.startsWith('%') ? `${muxName}.${paneTarget}` : `${muxName}.%${paneTarget}`;

    try {
-      return execSync(`tmux capture-pane -p -e -t ${shellescape(target)} -S -5000`, {
+      return execSync(`${this.tmux()} capture-pane -p -e -t ${shellescape(target)} -S -5000`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -1572,7 +1713,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const target = paneTarget.startsWith('%') ? `${muxName}.${paneTarget}` : `${muxName}.%${paneTarget}`;

    try {
-      execSync(`tmux pipe-pane -O -t ${shellescape(target)} ${shellescape('cat >> ' + outputFile)}`, {
+      execSync(`${this.tmux()} pipe-pane -O -t ${shellescape(target)} ${shellescape('cat >> ' + outputFile)}`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -1600,7 +1741,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const target = paneTarget.startsWith('%') ? `${muxName}.${paneTarget}` : `${muxName}.%${paneTarget}`;

    try {
-      execSync(`tmux pipe-pane -t ${shellescape(target)}`, {
+      execSync(`${this.tmux()} pipe-pane -t ${shellescape(target)}`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
      });
@@ -1616,7 +1757,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
  }

  getAttachArgs(muxName: string): string[] {
-    return ['attach-session', '-t', muxName];
+    return ['-L', this.tmuxSocket, 'attach-session', '-t', muxName];
  }

  isAvailable(): boolean {
@@ -40,6 +40,21 @@ export type ClaudeMode = 'dangerously-skip-permissions' | 'normal' | 'allowedToo
 /** Session mode: which CLI backend a session runs */
 export type SessionMode = 'claude' | 'shell' | 'opencode';

+/**
+ * Valid Claude CLI effort levels (claude >= 2.1.154).
+ * `ultracode` = xhigh effort + standing dynamic-workflow orchestration; it is a
+ * separate `ultracode` settings key rather than an `effortLevel` value.
+ */
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'] as const;
+
+/** Claude CLI effort level for new sessions (soft default, switchable via /effort in-session) */
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+
+/** Type guard: is the string a valid EffortLevel? */
+export function isEffortLevel(value: string | undefined): value is EffortLevel {
+  return value !== undefined && (EFFORT_LEVELS as readonly string[]).includes(value);
+}
+
 /** OpenCode session configuration */
 export interface OpenCodeConfig {
  /** Model identifier (e.g., "anthropic/claude-sonnet-4-5", "openai/gpt-5.2", "ollama/codellama") */
@@ -145,6 +160,8 @@ export interface SessionState {
  openCodeConfig?: OpenCodeConfig;
  /** Claude conversation session ID to resume after reboot (set by restore script) */
  resumeSessionId?: string;
+  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
+  effort?: EffortLevel;
 }

 /**
@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Event-loop lag monitor.
+ *
+ * Node is single-threaded: any synchronous work (e.g. a blocking `execSync`)
+ * freezes the whole event loop, so the HTTP server stops answering on its port
+ * while the process stays alive and other ports are unaffected. Such stalls
+ * self-heal and never restart the process, so a periodic loopback healthcheck
+ * misses them entirely — they leave no trace.
+ *
+ * This monitor samples how late a fixed-interval timer actually fires versus when
+ * it was scheduled; the excess is time the loop was blocked. When that exceeds a
+ * threshold it logs the measured stall, turning otherwise-invisible "port briefly
+ * unreachable" incidents into a timestamped, quantified log line.
+ *
+ * @module utils/event-loop-monitor
+ */
+
+export interface EventLoopMonitorHandle {
+  stop(): void;
+}
+
+/**
+ * Start sampling event-loop lag.
+ *
+ * @param sampleMs    How often to sample (and the baseline interval lag is measured against).
+ * @param thresholdMs Only stalls at or above this many ms are logged (noise floor).
+ * @param log         Sink for stall reports; defaults to console.warn (lands in the web log).
+ */
+export function startEventLoopMonitor(
+  sampleMs = 1000,
+  thresholdMs = 1000,
+  log: (msg: string) => void = (m) => console.warn(m)
+): EventLoopMonitorHandle {
+  let last = performance.now();
+
+  const timer = setInterval(() => {
+    const now = performance.now();
+    // Lag = elapsed beyond the scheduled interval = time the loop was blocked.
+    const lag = Math.round(now - last - sampleMs);
+    if (lag >= thresholdMs) {
+      log(`[EventLoopLag] event loop blocked ~${lag}ms (at ${new Date().toISOString()})`);
+    }
+    last = now;
+  }, sampleMs);
+
+  // Never keep the process alive solely for this monitor.
+  timer.unref?.();
+
+  return {
+    stop() {
+      clearInterval(timer);
+    },
+  };
+}
@@ -9,6 +9,8 @@
 export { BufferAccumulator } from './buffer-accumulator.js';
 export { CleanupManager } from './cleanup-manager.js';
 export { Debouncer, KeyedDebouncer } from './debouncer.js';
+export { startEventLoopMonitor } from './event-loop-monitor.js';
+export type { EventLoopMonitorHandle } from './event-loop-monitor.js';
 export { StaleExpirationMap } from './stale-expiration-map.js';
 export {
  ANSI_ESCAPE_PATTERN_FULL,
@@ -154,13 +154,24 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
 * Register security headers and CORS middleware on every response.
 */
 export function registerSecurityHeaders(app: FastifyInstance, https: boolean): void {
+  // Gesture-control overlay (opt-in via CODEMAN_GESTURE=1) runs MediaPipe, which
+  // needs WebAssembly eval (script-src) and blob workers (worker-src). Its wasm
+  // runtime + model are self-hosted under /gesture/ (same-origin, covered by
+  // 'self'), so no CDN connect-src entries are needed. OFF by default so the
+  // production CSP is byte-for-byte unchanged.
+  const gesture = process.env.CODEMAN_GESTURE === '1';
+  const scriptSrc =
+    "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net" + (gesture ? " 'wasm-unsafe-eval'" : '');
+  const connectSrc = "connect-src 'self' wss://api.deepgram.com";
+  const workerSrc = gesture ? "; worker-src 'self' blob:" : '';
+  const csp =
+    `default-src 'self'; ${scriptSrc}; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; ` +
+    `img-src 'self' data: blob:; ${connectSrc}; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'${workerSrc}`;
+
  app.addHook('onRequest', (req, reply, done) => {
    reply.header('X-Content-Type-Options', 'nosniff');
    reply.header('X-Frame-Options', 'SAMEORIGIN');
-    reply.header(
-      'Content-Security-Policy',
-      "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: blob:; connect-src 'self' wss://api.deepgram.com; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'"
-    );
+    reply.header('Content-Security-Policy', csp);
    if (https) {
      reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
    }
@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Periodic GC for paste-image files.
+ *
+ * Without cleanup, /api/sessions/:id/paste-image accumulates files indefinitely
+ * under {workingDir}/.claude-images/. The route only triggers cleanup on
+ * killMux=true session deletion, so long-lived sessions can fill disk under
+ * heavy pasting. This sweeper bounds disk use by deleting `paste-*` files
+ * older than MAX_AGE_MS from each live session's image dir on an interval.
+ *
+ * Conservative defaults — only files matching the `paste-` prefix are
+ * considered, and we lstat (not stat) so a planted symlink cannot escape the
+ * image dir.
+ */
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import type { SessionPort } from './ports/index.js';
+
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const SWEEP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const INITIAL_DELAY_MS = 30 * 1000; // 30s after startup
+
+export async function sweepPasteImagesOnce(
+  ctx: Pick<SessionPort, 'sessions'>,
+  now: number = Date.now()
+): Promise<{ scanned: number; deleted: number }> {
+  const cutoff = now - MAX_AGE_MS;
+  let scanned = 0;
+  let deleted = 0;
+  for (const session of ctx.sessions.values()) {
+    const dir = join(session.workingDir, '.claude-images');
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue; // dir absent — nothing to do
+    }
+    for (const name of entries) {
+      if (!name.startsWith('paste-')) continue;
+      const p = join(dir, name);
+      scanned += 1;
+      try {
+        const st = await fs.lstat(p);
+        if (!st.isFile()) continue;
+        if (st.mtimeMs < cutoff) {
+          await fs.unlink(p);
+          deleted += 1;
+        }
+      } catch {
+        // best-effort: skip permission/race errors silently
+      }
+    }
+  }
+  return { scanned, deleted };
+}
+
+export function startPasteImageGc(ctx: Pick<SessionPort, 'sessions'>): () => void {
+  const initial = setTimeout(() => {
+    void sweepPasteImagesOnce(ctx);
+  }, INITIAL_DELAY_MS);
+  const interval = setInterval(() => {
+    void sweepPasteImagesOnce(ctx);
+  }, SWEEP_INTERVAL_MS);
+  if (typeof initial.unref === 'function') initial.unref();
+  if (typeof interval.unref === 'function') interval.unref();
+  return (): void => {
+    clearTimeout(initial);
+    clearInterval(interval);
+  };
+}
@@ -286,9 +286,31 @@ class CodemanApp {
    this.totalTokens = 0;
    this.globalStats = null; // Global token/cost stats across all sessions
    this.eventSource = null;
+    // Stable per-page client ID — lets the server target this connection
+    // for live filter updates (POST /api/events/subscribe) without forcing
+    // an SSE reconnect on session switches.
+    this._clientId = (typeof crypto !== 'undefined' && crypto.randomUUID)
+      ? crypto.randomUUID()
+      : 'c-' + Math.random().toString(36).slice(2) + Date.now().toString(36);
    this.terminal = null;
    this.fitAddon = null;
    this.activeSessionId = null;
+
+    // ── Session detach / undock (beta) ───────────────────────────────────
+    // A "solo window" is a popped-out browser window showing exactly one
+    // session. Detected from the /session/:id URL path (robust even if a cached
+    // service-worker shell loads), with the server-injected global as a fallback.
+    this.soloSessionId = this._detectSoloSessionId();
+    this.isSoloWindow = !!this.soloSessionId;
+    this.detachedSessions = new Set();   // dashboard-side: ids currently popped out
+    this.detachedWindows = new Map();    // dashboard-side: id -> WindowProxy
+    this._detachWatchTimers = new Map(); // dashboard-side: id -> setInterval handle
+    this.windowChannel = null;           // BroadcastChannel for cross-window sync
+    this._redockGrace = new Map();       // id -> timer: deferred redock (debounces popup reloads)
+    this._detachPingPending = null;      // Set of ids awaiting a liveness answer
+    this._detachLivenessTimer = null;    // periodic reconcile of channel-only detached windows
+    this._detachOrphanStrikes = new Map(); // id -> consecutive unanswered roll-calls (redock at 2)
+
    this._initGeneration = 0;     // dedup concurrent handleInit calls
    this._initFallbackTimer = null; // fallback timer if SSE init doesn't arrive
    this._selectGeneration = 0;   // cancel stale selectSession loads
@@ -538,6 +560,11 @@ class CodemanApp {
  init() {
    // Initialize mobile detection first (adds device classes to body)
    MobileDetection.init();
+    // Detach/undock: open the cross-window sync channel; if this is a solo
+    // (popped-out) window, apply its minimal chrome immediately so the tab
+    // strip never flashes before handleInit selects the target session.
+    this._initWindowChannel();
+    if (this.isSoloWindow) document.body.classList.add('solo-mode');
    // Initialize mobile handlers
    KeyboardHandler.init();
    SwipeHandler.init();
@@ -617,14 +644,66 @@ class CodemanApp {
      this._webglAddon = new WebglAddon.WebglAddon();
      this._webglAddon.onContextLoss(() => {
        console.error('[CRASH-DIAG] WebGL context LOST — falling back to canvas renderer');
-        this._webglAddon.dispose();
+        _crashDiag.log('WEBGL_LOST');
+        this._disableWebGLSticky('context-lost');
+        this._disposeWebGLObserver();
+        this._webglAddon?.dispose();
        this._webglAddon = null;
      });
      this.terminal.loadAddon(this._webglAddon);
      console.log('[CRASH-DIAG] WebGL renderer enabled');
+      this._installWebGLLongTaskGuard();
    } catch (_e) { /* WebGL2 unavailable — canvas renderer used */ }
  }

+  /**
+   * Watch for sustained main-thread stalls that indicate WebGL/GPU trouble.
+   * After WEBGL_FALLBACK.LONGTASK_COUNT long tasks (>=LONGTASK_MS each) within
+   * WINDOW_MS, dispose the WebGL addon and persist a sticky disable so
+   * subsequent reloads also use the DOM renderer. GRACE_MS skips initial-load
+   * stalls. Force-re-enable: ?webgl=force.
+   */
+  _installWebGLLongTaskGuard() {
+    if (typeof PerformanceObserver === 'undefined' || this._webglLongTaskObserver) return;
+    const installedAt = performance.now();
+    const recent = [];
+    try {
+      this._webglLongTaskObserver = new PerformanceObserver((list) => {
+        if (!this._webglAddon) return;
+        const now = performance.now();
+        if (now - installedAt < WEBGL_FALLBACK.GRACE_MS) return;
+        if (evaluateWebGLLongTaskTrip(recent, list.getEntries(), now)) {
+          console.warn(`[CRASH-DIAG] WebGL long-task threshold (${recent.length} stalls/${WEBGL_FALLBACK.WINDOW_MS}ms) — falling back to canvas renderer`);
+          _crashDiag.log(`WEBGL_FALLBACK: ${recent.length}`);
+          this._disableWebGLSticky('long-tasks');
+          this._disposeWebGLObserver();
+          this._webglAddon?.dispose();
+          this._webglAddon = null;
+          try { this.terminal.refresh(0, this.terminal.rows - 1); } catch {}
+        }
+      });
+      this._webglLongTaskObserver.observe({ type: 'longtask', buffered: false });
+    } catch { /* longtask not supported */ }
+  }
+
+  /**
+   * Disconnect the WebGL longtask observer. Idempotent. Called from the trip
+   * path, the onContextLoss handler, and any future terminal-teardown path —
+   * the observer outlives its addon otherwise, holding a closure reference
+   * over `this` for every long task the page emits.
+   */
+  _disposeWebGLObserver() {
+    if (!this._webglLongTaskObserver) return;
+    try { this._webglLongTaskObserver.disconnect(); } catch {}
+    this._webglLongTaskObserver = null;
+  }
+
+  _disableWebGLSticky(reason) {
+    try {
+      localStorage.setItem('codeman-webgl-disabled', JSON.stringify({ reason, at: Date.now() }));
+    } catch {}
+  }
+
  // ═══════════════════════════════════════════════════════════════
  // Event Listeners (Keyboard Shortcuts, Resize, Beforeunload)
  // ═══════════════════════════════════════════════════════════════
@@ -696,6 +775,278 @@ class CodemanApp {
  // SSE Connection
  // ═══════════════════════════════════════════════════════════════

+  /**
+   * POST a live subscription update so the server filters terminal events
+   * to the given session(s) for this client. Fire-and-forget — failures
+   * are non-fatal because we'll still get every event we don't want
+   * (just at higher cost), and the next reconnect carries the filter via
+   * the SSE query string.
+   */
+  _updateSseSubscription(sessionId) {
+    try {
+      const body = JSON.stringify({
+        clientId: this._clientId,
+        sessions: sessionId ? [sessionId] : null,
+      });
+      fetch('/api/events/subscribe', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        keepalive: true,
+      }).catch(() => { /* non-fatal */ });
+    } catch { /* non-fatal */ }
+  }
+
+  // ══════════════════════════════════════════════════════════════════════
+  // Session detach / undock (beta/session-detach)
+  //
+  // Each detached window is just another normal client of the same session:
+  // the server already fans one PTY's output out to N SSE/WS clients and merges
+  // input from all of them, so a popped-out window is live with no extra server
+  // plumbing. The dashboard tracks which sessions are out, marks their tabs, and
+  // re-docks when the window closes. A BroadcastChannel keeps state in sync
+  // across windows (and survives a dashboard reload via roll-call).
+  // ══════════════════════════════════════════════════════════════════════
+
+  /** Resolve the solo session id from the URL path (preferred) or the
+   *  server-injected global (fallback). Returns null for the normal dashboard. */
+  _detectSoloSessionId() {
+    try {
+      if (typeof window !== 'undefined' && typeof window.__CODEMAN_SOLO__ === 'string' && window.__CODEMAN_SOLO__) {
+        return window.__CODEMAN_SOLO__;
+      }
+      const m = location.pathname.match(/^\/session\/([^/]+)\/?$/);
+      return m ? decodeURIComponent(m[1]) : null;
+    } catch { return null; }
+  }
+
+  /**
+   * Pop a session out into its own browser window. SINGLE, idempotent entry
+   * point: the tab's pop-out icon calls this, and a future gesture layer
+   * ("pinch to drop") calls the exact same method — so keep it cheap and
+   * side-effect-light. Calling it again for an already-open window just raises
+   * that window.
+   * @param {string} id session id
+   */
+  detachSession(id) {
+    if (this.isSoloWindow) return;            // a solo window can't spawn more
+    if (!this.sessions.has(id)) return;
+    // Already detached → raise the existing popup instead of opening (or
+    // reloading) another. Mirrors the tab-click path: after a dashboard reload
+    // we hold no WindowProxy ref, so this raises via the channel rather than
+    // re-running window.open (which would reload the popup's terminal). Returns
+    // false only when we owned a now-closed window (re-dock + fall through to
+    // genuinely re-open below).
+    if (this.detachedSessions.has(id) && this._raiseDetached(id)) return;
+    const features = 'width=960,height=680,menubar=no,toolbar=no,location=no,status=no';
+    let win = null;
+    try { win = window.open('/session/' + encodeURIComponent(id), 'codeman-session-' + id, features); } catch {}
+    if (!win) {
+      this.showToast?.('Pop-out blocked — allow popups for this site to detach a session', 'error');
+      return;
+    }
+    this.detachedWindows.set(id, win);
+    this._markDetached(id, true);
+    this._watchDetachedWindow(id, win);
+    this._postWindowMessage({ type: 'detached', id });
+    try { win.focus(); } catch {}
+  }
+
+  /** Raise the popup for an already-detached session. Returns true if the raise
+   *  was handled (caller should stop); false if we owned a now-closed window and
+   *  re-docked it (caller should fall through to inline / re-open). Unifies the
+   *  pop-out icon and tab-click paths so neither reloads a live popup. */
+  _raiseDetached(id) {
+    const win = this.detachedWindows.get(id);
+    if (win && !win.closed) { try { win.focus(); } catch {} return true; }
+    if (win && win.closed) { this._redock(id); return false; }   // owned ref dead → redock + fall through
+    // No local ref (dashboard reloaded): assume alive and raise via the channel.
+    // A liveness ping (or the popup's own unload) heals the badge if it's gone.
+    this._postWindowMessage({ type: 'focus-request', id });
+    return true;
+  }
+
+  /** Re-dock a session: close its window (which re-docks via its unload
+   *  announcement) and clear dashboard state now. */
+  redockSession(id) {
+    const win = this.detachedWindows.get(id);
+    if (win && !win.closed) { try { win.close(); } catch {} }
+    this._postWindowMessage({ type: 'close-request', id });
+    this._redock(id);
+  }
+
+  /** Clear all dashboard-side detached state/timers for a session. */
+  _redock(id) {
+    const t = this._detachWatchTimers.get(id);
+    if (t) { clearInterval(t); this._detachWatchTimers.delete(id); }
+    this._cancelPendingRedock(id);
+    this._detachOrphanStrikes.delete(id);
+    this.detachedWindows.delete(id);
+    this._markDetached(id, false);
+  }
+
+  /** Defer a channel-driven redock briefly. A popup *reload* emits 'redocked'
+   *  then re-announces 'detached'; the grace window lets that re-announce cancel
+   *  the redock, so a reload doesn't blip the dashboard badge. A real close
+   *  leaves the redock unanswered and it fires. */
+  _scheduleRedock(id) {
+    if (this._redockGrace.has(id)) return;
+    const timer = setTimeout(() => { this._redockGrace.delete(id); this._redock(id); }, 1500);
+    this._redockGrace.set(id, timer);
+  }
+
+  _cancelPendingRedock(id) {
+    const t = this._redockGrace.get(id);
+    if (t) { clearTimeout(t); this._redockGrace.delete(id); }
+  }
+
+  /** Toggle the "detached" marker on a tab (immediate DOM update + state set).
+   *  Full re-renders re-apply the class from this.detachedSessions. */
+  _markDetached(id, on) {
+    if (on) this.detachedSessions.add(id); else this.detachedSessions.delete(id);
+    const container = this.$('sessionTabs');
+    const tab = container && container.querySelector(`.session-tab[data-id="${id}"]`);
+    if (tab) tab.classList.toggle('detached', on);
+  }
+
+  /** Poll a window we opened; when it closes, re-dock its tab. This is the
+   *  primary (reliable) close-detection path for windows this tab opened. */
+  _watchDetachedWindow(id, win) {
+    const prev = this._detachWatchTimers.get(id);
+    if (prev) clearInterval(prev);
+    const timer = setInterval(() => {
+      if (!win || win.closed) {
+        clearInterval(timer);
+        this._detachWatchTimers.delete(id);
+        this._redock(id);
+      }
+    }, 800);
+    this._detachWatchTimers.set(id, timer);
+  }
+
+  /** Open the cross-window BroadcastChannel and wire role-specific handlers. */
+  _initWindowChannel() {
+    if (typeof BroadcastChannel === 'undefined') return;
+    try { this.windowChannel = new BroadcastChannel('codeman-windows'); }
+    catch { this.windowChannel = null; return; }
+    this.windowChannel.onmessage = (e) => this._onWindowMessage(e.data);
+    if (this.isSoloWindow) {
+      // Announce presence so the dashboard marks this session's tab detached —
+      // even if this window was opened directly by URL rather than window.open.
+      this._postWindowMessage({ type: 'detached', id: this.soloSessionId });
+      // On close, tell the dashboard to re-dock. pagehide is the reliable signal
+      // on modern browsers; beforeunload is a belt-and-suspenders fallback.
+      const announceClose = () => this._postWindowMessage({ type: 'redocked', id: this.soloSessionId });
+      window.addEventListener('pagehide', announceClose);
+      window.addEventListener('beforeunload', announceClose);
+    } else {
+      // Dashboard: ask any already-open solo windows to re-announce themselves
+      // (covers a dashboard reload while popups remain open), then keep
+      // reconciling so a popup that died WITHOUT a 'redocked' (hard kill / crash)
+      // eventually un-marks its tab.
+      this._postWindowMessage({ type: 'roll-call' });
+      this._startDetachLiveness();
+    }
+  }
+
+  _postWindowMessage(msg) {
+    try { if (this.windowChannel) this.windowChannel.postMessage(msg); } catch {}
+  }
+
+  _onWindowMessage(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    if (this.isSoloWindow) {
+      // Roll-call has no id (broadcast to all) — answer before the id filter.
+      if (msg.type === 'roll-call') { this._postWindowMessage({ type: 'detached', id: this.soloSessionId }); return; }
+      if (msg.id !== this.soloSessionId) return;
+      if (msg.type === 'close-request') { try { window.close(); } catch {} }
+      else if (msg.type === 'focus-request') { try { window.focus(); } catch {} }
+      return;
+    }
+    // Dashboard side.
+    if (msg.type === 'detached' && msg.id) {
+      this._cancelPendingRedock(msg.id);    // a re-announce (e.g. popup reload) cancels a deferred redock
+      this._detachPingPending?.delete(msg.id);  // and proves liveness for this tick
+      this._detachOrphanStrikes.delete(msg.id); // any answer clears accumulated misses
+      this._markDetached(msg.id, true);
+    } else if (msg.type === 'redocked' && msg.id) {
+      this._scheduleRedock(msg.id);         // defer: a popup reload fires redocked→detached; grace avoids a badge blip
+    } else if (msg.type === 'detach-request' && msg.id) {
+      // Future gesture hook: another window asks the dashboard to detach a tab.
+      this.detachSession(msg.id);
+    }
+  }
+
+  /** Dashboard: periodically reconcile detached tabs we hold no window ref for
+   *  (e.g. after a dashboard reload). Owned windows are covered by the
+   *  win.closed poll; channel-only ones can only be checked by asking them to
+   *  re-announce and re-docking any that stay silent. */
+  _startDetachLiveness() {
+    if (this._detachLivenessTimer) return;
+    this._detachLivenessTimer = setInterval(() => this._pingDetached(), 5000);
+  }
+
+  _pingDetached() {
+    const orphans = [];
+    for (const id of this.detachedSessions) {
+      const win = this.detachedWindows.get(id);
+      if (!win) orphans.push(id);            // channel-only — must verify via re-announce
+      else if (win.closed) this._redock(id); // owned & closed — heal now
+    }
+    if (!orphans.length) return;
+    this._detachPingPending = new Set(orphans);
+    this._postWindowMessage({ type: 'roll-call' });
+    // Live popups answer 'detached' (clearing themselves above); survivors stay in
+    // the pending set. Redock only after TWO consecutive unanswered roll-calls — a
+    // backgrounded popup is timer-throttled and may miss a single 1.2s window, and
+    // we don't want to wrongly un-mark a still-open tab. A later answer resets the
+    // strike count (see _onWindowMessage).
+    setTimeout(() => {
+      if (!this._detachPingPending) return;
+      for (const id of this._detachPingPending) {
+        const strikes = (this._detachOrphanStrikes.get(id) || 0) + 1;
+        if (strikes >= 2) { this._detachOrphanStrikes.delete(id); this._redock(id); }
+        else this._detachOrphanStrikes.set(id, strikes);
+      }
+      this._detachPingPending = null;
+    }, 1200);
+  }
+
+  /** Solo window: select the target session and apply minimal single-session
+   *  chrome. Called from handleInit once the session list has loaded. */
+  _applySoloMode() {
+    document.body.classList.add('solo-mode');
+    const session = this.sessions.get(this.soloSessionId);
+    if (!session) { this._showSoloSessionGone(); return; }
+    // Force re-select (handleInit cleared terminal state above).
+    this.activeSessionId = null;
+    this.selectSession(this.soloSessionId);
+    const name = this.getSessionName(session) || 'Session';
+    const titleEl = document.getElementById('soloSessionTitle');
+    if (titleEl) { titleEl.textContent = name; titleEl.style.display = ''; }
+    const redock = document.getElementById('soloRedockBtn');
+    if (redock) redock.style.display = '';
+    document.title = name + ' — Codeman';
+    if (this.notificationManager) this.notificationManager.originalTitle = document.title;
+    // Neutralize the dashboard-only brand click in a solo window.
+    const logo = document.querySelector('.header-brand .logo');
+    if (logo) logo.onclick = (e) => { e.preventDefault(); };
+  }
+
+  /** Solo window: the target session is gone (never existed, or ended while
+   *  this window was open). Show a friendly terminal state. */
+  _showSoloSessionGone() {
+    document.body.classList.add('solo-mode');
+    if (document.querySelector('.solo-gone-overlay')) return;
+    const el = document.createElement('div');
+    el.className = 'solo-gone-overlay';
+    el.innerHTML = '<h2>Session unavailable</h2>'
+      + '<p>This session has ended or is no longer available.</p>'
+      + '<button class="btn-primary" onclick="window.close()">Close window</button>';
+    document.body.appendChild(el);
+    document.title = 'Session ended — Codeman';
+  }
+
  connectSSE() {
    // Check if browser is offline
    if (!navigator.onLine) {
@@ -725,7 +1076,13 @@ class CodemanApp {
      this.setConnectionStatus('reconnecting');
    }

-    this.eventSource = new EventSource('/api/events');
+    // Build URL with stable client ID and (if known) the active-session
+    // filter so the server only streams session:terminal events for the
+    // session we're rendering. Lifecycle/metadata events are sent globally
+    // regardless of filter (server side).
+    const _sseParams = new URLSearchParams({ clientId: this._clientId });
+    if (this.activeSessionId) _sseParams.set('sessions', this.activeSessionId);
+    this.eventSource = new EventSource(`/api/events?${_sseParams.toString()}`);

    // Store all event listeners for cleanup on reconnect
    const listeners = [];
@@ -843,6 +1200,12 @@ class CodemanApp {

  _onSessionDeleted(data) {
    if (this._wsSessionId === data.id) this._disconnectWs();
+    // Solo window whose session just ended → show the "unavailable" state.
+    if (this.isSoloWindow && data.id === this.soloSessionId) {
+      this._showSoloSessionGone();
+    }
+    // Dashboard: a detached session ended → clear its detached state/timers.
+    if (this.detachedSessions.has(data.id)) this._redock(data.id);
    this._cleanupSessionData(data.id);
    if (this.activeSessionId === data.id) {
      this.activeSessionId = null;
@@ -1024,9 +1387,10 @@ class CodemanApp {

  /** Render markdown to sanitized HTML, falling back to plain text if marked.js unavailable */
  _renderMarkdown(text) {
+    const src = text || '';
    if (typeof marked !== 'undefined' && marked.parse) {
      try {
-        const prepared = this._preprocessAsciiArt(text);
+        const prepared = this._preprocessAsciiArt(src);
        let html = this._sanitizeHtml(marked.parse(prepared, { breaks: true, gfm: true }));
        // Wrap tables in a horizontal-scroll container so they overflow gracefully
        // on mobile without collapsing into block-level cells.
@@ -1042,29 +1406,47 @@ class CodemanApp {
        const DIAGRAM_CHAR = /[─-╿▀-▟]/;
        const tmpl = document.createElement('template');
        tmpl.innerHTML = html;
+        // Every fenced code block gets a positioned wrapper with an action
+        // toolbar pinned to its top-right corner. The toolbar lives OUTSIDE the
+        // <pre> scroll container so its buttons stay put during horizontal
+        // scroll. All blocks get a one-click copy button; ASCII diagrams keep
+        // the additional line-wrap toggle.
        tmpl.content.querySelectorAll('pre > code').forEach((code) => {
-          if (!DIAGRAM_CHAR.test(code.textContent || '')) return;
          const pre = code.parentElement;
-          pre.classList.add('rv-diagram');
+          const isDiagram = DIAGRAM_CHAR.test(code.textContent || '');

          const wrap = document.createElement('div');
-          wrap.className = 'rv-diagram-wrap';
+          wrap.className = isDiagram ? 'rv-code-wrap rv-diagram-wrap' : 'rv-code-wrap';

-          const btn = document.createElement('button');
-          btn.className = 'rv-wrap-toggle';
-          btn.type = 'button';
-          btn.setAttribute('aria-label', 'Toggle line wrapping');
-          btn.setAttribute('title', 'Toggle line wrapping');
+          const actions = document.createElement('div');
+          actions.className = 'rv-code-actions';
+
+          const copyBtn = document.createElement('button');
+          copyBtn.className = 'rv-copy-btn';
+          copyBtn.type = 'button';
+          copyBtn.setAttribute('aria-label', 'Copy code');
+          copyBtn.setAttribute('title', 'Copy code');
+          actions.appendChild(copyBtn);
+
+          if (isDiagram) {
+            pre.classList.add('rv-diagram');
+            const toggle = document.createElement('button');
+            toggle.className = 'rv-wrap-toggle';
+            toggle.type = 'button';
+            toggle.setAttribute('aria-label', 'Toggle line wrapping');
+            toggle.setAttribute('title', 'Toggle line wrapping');
+            actions.appendChild(toggle);
+          }

          pre.parentNode.insertBefore(wrap, pre);
-          wrap.appendChild(btn);
+          wrap.appendChild(actions);
          wrap.appendChild(pre);
        });
        return tmpl.innerHTML;
      } catch { /* fall through */ }
    }
    // Fallback: escape HTML and preserve whitespace
-    const escaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const escaped = src.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
    return `<pre style="white-space:pre-wrap;word-break:break-word">${escaped}</pre>`;
  }

@@ -1076,7 +1458,23 @@ class CodemanApp {
  _bindResponseViewerInteractions(body) {
    if (!body || body.dataset.rvBound === '1') return;
    body.dataset.rvBound = '1';
-    body.addEventListener('click', (ev) => {
+    body.addEventListener('click', async (ev) => {
+      // One-click copy: lift the raw source from the sibling <pre><code>.
+      const copyBtn = ev.target.closest('.rv-copy-btn');
+      if (copyBtn) {
+        ev.preventDefault();
+        ev.stopPropagation();
+        const code = copyBtn.closest('.rv-code-wrap')?.querySelector('pre code');
+        const ok = code ? await this._copyText(code.textContent || '') : false;
+        copyBtn.classList.remove('rv-copied', 'rv-copy-failed');
+        copyBtn.classList.add(ok ? 'rv-copied' : 'rv-copy-failed');
+        clearTimeout(copyBtn._resetTimer);
+        copyBtn._resetTimer = setTimeout(() => {
+          copyBtn.classList.remove('rv-copied', 'rv-copy-failed');
+        }, 1500);
+        return;
+      }
+
      const btn = ev.target.closest('.rv-wrap-toggle');
      if (!btn) return;
      ev.preventDefault();
@@ -1089,6 +1487,34 @@ class CodemanApp {
    });
  }

+  /**
+   * Copy text to the clipboard. Prefers the async Clipboard API (secure
+   * contexts); falls back to a hidden-textarea + execCommand path so copy
+   * still works over plain HTTP. Returns true on success.
+   */
+  async _copyText(text) {
+    if (!text) return false;
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+        return true;
+      }
+    } catch { /* secure-context write failed — try the legacy path */ }
+    try {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.setAttribute('readonly', '');
+      ta.style.cssText = 'position:fixed;top:0;left:0;opacity:0;pointer-events:none';
+      document.body.appendChild(ta);
+      ta.select();
+      const ok = document.execCommand('copy');
+      document.body.removeChild(ta);
+      return ok;
+    } catch {
+      return false;
+    }
+  }
+
  async toggleResponseViewer() {
    const viewer = document.getElementById('responseViewer');
    const backdrop = document.getElementById('responseViewerBackdrop');
@@ -1708,8 +2134,10 @@ class CodemanApp {
      }
    });

-    // Restore tabs that were open before refresh but are no longer on the server
-    this._restoreEndedTabs();
+    // Server is source of truth for open sessions — don't resurrect stale tabs
+    // from localStorage (would show phantom "ended" tabs when a session was closed
+    // on another device).
+    try { localStorage.removeItem('codeman-tab-meta'); } catch {}

    // Sync sessionOrder with current sessions (preserve order, add new, remove stale)
    this.syncSessionOrder();
@@ -1798,6 +2226,14 @@ class CodemanApp {
    // Reset activeSessionId so selectSession doesn't early-return.
    // Guard: skip if a newer handleInit has already started (race between loadState + SSE init).
    if (gen !== this._initGeneration) return;
+
+    // Solo (detached) window: always show exactly the target session, ignoring
+    // the dashboard's "restore last active" logic.
+    if (this.isSoloWindow) {
+      this._applySoloMode();
+      return;
+    }
+
    const previousActiveId = this.activeSessionId;
    this.activeSessionId = null;
    if (this.sessionOrder.length > 0) {
@@ -2031,20 +2467,21 @@ class CodemanApp {
      const tallTabsEnabled = this._tallTabsEnabled ?? false;
      const showFolder = tallTabsEnabled && session.name && folderName && folderName !== name;

-      const endedAttr = session._ended ? ' data-ended="1"' : '';
-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}" data-id="${id}" data-color="${color}"${endedAttr} onclick="app.selectSession('${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
+      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${this.detachedSessions.has(id) ? ' detached' : ''}" data-id="${id}" data-color="${color}" onclick="app.selectSession('${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
          ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
          <span class="tab-status ${status}" aria-hidden="true"></span>
          <span class="tab-info">
            <span class="tab-name-row">
              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : ''}
              <span class="tab-name" data-session-id="${id}">${(() => { const p = parseSessionPrefix(name); return p && p.suffix ? '<span class="tab-prefix">' + escapeHtml(p.prefix) + '</span><span class="tab-suffix">: ' + escapeHtml(p.suffix) + '</span>' : escapeHtml(name); })()}</span>
+              <span class="tab-detached-badge" aria-hidden="true">detached</span>
            </span>
            ${showFolder ? `<span class="tab-folder">\u{1F4C1} ${escapeHtml(folderName)}</span>` : ''}
          </span>
          ${hasRunningTasks ? `<span class="tab-badge" onclick="event.stopPropagation(); app.toggleTaskPanel()" aria-label="${taskStats.running} running tasks">${taskStats.running}</span>` : ''}
          ${subagentBadge}
          <span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions('${escapeHtml(id)}')" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span>
+          <span class="tab-detach" onclick="event.stopPropagation(); app.detachSession('${escapeHtml(id)}')" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span>
          <span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession('${escapeHtml(id)}')" title="Close session" aria-label="Close session" tabindex="0">&times;</span>
        </div>`);
      _tabIdx++;
@@ -2052,9 +2489,6 @@ class CodemanApp {

    container.innerHTML = parts.join('');

-    // Persist tab metadata for refresh recovery
-    this._saveTabMetadata();
-
    // Set up drag-and-drop handlers for tab reordering
    this.setupTabDragHandlers();

@@ -2154,33 +2588,6 @@ class CodemanApp {
    }
  }

-  // Save tab metadata to localStorage so ended sessions can be restored after refresh
-  _saveTabMetadata() {
-    try {
-      const meta = {};
-      for (const [id, s] of this.sessions) {
-        if (s._ended) continue; // Don't persist ended stubs back
-        meta[id] = { id, name: s.name || '', workingDir: s.workingDir || '', mode: s.mode || 'claude', color: s.color || 'default' };
-      }
-      localStorage.setItem('codeman-tab-meta', JSON.stringify(meta));
-    } catch { /* ignore */ }
-  }
-
-  // Restore tabs that were open before refresh but are no longer on the server
-  _restoreEndedTabs() {
-    try {
-      const saved = localStorage.getItem('codeman-tab-meta');
-      if (!saved) return;
-      const meta = JSON.parse(saved);
-      for (const [id, info] of Object.entries(meta)) {
-        if (!this.sessions.has(id)) {
-          // Add a stub session so the tab renders
-          this.sessions.set(id, { id, name: info.name, workingDir: info.workingDir, mode: info.mode, color: info.color, status: 'ended', _ended: true });
-        }
-      }
-    } catch { /* ignore */ }
-  }
-
  // Set up drag-and-drop handlers on tab elements
  setupTabDragHandlers() {
    const container = this.$('sessionTabs');
@@ -2405,6 +2812,13 @@ class CodemanApp {
  }

  async selectSession(sessionId) {
+    // If this session is popped out into its own window, raise that window
+    // instead of showing it inline (focus-on-click for detached tabs).
+    if (!this.isSoloWindow && this.detachedSessions.has(sessionId)) {
+      // Raise the popup instead of showing inline. If we owned a now-closed
+      // window, _raiseDetached re-docks and returns false so we fall through.
+      if (this._raiseDetached(sessionId)) return;
+    }
    if (this.activeSessionId === sessionId) return;
    // Focus terminal SYNCHRONOUSLY before any await — iOS Safari only honors
    // programmatic focus() within the user-gesture call stack (e.g. tab click).
@@ -2424,6 +2838,12 @@ class CodemanApp {
    this._cleanupPreviousSession(sessionId);
    this.activeSessionId = sessionId;
    try { localStorage.setItem('codeman-active-session', sessionId); } catch {}
+    // Narrow SSE filter to the active session — server stops streaming
+    // session:terminal events for other sessions to this client. Cuts
+    // SSE traffic ~Nx for N concurrent sessions. Fire-and-forget; on the
+    // rare race where server doesn't know our clientId yet, the next
+    // selectSession or reconnect catches up.
+    this._updateSseSubscription(sessionId);
    this.hideWelcome();
    // Clear idle hooks on view, but keep action hooks until user interacts
    this.clearPendingHooks(sessionId, 'idle_prompt');
@@ -2454,16 +2874,9 @@ class CodemanApp {
    // Check if this is a restored session that needs to be attached
    const session = this.sessions.get(sessionId);

-    // Ended tabs (restored from localStorage, no longer on server) — show message, skip buffer load
-    if (session?._ended) {
-      this.terminal.clear();
-      this.terminal.write('\r\n  \x1b[2mSession ended. Close tab or click to reopen.\x1b[0m\r\n');
-      return;
-    }
-
    // Track working directory for path normalization in Project Insights
    this.currentSessionWorkingDir = session?.workingDir || null;
-    if (session && session.pid === null && !session._ended) {
+    if (session && session.pid === null) {
      // Session has no PTY attached — either restored after server restart
      // or detached for some other reason. Re-attach regardless of status.
      try {
@@ -2587,19 +3000,15 @@ class CodemanApp {
        });
      }

-      // Fire-and-forget resize + Ctrl+L to force Ink redraw.
-      // Tailed buffers accumulate stale CUP-positioned Ink frames that overlap
-      // in the viewport (e.g. duplicate "bypass permissions" bars). Ctrl+L
-      // triggers a full Ink redraw which overwrites all stale frame content.
-      // sendResize may be a no-op if dimensions match, so Ctrl+L is essential.
-      this.sendResize(sessionId).then(() => {
-        if (selectGen !== this._selectGeneration) return;
-        fetch(`/api/sessions/${sessionId}/input`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ input: '\x0c' })
-        }).catch(() => {});
-      });
+      // Fire-and-forget resize to nudge Ink via SIGWINCH on real size changes.
+      // Previously we also sent Ctrl+L (\x0c) here to force a full Ink redraw,
+      // but Claude Code 2.x treats Ctrl+L as a two-step "clear conversation"
+      // command — if a page refresh or SSE reconnect ran selectSession twice
+      // within Claude's confirmation window, the second \x0c silently wiped the
+      // conversation. Stale Ink frames in the tailed buffer are a cosmetic
+      // annoyance that disappear on the user's next keypress; data loss is not
+      // acceptable. Do NOT re-introduce Ctrl+L here.
+      this.sendResize(sessionId);

      // Defer secondary panel updates so they don't block the main thread
      // after terminal content is already visible.
@@ -71,6 +71,52 @@ const WINDOW_MIN_WIDTH_PX = 200;
 const WINDOW_MIN_HEIGHT_PX = 200;
 const WINDOW_DEFAULT_WIDTH_PX = 300;

+// WebGL renderer auto-fallback thresholds.
+// _installWebGLLongTaskGuard() observes longtask entries and disables WebGL
+// after LONGTASK_COUNT stalls of >= LONGTASK_MS within WINDOW_MS. GRACE_MS
+// suppresses the noisy initial-load stalls. STICKY_EXPIRY_MS is how long
+// localStorage's webgl-disabled marker survives before we retry WebGL on a
+// fresh load (driver/Chrome may have been updated).
+const WEBGL_FALLBACK = {
+  LONGTASK_MS: 200,
+  LONGTASK_COUNT: 3,
+  WINDOW_MS: 30000,
+  GRACE_MS: 5000,
+  STICKY_EXPIRY_MS: 7 * 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Pure rolling-window trip evaluator for the WebGL longtask guard.
+ * Mutates `recent` in place (prunes entries older than `now - WINDOW_MS`)
+ * and appends each new duration's startTime that meets the threshold.
+ * Returns true when the count inside the window reaches `LONGTASK_COUNT`.
+ *
+ * Exposed on `window` for unit testing — the production guard in app.js
+ * inlines this same logic in its PerformanceObserver callback. Splitting it
+ * out keeps the threshold math testable without a real PerformanceObserver.
+ *
+ * @param {number[]} recent - mutable array of startTimes inside the window
+ * @param {{startTime: number, duration: number}[]} entries - new longtask entries
+ * @param {number} now - performance.now() at evaluation time
+ * @param {typeof WEBGL_FALLBACK} [config=WEBGL_FALLBACK] - thresholds
+ * @returns {boolean} true if the rolling window has reached the trip count
+ */
+function evaluateWebGLLongTaskTrip(recent, entries, now, config = WEBGL_FALLBACK) {
+  for (const entry of entries) {
+    if (entry.duration >= config.LONGTASK_MS) recent.push(entry.startTime);
+  }
+  while (recent.length && now - recent[0] > config.WINDOW_MS) recent.shift();
+  return recent.length >= config.LONGTASK_COUNT;
+}
+
+// Expose for tests. `const` declarations at the top of a non-module script
+// are global lexical bindings but not `window` properties, so explicit
+// assignment is the test-visible API surface.
+if (typeof window !== 'undefined') {
+  window.WEBGL_FALLBACK = WEBGL_FALLBACK;
+  window.evaluateWebGLLongTaskTrip = evaluateWebGLLongTaskTrip;
+}
+
 // Scheduler API — prioritize terminal writes over background UI updates.
 // scheduler.postTask('background') defers non-critical work (connection lines, panel renders)
 // so the main thread stays free for terminal rendering at 60fps.
@@ -0,0 +1,200 @@
+/**
+ * Image Input Mixin - Clipboard paste and drag-and-drop image support
+ *
+ * For paste: intercepts Ctrl+V at the xterm keyboard level, creates a temporary
+ * hidden contenteditable div ("paste trap"), lets the browser's native paste fill
+ * it, then checks for image data. This works on HTTP (no secure context needed).
+ *
+ * For drag-and-drop: listens on the terminal container for file drops.
+ *
+ * @dependency app.js (uses global `app` for sendInput, activeSessionId, showToast)
+ * @dependency panels-ui.js (provides showToast)
+ */
+
+Object.assign(CodemanApp.prototype, {
+
+  initImageInput() {
+    // Drag-and-drop handlers on terminal container
+    const container = document.getElementById('terminalContainer');
+    if (!container) return;
+
+    container.addEventListener('dragover', (e) => {
+      e.preventDefault();
+      if (e.dataTransfer && e.dataTransfer.types.includes('Files')) {
+        container.classList.add('drag-active');
+      }
+    });
+
+    container.addEventListener('dragleave', (e) => {
+      if (!container.contains(e.relatedTarget)) {
+        container.classList.remove('drag-active');
+      }
+    });
+
+    container.addEventListener('drop', (e) => {
+      e.preventDefault();
+      container.classList.remove('drag-active');
+
+      if (!this.activeSessionId) return;
+      if (!e.dataTransfer || !e.dataTransfer.files.length) return;
+
+      const imageFiles = Array.from(e.dataTransfer.files).filter((f) => f.type.startsWith('image/'));
+      if (imageFiles.length === 0) {
+        this.showToast('Only image files are supported', 'error');
+        return;
+      }
+      this._uploadAndInsertImages(imageFiles);
+    });
+  },
+
+  // Called from customKeyEventHandler in terminal-ui.js on Ctrl+V keydown.
+  // Creates a hidden paste trap, lets the browser paste into it, then inspects
+  // the result for images. Works on plain HTTP (no Clipboard API needed).
+  _handleImagePaste() {
+    const self = this;
+
+    // Create a hidden contenteditable div to receive the paste
+    const trap = document.createElement('div');
+    trap.contentEditable = 'true';
+    trap.style.cssText = 'position:fixed;left:-9999px;top:0;width:1px;height:1px;opacity:0;overflow:hidden';
+    document.body.appendChild(trap);
+    trap.focus();
+
+    // Listen for the paste event on our trap
+    trap.addEventListener('paste', function(e) {
+      e.stopPropagation();
+
+      // Check for images in clipboard items
+      var imageFiles = [];
+      var items = e.clipboardData && e.clipboardData.items;
+      if (items) {
+        for (var i = 0; i < items.length; i++) {
+          if (items[i].type.startsWith('image/')) {
+            var blob = items[i].getAsFile();
+            if (blob) imageFiles.push(blob);
+          }
+        }
+      }
+
+      // Clean up the trap
+      setTimeout(function() {
+        if (trap.parentNode) trap.parentNode.removeChild(trap);
+        // Refocus the terminal
+        if (self.terminal) self.terminal.focus();
+      }, 0);
+
+      if (imageFiles.length > 0) {
+        e.preventDefault();
+        self._uploadAndInsertImages(imageFiles);
+      } else {
+        // No image -- route text through xterm's paste() so bracketed-paste
+        // markers (CSI 200~ ... CSI 201~) survive when the inner application
+        // has enabled bracketed-paste mode (Claude Code does). Sending text
+        // via raw sendInput() strips those markers and makes pasted input
+        // indistinguishable from typed input, weakening the CLI's
+        // prompt-injection defenses.
+        var text = e.clipboardData ? e.clipboardData.getData('text/plain') : '';
+        e.preventDefault();
+        if (text && self.terminal) self.terminal.paste(text);
+      }
+    });
+
+    // Trigger the browser's native paste via execCommand
+    // (this fires the paste event on our focused trap element)
+    document.execCommand('paste');
+  },
+
+  async _uploadAndInsertImages(files) {
+    const sessionId = this.activeSessionId;
+    if (!sessionId) return;
+
+    this.showToast('Uploading ' + files.length + ' image' + (files.length > 1 ? 's' : '') + '...', 'info');
+
+    const paths = [];
+    for (const file of files) {
+      try {
+        // Re-encode to a standard JPEG/PNG before upload. Galleries on some
+        // phones (notably Android/MIUI) hand back a WebP/HEIF whose filename and
+        // MIME claim "image/jpeg", which passes the server's extension allowlist
+        // but fails its magic-byte check ("bytes do not match declared type").
+        // Decoding through the browser and re-encoding guarantees the bytes
+        // match the extension we send.
+        const normalized = await this._normalizeImageForUpload(file);
+        const path = await this._uploadPasteImage(sessionId, normalized);
+        paths.push(path);
+      } catch (err) {
+        this.showToast('Upload failed: ' + (err.message || 'unknown error'), 'error');
+      }
+    }
+
+    if (paths.length > 0) {
+      const pathStr = paths.join(' ');
+      await this.sendInput(pathStr);
+      this.showToast(paths.length + ' image' + (paths.length > 1 ? 's' : '') + ' ready', 'success');
+    }
+  },
+
+  async _uploadPasteImage(sessionId, file) {
+    const form = new FormData();
+    form.append('image', file);
+
+    const resp = await fetch('/api/sessions/' + sessionId + '/paste-image', {
+      method: 'POST',
+      body: form,
+    });
+
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(data.error || 'HTTP ' + resp.status);
+    }
+
+    const data = await resp.json();
+    return data.path;
+  },
+
+  // Decode an image File through the browser and re-encode it to a format the
+  // server accepts, so the uploaded bytes always match their declared
+  // extension. PNG is re-encoded as PNG (preserves transparency); everything
+  // else (JPEG, WebP, HEIF, unknown) becomes JPEG. Animated GIFs are passed
+  // through untouched since a canvas would flatten them to one frame. On any
+  // decode/encode failure the original file is returned unchanged so the server
+  // still gets a chance (and logs a precise diagnostic).
+  async _normalizeImageForUpload(file) {
+    if (file.type === 'image/gif') return file;
+
+    const toPng = file.type === 'image/png';
+    const url = URL.createObjectURL(file);
+    try {
+      const img = new Image();
+      await new Promise((resolve, reject) => {
+        img.onload = () => resolve();
+        img.onerror = () => reject(new Error('decode failed'));
+        img.src = url;
+      });
+
+      const width = img.naturalWidth;
+      const height = img.naturalHeight;
+      if (!width || !height) return file;
+
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) return file;
+      ctx.drawImage(img, 0, 0);
+
+      const mime = toPng ? 'image/png' : 'image/jpeg';
+      const blob = await new Promise((resolve) => canvas.toBlob(resolve, mime, 0.92));
+      if (!blob) return file;
+
+      const baseName = (file.name || 'image').replace(/\.[^.]+$/, '') || 'image';
+      return new File([blob], baseName + (toPng ? '.png' : '.jpg'), { type: mime });
+    } catch (err) {
+      console.warn('Image re-encode failed, uploading original:', err);
+      return file;
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  },
+
+});
@@ -2,6 +2,10 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
+  <!-- Resolve all relative assets against the site root so the same shell can be
+       served at /session/:id (detached single-session window) without 404ing
+       on relative <script>/<link> URLs. Must precede the first resource tag. -->
+  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  <meta name="description" content="Claude Code session manager with web interface">
  <meta name="theme-color" content="#0a0a0a">
@@ -55,7 +59,9 @@
    <div class="skeleton-toolbar"></div>
  </div>
  <!-- Skip link for keyboard users -->
-  <a href="#terminalContainer" class="skip-link">Skip to terminal</a>
+  <!-- onclick scrolls/focuses directly: with <base href="/"> a bare href="#..." would
+       navigate to /#... (the dashboard) from a /session/:id solo window. -->
+  <a href="#terminalContainer" class="skip-link" onclick="event.preventDefault(); var t=document.getElementById('terminalContainer'); if(t){t.scrollIntoView(); var f=t.querySelector('textarea,[tabindex]'); (f||t).focus&&(f||t).focus();}">Skip to terminal</a>
  <div class="app">
    <!-- Compact Header with Session Tabs -->
    <header class="header">
@@ -67,7 +73,11 @@
      <div class="session-tabs" id="sessionTabs" role="tablist" aria-label="Session tabs">
      </div>

+      <!-- Detached single-session window title (shown only in solo mode) -->
+      <div class="solo-session-title" id="soloSessionTitle" style="display: none;" aria-live="polite"></div>
+
      <div class="header-right">
+        <button class="btn-icon-header btn-solo-redock" id="soloRedockBtn" style="display: none;" onclick="window.close()" title="Re-dock to dashboard (close window)" aria-label="Re-dock session to dashboard">&#x229E;</button>
        <button class="tunnel-indicator" id="tunnelIndicator" style="display: none;" onclick="app.toggleTunnelPanel()" title="Cloudflare Tunnel" aria-label="Tunnel status">
          <span class="tunnel-dot"></span>
        </button>
@@ -97,7 +107,8 @@
          </div>
        </div>
        <button class="btn-icon-header btn-response-viewer-header" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
-        <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications">
+        <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
+        <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
          <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
        </button>
@@ -922,6 +933,16 @@
                  <span class="slider"></span>
                </label>
              </div>
+              <div class="settings-item settings-item-multiline" id="appSettingsGestureControlItem" title="Enable the camera hand-tracking gesture overlay (applied on reload). The instance must run with CODEMAN_GESTURE=1.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Gesture Control (beta)</span>
+                  <span class="settings-item-desc">Camera hand-tracking overlay (applied on reload)</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsGestureControl">
+                  <span class="slider"></span>
+                </label>
+              </div>

              <!-- Header Displays Section -->
              <div class="settings-section-header">Header Displays</div>
@@ -960,6 +981,13 @@
                  <span class="slider"></span>
                </label>
              </div>
+              <div class="settings-item" title="Show the multi-monitor button in the header (opens Codeman spanned across all displays)">
+                <span class="settings-item-label">Multi-monitor Button</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsShowMultiMonitorButton">
+                  <span class="slider"></span>
+                </label>
+              </div>

              <!-- Tab Bar Section -->
              <div class="settings-section-header">Tab Bar</div>
@@ -1104,8 +1132,9 @@
                <option value="high">High</option>
                <option value="xhigh">XHigh</option>
                <option value="max">Max</option>
+                <option value="ultracode">Ultracode (multi-agent workflows)</option>
              </select>
-              <span class="form-hint">Set CLAUDE_CODE_EFFORT_LEVEL for all new sessions (default = no override)</span>
+              <span class="form-hint">Default effort for new Claude sessions — soft default, switchable anytime in-session via /effort (e.g. /effort ultracode)</span>
            </div>
            <!-- Nice Priority Section -->
            <div class="form-section-header">Nice Priority</div>
@@ -1804,5 +1833,6 @@
  <script defer src="ralph-wizard.js"></script>
  <script defer src="api-client.js"></script>
  <script defer src="subagent-windows.js"></script>
+  <script defer src="image-input.js"></script>
 </body>
 </html>
@@ -4,8 +4,10 @@
 * Defines two exports:
 *
 * - KeyboardAccessoryBar (singleton object) — Quick action buttons shown above the virtual
- *   keyboard on mobile: arrow up/down, /init, /clear, /compact, paste, and dismiss.
- *   Destructive actions (/clear, /compact) require double-tap confirmation (2s amber state).
+ *   keyboard on mobile: arrow up/down, /init, /clear, paste, and dismiss.
+ *   The paste button opens a dialog that handles both text paste and image attach
+ *   (native picker + best-effort image paste, routed through app._uploadAndInsertImages).
+ *   Destructive actions (/clear) require double-tap confirmation (2s amber state).
 *   Commands are sent as text + Enter separately for Ink compatibility.
 *   Only initializes on touch devices (MobileDetection.isTouchDevice guard).
 *
@@ -49,7 +51,6 @@ const KeyboardAccessoryBar = {
      </button>
      <button class="accessory-btn" data-action="init" title="/init">/init</button>
      <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
-      <button class="accessory-btn" data-action="compact" title="/compact">/compact</button>
      <button class="accessory-btn" data-action="paste" title="Paste from clipboard">
        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>
@@ -98,7 +99,6 @@ const KeyboardAccessoryBar = {
      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
      <button class="accessory-btn" data-action="init" title="/init">/init</button>
      <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
-      <button class="accessory-btn" data-action="compact" title="/compact">/compact</button>
      <button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
          <path d="M19 9l-7 7-7-7"/>
@@ -128,7 +128,7 @@ const KeyboardAccessoryBar = {
      // Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max']);
      if (refocusActions.has(action) ||
-          ((action === 'clear' || action === 'compact') && this._confirmAction)) {
+          (action === 'clear' && this._confirmAction)) {
        if (typeof app !== 'undefined' && app.terminal) {
          app.terminal.focus();
        }
@@ -191,13 +191,11 @@ const KeyboardAccessoryBar = {
      case 'init':
        this.sendCommand('/init');
        break;
-      case 'clear':
-      case 'compact': {
+      case 'clear': {
        // Require double-tap: first tap turns amber, second tap within 2s sends
-        const cmd = action === 'clear' ? '/clear' : '/compact';
        if (this._confirmAction === action && this._confirmTimer) {
          this.clearConfirm();
-          this.sendCommand(cmd);
+          this.sendCommand('/clear');
        } else {
          this.setConfirm(action, btn);
        }
@@ -264,8 +262,17 @@ const KeyboardAccessoryBar = {
    }).catch(() => {});
  },

-  /** Read clipboard and send contents as input */
-  /** Show a paste overlay with a textarea for iOS compatibility */
+  /** Show a paste overlay for iOS compatibility.
+   *  Handles three input paths from one dialog:
+   *   - Text: long-press the textarea → Paste → Send (unchanged).
+   *   - Image (picker): the "Image" button opens a native file picker
+   *     (accept=image/* → camera / photo library / files), the most reliable
+   *     way to attach a photo on mobile.
+   *   - Image (paste): if the browser exposes image blobs on the textarea's
+   *     paste event, we intercept them and upload directly. Support is spotty
+   *     on mobile, so it is a best-effort enhancement layered on the picker.
+   *  All image paths reuse app._uploadAndInsertImages() (image-input.js), which
+   *  uploads to /api/sessions/:id/paste-image and inserts the saved path. */
  pasteFromClipboard() {
    if (typeof app === 'undefined' || !app.activeSessionId) return;

@@ -274,23 +281,61 @@ const KeyboardAccessoryBar = {
    overlay.className = 'paste-overlay';
    overlay.innerHTML = `
      <div class="paste-dialog">
-        <textarea class="paste-textarea" placeholder="Long-press here and tap Paste"></textarea>
+        <textarea class="paste-textarea" placeholder="Long-press to paste text — or tap 🖼 to attach an image"></textarea>
        <div class="paste-actions">
+          <button class="paste-image">🖼 Image</button>
          <button class="paste-cancel">Cancel</button>
          <button class="paste-send">Send</button>
        </div>
+        <input type="file" class="paste-file-input" accept="image/*" multiple hidden>
      </div>
    `;

    const textarea = overlay.querySelector('.paste-textarea');
-    const send = () => {
+    const fileInput = overlay.querySelector('.paste-file-input');
+
+    const close = () => overlay.remove();
+
+    const sendText = () => {
      const text = textarea.value;
-      overlay.remove();
+      close();
      if (text) app.sendInput(text);
    };
-    overlay.querySelector('.paste-cancel').addEventListener('click', () => overlay.remove());
-    overlay.querySelector('.paste-send').addEventListener('click', send);
-    overlay.addEventListener('click', (e) => { if (e.target === overlay) overlay.remove(); });
+
+    // Filter to images, close the dialog, and hand off to the shared
+    // upload+insert pipeline. Returns true if any image was handled.
+    const handleImages = (files) => {
+      const images = Array.from(files || []).filter((f) => f.type.startsWith('image/'));
+      if (images.length === 0) return false;
+      close();
+      if (typeof app._uploadAndInsertImages === 'function') app._uploadAndInsertImages(images);
+      return true;
+    };
+
+    // Image picker (camera / photo library) — the reliable mobile path.
+    overlay.querySelector('.paste-image').addEventListener('click', () => fileInput.click());
+    fileInput.addEventListener('change', () => handleImages(fileInput.files));
+
+    // Best-effort: capture images pasted straight into the textarea.
+    textarea.addEventListener('paste', (e) => {
+      const items = e.clipboardData && e.clipboardData.items;
+      if (!items) return;
+      const imageFiles = [];
+      for (let i = 0; i < items.length; i++) {
+        if (items[i].type.startsWith('image/')) {
+          const blob = items[i].getAsFile();
+          if (blob) imageFiles.push(blob);
+        }
+      }
+      if (imageFiles.length > 0) {
+        e.preventDefault();
+        handleImages(imageFiles);
+      }
+    });
+
+    overlay.querySelector('.paste-cancel').addEventListener('click', close);
+    overlay.querySelector('.paste-send').addEventListener('click', sendText);
+    overlay.addEventListener('click', (e) => { if (e.target === overlay) close(); });

    document.body.appendChild(overlay);
    textarea.focus();
@@ -1043,7 +1043,7 @@ html.mobile-init .file-browser-panel {
    margin-top: 10px;
  }

-  .paste-cancel, .paste-new, .paste-send {
+  .paste-cancel, .paste-new, .paste-send, .paste-image {
    padding: 8px 18px;
    border: none;
    border-radius: 8px;
@@ -1051,6 +1051,14 @@ html.mobile-init .file-browser-panel {
    cursor: pointer;
  }

+  /* Image attach button — left-aligned, accent outline */
+  .paste-image {
+    margin-right: auto;
+    background: var(--bg-tertiary, #333);
+    color: var(--accent-color, #7aa2f7);
+    border: 1px solid var(--accent-color, #7aa2f7);
+  }
+
  .paste-cancel {
    background: var(--bg-tertiary, #333);
    color: var(--text-secondary, #aaa);
@@ -3129,6 +3129,23 @@ Object.assign(CodemanApp.prototype, {
    this.notificationManager?.toggleDrawer();
  },

+  // Open a Codeman window stretched across all displays (multi-monitor mode).
+  // The server spawns scripts/span-codeman.sh, which launches a fresh, spanning
+  // browser --app window so in-page floating panels can cross the monitor seam.
+  async launchMultiMonitor() {
+    try {
+      const res = await fetch('/api/system/span-displays', { method: 'POST' });
+      const data = await res.json().catch(() => ({}));
+      if (res.ok && data.success) {
+        this.showToast('Opening Codeman across all displays…', 'success');
+      } else {
+        this.showToast(data.error || 'Could not open spanning window', 'error');
+      }
+    } catch (err) {
+      this.showToast('Could not open spanning window: ' + (err?.message || err), 'error');
+    }
+  },
+
  // Alias for showToast
  toast(message, type = 'info') {
    return this.showToast(message, type);
@@ -1032,10 +1032,9 @@ Object.assign(CodemanApp.prototype, {
    const enabledItems = config.generatedPlan?.filter(i => i.enabled);

    try {
-      const envOverrides = this.buildEnvOverrides(
-        this.getCaseSettings(config.caseName),
-        this.loadAppSettingsFromStorage()
-      );
+      const ralphGlobalSettings = this.loadAppSettingsFromStorage();
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(config.caseName), ralphGlobalSettings);
+      const effort = this.getEffortSetting(ralphGlobalSettings);
      const res = await fetch('/api/ralph-loop/start', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
@@ -1047,6 +1046,7 @@ Object.assign(CodemanApp.prototype, {
          enableRespawn: config.enableRespawn,
          planItems: enabledItems?.length ? enabledItems : undefined,
          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          ...(effort ? { effort } : {}),
        }),
      });
      const data = await res.json();
@@ -22,12 +22,24 @@ Object.assign(CodemanApp.prototype, {
    if (caseSettings?.agentTeams || globalSettings?.agentTeamsEnabled) {
      env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
    }
-    if (globalSettings?.thinkingEffort) {
-      env.CLAUDE_CODE_EFFORT_LEVEL = globalSettings.thinkingEffort;
-    }
+    // NOTE: thinkingEffort is intentionally NOT emitted as CLAUDE_CODE_EFFORT_LEVEL —
+    // the env var hard-locks effort and blocks in-session /effort switching (e.g.,
+    // ultracode). It flows as the dedicated `effort` payload field instead, which the
+    // backend injects as a `--settings` soft default. See getEffortSetting().
    return env;
  },

+  /**
+   * Resolve the effort level for new sessions from global settings.
+   * Returns a valid effort string or undefined (= no override, CLI default).
+   * Sent as the `effort` payload field — backend turns it into `claude --settings ...`.
+   */
+  getEffortSetting(globalSettings) {
+    const effort = globalSettings?.thinkingEffort;
+    const valid = ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
+    return valid.includes(effort) ? effort : undefined;
+  },
+
  // ═══════════════════════════════════════════════════════════════
  // Quick Start
  // ═══════════════════════════════════════════════════════════════
@@ -337,6 +349,7 @@ Object.assign(CodemanApp.prototype, {
      const globalSettings = this.loadAppSettingsFromStorage();
      const envOverrides = this.buildEnvOverrides(caseSettings, globalSettings);
      const hasEnvOverrides = Object.keys(envOverrides).length > 0;
+      const effort = this.getEffortSetting(globalSettings);
      const useOpus1m = caseSettings.opusContext1m || globalSettings.opusContext1mEnabled;
      const modelOverride = useOpus1m ? 'opus[1m]' : '';

@@ -349,6 +362,7 @@ Object.assign(CodemanApp.prototype, {
          body: JSON.stringify({
            workingDir, name,
            ...(hasEnvOverrides ? { envOverrides } : {}),
+            ...(effort ? { effort } : {}),
            ...(modelOverride !== undefined ? { modelOverride } : {}),
          })
        }).then(r => r.json())
@@ -538,7 +552,8 @@ Object.assign(CodemanApp.prototype, {
        return;
      }

-      // Quick-start with opencode mode (auto-allow tools by default)
+      // Quick-start with opencode mode (auto-allow tools by default).
+      // No `effort` field — it's Claude-specific (OpenCode has no /effort).
      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
      const res = await fetch('/api/quick-start', {
        method: 'POST',
@@ -312,6 +312,14 @@ Object.assign(CodemanApp.prototype, {
    document.getElementById('appSettingsShowProjectInsights').checked = settings.showProjectInsights ?? defaults.showProjectInsights ?? false;
    document.getElementById('appSettingsShowFileBrowser').checked = settings.showFileBrowser ?? defaults.showFileBrowser ?? false;
    document.getElementById('appSettingsShowSubagents').checked = settings.showSubagents ?? defaults.showSubagents ?? false;
+    document.getElementById('appSettingsShowMultiMonitorButton').checked = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
+    // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
+    // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
+    // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
+    // can't promise something that won't work.
+    const gestureItem = document.getElementById('appSettingsGestureControlItem');
+    if (gestureItem) gestureItem.style.display = window.__codemanGestureAvailable ? '' : 'none';
+    document.getElementById('appSettingsGestureControl').checked = settings.gestureControlEnabled ?? defaults.gestureControlEnabled ?? false;
    document.getElementById('appSettingsSubagentTracking').checked = settings.subagentTrackingEnabled ?? defaults.subagentTrackingEnabled ?? true;
    document.getElementById('appSettingsSubagentActiveTabOnly').checked = settings.subagentActiveTabOnly ?? defaults.subagentActiveTabOnly ?? true;
    document.getElementById('appSettingsImageWatcherEnabled').checked = settings.imageWatcherEnabled ?? defaults.imageWatcherEnabled ?? false;
@@ -1107,6 +1115,9 @@ Object.assign(CodemanApp.prototype, {
  },

  async saveAppSettings() {
+    // Gesture overlay is injected at page render (server-side), so a change to it
+    // only takes effect on reload — remember the prior value to decide below.
+    const _prevGestureEnabled = (this.loadAppSettingsFromStorage().gestureControlEnabled ?? false) === true;
    const settings = {
      defaultClaudeMdPath: document.getElementById('appSettingsClaudeMdPath').value.trim(),
      defaultWorkingDir: document.getElementById('appSettingsDefaultDir').value.trim(),
@@ -1121,6 +1132,8 @@ Object.assign(CodemanApp.prototype, {
      showProjectInsights: document.getElementById('appSettingsShowProjectInsights').checked,
      showFileBrowser: document.getElementById('appSettingsShowFileBrowser').checked,
      showSubagents: document.getElementById('appSettingsShowSubagents').checked,
+      showMultiMonitorButton: document.getElementById('appSettingsShowMultiMonitorButton').checked,
+      gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
      subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
      subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
      imageWatcherEnabled: document.getElementById('appSettingsImageWatcherEnabled').checked,
@@ -1273,6 +1286,18 @@ Object.assign(CodemanApp.prototype, {
    }

    this.closeAppSettings();
+
+    // The gesture overlay is injected at page render (server reads
+    // gestureControlEnabled from settings.json), so a change only takes effect on
+    // reload. Reload when it actually changed — the server PUT above already
+    // persisted the new value.
+    if (settings.gestureControlEnabled !== _prevGestureEnabled) {
+      this.showToast(
+        settings.gestureControlEnabled ? 'Enabling gesture control — reloading…' : 'Disabling gesture control — reloading…',
+        'info'
+      );
+      setTimeout(() => location.reload(), 400);
+    }
  },

  // Load model configuration from server for the settings modal
@@ -1374,6 +1399,9 @@ Object.assign(CodemanApp.prototype, {
        showProjectInsights: false,
        showFileBrowser: false,
        showSubagents: false,
+        showMultiMonitorButton: false,
+        // Input
+        gestureControlEnabled: false,
        // Feature toggles - keep tracking on even on mobile
        subagentTrackingEnabled: true,
        subagentActiveTabOnly: true, // Only show subagents for active tab
@@ -1445,13 +1473,24 @@ Object.assign(CodemanApp.prototype, {
      lifecycleBtn.style.display = showLifecycleLog ? '' : 'none';
    }

-    // Hide notification bell when notifications are disabled
-    const notifEnabled = this.notificationManager?.preferences?.enabled ?? true;
+    // Multi-monitor button — hidden by default (App Settings → Display → "Header
+    // Displays"). The server renders the correct initial state on every reload;
+    // this handles a live toggle from a settings save (no reload). Toggle the
+    // marker class (matches the server-side reveal) rather than an inline style.
+    const showMultiMonitorButton = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
+    const multiMonitorBtn = document.querySelector('.btn-multimonitor');
+    if (multiMonitorBtn) {
+      multiMonitorBtn.classList.toggle('btn-multimonitor--hidden', !showMultiMonitorButton);
+    }
+
+    // Notification bell is retired (notifications live in Settings → Notifications
+    // + the drawer); keep it hidden regardless of the notification-enabled state.
    const notifBtn = document.querySelector('.btn-notifications');
    if (notifBtn) {
-      notifBtn.style.display = notifEnabled ? '' : 'none';
+      notifBtn.style.display = 'none';
    }
    // Close the drawer if notifications got disabled while it's open
+    const notifEnabled = this.notificationManager?.preferences?.enabled ?? true;
    if (!notifEnabled) {
      const drawer = document.getElementById('notifDrawer');
      if (drawer) drawer.classList.remove('open');
@@ -293,7 +293,6 @@ body {
 }
 .session-tab .tab-status.error { background: var(--red); }
 .session-tab .tab-status.ended { background: var(--text-muted); opacity: 0.5; }
-.session-tab[data-ended] { opacity: 0.55; }

 /* Session color coding - left border indicator */
 .session-tab[data-color="red"] { border-left: 3px solid var(--session-red); }
@@ -847,6 +846,13 @@ body {
  transform: rotate(45deg);
 }

+/* Multi-monitor header button: hidden by default (opt-in via App Settings →
+   Display → "Header Displays"). The server strips this class at render when the
+   setting is on; the client toggles it live on save. */
+.btn-multimonitor--hidden {
+  display: none !important;
+}
+
 .btn-icon-header.btn-settings {
  width: 30px;
  height: 30px;
@@ -906,6 +912,97 @@ body {
  transform: rotate(45deg);
 }

+/* ===== Session detach / undock (beta/session-detach) ===================== */
+
+/* Pop-out (detach) icon on each tab — mirrors .tab-gear reveal-on-hover. */
+.session-tab .tab-detach {
+  opacity: 0;
+  width: 0;
+  padding: 0;
+  font-size: 0.95rem;
+  line-height: 1;
+  color: var(--text-muted);
+  cursor: pointer;
+  overflow: hidden;
+  transition: opacity 0.15s, width 0.15s, padding 0.15s;
+}
+.session-tab:hover .tab-detach {
+  opacity: 1;
+  width: auto;
+  padding: 0 0.3rem;
+}
+.session-tab .tab-detach:hover {
+  color: var(--accent-hover);
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 3px;
+}
+
+/* A tab whose session is popped out into its own window. */
+.session-tab.detached {
+  opacity: 0.72;
+}
+.session-tab.detached .tab-detach {
+  /* Keep the pop-out icon visible while detached as a re-focus affordance. */
+  opacity: 1;
+  width: auto;
+  padding: 0 0.3rem;
+  color: var(--accent-hover);
+}
+.session-tab .tab-detached-badge {
+  display: none;
+  align-items: center;
+  font-size: 0.55rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 1px 4px;
+  margin-left: 4px;
+  border-radius: 3px;
+  background: rgba(96, 165, 250, 0.18);
+  color: var(--accent-hover);
+}
+.session-tab.detached .tab-detached-badge {
+  display: inline-flex;
+}
+
+/* ===== Solo (detached single-session) window chrome ===================== */
+body.solo-mode .session-tabs,
+body.solo-mode .header-system-stats,
+body.solo-mode .header-tokens,
+body.solo-mode .btn-notifications,
+body.solo-mode .btn-multimonitor,
+body.solo-mode .btn-lifecycle-log {
+  display: none !important;
+}
+.solo-session-title {
+  flex: 1;
+  min-width: 0;
+  font-weight: 600;
+  font-size: 13px;
+  color: var(--text);
+  padding: 0 12px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+/* "Session unavailable" overlay for a solo window whose session has ended. */
+.solo-gone-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 5000;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  background: rgba(9, 9, 11, 0.92);
+  color: var(--text);
+  text-align: center;
+  padding: 24px;
+}
+.solo-gone-overlay h2 { margin: 0; font-size: 18px; }
+.solo-gone-overlay p { margin: 0; color: var(--text-muted); font-size: 13px; }
+
 /* Mode indicator on session tab */
 .session-tab .tab-mode {
  font-size: 0.6rem;
@@ -2370,6 +2467,56 @@ body {
  color: var(--text);
 }

+.history-detail-actions {
+  margin-top: 0.5rem;
+}
+
+.history-view-all-btn {
+  width: 100%;
+  padding: 0.45rem 0.75rem;
+  background: rgba(99, 179, 237, 0.08);
+  border: 1px solid rgba(99, 179, 237, 0.25);
+  border-radius: 6px;
+  color: rgba(99, 179, 237, 0.95);
+  font-size: 0.78rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background var(--transition-smooth), border-color var(--transition-smooth);
+}
+
+.history-view-all-btn:hover {
+  background: rgba(99, 179, 237, 0.15);
+  border-color: rgba(99, 179, 237, 0.5);
+}
+
+/* Folder history modal */
+.folder-history-modal .modal-body {
+  padding: 0.75rem 1rem 1rem;
+}
+
+.folder-history-subtitle {
+  color: var(--text-muted);
+  font-size: 0.78rem;
+  font-family: 'SF Mono', Menlo, Consolas, monospace;
+  word-break: break-all;
+  margin-bottom: 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.folder-history-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.folder-history-empty {
+  padding: 2rem 0.5rem;
+  text-align: center;
+  color: var(--text-muted);
+  font-size: 0.85rem;
+}
+
 .welcome-hint {
  color: var(--text-muted);
  font-size: 0.8rem;
@@ -7922,14 +8069,15 @@ kbd {
  bottom: 0;
  left: 0;
  right: 0;
-  max-height: 85vh;
-  background: #1a1a2e;
-  border-top: 1px solid #333;
-  border-radius: 12px 12px 0 0;
+  max-height: 88vh;
+  background: #14141f;
+  border-top: 1px solid #2a2a3a;
+  border-radius: 14px 14px 0 0;
+  box-shadow: 0 -8px 32px rgba(0, 0, 0, 0.45);
  z-index: 5000;
  flex-direction: column;
  transform: translateY(100%);
-  transition: transform 0.25s ease-out;
+  transition: transform 0.28s cubic-bezier(0.22, 1, 0.36, 1);
 }

 .response-viewer.visible {
@@ -7941,12 +8089,13 @@ kbd {
  display: flex;
  align-items: center;
  justify-content: space-between;
-  padding: 12px 16px;
-  border-bottom: 1px solid #333;
+  padding: 14px 20px;
+  border-bottom: 1px solid #2a2a3a;
  flex-shrink: 0;
  font-size: 14px;
  font-weight: 600;
-  color: #e0e0e0;
+  color: #e8e8ec;
+  letter-spacing: 0.2px;
 }

 .response-viewer-actions {
@@ -8029,42 +8178,80 @@ kbd {
  background: rgba(109, 219, 127, 0.12);
 }

-/* Markdown rendered content inside response viewer */
-.rv-text {
-  word-break: break-word;
-  line-height: 1.6;
+/* Markdown rendered content inside response viewer.
+   Prose uses a proportional font for readability; code keeps monospace. */
+.rv-text,
+.response-viewer-body > :not(.rv-message) {
+  word-break: normal;
+  overflow-wrap: anywhere;
+  line-height: 1.7;
 }

-.rv-text p {
-  margin: 0 0 0.6em;
+.rv-text p,
+.response-viewer-body > p {
+  margin: 0 0 0.85em;
 }

-.rv-text p:last-child {
+.rv-text p:last-child,
+.response-viewer-body > p:last-child {
  margin-bottom: 0;
 }

-.rv-text h1, .rv-text h2, .rv-text h3, .rv-text h4 {
-  color: #e0e0e0;
-  margin: 1em 0 0.4em;
+.rv-text h1, .rv-text h2, .rv-text h3, .rv-text h4,
+.response-viewer-body > h1, .response-viewer-body > h2,
+.response-viewer-body > h3, .response-viewer-body > h4 {
+  color: #f2f2f6;
+  margin: 1.4em 0 0.5em;
  line-height: 1.3;
+  font-weight: 700;
+  letter-spacing: -0.01em;
 }

-.rv-text h1 { font-size: 1.3em; }
-.rv-text h2 { font-size: 1.15em; }
-.rv-text h3 { font-size: 1.05em; }
+.rv-text h1:first-child, .rv-text h2:first-child,
+.response-viewer-body > h1:first-child, .response-viewer-body > h2:first-child {
+  margin-top: 0;
+}

-.rv-text code {
-  background: #2a2a3e;
-  padding: 1px 5px;
-  border-radius: 3px;
+.rv-text h1, .response-viewer-body > h1 {
+  font-size: 1.55em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid #2d2d40;
+}
+.rv-text h2, .response-viewer-body > h2 {
+  font-size: 1.3em;
+  color: #ffd27a;
+}
+.rv-text h3, .response-viewer-body > h3 {
+  font-size: 1.13em;
+  color: #bfc8ff;
+}
+.rv-text h4, .response-viewer-body > h4 {
+  font-size: 1em;
+  color: #c9c9d5;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.rv-text code,
+.response-viewer-body > :not(pre) code {
+  background: #262638;
+  color: #ffb4a2;
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-family: 'Fira Code', 'JetBrains Mono', 'SF Mono', Menlo, Monaco, monospace;
  font-size: 0.9em;
 }

-.rv-text pre {
-  background: #1e1e2e;
-  border: 1px solid #333;
-  border-radius: 6px;
-  padding: 10px 12px;
+/* Descendant (not child) combinator: code blocks are wrapped in .rv-code-wrap,
+   so the latest-response view (markdown rendered straight into the body) nests
+   <pre> one level deeper than a direct child. The historical .rv-text path
+   already matched via descendant; keep both in lockstep. */
+.rv-text pre,
+.response-viewer-body pre {
+  background: #0f0f1a;
+  border: 1px solid #2a2a3d;
+  border-radius: 8px;
+  padding: 14px 16px;
  overflow-x: auto;
  margin: 1em 0;
  -webkit-overflow-scrolling: touch;
@@ -8076,7 +8263,7 @@ kbd {
   Preserve indentation (pre-wrap) but allow breaks inside long tokens
   (URLs, paths, identifiers) so they don't overflow. */
 .rv-text pre code,
-.response-viewer-body > pre code {
+.response-viewer-body pre code {
  background: none;
  color: #e6e6f0;
  padding: 0;
@@ -8174,41 +8361,114 @@ kbd {
  content: '⤢';
 }

+/* ── Code block one-click copy ──────────────────────────────────────────────
+   Every fenced code block is wrapped in .rv-code-wrap with an action toolbar
+   pinned to its top-right. Regular blocks get the relative positioning here;
+   ASCII diagrams already get it from .rv-diagram-wrap (don't clobber its
+   centering margins). */
+.rv-text .rv-code-wrap:not(.rv-diagram-wrap),
+.response-viewer-body .rv-code-wrap:not(.rv-diagram-wrap) {
+  position: relative;
+  margin: 1em 0;
+}
+
+.rv-text .rv-code-wrap:not(.rv-diagram-wrap) > pre,
+.response-viewer-body .rv-code-wrap:not(.rv-diagram-wrap) > pre {
+  margin: 0;
+  padding-right: 44px;    /* reserve room for the copy button */
+}
+
+/* Diagrams carry two buttons (copy + wrap toggle) — widen the reserve. */
+.rv-text .rv-code-wrap.rv-diagram-wrap > pre.rv-diagram,
+.response-viewer-body .rv-code-wrap.rv-diagram-wrap > pre.rv-diagram {
+  padding-right: 76px;
+}
+
+.rv-code-actions {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  display: inline-flex;
+  gap: 4px;
+  z-index: 2;
+}
+
+/* Inside the flex toolbar the wrap toggle flows normally — drop its own pin. */
+.rv-code-actions .rv-wrap-toggle {
+  position: static;
+  top: auto;
+  right: auto;
+}
+
+.rv-copy-btn {
+  width: 28px;
+  height: 24px;
+  padding: 0;
+  border: 1px solid #2f2f45;
+  border-radius: 5px;
+  background: rgba(20, 20, 32, 0.92);
+  color: #8b8b97;
+  font-size: 13px;
+  line-height: 1;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transition: color 0.15s, border-color 0.15s;
+}
+
+.rv-copy-btn:hover,
+.rv-copy-btn:active {
+  color: #e0e0ec;
+  border-color: #4a4a65;
+}
+
+.rv-copy-btn::before { content: '\2398'; }            /* ⎘ — matches file-preview copy */
+.rv-copy-btn.rv-copied { color: #9ece6a; border-color: #3a5a3a; }
+.rv-copy-btn.rv-copied::before { content: '\2713'; }  /* ✓ */
+.rv-copy-btn.rv-copy-failed { color: #f7768e; border-color: #5a3a3a; }
+.rv-copy-btn.rv-copy-failed::before { content: '\2715'; } /* ✕ */
+
 .rv-text ul, .rv-text ol,
 .response-viewer-body > ul, .response-viewer-body > ol {
  margin: 0.6em 0;
+  padding-left: 1.5em;
 }

-.rv-text pre code {
-  background: none;
-  padding: 0;
-  font-size: 0.85em;
-  line-height: 1.5;
+.rv-text li,
+.response-viewer-body > ul > li, .response-viewer-body > ol > li {
+  margin-bottom: 0.3em;
 }

-.rv-text ul, .rv-text ol {
-  margin: 0.4em 0;
-  padding-left: 1.4em;
+.rv-text li > p { margin: 0.2em 0; }
+
+.rv-text blockquote,
+.response-viewer-body > blockquote {
+  border-left: 3px solid #5c7cfa;
+  background: rgba(92, 124, 250, 0.06);
+  margin: 0.8em 0;
+  padding: 0.5em 14px;
+  color: #b8b8c8;
+  border-radius: 0 6px 6px 0;
 }

-.rv-text li {
-  margin-bottom: 0.2em;
+.rv-text strong,
+.response-viewer-body > p strong,
+.response-viewer-body > li strong {
+  color: #ffffff;
+  font-weight: 700;
 }

-.rv-text blockquote {
-  border-left: 3px solid #444;
-  margin: 0.6em 0;
-  padding: 0.3em 0 0.3em 12px;
-  color: #999;
+.rv-text em,
+.response-viewer-body em {
+  color: #e0e0ec;
 }

-.rv-text strong {
-  color: #f0f0f0;
-}
-
-.rv-text a {
-  color: #5c7cfa;
+.rv-text a,
+.response-viewer-body a {
+  color: #7aa2ff;
  text-decoration: none;
+  border-bottom: 1px solid rgba(122, 162, 255, 0.35);
 }

 .rv-text a:hover,
@@ -8286,19 +8546,37 @@ kbd {
 .rv-text hr,
 .response-viewer-body > hr {
  border: none;
-  border-top: 1px solid #333;
-  margin: 1em 0;
+  border-top: 1px solid #2d2d40;
+  margin: 1.5em 0;
 }

 .response-viewer-body {
  flex: 1;
  overflow-y: auto;
  -webkit-overflow-scrolling: touch;
-  padding: 16px;
-  font-family: 'Fira Code', 'Cascadia Code', 'JetBrains Mono', 'SF Mono', Monaco, monospace;
-  font-size: 13px;
-  line-height: 1.5;
-  color: #d4d4d4;
+  overscroll-behavior: contain;
+  padding: 20px 22px 28px;
+  /* Proportional font for prose — monospace only for code/pre */
+  font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'PingFang SC',
+    'Hiragino Sans GB', 'Segoe UI', 'Helvetica Neue', Helvetica, Arial,
+    'Noto Sans CJK SC', sans-serif;
+  font-size: 15px;
+  line-height: 1.7;
+  color: #d8d8e0;
+  /* Comfortable reading width on wider viewports */
+  --rv-content-max: 720px;
+}
+
+/* Constrain content width for readability; code blocks can still scroll horizontally */
+.response-viewer-body > * {
+  max-width: var(--rv-content-max);
+  margin-left: auto;
+  margin-right: auto;
+}
+.response-viewer-body > pre,
+.response-viewer-body > table,
+.response-viewer-body > .rv-message {
+  max-width: var(--rv-content-max);
 }

 .response-viewer-body:empty::after {
@@ -8591,3 +8869,23 @@ kbd {
  margin-top: 4px;
  font-size: 0.7rem;
 }
+
+/* Image drag-and-drop overlay */
+#terminalContainer.drag-active {
+  outline: 2px dashed #4a9eff;
+  outline-offset: -2px;
+  position: relative;
+}
+#terminalContainer.drag-active::after {
+  content: 'Drop image here';
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(74, 158, 255, 0.08);
+  color: #4a9eff;
+  font-size: 1.2rem;
+  pointer-events: none;
+  z-index: 100;
+}
@@ -83,6 +83,15 @@ Object.assign(CodemanApp.prototype, {
      // Let Alt+digit pass through to browser (tab switching)
      if (ev.altKey && ev.key >= '0' && ev.key <= '9') return false;

+      // 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') {
+        if (this.activeSessionId && this._handleImagePaste) {
+          this._handleImagePaste();
+        }
+        return false;
+      }
+
      // Shift+Enter / Ctrl+Enter: insert newline for multi-line input.
      // xterm.js sends plain \r for all Enter variants, so Claude Code (Ink) can't
      // distinguish them. We use tmux send-keys -H to send a line feed byte (0x0a)
@@ -174,10 +183,37 @@ Object.assign(CodemanApp.prototype, {
    // but the 48KB/frame flush cap in flushPendingWrites() now prevents
    // oversized terminal.write() calls that triggered the stalls.
    // Disable with ?nowebgl URL param if GPU issues return.
+    // Auto-fallback: _initWebGL installs a long-task watchdog that disables
+    // WebGL sticky in localStorage after repeated GPU stalls (see app.js).
+    // Force re-enable after sticky disable with ?webgl=force.
    // Lazy-loaded: script downloaded only on desktop (saves 244KB on mobile).
    this._webglAddon = null;
-    const skipWebGL = MobileDetection.getDeviceType() !== 'desktop';
-    if (!skipWebGL && !new URLSearchParams(location.search).has('nowebgl')) {
+    const _params = new URLSearchParams(location.search);
+    if (_params.get('webgl') === 'force') {
+      try { localStorage.removeItem('codeman-webgl-disabled'); } catch {}
+    }
+    const _stickyDisabled = (() => {
+      try {
+        const raw = localStorage.getItem('codeman-webgl-disabled');
+        if (!raw) return false;
+        const { at } = JSON.parse(raw);
+        // Auto-expire after WEBGL_FALLBACK.STICKY_EXPIRY_MS so we retry
+        // (driver/Chrome may have been updated).
+        if (Date.now() - at > WEBGL_FALLBACK.STICKY_EXPIRY_MS) {
+          localStorage.removeItem('codeman-webgl-disabled');
+          return false;
+        }
+        return true;
+      } catch { return false; }
+    })();
+    const skipWebGL =
+      MobileDetection.getDeviceType() !== 'desktop' ||
+      _params.has('nowebgl') ||
+      _stickyDisabled;
+    if (_stickyDisabled) {
+      console.log('[CRASH-DIAG] WebGL sticky-disabled from prior stalls — DOM renderer in use. Re-enable: ?webgl=force');
+    }
+    if (!skipWebGL) {
      if (typeof WebglAddon !== 'undefined') {
        this._initWebGL();
      } else {
@@ -341,6 +377,9 @@ Object.assign(CodemanApp.prototype, {
    // Welcome message
    this.showWelcome();

+    // Image paste and drag-and-drop support
+    this.initImageInput();
+
    // Generation counter for chunkedTerminalWrite — aborts stale writes on tab switch
    this._chunkedWriteGen = 0;

@@ -405,7 +444,6 @@ Object.assign(CodemanApp.prototype, {
            if (
              activeResizeSession &&
              activeResizeSession.mode !== 'shell' &&
-              !activeResizeSession._ended &&
              this.terminal &&
              this.isTerminalAtBottom()
            ) {
@@ -879,8 +917,15 @@ Object.assign(CodemanApp.prototype, {
      .replace(/^\/Users\/[^/]+\//, '~/');
  },

-  /** Build a single history item DOM element */
-  _buildHistoryItem(s, cases) {
+  /**
+   * Build a single history item DOM element.
+   * @param {object} s session record
+   * @param {Array} cases linked cases (for #caseName label)
+   * @param {object} [options]
+   * @param {boolean} [options.showViewAll=true] show "View all in folder" button in detail panel
+   */
+  _buildHistoryItem(s, cases, options) {
+    const showViewAll = options?.showViewAll !== false;
    const size =
      s.sizeBytes < 1024
        ? `${s.sizeBytes}B`
@@ -962,6 +1007,21 @@ Object.assign(CodemanApp.prototype, {

    detail.append(promptRow, pathRow, metaRow);

+    if (showViewAll && s.projectKey) {
+      const actionRow = document.createElement('div');
+      actionRow.className = 'history-detail-row history-detail-actions';
+      const viewAllBtn = document.createElement('button');
+      viewAllBtn.type = 'button';
+      viewAllBtn.className = 'history-view-all-btn';
+      viewAllBtn.textContent = 'View all in this folder';
+      viewAllBtn.addEventListener('click', (ev) => {
+        ev.stopPropagation();
+        this.openFolderHistoryModal(s.projectKey, s.workingDir, cases);
+      });
+      actionRow.appendChild(viewAllBtn);
+      detail.appendChild(actionRow);
+    }
+
    expandBtn.addEventListener('click', (ev) => {
      ev.stopPropagation();
      const expanded = item.classList.toggle('expanded');
@@ -1025,9 +1085,144 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  /** Page size for the folder history modal */
+  _FOLDER_HISTORY_PAGE_SIZE: 20,
+
+  /**
+   * Open a modal showing all history sessions in a single folder.
+   * Paginated by FOLDER_HISTORY_PAGE_SIZE; "Show more" loads next page.
+   */
+  openFolderHistoryModal(projectKey, workingDir, cases) {
+    // Close any existing instance first
+    this._closeFolderHistoryModal();
+
+    const modal = document.createElement('div');
+    modal.className = 'modal active folder-history-modal';
+    modal.id = 'folderHistoryModal';
+
+    const backdrop = document.createElement('div');
+    backdrop.className = 'modal-backdrop';
+    backdrop.addEventListener('click', () => this._closeFolderHistoryModal());
+
+    const content = document.createElement('div');
+    content.className = 'modal-content modal-lg';
+
+    const header = document.createElement('div');
+    header.className = 'modal-header';
+    const title = document.createElement('h3');
+    title.textContent = 'Folder History';
+    const subtitle = document.createElement('div');
+    subtitle.className = 'folder-history-subtitle';
+    subtitle.textContent = this._shortenHomePath(workingDir);
+    const closeBtn = document.createElement('button');
+    closeBtn.className = 'modal-close';
+    closeBtn.setAttribute('aria-label', 'Close');
+    closeBtn.innerHTML = '&times;';
+    closeBtn.addEventListener('click', () => this._closeFolderHistoryModal());
+    header.append(title, closeBtn);
+
+    const body = document.createElement('div');
+    body.className = 'modal-body';
+    const list = document.createElement('div');
+    list.className = 'folder-history-list';
+    list.setAttribute('data-loading', 'true');
+    list.textContent = 'Loading...';
+    body.append(subtitle, list);
+
+    content.append(header, body);
+    modal.append(backdrop, content);
+    document.body.appendChild(modal);
+
+    // Track state for pagination
+    this._folderHistoryState = {
+      projectKey,
+      workingDir,
+      cases: cases || [],
+      offset: 0,
+      total: null,
+      list,
+    };
+
+    // ESC to close
+    this._folderHistoryEscHandler = (ev) => {
+      if (ev.key === 'Escape') this._closeFolderHistoryModal();
+    };
+    document.addEventListener('keydown', this._folderHistoryEscHandler);
+
+    this._loadFolderHistoryPage();
+  },
+
+  async _loadFolderHistoryPage() {
+    const state = this._folderHistoryState;
+    if (!state) return;
+    const { projectKey, cases, list } = state;
+    const limit = this._FOLDER_HISTORY_PAGE_SIZE;
+    const offset = state.offset;
+
+    // Remove existing "Show more" button while loading
+    const existingMore = list.querySelector('.folder-history-more');
+    if (existingMore) existingMore.remove();
+
+    // First page: clear loading placeholder
+    if (offset === 0) {
+      list.replaceChildren();
+      list.removeAttribute('data-loading');
+    }
+
+    try {
+      const url = `/api/history/sessions?projectKey=${encodeURIComponent(projectKey)}&offset=${offset}&limit=${limit}`;
+      const res = await fetch(url);
+      const data = await res.json();
+      const sessions = data.sessions || [];
+      state.total = typeof data.total === 'number' ? data.total : sessions.length + offset;
+
+      if (offset === 0 && sessions.length === 0) {
+        const empty = document.createElement('div');
+        empty.className = 'folder-history-empty';
+        empty.textContent = 'No conversations found in this folder.';
+        list.appendChild(empty);
+        return;
+      }
+
+      for (const s of sessions) {
+        list.appendChild(this._buildHistoryItem(s, cases, { showViewAll: false }));
+      }
+
+      state.offset = offset + sessions.length;
+
+      // Add "Show more" if there are more sessions
+      if (state.offset < state.total) {
+        const remaining = state.total - state.offset;
+        const moreBtn = document.createElement('button');
+        moreBtn.className = 'history-show-more folder-history-more';
+        moreBtn.textContent = `Show ${Math.min(limit, remaining)} more (${remaining} remaining)`;
+        moreBtn.addEventListener('click', () => this._loadFolderHistoryPage());
+        list.appendChild(moreBtn);
+      }
+    } catch (err) {
+      console.error('[loadFolderHistoryPage]', err);
+      const errorEl = document.createElement('div');
+      errorEl.className = 'folder-history-empty';
+      errorEl.textContent = 'Failed to load folder history.';
+      list.appendChild(errorEl);
+    }
+  },
+
+  _closeFolderHistoryModal() {
+    const modal = document.getElementById('folderHistoryModal');
+    if (modal) modal.remove();
+    if (this._folderHistoryEscHandler) {
+      document.removeEventListener('keydown', this._folderHistoryEscHandler);
+      this._folderHistoryEscHandler = null;
+    }
+    this._folderHistoryState = null;
+  },
+
  async resumeHistorySession(sessionId, workingDir) {
    // Close the run mode menu if open
    document.getElementById('runModeMenu')?.classList.remove('active');
+    // Close folder history modal if open
+    this._closeFolderHistoryModal();
    try {
      this.terminal.clear();
      this.terminal.writeln(`\x1b[1;32m Resuming conversation ${sessionId.slice(0, 8)}...\x1b[0m`);
@@ -1049,7 +1244,9 @@ Object.assign(CodemanApp.prototype, {
      // Match by path (not basename) so linked/renamed cases still resolve correctly.
      const matchingCase = (this.cases || []).find((c) => c.path === workingDir);
      const caseName = matchingCase?.name || workingDir.split('/').pop() || '';
-      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const globalSettings = this.loadAppSettingsFromStorage();
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), globalSettings);
+      const effort = this.getEffortSetting(globalSettings);
      const createRes = await fetch('/api/sessions', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
@@ -1058,6 +1255,7 @@ Object.assign(CodemanApp.prototype, {
          name,
          resumeSessionId: sessionId,
          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          ...(effort ? { effort } : {}),
        }),
      });
      const createData = await createRes.json();
@@ -1151,7 +1349,7 @@ Object.assign(CodemanApp.prototype, {

    if (!this.writeFrameScheduled) {
      this.writeFrameScheduled = true;
-      requestAnimationFrame(() => {
+      this._safeYield(() => {
        // xterm.js 6.0 handles DEC 2026 sync markers natively — it buffers
        // content between 2026h/2026l and renders atomically. No need for
        // client-side incomplete-block detection; just flush every frame.
@@ -1176,7 +1374,7 @@ Object.assign(CodemanApp.prototype, {
    // Trigger a normal flush
    if (!this.writeFrameScheduled) {
      this.writeFrameScheduled = true;
-      requestAnimationFrame(() => {
+      this._safeYield(() => {
        this.flushPendingWrites();
        this.writeFrameScheduled = false;
      });
@@ -1264,7 +1462,7 @@ Object.assign(CodemanApp.prototype, {
      deferred = true;
      if (!this.writeFrameScheduled) {
        this.writeFrameScheduled = true;
-        requestAnimationFrame(() => {
+        this._safeYield(() => {
          this.flushPendingWrites();
          this.writeFrameScheduled = false;
        });
@@ -1336,9 +1534,70 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  /**
+   * Schedule cb via THREE racing primitives so data-pacing makes progress
+   * regardless of which scheduling primitive Chrome is throttling:
+   *   1. requestAnimationFrame — primary, fires at compositor rate
+   *      (may be 0Hz when window is occluded / on backgrounded monitor).
+   *   2. setTimeout(50) — fallback for occluded-but-visible windows
+   *      (clamped to 1Hz by Chrome's intensive wake-up throttling
+   *      after ~5 min of no user interaction).
+   *   3. Worker postMessage — bypasses intensive throttling entirely;
+   *      Workers are not subject to background-tab / idle-tab throttling
+   *      (the React Scheduler trick).
+   * Whichever fires first wins; the others are no-ops thanks to the
+   * `done` guard. Without all three, chunkedTerminalWrite and the deferred
+   * path of flushPendingWrites stall indefinitely when the substrate is
+   * degraded (visible-but-occluded window, OR idle-throttled tab, OR
+   * background tab on a different monitor).
+   */
+  _safeYield(cb) {
+    let done = false;
+    const wrapped = () => {
+      if (done) return;
+      done = true;
+      cb();
+    };
+    requestAnimationFrame(wrapped);
+    setTimeout(wrapped, 50);
+    this._workerYield(wrapped);
+  },
+
+  /**
+   * Lazy-init a tiny "tick" worker whose only job is to postMessage back to
+   * us as fast as possible, escaping main-thread throttling. The worker's
+   * setTimeout(0) is not subject to Chrome's intensive wake-up throttling
+   * even when the parent tab is idle.
+   */
+  _workerYield(cb) {
+    try {
+      if (this._yieldWorker === undefined) {
+        // First call: build the worker (or mark unavailable). Each
+        // postMessage in produces exactly one postMessage out — we count on
+        // FIFO 1:1 to drain queue entries.
+        const src = "onmessage=()=>setTimeout(()=>postMessage(0),0);";
+        const blob = new Blob([src], { type: 'application/javascript' });
+        const url = URL.createObjectURL(blob);
+        this._yieldWorker = new Worker(url);
+        URL.revokeObjectURL(url);
+        this._yieldQueue = [];
+        this._yieldWorker.onmessage = () => {
+          const fn = this._yieldQueue.shift();
+          if (fn) fn();
+        };
+      }
+      if (!this._yieldWorker) return;
+      this._yieldQueue.push(cb);
+      this._yieldWorker.postMessage(0);
+    } catch {
+      this._yieldWorker = null; // mark unavailable, future calls skip
+    }
+  },
+
  /**
   * Write large buffer to terminal in chunks to avoid UI jank.
-   * Uses requestAnimationFrame to spread work across frames.
+   * Uses _safeYield to spread work across frames; falls back to setTimeout
+   * and a tick-Worker so progress continues on occluded / idle-throttled tabs.
   * @param {string} buffer - The full terminal buffer to write
   * @param {number} chunkSize - Size of each chunk (default 128KB for smooth 60fps)
   * @returns {Promise<void>} - Resolves when all chunks written
@@ -1397,7 +1656,7 @@ Object.assign(CodemanApp.prototype, {
            `[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`
          );
          // Wait one more frame for xterm to finish rendering before resolving
-          requestAnimationFrame(finish);
+          this._safeYield(finish);
          return;
        }

@@ -1412,12 +1671,13 @@ Object.assign(CodemanApp.prototype, {
          );
        offset += chunkSize;

-        // Schedule next chunk on next frame
-        requestAnimationFrame(writeChunk);
+        // Schedule next chunk; rAF if possible, else setTimeout/Worker
+        // fallback so progress doesn't stall on occluded/unfocused windows.
+        this._safeYield(writeChunk);
      };

      // Start writing
-      requestAnimationFrame(writeChunk);
+      this._safeYield(writeChunk);
    });
  },

@@ -1447,7 +1707,8 @@ Object.assign(CodemanApp.prototype, {
  /**
   * Restore terminal size to match web UI dimensions.
   * Use this after mobile screen attachment has squeezed the terminal.
-   * Sends resize to PTY and Ctrl+L to trigger Claude to redraw.
+   * Sends only resize — SIGWINCH triggers Ink redraw on real dimension changes.
+   * Ctrl+L is NOT sent here (Claude Code 2.x treats it as "clear conversation").
   */
  async restoreTerminalSize() {
    if (!this.activeSessionId) {
@@ -1462,16 +1723,10 @@ Object.assign(CodemanApp.prototype, {
    }

    try {
-      // Send resize to restore proper dimensions (with minimum enforcement)
+      // Send resize to restore proper dimensions (with minimum enforcement).
+      // The PTY's SIGWINCH on real dim change is enough for Ink to redraw.
      await this.sendResize(this.activeSessionId);

-      // Send Ctrl+L to trigger Claude to redraw at new size
-      await fetch(`/api/sessions/${this.activeSessionId}/input`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ input: '\x0c' }),
-      });
-
      this.showToast(`Terminal restored to ${dims.cols}x${dims.rows}`, 'success');
    } catch (err) {
      console.error('Failed to restore terminal size:', err);
@@ -1479,26 +1734,20 @@ Object.assign(CodemanApp.prototype, {
    }
  },

-  // Send Ctrl+L to fix display for newly created sessions once Claude is running
-  sendPendingCtrlL(sessionId) {
-    if (!this.pendingCtrlL || !this.pendingCtrlL.has(sessionId)) {
-      return;
-    }
-    this.pendingCtrlL.delete(sessionId);
-
-    // Only send if this is the active session
-    if (sessionId !== this.activeSessionId) {
-      return;
-    }
-
-    // Send resize + Ctrl+L to fix the display (with minimum dimension enforcement)
-    this.sendResize(sessionId).then(() => {
-      fetch(`/api/sessions/${sessionId}/input`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ input: '\x0c' }),
-      });
-    });
+  // Vestigial no-op: this method has no callers today. It's kept (not deleted)
+  // as a documented guard so the Ctrl+L behavior below isn't reintroduced.
+  //
+  // Originally this sent Ctrl+L (\x0c) when a flagged session first reached
+  // idle/working to scrub mux-init junk from the screen. Two problems:
+  //   1. `pendingCtrlL` was never actually populated anywhere (dead path).
+  //   2. Claude Code 2.x interprets Ctrl+L as a two-step "clear conversation"
+  //      command — sending it from background flows risked nuking the user's
+  //      conversation if it coincided with another Ctrl+L (e.g. from
+  //      selectSession on page reload).
+  // If a per-session display-fix is ever needed again, do it via sendResize
+  // or an Ink-safe control sequence, NOT \x0c.
+  sendPendingCtrlL(_sessionId) {
+    // intentionally empty
  },

  async copyTerminal() {
@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Shared Fastify error handler for Codeman's HTTP routes.
+ *
+ * Route helpers (`findSessionOrFail`, `parseBody` in route-helpers.ts) throw
+ * structured errors carrying `{ statusCode, body }`. This handler renders them
+ * into the proper HTTP response. It is installed by BOTH the production server
+ * and the route test harness so test behavior matches production exactly —
+ * without it, thrown errors fall through to Fastify's default handler and the
+ * response body is `{statusCode,error,message}` instead of `{success:false,...}`.
+ */
+import type { FastifyInstance } from 'fastify';
+import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../types.js';
+
+/**
+ * Install the global error handler that renders structured route errors.
+ * Errors thrown with a `statusCode`/`body` (see route-helpers.ts) are sent
+ * verbatim at that status; anything else becomes a 500 OPERATION_FAILED response.
+ */
+export function installRouteErrorHandler(app: FastifyInstance): void {
+  app.setErrorHandler((error, _req, reply) => {
+    const statusCode = (error as { statusCode?: number }).statusCode ?? 500;
+    const body = (error as { body?: unknown }).body;
+    if (body) {
+      reply.code(statusCode).send(body);
+    } else {
+      reply.code(statusCode).send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(error)));
+    }
+  });
+}
@@ -16,10 +16,12 @@ import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.j
 import { SseEvent } from './sse-events.js';
 import type { SessionPort } from './ports/session-port.js';
 import type { EventPort } from './ports/event-port.js';
+import { dataPath } from '../config/instance.js';

-// Shared path constants used across route modules
+// Shared path constants used across route modules. CASES_DIR (project folders)
+// stays shared across instances; SETTINGS_PATH is per-instance runtime state.
 export const CASES_DIR = join(homedir(), 'codeman-cases');
-export const SETTINGS_PATH = join(homedir(), '.codeman', 'settings.json');
+export const SETTINGS_PATH = dataPath('settings.json');

 /**
 * Validates that a path component doesn't escape the base directory.
@@ -17,8 +17,9 @@ import { writeHooksConfig } from '../../hooks-config.js';
 import { CASES_DIR, SETTINGS_PATH, validatePathWithinBase, parseBody, readJsonConfig } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { EventPort, ConfigPort } from '../ports/index.js';
+import { dataPath, getDataDir } from '../../config/instance.js';

-const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
+const LINKED_CASES_FILE = dataPath('linked-cases.json');
 const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;

 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
@@ -151,7 +152,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    // Save the linked case
    linkedCases[name] = expandedPath;
    try {
-      const codemanDir = join(homedir(), '.codeman');
+      const codemanDir = getDataDir();
      if (!existsSync(codemanDir)) {
        mkdirSync(codemanDir, { recursive: true });
      }
@@ -206,7 +207,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    const { order } = parseBody(CaseOrderSchema, req.body, 'Invalid order data');

    try {
-      const dir = join(homedir(), '.codeman');
+      const dir = getDataDir();
      if (!existsSync(dir)) {
        mkdirSync(dir, { recursive: true });
      }
@@ -268,8 +268,16 @@ export function registerRalphRoutes(
      );
    }

-    const { caseName, taskDescription, completionPhrase, maxIterations, enableRespawn, planItems, envOverrides } =
-      parseBody(RalphLoopStartSchema, req.body);
+    const {
+      caseName,
+      taskDescription,
+      completionPhrase,
+      maxIterations,
+      enableRespawn,
+      planItems,
+      envOverrides,
+      effort,
+    } = parseBody(RalphLoopStartSchema, req.body);

    const casePath = join(CASES_DIR, caseName);

@@ -315,6 +323,7 @@ export function registerRalphRoutes(
      claudeMode: rlClaudeModeConfig.claudeMode,
      allowedTools: rlClaudeModeConfig.allowedTools,
      envOverrides,
+      effort,
    });

    // Configure Ralph tracker
@@ -5,11 +5,12 @@
 */

 import { FastifyInstance } from 'fastify';
-import { join, dirname } from 'node:path';
+import { join, dirname, extname } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import fs from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
 import {
  ApiErrorCode,
  createErrorResponse,
@@ -53,9 +54,10 @@ import { MAX_CONCURRENT_SESSIONS } from '../../config/map-limits.js';
 import { RunSummaryTracker } from '../../run-summary.js';

 import { MAX_INPUT_LENGTH, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js';
+import { dataPath } from '../../config/instance.js';

 // Path to linked-cases registry (same file used by case-routes resolveCasePath)
-const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
+const LINKED_CASES_FILE = dataPath('linked-cases.json');

 // Pre-compiled regex for terminal buffer cleaning (avoids per-request compilation)
 // eslint-disable-next-line no-control-regex
@@ -122,6 +124,76 @@ export function stripInkRedrawBloat(buffer: string): string {
  return parts.join('');
 }

+/**
+ * Validate image bytes against a declared extension. Sniffs the first ~12 bytes
+ * for a known magic-number signature. Defends against polyglots (e.g. HTML or
+ * SVG disguised under a `Content-Type: image/png` header) and against simple
+ * extension-only spoofing — both the multipart filename and the Content-Type
+ * are attacker-controlled, the raw bytes are not.
+ *
+ * Signatures: https://en.wikipedia.org/wiki/List_of_file_signatures
+ */
+export function imageMagicMatchesExt(data: Buffer, ext: string): boolean {
+  if (data.length < 12) return false;
+  const u32be = (off: number): number => data.readUInt32BE(off);
+  switch (ext) {
+    case '.png':
+      return u32be(0) === 0x89504e47 && u32be(4) === 0x0d0a1a0a;
+    case '.jpg':
+    case '.jpeg':
+      return data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
+    case '.gif':
+      return (
+        data[0] === 0x47 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x38 &&
+        (data[4] === 0x37 || data[4] === 0x39) &&
+        data[5] === 0x61
+      );
+    case '.webp':
+      // RIFF....WEBP
+      return u32be(0) === 0x52494646 && u32be(8) === 0x57454250;
+    case '.bmp':
+      return data[0] === 0x42 && data[1] === 0x4d;
+    default:
+      return false;
+  }
+}
+
+// Per-(IP, sessionId) token bucket for paste-image. 30 requests/minute.
+// Bucket map entries are pruned when they drift > 1h stale to bound memory
+// against a flood of unique IP keys.
+const PASTE_RATE_TOKENS = 30;
+const PASTE_RATE_REFILL_PER_MS = PASTE_RATE_TOKENS / 60_000;
+const PASTE_BUCKET_TTL_MS = 60 * 60 * 1000;
+const PASTE_BUCKET_GC_THRESHOLD = 1000;
+const pasteRateBuckets = new Map<string, { tokens: number; lastRefill: number }>();
+
+export function consumePasteToken(key: string, now: number = Date.now()): boolean {
+  if (pasteRateBuckets.size > PASTE_BUCKET_GC_THRESHOLD) {
+    for (const [k, b] of pasteRateBuckets) {
+      if (now - b.lastRefill > PASTE_BUCKET_TTL_MS) pasteRateBuckets.delete(k);
+    }
+  }
+  let b = pasteRateBuckets.get(key);
+  if (!b) {
+    b = { tokens: PASTE_RATE_TOKENS, lastRefill: now };
+    pasteRateBuckets.set(key, b);
+  }
+  const delta = (now - b.lastRefill) * PASTE_RATE_REFILL_PER_MS;
+  b.tokens = Math.min(PASTE_RATE_TOKENS, b.tokens + delta);
+  b.lastRefill = now;
+  if (b.tokens < 1) return false;
+  b.tokens -= 1;
+  return true;
+}
+
+// Test hook: reset between runs.
+export function _resetPasteRateBuckets(): void {
+  pasteRateBuckets.clear();
+}
+
 export function registerSessionRoutes(
  app: FastifyInstance,
  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
@@ -264,6 +336,7 @@ export function registerSessionRoutes(
      openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
      resumeSessionId: validatedResumeId,
      envOverrides: body.envOverrides,
+      effort: body.effort,
    });

    ctx.addSession(session);
@@ -581,11 +654,18 @@ export function registerSessionRoutes(
    }

    try {
+      // Route through the dedicated Codeman socket — bare `tmux` would target the
+      // user's default server and never find this session (same #80 regression class).
      await new Promise<void>((resolve, reject) => {
-        execFile('tmux', ['send-keys', '-H', '-t', muxName, ...hex], { timeout: 5000 }, (err) => {
-          if (err) reject(err);
-          else resolve();
-        });
+        execFile(
+          'tmux',
+          ['-L', ctx.mux.muxSocket, 'send-keys', '-H', '-t', muxName, ...hex],
+          { timeout: 5000 },
+          (err) => {
+            if (err) reject(err);
+            else resolve();
+          }
+        );
      });
    } catch (err) {
      console.error('[Server] send-key failed:', err);
@@ -1028,6 +1108,7 @@ export function registerSessionRoutes(
      mode = 'claude',
      openCodeConfig,
      envOverrides,
+      effort,
    } = parseBody(QuickStartSchema, req.body);

    // Check OpenCode availability if requested
@@ -1108,6 +1189,7 @@ export function registerSessionRoutes(
      allowedTools: qsClaudeModeConfig.allowedTools,
      openCodeConfig: mode === 'opencode' ? openCodeConfig : undefined,
      envOverrides,
+      effort,
    });

    // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
@@ -1253,42 +1335,76 @@ export function registerSessionRoutes(
   * Claude CLI encodes both '/' and '_' as '-', so each '-' in the key could be
   * any of: '/' (path separator), '_' (underscore), or '-' (literal dash).
   *
-   * Strategy: look-ahead matching. At each '-', try consuming multiple segments
-   * joined by '_' or '-' to find an existing child directory, then recurse.
-   * E.g. for segments [AI, project, Mirror] inside /Workspace:
-   *   try /Workspace/AI (no) -> /Workspace/AI_project (yes!) -> continue with [Mirror]
+   * Strategy: recursive backtracking with longest-match-first preference.
+   * At each segment boundary, try joining as many segments as possible (with '_'
+   * or '-') into a single existing directory name. If a shorter match leads to a
+   * dead end, backtrack and try the next-shorter candidate.
+   *
+   * Why backtracking: when both `diary/` and `diary-app/` exist as siblings, the
+   * naive shortest-match would pick `diary` and then fail to find `app` inside,
+   * leaving the rest of the key unresolved. Longest-first picks `diary-app`.
   */
  async function decodeProjectKey(projKey: string): Promise<string> {
    const encoded = projKey.startsWith('-') ? projKey.slice(1) : projKey;
    const segments = encoded.split('-');

-    const isDir = async (p: string): Promise<boolean> =>
-      fs
+    const isDirCache = new Map<string, boolean>();
+    const isDir = async (p: string): Promise<boolean> => {
+      const cached = isDirCache.get(p);
+      if (cached !== undefined) return cached;
+      const result = await fs
        .stat(p)
        .then((s) => s.isDirectory())
        .catch(() => false);
+      isDirCache.set(p, result);
+      return result;
+    };

+    // Recursive backtracking: returns the deepest valid path that consumes all
+    // segments. Tries the longest segment-join first at each step so that
+    // dash-containing directory names win over shorter same-prefix siblings.
+    async function tryDecode(idx: number, current: string): Promise<string | null> {
+      if (idx >= segments.length) return current;
+      const maxLook = Math.min(idx + 4, segments.length);
+      // Longest first: end = maxLook-1 down to idx
+      for (let end = maxLook - 1; end >= idx; end--) {
+        const candidates: string[] = [];
+        if (end === idx) {
+          candidates.push(segments[idx]);
+        } else {
+          candidates.push(segments.slice(idx, end + 1).join('-'));
+          candidates.push(segments.slice(idx, end + 1).join('_'));
+        }
+        for (const child of candidates) {
+          const candidate = current + '/' + child;
+          if (await isDir(candidate)) {
+            const result = await tryDecode(end + 1, candidate);
+            if (result) return result;
+          }
+        }
+      }
+      return null;
+    }
+
+    const decoded = await tryDecode(0, '');
+    if (decoded) return decoded;
+
+    // Fallback: greedy shortest-match (original behavior) — best effort when
+    // no fully-valid path exists (e.g. directory was deleted after the
+    // conversation was recorded).
    let current = '';
    let i = 0;
-
    while (i < segments.length) {
-      // Try progressively longer child names by joining segments with '_' or '-'
      let matched = false;
-      // Limit look-ahead to avoid excessive fs checks (max 4 segments per component)
      const maxLook = Math.min(i + 4, segments.length);
      for (let end = i; end < maxLook; end++) {
-        // Build candidate child name from segments[i..end]
-        // Try all separator combinations: for 2+ segments, try '_' first then '-'
        const candidates: string[] = [];
        if (end === i) {
          candidates.push(segments[i]);
        } else {
-          // Build with underscores between joined segments
          candidates.push(segments.slice(i, end + 1).join('_'));
-          // Build with dashes (literal)
          candidates.push(segments.slice(i, end + 1).join('-'));
        }
-
        for (const child of candidates) {
          const candidate = current + '/' + child;
          if (await isDir(candidate)) {
@@ -1301,12 +1417,10 @@ export function registerSessionRoutes(
        if (matched) break;
      }
      if (!matched) {
-        // No directory match found — append as-is and move on
        current = current + '/' + segments[i];
        i++;
      }
    }
-
    const finalExists = await fs
      .access(current)
      .then(() => true)
@@ -1345,96 +1459,272 @@ export function registerSessionRoutes(
    }
  }

-  app.get('/api/history/sessions', async () => {
+  type HistorySession = {
+    sessionId: string;
+    workingDir: string;
+    projectKey: string;
+    sizeBytes: number;
+    lastModified: string;
+    firstPrompt?: string;
+  };
+
+  // Scan a single project directory and return all valid history sessions in it.
+  // Reused by both the global overview and the single-folder drill-down.
+  async function scanProjectDir(projPath: string, projDir: string, headBuf: Buffer): Promise<HistorySession[]> {
+    const out: HistorySession[] = [];
+    const stat = await fs.stat(projPath).catch(() => null);
+    if (!stat?.isDirectory()) return out;
+
+    const workingDir = await decodeProjectKey(projDir);
+    const entries = await fs.readdir(projPath).catch(() => [] as string[]);
+
+    for (const entry of entries) {
+      if (!entry.endsWith('.jsonl')) continue;
+      const sessionId = entry.replace('.jsonl', '');
+      if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(sessionId)) continue;
+
+      const filePath = join(projPath, entry);
+      const fileStat = await fs.stat(filePath).catch(() => null);
+      if (!fileStat) continue;
+      if (fileStat.size < 4000) continue;
+
+      let firstPrompt: string | undefined;
+      const head = await readFileHead(filePath, headBuf);
+      const hasConversation = (text: string) =>
+        text.includes('"type":"user"') || text.includes('"type":"assistant"') || text.includes('"type":"summary"');
+
+      let foundContent = head ? hasConversation(head) : false;
+      let tail: string | null = null;
+      if (!foundContent && fileStat.size > 16384) {
+        const tailBuf = Buffer.alloc(32768);
+        tail = await readFileTail(filePath, tailBuf, fileStat.size);
+        if (tail) foundContent = hasConversation(tail);
+      }
+      if (!foundContent) continue;
+
+      if (head) firstPrompt = extractFirstUserPrompt(head);
+      if (!firstPrompt && fileStat.size > 65536) {
+        if (!tail) {
+          const tailBuf = Buffer.alloc(32768);
+          tail = await readFileTail(filePath, tailBuf, fileStat.size);
+        }
+        if (tail) firstPrompt = extractFirstUserPrompt(tail);
+      }
+
+      out.push({
+        sessionId,
+        workingDir,
+        projectKey: projDir,
+        sizeBytes: fileStat.size,
+        lastModified: fileStat.mtime.toISOString(),
+        firstPrompt,
+      });
+    }
+    return out;
+  }
+
+  app.get('/api/history/sessions', async (req) => {
+    const query = req.query as { projectKey?: string; offset?: string; limit?: string };
    const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects');
-    const results: Array<{
-      sessionId: string;
-      workingDir: string;
-      projectKey: string;
-      sizeBytes: number;
-      lastModified: string;
-      firstPrompt?: string;
-    }> = [];
    const headBuf = Buffer.alloc(16384);

+    // Single-folder drill-down: when projectKey is provided, scan only that
+    // directory, bypass the 50-cap, and honor offset/limit pagination.
+    if (query.projectKey) {
+      // Validate projectKey format to prevent path traversal
+      if (!/^[A-Za-z0-9_-]+$/.test(query.projectKey)) {
+        return { sessions: [], total: 0 };
+      }
+      const offset = Math.max(0, parseInt(query.offset || '0', 10) || 0);
+      const limit = Math.min(100, Math.max(1, parseInt(query.limit || '20', 10) || 20));
+      const projPath = join(projectsDir, query.projectKey);
+      const all = await scanProjectDir(projPath, query.projectKey, headBuf);
+      all.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
+      return { sessions: all.slice(offset, offset + limit), total: all.length };
+    }
+
+    // Global overview: scan all projects, return up to 50 most-recent sessions.
+    const results: HistorySession[] = [];
    try {
      const projectDirs = await fs.readdir(projectsDir);
      for (const projDir of projectDirs) {
        const projPath = join(projectsDir, projDir);
-        const stat = await fs.stat(projPath).catch(() => null);
-        if (!stat?.isDirectory()) continue;
-
-        // Decode project key to working dir. Claude CLI encodes '/' as '-',
-        // but path components may also contain '-' (e.g. "AI_project" vs "AI-project").
-        // Use recursive backtracking: try each '-' as either '/' or literal '-',
-        // verify which decoded path actually exists on disk.
-        const workingDir = await decodeProjectKey(projDir);
-
-        const entries = await fs.readdir(projPath);
-        for (const entry of entries) {
-          if (!entry.endsWith('.jsonl')) continue;
-          const sessionId = entry.replace('.jsonl', '');
-          // Only valid UUIDs
-          if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(sessionId)) continue;
-
-          const filePath = join(projPath, entry);
-          const fileStat = await fs.stat(filePath).catch(() => null);
-          if (!fileStat) continue;
-          // Skip files too small to contain real conversation (metadata-only sessions
-          // like file-history-snapshot entries are typically < 4KB)
-          if (fileStat.size < 4000) continue;
-
-          // Quick content check: verify actual conversation data exists.
-          // Sessions with only file-history-snapshot or hook_progress entries have
-          // no "user"/"assistant" messages and will fail claude --resume.
-          // Read first 16KB to check content and extract first user prompt.
-          let firstPrompt: string | undefined;
-          const head = await readFileHead(filePath, headBuf);
-          const hasConversation = (text: string) =>
-            text.includes('"type":"user"') || text.includes('"type":"assistant"') || text.includes('"type":"summary"');
-
-          let foundContent = head ? hasConversation(head) : false;
-
-          // For large files, head may not contain user messages (e.g. /init followed
-          // by large system entries). Check the tail as well.
-          let tail: string | null = null;
-          if (!foundContent && fileStat.size > 16384) {
-            const tailBuf = Buffer.alloc(32768);
-            tail = await readFileTail(filePath, tailBuf, fileStat.size);
-            if (tail) foundContent = hasConversation(tail);
-          }
-
-          if (!foundContent) continue; // No conversation content — skip
-
-          if (head) firstPrompt = extractFirstUserPrompt(head);
-
-          // If head scan found no usable prompt (e.g. session started with /init),
-          // try reading the tail for a recent user message.
-          if (!firstPrompt && fileStat.size > 65536) {
-            if (!tail) {
-              const tailBuf = Buffer.alloc(32768);
-              tail = await readFileTail(filePath, tailBuf, fileStat.size);
-            }
-            if (tail) firstPrompt = extractFirstUserPrompt(tail);
-          }
-
-          results.push({
-            sessionId,
-            workingDir,
-            projectKey: projDir,
-            sizeBytes: fileStat.size,
-            lastModified: fileStat.mtime.toISOString(),
-            firstPrompt,
-          });
-        }
+        const list = await scanProjectDir(projPath, projDir, headBuf);
+        results.push(...list);
      }
    } catch {
      // Projects dir may not exist
    }

-    // Sort by lastModified descending
    results.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
-
    return { sessions: results.slice(0, 50) };
  });
+
+  // ═══════════════════════════════════════════════════════════════
+  // Paste Image (clipboard / drag-drop upload)
+  // ═══════════════════════════════════════════════════════════════
+
+  const ALLOWED_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp']);
+  // The 10MB size cap is enforced by @fastify/multipart (registered in server.ts).
+
+  app.post('/api/sessions/:id/paste-image', async (req, reply) => {
+    // CSRF defense: state-changing routes must come from same origin.
+    // Cookies are SameSite=lax, multipart/form-data is a "simple" CORS request
+    // (no preflight), so a cross-origin <form enctype="multipart/form-data">
+    // submit attaches the session cookie unimpeded. Reject unless Origin/Referer
+    // matches req.host. Non-browser clients (no Origin AND no Referer) must
+    // supply X-Codeman-CSRF — a header browsers cannot add cross-origin without
+    // a preflight, which our CORS config does not allow from other origins.
+    const reqHost = req.headers.host;
+    const origin = req.headers.origin;
+    const referer = req.headers.referer;
+    let csrfOk = false;
+    if (origin) {
+      try {
+        csrfOk = new URL(origin).host === reqHost;
+      } catch {
+        /* invalid Origin → not ok */
+      }
+    } else if (referer) {
+      try {
+        csrfOk = new URL(referer).host === reqHost;
+      } catch {
+        /* invalid Referer → not ok */
+      }
+    } else {
+      csrfOk = !!req.headers['x-codeman-csrf'];
+    }
+    if (!csrfOk) {
+      reply.code(403);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'CSRF check failed');
+    }
+
+    const { id } = req.params as { id: string };
+
+    // Rate limit per (IP, sessionId): 30/min. Defends against disk-fill DoS
+    // — even an authenticated attacker can otherwise loop 10MB POSTs.
+    if (!consumePasteToken(`${req.ip}:${id}`)) {
+      reply.code(429);
+      reply.header('Retry-After', '60');
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Rate limit exceeded (30 uploads/min per session)');
+    }
+
+    const session = findSessionOrFail(ctx, id);
+
+    if (!req.isMultipart()) {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Expected multipart/form-data');
+    }
+
+    // Read the single file part. @fastify/multipart enforces the 10MB size cap
+    // and the 1-file/4-field count limits (server.ts), replacing a hand-rolled
+    // boundary scanner with several bugs: literal boundary matches anywhere in
+    // body, LF-only clients silently corrupted the last byte (hard-coded \r\n
+    // offsets), no part-count cap.
+    let part: import('@fastify/multipart').MultipartFile | undefined;
+    try {
+      part = await req.file();
+    } catch (err: unknown) {
+      reply.code(413);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err) || 'Invalid multipart payload');
+    }
+    if (!part) {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'No image uploaded');
+    }
+    if (part.fieldname !== 'image') {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Unexpected field "${part.fieldname}", expected "image"`);
+    }
+    let imageBytes: Buffer;
+    try {
+      imageBytes = await part.toBuffer();
+    } catch (err: unknown) {
+      reply.code(413);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err) || 'File too large (max 10MB)');
+    }
+    if (imageBytes.length === 0) {
+      reply.code(400);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Empty file');
+    }
+
+    // Determine extension from filename or Content-Type.
+    let ext = '.png';
+    if (part.filename) {
+      const origExt = extname(part.filename).toLowerCase();
+      if (ALLOWED_IMAGE_EXTS.has(origExt)) ext = origExt;
+    }
+    const mimeMatch = (part.mimetype || '').toLowerCase().match(/^image\/(png|jpeg|jpg|webp|gif|bmp)$/);
+    if (mimeMatch) {
+      const map: Record<string, string> = {
+        png: '.png',
+        jpeg: '.jpg',
+        jpg: '.jpg',
+        webp: '.webp',
+        gif: '.gif',
+        bmp: '.bmp',
+      };
+      ext = map[mimeMatch[1]] ?? ext;
+    }
+
+    if (!ALLOWED_IMAGE_EXTS.has(ext)) {
+      reply.code(400);
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        `Unsupported image type: ${ext}. Allowed: ${[...ALLOWED_IMAGE_EXTS].join(', ')}`
+      );
+    }
+
+    // Sniff actual bytes — filename and Content-Type are both attacker-supplied.
+    // Polyglot HTML/PNG would otherwise pass and serve back with image/png MIME.
+    if (!imageMagicMatchesExt(imageBytes, ext)) {
+      // Diagnostic: on some Android galleries (e.g. MIUI) a WebP/HEIF is
+      // mislabeled as image/jpeg, so the declared ext passes the allowlist but
+      // the magic bytes do not. Log the real header so format mismatches can be
+      // pinned down without a reproduce-and-guess loop. The client now
+      // re-encodes images to JPEG/PNG before upload, so this should be rare.
+      console.warn(
+        `[paste-image] magic mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${ext} magic=${imageBytes.subarray(0, 12).toString('hex')}`
+      );
+      reply.code(415);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
+    }
+
+    // Save to {workingDir}/.claude-images/
+    // Refuse symlinks at imageDir — an agent or postinstall script could plant
+    // `.claude-images -> ~/.ssh/` and redirect future writes outside workingDir.
+    // We lstat (not stat) so we see the symlink itself. Use mkdir without
+    // `recursive` so the leaf creation does not follow a symlink either, and
+    // O_EXCL|O_NOFOLLOW on the file open so the write itself is symlink-safe.
+    const imageDir = join(session.workingDir, '.claude-images');
+    try {
+      const dirStat = await fs.lstat(imageDir);
+      if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+        reply.code(403);
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, '.claude-images is not a regular directory');
+      }
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+      // Non-recursive mkdir: errors on EEXIST and does not follow symlinks for
+      // the leaf. session.workingDir is guaranteed to exist (live session).
+      await fs.mkdir(imageDir);
+    }
+    // Date.now() collides on same-ms uploads from two tabs (last-write wins
+    // silently). Append 8 hex chars so concurrent pastes get distinct names.
+    const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${ext}`;
+    const filepath = join(imageDir, filename);
+    // O_EXCL: refuse to overwrite (collision is impossible with random suffix,
+    // but defends against TOCTOU). O_NOFOLLOW: refuse if filepath is a symlink.
+    const fh = await fs.open(
+      filepath,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW
+    );
+    try {
+      await fh.writeFile(imageBytes);
+    } finally {
+      await fh.close();
+    }
+
+    return { success: true, path: filepath, filename };
+  });
 }
@@ -6,11 +6,13 @@

 import { FastifyInstance } from 'fastify';
 import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import fs from 'node:fs/promises';
-import { homedir, totalmem, freemem, loadavg, cpus } from 'node:os';
-import { execSync } from 'node:child_process';
+import { totalmem, freemem, loadavg, cpus } from 'node:os';
+import { execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { dataPath } from '../../config/instance.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
 import {
  ConfigUpdateSchema,
@@ -41,7 +43,7 @@ import { AUTH_SESSION_TTL_MS } from '../../config/auth-config.js';
 // Maximum screenshot upload size (10MB)
 const MAX_SCREENSHOT_SIZE = 10 * 1024 * 1024;
 // Screenshots directory
-const SCREENSHOTS_DIR = join(homedir(), '.codeman', 'screenshots');
+const SCREENSHOTS_DIR = dataPath('screenshots');

 /** Cached CPU count — doesn't change at runtime */
 const CPU_COUNT = cpus().length;
@@ -92,12 +94,24 @@ function getSystemStats(): {
  }
 }

+/**
+ * Build the URL the spanning browser window should open, pinned to localhost.
+ * Takes only a digits-only port from the (untrusted) Host header so nothing
+ * attacker-controllable reaches the launched browser; falls back to the default
+ * port when the header is absent/odd. Exported for unit testing.
+ */
+export function resolveSpanUrl(hostHeader: string | undefined, fallbackPort = '3000'): string {
+  const hostPort = String(hostHeader ?? '').split(':')[1] ?? '';
+  const port = /^\d+$/.test(hostPort) ? hostPort : fallbackPort;
+  return `http://localhost:${port}`;
+}
+
 export function registerSystemRoutes(
  app: FastifyInstance,
  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
 ): void {
-  const windowStatesPath = join(homedir(), '.codeman', 'subagent-window-states.json');
-  const parentMapPath = join(homedir(), '.codeman', 'subagent-parents.json');
+  const windowStatesPath = dataPath('subagent-window-states.json');
+  const parentMapPath = dataPath('subagent-parents.json');

  // ═══════════════════════════════════════════════════════════════
  // System Status & Health
@@ -239,6 +253,40 @@ export function registerSystemRoutes(
    return { success: true };
  });

+  // ═══════════════════════════════════════════════════════════════
+  // Multi-monitor: span Codeman across all displays
+  // ═══════════════════════════════════════════════════════════════
+
+  // Spawn scripts/span-codeman.sh, which opens a fresh, maximized browser --app
+  // window sized to the union of all displays — so in-page floating session
+  // panels can be dragged across the physical monitor seam. macOS only; needs
+  // the one-time "Displays have separate Spaces" OFF prerequisite (see script).
+  app.post('/api/system/span-displays', async (req, reply) => {
+    // macOS only: the launcher uses osascript + Finder desktop bounds and Chrome
+    // --app geometry flags. Fail clearly elsewhere instead of spawning a bash
+    // that errors out invisibly (the toast would otherwise lie "Opening…").
+    if (process.platform !== 'darwin') {
+      return reply
+        .code(400)
+        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Multi-monitor spanning is only supported on macOS.'));
+    }
+    // Resolve the bundled launcher relative to this module (works from src/ and dist/).
+    const scriptPath = join(dirname(fileURLToPath(import.meta.url)), '../../../scripts/span-codeman.sh');
+    if (!existsSync(scriptPath)) {
+      return reply.code(500).send(createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'span-codeman.sh not found'));
+    }
+    // Point the spanning window at THIS server (localhost + sanitized port).
+    const url = resolveSpanUrl(req.headers.host);
+    try {
+      const child = spawn('bash', [scriptPath, url], { detached: true, stdio: 'ignore' });
+      child.on('error', (err) => app.log.error({ err }, 'span-displays launch failed'));
+      child.unref();
+      return { success: true, url };
+    } catch (err) {
+      return reply.code(500).send(createErrorResponse(ApiErrorCode.INTERNAL_ERROR, getErrorMessage(err)));
+    }
+  });
+
  // ═══════════════════════════════════════════════════════════════
  // CLI Integrations (OpenCode)
  // ═══════════════════════════════════════════════════════════════
@@ -80,6 +80,15 @@ const safeEnvOverridesSchema = z
    }
  );

+// ========== Effort Level ==========
+
+/**
+ * Claude CLI effort level for new sessions. Injected as a `--settings` soft default
+ * (NOT the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session and
+ * block in-session `/effort` switching). `ultracode` enables dynamic workflow orchestration.
+ */
+const effortLevelSchema = z.enum(['low', 'medium', 'high', 'xhigh', 'max', 'ultracode']).optional();
+
 // ========== Session Routes ==========

 /**
@@ -124,6 +133,8 @@ export const CreateSessionSchema = z.object({
  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
  name: z.string().max(100).optional(),
  envOverrides: safeEnvOverridesSchema,
+  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
+  effort: effortLevelSchema,
  /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
  modelOverride: z.string().max(50).optional(),
  openCodeConfig: OpenCodeConfigSchema,
@@ -179,6 +190,8 @@ export const QuickStartSchema = z.object({
  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
  openCodeConfig: OpenCodeConfigSchema,
  envOverrides: safeEnvOverridesSchema,
+  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
+  effort: effortLevelSchema,
 });

 // ========== Hook Events ==========
@@ -280,6 +293,9 @@ export const SettingsUpdateSchema = z
    showProjectInsights: z.boolean().optional(),
    showFileBrowser: z.boolean().optional(),
    showSubagents: z.boolean().optional(),
+    showMultiMonitorButton: z.boolean().optional(),
+    // Input
+    gestureControlEnabled: z.boolean().optional(),
    // Claude CLI settings
    claudeMode: z.string().max(50).optional(),
    allowedTools: z.string().max(2000).optional(),
@@ -543,6 +559,8 @@ export const RalphLoopStartSchema = z.object({
  maxIterations: z.number().int().min(0).max(1000).nullable().default(10),
  enableRespawn: z.boolean().default(false),
  envOverrides: safeEnvOverridesSchema,
+  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
+  effort: effortLevelSchema,
  planItems: z
    .array(
      z.object({
@@ -32,12 +32,15 @@ import fastifyCompress from '@fastify/compress';
 import fastifyCookie from '@fastify/cookie';
 import fastifyStatic from '@fastify/static';
 import fastifyWebsocket from '@fastify/websocket';
+import fastifyMultipart from '@fastify/multipart';
+import { startPasteImageGc } from './paste-image-gc.js';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { existsSync, mkdirSync, readFileSync, chmodSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, chmodSync, rmSync, statSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
-import { homedir, hostname as getHostname } from 'node:os';
+import { hostname as getHostname } from 'node:os';
+import { dataPath } from '../config/instance.js';
 import { EventEmitter } from 'node:events';
 import { Session, type BackgroundTask } from '../session.js';
 import type { ClaudeMode, SessionState } from '../types.js';
@@ -87,18 +90,18 @@ const require = createRequire(import.meta.url);
 const { version: APP_VERSION } = require('../../package.json');
 import {
  getErrorMessage,
-  ApiErrorCode,
-  createErrorResponse,
  type PersistedRespawnConfig,
  type NiceConfig,
  type ImageDetectedEvent,
  DEFAULT_NICE_CONFIG,
 } from '../types.js';
-import { CleanupManager, KeyedDebouncer, StaleExpirationMap } from '../utils/index.js';
+import { CleanupManager, KeyedDebouncer, StaleExpirationMap, startEventLoopMonitor } from '../utils/index.js';
+import type { EventLoopMonitorHandle } from '../utils/index.js';
 import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.js';
 import { SseEvent } from './sse-events.js';
 import type { ScheduledRun } from './ports/index.js';
 import { registerAuthMiddleware, registerSecurityHeaders } from './middleware/auth.js';
+import { installRouteErrorHandler } from './route-error-handler.js';
 import {
  registerPushRoutes,
  registerTeamRoutes,
@@ -119,6 +122,11 @@ import {

 const __dirname = dirname(fileURLToPath(import.meta.url));

+// Bounded, predictable shape for SSE client identifiers: alphanumerics, `_`, `-`.
+// Length range covers crypto.randomUUID() (36 chars) plus any short stable IDs,
+// while capping growth of `sseClientsById` and blocking pathological inputs.
+const SSE_CLIENT_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+
 function escapeHtmlText(value: string): string {
  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 }
@@ -139,7 +147,7 @@ import {
 * Certs are stored in ~/.codeman/certs/ and reused across restarts.
 */
 function getOrCreateSelfSignedCert(): { key: string; cert: string } {
-  const certsDir = join(homedir(), '.codeman', 'certs');
+  const certsDir = dataPath('certs');
  const keyPath = join(certsDir, 'server.key');
  const certPath = join(certsDir, 'server.crt');

@@ -224,6 +232,8 @@ export class WebServer extends EventEmitter {
  private pushStore: PushSubscriptionStore = new PushSubscriptionStore();
  private teamWatcher: TeamWatcher = new TeamWatcher();
  private _orchestratorLoop: import('../orchestrator-loop.js').OrchestratorLoop | null = null;
+  private _pasteImageGcStop: (() => void) | null = null;
+  private _eventLoopMonitor: EventLoopMonitorHandle | null = null;
  private teamWatcherHandlers: {
    teamCreated: (config: unknown) => void;
    teamUpdated: (config: unknown) => void;
@@ -507,11 +517,10 @@ export class WebServer extends EventEmitter {
  }

  private async setupRoutes(): Promise<void> {
-    // Allow multipart/form-data for screenshot uploads — skip Fastify's body parser
-    // so the route handler can read the raw stream directly.
-    this.app.addContentTypeParser('multipart/form-data', (_req, _payload, done) => {
-      done(null);
-    });
+    // multipart/form-data: parser is provided by @fastify/multipart (registered
+    // below). Its parser is a no-op marker that leaves the body on req.raw, so
+    // legacy routes that read the raw stream directly (e.g. /api/screenshots)
+    // continue to work alongside routes that use req.file() (e.g. paste-image).

    // Enable gzip/brotli compression for all responses.
    // Massive win: 793KB uncompressed → ~120KB compressed for static assets.
@@ -534,13 +543,45 @@ export class WebServer extends EventEmitter {
    // WebSocket support (terminal I/O — low-latency bidirectional channel)
    await this.app.register(fastifyWebsocket);

+    // Multipart parsing (used by paste-image). Replaces a hand-rolled
+    // boundary scanner that had several edge-case bugs: literal boundary
+    // anywhere in body was a match, LF-only clients silently corrupted the
+    // last byte (hard-coded \r\n offsets), and there was no part-count cap.
+    await this.app.register(fastifyMultipart, {
+      limits: {
+        fileSize: 10 * 1024 * 1024, // 10MB per file
+        files: 1, // paste-image only ever sends one file
+        fields: 4, // small headroom for accompanying form fields
+      },
+    });
+
    // Security headers + CORS
    registerSecurityHeaders(this.app, this.https);
    this.app.get('/', async (_req, reply) => {
-      return reply.header('Cache-Control', 'no-cache').type('text/html; charset=utf-8').send(this.renderIndexHtml());
+      return reply
+        .header('Cache-Control', 'no-cache')
+        .type('text/html; charset=utf-8')
+        .send(await this.renderIndexHtml());
    });
    this.app.get('/index.html', async (_req, reply) => {
-      return reply.header('Cache-Control', 'no-cache').type('text/html; charset=utf-8').send(this.renderIndexHtml());
+      return reply
+        .header('Cache-Control', 'no-cache')
+        .type('text/html; charset=utf-8')
+        .send(await this.renderIndexHtml());
+    });
+    // Detached single-session window (undock). Serves the same SPA shell but
+    // flags the client into "solo mode" for one session. Auth applies normally
+    // (the popup carries the dashboard's cookie on navigation). We serve 200
+    // even for an unknown id — the client renders a friendly "session
+    // unavailable" state, which also covers a session that ends while its
+    // detached window is still open. Registered before the static plugin so the
+    // explicit route wins over the '/' static prefix.
+    this.app.get('/session/:id', async (req, reply) => {
+      const { id } = req.params as { id: string };
+      return reply
+        .header('Cache-Control', 'no-cache')
+        .type('text/html; charset=utf-8')
+        .send(await this.renderIndexHtml(id));
    });
    // Service worker must never be cached — browsers check for SW updates on navigation
    this.app.get('/sw.js', async (_req, reply) => {
@@ -579,9 +620,11 @@ export class WebServer extends EventEmitter {
      }

      // Parse optional session subscription filter from query parameter.
-      // /api/events?sessions=id1,id2 — client only receives events for those sessions.
-      // /api/events (no param) — client receives all events (backwards-compatible).
-      const query = req.query as { sessions?: string };
+      // /api/events?sessions=id1,id2 — client only receives session:terminal
+      //   events for those sessions (other events broadcast to all clients).
+      // /api/events?clientId=<uuid> — enables live filter updates via
+      //   POST /api/events/subscribe without reconnecting.
+      const query = req.query as { sessions?: string; clientId?: string };
      let sessionFilter: Set<string> | null = null;
      if (query.sessions) {
        const ids = query.sessions
@@ -592,6 +635,8 @@ export class WebServer extends EventEmitter {
          sessionFilter = new Set(ids);
        }
      }
+      const clientId =
+        typeof query.clientId === 'string' && SSE_CLIENT_ID_RE.test(query.clientId) ? query.clientId : undefined;

      reply.raw.writeHead(200, {
        'Content-Type': 'text/event-stream',
@@ -603,7 +648,7 @@ export class WebServer extends EventEmitter {
      // Track tunnel clients — cloudflared proxies locally so req.ip is always
      // 127.0.0.1; detect tunnel traffic via Cf-Connecting-Ip header instead.
      const isRemote = !!req.headers['cf-connecting-ip'];
-      this.sse.addClient(reply, sessionFilter, isRemote);
+      this.sse.addClient(reply, sessionFilter, isRemote, clientId);

      // Send initial state
      // Use light state for SSE init to avoid sending 2MB+ terminal buffers
@@ -618,17 +663,26 @@ export class WebServer extends EventEmitter {
      });
    });

-    // Global error handler for structured errors thrown by findSessionOrFail
-    this.app.setErrorHandler((error, _req, reply) => {
-      const statusCode = (error as { statusCode?: number }).statusCode ?? 500;
-      const body = (error as { body?: unknown }).body;
-      if (body) {
-        reply.code(statusCode).send(body);
-      } else {
-        reply.code(statusCode).send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(error)));
+    // Live subscription update — change a connected client's session filter
+    // without forcing an SSE reconnect. Body: { clientId, sessions: string[] | null }
+    // Empty/null sessions array = remove filter (receive all session:terminal events).
+    this.app.post('/api/events/subscribe', (req, reply) => {
+      const body = (req.body || {}) as { clientId?: string; sessions?: string[] | null };
+      if (typeof body.clientId !== 'string' || !SSE_CLIENT_ID_RE.test(body.clientId)) {
+        reply.code(400).send({ error: 'clientId required' });
+        return;
      }
+      const sessions = Array.isArray(body.sessions)
+        ? body.sessions.filter((s) => typeof s === 'string' && s.length > 0 && s.length <= 128).slice(0, 64)
+        : null;
+      const updated = this.sse.updateClientFilter(body.clientId, sessions);
+      reply.code(updated ? 204 : 404).send();
    });

+    // Global error handler for structured errors thrown by findSessionOrFail /
+    // parseBody. Shared with the route test harness so test behavior matches prod.
+    installRouteErrorHandler(this.app);
+
    // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them
    let _crashBreadcrumbs = '';
    this.app.addContentTypeParser('text/plain;charset=UTF-8', { parseAs: 'string' }, (_req, body, done) => {
@@ -926,6 +980,15 @@ export class WebServer extends EventEmitter {
      fileStreamManager.closeSessionStreams(sessionId);
      // Stop watching for images in this session's directory
      imageWatcher.unwatchSession(sessionId);
+      // Clean up pasted images directory for this session
+      if (killMux && session.workingDir) {
+        const pasteImageDir = join(session.workingDir, '.claude-images');
+        try {
+          rmSync(pasteImageDir, { recursive: true, force: true });
+        } catch {
+          // Best-effort cleanup
+        }
+      }
      await session.stop(killMux);
      this.sessions.delete(sessionId);
      // Only remove from state.json if we're also killing the mux session.
@@ -938,11 +1001,100 @@ export class WebServer extends EventEmitter {
    this.broadcast(SseEvent.SessionDeleted, { id: sessionId });
  }

-  private renderIndexHtml(): string {
-    return this.indexHtmlTemplate.replace(
+  private async renderIndexHtml(soloSessionId?: string): Promise<string> {
+    let html = this.indexHtmlTemplate.replace(
      '<title>Codeman</title>',
      `<title>${escapeHtmlText(this.windowTitle)}</title>`
    );
+    // Cache-bust same-origin module scripts + stylesheets so a normal reload
+    // always serves the latest (static assets carry a 1-year immutable cache).
+    html = this.cacheBustAssets(html);
+    // Per-user App-Settings flags, read server-side so the page renders in the
+    // right initial state on every normal reload (the client apply* functions
+    // only run on save). Read FRESH (bypass the 2s cache): a setting toggled
+    // moments ago triggers a reload here, and the cached value would render the
+    // pre-toggle state (e.g. the gesture bundle wouldn't inject until a 2nd
+    // reload). Skipped for solo popups (their header differs).
+    const settings: Record<string, unknown> = soloSessionId ? {} : await this.readSettings(true);
+    // Multi-monitor header button: carries the `btn-multimonitor--hidden` class
+    // in the template by default (App Settings → Display → "Header Displays");
+    // reveal by stripping that class when the user enabled it. Matching a unique
+    // class token (not user-facing copy) keeps this robust against template edits.
+    if (settings.showMultiMonitorButton === true) {
+      html = html.replace(' btn-multimonitor--hidden', '');
+    }
+    // Detached single-session ("solo") window: inject the target session id so
+    // the client can enter solo mode even if a (network-first) service worker
+    // later serves a cached shell. The client primarily detects solo mode from
+    // the /session/:id URL path; this global is a belt-and-suspenders fallback.
+    // The id is gated to JSON + <-escaped so it can't break out of the inline
+    // <script> (ids are UUIDs in practice, but defense-in-depth is cheap).
+    if (soloSessionId) {
+      const safeId = JSON.stringify(soloSessionId).replace(/</g, '\\u003c');
+      html = html.replace('</head>', `<script>window.__CODEMAN_SOLO__=${safeId};</script>\n</head>`);
+    }
+    // Gesture-control overlay (Phase 5): dashboard only (not solo popups, which
+    // have no tab strip). `CODEMAN_GESTURE=1` makes the feature *available* on
+    // this instance (it also widens CSP + serves the assets); the per-user
+    // `gestureControlEnabled` setting (App Settings → Input, default OFF) is the
+    // 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.
+    if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
+      html = html.replace('</head>', `<script>window.__codemanGestureAvailable=true;</script>\n</head>`);
+      if (settings.gestureControlEnabled === true) {
+        const v = this.gestureBundleVersion();
+        html = html.replace(
+          '</head>',
+          `<script type="module" src="/gesture/gesture-codeman.js${v}"></script>\n</head>`
+        );
+      }
+    }
+    return html;
+  }
+
+  /** mtime memo for asset cache-busting (keyed by absolute path). A full index
+   *  render does one stat per script/link tag (~25-30); without this each `/`,
+   *  `/index.html` and `/session/:id` hit would re-stat them all. A 1s TTL keeps
+   *  a burst of renders cheap while still picking up an edited/redeployed file
+   *  within a second (no server restart needed). */
+  private _assetVersionMemo = new Map<string, { v: number; ts: number }>();
+  private assetVersion(absPath: string): number | null {
+    const now = Date.now();
+    const hit = this._assetVersionMemo.get(absPath);
+    if (hit && now - hit.ts < 1000) return hit.v;
+    try {
+      const v = Math.floor(statSync(absPath).mtimeMs);
+      this._assetVersionMemo.set(absPath, { v, ts: now });
+      return v;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Cache-busting query for the gesture bundle: its mtime (memoized, see
+   *  assetVersion). The bundle is served from /gesture/ with a 1-year cache, so
+   *  without a version that changes on redeploy the browser would keep running a
+   *  stale bundle forever. Empty string if the file is missing. */
+  private gestureBundleVersion(): string {
+    const v = this.assetVersion(join(__dirname, 'public', 'gesture', 'gesture-codeman.js'));
+    return v === null ? '' : `?v=${v}`;
+  }
+
+  /** Append ?v=<mtime> to every same-origin .js/.css reference in the page so a
+   *  normal reload always serves the latest. Codeman's static assets are sent
+   *  with `Cache-Control: max-age=1y, immutable` and the script/link tags carry
+   *  no version, so without this an edited module (panels-ui.js, styles.css, …)
+   *  stays cached until a manual hard refresh. mtime is memoized (1s TTL) so a
+   *  changed file is picked up with no server restart. External URLs (have a
+   *  `:` scheme), already-versioned refs (have a `?`), and refs with no matching
+   *  file on disk are left untouched. */
+  private cacheBustAssets(html: string): string {
+    const publicDir = join(__dirname, 'public');
+    return html.replace(/(\s(?:src|href)=")([^"?:]+\.(?:js|css))(")/g, (full, pre, ref, post) => {
+      const v = this.assetVersion(join(publicDir, ref));
+      return v === null ? full : `${pre}${ref}?v=${v}${post}`;
+    });
  }

  private async setupSessionListeners(session: Session): Promise<void> {
@@ -1046,7 +1198,7 @@ export class WebServer extends EventEmitter {

  // Helper to get custom CLAUDE.md template path from settings
  private async getDefaultClaudeMdPath(): Promise<string | undefined> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');

    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
@@ -1064,13 +1216,16 @@ export class WebServer extends EventEmitter {

  // Read ~/.codeman/settings.json once and return the parsed object.
  // Cached for 2s to avoid redundant reads during session creation bursts.
+  // The settings PUT route writes the file without invalidating this cache, so
+  // callers that must observe a just-saved value (e.g. renderIndexHtml on a
+  // post-save reload) pass forceFresh=true to bypass the cache.
  private _settingsCache: { data: Record<string, unknown>; ts: number } | null = null;
-  private async readSettings(): Promise<Record<string, unknown>> {
+  private async readSettings(forceFresh = false): Promise<Record<string, unknown>> {
    const now = Date.now();
-    if (this._settingsCache && now - this._settingsCache.ts < 2000) {
+    if (!forceFresh && this._settingsCache && now - this._settingsCache.ts < 2000) {
      return this._settingsCache.data;
    }
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const data = JSON.parse(content) as Record<string, unknown>;
@@ -1507,6 +1662,16 @@ export class WebServer extends EventEmitter {
    // Clean up stale sessions from state file that don't have active mux sessions
    this.cleanupStaleSessions();

+    // Bound disk use under heavy paste-image traffic: delete `paste-*` files
+    // older than 7 days from each live session's .claude-images/ hourly.
+    if (!this.testMode) {
+      this._pasteImageGcStop = startPasteImageGc({ sessions: this.sessions });
+      // Surface event-loop stalls (e.g. a slow synchronous tmux/ps call) so the
+      // intermittent ":3000 briefly unreachable, process never restarts" class of
+      // incident leaves a quantified log line instead of vanishing silently.
+      this._eventLoopMonitor = startEventLoopMonitor();
+    }
+
    await this.app.listen({ port: this.port, host: '0.0.0.0' });
    const protocol = this.https ? 'https' : 'http';
    console.log(`Codeman web interface running at ${protocol}://localhost:${this.port}`);
@@ -1567,7 +1732,7 @@ export class WebServer extends EventEmitter {
    // Tunnel only starts when user clicks the toggle in the UI — never on boot.
    // Reset persisted tunnelEnabled so the UI toggle reflects actual state.
    if (await this.isTunnelEnabled()) {
-      const settingsPath = join(homedir(), '.codeman', 'settings.json');
+      const settingsPath = dataPath('settings.json');
      try {
        const content = await fs.readFile(settingsPath, 'utf-8');
        const settings = JSON.parse(content);
@@ -1588,7 +1753,7 @@ export class WebServer extends EventEmitter {
   * Check if subagent tracking is enabled in settings (default: true)
   */
  private async isSubagentTrackingEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -1606,7 +1771,7 @@ export class WebServer extends EventEmitter {
   * Check if image watcher is enabled in settings (default: false)
   */
  private async isImageWatcherEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -1624,7 +1789,7 @@ export class WebServer extends EventEmitter {
   * Check if Cloudflare tunnel is enabled in settings (default: false)
   */
  private async isTunnelEnabled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.codeman', 'settings.json');
+    const settingsPath = dataPath('settings.json');
    try {
      const content = await fs.readFile(settingsPath, 'utf-8');
      const settings = JSON.parse(content);
@@ -1664,6 +1829,8 @@ export class WebServer extends EventEmitter {
            const recoveryClaudeMode = await this.getClaudeModeConfig();
            // Recover envOverrides from the internal __envOverrides field written by
            // session-manager (see updateSessionState). Cast to read the non-public field.
+            // Note: a legacy CLAUDE_CODE_EFFORT_LEVEL entry is auto-migrated to `effort`
+            // by the Session constructor (env var would hard-lock /effort switching).
            const savedEnvOverrides = (savedState as { __envOverrides?: Record<string, string> })?.__envOverrides;
            const session = new Session({
              id: muxSession.sessionId, // Preserve the original session ID
@@ -1676,6 +1843,7 @@ export class WebServer extends EventEmitter {
              claudeMode: recoveryClaudeMode.claudeMode,
              allowedTools: recoveryClaudeMode.allowedTools,
              envOverrides: savedEnvOverrides,
+              effort: savedState?.effort,
            });

            // Update session name if it was a "Restored:" placeholder or doesn't match saved name
@@ -1860,6 +2028,16 @@ export class WebServer extends EventEmitter {
    // Set stopping flag to prevent new timer creation during shutdown
    this.sse.setStopping();

+    if (this._pasteImageGcStop) {
+      this._pasteImageGcStop();
+      this._pasteImageGcStop = null;
+    }
+
+    if (this._eventLoopMonitor) {
+      this._eventLoopMonitor.stop();
+      this._eventLoopMonitor = null;
+    }
+
    // Dispose all managed timers (intervals + resettable timeouts)
    this.cleanup.dispose();

@@ -48,6 +48,8 @@ export class SseStreamManager {
   * or `null` meaning "receive all events" (backwards-compatible default).
   */
  private sseClients: Map<FastifyReply, Set<string> | null> = new Map();
+  /** Optional client-supplied IDs → reply, for live filter updates without reconnecting */
+  private sseClientsById: Map<string, FastifyReply> = new Map();
  /** SSE clients connecting from non-localhost (i.e. through tunnel) */
  private remoteSseClients: Set<FastifyReply> = new Set();
  /** Clients with backpressure — skip writes until 'drain' fires */
@@ -103,17 +105,43 @@ export class SseStreamManager {
    this._isTunnelActive = active;
  }

-  addClient(reply: FastifyReply, sessionFilter: Set<string> | null, isRemote: boolean): void {
+  addClient(reply: FastifyReply, sessionFilter: Set<string> | null, isRemote: boolean, clientId?: string): void {
    this.sseClients.set(reply, sessionFilter);
    if (isRemote) {
      this.remoteSseClients.add(reply);
    }
+    if (clientId) {
+      // If a previous reply registered the same id (reconnect), drop the old one.
+      const prev = this.sseClientsById.get(clientId);
+      if (prev && prev !== reply) {
+        this.sseClients.delete(prev);
+        this.remoteSseClients.delete(prev);
+        this.backpressuredClients.delete(prev);
+      }
+      this.sseClientsById.set(clientId, reply);
+    }
  }

  removeClient(reply: FastifyReply): void {
    this.sseClients.delete(reply);
    this.remoteSseClients.delete(reply);
    this.backpressuredClients.delete(reply);
+    // Clear any clientId mappings pointing at this reply
+    for (const [id, r] of this.sseClientsById) {
+      if (r === reply) this.sseClientsById.delete(id);
+    }
+  }
+
+  /**
+   * Update an existing client's session subscription filter without forcing
+   * an SSE reconnect. Returns true if the client was found and updated.
+   */
+  updateClientFilter(clientId: string, sessions: string[] | null): boolean {
+    const reply = this.sseClientsById.get(clientId);
+    if (!reply || !this.sseClients.has(reply)) return false;
+    const filter = sessions && sessions.length > 0 ? new Set(sessions) : null;
+    this.sseClients.set(reply, filter);
+    return true;
  }

  /** Send a single SSE event to a specific client. */
@@ -188,35 +216,18 @@ export class SseStreamManager {
      console.error(`[Server] Failed to serialize SSE event "${event}":`, err);
      return;
    }
-    // Extract sessionId from event data for subscription filtering.
-    const eventSessionId = this.extractSessionId(event, data);
-
-    for (const [client, filter] of this.sseClients) {
-      // No filter (null) = receive everything. Otherwise, skip if event is
-      // session-scoped and the session isn't in the client's subscription set.
-      if (filter && eventSessionId && !filter.has(eventSessionId)) continue;
+    // Subscription filtering is intentionally NOT applied here. The
+    // `?sessions=` filter is intended to suppress only the high-volume
+    // terminal stream — lifecycle/metadata events (session:created,
+    // session:updated, ralph:*, hook:*, etc.) are needed for correct UI
+    // state across all sessions even when the client subscribes to a single
+    // active session's terminal output. Terminal events bypass this method
+    // entirely (see flushSessionTerminalBatch — it applies the filter).
+    for (const [client] of this.sseClients) {
      this.sendSSEPreformatted(client, message);
    }
  }

-  /**
-   * Extract the session ID from an event's data payload for subscription filtering.
-   * Returns the sessionId string if the event is session-scoped, or null for global events.
-   */
-  private extractSessionId(event: string, data: unknown): string | null {
-    if (data == null || typeof data !== 'object') return null;
-    const record = data as Record<string, unknown>;
-
-    // Most session-scoped events use `sessionId`
-    if (typeof record.sessionId === 'string') return record.sessionId;
-
-    // Session lifecycle events (session:*) use `id` from the session state object
-    if (typeof record.id === 'string' && event.startsWith('session:')) return record.id;
-
-    // No session ID found — treat as global event (sent to all clients)
-    return null;
-  }
-
  // ========== Terminal Data Batching ==========

  // Batch terminal data for better performance (60fps)
@@ -0,0 +1,79 @@
+/**
+ * Per-instance isolation (src/config/instance.ts): the data dir + tmux socket
+ * derive from CODEMAN_INSTANCE, defaulting to the production layout so the
+ * feature branch is safe to merge to master.
+ *
+ * instance.ts reads env at module load, so each case re-imports it via
+ * vi.resetModules() under a controlled env. node:fs mkdirSync is mocked so
+ * getDataDir() never creates real directories on the test machine.
+ *
+ * Port: N/A (no server).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+vi.mock('node:fs', async (orig) => {
+  const actual = await orig<typeof import('node:fs')>();
+  return { ...actual, mkdirSync: vi.fn() };
+});
+
+const ENV_KEYS = ['CODEMAN_INSTANCE', 'CODEMAN_DATA_DIR'] as const;
+const ORIG: Record<string, string | undefined> = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+
+async function load(env: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>> = {}) {
+  vi.resetModules();
+  for (const k of ENV_KEYS) {
+    const v = env[k];
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  return import('../../src/config/instance.js');
+}
+
+afterEach(() => {
+  for (const k of ENV_KEYS) {
+    if (ORIG[k] === undefined) delete process.env[k];
+    else process.env[k] = ORIG[k];
+  }
+  vi.resetModules();
+});
+
+describe('config/instance', () => {
+  it('defaults to the production layout when CODEMAN_INSTANCE is unset', async () => {
+    const m = await load({ CODEMAN_INSTANCE: undefined, CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman'));
+    expect(m.dataPath('state.json')).toBe(join(homedir(), '.codeman', 'state.json'));
+  });
+
+  it('treats an explicitly-empty CODEMAN_INSTANCE as the production layout', async () => {
+    const m = await load({ CODEMAN_INSTANCE: '', CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman'));
+  });
+
+  it('scopes BOTH the data dir and the tmux socket for a named instance', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'beta', CODEMAN_DATA_DIR: undefined });
+    expect(m.CODEMAN_INSTANCE).toBe('beta');
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-beta');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman-beta'));
+    expect(m.dataPath('mux-sessions.json')).toBe(join(homedir(), '.codeman-beta', 'mux-sessions.json'));
+  });
+
+  it('supports an arbitrary instance name', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'foo', CODEMAN_DATA_DIR: undefined });
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-foo');
+    expect(m.getDataDir()).toBe(join(homedir(), '.codeman-foo'));
+  });
+
+  it('CODEMAN_DATA_DIR overrides the derived data dir (socket still instance-scoped)', async () => {
+    const m = await load({ CODEMAN_INSTANCE: 'beta', CODEMAN_DATA_DIR: '/tmp/codeman-test-xyz' });
+    expect(m.getDataDir()).toBe('/tmp/codeman-test-xyz');
+    expect(m.dataPath('a', 'b')).toBe(join('/tmp/codeman-test-xyz', 'a', 'b'));
+    // Socket is derived from the instance name, not the data dir override.
+    expect(m.DEFAULT_TMUX_SOCKET).toBe('codeman-beta');
+  });
+});
@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Tests for Claude CLI effort level injection.
+ *
+ * Effort must flow as a `--settings` SOFT default (overridable in-session via
+ * /effort, incl. ultracode) — never as the CLAUDE_CODE_EFFORT_LEVEL env var,
+ * which hard-locks the session. Also covers the legacy migration path: old
+ * persisted sessions carried effort inside __envOverrides.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildEffortCliArgs, buildInteractiveArgs } from '../src/session-cli-builder.js';
+import { isEffortLevel, EFFORT_LEVELS } from '../src/types.js';
+import { Session } from '../src/session.js';
+
+describe('buildEffortCliArgs', () => {
+  it('maps regular levels (incl. max) to the --effort flag', () => {
+    // NOT the settings effortLevel key: its enum lacks "max" and silently drops it
+    expect(buildEffortCliArgs('low')).toEqual(['--effort', 'low']);
+    expect(buildEffortCliArgs('high')).toEqual(['--effort', 'high']);
+    expect(buildEffortCliArgs('xhigh')).toEqual(['--effort', 'xhigh']);
+    expect(buildEffortCliArgs('max')).toEqual(['--effort', 'max']);
+  });
+
+  it('maps ultracode to its dedicated --settings boolean key', () => {
+    // The --effort flag rejects ultracode; only the settings key enables it at spawn
+    expect(buildEffortCliArgs('ultracode')).toEqual(['--settings', '{"ultracode":true}']);
+  });
+
+  it('returns empty args for missing or invalid values', () => {
+    expect(buildEffortCliArgs(undefined)).toEqual([]);
+    // Invalid strings must not reach the shell command (injection guard)
+    expect(buildEffortCliArgs('"; rm -rf /' as never)).toEqual([]);
+    expect(buildEffortCliArgs('turbo' as never)).toEqual([]);
+  });
+
+  it('produces a flag/value pair for every allowed level', () => {
+    for (const level of EFFORT_LEVELS) {
+      const args = buildEffortCliArgs(level);
+      expect(args).toHaveLength(2);
+      expect(args[0]).toMatch(/^--(effort|settings)$/);
+    }
+  });
+});
+
+describe('isEffortLevel', () => {
+  it('accepts all defined levels and rejects everything else', () => {
+    for (const level of EFFORT_LEVELS) {
+      expect(isEffortLevel(level)).toBe(true);
+    }
+    expect(isEffortLevel(undefined)).toBe(false);
+    expect(isEffortLevel('')).toBe(false);
+    expect(isEffortLevel('ULTRACODE')).toBe(false);
+  });
+});
+
+describe('buildInteractiveArgs with effort', () => {
+  it('appends --settings for ultracode', () => {
+    const args = buildInteractiveArgs('sid-123', 'dangerously-skip-permissions', undefined, undefined, 'ultracode');
+    const idx = args.indexOf('--settings');
+    expect(idx).toBeGreaterThan(-1);
+    expect(args[idx + 1]).toBe('{"ultracode":true}');
+  });
+
+  it('appends --effort for max', () => {
+    const args = buildInteractiveArgs('sid-123', 'dangerously-skip-permissions', undefined, undefined, 'max');
+    const idx = args.indexOf('--effort');
+    expect(idx).toBeGreaterThan(-1);
+    expect(args[idx + 1]).toBe('max');
+  });
+
+  it('omits effort args when effort is absent', () => {
+    const args = buildInteractiveArgs('sid-123', 'dangerously-skip-permissions');
+    expect(args).not.toContain('--settings');
+    expect(args).not.toContain('--effort');
+  });
+});
+
+describe('Session effort handling', () => {
+  it('stores explicit effort and exposes it in toState()', () => {
+    const session = new Session({ workingDir: '/tmp', effort: 'ultracode' });
+    expect(session.toState().effort).toBe('ultracode');
+  });
+
+  it('migrates legacy CLAUDE_CODE_EFFORT_LEVEL out of envOverrides', () => {
+    const session = new Session({
+      workingDir: '/tmp',
+      envOverrides: {
+        CLAUDE_CODE_EFFORT_LEVEL: 'high',
+        CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+      },
+    });
+    // Legacy env var becomes the soft-default effort...
+    expect(session.toState().effort).toBe('high');
+    // ...and is never persisted (or exported) as an env var again
+    expect(session.getEnvOverridesForPersist()).toEqual({
+      CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+    });
+  });
+
+  it('drops an invalid legacy effort value instead of forwarding it', () => {
+    const session = new Session({
+      workingDir: '/tmp',
+      envOverrides: { CLAUDE_CODE_EFFORT_LEVEL: 'bogus-value' },
+    });
+    expect(session.toState().effort).toBeUndefined();
+    expect(session.getEnvOverridesForPersist()).toBeUndefined();
+  });
+
+  it('prefers explicit effort over the legacy env var', () => {
+    const session = new Session({
+      workingDir: '/tmp',
+      effort: 'ultracode',
+      envOverrides: { CLAUDE_CODE_EFFORT_LEVEL: 'low' },
+    });
+    expect(session.toState().effort).toBe('ultracode');
+  });
+
+  it('leaves effort undefined when nothing is configured', () => {
+    const session = new Session({ workingDir: '/tmp' });
+    expect(session.toState().effort).toBeUndefined();
+  });
+});
@@ -90,6 +90,7 @@ export function createMockRouteContext(options?: { sessionId?: string }) {

    // -- InfraPort --
    mux: {
+      muxSocket: 'codeman',
      createSession: vi.fn(),
      killSession: vi.fn(),
      listSessions: vi.fn(() => []),
@@ -3,7 +3,8 @@
 *
 * Covers:
 * - SSE subscription filter edge cases (empty params, whitespace, duplicates)
- * - extractSessionId logic (sessionId vs id field, global events)
+ * - Lifecycle-event broadcast contract (session:*, case:* fan out to all clients;
+ *   only session:terminal is filtered by subscription)
 * - Tab switching: terminal buffer loading, session creation + switch
 * - Terminal data cap / backpressure recovery
 * - Lazy teammate terminal lifecycle
@@ -254,11 +255,11 @@ describe('Operation Lightspeed', () => {
  });

  // ═══════════════════════════════════════════════════════════════
-  // extractSessionId — Event Classification
+  // Lifecycle Event Broadcast — Event Classification
  // ═══════════════════════════════════════════════════════════════

-  describe('extractSessionId via SSE Filtering', () => {
-    it('should route session:updated events by id field', async () => {
+  describe('Lifecycle Event Broadcast Contract', () => {
+    it('should deliver session:updated events to all clients regardless of filter', async () => {
      // Create two sessions
      const session1 = await createSession(baseUrl);
      const session2 = await createSession(baseUrl);
@@ -310,21 +311,23 @@ describe('Operation Lightspeed', () => {

      const events = parseSSEEvents(receivedData);

-      // Should receive session:updated for session1 only
+      // New contract: session:updated is a lifecycle event that broadcasts to ALL clients.
+      // The subscription filter only applies to session:terminal.
      const updatedEvents = events.filter((e) => e.event === 'session:updated');
      const session1Updated = updatedEvents.find((e) => (e.data as any).id === session1);
      const session2Updated = updatedEvents.find((e) => (e.data as any).id === session2);

      expect(session1Updated).toBeDefined();
-      expect(session2Updated).toBeUndefined();
+      expect(session2Updated).toBeDefined();

      // Cleanup
      await deleteSession(baseUrl, session1);
      await deleteSession(baseUrl, session2);
    });

-    it('should filter session:deleted by session ID (sessionId extraction from id field)', async () => {
-      // Tests extractSessionId's fallback path: session:* events use `id` not `sessionId`
+    it('should deliver session:deleted events to all clients regardless of filter', async () => {
+      // New contract: lifecycle events (session:*) broadcast to every connected client;
+      // the per-client filter no longer gates them. Only session:terminal is filtered.
      const target = await createSession(baseUrl);
      const other = await createSession(baseUrl);

@@ -367,13 +370,12 @@ describe('Operation Lightspeed', () => {

      const events = parseSSEEvents(receivedData);

-      // Target deletion should arrive (extractSessionId matches `id` field for session:* events)
+      // Both deletions arrive regardless of the per-client filter
      const targetDeleted = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === target);
      expect(targetDeleted).toBeDefined();

-      // Other deletion should NOT arrive
      const otherDeleted = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === other);
-      expect(otherDeleted).toBeUndefined();
+      expect(otherDeleted).toBeDefined();
    });
  });

@@ -488,13 +490,13 @@ describe('Operation Lightspeed', () => {
      expect(events.find((e) => e.event === 'init')).toBeDefined();
    });

-    it('should handle multiple SSE clients with different filters', async () => {
+    it('should fan lifecycle events out to all SSE clients regardless of filter', async () => {
      const session1 = await createSession(baseUrl);
      const session2 = await createSession(baseUrl);

-      // Client A: subscribes to session1
-      // Client B: subscribes to session2
-      // Client C: no filter (all events)
+      // Client A: subscribes to session1, Client B: subscribes to session2, Client C: no filter.
+      // Under the broadcast contract, all three see every session:deleted event — the filter
+      // only narrows session:terminal traffic.
      const controllerA = new AbortController();
      const controllerB = new AbortController();
      const controllerC = new AbortController();
@@ -585,15 +587,13 @@ describe('Operation Lightspeed', () => {
      const eventsB = parseSSEEvents(dataB);
      const eventsC = parseSSEEvents(dataC);

-      // Client A: sees session1 deleted, not session2
+      // Every client sees both deletions — lifecycle events are not filter-gated.
      expect(eventsA.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1)).toBeDefined();
-      expect(eventsA.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2)).toBeUndefined();
+      expect(eventsA.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2)).toBeDefined();

-      // Client B: sees session2 deleted, not session1
+      expect(eventsB.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1)).toBeDefined();
      expect(eventsB.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2)).toBeDefined();
-      expect(eventsB.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1)).toBeUndefined();

-      // Client C: sees both
      expect(eventsC.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1)).toBeDefined();
      expect(eventsC.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2)).toBeDefined();
    });
@@ -991,13 +991,13 @@ describe('Operation Lightspeed', () => {
  });

  // ═══════════════════════════════════════════════════════════════
-  // extractSessionId — Additional Edge Cases
+  // Lifecycle Event Broadcast — Additional Edge Cases
  // ═══════════════════════════════════════════════════════════════

-  describe('extractSessionId — Edge Cases via SSE', () => {
+  describe('Lifecycle Event Broadcast — Edge Cases via SSE', () => {
    it('should treat non-session: events with id field as global (not filtered)', async () => {
      // Events like case:created have an `id` field but aren't session:* events.
-      // extractSessionId should NOT use the `id` field for non-session:* events.
+      // Under the broadcast contract they reach every connected client.
      const controller = new AbortController();
      let receivedData = '';

@@ -1052,8 +1052,9 @@ describe('Operation Lightspeed', () => {
      }
    });

-    it('should deliver session:created for a newly created session to unfiltered client but not mismatched filter', async () => {
-      // session:created uses `id` field and starts with `session:` — extractSessionId should match it
+    it('should deliver session:created to every client, even those with a mismatched filter', async () => {
+      // Under the broadcast contract, lifecycle events ignore the per-client filter.
+      // A client subscribed only to `existing` still receives `session:created` for `newSession`.
      const existing = await createSession(baseUrl);

      // Subscribe to existing session only
@@ -1091,9 +1092,9 @@ describe('Operation Lightspeed', () => {
      }

      const events = parseSSEEvents(receivedData);
-      // session:created for newSession should be filtered OUT (id doesn't match our filter)
+      // session:created reaches the filtered client even though its id doesn't match the filter.
      const createdEvent = events.find((e) => e.event === 'session:created' && (e.data as any).id === newSession);
-      expect(createdEvent).toBeUndefined();
+      expect(createdEvent).toBeDefined();

      await Promise.all([deleteSession(baseUrl, existing), deleteSession(baseUrl, newSession)]);
    });
@@ -0,0 +1,96 @@
+/**
+ * WebServer.renderIndexHtml — server-side gating of the index shell:
+ *  - multi-monitor button reveal (stable class-marker, not brittle copy match)
+ *  - solo (/session/:id) global injection + escaping, and settings skipped
+ *  - gesture overlay availability vs. enablement (CODEMAN_GESTURE + setting)
+ *  - settings read FRESH so a post-save reload doesn't render stale state
+ *
+ * WebServer's constructor only assigns fields (no port bind), so we construct it
+ * directly, swap in a tiny indexHtmlTemplate, and stub readSettings to avoid disk.
+ *
+ * Port: N/A (no server start).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { WebServer } from '../src/web/server.js';
+
+const TEMPLATE = [
+  '<head>',
+  '<title>Codeman</title>',
+  '</head>',
+  '<body>',
+  '<button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" aria-label="Open Codeman across all displays"></button>',
+  '</body>',
+].join('\n');
+
+function makeServer(settings: Record<string, unknown> = {}) {
+  const server = new WebServer(0, false, true);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (server as any).indexHtmlTemplate = TEMPLATE;
+  const readSettings = vi.fn(async () => settings);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (server as any).readSettings = readSettings;
+  return { server, readSettings };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const render = (server: WebServer, solo?: string): Promise<string> => (server as any).renderIndexHtml(solo);
+
+const ORIG_GESTURE = process.env.CODEMAN_GESTURE;
+afterEach(() => {
+  if (ORIG_GESTURE === undefined) delete process.env.CODEMAN_GESTURE;
+  else process.env.CODEMAN_GESTURE = ORIG_GESTURE;
+});
+
+describe('WebServer.renderIndexHtml', () => {
+  it('keeps the multi-monitor button hidden by default and reads settings FRESH', async () => {
+    const { server, readSettings } = makeServer({});
+    const html = await render(server);
+    expect(html).toContain('btn-multimonitor--hidden');
+    // forceFresh=true — fixes the post-save reload race against the 2s cache.
+    expect(readSettings).toHaveBeenCalledWith(true);
+  });
+
+  it('reveals the multi-monitor button when showMultiMonitorButton is set', async () => {
+    const { server } = makeServer({ showMultiMonitorButton: true });
+    const html = await render(server);
+    expect(html).not.toContain('btn-multimonitor--hidden');
+    expect(html).toContain('btn-multimonitor"'); // class list still present, only the marker stripped
+  });
+
+  it('injects the solo global and skips settings for a /session/:id window', async () => {
+    const { server, readSettings } = makeServer({ showMultiMonitorButton: true });
+    const html = await render(server, 'sess-123');
+    expect(html).toContain('window.__CODEMAN_SOLO__="sess-123"');
+    expect(readSettings).not.toHaveBeenCalled();
+    // Solo skips settings, so the button is NOT revealed even though the setting is on.
+    expect(html).toContain('btn-multimonitor--hidden');
+  });
+
+  it('escapes the solo id so it cannot break out of the inline <script>', async () => {
+    const { server } = makeServer({});
+    const html = await render(server, 'a</script><b>');
+    expect(html).not.toContain('</script><b>');
+    expect(html).toContain('\\u003c');
+  });
+
+  it('exposes gesture availability but injects the bundle only when enabled', async () => {
+    process.env.CODEMAN_GESTURE = '1';
+    let { server } = makeServer({ gestureControlEnabled: false });
+    let html = await render(server);
+    expect(html).toContain('window.__codemanGestureAvailable=true');
+    expect(html).not.toContain('gesture-codeman.js');
+
+    ({ server } = makeServer({ gestureControlEnabled: true }));
+    html = await render(server);
+    expect(html).toContain('window.__codemanGestureAvailable=true');
+    expect(html).toContain('gesture-codeman.js');
+  });
+
+  it('does not expose gesture at all when CODEMAN_GESTURE is unset', async () => {
+    delete process.env.CODEMAN_GESTURE;
+    const { server } = makeServer({ gestureControlEnabled: true });
+    const html = await render(server);
+    expect(html).not.toContain('__codemanGestureAvailable');
+    expect(html).not.toContain('gesture-codeman.js');
+  });
+});
@@ -7,6 +7,7 @@
 import Fastify, { type FastifyInstance } from 'fastify';
 import fastifyCookie from '@fastify/cookie';
 import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';

 export interface RouteTestHarness {
  app: FastifyInstance;
@@ -24,7 +25,7 @@ export interface RouteTestHarness {
 export async function createRouteTestHarness(
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  registerFn: (app: FastifyInstance, ctx: any) => void,
-  ctxOptions?: { sessionId?: string },
+  ctxOptions?: { sessionId?: string }
 ): Promise<RouteTestHarness> {
  const app = Fastify({ logger: false });

@@ -34,6 +35,9 @@ export async function createRouteTestHarness(
  const ctx = createMockRouteContext(ctxOptions);

  registerFn(app, ctx);
+  // Mirror production: structured errors thrown by route helpers (findSessionOrFail,
+  // parseBody) are rendered to {success:false} bodies at the right status.
+  installRouteErrorHandler(app);
  await app.ready();

  return { app, ctx };
@@ -104,9 +104,7 @@ describe('case-routes', () => {
    });

    it('includes hasClaudeMd flag', async () => {
-      mockedReaddir.mockResolvedValue([
-        { name: 'case-with-md', isDirectory: () => true },
-      ] as never);
+      mockedReaddir.mockResolvedValue([{ name: 'case-with-md', isDirectory: () => true }] as never);
      mockedExistsSync.mockReturnValue(true);

      const res = await harness.app.inject({
@@ -120,9 +118,7 @@ describe('case-routes', () => {

    it('includes linked cases from linked-cases.json', async () => {
      // CASES_DIR readdir returns one case
-      mockedReaddir.mockResolvedValue([
-        { name: 'regular-case', isDirectory: () => true },
-      ] as never);
+      mockedReaddir.mockResolvedValue([{ name: 'regular-case', isDirectory: () => true }] as never);
      // linked-cases.json is read second (after CASES_DIR readdir)
      let readCallCount = 0;
      mockedReadFile.mockImplementation(async () => {
@@ -158,7 +154,7 @@ describe('case-routes', () => {
        url: '/api/cases',
        payload: { name: 'invalid case name!!' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -169,7 +165,7 @@ describe('case-routes', () => {
        url: '/api/cases',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -180,7 +176,7 @@ describe('case-routes', () => {
        url: '/api/cases',
        payload: { name: '../etc' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -230,7 +226,7 @@ describe('case-routes', () => {
        url: '/api/cases/link',
        payload: { name: 'bad name!' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -241,7 +237,7 @@ describe('case-routes', () => {
        url: '/api/cases/link',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -294,7 +290,10 @@ describe('case-routes', () => {
      const body = JSON.parse(res.body);
      expect(body.success).toBe(true);
      expect(body.data.case.name).toBe('linked-project');
-      expect(harness.ctx.broadcast).toHaveBeenCalledWith('case:linked', expect.objectContaining({ name: 'linked-project' }));
+      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
+        'case:linked',
+        expect.objectContaining({ name: 'linked-project' })
+      );
    });
  });

@@ -312,7 +312,8 @@ describe('file-routes', () => {
        method: 'GET',
        url: `/api/sessions/${harness.ctx._sessionId}/file-raw?path=../../etc/shadow`,
      });
-      expect(res.statusCode).toBe(400);
+      // Path traversal returns 404 ("File not found") to avoid revealing the target exists.
+      expect(res.statusCode).toBe(404);
    });

    it('rejects overly large raw files', async () => {
@@ -38,7 +38,7 @@ describe('hook-event-routes', () => {
      expect(body.success).toBe(true);
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'hook:stop',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId })
      );
    });

@@ -55,7 +55,7 @@ describe('hook-event-routes', () => {
      expect(res.statusCode).toBe(200);
      expect(harness.ctx.sendPushNotifications).toHaveBeenCalledWith(
        'hook:idle_prompt',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId })
      );
    });

@@ -85,7 +85,7 @@ describe('hook-event-routes', () => {
          data: null,
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -98,7 +98,7 @@ describe('hook-event-routes', () => {
          event: 'stop',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -180,10 +180,7 @@ describe('hook-event-routes', () => {
        },
      });
      expect(res.statusCode).toBe(200);
-      expect(mockTracker.recordHookEvent).toHaveBeenCalledWith(
-        'stop',
-        expect.any(Object),
-      );
+      expect(mockTracker.recordHookEvent).toHaveBeenCalledWith('stop', expect.any(Object));
    });

    it('starts transcript watcher when transcript_path is provided', async () => {
@@ -199,7 +196,7 @@ describe('hook-event-routes', () => {
      expect(res.statusCode).toBe(200);
      expect(harness.ctx.startTranscriptWatcher).toHaveBeenCalledWith(
        harness.ctx._sessionId,
-        '/home/user/.claude/transcript.jsonl',
+        '/home/user/.claude/transcript.jsonl'
      );
    });

@@ -103,7 +103,7 @@ describe('orchestrator-routes', () => {
        url: '/api/orchestrator/start',
        payload: { goal: '' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -114,7 +114,7 @@ describe('orchestrator-routes', () => {
        url: '/api/orchestrator/start',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -228,7 +228,7 @@ describe('orchestrator-routes', () => {
        url: '/api/orchestrator/reject',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -80,7 +80,7 @@ describe('plan-routes', () => {
        url: '/api/cancel-plan-generation',
        payload: { orchestratorId: 12345 }, // should be string
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -129,7 +129,7 @@ describe('plan-routes', () => {
      expect(body.data.status).toBe('completed');
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'session:planTaskUpdate',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId, taskId: 'task-1' }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId, taskId: 'task-1' })
      );
    });

@@ -159,7 +159,7 @@ describe('plan-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/plan/task/task-1`,
        payload: { status: 'invalid_status' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -208,7 +208,7 @@ describe('plan-routes', () => {
      expect(body.data.completedCount).toBe(5);
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'session:planCheckpoint',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId })
      );
    });
  });
@@ -279,9 +279,7 @@ describe('plan-routes', () => {
    });

    it('rolls back to a previous version', async () => {
-      const mockPlan = [
-        { id: 'task-1', content: 'Step 1', status: 'pending' },
-      ];
+      const mockPlan = [{ id: 'task-1', content: 'Step 1', status: 'pending' }];
      harness.ctx._session.ralphTracker = {
        rollbackToVersion: vi.fn(() => ({ success: true, plan: mockPlan })),
      } as never;
@@ -296,7 +294,7 @@ describe('plan-routes', () => {
      expect(body.data).toHaveLength(1);
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'session:planRollback',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId, version: 1 }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId, version: 1 })
      );
    });

@@ -358,7 +356,7 @@ describe('plan-routes', () => {
      expect(body.data.content).toBe('New task');
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'session:planTaskAdded',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId })
      );
    });

@@ -372,7 +370,7 @@ describe('plan-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/plan/task`,
        payload: { priority: 'P1' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -65,7 +65,7 @@ describe('push-routes', () => {
        expect.objectContaining({
          endpoint: 'https://push.example.com/send/abc123',
          keys: { p256dh: 'test-p256dh-key', auth: 'test-auth-key' },
-        }),
+        })
      );
    });

@@ -87,7 +87,7 @@ describe('push-routes', () => {
        expect.objectContaining({
          userAgent: 'TestBrowser/1.0',
          pushPreferences: { 'session:idle': true, 'session:error': false },
-        }),
+        })
      );
    });

@@ -99,7 +99,7 @@ describe('push-routes', () => {
          keys: { p256dh: 'test-p256dh', auth: 'test-auth' },
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -112,7 +112,7 @@ describe('push-routes', () => {
          endpoint: 'https://push.example.com/send/abc123',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -160,7 +160,7 @@ describe('push-routes', () => {
        url: '/api/push/subscribe/sub-123',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -66,7 +66,9 @@ describe('ralph-routes', () => {
    });

    it('enables ralph tracker', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      const res = await harness.app.inject({
        method: 'POST',
@@ -79,7 +81,9 @@ describe('ralph-routes', () => {
    });

    it('disables ralph tracker', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      const res = await harness.app.inject({
        method: 'POST',
@@ -99,7 +103,7 @@ describe('ralph-routes', () => {
      });
      expect((harness.ctx.mux as Record<string, unknown>).updateRalphEnabled).toHaveBeenCalledWith(
        harness.ctx._sessionId,
-        true,
+        true
      );
    });

@@ -116,7 +120,9 @@ describe('ralph-routes', () => {
    });

    it('handles reset option', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      await harness.app.inject({
        method: 'POST',
@@ -127,7 +133,9 @@ describe('ralph-routes', () => {
    });

    it('configures completion phrase and max iterations', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      await harness.app.inject({
        method: 'POST',
@@ -138,7 +146,9 @@ describe('ralph-routes', () => {
    });

    it('sets max iterations independently', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      await harness.app.inject({
        method: 'POST',
@@ -154,7 +164,7 @@ describe('ralph-routes', () => {
        url: '/api/sessions/nonexistent/ralph-config',
        payload: { enabled: true },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -178,13 +188,15 @@ describe('ralph-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/ralph-config`,
        payload: { enabled: 'not-boolean' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });

    it('handles disableAutoEnable flag', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      await harness.app.inject({
        method: 'POST',
@@ -208,7 +220,9 @@ describe('ralph-routes', () => {

  describe('POST /api/sessions/:id/ralph-circuit-breaker/reset', () => {
    it('resets circuit breaker for valid session', async () => {
-      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<typeof createMockRalphTracker>;
+      const tracker = (harness.ctx._session as Record<string, unknown>).ralphTracker as ReturnType<
+        typeof createMockRalphTracker
+      >;

      const res = await harness.app.inject({
        method: 'POST',
@@ -225,7 +239,7 @@ describe('ralph-routes', () => {
        method: 'POST',
        url: '/api/sessions/nonexistent/ralph-circuit-breaker/reset',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -253,7 +267,7 @@ describe('ralph-routes', () => {
        method: 'GET',
        url: '/api/sessions/nonexistent/ralph-status',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -279,7 +293,7 @@ describe('ralph-routes', () => {
        method: 'GET',
        url: '/api/sessions/nonexistent/fix-plan',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -315,7 +329,7 @@ describe('ralph-routes', () => {
        url: '/api/sessions/nonexistent/fix-plan/import',
        payload: { content: 'test' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -326,7 +340,7 @@ describe('ralph-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/fix-plan/import`,
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -341,7 +355,7 @@ describe('ralph-routes', () => {
        url: '/api/sessions/nonexistent/ralph-prompt/write',
        payload: { content: 'test prompt' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -365,7 +379,7 @@ describe('ralph-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/ralph-prompt/write`,
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -379,7 +393,7 @@ describe('ralph-routes', () => {
        method: 'POST',
        url: '/api/sessions/nonexistent/fix-plan/write',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -405,7 +419,7 @@ describe('ralph-routes', () => {
        method: 'POST',
        url: '/api/sessions/nonexistent/fix-plan/read',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -432,7 +446,7 @@ describe('ralph-routes', () => {
        url: '/api/ralph-loop/start',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -466,7 +480,7 @@ describe('ralph-routes', () => {
          caseName: '../escape-path',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -172,7 +172,7 @@ describe('respawn-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/respawn/config`,
        payload: { idleTimeoutMs: 'not-a-number' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -196,7 +196,7 @@ describe('respawn-routes', () => {
      expect(mockController.updateConfig).toHaveBeenCalled();
      expect(harness.ctx.broadcast).toHaveBeenCalledWith(
        'respawn:configUpdated',
-        expect.objectContaining({ sessionId: harness.ctx._sessionId }),
+        expect.objectContaining({ sessionId: harness.ctx._sessionId })
      );
    });

@@ -114,7 +114,7 @@ describe('scheduled-routes', () => {
          prompt: '',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -125,7 +125,7 @@ describe('scheduled-routes', () => {
        url: '/api/scheduled',
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -139,7 +139,7 @@ describe('scheduled-routes', () => {
          workingDir: '/tmp/test;rm -rf /',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -171,11 +171,7 @@ describe('scheduled-routes', () => {
      const body = JSON.parse(res.body);
      expect(body.success).toBe(true);
      // Should default to 60 minutes
-      expect(harness.ctx.startScheduledRun).toHaveBeenCalledWith(
-        'test',
-        expect.any(String),
-        60,
-      );
+      expect(harness.ctx.startScheduledRun).toHaveBeenCalledWith('test', expect.any(String), 60);
    });
  });

@@ -7,6 +7,14 @@

 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+
+// Mock execFile so the send-key route's `tmux` invocation is observable (not run for real).
+const { execFile } = vi.hoisted(() => ({ execFile: vi.fn() }));
+vi.mock('node:child_process', async (orig) => {
+  const actual = await orig<typeof import('node:child_process')>();
+  return { ...actual, execFile };
+});
+
 import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';

 describe('session-routes', () => {
@@ -20,6 +28,44 @@ describe('session-routes', () => {
    await harness.app.close();
  });

+  // ========== POST /api/sessions/:id/send-key ==========
+
+  describe('POST /api/sessions/:id/send-key', () => {
+    it('routes tmux send-keys through the dedicated Codeman socket (-L)', async () => {
+      // Regression guard: bare `tmux` would hit the user's default server and never
+      // find a session that lives only on the Codeman socket (#80 regression class).
+      execFile.mockReset();
+      execFile.mockImplementation((_bin: string, _argv: string[], _opts: unknown, cb: (e: Error | null) => void) =>
+        cb(null)
+      );
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/sessions/test-session-1/send-key',
+        payload: { key: 'S-Enter' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(execFile).toHaveBeenCalledTimes(1);
+      const [bin, argv] = execFile.mock.calls[0];
+      expect(bin).toBe('tmux');
+      expect((argv as string[]).slice(0, 2)).toEqual(['-L', 'codeman']);
+      expect(argv).toContain('send-keys');
+      expect(argv).toContain('-H');
+    });
+
+    it('rejects keys outside the hex allowlist without invoking tmux', async () => {
+      execFile.mockReset();
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/sessions/test-session-1/send-key',
+        payload: { key: 'rm -rf' },
+      });
+      expect(JSON.parse(res.body).success).toBe(false);
+      expect(execFile).not.toHaveBeenCalled();
+    });
+  });
+
  // ========== GET /api/sessions ==========

  describe('GET /api/sessions', () => {
@@ -57,7 +103,7 @@ describe('session-routes', () => {
        method: 'GET',
        url: '/api/sessions/nonexistent',
      });
-      expect(res.statusCode).toBe(200); // returns error in body, not HTTP 404
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
      expect(body.error).toBeDefined();
@@ -128,7 +174,7 @@ describe('session-routes', () => {
        url: '/api/sessions/nonexistent/name',
        payload: { name: 'test' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -181,7 +227,7 @@ describe('session-routes', () => {
        url: '/api/sessions/nonexistent/input',
        payload: { input: 'hello' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -192,7 +238,7 @@ describe('session-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/input`,
        payload: {},
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -219,7 +265,7 @@ describe('session-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/resize`,
        payload: { cols: 501, rows: 24 },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -230,7 +276,7 @@ describe('session-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/resize`,
        payload: { cols: 80, rows: 201 },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -241,7 +287,7 @@ describe('session-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/resize`,
        payload: { cols: 0, rows: 24 },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -266,7 +312,7 @@ describe('session-routes', () => {
        method: 'GET',
        url: '/api/sessions/nonexistent/terminal',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -292,7 +338,7 @@ describe('session-routes', () => {
        url: `/api/sessions/${harness.ctx._sessionId}/run`,
        payload: { prompt: '' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -303,7 +349,7 @@ describe('session-routes', () => {
        url: '/api/sessions/nonexistent/run',
        payload: { prompt: 'test' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -340,7 +386,7 @@ describe('session-routes', () => {
        method: 'POST',
        url: '/api/sessions/nonexistent/interactive',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -404,7 +450,7 @@ describe('session-routes', () => {
        method: 'GET',
        url: '/api/sessions/nonexistent/output',
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(404);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -540,7 +586,7 @@ describe('session-routes', () => {
          resumeSessionId: 'not-a-uuid',
        },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -166,7 +166,7 @@ describe('system-routes', () => {
        url: '/api/config',
        payload: { unknownField: 'invalid' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -361,7 +361,7 @@ describe('system-routes', () => {
        url: '/api/settings',
        payload: { unknownField: 'bad' },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -459,7 +459,7 @@ describe('system-routes', () => {
        url: '/api/subagent-window-states',
        payload: { minimized: { 'agent-1': 'not-a-boolean' } },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -516,7 +516,7 @@ describe('system-routes', () => {
        url: '/api/subagent-parents',
        payload: { 'agent-1': 123 },
      });
-      expect(res.statusCode).toBe(200);
+      expect(res.statusCode).toBe(400);
      const body = JSON.parse(res.body);
      expect(body.success).toBe(false);
    });
@@ -0,0 +1,76 @@
+/**
+ * POST /api/system/span-displays (multi-monitor launcher) + resolveSpanUrl.
+ *
+ * The route shells out to scripts/span-codeman.sh, so we mock child_process.spawn
+ * to avoid actually opening a browser (and to assert the sanitized URL passed to
+ * it). process.platform is overridden per-case so the macOS-only guard is tested
+ * deterministically regardless of where the suite runs.
+ *
+ * Port: N/A (app.inject).
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+const spawnMock = vi.hoisted(() => vi.fn(() => ({ on: vi.fn(), unref: vi.fn() })));
+vi.mock('node:child_process', async (orig) => {
+  const actual = await orig<typeof import('node:child_process')>();
+  return { ...actual, spawn: spawnMock };
+});
+
+import { createRouteTestHarness } from './_route-test-utils.js';
+import { registerSystemRoutes, resolveSpanUrl } from '../../src/web/routes/system-routes.js';
+
+const REAL_PLATFORM = process.platform;
+function setPlatform(p: NodeJS.Platform) {
+  Object.defineProperty(process, 'platform', { value: p, configurable: true });
+}
+afterEach(() => {
+  setPlatform(REAL_PLATFORM);
+  spawnMock.mockClear();
+});
+
+describe('resolveSpanUrl', () => {
+  it('takes a digits-only port from the Host header, pinned to localhost', () => {
+    expect(resolveSpanUrl('localhost:5000')).toBe('http://localhost:5000');
+    // Hostname is discarded — always localhost (same machine).
+    expect(resolveSpanUrl('attacker.example.com:3000')).toBe('http://localhost:3000');
+  });
+
+  it('falls back to the default port for missing / non-numeric ports', () => {
+    expect(resolveSpanUrl(undefined)).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost:99;rm -rf /')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('localhost:80abc')).toBe('http://localhost:3000');
+    expect(resolveSpanUrl('x', '5000')).toBe('http://localhost:5000');
+  });
+});
+
+describe('POST /api/system/span-displays', () => {
+  it('returns 400 (macOS-only) on non-darwin and never spawns', async () => {
+    setPlatform('linux');
+    const { app } = await createRouteTestHarness(registerSystemRoutes);
+    const res = await app.inject({ method: 'POST', url: '/api/system/span-displays' });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().success).toBe(false);
+    expect(res.json().error).toMatch(/macOS/i);
+    expect(spawnMock).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it('spawns the launcher with the sanitized localhost URL on darwin', async () => {
+    setPlatform('darwin');
+    const { app } = await createRouteTestHarness(registerSystemRoutes);
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/system/span-displays',
+      headers: { host: 'localhost:5000' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toMatchObject({ success: true, url: 'http://localhost:5000' });
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = spawnMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe('bash');
+    expect(args[0]).toMatch(/span-codeman\.sh$/);
+    expect(args[1]).toBe('http://localhost:5000');
+    await app.close();
+  });
+});
@@ -77,9 +77,24 @@ describe('TmuxManager (unit)', () => {
  });

  describe('getAttachArgs', () => {
-    it('should return attach-session args', () => {
+    it('should attach every session through the dedicated Codeman socket', () => {
      const args = manager.getAttachArgs('codeman-abc12345');
-      expect(args).toEqual(['attach-session', '-t', 'codeman-abc12345']);
+      expect(args).toEqual(['-L', 'codeman', 'attach-session', '-t', 'codeman-abc12345']);
+    });
+
+    it('should attach registered sessions on the same dedicated socket (no per-session socket)', () => {
+      manager.registerSession({
+        sessionId: 'some-session',
+        muxName: 'codeman-abc12345',
+        pid: 12345,
+        createdAt: Date.now(),
+        workingDir: '/tmp',
+        mode: 'claude',
+        attached: false,
+      });
+
+      const args = manager.getAttachArgs('codeman-abc12345');
+      expect(args).toEqual(['-L', 'codeman', 'attach-session', '-t', 'codeman-abc12345']);
    });
  });

@@ -8,7 +8,8 @@
 * the next frame — visible flicker and one lost repaint of scrollback.
 *
 * The fix queries tmux for the actual window geometry first via
- * `tmux display -t <name> -p '#{window_width} #{window_height}'`. We cover:
+ * `tmux -L <socket> display -t <name> -p '#{window_width} #{window_height}'`
+ * (the `-L <socket>` targets the isolated Codeman socket). We cover:
 *   - Happy path: tmux reports valid geometry → those numbers are used.
 *   - Browser-resize-between-attaches: tmux reports a non-default size
 *     (because a prior client resized it) → the helper picks that up.
@@ -49,7 +50,7 @@ beforeEach(() => {
 describe('queryTmuxWindowSize — happy path', () => {
  it('returns the geometry tmux reports', () => {
    execFileSync.mockReturnValue('200 50\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual({ cols: 200, rows: 50 });
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual({ cols: 200, rows: 50 });
  });

  it('picks up a non-default size left behind by a prior client (browser-resize-between-attaches)', () => {
@@ -57,12 +58,12 @@ describe('queryTmuxWindowSize — happy path', () => {
    // tmux keeps the last-attached geometry. Client B re-attaches and should spawn
    // its PTY at 220x60, not 120x40 — that's the whole point of #80.
    execFileSync.mockReturnValue('220 60');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual({ cols: 220, rows: 60 });
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual({ cols: 220, rows: 60 });
  });

  it('tolerates trailing whitespace and newlines in tmux output', () => {
    execFileSync.mockReturnValue('  180 45  \n\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual({ cols: 180, rows: 45 });
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual({ cols: 180, rows: 45 });
  });
 });

@@ -75,7 +76,7 @@ describe('queryTmuxWindowSize — fallback paths', () => {
      err.status = 1;
      throw err;
    });
-    expect(queryTmuxWindowSize('bogus')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('bogus', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when tmux dies between query and parse (ETIMEDOUT / ENOENT)', () => {
@@ -85,63 +86,65 @@ describe('queryTmuxWindowSize — fallback paths', () => {
      err.code = 'ETIMEDOUT';
      throw err;
    });
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when tmux returns empty output', () => {
    execFileSync.mockReturnValue('');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when tmux returns whitespace-only output', () => {
    execFileSync.mockReturnValue('   \n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when tmux returns non-numeric output', () => {
    execFileSync.mockReturnValue('not a size\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when only one dimension is present', () => {
    execFileSync.mockReturnValue('200\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when a dimension is zero (degenerate geometry)', () => {
    // tmux reporting `0` would crash node-pty downstream — must not propagate.
    execFileSync.mockReturnValue('0 40\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
    execFileSync.mockReturnValue('120 0\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when a dimension is negative', () => {
    execFileSync.mockReturnValue('-200 -50\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });

  it('falls back when tmux returns NaN-producing tokens', () => {
    execFileSync.mockReturnValue('abc def\n');
-    expect(queryTmuxWindowSize('codeman-abc')).toEqual(DEFAULT);
+    expect(queryTmuxWindowSize('codeman-abc', 'codeman')).toEqual(DEFAULT);
  });
 });

 describe('queryTmuxWindowSize — call shape', () => {
-  it('invokes tmux with display -t <name> -p ... via argv (not a shell)', () => {
+  it('invokes tmux on the dedicated socket via argv (not a shell)', () => {
    execFileSync.mockReturnValue('120 40\n');
-    queryTmuxWindowSize('codeman-abc');
+    queryTmuxWindowSize('codeman-abc', 'codeman');
    expect(execFileSync).toHaveBeenCalledTimes(1);
    const [bin, argv, opts] = execFileSync.mock.calls[0];
    expect(bin).toBe('tmux');
-    expect(argv).toEqual(['display', '-t', 'codeman-abc', '-p', '#{window_width} #{window_height}']);
+    // `-L <socket>` MUST lead: querying the default server would never find a
+    // session that lives on the isolated Codeman socket (the #80 regression).
+    expect(argv).toEqual(['-L', 'codeman', 'display', '-t', 'codeman-abc', '-p', '#{window_width} #{window_height}']);
    // execFileSync — not execSync — so muxName is never substituted into a shell string.
    expect(opts).toMatchObject({ encoding: 'utf8' });
  });

  it('uses a bounded timeout so a hung tmux server cannot block startup forever', () => {
    execFileSync.mockReturnValue('120 40\n');
-    queryTmuxWindowSize('codeman-abc');
+    queryTmuxWindowSize('codeman-abc', 'codeman');
    const [, , opts] = execFileSync.mock.calls[0];
    // Whatever the exact constant, the contract is: ≤5s so the user-visible
    // attach path can't hang on a stuck tmux server.
@@ -152,12 +155,12 @@ describe('queryTmuxWindowSize — call shape', () => {

  it('passes a muxName that looks like a tmux flag as an argv element (no option injection)', () => {
    execFileSync.mockReturnValue('120 40\n');
-    queryTmuxWindowSize('-x 1 -y 1; rm -rf');
+    queryTmuxWindowSize('-x 1 -y 1; rm -rf', 'codeman');
    const [, argv] = execFileSync.mock.calls[0];
-    // The whole "name" lives in a single argv slot, so tmux interprets it as a
-    // target session name, not as additional flags. The `-t` flag preceding it
-    // pins it as the target argument.
-    expect(argv?.[2]).toBe('-x 1 -y 1; rm -rf');
+    // The whole "name" lives in a single argv slot (index 4, after `-L codeman
+    // display -t`), so tmux interprets it as a target session name, not as
+    // additional flags. The `-t` flag preceding it pins it as the target.
+    expect(argv?.[4]).toBe('-x 1 -y 1; rm -rf');
    expect((argv as string[]).indexOf('-x')).toBe(-1);
  });
 });
@@ -0,0 +1,218 @@
+/**
+ * WebGL longtask auto-fallback tests.
+ *
+ * Covers the three follow-ups from #89:
+ *   1. Pure trip-detection helper — rolling-window arithmetic for the
+ *      "N longtasks of >=Xms within Yms" trip condition. Unit-tested
+ *      independently of PerformanceObserver, which can't be driven
+ *      deterministically from JS (entries arrive from the platform).
+ *   2. Constants are hoisted from inline literals to `WEBGL_FALLBACK`
+ *      in constants.js — assert they exist with the documented values.
+ *   3. Observer disconnect — _disposeWebGLObserver() is idempotent and
+ *      can be called from the onContextLoss path without the addon
+ *      having been initialised. Mirrors the leak case in the issue:
+ *      "observer outlives its addon" when teardown precedes a trip.
+ *
+ * Strategy: load the static app shell in a headless browser and drive
+ * the helper through page.evaluate(). No real PTY/tmux/WebGL needed —
+ * the trip math is pure and the dispose path is a couple of property
+ * mutations, both of which run on any page where app.js loaded.
+ *
+ * Port: 3166 (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 = 3166;
+const BASE_URL = `http://localhost:${PORT}`;
+
+describe('WebGL longtask auto-fallback', () => {
+  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 });
+    page = await browser.newPage();
+    await page.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
+    // Wait for constants.js + app.js to have loaded — both expose globals.
+    await page.waitForFunction(
+      () =>
+        typeof (window as { WEBGL_FALLBACK?: unknown }).WEBGL_FALLBACK !== 'undefined' &&
+        typeof (window as { evaluateWebGLLongTaskTrip?: unknown }).evaluateWebGLLongTaskTrip === 'function' &&
+        typeof (window as { app?: unknown }).app !== 'undefined'
+    );
+  }, 60000);
+
+  afterAll(async () => {
+    if (browser) await browser.close();
+    if (server) await server.stop();
+  }, 60000);
+
+  describe('constants are hoisted', () => {
+    it('WEBGL_FALLBACK exposes documented thresholds', async () => {
+      const cfg = await page.evaluate(
+        () => (window as unknown as { WEBGL_FALLBACK: Record<string, number> }).WEBGL_FALLBACK
+      );
+      expect(cfg).toEqual({
+        LONGTASK_MS: 200,
+        LONGTASK_COUNT: 3,
+        WINDOW_MS: 30000,
+        GRACE_MS: 5000,
+        STICKY_EXPIRY_MS: 7 * 24 * 60 * 60 * 1000,
+      });
+    });
+  });
+
+  describe('evaluateWebGLLongTaskTrip — rolling window arithmetic', () => {
+    type EvalFn = (
+      recent: number[],
+      entries: { startTime: number; duration: number }[],
+      now: number
+    ) => { tripped: boolean; recent: number[] };
+
+    /** Run the pure helper in the page and return the post-call state. */
+    const run: EvalFn = async (recent, entries, now) =>
+      page.evaluate(
+        ({ r, e, n }) => {
+          const fn = (
+            window as unknown as {
+              evaluateWebGLLongTaskTrip: (
+                rec: number[],
+                ents: { startTime: number; duration: number }[],
+                now: number
+              ) => boolean;
+            }
+          ).evaluateWebGLLongTaskTrip;
+          const recent = [...r];
+          const tripped = fn(recent, e, n);
+          return { tripped, recent };
+        },
+        { r: recent, e: entries, n: now }
+      ) as unknown as { tripped: boolean; recent: number[] };
+
+    it('trips when 3 longtasks fall inside the 30s window', async () => {
+      const entries = [
+        { startTime: 1000, duration: 250 },
+        { startTime: 5000, duration: 300 },
+        { startTime: 10000, duration: 220 },
+      ];
+      const result = await run([], entries, 12000);
+      expect(result.tripped).toBe(true);
+      expect(result.recent).toEqual([1000, 5000, 10000]);
+    });
+
+    it('does not trip when 3 longtasks are spread across 60s', async () => {
+      // 3 longtasks 25s apart — only the most recent two stay inside 30s.
+      const entries = [
+        { startTime: 1000, duration: 250 },
+        { startTime: 26000, duration: 250 },
+        { startTime: 51000, duration: 250 },
+      ];
+      const result = await run([], entries, 51100);
+      expect(result.tripped).toBe(false);
+      // First entry pruned (1000 is >30s before now=51100); 26000 and 51000 stay.
+      expect(result.recent).toEqual([26000, 51000]);
+    });
+
+    it('ignores entries shorter than 200ms', async () => {
+      const entries = [
+        { startTime: 1000, duration: 199 },
+        { startTime: 2000, duration: 100 },
+        { startTime: 3000, duration: 50 },
+      ];
+      const result = await run([], entries, 3500);
+      expect(result.tripped).toBe(false);
+      expect(result.recent).toEqual([]);
+    });
+
+    it('prunes stale entries even when no new ones arrive', async () => {
+      // Existing window has 2 stale + 1 fresh; an empty batch should still
+      // age out the stale ones so the next real batch evaluates correctly.
+      const recent = [1000, 5000, 40000];
+      const result = await run(recent, [], 41000);
+      expect(result.tripped).toBe(false);
+      expect(result.recent).toEqual([40000]);
+    });
+
+    it('counts entries cumulatively across batches', async () => {
+      // Two batches of 2 entries each, all inside the window — second
+      // batch should push the cumulative count to 4 and trip.
+      const recent: number[] = [];
+      const first = await run(
+        recent,
+        [
+          { startTime: 1000, duration: 250 },
+          { startTime: 2000, duration: 250 },
+        ],
+        3000
+      );
+      expect(first.tripped).toBe(false);
+      expect(first.recent).toEqual([1000, 2000]);
+
+      const second = await run(
+        first.recent,
+        [
+          { startTime: 4000, duration: 250 },
+          { startTime: 5000, duration: 250 },
+        ],
+        6000
+      );
+      expect(second.tripped).toBe(true);
+      expect(second.recent).toEqual([1000, 2000, 4000, 5000]);
+    });
+  });
+
+  describe('_disposeWebGLObserver', () => {
+    it('is idempotent — safe to call when no observer was installed', async () => {
+      const ok = await page.evaluate(() => {
+        const app = (
+          window as unknown as { app: { _disposeWebGLObserver: () => void; _webglLongTaskObserver: unknown } }
+        ).app;
+        app._webglLongTaskObserver = null;
+        app._disposeWebGLObserver();
+        app._disposeWebGLObserver();
+        return app._webglLongTaskObserver === null;
+      });
+      expect(ok).toBe(true);
+    });
+
+    it('disconnects a stub observer and nulls the reference', async () => {
+      const result = await page.evaluate(() => {
+        const app = (
+          window as unknown as { app: { _disposeWebGLObserver: () => void; _webglLongTaskObserver: unknown } }
+        ).app;
+        let disconnectCalls = 0;
+        app._webglLongTaskObserver = {
+          disconnect() {
+            disconnectCalls++;
+          },
+        } as unknown;
+        app._disposeWebGLObserver();
+        return { disconnectCalls, ref: app._webglLongTaskObserver };
+      });
+      expect(result.disconnectCalls).toBe(1);
+      expect(result.ref).toBeNull();
+    });
+
+    it('swallows a throwing disconnect — guards against driver quirks', async () => {
+      const result = await page.evaluate(() => {
+        const app = (
+          window as unknown as { app: { _disposeWebGLObserver: () => void; _webglLongTaskObserver: unknown } }
+        ).app;
+        app._webglLongTaskObserver = {
+          disconnect() {
+            throw new Error('synthetic');
+          },
+        } as unknown;
+        app._disposeWebGLObserver();
+        return app._webglLongTaskObserver;
+      });
+      expect(result).toBeNull();
+    });
+  });
+});