chore: version packages

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

.github/SECURITY.md

@@ -4,7 +4,7 @@ Codeman launches AI coding sessions with `--dangerously-skip-permissions`, so th
 web UI is **by design a remote-code-execution surface for whoever can reach it**.
 The entire security model exists to control *who* that is. Please read this before
 exposing an instance beyond `localhost`. The full model lives in
-[`docs/security-architecture.md`](docs/security-architecture.md).
+[`docs/security-architecture.md`](../docs/security-architecture.md).
 
 ## Supported versions
 
@@ -75,4 +75,4 @@ subscribe and send time), and tmux session names discovered on the shared socket
 are validated against the safe-name pattern before reaching any shell call site.
 
 For the detailed rationale, defenses, and recommended secure setups, see
-[`docs/security-architecture.md`](docs/security-architecture.md).
+[`docs/security-architecture.md`](../docs/security-architecture.md).

.prettierignore

@@ -26,3 +26,6 @@ src/web/public/terminal-ui.js
 src/web/public/voice-input.js
 src/web/public/upload.html
 scripts/remotion/
+
+# Hand-maintained; Prettier escapes underscores in glob paths and corrupts paragraphs.
+CLAUDE.md

.prettierrc

@@ -1,8 +0,0 @@
-{
-  "singleQuote": true,
-  "semi": true,
-  "tabWidth": 2,
-  "printWidth": 120,
-  "trailingComma": "es5",
-  "endOfLine": "lf"
-}

CHANGELOG.md

@@ -1,5 +1,52 @@
 # aicodeman
 
+## 1.8.2
+
+### Patch Changes
+
+- Web tabs: open dashboard URLs as tabs beside agent sessions, plus terminal link fixes.
+
+  **Web tabs.** The Run dropdown gains a "Web / URL" section. A saved URL renders as a tab in the same strip as Claude/Codex/Gemini sessions, with the same Alt+1-9 numbering, an icon picker, and per-device tab order. Frames stay mounted while hidden (LRU-bounded), so switching tabs never reloads a dashboard.
+
+  Dashboards are proxied through Codeman's own origin, because a direct iframe fails three ways at once: an HTTPS Codeman cannot embed a plain-HTTP target (mixed content, with no override at all on iOS Safari), many dashboards send `X-Frame-Options: DENY`, and Codeman's own `default-src 'self'` CSP blocks cross-origin frames. Proxying dissolves all three and leaves the production CSP unchanged. The fetch happens server-side, so a tailnet-only or localhost-only dashboard is reachable from any device that can reach Codeman.
+
+  The proxy is not an API surface: it authenticates on a 192-bit capability in the path (memory-only, rolling TTL, bound to the minting user, revoked on edit or delete) and is exempt from the cookie and Origin checks, because a sandboxed iframe is opaque-origin and sends neither. The Host allowlist is never bypassed. Iframes omit `allow-same-origin` unless a URL is explicitly marked trusted, and `Authorization` plus the session cookie are stripped upstream in both modes so `CODEMAN_PASSWORD` cannot leak into a dashboard. Includes an HTTP and WebSocket proxy, redirect/cookie/`<base>` rewriting, a runtime URL shim for requests built by dashboard JavaScript, and CORS handling for the opaque-origin frame. New endpoints under `/api/webviews`, storage in `~/.codeman/webviews.json`, user guide in `docs/web-tabs.md`.
+
+  **Terminal links no longer truncate.** Three separate cuts, each producing a link that opened the wrong target or none at all:
+  - A single `&` ended the match, so every query string was cut. A WordPress edit link resolved to `?post=1479` and Claude Code's own `/login` URL was unusable. `&` is now part of a URL while `&&` remains a boundary.
+  - Links wider than the terminal were cut at the row boundary. The link provider now stitches continuation rows into one logical line and maps offsets back across rows. Handles both soft wraps (emulator, `isWrapped`) and hard wraps (a program wrapping its own output and emitting a newline, as Ink does), the latter being why the `/login` URL grew longer as the window was widened.
+  - Image and PDF paths were not matched at all, so pasted-screenshot paths rendered as plain text. They now link and open the file preview, which renders images inline.
+
+  **Also fixes** a pre-existing bug where `.toolbar`'s `backdrop-filter` created a stacking context that trapped the Run menu's z-index, letting the welcome overlay cover it: with no session open, every item in that menu (Claude Code included) was unclickable.
+
+## 1.8.1
+
+### Patch Changes
+
+- Mobile toolbar: a dedicated Enter button, and Shell moves into the Run dropdown.
+
+  Submitting is a constant need on a touch keyboard, so on phones (≤430px) the toolbar slot that held "Shell" now holds a dark blue **Enter** button. Starting a shell, the far rarer action, moves into the expandable Run dropdown as `Terminal / Shell` (the Run button then reads "Run SH"). Desktop and tablet are unchanged: the green Run Shell button stays exactly where it was.
+
+  Enter is replayed through the terminal's own input path rather than posted to the input API. This matters because local echo is on by default on touch devices: the characters you type are buffered client-side and have not yet reached the PTY, so sending a bare carriage return would submit an empty line and leave your text stranded on screen. Replaying the keypress flushes the buffered text first, then submits.
+
+  Installer: re-runs and updates now preserve the existing network binding instead of silently reverting it, so upgrading no longer changes how the dashboard is reachable.
+
+  Default desktop header is cleaner: the file viewer is shown by default and the plan-usage chip is unchanged, while the token-count chip and lifecycle-log button now default off. Stored preferences are still honored.
+
+  Docs and repo housekeeping: fresh phone screenshots and a new hero GIF in both READMEs, contributor and total-commit badges, and a much shorter repo root. `SECURITY.md` moved to `.github/` (GitHub resolves it there, so the Security policy tab is unaffected), `SPEEDRUN.md` to `docs/`, the knip config to `config/`, and Prettier's config into the `"prettier"` key of `package.json`. `CLAUDE.md` was split so the always-loaded guidance is roughly half its former size, with the deep implementation detail preserved verbatim in `docs/architecture-invariants.md`.
+
+## 1.8.0
+
+### Minor Changes
+
+- Installer: choose your network binding, with LAN access as the new guided default.
+
+  The install script now asks at the end of setup how the dashboard should be reachable:
+  1. Any device on your network (0.0.0.0), the default. The installer prompts for a dashboard password (hidden input, confirmed twice); declining a password requires an explicit confirmation and the install ends with a prominent warning explaining the exposure.
+  2. This machine only (127.0.0.1), the safer option for tunnel/Tailscale setups.
+
+  The choice is wired into the generated systemd unit and launchd plist (values escaped for each format), the run-now launch path, and the printed URLs, which now include the detected LAN IP for instant phone access. Non-interactive installs keep the safe loopback default unless CODEMAN_HOST is preset, and the server binary's own default binding (127.0.0.1) is unchanged, so npm and manual installs behave exactly as before. New installer env presets: CODEMAN_HOST and CODEMAN_PASSWORD skip the prompts for automation.
+
 ## 1.7.1
 
 ### Patch Changes

CLAUDE.md

@@ -2,6 +2,12 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+> Deep implementation detail lives in [`docs/architecture-invariants.md`](docs/architecture-invariants.md). This file holds the rules that prevent mistakes; that file holds the mechanisms, file inventories, and the history behind each rule. Pointers below are written as `→ architecture-invariants#anchor`. When the goal is raw throughput, [`docs/SPEEDRUN.md`](docs/SPEEDRUN.md) is the fast-execution protocol (it removes ceremony, never the safety rules here).
+>
+> **This file is in `.prettierignore` on purpose.** Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (`agent-*.jsonl` became `agent-\_.jsonl`, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run `prettier --write` on it.
+>
+> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those.
+
 ## Quick Reference
 
 | Task        | Command                                                                                                                                                             |
@@ -22,6 +28,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **NEVER** run `tmux kill-session`, `pkill tmux`, or `pkill claude` without confirming
 3. Use the web UI or `./scripts/tmux-manager.sh` instead of direct kill commands
 
+**The working tree is shared with other agent sessions.** Several Codeman sessions run against THIS one checkout, so another session can `git checkout` a different branch, or leave half-finished untracked files, while you are mid-task.
+
+- **Always `git branch --show-current` immediately before committing.** Observed 2026-07-27: another session ran `git checkout -b feat/web-tabs`, a commit silently landed there instead of master, and the follow-up `git push origin master` cheerfully reported "Everything up-to-date".
+- To land a commit on master **without** switching branches (which would yank the tree out from under the other session): `git push origin HEAD:master` then `git branch -f master HEAD`. Never `git checkout master` to "fix" it.
+- **Never `git add -A`/`git add .`** — stage explicit paths. A sweep will pick up another session's WIP.
+- Another session's broken WIP can block `npm run build`, since `tsc` is the first step and the build gates on it. That is not your bug to fix. ⚠️ `tsc` still EMITS on type errors, so a failed `npm run build` leaves a rebuilt `dist/index.js` compiled from their tree; check what it pulled in before restarting the service. To deploy frontend-only changes past a blocked `tsc`, run the asset stage of `scripts/build.mjs` (everything after the `tsc`/`chmod` lines is independent of it).
+
 ## CRITICAL: Always Test Before Deploying
 
 **NEVER COM without verifying your changes actually work.** For every fix:
@@ -34,7 +47,7 @@ The production server caches static files for 1 year, `immutable` (`maxAge: '1y'
 
 ## COM Shorthand (Deployment)
 
-Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`. What SemVer actually covers (the CLI + documented env vars are public; the HTTP/SSE API, on-disk state, and experimental features are internal/unstable) is defined in `docs/versioning-policy.md`. Security reporting + known limitations live in `SECURITY.md`.
+Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`. What SemVer actually covers (the CLI + documented env vars are public; the HTTP/SSE API, on-disk state, and experimental features are internal/unstable) is defined in `docs/versioning-policy.md`. Security reporting + known limitations live in `.github/SECURITY.md`.
 
 When user says "COM":
 
@@ -55,12 +68,13 @@ When user says "COM":
 
 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`
+5. **Commit and deploy**: verify the branch first (`git branch --show-current`), then stage EXPLICIT paths — never `git add -A`, which has swept another session's WIP into a release. `git status --short` and account for every line before committing:
+   `git add <paths> && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 6. **Wait for CI**: after `git push`, TWO workflows fire per master push — `CI` and `Release` (the npm publish + GitHub release). List both runs for the pushed commit with `gh run list --commit $(git rev-parse HEAD) --json databaseId,workflowName` and watch EACH with `gh run watch <id> --exit-status`. Confirm both pass before considering the release done (`gh run list -L 1` returns only one of the two).
 
 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**: 1.7.1 (must match `package.json`)
+**Version**: 1.8.2 (must match `package.json`)
 
 ## Project Overview
 
@@ -86,7 +100,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | Continuous typecheck           | `tsc --noEmit --watch`                                                                                                                                                                                         |
 | Watch-mode test                | `npm run test:watch -- test/<file>.test.ts` (always pass a file — bare watch includes the browser suites)                                                                                                      |
 | Test coverage                  | `npm run test:coverage`                                                                                                                                                                                        |
-| Dead-code sweep                | `npm run knip` (config in `knip.json`)                                                                                                                                                                         |
+| Dead-code sweep                | `npm run knip` (config in `config/knip.json`, passed via `--config`)                                                                                                                                          |
 | 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)                                                             |
 | Build the docker agent image   | `node scripts/build-agent-image.mjs` (builds `codeman/agent:base` from `docker/agent.Dockerfile`; prerequisite for Docker cases; `--engine`/`--image`/`--no-cache`)                                            |
 | Gesture playground             | `npm run dev` **in** `packages/gesture-control/` (standalone vite demo, fake tabs)                                                                                                                             |
@@ -98,7 +112,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 3 Playwright tests). Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing).
 
-**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/**`.
+**Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`) — config lives in the **`"prettier"` key of `package.json`**, not a `.prettierrc` (keeps the repo root short; editors read it natively). `.prettierignore` stays at the root because Prettier resolves it relative to cwd. 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/**`.
+
+**Prettier scope is deliberately narrow.** `npm run format` globs only `src/**/*.ts` and `src/web/public/**`, and `.prettierignore` then exempts most of `src/web/public/*.js` (app.js, styles.css, index.html, and 14 hand-formatted modules) plus `CLAUDE.md`. Those files are hand-formatted by design; `npm run check:public-assets` and `check:frontend-syntax` are what guard them (NUL bytes + JS syntax), not Prettier. Do not "fix" a file by adding it back to Prettier's scope.
 
 ## Common Gotchas
 
@@ -109,12 +125,12 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` 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. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.)
 - **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`
 - **Model choice flows via `settings.local.json`, NOT `--model` or env** — the App Settings **Claude Model** picker (`claudeModel` in `settings.json`) is read by `session-ui.js` at session create (wins over the legacy 1M-Opus toggles `opusContext1m`/`opusContext1mEnabled`), sent as the `modelOverride` payload field, and `updateCaseModel()` (`hooks-config.ts`) writes/deletes the `model` key in `<case>/.claude/settings.local.json`. This is the intended exception to the envOverrides rule above: model legitimately lives in `settings.local.json` (a soft default — in-session `/model` still works); env vars do not
-- **Multi-CLI prefix discipline** — Codeman supports Claude Code, OpenCode, Codex, and Gemini (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts` / `codex-cli-resolver.ts` / `gemini-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional — Vertex AI auth uses `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc.; it's the loosest allowlist entry, affecting only the user's own spawned CLI). When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward all prefixes. See `docs/opencode-integration.md` for the resolver design pattern
-- **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 single-source — edit the package, then rebuild the bundle** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/` (`zerolag-input-addon.ts`; also published to npm as a standalone library — see README "Published Packages"). It is bundled (esbuild → IIFE, with appended `window.LocalEchoOverlay` aliases) into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` by `scripts/postinstall.js` (for dev/`tsx`) and into `dist/.../vendor/` by `scripts/build.mjs` (the `xterm-zerolag-input` esbuild step, for prod). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)` — there is NO inline copy to keep in sync. So: change behavior in the package source, then re-run the bundle step (`npm install` reruns postinstall; `npm run build` for prod); **never hand-edit `app.js` for overlay behavior or commit the gitignored vendor bundle**. A public-API break in the package still warrants a separate `xterm-zerolag-input` version bump 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', …)`.
-- **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — `scripts/capture-real-overview.mjs` (drives a live session in headless Chromium → overview PNG). Two traps, both observed 2026-06-14: **(1) DSF=2 doubles the console font.** xterm's WebGL renderer draws terminal glyphs at ~2× their nominal size under `deviceScaleFactor: 2`, while STILL reporting nominal cell dims (`terminal.cols`/`_renderService.dimensions.css.cell` say 8px/187cols — they lie), so it's invisible to any internal measurement and only the pixels reveal it. The HTML chrome (header/toolbar) is unaffected → ONLY the console font looks comically large. Default to **DSF=1** (script does); the image is 1× res but the font is true-to-browser. **(2) Stable filenames → stale renders.** Overwriting a fixed path (`claude-overview.png`) in place leaves OS image viewers (eog/feh) — and any HTTP client behind a long/`immutable` cache — showing the OLD render; the user reads it as "the fix didn't work". The script now mints a timestamped `claude-overview-<ts>.png` per run. ⚠️ This was a LOCAL image-viewer cache, NOT a Codeman serving bug: `file-routes` previews send `Cache-Control: no-cache` and `/api/screenshots/:name` sends none. The one real Codeman-side footgun: `server.ts` serves non-content-hashed static assets `public, max-age=31536000, immutable`, and `cacheBustAssets()` only rewrites `.js`/`.css` refs — a stable-named **image** referenced from public/ would go stale on overwrite. Reflect the per-device UI to match a real device when capturing: seed `localStorage` `codeman:skin`, `codeman-font-size`, and the desktop `codeman-app-settings` blob (the plan-usage chip is a per-device display key deleted from the server payload — a fresh browser hides it unless seeded; close side panels for a full-width terminal).
+- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. Resolver design pattern: `docs/opencode-integration.md`
+- **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()`. This has caused real shipped bugs twice
+- **`xterm-zerolag-input` is single-source** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/`, and is bundled into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` (dev, by `scripts/postinstall.js`) and `dist/.../vendor/` (prod, by `scripts/build.mjs`). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundle.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
+- **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
+- **Instance isolation / multi-instance attach danger** — the 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`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
+- **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)
 
 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
 
@@ -122,32 +138,33 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Core Files (by domain)
 
-| Domain           | Key files                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Notes                                                                                                                                 |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| **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`, `src/session-pty-exit-breaker.ts`, `src/session-order.ts` (pure tab-order normalize/merge helpers, COD-131), `src/usage-limit-patterns.ts`, `src/usage-telemetry.ts`; `src/services/unified-session-service.ts` (merges live/persisted/lifecycle/transcript rows for `GET /api/sessions/unified`)                                                                                                        |                                                                                                                                       |
-| **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                                                                                   |
-| **Cron**         | `src/cron/cron-service.ts`, `src/cron/cron-time.ts` (pure next-run math), `src/cron/cron-input.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Cron-style `CronJob`s. Read `docs/cron-discovery.md` first; distinct from legacy `ScheduledRun` (`/api/scheduled`) — see Key Patterns |
-| **Agents**       | `src/subagent-watcher.ts` ★, `src/team-watcher.ts`, `src/bash-tool-parser.ts`, `src/transcript-watcher.ts`, `src/workflow-run-watcher.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                    | `workflow-run-watcher` is STANDALONE (never touches `subagent-watcher`) — see Key Patterns                                            |
-| **AI**           | `src/ai-checker-base.ts`, `src/ai-idle-checker.ts`, `src/ai-plan-checker.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                       |
-| **Tasks**        | `src/task.ts`, `src/task-queue.ts`, `src/task-tracker.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                                       |
-| **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`, `src/remote-hosts.ts` (remote SSH hosts/cases — see Key Patterns), `src/remote-reconnect.ts` (pure COD-108 auto-reconnect backoff/eligibility; watcher lives in `tmux-manager.ts`), `src/docker-hosts.ts` + `src/docker-export.ts` (docker hosts/cases + export/import — see Key Patterns)                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                       |
-| **Search**       | `src/search-service.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Pure in-memory core for `GET /api/search` — see Key Patterns                                                                          |
-| **Attachments**  | `src/attachment-registry.ts`, `src/attachment-magic.ts`, `src/generated-artifact-attachments.ts` (Codex `Saved to:` artifacts), `src/session-attachment-history.ts`, `src/document-preview-cache.ts`, `src/document-thumbnailer.ts`, `src/document-conversion-limiter.ts`, `src/config/attachment-guard.ts`                                                                                                                                                                                                                                                                  | See Key Patterns                                                                                                                      |
-| **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`, the CLAUDE.md scaffold generated into new cases)                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                                                                                                       |
-| **Web**          | `src/web/server.ts` ★, `src/web/sse-events.ts`, `src/web/routes/*.ts` (20 route modules + barrel; `session-routes.ts` ★), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts`, `src/web/self-update.ts`, `src/web/plan-usage-latest.ts`, `src/web/ws-connection-registry.ts` (per-tab WS supersede), `src/web/heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` (HEIC→JPEG off-thread)                                                                                                                                        |                                                                                                                                       |
-| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 7 infra modules (`constants.js`, `i18n.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`, `sanitize-html.js` — DOMPurify mXSS allowlist, COD-56) + 10 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `ultracode-panel.js`, `cron-ui.js`, `settings-ui.js`, `panels-ui.js`, `admin-ui.js`, `session-ui.js`) + 6 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `ultracode-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | `i18n.js` owns English/Simplified Chinese UI localization + user-facing branding; `ultracode-windows.js` = floating run windows w/ tab connector lines                                   |
-| **Types**        | `src/types/index.ts` (barrel) → 19 domain files (incl. `workflow-run.ts`, `search.ts`, `cron.ts`, `user.ts`); also `src/types.ts` root re-export                                                                                                                                                                                                                                                                                                                                                                                                                                        | See `@fileoverview` in index.ts                                                                                                       |
+| Domain           | Key files                                                                                              | Notes                                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Entry**        | `src/index.ts`, `src/cli.ts`                                                                           |                                                                                                  |
+| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
+| **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`, `-planner`, `-verifier`                                                    | Read `docs/orchestrator-loop-architecture.md` first                                              |
+| **Cron**         | `src/cron/cron-service.ts`, `cron-time.ts` (pure next-run math), `cron-input.ts`                        | Read `docs/cron-discovery.md` first. Distinct from legacy `ScheduledRun` (`/api/scheduled`)      |
+| **Agents**       | `src/subagent-watcher.ts` ★, `team-watcher`, `bash-tool-parser`, `transcript-watcher`, `workflow-run-watcher` | `workflow-run-watcher` is STANDALONE and never touches `subagent-watcher`                        |
+| **AI**           | `src/ai-checker-base.ts`, `ai-idle-checker.ts`, `ai-plan-checker.ts`                                   |                                                                                                  |
+| **Tasks**        | `src/task.ts`, `task-queue.ts`, `task-tracker.ts`                                                      |                                                                                                  |
+| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`                                     |                                                                                                  |
+| **Infra**        | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` (pure), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns                                                    |
+| **Web tabs**     | `src/webview-store.ts`, `webview-capabilities.ts`, `src/web/webview-proxy.ts` (pure), `src/web/routes/webview-routes.ts` | Dashboard URLs as tabs; NOT a SessionMode                                                        |
+| **Search**       | `src/search-service.ts`                                                                                | Pure in-memory core for `GET /api/search`                                                        |
+| **Attachments**  | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns                                                                                 |
+| **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases                                |
+| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (20 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
+| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 23 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
+| **Types**        | `src/types/index.ts` (barrel) → 20 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
 
 ★ = Large, central file (>50KB) — read its `@fileoverview` first. 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 packages**: `packages/xterm-zerolag-input/` — local echo overlay for xterm.js; single-source, bundled to the gitignored `vendor/xterm-zerolag-input.js` and consumed by `app.js` (see Gotchas). `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).
+**Local packages**: `packages/xterm-zerolag-input/` (local echo overlay, single-source, see Gotchas). `packages/gesture-control/` (`codeman-gesture-control`, hand-tracking overlay source, built via `npm run build:gesture`).
 
-**Config**: `src/config/` — 16 files, no barrel (`index.ts`) exists; import from the specific file.
+**Config**: `src/config/` — 17 files, no barrel (`index.ts`) exists; import from the specific file.
 
 **Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-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).
 
@@ -160,108 +177,111 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Key Patterns
 
-**Input**: `session.writeViaMux()` for programmatic/curl input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only (fire-and-once). Interactive **browser** input goes through a durable **exactly-once** layer: each frame carries a stable `clientId` + monotonic per-session `seq`, persisted to localStorage until the server ACKs (`{t:'ia',seq}` over WS, or HTTP 2xx), so a dropped link/reconnect can't lose or double-deliver a prompt. **WS resilience** (#149): the upgrade URL carries `cid = clientId + ':' + perTabNonce`, and `ws-connection-registry.ts` supersedes only same-TAB reconnects (two tabs on one session coexist; input frames keep the bare `clientId` for seq dedup); reconnects back off exponentially (attempts preserved across `_connectWs`), and the header connection chip renders from a real `_wsState` lifecycle (`connecting`/`connected`/`fallback`/`reconnecting`/`disconnected`).
+**Input**: `session.writeViaMux()` for programmatic/curl input via tmux `send-keys -l` + `send-keys Enter`, single-line only. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
-**Auto-resume on usage limit** ("token pause" control, opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit ("5-hour limit reached ∙ resets 8pm" and all 1.0.x–2.1.x variants), `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time from cleaned output; `SessionAutoOps` arms a timer for reset+2min, then sends Esc (dismisses the rate-limit dialog) + `continue`. Still-limited responses re-arm the loop (5-min retry on stale times); a `working` transition cancels it. Claude-mode only (detection rides `_processExpensiveParsers`). Persists/recovers via `SessionState.autoResumeEnabled`/`autoResumeAt`; respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected` — prevents `/clear` from wiping the paused conversation). Endpoint: `POST /api/sessions/:id/auto-resume`; SSE: `session:limitPauseScheduled`/`limitResume`/`limitResumeCancelled`. Tests: `test/usage-limit-patterns.test.ts`, `test/session-auto-resume.test.ts`.
+**Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit)
 
-**Plan-usage chip** (statusLine telemetry, opt-in `showPlanUsageLimits`, default OFF): Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through** (so injecting our statusLine doesn't blank the in-terminal footer). `plan-usage-latest.ts` holds the process-wide last value, replayed in the SSE init snapshot (`getLightState`) so the header chip (`#planUsageChip`, toggled by `showPlanUsageLimits` in settings-ui.js) renders immediately on page load / reconnect without per-browser localStorage. Claude-mode only. **Distinct from auto-resume** (which reacts to the limit _message_; this proactively shows the live %). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`.
+**Plan-usage chip** (statusLine telemetry, opt-in `showPlanUsageLimits`, default OFF): Codeman injects its own `statusLine.command` exporter which POSTs Claude's `rate_limits` blob to `POST /api/status-telemetry`. The exporter is identified by a marker, so it only ever adds/updates/removes a statusLine that is **ours**, never a user's hand-authored one, and it prints the footer through so the in-terminal statusline is not blanked. Claude-mode only; distinct from auto-resume, which reacts to the limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.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`.
 
-**Cron (cron-style `CronJob`s)**: saved, named jobs with a recurring schedule (`once`/`interval`/`daily`/`weekly`), enable/disable, Run Now, next-run calc, and per-job run history (`CronJobRun`). ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded autonomous loop) — the two never interact; the legacy concept keeps the `Scheduled*` names, the recurring-job feature is `Cron*`. `CronService` (`src/cron/cron-service.ts`) owns CRUD + the 30s background due-tick (`tickDueJobs`, registered via `cleanup.setInterval` in `server.ts`; `init()` recomputes nextRunAt on boot) and **reuses the existing session layer** (create → `addSession` → `setupSessionListeners` → `startInteractive`/`startShell` → prompt via `writeViaMux`/`write`) rather than rebuilding tmux logic. Next-run math is pure/unit-tested in `cron-time.ts` (SERVER-LOCAL timezone for daily/weekly). Dup-launch guard = `lastDueKey` (jobId:fireTime); schedule is advanced BEFORE launch so a slow launch can't re-trigger. `once` jobs self-disable after firing (`completedOnce`). Persisted via `AppState.cronJobs`/`cronJobRuns` (StateStore accessors). Routes `/api/cron/jobs*` + `/api/cron/runs` (`cron-routes.ts`, `CronPort`); schema `CronJobSchema` (cross-field `superRefine`; the `.partial()` update schema does NOT re-run it); SSE `cron:*`. Frontend `cron-ui.js` (#cronModal). Claude/shell/opencode/codex/gemini agent types. Tests: `test/cron-time.test.ts`, `test/cron-service.test.ts`. Design: `docs/cron-discovery.md`.
+**Cron (`CronJob`s)**: saved, named jobs on a recurring schedule (`once`/`interval`/`daily`/`weekly`) with per-job run history. ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded loop); the two never interact and keep separate `Scheduled*` / `Cron*` names. `CronService` **reuses the existing session layer** rather than rebuilding tmux logic. Next-run math is pure and unit-tested in `cron-time.ts` (server-local timezone). The schedule is advanced BEFORE launch so a slow launch cannot re-trigger. → [architecture-invariants#cron-jobs](docs/architecture-invariants.md#cron-jobs), `docs/cron-discovery.md`
 
-**Remote sessions (SSH)**: Sessions can run the agent inside a durable `tmux -L codeman-remote new-session -A` **on a remote host** so it survives the SSH drop (COD-104), and can also **discover + attach** to `codeman-*` sessions another Codeman launched there — attached (`owned:false`) sessions **detach, never kill** on tab close (COD-105). **Shared/collaborative** (COD-106): remote set-options are scoped per-session (never `-g`) and `window-size latest` lets multiple clients attach the same session at different viewports without clamping to the smallest; a client count surfaces a "shared · N" badge. **Auto-reconnect** (COD-108): a bounded-backoff watcher re-establishes a dropped remote session's local ssh pane and reattaches the still-running durable remote tmux (kill-switch `remoteAutoReconnect`, default ON); the pure pieces (backoff schedule, per-session reconnect state, `decideReconnect` eligibility) live in `src/remote-reconnect.ts` (tests: `test/remote-auto-reconnect.test.ts`), while `tmux-manager.ts` owns the live pane probe + timers. Owned sessions propagate `kill-session` to the remote on close; non-owned never do. ⚠️ Command-injection surface (COD-107): all ssh command lines flow through the single shell-safe `buildSshConnectionArgs()` — every user field (`-J jumpHost`, `-i identity`, `-o`) is `shellescape`d; never hand-build an ssh line elsewhere. Full design: `docs/remote-sessions.md`.
+**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md`
 
-**External CLI modes (OpenCode, Codex, Gemini)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All three modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Codex CLI tab; Respawn/Ralph options are Claude-only, so session options open on the Summary tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM).
+**Docker cases**: a case can point at a **container**, with any of the five CLI backends running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
 
-**Run launch synchronization**: the main Run entrypoint in `session-ui.js` holds an in-flight lock and disables `#runBtn` for the whole launch (at least 500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. A successful create/quick-start also calls `_ensureCreatedSessionVisible()` before `selectSession()`: local creates use the response's full session snapshot; quick-start modes fetch `GET /api/sessions/:id` only when `session:created` SSE has not already populated the map. The normal `_onSessionCreated()` handler remains the idempotent upsert, so POST-first and SSE-first ordering both produce one immediately-rendered tab. Tests: `test/run-mode-ui.test.ts`.
+**External CLI modes (OpenCode, Codex, Gemini)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All three **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. → [architecture-invariants#external-cli-modes-opencode-codex-gemini](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini)
 
-**Remote SSH cases** (COD-94/#145): cases can point at a **remote host** (`~/.codeman/remote-hosts.json` + `remote-cases.json` via `src/remote-hosts.ts`; CRUD under `/api/cases` — cases route file). A remote session launches a LOCAL tmux pane running `ssh <host>` that creates a durable REMOTE tmux session on a **dedicated socket** `-L codeman-remote` with name `codeman-ssh-<id>` — deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so a Codeman instance on the target host never adopts it; no `-g` global tmux options are set remotely. `remotePath`/`identityFile` are schema-guarded against shell injection (backticks/`$` rejected — same approach as `extraSshOptions`); remote tmux availability is probed via `checkRemoteTmuxAvailable()` in quick-start (ssh args carry `-o ConnectTimeout=10`). Remote claude defaults to `exec claude --dangerously-skip-permissions`; per-host `commands.*` override. Session kill best-effort kills the remote tmux too. `SessionState.remote`/`MuxSession.remote` round-trip through recovery (`restoreMuxSessions` passes `remote` back into the Session constructor). ⚠️ Run flows must route remote cases through `POST /api/quick-start` (which resolves the remote case and skips LOCAL CLI availability gates) — `POST /api/sessions` stat-validates `workingDir` locally and has no `caseName`. `envOverrides`/`effort`/`modelOverride`/`codexConfig`/`geminiConfig` are rejected for remote quick-starts (not silently dropped). UI: Create Case modal → Remote tab. Tests: `test/remote-hosts.test.ts`, `test/remote-ssh-options.test.ts`.
+**Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
 
-**Docker cases** (shipped 1.4.0; user guide `docs/docker-cases.md`, design `docs/docker-cases-plan.md`): a case can point at a **container** instead of a local/remote path, and any of the five CLI backends runs INSIDE it. Like remote-SSH, it is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`** (`SessionMode` is unchanged). Storage `~/.codeman/docker-hosts.json` + `docker-cases.json` via `src/docker-hosts.ts` (direct mirror of `remote-hosts.ts`: `readDockerHosts`/`readDockerCases`, `toSessionDocker`, `dockerDisplayPath`, and the PURE builders `buildDockerBaseArgs`/`buildDockerCreateArgs`/`containerApiUrl`/`hostGatewayAlias`/`dockerConfigHash`). CRUD `/api/docker-hosts` + `/api/cases/docker-link`, plus **one-click** `/api/cases/docker-quickcreate` (Create New "Run in Docker" checkbox → case folder in `CASES_DIR` + auto-provisioned shared `default` host + auto-start a session inside; an expandable Template picker Small/Medium/Large/GPU or any override creates a per-case `q-<name>` host), and export/import (`/api/docker-cases/:name/export`, `/api/docker-cases/import`, `GET/DELETE /api/docker-exports`) — all in `case-routes.ts`. Run flows route through `POST /api/quick-start` like remote (session-routes.ts docker branch, skips LOCAL CLI-availability gates). **Launch model**: exactly one long-lived container **per case** (`codeman-case-<slug>`, PID1 `sleep infinity` under `--init`); a LOCAL tmux pane runs `docker exec -it` into a **durable in-container tmux** on dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>` (deliberately fails `SAFE_MUX_NAME_PATTERN` so a Codeman running INSIDE the container never adopts it, exactly like remote's `codeman-ssh-<id8>`). Builders `buildDockerLaunchCommand`/`buildDockerKillCommand` in `tmux-manager.ts` (image-check → `docker inspect||create` → start → exec, all idempotent). The container is **shared by all sessions of the case**: `buildDockerKillCommand` kills ONLY that session's in-container tmux session, NEVER `docker stop` while siblings remain; `docker rm -f` happens only on case-delete (plus an instance-scoped boot reaper keyed on the `codeman.instance` label). **Two-layer durability/resume** (the central design point): (1) Codeman-PROCESS restart with the container still up → `tmux new-session -A` reattaches the SAME live agent (paneCommand ignored); (2) container stop/reboot/OOM → inner tmux is gone, so the re-run pane command resumes the conversation from the bind-mounted transcript: claude mode pins a DETERMINISTIC conversation id via `claudeDockerPaneCommand()` (`tmux-manager.ts`) — fresh launch `claude --session-id <sessionId> || claude --resume <sessionId>` (a duplicate `--session-id` exits 1 "already in use", so the fallback RESUMES after a container stop; verified CLI behavior), explicit resume `--resume <rid> || --session-id <sid>` so a stale id never dead-panes (leading `exec ` is stripped — an exec'd first branch could never fall back); codex `resume <id>` / gemini `--resume` keep `appendResumeFlag`. The resume id rides `resumeSessionId` through create/respawn options and persists on `DockerCase.lastClaudeSessionId` via `persistDockerCaseClaudeSessionId()` (written at quick-start launch, and again on hook/last-response conversation-id adoption so post-`/clear` switches track; seeded back when `resumeOnStart`, default true); `-A` makes the pane command self-selecting (inert on reattach, active only when tmux was re-created). **Config drift** (`dockerConfigHash` → `codeman.confighash` label): quick-start compares via `checkDockerConfigDrift()` and REFUSES a drifted launch with `CONFLICT`; the UI confirm calls `POST /api/docker-cases/:name/recreate` (refused while case sessions are live) which `docker rm -f`s so the next launch recreates with the new config — host config edits actually take effect. **Workspace** is a REAL host dir bind-mounted at the SAME absolute path (mirror, `dst==src`), so `Session.workingDir = hostWorkspacePath` keeps file-routes/attachments/watchers on real host bytes AND the in-container transcript projHash matches the host so subagent/workflow correlation (and thus resume-id capture) works; `resolveMuxAttachCwd` returns `/tmp` for docker (the local pane only runs `docker exec`). **Creds** arrive commit-safe and ISOLATED (1.4.1; replaced the whole-dir RW mounts that let in-container CLIs write refreshed tokens/state back to the host): shared RW across the boundary is ONLY what host-side reads/resume need (`~/.claude/projects` transcripts; codex `sessions/` + `history.jsonl` for response-viewer/`codex resume`); everything else is SEEDED (RO mount, copied into container HOME once at launch via `[ -e ] || cp`; the container refreshes its own copy and never writes back): `~/.claude.json` is merged through `buildSeamlessClaudeConfig()` (forces `hasCompletedOnboarding` + theme + workspace trust, so no login wizard/theme picker/trust prompt inside the container), plus `.claude/{.credentials.json,settLine truncated
-
-**Unified session list** (COD-160/#139): `GET /api/sessions/unified?limit=&q=` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows are keyed by conversation UUID and folded into their owning session via a `claudeSessionId → Codeman id` alias map (resumed//clear-respawned sessions must not appear twice); lifecycle name/mode resolution is first-seen-wins (the log returns entries NEWEST-first). No terminal buffers in the response (unlike `/api/sessions`). Consumed by the Cmd+K Session Manager (#146). Session Manager polish (COD-162/#157, 1.6.0): **pinning** via `POST /api/sessions/:id/pin` (`session:pinned` SSE; killing a pinned session demotes it to a lightweight stopped record that stays visible/resumable, and cleanup skips pinned records); **cross-device tab order** via `PUT /api/session-order` (`session:orderChanged` SSE, persisted in `state.json`; pure `normalizeSessionOrder`/`mergeSessionOrder` in `src/session-order.ts`: pushing device wins, server-only ids fall to the end, never dropped); resume from the manager keeps the original session name (COD-143); `firstPrompt` is backfilled for sessions whose id != transcript UUID and the most recent prompt (`lastPrompt`) is shown + searched (COD-140/145).
+**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
 
 **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`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`.
 
 **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`. **Distinct: PTY-exit breaker** (COD-115/118/#147, `session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits (crash loops on attach), blocks further auto-restarts, broadcasts SSE `session:respawnBreakerTripped` + push (in `PUSH_EVENT_MAP`). Reset ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive` (sent by the user-facing restart control) — the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. Sessions also scrub inherited `TMUX`/`TMUX_PANE` env so Codeman-in-tmux doesn't nest. Tests: `test/respawn-pty-breaker.test.ts`.
+**Circuit breakers**: the Ralph breaker prevents respawn thrashing (`CLOSED` → `HALF_OPEN` → `OPEN`; reset via `/api/sessions/:id/ralph-circuit-breaker/reset`). **Distinct: the PTY-exit breaker** (`session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits and blocks auto-restarts. ⚠️ It resets ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive`; the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. → [architecture-invariants#circuit-breakers-ralph--pty-exit](docs/architecture-invariants.md#circuit-breakers-ralph-and-pty-exit)
 
-**Full-scrollback replay** (COD-164/#148): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). Only the FIRST buffer load after a page load requests `full=1` (one-shot `_initialFullBufferLoad` flag in app.js); tab switches keep the cheap `?tail=` visible-frame path. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`.
+**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. Only the FIRST buffer load after a page load requests `full=1`; tab switches keep the cheap `?tail=` path. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
 
-**Self-update** (App Settings → Updates): in-app updater for **git-clone installs** supervised by systemd/launchd. Supervisors: `systemd` (user unit), `launchd` (GUI LaunchAgent, gui-domain kickstart), `launchd-daemon` (KeepAlive system LaunchDaemon on headless Macs — restarts rootlessly by killing the server PID and letting launchd respawn it; detected only when the daemon is bootstrapped AND KeepAlive), else `none` → "restart manually" message; on next boot a manual-restart status auto-completes when the running version matches the target. The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` (`git checkout <release tag> && npm install && npm run build && restart`) that outlives the restart; it writes progress to `dataPath('update-status.json')`, which the browser polls across the connection drop. Channel = latest `codeman@X.Y.Z` release tag; dirty trees are auto-stashed. `src/web/self-update.ts` splits PURE helpers (semver/tag parsing, reconcile decision — unit-tested) from IO wrappers (`getInstallInfo`/`checkForUpdate`/`startUpdate`/`reconcileUpdateOnBoot`). Routes: `GET /api/system/update/check`, `POST /api/system/update`, `GET /api/system/update/status`. Types: `src/types/update.ts`. npm installs report as non-updatable.
+**Self-update** (App Settings → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
 
-**Attachments** (live external document references; COD-37/#119 core, COD-38/#120 previews, COD-39/#121 history): all wiring in `file-routes.ts`. **Registry** (`attachment-registry.ts`): an **in-memory** map of a stable `attachmentId` → an absolute, `realpath`-resolved, extension-allowlisted file path, so browser requests (`GET /api/sessions/:id/attachments/:attachmentId/raw`) never carry arbitrary absolute paths; `POST /api/sessions/:id/attachments` registers one. **Magic links** (`attachment-magic.ts`): parses `codeman://attach?...` out of terminal output — ⚠️ this scanner is prompt-injectable, so the scan path is **force-confined to the session workspace** (a hostile prompt could otherwise make it read arbitrary host files over SSE); emits the `attachment:detected` SSE event. Security gate is an extension **allowlist** (`isSupportedAttachmentExtension`, in the registry/magic modules), not a blocklist; a separate path layer (`config/attachment-guard.ts`) confines reads to the workspace (`attachmentConfineToWorkspace`) and blocks sensitive trees (`/root`, `/etc`). **Previews + thumbnails** (COD-38): `:attachmentId/preview` + `:attachmentId/thumbnail` (and the workspace-file equivalents `file-preview`/`file-thumbnail`) render Office docs/PDFs via external converters (`pdftoppm` / LibreOffice `soffice` / Word-COM `powershell`); `document-preview-cache.ts` is a shared disk cache (de-dups _identical_ in-flight inputs), `document-thumbnailer.ts` does best-effort first-page images, and `document-conversion-limiter.ts` is a **global converter-spawn concurrency cap** (`runWithConversionLimit`) — without it, N distinct large docs detected at once fork N multi-minute converter processes = a localhost fork-bomb-shaped resource-exhaustion vector. **History drawer** (COD-39): `session-attachment-history.ts` tracks the last `ATTACHMENT_HISTORY_LIMIT` (100) attachments per session (`Session._attachmentHistory`, persisted via `SessionState.attachmentHistory`, replayed so externals re-register on reconnect); `GET /api/sessions/:id/attachments` is the list endpoint. ⚠️ The history drawer's launcher button is desktop-only — hidden on phones (regression-guarded; see `mobile-header-buttons-policy` test). Session-local files keep using the existing workspace-scoped `file-routes` paths; the registry is only for explicit live externals. **Codex generated artifacts** (COD-166/#150, `generated-artifact-attachments.ts`): codex-mode sessions ALSO scan (ANSI-stripped) output for `Saved to: file:///…` lines and surface those files as attachment cards with a relaxed trust policy — the allow decision runs on the **realpath-resolved** path against `os.homedir()`-anchored `~/.codex` marker dirs (symlink escapes fall back to force-confinement); gated to `mode === 'codex'` only (`source` is a REQUIRED param through the listener-deps chain — a dropped arg here silently kills the feature). Image thumbnails pass through jpg/jpeg/gif/webp.
+**Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments)
 
-**Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a COMPLETION artifact per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json` (written only at run end); LIVE in-flight runs exist only as transcript dirs at `…/subagents/workflows/wf_<id>/` (journal.jsonl + agent-\_.jsonl). `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; separate singleton, though it independently reads the same `subagents/workflows/` tree) scans BOTH sources via periodic poll + per-directory chokidar watchers with per-source mtime skip (LRU agentStatCache + journalCache), synthesizing ACTIVE runs (live per-agent tokens/tools/state from transcripts, title/phases from the workflow script) until the completion `wf\__.json`appears and supersedes, and broadcasts SSE`workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is started when **either** `showUltracodeAgents`**or**`ultracodeFloatingWindows` is on (`server.ts` `isWorkflowAgentTrackingEnabled()`returns`(showUltracodeAgents ?? false) || (ultracodeFloatingWindows ?? false)`). Served via `GET /api/workflows`(optional`?minutes=`filter) and`GET /api/workflows/:runId`. Frontend `ultracode-panel.js`renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side`agentId`join). **Additionally**,`ultracode-windows.js`auto-pops a draggable **floating window per active run** (gated on a **DEDICATED**`ultracodeFloatingWindows`toggle, default OFF — independent of the dock panel's`showUltracodeAgents`; see `\_ultracodeFloatingEnabled()`), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines`SVG from the tail of`\_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Clicking an agent card opens an **in-page** connected transcript window (not a browser popup); both run and transcript windows minimize **into** the originating session tab as a merged `ULTRA`badge (🧬 runs / 📄 transcripts) with a restore/dismiss dropdown — minimized runs are skipped by auto-pop. Gesture beta: floating subagent/ultracode windows are pinch-draggable (a`window`grab kind in`entry.ts`). Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
+**Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
 
-**Cross-session search** (COD-113/#133): `GET /api/search?q=&types=&limit=` federates an **in-memory** search across all live sessions — session metadata (name/workingDir/id), run-summary events, and per-session attachment-history file entries (workspace-relative path only; the server-private `externalPath` is never read). Pure core `searchSources()` in `search-service.ts` (substring-matches with hard per-type caps — no regex, so no ReDoS; no filesystem reads, so no traversal); `harvestSources()` in `search-routes.ts` gathers the in-memory sources. `SearchQuerySchema` bounds `q` (1–200), allowlists `types` (`session,event,file`), clamps `limit` (1–60). Returns the `{success,data}` envelope. Frontend: history-panel search box in `terminal-ui.js`. Types: `src/types/search.ts`.
+**Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
 
-**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default; shipped 1.5.0 via PR #161, design `docs/multi-user-plan.md`): named users with individually scrypt-hashed passwords in `~/.codeman/users.json` (via `src/user-store.ts`: atomic 0600 write, short-TTL cache, SERIALIZED read-modify-write so a fire-and-forget `touchLastLogin` can't clobber a concurrent route write, last-admin invariants). Gated everywhere by `isMultiUserMode()` (`src/config/multiuser.ts`); when OFF, behavior is byte-identical to single-user (all scoping helpers short-circuit). ⚠️ **Not a security boundary at the agent layer** — every session still runs as the SAME OS account; this separates WORKSPACES, it does not sandbox users (Docker cases are the isolation story). Auth: a PARALLEL async branch in `middleware/auth.ts` (single-user branch untouched) verifies `username:password` against the store, mints identity-carrying cookies (`AuthSessionRecord` gains `username`/`role`/`mustChangePassword`), decorates `req.authUser` (Fastify augmentation; single-user leaves it undefined and the ownership helpers default to a synthetic admin), enforces a per-username failure bucket + the `mustChangePassword` lockbox. Ownership threads through `Session.owner` (stamped from `req.authUser`/`job.owner` at every `new Session()`, round-tripped via `MuxSession.owner` on recovery); `findSessionOrFail(ctx,id,req)` does a NOT_FOUND owner check; list endpoints + `getLightState` + SSE (`deriveSseHint` routes session-scoped events by owner, fail-closed; machine-level + host-plan telemetry admin-only) + WS + search + file-preview all filter by owner. §6.3 permission policy: non-granted users are forced to `--permission-mode auto` (via `resolveClaudeModeForUser` at all spawn sites, incl. one-shots because `buildPromptArgs` now respects the session mode), and shell mode / cron `launchCommand` require the `canBypassPermissions` grant. Cases live in per-user `~/codeman-users/<name>/cases` (`resolveCasesDir`); a non-admin's `workingDir` is realpath-confined there; host CRUD is admin-only. Admin API `src/web/routes/admin-routes.ts` (`/api/admin/users*`, one-time passwords, audit log `admin-audit.jsonl`) + self-service `/api/me` + `/api/me/password` (`me-routes.ts`); frontend `public/admin-ui.js` (identity boot, change-password modal + interceptor, admin Users tab, and the header **Admin Panel** button `#adminPanelBtn`: ships `btn-admin-panel--hidden`, revealed for admins in multi-user mode, phone-hidden via mobile.css; opens the full Admin Panel modal with user CRUD, per-user permission toggles, and case-folder list/delete via `GET/DELETE /api/admin/users/:username/cases[/:caseName]`; live-refreshes on SSE `admin:usersChanged`, wired in app.js). CLI `codeman users add|passwd|list|rm`. Per-user session cap via `sessionCapacityState`/`sessionCapacityMessage`. Tests: `test/user-store.test.ts`, `test/multiuser-auth.test.ts`, `test/ownership-scoping.test.ts`, `test/admin-routes.test.ts`, `test/admin-ui.test.ts`.
+**Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside agent sessions. **NOT a sixth `SessionMode`** (no PTY, no tmux, no respawn), same reasoning that keeps Docker/remote-SSH as case overlays. Dashboards are **proxied through Codeman's own origin** by default, because a direct iframe fails three ways at once: prod is HTTPS so `http://` targets are blocked as mixed content, many dashboards send `X-Frame-Options: DENY`, and our own `default-src 'self'` CSP blocks cross-origin frames. Proxying leaves the prod CSP unchanged (`/webview/...` is `'self'`). ⚠️ The proxy is **NOT an API surface**: it authenticates on an in-memory capability in the path and is correspondingly exempt from the cookie + Origin checks; that exemption is fenced to safe methods and non-`/api` paths and is pinned by `test/webview-auth-exemption.test.ts`. ⚠️ Iframes omit `allow-same-origin` unless a dashboard is explicitly marked `trusted`, and `Authorization`/`codeman_session` are stripped upstream in **both** modes so `CODEMAN_PASSWORD` cannot leak. ⚠️ A sandboxed frame is **opaque-origin**, which breaks two things `curl` can never reproduce: its runtime-built root-absolute URLs escape `<base>` (fixed by an injected `runtimeUrlShim()`), and its same-host `fetch`/XHR are CORS-checked with `Origin: null` (fixed by `buildProxyCorsHeaders()` plus exempting the proxy from the global `OPTIONS`-204 short-circuit in `registerSecurityHeaders`). Both present as the dashboard's own "Failed to fetch" while the page renders fine. → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
 
-**Away digest** (COD-41/#136): `GET /api/away-digest?range=&since=&until=&lastViewed=` aggregates "what happened while you were away" from the lifecycle log + run-summary events + live sessions + daily token stats + recently-completed subagents into needs-attention/completed/still-running/idle/informational sections. Pure aggregator in `web/away-digest.ts` (`resolveAwayDigestRange()` validates the window — `since-last-visit`/`1h`/`today`/`24h`/`custom`, server-local TZ; `buildAwayDigest()` classifies). Header-button modal in `panels-ui.js` (button hidden on phones — regression-guarded). ⚠️ Returns `{success:true,digest}` (a legacy raw-ish shape, consistent with the other raw GET handlers in `system-routes.ts` — `{entries}`/`{config}`/`{files}`/`getSystemStats()`); frontend + tests read `.digest`. Subagent lookback is a fixed 60-min window regardless of range.
+**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
 
-**Ralph todo-config** (COD-79/#135): per-session `maxTodos` (FIFO-eviction cap, default 500 = `MAX_TODOS_PER_SESSION`) + `todoExpirationMinutes` (auto-expiry, default 60) set via `POST /api/sessions/:id/ralph-config` (`RalphConfigSchema`, both `.int().positive()`). Stored on the tracker (`setMaxTodos`/`setTodoExpirationMinutes`) and **persisted/read-back via `RalphTrackerState`** (surfaced in the `loopState` getter → `toState()` + SSE broadcast → modal `populateRalphForm`), mirroring how `maxIterations` round-trips. Claude-only (skipped by `isExternalCliMode`).
+**Away digest**: `GET /api/away-digest` aggregates what happened while you were away from the lifecycle log, run-summary events, live sessions, token stats, and recent subagents. Pure aggregator in `web/away-digest.ts`. ⚠️ Returns `{success:true,digest}`, a legacy raw-ish shape consistent with the other raw GET handlers in `system-routes.ts`; frontend and tests read `.digest`. → [architecture-invariants#away-digest](docs/architecture-invariants.md#away-digest)
+
+**Ralph todo-config**: per-session `maxTodos` (FIFO-eviction cap, default 500 = `MAX_TODOS_PER_SESSION`) + `todoExpirationMinutes` (auto-expiry, default 60) set via `POST /api/sessions/:id/ralph-config` (`RalphConfigSchema`, both `.int().positive()`). Stored on the tracker (`setMaxTodos`/`setTodoExpirationMinutes`) and **persisted/read-back via `RalphTrackerState`** (surfaced in the `loopState` getter → `toState()` + SSE broadcast → modal `populateRalphForm`), mirroring how `maxIterations` round-trips. Claude-only (skipped by `isExternalCliMode`).
 
 **Port interfaces**: Routes declare dependencies via port interfaces (`src/web/ports/`). Routes use intersection types (e.g., `SessionPort & EventPort`).
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `webview-tabs.js`(12.5) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
 
-**Command palette + shortcut registry** (COD-151/153/157/192, #146): `Ctrl/Cmd/Alt+K` opens the session palette (fuzzy search over live sessions; "Browse all sessions" → the Session Manager modal backed by `GET /api/sessions/unified`); the quick-start case `<select>` is fronted by a searchable picker (`buildCasePickerOptions`/`formatCasePickerLabel` — remote cases render `name @ hostId`). Shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js; overrides persist under `settings.shortcutOverrides` via `saveAppSettingsToStorage`); App Settings → Shortcuts renders capture/disable rows; `Ctrl+?` opens the registry-driven overlay (footer links to the full `#helpModal` reference). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM — keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over.
+**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)
 
-**WebGL renderer toggle** (#140, `webglRendererEnabled`): per-device (`displayKeys` set, stripped from the server payload — NOT in `SettingsUpdateSchema`, which is `.strict()`). The GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads; it's cleared only by an explicit OFF→ON save transition or `?webgl=force` (`shouldSkipWebGL` in constants.js). `?nowebgl` still forces the DOM renderer per-load.
+**Per-device vs synced settings**: the `displayKeys` set in settings-ui.js is a **client-side merge policy**, not a wire filter. A display key seeds from the server only when localStorage has no value for it, which is what prevents one device overwriting another; `showPlanUsageLimits` is additionally `delete`d from the incoming payload outright. Separately, `SettingsUpdateSchema` is `.strict()` and simply **does not declare** `skin`, `showFileViewerButton`, `showCronButton`, `webglRendererEnabled`, `localEchoEnabled`, `cjkInputEnabled`, or `extendedKeyboardBar`, so sending one of those is a validation error. The rest (`showResponseViewer`, `showPlanUsageLimits`, `language`, and most `show*` keys) ARE in the schema and do persist server-side; they are per-device by client policy only. ⚠️ Adding a new per-device setting means deciding **both** questions: membership in `displayKeys`, and presence in the schema.
 
-**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried; bug fixed in `b8cb467`), log viewers (2000), image popups (3000), local echo overlay (7).
+**Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
 
-**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** (camera hand-tracking overlay, opt-in, default OFF): `CODEMAN_GESTURE=1` makes the feature *available*; `gestureControlEnabled` turns it on. The bundle is injected by `renderIndexHtml` only when enabled, which is why that method is `async` and reads settings with `readSettings(true)` (a fresh read: a post-save reload lands inside the 2s cache TTL and would otherwise render the pre-toggle state). **Source lives in `packages/gesture-control/`; edit there, run `npm run build:gesture`, and commit the regenerated bundle** because dev serves the committed bundle with no runtime bundler. The MediaPipe wasm + model are fetched separately and gitignored. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision`. → [architecture-invariants#gesture-control-the-source-package](docs/architecture-invariants.md#gesture-control-the-source-package)
 
-**Response-viewer (eye) button** (header) is likewise **hidden by default** — enable under App Settings → Display → **Response Viewer** (`showResponseViewer`). Works for Claude AND Codex sessions (#152): Codex last-responses are located via a 4-layer rollout resolution under `CODEX_HOME` (history pin → originator match → resume-UUID → cwd fallback with other-pane exclusion), with injected-context filtering and event/legacy dedup — tests in `test/routes/session-routes-codex-last-response.test.ts`. Purely client-side (no `renderIndexHtml` step): the template ships with `btn-response-viewer-header--hidden` and `applyHeaderVisibilitySettings()` (settings-ui.js) toggles it after settings load. Hiding must go through that marker class — the base rule is `display:inline-flex !important`, so an inline style can't override it. `showResponseViewer` is in the `displayKeys` per-device set (settings-ui.js), so it does NOT sync across devices.
+**Theme skins / branding / i18n**: `skin` selects a palette via `data-skin` on `<html>`, applied by an **inline pre-paint script** in `index.html` reading `localStorage['codeman:skin']` to avoid a flash of wrong theme. `displayName` changes user-facing browser branding only and must NEVER rename npm package, CLI, API, storage, CSS, or protocol identifiers. `language` (`en`/`zh-CN`) keeps English as the canonical source so live switching stays reversible. User display names flow through `textContent`/attribute APIs and the server title's HTML escaper, never `innerHTML`. → [architecture-invariants#theme-skins](docs/architecture-invariants.md#theme-skins)
 
-**File Viewer button** (header, 1.4.1) is likewise **hidden by default**: enable under App Settings → Display → **Header Displays** → File Viewer (`showFileViewerButton`, also in the per-device `displayKeys` set). Purely client-side like the response viewer: the template ships `btn-file-viewer--hidden` and `applyHeaderVisibilitySettings()` toggles the marker class after settings load. The button toggles the file-browser panel open/closed without opening the settings modal (`panels-ui.js`). The **Cron toolbar button** joined the same opt-in pattern in 1.6.0: template ships `btn-cron--hidden`, `applyHeaderVisibilitySettings()` toggles it via the per-device `showCronButton` setting (default OFF, App Settings → Display → Header Displays); cron jobs themselves are unaffected.
+**Foldable settings identity**: responsive layout is width-driven via `MobileDetection.getDeviceType()`, but the localStorage namespace uses `MobileDetection.isHandheldDevice()` so an unfolded Android foldable keeps `codeman-app-settings-mobile`. ⚠️ Do not switch per-device settings namespaces from instantaneous viewport width: a posture-triggered WebView reload would lose opt-in UI. Regression profile: `OPPO Find N5 (unfolded)` in `test/mobile/devices.ts`. → [architecture-invariants#foldable-settings-identity](docs/architecture-invariants.md#foldable-settings-identity)
 
-**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).
+**WebGL renderer toggle** (`webglRendererEnabled`, per-device): the GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads and is cleared only by an explicit OFF→ON save or `?webgl=force`. `?nowebgl` forces the DOM renderer per-load. → [architecture-invariants#webgl-renderer-toggle](docs/architecture-invariants.md#webgl-renderer-toggle)
 
-**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`.
+**Phone toolbar: Enter replaces Shell** (post-1.8.0): inside `@media (max-width: 430px)` `btn-shell` is `display:none` and `btn-enter` takes its slot (`order: 4`); starting a shell moved into the Run dropdown (`Terminal / Shell` → `setRunMode('shell')` → `run()` → `runShell()`, button label "Run SH"). `runMode` is `z.string().max(20)` server-side, so new modes need no schema change. Desktop and tablet keep the green Run Shell button unchanged.
 
-**Theme skins** (App Settings → Display): the `skin` setting selects a palette via a `data-skin` attribute on `<html>`. Values: `daylight-blue` (default), `daylight-green`, `og` (OG Codeman). CSS lives under `[data-skin="…"]` blocks in `styles.css`. To avoid a flash-of-wrong-theme, an **inline pre-paint script** in `index.html` (`<head>`) reads `localStorage['codeman:skin']` and sets `data-skin` before first paint; `settings-ui.js` `applySkin()` applies it live on save (sets `html[data-skin]` + `window.__codemanSkin`, syncs the standalone `codeman:skin` key with the settings blob, and calls terminal-ui.js `applyTerminalSkin()` to re-theme live terminals). `skin` is a **per-device/client-only** setting — it's destructured OUT of the server payload (settings-ui.js, alongside `localEchoEnabled`/`cjkInputEnabled`/`extendedKeyboardBar`), so it does NOT sync across devices.
+⚠️ **`sendEnterKey()` MUST go through `terminal._core.coreService.triggerDataEvent('\r', true)`** — not `sendInput()`, and never a raw POST to `/api/sessions/:id/input`. `localEchoEnabled` defaults to `MobileDetection.isTouchDevice()`, so on every phone the characters you type are buffered in the `LocalEchoOverlay` and have **never reached the PTY**; the `onData` Enter branch in terminal-ui.js is what flushes `pendingText` first and only then sends `\r` (after an 80ms delay so text lands first). Sending a bare `\r` submits an empty line and strands the typed text on screen, so the button looks dead. Replaying the keypress reuses the overlay flush, the flushed-offset cleanup and the ordering instead of reimplementing them. `KeyboardAccessory.sendKey()` is for escape sequences (arrows/Esc) and is the WRONG template to copy for input.
 
-**Custom branding + UI language** (App Settings → Display → Branding & Language): `displayName` is schema-validated (trimmed, 1–40 chars), server-synced, and changes user-facing browser branding/window titles only — NEVER rename npm package/CLI/API/storage/CSS/protocol identifiers. `language` is a per-device `en`/`zh-CN` display key, stripped from the server payload. `i18n.js` keeps English as the canonical source/fallback, observes newly inserted application DOM for dynamic copy, preserves source strings so live EN↔ZH switching is reversible, and skips terminal/response/file/session-name/user-content surfaces. User display names flow through `textContent`/attribute APIs and the server title's HTML escaper, never `innerHTML`.
+⚠️ **Skin overrides outrank plain class rules.** `styles.css` nests its skin block inside `html:not([data-skin="og"]) { … }`, so a bare `.btn-toolbar` rule in there resolves to specificity **(0,2,1)** and beats a `.btn-toolbar.btn-x` rule **(0,2,0)** in `mobile.css` regardless of load order. Toolbar-button colors set from mobile.css therefore need `!important` — that is why mobile.css leans on it so heavily. Symptom: only your `!important` properties land and everything else silently renders in generic toolbar grey.
+
+**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried), log viewers (2000), image popups (3000), local echo overlay (7).
 
-**Foldable settings identity**: responsive layout remains width-driven through `MobileDetection.getDeviceType()`, but the localStorage namespace/defaults use `MobileDetection.isHandheldDevice()` so an Android foldable keeps `codeman-app-settings-mobile` after unfolding past the desktop breakpoint. The stable handheld check prefers explicit phone/tablet/desktop UA tokens, then `navigator.userAgentData.mobile`; Android WebView is covered by the `Mobile` UA fallback. Do not switch per-device settings namespaces from instantaneous viewport width — a posture-triggered WebView reload would lose opt-in UI such as `showResponseViewer` and `extendedKeyboardBar`. Regression profile: `OPPO Find N5 (unfolded)` in `test/mobile/devices.ts`.
 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).
 
-**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry (see Command palette above).
+**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry.
 
 ### 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.
+**Full model: [`docs/security-architecture.md`](docs/security-architecture.md)** (network binding, auth pipeline, the tunnel caveat, file-serving hardening, supply-chain, instance isolation, recommended setups). **Layer-by-layer detail with the history behind each: [architecture-invariants#security-layers](docs/architecture-invariants.md#security-layers).**
 
-| Layer             | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Auth**          | Optional HTTP Basic via `CODEMAN_USERNAME` (defaults to `admin`) / `CODEMAN_PASSWORD` env vars. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **Network bind**  | Defaults to `127.0.0.1` (loopback). A non-loopback bind (`--host`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **starts but warns loudly** (0.9.0; was fail-closed in COD-29/#107). `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges the warning. Classifier: `network-auth-policy.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **Host guard**    | Always-on Host-header allowlist blocks DNS rebinding (RCE on the default no-auth loopback install). Allows loopback, any IP literal, the bind host, `*.ts.net`/`*.trycloudflare.com`/`*.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS`. ⚠️ **Custom reverse-proxy domains are rejected** unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`. `registerHostGuard` in `server.ts`; policy in `network-auth-policy.ts` (`buildHostPolicy`/`isAllowedRequestHost`/`isAllowedRequestOrigin`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| **CSRF / Origin** | Always-on cross-site Origin guard rejects state-changing requests from foreign origins (covers self-update, session create/input, settings/tunnel toggles). **A missing Origin is allowed** so curl/CLI and Claude Code hooks keep working. The global body parser keeps `text/plain` RAW (no auto-JSON-parse, which had enabled simple-request CSRF); `/api/crash-diag` self-parses. WebSocket upgrade validates Origin+Host (anti-CSWSH) in `ws-routes.ts`. Added in `c669518` (closes 2026-06-09 review CRITICALs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| **QR Auth**       | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| **Sessions**      | 24h cookie (`codeman_session`), auto-extend, device context audit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **Rate limit**    | 10 failed auth/IP → 429 (15min decay). QR has separate limiter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **Hook bypass**   | `/api/hook-event` (and `/api/status-telemetry`, the statusLine exporter) skip Basic auth (localhost-only, schema-validated). When auth is active (`CODEMAN_PASSWORD` set), the loopback bypass requires the per-instance `X-Codeman-Hook-Secret` header **unconditionally** — COD-54 introduced it tunnel-gated; COD-91 (PR #127) made it always-on because Codeman can't detect a user's own loopback reverse proxy (own cloudflared/`tailscale serve`/nginx → 127.0.0.1), closing that residual plain-bypass gap. Hook curls cat the secret file at exec time via `$CODEMAN_HOOK_SECRET_FILE` (session env, `config/hook-secret.ts`); a missing/wrong secret gets 401 and rate-limits in a dedicated bucket (never locks out login). Tunnel enable **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged — via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` (env, COD-55) **or** the per-request `acknowledgeUnauthTunnel:true` action field (1.1.9): the welcome/settings tunnel toggle pops a security confirm dialog and, on confirm, resends with that flag (server logs a loud warning on every passwordless tunnel start; curl/API stay refused without password/env/flag). The flag is an action field, never persisted |
-| **Env vars**      | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies, comma-separated; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS`=1 (opt-in hooks-only listener on the docker bridge gateway so in-container hooks reach a loopback-bound server; bind IP from `CODEMAN_DOCKER_BRIDGE_HOST` or auto-detect)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Layer             | The rule                                                                                                                                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auth**          | Optional HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`)                                                        |
+| **Network bind**  | Defaults to loopback. Non-loopback without a password starts but warns loudly. Classifier: `network-auth-policy.ts`                                                                                          |
+| **Host guard**    | Always-on Host-header allowlist blocking DNS rebinding. ⚠️ **Custom reverse-proxy domains are rejected** unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`                                              |
+| **CSRF / Origin** | Always-on cross-site Origin guard on state-changing requests. **A missing Origin is allowed** so curl/CLI and hooks keep working. ⚠️ The body parser keeps `text/plain` RAW; auto-JSON-parsing it enabled simple-request CSRF |
+| **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 and hook-secret have separate buckets, so neither can lock out login                                                                                              |
+| **Hook bypass**   | `/api/hook-event` + `/api/status-telemetry` skip Basic auth (localhost-only, schema-validated), but when auth is active the loopback bypass requires `X-Codeman-Hook-Secret` **unconditionally** (Codeman cannot detect a user's own loopback reverse proxy) |
+| **Tunnel**        | Enabling a tunnel **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` or the per-request `acknowledgeUnauthTunnel:true` action field (never persisted) |
+| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`)                                                                        |
+| **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                     |
+
+**Security-relevant env vars**: `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS=1` (opt-in hooks-only listener on the docker bridge gateway).
 
 ### SSE Event Registry
 
-148 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend), incl. `docker:exportComplete`/`exportFailed`/`importComplete` and `docker:imageBuildStarted`/`imageBuildProgress`/`imageBuildComplete`/`imageBuildFailed`. Both must be kept in sync.
+149 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync** — they are currently exactly in sync, and the backend file's `@fileoverview` carries the per-category breakdown.
 
 ### API Routes
 
-~190 handlers across 20 route files in `src/web/routes/`: system (45, incl. self-update `check`/`status`/`POST /api/system/update`, `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`, `GET /api/codex/status`, `GET /api/gemini/status`, and `GET /api/away-digest`), sessions (32, incl. `GET /api/sessions/unified`, `POST /api/sessions/:id/pin`, `PUT /api/session-order`), orchestrator (10), cases (27, incl. remote hosts CRUD + remote case-link, docker hosts CRUD + `docker-link` + `docker-quickcreate` + export/import + `docker-exports`), ralph (9), plan (8), files (14, incl. attachment register + list/history + `:attachmentId/raw`/`preview`/`thumbnail` + workspace `file-preview`/`file-thumbnail`), respawn (7), admin (8, multi-user `/api/admin/users*` incl. per-user case folders), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), cron (9, cron-style `CronJob` jobs/runs), teams (2), me (2, `/api/me` + password), search (1, `GET /api/search`), hooks (1), clipboard (1), status-telemetry (1, `POST /api/status-telemetry` ← statusLine exporter), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~197 handlers across 21 route files in `src/web/routes/`: system (45), sessions (32), cases (27), files (14), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), me (2), teams (2), search (1), hooks (1), clipboard (1), status-telemetry (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 **HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 
@@ -270,15 +290,16 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 - **API endpoint**: Types in `src/types/` domain file, route in `src/web/routes/*-routes.ts`. Return the `ApiResponse` envelope (`{ success: true, data }`; errors via `createErrorResponse()` with proper status code). Validate with Zod schemas in `schemas.ts`.
 - **SSE event**: Add to `src/web/sse-events.ts` + `SSE_EVENTS` in `constants.js`, emit via `broadcast()`, handle in `app.js` (`addListener(`)
 - **Session setting**: Add to `SessionState`, include in `session.toState()`, call `persistSessionState()`
+- **App setting**: decide per-device vs synced first. Per-device keys go in the `displayKeys` set in settings-ui.js and must NOT be added to `SettingsUpdateSchema` (it is `.strict()`).
 - **Hook event**: Add to `HookEventType`, add hook in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema`
-- **Mobile feature**: Add to relevant singleton, guard with `MobileDetection.isMobile()`
+- **Mobile feature**: Add to relevant singleton, guard with `MobileDetection.isMobile()`. New header buttons must stay off phones (`test/mobile-header-buttons-policy.test.ts`).
 - **New test**: Pick unique port (search `const PORT =`). Route tests use `app.inject()` (no port needed) — see `test/routes/_route-test-utils.ts`.
 
 **Validation**: Zod v4 (different API from v3). Define schemas in `schemas.ts`, use `.parse()`/`.safeParse()`.
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, `cronJobs`/`cronJobRuns`), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` (VAPID), `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json` (linked-case registry used for case-path resolution), `remote-hosts.json` + `remote-cases.json` (remote SSH hosts/cases, COD-94), `docker-hosts.json` + `docker-cases.json` (docker hosts/cases, 1.4.0) + `docker-exports/` (portable container bundles), `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance hook secret, COD-54), `users.json` (multi-user accounts, scrypt hashes, mode 0600) + `admin-audit.jsonl` (multi-user admin action log), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
 **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 
@@ -297,9 +318,13 @@ Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pa
 
 **Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s. `config/vitest.ci.config.ts` = same minus the browser/perf excludes — keep the two configs in sync when changing shared options.
 
-**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). `test/setup.ts` additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions).
+**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). Every docker IO path is no-op'd the same way. `test/setup.ts` additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions).
 
-**Ports**: Pick unique ports manually. Search `const PORT =` before adding new tests.
+**Ports**: Pick unique ports manually, 3150+. Search `const PORT =` before adding new tests. Never 3000 (the live instance).
+
+⚠️ **Browser tests can pass vacuously on mobile input paths.** Two traps, both hit on 2026-07-27 while fixing the phone Enter button: **(1)** driving input with `app.sendInput('…')` writes PAST the `LocalEchoOverlay`, so `pendingText` stays empty and any overlay bug is invisible — type with `page.keyboard.type()` instead; **(2)** headless Chromium reports `MobileDetection.isTouchDevice()` **false even with `hasTouch: true`**, so `_localEchoEnabled` is off and the local-echo branch never executes. Force it (`app._localEchoEnabled = true`) or the test proves nothing. Assert on real state (`app._localEchoOverlay.pendingText`, plus `tmux -L codeman capture-pane -p -t <pane>` for what actually reached the PTY), not on HTTP 200.
+
+**Testing against the live instance**: prod is HTTPS-only on :3000 (`curl -sk https://localhost:3000/...`). ⚠️ `w1`/`w2`/`w3` are the user's REAL sessions — never send input to them. Create your own throwaway session (`POST /api/sessions` then `POST /api/sessions/:id/shell`; creation alone leaves `pid: null` and no pane), test against that, and `DELETE` it by exact id when done.
 
 **Respawn tests**: Use `MockSession` from `test/mocks/index.ts` (defined in `test/mocks/mock-session.ts`). **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (136 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
 
@@ -317,10 +342,14 @@ Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/scree
 
 ## Performance & Limits
 
-Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired live); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+Target: 20 sessions, 50 agent windows at 60fps. Limits live in `src/config/` (terminal 32MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100), most env-overridable.
 
-**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`.
+Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired live. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
+
+**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*()`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 
 ## Scripts & Tunnel
 
-Key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.
+**`install.sh`** (repo root, 69KB) is the public entry point: `curl -fsSL <raw url> | bash` installs Node/tmux if missing, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service. It prompts for the network binding (LAN default + password prompt) and preserves the existing binding on re-runs via `read_existing_binding()`. `install.sh update` and `install.sh uninstall` also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation.
+
+Other key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick), `scripts/run-beta.sh` (isolated beta instance), `scripts/build-agent-image.mjs` (docker base image), `scripts/self-update.sh` (detached updater). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

README.md

@@ -16,6 +16,8 @@
   <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
   <a href="https://www.npmjs.com/package/aicodeman"><img src="https://img.shields.io/npm/v/aicodeman?style=flat-square&label=npm&color=22c55e" alt="npm version"></a>
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
 <p align="center">
@@ -23,7 +25,7 @@
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo.gif" alt="Codeman — parallel subagent visualization" width="900">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
 </p>
 
 **Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, or Gemini CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
@@ -33,7 +35,11 @@
 - **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
 - **See your agents think** - [live floating windows](#live-agent-visualization) for every subagent and teammate, with real-time transcripts
 - **Nothing gets lost** - tmux persistence across restarts and network drops, exactly-once input delivery, full-scrollback replay
-- **Self-hosted and boring on purpose** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
+- **Self-hosted and private** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman dashboard tour: session tabs per case, one-click Run for new agents, live plan usage in the header" width="900">
+</p>
 
 ---
 
@@ -46,6 +52,7 @@ 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. A few things worth knowing:
 
 - **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
+- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
 - **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
 - **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
 
@@ -212,12 +219,12 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
 <table>
 <tr>
 <td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="Mobile — landing page with QR auth" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="Mobile — idle session with keyboard accessory" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="260"></td>
 <td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="Mobile — active agent session" width="260"></td>
 </tr>
 <tr>
 <td align="center"><em>Landing page with QR auth</em></td>
-<td align="center"><em>Keyboard accessory bar</em></td>
+<td align="center"><em>Answering prompts by touch</em></td>
 <td align="center"><em>Agent working in real-time</em></td>
 </tr>
 </table>
@@ -247,7 +254,12 @@ The security design addresses all 6 critical QR auth flaws identified in ["Demys
 
 ### Touch-Optimized Interface
 
+<p align="center">
+  <img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="560">
+</p>
+
 - **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard. Destructive commands (`/clear`, `/compact`) require a double-press to confirm — first tap arms the button, second tap executes — so you never fire one by accident on a bumpy commute
+- **Dedicated Enter button** — submitting is a constant need on a touch keyboard, so the phone toolbar gives it a button of its own. It replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded. Starting a shell moves into the Run dropdown (`Terminal / Shell`), which is the rarer action
 - **Swipe navigation** — left/right on the terminal to switch sessions (80px threshold, 300ms)
 - **Smart keyboard handling** — toolbar and terminal shift up when keyboard opens (uses `visualViewport` API with 100px threshold for iOS address bar drift)
 - **Safe area support** — respects iPhone notch and home indicator via `env(safe-area-inset-*)`
@@ -269,7 +281,7 @@ codeman web --https
 Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.
 
 <p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="Subagent Visualization" width="900">
+  <img src="docs/images/subagent-windows-20260724.png" alt="Subagent Visualization: three parallel Explore agents as floating windows with live tool-call feeds" width="900">
 </p>
 
 - **Floating terminal windows** — draggable, resizable panels for each agent with a live activity log showing every tool call, file read, and progress update as it happens
@@ -278,6 +290,12 @@ Watch background agents work in real-time. Codeman monitors agent activity and d
 - **Auto-behavior** — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
 - **Nested agents** — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)
 
+Multi-agent Workflow runs ("ultracode") get the same treatment: a floating run window tracks the whole workflow live, with phases, per-agent token counts, and the current tool of every agent:
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode workflow visualization: a live run window with per-agent tokens and phases" width="900">
+</p>
+
 **Agent Teams** — first-class support for Claude Code's native multi-agent teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). `TeamWatcher` polls `~/.claude/teams/`, matches teammates to their lead session, and surfaces them as live subagent windows with **team-aware idle detection** — so the Respawn Controller won't fire while teammates are still working. See [`docs/agent-teams/`](docs/agent-teams/).
 
 ---
@@ -586,11 +604,11 @@ When someone authenticates via QR, the desktop shows a notification toast with t
 
 ## Security
 
-By default Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control _who_ that is. (The startup permission mode is configurable; see below.) Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **Found a vulnerability?** See [`SECURITY.md`](SECURITY.md) for private disclosure and the list of known limitations.
+By default Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control _who_ that is. (The startup permission mode is configurable; see below.) Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **Found a vulnerability?** See [`SECURITY.md`](.github/SECURITY.md) for private disclosure and the list of known limitations.
 
 ### Network & access
 
-- **Loopback by default** — binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box. Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
+- **Loopback by default** — the server binary binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box (the guided installer asks about network access and configures the binding + password for you). Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
 - **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
 - **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers _immediately_ even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
 - **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Claude CLI → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant

README.zh-CN.md

@@ -18,10 +18,16 @@
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
   <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
+  <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo.gif" alt="Codeman — 并行子智能体可视化" width="900">
+  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — 并行子智能体可视化" width="900">
+</p>
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman 仪表盘导览：按项目分组的会话标签页、一键 Run 启动新智能体、页头实时用量" width="900">
 </p>
 
 > 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
@@ -203,12 +209,12 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 <table>
 <tr>
 <td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="移动端 — 带键盘配件栏的空闲会话" width="260"></td>
+<td align="center" width="33%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="260"></td>
 <td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
 </tr>
 <tr>
 <td align="center"><em>带二维码认证的登录页</em></td>
-<td align="center"><em>键盘配件栏</em></td>
+<td align="center"><em>触控回答提示</em></td>
 <td align="center"><em>智能体实时工作中</em></td>
 </tr>
 </table>
@@ -238,7 +244,12 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 ### 触控优化界面
 
+<p align="center">
+  <img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="560">
+</p>
+
 - **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮。破坏性命令（`/clear`、`/compact`）需双击确认 —— 第一次点击「上膛」，第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
+- **独立的 Enter 按钮** —— 在触控键盘上提交是高频操作，因此手机工具栏为它单独设了一个按钮。它会以按键的方式回放，从而先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上。启动 Shell 这类低频操作则移入 Run 下拉菜单（`Terminal / Shell`）
 - **滑动导航** —— 在终端上左右滑动切换会话（阈值 80px，300ms）
 - **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移（使用 `visualViewport` API，并对 iOS 地址栏漂移设置 100px 阈值）
 - **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
@@ -260,7 +271,7 @@ codeman web --https
 实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
 
 <p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="子智能体可视化" width="900">
+  <img src="docs/images/subagent-windows-20260724.png" alt="子智能体可视化 —— 三个并行 Explore 智能体的浮动窗口与实时工具调用日志" width="900">
 </p>
 
 - **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
@@ -269,6 +280,12 @@ codeman web --https
 - **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
 - **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
 
+多智能体 Workflow 运行（「ultracode」）同样可视化：一个浮动运行窗口实时跟踪整个工作流，展示阶段、各智能体的 token 用量与当前工具：
+
+<p align="center">
+  <img src="docs/images/ultracode-window-20260724.png" alt="Ultracode 工作流可视化 —— 实时运行窗口，含各智能体 token 与阶段" width="900">
+</p>
+
 **智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
 
 ---
@@ -577,7 +594,7 @@ URL 被刻意保持精简（`/q/` 路径 + 6 字符码 ≈ 53–56 个字符）
 
 ## 安全
 
-Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。（启动权限模式可配置，见下文。）近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。**发现了漏洞？** 私下披露方式与已知限制清单见 [`SECURITY.md`](SECURITY.md)。
+Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设计上对任何能访问到它的人都是一个远程代码执行面 —— 整套安全模型的存在就是为了控制*谁*能访问。（启动权限模式可配置，见下文。）近期加固（v0.9.0 + v0.9.5）封堵了那些常困扰自托管开发工具的浏览器驱动攻击路径。完整模型：[`docs/security-architecture.md`](docs/security-architecture.md)。**发现了漏洞？** 私下披露方式与已知限制清单见 [`SECURITY.md`](.github/SECURITY.md)。
 
 ### 网络与访问
 

docs/architecture-invariants.md

@@ -0,0 +1,192 @@
+# Architecture invariants
+
+Implementation detail extracted from `CLAUDE.md` so that file stays small enough to load into every session cheaply. Nothing here was rewritten: these are the original paragraphs, verbatim, including the version history and PR references that explain *why* each rule exists.
+
+`CLAUDE.md` keeps the short form of each rule plus a pointer to the section here. Read the pointer first; come here when you need the mechanism, the file names, or the history behind a constraint.
+
+---
+
+## Network binding and instance isolation
+
+### Default bind, and the non-loopback warning path
+
+**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`. **Installer note** (1.8.x, `install.sh`): interactive installs now PROMPT for the binding, defaulting to LAN (`0.0.0.0`) with a required password prompt (skipping the password needs an explicit confirm and prints a loud warning); non-interactive installs keep loopback unless `CODEMAN_HOST` is preset, and re-runs/updates preserve the EXISTING binding (`read_existing_binding()` parses the current systemd unit / launchd plist). The server binary's own default is unchanged. **Full model: `docs/security-architecture.md`.**
+
+### Instance isolation and the multi-instance attach danger
+
+**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', …)`.
+
+## Session launch modes
+
+### External CLI modes (OpenCode, Codex, Gemini)
+
+**External CLI modes (OpenCode, Codex, Gemini)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All three modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Codex CLI tab; Respawn/Ralph options are Claude-only, so session options open on the Summary tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM).
+
+### Remote sessions over SSH
+
+**Remote sessions (SSH)**: Sessions can run the agent inside a durable `tmux -L codeman-remote new-session -A` **on a remote host** so it survives the SSH drop (COD-104), and can also **discover + attach** to `codeman-*` sessions another Codeman launched there — attached (`owned:false`) sessions **detach, never kill** on tab close (COD-105). **Shared/collaborative** (COD-106): remote set-options are scoped per-session (never `-g`) and `window-size latest` lets multiple clients attach the same session at different viewports without clamping to the smallest; a client count surfaces a "shared · N" badge. **Auto-reconnect** (COD-108): a bounded-backoff watcher re-establishes a dropped remote session's local ssh pane and reattaches the still-running durable remote tmux (kill-switch `remoteAutoReconnect`, default ON); the pure pieces (backoff schedule, per-session reconnect state, `decideReconnect` eligibility) live in `src/remote-reconnect.ts` (tests: `test/remote-auto-reconnect.test.ts`), while `tmux-manager.ts` owns the live pane probe + timers. Owned sessions propagate `kill-session` to the remote on close; non-owned never do. ⚠️ Command-injection surface (COD-107): all ssh command lines flow through the single shell-safe `buildSshConnectionArgs()` — every user field (`-J jumpHost`, `-i identity`, `-o`) is `shellescape`d; never hand-build an ssh line elsewhere. Full design: `docs/remote-sessions.md`.
+
+### Remote SSH cases
+
+**Remote SSH cases** (COD-94/#145): cases can point at a **remote host** (`~/.codeman/remote-hosts.json` + `remote-cases.json` via `src/remote-hosts.ts`; CRUD under `/api/cases` — cases route file). A remote session launches a LOCAL tmux pane running `ssh <host>` that creates a durable REMOTE tmux session on a **dedicated socket** `-L codeman-remote` with name `codeman-ssh-<id>` — deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so a Codeman instance on the target host never adopts it; no `-g` global tmux options are set remotely. `remotePath`/`identityFile` are schema-guarded against shell injection (backticks/`$` rejected — same approach as `extraSshOptions`); remote tmux availability is probed via `checkRemoteTmuxAvailable()` in quick-start (ssh args carry `-o ConnectTimeout=10`). Remote claude defaults to `exec claude --dangerously-skip-permissions`; per-host `commands.*` override. Session kill best-effort kills the remote tmux too. `SessionState.remote`/`MuxSession.remote` round-trip through recovery (`restoreMuxSessions` passes `remote` back into the Session constructor). ⚠️ Run flows must route remote cases through `POST /api/quick-start` (which resolves the remote case and skips LOCAL CLI availability gates) — `POST /api/sessions` stat-validates `workingDir` locally and has no `caseName`. `envOverrides`/`effort`/`modelOverride`/`codexConfig`/`geminiConfig` are rejected for remote quick-starts (not silently dropped). UI: Create Case modal → Remote tab. Tests: `test/remote-hosts.test.ts`, `test/remote-ssh-options.test.ts`.
+
+### Docker cases
+
+**Docker cases** (shipped 1.4.0; user guide `docs/docker-cases.md`, design `docs/docker-cases-plan.md`): a case can point at a **container** instead of a local/remote path, and any of the five CLI backends runs INSIDE it. Like remote-SSH, it is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`** (`SessionMode` is unchanged). Storage `~/.codeman/docker-hosts.json` + `docker-cases.json` via `src/docker-hosts.ts` (direct mirror of `remote-hosts.ts`: `readDockerHosts`/`readDockerCases`, `toSessionDocker`, `dockerDisplayPath`, and the PURE builders `buildDockerBaseArgs`/`buildDockerCreateArgs`/`containerApiUrl`/`hostGatewayAlias`/`dockerConfigHash`). CRUD `/api/docker-hosts` + `/api/cases/docker-link`, plus **one-click** `/api/cases/docker-quickcreate` (Create New "Run in Docker" checkbox → case folder in `CASES_DIR` + auto-provisioned shared `default` host + auto-start a session inside; an expandable Template picker Small/Medium/Large/GPU or any override creates a per-case `q-<name>` host), and export/import (`/api/docker-cases/:name/export`, `/api/docker-cases/import`, `GET/DELETE /api/docker-exports`) — all in `case-routes.ts`. Run flows route through `POST /api/quick-start` like remote (session-routes.ts docker branch, skips LOCAL CLI-availability gates). **Launch model**: exactly one long-lived container **per case** (`codeman-case-<slug>`, PID1 `sleep infinity` under `--init`); a LOCAL tmux pane runs `docker exec -it` into a **durable in-container tmux** on dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>` (deliberately fails `SAFE_MUX_NAME_PATTERN` so a Codeman running INSIDE the container never adopts it, exactly like remote's `codeman-ssh-<id8>`). Builders `buildDockerLaunchCommand`/`buildDockerKillCommand` in `tmux-manager.ts` (image-check → `docker inspect||create` → start → exec, all idempotent). The container is **shared by all sessions of the case**: `buildDockerKillCommand` kills ONLY that session's in-container tmux session, NEVER `docker stop` while siblings remain; `docker rm -f` happens only on case-delete (plus an instance-scoped boot reaper keyed on the `codeman.instance` label). **Two-layer durability/resume** (the central design point): (1) Codeman-PROCESS restart with the container still up → `tmux new-session -A` reattaches the SAME live agent (paneCommand ignored); (2) container stop/reboot/OOM → inner tmux is gone, so the re-run pane command resumes the conversation from the bind-mounted transcript: claude mode pins a DETERMINISTIC conversation id via `claudeDockerPaneCommand()` (`tmux-manager.ts`) — fresh launch `claude --session-id <sessionId> || claude --resume <sessionId>` (a duplicate `--session-id` exits 1 "already in use", so the fallback RESUMES after a container stop; verified CLI behavior), explicit resume `--resume <rid> || --session-id <sid>` so a stale id never dead-panes (leading `exec ` is stripped — an exec'd first branch could never fall back); codex `resume <id>` / gemini `--resume` keep `appendResumeFlag`. The resume id rides `resumeSessionId` through create/respawn options and persists on `DockerCase.lastClaudeSessionId` via `persistDockerCaseClaudeSessionId()` (written at quick-start launch, and again on hook/last-response conversation-id adoption so post-`/clear` switches track; seeded back when `resumeOnStart`, default true); `-A` makes the pane command self-selecting (inert on reattach, active only when tmux was re-created). **Config drift** (`dockerConfigHash` → `codeman.confighash` label): quick-start compares via `checkDockerConfigDrift()` and REFUSES a drifted launch with `CONFLICT`; the UI confirm calls `POST /api/docker-cases/:name/recreate` (refused while case sessions are live) which `docker rm -f`s so the next launch recreates with the new config — host config edits actually take effect. **Workspace** is a REAL host dir bind-mounted at the SAME absolute path (mirror, `dst==src`), so `Session.workingDir = hostWorkspacePath` keeps file-routes/attachments/watchers on real host bytes AND the in-container transcript projHash matches the host so subagent/workflow correlation (and thus resume-id capture) works; `resolveMuxAttachCwd` returns `/tmp` for docker (the local pane only runs `docker exec`). **Creds** arrive commit-safe and ISOLATED (1.4.1; replaced the whole-dir RW mounts that let in-container CLIs write refreshed tokens/state back to the host): shared RW across the boundary is ONLY what host-side reads/resume need (`~/.claude/projects` transcripts; codex `sessions/` + `history.jsonl` for response-viewer/`codex resume`); everything else is SEEDED (RO mount, copied into container HOME once at launch via `[ -e ] || cp`; the container refreshes its own copy and never writes back): `~/.claude.json` is merged through `buildSeamlessClaudeConfig()` (forces `hasCompletedOnboarding` + theme + workspace trust, so no login wizard/theme picker/trust prompt inside the container), plus `.claude/{.credentials.json,settLine truncated
+
+## Session data and lifecycle
+
+### Input delivery and WS resilience
+
+**Input**: `session.writeViaMux()` for programmatic/curl input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only (fire-and-once). Interactive **browser** input goes through a durable **exactly-once** layer: each frame carries a stable `clientId` + monotonic per-session `seq`, persisted to localStorage until the server ACKs (`{t:'ia',seq}` over WS, or HTTP 2xx), so a dropped link/reconnect can't lose or double-deliver a prompt. **WS resilience** (#149): the upgrade URL carries `cid = clientId + ':' + perTabNonce`, and `ws-connection-registry.ts` supersedes only same-TAB reconnects (two tabs on one session coexist; input frames keep the bare `clientId` for seq dedup); reconnects back off exponentially (attempts preserved across `_connectWs`), and the header connection chip renders from a real `_wsState` lifecycle (`connecting`/`connected`/`fallback`/`reconnecting`/`disconnected`).
+
+### Auto-resume on usage limit
+
+**Auto-resume on usage limit** ("token pause" control, opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit ("5-hour limit reached ∙ resets 8pm" and all 1.0.x–2.1.x variants), `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time from cleaned output; `SessionAutoOps` arms a timer for reset+2min, then sends Esc (dismisses the rate-limit dialog) + `continue`. Still-limited responses re-arm the loop (5-min retry on stale times); a `working` transition cancels it. Claude-mode only (detection rides `_processExpensiveParsers`). Persists/recovers via `SessionState.autoResumeEnabled`/`autoResumeAt`; respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected` — prevents `/clear` from wiping the paused conversation). Endpoint: `POST /api/sessions/:id/auto-resume`; SSE: `session:limitPauseScheduled`/`limitResume`/`limitResumeCancelled`. Tests: `test/usage-limit-patterns.test.ts`, `test/session-auto-resume.test.ts`.
+
+### Plan-usage chip (statusLine telemetry)
+
+**Plan-usage chip** (statusLine telemetry, opt-in `showPlanUsageLimits`, default OFF): Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through** (so injecting our statusLine doesn't blank the in-terminal footer). `plan-usage-latest.ts` holds the process-wide last value, replayed in the SSE init snapshot (`getLightState`) so the header chip (`#planUsageChip`, toggled by `showPlanUsageLimits` in settings-ui.js) renders immediately on page load / reconnect without per-browser localStorage. Claude-mode only. **Distinct from auto-resume** (which reacts to the limit _message_; this proactively shows the live %). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`.
+
+### Cron jobs
+
+**Cron (cron-style `CronJob`s)**: saved, named jobs with a recurring schedule (`once`/`interval`/`daily`/`weekly`), enable/disable, Run Now, next-run calc, and per-job run history (`CronJobRun`). ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded autonomous loop) — the two never interact; the legacy concept keeps the `Scheduled*` names, the recurring-job feature is `Cron*`. `CronService` (`src/cron/cron-service.ts`) owns CRUD + the 30s background due-tick (`tickDueJobs`, registered via `cleanup.setInterval` in `server.ts`; `init()` recomputes nextRunAt on boot) and **reuses the existing session layer** (create → `addSession` → `setupSessionListeners` → `startInteractive`/`startShell` → prompt via `writeViaMux`/`write`) rather than rebuilding tmux logic. Next-run math is pure/unit-tested in `cron-time.ts` (SERVER-LOCAL timezone for daily/weekly). Dup-launch guard = `lastDueKey` (jobId:fireTime); schedule is advanced BEFORE launch so a slow launch can't re-trigger. `once` jobs self-disable after firing (`completedOnce`). Persisted via `AppState.cronJobs`/`cronJobRuns` (StateStore accessors). Routes `/api/cron/jobs*` + `/api/cron/runs` (`cron-routes.ts`, `CronPort`); schema `CronJobSchema` (cross-field `superRefine`; the `.partial()` update schema does NOT re-run it); SSE `cron:*`. Frontend `cron-ui.js` (#cronModal). Claude/shell/opencode/codex/gemini agent types. Tests: `test/cron-time.test.ts`, `test/cron-service.test.ts`. Design: `docs/cron-discovery.md`.
+
+### Unified session list and Session Manager
+
+**Unified session list** (COD-160/#139): `GET /api/sessions/unified?limit=&q=` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows are keyed by conversation UUID and folded into their owning session via a `claudeSessionId → Codeman id` alias map (resumed//clear-respawned sessions must not appear twice); lifecycle name/mode resolution is first-seen-wins (the log returns entries NEWEST-first). No terminal buffers in the response (unlike `/api/sessions`). Consumed by the Cmd+K Session Manager (#146). Session Manager polish (COD-162/#157, 1.6.0): **pinning** via `POST /api/sessions/:id/pin` (`session:pinned` SSE; killing a pinned session demotes it to a lightweight stopped record that stays visible/resumable, and cleanup skips pinned records); **cross-device tab order** via `PUT /api/session-order` (`session:orderChanged` SSE, persisted in `state.json`; pure `normalizeSessionOrder`/`mergeSessionOrder` in `src/session-order.ts`: pushing device wins, server-only ids fall to the end, never dropped); resume from the manager keeps the original session name (COD-143); `firstPrompt` is backfilled for sessions whose id != transcript UUID and the most recent prompt (`lastPrompt`) is shown + searched (COD-140/145).
+
+### Full-scrollback replay
+
+**Full-scrollback replay** (COD-164/#148): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). Only the FIRST buffer load after a page load requests `full=1` (one-shot `_initialFullBufferLoad` flag in app.js); tab switches keep the cheap `?tail=` visible-frame path. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`.
+
+### Run launch synchronization
+
+**Run launch synchronization**: the main Run entrypoint in `session-ui.js` holds an in-flight lock and disables `#runBtn` for the whole launch (at least 500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. A successful create/quick-start also calls `_ensureCreatedSessionVisible()` before `selectSession()`: local creates use the response's full session snapshot; quick-start modes fetch `GET /api/sessions/:id` only when `session:created` SSE has not already populated the map. The normal `_onSessionCreated()` handler remains the idempotent upsert, so POST-first and SSE-first ordering both produce one immediately-rendered tab. Tests: `test/run-mode-ui.test.ts`.
+
+### Circuit breakers: Ralph and PTY-exit
+
+**Circuit breaker**: Prevents respawn thrashing. States: `CLOSED` → `HALF_OPEN` → `OPEN`. Reset: `/api/sessions/:id/ralph-circuit-breaker/reset`. **Distinct: PTY-exit breaker** (COD-115/118/#147, `session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits (crash loops on attach), blocks further auto-restarts, broadcasts SSE `session:respawnBreakerTripped` + push (in `PUSH_EVENT_MAP`). Reset ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive` (sent by the user-facing restart control) — the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. Sessions also scrub inherited `TMUX`/`TMUX_PANE` env so Codeman-in-tmux doesn't nest. Tests: `test/respawn-pty-breaker.test.ts`.
+
+## Features
+
+### Attachments
+
+**Attachments** (live external document references; COD-37/#119 core, COD-38/#120 previews, COD-39/#121 history): all wiring in `file-routes.ts`. **Registry** (`attachment-registry.ts`): an **in-memory** map of a stable `attachmentId` → an absolute, `realpath`-resolved, extension-allowlisted file path, so browser requests (`GET /api/sessions/:id/attachments/:attachmentId/raw`) never carry arbitrary absolute paths; `POST /api/sessions/:id/attachments` registers one. **Magic links** (`attachment-magic.ts`): parses `codeman://attach?...` out of terminal output — ⚠️ this scanner is prompt-injectable, so the scan path is **force-confined to the session workspace** (a hostile prompt could otherwise make it read arbitrary host files over SSE); emits the `attachment:detected` SSE event. Security gate is an extension **allowlist** (`isSupportedAttachmentExtension`, in the registry/magic modules), not a blocklist; a separate path layer (`config/attachment-guard.ts`) confines reads to the workspace (`attachmentConfineToWorkspace`) and blocks sensitive trees (`/root`, `/etc`). **Previews + thumbnails** (COD-38): `:attachmentId/preview` + `:attachmentId/thumbnail` (and the workspace-file equivalents `file-preview`/`file-thumbnail`) render Office docs/PDFs via external converters (`pdftoppm` / LibreOffice `soffice` / Word-COM `powershell`); `document-preview-cache.ts` is a shared disk cache (de-dups _identical_ in-flight inputs), `document-thumbnailer.ts` does best-effort first-page images, and `document-conversion-limiter.ts` is a **global converter-spawn concurrency cap** (`runWithConversionLimit`) — without it, N distinct large docs detected at once fork N multi-minute converter processes = a localhost fork-bomb-shaped resource-exhaustion vector. **History drawer** (COD-39): `session-attachment-history.ts` tracks the last `ATTACHMENT_HISTORY_LIMIT` (100) attachments per session (`Session._attachmentHistory`, persisted via `SessionState.attachmentHistory`, replayed so externals re-register on reconnect); `GET /api/sessions/:id/attachments` is the list endpoint. ⚠️ The history drawer's launcher button is desktop-only — hidden on phones (regression-guarded; see `mobile-header-buttons-policy` test). Session-local files keep using the existing workspace-scoped `file-routes` paths; the registry is only for explicit live externals. **Codex generated artifacts** (COD-166/#150, `generated-artifact-attachments.ts`): codex-mode sessions ALSO scan (ANSI-stripped) output for `Saved to: file:///…` lines and surface those files as attachment cards with a relaxed trust policy — the allow decision runs on the **realpath-resolved** path against `os.homedir()`-anchored `~/.codex` marker dirs (symlink escapes fall back to force-confinement); gated to `mode === 'codex'` only (`source` is a REQUIRED param through the listener-deps chain — a dropped arg here silently kills the feature). Image thumbnails pass through jpg/jpeg/gif/webp.
+
+### Ultracode and workflow-run visualization
+
+**Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a COMPLETION artifact per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json` (written only at run end); LIVE in-flight runs exist only as transcript dirs at `…/subagents/workflows/wf_<id>/` (journal.jsonl + `agent-*.jsonl`). `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; separate singleton, though it independently reads the same `subagents/workflows/` tree) scans BOTH sources via periodic poll + per-directory chokidar watchers with per-source mtime skip (LRU agentStatCache + journalCache), synthesizing ACTIVE runs (live per-agent tokens/tools/state from transcripts, title/phases from the workflow script) until the completion `wf_*.json` appears and supersedes, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is started when **either** `showUltracodeAgents` **or** `ultracodeFloatingWindows` is on (`server.ts` `isWorkflowAgentTrackingEnabled()` returns `(showUltracodeAgents ?? false) || (ultracodeFloatingWindows ?? false)`). Served via `GET /api/workflows` (optional `?minutes=` filter) and `GET /api/workflows/:runId`. Frontend `ultracode-panel.js` renders a docked master-detail view (LEFT: runs + phases; RIGHT: per-agent tokens + tool-calls; click an agent card → its live transcript via client-side `agentId` join). **Additionally**, `ultracode-windows.js` auto-pops a draggable **floating window per active run** (gated on a **DEDICATED** `ultracodeFloatingWindows` toggle, default OFF — independent of the dock panel's `showUltracodeAgents`; see `_ultracodeFloatingEnabled()`), connected by a glowing line to the originating session tab (resolved by `session.claudeSessionId === run.sessionUuid`) — same line idiom as subagent windows, drawn into the shared `#connectionLines` SVG from the tail of `_updateConnectionLinesImmediate`. The window auto-closes ~8s after its run finishes; explicit dismissals are remembered. Clicking an agent card opens an **in-page** connected transcript window (not a browser popup); both run and transcript windows minimize **into** the originating session tab as a merged `ULTRA` badge (🧬 runs / 📄 transcripts) with a restore/dismiss dropdown — minimized runs are skipped by auto-pop. Gesture beta: floating subagent/ultracode windows are pinch-draggable (a `window` grab kind in `entry.ts`). Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
+
+### Cross-session search
+
+**Cross-session search** (COD-113/#133): `GET /api/search?q=&types=&limit=` federates an **in-memory** search across all live sessions — session metadata (name/workingDir/id), run-summary events, and per-session attachment-history file entries (workspace-relative path only; the server-private `externalPath` is never read). Pure core `searchSources()` in `search-service.ts` (substring-matches with hard per-type caps — no regex, so no ReDoS; no filesystem reads, so no traversal); `harvestSources()` in `search-routes.ts` gathers the in-memory sources. `SearchQuerySchema` bounds `q` (1–200), allowlists `types` (`session,event,file`), clamps `limit` (1–60). Returns the `{success,data}` envelope. Frontend: history-panel search box in `terminal-ui.js`. Types: `src/types/search.ts`.
+
+### Away digest
+
+**Away digest** (COD-41/#136): `GET /api/away-digest?range=&since=&until=&lastViewed=` aggregates "what happened while you were away" from the lifecycle log + run-summary events + live sessions + daily token stats + recently-completed subagents into needs-attention/completed/still-running/idle/informational sections. Pure aggregator in `web/away-digest.ts` (`resolveAwayDigestRange()` validates the window — `since-last-visit`/`1h`/`today`/`24h`/`custom`, server-local TZ; `buildAwayDigest()` classifies). Header-button modal in `panels-ui.js` (button hidden on phones — regression-guarded). ⚠️ Returns `{success:true,digest}` (a legacy raw-ish shape, consistent with the other raw GET handlers in `system-routes.ts` — `{entries}`/`{config}`/`{files}`/`getSystemStats()`); frontend + tests read `.digest`. Subagent lookback is a fixed 60-min window regardless of range.
+
+### Self-update
+
+**Self-update** (App Settings → Updates): in-app updater for **git-clone installs** supervised by systemd/launchd. Supervisors: `systemd` (user unit), `launchd` (GUI LaunchAgent, gui-domain kickstart), `launchd-daemon` (KeepAlive system LaunchDaemon on headless Macs — restarts rootlessly by killing the server PID and letting launchd respawn it; detected only when the daemon is bootstrapped AND KeepAlive), else `none` → "restart manually" message; on next boot a manual-restart status auto-completes when the running version matches the target. The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` (`git checkout <release tag> && npm install && npm run build && restart`) that outlives the restart; it writes progress to `dataPath('update-status.json')`, which the browser polls across the connection drop. Channel = latest `codeman@X.Y.Z` release tag; dirty trees are auto-stashed. `src/web/self-update.ts` splits PURE helpers (semver/tag parsing, reconcile decision — unit-tested) from IO wrappers (`getInstallInfo`/`checkForUpdate`/`startUpdate`/`reconcileUpdateOnBoot`). Routes: `GET /api/system/update/check`, `POST /api/system/update`, `GET /api/system/update/status`. Types: `src/types/update.ts`. npm installs report as non-updatable.
+
+### Web tabs
+
+**Web tabs** (saved dashboard URLs rendered as tabs beside agent sessions; user guide `docs/web-tabs.md`). A webview is **NOT a sixth `SessionMode`**: no PTY, no tmux, no respawn, no idle detection. It is a separate resource (`~/.codeman/webviews.json` via `src/webview-store.ts`, types in `src/types/webview.ts`, limits in `src/config/webview-limits.ts`) that shares only the tab strip and the main content area, exactly as Docker and remote-SSH are case overlays rather than modes.
+
+**Why there is a reverse proxy at all.** A direct `<iframe src="http://box:4000">` fails three independent ways in the shipped deployment: (1) prod serves `--https` behind `tailscale serve`, and browsers hard-block `http://` iframes on an HTTPS page with no override (none at all on iOS Safari); (2) Grafana/Portainer/Home-Assistant-class dashboards send `X-Frame-Options: DENY` or `frame-ancestors 'none'`; (3) our own `default-src 'self'` CSP makes `frame-src` fall back to `'self'`. Serving the dashboard through Codeman's origin dissolves all three, and as a bonus leaves the production CSP **byte-for-byte unchanged**, because `/webview/...` is already covered by `'self'`. A `direct` mode still exists for HTTPS targets that permit framing; `POST /api/webviews/probe` runs a server-side reachability + framing check and recommends which to use.
+
+**Origin-scoped, not path-scoped.** `/webview/<cap>/x/y` always maps to `<upstream origin>/x/y`, never `<upstream origin><saved path>/x/y`. Dashboards reference assets root-absolutely (`/public/build/app.js`), so origin-scoping is the only mapping under which those resolve; the saved URL's own path+query is used solely as what `/webview/<cap>/` itself serves.
+
+**The capability, and why the auth exemption is safe.** A sandboxed iframe (no `allow-same-origin`) is OPAQUE-ORIGIN, so every request it makes is cross-site: the `SameSite=lax` `codeman_session` cookie is never attached, and writes and WS upgrades arrive with `Origin: null`, which `isAllowedRequestOrigin` rejects by design. Cookie auth therefore cannot work. `src/webview-capabilities.ts` mints a 192-bit `randomBytes` token (memory-only, so a restart invalidates every outstanding one; rolling TTL; bound to the minting user; revoked on edit/delete) which `middleware/auth.ts` recognizes via `hasValidWebviewCapability()` to skip the cookie and Origin checks. ⚠️ The **Host allowlist is never bypassed**, so DNS-rebinding protection is intact. ⚠️ There is a second, `Referer`-keyed form of the exemption for root-absolute assets that `<base href>` cannot rewrite (`fetch('/api/data')`, `import('/chunk.js')`); it is the only exemption decided by a request-supplied header, so it is fenced to **safe methods on non-`/api`, non-`/ws`, non-`/q` paths**. Without that fence a page could present a webview Referer and skip auth on `/api`. `test/webview-auth-exemption.test.ts` pins every edge.
+
+**Sandbox default.** The iframe carries `allow-scripts allow-forms allow-popups allow-downloads allow-modals` and gains `allow-same-origin` ONLY when the dashboard is explicitly `trusted`. A proxied page is served from Codeman's own origin, so granting it would let the dashboard read the Codeman document and drive the agent-spawning API. ⚠️ In **both** modes, `Authorization` and the `codeman_session` cookie are stripped before the upstream request (`buildUpstreamRequestHeaders`), because a trusted (same-origin) frame makes the browser attach Codeman's own Basic-auth header to every proxied request; forwarding it would hand `CODEMAN_PASSWORD` to the dashboard.
+
+**Two things a sandboxed frame breaks that are invisible to `curl`.** Both were found only by driving a real dashboard in a real browser, and both present identically as the dashboard's own "Failed to fetch" while the page itself renders fine:
+
+1. **Root-absolute URLs built at runtime.** `<base href>` only governs URLs the HTML parser resolves; `fetch('/api/data')` bypasses it and lands on Codeman's root. That is how most dashboards talk to their own backend. The `Referer`-keyed 404 fallback deliberately refuses `/api`, `/ws`, `/q` (widening it there would let a request-supplied header skip auth on Codeman's own API), so the fix is `runtimeUrlShim()`: a small script injected right after `<base>` that patches `fetch`, `XMLHttpRequest.open`, `WebSocket` and `EventSource` to rebase root-absolute and same-origin-absolute URLs into the prefix. It removes the whole class inside the iframe instead of trading security for it. ⚠️ It must be injected even when the page ships its OWN `<base>` (an early return there silently breaks exactly the pages that need it most).
+2. **CORS on same-host requests.** An opaque-origin document treats EVERY request as cross-origin, including to the very host it was served from, so its `fetch`/XHR are CORS-checked and its preflights carry `Origin: null`. Static subresources (script/css/img) are NOT CORS-checked, which is why the page renders while its API calls die with an opaque `net::ERR_FAILED`. `buildProxyCorsHeaders()` echoes the origin (omitting `allow-credentials` for `null`, which browsers reject in combination), upstream `access-control-*` headers are dropped (they describe the dashboard's origin, not the frame's), and the proxy answers preflights itself rather than relaying them. ⚠️ `registerSecurityHeaders` answers EVERY `OPTIONS` with a bare 204 before routing, and its CORS block only emits headers for localhost origins, so that short-circuit **must** exempt a valid webview capability or every preflight fails. `curl` cannot reproduce any of this because curl does not enforce CORS.
+
+**Rewrites, each load-bearing** (pure + unit-tested in `src/web/webview-proxy.ts`): drop `x-frame-options` and the CSP `frame-ancestors` directive (the point of the proxy); drop `content-encoding`/`content-length` because undici's `fetch` already decoded the body (forwarding them makes the browser gunzip plaintext); rewrite `Location` for same-origin redirects only, handing CROSS-origin redirects back unchanged so this never becomes an open relay; rebase `Set-Cookie` `Path` onto the prefix and drop `Domain`; inject `<base href>` and rebase root-absolute `src`/`href`/`action`. `resolveUpstreamUrl()` returns null on anything escaping the upstream origin.
+
+**Fastify specifics.** The proxy lives in an **encapsulated plugin scope** with `removeAllContentTypeParsers()` + a `'*'` pass-through parser, so raw bodies relay byte-for-byte while the root instance keeps its JSON parsing (and keeps `text/plain` RAW, which was a real CSRF hole once). One `app.route({ method:'GET', handler, wsHandler })` serves both HTTP and the WebSocket upgrade; **HEAD must NOT be declared** on the sibling route because `exposeHeadRoutes` already derives it and the duplicate is a startup error. ⚠️ **Every exit path in the proxy handler RETURNS `reply.send(...)`**: the handler is `async`, and a bare `return` after `reply.send(stream)` resolves the handler promise to `undefined` before the stream is consumed, so Fastify answers with an EMPTY body. HTML survives that (synchronous string payload) while every streamed asset comes back zero-length, which is a genuinely confusing failure. The root-absolute fallback hangs off `setNotFoundHandler`, so real Codeman routes always win.
+
+**Frontend** (`src/web/public/webview-tabs.js`, load order 12.5): web tabs render into `#sessionTabs` carrying `data-webview-id` instead of `data-id`, so every session-tab path (drag-and-drop, alerts, badges) skips them. ⚠️ `_renderSessionTabsImmediate()`'s `canIncremental` check must include the web-tab comparison: the session-only comparison is vacuously "unchanged" whenever session count is stable, most visibly at ZERO sessions (`0 === 0`), where opening a dashboard would never draw its tab. ⚠️ `isActive` for a session tab is `id === activeSessionId && !activeWebviewId`: `activeSessionId` stays set while a web tab is showing (the terminal keeps streaming underneath), so without that clause the debounced re-render lights two tabs at once. Frames stay MOUNTED while hidden (LRU-evicted past `maxLiveFrames`) so tab switching never reloads a dashboard.
+
+**Pre-existing bug fixed alongside**: `.toolbar` has `backdrop-filter`, which makes it a stacking context and TRAPS `.run-mode-menu`'s `z-index: 1000` inside it. With the toolbar itself at `z-index: auto`, `.welcome-overlay` (z-index 10, inside `<main>`) painted over the popped-up Run menu, making **every** item in it unclickable whenever no session was open. `.toolbar` now carries `z-index: 20` (must stay below `.modal`'s 1000).
+
+### Multi-user mode
+
+**Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default; shipped 1.5.0 via PR #161, design `docs/multi-user-plan.md`): named users with individually scrypt-hashed passwords in `~/.codeman/users.json` (via `src/user-store.ts`: atomic 0600 write, short-TTL cache, SERIALIZED read-modify-write so a fire-and-forget `touchLastLogin` can't clobber a concurrent route write, last-admin invariants). Gated everywhere by `isMultiUserMode()` (`src/config/multiuser.ts`); when OFF, behavior is byte-identical to single-user (all scoping helpers short-circuit). ⚠️ **Not a security boundary at the agent layer** — every session still runs as the SAME OS account; this separates WORKSPACES, it does not sandbox users (Docker cases are the isolation story). Auth: a PARALLEL async branch in `middleware/auth.ts` (single-user branch untouched) verifies `username:password` against the store, mints identity-carrying cookies (`AuthSessionRecord` gains `username`/`role`/`mustChangePassword`), decorates `req.authUser` (Fastify augmentation; single-user leaves it undefined and the ownership helpers default to a synthetic admin), enforces a per-username failure bucket + the `mustChangePassword` lockbox. Ownership threads through `Session.owner` (stamped from `req.authUser`/`job.owner` at every `new Session()`, round-tripped via `MuxSession.owner` on recovery); `findSessionOrFail(ctx,id,req)` does a NOT_FOUND owner check; list endpoints + `getLightState` + SSE (`deriveSseHint` routes session-scoped events by owner, fail-closed; machine-level + host-plan telemetry admin-only) + WS + search + file-preview all filter by owner. §6.3 permission policy: non-granted users are forced to `--permission-mode auto` (via `resolveClaudeModeForUser` at all spawn sites, incl. one-shots because `buildPromptArgs` now respects the session mode), and shell mode / cron `launchCommand` require the `canBypassPermissions` grant. Cases live in per-user `~/codeman-users/<name>/cases` (`resolveCasesDir`); a non-admin's `workingDir` is realpath-confined there; host CRUD is admin-only. Admin API `src/web/routes/admin-routes.ts` (`/api/admin/users*`, one-time passwords, audit log `admin-audit.jsonl`) + self-service `/api/me` + `/api/me/password` (`me-routes.ts`); frontend `public/admin-ui.js` (identity boot, change-password modal + interceptor, admin Users tab, and the header **Admin Panel** button `#adminPanelBtn`: ships `btn-admin-panel--hidden`, revealed for admins in multi-user mode, phone-hidden via mobile.css; opens the full Admin Panel modal with user CRUD, per-user permission toggles, and case-folder list/delete via `GET/DELETE /api/admin/users/:username/cases[/:caseName]`; live-refreshes on SSE `admin:usersChanged`, wired in app.js). CLI `codeman users add|passwd|list|rm`. Per-user session cap via `sessionCapacityState`/`sessionCapacityMessage`. Tests: `test/user-store.test.ts`, `test/multiuser-auth.test.ts`, `test/ownership-scoping.test.ts`, `test/admin-routes.test.ts`, `test/admin-ui.test.ts`.
+
+## Frontend
+
+### Command palette and shortcut registry
+
+**Command palette + shortcut registry** (COD-151/153/157/192, #146): `Ctrl/Cmd/Alt+K` opens the session palette (fuzzy search over live sessions; "Browse all sessions" → the Session Manager modal backed by `GET /api/sessions/unified`); the quick-start case `<select>` is fronted by a searchable picker (`buildCasePickerOptions`/`formatCasePickerLabel` — remote cases render `name @ hostId`). Shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js; overrides persist under `settings.shortcutOverrides` via `saveAppSettingsToStorage`); App Settings → Shortcuts renders capture/disable rows; `Ctrl+?` opens the registry-driven overlay (footer links to the full `#helpModal` reference). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM — keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over.
+
+### WebGL renderer toggle
+
+**WebGL renderer toggle** (#140, `webglRendererEnabled`): per-device (`displayKeys` set, stripped from the server payload — NOT in `SettingsUpdateSchema`, which is `.strict()`). The GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads; it's cleared only by an explicit OFF→ON save transition or `?webgl=force` (`shouldSkipWebGL` in constants.js). `?nowebgl` still forces the DOM renderer per-load.
+
+### Header button visibility (multi-monitor, response viewer, file viewer, cron)
+
+**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`.
+**Response-viewer (eye) button** (header) is likewise **hidden by default** — enable under App Settings → Display → **Response Viewer** (`showResponseViewer`). Works for Claude AND Codex sessions (#152): Codex last-responses are located via a 4-layer rollout resolution under `CODEX_HOME` (history pin → originator match → resume-UUID → cwd fallback with other-pane exclusion), with injected-context filtering and event/legacy dedup — tests in `test/routes/session-routes-codex-last-response.test.ts`. Purely client-side (no `renderIndexHtml` step): the template ships with `btn-response-viewer-header--hidden` and `applyHeaderVisibilitySettings()` (settings-ui.js) toggles it after settings load. Hiding must go through that marker class — the base rule is `display:inline-flex !important`, so an inline style can't override it. `showResponseViewer` is in the `displayKeys` per-device set (settings-ui.js), so it does NOT sync across devices.
+**File Viewer button** (header, 1.4.1) is **shown by default on desktop** since `211f3c0` (post-1.8.0): toggle under App Settings → Display → **Header Displays** → File Viewer (`showFileViewerButton`, in the per-device `displayKeys` set, fallback default `true`). Purely client-side like the response viewer: the template now ships the button VISIBLE (no `--hidden` class) and `applyHeaderVisibilitySettings()` toggles the `btn-file-viewer--hidden` marker class after settings load; phones still hide it via mobile.css. The button toggles the file-browser panel open/closed without opening the settings modal (`panels-ui.js`). The same commit set the **default desktop header** to WS/CPU/MEM + File Viewer + gear: the token-count chip (`showTokenCount`, no settings-UI toggle) and the lifecycle-log button (`showLifecycleLog`) both default **OFF** now (templates ship them hidden; stored prefs still honored). The plan-usage chip default is unchanged (opt-in, see Plan-usage chip). The **Cron toolbar button** joined the same opt-in pattern in 1.6.0: template ships `btn-cron--hidden`, `applyHeaderVisibilitySettings()` toggles it via the per-device `showCronButton` setting (default OFF, App Settings → Display → Header Displays); cron jobs themselves are unaffected.
+
+### Gesture control: the setting
+
+**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: the source package
+
+**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`.
+
+### Theme skins
+
+**Theme skins** (App Settings → Display): the `skin` setting selects a palette via a `data-skin` attribute on `<html>`. Values: `daylight-blue` (default), `daylight-green`, `og` (OG Codeman). CSS lives under `[data-skin="…"]` blocks in `styles.css`. To avoid a flash-of-wrong-theme, an **inline pre-paint script** in `index.html` (`<head>`) reads `localStorage['codeman:skin']` and sets `data-skin` before first paint; `settings-ui.js` `applySkin()` applies it live on save (sets `html[data-skin]` + `window.__codemanSkin`, syncs the standalone `codeman:skin` key with the settings blob, and calls terminal-ui.js `applyTerminalSkin()` to re-theme live terminals). `skin` is a **per-device/client-only** setting — it's destructured OUT of the server payload (settings-ui.js, alongside `localEchoEnabled`/`cjkInputEnabled`/`extendedKeyboardBar`), so it does NOT sync across devices.
+
+### Custom branding and UI language
+
+**Custom branding + UI language** (App Settings → Display → Branding & Language): `displayName` is schema-validated (trimmed, 1–40 chars), server-synced, and changes user-facing browser branding/window titles only — NEVER rename npm package/CLI/API/storage/CSS/protocol identifiers. `language` is a per-device `en`/`zh-CN` display key, stripped from the server payload. `i18n.js` keeps English as the canonical source/fallback, observes newly inserted application DOM for dynamic copy, preserves source strings so live EN↔ZH switching is reversible, and skips terminal/response/file/session-name/user-content surfaces. User display names flow through `textContent`/attribute APIs and the server title's HTML escaper, never `innerHTML`.
+
+### Foldable settings identity
+
+**Foldable settings identity**: responsive layout remains width-driven through `MobileDetection.getDeviceType()`, but the localStorage namespace/defaults use `MobileDetection.isHandheldDevice()` so an Android foldable keeps `codeman-app-settings-mobile` after unfolding past the desktop breakpoint. The stable handheld check prefers explicit phone/tablet/desktop UA tokens, then `navigator.userAgentData.mobile`; Android WebView is covered by the `Mobile` UA fallback. Do not switch per-device settings namespaces from instantaneous viewport width — a posture-triggered WebView reload would lose opt-in UI such as `showResponseViewer` and `extendedKeyboardBar`. Regression profile: `OPPO Find N5 (unfolded)` in `test/mobile/devices.ts`.
+
+## Security layers
+
+### Layer-by-layer detail
+
+| Layer             | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auth**          | Optional HTTP Basic via `CODEMAN_USERNAME` (defaults to `admin`) / `CODEMAN_PASSWORD` env vars. Active only when `CODEMAN_PASSWORD` is set (`middleware/auth.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Network bind**  | Defaults to `127.0.0.1` (loopback). A non-loopback bind (`--host`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` **starts but warns loudly** (0.9.0; was fail-closed in COD-29/#107). `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges the warning. Classifier: `network-auth-policy.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| **Host guard**    | Always-on Host-header allowlist blocks DNS rebinding (RCE on the default no-auth loopback install). Allows loopback, any IP literal, the bind host, `*.ts.net`/`*.trycloudflare.com`/`*.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS`. ⚠️ **Custom reverse-proxy domains are rejected** unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`. `registerHostGuard` in `server.ts`; policy in `network-auth-policy.ts` (`buildHostPolicy`/`isAllowedRequestHost`/`isAllowedRequestOrigin`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **CSRF / Origin** | Always-on cross-site Origin guard rejects state-changing requests from foreign origins (covers self-update, session create/input, settings/tunnel toggles). **A missing Origin is allowed** so curl/CLI and Claude Code hooks keep working. The global body parser keeps `text/plain` RAW (no auto-JSON-parse, which had enabled simple-request CSRF); `/api/crash-diag` self-parses. WebSocket upgrade validates Origin+Host (anti-CSWSH) in `ws-routes.ts`. Added in `c669518` (closes 2026-06-09 review CRITICALs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **QR Auth**       | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **Sessions**      | 24h cookie (`codeman_session`), auto-extend, device context audit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Rate limit**    | 10 failed auth/IP → 429 (15min decay). QR has separate limiter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| **Hook bypass**   | `/api/hook-event` (and `/api/status-telemetry`, the statusLine exporter) skip Basic auth (localhost-only, schema-validated). When auth is active (`CODEMAN_PASSWORD` set), the loopback bypass requires the per-instance `X-Codeman-Hook-Secret` header **unconditionally** — COD-54 introduced it tunnel-gated; COD-91 (PR #127) made it always-on because Codeman can't detect a user's own loopback reverse proxy (own cloudflared/`tailscale serve`/nginx → 127.0.0.1), closing that residual plain-bypass gap. Hook curls cat the secret file at exec time via `$CODEMAN_HOOK_SECRET_FILE` (session env, `config/hook-secret.ts`); a missing/wrong secret gets 401 and rate-limits in a dedicated bucket (never locks out login). Tunnel enable **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged — via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` (env, COD-55) **or** the per-request `acknowledgeUnauthTunnel:true` action field (1.1.9): the welcome/settings tunnel toggle pops a security confirm dialog and, on confirm, resends with that flag (server logs a loud warning on every passwordless tunnel start; curl/API stay refused without password/env/flag). The flag is an action field, never persisted |
+| **Env vars**      | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies, comma-separated; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS`=1 (opt-in hooks-only listener on the docker bridge gateway so in-container hooks reach a loopback-bound server; bind IP from `CODEMAN_DOCKER_BRIDGE_HOST` or auto-detect)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+
+## Performance and limits
+
+### Buffers, uploads, and terminal history
+
+Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired live); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+
+## Local packages and build artifacts
+
+### xterm-zerolag-input is single-source
+
+**`xterm-zerolag-input` is single-source — edit the package, then rebuild the bundle** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/` (`zerolag-input-addon.ts`; also published to npm as a standalone library — see README "Published Packages"). It is bundled (esbuild → IIFE, with appended `window.LocalEchoOverlay` aliases) into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` by `scripts/postinstall.js` (for dev/`tsx`) and into `dist/.../vendor/` by `scripts/build.mjs` (the `xterm-zerolag-input` esbuild step, for prod). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)` — there is NO inline copy to keep in sync. So: change behavior in the package source, then re-run the bundle step (`npm install` reruns postinstall; `npm run build` for prod); **never hand-edit `app.js` for overlay behavior or commit the gitignored vendor bundle**. A public-API break in the package still warrants a separate `xterm-zerolag-input` version bump in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+
+## Tooling traps
+
+### Headless screenshot capture
+
+**Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — `scripts/capture-real-overview.mjs` (drives a live session in headless Chromium → overview PNG). Two traps, both observed 2026-06-14: **(1) DSF=2 doubles the console font.** xterm's WebGL renderer draws terminal glyphs at ~2× their nominal size under `deviceScaleFactor: 2`, while STILL reporting nominal cell dims (`terminal.cols`/`_renderService.dimensions.css.cell` say 8px/187cols — they lie), so it's invisible to any internal measurement and only the pixels reveal it. The HTML chrome (header/toolbar) is unaffected → ONLY the console font looks comically large. Default to **DSF=1** (script does); the image is 1× res but the font is true-to-browser. **(2) Stable filenames → stale renders.** Overwriting a fixed path (`claude-overview.png`) in place leaves OS image viewers (eog/feh) — and any HTTP client behind a long/`immutable` cache — showing the OLD render; the user reads it as "the fix didn't work". The script now mints a timestamped `claude-overview-<ts>.png` per run. ⚠️ This was a LOCAL image-viewer cache, NOT a Codeman serving bug: `file-routes` previews send `Cache-Control: no-cache` and `/api/screenshots/:name` sends none. The one real Codeman-side footgun: `server.ts` serves non-content-hashed static assets `public, max-age=31536000, immutable`, and `cacheBustAssets()` only rewrites `.js`/`.css` refs — a stable-named **image** referenced from public/ would go stale on overwrite. Reflect the per-device UI to match a real device when capturing: seed `localStorage` `codeman:skin`, `codeman-font-size`, and the desktop `codeman-app-settings` blob (the plan-usage chip is a per-device display key deleted from the server payload — a fresh browser hides it unless seeded; close side panels for a full-width terminal).

docs/security-architecture.md

@@ -500,6 +500,16 @@ Full feature guide: [`docker-cases.md`](docker-cases.md).
 
 ---
 
+## 10b. Web tabs (dashboard proxy)
+
+A saved dashboard URL renders as a tab, served through Codeman's own origin at `/webview/<capability>/`. User guide: [`web-tabs.md`](web-tabs.md). Three properties carry the security weight:
+
+- **The proxy is exempt from cookie auth and the Origin/CSRF guard, and that is deliberate.** The iframe is sandboxed without `allow-same-origin`, so it is opaque‑origin: its requests are cross‑site, meaning the `SameSite=lax` session cookie is never attached and its writes and WS upgrades arrive with `Origin: null`. The credential is instead a 192‑bit capability in the path, minted only by an authenticated `POST /api/webviews/:id/open`, held in memory (a restart invalidates every one), rolling TTL, bound to the minting user, and granting nothing but "relay bytes to this one saved URL". ⚠️ **The Host allowlist is NOT bypassed**, so DNS‑rebinding protection is unaffected. A second `Referer`‑keyed form exists for root‑absolute assets and is the only exemption decided by a request‑supplied header, so it is fenced to safe methods on non‑`/api`, non‑`/ws`, non‑`/q` paths. Edges pinned by `test/webview-auth-exemption.test.ts`.
+- **Sandboxed by default; `allow-same-origin` is an explicit per‑dashboard opt‑in.** A proxied page is same‑origin with Codeman, so without the sandbox its JavaScript could read the Codeman document and call the agent‑spawning API. ⚠️ In BOTH modes the `Authorization` header and the `codeman_session` cookie are stripped before the upstream request, because a trusted (same‑origin) frame makes the browser attach Codeman's own Basic‑auth credentials to every proxied request; forwarding them would hand `CODEMAN_PASSWORD` to the dashboard.
+- **Not an open relay, and not a privilege boundary.** `resolveUpstreamUrl()` refuses anything leaving the saved origin, and cross‑origin redirects are handed back unchanged rather than followed. The proxy does reach whatever the SERVER can reach, which is not an escalation for someone who already commands `--dangerously-skip-permissions` agents, but in multi‑user mode it means a non‑admin's dashboard is fetched from the server's network position. Saved URLs are validated to plain http(s) with no embedded credentials, and there is deliberately **no magic‑link path**: terminal output can never create a webview (the mistake the attachment scanner had to be walled off from).
+
+---
+
 ## 11. Quick reference
 
 | Env / flag | Effect |

docs/versioning-policy.md

@@ -75,5 +75,5 @@ allowance. The commitments above take effect at `1.0.0`.
 ## See also
 
 - `CLAUDE.md` — the COM release workflow (changesets, version bump, deploy)
-- `SECURITY.md` — security reporting and the supported-version policy
+- `.github/SECURITY.md` — security reporting and the supported-version policy
 - `docs/security-architecture.md` — the full trust model

docs/web-tabs.md

@@ -0,0 +1,137 @@
+# Web Tabs (dashboards as Codeman tabs)
+
+Open any dashboard you run, Grafana, Uptime Kuma, Portainer, a status page on port
+4000, as a tab beside your Claude/Codex/Gemini sessions. Codeman becomes one mission
+control instead of Codeman plus a pile of browser tabs.
+
+## Using it
+
+1. Click the chevron next to **Run** to expand the dropdown.
+2. Under **Web / URL**, pick **Add dashboard...**
+3. Give it a name and a URL, optionally hit **Test**, then **Save**.
+
+The dashboard opens as a tab immediately, and appears in the Run dropdown from then
+on. Web tabs sit in the same strip as session tabs, continue the same `Alt+1..9`
+numbering, and carry a globe icon so they never read as a running agent.
+
+Closing a tab (the `x`) only closes it. The saved dashboard stays in the dropdown.
+Deleting for good is behind the gear on the tab, or the gear on its dropdown row.
+
+Switching tabs does **not** reload a dashboard. Frames stay alive in the background,
+so a dashboard that took a while to authenticate is still there when you come back.
+Past six live frames the least-recently-viewed one is dropped to bound memory
+(`CODEMAN_MAX_LIVE_WEBVIEW_FRAMES`).
+
+## Why dashboards are proxied
+
+A plain `<iframe src="http://your-box:4000">` does not work in the setup Codeman
+actually ships in, for three separate reasons:
+
+| Blocker             | What happens                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| **Mixed content**   | Production serves HTTPS (behind `tailscale serve`). Browsers hard-block `http://` iframes on an HTTPS page, with no override, and none at all on iOS Safari. |
+| **Framing refusal** | Grafana, Portainer, Home Assistant and many others send `X-Frame-Options: DENY` or `frame-ancestors 'none'`. |
+| **Codeman's CSP**   | `default-src 'self'` means `frame-src` falls back to `'self'`, so a cross-origin iframe is blocked before it starts. |
+
+Serving the dashboard **through Codeman's own origin** dissolves all three. So by
+default a web tab loads `/webview/<capability>/` on Codeman, and Codeman relays to
+the dashboard: stripping the framing refusal, rewriting redirects, cookies and
+root-absolute URLs, and relaying WebSockets so live panels actually update.
+
+A useful consequence: the dashboard is fetched **from the Codeman server**, so a
+tailnet-only or `localhost`-only dashboard works from any device that can reach
+Codeman, including a phone that is not on the tailnet.
+
+`direct` mode (a plain cross-origin iframe) still exists and is cheaper, but it only
+works for an HTTPS dashboard that permits framing. The **Test** button probes from
+the server and tells you which mode applies.
+
+## The sandbox, and when to turn it off
+
+Because a proxied dashboard is served from Codeman's own address, it is
+*same-origin with Codeman* as far as the browser is concerned. Left unchecked, its
+JavaScript could read the Codeman page and call the API that spawns agents.
+
+So the iframe is sandboxed **without** `allow-same-origin` by default. The page runs
+in an opaque origin: it cannot touch Codeman, and it gets no cookies or
+`localStorage` of its own.
+
+Unchecking **Open sandboxed** grants `allow-same-origin`. Do that only for a
+dashboard you fully trust, and only if you need it, which in practice means a
+dashboard with its own login that stores a session in a cookie or `localStorage`.
+
+Even in trusted mode, Codeman never forwards its own credentials upstream: the
+`Authorization` header and the `codeman_session` cookie are stripped on the way out,
+so `CODEMAN_PASSWORD` cannot leak into a dashboard.
+
+## How the proxy authenticates
+
+A sandboxed iframe is opaque-origin, so every request it makes is cross-site: the
+`SameSite=lax` session cookie is not sent, and writes and WebSocket upgrades arrive
+with `Origin: null`. Cookie auth cannot work.
+
+Instead, opening a dashboard mints a **capability**: 192 bits of entropy in the URL
+path, held in memory only, with a rolling 12-hour TTL, bound to the user who minted
+it, and granting exactly one thing, relaying bytes to that one saved URL. Editing or
+deleting a dashboard revokes it, and a server restart invalidates every outstanding
+capability (tabs re-mint transparently on next click).
+
+## Limits and env vars
+
+| Variable                             | Default | Meaning                                    |
+| ------------------------------------ | ------- | ------------------------------------------ |
+| `CODEMAN_MAX_WEBVIEWS`               | 50      | Saved dashboards per owner                 |
+| `CODEMAN_MAX_LIVE_WEBVIEW_FRAMES`    | 6       | Iframes kept mounted at once               |
+| `CODEMAN_WEBVIEW_CAPABILITY_TTL_MS`  | 12h     | Rolling capability lifetime                |
+| `CODEMAN_WEBVIEW_TIMEOUT_MS`         | 30000   | Upstream request timeout                   |
+| `CODEMAN_WEBVIEW_PROBE_TIMEOUT_MS`   | 8000    | Timeout for the Test button                |
+| `CODEMAN_MAX_WEBVIEW_HTML_BYTES`     | 8MB     | Largest HTML document rewritten            |
+| `CODEMAN_MAX_WEBVIEW_SOCKETS`        | 8       | Concurrent proxied WebSockets per dashboard |
+
+Saved dashboards live in `~/.codeman/webviews.json`. Which tabs you have open is
+per-device (`localStorage`), since that is workspace layout rather than config.
+
+## How a dashboard's own API calls keep working
+
+Worth knowing, because it is where this feature does its least obvious work. Three
+layers cooperate so a dashboard talking to its own backend just works:
+
+1. `<base href>` handles relative URLs in the markup.
+2. Attribute rewriting handles root-absolute `src`/`href`/`action`.
+3. A small injected script rebases URLs built at **runtime** (`fetch('/api/data')`,
+   `new WebSocket('/live')`), which the first two cannot see.
+
+On top of that, the proxy answers those requests with CORS headers. That sounds
+wrong for same-host requests, but a sandboxed iframe has an *opaque* origin, so the
+browser treats every one of its `fetch`/XHR calls as cross-origin even though the
+URL is on Codeman itself. Without those headers, a dashboard renders perfectly and
+then every API call fails, which looks like the dashboard being broken.
+
+## Known limits
+
+- **Exotic loaders.** The three layers above cover normal `fetch`/XHR/WebSocket/
+  EventSource and normal markup. Something that constructs requests by an unusual
+  route can still slip through. Symptom: the page renders but a panel stays empty.
+- **Cross-origin redirects are not followed.** If a dashboard bounces to a different
+  host (an external SSO provider, say), the proxy hands the redirect back unchanged
+  rather than relaying it, because relaying would make this an open proxy. Use
+  **Open in new tab** for those.
+- **Login-protected dashboards need trusted mode**, since a sandboxed frame has no
+  cookie jar. A server-side per-dashboard cookie jar would lift this and is the
+  natural next step if it becomes annoying.
+- **Not a security boundary.** The proxy reaches whatever the Codeman server can
+  reach. That is not an escalation for someone who already commands
+  `--dangerously-skip-permissions` agents, but in multi-user mode it does mean a
+  non-admin user's dashboard is fetched from the server's network position.
+
+## Where the code lives
+
+| Concern                  | File                                    |
+| ------------------------ | --------------------------------------- |
+| Pure rewrite helpers     | `src/web/webview-proxy.ts`              |
+| Routes + proxy + sockets | `src/web/routes/webview-routes.ts`      |
+| Capability tokens        | `src/webview-capabilities.ts`           |
+| Persistence              | `src/webview-store.ts`                  |
+| Limits                   | `src/config/webview-limits.ts`          |
+| Frontend                 | `src/web/public/webview-tabs.js`        |
+| Auth exemption           | `src/web/middleware/auth.ts`             |

install.sh

@@ -15,6 +15,12 @@
 #   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)
+#   CODEMAN_HOST              - Preset the network binding and skip the prompt
+#                               (e.g. 0.0.0.0 for LAN access, 127.0.0.1 for
+#                               local-only; interactive default is 0.0.0.0,
+#                               non-interactive default is 127.0.0.1)
+#   CODEMAN_PASSWORD          - Preset the dashboard password (skips the
+#                               password prompt when binding to the network)
 
 set -euo pipefail
 
@@ -30,6 +36,21 @@ TARGET_NODE_VERSION="${CODEMAN_NODE_VERSION:-22}"
 NONINTERACTIVE="${CODEMAN_NONINTERACTIVE:-0}"
 SKIP_SYSTEMD="${CODEMAN_SKIP_SYSTEMD:-0}"
 
+# Network binding chosen during install (choose_network_binding). Empty
+# BIND_HOST means "not chosen" (e.g. the update path) and falls back to the
+# server's own loopback default.
+BIND_HOST=""
+BIND_PASSWORD=""
+BIND_ACK="0"
+
+# Binding found in an already-installed service (read_existing_binding), used
+# so updates and re-installs preserve the user's previous choice instead of
+# silently loosening it to the new network-access default.
+EXISTING_FOUND="0"
+EXISTING_HOST=""
+EXISTING_PASSWORD=""
+EXISTING_ACK="0"
+
 # puppeteer is a devDependency used only by scripts/browser-comparison.mjs — its
 # ~150MB chrome-headless-shell download is never needed to build or run Codeman.
 # Skipping it avoids a slow download and a fatal install failure when a prior
@@ -131,16 +152,39 @@ die() {
 }
 
 # Security notice — printed at the very end of install/update so it is the last
-# thing the user sees (the default loopback bind + how to expose it safely).
+# thing the user sees. Adapts to the binding chosen during install; the update
+# path (BIND_HOST empty) gets the generic text.
 print_security_notice() {
     echo ""
-    echo -e "  ${YELLOW}${BOLD}Security:${NC}"
-    echo -e "    Codeman binds ${BOLD}127.0.0.1${NC} (this machine only) — no password needed by default."
-    echo -e "    To reach it from another device, do ONE of:"
-    echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
-    echo -e "      ${CYAN}•${NC} ${CYAN}codeman web --host 0.0.0.0${NC}  AND set ${CYAN}CODEMAN_PASSWORD${NC}"
-    echo -e "    A non-loopback bind without a password still starts, but warns loudly."
-    echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
+    if [[ "$BIND_HOST" == "0.0.0.0" && -z "$BIND_PASSWORD" ]]; then
+        echo -e "  ${RED}${BOLD}============================================================${NC}"
+        echo -e "  ${RED}${BOLD}  WARNING: NETWORK ACCESS WITHOUT A PASSWORD${NC}"
+        echo -e "  ${RED}${BOLD}============================================================${NC}"
+        echo -e "  ${RED}The dashboard is reachable by EVERY device on your network,${NC}"
+        echo -e "  ${RED}and whoever opens it can run commands as ${BOLD}$USER${NC}${RED} through${NC}"
+        echo -e "  ${RED}your AI agents. Anyone on your Wi-Fi owns this machine.${NC}"
+        echo ""
+        echo -e "  Fix it by setting a password (takes 30 seconds):"
+        echo -e "    ${CYAN}•${NC} re-run the installer and choose a password, or"
+        echo -e "    ${CYAN}•${NC} add ${CYAN}Environment=CODEMAN_PASSWORD=<yours>${NC} to the service"
+        echo -e "  Or switch back to local-only: ${CYAN}CODEMAN_HOST=127.0.0.1${NC}"
+        echo -e "  ${DIM}Details: docs/security-architecture.md${NC}"
+    elif [[ "$BIND_HOST" == "0.0.0.0" ]]; then
+        echo -e "  ${YELLOW}${BOLD}Security:${NC}"
+        echo -e "    The dashboard is reachable from your network at port 3000 and is"
+        echo -e "    password-protected (user ${BOLD}admin${NC}). Keep that password strong:"
+        echo -e "    whoever logs in can run commands through your agents."
+        echo -e "    For access from OUTSIDE your network, prefer Tailscale or a tunnel."
+        echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
+    else
+        echo -e "  ${YELLOW}${BOLD}Security:${NC}"
+        echo -e "    Codeman binds ${BOLD}127.0.0.1${NC} (this machine only) — no password needed by default."
+        echo -e "    To reach it from another device, do ONE of:"
+        echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+        echo -e "      ${CYAN}•${NC} ${CYAN}codeman web --host 0.0.0.0${NC}  AND set ${CYAN}CODEMAN_PASSWORD${NC}"
+        echo -e "    A non-loopback bind without a password still starts, but warns loudly."
+        echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
+    fi
     echo ""
 }
 
@@ -781,6 +825,16 @@ read_reply() {
     fi
 }
 
+read_secret() {
+    # read_secret <varname>: like read_reply but without echoing (passwords)
+    if [[ -t 0 ]]; then
+        read -rs "$1"
+    else
+        read -rs "$1" < /dev/tty
+    fi
+    echo "" >&2
+}
+
 # headless_guard <action>: refuse consequential system changes (sudo package
 # installs, third-party curl | bash installers) when nobody can consent, i.e.
 # no terminal AND no explicit CODEMAN_NONINTERACTIVE=1 opt-in. Interactive
@@ -926,6 +980,188 @@ setup_sc_alias() {
     info "Added 'sc' alias for tmux-chooser"
 }
 
+# ============================================================================
+# Network Binding
+# ============================================================================
+
+# Best-effort LAN IP for "open this URL from your phone" hints.
+detect_lan_ip() {
+    local ip=""
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        ip=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || true)
+    else
+        ip=$(hostname -I 2>/dev/null | awk '{print $1}')
+    fi
+    echo "${ip:-<your-ip>}"
+}
+
+# Escape a value for a quoted systemd Environment="KEY=value" assignment.
+systemd_env_escape() {
+    printf '%s' "$1" | sed 's/[\\"]/\\&/g'
+}
+
+# Escape a value for embedding in a launchd plist <string>.
+xml_escape() {
+    printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'
+}
+
+systemd_env_unescape() {
+    printf '%s' "$1" | sed 's/\\\(["\\]\)/\1/g'
+}
+
+xml_unescape() {
+    printf '%s' "$1" | sed -e 's/&lt;/</g' -e 's/&gt;/>/g' -e 's/&amp;/\&/g'
+}
+
+# Read the binding out of an already-installed service file, if any. A service
+# file WITHOUT our CODEMAN_HOST line is a pre-1.8 install, which effectively
+# ran loopback (the server default), so it reports 127.0.0.1.
+read_existing_binding() {
+    EXISTING_FOUND="0"; EXISTING_HOST=""; EXISTING_PASSWORD=""; EXISTING_ACK="0"
+    local unit="$HOME/.config/systemd/user/codeman-web.service"
+    local plist="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+
+    if [[ -f "$unit" ]]; then
+        EXISTING_FOUND="1"
+        EXISTING_HOST=$(sed -n 's/^Environment=CODEMAN_HOST=//p' "$unit" | head -1)
+        local pwline
+        pwline=$(sed -n 's/^Environment="CODEMAN_PASSWORD=\(.*\)"$/\1/p' "$unit" | head -1)
+        [[ -n "$pwline" ]] && EXISTING_PASSWORD=$(systemd_env_unescape "$pwline")
+        grep -q '^Environment=CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1' "$unit" && EXISTING_ACK="1"
+    elif [[ -f "$plist" ]]; then
+        EXISTING_FOUND="1"
+        EXISTING_HOST=$(awk '/<key>CODEMAN_HOST<\/key>/{getline; print}' "$plist" | sed -n 's/.*<string>\(.*\)<\/string>.*/\1/p')
+        local pwraw
+        pwraw=$(awk '/<key>CODEMAN_PASSWORD<\/key>/{getline; print}' "$plist" | sed -n 's/.*<string>\(.*\)<\/string>.*/\1/p')
+        [[ -n "$pwraw" ]] && EXISTING_PASSWORD=$(xml_unescape "$pwraw")
+        grep -q '<key>CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK</key>' "$plist" && EXISTING_ACK="1"
+    fi
+
+    if [[ "$EXISTING_FOUND" == "1" && -z "$EXISTING_HOST" ]]; then
+        EXISTING_HOST="127.0.0.1"
+    fi
+    return 0
+}
+
+# Ask how the dashboard should be reachable and set BIND_HOST/BIND_PASSWORD/
+# BIND_ACK. Interactive default is network access (0.0.0.0) because that is
+# what most installs need; loopback is offered as the safer alternative.
+# Non-interactive runs keep the safe loopback default unless CODEMAN_HOST is
+# preset. The server binary itself still defaults to 127.0.0.1 either way.
+choose_network_binding() {
+    # Preset via environment: honor it and skip the prompt entirely.
+    if [[ -n "${CODEMAN_HOST:-}" ]]; then
+        BIND_HOST="$CODEMAN_HOST"
+        BIND_PASSWORD="${CODEMAN_PASSWORD:-}"
+        if [[ "$BIND_HOST" != "127.0.0.1" && -z "$BIND_PASSWORD" ]]; then
+            BIND_ACK="1"
+        fi
+        info "Network binding preset via CODEMAN_HOST: $BIND_HOST"
+        return 0
+    fi
+
+    # A previous install's choice is the baseline: re-installing must never
+    # silently loosen it.
+    read_existing_binding
+
+    if [[ "$NONINTERACTIVE" == "1" ]] || ! has_tty; then
+        if [[ "$EXISTING_FOUND" == "1" ]]; then
+            BIND_HOST="$EXISTING_HOST"
+            BIND_PASSWORD="$EXISTING_PASSWORD"
+            BIND_ACK="$EXISTING_ACK"
+            info "Non-interactive install: preserving existing binding ($BIND_HOST)"
+        else
+            BIND_HOST="127.0.0.1"
+            info "Non-interactive install: binding 127.0.0.1 (preset CODEMAN_HOST=0.0.0.0 to override)"
+        fi
+        return 0
+    fi
+
+    # Default follows the existing setup when there is one, else network.
+    local default_choice="1"
+    if [[ "$EXISTING_FOUND" == "1" && "$EXISTING_HOST" == "127.0.0.1" ]]; then
+        default_choice="2"
+    fi
+
+    echo -e "  ${BOLD}Network access${NC}"
+    echo ""
+    echo -e "  How should the Codeman dashboard be reachable?"
+    echo ""
+    echo -e "    ${CYAN}1)${NC} ${BOLD}Any device on your network${NC} ${DIM}(0.0.0.0)${NC}"
+    echo -e "       Open it straight from your phone or laptop."
+    echo -e "       ${YELLOW}Less safe: set a password so only you control your agents.${NC}"
+    echo -e "    ${CYAN}2)${NC} ${BOLD}This machine only${NC} ${DIM}(127.0.0.1)${NC}"
+    echo -e "       Safest. Reach it remotely via Tailscale or a tunnel."
+    echo ""
+    if [[ "$EXISTING_FOUND" == "1" ]]; then
+        echo -e "  ${DIM}Current setup: $EXISTING_HOST$([[ -n "$EXISTING_PASSWORD" ]] && echo ", password set"). Enter keeps it.${NC}"
+        echo ""
+    fi
+
+    local bind_choice=""
+    while true; do
+        echo -en "${CYAN}Choose [1/2] (default $default_choice):${NC} " >&2
+        read_reply bind_choice || bind_choice="$default_choice"
+        bind_choice="${bind_choice:-$default_choice}"
+        case "$bind_choice" in
+            1|2) break ;;
+            *) echo "Please enter 1 or 2." >&2 ;;
+        esac
+    done
+
+    if [[ "$bind_choice" == "2" ]]; then
+        BIND_HOST="127.0.0.1"
+        success "Binding 127.0.0.1 (this machine only)"
+        return 0
+    fi
+
+    # Keep a custom non-loopback host from a previous install (e.g. a specific
+    # interface IP); otherwise bind all interfaces.
+    if [[ "$EXISTING_FOUND" == "1" && -n "$EXISTING_HOST" && "$EXISTING_HOST" != "127.0.0.1" ]]; then
+        BIND_HOST="$EXISTING_HOST"
+    else
+        BIND_HOST="0.0.0.0"
+    fi
+
+    if [[ -n "${CODEMAN_PASSWORD:-}" ]]; then
+        BIND_PASSWORD="$CODEMAN_PASSWORD"
+        info "Using CODEMAN_PASSWORD from the environment"
+        return 0
+    fi
+
+    echo ""
+    local pw="" pw2="" keep_hint=""
+    [[ -n "$EXISTING_PASSWORD" ]] && keep_hint="Enter to keep the current one" || keep_hint="Enter to skip"
+    while true; do
+        echo -en "${CYAN}Set a dashboard password (recommended; $keep_hint):${NC} " >&2
+        read_secret pw || pw=""
+        if [[ -z "$pw" ]]; then
+            if [[ -n "$EXISTING_PASSWORD" ]]; then
+                BIND_PASSWORD="$EXISTING_PASSWORD"
+                success "Keeping the existing password"
+                break
+            fi
+            echo ""
+            warn "Without a password, EVERY device on your network gets full access"
+            warn "to your agents (they run commands as $USER)."
+            if prompt_yes_no "Continue WITHOUT a password?" "n"; then
+                BIND_ACK="1"
+                break
+            fi
+            continue
+        fi
+        echo -en "${CYAN}Confirm password:${NC} " >&2
+        read_secret pw2 || pw2=""
+        if [[ "$pw" == "$pw2" ]]; then
+            BIND_PASSWORD="$pw"
+            success "Password set (login user: admin)"
+            break
+        fi
+        echo "Passwords do not match, try again." >&2
+    done
+    return 0
+}
+
 # ============================================================================
 # Service Setup (Linux systemd / macOS launchd)
 # ============================================================================
@@ -976,6 +1212,21 @@ setup_launchd_service() {
     local node_path
     node_path=$(command -v node)
 
+    # Binding chosen during install (empty on paths that never asked)
+    local bind_plist=""
+    if [[ -n "$BIND_HOST" ]]; then
+        bind_plist="    <key>CODEMAN_HOST</key>
+    <string>$BIND_HOST</string>"
+        if [[ -n "$BIND_PASSWORD" ]]; then
+            bind_plist+=$'\n'"    <key>CODEMAN_PASSWORD</key>
+    <string>$(xml_escape "$BIND_PASSWORD")</string>"
+        fi
+        if [[ "$BIND_ACK" == "1" ]]; then
+            bind_plist+=$'\n'"    <key>CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK</key>
+    <string>1</string>"
+        fi
+    fi
+
     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">
@@ -997,6 +1248,7 @@ setup_launchd_service() {
     <string>$HOME</string>
     <key>LANG</key>
     <string>en_US.UTF-8</string>
+$bind_plist
   </dict>
   <key>WorkingDirectory</key>
   <string>$HOME</string>
@@ -1039,6 +1291,18 @@ setup_systemd_service() {
     local node_path
     node_path=$(command -v node)
 
+    # Binding chosen during install (empty on paths that never asked)
+    local bind_env=""
+    if [[ -n "$BIND_HOST" ]]; then
+        bind_env="Environment=CODEMAN_HOST=$BIND_HOST"
+        if [[ -n "$BIND_PASSWORD" ]]; then
+            bind_env+=$'\n'"Environment=\"CODEMAN_PASSWORD=$(systemd_env_escape "$BIND_PASSWORD")\""
+        fi
+        if [[ "$BIND_ACK" == "1" ]]; then
+            bind_env+=$'\n'"Environment=CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1"
+        fi
+    fi
+
     # Create service file
     cat > "$service_file" << EOF
 [Unit]
@@ -1053,6 +1317,7 @@ Restart=always
 RestartSec=10
 Environment=NODE_ENV=production
 Environment=PATH=$PATH
+$bind_env
 
 [Install]
 WantedBy=default.target
@@ -1419,6 +1684,11 @@ main() {
     echo -e "${GREEN}${BOLD}============================================================${NC}"
     echo ""
 
+    # Ask how the dashboard should be reachable BEFORE the launch menu, so the
+    # service files and the run-now path all inherit the choice.
+    choose_network_binding
+    echo ""
+
     local launch_choice=""
     local has_service=false
     local service_type=""
@@ -1506,7 +1776,12 @@ main() {
             echo -e "  ${GREEN}${BOLD}Codeman is running now!${NC}"
             echo ""
             echo -e "    ${CYAN}# Open in browser${NC}"
-            echo -e "    http://localhost:3000"
+            if [[ "$BIND_HOST" == "0.0.0.0" ]]; then
+                echo -e "    http://$(detect_lan_ip):3000   ${DIM}(any device on your network)${NC}"
+                echo -e "    http://localhost:3000       ${DIM}(this machine)${NC}"
+            else
+                echo -e "    http://localhost:3000"
+            fi
         else
             echo -e "  ${YELLOW}${BOLD}The service was set up but is not running yet${NC} (see warnings above)."
             echo -e "  ${DIM}You can always run it directly:${NC} ${CYAN}codeman web${NC}"
@@ -1531,11 +1806,23 @@ main() {
     if [[ "$launch_choice" != "2" ]]; then
         echo -e "  ${BOLD}Quick Start:${NC}"
         echo ""
-        echo -e "    ${CYAN}codeman web${NC}            # Start the web server"
-        echo -e "    ${CYAN}codeman web --https${NC}    # With HTTPS (for remote access)"
-        echo ""
-        echo -e "    ${CYAN}# Open in browser${NC}"
-        echo -e "    http://localhost:3000"
+        if [[ "$BIND_HOST" == "0.0.0.0" ]]; then
+            if [[ -n "$BIND_PASSWORD" ]]; then
+                echo -e "    ${CYAN}CODEMAN_HOST=0.0.0.0 CODEMAN_PASSWORD='<your-password>' codeman web${NC}"
+            else
+                echo -e "    ${CYAN}CODEMAN_HOST=0.0.0.0 codeman web${NC}"
+            fi
+            echo -e "    ${DIM}(a bare 'codeman web' binds 127.0.0.1, this machine only)${NC}"
+            echo ""
+            echo -e "    ${CYAN}# Open in browser${NC}"
+            echo -e "    http://$(detect_lan_ip):3000   ${DIM}(any device on your network)${NC}"
+        else
+            echo -e "    ${CYAN}codeman web${NC}            # Start the web server"
+            echo -e "    ${CYAN}codeman web --https${NC}    # With HTTPS (for remote access)"
+            echo ""
+            echo -e "    ${CYAN}# Open in browser${NC}"
+            echo -e "    http://localhost:3000"
+        fi
         echo ""
     fi
 
@@ -1584,6 +1871,11 @@ main() {
         # Source profile to pick up PATH changes, then exec codeman
         # shellcheck disable=SC1090
         source "$profile" 2>/dev/null || true
+        if [[ -n "$BIND_HOST" ]]; then
+            export CODEMAN_HOST="$BIND_HOST"
+            [[ -n "$BIND_PASSWORD" ]] && export CODEMAN_PASSWORD="$BIND_PASSWORD"
+            [[ "$BIND_ACK" == "1" ]] && export CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1
+        fi
         exec node "$INSTALL_DIR/dist/index.js" web
     fi
 }
@@ -1641,6 +1933,15 @@ update() {
     fi
     echo ""
 
+    # Reflect the service's actual binding in the closing notice. Updates
+    # never rewrite the service files, so the existing choice is authoritative.
+    read_existing_binding
+    if [[ "$EXISTING_FOUND" == "1" ]]; then
+        BIND_HOST="$EXISTING_HOST"
+        BIND_PASSWORD="$EXISTING_PASSWORD"
+        BIND_ACK="$EXISTING_ACK"
+    fi
+
     print_security_notice
 }
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.7.1",
+  "version": "1.8.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.7.1",
+      "version": "1.8.2",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -34,6 +34,7 @@
         "qrcode": "^1.5.4",
         "uuid": "^14.0.0",
         "web-push": "^3.6.7",
+        "ws": "^8.21.0",
         "zod": "^4.3.6"
       },
       "bin": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.7.1",
+  "version": "1.8.2",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -32,9 +32,17 @@
     "changeset": "changeset",
     "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",
+    "knip": "npx --yes knip@latest --config config/knip.json",
     "release": "changeset publish"
   },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "tabWidth": 2,
+    "printWidth": 120,
+    "trailingComma": "es5",
+    "endOfLine": "lf"
+  },
   "workspaces": [
     ".",
     "packages/*"
@@ -75,6 +83,7 @@
     "qrcode": "^1.5.4",
     "uuid": "^14.0.0",
     "web-push": "^3.6.7",
+    "ws": "^8.21.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

scripts/capture-readme-real.mjs

@@ -50,7 +50,7 @@ async function newCtx(browser) {
       try {
         localStorage.setItem('codeman:skin', skin);
         localStorage.setItem('codeman-font-size', String(font));
-        const blob = { skin, showFileBrowser: false, showProjectInsights: false };
+        const blob = { skin, showFileBrowser: false, showProjectInsights: false, showTokenCount: false };
         // Don't auto-hide subagent windows that belong to a non-active tab — the
         // subagent scene re-homes agents and needs both windows visible at once.
         blob.subagentActiveTabOnly = false;

scripts/capture-real-overview.mjs

@@ -79,6 +79,7 @@ const main = async () => {
           showMonitor: false,
           showSubagents: false,
           showProjectInsights: false,
+          showTokenCount: false,
         };
         if (planUsage) blob.showPlanUsageLimits = true;
         localStorage.setItem('codeman-app-settings', JSON.stringify(blob));

scripts/capture-subagent-gif.mjs

@@ -126,6 +126,7 @@ async function capture() {
         showMonitor: false,
         showProjectInsights: false,
         showFileBrowser: false,
+        showTokenCount: false,
       });
       localStorage.setItem('codeman-app-settings', JSON.stringify(existing));
     });
@@ -230,6 +231,7 @@ async function capture() {
         showMonitor: false,
         showProjectInsights: false,
         showFileBrowser: false,
+        showTokenCount: false,
       });
       localStorage.setItem('codeman-app-settings', JSON.stringify(existing));
     });

scripts/capture-subagent-screenshots.mjs

@@ -221,6 +221,7 @@ async function configureSettings(page) {
       subagentTrackingEnabled: true,
       subagentActiveTabOnly: false, // Show all subagents regardless of active tab
       showMonitor: true,
+      showTokenCount: false,
     };
     localStorage.setItem('codeman-app-settings', JSON.stringify(settings));
   });

src/config/webview-limits.ts

@@ -0,0 +1,49 @@
+/**
+ * Limits and timeouts for web tabs (dashboards embedded as Codeman tabs).
+ *
+ * Every value here bounds something an untrusted-ish upstream controls: how many
+ * dashboards can be saved, how long the server will wait on one, how much of a
+ * response it will buffer before rewriting HTML, and how many sockets a single
+ * dashboard may hold open. Env-overridable in the same style as the other config
+ * modules.
+ */
+
+function envInt(name: string, fallback: number): number {
+  const parsed = parseInt(process.env[name] || '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/** Max saved webviews (per owner in multi-user mode). */
+export const MAX_WEBVIEWS = envInt('CODEMAN_MAX_WEBVIEWS', 50);
+
+/**
+ * Max iframes kept mounted at once. Switching tabs must not reload a dashboard,
+ * so frames stay alive while hidden; past this many, the least-recently-viewed
+ * frame is evicted. Consumed by the frontend via `GET /api/webviews`.
+ */
+export const MAX_LIVE_WEBVIEW_FRAMES = envInt('CODEMAN_MAX_LIVE_WEBVIEW_FRAMES', 6);
+
+/** How long a minted proxy capability stays valid (rolling, refreshed on use). */
+export const WEBVIEW_CAPABILITY_TTL_MS = envInt('CODEMAN_WEBVIEW_CAPABILITY_TTL_MS', 12 * 60 * 60 * 1000);
+
+/** Max concurrent capabilities held in memory before the oldest are dropped. */
+export const MAX_WEBVIEW_CAPABILITIES = 200;
+
+/** Upstream request timeout for a proxied HTTP request. */
+export const WEBVIEW_UPSTREAM_TIMEOUT_MS = envInt('CODEMAN_WEBVIEW_TIMEOUT_MS', 30_000);
+
+/** Shorter timeout for the editor's "Test" probe, which a human is waiting on. */
+export const WEBVIEW_PROBE_TIMEOUT_MS = envInt('CODEMAN_WEBVIEW_PROBE_TIMEOUT_MS', 8_000);
+
+/**
+ * Max bytes of an HTML response buffered for `<base>` injection and link
+ * rewriting. Larger HTML documents stream through untouched: the rewrite is a
+ * convenience, and buffering an unbounded upstream body is a memory hazard.
+ */
+export const MAX_WEBVIEW_HTML_REWRITE_BYTES = envInt('CODEMAN_MAX_WEBVIEW_HTML_BYTES', 8 * 1024 * 1024);
+
+/** Max concurrent proxied WebSockets per webview (mirrors MAX_WS_PER_SESSION). */
+export const MAX_WEBVIEW_SOCKETS = envInt('CODEMAN_MAX_WEBVIEW_SOCKETS', 8);
+
+/** URL path prefix the proxy is mounted at. Single source of truth. */
+export const WEBVIEW_PROXY_PREFIX = '/webview';

src/types/index.ts

@@ -70,3 +70,4 @@ export * from './update.js';
 export * from './workflow-run.js';
 export * from './search.js';
 export * from './user.js';
+export * from './webview.js';

src/types/webview.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Web tab (dashboard) types.
+ *
+ * A "webview" is a saved URL that Codeman renders as a tab alongside agent
+ * sessions: Grafana on :3000, a Uptime-Kuma on :4000, an internal status page.
+ * It is deliberately NOT a sixth `SessionMode`, it has no PTY, no tmux, no
+ * respawn and no idle detection. Same reasoning that keeps Docker and remote-SSH
+ * as case overlays rather than modes.
+ *
+ * Key exports:
+ * - Webview, the persisted record (`~/.codeman/webviews.json`).
+ * - WebviewEmbedMode, 'proxy' (served through Codeman's origin) or 'direct'
+ *   (a plain cross-origin iframe, only viable for HTTPS targets that allow framing).
+ * - WebviewProbe, the result of the server-side reachability/framing probe.
+ * - WebviewOpenData, what `POST /api/webviews/:id/open` hands the browser.
+ *
+ * No I/O here. Persistence lives in `src/webview-store.ts`, capability minting in
+ * `src/webview-capabilities.ts`, the proxy helpers in `src/web/webview-proxy.ts`.
+ */
+
+/**
+ * How the browser should embed a webview.
+ *
+ * - `proxy`: the iframe points at `/webview/<capability>/` on Codeman's own
+ *   origin and the server relays to the target. Required whenever the target is
+ *   plain HTTP (an HTTPS Codeman page cannot embed it: mixed content) or refuses
+ *   framing via `X-Frame-Options` / `frame-ancestors`.
+ * - `direct`: the iframe points at the target URL itself. Cheaper, but only works
+ *   for HTTPS targets that permit framing, and needs the target origin added to
+ *   the page CSP's `frame-src`.
+ */
+export type WebviewEmbedMode = 'proxy' | 'direct';
+
+/** A saved dashboard, persisted to `~/.codeman/webviews.json`. */
+export interface Webview {
+  id: string;
+  /** Display name shown on the tab. */
+  name: string;
+  /** Absolute target URL. `http:` / `https:` only, never with embedded credentials. */
+  url: string;
+  /** Optional single-glyph tab icon (emoji or letter). */
+  icon?: string;
+  /** Default embed strategy for this dashboard. */
+  embedMode: WebviewEmbedMode;
+  /**
+   * When false (the default) the iframe is sandboxed WITHOUT `allow-same-origin`,
+   * so a proxied page runs in an opaque origin and cannot read the Codeman page or
+   * call its API. Setting this to true trades that isolation for the page's own
+   * cookies/localStorage, only for dashboards the user fully trusts.
+   */
+  trusted: boolean;
+  /** Multi-user owner (username). Undefined in single-user mode. */
+  owner?: string;
+  createdAt: number;
+  lastOpenedAt?: number;
+}
+
+/** Result of the server-side probe used by the "Test" button in the editor. */
+export interface WebviewProbe {
+  /** True when the server could complete an HTTP request to the target. */
+  reachable: boolean;
+  /** Upstream status code, when a response came back. */
+  status?: number;
+  /** Raw `X-Frame-Options` value, if the target sent one. */
+  xFrameOptions?: string;
+  /** The `frame-ancestors` directive extracted from the target's CSP, if any. */
+  frameAncestors?: string;
+  /** True when the target permits being framed cross-origin by this Codeman. */
+  framable: boolean;
+  /** Strategy the UI should default to for this URL. */
+  recommendedMode: WebviewEmbedMode;
+  /** Human-readable explanation of the recommendation (or the failure). */
+  reason: string;
+}
+
+/** Payload of `POST /api/webviews/:id/open`. */
+export interface WebviewOpenData {
+  /** The webview being opened (echoed so the client can refresh its copy). */
+  webview: Webview;
+  /**
+   * Same-origin path the iframe should load. Present for `proxy` mode only;
+   * `direct` mode uses `webview.url` instead.
+   */
+  embedUrl?: string;
+  /** Epoch ms at which the capability behind `embedUrl` stops working. */
+  expiresAt?: number;
+}

src/web/middleware/auth.ts

@@ -22,6 +22,8 @@ import {
 import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { findUser, setPassword, touchLastLogin, verifyPassword } from '../../user-store.js';
+import { webviewCapabilities } from '../../webview-capabilities.js';
+import { capabilityFromProxyPath, capabilityFromReferer } from '../webview-proxy.js';
 import { ApiErrorCode, createErrorResponse, type AuthUser } from '../../types.js';
 
 // Request-scoped identity (multi-user). Single-user leaves it undefined and the
@@ -120,6 +122,49 @@ function isPasswordChangeExempt(req: FastifyRequest): boolean {
   return !url.startsWith('/api/');
 }
 
+/**
+ * Whether this request carries a VALID web-tab proxy capability.
+ *
+ * Requests under `/webview/<cap>/` cannot authenticate the normal way. The iframe
+ * rendering a dashboard is sandboxed without `allow-same-origin`, so it runs in an
+ * opaque origin: every request it makes is cross-site, meaning the `SameSite=lax`
+ * `codeman_session` cookie is never attached, and non-GET requests and WebSocket
+ * upgrades arrive with `Origin: null`. Both the cookie check and the CSRF Origin
+ * guard would therefore reject a perfectly legitimate dashboard asset load.
+ *
+ * The capability in the path is the credential instead: 192 bits of entropy, held
+ * in memory only (a restart invalidates it), rolling TTL, bound to the user who
+ * minted it through an already-authenticated `POST /api/webviews/:id/open`, and
+ * granting nothing but "relay bytes to this one saved URL".
+ *
+ * The exemption is deliberately narrow: it requires the capability to RESOLVE, so
+ * a bare `/webview/anything` reaches nothing, and a `/webviewfoo` path does not
+ * match the prefix at all. The Host allowlist is NOT bypassed, so DNS-rebinding
+ * protection still applies to these requests.
+ */
+function hasValidWebviewCapability(req: FastifyRequest): boolean {
+  const url = (req.url ?? '').split('?')[0];
+
+  const fromPath = capabilityFromProxyPath(url);
+  if (fromPath) return webviewCapabilities.resolve(fromPath) !== undefined;
+
+  // Referer form: a dashboard subresource requested with a ROOT-ABSOLUTE URL, which
+  // lands on Codeman's root and is relayed by the 404 fallback. Without this the
+  // asset would be rejected here, before the fallback ever runs.
+  //
+  // This is the only exemption decided by a header the request itself supplies, so
+  // it is fenced in hard: safe methods only, and never for Codeman's own functional
+  // surfaces. Without those fences a page could present a webview Referer and skip
+  // auth on /api. It is not a privilege escalation even so, holding a live
+  // capability already implies an authenticated `POST /api/webviews/:id/open`, but
+  // the exemption should stay no wider than the problem it solves.
+  if (req.method !== 'GET' && req.method !== 'HEAD') return false;
+  if (url.startsWith('/api/') || url.startsWith('/ws/') || url.startsWith('/q/')) return false;
+
+  const fromReferer = capabilityFromReferer(typeof req.headers.referer === 'string' ? req.headers.referer : undefined);
+  return !!fromReferer && webviewCapabilities.resolve(fromReferer) !== undefined;
+}
+
 /**
  * Register HTTP Basic Auth middleware with session cookies and rate limiting.
  * Only active when CODEMAN_PASSWORD is set.
@@ -211,6 +256,12 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
       return;
     }
 
+    // Web-tab proxy, authenticated by the capability in the path, not the cookie.
+    if (hasValidWebviewCapability(req)) {
+      done();
+      return;
+    }
+
     const clientIp = req.ip;
 
     // Check session cookie first (avoids re-sending credentials on every request)
@@ -341,6 +392,12 @@ function registerMultiUserAuthHook(
     // QR redemption path — handled by the route itself.
     if (req.url?.startsWith('/q/')) return;
 
+    // Web-tab proxy, authenticated by the capability in the path, not the cookie.
+    // `req.authUser` stays undefined here on purpose: the proxy handler enforces
+    // ownership against the identity BOUND TO THE CAPABILITY, which is stricter
+    // than re-deriving it from a request that carries no credentials.
+    if (hasValidWebviewCapability(req)) return;
+
     const clientIp = req.ip;
 
     // 1. Cookie session (carries identity + mustChangePassword snapshot).
@@ -466,7 +523,17 @@ export function registerHostGuard(app: FastifyInstance, getPolicy: () => HostPol
       reply.code(403).send('Forbidden: host not allowed');
       return;
     }
-    if (!SAFE_HTTP_METHODS.has(req.method) && !isAllowedRequestOrigin(req.headers.origin, policy)) {
+    // The Host allowlist above is NEVER bypassed. The Origin (CSRF) check is,
+    // but only for a request carrying a valid web-tab capability: a sandboxed
+    // dashboard is opaque-origin, so its form posts and uploads arrive with
+    // `Origin: null`, which this guard rejects by design. The capability is the
+    // credential in that case, and it is unguessable, see
+    // hasValidWebviewCapability.
+    if (
+      !SAFE_HTTP_METHODS.has(req.method) &&
+      !isAllowedRequestOrigin(req.headers.origin, policy) &&
+      !hasValidWebviewCapability(req)
+    ) {
       reply.code(403).send('Forbidden: cross-site request blocked');
       return;
     }
@@ -521,8 +588,17 @@ export function registerSecurityHeaders(app: FastifyInstance, https: boolean): v
       }
     }
 
-    // Handle CORS preflight
-    if (req.method === 'OPTIONS') {
+    // Handle CORS preflight.
+    //
+    // EXCEPT for the web-tab proxy, which must answer its own preflight. A
+    // sandboxed dashboard iframe is opaque-origin, so it sends `Origin: null`;
+    // the CORS block above only emits headers for localhost origins, so a bare
+    // 204 from here carries no `Access-Control-Allow-Origin` and the browser
+    // rejects the preflight. Every dashboard fetch then fails with an opaque
+    // net::ERR_FAILED while the page itself renders fine (script/css/img loads
+    // are not CORS-checked). Falling through lets the proxy route reply with the
+    // right headers.
+    if (req.method === 'OPTIONS' && !hasValidWebviewCapability(req)) {
       reply.code(204).send();
       done();
       return;

src/web/public/app.js

@@ -294,6 +294,9 @@ const _SSE_HANDLER_MAP = [
 
   // Session order (global tab order sync, COD-131)
   [SSE_EVENTS.SESSION_ORDER_CHANGED, '_onSessionOrderChanged'],
+
+  // Web tabs (dashboard URLs)
+  [SSE_EVENTS.WEBVIEW_CHANGED, '_onWebviewChanged'],
 ];
 
 
@@ -821,6 +824,7 @@ class CodemanApp {
     const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null).catch(() => null);
     this.loadQuickStartCases(null, settingsPromise);
     this._initRunMode();
+    this.initWebviews?.();
     this.setupEventListeners();
     // Mobile: ensure button taps register even when keyboard is visible.
     // On mobile, tapping a button while the soft keyboard is up causes the
@@ -1007,9 +1011,18 @@ class CodemanApp {
         const digitMatch = code.match(/^Digit([1-9])$/);
         if (digitMatch) {
           const idx = parseInt(digitMatch[1], 10) - 1;
+          // Sessions occupy 1..N and web tabs continue from N+1, matching the
+          // numbers actually painted on the tabs.
           if (idx < this.sessionOrder.length) {
             e.preventDefault();
             this.selectSession(this.sessionOrder[idx]);
+          } else {
+            const webIdx = idx - this.sessionOrder.length;
+            const webId = (this.webviewOrder || [])[webIdx];
+            if (webId) {
+              e.preventDefault();
+              this.openWebview(webId);
+            }
           }
           return;
         }
@@ -3272,9 +3285,21 @@ class CodemanApp {
     const existingIds = new Set([...existingTabs].map(t => t.dataset.id));
     const currentIds = new Set(this.sessions.keys());
 
-    // Check if we can do incremental update (same session IDs)
+    // Web tabs live in the same strip but are not in this.sessions, so they need
+    // their own change check. Without it, the session-only comparison below is
+    // vacuously "unchanged" whenever session count is stable — most visibly with
+    // ZERO sessions (0 === 0), where opening a dashboard would never draw its tab.
+    const existingWebIds = [...container.querySelectorAll('.session-tab[data-webview-id]')].map(
+      t => t.dataset.webviewId
+    );
+    const wantedWebIds = (this.webviewOrder || []).filter(id => this.webviews?.has(id));
+    const webTabsUnchanged =
+      existingWebIds.length === wantedWebIds.length && existingWebIds.every((id, i) => id === wantedWebIds[i]);
+
+    // Check if we can do incremental update (same session IDs and same web tabs)
     const canIncremental = existingIds.size === currentIds.size &&
-      [...existingIds].every(id => currentIds.has(id));
+      [...existingIds].every(id => currentIds.has(id)) &&
+      webTabsUnchanged;
 
     if (canIncremental) {
       // Incremental update - only modify changed properties
@@ -3282,7 +3307,12 @@ class CodemanApp {
         const tab = container.querySelector(`.session-tab[data-id="${id}"]`);
         if (!tab) continue;
 
-        const isActive = id === this.activeSessionId;
+        // A web tab owns the active state while one is open. activeSessionId stays
+        // set (the terminal keeps streaming underneath, and switching back is
+        // instant): only the highlight moves. Without this the debounced render
+        // re-marks the session tab active moments after a web tab was selected,
+        // leaving two tabs lit at once.
+        const isActive = id === this.activeSessionId && !this.activeWebviewId;
         const status = session.status || 'idle';
         const name = this.getSessionName(session);
         const taskStats = session.taskStats || { running: 0, total: 0 };
@@ -3469,7 +3499,9 @@ class CodemanApp {
       const session = this.sessions.get(id);
       if (!session) continue; // Skip if session was removed
 
-      const isActive = id === this.activeSessionId;
+      // See the note in the incremental path: a web tab owns the active highlight
+      // while one is open, even though activeSessionId stays set.
+      const isActive = id === this.activeSessionId && !this.activeWebviewId;
       const status = session.status || 'idle';
       const name = this.getSessionName(session);
       const mode = session.mode || 'claude';
@@ -3516,6 +3548,11 @@ class CodemanApp {
       _tabIdx++;
     }
 
+    // Web tabs (dashboard URLs) render after the session tabs, continuing the
+    // Alt+N numbering. They carry data-webview-id instead of data-id, so every
+    // session-tab code path above (drag-and-drop, alerts, badges) skips them.
+    parts.push(this.renderWebviewTabs ? this.renderWebviewTabs(_tabIdx) : '');
+
     container.innerHTML = parts.join('');
 
     // Set up drag-and-drop handlers for tab reordering
@@ -4050,6 +4087,9 @@ class CodemanApp {
       return; // newer tab switch won
     }
 
+    // A session tab takes the stage back from any active web tab.
+    this._hideWebviewLayer?.();
+
     this._cleanupPreviousSession(sessionId);
     this.activeSessionId = sessionId;
     try { localStorage.setItem('codeman-active-session', sessionId); } catch {}

src/web/public/constants.js

@@ -494,6 +494,9 @@ const SSE_EVENTS = {
 
   // Session order (global tab order sync)
   SESSION_ORDER_CHANGED: 'session:orderChanged',
+
+  // Web tabs (dashboard URLs)
+  WEBVIEW_CHANGED: 'webview:changed',
 };
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/index.html

@@ -134,7 +134,7 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
           <span class="attachment-history-badge" id="attachmentHistoryBadge" style="display:none;">0</span>
         </button>
-        <button class="btn-icon-header btn-file-viewer btn-file-viewer--hidden" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
+        <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
         <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
@@ -142,9 +142,9 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
           <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
         </button>
-        <button class="btn-icon-header btn-lifecycle-log" onclick="app.openLifecycleLog()" title="Session Lifecycle Log" aria-label="Open session lifecycle log"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg></button>
+        <button class="btn-icon-header btn-lifecycle-log" style="display: none" onclick="app.openLifecycleLog()" title="Session Lifecycle Log" aria-label="Open session lifecycle log"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/></svg></button>
         <button class="btn-icon-header btn-settings" onclick="app.openAppSettings()" title="App Settings" aria-label="Open app settings"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg></button>
-        <div class="header-tokens" id="headerTokens" title="Total tokens across all sessions">0 tokens</div>
+        <div class="header-tokens" id="headerTokens" style="display: none" title="Total tokens across all sessions">0 tokens</div>
       </div>
     </header>
 
@@ -300,6 +300,11 @@
           autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
       </div>
 
+      <!-- Web tab layer: one iframe per open dashboard, shown in place of the
+           terminal while a web tab is active. Frames stay mounted while hidden so
+           switching tabs does not reload (and re-authenticate) a dashboard. -->
+      <div class="webview-layer" id="webviewLayer"></div>
+
       <!-- Welcome Overlay (shown when no session active) -->
       <div class="welcome-overlay" id="welcomeOverlay">
         <div class="welcome-content">
@@ -460,6 +465,18 @@
                 <span class="run-mode-dot gemini"></span>Gemini
               </button>
               <div class="run-mode-sep"></div>
+              <button class="run-mode-option" data-mode="shell" onclick="app.setRunMode('shell')">
+                <span class="run-mode-dot shell"></span>Terminal / Shell
+              </button>
+              <div class="run-mode-sep"></div>
+              <!-- Web tabs: dashboards open as tabs beside agent sessions. These do NOT
+                   set runMode: the Run button always means "start an agent". -->
+              <div class="run-mode-header">Web / URL</div>
+              <div class="run-mode-webviews" id="runModeWebviews"></div>
+              <button class="run-mode-option run-mode-option--add" onclick="app.showWebviewModal()">
+                <span class="run-mode-dot web"></span>Add URL&hellip;
+              </button>
+              <div class="run-mode-sep"></div>
               <div class="run-mode-header">Recent Sessions</div>
               <div class="run-mode-history" id="runModeHistory"></div>
             </div>
@@ -475,6 +492,12 @@
           <button class="btn-toolbar btn-shell" onclick="app.runShell()" title="Run Shell">
             Run Shell
           </button>
+          <!-- Phone-only: replaces the Shell button on ≤430px (Shell moves into the Run
+               dropdown there). Sends a bare Enter to the active session, the complement
+               to the accessory bar's Esc. Hidden everywhere else — see styles.css. -->
+          <button class="btn-toolbar btn-enter" onclick="app.sendEnterKey()" title="Send Enter">
+            Enter
+          </button>
           <div class="tab-count-group" title="Instance count">
             <button class="tab-count-btn" onclick="app.decrementShellCount()">−</button>
             <input type="number" id="shellCount" class="tab-count-input" value="1" min="1" max="20" readonly>
@@ -629,6 +652,56 @@
       </div>
     </div>
 
+    <!-- Web Tab (dashboard URL) editor -->
+    <div class="modal" id="webviewModal">
+      <div class="modal-backdrop" onclick="app.closeWebviewModal()"></div>
+      <div class="modal-content">
+        <div class="modal-header">
+          <h3 id="webviewModalTitle">Add URL</h3>
+          <button class="modal-close" onclick="app.closeWebviewModal()" aria-label="Close URL editor">&times;</button>
+        </div>
+        <div class="modal-body">
+          <div class="form-row">
+            <label for="webviewName">Name</label>
+            <input type="text" id="webviewName" placeholder="Grafana" autocomplete="off" spellcheck="false">
+          </div>
+          <div class="form-row">
+            <label for="webviewUrl">URL</label>
+            <input type="text" id="webviewUrl" placeholder="http://100.70.56.18:4000/" autocomplete="off"
+                   autocapitalize="off" spellcheck="false">
+            <span class="form-hint">
+              Reached from the Codeman server, so a tailnet or localhost address works even when
+              this browser cannot see it. Plain HTTP is fine: the dashboard is proxied through
+              Codeman, which is also what gets past dashboards that refuse to be embedded.
+            </span>
+          </div>
+          <div class="form-row">
+            <label for="webviewIcon">Icon</label>
+            <!-- Click to pick; the field stays editable so any emoji still works. -->
+            <div class="webview-icon-picker" id="webviewIconPicker" role="group" aria-label="Choose an icon"></div>
+            <input type="text" id="webviewIcon" placeholder="Or paste any emoji" maxlength="8" autocomplete="off">
+          </div>
+          <div class="form-row">
+            <label class="checkbox-row"><input type="checkbox" id="webviewSandboxed" checked> Open sandboxed</label>
+            <span class="form-hint">
+              Recommended. A proxied dashboard is served from Codeman's own address, so unchecking
+              this lets its JavaScript read this page and call the API that starts agents. Uncheck
+              only for a dashboard you fully trust, or one whose own login needs cookies.
+            </span>
+          </div>
+          <div class="form-row">
+            <button class="btn-secondary" onclick="app.testWebviewUrl()">Test</button>
+            <span class="form-hint webview-probe-result" id="webviewProbeResult"></span>
+          </div>
+        </div>
+        <div class="form-actions webview-modal-actions">
+          <button class="btn-danger" id="webviewDeleteBtn" onclick="app.deleteWebview()">Delete</button>
+          <button class="btn-secondary" onclick="app.closeWebviewModal()">Cancel</button>
+          <button class="btn-primary" onclick="app.saveWebview()">Save</button>
+        </div>
+      </div>
+    </div>
+
     <!-- Cron Jobs Modal -->
     <div class="modal" id="cronModal">
       <div class="modal-backdrop" onclick="app.closeCron()"></div>
@@ -2541,6 +2614,7 @@
   <script defer src="ultracode-panel.js"></script>
   <script defer src="admin-ui.js"></script>
   <script defer src="session-ui.js"></script>
+  <script defer src="webview-tabs.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
   <script defer src="subagent-windows.js"></script>

src/web/public/mobile.css

@@ -875,19 +875,44 @@ html.mobile-init .file-browser-panel {
     margin-right: 0;
   }
 
-  /* Secondary action - Run Shell - right side */
+  /* Shell is NOT a toolbar button on phones — it moved into the Run dropdown
+     (Terminal / Shell), freeing this slot for Enter. Starting a shell is a rare,
+     deliberate act; sending Enter is a constant one, so the scarce phone real
+     estate goes to Enter. */
   .btn-toolbar.btn-shell {
-    flex: 0 0 auto;
-    background: transparent;
-    border: 1px solid rgba(255, 255, 255, 0.2);
-    color: #9ca3af;
-    order: 4; /* Right position */
+    display: none !important;
   }
 
-  .btn-toolbar.btn-shell:hover,
-  .btn-toolbar.btn-shell:active {
-    background: rgba(255, 255, 255, 0.1);
-    color: #fff;
+  /* Secondary action - Enter - right side. Takes the slot (and the order) the
+     Shell button used to hold, so the toolbar rhythm is unchanged. */
+  .btn-toolbar.btn-enter {
+    display: flex !important;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    min-width: 54px;
+    width: 54px;
+    white-space: nowrap;
+    padding: 0 8px !important;
+    overflow: hidden;
+    font-size: 0.65rem;
+    font-weight: 600;
+    letter-spacing: 0.01em;
+    /* !important is REQUIRED here, not defensive habit: styles.css nests its skin
+       overrides inside `html:not([data-skin="og"]) { … }`, so a plain `.btn-toolbar`
+       in that block resolves to (0,2,1) and outranks this (0,2,0) rule. Without
+       !important the button silently renders in generic toolbar grey. */
+    background: rgba(30, 58, 95, 0.85) !important;
+    border: 1px solid rgba(59, 130, 246, 0.45) !important;
+    color: #dbeafe !important;
+    order: 4; /* Right position — same slot Shell used to occupy */
+  }
+
+  .btn-toolbar.btn-enter:hover,
+  .btn-toolbar.btn-enter:active {
+    background: rgba(37, 74, 122, 0.95) !important;
+    border-color: rgba(59, 130, 246, 0.7) !important;
+    color: #fff !important;
   }
 
   /* Hide case selector on mobile - simplified toolbar */
@@ -895,27 +920,12 @@ html.mobile-init .file-browser-panel {
     display: none !important;
   }
 
-  /* Simplified toolbar layout — Run, Shell, and Case */
+  /* Simplified toolbar layout — Run, Enter, and Case */
   .toolbar-left .toolbar-group:first-child {
     width: 100%;
     gap: 8px;
   }
 
-  .btn-toolbar.btn-shell {
-    flex: 0 0 auto;
-    min-width: 54px;
-    width: 54px;
-    white-space: nowrap;
-    padding: 0 8px !important;
-    overflow: hidden;
-    font-size: 0 !important;
-  }
-
-  .btn-toolbar.btn-shell::after {
-    content: "Shell";
-    font-size: 0.65rem;
-  }
-
   /* Mobile case button - visible on mobile */
   .btn-toolbar.btn-case-mobile {
     display: flex !important;

src/web/public/session-ui.js

@@ -394,6 +394,9 @@ Object.assign(CodemanApp.prototype, {
       if (mode === 'gemini') {
         return await this.runGemini();
       }
+      if (mode === 'shell') {
+        return await this.runShell();
+      }
       return await this.runClaude();
     } finally {
       const remaining = minLockMs - (Date.now() - startedAt);
@@ -500,10 +503,32 @@ Object.assign(CodemanApp.prototype, {
       gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
     }
     if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'shell' ? 'Run SH' : 'Run';
     }
   },
 
+  /** Send Enter to the active session (phone toolbar button).
+   *
+   *  MUST go through xterm's onData path, NOT straight to sendInput()/the API.
+   *  With local echo on (the mobile default) the characters you typed are still
+   *  buffered in the LocalEchoOverlay and have NEVER reached the PTY. The onData
+   *  Enter branch (terminal-ui.js) is what flushes that pending text and only
+   *  then sends \r. Send a bare \r instead and you submit an empty line while the
+   *  typed text stays stranded on screen — which reads as "the button does
+   *  nothing". triggerDataEvent replays it exactly as if the key were pressed,
+   *  so overlay flush, flushed-offset cleanup and ordering are all reused. */
+  sendEnterKey() {
+    if (!this.activeSessionId) return;
+    const coreService = this.terminal?._core?.coreService;
+    if (coreService && typeof coreService.triggerDataEvent === 'function') {
+      coreService.triggerDataEvent('\r', true);
+      return;
+    }
+    // Fallback only if xterm's private core API moves: correct when local echo
+    // is off, and still better than doing nothing.
+    this.sendInput('\r');
+  },
+
   _initRunMode() {
     try { this._runMode = localStorage.getItem('codeman_runMode') || 'claude'; } catch { this._runMode = 'claude'; }
     this._applyRunMode();

src/web/public/settings-ui.js

@@ -307,9 +307,9 @@ Object.assign(CodemanApp.prototype, {
     // Header visibility settings
     document.getElementById('appSettingsShowFontControls').checked = settings.showFontControls ?? defaults.showFontControls ?? false;
     document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? defaults.showSystemStats ?? true;
-    document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? true;
+    document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     document.getElementById('appSettingsShowResponseViewer').checked = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
-    document.getElementById('appSettingsShowFileViewerButton').checked = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? false;
+    document.getElementById('appSettingsShowFileViewerButton').checked = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? true;
     document.getElementById('appSettingsShowAttachmentsButton').checked = settings.showAttachmentsButton ?? defaults.showAttachmentsButton ?? false;
     document.getElementById('appSettingsSkin').value = settings.skin ?? defaults.skin ?? 'daylight-blue';
     // WebGL renderer (desktop only — mobile always uses the DOM renderer, so hide
@@ -1893,7 +1893,9 @@ Object.assign(CodemanApp.prototype, {
     const compactHeader = MobileDetection.getDeviceType() !== 'desktop';
     const showFontControls = compactHeader ? false : (settings.showFontControls ?? defaults.showFontControls ?? false);
     const showSystemStats = compactHeader ? false : (settings.showSystemStats ?? defaults.showSystemStats ?? true);
-    const showTokenCount = compactHeader ? false : (settings.showTokenCount ?? defaults.showTokenCount ?? true);
+    // Default OFF: the header stays gear + usage chips + files button unless a
+    // stored preference explicitly re-enables the token chip (no UI toggle exists).
+    const showTokenCount = compactHeader ? false : (settings.showTokenCount ?? defaults.showTokenCount ?? false);
 
     const fontControlsEl = document.querySelector('.header-font-controls');
     const systemStatsEl = document.getElementById('headerSystemStats');
@@ -1910,7 +1912,9 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Hide lifecycle log button when setting is disabled
-    const showLifecycleLog = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? true;
+    // Default OFF: the lifecycle-log document icon is opt-in; the default header
+    // keeps only WS/CPU/MEM, the file-viewer folder, usage chips, and the gear.
+    const showLifecycleLog = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     const lifecycleBtn = document.querySelector('.btn-lifecycle-log');
     if (lifecycleBtn) {
       lifecycleBtn.style.display = showLifecycleLog ? '' : 'none';
@@ -1934,7 +1938,9 @@ Object.assign(CodemanApp.prototype, {
 
     // File Viewer header button — opt-in, default OFF. Marker class (base is
     // display:inline-flex !important); clicking it toggles the file browser panel.
-    const showFileViewerButton = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? false;
+    // Default ON (desktop): the folder button is part of the standard header now;
+    // phones still hide it via mobile.css (btn-file-viewer in the phone-hidden set).
+    const showFileViewerButton = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? true;
     const fileViewerBtn = document.querySelector('.btn-file-viewer');
     if (fileViewerBtn) {
       fileViewerBtn.classList.toggle('btn-file-viewer--hidden', !showFileViewerButton);

src/web/public/styles.css

@@ -3129,6 +3129,12 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   /* contain: style only — layout/paint containment clips the case-settings popover
      that extends above the toolbar (popover uses position:absolute + bottom:100%) */
   contain: style;
+  /* backdrop-filter above makes this a stacking context, which TRAPS the
+     z-index:1000 on .run-mode-menu inside it. Without an explicit z-index here the
+     toolbar resolves to auto (0) and .welcome-overlay (z-index:10, inside <main>)
+     paints over the popped-up Run menu: with no session open, every item in that
+     menu is unclickable. Must stay below .modal (1000). */
+  z-index: 20;
 }
 
 /* backdrop-filter creates a stacking context, trapping the popover's
@@ -3370,6 +3376,14 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
 .run-mode-dot.opencode { background: #10b981; }
 .run-mode-dot.codex { background: #a855f7; }
 .run-mode-dot.gemini { background: #8ab4f8; }
+.run-mode-dot.shell { background: #94a3b8; }
+
+/* Phone-only Enter button (see index.html). Hidden by default at every width;
+   mobile.css turns it on inside @media (max-width: 430px), where it takes over
+   the slot the Shell button occupies on wider screens. */
+.btn-toolbar.btn-enter {
+  display: none;
+}
 
 .run-mode-sep {
   height: 1px;
@@ -11618,6 +11632,7 @@ html:not([data-skin="og"]) {
 .run-mode-dot.claude { background: var(--accent); }
 .run-mode-dot.opencode { background: var(--accent-soft); }
 .run-mode-dot.codex { background: var(--accent-grad-b); }
+.run-mode-dot.shell { background: var(--text-dim); }
 
 /* ---- Shell button: quiet neutral with a calm green tint ---- */
 .btn-toolbar.btn-shell {
@@ -11845,3 +11860,118 @@ html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
   display: flex; gap: 0.5rem; justify-content: flex-end;
   margin-top: 1rem; padding-top: 0.85rem; border-top: 1px solid var(--border);
 }
+
+/* ═══════════════════════════════════════════════════════════════
+   Web tabs (dashboard URLs embedded as tabs)
+   ═══════════════════════════════════════════════════════════════ */
+
+/* The iframe layer sits alongside .terminal-wrap inside <main> and only one of
+   the two is visible at a time. Frames stay in the DOM while hidden so switching
+   tabs does not reload a dashboard. */
+.webview-layer {
+  display: none;
+  flex: 1;
+  min-height: 0;
+  position: relative;
+  background: var(--term-bg, #161b23);
+}
+.main.webview-active .webview-layer { display: flex; }
+.main.webview-active .terminal-wrap { display: none; }
+
+.webview-frame {
+  display: none;
+  position: absolute;
+  inset: 0;
+}
+.webview-frame.active { display: block; }
+
+.webview-iframe {
+  width: 100%;
+  height: 100%;
+  border: 0;
+  display: block;
+  background: #fff;
+}
+
+/* Shown only when the frame never signalled load: a refused embed or an
+   unreachable host would otherwise be an unexplained blank rectangle. */
+.webview-failure { display: none; }
+.webview-frame--failed .webview-failure {
+  display: flex;
+  position: absolute;
+  inset: 0;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg, #0f1319);
+  padding: 1.5rem;
+  text-align: center;
+}
+.webview-failure-inner { max-width: 380px; }
+.webview-failure-inner h3 { margin: 0 0 0.5rem; font-size: 1rem; color: var(--text); }
+.webview-failure-inner p { margin: 0 0 1rem; font-size: 0.85rem; color: var(--text-dim); line-height: 1.5; }
+.webview-failure-actions { display: flex; gap: 0.5rem; justify-content: center; flex-wrap: wrap; }
+
+/* Tab styling: same shape as a session tab, distinguished by the globe icon and
+   a cool accent so a dashboard never reads as a running agent. */
+.session-tab--web .tab-web-icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--text-dim);
+  flex-shrink: 0;
+}
+.session-tab--web.active .tab-web-icon { color: var(--accent, #3ec8ee); }
+.session-tab--web.active { border-bottom-color: var(--accent, #3ec8ee); }
+
+.run-mode-dot.web { background: #38bdf8; }
+.run-mode-webviews { max-height: 180px; overflow-y: auto; }
+.run-mode-empty {
+  padding: 4px 10px 6px;
+  font-size: 0.75em;
+  color: var(--text-dim);
+  font-style: italic;
+}
+
+/* Icon picker: a compact grid above the free-text field, so the common case is a
+   click and the escape hatch (any emoji at all) stays available. */
+.webview-icon-picker {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-bottom: 6px;
+}
+.webview-icon-choice {
+  width: 34px;
+  height: 34px;
+  font-size: 1.05rem;
+  line-height: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--bg-soft, rgba(255, 255, 255, 0.03));
+  cursor: pointer;
+  padding: 0;
+}
+.webview-icon-choice:hover { border-color: var(--accent, #3ec8ee); }
+.webview-icon-choice.selected {
+  border-color: var(--accent, #3ec8ee);
+  box-shadow: 0 0 0 1px var(--accent, #3ec8ee) inset;
+}
+
+/* Saved-URL rows in the Run dropdown show their chosen icon in the dot's slot. */
+.run-mode-menu-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  margin-right: 6px;
+  font-size: 0.95em;
+  flex-shrink: 0;
+}
+
+.webview-probe-result.ok { color: var(--success, #10b981); }
+.webview-probe-result.bad { color: var(--danger, #ef4444); }
+/* Delete sits apart from Cancel/Save so it is not fat-fingered on the way to Save. */
+.webview-modal-actions { justify-content: space-between; }
+.webview-modal-actions .btn-danger { margin-right: auto; }

src/web/public/terminal-ui.js

@@ -969,8 +969,66 @@ Object.assign(CodemanApp.prototype, {
           return;
         }
 
-        // Get line text - translateToString handles wrapped lines
-        const lineText = line.translateToString(true);
+        // Stitch the LOGICAL line back together.
+        //
+        // xterm invokes this provider per visible ROW, and translateToString returns
+        // that row alone (the old comment here claimed otherwise). A URL or path
+        // longer than the terminal is wide therefore matched only as far as the row
+        // boundary, and the link opened a PREFIX of the real target. Walk out to both
+        // ends of the continuation, match against the joined text, and map offsets
+        // back to (x, y) so a link can span rows.
+        //
+        // Two different kinds of continuation, and handling only the first is not
+        // enough:
+        //   1. SOFT wrap: the emulator ran out of columns and flags the next row
+        //      `isWrapped`.
+        //   2. HARD wrap: the program did its own wrapping and emitted a real
+        //      newline, so nothing is flagged. Ink does this, which is why Claude
+        //      Code's own `/login` URL was cut at the window edge, and why the
+        //      clickable part grew when the window was widened.
+        // A row that fills the full width is treated as continuing into the next:
+        // that is the signal a hard wrap leaves behind, and a line that genuinely
+        // ended would stop short of the last column.
+        const cols = self.terminal.cols;
+        const rowAt = (r) => buffer.getLine(r - 1);
+        const continuesPrevious = (r) => {
+          if (r <= 1) return false;
+          if (rowAt(r)?.isWrapped) return true;
+          const prev = rowAt(r - 1);
+          return !!prev && prev.translateToString(true).length >= cols;
+        };
+
+        // Bounded so a screenful of full-width output (wide tables, box drawing)
+        // cannot make every hover stitch and re-scan the entire viewport.
+        const MAX_STITCHED_ROWS = 12;
+        let startRow = bufferLineNumber;
+        while (startRow > 1 && bufferLineNumber - startRow < MAX_STITCHED_ROWS && continuesPrevious(startRow)) {
+          startRow--;
+        }
+        let endRow = bufferLineNumber;
+        while (endRow < buffer.length && endRow - startRow < MAX_STITCHED_ROWS && continuesPrevious(endRow + 1)) {
+          endRow++;
+        }
+
+        const rowTexts = [];
+        for (let r = startRow; r <= endRow; r++) {
+          const row = rowAt(r);
+          if (!row) break;
+          // Only the final row may be trimmed. Continuation rows fill the width by
+          // definition, and trimming one would shift every later offset.
+          rowTexts.push(row.translateToString(r === endRow));
+        }
+        const lineText = rowTexts.join('');
+
+        /** Map an offset in the stitched text back to a 1-based terminal cell. */
+        const coordAt = (index) => {
+          let rest = index;
+          for (let i = 0; i < rowTexts.length - 1; i++) {
+            if (rest < rowTexts[i].length) return { x: rest + 1, y: startRow + i };
+            rest -= rowTexts[i].length;
+          }
+          return { x: rest + 1, y: startRow + rowTexts.length - 1 };
+        };
 
         if (!lineText || !lineText.includes('/')) {
           callback(undefined);
@@ -980,22 +1038,27 @@ Object.assign(CodemanApp.prototype, {
         const links = [];
 
         // Pattern 0: URLs (https://, http://) — matched first so they take priority
-        const urlPattern = /https?:\/\/[^\s"'<>|;&)\]\x00-\x1f]+/g;
+        //
+        // A single `&` is PART of the URL: it separates query parameters, so excluding
+        // it truncated every real query string (`?post=1479&action=edit` linked only
+        // through `1479`, landing on the wrong page). `&&` is still a boundary, since
+        // that is the shell operator and never appears inside a URL. A lone trailing
+        // `&` is trimmed below with the other trailing punctuation.
+        const urlPattern = /https?:\/\/(?:[^\s"'<>|;&)\]\x00-\x1f]|&(?!&))+/g;
 
         const addUrlLink = (url, matchIndex) => {
           // Strip trailing punctuation that's likely not part of the URL
-          const cleaned = url.replace(/[.,;:!?)]+$/, '');
+          const cleaned = url.replace(/[.,;:!?)&]+$/, '');
           const startCol = lineText.indexOf(cleaned, matchIndex);
           if (startCol === -1) return;
 
-          if (links.some((l) => l.range.start.x === startCol + 1)) return;
+          const start = coordAt(startCol);
+          const end = coordAt(startCol + cleaned.length);
+          if (links.some((l) => l.range.start.x === start.x && l.range.start.y === start.y)) return;
 
           links.push({
             text: cleaned,
-            range: {
-              start: { x: startCol + 1, y: bufferLineNumber },
-              end: { x: startCol + cleaned.length + 1, y: bufferLineNumber },
-            },
+            range: { start, end },
             decorations: { pointerCursor: true, underline: true },
             activate(_event, text) {
               window.open(text, '_blank', 'noopener,noreferrer');
@@ -1017,31 +1080,43 @@ Object.assign(CodemanApp.prototype, {
         // the whole tab on hover. Non-empty token + bounded reps is O(n).
         const cmdPattern = /\b(tail|cat|head|less|grep|watch|vim|nano)\s+(?:[^\s\/]+\s+){0,4}(\/[^\s"'<>|;&\n\x00-\x1f]+)/g;
 
-        // Pattern 2: Paths with common extensions
+        // Pattern 2: Paths with common extensions.
+        // Image/PDF extensions are included so pasted-attachment paths
+        // (`.claude-images/paste-*.png`) are clickable; they open the file preview
+        // rather than the log viewer (see addLink).
         const extPattern =
-          /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js))\b/g;
+          /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js|png|jpe?g|gif|webp|bmp|svg|pdf))\b/g;
 
         // Pattern 3: Bash() tool output
         const bashPattern = /Bash\([^)]*?(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\)\n\x00-\x1f]+)/g;
 
+        /** Extensions that should open the image/document preview, not the log viewer. */
+        const PREVIEW_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg', 'pdf']);
+
         const addLink = (filePath, matchIndex) => {
           const startCol = lineText.indexOf(filePath, matchIndex);
           if (startCol === -1) return;
 
+          const start = coordAt(startCol);
+          const end = coordAt(startCol + filePath.length);
           // Skip if already have link at this position
-          if (links.some((l) => l.range.start.x === startCol + 1)) return;
+          if (links.some((l) => l.range.start.x === start.x && l.range.start.y === start.y)) return;
 
           links.push({
             text: filePath,
-            range: {
-              start: { x: startCol + 1, y: bufferLineNumber }, // 1-based
-              end: { x: startCol + filePath.length + 1, y: bufferLineNumber },
-            },
+            range: { start, end }, // 1-based, may span wrapped rows
             decorations: {
               pointerCursor: true,
               underline: true,
             },
             activate(event, text) {
+              // Tailing a PNG in the log viewer shows binary noise; the file preview
+              // already renders images and PDFs inline.
+              const ext = (text.split('.').pop() || '').toLowerCase();
+              if (PREVIEW_EXTS.has(ext)) {
+                self.openFilePreview(text, self.activeSessionId);
+                return;
+              }
               self.openLogViewerWindow(text, self.activeSessionId);
             },
             hover() {

src/web/public/webview-tabs.js

@@ -0,0 +1,445 @@
+/**
+ * @fileoverview Web tabs: saved dashboard URLs rendered as tabs beside agent
+ * sessions, so Codeman is one mission control instead of Codeman plus a pile of
+ * browser tabs.
+ *
+ * Each open dashboard is an <iframe> inside #webviewLayer, which covers the
+ * terminal while a web tab is active. Frames stay MOUNTED while hidden, because a
+ * dashboard that reloads and re-authenticates on every tab switch is worse than
+ * the browser tab it replaced. `maxLiveFrames` (from the server) bounds that with
+ * least-recently-viewed eviction.
+ *
+ * Sandboxing: a proxied dashboard is served from Codeman's own origin, so the
+ * iframe deliberately omits `allow-same-origin` unless the dashboard is marked
+ * trusted. Without that omission the page could read this document and call the
+ * API that spawns agents.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js, api-client.js, constants.js (escapeHtml)
+ * @loadorder 12.5 of 16, after session-ui.js (needs the tab strip), before api-client.js
+ */
+
+Object.assign(CodemanApp.prototype, {
+  // ── State ─────────────────────────────────────────────────────────────────
+
+  /** Load the saved list and restore which tabs were open. */
+  async initWebviews() {
+    this.webviews = this.webviews || new Map();
+    this.webviewOrder = this.webviewOrder || [];
+    this.activeWebviewId = this.activeWebviewId || null;
+    this._webviewMaxFrames = this._webviewMaxFrames || 6;
+    this._webviewFrameLru = this._webviewFrameLru || [];
+
+    await this.refreshWebviews();
+
+    // Restore the previously open web tabs (per device: which dashboards you keep
+    // open is a workspace-layout choice, not something to sync across machines).
+    let saved = [];
+    try {
+      saved = JSON.parse(localStorage.getItem('codeman-webview-order') || '[]');
+    } catch {
+      saved = [];
+    }
+    this.webviewOrder = saved.filter((id) => this.webviews.has(id));
+    this.renderSessionTabs();
+  },
+
+  async refreshWebviews() {
+    const data = await this._apiJson('/api/webviews');
+    if (!data) return;
+    this.webviews = new Map((data.webviews || []).map((w) => [w.id, w]));
+    if (typeof data.maxLiveFrames === 'number') this._webviewMaxFrames = data.maxLiveFrames;
+    this.renderWebviewMenuItems();
+  },
+
+  /** SSE: the saved list changed (possibly on another device). */
+  async _onWebviewChanged(data) {
+    await this.refreshWebviews();
+    // A dashboard deleted elsewhere must not linger as a dead tab here.
+    if (data && data.action === 'deleted' && data.id) this._removeWebviewTab(data.id);
+    this.renderSessionTabs();
+  },
+
+  _persistWebviewOrder() {
+    try {
+      localStorage.setItem('codeman-webview-order', JSON.stringify(this.webviewOrder || []));
+    } catch {
+      /* private mode / quota, order is a convenience, never fatal */
+    }
+  },
+
+  // ── Tab strip ─────────────────────────────────────────────────────────────
+
+  /**
+   * Tab HTML for every OPEN web tab, appended by _fullRenderSessionTabs().
+   * `startIndex` continues the Alt+N numbering after the session tabs.
+   */
+  renderWebviewTabs(startIndex) {
+    if (!this.webviewOrder || this.webviewOrder.length === 0) return '';
+    const parts = [];
+    let idx = startIndex;
+
+    for (const id of this.webviewOrder) {
+      const webview = this.webviews.get(id);
+      if (!webview) continue;
+      const isActive = id === this.activeWebviewId;
+      const jsonId = escapeHtml(JSON.stringify(id));
+      const icon = webview.icon ? escapeHtml(webview.icon) : '';
+
+      parts.push(`<div class="session-tab session-tab--web ${isActive ? 'active' : ''}" data-webview-id="${escapeHtml(id)}"
+          onclick="app.handleWebviewTabClick(event, ${jsonId})"
+          tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}"
+          aria-label="${escapeHtml(webview.name)} web tab" title="${escapeHtml(webview.url)}">
+          ${idx < 9 ? '<span class="tab-number">' + (idx + 1) + '</span>' : ''}
+          <span class="tab-web-icon" aria-hidden="true">${icon || this._webviewGlobeIcon()}</span>
+          <span class="tab-info">
+            <span class="tab-name-row">
+              <span class="tab-name">${escapeHtml(webview.name)}</span>
+            </span>
+          </span>
+          <span class="tab-gear" onclick="event.stopPropagation(); app.showWebviewModal(${jsonId})" title="URL settings" aria-label="URL settings" tabindex="0">&#x2699;</span>
+          <span class="tab-close" onclick="event.stopPropagation(); app.closeWebviewTab(${jsonId})" title="Close tab" aria-label="Close web tab" tabindex="0">&times;</span>
+        </div>`);
+      idx++;
+    }
+    return parts.join('');
+  },
+
+  _webviewGlobeIcon() {
+    return '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M2 12h20M12 2a15 15 0 0 1 0 20 15 15 0 0 1 0-20"/></svg>';
+  },
+
+  handleWebviewTabClick(event, id) {
+    event?.preventDefault?.();
+    return this.openWebview(id);
+  },
+
+  /** Mark exactly one tab active across BOTH tab kinds. */
+  _updateActiveWebviewTab() {
+    const container = this.$('sessionTabs');
+    if (!container) return;
+    for (const tab of container.querySelectorAll('.session-tab[data-webview-id]')) {
+      tab.classList.toggle('active', tab.dataset.webviewId === this.activeWebviewId);
+    }
+    if (this.activeWebviewId) {
+      // A web tab is active, so no session tab may also look active.
+      for (const tab of container.querySelectorAll('.session-tab[data-id]')) tab.classList.remove('active');
+    }
+  },
+
+  // ── Opening / closing ─────────────────────────────────────────────────────
+
+  /**
+   * Open (or focus) a dashboard tab. Mints a fresh capability every time: they are
+   * memory-only and expire, so a tab reopened after a server restart must not reuse
+   * the dead URL from the previous run.
+   */
+  async openWebview(id) {
+    const webview = this.webviews.get(id);
+    if (!webview) return;
+
+    if (!this.webviewOrder.includes(id)) {
+      this.webviewOrder.push(id);
+      this._persistWebviewOrder();
+    }
+
+    const data = await this._apiJson(`/api/webviews/${encodeURIComponent(id)}/open`, { method: 'POST' });
+    if (!data) {
+      this.showToast?.('Could not open URL', 'error');
+      return;
+    }
+    if (data.webview) this.webviews.set(id, data.webview);
+
+    const src = data.embedUrl || data.webview?.url || webview.url;
+    this._mountWebviewFrame(id, src, data.webview || webview);
+    this.activeWebviewId = id;
+    this.hideWelcome?.();
+    document.querySelector('.main')?.classList.add('webview-active');
+    this.renderSessionTabs();
+    this._updateActiveWebviewTab();
+  },
+
+  /** Create the frame if absent, then reveal it and hide its siblings. */
+  _mountWebviewFrame(id, src, webview) {
+    const layer = document.getElementById('webviewLayer');
+    if (!layer) return;
+
+    let wrap = layer.querySelector(`.webview-frame[data-webview-id="${CSS.escape(id)}"]`);
+    if (!wrap) {
+      wrap = document.createElement('div');
+      wrap.className = 'webview-frame';
+      wrap.dataset.webviewId = id;
+
+      const frame = document.createElement('iframe');
+      frame.className = 'webview-iframe';
+      frame.setAttribute('title', webview.name);
+      // No allow-same-origin unless explicitly trusted: a proxied page is served
+      // from THIS origin, so granting it would let the dashboard read this document
+      // and drive the Codeman API.
+      const sandbox = ['allow-scripts', 'allow-forms', 'allow-popups', 'allow-downloads', 'allow-modals'];
+      if (webview.trusted) sandbox.push('allow-same-origin');
+      frame.setAttribute('sandbox', sandbox.join(' '));
+      frame.setAttribute('referrerpolicy', 'no-referrer-when-downgrade');
+      frame.src = src;
+
+      const failure = document.createElement('div');
+      failure.className = 'webview-failure';
+      failure.innerHTML = this._webviewFailureHtml(id);
+
+      wrap.appendChild(frame);
+      wrap.appendChild(failure);
+      layer.appendChild(wrap);
+
+      // A frame that never fires `load` is the normal symptom of a refused embed or
+      // an unreachable host. Show an actionable panel instead of a blank rectangle.
+      const timer = setTimeout(() => wrap.classList.add('webview-frame--failed'), 8000);
+      frame.addEventListener('load', () => {
+        clearTimeout(timer);
+        wrap.classList.remove('webview-frame--failed');
+      });
+    }
+
+    this._touchWebviewFrame(id);
+    for (const other of layer.querySelectorAll('.webview-frame')) {
+      other.classList.toggle('active', other.dataset.webviewId === id);
+    }
+    // Chart libraries measure on resize; a frame revealed from display:none needs the nudge.
+    requestAnimationFrame(() => window.dispatchEvent(new Event('resize')));
+  },
+
+  _webviewFailureHtml(id) {
+    const jsonId = escapeHtml(JSON.stringify(id));
+    return `<div class="webview-failure-inner">
+        <h3>This URL did not load</h3>
+        <p>It may be unreachable from the Codeman server, or it may refuse to be embedded.</p>
+        <div class="webview-failure-actions">
+          <button class="btn-secondary" onclick="app.reloadWebview(${jsonId})">Reload</button>
+          <button class="btn-secondary" onclick="app.openWebviewExternal(${jsonId})">Open in new tab</button>
+          <button class="btn-secondary" onclick="app.showWebviewModal(${jsonId})">Edit</button>
+        </div>
+      </div>`;
+  },
+
+  /** Least-recently-viewed eviction so N open dashboards cannot pin N live pages. */
+  _touchWebviewFrame(id) {
+    this._webviewFrameLru = (this._webviewFrameLru || []).filter((x) => x !== id);
+    this._webviewFrameLru.push(id);
+    const layer = document.getElementById('webviewLayer');
+    if (!layer) return;
+    while (this._webviewFrameLru.length > this._webviewMaxFrames) {
+      const evict = this._webviewFrameLru.shift();
+      if (evict === this.activeWebviewId) continue;
+      layer.querySelector(`.webview-frame[data-webview-id="${CSS.escape(evict)}"]`)?.remove();
+    }
+  },
+
+  reloadWebview(id) {
+    const target = id || this.activeWebviewId;
+    if (!target) return;
+    document
+      .getElementById('webviewLayer')
+      ?.querySelector(`.webview-frame[data-webview-id="${CSS.escape(target)}"]`)
+      ?.remove();
+    this._webviewFrameLru = (this._webviewFrameLru || []).filter((x) => x !== target);
+    return this.openWebview(target);
+  },
+
+  openWebviewExternal(id) {
+    const webview = this.webviews.get(id || this.activeWebviewId);
+    if (webview) window.open(webview.url, '_blank', 'noopener');
+  },
+
+  closeWebviewTab(id) {
+    this._removeWebviewTab(id);
+    this.renderSessionTabs();
+  },
+
+  _removeWebviewTab(id) {
+    this.webviewOrder = (this.webviewOrder || []).filter((x) => x !== id);
+    this._webviewFrameLru = (this._webviewFrameLru || []).filter((x) => x !== id);
+    this._persistWebviewOrder();
+    document
+      .getElementById('webviewLayer')
+      ?.querySelector(`.webview-frame[data-webview-id="${CSS.escape(id)}"]`)
+      ?.remove();
+
+    if (this.activeWebviewId === id) {
+      this.activeWebviewId = null;
+      const next = this.webviewOrder[0];
+      if (next) {
+        this.openWebview(next);
+      } else {
+        this._hideWebviewLayer();
+        // Fall back to whatever session was last shown, or the welcome screen.
+        if (this.activeSessionId) this._updateActiveTabImmediate(this.activeSessionId);
+        else this.showWelcome?.();
+      }
+    }
+  },
+
+  /** Called by selectSession(): a session tab takes the stage back from a web tab. */
+  _hideWebviewLayer() {
+    if (!this.activeWebviewId && !document.querySelector('.main.webview-active')) return;
+    this.activeWebviewId = null;
+    document.querySelector('.main')?.classList.remove('webview-active');
+    for (const frame of document.querySelectorAll('#webviewLayer .webview-frame')) {
+      frame.classList.remove('active');
+    }
+    this._updateActiveWebviewTab();
+  },
+
+  // ── Run-menu entries ──────────────────────────────────────────────────────
+
+  /** Saved dashboards listed inside the Run dropdown, under "Web / URL". */
+  renderWebviewMenuItems() {
+    const container = document.getElementById('runModeWebviews');
+    if (!container) return;
+    const list = [...(this.webviews?.values() || [])];
+    if (list.length === 0) {
+      container.innerHTML = '<div class="run-mode-empty">No URLs yet</div>';
+      return;
+    }
+    container.innerHTML = list
+      .map(
+        (w) => `<button class="run-mode-option run-mode-option--web" onclick="app.openWebviewFromMenu(${escapeHtml(
+          JSON.stringify(w.id)
+        )})" title="${escapeHtml(w.url)}">
+          <span class="run-mode-menu-icon">${w.icon ? escapeHtml(w.icon) : '<span class="run-mode-dot web"></span>'}</span>${escapeHtml(
+            w.name
+          )}
+        </button>`
+      )
+      .join('');
+  },
+
+  openWebviewFromMenu(id) {
+    document.getElementById('runModeMenu')?.classList.remove('active');
+    return this.openWebview(id);
+  },
+
+  // ── Icon picker ───────────────────────────────────────────────────────────
+
+  /** Common dashboard/service glyphs. The text field stays open for anything else. */
+  _webviewIconChoices() {
+    return ['📊', '📈', '🖥️', '🎛️', '📡', '🐳', '🗄️', '🔒', '🌐', '📁', '🧪', '🧬', '⚡', '🔔', '📝', '🎧'];
+  },
+
+  _renderWebviewIconPicker(selected) {
+    const picker = document.getElementById('webviewIconPicker');
+    if (!picker) return;
+    picker.innerHTML = this._webviewIconChoices()
+      .map(
+        (icon) =>
+          `<button type="button" class="webview-icon-choice${icon === selected ? ' selected' : ''}"
+             onclick="app.pickWebviewIcon(${escapeHtml(JSON.stringify(icon))})"
+             aria-label="Use ${escapeHtml(icon)} as the icon">${escapeHtml(icon)}</button>`
+      )
+      .join('');
+  },
+
+  /** Clicking the selected icon again clears it, so there is a way back to no icon. */
+  pickWebviewIcon(icon) {
+    const field = document.getElementById('webviewIcon');
+    if (!field) return;
+    field.value = field.value === icon ? '' : icon;
+    this._renderWebviewIconPicker(field.value);
+  },
+
+  // ── Editor modal ──────────────────────────────────────────────────────────
+
+  showWebviewModal(id) {
+    const modal = document.getElementById('webviewModal');
+    if (!modal) return;
+    const webview = id ? this.webviews.get(id) : null;
+    this._editingWebviewId = webview ? webview.id : null;
+
+    document.getElementById('webviewModalTitle').textContent = webview ? 'Edit URL' : 'Add URL';
+    this._renderWebviewIconPicker(webview?.icon || '');
+    document.getElementById('webviewName').value = webview?.name || '';
+    document.getElementById('webviewUrl').value = webview?.url || '';
+    document.getElementById('webviewIcon').value = webview?.icon || '';
+    document.getElementById('webviewSandboxed').checked = !webview?.trusted;
+    document.getElementById('webviewProbeResult').textContent = '';
+    document.getElementById('webviewDeleteBtn').style.display = webview ? '' : 'none';
+
+    document.getElementById('runModeMenu')?.classList.remove('active');
+    modal.classList.add('active');
+    document.getElementById('webviewName').focus();
+  },
+
+  closeWebviewModal() {
+    document.getElementById('webviewModal')?.classList.remove('active');
+    this._editingWebviewId = null;
+  },
+
+  /** Server-side probe: it runs from the network position the proxy will use. */
+  async testWebviewUrl() {
+    const url = document.getElementById('webviewUrl').value.trim();
+    const out = document.getElementById('webviewProbeResult');
+    if (!url) {
+      out.textContent = 'Enter a URL first.';
+      return;
+    }
+    out.textContent = 'Testing...';
+    const probe = await this._apiJson('/api/webviews/probe', { method: 'POST', body: { url } });
+    if (!probe) {
+      out.textContent = 'Test failed (invalid URL?).';
+      return;
+    }
+    out.textContent = probe.reachable
+      ? `Reachable (HTTP ${probe.status}). ${probe.reason}`
+      : `Not reachable. ${probe.reason}`;
+    out.className = 'form-hint webview-probe-result ' + (probe.reachable ? 'ok' : 'bad');
+  },
+
+  async saveWebview() {
+    const name = document.getElementById('webviewName').value.trim();
+    const url = document.getElementById('webviewUrl').value.trim();
+    const icon = document.getElementById('webviewIcon').value.trim();
+    const trusted = !document.getElementById('webviewSandboxed').checked;
+    if (!name || !url) {
+      this.showToast?.('Name and URL are required', 'error');
+      return;
+    }
+
+    // `icon: undefined` rather than null, the schema uses .optional(), which
+    // rejects an explicit null on the wire.
+    const body = { name, url, icon: icon || undefined, trusted };
+    const editing = this._editingWebviewId;
+    const data = editing
+      ? await this._apiJson(`/api/webviews/${encodeURIComponent(editing)}`, { method: 'PATCH', body })
+      : await this._apiJson('/api/webviews', { method: 'POST', body });
+
+    if (!data) {
+      this.showToast?.('Could not save (check the URL)', 'error');
+      return;
+    }
+
+    await this.refreshWebviews();
+    this.closeWebviewModal();
+    if (editing) {
+      // The capability was revoked server-side by the edit, so a mounted frame is
+      // now pointing at a dead URL. Remount it.
+      if (this.webviewOrder.includes(editing)) this.reloadWebview(editing);
+    } else {
+      this.openWebview(data.id);
+    }
+  },
+
+  async deleteWebview() {
+    const id = this._editingWebviewId;
+    if (!id) return;
+    const webview = this.webviews.get(id);
+    if (!confirm(`Delete "${webview?.name || id}"?`)) return;
+    const res = await this._apiDelete(`/api/webviews/${encodeURIComponent(id)}`);
+    if (!res || !res.ok) {
+      this.showToast?.('Could not delete URL', 'error');
+      return;
+    }
+    this._removeWebviewTab(id);
+    this.webviews.delete(id);
+    this.closeWebviewModal();
+    this.renderWebviewMenuItems();
+    this.renderSessionTabs();
+  },
+});

src/web/routes/index.ts

@@ -22,3 +22,4 @@ export { registerSearchRoutes } from './search-routes.js';
 export { registerMeRoutes } from './me-routes.js';
 export { registerAdminRoutes } from './admin-routes.js';
 export { registerWsRoutes } from './ws-routes.js';
+export { registerWebviewRoutes, tryWebviewRefererFallback } from './webview-routes.js';

src/web/routes/webview-routes.ts

@@ -0,0 +1,629 @@
+/**
+ * @fileoverview Web tabs: saved dashboard URLs, plus the reverse proxy that makes
+ * them embeddable.
+ *
+ * Two distinct surfaces live here, and the split matters:
+ *
+ * 1. `/api/webviews/*`, ordinary authenticated CRUD, owner-scoped like every
+ *    other resource, returning the `ApiResponse` envelope.
+ * 2. `/webview/:cap/*`, the proxy. NOT an API surface. It authenticates on an
+ *    unguessable capability in the path instead of Codeman's session cookie, and
+ *    is correspondingly exempt from the cookie and Origin checks in
+ *    `middleware/auth.ts`. See `src/webview-capabilities.ts` for why a cookie
+ *    cannot work here (sandboxed iframes are opaque-origin, so their requests are
+ *    cross-site and arrive with `Origin: null`).
+ *
+ * The proxy is registered inside an ENCAPSULATED plugin scope with its own
+ * catch-all content-type parser. Fastify scopes parsers to the plugin that
+ * registers them, which is what lets the proxy forward raw request bodies
+ * upstream while the rest of the app keeps its JSON parsing (and, critically,
+ * keeps `text/plain` raw, auto-parsing that was a real CSRF hole once).
+ *
+ * Endpoints:
+ *   GET    /api/webviews
+ *   POST   /api/webviews
+ *   PATCH  /api/webviews/:id
+ *   DELETE /api/webviews/:id
+ *   POST   /api/webviews/probe
+ *   POST   /api/webviews/:id/open
+ *   ALL    /webview/:cap/*   (+ WebSocket upgrade on GET)
+ */
+
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { WebSocket as WsClient } from 'ws';
+import type { WebSocket } from 'ws';
+import { getDataDir } from '../../config/instance.js';
+import {
+  MAX_LIVE_WEBVIEW_FRAMES,
+  MAX_WEBVIEWS,
+  MAX_WEBVIEW_HTML_REWRITE_BYTES,
+  MAX_WEBVIEW_SOCKETS,
+  WEBVIEW_PROBE_TIMEOUT_MS,
+  WEBVIEW_PROXY_PREFIX,
+  WEBVIEW_UPSTREAM_TIMEOUT_MS,
+} from '../../config/webview-limits.js';
+import { readWebviews, writeWebviews } from '../../webview-store.js';
+import { webviewCapabilities } from '../../webview-capabilities.js';
+import { ApiErrorCode, createErrorResponse } from '../../types.js';
+import type { Webview, WebviewOpenData, WebviewProbe } from '../../types.js';
+import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
+import { canAccessOwned, getAuthUser, ownerFor, parseBody } from '../route-helpers.js';
+import { WebviewCreateSchema, WebviewProbeSchema, WebviewUpdateSchema } from '../schemas.js';
+import { SseEvent } from '../sse-events.js';
+import type { EventPort } from '../ports/index.js';
+import {
+  buildDownstreamResponseHeaders,
+  buildProxyCorsHeaders,
+  buildUpstreamRequestHeaders,
+  capabilityFromReferer,
+  extractFrameAncestors,
+  isFramableCrossOrigin,
+  isHtmlContentType,
+  parseWebviewUrl,
+  proxyPrefixFor,
+  resolveUpstreamUrl,
+  rewriteHtml,
+  upstreamWebSocketUrl,
+} from '../webview-proxy.js';
+
+/**
+ * Resolved per call rather than captured at module load. `getDataDir()` reads
+ * `CODEMAN_DATA_DIR` each time, so a lazy lookup keeps tests writing to a temp dir
+ * instead of the developer's real `~/.codeman/webviews.json`.
+ */
+function configDir(): string {
+  return getDataDir();
+}
+
+/** Live proxied WebSockets per webview id, so one dashboard cannot exhaust the socket budget. */
+const socketCounts = new Map<string, number>();
+
+interface ProxyParams {
+  cap: string;
+  '*'?: string;
+}
+
+/** Serialize webview mutations: read-modify-write on a shared JSON file otherwise races. */
+let writeChain: Promise<unknown> = Promise.resolve();
+function withWebviews<T>(fn: (list: Webview[]) => Promise<T> | T): Promise<T> {
+  const next = writeChain.then(async () => {
+    const list = await readWebviews(configDir());
+    return fn(list);
+  });
+  // Keep the chain alive even if this link rejects, or every later write deadlocks.
+  writeChain = next.catch(() => undefined);
+  return next;
+}
+
+export function registerWebviewRoutes(app: FastifyInstance, ctx: EventPort): void {
+  registerCrudRoutes(app, ctx);
+  registerProxyRoutes(app);
+}
+
+// ───────────────────────────── CRUD ─────────────────────────────
+
+function registerCrudRoutes(app: FastifyInstance, ctx: EventPort): void {
+  app.get('/api/webviews', async (req) => {
+    const user = getAuthUser(req);
+    const all = await readWebviews(configDir());
+    const webviews = all.filter((w) => canAccessOwned(user, w.owner));
+    return { success: true, data: { webviews, maxLiveFrames: MAX_LIVE_WEBVIEW_FRAMES } };
+  });
+
+  app.post('/api/webviews', async (req, reply) => {
+    const input = parseBody(WebviewCreateSchema, req.body);
+    const owner = ownerFor(req);
+    const user = getAuthUser(req);
+
+    const created = await withWebviews(async (list) => {
+      const mine = list.filter((w) => canAccessOwned(user, w.owner));
+      if (mine.length >= MAX_WEBVIEWS) return null;
+
+      const webview: Webview = {
+        id: randomUUID(),
+        name: input.name,
+        url: input.url,
+        icon: input.icon,
+        // Proxy is the safe default: it is the only mode that works for a plain-HTTP
+        // dashboard on an HTTPS Codeman, which is the common case.
+        embedMode: input.embedMode ?? 'proxy',
+        trusted: input.trusted ?? false,
+        owner,
+        createdAt: Date.now(),
+      };
+      list.push(webview);
+      await writeWebviews(configDir(), list);
+      return webview;
+    });
+
+    if (!created) {
+      return reply
+        .code(400)
+        .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, `Webview limit reached (max ${MAX_WEBVIEWS})`));
+    }
+
+    ctx.broadcast(SseEvent.WebviewChanged, { action: 'created', id: created.id });
+    return { success: true, data: created };
+  });
+
+  app.patch<{ Params: { id: string } }>('/api/webviews/:id', async (req, reply) => {
+    const input = parseBody(WebviewUpdateSchema, req.body);
+    const user = getAuthUser(req);
+    const { id } = req.params;
+
+    const updated = await withWebviews(async (list) => {
+      const index = list.findIndex((w) => w.id === id);
+      if (index === -1) return 'not-found' as const;
+      if (!canAccessOwned(user, list[index].owner)) return 'forbidden' as const;
+
+      const next: Webview = { ...list[index], ...input };
+      list[index] = next;
+      await writeWebviews(configDir(), list);
+      return next;
+    });
+
+    if (updated === 'not-found') {
+      return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Webview not found'));
+    }
+    if (updated === 'forbidden') {
+      return reply.code(403).send(createErrorResponse(ApiErrorCode.FORBIDDEN, 'Not your webview'));
+    }
+
+    // Any edit invalidates the outstanding capability. Otherwise a token minted
+    // against the OLD url keeps proxying to it after the user repointed the tab.
+    webviewCapabilities.revokeWebview(id);
+    ctx.broadcast(SseEvent.WebviewChanged, { action: 'updated', id });
+    return { success: true, data: updated };
+  });
+
+  app.delete<{ Params: { id: string } }>('/api/webviews/:id', async (req, reply) => {
+    const user = getAuthUser(req);
+    const { id } = req.params;
+
+    const result = await withWebviews(async (list) => {
+      const index = list.findIndex((w) => w.id === id);
+      if (index === -1) return 'not-found' as const;
+      if (!canAccessOwned(user, list[index].owner)) return 'forbidden' as const;
+      list.splice(index, 1);
+      await writeWebviews(configDir(), list);
+      return 'deleted' as const;
+    });
+
+    if (result === 'not-found') {
+      return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Webview not found'));
+    }
+    if (result === 'forbidden') {
+      return reply.code(403).send(createErrorResponse(ApiErrorCode.FORBIDDEN, 'Not your webview'));
+    }
+
+    webviewCapabilities.revokeWebview(id);
+    socketCounts.delete(id);
+    ctx.broadcast(SseEvent.WebviewChanged, { action: 'deleted', id });
+    return { success: true, data: { id } };
+  });
+
+  /**
+   * Reachability + framing probe for the editor's "Test" button.
+   *
+   * Runs from the SERVER, which is the network position the proxy will use, so a
+   * green result here means the proxy will actually work. Never throws upstream
+   * failures at the caller: an unreachable dashboard is a normal answer, not a 500.
+   */
+  app.post('/api/webviews/probe', async (req) => {
+    const { url } = parseBody(WebviewProbeSchema, req.body);
+    return { success: true, data: await probeUrl(url) };
+  });
+
+  /**
+   * Mint the capability the iframe will load. Separate from GET /api/webviews so a
+   * capability exists only for dashboards actually opened, and so the TTL clock
+   * starts on open rather than on page load.
+   */
+  app.post<{ Params: { id: string } }>('/api/webviews/:id/open', async (req, reply) => {
+    const user = getAuthUser(req);
+    const { id } = req.params;
+
+    const webview = await withWebviews(async (list) => {
+      const index = list.findIndex((w) => w.id === id);
+      if (index === -1) return 'not-found' as const;
+      if (!canAccessOwned(user, list[index].owner)) return 'forbidden' as const;
+      list[index] = { ...list[index], lastOpenedAt: Date.now() };
+      await writeWebviews(configDir(), list);
+      return list[index];
+    });
+
+    if (webview === 'not-found') {
+      return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Webview not found'));
+    }
+    if (webview === 'forbidden') {
+      return reply.code(403).send(createErrorResponse(ApiErrorCode.FORBIDDEN, 'Not your webview'));
+    }
+
+    // Direct mode has no capability to mint: the iframe loads the real URL.
+    if (webview.embedMode === 'direct') {
+      const data: WebviewOpenData = { webview };
+      return { success: true, data };
+    }
+
+    const capability = webviewCapabilities.mint(webview.id, webview.owner);
+    const data: WebviewOpenData = { webview, embedUrl: proxyPrefixFor(capability) };
+    return { success: true, data };
+  });
+}
+
+async function probeUrl(url: string): Promise<WebviewProbe> {
+  const target = parseWebviewUrl(url);
+  if (!target) {
+    return {
+      reachable: false,
+      framable: false,
+      recommendedMode: 'proxy',
+      reason: 'Invalid URL',
+    };
+  }
+
+  try {
+    const response = await fetch(target.href, {
+      method: 'GET',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(WEBVIEW_PROBE_TIMEOUT_MS),
+    });
+    // The body is irrelevant to the probe; release the socket rather than leak it.
+    await response.body?.cancel().catch(() => undefined);
+
+    const xFrameOptions = response.headers.get('x-frame-options') ?? undefined;
+    const csp = response.headers.get('content-security-policy') ?? undefined;
+    const frameAncestors = extractFrameAncestors(csp);
+    const framable = isFramableCrossOrigin(xFrameOptions, csp);
+    const isHttp = target.protocol === 'http:';
+
+    // Direct embedding is only viable for an HTTPS target that permits framing:
+    // an HTTPS Codeman page cannot embed http:// at all (mixed content).
+    const recommendedMode = !isHttp && framable ? 'direct' : 'proxy';
+    const reason = isHttp
+      ? 'Plain HTTP: an HTTPS Codeman page cannot embed it directly, so it is proxied.'
+      : framable
+        ? 'Reachable and allows framing: can be embedded directly.'
+        : 'Reachable but refuses framing, so it is proxied.';
+
+    return {
+      reachable: true,
+      status: response.status,
+      xFrameOptions,
+      frameAncestors,
+      framable,
+      recommendedMode,
+      reason,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      reachable: false,
+      framable: false,
+      recommendedMode: 'proxy',
+      reason: `Server could not reach it: ${message}`,
+    };
+  }
+}
+
+// ───────────────────────────── Proxy ─────────────────────────────
+
+function registerProxyRoutes(app: FastifyInstance): void {
+  app.register(async (scope) => {
+    // Encapsulated to this plugin only. The proxy must relay request bodies
+    // BYTE-FOR-BYTE, so every parser is replaced with a pass-through that hands
+    // back the raw stream. Doing this on the root instance would break JSON
+    // routes and un-fix the text/plain CSRF hardening.
+    scope.removeAllContentTypeParsers();
+    scope.addContentTypeParser('*', (_req, payload, done) => done(null, payload));
+
+    // A single GET route serving both roles: `handler` for normal requests,
+    // `wsHandler` for upgrades. Registering them as two routes on one URL would
+    // collide.
+    scope.route<{ Params: ProxyParams }>({
+      method: 'GET',
+      url: `${WEBVIEW_PROXY_PREFIX}/:cap/*`,
+      handler: proxyHttp,
+      wsHandler: proxyWebSocket,
+    });
+
+    // HEAD is deliberately absent: Fastify's `exposeHeadRoutes` already derives a
+    // HEAD route from the GET above, and declaring it again is a startup error.
+    scope.route<{ Params: ProxyParams }>({
+      method: ['POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      url: `${WEBVIEW_PROXY_PREFIX}/:cap/*`,
+      handler: proxyHttp,
+    });
+
+    // `/webview/<cap>` with no trailing slash: redirect rather than serve, so the
+    // browser's notion of the base path ends in `/` and relative URLs in the
+    // dashboard's HTML resolve inside the prefix instead of one level above it.
+    scope.get<{ Params: { cap: string } }>(`${WEBVIEW_PROXY_PREFIX}/:cap`, (req, reply) => {
+      return reply.redirect(proxyPrefixFor(req.params.cap), 302);
+    });
+  });
+}
+
+/** Resolve a capability to its live webview record, or null. */
+async function lookupCapability(capability: string): Promise<Webview | null> {
+  const record = webviewCapabilities.resolve(capability);
+  if (!record) return null;
+  const list = await readWebviews(configDir());
+  const webview = list.find((w) => w.id === record.webviewId);
+  if (!webview) return null;
+  // The capability is bound to the identity that minted it; an ownership change
+  // on the record must not leave a stale token working.
+  if (webview.owner !== record.owner) return null;
+  return webview;
+}
+
+/**
+ * ⚠ Every exit path RETURNS `reply.send(...)`.
+ *
+ * This handler is `async`, and Fastify resolves an async handler's promise as the
+ * response. `reply.send(stream)` followed by a bare `return` resolves to
+ * `undefined` before the stream has been consumed, and Fastify then answers with
+ * an EMPTY body: HTML (a synchronously-set string payload) survives it, every
+ * streamed asset comes back zero-length. Returning the reply is what tells Fastify
+ * the response is already owned by this handler.
+ */
+function proxyHttp(req: FastifyRequest<{ Params: ProxyParams }>, reply: FastifyReply): Promise<FastifyReply> {
+  return proxyRequest(req, reply, req.params.cap, req.params['*'] ?? '');
+}
+
+/**
+ * Proxy one request to the dashboard behind `cap`, serving `wildcard` as the
+ * upstream path. Split out from the route handler so the 404 fallback (which has
+ * no route params) can reuse it.
+ */
+async function proxyRequest(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  cap: string,
+  wildcard: string
+): Promise<FastifyReply> {
+  const webview = await lookupCapability(cap);
+  if (!webview) {
+    return reply.code(403).type('text/plain').send('Forbidden: unknown or expired webview capability');
+  }
+
+  // CORS is required even though the URL is on this host: a sandboxed dashboard is
+  // opaque-origin, so its fetch/XHR are cross-origin requests. See
+  // buildProxyCorsHeaders.
+  const cors = buildProxyCorsHeaders(
+    typeof req.headers.origin === 'string' ? req.headers.origin : undefined,
+    typeof req.headers['access-control-request-headers'] === 'string'
+      ? req.headers['access-control-request-headers']
+      : undefined
+  );
+
+  // Answer the preflight here rather than relaying it: the dashboard has no reason
+  // to know it is being framed, and most would reject an unexpected `Origin: null`.
+  if (req.method === 'OPTIONS' && req.headers['access-control-request-method']) {
+    for (const [key, value] of Object.entries(cors)) reply.header(key, value);
+    return reply.code(204).send();
+  }
+
+  const queryStart = req.url.indexOf('?');
+  const search = queryStart === -1 ? '' : req.url.slice(queryStart);
+  const upstream = resolveUpstreamUrl(webview.url, wildcard, search);
+  if (!upstream) {
+    return reply.code(400).type('text/plain').send('Bad Request: path escapes the dashboard origin');
+  }
+
+  const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+  const headers = buildUpstreamRequestHeaders(req.headers, upstream, {
+    forwardCookies: webview.trusted,
+    sessionCookieName: AUTH_COOKIE_NAME,
+    refererPath: typeof req.headers.referer === 'string' ? stripProxyPrefix(req.headers.referer, cap) : undefined,
+  });
+
+  let response: Response;
+  try {
+    response = await fetch(upstream.href, {
+      method: req.method,
+      headers,
+      body: hasBody ? (req.body as Readable) : undefined,
+      // Required by undici whenever the body is a stream.
+      ...(hasBody ? { duplex: 'half' } : {}),
+      // Redirects are rewritten into the proxy prefix instead of followed, so the
+      // browser's URL stays inside the frame and relative assets keep resolving.
+      redirect: 'manual',
+      signal: AbortSignal.timeout(WEBVIEW_UPSTREAM_TIMEOUT_MS),
+    } as RequestInit);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return reply.code(502).type('text/plain').send(`Dashboard unreachable: ${message}`);
+  }
+
+  const secureContext = req.protocol === 'https';
+  const {
+    headers: outHeaders,
+    setCookie,
+    csp,
+  } = buildDownstreamResponseHeaders(
+    response.headers as unknown as Iterable<[string, string]>,
+    response.headers.getSetCookie(),
+    cap,
+    upstream,
+    secureContext
+  );
+
+  reply.code(response.status);
+  for (const [key, value] of Object.entries(outHeaders)) reply.header(key, value);
+  // After the upstream headers, so ours win: an upstream ACAO would name the
+  // dashboard's own origin, not the opaque origin this frame actually has.
+  for (const [key, value] of Object.entries(cors)) reply.header(key, value);
+  for (const cookie of setCookie) reply.header('set-cookie', cookie);
+
+  // registerSecurityHeaders already stamped Codeman's own `default-src 'self'`
+  // policy on this reply during onRequest. Left in place it breaks essentially
+  // every dashboard (inline scripts, CDN assets), so it is replaced by the
+  // upstream's own policy, or removed when the upstream had none.
+  if (csp) reply.header('content-security-policy', csp);
+  else reply.removeHeader('content-security-policy');
+
+  if (!response.body || req.method === 'HEAD') {
+    return reply.send();
+  }
+
+  const contentType = response.headers.get('content-type') ?? undefined;
+  const declaredLength = Number(response.headers.get('content-length') ?? '0');
+  const rewritable = isHtmlContentType(contentType) && declaredLength <= MAX_WEBVIEW_HTML_REWRITE_BYTES;
+
+  if (rewritable) {
+    // Buffer only HTML, only under the cap: `<base>` injection needs the whole
+    // document, and buffering an unbounded upstream body is a memory hazard.
+    const html = await response.text();
+    return reply.send(html.length <= MAX_WEBVIEW_HTML_REWRITE_BYTES ? rewriteHtml(html, cap) : html);
+  }
+
+  return reply.send(Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]));
+}
+
+/**
+ * Last-resort handler for a dashboard asset requested with a ROOT-ABSOLUTE URL.
+ *
+ * `<base href>` fixes relative URLs and the HTML rewrite fixes `src`/`href`/`action`
+ * attributes, but neither can reach a URL built at runtime: `fetch('/api/data')`,
+ * `import('/chunk.js')`, `url(/img.png)` inside a stylesheet. Those arrive at
+ * Codeman's root and 404.
+ *
+ * The `Referer` identifies which dashboard asked, so the request can be routed to
+ * the right upstream. Wiring it into the 404 handler rather than a catch-all route
+ * is what keeps it contained: every real Codeman route matches first, and this only
+ * ever sees requests that were going to fail anyway.
+ *
+ * @returns true when the request was handled (caller must not also reply).
+ */
+export async function tryWebviewRefererFallback(req: FastifyRequest, reply: FastifyReply): Promise<boolean> {
+  // Safe methods only. A write arriving here has already lost its raw body to the
+  // root instance's JSON parser, so it could not be relayed faithfully anyway.
+  if (req.method !== 'GET' && req.method !== 'HEAD') return false;
+
+  const capability = capabilityFromReferer(typeof req.headers.referer === 'string' ? req.headers.referer : undefined);
+  if (!capability) return false;
+  if (!webviewCapabilities.resolve(capability)) return false;
+
+  const path = req.url.split('?')[0].replace(/^\//, '');
+  await proxyRequest(req, reply, capability, path);
+  return true;
+}
+
+/** Turn a proxy-side Referer back into the upstream path it corresponds to. */
+function stripProxyPrefix(referer: string, capability: string): string | undefined {
+  try {
+    const url = new URL(referer);
+    const prefix = proxyPrefixFor(capability);
+    if (!url.pathname.startsWith(prefix)) return undefined;
+    return `/${url.pathname.slice(prefix.length)}${url.search}`;
+  } catch {
+    return undefined;
+  }
+}
+
+// ─────────────────────────── WebSocket ───────────────────────────
+
+/**
+ * Relay a WebSocket through to the dashboard.
+ *
+ * Live dashboards (Grafana, Home Assistant, Uptime Kuma) push over WebSocket, so
+ * without this leg they load but their realtime panels stay permanently empty.
+ *
+ * The upgrade is guarded on the capability, NOT on `Origin`: a sandboxed iframe is
+ * opaque-origin, so its upgrade arrives with `Origin: null`. The host allowlist
+ * still applies (it runs in the global onRequest hook), so DNS-rebinding
+ * protection is unaffected.
+ */
+function proxyWebSocket(socket: WebSocket, req: FastifyRequest<{ Params: ProxyParams }>): void {
+  const { cap } = req.params;
+
+  void (async () => {
+    const webview = await lookupCapability(cap);
+    if (!webview) {
+      socket.close(4003, 'Forbidden');
+      return;
+    }
+
+    const live = socketCounts.get(webview.id) ?? 0;
+    if (live >= MAX_WEBVIEW_SOCKETS) {
+      socket.close(4008, 'Too many connections');
+      return;
+    }
+
+    const wildcard = req.params['*'] ?? '';
+    const queryStart = req.url.indexOf('?');
+    const search = queryStart === -1 ? '' : req.url.slice(queryStart);
+    const upstream = resolveUpstreamUrl(webview.url, wildcard, search);
+    if (!upstream) {
+      socket.close(4003, 'Forbidden');
+      return;
+    }
+
+    socketCounts.set(webview.id, live + 1);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      const count = socketCounts.get(webview.id) ?? 1;
+      if (count <= 1) socketCounts.delete(webview.id);
+      else socketCounts.set(webview.id, count - 1);
+    };
+
+    const protocols = req.headers['sec-websocket-protocol'];
+    const upstreamSocket = new WsClient(
+      upstreamWebSocketUrl(upstream),
+      protocols ? String(protocols).split(/,\s*/) : [],
+      {
+        headers: {
+          origin: upstream.origin,
+          ...(webview.trusted && req.headers.cookie ? { cookie: String(req.headers.cookie) } : {}),
+        },
+        handshakeTimeout: WEBVIEW_UPSTREAM_TIMEOUT_MS,
+      }
+    );
+
+    // Buffer anything the browser sends before the upstream handshake completes,
+    // rather than dropping it: a client that sends a subscribe frame immediately
+    // would otherwise sit connected and silent forever.
+    const pending: Array<Buffer | string> = [];
+    let upstreamOpen = false;
+
+    upstreamSocket.on('open', () => {
+      upstreamOpen = true;
+      for (const message of pending) upstreamSocket.send(message);
+      pending.length = 0;
+    });
+
+    socket.on('message', (data: Buffer, isBinary: boolean) => {
+      const payload = isBinary ? data : data.toString();
+      if (upstreamOpen) upstreamSocket.send(payload);
+      else if (pending.length < 64) pending.push(payload);
+    });
+
+    upstreamSocket.on('message', (data: Buffer, isBinary: boolean) => {
+      if (socket.readyState === socket.OPEN) socket.send(isBinary ? data : data.toString());
+    });
+
+    // Paired close in both directions, so neither side is left half-open.
+    const closeBoth = (code?: number, reason?: string) => {
+      release();
+      // Codes outside 3000-4999 (and 1000/1001) are not valid to send onward.
+      const safeCode = code && code >= 3000 && code <= 4999 ? code : 1000;
+      if (socket.readyState === socket.OPEN) socket.close(safeCode, reason);
+      if (upstreamSocket.readyState === WsClient.OPEN || upstreamSocket.readyState === WsClient.CONNECTING) {
+        upstreamSocket.close(safeCode, reason);
+      }
+    };
+
+    socket.on('close', (code: number, reason: Buffer) => closeBoth(code, reason?.toString()));
+    upstreamSocket.on('close', (code: number, reason: Buffer) => closeBoth(code, reason?.toString()));
+    socket.on('error', () => closeBoth());
+    upstreamSocket.on('error', () => {
+      release();
+      if (socket.readyState === socket.OPEN) socket.close(1011, 'Upstream error');
+    });
+  })();
+}

src/web/schemas.ts

@@ -9,6 +9,7 @@
 
 import { z } from 'zod';
 import { SAFE_PATH_PATTERN, isSafePushEndpoint } from '../utils/index.js';
+import { isValidWebviewUrl } from './webview-proxy.js';
 import {
   MAX_TERMINAL_BUFFER_BYTES,
   MAX_TERMINAL_SCROLLBACK_LINES,
@@ -1184,3 +1185,42 @@ export const SearchQuerySchema = z.object({
     ),
   limit: z.coerce.number().int().min(1).max(60).optional(),
 });
+
+// ========== Web Tabs (dashboard URLs) ==========
+
+/**
+ * A dashboard URL. `isValidWebviewUrl` rejects anything that is not plain
+ * http/https, anything carrying embedded credentials, and anything without a
+ * hostname. See `src/web/webview-proxy.ts` for why each of those matters.
+ */
+const webviewUrlSchema = z
+  .string()
+  .trim()
+  .min(1, 'URL is required')
+  .max(2000, 'URL too long (max 2000 chars)')
+  .refine(isValidWebviewUrl, {
+    message: 'Invalid URL: must be http(s), with a hostname and no embedded credentials',
+  });
+
+const WebviewBaseSchema = z.object({
+  name: z.string().trim().min(1, 'Name is required').max(60, 'Name too long (max 60 chars)'),
+  url: webviewUrlSchema,
+  /** A single glyph shown on the tab. Bounded generously: one emoji can be several code units. */
+  icon: z.string().max(8).optional(),
+  embedMode: z.enum(['proxy', 'direct']).optional(),
+  /**
+   * Opt out of the iframe sandbox. Defaults to false: a proxied page is served
+   * from Codeman's own origin, so `allow-same-origin` would let it read this page
+   * and call the API that spawns agents.
+   */
+  trusted: z.boolean().optional(),
+});
+
+/** POST /api/webviews */
+export const WebviewCreateSchema = WebviewBaseSchema;
+
+/** PATCH /api/webviews/:id, partial update. */
+export const WebviewUpdateSchema = WebviewBaseSchema.partial();
+
+/** POST /api/webviews/probe: reachability + framing check for the editor's Test button. */
+export const WebviewProbeSchema = z.object({ url: webviewUrlSchema });

src/web/server.ts

@@ -160,6 +160,8 @@ import {
   registerMeRoutes,
   registerAdminRoutes,
   registerWsRoutes,
+  registerWebviewRoutes,
+  tryWebviewRefererFallback,
 } from './routes/index.js';
 import { CronService } from '../cron/cron-service.js';
 
@@ -851,13 +853,17 @@ export class WebServer extends EventEmitter {
     // Stable-contract 404 for unknown /api routes — without this, Fastify's
     // default not-found payload {message,error,statusCode} would be wrapped by
     // the envelope hook into a contradictory HTTP 404 {success:true,...}.
-    this.app.setNotFoundHandler((req, reply) => {
+    this.app.setNotFoundHandler(async (req, reply) => {
       const notFound = `Route ${req.method}:${req.url} not found`;
       if (req.url.startsWith('/api')) {
-        reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, notFound));
-        return;
+        return reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, notFound));
       }
-      reply.code(404).send({ message: notFound, error: 'Not Found', statusCode: 404 });
+      // A web-tab dashboard asking for a root-absolute asset (`fetch('/api/data')`,
+      // `import('/chunk.js')`) lands here, because `<base href>` cannot rewrite a URL
+      // built at runtime. Its Referer says which dashboard to relay to. Deliberately
+      // placed on the 404 path so every real Codeman route still wins.
+      if (await tryWebviewRefererFallback(req, reply)) return reply;
+      return reply.code(404).send({ message: notFound, error: 'Not Found', statusCode: 404 });
     });
 
     // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them.
@@ -925,6 +931,7 @@ export class WebServer extends EventEmitter {
     registerMeRoutes(this.app, ctx);
     registerAdminRoutes(this.app, ctx);
     registerOrchestratorRoutes(this.app, ctx);
+    registerWebviewRoutes(this.app, ctx);
 
     // Cron: build the service from the same context, recompute
     // due times for any persisted jobs, then expose it to its routes.

src/web/sse-events.ts

@@ -5,7 +5,7 @@
  * and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
  * Both files MUST be kept in sync.
  *
- * 148 event constants organized by category:
+ * 149 event constants organized by category:
  * - **Core** (1): init
  * - **Session lifecycle** (23): created, updated, deleted, terminal, idle, working, ...
  * - **Session: Ralph** (6): ralphLoopUpdate, todoUpdate, completionDetected, ...
@@ -30,6 +30,7 @@
  * - **Cases** (4): created, linked, deleted, order-changed
  * - **Docker cases** (8): exportComplete/Failed, importComplete, imageBuild*, containerRecreated
  * - **Multi-user** (3): admin:usersChanged, auth:passwordChangeRequired, session:orderChanged
+ * - **Web tabs** (1): webview:changed
  *
  * Naming convention: `domain:action` (e.g., `session:created`, `respawn:stateChanged`)
  *
@@ -413,6 +414,11 @@ export const AuthPasswordChangeRequired = 'auth:passwordChangeRequired' as const
 /** Global session tab order changed (synced across devices). COD-131. */
 export const SessionOrderChanged = 'session:orderChanged' as const;
 
+/** A saved web tab (dashboard URL) was created, updated or deleted.
+ *  Payload: `{ action: 'created' | 'updated' | 'deleted', id }`. The client
+ *  re-fetches the list rather than patching from the payload. */
+export const WebviewChanged = 'webview:changed' as const;
+
 // ─── Namespace Re-export ─────────────────────────────────────────────────────
 
 /**
@@ -615,4 +621,7 @@ export const SseEvent = {
 
   // Session order (global tab order sync)
   SessionOrderChanged,
+
+  // Web tabs (dashboard URLs)
+  WebviewChanged,
 } as const;

src/web/webview-proxy.ts

@@ -0,0 +1,507 @@
+/**
+ * @fileoverview Pure helpers for the web-tab reverse proxy. No I/O, no Fastify.
+ *
+ * The proxy exists because an iframe pointing straight at a dashboard cannot work
+ * in the deployment that matters: prod serves HTTPS (behind `tailscale serve`), so
+ * a plain-HTTP dashboard is hard-blocked as mixed content; many dashboards also
+ * refuse framing outright via `X-Frame-Options` / `frame-ancestors`; and Codeman's
+ * own CSP (`default-src 'self'`) blocks cross-origin frames anyway. Serving the
+ * dashboard through Codeman's own origin dissolves all three at once, and keeps
+ * the production CSP byte-for-byte unchanged because `/webview/...` is `'self'`.
+ *
+ * ## Origin-scoped, not path-scoped
+ *
+ * `/webview/<cap>/x/y` always maps to `<upstream origin>/x/y`, never to
+ * `<upstream origin><saved path>/x/y`. Dashboards reference assets with
+ * root-absolute paths (`/public/build/app.js`), so origin-scoping is the only
+ * mapping under which those resolve. The saved URL's own path+query is used for
+ * exactly one thing: what `/webview/<cap>/` itself serves (the landing page).
+ *
+ * ## What gets rewritten, and why each one is load-bearing
+ *
+ * - `x-frame-options` / CSP `frame-ancestors`: dropped, else the browser refuses
+ *   to render the frame. This is the whole point of the proxy.
+ * - `content-encoding` / `content-length`: dropped, because undici's `fetch`
+ *   already decoded the body. Forwarding them makes the browser try to gunzip
+ *   plaintext.
+ * - `authorization` + the `codeman_session` cookie: stripped on the way OUT. In
+ *   trusted mode the iframe is same-origin, so the browser attaches Codeman's own
+ *   Basic-auth header and session cookie to every proxied request. Forwarding
+ *   those would hand CODEMAN_PASSWORD to the dashboard.
+ * - `Location` and `Set-Cookie`: remapped into the proxy path, else a redirect or
+ *   a login cookie escapes the prefix and lands on Codeman's root.
+ * - `<base href>` + root-absolute attribute rewriting: relative and `/`-rooted
+ *   URLs in the HTML resolve back through the proxy instead of hitting Codeman.
+ *
+ * No `X-Forwarded-*` is sent deliberately: apps that honor it generate absolute
+ * URLs against Codeman's root, which would bypass the `/webview/<cap>/` prefix
+ * that everything else here works to preserve.
+ */
+
+import { WEBVIEW_PROXY_PREFIX } from '../config/webview-limits.js';
+
+/** Headers that are per-connection and must never be relayed in either direction. */
+const HOP_BY_HOP = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+/**
+ * Request headers dropped on the way to the upstream. `authorization` and `cookie`
+ * carry Codeman's own credentials on a same-origin (trusted) frame; `host`,
+ * `content-length` and `accept-encoding` are recomputed by undici.
+ */
+const DROP_REQUEST_HEADERS = new Set([
+  ...HOP_BY_HOP,
+  'host',
+  'content-length',
+  'accept-encoding',
+  'authorization',
+  'cookie',
+  'origin',
+  'referer',
+  'x-codeman-hook-secret',
+]);
+
+/** Response headers dropped on the way back to the browser. */
+const DROP_RESPONSE_HEADERS = new Set([
+  ...HOP_BY_HOP,
+  'content-encoding',
+  'content-length',
+  'x-frame-options',
+  'content-security-policy-report-only',
+  // Cross-origin isolation headers describe the UPSTREAM's origin policy; applied
+  // to a frame on Codeman's origin they only produce blocked-resource surprises.
+  'cross-origin-opener-policy',
+  'cross-origin-embedder-policy',
+  'cross-origin-resource-policy',
+  'set-cookie',
+  'location',
+  'content-security-policy',
+  // The upstream's CORS answer describes ITS origin; the frame asking is
+  // opaque-origin on ours, so ours must replace it (see buildProxyCorsHeaders).
+  'access-control-allow-origin',
+  'access-control-allow-credentials',
+  'access-control-allow-methods',
+  'access-control-allow-headers',
+  'access-control-expose-headers',
+  'access-control-max-age',
+]);
+
+/** The same-origin path prefix an iframe loads for a given capability. */
+export function proxyPrefixFor(capability: string): string {
+  return `${WEBVIEW_PROXY_PREFIX}/${capability}/`;
+}
+
+/**
+ * Parse and validate a user-supplied dashboard URL.
+ *
+ * Rejects everything that is not plain `http:`/`https:`, anything carrying
+ * embedded credentials (they would be silently forwarded and logged), and
+ * anything without a hostname. Returns the normalized `URL` or null.
+ */
+export function parseWebviewUrl(raw: string): URL | null {
+  if (typeof raw !== 'string' || raw.trim() === '') return null;
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.username !== '' || url.password !== '') return null;
+  if (!url.hostname) return null;
+  return url;
+}
+
+/** Convenience predicate for Zod refinements. */
+export function isValidWebviewUrl(raw: string): boolean {
+  return parseWebviewUrl(raw) !== null;
+}
+
+/**
+ * Map a proxy request path to its upstream URL.
+ *
+ * `wildcard` is Fastify's `*` param: the path after `/webview/<cap>/`, without a
+ * leading slash. An empty wildcard means the landing page, which is the saved
+ * URL's own path and query.
+ *
+ * Returns null when the result would escape the upstream origin (a `..` chain, a
+ * protocol-relative `//evil.com` wildcard, or an absolute URL smuggled into the
+ * path). That check is what keeps this from being an open proxy.
+ */
+export function resolveUpstreamUrl(savedUrl: string, wildcard: string, search: string): URL | null {
+  const base = parseWebviewUrl(savedUrl);
+  if (!base) return null;
+
+  if (wildcard === '' || wildcard === '/') {
+    const landing = new URL(base.pathname + (search || base.search), base.origin);
+    return landing.origin === base.origin ? landing : null;
+  }
+
+  // A wildcard starting with `//` would parse as protocol-relative and jump host.
+  const path = wildcard.startsWith('/') ? wildcard : `/${wildcard}`;
+  if (path.startsWith('//')) return null;
+
+  let target: URL;
+  try {
+    target = new URL(path + (search || ''), base.origin);
+  } catch {
+    return null;
+  }
+  return target.origin === base.origin ? target : null;
+}
+
+/** Extract the capability from a `/webview/<cap>/...` pathname, or null. */
+export function capabilityFromProxyPath(pathname: string): string | null {
+  if (typeof pathname !== 'string') return null;
+  const prefix = `${WEBVIEW_PROXY_PREFIX}/`;
+  if (!pathname.startsWith(prefix)) return null;
+  const rest = pathname.slice(prefix.length);
+  const slash = rest.indexOf('/');
+  const cap = slash === -1 ? rest : rest.slice(0, slash);
+  return /^[A-Za-z0-9_-]{16,128}$/.test(cap) ? cap : null;
+}
+
+/**
+ * Extract the capability a `Referer` belongs to. Backs the 404 fallback that
+ * catches root-absolute asset requests (`/static/app.js`) which `<base>` cannot fix.
+ */
+export function capabilityFromReferer(referer: string | undefined): string | null {
+  if (!referer) return null;
+  try {
+    return capabilityFromProxyPath(new URL(referer).pathname);
+  } catch {
+    return null;
+  }
+}
+
+/** Remove the `frame-ancestors` directive from a CSP, preserving the rest. */
+export function stripFrameAncestors(csp: string): string {
+  return csp
+    .split(';')
+    .map((d) => d.trim())
+    .filter((d) => d !== '' && !/^frame-ancestors\b/i.test(d))
+    .join('; ');
+}
+
+/** The `frame-ancestors` directive value from a CSP, or undefined. */
+export function extractFrameAncestors(csp: string | undefined): string | undefined {
+  if (!csp) return undefined;
+  for (const directive of csp.split(';')) {
+    const trimmed = directive.trim();
+    if (/^frame-ancestors\b/i.test(trimmed)) {
+      return trimmed.slice('frame-ancestors'.length).trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether a target permits being framed by a different origin, judged from its
+ * `X-Frame-Options` and CSP. Used only to recommend proxy vs direct mode in the
+ * editor; the proxy path works either way.
+ */
+export function isFramableCrossOrigin(xFrameOptions: string | undefined, csp: string | undefined): boolean {
+  const xfo = xFrameOptions?.trim().toLowerCase();
+  if (xfo === 'deny' || xfo === 'sameorigin') return false;
+  const ancestors = extractFrameAncestors(csp)?.toLowerCase();
+  if (ancestors === undefined) return true;
+  if (ancestors.includes("'none'")) return false;
+  // 'self' alone means same-origin only, which a cross-origin embed is not.
+  if (ancestors === "'self'") return false;
+  return ancestors.includes('*') || ancestors.includes('http');
+}
+
+/**
+ * Rewrite an upstream `Location` into the proxy path.
+ *
+ * Same-origin redirects (relative or absolute) are remapped so the browser stays
+ * inside the frame. Cross-origin redirects are returned unchanged rather than
+ * proxied: relaying them would turn this into an open proxy for any host the
+ * upstream chooses to name.
+ */
+export function rewriteLocation(location: string, requestUrl: URL, capability: string): string {
+  let resolved: URL;
+  try {
+    resolved = new URL(location, requestUrl);
+  } catch {
+    return location;
+  }
+  if (resolved.origin !== requestUrl.origin) return location;
+  const suffix = resolved.pathname.replace(/^\//, '');
+  return `${proxyPrefixFor(capability)}${suffix}${resolved.search}${resolved.hash}`;
+}
+
+/**
+ * Rewrite an upstream `Set-Cookie` so it applies to the proxy path only.
+ *
+ * `Domain` is dropped (the cookie now belongs to Codeman's host), `Path` is
+ * rebased onto the proxy prefix so two dashboards cannot collide on a shared
+ * cookie name, and `Secure` is dropped when Codeman itself is serving plain HTTP
+ * in dev, where a Secure cookie would simply be discarded.
+ */
+export function rewriteSetCookie(cookie: string, capability: string, secureContext: boolean): string {
+  const parts = cookie.split(';');
+  const out: string[] = [parts[0]];
+  let sawPath = false;
+
+  for (const raw of parts.slice(1)) {
+    const attr = raw.trim();
+    const lower = attr.toLowerCase();
+    if (lower.startsWith('domain=')) continue;
+    if (lower === 'secure' && !secureContext) continue;
+    if (lower.startsWith('path=')) {
+      sawPath = true;
+      const value = attr.slice('path='.length);
+      const suffix = value.replace(/^\//, '');
+      out.push(`Path=${proxyPrefixFor(capability)}${suffix}`);
+      continue;
+    }
+    out.push(attr);
+  }
+
+  if (!sawPath) out.push(`Path=${proxyPrefixFor(capability)}`);
+  return out.join('; ');
+}
+
+/** Drop named cookies from a `Cookie` request header, returning undefined if none remain. */
+export function filterCookieHeader(cookie: string | undefined, drop: string[]): string | undefined {
+  if (!cookie) return undefined;
+  const dropSet = new Set(drop.map((n) => n.toLowerCase()));
+  const kept = cookie
+    .split(';')
+    .map((c) => c.trim())
+    .filter((c) => c !== '' && !dropSet.has(c.slice(0, c.indexOf('=')).trim().toLowerCase()));
+  return kept.length > 0 ? kept.join('; ') : undefined;
+}
+
+/** Build the header set sent upstream, from the browser's request headers. */
+export function buildUpstreamRequestHeaders(
+  incoming: Record<string, string | string[] | undefined>,
+  upstream: URL,
+  opts: { forwardCookies: boolean; sessionCookieName: string; refererPath?: string }
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(incoming)) {
+    const lower = key.toLowerCase();
+    if (DROP_REQUEST_HEADERS.has(lower)) continue;
+    if (value === undefined) continue;
+    headers[lower] = Array.isArray(value) ? value.join(', ') : value;
+  }
+
+  if (opts.forwardCookies) {
+    const raw = incoming['cookie'];
+    const cookie = filterCookieHeader(Array.isArray(raw) ? raw.join('; ') : raw, [opts.sessionCookieName]);
+    if (cookie) headers['cookie'] = cookie;
+  }
+
+  // Present as if the browser were talking to the dashboard directly. Apps that
+  // check Origin on writes (CSRF defenses) need this to match their own origin.
+  headers['origin'] = upstream.origin;
+  headers['referer'] = opts.refererPath ? new URL(opts.refererPath, upstream.origin).href : upstream.href;
+
+  return headers;
+}
+
+/**
+ * Build the response headers sent to the browser.
+ *
+ * Also returns the CSP to apply: the upstream's, minus `frame-ancestors`. Callers
+ * MUST set (or explicitly clear) this, because `registerSecurityHeaders` has
+ * already stamped Codeman's own `default-src 'self'` policy onto the reply, and
+ * that policy would break virtually every dashboard.
+ */
+export function buildDownstreamResponseHeaders(
+  upstreamHeaders: Iterable<[string, string]>,
+  /**
+   * Upstream `Set-Cookie` values, already separated. Passed in rather than read
+   * from `upstreamHeaders` because iterating a `Headers` object JOINS duplicate
+   * set-cookie values into one comma-separated string, which cannot be split back
+   * apart reliably (Expires dates contain commas). Callers use
+   * `response.headers.getSetCookie()`.
+   */
+  setCookies: string[],
+  capability: string,
+  requestUrl: URL,
+  secureContext: boolean
+): { headers: Record<string, string>; setCookie: string[]; csp: string | null } {
+  const headers: Record<string, string> = {};
+  let csp: string | null = null;
+
+  for (const [key, value] of upstreamHeaders) {
+    const lower = key.toLowerCase();
+    if (lower === 'content-security-policy') {
+      const stripped = stripFrameAncestors(value);
+      csp = stripped === '' ? null : stripped;
+      continue;
+    }
+    if (lower === 'location') {
+      headers['location'] = rewriteLocation(value, requestUrl, capability);
+      continue;
+    }
+    if (DROP_RESPONSE_HEADERS.has(lower)) continue;
+    headers[lower] = value;
+  }
+
+  const setCookie = setCookies.map((cookie) => rewriteSetCookie(cookie, capability, secureContext));
+
+  return { headers, setCookie, csp };
+}
+
+/**
+ * A tiny script injected at the top of every proxied document, rewriting
+ * ROOT-ABSOLUTE URLs built at runtime so they stay inside the proxy prefix.
+ *
+ * `<base href>` only governs URLs the HTML parser resolves. A dashboard that calls
+ * `fetch('/api/data')` bypasses it entirely and the request lands on Codeman's own
+ * root, where it 404s. That is not a rare shape: it is how most dashboards talk to
+ * their own backend, and it presents as the dashboard's own "Failed to fetch".
+ *
+ * The `Referer`-keyed 404 fallback catches some of these, but deliberately NOT
+ * paths under `/api`, `/ws` or `/q` (widening it there would let a request-supplied
+ * header skip auth on Codeman's own API). Rewriting inside the iframe removes the
+ * whole class instead of trading security for it: the page never emits a
+ * root-absolute request in the first place.
+ *
+ * Runs before any page script because it is injected immediately after `<base>`.
+ * Only same-origin, non-prefixed, root-absolute URLs are touched; relative URLs
+ * (already handled by `<base>`) and cross-origin URLs are passed through.
+ */
+export function runtimeUrlShim(prefix: string): string {
+  // Kept dependency-free and defensive: it runs inside a page we do not control,
+  // and a throw here would break the dashboard rather than fix it.
+  return `<script>(function(){try{
+var P=${JSON.stringify(prefix)};
+function rw(u){
+  try{
+    if(u==null)return u;
+    if(typeof u!=='string'){
+      if(typeof URL!=='undefined'&&u instanceof URL)return rw(u.href);
+      return u;
+    }
+    if(u.indexOf(P)===0)return u;
+    if(u.charAt(0)==='/'&&u.charAt(1)!=='/')return P+u.slice(1);
+    if(/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(u)||u.indexOf('//')===0){
+      var a=new URL(u,location.href);
+      if(a.host===location.host&&a.pathname.indexOf(P)!==0){
+        a.pathname=P+a.pathname.replace(/^\\//,'');
+        return a.href;
+      }
+    }
+    return u;
+  }catch(e){return u;}
+}
+var of=window.fetch;
+if(of)window.fetch=function(i,o){
+  try{
+    if(typeof Request!=='undefined'&&i instanceof Request)return of.call(this,new Request(rw(i.url),i),o);
+    return of.call(this,rw(i),o);
+  }catch(e){return of.call(this,i,o);}
+};
+if(window.XMLHttpRequest&&XMLHttpRequest.prototype.open){
+  var oo=XMLHttpRequest.prototype.open;
+  XMLHttpRequest.prototype.open=function(m,u){
+    var a=[].slice.call(arguments);a[1]=rw(u);return oo.apply(this,a);
+  };
+}
+['WebSocket','EventSource'].forEach(function(k){
+  var C=window[k];if(!C)return;
+  function W(u,p){return p===undefined?new C(rw(u)):new C(rw(u),p);}
+  W.prototype=C.prototype;
+  ['CONNECTING','OPEN','CLOSING','CLOSED'].forEach(function(s){if(s in C)W[s]=C[s];});
+  window[k]=W;
+});
+}catch(e){}})();</script>`;
+}
+
+/**
+ * Inject `<base href="/webview/<cap>/">` plus the runtime URL shim, and rebase
+ * root-absolute `src`/`href`/`action` attributes, which `<base>` alone does not
+ * affect.
+ *
+ * Three layers, because no single one is sufficient: `<base>` for parser-resolved
+ * relative URLs, attribute rewriting for root-absolute markup, and the shim for
+ * URLs built at runtime.
+ */
+export function rewriteHtml(html: string, capability: string): string {
+  const prefix = proxyPrefixFor(capability);
+
+  // Fresh regexes per call: module-level /g patterns carry `lastIndex` between calls.
+  const rebased = html
+    .replace(/(\s(?:src|href|action)\s*=\s*")\/(?!\/)/gi, `$1${prefix}`)
+    .replace(/(\s(?:src|href|action)\s*=\s*')\/(?!\/)/gi, `$1${prefix}`);
+
+  // A page that ships its own <base> keeps it (overriding it would break the
+  // author's intent), but it STILL needs the shim, which is the layer that
+  // catches runtime-built URLs. So only the base tag is conditional.
+  const injected = (/<base\b/i.test(rebased) ? '' : `<base href="${prefix}">`) + runtimeUrlShim(prefix);
+
+  const headMatch = /<head\b[^>]*>/i.exec(rebased);
+  if (headMatch) {
+    const at = headMatch.index + headMatch[0].length;
+    return rebased.slice(0, at) + injected + rebased.slice(at);
+  }
+  const htmlMatch = /<html\b[^>]*>/i.exec(rebased);
+  if (htmlMatch) {
+    const at = htmlMatch.index + htmlMatch[0].length;
+    return rebased.slice(0, at) + injected + rebased.slice(at);
+  }
+  return injected + rebased;
+}
+
+/**
+ * CORS headers for a proxied response.
+ *
+ * Non-obvious but load-bearing: a SANDBOXED iframe (no `allow-same-origin`) runs
+ * in an OPAQUE origin, so every `fetch`/XHR it makes is a cross-origin request even
+ * though the URL is on this very host, and the browser requires CORS headers to
+ * hand back the response. Without this, a dashboard renders fine (script/css/img
+ * loads are not CORS-checked) while every one of its API calls fails with an opaque
+ * `net::ERR_FAILED` and the page shows its own "failed to load" state. `curl`
+ * cannot reproduce it, because curl does not enforce CORS.
+ *
+ * The origin is echoed rather than `*` so credentialed requests still work in
+ * trusted mode. `null` (the opaque-origin case) is echoed as-is, but WITHOUT
+ * `allow-credentials`, which browsers reject in combination.
+ *
+ * This grants nothing extra: the URL is already gated by the capability, and only
+ * a document that was handed the capability can construct these requests.
+ */
+export function buildProxyCorsHeaders(origin: string | undefined, requestedHeaders?: string): Record<string, string> {
+  if (!origin) return {};
+  const headers: Record<string, string> = {
+    'access-control-allow-origin': origin,
+    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS',
+    'access-control-allow-headers': requestedHeaders && requestedHeaders.trim() !== '' ? requestedHeaders : '*',
+    'access-control-expose-headers': '*',
+    'access-control-max-age': '600',
+    vary: 'Origin',
+  };
+  // `Access-Control-Allow-Credentials: true` alongside a `null` origin is rejected
+  // by browsers; a sandboxed frame sends no credentials anyway.
+  if (origin !== 'null' && origin !== '*') headers['access-control-allow-credentials'] = 'true';
+  return headers;
+}
+
+/** Whether a content-type identifies HTML worth rewriting. */
+export function isHtmlContentType(contentType: string | undefined): boolean {
+  if (!contentType) return false;
+  const type = contentType.split(';')[0].trim().toLowerCase();
+  return type === 'text/html' || type === 'application/xhtml+xml';
+}
+
+/** Map an upstream http(s) URL to its ws(s) equivalent for the WebSocket leg. */
+export function upstreamWebSocketUrl(target: URL): string {
+  const ws = new URL(target.href);
+  ws.protocol = ws.protocol === 'https:' ? 'wss:' : 'ws:';
+  return ws.href;
+}

src/webview-capabilities.ts

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Capability tokens for the web-tab proxy.
+ *
+ * The proxy cannot authenticate on Codeman's session cookie. A sandboxed iframe
+ * (no `allow-same-origin`) runs in an OPAQUE origin, so every request it makes is
+ * cross-site: the `SameSite=lax` `codeman_session` cookie is not sent, and its
+ * non-GET requests and WebSocket upgrades arrive with `Origin: null`, which the
+ * host guard rejects by design.
+ *
+ * So `/webview/:cap/*` authenticates on an unguessable capability minted by an
+ * already-authenticated `POST /api/webviews/:id/open`. Properties that make this
+ * safe to exempt from the cookie/Origin checks:
+ *
+ * - 128 bits of `randomBytes` entropy, base64url, never derived from anything.
+ * - Held in memory only. A restart invalidates every outstanding capability.
+ * - Rolling TTL: refreshed on use, expired after inactivity.
+ * - Bound to the minting user, so multi-user ownership survives the exemption.
+ * - Grants exactly one thing: relaying bytes to that one saved URL. It reaches no
+ *   session, no file, no API surface.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { StaleExpirationMap } from './utils/index.js';
+import { MAX_WEBVIEW_CAPABILITIES, WEBVIEW_CAPABILITY_TTL_MS } from './config/webview-limits.js';
+
+export interface WebviewCapabilityRecord {
+  webviewId: string;
+  /** Username that minted it (multi-user); undefined in single-user mode. */
+  owner?: string;
+  createdAt: number;
+}
+
+export class WebviewCapabilityStore {
+  private readonly capabilities: StaleExpirationMap<string, WebviewCapabilityRecord>;
+  /** Reverse index so re-opening a webview reuses its capability instead of leaking one per click. */
+  private readonly byWebview = new Map<string, string>();
+
+  constructor(ttlMs: number = WEBVIEW_CAPABILITY_TTL_MS) {
+    this.capabilities = new StaleExpirationMap<string, WebviewCapabilityRecord>({
+      ttlMs,
+      refreshOnGet: true,
+      onExpire: (_token, record) => {
+        const current = this.byWebview.get(record.webviewId);
+        if (current !== undefined) this.byWebview.delete(record.webviewId);
+      },
+    });
+  }
+
+  /** Mint (or reuse) a capability for a webview. Returns the token. */
+  mint(webviewId: string, owner?: string): string {
+    const existing = this.byWebview.get(webviewId);
+    if (existing) {
+      const record = this.capabilities.get(existing);
+      // Reuse only while the record is live AND still belongs to the same identity.
+      if (record && record.owner === owner) return existing;
+      this.capabilities.delete(existing);
+      this.byWebview.delete(webviewId);
+    }
+
+    // Bound growth: a client that never reuses tokens must not grow this forever.
+    if (this.capabilities.size >= MAX_WEBVIEW_CAPABILITIES) this.capabilities.cleanup();
+
+    const token = randomBytes(24).toString('base64url');
+    this.capabilities.set(token, { webviewId, owner, createdAt: Date.now() });
+    this.byWebview.set(webviewId, token);
+    return token;
+  }
+
+  /** Resolve a capability, refreshing its TTL. Returns undefined when unknown or expired. */
+  resolve(token: string): WebviewCapabilityRecord | undefined {
+    if (!token) return undefined;
+    return this.capabilities.get(token);
+  }
+
+  /** Revoke every capability for a webview (called on delete/edit). */
+  revokeWebview(webviewId: string): void {
+    const token = this.byWebview.get(webviewId);
+    if (token) {
+      this.capabilities.delete(token);
+      this.byWebview.delete(webviewId);
+    }
+  }
+
+  /** Revoke every capability minted by a user (called on logout / user deletion). */
+  revokeOwner(owner: string): void {
+    for (const [webviewId, token] of [...this.byWebview]) {
+      const record = this.capabilities.peek(token);
+      if (record?.owner === owner) {
+        this.capabilities.delete(token);
+        this.byWebview.delete(webviewId);
+      }
+    }
+  }
+
+  get size(): number {
+    return this.capabilities.size;
+  }
+
+  dispose(): void {
+    this.capabilities.dispose();
+    this.byWebview.clear();
+  }
+}
+
+/**
+ * Process-wide capability store.
+ *
+ * A singleton rather than an injected dependency because two unrelated layers must
+ * agree on it: the proxy routes that mint and consume capabilities, and the auth
+ * middleware, which has to recognize a valid capability to know that a
+ * `/webview/...` request is legitimately exempt from the cookie and Origin checks.
+ * Threading a store through the auth middleware's construction just to answer that
+ * one question would be worse. The map's cleanup timer is `unref`'d, so holding
+ * this at module scope does not keep the process alive.
+ */
+export const webviewCapabilities = new WebviewCapabilityStore();

src/webview-store.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Persistence for web tabs (saved dashboard URLs).
+ *
+ * Stores `Webview` records in `~/.codeman/webviews.json`, following the same
+ * read-array / write-array shape as `src/remote-hosts.ts`. Deliberately dumb: no
+ * caching, no watchers. The list is small (bounded by MAX_WEBVIEWS) and is read
+ * on demand by the route handlers.
+ *
+ * The file lives under the instance data dir, so a beta instance started with a
+ * distinct CODEMAN_INSTANCE keeps its own dashboards.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Webview } from './types.js';
+
+const WEBVIEWS_FILE = 'webviews.json';
+
+export function webviewsPath(configDir: string): string {
+  return join(configDir, WEBVIEWS_FILE);
+}
+
+export async function readWebviews(configDir: string): Promise<Webview[]> {
+  try {
+    const raw = await fs.readFile(webviewsPath(configDir), 'utf-8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? (parsed as Webview[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function writeWebviews(configDir: string, webviews: Webview[]): Promise<void> {
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+  await fs.writeFile(webviewsPath(configDir), JSON.stringify(webviews, null, 2));
+}

test/link-provider-regex.test.ts

@@ -79,6 +79,61 @@ describe('terminal link-provider regexes (shipped source)', () => {
     }
   });
 
+  it('urlPattern keeps query strings whole (a single & is part of the URL)', () => {
+    // Excluding `&` truncated every real query string: a WordPress edit link
+    // resolved to `?post=1479` and opened the wrong page, and Claude Code's OAuth
+    // login URL (many `&` params) was not clickable at all.
+    const url = shippedPattern('urlPattern');
+    const strip = (u: string) => u.replace(/[.,;:!?)&]+$/, '');
+    const cases: Array<[string, string]> = [
+      [
+        'updated in place: https://bio-hacking.blog/wp-admin/post.php?post=1479&action=edit',
+        'https://bio-hacking.blog/wp-admin/post.php?post=1479&action=edit',
+      ],
+      [
+        'open https://claude.ai/oauth/authorize?code=true&client_id=abc&scope=user%3Ainference&state=xyz',
+        'https://claude.ai/oauth/authorize?code=true&client_id=abc&scope=user%3Ainference&state=xyz',
+      ],
+      ['see https://x.com/a?b=1&c=2&d=3 ok', 'https://x.com/a?b=1&c=2&d=3'],
+      // A lone trailing & is punctuation, not part of the target.
+      ['trailing https://x.com/a?b=1& next', 'https://x.com/a?b=1'],
+    ];
+    for (const [line, want] of cases) {
+      url.lastIndex = 0;
+      const m = url.exec(line);
+      expect(m, line).not.toBeNull();
+      expect(strip(m![0]), line).toBe(want);
+    }
+  });
+
+  it('urlPattern still stops at the shell && operator', () => {
+    // `&&` never appears inside a URL, so it must remain a boundary or a link
+    // would swallow the next command.
+    const url = shippedPattern('urlPattern');
+    for (const line of ['curl https://x.com/api && echo done', 'curl https://x.com/api&&echo done']) {
+      url.lastIndex = 0;
+      expect(url.exec(line)![0], line).toBe('https://x.com/api');
+    }
+  });
+
+  it('extPattern links pasted image/PDF attachment paths', () => {
+    // `.claude-images/paste-*.png` is what Codeman writes for a pasted screenshot;
+    // without image extensions the path rendered as plain, unclickable text.
+    const ext = shippedPattern('extPattern');
+    const cases = [
+      '/home/arkon/default/claudeman/.claude-images/paste-1785164958410-d11eb7d0.png',
+      '/tmp/shot.jpeg',
+      '/opt/app/report.pdf',
+      '/home/a/diagram.svg',
+    ];
+    for (const path of cases) {
+      ext.lastIndex = 0;
+      const m = ext.exec(`see ${path} here`);
+      expect(m, path).not.toBeNull();
+      expect(m![1], path).toBe(path);
+    }
+  });
+
   it('cmdPattern arg group cannot match empty tokens (the exponential trigger)', () => {
     // structural guard: the dangerous construct is an empty-matchable token
     // inside a repeated group — `[^\s\/]*\s+` repeated. Check the pattern

test/routes/webview-routes.test.ts

@@ -0,0 +1,216 @@
+/**
+ * CRUD + capability behaviour for /api/webviews.
+ *
+ * Uses app.inject() (no port) against a temp CODEMAN_DATA_DIR, so nothing touches
+ * the developer's real ~/.codeman/webviews.json.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import fastifyWebsocket from '@fastify/websocket';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { registerWebviewRoutes } from '../../src/web/routes/webview-routes.js';
+import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
+import { webviewCapabilities } from '../../src/webview-capabilities.js';
+import { capabilityFromProxyPath } from '../../src/web/webview-proxy.js';
+
+let app: FastifyInstance;
+let tmpDir: string;
+let savedDataDir: string | undefined;
+const broadcasts: Array<{ event: string; data: unknown }> = [];
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'codeman-webviews-'));
+  savedDataDir = process.env.CODEMAN_DATA_DIR;
+  process.env.CODEMAN_DATA_DIR = tmpDir;
+  broadcasts.length = 0;
+
+  app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  // The proxy route declares a wsHandler, so the plugin must be present.
+  await app.register(fastifyWebsocket);
+  registerWebviewRoutes(app, {
+    broadcast: (event: string, data: unknown) => broadcasts.push({ event, data }),
+  } as never);
+  installRouteErrorHandler(app);
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+  if (savedDataDir === undefined) delete process.env.CODEMAN_DATA_DIR;
+  else process.env.CODEMAN_DATA_DIR = savedDataDir;
+  await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+});
+
+const create = (payload: Record<string, unknown>) => app.inject({ method: 'POST', url: '/api/webviews', payload });
+
+describe('GET /api/webviews', () => {
+  it('starts empty and reports the frame budget the client must honour', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/webviews' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.webviews).toEqual([]);
+    expect(typeof body.data.maxLiveFrames).toBe('number');
+  });
+});
+
+describe('POST /api/webviews', () => {
+  it('creates a dashboard that defaults to proxied and sandboxed', async () => {
+    const res = await create({ name: 'Grafana', url: 'http://127.0.0.1:4000/' });
+    expect(res.statusCode).toBe(200);
+    const w = res.json().data;
+    // Proxy + untrusted are the safe defaults and must not drift.
+    expect(w.embedMode).toBe('proxy');
+    expect(w.trusted).toBe(false);
+    expect(w.id).toBeTruthy();
+  });
+
+  it('broadcasts the change so other devices re-fetch', async () => {
+    await create({ name: 'G', url: 'http://127.0.0.1:4000/' });
+    expect(broadcasts.map((b) => b.event)).toContain('webview:changed');
+  });
+
+  it('persists across a fresh read of the store', async () => {
+    await create({ name: 'G', url: 'http://127.0.0.1:4000/' });
+    const list = (await app.inject({ method: 'GET', url: '/api/webviews' })).json().data.webviews;
+    expect(list).toHaveLength(1);
+    expect(list[0].name).toBe('G');
+  });
+
+  it('rejects URLs that are not plain http(s)', async () => {
+    for (const url of ['javascript:alert(1)', 'file:///etc/passwd', 'data:text/html,x']) {
+      const res = await create({ name: 'bad', url });
+      expect(res.statusCode, url).toBe(400);
+      expect(res.json().errorCode).toBe('INVALID_INPUT');
+    }
+  });
+
+  it('rejects URLs carrying embedded credentials', async () => {
+    const res = await create({ name: 'bad', url: 'http://user:pass@host:4000/' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('requires a name', async () => {
+    expect((await create({ url: 'http://127.0.0.1:4000/' })).statusCode).toBe(400);
+    expect((await create({ name: '   ', url: 'http://127.0.0.1:4000/' })).statusCode).toBe(400);
+  });
+});
+
+describe('PATCH /api/webviews/:id', () => {
+  it('updates fields and revokes the outstanding capability', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    const opened = await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` });
+    const cap = capabilityFromProxyPath(opened.json().data.embedUrl)!;
+    expect(webviewCapabilities.resolve(cap)).toBeDefined();
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/api/webviews/${id}`,
+      payload: { url: 'http://127.0.0.1:4001/' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.url).toBe('http://127.0.0.1:4001/');
+    // A token minted against the OLD url must not survive the repoint.
+    expect(webviewCapabilities.resolve(cap)).toBeUndefined();
+  });
+
+  it('404s an unknown id', async () => {
+    const res = await app.inject({ method: 'PATCH', url: '/api/webviews/nope', payload: { name: 'x' } });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('still validates the URL on update', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    const res = await app.inject({ method: 'PATCH', url: `/api/webviews/${id}`, payload: { url: 'file:///etc' } });
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+describe('DELETE /api/webviews/:id', () => {
+  it('removes it and revokes its capability', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    const opened = await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` });
+    const cap = capabilityFromProxyPath(opened.json().data.embedUrl)!;
+
+    expect((await app.inject({ method: 'DELETE', url: `/api/webviews/${id}` })).statusCode).toBe(200);
+    expect((await app.inject({ method: 'GET', url: '/api/webviews' })).json().data.webviews).toEqual([]);
+    expect(webviewCapabilities.resolve(cap)).toBeUndefined();
+  });
+
+  it('404s an unknown id', async () => {
+    expect((await app.inject({ method: 'DELETE', url: '/api/webviews/nope' })).statusCode).toBe(404);
+  });
+});
+
+describe('POST /api/webviews/:id/open', () => {
+  it('mints a same-origin embed path for a proxied dashboard', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    const data = (await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` })).json().data;
+    expect(data.embedUrl).toMatch(/^\/webview\/[A-Za-z0-9_-]{16,}\/$/);
+    expect(capabilityFromProxyPath(data.embedUrl)).toBeTruthy();
+  });
+
+  it('returns no embed path in direct mode, where the iframe uses the real URL', async () => {
+    const id = (await create({ name: 'G', url: 'https://ok.example/', embedMode: 'direct' })).json().data.id;
+    const data = (await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` })).json().data;
+    expect(data.embedUrl).toBeUndefined();
+    expect(data.webview.url).toBe('https://ok.example/');
+  });
+
+  it('reuses the capability across repeated opens instead of leaking one per click', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    const first = (await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` })).json().data.embedUrl;
+    const second = (await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` })).json().data.embedUrl;
+    expect(second).toBe(first);
+  });
+
+  it('records lastOpenedAt', async () => {
+    const id = (await create({ name: 'G', url: 'http://127.0.0.1:4000/' })).json().data.id;
+    await app.inject({ method: 'POST', url: `/api/webviews/${id}/open` });
+    const list = (await app.inject({ method: 'GET', url: '/api/webviews' })).json().data.webviews;
+    expect(typeof list[0].lastOpenedAt).toBe('number');
+  });
+
+  it('404s an unknown id', async () => {
+    expect((await app.inject({ method: 'POST', url: '/api/webviews/nope/open' })).statusCode).toBe(404);
+  });
+});
+
+describe('proxy route', () => {
+  it('refuses an unknown or expired capability', async () => {
+    const res = await app.inject({ method: 'GET', url: `/webview/${'Z'.repeat(32)}/` });
+    expect(res.statusCode).toBe(403);
+  });
+
+  it('redirects the prefix without a trailing slash, so relative URLs resolve inside it', async () => {
+    const cap = 'Y'.repeat(32);
+    const res = await app.inject({ method: 'GET', url: `/webview/${cap}` });
+    expect(res.statusCode).toBe(302);
+    expect(res.headers.location).toBe(`/webview/${cap}/`);
+  });
+});
+
+describe('POST /api/webviews/probe', () => {
+  it('reports an unreachable target as a normal answer, not a 500', async () => {
+    // Port 1 is reserved and refuses instantly.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/webviews/probe',
+      payload: { url: 'http://127.0.0.1:1/' },
+    });
+    expect(res.statusCode).toBe(200);
+    const probe = res.json().data;
+    expect(probe.reachable).toBe(false);
+    expect(probe.recommendedMode).toBe('proxy');
+  });
+
+  it('rejects an invalid URL up front', async () => {
+    const res = await app.inject({ method: 'POST', url: '/api/webviews/probe', payload: { url: 'file:///etc' } });
+    expect(res.statusCode).toBe(400);
+  });
+});

test/webview-auth-exemption.test.ts

@@ -0,0 +1,180 @@
+/**
+ * The web-tab proxy is exempt from Codeman's cookie auth and its cross-site Origin
+ * guard, because a sandboxed dashboard iframe is opaque-origin: it sends no session
+ * cookie and its writes arrive with `Origin: null`. The capability in the path is
+ * the credential instead.
+ *
+ * That exemption is the security-sensitive part of this feature, so these tests pin
+ * its EDGES: it must apply to a live capability and to nothing else. A regression
+ * here would be an unauthenticated hole into an agent-spawning API.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { registerAuthMiddleware, registerHostGuard, registerSecurityHeaders } from '../src/web/middleware/auth.js';
+import { webviewCapabilities } from '../src/webview-capabilities.js';
+import type { HostPolicy } from '../src/web/network-auth-policy.js';
+
+const POLICY: HostPolicy = { allowedHosts: [], allowLan: true };
+const PASSWORD = 'test-password';
+
+let app: FastifyInstance;
+let capability: string;
+let savedPassword: string | undefined;
+
+beforeEach(async () => {
+  savedPassword = process.env.CODEMAN_PASSWORD;
+  // The middleware reads this at registration time; auth is inert without it.
+  process.env.CODEMAN_PASSWORD = PASSWORD;
+
+  capability = webviewCapabilities.mint('webview-under-test', undefined);
+
+  app = Fastify({ logger: false });
+  await app.register(fastifyCookie);
+  // Same order as server.ts (host guard → auth → security headers), so hook
+  // interactions are exercised for real. The OPTIONS short-circuit lives in
+  // registerSecurityHeaders and is part of what these tests pin.
+  registerHostGuard(app, () => POLICY);
+  registerAuthMiddleware(app, false);
+  registerSecurityHeaders(app, false);
+
+  // Stand-ins for the real surfaces, so a reachable route means auth let it through.
+  app.all('/webview/:cap/*', async () => ({ proxied: true }));
+  app.all('/api/sessions', async () => ({ sensitive: true }));
+  app.get('/', async () => 'app shell');
+  app.get('/static/app.js', async () => 'asset');
+  app.get('/webviewfoo/bar', async () => 'lookalike');
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+  webviewCapabilities.revokeWebview('webview-under-test');
+  if (savedPassword === undefined) delete process.env.CODEMAN_PASSWORD;
+  else process.env.CODEMAN_PASSWORD = savedPassword;
+});
+
+describe('the exemption applies to a live capability', () => {
+  it('lets an unauthenticated GET through on the proxy path', async () => {
+    const res = await app.inject({ method: 'GET', url: `/webview/${capability}/static/app.js` });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('lets a write through despite Origin: null, which a sandboxed iframe always sends', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: `/webview/${capability}/login`,
+      headers: { origin: 'null' },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('lets a CORS preflight reach the proxy instead of the global 204 short-circuit', async () => {
+    // registerSecurityHeaders answers every OPTIONS with a bare 204, which carries
+    // no Access-Control-Allow-Origin for the `null` origin a sandboxed frame sends.
+    // The proxy must get the chance to answer with real CORS headers, or every
+    // dashboard fetch fails its preflight.
+    const res = await app.inject({
+      method: 'OPTIONS',
+      url: `/webview/${capability}/api/stats`,
+      headers: { origin: 'null', 'access-control-request-method': 'GET' },
+    });
+    expect(res.statusCode).toBe(200); // reached the stand-in route, not the 204 hook
+  });
+
+  it('still short-circuits OPTIONS everywhere else', async () => {
+    // Authenticated, because the auth hook runs before the security-headers hook
+    // and would otherwise 401 first. With credentials the 204 short-circuit is
+    // reached, proving it is intact for every non-webview path.
+    const res = await app.inject({
+      method: 'OPTIONS',
+      url: '/api/sessions',
+      headers: {
+        origin: 'null',
+        'access-control-request-method': 'GET',
+        authorization: 'Basic ' + Buffer.from(`admin:${PASSWORD}`).toString('base64'),
+      },
+    });
+    expect(res.statusCode).toBe(204);
+    expect(res.headers['access-control-allow-origin']).toBeUndefined();
+  });
+
+  it('serves a root-absolute asset when the Referer identifies the dashboard', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: '/static/app.js',
+      headers: { referer: `http://localhost/webview/${capability}/panel` },
+    });
+    expect(res.statusCode).toBe(200);
+  });
+});
+
+describe('the exemption does NOT widen anywhere else', () => {
+  it('rejects an unauthenticated request with no capability at all', async () => {
+    expect((await app.inject({ method: 'GET', url: '/static/app.js' })).statusCode).toBe(401);
+    expect((await app.inject({ method: 'GET', url: '/' })).statusCode).toBe(401);
+  });
+
+  it('rejects a well-formed but UNKNOWN capability', async () => {
+    const res = await app.inject({ method: 'GET', url: `/webview/${'Z'.repeat(32)}/x` });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a revoked capability immediately', async () => {
+    webviewCapabilities.revokeWebview('webview-under-test');
+    const res = await app.inject({ method: 'GET', url: `/webview/${capability}/x` });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('does not match a lookalike prefix', async () => {
+    expect((await app.inject({ method: 'GET', url: '/webviewfoo/bar' })).statusCode).toBe(401);
+  });
+
+  it('NEVER exempts the Codeman API, even with a valid capability in the Referer', async () => {
+    // This is the hole the Referer form would open if it were not path-fenced.
+    const res = await app.inject({
+      method: 'GET',
+      url: '/api/sessions',
+      headers: { referer: `http://localhost/webview/${capability}/panel` },
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('does not let the Referer form carry a WRITE', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/static/app.js',
+      headers: { referer: `http://localhost/webview/${capability}/panel`, origin: 'null' },
+      payload: {},
+    });
+    // Blocked as cross-site by the Origin guard, or as unauthenticated. Either is fine;
+    // what matters is that it is not 200.
+    expect(res.statusCode).not.toBe(200);
+  });
+
+  it('still blocks a genuinely cross-site write to the API', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/sessions',
+      headers: { origin: 'https://evil.example' },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(403);
+  });
+});
+
+describe('authenticated access is unaffected', () => {
+  const basic = 'Basic ' + Buffer.from(`admin:${PASSWORD}`).toString('base64');
+
+  it('normal Basic auth still reaches the app', async () => {
+    const res = await app.inject({ method: 'GET', url: '/', headers: { authorization: basic } });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('a wrong password is still rejected', async () => {
+    const wrong = 'Basic ' + Buffer.from('admin:nope').toString('base64');
+    expect((await app.inject({ method: 'GET', url: '/', headers: { authorization: wrong } })).statusCode).toBe(401);
+  });
+});

test/webview-proxy.test.ts

@@ -0,0 +1,493 @@
+/**
+ * Pure helpers behind the web-tab reverse proxy (src/web/webview-proxy.ts).
+ *
+ * These cover the rewrites that make an un-embeddable dashboard embeddable, and
+ * the containment checks that keep the proxy from becoming an open relay.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildDownstreamResponseHeaders,
+  buildProxyCorsHeaders,
+  buildUpstreamRequestHeaders,
+  capabilityFromProxyPath,
+  capabilityFromReferer,
+  extractFrameAncestors,
+  filterCookieHeader,
+  isFramableCrossOrigin,
+  isHtmlContentType,
+  isValidWebviewUrl,
+  parseWebviewUrl,
+  proxyPrefixFor,
+  resolveUpstreamUrl,
+  rewriteHtml,
+  rewriteLocation,
+  rewriteSetCookie,
+  runtimeUrlShim,
+  stripFrameAncestors,
+  upstreamWebSocketUrl,
+} from '../src/web/webview-proxy.js';
+
+const CAP = 'A'.repeat(32);
+const PREFIX = `/webview/${CAP}/`;
+
+describe('parseWebviewUrl', () => {
+  it('accepts plain http and https', () => {
+    expect(parseWebviewUrl('http://127.0.0.1:4000/')?.origin).toBe('http://127.0.0.1:4000');
+    expect(parseWebviewUrl('https://dash.example.com/grafana')?.origin).toBe('https://dash.example.com');
+  });
+
+  it('rejects non-http schemes', () => {
+    for (const url of ['javascript:alert(1)', 'file:///etc/passwd', 'data:text/html,x', 'ftp://host/x']) {
+      expect(parseWebviewUrl(url), url).toBeNull();
+    }
+  });
+
+  it('rejects embedded credentials, which would be forwarded and logged', () => {
+    expect(parseWebviewUrl('http://user:pass@host:4000/')).toBeNull();
+    expect(parseWebviewUrl('http://user@host:4000/')).toBeNull();
+  });
+
+  it('rejects garbage and empty input', () => {
+    expect(parseWebviewUrl('')).toBeNull();
+    expect(parseWebviewUrl('not a url')).toBeNull();
+    expect(isValidWebviewUrl('http://ok.example')).toBe(true);
+  });
+});
+
+describe('resolveUpstreamUrl', () => {
+  const saved = 'http://127.0.0.1:4000/grafana/d/abc?theme=dark';
+
+  it('serves the saved path+query for the landing page', () => {
+    expect(resolveUpstreamUrl(saved, '', '')?.href).toBe('http://127.0.0.1:4000/grafana/d/abc?theme=dark');
+  });
+
+  it('is ORIGIN-scoped, not path-scoped, so root-absolute assets resolve', () => {
+    // The saved /grafana/d/abc path must NOT be prepended, or /public/x.js 404s.
+    expect(resolveUpstreamUrl(saved, 'public/build/app.js', '')?.href).toBe(
+      'http://127.0.0.1:4000/public/build/app.js'
+    );
+  });
+
+  it('carries the query string through', () => {
+    expect(resolveUpstreamUrl(saved, 'api/data', '?from=now-6h')?.href).toBe(
+      'http://127.0.0.1:4000/api/data?from=now-6h'
+    );
+  });
+
+  it('refuses to leave the upstream origin', () => {
+    // Protocol-relative would jump host; traversal would climb out.
+    expect(resolveUpstreamUrl(saved, '/evil.com/x', '')?.origin).toBe('http://127.0.0.1:4000');
+    expect(resolveUpstreamUrl(saved, '//evil.com/x', '')).toBeNull();
+    const climbed = resolveUpstreamUrl(saved, '../../../../etc/passwd', '');
+    expect(climbed?.origin).toBe('http://127.0.0.1:4000');
+  });
+
+  it('returns null for an unusable saved url', () => {
+    expect(resolveUpstreamUrl('javascript:alert(1)', 'x', '')).toBeNull();
+  });
+});
+
+describe('capability extraction', () => {
+  it('reads the capability out of a proxy path', () => {
+    expect(capabilityFromProxyPath(`${PREFIX}static/app.js`)).toBe(CAP);
+    expect(capabilityFromProxyPath(PREFIX)).toBe(CAP);
+    expect(capabilityFromProxyPath(`/webview/${CAP}`)).toBe(CAP);
+  });
+
+  it('does not match a lookalike prefix', () => {
+    expect(capabilityFromProxyPath('/webviewfoo/bar')).toBeNull();
+    expect(capabilityFromProxyPath('/api/webviews')).toBeNull();
+    expect(capabilityFromProxyPath('/')).toBeNull();
+  });
+
+  it('rejects capabilities of implausible shape', () => {
+    expect(capabilityFromProxyPath('/webview/short/x')).toBeNull();
+    expect(capabilityFromProxyPath('/webview/has spaces here and more/x')).toBeNull();
+    expect(capabilityFromProxyPath('/webview/../../etc/x')).toBeNull();
+  });
+
+  it('reads it from a Referer for the root-absolute asset fallback', () => {
+    expect(capabilityFromReferer(`https://box.ts.net${PREFIX}page`)).toBe(CAP);
+    expect(capabilityFromReferer('https://box.ts.net/')).toBeNull();
+    expect(capabilityFromReferer('not a url')).toBeNull();
+    expect(capabilityFromReferer(undefined)).toBeNull();
+  });
+});
+
+describe('CSP handling', () => {
+  it('strips frame-ancestors and keeps every other directive', () => {
+    const csp = "default-src 'self'; frame-ancestors 'none'; script-src 'unsafe-inline'";
+    expect(stripFrameAncestors(csp)).toBe("default-src 'self'; script-src 'unsafe-inline'");
+  });
+
+  it('leaves a policy without frame-ancestors alone', () => {
+    expect(stripFrameAncestors("default-src 'self'")).toBe("default-src 'self'");
+  });
+
+  it('does not confuse a similarly-named directive', () => {
+    expect(stripFrameAncestors("frame-src 'self'; frame-ancestors 'none'")).toBe("frame-src 'self'");
+  });
+
+  it('extracts the directive value for the probe', () => {
+    expect(extractFrameAncestors("default-src 'self'; frame-ancestors https://a.com")).toBe('https://a.com');
+    expect(extractFrameAncestors("default-src 'self'")).toBeUndefined();
+    expect(extractFrameAncestors(undefined)).toBeUndefined();
+  });
+});
+
+describe('isFramableCrossOrigin', () => {
+  it('honours X-Frame-Options', () => {
+    expect(isFramableCrossOrigin('DENY', undefined)).toBe(false);
+    expect(isFramableCrossOrigin('sameorigin', undefined)).toBe(false);
+    expect(isFramableCrossOrigin(undefined, undefined)).toBe(true);
+  });
+
+  it("treats frame-ancestors 'none' and 'self' as not cross-origin framable", () => {
+    expect(isFramableCrossOrigin(undefined, "frame-ancestors 'none'")).toBe(false);
+    expect(isFramableCrossOrigin(undefined, "frame-ancestors 'self'")).toBe(false);
+  });
+
+  it('allows a wildcard or explicit host', () => {
+    expect(isFramableCrossOrigin(undefined, 'frame-ancestors *')).toBe(true);
+    expect(isFramableCrossOrigin(undefined, 'frame-ancestors https://codeman.example')).toBe(true);
+  });
+});
+
+describe('rewriteLocation', () => {
+  const requestUrl = new URL('http://127.0.0.1:4000/login');
+
+  it('maps a root-absolute redirect into the proxy prefix', () => {
+    expect(rewriteLocation('/dashboard?x=1', requestUrl, CAP)).toBe(`${PREFIX}dashboard?x=1`);
+  });
+
+  it('maps a same-origin absolute redirect', () => {
+    expect(rewriteLocation('http://127.0.0.1:4000/home', requestUrl, CAP)).toBe(`${PREFIX}home`);
+  });
+
+  it('leaves a CROSS-origin redirect alone rather than relaying it', () => {
+    // Relaying would make this an open proxy for any host the upstream names.
+    expect(rewriteLocation('https://evil.example/x', requestUrl, CAP)).toBe('https://evil.example/x');
+  });
+
+  it('preserves the hash', () => {
+    expect(rewriteLocation('/panel#row2', requestUrl, CAP)).toBe(`${PREFIX}panel#row2`);
+  });
+});
+
+describe('rewriteSetCookie', () => {
+  it('rebases Path onto the proxy prefix and drops Domain', () => {
+    const out = rewriteSetCookie('sid=abc; Path=/; Domain=dash.local; HttpOnly', CAP, true);
+    expect(out).toContain('sid=abc');
+    expect(out).toContain(`Path=${PREFIX}`);
+    expect(out).not.toContain('Domain');
+    expect(out).toContain('HttpOnly');
+  });
+
+  it('adds a scoped Path when the upstream sent none', () => {
+    expect(rewriteSetCookie('sid=abc; HttpOnly', CAP, true)).toContain(`Path=${PREFIX}`);
+  });
+
+  it('drops Secure when Codeman itself is serving plain HTTP', () => {
+    // A Secure cookie over http is silently discarded by the browser.
+    expect(rewriteSetCookie('sid=abc; Path=/; Secure', CAP, false)).not.toMatch(/secure/i);
+    expect(rewriteSetCookie('sid=abc; Path=/; Secure', CAP, true)).toMatch(/Secure/);
+  });
+
+  it('keeps a nested upstream path under the prefix', () => {
+    expect(rewriteSetCookie('sid=abc; Path=/admin', CAP, true)).toContain(`Path=${PREFIX}admin`);
+  });
+});
+
+describe('filterCookieHeader', () => {
+  it("removes Codeman's own session cookie and keeps the dashboard's", () => {
+    expect(filterCookieHeader('codeman_session=SECRET; dash=1; other=2', ['codeman_session'])).toBe('dash=1; other=2');
+  });
+
+  it('returns undefined when nothing survives', () => {
+    expect(filterCookieHeader('codeman_session=SECRET', ['codeman_session'])).toBeUndefined();
+    expect(filterCookieHeader(undefined, ['codeman_session'])).toBeUndefined();
+  });
+});
+
+describe('buildUpstreamRequestHeaders', () => {
+  const upstream = new URL('http://127.0.0.1:4000/panel');
+
+  it('NEVER forwards Codeman credentials to the dashboard', () => {
+    const headers = buildUpstreamRequestHeaders(
+      { authorization: 'Basic CODEMANCREDS', cookie: 'codeman_session=SECRET; dash=1', accept: '*/*' },
+      upstream,
+      { forwardCookies: false, sessionCookieName: 'codeman_session' }
+    );
+    expect(headers.authorization).toBeUndefined();
+    expect(headers.cookie).toBeUndefined();
+    expect(headers.accept).toBe('*/*');
+  });
+
+  it('forwards the dashboard cookies but strips the session cookie in trusted mode', () => {
+    const headers = buildUpstreamRequestHeaders({ cookie: 'codeman_session=SECRET; dash=1' }, upstream, {
+      forwardCookies: true,
+      sessionCookieName: 'codeman_session',
+    });
+    expect(headers.cookie).toBe('dash=1');
+    expect(headers.authorization).toBeUndefined();
+  });
+
+  it('presents Origin/Referer as if the browser talked to the dashboard directly', () => {
+    const headers = buildUpstreamRequestHeaders({ origin: 'https://codeman.local' }, upstream, {
+      forwardCookies: false,
+      sessionCookieName: 'codeman_session',
+    });
+    expect(headers.origin).toBe('http://127.0.0.1:4000');
+    expect(headers.referer).toBe('http://127.0.0.1:4000/panel');
+  });
+
+  it('drops hop-by-hop and recomputed headers', () => {
+    const headers = buildUpstreamRequestHeaders(
+      { host: 'codeman.local', connection: 'keep-alive', 'transfer-encoding': 'chunked', 'content-length': '5' },
+      upstream,
+      { forwardCookies: false, sessionCookieName: 'codeman_session' }
+    );
+    expect(headers.host).toBeUndefined();
+    expect(headers.connection).toBeUndefined();
+    expect(headers['transfer-encoding']).toBeUndefined();
+    expect(headers['content-length']).toBeUndefined();
+  });
+});
+
+describe('buildDownstreamResponseHeaders', () => {
+  const requestUrl = new URL('http://127.0.0.1:4000/panel');
+  const build = (entries: Array<[string, string]>, cookies: string[] = []) =>
+    buildDownstreamResponseHeaders(entries, cookies, CAP, requestUrl, true);
+
+  it('strips the framing refusal, which is the whole point of the proxy', () => {
+    const { headers } = build([
+      ['x-frame-options', 'DENY'],
+      ['content-type', 'text/html'],
+    ]);
+    expect(headers['x-frame-options']).toBeUndefined();
+    expect(headers['content-type']).toBe('text/html');
+  });
+
+  it('drops content-encoding/length because undici already decoded the body', () => {
+    // Forwarding these makes the browser try to gunzip plaintext.
+    const { headers } = build([
+      ['content-encoding', 'gzip'],
+      ['content-length', '1234'],
+    ]);
+    expect(headers['content-encoding']).toBeUndefined();
+    expect(headers['content-length']).toBeUndefined();
+  });
+
+  it('returns the upstream CSP minus frame-ancestors, and null when there was none', () => {
+    expect(build([['content-security-policy', "default-src 'self'; frame-ancestors 'none'"]]).csp).toBe(
+      "default-src 'self'"
+    );
+    expect(build([['content-type', 'text/css']]).csp).toBeNull();
+  });
+
+  it('rewrites Location and Set-Cookie', () => {
+    const { headers, setCookie } = build([['location', '/next']], ['sid=1; Path=/']);
+    expect(headers.location).toBe(`${PREFIX}next`);
+    expect(setCookie).toHaveLength(1);
+    expect(setCookie[0]).toContain(`Path=${PREFIX}`);
+  });
+});
+
+describe('rewriteHtml', () => {
+  it('injects <base> immediately after <head>', () => {
+    const out = rewriteHtml('<html><head><title>x</title></head><body></body></html>', CAP);
+    expect(out).toContain(`<head><base href="${PREFIX}">`);
+  });
+
+  it('falls back to <html>, then to the very start, for malformed documents', () => {
+    expect(rewriteHtml('<html><body>hi</body></html>', CAP)).toContain(`<html><base href="${PREFIX}">`);
+    const bare = rewriteHtml('just text', CAP);
+    expect(bare.startsWith(`<base href="${PREFIX}">`)).toBe(true);
+    expect(bare.endsWith('just text')).toBe(true);
+  });
+
+  it('does not add a second <base> when the page already has one', () => {
+    const out = rewriteHtml('<html><head><base href="/x/"></head></html>', CAP);
+    expect(out.match(/<base/g)).toHaveLength(1);
+  });
+
+  it('still injects the runtime shim when the page ships its own <base>', () => {
+    // The shim is the only layer that catches runtime-built URLs, so an early
+    // return on an existing <base> would silently break those pages.
+    const out = rewriteHtml('<html><head><base href="/x/"></head></html>', CAP);
+    expect(out).toContain('<script>');
+    expect(out).toContain(PREFIX);
+  });
+
+  it('injects the shim into every rewritten document', () => {
+    expect(rewriteHtml('<html><head></head></html>', CAP)).toContain('<script>');
+    expect(rewriteHtml('just text', CAP)).toContain('<script>');
+  });
+
+  it('rebases root-absolute src/href/action, which <base> cannot fix', () => {
+    const out = rewriteHtml(
+      `<head></head><body><script src="/static/app.js"></script><link href='/s.css'><form action="/login"></form></body>`,
+      CAP
+    );
+    expect(out).toContain(`src="${PREFIX}static/app.js"`);
+    expect(out).toContain(`href='${PREFIX}s.css'`);
+    expect(out).toContain(`action="${PREFIX}login"`);
+  });
+
+  it('leaves protocol-relative and absolute URLs alone', () => {
+    const out = rewriteHtml('<head></head><script src="//cdn.example/x.js"></script><img src="https://a/b.png">', CAP);
+    expect(out).toContain('src="//cdn.example/x.js"');
+    expect(out).toContain('src="https://a/b.png"');
+  });
+
+  it('is stable across repeated calls (no shared regex lastIndex)', () => {
+    const html = '<head></head><script src="/a.js"></script>';
+    expect(rewriteHtml(html, CAP)).toBe(rewriteHtml(html, CAP));
+  });
+});
+
+describe('buildProxyCorsHeaders', () => {
+  it('echoes the opaque origin a sandboxed frame sends', () => {
+    // Without this the browser rejects every dashboard fetch with an opaque
+    // net::ERR_FAILED, while the page itself renders fine.
+    const h = buildProxyCorsHeaders('null');
+    expect(h['access-control-allow-origin']).toBe('null');
+    expect(h.vary).toBe('Origin');
+  });
+
+  it('omits allow-credentials for a null origin, which browsers reject together', () => {
+    expect(buildProxyCorsHeaders('null')['access-control-allow-credentials']).toBeUndefined();
+  });
+
+  it('allows credentials for a real origin (trusted mode)', () => {
+    const h = buildProxyCorsHeaders('https://codeman.local');
+    expect(h['access-control-allow-origin']).toBe('https://codeman.local');
+    expect(h['access-control-allow-credentials']).toBe('true');
+  });
+
+  it('echoes requested headers on a preflight', () => {
+    expect(buildProxyCorsHeaders('null', 'content-type, x-token')['access-control-allow-headers']).toBe(
+      'content-type, x-token'
+    );
+    expect(buildProxyCorsHeaders('null')['access-control-allow-headers']).toBe('*');
+  });
+
+  it('emits nothing when the request carries no Origin', () => {
+    expect(buildProxyCorsHeaders(undefined)).toEqual({});
+  });
+});
+
+describe('runtimeUrlShim', () => {
+  const shim = runtimeUrlShim(PREFIX);
+  const body = shim.replace(/^<script>/, '').replace(/<\/script>$/, '');
+
+  it('emits a parseable script', () => {
+    expect(shim.startsWith('<script>')).toBe(true);
+    expect(shim.endsWith('</script>')).toBe(true);
+    expect(() => new Function(body)).not.toThrow();
+  });
+
+  it('contains no bare </script> that would close the tag early', () => {
+    expect(/<\/script>/i.test(body)).toBe(false);
+  });
+
+  /**
+   * Execute the shim against a fake window and return the patched globals, so the
+   * rewrite logic is tested for real rather than by reading the source.
+   */
+  function runShim(host = 'codeman.local') {
+    const calls: string[] = [];
+    const win: Record<string, unknown> = {
+      fetch: (input: unknown) => {
+        calls.push(String(typeof input === 'object' && input ? (input as { url: string }).url : input));
+        return Promise.resolve();
+      },
+      XMLHttpRequest: function () {} as unknown as { prototype: Record<string, unknown> },
+      WebSocket: class {
+        url: string;
+        constructor(u: string) {
+          this.url = u;
+          calls.push(u);
+        }
+      },
+      EventSource: class {
+        url: string;
+        constructor(u: string) {
+          this.url = u;
+          calls.push(u);
+        }
+      },
+    };
+    (win.XMLHttpRequest as { prototype: Record<string, unknown> }).prototype = {
+      open(_m: string, u: string) {
+        calls.push(u);
+      },
+    };
+    const location = { href: `https://${host}${PREFIX}page`, host };
+    new Function('window', 'location', 'URL', 'Request', `with (window) { ${body} }`)(win, location, URL, undefined);
+    return { win, calls };
+  }
+
+  it('rewrites a ROOT-ABSOLUTE fetch, the case <base> cannot reach', () => {
+    const { win, calls } = runShim();
+    (win.fetch as (u: string) => void)('/api/carousel/job?id=1');
+    expect(calls[0]).toBe(`${PREFIX}api/carousel/job?id=1`);
+  });
+
+  it('leaves relative URLs alone (<base> already handles them)', () => {
+    const { win, calls } = runShim();
+    (win.fetch as (u: string) => void)('api/data');
+    expect(calls[0]).toBe('api/data');
+  });
+
+  it('does not double-prefix an already-proxied URL', () => {
+    const { win, calls } = runShim();
+    (win.fetch as (u: string) => void)(`${PREFIX}api/data`);
+    expect(calls[0]).toBe(`${PREFIX}api/data`);
+  });
+
+  it('leaves cross-origin URLs alone', () => {
+    const { win, calls } = runShim();
+    (win.fetch as (u: string) => void)('https://cdn.example/lib.js');
+    expect(calls[0]).toBe('https://cdn.example/lib.js');
+  });
+
+  it('rewrites a same-origin ABSOLUTE URL built from location', () => {
+    const { win, calls } = runShim();
+    (win.fetch as (u: string) => void)('https://codeman.local/api/data');
+    expect(calls[0]).toBe(`https://codeman.local${PREFIX}api/data`);
+  });
+
+  it('patches XMLHttpRequest.open', () => {
+    const { win, calls } = runShim();
+    const xhr = win.XMLHttpRequest as { prototype: { open: (m: string, u: string) => void } };
+    xhr.prototype.open.call({}, 'GET', '/api/data');
+    expect(calls[0]).toBe(`${PREFIX}api/data`);
+  });
+
+  it('patches WebSocket and EventSource', () => {
+    const { win, calls } = runShim();
+    new (win.WebSocket as new (u: string) => unknown)('/live');
+    new (win.EventSource as new (u: string) => unknown)('/events');
+    expect(calls).toEqual([`${PREFIX}live`, `${PREFIX}events`]);
+  });
+});
+
+describe('misc helpers', () => {
+  it('identifies HTML content types, parameters included', () => {
+    expect(isHtmlContentType('text/html; charset=utf-8')).toBe(true);
+    expect(isHtmlContentType('application/xhtml+xml')).toBe(true);
+    expect(isHtmlContentType('application/json')).toBe(false);
+    expect(isHtmlContentType(undefined)).toBe(false);
+  });
+
+  it('maps http(s) to ws(s) for the socket leg', () => {
+    expect(upstreamWebSocketUrl(new URL('http://h:4000/live'))).toBe('ws://h:4000/live');
+    expect(upstreamWebSocketUrl(new URL('https://h/live'))).toBe('wss://h/live');
+  });
+
+  it('builds the iframe prefix', () => {
+    expect(proxyPrefixFor(CAP)).toBe(PREFIX);
+  });
+});