chore: version packages

Follow-up to #200 and #201, which gate the welcome buttons and the run-mode
dropdown on whether the CLI is actually installed. Four corrections:

1. #200 also DELETED the Cloudflare Tunnel welcome button and the QR widget
   outright. Its rationale is right (offering a tunnel where cloudflared is not
   installed is a bad default) but the conclusion overshoots: the welcome QR is
   the whole scan-to-connect-from-your-phone flow, and deleting it left a large
   block of live tunnel code in settings-ui.js driving elements that no longer
   existed. Both are restored and the button is gated on cloudflared, which is
   what the stated rationale actually asks for. New cloudflared-resolver.ts
   mirrors the CLI resolvers, and TunnelManager now shares its search path so
   the button and the spawn can never disagree about where cloudflared lives.

2. Antigravity was missing from the run-mode gating, the one run mode LEAST
   likely to be installed. It slipped past because #201 predates it. Covered
   now, plus a static test that fails if a sixth mode reaches the dropdown
   without being gated, so the next one cannot slip the same way.

3. The per-surface fetches are replaced by the injected availability object
   already used for the Codex settings tab, so the codebase has one mechanism
   rather than two. The status routes buy nothing as a gating source: every
   resolver memoizes its PATH probe server-side, so a fetch is exactly as stale
   as an injected value while costing a round trip every time the dropdown opens
   and leaving the welcome buttons to flicker in after paint. The routes
   themselves stay, including the /api/claude/status that #200 adds.

4. Unknown availability now reads as AVAILABLE for run buttons. Both PRs hid the
   button on a failed fetch, so a blip left a working install with nothing to
   click; a genuinely missing CLI only ever produced an error toast. The Codex
   settings TAB keeps the opposite default, since hiding it costs nothing.

The dropdown query is also scoped to the menu: `.run-mode-option` is the class
the saved-dashboard and history rows use too, and a document-wide querySelector
would have found whichever came first in the DOM.

Fixes a latent environment-sensitivity in 816d900 while here: the index-title
test asserted the template was untouched apart from the title, which held only
on a machine with no codex installed.

Verified end-to-end against a real server on an isolated instance+socket, with
Playwright: gemini/codex hidden and claude/opencode/antigravity/shell shown,
matching this host, tunnel button back, Codex settings tab still hidden, no
console errors. Full test:ci sweep green (3902 tests).

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

.github/workflows/release.yml

@@ -52,12 +52,20 @@ jobs:
           OLD_TAG="aicodeman@${VERSION}"
           NEW_TAG="codeman@${VERSION}"
 
-          # Update the GitHub release BEFORE deleting the old tag
+          # Update the GitHub release BEFORE deleting the old tag.
+          # make_latest pins the "Latest" badge to the Codeman release. This repo
+          # publishes TWO packages (aicodeman + xterm-zerolag-input), changesets
+          # creates a GitHub release for each, and GitHub awards "Latest" to
+          # whichever was published LAST. That is a race: 1.9.2 kept the badge,
+          # 1.9.4 lost it to xterm-zerolag-input@0.1.7 by two seconds. All package
+          # releases already exist by the time this step runs, so setting it here
+          # is deterministic.
           RELEASE_ID=$(gh release view "$OLD_TAG" --json databaseId -q .databaseId 2>/dev/null || true)
           if [ -n "$RELEASE_ID" ]; then
             gh api -X PATCH "repos/${{ github.repository }}/releases/${RELEASE_ID}" \
               -f tag_name="$NEW_TAG" \
-              -f name="$NEW_TAG"
+              -f name="$NEW_TAG" \
+              -f make_latest=true
           fi
 
           # Retag

.gitignore

@@ -2,6 +2,9 @@
 .agents/
 skills-lock.json
 
+# Written by install.sh into end-user clones when setup finishes
+.install-complete
+
 # Dependencies
 node_modules/
 
@@ -52,11 +55,22 @@ Thumbs.db
 # Generated output
 out/
 screenshots-echo-diag/
+screenshots-readme/
+screenshots-readme-real/
+screenshots-real/
 scripts/remotion/out/
 
+# Local UI/README capture scratch (screenshot runs, design mockups). Not build
+# output, but never meant for git — an unqualified `git add -A` during a COM has
+# swept dirs like these into a release before.
+design-explorations/
+
 # Artifacts that should not be tracked
 test-results/
 tmp/
+# Machine-local working files (never meant for git). ANCHORED so only the root
+# dir matches.
+/pr/
 # Root `public` (a symlink to scripts/remotion/public — local artifact). ANCHORED
 # with a leading slash so it does NOT also match src/web/public (a bare `public`
 # would swallow the whole web UI source dir and silently un-stage any new asset

.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,585 @@
 # aicodeman
 
+## 1.10.0
+
+### Minor Changes
+
+- Codeman 1.10.0.
+
+  **Every surface that offers a CLI now checks the CLI is actually there** (#200, #201). The welcome-screen run buttons, the run-mode dropdown and the App Settings "Codex CLI" tab used to be shown unconditionally, so picking one on a box without the binary spawned a session that errored out immediately. All of them now gate on a single server-injected availability object covering Claude, OpenCode, Codex, Gemini, Antigravity and cloudflared, so nothing flickers in after paint and the dropdown costs no round trips to open. Shell is never gated, which is what keeps the menu non-empty on a box with nothing installed, and unknown availability reads as available so a stale page can never leave a working install with nothing to click. Adds `isClaudeAvailable()` and `GET /api/claude/status`, the one CLI that had no availability check despite being the default. The Cloudflare Tunnel welcome button and its scan-to-connect QR are gated on `cloudflared` rather than shown regardless.
+
+  **Shell and remote-SSH sessions now launch a real login shell** (#209, #210). Local shell tabs match what tmux itself does for a pane with no `default-command`, picking up the `/etc/profile` and `/etc/profile.d/*` entries a systemd `--user` service never sourced. On remote SSH, `claude`/`opencode`/`codex`/`gemini`/`agy` are routed through the remote user's interactive login shell, fixing agent CLIs that silently failed with "command not found" because ssh's remote-command execution sees only sshd's minimal default PATH and not the `~/.local/bin` or `~/.opencode/bin` entries where those CLIs actually live. Shell mode uses the remote user's real shell instead of hardcoded bash. The login flags are applied only to shells verified to accept them, so an exotic passwd entry (nushell, elvish, xonsh) cannot produce a dead pane on arrival.
+
+  **A crashed remote pane is kept for diagnosis** (#210), which is how the PATH failure above was found: it previously destroyed the pane, the window and the whole remote session on exit, tearing the local ssh attach down with it and leaving a flap loop with no evidence. Scoped to `remain-on-exit failed`, so a clean `exit` still tears the session down and only a non-zero exit strands anything, and applied last in the tmux command chain so a remote tmux older than 3.2 cannot drop the other session options with it.
+
+  **Resumed sessions under a hidden directory get the right working directory** (#202). Claude Code's project-key encoder maps both `/` and `.` to `-`, and the decoder could not reconstruct a dot-prefixed component, so every session under `~/.codeman` (or any project nested beneath any dotdir) silently resolved to bare `$HOME`. The wrong `workingDir` then propagated into `state.json` and everything trusting it: CLAUDE.md lookup, paste-image directory, subagent and image watchers. A same-named non-dot sibling could also produce a doubled-slash path that failed every later string comparison.
+
+  **Launching a session no longer wipes the terminal you are looking at** (#180). All six run modes route through the shared ownership helpers instead of clearing and writing into whatever session happened to be active, Antigravity included.
+
+  **Codex terminal animations are configurable** (#181), and the App Settings "Codex CLI" tab appears only where the `codex` binary resolves, since both settings on it are handed to `codex` at launch.
+
+## 1.9.9
+
+### Patch Changes
+
+- Two bug fixes.
+
+  **Plain shell sessions could not start when the server process had no `SHELL` (#208).** The tmux pane command for `mode: 'shell'` was the literal string `$SHELL`. That string is embedded in the `bash -c "..."` argument of the `respawn-pane` line, which is run through `/bin/sh -c`, so it was expanded by the _server_ process's shell against the _server_ process's environment rather than inside the pane. Containers and system-level systemd units do not set `SHELL`, so it expanded to nothing and the pane command ended in a dangling `&&`, giving `bash: -c: line 1: syntax error: unexpected end of file` and a pane that died instantly (status 2) while tmux session creation still reported success. The shell is now resolved in Node (`$SHELL`, then the passwd entry, then `/bin/bash`, `/bin/zsh`, `/bin/sh`), requiring an absolute path to an executable and skipping `nologin`-style stubs, then shell-quoted. Only local shell sessions were affected: agent CLI modes emit a real command, and Docker/remote-SSH cases already used a literal `exec bash -l`.
+
+  **A session name typed into the tab options could be silently dropped.** Two independent paths. In the Session Options modal, the Session Name input saves on blur while every autosave handler bails on a null `editingSessionId`, and `closeSessionOptions()` cleared that id before hiding the modal (hiding is what blurs the input), so the save always ran too late; Escape and backdrop-click lost the name with no PUT at all, and only the X button worked because mousedown blurs first. The focused modal field is now blurred before the id is cleared, which also covers the auto-compact prompt. Separately, the right-click inline rename could be destroyed mid-keystroke: the `_inlineRenameActive` guard was missing from `_renderSessionTabsImmediate()`, so a render queued just before the rename opened still rewrote the tab name's innerHTML, committing a truncated name or closing the rename outright. The debounced executor is now guarded too.
+
+## 1.9.8
+
+### Patch Changes
+
+- **Fixed: sessions failed to start on macOS with `Error: posix_spawnp failed.`** (issues #6 and #204)
+
+  `node-pty@1.1.0` publishes its macOS prebuilt helper as `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit. macOS launches every PTY through that helper, so a stock install failed on every session start. The bug is macOS-only: `spawn-helper` is a mac-only gyp target and node-pty ships no Linux prebuild, so Linux always compiles a correctly-permissioned helper from source.
+
+  The previous fix chmodded only `build/Release/spawn-helper`, which on macOS does not exist (the prebuild is used, so node-gyp never runs), and it derived that path from `require.resolve('node-pty')`, landing on `<pkg>/lib/build/Release/...`. It was a no-op on every platform.
+  - New `scripts/fix-node-pty.mjs` (also `npm run fix:node-pty`) chmods every `spawn-helper` it finds, in `build/Release`, `build/Debug` and each `prebuilds/*/`, then verifies the result by actually opening a PTY. A `require()` alone passes on a broken install, because the helper is only touched at spawn time.
+  - `postinstall` no longer force-rebuilds node-pty from source on Node 22+. That step needed Xcode command line tools, cost 30-120s on every install, and deleted the `prebuilds/` tree before compiling, so a Mac without a compiler was left with no working binary at all. A rebuild now happens only when the chmod plus spawn probe still fails, and the prebuilds tree is backed up and restored around it.
+  - New `spawnPtyWithHelperRepair()` (`src/utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts`, so an install that is already broken repairs itself on the first failed spawn and retries in-process instead of showing a dead session. Unrelated spawn errors are rethrown untouched; a second failure carries the `npm run fix:node-pty` hint.
+  - `scripts/fix-node-pty.mjs` is now in the published `files` list, so global npm installs get the repair too.
+  - Direct-PTY Claude spawns use the resolved absolute binary path (new `getClaudeBinaryPath()`) instead of the bare name `claude`, so a CLI installed outside the server's PATH still launches.
+
+  Verified end to end on macOS 26.4 arm64: a stock `npm i` reproduces `posix_spawnp failed.`, and after the fix the same install spawns a PTY successfully with the prebuilds preserved.
+
+  **Added: phone home screen (session overview)**
+
+  Under 430px the "C" logo now opens a session overview (current sessions, past sessions, spaces) instead of the welcome overlay: on a small screen "which session needs me" beats "how do I start one". Rows resume a session in place, and "New session here" goes through the normal quick-start path so remote and Docker cases keep their routing. Per-device setting `mobileOverviewEnabled` (phones only, default ON) in App Settings. Tablet and desktop are unchanged.
+
+  **Added: guided Tailscale setup in `install.sh`**
+
+  The network-access prompt is now 3-way: Tailscale, LAN, or local-only. The Tailscale path binds loopback and walks through installing Tailscale, logging in, the operator grant, the tailnet HTTPS-certificates toggle, and `tailscale serve --bg <port>`, then verifies the result end to end with curl. That gives HTTPS on a real certificate with no app password and no `0.0.0.0` bind, which is also what PWA install and web push need. `install.sh tailscale` retrofits it onto an existing install, and `CODEMAN_TAILSCALE=1` presets the choice. Serve state is detected from `tailscale serve status --json`; the installer never runs `tailscale serve reset` and never touches serve mappings other than 443 to Codeman's port. README and `docs/security-architecture.md` updated to match.
+
+  **Docs**: replaced a real tailnet hostname with placeholders in `docs/web-tabs-fixes-plan.md`.
+
+  **xterm-zerolag-input**: npm description and keywords only, no code change.
+
+## 1.9.7
+
+### Patch Changes
+
+- Antigravity run mode, plus opt-in entrance animations.
+
+  **Antigravity CLI backend (#207).** Antigravity (`agy`) joins Claude Code, shell, OpenCode, Codex and Gemini as a sixth session backend, following the same pluggable-resolver pattern: `utils/antigravity-cli-resolver.ts` resolves the CLI and `GET /api/antigravity/status` reports availability and path. `ANTIGRAVITY_*` is added to the `ALLOWED_ENV_PREFIXES` allowlist so env overrides stay CLI-scoped rather than blanket-forwarded. Like the other external CLIs it requires tmux with no direct PTY fallback, because secrets are injected through socket-scoped `tmux setenv` and never on the spawn command line. The UI gains a Run-dropdown entry, an agent-type option, an `ag` tab badge and toolbar colours; `runAntigravity()` routes remote and docker cases through `POST /api/quick-start` and skips the local status probe for them.
+
+  **Entrance animations (opt-in, OFF by default).** Optional animations for the four things that appear when work starts: session tabs, the terminal pane a session's CLI runs in, floating agent windows, and the connection lines tying a window back to its parent tab. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. Choose a look in App Settings > Appearance > Entrance Animations (per-device, stored in localStorage rather than the settings payload); `?animlab=1` opens a per-surface picker with a live preview that fakes tabs, a pane, a window and a line so styles can be compared without spawning sessions.
+
+  Three implementation notes worth knowing if you touch this: tabs and connection lines are destroyed mid-animation on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML, `_updateConnectionLinesImmediate()` clears the SVG), so both are tracked by id and re-applied to the fresh element with a negative `animation-delay` that resumes rather than restarts them; terminal-pane styles animate transform, opacity and clip-path only, because xterm's FitAddon derives rows and columns from the untransformed layout box and animating width or height there would resize the PTY; and window styles that transform also move the rect their connection line aims at, which is why the `beam` style animates opacity and filter only.
+
+  Also fixes an agent window spawning hidden (its agent belongs to a background tab): being `display:none` it never ran its animation, so `animationend` never fired and the entrance class plus its inline custom property stuck to the window permanently. Hidden windows now skip the entrance entirely.
+
+## 1.9.6
+
+### Patch Changes
+
+- Two fixes from community PRs (thanks @Lint111):
+  - fix(transcripts): complete tools from user-entry results (#177). Claude transcripts record tool requests in assistant entries but commonly carry their results in user-role entries; the transcript watcher only completed tools from the older assistant-entry path, so Codeman could keep showing a tool as running after it had finished. The watcher now recognizes `tool_result` blocks in user entries, ends the active tool state, and emits `transcript:tool_end` with the correct tool name and error status. Watcher tests also moved from fixed sleeps to condition-based `vi.waitFor` assertions.
+  - fix(notifications): quiet lifecycle hook noise (#178). Notification preferences move to schema version 5: the drawer-only "Response complete" (stop) default is now off, and the migration disables only the legacy drawer-only shape, preserving any explicit browser, audio, or push delivery the user opted into. Teammate-idle and task-completed hooks now map to the existing opt-in subagent categories instead of the broadly enabled idle/stop alerts, so normal agent activity no longer floods the drawer. Local and server-hydrated preferences are normalized through the same migration path (server hydration used to revive the retired default on fresh browsers), and the notification storage key now uses the stable handheld identity so an unfolded foldable keeps its mobile defaults and storage key (tablets and desktops unaffected).
+
+## 1.9.5
+
+### Patch Changes
+
+- Background-Bash rewake hook, hooks self-heal that preserves user hooks, and test-harness isolation.
+  - New `PostToolUse(Bash)` hook (PR #176): a self-contained `node -e` helper watches the session transcript for a background command's completion notification and uses Claude Code's `asyncRewake` to wake an idle agent (exit code 2), without injecting terminal input that could submit a user's draft. Works on Claude Code 2.1.207+; older CLIs strip the fields harmlessly.
+  - Hooks self-heal (`refreshStaleHookSecret` renamed to `refreshStaleCodemanHooks`) now replaces only Codeman-owned handlers, preserving user events, matchers, and sibling handlers in mixed configurations; `writeHooksConfig` merges instead of clobbering the hooks key at case creation (PR #176).
+  - Rewake helper hardening: self-terminates on its own 6h deadline and when orphaned; the marker is versioned (V2) with a version-agnostic ownership prefix so future script updates replace older handlers instead of duplicating them.
+  - Hook timeout units fixed: the hook `timeout` field is seconds (the CLI multiplies by 1000), so `HOOK_TIMEOUT_MS = 10000` gave curl hooks a ~2.8-hour effective timeout; now `HOOK_TIMEOUT_SECONDS = 10`.
+  - Test-harness isolation (PR #175): every test file gets a temporary `HOME`/`USERPROFILE` so tests cannot touch real Codeman state or delete real case directories, and `Session` attaches a raw-mode echo PTY instead of a real tmux client under Vitest. Fixes the quick-start suite deleting the real `~/codeman-cases/testcase`.
+  - CI stability: drain console-log rpc forwards before worker teardown (fixes a run-failing `EnvironmentTeardownError` with all tests passing); `test/webview-proxy.test.ts` no longer accidentally runs under the jsdom environment via a directive named in a comment.
+  - Release workflow pins the GitHub "Latest" badge to the Codeman release.
+
+## 1.9.4
+
+### Patch Changes
+
+- Fix a latent bug where a partial settings PUT silently reset live service state, and trim the `xterm-zerolag-input` README callout.
+  - **`PUT /api/settings` no longer resets watchers on a partial body.** The three `toggleService` calls (subagent watcher, workflow-run watcher, image watcher) read the raw request body with `??` defaults, so every key a caller omitted was treated as "apply the default". A body of just `{statusLineTelemetry:true}` would START the subagent watcher and STOP the workflow and image watchers, undoing the persisted config. They now resolve from `merged` (persisted settings + incoming), the same convention the `tmuxHistoryLimit` branch in that handler already used, so any PUT reconciles services to the effective stored state. Nothing triggered this in practice because every shipped client sends a full settings payload rebuilt from the DOM, but it was a trap for the next partial-update caller.
+  - **Regression test**: `test/routes/system-routes-settings-partial-put.test.ts` (4 cases) pins both directions, omitted keys preserve state and explicit keys still take effect. Verified to fail against the pre-fix handler.
+  - **CLAUDE.md** records the rule under "Adding Features → App setting": anything acting on a setting in that handler must resolve from `merged`, never the request body.
+  - **`xterm-zerolag-input` README**: removed the links line (getcodeman.com / install one-liner / star link) from the Codeman callout above the demo GIF. The callout keeps its links in the heading and body.
+
+## 1.9.3
+
+### Patch Changes
+
+- Plan-usage chip now defaults ON on desktop, plus the reworked `xterm-zerolag-input` README.
+  - **Plan-usage chip defaults ON (desktop).** The `showPlanUsageLimits` chip (live 5-hour and weekly plan usage from the Claude statusline) used to be opt-in and default OFF, so most users never saw it. Desktop now defaults ON; handhelds still default OFF so the phone header stays minimal and the `mobile-header-buttons-policy` guard keeps passing. Devices with an explicitly stored preference keep whatever they chose, so nobody's OFF gets overridden.
+  - **One resolver behind the chip.** Added `planUsageChipEnabled()` in settings-ui.js and routed all three call sites through it: the App Settings checkbox, the chip's visibility, and the create-time `statusLineTelemetry` flag in session-ui.js. Those three had independent `?? false` / `=== true` defaults, and a chip revealed without the telemetry flag renders `—` forever, so a default flip on one site alone would have shipped a permanently empty chip.
+  - **Cron button comment corrected.** The App Settings comment claimed "Cron button defaults ON" while the code, the template (`btn-cron--hidden`) and the CSS all default it OFF. Verified against a fresh browser profile: the button is hidden and its checkbox unchecked out of the box. Comment now matches, and states why the two halves stay consistent.
+  - **Docs.** CLAUDE.md, `docs/architecture-invariants.md` and `docs/usage-limits-display-plan.md` updated for the new default and the single-resolver rule; the stale `styles.css` comment claiming the server strips the chip's hidden class at render was corrected (display is per-device, so the client reveals it).
+  - **`xterm-zerolag-input` README rework** (0.1.5 shipped the content; this republishes with the graphic and promo changes): replaced the misaligned 8-line keystroke-flow diagram with a two-line stock-vs-zerolag contrast, added a Codeman callout above the demo GIF with links to getcodeman.com and the repo, and rewrote the Origin section so it argues the extraction story instead of repeating the promo.
+
+## 1.9.2
+
+### Patch Changes
+
+- Rewrite the `xterm-zerolag-input` package README as a value-first document and correct the drift that had accumulated against the source.
+  - Added the side-by-side phone demo GIF (`docs/images/zerolag-demo-20260728.gif`) as the hero image, referenced by absolute raw URL so it renders on npmjs.com as well as GitHub. The two-phone comparison shows 0ms local echo next to a 600ms-2.7s server echo on the same session.
+  - New "Why this one" comparison table, an explicit list of target use cases (SSH web clients, cloud IDEs, mobile terminals, container consoles), and a bundle-size badge (6.1 kB gzipped, measured from the ESM build).
+  - Corrected the test-count badge from 78 to the actual 175 tests across 5 files, in both the package README and the Published Packages section of the root README.
+  - Removed the stale "Unicode/emoji rendered at single-cell width" limitation. CJK, fullwidth forms and emoji have had double-width rendering and visual-column positioning since the wide-character fix; the honest remaining caveat (per-code-point width summing over-counts ZWJ grapheme clusters) replaces it.
+  - Documented the previously undocumented public `setPrompt()` method for switching prompt strategies at runtime, and the new "Wide characters (CJK, emoji)" integration section covering the optional `Unicode11Addon` path and the built-in range-table fallback.
+  - Documented `backgroundColor: 'transparent'`, corrected the `foregroundColor` default, and updated the grid-alignment math to reflect visual-column positioning rather than character index.
+
+  No source changes, docs only.
+
+## 1.9.1
+
+### Patch Changes
+
+- Narrow the Run dropdown, and close the last two gaps in web-tab asset rewriting.
+
+  **The Run dropdown was pinned at its full width.** It capped at 300px, and the recent-session rows wanted 326px, so it always rendered at the cap and reached further across the terminal than it needed to. Now 250px, chosen as the width at which a `~/<dir>/<repo>` + timestamp row still fits whole, since identifying a session to resume is what that list is for. Three fixes were needed to make the narrower menu degrade instead of clip: the saved-URL label now has its own element, because `text-overflow` on the row button did nothing (a bare text node inside a flex container becomes an anonymous flex item that ellipsis cannot reach); `.hist-dir` got `min-width: 0`, without which a flex item refuses to shrink below its own text and pushes the date out of the box; and history rows are held to the container width, because the list's `overflow-y: auto` implicitly makes `overflow-x: auto` and let each row size to its own content and scroll sideways. Phone and tablet widths are unchanged, being set separately in `mobile.css`.
+
+  **A dashboard's own `/api/...` assets are relayed again.** The `Referer`-keyed 404 fallback, which rescues a root-absolute asset that no rewrite layer could reach, refused everything under `/api` outright. Dashboards commonly serve their assets from exactly that namespace, so those requests had no rescue at all. The refusal is now precise: the relay runs before the API-shaped 404, and the auth exemption refuses only paths that resolve to a REAL Codeman route, with `/ws/` and `/q/` still refused by prefix.
+
+  Two findings shaped that fence, both from probing Fastify rather than reading it. `hasRoute()` matches the registered PATTERN literally, so `/api/sessions/abc` reports no match against a registered `/api/sessions/:id` and would have granted an unauthenticated exemption on a live session-scoped route; `findRoute()` performs the real lookup and is what the fence uses. And `@fastify/static` is mounted at `/`, so it registers a root catch-all matching every path, which has to count as "no real route" or the fence would refuse every referer-form request and break the rescue that already worked. A root catch-all is distinguishable because it is the only route whose wildcard param comes back equal to the whole request path. The fence fails closed, and both edges are pinned in `test/webview-auth-exemption.test.ts`.
+
+  **`url()` inside runtime CSS is rewritten.** Measuring the fallback against a purpose-built dashboard showed one sink no relay can reach: a `<style>` element built by page script has no URL of its own, so the browser sends an EMPTY `Referer` with the image request it triggers. The injected URL shim now rewrites root-absolute `url()` in `<style>` blocks, both as markup and when a `<style>` node is inserted. Verified in Chromium: a stylesheet-only `/api/hero.png` and a runtime `<style>` `/api/late.png` both load, where both previously failed. The remaining known gap is self-navigation via `location.href`, which cannot be patched because `Location.href` is unforgeable.
+
+## 1.9.0
+
+### Minor Changes
+
+- 2667150: feat(mobile): browse and insert local file and folder paths
+
+  Add a root-confined filesystem picker to Link Existing and the extended mobile
+  keyboard bar. Selected paths remain editable at the active prompt, supported
+  images/documents/text files open in a safe inline preview, and a new one-tap
+  action clears only the current unsent input without invoking `/clear`.
+
+### Patch Changes
+
+- 3cff98f: Fix two multi-user scoping holes in the new filesystem path picker. `GET /api/filesystem/browse` and `GET /api/filesystem/preview` accept an optional `sessionId` that contributes the session's working directory as a browse root, but they resolved it straight off the session map without an ownership check, unlike the nine other session-scoped handlers in the same route file. A non-admin could therefore pin another user's working directory as a root simply by passing their session id, then list and preview files under it. Both endpoints now run `canAccessOwned` and report 404, which also avoids confirming that a session id exists.
+
+  Separately, `Home` and `CASES_DIR` were unconditional browse roots for every caller. Per-user spaces live at `<USER_SPACES_DIR>/<username>`, which is inside `homedir()`, so the `Home` root alone exposed every other user's workspace to any authenticated user. In multi-user mode a non-admin now gets only their own space plus anything explicitly listed in `CODEMAN_FILE_PICKER_ROOTS`; `/mnt/d` is no longer offered by default, since a broad host mount should be an explicit operator decision in a multi-user deployment. Admins keep the host-wide roots, and single-user mode is unchanged.
+
+  Both holes are regression-guarded in `test/routes/file-routes.test.ts`, verified to fail against the previous code. Multi-user mode is opt-in and off by default, so single-user installs were never affected.
+
+- Web tabs: delete saved URLs from the Run dropdown, and fix images in proxied dashboards.
+
+  **Saved URLs are now manageable from the dropdown.** Each row under "Web / URL" gains a gear and an `x`, so a URL can be edited or deleted without first opening it as a tab. Previously the only delete path ran through the gear on an open tab, which was a dead end for a URL you no longer wanted open at all. Both controls stay permanently visible rather than hover-revealed, because the same menu is used on touch, and they get a larger hit box there. Deleting leaves the dropdown open on the remaining rows, and deleting the dashboard that is currently open also closes its tab and unmounts its frame.
+
+  **Runtime-injected images no longer 404.** A dashboard that renders its own markup from script (`card.innerHTML = '<img src="/api/hero?slug=x">'`, `img.src = '/api/slide'`) escaped every rewrite layer at once: `<base href>` never applies to a root-absolute URL, the server-side attribute rewrite only ever sees the initial document, and `runtimeUrlShim()` patched only `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource`. Those requests landed on Codeman's own root and 404'd, with a symptom that reads as an upstream fault: the dashboard's data loaded while every image stayed broken.
+
+  The shim now also covers the DOM URL sinks, so the request is never emitted in the first place and neither the `/api` fence in the 404 fallback nor the one in the auth middleware had to move. It wraps `innerHTML`, `outerHTML`, `insertAdjacentHTML` (including on `ShadowRoot`), `setAttribute`/`setAttributeNS`, and the `src`/`srcset`/`href`/`poster`/`data`/`action` property setters on img, source, media, video poster, script, iframe, embed, track, link, anchor, area, object and form, with a `MutationObserver` as a last net for sinks not patched above. Every rewrite routes through the same idempotent helper, which matters because unlike the server-side rewrite this one sees markup that may already be proxied, and a page re-injecting its own `outerHTML` would otherwise double-prefix. Everything is defensively guarded and marked so a double injection cannot wrap an already-wrapped setter.
+
+  Measured against a real dashboard: 693 image elements, 0 of them under the proxy prefix and 0 of 23 in-viewport images decoded before, 693 and 23 of 23 after. Covered by a new jsdom suite over the shim's DOM half and a new frontend suite over the dropdown rows. Known remaining gaps are documented in `docs/web-tabs.md`: a root-absolute `url()` inside a stylesheet injected at runtime, and self-navigation via `location.href`, which cannot be patched because `Location.href` is unforgeable.
+
+  Also in this release: a value-first README overhaul pointing at getcodeman.com, and the QR-auth distribution test now uses a chi-square check instead of a max-deviation threshold that failed on random variance.
+
+- bca56b4: Normalize Claude conversations in the response viewer. A Claude transcript is an append-only event log, so one logical exchange spans many JSONL rows: tool-result rows, meta/image/skill rows, compact summaries, task and team notifications, sidechains, replayed assistant snapshots, and multi-block assistant output. The viewer rendered a card per row, which produced duplicate and truncated cards that read as lost responses. Cards are now built at real human-turn boundaries, replayed assistant snapshots are deduplicated, and sidechain rows (which belong to subagents, not the main conversation) no longer leak in. An identical prompt that legitimately recurs after an assistant reply is still kept as its own turn.
+
+  Measured over 40 real transcripts: 3108 cards became 621, duplicate cards dropped from 74 to 8 (all of them genuinely repeated turns), no assistant text was lost, and the non-`context=full` last-response text was byte-identical on every file.
+
+  Also rebinds recovered sessions to their transcript. `reconcileSessions()` can recover a lost mux session as a `restored-<uuid8>` placeholder with a stale working directory, which made transcript lookup by cwd find nothing. The placeholder still carries the first eight characters of the conversation UUID, so the viewer now rebinds to the matching top-level transcript when exactly one candidate matches.
+
+## 1.8.3
+
+### Patch Changes
+
+- 8c089a4: Add four light UI and terminal skins: Paper Gray, Solarized Light, Catppuccin Latte, and Rosé Pine Dawn. The Skin picker now groups Light and Dark options, and each light skin ships a matching xterm ANSI palette plus `color-scheme: light` so native selects, date pickers and scrollbars stop rendering as dark OS widgets on a light page. Terminals set `minimumContrastRatio: 4.5` under a light skin (main terminal and teammate terminals both), which keeps CLI output that assumes a dark background readable, and `applyTerminalSkin()` now refreshes the zero-lag input overlay so typed-but-unflushed text does not keep the previous theme's colors.
+
+  Elevated surfaces (modals, command palette, dropdowns, subagent and ultracode windows, file preview, attachment tray, mobile sheets) now resolve through shared `--floating-bg` / `--control-*` / `--banner-bg-*` / `--modal-backdrop` / `--elevated-shadow` tokens instead of hardcoded near-black rgba, so they follow whichever skin is active. On the Daylight skins this lifts modals slightly off the page background; OG Codeman pins its own near-black value to keep that palette neutral.
+
+  Also defines twelve CSS compatibility aliases (`--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--text-primary`, `--text-secondary`, `--border-color`, `--accent-color`, `--success`, `--error`, `--danger`, `--font-mono`, `--shadow-lg`) that panels and overlays already referenced in about 79 places but which were never actually declared, so those rules silently resolved to nothing. Status badges and accent-tinted pills (search filter chips and result badges, session tab mode pills, respawn state, Ralph priority and circuit-breaker badges, tunnel and voice status, mobile case picker) no longer keep their pale light-on-dark ink under a light skin, where it measured 1.0 to 1.9:1 and made the search filter chips invisible.
+
+  New static regression `test/skin-themes.test.ts` guards the four-way parity between the CSS token block, the xterm palette, the pre-paint allowlist and the Settings picker.
+
+## 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
+
+- Mobile and UI polish plus docs refresh.
+  - Mobile: the header brand collapses to a single "C" home button on phones (<430px), freeing header space for session tabs while keeping the same tap target. The compact letter lives in its own span so i18n custom branding keeps rewriting only the full wordmark.
+  - UI fix: the absolutely-centered toolbar voice button no longer overlaps the case picker's chevron and "+" button. Below ~1500px (or with long case names widening the left toolbar group) it now falls back into normal flex flow where overlap is impossible; wide viewports keep the centered layout.
+  - Docs: README gains a hero pitch block with deep links, npm version + GitHub stars badges, and a star CTA; CLAUDE.md core-files table synced (Infra docker modules, app.js line count); blog article images added under docs/images/blog/.
+
+## 1.7.0
+
+### Minor Changes
+
+- Community release (thanks @shenlvkang-collab for all four PRs) plus documentation fixes.
+  - fix(mobile): per-device settings now key off a stable handheld classification (`MobileDetection.isHandheldDevice()`: touch plus UA form-factor tokens, with User-Agent Client Hints fallback) instead of the instantaneous viewport width, so an Android foldable that unfolds past the desktop breakpoint keeps `codeman-app-settings-mobile` and opt-ins such as the Response Viewer and Extended Keyboard Bar. Responsive layout stays width-driven. Adds an OPPO Find N5 (unfolded) device profile and a fold/unfold/reload Playwright regression test (mobile suite now 136 devices). (#162)
+  - fix(paths): `SAFE_PATH_PATTERN` now accepts Unicode letters and numbers (`\p{L}\p{N}` with the `u` flag), so working directories like `/mnt/d/AI/中文项目` validate in Create Session, Quick Run, and Scheduled Run. All shell-metacharacter, traversal, and absolute-path protections are unchanged. (#163)
+  - fix(ui): newly created run sessions render their tab immediately instead of waiting for the `session:created` SSE event (idempotent upsert from the POST response, with a `GET /api/sessions/:id` fallback for quick-start modes), and the Run button holds an in-flight lock (min 500 ms) so a double click cannot create duplicate sessions. (#164)
+  - feat(ui): the synced custom display name and per-device English/Simplified Chinese UI language are described in their own entry (#165); on top of that PR, `renderIndexHtml` no longer recomputes `windowTitle` on solo-session renders, so a detached window cannot reset the push-notification `hostTitle` prefix to the default name.
+  - docs: corrected the `sse-events.ts` fileoverview breakdown (148 event constants, was stale at 120; per-category counts refreshed, including Cron, Docker, Remote auto-reconnect, and Multi-user) and the CLAUDE.md SSE registry count; READMEs synced with the 1.6.2 installer behavior.
+
+### Patch Changes
+
+- 8d9fc41: Add a synced custom display name and a per-device English/Simplified Chinese browser UI language picker under App Settings → Display.
+
+## 1.6.2
+
+### Patch Changes
+
+- Installer (install.sh) reliability and safety overhaul, prompted by a review of the Linux flow:
+  - Install-completion marker (`.install-complete`): a bare re-run only takes the quiet update path when a previous install actually finished. Previously, a first install that failed during npm install/build (or was interrupted) left `.git` behind, so the retry silently became an "update" and the user never got the launch menu, the `codeman`/`tmux-chooser` symlinks, the PATH entry, or the `sc` alias. The marker is refreshed by updates and cleared by uninstall when the app dir is kept; added to .gitignore for end-user clones.
+  - `update` no longer runs an unconditional `git reset --hard` over local changes: interactive runs are asked to stash (declining keeps everything and skips the update), headless runs auto-stash with a dated message (same policy as scripts/self-update.sh).
+  - Service setup is verified instead of asserted: after starting codeman-web, the installer polls `systemctl --user is-active` (up to 6s) and only then prints "Codeman is running now!"; failures print an honest warning plus status/journalctl hints. Uses `restart` instead of `start` so re-running the installer over an already-running service actually loads the new build. A missing user D-Bus session (e.g. bare `ssh host 'curl | bash'`) is detected up front with copy-paste recovery commands instead of dying mid-setup via `set -e`. macOS gets the equivalent `launchctl list` verification, and the update path verifies its service restart too. The Cloudflare tunnel-service offer is skipped when service setup failed.
+  - Headless consent guard: with no interactive terminal AND no explicit `CODEMAN_NONINTERACTIVE=1`, the installer now refuses (with instructions) to run sudo package installs (git/node/tmux) or third-party `curl | bash` AI CLI installers, instead of silently taking the default-yes prompts. Explicit `CODEMAN_NONINTERACTIVE=1` keeps the previous full-auto behavior for CI/automation.
+  - AI CLI gate now recognizes Codex and Gemini (search paths mirrored from the CLI resolvers), so a box with only Codex or Gemini installed is no longer forced to install Claude Code/OpenCode. The install menu gains a "Skip" option (with npm install hints for Codex/Gemini), and the final reminder lists all four CLIs.
+
+  Docs: CLAUDE.md documents `src/remote-reconnect.ts` (pure COD-108 auto-reconnect backoff/eligibility logic) in the Infra table and the remote-sessions pattern.
+
+## 1.6.1
+
+### Patch Changes
+
+- **Admin Panel for multi-user mode.** Admins in multi-user mode now get a prominent Admin Panel button at the top of the page (header, admin-only; the template ships it hidden and `admin-ui.js` reveals it after identity boot; hidden on phones per the mobile header policy, where user management stays reachable via App Settings > Users). It opens a full Admin Panel modal: a users table with role, enabled/disabled status, bypass-permissions grant, live sessions, active logins, case count, and last login; per-user actions for Promote/Demote, Enable/Disable, Grant/Revoke bypass, Reset password (copyable one-time password), Force logout, and Delete (with an optional "also delete their files" step); and a proper add-user form (role, optional password, bypass checkbox) replacing the old prompt() flow. Each user's cases open in a drawer listing their case folders (modified date, live-session badge) with per-folder delete. Two new admin endpoints back this: `GET /api/admin/users/:username/cases` and `DELETE /api/admin/users/:username/cases/:caseName`, guarded like `deleteUserSpace` (symlinks refused, realpath confined to the user's space, folders in use by a live session refused with 409, audit-logged). The panel and the App Settings Users tab live-refresh on the SSE `admin:usersChanged` event (now wired in app.js). New coverage in `test/admin-routes.test.ts` (list/delete, traversal + symlink refusal, non-admin 403) and `test/admin-ui.test.ts` (button reveal gating, panel render, case drawer); verified end to end against a live multi-user instance with curl and Playwright.
+
+  **Also in this release:** README/docs synced with 1.6.0 (remote SSH cases, session manager, permissions) and fixed installer prompts when run via `curl | bash`.
+
+  **Recap of the recent feature line, for readers catching up:**
+  - **Multi-user mode (shipped 1.5.0, opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`).** Named users with scrypt-hashed passwords, per-user case spaces under `~/codeman-users/<name>/cases`, and full ownership scoping of sessions, cases, cron jobs, scheduled runs, search, file previews, and SSE/WS streams. Non-admin users default to Claude's classifier-guarded `--permission-mode auto`; shell mode, cron `launchCommand`, and skip-permissions bypass switches require the per-user `canBypassPermissions` grant (now toggleable from the Admin Panel). Admin API with one-time passwords, last-admin invariants, and an append-only audit log; self-service `/api/me` password change; `codeman users add|passwd|list|rm` CLI. Off by default is byte-identical to single-user. Note: multi-user separates workspaces for a trusted team; it is not a security boundary (all sessions share the host OS account), so pair it with Docker cases for real isolation.
+  - **Docker cases (shipped 1.4.0/1.4.1).** A case can run inside an isolated per-case container (any of the five CLI backends), with one-click "Run in Docker" quick-create, durable in-container tmux that survives Codeman restarts and resumes conversations after container stops, hardened container creation (cap-drop ALL, no-new-privileges, non-root, memory/pid limits, never privileged, never the docker socket), commit-safe seeded credentials, config-drift detection, GPU passthrough, and portable export/import bundles to move a whole case between machines.
+  - **1.6.0 highlights.** Remote SSH cases with durable remote tmux (survives SSH drops, auto-reconnect, shared multi-client attach, discover + attach with detach-not-kill); the Cmd+K session palette and unified Session Manager with pinning, cross-device tab order, and first/last prompt search; full-scrollback replay; and the multi-user permission downgrade now threading through to remote launch/attach.
+
+## 1.6.0
+
+### Minor Changes
+
+- Remote tmux durability, Session Manager polish, and an opt-in Cron button.
+
+  **Remote sessions: durability, discovery, and auto-reconnect** (PR #156 by @aakhter, COD-104 to COD-109)
+  - Durable remote launches survive an SSH drop: the agent runs inside `tmux -L codeman-remote new-session -A` on the remote host, and reconnecting lands back in the same session.
+  - Discover + attach: a "Discover existing sessions" action per remote host lists `codeman-*` tmux sessions on the host's canonical socket (started by the remote's own Codeman or another instance) and attaches to one. Attached (non-owned) sessions detach on tab close, never kill; a structural early-return in `killSession()` guarantees no remote `kill-session` can ever be issued for a session Codeman doesn't own (COD-105).
+  - Shared/collaborative sessions: per-session `window-size latest` so concurrent clients at different viewports don't clamp each other, plus a "shared - N clients" badge in discovery results (COD-106).
+  - Auto-reconnect watcher: a bounded-backoff (5s to 5m, ~6 attempts) watcher detects a dead remote pane and reattaches the still-running remote tmux session; intentional kills/detaches are guarded and never revived. Kill-switch setting `remoteAutoReconnect` (default on). SSE `remote:sessionDropped`/`sessionReconnected`/`reconnectExhausted`, with a manual Reconnect toast after exhaustion (COD-108).
+  - Owned durable sessions propagate `kill-session` to the remote on close (COD-109); the remote tmux prereq probe is skipped under the test runner (COD-104).
+  - All ssh command lines continue to flow through the single shell-safe `buildSshConnectionArgs()` (COD-107). New design doc: `docs/remote-sessions.md`.
+  - Maintainer additions: the discovery endpoint is admin-gated in multi-user mode, and the remote launch/attach chooser threads the multi-user permission downgrade (`claudeMode`/`allowedTools`) through to the remote agent.
+
+  **Session Manager: pinning, cross-device ordering, name/prompt retention** (PR #157 by @aakhter, COD-131/139/140/142/143/145)
+  - Session pinning: pin a session to the top of the Session Manager list (`POST /api/sessions/:id/pin`, `session:pinned` SSE, amber highlight + pin glyph). Pinned group orders most-recently-pinned first (COD-139).
+  - Pinned sessions survive kill: killing a pinned session demotes its record to a lightweight stopped entry instead of removing it, so it stays visible and resumable; cleanup skips pinned records (COD-142). The pin route also works on these persisted-only records, so a pinned-then-killed session can always be unpinned.
+  - Cross-device tab order: tab order syncs via server state (`PUT /api/session-order`, `session:orderChanged` SSE, persisted in `state.json`); the pushing device wins and server-only ids fall to the end, never dropped (COD-131).
+  - Resuming from the Session Manager keeps the session's original name instead of always synthesizing a fresh `w<N>-<dir>` one (COD-143).
+  - firstPrompt backfill for sessions whose Codeman id is not the transcript UUID (claudeSessionId join, then newest transcript in the same workingDir), and the most recent prompt is shown alongside the first and included in search (COD-140/145).
+
+  **Cron button now opt-in** (hidden by default)
+  - The Cron footer-toolbar button follows the same opt-in pattern as the Session Manager / Away Digest / File Viewer buttons: hidden by default, enable per device under App Settings -> Display -> Header Displays. Cron jobs themselves are unchanged.
+
+  Also: `docs/remote-sessions.md` synced with the shipped `-L codeman-remote` / `codeman-ssh-<id8>` naming.
+
+## 1.5.1
+
+### Patch Changes
+
+- Docker session-mode deep-review fixes — the work intended for the skipped **1.4.2**, now merged onto the 1.5.x line — plus a recap of the multi-user mode shipped in 1.5.0.
+
+  **Docker resume actually works now.** `DockerCase.lastClaudeSessionId` was read at quick-start but never written, so the documented resume-after-container-stop never fired. Claude-mode docker panes now pin a deterministic conversation id (`claudeDockerPaneCommand()`): a fresh launch runs `claude --session-id <id> || claude --resume <id>` (a duplicate `--session-id` exits 1 "already in use", so the fallback resumes after a container stop/reboot — verified CLI behavior), an explicit resume runs `--resume <rid> || --session-id <sid>` so a stale id never dead-panes. The id is persisted at launch and again on hook / last-response conversation-id adoption. Verified end-to-end across a `docker stop` + relaunch and a full container recreate.
+
+  **Config-drift detection + recreate (was documented but entirely missing).** The `codeman.confighash` label was stamped but never read, so docker-host config edits silently never applied. Quick-start now compares via `checkDockerConfigDrift()` and refuses a drifted launch with `CONFLICT`; the UI confirms and calls the new `POST /api/docker-cases/:name/recreate` (refused while the case has live sessions), then relaunches with the new config. New SSE event `docker:containerRecreated`.
+
+  **Model picker now applies to docker sessions.** `modelOverride` was absent from `QuickStartSchema`, so the App Settings Claude Model choice was silently inert for docker runs. It is now accepted and applied via `updateCaseModel` for local and docker quick-starts (still rejected for remote, where the settings file would land on the wrong machine).
+
+  **Import hardening.** `importDockerBundle` validates the untrusted cross-machine manifest before trusting any field (`validateImportManifest`: engine/image/containerWorkdir/network/caseName/schemaVersion — a hostile `engine` could previously select the probe binary); the outer bundle tar gets the same member-traversal guard as the inner workspace tar; the quarantine image tag derives from the schema-validated case name.
+
+  **Remote-daemon correctness.** All docker probes and the base-image auto-build now honor a host's `context`/`daemonHost` (`dockerEngineArgv`) instead of always probing the local daemon.
+
+  **Smaller fixes:** commas are rejected in docker workspace/workdir/destination paths (a comma corrupts the `--mount type=bind,src=…` CSV spec, which shell escaping cannot protect); a dead `this.escapeHtml` reference in the exports refresh is fixed; `docker:importComplete` / `docker:containerRecreated` get frontend SSE listeners so other open tabs refresh; the File Viewer header button is hidden on phone headers like its siblings.
+
+  **Docs.** CLAUDE.md + READMEs synced with the current feature set, including a full zh-CN README re-translation.
+
+  **Multi-user mode (recap — shipped in 1.5.0).** Opt-in named users (`--multiuser` / `CODEMAN_MULTIUSER=1`, off by default) with per-user case spaces and full ownership scoping of sessions, cases, cron jobs, scheduled runs, search, file previews, and real-time SSE/WS streams. Non-admin users default to Claude's classifier-guarded `--permission-mode auto`; raw shell mode, cron `launchCommand`, skip-permissions, and the Codex/Gemini bypass switches require an explicit per-user `canBypassPermissions` grant. Machine-level resources are admin-only. Admin API (`/api/admin/users*`) with one-time passwords, last-admin invariants, and an append-only audit log; self-service `/api/me` + password change; and a `codeman users add|passwd|list|rm` CLI. Off by default is byte-identical to single-user. Note: multi-user separates workspaces for a trusted team; it is not a security boundary between mutually-distrusting users (all sessions share the host OS account) — pair with Docker cases for real isolation.
+
+## 1.5.0
+
+### Minor Changes
+
+- 0ab2416: Opt-in multi-user mode (`--multiuser` / `CODEMAN_MULTIUSER=1`, off by default).
+
+  Named users with individually scrypt-hashed passwords in `~/.codeman/users.json`, per-user case spaces under `~/codeman-users/<name>/cases`, and ownership scoping of sessions (create/list/delete/mutate, incl. bulk delete), cases, cron jobs + run history, scheduled runs, search, file previews, session history, away digest, subagent/workflow monitors, and real-time SSE/WS streams (including the debounced session/task update path, clipboard, and push notifications). A non-admin's `workingDir` is realpath-confined to their own space at every spawn/link path (session create, quick-start, cron create/fire, scheduled runs, case link/docker-link, docker import). Non-admin users default to Claude's classifier-guarded `--permission-mode auto`; raw shell mode, cron `launchCommand`, skip-permissions, and the Codex/Gemini bypass switches require an explicit per-user `canBypassPermissions` grant (enforced at every spawn site incl. one-shots, plan generation, scheduled runs, and remote launches). Machine-level resources (remote/Docker hosts + host reads, mux sessions, orchestrator, tunnel, self-update, settings) are admin-only. Admin API (`/api/admin/users*`) with one-time passwords, last-admin invariants (validated before any teardown), and an append-only audit log; self-service `/api/me` + password change; a frontend admin Users tab + change-password modal; and `codeman users add|passwd|list|rm` CLI. Also adds a global `auto` Claude startup permission mode. When off, behavior is byte-identical to single-user.
+
+  Auth hardening: the login throttle verifies the password before consulting the per-account failure bucket (a correct password can never be locked out); the `mustChangePassword` lockbox covers the WebSocket terminal; the cookie fast-path re-validates identity against the store each request (so a CLI/admin delete/disable/demote takes effect promptly); a role/grant change revokes the target's sessions. (Known limitation: a bare CLI `codeman users passwd` reset — no delete — does not by itself revoke an already-active cookie until it expires; use `codeman users rm`, the admin API, or a restart to force-revoke.) Data-integrity hardening: the store distinguishes a missing users file from a corrupt/unreadable one (so a transient read error can't overwrite all accounts) and writes via a unique per-process temp file; the earlier fire-and-forget `touchLastLogin` corruption race is serialized.
+
+  Note: multi-user mode separates workspaces for a trusted team; it is not a security boundary between users (all sessions share the host OS account). Pair with Docker cases for real isolation.
+
+## 1.4.1
+
+### Patch Changes
+
+- **Docker session mode** hardening + fixes, plus a File Viewer header button.
+
+  **What Docker session mode is** (recap): a case can run inside an isolated, hardened Docker container instead of on the host, and any of the CLI backends (Claude, Codex, Gemini, OpenCode, or a plain shell) runs inside it. It is a location overlay on cases — not a new session mode — and the container analog of remote-SSH cases: a local tmux pane `docker exec`s into a durable in-container tmux, with exactly one long-lived container per case that multiple sessions share. The workspace, credentials, and conversation transcripts are bind-mounted so the agent is authenticated and resumable; containers are hardened by default (`--cap-drop ALL`, `--security-opt no-new-privileges`, non-root, pids/memory caps, `--init`, never `--privileged` or the docker socket) and export-safe. Start one with the one-click "Run in Docker" checkbox on Create Case, or the Docker tab for full control.
+
+  This release fixes the rough edges found running it for real:
+
+  Docker cases:
+  - **Seamless Claude auth in containers**: `~/.claude.json` is no longer bind-mounted as a single file (a mount point that broke Claude's atomic-rename config writes — forcing re-auth and, via failed in-place writes, corrupting the host `~/.claude.json`). It is now seeded as a writable, onboarding-complete copy, so a docker session boots straight to the prompt (no theme picker, login, or folder-trust prompt).
+  - **Claude-state isolation**: containers no longer bind-mount the whole `~/.claude` directory (which wrote backups/tasks/teams/settings back into the host). Only `~/.claude/projects` transcripts are shared (host watchers + `--resume`); credentials, settings, and stats-cache are seeded as writable copies; everything else stays container-local.
+  - **Codex/Gemini/gcloud/opencode isolation**: same treatment — codex shares `sessions/` + `history.jsonl` (response-viewer + resume) and seeds `auth.json`/`config.toml`; gemini/gcloud/opencode are whole seed-copies. Containers never write their credential state back into the host dirs.
+  - **Base image auto-builds on first use**: a missing `codeman/agent:base` no longer blocks case creation or launch; it builds locally on first use (concurrency-safe, with SSE progress toasts).
+  - **UTF-8 locale**: containers set `LANG`/`LC_ALL=C.UTF-8` so tmux renders Claude's box-drawing correctly (fixes `qqqq` line artifacts).
+  - **Create Case UI**: larger, collapsed-by-default "Run in Docker" settings with a shorter hint; dockerized cases show a short `(docker)` tag (or the custom host id) in the case menus.
+  - **Tab naming**: docker/remote (and codex/gemini/opencode) sessions now follow the `w<n>-<case>` convention instead of `codeman-<id>`.
+
+  Other:
+  - **File Viewer header button** (opt-in via App Settings, Header Displays): toggle the file browser panel from the header.
+  - Fixed a timezone-boundary flaky test in the away-digest route suite.
+
+## 1.4.0
+
+### Minor Changes
+
+- Add **Docker session mode**: a case can now run inside an isolated Docker container instead of on the host, with configurable network / resource / credential settings, multiple sessions sharing one per-case container, and one-click export to move a container (toolchain + workspace) to another machine.
+  - Docker is a location overlay on cases (not a new session mode), mirroring the remote-SSH feature: a local tmux pane runs `docker exec -it` into a durable in-container tmux server. The container is scoped to the case (`codeman-case-<name>`), so multiple sessions share it; killing one session never stops the shared container.
+  - New `/api/docker-hosts` CRUD, `/api/cases/docker-link`, and a `/api/quick-start` docker branch. Create Case gains a **Docker** tab. Base image is built locally via `scripts/build-agent-image.mjs` (node + claude/codex/gemini/opencode + tmux, secret-free, arbitrary-uid-writable HOME).
+  - Hardened by default: `--cap-drop ALL`, `--security-opt no-new-privileges`, non-root, `--pids-limit`, `--memory`==`--memory-swap`, `--init`; never `--privileged` or the docker socket. Convenient credential default bind-mounts host `~/.claude` etc. read-write (never captured by `docker commit`); a sealed profile is opt-in.
+  - Two-layer durability: reconnect after a Codeman restart reattaches the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript via `--resume`.
+  - Export / import: full-image (`docker commit` + `save` + workspace tar + manifest) or workspace-only, to one portable `.codeman-container.tgz`; import validates checksums, guards path traversal, and re-tags the loaded image into a quarantined namespace. Instance-scoped boot reaper cleans orphaned containers. New `docker:*` SSE events. Docs in `docs/docker-cases.md`.
+  - Robustness: sets `CLAUDE_CODE_TMPDIR` in the container so claude launches regardless of workspace path. In-container hooks require the server to be reachable from the container (documented); on a loopback-only bind, idle detection falls back to output-based.
+
+  Also wire session, away-digest, and cron header-button visibility toggles in App Settings.
+
+## 1.3.5
+
+### Patch Changes
+
+- a842f2d: fix(auth): slide the session cookie so active users aren't logged out
+
+  Re-issue the `codeman_session` cookie on every authenticated request so the
+  browser cookie lifetime tracks the server-side sliding TTL (the session store
+  already uses `refreshOnGet`). Previously the cookie was only set on the Basic
+  Auth path with a fixed 24h lifetime from login, so the browser dropped it
+  mid-use; the next request arrived cookie-less, fell through to Basic Auth and
+  popped the native username/password dialog, perceived as a random logout while
+  actively working.
+
+## 1.3.4
+
+### Patch Changes
+
+- Fix "Run Shell" not switching the terminal to the newly created shell session. Clicking Run Shell created the shell tab but left the previous session's terminal on screen, so you had to manually click the new tab to actually enter it. Root cause: `runShell()` pre-set `activeSessionId` to the new session's id right before calling `selectSession()`, and `selectSession()` early-returns when the requested id already matches the active one, so it skipped the terminal buffer load, tab activation, and focus. Removed the premature assignment in both the local and remote-SSH shell branches so `selectSession()` runs to completion (matching `runClaude`/`runCodex`/`runGemini`/`runOpenCode`, which already avoid this). Verified end-to-end in a real browser with a negative/positive control.
+
+## 1.3.3
+
+### Patch Changes
+
+- Fix terminal scroll-back in Claude sessions, especially on macOS trackpads (#154).
+  - **Deterministic CLI version detection.** `cliVersion` was often `undefined` because it was scraped from the `Claude Code vX.Y.Z` startup banner, which newer Claude Code builds (2.1.187+) don't reliably print and resumed sessions never show. With the version unknown, wheel-forwarding to Claude's transcript was silently disabled — and since repaint-mode Claude keeps no local terminal scrollback, scrolling up reached nothing. A new `getClaudeCliVersion()` probe (`claude --version`, cached, local-only) seeds the version at session start so forwarding engages. Restored sessions pick it up on restart.
+  - **Trackpad Shift+scroll.** The wheel handler now reads the dominant axis, so a macOS trackpad's Shift+two-finger scroll — which the browser reports as horizontal `deltaX` — reaches xterm's local scrollback instead of collapsing to a fixed one line per tick.
+  - **Opt-out setting.** New per-device App Settings → Input → "Wheel Scrolls Local History" (default off) pins the plain wheel to local scrollback (the pre-#144 behavior) for shell and other non-repaint sessions.
+  - **No more "queued bytes" flicker on scroll.** Wheel-scroll reports now use a fire-and-forget send path (seq-less input frame) instead of the durable exactly-once input queue, so they no longer appear in the pending-bytes connection indicator or churn localStorage. Keystrokes, taps, and clicks still use the durable queue.
+
+## 1.3.2
+
+### Patch Changes
+
+- Make the Cron Jobs modal fully skin-aware and consistent with App Settings' design language.
+  - **Fix white dropdowns:** `.form-select` had no `appearance` reset and the app set no `color-scheme`, so native `<select>` fields rendered as white OS widgets that ignored the active skin. Selects now use `appearance: none` with an opaque `var(--bg-input)` fill, a `var(--border)` outline, and a custom chevron, so they follow the skin (daylight `#202833`, OG `#1a1a1f`). This is on the shared `.form-select` class, so App Settings, Cron, and every other select match and are fixed together.
+  - Set `color-scheme: dark` on `:root` so native select option popups, date/time pickers, and scrollbars render dark across all three (dark) skins instead of flashing white.
+  - Themed the Cron date/time inputs with `var(--bg-input)` / `var(--border)` instead of hardcoded values.
+  - Fixed the Cron toolbar: "+ New Job" / "Refresh" and the footer Save / Cancel now use the full `btn-toolbar` size (matching the App Settings footer), with a wider gap and a divider under the toolbar for better spacing.
+
+## 1.3.1
+
+### Patch Changes
+
+- Redesign the Cron Jobs modal to match the App Settings styling, and fix a bug that left its create form fully expanded.
+  - **Fix:** the cron modal's "New Cron Job" form and all of its conditional rows (Launch Command, Prompt File Path, and the once/interval/daily/weekly schedule fields) never actually collapsed — there is no global `.hidden` utility in the stylesheet and the cron modal never scoped its own, so the form opened fully expanded with every field visible at once. Added a scoped `#cronModal .hidden` rule; the form now stays collapsed until "+ New Job" and only shows the fields relevant to the selected agent type, prompt source, and schedule type.
+  - Sectioned the create/edit form into Basics / Prompt / Schedule / Options with the same section-header dividers used in App Settings, and increased row spacing.
+  - Styled the agent-type / prompt-source / input-mode / schedule-type dropdowns and the datetime-local / time inputs to share the bordered, rounded, focus-ringed field look.
+  - Converted the "Auto-close previous run's session" and "Enabled" toggles into App-Settings-style cards (label + description on the left, compact switch on the right).
+  - Replaced the raw weekday checkboxes with pill toggles that fill with the accent color when selected.
+  - Restyled the job list rows as hover-highlighted cards with pill badges (agent type, schedule, disabled) and right-aligned actions, and gave the modal a divider-topped Cancel / Save footer.
+
+## 1.3.0
+
+### Minor Changes
+
+- Community release: 16 contributor PRs reviewed (multi-agent adversarial review), fixed, and merged. Thanks to @aakhter, @TeigenZhang, @chatgptkrylor, @kvncrw, and @pirronewantlux529-coder!
+
+  **New features**
+  - **Cron jobs** (#141, @chatgptkrylor): recurring scheduled jobs (once/interval/daily/weekly) that spawn a session and send a prompt when due — CRUD + run history (`/api/cron/*`), ⏰ modal UI, per-job concurrency policy and `autoClosePreviousSession` lifecycle, pure unit-tested next-run math. Distinct from the legacy `ScheduledRun`.
+  - **Remote host SSH cases** (#145, @aakhter): link cases on remote hosts (`remote-hosts.json`/`remote-cases.json`), launch sessions over ssh into a durable remote tmux (dedicated `-L codeman-remote` socket; adoption-safe naming), per-host command overrides, injection-guarded schemas, remote tmux probe + ConnectTimeout, remote kill on delete, recovery-safe persistence.
+  - **Command-K session palette + searchable case picker + shortcut registry** (#146, @aakhter): Ctrl/Cmd/Alt+K fuzzy session palette with "Browse all sessions" Session Manager; searchable quick-start case picker (remote-aware labels); rebindable shortcut registry with App Settings → Shortcuts tab and Ctrl+? overlay.
+  - **Unified session list** (#139, @aakhter): `GET /api/sessions/unified` merges live/persisted/lifecycle/transcript sessions into one deduped list (resumed sessions fold via claudeSessionId alias map).
+  - **Unified Session Manager UX** (#153, @aakhter): unified welcome list with mode/LIVE badges + per-row kebab menu, `projectKey` plumbing for "View all in this folder", SSE-driven live list refresh, desktop Session Manager header button.
+  - **Full-scrollback replay** (#148, @aakhter): page reload replays the entire tmux scrollback (`?full=1`, bounded capture with proper maxBuffer) with CRLF normalization for shell panes.
+  - **WebSocket resilience** (#149, @aakhter): reconnect with preserved exponential backoff, per-tab connection identity (multi-tab safe), ACK re-drive, and a truthful connection chip (WS/HTTP/reconnecting states).
+  - **PTY-exit circuit breaker + TMUX scrub** (#147, @aakhter): rapid PTY crash-loops trip a breaker (SSE + critical push notification; explicit-restart-only reset); inherited TMUX vars are scrubbed so Codeman-in-tmux doesn't nest.
+  - **Codex generated-artifact attachments** (#150, @aakhter): codex sessions surface `Saved to: file://…` outputs as attachment cards (realpath-anchored trust, codex-mode-gated, jpg/gif/webp thumbnails).
+  - **Codex response viewer** (#152, @pirronewantlux529-coder): the eye button now works for Codex sessions via 4-layer rollout resolution (history pin → originator → resume-UUID → cwd) with dedup + injected-context filtering.
+  - **HEIC paste conversion** (#151, @aakhter): iPhone HEIC pastes convert to JPEG server-side in a worker thread (concurrency-capped, 64MP decompression-bomb guard, magic-byte detection for mislabeled Android HEIFs). Deps: heic-decode + jpeg-js.
+  - **WebGL renderer toggle** (#140, @kvncrw): per-device setting to switch xterm between WebGL and DOM renderers, cooperating with the GPU-stall auto-fallback marker.
+  - **Raised terminal history defaults** (#138, @aakhter): tmux history-limit 50k→100k lines, PTY buffer 2MB/1.5MB→32MB/24MB (env-clamped so trim always stays below max).
+
+  **Mobile & input fixes**
+  - CJK input loss fixes: IME state machine, focus routing, Android InputConnection recovery — with content-free diagnostics (#143, @TeigenZhang).
+  - Tap/click/wheel restored when the server strips mouse DECSETs — version-gated wheel passthrough (claude ≥ 2.1.187), link-click double-fire fix, Shift+wheel documented (#144, @TeigenZhang).
+  - Response-viewer readability on phones + iOS dvh viewport fix (#142, @TeigenZhang).
+
+  **Docs**: CLAUDE.md accuracy audit (18 verified fixes: security hook-bypass description, env-prefix allowlist, state-file inventory, watcher/function names, counts) + documentation for all new subsystems. README gains a user walkthrough (#141).
+
+  All PRs went through adversarial multi-agent review; ~60 verified findings (including 12 blockers) were fixed on the contributors' branches before merge. Full test suite green: 3,400+ tests.
+
+### Patch Changes
+
+- bf36eb0: Add a **WebGL Renderer** toggle to Settings → Appearance (desktop). WebGL stays on by default; turning it off forces the DOM renderer for users who hit GPU glitches, without needing the `?nowebgl` URL param. Turning it back on (or `?webgl=force`) clears any stale auto-fallback marker. The existing mobile skip and long-task auto-fallback safety net are unchanged. The skip decision is factored into a pure, unit-tested `shouldSkipWebGL()` helper.
+
+## 1.2.2
+
+### Patch Changes
+
+- Centralize terminal history/scrollback/buffer retention limits into config (PR #137, COD-80).
+
+  New `src/config/terminal-history.ts` is now the single source of truth for the terminal scrollback lines, tmux `history-limit`, and server PTY buffer byte caps that were previously scattered as hardcoded literals across `buffer-limits.ts`, `tmux-manager.ts`, and `session.ts`. Each value is overridable (env var or the settings object) and bounds-clamped via a pure `resolveTerminalHistoryConfig()`.
+
+  This change is behavior-neutral: the defaults intentionally match the prior hardcoded values (tmux history-limit 50,000; terminal scrollback 50,000; PTY buffer max 2 MB; trim 1.5 MB) and the existing `CODEMAN_MAX_TERMINAL_BUFFER` / `CODEMAN_TRIM_TERMINAL_TO` env overrides are preserved, so runtime behavior is unchanged on its own. It is the mechanism half of a stacked change; a follow-up raises the defaults.
+  - `buffer-limits.ts` sources `MAX_TERMINAL_BUFFER_SIZE` / `TRIM_TERMINAL_TO` from the resolver.
+  - `tmux-manager.ts` uses `DEFAULT_TMUX_HISTORY_LIMIT` in place of the hardcoded `history-limit 50000`, gains `setHistoryLimit()` (mux-interface + impl) so a settings change applies to live sessions, and re-applies the limit on `respawnPane` so it survives a respawn.
+  - `session.ts` threads a per-session `tmuxHistoryLimit` into the tmux spawn calls; `server.ts` exposes `getTerminalHistoryConfig()` on the route ctx and `system-routes.ts` applies a changed `tmuxHistoryLimit` to live sessions immediately.
+  - `schemas.ts` adds four optional, bounds-clamped settings keys (`terminalScrollbackLines`, `tmuxHistoryLimit`, `terminalBufferMaxBytes`, `terminalBufferTrimBytes`) with a `trim <= max` cross-field check.
+  - New tests: `test/terminal-history.test.ts` (resolver defaults / clamping / trim<=max / non-number fallback) and `test/terminal-history-schema.test.ts` (settings-schema validation).
+
+## 1.2.1
+
+### Patch Changes
+
+- Fix local echo on iOS Safari when switching into a tab whose session already has output. The on-screen-keyboard "heal" (refit + scroll-to-bottom + overlay re-render + one-shot resize) only ran on a keyboard visibility transition, so switching into a tab while the keyboard was already up never triggered it — leaving the local-echo overlay rendering against stale, off-bottom terminal state. Typed characters were invisible (or mispositioned at the cursor row, far below the actual `❯` prompt) until the user manually hid and re-showed the keyboard. `selectSession` now replicates that heal when the keyboard is already visible, so local echo paints correctly on the first keystroke after a keyboard-up tab switch.
+
+## 1.2.0
+
+### Minor Changes
+
+- Merge four feature PRs and harden them for release.
+
+  **Gemini run mode (PR #134, COD-36)** — a third external-CLI backend alongside Codex and OpenCode (`SessionMode` adds `'gemini'`). New `gemini-cli-resolver.ts`, `buildGeminiCommand()` (`--skip-trust`, `--approval-mode {default|auto_edit|yolo|plan}` defaulting to `yolo`, `--model`, `--resume`), `setGeminiEnvVars()` (socket-scoped `tmux setenv` of `GEMINI_*`/`GOOGLE_*` auth incl. Vertex AI), `GET /api/gemini/status` with an install hint (`npm install -g @google/gemini-cli`), run-mode dropdown + welcome "Run Gemini" button + "Run GM" label, `GeminiConfigSchema`, and `GEMINI_*`/`GOOGLE_*` added to the env-override allowlist. Requires tmux (no PTY fallback), like Codex.
+
+  **Cross-session search (PR #133, COD-113)** — `GET /api/search?q=&types=&limit=` federates an in-memory search across session metadata, run-summary events, and attachment-history file entries (substring match, hard caps, no FS reads); history-panel search box in the frontend.
+
+  **Away digest (PR #136, COD-41)** — `GET /api/away-digest` aggregates "what happened while you were away" (lifecycle log, run summaries, live sessions, daily token stats, recent subagents) into categorized sections behind a header-button modal (hidden on phones).
+
+  **Ralph todo-config (PR #135, COD-79)** — per-session `maxTodos` and `todoExpirationMinutes` via `POST /api/sessions/:id/ralph-config`; now persisted in `RalphTrackerState` and read back into the Session Options modal (mirrors `maxIterations` round-trip).
+
+  **Review fixes applied on merge:**
+  - Gemini: fixed two `{success,data}` envelope bugs in `runGemini()` (status check and new-session selection) that made the Run-Gemini button non-functional; fixed `setGeminiEnvVars()` to use the socket-scoped tmux command so Google-auth env injection actually reaches the session.
+  - Gemini parity: tab-mode badge, kill-dialog label, `codeman doctor` registry entry, `isGeminiAvailable` barrel export, `COLORTERM=truecolor`, and alt-screen/scrollback stripping (Ink TUI, like Codex/Claude).
+  - Restored four envelope-shape test assertions weakened during the Gemini PR; added a `runGemini()` regression test covering the envelope path.
+  - Ralph todo-config values now persist across restart and read back correctly instead of always reverting to defaults.
+
+## 1.1.17
+
+### Patch Changes
+
+- Fix the connection indicator flashing "Sending 1B…" on every keystroke. The reliable input-delivery layer (1.1.16) marks each keystroke as briefly pending until its ACK arrives a few milliseconds later, which made the indicator flash on every character while typing on a healthy connection. The indicator is now hidden whenever the connection is healthy and only appears for an actual problem (reconnecting/offline), where it still shows the queued byte count so you know buffered input will be sent.
+
+## 1.1.16
+
+### Patch Changes
+
+- Mobile image uploads, reliable input delivery, and gesture window dragging.
+
+  **Mobile image uploads (camera-roll picker / drag-drop / paste).** The "🖼 Image" button now handles real photo batches: up to 20 images per batch uploaded with bounded concurrency and a live "Uploading N/M…" progress toast (with a summary of successes, failures, and whether the 20-cap trimmed the selection). The per-file limit is raised from 10MB to 50MB (`MAX_PASTE_IMAGE_BYTES`, env-overridable via `CODEMAN_MAX_PASTE_IMAGE_BYTES`) so full-resolution phone photos and large screenshots are accepted. Very large images are downscaled to ≤4096px on the longest edge before upload, fixing iOS Safari's ~16.7M-px `<canvas>` limit that previously made huge photos fail to re-encode. Also fixes a latent concurrency bug the batch path exposed where the first parallel uploads to a session raced on creating `.claude-images/` and failed with EEXIST.
+
+  **Reliable, exactly-once input delivery.** A "sent" prompt could be silently lost on a flaky connection (e.g. a train): a half-open WebSocket accepts `ws.send()` without error while discarding the frame, and nothing was queued or resent. Input is now recorded durably (localStorage) with a stable clientId + monotonic per-session sequence before delivery, and only dropped once the server ACKs it — delivered over the WebSocket (acked via `{t:'ia',seq}`) or, when the socket is down, over POST in order. A 2s sweep force-reconnects a half-open socket; pending input survives reconnects and page reloads. The server applies each `(clientId, seq)` at most once (`Session.shouldApplyInput`), so an at-least-once resend can never type the prompt twice. Untagged input (curl/legacy) is unchanged. See `docs/reliable-input-delivery.md`.
+
+  **Gesture beta: drag agent windows.** With the camera hand-tracking overlay, you can now pinch and move the floating subagent and ultracode run/transcript windows. They keep their glowing connector line to the session tab while moving and can travel across a multi-monitor seam.
+
+## 1.1.15
+
+### Patch Changes
+
+- Security: harden all frontend inline `onclick`/`ondblclick` handlers against a stored-XSS double-context bug.
+
+  Many inline handlers interpolated values as `'${escapeHtml(value)}'` — a JavaScript string literal sitting inside an HTML attribute. The browser HTML-decodes the attribute value _before_ parsing the handler source, so `escapeHtml`'s `&#39;` reverts to a literal `'` and a quote-bearing id/name/path/URL breaks out of the JS string into executable code. `escapeHtml` alone is insufficient for this JS-string-within-HTML-attribute context.
+
+  All affected handlers now use `escapeHtml(JSON.stringify(value))`: `JSON.stringify` JS-encodes and quote-wraps the value, then `escapeHtml` handles the HTML-attribute layer, so the value round-trips as a single inert string argument.
+  - ultracode run/agent cards and minimized-tab badges (`ultracode-panel.js`, `ultracode-windows.js`) — PR #132.
+  - Session tabs (click/rename/gear/detach/close), notifications, subagent windows + dropdowns, the agents/tools/log-viewer/image-popup panels, mux-session monitor rows, and case-management buttons (`app.js`, `notification-manager.js`, `subagent-windows.js`, `panels-ui.js`, `session-ui.js`).
+  - Two non-`escapeHtml` variants of the same class: a pre-escaped mux-session id in `panels-ui.js` (`selectSession`/`killMuxSession`) and a fully raw, unescaped `phase.id` in `orchestrator-panel.js` (`orchestratorSkipPhase`/`orchestratorRetryPhase`).
+
+  The most realistic exploitation vector was file paths in the project-insights log-viewer link, since filenames can legally contain a single quote. Purely numeric interpolations and developer-literal handler strings were left unchanged.
+
+## 1.1.14
+
+### Patch Changes
+
+- Ultracode (Workflow-tool) floating windows — agent transcripts in-page, and minimize-to-tab.
+  - **Agent transcripts open in-page, connected, instead of a detached browser popup.** Clicking an agent card (in a run window or the dock panel) now opens the agent's live transcript as its own draggable floating window, tied by a connector line to its parent run window (falling back to the run's session tab if that window has since closed) — the same line idiom the run windows use. Re-clicking a card focuses the existing window; closing it removes the window and its line. (Previously this spawned a separate `window.open` browser popup.)
+  - **The window "−" button now minimizes into the originating session tab**, mirroring the subagent-window idiom. The window genie-animates into its tab and is tracked there; the tab shows an `ULTRA` badge whose hover/click dropdown lists each minimized item (🧬 run windows, 📄 agent transcripts). Click an item to restore its floating window, or dismiss it with ×. A run minimized while still active keeps tracking in the background and its badge auto-clears shortly after the run finishes. Both run windows and agent-transcript windows minimize into the same merged badge.
+  - Removed the old collapse-to-header behavior that the "−" button previously triggered (now superseded by minimize-to-tab).
+
+## 1.1.13
+
+### Patch Changes
+
+- Keep the `/compact` button in the extended (full) mobile keyboard accessory bar; only the simple bar drops it. (1.1.12 had removed it from both.)
+
+## 1.1.12
+
+### Patch Changes
+
+- Remove the `/compact` button from the mobile keyboard accessory bar. It had been reintroduced in 1.1.10; this removes the button from both the simple and full accessory-bar layouts (the underlying command handler is left in place as inert plumbing).
+
+## 1.1.11
+
+### Patch Changes
+
+- Ultracode (Workflow-tool) run visualization — much better live tracking.
+
+  While a run is in flight, the watcher previously showed empty agent slots ("agent N", 0 tokens, raw `wf_…` id as the title) because the detailed completion JSON only lands when the run finishes. The live path now enriches in-flight runs directly from the on-disk transcript tree:
+  - **Real per-agent stats mid-run** — tokens and tool-call counts are parsed from each `agent-<id>.jsonl` transcript (tool counts match the final accounting exactly; token totals land within ~1% of the completion value), with model and a prompt preview. All mtime-cached (transcripts, journal, and script meta) so idle polls do no extra reads.
+  - **Readable window/run title** — workflow name, summary, and phases are derived from the persisted `workflows/scripts/<name>-<runId>.js` instead of showing the raw run id.
+  - **Agent status colors** — done agents show green, working agents show yellow (this also fixes the run/agent status badges, which referenced undefined `--success`/`--warning` CSS variables and were rendering with no color).
+  - **Connector line** — the floating-window → session-tab line now uses the session-tab accent blue (was purple).
+  - **Click a run to open its floating window** — clicking a workflow in the dock panel opens (or focuses) its floating window with the connector line, in addition to the auto-popped windows.
+  - Agents are ordered by journal launch order; concurrent run-detail fetches are de-duplicated.
+
 ## 1.1.10
 
 ### Patch Changes

CLAUDE.md

@@ -2,17 +2,23 @@
 
 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 |
-|------|---------|
-| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
-| Type check | `tsc --noEmit` |
-| Lint | `npm run lint` (fix: `npm run lint:fix`) |
-| Format | `npm run format` (check: `npm run format:check`) |
+| Task        | Command                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dev server  | `npm run dev` (or `npx tsx src/index.ts web`)                                                                                                                       |
+| Type check  | `tsc --noEmit`                                                                                                                                                      |
+| Lint        | `npm run lint` (fix: `npm run lint:fix`)                                                                                                                            |
+| Format      | `npm run format` (check: `npm run format:check`)                                                                                                                    |
 | Single test | `npm test -- test/<file>.test.ts` (or `npx vitest run --config config/vitest.config.ts test/<file>.test.ts`) — ⚠ **never** run bare `npm test`, see Testing section |
-| Build | `npm run build` (esbuild via `scripts/build.mjs`, NOT tsc — `tsc --noEmit` is type-check only) |
-| Production | `npm run build && systemctl --user restart codeman-web` |
+| Build       | `npm run build` (esbuild via `scripts/build.mjs`, NOT tsc — `tsc --noEmit` is type-check only)                                                                      |
+| Production  | `npm run build && systemctl --user restart codeman-web`                                                                                                             |
 
 ## CRITICAL: Session Safety
 
@@ -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:
@@ -30,15 +43,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM
 
-The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an *absolute* URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an _absolute_ URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.
 
 ## COM Shorthand (Deployment)
 
-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":
+
 1. **Determine bump type**: `COM` = patch (default), `COM minor` = minor, `COM major` = major
 2. **Create a changeset file** (no interactive prompts). Write a `.md` file in `.changeset/` with a random filename:
+
    ```bash
    cat > .changeset/$(openssl rand -hex 4).md << 'CHANGESET'
    ---
@@ -48,21 +63,24 @@ When user says "COM":
    Detailed description of ALL changes since last release (not just the most recent commit — review full git log since last version tag)
    CHANGESET
    ```
+
    Replace `patch` with `minor` or `major` as needed. Include `"xterm-zerolag-input": patch` on a separate line if that package changed too.
+
 3. **Consume the changeset**: `npm run version-packages` (auto-bumps `package.json` files, updates `CHANGELOG.md`, runs `npm install --package-lock-only`, and verifies lockfile sync via `scripts/check-lockfile-sync.mjs` — all in one command; never hand-edit `CHANGELOG.md` or `package-lock.json` versions)
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
-5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
-6. **Wait for CI**: after `git push`, find the run with `gh run list -L 1 --json databaseId,headBranch -q '.[0].databaseId'` and watch it with `gh run watch <id> --exit-status`. Confirm all checks pass before considering the release done.
+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.1.10 (must match `package.json`)
+**Version**: 1.10.0 (must match `package.json`)
 
 ## Project Overview
 
 Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs.
 
-**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, and Codex (OpenAI) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex'`).
+**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), and Antigravity (`agy`, Google) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity'`).
 
 **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.
 
@@ -74,25 +92,29 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 `npm run dev` = dev server. Default port: `3000` (override with `--port` or the `CODEMAN_PORT` env var). To run this beta isolated alongside a prod Codeman, use `scripts/run-beta.sh` (sets `CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`). Commands not in Quick Reference:
 
-| Task | Command |
-|------|---------|
-| Dev with TLS | `npx tsx src/index.ts web --https` |
-| Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix) |
-| Bind a non-loopback host | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
-| Continuous typecheck | `tsc --noEmit --watch` |
-| Test coverage | `npm run test:coverage` |
-| Dead-code sweep | `npm run knip` (config in `knip.json`) |
-| Rebuild gesture overlay | `npm run build:gesture` (esbuild `packages/gesture-control/src/codeman/entry.ts` → `src/web/public/gesture/gesture-codeman.js`; commit the result) |
-| Gesture playground | `npm run dev` **in** `packages/gesture-control/` (standalone vite demo, fake tabs) |
-| Check public-asset formatting | `npm run check:public-assets` (prettier-checks `src/web/public/**` text assets; `scripts/check-public-assets.mjs`) |
-| Frontend JS syntax check | `npm run check:frontend-syntax` (`scripts/check-frontend-syntax.mjs`; runs in CI) |
-| CI-equivalent test sweep | `npm run test:ci` (full suite minus browser/perf — see Testing) |
-| Production start | `npm run start` |
-| Production logs | `journalctl --user -u codeman-web -f` |
+| Task                           | Command                                                                                                                                                                                                        |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dev with TLS                   | `npx tsx src/index.ts web --https`                                                                                                                                                                             |
+| Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix)                                        |
+| Bind a non-loopback host       | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
+| Continuous typecheck           | `tsc --noEmit --watch`                                                                                                                                                                                         |
+| 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 `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)                                                                                                                             |
+| Check public-asset formatting  | `npm run check:public-assets` (prettier-checks `src/web/public/**` text assets; `scripts/check-public-assets.mjs`)                                                                                             |
+| Frontend JS syntax check       | `npm run check:frontend-syntax` (`scripts/check-frontend-syntax.mjs`; runs in CI)                                                                                                                              |
+| CI-equivalent test sweep       | `npm run test:ci` (full suite minus browser/perf — see Testing)                                                                                                                                                |
+| Production start               | `npm run start`                                                                                                                                                                                                |
+| Production logs                | `journalctl --user -u codeman-web -f`                                                                                                                                                                          |
 
 **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
 
@@ -100,15 +122,16 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly. Both `aicodeman` and `codeman` bin aliases are installed (`package.json` `bin`)
 - **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
-- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` 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
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` / `ANTIGRAVITY_*` 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, and Codex (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts` / `codex-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward all prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
-- **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. Real bugs caused: 0.6.4 (`durationMinutes` for ∞ respawn), and the same shape pattern hit `opusContext1mEnabled` in 0.6.3
-- **`xterm-zerolag-input` is 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:50` (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_*` vs `ANTIGRAVITY_*`) 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)
+- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
+- **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.
 
@@ -116,32 +139,35 @@ 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/usage-limit-patterns.ts`, `src/usage-telemetry.ts` | |
-| **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★ | |
-| **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
-| **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
-| **Orchestrator** | `src/orchestrator-loop.ts`, `src/orchestrator-planner.ts`, `src/orchestrator-verifier.ts` | Read `docs/orchestrator-loop-architecture.md` first |
-| **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` | |
-| **Attachments** | `src/attachment-registry.ts`, `src/attachment-magic.ts`, `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` (16 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` | |
-| **Frontend** | `src/web/public/app.js` (~4K lines, core) + 6 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`, `sanitize-html.js` — DOMPurify mXSS allowlist, COD-56) + 8 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `ultracode-panel.js`, `settings-ui.js`, `panels-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` | `ultracode-windows.js` = floating run windows w/ tab connector lines (additional to the dock panel) |
-| **Types** | `src/types/index.ts` (barrel) → 16 domain files (incl. `workflow-run.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) + 25 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/` — 14 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`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-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).
+**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).
 
 ### Data Flow
 
@@ -152,77 +178,117 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Key Patterns
 
-**Input**: `session.writeViaMux()` for programmatic input — tmux `send-keys -l` (literal) + `send-keys Enter`. Single-line only.
+**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 under a tunnel) 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, `showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the `statusLineTelemetry` flag on session create). A chip shown without telemetry renders `—` forever. 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`.
 
-**External CLI modes (OpenCode, Codex)**: `isExternalCliMode()` in `session.ts` 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). Both modes **require tmux — no direct PTY fallback** — because secrets are injected via `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` 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); tmux exports `COLORTERM=truecolor` + unsets `NO_COLOR` (other modes unset `COLORTERM`); availability via `GET /api/codex/status` — session/quick-start routes fail with `OPERATION_FAILED` and an install hint (`npm install -g @openai/codex`) when the binary is missing. Frontend: run-mode dropdown → `runCodex()` in `session-ui.js` ("Run CX" label), App Settings → Codex CLI tab; Respawn/Ralph options are Claude-only, so session options open on the Summary tab for external CLI sessions. Tests: `test/run-mode-ui.test.ts` (vm-sandbox harness, no real DOM).
+**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 + 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`
+
+**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)
+
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity)**: `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 four **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)
+
+**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)
+
+**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`.
+**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)
 
-**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.
+**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)
 
-**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.
+**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)
 
-**Ultracode / Workflow-run visualization** (opt-in `showUltracodeAgents`, default OFF; released 1.1.2): the Workflow tool ("ultracode") writes a run-state JSON per run at `~/.claude/projects/<projHash>/<sessionUuid>/workflows/wf_*.json`. `workflow-run-watcher.ts` (STANDALONE — deliberately never imports/touches `subagent-watcher.ts`; disjoint directory tree, separate singleton) globs that tree via periodic poll + per-run chokidar watcher with per-file mtime skip, and broadcasts SSE `workflow:run_discovered`/`run_updated`/`run_removed`. The watcher is only started when the setting is on (`server.ts` gates on `showUltracodeAgents`). 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 the same `showUltracodeAgents` setting), 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. Types: `src/types/workflow-run.ts`. Config: `src/config/workflow-config.ts`.
+**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)
+
+**Filesystem path picker** (Link Existing "Browse" + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file. Inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping** — it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)
+
+**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**: `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)
+
+**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`
+
+**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`
+
+**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) → `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) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `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). `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) → `mobile-overview.js`(12.55) → `entrance-animations.js`(12.6) → `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).
 
-**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).
+**Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for the four things that appear when work starts, chosen per surface via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` on `<html>`. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. ⚠️ Tabs and connection lines are **destroyed mid-animation** on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML; `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''`), so both are tracked by id and re-applied to the fresh element with a **negative `animation-delay`** to resume rather than restart. ⚠️ The terminal-pane styles may animate **transform / opacity / clip-path only**, xterm's FitAddon derives rows+cols from `getComputedStyle(parent).width/height`, so animating width/height/padding there would resize the PTY. ⚠️ Window styles other than `beam` transform the window, which moves the rect its connection line is aimed at; `beam` deliberately animates opacity/filter only so its line can draw toward a stable target. Persisted to its own `codeman:*Anim` localStorage keys (per-device, deliberately NOT in the `.strict()` `SettingsUpdateSchema`); picker in App Settings → Appearance, full per-surface lab at `?animlab=1`.
 
-**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`.
+**Phone overview home screen** (`mobile-overview.js`, phones only, per-device `mobileOverviewEnabled`, default ON): under 430px the "C" logo shows a session overview (NEEDS YOU / CURRENT SESSIONS / PAST SESSIONS) instead of the welcome overlay; tablet and desktop are unchanged. The branch lives in `showWelcome()`/`hideWelcome()` (terminal-ui.js) behind `shouldUseMobileOverview()`, which is **width-driven** (`getDeviceType() === 'mobile'`) because this is a layout decision, unlike the settings namespace which stays handheld-based. ⚠️ The container ships with the `hidden` attribute and only this module removes it: never give `.mobile-overview` a bare `display` rule, since desktop does not load `mobile.css` (`media="(max-width: 1023px)"`) and would then render it unstyled. Live re-renders ride on the tail of `_renderSessionTabsImmediate()` (every state change it needs already funnels there); PAST rows come from one `_fetchUnifiedSessions(60)` per home-screen visit and resume through the shared `resumeHistorySession()`, so they behave exactly like the welcome screen's Resume list. ⚠️ Two things must stay in lockstep with surfaces outside this module, because divergence reads as a bug rather than a style: the split Run button carries the **toolbar's own classes** (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) so the per-backend gradient and the light-skin overrides apply unchanged (mobile.css must therefore set no `background`/`color` on it), and row status uses the **session-tab language** (green dot when fine, `pulse` while working, yellow blinking row when waiting for input, red blinking row when a question is pending, mirroring `tab-alert-idle`/`tab-alert-action`). The picker mirrors the toolbar run-mode menu (`setRunMode()` + `run()`, `openWebviewFromMenu()` for saved dashboards) and deliberately omits its Recent-Sessions block, since PAST SESSIONS is that. Status pills carry `data-i18n-skip` (generic words like "idle" collide with state strings elsewhere).
 
-**Response-viewer (eye) button** (header) is likewise **hidden by default** — enable under App Settings → Display → **Response Viewer** (`showResponseViewer`). 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.
+**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)
 
-**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).
+**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.
 
-**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`.
+**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)
 
-**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` `applyTheme()`/`applyTerminalSkin()` apply it live on save and keep the standalone `codeman:skin` key + the settings object in sync. `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.
+**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)
+
+**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. ⚠️ A skin is **four things that must stay in sync**, and missing any one degrades silently: the `html[data-skin="…"]` token block in `styles.css`, the xterm ANSI palette in `terminal-ui.js`, the pre-paint allowlist, and the Settings picker (both in `index.html`). `test/skin-themes.test.ts` is the static guard. Light skins additionally need `color-scheme: light` and xterm `minimumContrastRatio: 4.5`, and `applyTerminalSkin()` must call the local-echo overlay's `refreshFont()` because it caches the terminal fg/bg. `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)
+
+**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)
+
+**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)
+
+**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.
+
+⚠️ **`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.
+
+⚠️ **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).
 
 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).
 
-**Keyboard shortcuts**: Escape (close), Ctrl+? (help), Ctrl+W (kill), Ctrl+Tab (next), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font).
+**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) exempt from auth (localhost-only, schema-validated). While the **managed tunnel** runs, the bypass additionally requires the per-instance `X-Codeman-Hook-Secret` header (COD-54, `config/hook-secret.ts`): hook curls cat the secret file at exec time via `$CODEMAN_HOOK_SECRET_FILE` (session env), failures rate-limit in a dedicated bucket (never lock out login). External loopback proxies (own cloudflared/`tailscale serve`) aren't detected — plain bypass still applies there. 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) |
-| **Validation** | Zod schemas, path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`) |
-| **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_*`/`ANTIGRAVITY_*`)                                                        |
+| **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
 
-~120 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). 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
 
-~146 handlers across 16 route files in `src/web/routes/`: system (41, incl. self-update `check`/`status`/`POST /api/system/update`, `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`, and `GET /api/codex/status`), sessions (29), orchestrator (10), cases (9), ralph (9), plan (8), files (14, incl. attachment register + list/history + `:attachmentId/raw`/`preview`/`thumbnail` + workspace `file-preview`/`file-thumbnail`), respawn (7), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), status-telemetry (1, `POST /api/status-telemetry` ← statusLine exporter), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~199 handlers across 21 route files in `src/web/routes/`: system (45), sessions (32), cases (27), files (16), 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`).
 
@@ -231,15 +297,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()`). ⚠️ Anything in `PUT /api/settings` that acts on a setting (the `toggleService` watcher calls) must resolve from **`merged`** (persisted + incoming), never from the raw request body: a partial PUT omits keys it doesn't intend to change, and `body.x ?? default` turns every omission into "apply the default" and silently resets live services. Pinned by `test/routes/system-routes-settings-partial-put.test.ts`.
 - **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), `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).
+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.
 
@@ -258,11 +325,15 @@ 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.
+**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. `Session` is test-gated too: instead of attaching a real tmux client, it spawns a raw-mode echo PTY (`TEST_PTY_SCRIPT` in `src/session.ts`), so integration tests get a live input/output loop that echoes each byte exactly once. `test/setup.ts` gives every test file a temporary `HOME`/`USERPROFILE` (all `homedir()`-derived state, `~/.codeman` and `~/codeman-cases` included, resolves into a per-file fixture; the Playwright browser cache path is preserved), and 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). ⚠️ Raw `npx vitest` without `--config` skips `setup.ts` and with it the temp-HOME isolation.
 
-**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).
 
-**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
+⚠️ **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`.
 
 ## Debugging
 
@@ -278,10 +349,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 2MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+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 start|stop|url` (tunnel). 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. The network-access prompt is 3-way: **Tailscale** (loopback bind + guided `tailscale serve --bg <port>` HTTPS setup: install/login/operator/tailnet-HTTPS-toggle, then curl-verified end-to-end), **LAN** (0.0.0.0 + password prompt), or **local-only**; it preserves the existing binding on re-runs via `read_existing_binding()`. Tailscale state is detected dynamically from `tailscale serve status --json` (no marker files); the installer must NEVER `tailscale serve reset` or touch serve mappings other than 443→Codeman's port (users have unrelated serve config). `install.sh update`, `install.sh uninstall`, and `install.sh tailscale` (retrofit Tailscale access onto an existing install) also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation, `CODEMAN_TAILSCALE=1` presets the Tailscale choice (never installs Tailscale non-interactively).
+
+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

@@ -5,7 +5,7 @@
 <h2 align="center">Mission control for AI coding agents</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Terminal - One Dashboard &bull; Any Device</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
 <p align="center">
@@ -13,7 +13,10 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <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">
@@ -21,7 +24,33 @@
 </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.
+
+Get started in one line (macOS & Linux, Windows via WSL):
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+```
+
+```bash
+codeman web
+# Open http://localhost:3000 and start your first session
+```
+
+The installer asks before every system change, and re-running the same line updates in place. Full details: [Quick Start - Installation](#quick-start---installation).
+
+- **One dashboard, four CLIs** - run [Claude Code, OpenCode, Codex, or Gemini](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
+- **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
+- **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 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>
 
 ---
@@ -29,22 +58,39 @@
 ## Quick Start - Installation
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+curl -fsSL https://getcodeman.com/install | bash
 ```
 
-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it.
+This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
 
-You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), or [Codex](https://developers.openai.com/codex/cli) (any combination works). After install:
+- **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.
+
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (any combination works). The installer detects whichever of the four is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
 
 ```bash
 codeman web
 # Open http://localhost:3000 and start your first session
 ```
 
+**Sharing with a small team?** Start it in multi-user mode instead: each person gets their own login and workspace.
+
+```bash
+codeman users add alice --admin      # create the first admin account
+codeman web --multiuser              # named logins + per-user case spaces
+```
+
+Details in [Multi-User Mode](#multi-user-mode-opt-in) below.
+
 <details>
 <summary><strong>Run as a background service</strong></summary>
 
+The installer's final menu sets this up for you (option 2) and verifies the service actually comes up before claiming success. To configure it manually instead:
+
 **Linux (systemd):**
+
 ```bash
 mkdir -p ~/.config/systemd/user
 cat > ~/.config/systemd/user/codeman-web.service << EOF
@@ -67,6 +113,7 @@ loginctl enable-linger $USER
 ```
 
 **macOS (launchd):**
+
 ```bash
 mkdir -p ~/Library/LaunchAgents
 cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
@@ -94,16 +141,18 @@ cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
 EOF
 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 ```
+
 </details>
 
 <details>
 <summary><strong>Windows (WSL)</strong></summary>
 
 ```powershell
-wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), or [Codex](https://developers.openai.com/codex/cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+
 </details>
 
 ---
@@ -114,14 +163,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-active.png" alt="Mobile — active agent session" width="260"></td>
+<td align="center" width="40%"><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="300"></td>
+<td align="center" width="60%"><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="440"></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>Agent working in real-time</em></td>
+<td align="center"><em>Answering prompts by touch</em></td>
+<td align="center"><em>Accessory bar + dedicated Enter button</em></td>
 </tr>
 </table>
 
@@ -140,6 +187,18 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
 <tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
 </table>
 
+- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
+- **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
+- **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
+- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
+
+```bash
+codeman web --https
+# Open on your phone: https://<your-ip>:3000
+```
+
+> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended): the installer can set it up for you (choose **Tailscale** at the network-access prompt, or run `bash ~/.codeman/app/install.sh tailscale` on an existing install). That gives you `https://<your-machine>.<tailnet>.ts.net` with a real certificate: private to your tailnet, no password required, and PWA install + push notifications work on your phone.
+
 ### Secure QR Code Authentication
 
 Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
@@ -148,47 +207,78 @@ Each QR encodes a URL containing a 6-character short code that maps to a 256-bit
 
 The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
 
-### Touch-Optimized Interface
-
-- **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
-- **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-*)`
-- **44px touch targets** — all buttons meet iOS Human Interface Guidelines minimum sizes
-- **Bottom sheet case picker** — slide-up modal replaces the desktop dropdown
-- **Native momentum scrolling** — `-webkit-overflow-scrolling: touch` for buttery scroll
-
-```bash
-codeman web --https
-# Open on your phone: https://<your-ip>:3000
-```
-
-> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended) — it provides a private network so you can access `http://<tailscale-ip>:3000` from your phone without TLS certificates.
-
 ---
 
-## Live Agent Visualization
+## Using Codeman — A Human's Guide
 
-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.
+A start-to-finish walkthrough for driving Codeman from the browser. If you just installed, this is where to begin.
 
-<p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="Subagent Visualization" width="900">
-</p>
+### 1. Launch the server
 
-- **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
-- **Connection lines** — animated green lines linking parent sessions to their child agents, updating in real-time as agents spawn and complete
-- **Status & model badges** — green (active), yellow (idle), blue (completed) indicators with Haiku/Sonnet/Opus model color coding
-- **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)
+```bash
+codeman web                       # localhost:3000 (loopback only — safe default)
+codeman web --port 8080           # custom port (or set CODEMAN_PORT)
+codeman web --https               # self-signed TLS (only needed for remote access)
+codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
+```
 
-**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/).
+Open the printed URL. The page is a single dashboard; everything below happens there.
+
+### 2. Create your first session
+
+Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in its own tmux-backed terminal. You choose:
+
+| Field                        | What it does                                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers.                           |
+| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Gemini`, or `Terminal` (plain shell).                                     |
+| **Model**                    | Per-session model (App Settings → Claude Model). A soft default — `/model` still works in-session.                  |
+| **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
+
+Hit start — Codeman spawns the CLI via a real PTY and streams it to your browser over SSE.
+
+### 3. Read the dashboard
+
+- **Tabs (top)** — one per session. `Alt+1`-`9` to jump, `Ctrl+Tab` for next, drag to reorder (tab order syncs across your devices).
+- **Terminal (center)** — a real `xterm.js` terminal; full TUIs render correctly. Type directly and press **Enter** to send. `Shift+Enter` inserts a newline.
+- **Side panels** — Respawn, Orchestrator, Cron, Subagents, Settings (toggled from the toolbar).
+
+### 4. Talk to the agent
+
+- **Type prompts** straight into the terminal — input is delivered exactly-once even across reconnects (a dropped link never loses or double-sends a prompt).
+- **Paste or drag-and-drop images** directly into the session.
+- **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, with auto-silence stop).
+- **Attachments** — register external files/docs and preview Office/PDF inline.
+
+### 5. Make it autonomous
+
+| Mode             | Use it for                                                                                                                        | Where                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Respawn**      | Long unattended runs — auto-restarts the CLI on idle/limit, with adaptive timing. Presets: `solo-work`, `overnight-autonomous`, … | Respawn tab                                                         |
+| **Orchestrator** | Turn one goal into a phased plan and drive it to completion across agents.                                                        | Orchestrator panel                                                  |
+| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Display → Header Displays)_ |
+| **Auto-resume**  | Automatically continue after a subscription rate-limit resets.                                                                    | Respawn tab (top)                                                   |
+
+### 6. Reach it from anywhere
+
+- **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
+- **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
+- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+
+### 7. Operate & maintain
+
+- **App Settings** — model, effort, permission startup mode, theme/skin, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
+- **Self-update** — git-clone installs update in place from **Settings → Updates**.
+- **Deploy your own changes** — see [Development](#development).
+
+> ⚠️ **Safety:** if you're working _inside_ a Codeman-managed session (`echo $CODEMAN_MUX` → `1`), never run `tmux kill-session` / `pkill claude` directly — use the web UI or `./scripts/tmux-manager.sh`.
 
 ---
 
 ## Zero-Lag Input Overlay
 
 <p align="center">
-  <img src="docs/images/zerolag-demo.gif" alt="Zerolag Demo — local echo vs server echo side-by-side" width="900">
+  <img src="docs/images/zerolag-demo-20260728.gif" alt="Zerolag demo: instant local echo next to 600ms-2.7s server echo, side by side on two phones" width="900">
 </p>
 
 When accessing your coding agent remotely (VPN, Tailscale, SSH tunnel), every keystroke normally takes 200-300ms to round-trip. Codeman implements a **Mosh-inspired local echo system** that makes typing feel instant regardless of latency.
@@ -205,6 +295,30 @@ A pixel-perfect DOM overlay inside xterm.js renders keystrokes at 0ms. Backgroun
 
 ---
 
+## Live Agent Visualization
+
+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-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
+- **Connection lines** — animated green lines linking parent sessions to their child agents, updating in real-time as agents spawn and complete
+- **Status & model badges** — green (active), yellow (idle), blue (completed) indicators with Haiku/Sonnet/Opus model color coding
+- **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/).
+
+---
+
 ## Respawn Controller
 
 The core of autonomous work. When the agent goes idle, the Respawn Controller detects it, sends a continue prompt, cycles context management commands for fresh context, and resumes — running **24+ hours** completely unattended.
@@ -214,7 +328,7 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 ```
 
 - **Multi-layer idle detection** — completion messages, AI-powered idle check, output silence, token stability
-- **Auto-resume on usage limit** *(opt-in, off by default)* — when Claude halts on a subscription limit ("You've hit your limit · resets 3pm"), Codeman parses the reset time, waits it out plus a 2-minute safety buffer, then dismisses the rate-limit dialog and sends `continue` — so an overnight run survives the 5-hour window instead of stalling until morning. Recognizes every Claude Code limit-message format, retries if still limited, survives Codeman restarts, and holds respawn cycles while paused so `/clear` can't wipe the waiting conversation. Enable per session at the top of the Respawn tab
+- **Auto-resume on usage limit** _(opt-in, off by default)_ — when Claude halts on a subscription limit ("You've hit your limit · resets 3pm"), Codeman parses the reset time, waits it out plus a 2-minute safety buffer, then dismisses the rate-limit dialog and sends `continue` — so an overnight run survives the 5-hour window instead of stalling until morning. Recognizes every Claude Code limit-message format, retries if still limited, survives Codeman restarts, and holds respawn cycles while paused so `/clear` can't wipe the waiting conversation. Enable per session at the top of the Respawn tab
 - **Circuit breaker** — prevents respawn thrashing when Claude is stuck (CLOSED -> HALF_OPEN -> OPEN states, tracks consecutive no-progress and repeated errors)
 - **Health scoring** — 0-100 health score with component scores for cycle success, circuit breaker state, iteration progress, and stuck recovery
 - **Built-in presets** — `solo-work` (3s idle, 60min), `subagent-workflow` (45s, 240min), `team-lead` (90s, 480min), `ralph-todo` (8s, 480min), `overnight-autonomous` (10s, 480min)
@@ -231,7 +345,7 @@ Beyond single-session respawn, the **Orchestrator** turns a high-level goal into
 - **Crash-safe** — full state persists under the `orchestrator` key in `state.json`, so it survives restarts
 - **Driven from the UI or API** — the Orchestrator panel, or `POST /api/orchestrator/start` → `/approve` → `/status` (10 endpoints)
 
-> Distinct from Ralph (a single-session autonomous loop): the orchestrator coordinates multi-phase, multi-agent execution. Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
+> Full design: [`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md).
 
 ---
 
@@ -239,14 +353,18 @@ Beyond single-session respawn, the **Orchestrator** turns a high-level goal into
 
 Run **20 parallel sessions** with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.
 
-<p align="center">
-  <img src="docs/screenshots/multi-session-dashboard.png" alt="Multi-Session Dashboard" width="800">
-</p>
-
 ### Persistent Sessions
 
 Every session runs inside **tmux** — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Managed sessions are environment-tagged so the agent won't kill its own session.
 
+### Session Manager & Command Palette
+
+`Ctrl/Cmd/Alt+K` opens a fuzzy session palette; **Browse all sessions** opens the Session Manager: one deduped list of everything Codeman knows about (live sessions, past sessions from state and lifecycle history, and Claude transcripts), each row showing its first and most recent prompt.
+
+- **Pinning**: pin a session to float it to the top of the list. Pinned sessions even survive kill (they demote to a lightweight stopped entry that stays visible and resumable).
+- **Name retention**: resuming a past session keeps its original name instead of minting a new one.
+- **Cross-device tab order**: drag-reordered tabs persist server-side, so your ordering follows you from desktop to phone.
+
 ### Hostname-Aware Window Title
 
 Running Codeman on multiple hosts (laptop, dev box, NAS)? The browser tab title is `codeman:<hostname>` so you can tell which backend each tab points at without clicking in:
@@ -260,23 +378,15 @@ The title is templated into the served HTML on first byte, so it's correct from
 
 ### Smart Token Management
 
-| Threshold | Action | Result |
-|-----------|--------|--------|
+| Threshold       | Action          | Result                             |
+| --------------- | --------------- | ---------------------------------- |
 | **110k tokens** | Auto `/compact` | Context summarized, work continues |
-| **140k tokens** | Auto `/clear` | Fresh start with `/init` |
+| **140k tokens** | Auto `/clear`   | Fresh start with `/init`           |
 
 ### Notifications
 
 Real-time desktop alerts when sessions need attention — `permission_prompt` and `elicitation_dialog` trigger critical red tab blinks, `idle_prompt` triggers yellow blinks. Click any notification to jump directly to the affected session. Hooks auto-configured per case directory.
 
-### Ralph / Todo Tracking
-
-Auto-detects Ralph Loops, `<promise>` tags, TodoWrite progress (`4/9 complete`), and iteration counters (`[5/50]`) with real-time progress rings and elapsed time tracking.
-
-<p align="center">
-  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph Loop Tracking" width="800">
-</p>
-
 ### Run Summary
 
 Click the chart icon on any session tab to see a timeline of everything that happened — respawn cycles, token milestones, auto-compact triggers, idle/working transitions, hook events, errors, and more.
@@ -294,17 +404,70 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 ## More Features
 
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
-- **Multi-CLI** — run **Claude Code**, **OpenCode**, or **Codex** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
+- **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
 - **Voice input** — dictate prompts with Deepgram Nova-3 (Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
 - **Image input** — paste or drag-and-drop images straight into a session
-- **Gesture control** *(opt-in)* — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
-- **Multi-monitor span** *(macOS)* — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
+- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
+- **Multi-monitor span** _(macOS)_ — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
+- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Display → Header Displays
 - **CJK / IME input** — full composition support for Chinese / Japanese / Korean
 - **OS notifications & hostname-aware titles** — desktop alerts and tab titles are prefixed `codeman:<host>` so multi-host setups stay unambiguous
 
 ---
 
+## Isolated Docker Sessions
+
+Run a case inside its own hardened Docker container instead of directly on your host — for security isolation, reproducible toolchains, and one-click portability.
+
+- **One click** — on **New Case → Create New**, tick **🐳 Run in an isolated Docker container**. Codeman creates the case folder, spins up a container with default settings, and starts the agent inside it. No host/image/network fields to fill in.
+- **Resource templates** — expand the checkbox for a **Small / Medium / Large / GPU** preset (memory, CPUs, GPU), or set your own. **Disk is elastic** — storage grows as data flows in, no fixed cap.
+- **Shared per-case container** — many sessions can `docker exec` into the same container; killing one session never tears the container out from under the others.
+- **Hardened by default** — non-root, `--cap-drop ALL`, `no-new-privileges`, PID/memory caps, never `--privileged` or the docker socket; a **sealed** profile (no host credentials, network off) is one toggle away.
+- **Seamless auth, isolated credentials** — your host Claude / Codex / Gemini / OpenCode logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
+- **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
+- **Durable** — reconnect after a restart lands back in the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript.
+
+Prerequisite: just Docker (or Podman). The agent base image builds itself automatically on first use, with progress streamed to the UI (or pre-build it with `node scripts/build-agent-image.mjs`). Full guide: [`docs/docker-cases.md`](docs/docker-cases.md).
+
+---
+
+## Remote SSH Sessions
+
+Point a case at another machine and run the agent **there**, over SSH, with the same dashboard, mobile UI, and autonomy features. Your laptop is just a window onto a session that lives on the remote host.
+
+- **Durable by design**: the agent runs inside a dedicated tmux session on the remote host, so a dropped SSH connection, network change, or laptop sleep never kills the run. Reconnecting lands back in the same live conversation.
+- **Auto-reconnect**: a bounded-backoff watcher notices a dead SSH pane and silently reattaches to the still-running remote session (kill-switch in settings; intentional kills are never revived).
+- **Discover & attach**: list the `codeman-*` sessions already running on a host (started by that machine's own Codeman, or by another operator) and attach to one. Attached sessions you don't own **detach on tab close, never kill**.
+- **Shared sessions**: several clients can attach the same remote session at different window sizes without clamping each other; discovery shows a "shared" badge with the client count.
+- **Injection-safe**: every ssh command line flows through a single shell-escaping builder, and host/path/identity fields are schema-guarded.
+
+Set it up under **New Case → Remote** (host, user, identity file, optional jump host). Full design: [`docs/remote-sessions.md`](docs/remote-sessions.md).
+
+---
+
+## Multi-User Mode (opt-in)
+
+Share one Codeman with a small trusted team, each person getting their own login and workspace. **Off by default** — without the flag, nothing changes.
+
+Enable with `codeman web --multiuser` (or `CODEMAN_MULTIUSER=1`). Create the first admin, then manage users from the CLI or the **Users** tab in App Settings:
+
+```bash
+codeman users add alice --admin      # prompts for a password (or --password-stdin)
+codeman users add bob                # a regular user
+codeman users list
+```
+
+- **Per-user spaces** — each user's cases live under `~/codeman-users/<name>/cases`; sessions, cases, search, and real-time events are scoped to their owner. Admins see everything.
+- **Individually revocable logins** — named users with scrypt-hashed passwords in `~/.codeman/users.json`; disable, reset (one-time password), or delete an account at any time. Admin actions are audited to `~/.codeman/admin-audit.jsonl`.
+- **Safer defaults for regular users** — non-admins run Claude in `--permission-mode auto` (Anthropic's classifier-guarded mode); raw shell sessions, cron `launchCommand`, and skip-permissions require an explicit per-user grant.
+
+> ⚠️ **This separates workspaces; it does not sandbox users from each other.** Every session runs as the same OS account, so a determined user's agent can still reach another user's files. For real isolation, pair users with **Docker cases** or run separate instances under separate OS accounts. See [`docs/multi-user-plan.md`](docs/multi-user-plan.md) and the multi-user section of [`docs/security-architecture.md`](docs/security-architecture.md).
+
+---
+
 ## Remote Access — Cloudflare Tunnel
 
 Access Codeman from your phone or any device outside your local network using a free [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) — no port forwarding, no DNS, no static IP required.
@@ -372,14 +535,14 @@ Every **60 seconds**, the server automatically rotates to a fresh token. The pre
 
 The design is informed by ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025), which found 47 of the top-100 websites vulnerable to QR auth attacks due to 6 critical design flaws across 42 CVEs. Codeman addresses all six:
 
-| USENIX Flaw | Mitigation |
-|-------------|------------|
-| **Flaw-1**: Missing single-use enforcement | Token atomically consumed on first scan — replays always fail |
-| **Flaw-2**: Long-lived tokens | 60s TTL with 90s grace, auto-rotation via timer |
-| **Flaw-3**: Predictable token generation | `crypto.randomBytes(32)` — 256-bit entropy. Short codes use rejection sampling to eliminate modulo bias |
-| **Flaw-4**: Client-side token generation | Server-side only — tokens never leave the server until embedded in the QR |
-| **Flaw-5**: Missing status notification | Desktop toast: *"Device [IP] authenticated via QR (Safari). Not you? [Revoke]"* — real-time QRLjacking detection |
-| **Flaw-6**: Inadequate session binding | IP + User-Agent stored for audit. Manual session revocation via API. HttpOnly + Secure + SameSite=lax cookies |
+| USENIX Flaw                                | Mitigation                                                                                                       |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Flaw-1**: Missing single-use enforcement | Token atomically consumed on first scan — replays always fail                                                    |
+| **Flaw-2**: Long-lived tokens              | 60s TTL with 90s grace, auto-rotation via timer                                                                  |
+| **Flaw-3**: Predictable token generation   | `crypto.randomBytes(32)` — 256-bit entropy. Short codes use rejection sampling to eliminate modulo bias          |
+| **Flaw-4**: Client-side token generation   | Server-side only — tokens never leave the server until embedded in the QR                                        |
+| **Flaw-5**: Missing status notification    | Desktop toast: _"Device [IP] authenticated via QR (Safari). Not you? [Revoke]"_ — real-time QRLjacking detection |
+| **Flaw-6**: Inadequate session binding     | IP + User-Agent stored for audit. Manual session revocation via API. HttpOnly + Secure + SameSite=lax cookies    |
 
 #### Timing-Safe Lookup
 
@@ -404,23 +567,23 @@ When someone authenticates via QR, the desktop shows a notification toast with t
 
 #### Threat Coverage
 
-| Threat | Why it doesn't work |
-|--------|-------------------|
-| **QR screenshot shared** | Single-use: consumed on first scan. 60s TTL: expired before the attacker can act. Desktop notification alerts you immediately. |
-| **Replay attack** | Atomic single-use consumption + 60s TTL. Old URLs always return 401. |
-| **Cloudflare edge logs** | Short code is an opaque 6-char lookup key, not the real 256-bit token. Single-use means replaying from logs always fails. |
-| **Brute force** | 56.8 billion combinations, ~2 valid at any time, dual-layer rate limiting blocks well before statistical feasibility. |
-| **QRLjacking** | 60s rotation forces real-time relay. Desktop toast provides instant detection. Self-hosted single-user context makes phishing implausible. |
-| **Timing attack** | Hash-based Map lookup — no string comparison timing leak. |
-| **Session cookie theft** | HttpOnly + Secure + SameSite=lax + 24h TTL. Manual revocation at `POST /api/auth/revoke`. |
+| Threat                   | Why it doesn't work                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **QR screenshot shared** | Single-use: consumed on first scan. 60s TTL: expired before the attacker can act. Desktop notification alerts you immediately.             |
+| **Replay attack**        | Atomic single-use consumption + 60s TTL. Old URLs always return 401.                                                                       |
+| **Cloudflare edge logs** | Short code is an opaque 6-char lookup key, not the real 256-bit token. Single-use means replaying from logs always fails.                  |
+| **Brute force**          | 56.8 billion combinations, ~2 valid at any time, dual-layer rate limiting blocks well before statistical feasibility.                      |
+| **QRLjacking**           | 60s rotation forces real-time relay. Desktop toast provides instant detection. Self-hosted single-user context makes phishing implausible. |
+| **Timing attack**        | Hash-based Map lookup — no string comparison timing leak.                                                                                  |
+| **Session cookie theft** | HttpOnly + Secure + SameSite=lax + 24h TTL. Manual revocation at `POST /api/auth/revoke`.                                                  |
 
 #### How It Compares
 
-| Platform | Model | Comparison |
-|----------|-------|------------|
-| **Discord** | Long-lived token, no confirmation, [repeatedly exploited](https://owasp.org/www-community/attacks/Qrljacking) | Codeman: single-use + TTL + notification |
-| **WhatsApp Web** | Phone confirms "Link device?", ~60s rotation | Comparable rotation; WhatsApp adds explicit confirmation (acceptable tradeoff for single-user) |
-| **Signal** | Ephemeral public key, E2E encrypted channel | Stronger crypto, but [exploited by Russian state actors in 2025](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger) via social engineering despite it |
+| Platform         | Model                                                                                                         | Comparison                                                                                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Discord**      | Long-lived token, no confirmation, [repeatedly exploited](https://owasp.org/www-community/attacks/Qrljacking) | Codeman: single-use + TTL + notification                                                                                                                                                       |
+| **WhatsApp Web** | Phone confirms "Link device?", ~60s rotation                                                                  | Comparable rotation; WhatsApp adds explicit confirmation (acceptable tradeoff for single-user)                                                                                                 |
+| **Signal**       | Ephemeral public key, E2E encrypted channel                                                                   | Stronger crypto, but [exploited by Russian state actors in 2025](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger) via social engineering despite it |
 
 > Full design rationale, security analysis, and implementation details: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
 
@@ -428,27 +591,28 @@ When someone authenticates via QR, the desktop shows a notification toast with t
 
 ## Security
 
-Codeman launches sessions with `--dangerously-skip-permissions`, so the web UI is by design a remote-code-execution surface for whoever can reach it — the whole security model exists to control *who* that is. Recent hardening (v0.9.0 + v0.9.5) closes the browser-driven attack paths that bite self-hosted dev tools. Full model: [`docs/security-architecture.md`](docs/security-architecture.md). **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
+- **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
 
 ### Always-on browser hardening (v0.9.5)
 
 These run for **every** request — before auth, even on the default no-password loopback install:
 
 - **Host-header allowlist → blocks DNS rebinding.** A custom domain rebound to `127.0.0.1` is rejected with `403 host not allowed` before any handler runs. Allowed: `localhost`, any IP literal, the bind host, `.ts.net` / `.trycloudflare.com` / `.cfargotunnel.com`, the active managed tunnel, and `CODEMAN_ALLOWED_HOSTS` (add custom reverse-proxy domains here — comma-separated; exact host or leading-dot `.suffix` for subdomains)
-- **Cross-site Origin / CSRF guard.** On state-changing methods (`POST`/`PUT`/`PATCH`/`DELETE`) the `Origin` must pass the same allowlist, else `403 cross-site request blocked`. A *missing* Origin is allowed (so `curl`, the CLI, and Claude Code hooks keep working); only a present-but-foreign or opaque `null` origin is rejected
+- **Cross-site Origin / CSRF guard.** On state-changing methods (`POST`/`PUT`/`PATCH`/`DELETE`) the `Origin` must pass the same allowlist, else `403 cross-site request blocked`. A _missing_ Origin is allowed (so `curl`, the CLI, and Claude Code hooks keep working); only a present-but-foreign or opaque `null` origin is rejected
 - **Raw `text/plain` bodies.** The global parser no longer JSON-parses `text/plain`, closing the CORS "simple request" CSRF vector where a cross-site `fetch` could smuggle JSON into a write route with no preflight
 - **WebSocket origin validation.** The terminal WS upgrade runs the same Host + Origin check and closes with code `4003` on failure (anti-CSWSH)
 - **XSS-escaped agent output.** AI-derived strings (tool names, command arguments, subagent descriptions) are HTML-escaped at every injection site before rendering in the subagent / activity panels
 
 ### Input, files & headers
 
-- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` env-prefix allowlist gates which settings each CLI can receive
+- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env-prefix allowlist gates which settings each CLI can receive
 - **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 50 MB raw & download; `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
 - **Security headers** — `Content-Security-Policy` (`default-src 'self'`, every exception enumerated), `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, HSTS over HTTPS, and CORS reflected **only** for `localhost` / `127.0.0.1` / `::1`
 
@@ -479,74 +643,172 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 
 > Ctrl bindings also accept Cmd on macOS.
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl/Cmd+W` | Kill active session |
-| `Ctrl/Cmd+Tab` | Next session |
-| `Alt/Option+[` / `Alt/Option+]` | Previous / next session |
-| `Alt/Option+1`-`Alt/Option+9` | Switch to tab N (physical keys, so macOS Option layouts work) |
-| `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right |
-| `Ctrl/Cmd+L` | Clear terminal |
-| `Ctrl+Shift+R` | Restore terminal size |
-| `Ctrl+Shift+V` | Toggle voice input |
-| `Ctrl/Cmd +` / `-` | Font size |
-| `Ctrl/Cmd+?` | Keyboard help |
-| `Shift+Enter` | Insert newline (sent to terminal) |
-| `Escape` | Close panels & modals |
+| Shortcut                        | Action                                                        |
+| ------------------------------- | ------------------------------------------------------------- |
+| `Ctrl/Cmd+W`                    | Kill active session                                           |
+| `Ctrl/Cmd/Option+K`             | Find open session or start a new one                          |
+| `Ctrl/Cmd+Tab`                  | Next session                                                  |
+| `Alt/Option+[` / `Alt/Option+]` | Previous / next session                                       |
+| `Alt/Option+1`-`Alt/Option+9`   | Switch to tab N (physical keys, so macOS Option layouts work) |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right                                  |
+| `Ctrl/Cmd+L`                    | Clear terminal                                                |
+| `Ctrl+Shift+R`                  | Restore terminal size                                         |
+| `Ctrl+Shift+V`                  | Toggle voice input                                            |
+| `Ctrl/Cmd +` / `-`              | Font size                                                     |
+| `Ctrl/Cmd+?`                    | Keyboard help                                                 |
+| `Shift+Enter`                   | Insert newline (sent to terminal)                             |
+| `Escape`                        | Close panels & modals                                         |
+
+---
+
+## Driving Codeman from an Agent — Programmatic Guide
+
+For AI agents and automation that control Codeman without a browser: an agent that spins up worker sessions, a CI bot, or **Claude Code running _inside_ a Codeman session orchestrating other sessions**. Everything the UI does is HTTP + a CLI, so an agent can do it too.
+
+### Detect that you're inside Codeman
+
+When a CLI runs in a Codeman-managed session, these environment variables are set — read them instead of hardcoding anything:
+
+| Variable                   | Meaning                                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `CODEMAN_MUX=1`            | You're in a managed tmux session. **Never** `tmux kill-session` / `pkill claude` / `pkill tmux` — you'll kill yourself or a sibling. |
+| `CODEMAN_API_URL`          | Base URL of the API (e.g. `https://127.0.0.1:3000`). Use it for every call below.                                                    |
+| `CODEMAN_SESSION_ID`       | _Your own_ session id. Use it to avoid acting on yourself.                                                                           |
+| `CODEMAN_HOOK_SECRET_FILE` | Path to the hook secret (required on `/api/hook-event` while a managed tunnel is up).                                                |
+
+### Rules of the road (read before you POST)
+
+1. **Single-line input only.** Programmatic input is sent as literal text **+ Enter** in one shot. Multi-line strings break the agent TUI (Ink) — send one line, or split into multiple calls.
+2. **Make input idempotent.** Include a stable `clientId` and a monotonic per-session `seq` on `POST …/input`. The server de-duplicates, so a retry after a dropped connection can't double-deliver a prompt.
+3. **Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic auth (user `admin` or `CODEMAN_USERNAME`) or a `codeman_session` cookie. The default loopback install is passwordless. A missing `Origin` header is allowed, so plain `curl` works; cross-site browser origins are rejected (CSRF guard).
+4. **Response envelope.** Most endpoints return `{ "success": true, "data": … }` (errors: `{ "success": false, "error", "errorCode" }`). A few legacy GETs return bare bodies — **handle both** (`body.data ?? body`).
+5. **`/api/v1/*`** is a stable alias of `/api/*`.
+
+### Recipes
+
+```bash
+API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
+# (add  -u admin:"$CODEMAN_PASSWORD"  to each call if a password is set)
+
+# 1. See what's running
+curl -s "$API/api/sessions" | jq '.data // .'
+
+# 2. Spin up a worker session (a "case" = named working dir)
+curl -s -X POST "$API/api/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
+
+# 3. Send a prompt into a session (exactly-once: clientId + seq)
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+
+# 4. Read the terminal back
+curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+
+# 5. Stream live events (session output, agent activity, status)
+curl -sN "$API/api/events"          # Server-Sent Events
+
+# 6. Schedule recurring work (cron-style job)
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
+       "promptMode":"inline_text","promptText":"Update dependencies and open a PR",
+       "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
+       "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
+
+# 7. Inspect background sub-agents and their transcripts
+curl -s "$API/api/subagents" | jq '.data // .'
+curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
+
+# 8. Whole-system snapshot (sessions, settings, respawn, stats)
+curl -s "$API/api/status" | jq
+```
+
+### Or use the bundled CLI
+
+The same operations are available as commands (`codeman <cmd>`, aliases in parentheses) — handy from a shell tool inside a session:
+
+```bash
+codeman session start -d /path/to/repo   # (s)  start a session
+codeman session list                     #      list sessions
+codeman session logs <id>                #      tail output
+codeman task add "fix the failing test"  # (t)  queue a task
+codeman attach <path>                     #      attach a Claude hook context
+```
+
+### Hooks (events flowing _back_ to Codeman)
+
+Codeman registers Claude Code hooks that `POST /api/hook-event` (`permission_prompt`, `idle_prompt`, `stop`, `task_completed`, …) so the dashboard reacts in real time. This endpoint is auth-exempt on loopback but, under a managed tunnel, requires the `X-Codeman-Hook-Secret` header (read it from `$CODEMAN_HOOK_SECRET_FILE`). You normally don't call this by hand — Codeman wires it up — but it's how the autonomy layers "see" what the agent is doing.
+
+> Full endpoint list and request/response shapes follow.
 
 ---
 
 ## API
 
-REST over Fastify — **~140 handlers across 15 route modules**, plus an SSE stream and a WebSocket terminal channel. A representative subset:
+REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE stream and a WebSocket terminal channel. All responses use the `ApiResponse<T>` envelope (`{success, data}` / `{success, error, errorCode}`); `/api/v1/*` is a stable alias. A representative subset:
 
 ### Sessions
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/sessions` | List all |
-| `POST` | `/api/quick-start` | Create case + start session |
-| `DELETE` | `/api/sessions/:id` | Delete session |
-| `POST` | `/api/sessions/:id/input` | Send input |
+
+| Method   | Endpoint                   | Description                                                                        |
+| -------- | -------------------------- | ---------------------------------------------------------------------------------- |
+| `GET`    | `/api/sessions`            | List all                                                                           |
+| `POST`   | `/api/quick-start`         | Create case + start session (`{caseName?, mode?, effort?, envOverrides?}`)         |
+| `POST`   | `/api/sessions/:id/input`  | Send input (`{input, useMux?, clientId?, seq?}` — `clientId`+`seq` = exactly-once) |
+| `GET`    | `/api/sessions/:id/output` | Read terminal output                                                               |
+| `GET`    | `/api/sessions/unified`    | Unified live + history list (Session Manager) — `?q=&limit=`                       |
+| `POST`   | `/api/sessions/:id/pin`    | Pin/unpin in the Session Manager (`{pinned}`)                                      |
+| `PUT`    | `/api/session-order`       | Sync tab order across devices (`{order: [ids]}`)                                   |
+| `DELETE` | `/api/sessions/:id`        | Delete session                                                                     |
 
 ### Respawn
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/api/sessions/:id/respawn/enable` | Enable with config + timer |
-| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
-| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
 
-### Ralph / Todo
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/sessions/:id/ralph-state` | Get loop state + todos |
-| `POST` | `/api/sessions/:id/ralph-config` | Configure tracking |
+| Method | Endpoint                           | Description                |
+| ------ | ---------------------------------- | -------------------------- |
+| `POST` | `/api/sessions/:id/respawn/enable` | Enable with config + timer |
+| `POST` | `/api/sessions/:id/respawn/stop`   | Stop controller            |
+| `PUT`  | `/api/sessions/:id/respawn/config` | Update config              |
 
 ### Orchestrator
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/api/orchestrator/start` | Start orchestration from a goal |
-| `POST` | `/api/orchestrator/approve` | Approve the generated plan |
-| `GET` | `/api/orchestrator/status` | Current phase + progress |
-| `POST` | `/api/orchestrator/stop` | Stop and clean up |
+
+| Method | Endpoint                    | Description                     |
+| ------ | --------------------------- | ------------------------------- |
+| `POST` | `/api/orchestrator/start`   | Start orchestration from a goal |
+| `POST` | `/api/orchestrator/approve` | Approve the generated plan      |
+| `GET`  | `/api/orchestrator/status`  | Current phase + progress        |
+| `POST` | `/api/orchestrator/stop`    | Stop and clean up               |
+
+### Cron (scheduled jobs)
+
+| Method           | Endpoint                     | Description             |
+| ---------------- | ---------------------------- | ----------------------- |
+| `GET` / `POST`   | `/api/cron/jobs`             | List / create cron jobs |
+| `PUT` / `DELETE` | `/api/cron/jobs/:id`         | Update / delete a job   |
+| `PUT`            | `/api/cron/jobs/:id/enabled` | Enable / disable        |
+| `POST`           | `/api/cron/jobs/:id/run`     | Run now                 |
+| `GET`            | `/api/cron/jobs/:id/runs`    | Run history             |
 
 ### Subagents
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/subagents` | List all background agents |
-| `GET` | `/api/subagents/:id` | Agent info and status |
-| `GET` | `/api/subagents/:id/transcript` | Full activity transcript |
-| `DELETE` | `/api/subagents/:id` | Kill agent process |
+
+| Method   | Endpoint                        | Description                |
+| -------- | ------------------------------- | -------------------------- |
+| `GET`    | `/api/subagents`                | List all background agents |
+| `GET`    | `/api/subagents/:id`            | Agent info and status      |
+| `GET`    | `/api/subagents/:id/transcript` | Full activity transcript   |
+| `DELETE` | `/api/subagents/:id`            | Kill agent process         |
 
 ### System
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/api/events` | SSE stream |
-| `GET` | `/api/status` | Full app state |
-| `POST` | `/api/hook-event` | Hook callbacks |
-| `GET` | `/api/system/update/check` | Check for a new release |
-| `POST` | `/api/system/update` | Self-update (git-clone installs) |
-| `POST` | `/api/clipboard` | Push text to all connected browsers (`{text}`) |
-| `GET` | `/api/sessions/:id/run-summary` | Timeline + stats |
+
+| Method | Endpoint                        | Description                                    |
+| ------ | ------------------------------- | ---------------------------------------------- |
+| `GET`  | `/api/events`                   | SSE stream                                     |
+| `GET`  | `/api/status`                   | Full app state                                 |
+| `POST` | `/api/hook-event`               | Hook callbacks                                 |
+| `GET`  | `/api/system/update/check`      | Check for a new release                        |
+| `POST` | `/api/system/update`            | Self-update (git-clone installs)               |
+| `POST` | `/api/clipboard`                | Push text to all connected browsers (`{text}`) |
+| `GET`  | `/api/sessions/:id/run-summary` | Timeline + stats                               |
 
 ---
 
@@ -570,7 +832,6 @@ flowchart TB
         end
 
         subgraph Detection["Detection Layer"]
-            RT["Ralph Tracker"]
             SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
             TW["Team Watcher<br/><small>~/.claude/teams/*</small>"]
         end
@@ -581,7 +842,7 @@ flowchart TB
         end
 
         subgraph External["External"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
             BG["Background Agents<br/><small>(Task tool)</small>"]
         end
     end
@@ -594,7 +855,6 @@ flowchart TB
     SM --> RC
     SM --> ORC
     SM --> SS
-    S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
@@ -613,7 +873,7 @@ flowchart TB
 npm install
 npx tsx src/index.ts web    # Dev mode
 npm run build               # Production build
-npm test                    # Run tests
+npm run test:ci             # Run tests (the CI suite; browser suites need extra setup)
 ```
 
 See [CLAUDE.md](./CLAUDE.md) for full documentation.
@@ -624,14 +884,14 @@ See [CLAUDE.md](./CLAUDE.md) for full documentation.
 
 The codebase went through a comprehensive 7-phase refactoring that eliminated god objects, centralized configuration, and established modular architecture:
 
-| Phase | What changed | Impact |
-|-------|-------------|--------|
-| **Performance** | Cached endpoints, SSE adaptive batching, buffer chunking | Sub-16ms terminal latency |
-| **Route extraction** | `server.ts` split into 15 domain route modules + auth middleware + port interfaces | **−67%** server.ts LOC (6,736 → 2,254) |
-| **Domain splitting** | `types.ts` → 16 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files |
-| **Frontend modules** | `app.js` → 18 extracted modules across infra, domain & feature layers | app.js core down to **~3.4K LOC** |
-| **Config consolidation** | ~70 scattered magic numbers → 10 domain-focused config files | Zero cross-file duplicates |
-| **Test infrastructure** | Shared mock library, 12 route test files, consolidated MockSession | Testable route handlers via `app.inject()` |
+| Phase                    | What changed                                                                                                 | Impact                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| **Performance**          | Cached endpoints, SSE adaptive batching, buffer chunking                                                     | Sub-16ms terminal latency                  |
+| **Route extraction**     | `server.ts` split into 15 domain route modules + auth middleware + port interfaces                           | **−67%** server.ts LOC (6,736 → 2,254)     |
+| **Domain splitting**     | `types.ts` → 16 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files                          |
+| **Frontend modules**     | `app.js` → 18 extracted modules across infra, domain & feature layers                                        | app.js core down to **~3.4K LOC**          |
+| **Config consolidation** | ~70 scattered magic numbers → 10 domain-focused config files                                                 | Zero cross-file duplicates                 |
+| **Test infrastructure**  | Shared mock library, 12 route test files, consolidated MockSession                                           | Testable route handlers via `app.inject()` |
 
 Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
 
@@ -643,7 +903,7 @@ Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-stru
 
 [![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
 
-Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, configurable prompt detection, full state machine with 78 tests.
+Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 6.1 kB gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 175 tests.
 
 ```bash
 npm install xterm-zerolag-input
@@ -670,3 +930,8 @@ MIT — see [LICENSE](LICENSE)
 <p align="center">
   <strong>Track sessions. Visualize agents. Control respawn. Let it run while you sleep.</strong>
 </p>
+
+<p align="center">
+  If Codeman saves you time, <a href="https://github.com/Ark0N/Codeman/stargazers">a star</a> helps other people find it.<br>
+  Bug reports and feature ideas are welcome in <a href="https://github.com/Ark0N/Codeman/issues">Issues</a>.
+</p>

README.zh-CN.md

@@ -5,7 +5,7 @@
 <h2 align="center">AI 编程智能体的任务控制中心</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex —— 统一仪表盘 &bull; 任意设备</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
 </p>
 
 <p align="center">
@@ -14,39 +14,73 @@
 
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
-  <img src="https://img.shields.io/badge/Tests-2861%20total-22c55e?style=flat-square" alt="Tests">
+  <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) 翻译而来。如有出入，以英文版为准。
 
----
-
-## 快速开始 — 安装
+一行命令即可安装（macOS 和 Linux，Windows 通过 WSL）：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
+curl -fsSL https://getcodeman.com/install | bash
 ```
 
-该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。
-
-你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai) 或 [Codex](https://developers.openai.com/codex/cli)（任意组合均可）。安装完成后：
-
 ```bash
 codeman web
 # 打开 http://localhost:3000，开启你的第一个会话
 ```
 
+安装器在每次系统改动前都会先询问；重跑同一条命令即可原地更新。详见[快速开始 — 安装](#快速开始--安装)。
+
+---
+
+## 快速开始 — 安装
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+```
+
+该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。几点须知：
+
+- **先询问，后改动。** 所有系统级改动（安装软件包、下载 AI CLI）都会先征求确认；结束时的菜单可选择：直接在本终端运行、安装为后台服务（systemd/launchd，开机自启），或暂不启动。不选就不会有任何后台进程。
+- **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。也可以使用 `install.sh update` 与 `install.sh uninstall`。
+- **CI / 无终端环境：** 没有终端时，涉及系统改动的步骤会带着说明中止，而不是静默执行；在自动化场景设置 `CODEMAN_NONINTERACTIVE=1` 即可批准这些步骤。
+
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)（任意组合均可）。安装器会自动检测这四个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
+
+```bash
+codeman web
+# 打开 http://localhost:3000，开启你的第一个会话
+```
+
+**想和小团队共用一台？** 改用多用户模式启动：每人拥有自己的登录与工作空间。
+
+```bash
+codeman users add alice --admin      # 创建第一个管理员账号
+codeman web --multiuser              # 命名登录 + 按用户隔离的案例空间
+```
+
+详见下文[多用户模式](#多用户模式可选启用)。
+
 <details>
 <summary><strong>作为后台服务运行</strong></summary>
 
+安装器结尾的菜单（选项 2）可以帮你完成这一步，并在宣告成功前校验服务确实已启动。如需手动配置：
+
 **Linux（systemd）：**
+
 ```bash
 mkdir -p ~/.config/systemd/user
 cat > ~/.config/systemd/user/codeman-web.service << EOF
@@ -69,6 +103,7 @@ loginctl enable-linger $USER
 ```
 
 **macOS（launchd）：**
+
 ```bash
 mkdir -p ~/Library/LaunchAgents
 cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
@@ -96,16 +131,18 @@ cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
 EOF
 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 ```
+
 </details>
 
 <details>
 <summary><strong>Windows（WSL）</strong></summary>
 
 ```powershell
-wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
+wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai) 或 [Codex](https://developers.openai.com/codex/cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+
 </details>
 
 ---
@@ -116,14 +153,12 @@ Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.
 
 <table>
 <tr>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="移动端 — 带二维码认证的登录页" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="移动端 — 带键盘配件栏的空闲会话" width="260"></td>
-<td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="移动端 — 活动中的智能体会话" width="260"></td>
+<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="300"></td>
+<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="440"></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>
+<td align="center"><em>配件栏 + 独立 Enter 按钮</em></td>
 </tr>
 </table>
 
@@ -142,23 +177,10 @@ Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.
 <tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
 </table>
 
-### 安全的二维码认证
-
-在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
-
-每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
-
-该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
-
-### 触控优化界面
-
-- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮。破坏性命令（`/clear`、`/compact`）需双击确认 —— 第一次点击「上膛」，第二次点击执行 —— 这样在颠簸的通勤路上也不会误触
-- **滑动导航** —— 在终端上左右滑动切换会话（阈值 80px，300ms）
-- **智能键盘处理** —— 键盘弹出时工具栏与终端整体上移（使用 `visualViewport` API，并对 iOS 地址栏漂移设置 100px 阈值）
-- **安全区适配** —— 通过 `env(safe-area-inset-*)` 适配 iPhone 刘海与底部 Home 指示条
-- **44px 触控目标** —— 所有按钮均满足 iOS 人机界面指南的最小尺寸
-- **底部抽屉式 case 选择器** —— 用上滑模态框替代桌面端下拉菜单
-- **原生惯性滚动** —— `-webkit-overflow-scrolling: touch`，丝滑流畅
+- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触
+- **独立的 Enter 按钮** —— 以按键方式回放，先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上
+- **滑动导航与智能键盘处理** —— 左右滑动切换会话；键盘弹出时工具栏与终端整体上移（`visualViewport` API）
+- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
 
 ```bash
 codeman web --https
@@ -167,30 +189,86 @@ codeman web --https
 
 > `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
 
+### 安全的二维码认证
+
+在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
+
+每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
+
+该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
+
 ---
 
-## 实时智能体可视化
+## 使用 Codeman —— 人类操作指南
 
-实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
+从头到尾走一遍如何在浏览器里驾驭 Codeman。如果你刚装好，就从这里开始。
 
-<p align="center">
-  <img src="docs/images/subagent-spawn.png" alt="子智能体可视化" width="900">
-</p>
+### 1. 启动服务器
 
-- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
-- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
-- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
-- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「AGENT」或「AGENTS (n)」计数
-- **嵌套智能体** —— 支持 3 层层级（主会话 → 团队成员智能体 → 子-子智能体）
+```bash
+codeman web                       # localhost:3000（仅环回 —— 安全默认值）
+codeman web --port 8080           # 自定义端口（或设置 CODEMAN_PORT）
+codeman web --https               # 自签名 TLS（仅远程访问时需要）
+codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_PASSWORD（见「安全」）
+```
 
-**智能体团队（Agent Teams）** —— 一等公民式支持 Claude Code 原生的多智能体团队（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）。`TeamWatcher` 轮询 `~/.claude/teams/`，将团队成员匹配到其主会话，并以实时子智能体窗口呈现，且具备**团队感知的空闲检测** —— 因此当团队成员仍在工作时，重生控制器不会被触发。详见 [`docs/agent-teams/`](docs/agent-teams/)。
+打开打印出的 URL。整个页面是一个单一仪表盘；下面的一切都在这里完成。
+
+### 2. 创建你的第一个会话
+
+点击 **+ New Session**（或 **Quick Start**）。一个会话就是一个运行在自己 tmux 终端里的 AI CLI。你可以选择：
+
+| 字段                   | 作用                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。                           |
+| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Gemini` 或 `Terminal`（普通 shell）。               |
+| **模型**               | 每会话模型（App Settings → Claude Model）。软默认值 —— 会话内 `/model` 依然有效。           |
+| **Effort / Ultracode** | 推理力度（`low`–`max`），或用 `ultracode` 开启动态多智能体工作流。随时可用 `/effort` 切换。 |
+
+点击启动 —— Codeman 通过真实 PTY 拉起 CLI，并经 SSE 流式传输到你的浏览器。
+
+### 3. 读懂仪表盘
+
+- **标签（顶部）** —— 每个会话一个。`Alt+1`–`9` 跳转，`Ctrl+Tab` 下一个，拖拽排序（标签顺序会跨设备同步）。
+- **终端（中央）** —— 真实的 `xterm.js` 终端；完整 TUI 正常渲染。直接输入并按 **Enter** 发送。`Shift+Enter` 插入换行。
+- **侧边面板** —— Respawn、Orchestrator、Cron、Subagents、Settings（从工具栏切换）。
+
+### 4. 与智能体对话
+
+- **直接在终端输入提示** —— 即使跨越重连，输入也是精确一次送达（连接中断绝不会丢失或重复发送提示）。
+- **粘贴或拖放图片**，直接进入会话。
+- **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，自动静音停止）。
+- **附件** —— 注册外部文件/文档，并内联预览 Office/PDF。
+
+### 5. 让它自主运行
+
+| 模式             | 用途                                                                                                      | 位置                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Respawn**      | 长时间无人值守运行 —— 空闲/限额时自动重启 CLI，带自适应时序。预设：`solo-work`、`overnight-autonomous` 等 | Respawn 标签页                                                     |
+| **Orchestrator** | 把一个目标变成分阶段计划，并跨多个智能体推动完成。                                                        | 编排器面板                                                         |
+| **Cron**         | 已保存的、命名的定时任务（`once`/`interval`/`daily`/`weekly`），到期时拉起会话并发送提示。                | ⏰ Cron 按钮（可选启用：App Settings → Display → Header Displays） |
+| **Auto-resume**  | 订阅限额重置后自动继续。                                                                                  | Respawn 标签页（顶部）                                             |
+
+### 6. 随时随地访问
+
+- **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
+- **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
+- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+
+### 7. 运维与维护
+
+- **App Settings** —— 模型、effort、权限启动模式、主题/皮肤、通知、显示开关、各 CLI 的专属选项，以及跨设备同步的自定义显示名称和按设备保存的英文/简体中文界面语言。
+- **自更新** —— git-clone 安装可在 **Settings → Updates** 中原地更新。
+- **部署你自己的改动** —— 见[开发](#开发)。
+
+> ⚠️ **安全提示：** 如果你正在 Codeman 受管会话*内部*工作（`echo $CODEMAN_MUX` → `1`），绝不要直接运行 `tmux kill-session` / `pkill claude` —— 请使用 Web UI 或 `./scripts/tmux-manager.sh`。
 
 ---
 
 ## 零延迟输入叠加层
 
 <p align="center">
-  <img src="docs/images/zerolag-demo.gif" alt="Zerolag 演示 —— 本地回显与服务端回显并排对比" width="900">
+  <img src="docs/images/zerolag-demo-20260728.gif" alt="Zerolag 演示：两台手机并排对比，即时本地回显与 600ms-2.7s 服务端回显" width="900">
 </p>
 
 远程访问你的编程智能体时（VPN、Tailscale、SSH 隧道），每次按键通常需要 200–300 毫秒往返。Codeman 实现了一套**受 Mosh 启发的本地回显系统**，无论延迟多高，打字都感觉即时。
@@ -207,6 +285,30 @@ xterm.js 内部一个像素级精准的 DOM 叠加层以 0ms 渲染按键。后
 
 ---
 
+## 实时智能体可视化
+
+实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。
+
+<p align="center">
+  <img src="docs/images/subagent-windows-20260724.png" alt="子智能体可视化 —— 三个并行 Explore 智能体的浮动窗口与实时工具调用日志" width="900">
+</p>
+
+- **浮动终端窗口** —— 每个智能体一个可拖拽、可调整大小的面板，带实时活动日志，逐条展示每一次工具调用、文件读取与进度更新
+- **连接线** —— 用动态绿色线条连接父会话与其子智能体，随智能体的产生与完成实时更新
+- **状态与模型徽标** —— 绿色（活动）、黄色（空闲）、蓝色（已完成）指示，并以 Haiku/Sonnet/Opus 的颜色编码区分模型
+- **自动行为** —— 窗口在产生时自动打开、完成时自动最小化，标签徽标显示「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/)。
+
+---
+
 ## 重生控制器（Respawn Controller）
 
 自主工作的核心。当智能体进入空闲，重生控制器会检测到，发送继续提示，循环执行上下文管理命令以获得全新上下文，然后恢复工作 —— 可完全无人值守运行 **24 小时以上**。
@@ -216,7 +318,7 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 ```
 
 - **多层空闲检测** —— 完成消息、AI 驱动的空闲检查、输出静默、token 稳定性
-- **用量限额自动恢复**（*可选，默认关闭*）—— 当 Claude 因订阅用量限额而停止（"You've hit your limit · resets 3pm"）时，Codeman 会解析重置时间，等到限额刷新（外加 2 分钟安全缓冲）后自动关闭限额对话框并发送 `continue`，让通宵任务平稳跨过 5 小时窗口而不是停摆到早晨。可识别 Claude Code 各版本的全部限额消息格式；若仍受限会自动重试；计划在 Codeman 重启后依然生效；暂停期间会阻止重生循环，避免 `/clear` 清掉等待中的对话。在会话 Respawn 标签页顶部按会话启用
+- **用量限额自动恢复**（_可选，默认关闭_）—— 当 Claude 因订阅用量限额而停止（"You've hit your limit · resets 3pm"）时，Codeman 会解析重置时间，等到限额刷新（外加 2 分钟安全缓冲）后自动关闭限额对话框并发送 `continue`，让通宵任务平稳跨过 5 小时窗口而不是停摆到早晨。可识别 Claude Code 各版本的全部限额消息格式；若仍受限会自动重试；计划在 Codeman 重启后依然生效；暂停期间会阻止重生循环，避免 `/clear` 清掉等待中的对话。在会话 Respawn 标签页顶部按会话启用
 - **熔断器** —— 当 Claude 卡住时防止重生抖动（CLOSED → HALF_OPEN → OPEN 状态，跟踪连续无进展与重复错误）
 - **健康评分** —— 0–100 健康分，分项涵盖循环成功率、熔断器状态、迭代进展与卡死恢复
 - **内置预设** —— `solo-work`（3s 空闲，60min）、`subagent-workflow`（45s，240min）、`team-lead`（90s，480min）、`ralph-todo`（8s，480min）、`overnight-autonomous`（10s，480min）
@@ -233,7 +335,7 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 - **崩溃安全** —— 完整状态持久化在 `state.json` 的 `orchestrator` 键下，可在重启后存续
 - **可从 UI 或 API 驱动** —— 编排器面板，或 `POST /api/orchestrator/start` → `/approve` → `/status`（共 10 个端点）
 
-> 与 Ralph（单会话自主循环）不同：编排器协调多阶段、多智能体执行。完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
+> 完整设计：[`docs/orchestrator-loop-architecture.md`](docs/orchestrator-loop-architecture.md)。
 
 ---
 
@@ -241,14 +343,18 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 
 运行 **20 个并行会话**且全程可见 —— 60fps 的实时 xterm.js 终端、按会话的 token 与成本跟踪、基于标签的导航，以及一键管理。
 
-<p align="center">
-  <img src="docs/screenshots/multi-session-dashboard.png" alt="多会话仪表盘" width="800">
-</p>
-
 ### 持久化会话
 
 每个会话都运行在 **tmux** 内 —— 会话可在服务器重启、网络中断与机器休眠后存续。启动时自动恢复，具备双重冗余。幽灵会话发现机制能找到孤立的 tmux 会话。受管会话带有环境标签，因此智能体不会杀掉自己的会话。
 
+### 会话管理器与命令面板
+
+`Ctrl/Cmd/Alt+K` 打开模糊搜索的会话面板；**Browse all sessions** 打开会话管理器：一份去重后的完整清单，涵盖 Codeman 所知的一切（活动会话、来自状态与生命周期历史的既往会话，以及 Claude 转录），每一行都显示其第一条与最近一条提示。
+
+- **置顶（Pin）**：把会话固定到列表顶部。被置顶的会话甚至能挺过被杀掉（降级为一条轻量的已停止记录，依然可见、可恢复）。
+- **名称保留**：从会话管理器恢复既往会话时保留其原有名称，而不是生成一个新名称。
+- **跨设备标签顺序**：拖拽排序的标签顺序保存在服务端，你的排列会从桌面跟随到手机。
+
 ### 主机名感知的窗口标题
 
 在多台主机上运行 Codeman（笔记本、开发机、NAS）？浏览器标签标题是 `codeman:<主机名>`，让你无需点进去就能分辨每个标签对应哪个后端：
@@ -262,23 +368,15 @@ codeman web --title-hostname dev-box       # codeman:dev-box（用于覆盖嘈
 
 ### 智能 Token 管理
 
-| 阈值 | 动作 | 结果 |
-|-----------|--------|--------|
+| 阈值            | 动作            | 结果                   |
+| --------------- | --------------- | ---------------------- |
 | **110k tokens** | 自动 `/compact` | 上下文被摘要，工作继续 |
-| **140k tokens** | 自动 `/clear` | 以 `/init` 全新开始 |
+| **140k tokens** | 自动 `/clear`   | 以 `/init` 全新开始    |
 
 ### 通知
 
 当会话需要关注时实时桌面提醒 —— `permission_prompt` 与 `elicitation_dialog` 触发关键的红色标签闪烁，`idle_prompt` 触发黄色闪烁。点击任意通知即可直接跳转到相关会话。Hook 按 case 目录自动配置。
 
-### Ralph / Todo 跟踪
-
-自动检测 Ralph 循环、`<promise>` 标签、TodoWrite 进度（`4/9 complete`）以及迭代计数器（`[5/50]`），并提供实时进度环与已用时间跟踪。
-
-<p align="center">
-  <img src="docs/images/ralph-tracker-8tasks-44percent.png" alt="Ralph 循环跟踪" width="800">
-</p>
-
 ### 运行摘要（Run Summary）
 
 点击任意会话标签上的图表图标，即可看到所发生一切的时间线 —— 重生周期、token 里程碑、自动 compact 触发、空闲/工作切换、hook 事件、错误等等。
@@ -296,17 +394,70 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 ## 更多特性
 
 - **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
-- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode** 或 **Codex**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*` 与 `CODEX_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex** 或 **Gemini**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **Docker 会话** —— 在隔离且加固的容器中运行案例。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一案例的多个会话共享一个容器；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
+- **远程 SSH 会话**：把案例指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
 - **语音输入** —— 用 Deepgram Nova-3 口述提示（带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
 - **图像输入** —— 直接把图片粘贴或拖放进会话
-- **手势控制** *(可选)* —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Display 启用
-- **多显示器横跨** *(macOS)* —— 一键打开一个横跨所有显示器最大化的浏览器窗口，让浮动的智能体/手势面板可以跨越物理拼接缝
+- **手势控制** _(可选)_ —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Display 启用
+- **多显示器横跨** _(macOS)_ —— 一键打开一个横跨所有显示器最大化的浏览器窗口，让浮动的智能体/手势面板可以跨越物理拼接缝
+- **文件查看器按钮** _(可选)_ —— 头部新增一个按钮，一键切换内置文件浏览器面板；在 App Settings → Display → Header Displays 中启用
 - **CJK / 输入法支持** —— 完整支持中文 / 日文 / 韩文的组合输入
 - **操作系统通知与主机名感知标题** —— 桌面提醒与标签标题以 `codeman:<host>` 为前缀，使多主机配置不再含糊
 
 ---
 
+## 隔离的 Docker 会话
+
+让案例（case）运行在专属的加固 Docker 容器里，而不是直接跑在主机上：获得安全隔离、可复现的工具链和一键可移植性。
+
+- **一键启动** —— 在 **New Case → Create New** 中勾选 **🐳 Run in an isolated Docker container**。Codeman 会创建案例文件夹、用默认设置启动容器，并在容器内启动智能体。无需填写任何主机/镜像/网络字段。
+- **资源模板** —— 展开复选框可选 **Small / Medium / Large / GPU** 预设（内存、CPU、GPU），也可以完全自定义。**磁盘是弹性的** —— 存储随数据增长，没有固定上限。
+- **按案例共享容器** —— 多个会话可以 `docker exec` 进同一个容器；结束某个会话绝不会影响其他会话所在的容器。
+- **默认加固** —— 非 root、`--cap-drop ALL`、`no-new-privileges`、PID/内存上限，绝不使用 `--privileged` 或 docker socket；**密封（sealed）** 配置（不注入主机凭据、关闭网络）只需一个开关。
+- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Gemini / OpenCode 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
+- **迁移到另一台机器** —— 把容器的完整环境（工具链 + 工作区）导出为可移植的 `.tar.gz`，在另一台机器上导入到新案例即可继续。
+- **持久耐用** —— Codeman 重启后重连会回到同一个存活的智能体；容器停止/重启后则从绑定挂载的转录恢复对话。
+
+前置条件：只需 Docker（或 Podman）。智能体基础镜像会在首次使用时自动构建，构建进度实时显示在 UI 中（也可用 `node scripts/build-agent-image.mjs` 预构建）。完整指南：[`docs/docker-cases.md`](docs/docker-cases.md)。
+
+---
+
+## 远程 SSH 会话
+
+把案例（case）指向另一台机器，通过 SSH 让智能体**在那台机器上**运行，同时保留同样的仪表盘、移动端 UI 与自主运行特性。你的笔记本只是一扇窗口，会话本体活在远程主机上。
+
+- **天生持久**：智能体运行在远程主机上一个专用的 tmux 会话里，SSH 断连、网络切换或笔记本休眠都不会中断任务。重新连接后回到同一个活跃对话。
+- **自动重连**：一个带上限退避的监视器发现 SSH 面板断开后，会静默重新附着到仍在运行的远程会话（设置中有总开关；主动杀掉的会话绝不会被复活）。
+- **发现与附着**：列出主机上已在运行的 `codeman-*` 会话（由那台机器自己的 Codeman 或其他操作者启动）并附着其一。非你所有的已附着会话在关闭标签时**只分离，绝不杀掉**。
+- **共享会话**：多个客户端可以以不同窗口尺寸同时附着同一个远程会话而互不挤压；发现列表会显示带客户端计数的「shared」徽标。
+- **注入安全**：所有 ssh 命令行都经由单一的 shell 转义构建器生成，主机/路径/身份文件字段均有模式校验。
+
+在 **New Case → Remote** 中配置（主机、用户、身份文件、可选跳板机）。完整设计：[`docs/remote-sessions.md`](docs/remote-sessions.md)。
+
+---
+
+## 多用户模式（可选启用）
+
+与一个小型互信团队共享同一个 Codeman，每人拥有自己的登录与工作空间。**默认关闭**：不加该开关时，行为与单用户完全一致。
+
+用 `codeman web --multiuser`（或 `CODEMAN_MULTIUSER=1`）启用。创建第一个管理员后，可通过 CLI 或 App Settings 中的 **Users** 标签页管理用户：
+
+```bash
+codeman users add alice --admin      # 提示输入密码（或 --password-stdin）
+codeman users add bob                # 普通用户
+codeman users list
+```
+
+- **按用户的空间**：每个用户的案例位于 `~/codeman-users/<name>/cases`；会话、案例、搜索与实时事件都按属主隔离。管理员可以看到全部。
+- **可单独吊销的登录**：命名用户的密码以 scrypt 哈希保存在 `~/.codeman/users.json`；可随时禁用、重置（一次性密码）或删除账号。管理员操作审计记录在 `~/.codeman/admin-audit.jsonl`。
+- **普通用户的更安全默认值**：非管理员以 `--permission-mode auto` 运行 Claude（Anthropic 的分类器护栏模式）；raw shell 会话、cron `launchCommand` 与跳过权限模式需要按用户显式授权。
+
+> ⚠️ **这只是工作空间的划分，不是用户之间的沙箱。** 所有会话都以同一个操作系统账户运行，因此有心用户的智能体依然能触及他人的文件。若需要真正的隔离，请结合 **Docker 案例**，或在不同的操作系统账户下运行独立实例。参见 [`docs/multi-user-plan.md`](docs/multi-user-plan.md) 与 [`docs/security-architecture.md`](docs/security-architecture.md) 的多用户章节。
+
+---
+
 ## 远程访问 —— Cloudflare 隧道
 
 使用免费的 [Cloudflare 快速隧道](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)，从手机或本地网络外的任意设备访问 Codeman —— 无需端口转发、无需 DNS、无需静态 IP。
@@ -374,14 +525,14 @@ loginctl enable-linger $USER
 
 该设计参考了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025），该研究发现 Top-100 网站中有 47 个因横跨 42 个 CVE 的 6 个关键设计缺陷而易受二维码认证攻击。Codeman 全部六个都做了应对：
 
-| USENIX 缺陷 | 缓解措施 |
-|-------------|------------|
-| **缺陷 1**：缺少一次性强制 | 令牌首次扫描即原子性消费 —— 重放永远失败 |
-| **缺陷 2**：长生命周期令牌 | 60s TTL + 90s 宽限，由定时器自动轮换 |
-| **缺陷 3**：可预测的令牌生成 | `crypto.randomBytes(32)` —— 256 位熵。短码采用拒绝采样以消除取模偏差 |
-| **缺陷 4**：客户端令牌生成 | 仅服务端 —— 令牌在嵌入二维码前绝不离开服务器 |
-| **缺陷 5**：缺少状态通知 | 桌面提示：*「设备 [IP] 已通过二维码认证（Safari）。不是你？[吊销]」* —— 实时 QRLjacking 检测 |
-| **缺陷 6**：会话绑定不足 | 存储 IP + User-Agent 以供审计。通过 API 手动吊销会话。HttpOnly + Secure + SameSite=lax cookie |
+| USENIX 缺陷                  | 缓解措施                                                                                      |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| **缺陷 1**：缺少一次性强制   | 令牌首次扫描即原子性消费 —— 重放永远失败                                                      |
+| **缺陷 2**：长生命周期令牌   | 60s TTL + 90s 宽限，由定时器自动轮换                                                          |
+| **缺陷 3**：可预测的令牌生成 | `crypto.randomBytes(32)` —— 256 位熵。短码采用拒绝采样以消除取模偏差                          |
+| **缺陷 4**：客户端令牌生成   | 仅服务端 —— 令牌在嵌入二维码前绝不离开服务器                                                  |
+| **缺陷 5**：缺少状态通知     | 桌面提示：_「设备 [IP] 已通过二维码认证（Safari）。不是你？[吊销]」_ —— 实时 QRLjacking 检测  |
+| **缺陷 6**：会话绑定不足     | 存储 IP + User-Agent 以供审计。通过 API 手动吊销会话。HttpOnly + Secure + SameSite=lax cookie |
 
 #### 时序安全的查找
 
@@ -406,23 +557,23 @@ URL 被刻意保持精简（`/q/` 路径 + 6 字符码 ≈ 53–56 个字符）
 
 #### 威胁覆盖
 
-| 威胁 | 为何无效 |
-|--------|-------------------|
-| **二维码截图被分享** | 一次性：首次扫描即消费。60s TTL：攻击者动手前已过期。桌面通知会立即提醒你。 |
-| **重放攻击** | 原子性一次性消费 + 60s TTL。旧 URL 始终返回 401。 |
+| 威胁                    | 为何无效                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| **二维码截图被分享**    | 一次性：首次扫描即消费。60s TTL：攻击者动手前已过期。桌面通知会立即提醒你。          |
+| **重放攻击**            | 原子性一次性消费 + 60s TTL。旧 URL 始终返回 401。                                    |
 | **Cloudflare 边缘日志** | 短码是不透明的 6 字符查找键，而非真正的 256 位令牌。一次性意味着从日志重放永远失败。 |
-| **暴力破解** | 568 亿种组合、任意时刻约 2 个有效、双层速率限制，早在统计可行性之前就已拦截。 |
-| **QRLjacking** | 60s 轮换迫使实时转发。桌面提示提供即时检测。自托管单用户场景使钓鱼难以成立。 |
-| **时序攻击** | 基于哈希的 Map 查找 —— 无字符串比较时序泄露。 |
-| **会话 cookie 窃取** | HttpOnly + Secure + SameSite=lax + 24h TTL。可在 `POST /api/auth/revoke` 手动吊销。 |
+| **暴力破解**            | 568 亿种组合、任意时刻约 2 个有效、双层速率限制，早在统计可行性之前就已拦截。        |
+| **QRLjacking**          | 60s 轮换迫使实时转发。桌面提示提供即时检测。自托管单用户场景使钓鱼难以成立。         |
+| **时序攻击**            | 基于哈希的 Map 查找 —— 无字符串比较时序泄露。                                        |
+| **会话 cookie 窃取**    | HttpOnly + Secure + SameSite=lax + 24h TTL。可在 `POST /api/auth/revoke` 手动吊销。  |
 
 #### 横向对比
 
-| 平台 | 模型 | 对比 |
-|----------|-------|------------|
-| **Discord** | 长生命周期令牌、无确认、[屡被利用](https://owasp.org/www-community/attacks/Qrljacking) | Codeman：一次性 + TTL + 通知 |
-| **WhatsApp Web** | 手机确认「关联设备？」，约 60s 轮换 | 轮换相当；WhatsApp 额外加了显式确认（对单用户而言是可接受的取舍） |
-| **Signal** | 临时公钥、端到端加密信道 | 加密更强，但 [2025 年仍被俄罗斯国家级行为者](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger)通过社会工程攻破 |
+| 平台             | 模型                                                                                   | 对比                                                                                                                                                     |
+| ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Discord**      | 长生命周期令牌、无确认、[屡被利用](https://owasp.org/www-community/attacks/Qrljacking) | Codeman：一次性 + TTL + 通知                                                                                                                             |
+| **WhatsApp Web** | 手机确认「关联设备？」，约 60s 轮换                                                    | 轮换相当；WhatsApp 额外加了显式确认（对单用户而言是可接受的取舍）                                                                                        |
+| **Signal**       | 临时公钥、端到端加密信道                                                               | 加密更强，但 [2025 年仍被俄罗斯国家级行为者](https://cloud.google.com/blog/topics/threat-intelligence/russia-targeting-signal-messenger)通过社会工程攻破 |
 
 > 完整设计理由、安全分析与实现细节：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
 
@@ -430,13 +581,14 @@ 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)。
+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)。
 
 ### 网络与访问
 
 - **默认仅环回** —— 绑定 `127.0.0.1`，仅可从本机访问，因此「无密码」默认配置开箱即安全。在未设置 `CODEMAN_PASSWORD` 的情况下绑定非环回主机会*启动但打印一条醒目警告*，并给出三个具体修复方案（设置密码、环回 + 一个带认证的隧道，或用 `--allow-unauthenticated-network` 显式确认）
 - **可选认证，真实会话** —— 通过 `CODEMAN_USERNAME`（默认 `admin`）/ `CODEMAN_PASSWORD` 的 HTTP Basic 认证。成功后签发一个不透明的 256 位 `codeman_session` cookie（`randomBytes(32)`）—— 服务端校验，而非客户端签名，因此无法离线伪造（24h TTL、自动延长、设备上下文审计日志）
 - **按 IP 速率限制** —— 失败 10 次 → `429` 并带 `Retry-After`（15 分钟衰减）。即便攻击者在同一 IP 上猛攻，有效 cookie 或正确密码也能*立即*恢复 —— 这很重要，因为所有隧道流量共享同一个环回 IP。二维码认证有自己独立的限制器
+- **可配置的权限模式**：`--dangerously-skip-permissions` 只是默认值。**App Settings → Claude CLI → Startup Mode** 可以把新会话切换为 Anthropic 的分类器护栏 `auto` 模式（低打扰，需要 Claude Code 2.1.207+）、`normal` 提示模式，或一份显式的允许工具列表。多用户模式下，未获授权的用户会被强制为 `auto`，shell 会话与跳过权限需要按用户显式授权
 
 ### 始终开启的浏览器加固（v0.9.5）
 
@@ -450,7 +602,7 @@ Codeman 用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设
 
 ### 输入、文件与响应头
 
-- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
 - **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 50 MB 原始与下载；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
 - **安全响应头** —— `Content-Security-Policy`（`default-src 'self'`，每个例外都逐条列举）、`X-Content-Type-Options: nosniff`、`X-Frame-Options: SAMEORIGIN`、HTTPS 下的 HSTS，以及**仅**对 `localhost` / `127.0.0.1` / `::1` 反射的 CORS
 
@@ -481,73 +633,172 @@ sc -l           # 列出会话
 
 > Ctrl 绑定在 macOS 上也接受 Cmd。
 
-| 快捷键 | 动作 |
-|----------|--------|
-| `Ctrl/Cmd+W` | 杀掉当前会话 |
-| `Ctrl/Cmd+Tab` | 下一个会话 |
-| `Alt+1`–`Alt+9` | 切换到第 N 个标签 |
-| `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移 |
-| `Ctrl/Cmd+L` | 清屏 |
-| `Ctrl+Shift+R` | 恢复终端尺寸 |
-| `Ctrl+Shift+V` | 切换语音输入 |
-| `Ctrl/Cmd +` / `-` | 字体大小 |
-| `Ctrl/Cmd+?` | 键盘帮助 |
-| `Shift+Enter` | 插入换行（发送到终端） |
-| `Escape` | 关闭面板与模态框 |
+| 快捷键                          | 动作                                                     |
+| ------------------------------- | -------------------------------------------------------- |
+| `Ctrl/Cmd+W`                    | 杀掉当前会话                                             |
+| `Ctrl/Cmd/Option+K`             | 查找已打开的会话或新建一个                               |
+| `Ctrl/Cmd+Tab`                  | 下一个会话                                               |
+| `Alt/Option+[` / `Alt/Option+]` | 上一个 / 下一个会话                                      |
+| `Alt/Option+1`–`Alt/Option+9`   | 切换到第 N 个标签（按物理键位，macOS Option 布局也适用） |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移                                    |
+| `Ctrl/Cmd+L`                    | 清屏                                                     |
+| `Ctrl+Shift+R`                  | 恢复终端尺寸                                             |
+| `Ctrl+Shift+V`                  | 切换语音输入                                             |
+| `Ctrl/Cmd +` / `-`              | 字体大小                                                 |
+| `Ctrl/Cmd+?`                    | 键盘帮助                                                 |
+| `Shift+Enter`                   | 插入换行（发送到终端）                                   |
+| `Escape`                        | 关闭面板与模态框                                         |
+
+---
+
+## 从智能体驱动 Codeman —— 编程指南
+
+面向不经浏览器控制 Codeman 的 AI 智能体与自动化：一个拉起工作会话的智能体、一个 CI 机器人，或是**运行在 Codeman 会话*内部*、编排其他会话的 Claude Code**。UI 能做的一切都是 HTTP + CLI，因此智能体也能做。
+
+### 检测自己身处 Codeman 内部
+
+当 CLI 运行在 Codeman 受管会话中时，以下环境变量会被设置 —— 读取它们，别硬编码任何东西：
+
+| 变量                       | 含义                                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `CODEMAN_MUX=1`            | 你在一个受管 tmux 会话里。**绝不要** `tmux kill-session` / `pkill claude` / `pkill tmux` —— 你会杀掉自己或兄弟会话。 |
+| `CODEMAN_API_URL`          | API 的基础 URL（例如 `https://127.0.0.1:3000`）。下面每个调用都用它。                                                |
+| `CODEMAN_SESSION_ID`       | *你自己的*会话 id。用它避免对自己下手。                                                                              |
+| `CODEMAN_HOOK_SECRET_FILE` | hook 密钥文件的路径（受管隧道开启时调用 `/api/hook-event` 必需）。                                                   |
+
+### 行路规则（POST 之前先读）
+
+1. **只发单行输入。** 编程输入会作为字面文本 **+ Enter** 一次性发送。多行字符串会破坏智能体 TUI（Ink）—— 发送一行，或拆成多次调用。
+2. **让输入幂等。** 在 `POST …/input` 上带上稳定的 `clientId` 和按会话单调递增的 `seq`。服务端会去重，因此连接中断后的重试不会重复投递提示。
+3. **认证。** 若设置了 `CODEMAN_PASSWORD`，发送 HTTP Basic 认证（用户 `admin` 或 `CODEMAN_USERNAME`）或 `codeman_session` cookie。默认的环回安装无密码。缺失的 `Origin` 头被允许，因此普通 `curl` 可用；跨站的浏览器 origin 会被拒绝（CSRF 防护）。
+4. **响应信封。** 多数端点返回 `{ "success": true, "data": … }`（错误：`{ "success": false, "error", "errorCode" }`）。少数遗留 GET 返回裸响应体 —— **两种都要处理**（`body.data ?? body`）。
+5. **`/api/v1/*`** 是 `/api/*` 的稳定别名。
+
+### 常用配方
+
+```bash
+API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
+# （若设置了密码，给每个调用加上  -u admin:"$CODEMAN_PASSWORD"）
+
+# 1. 看看有什么在运行
+curl -s "$API/api/sessions" | jq '.data // .'
+
+# 2. 拉起一个工作会话（「case」= 命名工作目录）
+curl -s -X POST "$API/api/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
+
+# 3. 向会话发送提示（精确一次：clientId + seq）
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+
+# 4. 读回终端内容
+curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+
+# 5. 流式接收实时事件（会话输出、智能体活动、状态）
+curl -sN "$API/api/events"          # Server-Sent Events
+
+# 6. 调度周期性工作（cron 风格任务）
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
+       "promptMode":"inline_text","promptText":"Update dependencies and open a PR",
+       "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
+       "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
+
+# 7. 查看后台子智能体及其活动记录
+curl -s "$API/api/subagents" | jq '.data // .'
+curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
+
+# 8. 全系统快照（会话、设置、重生、统计）
+curl -s "$API/api/status" | jq
+```
+
+### 或使用内置 CLI
+
+同样的操作也有命令形式（`codeman <cmd>`，括号内为别名）—— 在会话内的 shell 工具里很顺手：
+
+```bash
+codeman session start -d /path/to/repo   # (s)  启动会话
+codeman session list                     #      列出会话
+codeman session logs <id>                #      查看输出
+codeman task add "fix the failing test"  # (t)  排入任务
+codeman attach <path>                    #      附着 Claude hook 上下文
+```
+
+### Hook（事件*回流*到 Codeman）
+
+Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission_prompt`、`idle_prompt`、`stop`、`task_completed` 等），让仪表盘实时响应。该端点在环回上免认证，但在受管隧道下需要 `X-Codeman-Hook-Secret` 头（从 `$CODEMAN_HOOK_SECRET_FILE` 读取）。通常你不需要手动调用它 —— Codeman 会自动接好 —— 但自主层正是靠它「看见」智能体在做什么。
+
+> 完整端点列表与请求/响应形状见下文。
 
 ---
 
 ## API
 
-基于 Fastify 的 REST —— **15 个路由模块中约 140 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。以下是一个有代表性的子集：
+基于 Fastify 的 REST —— **20 个路由模块中约 190 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。所有响应都使用 `ApiResponse<T>` 信封（`{success, data}` / `{success, error, errorCode}`）；`/api/v1/*` 是稳定别名。以下是一个有代表性的子集：
 
 ### 会话（Sessions）
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `GET` | `/api/sessions` | 列出全部 |
-| `POST` | `/api/quick-start` | 创建 case 并启动会话 |
-| `DELETE` | `/api/sessions/:id` | 删除会话 |
-| `POST` | `/api/sessions/:id/input` | 发送输入 |
+
+| 方法     | 端点                       | 说明                                                                           |
+| -------- | -------------------------- | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/sessions`            | 列出全部                                                                       |
+| `POST`   | `/api/quick-start`         | 创建 case + 启动会话（`{caseName?, mode?, effort?, envOverrides?}`）           |
+| `POST`   | `/api/sessions/:id/input`  | 发送输入（`{input, useMux?, clientId?, seq?}` —— `clientId`+`seq` = 精确一次） |
+| `GET`    | `/api/sessions/:id/output` | 读取终端输出                                                                   |
+| `GET`    | `/api/sessions/unified`    | 统一的活动 + 历史清单（会话管理器）：`?q=&limit=`                              |
+| `POST`   | `/api/sessions/:id/pin`    | 在会话管理器中置顶 / 取消置顶（`{pinned}`）                                    |
+| `PUT`    | `/api/session-order`       | 跨设备同步标签顺序（`{order: [ids]}`）                                         |
+| `DELETE` | `/api/sessions/:id`        | 删除会话                                                                       |
 
 ### 重生（Respawn）
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `POST` | `/api/sessions/:id/respawn/enable` | 启用，带配置与定时器 |
-| `POST` | `/api/sessions/:id/respawn/stop` | 停止控制器 |
-| `PUT` | `/api/sessions/:id/respawn/config` | 更新配置 |
 
-### Ralph / Todo
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `GET` | `/api/sessions/:id/ralph-state` | 获取循环状态 + todos |
-| `POST` | `/api/sessions/:id/ralph-config` | 配置跟踪 |
+| 方法   | 端点                               | 说明                 |
+| ------ | ---------------------------------- | -------------------- |
+| `POST` | `/api/sessions/:id/respawn/enable` | 启用，带配置与定时器 |
+| `POST` | `/api/sessions/:id/respawn/stop`   | 停止控制器           |
+| `PUT`  | `/api/sessions/:id/respawn/config` | 更新配置             |
 
 ### 编排器（Orchestrator）
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `POST` | `/api/orchestrator/start` | 从目标启动编排 |
-| `POST` | `/api/orchestrator/approve` | 批准生成的计划 |
-| `GET` | `/api/orchestrator/status` | 当前阶段 + 进度 |
-| `POST` | `/api/orchestrator/stop` | 停止并清理 |
+
+| 方法   | 端点                        | 说明            |
+| ------ | --------------------------- | --------------- |
+| `POST` | `/api/orchestrator/start`   | 从目标启动编排  |
+| `POST` | `/api/orchestrator/approve` | 批准生成的计划  |
+| `GET`  | `/api/orchestrator/status`  | 当前阶段 + 进度 |
+| `POST` | `/api/orchestrator/stop`    | 停止并清理      |
+
+### Cron（定时任务）
+
+| 方法             | 端点                         | 说明                  |
+| ---------------- | ---------------------------- | --------------------- |
+| `GET` / `POST`   | `/api/cron/jobs`             | 列出 / 创建 cron 任务 |
+| `PUT` / `DELETE` | `/api/cron/jobs/:id`         | 更新 / 删除任务       |
+| `PUT`            | `/api/cron/jobs/:id/enabled` | 启用 / 禁用           |
+| `POST`           | `/api/cron/jobs/:id/run`     | 立即运行              |
+| `GET`            | `/api/cron/jobs/:id/runs`    | 运行历史              |
 
 ### 子智能体（Subagents）
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `GET` | `/api/subagents` | 列出所有后台智能体 |
-| `GET` | `/api/subagents/:id` | 智能体信息与状态 |
-| `GET` | `/api/subagents/:id/transcript` | 完整活动记录 |
-| `DELETE` | `/api/subagents/:id` | 杀掉智能体进程 |
+
+| 方法     | 端点                            | 说明               |
+| -------- | ------------------------------- | ------------------ |
+| `GET`    | `/api/subagents`                | 列出所有后台智能体 |
+| `GET`    | `/api/subagents/:id`            | 智能体信息与状态   |
+| `GET`    | `/api/subagents/:id/transcript` | 完整活动记录       |
+| `DELETE` | `/api/subagents/:id`            | 杀掉智能体进程     |
 
 ### 系统（System）
-| 方法 | 端点 | 说明 |
-|--------|----------|-------------|
-| `GET` | `/api/events` | SSE 流 |
-| `GET` | `/api/status` | 完整应用状态 |
-| `POST` | `/api/hook-event` | Hook 回调 |
-| `GET` | `/api/system/update/check` | 检查新发行版 |
-| `POST` | `/api/system/update` | 自更新（git-clone 安装） |
-| `POST` | `/api/clipboard` | 把文本推送到所有已连接浏览器（`{text}`） |
-| `GET` | `/api/sessions/:id/run-summary` | 时间线 + 统计 |
+
+| 方法   | 端点                            | 说明                                     |
+| ------ | ------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/events`                   | SSE 流                                   |
+| `GET`  | `/api/status`                   | 完整应用状态                             |
+| `POST` | `/api/hook-event`               | Hook 回调                                |
+| `GET`  | `/api/system/update/check`      | 检查新发行版                             |
+| `POST` | `/api/system/update`            | 自更新（git-clone 安装）                 |
+| `POST` | `/api/clipboard`                | 把文本推送到所有已连接浏览器（`{text}`） |
+| `GET`  | `/api/sessions/:id/run-summary` | 时间线 + 统计                            |
 
 ---
 
@@ -571,7 +822,6 @@ flowchart TB
         end
 
         subgraph Detection["检测层"]
-            RT["Ralph 跟踪器"]
             SW["子智能体监视器<br/><small>~/.claude/projects/*/subagents</small>"]
             TW["团队监视器<br/><small>~/.claude/teams/*</small>"]
         end
@@ -582,7 +832,7 @@ flowchart TB
         end
 
         subgraph External["外部"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
             BG["后台智能体<br/><small>(Task 工具)</small>"]
         end
     end
@@ -595,7 +845,6 @@ flowchart TB
     SM --> RC
     SM --> ORC
     SM --> SS
-    S1 --> RT
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
@@ -614,7 +863,7 @@ flowchart TB
 npm install
 npx tsx src/index.ts web    # 开发模式
 npm run build               # 生产构建
-npm test                    # 运行测试
+npm run test:ci             # 运行测试（CI 套件；浏览器套件需要额外环境）
 ```
 
 完整文档见 [CLAUDE.md](./CLAUDE.md)。
@@ -625,14 +874,14 @@ npm test                    # 运行测试
 
 本代码库经历了一次全面的 7 阶段重构，消除了上帝对象、集中了配置，并建立了模块化架构：
 
-| 阶段 | 改了什么 | 影响 |
-|-------|-------------|--------|
-| **性能** | 缓存端点、SSE 自适应批处理、缓冲区分块 | 终端延迟低于 16ms |
-| **路由抽取** | `server.ts` 拆分为 15 个领域路由模块 + 认证中间件 + 端口接口 | server.ts 代码量 **−67%**（6,736 → 2,254） |
-| **领域拆分** | `types.ts` → 16 个领域文件、`ralph-tracker` → 7 个文件、`respawn-controller` → 5 个文件、`session` → 6 个文件 | 不再有上帝文件 |
-| **前端模块** | `app.js` → 18 个抽取模块，横跨基础设施、领域与特性层 | app.js 核心降至 **约 3.4K 行** |
-| **配置合并** | 约 70 个散落的魔法数字 → 10 个领域聚焦的配置文件 | 零跨文件重复 |
-| **测试基础设施** | 共享 mock 库、12 个路由测试文件、统一的 MockSession | 路由处理器可通过 `app.inject()` 测试 |
+| 阶段             | 改了什么                                                                                                      | 影响                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **性能**         | 缓存端点、SSE 自适应批处理、缓冲区分块                                                                        | 终端延迟低于 16ms                          |
+| **路由抽取**     | `server.ts` 拆分为 15 个领域路由模块 + 认证中间件 + 端口接口                                                  | server.ts 代码量 **−67%**（6,736 → 2,254） |
+| **领域拆分**     | `types.ts` → 16 个领域文件、`ralph-tracker` → 7 个文件、`respawn-controller` → 5 个文件、`session` → 6 个文件 | 不再有上帝文件                             |
+| **前端模块**     | `app.js` → 18 个抽取模块，横跨基础设施、领域与特性层                                                          | app.js 核心降至 **约 3.4K 行**             |
+| **配置合并**     | 约 70 个散落的魔法数字 → 10 个领域聚焦的配置文件                                                              | 零跨文件重复                               |
+| **测试基础设施** | 共享 mock 库、12 个路由测试文件、统一的 MockSession                                                           | 路由处理器可通过 `app.inject()` 测试       |
 
 完整细节：[`docs/archive/code-structure-findings.md`](docs/archive/code-structure-findings.md)
 
@@ -654,6 +903,10 @@ npm install xterm-zerolag-input
 
 ---
 
+## 版本策略
+
+Codeman 遵循 [SemVer](https://semver.org/)。版本号真正承诺的内容，以及哪些算内部实现（HTTP/SSE API、磁盘上的状态、实验性特性），都写在 [`docs/versioning-policy.md`](docs/versioning-policy.md) 中。如果你的脚本依赖 HTTP API，请锁定到确切版本。
+
 ## 许可证
 
 MIT —— 见 [LICENSE](LICENSE)

docker/agent.Dockerfile

@@ -0,0 +1,65 @@
+# Codeman agent base image (built locally by scripts/build-agent-image.mjs).
+#
+# Contains the agent toolchain (node + the CLIs + git/tmux/ripgrep) but NO
+# secrets: credentials are delivered at RUNTIME via bind mounts (~/.claude etc.)
+# or name-only `docker exec --env`, never baked in, so `docker save` exports stay
+# secret-free. tmux is a HARD prerequisite (the in-container tmux is what makes a
+# reconnect durable), so it is installed here and probed before launch.
+#
+# HOME is made writable by an ARBITRARY host uid via the OpenShift "gid 0,
+# group-writable" convention: on Linux we run `--user <hostUid>:0`, so the agent
+# uid is the host uid (workspace files stay host-owned) while gid 0 keeps $HOME
+# writable even though the uid is not the baked 1000.
+FROM node:22-bookworm-slim
+
+# Base toolchain. `curl` is needed for the hook callbacks (`curl -sk $CODEMAN_API_URL`),
+# `procps` for `ps`, `tmux` for the durable in-container session.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      git \
+      tmux \
+      ripgrep \
+      curl \
+      ca-certificates \
+      less \
+      procps \
+      openssh-client \
+ && rm -rf /var/lib/apt/lists/*
+
+# The agent CLIs (all four backends Codeman supports). Pinning is left to the
+# rebuild cadence (see docs/docker-cases-plan.md, user-decision 2).
+RUN npm install -g \
+      @anthropic-ai/claude-code \
+      @openai/codex \
+      @google/gemini-cli \
+      opencode-ai \
+ && npm cache clean --force
+
+# `agent` user (gid 0) with an arbitrary-uid-writable HOME. The uid is
+# auto-assigned (node:22-slim already occupies uid 1000 with its `node` user); at
+# runtime Codeman overrides with `--user <hostUid>:0` on Linux, so the baked uid
+# only matters for a hand-run / Docker Desktop container. gid 0 + group-writable
+# HOME (OpenShift arbitrary-uid convention) keeps $HOME writable for any uid.
+# UTF-8 locale so tmux/Ink render Unicode box-drawing instead of VT100 ACS `q`
+# glyphs (C.UTF-8 is built into glibc; no locales package needed). Codeman also
+# sets these at run time so containers built before this line still get UTF-8.
+ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
+ENV HOME=/home/agent
+# `.claude` (+ `.claude/projects` mount point) and `.codex` (+ `.codex/sessions`) are
+# pre-created gid-0 group-writable so the container owns its OWN credential config
+# dirs: tokens/settings/config are seeded in as writable copies and each CLI's runtime
+# state (backups, tasks, refreshed tokens) stays container-local, while ONLY the shared
+# transcript/rollout dirs (`.claude/projects`, `.codex/sessions`) are bind-mounted from
+# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir.)
+RUN useradd -g 0 -m -d /home/agent -s /bin/bash agent \
+ && mkdir -p /home/agent/.npm /home/agent/.cache /home/agent/.config /home/agent/.codeman \
+      /home/agent/.claude/projects /home/agent/.codex/sessions \
+ && chgrp -R 0 /home/agent \
+ && chmod -R g=u /home/agent
+
+USER agent
+WORKDIR /home/agent
+
+# Codeman overrides the command with `sleep infinity` at create time; this is the
+# fallback so a hand-run container also idles rather than exiting.
+CMD ["sleep", "infinity"]

docs/SPEEDRUN.md

@@ -0,0 +1,104 @@
+# SPEEDRUN.md — Fast-execution protocol for Claude
+
+Read this when the goal is **throughput**: get correct, verified work done with
+minimum ceremony. This does **not** relax correctness or the safety rules in
+`CLAUDE.md` — those still win. It removes _waste_, not _rigor_.
+
+> Precedence: `CLAUDE.md` > explicit user instructions > this file. If anything
+> here conflicts with `CLAUDE.md`, `CLAUDE.md` wins.
+
+---
+
+## The mindset
+
+- **Act, don't announce.** No "I'm going to now…" preamble. Do the thing, report
+  the result.
+- **Cheapest proof that the change works.** Pick the smallest check that actually
+  demonstrates correctness — not the biggest.
+- **Batch aggressively.** Independent reads, greps, and edits go in **one**
+  message with parallel tool calls. Never serialize work that has no dependency.
+- **Momentum over perfection.** Land a correct increment, verify it, move on.
+  Don't gold-plate untouched code.
+
+---
+
+## Loop (repeat until done)
+
+1. **Orient once** — one parallel burst of reads/greps to load the context you
+   need. Don't re-read files the harness says are already current.
+2. **Change** — make the edit(s). Batch independent edits.
+3. **Verify cheaply** — the smallest check that proves _this_ change (see below).
+4. **Advance** — next item. Only re-verify what you touched.
+5. **Stop** at: list empty, a hard blocker, or a decision that's genuinely the
+   user's to make.
+
+---
+
+## Verification ladder — climb only as high as the change needs
+
+| Change kind | Cheapest sufficient check |
+|-------------|---------------------------|
+| Types / signatures / imports | `tsc --noEmit` (or `--watch` already running) |
+| One module's logic | `npm test -- test/<file>.test.ts` (the **one** relevant file) |
+| A named behavior | `npm test -- -t "pattern"` |
+| Route/handler | `app.inject()` route test, or one `curl` against the running dev server |
+| Frontend render | Playwright load + assert (`waitUntil: 'domcontentloaded'`, wait 3–4s) |
+| Broad / pre-merge | `npm run test:ci` (the CI-equivalent sweep) |
+
+**Hard rules (never skip, even in a rush):**
+- ⚠️ **Never run bare `npm test`** — it pulls in browser/visual suites that hang
+  or fail locally. Always pass a file or `-t`, or use `test:ci`.
+- ⚠️ **Never COM without verifying the change actually works** first (curl the
+  endpoint / Playwright the UI). "Compiles" ≠ "works".
+- ⚠️ **Session safety** — check `$CODEMAN_MUX`; never `tmux kill-session` /
+  `pkill claude` in a managed session.
+- ⚠️ **Single-line prompts** for any programmatic session input.
+
+---
+
+## Speed tactics that pay off here
+
+- **Parallel exploration**: dispatch `Explore` subagents (or one parallel grep
+  burst) instead of serial file-by-file reading when scope is uncertain.
+- **`tsc --noEmit --watch`** in the background — instant type feedback, no repeat
+  cold starts.
+- **Target one test file** — `fileParallelism: false` means the suite is serial;
+  running one file is dramatically faster than the sweep.
+- **`curl localhost:3000/api/...`** beats spinning up a browser for backend
+  checks. Reserve Playwright for actual UI rendering.
+- **Trust the harness** — if it says a file you just edited is current, don't
+  re-Read it to "confirm". The Edit already succeeded or it would have errored.
+
+---
+
+## Anti-patterns (these masquerade as speed, but cost time)
+
+- Running the full test suite to check a one-file change.
+- Re-reading files you already have in context.
+- Narrating a plan you're about to execute anyway.
+- Serial tool calls that have no dependency between them.
+- Claiming "done / fixed / passing" **before** running the check that proves it.
+- Deploying (COM) on green typecheck alone, without exercising the real flow.
+
+---
+
+## Stop-conditions (don't rush past these)
+
+Stop and surface, don't guess, when you hit:
+- A **destructive / hard-to-reverse** action (delete, overwrite, force-push).
+- An **outward-facing** action (publishing, sending, deploying) not already
+  authorized.
+- A **genuine product decision** the code can't answer.
+- A **failing verification you can't explain** — debug it (see
+  `superpowers:systematic-debugging`), don't paper over it.
+
+---
+
+## Definition of done
+
+A task is done when **all** hold:
+- The change is made.
+- The cheapest sufficient check **ran** and **passed** — evidence, not assertion.
+- No new type errors / lint errors introduced (`tsc --noEmit`, `npm run lint`).
+- You state plainly what was done and what proved it. If a step was skipped or a
+  test failed, say so — don't hedge, don't overclaim.

docs/claude-code-hooks-reference.md

@@ -2,14 +2,18 @@
 
 > Official documentation for Claude Code hooks system, extracted from [code.claude.com](https://code.claude.com/docs/en/hooks).
 
-**Last Updated**: 2026-01-24
+**Last Updated**: 2026-07-25
 **Source**: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
 
+> This is a maintained summary, not an exhaustive copy of the upstream reference.
+> Check the source link for event-specific schemas before adding a new hook.
+
 ---
 
 ## Overview
 
 Hooks are automated scripts that execute at specific events during your Claude Code session. They allow you to:
+
 - Validate, modify, or block tool usage
 - Add context to prompts
 - Implement custom workflows
@@ -21,12 +25,12 @@ Hooks are automated scripts that execute at specific events during your Claude C
 
 Hooks are configured in settings files:
 
-| File | Scope |
-|------|-------|
-| `~/.claude/settings.json` | User (global) |
-| `.claude/settings.json` | Project |
+| File                          | Scope                      |
+| ----------------------------- | -------------------------- |
+| `~/.claude/settings.json`     | User (global)              |
+| `.claude/settings.json`       | Project                    |
 | `.claude/settings.local.json` | Local project (gitignored) |
-| Plugin hook files | Plugin-specific |
+| Plugin hook files             | Plugin-specific            |
 
 ### Basic Structure
 
@@ -49,8 +53,9 @@ Hooks are configured in settings files:
 ```
 
 **Key Fields**:
+
 - `matcher`: Pattern to match tool names (case-sensitive, supports regex like `Edit|Write` or `*` for all)
-- `type`: `"command"` for bash or `"prompt"` for LLM-based evaluation
+- `type`: `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` where the event supports it
 - `command`: Bash command to execute
 - `prompt`: LLM prompt for evaluation (prompt-based hooks only)
 - `timeout`: Optional timeout in seconds (default: 60)
@@ -59,6 +64,10 @@ Hooks are configured in settings files:
 
 ## Hook Events
 
+Claude Code's current event surface is broader than the detailed subset below. In
+particular, `TeammateIdle` and `TaskCompleted` are supported lifecycle events used
+by Codeman; they are not stale or plugin-defined event names.
+
 ### PreToolUse
 
 **When**: After Claude creates tool parameters, before processing the tool call.
@@ -66,15 +75,17 @@ Hooks are configured in settings files:
 **Use Cases**: Approval, denial, or modification of tool calls.
 
 **Common Matchers**:
+
 - `Bash` - Shell commands
 - `Write` - File writing
 - `Edit` - File editing
 - `Read` - File reading
-- `Task` - Subagent tasks
+- `Agent` - Subagent tasks
 - `WebFetch`, `WebSearch` - Web operations
 - `mcp__<server>__<tool>` - MCP tools
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -96,13 +107,14 @@ Hooks are configured in settings files:
 **Use Cases**: Auto-approve or deny permissions.
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "PermissionRequest",
     "decision": {
       "behavior": "allow|deny",
-      "updatedInput": { },
+      "updatedInput": {},
       "message": "deny reason",
       "interrupt": false
     }
@@ -117,6 +129,7 @@ Hooks are configured in settings files:
 **Use Cases**: Provide feedback, run formatters/linters, log operations.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -128,15 +141,30 @@ Hooks are configured in settings files:
 }
 ```
 
+#### Asynchronous Rewake
+
+Command hooks can set `"asyncRewake": true` to run asynchronously and wake an
+idle Claude turn when the hook exits with code 2. The hook's stderr is delivered
+to Claude as a system reminder. This implies `"async": true`; ordinary async
+hooks do not wake an idle turn, and their output waits for the next interaction.
+
+Codeman uses this on `PostToolUse(Bash)`: a self-contained Node helper extracts
+the background task ID from the Bash result, watches the session transcript for
+the matching completion notification, and exits 2. It does not send terminal
+input, so it cannot submit a user's partially written prompt.
+
 ### Notification
 
 **When**: When Claude Code sends notifications.
 
 **Matchers**:
+
 - `permission_prompt`
 - `idle_prompt`
 - `auth_success`
 - `elicitation_dialog`
+- `elicitation_complete`
+- `elicitation_response`
 
 ### UserPromptSubmit
 
@@ -145,6 +173,7 @@ Hooks are configured in settings files:
 **Use Cases**: Add context, validate, or block prompts.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -165,6 +194,7 @@ Hooks are configured in settings files:
 **Use Cases**: **Ralph Wiggum loops** - block exit and refeed prompt.
 
 **Output Control**:
+
 ```json
 {
   "decision": "block",
@@ -173,6 +203,7 @@ Hooks are configured in settings files:
 ```
 
 Or to allow exit:
+
 ```json
 {
   "continue": true,
@@ -184,15 +215,32 @@ Or to allow exit:
 
 ### SubagentStop
 
-**When**: When a subagent (Task tool call) finishes responding.
+**When**: When a subagent (Agent tool call) finishes responding.
 
 **Use Cases**: Control nested loops, verify subagent output.
 
+### TeammateIdle
+
+**When**: When an agent-team teammate is about to go idle.
+
+**Use Cases**: Reassign work, continue a teammate loop, or notify an orchestrator.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
+### TaskCompleted
+
+**When**: When a task is about to be marked completed.
+
+**Use Cases**: Validate completion or forward team progress to an external UI.
+
+**Matcher Support**: None. The hook fires for every occurrence.
+
 ### PreCompact
 
 **When**: Before a compact operation.
 
 **Matchers**:
+
 - `manual` - Invoked from `/compact`
 - `auto` - Invoked from auto-compact
 
@@ -201,6 +249,7 @@ Or to allow exit:
 **When**: When Claude Code starts or resumes a session.
 
 **Matchers**:
+
 - `startup` - Fresh start
 - `resume` - From `--resume`, `--continue`, or `/resume`
 - `clear` - From `/clear`
@@ -209,6 +258,7 @@ Or to allow exit:
 **Use Cases**: Load development context, set environment variables.
 
 **Persisting Environment Variables**:
+
 ```bash
 #!/bin/bash
 if [ -n "$CLAUDE_ENV_FILE" ]; then
@@ -219,6 +269,7 @@ exit 0
 ```
 
 **Output Control**:
+
 ```json
 {
   "hookSpecificOutput": {
@@ -233,6 +284,7 @@ exit 0
 **When**: When a session ends.
 
 **Reason Values**:
+
 - `clear`
 - `logout`
 - `prompt_input_exit`
@@ -254,7 +306,7 @@ Hooks receive JSON via stdin with common fields:
   "permission_mode": "default",
   "hook_event_name": "PreToolUse",
   "tool_name": "Bash",
-  "tool_input": { },
+  "tool_input": {},
   "tool_use_id": "toolu_01ABC123..."
 }
 ```
@@ -262,6 +314,7 @@ Hooks receive JSON via stdin with common fields:
 ### Tool-Specific Input
 
 **Bash**:
+
 ```json
 {
   "tool_name": "Bash",
@@ -274,6 +327,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Write**:
+
 ```json
 {
   "tool_name": "Write",
@@ -285,6 +339,7 @@ Hooks receive JSON via stdin with common fields:
 ```
 
 **Edit**:
+
 ```json
 {
   "tool_name": "Edit",
@@ -302,11 +357,11 @@ Hooks receive JSON via stdin with common fields:
 
 ### Exit Codes
 
-| Code | Behavior |
-|------|----------|
-| 0 | Success. `stdout` processed (shown in verbose or added as context) |
-| 2 | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
-| Other | Non-blocking error. `stderr` shown in verbose, execution continues |
+| Code  | Behavior                                                              |
+| ----- | --------------------------------------------------------------------- |
+| 0     | Success. `stdout` processed (shown in verbose or added as context)    |
+| 2     | Blocking error. Only `stderr` used. Blocks tool/prompt based on event |
+| Other | Non-blocking error. `stderr` shown in verbose, execution continues    |
 
 ### JSON Output (Exit Code 0)
 
@@ -323,7 +378,12 @@ Hooks receive JSON via stdin with common fields:
 
 ## Prompt-Based Hooks
 
-For Stop and SubagentStop events, you can use LLM-based evaluation:
+Prompt and agent handlers are supported by decision-oriented events including
+`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`,
+`PostToolBatch`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `TaskCreated`, and
+`TaskCompleted`. Check the upstream reference before choosing a handler type.
+
+For example, a Stop event can use LLM-based evaluation:
 
 ```json
 {
@@ -344,6 +404,7 @@ For Stop and SubagentStop events, you can use LLM-based evaluation:
 ```
 
 **LLM Response Format**:
+
 ```json
 {
   "ok": true,
@@ -362,17 +423,18 @@ Hooks can be defined in Skills, Agents, and Slash Commands using frontmatter:
 name: secure-operations
 hooks:
   PreToolUse:
-    - matcher: "Bash"
+    - matcher: 'Bash'
       hooks:
         - type: command
-          command: "./scripts/security-check.sh"
+          command: './scripts/security-check.sh'
 ---
 ```
 
 These hooks:
+
 - Are scoped to the component's lifecycle
 - Only run when that component is active
-- Support: PreToolUse, PostToolUse, Stop
+- Support all hook events; a subagent-scoped `Stop` is converted to `SubagentStop`
 
 ---
 
@@ -550,11 +612,11 @@ exit 0
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `CLAUDE_PROJECT_DIR` | Project root directory |
-| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI |
-| `CLAUDE_ENV_FILE` | Path to write persistent env vars (SessionStart) |
+| Variable             | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `CLAUDE_PROJECT_DIR` | Project root directory                           |
+| `CLAUDE_CODE_REMOTE` | `"true"` for web, empty for CLI                  |
+| `CLAUDE_ENV_FILE`    | Path to write persistent env vars (SessionStart) |
 
 ---
 
@@ -593,4 +655,4 @@ Use `/hooks` command to view registered hooks and make changes.
 
 ---
 
-*Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)*
+_Source: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)_

docs/cron-build-brief.md

@@ -0,0 +1,588 @@
+# Claude Code Build Brief: Add Scheduling to Codeman
+
+## 0. Purpose of This Brief
+
+You are Claude Code working inside the Codeman repository.
+
+Your task is to add a **small, reliable scheduling layer** to Codeman while preserving Codeman's existing architecture and session-management behavior.
+
+This is not a greenfield rewrite. This is not a full product rebuild. This is a focused extension.
+
+The target user wants Codeman-like tmux/web/session management, but with first-class scheduled jobs for Claude, Codex, OpenCode, Terminal, or any other configurable coding-agent harness.
+
+---
+
+## 1. Non-Negotiable Goal
+
+Add scheduling to Codeman so a user can define a scheduled coding-agent job that:
+
+1. Has a name.
+2. Uses an existing Codeman-supported agent/session type where possible.
+3. Has a working directory.
+4. Has a prompt or prompt file.
+5. Has a schedule.
+6. Can be enabled or disabled.
+7. Can be manually run now.
+8. When due, creates a Codeman/tmux session.
+9. Sends the configured prompt into that session.
+10. Records last run, next run, status, and run history.
+
+The first working version should prioritize **scheduling correctness and reuse of Codeman's existing tmux/session system** over UI polish.
+
+---
+
+## 2. Core Architectural Rule
+
+Do **not** rebuild Codeman's session layer.
+
+Reuse existing Codeman functionality for:
+
+- Creating sessions.
+- Naming sessions.
+- Launching Claude/Codex/OpenCode/Terminal sessions.
+- Sending input into sessions.
+- Displaying sessions in the web UI.
+- Killing sessions.
+- Tracking session status if already supported.
+
+If an internal API/service/function already exists, reuse it.
+
+If no reusable function exists, create a thin wrapper around the existing implementation rather than duplicating logic.
+
+---
+
+## 3. Product Boundary
+
+This build is **Codeman + Scheduler**.
+
+It is not yet:
+
+- A full quota engine.
+- A full lock manager.
+- A replacement for Codeman's terminal UI.
+- A new FastAPI application.
+- A multi-tenant SaaS platform.
+- A complex cron-management product.
+- A full agent autonomy framework.
+
+Keep the build small and shippable.
+
+---
+
+## 4. Required Working Scope for v0.1
+
+Implement the following minimum features.
+
+### 4.1 Scheduled Jobs List
+
+Create a UI page showing all scheduled jobs.
+
+Each row/card should show:
+
+- Job name.
+- Agent/session type.
+- Working directory.
+- Schedule type.
+- Enabled/disabled state.
+- Last run time.
+- Next run time.
+- Last run status.
+- Actions:
+  - Run Now.
+  - Enable/Disable.
+  - Edit.
+  - Delete.
+
+### 4.2 Create/Edit Scheduled Job
+
+Create a form for scheduled jobs with these fields:
+
+- `name`
+- `agent_type`
+  - Reuse Codeman's existing session/agent types where possible.
+  - Include at least Terminal/custom command if supported.
+- `working_directory`
+- `launch_command` if needed by Codeman's model.
+- `prompt_mode`
+  - `inline_text`
+  - `prompt_file_path`
+- `prompt_text`
+- `prompt_file_path`
+- `input_mode`
+  - `paste`
+  - `typed`
+- `schedule_type`
+  - `once`
+  - `interval_minutes`
+  - `daily_time`
+  - `weekly_time`
+- `run_at` for one-time jobs.
+- `interval_minutes` for interval jobs.
+- `daily_time` for daily jobs.
+- `weekly_days` and `weekly_time` for weekly jobs.
+- `enabled`
+- `notes` optional.
+
+Do not build a complex visual cron editor in v0.1.
+
+### 4.3 Run Now
+
+Every scheduled job must support a `Run Now` action.
+
+Run Now should:
+
+1. Create a new session through Codeman's existing session creation logic.
+2. Send the configured prompt into the session using Codeman's existing input mechanism.
+3. Create a run-history record.
+4. Update last-run fields.
+5. Redirect or link the user to the created Codeman session.
+
+### 4.4 Background Scheduler Loop
+
+Add a small background scheduler loop that runs inside the Codeman backend process.
+
+The loop should:
+
+1. Wake every 15-60 seconds.
+2. Load enabled schedules.
+3. Find schedules where `next_run_at <= now`.
+4. Create a scheduled run.
+5. Launch the session using existing Codeman session logic.
+6. Send the prompt.
+7. Record run history.
+8. Compute the next run time.
+9. Avoid duplicate launches if the loop overlaps or restarts.
+
+Keep this simple and robust.
+
+### 4.5 Run History
+
+Every scheduled execution should create a run-history record.
+
+Track:
+
+- `id`
+- `scheduled_job_id`
+- `session_id` or Codeman session reference.
+- `session_name` if applicable.
+- `started_at`
+- `finished_at` optional.
+- `status`
+  - `created`
+  - `session_started`
+  - `prompt_sent`
+  - `failed`
+- `error_message` optional.
+- `trigger_type`
+  - `scheduled`
+  - `manual_run_now`
+- `created_session_url` or route reference if easy.
+
+---
+
+## 5. Scheduling Rules
+
+### 5.1 Once
+
+Run at a specific date/time.
+
+After successful launch:
+
+- Set `enabled = false`, or mark as completed.
+
+### 5.2 Interval
+
+Run every N minutes.
+
+Example:
+
+- Every 60 minutes.
+- Every 240 minutes.
+
+After launch:
+
+- `next_run_at = now + interval_minutes`.
+
+### 5.3 Daily
+
+Run every day at HH:MM.
+
+After launch:
+
+- Compute the next occurrence of HH:MM after now.
+
+### 5.4 Weekly
+
+Run on selected weekdays at HH:MM.
+
+After launch:
+
+- Compute the next selected weekday/time after now.
+
+### 5.5 Timezone
+
+Use the server's local timezone for v0.1 unless Codeman already has timezone handling.
+
+Add a visible note in the UI:
+
+> Times use the server's local timezone.
+
+Do not overbuild timezone support in v0.1.
+
+---
+
+## 6. Data Storage Decision
+
+First inspect Codeman's existing persistence model.
+
+If Codeman already has a database or persistence layer:
+
+- Reuse it.
+- Add scheduled job and scheduled run models/tables/records using the existing pattern.
+
+If Codeman uses files or JSON state:
+
+- Use the same style for v0.1.
+- Prefer simple persistence over introducing a heavy new dependency.
+
+If there is no appropriate persistence layer:
+
+- Add SQLite only if it fits the codebase cleanly.
+- Otherwise use a JSON file store for the first version.
+
+Do not introduce Postgres, Redis, Celery, or a separate scheduler service.
+
+---
+
+## 7. Concurrency and Duplicate-Run Guard
+
+Implement a basic duplicate-run guard.
+
+A schedule should not launch twice for the same due time.
+
+Minimum acceptable approach:
+
+- Before launching, create/update a run record with a `created` or `launching` state.
+- Use a schedule-level `last_triggered_at` or `last_due_key` to avoid double launching.
+- If launch fails, record failure clearly.
+
+Do not build distributed locks. Codeman is expected to be local/single-instance for v0.1.
+
+---
+
+## 8. Multi-Session Warning
+
+When the user clicks `Run Now`, show a warning if there are already active sessions for the same agent type.
+
+Minimum behavior:
+
+- If active sessions exist, show a confirmation warning.
+- User can continue anyway.
+
+For scheduled automatic runs:
+
+- Add a setting on the scheduled job:
+  - `warn_only`
+  - `skip_if_same_agent_running`
+
+Default:
+
+- `warn_only` for manual runs.
+- `skip_if_same_agent_running = false` for automatic runs unless easy to implement.
+
+Do not build a complete quota engine in v0.1.
+
+---
+
+## 9. Prompt Sending Rules
+
+The scheduler must support sending the configured prompt into the created session.
+
+Prompt source:
+
+1. Inline prompt text.
+2. Prompt file path.
+
+Input mode:
+
+1. Paste mode.
+2. Typed mode.
+
+If only one input mode is easy with Codeman's current internals, implement that first and structure the code so the other can be added later.
+
+Important:
+
+- Do not send prompts to a session if session creation failed.
+- Record prompt-send success/failure in run history.
+- Save enough metadata to understand what prompt was used.
+
+---
+
+## 10. UI Bifurcation
+
+Keep UI changes cleanly separated.
+
+Add scheduler UI under a clear navigation item:
+
+- `Scheduled Jobs`
+
+Do not clutter the existing session dashboard.
+
+The existing session dashboard may show sessions created by scheduled jobs, but the scheduling controls should live in their own section.
+
+Recommended pages/routes:
+
+- `/schedules`
+- `/schedules/new`
+- `/schedules/:id`
+- `/schedules/:id/edit`
+- `/schedules/:id/run-now`
+- `/schedules/:id/enable`
+- `/schedules/:id/disable`
+- `/schedules/:id/delete`
+
+Use Codeman's existing frontend conventions and routing style.
+
+---
+
+## 11. Backend Bifurcation
+
+Keep scheduler code separate from existing session code.
+
+Recommended logical modules, adapted to Codeman's actual structure:
+
+- `scheduler/model` or equivalent.
+- `scheduler/store` or equivalent.
+- `scheduler/service` for schedule calculations and launch logic.
+- `scheduler/loop` for the background due-job checker.
+- `scheduler/routes` for API/UI endpoints.
+- `scheduler/time` for next-run calculations.
+
+Do not mix scheduling logic directly into terminal rendering, xterm handling, or low-level tmux code.
+
+The scheduler service should call session services; it should not own tmux directly unless Codeman has no session abstraction.
+
+---
+
+## 12. Required Discovery Phase Before Coding
+
+Before implementing, inspect the Codeman repo and produce a short architecture note in the terminal or in a file called:
+
+`docs/cron-discovery.md`
+
+This note must identify:
+
+1. Where session creation happens.
+2. Where agent/session types are defined.
+3. Where input is sent into a session.
+4. Where active sessions are listed.
+5. Where session kill/delete is handled.
+6. How session state is stored.
+7. Whether there is existing persistence.
+8. Where backend routes live.
+9. Where frontend pages/components live.
+10. The smallest integration points for scheduling.
+
+Do not start coding until this discovery is complete.
+
+---
+
+## 13. Implementation Phases
+
+### Phase 1: Discovery
+
+Deliverable:
+
+- `docs/cron-discovery.md`
+
+Must answer the 10 discovery questions above.
+
+### Phase 2: Data Model / Persistence
+
+Deliverable:
+
+- Scheduled job persistence.
+- Scheduled run history persistence.
+- Basic create/read/update/delete operations.
+
+### Phase 3: Scheduler Calculation Logic
+
+Deliverable:
+
+- Functions to compute `next_run_at` for:
+  - once
+  - interval
+  - daily
+  - weekly
+
+Add tests if the repo has an existing test setup.
+
+### Phase 4: Manual Run Now
+
+Deliverable:
+
+- Create scheduled job.
+- Click Run Now.
+- Codeman session is created.
+- Prompt is sent.
+- Run history is recorded.
+- UI links to the session.
+
+This is the most important milestone.
+
+### Phase 5: Background Scheduler Loop
+
+Deliverable:
+
+- Enabled schedules launch automatically when due.
+- Run history is recorded.
+- `last_run_at` and `next_run_at` update.
+- Duplicate launch guard exists.
+
+### Phase 6: UI Polish Only After Functionality
+
+Deliverable:
+
+- Scheduled jobs list is readable.
+- Create/edit form is usable.
+- Status labels are clear.
+- Errors are visible.
+
+Do not polish before Phase 4 works.
+
+---
+
+## 14. Acceptance Criteria
+
+The build is acceptable when all these pass.
+
+### Manual Run
+
+1. Create a schedule/job with inline prompt.
+2. Click Run Now.
+3. A new Codeman/tmux session starts.
+4. Prompt is sent into that session.
+5. The created session is visible in Codeman's normal session UI.
+6. Run history shows success or failure.
+
+### One-Time Schedule
+
+1. Create a one-time schedule 2 minutes in the future.
+2. Wait for it to become due.
+3. Scheduler launches a session.
+4. Prompt is sent.
+5. Schedule does not repeatedly launch forever.
+
+### Interval Schedule
+
+1. Create interval schedule every 2 minutes.
+2. It launches once when due.
+3. It computes the next due time.
+4. It does not launch duplicates for the same due time.
+
+### Daily Schedule
+
+1. Create daily schedule at a time a few minutes ahead.
+2. It launches when due.
+3. Next run becomes tomorrow at the same time.
+
+### Disable Schedule
+
+1. Disable a schedule.
+2. It does not launch even when due.
+
+### Error Handling
+
+1. Invalid working directory produces visible error.
+2. Invalid prompt file produces visible error.
+3. Failed session launch creates failed run-history entry.
+
+---
+
+## 15. Explicitly Out of Scope for v0.1
+
+Do not implement these unless all required scope is already working:
+
+- Full quota engine.
+- Advanced lock manager.
+- Post-run git inspection reports.
+- Complex recurring calendar UI.
+- User accounts / RBAC.
+- External distributed workers.
+- Redis.
+- Postgres.
+- Celery.
+- Kubernetes.
+- A separate Python service.
+- Full visual cron editor.
+- AI-generated follow-up prompts.
+- Automatic continuation after idle.
+- Any attempt to bypass agent quotas or platform limits.
+
+---
+
+## 16. Quality Rules
+
+Follow these rules while coding:
+
+1. Reuse existing Codeman services and conventions.
+2. Keep scheduler code isolated.
+3. Prefer boring, readable code over clever abstractions.
+4. Add error messages that a human can understand.
+5. Do not break existing Codeman sessions.
+6. Do not rename existing core concepts unnecessarily.
+7. Do not introduce large dependencies without strong reason.
+8. Keep v0.1 local-first and single-instance.
+9. Commit in logical chunks if git is available.
+10. After coding, provide a final implementation summary.
+
+---
+
+## 17. Final Response Required from Claude Code
+
+At the end, report:
+
+1. Files changed.
+2. New routes/pages added.
+3. New data structures added.
+4. How the scheduler loop works.
+5. How to run the app.
+6. How to test manual Run Now.
+7. How to test scheduled execution.
+8. Known limitations.
+9. Suggested v0.2 improvements.
+
+---
+
+## 18. v0.2 Ideas, Not for Current Build
+
+Keep these in mind but do not build unless v0.1 is complete:
+
+- Quota-aware scheduling.
+- Manual takeover locks.
+- Post-idle inspection.
+- Git diff reports.
+- Schedule groups.
+- Prompt templates.
+- Agent-specific concurrency rules.
+- Better timezone support.
+- Audit events.
+- More advanced cron expressions.
+
+---
+
+## 19. Final Reminder
+
+The goal is to add **scheduling** to Codeman quickly and cleanly.
+
+Do not drift into building a new platform.
+
+The highest-priority path is:
+
+1. Discover existing Codeman integration points.
+2. Add scheduled job persistence.
+3. Add Run Now.
+4. Add background due-job loop.
+5. Add minimal UI.
+6. Verify that scheduled jobs create real Codeman/tmux sessions and send prompts.
+

docs/cron-discovery.md

@@ -0,0 +1,142 @@
+# CRON_DISCOVERY.md
+
+Phase 1 deliverable for the "Add Scheduling to Codeman" build brief.
+This documents the existing Codeman architecture and the smallest integration
+points for a cron. **No session/tmux logic will be rebuilt** —
+the new code is purely a trigger + persistence + history layer on top of the
+existing primitives.
+
+Stack: `aicodeman` v1.2.1 — Fastify 5 backend, `node-pty` + tmux sessions,
+vanilla-JS SPA frontend served as static assets, JSON file state store, zod
+validation, ports-based dependency injection.
+
+---
+
+## 0. Critical finding: an existing `ScheduledRun` is NOT a cron
+
+Codeman already has a `ScheduledRun` concept (`/api/scheduled`,
+`src/web/ports/infra-port.ts:14-26`, `src/web/server.ts:1480-1605`). It is a
+**run-now, duration-bounded autonomous loop**: given `{prompt, workingDir,
+durationMinutes}` it immediately spawns/kills throwaway sessions in a loop until
+the duration elapses. It has **no** time-based triggering, recurrence
+(once/interval/daily/weekly), enable/disable, next-run calculation, run history,
+or persistence across restarts.
+
+Therefore the brief's core (the calendar/cron trigger layer) does **not** exist
+and must be built. The execution primitives it sits on top of **do** exist and
+will be reused. To honor brief §16 ("do not rename existing core concepts"), the
+new feature is named **`CronJob`** (with **`CronJobRun`** history
+records), kept distinct from the existing `ScheduledRun`.
+
+---
+
+## 1. Where session creation happens
+
+- Canonical create flow: `POST /api/sessions`,
+  `src/web/routes/session-routes.ts:262-438`.
+  - `new Session({ workingDir, mode, ... })` (`src/session.ts:421-570`)
+  - `ctx.addSession(session)` → `ctx.setupSessionListeners(session)` →
+    `ctx.persistSessionState(session)` (all via `SessionPort`).
+- `SessionPort` interface: `src/web/ports/session-port.ts:8-16`.
+- **Integration point:** the cron service will mirror this exact sequence
+  (create → addSession → setupSessionListeners → start) via `SessionPort`,
+  not reimplement it.
+
+## 2. Where agent/session types are defined
+
+- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`
+  (`src/types/session.ts:43-44`). `shell` covers the brief's "Terminal/custom".
+- CLI availability resolvers in `src/utils/{claude,codex,gemini,opencode}-cli-resolver.ts`.
+- **Integration point:** the job's `agentType` reuses `SessionMode` verbatim.
+
+## 3. Where input is sent into a session
+
+- Raw / paste: `session.write(data)` (`src/session.ts:2243-2247`) — direct PTY write.
+- Typed (recommended): `session.writeViaMux(data)` (`src/session.ts:2301-2311`)
+  — tmux `send-keys`, falls back to PTY. Submit requires trailing `\r`.
+- **Integration point:** prompt delivery uses `writeViaMux` (typed) by default,
+  `write` (paste) as the alternate `input_mode`.
+
+## 4. Where active sessions are listed
+
+- `ctx.sessions: ReadonlyMap<string, Session>` (`SessionPort`).
+- Filters: `Array.from(ctx.sessions.values()).filter(s => s.mode === X)` and
+  `.isBusy()` / `.isIdle()` (`src/session-manager.ts:220-247`).
+- **Integration point:** the §8 multi-session warning queries this map.
+
+## 5. Where session kill/delete is handled
+
+- `ctx.cleanupSession(sessionId, killMux?, reason?)`
+  (`SessionPort`; impl `src/web/server.ts:997-1152`). Underlying
+  `session.stop(killMux)` at `src/session.ts:2498-2585`.
+- The cron does **not** kill sessions it launches (the brief wants them
+  visible in the normal session UI); cleanup stays user-driven.
+  _Superseded post-review:_ recurring jobs now default to
+  `autoClosePreviousSession: true` — the previous run's still-open session is
+  closed via `cleanupSession` when the next run fires (see
+  `docs/cron-guide.md` §8); opt out per job for fully user-driven cleanup.
+
+## 6. How session state is stored / 7. Existing persistence
+
+- JSON file store: `~/.codeman/state.json` (+ `state-inner.json` for Ralph).
+  `StateStore` class `src/state-store.ts:71`; `AppState` interface
+  `src/types/app-state.ts:99-114`.
+- Pattern: declare a field on `AppState`, add typed get/set methods on
+  `StateStore` that mutate in-memory state and call the debounced `save()`
+  (500ms debounce, atomic temp-file+rename, `.bak` backup, circuit breaker).
+- **Integration point:** add `cronJobs?: Record<string, CronJob>` and
+  `cronJobRuns?: Record<string, CronJobRun>` to `AppState`, with
+  matching `StateStore` accessors. No new DB (brief §6 forbids Postgres/Redis).
+
+## 8. Where backend routes live
+
+- Route modules: `src/web/routes/*.ts`; barrel `src/web/routes/index.ts`;
+  registered in `WebServer.setupRoutes()` `src/web/server.ts:858-876` with a
+  single `ctx` object from `createRouteContext()` (`src/web/server.ts:553-613`)
+  that satisfies all port interfaces.
+- Validation: zod schemas in `src/web/schemas.ts`, applied via
+  `parseBody(Schema, req.body)` (`src/web/route-helpers.ts:101-111`).
+- Errors: `createErrorResponse(ApiErrorCode.X, msg)` / `ApiResponse`
+  (`src/types/api.ts`), auto-mapped to HTTP status by a `preSerialization` hook
+  (`src/web/server.ts:644-659`).
+- SSE: `ctx.broadcast(SseEvent.X, data)` (`EventPort`,
+  `src/web/sse-events.ts`); frontend mirror in `src/web/public/constants.js`.
+- **Integration point:** new `cron-routes.ts` registered alongside the
+  others; new zod schema; new `SseEvent` constants for job list/run changes.
+
+## 9. Where frontend pages/components live
+
+- Vanilla-JS SPA: single `src/web/public/index.html` + feature mixin files
+  (`Object.assign(CodemanApp.prototype, {...})`). API via `api-client.js`
+  (`_apiJson/_apiPost/_apiDelete`). Build = esbuild minify + content-hash, no
+  bundler (`scripts/build.mjs`).
+- UI is panels/modals toggled by JS classes; forms use `.form-row` / `.modal`
+  conventions (`styles.css`). SSE handler map in `app.js`.
+- **Integration point:** add a new `cron-ui.js` mixin + a panel/modal in
+  `index.html` + nav entry, following the orchestrator/respawn panel pattern.
+
+## 10. Background-loop pattern (for the due-checker)
+
+- Established pattern: `this.cleanup.setInterval(fn, intervalMs, {description})`
+  in `WebServer.start()` (`src/web/server.ts:~1942-1966`), auto-disposed in
+  `WebServer.stop()` via `this.cleanup.dispose()` (`src/web/server.ts:2336`).
+  RalphLoop (`src/ralph-loop.ts:268-286`) shows the self-rescheduling guard idiom.
+- **Integration point:** register a 30s cron tick via `cleanup.setInterval`;
+  no manual shutdown wiring needed.
+
+---
+
+## Smallest integration points (summary)
+
+| New piece | Reuses | Location |
+| --- | --- | --- |
+| `CronJob` / `CronJobRun` types | — (new) | `src/types/cron.ts` |
+| Persistence | `StateStore` / `AppState` | `src/types/app-state.ts`, `src/state-store.ts` |
+| Next-run time math | — (new, pure, unit-tested) | `src/cron/cron-time.ts` |
+| Launch + send prompt | `SessionPort` (`addSession`/listeners/`writeViaMux`) | `src/cron/cron-service.ts` |
+| Background due loop | `cleanup.setInterval` pattern | `src/cron/cron-loop.ts` |
+| Routes + schema | route/ports/zod/SSE patterns | `src/web/routes/cron-routes.ts`, `src/web/schemas.ts`, `src/web/sse-events.ts` |
+| UI | panel/modal/mixin conventions | `src/web/public/cron-ui.js`, `index.html` |
+
+Nothing in the session, tmux, persistence, routing, or SSE subsystems is
+rewritten — the cron is additive and calls existing services.

docs/cron-guide.md

@@ -0,0 +1,426 @@
+# Cron Jobs — User & Operator Guide
+
+Codeman's **Cron** feature lets you save named, recurring jobs that automatically
+spin up a Claude (or shell / OpenCode / Codex / Gemini) session on a schedule and
+feed it a prompt. Think "cron for agent sessions": _"every weekday at 3am, open a
+Claude session in `~/proj` and tell it to update dependencies and open a PR."_
+
+- **UI**: the **⏰ Cron** button in the header → the Cron Jobs modal (`#cronModal`).
+- **API**: `/api/cron/jobs*` and `/api/cron/runs`.
+- **Code**: `src/cron/cron-service.ts`, `src/cron/cron-time.ts`, `src/cron/cron-input.ts`,
+  types in `src/types/cron.ts`, routes in `src/web/routes/cron-routes.ts`,
+  frontend in `src/web/public/cron-ui.js`.
+
+> **Not to be confused with `ScheduledRun` (`/api/scheduled`).** That older,
+> deliberately-separate concept is a _run-now, duration-bounded autonomous loop_
+> (`{prompt, workingDir, durationMinutes}` → spawn/kill throwaway sessions until
+> the duration elapses). It has no recurrence, no saved jobs, and no next-run
+> calculation. The two systems never interact. This guide is only about **Cron
+> jobs** (`Cron*`). See `docs/cron-discovery.md` §0.
+
+---
+
+## 1. Quick start
+
+### In the browser
+
+1. Click **⏰ Cron** in the header.
+2. Click **+ New Job**.
+3. Fill in a **name**, pick an **agent type** and **working directory**, choose a
+   **prompt** (inline text or a file path), pick a **schedule**, and leave
+   **Enabled** on.
+4. **Save**. The job appears in the list with its computed **next run**.
+5. Use **Run Now** to fire it immediately without waiting for the schedule.
+
+### With curl
+
+```bash
+API=http://localhost:3000
+
+# Create a daily job (03:00 server-local time)
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "nightly-deps",
+    "agentType": "claude",
+    "workingDir": "/home/me/proj",
+    "promptMode": "inline_text",
+    "promptText": "Update dependencies and open a PR",
+    "inputMode": "typed",
+    "scheduleType": "daily",
+    "dailyTime": "03:00",
+    "enabled": true,
+    "concurrencyPolicy": "warn_only"
+  }' | jq
+
+# List jobs
+curl -s "$API/api/cron/jobs" | jq
+
+# Run one immediately
+curl -s -X POST "$API/api/cron/jobs/<jobId>/run" | jq
+
+# See a job's run history
+curl -s "$API/api/cron/jobs/<jobId>/runs" | jq
+```
+
+---
+
+## 2. Concepts
+
+| Term                       | Meaning                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Cron job** (`CronJob`)   | A saved, named definition: what agent to launch, where, with what prompt, on what schedule.      |
+| **Run** (`CronJobRun`)     | One execution of a job — a history record with a status and a link to the session it created.    |
+| **Schedule type**          | How fire times are computed: `once`, `interval`, `daily`, or `weekly`.                           |
+| **Next run** (`nextRunAt`) | Server-computed epoch-ms of the next fire. `null` when the job is disabled or has no future run. |
+| **Due tick**               | A background loop (every 30s) that launches any enabled job whose `nextRunAt` has passed.        |
+
+A job is essentially a **trigger + persistence + history layer on top of the
+existing session primitives**. When a job fires, the cron service does exactly
+what the "quick start" route does — `new Session(...)` → `addSession` →
+`setupSessionListeners` → `startInteractive()`/`startShell()` → deliver the
+prompt. It does **not** reimplement any tmux/PTY logic.
+
+---
+
+## 3. The job form — every field
+
+These map 1:1 to `CronJobSchema` (`src/web/schemas.ts`) and the `CronJob` type
+(`src/types/cron.ts`).
+
+| Field                      | Required    | Values / limits                                          | Notes                                                                                                                                                                                      |
+| -------------------------- | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                     | ✅          | 1–200 chars                                              | Display name; also used as the created session's name.                                                                                                                                     |
+| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal.                                                                                                                                |
+| `workingDir`               | ✅          | valid path (allowlist-validated)                         | Validated at **create/update** (must exist, be a directory, and not resolve into a blocked tree — `/etc`, `/root`, `/proc`, `/sys`, `/dev`, or `/` itself) and again **at fire time**.     |
+| `launchCommand`            | —           | ≤ 2000 chars, single line                                | `shell` mode only: sent as the **first input line** once the shell is up, before the prompt. Ignored for other agent types.                                                                |
+| `promptMode`               | ✅          | `inline_text` \| `prompt_file_path`                      | See §5.                                                                                                                                                                                    |
+| `promptText`               | conditional | ≤ 100000 chars, **single line**                          | Required when `promptMode = inline_text`. Newlines are rejected (see §6).                                                                                                                  |
+| `promptFilePath`           | conditional | valid path                                               | Required when `promptMode = prompt_file_path`. Confined to `workingDir` (see §5).                                                                                                          |
+| `inputMode`                | ✅          | `paste` \| `typed`                                       | How the prompt is delivered. See §6.                                                                                                                                                       |
+| `scheduleType`             | ✅          | `once` \| `interval` \| `daily` \| `weekly`              | See §4.                                                                                                                                                                                    |
+| `runAt`                    | conditional | epoch-ms (positive int)                                  | Required for `once`.                                                                                                                                                                       |
+| `intervalMinutes`          | conditional | 1–525600 (≤ 1 year)                                      | Required for `interval`.                                                                                                                                                                   |
+| `dailyTime`                | conditional | `HH:MM` (24h)                                            | Required for `daily`. Server-local time.                                                                                                                                                   |
+| `weeklyDays`               | conditional | array of 1–7 ints, each 0–6 (0 = Sunday)                 | Required for `weekly`.                                                                                                                                                                     |
+| `weeklyTime`               | conditional | `HH:MM` (24h)                                            | Required for `weekly`. Server-local time.                                                                                                                                                  |
+| `enabled`                  | ✅          | boolean                                                  | Disabled jobs never auto-fire (but **Run Now** still works).                                                                                                                               |
+| `notes`                    | —           | ≤ 2000 chars                                             | Free-form.                                                                                                                                                                                 |
+| `concurrencyPolicy`        | ✅          | `warn_only` \| `skip_if_same_agent_running`              | Applies to **automatic** runs only. See §7.                                                                                                                                                |
+| `autoClosePreviousSession` | —           | boolean (default **true**)                               | Recurring schedules only (ignored for `once`): when the next run fires, the still-open session created by this job's **previous** run is closed first via the normal cleanup path. See §8. |
+
+**Cross-field validation** (`refineCronJob` in `schemas.ts`): the conditional
+fields above are enforced by a Zod `superRefine` on create. A missing dependent
+field (e.g. `scheduleType: "once"` with no `runAt`) is rejected with
+`INVALID_INPUT` and a field-specific message.
+
+> ⚠️ **Update caveat.** `PUT /api/cron/jobs/:id` uses a `.partial()` schema that
+> does **not** re-run the cross-field `superRefine`. To keep partial edits safe,
+> `updateJob()` re-validates the **merged** job against the full `CronJobSchema`
+> and throws `400` if the result is inconsistent (e.g. switching to `once`
+> without a `runAt`). So the store is never left with a half-valid job.
+
+---
+
+## 4. Schedule types
+
+Next-run math lives in `src/cron/cron-time.ts` (pure, unit-tested in
+`test/cron-time.test.ts`). **All wall-clock times use the server's local
+timezone** (v0.1 decision).
+
+### `once`
+
+- Fires a single time at the absolute `runAt` epoch-ms.
+- A **missed** one-time job (server was down at `runAt`) **still fires once** on
+  the next tick — `computeNextRunAt` returns `runAt` even if it's in the past,
+  until the job has fired.
+- After firing, the job **self-disables**: `completedOnce = true`, `enabled =
+false`, `nextRunAt = null`.
+
+### `interval`
+
+- Fires every `intervalMinutes`, computed as `fireTime + intervalMinutes`.
+- ⚠️ **Drift**: the next run re-anchors to the actual fire time, not to an ideal
+  cadence — a slow tick or restart shifts subsequent runs slightly later. This is
+  an accepted limitation.
+
+### `daily`
+
+- Fires at `dailyTime` (`HH:MM`) every day, server-local.
+- If today's time has already passed, the next run is tomorrow at that time.
+
+### `weekly`
+
+- Fires at `weeklyTime` on each weekday in `weeklyDays` (0 = Sunday … 6 =
+  Saturday), server-local.
+- The next run is the soonest upcoming matching weekday/time within the next 7
+  days.
+
+---
+
+## 5. Prompt source (`promptMode`)
+
+### `inline_text`
+
+The prompt is the literal `promptText`. Simplest option.
+
+### `prompt_file_path`
+
+The prompt is read from a file at fire time. **This path is security-hardened**
+because a job config is attacker-controllable and the file's contents are
+injected into an agent session (an exfiltration sink over SSE/terminal).
+`resolveSafePromptPath()` enforces, in order:
+
+1. **`realpath` resolution** — symlinks are resolved to their true target, for
+   the prompt file **and for `workingDir` itself**.
+2. **`workingDir` is not a trust boundary** — because it is user-supplied, the
+   resolved `workingDir` is itself rejected if it is `/` or resolves into a
+   blocked tree (`/etc`, `/root`, operator extras) or a pseudo-filesystem
+   (`/proc`, `/sys`, `/dev`). This closes the `workingDir: '/proc'` +
+   `promptFilePath: '/proc/self/environ'` env-exfil trick. The same rule is
+   enforced earlier, at job create/update.
+3. **Blocklist** (defense-in-depth) — sensitive trees (`/etc`, `/root`,
+   `/proc`, `/sys`, `/dev`, known secret locations) are rejected for the
+   resolved prompt file.
+4. **Allowlist (primary gate)** — the resolved path **must live inside the job's
+   (resolved) `workingDir`** (`validateSessionFilePath`). A symlink escaping the
+   workspace fails here.
+5. **Regular-file check** — directories, FIFOs, and `/dev/*` character devices
+   are rejected (they would hang or OOM an unbounded read).
+6. **Size cap** — files larger than **1 MiB** (`MAX_PROMPT_FILE_BYTES`) are
+   rejected.
+7. **Single-line check** — after trailing newlines are stripped, the file
+   content must be a single line (see §6).
+
+If any check fails, the run is recorded as **`failed`** with the reason; no
+session is created.
+
+---
+
+## 6. Prompt delivery (`inputMode`)
+
+Once the CLI is ready (see §8), the prompt is written to the session with a
+trailing carriage return:
+
+| Mode    | Mechanism                                                       | Use when                                         |
+| ------- | --------------------------------------------------------------- | ------------------------------------------------ |
+| `typed` | `session.writeViaMux()` — tmux `send-keys -l` (literal) + Enter | Default; behaves like a human typing the prompt. |
+| `paste` | `session.write()` — writes directly to the PTY/mux              | Bulk paste-style delivery.                       |
+
+> ⚠️ **Single-line only — enforced.** Like all programmatic input in Codeman,
+> multi-line delivery would be silently corrupted (Ink-based TUIs treat a
+> newline as submit; typed mode fuses lines). So newlines are **rejected**: the
+> schema and the form refuse a multi-line `promptText`, and at fire time a
+> prompt file whose content is multi-line (after stripping trailing newlines)
+> fails the run with a clear `errorMessage`. Put multi-line instructions in a
+> file the agent is told to read itself (e.g. "read TASKS.md and do it").
+
+---
+
+## 7. Concurrency policy (automatic runs)
+
+`concurrencyPolicy` governs what happens when a **scheduled** run is due and
+sessions of the same `agentType` already exist:
+
+| Policy                       | Behavior                                                                                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `warn_only`                  | Always launch. (The count is surfaced but not blocking.)                                                                                                                 |
+| `skip_if_same_agent_running` | If ≥ 1 **other, live** session of that mode is active, **skip** this fire — record a `skipped` run and (for recurring schedules) advance the schedule without launching. |
+
+Notes on `skip_if_same_agent_running`:
+
+- Only **live** sessions block: a tab whose CLI already exited (status
+  `stopped`/`error`) does not count.
+- Sessions created by **this job's own previous runs never block it** —
+  otherwise a recurring job would deadlock on the session it created last time
+  and fire exactly once.
+- A skipped **`once`** job is **not consumed**: it stays armed and retries on
+  the next tick until the blocking session goes away, then fires its single run.
+- A skip is **not** a run: it sets `lastStatus = 'skipped'` but does **not**
+  advance `lastRunAt`.
+- Consecutive skips are **coalesced** — a perpetually-skipped interval job writes
+  **one** skip record per streak, not one every tick, so it can't bloat
+  `state.json`.
+
+**Run Now ignores this policy on the server.** The browser shows a `confirm()`
+warning if same-type sessions are active, but if you proceed (or call the API
+directly), the job launches unconditionally.
+
+---
+
+## 8. What happens when a job fires
+
+Sequence in `CronService.launch()`:
+
+1. A `CronJobRun` is created with status **`created`** and broadcast
+   (`cron:runCreated`).
+2. The prompt is resolved (inline or file, single-line enforced). Failure →
+   **`failed`**.
+3. `workingDir` is checked (`statSync().isDirectory()`). Missing/not-a-dir →
+   **`failed`**.
+4. **Auto-close previous session** (recurring schedules, unless
+   `autoClosePreviousSession: false`): any still-open session created by this
+   job's previous runs is closed via the normal session-cleanup path.
+5. The global session cap is checked (`MAX_CONCURRENT_SESSIONS = 50`). At cap →
+   **`failed`**.
+6. A `Session` is created **with `useMux: true`** (so it runs inside tmux),
+   registered, listeners attached, and started via `startInteractive()`
+   (`startShell()` for `shell` mode). Model/claudeMode come from global config.
+   Run status → **`session_started`**.
+7. **Readiness wait** (async, non-blocking): for non-shell agents the service
+   polls the terminal buffer up to **60 × 500ms** for a `❯` prompt or the string
+   `tokens`, then settles **2000ms** (`CRON_READY_SETTLE_MS`). Shell mode waits
+   1000ms, then sends the optional `launchCommand` as the first input line
+   (+1000ms settle).
+8. The prompt is delivered (`typed`/`paste`, trailing `\r`). Run status →
+   **`prompt_sent`**; `finishedAt` stamped. Delivery failure (e.g. the mux
+   session is gone) → **`failed`**.
+
+The created session is a **normal, persistent interactive session** — it appears
+as its own tab and keeps running after the prompt is sent. The run's
+`createdSessionUrl` is a deep link (`/?session=<id>`); the UI focuses it
+automatically after **Run Now**.
+
+> ⚠️ **Session-cap math if you disable auto-close.** With
+> `autoClosePreviousSession: false`, nothing ever closes the sessions a
+> recurring job creates — an interval job every 30 min creates 48 tabs/day and
+> hits the global 50-session cap in ~25 hours (sooner with existing tabs), after
+> which **every** fire of **every** job fails with "Maximum concurrent sessions
+> reached" until you delete tabs by hand. Leave auto-close on for unattended
+> recurring jobs, or clean up sessions yourself.
+
+### The background tick
+
+`tickDueJobs()` runs every **30s** (`CRON_TICK_INTERVAL`, registered in
+`server.ts`). For each enabled job whose `nextRunAt ≤ now`:
+
+- **Duplicate-launch guard**: `lastDueKey = jobId:fireTime`. If this due time was
+  already consumed (overlap/restart), the job is just advanced, not relaunched.
+- The schedule is **advanced _before_ launching** so a slow launch can't be
+  re-triggered by the next tick.
+- On boot, `init()` recomputes `nextRunAt` for loaded jobs (dead `once` jobs stay
+  dead).
+
+---
+
+## 9. Run history & statuses
+
+Each job keeps a history of `CronJobRun` records. Statuses (`CronJobRunStatus`):
+
+| Status            | Meaning                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `created`         | Run record created; prompt/session not yet started.           |
+| `session_started` | Session launched successfully.                                |
+| `prompt_sent`     | Prompt delivered — the happy-path terminal state.             |
+| `failed`          | Something went wrong (see `errorMessage`).                    |
+| `skipped`         | A scheduled fire was skipped by `skip_if_same_agent_running`. |
+
+Each run also records `triggerType` (`scheduled` or `manual_run_now`),
+`sessionId`/`sessionName`, timestamps, and `createdSessionUrl`.
+
+**History is capped globally** at **500 records** (`MAX_CRON_RUN_HISTORY`); the
+oldest are pruned first. Deleting a job also deletes its run records.
+
+---
+
+## 10. API reference
+
+All responses use the standard `ApiResponse<T>` envelope (`{success, data}` /
+`{success, error, errorCode}`). `/api/v1/*` is a stable alias.
+
+| Method   | Endpoint                     | Body                   | Returns                           |
+| -------- | ---------------------------- | ---------------------- | --------------------------------- |
+| `GET`    | `/api/cron/jobs`             | —                      | `CronJob[]`                       |
+| `POST`   | `/api/cron/jobs`             | `CronJobSchema`        | `{ job }`                         |
+| `GET`    | `/api/cron/jobs/:id`         | —                      | `CronJob` (404 if missing)        |
+| `PUT`    | `/api/cron/jobs/:id`         | partial `CronJob`      | `{ job }` (400 if merge invalid)  |
+| `DELETE` | `/api/cron/jobs/:id`         | —                      | `{}`                              |
+| `PUT`    | `/api/cron/jobs/:id/enabled` | `{ enabled: boolean }` | `{ job }`                         |
+| `POST`   | `/api/cron/jobs/:id/run`     | —                      | `{ run, activeAgents }`           |
+| `GET`    | `/api/cron/jobs/:id/runs`    | —                      | `CronJobRun[]` (newest first)     |
+| `GET`    | `/api/cron/runs`             | —                      | all `CronJobRun[]` (newest first) |
+
+---
+
+## 11. SSE events
+
+Emitted on `/api/events`, mirrored in `SSE_EVENTS` (`constants.js`):
+
+| Event              | Payload      | When                                                                 |
+| ------------------ | ------------ | -------------------------------------------------------------------- |
+| `cron:jobsChanged` | `{ jobs }`   | Any job created / updated / enabled / status change.                 |
+| `cron:jobDeleted`  | `{ id }`     | A job was deleted.                                                   |
+| `cron:runCreated`  | `CronJobRun` | A run (incl. skips) started.                                         |
+| `cron:runUpdated`  | `CronJobRun` | A run advanced state (`session_started` / `prompt_sent` / `failed`). |
+
+---
+
+## 12. State & persistence
+
+Persisted in `~/.codeman/state.json` via `StateStore`:
+
+- `AppState.cronJobs` — map of `id → CronJob`.
+- `AppState.cronJobRuns` — map of `id → CronJobRun`.
+
+Jobs and their schedules survive restarts; `init()` recomputes `nextRunAt` on
+boot. Sessions the jobs create persist through the normal session-recovery path.
+
+---
+
+## 13. Limits & constants
+
+| Constant                 | Value                 | Source                                           |
+| ------------------------ | --------------------- | ------------------------------------------------ |
+| Due-tick interval        | 30s                   | `CRON_TICK_INTERVAL` (`config/server-timing.ts`) |
+| Readiness poll           | 60 × 500ms            | `CRON_READY_MAX_ATTEMPTS`                        |
+| Readiness settle         | 2000ms                | `CRON_READY_SETTLE_MS`                           |
+| Run-history cap (global) | 500                   | `MAX_CRON_RUN_HISTORY` (`config/map-limits.ts`)  |
+| Saved-jobs cap           | 100                   | `MAX_CRON_JOBS` (`config/map-limits.ts`)         |
+| Concurrent-session cap   | 50                    | `MAX_CONCURRENT_SESSIONS`                        |
+| Prompt-file size cap     | 1 MiB                 | `MAX_PROMPT_FILE_BYTES` (`cron-service.ts`)      |
+| `name` length            | 1–200                 | `CronJobSchema`                                  |
+| `promptText` length      | ≤ 100000              | `CronJobSchema`                                  |
+| `intervalMinutes`        | 1–525600              | `CronJobSchema`                                  |
+| `weeklyDays`             | 1–7 entries, each 0–6 | `CronJobSchema`                                  |
+
+---
+
+## 14. Known limitations
+
+- **Server-local timezone only** — `daily`/`weekly` times are interpreted in the
+  host's local time; there is no per-job timezone.
+- **Interval drift** — `interval` re-anchors to the actual fire time; long-running
+  intervals slowly shift.
+- **Single-line prompts** — multi-line prompts are rejected (schema, form, and
+  at fire time for prompt files); tell the agent to read a file itself for
+  multi-line instructions.
+- **`runNow` / tick race** — a manual Run Now firing at the same instant as a
+  scheduled tick is theoretically possible; benign (you may get two sessions).
+- **`{enabled:true}` on a dead `once` job** — re-enabling a fired one-time job
+  without changing its schedule leaves it enabled-but-dead (won't fire); change
+  the schedule to re-arm.
+
+---
+
+## 15. Troubleshooting
+
+| Symptom                        | Likely cause                                                                                                      | Fix                                                                                                  |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Job never fires                | Disabled, or `nextRunAt: null`                                                                                    | Check **Enabled**; verify the schedule fields are complete.                                          |
+| Run shows `failed` immediately | Bad `workingDir`, prompt-file rejected, or session cap hit                                                        | Read `errorMessage` on the run; confirm the dir exists and the prompt file is inside it and < 1 MiB. |
+| Run shows `skipped`            | `skip_if_same_agent_running` + another live same-type session (this job's own sessions and dead tabs don't count) | Switch to `warn_only`, or wait for the other session to end.                                         |
+| Run fails with "single line"   | Multi-line prompt text / prompt file                                                                              | Keep the prompt to one line; point the agent at a file to read for long instructions.                |
+| Sessions pile up between runs  | `autoClosePreviousSession: false`                                                                                 | Re-enable auto-close, or delete old tabs before the 50-session cap bites (see §8).                   |
+| Wrong fire time                | Timezone assumption                                                                                               | Times are **server-local** — check the host clock/TZ.                                                |
+| One-time job won't re-fire     | `completedOnce` set                                                                                               | Edit the schedule (any real schedule change re-arms it).                                             |
+
+---
+
+## 16. Related docs
+
+- `docs/cron-discovery.md` — architecture / integration-point analysis (why the
+  feature reuses the session layer and stays distinct from `ScheduledRun`).
+- `docs/cron-build-brief.md` — the original build brief / requirements.
+- `CLAUDE.md` → **Key Patterns → Cron** — the one-paragraph engineering summary.
+- Tests: `test/cron-time.test.ts` (schedule math), `test/cron-service.test.ts`
+  (CRUD, tick, concurrency, security).

docs/docker-cases-plan.md

@@ -0,0 +1,433 @@
+<!-- Design doc generated via ultracode multi-agent workflow (wf_e3a7498b-26f): 3 architecture proposals -> judge panel -> synthesis -> completeness critic. -->
+
+# Docker Session Mode, Implementation Plan
+
+## Decisions (locked 2026-07-19, by repo owner)
+
+1. **Isolation posture**: CONVENIENT default (bind-mount host `~/.claude` etc. read-write so the existing login just works; network on; still hardened non-root + cap-drop + resource caps). SEALED profile (`mountCredentials:false` + `network:none`) is a per-case opt-in.
+2. **Export**: offer BOTH full-image (`commit`+`save`+workspace tar) AND workspace-only, side by side, no default (ask each time).
+3. **Base image**: BUILD LOCALLY on first use via `scripts/build-agent-image.mjs` from a repo `docker/agent.Dockerfile`. No registry required. (GHCR pull can be added later.)
+4. **Hooks**: WIRE HOOKS NOW. Codeman scaffolds `.claude/settings.local.json` + CLAUDE.md into the linked host workspace dir (same as local cases), enabling in-container permission prompts, hook-idle detection, and the Claude Model picker.
+
+Adopted defaults for the remaining open items (Section 10): resume-on-restart ON; container is per-CASE and shared by multiple sessions (killing one session only kills its in-container tmux session, never `docker stop` while siblings remain; stop/remove only on explicit teardown or case-delete); rootless caps = ship-with-warning (`capsEnforced` surfaced); remote docker daemon = local-first; podman = docker-first best-effort.
+
+## Implementation status (branch `feat/docker-session-mode`)
+
+DONE and END-TO-END VERIFIED against a real docker daemon (create host, link case, quick-start shell in a real container, workspace bind-mount round-trip, hook scaffolding, session-delete keeps the shared container up, case-delete `docker rm`s it):
+
+- Phase 0-1: types (`DockerHost`/`DockerCase`/`SessionDocker`), `src/docker-hosts.ts` (storage, pure `buildDockerBaseArgs`/`buildDockerCreateArgs`, `containerApiUrl`, `hostGatewayAlias`, config-hash, credential-mount resolution, daemon probes), `DockerHostSchema`/`DockerCaseLinkSchema`. 26 unit tests.
+- Phase 2: `tmux-manager` `buildDockerLaunchCommand` (image-check -> ensure -> start -> exec, resume-aware), `buildDockerKillCommand` (in-container tmux only, multi-session safe), stop/remove; wired into `createSession`/`respawnPane`/`killSession`. 14 unit tests.
+- Phase 3: `Session` threading (`_docker`, toState, option builders, in-container cliVersion probe, `resolveMuxAttachCwd`), `server.ts` recovery round-trip.
+- Phase 4: `case-routes` `/api/docker-hosts` CRUD + `/api/cases/docker-link` + listing + docker-unlink; `session-routes` `/api/quick-start` docker branch (rejects per-session config, probes availability + tmux, scaffolds hooks, seeds resume id).
+- Phase 5 (partial): `docker/agent.Dockerfile` + `scripts/build-agent-image.mjs` (built + verified: node 22, tmux, claude/codex/gemini/opencode, arbitrary-uid HOME). Host-guard allowlists `host.docker.internal`/`host.containers.internal` for in-container hooks.
+- Full CI green (3445 tests).
+
+REMAINING:
+
+- Phase 6: export / import (`docker commit` + `save | gzip` + workspace tar + manifest; `load` + quarantined re-tag), GC / boot reaper, disk-safety prechecks, drift-recreate route, SSE `docker:*` events. THE "move to a new machine" feature.
+- Phase 7: frontend Create Case "Docker" tab + `linkDockerCase` + run wiring + case-picker labels + export/import UI.
+- Phase 8: CLAUDE.md "Docker cases" Key Pattern + `docs/docker-cases.md` + COM.
+- Deferred refinements: in-container model-picker via `settings.local.json`; live mid-run resume-id capture into `DockerCase.lastClaudeSessionId`; rootless/Desktop uid probe (currently a platform heuristic).
+
+## 1. Goal & user stories
+
+Add "Docker cases" to Codeman: a case can point at a container instead of a local or remote-SSH path, and any of the five CLI backends (`claude` / `shell` / `opencode` / `codex` / `gemini`) runs inside that container. It is modeled as a LOCATION OVERLAY on cases, exactly like the remote-SSH feature (COD-94/#145), never as a sixth `SessionMode`.
+
+User stories:
+
+- As the repo owner, I link a case to a per-project container so an autonomous Claude/Ralph run executes in a hardened sandbox (cap-drop, non-root, resource caps) instead of directly on my host, while keeping my existing OAuth login and transcript history working with zero extra setup.
+- I set default, per-case-changeable container settings (image, network mode, memory/cpu/pids caps) at link time and edit them later, and edits actually take effect through a recreate-on-drift path (see Section 4).
+- I reconnect after a Codeman restart and land back in the SAME running agent with the conversation intact. When the CONTAINER itself was stopped/rebooted/OOM-killed (which destroys the in-container tmux), the next launch RESUMES the last conversation from the bind-mounted transcript rather than starting fresh (durability model in Section 2, Key decision 1).
+- I export a finished run's whole environment (toolchain plus workspace) to a portable, secret-free `.tar.gz`, move it to another machine, and import it back into a fresh case in one click.
+- The container never accumulates: killing the session stops it, deleting the case removes it, and an instance-scoped boot reaper reaps containers whose case is gone.
+
+Non-goals for the MVP: multi-tenant untrusted-code isolation guarantees (Codeman is loopback-default and single-operator, and the agent already runs `--dangerously-skip-permissions` on the host today), Kubernetes/compose orchestration, and per-command ephemeral containers.
+
+## 2. Chosen architecture and why
+
+The design grafts the strongest idea from each of the three proposals:
+
+- Overlay-not-a-mode + faithful remote-SSH mirror (from "Docker Cases as a Location Overlay"): lowest churn, rides the existing quick-start / mux-sessions / state / recovery plumbing.
+- Convenient-but-hardened default with an opt-in sealed profile, plus exec-time name-only secret env (from "Sealed Sandbox"): a strict security improvement over today's on-host execution without the UX tax of forcing an in-container re-login.
+- One-artifact export + in-app import route (from "Container-as-Cargo"): the genuinely new, high-value capability Codeman lacks.
+
+### Key decision 1: persistent per-CASE container, durable in-container tmux, AND resume-on-restart (the two-layer durability model)
+
+Exactly one long-lived container per Docker case, named as a pure slug function `codeman-case-<slug>` (Docker charset `^[a-zA-Z0-9][a-zA-Z0-9_.-]+$`; Codeman already slugs case names for tmux), so create-if-missing and boot recovery are idempotent. PID1 is `sleep infinity` under `--init` (tini reaps zombies and forwards `docker stop`'s SIGTERM); the CLI is NOT the container command. The CLI runs inside a DURABLE in-container tmux on a dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>`, the direct analog of remote's `-L codeman-remote` / `codeman-ssh-<id8>`.
+
+Two DIFFERENT failure surfaces need two DIFFERENT recovery layers, and conflating them is the central flaw the critic caught:
+
+1. Codeman-PROCESS restart while the container stays up: the in-container tmux is still alive, so `tmux new-session -A` (attach-or-create) reattaches the SAME live agent and the paneCommand is ignored. This is the remote-SSH durability idiom and it works unchanged.
+2. CONTAINER stop / daemon restart / host reboot / OOM-kill: the in-container tmux is GONE (fresh PID1). `new-session -A` will now CREATE a fresh session and run the paneCommand, which would start a brand-new conversation. This is the case the raw plan silently lost. Because the transcript directory is bind-mounted from the host (Key decision 3), the fix is to launch with RESUME: the paneCommand becomes `exec claude --dangerously-skip-permissions --resume <claudeSessionId>` (codex uses `resume <id>`, gemini `--resume <id>`) whenever a captured `claudeSessionId` exists. The `-A` semantics make this self-selecting: the resume flag only ever executes when tmux is actually re-created, which is exactly when the live session was lost. When tmux is still alive (case 1), attach wins and the flag is inert.
+
+Capturing / persisting / reusing the resume id (the missing mechanism the critic flagged): Codeman already learns `Session.claudeSessionId` from transcript correlation (which works here because projHash matches, Key decision 3) and persists it in `SessionState`. We thread that value into `createSessionOptions` / `respawnPaneOptions` for docker so `buildDockerLaunchCommand` can inject the resume flag on any relaunch. To make a NEW Codeman session (new `id8`) re-launched against the same case resume its predecessor's conversation, we ALSO persist `lastClaudeSessionId` on the `DockerCase` record; the quick-start docker branch seeds the new `Session` with it when the `dockerResumeOnStart` setting is on. First-ever launch has no id, so it starts fresh. This is user-decision 7 (default resume behavior).
+
+Reconciling with stop-on-kill and with the `--restart` policy (the internal inconsistency the critic found): the container is created with `--restart no` uniformly (Codeman's idempotent create-if-missing plus boot recovery is the single recovery mechanism; a restart policy would not preserve the conversation anyway because a restarted container gets a fresh PID1/tmux). Boot recovery re-runs `buildDockerLaunchCommand` from the restored `MuxSession.docker` (`docker inspect || docker create; docker start`, then exec with resume), so a host reboot or daemon restart recreates+starts the container and resumes the conversation instead of the session vanishing. `reconcileSessions` (tmux-manager.ts ~1800-1815) must NOT hard-delete a docker session merely because no LOCAL pane exists after the local `-L codeman` server died; docker (like remote) sessions are restored from `mux-sessions.json` and relaunched. This relaunch path is explicitly part of Phase 4/Phase 3 recovery work, not assumed.
+
+Why this over the alternatives: `docker exec` gets SIGHUP and dies when its client TTY closes, so a bare `docker exec claude` restarts the CLI on every reconnect/respawn. The inner tmux plus resume is what makes reconnect idempotent across BOTH failure surfaces. Because this durability is the single most important design point, tmux-in-image is a HARD gated prerequisite (`checkDockerTmuxAvailable`), never a silent fallback to bare exec. Rejected alternatives: ephemeral-per-run or bare-exec containers (no reattach durability); a literal `'docker'` `SessionMode` (touches dozens of switch/enum sites and diverges from the remote overlay precedent, since Docker is a LOCATION orthogonal to the 5 CLI backends).
+
+### Key decision 2: CLI + auth delivery
+
+One prebuilt base image (built once, contains NO secrets): `node:22-bookworm-slim` + `git tmux ripgrep ca-certificates`, `npm i -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai`, an `agent` user, HOME dirs made writable by an arbitrary host uid via the OpenShift "gid 0, group-writable" convention (Key decision 6). Because the toolchain is baked, export is reproducible and needs no network at import time. The image name/namespace/registry and its refresh cadence are user-decision 2 (the `codeman/agent:base` placeholder implies a Docker Hub org the project may not own).
+
+Credentials are delivered ONLY at runtime, two commit-safe channels, default convenient:
+
+- OAuth/config-file CLIs (Claude Max/Pro, gcloud, opencode): bind-mount the host credential dirs read-write (`~/.claude`, `~/.codex`, `~/.gemini` + `~/.config/gcloud`, `~/.config/opencode`) so the common user "just works" with no in-container login. Because these are bind mounts, `docker commit` (which captures only the container's own writable layer, never bind mounts) physically cannot capture them, so exports stay secret-free.
+- API-key CLIs (codex/gemini): exec-time NAME-ONLY `docker exec --env OPENAI_API_KEY --env GEMINI_API_KEY ...` (no `=value`), sourced from Codeman's own process env. Only the key NAME appears in argv (no `ps` leak), and per-exec env is never captured by `docker commit`. This is the technique Codeman already uses via `tmux setenv` for the local Codex/Gemini panes, so it composes with existing machinery.
+
+Per-host `DockerHost.mountCredentials` defaults `true` (convenient); setting it `false` yields a SEALED profile (no host cred mounts, in-container login only) for genuinely untrusted work. CRITICAL sealed-mode export rule (the leak the critic caught): in sealed mode the in-container login writes tokens into the container's OWN writable layer, which `docker commit` DOES capture, so a full-image export of a sealed container would ship credentials. Therefore full-image export is REFUSED for `mountCredentials:false` containers by default; the user may either take a workspace-only export (always safe) or opt into a pre-commit scrub that `docker exec`s `rm -rf ~/.claude ~/.codex ~/.gemini ~/.config/gcloud ~/.config/opencode` inside the container before commit (destructive to the in-container login, which is the point). This is enforced in the export route, not left to a manifest assertion.
+
+Per-session `envOverrides` / `effort` / `codexConfig` / `geminiConfig` / `openCodeConfig` are REJECTED at quick-start exactly like the remote branch (session-routes.ts ~1698-1710). `modelOverride` is the one deliberate difference from remote: because the docker workspace is a REAL bind-mounted host dir that Codeman scaffolds (Key decision 5 and Section 6), `updateCaseModel()` can write the `model` key into `<workspace>/.claude/settings.local.json` and the in-container `claude` reads it, so the App Settings Claude Model picker works for docker cases. `effort` is a `--effort` CLI arg applied only by the local-spawn path we bypass, so it stays rejected (surfaced honestly in the UI, not silently inert). Per-mode command customization goes through `DockerHost.commands.<mode>` (`defaultDockerCommandForMode`, mirror of `defaultRemoteCommandForMode` at remote-hosts.ts:60). NEVER bake secrets into an image layer and NEVER pass a secret via create-time `-e` (both are committed).
+
+Rejected alternative: sealed-by-default. For a single-operator loopback tool where the agent already runs skip-permissions on the host, forcing an in-container OAuth re-login is a UX regression with little real gain. We keep sealed as an opt-in. Rejected alternative: baking a login into the image, which leaks the instant you `docker save`.
+
+### Key decision 3: workspace mount, container CWD, and transcript correlation
+
+Bind-mount the host workspace dir into the container at the SAME absolute path (`dst == src`, mirror the host path), and set both `Session.workingDir` and the container workdir to that host path.
+
+Two problems this solves that the raw proposals got wrong:
+
+- File features: `DockerCase.hostWorkspacePath` is a REAL host directory, so `Session.workingDir = hostWorkspacePath` keeps file-routes, attachments, image-watcher, and previews working on real host bytes (unlike remote, where the path is remote-only and those features no-op). All three proposals wired `casePath = <container path>`; we deliberately diverge and use the host path.
+- Transcript correlation: Claude writes transcripts under `~/.claude/projects/<hash-of-CWD>/`. By mirroring the host path as the container CWD, the projHash computed inside the container equals the host-side hash Codeman's transcript/subagent/workflow watchers expect, so correlation keeps working (and, in turn, feeds the resume-id capture in Key decision 1). A `/workspace`-style fixed dst would break it. Mirror-vs-fixed is user-decision 3.
+
+`resolveMuxAttachCwd` still returns `/tmp` for docker sessions (the LOCAL bash pane only runs `docker exec`; it never needs the workspace as its cwd), mirroring remote.
+
+### Key decision 4: network default and the engine-specific host gateway
+
+Default `bridge` (own netns, NAT egress, no inbound), per-case changeable to `none` (offline shell sandbox; warned because it breaks the API CLIs) or `custom` (a user-defined bridge `codeman-net-<slug>`, the chokepoint for a future egress allowlist). `host` networking and any `-p` inbound publish are structurally unrepresentable in the flag builder and schema. Rationale: every API-backed CLI (Claude, Codex, Gemini) plus npm/git needs egress, so `bridge` is the only sane functional default; `none` is reserved for `shell`.
+
+The host-callback gateway alias is ENGINE-SPECIFIC (the critic's podman finding): Docker uses `host.docker.internal`, Podman uses `host.containers.internal` (Docker's alias only exists on recent podman). A helper `hostGatewayAlias(engine)` returns the right name; Section 2.5, the create args, the `CODEMAN_API_URL` rewrite, and the host-guard allowlist all consume it, and BOTH aliases are added to the allowlist so a mixed fleet keeps working.
+
+### Key decision 5: hooks actually reach the host AND are actually installed
+
+Two independent things must both be true for a hook to fire, and the raw plan wired only the first:
+
+1. Network reachability. Claude Code hooks POST to `$CODEMAN_API_URL` (`curl -sk`). Inside a bridge container `localhost` is the container and prod binds `127.0.0.1`, so we set `--add-host <gatewayAlias>:host-gateway` on create (skipped on Docker Desktop, where the alias is native), add the gateway alias to the host guard, and provide `CODEMAN_API_URL` and the hook secret (below).
+2. Hook INSTALLATION. Hooks live in `<workspace>/.claude/settings.local.json`, written by the quick-start scaffolding block (around session-routes.ts ~1776) that calls `writeHooksConfig()` / `updateCaseModel()`. The raw plan extended the `!remote` guard to `!remote && !docker`, which would SKIP that block and silently disable ALL hooks regardless of networking. For docker the workspace is a REAL bind-mounted host dir, so the scaffolding block MUST run. Precise fix: extend to `!remote && !docker` ONLY the LOCAL-CLI-availability and local-spawn guards (the ones that stat the local binary or build the local spawn command); leave the workspace-scaffolding guard at `!remote` so it runs for docker. This same decision is what makes `modelOverride` work (Key decision 2). Consequence, surfaced as user-decision 4: linking a docker case now WRITES `.claude/settings.local.json` (and the CLAUDE.md scaffold, matching local-case behavior) into the user's real host directory, a behavioral shift from "link a dir" to "link and scaffold a dir."
+
+`CODEMAN_API_URL` derivation (the wrong-scheme bug the critic caught): prod is HTTPS-only on 3000, and `server.ts` (~2000) auto-sets `process.env.CODEMAN_API_URL = ${protocol}://${apiHost}:${port}`. Hardcoding `http://host.docker.internal:3000` fails every hook. Instead a pure helper `containerApiUrl(process.env.CODEMAN_API_URL, engine)` parses the running URL and substitutes ONLY the hostname with `hostGatewayAlias(engine)`, preserving scheme and port (`https://host.docker.internal:3000`). Unit-tested against http, https, non-default ports, and both engines. Passed as create-time `--env CODEMAN_API_URL=<derived>` (case-stable, non-secret).
+
+Hook secret and session attribution:
+- `~/.codeman/hook-secret` is bind-mounted read-only to a container path; `--env CODEMAN_HOOK_SECRET_FILE=<that path>` is create-time (a path is non-secret; the bytes ride the bind mount and are never committed).
+- `CODEMAN_SESSION_ID` (which the generated hooks reference at hooks-config.ts:78-80 to attribute events) plus `CODEMAN_MUX=1` are SESSION-scoped, so they are passed at EXEC time via `docker exec --env CODEMAN_SESSION_ID=<id> --env CODEMAN_MUX=1` (non-secret, value inline is fine, and exec env is not committed). Because a `tmux` session started fresh only inherits the invoking env when it starts the SERVER, the launch chain ALSO runs `tmux -L codeman-docker setenv -g CODEMAN_SESSION_ID <id>` (and `CODEMAN_MUX`) so reattaches and newly created panes see the same values. This mirrors how Codeman already injects per-session env into tmux for the external CLIs.
+
+Hooks-in-MVP-vs-deferred stays user-decision 4; if deferred, docker ships as explicitly hook-degraded and we lean on output-based idle detection through the docker-exec PTY.
+
+### Key decision 6: uid / HOME / rootless enforcement / macOS Docker Desktop
+
+The raw plan showed `--user 1000:1000` in one place and `--user "$(id -u):$(id -g)"` in another and never resolved HOME writability; this section fixes all of it.
+
+- Linux native (docker rootful or rootless): run `--user <hostUid>:0` (host uid, GID 0). The image follows the OpenShift arbitrary-uid convention: `HOME=/home/agent`, and `/home/agent` plus the tool cache dirs (`~/.npm`, `~/.cache`, `~/.config`) are owned `root:0` and group-writable (`chmod -R g+w`, `g+s` on dirs) so a process with GID 0 can write HOME even though its UID is not 1000. This keeps workspace files host-owned (the agent's UID is the host UID) AND keeps HOME writable, so the CLIs actually start.
+- Podman rootless: use `--userns=keep-id` (maps the host uid to the image's `agent` uid inside the container) instead of `--user`, so `/home/agent` is owned by the running user and workspace files are host-owned. This is a real per-engine branch in `buildDockerCreateArgs`.
+- macOS Docker Desktop: `--user <macUid>` (e.g. 501) does not own the image's `/home/agent`, so non-bind HOME writes fail EACCES and the CLIs may not start; Desktop also does its own bind-mount uid translation, provides `host.docker.internal` natively (no `--add-host`), and its VM memory ceiling can cap `--memory`. Detect Desktop via `docker info` (Server OS `linuxkit` / `OperatingString` contains "Docker Desktop") and take a dedicated path: do NOT pass `--user` (run as the image's baked `agent` uid and rely on Desktop's translation for workspace access), skip `--add-host`, and note in the UI that memory caps are subject to the VM ceiling.
+
+Rootless resource-cap enforcement (the silently-inert risk): rootless Docker without cgroup-v2 systemd delegation (`Delegate=yes`) silently IGNORES `--memory`/`--cpus`/`--pids-limit`. The probe checks `docker info` for `CgroupVersion=2` plus rootless plus delegation; if caps cannot be enforced, `checkDockerAvailable` returns `capsEnforced:false` and the link/probe surfaces "resource caps are advisory on this engine." Whether to REQUIRE delegation or ship-with-warning is user-decision 6.
+
+## 3. Data model
+
+New TypeScript types in `src/types/session.ts`, added right after the remote types (lines 46-99). SessionMode (line 44) is UNCHANGED.
+
+```ts
+export type DockerCommandMode = Extract<SessionMode, 'shell' | 'claude' | 'opencode' | 'codex' | 'gemini'>;
+export type DockerEngine = 'docker' | 'podman';
+export type DockerNetworkMode = 'bridge' | 'none' | 'custom'; // never 'host'
+
+export interface DockerResourceLimits {
+  memory?: string;    // '4g'  -> --memory 4g --memory-swap 4g (swap==memory: real OOM cap)
+  cpus?: string;      // '2'
+  pidsLimit?: number; // 512   (fork-bomb guard)
+  nofile?: string;    // '4096:8192'
+  shmSize?: string;   // optional; only when a tool needs /dev/shm
+}
+
+export interface DockerHost {
+  id: string;
+  label: string;
+  engine?: DockerEngine;             // default resolved by probe (docker, else podman)
+  image: string;                     // default resolved image ref (see user-decision 2)
+  daemonHost?: string;               // advanced: -H ssh://user@host / DOCKER_HOST
+  context?: string;                  // advanced: --context <ctx>
+  network?: DockerNetworkMode;       // default 'bridge'
+  networkName?: string;              // when network === 'custom'
+  resources?: DockerResourceLimits;
+  mountCredentials?: boolean;        // default true (false = sealed; blocks full-image export)
+  hooksEnabled?: boolean;            // default true (host-gateway callback wiring)
+  resumeOnStart?: boolean;           // default true (see Key decision 1 / user-decision 7)
+  commands?: Partial<Record<DockerCommandMode, string>>;
+  extraCreateArgs?: string[];        // validated like extraSshOptions
+  extraExecArgs?: string[];
+}
+
+export interface DockerCase {
+  name: string;
+  type: 'docker';
+  hostId: string;
+  hostWorkspacePath: string;         // absolute HOST dir: bind src + Session.workingDir
+  containerWorkdir?: string;         // container path; default = hostWorkspacePath (mirror -> projHash match)
+  container?: string;                // default codeman-case-<slug>
+  lastClaudeSessionId?: string;      // captured resume id (Key decision 1)
+}
+
+export interface SessionDocker {     // flattened, round-trips through mux/state (mirror SessionRemote at 91)
+  hostId: string;
+  label: string;
+  engine: DockerEngine;
+  image: string;
+  containerName: string;
+  hostWorkspacePath: string;
+  containerWorkdir: string;
+  network: DockerNetworkMode;
+  networkName?: string;
+  resources?: DockerResourceLimits;
+  mountCredentials: boolean;
+  hooksEnabled: boolean;
+  resumeOnStart: boolean;
+  daemonHost?: string;
+  context?: string;
+  commands?: Partial<Record<DockerCommandMode, string>>;
+  extraCreateArgs?: string[];
+  extraExecArgs?: string[];
+  configHash?: string;               // drift detection (Key decision, Section 4)
+}
+```
+
+- `SessionState` gains `docker?: SessionDocker` immediately after `remote?` (line 219). It persists automatically because `SessionState` is structural and `state-store.ts` stores `toState()` verbatim.
+- `src/mux-interface.ts`: add `docker?: SessionDocker` to `MuxSession` (after line 38), `CreateSessionOptions` (after 81), `RespawnPaneOptions` (after 105). `MuxSession.docker` round-trips through `mux-sessions.json` automatically.
+- `src/types/api.ts` `CaseInfo`: add `'docker'` to the `location` union and a `docker?: { hostId; container; image?; path; network }` display block.
+- `src/services/unified-session-service.ts`: add a boolean `docker?` flag on `UnifiedSessionItem` and source rows, set from `MuxSession.docker` presence (mirror the `remote` flag at ~line 200 and the harvest at session-routes.ts:2313).
+
+New state files (all via `dataPath()`, mirroring `remote-hosts.json` / `remote-cases.json`):
+
+- `~/.codeman/docker-hosts.json` (reusable engine/image/network/resource profiles).
+- `~/.codeman/docker-cases.json` (`name -> DockerCase`, including `lastClaudeSessionId`).
+- `~/.codeman/docker-exports/` (dedicated dir for `.image.tar.gz` + `.workspace.tar.gz` + `manifest.json`; never inline in state.json; retention/pruning per Section 5).
+
+No new `state.json` / `mux-sessions.json` files: `SessionState.docker` and `MuxSession.docker` ride the existing serialization.
+
+## 4. Container lifecycle (exact command shapes)
+
+All builders are PURE string functions (directly unit-testable). Host values interpolated into the outer `bash -c "..."` layer (container name, image, workdir, host paths) are `shellescape()`'d and, for user-supplied fields, schema-rejected for `$`/backtick via `NO_SHELL_META`. The escaping chain here is DEEPER than remote's single `ssh '<tmux ...>'`: the whole `docker inspect || docker create <dozens of --mount/--env/shellescaped host paths>` is interpolated into `bash -c "..."` then `JSON.stringify`'d into respawn-pane. This is a known place to get stuck, so it is covered by concrete escaping tests (Section 9), including host workspace paths containing spaces, not just a "we call shellescape" claim.
+
+New in `src/tmux-manager.ts`:
+
+```ts
+const DOCKER_TMUX_SOCKET = 'codeman-docker';
+// 'dkr' letters deliberately FAIL SAFE_MUX_NAME_PATTERN (^codeman-[a-f0-9-]+$),
+// so a Codeman running INSIDE the container never adopts/resizes/respawns our session.
+export function dockerTmuxSessionName(id: string): string { return `codeman-dkr-${id.slice(0, 8)}`; }
+```
+
+`buildDockerBaseArgs(docker)` (pure, in `docker-hosts.ts`, mirror of `buildSshConnectionArgs`) emits the engine prefix tokens: `docker` (or `podman`) + optional `--context <ctx>` or `-H <daemonHost>`. `buildDockerCreateArgs(docker, sessionId)` emits the `docker create` flag array (with the per-engine uid/userns branch from Key decision 6).
+
+IMAGE PRESENCE (before any create, the auto-pull footgun the critic caught): the launch chain runs `docker image inspect <image> >/dev/null 2>&1` first; on miss it exits with a distinct message ("base image <ref> not present: build with scripts/build-agent-image.mjs or pull it") rather than triggering a blocking multi-GB auto-pull inside the tmux pane. `docker create` carries `--pull=never`. The tmux-availability probe likewise uses `docker run --rm --pull=never <image> sh -lc 'command -v tmux'` and reports the same build/pull hint if the image is absent, so the 15s-bounded probe never hangs on a pull.
+
+CREATE (the ensure step, embedded in the launch string):
+
+```
+docker create \
+  --name codeman-case-myproj --hostname myproj \
+  --label codeman.managed=1 --label codeman.instance=<CODEMAN_INSTANCE> \
+  --label codeman.case=myproj --label codeman.session=<id8> \
+  --label codeman.confighash=<hash> \
+  --pull=never --init --restart no \
+  --user 1000:0 \
+  --workdir '/home/arkon/cases/myproj' \
+  --mount type=bind,src='/home/arkon/cases/myproj',dst='/home/arkon/cases/myproj' \
+  --mount type=bind,src='/home/arkon/.claude',dst='/home/agent/.claude' \
+  --mount type=bind,src='/home/arkon/.codeman/hook-secret',dst='/home/agent/.codeman/hook-secret',readonly \
+  --add-host host.docker.internal:host-gateway \
+  --memory 4g --memory-swap 4g --cpus 2 --pids-limit 512 --ulimit nofile=4096:8192 \
+  --cap-drop ALL --security-opt no-new-privileges \
+  --network bridge \
+  --env HOME=/home/agent --env TERM=xterm-256color --env COLORTERM=truecolor \
+  --env CODEMAN_API_URL=https://host.docker.internal:3000 \
+  --env CODEMAN_HOOK_SECRET_FILE=/home/agent/.codeman/hook-secret \
+  codeman/agent:base \
+  sleep infinity
+```
+
+- `--user 1000:0` shown is the Linux-native form with GID 0 (Key decision 6); it is actually `--user <hostUid>:0`, or `--userns=keep-id` for podman rootless, or omitted on Docker Desktop. The literal is illustrative only.
+- Create-time `--env` carries only NON-SESSION, non-secret, case-stable values (safe to be committed): the DERIVED `CODEMAN_API_URL` (https-preserving, Key decision 5) and the hook-secret FILE PATH. `CODEMAN_SESSION_ID`/`CODEMAN_MUX` and the codex/gemini key NAMES are exec-time only.
+- `codeman.instance=<CODEMAN_INSTANCE>` is REQUIRED on the label set so the boot reaper is instance-scoped (a beta/second instance must never reap prod's containers).
+- `codeman.confighash` is a stable hash of the drift-relevant create args (image, resources, network, mounts, non-session env). Drift detection (user story 2, the config-never-takes-effect gap): on launch the ensure block compares the desired hash to the existing container's label; on mismatch the launch does NOT silently reuse the stale container. Instead the docker route returns a "container config changed, recreate?" action (SSE + UI confirm), and on confirm Codeman `docker rm`'s and recreates. rm destroys in-image (non-bind) state, but the workspace and transcripts survive on their bind mounts and the conversation is restored via `--resume`, so the recreate is safe. Auto-recreate-vs-prompt is a UI choice; the MVP prompts.
+- `--restart no` (resolved consistently with Key decision 1; recovery is Codeman's idempotent create-if-missing, not an engine restart policy, which also matters for Podman which has no daemon).
+
+EXEC (`buildDockerLaunchCommand`, the docker analog of `buildRemoteLaunchCommand`, TTY-correct, resume-aware). The whole thing is ONE `bash -c` string that image-checks, ensures, starts, primes tmux env, then execs:
+
+```
+docker image inspect codeman/agent:base >/dev/null 2>&1 || { echo 'Codeman: base image codeman/agent:base not present (build or pull it)'; exit 1; } ; \
+docker inspect codeman-case-myproj >/dev/null 2>&1 || docker create <all create args above> ; \
+docker start codeman-case-myproj >/dev/null 2>&1 || { echo 'Codeman: container codeman-case-myproj failed to start (daemon down?)'; exit 1; } ; \
+exec docker exec -it \
+  --workdir '/home/arkon/cases/myproj' \
+  --env TERM=xterm-256color --env COLORTERM=truecolor \
+  --env CODEMAN_SESSION_ID=1a2b3c4d --env CODEMAN_MUX=1 \
+  --env OPENAI_API_KEY --env GEMINI_API_KEY \
+  codeman-case-myproj \
+  sh -lc 'tmux -L codeman-docker setenv -g CODEMAN_SESSION_ID 1a2b3c4d \; setenv -g CODEMAN_MUX 1 \; new-session -A -s codeman-dkr-1a2b3c4d -c '\''/home/arkon/cases/myproj'\'' '\''cd /home/arkon/cases/myproj && exec claude --dangerously-skip-permissions --resume <claudeSessionId>'\'' \; set -t codeman-dkr-1a2b3c4d status off \; set -t codeman-dkr-1a2b3c4d mouse off \; set -t codeman-dkr-1a2b3c4d prefix C-q \; set -s escape-time 0'
+```
+
+- `docker exec -it`: `-t` allocates a PTY and forwards SIGWINCH into the container so the Ink TUI re-lays-out on pane resize; `TERM`/`COLORTERM` prevent degraded rendering. `--env OPENAI_API_KEY` (name only) is present only for codex/gemini and is exec-time (never committed). `CODEMAN_SESSION_ID`/`CODEMAN_MUX` are exec-time values plus a `tmux setenv -g` prime so reattaches and new panes inherit them (Key decision 5).
+- `--resume <claudeSessionId>` (codex `resume <id>`, gemini `--resume <id>`) is appended to `modeCommand` ONLY when a captured id exists; on first launch it is omitted. `new-session -A` makes the flag inert on a live-tmux reattach and effective only when tmux is re-created (Key decision 1).
+- `modeCommand = docker.commands?.[mode] || defaultDockerCommandForMode(mode)` (`exec claude --dangerously-skip-permissions`, `exec bash -l`, etc.), with the resume suffix injected by the builder.
+- Escaping survives every layer identically to remote in shape but deeper in nesting: `paneCommand` (`cd ... && exec ...`) is one shellescaped tmux arg, the whole `tmuxInvocation` is one shellescaped `sh -lc` arg, and the outer string is `JSON.stringify()`'d into `bash -c` by respawn-pane (tmux-manager.ts:1329).
+
+Wire-up (extend the two existing seams to 3-way):
+
+- createSession (tmux-manager.ts:1276): `const fullCmd = docker ? buildDockerLaunchCommand({ mode, docker, sessionId, resumeSessionId }) : remote ? buildRemoteLaunchCommand({ mode, remote, sessionId }) : localFullCmd;`
+- launchCmd cd-skip (tmux-manager.ts:1327): `const launchCmd = (remote || docker) ? fullCmd : \`cd ${JSON.stringify(workingDir)} && ${fullCmd}\`;`
+- respawnPane: same two edits at lines 1524 and 1542.
+
+START / reattach-after-reboot: the ensure block (image-check, `docker inspect || docker create`, `docker start`) is fully idempotent, so boot recovery just re-runs `buildDockerLaunchCommand` from the restored `MuxSession.docker` with the persisted resume id. A rebooted host recreates the container and resumes the conversation.
+
+DOCKER-DOWN surfacing (the PTY-exit-breaker false-trip risk): if `docker start` or `docker exec` cannot attach (daemon down, container missing), the launch prints a docker-specific message and exits, which alone would still count toward `session-pty-exit-breaker` and show a generic "respawn breaker tripped" push. To avoid masking the cause, the docker reattach path runs a fast `checkDockerAvailable` pre-flight: if the daemon/container is unreachable, Codeman broadcasts a docker-specific error (SSE + push, "container <name> is not running / daemon down") and SKIPS the auto-reattach that would trip the breaker, rather than fast-looping `docker exec`.
+
+STOP / KILL (`killSession` Strategy 3c, right after remote's Strategy 3b at tmux-manager.ts:1719, guarded by `IS_TEST_MODE`):
+
+```ts
+if (session.docker) {
+  // best-effort, fire-and-forget, timeout-bounded so it never blocks the local kill
+  execAsync(buildDockerKillCommand({ docker: session.docker, sessionId }), { timeout: EXEC_TIMEOUT_MS }).catch(() => {});
+}
+```
+
+`buildDockerKillCommand` emits: `docker exec codeman-case-<slug> tmux -L codeman-docker kill-session -t codeman-dkr-<id8> ; docker stop -t 10 codeman-case-<slug>`. Stopping frees CPU/RAM and, per Key decision 1, is safe for conversation continuity because the NEXT launch resumes from the bind-mounted transcript via `--resume`. Whether to stop at all (RAM vs instant live-agent reattach) is user-decision 6/1 (reframed honestly). The bind-mounted workspace and transcripts always survive on the host.
+
+REMOVE: only on explicit case delete (`docker rm -f codeman-case-<slug>`), gated behind an "export first?" UI prompt because rm destroys any in-image (non-bind) state. Instance-scoped boot reaper (fixing the racy/cross-instance reaper): after `docker-cases.json` is loaded AND after `restoreMuxSessions` has run, enumerate `docker ps -a --filter label=codeman.managed=1 --filter label=codeman.instance=<CODEMAN_INSTANCE> --format '{{.Names}}\t{{index .Labels "codeman.case"}}'` and `docker rm -f` only containers whose case is gone from THIS instance's `docker-cases.json`. The instance filter is what stops a beta reaping prod's containers (the exact cross-instance hazard the project memory warns about).
+
+AVAILABILITY PROBE (`docker-hosts.ts`, timeout-bounded like `checkRemoteTmuxAvailable`'s 15s, `IS_TEST_MODE` no-op):
+
+```
+docker info --format '{{json .}}'                                  # server up, CgroupVersion, rootless, OS (Desktop detect), cap-delegation
+docker image inspect <image> --format '{{.Id}}'                    # image PRESENT (no auto-pull)
+docker run --rm --pull=never <image> sh -lc 'command -v tmux'      # tmux-in-image gate (hard prerequisite), only if image present
+```
+
+`checkDockerAvailable()` returns `{ ok, engine, rootless, isDesktop, cgroupV2, capsEnforced }` (parse `SecurityOptions` for `name=rootless`, `CgroupVersion`, delegation, and Server OS for Desktop). `checkDockerTmuxAvailable(host)` returns a structured result with a user-facing error and correct install hint (NOT `npm install -g`; the hint is "build/pull the base image" for a missing image and "install docker or podman" for a missing engine).
+
+IN-CONTAINER CLI VERSION (fixing the #154 wheel-forwarding regression): the raw plan skipped the LOCAL `cliVersion` probe for docker (correct, since it reports the HOST claude) but left `cliVersion` undefined, which disables trackpad wheel-forwarding. Instead, for docker sessions Codeman runs an IN-CONTAINER probe `docker exec <container> claude --version` (bounded, `IS_TEST_MODE` no-op) and feeds THAT into `cliVersion`. This also means a stale baked CLI is visible; combined with the rebuild-cadence in user-decision 2, agents are not silently pinned to an old claude.
+
+## 5. Export / Import
+
+EXPORT is a concurrency-bounded job (reuse `runWithConversionLimit` from `document-conversion-limiter.ts` so N simultaneous exports cannot fork-bomb the host). Route `POST /api/docker-cases/:name/export`.
+
+Preconditions (the consistency and leak risks the critic caught):
+- Sealed guard: if `mountCredentials:false`, full-image export is REFUSED unless the caller explicitly opts into the pre-commit scrub (Key decision 2). Workspace-only export is always allowed.
+- Quiesce + free-space: require the session idle, then `docker pause` the container spanning BOTH the workspace tar AND the commit so the two artifacts are mutually consistent (the raw plan paused only the commit, leaving the bind-mount tar to run against a mid-write agent). Before any heavy step, precheck free space in the exports dir and in `/var/lib/docker`; if below `DOCKER_EXPORT_MIN_FREE_BYTES`, refuse with a clear error (a full `/var/lib/docker` wedges the daemon and breaks EVERY session on the host).
+
+Steps (all cleanup in try/finally so a mid-way failure never orphans an intermediate image or leaves the container paused):
+
+1. `docker commit -c 'LABEL codeman.exported=1' codeman-case-<slug> codeman/export-<slug>:<ts>` (unique tag per export defeats the stale-image trap). Optional pre-commit scrub in sealed mode as above; also blank instance-specific committed env (`-c 'ENV CODEMAN_API_URL='` etc.) so the image carries no stale host references.
+2. `docker save codeman/export-<slug>:<ts> | gzip` streamed in fixed 8192-byte chunks to `~/.codeman/docker-exports/<slug>-<ts>.image.tar.gz`. Uses `docker save` (layers + repo:tag + CMD), never `docker export` (flat rootfs), so restore is a trivial `docker load`.
+3. `tar --numeric-owner -C <hostWorkspacePath> -czf <slug>-<ts>.workspace.tar.gz .` while paused (the bind-mounted workspace is NOT in the image, so it travels separately and consistently).
+4. Write `manifest.json`: schema version, caseName, image tag, engine, containerWorkdir, resource/network config, codeman version, base-image digest, createdAt, per-member sha256, `mountCredentials`, and `secretFree` (true only for convenient-mode or scrubbed-sealed exports).
+5. `docker rmi codeman/export-<slug>:<ts>` in the `finally` (delete the intermediate committed image regardless of success), then `docker unpause`.
+
+The three files are wrapped in one bundle `<slug>-<ts>.codeman-container.tgz` and offered as a downloadable artifact through the existing file-routes streaming + attachment-registry handoff.
+
+Retention / disk budget (user-decision 3): `docker-exports/` is capped at `DOCKER_EXPORT_KEEP` most-recent bundles with an auto-prune on each new export, plus the free-space precheck above. Workspace scrub: the WORKSPACE tar gets a scan/warn pass for agent-created `.env` / `.git/credentials` (a distinct leak channel from container creds). A lighter "workspace-only" export (just the workspace tar, no commit/save) is the fast default for 24h+ runs; full-image is the explicit heavier option (user-decision 7 in the original list, now decision on the default button below).
+
+What travels: the baked toolchain image plus any in-image writes, and the workspace tar. What does NOT travel: bind-mounted credentials (physically excluded from commit) and anything that lived only in a bind mount. Secret-free by construction in convenient mode, and enforced (refuse-or-scrub) in sealed mode.
+
+IMPORT `POST /api/docker-cases/import` (untrusted-bundle containment, the traversal/overwrite risk): stream the uploaded bundle, validate every manifest checksum BEFORE any extraction or load. Extract the workspace tar with `tar --no-absolute-names -C <fresh dir>` PLUS per-entry validation rejecting any member whose normalized path escapes the destination (leading `/` or `..` components). `gunzip | docker load` the image, then RE-TAG the loaded image id into a quarantined namespace `codeman/imported-<slug>:<ts>` and NEVER allow the load to overwrite `codeman/agent:base` or any pre-existing tag (capture the loaded id, ignore the bundle's repo:tag). Create a NEW `DockerCase` pointing at the quarantined image with THIS host's mounts/creds and the manifest's resource/network config, and recreate the container hardened (cap-drop ALL, no-new-privileges, non-root, `--pull=never`, CMD overridden to `sleep infinity`). The destination supplies its own login, so credentials never cross machines. Plus `GET /api/docker-exports` (list) and `DELETE /api/docker-exports/:filename`, all behind Codeman's existing auth / loopback-default / host-guard / Origin-CSRF stack.
+
+## 6. Codeman integration (file-by-file, mirroring the remote-SSH feature)
+
+- `src/types/session.ts`: add `DockerCommandMode`, `DockerEngine`, `DockerNetworkMode`, `DockerResourceLimits`, `DockerHost`, `DockerCase`, `SessionDocker` (Section 3). Add `docker?: SessionDocker` to `SessionState` after line 219. SessionMode (line 44) UNCHANGED.
+- `src/mux-interface.ts`: add `docker?: SessionDocker` to `MuxSession` (38), `CreateSessionOptions` (81), `RespawnPaneOptions` (105).
+- `src/docker-hosts.ts` (NEW, direct mirror of `src/remote-hosts.ts`): `readDockerHosts`/`writeDockerHosts`/`readDockerCases`/`writeDockerCases` (via `dataPath`, including `lastClaudeSessionId` read/write), `defaultDockerCommandForMode` (mirror line 60), `dockerDisplayPath` (`container:/path`, mirror `remoteDisplayPath` at 205), `toSessionDocker(host, case)` (mirror `toSessionRemote` at 212), `buildDockerBaseArgs`/`buildDockerCreateArgs` (per-engine uid/userns branch), `hostGatewayAlias(engine)`, `containerApiUrl(processApiUrl, engine)` (scheme+port-preserving, unit-tested), `checkDockerAvailable`/`checkDockerTmuxAvailable`/`probeDockerCliVersion` (15s-bounded, `IS_TEST_MODE` no-op), a config-hash helper for drift, its own POSIX `shellescape` copy (mirror line 83). `const IS_TEST_MODE = !!process.env.VITEST;` gates every real `docker` invocation.
+- `src/tmux-manager.ts`: add `DOCKER_TMUX_SOCKET`, `dockerTmuxSessionName`, `buildDockerLaunchCommand` (resume-aware, image-check, env-prime), `buildDockerKillCommand` (Section 4). Extend the two `fullCmd` ternaries (1276, 1524) and the two `launchCmd` cd-skips (1327, 1542). Add `killSession` Strategy 3c after 1719. Ensure `reconcileSessions` (~1800-1815) does NOT hard-delete docker sessions on local-tmux death (recovery relaunch path).
+- `src/session.ts`: add `_docker?: SessionDocker` field (mirror `_remote` at 403), constructor arg (477), assignment (550). Thread `docker: this._docker` and `resumeSessionId: this._claudeSessionId` into BOTH `createSessionOptions` and `respawnPaneOptions` in `startInteractive` (1352/1370) and the second path (1740/1750). Emit `docker: this._docker` in `toState()` (1010). Replace the LOCAL cliVersion probe at 1320 for docker with the IN-CONTAINER `probeDockerCliVersion` (do not merely skip it). Extend `resolveMuxAttachCwd(workingDir, remote, docker)` (215) to return `/tmp` when `docker` is set. On claudeSessionId capture, persist it to the owning `DockerCase.lastClaudeSessionId`.
+- `src/web/server.ts`: in `restoreMuxSessions` (2160), add `docker: muxSession.docker ?? savedState?.docker` to the `new Session({...})` call (2195-2216), and skip docker in the same `isExternalCliMode`/Ralph recovery guards as remote. Register the instance-scoped boot reaper to run AFTER docker-cases load and AFTER `restoreMuxSessions`. Ensure `CODEMAN_API_URL` derivation reads the SAME `process.env.CODEMAN_API_URL` the server sets at ~2000.
+- `src/web/schemas.ts`: add `DockerHostSchema` and `DockerCaseLinkSchema` (below). The three mode enums (177/373/705) and `QuickStartSchema` (368) UNCHANGED (docker resolves by `caseName` lookup like remote).
+- `src/web/routes/session-routes.ts`: import the docker helpers from `../../docker-hosts.js`. Add a docker branch in `/api/quick-start` parallel to the remote branch (1686-1720): `readDockerCases` -> find by `caseName` -> `readDockerHosts` -> find by `hostId`; reject `envOverrides`/`effort`/`codexConfig`/`geminiConfig`/`openCodeConfig` (but ACCEPT `modelOverride`, which flows via scaffolded `settings.local.json`); run `checkDockerAvailable` + `checkDockerTmuxAvailable` (image-present, engine, caps-enforced); surface `capsEnforced:false` and Desktop notes; set `casePath = dockerCase.hostWorkspacePath` (REAL host dir), `docker = toSessionDocker(host, dockerCase)`, and seed `resumeSessionId` from `dockerCase.lastClaudeSessionId` when `resumeOnStart`. Extend the LOCAL-availability and local-spawn guards (around 1796/1810) to `!remote && !docker`, but DO NOT extend the workspace-scaffolding guard (~1776, `writeHooksConfig`/`updateCaseModel`), which MUST run for docker. Pass `docker` into `new Session` (1847); `autoConfigureRalph` (1853) gated on `!docker`. Add `docker: m.docker !== undefined ? true : undefined` to the unified harvest (2313).
+- `src/web/routes/case-routes.ts`: import the docker read/write/check helpers + schemas. Add a docker listing loop in `GET /api/cases` (mirror 94-119, `location: 'docker'`, `docker: {...}` via `dockerDisplayPath`). Add `/api/docker-hosts` GET/POST/PUT/DELETE (mirror 168-204) and `POST /api/cases/docker-link` (mirror 206-232; run `checkDockerAvailable`/`checkDockerTmuxAvailable` at link time; broadcast `CaseLinked` with `type: 'docker'`). Add a docker-unlink branch to `DELETE /api/cases/:name` (mirror 288-296; `docker rm -f`; broadcast `CaseDeleted` `type: 'docker-unlinked'`). Add the docker branch to single-case `GET` (mirror 358-368). Add `POST /api/docker-cases/:name/export`, `/import`, `GET/DELETE /api/docker-exports`, and a `POST /api/docker-cases/:name/recreate` (drift confirm) per Sections 4 and 5.
+- `src/web/sse-events.ts` + `src/web/public/constants.js`: reuse `CaseLinked`/`CaseDeleted` for CRUD. Add `docker:exportProgress`, `docker:exportComplete`, `docker:importComplete`, `docker:configDrift`, and `docker:containerError` to BOTH registries (kept in sync per CLAUDE.md).
+- Frontend `src/web/public/index.html` (~1831): add a Docker `modal-tab-btn` next to Remote; add a `#case-docker` panel mirroring `#case-remote` with `dockerCaseName`, `dockerHostWorkspacePath`, `dockerContainer`, `dockerImage`, `dockerHostId`, and an Advanced `<details>` for network mode, resource caps, `mountCredentials`, `resumeOnStart`, and remote daemon. Surface a "scaffolds .claude into this host dir" note (user-decision 4) and a "resource caps advisory on this engine" warning when `capsEnforced:false`.
+- Frontend `src/web/public/session-ui.js`: `formatCasePickerLabel` (48) + `buildCasePickerOptions` (71-73) handle `location === 'docker'` (`name @ container`, add container/image to the search haystack); `resetCaseModalFields` (~1514) add a `dockerFields` array; `switchCaseModalTab` (1573/1580/1597) handle `'case-docker'`; `submitCaseModal` add the docker branch; new `linkDockerCase()` (mirror `linkRemoteCase` at 1689) POSTing `/api/docker-hosts` then `/api/cases/docker-link`, sending omitted optionals as `undefined` (spread `...(x ? {x} : {})`, never `null`, per the Zod `.optional()`-rejects-null gotcha); `runClaude` (520) / `runShell` (702) extend the `location === 'remote'` routing to also match `'docker'`; `runOpenCode`/`runCodex`/`runGemini` (792/846/900) make the `isRemote` checks `isRemoteOrDocker` so local status probes are skipped. In the session-options Summary tab, note that `effort` is inert for docker (rejected) while `model` IS honored via `settings.local.json`.
+- Frontend `src/web/public/panels-ui.js` (425-426): add `caseItem?.docker?.path`/`container` to the case-search fields.
+
+Schemas (`src/web/schemas.ts`), mirroring `RemoteHostSchema` (299) / `RemoteCaseLinkSchema` (351):
+
+```ts
+export const DockerHostSchema = z.object({
+  id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  label: z.string().min(1).max(100),
+  engine: z.enum(['docker', 'podman']).optional(),
+  image: z.string().min(1).max(512).regex(/^[a-zA-Z0-9][\w./:@-]*$/, 'Invalid image ref').regex(NO_SHELL_META),
+  daemonHost: z.string().max(512).regex(NO_SHELL_META, 'Invalid daemon host').optional(),
+  context: z.string().max(128).regex(/^[a-zA-Z0-9._-]+$/, 'Invalid context').optional(),
+  network: z.enum(['bridge', 'none', 'custom']).optional(),
+  networkName: z.string().max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/).optional(),
+  resources: z.object({
+    memory: z.string().regex(/^\d+[bkmg]?$/i).optional(),
+    cpus: z.string().regex(/^\d+(\.\d+)?$/).optional(),
+    pidsLimit: z.number().int().positive().max(100000).optional(),
+    nofile: z.string().regex(/^\d+:\d+$/).optional(),
+    shmSize: z.string().regex(/^\d+[bkmg]?$/i).optional(),
+  }).strict().optional(),
+  mountCredentials: z.boolean().optional(),
+  hooksEnabled: z.boolean().optional(),
+  resumeOnStart: z.boolean().optional(),
+  commands: RemoteCommandOverridesSchema, // reuse the shared shape
+  extraCreateArgs: z.array(z.string().min(1).max(1024).regex(NO_SHELL_INJECTION).refine(noCommandSubstitution)).max(32).optional(),
+  extraExecArgs: z.array(z.string().min(1).max(1024).regex(NO_SHELL_INJECTION).refine(noCommandSubstitution)).max(32).optional(),
+});
+
+export const DockerCaseLinkSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
+  hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
+  hostWorkspacePath: z.string().min(1).max(2000).regex(/^\//, 'Path must be absolute').regex(NO_SHELL_META, 'Invalid characters in workspace path'),
+  containerWorkdir: z.string().min(1).max(2000).regex(/^\//).regex(NO_SHELL_META).optional(),
+  container: z.string().min(2).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name').optional(),
+});
+```
+
+`NO_SHELL_META` (rejects `$`/backtick, schemas.ts:297) is REQUIRED on `image`, `hostWorkspacePath`, `containerWorkdir`, and `container`, because all four reach the outer `bash -c "..."` double-quote layer where `$(...)`/backtick re-expose, exactly the reason `remotePath`/`identityFile` use it. `--privileged` and any `-v /var/run/docker.sock` are structurally unrepresentable (never emitted by the builder, never accepted by the schema).
+
+## 7. Security model
+
+- Hardening flags on every create: `--cap-drop ALL`, `--security-opt no-new-privileges` (NOT auto-set by rootless Docker or Podman, so always explicit), the uid/userns branch of Key decision 6 (never container-root; workspace files stay host-owned and HOME stays writable via GID 0), `--pids-limit` (fork-bomb guard), `--memory` with `--memory-swap == --memory` (real OOM cap), `--ulimit nofile`, `--init`, `--pull=never`. NEVER `--privileged`, NEVER mount the docker socket into the agent container. `--storage-opt size=` is emitted ONLY after the probe confirms overlay2-on-xfs-pquota or btrfs (the AICE-class silently-ignored trap); otherwise it is omitted and the UI does not advertise a size cap. Resource caps are advertised as ENFORCED only when the probe reports `capsEnforced:true`; under non-delegated rootless they are labeled advisory (user-decision 6).
+- Engine: prefer whichever the probe finds, Podman-rootless first for security (a container-root breakout lands as an unprivileged host user). Rootless bind-mount ownership uses `--userns=keep-id` (Podman) vs `--user <hostUid>:0` (Docker), so real per-engine branching lives in `buildDockerCreateArgs`. Docker Desktop takes its own uid path (Key decision 6).
+- Blast radius (the combined-posture the critic asked to surface, user-decision 5): the default convenient profile mounts an arbitrary host workspace dir RW (host-owned, mirrored path) AND host `~/.claude`/`~/.codex`/`~/.gemini`/`~/.config/gcloud`/`~/.config/opencode` RW into a NETWORK-ENABLED container. Container-run agent code can therefore read/modify those host trees and reach the network simultaneously. This is still a strict improvement over today's on-host skip-permissions execution, but the user must accept the combined posture explicitly; the sealed profile plus `network:none` is the mitigation for genuinely untrusted work.
+- Secret handling: creds arrive ONLY as bind-mounted files (default) or exec-time NAME-ONLY `--env` (codex/gemini keys), NEVER as create-time `-e` and NEVER as an image layer. Sealed-mode export is refuse-or-scrub (Section 5), closing the sealed-leak inversion.
+- CLAUDE.md "Multi-CLI prefix discipline": the exec-time name-only env is restricted to the CLI-specific keys per mode (Claude: none with OAuth mount; Codex: `OPENAI_API_KEY`/`CODEX_API_KEY`; Gemini: `GEMINI_API_KEY`/`GOOGLE_*`), never a blanket forward. `envOverrides` is rejected for docker, so the `ALLOWED_ENV_PREFIXES` allowlist is not widened.
+- hook-secret: bind-mounted read-only, referenced via `CODEMAN_HOOK_SECRET_FILE` (a path, non-secret); the secret bytes never enter env or the image. Both `host.docker.internal` and `host.containers.internal` are added to the host-guard allowlist so the in-container hook curl's Host header passes on either engine.
+- Host guard / instance isolation: the in-container tmux socket (`codeman-docker`) and name (`codeman-dkr-<id8>`) deliberately FAIL a container-internal Codeman's `SAFE_MUX_NAME_PATTERN`, so a nested Codeman never adopts our session (unit-asserted). The boot reaper is instance-scoped by the `codeman.instance` label so a beta never reaps prod. Any remote-daemon (`-H`/`--context`) mode is host-root-equivalent and stays strictly behind the existing auth/loopback/host-guard/Origin-CSRF stack.
+- Import containment: untrusted bundles are checksum-validated, extracted with traversal guards, and loaded into a quarantined image namespace (never overwriting the base image), then run with the same hardening.
+
+## 8. Phased implementation (branch: `feat/docker-session-mode`)
+
+Each phase is independently testable; per CLAUDE.md, end-to-end test in the real env before COM. All new docker IO paths carry `const IS_TEST_MODE = !!process.env.VITEST;` and no-op under it; the pure command builders are tested directly.
+
+- Phase 0: base image + engine probe. Author `docker/agent.Dockerfile` (OpenShift arbitrary-uid HOME) and `scripts/build-agent-image.mjs` (build or pull the base image; digest recorded). Add `checkDockerAvailable`/`checkDockerTmuxAvailable`/`containerApiUrl`/`hostGatewayAlias` (IS_TEST_MODE no-op) and `GET /api/docker/status`. Test: probe stub returns available/caps/Desktop flags under VITEST; `containerApiUrl` preserves scheme+port and swaps host per engine; status route returns the envelope.
+- Phase 1: types + storage + schemas. Add all types (Section 3), `src/docker-hosts.ts`, `DockerHostSchema`/`DockerCaseLinkSchema`. Test: `docker-hosts.test.ts` (round-trip incl. `lastClaudeSessionId`, display path, config-hash stability); `docker-exec-options.test.ts` (schema rejects `$`/backtick in image/workdir/container).
+- Phase 2: tmux-manager builders. Add `DOCKER_TMUX_SOCKET`, `dockerTmuxSessionName`, `buildDockerLaunchCommand` (resume-aware, image-check, env-prime), `buildDockerKillCommand`; wire the two ternaries + two cd-skips + Strategy 3c; harden `reconcileSessions` against docker hard-delete. Test (pure strings): adopt-proof name fails `SAFE_MUX_NAME_PATTERN`; image-check precedes create; `new-session -A` idempotent; resume flag present only when a resume id is passed; `--pull=never` present; instance label present; escaping survives `bash -c` -> `docker exec` -> `sh -lc` -> tmux WITH a host workspace path containing spaces.
+- Phase 3: session.ts + mux + recovery. Add `_docker` + `resumeSessionId` threading, in-container cliVersion probe, `resolveMuxAttachCwd`, mux-interface fields, `restoreMuxSessions` passthrough, instance-scoped reaper wiring, claudeSessionId -> `DockerCase.lastClaudeSessionId` persistence, unified flag. Test: `toState()` emits docker; a persisted docker session round-trips through mux/state; a relaunch injects the persisted resume id (mock mux); reaper only targets this instance's orphaned containers.
+- Phase 4: routes + first real e2e. case-routes CRUD + listing + drift-recreate; session-routes quick-start branch (scaffolding RUNS, local-availability guards skip, model accepted, effort/config rejected). Manual e2e on a real docker host: docker-host create -> docker-link -> quick-start; confirm the pane runs `claude` in the container, files land host-owned, a Codeman restart reattaches the SAME live agent, and a `docker stop` followed by relaunch RESUMES the conversation.
+- Phase 5: hooks connectivity + installation. host-gateway (per engine), derived `CODEMAN_API_URL`, hook-secret mount, `CODEMAN_SESSION_ID`/`CODEMAN_MUX` exec-env + tmux setenv, host-guard allowlist, and the scaffolding write into the real workspace. Manual e2e: trigger a permission prompt from inside the container and confirm it surfaces; verify hook payloads carry the right session id. If deferred, ship docker as explicitly hook-degraded and verify output-based idle detection through the docker-exec PTY.
+- Phase 6: export/import + GC + disk safety. quiesce+pause span, free-space precheck, commit+save+gzip + workspace tar + manifest + streaming download; sealed-mode refuse-or-scrub; retention/auto-prune; import with checksum validation + traversal guard + quarantined re-tag; drift-recreate; boot reaper; `runWithConversionLimit` cap; `docker rmi` in finally. Manual e2e: export, `docker load` on a second machine (or fresh case), import, confirm toolchain + workspace restored and NO creds present; attempt a sealed full-image export and confirm it is refused-or-scrubbed; attempt a `../` bundle and confirm it is rejected.
+- Phase 7: frontend. Docker tab, `linkDockerCase`, run wiring, case-picker labels, panels search, caps-advisory + scaffold-warning + effort-inert notes. Verify with Playwright (`waitUntil: 'domcontentloaded'`, 3-4s settle) that the Docker tab renders and a linked docker case appears in the picker.
+- Phase 8: docs + COM. Update CLAUDE.md (a "Docker cases" Key Pattern paragraph mirroring remote-SSH, plus the new state files, routes counts, and the resume/durability model), `docs/docker-cases.md`, then COM per the standard flow.
+
+## 9. Test plan
+
+- Unit (pure, CI-safe, mirror `test/remote-hosts.test.ts` / `test/remote-ssh-options.test.ts`):
+  - `test/docker-hosts.test.ts`: storage round-trip (incl. `lastClaudeSessionId`), `dockerDisplayPath`, `defaultDockerCommandForMode`, `toSessionDocker`, `containerApiUrl` (http/https, custom port, docker vs podman gateway), config-hash stability/drift, `buildDockerCreateArgs` flag ordering (cap-drop/no-new-privileges/memory==memory-swap/instance-label/`--pull=never` present; host/privileged/socket absent; per-engine uid vs `--userns=keep-id`).
+  - `test/docker-exec-options.test.ts`: `buildDockerLaunchCommand`/`buildDockerKillCommand` string shape and escaping through `bash -c` -> `docker exec` -> `sh -lc` -> tmux, including a workspace path with spaces; resume flag present only with a resume id; image-presence check precedes create; `dockerTmuxSessionName` fails `SAFE_MUX_NAME_PATTERN`; schema rejects `$`/backtick in image/workdir/container/name; `linkDockerCase`-shaped bodies with omitted optionals validate (no `null` on the wire).
+  - Probe no-op: `checkDockerAvailable`/`checkDockerTmuxAvailable`/`probeDockerCliVersion` return canned values under VITEST and never spawn.
+- Integration (route tests via `app.inject()`, docker no-op'd): `/api/docker-hosts` CRUD; `/api/cases/docker-link` dup-check + broadcast; `GET /api/cases` includes the docker case with `location: 'docker'`; `/api/quick-start` docker branch rejects `envOverrides`/`effort`/config but ACCEPTS `modelOverride`, runs the workspace-scaffolding path, and constructs a session with `docker` set + seeded resume id; `DELETE /api/cases/:name` docker-unlink; export refuse-or-scrub for sealed; import traversal rejection; reaper instance-scoping (label filter). Pick a unique port only if a live-server test is added (search `const PORT =`; 3150+).
+- Manual end-to-end (real docker daemon, the mandatory "always end-to-end test" gate): build the base image; link a docker case; quick-start `claude`; verify OAuth via the mounted `~/.claude`, transcript correlation (subagent/workflow watchers show the session), host-owned files, and a working permission-prompt hook; reattach after a Codeman PROCESS restart (SAME live agent); `docker stop` then relaunch and confirm conversation RESUME; reboot-equivalent (daemon restart) and confirm boot recovery recreates+resumes; change the host's memory/image and confirm the drift-recreate prompt fires; export (convenient) and confirm the tar `docker load`s with no creds; attempt a sealed full-image export and confirm refuse-or-scrub; import into a fresh case; delete the case and confirm `docker rm -f` plus instance-scoped reaper GC; confirm a docker-down state surfaces a docker-specific error and does NOT trip the generic PTY-exit breaker.
+
+## 10. Open decisions for the user
+
+1. Credential + blast-radius posture (combined). Convenient default bind-mounts host `~/.claude` etc. RW AND an arbitrary host workspace RW into a network-enabled container, so container-run agent code can read/modify those host trees and reach the network at the same time. Recommended: convenient default plus a per-host SEALED opt-in (`mountCredentials:false` + `network:none`) for untrusted work. Please confirm you accept the combined arbitrary-workspace-plus-egress-plus-host-creds posture for the default profile (it is still a net improvement over today's on-host skip-permissions execution).
+2. Base image ownership, registry, and freshness. The `codeman/agent:base` placeholder implies a Docker Hub org the project may not own. Pick the real registry/namespace (GHCR under the repo is the natural fit), decide digest pinning, and set a REBUILD CADENCE so agents are not stuck on a stale baked `claude` (the in-container version probe surfaces staleness, but something must trigger rebuilds). Choose: pull a pinned published image, build locally on first use via `scripts/build-agent-image.mjs`, or both.
+3. Container CWD strategy. Mirror the host workspace path inside the container (recommended: makes transcript projHash correlate, file features and resume capture work) vs a fixed `/workspace` (simpler mount, breaks watcher correlation). Please confirm the mirror approach.
+4. Hooks in the MVP AND workspace scaffolding. Making docker hooks fire requires WRITING `.claude/settings.local.json` (and the CLAUDE.md scaffold) into the user's REAL linked host directory, a behavioral shift from "link a dir" to "link and scaffold a dir." Choose: wire hooks + scaffolding now (Phase 5, recommended, and it also enables the model picker), or ship docker as explicitly hook-degraded (no permission prompts / hook-idle) for v1 and add later. Confirm you are OK with Codeman mutating the linked host workspace.
+5. Session-kill teardown and RESUME (reframed honestly). `docker stop` on session kill is not merely "free RAM vs instant reattach": it destroys the in-container live agent, and the conversation survives ONLY because the next launch runs `--resume` from the bind-mounted transcript. Choose: keep the container running (costs RAM, preserves the exact live in-flight agent) vs stop and rely on `--resume` (frees RAM, may lose uncommitted in-flight tool state). Case-delete always `docker rm -f`.
+6. Rootless enforcement posture. Under rootless without cgroup-v2 systemd delegation, `--memory`/`--cpus`/`--pids-limit` are SILENTLY ignored. Choose: REQUIRE delegation (refuse to link a host that cannot enforce caps) or ship-with-warning ("resource caps are advisory on your engine"). The probe reports `capsEnforced` either way.
+7. Default resume behavior. Should a re-linked or re-run docker case default to resuming its last conversation (`resumeOnStart:true`, using `DockerCase.lastClaudeSessionId`) rather than starting clean? This is the crux of making the durability story real and is the recommended default, but it changes user-visible behavior (a new session in an existing case continues the prior conversation).
+8. Export defaults and disk budget. Default export button: workspace-only (fast, small, files-only, recommended for 24h+ runs) vs full-image (reproducible env, multi-GB). Also set the retention cap (max retained exports), the auto-prune policy, and the free-space threshold below which export is refused (a full `/var/lib/docker` breaks EVERY session on the host, not just docker ones).
+9. Remote docker daemon (`-H ssh://...` / `--context`). Support in the MVP (composes with remote hosts, adds host-root trust surface) or local-daemon-only first.
+10. Podman parity depth. Full `--userns=keep-id` plus Quadlet boot-persistence, or Docker-first with Podman as best-effort and boot-persistence via Codeman's idempotent create-if-missing only. Note the podman host alias is `host.containers.internal`, already handled per engine.

docs/docker-cases.md

@@ -0,0 +1,95 @@
+# Docker cases
+
+Run a case inside an **isolated Docker container** instead of directly on the host. Any number of Codeman sessions can share one container (it is scoped to the case, not the session), so a whole project lives in a sandbox with its own network, resource caps, and filesystem, and you can **export the container to move it to another machine**.
+
+Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` all work inside the container.
+
+## One-time setup: build the base image
+
+The container needs a base image with the agent toolchain (node, the CLIs, git, tmux). Build it locally once:
+
+```bash
+node scripts/build-agent-image.mjs          # builds codeman/agent:base
+# options: --engine docker|podman  --image <ref>  --no-cache
+```
+
+The image is **secret-free**: credentials are delivered at runtime (bind mounts or `docker exec --env`), never baked in, so exports never leak them.
+
+## Quickest path: one-click "Run in Docker"
+
+On the **New case → Create New** tab there's a **🐳 Run in an isolated Docker container** checkbox. Checking it alone is enough: Codeman creates the case folder in `~/codeman-cases/<name>`, spins up a hardened container with sensible defaults (auto-provisioning a shared `default` host), and starts the session inside it. No host/image/network fields to fill in.
+
+Click the checkbox's **Container settings** to optionally tweak the predefined defaults, including a **Template** picker:
+
+| Template | Memory | CPUs | GPUs |
+|----------|--------|------|------|
+| Small | 2 GB | 1 | none |
+| Medium (default) | 4 GB | 2 | none |
+| Large | 8 GB | 4 | none |
+| GPU | 8 GB | 4 | all (needs the NVIDIA container toolkit) |
+
+**Disk is elastic** — the container's storage grows automatically as data flows in; there is no fixed cap (bounded only by host disk). Any tweaked setting creates a dedicated per-case host so it never changes the shared `default`.
+
+## Create a docker case (full control)
+
+App → **New case → Docker** tab:
+
+- **Case Name** / **Workspace Path**: the workspace is a real HOST directory bind-mounted into the container at the same path. Codeman scaffolds `CLAUDE.md` + `.claude/settings.local.json` (hooks) into it, and file previews / attachments work on the real bytes.
+- **Host ID**: a reusable docker host profile (image, network, resources). Reuse the same ID across cases to share settings.
+- **Network**: `bridge` (internet on, default), `none` (fully isolated), or a `custom` bridge.
+- **Advanced**: memory / CPU caps, **Mount host credentials** (on = your existing `~/.claude` login just works; off = a sealed sandbox you log into inside the container), **Resume last conversation on relaunch**.
+
+Then run it like any case (Run Claude / Run Shell / …). The first launch creates the container (`codeman-case-<name>`); subsequent sessions attach to the same one.
+
+Equivalent API:
+
+```bash
+curl -X POST localhost:3000/api/docker-hosts -d '{"id":"local","label":"Local","image":"codeman/agent:base"}'
+curl -X POST localhost:3000/api/cases/docker-link -d '{"name":"sandbox","hostId":"local","hostWorkspacePath":"/home/you/projects/sandbox"}'
+curl -X POST localhost:3000/api/quick-start -d '{"caseName":"sandbox","mode":"claude"}'
+```
+
+## Lifecycle
+
+- **Reconnect after a Codeman restart** lands back in the same live agent (the in-container tmux survives).
+- **Container stop / host reboot** restarts the container and **resumes** the last conversation from the bind-mounted transcript. Claude sessions launch with a pinned conversation id (`--session-id <sessionId>`, with a `--resume` fallback when the transcript already exists), and the case remembers its last conversation (`lastClaudeSessionId`), so a relaunch after the container was stopped, rebooted, or recreated continues where it left off.
+- **Killing one session** only kills that session's in-container tmux session; the shared container stays up for sibling sessions.
+- **Editing the docker host config** (image, memory, network, ...) is detected on the next launch: the desired config hash is compared against the container's `codeman.confighash` label, and a mismatch refuses the launch with a "config changed, recreate?" confirm. Confirming calls `POST /api/docker-cases/:name/recreate` (refused while sessions of the case are live), which removes the container so the next launch recreates it with the new config; the workspace and the conversation survive.
+- **Deleting the case** `docker rm -f`s the container (the bind-mounted workspace on the host survives). An instance-scoped boot reaper removes containers whose case is gone.
+
+## Isolation & security
+
+Every container runs hardened: `--cap-drop ALL`, `--security-opt no-new-privileges`, non-root (`--user <hostUid>:0` so workspace files stay host-owned), `--pids-limit`, `--memory` == `--memory-swap`, `--init`. Never `--privileged`, never the docker socket. The default **convenient** profile bind-mounts host credential dirs read-write so the common login just works (creds stay on the host, never captured by `docker commit`); the **sealed** profile (`mountCredentials:false` + `network:none`) is the opt-in for genuinely untrusted work.
+
+Rootless engines without cgroup-v2 systemd delegation cannot enforce resource caps; linking such a host warns that caps are advisory.
+
+## Export / Import (move to another machine)
+
+**Export** (from the Docker tab, or `POST /api/docker-cases/:name/export`): choose
+
+- **Full image + workspace**: `docker commit` the container to an image, `docker save` it, tar the workspace, and a manifest, all into one portable `<case>-<ts>.codeman-container.tgz` (the whole toolchain, installed packages, and files). Runs in the background; you are notified when the bundle is ready.
+- **Workspace only**: just the project files (fast, small).
+
+The container is paused across the capture so the image and workspace are consistent; a full `/var/lib/docker` is guarded against with a free-space precheck; the intermediate image is always cleaned up.
+
+**Import** (`POST /api/docker-cases/import`, or the Manage tab): copy the `.tgz` onto the new machine's `~/.codeman/docker-exports/`, then import it into a new case. The manifest and per-member SHA-256 checksums are validated, the workspace tar is extracted with a path-traversal guard, and the image is `docker load`ed and **re-tagged into a quarantined namespace** (`codeman/imported-<case>:<ts>`) so it never overwrites a local tag. The destination supplies its own credentials, so nothing secret crosses machines.
+
+`GET /api/docker-exports` lists bundles; `GET /api/docker-exports/:filename` downloads one; `DELETE` removes one.
+
+## Hooks require the server to be reachable from the container
+
+In-container hooks (permission events, hook-based idle/stop/task notifications) POST to `CODEMAN_API_URL`, which is derived as `https://host.docker.internal:<port>` (`host.docker.internal` → the docker bridge gateway, e.g. `172.17.0.1`, via `--add-host …:host-gateway`). For that callback to succeed, the Codeman server must be **listening on an interface the container can reach**.
+
+- If Codeman binds **loopback-only** (`127.0.0.1`, the default and the production systemd config), a container reaching `172.17.0.1:<port>` cannot connect, so by default **in-container hooks do not fire**. The session still works fully: idle/stop detection falls back to **output-based** detection through the `docker exec` PTY (which always works), and claude runs with `--dangerously-skip-permissions` so there are no permission prompts to forward anyway.
+- **To enable in-container hooks on a loopback-only server, set `CODEMAN_DOCKER_BRIDGE_HOOKS=1`** (env). Codeman then starts a SECOND listener bound to the docker bridge gateway (`172.17.0.1`, auto-detected; override with `CODEMAN_DOCKER_BRIDGE_HOST`) that serves **only the hook endpoints** (`/api/hook-event`, `/api/status-telemetry`) and delegates them into the same secret-gated pipeline. The bridge is host-internal (containers + host, not the LAN), and every other path returns `403`, so this does not widen your network exposure. Add `Environment=CODEMAN_DOCKER_BRIDGE_HOOKS=1` to the systemd unit and restart.
+- Alternatively, bind `0.0.0.0` **with `CODEMAN_PASSWORD` set** (exposes on the LAN too).
+
+The host-gateway mapping, `CODEMAN_API_URL` derivation, host-guard allowlist, and hook-secret mount are all wired correctly; `CODEMAN_DOCKER_BRIDGE_HOOKS` closes the last gap for loopback-only servers.
+
+## Notes & limits
+
+- Requires Docker (or Podman) with a reachable daemon; tmux must be present in the base image (a hard prerequisite, probed at link time).
+- Per-session `envOverrides` / `effort` / per-CLI config are rejected for docker cases (they do not cross into the container); configure the container via the docker host's per-mode command override instead.
+- macOS Docker Desktop takes a dedicated uid path (the baked image uid; memory caps are subject to the VM ceiling).
+
+Design + rationale: [`docker-cases-plan.md`](./docker-cases-plan.md).

docs/multi-user-plan.md

@@ -0,0 +1,282 @@
+# Multi-User Mode: Design Plan
+
+Status: **IMPLEMENTED on `feat/multiuser-mode`** (phases 1-5; opt-in, off by default). Target: opt-in multi-user support behind a `--multiuser` flag, with per-user case spaces and an admin panel for user management.
+
+Shipped by phase:
+
+- **Phase 1** (user store + mode plumbing + CLI): `src/user-store.ts` (scrypt, atomic 0600 writes, last-admin invariants, serialized read-modify-write), `src/config/multiuser.ts`, `codeman users add|passwd|list|rm`, `--multiuser` flag, bootstrap-on-first-boot. Tests: `test/user-store.test.ts`.
+- **Phase 2** (multi-user auth): parallel async auth branch (`src/web/middleware/auth.ts`), `req.authUser`, per-username rate bucket, `mustChangePassword` lockbox, `GET /api/me` + `POST /api/me/password`, QR identity-bound minting, network-bind + tunnel exemptions, new error codes. Tests: `test/multiuser-auth.test.ts`.
+- **Phase 3** (ownership threading): `Session.owner` at every create path + recovery mirror; `findSessionOrFail` owner check + list filtering; §6.3 permission policy (`resolveClaudeModeForUser` at all spawn sites incl. one-shots via `buildPromptArgs`; shell/launchCommand grant); per-user case spaces (`resolveCasesDir`) + owner-scoped case list + admin-only host CRUD; `workingDir` confinement; `sessionCapacityState` per-user cap. Tests: `test/ownership-scoping.test.ts`.
+- **Phase 4** (event fan-out): WS owner gate; SSE per-client identity + `broadcast`/terminal-batch routing (`deriveSseHint`, fail-closed); `getLightState` per-identity filtering; file-route preview/thumbnail/history + `GET /api/search` scoping.
+- **Phase 5** (admin API + frontend): `src/web/routes/admin-routes.ts` (user CRUD, one-time passwords, last-admin guards, session revoke/kill) + `src/web/admin-audit.ts`; `public/admin-ui.js` (identity boot, change-password modal + interceptor, admin Users tab). Tests: `test/admin-routes.test.ts`, `test/admin-ui.test.ts`.
+
+Deferred follow-ups (documented, non-blocking): away-digest + subagent/workflow REST-list scoping, push-subscription identity/routing, per-user screenshot subdirs, `linked-cases.json` v2 owner field, `ScheduledRun.owner`, plan-orchestrator internal one-shot mode resolution, and a Playwright browser pass. Phase 6 (login form replacing Basic) remains out of scope.
+
+## 1. Summary
+
+Today Codeman is strictly single-user: one optional credential pair (`CODEMAN_USERNAME`/`CODEMAN_PASSWORD`), one shared `~/codeman-cases` folder, one global session list, and a global SSE/WS fan-out. This plan adds an opt-in **multi-user mode**:
+
+- **Off by default.** Without the flag, behavior stays byte-identical to today (same auth path, same paths, same payloads). All new code is gated behind `isMultiUserMode()`.
+- **`codeman web --multiuser`** (or `CODEMAN_MULTIUSER=1`) enables named users with individually hashed passwords stored in `~/.codeman/users.json`.
+- **Each user gets their own space**: `~/codeman-users/<username>/cases/<case>` replaces the shared `~/codeman-cases` for that user. Sessions, cases, attachments, search, digests, and SSE events are scoped to their owner.
+- **Admin panel** (App Settings, admin-only "Users" tab): create/delete users, change/reset passwords, enable/disable accounts, delete a user's space, see per-user live sessions and disk usage, force logout.
+
+## 2. Threat Model (read first, be honest about this)
+
+Multi-user mode is **workspace separation for a trusted team, NOT security isolation between mutually distrusting users**:
+
+- Every session still runs as the **same OS account** with `claude --dangerously-skip-permissions`. Any user can ask their agent to `cat /home/<host>/codeman-users/otheruser/...`. The web layer enforces scoping; the agent layer cannot.
+- **Shell sessions and custom launch commands are the bluntest holes**: `SessionMode = 'shell'` hands out a raw shell as the host account, and a cron job's `launchCommand` runs an arbitrary command; no Claude permission classifier is involved in either. These must be gated behind the same grant as bypass (section 6.3), otherwise the `auto`-mode mitigation below is theater.
+- All sessions share one tmux socket (`-L codeman`), one `~/.claude` (transcripts, credentials, plan usage), one Claude subscription.
+- Mitigation for stronger isolation: pair a user's cases with **Docker cases** (container per case, `docs/docker-cases.md`), or run separate Codeman instances per user (`CODEMAN_INSTANCE`, separate OS accounts). True per-user OS isolation is explicitly **out of scope** for this feature.
+- Partial mitigation at the agent layer: non-admin users default to Claude's `auto` permission mode (section 6.3), whose safety classifier blocks destructive actions and credential exfiltration. That reduces, but does not eliminate, cross-user snooping; the `canBypassPermissions` grant reopens it and should be given deliberately.
+
+This must be stated loudly in `docs/security-architecture.md`, the README section, and the admin panel UI ("Users share the host account; this separates workspaces, it does not sandbox users from each other").
+
+Also note the flip side: multi-user mode strictly _improves_ today's network posture, because it removes the single shared password and gives every person their own revocable credential.
+
+## 3. Activation and Mode Rules
+
+| Condition                                                     | Behavior                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No flag (default)                                             | Exactly today's behavior. `users.json` is never read. Single-user auth via `CODEMAN_PASSWORD` if set.                                                                                                                                                                      |
+| `--multiuser` / `CODEMAN_MULTIUSER=1`, `users.json` has users | Multi-user auth active. `CODEMAN_PASSWORD` is ignored for login (warn if set).                                                                                                                                                                                             |
+| `--multiuser`, no `users.json` (first boot)                   | Bootstrap: if `CODEMAN_USERNAME`/`CODEMAN_PASSWORD` are set, create that user as the initial admin and continue. Otherwise refuse to start with instructions to run `codeman users add <name> --admin`. Never start multi-user with zero users (there would be no way in). |
+| `--multiuser` on a non-loopback bind                          | Allowed without `CODEMAN_PASSWORD`: `server.ts start()` treats "multi-user with >= 1 enabled user" as satisfying the auth requirement in the loud-warning check (wire into the existing `isLoopbackBindHost()` branch).                                                    |
+| Flag later removed                                            | Single-user mode again. Sessions/state that carry `owner` fields keep working (owner is simply ignored); user spaces remain on disk untouched.                                                                                                                             |
+
+Plumbing: flag in `src/cli.ts` (web command), env in a new `src/config/multiuser.ts` exporting `isMultiUserMode()`. Per-instance like everything else: a beta instance (`CODEMAN_INSTANCE=beta`) has its own `users.json` via `dataPath()`.
+
+## 4. Data Model and Disk Layout
+
+### 4.1 `~/.codeman/users.json` (via `dataPath('users.json')`, mode 0600, atomic write: tmp + rename)
+
+```jsonc
+{
+  "version": 1,
+  "users": [
+    {
+      "username": "alice", // canonical lowercase slug
+      "role": "admin", // "admin" | "user"
+      "password": {
+        "algo": "scrypt", // node:crypto scrypt, no new deps
+        "N": 16384,
+        "r": 8,
+        "p": 1,
+        "salt": "<hex 32B>",
+        "hash": "<hex 64B>",
+      },
+      "disabled": false,
+      "mustChangePassword": false, // set by admin reset; gates all API access until changed
+      "canBypassPermissions": false, // permission-mode grant, see section 6.3; false for new users
+      "createdAt": 1752900000000,
+      "lastLoginAt": 1752900000000,
+    },
+  ],
+}
+```
+
+- **Username rules**: `^[a-z0-9][a-z0-9_-]{1,31}$` (it becomes a folder name), stored lowercase, unique case-insensitively. Reserve `admin`? No: any name can be admin; role is a field, not a name.
+- **Hashing**: `scrypt` from `node:crypto` with per-user salt, compared via `timingSafeEqual`. Params stored per record so they can be raised later; verify tolerates old params and rehashes on next successful login.
+- New module `src/user-store.ts` (mirrors the `remote-hosts.ts` / `docker-hosts.ts` pattern): `readUsers()`, `writeUsers()`, `verifyPassword()`, `createUser()`, `setPassword()`, `deleteUser()`, plus pure helpers (`isValidUsername`, `hashPassword`) that are unit-testable without IO. In-process cache with short TTL like `readSettings`, invalidated on every write; the short TTL also covers the CLI (section 10) editing `users.json` while the server runs (cross-process changes picked up within the TTL).
+
+### 4.2 User spaces
+
+```
+~/codeman-users/
+  alice/
+    cases/
+      my-project/          <- same layout as today's ~/codeman-cases/<case>
+  bob/
+    cases/
+```
+
+- New helper in `route-helpers.ts`:
+  `resolveCasesDir(user?: AuthUser): string`
+  single-user mode: returns `CASES_DIR` (today's `~/codeman-cases`); multi-user: returns `join(USER_SPACES_DIR, user.username, 'cases')`, creating it lazily on first use.
+- `CASES_DIR` stays exported for single-user code paths, but every route usage (see 6) switches to the resolver.
+- The **user folder** (`~/codeman-users/<username>/`) is the deletion unit for "delete user + space" and leaves room for future per-user extras (uploads, exports) beside `cases/`.
+- Legacy `~/codeman-cases` in multi-user mode: surfaces to admins only, as a read-only "Unassigned (legacy)" group in the case list, with an admin action `POST /api/admin/cases/assign { case, username }` that `fs.rename`s the folder into a user's space (same-filesystem move, cheap). No automatic migration.
+
+## 5. Auth Pipeline Changes (`src/web/middleware/auth.ts`)
+
+Keep the existing single-user branch untouched. Add a parallel multi-user branch selected once at registration time:
+
+1. **Credential check**: Basic header parsed into `username:password`, verified against the user store (scrypt + `timingSafeEqual`). Disabled users fail closed.
+2. **Cookie sessions**: same `codeman_session` cookie and `StaleExpirationMap`, but `AuthSessionRecord` gains `username` and `role`. All existing TTL/sliding/eviction logic reused. Eviction cap becomes per-user aware (evict oldest _of that user_ first) so one user cannot flush everyone's sessions by logging in 100 times.
+3. **Request identity**: decorate `req.authUser = { username, role }` (Fastify decorateRequest). In single-user mode `req.authUser` is `{ username: 'admin', role: 'admin' }` when auth is on, and a synthetic admin when auth is off, so downstream code has ONE code path.
+4. **Rate limiting**: keep the per-IP bucket; add a per-username failure bucket (same `StaleExpirationMap` pattern) so a botnet cannot brute-force one account across IPs, and one flaky user behind a NAT cannot lock out the rest.
+5. **`mustChangePassword` gate**: when set, every API request except `GET /api/me`, `POST /api/me/password`, and static assets returns 403 with `errorCode: 'PASSWORD_CHANGE_REQUIRED'`; the frontend intercepts that code and shows the change-password modal.
+6. **Password change vs Basic-auth caching**: browsers cache Basic credentials. After a password change we revoke all of that user's cookie sessions; the next request falls to Basic with stale creds, gets 401, and the browser re-prompts. Acceptable for v1; a proper login form is Phase 6 (see 15).
+7. **Unchanged**: hook-secret loopback bypass (hooks authenticate the _instance_, not a user; the event maps to a session which has an owner), host guard, Origin/CSRF guard, security headers.
+8. **WS upgrade identity** (`ws-routes.ts`): the global auth `onRequest` hook does run on the upgrade request (`@fastify/websocket` v11 runs hooks before the handshake; browsers send the session cookie), but the route handler itself only checks Host/Origin and never learns WHO authenticated. Multi-user: the handler reads the decorated `req.authUser` and closes 4003 unless owner or admin (section 6.4; identity plumbing lands in Phase 2, the owner check in Phase 4 once sessions have owners). Add a regression test that an upgrade with no credentials is rejected while auth is active: the handler-level Host/Origin gate alone must never be mistaken for auth.
+9. **QR auth** (`/q/:code` redemption in `system-routes.ts`, minting in `tunnel-manager.ts`): today there is ONE global token, auto-rotated every 60s with a 90s grace window. A globally-rotating token cannot carry an identity (every logged-in user sees the same code), so multi-user mode replaces rotation with **on-demand minting**: an authenticated `POST /api/tunnel/qr` mints a single-use, short-TTL token bound to `req.authUser.username` (field on `QrTokenRecord`); redemption creates a cookie session for that user. Existing rate-limit buckets (`qrAuthFailures`, global `QR_RATE_LIMIT_MAX`) apply unchanged. Single-user mode keeps the rotating token.
+
+New error codes in `src/types/api.ts`: `FORBIDDEN`, `PASSWORD_CHANGE_REQUIRED`, `USER_EXISTS`, `USER_NOT_FOUND`, `LAST_ADMIN`.
+
+Role guard helper in `route-helpers.ts`: `requireAdmin(req, reply): boolean` used as the first line of every admin handler (403 `FORBIDDEN`), plus `requireOwnerOrAdmin(req, session)`.
+
+## 6. Ownership Threading (the big refactor)
+
+### 6.1 Sessions
+
+- `Session` gains `owner?: string` (constructor option), persisted in `SessionState.owner`, included in `toState()`, round-tripped through recovery (`mux-sessions.json` entries carry it, `restoreMuxSessions` passes it back, exactly like `remote`/`docker`).
+- Every session-creating path stamps the owner from `req.authUser`. Verified inventory of `new Session(...)` call sites: `POST /api/sessions` (session-routes.ts:444), `POST /api/quick-start` (:1956), `POST /api/run` one-shot (:1652), Ralph start (ralph-routes.ts:327), **cron** (cron-service.ts:352; `CronJob` gains `owner`, stamped at job create, launched as the job's owner), legacy `ScheduledRun` loop (server.ts:1603), plan generation + plan-orchestrator agents (plan-routes.ts:128, plan-orchestrator.ts:422/578; owner = requesting user), and recovery (server.ts:2225, next bullet). Two non-paths, also verified: **respawn never constructs a new Session** (it re-spawns the PTY on the same object, so `owner` survives automatically; no inheritance logic needed), and **orchestrator-loop creates no sessions** (it schedules work onto existing idle sessions via the task queue; its scoping requirement is different: it must only pick idle sessions owned by the goal's creator).
+- Recovery: `owner` must ALSO be mirrored on `MuxSession` (mux-sessions.json) and read back mux-first like `remote`/`docker` (`muxSession.owner ?? savedState?.owner`, the server.ts:2246-2250 pattern), or a reboot erases ownership on the next persist.
+- Every session-reading/mutating route filters: non-admin users only see and act on `session.owner === req.authUser.username`. Centralize in `findSessionOrFail` (route-helpers.ts:87; the owner check there covers the 6 route files that use it: system/session/respawn/ralph/file/plan-routes) and in the list endpoints (`GET /api/sessions`, `GET /api/sessions/unified`, `GET /api/status`). The Phase 3 audit must grep for BOTH `sessionManager.getSession` AND direct map access (`ctx.sessions.get(` / `.has(`): ws-routes and hook-event-routes reach sessions that way and bypass `findSessionOrFail`.
+- Admins see everything; every session row carries `owner` so the UI can badge it.
+
+### 6.2 Cases
+
+- All `CASES_DIR` call sites switch to `resolveCasesDir(req.authUser)`: `case-routes.ts` (list/create/delete/CLAUDE.md scaffolding, name-collision checks, docker quickcreate), `session-routes.ts` (quick-start case resolution, the workingDir-inside-cases env-strip check), `ralph-routes.ts` (case path resolution), and `plan-routes.ts:231` (easy to miss). Case-name-to-path resolution is currently DUPLICATED (`resolveCasePath` in case-routes.ts:82 and an inline copy in quick-start, session-routes.ts:1846-1863); consolidate into one owner-aware resolver as part of this refactor instead of patching both copies.
+- Registries that map case names to metadata become owner-scoped. `remote-cases.json`/`docker-cases.json` are arrays of objects, so entries simply gain `owner?: string` (absent = legacy: admin-only). `linked-cases.json` is a flat `Record<caseName, path>` with no room for a field: it needs a v2 shape (`{ "version": 2, "cases": { "<name>": { "path": "...", "owner": "..." } } }`) with read-time migration of the v1 form; it is read in two places (case-routes AND inline in quick-start), both must move to the new reader. Case names only need to be unique per user.
+- **Remote hosts and Docker hosts are machine-level resources**: CRUD on `/api/docker-hosts` and remote-host endpoints becomes admin-only in multi-user mode; regular users can _use_ hosts on their own cases but not define them. (Docker containers exec as the host account; letting any user define arbitrary `docker run` args is admin-equivalent.)
+- Case deletion, exports (`docker-exports/`), and imports check ownership; export filenames get an owner prefix to avoid collisions (fits the existing `^[a-zA-Z0-9._-]+\.tgz$` download guard).
+- **Workspace confinement for non-admins (the linchpin, do not skip)**: today `POST /api/sessions` accepts ANY host directory as `workingDir` (the only check is `statSync().isDirectory()`, session-routes.ts:305-318), and file-routes/attachments confine reads to `session.workingDir`. Without a new rule the whole scoping story is circular: a user points a session at `~/codeman-users/bob` (or `/home`) and the web layer itself serves that subtree, no agent needed. Rule: in multi-user mode a non-admin's `workingDir` must realpath-resolve inside their own space, enforced at `POST /api/sessions`, `POST /api/run`, cron job create AND fire time (the dir can change owners between the two), and Ralph auto-configure. Admins are unrestricted. This one rule is what makes the section 6.4 file-route line ("own space or own sessions' workingDirs") meaningful.
+
+### 6.3 Per-user Claude permission-mode policy
+
+Codeman now ships a global **Startup Mode** picker (App Settings, Claude CLI tab: `settings.claudeMode`, values `dangerously-skip-permissions` (default) | `auto` | `normal` | `allowedTools`; `auto` emits `--permission-mode auto`, Anthropic's classifier-guarded low-prompt mode). Multi-user mode layers a per-user policy on top of it:
+
+- **Default for regular users: `auto` only.** A non-admin's Claude sessions are forced to `--permission-mode auto` regardless of the global `claudeMode` setting. `normal` and `allowedTools` are also permitted (they are strictly more restrictive than auto), but `dangerously-skip-permissions` is NOT.
+- **Bypass is an explicit admin grant**: `canBypassPermissions: true` on the user record (default `false`, section 4.1). Only with that grant does the global skip-permissions default (or a future per-user choice) apply to their sessions.
+- **Admins** are unrestricted; the global setting applies to them as-is.
+- **Single enforcement point**: a pure `resolveClaudeModeForUser(globalMode, user)` in `user-store.ts`, applied server-side at option-resolution time, BEFORE the Session constructor, so both downstream arg builders inherit it for free (`buildPermissionArgs` in session-cli-builder.ts for the direct-PTY path AND `buildClaudePermissionFlags` in tmux-manager.ts for tmux panes; there are two builders, not one). Call sites where `getClaudeModeConfig()` feeds a spawn: session-routes.ts:452/1964, ralph-routes.ts:334, cron-service.ts:360, and recovery (server.ts:2214/2233). Recovery re-reads the GLOBAL setting on reboot, so the resolver must run there with the RECOVERED owner, or a restart silently un-downgrades every restored session. Never resolved in the frontend, so it cannot be bypassed via payload.
+- **Downgrade, don't error**: a non-granted user whose effective mode would be bypass gets `auto` silently (logged + surfaced as a badge on the session), so shared presets keep working.
+- **Other CLIs' bypass equivalents** follow the same grant: Codex `--dangerously-bypass-approvals-and-sandbox` (`codexDangerouslyBypassApprovals`) and Gemini `--approval-mode yolo` are refused for non-granted users (Gemini falls back to `auto_edit`, Codex to its default sandbox). Whether this stays one grant or splits per-CLI is an open question (section 15).
+- **Shell mode and custom launch commands follow the grant too**: `mode: 'shell'` sessions and cron `launchCommand` are arbitrary command execution as the host account, strictly stronger than any bypass flag, and no permission-mode downgrade applies to them. Non-granted users get 403 `FORBIDDEN` on shell session/quick-start creation and on cron jobs carrying `launchCommand` (checked at create AND at fire time). Folding them under `canBypassPermissions` keeps the model one-bit; section 15 asks whether it should split.
+- **Admin UI**: a "Can skip permissions" toggle per user in the Users tab (PATCH field, section 8), with a warning echoing the section 2 threat model.
+- Revoking the grant takes effect on the user's NEXT session start; live sessions are listed so the admin can restart them.
+
+### 6.4 Everything else that lists or streams
+
+| Surface                                                                    | Scoping rule                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SSE `/api/events`                                                          | Per-connection filter (see 7)                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| WS terminal (`ws-routes.ts`)                                               | Handler reads `req.authUser` (section 5.8) and closes 4003 unless owner or admin; today it checks Host/Origin only and has no identity                                                                                                                                                                                                                                                                                                                    |
+| `GET /api/search`                                                          | `harvestSources()` only over owned sessions                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `GET /api/away-digest`                                                     | Aggregate only owned sessions/events                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `GET /api/subagents`, workflow runs                                        | Filter by owning session (`claudeSessionId -> session -> owner`); agents not attributable to any session: admin-only                                                                                                                                                                                                                                                                                                                                      |
+| Push (`push-routes.ts`)                                                    | Subscription records currently carry NO identity (keyed by endpoint only): `subscribe` stamps `username`. All 8 `PUSH_EVENT_MAP` events are session-scoped, so routing = resolve owner from `data.sessionId`, deliver to that owner's (plus admins') subscriptions. Legacy identity-less subscriptions: admin-only delivery                                                                                                                               |
+| Screenshots `/api/screenshots`                                             | Per-user subdir `~/.codeman/screenshots/<username>/` in multi-user mode. Note: `GET /:name` deliberately rejects `/` in names as traversal, so derive the subdir server-side from `req.authUser` and keep client-visible names flat                                                                                                                                                                                                                       |
+| Attachments                                                                | Already session-scoped; inherits the session owner check. `attachmentConfineToWorkspace` is a global, default-OFF setting today: in multi-user mode it is FORCED ON for non-admins regardless of the setting (their attachments must resolve inside their own space); the setting keeps meaning what it means for admins                                                                                                                                  |
+| File routes (browse/preview)                                               | Path allowlist adds: non-admin paths must resolve (realpath) inside their own space or their own sessions' workingDirs                                                                                                                                                                                                                                                                                                                                    |
+| Settings (`settings.json`)                                                 | Global, admin-only writes in multi-user mode; reads allowed (per-device display keys stay in localStorage as today). Per-user server settings: out of scope v1                                                                                                                                                                                                                                                                                            |
+| System ops (self-update, tunnel toggle, span-displays, docker image build) | Admin-only                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `getLightState` init snapshot                                              | Filtered per connection. Actual contents to filter (verified): `sessions`, `scheduledRuns`, `respawnStatus`, `subagents`, `workflowRuns`, `planUsage` (host-plan telemetry: admin-only); `globalStats` stays coarse-global. Cron jobs are NOT in the snapshot (they have their own REST route; filter there). The snapshot is cached process-wide (`LIGHT_STATE_CACHE_TTL_MS`): either key the cache per role/user or filter AFTER the cache on each send |
+
+## 7. SSE Event Filtering
+
+`/api/events` currently broadcasts everything to everyone. Ground truth first (verified): `broadcast()` lives in `SseStreamManager` (`sse-stream-manager.ts`), not server.ts; clients are keyed by the raw Fastify reply (`sseClients: Map<FastifyReply, Set<string> | null>`, plus `sseClientsById` for live filter updates); the existing `?sessions=` filter is a bandwidth optimization applied ONLY to `session:terminal` batches in `flushSessionTerminalBatch()`, while `broadcast()` itself loops ALL clients unconditionally. The single-client delivery primitive already exists (`sendSSE`, used for the per-connection init snapshot). Plan:
+
+- At connection time, resolve `req.authUser` and store `{ username, role }` with the client. Concretely: extend `addClient(reply, sessionFilter, isRemote, clientId)` to take the identity and change the `sseClients` map value to `{ filter, identity }` (or add a parallel `Map<reply, identity>`); there is no per-client record object today to hang it on.
+- `broadcast()` gains an optional routing hint: `broadcast(event, data, { sessionId?, adminOnly?, username? })`. Resolution order per client: admin sees all; `username` targets one user; `sessionId` resolves owner via SessionManager; `adminOnly` for machine-level events (docker image builds, tunnel, self-update); no hint = broadcast to all (connection status etc.).
+- **Enforce the identity check in BOTH `broadcast()` AND `flushSessionTerminalBatch()`**: the terminal batch path does not go through `broadcast()`, and it carries the highest-value payload (raw terminal bytes).
+- Sweep of the ~120 backend event constants in `sse-events.ts`: mechanically, everything `session:*`, `ralph:*`, `respawn:*`, `subagent:*`, `workflow:*`, `attachment:*`, `cron:*` (job owner) carries or can resolve a sessionId/owner; `docker:*`, `system:*`, tunnel and update events are adminOnly; a short tail needs case-by-case decisions during implementation.
+- The existing `?sessions=` filter and `/api/events/subscribe` compose with (never override) the ownership filter: the subscription filter can only narrow within what the identity allows.
+
+## 8. Admin API (`src/web/routes/admin-routes.ts`, new module + `AdminPort`)
+
+All handlers: multi-user mode only (404 otherwise), `requireAdmin`, Zod schemas in `schemas.ts`, `ApiResponse` envelope, audit-logged.
+
+| Endpoint                                         | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /api/admin/users`                           | List users + stats: role, disabled, createdAt, lastLoginAt, live session count, case count, space disk usage (best-effort async walk, cached 60s), active cookie-session count                                                                                                                                                                                                                                          |
+| `POST /api/admin/users`                          | Create: `{ username, role, password? }`. No password given: generate a one-time password, return it ONCE in the response, set `mustChangePassword`                                                                                                                                                                                                                                                                      |
+| `PATCH /api/admin/users/:username`               | `{ role?, disabled?, canBypassPermissions? }`. Demoting/disabling the last enabled admin: 409 `LAST_ADMIN`. Disable also revokes cookie sessions. `canBypassPermissions` is the section 6.3 grant (default false)                                                                                                                                                                                                       |
+| `POST /api/admin/users/:username/reset-password` | Generates one-time password (returned once), sets `mustChangePassword`, revokes cookie sessions                                                                                                                                                                                                                                                                                                                         |
+| `POST /api/admin/users/:username/logout`         | Revoke all cookie sessions for that user. Honest limit under Basic auth: the browser silently re-sends cached credentials and gets a fresh cookie on the next request, so logout only truly ends QR-issued sessions; to actually lock someone out, disable the account or reset the password. Say so in the panel tooltip until Phase 6                                                                                 |
+| `DELETE /api/admin/users/:username`              | `{ deleteSpace?: boolean }` (default false). Refuses last admin. Kills the user's live sessions first (normal kill flow, incl. docker/remote teardown per case), revokes cookies, removes from store. With `deleteSpace`: guarded recursive delete of `~/codeman-users/<username>` (realpath must be inside `USER_SPACES_DIR`, top-level dir must not be a symlink), plus their registry entries and push subscriptions |
+| `POST /api/admin/cases/assign`                   | Move a legacy `~/codeman-cases/<case>` into a user's space (`fs.rename`)                                                                                                                                                                                                                                                                                                                                                |
+| Self-service `GET /api/me`                       | `{ username, role, mustChangePassword }` (works in single-user mode too: synthetic admin; the frontend uses it to decide whether to render admin UI)                                                                                                                                                                                                                                                                    |
+| Self-service `POST /api/me/password`             | `{ currentPassword, newPassword }`, verifies current, min length 8, revokes other sessions, clears `mustChangePassword`                                                                                                                                                                                                                                                                                                 |
+
+**Audit log**: append-only `~/.codeman/admin-audit.jsonl` (same idiom as `session-lifecycle.jsonl`): timestamp, acting admin, action, target, request IP. User management without an audit trail is not acceptable even for a homelab tool.
+
+SSE additions (both `sse-events.ts` and `constants.js`): `admin:usersChanged` (adminOnly; the panel re-fetches) and `auth:passwordChangeRequired` (targeted to the user).
+
+## 9. Frontend
+
+- **`GET /api/me` on boot** (app.js init): stores `window.__codemanUser`; everything below keys off it. Single-user mode returns the synthetic admin, so the UI needs no mode awareness beyond "am I admin".
+- **Admin panel**: new tab "Users" in the App Settings modal (settings-ui.js), rendered only for admins in multi-user mode. Table of users with actions (create, reset password showing the one-time password in a copy-to-clipboard reveal, enable/disable, role toggle, logout, delete with a typed-username confirm for the delete-space variant). No new header button (mobile header policy test stays green; the settings modal is already reachable everywhere).
+- **Change-password modal**: shown on `PASSWORD_CHANGE_REQUIRED` (fetch interceptor in api-client.js) and reachable from settings for self-service.
+- **Owner badges**: admin's session tabs and the session palette/manager show `owner` on foreign sessions; regular users see no change.
+- New module `admin-ui.js` if the settings-ui.js addition gets large (load order after settings-ui, before session-ui), else keep inside settings-ui.js. Follow the `@fileoverview` + `@loadorder` convention either way.
+
+## 10. CLI Additions (`src/cli.ts`)
+
+Headless bootstrap and recovery must not require the web UI:
+
+```
+codeman users add <name> [--admin]     # prompts for password (hidden input), or --password-stdin
+codeman users passwd <name>            # reset password
+codeman users list
+codeman users rm <name> [--delete-space]
+```
+
+These operate directly on `users.json` via `user-store.ts` (no server needed), honoring `CODEMAN_INSTANCE`. This is also the answer to "locked out: last admin forgot password".
+
+## 11. Limits and Config
+
+- New `src/config/multiuser.ts`: `isMultiUserMode()`, `USER_SPACES_DIR` (`~/codeman-users`, overridable via `CODEMAN_USER_SPACES_DIR` for tests), `MAX_USERS` (default 25), per-user session cap (default: global cap / 2, env `CODEMAN_MAX_SESSIONS_PER_USER`).
+- Cap enforcement is currently COPY-PASTED: the global `MAX_CONCURRENT_SESSIONS` (50, `config/map-limits.ts:25`) check appears at 6 independent sites (session-routes.ts:298/1622/1683, ralph-routes.ts:275, cron-service.ts:340, server.ts:1595). Do not add a 7th copy per site: extract one `assertSessionCapacity(ctx, owner?)` helper doing the global + per-user checks and use it everywhere, or the per-user cap WILL miss a path.
+- Global limits (50 sessions, SSE clients 100, terminal buffers) are unchanged and shared; the per-user session cap is the fairness lever.
+
+## 12. Compatibility Matrix
+
+| Concern            | Guarantee                                                                                                                                                                                                   |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default (no flag)  | No behavior change. No new file reads on the hot path. All new fields optional in state                                                                                                                     |
+| State round-trip   | `SessionState.owner`, `MuxSession.owner`, `CronJob.owner`, registry `owner` fields are optional; old state loads clean; new state loaded by an old build ignores unknown fields (existing tolerant parsing) |
+| Instance isolation | `users.json`, audit log, screenshots subdirs all via `dataPath()`; user spaces dir is shared across instances like `~/codeman-cases` is today (documented)                                                  |
+| API versioning     | HTTP API is internal per `docs/versioning-policy.md`; still, all changes are additive. Ship as a **minor** version                                                                                          |
+| Hooks              | Unchanged (instance-level hook secret; owner resolved from the session)                                                                                                                                     |
+
+## 13. Implementation Phases
+
+Each phase is independently shippable behind the flag and ends with its tests green.
+
+**Phase 1: user store + mode plumbing** (no behavior change yet)
+`src/user-store.ts`, `src/config/multiuser.ts`, CLI `users` subcommands, bootstrap-on-first-boot logic, `users.json` schema + atomic writes.
+Tests: `test/user-store.test.ts` (hashing, verify, params upgrade, username validation, atomic write, last-admin invariants; pure, no server).
+
+**Phase 2: multi-user auth**
+Auth middleware branch, `req.authUser` decoration, cookie records with username/role, per-username rate bucket, `mustChangePassword` gate, WS upgrade identity plumbing + unauthenticated-upgrade regression test (section 5.8), QR on-demand minting + identity binding (section 5.9), `GET /api/me`, `POST /api/me/password`, error codes, network-bind check integration.
+Tests: `test/multiuser-auth.test.ts` (live server, unique port 3170+; wrong password, disabled user, cookie carries identity, per-user rate limit isolation, mustChangePassword lockbox, QR redemption identity). Reuse the `delete process.env.CODEMAN_PASSWORD` idiom from `test/setup.ts`.
+
+**Phase 3: ownership threading**
+Session `owner` + persistence + `MuxSession` mirror + recovery; `resolveCasesDir()` refactor across case/session/ralph/plan routes (consolidating the duplicated case-path resolution); registry owner fields incl. the linked-cases v2 shape; `findSessionOrFail` owner check + the direct-`sessions.get` audit; list filtering; owner stamping across ALL create paths from 6.1; **non-admin workingDir confinement** (6.2); permission-mode/shell/launchCommand policy (6.3); `assertSessionCapacity` helper + per-user cap.
+Tests: `test/routes/ownership-scoping.test.ts` (inject-based: user A cannot read/kill/input user B's session, case lists are disjoint, admin sees both), extend `test/cron-service.test.ts` for owner stamping, recovery round-trip in the existing mux-recovery tests.
+
+**Phase 4: event fan-out + remaining surfaces**
+SSE routing hints + client identity (enforced in BOTH `broadcast()` and the terminal-batch flush), WS owner gate (identity landed in Phase 2), search/digest/subagent/workflow scoping, push subscription identity + owner routing, screenshot subdirs, file-route scoping, `getLightState` filtering + per-identity caching, admin-only system ops.
+Tests: `test/sse-ownership.test.ts` (two SSE clients, event for A's session reaches only A + admin), WS upgrade rejection test, search/digest scoping tests.
+
+**Phase 5: admin API + frontend**
+`admin-routes.ts` + `AdminPort` + schemas + audit log + `admin:usersChanged`; settings-ui Users tab, change-password modal, owner badges, api-client interceptor.
+Tests: `test/routes/admin-routes.test.ts` (CRUD, last-admin 409, one-time password flow, delete-space guard rails incl. symlink refusal), frontend vm-sandbox test following `test/run-mode-ui.test.ts` pattern, Playwright pass per the always-end-to-end rule before calling it done.
+
+**Phase 6 (optional, later): login page**
+Replace Basic with a form + `POST /api/login` in multi-user mode only (fixes browser credential caching UX, enables logout button). Explicitly deferred; Basic works for v1.
+
+**Docs**: update `docs/security-architecture.md` (new section: multi-user model + threat model from section 2), `README.md` (short opt-in section), `CLAUDE.md` (Key Patterns entry + State Files + route/SSE counts), this file gets a "shipped" status stamp per phase.
+
+## 14. Key Risks / Decisions Made
+
+1. **Not a security boundary at the agent layer** (section 2). Decided: ship with loud documentation; Docker cases are the isolation story.
+2. **`findSessionOrFail` as the single enforcement point** for ~30 session routes: any route that fetches sessions another way must be audited in Phase 3 (grep for `sessionManager.getSession` outside route-helpers).
+3. **SSE sweep is the riskiest surface**: a missed event leaks metadata (not terminal content, which is session-scoped, but names/paths). Phase 4 includes a checklist pass over all ~138 events with the default flipped to "owner-scoped unless explicitly global": fail closed.
+4. **Basic-auth password-change UX** is mediocre (browser re-prompt). Accepted for v1; Phase 6 fixes it properly.
+5. **Legacy case migration** is manual (admin assigns). No silent moves of user data.
+6. **Case-name uniqueness becomes per-user**; tmux session names already include the session id so no collision, but the `w<n>-<case>` tab naming and lifecycle-log rows should include the owner for disambiguation in admin views.
+7. **`workingDir` confinement (6.2) is the single most load-bearing rule**: every file-serving and agent-spawning surface downstream trusts `session.workingDir`. Review and test it as carefully as the auth branch (foreign-space path, symlink into a foreign space, `..` traversal, cron fire-time re-check).
+8. **The WS handler never sees identity today** (auth happens only in the global hook): the 5.8 wiring is new code on a security-sensitive path; cover unauthenticated, foreign-user, and admin upgrades with tests.
+
+## 15. Open Questions (answer before Phase 3)
+
+1. Should admins' own cases live in `~/codeman-users/<admin>/cases` (symmetric, proposed) or keep using legacy `~/codeman-cases`? Proposed: symmetric; legacy dir is a migration source only.
+2. Per-user settings (respawn presets, notification prefs): global-only in v1. Worth a `users/<name>/settings.json` overlay later?
+3. Should regular users be allowed to create Docker cases on admin-defined hosts (proposed: yes) or is Docker entirely admin-only?
+4. Session handoff: does an admin need "reassign session/case to another user"? (Cheap to add next to `cases/assign`; not in v1 scope.)
+5. Permission-mode grants (section 6.3): one `canBypassPermissions` flag covering Claude/Codex/Gemini bypass equivalents PLUS shell mode and cron `launchCommand` (proposed: one flag, keep it one-bit), or split into `canBypassPermissions` + `canRunArbitraryCommands`? And should admins be able to set a per-user DEFAULT mode (for example force `normal` for an intern) rather than just gating bypass?
+6. OpenCode has no single bypass flag (its permission config rides `OPENCODE_CONFIG_CONTENT`): decide what the grant means there before Phase 3, or exclude OpenCode mode for non-granted users in v1.

docs/reliable-input-delivery.md

@@ -0,0 +1,72 @@
+# Reliable input delivery (exactly-once, durable)
+
+## The bug this fixes
+
+With local echo on, pressing Enter cleared the overlay and then sent the prompt
+over the WebSocket **fire-and-forget** (`ws.send({t:'i',d})`). On a flaky link
+(e.g. a moving train) the socket is frequently *half-open*: `readyState === OPEN`
+so `ws.send()` does **not** throw, but the underlying TCP is dead, so the frame is
+silently discarded. Nothing was enqueued (the send "succeeded"), the on-screen
+prompt was already wiped, and `navigator.onLine` stays `true` — so a long typed
+prompt vanished with no trace and no resend.
+
+## The guarantee
+
+Every byte of user input is **recorded durably before delivery** and **only
+dropped once the server ACKs it** — so a half-open socket, a reconnect, or a page
+reload can never lose input. Redelivery is **exactly-once**: the server applies
+each `(clientId, seq)` at most once, so a resend can't type the prompt twice.
+
+## How it works
+
+### Client (`app.js`)
+
+- A stable **`clientId`** (`localStorage['codeman:clientId']`) identifies this
+  browser to the server's dedup across reconnects and reloads.
+- Each input frame gets a **monotonic per-session `seq`**. Frame records
+  (`{seq,data,useMux,ts,tries,sentAt}`) live in `_pendingDeliveries`
+  (`Map<sessionId, record[]>`), persisted (debounced, + flushed on `pagehide`/
+  `visibilitychange`) to `localStorage['codeman:pendingInput']`. The seq counters
+  persist too, so seqs stay monotonic across reloads (never reset — a reset would
+  let the server treat fresh input as an already-applied duplicate).
+- **Delivery** (`_drainSession`):
+  - **WS path** — when the socket is `OPEN` for the session, send each not-yet-sent
+    record (`sentAt === 0`) in seq order over the single ordered stream. Records
+    stay pending until the server's `{t:'ia',seq}` ACK removes them.
+  - **POST path** — when no WS, POST records in order, awaiting each (the HTTP 2xx
+    *is* the ACK). A 404/410 (session gone) drops the record rather than retry
+    forever.
+- **Half-open recovery** (`_redeliverSweep`, every 2s): if the active WS session's
+  oldest record is unacked past `_reliableAckTimeoutMs` (4s), the socket is assumed
+  dead — `ws.close()` forces a fast reconnect; `onopen` (`_onWsReady`) resets
+  `sentAt = 0` and re-sends everything pending. Also re-drains background sessions
+  over POST, and fires on SSE-reconnect / `online`.
+- The connection indicator shows pending count/bytes (`_pendingBytes`).
+
+### Server
+
+- **`Session.shouldApplyInput(clientId, seq)`** — returns `true` exactly once per
+  `(clientId, seq)`: the first time a seq strictly greater than that client's
+  last-applied is seen. A replayed/lower seq returns `false`. Bounded MRU map
+  (`MAX_INPUT_DEDUP_CLIENTS = 256`).
+- **WS route** (`ws-routes.ts`) — parses optional `cid`/`seq` on `{t:'i'}`; applies
+  via `shouldApplyInput` (skips a duplicate, still ACKs with `{t:'ia',seq}` so the
+  client drops it). Untagged frames apply unconditionally (no behavior change).
+- **POST route** (`/api/sessions/:id/input`) — optional `seq`/`clientId` in
+  `SessionInputWithLimitSchema`; a deduped duplicate returns 200 without writing
+  (the 200 is the client's ACK). `curl`/legacy callers omit the fields and always
+  apply.
+
+## Known limitation
+
+Dedup state is in-memory on the server. A **server restart** between a write and
+the client's redelivery of that same seq could re-apply it (a rare duplicate).
+This is a deliberate trade-off: favor *never losing input* over a rare duplicate
+across the narrow restart window.
+
+## Tests
+
+- `test/reliable-input-dedup.test.ts` — `Session.shouldApplyInput` exactly-once
+  semantics (monotonic, per-client, gap-tolerant, eviction-safe).
+- `test/routes/session-routes.test.ts` — POST `/input` applies a tagged
+  `(clientId, seq)` once on redelivery; untagged input always applies.

docs/remote-sessions.md

@@ -0,0 +1,246 @@
+# Remote Sessions (SSH)
+
+Codeman can run a session's agent on a **remote host over SSH** instead of the
+local machine. The agent (Claude, OpenCode, Codex, Gemini, or a plain shell)
+runs inside a `tmux` server **on the remote host**, so it survives the SSH
+connection dropping; Codeman attaches to it the same way it attaches to a local
+managed session.
+
+This document covers the data model, the shell-safe SSH command construction
+(COD-107), the durable-launch design (COD-104), and the operational caveats.
+For the local session/mux machinery this builds on, see the **Mux** and
+**Session** entries in `CLAUDE.md` → Architecture.
+
+## Why it exists
+
+A developer box (`AA-DESKTOP`) often needs to drive an agent on another machine —
+a NAS, a build server, a host reachable only through a jump box or a
+cloudflared SOCKS5 proxy. Rather than wrap `ssh` by hand per host, Codeman
+stores reusable **remote hosts** + **remote cases** and reproduces the exact
+connection the operator already uses (`ssh-aa-desktop`-style configs:
+custom port, identity file, `-J` jump host, `-o ProxyCommand`).
+
+## Data model
+
+Types live in `src/types/session.ts`; persistence in `src/remote-hosts.ts`.
+
+| Type | Role |
+|------|------|
+| `RemoteSshOptions` | The **HOW-to-reach** fields, shared by host + session: `identityFile`, `socksProxy` (`host:port`), `jumpHost` (`[user@]host[:port]`), `extraSshOptions` (`KEY=VALUE[]`). Every field optional — all-absent reproduces port-22, default-identity, directly-SSH-able behavior. |
+| `RemoteHost` (extends `RemoteSshOptions`) | A saved host: `id`, `label`, `host`, `username`, `port?`, `commands?` (per-mode launch command override). |
+| `RemoteCase` | A working directory on a host: `name`, `type: 'remote'`, `hostId`, `remotePath`. |
+| `SessionRemote` (extends `RemoteSshOptions`) | The resolved bundle stamped onto a live session: host coordinates + `remotePath` + `commands`, plus **`owned?`** and **`remoteSessionName?`** (COD-105 — see [Ownership](#ownership-launched-vs-discovered-and-attached-cod-105)). Built by `toSessionRemote(host, case)` (sets `owned: true`) for the launch path, or `toAttachedSessionRemote(host, name, path)` (sets `owned: false`) for the attach path. Both copy the advanced SSH options through so every connection is identical. |
+| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini'>` — the modes that can run remotely. |
+| `RemoteSessionInfo` (COD-105) | One discovered remote tmux session: `name` (always `codeman-*`), `attached` (a client is connected), `created` (epoch s), `windows`. Returned by `listRemoteCodemanSessions()`. |
+
+Persistence is two flat JSON arrays in the instance data dir:
+
+- `~/.codeman/remote-hosts.json` — `readRemoteHosts()` / `writeRemoteHosts()`
+- `~/.codeman/remote-cases.json` — `readRemoteCases()` / `writeRemoteCases()`
+
+(Paths via `remoteHostsPath()` / `remoteCasesPath()`; both honor `CODEMAN_INSTANCE`
+because the config dir is the instance data dir.)
+
+On the live `Session`, the remote rides as `_remote?: SessionRemote`. When
+attaching, `resolveMuxAttachCwd()` forces the cwd to `/tmp` for remote sessions —
+the local working directory is meaningless on the remote box.
+
+## SSH command construction (COD-107 — the injection surface)
+
+**All** SSH command lines flow through one function so user-controlled fields are
+escaped once and the launch + prereq probe can never drift apart:
+
+```ts
+// src/remote-hosts.ts
+buildSshConnectionArgs(remote: RemoteSshOptions & Pick<RemoteHost, 'port'>): string[]
+```
+
+It returns the **ordered leading tokens** of an ssh command line (no `-t`, no
+target, no remote command):
+
+```
+ssh -o BatchMode=yes
+    [-p <port>]
+    [-i <abs-identity>]            # ~ / $HOME expanded, then shellescaped
+    [-J <jumpHost>]                # shellescaped, single token
+    [-o ProxyCommand=nc -X 5 -x <socks> %h %p]   # ONE shellescaped -o token
+    [-o <KEY=VALUE>] …             # each extra option, shellescaped
+```
+
+Rules that keep this safe — **do not bypass them by hand-building an ssh line elsewhere:**
+
+- **Every** user-controlled value (`-i`, `-J`, `-o`, ProxyCommand) is POSIX
+  single-quote `shellescape`d (`'…'` with embedded `'\''`). The helper mirrors
+  the one in `tmux-manager.ts`.
+- **`~`/`$HOME` in `identityFile` is expanded at build time** (`expandIdentityPath`),
+  *before* escaping — ssh does not expand `~` inside `-i`, and the escaped value
+  never reaches a shell that would.
+- **The ProxyCommand is one shellescaped `-o KEY=VALUE` token**, so its spaces and
+  the `%h`/`%p` placeholders reach ssh as a single argument. `%h %p` survive
+  verbatim — **ssh** expands them to the real host/port, not the shell.
+- **Empty options ⇒ `['ssh', '-o BatchMode=yes']`** (+ `-p` only when set) —
+  byte-identical to the historical behavior.
+
+Token construction is unit-tested independently of any live connection (see
+`test/` for `buildSshConnectionArgs` / `buildRemoteTmuxCheckCommand` cases).
+
+## Durable launch (COD-104)
+
+`buildRemoteLaunchCommand({ mode, remote, sessionId })` in `tmux-manager.ts`
+builds the command that launches (or **reattaches** to) the remote session:
+
+```
+ssh -o BatchMode=yes -t <connection-args> user@host \
+  'tmux -L codeman-remote new-session -A -s codeman-ssh-<id8> -c <remotePath> "cd <remotePath> && exec <cli>" \; \
+     set -t codeman-ssh-<id8> status off \; set -t codeman-ssh-<id8> mouse off \; \
+     set -t codeman-ssh-<id8> prefix C-q \; set -s escape-time 0 \; \
+     set -t codeman-ssh-<id8> window-size latest'
+```
+
+Key points:
+
+- **`new-session -A -s codeman-ssh-<id8>`** = attach-if-exists-else-create, so a
+  reconnect (same deterministic `remoteTmuxSessionName(sessionId)` — `codeman-ssh-` +
+  the first 8 chars of the session id) lands back in
+  the **same** remote session rather than spawning a duplicate. This is what makes
+  the remote agent survive an SSH drop. The name deliberately fails
+  `SAFE_MUX_NAME_PATTERN` so a Codeman running ON the remote host never adopts it.
+- **`-L codeman-remote`** = a DEDICATED socket for sessions launched by remote
+  Codemans, NOT the canonical `-L codeman` socket the remote host's own Codeman
+  uses. Options are set per-session (`set -t`), never `-g`, so a shared remote
+  tmux server's other sessions are untouched (#145 hardening). Note the
+  asymmetry: **discovery/attach (COD-105) target the canonical `-L codeman`
+  socket** — they join sessions the remote's own Codeman manages, while owned
+  durable launches live on `-L codeman-remote`.
+- **`exec <cli>`** replaces the pane shell with the agent, so the pane PID *is*
+  the agent. The per-mode command comes from `remote.commands?.[mode]` or
+  `defaultRemoteCommandForMode(mode)` (`exec claude` / `exec opencode` /
+  `exec codex` / `exec gemini` / `exec bash -l`).
+- The **whole tmux invocation is a single shell-quoted ssh argument**, and the
+  pane command is independently quoted, so a `remotePath` with spaces is safe.
+- Connection options come from the **same `buildSshConnectionArgs(remote)`** as
+  the prereq probe; `-t` is inserted right after `ssh -o BatchMode=yes`,
+  preserving historical token order.
+
+### tmux prerequisite probe
+
+Because durable remote sessions require tmux on the remote host,
+`checkRemoteTmuxAvailable(host)` runs `command -v tmux` over SSH **before**
+creating a remote case/session and returns a structured, never-throwing result:
+
+- empty stdout / non-zero exit → *"remote host `<host>` needs tmux installed for
+  durable remote sessions"*
+- stderr present → *"could not verify tmux on remote host `<host>`: `<stderr>`"*
+  (a real connection failure, surfaced to the operator)
+- success → `{ ok: true, tmuxPath }`
+
+It connects with the **identical** options as the launch
+(`buildRemoteTmuxCheckCommand` reuses `buildSshConnectionArgs` and inserts
+`-o ConnectTimeout=10`), so a proxied/custom-port/identity host that the launch
+can reach also passes the probe (and vice-versa).
+
+**Test-mode short-circuit:** under `VITEST` the probe returns
+`{ ok: true, tmuxPath: '(test-mode)' }` without opening a socket — mirroring
+`TmuxManager`'s no-op-shell-under-VITEST (`IS_TEST_MODE`). Without it, remote-case
+create-path tests would hit a real ~10s ssh timeout. Only the live probe is
+skipped; command construction is still asserted by unit tests.
+
+## Ownership: launched vs. discovered-and-attached (COD-105)
+
+COD-104 (above) was Phase 1 — Codeman *launches* a remote session and owns it.
+COD-105 is Phase 2 — Codeman can also **discover** `codeman-*` tmux sessions
+already running on a remote host (created by the remote's own Codeman or another
+instance) and **attach** to one it didn't launch. Ownership decides what happens
+when the tab closes.
+
+`SessionRemote.owned` carries this:
+
+- **`owned: true`** (or absent — legacy/COD-104 sessions persisted before this
+  field) — we launched it via `buildRemoteLaunchCommand` and may explicitly kill it.
+- **`owned: false`** — discovered + attached; another Codeman owns the remote
+  session. `remoteSessionName` holds its existing tmux name. Closing the tab
+  **detaches**, never kills.
+
+### Discovery
+
+`listRemoteCodemanSessions(host)` lists the remote's `codeman-*` sessions:
+
+- `buildRemoteListSessionsCommand()` runs `tmux -L codeman list-sessions -F "…"`
+  over SSH (connection args from the shared `buildSshConnectionArgs`, so discovery
+  connects identically to launch/probe). `2>/dev/null` swallows tmux's "no server
+  running" stderr.
+- `parseRemoteSessionList()` is a **pure, unit-tested** parser. ⚠️ Quirk: the
+  remote tmux's `-F "…\t…"` format emits the **literal two-character `\t`**, not a
+  real tab (verified on tmux next-3.7), so the parser splits on `/\\t|\t/` (literal
+  backslash-t **or** a real tab, for builds that do expand it). It keeps only
+  `codeman-*` names, coerces types, and skips malformed lines.
+- `listRemoteCodemanSessions()` **never throws** — unreachable host / no tmux / no
+  sessions all map to `[]`. Like the prereq probe, it **no-ops to `[]` under
+  `VITEST`** so a request path never opens a real ssh connection.
+
+Discovery is **explicit** — the UI has a "Discover existing sessions" button per
+host; Codeman never auto-discovers on host select.
+
+### Attach vs. launch selection
+
+`buildRemoteSessionCommand(mode, remote, sessionId)` in `tmux-manager.ts` picks the
+remote command line by ownership:
+
+- **`owned === false`** → `buildRemoteAttachCommand(remote, name)` — emits
+  `ssh … -t … 'tmux -L codeman attach -t <remoteSessionName>'`. It uses **`attach`,
+  NOT `new-session -A`**, so it only *joins* an existing session and never creates
+  one.
+- **owned (default)** → `buildRemoteLaunchCommand` (the COD-104 path above).
+
+### Detach-not-kill
+
+`TmuxManager.killSession()` has an **early return for non-owned remote sessions**:
+it tears down **only the LOCAL pane** holding the ssh client (`tmux -L codeman
+kill-session` on *this* host's socket). Killing the local ssh sends SIGHUP to the
+remote `tmux attach`, which **detaches** — the durable remote session survives.
+The early return is a structural guarantee that **no code path can ever issue a
+remote `kill-session` for a session we don't own** — the only `kill-session` run is
+on the local socket, which never reaches the remote socket.
+
+## API
+
+Routes are registered in `src/web/routes/case-routes.ts`:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/remote-hosts` | List saved hosts |
+| `POST` | `/api/remote-hosts` | Create a host |
+| `PUT` | `/api/remote-hosts/:id` | Update a host |
+| `DELETE` | `/api/remote-hosts/:id` | Delete a host |
+| `GET` | `/api/remote-hosts/:hostId/sessions` | Discover `codeman-*` sessions on the host (COD-105; `listRemoteCodemanSessions`, never errors) |
+| `POST` | `/api/cases/remote-link` | Link a case to a remote host (creates the `RemoteCase`) |
+
+Attaching to a discovered session is a **session-create** path, not a host route:
+`POST /api/sessions` accepts `attachRemoteSession: { hostId, remoteSessionName }`
+(schema in `schemas.ts`; `remoteSessionName` must match `^codeman-[a-zA-Z0-9._-]+$`),
+which `session-routes.ts` turns into a non-owned (`owned: false`) session.
+
+Frontend touchpoints: the remote-host management UI is in `session-ui.js` /
+`panels-ui.js`; a remote session is created by picking a remote host/case in the
+session-create flow, or via the per-host **"Discover existing sessions"** button →
+**Attach** action (creates an `owned: false` session).
+
+## Security notes
+
+- **`identityFile` is a path only — never key bytes.** Codeman stores the path and
+  passes it to `ssh -i`; the key never enters Codeman's state or the wire.
+- The injection surface is the SSH option fields. The single-source
+  `buildSshConnectionArgs` + `shellescape` discipline (COD-107) is the control —
+  audit any new code path that constructs an ssh command to route through it
+  rather than concatenating options inline.
+- `BatchMode=yes` means **no interactive password/passphrase prompts** — remote
+  hosts must be reachable with key-based or agent auth (or an unencrypted key the
+  agent has loaded). A host needing a passphrase will fail the probe with an ssh
+  diagnostic rather than hang.
+
+## Related
+
+- `CLAUDE.md` → Architecture → **Remote** row, and the **Remote sessions (SSH)**
+  Key Pattern.
+- `docs/security-architecture.md` — overall network/auth model.
+- COD-104 (tmux prereq + durable launch), COD-105 (discover + attach, detach-not-kill ownership), COD-107 (shell-safe connection args).

docs/security-architecture.md

@@ -30,7 +30,8 @@ an explicit, guided opt‑in.
 7. [Supply‑chain & build‑asset hardening](#7-supplychain--buildasset-hardening-cod28)
 8. [Multi‑instance isolation](#8-multiinstance-isolation)
 9. [Transport security headers](#9-transport-security-headers)
-10. [Quick reference](#10-quick-reference)
+10. [Docker container isolation](#10-docker-container-isolation)
+11. [Quick reference](#11-quick-reference)
 
 ---
 
@@ -248,16 +249,28 @@ Ordered most‑to‑least recommended:
 
 ### A. Tailscale serve (recommended)
 
-Bind loopback, let Tailscale front it on your tailnet with a real cert:
+Bind loopback, let Tailscale front it on your tailnet with a real cert. **The
+installer sets this up for you**: choose **Tailscale** at the network-access
+prompt, or retrofit an existing install with:
 
 ```bash
-codeman web --https            # binds 127.0.0.1:3000
-tailscale serve --bg https / http://127.0.0.1:3000
+bash ~/.codeman/app/install.sh tailscale
 ```
 
-Only devices on your tailnet can reach it; Tailscale handles identity. No app
-password and no `0.0.0.0` bind required. (This is the maintainer's production
-setup.)
+The guided flow installs Tailscale if needed, walks through login and the
+tailnet HTTPS-certificates toggle, and configures the equivalent of:
+
+```bash
+codeman web                    # binds 127.0.0.1:3000 (plain HTTP is fine here)
+tailscale serve --bg 3000      # HTTPS at https://<node>.<tailnet>.ts.net
+```
+
+Only devices on your tailnet can reach it; Tailscale handles identity and
+terminates TLS with a real Let's Encrypt certificate (so PWA install and web
+push work). No app password and no `0.0.0.0` bind required. (This is the
+maintainer's production setup.) `CODEMAN_TAILSCALE=1` presets the choice for
+automation; the installer never runs `tailscale serve reset` and never touches
+serve mappings other than `443 -> Codeman's port`.
 
 ### B. Authenticated cloudflared tunnel + password
 
@@ -471,7 +484,45 @@ production layout (`~/.codeman`, `-L codeman`, port 3000).
 
 ---
 
-## 10. Quick reference
+## 10. Docker container isolation
+
+Docker cases (1.4.0) run a session inside a per‑case container instead of on the host. The security posture:
+
+- **Hardened create flags, always** — `--cap-drop ALL`, `--security-opt no-new-privileges`, `--pids-limit` (fork‑bomb guard), `--memory` == `--memory-swap` (a real OOM cap), `--init`, and non‑root: `--user <hostUid>:0` on Linux (host uid → workspace files stay host‑owned; GID 0 keeps `$HOME` writable), `--userns=keep-id` on rootless Podman. **Never** `--privileged`, and **never** the docker socket — the pure builder in `docker-hosts.ts` cannot emit them and the schema cannot represent them.
+- **Credentials never enter an image** — the convenient default bind‑mounts host cred dirs (`~/.claude`, `~/.codex`, `~/.gemini`, `~/.config/{gcloud,opencode}`) read‑write. Bind mounts are physically excluded from `docker commit`, so exported images are secret‑free. API‑key CLIs get their key as an exec‑time NAME‑ONLY `--env OPENAI_API_KEY` (no `=value`, no `ps` leak, never committed); a create‑time `-e` for a secret is never used. The **sealed** profile (`mountCredentials:false` + `network:none`) drops the host mounts; full‑image export is then refused (an in‑container login would ride the committed layer) unless a pre‑commit scrub is opted into.
+- **Blast radius — accept it explicitly** — the convenient profile mounts an arbitrary host workspace RW plus the host credential dirs RW into a network‑enabled container, so container‑run agent code can read/modify those host trees and reach the network at once. Still a net improvement over today's on‑host `--dangerously-skip-permissions` execution; use the sealed profile for genuinely untrusted work.
+- **Import is untrusted‑bundle‑safe** — `/api/docker-cases/import` validates the manifest + per‑member SHA‑256 before extraction, rejects absolute / `..` tar members (traversal guard), and re‑tags the loaded image into a quarantined namespace so it can never overwrite `codeman/agent:base` or a pre‑existing tag.
+- **Host guard & the bridge‑hooks listener** — in‑container hook callbacks carry `Host: host.docker.internal` / `host.containers.internal`; both are on the always‑on host‑header allowlist (`DOCKER_HOST_GATEWAY_ALIASES`) and resolve to the host only from inside a container netns, so they are not a browser DNS‑rebinding surface. On a loopback‑only server, in‑container hooks are opt‑in via `CODEMAN_DOCKER_BRIDGE_HOOKS=1`, which binds a SECOND listener on the docker bridge gateway serving **only** the hook endpoints (every other path → `403`) into the same hook‑secret‑gated pipeline. The bridge is host‑internal (containers + host), not the LAN, so it does not widen network exposure; the hook secret is bind‑mounted read‑only and referenced by path.
+- **Instance isolation** — every managed container is labeled `codeman.instance=<CODEMAN_INSTANCE>`; the boot reaper reaps orphans of its OWN instance only, so a beta never removes a prod container. The in‑container tmux socket (`-L codeman-docker`) + session name (`codeman-dkr-*`) deliberately fail a nested Codeman's discovery pattern.
+
+Full feature guide: [`docker-cases.md`](docker-cases.md).
+
+---
+
+## 10a. Multi‑user mode (opt‑in)
+
+`codeman web --multiuser` (or `CODEMAN_MULTIUSER=1`) turns on named users with individually scrypt‑hashed passwords in `~/.codeman/users.json` (mode 0600). OFF by default; when off, nothing here applies and behavior is byte‑identical to single‑user. Design + phase status: [`multi-user-plan.md`](multi-user-plan.md).
+
+- **It is workspace separation, NOT a security boundary between users.** Every session still runs as the SAME OS account with agent code that can read the whole host. Any user can ask their agent to `cat` another user's files; the WEB layer enforces scoping, the AGENT layer cannot. Mitigations: give non‑admins the default `auto` permission mode (classifier‑guarded), pair users with **Docker cases** (container per case) for real isolation, or run separate Codeman instances under separate OS accounts. Stated loudly in the admin panel and the plan's threat model (section 2).
+- **It strictly improves network posture.** It removes the single shared `CODEMAN_PASSWORD` and gives each person a revocable credential; a non‑loopback bind and the tunnel‑enable guard are satisfied by "multi‑user with ≥1 enabled user" without a shared password.
+- **Auth is a parallel branch** (`middleware/auth.ts`) that leaves the single‑user path untouched: per‑user scrypt verify (`timingSafeEqual`, timing‑equalized against user enumeration), identity‑carrying cookies, a per‑username failure bucket (a botnet can't brute one account across IPs; one NATed user can't lock out the rest), and a `mustChangePassword` lockbox. The hook‑secret loopback bypass, host guard, and Origin/CSRF guard are unchanged (hooks authenticate the INSTANCE, not a user).
+- **Ownership is enforced server‑side only** and fails closed: `req.authUser` (a synthetic admin in single‑user), `findSessionOrFail` returns NOT_FOUND (never 403) for a foreign session, list/SSE/WS/file‑preview/search all filter by `session.owner`, and SSE routing defaults session‑scoped events to their owner (unresolved owner → withheld). The load‑bearing rule is **non‑admin `workingDir` confinement**: a non‑admin's session/one‑shot working dir must realpath‑resolve inside `~/codeman-users/<name>/cases`, checked BEFORE any disk write.
+- **Privileged actions are a one‑bit grant** (`canBypassPermissions`, default off): only granted users (and admins) get `--dangerously-skip-permissions` (others are silently downgraded to `--permission-mode auto`), shell‑mode sessions, cron `launchCommand`, and other CLIs' bypass flags. Machine‑level resources (remote/Docker host definitions, tunnel, self‑update, settings writes) are admin‑only.
+- **Admin actions are audited** append‑only to `~/.codeman/admin-audit.jsonl` (acting admin, action, target, IP). Passwords set by an admin create/reset are one‑time (returned once, force change). Under Basic auth, `logout` only truly ends QR‑issued sessions — to lock someone out, disable the account or reset the password (a proper login form is a deferred Phase 6).
+
+---
+
+## 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 |
 |------------|--------|
@@ -482,6 +533,8 @@ production layout (`~/.codeman`, `-L codeman`, port 3000).
 | `--https` | Enable TLS (adds HSTS) |
 | `CODEMAN_INSTANCE` | Scope tmux socket + data dir for isolation |
 | `CODEMAN_GESTURE=1` | Make the gesture overlay available (widens CSP) |
+| `CODEMAN_DOCKER_BRIDGE_HOOKS=1` | Serve the hook endpoints on the docker bridge gateway (host‑internal, hooks‑only, `403` elsewhere) so in‑container hooks reach a loopback‑bound server — see §10 |
+| `CODEMAN_DOCKER_BRIDGE_HOST` | Override the bridge gateway IP the hooks listener binds (default: auto‑detect) |
 
 **Audit log:** session lifecycle and server start are recorded in
 `~/.codeman/session-lifecycle.jsonl`.

docs/tailscale-installer-plan.md

@@ -0,0 +1,236 @@
+# Tailscale Setup in the Installer (Plan)
+
+Goal: make "Codeman over Tailscale, with real HTTPS" a first-class, guided path in
+`install.sh`, instead of a one-line hint pointing at the docs. Today the safest
+recommended deployment (loopback bind + `tailscale serve`) is exactly what the
+maintainer's own prod runs, but a new user has to discover and wire it by hand.
+The installer should do it for them.
+
+Status: IMPLEMENTED (2026-08-04). `install.sh` carries the 3-way network
+prompt, the guided Tailscale flow, and the `tailscale` subcommand; README,
+`docs/security-architecture.md` section A, and CLAUDE.md are updated. Verified
+live on the maintainer's prod host: `install.sh tailscale` took the idempotent
+kept-as-is path against the existing serve mapping (recognizing the legacy
+`https+insecure://` target), verified `https://<node>.ts.net/api/status`
+end-to-end, and left `tailscale serve status` byte-identical. Items 1-4, 7,
+and 10-12 of the manual matrix below still need a fresh machine to exercise.
+
+## Why this is low-hanging fruit
+
+Everything on the app side already works; this is almost purely installer UX:
+
+- `.ts.net` is already in `DEFAULT_TRUSTED_HOST_SUFFIXES`
+  (`src/web/network-auth-policy.ts`), so the always-on Host/Origin guard accepts
+  `tailscale serve` traffic with zero configuration. No `CODEMAN_ALLOWED_HOSTS`
+  needed.
+- The loopback bind is the server default and prints no warning; nothing to
+  acknowledge, no `CODEMAN_PASSWORD` strictly required (the tailnet is the auth
+  boundary; Tailscale authenticates the device before a packet ever reaches us).
+- `tailscale serve` terminates TLS with a real Let's Encrypt certificate for
+  `<node>.<tailnet>.ts.net`. That gives users valid HTTPS with no self-signed
+  cert warnings, and (because it is a proper secure context) working service
+  worker, PWA install, and web push on phones. This is strictly better than
+  `codeman web --https` for remote access.
+- SSE and WebSockets work through serve (proven by prod:
+  `https://tnode.tailf80371.ts.net` fronting `127.0.0.1:3000` daily).
+- `docs/security-architecture.md` section "A. Tailscale serve (recommended)"
+  already documents this as the preferred setup; the installer just does not
+  implement it.
+
+## UX design
+
+### 1. The network-access prompt grows a Tailscale option
+
+`choose_network_binding()` (install.sh:1051) currently offers two choices. New
+menu, with Tailscale first when it can be recommended:
+
+```
+  Network access
+
+  How should the Codeman dashboard be reachable?
+
+    1) Tailscale (recommended)
+       Private VPN access from your phone/laptop, real HTTPS,
+       no password needed. Works from anywhere, not just your Wi-Fi.
+    2) Any device on your network (0.0.0.0)
+       Open it straight from your phone or laptop on the same Wi-Fi.
+       Less safe: set a password so only you control your agents.
+    3) This machine only (127.0.0.1)
+       Safest. Reach it remotely via Tailscale or a tunnel later.
+```
+
+Choice mapping:
+
+- Option 1 = bind `127.0.0.1` (unchanged server posture) + configure
+  `tailscale serve`. Internally it is option 3 plus the serve setup, so all
+  existing binding plumbing (`BIND_HOST`, service files, `read_existing_binding`)
+  is untouched.
+- Options 2 and 3 behave exactly as today (renumbered).
+- Default choice: 1 when tailscale is installed and logged in, or when an
+  existing serve mapping for our port is detected; otherwise keep today's
+  defaults (1 -> 2, 2 -> 3 renumbering, preserving the "existing setup wins"
+  rule). If tailscale is not installed, option 1 is still shown (the installer
+  offers to install it), but the default stays on the current behavior so a
+  bare Enter never pulls in new software.
+- Password: after choosing Tailscale, offer the password prompt as optional
+  defense in depth with default skip ("the tailnet already authenticates your
+  devices; add one anyway?"). No `BIND_ACK` needed since the bind is loopback.
+
+### 2. The Tailscale flow (state machine)
+
+New `setup_tailscale_access()` runs after the binding choice, before service
+setup, handling each state in order:
+
+1. **Not installed.**
+   - Linux: offer to run the official installer
+     (`curl -fsSL https://tailscale.com/install.sh | sh`), which handles all
+     distros and enables `tailscaled` at boot. This mirrors our own
+     curl-pipe-bash story and avoids maintaining per-distro logic like the six
+     `install_cloudflared_*` functions.
+   - macOS: do not auto-install (the GUI app needs an interactive login).
+     Offer `brew install --cask tailscale` when brew exists, else print the
+     download link, then wait-and-retry or let the user skip.
+   - Declined install => fall back to plain loopback (option 3 behavior) and
+     print how to redo this later (`install.sh tailscale`, see below).
+2. **Installed but logged out** (`tailscale status --json` ->
+   `.BackendState == "NeedsLogin"` or `"Stopped"`).
+   - Run `tailscale up` (via `run_as_root` if needed). It prints an auth URL
+     that works headless (user opens it on any device). Poll
+     `.BackendState == "Running"` with a friendly spinner + timeout; on
+     timeout, skip gracefully with re-run instructions.
+3. **Running: grant operator (Linux).** `sudo tailscale set --operator=$USER`
+   so serve configuration (now and in the future) does not need root. Skip
+   silently if we are already operator (probe: `tailscale serve status`
+   exits 0) or sudo is declined; fall back to `run_as_root tailscale serve ...`.
+4. **HTTPS availability check.** `.CertDomains` empty or
+   `.CurrentTailnet.MagicDNSEnabled == false` means the tailnet has not enabled
+   MagicDNS / HTTPS certificates. Print the exact two toggles with the admin
+   URL (https://login.tailscale.com/admin/dns: enable MagicDNS, then enable
+   HTTPS Certificates), then offer "I enabled it, re-check" / "skip for now".
+   No silent HTTP fallback: the pitch is real HTTPS, and a plain-HTTP serve
+   would break the PWA/push story. Skipping falls back to loopback + re-run
+   instructions.
+5. **Existing serve config check** (`tailscale serve status --json`).
+   - Already proxying to our port (443 -> `127.0.0.1:$PORT`): keep it, report
+     it, done. Re-running the installer must be idempotent.
+   - Port 443 occupied by a DIFFERENT target: never clobber it. Ask whether to
+     replace it or skip. (Prod itself has a second serve on :5000; blind
+     `tailscale serve reset` would destroy user config. NEVER use `reset`.)
+6. **Configure.** `tailscale serve --bg $PORT` where `$PORT` is the install's
+   Codeman port (default 3000; honor a preset `CODEMAN_PORT`). Serve targets
+   plain HTTP on loopback; TLS terminates at tailscaled with the real cert.
+   The `--bg` config persists in tailscaled state across reboots, so no extra
+   service unit is needed.
+   (Note: do NOT combine this with `codeman web --https`; that is what forces
+   the awkward `https+insecure://` proxy target prod historically used. New
+   installs should keep Codeman on plain HTTP behind serve.)
+7. **Verify end-to-end.** Derive the URL from `.Self.DNSName` (strip the
+   trailing dot) and curl `https://<dnsname>/api/status` after the service is
+   up, retrying for ~30s: the first request can be slow while the Let's
+   Encrypt cert is issued. Print success with the URL, or the observed error
+   with `tailscale serve status` output on failure. This follows the "always
+   test before claiming it works" rule; a blind "done!" is not acceptable.
+
+### 3. Closing summary and security notice
+
+- The final summary gains a "Remote Access (Tailscale)" block, printed above
+  the cloudflared block, showing the actual URL:
+
+  ```
+    Remote Access (Tailscale):
+      https://tnode.tailf80371.ts.net    (any device on your tailnet, HTTPS)
+      tailscale serve status             # inspect
+  ```
+
+- `print_security_notice()` third branch (loopback) gets a variant: when a
+  serve mapping for our port is detected, lead with "reachable on your tailnet
+  at https://... (HTTPS, tailnet-only)" instead of the generic "do ONE of"
+  list. Detection is dynamic (query `tailscale serve status --json` at print
+  time), no marker persisted anywhere: tailscaled's own state is the single
+  source of truth, so external changes never drift against a stale flag.
+
+### 4. Standalone entry point: `install.sh tailscale`
+
+Add a `tailscale` subcommand next to `update` / `uninstall` in the existing
+dispatch. It runs `setup_tailscale_access()` against the already-installed
+service (reads the port from the service file, requires an existing install).
+This serves:
+
+- existing installs that predate the feature,
+- users who picked "this machine only" and changed their mind,
+- every "skip for now" branch above, all of which print this exact command.
+
+One implementation, two entry points. No separate `scripts/tailscale-setup.sh`
+(unlike cloudflared, there is no long-running process for a `tunnel.sh`-style
+start/stop wrapper to manage; tailscaled owns the lifecycle).
+
+### 5. Non-interactive / automation
+
+- `CODEMAN_TAILSCALE=1` presets choice 1 (analogous to presetting
+  `CODEMAN_HOST`). In non-interactive runs it only proceeds through states
+  that need no human (already installed + logged in + HTTPS-enabled tailnet);
+  anything requiring interaction (login URL, admin-console toggle, replacing a
+  foreign serve mapping) warns and falls back to loopback. It never installs
+  tailscale non-interactively.
+- `CODEMAN_NONINTERACTIVE=1` with an existing serve mapping: preserve it, same
+  "never silently loosen/change" policy as `read_existing_binding`.
+- Document both in the header comment block of install.sh (the env-var
+  reference at the top) and in the README.
+
+## Edge cases and decisions
+
+| Case | Decision |
+| ---- | -------- |
+| macOS GUI app without `tailscale` on PATH | `get_tailscale_path()` helper mirroring `get_cloudflared_path()`: check PATH, then `/Applications/Tailscale.app/Contents/MacOS/Tailscale`. All calls go through it. |
+| Tailnet HTTPS certs disabled | Guided admin-console instructions + re-check loop; skip falls back to loopback. Never configure plain-HTTP serve. |
+| Port 443 serve exists for another app | Prompt replace/skip; never `tailscale serve reset` (destroys unrelated mappings). |
+| First cert issuance latency | Verify step retries ~30s and says why the first load may be slow. |
+| `tailscale up` needs auth | Print the auth URL prominently, poll with timeout, skip gracefully. Works headless. |
+| Custom `CODEMAN_PORT` | Serve target uses the actual port; `install.sh tailscale` re-reads it from the service file. |
+| Funnel (public internet) | OUT OF SCOPE for v1. If ever added it must mirror the tunnel guard: refuse without `CODEMAN_PASSWORD` (`isUnauthenticatedNetworkAcknowledged`). Funnel exposes to the whole internet and is a different risk class than tailnet-only serve. Mention `tailscale funnel` in docs only, with the password warning. |
+| Uninstall | Best effort: if `serve status --json` shows 443 proxying to our port, run the targeted `tailscale serve --https=443 off` (still accepted by current CLIs); if the CLI rejects it, print manual instructions. Never touch other mappings, never uninstall tailscale itself. |
+| User already fronting Codeman some other way (reverse proxy etc.) | The serve check only looks at tailscale state; other proxies are invisible and unaffected (same stance as the loopback-exemption note in security-architecture). |
+
+## What does NOT change
+
+- Server code: no changes required. Host guard already trusts `.ts.net`,
+  loopback bind is already the default, SSE/WS already work through serve.
+- The two existing binding options and their semantics, `read_existing_binding`
+  preservation, and the LAN+password flow.
+- `scripts/tunnel.sh` / cloudflared support (stays as the "no Tailscale
+  account" alternative).
+- The security model: this feature only ever narrows exposure (loopback +
+  authenticated overlay), never widens it.
+
+## Files touched (implementation inventory)
+
+| File | Change |
+| ---- | ------ |
+| `install.sh` | New: `check_tailscale`, `get_tailscale_path`, `tailscale_status_field` (jq-free JSON field extraction; the installer cannot assume jq: use `sed`/`grep` like existing helpers or `tailscale status --json` piped to `node -e` since node is guaranteed post-install), `offer_install_tailscale`, `ensure_tailscale_login`, `ensure_tailscale_operator`, `ensure_tailnet_https`, `setup_tailscale_serve`, `verify_tailscale_access`, `setup_tailscale_access` (orchestrator). Modified: `choose_network_binding` (3-way menu), summary block, `print_security_notice`, subcommand dispatch (`tailscale`), `uninstall` (targeted serve removal), header env-var docs (`CODEMAN_TAILSCALE`). |
+| `README.md` | Remote-access section: promote the Tailscale path with the one-liner and `install.sh tailscale`; keep the tailscale-IP HTTP note for non-serve users but recommend serve + HTTPS. |
+| `docs/security-architecture.md` | Section A gains "the installer can set this up for you" + `install.sh tailscale` pointer. |
+| `CLAUDE.md` | One line in Scripts & Tunnel: installer offers Tailscale setup (`install.sh tailscale` to redo). |
+| `test/` | No unit tests possible for interactive bash + a live tailnet; guard with `shellcheck install.sh` (already the norm) and the manual matrix below. |
+
+## Manual test matrix (before release)
+
+1. Linux + tailscale absent: install offered, declined => loopback fallback + hint.
+2. Linux + tailscale absent: install accepted => full flow => URL verified.
+3. Logged out => auth URL flow => Running => serve configured.
+4. Tailnet with HTTPS certs disabled => guided instructions => re-check => success; and the skip branch.
+5. Re-run installer with serve already configured => idempotent, preserved, reported.
+6. Second serve mapping on another port present => untouched (prod-like state).
+7. Port 443 already proxying another target => replace/skip prompt honored.
+8. `install.sh tailscale` on an existing loopback install (the retrofit path).
+9. `CODEMAN_NONINTERACTIVE=1` re-run => preserves everything, no prompts.
+10. macOS (Mac mini `arbbot` box): GUI-app CLI path detection + full flow.
+11. Uninstall removes only our 443 mapping, leaves others.
+12. Phone check: PWA install + push from the `https://*.ts.net` origin.
+
+## Release
+
+Changeset: `minor` (new documented installer capability + new `CODEMAN_TAILSCALE`
+env var). The feature is installer-only, so it ships with zero risk to running
+servers; `install.sh update` does not invoke the new flow (updates never rewrite
+access config), only fresh installs and the explicit `install.sh tailscale`
+subcommand do.

docs/usage-limits-display-plan.md

@@ -1,6 +1,6 @@
 # Plan Usage Limits Display — Design & As-Built
 
-> **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** Opt-in via App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`, default OFF). Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
+> **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`). **Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via `planUsageChipEnabled()`.** The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
 >
 > Two surfaces from one `statusLine` callback:
 > - **Header chip** (top-right) — account-wide **plan limits**: `5h 35% · 7d 38%`, per-window green/yellow/red.

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-fixes-plan.md

@@ -0,0 +1,190 @@
+# Web tabs: two fixes (planned + implemented 2026-07-28)
+
+Both found against the saved dashboard
+`https://<your-host>.<your-tailnet>.ts.net:4000` (Bio-Hacking-Dashboard).
+Kept because the root-cause analysis of the second one is not obvious from the
+resulting diff.
+
+Status: **both implemented and verified end-to-end.** The one deliberate
+non-change is recorded at the bottom.
+
+---
+
+## Bug 1: saved URLs could not be deleted from the Run dropdown
+
+### What happened
+
+The "Web / URL" section of the Run dropdown listed every saved dashboard as a
+single clickable row whose only action was "open". Deleting required opening the
+dashboard as a tab, clicking the tab's gear, then Delete in the modal, so a URL
+you no longer wanted open at all could not be removed without first opening it.
+
+### What shipped
+
+- `renderWebviewMenuItems()` (`src/web/public/webview-tabs.js`) now renders each
+  saved URL as a `.run-mode-row--web` flex row: the open button, a gear
+  (`showWebviewModal`), and an `x` (`deleteWebviewById`). Nested buttons are
+  invalid HTML, hence the wrapper rather than a button inside a button.
+- `deleteWebview()` split into the modal entry point, the new row entry point
+  `deleteWebviewById(id)`, and the shared `_confirmAndDeleteWebview(id)`.
+- Both side buttons call `event.stopPropagation()` so the click does not also
+  open the dashboard.
+- The dropdown's outside-click handler (`session-ui.js`) closes when the click
+  target is not inside `#runModeMenu`, and the row is gone by the time the delete
+  resolves, so `deleteWebviewById` re-asserts `.active` on the menu. Verified in a
+  browser: deleting one of several URLs leaves you looking at the rest of the list.
+- CSS in `styles.css` (`.run-mode-row--web`, `.run-mode-row-btn`) plus a larger
+  touch target in `mobile.css`. The side buttons are permanently visible rather
+  than hover-revealed, because this menu is used on touch.
+
+No server change: `DELETE /api/webviews/:id` already existed, owner-scoped, and
+already revoked the capability and broadcast `WebviewChanged`.
+
+---
+
+## Bug 2: images did not load in a proxied dashboard
+
+### Reproduction (before the fix)
+
+```
+CAP=<from POST /api/webviews/<id>/open>
+# A) upstream direct                       -> 200 image/jpeg 118150
+curl -sk "https://<your-host>.<your-tailnet>.ts.net:4000/api/hero?slug=120-minutes-in-nature"
+# B) through the proxy prefix              -> 200 image/jpeg 118150
+curl -sk "https://localhost:3000/webview/$CAP/api/hero?slug=120-minutes-in-nature"
+# C) what the browser ACTUALLY requested   -> 404 {"errorCode":"NOT_FOUND"}
+curl -sk -H "Referer: https://localhost:3000/webview/$CAP/" \
+     "https://localhost:3000/api/hero?slug=120-minutes-in-nature"
+# D) same shape but NOT under /api         -> 200 (referer fallback rescues it)
+curl -sk -H "Referer: https://localhost:3000/webview/$CAP/" "https://localhost:3000/styles.css"
+```
+
+The proxy itself was fine (B). The failure was entirely about which URL the
+browser ended up requesting (C).
+
+### Root cause
+
+The dashboard builds its image markup at runtime with root-absolute URLs:
+`c.innerHTML = '<img class="thumb" src="/api/hero?slug=...">'`, `img.src =
+slideSrc(...)` returning `/api/slide?owner=...`, `/api/story`, `/api/video`, and a
+nested `<iframe src="/api/preview?slug=...">`.
+
+All three rewrite layers missed that shape:
+
+1. `<base href="/webview/<cap>/">` only affects **relative** URLs. A root-absolute
+   `/api/hero` ignores the base path and resolves against Codeman's origin.
+2. `rewriteHtml()` only runs over the **initial HTML document**. This markup is
+   created later by page script. (The static header `<img src="/api/logo">` DID
+   work, having been rewritten at proxy time, which is why only the
+   runtime-injected images were broken.)
+3. `runtimeUrlShim()` patched only `fetch`, `XMLHttpRequest.open`, `WebSocket` and
+   `EventSource`, so the dashboard's **data** loaded while its **pictures** did
+   not.
+
+The safety net was fenced off from `/api` in two places, both deliberate:
+`server.ts`'s not-found handler returns the API-envelope 404 before reaching
+`tryWebviewRefererFallback`, and `middleware/auth.ts` refuses the Referer-form
+auth exemption for `/api/`, `/ws/`, `/q/`.
+
+### What shipped
+
+`runtimeUrlShim()` in `src/web/webview-proxy.ts` now also covers the DOM sinks, so
+a root-absolute `/api/...` request is never emitted in the first place and neither
+security fence had to move:
+
+- `innerHTML` / `outerHTML` / `insertAdjacentHTML` (and `ShadowRoot.innerHTML`),
+- `setAttribute` / `setAttributeNS`,
+- the `src`/`srcset`/`href`/`poster`/`data`/`action` property setters on img,
+  source, media, video poster, script, iframe, embed, track, link, anchor, area,
+  object and form,
+- a `MutationObserver` as a last net for any sink not patched above (it costs one
+  wasted 404 per node, since the browser starts fetching on insert, so it is a net
+  and not the mechanism).
+
+Two details that mattered:
+
+- Every rewrite routes through the existing idempotent `rw()` rather than a blind
+  prefix concat. The first draft used the server-side regex shape and
+  double-prefixed markup that was already proxied (a page re-injecting its own
+  `outerHTML`); the jsdom test caught it.
+- Everything stays inside `try`/`catch` and is marked `__cmrw`, so a double
+  injection cannot wrap an already-wrapped setter, and nothing can throw into a
+  page we do not control.
+
+### Verification
+
+- `test/webview-proxy.test.ts` gained a jsdom `runtimeUrlShim DOM sinks` block:
+  innerHTML, insertAdjacentHTML, property setters, setAttribute, srcset candidate
+  lists, the MutationObserver net via an unpatched sink
+  (`createContextualFragment`), idempotence, re-injected markup, empty `src`, and
+  the pass-throughs (relative, cross-origin, `#hash`, `data:`). 73 tests pass.
+- End-to-end in a real browser against an isolated instance
+  (`CODEMAN_INSTANCE=wvtest`, port 3151), with prod's old build as the negative
+  control:
+
+  | | before (prod, old build) | after (fixed) |
+  | --- | --- | --- |
+  | images found | 693 | 693 |
+  | src under the proxy prefix | 0 | 693 |
+  | in-viewport images decoded | 0 / 23 | 23 / 23 |
+  | sample src | `/api/hero?slug=...` | `/webview/<cap>/api/hero?slug=...` |
+
+  (The dashboard marks thumbs `loading="lazy"`, so only in-viewport images are
+  ever fetched. All 27 proxied image responses returned 200.)
+
+---
+
+## Follow-up (same day): the `/api` referer fallback, done safely
+
+Originally deferred, then implemented on request. Both gates had to move, and the
+auth one is the security-sensitive half: auth runs in `onRequest`, before routing,
+so it cannot tell a real Codeman API route from a 404, and simply dropping the
+`/api` fence would let a page holding a capability forge a `Referer` and reach
+Codeman's **real** API unauthenticated.
+
+What shipped:
+
+- `server.ts`: `tryWebviewRefererFallback` is tried **before** the API-shaped 404.
+  Reaching that handler already proves no route matched, and the relay declines
+  unless the `Referer` carries a live capability, so unknown `/api` paths still
+  get the envelope.
+- `middleware/auth.ts`: the `/api/` prefix refusal is replaced by
+  `matchesRegisteredRoute()`, which refuses the exemption for any path that
+  resolves to a real route. `/ws/` and `/q/` stay refused by prefix.
+
+Two findings that decided the implementation, both established by probing Fastify
+rather than by reading its docs:
+
+- **`hasRoute()` is the wrong tool and would have been a hole.** It matches the
+  registered PATTERN literally, so `hasRoute({url: '/api/sessions/abc'})` returns
+  false against a registered `/api/sessions/:id` and would have handed out an
+  exemption on a live, session-scoped API route. `findRoute()` performs the real
+  radix-tree lookup and is what the fence uses.
+- **`@fastify/static` is mounted at `/`, so it registers a root catch-all that
+  matches every path.** A match on it means "heading for the 404 handler", not
+  "real route", and it is distinguishable because a root catch-all is the only
+  route whose `*` param comes back equal to the whole request path. Without that
+  carve-out the fence would have refused every referer-form request and broken the
+  rescue that already worked.
+
+The fence fails closed, and `test/webview-auth-exemption.test.ts` pins both edges
+(a concrete URL onto a parametric API route stays 401; the dashboard's own
+`/api/...` namespace is served).
+
+### And the CSS gap, which the fallback could NOT close
+
+Testing the fallback against a purpose-built upstream showed the runtime-injected
+stylesheet case is unreachable by any relay: a `<style>` element has no URL of its
+own, so Chromium sends an **empty `Referer`** with the image request it triggers
+and there is nothing to key on. Measured directly:
+
+| sink | Referer the browser sends | fixed by |
+| --- | --- | --- |
+| `url()` in a proxied `.css` | the stylesheet's proxied URL | the referer relay |
+| `url()` in a runtime `<style>` | *empty* | `rwCss()` in the shim |
+
+So the shim also rewrites `url()` inside `<style>` blocks, both when they arrive as
+markup and when a `<style>` node is inserted (via the existing MutationObserver).
+
+The only gap left is self-navigation via `location.href = '/x'`, which cannot be
+patched because `Location.href` is unforgeable.

docs/web-tabs.md

@@ -0,0 +1,155 @@
+# 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.
+To delete it for good, use the `x` on its **dropdown row** (the tab's own `x` is
+close, not delete). Each dropdown row also has a gear for editing, so a saved URL
+can be changed or removed without opening it first.
+
+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` in the page the
+   proxy serves.
+3. A small injected script rebases URLs built at **runtime**, which the first two
+   cannot see: `fetch('/api/data')` and `new WebSocket('/live')`, but equally
+   `card.innerHTML = '<img src="/api/hero">'`, `img.src = '/api/slide'`, and
+   `url(/img.png)` inside a `<style>` the page injects. That second group is why
+   images are covered too. A dashboard that renders its thumbnails from script
+   would otherwise show all its data and none of its pictures, because `<base>`
+   does not apply to root-absolute URLs and the attribute rewriting only ever saw
+   the initial document.
+4. As a last resort, a request that still lands on Codeman's own root is relayed
+   using its `Referer` to identify the dashboard. This only fires for a request
+   that already missed every Codeman route, and never for one that resolves to a
+   real route, which is what keeps it from being an authentication bypass.
+
+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 layers above cover normal `fetch`/XHR/WebSocket/
+  EventSource, normal markup, the DOM sinks a page uses to build markup at runtime,
+  and `url()` inside stylesheets. Something that constructs requests by an unusual
+  route can still slip through. Symptom: the page renders but a panel stays empty.
+- **Root-absolute `location` navigation.** A dashboard that navigates itself with
+  `location.href = '/login'` escapes the prefix, because `Location.href` is
+  unforgeable and cannot be patched the way the other sinks are. A relative
+  `location.href = 'login'` is fine (`<base>` covers it).
+- **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`             |

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.1.10",
+  "version": "1.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.1.10",
+      "version": "1.10.0",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -28,10 +28,13 @@
         "chokidar": "^3.6.0",
         "commander": "^12.1.0",
         "fastify": "^5.8.5",
+        "heic-decode": "^2.1.0",
+        "jpeg-js": "^0.4.4",
         "node-pty": "^1.1.0",
         "qrcode": "^1.5.4",
         "uuid": "^14.0.0",
         "web-push": "^3.6.7",
+        "ws": "^8.21.0",
         "zod": "^4.3.6"
       },
       "bin": {
@@ -7023,6 +7026,18 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/heic-decode": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/heic-decode/-/heic-decode-2.1.0.tgz",
+      "integrity": "sha512-0fB3O3WMk38+PScbHLVp66jcNhsZ/ErtQ6u2lMYu/YxXgbBtl+oKOhGQHa4RpvE68k8IzbWkABzHnyAIjR758A==",
+      "license": "ISC",
+      "dependencies": {
+        "libheif-js": "^1.19.8"
+      },
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/html-encoding-sniffer": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
@@ -7481,6 +7496,12 @@
         "node": ">=10"
       }
     },
+    "node_modules/jpeg-js": {
+      "version": "0.4.4",
+      "resolved": "https://registry.npmjs.org/jpeg-js/-/jpeg-js-0.4.4.tgz",
+      "integrity": "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/js-tokens": {
       "version": "10.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
@@ -7664,6 +7685,15 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/libheif-js": {
+      "version": "1.19.8",
+      "resolved": "https://registry.npmjs.org/libheif-js/-/libheif-js-1.19.8.tgz",
+      "integrity": "sha512-vQJWusIxO7wavpON1dusciL8Go9jsIQ+EUrckauFYAiSTjcmLAsuJh3SszLpvkwPci3JcL41ek2n+LUZGFpPIQ==",
+      "license": "LGPL-3.0",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/light-my-request": {
       "version": "6.6.0",
       "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
@@ -12303,7 +12333,7 @@
       }
     },
     "packages/xterm-zerolag-input": {
-      "version": "0.1.4",
+      "version": "0.1.8",
       "license": "MIT",
       "devDependencies": {
         "jsdom": "^24.1.3",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.1.10",
+  "version": "1.10.0",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
     "test:coverage": "vitest run --config config/vitest.config.ts --coverage",
     "test:ci": "vitest run --config config/vitest.ci.config.ts",
     "check:frontend-syntax": "node scripts/check-frontend-syntax.mjs",
+    "fix:node-pty": "node scripts/fix-node-pty.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint --config config/eslint.config.js 'src/**/*.ts'",
     "lint:fix": "eslint --config config/eslint.config.js 'src/**/*.ts' --fix",
@@ -32,25 +33,44 @@
     "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/*"
   ],
   "keywords": [
-    "claude",
     "claude-code",
+    "claude-ai",
+    "claude",
     "anthropic",
-    "ai-agent",
-    "automation",
+    "opencode",
+    "codex",
+    "gemini-cli",
+    "ai-agents",
+    "agent",
     "session-manager",
+    "self-hosted",
+    "developer-tools",
+    "tmux",
     "terminal",
+    "xterm",
+    "docker",
+    "mosh",
+    "local-echo",
+    "web-dashboard",
     "cli",
     "llm",
-    "autonomous-agent",
-    "ralph-loop"
+    "automation"
   ],
   "author": "arkon",
   "license": "MIT",
@@ -69,10 +89,13 @@
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "fastify": "^5.8.5",
+    "heic-decode": "^2.1.0",
+    "jpeg-js": "^0.4.4",
     "node-pty": "^1.1.0",
     "qrcode": "^1.5.4",
     "uuid": "^14.0.0",
     "web-push": "^3.6.7",
+    "ws": "^8.21.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -134,6 +157,7 @@
   "files": [
     "dist",
     "scripts/postinstall.js",
+    "scripts/fix-node-pty.mjs",
     "LICENSE",
     "README.md"
   ]

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

@@ -17,6 +17,13 @@
 //   • Panel "re-grab" — pinch an existing floating panel and move it anywhere;
 //     release over the tab strip to re-dock it (panel goes away, the tab stays).
 //     This is the capability the old OS-window detach lost.
+//   • Agent-window "grab-to-move" — pinch any floating *subagent* or *ultracode*
+//     run/transcript window (the dashboard's own `.subagent-window` /
+//     `.ultracode-window` floats) and move it anywhere. These windows stay owned
+//     by app.js — we only nudge their `style.left/top` and ask app.js to redraw
+//     the glowing connector line back to their session tab (its redraw reads live
+//     rects, so the line tracks without us touching app.js internals). This is the
+//     multi-monitor verb that lets these windows cross the physical monitor seam.
 //   • Button "tap" — pinch over a toolbar button (Run / Run Shell) and release
 //     in place → fires the button's real click handler. Drift too far first and
 //     it's treated as a stray move, not a tap.
@@ -36,12 +43,29 @@ import type { HandState } from '../gesture/types.ts';
 declare global {
   interface Window {
     __codemanGesture?: GestureBridge;
+    /** The Codeman dashboard singleton (app.js, `window.app`). The gesture layer
+     *  reaches into it to redraw the floating-window connector lines and bump a
+     *  grabbed window's z-order while moving the subagent / ultracode windows.
+     *  Loosely typed — only the few members we touch. */
+    app?: {
+      updateConnectionLines?: () => void;
+      saveSubagentWindowStates?: () => void;
+      subagentWindowZIndex?: number;
+      ultracodeWindowZIndex?: number;
+    };
   }
 }
 
 const TAB_SELECTOR = '.session-tab';
 /** An in-page floating session panel this layer spawned — re-grabbable to move. */
 const PANEL_SELECTOR = '.cg-float';
+/** The dashboard's own floating agent windows (subagent runs + ultracode run and
+ *  transcript windows). All three carry one of these classes, position via
+ *  `style.left/top`, and redraw their connector line from
+ *  `window.app.updateConnectionLines()` — so the hand can pick one up and move it
+ *  without app.js knowing. (`.ultracode-agent-window` also carries
+ *  `.ultracode-window`, so this matches it too.) */
+const WINDOW_SELECTOR = '.subagent-window, .ultracode-window';
 /** The session-tab strip; dropping a moved panel over it re-docks the session. */
 const DOCK_SELECTOR = '.session-tabs';
 /** Toolbar buttons a pinch can "tap": Run (#runBtn → app.run()) and Run Shell
@@ -93,6 +117,17 @@ type Grab =
       dy: number;
       /** Cursor currently over the tab strip → releasing re-docks. */
       overDock: boolean;
+    }
+  | {
+      /** A dashboard-owned floating agent window (subagent / ultracode) being
+       *  moved. We never remove or re-parent it — just reposition + redraw its
+       *  connector. The element ref can go stale mid-grab (SSE reconnect tears
+       *  ultracode windows down), so every move guards on `el.isConnected`. */
+      kind: 'window';
+      el: HTMLElement;
+      /** Cursor→window-top-left offset at grab, so it doesn't snap. */
+      dx: number;
+      dy: number;
     };
 
 /** Live state for one hand pinching a toolbar button (Run / Run Shell). */
@@ -122,6 +157,8 @@ class GestureBridge {
   private taps = new Map<string, Tap>();
   /** Live floating panels, keyed by session id (idempotent per id). */
   private floats = new Map<string, FloatingPanel>();
+  /** rAF coalescing for connector-line redraws while dragging an agent window. */
+  private connectorRedrawScheduled = false;
 
   constructor() {
     injectStyles();
@@ -187,7 +224,7 @@ class GestureBridge {
       await this.gc.start();
       this.running = true;
       this.button.classList.add('on');
-      this.status.textContent = 'on — pinch a tab or button';
+      this.status.textContent = 'on — pinch a tab, window, or button';
     } catch (err) {
       // Surface the *real* cause: MediaPipe/Emscripten can throw a non-Error
       // (number/string), so `(err as Error).message` was logging "undefined".
@@ -242,6 +279,22 @@ class GestureBridge {
       }
     }
 
+    // A dashboard-owned floating agent window (subagent / ultracode run or
+    // transcript) → pick it up and move it. Priority below cg-float panels
+    // (which sit far above), above tabs/buttons. We grab anywhere on the window
+    // (not just its titlebar) since the hand is choosing the whole window.
+    const win = this.hitClosest(x, y, WINDOW_SELECTOR);
+    if (win) {
+      const rect = win.getBoundingClientRect();
+      // Match app.js's own drag: drop any bottom-anchor so left/top take effect.
+      win.style.bottom = 'auto';
+      win.classList.add('cg-win-grabbed');
+      this.bringWindowToFront(win);
+      this.grabs.set(hand, { kind: 'window', el: win, dx: x - rect.left, dy: y - rect.top });
+      this.status.textContent = 'moving window';
+      return;
+    }
+
     // A session tab → grab-and-pull-out into a floating panel (ghost follows).
     const tab = this.hitClosest(x, y, TAB_SELECTOR);
     const id = tab?.dataset.id;
@@ -292,12 +345,16 @@ class GestureBridge {
       }
       return;
     }
+    if (grab?.kind === 'window') {
+      this.moveWindow(grab.el, x - grab.dx, y - grab.dy);
+      return;
+    }
     // A button pinch that drifts too far is a stray move, not a tap — cancel it.
     const tap = this.taps.get(hand);
     if (tap && Math.hypot(x - tap.ox, y - tap.oy) > TAP_CANCEL_PX) {
       tap.el.classList.remove('cg-tap-armed');
       this.taps.delete(hand);
-      this.status.textContent = 'on — pinch a tab or button';
+      this.status.textContent = 'on — pinch a tab, window, or button';
     }
   }
 
@@ -319,6 +376,23 @@ class GestureBridge {
       else this.flash('placed');
       return;
     }
+    if (grab?.kind === 'window') {
+      this.grabs.delete(hand);
+      grab.el.classList.remove('cg-win-grabbed');
+      // Clear the coalescer so the final placement always redraws, even if a
+      // mid-drag rAF was throttled (tab briefly backgrounded) and left it latched.
+      this.connectorRedrawScheduled = false;
+      this.redrawWindowConnectors();
+      // Persist subagent-window positions like app.js's own drag end does
+      // (a no-op for ultracode windows, which aren't position-persisted).
+      try {
+        window.app?.saveSubagentWindowStates?.();
+      } catch {
+        /* best-effort */
+      }
+      this.flash('placed window');
+      return;
+    }
     // Release over the same button → fire its real click handler.
     const tap = this.taps.get(hand);
     if (tap) {
@@ -373,6 +447,59 @@ class GestureBridge {
     float.el.style.top = `${t}px`;
   }
 
+  /** Move a dashboard-owned agent window by its top-left, clamped on-screen, then
+   *  redraw its connector line. The window self-positions via `style.left/top` and
+   *  app.js's connector redraw reads live rects, so this tracks without touching
+   *  app.js internals. Guards on `isConnected`: ultracode windows can be torn down
+   *  (SSE reconnect / auto-close) while still held. Clamps to `innerWidth/Height`,
+   *  which equals the *spanned* viewport in a multi-monitor window — so the window
+   *  can still travel across the physical monitor seam, just not off-screen. */
+  private moveWindow(el: HTMLElement, left: number, top: number): void {
+    if (!el.isConnected) return;
+    const w = el.offsetWidth || 380;
+    const h = el.offsetHeight || 320;
+    const l = Math.min(Math.max(4, left), Math.max(4, window.innerWidth - w - 4));
+    const t = Math.min(Math.max(4, top), Math.max(4, window.innerHeight - h - 4));
+    el.style.left = `${l}px`;
+    el.style.top = `${t}px`;
+    this.redrawWindowConnectors();
+  }
+
+  /** Ask app.js to redraw all connector lines (subagent + ultracode), coalesced to
+   *  one per frame so per-frame drags don't thrash. `updateConnectionLines()` is
+   *  itself debounced in app.js, but we rAF-gate too in case an older dashboard
+   *  build isn't, and to no-op cleanly when app.js isn't present (standalone). */
+  private redrawWindowConnectors(): void {
+    if (this.connectorRedrawScheduled) return;
+    this.connectorRedrawScheduled = true;
+    requestAnimationFrame(() => {
+      this.connectorRedrawScheduled = false;
+      try {
+        window.app?.updateConnectionLines?.();
+      } catch {
+        /* app.js may not expose it (standalone playground) */
+      }
+    });
+  }
+
+  /** Pop a grabbed window above its siblings using app.js's own z-counter, so a
+   *  picked-up window comes to the front like a real focus. Cosmetic + best-effort. */
+  private bringWindowToFront(el: HTMLElement): void {
+    const app = window.app;
+    if (!app) return;
+    try {
+      if (el.classList.contains('ultracode-window')) {
+        app.ultracodeWindowZIndex = (app.ultracodeWindowZIndex ?? 1000) + 1;
+        el.style.zIndex = String(app.ultracodeWindowZIndex);
+      } else {
+        app.subagentWindowZIndex = (app.subagentWindowZIndex ?? 1000) + 1;
+        el.style.zIndex = String(app.subagentWindowZIndex);
+      }
+    } catch {
+      /* cosmetic only */
+    }
+  }
+
   private positionGhost(ghost: HTMLElement, x: number, y: number): void {
     ghost.style.left = `${x}px`;
     ghost.style.top = `${y}px`;
@@ -385,17 +512,19 @@ class GestureBridge {
       if (grab.kind === 'tab') {
         grab.ghost.remove();
         grab.tab.classList.remove('cg-grabbed');
-      } else {
+      } else if (grab.kind === 'panel') {
         grab.panel.el.style.pointerEvents = '';
         grab.panel.el.classList.remove('cg-float-grabbed', 'cg-redock');
+      } else {
+        grab.el.classList.remove('cg-win-grabbed');
       }
     }
     this.grabs.clear();
     for (const tap of this.taps.values()) tap.el.classList.remove('cg-tap-armed');
     this.taps.clear();
     document
-      .querySelectorAll(`${TAB_SELECTOR}.cg-grabbed, .cg-tap-armed`)
-      .forEach((t) => t.classList.remove('cg-grabbed', 'cg-tap-armed'));
+      .querySelectorAll(`${TAB_SELECTOR}.cg-grabbed, .cg-tap-armed, .cg-win-grabbed`)
+      .forEach((t) => t.classList.remove('cg-grabbed', 'cg-tap-armed', 'cg-win-grabbed'));
   }
 
   private onStatus(fps: number, hands: HandState[]): void {
@@ -491,6 +620,10 @@ function injectStyles(): void {
   .cg-status { color: #9aa0a6; max-width: 220px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .session-tab.cg-grabbed { opacity: .35; outline: 2px dashed #4ade80; outline-offset: -2px; }
   .cg-tap-armed { outline: 2px solid #4ade80 !important; outline-offset: 2px; box-shadow: 0 0 0 4px rgba(74,222,128,.25) !important; }
+  .subagent-window.cg-win-grabbed, .ultracode-window.cg-win-grabbed {
+    outline: 2px solid #4ade80 !important; outline-offset: -2px;
+    box-shadow: 0 12px 48px rgba(74,222,128,.5) !important;
+  }
   .cg-float {
     position: fixed; left: 0; top: 0; width: ${FLOAT_W}px; height: ${FLOAT_H}px;
     z-index: ${Z}; display: flex; flex-direction: column; overflow: hidden;

packages/xterm-zerolag-input/CHANGELOG.md

@@ -1,5 +1,69 @@
 # xterm-zerolag-input
 
+## 0.1.8
+
+### Patch Changes
+
+- **Fixed: sessions failed to start on macOS with `Error: posix_spawnp failed.`** (issues #6 and #204)
+
+  `node-pty@1.1.0` publishes its macOS prebuilt helper as `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit. macOS launches every PTY through that helper, so a stock install failed on every session start. The bug is macOS-only: `spawn-helper` is a mac-only gyp target and node-pty ships no Linux prebuild, so Linux always compiles a correctly-permissioned helper from source.
+
+  The previous fix chmodded only `build/Release/spawn-helper`, which on macOS does not exist (the prebuild is used, so node-gyp never runs), and it derived that path from `require.resolve('node-pty')`, landing on `<pkg>/lib/build/Release/...`. It was a no-op on every platform.
+  - New `scripts/fix-node-pty.mjs` (also `npm run fix:node-pty`) chmods every `spawn-helper` it finds, in `build/Release`, `build/Debug` and each `prebuilds/*/`, then verifies the result by actually opening a PTY. A `require()` alone passes on a broken install, because the helper is only touched at spawn time.
+  - `postinstall` no longer force-rebuilds node-pty from source on Node 22+. That step needed Xcode command line tools, cost 30-120s on every install, and deleted the `prebuilds/` tree before compiling, so a Mac without a compiler was left with no working binary at all. A rebuild now happens only when the chmod plus spawn probe still fails, and the prebuilds tree is backed up and restored around it.
+  - New `spawnPtyWithHelperRepair()` (`src/utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts`, so an install that is already broken repairs itself on the first failed spawn and retries in-process instead of showing a dead session. Unrelated spawn errors are rethrown untouched; a second failure carries the `npm run fix:node-pty` hint.
+  - `scripts/fix-node-pty.mjs` is now in the published `files` list, so global npm installs get the repair too.
+  - Direct-PTY Claude spawns use the resolved absolute binary path (new `getClaudeBinaryPath()`) instead of the bare name `claude`, so a CLI installed outside the server's PATH still launches.
+
+  Verified end to end on macOS 26.4 arm64: a stock `npm i` reproduces `posix_spawnp failed.`, and after the fix the same install spawns a PTY successfully with the prebuilds preserved.
+
+  **Added: phone home screen (session overview)**
+
+  Under 430px the "C" logo now opens a session overview (current sessions, past sessions, spaces) instead of the welcome overlay: on a small screen "which session needs me" beats "how do I start one". Rows resume a session in place, and "New session here" goes through the normal quick-start path so remote and Docker cases keep their routing. Per-device setting `mobileOverviewEnabled` (phones only, default ON) in App Settings. Tablet and desktop are unchanged.
+
+  **Added: guided Tailscale setup in `install.sh`**
+
+  The network-access prompt is now 3-way: Tailscale, LAN, or local-only. The Tailscale path binds loopback and walks through installing Tailscale, logging in, the operator grant, the tailnet HTTPS-certificates toggle, and `tailscale serve --bg <port>`, then verifies the result end to end with curl. That gives HTTPS on a real certificate with no app password and no `0.0.0.0` bind, which is also what PWA install and web push need. `install.sh tailscale` retrofits it onto an existing install, and `CODEMAN_TAILSCALE=1` presets the choice. Serve state is detected from `tailscale serve status --json`; the installer never runs `tailscale serve reset` and never touches serve mappings other than 443 to Codeman's port. README and `docs/security-architecture.md` updated to match.
+
+  **Docs**: replaced a real tailnet hostname with placeholders in `docs/web-tabs-fixes-plan.md`.
+
+  **xterm-zerolag-input**: npm description and keywords only, no code change.
+
+## 0.1.7
+
+### Patch Changes
+
+- Fix a latent bug where a partial settings PUT silently reset live service state, and trim the `xterm-zerolag-input` README callout.
+  - **`PUT /api/settings` no longer resets watchers on a partial body.** The three `toggleService` calls (subagent watcher, workflow-run watcher, image watcher) read the raw request body with `??` defaults, so every key a caller omitted was treated as "apply the default". A body of just `{statusLineTelemetry:true}` would START the subagent watcher and STOP the workflow and image watchers, undoing the persisted config. They now resolve from `merged` (persisted settings + incoming), the same convention the `tmuxHistoryLimit` branch in that handler already used, so any PUT reconciles services to the effective stored state. Nothing triggered this in practice because every shipped client sends a full settings payload rebuilt from the DOM, but it was a trap for the next partial-update caller.
+  - **Regression test**: `test/routes/system-routes-settings-partial-put.test.ts` (4 cases) pins both directions, omitted keys preserve state and explicit keys still take effect. Verified to fail against the pre-fix handler.
+  - **CLAUDE.md** records the rule under "Adding Features → App setting": anything acting on a setting in that handler must resolve from `merged`, never the request body.
+  - **`xterm-zerolag-input` README**: removed the links line (getcodeman.com / install one-liner / star link) from the Codeman callout above the demo GIF. The callout keeps its links in the heading and body.
+
+## 0.1.6
+
+### Patch Changes
+
+- Plan-usage chip now defaults ON on desktop, plus the reworked `xterm-zerolag-input` README.
+  - **Plan-usage chip defaults ON (desktop).** The `showPlanUsageLimits` chip (live 5-hour and weekly plan usage from the Claude statusline) used to be opt-in and default OFF, so most users never saw it. Desktop now defaults ON; handhelds still default OFF so the phone header stays minimal and the `mobile-header-buttons-policy` guard keeps passing. Devices with an explicitly stored preference keep whatever they chose, so nobody's OFF gets overridden.
+  - **One resolver behind the chip.** Added `planUsageChipEnabled()` in settings-ui.js and routed all three call sites through it: the App Settings checkbox, the chip's visibility, and the create-time `statusLineTelemetry` flag in session-ui.js. Those three had independent `?? false` / `=== true` defaults, and a chip revealed without the telemetry flag renders `—` forever, so a default flip on one site alone would have shipped a permanently empty chip.
+  - **Cron button comment corrected.** The App Settings comment claimed "Cron button defaults ON" while the code, the template (`btn-cron--hidden`) and the CSS all default it OFF. Verified against a fresh browser profile: the button is hidden and its checkbox unchecked out of the box. Comment now matches, and states why the two halves stay consistent.
+  - **Docs.** CLAUDE.md, `docs/architecture-invariants.md` and `docs/usage-limits-display-plan.md` updated for the new default and the single-resolver rule; the stale `styles.css` comment claiming the server strips the chip's hidden class at render was corrected (display is per-device, so the client reveals it).
+  - **`xterm-zerolag-input` README rework** (0.1.5 shipped the content; this republishes with the graphic and promo changes): replaced the misaligned 8-line keystroke-flow diagram with a two-line stock-vs-zerolag contrast, added a Codeman callout above the demo GIF with links to getcodeman.com and the repo, and rewrote the Origin section so it argues the extraction story instead of repeating the promo.
+
+## 0.1.5
+
+### Patch Changes
+
+- Rewrite the `xterm-zerolag-input` package README as a value-first document and correct the drift that had accumulated against the source.
+  - Added the side-by-side phone demo GIF (`docs/images/zerolag-demo-20260728.gif`) as the hero image, referenced by absolute raw URL so it renders on npmjs.com as well as GitHub. The two-phone comparison shows 0ms local echo next to a 600ms-2.7s server echo on the same session.
+  - New "Why this one" comparison table, an explicit list of target use cases (SSH web clients, cloud IDEs, mobile terminals, container consoles), and a bundle-size badge (6.1 kB gzipped, measured from the ESM build).
+  - Corrected the test-count badge from 78 to the actual 175 tests across 5 files, in both the package README and the Published Packages section of the root README.
+  - Removed the stale "Unicode/emoji rendered at single-cell width" limitation. CJK, fullwidth forms and emoji have had double-width rendering and visual-column positioning since the wide-character fix; the honest remaining caveat (per-code-point width summing over-counts ZWJ grapheme clusters) replaces it.
+  - Documented the previously undocumented public `setPrompt()` method for switching prompt strategies at runtime, and the new "Wide characters (CJK, emoji)" integration section covering the optional `Unicode11Addon` path and the built-in range-table fallback.
+  - Documented `backgroundColor: 'transparent'`, corrected the `foregroundColor` default, and updated the grid-alignment math to reflect visual-column positioning rather than character index.
+
+  No source changes, docs only.
+
 ## 0.1.4
 
 ### Patch Changes

packages/xterm-zerolag-input/README.md

@@ -1,45 +1,64 @@
 <p align="center">
   <h1 align="center">xterm-zerolag-input</h1>
   <p align="center">
-    Instant keystroke feedback overlay for <a href="https://xtermjs.org/">xterm.js</a><br>
-    <em>Eliminates perceived input latency over high-RTT connections</em>
+    <strong>Make typing feel instant in <a href="https://xtermjs.org/">xterm.js</a>, no matter how far away the server is.</strong><br>
+    <em>A pixel-perfect local echo overlay. Client-side only. Zero dependencies.</em>
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/xterm-zerolag-input"><img src="https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e" alt="npm"></a>
     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="MIT"></a>
-    <img src="https://img.shields.io/badge/Dependencies-0-22c55e?style=flat-square" alt="Zero deps">
-    <img src="https://img.shields.io/badge/Tests-78-22c55e?style=flat-square" alt="78 tests">
-    <img src="https://img.shields.io/badge/xterm.js-v5%20%7C%20v7+-3b82f6?style=flat-square" alt="xterm.js">
+    <img src="https://img.shields.io/badge/Dependencies-0-22c55e?style=flat-square" alt="Zero dependencies">
+    <img src="https://img.shields.io/badge/Size-6.1%20kB%20gzip-22c55e?style=flat-square" alt="6.1 kB gzipped">
+    <img src="https://img.shields.io/badge/Tests-175-22c55e?style=flat-square" alt="175 tests">
+    <img src="https://img.shields.io/badge/xterm.js-v5%20%7C%20v7+-3b82f6?style=flat-square" alt="xterm.js v5 and v7+">
   </p>
 </p>
 
+> ### Made for [**Codeman**](https://getcodeman.com)
+>
+> This overlay is the local echo engine of [**Codeman**](https://github.com/Ark0N/Codeman), mission control for AI coding agents: run and monitor a dozen Claude Code, Codex, OpenCode and Gemini sessions at once, watch their subagents work in live floating windows, let them run autonomously overnight, and drive all of it from your phone.
+>
+> That last part is why this library exists. The demo below is a real Codeman session on two phones.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/zerolag-demo-20260728.gif" alt="Side-by-side phones typing into the same remote session: with zerolag the text appears at 0ms, without it every keystroke waits 600ms to 2.7s for the server echo" width="900">
+</p>
+
+<p align="center">
+  <em>Two phones, the same remote session, the same slow link.<br>
+  Left: the zerolag overlay paints every keystroke at <strong>0ms</strong>. Right: stock xterm.js waits <strong>600ms to 2.7s</strong> for the server to echo it back.</em>
+</p>
+
 ---
 
-## The Problem
+## The 30-second version
 
-When using xterm.js over a remote connection (SSH web clients, cloud IDEs, mobile terminals), every keystroke takes a full round-trip to the server before appearing on screen. At 100-500ms RTT, typing feels sluggish and unresponsive. Users type blind, make mistakes they can't see, and the experience feels broken.
-
-## The Solution
-
-`xterm-zerolag-input` renders typed characters **immediately** as a pixel-perfect DOM overlay positioned on the terminal's character grid. The overlay covers the terminal canvas at the prompt location, showing characters instantly while the server echo travels back. Once the server responds, the overlay seamlessly disappears and the real terminal text takes over.
+Over a remote connection, xterm.js shows you a character only after it has flown to the server and back. At 100-500ms RTT that reads as broken: you type ahead of the screen, you cannot see your typos, and you start pecking one key at a time to stay in sync.
 
 ```
-Keystroke Flow:
-                                    ┌─── DOM overlay (instant, 0ms)
-User types 'h' ─── onData('h') ───┤
-                                    └─── Your app sends to PTY ──→ Server
-                                                                      │
-Server echoes 'h' ←──────────────────────────────────────────────────┘
-         │                                                  (200-500ms RTT)
-         └──→ terminal.write('h') ──→ overlay.clear()
-              (server output replaces overlay — seamless transition)
+  stock xterm.js   keypress ─────── 300 ms ───────→ character appears
+  with zerolag     keypress → character appears  ·  echo lands later, unseen
 ```
 
-**No changes to your backend needed.** The addon is purely client-side.
+Same keystroke, same link. The only difference is who you wait for: the server, or nobody.
 
-## Origin
+`xterm-zerolag-input` paints your keystrokes **immediately**, as an absolutely-positioned DOM overlay locked to the terminal's character grid. The byte still goes to the PTY exactly as before, so nothing about your shell changes. When the server echo lands 300ms later, the overlay clears and the real terminal text takes over on the same pixels. The handoff is invisible.
 
-This library was extracted from [Codeman](https://github.com/Ark0N/Codeman), mission control for AI coding agents — multi-session management, real-time agent visualization, autonomous respawn loops, and a mobile-first web UI for Claude Code, OpenCode, and Codex. The local echo system was built to make mobile and remote access feel instant, then battle-tested across thousands of hours of real usage. After 3 deep code audits, it was extracted into this standalone library with 78 tests covering every state transition.
+**No backend changes. No protocol. No server support.** It is a client-side addon that never touches the wire.
+
+## Why this one
+
+| | |
+|---|---|
+| **Survives full-screen TUIs** | Ink, blessed, and friends repaint the whole screen constantly. The overlay is a separate DOM layer they cannot reach, so it does not get clobbered. |
+| **Pixel-matched to the canvas** | Each character is its own absolutely-positioned `<span>` at exact cell coordinates, so it does not drift out of the grid like normal DOM text flow. |
+| **Wide characters included** | CJK, fullwidth forms and emoji render double-width and position by visual column, using the terminal's Unicode addon when one is loaded. |
+| **Backspace that actually works** | A three-layer cascade (unsent, in-flight, already on screen) tells you exactly what to forward to the PTY, so editing works through any mix of typed, flushed and tab-completed text. |
+| **You keep control of input** | The addon never hooks `onData` for you. You decide what gets echoed and what gets forwarded, which is what makes char-at-a-time, buffered, and multi-session tab switching all possible. |
+| **Small and self-contained** | 6.1 kB gzipped, zero runtime dependencies, dual CJS/ESM with full type declarations. |
+| **Proven under load** | Extracted from [Codeman](https://getcodeman.com), hardened over thousands of hours of real remote and mobile usage, 175 tests over every state transition. |
+
+Built for anything that puts a terminal behind a network hop: SSH web clients, cloud IDEs, mobile terminals, Kubernetes and container consoles, remote agent dashboards, browser-based dev environments.
 
 ## Install
 
@@ -47,12 +66,9 @@ This library was extracted from [Codeman](https://github.com/Ark0N/Codeman), mis
 npm install xterm-zerolag-input
 ```
 
-- **Zero runtime dependencies**
-- Compatible with both `xterm` (pre-5.4) and `@xterm/xterm` (5.4+)
-- Dual CJS/ESM build with full TypeScript declarations
-- Works with canvas, WebGL, and DOM renderers
+Works with both `xterm` (pre-5.4) and `@xterm/xterm` (5.4+), and with the canvas, WebGL and DOM renderers.
 
-## Quick Start
+## Quick start
 
 ```typescript
 import { Terminal } from '@xterm/xterm';
@@ -61,7 +77,7 @@ import { ZerolagInputAddon } from 'xterm-zerolag-input';
 const terminal = new Terminal();
 terminal.open(document.getElementById('terminal')!);
 
-// 1. Create addon with your prompt character
+// 1. Create the addon with your prompt character
 const zerolag = new ZerolagInputAddon({
   prompt: { type: 'character', char: '$', offset: 2 },
 });
@@ -75,7 +91,7 @@ terminal.onData((data) => {
     ws.send(text + '\r');
   } else if (data === '\x7f') {
     const source = zerolag.removeChar();
-    if (source === 'flushed') ws.send(data); // only backspace text already in PTY
+    if (source === 'flushed') ws.send(data); // only backspace text already in the PTY
   } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
     zerolag.addChar(data);
   }
@@ -87,26 +103,29 @@ terminal.onWriteParsed(() => {
 });
 ```
 
-## Why This Is Hard
+That is the whole integration. Everything below is for tuning it.
 
-Most terminal UIs can't do local echo because:
+## Why this is hard
 
-1. **Buffer writes corrupt**: Frameworks like [Ink](https://github.com/vadimdemedes/ink) (React for terminals) redraw the entire screen on every state change. Writing directly to the terminal buffer gets immediately overwritten.
+Most terminal UIs cannot do local echo, for three reasons:
 
-2. **Cursor position lies**: In Ink, `buffer.cursorY` reflects internal state (near the status bar), not the visible prompt. You can't trust it.
+1. **Buffer writes get corrupted.** Frameworks like [Ink](https://github.com/vadimdemedes/ink) (React for terminals) redraw the entire screen on every state change. Anything written straight into the terminal buffer is overwritten immediately.
 
-3. **Font matching**: Canvas/WebGL renderers use their own text shaping. A DOM overlay must pixel-match the canvas grid — normal DOM text flow drifts due to sub-pixel glyph width differences.
+2. **Cursor position lies.** In Ink, `buffer.cursorY` reflects internal render state (often near a status bar), not the visible prompt. You cannot trust it.
 
-This library solves all three by:
-- Using a **DOM overlay** that Ink can't touch (separate z-index layer)
-- **Scanning the buffer** bottom-up for the prompt character instead of trusting cursor position
-- Rendering each character as an **absolutely-positioned `<span>`** at exact cell-grid coordinates
+3. **Fonts do not line up.** Canvas and WebGL renderers do their own text shaping. A DOM overlay has to pixel-match that grid, and normal DOM text flow drifts as sub-pixel glyph widths accumulate.
+
+This library answers all three:
+
+- a **DOM overlay** on its own z-index layer, which Ink cannot touch
+- **bottom-up buffer scanning** for the prompt instead of trusting the cursor
+- **one absolutely-positioned `<span>` per character** at exact cell-grid coordinates
 
 ---
 
-## Prompt Detection
+## Prompt detection
 
-The addon needs to know where user input starts. It scans the terminal buffer bottom-up for the prompt. Three strategies:
+The addon needs to know where user input starts. It scans the terminal buffer bottom-up. Three strategies:
 
 ### Character (default)
 
@@ -118,17 +137,17 @@ The addon needs to know where user input starts. It scans the terminal buffer bo
 { type: 'character', char: '%', offset: 2 }
 
 // Fish / Starship: ❯
-{ type: 'character', char: '\u276f', offset: 2 }
+{ type: 'character', char: '❯', offset: 2 }
 
 // Simple arrow: >
 { type: 'character', char: '>', offset: 2 }
 ```
 
-`offset` = characters between the prompt marker and where user input begins (e.g., `"$ "` = 2).
+`offset` = characters between the prompt marker and where user input begins (`"$ "` = 2).
 
 ### Regex
 
-For complex prompts. The `g` flag is safely stripped to prevent `lastIndex` mutation.
+For complex prompts. The `g` flag is stripped safely, so there is no `lastIndex` mutation.
 
 ```typescript
 { type: 'regex', pattern: /\$\s*$/, offset: 2 }
@@ -150,77 +169,88 @@ Full control:
 }
 ```
 
+### Switching prompts at runtime
+
+If one terminal hosts several CLIs with different prompts, swap the strategy in place:
+
+```typescript
+zerolag.setPrompt({ type: 'character', char: '❯', offset: 2 });
+```
+
+`setPrompt()` clears the cached prompt position and re-renders if anything is pending, so a mode switch cannot leave the overlay pinned to the old column.
+
 ---
 
-## API Reference
+## API reference
 
 ### `ZerolagInputAddon`
 
-Implements xterm.js `ITerminalAddon`. The addon does **not** hook `terminal.onData()` — you wire your own input handler and call these methods. This gives you full control over which keystrokes are echoed vs forwarded.
+Implements the xterm.js `ITerminalAddon` interface. It deliberately does **not** hook `terminal.onData()`: you wire your own handler and call these methods, which is what gives you control over which keystrokes are echoed and which are forwarded.
 
 ### Input
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `addChar(char)` | `void` | Add a single printable character. Auto-detects existing buffer text on first keystroke. |
+| `addChar(char)` | `void` | Add a single printable character. Auto-detects existing buffer text on the first keystroke. |
 | `appendText(text)` | `void` | Append multiple characters (paste). |
-| `removeChar()` | `'pending'` \| `'flushed'` \| `false` | Remove last char. See [backspace handling](#backspace-handling). |
-| `clear()` | `void` | Clear all state, hide overlay. Call on Enter/Ctrl+C/Escape. |
+| `removeChar()` | `'pending'` \| `'flushed'` \| `false` | Remove the last character. See [backspace handling](#backspace-handling). |
+| `clear()` | `void` | Clear all state and hide the overlay. Call on Enter, Ctrl+C, Escape. |
 
-### Backspace Handling
+### Backspace handling
 
 `removeChar()` cascades through three layers and tells you what it removed:
 
 | Return | Source | Your action |
 |--------|--------|-------------|
-| `'pending'` | Unsent text (never transmitted to PTY) | Do nothing |
-| `'flushed'` | Text already sent to PTY | Send `\x7f` backspace to PTY |
+| `'pending'` | Unsent text (never transmitted to the PTY) | Do nothing |
+| `'flushed'` | Text already sent to the PTY | Send `\x7f` to the PTY |
 | `false` | Nothing to remove | Do nothing |
 
-The cascade: pending text first, then flushed text, then auto-detect buffer text (handles tab completion). This means backspace "just works" through any combination of typed, flushed, and tab-completed text.
+The cascade order is pending text, then flushed text, then auto-detected buffer text (which is what makes backspace work after tab completion). Backspace "just works" across any combination of typed, in-flight and completed text.
 
-### Flushed Text
+### Flushed text
 
-"Flushed" = sent to PTY but echo hasn't arrived yet. Happens during tab switches and tab completion.
+"Flushed" means sent to the PTY but the echo has not arrived yet. This happens during tab switches and tab completion.
 
 | Method | Description |
 |--------|-------------|
-| `setFlushed(count, text, render?)` | Mark text as flushed. Pass `render=false` during tab-switch restore (buffer not loaded yet). |
+| `setFlushed(count, text, render?)` | Mark text as flushed. Pass `render=false` during tab-switch restore, when the buffer is not loaded yet. |
 | `getFlushed()` | Returns `{ count, text }`. |
-| `clearFlushed()` | Clear flushed state when server echo arrives. |
+| `clearFlushed()` | Clear flushed state once the server echo arrives. |
 
-### Buffer Detection
+### Buffer detection
 
-Scan the terminal for text that exists after the prompt but wasn't typed through the overlay.
+Finds text that exists after the prompt but was never typed through the overlay.
 
 | Method | Description |
 |--------|-------------|
-| `detectBufferText()` | Scan and return detected text (or `null`). Sets it as flushed. Guarded: runs once per `clear()` cycle. |
+| `detectBufferText()` | Scan and return the detected text (or `null`), marking it flushed. Guarded: runs once per `clear()` cycle. |
 | `resetBufferDetection()` | Re-enable detection. |
-| `suppressBufferDetection()` | Block detection until next `clear()`. Use for sessions with UI framework text after the prompt. |
-| `undoDetection()` | Undo last detection — clears flushed state, re-enables detection. For tab completion retry. |
+| `suppressBufferDetection()` | Block detection until the next `clear()`. Use for sessions that render UI framework text after the prompt. |
+| `undoDetection()` | Undo the last detection: clears flushed state and re-enables detection. For tab-completion retries. |
 
 ### Rendering
 
 | Method | Description |
 |--------|-------------|
-| `rerender()` | Force re-render. Call after buffer reloads, screen redraws, resizes, reconnects. |
-| `refreshFont()` | Re-cache font properties from terminal. Call after font size or theme changes. |
+| `rerender()` | Force a re-render. Call after buffer reloads, screen redraws, resizes and reconnects. |
+| `refreshFont()` | Re-cache font and color properties from the terminal. Call after a font size or theme change. |
 
-### Prompt Utilities
+### Prompt
 
 | Method | Description |
 |--------|-------------|
-| `findPrompt()` | Find prompt position. Returns `{ row, col }` or `null`. |
-| `readPromptText()` | Read text after prompt marker. Returns string or `null`. |
+| `setPrompt(finder)` | Replace the prompt detection strategy at runtime. |
+| `findPrompt()` | Find the prompt position. Returns `{ row, col }` or `null`. |
+| `readPromptText()` | Read the text after the prompt marker. Returns a string or `null`. |
 
 ### State
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `pendingText` | `string` | Unacknowledged text (read-only) |
-| `hasPending` | `boolean` | `true` if overlay has any content |
-| `state` | `ZerolagInputState` | Full snapshot: pendingText, flushedLength, flushedText, visible, promptPosition |
+| `hasPending` | `boolean` | `true` if the overlay has any content |
+| `state` | `ZerolagInputState` | Full snapshot: `pendingText`, `flushedLength`, `flushedText`, `visible`, `promptPosition` |
 
 ### Options
 
@@ -228,23 +258,23 @@ Scan the terminal for text that exists after the prompt but wasn't typed through
 {
   prompt?: PromptFinder,       // Default: { type: 'character', char: '>', offset: 2 }
   zIndex?: number,             // Default: 7
-  backgroundColor?: string,    // Default: from terminal theme
-  foregroundColor?: string,    // Default: from computed .xterm-rows style
+  backgroundColor?: string,    // Default: terminal theme background ('transparent' to disable)
+  foregroundColor?: string,    // Default: terminal theme / computed .xterm-rows style
   showCursor?: boolean,        // Default: true
-  cursorColor?: string,        // Default: from terminal theme
+  cursorColor?: string,        // Default: terminal theme cursor
   scrollDebounceMs?: number,   // Default: 50
 }
 ```
 
 ---
 
-## Integration Patterns
+## Integration patterns
 
-### Buffered Input (hold until Enter)
+### Buffered input (hold until Enter)
 
-The quick start example above. Characters accumulate in the overlay and are sent on Enter. Best for remote shells where you want to batch input.
+The quick start above. Characters accumulate in the overlay and go out on Enter. Best for remote shells where you want to batch input.
 
-### Char-at-a-Time (send immediately)
+### Char-at-a-time (send immediately)
 
 ```typescript
 terminal.onData((data) => {
@@ -256,12 +286,14 @@ terminal.onData((data) => {
     ws.send(data);
   } else if (data.length === 1 && data.charCodeAt(0) >= 32) {
     zerolag.addChar(data);
-    ws.send(data); // send immediately — overlay shows while echo travels back
+    ws.send(data); // overlay shows the char while the echo travels back
   }
 });
 ```
 
-### Tab Switching (multi-session)
+This is the mode that keeps shell features intact: tab completion, `Ctrl+R` history search, and readline bindings all still work, because every byte still reaches the PTY.
+
+### Tab switching (multi-session)
 
 ```typescript
 function switchToSession(newId: string) {
@@ -280,19 +312,19 @@ function switchToSession(newId: string) {
   const saved = savedState.get(newId);
   if (saved) zerolag.setFlushed(saved.count, saved.text, false); // silent
 
-  // Render after buffer loads
+  // Render after the buffer loads
   terminal.write('', () => zerolag.rerender());
 }
 ```
 
-### Tab Completion
+### Tab completion
 
 ```typescript
 const baseline = zerolag.readPromptText();
 zerolag.clear();
 sendToPty('\t');
 
-// After response:
+// After the response:
 zerolag.resetBufferDetection();
 const detected = zerolag.detectBufferText();
 if (detected && detected !== baseline) {
@@ -302,7 +334,7 @@ if (detected && detected !== baseline) {
 }
 ```
 
-### Resize / Font / Reconnect
+### Resize, font, reconnect
 
 ```typescript
 fitAddon.fit();
@@ -311,14 +343,31 @@ zerolag.rerender();
 terminal.options.fontSize = 18;
 zerolag.refreshFont();
 
-function onReconnect() { zerolag.rerender(); }
+function onReconnect() {
+  zerolag.rerender();
+}
 ```
 
+### Wide characters (CJK, emoji)
+
+Wide characters work out of the box: the overlay measures each character's cell width, renders double-width spans for wide ones, and positions later characters by visual column instead of character index. Line wrapping is computed in columns too, so a wrapped Japanese or Chinese line lands on the same cells the server will use.
+
+For exact Unicode 11+ widths, load xterm's Unicode addon and the overlay will defer to it:
+
+```typescript
+import { Unicode11Addon } from '@xterm/addon-unicode11';
+
+terminal.loadAddon(new Unicode11Addon());
+terminal.unicode.activeVersion = '11';
+```
+
+Without it, a built-in range table covers Hangul, Kana, CJK Unified (including Ext A through G), fullwidth forms and the emoji planes.
+
 ---
 
-## How It Works
+## How it works
 
-### DOM Structure
+### DOM structure
 
 ```
 div.xterm-screen (position: relative)
@@ -326,53 +375,61 @@ div.xterm-screen (position: relative)
   ├── div.xterm-selection (z-index: 1)
   ├── div.xterm-helpers (z-index: 5)
   ├── div.xterm-decoration-container (z-index: 6-7)
-  └── div[zerolag overlay] (z-index: 7)  ← our overlay (invisible to Ink)
+  └── div[zerolag overlay] (z-index: 7)  ← our overlay, invisible to Ink
 ```
 
-### Per-Character Grid Alignment
+### Per-character grid alignment
 
 Each character is an absolutely-positioned `<span>`:
 
 ```
-left  = charIndex * cellWidth   (CSS pixels)
-top   = lineIndex * cellHeight  (CSS pixels)
-width = cellWidth               (exact cell width)
+left  = visualColumn * cellWidth   (CSS pixels)
+top   = lineIndex    * cellHeight  (CSS pixels)
+width = cellWidth * charCellWidth  (1 cell, or 2 for wide characters)
 ```
 
-This avoids sub-pixel drift from normal DOM text flow.
+Positioning by visual column instead of letting the browser lay out text is what removes sub-pixel drift.
 
-### Font Matching
+### Font matching
 
 1. `fontFamily`, `fontSize`, `fontWeight` from `terminal.options`
-2. `letterSpacing` from computed style of `.xterm-rows`
-3. `-webkit-font-smoothing: antialiased` (matches canvas grayscale)
+2. `letterSpacing` from the computed style of `.xterm-rows`
+3. `-webkit-font-smoothing: antialiased` (matches canvas grayscale AA)
 4. `font-feature-settings: 'liga' 0, 'calt' 0` (no ligatures)
 5. `text-rendering: geometricPrecision`
 
-### Cell Dimensions
+### Cell dimensions
 
 - **xterm.js v5.x**: `terminal._core._renderService.dimensions.css.cell` (private API)
 - **xterm.js v7+**: `terminal.dimensions.css.cell` (public API, auto-detected)
 
-### Prompt Column Locking
+### Prompt column locking
 
-When flushed text exists, the prompt column is locked to prevent jitter from full-screen redraws. Row changes are allowed (output can scroll the prompt).
+While flushed text exists the prompt column is locked, so a full-screen redraw cannot make the overlay jitter sideways. Row changes are still allowed, because output legitimately scrolls the prompt.
 
-### Scroll Awareness
+### Scroll awareness
 
-Overlay hides when scrolled up (`viewportY !== baseY`). Debounced re-render when scrolling back to bottom.
+The overlay hides when the viewport is scrolled up (`viewportY !== baseY`) and re-renders, debounced, when you scroll back to the bottom.
 
 ---
 
-## Known Limitations
+## Known limitations
 
-- **Canvas/WebGL font mismatch**: Minor sub-pixel differences possible. Per-character absolute positioning minimizes this.
-- **Unicode/emoji**: Multi-byte characters occupy variable cell widths — rendered at single-cell width, causing misalignment.
-- **Password prompts**: Overlay shows characters that aren't echoed. Call `clear()` when you detect no-echo mode.
-- **Prompt in output**: If `$` appears in command output, prompt detection may find the wrong position. Use regex or custom finder.
+- **Canvas and WebGL font mismatch**: minor sub-pixel differences are still possible. Per-character absolute positioning keeps them small.
+- **Grapheme clusters**: widths are summed per code point, so ZWJ emoji sequences (for example 👨‍👩‍👧) and combining marks can be over-counted. Single-code-point emoji and CJK are correct.
+- **Password prompts**: the overlay will happily show characters the server is not echoing. Call `clear()` when you detect a no-echo prompt.
+- **Prompt characters in output**: if your prompt marker also appears in command output, detection can latch onto the wrong line. Use a regex or a custom finder.
 
 ---
 
+## Origin
+
+[Codeman](https://getcodeman.com) needed this before anyone else did. A coding agent you drive from your phone over a tunnel is unusable if every keystroke costs a round trip.
+
+So the overlay was built there, ran in production for thousands of hours, and survived three deep code audits before being pulled out into this standalone library with its tests intact. Nothing was reimplemented for the extraction: the engine here is the one Codeman ships.
+
+Want the whole thing? [**getcodeman.com**](https://getcodeman.com) · [github.com/Ark0N/Codeman](https://github.com/Ark0N/Codeman)
+
 ## License
 
-MIT — [Codeman](https://github.com/Ark0N/Codeman) Contributors
+MIT, [Codeman](https://github.com/Ark0N/Codeman) Contributors

packages/xterm-zerolag-input/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xterm-zerolag-input",
-  "version": "0.1.4",
-  "description": "Instant keystroke feedback overlay for xterm.js — eliminates perceived input latency over high-RTT connections",
+  "version": "0.1.8",
+  "description": "Instant keystroke feedback overlay for xterm.js: Mosh-inspired local echo that removes perceived input latency over SSH, tunnels and other high-RTT connections",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -26,8 +26,16 @@
     "xterm",
     "xterm.js",
     "terminal",
+    "web-terminal",
     "local-echo",
+    "local echo",
+    "mosh",
     "input-latency",
+    "latency",
+    "zero-lag",
+    "keystroke",
+    "ssh",
+    "remote-terminal",
     "overlay",
     "addon"
   ],

scripts/build-agent-image.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Build the Codeman agent base image locally (decision: "build locally on first
+ * use", see docs/docker-cases-plan.md). No registry account required.
+ *
+ * Usage:
+ *   node scripts/build-agent-image.mjs [--engine docker|podman] [--image <ref>] [--no-cache]
+ *
+ * Defaults: engine=docker (falls back to podman if docker is absent),
+ *           image=codeman/agent:base
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..');
+const DOCKERFILE = join(REPO_ROOT, 'docker', 'agent.Dockerfile');
+const DEFAULT_IMAGE = 'codeman/agent:base';
+
+function parseArgs(argv) {
+  const args = { image: DEFAULT_IMAGE, engine: undefined, noCache: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--image') args.image = argv[++i];
+    else if (a === '--engine') args.engine = argv[++i];
+    else if (a === '--no-cache') args.noCache = true;
+    else if (a === '-h' || a === '--help') args.help = true;
+  }
+  return args;
+}
+
+function engineAvailable(engine) {
+  const r = spawnSync(engine, ['--version'], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+function resolveEngine(preferred) {
+  if (preferred) {
+    if (!engineAvailable(preferred)) {
+      console.error(`[build-agent-image] engine "${preferred}" not found on PATH`);
+      process.exit(1);
+    }
+    return preferred;
+  }
+  if (engineAvailable('docker')) return 'docker';
+  if (engineAvailable('podman')) return 'podman';
+  console.error('[build-agent-image] neither docker nor podman found on PATH. Install one and retry.');
+  process.exit(1);
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  console.log('Usage: node scripts/build-agent-image.mjs [--engine docker|podman] [--image <ref>] [--no-cache]');
+  process.exit(0);
+}
+
+const engine = resolveEngine(args.engine);
+const buildArgs = ['build', '-f', DOCKERFILE, '-t', args.image];
+if (args.noCache) buildArgs.push('--no-cache');
+buildArgs.push(REPO_ROOT);
+
+console.log(`[build-agent-image] ${engine} ${buildArgs.join(' ')}`);
+const child = spawn(engine, buildArgs, { stdio: 'inherit' });
+child.on('exit', (code) => {
+  if (code === 0) {
+    console.log(`\n[build-agent-image] built ${args.image}. Docker cases can now launch.`);
+  } else {
+    console.error(`\n[build-agent-image] build failed (exit ${code}).`);
+  }
+  process.exit(code ?? 1);
+});

scripts/build.mjs

@@ -67,6 +67,7 @@ appendFileSync(
 
 // 4. Minify frontend assets
 run('minify input-cjk.js', 'npx esbuild dist/web/public/input-cjk.js --minify --outfile=dist/web/public/input-cjk.js --allow-overwrite');
+run('minify i18n.js', 'npx esbuild dist/web/public/i18n.js --minify --outfile=dist/web/public/i18n.js --allow-overwrite');
 run('minify sanitize-html.js', 'npx esbuild dist/web/public/sanitize-html.js --minify --outfile=dist/web/public/sanitize-html.js --allow-overwrite');
 run('minify app.js', 'npx esbuild dist/web/public/app.js --minify --outfile=dist/web/public/app.js --allow-overwrite');
 run('minify terminal-ui.js', 'npx esbuild dist/web/public/terminal-ui.js --minify --outfile=dist/web/public/terminal-ui.js --allow-overwrite');
@@ -86,6 +87,7 @@ console.log('\n[build] content-hash cache busting');
     'styles.css',
     'mobile.css',
     'constants.js',
+    'i18n.js',
     'mobile-handlers.js',
     'voice-input.js',
     'notification-manager.js',

scripts/capture-readme-gifs.mjs

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+
+/**
+ * capture-readme-gifs.mjs
+ *
+ * Deterministic README GIFs — no real server, Claude CLI, or tmux. Reuses the
+ * mock-injection pipeline from capture-readme-screenshots.mjs (static file
+ * server + page.route mocks), drives a scripted timeline in the page, records
+ * it with Playwright video, and converts to GIF via ffmpeg palette encoding.
+ *
+ * Scenes:
+ *   1. subagent-demo.gif  — terminal spawns 3 parallel agents; floating agent
+ *      windows open one by one and stream tool-call activity live (driven
+ *      through the real _onSubagentDiscovered/_onSubagentToolCall handlers).
+ *   2. zerolag-demo.gif   — side-by-side typing: instant local echo (zerolag)
+ *      vs bursty ~350 ms server echo, rendered with the vendored xterm.
+ *
+ * Usage:  node scripts/capture-readme-gifs.mjs
+ *         SCREENSHOT_OUT_DIR=/path/to/review node scripts/capture-readme-gifs.mjs
+ * Output: docs/images/ (or flat into SCREENSHOT_OUT_DIR)
+ * Requires: ffmpeg
+ */
+
+import { chromium } from 'playwright';
+import { execSync } from 'child_process';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  PORT,
+  SESSION_IDS,
+  STANDARD_SESSIONS,
+  buildInitPayload,
+  startStaticServer,
+  setupRoutes,
+  injectState,
+  outPath,
+  RST, GRN, YEL, MAG, CYN, GRY, BOLD,
+} from './capture-readme-screenshots.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const GIF_COLORS = 192;
+
+// ─── ffmpeg conversion (palette recipe from capture-subagent-gif.mjs) ────────
+
+function webmToGif(videoPath, gifPath, { ss, duration, width, fps }) {
+  // One GLOBAL palette (default stats_mode=full) + ordered dither: per-frame
+  // palettes (stats_mode=single:new=1) make dirty rectangles visibly mismatch
+  // on flat dark UI, and error-diffusion dither shimmers between frames.
+  const filters = `fps=${fps},scale=${width}:-1:flags=lanczos`;
+  execSync(
+    `ffmpeg -y -loglevel error -ss ${ss.toFixed(2)} -t ${duration} -i "${videoPath}" ` +
+      `-vf "${filters},split[s0][s1];[s0]palettegen=max_colors=${GIF_COLORS}:reserve_transparent=0[p];` +
+      `[s1][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" "${gifPath}"`,
+    { stdio: 'inherit' }
+  );
+}
+
+// ─── Scene 1: subagent demo ──────────────────────────────────────────────────
+
+const SUBAGENT_VIEWPORT = { width: 1440, height: 810 };
+
+// Terminal content visible before the agents spawn
+const TERMINAL_PRESPAWN = [
+  '',
+  `${GRN}●${RST} Working on ${CYN}/home/arkon/codeman-cases/testcase${RST} - I'll use the ${BOLD}Task tool${RST} to spawn parallel agents.`,
+  '',
+  `${GRN}●${RST} ${BOLD}Read${RST}(/home/arkon/codeman-cases/testcase/CLAUDE.md)`,
+  `  ${GRY}░${RST} Read ${BOLD}127${RST} lines ${GRY}│${RST} ${CYN}1.2KB${RST}`,
+  '',
+  `${GRN}●${RST} ${BOLD}Bash${RST}(find . -name "*.ts" -not -path "*/node_modules/*" | head -20)`,
+  `  ${GRY}░${RST} ./src/index.ts`,
+  `  ${GRY}░${RST} ./src/session.ts`,
+  `  ${GRY}░${RST} ./src/web/server.ts`,
+  `  ${GRY}░${RST} ${GRY}... (17 more)${RST}`,
+  '',
+  `${GRN}●${RST} I'll spawn 3 parallel research agents to analyze different parts of the codebase simultaneously.`,
+  '',
+].join('\r\n');
+
+function makeAgent(agentId, description, startedOffsetMs) {
+  return {
+    agentId,
+    sessionId: 'claude-sess-w1-0001',
+    projectHash: 'abc123',
+    filePath: `/tmp/${agentId}.jsonl`,
+    startedAt: new Date(Date.now() - startedOffsetMs).toISOString(),
+    lastActivityAt: Date.now(),
+    status: 'active',
+    toolCallCount: 0,
+    entryCount: 0,
+    fileSize: 4000,
+    description,
+    model: 'claude-haiku-4-5-20251001',
+    modelShort: 'haiku',
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    parentSessionId: SESSION_IDS.w1,
+  };
+}
+
+// Timeline events: t (ms from scene start) + kind
+//   term     — write raw data to the session terminal
+//   discover — register subagent + open + position its floating window
+//   tool     — stream a tool call into an agent window
+//   msg      — stream an assistant message into an agent window
+//   complete — flip an agent to completed
+function buildSubagentTimeline() {
+  const T = (lines) => lines.join('\r\n') + '\r\n';
+  const tool = (t, agentId, name, input) => ({ t, kind: 'tool', agentId, tool: name, input });
+  const msg = (t, agentId, text) => ({ t, kind: 'msg', agentId, text });
+
+  return [
+    {
+      t: 600,
+      kind: 'term',
+      data: T([
+        `${GRN}●${RST} ${BOLD}Task${RST}(Find and document all API endpoints in src/)`,
+        `  ${GRY}░${RST} Spawned ${CYN}agent-001${RST} ${GRY}(haiku)${RST}`,
+        '',
+      ]),
+    },
+    {
+      t: 1000,
+      kind: 'discover',
+      agent: makeAgent('agent-001', 'Find and document all API endpoints in src/', 2000),
+      x: 440, y: 45,
+    },
+    tool(1500, 'agent-001', 'Glob', { pattern: 'src/**/*.ts' }),
+    {
+      t: 2000,
+      kind: 'term',
+      data: T([
+        `${GRN}●${RST} ${BOLD}Task${RST}(Explore and understand test structure in test/)`,
+        `  ${GRY}░${RST} Spawned ${CYN}agent-002${RST} ${GRY}(haiku)${RST}`,
+        '',
+      ]),
+    },
+    tool(2200, 'agent-001', 'Read', { file_path: '/home/arkon/codeman/src/web/server.ts' }),
+    {
+      t: 2500,
+      kind: 'discover',
+      agent: makeAgent('agent-002', 'Explore and understand test structure in test/', 1200),
+      x: 880, y: 45,
+    },
+    tool(3000, 'agent-002', 'Glob', { pattern: 'test/**/*.test.ts' }),
+    {
+      t: 3300,
+      kind: 'term',
+      data: T([
+        `${GRN}●${RST} ${BOLD}Task${RST}(Analyze TypeScript type definitions in src/types.ts)`,
+        `  ${GRY}░${RST} Spawned ${CYN}agent-003${RST} ${GRY}(haiku)${RST}`,
+        '',
+      ]),
+    },
+    tool(3500, 'agent-001', 'Grep', { pattern: 'app\\.get|app\\.post|app\\.delete', path: 'src/' }),
+    {
+      t: 3800,
+      kind: 'discover',
+      agent: makeAgent('agent-003', 'Analyze TypeScript type definitions in src/types.ts', 400),
+      x: 660, y: 400,
+    },
+    tool(4100, 'agent-002', 'Read', { file_path: '/home/arkon/codeman/test/respawn-test-utils.ts' }),
+    {
+      t: 4500,
+      kind: 'term',
+      data: T([
+        `${MAG}✻${RST} ${YEL}Waiting for agents...${RST} ${GRY}(${BOLD}esc${RST}${GRY} to interrupt · 32s · ↓ 1.7k tokens · thinking)${RST}`,
+        '',
+      ]),
+    },
+    tool(4700, 'agent-003', 'Read', { file_path: '/home/arkon/codeman/src/types.ts' }),
+    tool(5200, 'agent-001', 'Read', { file_path: '/home/arkon/codeman/src/web/schemas.ts' }),
+    tool(5600, 'agent-002', 'Read', { file_path: '/home/arkon/codeman/config/vitest.config.ts' }),
+    tool(6100, 'agent-003', 'Grep', { pattern: 'export (interface|type)', path: 'src/types/' }),
+    msg(6700, 'agent-001', 'Found 47 API endpoints across server.ts. Documenting REST paths...'),
+    tool(7100, 'agent-002', 'Grep', { pattern: 'const PORT =', path: 'test/' }),
+    msg(7700, 'agent-002', 'Analyzing test patterns: MockSession, unique ports, fileParallelism: false...'),
+    tool(8100, 'agent-003', 'Read', { file_path: '/home/arkon/codeman/src/types/index.ts' }),
+    msg(8700, 'agent-003', 'Mapped 38 exported interfaces across 15 domain files. Building summary...'),
+    {
+      t: 9300,
+      kind: 'term',
+      data: T([
+        `${GRN}●${RST} ${CYN}agent-001${RST}: ${GRY}12 tool calls — Glob, Read(server.ts), Grep(endpoints)...${RST}`,
+        `${GRN}●${RST} ${CYN}agent-002${RST}: ${GRY}8 tool calls — Glob, Read(test-utils), Read(vitest.config)...${RST}`,
+        `${GRN}●${RST} ${CYN}agent-003${RST}: ${GRY}7 tool calls — Read(types.ts), Grep(interface)...${RST}`,
+        '',
+      ]),
+    },
+    tool(10100, 'agent-001', 'Glob', { pattern: 'src/web/routes/*.ts' }),
+    tool(10600, 'agent-002', 'Read', { file_path: '/home/arkon/codeman/test/setup.ts' }),
+    tool(11100, 'agent-003', 'Grep', { pattern: 'assertNever', path: 'src/' }),
+    {
+      t: 11600,
+      kind: 'term',
+      data: T([`${GRN}●${RST} ${GRY}171.8k, 13s${RST} ${GRY}│${RST} ${GRY}1.7k tokens${RST} ${GRY}│${RST} ${GRY}thinking${RST}`, '']),
+    },
+  ];
+}
+
+const SUBAGENT_TAIL_HOLD = 2500; // hold the final frame
+
+async function recordSubagentScene(browser, videoDir) {
+  console.log('\n1/2 Recording subagent-demo...');
+
+  const context = await browser.newContext({
+    viewport: SUBAGENT_VIEWPORT,
+    deviceScaleFactor: 1,
+    recordVideo: { dir: videoDir, size: SUBAGENT_VIEWPORT },
+  });
+  const recStart = Date.now();
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+
+  // Start with NO subagents — they appear during the recording
+  const initPayload = buildInitPayload(STANDARD_SESSIONS);
+  await setupRoutes(page, initPayload, TERMINAL_PRESPAWN);
+  await page.goto(`http://localhost:${PORT}`, { waitUntil: 'domcontentloaded' });
+  await injectState(page, initPayload, TERMINAL_PRESPAWN, SESSION_IDS.w1);
+
+  await page.evaluate(() => {
+    try { window.app?.fitAddon?.fit(); } catch {}
+    window.app?.terminal?.scrollToBottom();
+  });
+  await sleep(500);
+
+  const timeline = buildSubagentTimeline();
+  const totalMs = Math.max(...timeline.map((e) => e.t)) + SUBAGENT_TAIL_HOLD;
+  const sceneStart = Date.now();
+
+  // Run the whole timeline inside the page so events interleave naturally
+  await page.evaluate((events) => {
+    const app = window.app;
+    for (const ev of events) {
+      setTimeout(() => {
+        try {
+          if (ev.kind === 'term') {
+            app.terminal.write(ev.data);
+            app.terminal.scrollToBottom();
+          } else if (ev.kind === 'discover') {
+            app._onSubagentDiscovered(ev.agent);
+            app.openSubagentWindow(ev.agent.agentId);
+            // The spawn animation (400ms) lands on the auto-grid; glide to our tile after it
+            setTimeout(() => {
+              const win = app.subagentWindows.get(ev.agent.agentId);
+              if (win?.element) {
+                win.element.style.transition = 'left 0.25s ease, top 0.25s ease';
+                win.element.style.left = `${ev.x}px`;
+                win.element.style.top = `${ev.y}px`;
+              }
+            }, 520);
+            setTimeout(() => {
+              const win = app.subagentWindows.get(ev.agent.agentId);
+              if (win?.element) win.element.style.transition = '';
+              app.updateConnectionLines();
+            }, 850);
+          } else if (ev.kind === 'tool') {
+            app._onSubagentToolCall({
+              agentId: ev.agentId,
+              tool: ev.tool,
+              input: ev.input,
+              timestamp: new Date().toISOString(),
+            });
+          } else if (ev.kind === 'msg') {
+            app._onSubagentMessage({
+              agentId: ev.agentId,
+              role: 'assistant',
+              text: ev.text,
+              timestamp: new Date().toISOString(),
+            });
+          } else if (ev.kind === 'complete') {
+            app._onSubagentCompleted({ agentId: ev.agentId, timestamp: new Date().toISOString() });
+          }
+        } catch (err) {
+          console.error('timeline event failed', ev, err);
+        }
+      }, ev.t);
+    }
+  }, timeline);
+
+  await sleep(totalMs + 500);
+
+  await page.close();
+  const videoPath = await page.video().path();
+  await context.close();
+
+  return {
+    videoPath,
+    ss: (sceneStart - recStart) / 1000 - 0.4,
+    duration: (totalMs + 400) / 1000,
+  };
+}
+
+// ─── Scene 2: zerolag typing comparison ──────────────────────────────────────
+
+const ZEROLAG_VIEWPORT = { width: 1280, height: 470 };
+const TYPED_TEXT = 'echo "zero lag typing from anywhere"';
+const TYPE_INTERVAL_MS = 110;
+const REMOTE_FLUSH_MS = 350; // server-echo pane flushes queued chars in bursts
+const ZEROLAG_TAIL_HOLD = 1800;
+
+const ZEROLAG_HTML = `<!DOCTYPE html>
+<html>
+<head>
+<link rel="stylesheet" href="http://localhost:${PORT}/vendor/xterm.css">
+<script src="http://localhost:${PORT}/vendor/xterm.min.js"></script>
+<style>
+  * { margin: 0; box-sizing: border-box; }
+  body {
+    width: 1280px; height: 470px; background: #0a0a0c;
+    display: flex; align-items: center; justify-content: center; gap: 48px;
+    font-family: -apple-system, 'Segoe UI', Roboto, sans-serif;
+  }
+  .pane { width: 560px; }
+  .card {
+    background: #131316; border: 1px solid rgba(255,255,255,0.08);
+    border-radius: 10px; overflow: hidden;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.45);
+  }
+  .card-head {
+    display: flex; align-items: baseline; gap: 10px;
+    padding: 12px 16px; border-bottom: 1px solid rgba(255,255,255,0.06);
+  }
+  .dot { width: 9px; height: 9px; border-radius: 50%; align-self: center; }
+  .title { font-size: 15px; font-weight: 600; color: #e8e8ea; }
+  .sub { font-size: 12.5px; color: #8b8b92; }
+  .term { padding: 16px 8px 12px 16px; height: 165px; }
+  .good .dot { background: #22c55e; box-shadow: 0 0 8px rgba(34,197,94,0.7); }
+  .bad  .dot { background: #ef4444; box-shadow: 0 0 8px rgba(239,68,68,0.7); }
+  .tag {
+    margin-top: 14px; text-align: center; font-size: 14.5px; color: #7e7e86;
+  }
+  .tag b { color: #22c55e; font-weight: 600; }
+  .bad-tag b { color: #ef4444; }
+</style>
+</head>
+<body>
+  <div class="pane">
+    <div class="card good">
+      <div class="card-head">
+        <span class="dot"></span>
+        <span class="title">With zerolag-input</span>
+        <span class="sub">instant local echo</span>
+      </div>
+      <div class="term" id="termLeft"></div>
+    </div>
+    <div class="tag">keystrokes echo in <b>0 ms</b></div>
+  </div>
+  <div class="pane">
+    <div class="card bad">
+      <div class="card-head">
+        <span class="dot"></span>
+        <span class="title">Without</span>
+        <span class="sub">server round-trip echo</span>
+      </div>
+      <div class="term" id="termRight"></div>
+    </div>
+    <div class="tag bad-tag">keystrokes echo after <b>~350 ms</b></div>
+  </div>
+</body>
+</html>`;
+
+async function recordZerolagScene(browser, videoDir) {
+  console.log('\n2/2 Recording zerolag-demo...');
+
+  const context = await browser.newContext({
+    viewport: ZEROLAG_VIEWPORT,
+    deviceScaleFactor: 1,
+    recordVideo: { dir: videoDir, size: ZEROLAG_VIEWPORT },
+  });
+  const recStart = Date.now();
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+
+  await page.setContent(ZEROLAG_HTML, { waitUntil: 'load' });
+  await page.waitForFunction(() => typeof Terminal !== 'undefined');
+
+  await page.evaluate(() => {
+    const theme = {
+      background: '#131316',
+      foreground: '#e8e8ea',
+      cursor: '#22c55e',
+      cursorAccent: '#131316',
+    };
+    const mk = (id) => {
+      const term = new Terminal({
+        cols: 44,
+        rows: 5,
+        fontSize: 20,
+        fontFamily: "'SF Mono', 'Cascadia Code', Menlo, monospace",
+        cursorBlink: true,
+        cursorStyle: 'block',
+        theme,
+      });
+      term.open(document.getElementById(id));
+      term.write('\x1b[32m❯\x1b[0m ');
+      return term;
+    };
+    window.termLeft = mk('termLeft');
+    window.termRight = mk('termRight');
+  });
+  await sleep(600);
+
+  const sceneStart = Date.now();
+  const typingMs = TYPED_TEXT.length * TYPE_INTERVAL_MS;
+  const totalMs = typingMs + REMOTE_FLUSH_MS + ZEROLAG_TAIL_HOLD;
+
+  await page.evaluate(
+    ({ text, interval, flushEvery }) => {
+      let i = 0;
+      const remoteQueue = [];
+      const typer = setInterval(() => {
+        if (i >= text.length) { clearInterval(typer); return; }
+        const ch = text[i++];
+        window.termLeft.write(ch); // local echo: instant
+        remoteQueue.push(ch); // server echo: waits for the round-trip
+      }, interval);
+      const flusher = setInterval(() => {
+        if (remoteQueue.length) window.termRight.write(remoteQueue.splice(0).join(''));
+        if (i >= text.length && remoteQueue.length === 0) clearInterval(flusher);
+      }, flushEvery);
+    },
+    { text: TYPED_TEXT, interval: TYPE_INTERVAL_MS, flushEvery: REMOTE_FLUSH_MS }
+  );
+
+  await sleep(totalMs + 400);
+
+  await page.close();
+  const videoPath = await page.video().path();
+  await context.close();
+
+  return {
+    videoPath,
+    ss: (sceneStart - recStart) / 1000 - 0.6, // small lead-in with idle cursors
+    duration: (totalMs + 600) / 1000,
+  };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('Codeman README GIF Capture');
+  console.log('='.repeat(60));
+
+  const server = await startStaticServer();
+  const videoDir = mkdtempSync(join(tmpdir(), 'codeman-gifs-'));
+  let browser;
+
+  try {
+    browser = await chromium.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+    });
+
+    const sub = await recordSubagentScene(browser, videoDir);
+    const subGif = outPath('images', 'subagent-demo.gif');
+    webmToGif(sub.videoPath, subGif, { ss: Math.max(0, sub.ss), duration: sub.duration, width: 960, fps: 8 });
+    console.log(`  Saved: ${subGif}`);
+
+    const zl = await recordZerolagScene(browser, videoDir);
+    const zlGif = outPath('images', 'zerolag-demo.gif');
+    webmToGif(zl.videoPath, zlGif, { ss: Math.max(0, zl.ss), duration: zl.duration, width: 900, fps: 10 });
+    console.log(`  Saved: ${zlGif}`);
+
+    console.log('\nDone.');
+  } catch (err) {
+    console.error('\nFatal error:', err.message);
+    console.error(err.stack);
+    process.exitCode = 1;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    server.close();
+    rmSync(videoDir, { recursive: true, force: true });
+  }
+}
+
+process.on('SIGINT', () => process.exit(1));
+
+main();

scripts/capture-readme-real.mjs

@@ -50,7 +50,10 @@ 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;
         if (planUsage) blob.showPlanUsageLimits = true;
         localStorage.setItem('codeman-app-settings', JSON.stringify(blob));
       } catch {
@@ -136,9 +139,9 @@ async function sceneSubagent(browser) {
   const sessions = await listSessions(page);
   const targetId = process.env.SUBAGENT_SID || (sessions.find((s) => s.mode === 'claude') || sessions[0])?.id;
   if (targetId) await page.evaluate((id) => window.app.selectSession(id), targetId);
-  // Wait (up to ~25s) for live subagents to arrive via SSE into app.subagents.
+  // Wait (up to ~45s) for live subagents to arrive via SSE into app.subagents.
   let agents = [];
-  for (let i = 0; i < 25; i++) {
+  for (let i = 0; i < 45; i++) {
     agents = await page.evaluate(() =>
       Array.from(window.app.subagents?.entries?.() || []).map(([id, a]) => ({ id, name: a.name ?? a.agentType ?? '' }))
     );
@@ -151,6 +154,44 @@ async function sceneSubagent(browser) {
     await context.close();
     return;
   }
+  // The window body renders from app.subagentActivity, which fills ONLY from live
+  // SSE tool-call/progress events — a fresh client never gets past activity replayed.
+  // So sit connected and wait for live activity to accumulate, then open the two
+  // agents that actually have content (otherwise the windows read "No activity yet").
+  let active = [];
+  for (let i = 0; i < 100; i++) {
+    active = await page.evaluate(() =>
+      Array.from(window.app.subagentActivity?.entries?.() || [])
+        .filter(([, arr]) => Array.isArray(arr) && arr.length >= 1)
+        .map(([id, arr]) => ({ id, n: arr.length }))
+        .sort((a, b) => b.n - a.n)
+    );
+    if (active.length >= 2) break;
+    // xhigh-effort agents churn in bursts between long thinking pauses, so be
+    // patient (~150s); accept a single populated window after ~45s if that's all.
+    if (i >= 30 && active.length >= 1) break;
+    await sleep(1500);
+  }
+  console.log('  agents with live activity:', JSON.stringify(active));
+  const openIds = (active.length ? active : agents).map((a) => a.id);
+  // Capture-only DOM nudge: on fresh dev sessions, a tab's claudeSessionId stays the
+  // Codeman id and never becomes the real Claude conversation UUID, so the window
+  // open-gate (claudeSessionId === agent.sessionId) + the activeTabOnly hide rule both
+  // fail. Re-home the chosen agents onto the active tab and align its claudeSessionId
+  // to the agents' (shared) sessionId so the windows open AND show their live activity.
+  await page.evaluate(
+    (ids) => {
+      const activeId = window.app.activeSessionId;
+      const tab = window.app.sessions.get(activeId);
+      ids.slice(0, 2).forEach((id) => {
+        const a = window.app.subagents.get(id);
+        if (!a) return;
+        a.parentSessionId = activeId;
+        if (tab && a.sessionId) tab.claudeSessionId = a.sessionId;
+      });
+    },
+    openIds
+  );
   await page.evaluate(
     (ids) => {
       ids.slice(0, 2).forEach((id) => {
@@ -159,22 +200,33 @@ async function sceneSubagent(browser) {
         } catch {}
       });
     },
-    agents.map((a) => a.id)
+    openIds
   );
   await sleep(2000);
   await page.evaluate(() => {
+    // Viewport-relative tiling: center two subagent windows over the terminal so
+    // the layout adapts to whatever VW/VH the capture uses (e.g. the HQ 1100×650
+    // recipe) instead of overflowing at narrower widths.
     const wins = Array.from(window.app.subagentWindows.values());
-    const place = [
-      { left: 360, top: 60, w: 430, h: 330 },
-      { left: 810, top: 60, w: 430, h: 330 },
-    ];
+    const W = window.innerWidth;
+    const H = window.innerHeight;
+    const winW = Math.min(440, Math.floor((W - 60) / 2 - 10));
+    const winH = Math.min(360, Math.floor(H * 0.56));
+    const top = Math.floor(H * 0.16);
+    const gap = 16;
+    const totalW = winW * 2 + gap;
+    const startLeft = Math.max(16, Math.floor((W - totalW) / 2));
     wins.slice(0, 2).forEach((win, i) => {
       const el = win.element;
-      const p = place[i];
-      el.style.left = p.left + 'px';
-      el.style.top = p.top + 'px';
-      el.style.width = p.w + 'px';
-      el.style.height = p.h + 'px';
+      // Force visible: a freshly opened window may be hidden by the activeTabOnly
+      // rule before we override it (we also seed subagentActiveTabOnly:false).
+      win.hidden = false;
+      win.minimized = false;
+      el.style.display = 'flex';
+      el.style.left = startLeft + i * (winW + gap) + 'px';
+      el.style.top = top + 'px';
+      el.style.width = winW + 'px';
+      el.style.height = winH + 'px';
     });
   });
   await sleep(1500);

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

scripts/fix-node-pty.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Repairs node-pty's macOS `spawn-helper` and verifies that a PTY
+ * can really be spawned. Called by `scripts/postinstall.js` on every install and
+ * exposed as `npm run fix:node-pty` for repairing an install after the fact.
+ *
+ * Why this exists (issues #6 and #204):
+ *
+ * node-pty@1.1.0 publishes its macOS prebuilt helper as
+ * `prebuilds/darwin-<arch>/spawn-helper` with mode 0644, i.e. no execute bit.
+ * On macOS node-pty launches every PTY through that helper with posix_spawnp,
+ * which then fails EACCES and surfaces as `Error: posix_spawnp failed.` on every
+ * session start.
+ *
+ * It is macOS-exclusive twice over: `spawn-helper` is an `OS=="mac"` gyp target,
+ * and pty.cc only spawns it under `#if defined(__APPLE__)`. node-pty ships
+ * prebuilds for darwin and win32 only, so Linux always compiles from source
+ * (which produces an executable helper) and never sees the bug.
+ *
+ * The repair is a chmod, NOT a rebuild: the prebuilt binary itself is fine, and
+ * requiring a from-source rebuild would make every macOS install depend on Xcode
+ * command line tools. A rebuild is attempted only when a chmod plus a real spawn
+ * probe still can't get a working PTY, and the prebuilds tree is backed up first
+ * so a failed rebuild can never leave the install worse than it started.
+ */
+
+import { chmodSync, cpSync, existsSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** Errors that mean "the native module or its helper is unusable", i.e. worth a rebuild. */
+const NATIVE_FAILURE_PATTERN = /posix_spawnp|spawn-helper|Failed to load native module|Cannot find module/i;
+
+/**
+ * Locates the installed node-pty package directory.
+ *
+ * @returns {string|null} Absolute path to the package root, or null if not installed.
+ */
+export function findNodePtyDir() {
+    // package.json first: node-pty declares no "exports" map, so the subpath resolves,
+    // and it lands on the package root directly. require.resolve('node-pty') would give
+    // <pkg>/lib/index.js, which is one directory deeper than callers expect.
+    try {
+        return dirname(require.resolve('node-pty/package.json'));
+    } catch {
+        /* fall through */
+    }
+    try {
+        return join(dirname(require.resolve('node-pty')), '..');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Lists every `spawn-helper` shipped in a node-pty install.
+ *
+ * node-pty's own loader (lib/utils.js) checks `build/Release`, `build/Debug` and
+ * then `prebuilds/<platform>-<arch>`, and takes the helper from whichever
+ * directory the native module loaded out of, so all of them must be executable,
+ * not just the one this machine happens to use today.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {string[]} Absolute paths of the helpers that exist on disk.
+ */
+export function listSpawnHelpers(ptyDir) {
+    const dirs = [join(ptyDir, 'build', 'Release'), join(ptyDir, 'build', 'Debug')];
+
+    const prebuilds = join(ptyDir, 'prebuilds');
+    if (existsSync(prebuilds)) {
+        try {
+            for (const entry of readdirSync(prebuilds, { withFileTypes: true })) {
+                if (entry.isDirectory()) dirs.push(join(prebuilds, entry.name));
+            }
+        } catch {
+            /* unreadable prebuilds dir: nothing to repair there */
+        }
+    }
+
+    return dirs.map((d) => join(d, 'spawn-helper')).filter((p) => existsSync(p));
+}
+
+/**
+ * Adds the execute bit to every `spawn-helper` that is missing it.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {{ repaired: string[], failed: Array<{ path: string, error: string }> }}
+ */
+export function repairSpawnHelpers(ptyDir) {
+    const repaired = [];
+    const failed = [];
+
+    for (const helper of listSpawnHelpers(ptyDir)) {
+        try {
+            const mode = statSync(helper).mode & 0o777;
+            if ((mode & 0o111) === 0o111) continue; // already executable by all
+            chmodSync(helper, mode | 0o755);
+            repaired.push(helper);
+        } catch (err) {
+            failed.push({ path: helper, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+
+    return { repaired, failed };
+}
+
+/**
+ * Proves node-pty works by actually opening a PTY, which is the only check that
+ * exercises the spawn-helper path that breaks. A `require` alone would pass on a
+ * broken install, because the helper is only touched at spawn time.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @returns {{ ok: boolean, error?: string, nativeFailure?: boolean }}
+ */
+export function verifyPtySpawn(ptyDir) {
+    let child;
+    try {
+        const pty = require(ptyDir); // directory require → node-pty's "main" (lib/index.js)
+        const file = process.platform === 'win32' ? process.env.COMSPEC || 'cmd.exe' : '/bin/echo';
+        const args = process.platform === 'win32' ? ['/c', 'exit'] : ['codeman-node-pty-check'];
+        child = pty.spawn(file, args, {
+            name: 'xterm-color',
+            cols: 80,
+            rows: 24,
+            cwd: tmpdir(),
+            env: process.env,
+        });
+        return { ok: true };
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: message, nativeFailure: NATIVE_FAILURE_PATTERN.test(message) };
+    } finally {
+        try {
+            child?.kill();
+        } catch {
+            /* the probe child exits on its own anyway */
+        }
+    }
+}
+
+/**
+ * Rebuilds node-pty from source, preserving the prebuilds tree across a failure.
+ *
+ * node-pty's install script deletes `prebuilds/` as soon as
+ * `npm_config_build_from_source` is set and only then shells out to node-gyp, so
+ * a machine without a compiler toolchain would otherwise be left with neither a
+ * prebuilt nor a compiled binary.
+ *
+ * @param {string} ptyDir Absolute path to the node-pty package root.
+ * @param {string} cwd Directory to run npm from (the package root that owns node_modules).
+ * @returns {{ ok: boolean, error?: string }}
+ */
+function rebuildFromSource(ptyDir, cwd) {
+    const prebuilds = join(ptyDir, 'prebuilds');
+    const backup = join(ptyDir, '.prebuilds-codeman-backup');
+
+    let backedUp = false;
+    if (existsSync(prebuilds)) {
+        try {
+            rmSync(backup, { recursive: true, force: true });
+            cpSync(prebuilds, backup, { recursive: true });
+            backedUp = true;
+        } catch {
+            /* best effort: proceed without a safety net rather than skip the repair */
+        }
+    }
+
+    try {
+        execSync('npm rebuild node-pty --build-from-source', { cwd, stdio: 'pipe', timeout: 300000 });
+        return { ok: true };
+    } catch (err) {
+        if (backedUp && !existsSync(prebuilds)) {
+            try {
+                cpSync(backup, prebuilds, { recursive: true });
+            } catch {
+                /* nothing further we can do */
+            }
+        }
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    } finally {
+        rmSync(backup, { recursive: true, force: true });
+    }
+}
+
+/**
+ * Full repair flow: chmod, verify, and only rebuild if a working PTY still can't
+ * be opened.
+ *
+ * @param {object} [options]
+ * @param {(line: string) => void} [options.log] Progress sink (default: silent).
+ * @param {(line: string) => void} [options.warn] Warning sink (default: same as log).
+ * @param {boolean} [options.allowRebuild] Permit a from-source rebuild (default: true).
+ * @returns {Promise<{ ok: boolean, repaired: string[], rebuilt: boolean, reason?: string }>}
+ */
+export async function fixNodePty(options = {}) {
+    const log = options.log ?? (() => {});
+    const warn = options.warn ?? log;
+    const allowRebuild = options.allowRebuild ?? true;
+
+    const ptyDir = findNodePtyDir();
+    if (!ptyDir) {
+        return { ok: false, repaired: [], rebuilt: false, reason: 'node-pty is not installed' };
+    }
+
+    const { repaired, failed } = repairSpawnHelpers(ptyDir);
+    for (const f of failed) warn(`could not chmod ${f.path}: ${f.error}`);
+    if (repaired.length > 0) {
+        log(`made node-pty spawn-helper executable (${repaired.length} file${repaired.length === 1 ? '' : 's'})`);
+    }
+
+    const first = verifyPtySpawn(ptyDir);
+    if (first.ok) return { ok: true, repaired, rebuilt: false };
+
+    if (!allowRebuild || !first.nativeFailure) {
+        return { ok: false, repaired, rebuilt: false, reason: first.error };
+    }
+
+    warn(`node-pty could not open a PTY (${first.error}), rebuilding from source...`);
+    const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+    const rebuild = rebuildFromSource(ptyDir, projectRoot);
+    if (!rebuild.ok) {
+        return { ok: false, repaired, rebuilt: false, reason: `rebuild failed: ${rebuild.error}` };
+    }
+
+    const after = repairSpawnHelpers(ptyDir);
+    repaired.push(...after.repaired);
+
+    const second = verifyPtySpawn(ptyDir);
+    return second.ok
+        ? { ok: true, repaired, rebuilt: true }
+        : { ok: false, repaired, rebuilt: true, reason: second.error };
+}
+
+// ---------------------------------------------------------------------------
+// CLI: node scripts/fix-node-pty.mjs [--quiet]
+// ---------------------------------------------------------------------------
+
+const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isDirectRun) {
+    const quiet = process.argv.includes('--quiet');
+    const say = (line) => {
+        if (!quiet) console.log(line);
+    };
+
+    const result = await fixNodePty({ log: say, warn: (line) => console.warn(line) });
+
+    if (result.ok) {
+        say(result.repaired.length > 0 || result.rebuilt ? 'node-pty repaired, PTY spawning works' : 'node-pty is healthy');
+        process.exit(0);
+    }
+
+    console.error(`node-pty is not usable: ${result.reason}`);
+    console.error('Try:  cd node_modules/node-pty && npx node-gyp rebuild');
+    process.exit(1);
+}

scripts/postinstall.js

@@ -6,7 +6,7 @@
  */
 
 import { execSync, spawn } from 'child_process';
-import { chmodSync, existsSync } from 'fs';
+import { existsSync } from 'fs';
 import { homedir, platform } from 'os';
 import { join } from 'path';
 import { createRequire } from 'module';
@@ -148,35 +148,32 @@ if (majorVersion < MIN_NODE_VERSION) {
 }
 
 // ----------------------------------------------------------------------------
-// 1b. Fix node-pty spawn-helper permissions (macOS posix_spawnp fix)
+// 1b. Repair + verify node-pty (macOS posix_spawnp fix, issues #6 and #204)
+//
+// node-pty ships its macOS spawn-helper without the execute bit, which breaks
+// every session start on macOS. fixNodePty() chmods it, then proves a PTY can
+// actually be opened, and only falls back to a from-source rebuild if that
+// still fails. See scripts/fix-node-pty.mjs for the full story.
 // ----------------------------------------------------------------------------
 
 try {
-    const require = createRequire(import.meta.url);
-    const ptyPath = join(require.resolve('node-pty'), '..');
-    const spawnHelper = join(ptyPath, 'build', 'Release', 'spawn-helper');
-    if (existsSync(spawnHelper)) {
-        chmodSync(spawnHelper, 0o755);
-        console.log(colors.green('✓ node-pty spawn-helper permissions fixed'));
-    }
-} catch {
-    // Non-critical — only affects macOS with prebuilt binaries
-}
+    const { fixNodePty } = await import('./fix-node-pty.mjs');
+    const result = await fixNodePty({
+        log: (line) => console.log(colors.dim(`  ${line}`)),
+        warn: (line) => console.log(colors.yellow(`⚠ ${line}`)),
+    });
 
-// ----------------------------------------------------------------------------
-// 1c. Rebuild node-pty from source for Node.js 22+ compatibility
-// ----------------------------------------------------------------------------
-
-if (majorVersion >= 22) {
-    try {
-        console.log(colors.dim('  Rebuilding node-pty from source for Node.js 22+...'));
-        execSync('npm rebuild node-pty --build-from-source', { stdio: 'pipe', timeout: 120000 });
-        console.log(colors.green('✓ node-pty rebuilt from source'));
-    } catch {
+    if (result.ok) {
+        console.log(colors.green('✓ node-pty verified') + colors.dim(' (PTY spawn works)'));
+    } else {
         hasWarnings = true;
-        console.log(colors.yellow('⚠ Failed to rebuild node-pty from source'));
-        console.log(colors.dim('  You may need to run: npm rebuild node-pty --build-from-source'));
+        console.log(colors.yellow(`⚠ node-pty is not usable: ${result.reason}`));
+        console.log(colors.dim('  Sessions will fail to start. Try: ') + colors.cyan('npm run fix:node-pty'));
     }
+} catch (err) {
+    hasWarnings = true;
+    console.log(colors.yellow(`⚠ Could not verify node-pty: ${err.message}`));
+    console.log(colors.dim('  If sessions fail to start, run: ') + colors.cyan('npm run fix:node-pty'));
 }
 
 // ----------------------------------------------------------------------------

src/attachment-magic.ts

@@ -3,11 +3,52 @@
  */
 
 import { isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { isSupportedAttachmentExtension } from './attachment-registry.js';
+import { stripAnsi } from './utils/index.js';
 
 const MAGIC_LINK_RE = /codeman:\/\/attach\?([^\s<>"']+)/g;
+const CODEX_SAVED_FILE_RE = /\bSaved to:\s*(file:\/\/[^\s<>"']+)/gi;
+
+export interface TerminalAttachmentRequest {
+  path: string;
+  source: 'external' | 'codex-generated';
+}
+
+export interface ParseTerminalAttachmentOptions {
+  /**
+   * Enable the Codex `Saved to: file://...` scanner. Only codex-mode sessions
+   * may set this — the relaxed codex-generated trust policy must never be
+   * reachable from other modes' (prompt-injectable) terminal output.
+   */
+  codexArtifacts?: boolean;
+}
 
 export function parseAttachmentMagicLinks(data: string): string[] {
+  return parseMagicAttachmentRequests(data).map((request) => request.path);
+}
+
+export function parseTerminalAttachmentRequests(
+  data: string,
+  options: ParseTerminalAttachmentOptions = {}
+): TerminalAttachmentRequest[] {
+  const results: TerminalAttachmentRequest[] = [];
+  const seen = new Set<string>();
+  const requests = options.codexArtifacts
+    ? [...parseMagicAttachmentRequests(data), ...parseCodexGeneratedArtifactRequests(data)]
+    : parseMagicAttachmentRequests(data);
+
+  for (const request of requests) {
+    const key = `${request.source}:${request.path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    results.push(request);
+  }
+
+  return results;
+}
+
+function parseMagicAttachmentRequests(data: string): TerminalAttachmentRequest[] {
   const results: string[] = [];
   const seen = new Set<string>();
 
@@ -27,6 +68,31 @@ export function parseAttachmentMagicLinks(data: string): string[] {
     }
   }
 
+  return results.map((path) => ({ path, source: 'external' }));
+}
+
+function parseCodexGeneratedArtifactRequests(data: string): TerminalAttachmentRequest[] {
+  const results: TerminalAttachmentRequest[] = [];
+  const seen = new Set<string>();
+
+  // Codex styles its TUI output — strip ANSI first so a trailing SGR reset
+  // (e.g. `...mockup.png\x1b[0m`) doesn't ride into the captured URL and break
+  // the extension allowlist check.
+  for (const match of stripAnsi(data).matchAll(CODEX_SAVED_FILE_RE)) {
+    const rawUrl = trimTrailingPunctuation(match[1] || '');
+    try {
+      const filePath = fileURLToPath(rawUrl);
+      if (!isAbsolute(filePath)) continue;
+      const extension = filePath.split('.').pop()?.toLowerCase() || '';
+      if (!isSupportedAttachmentExtension(extension)) continue;
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      results.push({ path: filePath, source: 'codex-generated' });
+    } catch {
+      // Ignore malformed terminal text. Generated-artifact links are advisory.
+    }
+  }
+
   return results;
 }
 

src/attachment-registry.ts

@@ -14,7 +14,18 @@ import { isBlockedAttachmentPath, loadAttachmentGuardConfig } from './config/att
 import { validateSessionFilePath } from './web/route-helpers.js';
 import type { AttachmentDetectedEvent, AttachmentDetectedType } from './types.js';
 
-const SUPPORTED_ATTACHMENT_EXTENSIONS = new Set(['png', 'pdf', 'docx', 'pptx', 'md', 'txt']);
+const SUPPORTED_ATTACHMENT_EXTENSIONS = new Set([
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'pdf',
+  'docx',
+  'pptx',
+  'md',
+  'txt',
+]);
 
 export type AttachmentSource = 'detected' | 'external';
 
@@ -96,7 +107,7 @@ export function isSupportedAttachmentExtension(extension: string): boolean {
 
 export function getAttachmentType(extension: string): AttachmentDetectedType {
   const normalized = extension.toLowerCase().replace(/^\./, '');
-  if (normalized === 'png') return 'image';
+  if (['png', 'jpg', 'jpeg', 'gif', 'webp'].includes(normalized)) return 'image';
   if (normalized === 'pdf') return 'pdf';
   if (normalized === 'pptx') return 'presentation';
   if (normalized === 'md') return 'markdown';

src/cli.ts

@@ -584,7 +584,11 @@ program
     '--allow-unauthenticated-network',
     'Allow non-loopback web access without CODEMAN_PASSWORD (dangerous; terminal control is exposed)'
   )
+  .option('--multiuser', 'Enable opt-in multi-user mode (named users in ~/.codeman/users.json; env: CODEMAN_MULTIUSER)')
   .action(async (options) => {
+    // The flag is surfaced to the rest of the process via the env var so
+    // isMultiUserMode() has a single source of truth (see config/multiuser.ts).
+    if (options.multiuser) process.env.CODEMAN_MULTIUSER = '1';
     const { startWebServer } = await import('./web/server.js');
     const host = options.host;
     const port = parseInt(options.port, 10);
@@ -626,6 +630,168 @@ program
     }
   });
 
+// ============ Multi-user Commands ============
+//
+// Operate directly on ~/.codeman/users.json (via user-store) with NO running
+// server, honoring CODEMAN_INSTANCE. This is the headless bootstrap path and the
+// recovery answer to "locked out: last admin forgot password".
+
+/** Read a password from stdin without echoing. Falls back to plain read on non-TTY. */
+function promptHiddenPassword(question: string): Promise<string> {
+  const stdin = process.stdin;
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+    // Non-interactive: read a single line from stdin.
+    return new Promise((resolve) => {
+      let buf = '';
+      stdin.setEncoding('utf8');
+      stdin.on('data', (d) => (buf += d));
+      stdin.on('end', () => resolve(buf.replace(/\r?\n$/, '')));
+    });
+  }
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    let input = '';
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    const onData = (chunk: string) => {
+      for (const c of chunk) {
+        if (c === '\n' || c === '\r' || c === '\u0004') {
+          stdin.setRawMode!(false);
+          stdin.pause();
+          stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          resolve(input);
+          return;
+        } else if (c === '\u0003') {
+          process.stdout.write('\n');
+          process.exit(1);
+        } else if (c === '\u007f' || c === '\b') {
+          input = input.slice(0, -1);
+        } else {
+          input += c;
+        }
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function readAllStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => (buf += d));
+    process.stdin.on('end', () => resolve(buf.replace(/\r?\n$/, '')));
+  });
+}
+
+const usersCmd = program.command('users').description('Manage multi-user accounts (~/.codeman/users.json)');
+
+usersCmd
+  .command('add <name>')
+  .description('Create a user (prompts for password; use --password-stdin for scripts)')
+  .option('--admin', 'Create as an admin')
+  .option('--password-stdin', 'Read the password from stdin instead of prompting')
+  .action(async (name, options) => {
+    const { createUser, isValidUsername } = await import('./user-store.js');
+    if (!isValidUsername(name)) {
+      console.error(chalk.red('✗ Username must be lowercase, start alphanumeric, 2-32 chars ([a-z0-9_-])'));
+      process.exit(1);
+    }
+    try {
+      let password: string;
+      if (options.passwordStdin) {
+        password = await readAllStdin();
+      } else {
+        password = await promptHiddenPassword('New password: ');
+        const confirm = await promptHiddenPassword('Confirm password: ');
+        if (password !== confirm) {
+          console.error(chalk.red('✗ Passwords do not match'));
+          process.exit(1);
+        }
+      }
+      if (!password || password.length < 8) {
+        console.error(chalk.red('✗ Password must be at least 8 characters'));
+        process.exit(1);
+      }
+      const user = await createUser({ username: name, role: options.admin ? 'admin' : 'user', password });
+      console.log(chalk.green(`✓ Created ${user.role} "${user.username}"`));
+    } catch (err) {
+      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      process.exit(1);
+    }
+  });
+
+usersCmd
+  .command('passwd <name>')
+  .description('Reset a user password')
+  .option('--password-stdin', 'Read the new password from stdin instead of prompting')
+  .action(async (name, options) => {
+    const { setPassword } = await import('./user-store.js');
+    try {
+      let password: string;
+      if (options.passwordStdin) {
+        password = await readAllStdin();
+      } else {
+        password = await promptHiddenPassword('New password: ');
+        const confirm = await promptHiddenPassword('Confirm password: ');
+        if (password !== confirm) {
+          console.error(chalk.red('✗ Passwords do not match'));
+          process.exit(1);
+        }
+      }
+      await setPassword(name, password, { mustChangePassword: false });
+      console.log(chalk.green(`✓ Password updated for "${name}"`));
+    } catch (err) {
+      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      process.exit(1);
+    }
+  });
+
+usersCmd
+  .command('list')
+  .alias('ls')
+  .description('List all users')
+  .action(async () => {
+    const { readUsers } = await import('./user-store.js');
+    const users = await readUsers(true);
+    if (users.length === 0) {
+      console.log(chalk.yellow('No users defined (run: codeman users add <name> --admin)'));
+      return;
+    }
+    console.log(chalk.bold('\nUsers:'));
+    for (const u of users) {
+      const role = u.role === 'admin' ? chalk.magenta('admin') : chalk.cyan('user ');
+      const state = u.disabled ? chalk.red('disabled') : chalk.green('enabled ');
+      const flags = [u.mustChangePassword ? 'must-change-pw' : '', u.canBypassPermissions ? 'can-bypass' : '']
+        .filter(Boolean)
+        .join(' ');
+      console.log(`  ${role} ${state} ${u.username}${flags ? chalk.gray(`  [${flags}]`) : ''}`);
+    }
+    console.log('');
+  });
+
+usersCmd
+  .command('rm <name>')
+  .description('Delete a user')
+  .option('--delete-space', "Also delete the user's ~/codeman-users/<name> space")
+  .action(async (name, options) => {
+    const { deleteUser, deleteUserSpace } = await import('./user-store.js');
+    try {
+      await deleteUser(name);
+      if (options.deleteSpace) {
+        await deleteUserSpace(name);
+        console.log(chalk.green(`✓ Deleted user "${name}" and their space`));
+      } else {
+        console.log(chalk.green(`✓ Deleted user "${name}" (space left on disk)`));
+      }
+    } catch (err) {
+      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .alias('check-deps')

src/config/auth-config.ts

@@ -31,5 +31,10 @@ export const AUTH_FAILURE_WINDOW_MS = 15 * 60 * 1000;
 // Hooks
 // ============================================================================
 
-/** Timeout for Claude Code hook curl commands (ms) */
-export const HOOK_TIMEOUT_MS = 10000;
+/**
+ * Timeout for Claude Code hook curl commands, in SECONDS: the hook `timeout`
+ * field is seconds (the CLI multiplies by 1000). The predecessor constant
+ * `HOOK_TIMEOUT_MS = 10000` fed the same field, so those hooks effectively had a
+ * ~2.8-hour timeout; 10 seconds is the originally intended budget.
+ */
+export const HOOK_TIMEOUT_SECONDS = 10;

src/config/buffer-limits.ts

@@ -6,14 +6,15 @@
  * it easy to tune memory usage.
  *
  * Memory Budget Rationale (for 20 concurrent sessions):
- * - Terminal buffer: 2MB max × 20 = 40MB worst case
+ * - Terminal buffer: 32MB max × 20 = 640MB worst case
  * - Text output: 1MB max × 20 = 20MB worst case
  * - Messages: ~1KB each × 1000 × 20 = 20MB worst case
- * - Total buffer overhead: ~80MB (acceptable for long-running server)
  *
  * @module config/buffer-limits
  */
 
+import { DEFAULT_TERMINAL_BUFFER_MAX_BYTES, DEFAULT_TERMINAL_BUFFER_TRIM_BYTES } from './terminal-history.js';
+
 // ============================================================================
 // Terminal Buffer Limits
 // ============================================================================
@@ -21,17 +22,17 @@
 /**
  * Maximum terminal buffer size in characters.
  * Contains raw terminal output with ANSI escape sequences.
- * Reduced from 5MB to 2MB for better render performance.
+ * Sourced from terminal-history config (env/settings overridable).
  * Override: CODEMAN_MAX_TERMINAL_BUFFER (bytes)
  */
-export const MAX_TERMINAL_BUFFER_SIZE = parseInt(process.env.CODEMAN_MAX_TERMINAL_BUFFER || '') || 2 * 1024 * 1024;
+export const MAX_TERMINAL_BUFFER_SIZE = DEFAULT_TERMINAL_BUFFER_MAX_BYTES;
 
 /**
  * Size to trim terminal buffer to when max is exceeded.
  * Keeps the most recent portion to preserve context.
  * Override: CODEMAN_TRIM_TERMINAL_TO (bytes)
  */
-export const TRIM_TERMINAL_TO = parseInt(process.env.CODEMAN_TRIM_TERMINAL_TO || '') || 1.5 * 1024 * 1024;
+export const TRIM_TERMINAL_TO = DEFAULT_TERMINAL_BUFFER_TRIM_BYTES;
 
 // ============================================================================
 // Text Output Buffer Limits
@@ -96,3 +97,18 @@ export const TRIM_RESPAWN_BUFFER_TO = 512 * 1024; // 512KB
  * which is enough to extract metadata from the first few JSONL lines.
  */
 export const FILE_PEEK_BYTES = 8 * 1024 - 1; // 8KB (inclusive end offset)
+
+// ============================================================================
+// Paste-Image Upload Limits
+// ============================================================================
+
+/**
+ * Maximum size (bytes) of a single image uploaded via POST
+ * /api/sessions/:id/paste-image. The mobile picker / drag-drop / paste paths
+ * send one file per request (the client uploads up to MAX_PASTE_IMAGES of them
+ * per batch), so this caps each individual file, not the batch. Generous enough
+ * for full-resolution phone photos and large screenshots; the client downscales
+ * very large images before upload, so legitimate uploads land well under this.
+ * Override: CODEMAN_MAX_PASTE_IMAGE_BYTES (bytes)
+ */
+export const MAX_PASTE_IMAGE_BYTES = parseInt(process.env.CODEMAN_MAX_PASTE_IMAGE_BYTES || '') || 50 * 1024 * 1024; // 50MB

src/config/dependency-registry.ts

@@ -90,6 +90,22 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
     usedBy: ['Codex sessions'],
     resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['codex'], versionArg: '--version' } }],
   },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Gemini sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['gemini'], versionArg: '--version' } }],
+  },
+  {
+    id: 'antigravity',
+    label: 'Antigravity CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Antigravity sessions'],
+    resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['agy'], versionArg: '--version' } }],
+  },
   {
     id: 'libreoffice',
     label: 'LibreOffice',

src/config/map-limits.ts

@@ -43,6 +43,19 @@ export const MAX_SSE_CLIENTS = 100;
  */
 export const MAX_TODOS_PER_SESSION = 500;
 
+/**
+ * Maximum cron-job run-history records retained across all jobs. Oldest runs
+ * (by startedAt) are pruned when exceeded — bounds state.json growth from
+ * frequently-firing or perpetually-skipped jobs.
+ */
+export const MAX_CRON_RUN_HISTORY = 500;
+
+/**
+ * Maximum saved cron jobs. Jobs persist to state.json, so an unbounded count
+ * would grow it without limit; creation past the cap is rejected with 400.
+ */
+export const MAX_CRON_JOBS = 100;
+
 // ============================================================================
 // Pending Tool Calls Limits
 // ============================================================================

src/config/multiuser.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Multi-user mode gating + limits (opt-in, off by default).
+ *
+ * Multi-user mode is enabled by `codeman web --multiuser` (which sets
+ * `CODEMAN_MULTIUSER=1`) or the env var directly. When OFF, behavior is
+ * byte-identical to today: `users.json` is never read and all ownership scoping
+ * is bypassed. Everything here is per-instance like the rest of Codeman: a beta
+ * instance (`CODEMAN_INSTANCE=beta`) has its own `users.json` via `dataPath()`,
+ * and its user spaces live under the same shared `~/codeman-users` as prod (like
+ * `~/codeman-cases`), unless `CODEMAN_USER_SPACES_DIR` overrides it.
+ *
+ * See `docs/multi-user-plan.md` sections 3, 4.2, and 11.
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { MAX_CONCURRENT_SESSIONS } from './map-limits.js';
+
+/**
+ * Whether multi-user mode is active. Read from the environment each call so it is
+ * stable for the process lifetime (env does not change after boot) and trivially
+ * overridable in tests. Accepts `1` or `true`.
+ */
+export function isMultiUserMode(): boolean {
+  const v = process.env.CODEMAN_MULTIUSER;
+  return v === '1' || v === 'true';
+}
+
+/**
+ * Root of per-user spaces: `~/codeman-users` (sibling of `~/codeman-cases`).
+ * Overridable via `CODEMAN_USER_SPACES_DIR` (used by tests). Resolved lazily so a
+ * test can point it at a temp dir before the first call.
+ */
+export function getUserSpacesDir(): string {
+  return process.env.CODEMAN_USER_SPACES_DIR || join(homedir(), 'codeman-users');
+}
+
+/** Absolute path to a user's top-level space: `<USER_SPACES_DIR>/<username>[/segments]`. */
+export function userSpacePath(username: string, ...segments: string[]): string {
+  return join(getUserSpacesDir(), username, ...segments);
+}
+
+/** Absolute path to a user's cases dir: `<USER_SPACES_DIR>/<username>/cases`. */
+export function userCasesDir(username: string): string {
+  return join(getUserSpacesDir(), username, 'cases');
+}
+
+/** Maximum number of user accounts (default 25, env `CODEMAN_MAX_USERS`). */
+export function maxUsers(): number {
+  const n = Number(process.env.CODEMAN_MAX_USERS);
+  return Number.isInteger(n) && n > 0 ? n : 25;
+}
+
+/**
+ * Per-user concurrent-session cap (the fairness lever). Defaults to half the
+ * global cap; overridable via `CODEMAN_MAX_SESSIONS_PER_USER`. The global cap
+ * (MAX_CONCURRENT_SESSIONS) still applies on top and is shared across users.
+ */
+export function maxSessionsPerUser(): number {
+  const n = Number(process.env.CODEMAN_MAX_SESSIONS_PER_USER);
+  if (Number.isInteger(n) && n > 0) return n;
+  return Math.max(1, Math.floor(MAX_CONCURRENT_SESSIONS / 2));
+}

src/config/server-timing.ts

@@ -51,6 +51,19 @@ export const SCHEDULED_CLEANUP_INTERVAL = 5 * 60 * 1000;
 /** Completed scheduled run max age before cleanup (ms) */
 export const SCHEDULED_RUN_MAX_AGE = 60 * 60 * 1000;
 
+// ============================================================================
+// Cron Jobs
+// ============================================================================
+
+/** How often the cron loop wakes to check for due jobs (ms). */
+export const CRON_TICK_INTERVAL = 30 * 1000;
+
+/** Max attempts (× 500ms) to poll a launched session for CLI readiness before sending the prompt. */
+export const CRON_READY_MAX_ATTEMPTS = 60;
+
+/** Extra settle delay after CLI readiness is detected, before sending the prompt (ms). */
+export const CRON_READY_SETTLE_MS = 2000;
+
 /** Session limit retry wait before retrying (ms) */
 export const SESSION_LIMIT_WAIT_MS = 5000;
 

src/config/terminal-history.ts

@@ -0,0 +1,77 @@
+/**
+ * Defaults, bounds, and resolution for terminal history retention.
+ *
+ * Raised defaults (the ones actually wired):
+ * - tmux history-limit: 50,000 -> 100,000 lines (applied at session spawn)
+ * - server PTY buffer cap: 2MB max / 1.5MB trim -> 32MB / 24MB (via buffer-limits.ts)
+ * Browser xterm scrollback is a separate hardcoded DEFAULT_SCROLLBACK (50,000) in
+ * src/web/public/constants.js and deliberately stays at 50k — 100k xterm lines per tab
+ * is a mobile-memory hazard — so DEFAULT_TERMINAL_SCROLLBACK_LINES stays 50,000 to match.
+ * The terminalScrollbackLines/terminalBufferMaxBytes/terminalBufferTrimBytes settings keys
+ * remain schema-validated but inert (a follow-up wires them); only tmuxHistoryLimit is live.
+ * All values remain env- and settings-overridable and bounds-clamped via
+ * resolveTerminalHistoryConfig().
+ */
+
+export const DEFAULT_TERMINAL_SCROLLBACK_LINES = 50_000;
+export const DEFAULT_TMUX_HISTORY_LIMIT = 100_000;
+export const DEFAULT_TERMINAL_BUFFER_MAX_BYTES =
+  parseInt(process.env.CODEMAN_MAX_TERMINAL_BUFFER || '', 10) || 32 * 1024 * 1024;
+// Trim must stay below the max: BufferAccumulator.trim() keeps the last trimSize chars, so a
+// trim >= max never shrinks the buffer — every append then re-joins the whole string (O(n²))
+// and memory overshoots the operator's cap (e.g. CODEMAN_MAX_TERMINAL_BUFFER=2097152 with no
+// trim env would leave the 24MB trim default in force). Clamp to 75% of the resolved max,
+// preserving the 24MB/32MB default ratio as trim hysteresis.
+export const DEFAULT_TERMINAL_BUFFER_TRIM_BYTES = Math.min(
+  parseInt(process.env.CODEMAN_TRIM_TERMINAL_TO || '', 10) || 24 * 1024 * 1024,
+  Math.floor(DEFAULT_TERMINAL_BUFFER_MAX_BYTES * 0.75)
+);
+
+export const MIN_TERMINAL_SCROLLBACK_LINES = 1_000;
+export const MAX_TERMINAL_SCROLLBACK_LINES = 1_000_000;
+export const MIN_TERMINAL_BUFFER_BYTES = 1024 * 1024;
+export const MAX_TERMINAL_BUFFER_BYTES = 128 * 1024 * 1024;
+
+export interface TerminalHistoryConfig {
+  terminalScrollbackLines: number;
+  tmuxHistoryLimit: number;
+  terminalBufferMaxBytes: number;
+  terminalBufferTrimBytes: number;
+}
+
+function boundedInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+export function resolveTerminalHistoryConfig(settings: Record<string, unknown> = {}): TerminalHistoryConfig {
+  const terminalBufferMaxBytes = boundedInt(
+    settings.terminalBufferMaxBytes,
+    DEFAULT_TERMINAL_BUFFER_MAX_BYTES,
+    MIN_TERMINAL_BUFFER_BYTES,
+    MAX_TERMINAL_BUFFER_BYTES
+  );
+  const terminalBufferTrimBytes = boundedInt(
+    settings.terminalBufferTrimBytes,
+    Math.min(DEFAULT_TERMINAL_BUFFER_TRIM_BYTES, terminalBufferMaxBytes),
+    MIN_TERMINAL_BUFFER_BYTES,
+    terminalBufferMaxBytes
+  );
+
+  return {
+    terminalScrollbackLines: boundedInt(
+      settings.terminalScrollbackLines,
+      DEFAULT_TERMINAL_SCROLLBACK_LINES,
+      MIN_TERMINAL_SCROLLBACK_LINES,
+      MAX_TERMINAL_SCROLLBACK_LINES
+    ),
+    tmuxHistoryLimit: boundedInt(
+      settings.tmuxHistoryLimit,
+      DEFAULT_TMUX_HISTORY_LIMIT,
+      MIN_TERMINAL_SCROLLBACK_LINES,
+      MAX_TERMINAL_SCROLLBACK_LINES
+    ),
+    terminalBufferMaxBytes,
+    terminalBufferTrimBytes,
+  };
+}

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/cron/cron-input.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Input shape for creating/updating a cron job. This is the
+ * user-settable subset of `CronJob` (server-maintained bookkeeping fields
+ * such as nextRunAt / lastStatus are excluded). Produced by the zod schema.
+ */
+
+import type { ConcurrencyPolicy, InputMode, PromptMode, ScheduleType } from '../types/cron.js';
+import type { SessionMode } from '../types/session.js';
+
+export type { CronJob, CronJobRun, CronJobRunStatus, TriggerType } from '../types/cron.js';
+
+export interface CronJobInput {
+  name: string;
+  agentType: SessionMode;
+  workingDir: string;
+  launchCommand?: string;
+  promptMode: PromptMode;
+  promptText?: string;
+  promptFilePath?: string;
+  inputMode: InputMode;
+  scheduleType: ScheduleType;
+  runAt?: number;
+  intervalMinutes?: number;
+  dailyTime?: string;
+  weeklyDays?: number[];
+  weeklyTime?: string;
+  enabled: boolean;
+  notes?: string;
+  concurrencyPolicy: ConcurrencyPolicy;
+  /** Default true. Ignored for 'once' schedules. */
+  autoClosePreviousSession?: boolean;
+}

src/cron/cron-service.ts

@@ -0,0 +1,668 @@
+/**
+ * @fileoverview Cron service: CRUD for cron jobs, manual Run Now,
+ * the background due-job tick, and run-history recording.
+ *
+ * It does NOT own session/tmux logic — it reuses Codeman's existing session
+ * layer (create → addSession → setupSessionListeners → startInteractive/Shell →
+ * send prompt via writeViaMux/write), mirroring the "quick start" route flow.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { readFile } from 'node:fs/promises';
+import { statSync, realpathSync } from 'node:fs';
+import { Session } from '../session.js';
+import { SseEvent } from '../web/sse-events.js';
+import { CronJobSchema } from '../web/schemas.js';
+import { getErrorMessage, createErrorResponse, ApiErrorCode } from '../types/api.js';
+import { MAX_CONCURRENT_SESSIONS, MAX_CRON_JOBS, MAX_CRON_RUN_HISTORY } from '../config/map-limits.js';
+import { canUsernameRunPrivilegedCommands, resolveClaudeModeForUsername } from '../user-store.js';
+import { sessionCapacityState, isWorkingDirAllowedForUsername } from '../web/route-helpers.js';
+import { CRON_READY_MAX_ATTEMPTS, CRON_READY_SETTLE_MS } from '../config/server-timing.js';
+import {
+  DEFAULT_BLOCKED_TREES,
+  isBlockedAttachmentPath,
+  loadAttachmentGuardConfig,
+} from '../config/attachment-guard.js';
+import { validateSessionFilePath } from '../web/route-helpers.js';
+import { computeNextRunAt, dueKeyFor } from './cron-time.js';
+import type { SessionPort, EventPort, ConfigPort, InfraPort } from '../web/ports/index.js';
+import type { CronJob, CronJobRun, CronJobRunStatus, TriggerType } from '../types/cron.js';
+import type { GeminiConfig } from '../types/session.js';
+import type { CronJobInput } from './cron-input.js';
+
+/** The subset of the route context the cron depends on. */
+export type CronDeps = SessionPort & EventPort & ConfigPort & InfraPort;
+
+const delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Hard ceiling on a prompt-file read (defends against unbounded-read DoS). */
+const MAX_PROMPT_FILE_BYTES = 1024 * 1024;
+
+/**
+ * Pseudo-filesystem trees a cron job may never touch, ON TOP of the shared
+ * attachment blocklist. `/proc` in particular defeats the workingDir
+ * confinement trick (`workingDir: '/proc'` + `promptFilePath:
+ * '/proc/self/environ'` would read the SERVER's own environment).
+ */
+const CRON_PSEUDO_FS_TREES: readonly string[] = ['/proc', '/sys', '/dev'];
+
+/** Sync blocklist for the create/update workingDir gate (no settings extras). */
+const CRON_WORKING_DIR_BLOCKED_TREES: readonly string[] = [...DEFAULT_BLOCKED_TREES, ...CRON_PSEUDO_FS_TREES];
+
+/** Prompt delivery is single-line only (writeViaMux/Ink constraint). */
+const HAS_NEWLINE = /[\r\n]/;
+
+/** Order-insensitive equality for the weekly-days arrays. */
+function sameDays(a: number[] | undefined, b: number[] | undefined): boolean {
+  const x = [...(a ?? [])].sort((p, q) => p - q);
+  const y = [...(b ?? [])].sort((p, q) => p - q);
+  return x.length === y.length && x.every((v, i) => v === y[i]);
+}
+
+export class CronService {
+  constructor(private readonly deps: CronDeps) {}
+
+  private get store() {
+    return this.deps.store;
+  }
+
+  // ───────────────────────────── Reads ─────────────────────────────
+
+  listJobs(): CronJob[] {
+    return Object.values(this.store.getCronJobs());
+  }
+
+  getJob(id: string): CronJob | null {
+    return this.store.getCronJob(id);
+  }
+
+  listRuns(jobId?: string): CronJobRun[] {
+    const all = Object.values(this.store.getCronJobRuns());
+    const filtered = jobId ? all.filter((r) => r.cronJobId === jobId) : all;
+    return filtered.sort((a, b) => b.startedAt - a.startedAt);
+  }
+
+  /**
+   * Number of LIVE sessions of a given agent type (for the multi-session
+   * warning and the skip_if_same_agent_running policy). Sessions whose CLI has
+   * exited (`stopped`/`error` — the tab is still open but nothing is running)
+   * don't count. When `excludeJobId` is given, sessions created by that job's
+   * own runs are also excluded — otherwise a recurring job with the skip
+   * policy would deadlock on its own previous (never-closed) session and fire
+   * exactly once, forever skipping after that.
+   */
+  countActiveAgents(agentType: string, excludeJobId?: string): number {
+    const ownSessionIds = excludeJobId
+      ? new Set(
+          this.listRuns(excludeJobId)
+            .map((r) => r.sessionId)
+            .filter((id): id is string => id !== null)
+        )
+      : null;
+    let n = 0;
+    for (const [id, s] of this.deps.sessions.entries()) {
+      if (s.mode !== agentType) continue;
+      if (s.status === 'stopped' || s.status === 'error') continue;
+      if (ownSessionIds?.has(id)) continue;
+      n++;
+    }
+    return n;
+  }
+
+  // ──────────────────────────── Mutations ───────────────────────────
+
+  createJob(input: CronJobInput, owner?: string): CronJob {
+    if (Object.keys(this.store.getCronJobs()).length >= MAX_CRON_JOBS) {
+      throw this.badRequest(`Maximum number of cron jobs (${MAX_CRON_JOBS}) reached`);
+    }
+    this.assertValidWorkingDir(input.workingDir);
+    const now = Date.now();
+    const job: CronJob = {
+      id: uuidv4(),
+      name: input.name,
+      owner,
+      agentType: input.agentType,
+      workingDir: input.workingDir,
+      launchCommand: input.launchCommand,
+      promptMode: input.promptMode,
+      promptText: input.promptText,
+      promptFilePath: input.promptFilePath,
+      inputMode: input.inputMode,
+      scheduleType: input.scheduleType,
+      runAt: input.runAt,
+      intervalMinutes: input.intervalMinutes,
+      dailyTime: input.dailyTime,
+      weeklyDays: input.weeklyDays,
+      weeklyTime: input.weeklyTime,
+      enabled: input.enabled,
+      notes: input.notes,
+      concurrencyPolicy: input.concurrencyPolicy,
+      autoClosePreviousSession: input.autoClosePreviousSession ?? true,
+      createdAt: now,
+      updatedAt: now,
+      lastRunAt: null,
+      nextRunAt: null,
+      lastStatus: null,
+      lastDueKey: null,
+    };
+    job.nextRunAt = job.enabled ? computeNextRunAt(job, now) : null;
+    this.store.setCronJob(job.id, job);
+    this.broadcastListChanged();
+    return job;
+  }
+
+  updateJob(id: string, patch: Partial<CronJobInput>): CronJob | null {
+    const existing = this.getJob(id);
+    if (!existing) return null;
+    const now = Date.now();
+
+    // A completed one-time job is only re-armed when the SCHEDULE actually
+    // CHANGES — otherwise a cosmetic edit would silently resurrect a job that
+    // already fired. We compare VALUES, not field-presence: the edit form
+    // round-trips the full job (incl. unchanged scheduleType/runAt) on every
+    // save, so a presence check would always re-arm. Only a real schedule
+    // change re-arms.
+    const changed = <T>(next: T | undefined, prev: T): boolean => next !== undefined && next !== prev;
+    const scheduleChanged =
+      changed(patch.scheduleType, existing.scheduleType) ||
+      changed(patch.runAt, existing.runAt) ||
+      changed(patch.intervalMinutes, existing.intervalMinutes) ||
+      changed(patch.dailyTime, existing.dailyTime) ||
+      changed(patch.weeklyTime, existing.weeklyTime) ||
+      (patch.weeklyDays !== undefined && !sameDays(patch.weeklyDays, existing.weeklyDays));
+    const reArm = existing.scheduleType !== 'once' || !existing.completedOnce || scheduleChanged;
+
+    const updated: CronJob = {
+      ...existing,
+      ...patch,
+      id: existing.id,
+      createdAt: existing.createdAt,
+      updatedAt: now,
+      completedOnce: reArm ? false : existing.completedOnce,
+      lastDueKey: null,
+    };
+
+    // The PUT schema is `.partial()`, so its cross-field rules don't run on a
+    // partial body. Re-validate the MERGED job against the full schema so a
+    // partial edit can't leave an enabled job with an inconsistent schedule
+    // (e.g. switching to `once` without a `runAt` → a dead `nextRunAt:null`).
+    const check = CronJobSchema.safeParse(updated);
+    if (!check.success) {
+      throw this.badRequest(check.error.issues[0]?.message ?? 'Invalid cron job update');
+    }
+    if (patch.workingDir !== undefined) this.assertValidWorkingDir(patch.workingDir);
+
+    updated.nextRunAt = updated.enabled ? computeNextRunAt(updated, now) : null;
+    this.store.setCronJob(updated.id, updated);
+    this.broadcastListChanged();
+    return updated;
+  }
+
+  setEnabled(id: string, enabled: boolean): CronJob | null {
+    const existing = this.getJob(id);
+    if (!existing) return null;
+    const now = Date.now();
+    existing.enabled = enabled;
+    existing.updatedAt = now;
+    existing.nextRunAt = enabled ? computeNextRunAt(existing, now) : null;
+    this.store.setCronJob(existing.id, existing);
+    this.broadcastListChanged();
+    return existing;
+  }
+
+  deleteJob(id: string): boolean {
+    if (!this.getJob(id)) return false;
+    this.store.removeCronJob(id);
+    for (const run of this.listRuns(id)) this.store.removeCronJobRun(run.id);
+    this.deps.broadcast(SseEvent.CronJobDeleted, { id });
+    this.broadcastListChanged();
+    return true;
+  }
+
+  // ──────────────────────────── Execution ───────────────────────────
+
+  /** Manual Run Now — always launches regardless of schedule/enabled state. */
+  async runNow(id: string): Promise<CronJobRun | null> {
+    const job = this.getJob(id);
+    if (!job) return null;
+    return this.launch(job, 'manual_run_now');
+  }
+
+  /**
+   * Background tick: launch every enabled job whose next run is due. Advances
+   * each job's schedule and guards against double-launching the same due time.
+   */
+  async tickDueJobs(now: number = Date.now()): Promise<void> {
+    for (const job of this.listJobs()) {
+      if (!job.enabled || job.nextRunAt == null || job.nextRunAt > now) continue;
+
+      const key = dueKeyFor(job.id, job.nextRunAt);
+      if (job.lastDueKey === key) {
+        // This due time was already consumed (overlap/restart) — just advance.
+        this.advanceAfterFire(job, now);
+        continue;
+      }
+
+      // Optional concurrency policy for AUTOMATIC runs. Only LIVE sessions
+      // block, and this job's own previous sessions never do (see
+      // countActiveAgents) — otherwise a recurring job would deadlock on the
+      // session it created last time.
+      if (job.concurrencyPolicy === 'skip_if_same_agent_running' && this.countActiveAgents(job.agentType, job.id) > 0) {
+        // Record the skip so the job's run history isn't silently empty when it
+        // keeps getting skipped (otherwise it looks like the job never ran).
+        this.recordSkippedRun(job);
+        if (job.scheduleType === 'once') {
+          // A skipped one-time job is NOT consumed: leave nextRunAt armed (and
+          // the due key unconsumed) so the next tick retries once the blocking
+          // session goes away.
+          continue;
+        }
+        job.lastDueKey = key;
+        this.advanceAfterFire(job, now);
+        continue;
+      }
+
+      job.lastDueKey = key;
+      // Advance the schedule BEFORE launching so a slow launch can't be
+      // re-triggered by the next tick.
+      this.advanceAfterFire(job, now);
+      this.launch(job, 'scheduled').catch((err) =>
+        console.error(`[cron] launch failed for job ${job.id}:`, getErrorMessage(err))
+      );
+    }
+  }
+
+  /** Recompute nextRunAt for loaded jobs on boot (e.g. after a restart). */
+  init(): void {
+    const now = Date.now();
+    for (const job of this.listJobs()) {
+      const isDeadOnce = job.scheduleType === 'once' && job.completedOnce;
+      if (job.enabled && job.nextRunAt == null && !isDeadOnce) {
+        job.nextRunAt = computeNextRunAt(job, now);
+        this.store.setCronJob(job.id, job);
+      }
+    }
+  }
+
+  // ──────────────────────────── Internals ───────────────────────────
+
+  private advanceAfterFire(job: CronJob, now: number): void {
+    if (job.scheduleType === 'once') {
+      job.completedOnce = true;
+      job.enabled = false;
+      job.nextRunAt = null;
+    } else {
+      job.nextRunAt = computeNextRunAt(job, now);
+    }
+    job.updatedAt = now;
+    this.store.setCronJob(job.id, job);
+    this.broadcastListChanged();
+  }
+
+  private async launch(job: CronJob, trigger: TriggerType): Promise<CronJobRun> {
+    const run: CronJobRun = {
+      id: uuidv4(),
+      cronJobId: job.id,
+      sessionId: null,
+      sessionName: null,
+      startedAt: Date.now(),
+      finishedAt: null,
+      status: 'created',
+      triggerType: trigger,
+      createdSessionUrl: null,
+    };
+    this.store.setCronJobRun(run.id, run);
+    this.pruneRunHistory();
+    this.deps.broadcast(SseEvent.CronRunCreated, run);
+
+    // Resolve the prompt.
+    let prompt: string;
+    try {
+      prompt = await this.resolvePrompt(job);
+    } catch (err) {
+      return this.failRun(job, run, `Prompt error: ${getErrorMessage(err)}`);
+    }
+
+    // Validate working directory.
+    try {
+      if (!statSync(job.workingDir).isDirectory()) {
+        return this.failRun(job, run, 'workingDir is not a directory');
+      }
+    } catch {
+      return this.failRun(job, run, 'workingDir does not exist');
+    }
+
+    // Section 6.3: defense-in-depth workingDir confinement re-check at FIRE time against the
+    // owner's CURRENT space (complements the create/update gate). No-op in single-user / unset owner.
+    if (!(await isWorkingDirAllowedForUsername(job.owner, job.workingDir))) {
+      return this.failRun(job, run, 'workingDir is outside the owner workspace');
+    }
+
+    // Recurring jobs: close the still-open session created by this job's
+    // previous run before launching the next (default ON, opt-out via
+    // autoClosePreviousSession:false) — otherwise an unattended interval/daily
+    // job accumulates a new tab per fire until the global session cap.
+    if (job.scheduleType !== 'once' && job.autoClosePreviousSession !== false) {
+      await this.closePreviousRunSessions(job, run.id);
+    }
+
+    // Respect the global cap AND the owner's per-user cap (multi-user).
+    const cap = sessionCapacityState(this.deps.sessions, job.owner);
+    if (cap.atGlobalCap) {
+      return this.failRun(job, run, `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached`);
+    }
+    if (cap.atUserCap) {
+      return this.failRun(job, run, `Owner's per-user session limit reached`);
+    }
+
+    // Section 6.3: re-resolve the owner's grant at FIRE time (it may have been revoked
+    // since create). Gates shell/launchCommand AND clamps the external-CLI bypass below.
+    const ownerGranted = await canUsernameRunPrivilegedCommands(job.owner);
+    if ((job.agentType === 'shell' || job.launchCommand) && !ownerGranted) {
+      return this.failRun(job, run, 'Owner lacks the can-bypass-permissions grant for shell/launchCommand jobs');
+    }
+
+    // Create + start the session (mirrors the quick-start route flow).
+    let session: Session;
+    try {
+      const mode = job.agentType;
+      const globalNice = await this.deps.getGlobalNiceConfig();
+      const modelConfig = await this.deps.getModelConfig();
+      const claudeModeConfig = await this.deps.getClaudeModeConfig();
+      const effectiveClaudeMode = await resolveClaudeModeForUsername(claudeModeConfig.claudeMode, job.owner);
+      const model = mode !== 'shell' ? modelConfig?.defaultModel || undefined : undefined;
+      // Section 6.3: cron carries no per-CLI config, so buildGeminiCommand(undefined)
+      // would default a non-granted owner to `--approval-mode yolo` (classifier-free) —
+      // materialize auto_edit for a non-granted gemini owner, mirroring the route clamp
+      // (#15). Granted/admin/single-user leave it undefined → yolo parity. Codex's absent
+      // config already defaults to the safe sandbox, so no clamp is needed there.
+      const geminiConfig: GeminiConfig | undefined =
+        mode === 'gemini' && !ownerGranted ? { approvalMode: 'auto_edit' } : undefined;
+      session = new Session({
+        workingDir: job.workingDir,
+        mode,
+        name: job.name,
+        mux: this.deps.mux,
+        useMux: true,
+        niceConfig: globalNice,
+        model,
+        claudeMode: effectiveClaudeMode,
+        allowedTools: claudeModeConfig.allowedTools,
+        geminiConfig,
+        owner: job.owner,
+      });
+      this.deps.addSession(session);
+      this.store.incrementSessionsCreated();
+      this.deps.persistSessionState(session);
+      await this.deps.setupSessionListeners(session);
+      this.deps.broadcast(SseEvent.SessionCreated, this.deps.getSessionStateWithRespawn(session));
+      if (mode === 'shell') {
+        await session.startShell();
+      } else {
+        await session.startInteractive();
+      }
+      this.deps.broadcast(SseEvent.SessionInteractive, { id: session.id, mode });
+    } catch (err) {
+      return this.failRun(job, run, `Session launch failed: ${getErrorMessage(err)}`);
+    }
+
+    run.sessionId = session.id;
+    run.sessionName = session.name;
+    run.createdSessionUrl = `/?session=${session.id}`;
+    run.status = 'session_started';
+    this.store.setCronJobRun(run.id, run);
+    this.deps.broadcast(SseEvent.CronRunUpdated, run);
+    this.updateJobLastStatus(job.id, 'session_started');
+
+    // Send the prompt once the CLI is ready (async; does not block the caller).
+    this.sendPromptWhenReady(session.id, prompt, job, run);
+    return run;
+  }
+
+  /**
+   * Resolves the prompt text and enforces the single-line constraint: prompt
+   * delivery rides writeViaMux/PTY writes where a newline is Enter, so a
+   * multi-line prompt would be silently corrupted (typed mode fuses lines,
+   * paste mode submits the first line and dribbles the rest in as separate
+   * messages). Rather than mangle an unattended agent's instructions, fail the
+   * run with a clear error. A prompt FILE may end with trailing newline(s)
+   * (every editor writes one) — those are stripped before the check.
+   */
+  private async resolvePrompt(job: CronJob): Promise<string> {
+    if (job.promptMode === 'prompt_file_path') {
+      if (!job.promptFilePath) throw new Error('prompt file path is empty');
+      const safePath = await this.resolveSafePromptPath(job.promptFilePath, job.workingDir);
+      const content = (await readFile(safePath, 'utf-8')).replace(/[\r\n]+$/, '');
+      if (HAS_NEWLINE.test(content)) {
+        throw new Error('prompt file must contain a single line — multi-line prompts are not supported');
+      }
+      return content;
+    }
+    const text = job.promptText ?? '';
+    if (HAS_NEWLINE.test(text)) {
+      // Schema-rejected since this check was added; guards legacy persisted jobs.
+      throw new Error('promptText must be a single line — multi-line prompts are not supported');
+    }
+    return text;
+  }
+
+  /**
+   * Guards a prompt-file path before it is read. The path is user-supplied via
+   * the API and its contents are injected into an agent session (an exfil sink
+   * over SSE/terminal), so an unconfined read would let a hostile job config
+   * pull arbitrary host files — including the SERVER PROCESS'S OWN secrets via
+   * `/proc/self/environ` — into the session.
+   *
+   * A denylist is the wrong posture for an exfil sink (it kept missing `/proc`,
+   * `/dev`, other users' `~/.ssh`, modern cloud creds…). So the PRIMARY gate is
+   * an allowlist: the prompt file must resolve INSIDE the job's working
+   * directory. A symlink escaping the workspace fails this because we check the
+   * realpath-resolved target. We additionally require a regular file (rejects
+   * directories, FIFOs, and `/dev/*` character devices that would hang or OOM
+   * the unbounded read) within a sane size cap, and keep the shared blocklist as
+   * cheap defense-in-depth. Returns the symlink-resolved path to read.
+   */
+  private async resolveSafePromptPath(rawPath: string, workingDir: string): Promise<string> {
+    let resolved: string;
+    try {
+      resolved = realpathSync(rawPath);
+    } catch {
+      throw new Error('prompt file path could not be resolved');
+    }
+
+    // workingDir is USER-CONTROLLED, so it is not a trust boundary by itself:
+    // realpath-resolve it (a symlinked workspace must not defeat containment)
+    // and reject blocked/pseudo-fs trees — otherwise workingDir '/proc' would
+    // make '/proc/self/environ' pass the containment check below.
+    let realWorkingDir: string;
+    try {
+      realWorkingDir = realpathSync(workingDir);
+    } catch {
+      throw new Error('job working directory could not be resolved');
+    }
+    const guard = await loadAttachmentGuardConfig();
+    const blockedTrees = [...guard.blockedTrees, ...CRON_PSEUDO_FS_TREES];
+    if (realWorkingDir === '/' || isBlockedAttachmentPath(realWorkingDir, blockedTrees)) {
+      throw new Error('job working directory is blocked');
+    }
+
+    // Defense-in-depth blocklist (secret locations, /etc, /root, pseudo-fs).
+    if (isBlockedAttachmentPath(resolved, blockedTrees)) {
+      throw new Error('prompt file path is blocked');
+    }
+
+    // Primary gate: the prompt file must live inside the job's workspace.
+    if (!validateSessionFilePath(realWorkingDir, resolved)) {
+      throw new Error('prompt file path must be inside the job working directory');
+    }
+
+    // Reject non-regular files and oversized files (DoS via unbounded read).
+    let info;
+    try {
+      info = statSync(resolved);
+    } catch {
+      throw new Error('prompt file path could not be resolved');
+    }
+    if (!info.isFile()) throw new Error('prompt file path is not a regular file');
+    if (info.size > MAX_PROMPT_FILE_BYTES) throw new Error('prompt file is too large');
+
+    return resolved;
+  }
+
+  private sendPromptWhenReady(sessionId: string, prompt: string, job: CronJob, run: CronJobRun): void {
+    setImmediate(() => {
+      const poll = async (): Promise<void> => {
+        if (job.agentType !== 'shell') {
+          for (let attempt = 0; attempt < CRON_READY_MAX_ATTEMPTS; attempt++) {
+            await delay(500);
+            const s = this.deps.sessions.get(sessionId);
+            if (!s) return; // session was removed
+            const buf = s.getTerminalBuffer().slice(-2048);
+            if (buf.includes('❯') || buf.includes('tokens')) break;
+          }
+          await delay(CRON_READY_SETTLE_MS);
+        } else {
+          await delay(1000);
+          // Shell mode: deliver the optional custom launch command as the
+          // first input line (single-line, schema-enforced), then give it a
+          // moment to start before the prompt follows.
+          if (job.launchCommand) {
+            const shell = this.deps.sessions.get(sessionId);
+            if (!shell) return;
+            const sent = await shell.writeViaMux(`${job.launchCommand}\r`);
+            if (!sent) {
+              this.failRun(job, run, 'Failed to send launch command: mux write failed');
+              return;
+            }
+            await delay(1000);
+          }
+        }
+        const s = this.deps.sessions.get(sessionId);
+        if (!s) return;
+        try {
+          const payload = prompt.endsWith('\r') ? prompt : `${prompt}\r`;
+          let delivered = true;
+          if (job.inputMode === 'paste') {
+            s.write(payload);
+          } else {
+            delivered = await s.writeViaMux(payload);
+          }
+          if (!delivered) {
+            this.failRun(job, run, 'Failed to send prompt: mux write failed');
+            return;
+          }
+          run.status = 'prompt_sent';
+          run.finishedAt = Date.now();
+          this.store.setCronJobRun(run.id, run);
+          this.deps.broadcast(SseEvent.CronRunUpdated, run);
+          this.updateJobLastStatus(job.id, 'prompt_sent');
+        } catch (err) {
+          this.failRun(job, run, `Failed to send prompt: ${getErrorMessage(err)}`);
+        }
+      };
+      poll().catch((err) => console.error('[cron] sendPromptWhenReady error:', getErrorMessage(err)));
+    });
+  }
+
+  /** 400-shaped error for route handlers (mirrors parseBody's error contract). */
+  private badRequest(msg: string): Error {
+    return Object.assign(new Error(msg), {
+      statusCode: 400,
+      body: createErrorResponse(ApiErrorCode.INVALID_INPUT, msg),
+    });
+  }
+
+  /**
+   * Create/update gate for a job's workingDir: must exist, be a directory, and
+   * not resolve into a blocked or pseudo-filesystem tree (nor the fs root).
+   * The user-supplied workingDir doubles as the prompt-file confinement root,
+   * so an unrestricted value would defeat that boundary (e.g. '/proc').
+   */
+  private assertValidWorkingDir(workingDir: string): void {
+    let real: string;
+    try {
+      real = realpathSync(workingDir);
+    } catch {
+      throw this.badRequest('workingDir does not exist');
+    }
+    if (!statSync(real).isDirectory()) throw this.badRequest('workingDir is not a directory');
+    if (real === '/' || isBlockedAttachmentPath(real, CRON_WORKING_DIR_BLOCKED_TREES)) {
+      throw this.badRequest('workingDir is not allowed (blocked or pseudo-filesystem tree)');
+    }
+  }
+
+  /** Close still-open sessions created by this job's previous runs (normal cleanup path). */
+  private async closePreviousRunSessions(job: CronJob, currentRunId: string): Promise<void> {
+    for (const prev of this.listRuns(job.id)) {
+      if (prev.id === currentRunId || !prev.sessionId) continue;
+      if (!this.deps.sessions.has(prev.sessionId)) continue;
+      try {
+        await this.deps.cleanupSession(prev.sessionId, true, 'cron: superseded by the next run of this job');
+      } catch (err) {
+        console.error(`[cron] failed to auto-close previous session ${prev.sessionId}:`, getErrorMessage(err));
+      }
+    }
+  }
+
+  private failRun(job: CronJob, run: CronJobRun, message: string): CronJobRun {
+    run.status = 'failed';
+    run.errorMessage = message;
+    run.finishedAt = Date.now();
+    this.store.setCronJobRun(run.id, run);
+    this.deps.broadcast(SseEvent.CronRunUpdated, run);
+    this.updateJobLastStatus(job.id, 'failed');
+    return run;
+  }
+
+  private recordSkippedRun(job: CronJob): void {
+    // Coalesce consecutive skips: if the job is already in a skip streak, don't
+    // record again — a perpetually-skipped interval job would otherwise write a
+    // run every tick forever and bloat state.json.
+    if (this.listRuns(job.id)[0]?.status === 'skipped') return;
+
+    const now = Date.now();
+    const run: CronJobRun = {
+      id: uuidv4(),
+      cronJobId: job.id,
+      sessionId: null,
+      sessionName: null,
+      startedAt: now,
+      finishedAt: now,
+      status: 'skipped',
+      errorMessage: `Skipped: a ${job.agentType} agent is already running (concurrency policy)`,
+      triggerType: 'scheduled',
+      createdSessionUrl: null,
+    };
+    this.store.setCronJobRun(run.id, run);
+    this.pruneRunHistory();
+    this.deps.broadcast(SseEvent.CronRunCreated, run);
+    // A skip is NOT a run: surface it as the lastStatus, but do NOT advance
+    // lastRunAt (no session was created).
+    this.updateJobLastStatus(job.id, 'skipped', { touchLastRun: false });
+  }
+
+  /** Prune the oldest run records (by startedAt) once the global cap is exceeded. */
+  private pruneRunHistory(): void {
+    const runs = Object.values(this.store.getCronJobRuns());
+    if (runs.length <= MAX_CRON_RUN_HISTORY) return;
+    runs.sort((a, b) => a.startedAt - b.startedAt);
+    for (const run of runs.slice(0, runs.length - MAX_CRON_RUN_HISTORY)) {
+      this.store.removeCronJobRun(run.id);
+    }
+  }
+
+  private updateJobLastStatus(jobId: string, status: CronJobRunStatus, opts: { touchLastRun?: boolean } = {}): void {
+    const fresh = this.store.getCronJob(jobId);
+    if (!fresh) return;
+    const now = Date.now();
+    fresh.lastStatus = status;
+    if (opts.touchLastRun !== false) fresh.lastRunAt = now;
+    fresh.updatedAt = now;
+    this.store.setCronJob(fresh.id, fresh);
+    this.broadcastListChanged();
+  }
+
+  private broadcastListChanged(): void {
+    this.deps.broadcast(SseEvent.CronJobsChanged, { jobs: this.listJobs() });
+  }
+}

src/cron/cron-time.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Pure next-run-time calculations for the cron.
+ *
+ * All functions are pure and take an explicit `after` timestamp (epoch ms) so
+ * they are deterministic and unit-testable. Times use the SERVER'S LOCAL
+ * timezone for v0.1 (per the build brief) — daily/weekly wall-clock times are
+ * interpreted via the host's local time.
+ */
+
+import type { CronJob } from '../types/cron.js';
+
+/** Parse an 'HH:MM' (24-hour) string into hours/minutes, or null if invalid. */
+export function parseHHMM(value: string | undefined): { hours: number; minutes: number } | null {
+  if (!value) return null;
+  const m = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+  if (!m) return null;
+  const hours = Number(m[1]);
+  const minutes = Number(m[2]);
+  if (hours < 0 || hours > 23 || minutes < 0 || minutes > 59) return null;
+  return { hours, minutes };
+}
+
+/**
+ * Returns the epoch-ms timestamp for `hours:minutes` (local time) on the day of
+ * `base`, shifted by `dayOffset` days.
+ */
+function atLocalTime(base: number, hours: number, minutes: number, dayOffset: number): number {
+  const d = new Date(base);
+  d.setHours(hours, minutes, 0, 0);
+  d.setDate(d.getDate() + dayOffset);
+  return d.getTime();
+}
+
+/**
+ * Compute the next fire time strictly relevant to `after`, or null if the job
+ * has no future run (e.g. a completed one-time job, or invalid config).
+ *
+ * For `once`, returns the absolute `runAt` (even if already in the past, so a
+ * missed one-time job still fires once) until it has `completedOnce`.
+ */
+export function computeNextRunAt(job: CronJob, after: number): number | null {
+  switch (job.scheduleType) {
+    case 'once': {
+      if (job.completedOnce) return null;
+      return typeof job.runAt === 'number' ? job.runAt : null;
+    }
+    case 'interval': {
+      const minutes = job.intervalMinutes;
+      if (!minutes || minutes <= 0) return null;
+      return after + minutes * 60_000;
+    }
+    case 'daily': {
+      const t = parseHHMM(job.dailyTime);
+      if (!t) return null;
+      let next = atLocalTime(after, t.hours, t.minutes, 0);
+      if (next <= after) next = atLocalTime(after, t.hours, t.minutes, 1);
+      return next;
+    }
+    case 'weekly': {
+      const t = parseHHMM(job.weeklyTime);
+      if (!t) return null;
+      const days = (job.weeklyDays ?? []).filter((d) => d >= 0 && d <= 6);
+      if (days.length === 0) return null;
+      for (let offset = 0; offset <= 7; offset++) {
+        const cand = atLocalTime(after, t.hours, t.minutes, offset);
+        if (cand > after && days.includes(new Date(cand).getDay())) return cand;
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Duplicate-launch guard key: identifies a specific due time for a job. The
+ * cron records the key it last consumed so an overlapping or restarted
+ * loop will not launch the same due time twice.
+ */
+export function dueKeyFor(jobId: string, fireTime: number): string {
+  return `${jobId}:${fireTime}`;
+}

src/docker-export.ts

@@ -0,0 +1,465 @@
+/**
+ * @fileoverview Docker case export / import: move a container (toolchain + any
+ * in-image changes) PLUS its workspace to another machine as one portable
+ * `.codeman-container.tgz`, and restore it.
+ *
+ * A full-image export = `docker commit` the running container to an image ->
+ * `docker save` that image -> tar the bind-mounted workspace -> a manifest, all
+ * bundled into one gzip tarball. A workspace-only export skips the image (fast,
+ * files-only). Import validates the manifest + per-member checksums, extracts the
+ * workspace with a path-traversal guard, `docker load`s the image and RE-TAGS it
+ * into a quarantined namespace (never overwriting a local tag), and hands the
+ * caller enough to recreate a hardened case on the destination.
+ *
+ * Safety (all from the design critic): pause the container spanning the workspace
+ * tar AND the commit so the two artifacts are mutually consistent; a free-space
+ * precheck (a full docker graph wedges EVERY session on the host); `docker rmi`
+ * the intermediate image in a finally; sealed containers refuse a full-image
+ * export (an in-container login would ride the committed layer); import rejects
+ * absolute / `..` tar members and checksum mismatches. Bounded by
+ * runWithConversionLimit so N exports cannot fork-bomb the host.
+ *
+ * @module docker-export
+ */
+
+import { createReadStream, createWriteStream, existsSync, mkdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { pipeline } from 'node:stream/promises';
+import type { DockerEngine, SessionDocker } from './types.js';
+import { runWithConversionLimit } from './document-conversion-limiter.js';
+
+const IS_TEST_MODE = !!process.env.VITEST;
+
+/** Refuse to export when the target filesystem has less than this free (a full graph wedges the daemon). */
+export const DOCKER_EXPORT_MIN_FREE_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+
+/** Manifest schema version (bump on any breaking field change). */
+export const DOCKER_EXPORT_SCHEMA = 1;
+
+export type DockerExportMode = 'full' | 'workspace';
+
+export interface DockerExportManifest {
+  schemaVersion: number;
+  caseName: string;
+  mode: DockerExportMode;
+  engine: DockerEngine;
+  image: string;
+  containerWorkdir: string;
+  network: string;
+  createdAt: number;
+  codemanVersion: string;
+  mountCredentials: boolean;
+  /** True when the bundle provably carries no credentials (convenient-mode workspace, or a full image whose creds were bind-mounted and thus never committed). */
+  secretFree: boolean;
+  /** sha256 of each bundle member that is present. */
+  checksums: { image?: string; workspace?: string };
+}
+
+// ========== Pure helpers (unit-tested) ==========
+
+/** Raw argv prefix for the engine (NO shell escaping — used with spawn). */
+export function dockerArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
+  const argv: string[] = [docker.engine === 'podman' ? 'podman' : 'docker'];
+  if (docker.context) argv.push('--context', docker.context);
+  if (docker.daemonHost) argv.push('-H', docker.daemonHost);
+  return argv;
+}
+
+/** Portable bundle filename for a case export. */
+export function exportBundleName(caseName: string, timestamp: number, mode: DockerExportMode): string {
+  const suffix = mode === 'workspace' ? 'workspace' : 'container';
+  return `${caseName}-${timestamp}.codeman-${suffix}.tgz`;
+}
+
+/** Quarantined image tag for an imported bundle (never overwrites a local tag). */
+export function importedImageTag(caseName: string, timestamp: number): string {
+  return `codeman/imported-${caseName}:${timestamp}`;
+}
+
+/** Intermediate commit tag for a full-image export (unique per export, rmi'd in finally). */
+export function exportImageTag(caseName: string, timestamp: number): string {
+  return `codeman/export-${caseName}:${timestamp}`;
+}
+
+/**
+ * Reject a tar member path that would escape the extraction root (absolute path
+ * or a `..` component). The import-side traversal guard.
+ */
+export function isSafeTarMember(member: string): boolean {
+  const trimmed = member.trim();
+  if (!trimmed || trimmed === './') return true;
+  if (trimmed.startsWith('/')) return false;
+  // Normalize separators and check each component.
+  return !trimmed.split('/').some((part) => part === '..');
+}
+
+/** Parse the image id/ref from `docker load` output ("Loaded image: x" / "Loaded image ID: sha256:..."). */
+export function parseLoadedImageRef(loadOutput: string): string | null {
+  const idMatch = loadOutput.match(/Loaded image ID:\s*(sha256:[0-9a-f]+)/i);
+  if (idMatch) return idMatch[1];
+  const refMatch = loadOutput.match(/Loaded image:\s*(\S+)/i);
+  if (refMatch) return refMatch[1];
+  return null;
+}
+
+/**
+ * Validate an imported bundle's manifest BEFORE any of its fields are trusted.
+ * A bundle is cross-machine input (potentially authored by someone else), and its
+ * fields flow into stored host/case config that the schema layer never sees:
+ * `engine` becomes the probe/launch binary selector, `image`/`containerWorkdir`
+ * reach the shellescaped launch string, `network` is a create arg. Mirror the
+ * DockerHostSchema/DockerCaseLinkSchema constraints here (throwing, since this is
+ * not a web-layer module). Exported for unit tests.
+ */
+export function validateImportManifest(manifest: DockerExportManifest): void {
+  const fail = (msg: string): never => {
+    throw new Error(`invalid bundle manifest: ${msg}`);
+  };
+  if (manifest.schemaVersion !== DOCKER_EXPORT_SCHEMA) {
+    fail(`unsupported export schema version ${manifest.schemaVersion} (expected ${DOCKER_EXPORT_SCHEMA})`);
+  }
+  if (manifest.mode !== 'full' && manifest.mode !== 'workspace') fail(`unknown mode ${String(manifest.mode)}`);
+  if (manifest.engine !== 'docker' && manifest.engine !== 'podman') fail(`unknown engine ${String(manifest.engine)}`);
+  if (typeof manifest.caseName !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(manifest.caseName)) fail('bad caseName');
+  if (
+    typeof manifest.image !== 'string' ||
+    manifest.image.length > 512 ||
+    !/^[a-zA-Z0-9][\w./:@-]*$/.test(manifest.image)
+  ) {
+    fail('bad image reference');
+  }
+  if (
+    typeof manifest.containerWorkdir !== 'string' ||
+    manifest.containerWorkdir.length > 2000 ||
+    !manifest.containerWorkdir.startsWith('/') ||
+    // comma: --mount specs are comma-delimited CSV; shell escaping cannot protect it
+    /[`$\\"'\n\r;&|<>,]/.test(manifest.containerWorkdir)
+  ) {
+    fail('bad containerWorkdir');
+  }
+  if (!['bridge', 'none', 'custom'].includes(manifest.network)) fail(`unknown network ${String(manifest.network)}`);
+  if (typeof manifest.checksums !== 'object' || manifest.checksums === null) fail('missing checksums');
+}
+
+// ========== IO helpers ==========
+
+function run(
+  cmd: string,
+  args: string[],
+  opts: { timeout?: number } = {}
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let timer: NodeJS.Timeout | undefined;
+    if (opts.timeout) {
+      timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        reject(new Error(`${cmd} timed out after ${opts.timeout}ms`));
+      }, opts.timeout);
+    }
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`${cmd} ${args.join(' ')} exited ${code}: ${stderr.trim()}`));
+    });
+  });
+}
+
+/**
+ * Stream `docker save <tag>` stdout to a raw tar file (no shell, no double-gzip).
+ * Uses stream `pipeline` so completion means the write stream is FULLY flushed to
+ * disk (a naive child 'close' resolves before the last chunks land, truncating the
+ * file — a real bug caught in end-to-end testing), AND waits for a clean exit code.
+ */
+async function saveImageToTar(argv: string[], tag: string, outPath: string): Promise<void> {
+  const child = spawn(argv[0], [...argv.slice(1), 'save', tag], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => (stderr += d));
+  const exited = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`docker save exited ${code}: ${stderr.trim()}`))
+    );
+  });
+  // pipeline resolves only after the destination has fully flushed.
+  await Promise.all([pipeline(child.stdout, createWriteStream(outPath)), exited]);
+}
+
+async function sha256File(path: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    stream.on('data', (d) => hash.update(d));
+    stream.on('error', reject);
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+async function freeBytes(path: string): Promise<number> {
+  try {
+    const stat = await fs.statfs(path);
+    return Number(stat.bavail) * Number(stat.bsize);
+  } catch {
+    return Number.POSITIVE_INFINITY; // statfs unsupported — don't block
+  }
+}
+
+async function isContainerRunning(argv: string[], container: string): Promise<boolean> {
+  try {
+    const { stdout } = await run(argv[0], [...argv.slice(1), 'inspect', '-f', '{{.State.Running}}', container], {
+      timeout: 15_000,
+    });
+    return stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+export interface ExportResult {
+  bundlePath: string;
+  manifest: DockerExportManifest;
+  sizeBytes: number;
+}
+
+/**
+ * Export a docker case to a portable bundle. Bounded by runWithConversionLimit.
+ * `full` mode commits + saves the image AND tars the workspace; `workspace` mode
+ * tars just the workspace. The container is paused across the artifact capture so
+ * image and workspace are mutually consistent.
+ */
+export async function exportDockerCase(params: {
+  docker: SessionDocker;
+  caseName: string;
+  timestamp: number;
+  exportsDir: string;
+  mode: DockerExportMode;
+  codemanVersion: string;
+}): Promise<ExportResult> {
+  const { docker, caseName, timestamp, exportsDir, mode, codemanVersion } = params;
+
+  if (mode === 'full' && !docker.mountCredentials) {
+    throw new Error(
+      'full-image export is refused for a sealed (mountCredentials:false) container: an in-container login would ride the committed image layer. Use a workspace-only export.'
+    );
+  }
+
+  if (IS_TEST_MODE) {
+    // No real docker/tar under vitest — return a deterministic stub.
+    const manifest: DockerExportManifest = {
+      schemaVersion: DOCKER_EXPORT_SCHEMA,
+      caseName,
+      mode,
+      engine: docker.engine,
+      image: docker.image,
+      containerWorkdir: docker.containerWorkdir,
+      network: docker.network,
+      createdAt: timestamp,
+      codemanVersion,
+      mountCredentials: docker.mountCredentials,
+      secretFree: true,
+      checksums: {},
+    };
+    return { bundlePath: join(exportsDir, exportBundleName(caseName, timestamp, mode)), manifest, sizeBytes: 0 };
+  }
+
+  return runWithConversionLimit(async () => {
+    if (!existsSync(exportsDir)) mkdirSync(exportsDir, { recursive: true });
+
+    const free = await freeBytes(exportsDir);
+    if (free < DOCKER_EXPORT_MIN_FREE_BYTES) {
+      throw new Error(
+        `not enough free space to export (need >= ${Math.round(DOCKER_EXPORT_MIN_FREE_BYTES / 1e9)}GB, have ${Math.round(free / 1e9)}GB). A full docker graph wedges every session on the host.`
+      );
+    }
+
+    const argv = dockerArgv(docker);
+    const bundlePath = join(exportsDir, exportBundleName(caseName, timestamp, mode));
+    const stageDir = join(exportsDir, `.stage-${caseName}-${timestamp}`);
+    mkdirSync(stageDir, { recursive: true });
+    const wasRunning = await isContainerRunning(argv, docker.containerName);
+    let commitTag: string | undefined;
+
+    try {
+      if (wasRunning) {
+        await run(argv[0], [...argv.slice(1), 'pause', docker.containerName], { timeout: 30_000 }).catch(() => {});
+      }
+
+      const checksums: DockerExportManifest['checksums'] = {};
+
+      if (mode === 'full') {
+        commitTag = exportImageTag(caseName, timestamp);
+        // Blank instance-specific committed env so the image carries no stale host refs.
+        await run(
+          argv[0],
+          [
+            ...argv.slice(1),
+            'commit',
+            '-c',
+            'ENV CODEMAN_API_URL=',
+            '-c',
+            'ENV CODEMAN_HOOK_SECRET_FILE=',
+            docker.containerName,
+            commitTag,
+          ],
+          { timeout: 300_000 }
+        );
+        const imageTar = join(stageDir, 'image.tar');
+        await saveImageToTar(argv, commitTag, imageTar);
+        checksums.image = await sha256File(imageTar);
+      }
+
+      const workspaceTar = join(stageDir, 'workspace.tar');
+      await run('tar', ['-cf', workspaceTar, '-C', docker.hostWorkspacePath, '.'], { timeout: 300_000 });
+      checksums.workspace = await sha256File(workspaceTar);
+
+      const manifest: DockerExportManifest = {
+        schemaVersion: DOCKER_EXPORT_SCHEMA,
+        caseName,
+        mode,
+        engine: docker.engine,
+        image: docker.image,
+        containerWorkdir: docker.containerWorkdir,
+        network: docker.network,
+        createdAt: timestamp,
+        codemanVersion,
+        mountCredentials: docker.mountCredentials,
+        // Convenient mode keeps creds on bind mounts (never committed), so the bundle is secret-free.
+        secretFree: docker.mountCredentials,
+        checksums,
+      };
+      await fs.writeFile(join(stageDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+      const members =
+        mode === 'full' ? ['manifest.json', 'image.tar', 'workspace.tar'] : ['manifest.json', 'workspace.tar'];
+      await run('tar', ['-czf', bundlePath, '-C', stageDir, ...members], { timeout: 300_000 });
+
+      const stat = await fs.stat(bundlePath);
+      return { bundlePath, manifest, sizeBytes: stat.size };
+    } finally {
+      // Always remove the intermediate image + stage dir, and unpause.
+      if (commitTag) {
+        await run(argv[0], [...argv.slice(1), 'rmi', commitTag], { timeout: 60_000 }).catch(() => {});
+      }
+      await fs.rm(stageDir, { recursive: true, force: true }).catch(() => {});
+      if (wasRunning) {
+        await run(argv[0], [...argv.slice(1), 'unpause', docker.containerName], { timeout: 30_000 }).catch(() => {});
+      }
+    }
+  });
+}
+
+export interface ImportResult {
+  manifest: DockerExportManifest;
+  /** Quarantined image ref the destination case should use (full mode only). */
+  importedImage?: string;
+  /** Directory the workspace was extracted into. */
+  workspacePath: string;
+}
+
+/**
+ * Import a bundle produced by exportDockerCase: validate the manifest + per-member
+ * checksums, extract the workspace (traversal-guarded) into destWorkspace, and, in
+ * full mode, `docker load` the image and re-tag it into a quarantined namespace.
+ */
+export async function importDockerBundle(params: {
+  bundlePath: string;
+  destWorkspace: string;
+  engine: DockerEngine;
+  timestamp: number;
+  /** Schema-validated destination case name; the quarantine tag derives from THIS,
+   *  never from the (attacker-authored) manifest.caseName. */
+  newCaseName: string;
+}): Promise<ImportResult> {
+  const { bundlePath, destWorkspace, engine, timestamp, newCaseName } = params;
+  const argv: string[] = [engine === 'podman' ? 'podman' : 'docker'];
+
+  if (IS_TEST_MODE) {
+    const raw = await fs.readFile(bundlePath, 'utf-8').catch(() => '{}');
+    const manifest = JSON.parse(raw) as DockerExportManifest;
+    validateImportManifest(manifest);
+    return { manifest, workspacePath: destWorkspace };
+  }
+
+  const stageDir = `${destWorkspace}.import-stage-${timestamp}`;
+  mkdirSync(stageDir, { recursive: true });
+  try {
+    // Outer-bundle traversal guard (defense in depth: GNU/bsd tar already refuse
+    // `..`/absolute members by default, but the bundle is cross-machine input).
+    const { stdout: bundleMembers } = await run('tar', ['-tzf', bundlePath], { timeout: 60_000 });
+    for (const member of bundleMembers.split('\n').filter(Boolean)) {
+      if (!isSafeTarMember(member)) throw new Error(`unsafe path in bundle archive: ${member}`);
+    }
+    await run('tar', ['--no-same-owner', '-xzf', bundlePath, '-C', stageDir], { timeout: 300_000 });
+
+    const manifestRaw = await fs.readFile(join(stageDir, 'manifest.json'), 'utf-8');
+    const manifest = JSON.parse(manifestRaw) as DockerExportManifest;
+    validateImportManifest(manifest);
+
+    // Integrity: verify checksums before trusting any member.
+    const workspaceTar = join(stageDir, 'workspace.tar');
+    if (manifest.checksums.workspace) {
+      const actual = await sha256File(workspaceTar);
+      if (actual !== manifest.checksums.workspace)
+        throw new Error('workspace checksum mismatch (corrupt or tampered bundle)');
+    }
+
+    // Traversal guard: reject absolute / `..` members before extraction.
+    const { stdout: memberList } = await run('tar', ['-tf', workspaceTar], { timeout: 60_000 });
+    for (const member of memberList.split('\n').filter(Boolean)) {
+      if (!isSafeTarMember(member)) throw new Error(`unsafe path in workspace archive: ${member}`);
+    }
+    mkdirSync(destWorkspace, { recursive: true });
+    await run('tar', ['--no-same-owner', '-xf', workspaceTar, '-C', destWorkspace], { timeout: 300_000 });
+
+    let importedImage: string | undefined;
+    if (manifest.mode === 'full') {
+      const imageTar = join(stageDir, 'image.tar');
+      if (manifest.checksums.image) {
+        const actual = await sha256File(imageTar);
+        if (actual !== manifest.checksums.image)
+          throw new Error('image checksum mismatch (corrupt or tampered bundle)');
+      }
+      const { stdout } = await run(argv[0], [...argv.slice(1), 'load', '-i', imageTar], { timeout: 300_000 });
+      const loadedRef = parseLoadedImageRef(stdout);
+      if (!loadedRef) throw new Error('could not determine loaded image ref');
+      // Quarantine: re-tag by the loaded ref/id, never trusting the bundle's original
+      // tag; the tag name derives from the caller's schema-validated newCaseName.
+      importedImage = importedImageTag(newCaseName, timestamp);
+      await run(argv[0], [...argv.slice(1), 'tag', loadedRef, importedImage], { timeout: 60_000 });
+    }
+
+    return { manifest, importedImage, workspacePath: destWorkspace };
+  } finally {
+    await fs.rm(stageDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/** List export bundles in the exports dir (newest first), with size + mtime. */
+export async function listDockerExports(
+  exportsDir: string
+): Promise<Array<{ name: string; sizeBytes: number; mtimeMs: number }>> {
+  if (!existsSync(exportsDir)) return [];
+  const entries = await fs.readdir(exportsDir).catch(() => [] as string[]);
+  const out: Array<{ name: string; sizeBytes: number; mtimeMs: number }> = [];
+  for (const name of entries) {
+    if (!name.endsWith('.tgz')) continue;
+    try {
+      const stat = await fs.stat(join(exportsDir, name));
+      out.push({ name: basename(name), sizeBytes: stat.size, mtimeMs: stat.mtimeMs });
+    } catch {
+      /* skip */
+    }
+  }
+  return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}

src/document-thumbnailer.ts

@@ -13,9 +13,18 @@ import { runWithConversionLimit } from './document-conversion-limiter.js';
 const execFileAsync = promisify(execFile);
 const THUMBNAIL_CONVERSION_TIMEOUT_MS = 5 * 60_000;
 
+/** Browser-renderable image formats served as-is (no conversion). */
+const IMAGE_PASSTHROUGH_CONTENT_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+};
+
 export interface ThumbnailResult {
   content: Buffer;
-  contentType: 'image/png';
+  contentType: string;
 }
 
 export async function generateFirstPageThumbnail(filePath: string, extension: string): Promise<ThumbnailResult | null> {
@@ -24,8 +33,9 @@ export async function generateFirstPageThumbnail(filePath: string, extension: st
   try {
     await fs.stat(filePath);
 
-    if (ext === 'png') {
-      return { content: await fs.readFile(filePath), contentType: 'image/png' };
+    const passthroughContentType = IMAGE_PASSTHROUGH_CONTENT_TYPES[ext];
+    if (passthroughContentType) {
+      return { content: await fs.readFile(filePath), contentType: passthroughContentType };
     }
 
     if (ext === 'pdf') {

src/generated-artifact-attachments.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Codex generated-artifact attachment registration.
+ *
+ * Codex image generation prints paths such as `Saved to: file://...`. These
+ * paths are registered directly when they fall within allowed locations (the
+ * session workspace or the well-known Codex generated-artifact directories
+ * anchored at the user's home). The trust decision is made on the
+ * realpath-RESOLVED path so a symlink staged at an allowed location cannot
+ * smuggle an arbitrary host file past workspace confinement.
+ */
+
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, normalize, sep } from 'node:path';
+import { registerExternalAttachment, type AttachmentRegistrationResult } from './attachment-registry.js';
+
+export interface GeneratedArtifactRegistrationOptions {
+  sessionId: string;
+  filePath: string;
+  sessionWorkingDir: string;
+}
+
+export async function registerGeneratedArtifactAttachment(
+  options: GeneratedArtifactRegistrationOptions
+): Promise<AttachmentRegistrationResult> {
+  // Decide trust on the symlink-resolved path. If it can't be resolved, fall
+  // back to the strict force-confined policy (registration will 404 a missing
+  // file anyway).
+  let forceWorkspaceConfinement = true;
+  try {
+    const resolvedPath = realpathSync(options.filePath);
+    forceWorkspaceConfinement = !isAllowedGeneratedArtifactPath(resolvedPath, options.sessionWorkingDir);
+  } catch {
+    // Keep force confinement.
+  }
+  return registerExternalAttachment(options.sessionId, options.filePath, {
+    sessionWorkingDir: options.sessionWorkingDir,
+    forceWorkspaceConfinement,
+  });
+}
+
+/** Well-known Codex generated-artifact directories, anchored at the user's home. */
+function codexGeneratedDirs(): string[] {
+  const home = homedir();
+  return [
+    join(home, '.codex-personal', 'generated_images'),
+    join(home, '.codex', 'generated_images'),
+    join(home, '.codex-personal', 'generated_artifacts'),
+    join(home, '.codex', 'generated_artifacts'),
+  ];
+}
+
+/**
+ * True when `filePath` (absolute; callers should pass the realpath-resolved
+ * path) is inside the session workspace or one of the well-known Codex
+ * generated-artifact directories under the current user's home. The marker
+ * directories are prefix-anchored to `os.homedir()` — a `.codex/...` subtree
+ * elsewhere on the filesystem does NOT qualify.
+ */
+export function isAllowedGeneratedArtifactPath(filePath: string, workingDir: string): boolean {
+  const normalizedPath = normalize(filePath);
+  if (isPathInside(normalizedPath, workingDir)) return true;
+  return codexGeneratedDirs().some((dir) => isPathInside(normalizedPath, dir));
+}
+
+function isPathInside(filePath: string, rootPath: string): boolean {
+  const normalizedRoot = normalize(rootPath);
+  if (filePath === normalizedRoot) return true;
+  return filePath.startsWith(normalizedRoot.endsWith(sep) ? normalizedRoot : normalizedRoot + sep);
+}

src/hooks-config.ts

@@ -16,9 +16,9 @@
  * `stop`, `teammate_idle`, `task_completed`
  *
  * Hook categories: `Notification` (3 matchers), `Stop` (1), `TeammateIdle` (1),
- * `TaskCompleted` (1)
+ * `TaskCompleted` (1), `PostToolUse` (1 self-contained background Bash rewake)
  *
- * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_MS)
+ * @dependencies types (HookEventType), config/auth-config (HOOK_TIMEOUT_SECONDS)
  * @consumedby web/server (session creation), session-cli-builder (env setup)
  *
  * @module hooks-config
@@ -29,7 +29,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { HookEventType } from './types.js';
-import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
+import { HOOK_TIMEOUT_SECONDS } from './config/auth-config.js';
 
 /**
  * Serializes read-modify-write access to a `settings.local.json` path. Every
@@ -40,6 +40,104 @@ import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
  * are independent; the map self-prunes when a path's chain goes idle.
  */
 const settingsWriteLocks = new Map<string, Promise<unknown>>();
+/**
+ * Version-agnostic ownership prefix: every rewake script version embeds a marker
+ * starting with this, and `isCodemanHookHandler` matches on the prefix. That way a
+ * version bump replaces the old handler instead of duplicating it (matching on the
+ * full versioned marker would disown every older script).
+ */
+const BACKGROUND_WAKE_MARKER_PREFIX = 'CODEMAN_BACKGROUND_REWAKE_V';
+/**
+ * Current script version. Bump the suffix whenever `generateBackgroundWakeScript`
+ * changes: `refreshStaleCodemanHooks` treats the absence of the CURRENT marker as
+ * stale, so healed cases pick up the new script on next launch.
+ */
+const BACKGROUND_WAKE_MARKER = `${BACKGROUND_WAKE_MARKER_PREFIX}2`;
+const BACKGROUND_WAKE_TIMEOUT_SECONDS = 6 * 60 * 60;
+
+/**
+ * Inline Node helper for Claude Code's `asyncRewake` hook.
+ *
+ * A background Bash tool returns immediately with a task ID, then Claude writes
+ * its completion as a queue-operation in the transcript. Watching that durable
+ * record avoids injecting terminal input (which could submit a user's draft).
+ * The helper is embedded in settings via `node -e`, so it has no script path
+ * that can go stale after an install or plugin-cache cleanup.
+ *
+ * Self-terminating: Claude Code enforces the hook timeout, but the helper does not
+ * rely on it. It exits on its own deadline (same budget) and when orphaned
+ * (`ppid === 1`), so a dead session cannot leave a poller stat-ing the transcript
+ * forever. The ppid check misses subreaper setups; the deadline is the backstop.
+ */
+export function generateBackgroundWakeScript(): string {
+  return [
+    "const fs = require('node:fs');",
+    `const ${BACKGROUND_WAKE_MARKER} = true;`,
+    `const deadline = Date.now() + ${BACKGROUND_WAKE_TIMEOUT_SECONDS} * 1000;`,
+    'let input = {};',
+    "try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }",
+    'function findTaskId(value) {',
+    "  const idKeys = new Set(['taskId', 'task_id', 'shellId', 'shell_id', 'backgroundTaskId', 'background_task_id']);",
+    '  const stack = [value];',
+    '  const seen = new Set();',
+    '  while (stack.length > 0) {',
+    '    const current = stack.pop();',
+    "    if (!current || typeof current !== 'object' || seen.has(current)) continue;",
+    '    seen.add(current);',
+    '    for (const [key, nested] of Object.entries(current)) {',
+    "      if (idKeys.has(key) && typeof nested === 'string' && /^[A-Za-z0-9_-]+$/.test(nested)) return nested;",
+    "      if (nested && typeof nested === 'object') stack.push(nested);",
+    '    }',
+    '  }',
+    "  const serialized = JSON.stringify(value ?? '');",
+    '  const messageMatch = serialized.match(/Command running in background with ID:\\s*([A-Za-z0-9_-]+)/i);',
+    '  if (messageMatch) return messageMatch[1];',
+    '  const pathMatch = serialized.match(/[\\\\/]tasks[\\\\/]([A-Za-z0-9_-]+)\\.output/i);',
+    '  return pathMatch ? pathMatch[1] : null;',
+    '}',
+    'const taskId = findTaskId(input.tool_response);',
+    "const transcriptPath = typeof input.transcript_path === 'string' ? input.transcript_path : '';",
+    'if (!taskId || !transcriptPath) process.exit(0);',
+    'let position = 0;',
+    'try { position = Math.max(0, fs.statSync(transcriptPath).size - 262144); } catch { process.exit(0); }',
+    "let carry = '';",
+    'function inspect(text) {',
+    '  for (const line of text.split(/\\r?\\n/)) {',
+    '    if (!line.includes(taskId)) continue;',
+    '    let entry;',
+    '    try { entry = JSON.parse(line); } catch { continue; }',
+    "    if (entry.type !== 'queue-operation' || typeof entry.content !== 'string') continue;",
+    "    if (!entry.content.includes('<task-id>' + taskId + '</task-id>')) continue;",
+    '    const status = entry.content.match(/<status>(completed|failed|killed|error)<\\/status>/i);',
+    '    if (!status) continue;',
+    '    const output = entry.content.match(/<output-file>([^<]+)<\\/output-file>/i);',
+    "    const location = output ? ' Read ' + output[1] + ' and' : '';",
+    "    console.error('Background command ' + taskId + ' ' + status[1].toLowerCase() + '.' + location + ' continue the task.');",
+    '    process.exit(2);',
+    '  }',
+    '}',
+    'function poll() {',
+    '  if (Date.now() > deadline || process.ppid === 1) process.exit(0);',
+    '  try {',
+    '    const size = fs.statSync(transcriptPath).size;',
+    "    if (size < position) { position = 0; carry = ''; }",
+    '    if (size > position) {',
+    '      const length = Math.min(size - position, 1048576);',
+    '      const buffer = Buffer.allocUnsafe(length);',
+    "      const fd = fs.openSync(transcriptPath, 'r');",
+    '      const bytes = fs.readSync(fd, buffer, 0, length, position);',
+    '      fs.closeSync(fd);',
+    '      position += bytes;',
+    "      carry = (carry + buffer.subarray(0, bytes).toString('utf8')).slice(-262144);",
+    '      inspect(carry);',
+    '    }',
+    '  } catch {}',
+    '  setTimeout(poll, 1000);',
+    '}',
+    'poll();',
+  ].join('\n');
+}
+
 function withSettingsLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
   const prev = settingsWriteLocks.get(path) ?? Promise.resolve();
   const run = prev.then(fn, fn); // run after the prior writer, regardless of its outcome
@@ -86,36 +184,118 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
       Notification: [
         {
           matcher: 'idle_prompt',
-          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('idle_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'permission_prompt',
-          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('permission_prompt'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
         {
           matcher: 'elicitation_dialog',
-          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('elicitation_dialog'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       Stop: [
         {
-          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('stop'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TeammateIdle: [
         {
-          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('teammate_idle'), timeout: HOOK_TIMEOUT_SECONDS }],
         },
       ],
       TaskCompleted: [
         {
-          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_MS }],
+          hooks: [{ type: 'command', command: curlCmd('task_completed'), timeout: HOOK_TIMEOUT_SECONDS }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: 'node',
+              args: ['-e', generateBackgroundWakeScript()],
+              asyncRewake: true,
+              timeout: BACKGROUND_WAKE_TIMEOUT_SECONDS,
+            },
+          ],
         },
       ],
     },
   };
 }
 
+function isCodemanHookHandler(value: unknown): boolean {
+  try {
+    const serialized = JSON.stringify(value);
+    // Prefix, not the versioned marker: older script versions must still be ours.
+    return serialized.includes('/api/hook-event') || serialized.includes(BACKGROUND_WAKE_MARKER_PREFIX);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Replace only Codeman-owned command handlers while preserving user events,
+ * matcher entries, and sibling handlers in mixed entries.
+ */
+function mergeCodemanHooks(existingValue: unknown, generated: Record<string, unknown[]>): Record<string, unknown[]> {
+  const existing =
+    existingValue && typeof existingValue === 'object' && !Array.isArray(existingValue)
+      ? (existingValue as Record<string, unknown>)
+      : {};
+  const merged: Record<string, unknown[]> = {};
+
+  for (const eventName of new Set([...Object.keys(existing), ...Object.keys(generated)])) {
+    const existingEntries = Array.isArray(existing[eventName]) ? (existing[eventName] as unknown[]) : [];
+    const generatedEntries = generated[eventName];
+    if (!generatedEntries) {
+      merged[eventName] = existingEntries;
+      continue;
+    }
+
+    const entries: unknown[] = [];
+    let insertedGenerated = false;
+    for (const entry of existingEntries) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        if (!isCodemanHookHandler(entry)) entries.push(entry);
+        continue;
+      }
+
+      const record = entry as Record<string, unknown>;
+      if (!Array.isArray(record.hooks)) {
+        if (isCodemanHookHandler(record)) {
+          if (!insertedGenerated) {
+            entries.push(...generatedEntries);
+            insertedGenerated = true;
+          }
+        } else {
+          entries.push(entry);
+        }
+        continue;
+      }
+
+      const retainedHandlers = record.hooks.filter((handler) => !isCodemanHookHandler(handler));
+      const removedCodemanHandler = retainedHandlers.length !== record.hooks.length;
+      if (removedCodemanHandler && !insertedGenerated) {
+        entries.push(...generatedEntries);
+        insertedGenerated = true;
+      }
+      if (retainedHandlers.length > 0 || !removedCodemanHandler) {
+        entries.push(retainedHandlers.length === record.hooks.length ? entry : { ...record, hooks: retainedHandlers });
+      }
+    }
+
+    if (!insertedGenerated) entries.push(...generatedEntries);
+    merged[eventName] = entries;
+  }
+
+  return merged;
+}
+
 /**
  * Remove a subset of env keys from .claude/settings.local.json.env if present.
  * Used during the disk→tmux-setenv migration: when the caller is actively setting
@@ -237,29 +417,31 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
     }
 
     const hooksConfig = generateHooksConfig();
-    const merged = { ...existing, ...hooksConfig };
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, hooksConfig.hooks),
+    };
 
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }
 
 /**
- * Self-heal a case's hooks block so the COD-91 unconditional hook-secret gate keeps
- * accepting its hook events.
+ * Self-heal a case's Codeman-owned hooks block.
  *
  * `writeHooksConfig` only runs when a case is first CREATED. Cases created before the
  * X-Codeman-Hook-Secret header was added (COD-54, 2026-06-10) keep hook curls in their
  * settings.local.json that POST to /api/hook-event WITHOUT the secret — which, once the
- * gate requires it unconditionally (COD-91), silently 401 on a password-protected
- * install. This refreshes the hooks block so those stale curls regain the header.
+ * gate requires it unconditionally (COD-91), silently 401 on a password-protected install.
+ * Older Codeman blocks also lack the background Bash async-rewake hook. Refresh either
+ * stale shape on launch so existing cases gain both current behaviors.
  *
  * Deliberately surgical: regenerates ONLY when settings.local.json already contains
- * Codeman's own hook curls (they target `/api/hook-event`) that lack the secret header.
- * No-op when the file/hooks are absent (we never impose hooks on a user who removed
- * them), when the hooks aren't ours, or when the secret is already present — so it never
- * clobbers a user's customizations and is cheap enough to call on every Claude spawn.
+ * Codeman's own hook curls (they target `/api/hook-event`) and they are stale. No-op
+ * when the file/hooks are absent (we never impose hooks on a user who removed them) or
+ * when the hooks aren't ours, so it is cheap enough to call on every Claude spawn.
  */
-export async function refreshStaleHookSecret(casePath: string): Promise<void> {
+export async function refreshStaleCodemanHooks(casePath: string): Promise<void> {
   const settingsPath = join(casePath, '.claude', 'settings.local.json');
   if (!existsSync(settingsPath)) return;
   await withSettingsLock(settingsPath, async () => {
@@ -274,8 +456,13 @@ export async function refreshStaleHookSecret(casePath: string): Promise<void> {
     // The generated curl carries this header literal (see generateHooksConfig); its
     // absence on our own hooks means they predate COD-54 and need regenerating.
     const hasSecret = hooksJson.includes('X-Codeman-Hook-Secret');
-    if (!isOurs || hasSecret) return;
-    const merged = { ...existing, ...generateHooksConfig() };
+    const hasBackgroundWake = hooksJson.includes(BACKGROUND_WAKE_MARKER);
+    if (!isOurs || (hasSecret && hasBackgroundWake)) return;
+    const generated = generateHooksConfig();
+    const merged = {
+      ...existing,
+      hooks: mergeCodemanHooks(existing.hooks, generated.hooks),
+    };
     await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
   });
 }

src/index.ts

@@ -14,6 +14,18 @@ import { program } from './cli.js';
 // In web mode, we should NOT exit on transient errors — log and continue
 const isWebMode = process.argv.includes('web');
 
+// COD-115: Codeman IS a tmux controller; it must never present as a tmux *client*.
+// If the web server is launched from inside a tmux pane it inherits TMUX/TMUX_PANE,
+// and tmux's nesting guard then kills every new attach-bridge PTY (exit 1 → respawn
+// loop, crash-looping any new tmux-backed session). Scrub at the root so every
+// downstream `{...process.env}` spread (attach, send-keys, create) is clean regardless
+// of launch context. `delete` (not `= undefined`, which node-pty serializes as the
+// literal string "undefined" and fails to clear).
+if (isWebMode) {
+  delete process.env.TMUX;
+  delete process.env.TMUX_PANE;
+}
+
 import { MAX_CONSECUTIVE_ERRORS, ERROR_RESET_MS } from './config/server-timing.js';
 
 // Track consecutive unhandled errors in web mode — restart after too many

src/mux-interface.ts

@@ -16,6 +16,10 @@ import type {
   OpenCodeConfig,
   CodexConfig,
   EffortLevel,
+  GeminiConfig,
+  AntigravityConfig,
+  SessionRemote,
+  SessionDocker,
 } from './types.js';
 
 /**
@@ -32,6 +36,12 @@ export interface MuxSession {
   createdAt: number;
   /** Working directory */
   workingDir: string;
+  /** Remote execution metadata for local tmux sessions wrapping SSH */
+  remote?: SessionRemote;
+  /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
+  docker?: SessionDocker;
+  /** Owning username in multi-user mode (round-tripped through recovery like remote/docker) */
+  owner?: string;
   /** Session mode */
   mode: SessionMode;
   /** Whether webserver is attached to this session */
@@ -64,12 +74,22 @@ export interface CreateSessionOptions {
   allowedTools?: string;
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
+  geminiConfig?: GeminiConfig;
+  antigravityConfig?: AntigravityConfig;
   /** When restoring after reboot, resume a previous Claude conversation by its session ID */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level, injected as a `--settings` soft default (overridable via /effort in-session) */
   effort?: EffortLevel;
+  /** tmux history-limit (scrollback lines) to set for this session. */
+  historyLimit?: number;
+  /** Remote execution metadata for local tmux sessions wrapping SSH */
+  remote?: SessionRemote;
+  /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
+  docker?: SessionDocker;
+  /** Owning username in multi-user mode; persisted for recovery. */
+  owner?: string;
 }
 
 /** Options for respawning a dead pane. */
@@ -83,12 +103,36 @@ export interface RespawnPaneOptions {
   allowedTools?: string;
   openCodeConfig?: OpenCodeConfig;
   codexConfig?: CodexConfig;
+  geminiConfig?: GeminiConfig;
+  antigravityConfig?: AntigravityConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (preserved across respawns). */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level (preserved across respawns, injected via `--settings`) */
   effort?: EffortLevel;
+  /** tmux history-limit (scrollback lines) to set for this session after respawn. */
+  historyLimit?: number;
+  /** Remote execution metadata for local tmux sessions wrapping SSH */
+  remote?: SessionRemote;
+  /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
+  docker?: SessionDocker;
+  /** Owning username (multi-user); redundant on respawn since the Session object survives, kept for shape parity. */
+  owner?: string;
+}
+
+/** Options for pane buffer capture (COD-47 full-history mode). */
+export interface PaneCaptureOptions {
+  /** Capture the entire tmux scrollback instead of just the visible frame. */
+  fullHistory?: boolean;
+  /** Bound the full-history capture to this many scrollback lines (`-S -<N>`). */
+  historyLimitLines?: number;
+  /**
+   * Byte cap the consumer will keep from the capture. Sizes the child-process
+   * stdout buffer (with slack) so multi-MB scrollback dumps aren't killed by
+   * the 1MB execSync default (ENOBUFS).
+   */
+  maxCaptureBytes?: number;
 }
 
 /**
@@ -167,6 +211,9 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Update Ralph enabled state for a session */
   updateRalphEnabled(sessionId: string, enabled: boolean): void;
 
+  /** Apply a tmux history-limit to all tracked sessions. */
+  setHistoryLimit(limit: number): Promise<void>;
+
   // ========== Discovery ==========
 
   /**
@@ -215,9 +262,16 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Respawn a dead pane with a fresh command. Returns the new PID or null on failure. */
   respawnPane(options: RespawnPaneOptions): Promise<number | null>;
 
-  /** Capture a pane's current tmux buffer with ANSI escape codes preserved. */
-  capturePaneBuffer?(muxName: string, paneTarget: string): string | null;
+  /**
+   * Capture a pane's current tmux buffer with ANSI escape codes preserved.
+   * Pass `{ fullHistory: true }` to capture the entire scrollback as linear
+   * text instead of just the visible single-screen frame (COD-47).
+   */
+  capturePaneBuffer?(muxName: string, paneTarget?: string, opts?: PaneCaptureOptions): string | null;
 
-  /** Capture the active pane's current tmux buffer with ANSI escape codes preserved. */
-  captureActivePaneBuffer?(muxName: string): string | null;
+  /**
+   * Capture the active pane's current tmux buffer with ANSI escape codes preserved.
+   * Pass `{ fullHistory: true }` to capture the entire scrollback (COD-47).
+   */
+  captureActivePaneBuffer?(muxName: string, opts?: PaneCaptureOptions): string | null;
 }

src/plan-orchestrator.ts

@@ -20,7 +20,7 @@ import type { TerminalMultiplexer } from './mux-interface.js';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { RESEARCH_AGENT_PROMPT, PLANNER_PROMPT } from './prompts/index.js';
-import { getErrorMessage, type PlanItem } from './types.js';
+import { getErrorMessage, type PlanItem, type ClaudeMode } from './types.js';
 
 // Re-export for backward compatibility
 export type { PlanItem };
@@ -130,18 +130,28 @@ export class PlanOrchestrator {
   private taskDescription = '';
   private researchModel: string;
   private plannerModel: string;
+  // Multi-user permission threading: the resolved claudeMode/owner/allowedTools for the
+  // internal research/planner one-shots. Left undefined = today's single-user behavior
+  // (the caller threads the resolved global mode, byte-identical when !isMultiUserMode()).
+  private claudeMode?: ClaudeMode;
+  private owner?: string;
+  private allowedTools?: string;
 
   constructor(
     mux: TerminalMultiplexer,
     workingDir: string = process.cwd(),
     outputDir?: string,
-    modelConfig?: { defaultModel?: string; agentTypeOverrides?: Record<string, string> }
+    modelConfig?: { defaultModel?: string; agentTypeOverrides?: Record<string, string> },
+    security?: { claudeMode?: ClaudeMode; owner?: string; allowedTools?: string }
   ) {
     this.mux = mux;
     this.workingDir = workingDir;
     this.outputDir = outputDir;
     this.researchModel = modelConfig?.agentTypeOverrides?.explore || modelConfig?.defaultModel || DEFAULT_MODEL;
     this.plannerModel = modelConfig?.agentTypeOverrides?.review || modelConfig?.defaultModel || DEFAULT_MODEL;
+    this.claudeMode = security?.claudeMode;
+    this.owner = security?.owner;
+    this.allowedTools = security?.allowedTools;
   }
 
   private saveAgentOutput(agentType: string, prompt: string, result: unknown, durationMs: number): void {
@@ -424,6 +434,12 @@ export class PlanOrchestrator {
       mux: this.mux,
       useMux: false,
       mode: 'claude',
+      // Section 6.3: run this one-shot under the caller-resolved permission mode/owner so a
+      // non-granted multi-user user cannot regain --dangerously-skip-permissions. Undefined
+      // (single-user, not threaded) is byte-identical to today (Session keeps its default).
+      claudeMode: this.claudeMode,
+      allowedTools: this.allowedTools,
+      owner: this.owner,
     });
 
     this.runningSessions.add(session);
@@ -580,6 +596,10 @@ export class PlanOrchestrator {
       mux: this.mux,
       useMux: false,
       mode: 'claude',
+      // Section 6.3: same permission-mode/owner threading as the research one-shot above.
+      claudeMode: this.claudeMode,
+      allowedTools: this.allowedTools,
+      owner: this.owner,
     });
 
     this.runningSessions.add(session);

src/push-store.ts

@@ -9,10 +9,23 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import webpush from 'web-push';
-import type { VapidKeys, PushSubscriptionRecord } from './types.js';
+import type { VapidKeys, PushSubscriptionRecord, UserRole } from './types.js';
 import { Debouncer } from './utils/index.js';
 import { getDataDir } from './config/instance.js';
 
+/**
+ * A push subscription plus the multi-user owner identity stamped at subscribe time.
+ * `username`/`role` are undefined in single-user mode (and for legacy records saved
+ * before this field existed). sendPushNotifications uses them to scope a
+ * session-notification to its owner's devices (+ admins) instead of fanning out to
+ * every user. Kept as a store-local widening of PushSubscriptionRecord so the shared
+ * type stays untouched; the extra keys serialize/persist transparently.
+ */
+export type OwnedPushSubscriptionRecord = PushSubscriptionRecord & {
+  username?: string;
+  role?: UserRole;
+};
+
 const DATA_DIR = getDataDir();
 const KEYS_FILE = join(DATA_DIR, 'push-keys.json');
 const SUBS_FILE = join(DATA_DIR, 'push-subscriptions.json');
@@ -20,7 +33,7 @@ const SAVE_DEBOUNCE_MS = 500;
 
 export class PushSubscriptionStore {
   private vapidKeys: VapidKeys | null = null;
-  private subscriptions: Map<string, PushSubscriptionRecord> = new Map();
+  private subscriptions: Map<string, OwnedPushSubscriptionRecord> = new Map();
   private saveDeb = new Debouncer(SAVE_DEBOUNCE_MS);
   private _disposed = false;
 
@@ -67,17 +80,19 @@ export class PushSubscriptionStore {
   }
 
   /** Register or update a push subscription (deduplicates by endpoint) */
-  addSubscription(sub: Omit<PushSubscriptionRecord, 'lastUsedAt'>): PushSubscriptionRecord {
+  addSubscription(sub: Omit<OwnedPushSubscriptionRecord, 'lastUsedAt'>): OwnedPushSubscriptionRecord {
     // Check for existing subscription with same endpoint
     for (const [existingId, existing] of this.subscriptions) {
       if (existing.endpoint === sub.endpoint) {
-        // Update existing
-        const updated: PushSubscriptionRecord = {
+        // Update existing (re-stamp owner identity so it tracks the current caller)
+        const updated: OwnedPushSubscriptionRecord = {
           ...existing,
           keys: sub.keys,
           userAgent: sub.userAgent,
           lastUsedAt: Date.now(),
           pushPreferences: sub.pushPreferences,
+          username: sub.username,
+          role: sub.role,
         };
         this.subscriptions.set(existingId, updated);
         this.scheduleSave();
@@ -86,7 +101,7 @@ export class PushSubscriptionStore {
     }
 
     // New subscription
-    const record: PushSubscriptionRecord = {
+    const record: OwnedPushSubscriptionRecord = {
       ...sub,
       lastUsedAt: Date.now(),
     };
@@ -96,7 +111,7 @@ export class PushSubscriptionStore {
   }
 
   /** Update push preferences for a subscription */
-  updatePreferences(id: string, preferences: Record<string, boolean>): PushSubscriptionRecord | null {
+  updatePreferences(id: string, preferences: Record<string, boolean>): OwnedPushSubscriptionRecord | null {
     const sub = this.subscriptions.get(id);
     if (!sub) return null;
     sub.pushPreferences = preferences;
@@ -124,12 +139,12 @@ export class PushSubscriptionStore {
   }
 
   /** Get all subscriptions */
-  getAll(): PushSubscriptionRecord[] {
+  getAll(): OwnedPushSubscriptionRecord[] {
     return Array.from(this.subscriptions.values());
   }
 
   /** Get a single subscription by ID */
-  get(id: string): PushSubscriptionRecord | null {
+  get(id: string): OwnedPushSubscriptionRecord | null {
     return this.subscriptions.get(id) ?? null;
   }
 
@@ -138,7 +153,7 @@ export class PushSubscriptionStore {
     if (!existsSync(SUBS_FILE)) return;
     try {
       const raw = readFileSync(SUBS_FILE, 'utf-8');
-      const arr = JSON.parse(raw) as PushSubscriptionRecord[];
+      const arr = JSON.parse(raw) as OwnedPushSubscriptionRecord[];
       for (const sub of arr) {
         this.subscriptions.set(sub.id, sub);
       }

src/ralph-tracker.ts

@@ -467,6 +467,12 @@ export class RalphTracker extends EventEmitter {
   /** Timestamp of last cleanup check for throttling */
   private _lastCleanupTime: number = 0;
 
+  /** Maximum number of todos retained for this session (defaults to global cap) */
+  private _maxTodos: number = MAX_TODOS_PER_SESSION;
+
+  /** Todo auto-expiry duration in milliseconds (defaults to global constant) */
+  private _todoExpiryMs: number = TODO_EXPIRY_MS;
+
   /** Debouncer for todoUpdate events */
   private _todoDeb = new Debouncer(EVENT_DEBOUNCE_MS);
 
@@ -1053,6 +1059,10 @@ export class RalphTracker extends EventEmitter {
       planVersion: this.planTracker.planVersion,
       planHistoryLength: this.planTracker.getPlanHistory().length,
       completionConfidence: this._lastCompletionConfidence,
+      // Surface the live todo-config so it persists (toState) and reads back into
+      // the Session Options modal (broadcast) — mirrors maxIterations round-trip.
+      maxTodos: this._maxTodos,
+      todoExpirationMinutes: this.todoExpirationMinutes,
     };
   }
 
@@ -1840,7 +1850,7 @@ export class RalphTracker extends EventEmitter {
         return;
       }
 
-      while (this._todos.size >= MAX_TODOS_PER_SESSION) {
+      while (this._todos.size >= this._maxTodos) {
         const oldest = this.findOldestTodo();
         if (oldest) {
           this._todos.delete(oldest.id);
@@ -2164,14 +2174,14 @@ export class RalphTracker extends EventEmitter {
   }
 
   /**
-   * Remove todo items older than TODO_EXPIRY_MS.
+   * Remove todo items older than the configured expiry duration.
    */
   private cleanupExpiredTodos(): void {
     const now = Date.now();
     const toDelete: string[] = [];
 
     for (const [id, todo] of this._todos) {
-      if (now - todo.detectedAt > TODO_EXPIRY_MS) {
+      if (now - todo.detectedAt > this._todoExpiryMs) {
         toDelete.push(id);
       }
     }
@@ -2211,6 +2221,34 @@ export class RalphTracker extends EventEmitter {
     this.emit('loopUpdate', this.loopState);
   }
 
+  /** Maximum number of todos retained for this session. */
+  get maxTodos(): number {
+    return this._maxTodos;
+  }
+
+  /** Todo auto-expiry duration in minutes for this session. */
+  get todoExpirationMinutes(): number {
+    return Math.round(this._todoExpiryMs / 60000);
+  }
+
+  /**
+   * Update the maximum number of retained todos (external API).
+   * Ignores non-positive values.
+   */
+  setMaxTodos(maxTodos: number): void {
+    if (!Number.isFinite(maxTodos) || maxTodos <= 0) return;
+    this._maxTodos = Math.floor(maxTodos);
+  }
+
+  /**
+   * Update the todo auto-expiry duration (external API), specified in minutes.
+   * Converts to milliseconds internally. Ignores non-positive values.
+   */
+  setTodoExpirationMinutes(minutes: number): void {
+    if (!Number.isFinite(minutes) || minutes <= 0) return;
+    this._todoExpiryMs = Math.floor(minutes) * 60000;
+  }
+
   /**
    * Configure the tracker from external state.
    */
@@ -2311,6 +2349,12 @@ export class RalphTracker extends EventEmitter {
       ...loopState,
       enabled: loopState.enabled ?? false,
     };
+    // Restore the per-session todo-config into the live fields used by the hot
+    // paths (eviction cap + expiry). Setters ignore non-positive values.
+    if (typeof loopState.maxTodos === 'number') this.setMaxTodos(loopState.maxTodos);
+    if (typeof loopState.todoExpirationMinutes === 'number') {
+      this.setTodoExpirationMinutes(loopState.todoExpirationMinutes);
+    }
     this._todos.clear();
     for (const todo of todos) {
       this._todos.set(todo.id, {

src/remote-hosts.ts

@@ -0,0 +1,424 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import type {
+  RemoteCase,
+  RemoteCommandMode,
+  RemoteHost,
+  RemoteSessionInfo,
+  RemoteSshOptions,
+  SessionMode,
+  SessionRemote,
+} from './types.js';
+
+const execAsync = promisify(exec);
+
+const REMOTE_HOSTS_FILE = 'remote-hosts.json';
+const REMOTE_CASES_FILE = 'remote-cases.json';
+
+export function remoteHostsPath(configDir: string): string {
+  return join(configDir, REMOTE_HOSTS_FILE);
+}
+
+export function remoteCasesPath(configDir: string): string {
+  return join(configDir, REMOTE_CASES_FILE);
+}
+
+async function readJsonArray<T>(path: string): Promise<T[]> {
+  try {
+    const raw = await fs.readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? (parsed as T[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+async function writeJsonArray<T>(configDir: string, path: string, value: T[]): Promise<void> {
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+  await fs.writeFile(path, JSON.stringify(value, null, 2));
+}
+
+export async function readRemoteHosts(configDir: string): Promise<RemoteHost[]> {
+  return readJsonArray<RemoteHost>(remoteHostsPath(configDir));
+}
+
+export async function writeRemoteHosts(configDir: string, hosts: RemoteHost[]): Promise<void> {
+  await writeJsonArray(configDir, remoteHostsPath(configDir), hosts);
+}
+
+export async function readRemoteCases(configDir: string): Promise<RemoteCase[]> {
+  return readJsonArray<RemoteCase>(remoteCasesPath(configDir));
+}
+
+export async function writeRemoteCases(configDir: string, cases: RemoteCase[]): Promise<void> {
+  await writeJsonArray(configDir, remoteCasesPath(configDir), cases);
+}
+
+/**
+ * The remote user's login shell, defaulted and quoted.
+ *
+ * The default is belt-and-braces, not a live bug: an empty `$SHELL` would expand
+ * to `exec  -i -l`, which the shell reads as `exec -i` — "not found", pane dead on
+ * arrival, the #208 failure all over again (verified: `sh -c 'exec $SHELL -i -l'`
+ * with SHELL unset prints `exec: -i: not found`). In practice tmux always exports
+ * SHELL into a pane from its own `default-shell` option, so the command as USED
+ * here is safe either way (also verified). The default matters because these
+ * strings are the seed values a per-host `commands.*` override is edited from, and
+ * nothing constrains where an edited one ends up running. Quoted for a shell path
+ * containing spaces. `/bin/sh` exists on every POSIX host.
+ */
+const REMOTE_LOGIN_SHELL = '"${SHELL:-/bin/sh}"';
+
+/**
+ * Run `command` through the remote user's interactive login shell, so per-user
+ * PATH entries (~/.local/bin, ~/.opencode/bin, …) are resolved before the CLI name
+ * is looked up. ssh's remote-command execution is neither interactive nor login,
+ * so a bare `exec claude` sees only sshd's minimal default PATH and dies with
+ * "command not found" (exit 127).
+ *
+ * Shells that take neither flag (nushell, elvish, …) cannot be detected from here
+ * the way `loginShellArgs()` detects them locally, since the shell is whatever the
+ * REMOTE passwd says. A host like that is what the per-host `commands.*` override
+ * is for.
+ */
+export function remoteLoginShellCommand(command: string): string {
+  return `exec ${REMOTE_LOGIN_SHELL} -i -l -c ${shellescape(command)}`;
+}
+
+export function defaultRemoteCommandForMode(mode: SessionMode): string {
+  // Agent CLIs (claude/opencode/codex/gemini/antigravity) are typically installed
+  // under per-user paths like ~/.local/bin or ~/.opencode/bin, added to PATH only by
+  // the remote user's interactive-login shell startup files (~/.zshrc etc.). ssh's
+  // remote-command execution is neither interactive nor login, so a bare `exec
+  // claude` sees only sshd's minimal default PATH and fails with "command not
+  // found" (exit 127) — confirmed via `tmux capture-pane` on the
+  // remain-on-exit-preserved dead pane. Route through `$SHELL -i -l -c`, the same
+  // fix already used for shell mode below, so PATH is fully resolved before the
+  // CLI name is looked up.
+  const commands: Record<RemoteCommandMode, string> = {
+    // $SHELL, not a hardcoded bash: sshd sets it from the remote user's
+    // /etc/passwd entry, so this launches their actual login shell (zsh,
+    // fish, etc.). -i -l so it sources rc files (~/.zshrc etc.), matching
+    // the local shell-mode launch.
+    shell: `exec ${REMOTE_LOGIN_SHELL} -i -l`,
+    // Mirror the LOCAL claude default so the remote agent runs non-interactively
+    // (no trust-folder/permission prompt that nothing on the remote answers). The
+    // per-host `commands.claude` override stays the escape hatch.
+    claude: remoteLoginShellCommand('claude --dangerously-skip-permissions'),
+    opencode: remoteLoginShellCommand('opencode'),
+    codex: remoteLoginShellCommand('codex'),
+    gemini: remoteLoginShellCommand('gemini'),
+    antigravity: remoteLoginShellCommand('agy'),
+  };
+  return commands[mode as RemoteCommandMode] || commands.shell;
+}
+
+export function remoteSshTarget(host: Pick<RemoteHost, 'username' | 'host'>): string {
+  return `${host.username}@${host.host}`;
+}
+
+/**
+ * POSIX single-quote shell-escaping (end-quote, escaped-quote, restart-quote).
+ * Mirrors the helper in tmux-manager.ts so a value with spaces/metachars stays a
+ * single shell token. Used here for identity paths and `-o KEY=VALUE` options.
+ */
+function shellescape(str: string): string {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Expand a leading `~` or `$HOME` in an identity path to an absolute path.
+ *
+ * ssh does NOT expand `~` inside `-i` (the shell would, but we shellescape the
+ * value into a single quoted token so the shell never sees it). So we expand at
+ * build time, before escaping. Non-`~`/`$HOME` paths are returned unchanged.
+ */
+function expandIdentityPath(identityFile: string): string {
+  if (identityFile === '~') return homedir();
+  if (identityFile.startsWith('~/')) return join(homedir(), identityFile.slice(2));
+  if (identityFile === '$HOME') return homedir();
+  if (identityFile.startsWith('$HOME/')) return join(homedir(), identityFile.slice('$HOME/'.length));
+  return identityFile;
+}
+
+/**
+ * COD-107 — build the ordered, shell-safe ssh CONNECTION tokens shared by both
+ * the durable-launch command (`buildRemoteLaunchCommand`) and the tmux
+ * prerequisite probe (`buildRemoteTmuxCheckCommand`), so the prereq check and
+ * the real launch connect with IDENTICAL options (they can't drift).
+ *
+ * Returns the leading tokens of an ssh command line (NOT including `-t`, the
+ * target, or any remote command). Order:
+ *   ssh -o BatchMode=yes
+ *       [-o ConnectTimeout=10]           (default; suppressed if extraSshOptions sets it)
+ *       [-p <port>]
+ *       [-i <abs-identity>]              (~/$HOME expanded, then shellescaped)
+ *       [-J <jumpHost>]                  (shellescaped, single token)
+ *       [-o ProxyCommand=nc -X 5 -x <socks> %h %p]   (ONE shellescaped -o token)
+ *       [-o <KEY=VALUE>] …               (each extra option, shellescaped)
+ *
+ * Escaping notes (the risky part):
+ *  - The ProxyCommand is emitted as a single shellescaped `-o KEY=VALUE`, so the
+ *    whole value (spaces + `%h`/`%p`) reaches ssh as one argument and `%h %p`
+ *    survive verbatim — ssh expands them to the real host/port, not the shell.
+ *  - A default `-o ConnectTimeout=10` bounds the wait on an unreachable/blackholed
+ *    host (else the pane hangs on the OS TCP timeout). It is omitted when the
+ *    operator already set ConnectTimeout via extraSshOptions, so their value wins.
+ */
+export function buildSshConnectionArgs(remote: RemoteSshOptions & Pick<RemoteHost, 'port'>): string[] {
+  const parts: string[] = ['ssh', '-o BatchMode=yes'];
+  const hasConnectTimeout = (remote.extraSshOptions ?? []).some((opt) => /^ConnectTimeout=/i.test(opt));
+  if (!hasConnectTimeout) parts.push('-o ConnectTimeout=10');
+  if (remote.port) parts.push(`-p ${remote.port}`);
+  if (remote.identityFile) parts.push(`-i ${shellescape(expandIdentityPath(remote.identityFile))}`);
+  if (remote.jumpHost) parts.push(`-J ${shellescape(remote.jumpHost)}`);
+  if (remote.socksProxy) {
+    parts.push(`-o ${shellescape(`ProxyCommand=nc -X 5 -x ${remote.socksProxy} %h %p`)}`);
+  }
+  for (const opt of remote.extraSshOptions ?? []) {
+    parts.push(`-o ${shellescape(opt)}`);
+  }
+  return parts;
+}
+
+/**
+ * COD-104 — build the SSH command that checks the remote host has tmux.
+ *
+ * Durable remote sessions run the agent inside a tmux server ON the remote host
+ * (`tmux -L codeman new-session -A …`), so tmux is now a hard prerequisite there.
+ * `command -v tmux` exits 0 (and prints the path) when tmux is installed.
+ *
+ * COD-107 — connects with the SAME options as the real launch
+ * (`buildSshConnectionArgs`) so a proxied/custom-port/identity host that the
+ * launch can reach also passes the prereq probe (and vice-versa).
+ */
+export function buildRemoteTmuxCheckCommand(
+  host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions
+): string {
+  // ConnectTimeout is now a default of buildSshConnectionArgs (shared with the launch).
+  return [...buildSshConnectionArgs(host), remoteSshTarget(host), "'command -v tmux'"].join(' ');
+}
+
+export interface RemoteTmuxCheckResult {
+  ok: boolean;
+  /** Resolved tmux path on the remote (when ok). */
+  tmuxPath?: string;
+  /** Human-readable failure reason (when !ok). */
+  error?: string;
+}
+
+/**
+ * COD-104 — verify the remote host has tmux installed (required for durable
+ * remote sessions). Returns a structured result with a clear, user-facing error
+ * when tmux is missing or the host is unreachable. Never throws.
+ */
+export async function checkRemoteTmuxAvailable(
+  host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions
+): Promise<RemoteTmuxCheckResult> {
+  // Under vitest, never open a real ssh connection — mirrors TmuxManager's
+  // no-op-shell-under-VITEST (IS_TEST_MODE). Without this, remote-case
+  // create-path tests hit a real ~10s ssh timeout. The command construction is
+  // covered by buildRemoteTmuxCheckCommand unit tests; only the live probe is
+  // short-circuited here.
+  if (process.env.VITEST) {
+    return { ok: true, tmuxPath: '(test-mode)' };
+  }
+  const command = buildRemoteTmuxCheckCommand(host);
+  try {
+    const { stdout } = await execAsync(command, { timeout: 15_000 });
+    const tmuxPath = stdout.trim();
+    if (!tmuxPath) {
+      return {
+        ok: false,
+        error: `remote host ${host.host} needs tmux installed for durable remote sessions`,
+      };
+    }
+    return { ok: true, tmuxPath };
+  } catch (err) {
+    const stderr =
+      err && typeof err === 'object' && 'stderr' in err ? String((err as { stderr?: unknown }).stderr ?? '') : '';
+    // `command -v tmux` exits non-zero when tmux is absent (no stderr); a real
+    // connection failure surfaces ssh diagnostics on stderr.
+    if (stderr.trim()) {
+      return {
+        ok: false,
+        error: `could not verify tmux on remote host ${host.host}: ${stderr.trim()}`,
+      };
+    }
+    return {
+      ok: false,
+      error: `remote host ${host.host} needs tmux installed for durable remote sessions`,
+    };
+  }
+}
+
+/**
+ * COD-105 — build the SSH command that lists `codeman-*` tmux sessions on a
+ * remote host's canonical `-L codeman` socket.
+ *
+ * `list-sessions` exits NON-ZERO with empty output when no sessions exist (and
+ * the server isn't running), so `2>/dev/null` swallows tmux's "no server
+ * running" stderr; the caller treats a non-zero exit / empty output as "no
+ * sessions" rather than an error.
+ *
+ * COD-107 — connection options come from the shared `buildSshConnectionArgs`, so
+ * discovery connects with the SAME port/identity/proxy/jump-host as the launch
+ * and the tmux prereq probe.
+ */
+export function buildRemoteListSessionsCommand(
+  host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions
+): string {
+  const [ssh, ...connectionArgs] = buildSshConnectionArgs(host);
+  const parts = [ssh, connectionArgs[0], '-o ConnectTimeout=10', ...connectionArgs.slice(1)];
+  // The tmux list-sessions invocation is passed as ONE shell-quoted argument so
+  // the remote login shell runs it verbatim. The `-F` format uses literal `\t`
+  // separators (tmux expands them); `2>/dev/null` is inside the quoted command.
+  const remoteCmd =
+    'tmux -L codeman list-sessions -F "#{session_name}\\t#{session_attached}\\t#{session_created}\\t#{session_windows}" 2>/dev/null';
+  parts.push(remoteSshTarget(host), shellescape(remoteCmd));
+  return parts.join(' ');
+}
+
+/**
+ * COD-105 — pure parser for the `tmux list-sessions -F` output emitted by
+ * `buildRemoteListSessionsCommand`. Factored out so the parse is unit-testable
+ * without opening a real ssh connection.
+ *
+ * - Splits each non-empty line into [name, attached, created, windows] on the
+ *   field separator. IMPORTANT: the remote tmux's `-F "…\t…"` format does NOT
+ *   expand `\t` to a real tab — it emits the LITERAL two-character sequence
+ *   `\t` (verified on aa-desktop / tmux next-3.7). So we split on the literal
+ *   backslash-t sequence; we also tolerate a real tab in case a tmux build
+ *   does expand it. (A real TAB is the regex `\t`; a literal backslash-t is the
+ *   regex `\\t`.)
+ * - Keeps ONLY sessions whose name starts with `codeman-` (ignores foreign tmux
+ *   sessions that happen to share the socket).
+ * - Coerces: `attached` → boolean (`'1'`), `created`/`windows` → finite ints.
+ * - Skips malformed lines (wrong column count or non-numeric created/windows)
+ *   rather than emitting garbage.
+ */
+export function parseRemoteSessionList(stdout: string): RemoteSessionInfo[] {
+  const out: RemoteSessionInfo[] = [];
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    // Split on a literal `\t` (backslash + t, what the remote tmux emits) OR a
+    // real tab character. `/\\t|\t/` = the two-char sequence, or a TAB.
+    const cols = line.split(/\\t|\t/);
+    if (cols.length !== 4) continue;
+    const [name, attachedStr, createdStr, windowsStr] = cols;
+    if (!name.startsWith('codeman-')) continue;
+    const created = Number(createdStr);
+    const windows = Number(windowsStr);
+    if (!Number.isFinite(created) || !Number.isFinite(windows)) continue;
+    // COD-106 — `session_attached` is the CLIENT COUNT (not a 0/1 flag); >1 = shared.
+    const attachedNum = Number(attachedStr.trim());
+    const attachedClients = Number.isFinite(attachedNum) ? Math.max(0, Math.trunc(attachedNum)) : 0;
+    out.push({
+      name,
+      attached: attachedClients > 0,
+      attachedClients,
+      created: Math.trunc(created),
+      windows: Math.trunc(windows),
+    });
+  }
+  return out;
+}
+
+/**
+ * COD-105 — discover `codeman-*` tmux sessions already running on a remote host
+ * (created by the remote's own Codeman, another instance, or this one), so the
+ * operator can attach to one this Codeman didn't launch.
+ *
+ * NEVER throws: returns `[]` on unreachable host / no tmux / no sessions
+ * (`list-sessions` exits non-zero with empty output when there are none).
+ *
+ * VITEST guard — like `checkRemoteTmuxAvailable`, returns `[]` under test so a
+ * real ssh never runs in a request path (which would make route tests hit a
+ * ~10s timeout). The command construction is covered by
+ * `buildRemoteListSessionsCommand` and the parse by `parseRemoteSessionList`.
+ */
+export async function listRemoteCodemanSessions(
+  remote: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions
+): Promise<RemoteSessionInfo[]> {
+  if (process.env.VITEST) {
+    return [];
+  }
+  const command = buildRemoteListSessionsCommand(remote);
+  try {
+    const { stdout } = await execAsync(command, { timeout: 15_000 });
+    return parseRemoteSessionList(stdout);
+  } catch {
+    // Unreachable host, no tmux server, or no sessions (non-zero exit). All map
+    // to "nothing to attach to" — never surface as an error to the caller.
+    return [];
+  }
+}
+
+export function remoteDisplayPath(
+  remote: Pick<SessionRemote, 'username' | 'host' | 'remotePath'> | { username: string; host: string; path: string }
+): string {
+  const path = 'remotePath' in remote ? remote.remotePath : remote.path;
+  return `${remote.username}@${remote.host}:${path}`;
+}
+
+export function toSessionRemote(host: RemoteHost, remoteCase: RemoteCase): SessionRemote {
+  return {
+    hostId: host.id,
+    label: host.label,
+    host: host.host,
+    username: host.username,
+    port: host.port,
+    remotePath: remoteCase.remotePath,
+    commands: host.commands,
+    // COD-105 — the COD-104 launch path creates the remote session, so we own it
+    // (an explicit kill may propagate a remote kill-session). Discovered+attached
+    // sessions go through `toAttachedSessionRemote` with `owned: false`.
+    owned: true,
+    // COD-107 — carry the advanced SSH options from host config into the session
+    // so the launch/prereq commands connect the same way the operator configured.
+    identityFile: host.identityFile,
+    socksProxy: host.socksProxy,
+    jumpHost: host.jumpHost,
+    extraSshOptions: host.extraSshOptions,
+  };
+}
+
+/**
+ * COD-105 — build a NON-owned `SessionRemote` for ATTACHING to a `codeman-*`
+ * session already running on a remote host (discovered via
+ * `listRemoteCodemanSessions`). The resulting session's pane runs
+ * `tmux -L codeman attach -t <remoteSessionName>` (see
+ * `buildRemoteAttachCommand`), and because we did NOT create the remote session,
+ * `owned: false` means closing the tab DETACHES rather than killing it.
+ *
+ * `remotePath` is informational here (the attached remote session keeps its own
+ * cwd); we record the host's nominal path so display helpers still show
+ * `user@host:path`.
+ */
+export function toAttachedSessionRemote(
+  host: RemoteHost,
+  remoteSessionName: string,
+  remotePath: string
+): SessionRemote {
+  return {
+    hostId: host.id,
+    label: host.label,
+    host: host.host,
+    username: host.username,
+    port: host.port,
+    remotePath,
+    commands: host.commands,
+    // Discovered + attached — another Codeman created it. Detach-not-kill.
+    owned: false,
+    remoteSessionName,
+    identityFile: host.identityFile,
+    socksProxy: host.socksProxy,
+    jumpHost: host.jumpHost,
+    extraSshOptions: host.extraSshOptions,
+  };
+}

src/remote-reconnect.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Pure logic for the remote-session auto-reconnect watcher (COD-108).
+ *
+ * COD-104 made remote tmux sessions durable + idempotently reattachable, but a
+ * reconnect only fired at explicit trigger points. COD-108 adds a continuous
+ * watcher (in `TmuxManager`) that detects a dead remote pane and emits
+ * `remoteSessionDropped`; `SessionManager`/server then reassembles the respawn
+ * options and reattaches (re-running the idempotent remote command).
+ *
+ * This module holds the SIDE-EFFECT-FREE pieces so they can be unit-tested
+ * without real tmux:
+ *  - the bounded exponential **backoff schedule** (attempt → delay, capped),
+ *  - the per-session **reconnect state** shape,
+ *  - the **eligibility decision** (`decideReconnect`) given a session + its
+ *    reconnect state + the current time + the guard set.
+ *
+ * The watcher in `tmux-manager.ts` owns the live `isPaneDead` probe and the
+ * timers; everything here is pure and deterministic (time is injected).
+ *
+ * @module remote-reconnect
+ */
+
+/**
+ * Bounded exponential backoff delays (ms) between reconnect attempts.
+ * Attempt N (1-based) waits `BACKOFF_SCHEDULE_MS[N-1]` from the previous emit
+ * before the next emit is eligible. After the last entry the session is
+ * considered `reconnect-exhausted` and the watcher stops emitting for it.
+ *
+ * 5s, 15s, 45s, 2m, 5m, 5m → ~6 attempts spanning ~13 minutes.
+ */
+export const BACKOFF_SCHEDULE_MS: readonly number[] = [5_000, 15_000, 45_000, 120_000, 300_000, 300_000];
+
+/** Maximum number of reconnect attempts before exhaustion. */
+export const MAX_RECONNECT_ATTEMPTS = BACKOFF_SCHEDULE_MS.length;
+
+/**
+ * Delay (ms) to wait AFTER emitting attempt `attempt` (1-based) before the next
+ * attempt is eligible. `attempt <= 0` returns the first delay; an attempt at or
+ * beyond the cap returns the last delay (callers should check exhaustion via
+ * {@link isExhausted} rather than relying on this for the stop decision).
+ *
+ * Pure — no clock, no I/O.
+ */
+export function reconnectDelayForAttempt(attempt: number): number {
+  if (!Number.isFinite(attempt) || attempt <= 1) return BACKOFF_SCHEDULE_MS[0];
+  const idx = Math.min(Math.floor(attempt) - 1, BACKOFF_SCHEDULE_MS.length - 1);
+  return BACKOFF_SCHEDULE_MS[idx];
+}
+
+/** Whether `attempts` reconnect emits have reached/exceeded the cap. Pure. */
+export function isExhausted(attempts: number): boolean {
+  return attempts >= MAX_RECONNECT_ATTEMPTS;
+}
+
+/**
+ * Per-session reconnect bookkeeping held by the watcher. All time values are
+ * epoch ms. `inFlight` guards against stacking respawns when a tick fires while
+ * a previous reattach is still running. `exhaustedEmitted` ensures the
+ * `remoteReconnectExhausted` event fires at most once per session.
+ */
+export interface RemoteReconnectState {
+  /** Number of `remoteSessionDropped` emits so far (advances per emit). */
+  attempts: number;
+  /** Earliest time (epoch ms) the next emit is eligible. 0 = eligible now. */
+  nextEligibleAt: number;
+  /** A reattach triggered by a prior emit is currently running. */
+  inFlight: boolean;
+  /** Cap reached — stop auto-retrying for this session. */
+  exhausted: boolean;
+  /** The `remoteReconnectExhausted` SSE event has already been emitted. */
+  exhaustedEmitted: boolean;
+}
+
+/** A fresh reconnect state (no attempts, immediately eligible). Pure. */
+export function freshReconnectState(): RemoteReconnectState {
+  return { attempts: 0, nextEligibleAt: 0, inFlight: false, exhausted: false, exhaustedEmitted: false };
+}
+
+/**
+ * Advance the backoff after an emit at time `now`. Increments `attempts` and
+ * schedules `nextEligibleAt = now + delay`. Returns a NEW state object (does
+ * not mutate the input). Pure.
+ *
+ * NOTE: this does NOT set `exhausted`. Exhaustion is a decision the watcher
+ * makes on the FOLLOWING tick (via {@link decideReconnect} → `exhaust`), so the
+ * `remoteReconnectExhausted` event fires exactly once after the final attempt's
+ * backoff window elapses — not pre-emptively on the last emit.
+ */
+export function advanceBackoff(state: RemoteReconnectState, now: number): RemoteReconnectState {
+  const attempts = state.attempts + 1;
+  const delay = reconnectDelayForAttempt(attempts);
+  return {
+    ...state,
+    attempts,
+    nextEligibleAt: now + delay,
+  };
+}
+
+/** Reset after a successful reattach — back to a fresh, eligible state. Pure. */
+export function resetReconnectState(): RemoteReconnectState {
+  return freshReconnectState();
+}
+
+/** Minimal session view the decision needs (avoids importing MuxSession here). */
+export interface ReconnectSessionView {
+  sessionId: string;
+  /** Truthy when this is a remote (SSH-wrapped) session. */
+  isRemote: boolean;
+  /** Result of `isPaneDead(muxName)` for this session. */
+  paneDead: boolean;
+}
+
+/**
+ * Decision outcomes for a single watcher tick on one session.
+ *  - `emit`     → emit `remoteSessionDropped { sessionId, attempt }`, then
+ *                 advance backoff (attempt = the returned `attempt`).
+ *  - `exhaust`  → cap reached this tick; emit `remoteReconnectExhausted` once.
+ *  - `skip`     → do nothing (not remote / pane alive / guarded / in-flight /
+ *                 not yet due / already exhausted).
+ */
+export type ReconnectAction =
+  | { kind: 'emit'; attempt: number }
+  | { kind: 'exhaust' }
+  | { kind: 'skip'; reason: ReconnectSkipReason };
+
+export type ReconnectSkipReason =
+  | 'not-remote'
+  | 'pane-alive'
+  | 'guarded'
+  | 'in-flight'
+  | 'not-due'
+  | 'exhausted'
+  | 'disabled';
+
+export interface DecideReconnectInput {
+  session: ReconnectSessionView;
+  state: RemoteReconnectState | undefined;
+  /** Session is in the intentional-teardown guard set (killed/detached/stopping). */
+  guarded: boolean;
+  /** Kill-switch: `remoteAutoReconnect` setting. When false, never reconnect. */
+  enabled: boolean;
+  now: number;
+}
+
+/**
+ * PURE eligibility decision for one session on one tick. No clock, no I/O — all
+ * inputs are passed in. The watcher translates the result into emits + state
+ * transitions.
+ *
+ * Order of guards (most-decisive first):
+ *  1. kill-switch off            → skip:disabled
+ *  2. not a remote session       → skip:not-remote
+ *  3. pane is alive              → skip:pane-alive
+ *  4. intentional teardown guard → skip:guarded   (NEVER revive a killed tab)
+ *  5. a reattach already running → skip:in-flight (no stacked respawns)
+ *  6. already exhausted          → skip:exhausted (one exhaust emit, then quiet)
+ *  7. cap reached this tick      → exhaust
+ *  8. not yet due (backoff)      → skip:not-due
+ *  9. otherwise                  → emit (attempt = attempts + 1)
+ */
+export function decideReconnect(input: DecideReconnectInput): ReconnectAction {
+  const { session, state, guarded, enabled, now } = input;
+
+  if (!enabled) return { kind: 'skip', reason: 'disabled' };
+  if (!session.isRemote) return { kind: 'skip', reason: 'not-remote' };
+  if (!session.paneDead) return { kind: 'skip', reason: 'pane-alive' };
+  // Intentional kill / detach must NEVER be auto-revived.
+  if (guarded) return { kind: 'skip', reason: 'guarded' };
+
+  const s = state ?? freshReconnectState();
+
+  // Only one reconnect in flight per session — don't stack respawns.
+  if (s.inFlight) return { kind: 'skip', reason: 'in-flight' };
+
+  if (s.exhausted) return { kind: 'skip', reason: 'exhausted' };
+
+  // Cap reached: surface exhaustion once, then go quiet.
+  if (isExhausted(s.attempts)) return { kind: 'exhaust' };
+
+  // Backoff gate — only emit when due.
+  if (now < s.nextEligibleAt) return { kind: 'skip', reason: 'not-due' };
+
+  return { kind: 'emit', attempt: s.attempts + 1 };
+}

src/search-service.ts

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Pure cross-session federated search core (COD-9).
+ *
+ * `searchSources()` is the testable heart of `GET /api/search`: it takes a
+ * normalized query plus already-collected, in-memory source data and returns
+ * grouped, ranked, and capped results. It performs NO I/O — the route wrapper
+ * (`src/web/routes/search-routes.ts`) is responsible for harvesting the source
+ * arrays from the live server stores (sessions, run-summary trackers, attachment
+ * histories) in a bounded way before calling this.
+ *
+ * v1 scope (do not expand here): three sources — sessions/cases, run-summary
+ * events, file paths. Terminal-buffer scanning and any persisted index are
+ * explicitly deferred.
+ *
+ * Ranking: results are grouped by source type in the fixed order
+ * sessions → events → files. Within each group, exact (case-insensitive)
+ * name/path matches come first, then recency (newest timestamp first) as the
+ * tiebreak. There is no relevance-scoring pass in v1.
+ *
+ * Safety: file results only ever expose a workspace-relative path — server-
+ * private absolute paths are never placed in a result. Per-group and total caps
+ * bound the output so a broad query cannot return an unbounded payload.
+ *
+ * Key exports:
+ * - searchSources() — the pure core.
+ * - SEARCH_TOTAL_CAP / SEARCH_PER_GROUP_CAP — the output bounds.
+ * - SearchSources and the *Input row types — the source-data contract.
+ */
+
+import type { SearchResult, SearchResultGroup, SearchResponseData, SearchSourceType } from './types/search.js';
+
+/** Maximum results returned across all groups combined. */
+export const SEARCH_TOTAL_CAP = 60;
+/** Maximum results returned within any single source group. */
+export const SEARCH_PER_GROUP_CAP = 25;
+/** Maximum characters in a result snippet. */
+export const SEARCH_SNIPPET_MAX = 200;
+
+/** A live-session row harvested for the session/case source. */
+export interface SessionSearchInput {
+  sessionId: string;
+  sessionName: string;
+  workingDir: string;
+  /** Recency timestamp (e.g. lastActivityAt or createdAt). */
+  timestamp: number;
+}
+
+/** A run-summary timeline event harvested for the event source. */
+export interface EventSearchInput {
+  sessionId: string;
+  sessionName: string;
+  eventId: string;
+  title: string;
+  details: string;
+  timestamp: number;
+}
+
+/** A per-session attachment harvested for the file source. */
+export interface FileSearchInput {
+  sessionId: string;
+  sessionName: string;
+  fileName: string;
+  /** Workspace-relative path, if known. Absolute/external paths are never passed in. */
+  relativePath: string | undefined;
+  timestamp: number;
+  /** Attachment history item id, used as the jump-to target. */
+  itemId: string;
+}
+
+/** The full set of in-memory source data the pure core searches over. */
+export interface SearchSources {
+  sessions: SessionSearchInput[];
+  events: EventSearchInput[];
+  files: FileSearchInput[];
+}
+
+/** Fixed group/render order. */
+const GROUP_ORDER: SearchSourceType[] = ['session', 'event', 'file'];
+
+function truncate(text: string, max = SEARCH_SNIPPET_MAX): string {
+  const trimmed = text.trim().replace(/\s+/g, ' ');
+  return trimmed.length > max ? trimmed.slice(0, max - 1) + '…' : trimmed;
+}
+
+/**
+ * Sort a group's results: exact matches first, then newest timestamp first.
+ * Stable for equal keys.
+ */
+function sortGroup(rows: SearchResult[]): SearchResult[] {
+  return rows
+    .map((result, index) => ({ result, index }))
+    .sort((a, b) => {
+      if (a.result.exactMatch !== b.result.exactMatch) {
+        return a.result.exactMatch ? -1 : 1;
+      }
+      if (a.result.timestamp !== b.result.timestamp) {
+        return b.result.timestamp - a.result.timestamp;
+      }
+      return a.index - b.index;
+    })
+    .map((r) => r.result);
+}
+
+/**
+ * Search the provided in-memory sources for `query`.
+ *
+ * @param query Raw query string (already length-validated by the route). Blank
+ *   queries return an empty result set.
+ * @param sources Harvested, bounded source arrays.
+ */
+export function searchSources(query: string, sources: SearchSources): SearchResponseData {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) {
+    return { query: query.trim(), groups: [], totalResults: 0, truncated: false };
+  }
+
+  const contains = (s: string | undefined): boolean => !!s && s.toLowerCase().includes(needle);
+  const isExact = (s: string | undefined): boolean => !!s && s.toLowerCase() === needle;
+
+  // -- Source: sessions/cases --
+  const sessionRows: SearchResult[] = [];
+  for (const s of sources.sessions) {
+    if (contains(s.sessionName) || contains(s.workingDir) || contains(s.sessionId)) {
+      sessionRows.push({
+        type: 'session',
+        sessionId: s.sessionId,
+        sessionName: s.sessionName,
+        timestamp: s.timestamp,
+        snippet: truncate(s.workingDir ? `${s.sessionName} — ${s.workingDir}` : s.sessionName),
+        exactMatch: isExact(s.sessionName),
+        jumpTo: { kind: 'session', sessionId: s.sessionId },
+      });
+    }
+  }
+
+  // -- Source: run-summary events --
+  const eventRows: SearchResult[] = [];
+  for (const e of sources.events) {
+    if (contains(e.title) || contains(e.details)) {
+      const snippetBase = e.details && contains(e.details) ? `${e.title}: ${e.details}` : e.title;
+      eventRows.push({
+        type: 'event',
+        sessionId: e.sessionId,
+        sessionName: e.sessionName,
+        timestamp: e.timestamp,
+        snippet: truncate(snippetBase),
+        exactMatch: isExact(e.title),
+        jumpTo: { kind: 'run-summary', sessionId: e.sessionId, targetId: e.eventId },
+      });
+    }
+  }
+
+  // -- Source: file paths --
+  const fileRows: SearchResult[] = [];
+  for (const f of sources.files) {
+    if (contains(f.fileName) || contains(f.relativePath)) {
+      fileRows.push({
+        type: 'file',
+        sessionId: f.sessionId,
+        sessionName: f.sessionName,
+        timestamp: f.timestamp,
+        snippet: truncate(f.relativePath ?? f.fileName),
+        // Exact match keys off the safe path (or filename) — never an absolute path.
+        exactMatch: isExact(f.relativePath) || isExact(f.fileName),
+        jumpTo: {
+          kind: 'file-preview',
+          sessionId: f.sessionId,
+          targetId: f.itemId,
+          // Only ever expose a relative path; absolute/external paths are not passed in.
+          relativePath: f.relativePath,
+        },
+      });
+    }
+  }
+
+  const byType: Record<SearchSourceType, SearchResult[]> = {
+    session: sortGroup(sessionRows),
+    event: sortGroup(eventRows),
+    file: sortGroup(fileRows),
+  };
+
+  const groups: SearchResultGroup[] = [];
+  let total = 0;
+  let truncated = false;
+
+  for (const type of GROUP_ORDER) {
+    const all = byType[type];
+    if (all.length === 0) continue;
+
+    // Per-group cap.
+    let capped = all.slice(0, SEARCH_PER_GROUP_CAP);
+    if (all.length > capped.length) truncated = true;
+
+    // Total cap (never exceed the global budget).
+    const remaining = SEARCH_TOTAL_CAP - total;
+    if (capped.length > remaining) {
+      capped = capped.slice(0, Math.max(0, remaining));
+      truncated = true;
+    }
+    if (capped.length === 0) continue;
+
+    groups.push({ type, results: capped });
+    total += capped.length;
+  }
+
+  return { query: query.trim(), groups, totalResults: total, truncated };
+}

src/services/unified-session-service.ts

@@ -0,0 +1,351 @@
+/**
+ * @fileoverview Pure merge/filter logic for the unified session list (COD-121).
+ *
+ * Combines four read-only views of a session — live (in-memory `Session`),
+ * persisted (`state.json`), transcript history (`~/.claude/projects`), and the
+ * lifecycle audit log — plus mux process stats, into one de-duplicated list
+ * keyed by sessionId. Transcript-history rows are keyed by the Claude
+ * conversation UUID (the `.jsonl` filename stem), which diverges from the
+ * Codeman id for resumed sessions — an alias map (claudeSessionId → Codeman id,
+ * built from the live/persisted views) folds them into the owning session item.
+ * Higher-precedence sources overwrite scalar fields when present
+ * (history < lifecycle < persisted < live), while the `sources` array
+ * always accumulates every contributing view. A "meaningfulness floor" drops
+ * noise (bare lifecycle/mux-only rows with no name and no first prompt).
+ *
+ * PURE: no fs/IO and no node imports. All IO happens in the route that feeds
+ * this module its inputs, which keeps the merge/sort/filter behavior unit-testable.
+ */
+
+export type UnifiedSessionItem = {
+  sessionId: string;
+  name?: string;
+  mode?: string;
+  status?: string;
+  isWorking?: boolean;
+  workingDir?: string;
+  createdAt?: number;
+  lastActivityAt?: number;
+  claudeSessionId?: string;
+  firstPrompt?: string;
+  /** Most recent user prompt from the transcript (COD-145), parallel to firstPrompt. */
+  lastPrompt?: string;
+  sizeBytes?: number;
+  projectKey?: string;
+  remote?: boolean;
+  /** Pinned to the top of the session manager list (COD-139). */
+  pinned?: boolean;
+  /** When the session was pinned (epoch ms) — orders the pinned group desc. */
+  pinnedAt?: number;
+  sources: string[];
+  stats?: { memoryMB: number; cpuPercent: number };
+};
+
+/** Live in-memory session view (subset of `Session.toState()`). */
+export type LiveSessionInput = {
+  id: string;
+  name?: string;
+  mode?: string;
+  status?: string;
+  isWorking?: boolean;
+  workingDir?: string;
+  createdAt?: number;
+  lastActivityAt?: number;
+  claudeSessionId?: string;
+  pinned?: boolean;
+  pinnedAt?: number;
+};
+
+/** Persisted session view (subset of `SessionState`). */
+export type PersistedSessionInput = {
+  id: string;
+  name?: string;
+  mode?: string;
+  status?: string;
+  workingDir?: string;
+  createdAt?: number;
+  lastActivityAt?: number;
+  /** Claude conversation ID this session resumes (`SessionState.resumeSessionId`). */
+  claudeSessionId?: string;
+  pinned?: boolean;
+  pinnedAt?: number;
+};
+
+/** Lifecycle audit-log view. Entries are expected NEWEST-first (the order `SessionLifecycleLog.query()` returns). */
+export type LifecycleInput = {
+  sessionId: string;
+  name?: string;
+  mode?: string;
+  ts: number;
+  event?: string;
+};
+
+/** Transcript-history view (one `.jsonl` per session). */
+export type HistoryInput = {
+  sessionId: string;
+  workingDir: string;
+  sizeBytes: number;
+  lastModified: string;
+  firstPrompt?: string;
+  /** Most recent user prompt from the transcript (COD-145). */
+  lastPrompt?: string;
+  projectKey?: string;
+};
+
+/** Mux process-stat view. */
+export type MuxStatInput = {
+  sessionId: string;
+  muxName?: string;
+  mode?: string;
+  stats?: { memoryMB: number; cpuPercent: number };
+  remote?: boolean;
+};
+
+export type UnifiedSources = {
+  live?: LiveSessionInput[];
+  persisted?: PersistedSessionInput[];
+  lifecycle?: LifecycleInput[];
+  history?: HistoryInput[];
+  mux?: MuxStatInput[];
+};
+
+/** Push a source tag onto an item exactly once. */
+function addSource(item: UnifiedSessionItem, source: string): void {
+  if (!item.sources.includes(source)) item.sources.push(source);
+}
+
+/** Get-or-create the accumulator item for a sessionId. */
+function ensureItem(map: Map<string, UnifiedSessionItem>, sessionId: string): UnifiedSessionItem {
+  let item = map.get(sessionId);
+  if (!item) {
+    item = { sessionId, sources: [] };
+    map.set(sessionId, item);
+  }
+  return item;
+}
+
+/** Overwrite a scalar field only when the incoming value is defined. */
+function overwrite<K extends keyof UnifiedSessionItem>(
+  item: UnifiedSessionItem,
+  key: K,
+  value: UnifiedSessionItem[K] | undefined
+): void {
+  if (value !== undefined) item[key] = value;
+}
+
+/**
+ * Merge all source views into one list, applying precedence
+ * (history → lifecycle → persisted → live) and the meaningfulness floor.
+ */
+export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionItem[] {
+  const map = new Map<string, UnifiedSessionItem>();
+
+  // Alias map: Claude conversation UUID → owning Codeman session id. Resumed
+  // (claudeSessionId = resumeSessionId != id) and /clear-respawned sessions
+  // would otherwise surface twice — once as a live/persisted row and once as a
+  // separate history-only row keyed by the conversation UUID. Live wins over
+  // persisted on conflicting entries (registered last).
+  const aliasToOwner = new Map<string, string>();
+  for (const p of sources.persisted ?? []) {
+    if (p.claudeSessionId !== undefined && p.claudeSessionId !== p.id) aliasToOwner.set(p.claudeSessionId, p.id);
+  }
+  for (const v of sources.live ?? []) {
+    if (v.claudeSessionId !== undefined && v.claudeSessionId !== v.id) aliasToOwner.set(v.claudeSessionId, v.id);
+  }
+  const resolveId = (sessionId: string): string => aliasToOwner.get(sessionId) ?? sessionId;
+
+  // 1) history (lowest precedence; keys resolve through the alias map)
+  for (const h of sources.history ?? []) {
+    const item = ensureItem(map, resolveId(h.sessionId));
+    addSource(item, 'history');
+    overwrite(item, 'workingDir', h.workingDir);
+    overwrite(item, 'sizeBytes', h.sizeBytes);
+    overwrite(item, 'firstPrompt', h.firstPrompt);
+    overwrite(item, 'lastPrompt', h.lastPrompt);
+    overwrite(item, 'projectKey', h.projectKey);
+    const ms = Date.parse(h.lastModified);
+    if (!Number.isNaN(ms) && item.lastActivityAt === undefined) item.lastActivityAt = ms;
+  }
+
+  // 2) lifecycle — entries arrive NEWEST-first, so first-seen wins for
+  //    name/mode (mirrors the lastActivityAt guard); unconditional overwrites
+  //    would leave the OLDEST entry in the window (stale name/mode) standing.
+  for (const l of sources.lifecycle ?? []) {
+    const item = ensureItem(map, resolveId(l.sessionId));
+    addSource(item, 'lifecycle');
+    if (item.name === undefined) overwrite(item, 'name', l.name);
+    if (item.mode === undefined) overwrite(item, 'mode', l.mode);
+    if (item.lastActivityAt === undefined && typeof l.ts === 'number') item.lastActivityAt = l.ts;
+  }
+
+  // 3) persisted
+  for (const p of sources.persisted ?? []) {
+    const item = ensureItem(map, p.id);
+    addSource(item, 'persisted');
+    overwrite(item, 'name', p.name);
+    overwrite(item, 'mode', p.mode);
+    overwrite(item, 'status', p.status);
+    overwrite(item, 'workingDir', p.workingDir);
+    overwrite(item, 'createdAt', p.createdAt);
+    overwrite(item, 'lastActivityAt', p.lastActivityAt);
+    overwrite(item, 'pinned', p.pinned);
+    overwrite(item, 'pinnedAt', p.pinnedAt);
+  }
+
+  // 4) live (highest precedence)
+  for (const v of sources.live ?? []) {
+    const item = ensureItem(map, v.id);
+    addSource(item, 'live');
+    overwrite(item, 'name', v.name);
+    overwrite(item, 'mode', v.mode);
+    overwrite(item, 'status', v.status);
+    overwrite(item, 'isWorking', v.isWorking);
+    overwrite(item, 'workingDir', v.workingDir);
+    overwrite(item, 'createdAt', v.createdAt);
+    overwrite(item, 'lastActivityAt', v.lastActivityAt);
+    overwrite(item, 'claudeSessionId', v.claudeSessionId);
+    overwrite(item, 'pinned', v.pinned);
+    overwrite(item, 'pinnedAt', v.pinnedAt);
+  }
+
+  // 5) mux stats + remote flag (create item if mux-only)
+  for (const m of sources.mux ?? []) {
+    const item = ensureItem(map, m.sessionId);
+    addSource(item, 'mux');
+    overwrite(item, 'mode', m.mode);
+    if (m.stats) item.stats = m.stats;
+    if (m.remote !== undefined) item.remote = m.remote;
+  }
+
+  // firstPrompt backfill (COD-140): the only source that sets firstPrompt is the
+  // transcript-history view, keyed by the Claude transcript file's UUID. A live/persisted
+  // row keyed by its Codeman id only inherits firstPrompt when that id happens to equal an
+  // on-disk transcript UUID. When it doesn't (stale/wrong claudeSessionId, post-/clear new
+  // uuid, resumed/attached/worktree session, transcript not yet flushed), the row shows
+  // "(no prompt captured)" even though a real transcript for that working dir exists under a
+  // different UUID. Backfill from the already-passed history: first try the claudeSessionId
+  // join, then the newest transcript in the same workingDir. Never overwrite a non-empty
+  // firstPrompt (so rows keyed to their own transcript are untouched).
+  const firstPromptByUuid = new Map<string, string>();
+  const firstPromptByWorkingDir = new Map<string, { prompt: string; ms: number }>();
+  // COD-145: lastPrompt rides the same backfill (build parallel indexes; never overwrite).
+  const lastPromptByUuid = new Map<string, string>();
+  const lastPromptByWorkingDir = new Map<string, { prompt: string; ms: number }>();
+  for (const h of sources.history ?? []) {
+    const ms = Date.parse(h.lastModified);
+    const ts = Number.isNaN(ms) ? -Infinity : ms;
+    if (h.firstPrompt) {
+      firstPromptByUuid.set(h.sessionId, h.firstPrompt);
+      if (h.workingDir) {
+        const existing = firstPromptByWorkingDir.get(h.workingDir);
+        if (!existing || ts > existing.ms) {
+          firstPromptByWorkingDir.set(h.workingDir, { prompt: h.firstPrompt, ms: ts });
+        }
+      }
+    }
+    if (h.lastPrompt) {
+      lastPromptByUuid.set(h.sessionId, h.lastPrompt);
+      if (h.workingDir) {
+        const existing = lastPromptByWorkingDir.get(h.workingDir);
+        if (!existing || ts > existing.ms) {
+          lastPromptByWorkingDir.set(h.workingDir, { prompt: h.lastPrompt, ms: ts });
+        }
+      }
+    }
+  }
+  for (const item of map.values()) {
+    if (!item.firstPrompt) {
+      // never overwrite an existing non-empty prompt
+      const byUuid = item.claudeSessionId ? firstPromptByUuid.get(item.claudeSessionId) : undefined;
+      if (byUuid) {
+        item.firstPrompt = byUuid;
+      } else if (item.workingDir) {
+        const byDir = firstPromptByWorkingDir.get(item.workingDir);
+        if (byDir) item.firstPrompt = byDir.prompt;
+      }
+    }
+    if (!item.lastPrompt) {
+      const byUuid = item.claudeSessionId ? lastPromptByUuid.get(item.claudeSessionId) : undefined;
+      if (byUuid) {
+        item.lastPrompt = byUuid;
+      } else if (item.workingDir) {
+        const byDir = lastPromptByWorkingDir.get(item.workingDir);
+        if (byDir) item.lastPrompt = byDir.prompt;
+      }
+    }
+  }
+
+  // Meaningfulness floor: keep real rows, drop bare lifecycle/mux-only noise.
+  const kept: UnifiedSessionItem[] = [];
+  for (const item of map.values()) {
+    const isReal =
+      item.sources.includes('live') ||
+      item.sources.includes('persisted') ||
+      item.sources.includes('history') ||
+      (item.firstPrompt !== undefined && item.firstPrompt !== '');
+    if (isReal) kept.push(item);
+  }
+
+  // Stable sort (COD-139): pinned group first (pinnedAt desc, most-recently-pinned
+  // first), then unpinned by lastActivityAt desc (undefined last), createdAt desc,
+  // sessionId asc.
+  kept.sort((a, b) => {
+    const pa = a.pinned === true;
+    const pb = b.pinned === true;
+    if (pa !== pb) return pa ? -1 : 1; // pinned floats above unpinned
+    if (pa && pb) {
+      // Both pinned: most-recently-pinned first (undefined pinnedAt sorts last).
+      const ta = a.pinnedAt;
+      const tb = b.pinnedAt;
+      if (ta !== tb) {
+        if (ta === undefined) return 1;
+        if (tb === undefined) return -1;
+        return tb - ta;
+      }
+      // tie-break falls through to the activity/createdAt/id rules below.
+    }
+    const la = a.lastActivityAt;
+    const lb = b.lastActivityAt;
+    if (la !== lb) {
+      if (la === undefined) return 1;
+      if (lb === undefined) return -1;
+      return lb - la;
+    }
+    const ca = a.createdAt;
+    const cb = b.createdAt;
+    if (ca !== cb) {
+      if (ca === undefined) return 1;
+      if (cb === undefined) return -1;
+      return cb - ca;
+    }
+    return a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0;
+  });
+
+  return kept;
+}
+
+/**
+ * Case-insensitive substring filter (name + firstPrompt + lastPrompt + workingDir + sessionId)
+ * with offset/limit paging. `total` is the filtered count BEFORE paging.
+ */
+export function filterAndPaginate(
+  items: UnifiedSessionItem[],
+  opts: { q?: string; offset?: number; limit?: number }
+): { sessions: UnifiedSessionItem[]; total: number } {
+  const q = (opts.q ?? '').trim().toLowerCase();
+  const filtered = q
+    ? items.filter((it) => {
+        const hay = [it.name, it.firstPrompt, it.lastPrompt, it.workingDir, it.sessionId]
+          .filter((v): v is string => typeof v === 'string')
+          .join(' ')
+          .toLowerCase();
+        return hay.includes(q);
+      })
+    : items;
+
+  const total = filtered.length;
+  const offset = Math.max(0, Math.floor(opts.offset ?? 0));
+  const limit = Math.min(500, Math.max(1, Math.floor(opts.limit ?? 100)));
+  const sessions = filtered.slice(offset, offset + limit);
+  return { sessions, total };
+}

src/session-cli-builder.ts

@@ -21,6 +21,8 @@ function buildPermissionArgs(claudeMode: ClaudeMode, allowedTools?: string): str
   switch (claudeMode) {
     case 'dangerously-skip-permissions':
       return ['--dangerously-skip-permissions'];
+    case 'auto':
+      return ['--permission-mode', 'auto'];
     case 'allowedTools':
       if (allowedTools) {
         return ['--allowedTools', allowedTools];
@@ -80,8 +82,16 @@ export function buildInteractiveArgs(
  * @param model - Optional model override
  * @returns Array of CLI arguments
  */
-export function buildPromptArgs(prompt: string, model?: string): string[] {
-  const args = ['-p', '--verbose', '--dangerously-skip-permissions', '--output-format', 'stream-json'];
+export function buildPromptArgs(
+  prompt: string,
+  model?: string,
+  claudeMode: ClaudeMode = 'dangerously-skip-permissions',
+  allowedTools?: string
+): string[] {
+  // Respect the session's permission mode instead of always skipping, so a
+  // multi-user non-granted user's one-shot runs classifier-guarded (auto) rather
+  // than with full bypass. Defaults to skip-permissions (unchanged single-user).
+  const args = ['-p', '--verbose', ...buildPermissionArgs(claudeMode, allowedTools), '--output-format', 'stream-json'];
   if (model) {
     args.push('--model', model);
   }
@@ -102,14 +112,12 @@ export function buildPromptArgs(prompt: string, model?: string): string[] {
  * @returns Environment variables object for pty.spawn
  */
 export function buildClaudeEnv(sessionId: string): Record<string, string | undefined> {
-  return {
+  const env: Record<string, string | undefined> = {
     ...process.env,
     LANG: 'en_US.UTF-8',
     LC_ALL: 'en_US.UTF-8',
     PATH: getAugmentedPath(),
     TERM: 'xterm-256color',
-    COLORTERM: undefined,
-    CLAUDECODE: undefined,
     // Inform Claude it's running within Codeman (helps prevent self-termination)
     CODEMAN_MUX: '1',
     CODEMAN_SESSION_ID: sessionId,
@@ -117,6 +125,11 @@ export function buildClaudeEnv(sessionId: string): Record<string, string | undef
     // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
     CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
   };
+  // COD-115: `delete`, not `= undefined` — node-pty serializes a present-with-undefined
+  // key as the literal string "KEY=undefined" (see buildMuxAttachEnv below).
+  delete env.COLORTERM;
+  delete env.CLAUDECODE;
+  return env;
 }
 
 /**
@@ -124,17 +137,32 @@ export function buildClaudeEnv(sessionId: string): Record<string, string | undef
  * Lighter than buildClaudeEnv — no PATH augmentation or Codeman vars needed
  * since the mux session already has those set.
  *
+ * @param truecolorEnabled - When true, set COLORTERM=truecolor (COD-75 opt-in);
+ *   otherwise leave COLORTERM unset. Mirrors buildEnvExports() so both paths agree.
  * @returns Environment variables object for pty.spawn
  */
-export function buildMuxAttachEnv(): Record<string, string | undefined> {
-  return {
+export function buildMuxAttachEnv(truecolorEnabled?: boolean): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = {
     ...process.env,
     LANG: 'en_US.UTF-8',
     LC_ALL: 'en_US.UTF-8',
     TERM: 'xterm-256color',
-    COLORTERM: undefined,
-    CLAUDECODE: undefined,
   };
+  // COD-115: keys to UNSET must be `delete`d, NOT set to `undefined`. On a
+  // `{...process.env}` spread the key stays present with value undefined, and node-pty
+  // serializes it as the literal string "TMUX=undefined" — a non-empty value that still
+  // trips tmux's nesting guard, killing the attach-bridge PTY (exit 1 → respawn loop).
+  // The server can be launched from inside tmux; attach clients must never inherit that
+  // parent tmux context. (Same fix the working create path uses in tmux-manager.ts.)
+  delete env.TMUX;
+  delete env.TMUX_PANE;
+  delete env.CLAUDECODE;
+  if (truecolorEnabled) {
+    env.COLORTERM = 'truecolor';
+  } else {
+    delete env.COLORTERM; // COD-75: unset for non-truecolor (was `: undefined`, same node-pty quirk)
+  }
+  return env;
 }
 
 /**

src/session-order.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Pure helpers for the global session tab-order (COD-131).
+ *
+ * Tab order (drag-and-drop reorder + Ctrl+Shift+{/}) is persisted server-side
+ * so it follows the user across devices. The server is authoritative; the
+ * browser's localStorage (`codeman-session-order`) is the offline fallback.
+ *
+ * These helpers are pure (no IO) so they can be unit-tested in isolation and
+ * reused by both the PUT /api/session-order route and the StateStore accessor.
+ *
+ * - `normalizeSessionOrder` coerces arbitrary input into a clean string[]
+ *   (non-empty strings only, deduped with first occurrence winning).
+ * - `mergeSessionOrder` lets the pushing device's order win, while preserving
+ *   any server-only ids the pushing device didn't know about — they fall to the
+ *   END in their existing relative order, never dropped.
+ */
+
+/**
+ * Coerce arbitrary input into a clean ordered list of session ids:
+ * keep only non-empty strings and dedup (first occurrence wins).
+ *
+ * @param order - unknown input (expected to be a string[], but defensive)
+ * @returns a normalized string[] (empty array for non-array / all-junk input)
+ */
+export function normalizeSessionOrder(order: unknown): string[] {
+  if (!Array.isArray(order)) {
+    return [];
+  }
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const entry of order) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      continue;
+    }
+    if (seen.has(entry)) {
+      continue;
+    }
+    seen.add(entry);
+    result.push(entry);
+  }
+  return result;
+}
+
+/**
+ * Merge an incoming order from a pushing device with the existing server order.
+ *
+ * The incoming order wins; any ids present in `existing` but NOT in `incoming`
+ * are appended at the END, preserving their relative order. This is the
+ * "server-only ids the pushing device didn't know about fall to the end, never
+ * dropped" rule.
+ *
+ * Both arguments are normalized first, so callers may pass raw input safely.
+ *
+ * @param incoming - the order the pushing device wants
+ * @param existing - the current server-side order
+ * @returns the merged, normalized order
+ */
+export function mergeSessionOrder(incoming: string[], existing: string[]): string[] {
+  const normalizedIncoming = normalizeSessionOrder(incoming);
+  const incomingSet = new Set(normalizedIncoming);
+  const merged = [...normalizedIncoming];
+  for (const id of normalizeSessionOrder(existing)) {
+    if (!incomingSet.has(id)) {
+      merged.push(id);
+    }
+  }
+  return merged;
+}

src/session-pty-exit-breaker.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Circuit breaker bounding repeated non-zero interactive-PTY exits (COD-118).
+ *
+ * Defense-in-depth after COD-115: if the interactive PTY exits non-zero repeatedly,
+ * external recovery/reconnect paths recreate it indefinitely (COD-115 observed 114
+ * `exited with code: 1` events + orphan sessions). This breaker tracks recent
+ * non-zero exits within a sliding window and "trips" once they exceed a threshold,
+ * so the Session can refuse to respawn and surface an error state instead of looping.
+ *
+ * Design notes:
+ * - PURE + dependency-free. Time is INJECTED (`nowMs` passed to `recordExit`); the
+ *   breaker never calls `Date.now()` itself, so trip/window logic is deterministically
+ *   unit-testable with no real timers.
+ * - A clean (exit code 0) exit resets the counter — a session that exited normally is
+ *   not on a crash-loop. (It does NOT clear an already-tripped breaker; only an explicit
+ *   `reset()` — e.g. a user-initiated restart — does that.)
+ * - Once tripped, stays tripped until `reset()`.
+ *
+ * @consumedby session (instantiates one per session; records exits in the interactive
+ *   PTY `onExit` handler; gates `startInteractive()` when tripped; `reset()` on restart)
+ * @module session-pty-exit-breaker
+ */
+
+/** Non-zero interactive-PTY exits within the window required to trip the breaker. */
+export const DEFAULT_BREAKER_THRESHOLD = 5;
+
+/** Sliding window (ms) over which non-zero exits accumulate toward the threshold. */
+export const DEFAULT_BREAKER_WINDOW_MS = 10_000;
+
+export interface InteractivePtyExitBreakerOptions {
+  /** Trip after this many non-zero exits within `windowMs` (default 5). */
+  threshold?: number;
+  /** Sliding window length in ms (default 10_000). */
+  windowMs?: number;
+}
+
+export interface RecordExitResult {
+  /** True once the breaker has tripped (stays true until `reset()`). */
+  tripped: boolean;
+  /** Number of non-zero exits currently inside the window. */
+  count: number;
+}
+
+/**
+ * Sliding-window counter that trips on rapid repeated non-zero exits.
+ *
+ * 5 within 10s safely clears normal usage (a single exit, an intentional restart)
+ * while tripping fast on a real loop — COD-115 saw 114 exits, far above 5.
+ */
+export class InteractivePtyExitBreaker {
+  private readonly _threshold: number;
+  private readonly _windowMs: number;
+
+  /** Timestamps (ms, injected) of recent non-zero exits, oldest first. */
+  private _exitTimes: number[] = [];
+
+  private _tripped = false;
+
+  constructor(opts: InteractivePtyExitBreakerOptions = {}) {
+    this._threshold = opts.threshold ?? DEFAULT_BREAKER_THRESHOLD;
+    this._windowMs = opts.windowMs ?? DEFAULT_BREAKER_WINDOW_MS;
+  }
+
+  /** Whether the breaker has tripped (respawn should be blocked). */
+  get tripped(): boolean {
+    return this._tripped;
+  }
+
+  /**
+   * Record a PTY exit. A zero (clean) exit resets the non-zero counter; a non-zero
+   * exit is added to the window, stale entries are evicted, and the breaker trips
+   * once the in-window count reaches the threshold.
+   *
+   * @param exitCode the PTY exit code (0 = clean)
+   * @param nowMs injected current time in ms (never read from a real clock)
+   */
+  recordExit(exitCode: number, nowMs: number): RecordExitResult {
+    if (exitCode === 0) {
+      // Clean exit: a normal stop, not a crash-loop. Clear accumulated non-zero
+      // exits. Does NOT un-trip an already-tripped breaker (only reset() does).
+      this._exitTimes = [];
+      return { tripped: this._tripped, count: 0 };
+    }
+
+    // Evict exits strictly older than the window, then record this one.
+    const cutoff = nowMs - this._windowMs;
+    this._exitTimes = this._exitTimes.filter((t) => t > cutoff);
+    this._exitTimes.push(nowMs);
+
+    if (this._exitTimes.length >= this._threshold) {
+      this._tripped = true;
+    }
+
+    return { tripped: this._tripped, count: this._exitTimes.length };
+  }
+
+  /** Clear the tripped state and the non-zero counter (e.g. on intentional restart). */
+  reset(): void {
+    this._exitTimes = [];
+    this._tripped = false;
+  }
+}

src/session.ts

@@ -48,7 +48,12 @@ import {
   type OpenCodeConfig,
   type CodexConfig,
   type EffortLevel,
+  type GeminiConfig,
+  type AntigravityConfig,
+  type SessionRemote,
+  type SessionDocker,
 } from './types.js';
+import { probeDockerCliVersion } from './docker-hosts.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
 import { TaskTracker, type BackgroundTask } from './task-tracker.js';
 import { RalphTracker } from './ralph-tracker.js';
@@ -60,6 +65,10 @@ import {
   SPINNER_PATTERN,
   MAX_SESSION_TOKENS,
   execPattern,
+  getClaudeCliVersion,
+  getClaudeBinaryPath,
+  spawnPtyWithHelperRepair,
+  resolveLocalShell,
 } from './utils/index.js';
 import {
   MAX_TERMINAL_BUFFER_SIZE,
@@ -69,6 +78,7 @@ import {
   MAX_MESSAGES,
   MAX_LINE_BUFFER_SIZE,
 } from './config/buffer-limits.js';
+import { DEFAULT_TMUX_HISTORY_LIMIT } from './config/terminal-history.js';
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import {
   buildInteractiveArgs,
@@ -80,7 +90,8 @@ import {
 import { SessionAutoOps } from './session-auto-ops.js';
 import { detectUsageLimitPause } from './usage-limit-patterns.js';
 import { SessionTaskCache } from './session-task-cache.js';
-import { parseAttachmentMagicLinks } from './attachment-magic.js';
+import { InteractivePtyExitBreaker } from './session-pty-exit-breaker.js';
+import { parseTerminalAttachmentRequests } from './attachment-magic.js';
 import {
   sanitizeAttachmentHistory,
   upsertAttachmentHistory as upsertAttachmentHistoryList,
@@ -133,7 +144,24 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;
 
 /** True for external-CLI run modes (non-Claude) that use their own TUI and output format. */
 export function isExternalCliMode(mode: SessionMode): boolean {
-  return mode === 'opencode' || mode === 'codex';
+  return mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity';
+}
+
+function getModeLabel(mode: SessionMode): string {
+  switch (mode) {
+    case 'opencode':
+      return 'OpenCode';
+    case 'codex':
+      return 'Codex';
+    case 'gemini':
+      return 'Gemini';
+    case 'antigravity':
+      return 'Antigravity';
+    case 'shell':
+      return 'Shell';
+    case 'claude':
+      return 'Claude';
+  }
 }
 
 /**
@@ -141,14 +169,15 @@ export function isExternalCliMode(mode: SessionMode): boolean {
  * that we strip so the browser keeps everything in the main buffer with scrollback
  * reachable (the strip runs on both the live stream and the buffer replay).
  *
- * Codex and Claude Code are known, controlled TUIs that repaint via cursor
- * positioning, so dropping the alt-screen switch is safe — content stays in the
- * normal buffer. Excluded: `shell` (arbitrary programs like vim/less/htop
- * legitimately need the alt screen) and `opencode` (renders its own TUI that
- * may rely on it). Keep parity with the replay-side strip in session-routes.ts.
+ * Codex, Claude Code, and Gemini are known, controlled (Ink/React) TUIs that
+ * repaint via cursor positioning, so dropping the alt-screen switch is safe —
+ * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
+ * vim/less/htop legitimately need the alt screen) and `opencode` (renders its own
+ * TUI that may rely on it). Keep parity with the replay-side strip in
+ * session-routes.ts.
  */
 export function isAltScreenStripMode(mode: SessionMode): boolean {
-  return mode === 'codex' || mode === 'claude';
+  return mode === 'codex' || mode === 'claude' || mode === 'gemini';
 }
 
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)
@@ -157,6 +186,15 @@ export function isAltScreenStripMode(mode: SessionMode): boolean {
 const DEFAULT_PTY_COLS = 120;
 const DEFAULT_PTY_ROWS = 40;
 const TMUX_DISPLAY_TIMEOUT_MS = 2000;
+const IS_TEST_MODE = !!process.env.VITEST;
+/**
+ * Echo transport for the test-mode PTY attach. Raw mode disables the tty line
+ * discipline, so each input byte flows back exactly once and immediately; without
+ * it, tty echo doubles every line and canonical buffering holds bytes until Enter.
+ */
+const TEST_PTY_SCRIPT = 'if (process.stdin.isTTY) process.stdin.setRawMode(true); process.stdin.pipe(process.stdout);';
+/** Delay before the in-container Claude CLI version probe (lets the container start). */
+const DOCKER_CLI_VERSION_PROBE_DELAY_MS = 3000;
 
 /**
  * Ask tmux for the current window geometry of `muxName` so a re-attaching PTY
@@ -191,6 +229,12 @@ export function queryTmuxWindowSize(muxName: string, socket: string): { cols: nu
   return { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS };
 }
 
+export function resolveMuxAttachCwd(workingDir: string, remote?: SessionRemote, docker?: SessionDocker): string {
+  // Remote and docker sessions run the CLI elsewhere (ssh / docker exec); the LOCAL
+  // wrapper pane never needs the workspace as its cwd, so launch it in /tmp.
+  return remote || docker ? '/tmp' : workingDir;
+}
+
 /**
  * Represents a JSON message from Claude CLI's stream-json output format.
  * Messages are newline-delimited JSON objects parsed from PTY output.
@@ -270,6 +314,13 @@ export class Session extends EventEmitter {
   private _pid: number | null = null;
   private _status: SessionStatus = 'idle';
   private _currentTaskId: string | null = null;
+
+  // COD-118: bound repeated non-zero interactive-PTY exits. Recorded in the
+  // interactive PTY onExit handler; when it trips, the session flips to 'error'
+  // and startInteractive() refuses to respawn until an explicit user restart
+  // calls resetRespawnBreaker(). Defense-in-depth over the COD-115 crash-loop.
+  private readonly _ptyExitBreaker = new InteractivePtyExitBreaker();
+  private _respawnBlocked = false;
   // Use BufferAccumulator for hot-path buffers to reduce GC pressure
   private _terminalBuffer = new BufferAccumulator(MAX_TERMINAL_BUFFER_SIZE, TERMINAL_BUFFER_TRIM_SIZE);
   private _textOutput = new BufferAccumulator(MAX_TEXT_OUTPUT_SIZE, TEXT_OUTPUT_TRIM_SIZE);
@@ -304,6 +355,11 @@ export class Session extends EventEmitter {
   // Image watcher setting (per-session toggle)
   private _imageWatcherEnabled: boolean = false;
 
+  // Pin state (COD-139) — pinned sessions float to the top of the session
+  // manager list, ordered by pinnedAt descending (most-recently-pinned first).
+  private _pinned: boolean = false;
+  private _pinnedAt: number | null = null;
+
   // Flicker filter setting (per-session toggle, applied on frontend)
   private _flickerFilterEnabled: boolean = false;
 
@@ -351,6 +407,10 @@ export class Session extends EventEmitter {
   private _openCodeConfig: OpenCodeConfig | undefined;
   // Codex configuration (only for mode === 'codex')
   private _codexConfig: CodexConfig | undefined;
+  // Gemini configuration (only for mode === 'gemini')
+  private _geminiConfig: GeminiConfig | undefined;
+  // Antigravity configuration (only for mode === 'antigravity')
+  private _antigravityConfig: AntigravityConfig | undefined;
   private _resumeSessionId: string | undefined;
 
   // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -362,6 +422,20 @@ export class Session extends EventEmitter {
   // the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session.
   private _effort: EffortLevel | undefined;
 
+  // tmux history-limit (scrollback lines) applied to this session's pane.
+  private readonly _tmuxHistoryLimit: number;
+
+  // Remote execution metadata, present when this session runs over SSH through local tmux.
+  private readonly _remote?: SessionRemote;
+
+  // Docker execution metadata, present when this session runs inside a container via
+  // local tmux + `docker exec`. The container is per-CASE (shared by sibling sessions).
+  private readonly _docker?: SessionDocker;
+
+  // Owning username in multi-user mode (undefined in single-user). Stamped at create
+  // from req.authUser and round-tripped through recovery like _remote/_docker.
+  private _owner?: string;
+
   // Session color for visual differentiation
   private _color: import('./types.js').SessionColor = 'default';
 
@@ -421,14 +495,26 @@ export class Session extends EventEmitter {
       openCodeConfig?: OpenCodeConfig;
       /** Codex configuration (only for mode === 'codex') */
       codexConfig?: CodexConfig;
+      /** Gemini configuration (only for mode === 'gemini') */
+      geminiConfig?: GeminiConfig;
+      /** Antigravity configuration (only for mode === 'antigravity') */
+      antigravityConfig?: AntigravityConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
       /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
       envOverrides?: Record<string, string>;
       /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
       effort?: EffortLevel;
+      /** tmux history-limit (scrollback lines) for this session's pane. */
+      tmuxHistoryLimit?: number;
       /** Restored per-session attachment history. May include server-private external paths. */
       attachmentHistory?: SessionAttachmentHistoryItem[];
+      /** Remote execution metadata for sessions launched through SSH inside local tmux. */
+      remote?: SessionRemote;
+      /** Docker execution metadata for sessions launched inside a container via local tmux. */
+      docker?: SessionDocker;
+      /** Owning username (multi-user mode); undefined in single-user. */
+      owner?: string;
     }
   ) {
     super();
@@ -481,6 +567,16 @@ export class Session extends EventEmitter {
       this._codexConfig = config.codexConfig;
     }
 
+    // Apply Gemini configuration
+    if (config.geminiConfig) {
+      this._geminiConfig = config.geminiConfig;
+    }
+
+    // Apply Antigravity configuration
+    if (config.antigravityConfig) {
+      this._antigravityConfig = config.antigravityConfig;
+    }
+
     // Apply env overrides (exported at spawn, not persisted to disk).
     // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
     // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
@@ -495,6 +591,10 @@ export class Session extends EventEmitter {
     if (config.effort && isEffortLevel(config.effort)) {
       this._effort = config.effort;
     }
+    this._tmuxHistoryLimit = config.tmuxHistoryLimit ?? DEFAULT_TMUX_HISTORY_LIMIT;
+    this._remote = config.remote;
+    this._docker = config.docker;
+    this._owner = config.owner;
     if (config.attachmentHistory && config.attachmentHistory.length > 0) {
       this.restoreAttachmentHistory(config.attachmentHistory);
     }
@@ -596,6 +696,21 @@ export class Session extends EventEmitter {
     return this._claudeSessionId;
   }
 
+  /** Docker execution metadata when this session runs inside a container, else undefined. */
+  get docker(): SessionDocker | undefined {
+    return this._docker;
+  }
+
+  /** Owning username in multi-user mode, else undefined. */
+  get owner(): string | undefined {
+    return this._owner;
+  }
+
+  /** Set the owning username (used by recovery to restore ownership). */
+  set owner(username: string | undefined) {
+    this._owner = username;
+  }
+
   // Adopt a Claude conversation ID observed from an external source (e.g. hook
   // payload). In interactive PTY mode Claude CLI emits no JSON to stdout, so
   // `_handleJsonMessage` never sees `session_id`; hooks are the only signal
@@ -904,6 +1019,26 @@ export class Session extends EventEmitter {
     this._imageWatcherEnabled = enabled;
   }
 
+  /** Whether this session is pinned to the top of the session manager (COD-139). */
+  get pinned(): boolean {
+    return this._pinned;
+  }
+
+  /** When the session was pinned (epoch ms), or null when unpinned. */
+  get pinnedAt(): number | null {
+    return this._pinnedAt;
+  }
+
+  /**
+   * Set pin state (COD-139). Pinning stamps pinnedAt with now so the pinned
+   * group orders most-recently-pinned first; unpinning clears it. Idempotent:
+   * re-pinning an already-pinned session refreshes its pinnedAt.
+   */
+  setPinned(pinned: boolean): void {
+    this._pinned = pinned;
+    this._pinnedAt = pinned ? Date.now() : null;
+  }
+
   get flickerFilterEnabled(): boolean {
     return this._flickerFilterEnabled;
   }
@@ -954,6 +1089,9 @@ export class Session extends EventEmitter {
       pid: this.pid,
       status: this._status,
       workingDir: this.workingDir,
+      remote: this._remote,
+      docker: this._docker,
+      owner: this._owner,
       currentTaskId: this._currentTaskId,
       createdAt: this.createdAt,
       lastActivityAt: this._lastActivityAt,
@@ -967,6 +1105,8 @@ export class Session extends EventEmitter {
       autoResumeEnabled: this._autoOps.autoResumeEnabled,
       autoResumeAt: this._autoOps.autoResumeAt ?? undefined,
       imageWatcherEnabled: this._imageWatcherEnabled,
+      pinned: this._pinned || undefined,
+      pinnedAt: this._pinned ? (this._pinnedAt ?? undefined) : undefined,
       totalCost: this._totalCost,
       inputTokens: this._totalInputTokens,
       outputTokens: this._totalOutputTokens,
@@ -985,8 +1125,15 @@ export class Session extends EventEmitter {
       cliLatestVersion: this._cliLatestVersion || undefined,
       openCodeConfig: this._openCodeConfig,
       codexConfig: this._codexConfig,
+      geminiConfig: this._geminiConfig,
+      antigravityConfig: this._antigravityConfig,
       resumeSessionId: this._resumeSessionId,
       effort: this._effort,
+      // COD-118: runtime-only — surfaced so the frontend can require explicit user
+      // intent before restarting a crash-looped session. Deliberately NOT restored
+      // by the constructor: a Codeman restart starts with a fresh breaker so boot
+      // recovery can re-attach.
+      respawnBlocked: this._respawnBlocked || undefined,
       attachmentHistory: this.attachmentHistory.length > 0 ? this.attachmentHistory : undefined,
       // envOverrides intentionally NOT on the public SessionState type — they must not
       // leak into SSE / GET /api/sessions broadcasts (schema allows OPENCODE_*, which
@@ -1124,22 +1271,33 @@ export class Session extends EventEmitter {
       // No extra sleep — createSession() already waits for tmux readiness
     }
 
-    // Attach to the mux session via PTY
-    // Prevent tmux from letting the newest browser attach dictate global window
-    // size; accepted Codeman resize events update it explicitly below.
-    mux.setManualWindowSize?.(this._muxSession!.muxName);
+    // Integration tests need a live input/output transport without attaching to
+    // the host's tmux server or agent CLI. Production still uses the real mux.
+    if (!IS_TEST_MODE) {
+      // Prevent tmux from letting the newest browser attach dictate global window
+      // size; accepted Codeman resize events update it explicitly below.
+      mux.setManualWindowSize?.(this._muxSession!.muxName);
+    }
     // Query existing tmux window size so re-attach matches (avoids flicker from 120x40 default).
     // MUST go through the dedicated socket (mux.muxSocket); a bare `tmux display` hits the
     // default server, always fails for our socketed sessions, and silently falls back to 120x40.
-    const { cols: ptyCols, rows: ptyRows } = queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const { cols: ptyCols, rows: ptyRows } = IS_TEST_MODE
+      ? { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS }
+      : queryTmuxWindowSize(this._muxSession!.muxName, mux.muxSocket);
+    const attachCommand = IS_TEST_MODE ? process.execPath : mux.getAttachCommand();
+    const attachArgs = IS_TEST_MODE ? ['-e', TEST_PTY_SCRIPT] : mux.getAttachArgs(this._muxSession!.muxName);
     try {
-      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
-        name: 'xterm-256color',
-        cols: ptyCols,
-        rows: ptyRows,
-        cwd: this.workingDir,
-        env: buildMuxAttachEnv(),
-      });
+      this.ptyProcess = spawnPtyWithHelperRepair(() =>
+        pty.spawn(attachCommand, attachArgs, {
+          name: 'xterm-256color',
+          cols: ptyCols,
+          rows: ptyRows,
+          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
+          // COD-75: codex/gemini/antigravity get COLORTERM=truecolor — mirrors buildEnvExports()
+          // in tmux-manager.ts so the attach client and the tmux session agree.
+          env: buildMuxAttachEnv(this.mode === 'codex' || this.mode === 'gemini' || this.mode === 'antigravity'),
+        })
+      );
     } catch (spawnErr) {
       console.error(`[Session] Failed to spawn PTY for ${options.spawnErrLabel}:`, spawnErr);
       this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
@@ -1149,6 +1307,71 @@ export class Session extends EventEmitter {
     return { isRestored };
   }
 
+  /**
+   * COD-108 — re-establish a dropped REMOTE session. Triggered by the
+   * `TmuxManager` remote-reconnect watcher (via `remoteSessionDropped`): the
+   * watcher detects a dead remote pane, the session owner reassembles the SAME
+   * `RespawnPaneOptions` used for Claude-idle respawns and calls
+   * `respawnPane()` directly. For a remote session that re-runs
+   * `buildRemoteSessionCommand` (owned → `new-session -A`, non-owned →
+   * `attach`), which idempotently REATTACHES the still-running durable remote
+   * tmux session — scrollback + agent intact (proven COD-104/105).
+   *
+   * Deliberately does NOT route through the Claude-idle respawn-controller —
+   * this is a transport re-establish, not a `/clear`/`/compact` cycle.
+   *
+   * @returns true if the pane was respawned (reattach issued), false otherwise.
+   */
+  async reattachRemote(): Promise<boolean> {
+    if (!this._remote) return false; // not a remote session
+    if (!this._useMux || !this._mux || !this._muxSession) return false;
+    const mux = this._mux;
+
+    // If tmux lost the whole session (not just a dead pane), there is nothing to
+    // respawn into — a genuine death, leave it for normal recovery/reconcile.
+    if (!mux.muxSessionExists(this._muxSession.muxName)) {
+      console.log('[Session] reattachRemote: mux session gone, skipping:', this._muxSession.muxName);
+      return false;
+    }
+
+    const newPid = await mux.respawnPane(this._buildRespawnPaneOptions());
+    if (!newPid) {
+      console.error('[Session] reattachRemote: respawnPane failed for', this._muxSession.muxName);
+      return false;
+    }
+    console.log('[Session] reattachRemote: reattached remote session', this._muxSession.muxName, 'pid', newPid);
+    return true;
+  }
+
+  /**
+   * Assemble the {@link RespawnPaneOptions} for this session. Single source of
+   * truth shared by interactive start, shell start (via their inline copies),
+   * and {@link reattachRemote} so the remote reattach path can never drift from
+   * the spawn path.
+   */
+  private _buildRespawnPaneOptions(): import('./mux-interface.js').RespawnPaneOptions {
+    return {
+      sessionId: this.id,
+      workingDir: this.workingDir,
+      mode: this.mode,
+      niceConfig: this._niceConfig,
+      model: this._model,
+      claudeMode: this._claudeMode,
+      allowedTools: this._allowedTools,
+      openCodeConfig: this._openCodeConfig,
+      codexConfig: this._codexConfig,
+      geminiConfig: this._geminiConfig,
+      antigravityConfig: this._antigravityConfig,
+      resumeSessionId: this._resumeSessionId,
+      envOverrides: this._envOverrides,
+      effort: this._effort,
+      historyLimit: this._tmuxHistoryLimit,
+      remote: this._remote,
+      docker: this._docker,
+      owner: this._owner,
+    };
+  }
+
   private _handleTerminalOutput(data: string): void {
     // Codex AND Claude Code emit sequences that wipe xterm.js scrollback, plus
     // mouse-tracking enables that hijack the scroll wheel so the user can't reach
@@ -1196,18 +1419,26 @@ export class Session extends EventEmitter {
         .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, '');
     }
 
-    // Scan terminal output for `codeman://attach?path=...` magic links and emit
-    // an attachmentRequested event for each newly-seen absolute path. The web
-    // server turns these into registered attachment cards.
-    const attachmentPaths = parseAttachmentMagicLinks(data);
-    for (const attachmentPath of attachmentPaths) {
-      if (this._attachmentMagicSeen.has(attachmentPath)) continue;
-      this._attachmentMagicSeen.add(attachmentPath);
+    // Scan terminal output for attachment requests. `codeman://attach?...` is an
+    // explicit magic link (all modes); Codex generated images report
+    // `Saved to: file://...` — that scanner (and its relaxed trust policy) is
+    // only enabled for codex-mode sessions. The web server applies the trust
+    // boundary for each request source.
+    const attachmentRequests = parseTerminalAttachmentRequests(data, { codexArtifacts: this.mode === 'codex' });
+    for (const request of attachmentRequests) {
+      const seenKey = `${request.source}:${request.path}`;
+      if (this._attachmentMagicSeen.has(seenKey)) continue;
+      this._attachmentMagicSeen.add(seenKey);
       if (this._attachmentMagicSeen.size > 200) {
         const oldest = this._attachmentMagicSeen.values().next().value;
         if (oldest) this._attachmentMagicSeen.delete(oldest);
       }
-      this.emit('attachmentRequested', { sessionId: this.id, path: attachmentPath, timestamp: Date.now() });
+      this.emit('attachmentRequested', {
+        sessionId: this.id,
+        path: request.path,
+        source: request.source,
+        timestamp: Date.now(),
+      });
     }
 
     // BufferAccumulator handles auto-trimming when max size exceeded
@@ -1222,31 +1453,75 @@ export class Session extends EventEmitter {
       throw new Error('Session already has a running process');
     }
 
+    // COD-118: if the PTY exit breaker has tripped (repeated non-zero exits in a
+    // short window), refuse to respawn. This is the uniform choke point that stops
+    // automatic recovery/reconnect callers from re-creating a crash-looping PTY.
+    // An explicit user restart clears it via resetRespawnBreaker().
+    if (this._respawnBlocked) {
+      throw new Error(
+        'Respawn blocked: interactive PTY exited non-zero too many times in a short window (circuit breaker tripped). Restart the session to clear it.'
+      );
+    }
+
     this._resetBuffers();
 
-    const modeLabel = this.mode === 'opencode' ? 'OpenCode' : this.mode === 'codex' ? 'Codex' : 'Claude';
+    const modeLabel = getModeLabel(this.mode);
     console.log(
       `[Session] Starting interactive ${modeLabel} session` + (this._useMux ? ` (with ${this._mux!.backend})` : '')
     );
 
+    // Seed the CLI version deterministically for LOCAL Claude sessions. The
+    // banner scrape in parseClaudeCodeInfo() is unreliable — newer Claude Code
+    // builds don't print "Claude Code vX.Y.Z" at startup and resumed sessions
+    // never show it — which left cliVersion undefined and silently disabled
+    // wheel-forwarding to Claude's own transcript (the only route to history in
+    // repaint/alt-screen mode; issue #154). Remote sessions run claude on
+    // another host, so a local probe wouldn't reflect their version — skip them
+    // and let the banner scrape handle those. Cached process-wide, best-effort.
+    if (this.mode === 'claude' && !this._remote && !this._docker && !this._cliVersion) {
+      const probedVersion = getClaudeCliVersion();
+      if (probedVersion) {
+        this._cliVersion = probedVersion;
+        this.emit('cliInfoUpdated', {
+          version: this._cliVersion,
+          model: this._cliModel,
+          accountType: this._cliAccountType,
+          latestVersion: this._cliLatestVersion,
+        });
+      }
+    }
+
+    // Docker sessions run claude INSIDE the container, so the local probe above
+    // reports the HOST claude (wrong version, and leaving cliVersion undefined
+    // silently disables wheel-forwarding, #154). Probe the IN-CONTAINER version
+    // instead — deferred so the container is up after the mux attach below.
+    if (this.mode === 'claude' && this._docker && !this._cliVersion) {
+      const dockerMeta = this._docker;
+      setTimeout(() => {
+        if (this._isStopped || this._cliVersion) return;
+        void probeDockerCliVersion(dockerMeta, this.mode)
+          .then((version) => {
+            if (!version || this._isStopped || this._cliVersion) return;
+            this._cliVersion = version;
+            this.emit('cliInfoUpdated', {
+              version: this._cliVersion,
+              model: this._cliModel,
+              accountType: this._cliAccountType,
+              latestVersion: this._cliLatestVersion,
+            });
+          })
+          .catch(() => {
+            /* best-effort */
+          });
+      }, DOCKER_CLI_VERSION_PROBE_DELAY_MS);
+    }
+
     // If mux wrapping is enabled, create or attach to a mux session
     if (this._useMux && this._mux) {
       try {
         const { isRestored } = await this._setupOrAttachMuxSession({
-          respawnPaneOptions: {
-            sessionId: this.id,
-            workingDir: this.workingDir,
-            mode: this.mode,
-            niceConfig: this._niceConfig,
-            model: this._model,
-            claudeMode: this._claudeMode,
-            allowedTools: this._allowedTools,
-            openCodeConfig: this._openCodeConfig,
-            codexConfig: this._codexConfig,
-            resumeSessionId: this._resumeSessionId,
-            envOverrides: this._envOverrides,
-            effort: this._effort,
-          },
+          // Single source of truth shared with reattachRemote() (COD-108).
+          respawnPaneOptions: this._buildRespawnPaneOptions(),
           createSessionOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
@@ -1258,9 +1533,15 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             codexConfig: this._codexConfig,
+            geminiConfig: this._geminiConfig,
+            antigravityConfig: this._antigravityConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
+            historyLimit: this._tmuxHistoryLimit,
+            remote: this._remote,
+            docker: this._docker,
+            owner: this._owner,
           },
           spawnErrLabel: 'mux attachment',
         });
@@ -1331,18 +1612,28 @@ export class Session extends EventEmitter {
       if (this.mode === 'codex') {
         throw new Error('Codex sessions require tmux. Direct PTY fallback is not supported.');
       }
+      // Gemini sessions require tmux for Gemini/Google auth env injection via setenv
+      if (this.mode === 'gemini') {
+        throw new Error('Gemini sessions require tmux. Direct PTY fallback is not supported.');
+      }
+      // Antigravity sessions require tmux for env override injection via setenv
+      if (this.mode === 'antigravity') {
+        throw new Error('Antigravity sessions require tmux. Direct PTY fallback is not supported.');
+      }
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab
         const args = buildInteractiveArgs(this.id, this._claudeMode, this._model, this._allowedTools, this._effort);
-        this.ptyProcess = pty.spawn('claude', args, {
-          name: 'xterm-256color',
-          cols: 120,
-          rows: 40,
-          cwd: this.workingDir,
-          // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
-          env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
-        });
+        this.ptyProcess = spawnPtyWithHelperRepair(() =>
+          pty.spawn(getClaudeBinaryPath(), args, {
+            name: 'xterm-256color',
+            cols: 120,
+            rows: 40,
+            cwd: this.workingDir,
+            // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+            env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
+          })
+        );
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn Claude PTY:', spawnErr);
         this._status = 'stopped';
@@ -1366,7 +1657,7 @@ export class Session extends EventEmitter {
 
       // === Auto-accept workspace trust dialog ===
       // Claude CLI 2.x shows "Yes, I trust this folder" prompt on first launch per directory.
-      // Codeman sessions always use --dangerously-skip-permissions, so auto-accept.
+      // Codeman sessions run permission-skipping or classifier-guarded (auto) modes, so auto-accept.
       if (!this._trustDialogAccepted && data.includes('trust this folder')) {
         this._trustDialogAccepted = true;
         console.log(`[Session] Auto-accepting workspace trust dialog for: ${this.id}`);
@@ -1454,6 +1745,9 @@ export class Session extends EventEmitter {
 
     this.ptyProcess.onExit(({ exitCode }) => {
       console.log('[Session] Interactive PTY exited with code:', exitCode);
+      // COD-118: record the exit in the circuit breaker BEFORE status bookkeeping.
+      // A clean (0) exit resets the counter; rapid non-zero repeats trip it.
+      const breakerResult = this._ptyExitBreaker.recordExit(exitCode, Date.now());
       this.ptyProcess = null;
       this._pid = null;
       this._status = 'idle';
@@ -1481,10 +1775,38 @@ export class Session extends EventEmitter {
       if (this._muxSession && this._mux) {
         this._mux.setAttached(this.id, false);
       }
+      // COD-118: if the breaker tripped, surface an error state and block the NEXT
+      // respawn so recovery/reconnect callers stop looping. Still emit 'exit' below
+      // for normal cleanup. Cleared by an explicit user restart (resetRespawnBreaker()).
+      if (breakerResult.tripped && !this._respawnBlocked) {
+        this._respawnBlocked = true;
+        this._status = 'error';
+        console.error(
+          `[Session] PTY exit circuit breaker tripped for ${this.id} (${breakerResult.count} non-zero exits within window); blocking respawn.`
+        );
+        this.emit('respawnBreakerTripped', { count: breakerResult.count });
+      }
       this.emit('exit', exitCode);
     });
   }
 
+  /**
+   * Clear the interactive-PTY exit circuit breaker (COD-118).
+   *
+   * Called on an EXPLICIT, user-initiated (re)start so an intentional restart is
+   * never blocked by a prior crash-loop trip. Automatic recovery/reconnect paths
+   * must NOT call this — that's the whole point of the breaker.
+   */
+  resetRespawnBreaker(): void {
+    this._ptyExitBreaker.reset();
+    this._respawnBlocked = false;
+  }
+
+  /** Whether the interactive-PTY exit circuit breaker is currently tripped (COD-118). */
+  get respawnBlocked(): boolean {
+    return this._respawnBlocked;
+  }
+
   /**
    * Process expensive parsers (ANSI strip, Ralph, bash tool, token, CLI info, task descriptions).
    * Called on a throttled schedule (every EXPENSIVE_PROCESS_INTERVAL_MS) instead of on every
@@ -1577,8 +1899,9 @@ export class Session extends EventEmitter {
 
     this._resetBuffers();
 
-    // Use user's default shell or bash
-    const shell = process.env.SHELL || '/bin/bash';
+    // Use user's default shell, falling back to a shell that actually exists.
+    // Shared with the tmux pane command so both paths launch the same binary.
+    const shell = resolveLocalShell();
     console.log(
       '[Session] Starting shell session with:',
       shell + (this._useMux ? ` (with ${this._mux!.backend})` : '')
@@ -1594,6 +1917,10 @@ export class Session extends EventEmitter {
             mode: 'shell',
             niceConfig: this._niceConfig,
             envOverrides: this._envOverrides,
+            historyLimit: this._tmuxHistoryLimit,
+            remote: this._remote,
+            docker: this._docker,
+            owner: this._owner,
           },
           createSessionOptions: {
             sessionId: this.id,
@@ -1602,6 +1929,10 @@ export class Session extends EventEmitter {
             name: this._name,
             niceConfig: this._niceConfig,
             envOverrides: this._envOverrides,
+            historyLimit: this._tmuxHistoryLimit,
+            remote: this._remote,
+            docker: this._docker,
+            owner: this._owner,
           },
           spawnErrLabel: 'shell mux attachment',
         });
@@ -1626,13 +1957,15 @@ export class Session extends EventEmitter {
     // Fallback to direct PTY if mux is not used
     if (!this.ptyProcess) {
       try {
-        this.ptyProcess = pty.spawn(shell, [], {
-          name: 'xterm-256color',
-          cols: 120,
-          rows: 40,
-          cwd: this.workingDir,
-          env: buildShellEnv(this.id),
-        });
+        this.ptyProcess = spawnPtyWithHelperRepair(() =>
+          pty.spawn(shell, [], {
+            name: 'xterm-256color',
+            cols: 120,
+            rows: 40,
+            cwd: this.workingDir,
+            env: buildShellEnv(this.id),
+          })
+        );
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn shell PTY:', spawnErr);
         this._status = 'stopped';
@@ -1729,17 +2062,19 @@ export class Session extends EventEmitter {
           model ? `(model: ${model})` : ''
         );
 
-        const args = buildPromptArgs(prompt, model);
+        const args = buildPromptArgs(prompt, model, this._claudeMode, this._allowedTools);
 
         try {
-          this.ptyProcess = pty.spawn('claude', args, {
-            name: 'xterm-256color',
-            cols: 120,
-            rows: 40,
-            cwd: this.workingDir,
-            // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
-            env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
-          });
+          this.ptyProcess = spawnPtyWithHelperRepair(() =>
+            pty.spawn(getClaudeBinaryPath(), args, {
+              name: 'xterm-256color',
+              cols: 120,
+              rows: 40,
+              cwd: this.workingDir,
+              // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+              env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
+            })
+          );
         } catch (spawnErr) {
           console.error('[Session] Failed to spawn Claude PTY for runPrompt:', spawnErr);
           this.emit(
@@ -2208,11 +2543,65 @@ export class Session extends EventEmitter {
    * ```
    */
   write(data: string): void {
+    this._trackCodexSubmit(data);
     if (this.ptyProcess) {
       this.ptyProcess.write(data);
     }
   }
 
+  // ── Codex thread tracking ─────────────────────────────────────────────
+  // When a codex pane last submitted a message (Enter). The response-viewer
+  // correlates this against ~/.codex/history.jsonl entry timestamps to find
+  // the thread the pane is ACTUALLY on — the only signal that survives
+  // /resume, /new and /fork typed inside the codex TUI itself.
+  private _codexLastSubmitAt = 0;
+
+  get codexLastSubmitAt(): number {
+    return this._codexLastSubmitAt;
+  }
+
+  private _trackCodexSubmit(data: string): void {
+    if (this.mode === 'codex' && (data.includes('\r') || data.includes('\n'))) {
+      this._codexLastSubmitAt = Date.now();
+    }
+  }
+
+  /**
+   * Per-client highest-applied input sequence, for exactly-once input delivery.
+   * Keyed by the web client's stable `clientId`. Bounded so many devices over a
+   * long-lived session can't grow it without limit (insertion order = MRU, so
+   * eviction drops the least-recently-active client).
+   */
+  private _appliedInputSeq = new Map<string, number>();
+  private static readonly MAX_INPUT_DEDUP_CLIENTS = 256;
+
+  /**
+   * Decide whether an input frame should be applied to the PTY or skipped as a
+   * duplicate redelivery. Returns true exactly once per (clientId, seq): the
+   * first time a seq strictly greater than the client's last-applied is seen.
+   * A redelivery of an already-applied seq (the client never got our ACK and
+   * resent) returns false. Callers should ACK regardless — a duplicate is, from
+   * the client's view, "delivered" — and only `write()` the PTY when this is
+   * true. Relies on the client delivering one client's frames in seq order over
+   * a single ordered stream, so `seq <= last` ⇒ already applied.
+   *
+   * Without this, the client's at-least-once redelivery (needed because a
+   * half-open socket silently drops frames with no error) would type a prompt
+   * twice whenever an ACK is lost after the write landed.
+   */
+  shouldApplyInput(clientId: string, seq: number): boolean {
+    const last = this._appliedInputSeq.get(clientId);
+    if (last !== undefined && seq <= last) return false;
+    // Re-insert to move this client to the MRU end for fair eviction.
+    if (last !== undefined) this._appliedInputSeq.delete(clientId);
+    this._appliedInputSeq.set(clientId, seq);
+    if (this._appliedInputSeq.size > Session.MAX_INPUT_DEDUP_CLIENTS) {
+      const oldest = this._appliedInputSeq.keys().next().value;
+      if (oldest !== undefined) this._appliedInputSeq.delete(oldest);
+    }
+    return true;
+  }
+
   /**
    * Sends input via the terminal multiplexer's direct input mechanism.
    *
@@ -2230,6 +2619,7 @@ export class Session extends EventEmitter {
    * ```
    */
   async writeViaMux(data: string): Promise<boolean> {
+    this._trackCodexSubmit(data);
     if (this._mux && this._muxSession) {
       return this._mux.sendInput(this.id, data);
     }
@@ -2338,7 +2728,7 @@ export class Session extends EventEmitter {
     if (this.ptyProcess && (dimsChanged || options.force)) {
       this._ptyCols = cols;
       this._ptyRows = rows;
-      if (this._mux && this._muxSession) {
+      if (!IS_TEST_MODE && this._mux && this._muxSession) {
         this._mux.resizeWindow?.(this._muxSession.muxName, cols, rows);
       }
       this.ptyProcess.resize(cols, rows);

src/state-store.ts

@@ -272,6 +272,15 @@ export class StateStore {
     if (this.state.tokenStats) {
       parts.push(`"tokenStats":${JSON.stringify(this.state.tokenStats)}`);
     }
+    if (this.state.cronJobs) {
+      parts.push(`"cronJobs":${JSON.stringify(this.state.cronJobs)}`);
+    }
+    if (this.state.cronJobRuns) {
+      parts.push(`"cronJobRuns":${JSON.stringify(this.state.cronJobRuns)}`);
+    }
+    if (this.state.sessionOrder) {
+      parts.push(`"sessionOrder":${JSON.stringify(this.state.sessionOrder)}`);
+    }
 
     return `{${parts.join(',')}}`;
   }
@@ -479,6 +488,25 @@ export class StateStore {
     this.save();
   }
 
+  /**
+   * COD-142: Remove a session's persisted record on kill UNLESS it is pinned.
+   * A pinned session is demoted to a lightweight `stopped` record (pin retained)
+   * so it stays visible in the session-manager pinned group and survives restart.
+   * Unpinned sessions are fully removed (unchanged behavior).
+   * @returns 'preserved' if demoted to stopped+pinned, 'removed' if deleted, 'absent' if no record existed.
+   */
+  demoteOrRemoveSession(id: string): 'preserved' | 'removed' | 'absent' {
+    const existing = this.state.sessions[id];
+    if (!existing) return 'absent';
+    if (existing.pinned === true) {
+      // Demote in place: keep identity/resume fields + pin, mark stopped, clear live runtime.
+      this.setSession(id, { ...existing, status: 'stopped', pid: null });
+      return 'preserved';
+    }
+    this.removeSession(id);
+    return 'removed';
+  }
+
   /**
    * Cleans up stale sessions from state that don't have corresponding active sessions.
    * @param activeSessionIds - Set of currently active session IDs
@@ -493,6 +521,7 @@ export class StateStore {
 
     for (const sessionId of allSessionIds) {
       if (!activeSessionIds.has(sessionId)) {
+        if (this.state.sessions[sessionId]?.pinned === true) continue; // COD-142: pinned records persist even with no live session
         const name = this.state.sessions[sessionId]?.name;
         cleaned.push({ id: sessionId, name });
         delete this.state.sessions[sessionId];
@@ -568,6 +597,51 @@ export class StateStore {
     this.save();
   }
 
+  // ========== Cron Job Methods ==========
+
+  /** Returns all scheduled jobs keyed by job ID. */
+  getCronJobs(): Record<string, import('./types/cron.js').CronJob> {
+    if (!this.state.cronJobs) this.state.cronJobs = {};
+    return this.state.cronJobs;
+  }
+
+  /** Returns a scheduled job by ID, or null if not found. */
+  getCronJob(id: string): import('./types/cron.js').CronJob | null {
+    return this.state.cronJobs?.[id] ?? null;
+  }
+
+  /** Sets a scheduled job and triggers a debounced save. */
+  setCronJob(id: string, job: import('./types/cron.js').CronJob): void {
+    if (!this.state.cronJobs) this.state.cronJobs = {};
+    this.state.cronJobs[id] = job;
+    this.save();
+  }
+
+  /** Removes a scheduled job and triggers a debounced save. */
+  removeCronJob(id: string): void {
+    if (this.state.cronJobs) delete this.state.cronJobs[id];
+    this.save();
+  }
+
+  /** Returns all scheduled job runs keyed by run ID. */
+  getCronJobRuns(): Record<string, import('./types/cron.js').CronJobRun> {
+    if (!this.state.cronJobRuns) this.state.cronJobRuns = {};
+    return this.state.cronJobRuns;
+  }
+
+  /** Sets a scheduled job run (history record) and triggers a debounced save. */
+  setCronJobRun(id: string, run: import('./types/cron.js').CronJobRun): void {
+    if (!this.state.cronJobRuns) this.state.cronJobRuns = {};
+    this.state.cronJobRuns[id] = run;
+    this.save();
+  }
+
+  /** Removes a scheduled job run and triggers a debounced save. */
+  removeCronJobRun(id: string): void {
+    if (this.state.cronJobRuns) delete this.state.cronJobRuns[id];
+    this.save();
+  }
+
   /** Returns the application configuration. */
   getConfig() {
     return this.state.config;
@@ -579,6 +653,17 @@ export class StateStore {
     this.save();
   }
 
+  /** Returns the global tab order (ordered sessionIds), [] if unset. COD-131. */
+  getSessionOrder(): string[] {
+    return this.state.sessionOrder ?? [];
+  }
+
+  /** Persists the global tab order (ordered sessionIds) and triggers a debounced save. COD-131. */
+  setSessionOrder(order: string[]): void {
+    this.state.sessionOrder = order;
+    this.save();
+  }
+
   /** Resets all state to initial values and saves immediately. */
   reset(): void {
     this.state = createInitialState();

src/transcript-watcher.ts

@@ -40,6 +40,7 @@ interface TranscriptContentBlock {
   text?: string;
   name?: string;
   input?: Record<string, unknown>;
+  tool_use_id?: string;
   content?: string;
   is_error?: boolean;
 }
@@ -328,10 +329,7 @@ export class TranscriptWatcher extends EventEmitter {
         this.handleResultEntry(entry);
         break;
       case 'user':
-        // User message means new turn, reset some state
-        this.state.isComplete = false;
-        this.state.hasError = false;
-        this.state.errorMessage = null;
+        this.handleUserEntry(entry);
         break;
       case 'system':
         // System messages are informational
@@ -360,23 +358,42 @@ export class TranscriptWatcher extends EventEmitter {
           this.state.currentTool = block.name;
           this.emit('transcript:tool_start', block.name);
         } else if (block.type === 'tool_result') {
-          // Tool completed
-          const wasError = block.is_error === true;
-          const toolName = this.state.currentTool;
-          this.state.toolExecuting = false;
-          this.state.currentTool = null;
-          if (toolName) {
-            this.emit('transcript:tool_end', toolName, wasError);
-          }
-          if (wasError && block.content) {
-            this.state.hasError = true;
-            this.state.errorMessage = String(block.content).slice(0, 200);
-          }
+          this.handleToolResult(block);
         }
       }
     }
   }
 
+  private handleUserEntry(entry: TranscriptEntry): void {
+    // A user-authored prompt starts a turn, while Claude tool results also use
+    // user entries. Reset turn state first, then close any completed tool.
+    this.state.isComplete = false;
+    this.state.hasError = false;
+    this.state.errorMessage = null;
+
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) return;
+    for (const block of content) {
+      if (block.type === 'tool_result') {
+        this.handleToolResult(block);
+      }
+    }
+  }
+
+  private handleToolResult(block: TranscriptContentBlock): void {
+    const wasError = block.is_error === true;
+    const toolName = this.state.currentTool;
+    this.state.toolExecuting = false;
+    this.state.currentTool = null;
+    if (toolName) {
+      this.emit('transcript:tool_end', toolName, wasError);
+    }
+    if (wasError && block.content) {
+      this.state.hasError = true;
+      this.state.errorMessage = String(block.content).slice(0, 200);
+    }
+  }
+
   private handleResultEntry(entry: TranscriptEntry): void {
     // Result entry indicates completion
     this.state.isComplete = true;

src/tunnel-manager.ts

@@ -15,10 +15,8 @@
 
 import { EventEmitter } from 'node:events';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
+import { resolveCloudflaredPath } from './utils/cloudflared-resolver.js';
 import {
   QR_TOKEN_TTL_MS,
   QR_TOKEN_GRACE_MS,
@@ -43,6 +41,8 @@ interface QrTokenRecord {
   shortCode: string; // 6 chars base62 (for URL path)
   createdAt: number; // Date.now()
   consumed: boolean; // single-use flag
+  /** Multi-user: the user this token logs in when redeemed (absent = rotating global token). */
+  username?: string;
 }
 
 /** Rejection-sampled base62 short code — no modulo bias */
@@ -93,23 +93,10 @@ export class TunnelManager extends EventEmitter {
   private resolveCloudflared(): string | null {
     if (this.cloudflaredPath) return this.cloudflaredPath;
 
-    // Check ~/.local/bin first (common user install location)
-    const localBin = join(homedir(), '.local', 'bin', 'cloudflared');
-    if (existsSync(localBin)) {
-      this.cloudflaredPath = localBin;
-      return localBin;
-    }
-
-    // Check /usr/local/bin
-    const usrLocalBin = '/usr/local/bin/cloudflared';
-    if (existsSync(usrLocalBin)) {
-      this.cloudflaredPath = usrLocalBin;
-      return usrLocalBin;
-    }
-
-    // Fall back to PATH
-    this.cloudflaredPath = 'cloudflared';
-    return 'cloudflared';
+    // Shared with the welcome-screen availability check, so the button and the
+    // spawn can never disagree about where cloudflared lives.
+    this.cloudflaredPath = resolveCloudflaredPath() ?? 'cloudflared';
+    return this.cloudflaredPath;
   }
 
   /** Clear all pending timers */
@@ -378,23 +365,64 @@ export class TunnelManager extends EventEmitter {
    * Map.get() is hash-based — no timing side-channel from string comparison.
    */
   consumeToken(shortCode: string): boolean {
+    return this.consumeTokenWithIdentity(shortCode).ok;
+  }
+
+  /**
+   * Like consumeToken, but also returns the bound username for multi-user tokens
+   * (undefined for the rotating global token). Only the identity-less rotating
+   * token triggers an immediate re-rotation (desktop gets a fresh QR); per-user
+   * tokens are on-demand and self-expire.
+   */
+  consumeTokenWithIdentity(shortCode: string): { ok: boolean; username?: string } {
     // Global rate limit (across all IPs)
-    if (this.qrAttemptCount >= QR_RATE_LIMIT_MAX) return false;
+    if (this.qrAttemptCount >= QR_RATE_LIMIT_MAX) return { ok: false };
     this.qrAttemptCount++;
 
     const record = this.qrTokensByCode.get(shortCode);
-    if (!record) return false;
-    if (record.consumed) return false;
+    if (!record) return { ok: false };
+    if (record.consumed) return { ok: false };
 
     const now = Date.now();
-    if (now - record.createdAt > QR_TOKEN_GRACE_MS) return false;
+    if (now - record.createdAt > QR_TOKEN_GRACE_MS) return { ok: false };
 
     // Atomic consume (single-threaded JS = no race)
     record.consumed = true;
-    // Immediately rotate so desktop gets a fresh QR
-    this.rotateToken();
-    this.emit('qrTokenRegenerated');
-    return true;
+    const username = record.username;
+    if (!username) {
+      // Rotating global token — immediately rotate so desktop gets a fresh QR.
+      this.rotateToken();
+      this.emit('qrTokenRegenerated');
+    } else {
+      this.qrTokensByCode.delete(shortCode);
+    }
+    return { ok: true, username };
+  }
+
+  /**
+   * Multi-user: mint a single-use token bound to a specific user (on-demand, no
+   * rotation). Evicts expired/consumed tokens first. Returns the short code.
+   */
+  mintUserToken(username: string): string {
+    const now = Date.now();
+    for (const [code, rec] of this.qrTokensByCode) {
+      if (now - rec.createdAt > QR_TOKEN_GRACE_MS || rec.consumed) this.qrTokensByCode.delete(code);
+    }
+    const record: QrTokenRecord = {
+      token: randomBytes(32).toString('hex'),
+      shortCode: generateShortCode(),
+      createdAt: Date.now(),
+      consumed: false,
+      username,
+    };
+    this.qrTokensByCode.set(record.shortCode, record);
+    return record.shortCode;
+  }
+
+  /** Render a QR SVG for an arbitrary short code (used by per-user minting). */
+  async getQrSvgForCode(tunnelUrl: string, code: string): Promise<string> {
+    const QRCode = await import('qrcode');
+    return QRCode.toString(`${tunnelUrl}/q/${code}`, { type: 'svg', margin: 2, width: 256 });
   }
 
   /** Force-regenerate (manual revocation via API) */

src/types/api.ts

@@ -37,6 +37,16 @@ export enum ApiErrorCode {
   RATE_LIMITED = 'RATE_LIMITED',
   /** Operation could not be completed (well-formed but unprocessable) */
   OPERATION_FAILED = 'OPERATION_FAILED',
+  /** Authenticated but not permitted (e.g. non-admin hitting an admin route) */
+  FORBIDDEN = 'FORBIDDEN',
+  /** User must change their password before any other action (multi-user) */
+  PASSWORD_CHANGE_REQUIRED = 'PASSWORD_CHANGE_REQUIRED',
+  /** A user with this name already exists (multi-user) */
+  USER_EXISTS = 'USER_EXISTS',
+  /** No user with this name (multi-user) */
+  USER_NOT_FOUND = 'USER_NOT_FOUND',
+  /** Refusing to demote/disable/delete the last enabled admin (multi-user) */
+  LAST_ADMIN = 'LAST_ADMIN',
   /** Internal server error */
   INTERNAL_ERROR = 'INTERNAL_ERROR',
 }
@@ -53,6 +63,11 @@ const ErrorMessages: Record<ApiErrorCode, string> = {
   [ApiErrorCode.ALREADY_EXISTS]: 'Resource already exists',
   [ApiErrorCode.RATE_LIMITED]: 'Too many requests',
   [ApiErrorCode.OPERATION_FAILED]: 'The operation failed',
+  [ApiErrorCode.FORBIDDEN]: 'You do not have permission to perform this action',
+  [ApiErrorCode.PASSWORD_CHANGE_REQUIRED]: 'You must change your password before continuing',
+  [ApiErrorCode.USER_EXISTS]: 'A user with that name already exists',
+  [ApiErrorCode.USER_NOT_FOUND]: 'No such user',
+  [ApiErrorCode.LAST_ADMIN]: 'Cannot remove the last enabled admin',
   [ApiErrorCode.INTERNAL_ERROR]: 'An internal error occurred',
 };
 
@@ -69,6 +84,11 @@ const ErrorStatus: Record<ApiErrorCode, number> = {
   [ApiErrorCode.CONFLICT]: 409,
   [ApiErrorCode.ALREADY_EXISTS]: 409,
   [ApiErrorCode.OPERATION_FAILED]: 422,
+  [ApiErrorCode.FORBIDDEN]: 403,
+  [ApiErrorCode.PASSWORD_CHANGE_REQUIRED]: 403,
+  [ApiErrorCode.USER_EXISTS]: 409,
+  [ApiErrorCode.USER_NOT_FOUND]: 404,
+  [ApiErrorCode.LAST_ADMIN]: 409,
   [ApiErrorCode.RATE_LIMITED]: 429,
   [ApiErrorCode.INTERNAL_ERROR]: 500,
 };
@@ -123,6 +143,25 @@ export interface CaseInfo {
   path: string;
   /** Whether CLAUDE.md exists */
   hasClaudeMd?: boolean;
+  /** Case storage/execution location */
+  location?: 'local' | 'linked-local' | 'remote' | 'docker';
+  /** Whether this is a linked local folder */
+  linked?: boolean;
+  /** Remote case metadata for display and session creation */
+  remote?: {
+    hostId: string;
+    host: string;
+    username: string;
+    path: string;
+  };
+  /** Docker case metadata for display and session creation */
+  docker?: {
+    hostId: string;
+    container: string;
+    image?: string;
+    path: string;
+    network?: string;
+  };
 }
 
 // ========== Error Handling Utilities ==========