feat: vendor gesture-control source into packages/gesture-control

Bring the Ark0N/codeman-gesture-control repo in-tree as the codeman-gesture-control
workspace package so the hand-tracking overlay can be developed in the Codeman repo.
New npm run build:gesture bundles src/codeman/entry.ts into the served
gesture-codeman.js; scripts/build.mjs reruns it on every production build.
Source formatted to Codeman's prettier style.

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

.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Check package-lock.json version sync
+        run: npm run check:lockfile
+
       - name: Type check
         run: npm run typecheck
 
@@ -31,6 +34,32 @@ jobs:
       - name: Format check
         run: npm run format:check
 
+      - name: Server boot smoke test
+        run: |
+          set -u
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+          npx tsx src/index.ts web --port 3151 > /tmp/boot.log 2>&1 &
+          SERVER_PID=$!
+          trap "kill $SERVER_PID 2>/dev/null || true" EXIT
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:3151/api/status -o /dev/null; then
+              echo "Server booted in ${i}s"
+              exit 0
+            fi
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "Server exited before becoming ready. Logs:"
+              cat /tmp/boot.log
+              exit 1
+            fi
+            sleep 1
+          done
+          echo "Server did not respond on /api/status within 30s. Logs:"
+          cat /tmp/boot.log
+          exit 1
+
 # Note: The test suite is intentionally excluded from CI.
 # Tests spawn real tmux sessions and require a full system environment.
 # Run tests locally with: npx vitest run test/<file>.test.ts

.gitignore

@@ -48,7 +48,29 @@ Thumbs.db
 # Generated output
 out/
 screenshots-echo-diag/
-tools/remotion/out/
+scripts/remotion/out/
+
+# Artifacts that should not be tracked
+test-results/
+tmp/
+# Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
+# with a leading slash so it does NOT also match src/web/public (a bare `public`
+# would swallow the whole web UI source dir and silently un-stage any new asset
+# added there). No trailing slash so it still matches the symlink, not just dirs.
+/public
+
+# Opt-in gesture overlay runtime assets: large MediaPipe wasm + model (~27 MB)
+# fetched at build/install by scripts/fetch-gesture-assets.mjs, kept out of git.
+# (The gesture bundle itself, gesture-codeman.js, IS tracked — 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
@@ -61,3 +83,6 @@ commands
 todo.md
 @fix_plan.md
 readme-preview.mjs
+
+# Uploaded images land here under each session working dir (runtime artifact)
+.claude-images/

.prettierignore

@@ -2,8 +2,27 @@ dist/
 coverage/
 node_modules/
 src/web/public/vendor/
+src/web/public/gesture/
 src/web/public/app.js
 src/web/public/styles.css
 src/web/public/mobile.css
 src/web/public/index.html
-tools/
+# 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,415 @@
 # aicodeman
 
+## 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
+
+- Session detach/undock, opt-in gesture-control overlay, multi-monitor spanning, new App-Settings toggles, and asset cache-busting.
+  - **Session detach/undock + instance isolation (#103):** Detach a session into its own solo (popup) window from the tab strip. Adds multi-instance isolation primitives in `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`) keyed off `CODEMAN_INSTANCE`, so a beta can run side-by-side with prod without discovering/attaching to prod's live tmux sessions or clobbering its `state.json`. `CODEMAN_INSTANCE` defaults to the production layout (`~/.codeman`, `-L codeman`, port 3000), so master installs are unaffected. Adds `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). The legacy `~/.claudeman` migration is now scoped to the default instance only. Hardened detach edge cases. Tests: `test/config/instance.test.ts`.
+  - **Gesture-control overlay (Phase 5, opt-in via `CODEMAN_GESTURE=1`):** Camera hand-tracking overlay (self-hosted MediaPipe — wasm + model fetched at install/build via `scripts/fetch-gesture-assets.mjs` rather than committed). `CODEMAN_GESTURE=1` makes the feature _available_ (CSP widening + `/gesture/` assets + `window.__codemanGestureAvailable`); the per-user **Gesture Control (beta)** toggle (App Settings → Display → Input, default OFF) is the actual on/off and reloads the page to inject/remove the bundle. Dashboard-only (not solo popups). Labeled "(beta)" (#109).
+  - **Multi-monitor button:** Header button (opt-in via App Settings → Display → Header Displays) that POSTs `/api/system/span-displays` to spawn `scripts/span-codeman.sh` — a maximized browser `--app` window sized to the union of all displays, so the gesture layer's floating panels can drag across the physical monitor seam. Tests: `test/routes/system-span-displays.test.ts`.
+  - **New App-Settings toggles (#105):** Gesture control and the multi-monitor button are both opt-in (default OFF), with live show/hide on save.
+  - **Asset cache-busting:** `renderIndexHtml` appends `?v=<mtime>` to every same-origin `.js`/`.css` reference; `index.html` is served `no-cache`, so a normal reload picks up edited modules/styles without a hard refresh. Tests: `test/render-index-html.test.ts`.
+  - **Gesture Control toggle placement:** the toggle now lives inside the existing **Input** settings section (alongside Local Echo / CJK Input / Extended Keyboard Bar) instead of a duplicate "Input" section; only the toggle itself is hidden when `CODEMAN_GESTURE=1` is unset, leaving the rest of the section intact.
+  - **Service env:** `scripts/codeman-web.service` now sets `CODEMAN_GESTURE=1` so the gesture feature is available on the local install (still gated behind the default-OFF per-user toggle).
+  - **Docs:** CLAUDE.md updated for the orchestrator loop, multi-monitor/span-displays, cache-busting, gesture/multi-monitor toggles, and structural-count fixes.
+
+## 0.8.1
+
+### Patch Changes
+
+- Thinking Effort now flows as a soft default the user can override in-session (PR #104, by @TeigenZhang).
+
+  Previously Codeman carried the effort setting as the `CLAUDE_CODE_EFFORT_LEVEL` env var, which Claude Code treats as a hard override — it locked effort for the whole session and rejected in-session `/effort` switching (including switching to `ultracode`). Effort is now injected at spawn time as a CLI soft default that `/effort` can still change freely in either direction:
+  - Regular levels (`low`/`medium`/`high`/`xhigh`/`max`) are passed via `claude --effort <level>` (the settings `effortLevel` key silently drops `max`, so the flag is used instead).
+  - `ultracode` (xhigh effort + standing dynamic-workflow orchestration) is passed via `claude --settings '{"ultracode":true}'`, since the `--effort` flag rejects it.
+
+  Details:
+  - New `effort` field on the create-session, quick-start, and Ralph-loop request schemas; threaded through `Session._effort` to both spawn paths (tmux `buildSpawnCommand` and direct-PTY `buildInteractiveArgs`), persisted in `SessionState.effort`, and restored on reboot recovery.
+  - `buildEffortCliArgs()` is the single, allowlist-validated source for both carriers (injection-safe).
+  - Settings UI adds an "Ultracode (multi-agent workflows)" option to the Thinking Effort dropdown; the frontend no longer emits `CLAUDE_CODE_EFFORT_LEVEL`.
+  - Legacy migration: sessions persisted with the old env var are auto-migrated into the new `effort` field, and the stale tmux env var is unset so respawned panes are no longer locked.
+  - Adds `test/effort-injection.test.ts` (13 cases) covering carrier mapping, injection guards, args building, and constructor migration.
+
+## 0.8.0
+
+### Minor Changes
+
+- Event-loop responsiveness fix, mobile image upload, response-viewer polish, and a mobile-UI trim.
+  - **fix: avoid event-loop stalls from synchronous tmux/ps calls (#100):** The session manager ran `execSync` for tmux mouse-mode toggles, `list-panes`, and `ps`/`pgrep` resource-stat queries on the main thread. Under multi-session / many-pane load these blocking spawns froze Node's single event loop, stalling SSE broadcasts and PTY I/O (the ":3000 briefly unreachable, process never restarts" class of incident). Converted those calls to async `execAsync` and updated all callers to `await`. Added a lightweight `utils/event-loop-monitor.ts` that samples loop-delay and logs when a stall threshold is exceeded, started on web-server boot and stopped on shutdown — so future regressions leave a timestamped, quantified log line instead of vanishing silently.
+  - **feat(web): mobile image upload to active session via paste dialog (#101):** The mobile keyboard-accessory paste dialog now attaches images, not just text — via a native picker (`accept=image/*` → camera / photo library / files) plus best-effort capture of images pasted into the textarea. Both paths reuse the existing `_uploadAndInsertImages()` → `POST /api/sessions/:id/paste-image` pipeline. Images are re-encoded client-side before upload (PNG→PNG to preserve transparency, everything else→JPEG, animated GIFs passed through untouched) so the bytes always match their declared extension — fixing the Android/MIUI case where a WebP/HEIF mislabeled as `image/jpeg` passed the extension allowlist but failed the server's magic-byte check. The server logs a precise diagnostic on any remaining magic-byte mismatch.
+  - **feat(web): response-viewer transcript fallback + code-block rendering (#102):** A substantial response-viewer styling overhaul — proportional prose font (monospace kept for code), refined heading/code/blockquote/list styling, readable max content width, and a smoother slide-in animation; the `.rv-text` rules now also apply to `.response-viewer-body` so transcript-missing fallback content gets the same typography. Plus a `_renderMarkdown` null-safety fix (`text` → `src = text || ''`).
+  - **feat(web): remove /compact button from the mobile keyboard accessory bar:** Dropped `/compact` from both the simple and extended accessory-bar layouts and the associated action handling. `/clear` retains its double-tap confirmation. Verified on a touch-emulated viewport that neither layout renders a compact action.
+
+## 0.7.1
+
+### Patch Changes
+
+- **fix(respawn): auto-accept now fires on plan approvals after `Worked for X` line, and on AskUserQuestion menus**
+
+  Two related blockers in the respawn controller's auto-accept path:
+  - Modern Claude Code emits `✻ Worked for Xm Ys` immediately before a plan-approval menu. `_detectCompletionMessage()` cancelled the auto-accept timer and `canAutoAccept()` then rejected on `completionMessageTime !== null`, so plan approvals **never** auto-accepted — the 10 s completion-confirm timer instead started a respawn cycle while the menu sat unanswered.
+  - The same logic in `signalElicitation()` set a hard flag that blocked auto-accept whenever Claude Code fired the `elicitation_dialog` hook, contradicting the in-UI hint ("Auto-accept presses Enter for plan approvals **and default question options**"). AskUserQuestion menus were therefore never auto-accepted either.
+
+  Fix:
+  - `_detectCompletionMessage()` no longer cancels the auto-accept timer; the auto-accept pre-filter is now the authoritative "is there a numbered selection menu?" gate.
+  - `canAutoAccept()` and the AI-plan-check callback both accept `'watching'` AND `'confirming_idle'` states (covers the single-PTY-burst case where `Worked for` and the menu arrive together — `_detectCompletionMessage` returns early before the substantial-output check can demote state back to watching). `sendAutoAcceptEnter()` self-transitions back to `'watching'` before sending Enter.
+  - `signalElicitation()` is now an affirmative hint that primes the auto-accept timer instead of blocking. Still gated on `config.autoAcceptPrompts` AND state ∈ {`watching`, `confirming_idle`} — never fires Enter when respawn is off or auto-accept is disabled.
+  - AI plan-check prompt broadened to recognize AskUserQuestion / elicitation menus as valid for auto-accept (the verdict name `PLAN_MODE` is preserved for compatibility but now means "auto-accept this selection menu").
+  - Removed the now-unused `elicitationDetected` field and its assignments.
+
+  Two new regression tests cover both the separate-PTY-chunk and single-PTY-chunk cases; the previously misleading "should NOT send Enter when completion message was detected" test was renamed and re-scoped to clarify it tests the **no-menu** path (which still correctly rejects via the pre-filter).
+
+  **docs(web): correct `sendPendingCtrlL` comment** — removed the stale "called by foo/bar" note from the dead-call-graph helper after #99.
+
+## 0.7.0
+
+### Minor Changes
+
+- Response viewer & terminal-stability improvements, plus test/error-handling hardening.
+  - **Copy button on code blocks (#98):** Every fenced code block in the response viewer now has a one-click copy button pinned to its top-right, outside the `<pre>` scroll container so it stays put during horizontal scroll. ASCII diagrams keep their line-wrap toggle alongside it. Copy prefers the async Clipboard API and falls back to a hidden-textarea + `execCommand` path, so it works over plain HTTP (tunnel) too, with a brief ✓/✕ feedback state.
+  - **Fix: stop auto-sending Ctrl+L from session-selection paths (#99):** A fast page refresh or SSE reconnect could fire two programmatic Ctrl+L (`\x0c`) sends within Claude Code 2.x's "clear conversation" confirmation window, silently wiping the active conversation. Removed the automatic Ctrl+L sends from `selectSession()`, `restoreTerminalSize()`, and the dead `sendPendingCtrlL()` path; redraws now rely on resize/SIGWINCH. User-initiated Ctrl+L still works. Trade-off: an occasional transient stale Ink frame right after refresh that self-heals on the next keypress — far preferable to silent data loss.
+  - **Test & error-handling hardening (#97):** Repaired route-test harness error rendering via a dedicated `route-error-handler.ts`, and stopped the AI idle/plan checkers from spawning real processes during tests.
+
+## 0.6.12
+
+### Patch Changes
+
+- Fix new-session crash after a tmux upgrade and isolate Codeman sessions on a dedicated tmux socket.
+  - **Pane file-descriptor limit**: raise `ulimit -Sn` before launching the CLI (in both the spawn and respawn paths) so the newer tmux + macOS launchd combination — which hands panes a low soft `nofile` limit (256) that recent Claude Code refuses to start under — no longer kills every freshly spawned session on startup.
+  - **Single-socket isolation**: all Codeman-owned tmux sessions now live on a dedicated socket (`tmux -L codeman`, overridable via `CODEMAN_TMUX_SOCKET`), fully separated from the user's default tmux server. The socket name is validated and shell-escaped at every call site.
+  - **Drop the drift-prone per-session `tmuxSocket` field**: session reconciliation collapses to a single `list-panes` query against the one socket, eliminating live sessions being wrongly marked dead ("session not found") and duplicate "Restored:" tabs. Stale per-session socket tags and duplicate records are cleaned from disk on load (dedup by `muxName`, keeping the real entry over `restored-` placeholders).
+  - **Route remaining bare-`tmux` call sites through the socket**: the window-size query on re-attach (previously fell back to 120×40 and lost scrollback) and the send-key route (Shift+Enter / Ctrl+Enter newline).
+  - **SSH chooser scripts** (`tmux-manager.sh`, `tmux-chooser.sh`) route every tmux call through the dedicated socket.
+
+## 0.6.11
+
+### Patch Changes
+
+- Resume Conversation: fixes and folder drill-down.
+  - **fix(history)**: `decodeProjectKey()` now uses longest-join-first backtracking with on-disk validation, so sibling directories sharing a prefix (e.g. `diary/` vs `diary-app/`) resolve to the correct path. Previously the greedy shortest-match decoder picked the shorter name and bailed, surfacing `$HOME` in the Resume Conversation list and resuming into the wrong folder. Greedy decode is kept as a fallback so history for deleted projects still resolves. (#92)
+  - **fix(tabs)**: Drop the client-side resurrection of ended-session tabs. The old code cached open tabs in `localStorage` and rebuilt them as grayed-out stubs whenever the server no longer knew them, which left phantom tabs after closing a session on another device. The server is now the single source of truth; legacy `localStorage` keys are purged on init. Net -44 / +6 lines. (#93)
+  - **feat(history)**: New "View all in this folder" drill-down on Resume Conversation. `GET /api/history/sessions` accepts `projectKey` (validated against `^[A-Za-z0-9_-]+$` before any filesystem access), `offset`, and `limit`; single-folder mode bypasses the 50-cap and returns `{ sessions, total }`. Frontend adds a modal listing 20 sessions per page with a "Show more" pagination button. Modal items omit their own "View all" button to prevent recursive entry points. (#94)
+
+## 0.6.10
+
+### Patch Changes
+
+- ## Security: paste-image endpoint hardening (#90)
+
+  Addresses seven findings from the dismissed review of #84. Most exposed in tunneled deployments where `CODEMAN_PASSWORD` is set but the server is reachable beyond localhost.
+  - **CSRF protection** on `POST /api/sessions/:id/paste-image`. Requires `Origin`/`Referer` to match `req.host`; non-browser clients (no `Origin` and no `Referer`) must send `X-Codeman-CSRF`. Defeats cross-origin `<form enctype="multipart/form-data">` submits that would otherwise plant arbitrary bytes into the victim's `.claude-images/` while their session cookie is live.
+  - **Magic-byte validation** on uploaded images. Sniffs the first 12 bytes against PNG/JPEG/GIF/WebP/BMP signatures and rejects 415 on mismatch. Polyglot HTML-or-SVG-with-image-MIME no longer round-trips through the endpoint.
+  - **Symlink-safe writes** on `.claude-images/`. `lstat` before the write, non-recursive `mkdir`, `O_EXCL|O_NOFOLLOW` on file open. A `node_modules` postinstall (or the agent itself) planting `.claude-images -> ~/.ssh/` no longer redirects pastes outside `workingDir`.
+  - **Multipart parser swap** to `@fastify/multipart` with `limits: { fileSize: 10MB, files: 1, fields: 4 }`. Replaces a hand-rolled boundary scanner that matched the literal boundary anywhere in the body, hard-coded `\r\n` (silently corrupting LF-only clients), and had no part-count cap.
+  - **Rate limit + GC**: token-bucket (30/min per IP+session) and hourly GC of `paste-*` files older than 7 days from each live session's `.claude-images/`. New `paste-image-gc.ts` started/stopped from `WebServer.start/stop`.
+  - **Collision-free filenames**: `paste-${Date.now()}-${randomBytes(4)}${ext}`. Two tabs pasting in the same millisecond no longer silently last-write-wins.
+  - **Bracketed-paste preservation**: text-only paste in `image-input.js` now goes through `terminal.paste(text)` instead of `sendInput(text)`, so xterm preserves `CSI 200~ ... CSI 201~` markers — Claude Code uses them as part of its prompt-injection defenses.
+
+  ## Fix: duplicate multipart parser conflict
+
+  Removed a duplicate multipart content-type parser left behind after the swap above. The duplicate registration conflicted with `@fastify/multipart`'s own parser; uploads now flow through the plugin exclusively.
+
+  ## WebGL renderer auto-fallback hardening (#91)
+
+  Follow-ups on the longtask auto-fallback shipped in #83.
+  - `PerformanceObserver` is now disconnected on `onContextLoss` as well as on the trip path. Previously the observer outlived its disposed addon after a context loss, holding a closure reference over every longtask the page emitted.
+  - Thresholds (`200ms / 3 longtasks / 30s window / 5s grace / 7d sticky-disable`) are hoisted to `WEBGL_FALLBACK` in `constants.js`. No more inline literals.
+  - New `evaluateWebGLLongTaskTrip()` pure helper splits the rolling-window arithmetic from the `PerformanceObserver` callback so the trip math is unit-testable. New `test/webgl-fallback.test.ts` (9 tests, port 3166): trip inside window, no-trip when spread, sub-threshold filtering, stale-entry pruning, cumulative counting across batches, observer-dispose idempotency.
+
+  ## CI: server boot smoke test
+
+  GitHub Actions now boots the server as a final step after typecheck/lint/format. Catches production-only ESM/CJS regressions that `tsx` masks in dev.
+
+  ## Docs
+
+  `CLAUDE.md` frontend-module table updated to include `image-input.js` (overlooked when #84 landed).
+
+## 0.6.9
+
+### Patch Changes
+
+- Terminal renderer hardening, SSE bandwidth cut, image paste, and a security tightening on the new live filter:
+  - **Multi-primitive yield for write pacing** (#85): replaces six raw `requestAnimationFrame` callsites in the xterm.js write pipeline with a yielding helper that races `requestAnimationFrame`, `setTimeout(50)`, and a tick Worker. Keeps the terminal responsive when the tab is backgrounded or occluded — Chrome's intensive-throttling no longer stalls long writes.
+  - **WebGL longtask auto-fallback** (#83): a `PerformanceObserver` watches for ≥200ms WebGL frames; three within a 30s window disposes the WebGL addon and falls back to the canvas renderer. Decision is persisted in localStorage for 7 days, and `?webgl=force` clears it.
+  - **Per-client live SSE subscription filter** (#86): each connected client gets a stable UUID and can narrow its terminal stream to one session via `POST /api/events/subscribe` — no EventSource reconnect on tab switches. Cuts SSE bandwidth roughly N× when N sessions are open. Lifecycle/metadata events (`session:*`, `case:*`, `ralph:*`, `hook:*`) now broadcast to every client so sidebars stay in sync.
+  - **Image paste and drag-and-drop into the terminal** (#84): `Ctrl+V` and dropped images upload to `POST /api/sessions/:id/paste-image`, save under `${workingDir}/.claude-images/paste-${ts}.${ext}` and type the path into the terminal. Hard 10MB cap, server-generated filename (no traversal), `.svg` deliberately excluded from the allowlist to avoid a same-origin XSS path through `file-raw`.
+  - **SSE clientId validation**: the per-client identifier introduced in #86 is now constrained to `[A-Za-z0-9_-]{8,64}` at both ingress points. Without this, an authenticated attacker could send another tab's clientId to silently evict it from broadcasts, mutate any clientId's session filter to blackhole the victim's terminal stream, or grow `sseClientsById` unboundedly via long IDs. The subscribe payload is also capped at 64 session entries of ≤128 chars each.
+
+## 0.6.8
+
+### Patch Changes
+
+- Finish the hostname-aware notification plumbing started in 0.6.7 and lock down the recent UI/runtime fixes with regression tests.
+  - Browser Notification API (OS-level desktop pop-ups, layer 3 of the 5-layer notification system) now uses `${originalTitle}: ${title}` instead of the hardcoded `Codeman:` literal — so multi-host users running Codeman on laptop / dev box / NAS see `codeman:<host>: <event>` consistently across tab title, tab-flash, Web Push, and OS notifications.
+  - Inline session rename hardened against three corner cases: IME composition commits (Chinese pinyin Enter no longer ships half-composed text as the session name), mid-rename SSE deletion (orphaned `<input>` no longer 404s on blur), and double-fire on stuck settle-once flag (closure-local `settled` boolean replaces the boolean instance flag).
+  - Test coverage backfilled for two prior shipped fixes:
+    - `<title>codeman:<host></title>` server-side templating (#82): 8 tests covering default `os.hostname()`, `--title-hostname` override, HTML-escape against `<script>`-style breakout, ampersand non-double-encoding, and template-tail byte-identical invariance.
+    - tmux size-query helper (#80): 15 tests covering the browser-resize-between-attaches happy path, the query-then-die race, zero/negative/empty/non-numeric output fallbacks, and argv-form/timeout assertions that lock down the no-shell-interpolation guarantee. Inline 14-line query block extracted into a named `queryTmuxWindowSize()` export in `session.ts` so the test surface is a pure function.
+  - Regression coverage added for `stripInkRedrawBloat` route helper.
+  - CLAUDE.md and README.md updated to document dual-CLI env-prefix discipline (`CLAUDE_CODE_*` vs `OPENCODE_*`), the `xterm-zerolag-input` published-package side-effect of overlay edits, and the unified hostname prefix across tab title / tab-flash / OS notifications.
+
+## 0.6.7
+
+### Patch Changes
+
+- - **fix(client): preserve inline rename input across tab re-renders** (#81) — Right-click → rename on a session tab no longer loses keystrokes when SSE traffic from sibling sessions triggers a tab re-render. Adds an `_inlineRenameActive` guard at the top of `renderSessionTabs()` and `_fullRenameSessionTabs()` so the in-progress input isn't destroyed mid-typing. Also fixes a latent double-fire of `finishRename` (blur + Enter could both invoke it). Drive-by: safer DOM child clearing in place of `innerHTML = ''`.
+  - **feat: hostname-aware window title** (#82) — The browser tab title is now `codeman:<hostname>` instead of the bare `Codeman` literal, so users running Codeman on multiple hosts (laptop, dev box, NAS) can tell at a glance which tab points at which backend. New `--title-hostname <name>` CLI flag overrides the detected `os.hostname()` when it's noisy or you want a cosmetic name. The title is templated into the served HTML on first byte (with narrow HTML escaping), so it's correct from the first paint and works without JavaScript. Title-flash logic now respects the per-host title.
+  - **perf: larger terminal tail on tab switch** — `TERMINAL_TAIL_SIZE` raised from 128KB to 1MB. When switching back to a busy session tab you now get ~8× more scrollback restored immediately.
+  - **fix: preserve response text in Ink redraw stripping** — `stripInkRedrawBloat()` rewritten from a first-VPA approach to cluster-based detection. The previous algorithm assumed all VPA escapes after the first one belonged to a single redraw region and discarded everything in between, which silently lost 100KB+ of legitimate Claude response text once a render had occurred. The new approach groups VPAs into clusters separated by ≥8KB gaps and only collapses clusters spanning ≥32KB, so streamed response content between redraw bursts is preserved.
+  - **docs**: `CLAUDE.md` Additional Commands gains the `--title-hostname` row; `README.md` gets a "Hostname-Aware Window Title" subsection under Multi-Session Dashboard.
+
+## 0.6.6
+
+### Patch Changes
+
+- **Terminal scrollback significantly increased** — both the xterm.js viewport and the tmux backing buffer were bottlenecking how far back you could scroll. Three changes:
+  - `DEFAULT_SCROLLBACK` raised from 20000 → 50000 lines (xterm.js, main terminal). The previous bump from 5000 only helped users with empty localStorage; existing users were stuck on whatever value they first picked up. The loader now treats `DEFAULT_SCROLLBACK` as a floor — if your stored value is below the new minimum, you're raised to it automatically.
+  - Subagent / teammate terminals (`panels-ui.js`) were stuck at 5000; now use the same `DEFAULT_SCROLLBACK` constant (50000).
+  - New tmux sessions now run with `history-limit 50000` (tmux defaults to 2000). This matters for hard-reload / re-attach — without it, only the last ~2000 lines survive the round-trip back into a fresh xterm.
+
+  **Tmux flicker on session re-attach fixed (PR #80 by @aakhter)**: the PTY now queries the existing tmux window size via `tmux display -p` before spawning, instead of hardcoding 120x40. Previously, every re-attach forced tmux to resize down to 120x40, causing a visible flicker and one frame of scrollback loss. The `-x 120 -y 40` flag was also dropped from `tmux new-session` so the initial size matches the first attaching client. Uses `execFileSync` (not shell) for safety and falls back to 120x40 on any error.
+
+  **Docs**: CLAUDE.md now documents two recurring foot-guns — the `xterm-zerolag-input` overlay code is duplicated between `packages/xterm-zerolag-input/src/` and inline inside `src/web/public/app.js`, so any overlay change must touch both; and the COM workflow explicitly includes a post-push `gh run watch` step to confirm CI before considering the release done.
+
+## 0.6.5
+
+### Patch Changes
+
+- **Mobile fix**
+  - Android virtual keyboard: space character was silently dropped on touch devices using GBoard / SwiftKey / similar IMEs. Root cause: the input-event handler in `terminal-ui.js` treated any whitespace-only textarea value as proof that xterm had already processed the input. A lone space (`' '.trim() === ''`) tripped this guard, so the space was consumed but never forwarded. Now skips only when the textarea is truly empty (or whitespace from a non-space key). Reported and diagnosed by @coolk8 in #79.
+
+  **Docs**
+  - `CLAUDE.md`: added Zod `.optional()`-vs-`null` gotcha (recurring trap from 0.6.3 / 0.6.4 incidents) and a more visible warning against running bare `npm test` (kills the host tmux session).
+  - `docs/local-echo-overlay-plan.md`: marked SHIPPED, corrected xterm version reference (v5.3.0 → `@xterm/xterm` ^6.0.0).
+
+## 0.6.4
+
+### Patch Changes
+
+- Fix "Failed to enable respawn: Invalid request body" error when selecting infinity duration (∞) in the respawn modal. Frontend was sending `durationMinutes: null`, which Zod's `.optional()` schema rejected (it accepts `undefined` only). The body now omits the field when no duration is selected.
+
+## 0.6.3
+
+### Patch Changes
+
+- **Fix**
+  - Allowlist `opusContext1mEnabled` in `SettingsUpdateSchema`. Without this entry, the strict schema rejected `PUT /api/settings {"opusContext1mEnabled":...}` with `INVALID_INPUT`, so the toggle's value never persisted across reloads. The frontend was already reading and writing this key (`settings-ui.js:336/1137`, `session-ui.js:340`), so saves were silently failing — users never noticed because the load path falls back to `false` on missing keys, hiding the bug. (#78)
+
+## 0.6.2
+
+### Patch Changes
+
+- **Mobile UX**
+  - Resume Conversation list (welcome page) reworked for narrow screens: 2-line title clamp so more of the first prompt is visible; case-aware subtitle that renders `#caseName` (or `#caseName/sub`) when `workingDir` matches a known case, otherwise falls back to the directory basename; inline `⋯` toggle that expands a detail panel with full prompt, full path, timestamp, size, and short session id; `/Users/<user>/` now collapses to `~/` alongside `/home/<user>/`. (#77)
+  - Response viewer: ASCII diagram wrap toggle, dedicated mobile code-block layout, and chrome-stripping fallback when the model wraps its reply in extra markup. (#75)
+  - Mobile keyboard accessory bar no longer triggers vertical scroll. (#72)
+
+  **Sessions & settings**
+  - New `thinkingEffort` setting on session creation, with `xhigh` option and `/effort max` mobile shortcut. (#73)
+  - `thinkingEffort` is now allowlisted in `SettingsUpdateSchema` so it round-trips through PATCH /api/settings.
+  - `envOverrides` (`CLAUDE_CODE_*` / `OPENCODE_*`) are now passed to Claude via tmux env exports at spawn time instead of being written to `<case>/.claude/settings.local.json`. Eliminates UI/disk drift; the value lives on `Session._envOverrides`, is exported by `tmux-manager.buildEnvExports()`, and is persisted in `SessionState.envOverrides`. (#74)
+
+  **Fixes**
+  - Eye icon (active-session indicator) now follows `/clear` to the new Claude conversation instead of getting stuck on the previous transcript. (#76)
+  - `tmux-manager.reconcileSessions` now uses `|` as the field separator, fixing parsing when session names contain other delimiters. (#71)
+
+  **Docs**
+  - CLAUDE.md: added `npm run knip` to the dead-code sweep table and a `Common Gotchas` entry documenting the `envOverrides` → tmux export flow.
+
+## 0.6.1
+
+### Patch Changes
+
+- Internal cleanup and release hygiene:
+  - **Dead-code sweep via knip**: added `knip.json` for dead-code detection and ran a full sweep — removed unused test files, unused scripts, and narrowed internal module exports to the minimum surface area actually consumed.
+  - **Lockfile drift prevention**: `version-packages` now runs `npm install --package-lock-only` and verifies the lockfile is in sync via `scripts/check-lockfile-sync.mjs`; CI runs the same check on every push/PR so version drift fails the build instead of reaching production. Resolves the `package-lock.json` / `package.json` version mismatch that shipped in 0.6.0.
+  - **Docs tightening**: archived 22 completed plan docs from `docs/`, corrected file/handler counts in `CLAUDE.md`, documented the lockfile step in the COM workflow, and removed footer redundancy.
+
+## 0.6.0
+
+### Minor Changes
+
+- Community contributions from @aakhter:
+  - **feat (#66): Tab reorder shortcuts** — `Ctrl+Shift+{` and `Ctrl+Shift+}` move the active session tab left/right, matching WezTerm convention. Order persists across reloads via `saveSessionOrder()`.
+  - **feat (#67): Active tab visibility + Alt+N badges** — active tab now has a bright green border with color-matched glow, and the first 9 tabs display number badges hinting at the `Alt+N` switch shortcut. Badges update on reorder/rerender.
+  - **feat (#68): Clipboard API** — new `POST /api/clipboard` accepting `{text}` broadcasts a `clipboard:write` SSE event; connected browsers attempt `navigator.clipboard.writeText()` with a manual-copy modal fallback when the page isn't focused. Auth-protected via the standard middleware. Useful for pushing snippets from remote sessions to the user's local clipboard.
+  - **fix (#65): Android Shift+key double character** — pressing `Shift+A` on attached Android keyboards no longer produces "AA". Tracks xterm-handled keydown timestamps and skips the orphaned-input listener for 50ms after a real keydown, while still catching Gboard symbol-keyboard inputs (keyCode 229).
+
+## 0.5.13
+
+### Patch Changes
+
+- Fix "Case path not found" error in Quick Start when `~/codeman-cases/` does not exist (issue #64). Two bugs in `session-ui.js`:
+  - `runClaude()` auto-create read `createCaseData.case`, but `POST /api/cases` returns `{ success, data: { case } }` — corrected to `createCaseData.data.case`.
+  - `runShell()` had no auto-create logic and would immediately throw on a missing case directory — now mirrors `runClaude()`'s create-on-demand flow.
+
+## 0.5.12
+
+### Patch Changes
+
+- Fix quick-start to resolve linked cases before codeman-cases fallback. `/api/quick-start` was always resolving `caseName` against `CASES_DIR`, ignoring entries in `~/.codeman/linked-cases.json`. Sessions started via quick-start now correctly honour linked external project directories, consistent with regular case routes.
+
+## 0.5.11
+
+### Patch Changes
+
+- Community contributions and security hardening:
+  - Mobile response viewer: native-scroll panel for reading full Claude responses with markdown rendering via marked.js (PR #62)
+  - PWA support: service worker caching, web app manifest, and Android home screen install (PR #59)
+  - Named Cloudflare tunnel support (PR #58)
+  - Markdown rendering for response viewer with HTML sanitization (XSS prevention) — strips dangerous elements, event handlers, and javascript: URIs
+  - Service worker switched from stale-while-revalidate to network-first caching so deploys take effect immediately
+  - Content-Disposition filename sanitization to prevent header injection in file downloads
+  - Expose session.muxName public getter, replace unsafe `as any` cast in session-routes
+  - Static import for execFile in session-routes
+  - Keyboard shortcut updates: Alt+1-9 tab switching, Shift+Enter newline
+  - Repo restructure for cleaner GitHub landing page
+  - Mobile logo, expandable history, session resume fixes
+
+## 0.5.10
+
+### Patch Changes
+
+- fix: allow bracket characters in model validation regex so models like opus[1m] (1M context window) are accepted instead of silently dropped. Quote the model flag value in tmux spawn commands to prevent bash glob expansion of bracket patterns.
+
+  docs: update macOS launchd instructions to use `launchctl bootstrap` instead of deprecated `load`. Clean up README install and service sections.
+
+## 0.5.9
+
+### Patch Changes
+
+- Mobile keyboard accessory bar: add configurable "Extended Keyboard Bar" setting (Settings > Display > Input) that toggles between simple mode (up/down arrows, /init, /clear, /compact, paste, dismiss) and extended mode (adds left/right arrows, Tab, Shift+Tab, Ctrl+O, Alt+Enter, Esc). Default is simple mode. Setting is device-specific (not synced to server).
+
+  Restyle dismiss button: muted steel-blue tone, fills remaining bar space via flex, larger tap target. Arrow buttons now blue.
+
+  Fix paste overlay visibility on mobile: dialog repositioned to top of screen (15vh from top) so the virtual keyboard doesn't cover it. Textarea enlarged for better usability.
+
+  (Also includes all v0.5.8 changes: case reorder/delete, XSS sanitization, auto-attach PTY on restart, mobile keyboard buttons, macOS installer fixes, terminal flicker fix, state store collision fix.)
+
+## 0.5.8
+
+### Patch Changes
+
+- Case management: add Manage tab with reorder (up/down arrows) and delete for cases; linked cases are unlinked (folder preserved), CASES_DIR cases are permanently deleted. New endpoints: DELETE /api/cases/:name, PUT /api/cases/order. SSE events: case:deleted, case:order-changed.
+
+  Security: sanitize case names from filesystem with /^[a-zA-Z0-9_-]+$/ regex before returning from GET /api/cases to prevent XSS via maliciously-named directories reaching frontend inline onclick handlers.
+
+  Auto-attach PTY: server now calls startInteractive() for recovered tmux sessions during startup so all sessions resume capturing output immediately after deploy, instead of waiting for client selection. Frontend auto-attach condition relaxed from (pid===null && status==='idle') to (pid===null && !\_ended).
+
+  Mobile keyboard accessory: add Shift+Tab, Tab, Esc, Alt+Enter, Left/Right arrow, and Ctrl+O buttons.
+
+  Terminal: fix flicker regression by moving viewport clear inside dimension guard.
+
+  State store: fix temp file collisions on concurrent writes.
+
+  macOS: fix installer failures when piped via curl | bash, add HTML cache support, launchd service template, and trust dialog handling.
+
+  Housekeeping: remove accidentally committed dist/state-store.js build artifact.
+
+## 0.5.7
+
+### Patch Changes
+
+- feat: support "Default (CLI default)" option for model selection. Adds a new empty-value option to the model dropdown that defers to the CLI's own default model instead of forcing a specific model. Ensures empty defaultModel values are treated as undefined when passed to session creation and Ralph loop start, preventing empty strings from being sent as model flags.
+
+## 0.5.6
+
+### Patch Changes
+
+- fix: default new sessions to opus[1m] (1M context window) instead of plain opus (200k context)
+
+## 0.5.5
+
+### Patch Changes
+
+- Add 1M Opus context quick setting — per-case and global toggle that writes `model: "opus[1m]"` to `.claude/settings.local.json` when creating new sessions. Fix mobile layout: banners (respawn, timer, orchestrator) between header and main content now visible by switching from margin-top on `.main` to padding-top on `.app`. Add tablet-optimized respawn banner styles and mobile phone banner refinements.
+
+## 0.5.4
+
+### Patch Changes
+
+- Fix terminal flicker regression — re-add server-side DEC 2026 synchronized output wrapping around batched terminal data. Ink spinner frames (cursor-up + redraw cycles) do not emit their own DEC 2026 markers, so without the server wrapper each partial cursor update rendered individually causing visible flicker. Also: extract SSE stream management, session listener wiring, and respawn event wiring from server.ts into dedicated modules; deduplicate error message extraction across 7 files with shared getErrorMessage() helper; update SSE event count in CLAUDE.md (106 → 117).
+
+## 0.5.3
+
+### Patch Changes
+
+- Readability refactor across 12 core files, extracting ~35 helper methods to reduce duplication:
+  - state-store: extract serializeState(), split assembleStateJson() into focused sub-methods
+  - session: extract \_resetBuffers() (3x dedup), \_clearAllTimers() (10 timer cleanups), \_handleJsonMessage()
+  - ralph-tracker: extract completeAllTodos() (4x dedup), emitValidationWarning(), named similarity constants
+  - subagent-watcher: extract markSubagentAsCompleted(), extractFirstTextContent(), emitToolResult(), findOldestInactiveAgent()
+  - respawn-controller: extract recoveryResetToWatching(), canAutoAccept(), formatRemainingSeconds(), validatePositiveTimeout()
+  - tmux-manager: replace 15 path.includes() with UNSAFE_PATH_CHARS regex, extract buildEnvExports/buildPathExport/\_configureOpenCode helpers
+  - session-auto-ops: extract executeWhenIdle() shared retry helper, convert to options object, add validateThreshold()
+  - app.js: add \_clearTimer() (11 call sites), \_isStaleSelect(), keyboard shortcut lookup table, \_cleanupPreviousSession(), \_resetAllAppState()
+  - route-helpers: add readJsonConfig() (5 inline patterns replaced), validateSessionFilePath() (2 duplicated blocks replaced)
+
+## 0.5.2
+
+### Patch Changes
+
+- Make buffer size limits configurable via CODEMAN\_\* environment variables (MAX_TERMINAL_BUFFER, TRIM_TERMINAL_TO, MAX_TEXT_OUTPUT, TRIM_TEXT_TO, MAX_MESSAGES), falling back to existing defaults. Allows users with fewer sessions or more RAM to tune buffer sizes without patching source.
+
+  Fix duplicate terminal output on tab switch to busy sessions by clearing the terminal before writing the new buffer.
+
+  Fix stale Ink CUP frames after tab switch by sending Ctrl+L to force a clean redraw.
+
+  Fix mobile CJK input handling: resolve textarea positioning, terminal flicker during composition, and layout overflow on small screens. Improve CJK composition lifecycle with better event handling and fallback flush timers.
+
 ## 0.5.1
 
 ### Patch Changes

CLAUDE.md

@@ -6,11 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 | Task | Command |
 |------|---------|
-| Dev server | `npx tsx src/index.ts web` |
+| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
 | Type check | `tsc --noEmit` |
 | Lint | `npm run lint` (fix: `npm run lint:fix`) |
 | Format | `npm run format` (check: `npm run format:check`) |
-| Single test | `npx vitest run test/<file>.test.ts` |
+| Single test | `npm test -- test/<file>.test.ts` (or `npx vitest run --config config/vitest.config.ts test/<file>.test.ts`) — ⚠ **never** run bare `npm test`, see Testing section |
+| Build | `npm run build` (esbuild via `scripts/build.mjs`, NOT tsc — `tsc --noEmit` is type-check only) |
 | Production | `npm run build && systemctl --user restart codeman-web` |
 
 ## CRITICAL: Session Safety
@@ -29,7 +30,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM
 
-The production server caches static files for 1 year (`maxAge: '1y'` in `server.ts`). After deploying frontend changes, users may need a hard refresh (Ctrl+Shift+R) to see updates.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an *absolute* URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.
 
 ## COM Shorthand (Deployment)
 
@@ -48,11 +49,14 @@ When user says "COM":
    CHANGESET
    ```
    Replace `patch` with `minor` or `major` as needed. Include `"xterm-zerolag-input": patch` on a separate line if that package changed too.
-3. **Consume the changeset**: `npm run version-packages` (bumps versions in `package.json` files and updates `CHANGELOG.md`)
+3. **Consume the changeset**: `npm run version-packages` (auto-bumps `package.json` files, updates `CHANGELOG.md`, runs `npm install --package-lock-only`, and verifies lockfile sync via `scripts/check-lockfile-sync.mjs` — all in one command; never hand-edit `CHANGELOG.md` or `package-lock.json` versions)
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
+6. **Wait for CI**: after `git push`, find the run with `gh run list -L 1 --json databaseId,headBranch -q '.[0].databaseId'` and watch it with `gh run watch <id> --exit-status`. Confirm all checks pass before considering the release done.
 
-**Version**: 0.5.1 (must match `package.json`)
+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.9.2 (must match `package.json`)
 
 ## Project Overview
 
@@ -68,26 +72,39 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ## Additional Commands
 
-`npm run dev` = dev server. Default port: `3000`. Commands not in Quick Reference:
+`npm run dev` = dev server. Default port: `3000` (override with `--port` or the `CODEMAN_PORT` env var). To run this beta isolated alongside a prod Codeman, use `scripts/run-beta.sh` (sets `CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). Commands not in Quick Reference:
 
 | Task | Command |
 |------|---------|
 | Dev with TLS | `npx tsx src/index.ts web --https` |
+| Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix) |
+| Bind a non-loopback host | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
 | Continuous typecheck | `tsc --noEmit --watch` |
 | Test coverage | `npm run test:coverage` |
+| Dead-code sweep | `npm run knip` (config in `knip.json`) |
+| 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 `typecheck`, `lint`, `format:check` on push to master (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 (`eslint.config.js`) allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Ignores: `app.js`, `scripts/**/*.mjs`, `src/web/public/vendor/**`, `tools/**`, `remotion/**`.
+**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/**`.
 
 ## Common Gotchas
 
 - **Single-line prompts only** — `writeViaMux()` sends text+Enter separately; multi-line breaks Ink
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly
-- **Global regex `lastIndex`** — Use `createAnsiPatternFull/Simple()` factories, not shared `g`-flag patterns in loops
+- **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift
+- **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
+- **Dual-CLI prefix discipline** — Codeman supports both Claude Code and OpenCode (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward both prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
+- **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. Real bugs caused: 0.6.4 (`durationMinutes` for ∞ respawn), and the same shape pattern hit `opusContext1mEnabled` in 0.6.3
+- **`xterm-zerolag-input` is duplicated** — the local-echo overlay lives in BOTH `packages/xterm-zerolag-input/src/` (published to npm as a standalone library for external consumers — see README "Published Packages") AND inline inside `src/web/public/app.js` (runtime copy the web UI actually loads, since the page ships as plain JS without a bundler). Any change to overlay behavior MUST be applied to both, or dev and prod diverge — and a public API break in the package warrants a separate version bump for `xterm-zerolag-input` in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+- **Default bind is loopback-only; non-loopback without a password starts but warns** — since COD-29 (PR #107) the web server defaults to `--host 127.0.0.1` (was `0.0.0.0`). As of **0.9.0** binding a non-loopback host (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **no longer refuses to start — it starts and prints a loud warning** listing the fixes (set `CODEMAN_PASSWORD`, bind loopback + tunnel/`tailscale serve`, or `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` to acknowledge → terser note). Host classification is `isLoopbackBindHost()` in `network-auth-policy.ts`; the warn-vs-start logic is in `server.ts` `start()`; flags wired in `cli.ts`. ⚠️ Operational note: the production systemd unit runs `node dist/index.js web --https` with no `--host`, so it binds **localhost only** — reach it remotely via `tailscale serve`/tunnel to `127.0.0.1`, or add `Environment=CODEMAN_HOST=0.0.0.0` + `Environment=CODEMAN_PASSWORD=…` to `~/.config/systemd/user/codeman-web.service`. A loopback bind is reachable through a same-host tunnel (cloudflared/tailscale → `127.0.0.1`) but NOT by a browser hitting the box's LAN IP. Auth user defaults to `admin`. **Full model: `docs/security-architecture.md`.**
+- **Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.
 
 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
 
@@ -99,7 +116,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 |--------|-----------|-------|
 | **Entry** | `src/index.ts`, `src/cli.ts` | |
 | **Session** | `src/session.ts` ★, `src/session-manager.ts`, `src/session-auto-ops.ts`, `src/session-cli-builder.ts`, `src/session-lifecycle-log.ts`, `src/session-task-cache.ts` | |
-| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` | |
+| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★ | |
 | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
 | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
 | **Orchestrator** | `src/orchestrator-loop.ts`, `src/orchestrator-planner.ts`, `src/orchestrator-verifier.ts` | Read `docs/orchestrator-loop-architecture.md` first |
@@ -109,15 +126,15 @@ 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` (14 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` (~2.6K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 4 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`) + `sw.js` | |
-| **Types** | `src/types/index.ts` → 14 domain files | See `@fileoverview` in index.ts |
+| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (15 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
+| **Frontend** | `src/web/public/app.js` (~3.4K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | |
+| **Types** | `src/types/index.ts` (barrel) → 14 domain files; also `src/types.ts` root re-export | See `@fileoverview` in index.ts |
 
-★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in.
+★ = 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/` — 9 files. Import from specific files, not barrel.
+**Config**: `src/config/` — 10 files. Import from specific files, not barrel.
 
 **Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
 
@@ -134,9 +151,11 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
+**Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
+
 **Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`.
 
-**Agent Teams**: `TeamWatcher` polls `~/.claude/teams/`, matches to sessions via `leadSessionId`. Teammates are in-process threads appearing as subagents. Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. See `agent-teams/`.
+**Agent Teams**: `TeamWatcher` polls `~/.claude/teams/`, matches to sessions via `leadSessionId`. Teammates are in-process threads appearing as subagents. Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. See `docs/agent-teams/`.
 
 **Circuit breaker**: Prevents respawn thrashing. States: `CLOSED` → `HALF_OPEN` → `OPEN`. Reset: `/api/sessions/:id/ralph-circuit-breaker/reset`.
 
@@ -148,15 +167,24 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).
 
+**Multi-monitor button** (header, top-right; the notification bell it sits beside stays hidden — notifications live in Settings → Notifications). `app.launchMultiMonitor()` (in `panels-ui.js`) POSTs `/api/system/span-displays`, which spawns `scripts/span-codeman.sh` — a fresh, maximized browser `--app` window sized to the union of all displays (macOS; needs "Displays have separate Spaces" OFF). Supports the gesture layer's in-page floating session panels dragging across the physical monitor seam. **Opt-in:** hidden by default; enable under App Settings → Display → **Header Displays** ("Multi-monitor Button", `showMultiMonitorButton`). The button carries a `btn-multimonitor--hidden` class in the template; `renderIndexHtml` strips that class at render when the setting is on (a unique class token, not a brittle match on the aria-label/style copy), and `applyHeaderVisibilitySettings()` toggles the same class live on save. Solo (detached) windows hide it via `body.solo-mode`.
+
+**Gesture control** (the camera hand-tracking overlay) is **opt-in, default OFF**, under App Settings → Display → **Input** (`gestureControlEnabled`). `CODEMAN_GESTURE=1` makes the feature *available* on the instance (CSP widening + `/gesture/` assets) and sets `window.__codemanGestureAvailable` (the Input section only shows when set); the overlay bundle is injected by `renderIndexHtml` **only when the setting is enabled**, so that method is `async` and reads `settings.json` via `readSettings(true)` — the `true` forces a **fresh** read (bypassing the 2s `_settingsCache`), because a post-save reload happens within that TTL and the cached value would otherwise render the pre-toggle state. Toggling the setting reloads the page (the bundle is render-injected).
+
+**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+Enter (quick start), Ctrl+W (kill), Ctrl+Tab (next), Ctrl+K (kill all), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl/Cmd +/- (font).
+**Keyboard shortcuts**: Escape (close), Ctrl+? (help), Ctrl+W (kill), Ctrl+Tab (next), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font).
 
 ### Security
 
+**Full model: [`docs/security-architecture.md`](docs/security-architecture.md)** — network binding, auth pipeline, the tunnel caveat, file-serving hardening, supply-chain, instance isolation, and recommended secure setups.
+
 | Layer | Details |
 |-------|---------|
-| **Auth** | Optional HTTP Basic via `CODEMAN_USERNAME`/`CODEMAN_PASSWORD` env vars |
+| **Auth** | Optional HTTP Basic via `CODEMAN_USERNAME` (defaults to `admin`) / `CODEMAN_PASSWORD` env vars. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`) |
+| **Network bind** | Defaults to `127.0.0.1` (loopback). A non-loopback bind (`--host`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **starts but warns loudly** (0.9.0; was fail-closed in COD-29/#107). `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges the warning. Classifier: `network-auth-policy.ts` |
 | **QR Auth** | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md` |
 | **Sessions** | 24h cookie (`codeman_session`), auto-extend, device context audit |
 | **Rate limit** | 10 failed auth/IP → 429 (15min decay). QR has separate limiter |
@@ -167,11 +195,11 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### SSE Event Registry
 
-~106 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
+~120 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
 
 ### API Routes
 
-~124 handlers across 14 route files in `src/web/routes/`: system (36), sessions (25), orchestrator (10), ralph (9), plan (8), respawn (7), cases (7), files (5), mux (5), scheduled (4), push (4), teams (2), hooks (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~130 handlers across 15 route files in `src/web/routes/`: system (37, incl. `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (5), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 ## Adding Features
 
@@ -193,22 +221,20 @@ All in `~/.codeman/`: `state.json` (sessions, settings, respawn), `mux-sessions.
 **CRITICAL: You are running inside a Codeman-managed tmux session.** Never run `npx vitest run` (full suite) — it spawns/kills tmux sessions and will crash your own session. Only run individual files:
 
 ```bash
-npx vitest run test/<specific-file>.test.ts     # Single file (SAFE)
-npx vitest run -t "pattern"                      # By name (SAFE)
-# npx vitest run                                 # DANGEROUS — DON'T DO THIS
+npm test -- test/<specific-file>.test.ts         # Single file (SAFE, uses config/vitest.config.ts)
+npm test -- -t "pattern"                          # By name (SAFE)
+# npm test                                        # DANGEROUS — runs full suite, DON'T DO THIS
 ```
 
+Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pass `--config config/vitest.config.ts`.
+
 **Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s.
 
 **Safety**: `test/setup.ts` snapshots pre-existing tmux sessions and never kills them. Only `registerTestTmuxSession()` sessions get cleaned up.
 
 **Ports**: Pick unique ports manually. Search `const PORT =` before adding new tests.
 
-**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject()` in `test/routes/`. **Mobile tests**: Playwright suite in `mobile-test/` (135 device profiles).
-
-## Screenshots
-
-Mobile screenshots in `~/.codeman/screenshots/`. API: `GET /api/screenshots`, `POST /api/screenshots`.
+**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles).
 
 ## Debugging
 
@@ -220,27 +246,14 @@ curl localhost:3000/api/subagents | jq             # Background agents
 cat ~/.codeman/state.json | jq                     # Persisted state
 ```
 
+Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/screenshots`.
+
 ## Performance & Limits
 
 Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 2MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
 
-## References
+**Memory leaks (24+ hour sessions)**: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 
-Deep-dive docs in `docs/`: `respawn-state-machine.md`, `ralph-wiggum-guide.md`, `claude-code-hooks-reference.md`, `terminal-anti-flicker.md`, `opencode-integration.md`, `qr-auth-plan.md`, `orchestrator-loop-architecture.md`, `browser-testing-guide.md`. Agent Teams: `agent-teams/README.md`. SSE events: `src/web/sse-events.ts` + `constants.js`.
+## Scripts & Tunnel
 
-## Scripts
-
-Key: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh` (tunnel start/stop/url). Production: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`.
-
-## Memory Leak Prevention
-
-24+ hour sessions: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Verify: `npx vitest run test/memory-leak-prevention.test.ts`.
-
-## Common Workflows
-
-**Bug investigation**: Dev server → reproduce in browser → check terminal + `~/.codeman/state.json`.
-**Respawn changes**: Read `docs/respawn-state-machine.md` first. Use `MockSession` from `test/respawn-test-utils.ts`.
-
-## Tunnel
-
-`./scripts/tunnel.sh start|stop|url`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.
+Key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh start|stop|url` (tunnel). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

README.md

@@ -30,24 +30,6 @@ curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | b
 
 This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it.
 
-**Install from a fork or specific branch:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/<user>/Codeman/<branch>/install.sh | \
-  CODEMAN_REPO_URL=https://github.com/<user>/Codeman.git \
-  CODEMAN_BRANCH=<branch> bash
-```
-
-The installer supports these environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CODEMAN_REPO_URL` | upstream Codeman | Custom git repository URL |
-| `CODEMAN_BRANCH` | `master` | Git branch to install |
-| `CODEMAN_INSTALL_DIR` | `~/.codeman/app` | Custom install directory |
-| `CODEMAN_SKIP_SYSTEMD` | `0` | Skip systemd service setup prompt |
-| `CODEMAN_NODE_VERSION` | `22` | Node.js major version to install |
-| `CODEMAN_NONINTERACTIVE` | `0` | Skip all prompts (for CI/automation) |
-
 You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai) (or both). After install:
 
 ```bash
@@ -60,12 +42,53 @@ codeman web
 
 **Linux (systemd):**
 ```bash
-mkdir -p ~/.config/systemd/user && printf '[Unit]\nDescription=Codeman Web Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=%s %s/dist/index.js web\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=default.target\n' "$(which node)" "$HOME/.codeman/app" > ~/.config/systemd/user/codeman-web.service && systemctl --user daemon-reload && systemctl --user enable --now codeman-web && loginctl enable-linger $USER
+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 && printf '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>com.codeman.web</string><key>ProgramArguments</key><array><string>%s</string><string>%s/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>\n' "$(which node)" "$HOME/.codeman/app" > ~/Library/LaunchAgents/com.codeman.web.plist && launchctl load ~/Library/LaunchAgents/com.codeman.web.plist
+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>
 
@@ -203,6 +226,17 @@ Run **20 parallel sessions** with full visibility — real-time xterm.js termina
 
 Every session runs inside **tmux** — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Managed sessions are environment-tagged so the agent won't kill its own session.
 
+### Hostname-Aware Window Title
+
+Running Codeman on multiple hosts (laptop, dev box, NAS)? The browser tab title is `codeman:<hostname>` so you can tell which backend each tab points at without clicking in:
+
+```bash
+codeman web                                # codeman:<os.hostname()>
+codeman web --title-hostname dev-box       # codeman:dev-box (manual override for noisy hostnames)
+```
+
+The title is templated into the served HTML on first byte, so it's correct from the very first paint and works without JavaScript. The same hostname prefix is applied to the tab-flash format (`⚠️ (N) codeman:<host>`) and to OS-level desktop notifications (`codeman:<host>: <event>`), so cross-host alerts in the system notification center are also unambiguous.
+
 ### Smart Token Management
 
 | Threshold | Action | Result |
@@ -378,9 +412,12 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 | `Ctrl+Enter` | Quick-start session |
 | `Ctrl+W` | Close session |
 | `Ctrl+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+Shift+R` | Restore terminal size |
+| `Ctrl+Shift+V` | Toggle voice input |
 | `Ctrl/Cmd +/-` | Font size |
 | `Escape` | Close panels |
 
@@ -423,6 +460,7 @@ 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 |
+| `POST` | `/api/clipboard` | Push text to all connected browsers (`{text}`) |
 | `GET` | `/api/sessions/:id/run-summary` | Timeline + stats |
 
 ---

config/eslint.config.js

@@ -22,8 +22,7 @@ export default tseslint.config(
       'src/web/public/vendor/**',
       'src/web/public/app.js',
       'scripts/**/*.mjs',
-      'tools/**',
-      'remotion/**',
+      'scripts/remotion/**',
     ],
   }
 );

config/vitest.config.ts

@@ -1,7 +1,11 @@
+import { resolve } from 'node:path';
 import { defineConfig } from 'vitest/config';
 
+const root = resolve(import.meta.dirname, '..');
+
 export default defineConfig({
   test: {
+    root,
     globals: true,
     environment: 'node',
     include: ['test/**/*.test.ts'],

docs/archive/cleanup-findings.md

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

docs/archive/code-structure-findings.md

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

docs/local-echo-overlay-plan.md

@@ -1,5 +1,7 @@
 # Local Echo Overlay — Implementation Plan
 
+> **Status: SHIPPED.** Implementation lives in `packages/xterm-zerolag-input/src/` (overlay-renderer.ts, prompt-finder.ts, cell-dimensions.ts, zerolag-input-addon.ts) with the embedded copy in `src/web/public/app.js`. This document is retained as historical design context.
+
 ## Context
 
 User accesses Codeman remotely from Thailand to Switzerland over Tailscale (~200-300ms RTT).
@@ -18,9 +20,9 @@ redraws. A DOM overlay sits in a separate rendering layer (z-index 7) and doesn'
 with Ink's cursor management or screen redraws at all. When Ink redraws (server output arrives),
 we simply hide the overlay.
 
-**Why it will look indistinguishable:** We use the DOM renderer (not canvas/WebGL) in our
-xterm.js v5.3.0, so both terminal text and overlay text are rendered by the same browser
-font engine with identical sub-pixel rendering.
+**Why it will look indistinguishable:** We use the DOM renderer (not canvas/WebGL), so both
+terminal text and overlay text are rendered by the same browser font engine with identical
+sub-pixel rendering. (Originally designed against xterm.js v5.3.0; project now on `@xterm/xterm` ^6.0.0 — the internal `_core._renderService.dimensions` access path still works in v6.)
 
 ## Key Technical Details (from research)
 
@@ -36,7 +38,7 @@ const top  = cursorY * dims.css.cell.height;  // CSS pixels, relative to .xterm-
 - `cursorY` = `terminal.buffer.active.cursorY` (0 to terminal.rows-1, ALREADY viewport-relative)
 - No scroll offset math needed
 
-### Cell Dimensions (v5.3.0 — no public API, use internal)
+### Cell Dimensions (no public API in v5/v6 — use internal; public in v7+)
 ```js
 const dims = terminal._core._renderService.dimensions;
 dims.css.cell.width   // e.g., 8.4px

docs/security-architecture.md

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

install.sh

@@ -7,7 +7,7 @@
 # Environment variables:
 #   CODEMAN_NONINTERACTIVE=1  - Skip all prompts (for CI/automation)
 #   CODEMAN_INSTALL_DIR       - Custom install directory (default: ~/.codeman/app)
-#   CODEMAN_SKIP_SYSTEMD=1    - Skip systemd service setup prompt
+#   CODEMAN_SKIP_SYSTEMD=1    - Skip systemd/launchd service setup prompt
 #   CODEMAN_NODE_VERSION      - Node.js major version to install (default: 22)
 #   CODEMAN_REPO_URL          - Custom git repository URL (default: upstream Codeman)
 #   CODEMAN_BRANCH            - Git branch to install (default: master)
@@ -353,8 +353,15 @@ ensure_sudo() {
         die "sudo is required but not installed. Please install packages manually or run as root."
     fi
     # Validate sudo access
-    if ! sudo -v 2>/dev/null; then
-        die "Failed to obtain sudo privileges."
+    # When piped (curl | bash), stdin is the pipe — redirect from /dev/tty so sudo can prompt
+    if [[ -e /dev/tty ]]; then
+        if ! sudo -v 2>/dev/null < /dev/tty; then
+            die "Failed to obtain sudo privileges."
+        fi
+    else
+        if ! sudo -v 2>/dev/null; then
+            die "Failed to obtain sudo privileges. Try running the script directly instead of piping."
+        fi
     fi
 }
 
@@ -372,7 +379,12 @@ ensure_homebrew() {
     fi
 
     info "Installing Homebrew first..."
-    /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    # When piped (curl | bash), stdin is the pipe — Homebrew needs TTY for sudo password prompt
+    if [[ -e /dev/tty ]]; then
+        /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" < /dev/tty
+    else
+        NONINTERACTIVE=1 /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    fi
 
     # Add Homebrew to PATH for Apple Silicon
     if [[ -f /opt/homebrew/bin/brew ]]; then
@@ -787,9 +799,84 @@ setup_sc_alias() {
 }
 
 # ============================================================================
-# Systemd Service Setup (Linux only)
+# Service Setup (Linux systemd / macOS launchd)
 # ============================================================================
 
+setup_launchd_service() {
+    local plist_label="com.codeman.web"
+    local agent_dir="$HOME/Library/LaunchAgents"
+    local agent_plist="$agent_dir/$plist_label.plist"
+    local daemon_plist="/Library/LaunchDaemons/$plist_label.plist"
+
+    info "Setting up macOS LaunchAgent..."
+
+    # Remove any existing LaunchDaemon (system-level) to prevent duplicates.
+    # We standardize on LaunchAgent (user-level) — it doesn't require sudo,
+    # inherits the user's environment, and is the correct choice for user apps.
+    if [[ -f "$daemon_plist" ]]; then
+        warn "Found system-level LaunchDaemon at $daemon_plist — removing to prevent duplicate"
+        sudo launchctl unload "$daemon_plist" 2>/dev/null || true
+        sudo rm -f "$daemon_plist"
+        success "Removed duplicate LaunchDaemon"
+    fi
+
+    # Unload existing agent before overwriting
+    if [[ -f "$agent_plist" ]]; then
+        launchctl unload "$agent_plist" 2>/dev/null || true
+    fi
+
+    mkdir -p "$agent_dir"
+
+    # Build PATH: ensure /opt/homebrew/bin (Apple Silicon) and ~/.local/bin are included
+    local svc_path="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+    # Find node binary path
+    local node_path
+    node_path=$(command -v node)
+
+    cat > "$agent_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>$plist_label</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$node_path</string>
+    <string>$INSTALL_DIR/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>$svc_path</string>
+    <key>HOME</key>
+    <string>$HOME</string>
+    <key>LANG</key>
+    <string>en_US.UTF-8</string>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>$HOME</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+
+    launchctl load "$agent_plist" 2>/dev/null || true
+
+    success "LaunchAgent installed and started"
+}
+
 setup_systemd_service() {
     local service_dir="$HOME/.config/systemd/user"
     local service_file="$service_dir/codeman-web.service"
@@ -1139,17 +1226,25 @@ main() {
     echo ""
 
     local launch_choice=""
-    local has_systemd=false
+    local has_service=false
+    local service_type=""
 
     if [[ "$os" == "linux" ]] && [[ "$SKIP_SYSTEMD" != "1" ]] && command -v systemctl &>/dev/null; then
-        has_systemd=true
+        has_service=true
+        service_type="systemd"
+    elif [[ "$os" == "macos" ]] && [[ "$SKIP_SYSTEMD" != "1" ]]; then
+        has_service=true
+        service_type="launchd"
     fi
 
-    if [[ "$has_systemd" == "true" ]]; then
+    if [[ "$has_service" == "true" ]]; then
+        local service_label="systemd service"
+        [[ "$service_type" == "launchd" ]] && service_label="LaunchAgent"
+
         echo -e "  ${BOLD}How would you like to run Codeman?${NC}"
         echo ""
         echo -e "    ${CYAN}1)${NC} Run now in this terminal"
-        echo -e "    ${CYAN}2)${NC} Install as systemd service (auto-start on boot)"
+        echo -e "    ${CYAN}2)${NC} Install as $service_label (auto-start on boot)"
         echo -e "    ${CYAN}3)${NC} Don't start — I'll run it later"
         echo ""
 
@@ -1166,7 +1261,7 @@ main() {
             done
         fi
     else
-        # macOS or no systemd — only offer run now or skip
+        # No service manager available — only offer run now or skip
         echo -e "  ${BOLD}Would you like to start Codeman now?${NC}"
         echo ""
         echo -e "    ${CYAN}1)${NC} Run now in this terminal"
@@ -1192,12 +1287,16 @@ main() {
 
     echo ""
 
-    # Handle systemd setup
+    # Handle service setup
     if [[ "$launch_choice" == "2" ]]; then
-        setup_systemd_service
+        if [[ "$service_type" == "launchd" ]]; then
+            setup_launchd_service
+        else
+            setup_systemd_service
+        fi
 
-        # Offer tunnel service if cloudflared is available
-        if check_cloudflared && [[ -f "$INSTALL_DIR/scripts/codeman-tunnel.service" ]]; then
+        # Offer tunnel service if cloudflared is available (Linux only — systemd tunnel service)
+        if [[ "$service_type" == "systemd" ]] && check_cloudflared && [[ -f "$INSTALL_DIR/scripts/codeman-tunnel.service" ]]; then
             echo ""
             if prompt_yes_no "Also set up Cloudflare tunnel service? (requires CODEMAN_PASSWORD)" "n"; then
                 setup_tunnel_service
@@ -1212,10 +1311,16 @@ main() {
         echo ""
         echo -e "  ${BOLD}Manage the service:${NC}"
         echo ""
-        echo -e "    ${CYAN}systemctl --user stop codeman-web${NC}    # Stop"
-        echo -e "    ${CYAN}systemctl --user restart codeman-web${NC} # Restart"
-        echo -e "    ${CYAN}systemctl --user status codeman-web${NC}  # Check status"
-        echo -e "    ${CYAN}journalctl --user -u codeman-web -f${NC}  # View logs"
+        if [[ "$service_type" == "launchd" ]]; then
+            echo -e "    ${CYAN}launchctl unload ~/Library/LaunchAgents/com.codeman.web.plist${NC}   # Stop"
+            echo -e "    ${CYAN}launchctl load ~/Library/LaunchAgents/com.codeman.web.plist${NC}     # Start"
+            echo -e "    ${CYAN}tail -f /tmp/codeman.log${NC}                                        # View logs"
+        else
+            echo -e "    ${CYAN}systemctl --user stop codeman-web${NC}    # Stop"
+            echo -e "    ${CYAN}systemctl --user restart codeman-web${NC} # Restart"
+            echo -e "    ${CYAN}systemctl --user status codeman-web${NC}  # Check status"
+            echo -e "    ${CYAN}journalctl --user -u codeman-web -f${NC}  # View logs"
+        fi
         echo ""
     fi
 
@@ -1289,11 +1394,17 @@ update() {
     success "Updated to $(node -e "console.log(require('./package.json').version)")"
     echo ""
 
-    # Auto-restart systemd service if it's running, otherwise tell the user
-    if systemctl --user is-active codeman-web.service &>/dev/null; then
+    # Auto-restart service if running, otherwise tell the user
+    local agent_plist="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+    if systemctl --user is-active codeman-web.service &>/dev/null 2>&1; then
         info "Restarting codeman-web service..."
         systemctl --user restart codeman-web.service
         success "codeman-web service restarted"
+    elif [[ -f "$agent_plist" ]]; then
+        info "Restarting LaunchAgent..."
+        launchctl unload "$agent_plist" 2>/dev/null || true
+        launchctl load "$agent_plist" 2>/dev/null || true
+        success "LaunchAgent restarted"
     else
         echo -e "  ${DIM}Restart codeman web to use the new version:${NC}"
         echo -e "    ${CYAN}pkill -f 'codeman.*web'; codeman web &${NC}"
@@ -1306,9 +1417,9 @@ uninstall() {
     info "Uninstalling Codeman..."
     echo ""
 
-    # Stop and remove systemd services
+    # Stop and remove systemd services (Linux)
     for svc in codeman-web codeman-tunnel; do
-        if systemctl --user is-active "${svc}.service" &>/dev/null; then
+        if systemctl --user is-active "${svc}.service" &>/dev/null 2>&1; then
             info "Stopping ${svc} service..."
             systemctl --user stop "${svc}.service"
         fi
@@ -1324,6 +1435,20 @@ uninstall() {
     done
     systemctl --user daemon-reload 2>/dev/null || true
 
+    # Stop and remove launchd services (macOS)
+    local agent_plist="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+    local daemon_plist="/Library/LaunchDaemons/com.codeman.web.plist"
+    if [[ -f "$agent_plist" ]]; then
+        launchctl unload "$agent_plist" 2>/dev/null || true
+        rm -f "$agent_plist"
+        success "Removed LaunchAgent"
+    fi
+    if [[ -f "$daemon_plist" ]]; then
+        sudo launchctl unload "$daemon_plist" 2>/dev/null || true
+        sudo rm -f "$daemon_plist"
+        success "Removed LaunchDaemon"
+    fi
+
     # Remove symlinks
     local symlink_dir="$HOME/.local/bin"
     if [[ -L "$symlink_dir/codeman" ]]; then

knip.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "scripts/*.mjs",
+    "scripts/*.js",
+    "scripts/watch-subagents.ts",
+    "scripts/remotion/Root.tsx",
+    "scripts/remotion/index.ts",
+    "test/**/*.test.ts",
+    "test/mobile/vitest.config.ts",
+    "test/**/*.mjs"
+  ],
+  "project": ["src/**/*.{ts,tsx}", "scripts/**/*.{ts,tsx,mjs,js}", "test/**/*.{ts,mjs}"],
+  "ignoreExportsUsedInFile": true,
+  "ignoreDependencies": ["@remotion/cli", "@remotion/transitions", "esbuild", "agent-browser"]
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.5.1",
+  "version": "0.9.2",
   "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -11,21 +11,25 @@
   "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",
     "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test": "vitest run --config config/vitest.config.ts",
+    "test:watch": "vitest --config config/vitest.config.ts",
+    "test:coverage": "vitest run --config config/vitest.config.ts --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint 'src/**/*.ts'",
-    "lint:fix": "eslint 'src/**/*.ts' --fix",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
+    "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' '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",
+    "version-packages": "changeset version && npm install --package-lock-only && node scripts/check-lockfile-sync.mjs",
+    "check:lockfile": "node scripts/check-lockfile-sync.mjs",
+    "knip": "npx --yes knip@latest",
     "release": "changeset publish"
   },
   "workspaces": [
@@ -50,7 +54,8 @@
   "dependencies": {
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
-    "@fastify/static": "^8.0.0",
+    "@fastify/multipart": "^10.0.0",
+    "@fastify/static": "^9.1.3",
     "@fastify/websocket": "^11.2.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-unicode11": "^0.9.0",
@@ -59,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",
@@ -78,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",
@@ -87,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"
   }
 }

public

@@ -1 +0,0 @@
-tools/remotion/public

scripts/browser-comparison.mjs

@@ -19,6 +19,10 @@ const PORTS = {
 
 const results = [];
 
+function isCodemanTitle(title) {
+  return typeof title === 'string' && title.startsWith('codeman:');
+}
+
 function logSection(title) {
   console.log('\n' + '='.repeat(60));
   console.log(`  ${title}`);
@@ -88,7 +92,7 @@ async function main() {
       const page = await playwrightBrowser.newPage();
       await page.goto(`http://localhost:${PORTS.playwright}`);
       const title = await page.title();
-      if (title !== 'Codeman') throw new Error(`Expected Codeman, got ${title}`);
+      if (!isCodemanTitle(title)) throw new Error(`Expected codeman:<hostname>, got ${title}`);
       await page.close();
     });
 
@@ -149,7 +153,7 @@ async function main() {
       const page = await puppeteerBrowser.newPage();
       await page.goto(`http://localhost:${PORTS.puppeteer}`);
       const title = await page.title();
-      if (title !== 'Codeman') throw new Error(`Expected Codeman, got ${title}`);
+      if (!isCodemanTitle(title)) throw new Error(`Expected codeman:<hostname>, got ${title}`);
       await page.close();
     });
 
@@ -202,7 +206,7 @@ async function main() {
     agentBrowser(`open http://localhost:${PORTS.agentBrowser}`);
     await new Promise(r => setTimeout(r, 2000));
     const title = agentBrowserJson('get title');
-    agentBrowserAvailable = title.title === 'Codeman';
+    agentBrowserAvailable = isCodemanTitle(title.title);
     console.log('  Browser launched');
 
     // Test 1: Page load
@@ -210,7 +214,7 @@ async function main() {
       agentBrowser(`open http://localhost:${PORTS.agentBrowser}`);
       await new Promise(r => setTimeout(r, 1000));
       const title = agentBrowserJson('get title');
-      if (title.title !== 'Codeman') throw new Error(`Expected Codeman, got ${title.title}`);
+      if (!isCodemanTitle(title.title)) throw new Error(`Expected codeman:<hostname>, got ${title.title}`);
     });
 
     // Test 2: Element selection

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

@@ -32,6 +32,12 @@ run('chmod dist/index.js', 'chmod +x dist/index.js');
 // 2. Copy static assets (clean first to remove stale hashed files from previous builds)
 run('clean public', 'rm -rf dist/web/public');
 run('prepare dirs', 'mkdir -p dist/web dist/templates dist/web/public/vendor');
+// Fetch the opt-in gesture overlay's MediaPipe wasm + model into src/ (idempotent,
+// non-fatal, kept out of git) so the copy below carries them into dist/.
+run('gesture assets', 'node scripts/fetch-gesture-assets.mjs');
+// 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/');
 
@@ -93,6 +99,7 @@ console.log('\n[build] content-hash cache busting');
     'ralph-wizard.js',
     'api-client.js',
     'subagent-windows.js',
+    'image-input.js',
     'vendor/xterm-zerolag-input.js',
   ];
   const manifest = {};

scripts/capture-readme-screenshots.mjs

@@ -428,7 +428,7 @@ const SUBAGENT_ACTIVITY = {
   'agent-002': [
     { type: 'tool', tool: 'Glob', input: { pattern: 'test/**/*.test.ts' }, timestamp: new Date().toISOString(), agentId: 'agent-002' },
     { type: 'tool', tool: 'Read', input: { file_path: '/home/arkon/codeman/test/respawn-test-utils.ts' }, timestamp: new Date().toISOString(), agentId: 'agent-002' },
-    { type: 'tool', tool: 'Read', input: { file_path: '/home/arkon/codeman/vitest.config.ts' }, timestamp: new Date().toISOString(), agentId: 'agent-002' },
+    { type: 'tool', tool: 'Read', input: { file_path: '/home/arkon/codeman/config/vitest.config.ts' }, timestamp: new Date().toISOString(), agentId: 'agent-002' },
     { type: 'message', role: 'assistant', text: 'Analyzing test patterns: MockSession, unique ports, fileParallelism: false...', timestamp: new Date().toISOString(), agentId: 'agent-002' },
   ],
 };

scripts/capture-video-screenshots.mjs

@@ -9,7 +9,7 @@
  *
  * Usage:  node scripts/capture-video-screenshots.mjs
  * Port:   3198 (static file server)
- * Output: remotion/public/ (6 PNGs)
+ * Output: scripts/scripts/remotion/public/ (6 PNGs)
  */
 
 import { chromium } from 'playwright';
@@ -21,7 +21,7 @@ import { fileURLToPath } from 'url';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const PROJECT_ROOT = join(__dirname, '..');
 const PUBLIC_DIR = join(PROJECT_ROOT, 'src', 'web', 'public');
-const OUTPUT_DIR = join(PROJECT_ROOT, 'remotion', 'public');
+const OUTPUT_DIR = join(PROJECT_ROOT, 'scripts', 'remotion', 'public');
 const PORT = 3198;
 
 const DESKTOP_VIEWPORT = { width: 1920, height: 1080 };
@@ -516,7 +516,7 @@ async function captureDesktopWelcome(browser) {
       path: join(OUTPUT_DIR, 'desktop-welcome.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/desktop-welcome.png');
+    console.log('  Saved: scripts/remotion/public/desktop-welcome.png');
   } finally {
     await context.close();
   }
@@ -545,7 +545,7 @@ async function captureDesktopClaude(browser) {
       path: join(OUTPUT_DIR, 'desktop-claude.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/desktop-claude.png');
+    console.log('  Saved: scripts/remotion/public/desktop-claude.png');
   } finally {
     await context.close();
   }
@@ -575,7 +575,7 @@ async function captureDesktopBothClaude(browser) {
       path: join(OUTPUT_DIR, 'desktop-both-claude.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/desktop-both-claude.png');
+    console.log('  Saved: scripts/remotion/public/desktop-both-claude.png');
   } finally {
     await context.close();
   }
@@ -605,7 +605,7 @@ async function captureDesktopBothOpencode(browser) {
       path: join(OUTPUT_DIR, 'desktop-both-opencode.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/desktop-both-opencode.png');
+    console.log('  Saved: scripts/remotion/public/desktop-both-opencode.png');
   } finally {
     await context.close();
   }
@@ -634,7 +634,7 @@ async function captureMobileClaude(browser) {
       path: join(OUTPUT_DIR, 'mobile-claude.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/mobile-claude.png');
+    console.log('  Saved: scripts/remotion/public/mobile-claude.png');
   } finally {
     await context.close();
   }
@@ -663,7 +663,7 @@ async function captureMobileOpencode(browser) {
       path: join(OUTPUT_DIR, 'mobile-opencode.png'),
       fullPage: false,
     });
-    console.log('  Saved: remotion/public/mobile-opencode.png');
+    console.log('  Saved: scripts/remotion/public/mobile-opencode.png');
   } finally {
     await context.close();
   }
@@ -706,12 +706,12 @@ async function main() {
     console.log('All 6 screenshots captured!');
     console.log('='.repeat(60));
     console.log('\nOutput files:');
-    console.log('  remotion/public/desktop-welcome.png');
-    console.log('  remotion/public/desktop-claude.png');
-    console.log('  remotion/public/desktop-both-claude.png');
-    console.log('  remotion/public/desktop-both-opencode.png');
-    console.log('  remotion/public/mobile-claude.png');
-    console.log('  remotion/public/mobile-opencode.png');
+    console.log('  scripts/remotion/public/desktop-welcome.png');
+    console.log('  scripts/remotion/public/desktop-claude.png');
+    console.log('  scripts/remotion/public/desktop-both-claude.png');
+    console.log('  scripts/remotion/public/desktop-both-opencode.png');
+    console.log('  scripts/remotion/public/mobile-claude.png');
+    console.log('  scripts/remotion/public/mobile-opencode.png');
   } catch (err) {
     console.error('\nFatal error:', err.message);
     console.error(err.stack);

scripts/check-lockfile-sync.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Fails if package-lock.json's version fields don't match package.json.
+// Changesets bumps package.json but NOT the lockfile — this catches that drift
+// (the top-level `version` in lockfiles is metadata, so `npm ci` won't flag it).
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8'));
+const lock = JSON.parse(readFileSync(resolve(repoRoot, 'package-lock.json'), 'utf8'));
+
+const expected = pkg.version;
+const rootVersion = lock.version;
+const selfVersion = lock.packages?.['']?.version;
+
+const mismatches = [];
+if (rootVersion !== expected) mismatches.push(`  package-lock.json#.version = ${rootVersion} (expected ${expected})`);
+if (selfVersion !== expected) mismatches.push(`  package-lock.json#.packages[""].version = ${selfVersion} (expected ${expected})`);
+
+if (mismatches.length > 0) {
+  console.error(`\nLockfile version drift detected (package.json is ${expected}):`);
+  console.error(mismatches.join('\n'));
+  console.error('\nFix: run `npm install --package-lock-only` and commit the updated package-lock.json.\n');
+  process.exit(1);
+}
+
+console.log(`Lockfile in sync with package.json (${expected}).`);

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-tunnel-named.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=Codeman Cloudflare Named Tunnel
+After=network-online.target codeman-web.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/cloudflared tunnel --config %h/.cloudflared/codeman.yml run codeman
+Restart=always
+RestartSec=5
+KillMode=process
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=codeman-tunnel-named
+
+[Install]
+WantedBy=default.target

scripts/codeman-web.service

@@ -12,6 +12,14 @@ KillMode=process
 Environment=NODE_ENV=production
 Environment=HOME=/home/arkon
 Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache
+# 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/fetch-gesture-assets.mjs

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

scripts/postinstall.js

@@ -312,6 +312,20 @@ if (isGlobalInstall) {
     }
 }
 
+// ----------------------------------------------------------------------------
+// 4b. Fetch gesture-overlay runtime assets (MediaPipe wasm + model) for dev mode
+//     (src/web/public/gesture/). Opt-in feature (CODEMAN_GESTURE=1); non-fatal.
+//     Large binaries kept out of git; the build copies them into dist/.
+// ----------------------------------------------------------------------------
+
+if (!isGlobalInstall) {
+    try {
+        execSync(`node "${join(import.meta.dirname, 'fetch-gesture-assets.mjs')}"`, { stdio: 'inherit' });
+    } catch {
+        // Non-fatal — the gesture overlay is opt-in.
+    }
+}
+
 // ----------------------------------------------------------------------------
 // 5. Install git pre-commit hook (format check)
 // ----------------------------------------------------------------------------
@@ -446,3 +460,16 @@ if (process.env.CI || process.env.CODEMAN_NO_AUTOSTART) {
         }
     }
 }
+
+// ----------------------------------------------------------------------------
+// Security note — printed on every install path
+// ----------------------------------------------------------------------------
+
+console.log(colors.bold('Security:'));
+console.log(colors.dim('  Codeman binds ') + colors.cyan('127.0.0.1') + colors.dim(' (this machine only) — no password needed by default.'));
+console.log(colors.dim('  To reach it from another device, do ONE of:'));
+console.log(colors.dim('    • ') + colors.cyan('tailscale serve') + colors.dim(' / ') + colors.cyan('cloudflared tunnel') + colors.dim('   (recommended), or'));
+console.log(colors.dim('    • ') + colors.cyan('codeman web --host 0.0.0.0') + colors.dim('  AND set ') + colors.cyan('CODEMAN_PASSWORD'));
+console.log(colors.dim('  A non-loopback bind without a password still starts, but warns loudly.'));
+console.log(colors.dim('  Details: docs/security-architecture.md'));
+console.log('');

scripts/run-beta.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# run-beta.sh — launch a BETA Codeman isolated from a production instance.
+#
+# Codeman's data dir (~/.codeman) and tmux socket (-L codeman) are process-wide
+# and shared by every instance on the machine. The code now DEFAULTS to that
+# production layout on port 3000 (safe for master / existing installs), so a beta
+# build no longer isolates itself automatically — this wrapper opts it in:
+#
+#   CODEMAN_INSTANCE=beta  → data dir ~/.codeman-beta + tmux socket codeman-beta
+#   CODEMAN_PORT=5000      → listen on 5000 instead of 3000
+#
+# Result: the beta runs side-by-side with prod and can never discover/attach to
+# prod's live tmux sessions or clobber prod's state.json. Override either var to
+# run additional named instances, e.g. CODEMAN_INSTANCE=foo CODEMAN_PORT=5050.
+#
+# Usage:  ./scripts/run-beta.sh [extra `codeman web` flags]
+# Build first (the beta runs the compiled dist):  npm run build
+
+set -euo pipefail
+
+export CODEMAN_INSTANCE="${CODEMAN_INSTANCE:-beta}"
+export CODEMAN_PORT="${CODEMAN_PORT:-5000}"
+
+DIST="$(cd "$(dirname "$0")/.." && pwd)/dist/index.js"
+if [ ! -f "$DIST" ]; then
+  echo "dist not found at $DIST — run 'npm run build' first." >&2
+  exit 1
+fi
+
+echo "Starting beta Codeman: instance='$CODEMAN_INSTANCE' (~/.codeman-$CODEMAN_INSTANCE, -L codeman-$CODEMAN_INSTANCE) on port $CODEMAN_PORT"
+exec node "$DIST" web "$@"

scripts/span-codeman.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+#
+# span-codeman.sh — open a Codeman window stretched across ALL displays, so that
+# in-page floating session panels can be dragged from one physical monitor to
+# the other. Spawned by the header "multi-monitor" button (POST
+# /api/system/span-displays), or run by hand at the desk.
+#
+# ── PREREQUISITE (one-time, manual) ──────────────────────────────────────────
+# System Settings → Desktop & Dock → turn OFF "Displays have separate Spaces",
+# then LOG OUT and back in. Until you do, macOS keeps every window on a single
+# display and this script's window will clamp to one monitor instead of spanning.
+# (Equivalent CLI: `defaults write com.apple.spaces spans-displays -bool true`,
+#  still needs a re-login. Revert with `-bool false`.)
+#
+# Why a maximized --app window and not fullscreen: browser fullscreen is
+# per-display and will NOT span. We size a windowed app to the union of all
+# displays instead. macOS only.
+#
+# ── 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}"
+
+# Union rect of all displays in top-left-origin points — exactly what Chromium's
+# --window-position/--window-size expect. Finder's desktop window bounds already
+# encloses every monitor (and handles a monitor placed left/above via a negative
+# origin), so no per-display math or coordinate flipping is needed.
+bounds=$(osascript -e 'tell application "Finder" to get bounds of window of desktop')
+X=$(echo "$bounds" | awk -F', *' '{print $1}')
+Y=$(echo "$bounds" | awk -F', *' '{print $2}')
+R=$(echo "$bounds" | awk -F', *' '{print $3}')
+B=$(echo "$bounds" | awk -F', *' '{print $4}')
+W=$((R - X))
+H=$((B - Y))
+echo "Display union: position ${X},${Y}  size ${W}x${H}"
+
+# Pick a Chromium-family browser. Brave leads the list — plain Google Chrome
+# bounced when launched this way on the desk machine (created its profile then
+# exited without a window). Force a specific one with, e.g.,
+# BROWSER="Google Chrome" ./span-codeman.sh
+app="${BROWSER:-}"
+if [ -z "$app" ]; then
+  for c in "Brave Browser" "Google Chrome" "Google Chrome Beta" "Chromium" "Microsoft Edge"; do
+    [ -x "/Applications/$c.app/Contents/MacOS/$c" ] && app="$c" && break
+  done
+fi
+bin="/Applications/$app.app/Contents/MacOS/$app"
+[ -n "$app" ] && [ -x "$bin" ] || { echo "No Chrome-family browser found (BROWSER='$app')" >&2; exit 1; }
+
+# A dedicated, PER-BROWSER profile forces a FRESH instance — an already-running
+# browser would hand the URL to itself and silently ignore the geometry flags.
+# Per-browser so a Chrome-made profile can't confuse Brave (or vice-versa).
+slug=$(echo "$app" | tr '[:upper:] ' '[:lower:]-')
+profile="$HOME/.codeman-gesture-$slug"
+
+echo "Browser: $bin"
+echo "URL:     $URL"
+
+# Detach so the caller (terminal / web server) isn't blocked for the window's life.
+nohup "$bin" \
+  --app="$URL" \
+  --user-data-dir="$profile" \
+  --window-position="${X},${Y}" \
+  --window-size="${W},${H}" \
+  --no-first-run \
+  --no-default-browser-check \
+  >/dev/null 2>&1 &
+
+echo "Launched spanning window (pid $!)."
+echo "If it filled only one monitor, the 'separate Spaces' prerequisite above"
+echo "isn't active yet — toggle it off, log out/in, and re-run."

scripts/tmux-chooser.sh

@@ -32,6 +32,13 @@ set -e
 CODEMAN_STATE="$HOME/.codeman/state.json"
 CODEMAN_SESSIONS="$HOME/.codeman/mux-sessions.json"
 
+# Dedicated tmux socket all Codeman sessions live on. MUST match
+# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
+# otherwise list-sessions would enumerate the user's default tmux server
+# (missing the real Codeman sessions, surfacing unrelated ones).
+CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
+TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
+
 
 # iPhone 17 Pro portrait width (conservative)
 MAX_WIDTH=44
@@ -286,7 +293,7 @@ parse_sessions() {
 
         # Get PID from tmux
         local pid
-        pid=$(tmux display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")
+        pid=$("${TMUX_CMD[@]}" display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")
 
         SESSION_PIDS+=("$pid")
         MUX_NAMES+=("$session_name")
@@ -314,7 +321,7 @@ parse_sessions() {
         fi
 
         i=$((i + 1))
-    done < <(tmux list-sessions 2>/dev/null || true)
+    done < <("${TMUX_CMD[@]}" list-sessions 2>/dev/null || true)
 }
 
 # ============================================================================
@@ -462,7 +469,7 @@ attach_session() {
     echo -e "${D}(Ctrl+B D to detach)${R}"
     sleep 0.3
 
-    tmux attach-session -t "$mux_name"
+    "${TMUX_CMD[@]}" attach-session -t "$mux_name"
 
     return 0
 }

scripts/tmux-manager.sh

@@ -20,6 +20,13 @@ REVERSE='\033[7m'
 # Use the same path as codeman (src/tmux-manager.ts)
 SESSIONS_FILE="${HOME}/.codeman/mux-sessions.json"
 
+# Dedicated tmux socket all Codeman sessions live on. MUST match
+# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
+# otherwise this script would talk to the user's default tmux server and never
+# see (or could mis-target) Codeman's sessions.
+CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
+TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
+
 
 # Cached data
 CACHED_JSON=""
@@ -92,7 +99,7 @@ declare -A ALIVE_CACHE
 check_alive() {
     local mux_name=$1
     if [[ -z "${ALIVE_CACHE[$mux_name]+x}" ]]; then
-        if tmux has-session -t "$mux_name" 2>/dev/null; then
+        if "${TMUX_CMD[@]}" has-session -t "$mux_name" 2>/dev/null; then
             ALIVE_CACHE[$mux_name]=1
         else
             ALIVE_CACHE[$mux_name]=0
@@ -111,8 +118,10 @@ kill_session() {
     local mux_name=$(get_session_field $idx "muxName")
     local pid=$(get_session_field $idx "pid")
 
-    # SAFETY: Never kill own tmux session
-    local current_session=$(tmux display-message -p '#{session_name}' 2>/dev/null || echo "")
+    # SAFETY: Never kill own tmux session. Queried on the Codeman socket; if run
+    # from a session on a different socket this returns empty (no match), which
+    # is fine — you can't be "inside" a Codeman-socket session you didn't attach to.
+    local current_session=$("${TMUX_CMD[@]}" display-message -p '#{session_name}' 2>/dev/null || echo "")
     if [[ -n "$current_session" && "$mux_name" == "$current_session" ]]; then
         echo -e "${RED}BLOCKED: Cannot kill own tmux session: $mux_name${NC}"
         return 1
@@ -120,7 +129,7 @@ kill_session() {
 
     pkill -TERM -P $pid 2>/dev/null
     kill -TERM -$pid 2>/dev/null
-    tmux kill-session -t "$mux_name" 2>/dev/null
+    "${TMUX_CMD[@]}" kill-session -t "$mux_name" 2>/dev/null
     kill -KILL $pid 2>/dev/null
 
     # Remove from JSON
@@ -345,7 +354,7 @@ interactive_menu() {
                         clear
                         echo -e "${CYAN}Attaching... (Ctrl+B D to detach)${NC}"
                         sleep 0.3
-                        tmux attach-session -t "$mux_name"
+                        "${TMUX_CMD[@]}" attach-session -t "$mux_name"
                         tput civis
                         need_full_redraw=1
                         force_refresh
@@ -474,7 +483,7 @@ main() {
             [[ -z "${2:-}" ]] && { echo "Usage: $0 attach <N>"; exit 1; }
             force_refresh
             local mux_name=$(get_session_field $(($2-1)) "muxName")
-            check_alive "$mux_name" && tmux attach-session -t "$mux_name" || echo "Session dead or not found"
+            check_alive "$mux_name" && "${TMUX_CMD[@]}" attach-session -t "$mux_name" || echo "Session dead or not found"
             ;;
         kill)
             [[ -z "${2:-}" ]] && { echo "Usage: $0 kill <N|N,M|N-M>"; exit 1; }
@@ -492,8 +501,8 @@ main() {
             ;;
         kill-all)
             force_refresh
-            # SAFETY: Never kill own tmux session
-            local current_session=$(tmux display-message -p '#{session_name}' 2>/dev/null || echo "")
+            # SAFETY: Never kill own tmux session (queried on the Codeman socket)
+            local current_session=$("${TMUX_CMD[@]}" display-message -p '#{session_name}' 2>/dev/null || echo "")
             local killed=0
             for ((i=CACHED_COUNT-1; i>=0; i--)); do
                 local mux_name=$(get_session_field $i "muxName")

scripts/tunnel.sh

@@ -1,45 +1,209 @@
 #!/usr/bin/env bash
-# Quick Cloudflare Tunnel for Codeman
-# Usage: ./scripts/tunnel.sh [start|stop|status|url]
+# Cloudflare Tunnel manager for Codeman
+# Usage: ./scripts/tunnel.sh [quick|named] [start|stop|status|url]
+#
+# Modes:
+#   quick  — Quick tunnel with random trycloudflare.com URL (default)
+#   named  — Named tunnel on a fixed hostname (requires setup, see below)
+#
+# Environment variables:
+#   CLOUDFLARED_TUNNEL_NAME     — tunnel name (default: codeman)
+#   CLOUDFLARED_TUNNEL_ID       — tunnel UUID (from: cloudflared tunnel list)
+#   CODEMAN_TUNNEL_HOSTNAME     — public hostname (e.g. codeman.example.com)
+#
+# First-time named tunnel setup:
+#   cloudflared tunnel login
+#   cloudflared tunnel create <tunnel-name>
+#   cloudflared tunnel route dns <tunnel-name> <hostname>
+#   ./scripts/tunnel.sh named setup   # writes ~/.cloudflared/<tunnel-name>.yml
 set -euo pipefail
 
-SERVICE="codeman-tunnel"
+QUICK_SERVICE="codeman-tunnel"
+NAMED_SERVICE="codeman-tunnel-named"
+TUNNEL_NAME="${CLOUDFLARED_TUNNEL_NAME:-codeman}"
+TUNNEL_HOSTNAME="${CODEMAN_TUNNEL_HOSTNAME:-codeman.example.com}"
+CODEMAN_PORT="3000"
+LOG_FILE="$HOME/.codeman/tunnel.log"
 
-case "${1:-start}" in
-  start)
-    if ! systemctl --user is-active "$SERVICE" &>/dev/null; then
-      # Install service if not already
-      if ! systemctl --user cat "$SERVICE" &>/dev/null 2>&1; then
-        cp "$(dirname "$0")/codeman-tunnel.service" "$HOME/.config/systemd/user/"
-        systemctl --user daemon-reload
-      fi
-      systemctl --user start "$SERVICE"
-      echo "Tunnel starting... waiting for URL"
-      sleep 6
-    fi
-    # Extract the tunnel URL from journal
-    URL=$(grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$HOME/.codeman/tunnel.log" 2>/dev/null | tail -1)
-    if [ -n "$URL" ]; then
-      echo "$URL"
-    else
-      echo "URL not ready yet, try: $0 url"
-    fi
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+_require_cloudflared() {
+  if ! command -v cloudflared &>/dev/null; then
+    echo "Error: cloudflared not found. Install with: yay -S cloudflared" >&2
+    exit 1
+  fi
+}
+
+_cloudflared_bin() {
+  command -v cloudflared
+}
+
+_install_service() {
+  local svc_file="$1"
+  local svc_name="$2"
+  if ! systemctl --user cat "$svc_name" &>/dev/null 2>&1; then
+    cp "$(dirname "$0")/$svc_file" "$HOME/.config/systemd/user/"
+    systemctl --user daemon-reload
+    echo "Service $svc_name installed."
+  fi
+}
+
+_install_named_service() {
+  if ! systemctl --user cat "$NAMED_SERVICE" &>/dev/null 2>&1; then
+    # Generate service file with the configured tunnel name
+    sed "s/codeman\.yml/$TUNNEL_NAME.yml/g; s/run codeman/run $TUNNEL_NAME/g" \
+      "$(dirname "$0")/codeman-tunnel-named.service" \
+      > "$HOME/.config/systemd/user/codeman-tunnel-named.service"
+    systemctl --user daemon-reload
+    echo "Service $NAMED_SERVICE installed (tunnel: $TUNNEL_NAME)."
+  fi
+}
+
+# ── named tunnel setup ───────────────────────────────────────────────────────
+
+_named_setup() {
+  _require_cloudflared
+
+  local creds_dir="$HOME/.cloudflared"
+  local config_file="$creds_dir/$TUNNEL_NAME.yml"
+  # Replace with your tunnel ID (from: cloudflared tunnel list)
+  local tunnel_id="${CLOUDFLARED_TUNNEL_ID:-YOUR_TUNNEL_ID_HERE}"
+  local creds_file="$creds_dir/$tunnel_id.json"
+
+  if [ ! -f "$creds_file" ]; then
+    echo "Credentials not found: $creds_file"
+    echo "Run: cloudflared tunnel create $TUNNEL_NAME"
+    exit 1
+  fi
+
+  cat > "$config_file" <<EOF
+tunnel: $tunnel_id
+credentials-file: $creds_file
+
+ingress:
+  - hostname: $TUNNEL_HOSTNAME
+    service: http://localhost:$CODEMAN_PORT
+  - service: http_status:404
+EOF
+
+  echo "Config written to $config_file"
+  echo "Tunnel ID: $tunnel_id"
+  echo "Hostname:  $TUNNEL_HOSTNAME"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Add Cloudflare Access policy for $TUNNEL_HOSTNAME (Zero Trust dashboard)"
+  echo "  2. ./scripts/tunnel.sh named start"
+}
+
+# ── quick mode ───────────────────────────────────────────────────────────────
+
+_quick_start() {
+  if ! systemctl --user is-active "$QUICK_SERVICE" &>/dev/null; then
+    _install_service "codeman-tunnel.service" "$QUICK_SERVICE"
+    systemctl --user start "$QUICK_SERVICE"
+    echo "Quick tunnel starting... waiting for URL"
+    sleep 6
+  fi
+  local url
+  url=$(grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$LOG_FILE" 2>/dev/null | tail -1)
+  if [ -n "$url" ]; then
+    echo "$url"
+  else
+    echo "URL not ready yet, try: $0 quick url"
+  fi
+}
+
+_quick_stop() {
+  systemctl --user stop "$QUICK_SERVICE"
+  echo "Quick tunnel stopped"
+}
+
+_quick_status() {
+  systemctl --user status "$QUICK_SERVICE" --no-pager 2>&1 | head -10
+  echo ""
+  echo "URL:"
+  grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$LOG_FILE" 2>/dev/null | tail -1
+}
+
+_quick_url() {
+  grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$LOG_FILE" 2>/dev/null | tail -1
+}
+
+# ── named mode ───────────────────────────────────────────────────────────────
+
+_named_start() {
+  _require_cloudflared
+  if [ ! -f "$HOME/.cloudflared/$TUNNEL_NAME.yml" ]; then
+    echo "Config not found. Run: $0 named setup"
+    exit 1
+  fi
+  if ! systemctl --user is-active "$NAMED_SERVICE" &>/dev/null; then
+    _install_named_service
+    systemctl --user start "$NAMED_SERVICE"
+    echo "Named tunnel starting..."
+    sleep 3
+  fi
+  echo "https://$TUNNEL_HOSTNAME"
+}
+
+_named_stop() {
+  systemctl --user stop "$NAMED_SERVICE"
+  echo "Named tunnel stopped"
+}
+
+_named_status() {
+  systemctl --user status "$NAMED_SERVICE" --no-pager 2>&1 | head -10
+  echo ""
+  echo "URL: https://$TUNNEL_HOSTNAME"
+}
+
+_named_enable() {
+  _install_named_service
+  systemctl --user enable "$NAMED_SERVICE"
+  echo "Named tunnel enabled at boot."
+}
+
+_named_disable() {
+  systemctl --user disable "$NAMED_SERVICE"
+  echo "Named tunnel disabled."
+}
+
+# ── dispatch ─────────────────────────────────────────────────────────────────
+
+MODE="${1:-quick}"
+CMD="${2:-start}"
+
+case "$MODE" in
+  quick)
+    case "$CMD" in
+      start)  _quick_start ;;
+      stop)   _quick_stop ;;
+      status) _quick_status ;;
+      url)    _quick_url ;;
+      *) echo "Usage: $0 quick [start|stop|status|url]"; exit 1 ;;
+    esac
     ;;
-  stop)
-    systemctl --user stop "$SERVICE"
-    echo "Tunnel stopped"
-    ;;
-  status)
-    systemctl --user status "$SERVICE" --no-pager 2>&1 | head -10
-    echo ""
-    echo "URL:"
-    grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$HOME/.codeman/tunnel.log" 2>/dev/null | tail -1
-    ;;
-  url)
-    grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' "$HOME/.codeman/tunnel.log" 2>/dev/null | tail -1
+  named)
+    case "$CMD" in
+      start)   _named_start ;;
+      stop)    _named_stop ;;
+      status)  _named_status ;;
+      url)     echo "https://$TUNNEL_HOSTNAME" ;;
+      setup)   _named_setup ;;
+      enable)  _named_enable ;;
+      disable) _named_disable ;;
+      *) echo "Usage: $0 named [start|stop|status|url|setup|enable|disable]"; exit 1 ;;
+    esac
     ;;
+  # backward compat: no mode prefix → quick tunnel
+  start)  _quick_start ;;
+  stop)   _quick_stop ;;
+  status) _quick_status ;;
+  url)    _quick_url ;;
   *)
-    echo "Usage: $0 [start|stop|status|url]"
+    echo "Usage: $0 [quick|named] [start|stop|status|url]"
+    echo "       $0 named setup    # first-time named tunnel configuration"
+    echo "       $0 named enable   # start at boot"
     exit 1
     ;;
 esac

src/ai-checker-base.ts

@@ -30,6 +30,7 @@ import { join } from 'node:path';
 import { EventEmitter } from 'node:events';
 import { getAugmentedPath, ANSI_ESCAPE_PATTERN_SIMPLE } from './utils/index.js';
 import { AI_CHECK_MAX_BACKOFF_MS } from './config/ai-defaults.js';
+import { getErrorMessage } from './types.js';
 
 // ========== Security Validation ==========
 
@@ -293,7 +294,7 @@ export abstract class AiCheckerBase<
       this.emit('checkCompleted', result);
       return result;
     } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
+      const errorMsg = getErrorMessage(err);
       this.handleError(errorMsg);
       const result = this.createErrorResult(errorMsg, Date.now() - this.checkStartTime);
       this.emit('checkFailed', errorMsg);
@@ -412,9 +413,7 @@ export abstract class AiCheckerBase<
       });
       muxProcess.unref();
     } catch (err) {
-      throw new Error(
-        `Failed to spawn ${this.checkDescription} tmux session: ${err instanceof Error ? err.message : String(err)}`
-      );
+      throw new Error(`Failed to spawn ${this.checkDescription} tmux session: ${getErrorMessage(err)}`);
     }
 
     // Poll the temp file for completion

src/ai-idle-checker.ts

@@ -41,7 +41,7 @@ import {
 
 // ========== Types ==========
 
-export type AiIdleCheckConfig = AiCheckerConfigBase;
+type AiIdleCheckConfig = AiCheckerConfigBase;
 
 export type AiCheckVerdict = 'IDLE' | 'WORKING' | 'ERROR';
 

src/ai-plan-checker.ts

@@ -40,13 +40,13 @@ import {
 
 // ========== Types ==========
 
-export type AiPlanCheckConfig = AiCheckerConfigBase;
+type AiPlanCheckConfig = AiCheckerConfigBase;
 
 export type AiPlanCheckVerdict = 'PLAN_MODE' | 'NOT_PLAN_MODE' | 'ERROR';
 
 export type AiPlanCheckResult = AiCheckerResultBase<AiPlanCheckVerdict>;
 
-export type AiPlanCheckState = AiCheckerStateBase<AiPlanCheckVerdict>;
+type AiPlanCheckState = AiCheckerStateBase<AiPlanCheckVerdict>;
 
 // ========== Constants ==========
 
@@ -64,20 +64,27 @@ const DEFAULT_PLAN_CHECK_CONFIG: AiPlanCheckConfig = {
 const VERDICT_PATTERN = /^\s*(PLAN_MODE|NOT_PLAN_MODE)\b/i;
 
 /** The prompt sent to the AI plan checker */
-const AI_PLAN_CHECK_PROMPT = `Analyze this terminal output from a running Claude Code session. Determine if the terminal is currently showing a PLAN MODE APPROVAL PROMPT or not.
+const AI_PLAN_CHECK_PROMPT = `Analyze this terminal output from a running Claude Code session. Determine if the terminal is currently showing a NUMBERED SELECTION MENU that is waiting for the user to press Enter on the highlighted default option.
 
-A plan mode approval prompt is a numbered selection menu that Claude Code shows when it wants the user to approve a plan before proceeding. It typically has these characteristics:
+A qualifying menu has all of these characteristics:
 - A numbered list of options (e.g., "1. Yes", "2. No", "3. Type your own")
-- A selection indicator arrow (❯ or >) pointing to one of the options
-- Text asking for approval like "Would you like to proceed?" or "Ready to implement?"
-- The prompt appears at the BOTTOM of the output (most recent content)
+- A selection indicator arrow (❯ or >) pointing to one of the options (the default)
+- The menu appears at the BOTTOM of the output (most recent content)
+- It is asking the user to choose, not just displaying numbered information
 
-NOT a plan mode prompt:
+This includes BOTH:
+- Plan-mode approval prompts ("Would you like to proceed?" / "Ready to implement?")
+- AskUserQuestion / elicitation dialogs (Claude Code's numbered question menus)
+
+NOT a qualifying menu:
 - Claude actively working (spinners, "Thinking", tool execution)
-- A completed response with no selection menu
-- An AskUserQuestion/elicitation dialog (different format, free-text input)
+- A completed response with no selection menu visible
+- A free-text input field with no numbered options
+- A numbered LIST in the assistant's prose with no selection arrow
 - Network lag or mid-output pause
-- Any state without a visible numbered selection menu
+- Any state without a visible selector arrow on a numbered option
+
+The verdict name PLAN_MODE is historical — it now means "auto-accept this selection menu by pressing Enter on the default".
 
 Terminal output (most recent at bottom):
 ---

src/bash-tool-parser.ts

@@ -99,7 +99,7 @@ const LOG_FILE_MENTION_PATTERN = /([/~][^\s'"<>|;&\n]*(?:\.log|\.txt|\.out|\/log
 /**
  * Events emitted by BashToolParser.
  */
-export interface BashToolParserEvents {
+interface BashToolParserEvents {
   /** New Bash tool with file paths started */
   toolStart: [tool: ActiveBashTool];
   /** Bash tool completed */
@@ -111,7 +111,7 @@ export interface BashToolParserEvents {
 /**
  * Configuration options for BashToolParser.
  */
-export interface BashToolParserConfig {
+interface BashToolParserConfig {
   /** Session ID this parser belongs to */
   sessionId: string;
   /** Whether the parser is enabled (default: true) */
@@ -470,120 +470,91 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
    * Process a single pre-stripped line of terminal output.
    */
   private processCleanLine(cleanLine: string): void {
-    // Check for tool start
+    if (this._handleToolStart(cleanLine)) return;
+    if (this._handleToolCompletion(cleanLine)) return;
+    if (this._handleTextCommand(cleanLine)) return;
+    this._handleLogFileMention(cleanLine);
+  }
+
+  private _handleToolStart(cleanLine: string): boolean {
     const startMatch = cleanLine.match(BASH_TOOL_START_PATTERN);
-    if (startMatch) {
-      const command = startMatch[1];
-      const timeout = startMatch[2]?.trim();
+    if (!startMatch) return false;
 
-      // Check if this is a file-viewing command
-      if (this.isFileViewerCommand(command)) {
-        const filePaths = this.extractFilePaths(command);
+    const command = startMatch[1];
+    const timeout = startMatch[2]?.trim();
 
-        // Skip if any file path is already tracked (cross-pattern dedup)
-        if (filePaths.some((fp) => this.isFilePathTracked(fp))) {
-          return;
-        }
+    if (!this.isFileViewerCommand(command)) return true;
 
-        if (filePaths.length > 0) {
-          const tool: ActiveBashTool = {
-            id: uuidv4(),
-            command,
-            filePaths,
-            timeout,
-            startedAt: Date.now(),
-            status: 'running',
-            sessionId: this._sessionId,
-          };
+    const filePaths = this.extractFilePaths(command);
 
-          // Enforce max tools limit
-          if (this._activeTools.size >= MAX_ACTIVE_TOOLS) {
-            // Remove oldest tool (O(n) min-scan instead of O(n log n) sort)
-            let oldestKey: string | undefined;
-            let oldestTime = Infinity;
-            for (const [key, entry] of this._activeTools) {
-              if (entry.startedAt < oldestTime) {
-                oldestTime = entry.startedAt;
-                oldestKey = key;
-              }
-            }
-            if (oldestKey) {
-              this._activeTools.delete(oldestKey);
-            }
+    // Skip if any file path is already tracked (cross-pattern dedup)
+    if (filePaths.some((fp) => this.isFilePathTracked(fp))) return true;
+
+    if (filePaths.length > 0) {
+      const tool = this._createActiveTool(command, filePaths, 'running', timeout);
+
+      // Enforce max tools limit
+      if (this._activeTools.size >= MAX_ACTIVE_TOOLS) {
+        // Remove oldest tool (O(n) min-scan instead of O(n log n) sort)
+        let oldestKey: string | undefined;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this._activeTools) {
+          if (entry.startedAt < oldestTime) {
+            oldestTime = entry.startedAt;
+            oldestKey = key;
           }
-
-          this._activeTools.set(tool.id, tool);
-          this._lastToolId = tool.id;
-
-          this.emit('toolStart', tool);
-          this.scheduleUpdate();
         }
-      }
-      return;
-    }
-
-    // Check for tool completion
-    if (TOOL_COMPLETION_PATTERN.test(cleanLine) && this._lastToolId) {
-      const tool = this._activeTools.get(this._lastToolId);
-      if (tool && tool.status === 'running') {
-        tool.status = 'completed';
-        this.emit('toolEnd', tool);
-        this.scheduleUpdate();
-
-        // Remove completed tool after a short delay to allow UI to show completion
-        this.cleanup.setTimeout(
-          () => {
-            if (this._destroyed) return;
-            this._activeTools.delete(tool.id);
-            this.scheduleUpdate();
-          },
-          2000,
-          { description: 'auto-remove completed tool' }
-        );
-      }
-      this._lastToolId = null;
-      return;
-    }
-
-    // Fallback: Check for command suggestions in plain text (e.g., "tail -f /tmp/file.log")
-    const textCmdMatch = cleanLine.match(TEXT_COMMAND_PATTERN);
-    if (textCmdMatch) {
-      const filePath = textCmdMatch[2];
-
-      // Create a suggestion tool (marked as 'suggestion' status)
-      const tool: ActiveBashTool = {
-        id: uuidv4(),
-        command: cleanLine.trim(),
-        filePaths: [filePath],
-        timeout: undefined,
-        startedAt: Date.now(),
-        status: 'running', // Shows as clickable
-        sessionId: this._sessionId,
-      };
-
-      // Don't add if file path already tracked (cross-pattern dedup)
-      if (this.isFilePathTracked(filePath)) {
-        return;
+        if (oldestKey) {
+          this._activeTools.delete(oldestKey);
+        }
       }
 
       this._activeTools.set(tool.id, tool);
+      this._lastToolId = tool.id;
+
       this.emit('toolStart', tool);
       this.scheduleUpdate();
-
-      // Auto-remove suggestions after 30 seconds
-      this.cleanup.setTimeout(
-        () => {
-          if (this._destroyed) return;
-          this._activeTools.delete(tool.id);
-          this.scheduleUpdate();
-        },
-        30000,
-        { description: 'auto-remove suggestion tool' }
-      );
-      return;
     }
 
-    // Last fallback: Check for log file paths mentioned anywhere in the line
+    return true;
+  }
+
+  private _handleToolCompletion(cleanLine: string): boolean {
+    if (!TOOL_COMPLETION_PATTERN.test(cleanLine) || !this._lastToolId) return false;
+
+    const tool = this._activeTools.get(this._lastToolId);
+    if (tool && tool.status === 'running') {
+      tool.status = 'completed';
+      this.emit('toolEnd', tool);
+      this.scheduleUpdate();
+
+      this._scheduleAutoRemove(tool.id, 2000, 'auto-remove completed tool');
+    }
+    this._lastToolId = null;
+    return true;
+  }
+
+  private _handleTextCommand(cleanLine: string): boolean {
+    const textCmdMatch = cleanLine.match(TEXT_COMMAND_PATTERN);
+    if (!textCmdMatch) return false;
+
+    const filePath = textCmdMatch[2];
+
+    // Don't add if file path already tracked (cross-pattern dedup)
+    if (this.isFilePathTracked(filePath)) return true;
+
+    const tool = this._createActiveTool(cleanLine.trim(), [filePath], 'running');
+
+    this._activeTools.set(tool.id, tool);
+    this.emit('toolStart', tool);
+    this.scheduleUpdate();
+
+    // Auto-remove suggestions after 30 seconds
+    this._scheduleAutoRemove(tool.id, 30000, 'auto-remove suggestion tool');
+    return true;
+  }
+
+  private _handleLogFileMention(cleanLine: string): void {
     LOG_FILE_MENTION_PATTERN.lastIndex = 0;
     let logMatch;
     while ((logMatch = LOG_FILE_MENTION_PATTERN.exec(cleanLine)) !== null) {
@@ -595,33 +566,46 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
       // Skip if file path already tracked (cross-pattern dedup)
       if (this.isFilePathTracked(filePath)) continue;
 
-      const tool: ActiveBashTool = {
-        id: uuidv4(),
-        command: `View: ${filePath}`,
-        filePaths: [filePath],
-        timeout: undefined,
-        startedAt: Date.now(),
-        status: 'running',
-        sessionId: this._sessionId,
-      };
+      const tool = this._createActiveTool(`View: ${filePath}`, [filePath], 'running');
 
       this._activeTools.set(tool.id, tool);
       this.emit('toolStart', tool);
       this.scheduleUpdate();
 
       // Auto-remove after 60 seconds
-      this.cleanup.setTimeout(
-        () => {
-          if (this._destroyed) return;
-          this._activeTools.delete(tool.id);
-          this.scheduleUpdate();
-        },
-        60000,
-        { description: 'auto-remove log file tool' }
-      );
+      this._scheduleAutoRemove(tool.id, 60000, 'auto-remove log file tool');
     }
   }
 
+  private _createActiveTool(
+    command: string,
+    filePaths: string[],
+    status: ActiveBashTool['status'],
+    timeout?: string
+  ): ActiveBashTool {
+    return {
+      id: uuidv4(),
+      command,
+      filePaths,
+      timeout,
+      startedAt: Date.now(),
+      status,
+      sessionId: this._sessionId,
+    };
+  }
+
+  private _scheduleAutoRemove(toolId: string, delayMs: number, description: string): void {
+    this.cleanup.setTimeout(
+      () => {
+        if (this._destroyed) return;
+        this._activeTools.delete(toolId);
+        this.scheduleUpdate();
+      },
+      delayMs,
+      { description }
+    );
+  }
+
   /**
    * Check if a command is a file-viewing command worth tracking.
    */

src/cli.ts

@@ -483,19 +483,29 @@ program
 program
   .command('web')
   .description('Start the web interface')
-  .option('-p, --port <port>', 'Port to listen on', '3000')
+  .option('-H, --host <host>', 'Host to bind to', process.env.CODEMAN_HOST || '127.0.0.1')
+  .option('-p, --port <port>', 'Port to listen on (env: CODEMAN_PORT)', process.env.CODEMAN_PORT || '3000')
   .option('--https', 'Enable HTTPS with self-signed certificate (only needed for remote access, not localhost)')
+  .option('--title-hostname <hostname>', 'Override the hostname shown in the browser title')
+  .option(
+    '--allow-unauthenticated-network',
+    'Allow non-loopback web access without CODEMAN_PASSWORD (dangerous; terminal control is exposed)'
+  )
   .action(async (options) => {
     const { startWebServer } = await import('./web/server.js');
+    const host = options.host;
     const port = parseInt(options.port, 10);
     const https = !!options.https;
+    const titleHostname = options.titleHostname;
+    const allowUnauthenticatedNetwork = !!options.allowUnauthenticatedNetwork;
     const protocol = https ? 'https' : 'http';
+    const displayHost = host === '0.0.0.0' ? 'localhost' : host;
 
-    console.log(chalk.cyan(`Starting Codeman web interface on port ${port}${https ? ' (HTTPS)' : ''}...`));
+    console.log(chalk.cyan(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
 
     try {
-      const server = await startWebServer(port, https);
-      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'));
       }