chore: release 0.9.0 — security hardening + warn-don't-block network policy

Release 0.9.0 covering the merged security/reliability PRs (#106 deps/
supply-chain, #107 auth/network, #108 test stability, #110 tmux cwd) plus:

- Network policy: a non-loopback bind without CODEMAN_PASSWORD now STARTS
  with a loud warning (3 ways to secure) instead of refusing to start.
  Loopback stays the safe default. --allow-unauthenticated-network just
  acknowledges (terser note). (src/web/server.ts start())
- Post-install security note explaining the loopback default + safe exposure.
- New docs/security-architecture.md documenting the full model (binding,
  auth pipeline, tunnel req.ip caveat, file-serving, supply-chain, isolation,
  recommended setups). CLAUDE.md Security section + gotcha updated.
- Updated auth-security test: asserts warn-and-start (not throw).

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

.gitignore

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

.prettierignore

@@ -2,8 +2,27 @@ dist/
 coverage/
 node_modules/
 src/web/public/vendor/
+src/web/public/gesture/
 src/web/public/app.js
 src/web/public/styles.css
 src/web/public/mobile.css
 src/web/public/index.html
+# Hand-formatted public JS modules (never prettier-enforced; the new
+# check-public-assets.mjs still validates NUL bytes + JS syntax on these).
+src/web/public/constants.js
+src/web/public/image-input.js
+src/web/public/input-cjk.js
+src/web/public/keyboard-accessory.js
+src/web/public/notification-manager.js
+src/web/public/orchestrator-panel.js
+src/web/public/panels-ui.js
+src/web/public/ralph-panel.js
+src/web/public/ralph-wizard.js
+src/web/public/respawn-ui.js
+src/web/public/session-ui.js
+src/web/public/settings-ui.js
+src/web/public/sw.js
+src/web/public/terminal-ui.js
+src/web/public/voice-input.js
+src/web/public/upload.html
 scripts/remotion/

CHANGELOG.md

@@ -1,5 +1,77 @@
 # aicodeman
 
+## 0.9.0
+
+### Minor Changes
+
+- Security hardening release: network-bind policy, auth lockout recovery, download/SVG hardening, dependency & supply-chain fixes, tmux launch reliability, and a full security-architecture doc.
+
+  **Network binding (COD-29, #107):**
+  - The web server now defaults to binding `127.0.0.1` (loopback) instead of `0.0.0.0`, so a fresh install is reachable only from the same machine and needs no password. New `--host` / `-H` / `CODEMAN_HOST` flag to choose the bind host.
+  - Binding a non-loopback host **without** `CODEMAN_PASSWORD` no longer refuses to start — it **starts and prints a loud warning** with the three ways to secure it (set `CODEMAN_PASSWORD`, bind loopback + an authenticated tunnel / `tailscale serve`, or acknowledge with `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1`). This keeps Codeman "just working" for new users while making remote exposure a guided, explicit choice. Host classification lives in the new `src/web/network-auth-policy.ts` (handles `127.0.0.0/8`, `::1`, `::ffff:127.*`, bracketed IPv6).
+  - A post-install security note now explains the loopback default and how to expose safely.
+
+  **Authentication (COD-29, #107):**
+  - Auth lockout now recovers gracefully: the per-IP rate-limit (`429`) check runs **after** the cookie/credential checks, so a valid session cookie or correct password is never locked out by a prior attacker's failures from the same IP (important behind a shared-IP tunnel). Wrong credentials are still counted and still hit the limit, and a `Retry-After` header is returned.
+
+  **Downloads & content-type hardening (COD-29, #107):**
+  - New session-scoped `POST /api/download` route: realpath-bounded to the session working dir, a sensitive-path blocklist (`/etc/shadow`, `~/.ssh/`, `.env`, `*credentials*`, …), `isFile()` + 50 MB cap, forced `attachment`.
+  - Workspace `.svg` files are served as `application/octet-stream` + `attachment` + `nosniff` (closes a stored-XSS-via-SVG vector); `nosniff` now applies to all `file-raw` responses.
+
+  **Dependencies & supply chain (COD-28, #106):**
+  - Bumped security-sensitive deps to patched versions (`@fastify/static` 9, `fastify` 5.8, `uuid` 14, `vitest` 4.1, …) and added `overrides` for patched transitives (`picomatch`, `basic-ftp`, `fast-uri`, `flatted`); `npm audit` goes from 7 advisories to 0.
+  - New `npm run check:public-assets` (`scripts/check-public-assets.mjs`): scans `src/web/public/**` for literal NUL bytes and runs `node --check` on every `.js` file, plus a Prettier pass on maintained files. Removed literal NUL placeholders from `app.js`. Added `test/dependency-security.test.ts` and `test/frontend-public-tooling.test.ts`.
+
+  **tmux launch reliability (COD-31, #110):**
+  - New tmux sessions and respawns launch from a stable `/tmp` and `cd` into the workspace inside the pane, avoiding `new-session` crashes when a FUSE/rclone-mounted workspace has a transient mount blip at launch. The `cd "<dir>" && <cmd>` form is fail-safe (the CLI never runs in `/tmp`) and the path is validated + double-quoted.
+
+  **Test stability (COD-30, #108):**
+  - Cleared leaked auth env in the Vitest setup, corrected stale route status-code / SSE-lifecycle expectations to match shipped behavior, updated the mobile keyboard accessory expectations, and measured DOMContentLoaded via browser navigation timing. Also fixed the `WebServer` title tests for the new `host` constructor arg + async `renderIndexHtml`.
+
+  **Docs:**
+  - New `docs/security-architecture.md` documenting the full model (network binding, auth pipeline, the tunnel `req.ip` caveat, file-serving hardening, supply-chain, multi-instance isolation, security headers, and recommended secure setups). CLAUDE.md updated accordingly.
+
+## 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

CLAUDE.md

@@ -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.7.1 (must match `package.json`)
+**Version**: 0.9.0 (must match `package.json`)
 
 ## Project Overview
 
@@ -72,19 +72,21 @@ 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 |
 |------|---------|
 | Dev with TLS | `npx tsx src/index.ts web --https` |
 | Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix) |
+| Bind a non-loopback host | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
 | Continuous typecheck | `tsc --noEmit --watch` |
 | Test coverage | `npm run test:coverage` |
 | Dead-code sweep | `npm run knip` (config in `knip.json`) |
+| Check public-asset formatting | `npm run check:public-assets` (prettier-checks `src/web/public/**` text assets; `scripts/check-public-assets.mjs`) |
 | Production start | `npm run start` |
 | Production logs | `journalctl --user -u codeman-web -f` |
 
-**CI**: `.github/workflows/ci.yml` runs `check:lockfile`, `typecheck`, `lint`, `format:check` on push to master/main and on PRs (Node 22). Tests excluded (they spawn tmux).
+**CI**: `.github/workflows/ci.yml` runs `check:lockfile`, `typecheck`, `lint`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s) on push to master/main and on PRs (Node 22). The unit test suite is excluded (it spawns tmux).
 
 **Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`). ESLint flat config (`config/eslint.config.js`) allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Ignores: `app.js`, `scripts/**/*.mjs`, `src/web/public/vendor/**`, `scripts/remotion/**`.
 
@@ -95,9 +97,12 @@ 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
+- **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. See `docs/local-echo-overlay-plan.md`.
+- **Default bind is loopback-only; non-loopback without a password starts but warns** — since COD-29 (PR #107) the web server defaults to `--host 127.0.0.1` (was `0.0.0.0`). As of **0.9.0** binding a non-loopback host (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **no longer refuses to start — it starts and prints a loud warning** listing the fixes (set `CODEMAN_PASSWORD`, bind loopback + tunnel/`tailscale serve`, or `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` to acknowledge → terser note). Host classification is `isLoopbackBindHost()` in `network-auth-policy.ts`; the warn-vs-start logic is in `server.ts` `start()`; flags wired in `cli.ts`. ⚠️ Operational note: the production systemd unit runs `node dist/index.js web --https` with no `--host`, so it binds **localhost only** — reach it remotely via `tailscale serve`/tunnel to `127.0.0.1`, or add `Environment=CODEMAN_HOST=0.0.0.0` + `Environment=CODEMAN_PASSWORD=…` to `~/.config/systemd/user/codeman-web.service`. A loopback bind is reachable through a same-host tunnel (cloudflared/tailscale → `127.0.0.1`) but NOT by a browser hitting the box's LAN IP. Auth user defaults to `admin`. **Full model: `docs/security-architecture.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.
 
@@ -120,14 +125,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` (~3.1K 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` | |
+| **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 +149,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,15 +165,22 @@ 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).
 
 ### Security
 
+**Full model: [`docs/security-architecture.md`](docs/security-architecture.md)** — network binding, auth pipeline, the tunnel caveat, file-serving hardening, supply-chain, instance isolation, and recommended secure setups.
+
 | Layer | Details |
 |-------|---------|
-| **Auth** | Optional HTTP Basic via `CODEMAN_USERNAME`/`CODEMAN_PASSWORD` env vars |
+| **Auth** | Optional HTTP Basic via `CODEMAN_USERNAME` (defaults to `admin`) / `CODEMAN_PASSWORD` env vars. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`) |
+| **Network bind** | Defaults to `127.0.0.1` (loopback). A non-loopback bind (`--host`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **starts but warns loudly** (0.9.0; was fail-closed in COD-29/#107). `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges the warning. Classifier: `network-auth-policy.ts` |
 | **QR Auth** | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md` |
 | **Sessions** | 24h cookie (`codeman_session`), auto-extend, device context audit |
 | **Rate limit** | 10 failed auth/IP → 429 (15min decay). QR has separate limiter |
@@ -181,7 +195,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### API Routes
 
-~130 handlers across 15 route files in `src/web/routes/`: system (36), 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.
+~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
 

docs/security-architecture.md

@@ -0,0 +1,319 @@
+# Security Architecture
+
+This document describes Codeman's security model: how it decides who may reach
+the web UI, how requests are authenticated, how the file-serving and tmux layers
+are hardened, and the recommended ways to expose an instance safely.
+
+Codeman spawns and drives Claude/OpenCode CLIs with
+`--dangerously-skip-permissions`. **Anyone who can reach an unauthenticated
+instance can run arbitrary commands as your user.** The defaults below are chosen
+so that a fresh install is safe on the machine it runs on, while remote access is
+an explicit, guided opt‑in.
+
+> TL;DR — Codeman binds **loopback only (`127.0.0.1`) by default**, so out of the
+> box it is reachable only from the same machine and needs no password. To reach
+> it from elsewhere, either put it behind an **authenticated tunnel**
+> (`tailscale serve` / `cloudflared`) **or** bind a wider host **and set
+> `CODEMAN_PASSWORD`**. If you bind a non‑loopback host with no password, Codeman
+> still starts but prints a **loud warning** telling you how to secure it.
+
+---
+
+## 1. Network binding model
+
+| Setting | Default | Source |
+|---------|---------|--------|
+| Bind host | `127.0.0.1` (loopback) | `--host` / `CODEMAN_HOST` → `WebServer` ctor |
+| Port | `3000` | `--port` / `CODEMAN_PORT` |
+| TLS | off (`--https` to enable) | `--https` |
+
+### Bind host classification
+
+`isLoopbackBindHost()` (`src/web/network-auth-policy.ts`) decides whether a bind
+host is loopback-only. It returns `true` for:
+
+- `localhost`
+- any IPv4 in `127.0.0.0/8` (e.g. `127.0.0.1`, `127.42.0.9`)
+- IPv6 loopback `::1` (bracketed `[::1]` and the long form `0:0:0:0:0:0:0:1`)
+- IPv4‑mapped loopback `::ffff:127.*`
+
+It returns `false` for `0.0.0.0`, `::` (all interfaces), LAN IPs, and hostnames.
+The classification is **fail‑safe in the dangerous direction**: any host that is
+not provably loopback is treated as non‑loopback (it never mistakes `0.0.0.0`
+for loopback). Shorthand forms like `127.1` or integer/octal IPs classify as
+non‑loopback (you'll get a warning, not a silent wide‑open bind) — use
+`127.0.0.1` for an unambiguous loopback bind.
+
+### Startup policy (the "warn, don't block" rule)
+
+At `WebServer.start()`:
+
+| Bind host | `CODEMAN_PASSWORD` | Behavior |
+|-----------|--------------------|----------|
+| loopback (default) | unset | **Start.** Safe — reachable only from this machine. |
+| loopback | set | **Start.** Auth required even locally. |
+| non‑loopback | set | **Start.** Auth protects the open bind. |
+| non‑loopback | unset | **Start + LOUD warning** listing how to secure it. |
+| non‑loopback | unset, `--allow-unauthenticated-network` | **Start + terse acknowledged note.** |
+
+> History: an earlier iteration (unreleased COD‑29) *refused to start* on a
+> non‑loopback bind without a password. That surprised setups that "just worked"
+> before, so **0.9.0 changed it to start‑and‑warn**. Loopback is still the safe
+> default; the warning (with three concrete fixes) replaces the hard failure.
+
+The warning points at three ways to secure the instance:
+
+1. `CODEMAN_PASSWORD=<password>` — turns on HTTP Basic auth (see §2).
+2. `--host 127.0.0.1` + an authenticated tunnel (`cloudflared` / `tailscale serve`).
+3. `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1`
+   — explicitly accept the risk (downgrades the warning to a one‑line note). This
+   flag is **only** an acknowledgement; it does not change reachability.
+
+`CODEMAN_API_URL` (used by hooks/child processes) is always derived as a loopback
+address (`0.0.0.0`/`localhost`/`::1` → `127.0.0.1`) so in‑process hooks reach the
+server over loopback regardless of the public bind.
+
+---
+
+## 2. Authentication
+
+Auth is **optional** and controlled by env vars captured at startup:
+
+- `CODEMAN_USERNAME` (default `admin` when only a password is set)
+- `CODEMAN_PASSWORD`
+
+When `CODEMAN_PASSWORD` is unset, no auth is enforced — which is why the default
+loopback bind matters. The auth pipeline (`src/web/middleware/auth.ts`,
+`onRequest` hook) runs in this order:
+
+1. **Localhost‑only exemptions** (always first): `POST /api/hook-event` and the QR
+   `/q/` short‑code path are exempt when `req.ip` is loopback (see §3).
+2. **Session cookie** check — a valid `codeman_session` cookie short‑circuits to
+   allow.
+3. **HTTP Basic** check — correct credentials short‑circuit to allow and clear
+   that IP's failure counter.
+4. **Rate‑limit gate** — if neither cookie nor credentials passed and the IP is
+   locked out, return `429` with a `Retry-After` header.
+5. Otherwise return `401`, incrementing the IP's failure counter.
+
+### Session cookies
+
+On successful Basic auth the server issues `codeman_session`, an opaque
+server‑side token (`randomBytes(32)`), valid 24h with auto‑extend and device
+context for the audit log. Tokens are **not** client‑signed — they're validated
+by presence in a server‑side map, so they cannot be forged offline.
+
+### Rate limiting / lockout recovery
+
+Failed auth is tracked **per IP**: 10 failures → `429`, with a 15‑minute decay.
+The QR path has its own separate limiter.
+
+The lockout check sits **after** the cookie/credential checks (step 4, not first).
+This is deliberate: a user with a **valid cookie or correct password recovers
+immediately** even while an attacker is hammering the same IP — important because
+all traffic through a tunnel shares one source IP (loopback). Wrong credentials
+are still counted and still hit the `429` at the threshold, so brute‑force
+protection is unchanged.
+
+---
+
+## 3. Request‑origin trust & the tunnel caveat
+
+`req.ip` is derived from the **TCP socket only** — Fastify runs with
+`trustProxy: false`, so `X-Forwarded-For` / `X-Real-IP` / `Forwarded` are
+**ignored**. A remote client cannot forge `req.ip` to `127.0.0.1`.
+
+**However**, a reverse tunnel that connects to the server over loopback (e.g.
+`cloudflared --url http://localhost:3000`) makes **every tunneled request arrive
+with `req.ip = 127.0.0.1`**. The localhost‑only exemptions then treat those
+requests as local:
+
+- `POST /api/hook-event` — auth‑exempt for loopback. Bounded impact: it is
+  `HookEventSchema`‑validated and requires a valid in‑memory `sessionId`; it can
+  drive respawn signals, SSE broadcasts, push notifications, and transcript
+  watching — **not** arbitrary terminal input or file reads. It is a
+  session‑disruption / notification‑spoofing surface, not RCE.
+- QR `/q/` — still protected by its own short‑code brute‑force limiter
+  (10 failures / 60s against a 62⁶ space).
+
+**Mitigation:** set `CODEMAN_PASSWORD` whenever a loopback‑connecting tunnel is
+up (it does not gate the hook‑event exemption, but it gates everything else and
+is the documented practice). Prefer `tailscale serve` (below), which authenticates
+at the tailnet layer so untrusted clients never reach the loopback port at all.
+A future hardening could gate the hook‑event exemption on a shared secret while a
+tunnel is active.
+
+---
+
+## 4. Recommended remote‑access setups
+
+Ordered most‑to‑least recommended:
+
+### A. Tailscale serve (recommended)
+
+Bind loopback, let Tailscale front it on your tailnet with a real cert:
+
+```bash
+codeman web --https            # binds 127.0.0.1:3000
+tailscale serve --bg https / http://127.0.0.1:3000
+```
+
+Only devices on your tailnet can reach it; Tailscale handles identity. No app
+password and no `0.0.0.0` bind required. (This is the maintainer's production
+setup.)
+
+### B. Authenticated cloudflared tunnel + password
+
+```bash
+export CODEMAN_PASSWORD=<password>
+codeman web --https
+cloudflared tunnel --url https://localhost:3000
+```
+
+Always set `CODEMAN_PASSWORD` here — the tunnel connects over loopback, so the
+hook‑event exemption (§3) would otherwise be reachable from the public URL.
+
+### C. Direct LAN bind + password
+
+```bash
+export CODEMAN_PASSWORD=<password>
+codeman web --https --host 0.0.0.0
+```
+
+Exposes the port on all interfaces; the password is the only thing protecting it.
+
+### Avoid
+
+`--host 0.0.0.0` **without** a password. Codeman will start (and warn), but
+anyone on the network can control your Claude sessions. Never re‑expose `0.0.0.0`
+without a password.
+
+---
+
+## 5. File‑serving hardening
+
+Three routes serve workspace files; all require a valid `sessionId` and run the
+shared path validator `validateSessionFilePath()` (`src/web/route-helpers.ts`):
+it `realpath`s the target **before** the boundary check and rejects anything that
+escapes the session working directory (`..`, absolute paths, and symlinks that
+resolve outside). The realpath‑before‑check ordering closes the validation‑time
+TOCTOU window.
+
+| Route | Cap | Notes |
+|-------|-----|-------|
+| `file-content` | 10 MB | text preview |
+| `file-raw` | 50 MB | inline MIME map; **`X-Content-Type-Options: nosniff` on all responses** |
+| `POST /api/download` | 50 MB | forced `attachment`; sensitive‑path blocklist |
+
+### SVG / content‑type XSS
+
+A workspace `.svg` served inline as `image/svg+xml` is a stored‑XSS vector (SVG
+can carry `<script>`, same‑origin = full session control). `file-raw` therefore
+serves `.svg` as `application/octet-stream` + `Content-Disposition: attachment` +
+`nosniff`. With global `nosniff` + CSP `default-src 'self'`, other text types
+(`.html`, `.xml`, …) that fall through to `octet-stream` are not rendered as HTML
+either. Trusted QR/welcome SVGs are injected from API JSON (`innerHTML`), not via
+`file-raw`, so they are unaffected.
+
+### Download sensitive‑path blocklist
+
+`/api/download` additionally refuses a blocklist of sensitive paths
+(`/etc/shadow`, `~/.ssh/`, `.env`, `*credentials*`, `.aws/credentials`, …). This
+is **defense‑in‑depth, not the primary boundary** — the realpath containment is
+the control.
+
+### Known limitation — `workingDir` scope
+
+The file‑route boundary is the session's `workingDir`, and `POST /api/sessions`
+currently accepts an arbitrary absolute `workingDir` (validated as "exists + is a
+directory"). A session created with `workingDir=/` can therefore read files
+across the filesystem within that boundary. This is **pre‑existing** across all
+file routes and not widened by the recent changes. Recommended follow‑up:
+constrain `workingDir` to an allowlist (e.g. under the cases dir / `$HOME`).
+
+---
+
+## 6. tmux launch hardening (COD‑31)
+
+New sessions and respawns launch the tmux server/pane from a stable `/tmp`
+(`TMUX_LAUNCH_CWD`) and then `cd` into the real workspace **inside** the pane,
+against the live mount table:
+
+```
+respawn-pane -k -c /tmp -t <session> bash -c "cd <workingDir> && <cmd>"
+```
+
+This avoids a class of failures on FUSE/rclone‑mounted workspaces where a
+transient mount blip at launch poisons tmux's long‑lived cwd and crashes
+`new-session`. Safety properties:
+
+- **Fail‑safe cwd:** the command is `cd "<dir>" && <cmd>` — if `cd` fails the CLI
+  does **not** run in `/tmp`; the pane dies with a visible error instead.
+- **No injection:** `workingDir` passes `isValidWorkingDir` (absolute, rejects
+  `;&|$\`(){}<>'"` and newlines and `..`) and `isValidPath`, and is double‑quoted
+  in the pane command. Paths with spaces work; metacharacters are rejected before
+  reaching the shell.
+- It does not change which tmux socket is targeted, so instance isolation (§8) is
+  preserved.
+
+---
+
+## 7. Supply‑chain & build‑asset hardening (COD‑28)
+
+- **Dependency advisories:** security‑sensitive ranges are bumped to patched
+  versions, and `overrides` force patched transitive deps (`picomatch`,
+  `basic-ftp`, `fast-uri`, `flatted`). `test/dependency-security.test.ts` asserts
+  these stay patched in the lockfile.
+- **Lockfile integrity:** `npm run check:lockfile` (CI on every push/PR) fails on
+  drift between `package.json` and `package-lock.json`. All lockfile entries
+  resolve to `registry.npmjs.org` with `sha512` integrity hashes.
+- **Public‑asset checker:** `npm run check:public-assets`
+  (`scripts/check-public-assets.mjs`) scans `src/web/public/**` for literal NUL
+  bytes and runs `node --check` on every `.js` file (syntax validation), plus a
+  Prettier pass on maintained files. It uses `execFileSync` with argv arrays (no
+  shell), so filenames/content cannot inject commands; `node --check` only parses,
+  never executes. Large hand‑formatted/generated assets (`app.js`, the gesture
+  bundle, vendored libs) are `.prettierignore`d for the style pass, but the NUL +
+  syntax checks still cover them.
+
+---
+
+## 8. Multi‑instance isolation
+
+The tmux socket (`tmux -L codeman[-<instance>]`) and data dir
+(`~/.codeman[-<instance>]`) are **process‑wide and shared by every Codeman on the
+machine**, derived from `CODEMAN_INSTANCE` (`src/config/instance.ts`). A second
+instance on the **same** socket discovers and attaches PTYs to the first
+instance's live sessions. To run instances side by side, give each a distinct
+`CODEMAN_INSTANCE` (scopes both dir + socket), or set `CODEMAN_TMUX_SOCKET` +
+`CODEMAN_DATA_DIR` individually. `CODEMAN_INSTANCE` defaults to empty = the
+production layout (`~/.codeman`, `-L codeman`, port 3000).
+
+---
+
+## 9. Transport security headers
+
+`registerSecurityHeaders` applies on every response:
+
+- `Content-Security-Policy: default-src 'self'` (widened only for `/gesture/`
+  assets when `CODEMAN_GESTURE=1`, to load self‑hosted MediaPipe)
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options`
+- `Strict-Transport-Security` when served over HTTPS
+- CORS restricted to localhost origins
+
+---
+
+## 10. Quick reference
+
+| Env / flag | Effect |
+|------------|--------|
+| `CODEMAN_PASSWORD` (+ `CODEMAN_USERNAME`) | Enable HTTP Basic auth |
+| `--host` / `CODEMAN_HOST` | Bind host (default `127.0.0.1`) |
+| `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` | Acknowledge an unauthenticated non‑loopback bind (downgrades the warning) |
+| `--https` | Enable TLS (adds HSTS) |
+| `CODEMAN_INSTANCE` | Scope tmux socket + data dir for isolation |
+| `CODEMAN_GESTURE=1` | Make the gesture overlay available (widens CSP) |
+
+**Audit log:** session lifecycle and server start are recorded in
+`~/.codeman/session-lifecycle.jsonl`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "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",
@@ -21,8 +21,9 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint --config config/eslint.config.js 'src/**/*.ts'",
     "lint:fix": "eslint --config config/eslint.config.js 'src/**/*.ts' --fix",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts' 'src/web/public/**/*.{js,css,html,json}'",
+    "format:check": "prettier --check 'src/**/*.ts' 'src/web/public/**/*.{js,css,html,json}'",
+    "check:public-assets": "node scripts/check-public-assets.mjs",
     "capture:subagents": "node scripts/capture-subagent-screenshots.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && npm install --package-lock-only && node scripts/check-lockfile-sync.mjs",
@@ -53,7 +54,7 @@
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
-    "@fastify/static": "^8.0.0",
+    "@fastify/static": "^9.1.3",
     "@fastify/websocket": "^11.2.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-unicode11": "^0.9.0",
@@ -62,18 +63,18 @@
     "chalk": "^5.3.0",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
-    "fastify": "^5.1.0",
+    "fastify": "^5.8.5",
     "node-pty": "^1.1.0",
     "qrcode": "^1.5.4",
-    "uuid": "^10.0.0",
+    "uuid": "^14.0.0",
     "web-push": "^3.6.7",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.0.0",
-    "@remotion/cli": "4.0.429",
-    "@remotion/transitions": "4.0.429",
+    "@remotion/cli": "4.0.473",
+    "@remotion/transitions": "4.0.473",
     "@types/node": "^20.19.33",
     "@types/pngjs": "^6.0.5",
     "@types/qrcode": "^1.5.6",
@@ -81,7 +82,7 @@
     "@types/uuid": "^10.0.0",
     "@types/web-push": "^3.6.4",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.8",
     "agent-browser": "^0.6.0",
     "esbuild": "^0.27.3",
     "eslint": "^9.0.0",
@@ -90,16 +91,30 @@
     "pngjs": "^7.0.0",
     "prettier": "^3.4.0",
     "puppeteer": "^24.36.0",
-    "remotion": "4.0.429",
+    "remotion": "4.0.473",
     "tsx": "^4.15.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.8"
   },
   "optionalDependencies": {
     "@remotion/compositor-linux-x64-gnu": "^4.0.432",
     "@rspack/binding-linux-x64-gnu": "^1.7.7"
   },
+  "overrides": {
+    "basic-ftp": "^5.3.1",
+    "fast-uri": "^3.1.2",
+    "flatted": "^3.4.2",
+    "anymatch": {
+      "picomatch": "^2.3.2"
+    },
+    "micromatch": {
+      "picomatch": "^2.3.2"
+    },
+    "readdirp": {
+      "picomatch": "^2.3.2"
+    }
+  },
   "engines": {
     "node": ">=18.0.0"
   },

packages/xterm-zerolag-input/package.json

@@ -45,6 +45,6 @@
     "jsdom": "^24.1.3",
     "tsup": "^8.5.1",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.9"
+    "vitest": "^4.1.8"
   }
 }

scripts/build.mjs

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

scripts/check-public-assets.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const publicRoot = resolve(repoRoot, 'src/web/public');
+const prettierBin = resolve(repoRoot, 'node_modules/.bin/prettier');
+const checkedExtensions = new Set(['.js', '.css', '.html', '.json']);
+
+function collectTextAssets(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectTextAssets(fullPath));
+      continue;
+    }
+    if (checkedExtensions.has(extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function findNullByte(buffer) {
+  for (let i = 0; i < buffer.length; i += 1) {
+    if (buffer[i] === 0) return i;
+  }
+  return -1;
+}
+
+const files = collectTextAssets(publicRoot);
+const failures = [];
+
+for (const file of files) {
+  const rel = relative(repoRoot, file);
+  const data = readFileSync(file);
+  const nullByteIndex = findNullByte(data);
+  if (nullByteIndex !== -1) {
+    failures.push(`${rel}: contains literal NUL byte at offset ${nullByteIndex}`);
+  }
+
+  if (extname(file) === '.js') {
+    try {
+      execFileSync(process.execPath, ['--check', file], { cwd: repoRoot, stdio: 'pipe' });
+    } catch (err) {
+      failures.push(`${rel}: JavaScript syntax check failed\n${String(err.stderr || err.message).trim()}`);
+    }
+  }
+}
+
+try {
+  execFileSync(prettierBin, ['--check', ...files], { cwd: repoRoot, stdio: 'pipe' });
+} catch (err) {
+  failures.push(`Prettier public asset check failed\n${String(err.stdout || err.stderr || err.message).trim()}`);
+}
+
+if (failures.length > 0) {
+  console.error(failures.join('\n\n'));
+  process.exit(1);
+}
+
+console.log(`Public asset checks passed (${files.length} files).`);

scripts/codeman-web.service

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

scripts/fetch-gesture-assets.mjs

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

scripts/postinstall.js

@@ -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)
 // ----------------------------------------------------------------------------
@@ -446,3 +460,16 @@ if (process.env.CI || process.env.CODEMAN_NO_AUTOSTART) {
         }
     }
 }
+
+// ----------------------------------------------------------------------------
+// Security note — printed on every install path
+// ----------------------------------------------------------------------------
+
+console.log(colors.bold('Security:'));
+console.log(colors.dim('  Codeman binds ') + colors.cyan('127.0.0.1') + colors.dim(' (this machine only) — no password needed by default.'));
+console.log(colors.dim('  To reach it from another device, do ONE of:'));
+console.log(colors.dim('    • ') + colors.cyan('tailscale serve') + colors.dim(' / ') + colors.cyan('cloudflared tunnel') + colors.dim('   (recommended), or'));
+console.log(colors.dim('    • ') + colors.cyan('codeman web --host 0.0.0.0') + colors.dim('  AND set ') + colors.cyan('CODEMAN_PASSWORD'));
+console.log(colors.dim('  A non-loopback bind without a password still starts, but warns loudly.'));
+console.log(colors.dim('  Details: docs/security-architecture.md'));
+console.log('');

scripts/run-beta.sh

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

scripts/span-codeman.sh

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

src/cli.ts

@@ -483,21 +483,29 @@ program
 program
   .command('web')
   .description('Start the web interface')
-  .option('-p, --port <port>', 'Port to listen on', '3000')
+  .option('-H, --host <host>', 'Host to bind to', process.env.CODEMAN_HOST || '127.0.0.1')
+  .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')
+  .option(
+    '--allow-unauthenticated-network',
+    'Allow non-loopback web access without CODEMAN_PASSWORD (dangerous; terminal control is exposed)'
+  )
   .action(async (options) => {
     const { startWebServer } = await import('./web/server.js');
+    const host = options.host;
     const port = parseInt(options.port, 10);
     const https = !!options.https;
     const titleHostname = options.titleHostname;
+    const allowUnauthenticatedNetwork = !!options.allowUnauthenticatedNetwork;
     const protocol = https ? 'https' : 'http';
+    const displayHost = host === '0.0.0.0' ? 'localhost' : host;
 
-    console.log(chalk.cyan(`Starting Codeman web interface on port ${port}${https ? ' (HTTPS)' : ''}...`));
+    console.log(chalk.cyan(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
 
     try {
-      const server = await startWebServer(port, https, false, titleHostname);
-      console.log(chalk.green(`\n✓ Web interface running at ${protocol}://localhost:${port}`));
+      const server = await startWebServer(port, https, false, host, titleHostname, allowUnauthenticatedNetwork);
+      console.log(chalk.green(`\n✓ Web interface running at ${protocol}://${displayHost}:${port}`));
       if (https) {
         console.log(chalk.yellow('  Note: Accept the self-signed certificate in your browser on first visit'));
       }

src/config/instance.ts

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

src/mux-interface.ts

@@ -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;
 }
 
 /**

src/push-store.ts

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

src/session-cli-builder.ts

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

src/session-lifecycle-log.ts

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

src/session.ts

@@ -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';
@@ -311,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';
 
@@ -376,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();
@@ -423,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)
@@ -847,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
@@ -1038,6 +1058,7 @@ export class Session extends EventEmitter {
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
+            effort: this._effort,
           },
           createSessionOptions: {
             sessionId: this.id,
@@ -1051,6 +1072,7 @@ export class Session extends EventEmitter {
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
+            effort: this._effort,
           },
           spawnErrLabel: 'mux attachment',
         });
@@ -1120,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,

src/state-store.ts

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

src/tmux-manager.ts

@@ -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;
 
+/** Stable cwd for tmux server/pane launch; actual session cwd is reached inside the pane. */
+const TMUX_LAUNCH_CWD = '/tmp';
+
 /** Claude Code native macOS recommendation for avoiding low nofile startup failures. */
 export const CLAUDE_CODE_NOFILE_LIMIT = 2147483646;
 
@@ -90,7 +95,7 @@ export const CLAUDE_CODE_NOFILE_LIMIT = 2147483646;
 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-]+$/;
@@ -101,8 +106,9 @@ 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. */
-const DEFAULT_CODEMAN_TMUX_SOCKET = 'codeman';
+/** 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_.-]+$/;
@@ -259,6 +265,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;
@@ -267,11 +287,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.
@@ -279,11 +301,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);
@@ -518,6 +540,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)) {
@@ -582,6 +616,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       resumeSessionId,
       envOverrides,
+      effort,
     } = options;
     const muxName = `codeman-${sessionId.slice(0, 8)}`;
 
@@ -628,6 +663,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       resumeSessionId,
+      effort,
     });
 
     const config = niceConfig || DEFAULT_NICE_CONFIG;
@@ -646,8 +682,10 @@ 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(`${this.tmux()} new-session -ds "${muxName}" -c "${workingDir}"`, {
-        cwd: workingDir,
+      // Start the tmux server from a stable local cwd so FUSE/rclone workspace
+      // blips do not poison tmux's long-lived getcwd state.
+      execSync(`${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD}`, {
+        cwd: TMUX_LAUNCH_CWD,
         timeout: EXEC_TIMEOUT_MS,
         stdio: 'ignore',
         env: cleanEnv,
@@ -673,11 +711,16 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // so secret values stay off the bash command line. Must run before respawn-pane.
       this.applyEnvOverrides(muxName, envOverrides);
 
-      // Replace the shell with the actual command (no echo in terminal)
-      execSync(`${this.tmux()} respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
-        timeout: EXEC_TIMEOUT_MS,
-        stdio: 'ignore',
-      });
+      // Replace the shell with the actual command (no echo in terminal). Keep
+      // pane launch in /tmp, then cd inside bash against the current mount table.
+      const launchCmd = `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      execSync(
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${JSON.stringify(launchCmd)}`,
+        {
+          timeout: EXEC_TIMEOUT_MS,
+          stdio: 'ignore',
+        }
+      );
 
       // Wait for tmux session to be queryable
       await new Promise((resolve) => setTimeout(resolve, TMUX_CREATION_WAIT_MS));
@@ -821,6 +864,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       openCodeConfig,
       resumeSessionId,
       envOverrides,
+      effort,
     } = options;
     const session = this.sessions.get(sessionId);
     if (!session) return null;
@@ -841,6 +885,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       resumeSessionId,
+      effort,
     });
     const config = niceConfig || DEFAULT_NICE_CONFIG;
     const cmd = wrapWithNice(baseCmd, config);
@@ -855,9 +900,13 @@ 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(`${this.tmux()} respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
-        timeout: EXEC_TIMEOUT_MS,
-      });
+      const launchCmd = `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      await execAsync(
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${JSON.stringify(launchCmd)}`,
+        {
+          timeout: EXEC_TIMEOUT_MS,
+        }
+      );
       // Wait for the respawned process to start
       await new Promise((resolve) => setTimeout(resolve, TMUX_CREATION_WAIT_MS));
       const pid = this.getPanePid(muxName);
@@ -1153,19 +1202,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
@@ -1202,13 +1255,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(':');
@@ -1233,10 +1288,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')) {
@@ -1324,11 +1381,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;
 
@@ -1337,12 +1394,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);
           }
         }
@@ -1473,7 +1530,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);
@@ -1481,7 +1538,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     try {
-      execSync(`${this.tmux()} set-option -t "${muxName}" mouse on`, {
+      await execAsync(`${this.tmux()} set-option -t "${muxName}" mouse on`, {
         encoding: 'utf-8',
         timeout: EXEC_TIMEOUT_MS,
       });
@@ -1497,7 +1554,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);
@@ -1505,7 +1562,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     try {
-      execSync(`${this.tmux()} set-option -t "${muxName}" mouse off`, {
+      await execAsync(`${this.tmux()} set-option -t "${muxName}" mouse off`, {
         encoding: 'utf-8',
         timeout: EXEC_TIMEOUT_MS,
       });
@@ -1522,9 +1579,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 {
@@ -1536,7 +1593,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);
@@ -1544,10 +1601,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     try {
-      const output = execSync(
-        `${this.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')

src/types/session.ts

@@ -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;
 }
 
 /**

src/utils/event-loop-monitor.ts

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

src/utils/index.ts

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

src/web/middleware/auth.ts

@@ -8,7 +8,7 @@
  * - CORS (localhost only)
  */
 
-import { FastifyInstance } from 'fastify';
+import type { FastifyInstance, FastifyReply } from 'fastify';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { StaleExpirationMap } from '../../utils/index.js';
 import type { AuthSessionRecord } from '../ports/auth-port.js';
@@ -69,6 +69,13 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
   const authSessions = state.authSessions;
   const authFailures = state.authFailures;
 
+  function sendAuthRateLimit(reply: FastifyReply, clientIp: string): void {
+    const remainingMs = authFailures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
+    const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
+    reply.header('Retry-After', String(retryAfterSeconds));
+    reply.code(429).send('Too Many Requests — try again later');
+  }
+
   app.addHook('onRequest', (req, reply, done) => {
     // Hook events come from local Claude Code hooks (curl from localhost) — no auth headers available.
     // Safe: validated by HookEventSchema, only triggers broadcasts.
@@ -90,13 +97,6 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
 
     const clientIp = req.ip;
 
-    // Rate limit: reject if too many failed attempts from this IP
-    const failures = authFailures.get(clientIp) ?? 0;
-    if (failures >= AUTH_FAILURE_MAX) {
-      reply.code(429).send('Too Many Requests — try again later');
-      return;
-    }
-
     // Check session cookie first (avoids re-sending credentials on every request)
     // Use get() instead of has() so refreshOnGet extends the TTL on active sessions
     const sessionToken = req.cookies[AUTH_COOKIE_NAME];
@@ -140,6 +140,13 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
       return;
     }
 
+    // Rate limit only requests that failed to authenticate on this attempt.
+    const failures = authFailures.get(clientIp) ?? 0;
+    if (failures >= AUTH_FAILURE_MAX) {
+      sendAuthRateLimit(reply, clientIp);
+      return;
+    }
+
     // Auth failed — track failure count
     authFailures.set(clientIp, failures + 1);
 
@@ -154,13 +161,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');
     }

src/web/network-auth-policy.ts

@@ -0,0 +1,21 @@
+import { isIP } from 'node:net';
+
+const EXPLICIT_TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+
+export function isExplicitlyEnabled(value: string | undefined): boolean {
+  return value !== undefined && EXPLICIT_TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+export function isLoopbackBindHost(host: string): boolean {
+  const normalized = host
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, '$1');
+  if (normalized === 'localhost' || normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
+    return true;
+  }
+  if (isIP(normalized) === 4 && normalized.startsWith('127.')) {
+    return true;
+  }
+  return normalized.startsWith('::ffff:127.');
+}

src/web/public/app.js

@@ -295,6 +295,22 @@ class CodemanApp {
     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
@@ -544,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();
@@ -776,6 +797,256 @@ class CodemanApp {
     } 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) {
@@ -929,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;
@@ -1089,7 +1366,7 @@ class CodemanApp {
     const placeholders = [];
     const masked = text.replace(fenceRe, (m) => {
       placeholders.push(m);
-      return `FENCE${placeholders.length - 1}`;
+      return `__CODEMAN_FENCE_${placeholders.length - 1}__`;
     });
 
     // Split on blank-line paragraph boundaries; wrap any paragraph containing
@@ -1099,20 +1376,21 @@ class CodemanApp {
       .map((chunk) => {
         if (/^\n{2,}$/.test(chunk)) return chunk; // keep separators
         if (!chunk.trim()) return chunk;
-        if (chunk.includes('FENCE')) return chunk;
+        if (chunk.includes('__CODEMAN_FENCE_')) return chunk;
         if (BOX_PATTERN.test(chunk)) return '\n```\n' + chunk + '\n```\n';
         return chunk;
       })
       .join('');
 
-    return processed.replace(/FENCE(\d+)/g, (_m, i) => placeholders[Number(i)]);
+    return processed.replace(/__CODEMAN_FENCE_(\d+)__/g, (_m, i) => placeholders[Number(i)]);
   }
 
   /** 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.
@@ -1168,7 +1446,7 @@ class CodemanApp {
       } 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>`;
   }
 
@@ -1948,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) {
@@ -2181,19 +2467,21 @@ class CodemanApp {
       const tallTabsEnabled = this._tallTabsEnabled ?? false;
       const showFolder = tallTabsEnabled && session.name && folderName && folderName !== name;
 
-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}" 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)}"` : ''}>
+      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++;
@@ -2524,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).

src/web/public/image-input.js

@@ -113,7 +113,14 @@ Object.assign(CodemanApp.prototype, {
     const paths = [];
     for (const file of files) {
       try {
-        const path = await this._uploadPasteImage(sessionId, file);
+        // 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');
@@ -145,4 +152,49 @@ Object.assign(CodemanApp.prototype, {
     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);
+    }
+  },
+
 });

src/web/public/index.html

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

src/web/public/keyboard-accessory.js

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

src/web/public/mobile.css

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

src/web/public/panels-ui.js

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

src/web/public/ralph-wizard.js

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

src/web/public/session-ui.js

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

src/web/public/settings-ui.js

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

src/web/public/styles.css

@@ -846,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;
@@ -905,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;
@@ -7971,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 {
@@ -7990,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 {
@@ -8078,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;
@@ -8125,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;
@@ -8294,38 +8432,43 @@ kbd {
 .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,
@@ -8403,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 {

src/web/public/terminal-ui.js

@@ -1244,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' },
@@ -1253,6 +1255,7 @@ Object.assign(CodemanApp.prototype, {
           name,
           resumeSessionId: sessionId,
           ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          ...(effort ? { effort } : {}),
         }),
       });
       const createData = await createRes.json();

src/web/route-helpers.ts

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

src/web/routes/case-routes.ts

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

src/web/routes/file-routes.ts

@@ -4,7 +4,8 @@
  */
 
 import { FastifyInstance } from 'fastify';
-import { join } from 'node:path';
+import { basename as pathBasename, join } from 'node:path';
+import { homedir } from 'node:os';
 import fs from 'node:fs/promises';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import { fileStreamManager } from '../../file-stream-manager.js';
@@ -278,7 +279,6 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
         jpeg: 'image/jpeg',
         gif: 'image/gif',
         webp: 'image/webp',
-        svg: 'image/svg+xml',
         ico: 'image/x-icon',
         bmp: 'image/bmp',
         mp4: 'video/mp4',
@@ -292,19 +292,21 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
       };
 
       const content = await fs.readFile(resolvedPath);
-      if (download === 'true') {
-        const rawBasename = filePath!.split('/').pop() || 'download';
-        // Sanitize filename for Content-Disposition header (prevent header injection)
-        const basename = rawBasename.replace(/["\\\r\n]/g, '_');
+      const rawBasename = filePath!.split('/').pop() || 'download';
+      // Sanitize filename for Content-Disposition header (prevent header injection)
+      const basename = rawBasename.replace(/["\\\r\n]/g, '_');
+      if (download === 'true' || ext === 'svg') {
         reply.raw.writeHead(200, {
-          'Content-Type': mimeTypes[ext] || 'application/octet-stream',
+          'Content-Type': ext === 'svg' ? 'application/octet-stream' : mimeTypes[ext] || 'application/octet-stream',
           'Content-Disposition': `attachment; filename="${basename}"`,
           'Content-Length': content.length,
+          'X-Content-Type-Options': 'nosniff',
         });
         reply.raw.end(content);
         return;
       }
       reply.header('Content-Type', mimeTypes[ext] || 'application/octet-stream');
+      reply.header('X-Content-Type-Options', 'nosniff');
       reply.send(content);
     } catch (err) {
       reply
@@ -380,4 +382,108 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
     const closed = fileStreamManager.closeStream(streamId);
     return { success: closed };
   });
+  // Session-scoped file download.
+  // Uses the same realpath-based workspace boundary as file preview/raw routes;
+  // the sensitive-path blocklist remains defense-in-depth, not the primary boundary.
+  const SENSITIVE_PATTERNS: RegExp[] = [
+    /^\/etc\/shadow$/,
+    /^\/etc\/gshadow$/,
+    /^\/etc\/master\.passwd$/,
+    new RegExp(`^${homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\.ssh\\/`),
+    /\/\.env$/,
+    /\/\.env\./,
+    /\/credentials(\.json|\.yml|\.yaml|\.xml)?$/i,
+    /\/\.aws\/credentials$/,
+    /\/\.gcloud\/credentials\.db$/,
+    /\/\.docker\/config\.json$/,
+  ];
+
+  function isSensitivePath(absPath: string): boolean {
+    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(absPath));
+  }
+
+  app.get('/api/download', async (req, reply) => {
+    const { path: filePath, sessionId } = req.query as { path?: string; sessionId?: string };
+
+    if (!filePath) {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing path parameter'));
+      return;
+    }
+
+    if (!sessionId) {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing sessionId parameter'));
+      return;
+    }
+
+    const session = findSessionOrFail(ctx, sessionId);
+    const validated = validateSessionFilePath(session.workingDir, filePath);
+    if (!validated) {
+      reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
+      return;
+    }
+    const { resolvedPath } = validated;
+
+    // Check sensitive path blocklist
+    if (isSensitivePath(resolvedPath)) {
+      reply.code(403).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Access to this file is blocked'));
+      return;
+    }
+
+    try {
+      const stat = await fs.stat(resolvedPath);
+
+      if (!stat.isFile()) {
+        reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path is not a file'));
+        return;
+      }
+
+      // 50MB size limit
+      const MAX_DOWNLOAD_SIZE = 50 * 1024 * 1024;
+      if (stat.size > MAX_DOWNLOAD_SIZE) {
+        reply
+          .code(400)
+          .send(
+            createErrorResponse(
+              ApiErrorCode.INVALID_INPUT,
+              `File too large (${Math.round(stat.size / 1024 / 1024)}MB > 50MB limit)`
+            )
+          );
+        return;
+      }
+
+      const ext = filePath.split('.').pop()?.toLowerCase() || '';
+      const mimeTypes: Record<string, string> = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        svg: 'image/svg+xml',
+        pdf: 'application/pdf',
+        json: 'application/json',
+        txt: 'text/plain',
+        md: 'text/markdown',
+        csv: 'text/csv',
+        xml: 'application/xml',
+        zip: 'application/zip',
+        gz: 'application/gzip',
+        tar: 'application/x-tar',
+      };
+
+      const filename = pathBasename(resolvedPath);
+      const content = await fs.readFile(resolvedPath);
+      // Bypass Fastify compression — write directly to raw response
+      reply.raw.writeHead(200, {
+        'Content-Type': mimeTypes[ext] || 'application/octet-stream',
+        'Content-Disposition': `attachment; filename="${filename}"`,
+        'Content-Length': content.length,
+      });
+      reply.raw.end(content);
+      return;
+    } catch (err) {
+      reply
+        .code(500)
+        .send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${getErrorMessage(err)}`));
+    }
+  });
 }

src/web/routes/ralph-routes.ts

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

src/web/routes/session-routes.ts

@@ -54,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
@@ -335,6 +336,7 @@ export function registerSessionRoutes(
       openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
       resumeSessionId: validatedResumeId,
       envOverrides: body.envOverrides,
+      effort: body.effort,
     });
 
     ctx.addSession(session);
@@ -1106,6 +1108,7 @@ export function registerSessionRoutes(
       mode = 'claude',
       openCodeConfig,
       envOverrides,
+      effort,
     } = parseBody(QuickStartSchema, req.body);
 
     // Check OpenCode availability if requested
@@ -1186,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
@@ -1674,6 +1678,14 @@ export function registerSessionRoutes(
     // 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}`);
     }

src/web/routes/system-routes.ts

@@ -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)
   // ═══════════════════════════════════════════════════════════════

src/web/schemas.ts

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

src/web/server.ts

@@ -36,10 +36,11 @@ 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, rmSync } 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';
@@ -94,12 +95,14 @@ import {
   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 { isExplicitlyEnabled, isLoopbackBindHost } from './network-auth-policy.js';
 import {
   registerPushRoutes,
   registerTeamRoutes,
@@ -145,7 +148,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');
 
@@ -189,6 +192,7 @@ export class WebServer extends EventEmitter {
   private sse: SseStreamManager;
   private store = getStore();
   private port: number;
+  private host: string;
   private https: boolean;
   private testMode: boolean;
   private mux: TerminalMultiplexer;
@@ -230,22 +234,34 @@ 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 readonly titleHostname: string;
+  private readonly windowTitle: string;
+  private readonly indexHtmlTemplate: string;
+  private readonly allowUnauthenticatedNetwork: boolean;
   private _pasteImageGcStop: (() => void) | null = null;
+  private _eventLoopMonitor: EventLoopMonitorHandle | null = null;
   private teamWatcherHandlers: {
     teamCreated: (config: unknown) => void;
     teamUpdated: (config: unknown) => void;
     teamRemoved: (config: unknown) => void;
     taskUpdated: (data: unknown) => void;
   } | null = null;
-  private readonly titleHostname: string;
-  private readonly windowTitle: string;
-  private readonly indexHtmlTemplate: string;
-  constructor(port: number = 3000, https: boolean = false, testMode: boolean = false, titleHostname?: string) {
+  constructor(
+    port: number = 3000,
+    https: boolean = false,
+    testMode: boolean = false,
+    host: string = '127.0.0.1',
+    titleHostname?: string,
+    allowUnauthenticatedNetwork: boolean = false
+  ) {
     super();
     this.setMaxListeners(0);
+    this.host = host;
     this.port = port;
     this.https = https;
     this.testMode = testMode;
+    this.allowUnauthenticatedNetwork =
+      allowUnauthenticatedNetwork || isExplicitlyEnabled(process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK);
     this.titleHostname = titleHostname || getHostname();
     this.windowTitle = `codeman:${this.titleHostname}`;
     this.indexHtmlTemplate = readFileSync(join(__dirname, 'public', 'index.html'), 'utf-8');
@@ -555,10 +571,30 @@ export class WebServer extends EventEmitter {
     // 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) => {
@@ -978,11 +1014,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> {
@@ -1086,7 +1211,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');
@@ -1104,13 +1229,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>;
@@ -1551,21 +1679,45 @@ export class WebServer extends EventEmitter {
     // 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' });
+    await this.app.listen({ port: this.port, host: this.host });
     const protocol = this.https ? 'https' : 'http';
-    console.log(`Codeman web interface running at ${protocol}://localhost:${this.port}`);
+    const displayHost = this.host === '0.0.0.0' ? 'localhost' : this.host;
+    console.log(`Codeman web interface running at ${protocol}://${displayHost}:${this.port}`);
 
-    // Security warning: server binds to 0.0.0.0 (all interfaces) — warn if no auth configured
-    if (!process.env.CODEMAN_PASSWORD) {
-      console.warn('\n⚠  WARNING: No CODEMAN_PASSWORD set — server is accessible without authentication.');
-      console.warn('   Anyone on your network can access and control Claude sessions.');
-      console.warn('   Set CODEMAN_PASSWORD environment variable to enable auth.\n');
+    // Codeman binds loopback (127.0.0.1) by default, which is safe out of the box.
+    // If the user opts into a non-loopback bind (e.g. --host 0.0.0.0) WITHOUT a
+    // password we no longer refuse to start — that surprised people whose setups
+    // "just worked" before. Instead we start and warn loudly, pointing at the ways
+    // to secure it. --allow-unauthenticated-network just acknowledges the risk (a
+    // terser note). See docs/security-architecture.md.
+    if (!isLoopbackBindHost(this.host) && !process.env.CODEMAN_PASSWORD) {
+      if (this.allowUnauthenticatedNetwork) {
+        console.warn(
+          `\n⚠  Codeman is reachable WITHOUT a password on ${displayHost}:${this.port} ` +
+            '(explicitly allowed). Anyone who can reach it can control your Claude sessions.\n'
+        );
+      } else {
+        console.warn(`\n⚠  WARNING: Codeman is bound to a non-loopback host (${this.host}) with NO password.`);
+        console.warn(`   Anyone who can reach ${displayHost}:${this.port} can control your Claude sessions.`);
+        console.warn('   Secure it with ONE of:');
+        console.warn('     • set CODEMAN_PASSWORD=<password>   (HTTP Basic auth), or');
+        console.warn('     • bind loopback only: --host 127.0.0.1, then front it with an');
+        console.warn('       authenticated tunnel (cloudflared) or `tailscale serve`, or');
+        console.warn('     • keep this bind and accept the risk: --allow-unauthenticated-network');
+        console.warn('   See docs/security-architecture.md for details.\n');
+      }
     }
 
     // Set API URL for child processes (MCP server, spawned sessions)
-    process.env.CODEMAN_API_URL = `${protocol}://localhost:${this.port}`;
+    const apiHost =
+      this.host === '0.0.0.0' || this.host === 'localhost' || this.host === '::1' ? '127.0.0.1' : this.host;
+    process.env.CODEMAN_API_URL = `${protocol}://${apiHost}:${this.port}`;
 
     // Start scheduled runs cleanup timer
     this.cleanup.setInterval(
@@ -1613,7 +1765,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);
@@ -1634,7 +1786,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);
@@ -1652,7 +1804,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);
@@ -1670,7 +1822,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);
@@ -1710,6 +1862,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
@@ -1722,6 +1876,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
@@ -1911,6 +2066,11 @@ export class WebServer extends EventEmitter {
       this._pasteImageGcStop = null;
     }
 
+    if (this._eventLoopMonitor) {
+      this._eventLoopMonitor.stop();
+      this._eventLoopMonitor = null;
+    }
+
     // Dispose all managed timers (intervals + resettable timeouts)
     this.cleanup.dispose();
 
@@ -2049,9 +2209,11 @@ export async function startWebServer(
   port: number = 3000,
   https: boolean = false,
   testMode: boolean = false,
-  titleHostname?: string
+  host: string = '127.0.0.1',
+  titleHostname?: string,
+  allowUnauthenticatedNetwork: boolean = false
 ): Promise<WebServer> {
-  const server = new WebServer(port, https, testMode, titleHostname);
+  const server = new WebServer(port, https, testMode, host, titleHostname, allowUnauthenticatedNetwork);
   await server.start();
   return server;
 }

test/auth-security.test.ts

@@ -3,26 +3,61 @@
  * 1. Timing-safe password comparison (timingSafeEqual)
  * 2. Hook event endpoint restricted to localhost
  * 3. Session cookie TTL refresh on access
- * 4. Startup warning when no password configured
+ * 4. Startup fails closed when network-bound without auth
  * 5. SSE client limit enforcement
  * 6. Logout endpoint invalidates session
  * 7. Settings schema rejects unknown fields
  *
- * Port: 3160 (auth tests), 3161 (no-auth tests)
+ * Port: 3160 (auth tests), 3161 (loopback no-auth tests), 3162 (network override tests)
  */
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest';
 import { WebServer } from '../src/web/server.js';
+import { TmuxManager } from '../src/tmux-manager.js';
 import { SettingsUpdateSchema } from '../src/web/schemas.js';
 
 const AUTH_PORT = 3160;
 const NOAUTH_PORT = 3161;
+const NETWORK_OVERRIDE_PORT = 3162;
+const AUTH_RATE_LIMIT_PORT = 3220;
+const NOAUTH_NETWORK_PORT = 3221;
 const TEST_USER = 'admin';
 const TEST_PASS = 'test-password-12345';
 
+vi.spyOn(TmuxManager, 'isTmuxAvailable').mockReturnValue(true);
+
 function basicAuthHeader(user: string, pass: string): string {
   return 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
 }
 
+async function startAuthServer(port: number): Promise<{ server: WebServer; baseUrl: string }> {
+  process.env.CODEMAN_PASSWORD = TEST_PASS;
+  process.env.CODEMAN_USERNAME = TEST_USER;
+  const server = new WebServer(port, false, true);
+  await server.start();
+  return { server, baseUrl: `http://localhost:${port}` };
+}
+
+async function getSessionCookie(baseUrl: string): Promise<string> {
+  const res = await fetch(`${baseUrl}/api/status`, {
+    headers: { Authorization: basicAuthHeader(TEST_USER, TEST_PASS) },
+  });
+  expect(res.status).toBe(200);
+  const setCookie = res.headers.get('set-cookie');
+  expect(setCookie).toBeTruthy();
+  const cookieMatch = setCookie!.match(/codeman_session=([^;]+)/);
+  expect(cookieMatch).toBeTruthy();
+  return `codeman_session=${cookieMatch![1]}`;
+}
+
+async function exhaustAuthFailures(baseUrl: string, prefix: string): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    const res = await fetch(`${baseUrl}/api/status`, {
+      headers: { Authorization: basicAuthHeader(TEST_USER, `${prefix}-${i}`) },
+    });
+    expect(res.status).toBe(401);
+  }
+}
+
 describe('Auth Security', () => {
   let server: WebServer;
   let baseUrl: string;
@@ -154,29 +189,63 @@ describe('Auth Security', () => {
   });
 
   describe('Rate Limiting', () => {
-    it('should block after too many failed attempts', async () => {
-      // Send 10 failed attempts
-      for (let i = 0; i < 10; i++) {
-        await fetch(`${baseUrl}/api/status`, {
-          headers: { Authorization: basicAuthHeader(TEST_USER, 'wrong-' + i) },
-        });
-      }
+    let rateServer: WebServer;
+    let rateBaseUrl: string;
 
-      // 11th attempt should be rate-limited
-      const res = await fetch(`${baseUrl}/api/status`, {
-        headers: { Authorization: basicAuthHeader(TEST_USER, 'wrong-again') },
-      });
-      expect(res.status).toBe(429);
+    beforeEach(async () => {
+      ({ server: rateServer, baseUrl: rateBaseUrl } = await startAuthServer(AUTH_RATE_LIMIT_PORT));
     });
 
-    it('should rate-limit even with correct credentials after lockout', async () => {
-      // After being rate-limited, even correct credentials should fail
-      const res = await fetch(`${baseUrl}/api/status`, {
+    afterEach(async () => {
+      await rateServer.stop();
+    });
+
+    it('should rate-limit wrong credentials after too many failed attempts', async () => {
+      await exhaustAuthFailures(rateBaseUrl, 'cod21-wrong');
+
+      const res = await fetch(`${rateBaseUrl}/api/status`, {
+        headers: { Authorization: basicAuthHeader(TEST_USER, 'wrong-again') },
+      });
+
+      expect(res.status).toBe(429);
+      expect(res.headers.get('retry-after')).toMatch(/^\d+$/);
+    });
+
+    it('should allow an existing valid session cookie during auth failure lockout', async () => {
+      const cookie = await getSessionCookie(rateBaseUrl);
+      await exhaustAuthFailures(rateBaseUrl, 'cod21-cookie');
+
+      const res = await fetch(`${rateBaseUrl}/api/status`, {
+        headers: { Cookie: cookie },
+      });
+
+      expect(res.status).toBe(200);
+    });
+
+    it('should allow correct credentials to recover from auth failure lockout', async () => {
+      await exhaustAuthFailures(rateBaseUrl, 'cod21-recover');
+
+      const res = await fetch(`${rateBaseUrl}/api/status`, {
         headers: { Authorization: basicAuthHeader(TEST_USER, TEST_PASS) },
       });
-      // Rate limit is per-IP and the previous test used the same IP
-      // This test verifies rate limiting isn't bypassed by correct creds
-      expect(res.status).toBe(429);
+
+      expect(res.status).toBe(200);
+      expect(res.headers.get('set-cookie')).toContain('codeman_session=');
+    });
+
+    it('should clear failed attempt count after correct credentials recover access', async () => {
+      await exhaustAuthFailures(rateBaseUrl, 'cod21-clear');
+
+      const recoveryRes = await fetch(`${rateBaseUrl}/api/status`, {
+        headers: { Authorization: basicAuthHeader(TEST_USER, TEST_PASS) },
+      });
+      expect(recoveryRes.status).toBe(200);
+
+      const wrongAfterRecovery = await fetch(`${rateBaseUrl}/api/status`, {
+        headers: { Authorization: basicAuthHeader(TEST_USER, 'wrong-after-recovery') },
+      });
+
+      expect(wrongAfterRecovery.status).toBe(401);
     });
   });
 
@@ -220,7 +289,7 @@ describe('Settings Schema Security', () => {
 
   it('should enforce tunnelEnabled as boolean', () => {
     const result = SettingsUpdateSchema.safeParse({
-      tunnelEnabled: 'yes',  // truthy string — should be rejected
+      tunnelEnabled: 'yes', // truthy string — should be rejected
     });
     expect(result.success).toBe(false);
   });
@@ -264,40 +333,80 @@ describe('Settings Schema Security', () => {
     expect(validResult.success).toBe(true);
 
     const invalidResult = SettingsUpdateSchema.safeParse({
-      nice: { enabled: true, niceValue: 100 },  // Out of range
+      nice: { enabled: true, niceValue: 100 }, // Out of range
     });
     expect(invalidResult.success).toBe(false);
   });
 });
 
-describe('No-Auth Server Warning', () => {
+describe('No-Auth Server Startup Policy', () => {
   let server: WebServer;
-  let consoleWarnSpy: string[] = [];
-  const originalWarn = console.warn;
 
   beforeAll(async () => {
     delete process.env.CODEMAN_PASSWORD;
     delete process.env.CODEMAN_USERNAME;
-    consoleWarnSpy = [];
-    console.warn = (...args: unknown[]) => {
-      consoleWarnSpy.push(args.map(String).join(' '));
-    };
-    server = new WebServer(NOAUTH_PORT, false, true);
+    delete process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK;
+    server = new WebServer(NOAUTH_PORT, false, true, '127.0.0.1');
     await server.start();
   });
 
   afterAll(async () => {
-    console.warn = originalWarn;
+    delete process.env.CODEMAN_PASSWORD;
+    delete process.env.CODEMAN_USERNAME;
+    delete process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK;
     await server.stop();
   });
 
-  it('should warn when no CODEMAN_PASSWORD is set', () => {
-    const hasWarning = consoleWarnSpy.some(msg => msg.includes('No CODEMAN_PASSWORD set'));
-    expect(hasWarning).toBe(true);
-  });
-
-  it('should allow requests without auth when no password configured', async () => {
+  it('allows loopback requests without auth when no password is configured', async () => {
     const res = await fetch(`http://localhost:${NOAUTH_PORT}/api/status`);
     expect(res.status).toBe(200);
   });
+
+  it('starts with a loud warning (not a hard failure) on a non-loopback bind without a password', async () => {
+    // Policy (0.9.0): loopback is the safe default, but opting into a non-loopback
+    // bind without a password no longer refuses to start — it starts and warns,
+    // pointing at how to secure it. See docs/security-architecture.md.
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const networkServer = new WebServer(NOAUTH_NETWORK_PORT, false, true, '0.0.0.0');
+
+    await expect(networkServer.start()).resolves.toBeUndefined();
+    const res = await fetch(`http://localhost:${NOAUTH_NETWORK_PORT}/api/status`);
+    expect(res.status).toBe(200);
+
+    const warned = warnSpy.mock.calls.flat().join('\n');
+    expect(warned).toMatch(/non-loopback host|NO password/i);
+    expect(warned).toMatch(/CODEMAN_PASSWORD/);
+
+    warnSpy.mockRestore();
+    await networkServer.stop();
+  });
+
+  it('allows non-loopback startup when CODEMAN_PASSWORD is configured', async () => {
+    process.env.CODEMAN_PASSWORD = TEST_PASS;
+    const networkServer = new WebServer(0, false, true, '0.0.0.0');
+
+    await networkServer.start();
+    await networkServer.stop();
+
+    delete process.env.CODEMAN_PASSWORD;
+  });
+
+  it('allows non-loopback startup with the explicit unauthenticated-network override', async () => {
+    const networkServer = new WebServer(NETWORK_OVERRIDE_PORT, false, true, '0.0.0.0', undefined, true);
+
+    await networkServer.start();
+    const res = await fetch(`http://localhost:${NETWORK_OVERRIDE_PORT}/api/status`);
+    expect(res.status).toBe(200);
+    await networkServer.stop();
+  });
+
+  it('allows non-loopback startup with the explicit unauthenticated-network env override', async () => {
+    process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK = 'true';
+    const networkServer = new WebServer(0, false, true, '0.0.0.0');
+
+    await networkServer.start();
+    await networkServer.stop();
+
+    delete process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK;
+  });
 });

test/cli-commands.test.ts

@@ -5,6 +5,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { program } from '../src/cli.js';
 
 describe('CLI Command Parsing', () => {
   describe('Command Structure', () => {
@@ -72,11 +73,11 @@ describe('CLI Command Parsing', () => {
     ];
 
     const findCommand = (name: string): Command | undefined => {
-      return commands.find(c => c.name === name || c.aliases.includes(name));
+      return commands.find((c) => c.name === name || c.aliases.includes(name));
     };
 
     const findSubcommand = (parent: Command, name: string): Command | undefined => {
-      return parent.subcommands?.find(c => c.name === name || c.aliases.includes(name));
+      return parent.subcommands?.find((c) => c.name === name || c.aliases.includes(name));
     };
 
     it('should find commands by name', () => {
@@ -103,7 +104,7 @@ describe('CLI Command Parsing', () => {
     });
 
     it('should have descriptions for all commands', () => {
-      commands.forEach(cmd => {
+      commands.forEach((cmd) => {
         expect(cmd.description).toBeTruthy();
       });
     });
@@ -267,13 +268,13 @@ describe('CLI Command Parsing', () => {
     });
 
     it('should have defaults for web flags', () => {
-      webFlags.forEach(flag => {
+      webFlags.forEach((flag) => {
         expect(flag.default).toBeDefined();
       });
     });
 
     it('should have defaults for tui flags', () => {
-      tuiFlags.forEach(flag => {
+      tuiFlags.forEach((flag) => {
         expect(flag.default).toBeDefined();
       });
     });
@@ -322,7 +323,7 @@ describe('CLI Command Parsing', () => {
       help += `${description}\n`;
       if (options.length > 0) {
         help += '\nOptions:\n';
-        options.forEach(opt => {
+        options.forEach((opt) => {
           help += `  ${opt}\n`;
         });
       }
@@ -345,6 +346,15 @@ describe('CLI Command Parsing', () => {
       expect(help).toContain('--host');
     });
 
+    it('documents the unauthenticated network override in real web command help', () => {
+      const webCommand = program.commands.find((command) => command.name() === 'web');
+      expect(webCommand).toBeDefined();
+
+      const help = webCommand!.helpInformation();
+      expect(help).toContain('--allow-unauthenticated-network');
+      expect(help).toMatch(/without\s+CODEMAN_PASSWORD/);
+    });
+
     it('should format properly', () => {
       const help = generateHelp('test', 'Test command', ['--flag']);
       const lines = help.split('\n');
@@ -474,22 +484,27 @@ describe('CLI Output Formatting', () => {
     }
 
     const formatRow = (values: string[], columns: Column[]): string => {
-      return values.map((val, i) => {
-        const width = columns[i]?.width || 10;
-        return val.padEnd(width).substring(0, width);
-      }).join(' ');
+      return values
+        .map((val, i) => {
+          const width = columns[i]?.width || 10;
+          return val.padEnd(width).substring(0, width);
+        })
+        .join(' ');
     };
 
     const formatTable = (headers: string[], rows: string[][], widths: number[]): string => {
       const columns = headers.map((h, i) => ({ header: h, width: widths[i] }));
       const headerRow = formatRow(headers, columns);
-      const separator = columns.map(c => '-'.repeat(c.width)).join(' ');
-      const dataRows = rows.map(row => formatRow(row, columns));
+      const separator = columns.map((c) => '-'.repeat(c.width)).join(' ');
+      const dataRows = rows.map((row) => formatRow(row, columns));
       return [headerRow, separator, ...dataRows].join('\n');
     };
 
     it('should format single row', () => {
-      const columns = [{ header: 'ID', width: 10 }, { header: 'Status', width: 8 }];
+      const columns = [
+        { header: 'ID', width: 10 },
+        { header: 'Status', width: 8 },
+      ];
       const row = formatRow(['123', 'active'], columns);
       expect(row).toBe('123        active  ');
     });
@@ -503,7 +518,10 @@ describe('CLI Output Formatting', () => {
     it('should format complete table', () => {
       const table = formatTable(
         ['ID', 'Status'],
-        [['1', 'active'], ['2', 'idle']],
+        [
+          ['1', 'active'],
+          ['2', 'idle'],
+        ],
         [5, 8]
       );
       expect(table).toContain('ID');
@@ -587,7 +605,7 @@ describe('CLI Output Formatting', () => {
     });
 
     it('should format normal costs with 2 decimals', () => {
-      expect(formatCost(1.50)).toBe('$1.50');
+      expect(formatCost(1.5)).toBe('$1.50');
       expect(formatCost(0.05)).toBe('$0.05');
     });
 
@@ -633,7 +651,7 @@ describe('CLI Output Formatting', () => {
 
   describe('List Formatting', () => {
     const formatList = (items: string[], bullet: string = '-'): string => {
-      return items.map(item => `${bullet} ${item}`).join('\n');
+      return items.map((item) => `${bullet} ${item}`).join('\n');
     };
 
     const formatNumberedList = (items: string[]): string => {

test/config/instance.test.ts

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

test/dependency-security.test.ts

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const root = resolve(import.meta.dirname, '..');
+
+type PackageLockPackage = {
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+type PackageLock = {
+  packages: Record<string, PackageLockPackage>;
+};
+
+function readJson<T>(relativePath: string): T {
+  return JSON.parse(readFileSync(resolve(root, relativePath), 'utf8')) as T;
+}
+
+function compareVersions(actual: string, expected: string): number {
+  const actualParts = actual.split('.').map((part) => Number(part.replace(/\D.*/, '')) || 0);
+  const expectedParts = expected.split('.').map((part) => Number(part.replace(/\D.*/, '')) || 0);
+  for (let i = 0; i < Math.max(actualParts.length, expectedParts.length); i++) {
+    const left = actualParts[i] ?? 0;
+    const right = expectedParts[i] ?? 0;
+    if (left > right) return 1;
+    if (left < right) return -1;
+  }
+  return 0;
+}
+
+function packageNameFromLockPath(lockPath: string): string | null {
+  const parts = lockPath.split('node_modules/');
+  if (parts.length < 2) return null;
+  return parts[parts.length - 1] ?? null;
+}
+
+function lockedVersions(lock: PackageLock, packageName: string): string[] {
+  const versions = new Set<string>();
+  for (const [lockPath, pkg] of Object.entries(lock.packages)) {
+    if (packageNameFromLockPath(lockPath) === packageName && pkg.version) {
+      versions.add(pkg.version);
+    }
+  }
+  return [...versions].sort();
+}
+
+function expectEveryLockedVersionAtLeast(lock: PackageLock, packageName: string, minimum: string): void {
+  const versions = lockedVersions(lock, packageName);
+  expect(versions, `${packageName} should be present in package-lock.json`).not.toHaveLength(0);
+  for (const version of versions) {
+    expect(
+      compareVersions(version, minimum),
+      `${packageName}@${version} should be >= ${minimum}`
+    ).toBeGreaterThanOrEqual(0);
+  }
+}
+
+function expectNoVulnerableVite(lock: PackageLock): void {
+  const versions = lockedVersions(lock, 'vite');
+  expect(versions, 'vite should be present in package-lock.json').not.toHaveLength(0);
+  for (const version of versions) {
+    const major = Number(version.split('.')[0]);
+    if (major === 6) {
+      expect(compareVersions(version, '6.4.2'), `vite@${version} should be >= 6.4.2`).toBeGreaterThanOrEqual(0);
+    } else if (major === 7) {
+      expect(compareVersions(version, '7.3.2'), `vite@${version} should be >= 7.3.2`).toBeGreaterThanOrEqual(0);
+    } else {
+      expect(major, `vite@${version} should be on a supported patched major`).toBeGreaterThanOrEqual(8);
+    }
+  }
+}
+
+function expectNoVulnerablePicomatch(lock: PackageLock): void {
+  const versions = lockedVersions(lock, 'picomatch');
+  expect(versions, 'picomatch should be present in package-lock.json').not.toHaveLength(0);
+  for (const version of versions) {
+    const major = Number(version.split('.')[0]);
+    if (major === 2) {
+      expect(compareVersions(version, '2.3.2'), `picomatch@${version} should be >= 2.3.2`).toBeGreaterThanOrEqual(0);
+    } else if (major === 4) {
+      expect(compareVersions(version, '4.0.4'), `picomatch@${version} should be >= 4.0.4`).toBeGreaterThanOrEqual(0);
+    }
+  }
+}
+
+function expectNoVulnerableBraceExpansion(lock: PackageLock): void {
+  const versions = lockedVersions(lock, 'brace-expansion');
+  expect(versions, 'brace-expansion should be present in package-lock.json').not.toHaveLength(0);
+  for (const version of versions) {
+    const major = Number(version.split('.')[0]);
+    if (major === 1) {
+      expect(
+        compareVersions(version, '1.1.13'),
+        `brace-expansion@${version} should be >= 1.1.13`
+      ).toBeGreaterThanOrEqual(0);
+    } else if (major === 4) {
+      expect(
+        compareVersions(version, '5.0.5'),
+        `brace-expansion@${version} should not remain on vulnerable 4.x`
+      ).toBeGreaterThanOrEqual(0);
+    } else if (major === 5) {
+      expect(compareVersions(version, '5.0.6'), `brace-expansion@${version} should be >= 5.0.6`).toBeGreaterThanOrEqual(
+        0
+      );
+    }
+  }
+}
+
+describe('dependency security policy', () => {
+  it('keeps direct security-sensitive dependency ranges on patched versions', () => {
+    const rootPackage = readJson<PackageLockPackage>('package.json');
+    const xtermPackage = readJson<PackageLockPackage>('packages/xterm-zerolag-input/package.json');
+
+    expect(rootPackage.dependencies?.['@fastify/static']).toBe('^9.1.3');
+    expect(rootPackage.dependencies?.fastify).toBe('^5.8.5');
+    expect(rootPackage.dependencies?.uuid).toBe('^14.0.0');
+    expect(rootPackage.devDependencies?.['@remotion/cli']).toBe('4.0.473');
+    expect(rootPackage.devDependencies?.remotion).toBe('4.0.473');
+    expect(rootPackage.devDependencies?.['@remotion/transitions']).toBe('4.0.473');
+    expect(rootPackage.devDependencies?.vitest).toBe('^4.1.8');
+    expect(rootPackage.devDependencies?.['@vitest/coverage-v8']).toBe('^4.1.8');
+    expect(xtermPackage.devDependencies?.vitest).toBe('^4.1.8');
+  });
+
+  it('keeps critical and high audit findings resolved in the lockfile', () => {
+    const lock = readJson<PackageLock>('package-lock.json');
+
+    expectEveryLockedVersionAtLeast(lock, 'vitest', '4.1.0');
+    expectEveryLockedVersionAtLeast(lock, '@vitest/coverage-v8', '4.1.0');
+    expectEveryLockedVersionAtLeast(lock, 'fastify', '5.8.5');
+    expectEveryLockedVersionAtLeast(lock, '@fastify/static', '9.1.3');
+    expectEveryLockedVersionAtLeast(lock, 'ip-address', '10.2.0');
+    expectEveryLockedVersionAtLeast(lock, 'uuid', '14.0.0');
+    expectEveryLockedVersionAtLeast(lock, 'ws', '8.20.1');
+    expectEveryLockedVersionAtLeast(lock, 'fast-uri', '3.1.2');
+    expectEveryLockedVersionAtLeast(lock, 'basic-ftp', '5.3.1');
+    expectEveryLockedVersionAtLeast(lock, 'flatted', '3.4.2');
+    expectNoVulnerableBraceExpansion(lock);
+    expectNoVulnerableVite(lock);
+    expectNoVulnerablePicomatch(lock);
+  });
+
+  it('keeps standalone workspace lockfiles on patched test tooling', () => {
+    const lock = readJson<PackageLock>('packages/xterm-zerolag-input/package-lock.json');
+
+    expect(lock.packages['']?.devDependencies?.vitest).toBe('^4.1.8');
+    expectEveryLockedVersionAtLeast(lock, 'vitest', '4.1.0');
+    expectEveryLockedVersionAtLeast(lock, 'ws', '8.20.1');
+    expectNoVulnerableVite(lock);
+    expectNoVulnerablePicomatch(lock);
+  });
+});

test/effort-injection.test.ts

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

test/frontend-public-tooling.test.ts

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(import.meta.dirname, '..');
+
+describe('frontend public asset tooling', () => {
+  it('exposes a public asset check script', () => {
+    const pkg = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8')) as {
+      scripts?: Record<string, string>;
+    };
+
+    expect(pkg.scripts?.['check:public-assets']).toContain('scripts/check-public-assets.mjs');
+  });
+
+  it('keeps app.js free of literal NUL bytes', () => {
+    const appJs = readFileSync(resolve(repoRoot, 'src/web/public/app.js'));
+
+    expect(appJs.includes(0)).toBe(false);
+  });
+
+  it('runs the public asset check script', () => {
+    expect(() => {
+      execFileSync('npm', ['run', 'check:public-assets', '--silent'], {
+        cwd: repoRoot,
+        stdio: 'pipe',
+      });
+    }).not.toThrow();
+  });
+});

test/mobile/keyboard.test.ts

@@ -5,16 +5,22 @@ import { PORTS, KEYBOARD, SELECTORS, BODY_CLASSES, WAIT } from './helpers/consta
 import { createTestServer, stopTestServer } from './helpers/server.js';
 import { createDevicePage, getBrowser, closeAllBrowsers } from './helpers/browser.js';
 import {
-  showKeyboard, hideKeyboard,
-  showKeyboardViaCDP, hideKeyboardViaCDP,
-  showKeyboardViaMock, hideKeyboardViaMock,
-  showKeyboardViaDOM, hideKeyboardViaDOM,
+  showKeyboard,
+  hideKeyboard,
+  showKeyboardViaCDP,
+  hideKeyboardViaCDP,
+  showKeyboardViaMock,
+  hideKeyboardViaMock,
+  showKeyboardViaDOM,
+  hideKeyboardViaDOM,
   setupViewportMock,
 } from './helpers/keyboard-sim.js';
 import { getCDP, setVisualViewportHeight } from './helpers/cdp.js';
 import {
-  assertHasClass, assertNotHasClass,
-  assertVisible, assertHidden,
+  assertHasClass,
+  assertNotHasClass,
+  assertVisible,
+  assertHidden,
   getCSSProperty,
 } from './helpers/assertions.js';
 import { REPRESENTATIVE_DEVICES } from './devices.js';
@@ -167,9 +173,7 @@ describe('Virtual Keyboard', () => {
         const success = await showKeyboardViaMock(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
         expect(success).toBe(true);
 
-        const hasClass = await page.evaluate(() =>
-          document.body.classList.contains('keyboard-visible'),
-        );
+        const hasClass = await page.evaluate(() => document.body.classList.contains('keyboard-visible'));
         expect(hasClass).toBe(true);
       } finally {
         await context.close();
@@ -280,12 +284,13 @@ describe('Virtual Keyboard', () => {
       expect(mainPadding).toBe('');
     });
 
-    it('accessory bar has 7 action buttons', async () => {
-      const count = await page.evaluate(() => {
-        const buttons = document.querySelectorAll('.keyboard-accessory-bar [data-action]');
-        return buttons.length;
+    it('accessory bar has the simple-mode action buttons', async () => {
+      const actions = await page.evaluate(() => {
+        return Array.from(document.querySelectorAll('.keyboard-accessory-bar [data-action]')).map(
+          (button) => (button as HTMLElement).dataset.action
+        );
       });
-      expect(count).toBe(7);
+      expect(actions).toEqual(['scroll-up', 'scroll-down', 'init', 'clear', 'paste', 'dismiss']);
     });
 
     it('double-tap confirm on /clear button', async () => {
@@ -321,27 +326,6 @@ describe('Virtual Keyboard', () => {
       expect(text).toBe('Tap again');
     });
 
-    it('double-tap confirm on /compact button', async () => {
-      await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
-      await page.waitForTimeout(WAIT.KEYBOARD_ANIMATION);
-
-      await page.evaluate(`
-        if (typeof app !== 'undefined') app.activeSessionId = 'test-session';
-      `);
-
-      await page.evaluate(() => {
-        const btn = document.querySelector('[data-action="compact"]') as HTMLElement;
-        btn?.click();
-      });
-      await page.waitForTimeout(100);
-
-      const confirming = await page.evaluate(() => {
-        const btn = document.querySelector('[data-action="compact"]');
-        return btn?.classList.contains('confirming') ?? false;
-      });
-      expect(confirming).toBe(true);
-    });
-
     it('double-tap expires after 2s', async () => {
       await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
       await page.waitForTimeout(WAIT.KEYBOARD_ANIMATION);

test/network-auth-policy.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { isExplicitlyEnabled, isLoopbackBindHost } from '../src/web/network-auth-policy.js';
+
+describe('network auth policy', () => {
+  it.each(['localhost', '127.0.0.1', '127.42.0.9', '::1', '[::1]', '0:0:0:0:0:0:0:1', '::ffff:127.0.0.1'])(
+    'treats %s as loopback',
+    (host) => {
+      expect(isLoopbackBindHost(host)).toBe(true);
+    }
+  );
+
+  it.each(['0.0.0.0', '192.168.1.10', '10.0.0.1', 'example.com', '::', '[::]', '::ffff:192.168.1.10'])(
+    'treats %s as non-loopback',
+    (host) => {
+      expect(isLoopbackBindHost(host)).toBe(false);
+    }
+  );
+
+  it.each(['1', 'true', 'TRUE', ' yes ', 'on'])('treats %s as an explicit opt-in', (value) => {
+    expect(isExplicitlyEnabled(value)).toBe(true);
+  });
+
+  it.each([undefined, '', '0', 'false', 'no', 'off', 'enabled'])('does not treat %s as an explicit opt-in', (value) => {
+    expect(isExplicitlyEnabled(value)).toBe(false);
+  });
+});

test/operation-lightspeed.test.ts

@@ -1256,7 +1256,7 @@ describe('Operation Lightspeed', () => {
       await Promise.all(ids.map((id) => deleteSession(baseUrl, id)));
     });
 
-    it('should correctly filter SSE under concurrent session lifecycle', async () => {
+    it('should broadcast lifecycle events while filtering concurrent session terminal streams', async () => {
       // Create 2 sessions
       const target = await createSession(baseUrl);
       const other = await createSession(baseUrl);
@@ -1309,15 +1309,21 @@ describe('Operation Lightspeed', () => {
 
       const events = parseSSEEvents(receivedData);
 
-      // Should see target's rename but not other's events
-      const targetUpdated = events.find((e) => e.event === 'session:updated' && (e.data as any).id === target);
+      // session:updated is a lifecycle event broadcast to all clients; the
+      // subscription filter applies only to high-volume terminal streams.
+      const updatedEvents = events.filter((e) => e.event === 'session:updated');
+      const targetUpdated = updatedEvents.find((e) => (e.data as any).id === target);
       expect(targetUpdated).toBeDefined();
 
-      // Should NOT see other's events
-      const otherEvents = events.filter(
-        (e) => ((e.data as any)?.id === other || (e.data as any)?.sessionId === other) && e.event !== 'init'
+      const otherLifecycleEvents = events.filter(
+        (e) => e.event !== 'init' && e.event !== 'session:terminal' && (e.data as any)?.id === other
       );
-      expect(otherEvents.length).toBe(0);
+      expect(otherLifecycleEvents.length).toBeGreaterThan(0);
+
+      const otherTerminalEvents = events.filter(
+        (e) => e.event === 'session:terminal' && (e.data as any)?.sessionId === other
+      );
+      expect(otherTerminalEvents.length).toBe(0);
 
       await deleteSession(baseUrl, target);
     });

test/perf-browser.test.ts

@@ -19,24 +19,24 @@ const BASE_URL = `http://localhost:${PORT}`;
 
 // Thresholds (ms)
 const THRESHOLDS = {
-  PAGE_LOAD: 3000,           // Full page load including JS init
-  DOMContentLoaded: 1500,    // HTML parsed
-  SSE_CONNECT: 2000,         // SSE EventSource open
-  TAB_CREATE_API: 200,       // POST /api/sessions response
-  TAB_RENDER: 300,           // Tab element appears in DOM
-  TAB_SWITCH: 400,           // Tab click to active class applied (includes tmux session creation)
-  TERMINAL_INIT: 500,        // xterm.js instance created for tab
-  INPUT_ROUNDTRIP: 500,      // Keystroke sent via API → acknowledged
-  SETTINGS_OPEN: 300,        // Settings modal visible
-  SETTINGS_CLOSE: 200,       // Settings modal hidden
+  PAGE_LOAD: 3000, // Full page load including JS init
+  DOMContentLoaded: 1500, // Browser nav timing through deferred script execution
+  SSE_CONNECT: 2000, // SSE EventSource open
+  TAB_CREATE_API: 200, // POST /api/sessions response
+  TAB_RENDER: 300, // Tab element appears in DOM
+  TAB_SWITCH: 400, // Tab click to active class applied (includes tmux session creation)
+  TERMINAL_INIT: 500, // xterm.js instance created for tab
+  INPUT_ROUNDTRIP: 500, // Keystroke sent via API → acknowledged
+  SETTINGS_OPEN: 300, // Settings modal visible
+  SETTINGS_CLOSE: 200, // Settings modal hidden
   SESSION_OPTIONS_OPEN: 300, // Session options modal visible
-  SESSION_OPTIONS_TAB: 200,  // Modal tab switch
+  SESSION_OPTIONS_TAB: 200, // Modal tab switch
   SUBAGENT_WINDOW_OPEN: 400, // Subagent window rendered
   SUBAGENT_WINDOW_CLOSE: 200,
-  BULK_TAB_CREATE: 3000,     // Create 10 sessions
-  BULK_TAB_SWITCH_AVG: 300,  // Average per-tab switch across 10 tabs (includes buffer loads)
-  MEMORY_HEAP_MB: 200,       // Max JS heap after heavy load
-  BUFFER_LOAD_16KB: 500,     // Load a 16KB terminal buffer
+  BULK_TAB_CREATE: 3000, // Create 10 sessions
+  BULK_TAB_SWITCH_AVG: 300, // Average per-tab switch across 10 tabs (includes buffer loads)
+  MEMORY_HEAP_MB: 200, // Max JS heap after heavy load
+  BUFFER_LOAD_16KB: 500, // Load a 16KB terminal buffer
 };
 
 let server: WebServer;
@@ -88,6 +88,25 @@ async function measure(fn: () => Promise<void>): Promise<number> {
   return performance.now() - start;
 }
 
+type BrowserNavigationTiming = {
+  domInteractive: number;
+  domContentLoadedEventEnd: number;
+  loadEventEnd: number;
+};
+
+/** Get the browser's own navigation timing, excluding Playwright harness overhead. */
+async function getBrowserNavigationTiming(page: Page): Promise<BrowserNavigationTiming> {
+  return page.evaluate(() => {
+    const entry = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined;
+    if (!entry) throw new Error('Navigation timing entry not available');
+    return {
+      domInteractive: entry.domInteractive,
+      domContentLoadedEventEnd: entry.domContentLoadedEventEnd,
+      loadEventEnd: entry.loadEventEnd,
+    };
+  });
+}
+
 /** Get JS heap size in MB (Chromium only) */
 async function getHeapMB(page: Page): Promise<number> {
   const metrics = await page.evaluate(() => {
@@ -123,12 +142,15 @@ describe('Page load performance', () => {
   it('DOMContentLoaded fires within threshold', async () => {
     ({ context, page } = await freshPage());
 
-    const timing = await measure(async () => {
+    const wallTiming = await measure(async () => {
       await page.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
     });
+    const navigationTiming = await getBrowserNavigationTiming(page);
 
-    console.log(`[page load] DOMContentLoaded: ${timing.toFixed(0)}ms`);
-    expect(timing).toBeLessThan(THRESHOLDS.DOMContentLoaded);
+    console.log(
+      `[page load] DOMContentLoaded: ${navigationTiming.domContentLoadedEventEnd.toFixed(0)}ms (wall ${wallTiming.toFixed(0)}ms)`
+    );
+    expect(navigationTiming.domContentLoadedEventEnd).toBeLessThan(THRESHOLDS.DOMContentLoaded);
   });
 
   it('full app initialization completes within threshold', async () => {
@@ -157,7 +179,7 @@ describe('Page load performance', () => {
           const dot = document.getElementById('connectionDot');
           return dot?.classList.contains('connected') || indicator.style.display === 'none';
         },
-        { timeout: 5000 },
+        { timeout: 5000 }
       );
     });
 
@@ -225,7 +247,7 @@ describe('Session tab creation', () => {
       await page.waitForFunction(
         (expected: number) => document.querySelectorAll('.session-tab').length > expected,
         tabCountBefore,
-        { timeout: 3000 },
+        { timeout: 3000 }
       );
     });
 
@@ -250,7 +272,7 @@ describe('Session tab creation', () => {
           if (!container) return false;
           return container.querySelector('.xterm-screen') !== null;
         },
-        { timeout: 3000 },
+        { timeout: 3000 }
       );
     });
 
@@ -277,7 +299,7 @@ describe('Tab switching performance', () => {
     await page.waitForFunction(
       (count: number) => document.querySelectorAll('.session-tab').length >= count,
       sessionIds.length,
-      { timeout: 5000 },
+      { timeout: 5000 }
     );
     // Select first tab
     await page.locator(`.session-tab[data-id="${sessionIds[0]}"]`).click();
@@ -303,7 +325,7 @@ describe('Tab switching performance', () => {
         await page.waitForFunction(
           (id: string) => document.querySelector(`.session-tab[data-id="${id}"]`)?.classList.contains('active'),
           targetId,
-          { timeout: 2000 },
+          { timeout: 2000 }
         );
       });
       timings.push(timing);
@@ -325,7 +347,7 @@ describe('Tab switching performance', () => {
         await page.waitForFunction(
           (id: string) => document.querySelector(`.session-tab[data-id="${id}"]`)?.classList.contains('active'),
           targetId,
-          { timeout: 2000 },
+          { timeout: 2000 }
         );
       });
       timings.push(timing);
@@ -362,11 +384,9 @@ describe('Bulk tab operations', () => {
         sessionIds.push(id);
       }
       // Wait for all tabs to render
-      await page.waitForFunction(
-        (count: number) => document.querySelectorAll('.session-tab').length >= count,
-        10,
-        { timeout: 5000 },
-      );
+      await page.waitForFunction((count: number) => document.querySelectorAll('.session-tab').length >= count, 10, {
+        timeout: 5000,
+      });
     });
 
     console.log(`[bulk create] 10 sessions: ${timing.toFixed(0)}ms`);
@@ -383,7 +403,7 @@ describe('Bulk tab operations', () => {
         await page.waitForFunction(
           (id: string) => document.querySelector(`.session-tab[data-id="${id}"]`)?.classList.contains('active'),
           targetId,
-          { timeout: 2000 },
+          { timeout: 2000 }
         );
       });
       timings.push(timing);
@@ -497,7 +517,10 @@ describe('Settings modal performance', () => {
 
   it('closes within threshold', async () => {
     // Make sure it's open
-    const isOpen = await page.locator('#appSettingsModal.active').isVisible().catch(() => false);
+    const isOpen = await page
+      .locator('#appSettingsModal.active')
+      .isVisible()
+      .catch(() => false);
     if (!isOpen) {
       await page.locator('.btn-settings').click();
       await page.waitForSelector('#appSettingsModal.active', { timeout: 2000 });
@@ -506,10 +529,9 @@ describe('Settings modal performance', () => {
     const timing = await measure(async () => {
       // Press Escape to close
       await page.keyboard.press('Escape');
-      await page.waitForFunction(
-        () => !document.querySelector('#appSettingsModal')?.classList.contains('active'),
-        { timeout: 2000 },
-      );
+      await page.waitForFunction(() => !document.querySelector('#appSettingsModal')?.classList.contains('active'), {
+        timeout: 2000,
+      });
     });
 
     console.log(`[settings] close: ${timing.toFixed(0)}ms`);
@@ -528,10 +550,9 @@ describe('Settings modal performance', () => {
       // Close
       const closeTime = await measure(async () => {
         await page.keyboard.press('Escape');
-        await page.waitForFunction(
-          () => !document.querySelector('#appSettingsModal')?.classList.contains('active'),
-          { timeout: 2000 },
-        );
+        await page.waitForFunction(() => !document.querySelector('#appSettingsModal')?.classList.contains('active'), {
+          timeout: 2000,
+        });
       });
       timings.push(openTime + closeTime);
     }
@@ -575,7 +596,10 @@ describe('Session options modal performance', () => {
 
   it('tab switching within modal is instant', async () => {
     // Ensure modal is open
-    const isOpen = await page.locator('#sessionOptionsModal.active').isVisible().catch(() => false);
+    const isOpen = await page
+      .locator('#sessionOptionsModal.active')
+      .isVisible()
+      .catch(() => false);
     if (!isOpen) {
       await page.locator(`.session-tab[data-id="${sessionId}"] .tab-gear`).click();
       await page.waitForSelector('#sessionOptionsModal.active', { timeout: 2000 });
@@ -590,7 +614,7 @@ describe('Session options modal performance', () => {
         await page.waitForFunction(
           (t: string) => document.querySelector(`[data-tab="${t}"]`)?.classList.contains('active'),
           tab,
-          { timeout: 1000 },
+          { timeout: 1000 }
         );
       });
       timings.push(timing);
@@ -634,27 +658,32 @@ describe('Subagent window simulation', () => {
     }, sessionId);
 
     const timing = await measure(async () => {
-      await page.evaluate(({ agentId, cSessionId }: { agentId: string; cSessionId: string }) => {
-        const app = (window as unknown as {
-          app: {
-            subagents: Map<string, Record<string, unknown>>;
-            openSubagentWindow: (id: string) => void;
-          }
-        }).app;
-        // Inject fake agent data
-        app.subagents.set(agentId, {
-          agentId,
-          sessionId: cSessionId,
-          status: 'active',
-          description: 'Performance test agent',
-          startedAt: Date.now(),
-          lastActivityAt: Date.now(),
-          toolCallCount: 0,
-          entryCount: 0,
-          fileSize: 0,
-        });
-        app.openSubagentWindow(agentId);
-      }, { agentId: 'perf-agent-1', cSessionId: claudeSessionId });
+      await page.evaluate(
+        ({ agentId, cSessionId }: { agentId: string; cSessionId: string }) => {
+          const app = (
+            window as unknown as {
+              app: {
+                subagents: Map<string, Record<string, unknown>>;
+                openSubagentWindow: (id: string) => void;
+              };
+            }
+          ).app;
+          // Inject fake agent data
+          app.subagents.set(agentId, {
+            agentId,
+            sessionId: cSessionId,
+            status: 'active',
+            description: 'Performance test agent',
+            startedAt: Date.now(),
+            lastActivityAt: Date.now(),
+            toolCallCount: 0,
+            entryCount: 0,
+            fileSize: 0,
+          });
+          app.openSubagentWindow(agentId);
+        },
+        { agentId: 'perf-agent-1', cSessionId: claudeSessionId }
+      );
       await page.waitForSelector('.subagent-window', { timeout: 3000 });
     });
 
@@ -679,7 +708,7 @@ describe('Subagent window simulation', () => {
           const el = document.getElementById('subagent-window-perf-agent-1');
           return el && el.style.display === 'none';
         },
-        { timeout: 2000 },
+        { timeout: 2000 }
       );
     });
 
@@ -698,33 +727,35 @@ describe('Subagent window simulation', () => {
 
     const timing = await measure(async () => {
       for (let i = 0; i < 5; i++) {
-        await page.evaluate(({ idx, cSessionId }: { idx: number; cSessionId: string }) => {
-          const agentId = `perf-multi-agent-${idx}`;
-          const app = (window as unknown as {
-            app: {
-              subagents: Map<string, Record<string, unknown>>;
-              openSubagentWindow: (id: string) => void;
-            }
-          }).app;
-          app.subagents.set(agentId, {
-            agentId,
-            sessionId: cSessionId,
-            status: 'active',
-            description: `Perf agent ${idx}`,
-            startedAt: Date.now(),
-            lastActivityAt: Date.now(),
-            toolCallCount: 0,
-            entryCount: 0,
-            fileSize: 0,
-          });
-          app.openSubagentWindow(agentId);
-        }, { idx: i, cSessionId: claudeSessionId });
+        await page.evaluate(
+          ({ idx, cSessionId }: { idx: number; cSessionId: string }) => {
+            const agentId = `perf-multi-agent-${idx}`;
+            const app = (
+              window as unknown as {
+                app: {
+                  subagents: Map<string, Record<string, unknown>>;
+                  openSubagentWindow: (id: string) => void;
+                };
+              }
+            ).app;
+            app.subagents.set(agentId, {
+              agentId,
+              sessionId: cSessionId,
+              status: 'active',
+              description: `Perf agent ${idx}`,
+              startedAt: Date.now(),
+              lastActivityAt: Date.now(),
+              toolCallCount: 0,
+              entryCount: 0,
+              fileSize: 0,
+            });
+            app.openSubagentWindow(agentId);
+          },
+          { idx: i, cSessionId: claudeSessionId }
+        );
       }
       // Wait for all 5
-      await page.waitForFunction(
-        () => document.querySelectorAll('.subagent-window').length >= 5,
-        { timeout: 5000 },
-      );
+      await page.waitForFunction(() => document.querySelectorAll('.subagent-window').length >= 5, { timeout: 5000 });
     });
 
     const windowCount = await page.locator('.subagent-window').count();
@@ -772,7 +803,7 @@ describe('SSE event throughput', () => {
     await page.waitForFunction(
       (count: number) => document.querySelectorAll('.session-tab').length >= count,
       sessionIds.length,
-      { timeout: 5000 },
+      { timeout: 5000 }
     );
     const elapsed = performance.now() - start;
 
@@ -797,7 +828,7 @@ describe('SSE event throughput', () => {
     await page.waitForFunction(
       (count: number) => document.querySelectorAll('.session-tab').length >= count,
       sessionIds.length,
-      { timeout: 5000 },
+      { timeout: 5000 }
     );
 
     const start = performance.now();
@@ -813,7 +844,7 @@ describe('SSE event throughput', () => {
         }
         return true;
       },
-      { timeout: 5000 },
+      { timeout: 5000 }
     );
     const elapsed = performance.now() - start;
 
@@ -880,11 +911,9 @@ describe('Memory usage under load', () => {
       const id = await createSession(page, `perf-mem-${i}`);
       sessionIds.push(id);
     }
-    await page.waitForFunction(
-      (count: number) => document.querySelectorAll('.session-tab').length >= count,
-      10,
-      { timeout: 5000 },
-    );
+    await page.waitForFunction((count: number) => document.querySelectorAll('.session-tab').length >= count, 10, {
+      timeout: 5000,
+    });
 
     // Switch through all tabs
     for (const id of sessionIds) {
@@ -895,10 +924,13 @@ describe('Memory usage under load', () => {
     const heapAfter = await getHeapMB(page);
     const heapGrowth = heapAfter - heapBefore;
 
-    console.log(`[memory] before: ${heapBefore.toFixed(1)}MB, after: ${heapAfter.toFixed(1)}MB, growth: ${heapGrowth.toFixed(1)}MB`);
+    console.log(
+      `[memory] before: ${heapBefore.toFixed(1)}MB, after: ${heapAfter.toFixed(1)}MB, growth: ${heapGrowth.toFixed(1)}MB`
+    );
 
     // Heap should stay under absolute limit
-    if (heapAfter > 0) { // memory API may not be available
+    if (heapAfter > 0) {
+      // memory API may not be available
       expect(heapAfter).toBeLessThan(THRESHOLDS.MEMORY_HEAP_MB);
     }
   });

test/push-payload-host-title.test.ts

@@ -47,7 +47,8 @@ interface PushPayload {
 
 function makeServerWithHost(host: string): WebServer {
   // Constructor only assigns fields — no network/disk activity until start().
-  const server = new WebServer(0, false, true, host);
+  // 4th arg is the bind host; the title hostname is the 5th arg.
+  const server = new WebServer(0, false, true, '127.0.0.1', host);
   // Stub push store: one subscription with all events enabled.
   const fakeSub = {
     endpoint: 'https://push.example.com/abc',

test/ralph-integration.test.ts

@@ -106,7 +106,7 @@ describe('Ralph Integration Tests', () => {
       const res = await fetch(`${baseUrl}/api/sessions/non-existent-id`);
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -136,7 +136,8 @@ describe('Ralph Integration Tests', () => {
       // Verify session is gone
       const getRes = await fetch(`${baseUrl}/api/sessions/${sessionId}`);
       const getData = await getRes.json();
-      expect(getData.error).toBe('Session not found');
+      expect(getRes.status).toBe(404);
+      expect(getData.error).toContain('not found');
     });
 
     it('should create shell session', async () => {
@@ -191,7 +192,7 @@ describe('Ralph Integration Tests', () => {
       const res = await fetch(`${baseUrl}/api/sessions/fake-session/ralph-state`);
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.error).toContain('not found');
     });
@@ -359,7 +360,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(400);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('INVALID_INPUT');
     });
@@ -372,7 +373,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -395,7 +396,7 @@ describe('Ralph Integration Tests', () => {
       createdSessions.push(createData.sessionId);
 
       // Wait for session to be ready
-      await new Promise(r => setTimeout(r, 200));
+      await new Promise((r) => setTimeout(r, 200));
 
       const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/resize`, {
         method: 'POST',
@@ -422,7 +423,7 @@ describe('Ralph Integration Tests', () => {
       createdSessions.push(createData.sessionId);
 
       // Wait for session to be ready
-      await new Promise(r => setTimeout(r, 200));
+      await new Promise((r) => setTimeout(r, 200));
 
       const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/resize`, {
         method: 'POST',
@@ -431,7 +432,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(400);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('INVALID_INPUT');
     });
@@ -472,7 +473,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -497,7 +498,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(400);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('INVALID_INPUT');
     });
@@ -536,7 +537,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -561,7 +562,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(400);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('INVALID_INPUT');
     });
@@ -626,7 +627,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -907,7 +908,7 @@ describe('Ralph Integration Tests', () => {
       });
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -991,7 +992,7 @@ describe('Ralph Integration Tests', () => {
       const res = await fetch(`${baseUrl}/api/sessions/fake-session/output`);
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });
@@ -1021,7 +1022,7 @@ describe('Ralph Integration Tests', () => {
       const res = await fetch(`${baseUrl}/api/sessions/fake-session/terminal`);
       const data = await res.json();
 
-      expect(res.status).toBe(200);
+      expect(res.status).toBe(404);
       expect(data.success).toBe(false);
       expect(data.errorCode).toBe('NOT_FOUND');
     });

test/render-index-html.test.ts

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

test/routes/file-routes.test.ts

@@ -305,6 +305,22 @@ describe('file-routes', () => {
       expect(res.headers['content-type']).toBe('image/png');
     });
 
+    it('serves workspace SVG as an untrusted attachment instead of inline image/svg+xml', async () => {
+      const content = Buffer.from('<svg><script>alert("xss")</script></svg>');
+      mockedReadFile.mockResolvedValue(content as never);
+      mockedStat.mockResolvedValue({ size: content.length } as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/file-raw?path=malicious.svg`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.headers['content-type']).toBe('application/octet-stream');
+      expect(res.headers['content-disposition']).toContain('attachment; filename="malicious.svg"');
+      expect(res.headers['x-content-type-options']).toBe('nosniff');
+    });
+
     it('rejects path traversal in raw file serving', async () => {
       mockedRealpathSync.mockReturnValue('/etc/shadow' as never);
 
@@ -363,4 +379,63 @@ describe('file-routes', () => {
       expect(body.success).toBe(false);
     });
   });
+
+  // ========== GET /api/download ==========
+
+  describe('GET /api/download', () => {
+    it('requires a sessionId to scope downloads', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?path=${encodeURIComponent('/tmp/test-workdir/report.txt')}`,
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('downloads files scoped to the session working directory', async () => {
+      const content = Buffer.from('download content');
+      mockedReadFile.mockResolvedValue(content as never);
+      mockedStat.mockResolvedValue({ size: content.length, isFile: () => true } as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=report.txt`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.headers['content-disposition']).toContain('filename="report.txt"');
+      expect(res.body).toBe('download content');
+    });
+
+    it('rejects absolute paths outside the session working directory', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=${encodeURIComponent('/var/log/app.log')}`,
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+
+    it('rejects symlink targets that escape the session working directory', async () => {
+      mockedRealpathSync.mockReturnValue('/tmp/outside-workdir/link.log' as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=${encodeURIComponent(
+          '/tmp/test-workdir/link.log'
+        )}`,
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+
+    it('blocks sensitive files even when they are inside the session working directory', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/download?sessionId=${harness.ctx._sessionId}&path=.env`,
+      });
+
+      expect(res.statusCode).toBe(403);
+    });
+  });
 });

test/routes/system-span-displays.test.ts

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

test/server-index-title.test.ts

@@ -32,36 +32,38 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const indexHtmlPath = join(__dirname, '..', 'src', 'web', 'public', 'index.html');
 const rawTemplate = readFileSync(indexHtmlPath, 'utf-8');
 
-function render(host?: string): string {
-  const server = new WebServer(0, false, true, host);
-  return (server as unknown as { renderIndexHtml: () => string }).renderIndexHtml();
+async function render(host?: string): Promise<string> {
+  // 4th arg is the bind host; the title hostname is the 5th arg.
+  const server = new WebServer(0, false, true, '127.0.0.1', host);
+  // renderIndexHtml is async (it reads settings.json for the gesture bundle).
+  return (server as unknown as { renderIndexHtml: () => Promise<string> }).renderIndexHtml();
 }
 
 describe('WebServer index.html <title> templating (#82)', () => {
-  it('substitutes the bare <title>Codeman</title> with codeman:<host>', () => {
-    const html = render('laptop');
+  it('substitutes the bare <title>Codeman</title> with codeman:<host>', async () => {
+    const html = await render('laptop');
     expect(html).toContain('<title>codeman:laptop</title>');
     expect(html).not.toContain('<title>Codeman</title>');
   });
 
-  it('defaults to os.hostname() when no titleHostname is supplied', () => {
-    const html = render();
+  it('defaults to os.hostname() when no titleHostname is supplied', async () => {
+    const html = await render();
     const expected = `<title>codeman:${osHostname()}</title>`;
     expect(html).toContain(expected);
   });
 
-  it('treats an empty-string titleHostname as "not supplied" and falls back to os.hostname()', () => {
+  it('treats an empty-string titleHostname as "not supplied" and falls back to os.hostname()', async () => {
     // CLI normally guarantees a non-empty string, but the constructor's
     // `titleHostname || getHostname()` guard makes empty fall through —
     // pin that behavior so a future refactor doesn't accidentally ship
     // a `<title>codeman:</title>` to users.
-    const html = render('');
+    const html = await render('');
     expect(html).toMatch(/<title>codeman:.+<\/title>/);
     expect(html).not.toContain('<title>codeman:</title>');
   });
 
-  it('HTML-escapes < > & in the hostname so it cannot break out of the title tag', () => {
-    const html = render('<script>alert(1)</script>');
+  it('HTML-escapes < > & in the hostname so it cannot break out of the title tag', async () => {
+    const html = await render('<script>alert(1)</script>');
     expect(html).toContain('<title>codeman:&lt;script&gt;alert(1)&lt;/script&gt;</title>');
     // The raw closing </title> from the injected payload must NOT appear
     // outside the actual title element — escape-then-substitute prevents
@@ -69,16 +71,18 @@ describe('WebServer index.html <title> templating (#82)', () => {
     expect(html).not.toContain('<script>alert(1)</script></title>');
   });
 
-  it('escapes an ampersand without double-encoding existing entities', () => {
+  it('escapes an ampersand without double-encoding existing entities', async () => {
     // The escaper replaces & first, then < and >. A hostname that already
     // contains a literal `&` should render as `&amp;` once, not `&amp;amp;`.
-    const html = render('a&b');
+    const html = await render('a&b');
     expect(html).toContain('<title>codeman:a&amp;b</title>');
     expect(html).not.toContain('&amp;amp;');
   });
 
-  it('only substitutes the <title> tag — the rest of the template is byte-for-byte identical', () => {
-    const html = render('laptop');
+  it('only substitutes the <title> tag — the rest of the template is identical (modulo asset cache-busting)', async () => {
+    // renderIndexHtml also appends ?v=<mtime> cache-bust params to same-origin
+    // .js/.css refs; strip them so the title remains the only other change.
+    const html = (await render('laptop')).replace(/(\.(?:js|css))\?v=[^"]*/g, '$1');
     const beforeTitle = rawTemplate.split('<title>Codeman</title>')[0];
     const afterTitle = rawTemplate.split('<title>Codeman</title>')[1];
     expect(html.startsWith(beforeTitle)).toBe(true);
@@ -88,8 +92,8 @@ describe('WebServer index.html <title> templating (#82)', () => {
     expect(html.length - rawTemplate.length).toBe(expectedDelta);
   });
 
-  it('replaces the <title> placeholder exactly once', () => {
-    const html = render('laptop');
+  it('replaces the <title> placeholder exactly once', async () => {
+    const html = await render('laptop');
     // Defense against a future regression where the template gains a
     // second `<title>Codeman</title>` (e.g. inside a <noscript>) and only
     // the first gets templated — would leave a stale literal in the served
@@ -100,9 +104,9 @@ describe('WebServer index.html <title> templating (#82)', () => {
     expect(occurrencesOfOld).toBe(0);
   });
 
-  it('two WebServer instances on different hostnames render distinct titles', () => {
-    const htmlA = render('host-a');
-    const htmlB = render('host-b');
+  it('two WebServer instances on different hostnames render distinct titles', async () => {
+    const htmlA = await render('host-a');
+    const htmlB = await render('host-b');
     expect(htmlA).toContain('<title>codeman:host-a</title>');
     expect(htmlB).toContain('<title>codeman:host-b</title>');
     expect(htmlA).not.toContain('host-b');

test/setup.ts

@@ -6,11 +6,15 @@
  * This means tests CANNOT kill, create, or interact with real tmux
  * sessions regardless of what the test code does.
  *
- * This setup file only handles mock/timer cleanup between tests.
+ * This setup file strips shell-level auth configuration that can leak from a
+ * running Codeman instance, then handles mock/timer cleanup between tests.
  */
 
 import { afterEach, vi } from 'vitest';
 
+delete process.env.CODEMAN_PASSWORD;
+delete process.env.CODEMAN_USERNAME;
+
 afterEach(() => {
   vi.clearAllMocks();
   vi.useRealTimers();

test/tmux-manager.test.ts

@@ -20,6 +20,17 @@ vi.mock('node:child_process', async () => {
   const actual = await vi.importActual('node:child_process');
   return {
     ...actual,
+    exec: vi.fn((_cmd: string, optionsOrCallback?: unknown, maybeCallback?: unknown) => {
+      const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+      if (typeof callback === 'function') {
+        setImmediate(() => callback(null, '', ''));
+      }
+      return {
+        on: vi.fn(),
+        kill: vi.fn(),
+        pid: 12345,
+      };
+    }),
     execSync: vi.fn(),
     spawn: vi.fn(() => ({
       unref: vi.fn(),
@@ -41,6 +52,15 @@ vi.mock('node:fs', async () => {
   };
 });
 
+vi.mock('node:fs/promises', async () => {
+  const actual = await vi.importActual('node:fs/promises');
+  return {
+    ...actual,
+    writeFile: vi.fn(() => Promise.resolve()),
+    rename: vi.fn(() => Promise.resolve()),
+  };
+});
+
 describe('TmuxManager (unit)', () => {
   let manager: TmuxManager;
   const mockedExecSync = vi.mocked(execSync);
@@ -369,6 +389,95 @@ describe('TmuxManager (unit)', () => {
       // No error thrown
     });
   });
+
+  describe('tmux launch cwd hardening', () => {
+    async function importWithTmuxCommandsEnabled(): Promise<typeof TmuxManager> {
+      const originalVitest = process.env.VITEST;
+      vi.resetModules();
+      delete process.env.VITEST;
+      const module = await import('../src/tmux-manager.js');
+      if (originalVitest === undefined) {
+        delete process.env.VITEST;
+      } else {
+        process.env.VITEST = originalVitest;
+      }
+      return module.TmuxManager;
+    }
+
+    beforeEach(() => {
+      mockedExecSync.mockImplementation((cmd: string) => {
+        if (typeof cmd === 'string' && cmd.includes('which tmux')) {
+          return '/usr/bin/tmux\n';
+        }
+        if (typeof cmd === 'string' && cmd.includes('display-message') && cmd.includes('#{pane_pid}')) {
+          return '4242\n';
+        }
+        return '';
+      });
+    });
+
+    it('starts new tmux sessions from /tmp and cd-bounces into the requested workspace', async () => {
+      const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+      const nonTestManager = new NonTestTmuxManager();
+
+      try {
+        const session = await nonTestManager.createSession({
+          sessionId: 'abc12345-1234-5678-90ab-cdef12345678',
+          workingDir: '/mnt/gdrive/project with spaces',
+          mode: 'shell',
+        });
+
+        expect(session.workingDir).toBe('/mnt/gdrive/project with spaces');
+        expect(session.pid).toBe(4242);
+
+        const newSessionCall = mockedExecSync.mock.calls.find(
+          ([cmd]) => typeof cmd === 'string' && cmd.includes(' new-session ')
+        );
+        expect(newSessionCall?.[0]).toBe(`tmux -L 'codeman' new-session -ds "codeman-abc12345" -c /tmp`);
+        expect(newSessionCall?.[1]).toEqual(expect.objectContaining({ cwd: '/tmp' }));
+
+        const respawnCall = mockedExecSync.mock.calls.find(
+          ([cmd]) => typeof cmd === 'string' && cmd.includes(' respawn-pane ')
+        );
+        expect(respawnCall?.[0]).toContain(`tmux -L 'codeman' respawn-pane -k -c /tmp -t "codeman-abc12345"`);
+        expect(respawnCall?.[0]).toContain('cd \\"/mnt/gdrive/project with spaces\\" &&');
+      } finally {
+        nonTestManager.destroy();
+      }
+    });
+
+    it('respawns existing panes from /tmp and cd-bounces into the requested workspace', async () => {
+      const NonTestTmuxManager = await importWithTmuxCommandsEnabled();
+      const nonTestManager = new NonTestTmuxManager();
+      nonTestManager.registerSession({
+        sessionId: 'respawn1234',
+        muxName: 'codeman-abcd1234',
+        pid: 1000,
+        createdAt: Date.now(),
+        workingDir: '/tmp',
+        mode: 'shell',
+        attached: false,
+      });
+
+      try {
+        const pid = await nonTestManager.respawnPane({
+          sessionId: 'respawn1234',
+          workingDir: '/mnt/gdrive/project',
+          mode: 'shell',
+        });
+
+        expect(pid).toBe(4242);
+        const { exec: currentExec } = await import('node:child_process');
+        const respawnCall = vi
+          .mocked(currentExec)
+          .mock.calls.find(([cmd]) => typeof cmd === 'string' && cmd.includes(' respawn-pane '));
+        expect(respawnCall?.[0]).toContain(`tmux -L 'codeman' respawn-pane -k -c /tmp -t "codeman-abcd1234"`);
+        expect(respawnCall?.[0]).toContain('cd \\"/mnt/gdrive/project\\" &&');
+      } finally {
+        nonTestManager.destroy();
+      }
+    });
+  });
 });
 
 // ============================================================================