chore: version packages — Codeman 1.0.0

Bumps aicodeman 0.9.14 → 1.0.0 (theme skins + first stable release). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
feat(ui): theme skins — OG Codeman, Daylight Green, Daylight Blue
2026-09-30 20:49:41 +02:00 · 2026-06-13 23:30:34 +02:00 · 2026-06-13 23:21:47 +02:00 · 2026-06-11 10:32:34 +02:00 · 2026-06-11 10:27:09 +02:00 · 2026-06-11 10:27:09 +02:00
146 changed files with 10198 additions and 1706 deletions
@@ -31,6 +31,9 @@ jobs:
      - name: Lint
        run: npm run lint

+      - name: Frontend JS syntax check
+        run: npm run check:frontend-syntax
+
      - name: Format check
        run: npm run format:check

@@ -60,6 +63,34 @@ jobs:
          cat /tmp/boot.log
          exit 1

-# Note: The test suite is intentionally excluded from CI.
-# Tests spawn real tmux sessions and require a full system environment.
-# Run tests locally with: npx vitest run test/<file>.test.ts
+  test:
+    name: Unit & integration tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install tmux
+        run: |
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+
+      - name: Run unit & integration tests
+        # Excludes the browser-driven mobile suite (test/mobile/**); see config/vitest.ci.config.ts.
+        # Safe in CI: TmuxManager no-ops all shell commands under VITEST (test/setup.ts).
+        run: npm run test:ci
+
+# Note: The browser-driven mobile suite (test/mobile/**) is excluded from CI —
+# it needs a live server + chromium + environment-specific PNG baselines.
+# Run it locally/manually. All other tests run via the `test` job above.
@@ -18,6 +18,10 @@ coverage/
 test/e2e/screenshots/current/
 test/e2e/screenshots/diffs/

+# Mobile visual regression failure artifacts
+test/mobile/snapshots/*.actual.png
+test/mobile/snapshots/*.diff.png
+
 # Logs
 *.log
 npm-debug.log*
@@ -0,0 +1,16 @@
+# Repository Guidelines
+
+Canonical agent/contributor guidance for this repository lives in [CLAUDE.md](CLAUDE.md) —
+project structure, build/test/lint commands, code style, testing safety rules
+(never run the full suite inside a managed tmux session), security notes, and
+the deployment workflow are all maintained there. Please read it before making
+changes, and keep it the single source of truth rather than duplicating
+sections here.
+
+Quick pointers:
+
+- Type check: `tsc --noEmit` · Lint: `npm run lint` · Format: `npm run format:check`
+- Targeted tests only: `npm test -- test/<file>.test.ts` (bare `npm test` is unsafe in managed sessions)
+- Route tests use `app.inject()`; new tests needing ports must pick a unique `const PORT =`
+- Branch off `master` for all work; Conventional Commit-style messages (`fix(mobile): ...`)
+- Never commit secrets or local state from `~/.codeman/`
@@ -1,5 +1,125 @@
 # aicodeman

+## 1.0.0
+
+### Major Changes
+
+- # Codeman 1.0.0 🎉
+
+  The first stable release of Codeman — and it comes with a fresh new look.
+
+  **New: theme skins.** Codeman now ships a built-in skin switcher (App Settings → Display → Appearance):
+  - **OG Codeman** — the original look, preserved exactly.
+  - **Daylight Green** — a fresh emerald-on-slate theme.
+  - **Daylight Blue** — bright sky-blue on lifted slate (the new default).
+
+  Skins apply instantly, persist per device (with a pre-paint script so there's no flash on load), and re-theme any open terminals live. The system is built on `html[data-skin]` design tokens and self-hosted Manrope (UI) + JetBrains Mono (terminal) fonts — no external CDN, CSP-safe.
+
+  **1.0.0 milestone.** This marks the start of the stable 1.x line: the CLI, documented environment variables, and the `{ success, data }` HTTP/SSE API envelope follow semantic versioning (see `docs/versioning-policy.md`).
+
+  **Thank you to everyone who helped build Codeman.** This release is dedicated to all of our contributors for their work on the project: Ark0N, Aamer Akhter (@aakhter), Tenggan Zhang (@TeigenZhang), zhouyuan / @sunnyzhouy, jaypark, Marco Migozzi, Skúli Arnlaugsson, Aaron Fields, Loïc Sculier, and Noah Waldner (@noahwaldner). 💙
+
+## 0.9.14
+
+### Patch Changes
+
+- Security hardening for the tunnel exposure path, Codex terminal rendering fixes, and a mobile modal fix.
+
+  **Security (PR #115, COD-54/COD-55):**
+  - `/api/hook-event` localhost bypass is now gated while the managed Cloudflare tunnel is running: tunneled traffic arrives with a loopback source IP, so the bypass additionally requires a per-instance shared secret (`X-Codeman-Hook-Secret`, 256-bit, `~/.codeman/hook-secret`, mode 0600). Locally generated hook commands read the secret file at execution time via `$CODEMAN_HOOK_SECRET_FILE` (exported into every managed session's environment), so the value never lands on command lines or in case configs, and running sessions pick up a new secret without respawn. Failed presentations rate-limit in a dedicated per-IP bucket so misfiring legacy hooks can never lock out the Basic-Auth login path. With no tunnel running, behavior is unchanged.
+  - Enabling the Cloudflare tunnel now **refuses with 403** when no `CODEMAN_PASSWORD` is set (a public tunnel URL with no auth is effectively public RCE), unless `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` explicitly acknowledges the exposure. The settings UI surfaces the refusal as an error toast and reverts the toggle.
+
+  **Codex rendering (PRs #116, #117):**
+  - Alt-screen toggles (`?47/?1047/?1049`), scrollback-erase (`CSI 3 J`), and mouse-tracking enables (`?1000`–`?1007`) are stripped from the Codex byte stream (live + replay), so conversation history survives tab switches and the scroll wheel scrolls the viewport instead of being hijacked. Sequences split across PTY chunk boundaries are reassembled via a small carry before stripping, so a split `?1049h` can no longer trap xterm in the scrollback-less alt buffer.
+  - Smaller 32KB first-frame write budget for Codex sessions keeps dense synchronized redraws from stalling the renderer; a 1.5s grace window after a manual scroll-up suppresses sticky-scroll so high-frequency `• Working (Ns)` status ticks no longer snap the viewport back to the bottom while reading earlier output.
+
+  **Mobile:** session-options modal raised above the fixed mobile/tablet header (z-index 1300 vs 1200) so the close button is reachable on phones; Respawn tab controls regrouped.
+
+  **Docs:** security-architecture.md updated for the secret-gated hook bypass (including the external-proxy caveat) and the tunnel password guard; README documents auto-resume on usage limit.
+
+## 0.9.13
+
+### Patch Changes
+
+- Auto-resume on usage limit ("token pause" control) plus a set of mobile-view fixes for regressions introduced in 0.9.8.
+
+  **Auto-resume on usage limit** — new opt-in checkbox at the top of the session Respawn tab (off by default). When Claude stops because a usage limit was reached, Codeman parses the reset time from the limit message, waits until the limit lifts (plus a 2-minute safety buffer), then dismisses the rate-limit dialog (Esc) and sends "continue" so the session picks its work back up automatically. All Claude Code message formats from 1.0.x through 2.1.x are recognized ("5-hour limit reached ∙ resets 8pm", "Limit reached · resets 1pm (America/Chicago) · /upgrade…", "You've hit your weekly limit · resets Mon 12:00am", weekly date forms, and the raw API `usage limit reached|<epoch>` form). Still-limited responses re-arm the scheduler (5-minute retry loop); a pending schedule persists across Codeman restarts and re-arms on boot; respawn cycles are blocked while a limit pause is active so the cycle's `/clear` cannot wipe the paused conversation. New endpoint `POST /api/sessions/:id/auto-resume`; new SSE events `session:limitPauseScheduled`, `session:limitResume`, `session:limitResumeCancelled`; toast/notification on pause and resume, plus a live "resumes at HH:MM" status line in the modal. The Respawn tab layout was also tidied: compact single-row Update/Kickstart prompt fields and a merged options row.
+
+  **Mobile fixes (0.9.8 regressions)**:
+  - **Activity-based resize arbitration** — a desktop sizing claim now only blocks a phone's resize while that desktop has actually typed within the last 90 seconds. Previously any connected desktop tab (even one abandoned hours ago) silently discarded the phone's resize with no fallback, leaving the phone rendering a desktop-width stream in a narrow terminal: mid-word wraps, tmux dot-fill rows, overdrawn garbled text, and misplaced keyboard echo. Now an idle desktop yields the pane to the phone, and the next desktop keystroke automatically restores the desktop layout ("whoever is actively using the session wins"). Phones also re-send their dimensions every 30 seconds (visible tab only, skipped while the virtual keyboard is open) so attaching under a momentarily-active desktop self-corrects.
+  - **Keyboard accessory bar and toolbar restored on iOS** — the lift offset is measured against the layout viewport (`window.innerHeight`) again instead of the keyboard-shrunken app element; on iOS the offset computed to 0, leaving both bars hidden behind the OS keyboard with a dead black gap above it.
+  - **Removed the mobile header utility ("three dots") toggle** — the header-utilities tray stays collapsed on small viewports.
+
+## 0.9.12
+
+### Patch Changes
+
+- Documentation refresh — README catches up with the Codex run mode, plus a CLAUDE.md correction.
+
+  **README (en + zh-CN)**: Codex is now listed as a third supported AI coding CLI everywhere the docs previously said "Claude Code or OpenCode": the install requirement in Quick Start (now "any combination works", linking to the official Codex CLI docs), the Windows/WSL setup note, the renamed **Multi-CLI** feature bullet (env-prefix gating now reads `CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*`), the Zod schema-validation security bullet, and the architecture mermaid diagram. The header tagline was also finalized to "Claude Code • OpenCode • Codex — One Dashboard • Any Device" in both languages.
+
+  **CLAUDE.md**: fixed a stale "Local packages" line that claimed the xterm-zerolag-input local-echo overlay had a copy embedded in `app.js` — it is single-source in `packages/xterm-zerolag-input/`, bundled to the gitignored vendor file, and only consumed by `app.js`, matching the existing single-source gotcha.
+
+## 0.9.11
+
+### Patch Changes
+
+- Fix a terminal freeze on hover (catastrophic regex backtracking) and a CSP violation that disabled the terminal's anti-throttling worker.
+
+  **Tab-freezing hover bug**: the terminal link provider's `cmdPattern` (which turns `tail -f /path`-style text into clickable links) used an empty-matchable, unbounded arg group — `(?:[^\s\/]*\s+)*` — that backtracks exponentially on real Claude output, e.g. wrapped `git commit -m "$(cat <<'EOF'` heredoc lines or aligned table rows. Hovering the mouse over such a line hung the page's main thread for minutes ("page unresponsive"). The pattern now uses non-empty tokens with bounded repetition (linear time); all intended command+path link forms still match. New `test/link-provider-regex.test.ts` extracts the shipped patterns from source and pins linear-time behavior on the killer line shapes.
+
+  **Blob worker CSP fix**: `worker-src 'self' blob:` is now always present in the CSP (previously only with `CODEMAN_GESTURE=1`). The terminal's `_safeYield` anti-throttling tick worker is created from a Blob URL and was silently blocked on every install, logging a CSP violation on each page load and disabling the worker leg of the render-yield fallback chain.
+
+## 0.9.10
+
+### Patch Changes
+
+- Self-update now restarts automatically on headless Macs supervised by a system LaunchDaemon.
+
+  New `launchd-daemon` supervisor kind: when Codeman runs under a bootstrapped, KeepAlive system-level LaunchDaemon (`/Library/LaunchDaemons/com.codeman.web.plist` — the right setup for headless Macs, where LaunchAgents never start because there is no GUI login), the updater no longer ends with "Update staged — restart Codeman to apply". It restarts rootlessly: the update script kills the server PID (passed via `--server-pid`) and launchd respawns it on the freshly built `dist/`. Detection is conservative — the daemon must be bootstrapped in the system domain AND have `KeepAlive` enabled.
+
+  Also fixed: a lingering "restart Codeman to apply" status. After a manual restart of a staged update, boot reconciliation now flips `completed-needs-manual-restart` to `completed` once the running version matches the staged target, so the Updates tab stops showing the stale instruction.
+
+## 0.9.9
+
+### Patch Changes
+
+- Codex (OpenAI CLI) run mode, Claude Model picker, and response-viewer button now opt-in.
+
+  **Codex (OpenAI CLI) run mode** (#114): new `codex` session mode alongside Claude Code and OpenCode. Sessions launch the Codex CLI via tmux with secrets injected through `tmux setenv` (`OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` — never on the command line). Supports `--model`, `resume <id>`, and `--dangerously-bypass-approvals-and-sandbox` via the `codexConfig` payload or the new App Settings → Codex CLI tab (`codexDangerouslyBypassApprovals`). Availability surfaced at `GET /api/codex/status` with an install hint when the binary is missing. Frontend gets a "Run CX" run-mode option; Respawn/Ralph options stay Claude-only (session options open on the Summary tab for external-CLI sessions). `CODEX_*` env prefix added to the env-override allowlist.
+
+  **Claude Model picker**: App Settings → Claude CLI gains a "Claude Model" select (`claudeModel` setting) that pins the model for new Claude sessions via the case's `.claude/settings.local.json` — e.g. Fable 5 (1M context), Fable 5, Opus (1M), Opus, Sonnet, Haiku. It takes precedence over the legacy 1M Opus Context toggle. Fable 5 also added to the orchestrator default/phase model dropdowns.
+
+  **Response-viewer (eye) header button is now hidden by default** — existing users who relied on it can re-enable it under App Settings → Display → Response Viewer (`showResponseViewer`, per-device setting). A new Display toggle controls its visibility.
+
+  Also: tests made immune to a set `CODEMAN_GESTURE` env var; CLAUDE.md documents the Codex run mode and the eye-button toggle.
+
+## 0.9.8
+
+### Patch Changes
+
+- Stable HTTP contract, terminal pane-buffer rework, mobile/touch fixes, and fresh-install default cleanups.
+
+  **API / v1 readiness (PR #113)**
+  - Stable HTTP contract: uniform `{success, data}` / `{success: false, error, errorCode}` response envelope across all ~134 handlers, correct HTTP status codes, and a versioned `/api/v1/*` alias of `/api/*`
+  - Post-merge adversarial audit closed 9 contract gaps (envelope/status-code stragglers), incl. `loadQuickStartCases` double-unwrap
+  - Node.js floor raised to >=22; `codeman` bin alias installed alongside `aicodeman`
+  - Security hardening: SSRF guard on the push endpoint, tmux session-name validation, documented tail-file roots
+  - Governance: SECURITY.md and a SemVer versioning policy (docs/versioning-policy.md)
+  - CI now runs the full unit/integration suite (vitest.ci.config.ts) plus a frontend JS syntax gate
+
+  **Terminal (PR #112)**
+  - tmux pane-buffer primitives and session/render reliability fixes for the terminal pipeline, with re-review findings addressed
+
+  **Mobile / touch (PR #111)**
+  - Terminal and layout fixes for touch devices: desktop focus handling, WS resize-claim wiring, CJK setting, ESC passthrough
+  - New: Esc button in the simple (default) keyboard accessory bar, next to paste — sends a real ESC to the session
+
+  **Defaults & UI**
+  - Monitor panel is now disabled by default on fresh installs (desktop previously slid it open at startup; mobile was already off). Opt in via App Settings -> Show Monitor
+  - Fixed the session-tab task badge silently failing to open the Monitor panel when it was hidden by the setting (long-broken on mobile)
+  - Local echo defaults audited and confirmed per-device: off on desktop, on for touch devices, never server-synced
+
 ## 0.9.7

 ### Patch Changes
@@ -34,7 +34,7 @@ The production server caches static files for 1 year, `immutable` (`maxAge: '1y'

 ## COM Shorthand (Deployment)

-Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`.
+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`.

 When user says "COM":
 1. **Determine bump type**: `COM` = patch (default), `COM minor` = minor, `COM major` = major
@@ -56,17 +56,17 @@ When user says "COM":

 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.

-**Version**: 0.9.7 (must match `package.json`)
+**Version**: 1.0.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 both Claude Code and OpenCode AI CLIs via pluggable CLI resolvers.
+**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'`).

 **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.

-**Requirements**: Node.js 18+, Claude CLI, tmux
+**Requirements**: Node.js 22+, Claude CLI, tmux

 **Git**: Main branch is `master`. SSH session chooser: `sc` (interactive), `sc 2` (quick attach), `sc -l` (list).

@@ -85,10 +85,12 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | 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` |

-**CI**: `.github/workflows/ci.yml` runs `check:lockfile`, `typecheck`, `lint`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s) on push to master/main and on PRs (Node 22). The unit test suite is excluded (it spawns tmux).
+**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/**`.

@@ -96,13 +98,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 - **Single-line prompts only** — `writeViaMux()` sends text+Enter separately; multi-line breaks Ink
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
- **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly
+- **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_*` 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_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift
 - **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
- **Dual-CLI prefix discipline** — Codeman supports both Claude Code and OpenCode (`claude-cli-resolver.ts` / `opencode-cli-resolver.ts`); env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*`) and the allowlist in `schemas.ts` enforces this. When adding settings, decide which CLI(s) it applies to and gate the env export accordingly — don't blindly forward both prefixes. See `docs/opencode-integration.md` for the OpenCode resolver design
+- **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 duplicated** — the local-echo overlay lives in BOTH `packages/xterm-zerolag-input/src/` (published to npm as a standalone library for external consumers — see README "Published Packages") AND inline inside `src/web/public/app.js` (runtime copy the web UI actually loads, since the page ships as plain JS without a bundler). Any change to overlay behavior MUST be applied to both, or dev and prod diverge — and a public API break in the package warrants a separate version bump for `xterm-zerolag-input` in the changeset. Always test on mobile after touching it. See `docs/local-echo-overlay-plan.md`.
+- **`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', …)`.

@@ -115,7 +118,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | 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` | |
+| **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` | |
 | **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 |
@@ -125,18 +128,18 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **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` | |
-| **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
-| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (15 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts`, `src/web/self-update.ts` | |
-| **Frontend** | `src/web/public/app.js` (~3.4K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | |
+| **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` (15 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` | |
+| **Frontend** | `src/web/public/app.js` (~3.7K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`, `image-input.js`) + `sw.js` | |
 | **Types** | `src/types/index.ts` (barrel) → 15 domain files; also `src/types.ts` root re-export | See `@fileoverview` in index.ts |

-★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
+★ = 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; copy embedded in `app.js`. `packages/gesture-control/` (`codeman-gesture-control`) — hand-tracking overlay source; built to `src/web/public/gesture/gesture-codeman.js` via `npm run build:gesture` (see Frontend → Gesture control).
+**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).

-**Config**: `src/config/` — 10 files. Import from specific files, not barrel.
+**Config**: `src/config/` — 10 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` (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`, `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).

 ### Data Flow

@@ -151,26 +154,32 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.

+**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`.
+
 **Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.

-**Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`.
+**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).
+
+**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`.

-**Self-update** (App Settings → Updates): in-app updater for **git-clone installs** supervised by systemd/launchd. The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` (`git checkout <release tag> && npm install && npm run build && restart`) that outlives the restart; it writes progress to `dataPath('update-status.json')`, which the browser polls across the connection drop. Channel = latest `codeman@X.Y.Z` release tag; dirty trees are auto-stashed. `src/web/self-update.ts` splits PURE helpers (semver/tag parsing, reconcile decision — unit-tested) from IO wrappers (`getInstallInfo`/`checkForUpdate`/`startUpdate`/`reconcileUpdateOnBoot`). Routes: `GET /api/system/update/check`, `POST /api/system/update`, `GET /api/system/update/status`. Types: `src/types/update.ts`. npm installs report as non-updatable.
+**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.

 **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) → `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) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15). `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) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `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) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `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).

-**Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).
+**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).

 **Multi-monitor button** (header, top-right; the notification bell it sits beside stays hidden — notifications live in Settings → Notifications). `app.launchMultiMonitor()` (in `panels-ui.js`) POSTs `/api/system/span-displays`, which spawns `scripts/span-codeman.sh` — a fresh, maximized browser `--app` window sized to the union of all displays (macOS; needs "Displays have separate Spaces" OFF). Supports the gesture layer's in-page floating session panels dragging across the physical monitor seam. **Opt-in:** hidden by default; enable under App Settings → Display → **Header Displays** ("Multi-monitor Button", `showMultiMonitorButton`). The button carries a `btn-multimonitor--hidden` class in the template; `renderIndexHtml` strips that class at render when the setting is on (a unique class token, not a brittle match on the aria-label/style copy), and `applyHeaderVisibilitySettings()` toggles the same class live on save. Solo (detached) windows hide it via `body.solo-mode`.

+**Response-viewer (eye) button** (header) is likewise **hidden by default** — enable under App Settings → Display → **Response Viewer** (`showResponseViewer`). 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.
+
 **Gesture control** (the camera hand-tracking overlay) is **opt-in, default OFF**, under App Settings → Display → **Input** (`gestureControlEnabled`). `CODEMAN_GESTURE=1` makes the feature *available* on the instance (CSP widening + `/gesture/` assets) and sets `window.__codemanGestureAvailable` (the Input section only shows when set); the overlay bundle is injected by `renderIndexHtml` **only when the setting is enabled**, so that method is `async` and reads `settings.json` via `readSettings(true)` — the `true` forces a **fresh** read (bypassing the 2s `_settingsCache`), because a post-save reload happens within that TTL and the cached value would otherwise render the pre-toggle state. Toggling the setting reloads the page (the bundle is render-injected).

 **Gesture-control source lives in-repo** at `packages/gesture-control/` (workspace package `codeman-gesture-control`, was the standalone `Ark0N/codeman-gesture-control` repo). The transport-agnostic core is `src/gesture/*` (MediaPipe GestureRecognizer → One-Euro-filtered cursor → pinch state machine); `src/codeman/entry.ts` is the Codeman *consumer* that maps grab/drag/drop onto real `.session-tab`/toolbar buttons and is the bundle entry. **Edit there, then run `npm run build:gesture`** (`scripts/build-gesture-bundle.mjs` → esbuild bundles `entry.ts`, MediaPipe JS included, into `src/web/public/gesture/gesture-codeman.js`) and **commit the regenerated bundle** — the committed bundle is what dev/`tsx` serves (no bundler at runtime), and `scripts/build.mjs` reruns the same step so prod always reflects current source. The MediaPipe **wasm + model** are NOT bundled — loaded at runtime from same-origin `/gesture/wasm` + `/gesture/gesture_recognizer.task`, fetched by `scripts/fetch-gesture-assets.mjs` (gitignored, see Gotchas). `entry.ts` mounts `window.__codemanGesture = new GestureBridge()` idempotently at module-eval. A standalone vite playground (`npm run dev` in the package — fake tabs, no Codeman) lets you iterate on gesture *feel* in isolation. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision` in `packages/gesture-control/package.json`.
@@ -192,9 +201,9 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 | **QR Auth** | Single-use 6-char tokens (60s TTL) for tunnel login. See `docs/qr-auth-plan.md` |
 | **Sessions** | 24h cookie (`codeman_session`), auto-extend, device context audit |
 | **Rate limit** | 10 failed auth/IP → 429 (15min decay). QR has separate limiter |
-| **Hook bypass** | `/api/hook-event` exempt from auth (localhost-only, schema-validated) |
+| **Hook bypass** | `/api/hook-event` 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 also **refuses** without `CODEMAN_PASSWORD` unless `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` (COD-55) |
 | **Env vars** | `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies, comma-separated; bare `.suffix` matches subdomains) |
-| **Validation** | Zod schemas, path allowlist regex, `CLAUDE_CODE_*` env prefix allowlist |
+| **Validation** | Zod schemas, path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`) |
 | **Headers** | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS |

 ### SSE Event Registry
@@ -203,11 +212,13 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 ### API Routes

-~134 handlers across 15 route files in `src/web/routes/`: system (40, incl. self-update `check`/`status`/`POST /api/system/update` + `POST /api/system/span-displays` → spawns `scripts/span-codeman.sh`), sessions (28), orchestrator (10), cases (9), ralph (9), plan (8), respawn (7), files (6), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~136 handlers across 15 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), respawn (7), files (6), mux (5), push (4), scheduled (4), teams (2), hooks (1), clipboard (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+
+**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`).

 ## Adding Features

- **API endpoint**: Types in `src/types/` domain file, route in `src/web/routes/*-routes.ts`, use `createErrorResponse()`. Validate with Zod schemas in `schemas.ts`.
+- **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()`
 - **Hook event**: Add to `HookEventType`, add hook in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema`
@@ -220,25 +231,28 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

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

+**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.
+
 ## Testing

-**CRITICAL: You are running inside a Codeman-managed tmux session.** Never run `npx vitest run` (full suite) — it spawns/kills tmux sessions and will crash your own session. Only run individual files:
+**Never run the bare full suite** (`npm test` with no file argument): the default config includes the browser-driven suites (`test/mobile/**` and 3 other Playwright tests), which need a live server + chromium + environment-specific PNG baselines and will fail/hang locally. Run individual files, or `test:ci` for a broad sweep:

 ```bash
 npm test -- test/<specific-file>.test.ts         # Single file (SAFE, uses config/vitest.config.ts)
 npm test -- -t "pattern"                          # By name (SAFE)
-# npm test                                        # DANGEROUS — runs full suite, DON'T DO THIS
+npm run test:ci                                   # Everything except browser/perf suites — what CI runs
+# npm test                                        # DON'T — includes browser/visual suites
 ```

 Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pass `--config config/vitest.config.ts`.

-**Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s.
+**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.

-**Safety**: `test/setup.ts` snapshots pre-existing tmux sessions and never kills them. Only `registerTestTmuxSession()` sessions get cleaned up.
+**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.

 **Ports**: Pick unique ports manually. Search `const PORT =` before adding new tests.

-**Respawn tests**: Use `MockSession` from `test/respawn-test-utils.ts`. **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (135 device profiles).
+**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`.

 ## Debugging

@@ -1,6 +1,6 @@
 MIT License

-Copyright (c) 2024 Claudeman Contributors
+Copyright (c) 2024-2026 Codeman Contributors

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -2,24 +2,24 @@
  <img src="docs/images/codeman-title.svg" alt="Codeman" height="60">
 </p>

-<h2 align="center">The missing control plane for AI coding agents</h2>
+<h2 align="center">Mission control for AI coding agents</h2>

 <p align="center">
-  <em>Agent Visualization &bull; Zero-Lag Input &bull; Autonomous Orchestrator &bull; Respawn Controller &bull; Mobile-First UI &bull; Hardened Security</em>
-</p>
-
-<p align="center">
-  <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>

 <p align="center">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
+  <a href="https://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">
 </p>

+<p align="center">
+  <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
+</p>
+
 <p align="center">
  <img src="docs/images/subagent-demo.gif" alt="Codeman — parallel subagent visualization" width="900">
 </p>
@@ -34,7 +34,7 @@ curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | b

 This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it.

-You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai) (or both). After install:
+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:

 ```bash
 codeman web
@@ -103,7 +103,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | 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) or [OpenCode](https://opencode.ai)). 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), or [Codex](https://developers.openai.com/codex/cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
 </details>

 ---
@@ -214,6 +214,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
 - **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)
@@ -293,7 +294,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 ## More Features

 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
- **Dual-CLI** — run **Claude Code** or **OpenCode** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **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)
 - **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
@@ -427,7 +428,7 @@ 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).
+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.

 ### Network & access

@@ -447,7 +448,7 @@ These run for **every** request — before auth, even on the default no-password

 ### Input, files & headers

- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` env-prefix allowlist gates which settings each CLI can receive
+- **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
 - **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`

@@ -579,7 +580,7 @@ flowchart TB
        end

        subgraph External["External"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex</small>"]
            BG["Background Agents<br/><small>(Task tool)</small>"]
        end
    end
@@ -651,6 +652,14 @@ npm install xterm-zerolag-input

 ---

+## Versioning
+
+Codeman follows [SemVer](https://semver.org/). What the version number actually
+commits to — and what counts as internal (the HTTP/SSE API, on-disk state,
+experimental features) — is spelled out in
+[`docs/versioning-policy.md`](docs/versioning-policy.md). If you script against
+the HTTP API, pin to an exact version.
+
 ## License

 MIT — see [LICENSE](LICENSE)
@@ -2,10 +2,10 @@
  <img src="docs/images/codeman-title.svg" alt="Codeman" height="60">
 </p>

-<h2 align="center">为 AI 编程智能体而生的「控制平面」</h2>
+<h2 align="center">AI 编程智能体的任务控制中心</h2>

 <p align="center">
-  <em>智能体可视化 &bull; 零延迟输入 &bull; 自主编排器 &bull; 重生控制器 &bull; 移动优先 UI &bull; 安全加固</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex —— 统一仪表盘 &bull; 任意设备</em>
 </p>

 <p align="center">
@@ -36,7 +36,7 @@ curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | b

 该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。

-你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenCode](https://opencode.ai)（两个都装也可以）。安装完成后：
+你至少需要安装一个 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
@@ -105,7 +105,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"
 ```

-Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenCode](https://opencode.ai)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+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`。
 </details>

 ---
@@ -216,6 +216,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 卡住时防止重生抖动（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）
@@ -295,7 +296,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 ## 更多特性

 - **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
- **双 CLI** —— 每个会话可选 **Claude Code** 或 **OpenCode**；环境变量前缀自动隔离（`CLAUDE_CODE_*` 与 `OPENCODE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode** 或 **Codex**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*` 与 `CODEX_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
 - **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
 - **语音输入** —— 用 Deepgram Nova-3 口述提示（带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
 - **图像输入** —— 直接把图片粘贴或拖放进会话
@@ -449,7 +450,7 @@ Codeman 用 `--dangerously-skip-permissions` 启动会话，因此 Web UI 在设

 ### 输入、文件与响应头

- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` 环境变量前缀允许列表把控每个 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

@@ -581,7 +582,7 @@ flowchart TB
        end

        subgraph External["外部"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex</small>"]
            BG["后台智能体<br/><small>(Task 工具)</small>"]
        end
    end
@@ -0,0 +1,78 @@
+# Security Policy
+
+Codeman launches AI coding sessions with `--dangerously-skip-permissions`, so the
+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).
+
+## Supported versions
+
+Security fixes land on the latest published `codeman@X.Y.Z` release and `master`.
+Older versions are not patched — upgrade to the latest release (App Settings →
+Updates for git-clone installs, or `npm i -g aicodeman@latest`).
+
+| Version | Supported |
+| ------- | --------- |
+| latest `0.9.x` / `master` | ✅ |
+| anything older | ❌ (upgrade) |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security problems.**
+
+Report privately via **GitHub's private vulnerability reporting**:
+the repository's **Security** tab → **Report a vulnerability**
+(<https://github.com/Ark0N/Codeman/security/advisories/new>). This opens a private
+advisory thread with the maintainer.
+
+> Maintainer note: enable *Settings → Code security and analysis → Private
+> vulnerability reporting* so this channel is live.
+
+When reporting, please include: affected version/commit, the deployment shape
+(loopback-only, `CODEMAN_PASSWORD` set, tunnel/`tailscale serve`, custom
+reverse proxy), reproduction steps, and impact. We aim to acknowledge within a
+few days. Coordinated disclosure is appreciated — we'll agree a disclosure
+timeline with you once impact is confirmed.
+
+### In scope
+- Authentication / session-cookie bypass when `CODEMAN_PASSWORD` is set
+- DNS-rebinding, CSRF/CSWSH, or Origin/Host-guard bypass reaching state-changing routes
+- Remote code execution reachable **without** local OS access (e.g. via a browser, a tunnel, or a foreign origin)
+- Path traversal / arbitrary file read or write through the HTTP API
+- Supply-chain integrity of the in-app self-updater
+
+### Out of scope (by design — see Known limitations)
+- Anything requiring an already-trusted **same-machine, same-uid** process. Codeman trusts the local OS user it runs as; a peer process of that user is already inside the boundary.
+- Running an authless instance bound to a non-loopback host after dismissing the startup warning (you explicitly acknowledged it).
+- The default loopback + no-password posture itself (it is reachable only from the same machine).
+
+## Trust model (summary)
+
+- **Loopback by default.** Binds `127.0.0.1`; 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 concrete fixes.
+- **Always-on Host + Origin guards.** Block DNS-rebinding and cross-site state-changing requests even on the no-auth loopback install (a missing Origin is allowed so CLI/hooks work).
+- **Optional auth.** HTTP Basic via `CODEMAN_USERNAME`/`CODEMAN_PASSWORD`; success issues an opaque server-side 256-bit cookie. Per-IP rate limiting on failures.
+- **Hardened file serving, tmux launch, transport headers, and multi-instance isolation** — see the full architecture doc.
+
+## Known limitations and accepted risk
+
+A 1.0 release is an implicit statement that the documented model *is* the model, so
+these residuals are stated explicitly. Most sit **inside the same-uid OS trust
+boundary** or behind the always-on Origin guard; they matter mainly for
+shared-host, multi-user, or tunneled deployments.
+
+- **Self-update trusts an unsigned release tag.** The in-app updater does `git checkout <tag> && npm install` (lifecycle scripts run) of a tag matched only by name shape, from whatever `origin` points to — no signature/commit verification. Treat the updater as trusting your `origin` remote and your release pipeline. (Hardening tracked for 1.0.)
+- **CSP ships `'unsafe-inline'`.** Inline handlers mean the Content-Security-Policy is defense-in-depth only; all AI-/file-derived sinks are escaped, but a future missed escape would be executable.
+- **`workingDir` is unconstrained.** A session may be created with any absolute working directory (e.g. `/`), which becomes the file-route boundary for that session. Scope it to trusted paths on shared hosts.
+- **Hook-event auth exemption is loopback-IP-based.** `POST /api/hook-event` is exempt from auth for loopback callers; because tunnels (cloudflared / `tailscale serve`) terminate at `127.0.0.1`, a loopback-terminating tunnel inherits the exemption. Set `CODEMAN_PASSWORD` and prefer a tunnel that preserves the client identity if this matters.
+- **Session cookie is not bound to client IP/UA on reuse, and refreshes without an absolute cap.** A stolen cookie replays until its idle TTL elapses.
+- **Multi-instance tmux socket is process-wide.** Two Codeman instances on the same `CODEMAN_INSTANCE` share a tmux socket and can attach each other's live sessions — isolate with distinct `CODEMAN_INSTANCE` values.
+- **The live log-tail route reads `/var/log` and `~/logs`** in addition to the session working directory (read-only) — a deliberate choice for tailing system/app logs. On a password-protected remote deployment an authenticated user can therefore read those roots outside their session. See `docs/security-architecture.md` §5.
+
+Recent hardening (this release): web-push subscription endpoints are restricted
+to https public hosts (SSRF guard — rejects internal/metadata IPs, validated at
+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).
@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { defineConfig, configDefaults } from 'vitest/config';
+
+const root = resolve(import.meta.dirname, '..');
+
+/**
+ * CI test config — same as vitest.config.ts but EXCLUDES the browser-driven
+ * mobile suite (test/mobile/**). Those are Playwright visual-regression tests
+ * that need a live server + chromium + environment-specific PNG baselines, so
+ * they are run/maintained separately and are not part of the CI gate.
+ *
+ * Keep the rest in sync with config/vitest.config.ts.
+ */
+export default defineConfig({
+  test: {
+    root,
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    exclude: [
+      ...configDefaults.exclude,
+      'test/mobile/**', // browser/visual (Playwright + chromium)
+      'test/perf-*.test.ts', // timing-sensitive perf benchmarks (flaky in CI)
+      'test/inline-rename.test.ts', // browser (Playwright)
+      'test/opencode-resize.test.ts', // browser (Playwright)
+      'test/webgl-fallback.test.ts', // browser (Playwright)
+    ],
+    setupFiles: ['./test/setup.ts'],
+    fileParallelism: false,
+    testTimeout: 30000,
+    teardownTimeout: 60000,
+  },
+});
@@ -0,0 +1,90 @@
+# HTTP API Reference
+
+Codeman's HTTP API is a **stable contract** as of 1.0 — see
+[`versioning-policy.md`](versioning-policy.md) for the SemVer guarantee. This page
+defines the response envelope, status codes, error codes, versioning, and the SSE
+event channel.
+
+## Versioning
+
+- The stable, public surface is served under **`/api/v1/...`**. Pin external
+  clients to this prefix.
+- The unversioned **`/api/...`** paths are a permanent alias of the current
+  version (what the bundled web UI uses). They are kept working, but new external
+  integrations should use `/api/v1`.
+- Breaking changes to the contract ship under a new prefix (`/api/v2`); `/api/v1`
+  keeps its semantics. Additive changes (new endpoints, new optional fields, new
+  error codes) are non-breaking and may appear in a minor release.
+- The implementation rewrites `/api/v1/*` → `/api/*` at the server level
+  (`rewriteApiV1Url` in `src/web/server.ts`).
+
+## Response envelope
+
+Every JSON response uses one uniform envelope, applied centrally by a
+`preSerialization` hook (`src/web/server.ts`) — handlers return bare data and the
+hook wraps it:
+
+**Success** — HTTP `2xx`:
+
+```json
+{ "success": true, "data": <payload> }
+```
+
+`data` is the endpoint's payload (object, array, or value). Endpoints with no
+payload return `{ "success": true, "data": {} }`.
+
+**Error** — HTTP `4xx`/`5xx`:
+
+```json
+{ "success": false, "error": "human-readable message", "errorCode": "NOT_FOUND" }
+```
+
+`ApiResponse<T>` in `src/types/api.ts` is the canonical type.
+
+> Non-JSON endpoints are exempt from the envelope: `GET /api/sessions/:id/file-raw`,
+> `GET /api/sessions/:id/tail-file` (SSE), `GET /api/download`,
+> `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect), and the
+> `GET /ws/sessions/:id/terminal` WebSocket upgrade.
+
+## Error codes → HTTP status
+
+The single source of truth is `ErrorStatus` / `httpStatusForErrorCode()` in
+`src/types/api.ts`. Clients should branch on `errorCode` (stable) and may rely on
+the HTTP status.
+
+| `errorCode` | HTTP | Meaning |
+|-------------|------|---------|
+| `INVALID_INPUT` | 400 | Malformed request / failed validation |
+| `UNAUTHORIZED` | 401 | Authentication required or failed |
+| `NOT_FOUND` | 404 | Resource does not exist |
+| `SESSION_BUSY` | 409 | Session is busy |
+| `CONFLICT` | 409 | Conflicts with current state (e.g. already running) |
+| `ALREADY_EXISTS` | 409 | Resource already exists |
+| `OPERATION_FAILED` | 422 | Well-formed but could not be completed |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Unexpected server error |
+
+Adding a new error code is non-breaking; removing or renaming one is a major change.
+
+## Authentication
+
+Optional HTTP Basic (`CODEMAN_USERNAME`/`CODEMAN_PASSWORD`) → opaque
+`codeman_session` cookie. When enabled, unauthenticated requests get
+`401 UNAUTHORIZED`; rate-limited requests get `429 RATE_LIMITED`. See
+[`security-architecture.md`](security-architecture.md).
+
+## SSE event channel
+
+`GET /api/events` is a Server-Sent Events stream (`text/event-stream`); each
+message is `event: <name>` + `data: <json>`. The event-name registry
+(`src/web/sse-events.ts`, mirrored in `src/web/public/constants.js`) is part of
+the stable contract — event names are not renamed without a major bump. An
+optional `?sessions=<id,...>` filter suppresses only the high-volume terminal
+stream; lifecycle/metadata events are delivered to all clients regardless.
+
+## Consuming from JavaScript
+
+The bundled frontend reads responses through `_apiJson()`
+(`src/web/public/api-client.js`), which unwraps `{success:true,data}` → `data` and
+returns `null` on a non-2xx / `{success:false}` response. External clients should
+do the same: check the HTTP status (or `body.success`), then read `body.data`.
@@ -124,7 +124,11 @@ loopback bind matters. The auth pipeline (`src/web/middleware/auth.ts`,
 `onRequest` hook) runs in this order:

 1. **Localhost‑only exemptions** (always first): `POST /api/hook-event` and the QR
-   `/q/` short‑code path are exempt when `req.ip` is loopback (see §3).
+   `/q/` short‑code path are exempt when `req.ip` is loopback (see §3). While the
+   **managed tunnel is running**, the hook‑event exemption additionally requires
+   the per‑instance `X-Codeman-Hook-Secret` header (COD‑54); failed presentations
+   are rate‑limited in a **dedicated bucket** (separate from Basic‑Auth failures)
+   so misfiring hooks can never lock out the login path.
 2. **Session cookie** check — a valid `codeman_session` cookie short‑circuits to
   allow.
 3. **HTTP Basic** check — correct credentials short‑circuit to allow and clear
@@ -165,17 +169,29 @@ protection is unchanged.
 with `req.ip = 127.0.0.1`**. The localhost‑only exemptions then treat those
 requests as local:

- `POST /api/hook-event` — auth‑exempt for loopback. Bounded impact: it is
+- `POST /api/hook-event` — auth‑exempt for loopback **only while no managed tunnel
+  is running**. When Codeman's own tunnel is up, the exemption requires the
+  per‑instance shared secret (`X-Codeman-Hook-Secret`, 256‑bit hex in
+  `~/.codeman/hook-secret`, mode 0600, COD‑54). Local hook commands read the
+  secret file at execution time (`$CODEMAN_HOOK_SECRET_FILE`, exported into every
+  managed session), so they keep working — tunneled internet traffic can't know
+  it. Even without the secret the impact is bounded: the route is
  `HookEventSchema`‑validated and requires a valid in‑memory `sessionId`; it can
  drive respawn signals, SSE broadcasts, push notifications, and transcript
-  watching — **not** arbitrary terminal input or file reads. It is a
-  session‑disruption / notification‑spoofing surface, not RCE.
+  watching — **not** arbitrary terminal input or file reads. ⚠️ The gate keys off
+  the **managed** tunnel — an externally run loopback proxy (your own
+  `cloudflared`, `tailscale serve`) is invisible to it, so the plain loopback
+  exemption still applies there (prefer `tailscale serve`, which authenticates at
+  the tailnet layer). Hook configs regenerated since COD‑54 always present the
+  header, so a future release can require the secret unconditionally.
 - QR `/q/` — still protected by its own short‑code brute‑force limiter
  (10 failures / 60s against a 62⁶ space).

 **Mitigation:** set `CODEMAN_PASSWORD` whenever a loopback‑connecting tunnel is
-up (it does not gate the hook‑event exemption, but it gates everything else and
-is the documented practice). Prefer `tailscale serve` (below), which authenticates
+up — it gates everything except the (secret‑gated) hook exemption and is the
+documented practice; since COD‑55 enabling the managed tunnel **refuses** to start
+without it unless `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` explicitly
+acknowledges the exposure. Prefer `tailscale serve` (below), which authenticates
 at the tailnet layer so untrusted clients never reach the loopback port at all.

 ### Host‑header & Origin allowlist (DNS‑rebinding & CSRF defense)
@@ -304,7 +320,51 @@ injected from API JSON (`innerHTML`), not via `file-raw`, so they are unaffected
 `/api/download` additionally refuses a blocklist of sensitive paths
 (`/etc/shadow`, `~/.ssh/`, `.env`, `*credentials*`, `.aws/credentials`, …). This
 is **defense‑in‑depth, not the primary boundary** — the realpath containment is
-the control.
+the control. The blocklist patterns are shared (`src/web/sensitive-path.ts`) with
+the attachment guard below.
+
+### External attachments (registry) & the magic‑link trust boundary
+
+Live external attachments (`src/attachment-registry.ts`) mint an `att_<uuid>` id
+for a host file so browser requests carry the id, never an absolute path. Serving
+is by id (`GET /api/sessions/:id/attachments/:attachmentId/raw`, 50 MB cap,
+`nosniff`) and re‑resolves the symlink + re‑checks the **attachment guard**
+(`src/config/attachment-guard.ts`: the shared sensitive‑path blocklist **plus**
+the `/root` and `/etc` trees, extendable via `attachmentBlockedPaths` /
+`CODEMAN_ATTACHMENT_BLOCKED_PATHS`) on every request. Unlike the workspace file
+routes, attachments are intentionally **cross‑workspace** — so the effective gate
+is the blocklist + a 6‑extension allowlist (`png/pdf/docx/pptx/md/txt`), not
+realpath containment.
+
+Two registration paths, with **different trust**:
+
+- **Explicit `POST /api/sessions/:id/attachments`** (and `codeman attach`, which
+  POSTs directly inside a managed session) — a deliberate, Origin‑guarded HTTP
+  request. Allowed cross‑workspace (subject to the guard). This is the supported
+  path for codeman‑publish and the `~/.codeman` review‑card loop.
+- **Terminal `codeman://attach?path=…` magic links** — scanned passively from
+  session output. Terminal output is **attacker‑influenceable** (a prompt‑injected
+  session can print an arbitrary path), and registration here is server‑side with
+  no Origin gate and broadcasts the `rawUrl` over SSE to all clients. This path is
+  therefore **force‑confined to the session workspace** (`forceWorkspaceConfinement`
+  in `registerExternalAttachment`, wired in `WebServer.registerAttachment`),
+  regardless of the global confine setting — a passive magic link cannot expose a
+  file outside the session's own workspace. Cross‑workspace attach must go through
+  the explicit POST path above.
+
+### SSE log‑tail route — intentional extra read roots
+
+The live file‑tail SSE route (`FileStreamManager`, used to stream a growing log
+into the UI) does **not** use `validateSessionFilePath`; it has its own validator
+with a deliberately **wider** allowlist: the session `workingDir` **plus two
+read‑only log roots — `/var/log` and `~/logs`** — so operators can tail
+system/app logs. `/tmp` is intentionally excluded (world‑writable). Like the
+other routes it `realpath`s the target and re‑checks right before spawning `tail`
+(TOCTOU guard), and it is read‑only. This is the one place the per‑session
+boundary is intentionally relaxed; on a password‑protected remote deployment an
+authenticated user can therefore read `/var/log` and `~/logs` outside their
+session dir. (Security review M5: this divergence is by design and is now
+documented here rather than silently diverging from the per‑session claim above.)

 ### Known limitation — `workingDir` scope

@@ -0,0 +1,79 @@
+# Versioning & Stability Policy
+
+Codeman follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`),
+managed via `@changesets/cli` (see the COM workflow in `CLAUDE.md`).
+
+This document defines **what the version number actually promises** — i.e. which
+surfaces are covered by SemVer and which are explicitly not. It exists because
+"1.0" is a commitment to stability, and an undocumented public surface invites
+incompatible client assumptions we would then be pressured to keep.
+
+> **Status:** finalized for the 1.0 cut. The HTTP/SSE API **is** part of the stable
+> surface — served under `/api/v1` with a uniform response envelope and
+> conventional HTTP status codes. See [`api-reference.md`](api-reference.md).
+
+## What SemVer covers (the public, stable surface)
+
+A **MAJOR** bump is required to break any of these after 1.0:
+
+1. **The CLI.** Command names, documented flags, and their behavior for
+   `codeman <command>` (published to npm as `aicodeman`; invoked as `codeman`).
+   This is the package's actual public entry point (`bin`).
+   - The package is published to npm as `aicodeman` and installs **both** the
+     `aicodeman` and `codeman` commands (`bin` aliases); `codeman` is the
+     canonical command used throughout the docs. Renaming either after 1.0 is a
+     breaking change.
+2. **The published `xterm-zerolag-input` library**, but on **its own version
+   line** — it is versioned and released independently of the Codeman app. Its
+   1.0 status is a separate decision; the Codeman app reaching 1.0 does *not*
+   imply `xterm-zerolag-input` is 1.0.
+3. **Documented environment variables** that configure deployment:
+   `CODEMAN_PASSWORD`, `CODEMAN_USERNAME`, `CODEMAN_HOST`, `CODEMAN_PORT`,
+   `CODEMAN_INSTANCE`, `CODEMAN_ALLOWED_HOSTS`, `CODEMAN_DATA_DIR`,
+   `CODEMAN_TMUX_SOCKET`, and the `--host` / `--port` / `--https` CLI flags.
+   Removing or changing the meaning of one of these is breaking.
+4. **The HTTP API and SSE event channel**, served under **`/api/v1`** with the
+   uniform `{success:true,data}` / `{success:false,error,errorCode}` envelope and
+   conventional HTTP status codes. Endpoint paths, the response envelope, error
+   `errorCode` values, and SSE event names are stable — see
+   [`api-reference.md`](api-reference.md). *Additive* changes (new endpoints, new
+   optional fields, new error codes, new SSE events) are non-breaking; breaking
+   changes ship under a new prefix (`/api/v2`). The unversioned `/api/...` alias
+   is kept working for the bundled UI.
+
+## What SemVer does NOT cover (internal surfaces — may change in any release)
+
+These may change in a **MINOR** (or even PATCH) release without a MAJOR bump:
+
+1. **The `~/.codeman/` state file formats** (`state.json`, `settings.json`,
+   `mux-sessions.json`, etc.). We make a **best-effort** to migrate existing data
+   forward (and have done so across renames), but the on-disk schema is not a
+   stable contract — do not write tooling that depends on its exact shape.
+2. **Internal TypeScript modules.** The npm package is CLI-only; `import`ing it
+   programmatically is not supported (there is no stable library entry point).
+3. **Experimental / opt-in features**, regardless of the app's version:
+   Gesture Control (beta), Agent Teams
+   (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), and anything labeled experimental
+   in the UI or docs. These may change or be removed at any time.
+
+## Deprecation policy
+
+When we need to change a covered surface:
+
+- Prefer **additive** changes (new flag/env var/command) over breaking ones.
+- A covered surface slated for removal is **deprecated first** — it keeps working
+  for at least one MINOR release with a runtime warning and a `CHANGELOG.md` note
+  pointing to the replacement — then removed in the next MAJOR.
+- Back-compat migration shims (e.g. the historical Claudeman→Codeman data/socket
+  migration) are kept until a MAJOR boundary, then may be dropped.
+
+## Pre-1.0 (`0.x`) caveat
+
+Until 1.0 ships, **any release may contain breaking changes** per SemVer's `0.x`
+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
+- `docs/security-architecture.md` — the full trust model
@@ -1,12 +1,12 @@
 {
  "name": "aicodeman",
-  "version": "0.9.7",
+  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "aicodeman",
-      "version": "0.9.7",
+      "version": "1.0.0",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -20,6 +20,7 @@
        "@fastify/static": "^9.1.3",
        "@fastify/websocket": "^11.2.0",
        "@xterm/addon-fit": "^0.11.0",
+        "@xterm/addon-serialize": "^0.14.0",
        "@xterm/addon-unicode11": "^0.9.0",
        "@xterm/addon-webgl": "^0.19.0",
        "@xterm/xterm": "^6.0.0",
@@ -34,7 +35,8 @@
        "zod": "^4.3.6"
      },
      "bin": {
-        "aicodeman": "dist/index.js"
+        "aicodeman": "dist/index.js",
+        "codeman": "dist/index.js"
      },
      "devDependencies": {
        "@changesets/cli": "^2.29.8",
@@ -64,7 +66,7 @@
        "vitest": "^4.1.8"
      },
      "engines": {
-        "node": ">=18.0.0"
+        "node": ">=22.0.0"
      },
      "optionalDependencies": {
        "@remotion/compositor-linux-x64-gnu": "^4.0.432",
@@ -4524,6 +4526,12 @@
      "integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==",
      "license": "MIT"
    },
+    "node_modules/@xterm/addon-serialize": {
+      "version": "0.14.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-serialize/-/addon-serialize-0.14.0.tgz",
+      "integrity": "sha512-uteyTU1EkrQa2Ux6P/uFl2fzmXI46jy5uoQMKEOM0fKTyiW7cSn0WrFenHm5vO5uEXX/GpwW/FgILvv3r0WbkA==",
+      "license": "MIT"
+    },
    "node_modules/@xterm/addon-unicode11": {
      "version": "0.9.0",
      "resolved": "https://registry.npmjs.org/@xterm/addon-unicode11/-/addon-unicode11-0.9.0.tgz",
@@ -1,12 +1,13 @@
 {
  "name": "aicodeman",
-  "version": "0.9.7",
-  "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
+  "version": "1.0.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",
  "types": "dist/index.d.ts",
  "bin": {
-    "aicodeman": "./dist/index.js"
+    "aicodeman": "./dist/index.js",
+    "codeman": "./dist/index.js"
  },
  "scripts": {
    "postinstall": "node scripts/postinstall.js",
@@ -19,6 +20,8 @@
    "test": "vitest run --config config/vitest.config.ts",
    "test:watch": "vitest --config config/vitest.config.ts",
    "test:coverage": "vitest run --config config/vitest.config.ts --coverage",
+    "test:ci": "vitest run --config config/vitest.ci.config.ts",
+    "check:frontend-syntax": "node scripts/check-frontend-syntax.mjs",
    "typecheck": "tsc --noEmit",
    "lint": "eslint --config config/eslint.config.js 'src/**/*.ts'",
    "lint:fix": "eslint --config config/eslint.config.js 'src/**/*.ts' --fix",
@@ -58,6 +61,7 @@
    "@fastify/static": "^9.1.3",
    "@fastify/websocket": "^11.2.0",
    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-serialize": "^0.14.0",
    "@xterm/addon-unicode11": "^0.9.0",
    "@xterm/addon-webgl": "^0.19.0",
    "@xterm/xterm": "^6.0.0",
@@ -117,7 +121,7 @@
    }
  },
  "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
  },
  "repository": {
    "type": "git",
@@ -39,7 +39,7 @@ Server echoes 'h' ←───────────────────

 ## Origin

-This library was extracted from [Codeman](https://github.com/Ark0N/Codeman), the missing control plane for AI coding agents — multi-session management, real-time agent visualization, autonomous respawn loops, and a mobile-first web UI for Claude Code and OpenCode. 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.
+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.

 ## Install

@@ -45,6 +45,7 @@ run('copy template', 'cp src/templates/case-template.md dist/templates/');
 run('xterm css', 'cp node_modules/@xterm/xterm/css/xterm.css dist/web/public/vendor/');
 run('xterm js', 'npx esbuild node_modules/@xterm/xterm/lib/xterm.js --minify --outfile=dist/web/public/vendor/xterm.min.js');
 run('xterm-addon-fit', 'npx esbuild node_modules/@xterm/addon-fit/lib/addon-fit.js --minify --outfile=dist/web/public/vendor/xterm-addon-fit.min.js');
+run('xterm-addon-serialize', 'npx esbuild node_modules/@xterm/addon-serialize/lib/addon-serialize.js --minify --outfile=dist/web/public/vendor/xterm-addon-serialize.min.js');
 run('xterm-addon-webgl', 'cp node_modules/@xterm/addon-webgl/lib/addon-webgl.js dist/web/public/vendor/xterm-addon-webgl.min.js');
 run('xterm-addon-unicode11', 'npx esbuild node_modules/@xterm/addon-unicode11/lib/addon-unicode11.js --minify --outfile=dist/web/public/vendor/xterm-addon-unicode11.min.js');
 run('xterm-zerolag-input', 'npx esbuild packages/xterm-zerolag-input/src/zerolag-input-addon.ts --bundle --minify --format=iife --global-name=XtermZerolagInput --outfile=dist/web/public/vendor/xterm-zerolag-input.js');
@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Frontend JS syntax check.
+ *
+ * CI's `npm run lint` only lints TypeScript under src/, and `tsc` excludes the
+ * frontend — so a plain SyntaxError in a shipped `src/web/public` script (loaded
+ * as a bare <script>, no bundler) passes CI green yet breaks the whole module at
+ * load.
+ * (This is exactly how PR #112's duplicate-`const` error in session-ui.js slipped
+ * through.) This runs `node --check` (parse-only; browser globals don't matter)
+ * on every shipped frontend script so that class of bug fails fast.
+ */
+import { readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PUBLIC_DIR = join(ROOT, 'src', 'web', 'public');
+
+const files = readdirSync(PUBLIC_DIR)
+  .filter((f) => f.endsWith('.js'))
+  .map((f) => join(PUBLIC_DIR, f));
+
+let failed = 0;
+for (const file of files) {
+  try {
+    execFileSync(process.execPath, ['--check', file], { stdio: 'pipe' });
+  } catch (err) {
+    failed++;
+    const msg = err.stderr ? err.stderr.toString() : String(err);
+    console.error(`✗ syntax error in ${file.replace(ROOT + '/', '')}:\n${msg}`);
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} frontend file(s) failed the syntax check.`);
+  process.exit(1);
+}
+console.log(`✓ ${files.length} frontend JS files parse cleanly`);
@@ -252,6 +252,7 @@ if (isGlobalInstall) {
        const require = createRequire(import.meta.url);
        const xtermDir = join(require.resolve('@xterm/xterm'), '..', '..');
        const fitDir = join(require.resolve('@xterm/addon-fit'), '..', '..');
+        const serializeDir = join(require.resolve('@xterm/addon-serialize'), '..', '..');
        const webglDir = join(require.resolve('@xterm/addon-webgl'), '..', '..');
        const unicode11Dir = join(require.resolve('@xterm/addon-unicode11'), '..', '..');
        const vendorDir = join(srcDir, 'web', 'public', 'vendor');
@@ -264,12 +265,14 @@ if (isGlobalInstall) {
        try {
            execSync(`npx esbuild "${join(xtermDir, 'lib', 'xterm.js')}" --minify --outfile="${join(vendorDir, 'xterm.min.js')}"`, { stdio: 'pipe' });
            execSync(`npx esbuild "${join(fitDir, 'lib', 'addon-fit.js')}" --minify --outfile="${join(vendorDir, 'xterm-addon-fit.min.js')}"`, { stdio: 'pipe' });
+            execSync(`npx esbuild "${join(serializeDir, 'lib', 'addon-serialize.js')}" --minify --outfile="${join(vendorDir, 'xterm-addon-serialize.min.js')}"`, { stdio: 'pipe' });
            execSync(`npx esbuild "${join(unicode11Dir, 'lib', 'addon-unicode11.js')}" --minify --outfile="${join(vendorDir, 'xterm-addon-unicode11.min.js')}"`, { stdio: 'pipe' });
            console.log(colors.green('✓ xterm vendor files copied to src/web/public/vendor/'));
        } catch {
            // Fallback: copy unminified
            copyFileSync(join(xtermDir, 'lib', 'xterm.js'), join(vendorDir, 'xterm.min.js'));
            copyFileSync(join(fitDir, 'lib', 'addon-fit.js'), join(vendorDir, 'xterm-addon-fit.min.js'));
+            copyFileSync(join(serializeDir, 'lib', 'addon-serialize.js'), join(vendorDir, 'xterm-addon-serialize.min.js'));
            copyFileSync(join(unicode11Dir, 'lib', 'addon-unicode11.js'), join(vendorDir, 'xterm-addon-unicode11.min.js'));
            console.log(colors.green('✓ xterm vendor files copied') + colors.dim(' (unminified — esbuild not available)'));
        }
@@ -31,6 +31,7 @@ export PUPPETEER_SKIP_DOWNLOAD="${PUPPETEER_SKIP_DOWNLOAD:-1}"
 REPO=""
 TAG=""
 SUPERVISOR="none"
+SERVER_PID=""
 STATUS_FILE=""
 UPDATE_ID=""
 FROM_VERSION=""
@@ -50,6 +51,7 @@ while [[ $# -gt 0 ]]; do
    --node) NODE="$2"; shift 2 ;;
    --log) LOG="$2"; shift 2 ;;
    --prev-sha) PREV_SHA="$2"; shift 2 ;;
+    --server-pid) SERVER_PID="$2"; shift 2 ;;
    --stash) DO_STASH=1; shift ;;
    *) shift ;;
  esac
@@ -198,6 +200,19 @@ case "$SUPERVISOR" in
        || fail "Build succeeded but launchd restart failed" "launchctl"
    }
    ;;
+  launchd-daemon)
+    # System-level KeepAlive LaunchDaemon (headless Mac): kickstarting the system
+    # domain needs root, but we don't need it — kill the server and launchd
+    # respawns it on the new dist/ within ThrottleInterval seconds.
+    if [[ -n "$SERVER_PID" ]] && kill "$SERVER_PID" 2>/dev/null; then
+      : # respawn is launchd's job from here
+    else
+      MANUAL_CMD="sudo launchctl kickstart -k system/com.codeman.web"
+      write_status "completed-needs-manual-restart" "Update staged — restart Codeman to apply v$TO_VERSION."
+      echo "[self-update] launchd-daemon: could not signal server pid '$SERVER_PID' — manual restart required"
+      exit 0
+    fi
+    ;;
  *)
    MANUAL_CMD="pkill -f 'codeman.*web'; codeman web &"
    write_status "completed-needs-manual-restart" "Update staged — restart Codeman to apply v$TO_VERSION."
@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Parses terminal magic links that request attachment cards.
+ */
+
+import { isAbsolute } from 'node:path';
+import { isSupportedAttachmentExtension } from './attachment-registry.js';
+
+const MAGIC_LINK_RE = /codeman:\/\/attach\?([^\s<>"']+)/g;
+
+export function parseAttachmentMagicLinks(data: string): string[] {
+  const results: string[] = [];
+  const seen = new Set<string>();
+
+  for (const match of data.matchAll(MAGIC_LINK_RE)) {
+    const query = trimTrailingPunctuation(match[1] || '');
+    try {
+      const params = new URLSearchParams(query);
+      const filePath = params.get('path');
+      if (!filePath || !isAbsolute(filePath)) continue;
+      const extension = filePath.split('.').pop()?.toLowerCase() || '';
+      if (!isSupportedAttachmentExtension(extension)) continue;
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      results.push(filePath);
+    } catch {
+      // Ignore malformed terminal text. Magic links are advisory.
+    }
+  }
+
+  return results;
+}
+
+function trimTrailingPunctuation(value: string): string {
+  return value.replace(/[),.;:]+$/g, '');
+}
@@ -0,0 +1,237 @@
+/**
+ * @fileoverview In-memory attachment registry for live external document references.
+ *
+ * Session-local files keep using the existing workspace-scoped file routes. This
+ * registry is only for explicit, live external attachments that need a stable ID
+ * so browser requests never contain arbitrary absolute paths.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { basename, extname, isAbsolute } from 'node:path';
+import { isBlockedAttachmentPath, loadAttachmentGuardConfig } from './config/attachment-guard.js';
+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']);
+
+export type AttachmentSource = 'detected' | 'external';
+
+export interface AttachmentRecord {
+  attachmentId: string;
+  sessionId: string;
+  filePath: string;
+  fileName: string;
+  extension: string;
+  attachmentType: AttachmentDetectedType;
+  size: number;
+  mtimeMs: number;
+  timestamp: number;
+  source: AttachmentSource;
+}
+
+export interface AttachmentRegistrationResult extends AttachmentDetectedEvent {
+  attachmentId: string;
+  source: AttachmentSource;
+  rawUrl: string;
+  previewUrl: string;
+  thumbnailUrl: string;
+}
+
+export class AttachmentRegistrationError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: number = 400
+  ) {
+    super(message);
+  }
+}
+
+/** Per-session attachment cap. Bounds memory against a client (or a
+ *  prompt-injected magic-link flood) registering unbounded distinct paths. */
+const MAX_ATTACHMENTS_PER_SESSION = 200;
+
+class AttachmentRegistry {
+  private recordsBySession = new Map<string, Map<string, AttachmentRecord>>();
+
+  register(record: AttachmentRecord): void {
+    let records = this.recordsBySession.get(record.sessionId);
+    if (!records) {
+      records = new Map();
+      this.recordsBySession.set(record.sessionId, records);
+    }
+    records.set(record.attachmentId, record);
+    // Evict oldest (insertion-order) entries beyond the cap.
+    while (records.size > MAX_ATTACHMENTS_PER_SESSION) {
+      const oldest = records.keys().next().value;
+      if (oldest === undefined) break;
+      records.delete(oldest);
+    }
+  }
+
+  get(sessionId: string, attachmentId: string): AttachmentRecord | undefined {
+    return this.recordsBySession.get(sessionId)?.get(attachmentId);
+  }
+
+  findByFilePath(sessionId: string, filePath: string): AttachmentRecord | undefined {
+    const records = this.recordsBySession.get(sessionId);
+    if (!records) return undefined;
+    for (const record of records.values()) {
+      if (record.filePath === filePath) return record;
+    }
+    return undefined;
+  }
+
+  clearSession(sessionId: string): void {
+    this.recordsBySession.delete(sessionId);
+  }
+}
+
+export const attachmentRegistry = new AttachmentRegistry();
+
+export function isSupportedAttachmentExtension(extension: string): boolean {
+  return SUPPORTED_ATTACHMENT_EXTENSIONS.has(extension.toLowerCase().replace(/^\./, ''));
+}
+
+export function getAttachmentType(extension: string): AttachmentDetectedType {
+  const normalized = extension.toLowerCase().replace(/^\./, '');
+  if (normalized === 'png') return 'image';
+  if (normalized === 'pdf') return 'pdf';
+  if (normalized === 'pptx') return 'presentation';
+  if (normalized === 'md') return 'markdown';
+  if (normalized === 'txt') return 'text';
+  return 'document';
+}
+
+export function buildAttachmentRoutes(
+  sessionId: string,
+  attachmentId: string
+): {
+  rawUrl: string;
+  previewUrl: string;
+  thumbnailUrl: string;
+} {
+  const encodedId = encodeURIComponent(attachmentId);
+  return {
+    rawUrl: `/api/sessions/${sessionId}/attachments/${encodedId}/raw`,
+    previewUrl: `/api/sessions/${sessionId}/attachments/${encodedId}/preview`,
+    thumbnailUrl: `/api/sessions/${sessionId}/attachments/${encodedId}/thumbnail`,
+  };
+}
+
+export function buildFileThumbnailRoute(sessionId: string, relativePath: string): string {
+  return `/api/sessions/${sessionId}/file-thumbnail?path=${encodeURIComponent(relativePath)}`;
+}
+
+export function attachmentRecordToEvent(record: AttachmentRecord): AttachmentRegistrationResult {
+  const routes = buildAttachmentRoutes(record.sessionId, record.attachmentId);
+  return {
+    sessionId: record.sessionId,
+    filePath: record.fileName,
+    relativePath: '',
+    fileName: record.fileName,
+    extension: record.extension,
+    attachmentType: record.attachmentType,
+    timestamp: record.timestamp,
+    size: record.size,
+    attachmentId: record.attachmentId,
+    source: record.source,
+    ...routes,
+  };
+}
+
+/** Options for {@link registerExternalAttachment}. */
+export interface RegisterExternalAttachmentOptions {
+  /**
+   * The registering session's working directory. Required to enforce workspace
+   * confinement — either when the global mode is enabled
+   * (`attachmentConfineToWorkspace` / `CODEMAN_ATTACHMENT_CONFINE`) or when
+   * {@link forceWorkspaceConfinement} is set for this call.
+   */
+  sessionWorkingDir?: string;
+  /**
+   * Force workspace confinement for THIS registration regardless of the global
+   * setting. Used by the terminal-output `codeman://attach` magic-link scanner:
+   * terminal output is attacker-influenceable (a prompt-injected session can
+   * print an arbitrary path), so passive magic links may only reference files
+   * inside the session workspace. Deliberate cross-workspace attachment still
+   * works through the explicit, Origin-guarded `POST /attachments` route and the
+   * `codeman attach` CLI (which POSTs directly when a session id is known).
+   */
+  forceWorkspaceConfinement?: boolean;
+}
+
+export async function registerExternalAttachment(
+  sessionId: string,
+  requestedPath: string,
+  options: RegisterExternalAttachmentOptions = {}
+): Promise<AttachmentRegistrationResult> {
+  if (!requestedPath || !isAbsolute(requestedPath)) {
+    throw new AttachmentRegistrationError('Attachment path must be an absolute local path');
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = realpathSync(requestedPath);
+  } catch {
+    throw new AttachmentRegistrationError('Attachment file not found', 404);
+  }
+
+  // COD-53: enforce the active attachment-guard policy on the symlink-resolved
+  // path before doing anything else.
+  const guard = await loadAttachmentGuardConfig();
+
+  if (guard.confineToWorkspace || options.forceWorkspaceConfinement) {
+    // Workspace-confined: the file MUST resolve inside the session's workspace.
+    // Applies when the global strict mode is on (opt-in, default OFF) OR when
+    // the caller forces it for this registration (the magic-link scanner — see
+    // forceWorkspaceConfinement). Strictly more restrictive than the blocklist.
+    const workingDir = options.sessionWorkingDir;
+    if (!workingDir || !validateSessionFilePath(workingDir, resolvedPath)) {
+      throw new AttachmentRegistrationError('Access to this file is blocked', 403);
+    }
+  }
+
+  // Blocklist (DEFAULT, also applied alongside confinement as defense in
+  // depth): pre-populated secret locations + the /root and /etc trees + any
+  // operator-configured extra trees. Symlinks are already resolved above.
+  // Cross-workspace attachment of non-blocked files stays allowed, so
+  // codeman-publish and the ~/.codeman review loop keep working.
+  if (isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)) {
+    throw new AttachmentRegistrationError('Access to this file is blocked', 403);
+  }
+
+  const extension = extname(resolvedPath).toLowerCase().replace(/^\./, '');
+  if (!isSupportedAttachmentExtension(extension)) {
+    throw new AttachmentRegistrationError('Unsupported attachment type');
+  }
+
+  const stat = await fs.stat(resolvedPath);
+  if (typeof stat.isFile === 'function' && !stat.isFile()) {
+    throw new AttachmentRegistrationError('Attachment path is not a file');
+  }
+
+  const existing = attachmentRegistry.findByFilePath(sessionId, resolvedPath);
+  if (existing) {
+    existing.size = stat.size;
+    existing.mtimeMs = stat.mtimeMs ?? 0;
+    existing.timestamp = Date.now();
+    return attachmentRecordToEvent(existing);
+  }
+
+  const record: AttachmentRecord = {
+    attachmentId: `att_${randomUUID()}`,
+    sessionId,
+    filePath: resolvedPath,
+    fileName: basename(resolvedPath),
+    extension,
+    attachmentType: getAttachmentType(extension),
+    size: stat.size,
+    mtimeMs: stat.mtimeMs ?? 0,
+    timestamp: Date.now(),
+    source: 'external',
+  };
+  attachmentRegistry.register(record);
+  return attachmentRecordToEvent(record);
+}
@@ -10,11 +10,17 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { createRequire } from 'module';
+import http from 'node:http';
+import https from 'node:https';
+import { readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { dataPath } from './config/instance.js';
 import { getSessionManager } from './session-manager.js';
 import { getTaskQueue } from './task-queue.js';
 import { getRalphLoop } from './ralph-loop.js';
 import { getStore } from './state-store.js';
 import { getErrorMessage } from './types.js';
+import { isSupportedAttachmentExtension } from './attachment-registry.js';

 const require = createRequire(import.meta.url);
 const pkg = require('../package.json') as { version: string };
@@ -23,6 +29,93 @@ const program = new Command();

 program.name('codeman').description('Claude Code session manager with autonomous Ralph Loop').version(pkg.version);

+function makeAttachmentMagicLink(filePath: string): string {
+  return `codeman://attach?path=${encodeURIComponent(filePath)}`;
+}
+
+function readCodemanEnv(): Record<string, string> {
+  const envPath = dataPath('.env');
+  try {
+    const text = readFileSync(envPath, 'utf-8');
+    const result: Record<string, string> = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) continue;
+      const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!match) continue;
+      let value = match[2].trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      result[match[1]] = value;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+async function postAttachment(apiUrl: string, sessionId: string, filePath: string): Promise<boolean> {
+  const envFile = readCodemanEnv();
+  const username = process.env.CODEMAN_USERNAME || envFile.CODEMAN_USERNAME || 'admin';
+  const password = process.env.CODEMAN_PASSWORD || envFile.CODEMAN_PASSWORD;
+  const url = new URL(`/api/sessions/${encodeURIComponent(sessionId)}/attachments`, apiUrl);
+  const body = JSON.stringify({ path: filePath });
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve) => {
+    const headers: Record<string, string | number> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    };
+    if (password) {
+      headers.Authorization = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+    }
+
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port,
+        method: 'POST',
+        path: `${url.pathname}${url.search}`,
+        rejectUnauthorized: false,
+        headers,
+      },
+      (res) => {
+        res.resume();
+        res.on('end', () => resolve(Boolean(res.statusCode && res.statusCode >= 200 && res.statusCode < 300)));
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.write(body);
+    req.end();
+  });
+}
+
+program
+  .command('attach <path>')
+  .description('Show an attachment card for a local file')
+  .option('-s, --session <id>', 'Codeman session ID (defaults to CODEMAN_SESSION_ID)')
+  .option('--url <url>', 'Codeman API URL (defaults to CODEMAN_API_URL or https://127.0.0.1:3000)')
+  .action(async (filePath, options) => {
+    const extension = String(filePath).split('.').pop()?.toLowerCase() || '';
+    if (!isAbsolute(filePath) || !isSupportedAttachmentExtension(extension)) {
+      console.error(chalk.red('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
+      process.exit(1);
+    }
+
+    const sessionId = options.session || process.env.CODEMAN_SESSION_ID;
+    const apiUrl = options.url || process.env.CODEMAN_API_URL || 'https://127.0.0.1:3000';
+    if (sessionId && (await postAttachment(apiUrl, sessionId, filePath))) {
+      console.log(chalk.green('✓ Attachment card requested'));
+      return;
+    }
+
+    console.log(makeAttachmentMagicLink(filePath));
+  });
+
 // ============ Session Commands ============

 const sessionCmd = program.command('session').alias('s').description('Manage Claude sessions');
@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Attachment path-guard configuration (COD-53).
+ *
+ * Governs which host files may be registered as cross-workspace attachments
+ * and served to the browser. Two operator-facing knobs, both with safe
+ * defaults:
+ *
+ *  1. **Blocked-path blocklist (DEFAULT, configurable).** Pre-populated with the
+ *     shared secret-location blocklist (`isSensitivePath`) PLUS the directory
+ *     trees `/root` and `/etc` (anything under them is blocked). The operator
+ *     EXTENDS — never shrinks — this set with additional absolute directory
+ *     trees via the settings key `attachmentBlockedPaths: string[]` and/or the
+ *     env var `CODEMAN_ATTACHMENT_BLOCKED_PATHS` (comma-separated).
+ *
+ *  2. **Workspace confinement (OPTIONAL, default OFF).** When enabled, an
+ *     attachment must resolve INSIDE the registering session's workingDir
+ *     (reusing `validateSessionFilePath` containment semantics). This is
+ *     strictly more restrictive than the blocklist and breaks intentional
+ *     cross-workspace attachment (codeman-publish, the ~/.codeman review-card
+ *     loop), so it is OFF by default. Toggle via settings
+ *     `attachmentConfineToWorkspace: boolean` and/or env
+ *     `CODEMAN_ATTACHMENT_CONFINE` (`1`/`true`).
+ *
+ * All paths passed to the predicates here MUST be absolute and symlink-resolved
+ * (realpath) by the caller, mirroring `isSensitivePath`'s contract.
+ *
+ * @module config/attachment-guard
+ */
+
+import { sep } from 'node:path';
+import { isSensitivePath } from '../web/sensitive-path.js';
+import { readJsonConfig, SETTINGS_PATH } from '../web/route-helpers.js';
+
+/**
+ * Directory trees blocked by default, IN ADDITION to the secret-location
+ * blocklist in `isSensitivePath`. Anything resolving under one of these trees
+ * is rejected. Pre-populated with the root account home and the system config
+ * tree (which already partially overlaps `isSensitivePath`'s `/etc/shadow`
+ * etc., but here we block the WHOLE tree).
+ */
+export const DEFAULT_BLOCKED_TREES: readonly string[] = ['/root', '/etc'];
+
+/** Settings key carrying extra blocked directory trees (extends the defaults). */
+export const ATTACHMENT_BLOCKED_PATHS_SETTING = 'attachmentBlockedPaths';
+
+/** Settings key carrying the workspace-confinement toggle. */
+export const ATTACHMENT_CONFINE_SETTING = 'attachmentConfineToWorkspace';
+
+/** Resolved attachment-guard configuration. */
+export interface AttachmentGuardConfig {
+  /** Pre-populated default trees PLUS any operator extras. */
+  blockedTrees: string[];
+  /** Whether attachments must resolve inside the session workspace. */
+  confineToWorkspace: boolean;
+}
+
+/** Normalizes a tree prefix: trim, drop trailing separators (but keep root). */
+function normalizeTree(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return '';
+  // Strip trailing slashes so '/etc/' and '/etc' behave the same; never reduce
+  // a bare separator to empty.
+  const stripped = trimmed.replace(/[/\\]+$/, '');
+  return stripped || trimmed[0];
+}
+
+/**
+ * Returns true if `absPath` (absolute, symlink-resolved) is the tree itself or
+ * lives under it. Uses path-separator-aware matching so `/etc` does NOT block
+ * an unrelated `/etcetera/notes.md`.
+ */
+export function isUnderTree(absPath: string, tree: string): boolean {
+  const t = normalizeTree(tree);
+  if (!t) return false;
+  if (absPath === t) return true;
+  return absPath.startsWith(t.endsWith(sep) ? t : t + sep);
+}
+
+/** Parses the comma-separated env override into a list of normalized trees. */
+function parseEnvBlockedTrees(): string[] {
+  const raw = process.env.CODEMAN_ATTACHMENT_BLOCKED_PATHS;
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map(normalizeTree)
+    .filter((t) => t.length > 0);
+}
+
+/** Parses the env confinement toggle (`1`/`true`/`yes`/`on`, case-insensitive). */
+function parseEnvConfine(): boolean | undefined {
+  const raw = process.env.CODEMAN_ATTACHMENT_CONFINE;
+  if (raw === undefined) return undefined;
+  return /^(1|true|yes|on)$/i.test(raw.trim());
+}
+
+/**
+ * Loads the effective attachment-guard config by merging the pre-populated
+ * defaults with settings.json and env overrides. Env wins over settings for the
+ * confinement toggle; blocked-tree extras from BOTH sources are unioned on top
+ * of the defaults (operators can only EXTEND, never shrink, the blocked set).
+ */
+export async function loadAttachmentGuardConfig(): Promise<AttachmentGuardConfig> {
+  const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'settings.json', {});
+
+  const settingsTrees = Array.isArray(settings[ATTACHMENT_BLOCKED_PATHS_SETTING])
+    ? (settings[ATTACHMENT_BLOCKED_PATHS_SETTING] as unknown[])
+        .filter((v): v is string => typeof v === 'string')
+        .map(normalizeTree)
+        .filter((t) => t.length > 0)
+    : [];
+
+  const blockedTrees = Array.from(new Set([...DEFAULT_BLOCKED_TREES, ...settingsTrees, ...parseEnvBlockedTrees()]));
+
+  const envConfine = parseEnvConfine();
+  const settingsConfine = settings[ATTACHMENT_CONFINE_SETTING] === true;
+  const confineToWorkspace = envConfine ?? settingsConfine;
+
+  return { blockedTrees, confineToWorkspace };
+}
+
+/**
+ * Attachment-specific blocklist check. Builds on the shared `isSensitivePath`
+ * base (secret locations, shared with `/api/download`) and ADDS the configured
+ * directory trees (`/root`, `/etc`, plus operator extras). `absPath` must be
+ * absolute and symlink-resolved.
+ *
+ * NOTE: this is intentionally a SUPERSET of `isSensitivePath` so `/api/download`
+ * behavior is NOT changed — only attachment registration/serving uses this.
+ */
+export function isBlockedAttachmentPath(absPath: string, blockedTrees: readonly string[]): boolean {
+  if (isSensitivePath(absPath)) return true;
+  return blockedTrees.some((tree) => isUnderTree(absPath, tree));
+}
@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Per-instance shared hook secret (COD-54).
+ *
+ * Claude Code hooks POST to `/api/hook-event` with no Basic-Auth credentials,
+ * relying on a localhost bypass in `web/middleware/auth.ts`. That bypass is safe
+ * for loopback-only deploys, but a `cloudflared --url http://127.0.0.1:port`
+ * tunnel proxies internet traffic INTO the loopback origin, so tunneled requests
+ * arrive with `req.ip === 127.0.0.1` and would otherwise pass the bypass and
+ * drive respawn/Ralph signals unauthenticated.
+ *
+ * To close that hole WITHOUT breaking the loop's own (credential-less) hook
+ * channel, every locally-generated hook command now presents a per-instance
+ * shared secret in the `X-Codeman-Hook-Secret` header. The middleware requires
+ * a matching secret for the bypass WHEN A TUNNEL IS RUNNING. Tunneled internet
+ * traffic can't know the secret; local hooks (which we generate) do.
+ *
+ * Storage mirrors the VAPID-key pattern in `push-store.ts`: a small file under
+ * the instance data dir (`dataPath('hook-secret')`), read-if-present /
+ * generate-if-missing, stable across restarts. 256 bits of hex.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { getDataDir, dataPath } from './instance.js';
+
+/** HTTP header local hooks use to present the shared secret. */
+export const HOOK_SECRET_HEADER = 'X-Codeman-Hook-Secret';
+
+/** Number of random bytes in the secret (256 bits → 64 hex chars). */
+const SECRET_BYTES = 32;
+
+let cachedSecret: string | null = null;
+
+/**
+ * Return this instance's hook secret, generating and persisting it on first use.
+ * Stable across restarts. Cached in-process after the first read.
+ */
+export function getHookSecret(): string {
+  if (cachedSecret) return cachedSecret;
+
+  const secretFile = dataPath('hook-secret');
+
+  if (existsSync(secretFile)) {
+    try {
+      const raw = readFileSync(secretFile, 'utf-8').trim();
+      if (raw) {
+        cachedSecret = raw;
+        return cachedSecret;
+      }
+      // Empty/whitespace file — fall through and regenerate.
+    } catch {
+      // Unreadable — fall through and regenerate.
+    }
+  }
+
+  const secret = randomBytes(SECRET_BYTES).toString('hex');
+  try {
+    mkdirSync(getDataDir(), { recursive: true });
+    // Owner-only perms — the secret gates the hook bypass.
+    writeFileSync(secretFile, secret, { mode: 0o600 });
+  } catch {
+    // Best-effort persistence: even if the write fails we still return a usable
+    // secret for this process so hooks/middleware agree within this run.
+  }
+  cachedSecret = secret;
+  return cachedSecret;
+}
@@ -395,8 +395,12 @@ export class FileStreamManager extends EventEmitter {
    // Normalize the working directory
    const normalizedWorkingDir = resolve(workingDir);

-    // Check if the resolved path is within the working directory
-    // or common log directories (/tmp intentionally excluded — world-writable)
+    // Allowed read roots for log tailing: the session working dir plus the
+    // INTENTIONAL log directories (/var/log, ~/logs). This is wider than the
+    // per-session boundary used by validateSessionFilePath — a deliberate,
+    // tested design choice for tailing system/app logs, documented as such in
+    // docs/security-architecture.md (security review M5). /tmp is excluded
+    // (world-writable).
    const allowedPaths = [normalizedWorkingDir, '/var/log', resolve(homedir(), 'logs')];

    const isAllowed = allowedPaths.some((allowed) => {
@@ -3,8 +3,9 @@
 *
 * Generates `.claude/settings.local.json` with hook definitions that POST
 * to Codeman's `/api/hook-event` endpoint when Claude Code fires hooks.
- * Uses `$CODEMAN_API_URL` and `$CODEMAN_SESSION_ID` env vars (set on every
- * managed session) so the config is static per case directory.
+ * Uses `$CODEMAN_API_URL`, `$CODEMAN_SESSION_ID`, and `$CODEMAN_HOOK_SECRET_FILE`
+ * env vars (set on every managed session) so the config is static per case
+ * directory and free of secret values.
 *
 * Key exports:
 * - `generateHooksConfig()` — returns hooks object for settings.local.json
@@ -41,11 +42,18 @@ import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
 export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
  // Read Claude Code's stdin JSON and forward it as the data field.
  // Falls back to empty object if stdin is unavailable or malformed.
+  // COD-54: present the per-instance hook secret so the bypass keeps working while
+  // a tunnel is running. The value is read from the secret file AT EXECUTION TIME
+  // (path via $CODEMAN_HOOK_SECRET_FILE, set in every managed session's env), so it
+  // never lands in this config and rotation needs no respawn. If the var/file is
+  // missing the header is empty — the middleware then allows the request only on
+  // the plain loopback bypass (tunnel down), same as pre-secret behavior.
  const curlCmd = (event: HookEventType) =>
    `HOOK_DATA=$(cat 2>/dev/null || echo '{}'); ` +
    `printf '{"event":"${event}","sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ` +
    `curl -s -X POST "$CODEMAN_API_URL/api/hook-event" ` +
    `-H 'Content-Type: application/json' ` +
+    `-H "X-Codeman-Hook-Secret: $(cat "$CODEMAN_HOOK_SECRET_FILE" 2>/dev/null)" ` +
    `--data @- ` +
    `2>/dev/null || true`;

@@ -12,7 +12,7 @@ import { EventEmitter } from 'node:events';
 import { watch, type FSWatcher } from 'chokidar';
 import { basename, extname, relative } from 'node:path';
 import { statSync } from 'node:fs';
-import type { ImageDetectedEvent } from './types.js';
+import type { AttachmentDetectedEvent, AttachmentDetectedType, ImageDetectedEvent } from './types.js';
 import { KeyedDebouncer } from './utils/index.js';

 // ========== Types ==========
@@ -20,7 +20,13 @@ import { KeyedDebouncer } from './utils/index.js';
 // ========== Constants ==========

 /** Supported image file extensions (lowercase) */
-const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+// PNG stays on the image-popup path: it's the dominant screenshot format and the
+// frontend only wires the `image:detected` popup today. The attachment-card UI
+// that would consume `attachment:detected` for images is out of scope for this
+// PR, so routing PNG to it would silently break the dropped-screenshot popup.
+const IMAGE_POPUP_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+const ATTACHMENT_EXTENSIONS = new Set(['.pdf', '.docx', '.pptx']);
+const DETECTED_FILE_EXTENSIONS = new Set([...IMAGE_POPUP_EXTENSIONS, ...ATTACHMENT_EXTENSIONS]);

 /** Time to wait for file writes to stabilize (ms) */
 const STABILITY_THRESHOLD_MS = 500;
@@ -166,8 +172,8 @@ export class ImageWatcher extends EventEmitter {
          }
          const ext = extname(path).toLowerCase();
          // Don't ignore directories (needed for watching to work)
-          // Ignore files that aren't images
-          return ext !== '' && !IMAGE_EXTENSIONS.has(ext);
+          // Ignore files that aren't previewable images/documents
+          return ext !== '' && !DETECTED_FILE_EXTENSIONS.has(ext);
        },
      });

@@ -229,15 +235,16 @@ export class ImageWatcher extends EventEmitter {

  /**
   * Handle a new file being detected.
-   * Verifies it's an image and emits the detection event.
+   * Verifies it's a previewable image/document and emits the detection event.
   */
  private handleNewFile(sessionId: string, filePath: string): void {
    const ext = extname(filePath).toLowerCase();

-    // Double-check it's an image extension
-    if (!IMAGE_EXTENSIONS.has(ext)) {
+    // Double-check it's a supported extension
+    if (!DETECTED_FILE_EXTENSIONS.has(ext)) {
      return;
    }
+    const isAttachment = ATTACHMENT_EXTENSIONS.has(ext);

    // Burst limit: skip if too many images detected for this session in a short window
    const now = Date.now();
@@ -259,7 +266,11 @@ export class ImageWatcher extends EventEmitter {
    // Debounce rapid file creation (e.g., multiple screenshots quickly)
    this.fileDeb.schedule(filePath, () => {
      this.fileToSession.delete(filePath);
-      this.emitImageDetected(sessionId, filePath);
+      if (isAttachment) {
+        this.emitAttachmentDetected(sessionId, filePath);
+      } else {
+        this.emitImageDetected(sessionId, filePath);
+      }
      // Increment burst count on actual emission (not on detection)
      const b = this.burstTrackers.get(sessionId);
      if (b) b.count++;
@@ -294,6 +305,42 @@ export class ImageWatcher extends EventEmitter {
      this.emit('image:error', error instanceof Error ? error : new Error(String(error)), sessionId);
    }
  }
+
+  /**
+   * Emit the attachment:detected event with file metadata.
+   */
+  private emitAttachmentDetected(sessionId: string, filePath: string): void {
+    try {
+      const stat = statSync(filePath);
+      const fileName = basename(filePath);
+      const workingDir = this.sessionDirs.get(sessionId);
+      const relativePath = workingDir ? relative(workingDir, filePath) : fileName;
+      const extension = extname(fileName).toLowerCase().replace(/^\./, '');
+
+      const event: AttachmentDetectedEvent = {
+        sessionId,
+        filePath,
+        relativePath,
+        fileName,
+        extension,
+        attachmentType: this.getAttachmentType(extension),
+        timestamp: Date.now(),
+        size: stat.size,
+      };
+
+      this.emit('attachment:detected', event);
+    } catch (error) {
+      this.emit('image:error', error instanceof Error ? error : new Error(String(error)), sessionId);
+    }
+  }
+
+  private getAttachmentType(extension: string): AttachmentDetectedType {
+    if (extension === 'png') return 'image';
+    if (extension === 'pdf') return 'pdf';
+    if (extension === 'docx') return 'document';
+    if (extension === 'pptx') return 'presentation';
+    return 'document';
+  }
 }

 // Export singleton instance for convenience
@@ -14,6 +14,7 @@ import type {
  ClaudeMode,
  SessionMode,
  OpenCodeConfig,
+  CodexConfig,
  EffortLevel,
 } from './types.js';

@@ -62,6 +63,7 @@ export interface CreateSessionOptions {
  claudeMode?: ClaudeMode;
  allowedTools?: string;
  openCodeConfig?: OpenCodeConfig;
+  codexConfig?: CodexConfig;
  /** 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. */
@@ -80,6 +82,7 @@ export interface RespawnPaneOptions {
  claudeMode?: ClaudeMode;
  allowedTools?: string;
  openCodeConfig?: OpenCodeConfig;
+  codexConfig?: CodexConfig;
  /** Resume a previous Claude conversation when respawning */
  resumeSessionId?: string;
  /** Extra env vars exported before launching the CLI (preserved across respawns). */
@@ -192,6 +195,12 @@ export interface TerminalMultiplexer extends EventEmitter {
   */
  getAttachArgs(muxName: string): string[];

+  /** Pin a mux window so client attaches do not automatically dictate its size. */
+  setManualWindowSize?(muxName: string): boolean;
+
+  /** Explicitly resize a mux window after Codeman accepts a terminal resize. */
+  resizeWindow?(muxName: string, cols: number, rows: number): boolean;
+
  // ========== Availability ==========

  /** Check if the multiplexer binary is available on the system */
@@ -205,4 +214,10 @@ 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 the active pane's current tmux buffer with ANSI escape codes preserved. */
+  captureActivePaneBuffer?(muxName: string): string | null;
 }
@@ -8,3 +8,4 @@
 export { RESEARCH_AGENT_PROMPT } from './research-agent.js';
 export { PLANNER_PROMPT } from './planner.js';
 export { PHASE_EXECUTION_PROMPT, TEAM_LEAD_PROMPT, REPLAN_PROMPT, SINGLE_TASK_PROMPT } from './orchestrator.js';
+export { RALPH_STATUS_CONTRACT, buildRalphLoopPrompt, type RalphLoopPromptOptions } from './ralph.js';
@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Ralph Loop prompt construction
+ *
+ * Builds the full `@ralph_prompt.md` content written for a new Ralph loop
+ * session, including the RALPH_STATUS block contract. The contract travels
+ * with the loop prompt (not the generated CLAUDE.md) so every Ralph session
+ * emits parseable status blocks regardless of the project's CLAUDE.md.
+ *
+ * @module prompts/ralph
+ */
+
+/**
+ * Structured status-reporting contract appended to every Ralph loop prompt.
+ *
+ * `RalphStatusParser` (src/ralph-status-parser.ts) parses this block from
+ * session output — keep the field names and enum values in sync with its
+ * patterns.
+ */
+export const RALPH_STATUS_CONTRACT = `## Status Reporting
+
+End EVERY response with exactly this block — Codeman parses it to track the loop:
+
+\`\`\`
+---RALPH_STATUS---
+STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+TASKS_COMPLETED_THIS_LOOP: <number>
+FILES_MODIFIED: <number>
+TESTS_STATUS: PASSING | FAILING | NOT_RUN
+WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
+EXIT_SIGNAL: false | true
+RECOMMENDATION: <one line: what to do next>
+---END_RALPH_STATUS---
+\`\`\`
+
+Rules:
+- \`EXIT_SIGNAL: true\` only when ALL tasks are verifiably done — then also output the completion phrase
+- \`STATUS: BLOCKED\` when you need human input; describe the blocker in RECOMMENDATION
+- Never set \`EXIT_SIGNAL: true\` while tests are failing
+`;
+
+export interface RalphLoopPromptOptions {
+  /** The user's task description (becomes the prompt header) */
+  taskDescription: string;
+  /** Completion phrase the session must emit inside <promise></promise> */
+  completionPhrase: string;
+  /** Whether a @fix_plan.md task plan was generated for this loop */
+  hasPlan: boolean;
+}
+
+/**
+ * Builds the full Ralph loop prompt written to `@ralph_prompt.md`.
+ */
+export function buildRalphLoopPrompt({ taskDescription, completionPhrase, hasPlan }: RalphLoopPromptOptions): string {
+  let fullPrompt = taskDescription + '\n\n---\n\n';
+  if (hasPlan) {
+    fullPrompt += '## Task Plan\n\n';
+    fullPrompt += 'A task plan has been written to `@fix_plan.md`. Use this to track progress:\n';
+    fullPrompt += '- Reference the plan at the start of each iteration\n';
+    fullPrompt += '- Update task checkboxes as you complete items\n';
+    fullPrompt += '- Work through items in priority order (P0 > P1 > P2)\n\n';
+  }
+  fullPrompt += '## Iteration Protocol\n\n';
+  fullPrompt += 'This is an autonomous loop. Files from previous iterations persist. On each iteration:\n';
+  fullPrompt += '1. Check what work has already been done\n';
+  fullPrompt += '2. Make incremental progress toward completion\n';
+  fullPrompt += '3. Commit meaningful changes with descriptive messages\n\n';
+  fullPrompt += '## Verification\n\n';
+  fullPrompt += 'After each significant change:\n';
+  fullPrompt += '- Run tests to verify (npm test, pytest, etc.)\n';
+  fullPrompt += '- Check for type/lint errors if applicable\n';
+  fullPrompt += '- If tests fail, read the error, fix it, and retry\n\n';
+  fullPrompt += '## Completion Criteria\n\n';
+  fullPrompt += `Output \`<promise>${completionPhrase}</promise>\` when ALL of the following are true:\n`;
+  fullPrompt += '- All requirements from the task description are implemented\n';
+  fullPrompt += '- All tests pass\n';
+  fullPrompt += '- Changes are committed\n\n';
+  fullPrompt += '## If Stuck\n\n';
+  fullPrompt += 'If you encounter the same error for 3+ iterations:\n';
+  fullPrompt += "1. Document what you've tried\n";
+  fullPrompt += '2. Identify the specific blocker\n';
+  fullPrompt += '3. Try an alternative approach\n';
+  fullPrompt += '4. If truly blocked, output `<promise>BLOCKED</promise>` with an explanation\n\n';
+  fullPrompt += RALPH_STATUS_CONTRACT;
+  return fullPrompt;
+}
@@ -2779,6 +2779,19 @@ export class RespawnController extends EventEmitter {
      return;
    }

+    // Usage-limit pause: Claude can't work and the cycle's /clear would wipe
+    // the paused conversation — the auto-resume scheduler owns recovery here.
+    if (this.session.isLimitPaused) {
+      this.log('Skipping respawn cycle - usage-limit pause active (auto-resume armed)');
+      this.logAction('health', 'Respawn skipped: usage-limit pause (auto-resume armed)');
+      this.emit('respawnBlocked', {
+        reason: 'usage_limit',
+        details: 'Usage limit reached — waiting for scheduled auto-resume',
+      });
+      this.setState('watching');
+      return;
+    }
+
    // Start the respawn cycle
    this.cycleCount++;
    this.log(`Starting respawn cycle #${this.cycleCount}`);
@@ -1,15 +1,25 @@
 /**
- * @fileoverview Auto-compact and auto-clear automation for Session.
+ * @fileoverview Auto-compact, auto-clear, and auto-resume automation for Session.
 *
 * Monitors token counts and triggers /compact or /clear commands when
 * configurable thresholds are reached. Waits for Claude to be idle
 * before sending commands, with retry logic and mutual exclusion
 * (compact and clear never run simultaneously).
 *
+ * Also implements auto-resume on usage limit ("token pause" control):
+ * when enabled and Claude stops on a usage-limit message ("5-hour limit
+ * reached ∙ resets 8pm" and friends — see usage-limit-patterns.ts), a timer
+ * is armed for the parsed reset time plus a safety buffer, then Escape
+ * (dismisses the rate-limit options dialog if open) and a "continue" prompt
+ * are sent so work resumes automatically. If the session is still limited,
+ * the fresh limit message re-arms the scheduler — that retry loop is the
+ * safety net for clock skew and parse imprecision.
+ *
 * @module session-auto-ops
 */

 import { EventEmitter } from 'node:events';
+import { detectUsageLimitPause } from './usage-limit-patterns.js';

 // ============================================================================
 // Timing Constants
@@ -78,6 +88,28 @@ async function executeWhenIdle(
  }
 }

+// ============================================================================
+// Auto-resume (usage-limit pause) constants
+// ============================================================================
+
+/** Safety buffer after the stated reset time before resuming (2 minutes) */
+const RESUME_BUFFER_MS = 2 * 60_000;
+
+/** Minimum delay before an overdue resume fires (lets output settle) */
+const RESUME_MIN_DELAY_MS = 5_000;
+
+/** Retry interval when the reset time is stale/past (5 minutes) */
+const RESUME_RETRY_MS = 5 * 60_000;
+
+/** Re-detections scheduling within this window of the current schedule are ignored */
+const RESUME_DEDUP_TOLERANCE_MS = 90_000;
+
+/** Delay between Escape (dialog dismiss) and the resume prompt */
+const RESUME_ESC_DELAY_MS = 600;
+
+/** Prompt sent to resume work after the limit resets */
+const RESUME_PROMPT = 'continue';
+
 /** Minimum valid threshold for auto-clear/compact (1000 tokens) */
 const MIN_AUTO_THRESHOLD = 1000;

@@ -131,6 +163,16 @@ export class SessionAutoOps extends EventEmitter {
  private _isClearing: boolean = false;
  private _autoClearTimer: NodeJS.Timeout | null = null;

+  // Auto-resume (usage-limit pause) state
+  private _autoResumeEnabled: boolean = false;
+  private _autoResumeTimer: NodeJS.Timeout | null = null;
+  /** Esc→continue gap timer; detections must NOT cancel a resume in flight */
+  private _resumeFollowupTimer: NodeJS.Timeout | null = null;
+  /** When the scheduled resume fires (epoch ms), null when not armed */
+  private _autoResumeAt: number | null = null;
+  private _limitPaused: boolean = false;
+  private _resumeAttempts: number = 0;
+
  private readonly callbacks: AutoOpsCallbacks;

  constructor(callbacks: AutoOpsCallbacks, config?: { compactThreshold?: number; clearThreshold?: number }) {
@@ -207,6 +249,145 @@ export class SessionAutoOps extends EventEmitter {
    }
  }

+  // ============================================================================
+  // Auto-resume (usage-limit pause) — getters/setters
+  // ============================================================================
+
+  get autoResumeEnabled(): boolean {
+    return this._autoResumeEnabled;
+  }
+
+  /** When the scheduled resume fires (epoch ms), or null when not armed. */
+  get autoResumeAt(): number | null {
+    return this._autoResumeAt;
+  }
+
+  /** True while the session is believed to be paused on a usage limit. */
+  get isLimitPaused(): boolean {
+    return this._limitPaused;
+  }
+
+  setAutoResume(enabled: boolean): void {
+    this._autoResumeEnabled = enabled;
+    if (!enabled) {
+      this._cancelAutoResume('disabled');
+    }
+  }
+
+  /**
+   * Restore auto-resume state after a Codeman restart. A persisted pending
+   * schedule is re-armed; an overdue one fires shortly after boot (the limit
+   * footer won't reprint on its own, so without this the pause would stall).
+   */
+  restoreAutoResume(enabled: boolean, resumeAt?: number): void {
+    this._autoResumeEnabled = enabled;
+    if (!enabled || !resumeAt) return;
+    const now = Date.now();
+    this._scheduleResume(Math.max(resumeAt, now + RESUME_MIN_DELAY_MS), resumeAt, 'restored');
+  }
+
+  // ============================================================================
+  // Auto-resume — detection and scheduling
+  // ============================================================================
+
+  /**
+   * Scan cleaned terminal output for a usage-limit pause message and (re)arm
+   * the resume schedule. Called from the session's throttled parser path.
+   */
+  processCleanData(cleanData: string): void {
+    if (!this._autoResumeEnabled || this.callbacks.isStopped()) return;
+    // A resume is in flight (Esc sent, continue pending): output from our own
+    // Escape can redraw the stale limit footer — don't let it re-arm and
+    // cancel the continue. Fresh evidence arrives after the prompt is sent.
+    if (this._resumeFollowupTimer) return;
+
+    const detection = detectUsageLimitPause(cleanData);
+    if (!detection) return;
+
+    const now = Date.now();
+    const overdue = detection.resetAt <= now;
+    const fireAt = overdue
+      ? now + RESUME_RETRY_MS // stale reset time → gentle retry loop
+      : Math.max(detection.resetAt + RESUME_BUFFER_MS, now + RESUME_MIN_DELAY_MS);
+
+    if (this._autoResumeTimer && this._autoResumeAt !== null) {
+      // Already armed: the footer redraws constantly, so ignore re-detections
+      // that land on (or later than) the current schedule. Only an EARLIER
+      // parsed time replaces it — an overdue retry never preempts a real one.
+      if (overdue || fireAt >= this._autoResumeAt - RESUME_DEDUP_TOLERANCE_MS) return;
+    }
+
+    this._scheduleResume(fireAt, detection.resetAt, detection.matched);
+  }
+
+  /**
+   * Claude started working — the limit is lifted (or the user resumed
+   * manually), so any pending auto-resume is obsolete.
+   */
+  notifyWorking(): void {
+    this._resumeAttempts = 0;
+    if (!this._limitPaused && !this._autoResumeTimer && !this._resumeFollowupTimer) return;
+    this._cancelAutoResume('working');
+  }
+
+  private _scheduleResume(fireAt: number, resetAt: number, matched: string): void {
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
+    this._limitPaused = true;
+    this._autoResumeAt = fireAt;
+    const delay = Math.max(fireAt - Date.now(), 0);
+    console.log(
+      `[SessionAutoOps ${this.callbacks.getSessionId()}] Usage-limit pause detected ("${matched.slice(0, 60)}"), auto-resume in ${Math.round(delay / 60000)}min`
+    );
+    this._autoResumeTimer = setTimeout(() => void this._fireResume(), delay);
+    this.emit('limitPauseScheduled', { resetAt, resumeAt: fireAt, matched });
+  }
+
+  private async _fireResume(): Promise<void> {
+    this._autoResumeTimer = null;
+    if (!this._autoResumeEnabled || this.callbacks.isStopped()) return;
+
+    if (this.callbacks.isWorking()) {
+      // Session resumed on its own (or via the user) — nothing to do.
+      this._cancelAutoResume('working');
+      return;
+    }
+
+    this._resumeAttempts++;
+    const attempt = this._resumeAttempts;
+    this._limitPaused = false; // optimistic: a fresh limit message re-arms us
+    this._autoResumeAt = null;
+
+    // Escape first: dismisses the rate-limit options dialog if Claude opened
+    // one (harmless at an idle prompt), then the resume prompt after a beat.
+    await this.callbacks.writeCommand('\x1b');
+    this._resumeFollowupTimer = setTimeout(() => {
+      this._resumeFollowupTimer = null;
+      if (this.callbacks.isStopped()) return;
+      void this.callbacks.writeCommand(`${RESUME_PROMPT}\r`);
+      this.emit('limitResume', { attempt });
+    }, RESUME_ESC_DELAY_MS);
+  }
+
+  private _cancelAutoResume(reason: 'disabled' | 'working' | 'stopped'): void {
+    const wasArmed = this._autoResumeTimer !== null || this._resumeFollowupTimer !== null || this._limitPaused;
+    if (this._autoResumeTimer) {
+      clearTimeout(this._autoResumeTimer);
+      this._autoResumeTimer = null;
+    }
+    if (this._resumeFollowupTimer) {
+      clearTimeout(this._resumeFollowupTimer);
+      this._resumeFollowupTimer = null;
+    }
+    this._limitPaused = false;
+    this._autoResumeAt = null;
+    if (wasArmed && reason !== 'stopped') {
+      this.emit('limitResumeCancelled', { reason });
+    }
+  }
+
  // ============================================================================
  // Threshold checks
  // ============================================================================
@@ -321,5 +502,7 @@ export class SessionAutoOps extends EventEmitter {
      this._autoClearTimer = null;
    }
    this._isClearing = false;
+
+    this._cancelAutoResume('stopped');
  }
 }
@@ -11,6 +11,7 @@
 import type { ClaudeMode, EffortLevel } from './types.js';
 import { isEffortLevel } from './types.js';
 import { getAugmentedPath } from './utils/index.js';
+import { dataPath } from './config/instance.js';

 /**
 * Build Claude CLI permission flags based on the configured mode.
@@ -113,6 +114,8 @@ export function buildClaudeEnv(sessionId: string): Record<string, string | undef
    CODEMAN_MUX: '1',
    CODEMAN_SESSION_ID: sessionId,
    CODEMAN_API_URL: process.env.CODEMAN_API_URL || 'http://localhost:3000',
+    // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
+    CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
  };
 }

@@ -149,5 +152,7 @@ export function buildShellEnv(sessionId: string): Record<string, string | undefi
    CODEMAN_MUX: '1',
    CODEMAN_SESSION_ID: sessionId,
    CODEMAN_API_URL: process.env.CODEMAN_API_URL || 'http://localhost:3000',
+    // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
+    CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
  };
 }
@@ -46,6 +46,7 @@ import {
  type ClaudeMode,
  type SessionMode,
  type OpenCodeConfig,
+  type CodexConfig,
  type EffortLevel,
 } from './types.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
@@ -77,11 +78,15 @@ import {
  buildShellEnv,
 } from './session-cli-builder.js';
 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';

 export type { BackgroundTask } from './task-tracker.js';
 export type { RalphTrackerState, RalphTodoItem, ActiveBashTool } from './types.js';

+export type ResizeViewportType = 'mobile' | 'tablet' | 'desktop';
+
 /** Line buffer flush interval (100ms) - forces processing of partial lines */
 const LINE_BUFFER_FLUSH_INTERVAL = 100;

@@ -121,6 +126,11 @@ const CTRL_L_PATTERN = /\x0c/g;
 /** Pattern to split by newlines (CR or LF) */
 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';
+}
+
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)

 /** PTY fallback geometry when tmux can't be queried (matches pre-#80 hardcoded values). */
@@ -250,6 +260,9 @@ export class Session extends EventEmitter {
  private _messages: ClaudeMessage[] = [];
  private _lineBuffer: string = '';
  private _lineBufferFlushTimer: NodeJS.Timeout | null = null;
+  // Codex only: trailing partial CSI held back so sequences split across PTY
+  // chunks can't slip past the alt-screen/scrollback strip (see _handleTerminalOutput)
+  private _codexSeqCarry: string = '';
  private resolvePromise: ((value: { result: string; cost: number }) => void) | null = null;
  private rejectPromise: ((reason: Error) => void) | null = null;
  private _promptResolved: boolean = false; // Guard against race conditions in runPrompt
@@ -299,6 +312,9 @@ export class Session extends EventEmitter {
  private _parentAgentId: string | null = null;
  private _childAgentIds: string[] = [];

+  // Bounded dedup set for terminal attachment magic-links already requested.
+  private _attachmentMagicSeen = new Set<string>();
+
  // Nice prioritying configuration
  private _niceConfig: NiceConfig = { ...DEFAULT_NICE_CONFIG };

@@ -311,6 +327,8 @@ export class Session extends EventEmitter {

  // OpenCode configuration (only for mode === 'opencode')
  private _openCodeConfig: OpenCodeConfig | undefined;
+  // Codex configuration (only for mode === 'codex')
+  private _codexConfig: CodexConfig | undefined;
  private _resumeSessionId: string | undefined;

  // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -379,6 +397,8 @@ export class Session extends EventEmitter {
      allowedTools?: string;
      /** OpenCode configuration (only for mode === 'opencode') */
      openCodeConfig?: OpenCodeConfig;
+      /** Codex configuration (only for mode === 'codex') */
+      codexConfig?: CodexConfig;
      /** Resume a previous Claude conversation (used after server reboot) */
      resumeSessionId?: string;
      /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
@@ -432,6 +452,11 @@ export class Session extends EventEmitter {
      this._openCodeConfig = config.openCodeConfig;
    }

+    // Apply Codex configuration
+    if (config.codexConfig) {
+      this._codexConfig = config.codexConfig;
+    }
+
    // 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)
@@ -503,6 +528,9 @@ export class Session extends EventEmitter {
      this._totalOutputTokens = 0;
      this.emit('autoClear', data);
    });
+    this._autoOps.on('limitPauseScheduled', (data) => this.emit('limitPauseScheduled', data));
+    this._autoOps.on('limitResume', (data) => this.emit('limitResume', data));
+    this._autoOps.on('limitResumeCancelled', (data) => this.emit('limitResumeCancelled', data));
  }

  get status(): SessionStatus {
@@ -694,6 +722,11 @@ export class Session extends EventEmitter {
    return this._allowedTools;
  }

+  /** Codex CLI configuration for this session. */
+  get codexConfig(): CodexConfig | undefined {
+    return this._codexConfig;
+  }
+
  // Note: _buildPermissionArgs removed — now using buildInteractiveArgs from session-cli-builder.ts

  /**
@@ -803,6 +836,39 @@ export class Session extends EventEmitter {
    this._autoOps.setAutoCompact(enabled, threshold, prompt);
  }

+  get autoResumeEnabled(): boolean {
+    return this._autoOps.autoResumeEnabled;
+  }
+
+  /** When the scheduled usage-limit auto-resume fires (epoch ms), or null. */
+  get autoResumeAt(): number | null {
+    return this._autoOps.autoResumeAt;
+  }
+
+  /** True while the session is paused on a Claude usage limit (auto-resume armed). */
+  get isLimitPaused(): boolean {
+    return this._autoOps.isLimitPaused;
+  }
+
+  setAutoResume(enabled: boolean): void {
+    this._autoOps.setAutoResume(enabled);
+    // Users typically enable this WHILE a session already sits paused — the
+    // limit footer won't reprint on its own, so scan the recent buffer once.
+    // Only a future reset time counts: stale scrollback must not arm a resume.
+    if (enabled && !isExternalCliMode(this.mode)) {
+      const tail = this._terminalBuffer.value.slice(-8192).replace(ANSI_ESCAPE_PATTERN_FULL, '');
+      const detection = detectUsageLimitPause(tail);
+      if (detection && detection.resetAt > Date.now()) {
+        this._autoOps.processCleanData(tail);
+      }
+    }
+  }
+
+  /** Restore auto-resume state (and a pending schedule) after Codeman restart. */
+  restoreAutoResume(enabled: boolean, resumeAt?: number): void {
+    this._autoOps.restoreAutoResume(enabled, resumeAt);
+  }
+
  get imageWatcherEnabled(): boolean {
    return this._imageWatcherEnabled;
  }
@@ -847,6 +913,8 @@ export class Session extends EventEmitter {
      autoCompactEnabled: this._autoOps.autoCompactEnabled,
      autoCompactThreshold: this._autoOps.autoCompactThreshold,
      autoCompactPrompt: this._autoOps.autoCompactPrompt,
+      autoResumeEnabled: this._autoOps.autoResumeEnabled,
+      autoResumeAt: this._autoOps.autoResumeAt ?? undefined,
      imageWatcherEnabled: this._imageWatcherEnabled,
      totalCost: this._totalCost,
      inputTokens: this._totalInputTokens,
@@ -865,6 +933,7 @@ export class Session extends EventEmitter {
      cliAccountType: this._cliAccountType || undefined,
      cliLatestVersion: this._cliLatestVersion || undefined,
      openCodeConfig: this._openCodeConfig,
+      codexConfig: this._codexConfig,
      resumeSessionId: this._resumeSessionId,
      effort: this._effort,
      // envOverrides intentionally NOT on the public SessionState type — they must not
@@ -1004,7 +1073,12 @@ export class Session extends EventEmitter {
    }

    // Attach to the mux session via PTY
-    // Query existing tmux window size so re-attach matches (avoids flicker from 120x40 default)
+    // 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);
    try {
      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
@@ -1024,6 +1098,61 @@ export class Session extends EventEmitter {
  }

  private _handleTerminalOutput(data: string): void {
+    // Codex emits sequences that wipe xterm.js scrollback, plus mouse-tracking
+    // enables that hijack the scroll wheel so the user can't reach scrollback:
+    //   - \x1b[?1049h / \x1b[?47h / \x1b[?1047h: switch to the alt buffer (no
+    //     scrollback) — \x1b[?...l switches back.
+    //   - \x1b[3J: erase saved lines (scrollback). (\x1b[2J / \x1b[J — erase
+    //     the visible viewport — are left intact; the TUI repaints those rows.)
+    //   - \x1b[?1000h / 1002h / 1003h / 1005h / 1006h / 1007h: mouse-tracking
+    //     modes (X10, button-event, any-event, UTF-8, SGR, alt-scroll). Once on,
+    //     xterm.js forwards wheel events to codex instead of scrolling the
+    //     viewport, so the conversation is in scrollback but unreachable.
+    //     (Focus events at ?1004 are left alone — codeman uses them for
+    //     active-tab detection.)
+    // Strip them at the source so neither the persisted buffer nor the live
+    // SSE/WS stream carries them, keeping everything in the main buffer with
+    // scrollback intact. Codex's cursor-positioned redraws overwrite only the
+    // cells they actually target, so the non-erased rows keep their content.
+    if (this.mode === 'codex') {
+      // Reassemble sequences split across PTY chunk boundaries first: a chunk
+      // ending mid-sequence ('\x1b[?104' now, '9h' next) would slip past the
+      // strip below and leave xterm stuck in the scrollback-less alt buffer
+      // until the next buffer replay. Hold back an incomplete digit-only CSI
+      // tail (≤7 chars — the longest strippable intro is '\x1b[?1049') and
+      // prepend it to the next chunk; complete sequences are never held.
+      data = this._codexSeqCarry + data;
+      this._codexSeqCarry = '';
+      // eslint-disable-next-line no-control-regex
+      const splitTail = data.match(/\x1b(?:\[\??[0-9]{0,4})?$/);
+      if (splitTail) {
+        this._codexSeqCarry = splitTail[0];
+        data = data.slice(0, -splitTail[0].length);
+        if (!data) return;
+      }
+      data = data
+        // eslint-disable-next-line no-control-regex
+        .replace(/\x1b\[\?(?:47|1047|1049)[hl]/g, '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/\x1b\[3J/g, '')
+        // eslint-disable-next-line no-control-regex
+        .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);
+      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() });
+    }
+
    // BufferAccumulator handles auto-trimming when max size exceeded
    this._terminalBuffer.append(data);
    this._lastActivityAt = Date.now();
@@ -1038,7 +1167,7 @@ export class Session extends EventEmitter {

    this._resetBuffers();

-    const modeLabel = this.mode === 'opencode' ? 'OpenCode' : 'Claude';
+    const modeLabel = this.mode === 'opencode' ? 'OpenCode' : this.mode === 'codex' ? 'Codex' : 'Claude';
    console.log(
      `[Session] Starting interactive ${modeLabel} session` + (this._useMux ? ` (with ${this._mux!.backend})` : '')
    );
@@ -1056,6 +1185,7 @@ export class Session extends EventEmitter {
            claudeMode: this._claudeMode,
            allowedTools: this._allowedTools,
            openCodeConfig: this._openCodeConfig,
+            codexConfig: this._codexConfig,
            resumeSessionId: this._resumeSessionId,
            envOverrides: this._envOverrides,
            effort: this._effort,
@@ -1070,6 +1200,7 @@ export class Session extends EventEmitter {
            claudeMode: this._claudeMode,
            allowedTools: this._allowedTools,
            openCodeConfig: this._openCodeConfig,
+            codexConfig: this._codexConfig,
            resumeSessionId: this._resumeSessionId,
            envOverrides: this._envOverrides,
            effort: this._effort,
@@ -1083,8 +1214,8 @@ export class Session extends EventEmitter {
        // For NEW mux sessions: wait for readiness then clean buffer
        // For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
        if (!isRestored) {
-          if (this.mode === 'opencode') {
-            // OpenCode uses Bubble Tea TUI — no ❯ prompt to detect.
+          if (isExternalCliMode(this.mode)) {
+            // External CLIs use custom TUIs — no ❯ prompt to detect.
            // Wait for TUI to stabilize (output stops changing), then mark ready.
            // Don't clear the buffer — the TUI's initial render IS the useful content.
            // Emit needsRefresh so the client fetches the full buffer once the TUI has rendered.
@@ -1139,6 +1270,10 @@ export class Session extends EventEmitter {
      if (this.mode === 'opencode') {
        throw new Error('OpenCode sessions require tmux. Direct PTY fallback is not supported.');
      }
+      // Codex sessions require tmux for OPENAI_API_KEY injection via setenv
+      if (this.mode === 'codex') {
+        throw new Error('Codex 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
@@ -1216,6 +1351,7 @@ export class Session extends EventEmitter {
          this._isWorking = true;
          this._status = 'busy';
          this.emit('working');
+          this._autoOps.notifyWorking();
        }
        this._awaitingIdleConfirmation = false;
        if (this.activityTimeout) clearTimeout(this.activityTimeout);
@@ -1298,9 +1434,9 @@ export class Session extends EventEmitter {
   * PTY data chunk. Receives accumulated raw data to process in one batch.
   */
  private _processExpensiveParsers(rawData: string): void {
-    // Skip Claude-specific parsers for OpenCode sessions — Ralph tracker, BashToolParser,
-    // token parsing, and CLI info parsing all depend on Claude's output format.
-    if (this.mode === 'opencode') return;
+    // Skip Claude-specific parsers for external CLI sessions (Ralph tracker,
+    // BashToolParser, token + CLI-info parsing all depend on Claude's output format).
+    if (isExternalCliMode(this.mode)) return;

    // Lazy ANSI strip: only compute cleanData when a consumer actually needs it.
    let _cleanData: string | null = null;
@@ -1322,6 +1458,11 @@ export class Session extends EventEmitter {
      this._bashToolParser.processCleanData(getCleanData());
    }

+    // Usage-limit pause detection (auto-resume on usage limit)
+    if (this._autoOps.autoResumeEnabled) {
+      this._autoOps.processCleanData(getCleanData());
+    }
+
    // Parse token count from status line (e.g., "123.4k tokens" or "5234 tokens")
    if (rawData.includes('token')) {
      this.parseTokensFromStatusLine(getCleanData());
@@ -1350,6 +1491,7 @@ export class Session extends EventEmitter {
        this._isWorking = true;
        this._status = 'busy';
        this.emit('working');
+        this._autoOps.notifyWorking();
        this._awaitingIdleConfirmation = false;
        if (this.activityTimeout) clearTimeout(this.activityTimeout);
      }
@@ -1631,6 +1773,7 @@ export class Session extends EventEmitter {
    this._errorBuffer = '';
    this._messages = [];
    this._lineBuffer = '';
+    this._codexSeqCarry = '';
    this._lastActivityAt = Date.now();
  }

@@ -2045,18 +2188,101 @@ export class Session extends EventEmitter {
  private _ptyCols = 120;
  private _ptyRows = 40;

+  /**
+   * Live WebSocket connections that have announced a desktop viewport for this
+   * session. While at least one is registered, small-viewport (mobile/tablet)
+   * resizes are ignored so a phone glancing at the session can't reflow the
+   * PTY under an active desktop view. Claims are connection-scoped: ws-routes
+   * registers them on a desktop-typed resize and releases them on socket
+   * close, so a mobile-only session (no desktop connected) keeps full control
+   * of its own size — including narrowing below the spawn default.
+   *
+   * Deliberate tradeoff: claims are WS-only because only a socket has a
+   * liveness signal. A desktop degraded to the stateless HTTP resize fallback
+   * still applies its typed resizes but holds no claim, so a concurrent phone
+   * can reflow it. This is cooperative UX arbitration, not a security
+   * boundary — untyped (legacy/API) resizes bypass claims by design.
+   */
+  private _desktopSizeClaims = new Set<symbol>();
+
+  /**
+   * A desktop sizing claim only blocks small-viewport resizes while the
+   * desktop is RECENTLY ACTIVE (claim registration or typed input within this
+   * window). An abandoned-but-connected desktop tab (left open at home, screen
+   * locked) must not hold a phone's view hostage: without this, the phone
+   * renders a desktop-width stream in a narrow xterm — mid-word wraps, tmux
+   * dot-fill, and Ink overdraw soup (the 0.9.8–0.9.12 mobile regression).
+   */
+  private static readonly DESKTOP_CLAIM_IDLE_MS = 90_000;
+
+  /** Last evidence of a live desktop user (claim registered / typed input). */
+  private _lastDesktopActivityAt = 0;
+
+  /** Last desktop-typed dimensions, for re-asserting after a mobile override. */
+  private _lastDesktopDims: { cols: number; rows: number } | null = null;
+
+  /** True while a small viewport reflowed the pane past an idle desktop claim. */
+  private _mobileSizeOverride = false;
+
+  /** Register a live desktop sizing claim (see _desktopSizeClaims). */
+  claimDesktopSizing(token: symbol): void {
+    this._desktopSizeClaims.add(token);
+    this._lastDesktopActivityAt = Date.now();
+  }
+
+  /** Release a desktop sizing claim when its connection goes away. */
+  releaseDesktopSizing(token: symbol): void {
+    this._desktopSizeClaims.delete(token);
+  }
+
+  /**
+   * Record desktop user activity (typed input over a claim-holding socket).
+   * If a phone reflowed the pane while the desktop was idle, the desktop
+   * layout is restored — "whoever is actively using the session wins".
+   */
+  noteDesktopActivity(): void {
+    this._lastDesktopActivityAt = Date.now();
+    if (this._mobileSizeOverride && this._lastDesktopDims) {
+      this._mobileSizeOverride = false;
+      this.resize(this._lastDesktopDims.cols, this._lastDesktopDims.rows, { viewportType: 'desktop' });
+    }
+  }
+
  /**
   * Resizes the PTY terminal dimensions.
   * Skips the resize if dimensions haven't changed to avoid triggering
   * unnecessary Ink full-screen redraws (visible flicker on tab switch).
   *
+   * Arbitration: while a desktop connection holds a sizing claim AND has been
+   * active within DESKTOP_CLAIM_IDLE_MS, resizes from small viewports
+   * (mobile/tablet) are ignored — shrink AND grow would both reflow the
+   * desktop view. Once the desktop goes idle, a phone may take the pane (the
+   * desktop re-asserts its size on its next typed input via
+   * noteDesktopActivity). Without a desktop connected, small viewports
+   * control the PTY size freely.
+   *
   * @param cols - Number of columns (width in characters)
   * @param rows - Number of rows (height in lines)
   */
-  resize(cols: number, rows: number): void {
+  resize(cols: number, rows: number, options: { viewportType?: ResizeViewportType } = {}): void {
+    const isSmallViewport = options.viewportType === 'mobile' || options.viewportType === 'tablet';
+    if (options.viewportType === 'desktop') {
+      this._lastDesktopDims = { cols, rows };
+      this._lastDesktopActivityAt = Date.now();
+      this._mobileSizeOverride = false;
+    }
+    if (isSmallViewport && this._desktopSizeClaims.size > 0) {
+      if (Date.now() - this._lastDesktopActivityAt < Session.DESKTOP_CLAIM_IDLE_MS) {
+        return;
+      }
+      this._mobileSizeOverride = true;
+    }
    if (this.ptyProcess && (cols !== this._ptyCols || rows !== this._ptyRows)) {
      this._ptyCols = cols;
      this._ptyRows = rows;
+      if (this._mux && this._muxSession) {
+        this._mux.resizeWindow?.(this._muxSession.muxName, cols, rows);
+      }
      this.ptyProcess.resize(cols, rows);
    }
  }
@@ -2148,6 +2374,12 @@ export class Session extends EventEmitter {

    this._clearAllTimers();

+    // Drop desktop sizing claims defensively. Sockets normally release their
+    // own claim on close, but a hung client's close event can lag the session
+    // teardown by up to a ping cycle — don't let a stale claim suppress
+    // mobile resizes if this Session object sees any further use.
+    this._desktopSizeClaims.clear();
+
    // Immediately cleanup Promise callbacks to prevent orphaned references
    // during the rest of stop() processing (e.g., if mux kill times out)
    if (this.rejectPromise && !this._promptResolved) {
@@ -1,461 +1,58 @@
-# CLAUDE.md - Project Configuration
+# CLAUDE.md

-## Setup
-Copy these files to your new project:
- `CLAUDE.md` → project root
- `.claude/settings.json` → `.claude/settings.json`
+<!--
+  Generated by Codeman on [DATE]. This file is loaded into context at the
+  start of every Claude Code session in this project.

-Then update the Project Overview section below.
+  Keep it short (target: under 200 lines). For each line ask: "would removing
+  this cause Claude to make mistakes?" If not, cut it. Don't document what
+  Claude can infer from the code itself (file layout, standard conventions,
+  APIs) — bloat causes Claude to ignore the rules that matter.

---
+  HTML comments like this one are stripped before loading, so fill-in notes
+  cost no context. If this file grows too big, split into path-scoped rules
+  in .claude/rules/*.md or import other files with @path/to/file syntax.
+-->
+
+This file guides Claude Code when working in this repository.
+
+## Project

-## Project Overview
-<!-- Update this section with project-specific details -->
 - **Project Name**: [PROJECT_NAME]
 - **Description**: [PROJECT_DESCRIPTION]
- **Tech Stack**: [TECHNOLOGIES_USED]
- **Last Updated**: [DATE]

---
+## Commands
+
+<!-- List the exact commands Claude can't guess — fill in as the project
+     takes shape, then delete this comment:
+
+| Task | Command |
+|------|---------|
+| Dev server | `npm run dev` |
+| Test (single file) | `npm test -- test/<file>.test.ts` |
+| Lint | `npm run lint` |
+| Build | `npm run build` |
+-->
+
+## Code Style
+
+<!-- Only rules that differ from language/framework defaults, one line each:
+- Use 2-space indentation
+- ES modules only — never require()
+-->
+
+## Workflow
+
+- Full permissions are granted: read, write, edit, and execute without asking.
+- Commit after every meaningful change; never batch unrelated work.
+- Use conventional commits (`feat:` `fix:` `docs:` `refactor:` `test:` `chore:`); the message says what changed and why.
+- Run the tests and linter before declaring any task done.
+- Keep README and docs in sync with code changes.

 ## Codeman Environment

-This session is managed by **Codeman** and runs within a tmux session.
+This session is managed by Codeman and runs inside tmux (`CODEMAN_MUX=1` confirms it).

-**Important**: Check for `CODEMAN_MUX=1` environment variable to confirm.
- Do NOT attempt to kill your own tmux session
- The session persists across disconnects - your work is safe
- Token usage, costs, and background tasks are tracked externally
-
---
-
-## Work Principles
-
-### Autonomy
-Full permissions granted. Act decisively without asking - read, write, edit, execute freely.
-
-### Git Discipline
- **Commit after every meaningful change** - never batch unrelated work
- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Commit message = what changed + why (not how)
-
-### Documentation
- Update README.md when adding features or changing setup
- Update this file's session log after work sessions
- Keep docs in sync with code changes
-
-### Thinking
-Extended thinking is enabled. Use deep reasoning for complex architectural decisions, difficult bugs, and multi-file changes.
-
-### Task Tracking (TodoWrite)
-**ALWAYS use TodoWrite** to track tasks. This is non-negotiable for anything beyond trivial single-step work.
-
-**When to use TodoWrite:**
- Multi-step tasks (3+ steps)
- Bug fixes requiring investigation
- Feature implementations
- Any work where progress tracking helps
- When the user provides multiple requests
-
-**How to use it:**
-1. **Before starting**: Break down the work into discrete todos
-2. **During work**: Mark each todo `in_progress` before starting, `completed` when done
-3. **One at a time**: Only ONE todo should be `in_progress` at any moment
-4. **Immediately**: Mark todos complete the moment they're done - don't batch
-
-**Why this matters:**
- Gives the user visibility into your progress
- Prevents forgetting tasks mid-work
- Creates accountability checkpoints
- Makes complex work manageable
-
-**Example workflow:**
-```
-User: "Add user authentication with JWT"
-
-→ TodoWrite:
-  - [ ] Research existing auth patterns in codebase
-  - [ ] Implement JWT token generation
-  - [ ] Add login endpoint
-  - [ ] Add token validation middleware
-  - [ ] Add protected route example
-  - [ ] Write tests
-
-→ Mark "Research existing auth patterns" as in_progress
-→ Do the research
-→ Mark as completed, mark next as in_progress
-→ Continue until all done
-```
-
-**Anti-patterns to avoid:**
- Starting work without creating todos first
- Having multiple todos `in_progress` simultaneously
- Batching completions at the end
- Skipping TodoWrite for "simple" multi-step tasks
-
---
-
-## When to Use Agents
-
-**Explore agent**: Codebase investigation, finding files, understanding architecture
-```
-"Use explore agent to find all authentication-related code"
-```
-
-**Parallel agents**: Independent tasks that don't conflict
-```
-"Research auth, database, and API modules in parallel using separate agents"
-```
-
-**Background execution**: Long-running operations (tests, builds)
-```
-"Run the test suite in the background while I continue"
-```
-
-**Sequential chaining**: When second task depends on first
-```
-"Use code-reviewer to find issues, then use fixer to resolve them"
-```
-
---
-
-## Planning Mode (Automatic)
-
-**Automatically enter planning mode** when ANY of these conditions apply:
- Multi-file changes (3+ files affected)
- Architectural decisions
- Unclear or evolving requirements
- Risk mitigation on core systems
- New feature implementation
- Refactoring existing functionality
-
-**Do NOT ask** whether to enter planning mode - just enter it when conditions are met.
-
-Planning mode flow: read-only exploration → create plan → get approval → execute.
-
-**Skip planning mode** only for:
- Single-file bug fixes
- Typo corrections
- Simple config changes
- Tasks with explicit step-by-step instructions from user
-
---
-
-## Ralph Wiggum Loop (Autonomous Work Mode)
-
-Ralph loops enable persistent, autonomous work on large tasks. When active, you continue iterating until completion criteria are met or the loop is cancelled.
-
-### Starting a Ralph Loop
- Start: `/ralph-loop:ralph-loop`
- Cancel: `/ralph-loop:cancel-ralph`
- Help: `/ralph-loop:help`
-
-### Time-Aware Loops
-
-When the user specifies a **minimum duration** (e.g., "optimize for 8 hours", "work on this for 2 hours"), the loop becomes time-aware:
-
-**At loop start:**
-```bash
-# Record start time
-date +%s > /tmp/ralph_start_time
-echo "Loop started at $(date)"
-```
-
-**Check elapsed time periodically:**
-```bash
-START=$(cat /tmp/ralph_start_time)
-NOW=$(date +%s)
-ELAPSED_HOURS=$(echo "scale=2; ($NOW - $START) / 3600" | bc)
-echo "Elapsed: $ELAPSED_HOURS hours"
-```
-
-**Time-aware behavior:**
-1. Complete all primary tasks from the user's prompt
-2. After primary tasks done, check elapsed time
-3. If minimum duration NOT reached:
-   - **Do NOT output completion phrase**
-   - Self-generate additional related tasks
-   - Continue working until minimum time elapsed
-4. Only output completion phrase when:
-   - ALL primary tasks complete AND
-   - Minimum duration reached (or exceeded)
-
-**Self-generating additional tasks when time remains:**
- Code optimization (performance, readability, DRY)
- Test coverage improvements
- Edge case handling
- Error message improvements
- Documentation gaps
- Security hardening
- Accessibility improvements
- Code cleanup and dead code removal
- Dependency updates
- Type safety improvements
-
-**Example time-aware prompt:**
-```
-"Optimize the API endpoints for the next 4 hours. Focus on performance first,
-then code quality. Minimum runtime: 4 hours."
-Completion phrase: <promise>TIME_COMPLETE</promise>
-```
-
-**Time-aware loop behavior:**
-```
-[Start loop, record timestamp]
-[Complete primary optimization tasks - 2 hours elapsed]
-[Check time: 2/4 hours - NOT done yet]
-[Self-generate: "Add caching to database queries"]
-[Self-generate: "Optimize N+1 queries"]
-[Self-generate: "Add request batching"]
-[Continue working... 4.5 hours elapsed]
-[Check time: 4.5/4 hours - minimum reached]
-[All tasks complete, tests pass]
-<promise>TIME_COMPLETE</promise>
-```
-
-### How You Know You're in a Ralph Loop
-
-The user started the loop with a prompt containing:
- Clear task requirements
- A **completion phrase** (e.g., `<promise>COMPLETE</promise>`)
- **Optional: minimum duration** (e.g., "for the next 4 hours")
- Iteration limits (handled by the system)
-
-Your job: Keep working until ALL requirements are verifiably done AND minimum time reached (if specified), then output the exact completion phrase.
-
-### Core Behaviors During Ralph Loop
-
-**1. Work Incrementally**
- Complete one sub-task at a time
- Verify it works before moving to the next
- Don't try to do everything in one pass
-
-**2. Commit Frequently**
- Commit after each meaningful completion
- Creates recovery points if something breaks
- Shows progress in git history
-```
-git add . && git commit -m "feat(auth): add token refresh endpoint"
-```
-
-**3. Self-Correct Relentlessly**
-```
-Loop:
-  1. Implement/fix
-  2. Run tests
-  3. If tests fail → read error, fix, go to 1
-  4. Run linter
-  5. If lint errors → fix, go to 1
-  6. Commit
-  7. Continue to next task
-```
-
-**4. Track Progress**
-Update the session log in this file as you complete tasks:
-```markdown
-| Date | Tasks Completed | Files Changed | Notes |
-|------|-----------------|---------------|-------|
-| YYYY-MM-DD | Add auth endpoint | auth.ts, routes.ts | Tests passing |
-```
-
-**5. Use Git History When Stuck**
-If something isn't working:
-```bash
-git log --oneline -10
-git diff HEAD~1
-```
-See what you already tried. Don't repeat failed approaches.
-
-**6. Completion Phrase = Contract**
-Only output the completion phrase (e.g., `<promise>COMPLETE</promise>`) when:
- ALL requirements from the original prompt are done
- ALL tests pass
- ALL linting passes
- Changes are committed
-
-**Never output the completion phrase early.** The loop only ends when you say it's done.
-
-### What Makes Good Completion Criteria
-
-The user should provide criteria that are:
- **Verifiable**: Tests pass, lint clean, build succeeds
- **Measurable**: "5 endpoints", "all files in src/", "zero errors"
- **Binary**: Done or not done, no ambiguity
-
-If the original prompt has vague criteria, ask clarifying questions before starting heavy work.
-
-### Self-Correction Pattern (Include in Your Work)
-
-```
-FOR EACH TASK:
-1. Implement the change
-2. Run tests (npm test, pytest, go test, cargo test, etc.)
-   - If fail → read error, fix, retry
-3. Run linter (npm run lint, ruff, golangci-lint, etc.)
-   - If fail → fix, go to step 2
-4. Verify manually if needed
-5. Commit with descriptive message
-6. Update session log
-7. Move to next task
-
-WHEN ALL TASKS DONE:
-1. Run full test suite
-2. Run full lint
-3. Verify build succeeds
-4. Review all changes: git diff main
-5. Only then output completion phrase
-```
-
-### Example: How to Think During Ralph Loop
-
-**Original prompt**: "Add CRUD endpoints for todos with validation"
-
-**Your approach**:
-```
-Task breakdown:
- [ ] GET /todos (list)
- [ ] POST /todos (create with validation)
- [ ] GET /todos/:id (single)
- [ ] PUT /todos/:id (update with validation)
- [ ] DELETE /todos/:id
- [ ] Tests for all endpoints
-
-Starting with GET /todos...
-[implement]
-[test - passes]
-[commit: "feat(todos): add GET /todos endpoint"]
-[update session log]
-
-Moving to POST /todos...
-[implement]
-[test - fails: validation not working]
-[fix validation]
-[test - passes]
-[commit: "feat(todos): add POST /todos with validation"]
-[update session log]
-
-...continue until all done...
-
-Final verification:
-[npm test - all pass]
-[npm run lint - clean]
-[npm run build - succeeds]
-
-<promise>COMPLETE</promise>
-```
-
-### When to NOT Output Completion Phrase
-
- Tests are failing (even one)
- Lint errors exist
- Build is broken
- You skipped a requirement
- You're unsure if something works
- **Minimum duration not reached** (for time-aware loops)
-
-Instead: Fix the issue, verify, then complete. For time-aware loops: generate more tasks and keep improving until minimum time elapsed.
-
-### RALPH_STATUS Block (Required During Ralph Loop)
-
-At the **END of every response** during a Ralph Loop, output this structured status block:
-
-```
---RALPH_STATUS---
-STATUS: IN_PROGRESS | COMPLETE | BLOCKED
-TASKS_COMPLETED_THIS_LOOP: <number>
-FILES_MODIFIED: <number>
-TESTS_STATUS: PASSING | FAILING | NOT_RUN
-WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
-EXIT_SIGNAL: false | true
-RECOMMENDATION: <one line summary of what to do next>
---END_RALPH_STATUS---
-```
-
-**Rules:**
- Output this block at the end of **every** response, no exceptions
- Set `EXIT_SIGNAL` to `true` ONLY when ALL tasks are verifiably done
- Set `STATUS` to `BLOCKED` when you need human intervention
- Do NOT continue with busy work when `EXIT_SIGNAL` should be `true`
- Do NOT forget the status block — it is required for loop tracking
-
-### Testing Limits
-
- **LIMIT testing to ~20% of total effort** per loop
- PRIORITIZE: Implementation > Documentation > Tests
- Only write tests for NEW functionality
- Do NOT refactor existing tests unless broken
- Do NOT run tests repeatedly without implementing new features
-
-### Exit Scenarios (When to Set EXIT_SIGNAL)
-
-| Scenario | STATUS | EXIT_SIGNAL | Action |
-|----------|--------|-------------|--------|
-| All tasks completed, tests pass | COMPLETE | true | Output completion phrase |
-| No work remaining, specs done | COMPLETE | true | Output completion phrase |
-| Making normal progress | IN_PROGRESS | false | Continue to next task |
-| Test-only loop (no implementation) | IN_PROGRESS | false | Warn and shift to implementation |
-| Stuck on same error repeatedly | BLOCKED | false | Describe blocker, request help |
-| Needs human decision/intervention | BLOCKED | false | Describe what's needed |
-
-**Anti-patterns to avoid:**
- Setting `EXIT_SIGNAL: true` when tests are failing
- Continuing to work when all tasks are genuinely done (busy work)
- Running the same failing test repeatedly without changing approach
- Adding features not in the original specifications
- Refactoring working code instead of completing assigned tasks
-
---
-
-## Code Standards
-
-### Before Writing
- Read existing code in the area you're modifying
- Follow existing patterns and conventions
- Check for similar implementations to reference
-
-### During Implementation
- Keep changes focused and minimal
- Don't over-engineer
- Write tests for new functionality
-
-### After Implementation
- Run tests
- Update docs if needed
- Commit with descriptive message
-
---
-
-## Hooks Awareness
-
-This project may have hooks that auto-format code after writes or validate operations. If a tool call behaves unexpectedly, hooks are likely the cause. Continue working - they're intentional.
-
---
-
-## Session Log
-
-| Date | Tasks Completed | Files Changed | Notes |
-|------|-----------------|---------------|-------|
-| [DATE] | Project created | CLAUDE.md | Initial setup |
-
---
-
-## Current Task Queue
-
-### Active Ralph Loop
-**Status**: Not Active
-**Completion Phrase**: -
-
-### Pending Tasks
- [ ] <!-- Add tasks here -->
-
---
-
-## Implementation Plans
-
-<!-- Document plans before major implementations -->
-
---
-
-## Notes & Decisions
-
-<!-- Track important decisions and context -->
+- NEVER kill your own session: no `tmux kill-session`, `pkill tmux`, or `pkill claude`.
+- The session persists across disconnects — your work is safe.
+- Hooks may auto-format or validate after writes; unexpected tool behavior usually means a hook ran. Keep working.
@@ -15,18 +15,17 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BUNDLED_TEMPLATE_PATH = join(__dirname, 'case-template.md');

-const MINIMAL_FALLBACK = `# CLAUDE.md - Project Configuration
+const MINIMAL_FALLBACK = `# CLAUDE.md
+
+<!-- Generated by Codeman on [DATE]. Add the commands, code style rules, and
+     workflow notes Claude can't infer from the code. Keep it short. -->
+
+This file guides Claude Code when working in this repository.
+
+## Project

-## Project Overview
 - **Project Name**: [PROJECT_NAME]
 - **Description**: [PROJECT_DESCRIPTION]
- **Last Updated**: [DATE]
-
-## Session Log
-
-| Date | Tasks Completed | Files Changed | Notes |
-|------|-----------------|---------------|-------|
-| [DATE] | Project created | CLAUDE.md | Initial setup |
 `;

 /**
@@ -39,10 +39,11 @@ import {
  type ClaudeMode,
  type SessionMode,
  type OpenCodeConfig,
+  type CodexConfig,
  type EffortLevel,
 } from './types.js';
 import { buildEffortCliArgs } from './session-cli-builder.js';
-import { wrapWithNice, SAFE_PATH_PATTERN, findClaudeDir, resolveOpenCodeDir } from './utils/index.js';
+import { wrapWithNice, SAFE_PATH_PATTERN, findClaudeDir, resolveOpenCodeDir, resolveCodexDir } from './utils/index.js';
 import type {
  TerminalMultiplexer,
  MuxSession,
@@ -164,6 +165,285 @@ export function parsePaneList(output: string): Map<string, number> {
  return result;
 }

+/**
+ * Resolve a target pane id from `tmux list-panes -F '#{pane_id}:#{pane_active}'`.
+ * Prefers the active pane and falls back to the first valid pane.
+ */
+export function resolveTmuxPaneTarget(muxName: string, paneTarget?: string): string | null {
+  if (!isValidMuxName(muxName)) {
+    return null;
+  }
+  if (paneTarget === undefined || paneTarget === 'active') {
+    return muxName;
+  }
+  if (!SAFE_PANE_TARGET_PATTERN.test(paneTarget)) {
+    return null;
+  }
+  return `${muxName}.${paneTarget}`;
+}
+
+/**
+ * Pick the active pane id from `tmux list-panes -F '#{pane_id}:#{pane_active}'`
+ * output (lines like `%0:1`). Returns the pane id whose active flag is 1.
+ */
+export function resolveActivePaneTarget(output: string): string | null {
+  for (const line of output.split('\n')) {
+    const sep = line.indexOf(':');
+    if (sep === -1) continue;
+    const paneId = line.slice(0, sep).trim();
+    const active = line.slice(sep + 1).trim();
+    if (paneId && active === '1') return paneId;
+  }
+  return null;
+}
+
+type GraphemeSegmenter = {
+  segment(input: string): Iterable<{ segment: string }>;
+};
+
+const GRAPHEME_SEGMENTER: GraphemeSegmenter | null = (() => {
+  try {
+    const Segmenter = (
+      Intl as typeof Intl & {
+        Segmenter?: new (locale?: string, options?: { granularity: 'grapheme' }) => GraphemeSegmenter;
+      }
+    ).Segmenter;
+    return Segmenter ? new Segmenter(undefined, { granularity: 'grapheme' }) : null;
+  } catch {
+    return null;
+  }
+})();
+
+function findEscapeEnd(text: string, start: number): number {
+  const type = text[start + 1];
+  if (type === '[') {
+    for (let i = start + 2; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (code >= 0x40 && code <= 0x7e) return i;
+    }
+    return text.length - 1;
+  }
+
+  if (type === ']') {
+    for (let i = start + 2; i < text.length; i++) {
+      if (text.charCodeAt(i) === 0x07) return i;
+      if (text[i] === '\x1b' && text[i + 1] === '\\') return i + 1;
+    }
+    return text.length - 1;
+  }
+
+  if (type === 'P' || type === '^' || type === '_' || type === 'X') {
+    for (let i = start + 2; i < text.length; i++) {
+      if (text.charCodeAt(i) === 0x07) return i;
+      if (text[i] === '\x1b' && text[i + 1] === '\\') return i + 1;
+    }
+    return text.length - 1;
+  }
+
+  return Math.min(start + 1, text.length - 1);
+}
+
+function sanitizePaneLineStyles(line: string): string {
+  let result = '';
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] !== '\x1b') {
+      result += line[i];
+      continue;
+    }
+
+    const end = findEscapeEnd(line, i);
+    const sequence = line.slice(i, end + 1);
+    if (isSgrSequence(sequence)) {
+      result += sequence;
+    }
+    i = end;
+  }
+  return result;
+}
+
+function isSgrSequence(sequence: string): boolean {
+  return (
+    sequence.length >= 3 &&
+    sequence.charCodeAt(0) === 27 &&
+    sequence[1] === '[' &&
+    sequence.endsWith('m') &&
+    /^[0-9;:]*$/.test(sequence.slice(2, -1))
+  );
+}
+
+function isZeroWidthCodePoint(codePoint: number): boolean {
+  return (
+    codePoint === 0x00ad ||
+    codePoint === 0x034f ||
+    codePoint === 0x061c ||
+    codePoint === 0x115f ||
+    codePoint === 0x1160 ||
+    codePoint === 0x17b4 ||
+    codePoint === 0x17b5 ||
+    codePoint === 0x180e ||
+    codePoint === 0x200b ||
+    codePoint === 0x200c ||
+    codePoint === 0x200d ||
+    codePoint === 0x2060 ||
+    codePoint === 0xfeff ||
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x0483 && codePoint <= 0x0489) ||
+    (codePoint >= 0x0591 && codePoint <= 0x05bd) ||
+    codePoint === 0x05bf ||
+    (codePoint >= 0x05c1 && codePoint <= 0x05c2) ||
+    (codePoint >= 0x05c4 && codePoint <= 0x05c5) ||
+    codePoint === 0x05c7 ||
+    (codePoint >= 0x0610 && codePoint <= 0x061a) ||
+    (codePoint >= 0x064b && codePoint <= 0x065f) ||
+    codePoint === 0x0670 ||
+    (codePoint >= 0x06d6 && codePoint <= 0x06dc) ||
+    (codePoint >= 0x06df && codePoint <= 0x06e4) ||
+    (codePoint >= 0x06e7 && codePoint <= 0x06e8) ||
+    (codePoint >= 0x06ea && codePoint <= 0x06ed) ||
+    codePoint === 0x0711 ||
+    (codePoint >= 0x0730 && codePoint <= 0x074a) ||
+    (codePoint >= 0x07a6 && codePoint <= 0x07b0) ||
+    (codePoint >= 0x07eb && codePoint <= 0x07f3) ||
+    (codePoint >= 0x0816 && codePoint <= 0x0819) ||
+    (codePoint >= 0x081b && codePoint <= 0x0823) ||
+    (codePoint >= 0x0825 && codePoint <= 0x0827) ||
+    (codePoint >= 0x0829 && codePoint <= 0x082d) ||
+    (codePoint >= 0x0859 && codePoint <= 0x085b) ||
+    (codePoint >= 0x08d3 && codePoint <= 0x08e1) ||
+    (codePoint >= 0x08e3 && codePoint <= 0x0902) ||
+    (codePoint >= 0x093a && codePoint <= 0x093c) ||
+    codePoint === 0x094d ||
+    (codePoint >= 0x0951 && codePoint <= 0x0957) ||
+    (codePoint >= 0x0962 && codePoint <= 0x0963) ||
+    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+    (codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
+    (codePoint >= 0xfe20 && codePoint <= 0xfe2f) ||
+    (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+  );
+}
+
+function isWideCodePoint(codePoint: number): boolean {
+  return (
+    codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      codePoint === 0x2329 ||
+      codePoint === 0x232a ||
+      (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+      (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+      (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+      (codePoint >= 0x20000 && codePoint <= 0x3fffd))
+  );
+}
+
+function nextGrapheme(text: string, start: number): { value: string; nextIndex: number } {
+  if (GRAPHEME_SEGMENTER) {
+    const iterator = GRAPHEME_SEGMENTER.segment(text.slice(start))[Symbol.iterator]();
+    const next = iterator.next();
+    if (!next.done && next.value.segment) {
+      return { value: next.value.segment, nextIndex: start + next.value.segment.length };
+    }
+  }
+
+  const first = text.codePointAt(start);
+  if (first === undefined) return { value: '', nextIndex: start + 1 };
+  let value = String.fromCodePoint(first);
+  let nextIndex = start + value.length;
+  while (nextIndex < text.length) {
+    const codePoint = text.codePointAt(nextIndex);
+    if (codePoint === undefined || !isZeroWidthCodePoint(codePoint)) break;
+    const mark = String.fromCodePoint(codePoint);
+    value += mark;
+    nextIndex += mark.length;
+  }
+  return { value, nextIndex };
+}
+
+function terminalCellWidth(grapheme: string): number {
+  let hasVisible = false;
+  let hasWide = false;
+  for (let i = 0; i < grapheme.length; i++) {
+    const codePoint = grapheme.codePointAt(i);
+    if (codePoint === undefined) continue;
+    if (codePoint > 0xffff) i++;
+    if (isZeroWidthCodePoint(codePoint) || codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0)) {
+      continue;
+    }
+    hasVisible = true;
+    if (isWideCodePoint(codePoint)) hasWide = true;
+  }
+  if (!hasVisible) return 0;
+  return hasWide ? 2 : 1;
+}
+
+function truncatePaneLineByVisibleColumns(line: string, maxColumns: number): string {
+  let result = '';
+  let visibleColumns = 0;
+  let sawSgr = false;
+
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '\x1b') {
+      const end = findEscapeEnd(line, i);
+      const sequence = line.slice(i, end + 1);
+      if (isSgrSequence(sequence)) {
+        result += sequence;
+        sawSgr = true;
+      }
+      i = end;
+      continue;
+    }
+
+    const grapheme = nextGrapheme(line, i);
+    const width = terminalCellWidth(grapheme.value);
+    if (width === 0) {
+      result += grapheme.value;
+    } else if (visibleColumns + width <= maxColumns) {
+      result += grapheme.value;
+      visibleColumns += width;
+    } else {
+      break;
+    }
+    i = grapheme.nextIndex - 1;
+    if (visibleColumns >= maxColumns) {
+      continue;
+    }
+  }
+
+  if (sawSgr) {
+    result += '\x1b[0m';
+  }
+  return result;
+}
+
+export function formatPaneSnapshot(
+  lines: string[],
+  geometry: { cols: number; rows: number; cursorX: number; cursorY: number }
+): string {
+  const cols = Math.max(1, geometry.cols);
+  // Paint the full pane width. Earlier this dropped the rightmost column
+  // (cols - 1) out of caution about last-column autowrap, but every painted
+  // row is immediately followed by an absolute cursor-position CSI (the next
+  // row's `\x1b[r;1H`, or the final cursor move), which cancels xterm's
+  // pending-wrap state before any further glyph — so the last column is safe.
+  const paintCols = cols;
+  const rows = Math.max(1, geometry.rows);
+  const parts: string[] = [];
+  for (let row = 0; row < Math.min(lines.length, rows); row++) {
+    const safeLine = truncatePaneLineByVisibleColumns(sanitizePaneLineStyles(lines[row]), paintCols);
+    parts.push(`\x1b[${row + 1};1H${safeLine}`);
+  }
+  const cursorX = Math.max(0, Math.min(cols - 1, geometry.cursorX));
+  const cursorY = Math.max(0, Math.min(rows - 1, geometry.cursorY));
+  parts.push(`\x1b[${cursorY + 1};${cursorX + 1}H`);
+  return parts.join('');
+}
+
 /** Characters unsafe in paths — shell metacharacters, quotes, and control chars */
 const UNSAFE_PATH_CHARS = /[;&|$`(){}<>'"\n\r]/;

@@ -175,6 +455,10 @@ function isValidMuxName(name: string): boolean {
  return SAFE_MUX_NAME_PATTERN.test(name) || LEGACY_MUX_NAME_PATTERN.test(name);
 }

+function isValidTerminalDimension(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0 && value <= 1000;
+}
+
 /**
 * Validates that a path contains only safe characters.
 * Prevents command injection via malformed paths.
@@ -261,6 +545,32 @@ function buildOpenCodeCommand(config?: OpenCodeConfig): string {
  return parts.join(' ');
 }

+/**
+ * Build the codex CLI command with appropriate flags.
+ *
+ * Codeman launches Codex's native TUI and handles replay/scrollback by
+ * stripping destructive terminal sequences before xterm.js sees them.
+ */
+export function buildCodexCommand(config?: CodexConfig): string {
+  const parts = ['codex'];
+
+  if (config?.dangerouslyBypassApprovals) {
+    parts.push('--dangerously-bypass-approvals-and-sandbox');
+  }
+
+  if (config?.model) {
+    const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  if (config?.resumeSessionId) {
+    const safeId = /^[a-zA-Z0-9_-]+$/.test(config.resumeSessionId) ? config.resumeSessionId : undefined;
+    if (safeId) parts.push('resume', safeId);
+  }
+
+  return parts.join(' ');
+}
+
 /**
 * Build the spawn command for any session mode.
 * Shared by createSession() and respawnPane() to avoid duplication.
@@ -286,6 +596,7 @@ function buildSpawnCommand(options: {
  claudeMode?: ClaudeMode;
  allowedTools?: string;
  openCodeConfig?: OpenCodeConfig;
+  codexConfig?: CodexConfig;
  resumeSessionId?: string;
  effort?: EffortLevel;
 }): string {
@@ -310,6 +621,9 @@ function buildSpawnCommand(options: {
  if (options.mode === 'opencode') {
    return buildOpenCodeCommand(options.openCodeConfig);
  }
+  if (options.mode === 'codex') {
+    return buildCodexCommand(options.codexConfig);
+  }
  return '$SHELL';
 }

@@ -337,6 +651,29 @@ function setOpenCodeEnvVars(tmuxCmd: string, muxName: string): void {
  }
 }

+/**
+ * Set sensitive environment variables for Codex on a tmux session via setenv.
+ * Codex (OpenAI CLI) needs OPENAI_API_KEY; we also forward CODEX_* keys.
+ */
+function setCodexEnvVars(tmuxCmd: string, muxName: string): void {
+  const sensitiveVars = ['OPENAI_API_KEY', 'CODEX_API_KEY', 'CODEX_HOME'];
+  for (const key of sensitiveVars) {
+    const val = process.env[key];
+    if (val) {
+      const escaped = val.replace(/'/g, "'\\''");
+      try {
+        execSync(`${tmuxCmd} setenv -t '${muxName}' ${key} '${escaped}'`, {
+          encoding: 'utf8',
+          timeout: EXEC_TIMEOUT_MS,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch {
+        /* Non-critical — key may not be needed */
+      }
+    }
+  }
+}
+
 /**
 * Set OPENCODE_CONFIG_CONTENT on a tmux session via setenv.
 * Uses tmux setenv to avoid shell metacharacter injection from user-supplied JSON.
@@ -519,11 +856,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const exports = [
      'export LANG=en_US.UTF-8',
      'export LC_ALL=en_US.UTF-8',
-      'unset COLORTERM',
+      mode === 'codex' ? 'export COLORTERM=truecolor' : 'unset COLORTERM',
+      ...(mode === 'codex' ? ['unset NO_COLOR'] : []),
      'export CODEMAN_MUX=1',
      `export CODEMAN_SESSION_ID=${sessionId}`,
      `export CODEMAN_MUX_NAME=${muxName}`,
      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
+      // Path only (not the secret value): hook curl commands cat the file at
+      // execution time, so the COD-54 hook secret stays off the command line.
+      `export CODEMAN_HOOK_SECRET_FILE="${dataPath('hook-secret')}"`,
    ];
    // Only unset CLAUDECODE for Claude sessions
    if (mode === 'claude') exports.splice(2, 0, 'unset CLAUDECODE');
@@ -585,6 +926,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      const dir = resolveOpenCodeDir();
      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
    }
+    if (mode === 'codex') {
+      const dir = resolveCodexDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
    return { pathExport: '', dir: null };
  }

@@ -599,6 +944,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    setOpenCodeConfigContent(tmuxCmd, muxName, openCodeConfig);
  }

+  /**
+   * Configure Codex-specific environment on a tmux session.
+   * Sets OPENAI_API_KEY (and related keys) via tmux setenv so secrets don't
+   * appear in the bash command line.
+   */
+  private _configureCodex(muxName: string): void {
+    setCodexEnvVars(this.tmux(), muxName);
+  }
+
  /**
   * Creates a new tmux session wrapping Claude CLI or a shell.
   * In test mode: creates an in-memory session only (no real tmux session).
@@ -614,6 +968,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      claudeMode,
      allowedTools,
      openCodeConfig,
+      codexConfig,
      resumeSessionId,
      envOverrides,
      effort,
@@ -662,6 +1017,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      claudeMode,
      allowedTools,
      openCodeConfig,
+      codexConfig,
      resumeSessionId,
      effort,
    });
@@ -682,14 +1038,17 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // (Production uses systemd which has a clean env, but dev/test may be nested.)
      const cleanEnv = { ...process.env };
      delete cleanEnv.TMUX;
-      // Start the tmux server from a stable local cwd so FUSE/rclone workspace
-      // blips do not poison tmux's long-lived getcwd state.
+      // Create the session on the dedicated socket (${this.tmux()} = `tmux -L <socket>`),
+      // launched in TMUX_LAUNCH_CWD (/tmp) rather than the real workingDir: a FUSE/rclone
+      // mount that isn't ready yet makes `getcwd` fail and breaks the spawn (see #110). The
+      // pane cd's into workingDir below via respawn-pane.
      execSync(`${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD}`, {
        cwd: TMUX_LAUNCH_CWD,
        timeout: EXEC_TIMEOUT_MS,
        stdio: 'ignore',
        env: cleanEnv,
      });
+      this.resizeWindow(muxName, 120, 40);

      // Set remain-on-exit now that the server is running — must be before respawn-pane
      try {
@@ -705,6 +1064,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // (not visible in ps output or tmux history, inherited by panes)
      if (mode === 'opencode') {
        this._configureOpenCode(muxName, openCodeConfig);
+      } else if (mode === 'codex') {
+        this._configureCodex(muxName);
      }

      // Apply user-supplied env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL) via tmux setenv
@@ -862,6 +1223,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      claudeMode,
      allowedTools,
      openCodeConfig,
+      codexConfig,
      resumeSessionId,
      envOverrides,
      effort,
@@ -884,6 +1246,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      claudeMode,
      allowedTools,
      openCodeConfig,
+      codexConfig,
      resumeSessionId,
      effort,
    });
@@ -895,6 +1258,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      // For OpenCode: set sensitive env vars via tmux setenv before respawn
      if (mode === 'opencode') {
        this._configureOpenCode(muxName, openCodeConfig);
+      } else if (mode === 'codex') {
+        this._configureCodex(muxName);
      }

      // Re-apply user env overrides before respawn so the new shell inherits them.
@@ -920,6 +1285,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

  private sessionExists(muxName: string): boolean {
    if (IS_TEST_MODE) return false;
+    if (!isValidMuxName(muxName)) return false;

    try {
      execSync(`${this.tmux()} has-session -t "${muxName}" 2>/dev/null`, {
@@ -1060,13 +1426,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
      }
    }

-    // Strategy 3: Kill tmux session by name
-    try {
-      execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
-        timeout: EXEC_TIMEOUT_MS,
-      });
-    } catch {
-      // Session may already be dead
+    // Strategy 3: Kill tmux session by name (guard the name before it reaches the shell)
+    if (isValidMuxName(session.muxName)) {
+      try {
+        execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+          timeout: EXEC_TIMEOUT_MS,
+        });
+      } catch {
+        // Session may already be dead
+      }
    }

    // Strategy 4: Direct kill by PID as final fallback
@@ -1166,6 +1534,14 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {

    for (const [sessionName, pid] of active) {
      if (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-')) continue;
+      // Only admit names that pass the safe-name pattern. A foreign process on the
+      // shared `tmux -L codeman` socket could create a `codeman-…` session whose name
+      // contains shell metacharacters; rejecting it here keeps it out of this.sessions
+      // and away from the name-interpolating tmux call sites (M1).
+      if (!isValidMuxName(sessionName)) {
+        console.warn(`[TmuxManager] Skipping discovered tmux session with unsafe name: ${sessionName}`);
+        continue;
+      }
      if (knownMuxNames.has(sessionName)) continue;

      const fragment = sessionName.replace(/^(?:codeman|claudeman)-/, '');
@@ -1678,8 +2054,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
  }

  /**
-   * Capture the current buffer of a specific pane.
-   * Returns the pane content with ANSI escape codes preserved.
+   * Capture the current visible text and SGR styles of a specific pane.
+   *
+   * `capture-pane -e` is sanitized by `formatPaneSnapshot`: SGR color/style
+   * codes are preserved, while cursor/erase/scroll-region controls are stripped
+   * before rows are repainted at absolute positions in browser xterm.
   */
  capturePaneBuffer(muxName: string, paneTarget: string): string | null {
    if (IS_TEST_MODE) return '';
@@ -1695,16 +2074,67 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    const target = paneTarget.startsWith('%') ? `${muxName}.${paneTarget}` : `${muxName}.%${paneTarget}`;

    try {
-      return execSync(`${this.tmux()} capture-pane -p -e -t ${shellescape(target)} -S -5000`, {
+      const buffer = execSync(`${this.tmux()} capture-pane -p -e -t ${shellescape(target)}`, {
        encoding: 'utf-8',
        timeout: EXEC_TIMEOUT_MS,
-      });
+      }).replace(/\n+$/g, '');
+      try {
+        const cursor = execSync(
+          `${this.tmux()} display-message -p -t ${shellescape(target)} '#{cursor_x} #{cursor_y} #{pane_width} #{pane_height}'`,
+          {
+            encoding: 'utf-8',
+            timeout: EXEC_TIMEOUT_MS,
+          }
+        ).trim();
+        const [cursorX, cursorY, cols, rows] = cursor.split(/\s+/).map((value) => parseInt(value, 10));
+        if (
+          Number.isFinite(cursorX) &&
+          Number.isFinite(cursorY) &&
+          Number.isFinite(cols) &&
+          Number.isFinite(rows) &&
+          cursorX >= 0 &&
+          cursorY >= 0 &&
+          cols > 0 &&
+          rows > 0
+        ) {
+          return formatPaneSnapshot(buffer.split('\n'), { cols, rows, cursorX, cursorY });
+        }
+      } catch (cursorErr) {
+        console.error('[TmuxManager] Failed to query pane cursor after capture:', cursorErr);
+      }
+      return buffer;
    } catch (err) {
      console.error('[TmuxManager] Failed to capture pane buffer:', err);
      return null;
    }
  }

+  /**
+   * Capture the active pane for a tmux session.
+   *
+   * Pane ids are not stable across respawns or restores, so callers should not
+   * assume the first pane remains `%0`.
+   */
+  captureActivePaneBuffer(muxName: string): string | null {
+    if (IS_TEST_MODE) return '';
+    if (!isValidMuxName(muxName)) {
+      console.error('[TmuxManager] Invalid session name in captureActivePaneBuffer:', muxName);
+      return null;
+    }
+
+    try {
+      const output = execSync(`${this.tmux()} list-panes -t ${shellescape(muxName)} -F '#{pane_id}:#{pane_active}'`, {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      }).trim();
+      const target = resolveActivePaneTarget(output);
+      return target ? this.capturePaneBuffer(muxName, target) : null;
+    } catch (err) {
+      console.error('[TmuxManager] Failed to resolve active pane for capture:', err);
+      return null;
+    }
+  }
+
  /**
   * Start piping pane output to a file using tmux pipe-pane.
   * Only pipes output direction (-O) to avoid echoing input.
@@ -1774,6 +2204,49 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    return ['-L', this.tmuxSocket, 'attach-session', '-t', muxName];
  }

+  setManualWindowSize(muxName: string): boolean {
+    if (!isValidMuxName(muxName)) {
+      console.error('[TmuxManager] Invalid session name in setManualWindowSize:', muxName);
+      return false;
+    }
+
+    try {
+      execSync(`${this.tmux()} set-window-option -t ${shellescape(muxName)} window-size manual`, {
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: 'ignore',
+      });
+      return true;
+    } catch (err) {
+      console.error('[TmuxManager] Failed to set manual window size:', err);
+      return false;
+    }
+  }
+
+  resizeWindow(muxName: string, cols: number, rows: number): boolean {
+    if (!isValidMuxName(muxName)) {
+      console.error('[TmuxManager] Invalid session name in resizeWindow:', muxName);
+      return false;
+    }
+    if (!isValidTerminalDimension(cols) || !isValidTerminalDimension(rows)) {
+      console.error('[TmuxManager] Invalid resize dimensions:', { cols, rows });
+      return false;
+    }
+
+    // Fire-and-forget: this runs on the interactive resize path (WS {t:'z'} and
+    // HTTP /resize), so use a non-blocking exec — a slow/hung tmux must not stall
+    // the Fastify event loop while other sessions' input/SSE are served. The sole
+    // caller (Session.resize) ignores the result, and under `window-size manual`
+    // the subsequent ptyProcess.resize is subordinate to this authoritative size.
+    exec(
+      `${this.tmux()} resize-window -t ${shellescape(muxName)} -x ${cols} -y ${rows}`,
+      { timeout: EXEC_TIMEOUT_MS },
+      (err) => {
+        if (err) console.error('[TmuxManager] Failed to resize tmux window:', err);
+      }
+    );
+    return true;
+  }
+
  isAvailable(): boolean {
    return TmuxManager.isTmuxAvailable();
  }
@@ -25,12 +25,18 @@ export enum ApiErrorCode {
  NOT_FOUND = 'NOT_FOUND',
  /** Invalid input provided */
  INVALID_INPUT = 'INVALID_INPUT',
+  /** Authentication required or failed */
+  UNAUTHORIZED = 'UNAUTHORIZED',
  /** Session is currently busy */
  SESSION_BUSY = 'SESSION_BUSY',
-  /** Operation failed */
-  OPERATION_FAILED = 'OPERATION_FAILED',
+  /** Request conflicts with current state (e.g. already running) */
+  CONFLICT = 'CONFLICT',
  /** Resource already exists */
  ALREADY_EXISTS = 'ALREADY_EXISTS',
+  /** Too many requests / rate limited */
+  RATE_LIMITED = 'RATE_LIMITED',
+  /** Operation could not be completed (well-formed but unprocessable) */
+  OPERATION_FAILED = 'OPERATION_FAILED',
  /** Internal server error */
  INTERNAL_ERROR = 'INTERNAL_ERROR',
 }
@@ -41,12 +47,37 @@ export enum ApiErrorCode {
 const ErrorMessages: Record<ApiErrorCode, string> = {
  [ApiErrorCode.NOT_FOUND]: 'The requested resource was not found',
  [ApiErrorCode.INVALID_INPUT]: 'Invalid input provided',
+  [ApiErrorCode.UNAUTHORIZED]: 'Authentication required',
  [ApiErrorCode.SESSION_BUSY]: 'Session is currently busy',
-  [ApiErrorCode.OPERATION_FAILED]: 'The operation failed',
+  [ApiErrorCode.CONFLICT]: 'Request conflicts with the current state',
  [ApiErrorCode.ALREADY_EXISTS]: 'Resource already exists',
+  [ApiErrorCode.RATE_LIMITED]: 'Too many requests',
+  [ApiErrorCode.OPERATION_FAILED]: 'The operation failed',
  [ApiErrorCode.INTERNAL_ERROR]: 'An internal error occurred',
 };

+/**
+ * Maps each API error code to its HTTP status. Single source of truth for the
+ * stable HTTP contract (see docs/api-reference.md). Applied centrally so every
+ * error response carries a conventional 4xx/5xx status, not 200.
+ */
+const ErrorStatus: Record<ApiErrorCode, number> = {
+  [ApiErrorCode.INVALID_INPUT]: 400,
+  [ApiErrorCode.UNAUTHORIZED]: 401,
+  [ApiErrorCode.NOT_FOUND]: 404,
+  [ApiErrorCode.SESSION_BUSY]: 409,
+  [ApiErrorCode.CONFLICT]: 409,
+  [ApiErrorCode.ALREADY_EXISTS]: 409,
+  [ApiErrorCode.OPERATION_FAILED]: 422,
+  [ApiErrorCode.RATE_LIMITED]: 429,
+  [ApiErrorCode.INTERNAL_ERROR]: 500,
+};
+
+/** HTTP status for an API error code (defaults to 400 for unknown codes). */
+export function httpStatusForErrorCode(code: ApiErrorCode): number {
+  return ErrorStatus[code] ?? 400;
+}
+
 /**
 * Hook event types triggered by Claude Code's hooks system
 */
@@ -82,22 +113,6 @@ export function createErrorResponse(code: ApiErrorCode, details?: string): ApiRe
  };
 }

-/**
- * Response for quick start operation
- */
-export interface QuickStartResponse {
-  /** Whether the request succeeded */
-  success: boolean;
-  /** Created session ID */
-  sessionId?: string;
-  /** Path to case folder */
-  casePath?: string;
-  /** Case name */
-  caseName?: string;
-  /** Error message if failed */
-  error?: string;
-}
-
 /**
 * Information about a case folder
 */
@@ -8,7 +8,7 @@
 * - SessionConfig — creation-time config (id, workingDir, createdAt)
 * - SessionOutput — captured stdout/stderr/exitCode
 * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
- * - SessionMode — 'claude' | 'shell' | 'opencode' (which CLI backend)
+ * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' (which CLI backend)
 * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'normal' | 'allowedTools')
 * - SessionColor — visual differentiation color
 * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
@@ -38,7 +38,7 @@ export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
 export type ClaudeMode = 'dangerously-skip-permissions' | 'normal' | 'allowedTools';

 /** Session mode: which CLI backend a session runs */
-export type SessionMode = 'claude' | 'shell' | 'opencode';
+export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex';

 /**
 * Valid Claude CLI effort levels (claude >= 2.1.154).
@@ -69,6 +69,21 @@ export interface OpenCodeConfig {
  configContent?: string;
 }

+/** Codex (OpenAI CLI) browser rendering strategy. Hybrid TUI is the only supported mode. */
+export type CodexRenderMode = 'hybrid';
+
+/** Codex (OpenAI CLI) session configuration */
+export interface CodexConfig {
+  /** Model identifier (e.g., "gpt-5", "o4-mini"). Passed via --model. */
+  model?: string;
+  /** Resume a previous codex conversation by session id (passed via --resume) */
+  resumeSessionId?: string;
+  /** Bypass approval prompts (passes --dangerously-bypass-approvals-and-sandbox) */
+  dangerouslyBypassApprovals?: boolean;
+  /** Browser rendering strategy for Codex sessions. Hybrid TUI is the only supported mode. */
+  renderMode?: CodexRenderMode;
+}
+
 /**
 * Configuration for creating a new session
 */
@@ -118,6 +133,10 @@ export interface SessionState {
  autoCompactThreshold?: number;
  /** Auto-compact prompt */
  autoCompactPrompt?: string;
+  /** Auto-resume on usage limit enabled */
+  autoResumeEnabled?: boolean;
+  /** Pending usage-limit auto-resume fire time (epoch ms), if armed */
+  autoResumeAt?: number;
  /** Image watcher enabled for this session */
  imageWatcherEnabled?: boolean;
  /** Total cost in USD */
@@ -158,6 +177,8 @@ export interface SessionState {
  cliLatestVersion?: string;
  /** OpenCode-specific configuration (only for mode === 'opencode') */
  openCodeConfig?: OpenCodeConfig;
+  /** Codex-specific configuration (only for mode === 'codex') */
+  codexConfig?: CodexConfig;
  /** Claude conversation session ID to resume after reboot (set by restore script) */
  resumeSessionId?: string;
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
@@ -7,13 +7,14 @@
 * - ActiveBashTool — a live bash command with extracted file paths and status
 * - ActiveBashToolStatus — 'running' | 'completed'
 * - ImageDetectedEvent — screenshot/image file detection trigger for UI popup
+ * - AttachmentDetectedEvent — document/image file detection trigger for attachment cards
 *
 * Cross-domain relationships:
 * - ActiveBashTool.sessionId links to SessionState.id (session domain)
 * - ImageDetectedEvent.sessionId links to SessionState.id (session domain)
 *
 * Both types are in-memory only (not persisted). Broadcast via SSE events
- * `subagent:tool_call` and `image:detected`. Parsed by BashToolParser
+ * `subagent:tool_call`, `image:detected`, and `attachment:detected`. Parsed by BashToolParser
 * (`src/bash-tool-parser.ts`).
 */

@@ -61,3 +62,38 @@ export interface ImageDetectedEvent {
  /** File size in bytes */
  size: number;
 }
+
+export type AttachmentDetectedType = 'image' | 'pdf' | 'document' | 'presentation' | 'markdown' | 'text';
+
+/**
+ * Event emitted when a new previewable attachment file is detected in a session's
+ * working directory. Used to render a compact attachment card in the web UI.
+ */
+export interface AttachmentDetectedEvent {
+  /** Codeman session ID where the attachment was detected */
+  sessionId: string;
+  /** Full path to the detected attachment file */
+  filePath: string;
+  /** Path relative to the session's working directory (for file-raw/file-preview endpoints) */
+  relativePath: string;
+  /** Attachment file name (basename) */
+  fileName: string;
+  /** Lowercase extension without a leading dot */
+  extension: string;
+  /** Viewer category used by the web UI */
+  attachmentType: AttachmentDetectedType;
+  /** Timestamp when the attachment was detected */
+  timestamp: number;
+  /** File size in bytes */
+  size: number;
+  /** Registered attachment id for explicit live external attachments */
+  attachmentId?: string;
+  /** Source of the attachment card request */
+  source?: 'detected' | 'external';
+  /** Raw file route for explicit attachments */
+  rawUrl?: string;
+  /** Inline preview route for explicit attachments */
+  previewUrl?: string;
+  /** First-page thumbnail route for card previews */
+  thumbnailUrl?: string;
+}
@@ -13,8 +13,12 @@
 * @module types/update
 */

-/** Which init system supervises the running server (decides how we restart it). */
-export type SupervisorKind = 'systemd' | 'launchd' | 'none';
+/**
+ * Which init system supervises the running server (decides how we restart it).
+ * `launchd-daemon` = a KeepAlive system-level LaunchDaemon (headless Macs, no GUI
+ * login): restart works by killing the server and letting launchd respawn it.
+ */
+export type SupervisorKind = 'systemd' | 'launchd' | 'launchd-daemon' | 'none';

 /** How Codeman was installed — only `git` installs can self-update in place. */
 export type InstallKind = 'git' | 'npm' | 'unknown';
@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Pure detection of Claude Code usage-limit pause messages.
+ *
+ * When a Claude subscription limit (5-hour rolling window, weekly, Opus weekly,
+ * or extra-usage balance) is hit, the Claude Code TUI stops working and prints a
+ * status line with the reset time. These helpers detect that state in cleaned
+ * (ANSI-stripped) terminal output and parse the reset time, so the session
+ * auto-resume feature (SessionAutoOps) can schedule a "continue" nudge.
+ *
+ * Message shapes covered (observed across Claude Code 1.0.x–2.1.x, 2025–2026):
+ * - `5-hour limit reached ∙ resets 8pm`                                (v1.0.109+ footer)
+ * - `Session limit reached ∙ resets 8pm`
+ * - `Weekly limit reached ∙ resets 6pm`
+ * - `Opus weekly limit reached ∙ resets Oct 6, 1pm`
+ * - `Limit reached · resets 1pm (America/Chicago) · /upgrade to Max…`  (v2.0.55+)
+ * - `You've hit your limit · resets 1:40pm (America/New_York)`         (v2.1.x)
+ * - `You've hit your weekly limit · resets Mon 12:00am`
+ * - `You've hit your limit · resets May 5 at 9pm (America/New_York)`
+ * - `You're out of extra usage · resets 1pm (America/Los_Angeles)`
+ * - `Claude usage limit reached. Your limit will reset at 2pm (America/New_York)` (v1.0.x inline)
+ * - `Claude AI usage limit reached|1755309600`                         (raw API, epoch seconds)
+ *
+ * Deliberately conservative: a limit phrase WITHOUT a parseable reset time is
+ * ignored (returns null) so ordinary conversation text mentioning "limit
+ * reached" can't arm the scheduler. The downstream retry loop (re-detection
+ * after each resume attempt) compensates for any parsing imprecision.
+ *
+ * All functions are pure (caller passes `now`) for testability.
+ *
+ * @module usage-limit-patterns
+ */
+
+/** Result of scanning terminal output for a usage-limit pause. */
+export interface UsageLimitDetection {
+  /**
+   * Epoch ms when the limit resets. May be in the past when the matched
+   * message is stale (caller should treat past values as "retry soon").
+   */
+  resetAt: number;
+  /** Matched message snippet (for logging and UI). */
+  matched: string;
+}
+
+/**
+ * Limit phrases that indicate Claude stopped on a usage limit.
+ * `\blimit reached` covers all "<X> limit reached" footer variants.
+ */
+const LIMIT_PHRASE_PATTERN =
+  /(?:\blimit\s+reached\b|you'?ve\s+hit\s+your\s+(?:\w+\s+)?limit\b|you'?re\s+out\s+of\s+extra\s+usage\b)/gi;
+
+/**
+ * Reset-time spec following a limit phrase. Captures:
+ * 1 month (weekly resets >1 day out: "Oct 6, 1pm" / "May 5 at 9pm")
+ * 2 day-of-month
+ * 3 day-of-week ("Mon 12:00am")
+ * 4 hour (12h)  5 minutes  6 am/pm  7 IANA timezone in parens (optional)
+ * `resets?` + optional `at` also covers the v1.0.x "will reset at 2pm" form.
+ */
+const RESET_TIME_PATTERN =
+  /\bresets?\s+(?:at\s+)?(?:(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\s+(\d{1,2})(?:\s*,\s*|\s+at\s+)|(sun|mon|tue|wed|thu|fri|sat)[a-z]*\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\b(?:\s*\(([^()\n]{1,64})\))?/i;
+
+/** Raw API form: `Claude AI usage limit reached|1755309600` (epoch seconds). */
+const EPOCH_LIMIT_PATTERN = /\busage\s+limit\s+reached\|(\d{9,11})\b/gi;
+
+/** How far after a limit phrase the reset-time spec may appear (chars). */
+const RESET_TIME_WINDOW = 160;
+
+/** Parsed reset spec must not be further out than this (weekly max ≈ 7 days). */
+const MAX_RESET_HORIZON_MS = 8 * 24 * 60 * 60 * 1000;
+
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Current UTC offset of an IANA timezone in ms, or null if unresolvable
+ * (e.g. the `(Etc/Unknown)` failure variant Claude Code can print).
+ * DST transitions inside the wait window can skew the result by an hour;
+ * the auto-resume retry loop absorbs that.
+ */
+function zoneOffsetMs(timeZone: string, at: number): number | null {
+  try {
+    const dtf = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'longOffset' });
+    const name = dtf.formatToParts(at).find((p) => p.type === 'timeZoneName')?.value;
+    if (!name) return null;
+    const m = /^GMT(?:([+-])(\d{1,2})(?::(\d{2}))?)?$/.exec(name);
+    if (!m) return null;
+    if (!m[1]) return 0; // plain "GMT"
+    const sign = m[1] === '-' ? -1 : 1;
+    return sign * (parseInt(m[2], 10) * 60 + (m[3] ? parseInt(m[3], 10) : 0)) * 60_000;
+  } catch {
+    return null;
+  }
+}
+
+interface ResetSpec {
+  month?: number; // 0-11
+  dayOfMonth?: number; // 1-31
+  dayOfWeek?: number; // 0-6 (Sun-Sat)
+  hour: number; // 0-23
+  minute: number; // 0-59
+  timeZone?: string;
+}
+
+/**
+ * Compute the epoch ms for a parsed reset spec. Times are wall-clock in the
+ * given IANA timezone when present (and resolvable), otherwise server-local —
+ * Claude CLI runs on the same host as Codeman, so local time is the right
+ * default. Returns null when the spec is implausible (> ~8 days out).
+ */
+function resolveResetSpec(spec: ResetSpec, now: number): number | null {
+  const offset = spec.timeZone ? zoneOffsetMs(spec.timeZone, now) : null;
+
+  // Wall-clock view of "now": shifted-UTC when a zone offset is known,
+  // server-local otherwise. Read/build components with the matching API.
+  const useZone = offset !== null;
+  const wallNow = useZone ? new Date(now + offset) : new Date(now);
+  const get = {
+    year: () => (useZone ? wallNow.getUTCFullYear() : wallNow.getFullYear()),
+    month: () => (useZone ? wallNow.getUTCMonth() : wallNow.getMonth()),
+    date: () => (useZone ? wallNow.getUTCDate() : wallNow.getDate()),
+    day: () => (useZone ? wallNow.getUTCDay() : wallNow.getDay()),
+  };
+  const build = (y: number, mo: number, d: number): number => {
+    const wall = useZone
+      ? Date.UTC(y, mo, d, spec.hour, spec.minute)
+      : new Date(y, mo, d, spec.hour, spec.minute).getTime();
+    return useZone ? wall - offset : wall;
+  };
+
+  let ts: number;
+  if (spec.month !== undefined && spec.dayOfMonth !== undefined) {
+    // Explicit date ("Oct 6, 1pm"). More than 2 days in the past → assume year
+    // rollover (message seen near New Year); slightly past → stale, keep as-is.
+    ts = build(get.year(), spec.month, spec.dayOfMonth);
+    if (ts < now - 2 * DAY_MS) {
+      ts = build(get.year() + 1, spec.month, spec.dayOfMonth);
+    }
+  } else if (spec.dayOfWeek !== undefined) {
+    // Day-of-week ("Mon 12:00am") → next occurrence.
+    const delta = (spec.dayOfWeek - get.day() + 7) % 7;
+    ts = build(get.year(), get.month(), get.date() + delta);
+    if (ts <= now) ts += 7 * DAY_MS;
+  } else {
+    // Time-only ("resets 8pm") → next occurrence within 24h.
+    ts = build(get.year(), get.month(), get.date());
+    if (ts <= now) ts += DAY_MS;
+  }
+
+  if (ts > now + MAX_RESET_HORIZON_MS) return null;
+  return ts;
+}
+
+/** Parse the reset-time spec found within `window`, or null. */
+function parseResetTime(window: string, now: number): number | null {
+  const m = RESET_TIME_PATTERN.exec(window);
+  if (!m) return null;
+
+  const hour12 = parseInt(m[4], 10);
+  const minute = m[5] ? parseInt(m[5], 10) : 0;
+  if (hour12 < 1 || hour12 > 12 || minute > 59) return null;
+  const pm = m[6].toLowerCase() === 'pm';
+  const hour = (hour12 % 12) + (pm ? 12 : 0);
+
+  const spec: ResetSpec = { hour, minute };
+  if (m[1] && m[2]) {
+    spec.month = MONTHS.indexOf(m[1].toLowerCase());
+    spec.dayOfMonth = parseInt(m[2], 10);
+    if (spec.dayOfMonth < 1 || spec.dayOfMonth > 31) return null;
+  } else if (m[3]) {
+    spec.dayOfWeek = WEEKDAYS.indexOf(m[3].toLowerCase());
+  }
+  if (m[7]) spec.timeZone = m[7].trim();
+
+  return resolveResetSpec(spec, now);
+}
+
+/**
+ * Scan cleaned (ANSI-stripped) terminal output for a usage-limit pause message
+ * with a parseable reset time. Returns the LAST parseable occurrence in the
+ * chunk (most recent on screen), or null when none is found.
+ */
+export function detectUsageLimitPause(cleanData: string, now: number = Date.now()): UsageLimitDetection | null {
+  if (!cleanData || !/limit|extra usage/i.test(cleanData)) return null;
+
+  let result: UsageLimitDetection | null = null;
+
+  // Raw API epoch form
+  EPOCH_LIMIT_PATTERN.lastIndex = 0;
+  let em: RegExpExecArray | null;
+  while ((em = EPOCH_LIMIT_PATTERN.exec(cleanData)) !== null) {
+    const resetAt = parseInt(em[1], 10) * 1000;
+    if (resetAt > now + MAX_RESET_HORIZON_MS) continue;
+    result = { resetAt, matched: em[0] };
+  }
+
+  // TUI phrase + "resets <time>" forms
+  LIMIT_PHRASE_PATTERN.lastIndex = 0;
+  let pm: RegExpExecArray | null;
+  while ((pm = LIMIT_PHRASE_PATTERN.exec(cleanData)) !== null) {
+    const window = cleanData.slice(pm.index, pm.index + RESET_TIME_WINDOW);
+    const resetAt = parseResetTime(window, now);
+    if (resetAt !== null) {
+      result = { resetAt, matched: window.slice(0, 80).trim() };
+    }
+  }
+
+  return result;
+}
@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Resolve the Codex (OpenAI) CLI binary across common install paths.
+ *
+ * Mirrors opencode-cli-resolver.ts pattern. Finds the `codex` binary
+ * and provides an augmented PATH string for tmux sessions.
+ *
+ * @module utils/codex-cli-resolver
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+
+/** Common directories where the Codex CLI binary may be installed */
+const CODEX_SEARCH_DIRS = [
+  join(homedir(), '.codex', 'bin'), // Default install location
+  join(homedir(), '.local', 'bin'), // Alternative install location
+  '/usr/local/bin', // Homebrew / system
+  join(homedir(), '.bun', 'bin'), // Bun global
+  join(homedir(), '.npm-global', 'bin'), // npm global
+  join(homedir(), 'bin'), // User bin
+];
+
+/** Cached directory containing the codex binary (empty string = searched but not found) */
+let _codexDir: string | null = null;
+
+/**
+ * Finds the directory containing the `codex` binary.
+ * Checks `which codex` first, then falls back to common install locations.
+ * Result is cached for subsequent calls.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolveCodexDir(): string | null {
+  if (_codexDir !== null) return _codexDir || null;
+
+  // Try `which` first (respects current PATH)
+  try {
+    const result = execSync('which codex', {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    }).trim();
+    if (result && existsSync(result)) {
+      _codexDir = dirname(result);
+      return _codexDir;
+    }
+  } catch {
+    // Codex not in PATH, will check common locations
+  }
+
+  for (const dir of CODEX_SEARCH_DIRS) {
+    if (existsSync(join(dir, 'codex'))) {
+      _codexDir = dir;
+      return _codexDir;
+    }
+  }
+
+  _codexDir = ''; // mark as searched, not found
+  return null;
+}
+
+/**
+ * Check if Codex CLI is available on the system.
+ */
+export function isCodexAvailable(): boolean {
+  return resolveCodexDir() !== null;
+}
@@ -22,8 +22,10 @@ export {
  execPattern,
 } from './regex-patterns.js';
 export { MAX_SESSION_TOKENS } from './token-validation.js';
+export { isSafePushEndpoint } from './push-endpoint-validation.js';
 export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
 export { assertNever } from './type-safety.js';
 export { wrapWithNice } from './nice-wrapper.js';
 export { findClaudeDir, getAugmentedPath } from './claude-cli-resolver.js';
 export { resolveOpenCodeDir } from './opencode-cli-resolver.js';
+export { resolveCodexDir, isCodexAvailable } from './codex-cli-resolver.js';
@@ -0,0 +1,69 @@
+/**
+ * @fileoverview SSRF guard for web-push subscription endpoints (security review M7).
+ *
+ * A push `endpoint` is an attacker-suppliable URL that the server fetches via
+ * `webpush.sendNotification`. On the no-auth loopback default a local page (or any
+ * non-browser client) could register an endpoint pointing at the cloud metadata
+ * service (169.254.169.254) or an internal host, turning the server into an SSRF
+ * proxy. We require https and reject IP-literal hosts in private/loopback/
+ * link-local/reserved ranges. DNS-named hosts are allowed (every real push service
+ * — FCM, Mozilla, Apple, WNS — uses a public DNS name); this is checked both at
+ * subscribe time (schema) and again at send time (defense-in-depth).
+ *
+ * Note: a hostname that *resolves* to an internal IP (DNS rebinding) is not caught
+ * here without async resolution; the realistic, documented vector (a direct
+ * internal IP literal) is closed.
+ */
+import { isIP } from 'node:net';
+
+/** True if `host` is an IP literal in a private, loopback, link-local, or reserved range. */
+function isPrivateOrReservedIp(host: string): boolean {
+  const kind = isIP(host);
+  if (kind === 0) return false; // not an IP literal — a DNS name
+
+  if (kind === 4) {
+    const [a, b] = host.split('.').map(Number);
+    if (a === 0 || a === 10 || a === 127) return true; // unspecified, private, loopback
+    if (a === 169 && b === 254) return true; // link-local (incl. 169.254.169.254 metadata)
+    if (a === 172 && b >= 16 && b <= 31) return true; // private
+    if (a === 192 && b === 168) return true; // private
+    if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT (RFC 6598)
+    if (a >= 224) return true; // multicast + reserved (224.0.0.0+)
+    return false;
+  }
+
+  // IPv6
+  const h = host.toLowerCase();
+  if (h === '::1' || h === '::') return true; // loopback, unspecified
+  if (h.startsWith('fe8') || h.startsWith('fe9') || h.startsWith('fea') || h.startsWith('feb')) return true; // fe80::/10 link-local
+  if (h.startsWith('fc') || h.startsWith('fd')) return true; // fc00::/7 unique-local
+  // IPv4-mapped (::ffff:a.b.c.d). URL/Node may normalize the dotted tail to hex
+  // (::ffff:7f00:1), so handle both forms and re-check the embedded IPv4.
+  const mappedDotted = h.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (mappedDotted) return isPrivateOrReservedIp(mappedDotted[1]);
+  const mappedHex = h.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) {
+    const hi = parseInt(mappedHex[1], 16);
+    const lo = parseInt(mappedHex[2], 16);
+    return isPrivateOrReservedIp(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`);
+  }
+  return false;
+}
+
+/**
+ * Validate a web-push endpoint URL is safe to fetch server-side.
+ * Requires an https URL whose host is not an internal/reserved IP literal.
+ */
+export function isSafePushEndpoint(endpoint: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== 'https:') return false;
+  if (!url.hostname) return false;
+  // URL.hostname wraps IPv6 literals in brackets ([::1]); strip them for isIP().
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  return !isPrivateOrReservedIp(host);
+}
@@ -19,6 +19,7 @@ import {
  AUTH_FAILURE_MAX,
  AUTH_FAILURE_WINDOW_MS,
 } from '../../config/auth-config.js';
+import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';

 // Auth session cookie name
 export const AUTH_COOKIE_NAME = 'codeman_session';
@@ -28,19 +29,32 @@ interface AuthState {
  authSessions: StaleExpirationMap<string, AuthSessionRecord> | null;
  authFailures: StaleExpirationMap<string, number> | null;
  qrAuthFailures: StaleExpirationMap<string, number> | null;
+  hookSecretFailures: StaleExpirationMap<string, number> | null;
 }

 /**
 * Register HTTP Basic Auth middleware with session cookies and rate limiting.
 * Only active when CODEMAN_PASSWORD is set.
 *
+ * @param getTunnelRunning - returns true while a managed tunnel is active. Used
+ *   to gate the `/api/hook-event` localhost bypass: when a tunnel is up, tunneled
+ *   internet traffic reaches the loopback origin with `req.ip === 127.0.0.1`, so
+ *   the bypass additionally requires the shared hook secret (COD-54). When no
+ *   tunnel is running (loopback-only, the normal case) the plain localhost bypass
+ *   is kept so already-deployed (pre-secret) hooks + the loop channel keep working.
+ *   Optional; defaults to "no tunnel" (unchanged behavior) when omitted.
 * @returns AuthState for lifecycle management (dispose on server stop)
 */
-export function registerAuthMiddleware(app: FastifyInstance, https: boolean): AuthState {
+export function registerAuthMiddleware(
+  app: FastifyInstance,
+  https: boolean,
+  getTunnelRunning: () => boolean = () => false
+): AuthState {
  const state: AuthState = {
    authSessions: null,
    authFailures: null,
    qrAuthFailures: null,
+    hookSecretFailures: null,
  };

  const authPassword = process.env.CODEMAN_PASSWORD;
@@ -67,24 +81,70 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
    refreshOnGet: false,
  });

+  // Separate hook-secret failure counter (COD-54). MUST NOT share authFailures:
+  // legacy (pre-secret) hook configs fire constantly from 127.0.0.1, and counting
+  // their 401s against the shared bucket would 429 every cookie-less request from
+  // loopback — locking out the Basic-Auth login path (and, through a tunnel, every
+  // client, since tunneled traffic also arrives as 127.0.0.1).
+  state.hookSecretFailures = new StaleExpirationMap<string, number>({
+    ttlMs: AUTH_FAILURE_WINDOW_MS,
+    refreshOnGet: false,
+  });
+
  const authSessions = state.authSessions;
  const authFailures = state.authFailures;
+  const hookSecretFailures = state.hookSecretFailures;

-  function sendAuthRateLimit(reply: FastifyReply, clientIp: string): void {
-    const remainingMs = authFailures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
+  function sendAuthRateLimit(
+    reply: FastifyReply,
+    clientIp: string,
+    failures: StaleExpirationMap<string, number> = authFailures
+  ): void {
+    const remainingMs = failures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
    const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
    reply.header('Retry-After', String(retryAfterSeconds));
    reply.code(429).send('Too Many Requests — try again later');
  }

  app.addHook('onRequest', (req, reply, done) => {
-    // Hook events come from local Claude Code hooks (curl from localhost) — no auth headers available.
-    // Safe: validated by HookEventSchema, only triggers broadcasts.
-    // Security: restrict bypass to localhost only — prevents forged hook events via tunnel/LAN.
+    // Hook events come from local Claude Code hooks (curl from localhost) — no
+    // Basic-Auth credentials available. Validated downstream by HookEventSchema.
+    //
+    // COD-54: the bare localhost bypass is unsafe while a tunnel is running, because
+    // `cloudflared --url http://127.0.0.1:port` proxies internet traffic INTO the
+    // loopback origin, so a tunneled request arrives with req.ip === 127.0.0.1 and
+    // would pass. So:
+    //   - tunnel running → bypass requires the shared hook secret (local hooks present
+    //     it via the X-Codeman-Hook-Secret header; internet traffic can't know it),
+    //   - tunnel not running (loopback-only, the normal case) → keep the plain
+    //     localhost bypass so already-deployed (pre-secret) hooks + the loop's own
+    //     credential-less hook channel keep working.
    if (req.url === '/api/hook-event' && req.method === 'POST') {
      const ip = req.ip;
-      if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') {
-        done();
+      const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+      if (isLoopback) {
+        if (!getTunnelRunning()) {
+          // Loopback-only: unchanged behavior.
+          done();
+          return;
+        }
+        // Tunnel up: require the shared secret (constant-time compare).
+        const presented = Buffer.from(req.headers[HOOK_SECRET_HEADER.toLowerCase()]?.toString() ?? '');
+        const expected = Buffer.from(getHookSecret());
+        if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
+          done();
+          return;
+        }
+        // Wrong/absent secret while tunneled — rate-limit per IP in the DEDICATED
+        // hook bucket (never authFailures, which would lock out the login path).
+        const hookIp = req.ip;
+        const hookFailures = hookSecretFailures.get(hookIp) ?? 0;
+        if (hookFailures >= AUTH_FAILURE_MAX) {
+          sendAuthRateLimit(reply, hookIp, hookSecretFailures);
+          return;
+        }
+        hookSecretFailures.set(hookIp, hookFailures + 1);
+        reply.code(401).send('Unauthorized: hook secret required');
        return;
      }
      // Non-localhost hook requests fall through to normal auth
@@ -205,7 +265,12 @@ export function registerSecurityHeaders(app: FastifyInstance, https: boolean): v
  const scriptSrc =
    "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net" + (gesture ? " 'wasm-unsafe-eval'" : '');
  const connectSrc = "connect-src 'self' wss://api.deepgram.com";
-  const workerSrc = gesture ? "; worker-src 'self' blob:" : '';
+  // blob: workers are needed unconditionally: terminal-ui's _safeYield tick
+  // worker (throttling escape) is created from a Blob URL. Without this, every
+  // page load logs a CSP violation and the worker leg of _safeYield is dead.
+  // Risk is minimal — only same-origin scripts (already governed by script-src)
+  // can construct blob workers.
+  const workerSrc = "; worker-src 'self' blob:";
  const csp =
    `default-src 'self'; ${scriptSrc}; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; ` +
    `img-src 'self' data: blob:; ${connectSrc}; font-src 'self' https://cdn.jsdelivr.net; frame-ancestors 'self'${workerSrc}`;
@@ -6,6 +6,16 @@ export function isExplicitlyEnabled(value: string | undefined): boolean {
  return value !== undefined && EXPLICIT_TRUE_VALUES.has(value.trim().toLowerCase());
 }

+/**
+ * True when unauthenticated network exposure is acceptable: either a password is
+ * set (auth active) or the operator explicitly acknowledged it. Used by the
+ * tunnel-enable guard (COD-55) to refuse publishing an unauthenticated public URL.
+ */
+export function isUnauthenticatedNetworkAcknowledged(allowFlag = false): boolean {
+  if (process.env.CODEMAN_PASSWORD) return true;
+  return allowFlag || isExplicitlyEnabled(process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK);
+}
+
 export function isLoopbackBindHost(host: string): boolean {
  const normalized = host
    .trim()
@@ -44,11 +44,20 @@ Object.assign(CodemanApp.prototype, {
  async _apiJson(path, opts = {}) {
    const res = await this._api(path, opts);
    if (!res || !res.ok) return null;
+    let body;
    try {
-      return await res.json();
+      body = await res.json();
    } catch {
      return null;
    }
+    // Uniform API envelope (stable HTTP contract): unwrap { success:true, data } → data;
+    // { success:false } → null (errors also surface as a non-ok HTTP status above).
+    // Legacy/bare bodies pass through unchanged.
+    if (body && typeof body === 'object') {
+      if (body.success === false) return null;
+      if (body.success === true && 'data' in body) return body.data;
+    }
+    return body;
  },

  /**
@@ -153,6 +153,9 @@ const _SSE_HANDLER_MAP = [
  [SSE_EVENTS.SESSION_IDLE, '_onSessionIdle'],
  [SSE_EVENTS.SESSION_WORKING, '_onSessionWorking'],
  [SSE_EVENTS.SESSION_AUTO_CLEAR, '_onSessionAutoClear'],
+  [SSE_EVENTS.SESSION_LIMIT_PAUSE_SCHEDULED, '_onSessionLimitPauseScheduled'],
+  [SSE_EVENTS.SESSION_LIMIT_RESUME, '_onSessionLimitResume'],
+  [SSE_EVENTS.SESSION_LIMIT_RESUME_CANCELLED, '_onSessionLimitResumeCancelled'],
  [SSE_EVENTS.SESSION_CLI_INFO, '_onSessionCliInfo'],

  // Scheduled runs
@@ -314,6 +317,7 @@ class CodemanApp {
    this._initGeneration = 0;     // dedup concurrent handleInit calls
    this._initFallbackTimer = null; // fallback timer if SSE init doesn't arrive
    this._selectGeneration = 0;   // cancel stale selectSession loads
+    this.terminalLoadStates = new Map(); // Map<sessionId, { generation, phase }>
    this.respawnStatus = {};
    this.respawnTimers = {}; // Track timed respawn timers
    this.respawnCountdownTimers = {}; // { sessionId: { timerName: { endsAt, totalMs, reason } } }
@@ -416,6 +420,8 @@ class CodemanApp {
    this.syncWaitTimeout = null; // Timeout for incomplete sync blocks
    this._isLoadingBuffer = false; // true during chunkedTerminalWrite — blocks live SSE writes
    this._loadBufferQueue = null;  // queued SSE events during buffer load
+    this._bufferLoadSeq = 0;
+    this._bufferLoadOwner = null;

    // Flicker filter state (buffers output after screen clears)
    this.flickerFilterBuffer = '';
@@ -486,7 +492,7 @@ class CodemanApp {
  // If stale, cleans up buffer-loading state and returns true.
  _isStaleSelect(selectGen) {
    if (selectGen !== this._selectGeneration) {
-      if (this._isLoadingBuffer) this._finishBufferLoad();
+      if (this._isLoadingBuffer) this._finishBufferLoad(selectGen);
      this._restoringFlushedState = false;
      return true;
    }
@@ -574,6 +580,7 @@ class CodemanApp {
    const _kbSettings = this.loadAppSettingsFromStorage();
    if (_kbSettings.extendedKeyboardBar) KeyboardAccessoryBar.setMode('extended');
    this.applyHeaderVisibilitySettings();
+    this.applySkin();
    this.applyTabWrapSettings();
    this.applyMonitorVisibility();
    // Remove mobile-init class now that JS has applied visibility settings.
@@ -597,7 +604,7 @@ class CodemanApp {
    // Fetch tunnel status for header indicator (desktop only)
    this.loadTunnelStatus();
    // Share a single settings fetch between both consumers
-    const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).catch(() => null);
+    const settingsPromise = fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null).catch(() => null);
    this.loadQuickStartCases(null, settingsPromise);
    this._initRunMode();
    this.setupEventListeners();
@@ -631,6 +638,7 @@ class CodemanApp {
    // Load server-stored settings (async, re-applies visibility after load)
    this.loadAppSettingsFromServer(settingsPromise).then(() => {
      this.applyHeaderVisibilitySettings();
+      this.applySkin();
      this.applyTabWrapSettings();
      this.applyMonitorVisibility();
    });
@@ -649,6 +657,7 @@ class CodemanApp {
        this._disposeWebGLObserver();
        this._webglAddon?.dispose();
        this._webglAddon = null;
+        this._scheduleTerminalRepaint();
      });
      this.terminal.loadAddon(this._webglAddon);
      console.log('[CRASH-DIAG] WebGL renderer enabled');
@@ -679,7 +688,7 @@ class CodemanApp {
          this._disposeWebGLObserver();
          this._webglAddon?.dispose();
          this._webglAddon = null;
-          try { this.terminal.refresh(0, this.terminal.rows - 1); } catch {}
+          this._scheduleTerminalRepaint();
        }
      });
      this._webglLongTaskObserver.observe({ type: 'longtask', buffered: false });
@@ -698,6 +707,22 @@ class CodemanApp {
    this._webglLongTaskObserver = null;
  }

+  /**
+   * Repaint the full terminal viewport after a renderer swap (WebGL → canvas/DOM).
+   * Scheduled on the next frame so it lands after the addon teardown settles, and
+   * debounced so the context-loss and long-task fallback paths can't double-fire.
+   * No-ops safely if the terminal isn't ready.
+   */
+  _scheduleTerminalRepaint() {
+    if (this._terminalRepaintScheduled) return;
+    this._terminalRepaintScheduled = true;
+    const raf = typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => setTimeout(cb, 0);
+    raf(() => {
+      this._terminalRepaintScheduled = false;
+      try { this.terminal?.refresh(0, this.terminal.rows - 1); } catch {}
+    });
+  }
+
  _disableWebGLSticky(reason) {
    try {
      localStorage.setItem('codeman-webgl-disabled', JSON.stringify({ reason, at: Date.now() }));
@@ -1531,13 +1556,13 @@ class CodemanApp {
    try {
      // Source 1: Transcript JSONL (best quality — clean structured text from Claude)
      const res = await fetch(`/api/sessions/${this.activeSessionId}/last-response`);
-      const data = await res.json();
+      const data = (await res.json())?.data ?? {};
      let lastResponse = data.text || '';

      // Source 2: Terminal buffer fallback — strip ANSI, drop Claude CLI chrome
      if (!lastResponse) {
        const termRes = await fetch(`/api/sessions/${this.activeSessionId}/terminal`);
-        const termData = await termRes.json();
+        const termData = (await termRes.json())?.data ?? {};
        if (termData.terminalBuffer) {
          lastResponse = this._cleanTerminalBuffer(termData.terminalBuffer);
        }
@@ -1567,7 +1592,7 @@ class CodemanApp {
    if (moreBtn) moreBtn.textContent = '...';
    try {
      const res = await fetch(`/api/sessions/${this.activeSessionId}/last-response?context=full`);
-      const data = await res.json();
+      const data = (await res.json())?.data ?? {};
      const messages = data.messages || [];
      const body = document.getElementById('responseViewerBody');
      const title = document.getElementById('responseViewerTitle');
@@ -1618,7 +1643,7 @@ class CodemanApp {
    if (this._isLoadingBuffer) return;
    try {
      const res = await fetch(`/api/sessions/${this.activeSessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
-      const data = await res.json();
+      const data = (await res.json())?.data ?? {};
      if (data.terminalBuffer) {
        this.terminal.clear();
        this.terminal.reset();
@@ -1648,7 +1673,7 @@ class CodemanApp {
      // Fetch buffer, clear terminal, write buffer, resize (no Ctrl+L needed)
      try {
        const res = await fetch(`/api/sessions/${data.id}/terminal`);
-        const termData = await res.json();
+        const termData = (await res.json())?.data ?? {};

        this.terminal.clear();
        this.terminal.reset();
@@ -1747,6 +1772,33 @@ class CodemanApp {
    this._notifySession(data.sessionId, 'info', 'auto-clear', 'Auto-Cleared', `Context reset at ${(data.tokens || 0).toLocaleString()} tokens`);
  }

+  _onSessionLimitPauseScheduled(data) {
+    const session = this.sessions.get(data.sessionId);
+    if (session) session.autoResumeAt = data.resumeAt;
+    const at = new Date(data.resumeAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    if (data.sessionId === this.activeSessionId) {
+      this.showToast(`Usage limit reached — auto-resume at ${at}`, 'warning');
+    }
+    this._notifySession(data.sessionId, 'warning', 'limit-pause', 'Usage Limit Reached', `Auto-resume scheduled for ${at}`);
+    this.updateAutoResumeStatus(data.sessionId);
+  }
+
+  _onSessionLimitResume(data) {
+    const session = this.sessions.get(data.sessionId);
+    if (session) session.autoResumeAt = undefined;
+    if (data.sessionId === this.activeSessionId) {
+      this.showToast('Usage limit reset — work resumed automatically', 'success');
+    }
+    this._notifySession(data.sessionId, 'info', 'limit-resume', 'Auto-Resumed', 'Usage limit reset — continuing work');
+    this.updateAutoResumeStatus(data.sessionId);
+  }
+
+  _onSessionLimitResumeCancelled(data) {
+    const session = this.sessions.get(data.sessionId);
+    if (session) session.autoResumeAt = undefined;
+    this.updateAutoResumeStatus(data.sessionId);
+  }
+
  _onSessionCliInfo(data) {
    const session = this.sessions.get(data.sessionId);
    if (session) {
@@ -1817,6 +1869,12 @@ class CodemanApp {
      if (this._ws === ws) {
        this._wsReady = true;
        this._wsReconnectAttempts = 0;
+        // Send a typed resize over the fresh socket: syncs PTY dims after
+        // (re)connects AND registers the desktop sizing claim server-side —
+        // selectSession's earlier resizes ran before this WS existed, so they
+        // went over HTTP, which never claims (see ws-routes sizingToken).
+        this.sendResize(sessionId)?.catch?.(() => {});
+        this._startMobileResizeRetry(sessionId);
      }
    };

@@ -1842,6 +1900,7 @@ class CodemanApp {
      this._ws = null;
      this._wsSessionId = null;
      this._wsReady = false;
+      this._stopMobileResizeRetry();

      // Reconnect on unexpected close (server restart, network blip, ping timeout).
      // Don't reconnect if we intentionally disconnected (_disconnectWs nulls onclose)
@@ -1867,6 +1926,7 @@ class CodemanApp {
  _disconnectWs() {
    this._clearTimer('_wsReconnectTimer');
    this._wsReconnectAttempts = 0;
+    this._stopMobileResizeRetry();
    if (this._ws) {
      this._ws.onclose = null; // Prevent re-entrant cleanup
      this._ws.close();
@@ -1876,6 +1936,41 @@ class CodemanApp {
    }
  }

+  /**
+   * Small-viewport claim-idle retry. While a desktop sizing claim is "hot",
+   * the server ignores this device's resize (Session.DESKTOP_CLAIM_IDLE_MS),
+   * and the single resize sent on attach is deduped client-side — without a
+   * retry, a phone that attached under an active desktop would render a
+   * desktop-width stream forever. Re-send the current dims periodically (a
+   * server-side no-op once the pane already matches) so the pane reflows to
+   * this device shortly after the desktop goes idle. Visible-tab only: a
+   * phone in a pocket must not steal the pane from an active desktop.
+   */
+  _startMobileResizeRetry(sessionId) {
+    this._stopMobileResizeRetry();
+    const type =
+      typeof MobileDetection !== 'undefined' && MobileDetection.getDeviceType
+        ? MobileDetection.getDeviceType()
+        : 'desktop';
+    if (type === 'desktop') return;
+    this._mobileResizeRetryTimer = setInterval(() => {
+      if (document.visibilityState !== 'visible') return;
+      if (!this._wsReady || this._wsSessionId !== sessionId) return;
+      // Same guard as throttledResize: while the virtual keyboard is up, a
+      // fit()+SIGWINCH at the shrunken row count makes Ink re-render garbage
+      // and shifts the accessory toolbar mid-typing. Retry after it closes.
+      if (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) return;
+      this.sendResize(sessionId)?.catch?.(() => {});
+    }, MOBILE_RESIZE_RETRY_MS);
+  }
+
+  _stopMobileResizeRetry() {
+    if (this._mobileResizeRetryTimer) {
+      clearInterval(this._mobileResizeRetryTimer);
+      this._mobileResizeRetryTimer = null;
+    }
+  }
+
  /**
   * Send input to server without blocking the keystroke flush cycle.
   * Uses a sequential promise chain to preserve character ordering
@@ -2006,9 +2101,18 @@ class CodemanApp {
    const cjkEl = document.getElementById('cjkInput');
    if (!cjkEl) return;
    const settings = this.loadAppSettingsFromStorage();
-    const showCjk = this._serverCjkOverride || settings.cjkInputEnabled || false;
+    const defaults = this.getDefaultSettings?.() || {};
+    // Mobile defaults ship cjkInputEnabled: false (native terminal input by
+    // default on touch), but an explicit user enable is honored everywhere —
+    // the App Settings toggle must not be a silent no-op on phones.
+    const showCjk = this._serverCjkOverride || (settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false);
+    cjkEl.classList.toggle('cjk-input-visible', !!showCjk);
+    document.body.classList.toggle('cjk-input-visible', !!showCjk);
    cjkEl.style.display = showCjk ? 'block' : 'none';
+    cjkEl.setAttribute('aria-hidden', showCjk ? 'false' : 'true');
+    if (showCjk && cjkEl.value === '\u200B') cjkEl.value = '';
    if (!showCjk) window.cjkActive = false;
+    if (typeof KeyboardHandler !== 'undefined') KeyboardHandler.updateLayoutForKeyboard();
  }

  /**
@@ -2021,6 +2125,7 @@ class CodemanApp {
    this.ralphStates.clear();
    this.terminalBuffers.clear();
    this.terminalBufferCache.clear();
+    this._xtermSnapshots?.clear();
    this.projectInsights.clear();
    this.teams.clear();
    this.teamTasks.clear();
@@ -2039,6 +2144,7 @@ class CodemanApp {
    this.writeFrameScheduled = false;
    this._isLoadingBuffer = false;
    this._loadBufferQueue = null;
+    this._bufferLoadOwner = null;
    // Abort any in-flight chunkedTerminalWrite (SSE reconnect reloads buffers)
    this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
    // Preserve local echo overlay text across SSE reconnect — just hide until
@@ -2254,7 +2360,7 @@ class CodemanApp {
    try {
      const res = await fetch('/api/status');
      const data = await res.json();
-      this.handleInit(data);
+      this.handleInit(data?.data ?? {});
    } catch (err) {
      console.error('Failed to load state:', err);
    }
@@ -2281,7 +2387,7 @@ class CodemanApp {

  renderSessionTabs() {
    // Don't re-render while user is typing in the inline rename input
-    if (this._activeRename) return;
+    if (this._inlineRenameActive) return;
    this._debouncedCall('sessionTabs', this._renderSessionTabsImmediate);
  }

@@ -2299,6 +2405,45 @@ class CodemanApp {
    }
  }

+  _setTerminalLoadState(sessionId, selectGen, phase) {
+    this.terminalLoadStates.set(sessionId, { generation: selectGen, phase });
+    this._updateTerminalLoadTab(sessionId);
+  }
+
+  _clearTerminalLoadState(sessionId, selectGen) {
+    const state = this.terminalLoadStates.get(sessionId);
+    if (state && state.generation !== selectGen) return;
+    this.terminalLoadStates.delete(sessionId);
+    this._updateTerminalLoadTab(sessionId);
+  }
+
+  _updateTerminalLoadTab(sessionId) {
+    const tab = this.$('sessionTabs')?.querySelector(`.session-tab[data-id="${sessionId}"]`);
+    if (!tab) return;
+
+    const loadState = this.terminalLoadStates.get(sessionId);
+    tab.classList.toggle('tab-loading', !!loadState);
+    if (loadState) {
+      tab.setAttribute('aria-busy', 'true');
+      tab.dataset.loadPhase = loadState.phase;
+      if (!tab.querySelector('.tab-load-spinner')) {
+        const spinner = document.createElement('span');
+        spinner.className = 'tab-load-spinner';
+        spinner.setAttribute('aria-hidden', 'true');
+        const numberEl = tab.querySelector('.tab-number');
+        if (numberEl) {
+          numberEl.insertAdjacentElement('afterend', spinner);
+        } else {
+          tab.insertBefore(spinner, tab.firstChild);
+        }
+      }
+    } else {
+      tab.setAttribute('aria-busy', 'false');
+      delete tab.dataset.loadPhase;
+      tab.querySelector('.tab-load-spinner')?.remove();
+    }
+  }
+
  _renderSessionTabsImmediate() {
    const container = this.$('sessionTabs');
    const existingTabs = container.querySelectorAll('.session-tab[data-id]');
@@ -2320,6 +2465,7 @@ class CodemanApp {
        const name = this.getSessionName(session);
        const taskStats = session.taskStats || { running: 0, total: 0 };
        const hasRunningTasks = taskStats.running > 0;
+        const loadState = this.terminalLoadStates.get(id);

        // Update active class
        if (isActive && !tab.classList.contains('active')) {
@@ -2328,6 +2474,27 @@ class CodemanApp {
          tab.classList.remove('active');
        }

+        tab.classList.toggle('tab-loading', !!loadState);
+        if (loadState) {
+          tab.setAttribute('aria-busy', 'true');
+          tab.dataset.loadPhase = loadState.phase;
+          if (!tab.querySelector('.tab-load-spinner')) {
+            const spinner = document.createElement('span');
+            spinner.className = 'tab-load-spinner';
+            spinner.setAttribute('aria-hidden', 'true');
+            const numberEl = tab.querySelector('.tab-number');
+            if (numberEl) {
+              numberEl.insertAdjacentElement('afterend', spinner);
+            } else {
+              tab.insertBefore(spinner, tab.firstChild);
+            }
+          }
+        } else {
+          tab.setAttribute('aria-busy', 'false');
+          delete tab.dataset.loadPhase;
+          tab.querySelector('.tab-load-spinner')?.remove();
+        }
+
        // Update alert class
        const alertType = this.tabAlerts.get(id);
        const wantAction = alertType === 'action';
@@ -2426,7 +2593,7 @@ class CodemanApp {
  }

  _fullRenderSessionTabs() {
-    if (this._activeRename) return;
+    if (this._inlineRenameActive) return;
    const container = this.$('sessionTabs');

    // Clean up any orphaned dropdowns before re-rendering
@@ -2456,6 +2623,7 @@ class CodemanApp {
      const hasRunningTasks = taskStats.running > 0;
      const alertType = this.tabAlerts.get(id);
      const alertClass = alertType === 'action' ? ' tab-alert-action' : alertType === 'idle' ? ' tab-alert-idle' : '';
+      const loadState = this.terminalLoadStates.get(id);

      // Get minimized subagents for this session
      const minimizedAgents = this.minimizedSubagents.get(id);
@@ -2467,12 +2635,13 @@ class CodemanApp {
      const tallTabsEnabled = this._tallTabsEnabled ?? false;
      const showFolder = tallTabsEnabled && session.name && folderName && folderName !== name;

-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${this.detachedSessions.has(id) ? ' detached' : ''}" data-id="${id}" data-color="${color}" onclick="app.selectSession('${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
+      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${loadState ? ' tab-loading' : ''}" data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, '${escapeHtml(id)}')" oncontextmenu="event.preventDefault(); app.startInlineRename('${escapeHtml(id)}')" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${session.workingDir ? `title="${escapeHtml(session.workingDir)}"` : ''}>
          ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
+          ${loadState ? '<span class="tab-load-spinner" aria-hidden="true"></span>' : ''}
          <span class="tab-status ${status}" aria-hidden="true"></span>
          <span class="tab-info">
            <span class="tab-name-row">
-              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : ''}
+              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : ''}
              <span class="tab-name" data-session-id="${id}">${(() => { const p = parseSessionPrefix(name); return p && p.suffix ? '<span class="tab-prefix">' + escapeHtml(p.prefix) + '</span><span class="tab-suffix">: ' + escapeHtml(p.suffix) + '</span>' : escapeHtml(name); })()}</span>
              <span class="tab-detached-badge" aria-hidden="true">detached</span>
            </span>
@@ -2516,7 +2685,7 @@ class CodemanApp {
      if ((e.key === 'Enter' || e.key === ' ') && currentIndex >= 0) {
        e.preventDefault();
        const sessionId = tabs[currentIndex].dataset.id;
-        this.selectSession(sessionId);
+        this.selectSession(sessionId, { forceReload: true });
        return;
      }

@@ -2547,6 +2716,18 @@ class CodemanApp {
    container.addEventListener('keydown', this._tabKeydownHandler);
  }

+  handleSessionTabClick(event, sessionId) {
+    event?.preventDefault?.();
+    // On touch with the keyboard hidden, blur the tapped tab so switching
+    // sessions doesn't pop the on-screen keyboard. Focus policy itself lives
+    // in selectSession via _shouldFocusTerminalForTabSwitch().
+    const keyboardOpen = typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible === true;
+    if (!keyboardOpen && MobileDetection.isTouchDevice()) {
+      document.activeElement?.blur?.();
+    }
+    return this.selectSession(sessionId, { forceReload: true });
+  }
+

  // ═══════════════════════════════════════════════════════════════
  // Tab Order and Drag-and-Drop
@@ -2735,7 +2916,107 @@ class CodemanApp {
   * terminal write queue, IME composition, and local echo flush.
   * @param {string} newSessionId - The session being switched TO.
   */
+  _isUsableXtermSnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== 'string' || snapshot.length < 8) return false;
+    const visibleText = snapshot
+      .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+      .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+      .replace(/\x1b[()][0-2A-Z]/g, '')
+      .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+      .trim();
+    return visibleText.length >= 3;
+  }
+
+  /**
+   * Persist one xterm snapshot to localStorage, bounded to a fixed key budget
+   * regardless of how many sessions are live, and resilient to quota errors.
+   * The previous inline version only pruned snapshots for sessions that no
+   * longer existed AND pruned only after a successful setItem — so once the
+   * quota filled (e.g. >10 live sessions at the 20-session target) the write
+   * threw before the prune could run, permanently disabling persistence.
+   */
+  _persistXtermSnapshot(key, snapshot) {
+    const PREFIX = 'codeman-xs-';
+    const MAX_KEYS = 10;
+    const others = () => Object.keys(localStorage).filter((k) => k.startsWith(PREFIX) && k !== key);
+    try {
+      // Evict down to the budget before writing a NEW key, dead sessions first
+      // then oldest. (Overwriting an existing key doesn't grow the key count.)
+      if (localStorage.getItem(key) === null) {
+        const live = new Set(Array.from(this.sessions?.keys?.() || []));
+        const pool = others().sort(
+          (a, b) =>
+            Number(live.has(a.slice(PREFIX.length))) - Number(live.has(b.slice(PREFIX.length)))
+        );
+        while (pool.length >= MAX_KEYS) localStorage.removeItem(pool.shift());
+      }
+      try {
+        localStorage.setItem(key, snapshot);
+      } catch (_quota) {
+        // Quota exceeded: drop other snapshots one at a time and retry so a full
+        // quota can't permanently disable persistence.
+        for (const victim of others()) {
+          localStorage.removeItem(victim);
+          try {
+            localStorage.setItem(key, snapshot);
+            return;
+          } catch (_again) {
+            /* keep evicting */
+          }
+        }
+        try { localStorage.removeItem(key); } catch {}
+      }
+    } catch (_unavailable) {
+      /* localStorage unavailable (Safari private mode / disabled) — in-memory only */
+    }
+  }
+
  _cleanupPreviousSession(newSessionId) {
+    // Snapshot the OUTGOING session's xterm rendered state (viewport + scrollback +
+    // colors/attrs) before the terminal gets cleared/reset. Lets us restore the
+    // exact view on switch-back rather than replaying codex's byte stream, which
+    // drops earlier conversation from each TUI redraw and ends up showing only
+    // the latest (idle) frame.
+    // Shell sessions are never restored from a snapshot (restore is gated on
+    // mode !== 'shell'), so skip the serialize() + cache slot + localStorage
+    // quota for them. Unknown/undefined mode still snapshots, matching restore.
+    const outgoingSession = this.activeSessionId ? this.sessions?.get?.(this.activeSessionId) : null;
+    if (
+      this.activeSessionId &&
+      outgoingSession?.mode !== 'shell' &&
+      this._serializeAddon &&
+      this._xtermSnapshots
+    ) {
+      try {
+        const snapshot = this._serializeAddon.serialize({ scrollback: 1000 });
+        if (this._isUsableXtermSnapshot(snapshot)) {
+          // Delete-before-set so re-touching a session moves it to the end of
+          // the Map's insertion order — otherwise eviction is FIFO and can drop
+          // the most-recently-used session instead of the least.
+          this._xtermSnapshots.delete(this.activeSessionId);
+          this._xtermSnapshots.set(this.activeSessionId, snapshot);
+          // Cap in-memory snapshot cache at 20 entries; evict oldest on overflow.
+          if (this._xtermSnapshots.size > 20) {
+            const oldest = this._xtermSnapshots.keys().next().value;
+            this._xtermSnapshots.delete(oldest);
+          }
+          // Persist to localStorage so the snapshot survives tab discard /
+          // browser reload (Chrome discards inactive tabs after idle periods,
+          // wiping in-memory state). Cap per-snapshot at 256KB; codex
+          // buffer-replay produces a visual mess of stacked banner redraws when
+          // no snapshot exists, so persistence matters more here than for claude.
+          if (snapshot.length < 256 * 1024) {
+            this._persistXtermSnapshot(`codeman-xs-${this.activeSessionId}`, snapshot);
+          }
+        } else {
+          this._xtermSnapshots.delete(this.activeSessionId);
+          try { localStorage.removeItem(`codeman-xs-${this.activeSessionId}`); } catch {}
+        }
+      } catch (_err) {
+        /* Serialize failed — fall back to server buffer replay */
+      }
+    }
+
    // Close WebSocket for previous session (new one opens after buffer load)
    this._disconnectWs();

@@ -2761,6 +3042,7 @@ class CodemanApp {
    this.writeFrameScheduled = false;
    this._isLoadingBuffer = false;
    this._loadBufferQueue = null;
+    this._bufferLoadOwner = null;
    // Abort any in-flight chunkedTerminalWrite from the previous session.
    // Without this, old rAF-scheduled chunks continue writing stale data
    // into the terminal, interleaving with the new session's buffer.
@@ -2811,20 +3093,48 @@ class CodemanApp {
    }
  }

-  async selectSession(sessionId) {
+  _resetTerminalForReplay() {
+    this.terminal.reset();
+    this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
+  }
+
+  _shouldFocusTerminalForTabSwitch() {
+    if (typeof MobileDetection === 'undefined' || !MobileDetection.isTouchDevice()) {
+      return true;
+    }
+    return typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible;
+  }
+
+  async selectSession(sessionId, options = {}) {
    // If this session is popped out into its own window, raise that window
-    // instead of showing it inline (focus-on-click for detached tabs).
+    // instead of showing it inline (focus-on-click for detached tabs). If we
+    // owned a now-closed window, _raiseDetached re-docks and returns false so
+    // we fall through and load it inline.
    if (!this.isSoloWindow && this.detachedSessions.has(sessionId)) {
-      // Raise the popup instead of showing inline. If we owned a now-closed
-      // window, _raiseDetached re-docks and returns false so we fall through.
      if (this._raiseDetached(sessionId)) return;
    }
-    if (this.activeSessionId === sessionId) return;
+    const forceReload = options?.forceReload === true;
+    if (this.activeSessionId === sessionId && !forceReload) return;
+    if (this.activeSessionId === sessionId && forceReload) {
+      this.terminalBufferCache?.delete(sessionId);
+      this._xtermSnapshots?.delete(sessionId);
+      try { localStorage.removeItem(`codeman-xs-${sessionId}`); } catch {}
+      this._clearTimer('syncWaitTimeout');
+      this.pendingWrites = [];
+      this.writeFrameScheduled = false;
+      this._isLoadingBuffer = false;
+      this._loadBufferQueue = null;
+      this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
+      this.activeSessionId = null;
+    }
    // Focus terminal SYNCHRONOUSLY before any await — iOS Safari only honors
    // programmatic focus() within the user-gesture call stack (e.g. tab click).
    // After the first await the gesture context is lost and focus() is silently
    // ignored, leaving the keyboard unable to send input to the terminal.
-    if (this.terminal) this.terminal.focus();
+    // Desktop always focuses; touch focuses only while the on-screen keyboard
+    // is already open (so a tab switch doesn't pop the keyboard).
+    const shouldFocusTerminal = this._shouldFocusTerminalForTabSwitch();
+    if (shouldFocusTerminal && this.terminal) this.terminal.focus();

    const _selStart = performance.now();
    const _selName = this.sessions.get(sessionId)?.name || sessionId.slice(0,8);
@@ -2832,8 +3142,12 @@ class CodemanApp {
    console.log(`[CRASH-DIAG] selectSession START: ${sessionId.slice(0,8)}`);

    const selectGen = ++this._selectGeneration;
+    this._setTerminalLoadState(sessionId, selectGen, 'resizing');

-    if (selectGen !== this._selectGeneration) return; // newer tab switch won
+    if (selectGen !== this._selectGeneration) {
+      this._clearTerminalLoadState(sessionId, selectGen);
+      return; // newer tab switch won
+    }

    this._cleanupPreviousSession(sessionId);
    this.activeSessionId = sessionId;
@@ -2905,58 +3219,149 @@ class CodemanApp {
    // Without this, SSE events arriving during the fetch() gap compete with
    // the buffer write, causing 70KB+ single-frame flushes that stall WebGL.
    // chunkedTerminalWrite also sets this, but we need it before the fetch too.
-    this._isLoadingBuffer = true;
-    this._loadBufferQueue = [];
+    const bufferLoadOwner = this._beginBufferLoad(selectGen);
    try {
      // Fit terminal to container BEFORE writing any buffer data.
      // If the browser was resized while viewing another session, the terminal
      // canvas may be at stale dimensions — content would render at wrong width.
      if (this.fitAddon) this.fitAddon.fit();

+      // Also push the new dimensions to the PTY. Without this, codex/codeman
+      // sees the size that was set the last time the throttled resize handler
+      // fired (often the size of a different session's container, or the
+      // initial tmux default). The visible symptom is codex rendering inside
+      // a small region with empty rows below the status bar.
+      // sendResize is a no-op on the server when dims haven't changed, so
+      // calling it every tab switch is cheap.
+      const dimsChanged = await this.sendResize(sessionId, { forceHttp: true }).catch(() => false);
+      if (this._isStaleSelect(selectGen)) {
+        this._clearTerminalLoadState(sessionId, selectGen);
+        return;
+      }
+
+      // xterm snapshot restore: if we have a serialized xterm state from a
+      // previous visit to this session, restore the user's exact prior view
+      // (viewport + scrollback + colors) for an instant first paint. For codex
+      // this is also a correctness fix — its byte-stream replay shows only the
+      // latest TUI frame (the idle welcome banner) because codex doesn't include
+      // earlier conversation in its current redraw. For claude/opencode/gemini
+      // the replay is already complete, so the snapshot is purely a faster,
+      // scroll-preserving first paint before the canonical fetch reconciles.
+      //
+      // Try in-memory first (fast); fall back to localStorage so snapshots
+      // survive tab discards / browser reloads.
+      let snapshot = this._xtermSnapshots?.get(sessionId);
+      if (snapshot && !this._isUsableXtermSnapshot(snapshot)) {
+        this._xtermSnapshots?.delete(sessionId);
+        snapshot = null;
+      }
+      if (!snapshot) {
+        try {
+          const persisted = localStorage.getItem(`codeman-xs-${sessionId}`);
+          if (persisted && this._isUsableXtermSnapshot(persisted)) {
+            snapshot = persisted;
+            // Hoist into in-memory cache for next time (delete-before-set keeps
+            // the Map in LRU order so the just-used session isn't evicted first).
+            this._xtermSnapshots?.delete(sessionId);
+            this._xtermSnapshots?.set(sessionId, persisted);
+          } else if (persisted) {
+            localStorage.removeItem(`codeman-xs-${sessionId}`);
+          }
+        } catch (_e) {
+          /* localStorage unavailable — proceed without snapshot */
+        }
+      }
+      const sessionIsBusy = session && (session.status === 'busy' || session.status === 'working');
+      let restoredSnapshot = false;
+      if (snapshot && !sessionIsBusy && session?.mode !== 'shell') {
+        _crashDiag.log(`SNAPSHOT_RESTORE: ${(snapshot.length/1024).toFixed(0)}KB`);
+        this._setTerminalLoadState(sessionId, selectGen, 'replaying');
+        this._resetTerminalForReplay();
+        await new Promise((resolve) => this.terminal.write(snapshot, resolve));
+        if (this._isStaleSelect(selectGen)) {
+          this._clearTerminalLoadState(sessionId, selectGen);
+          return;
+        }
+        this.scrollToLastNonEmptyLine();
+        _crashDiag.log('SNAPSHOT_RESTORE_DONE');
+        // Snapshot restore is only first paint. Inactive tabs intentionally
+        // unsubscribe from high-volume terminal output, so they can miss bytes
+        // emitted while away. Keep going and replace the snapshot with the
+        // canonical live tmux pane frame from /terminal.
+        restoredSnapshot = true;
+      }
+
      // Instant cache restore for IDLE sessions only.
      // For busy sessions, the cache is always stale — writing it first causes a
      // jarring double-render: stale content appears, then the terminal flashes
      // blank and rewrites with fresh data. Skip the cache and write the fresh
      // buffer once for a single clean transition.
      const cachedBuffer = this.terminalBufferCache.get(sessionId);
-      const sessionIsBusy = session && (session.status === 'busy' || session.status === 'working');
-      if (cachedBuffer && !sessionIsBusy) {
+      let clearedForBusy = false;
+      if (cachedBuffer && !sessionIsBusy && !restoredSnapshot) {
        _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
-        this.terminal.clear();
-        this.terminal.reset();
-        await this.chunkedTerminalWrite(cachedBuffer);
-        if (this._isStaleSelect(selectGen)) return;
+        this._setTerminalLoadState(sessionId, selectGen, 'replaying');
+        this._resetTerminalForReplay();
+        await this.chunkedTerminalWrite(cachedBuffer, TERMINAL_CHUNK_SIZE, bufferLoadOwner);
+        if (this._isStaleSelect(selectGen)) {
+          this._clearTerminalLoadState(sessionId, selectGen);
+          return;
+        }
        this.terminal.scrollToBottom();
        _crashDiag.log('CACHE_DONE');
      } else if (sessionIsBusy) {
        // Clear stale content immediately — fresh buffer is being fetched
-        this.terminal.clear();
-        this.terminal.reset();
+        this._resetTerminalForReplay();
+        clearedForBusy = true;
        _crashDiag.log('CACHE_SKIP_BUSY');
      }

+      // Give TUI sessions a short chance to redraw after resize before the
+      // fresh buffer fetch. Only needed when the resize actually changed
+      // dimensions (a real SIGWINCH → Ink redraw); a same-size tab switch sent
+      // no resize, so waiting would just add latency. Shell sessions never need
+      // it, so terminal content can appear immediately when switching shells.
+      if (session?.mode !== 'shell' && dimsChanged) {
+        await new Promise((resolve) => setTimeout(resolve, TUI_REDRAW_SETTLE_MS));
+        if (this._isStaleSelect(selectGen)) {
+          this._clearTerminalLoadState(sessionId, selectGen);
+          return;
+        }
+      }
+
+      this._setTerminalLoadState(sessionId, selectGen, 'fetching');
      _crashDiag.log('FETCH_START');
      const res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
-      if (this._isStaleSelect(selectGen)) return;
-      const data = await res.json();
+      if (this._isStaleSelect(selectGen)) {
+        this._clearTerminalLoadState(sessionId, selectGen);
+        return;
+      }
+      const data = (await res.json())?.data ?? {};
      _crashDiag.log(`FETCH_DONE: ${data.terminalBuffer ? (data.terminalBuffer.length/1024).toFixed(0) + 'KB' : 'empty'} truncated=${data.truncated}`);

      if (data.terminalBuffer) {
        // Skip rewrite if fresh buffer matches cache — avoids visible clear+rewrite flash.
        // On slow connections (mobile 5G), the gap between clear() and chunkedWrite() is
        // very visible, causing the terminal to flash blank then repaint.
-        const needsRewrite = data.terminalBuffer !== cachedBuffer;
+        // A snapshot restore or a busy-clear leaves the terminal showing
+        // something other than the cache, so the fetched buffer must be
+        // replayed even when it byte-matches the cache.
+        const needsRewrite =
+          restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer;
        if (needsRewrite) {
          _crashDiag.log(`REWRITE: ${(data.terminalBuffer.length/1024).toFixed(0)}KB`);
-          this.terminal.clear();
-          this.terminal.reset();
+          this._setTerminalLoadState(sessionId, selectGen, 'replaying');
+          this._resetTerminalForReplay();
          // Show truncation indicator if buffer was cut
          if (data.truncated) {
            this.terminal.write('\x1b[90m... (earlier output truncated for performance) ...\x1b[0m\r\n\r\n');
          }
          // Use chunked write for large buffers to avoid UI jank
-          await this.chunkedTerminalWrite(data.terminalBuffer);
-          if (this._isStaleSelect(selectGen)) return;
+          await this.chunkedTerminalWrite(data.terminalBuffer, TERMINAL_CHUNK_SIZE, bufferLoadOwner);
+          if (this._isStaleSelect(selectGen)) {
+            this._clearTerminalLoadState(sessionId, selectGen);
+            return;
+          }
          // Ensure terminal is scrolled to bottom after buffer load
          this.terminal.scrollToBottom();
        }
@@ -2970,15 +3375,14 @@ class CodemanApp {
        }
      } else if (!cachedBuffer) {
        // No fresh buffer and no cache — clear any stale content
-        this.terminal.clear();
-        this.terminal.reset();
+        this._resetTerminalForReplay();
      }

      // Buffer load complete — unblock live SSE writes (queued events are discarded
      // to prevent duplicate content). chunkedTerminalWrite calls _finishBufferLoad
      // internally, but if we skipped the write (cache hit or empty), call it here.
      if (this._isLoadingBuffer) {
-        this._finishBufferLoad();
+        this._finishBufferLoad(bufferLoadOwner);
      }
      // Drop the guard so user input clears state normally
      this._restoringFlushedState = false;
@@ -3090,13 +3494,15 @@ class CodemanApp {
      this._connectWs(sessionId);

      _crashDiag.log('FOCUS');
-      this.terminal.focus();
-      this.terminal.scrollToBottom();
+      if (shouldFocusTerminal && this.terminal) this.terminal.focus();
+      this.scrollToLastNonEmptyLine();
+      this._clearTerminalLoadState(sessionId, selectGen);
      _crashDiag.log(`SELECT_DONE: ${(performance.now() - _selStart).toFixed(0)}ms`);
      console.log(`[CRASH-DIAG] selectSession DONE: ${sessionId.slice(0,8)} in ${(performance.now() - _selStart).toFixed(0)}ms`);
    } catch (err) {
-      if (this._isLoadingBuffer) this._finishBufferLoad();
+      if (this._isLoadingBuffer) this._finishBufferLoad(bufferLoadOwner);
      this._restoringFlushedState = false;
+      this._setTerminalLoadState(sessionId, selectGen, 'failed');
      console.error('Failed to load session terminal:', err);
    }
  }
@@ -3117,6 +3523,8 @@ class CodemanApp {
    }
    this.terminalBuffers.delete(sessionId);
    this.terminalBufferCache.delete(sessionId);
+    this._xtermSnapshots?.delete(sessionId);
+    try { localStorage.removeItem(`codeman-xs-${sessionId}`); } catch {}

    this._flushedOffsets?.delete(sessionId);
    this._flushedTexts?.delete(sessionId);
@@ -3126,6 +3534,7 @@ class CodemanApp {
    this.projectInsights.delete(sessionId);
    this.pendingHooks.delete(sessionId);
    this.tabAlerts.delete(sessionId);
+    this.terminalLoadStates.delete(sessionId);
    this.clearCountdownTimers(sessionId);
    this.closeSessionLogViewerWindows(sessionId);
    this.closeSessionImagePopups(sessionId);
@@ -3192,7 +3601,9 @@ class CodemanApp {
    if (killTitle) {
      killTitle.textContent = session.mode === 'opencode'
        ? 'Kill Tmux & OpenCode'
-        : 'Kill Tmux & Claude Code';
+        : session.mode === 'codex'
+          ? 'Kill Tmux & Codex'
+          : 'Kill Tmux & Claude Code';
    }

    document.getElementById('closeConfirmModal').classList.add('active');
@@ -3286,6 +3697,13 @@ class CodemanApp {
      this.sessions.clear();
      this.terminalBuffers.clear();
      this.terminalBufferCache.clear();
+      this.terminalLoadStates.clear();
+      this._xtermSnapshots?.clear();
+      try {
+        for (const k of Object.keys(localStorage)) {
+          if (k.startsWith('codeman-xs-')) localStorage.removeItem(k);
+        }
+      } catch {}
      this.activeSessionId = null;
      try { localStorage.removeItem('codeman-active-session'); } catch {}
      this.respawnStatus = {};
@@ -51,12 +51,14 @@ const GROUPING_TIMEOUT_MS = 5000;           // 5 seconds - notification grouping
 const NOTIFICATION_LIST_CAP = 100;          // Max notifications in list
 const TITLE_FLASH_INTERVAL_MS = 1500;       // Title flash rate
 const BROWSER_NOTIF_RATE_LIMIT_MS = 3000;   // Rate limit for browser notifications
+const MOBILE_RESIZE_RETRY_MS = 30000;       // Small-viewport resize re-send while a desktop sizing claim is hot
 const AUTO_CLOSE_NOTIFICATION_MS = 8000;    // Auto-close browser notifications
 const THROTTLE_DELAY_MS = 100;              // General UI throttle delay
 const TERMINAL_CHUNK_SIZE = 32 * 1024;      // 32KB chunks for terminal buffer loading
 const TERMINAL_TAIL_SIZE = 1024 * 1024;     // 1MB tail for initial load (more scrollback on tab switch)
 const SYNC_WAIT_TIMEOUT_MS = 50;            // Wait timeout for terminal sync
 const STATS_POLLING_INTERVAL_MS = 2000;     // System stats polling
+const TUI_REDRAW_SETTLE_MS = 400;           // Grace for a TUI to redraw after a real resize, before fetching its buffer

 // Z-index base values for layered floating windows
 const ZINDEX_SUBAGENT_BASE = 1000;
@@ -242,6 +244,9 @@ const SSE_EVENTS = {
  SESSION_WORKING: 'session:working',
  SESSION_AUTO_CLEAR: 'session:autoClear',
  SESSION_AUTO_COMPACT: 'session:autoCompact',
+  SESSION_LIMIT_PAUSE_SCHEDULED: 'session:limitPauseScheduled',
+  SESSION_LIMIT_RESUME: 'session:limitResume',
+  SESSION_LIMIT_RESUME_CANCELLED: 'session:limitResumeCancelled',
  SESSION_CLI_INFO: 'session:cliInfo',
  SESSION_MESSAGE: 'session:message',
  SESSION_INTERACTIVE: 'session:interactive',
@@ -331,6 +336,7 @@ const SSE_EVENTS = {

  // Images
  IMAGE_DETECTED: 'image:detected',
+  ATTACHMENT_DETECTED: 'attachment:detected',

  // Tunnel
  TUNNEL_STARTED: 'tunnel:started',
@@ -149,7 +149,7 @@ Object.assign(CodemanApp.prototype, {
    }

    const data = await resp.json();
-    return data.path;
+    return data.data.path;
  },

  // Decode an image File through the browser and re-encode it to a format the
@@ -8,7 +8,7 @@
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  <meta name="description" content="Claude Code session manager with web interface">
-  <meta name="theme-color" content="#0a0a0a">
+  <meta name="theme-color" content="#11151c">
  <meta name="google" content="notranslate">
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
@@ -30,21 +30,28 @@
       'defer' preserves execution order (xterm loads before fit addon). -->
  <script defer src="vendor/xterm.min.js"></script>
  <script defer src="vendor/xterm-addon-fit.min.js"></script>
+  <!-- SerializeAddon: snapshots xterm state (viewport + scrollback + attrs) for
+       per-session restore on tab switches. Lets codex tabs survive switch-away
+       without codeman having to replay codex's byte stream (which loses earlier
+       conversation because codex's TUI redraws drop it from the viewport). -->
+  <script defer src="vendor/xterm-addon-serialize.min.js"></script>
  <!-- WebGL addon lazy-loaded by app.js on desktop only (skipped on mobile, saving 244KB) -->
  <script defer src="vendor/xterm-addon-unicode11.min.js"></script>
  <script defer src="vendor/xterm-zerolag-input.js"></script>
  <script defer src="vendor/marked.min.js"></script>
  <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
  <script>if(window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024))document.documentElement.classList.add('mobile-init');</script>
+  <!-- Synchronous skin selection — runs before first paint to prevent theme flash -->
+  <script>try{var s=localStorage.getItem('codeman:skin');if(s!=='og'&&s!=='daylight-green'&&s!=='daylight-blue')s='daylight-blue';document.documentElement.dataset.skin=s;window.__codemanSkin=s;}catch(e){document.documentElement.dataset.skin='daylight-blue';window.__codemanSkin='daylight-blue';}</script>
  <!-- Inline critical CSS for instant skeleton paint (before styles.css loads) -->
  <style>
-    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#09090b}
-    .skeleton-header{height:40px;background:rgba(19,19,22,0.85);border-bottom:1px solid rgba(255,255,255,0.06);display:flex;align-items:center;padding:0 12px}
-    .skeleton-brand{color:#60a5fa;font-size:14px;font-weight:700;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.7}
+    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#11151c}
+    .skeleton-header{height:40px;background:rgba(31,38,48,0.85);border-bottom:1px solid rgba(255,255,255,0.08);display:flex;align-items:center;padding:0 12px}
+    .skeleton-brand{color:#38b6f0;font-size:14px;font-weight:700;font-family:'Manrope',-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.85}
    .skeleton-tabs{display:flex;gap:4px;margin-left:16px}
    .skeleton-tab{width:80px;height:24px;background:rgba(255,255,255,0.04);border-radius:6px}
-    .skeleton-terminal{flex:1;background:#0d0d0d}
-    .skeleton-toolbar{height:42px;background:rgba(19,19,22,0.85);border-top:1px solid rgba(255,255,255,0.06)}
+    .skeleton-terminal{flex:1;background:#161b23}
+    .skeleton-toolbar{height:42px;background:rgba(31,38,48,0.85);border-top:1px solid rgba(255,255,255,0.08)}
    .app-loaded .loading-skeleton{display:none}
  </style>
 </head>
@@ -76,7 +83,7 @@
      <!-- Detached single-session window title (shown only in solo mode) -->
      <div class="solo-session-title" id="soloSessionTitle" style="display: none;" aria-live="polite"></div>

-      <div class="header-right">
+      <div class="header-right mobile-collapsed" id="headerRight">
        <button class="btn-icon-header btn-solo-redock" id="soloRedockBtn" style="display: none;" onclick="window.close()" title="Re-dock to dashboard (close window)" aria-label="Re-dock session to dashboard">&#x229E;</button>
        <button class="tunnel-indicator" id="tunnelIndicator" style="display: none;" onclick="app.toggleTunnelPanel()" title="Cloudflare Tunnel" aria-label="Tunnel status">
          <span class="tunnel-dot"></span>
@@ -106,7 +113,7 @@
            <span class="stat-value" id="statMem">--</span>
          </div>
        </div>
-        <button class="btn-icon-header btn-response-viewer-header" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
+        <button class="btn-icon-header btn-response-viewer-header btn-response-viewer-header--hidden" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
        <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
        <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
@@ -173,8 +180,8 @@
            <svg viewBox="0 0 36 36" class="ralph-ring-svg">
              <defs>
                <linearGradient id="ralphGradientMini" x1="0%" y1="0%" x2="100%" y2="100%">
-                  <stop offset="0%" stop-color="#3b82f6" />
-                  <stop offset="100%" stop-color="#22c55e" />
+                  <stop offset="0%" stop-color="#3ec8ee" />
+                  <stop offset="100%" stop-color="#2b8fd9" />
                </linearGradient>
              </defs>
              <circle class="ralph-ring-bg" cx="18" cy="18" r="15.9" />
@@ -219,8 +226,8 @@
            <svg viewBox="0 0 100 100" class="ralph-ring-svg-large">
              <defs>
                <linearGradient id="ralphGradient" x1="0%" y1="0%" x2="100%" y2="100%">
-                  <stop offset="0%" stop-color="#3b82f6" />
-                  <stop offset="100%" stop-color="#22c55e" />
+                  <stop offset="0%" stop-color="#3ec8ee" />
+                  <stop offset="100%" stop-color="#2b8fd9" />
                </linearGradient>
              </defs>
              <circle class="ralph-ring-track" cx="50" cy="50" r="42" />
@@ -380,6 +387,9 @@
              <button class="run-mode-option" data-mode="opencode" onclick="app.setRunMode('opencode')">
                <span class="run-mode-dot opencode"></span>OpenCode
              </button>
+              <button class="run-mode-option" data-mode="codex" onclick="app.setRunMode('codex')">
+                <span class="run-mode-dot codex"></span>Codex
+              </button>
              <div class="run-mode-sep"></div>
              <div class="run-mode-header">Recent Sessions</div>
              <div class="run-mode-history" id="runModeHistory"></div>
@@ -601,17 +611,19 @@
          <div class="modal-tab-content" id="respawn-tab">
          <!-- Respawn Settings Section -->
          <div class="session-respawn-section" id="sessionRespawnSection">
-            <div class="respawn-header">
-              <div class="session-respawn-status" id="sessionRespawnStatus">
-                <span class="respawn-status-indicator"></span>
-                <span class="respawn-status-text">Not active</span>
-              </div>
-              <div class="respawn-actions">
-                <button class="btn-toolbar btn-success btn-sm" onclick="app.enableRespawnFromModal()" id="modalEnableRespawnBtn">Enable</button>
-                <button class="btn-toolbar btn-danger btn-sm" onclick="app.stopRespawnFromModal()" id="modalStopRespawnBtn" style="display: none;">Stop</button>
-              </div>
+            <div class="auto-resume-box">
+              <label class="checkbox-inline">
+                <input type="checkbox" id="modalAutoResumeEnabled" onchange="app.autoSaveAutoResume()">
+                <span>Auto-resume when usage limit resets</span>
+              </label>
+              <span class="auto-resume-status" id="autoResumeStatus"></span>
+              <span class="form-hint">If Claude pauses on a usage limit ("limit reached &middot; resets 3pm"), Codeman waits for the reset time and automatically continues the work. Independent of the respawn loop below.</span>
            </div>

+            <div class="respawn-loop-box">
+            <div class="respawn-loop-title">Respawn loop</div>
+            <span class="form-hint respawn-loop-hint">One autonomous work cycle: whenever Claude goes idle, Codeman sends the update prompt, optionally runs /clear + /init, and kickstarts the next round &mdash; repeating for the chosen duration. All settings below belong to this loop; configure them, then press Enable.</span>
+
            <div class="form-row">
              <label>Duration</label>
              <div class="duration-presets">
@@ -648,10 +660,10 @@
              <p class="form-hint" id="presetDescriptionHint"></p>
            </div>

-            <div class="form-section-header">Respawn Cycle</div>
+            <div class="form-section-header">Cycle Steps</div>
            <div class="form-row">
              <label>1. Update Prompt</label>
-              <textarea id="modalRespawnPrompt" rows="3" placeholder="Prompt to send when idle" onchange="app.autoSaveRespawnConfig()" style="resize: vertical; min-height: 60px;">update all the docs and CLAUDE.md</textarea>
+              <textarea id="modalRespawnPrompt" rows="1" placeholder="Prompt to send when idle" onchange="app.autoSaveRespawnConfig()" style="resize: vertical; min-height: 30px;">update all the docs and CLAUDE.md</textarea>
            </div>

            <div class="respawn-options-row" style="margin: 8px 0;">
@@ -663,22 +675,29 @@
                <input type="checkbox" id="modalRespawnSendInit" checked onchange="app.autoSaveRespawnConfig()">
                <span>3. Send /init</span>
              </label>
-            </div>
-
-            <div class="form-row">
-              <label>4. Kickstart Prompt</label>
-              <textarea id="modalRespawnKickstart" rows="2" placeholder="Optional: prompt if /init doesn't trigger work" onchange="app.autoSaveRespawnConfig()" style="resize: vertical; min-height: 40px;"></textarea>
-              <span class="form-hint">Sent only when /init completes but Claude stays idle</span>
-            </div>
-
-            <div class="form-section-header">Behavior</div>
-            <div class="respawn-options-row">
-              <label class="checkbox-inline">
+              <label class="checkbox-inline" title="Presses Enter for plan approvals and default question options">
                <input type="checkbox" id="modalRespawnAutoAccept" checked onchange="app.autoSaveRespawnConfig()">
                <span>Auto-accept prompts</span>
              </label>
            </div>
-            <span class="form-hint">Auto-accept presses Enter for plan approvals and default question options</span>
+
+            <div class="form-row">
+              <label>4. Kickstart Prompt</label>
+              <textarea id="modalRespawnKickstart" rows="1" placeholder="Optional: prompt if /init doesn't trigger work" onchange="app.autoSaveRespawnConfig()" style="resize: vertical; min-height: 30px;"></textarea>
+              <span class="form-hint">Sent only when /init completes but Claude stays idle &middot; Auto-accept presses Enter for plan approvals and default options</span>
+            </div>
+
+            <div class="respawn-header">
+              <div class="session-respawn-status" id="sessionRespawnStatus">
+                <span class="respawn-status-indicator"></span>
+                <span class="respawn-status-text">Not active</span>
+              </div>
+              <div class="respawn-actions">
+                <button class="btn-toolbar btn-success btn-sm" onclick="app.enableRespawnFromModal()" id="modalEnableRespawnBtn">Enable</button>
+                <button class="btn-toolbar btn-danger btn-sm" onclick="app.stopRespawnFromModal()" id="modalStopRespawnBtn" style="display: none;">Stop</button>
+              </div>
+            </div>
+            </div><!-- End respawn-loop-box -->
          </div>
          </div><!-- End respawn-tab -->

@@ -891,6 +910,7 @@
        <div class="modal-tabs">
          <button class="modal-tab-btn active" data-tab="settings-display">Display</button>
          <button class="modal-tab-btn" data-tab="settings-claude">Claude CLI</button>
+          <button class="modal-tab-btn" data-tab="settings-codex">Codex CLI</button>
          <button class="modal-tab-btn" data-tab="settings-models">Models</button>
          <button class="modal-tab-btn" data-tab="settings-paths">Paths</button>
          <button class="modal-tab-btn" data-tab="settings-notifications">Notifications</button>
@@ -900,6 +920,16 @@
          <!-- Display Tab -->
          <div class="modal-tab-content" id="settings-display">
            <div class="settings-grid">
+              <!-- Appearance Section -->
+              <div class="settings-section-header">Appearance</div>
+              <div class="settings-item settings-item-skin" title="Visual theme for this device (not synced)">
+                <span class="settings-item-label">Skin</span>
+                <select id="appSettingsSkin" class="form-select">
+                  <option value="daylight-blue">Daylight Blue</option>
+                  <option value="daylight-green">Daylight Green</option>
+                  <option value="og">OG Codeman</option>
+                </select>
+              </div>
              <!-- Input Section -->
              <div class="settings-section-header">Input</div>
              <div class="settings-item settings-item-multiline" title="Shows typed characters instantly via overlay while forwarding keystrokes to the server in the background. Enables Tab completion, preserves input across tab switches, and protects against session crashes. Recommended for mobile and high-latency connections.">
@@ -981,6 +1011,13 @@
                  <span class="slider"></span>
                </label>
              </div>
+              <div class="settings-item" title="Show the response viewer (eye) button in header">
+                <span class="settings-item-label">Response Viewer</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsShowResponseViewer">
+                  <span class="slider"></span>
+                </label>
+              </div>
              <div class="settings-item" title="Show the multi-monitor button in the header (opens Codeman spanned across all displays)">
                <span class="settings-item-label">Multi-monitor Button</span>
                <label class="switch switch-sm">
@@ -1133,13 +1170,26 @@
              </label>
              <span class="form-hint">Enable experimental Agent Teams for all new Claude sessions (disabled by default)</span>
            </div>
+            <div class="form-row">
+              <label>Claude Model</label>
+              <select id="appSettingsClaudeModel" class="form-select">
+                <option value="">Default (CLI setting)</option>
+                <option value="claude-fable-5[1m]">Fable 5 (1M context)</option>
+                <option value="claude-fable-5">Fable 5</option>
+                <option value="opus[1m]">Opus (1M context)</option>
+                <option value="opus">Opus</option>
+                <option value="sonnet">Sonnet</option>
+                <option value="haiku">Haiku</option>
+              </select>
+              <span class="form-hint">Model for new Claude sessions (pinned via the case's .claude/settings.local.json) — takes precedence over the 1M Opus toggle below</span>
+            </div>
            <div class="form-row form-row-switch">
              <label>1M Opus Context</label>
              <label class="switch">
                <input type="checkbox" id="appSettingsOpusContext1m">
                <span class="slider"></span>
              </label>
-              <span class="form-hint">Use 1M token context window (model: opus[1m]) for all new sessions</span>
+              <span class="form-hint">Use 1M token context window (model: opus[1m]) for all new sessions — ignored when a Claude Model is selected above</span>
            </div>
            <div class="form-row">
              <label>Thinking Effort</label>
@@ -1170,12 +1220,25 @@
              <span class="form-hint">Process priority (-20 to 19, higher = lower priority, default: 10)</span>
            </div>
          </div>
+          <!-- Codex CLI Tab -->
+          <div class="modal-tab-content hidden" id="settings-codex">
+            <div class="form-section-header">Codex CLI</div>
+            <div class="form-row form-row-switch">
+              <label>Bypass Approvals and Sandbox</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsCodexDangerouslyBypassApprovals">
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Start new Codex sessions with --dangerously-bypass-approvals-and-sandbox</span>
+            </div>
+          </div>
          <!-- Models Tab -->
          <div class="modal-tab-content hidden" id="settings-models">
            <div class="form-row">
              <label>Default Model</label>
              <select id="appSettingsDefaultModel" class="form-select">
                <option value="">Default (CLI default)</option>
+                <option value="claude-fable-5">Fable 5 (Most powerful)</option>
                <option value="opus">Opus (Most capable)</option>
                <option value="sonnet">Sonnet (Balanced)</option>
                <option value="haiku">Haiku (Fast & cheap)</option>
@@ -1199,6 +1262,7 @@
                <option value="haiku">Haiku</option>
                <option value="sonnet">Sonnet</option>
                <option value="opus">Opus</option>
+                <option value="claude-fable-5">Fable 5</option>
              </select>
              <span class="form-hint">Quick searches, codebase exploration</span>
            </div>
@@ -1209,6 +1273,7 @@
                <option value="haiku">Haiku</option>
                <option value="sonnet">Sonnet</option>
                <option value="opus">Opus</option>
+                <option value="claude-fable-5">Fable 5</option>
              </select>
              <span class="form-hint">Code writing, feature implementation</span>
            </div>
@@ -1219,6 +1284,7 @@
                <option value="haiku">Haiku</option>
                <option value="sonnet">Sonnet</option>
                <option value="opus">Opus</option>
+                <option value="claude-fable-5">Fable 5</option>
              </select>
              <span class="form-hint">Writing and running tests</span>
            </div>
@@ -1229,6 +1295,7 @@
                <option value="haiku">Haiku</option>
                <option value="sonnet">Sonnet</option>
                <option value="opus">Opus</option>
+                <option value="claude-fable-5">Fable 5</option>
              </select>
              <span class="form-hint">Code review, quality checks</span>
            </div>
@@ -41,6 +41,8 @@
 // eslint-disable-next-line no-unused-vars
 const CjkInput = (() => {
  let _textarea = null;
+  let _terminalContainer = null;
+  let _xtermTextarea = null;
  let _send = null;
  let _initialized = false;
  let _composing = false;
@@ -75,6 +77,23 @@ const CjkInput = (() => {
    _textarea.setSelectionRange(1, 1);
  }

+  function _isMobileComposer() {
+    return !!(
+      _textarea &&
+      typeof MobileDetection !== 'undefined' &&
+      MobileDetection.isTouchDevice() &&
+      _textarea.classList.contains('cjk-input-visible')
+    );
+  }
+
+  function _resetInput() {
+    if (_isMobileComposer()) {
+      _textarea.value = '';
+    } else {
+      _resetToPhantom();
+    }
+  }
+
  /** Check if textarea contains only phantom(s) or is empty — no real user text */
  function _isEffectivelyEmpty() {
    return !_strip(_textarea.value);
@@ -97,24 +116,44 @@ const CjkInput = (() => {
      _composing = false;
      _textarea = document.getElementById('cjkInput');
      if (!_textarea) return this;
+      _terminalContainer = document.getElementById('terminalContainer');

-      // Seed the phantom character
-      _resetToPhantom();
+      // Seed the phantom character for the hidden/immediate CJK path.
+      _resetInput();

      _listeners.mousedown = (e) => { e.stopPropagation(); };
      _listeners.focus = () => {
        window.cjkActive = true;
+        if (_isMobileComposer() && _textarea.value === PHANTOM) {
+          _textarea.value = '';
+          return;
+        }
        // Restore phantom if textarea was emptied while blurred
-        if (!_textarea.value) _resetToPhantom();
+        if (!_textarea.value && !_isMobileComposer()) _resetToPhantom();
      };
      _listeners.blur = () => { window.cjkActive = false; };
      _textarea.addEventListener('mousedown', _listeners.mousedown);
      _textarea.addEventListener('focus', _listeners.focus);
      _textarea.addEventListener('blur', _listeners.blur);

+      _listeners.xtermFocusRedirect = () => {
+        if (!_isMobileComposer()) return;
+        _textarea.focus();
+      };
+      if (_terminalContainer) {
+        _xtermTextarea = _terminalContainer.querySelector('.xterm-helper-textarea');
+        if (_xtermTextarea) {
+          _xtermTextarea.addEventListener('focus', _listeners.xtermFocusRedirect, { capture: true });
+        }
+      }
+
      // ── Composition tracking ──
      _listeners.compositionstart = () => {
        _composing = true;
+        if (_isMobileComposer()) {
+          if (_textarea.value === PHANTOM) _textarea.value = '';
+          return;
+        }
        // Clear phantom so IME sees a clean textarea — some IMEs include
        // existing text in the composition region which would corrupt input.
        if (_textarea.value === PHANTOM) {
@@ -123,6 +162,7 @@ const CjkInput = (() => {
      };
      _listeners.compositionend = () => {
        _composing = false;
+        if (_isMobileComposer()) return;
        // Defer flush: some Android IMEs haven't committed text to textarea
        // when compositionend fires. setTimeout(0) ensures we read the final value.
        setTimeout(_flush, 0);
@@ -145,7 +185,7 @@ const CjkInput = (() => {
          } else {
            _send('\r');
          }
-          _resetToPhantom();
+          _resetInput();
          return;
        }

@@ -153,7 +193,7 @@ const CjkInput = (() => {
        if (e.key === 'Escape') {
          e.preventDefault();
          _composing = false;
-          _resetToPhantom();
+          _resetInput();
          return;
        }

@@ -167,6 +207,19 @@ const CjkInput = (() => {
        // Below: only when NOT composing (composing keystrokes belong to IME)
        if (_composing) return;

+        if (_isMobileComposer()) {
+          if (e.key === 'Backspace' && _isEffectivelyEmpty()) {
+            e.preventDefault();
+            _send('\x7f');
+            return;
+          }
+          if (PASSTHROUGH_KEYS[e.key] && _isEffectivelyEmpty()) {
+            e.preventDefault();
+            _send(PASSTHROUGH_KEYS[e.key]);
+          }
+          return;
+        }
+
        // Backspace: forward to PTY when no real text in textarea
        // (Desktop path — Android uses the input event + phantom approach)
        if (e.key === 'Backspace' && _isEffectivelyEmpty()) {
@@ -198,6 +251,13 @@ const CjkInput = (() => {
      // making keydown unreliable. input fires AFTER character insertion and
      // carries inputType which tells us whether the text is final or tentative.
      _listeners.input = (e) => {
+        if (_isMobileComposer()) {
+          if (_textarea.value.includes(PHANTOM)) {
+            _textarea.value = _strip(_textarea.value);
+          }
+          return;
+        }
+
        // ── Backspace / delete detection ──
        // Android long-press backspace generates rapid deleteContentBackward events.
        // The phantom character ensures the textarea is never truly empty, so each
@@ -245,8 +305,13 @@ const CjkInput = (() => {
          if (handler) _textarea.removeEventListener(event, handler);
        }
      }
+      if (_xtermTextarea && _listeners.xtermFocusRedirect) {
+        _xtermTextarea.removeEventListener('focus', _listeners.xtermFocusRedirect, { capture: true });
+      }
      window.cjkActive = false;
      _composing = false;
+      _terminalContainer = null;
+      _xtermTextarea = null;
      for (const key of Object.keys(_listeners)) delete _listeners[key];
      _initialized = false;
    },
@@ -4,7 +4,7 @@
 * Defines two exports:
 *
 * - KeyboardAccessoryBar (singleton object) — Quick action buttons shown above the virtual
- *   keyboard on mobile: arrow up/down, /init, /clear, paste, and dismiss.
+ *   keyboard on mobile: arrow up/down, /init, /clear, paste, Esc, and dismiss.
 *   The paste button opens a dialog that handles both text paste and image attach
 *   (native picker + best-effort image paste, routed through app._uploadAndInsertImages).
 *   Destructive actions (/clear) require double-tap confirmation (2s amber state).
@@ -37,7 +37,7 @@ const KeyboardAccessoryBar = {
  element: null,
  _mode: 'simple', // 'simple' or 'extended'

-  /** HTML for simple mode: arrows, commands, paste, dismiss */
+  /** HTML for simple mode: arrows, commands, paste, Esc, dismiss */
  _simpleButtons: `
      <button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
@@ -57,6 +57,7 @@ const KeyboardAccessoryBar = {
          <rect x="8" y="2" width="8" height="4" rx="1" ry="1"/>
        </svg>
      </button>
+      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
      <button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
          <path d="M19 9l-7 7-7-7"/>
@@ -255,10 +255,9 @@ const KeyboardHandler = {
    if (heightDiff > 150 && !this.keyboardVisible) {
      this.keyboardVisible = true;
      document.body.classList.add('keyboard-visible');
-      // Restore --app-height: MobileDetection's resize listener fires before ours
-      // and may have already shrunk it for the keyboard viewport change.
-      // Use initialViewportHeight (captured before keyboard opened).
-      document.documentElement.style.setProperty('--app-height', `${this.initialViewportHeight}px`);
+      // While the keyboard is open, size the app to the visual viewport so
+      // xterm's bottom row and cursor sit above the OS keyboard.
+      document.documentElement.style.setProperty('--app-height', `${currentHeight}px`);
      this.onKeyboardShow();
    }
    // Keyboard hidden (viewport grew back close to initial)
@@ -277,6 +276,8 @@ const KeyboardHandler = {
    // state changes, orientation changes, and other viewport shifts
    if (!this.keyboardVisible) {
      this.initialViewportHeight = currentHeight;
+    } else {
+      document.documentElement.style.setProperty('--app-height', `${currentHeight}px`);
    }

    this.updateLayoutForKeyboard();
@@ -295,6 +296,7 @@ const KeyboardHandler = {

    const toolbar = document.querySelector('.toolbar');
    const accessoryBar = document.querySelector('.keyboard-accessory-bar');
+    const cjkInput = document.getElementById('cjkInput');
    const main = document.querySelector('.main');

    if (this.keyboardVisible) {
@@ -302,6 +304,15 @@ const KeyboardHandler = {
      // translate up so it sits at the bottom of the visual viewport.
      // This formula accounts for iOS scrolling the visual viewport (offsetTop)
      // when the user types in xterm's hidden textarea.
+      //
+      // MUST measure against the LAYOUT viewport (window.innerHeight): the
+      // bars are position:fixed, which anchors to the layout viewport — on
+      // iOS that keeps its full height while the keyboard is open. Measuring
+      // the shrunken .app instead (its height tracks --app-height = visual
+      // viewport) made the offset compute to 0 on iOS, leaving the toolbar
+      // and accessory bar behind the OS keyboard (0.9.8 regression). On
+      // Android the layout viewport itself shrinks with the keyboard, so
+      // innerHeight === visualBottom and the offset is naturally 0 there.
      const layoutHeight = window.innerHeight;
      const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
      const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
@@ -317,13 +328,17 @@ const KeyboardHandler = {
      if (accessoryBar) {
        accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
      }
+      if (cjkInput?.classList.contains('cjk-input-visible')) {
+        cjkInput.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
+      }

-      // Shrink main content area so terminal doesn't extend behind keyboard.
-      // Use stable keyboard height (not scroll-dependent) for padding.
-      // 84px = toolbar (40px) + accessory bar (44px).
+      // Reserve only Codeman's visible controls. The OS keyboard is outside
+      // the visual viewport; adding its height here creates a large blank area
+      // above the mobile toolbar on iPhone.
      const keyboardHeight = this.initialViewportHeight - (window.visualViewport.height || window.innerHeight);
      if (main && keyboardHeight > 0) {
-        main.style.paddingBottom = `${keyboardHeight + 84}px`;
+        const cjkInputHeight = cjkInput?.classList.contains('cjk-input-visible') ? 44 : 0;
+        main.style.paddingBottom = `${84 + cjkInputHeight}px`;
      }
    } else {
      this.resetLayout();
@@ -334,6 +349,7 @@ const KeyboardHandler = {
  resetLayout() {
    const toolbar = document.querySelector('.toolbar');
    const accessoryBar = document.querySelector('.keyboard-accessory-bar');
+    const cjkInput = document.getElementById('cjkInput');
    const main = document.querySelector('.main');

    if (toolbar) {
@@ -342,6 +358,9 @@ const KeyboardHandler = {
    if (accessoryBar) {
      accessoryBar.style.transform = '';
    }
+    if (cjkInput) {
+      cjkInput.style.transform = '';
+    }
    if (main) {
      main.style.paddingBottom = '';
    }
@@ -376,6 +395,8 @@ const KeyboardHandler = {
        // to the accessory bar.
        this._shrinkPaddingToFit();
        app.terminal.scrollToBottom();
+        app._syncMobileHelperTextareaToCursor?.();
+        app._localEchoOverlay?.rerender?.();
        // Send resize to server so PTY dimensions match xterm
        this._sendTerminalResize();
      }
@@ -421,10 +442,13 @@ const KeyboardHandler = {
        const cols = Math.max(dims.cols, 40);
        const rows = Math.max(dims.rows, 10);
        app._lastResizeDims = { cols, rows };
+        // Declare the viewport type so resize arbitration can ignore this
+        // while a desktop connection is sizing the same session.
+        const viewportType = MobileDetection.getDeviceType ? MobileDetection.getDeviceType() : 'mobile';
        fetch(`/api/sessions/${app.activeSessionId}/resize`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ cols, rows }),
+          body: JSON.stringify({ cols, rows, viewportType }),
        }).catch(() => {});
      }
    } catch {}
@@ -36,6 +36,13 @@ html.mobile-init .file-browser-panel {
  html {
    touch-action: manipulation;
  }
+
+  /* No "open in new window" (detach) on phones/tablets — popped-out browser
+     windows aren't usable there. !important beats the hover/detached reveal
+     rules in styles.css */
+  .session-tab .tab-detach {
+    display: none !important;
+  }
 }

 /* ============================================================================
@@ -55,7 +62,9 @@ html.mobile-init .file-browser-panel {
    padding-right: calc(0.5rem + var(--safe-area-right));
    background: #0a0a0a;
    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
-    z-index: 200;
+    contain: none;
+    overflow: visible;
+    z-index: 1200;
  }

  /* iOS safe area adjustment for fixed header - header extends into notch area */
@@ -93,7 +102,35 @@ html.mobile-init .file-browser-panel {
  }

  .header-right {
+    position: fixed;
+    top: calc(52px + var(--safe-area-top));
+    left: calc(0.5rem + var(--safe-area-left));
+    right: auto;
+    display: flex;
+    align-items: center;
    gap: 0.35rem;
+    max-width: calc(100vw - 1rem - var(--safe-area-left) - var(--safe-area-right));
+    padding: 0.35rem;
+    background: rgba(10, 10, 10, 0.96);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 8px;
+    box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
+    overflow-x: auto;
+    scrollbar-width: none;
+    z-index: 2000;
+  }
+
+  .header-right::-webkit-scrollbar {
+    display: none;
+  }
+
+  .header-right.mobile-collapsed {
+    display: none;
+  }
+
+  .btn-icon-header:not(.btn-sm) {
+    width: 44px;
+    height: 44px;
  }

  /* Compact session tabs — .tabs-two-rows override needed to match
@@ -170,6 +207,12 @@ html.mobile-init .file-browser-panel {

  /* ---- Settings Modal: Tablet Optimizations ---- */

+  /* Modals must stack above the fixed tablet header (z-index 1200) so the
+     modal header with the close button stays visible */
+  .modal {
+    z-index: 1300;
+  }
+
  .modal-tabs {
    overflow-x: auto;
    -webkit-overflow-scrolling: touch;
@@ -355,7 +398,8 @@ html.mobile-init .file-browser-panel {
    overflow: hidden;
    background: #0a0a0a;
    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
-    z-index: 200;
+    contain: none;
+    z-index: 1200;
  }

  /* iOS safe area adjustment for fixed header - header extends into notch area */
@@ -391,10 +435,32 @@ html.mobile-init .file-browser-panel {
  }

  .header-right {
+    position: fixed;
+    top: calc(40px + var(--safe-area-top));
+    left: calc(0.3rem + var(--safe-area-left));
+    right: auto;
+    display: flex;
+    align-items: center;
    padding-left: 0.2rem;
    gap: 0.1rem;
-    flex-shrink: 0;
+    max-width: calc(100vw - 0.6rem - var(--safe-area-left) - var(--safe-area-right));
+    padding: 0.25rem;
+    background: rgba(10, 10, 10, 0.96);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 8px;
+    box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
+    overflow-x: auto;
+    scrollbar-width: none;
    border-left: none;
+    z-index: 2000;
+  }
+
+  .header-right::-webkit-scrollbar {
+    display: none;
+  }
+
+  .header-right.mobile-collapsed {
+    display: none;
  }

  /* Smaller header buttons on mobile */
@@ -445,7 +511,18 @@ html.mobile-init .file-browser-panel {
    background: rgba(239, 68, 68, 0.25);
    border-color: rgba(239, 68, 68, 0.6);
    color: #ef4444;
-    animation: voice-pulse 1.2s ease-in-out infinite;
+    animation: mobile-voice-pulse 1.2s ease-in-out infinite;
+  }
+
+  @keyframes mobile-voice-pulse {
+    0%, 100% {
+      box-shadow: inset 0 0 0 1px rgba(239, 68, 68, 0.35);
+      background: rgba(239, 68, 68, 0.2);
+    }
+    50% {
+      box-shadow: inset 0 0 0 2px rgba(239, 68, 68, 0.75);
+      background: rgba(239, 68, 68, 0.35);
+    }
  }

  /* Mobile app settings gear in toolbar - far right */
@@ -491,7 +568,8 @@ html.mobile-init .file-browser-panel {
    top: 0;
    left: 0;
    right: 0;
-    bottom: 0;
+    bottom: auto;
+    height: var(--app-height, 100dvh);
  }

  /* Ultra-compact session tabs — .tabs-two-rows override needed to match
@@ -548,10 +626,10 @@ html.mobile-init .file-browser-panel {
    display: inline-flex;
    align-items: center;
    justify-content: center;
-    font-size: 0.5rem;
+    font-size: 0.65rem;
    line-height: 1;
-    width: 12px;
-    height: 12px;
+    width: 32px;
+    height: 32px;
    margin-left: auto;
    opacity: 0.6;
  }
@@ -617,6 +695,10 @@ html.mobile-init .file-browser-panel {
    align-items: center;
  }

+  .toolbar-center .btn-toolbar.btn-voice {
+    display: none !important;
+  }
+
  .toolbar-right {
    display: none !important;
  }
@@ -798,9 +880,17 @@ html.mobile-init .file-browser-panel {

  .btn-toolbar.btn-shell {
    flex: 0 0 auto;
-    min-width: fit-content;
+    min-width: 54px;
+    width: 54px;
    white-space: nowrap;
-    padding: 0 10px !important;
+    padding: 0 8px !important;
+    overflow: hidden;
+    font-size: 0 !important;
+  }
+
+  .btn-toolbar.btn-shell::after {
+    content: "Shell";
+    font-size: 0.65rem;
  }

  /* Mobile case button - visible on mobile */
@@ -843,6 +933,24 @@ html.mobile-init .file-browser-panel {
    color: #fff;
  }

+  @media (max-width: 374px) {
+    .toolbar {
+      padding: 0 2px;
+    }
+
+    .toolbar-left,
+    .toolbar-left .toolbar-group,
+    .toolbar-left .toolbar-group:first-child {
+      gap: 2px;
+    }
+  }
+
+  @media (max-width: 430px) {
+    .btn-case-settings-mobile {
+      display: none !important;
+    }
+  }
+
  /* Mobile case settings popover */
  .case-settings-popover-mobile {
    position: fixed;
@@ -1120,6 +1228,13 @@ html.mobile-init .file-browser-panel {
    max-height: 35vh;
  }

+  /* Modals must stack above the fixed mobile header (z-index 1200), or the
+     modal header with the close button is buried underneath it and the
+     full-screen modal cannot be dismissed */
+  .modal {
+    z-index: 1300;
+  }
+
  /* Full-screen modals on phones */
  .modal-content {
    width: 100%;
@@ -1243,6 +1358,16 @@ html.mobile-init .file-browser-panel {
    font-size: 0.85rem;
  }

+  .history-show-more {
+    display: block;
+    margin-bottom: 0.75rem;
+  }
+
+  .welcome-ralph-link {
+    display: block;
+    margin: 0.75rem auto 0;
+  }
+
  .welcome-hint {
    font-size: 0.7rem;
    margin-top: 0.75rem;
@@ -1423,42 +1548,36 @@ html.mobile-init .file-browser-panel {
    border-radius: 5px;
  }

-  /* Duration preset buttons — grid layout, 4 columns for even spacing */
+  /* Duration preset buttons — one compact row */
  .duration-presets {
-    display: grid;
-    grid-template-columns: repeat(4, 1fr);
+    display: flex;
+    flex-wrap: wrap;
    gap: 0.2rem;
  }

  .duration-preset-btn {
-    min-height: 32px;
-    padding: 0.2rem 0.25rem;
-    font-size: 0.65rem;
-    border-radius: 5px;
+    min-height: 24px;
+    padding: 0.1rem 0.4rem;
+    font-size: 0.6rem;
+    border-radius: 4px;
    text-align: center;
  }

-  /* Custom duration — spans full row below */
  .duration-custom {
-    grid-column: 1 / -1;
    display: flex;
-    gap: 0.25rem;
+    gap: 0.2rem;
    align-items: center;
  }

-  .duration-custom .duration-preset-btn {
-    flex: 0 0 auto;
-    min-width: 50px;
-  }
-
  .duration-custom-input.visible {
-    flex: 1;
+    flex: 0 1 auto;
  }

  .duration-custom-input input {
-    width: 100%;
-    min-height: 28px;
+    width: 64px;
+    min-height: 24px;
    font-size: 16px; /* Prevents iOS zoom */
+    padding: 0.1rem 0.3rem;
  }

  /* Preset selector row — full-width dropdown, buttons below */
@@ -1517,6 +1636,16 @@ html.mobile-init .file-browser-panel {
    height: 18px;
  }

+  /* Respawn-loop box title matches the auto-resume title; its cycle-step
+     checkboxes match the step labels */
+  #sessionOptionsModal .respawn-loop-title {
+    font-size: 0.75rem;
+  }
+
+  #sessionOptionsModal .respawn-loop-box .checkbox-inline {
+    font-size: 0.65rem;
+  }
+
  /* Respawn options row — stack if needed */
  #sessionOptionsModal .respawn-options-row {
    gap: 0.5rem;
@@ -182,7 +182,7 @@ Object.assign(CodemanApp.prototype, {
        body: JSON.stringify({ goal, config }),
      });
      const data = await res.json();
-      if (data.ok) {
+      if (data.data?.ok) {
        this.orchestratorState = { state: 'planning', plan: null };
        this.showOrchestratorPanel();
        this.renderOrchestratorPanel();
@@ -259,8 +259,8 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch('/api/orchestrator/status');
      const data = await res.json();
-      if (data.ok) {
-        this.orchestratorState = data;
+      if (data.data?.ok) {
+        this.orchestratorState = data.data;
        this.renderOrchestratorPanel();
      }
    } catch (err) {
@@ -251,7 +251,7 @@ Object.assign(CodemanApp.prototype, {
      const response = await fetch('/api/token-stats');
      const data = await response.json();
      if (data.success) {
-        this.renderTokenStats(data);
+        this.renderTokenStats(data.data);
        document.getElementById('tokenStatsModal').classList.add('active');
      } else {
        this.showToast('Failed to load token stats', 'error');
@@ -380,6 +380,9 @@ Object.assign(CodemanApp.prototype, {
    panel.classList.toggle('open');

    if (panel.classList.contains('open')) {
+      // applyMonitorVisibility() sets inline display:none when the "Show Monitor"
+      // setting is off — clear it so transient opens (session-tab task badge) work
+      panel.style.display = '';
      // Load screens and start stats collection
      await this.loadMuxSessions();
      await fetch('/api/mux-sessions/stats/start', { method: 'POST' });
@@ -1547,29 +1550,7 @@ Object.assign(CodemanApp.prototype, {
      }

      const terminal = new Terminal({
-        theme: {
-          background: '#0d0d0d',
-          foreground: '#e0e0e0',
-          cursor: '#e0e0e0',
-          cursorAccent: '#0d0d0d',
-          selection: 'rgba(255, 255, 255, 0.3)',
-          black: '#0d0d0d',
-          red: '#ff6b6b',
-          green: '#51cf66',
-          yellow: '#ffd43b',
-          blue: '#339af0',
-          magenta: '#cc5de8',
-          cyan: '#22b8cf',
-          white: '#e0e0e0',
-          brightBlack: '#495057',
-          brightRed: '#ff8787',
-          brightGreen: '#69db7c',
-          brightYellow: '#ffe066',
-          brightBlue: '#5c7cfa',
-          brightMagenta: '#da77f2',
-          brightCyan: '#66d9e8',
-          brightWhite: '#ffffff',
-        },
+        theme: { ...window.codemanCurrentXtermTheme() },
        fontFamily: '"Fira Code", "Cascadia Code", "JetBrains Mono", "SF Mono", Monaco, monospace',
        fontSize: 12,
        lineHeight: 1.2,
@@ -2881,7 +2862,7 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch('/api/mux-sessions');
      const data = await res.json();
-      this.muxSessions = data.sessions || [];
+      this.muxSessions = data.data?.sessions || [];
      this.renderMuxSessions();
    } catch (err) {
      console.error('Failed to load mux sessions:', err);
@@ -3109,8 +3090,8 @@ Object.assign(CodemanApp.prototype, {
      const res = await fetch('/api/mux-sessions/reconcile', { method: 'POST' });
      const data = await res.json();

-      if (data.dead && data.dead.length > 0) {
-        this.showToast(`Found ${data.dead.length} dead mux session(s)`, 'warning');
+      if (data.data?.dead && data.data.dead.length > 0) {
+        this.showToast(`Found ${data.data.dead.length} dead mux session(s)`, 'warning');
        await this.loadMuxSessions();
      } else {
        this.showToast('All mux sessions are alive', 'success');
@@ -3220,7 +3201,7 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch('/api/system/stats');
      const stats = await res.json();
-      this.updateSystemStatsDisplay(stats);
+      this.updateSystemStatsDisplay(stats.data);
    } catch (err) {
      // Silently fail - system stats are not critical
    }
@@ -996,14 +996,14 @@ Object.assign(CodemanApp.prototype, {
        return;
      }

-      const history = data.history || [];
+      const history = data.data.history || [];
      if (history.length === 0) {
        this.showToast('No plan history available', 'info');
        return;
      }

      // Show history dropdown modal
-      this.showPlanHistoryModal(history, data.currentVersion);
+      this.showPlanHistoryModal(history, data.data.currentVersion);
    } catch (err) {
      this.showToast('Failed to load plan history: ' + err.message, 'error');
    }
@@ -1035,7 +1035,7 @@ Object.assign(CodemanApp.prototype, {
                   onclick="app.rollbackToPlanVersion(${item.version})">
                <div>
                  <span class="plan-history-version">v${item.version}</span>
-                  <span class="plan-history-tasks">${item.taskCount || 0} tasks</span>
+                  <span class="plan-history-tasks">${item.stats?.total ?? 0} tasks</span>
                </div>
                <span class="plan-history-time">${this.formatRelativeTime(item.timestamp)}</span>
              </div>
@@ -151,11 +151,11 @@ Object.assign(CodemanApp.prototype, {
      const res = await fetch(`/api/cases/${encodeURIComponent(caseName)}/fix-plan`);
      const data = await res.json();

-      if (data.success && data.exists && data.todos?.length > 0) {
+      if (data.success && data.data.exists && data.data.todos?.length > 0) {
        this.ralphWizardConfig.existingPlan = {
-          todos: data.todos,
-          stats: data.stats,
-          content: data.content,
+          todos: data.data.todos,
+          stats: data.data.stats,
+          content: data.data.content,
        };
        this.updateExistingPlanUI();
      } else {
@@ -378,7 +378,10 @@ Object.assign(CodemanApp.prototype, {
    prompt += `Output \`<promise>${config.completionPhrase}</promise>\` when done\n\n`;

    prompt += '## If Stuck\n';
-    prompt += 'Output `<promise>BLOCKED</promise>` with explanation';
+    prompt += 'Output `<promise>BLOCKED</promise>` with explanation\n\n';
+
+    prompt += '## Status Reporting\n';
+    prompt += '• End every response with a `RALPH_STATUS` block (parsed by Codeman)';

    // Show preview with highlighting (escape first, then apply formatting)
    const escapedPrompt = escapeHtml(prompt);
@@ -1054,8 +1057,8 @@ Object.assign(CodemanApp.prototype, {
        this.showToast(data.error || 'Failed to start', 'error');
        return;
      }
-      this.ralphClosedSessions.delete(data.sessionId);
-      await this.selectSession(data.sessionId);
+      this.ralphClosedSessions.delete(data.data.sessionId);
+      await this.selectSession(data.data.sessionId);
      this.showToast(`Ralph Loop started in ${config.caseName}`, 'success');
    } catch (err) {
      console.error('Failed to start Ralph loop:', err);
@@ -1041,7 +1041,7 @@ Object.assign(CodemanApp.prototype, {
        return;
      }

-      this.runSummaryData = data.summary;
+      this.runSummaryData = data.data.summary;
      this.renderRunSummary();
    } catch (err) {
      console.error('Failed to load run summary:', err);
@@ -49,7 +49,7 @@ Object.assign(CodemanApp.prototype, {
      // Load settings to get lastUsedCase (reuse shared promise if provided)
      let lastUsedCase = null;
      try {
-        const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null);
+        const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.data ?? null);
        if (settings) {
          lastUsedCase = settings.lastUsedCase || null;
        }
@@ -58,7 +58,7 @@ Object.assign(CodemanApp.prototype, {
      }

      const res = await fetch('/api/cases');
-      const cases = await res.json();
+      const cases = (await res.json()).data;
      this.cases = cases;
      console.log('[loadQuickStartCases] Loaded cases:', cases.map(c => c.name), 'lastUsedCase:', lastUsedCase);

@@ -125,7 +125,7 @@ Object.assign(CodemanApp.prototype, {
  async updateDirDisplayForCase(caseName) {
    try {
      const res = await fetch(`/api/cases/${caseName}`);
-      const data = await res.json();
+      const data = (await res.json()).data;
      if (data.path) {
        document.getElementById('dirDisplay').textContent = data.path;
        document.getElementById('dirInput').value = data.path;
@@ -151,17 +151,21 @@ Object.assign(CodemanApp.prototype, {
    return this.run();
  },

-  /** Run using the selected mode (Claude Code or OpenCode) */
+  /** Run using the selected mode (Claude Code, OpenCode, or Codex) */
  async run() {
    const mode = this._runMode || 'claude';
    if (mode === 'opencode') {
      return this.runOpenCode();
    }
+    if (mode === 'codex') {
+      return this.runCodex();
+    }
    return this.runClaude();
  },

-  /** Get/set the run mode, persisted in localStorage */
-  get runMode() { return this._runMode || 'claude'; },
+  // Note: `runMode` is an accessor defined via Object.defineProperty at the bottom of
+  // this file — an object-literal getter here would be flattened to a static value by
+  // Object.assign (it copies values, not accessor descriptors).

  setRunMode(mode) {
    this._runMode = mode;
@@ -253,7 +257,7 @@ Object.assign(CodemanApp.prototype, {
      gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
    }
    if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : 'Run';
    }
  },

@@ -304,7 +308,7 @@ Object.assign(CodemanApp.prototype, {
    try {
      // Get case path first
      const caseRes = await fetch(`/api/cases/${caseName}`);
-      let caseData = await caseRes.json();
+      let caseData = (await caseRes.json())?.data ?? {};

      // Create the case if it doesn't exist
      if (!caseData.path) {
@@ -350,8 +354,10 @@ Object.assign(CodemanApp.prototype, {
      const envOverrides = this.buildEnvOverrides(caseSettings, globalSettings);
      const hasEnvOverrides = Object.keys(envOverrides).length > 0;
      const effort = this.getEffortSetting(globalSettings);
+      // Explicit Claude Model choice (App Settings) wins over the legacy 1M Opus
+      // toggles; both flow as `modelOverride` → the case's .claude/settings.local.json
      const useOpus1m = caseSettings.opusContext1m || globalSettings.opusContext1mEnabled;
-      const modelOverride = useOpus1m ? 'opus[1m]' : '';
+      const modelOverride = globalSettings.claudeModel || (useOpus1m ? 'opus[1m]' : '');

      // Step 1: Create all sessions in parallel
      this.terminal.writeln(`\x1b[90m Creating ${tabCount} session(s)...\x1b[0m`);
@@ -373,7 +379,7 @@ Object.assign(CodemanApp.prototype, {
      const sessionIds = [];
      for (const result of createResults) {
        if (!result.success) throw new Error(result.error);
-        sessionIds.push(result.session.id);
+        sessionIds.push(result.data.session.id);
      }
      firstSessionId = sessionIds[0];

@@ -452,7 +458,7 @@ Object.assign(CodemanApp.prototype, {
    try {
      // Get the case path
      const caseRes = await fetch(`/api/cases/${caseName}`);
-      let caseData = await caseRes.json();
+      let caseData = (await caseRes.json())?.data ?? {};

      // Create the case if it doesn't exist
      if (!caseData.path) {
@@ -501,7 +507,7 @@ Object.assign(CodemanApp.prototype, {
      const sessionIds = [];
      for (const result of createResults) {
        if (!result.success) throw new Error(result.error);
-        sessionIds.push(result.session.id);
+        sessionIds.push(result.data.session.id);
      }

      // Step 2: Start all shells in parallel
@@ -545,7 +551,7 @@ Object.assign(CodemanApp.prototype, {
    try {
      // Check if OpenCode is available
      const statusRes = await fetch('/api/opencode/status');
-      const status = await statusRes.json();
+      const status = (await statusRes.json()).data;
      if (!status.available) {
        this.terminal.writeln('\x1b[1;31m OpenCode CLI not found.\x1b[0m');
        this.terminal.writeln('\x1b[90m Install with: curl -fsSL https://opencode.ai/install | bash\x1b[0m');
@@ -570,8 +576,55 @@ Object.assign(CodemanApp.prototype, {

      // Switch to the new session (don't pre-set activeSessionId — selectSession
      // early-returns when IDs match, skipping buffer load and sendResize)
-      if (data.sessionId) {
-        await this.selectSession(data.sessionId);
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this.terminal.writeln(`\x1b[1;31m Error: ${err.message}\x1b[0m`);
+    }
+  },
+
+  async runCodex() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+
+    this.terminal.clear();
+    this.terminal.writeln(`\x1b[1;32m Starting Codex session in ${caseName}...\x1b[0m`);
+    this.terminal.writeln('');
+    this.terminal.focus();
+
+    try {
+      const statusRes = await fetch('/api/codex/status');
+      const status = (await statusRes.json()).data;
+      if (!status.available) {
+        this.terminal.writeln('\x1b[1;31m Codex CLI not found.\x1b[0m');
+        this.terminal.writeln('\x1b[90m Install with: npm install -g @openai/codex\x1b[0m');
+        return;
+      }
+
+      const globalSettings = this.loadAppSettingsFromStorage();
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), globalSettings);
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'codex',
+          codexConfig: {
+            dangerouslyBypassApprovals: globalSettings.codexDangerouslyBypassApprovals ?? false,
+            renderMode: 'hybrid',
+          },
+          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start Codex');
+
+      // Switch to the new session (don't pre-set activeSessionId — selectSession
+      // early-returns when IDs match, skipping buffer load and sendResize)
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
      }

      this.terminal.focus();
@@ -592,7 +645,7 @@ Object.assign(CodemanApp.prototype, {
    this.editingSessionId = sessionId;

    // Reset to an appropriate tab — Summary for OpenCode (Respawn/Ralph are Claude-only)
-    this.switchOptionsTab(session.mode === 'opencode' ? 'summary' : 'respawn');
+    this.switchOptionsTab(session.mode === 'opencode' || session.mode === 'codex' ? 'summary' : 'respawn');

    // Update respawn status display and buttons
    const respawnStatus = document.getElementById('sessionRespawnStatus');
@@ -621,7 +674,7 @@ Object.assign(CodemanApp.prototype, {
    }

    // Hide Claude-specific options for OpenCode sessions
-    const isOpenCode = session.mode === 'opencode';
+    const isOpenCode = session.mode === 'opencode' || session.mode === 'codex';
    const claudeOnlyEls = document.querySelectorAll('[data-claude-only]');
    claudeOnlyEls.forEach(el => { el.style.display = isOpenCode ? 'none' : ''; });

@@ -637,6 +690,10 @@ Object.assign(CodemanApp.prototype, {
    document.getElementById('modalAutoCompactPrompt').value = session.autoCompactPrompt ?? '';
    document.getElementById('modalAutoClearEnabled').checked = session.autoClearEnabled ?? false;
    document.getElementById('modalAutoClearThreshold').value = session.autoClearThreshold ?? 140000;
+
+    // Populate auto-resume on usage limit (token pause control)
+    document.getElementById('modalAutoResumeEnabled').checked = session.autoResumeEnabled ?? false;
+    this.updateAutoResumeStatus(sessionId);
    document.getElementById('modalImageWatcherEnabled').checked = session.imageWatcherEnabled ?? true;
    document.getElementById('modalFlickerFilterEnabled').checked = session.flickerFilterEnabled ?? false;

@@ -737,6 +794,39 @@ Object.assign(CodemanApp.prototype, {
    } catch { /* silent */ }
  },

+  async autoSaveAutoResume() {
+    if (!this.editingSessionId) return;
+    const enabled = document.getElementById('modalAutoResumeEnabled').checked;
+    try {
+      await this._apiPost(`/api/sessions/${this.editingSessionId}/auto-resume`, { enabled });
+      const session = this.sessions.get(this.editingSessionId);
+      if (session) {
+        session.autoResumeEnabled = enabled;
+        if (!enabled) session.autoResumeAt = undefined;
+      }
+      this.updateAutoResumeStatus(this.editingSessionId);
+      this.showToast(`Auto-resume on usage limit ${enabled ? 'enabled' : 'disabled'}`, 'success');
+    } catch (err) {
+      this.showToast('Failed to toggle auto-resume: ' + err.message, 'error');
+    }
+  },
+
+  // Show "resumes at HH:MM" in the session options modal while a usage-limit
+  // pause is armed for the session being edited
+  updateAutoResumeStatus(sessionId) {
+    const el = document.getElementById('autoResumeStatus');
+    if (!el || this.editingSessionId !== sessionId) return;
+    const session = this.sessions.get(sessionId);
+    if (session?.autoResumeAt && session.autoResumeAt > Date.now()) {
+      const at = new Date(session.autoResumeAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+      el.textContent = `Usage limit pause active — resumes at ${at}`;
+      el.classList.add('active');
+    } else {
+      el.textContent = '';
+      el.classList.remove('active');
+    }
+  },
+
  async toggleSessionImageWatcher() {
    if (!this.editingSessionId) return;
    const enabled = document.getElementById('modalImageWatcherEnabled').checked;
@@ -789,8 +879,8 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch(`/api/sessions/${sessionId}/respawn/config`);
      const data = await res.json();
-      if (data.success && data.config) {
-        const c = data.config;
+      if (data.success && data.data && data.data.config) {
+        const c = data.data.config;
        document.getElementById('modalRespawnPrompt').value = c.updatePrompt || 'update all the docs and CLAUDE.md';
        document.getElementById('modalRespawnSendClear').checked = c.sendClear ?? true;
        document.getElementById('modalRespawnSendInit').checked = c.sendInit ?? true;
@@ -927,9 +1017,8 @@ Object.assign(CodemanApp.prototype, {
    const tabName = document.querySelector(`.tab-name[data-session-id="${sessionId}"]`);
    if (!tabName) return;

-    // If a previous rename somehow leaked (shouldn't happen, but defends against
-    // future code paths that throw before cleanup), abort it before starting fresh.
-    if (this._activeRename) this._activeRename.cancel();
+    // Prevent tab re-renders from destroying the input while renaming
+    this._inlineRenameActive = true;

    const currentName = this.getSessionName(session);
    const parsed = parseSessionPrefix(session.name);
@@ -957,14 +1046,14 @@ Object.assign(CodemanApp.prototype, {
    input.focus();
    input.select();

-    let settled = false;
    const finishRename = async ({ commit }) => {
-      if (settled) return;
-      settled = true;
+      if (!this._inlineRenameActive) return; // prevent double-fire
+      this._inlineRenameActive = false;
      this._activeRename = null;

-      // Aborted (e.g. session was deleted mid-rename): just re-render so any
-      // ghost DOM left behind is replaced with the canonical tab list.
+      // Aborted (e.g. the session was deleted mid-rename, or Escape): re-render
+      // so any ghost DOM is replaced with the canonical tab list, and skip the
+      // API call — a cancel must not fire a stale rename PUT.
      if (!commit) {
        this.renderSessionTabs();
        return;
@@ -1475,3 +1564,14 @@ Object.assign(CodemanApp.prototype, {
    setTimeout(() => modal.classList.remove('from-mobile'), 300);
  },
 });
+
+Object.defineProperty(CodemanApp.prototype, 'runMode', {
+  configurable: true,
+  enumerable: true,
+  get() {
+    return this._runMode || 'claude';
+  },
+  set(mode) {
+    this._runMode = mode === 'opencode' || mode === 'codex' || mode === 'claude' ? mode : 'claude';
+  },
+});
@@ -185,9 +185,9 @@ Object.assign(CodemanApp.prototype, {
    try {
      // Get VAPID public key from server
      const keyData = await this._apiJson('/api/push/vapid-key');
-      if (!keyData?.success) throw new Error('Failed to get VAPID key');
+      if (!keyData) throw new Error('Failed to get VAPID key');

-      const applicationServerKey = urlBase64ToUint8Array(keyData.data.publicKey);
+      const applicationServerKey = urlBase64ToUint8Array(keyData.publicKey);
      const subscription = await this._swRegistration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey,
@@ -204,11 +204,11 @@ Object.assign(CodemanApp.prototype, {
          pushPreferences: this._buildPushPreferences(),
        },
      });
-      if (!data?.success) throw new Error('Failed to register subscription');
+      if (!data) throw new Error('Failed to register subscription');

      this._pushSubscription = subscription;
-      this._pushSubscriptionId = data.data.id;
-      localStorage.setItem('codeman-push-subscription-id', data.data.id);
+      this._pushSubscriptionId = data.id;
+      localStorage.setItem('codeman-push-subscription-id', data.id);
      this._updatePushUI(true);
      this.showToast('Push notifications enabled', 'success');
    } catch (err) {
@@ -308,7 +308,9 @@ Object.assign(CodemanApp.prototype, {
    document.getElementById('appSettingsShowTokenCount').checked = settings.showTokenCount ?? defaults.showTokenCount ?? true;
    document.getElementById('appSettingsShowCost').checked = settings.showCost ?? defaults.showCost ?? false;
    document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? true;
-    document.getElementById('appSettingsShowMonitor').checked = settings.showMonitor ?? defaults.showMonitor ?? true;
+    document.getElementById('appSettingsShowResponseViewer').checked = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
+    document.getElementById('appSettingsSkin').value = settings.skin ?? defaults.skin ?? 'daylight-blue';
+    document.getElementById('appSettingsShowMonitor').checked = settings.showMonitor ?? defaults.showMonitor ?? false;
    document.getElementById('appSettingsShowProjectInsights').checked = settings.showProjectInsights ?? defaults.showProjectInsights ?? false;
    document.getElementById('appSettingsShowFileBrowser').checked = settings.showFileBrowser ?? defaults.showFileBrowser ?? false;
    document.getElementById('appSettingsShowSubagents').checked = settings.showSubagents ?? defaults.showSubagents ?? false;
@@ -326,7 +328,7 @@ Object.assign(CodemanApp.prototype, {
    document.getElementById('appSettingsTunnelEnabled').checked = settings.tunnelEnabled ?? false;
    this.loadTunnelStatus();
    document.getElementById('appSettingsLocalEcho').checked = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
-    document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? false;
+    document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false;
    document.getElementById('appSettingsExtendedKeyboardBar').checked = settings.extendedKeyboardBar ?? false;
    document.getElementById('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
    // Claude CLI settings
@@ -339,8 +341,12 @@ Object.assign(CodemanApp.prototype, {
    claudeModeSelect.onchange = () => {
      allowedToolsRow.style.display = claudeModeSelect.value === 'allowedTools' ? '' : 'none';
    };
+    // Codex CLI settings
+    document.getElementById('appSettingsCodexDangerouslyBypassApprovals').checked =
+      settings.codexDangerouslyBypassApprovals ?? false;
    // Claude Permissions settings
    document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
+    document.getElementById('appSettingsClaudeModel').value = settings.claudeModel ?? '';
    document.getElementById('appSettingsOpusContext1m').checked = settings.opusContext1mEnabled ?? false;
    document.getElementById('appSettingsThinkingEffort').value = settings.thinkingEffort ?? '';
    // CPU Priority settings
@@ -569,7 +575,7 @@ Object.assign(CodemanApp.prototype, {
    const res = await this._apiPost('/api/system/update', {});
    if (!res || !res.ok) {
      let msg = 'Failed to start the update.';
-      try { const j = await res.json(); if (j?.error?.message) msg = j.error.message; } catch {}
+      try { const j = await res.json(); if (typeof j?.error === 'string' && j.error) msg = j.error; } catch {}
      this._setUpdateProgress(`<span style="color:var(--danger,#e5534b)">${escapeHtml(msg)}</span>`);
      if (btn) { btn.disabled = false; btn.textContent = 'Update now'; }
      return;
@@ -598,7 +604,10 @@ Object.assign(CodemanApp.prototype, {
      let data = null;
      try {
        const res = await fetch('/api/system/update/status');
-        if (res.ok) data = await res.json();
+        if (res.ok) {
+          const env = await res.json();
+          data = env && env.success === true ? env.data : env;
+        }
      } catch { /* server restarting — keep polling */ }

      if (!data) {
@@ -652,7 +661,8 @@ Object.assign(CodemanApp.prototype, {
  async loadTunnelStatus() {
    try {
      const res = await fetch('/api/tunnel/status');
-      const status = await res.json();
+      const env = await res.json();
+      const status = env?.success === true ? env.data : env;
      const active = status.running && status.url;
      this._tunnelUrl = active ? status.url : null;
      this._updateTunnelUrlDisplay(this._tunnelUrl);
@@ -721,7 +731,8 @@ Object.assign(CodemanApp.prototype, {
        if (!res.ok) throw new Error('Tunnel not running');
        return res.json();
      })
-      .then(data => {
+      .then(env => {
+        const data = env?.success === true ? env.data : env;
        const container = document.getElementById('tunnelQrContainer');
        if (container && data.svg) container.innerHTML = data.svg;
        // Show auth badge, countdown, and regenerate button when auth is enabled
@@ -754,7 +765,8 @@ Object.assign(CodemanApp.prototype, {
    // Fetch URL for display
    fetch('/api/tunnel/status')
      .then(r => r.json())
-      .then(status => {
+      .then(env => {
+        const status = env?.success === true ? env.data : env;
        const urlEl = document.getElementById('tunnelQrUrl');
        if (urlEl && status.url) {
          urlEl.textContent = status.url;
@@ -786,7 +798,8 @@ Object.assign(CodemanApp.prototype, {
  _refreshTunnelQrFromApi() {
    fetch('/api/tunnel/qr')
      .then(res => res.ok ? res.json() : null)
-      .then(data => {
+      .then(env => {
+        const data = env?.success === true ? env.data : env;
        if (!data?.svg) return;
        const container = document.getElementById('tunnelQrContainer');
        if (container) container.innerHTML = data.svg;
@@ -832,11 +845,18 @@ Object.assign(CodemanApp.prototype, {
    btn.disabled = true;
    try {
      const newEnabled = !isActive;
-      await fetch('/api/settings', {
+      const res = await fetch('/api/settings', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ tunnelEnabled: newEnabled }),
      });
+      // COD-55: server refuses an unauthenticated public tunnel (403). Surface it.
+      if (newEnabled && (await this._handleTunnelEnableRefusal(res))) {
+        this._dismissTunnelConnecting();
+        this._updateWelcomeTunnelBtn(false);
+        btn.disabled = false;
+        return;
+      }
      if (newEnabled) {
        this._showTunnelConnecting();
        // Poll tunnel status as fallback in case SSE event is missed
@@ -901,7 +921,8 @@ Object.assign(CodemanApp.prototype, {
    this._tunnelPollTimer = setTimeout(async () => {
      try {
        const res = await fetch('/api/tunnel/status');
-        const status = await res.json();
+        const env = await res.json();
+        const status = env?.success === true ? env.data : env;
        if (status.running && status.url) {
          // Tunnel is up — update UI
          this._dismissTunnelConnecting();
@@ -960,7 +981,7 @@ Object.assign(CodemanApp.prototype, {
      }
      fetch('/api/tunnel/qr')
        .then(r => { if (!r.ok) throw new Error(); return r.json(); })
-        .then(data => { if (data.svg) qrInner.innerHTML = data.svg; })
+        .then(env => { const data = env?.success === true ? env.data : env; if (data.svg) qrInner.innerHTML = data.svg; })
        .catch(() => { qrInner.innerHTML = '<div style="color:#999;font-size:11px;padding:20px">QR unavailable</div>'; });
    } else {
      clearTimeout(this._welcomeQrShrinkTimer);
@@ -1032,7 +1053,8 @@ Object.assign(CodemanApp.prototype, {
    // Fetch tunnel info
    try {
      const res = await fetch('/api/tunnel/info');
-      const info = await res.json();
+      const env = await res.json();
+      const info = env?.success === true ? env.data : env;
      this._renderTunnelPanel(info);
    } catch {
      const body = document.getElementById('tunnelPanelBody');
@@ -1134,13 +1156,40 @@ Object.assign(CodemanApp.prototype, {
    return `${Math.floor(hrs / 24)}d ago`;
  },

+  /**
+   * COD-55: detect the server's refusal to start an unauthenticated public tunnel.
+   * The PUT /api/settings route returns a 4xx with { success:false, error } when no
+   * CODEMAN_PASSWORD is set and the unauthenticated-network opt-in is not acknowledged.
+   * Shows the server's (actionable) message as an error toast.
+   * @param {Response|null} res - the fetch Response from the settings PUT
+   * @returns {Promise<boolean>} true if the tunnel-enable was refused (caller should abort)
+   */
+  async _handleTunnelEnableRefusal(res) {
+    if (!res || res.ok) return false;
+    let message = 'Tunnel refused: set CODEMAN_PASSWORD before exposing Codeman publicly.';
+    try {
+      const body = await res.json();
+      if (body && body.error) message = body.error;
+    } catch {
+      /* non-JSON body — use the default message */
+    }
+    this._dismissTunnelConnecting?.();
+    this.showToast(message, 'error');
+    return true;
+  },
+
  async _tunnelPanelToggle(enable) {
    try {
-      await fetch('/api/settings', {
+      const res = await fetch('/api/settings', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ tunnelEnabled: enable }),
      });
+      // COD-55: server refuses an unauthenticated public tunnel (403). Surface it.
+      if (enable && (await this._handleTunnelEnableRefusal(res))) {
+        this.closeTunnelPanel();
+        return;
+      }
      if (enable) {
        this._updateTunnelIndicator(false);
        const indicator = document.getElementById('tunnelIndicator');
@@ -1166,7 +1215,8 @@ Object.assign(CodemanApp.prototype, {
      this.showToast('All sessions revoked', 'success');
      // Refresh panel
      const res = await fetch('/api/tunnel/info');
-      const info = await res.json();
+      const env = await res.json();
+      const info = env?.success === true ? env.data : env;
      this._renderTunnelPanel(info);
    } catch {
      this.showToast('Failed to revoke sessions', 'error');
@@ -1261,7 +1311,8 @@ Object.assign(CodemanApp.prototype, {

    try {
      const res = await fetch(`/api/session-lifecycle?${params}`);
-      const data = await res.json();
+      const env = await res.json();
+      const data = env?.success === true ? env.data : env;
      const tbody = document.getElementById('lifecycleTableBody');
      const empty = document.getElementById('lifecycleEmpty');

@@ -1312,6 +1363,7 @@ Object.assign(CodemanApp.prototype, {
      showTokenCount: document.getElementById('appSettingsShowTokenCount').checked,
      showCost: document.getElementById('appSettingsShowCost').checked,
      showLifecycleLog: document.getElementById('appSettingsShowLifecycleLog').checked,
+      showResponseViewer: document.getElementById('appSettingsShowResponseViewer').checked,
      showMonitor: document.getElementById('appSettingsShowMonitor').checked,
      showProjectInsights: document.getElementById('appSettingsShowProjectInsights').checked,
      showFileBrowser: document.getElementById('appSettingsShowFileBrowser').checked,
@@ -1326,11 +1378,15 @@ Object.assign(CodemanApp.prototype, {
      cjkInputEnabled: document.getElementById('appSettingsCjkInput').checked,
      extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
      tabTwoRows: document.getElementById('appSettingsTabTwoRows').checked,
+      skin: document.getElementById('appSettingsSkin').value,
      // Claude CLI settings
      claudeMode: document.getElementById('appSettingsClaudeMode').value,
      allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(),
+      // Codex CLI settings
+      codexDangerouslyBypassApprovals: document.getElementById('appSettingsCodexDangerouslyBypassApprovals').checked,
      // Claude Permissions settings
      agentTeamsEnabled: document.getElementById('appSettingsAgentTeams').checked,
+      claudeModel: document.getElementById('appSettingsClaudeModel').value,
      opusContext1mEnabled: document.getElementById('appSettingsOpusContext1m').checked,
      thinkingEffort: document.getElementById('appSettingsThinkingEffort').value,
      // CPU Priority settings
@@ -1437,6 +1493,7 @@ Object.assign(CodemanApp.prototype, {

    // Apply header visibility immediately
    this.applyHeaderVisibilitySettings();
+    this.applySkin();
    this.applyTabWrapSettings();
    this._updateTokensImmediate();  // Re-render token display (picks up showCost change)
    this.applyMonitorVisibility();
@@ -1451,9 +1508,26 @@ Object.assign(CodemanApp.prototype, {

    // Save to server (includes notification prefs for cross-browser persistence)
    // Strip device-specific keys — localEchoEnabled/cjkInputEnabled are per-platform
-    const { localEchoEnabled: _leo, cjkInputEnabled: _cjk, extendedKeyboardBar: _ekb, ...serverSettings } = settings;
+    const { localEchoEnabled: _leo, cjkInputEnabled: _cjk, extendedKeyboardBar: _ekb, skin: _skin, ...serverSettings } = settings;
    try {
-      await this._apiPut('/api/settings', { ...serverSettings, notificationPreferences: notifPrefsToSave, voiceSettings });
+      const res = await this._apiPut('/api/settings', {
+        ...serverSettings,
+        notificationPreferences: notifPrefsToSave,
+        voiceSettings,
+      });
+
+      // COD-55: the server refuses an unauthenticated public tunnel with a 403 — which
+      // rejects the WHOLE settings PUT. Surface the message and revert the tunnel toggle
+      // (in the UI + localStorage) so it doesn't look enabled. Other settings persisted
+      // to localStorage above still apply locally.
+      if (settings.tunnelEnabled && (await this._handleTunnelEnableRefusal(res))) {
+        settings.tunnelEnabled = false;
+        this.saveAppSettingsToStorage(settings);
+        const cb = document.getElementById('appSettingsTunnelEnabled');
+        if (cb) cb.checked = false;
+        this.closeAppSettings();
+        return;
+      }

      // Save model configuration separately
      await this.saveModelConfigFromSettings();
@@ -1592,6 +1666,8 @@ Object.assign(CodemanApp.prototype, {
        imageWatcherEnabled: false,
        ralphTrackerEnabled: false,
        tabTwoRows: false,
+        cjkInputEnabled: false,
+        skin: 'daylight-blue',
      };
    }
    // Desktop defaults - rely on ?? operators in apply functions
@@ -1629,12 +1705,31 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  // Apply the chosen skin live: sets the html[data-skin] attribute, syncs BOTH
+  // localStorage locations (the standalone 'codeman:skin' key the pre-paint head
+  // script reads + the app-settings blob field written by saveAppSettingsToStorage),
+  // updates window.__codemanSkin, and re-themes any live terminals.
+  applySkin() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    const skin = settings.skin ?? defaults.skin ?? 'daylight-blue';
+    document.documentElement.setAttribute('data-skin', skin);
+    window.__codemanSkin = skin;
+    try {
+      localStorage.setItem('codeman:skin', skin);
+    } catch (_e) {
+      /* private mode */
+    }
+    if (typeof this.applyTerminalSkin === 'function') this.applyTerminalSkin(skin);
+  },
+
  applyHeaderVisibilitySettings() {
    const settings = this.loadAppSettingsFromStorage();
    const defaults = this.getDefaultSettings();
-    const showFontControls = settings.showFontControls ?? defaults.showFontControls ?? false;
-    const showSystemStats = settings.showSystemStats ?? defaults.showSystemStats ?? true;
-    const showTokenCount = settings.showTokenCount ?? defaults.showTokenCount ?? true;
+    const compactHeader = MobileDetection.getDeviceType() !== 'desktop';
+    const showFontControls = compactHeader ? false : (settings.showFontControls ?? defaults.showFontControls ?? false);
+    const showSystemStats = compactHeader ? false : (settings.showSystemStats ?? defaults.showSystemStats ?? true);
+    const showTokenCount = compactHeader ? false : (settings.showTokenCount ?? defaults.showTokenCount ?? true);

    const fontControlsEl = document.querySelector('.header-font-controls');
    const systemStatsEl = document.getElementById('headerSystemStats');
@@ -1657,6 +1752,14 @@ Object.assign(CodemanApp.prototype, {
      lifecycleBtn.style.display = showLifecycleLog ? '' : 'none';
    }

+    // Hide the response viewer (eye) button when setting is disabled.
+    // Marker class, not inline style — the base rule is display:inline-flex !important.
+    const showResponseViewer = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
+    const responseViewerBtn = document.querySelector('.btn-response-viewer-header');
+    if (responseViewerBtn) {
+      responseViewerBtn.classList.toggle('btn-response-viewer-header--hidden', !showResponseViewer);
+    }
+
    // Multi-monitor button — hidden by default (App Settings → Display → "Header
    // Displays"). The server renders the correct initial state on every reload;
    // this handles a live toggle from a settings save (no reload). Toggle the
@@ -1705,7 +1808,7 @@ Object.assign(CodemanApp.prototype, {
  applyMonitorVisibility() {
    const settings = this.loadAppSettingsFromStorage();
    const defaults = this.getDefaultSettings();
-    const showMonitor = settings.showMonitor ?? defaults.showMonitor ?? true;
+    const showMonitor = settings.showMonitor ?? defaults.showMonitor ?? false;
    const showSubagents = settings.showSubagents ?? defaults.showSubagents ?? false;
    const showFileBrowser = settings.showFileBrowser ?? defaults.showFileBrowser ?? false;

@@ -1850,7 +1953,7 @@ Object.assign(CodemanApp.prototype, {

  async loadAppSettingsFromServer(settingsPromise = null) {
    try {
-      const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null);
+      const settings = settingsPromise ? await settingsPromise : await fetch('/api/settings').then(r => r.ok ? r.json() : null).then(env => env?.success === true ? env.data : env);
      if (settings) {
        // Extract notification prefs before merging app settings
        const { notificationPreferences, voiceSettings, respawnPresets, runMode, ...appSettings } = settings;
@@ -1860,8 +1963,10 @@ Object.assign(CodemanApp.prototype, {
        // are NOT display keys — they control server-side behavior and must sync from server.
        const displayKeys = new Set([
          'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
+          'showLifecycleLog', 'showResponseViewer',
          'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
+          'skin',
        ]);
        // Merge settings: non-display keys always sync from server,
        // display keys only seed from server when localStorage has no value
@@ -1942,7 +2047,8 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch('/api/subagent-window-states');
      if (res.ok) {
-        states = await res.json();
+        const env = await res.json();
+        states = env?.success === true ? env.data : env;
        // Also update localStorage
        localStorage.setItem('codeman-subagent-window-states', JSON.stringify(states));
      }
@@ -2009,7 +2115,8 @@ Object.assign(CodemanApp.prototype, {
    try {
      const res = await fetch('/api/subagent-parents');
      if (res.ok) {
-        mapData = await res.json();
+        const env = await res.json();
+        mapData = env?.success === true ? env.data : env;
        // Update localStorage as cache
        localStorage.setItem('codeman-subagent-parents', JSON.stringify(mapData));
      }
@@ -1,36 +1,65 @@
 /* Codeman - Terminal-First UI */

+/* Self-hosted UI + mono fonts (Carbon Aurora · Daylight) — served from /fonts,
+   no external CDN, CSP-safe (font-src 'self'). Variable woff2 cover all weights. */
+@font-face {
+  font-family: 'Manrope';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 400 800;
+  src: url('fonts/manrope-variable.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'JetBrains Mono';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 400 700;
+  src: url('fonts/jetbrains-mono-variable.woff2') format('woff2');
+}
+
 :root {
-  --bg-dark: #09090b;
-  --bg-card: #131316;
-  --bg-input: #1a1a1f;
-  --bg-hover: #1f1f26;
-  --border: #232329;
-  --border-light: #2e2e38;
-  --text: #ececf0;
-  --text-dim: #8b8b97;
-  --text-muted: #52525e;
-  --accent: #3b82f6;
-  --accent-hover: #60a5fa;
-  --green: #22c55e;
-  --yellow: #eab308;
-  --red: #ef4444;
+  /* Carbon Aurora · Daylight — deep-but-not-black slate, surfaces step UP into the light */
+  --bg-dark: #11151c;
+  --bg-card: #1b222c;
+  --bg-input: #202833;
+  --bg-hover: #2a323d;
+  --border: #2b333f;
+  --border-light: #3a4350;
+  --text: #f3f6fa;
+  --text-dim: #98a2b1;
+  --text-muted: #717b8c;
+  /* SINGLE cohesive accent — optimistic emerald → teal (replaces the old blue) */
+  --accent: #38b6f0;
+  --accent-hover: #3ec8ee;
+  /* calmer secondary green for non-primary pills/dots so Run + ring stay focal */
+  --green: #44b993;
+  /* warm, quiet "working" amber (no second saturated hue) */
+  --yellow: #f0c25a;
+  --red: #e06363;
+  /* Daylight accent extras — referenced by the v1.0 override block at end of file */
+  --accent-d: #2487c9;
+  --emerald: #3ec8ee;
+  --teal: #2b8fd9;
+  --accent-soft: #44b993;
+  --accent-ink: #04223a;
+  --warm: #e8c79a;
+  --ring-glow: 0 0 12px -2px rgba(56, 182, 240, 0.55);
  --header-height: 36px;
  --toolbar-height: 42px;
-  --glass-bg: rgba(19, 19, 22, 0.85);
-  --glass-border: rgba(255, 255, 255, 0.06);
+  --glass-bg: rgba(31, 38, 48, 0.85);
+  --glass-border: rgba(255, 255, 255, 0.08);
  --subtle-shadow: 0 -1px 3px rgba(0, 0, 0, 0.3), 0 -4px 16px rgba(0, 0, 0, 0.15);
  --btn-radius: 6px;
  --transition-smooth: 0.2s cubic-bezier(0.4, 0, 0.2, 1);

-  /* Session color palette */
-  --session-red: #ef4444;
-  --session-orange: #f97316;
-  --session-yellow: #eab308;
-  --session-green: #22c55e;
-  --session-blue: #3b82f6;
-  --session-purple: #a855f7;
-  --session-pink: #ec4899;
+  /* Session color palette — retoned toward the Daylight system */
+  --session-red: #e06363;
+  --session-orange: #e8a45c;
+  --session-yellow: #f0c25a;
+  --session-green: #44b993;
+  --session-blue: #2b8fd9;
+  --session-purple: #a98fe0;
+  --session-pink: #e07db0;

  /* Safe area insets for notched devices (iPhone X+, Dynamic Island) */
  --safe-area-top: env(safe-area-inset-top, 0px);
@@ -40,6 +69,78 @@

  /* Touch target minimum (iOS Human Interface Guidelines) */
  --touch-target-min: 44px;
+
+  /* UI font + accent/gradient/hover tokens referenced by the v1.0 override block.
+     These :root values equal the daylight-blue palette so the no-attribute fallback
+     matches current behavior. */
+  --ui-font: 'Manrope', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --accent-rgb: 56, 182, 240;
+  --accent-grad-a: #3ec8ee;
+  --accent-grad-b: #2b8fd9;
+  --run-hover-a: #5cc4f5;
+  --run-hover-b: #3aa3e2;
+  --gear-hover: #2a93d0;
+}
+
+/* ===== Skin: Daylight Blue (current default) ===== */
+html[data-skin="daylight-blue"] {
+  --bg-dark: #11151c; --bg-card: #1b222c; --bg-input: #202833; --bg-hover: #2a323d;
+  --border: #2b333f; --border-light: #3a4350;
+  --text: #f3f6fa; --text-dim: #98a2b1; --text-muted: #717b8c;
+  --accent: #38b6f0; --accent-hover: #3ec8ee;
+  --term-bg: #161b23;
+  --green: #44b993; --yellow: #f0c25a; --red: #e06363;
+  --glass-bg: rgba(31, 38, 48, 0.85); --glass-border: rgba(255, 255, 255, 0.08);
+  --accent-d: #2487c9; --emerald: #3ec8ee; --teal: #2b8fd9;
+  --accent-soft: #44b993; --accent-ink: #04223a;
+  --accent-rgb: 56, 182, 240;
+  --accent-grad-a: #3ec8ee; --accent-grad-b: #2b8fd9;
+  --run-hover-a: #5cc4f5; --run-hover-b: #3aa3e2; --gear-hover: #2a93d0;
+  --ring-glow: 0 0 12px -2px rgba(56, 182, 240, 0.55);
+  --session-red: #e06363; --session-orange: #e8a45c; --session-yellow: #f0c25a;
+  --session-green: #44b993; --session-blue: #2b8fd9; --session-purple: #a98fe0; --session-pink: #e07db0;
+  --ui-font: 'Manrope', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+}
+
+/* ===== Skin: Daylight Green ===== */
+html[data-skin="daylight-green"] {
+  --bg-dark: #11151c; --bg-card: #1b222c; --bg-input: #202833; --bg-hover: #2a323d;
+  --border: #2b333f; --border-light: #3a4350;
+  --text: #f3f6fa; --text-dim: #98a2b1; --text-muted: #717b8c;
+  --accent: #2fd3aa; --accent-hover: #34d8a0;
+  --term-bg: #161b23;
+  --green: #44b993; --yellow: #f0c25a; --red: #e06363;
+  --glass-bg: rgba(31, 38, 48, 0.85); --glass-border: rgba(255, 255, 255, 0.08);
+  --accent-d: #19a987; --emerald: #34d8a0; --teal: #2bcbbb;
+  --accent-soft: #44b993; --accent-ink: #062019;
+  --accent-rgb: 47, 211, 170;
+  --accent-grad-a: #34d8a0; --accent-grad-b: #2bcbbb;
+  --run-hover-a: #3ee0aa; --run-hover-b: #34d4c4; --gear-hover: #1cbd97;
+  --ring-glow: 0 0 12px -2px rgba(47, 211, 170, 0.55);
+  --session-red: #e06363; --session-orange: #e8a45c; --session-yellow: #f0c25a;
+  --session-green: #44b993; --session-blue: #2bcbbb; --session-purple: #a98fe0; --session-pink: #e07db0;
+  --ui-font: 'Manrope', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+}
+
+/* ===== Skin: OG Codeman (original look — no Daylight polish, system font) ===== */
+html[data-skin="og"] {
+  --bg-dark: #09090b; --bg-card: #131316; --bg-input: #1a1a1f; --bg-hover: #1f1f26;
+  --border: #232329; --border-light: #2e2e38;
+  --text: #ececf0; --text-dim: #8b8b97; --text-muted: #52525e;
+  --accent: #3b82f6; --accent-hover: #60a5fa;
+  --term-bg: #0d0d0d;
+  --green: #22c55e; --yellow: #eab308; --red: #ef4444;
+  --glass-bg: rgba(19, 19, 22, 0.85); --glass-border: rgba(255, 255, 255, 0.06);
+  /* daylight-only extras left at sane neutral defaults (unused — override block does not apply to og) */
+  --accent-d: #3b82f6; --emerald: #3b82f6; --teal: #2563eb;
+  --accent-soft: #22c55e; --accent-ink: #0b1220;
+  --accent-rgb: 59, 130, 246;
+  --accent-grad-a: #3b82f6; --accent-grad-b: #2563eb;
+  --run-hover-a: #60a5fa; --run-hover-b: #3b82f6; --gear-hover: #2563eb;
+  --ring-glow: 0 0 12px -2px rgba(59, 130, 246, 0.55);
+  --session-red: #ef4444; --session-orange: #f97316; --session-yellow: #eab308;
+  --session-green: #22c55e; --session-blue: #3b82f6; --session-purple: #a855f7; --session-pink: #ec4899;
+  --ui-font: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
 }

 * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -107,11 +208,11 @@ textarea:focus-visible {
  caret-color: transparent !important;
 }
 .touch-device .xterm .xterm-helper-textarea {
-  left: 0 !important;
-  top: 0 !important;
+  left: var(--xterm-helper-left, 0px) !important;
+  top: var(--xterm-helper-top, 0px) !important;
  width: 1px !important;
  height: 1px !important;
-  z-index: -1 !important;
+  z-index: 0 !important;
  font-size: 16px !important; /* prevent iOS auto-zoom on focus */
 }

@@ -129,7 +230,7 @@ textarea:focus-visible {
 }

 body {
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  font-family: var(--ui-font);
  background: var(--bg-dark);
  color: var(--text);
  height: 100vh;
@@ -233,6 +334,7 @@ body {
  display: flex;
  align-items: center;
  gap: 0.35rem;
+  position: relative;
  padding: 0.35rem 0.6rem;
  background: transparent;
  border: 1px solid transparent;
@@ -265,6 +367,40 @@ body {
  outline: none !important;
 }

+.session-tab.tab-loading::after {
+  content: "";
+  position: absolute;
+  left: 8px;
+  right: 8px;
+  bottom: -2px;
+  height: 2px;
+  border-radius: 999px;
+  background: linear-gradient(90deg, transparent, rgba(96, 165, 250, 0.95), transparent);
+  animation: tab-load-sweep 0.9s linear infinite;
+  pointer-events: none;
+}
+
+.tab-load-spinner {
+  width: 10px;
+  height: 10px;
+  border: 2px solid rgba(96, 165, 250, 0.3);
+  border-top-color: rgba(96, 165, 250, 0.95);
+  border-radius: 50%;
+  flex: 0 0 10px;
+  animation: tab-load-spin 0.7s linear infinite;
+}
+
+@keyframes tab-load-spin {
+  to { transform: rotate(360deg); }
+}
+
+@keyframes tab-load-sweep {
+  0% { transform: translateX(-45%); opacity: 0.35; }
+  50% { opacity: 1; }
+  100% { transform: translateX(45%); opacity: 0.35; }
+}
+
+
 /* Tab switch feedback: bright green glow on the newly-active tab */
 .session-tab.tab-glow {
  animation: tab-glow 0.35s ease-out;
@@ -1023,6 +1159,11 @@ body.solo-mode .btn-lifecycle-log {
  color: #10b981;
 }

+.session-tab .tab-mode.codex {
+  background: rgba(168, 85, 247, 0.2);
+  color: #a855f7;
+}
+
 /* Timer Banner - Compact */
 .timer-banner {
  display: flex;
@@ -2057,7 +2198,7 @@ body.solo-mode .btn-lifecycle-log {

 .terminal-container {
  flex: 1;
-  background: #0d0d0d;
+  background: var(--term-bg, #161b23);
  overflow: hidden;
  position: relative;
  /* Performance: isolate layout and paint operations.
@@ -2070,6 +2211,8 @@ body.solo-mode .btn-lifecycle-log {
  will-change: contents;
 }
 .terminal-container .xterm {
+  width: 100%;
+  min-width: 0;
  height: 100%;
  padding: 0;
 }
@@ -2702,6 +2845,22 @@ body.solo-mode .btn-lifecycle-log {
  color: #a7f3d0;
 }

+/* Codex mode colors */
+.btn-toolbar.btn-run.mode-codex,
+.btn-toolbar.btn-run-gear.mode-codex {
+  background: linear-gradient(135deg, #2a0a3e 0%, #350b4d 50%, #400d5e 100%);
+  border-color: rgba(168, 85, 247, 0.5);
+  color: #d8b4fe;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+.btn-toolbar.btn-run.mode-codex:hover,
+.btn-toolbar.btn-run-gear.mode-codex:hover {
+  background: linear-gradient(135deg, #400d5e 0%, #581c87 50%, #6b21a8 100%);
+  box-shadow: 0 0 12px rgba(168, 85, 247, 0.35), 0 2px 8px rgba(168, 85, 247, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(192, 132, 252, 0.6);
+  color: #e9d5ff;
+}
+
 /* Dropdown menu */
 .run-mode-menu {
  display: none;
@@ -2754,6 +2913,7 @@ body.solo-mode .btn-lifecycle-log {
 }
 .run-mode-dot.claude { background: #3b82f6; }
 .run-mode-dot.opencode { background: #10b981; }
+.run-mode-dot.codex { background: #a855f7; }

 .run-mode-sep {
  height: 1px;
@@ -3769,6 +3929,22 @@ body.solo-mode .btn-lifecycle-log {
  text-overflow: ellipsis;
 }

+/* Skin picker: full-width row (not squeezed into a half-width grid cell) with an
+   auto-width select, so the "Skin" label keeps its space instead of truncating. */
+.settings-item-skin {
+  grid-column: 1 / -1;
+  gap: 0.75rem;
+}
+.settings-item-skin .settings-item-label {
+  flex: 0 0 auto;
+}
+.settings-item-skin .form-select {
+  width: auto;
+  min-width: 220px;
+  max-width: 320px;
+  flex: 0 1 auto;
+}
+
 .settings-item-multiline {
  align-items: center;
 }
@@ -4586,15 +4762,16 @@ body.solo-mode .btn-lifecycle-log {
  width: 60px;
 }

-/* Respawn header with status and actions */
+/* Respawn status + Enable/Stop row — sits at the bottom of the Respawn tab,
+   below the settings it acts on */
 .respawn-header {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 1rem;
-  margin-bottom: 0.75rem;
-  padding-bottom: 0.75rem;
-  border-bottom: 1px solid var(--border);
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid rgba(34, 197, 94, 0.2);
 }

 .respawn-header .respawn-actions {
@@ -4611,6 +4788,72 @@ body.solo-mode .btn-lifecycle-log {
  margin-bottom: 0.25rem;
 }

+/* Auto-resume on usage limit (token pause control) */
+.auto-resume-box {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  margin: 0.75rem 0;
+  padding: 0.6rem 0.75rem;
+  background: rgba(59, 130, 246, 0.07);
+  border: 1px solid rgba(59, 130, 246, 0.35);
+  border-radius: 6px;
+}
+
+.auto-resume-box .checkbox-inline {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text);
+}
+
+.auto-resume-box .form-hint {
+  margin-top: 0;
+}
+
+/* Respawn loop box — groups every setting that belongs to the autonomous
+   respawn cycle (duration, presets, cycle prompts, enable). Green like its
+   Enable button; a visual sibling of the standalone auto-resume option above */
+.respawn-loop-box {
+  margin: 0.75rem 0;
+  padding: 0.6rem 0.75rem;
+  background: rgba(34, 197, 94, 0.05);
+  border: 1px solid rgba(34, 197, 94, 0.3);
+  border-radius: 6px;
+}
+
+.respawn-loop-title {
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: var(--text);
+  margin-bottom: 0.3rem;
+}
+
+.respawn-loop-hint {
+  display: block;
+  margin-top: 0;
+  margin-bottom: 0.5rem;
+}
+
+.respawn-loop-box .form-section-header {
+  border-bottom-color: rgba(34, 197, 94, 0.2);
+}
+
+/* Match the cycle-step checkboxes (2./3.) to the step labels (1./4.) */
+.respawn-loop-box .checkbox-inline {
+  font-size: 0.7rem;
+}
+
+.auto-resume-status {
+  display: none;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: var(--accent-hover);
+}
+
+.auto-resume-status.active {
+  display: block;
+}
+
 /* Respawn actions in modal */
 .respawn-actions {
  display: flex;
@@ -8072,6 +8315,12 @@ kbd {
  display: inline-flex !important;
 }

+/* "Response Viewer" header toggle (App Settings → Display) — must out-specify
+   the inline-flex !important above */
+.btn-response-viewer-header.btn-response-viewer-header--hidden {
+  display: none !important;
+}
+
 .response-viewer {
  display: none;
  position: fixed;
@@ -8637,6 +8886,33 @@ kbd {
  font-size: 12px;
 }

+.touch-device #cjkInput.cjk-input-visible {
+  position: fixed;
+  left: var(--safe-area-left);
+  right: var(--safe-area-right);
+  bottom: calc(var(--safe-area-bottom) + 40px);
+  z-index: 52;
+  display: block;
+  min-height: 44px;
+  max-height: 96px;
+  border: 1px solid rgba(80, 120, 190, 0.55);
+  border-left: none;
+  border-right: none;
+  background: #101827;
+  color: #f3f4f6;
+  box-shadow: 0 -8px 20px rgba(0, 0, 0, 0.35);
+  transition: transform 0.15s ease-out;
+  will-change: transform;
+}
+
+.touch-device.keyboard-visible #cjkInput.cjk-input-visible {
+  bottom: calc(var(--safe-area-bottom) + 84px);
+}
+
+body.touch-device.cjk-input-visible .main {
+  padding-bottom: calc(84px + var(--safe-area-bottom));
+}
+
 /* ═══════════════════════════════════════════════════════════════
   Orchestrator Panel
   ═══════════════════════════════════════════════════════════════ */
@@ -8898,3 +9174,233 @@ kbd {
  pointer-events: none;
  z-index: 100;
 }
+
+/* ============================================================
+   === v1.0 Carbon Aurora · Daylight overrides ===
+   Single appended block — trivially removable. Retones the hardcoded
+   component colors that don't flow through :root: the active session
+   tab (#00FF66), the banners' literal gradients, the Ralph Material
+   palette, the Run/welcome/stop gradient buttons, the panels' glass,
+   and the welcome title. Calms heavy glows; the ONLY real saturation/
+   glow is reserved for the Run button + the progress ring.
+   ============================================================ */
+
+html:not([data-skin="og"]) {
+/* ---- Brand wordmark: emerald, calm (kill the blue glow) ---- */
+.logo:hover {
+  color: var(--accent-hover);
+  text-shadow: none;
+  filter: brightness(1.06);
+}
+
+/* ---- Active session tab: crisp emerald (replaces neon #00FF66) ---- */
+.session-tab.active {
+  background: rgba(var(--accent-rgb), 0.13) !important;
+  border: 1px solid var(--accent) !important;
+  color: var(--text) !important;
+  box-shadow: none !important;
+}
+.session-tab:hover {
+  background: rgba(var(--accent-rgb), 0.06);
+  border-color: rgba(var(--accent-rgb), 0.2);
+  box-shadow: none;
+}
+.session-tab .tab-number {
+  background: rgba(255, 255, 255, 0.08);
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  color: var(--text-dim);
+}
+.session-tab.active .tab-number {
+  background: rgba(var(--accent-rgb), 0.2) !important;
+  border-color: rgba(var(--accent-rgb), 0.45) !important;
+  color: var(--accent-hover) !important;
+}
+/* per-color active tints: calm the glow, keep the identity hue as a quiet border */
+.session-tab.active[data-color] {
+  box-shadow: none;
+}
+/* tab status dots: quiet, no halo */
+.session-tab .tab-status.idle,
+.session-tab .tab-status.busy {
+  box-shadow: none;
+}
+.tab-glow { animation: none; box-shadow: none; }
+
+/* ---- Timer banner: emerald-teal, flat ---- */
+.timer-banner {
+  background: linear-gradient(90deg, rgba(31, 38, 48, 0.92), rgba(22, 27, 35, 0.92));
+  border-bottom: 1px solid var(--glass-border);
+}
+.timer-value { color: var(--accent); }
+.timer-progress-fill { background: linear-gradient(90deg, var(--accent-grad-a), var(--accent-grad-b)); }
+
+/* ---- Respawn banner: lifted slate, calm green hairline ---- */
+.respawn-banner {
+  background: linear-gradient(90deg, rgba(31, 38, 48, 0.9), rgba(22, 27, 35, 0.9));
+  border-bottom: 1px solid var(--glass-border);
+}
+.respawn-countdown-timer .respawn-timer-value,
+.action-type { color: var(--accent); }
+.respawn-timer-progress { background: var(--accent); }
+.respawn-action-log { border-left-color: rgba(var(--accent-rgb), 0.18); }
+.respawn-action-log::-webkit-scrollbar-thumb { background: rgba(var(--accent-rgb), 0.28); }
+
+/* ---- Ralph panel: replace the blue->green ring gradient + Material badges ---- */
+.ralph-ring-text {
+  background: linear-gradient(135deg, var(--accent-grad-a), var(--accent-grad-b));
+  -webkit-background-clip: text;
+  background-clip: text;
+}
+.ralph-ring-bg, .ralph-ring-track { stroke: rgba(255, 255, 255, 0.1); }
+/* Ralph status badges: collapse the off-token Material palette onto the system */
+.ralph-status-badge { color: var(--text-dim); }
+.ralph-status-dot { box-shadow: none; }
+.ralph-info { background: rgba(var(--accent-rgb), 0.05); }
+
+/* ---- Bottom toolbar + neutral buttons ---- */
+.toolbar { box-shadow: 0 -1px 3px rgba(0, 0, 0, 0.22), 0 -4px 14px rgba(0, 0, 0, 0.14); }
+.btn-toolbar {
+  background: rgba(255, 255, 255, 0.045);
+  border-color: rgba(255, 255, 255, 0.09);
+  color: var(--text-dim);
+}
+.btn-toolbar:hover {
+  background: rgba(255, 255, 255, 0.08);
+  border-color: rgba(255, 255, 255, 0.14);
+  color: var(--text);
+  box-shadow: none;
+}
+
+/* ---- RUN button: THE focal saturated accent (flat emerald->teal fill) ---- */
+.btn-toolbar.btn-run,
+.btn-toolbar.btn-run.mode-claude {
+  background: linear-gradient(135deg, var(--accent-grad-a), var(--accent-grad-b));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+  font-weight: 700;
+  text-shadow: none;
+}
+.btn-toolbar.btn-run:hover,
+.btn-toolbar.btn-run.mode-claude:hover {
+  background: linear-gradient(135deg, var(--run-hover-a), var(--run-hover-b));
+  box-shadow: 0 0 14px -2px rgba(var(--accent-rgb), 0.5);
+}
+.btn-toolbar.btn-run.mode-opencode {
+  background: linear-gradient(135deg, var(--accent-d), var(--accent-grad-b));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+.btn-toolbar.btn-run.mode-opencode:hover { box-shadow: 0 0 14px -2px rgba(var(--accent-rgb), 0.45); }
+.btn-toolbar.btn-run.mode-codex {
+  background: linear-gradient(135deg, var(--accent-grad-b), #5cc6e8);
+  border-color: var(--accent-grad-b);
+  color: #061c20;
+}
+.btn-toolbar.btn-run.mode-codex:hover { box-shadow: 0 0 14px -2px rgba(43, 203, 187, 0.45); }
+.btn-toolbar.btn-run-gear {
+  background: var(--accent-d);
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+.btn-toolbar.btn-run-gear:hover { background: var(--gear-hover); box-shadow: none; }
+.run-mode-dot.claude { background: var(--accent); }
+.run-mode-dot.opencode { background: var(--accent-soft); }
+.run-mode-dot.codex { background: var(--accent-grad-b); }
+
+/* ---- Shell button: quiet neutral with a calm green tint ---- */
+.btn-toolbar.btn-shell {
+  background: rgba(68, 185, 147, 0.1);
+  border: 1px solid rgba(68, 185, 147, 0.28);
+  color: var(--green);
+  text-shadow: none;
+}
+.btn-toolbar.btn-shell:hover {
+  background: rgba(68, 185, 147, 0.16);
+  border-color: rgba(68, 185, 147, 0.4);
+  box-shadow: none;
+}
+
+/* ---- Stop button: quiet neutral control (no rose glow) ---- */
+.btn-toolbar.btn-stop {
+  background: rgba(255, 255, 255, 0.045);
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  color: var(--text-dim);
+  text-shadow: none;
+}
+.btn-toolbar.btn-stop:hover {
+  background: rgba(224, 99, 99, 0.14);
+  border-color: rgba(224, 99, 99, 0.4);
+  color: #f0a0a0;
+  box-shadow: none;
+}
+.btn-toolbar.btn-stop.confirming {
+  background: linear-gradient(135deg, #5a4a1a, #6b5620);
+  border-color: rgba(240, 194, 90, 0.6);
+  color: var(--yellow);
+}
+
+/* ---- Case selector + add ---- */
+.toolbar-select {
+  background: rgba(255, 255, 255, 0.045);
+  border-color: rgba(255, 255, 255, 0.09);
+  color: var(--text-dim);
+}
+.toolbar-select:hover { background: rgba(255, 255, 255, 0.07); border-color: rgba(255, 255, 255, 0.14); }
+.toolbar-select:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 1px rgba(var(--accent-rgb), 0.25);
+}
+.btn-case-add { color: var(--accent-soft); }
+
+/* ---- Header system stats: cohesive accent meters ---- */
+.stat-bar-mem { background: linear-gradient(90deg, var(--accent), var(--accent-hover)); }
+.header-tokens.clickable:hover { background: rgba(var(--accent-rgb), 0.16); }
+
+/* ---- Monitor + Subagents panels: lifted frosted slate ---- */
+.monitor-panel,
+.subagents-panel {
+  background: rgba(31, 38, 48, 0.95);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+/* ---- Subagent progress ring: emerald, calm glow ---- */
+.subagent-ring-progress,
+.subagent-ring circle.progress { stroke: var(--accent); }
+
+/* ---- PROGRESS RING (Ralph large): the one place a soft glow lives ---- */
+.ralph-ring-fill { filter: drop-shadow(0 0 6px rgba(var(--accent-rgb), 0.45)); }
+
+/* ---- Welcome overlay: emerald title + Daylight buttons ---- */
+.welcome-title {
+  background: linear-gradient(135deg, var(--accent-grad-a) 0%, var(--accent-grad-b) 50%, var(--accent-grad-a) 100%);
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+.welcome-btn-claude {
+  background: linear-gradient(135deg, var(--accent-grad-a), var(--accent-grad-b));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+.welcome-btn-claude:hover { box-shadow: 0 0 28px -4px rgba(var(--accent-rgb), 0.3); }
+.welcome-btn-opencode {
+  background: linear-gradient(135deg, var(--accent-d), var(--accent-grad-b));
+  border-color: rgba(var(--accent-rgb), 0.4);
+  color: var(--accent-ink);
+}
+.welcome-btn-opencode:hover { box-shadow: 0 0 28px -4px rgba(var(--accent-rgb), 0.25); }
+.welcome-btn-tunnel {
+  background: linear-gradient(135deg, rgba(46, 55, 67, 0.9), rgba(56, 66, 79, 0.9));
+  border-color: var(--border-light);
+  color: var(--text);
+}
+.welcome-btn-tunnel:hover { box-shadow: none; }
+.welcome-btn-tunnel.active {
+  background: linear-gradient(135deg, var(--accent-d), var(--accent-grad-a));
+  border-color: var(--accent);
+  color: var(--accent-ink);
+}
+
+/* ---- Focus rings (driven by --accent, now emerald) stay accessible ---- */
+:focus-visible { outline-color: var(--accent); }
+}
@@ -12,6 +12,45 @@
 * @loadorder 7 of 15 — loaded after app.js, before respawn-ui.js
 */

+(function (global) {
+  const TERMINAL_QUERY_RESPONSE_PATTERN = /^\x1b\[[\?>=]?[\d;]*[cnR]$/;
+  const TERMINAL_OSC_RESPONSE_PATTERN = /^\x1b\][\d;]*[^\x07\x1b]*(?:\x07|\x1b\\)$/;
+  // Grace window after a manual scroll-up gesture during which sticky-scroll is
+  // suppressed, so high-frequency Codex status redraws don't snap the viewport
+  // back to the bottom while the user is inspecting earlier output.
+  const USER_SCROLL_STICKY_SUPPRESS_MS = 1500;
+
+  function isTerminalQueryResponse(data) {
+    return TERMINAL_QUERY_RESPONSE_PATTERN.test(data) || TERMINAL_OSC_RESPONSE_PATTERN.test(data);
+  }
+
+  function shouldSuppressTerminalQueryResponse(data) {
+    return isTerminalQueryResponse(data);
+  }
+
+  // Per-skin xterm.js palettes. The 'daylight-blue' object equals the legacy hardcoded
+  // theme, so default behavior is unchanged. Shared at module scope and exported on the
+  // global so both terminal-ui.js (main terminal) and panels-ui.js (teammate terminals,
+  // a separate IIFE) can read the current skin's palette.
+  const CODEMAN_XTERM_THEMES = {
+    og: { background: '#0d0d0d', foreground: '#e0e0e0', cursor: '#e0e0e0', cursorAccent: '#0d0d0d', selection: 'rgba(255,255,255,0.3)', black: '#0d0d0d', red: '#ff6b6b', green: '#51cf66', yellow: '#ffd43b', blue: '#339af0', magenta: '#cc5de8', cyan: '#22b8cf', white: '#e0e0e0', brightBlack: '#495057', brightRed: '#ff8787', brightGreen: '#69db7c', brightYellow: '#ffe066', brightBlue: '#5c7cfa', brightMagenta: '#da77f2', brightCyan: '#66d9e8', brightWhite: '#ffffff' },
+    'daylight-green': { background: '#161b23', foreground: '#dfe6ef', cursor: '#2fd3aa', cursorAccent: '#161b23', selection: 'rgba(47,211,170,0.22)', black: '#161b23', red: '#ff8585', green: '#34d8a0', yellow: '#f0c25a', blue: '#5cc6e8', magenta: '#c79af2', cyan: '#2bcbbb', white: '#dfe6ef', brightBlack: '#5b6675', brightRed: '#ffa0a0', brightGreen: '#5fe6b8', brightYellow: '#ffd884', brightBlue: '#82d4ee', brightMagenta: '#d6b3f7', brightCyan: '#5ee0d4', brightWhite: '#f3f6fa' },
+    'daylight-blue': { background: '#161b23', foreground: '#dfe6ef', cursor: '#38b6f0', cursorAccent: '#161b23', selection: 'rgba(56,182,240,0.22)', black: '#161b23', red: '#ff8585', green: '#34d8a0', yellow: '#f0c25a', blue: '#5cc6e8', magenta: '#c79af2', cyan: '#2bcbbb', white: '#dfe6ef', brightBlack: '#5b6675', brightRed: '#ffa0a0', brightGreen: '#5fe6b8', brightYellow: '#ffd884', brightBlue: '#82d4ee', brightMagenta: '#d6b3f7', brightCyan: '#5ee0d4', brightWhite: '#f3f6fa' },
+  };
+  function currentXtermTheme() {
+    const skin = (typeof document !== 'undefined' && document.documentElement.dataset.skin) || 'daylight-blue';
+    return CODEMAN_XTERM_THEMES[skin] || CODEMAN_XTERM_THEMES['daylight-blue'];
+  }
+
+  global.CodemanTerminalInput = {
+    isTerminalQueryResponse,
+    shouldSuppressTerminalQueryResponse,
+    USER_SCROLL_STICKY_SUPPRESS_MS,
+  };
+  global.CODEMAN_XTERM_THEMES = CODEMAN_XTERM_THEMES;
+  global.codemanCurrentXtermTheme = currentXtermTheme;
+})(window);
+
 Object.assign(CodemanApp.prototype, {
  // ═══════════════════════════════════════════════════════════════
  // Terminal Setup — xterm.js config and input handling
@@ -24,29 +63,7 @@ Object.assign(CodemanApp.prototype, {
    const scrollback = Number.isFinite(stored) && stored > 0 ? Math.max(stored, DEFAULT_SCROLLBACK) : DEFAULT_SCROLLBACK;

    this.terminal = new Terminal({
-      theme: {
-        background: '#0d0d0d',
-        foreground: '#e0e0e0',
-        cursor: '#e0e0e0',
-        cursorAccent: '#0d0d0d',
-        selection: 'rgba(255, 255, 255, 0.3)',
-        black: '#0d0d0d',
-        red: '#ff6b6b',
-        green: '#51cf66',
-        yellow: '#ffd43b',
-        blue: '#339af0',
-        magenta: '#cc5de8',
-        cyan: '#22b8cf',
-        white: '#e0e0e0',
-        brightBlack: '#495057',
-        brightRed: '#ff8787',
-        brightGreen: '#69db7c',
-        brightYellow: '#ffe066',
-        brightBlue: '#5c7cfa',
-        brightMagenta: '#da77f2',
-        brightCyan: '#66d9e8',
-        brightWhite: '#ffffff',
-      },
+      theme: { ...window.codemanCurrentXtermTheme() },
      fontFamily: '"Fira Code", "Cascadia Code", "JetBrains Mono", "SF Mono", Monaco, monospace',
      // Use smaller font on mobile to fit more columns (prevents wrapping of Claude's status line)
      fontSize: MobileDetection.getDeviceType() === 'mobile' ? 10 : 14,
@@ -61,6 +78,23 @@ Object.assign(CodemanApp.prototype, {
    this.fitAddon = new FitAddon.FitAddon();
    this.terminal.loadAddon(this.fitAddon);

+    // SerializeAddon: lets us snapshot the xterm rendered state (viewport +
+    // scrollback + colors/attrs) when switching away from a tab and restore
+    // it on switch-back. Needed primarily for codex tabs — codex's TUI drops
+    // earlier conversation from its current frame, so replaying the server
+    // byte buffer on tab-switch shows only the latest (idle) frame. The
+    // snapshot captures what the user was actually looking at.
+    this._xtermSnapshots = new Map(); // Map<sessionId, serialized-string>
+    if (typeof SerializeAddon !== 'undefined') {
+      try {
+        this._serializeAddon = new SerializeAddon.SerializeAddon();
+        this.terminal.loadAddon(this._serializeAddon);
+      } catch (_e) {
+        /* SerializeAddon failed — snapshot/restore disabled, fallback to buffer-fetch */
+        this._serializeAddon = null;
+      }
+    }
+
    if (typeof Unicode11Addon !== 'undefined') {
      try {
        const unicode11Addon = new Unicode11Addon.Unicode11Addon();
@@ -164,7 +198,24 @@ Object.assign(CodemanApp.prototype, {
          // whitespace) -- if so, xterm handled it and we should not double-send.
          // Use a microtask to check after xterm's own handlers have run.
          const data = e.data;
+          const pendingBefore = this._localEchoOverlay?.pendingText || '';
          Promise.resolve().then(() => {
+            if (
+              this._lastTerminalData?.data === data &&
+              performance.now() - this._lastTerminalData.time < 100
+            ) {
+              xtermTextarea.value = '';
+              return;
+            }
+            const pendingAfter = this._localEchoOverlay?.pendingText || '';
+            if (
+              this._localEchoEnabled &&
+              pendingAfter.length > pendingBefore.length &&
+              pendingAfter.endsWith(data)
+            ) {
+              xtermTextarea.value = '';
+              return;
+            }
            // If xterm cleared the textarea, it processed the input -- skip.
            const val = xtermTextarea.value;
            if (!val || (val.trim() === '' && data !== ' ')) return;
@@ -227,15 +278,17 @@ Object.assign(CodemanApp.prototype, {
    }

    this._localEchoOverlay = new LocalEchoOverlay(this.terminal);
+    if (MobileDetection.isTouchDevice()) {
+      this.terminal.onCursorMove(() => this._syncMobileHelperTextareaToCursor());
+      this.terminal.onRender(() => this._syncMobileHelperTextareaToCursor());
+    }

    // CJK IME input — textarea in index.html, just wire up send
    this._cjkInput = null;
    if (typeof CjkInput !== 'undefined') {
      this._cjkInput = CjkInput.init({
        send: (text) => {
-          if (this.activeSessionId) {
-            this._sendInputAsync(this.activeSessionId, text);
-          }
+          this._handleCjkInput(text);
        },
      });
    }
@@ -265,6 +318,7 @@ Object.assign(CodemanApp.prototype, {
      (ev) => {
        ev.preventDefault();
        const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
+        this._noteTerminalUserScroll(lines);
        this.terminal.scrollLines(lines);
      },
      { passive: false }
@@ -328,6 +382,7 @@ Object.assign(CodemanApp.prototype, {
        'touchmove',
        (ev) => {
          if (ev.touches.length === 1 && isTouching) {
+            ev.preventDefault();
            didScroll = true;
            const touchY = ev.touches[0].clientY;
            const delta = touchLastY - touchY; // positive = scroll down
@@ -338,12 +393,13 @@ Object.assign(CodemanApp.prototype, {
            const ch = cellHeight();
            const lines = Math.trunc(pixelAccum / ch);
            if (lines !== 0) {
+              this._noteTerminalUserScroll(lines);
              this.terminal.scrollLines(lines);
              pixelAccum -= lines * ch;
            }
          }
        },
-        { passive: true }
+        { passive: false }
      );

      container.addEventListener(
@@ -357,7 +413,13 @@ Object.assign(CodemanApp.prototype, {
          // routes back to the terminal. Without this, a tap on the terminal area
          // consumes the touch event but xterm's textarea never regains focus.
          if (!didScroll && this.terminal) {
-            this.terminal.focus();
+            const cjkInput = document.getElementById('cjkInput');
+            if (cjkInput?.classList.contains('cjk-input-visible')) {
+              cjkInput.focus();
+            } else {
+              this._syncMobileHelperTextareaToCursor();
+              this.terminal.focus();
+            }
          }
        },
        { passive: true }
@@ -382,6 +444,9 @@ Object.assign(CodemanApp.prototype, {

    // Generation counter for chunkedTerminalWrite — aborts stale writes on tab switch
    this._chunkedWriteGen = 0;
+    this._bufferLoadSeq = 0;
+    this._bufferLoadOwner = null;
+    this._lastUserScrollUpAt = null;

    // Handle resize with throttling for performance
    this._resizeTimeout = null;
@@ -450,11 +515,30 @@ Object.assign(CodemanApp.prototype, {
              this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
            }
            this._lastResizeDims = { cols, rows };
-            fetch(`/api/sessions/${this.activeSessionId}/resize`, {
-              method: 'POST',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ cols, rows }),
-            }).catch(() => {});
+            // Typed + WS-first like sendResize: the viewport type feeds resize
+            // arbitration (a phone rotating must not bypass a desktop claim),
+            // and a desktop window narrowing past the tablet breakpoint must
+            // send a typed WS frame so its stale desktop claim is released.
+            const viewportType =
+              typeof MobileDetection !== 'undefined' && MobileDetection.getDeviceType
+                ? MobileDetection.getDeviceType()
+                : 'desktop';
+            let sentViaWs = false;
+            if (this._wsReady && this._wsSessionId === this.activeSessionId) {
+              try {
+                this._ws.send(JSON.stringify({ t: 'z', c: cols, r: rows, v: viewportType }));
+                sentViaWs = true;
+              } catch {
+                // Fall through to HTTP POST
+              }
+            }
+            if (!sentViaWs) {
+              fetch(`/api/sessions/${this.activeSessionId}/resize`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ cols, rows, viewportType }),
+              }).catch(() => {});
+            }
          }
        }
        // Update subagent connection lines and local echo at new dimensions
@@ -498,11 +582,15 @@ Object.assign(CodemanApp.prototype, {
      // CJK input has focus — block xterm from sending to PTY
      if (window.cjkActive || document.activeElement?.id === 'cjkInput') return;
      if (this.activeSessionId) {
-        // Filter out terminal query responses that xterm.js generates automatically.
-        // These are responses to DA (Device Attributes), DSR (Device Status Report), etc.
-        // sent by tmux when attaching. Without this filter, they appear as typed text.
-        // Patterns: \x1b[?...c (DA1), \x1b[>...c (DA2), \x1b[...R (CPR), \x1b[...n (DSR)
-        if (/^\x1b\[[\?>=]?[\d;]*[cnR]$/.test(data)) return;
+        // Filter terminal query replies generated by xterm.js itself.
+        // Forwarding them through the WebSocket injects DA/DSR/CPR replies
+        // into the foreground process as typed input (for example "0;276;0c").
+        if (
+          window.CodemanTerminalInput?.shouldSuppressTerminalQueryResponse(data)
+        ) {
+          return;
+        }
+        this._lastTerminalData = { data, time: performance.now() };

        // ── Local Echo Mode ──
        // When enabled, keystrokes are buffered locally in the overlay for
@@ -770,7 +858,11 @@ Object.assign(CodemanApp.prototype, {

        // Pattern 1: Commands with file paths (tail -f, cat, head, grep pattern, etc.)
        // Handles: tail -f /path, grep pattern /path, cat -n /path
-        const cmdPattern = /(tail|cat|head|less|grep|watch|vim|nano)\s+(?:[^\s\/]*\s+)*(\/[^\s"'<>|;&\n\x00-\x1f]+)/g;
+        // ⚠ The arg group must stay linear-time: `(?:[^\s\/]*\s+)*` (empty-matchable
+        // token, unbounded) backtracks exponentially on lines with a trigger word
+        // followed by multi-space runs (e.g. wrapped heredoc/table output) — froze
+        // the whole tab on hover. Non-empty token + bounded reps is O(n).
+        const cmdPattern = /\b(tail|cat|head|less|grep|watch|vim|nano)\s+(?:[^\s\/]+\s+){0,4}(\/[^\s"'<>|;&\n\x00-\x1f]+)/g;

        // Pattern 2: Paths with common extensions
        const extPattern =
@@ -868,7 +960,7 @@ Object.assign(CodemanApp.prototype, {
  async _fetchHistorySessions() {
    const res = await fetch('/api/history/sessions');
    const data = await res.json();
-    const sessions = data.sessions || [];
+    const sessions = data.data?.sessions || [];
    if (sessions.length === 0) return [];

    const byProject = new Map();
@@ -1046,7 +1138,7 @@ Object.assign(CodemanApp.prototype, {
      // Prefer already-loaded this.cases to avoid an extra request.
      const casesPromise = Array.isArray(this.cases) && this.cases.length > 0
        ? Promise.resolve(this.cases)
-        : fetch('/api/cases').then((r) => (r.ok ? r.json() : [])).catch(() => []);
+        : fetch('/api/cases').then((r) => (r.ok ? r.json() : null)).then((d) => d?.data || []).catch(() => []);
      const [allSessions, cases] = await Promise.all([
        this._fetchHistorySessions(30),
        casesPromise,
@@ -1173,8 +1265,8 @@ Object.assign(CodemanApp.prototype, {
      const url = `/api/history/sessions?projectKey=${encodeURIComponent(projectKey)}&offset=${offset}&limit=${limit}`;
      const res = await fetch(url);
      const data = await res.json();
-      const sessions = data.sessions || [];
-      state.total = typeof data.total === 'number' ? data.total : sessions.length + offset;
+      const sessions = data.data?.sessions || [];
+      state.total = typeof data.data?.total === 'number' ? data.data.total : sessions.length + offset;

      if (offset === 0 && sessions.length === 0) {
        const empty = document.createElement('div');
@@ -1261,7 +1353,7 @@ Object.assign(CodemanApp.prototype, {
      const createData = await createRes.json();
      if (!createData.success) throw new Error(createData.error);

-      const newSessionId = createData.session.id;
+      const newSessionId = createData.data.session.id;

      // Start interactive
      await fetch(`/api/sessions/${newSessionId}/interactive`, { method: 'POST' });
@@ -1291,6 +1383,22 @@ Object.assign(CodemanApp.prototype, {
    return buffer.viewportY >= buffer.baseY - 2;
  },

+  // Record manual scroll gestures so sticky-scroll can give an upward scroll a
+  // short grace window (see _hasRecentUserScrollUp). A downward scroll that
+  // lands back at the bottom clears the suppression immediately.
+  _noteTerminalUserScroll(lines) {
+    if (lines < 0) {
+      this._lastUserScrollUpAt = performance.now();
+    } else if (this.isTerminalAtBottom()) {
+      this._lastUserScrollUpAt = null;
+    }
+  },
+
+  _hasRecentUserScrollUp() {
+    if (typeof this._lastUserScrollUpAt !== 'number') return false;
+    return performance.now() - this._lastUserScrollUpAt < window.CodemanTerminalInput.USER_SCROLL_STICKY_SUPPRESS_MS;
+  },
+
  batchTerminalWrite(data) {
    // If a buffer load (chunkedTerminalWrite) is in progress, queue live events
    // to prevent interleaving historical buffer data with live SSE data.
@@ -1426,12 +1534,104 @@ Object.assign(CodemanApp.prototype, {
        this._localEchoOverlay.clear();
        this._localEchoEnabled = false;
      } else {
-        // Claude Code: scan for ❯ prompt character
-        this._localEchoOverlay.setPrompt({ type: 'character', char: '\u276f', offset: 2 });
+        // Codex/Claude-style TUIs usually expose a ❯ prompt. During active
+        // redraws or compact mobile layouts that marker may not be present in
+        // the viewport, while xterm's cursor still marks the editable input
+        // position. Fall back to cursor coordinates so phone typing appears at
+        // the terminal cursor instead of disappearing into pending state.
+        this._localEchoOverlay.setPrompt({
+          type: 'custom',
+          offset: 0,
+          find: (terminal) => {
+            try {
+              const buf = terminal.buffer.active;
+              for (let row = terminal.rows - 1; row >= 0; row--) {
+                const line = buf.getLine(buf.viewportY + row);
+                if (!line) continue;
+                const text = line.translateToString(true);
+                const idx = text.lastIndexOf('\u276f');
+                if (idx >= 0) return { row, col: idx + 2 };
+              }
+              return {
+                row: Math.max(0, Math.min(terminal.rows - 1, buf.cursorY)),
+                col: Math.max(0, Math.min(terminal.cols - 1, buf.cursorX)),
+              };
+            } catch {
+              return null;
+            }
+          },
+        });
      }
    }
  },

+  _handleCjkInput(text) {
+    if (!this.activeSessionId) return;
+    const sessionId = this.activeSessionId;
+    const session = this.sessions.get(sessionId);
+    const useLocalEcho = !!(this._localEchoEnabled && this._localEchoOverlay && session?.mode !== 'shell');
+    if (!useLocalEcho) {
+      this._sendInputAsync(sessionId, text);
+      return;
+    }
+
+    if (text === '\x7f') {
+      const source = this._localEchoOverlay.removeChar();
+      if (source === 'flushed') {
+        // Sync app-level flushed Maps (per-session state for tab switching),
+        // mirroring the onData backspace path — otherwise switching tabs away
+        // and back restores a stale, too-long flushed overlay.
+        const { count, text: flushedText } = this._localEchoOverlay.getFlushed();
+        if (this._flushedOffsets?.has(sessionId)) {
+          if (count === 0) {
+            this._flushedOffsets.delete(sessionId);
+            this._flushedTexts?.delete(sessionId);
+          } else {
+            this._flushedOffsets.set(sessionId, count);
+            this._flushedTexts?.set(sessionId, flushedText);
+          }
+        }
+        this._sendInputAsync(sessionId, text);
+      }
+      return;
+    }
+
+    if (/[\r\n]+$/.test(text)) {
+      const committed = text.replace(/[\r\n]+$/g, '');
+      if (committed) this._localEchoOverlay.appendText(committed);
+      const pending = this._localEchoOverlay.pendingText || '';
+      this._localEchoOverlay.clear();
+      this._localEchoOverlay.suppressBufferDetection();
+      this._flushedOffsets?.delete(sessionId);
+      this._flushedTexts?.delete(sessionId);
+      if (pending) this._sendInputAsync(sessionId, pending);
+      setTimeout(() => this._sendInputAsync(sessionId, '\r'), pending ? 80 : 0);
+      return;
+    }
+
+    // Multi-byte escape sequence (arrow/Home/End from a hardware keyboard on
+    // the composer) — forward to the PTY without touching overlay state,
+    // mirroring the onData path. Appending it to pending text would type raw
+    // ESC bytes into the prompt on the next Enter.
+    if (text.length > 1 && text.charCodeAt(0) === 27) {
+      this._sendInputAsync(sessionId, text);
+      return;
+    }
+
+    if (text.length === 1 && text.charCodeAt(0) < 32) {
+      const pending = this._localEchoOverlay.pendingText || '';
+      this._localEchoOverlay.clear();
+      this._localEchoOverlay.suppressBufferDetection();
+      this._flushedOffsets?.delete(sessionId);
+      this._flushedTexts?.delete(sessionId);
+      if (pending) this._sendInputAsync(sessionId, pending);
+      this._sendInputAsync(sessionId, text);
+      return;
+    }
+
+    this._localEchoOverlay.appendText(text);
+  },
+
  /**
   * Flush pending writes to terminal, processing DEC 2026 sync markers.
   * Strips markers and writes content atomically within a single frame.
@@ -1450,8 +1650,16 @@ Object.assign(CodemanApp.prototype, {

    // Per-frame byte budget to prevent main thread blocking.
    // Large writes (141KB+) can freeze Chrome for 2+ minutes.
-    const MAX_FRAME_BYTES = 65536; // 64KB budget per frame
+    // Codex's TUI emits dense synchronized redraws during thinking/high-effort
+    // phases, so it gets a smaller first frame to keep per-frame xterm/WebGL
+    // stalls short; other modes keep the larger 64KB budget.
+    const activeSession = this.activeSessionId && this.sessions ? this.sessions.get(this.activeSessionId) : null;
+    const MAX_FRAME_BYTES = activeSession?.mode === 'codex' ? 32768 : 65536;
    let deferred = false;
+    // If the user recently scrolled up, remember the viewport so we can restore
+    // it after the write — Codex status redraws would otherwise jump it.
+    const preserveViewportY =
+      this._hasRecentUserScrollUp() && this.terminal.buffer?.active ? this.terminal.buffer.active.viewportY : null;

    if (_joinedLen <= MAX_FRAME_BYTES) {
      this.terminal.write(joined);
@@ -1468,6 +1676,13 @@ Object.assign(CodemanApp.prototype, {
        });
      }
    }
+    if (
+      preserveViewportY !== null &&
+      this.terminal.buffer?.active?.viewportY !== preserveViewportY &&
+      typeof this.terminal.scrollToLine === 'function'
+    ) {
+      this.terminal.scrollToLine(preserveViewportY);
+    }
    const bytesThisFrame = deferred ? MAX_FRAME_BYTES : _joinedLen;
    const _dt = performance.now() - _t0;
    if (_dt > 100 || deferred)
@@ -1475,8 +1690,11 @@ Object.assign(CodemanApp.prototype, {
        `[CRASH-DIAG] flushPendingWrites: ${_dt.toFixed(0)}ms, ${(bytesThisFrame / 1024).toFixed(0)}KB written${deferred ? ', rest deferred' : ''} (total ${(_joinedLen / 1024).toFixed(0)}KB)`
      );

-    // Sticky scroll: if user was at bottom, keep them there after new output
-    if (this._wasAtBottomBeforeWrite) {
+    // Sticky scroll: if user was at bottom, keep them there after new output.
+    // Give manual scroll-up gestures a short grace window so high-frequency
+    // Codex status ticks do not snap the viewport back while the user is
+    // trying to inspect earlier output.
+    if (this._wasAtBottomBeforeWrite && !this._hasRecentUserScrollUp()) {
      this.terminal.scrollToBottom();
    }

@@ -1594,6 +1812,38 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  scrollToLastNonEmptyLine() {
+    if (!this.terminal?.buffer?.active) {
+      this.terminal?.scrollToBottom?.();
+      return;
+    }
+
+    const buffer = this.terminal.buffer.active;
+    const totalLines = buffer.baseY + buffer.length;
+    let lastNonEmptyLine = -1;
+
+    for (let lineIndex = totalLines - 1; lineIndex >= 0; lineIndex--) {
+      const line = buffer.getLine(lineIndex);
+      if (line?.translateToString(true).trim()) {
+        lastNonEmptyLine = lineIndex;
+        break;
+      }
+    }
+
+    if (lastNonEmptyLine >= 0 && typeof this.terminal.scrollToLine === 'function') {
+      let targetLine = Math.max(0, lastNonEmptyLine - this.terminal.rows + 2);
+      const maxTargetLine = Math.max(0, lastNonEmptyLine);
+      while (targetLine < maxTargetLine) {
+        const line = buffer.getLine(targetLine);
+        if (line?.translateToString(true).trim()) break;
+        targetLine++;
+      }
+      this.terminal.scrollToLine(targetLine);
+    } else {
+      this.terminal.scrollToBottom();
+    }
+  },
+
  /**
   * Write large buffer to terminal in chunks to avoid UI jank.
   * Uses _safeYield to spread work across frames; falls back to setTimeout
@@ -1602,22 +1852,19 @@ Object.assign(CodemanApp.prototype, {
   * @param {number} chunkSize - Size of each chunk (default 128KB for smooth 60fps)
   * @returns {Promise<void>} - Resolves when all chunks written
   */
-  chunkedTerminalWrite(buffer, chunkSize = TERMINAL_CHUNK_SIZE) {
+  chunkedTerminalWrite(buffer, chunkSize = TERMINAL_CHUNK_SIZE, loadOwner) {
    // Generation counter: if a newer chunkedTerminalWrite starts (tab switch),
    // older writes abort instead of continuing to push stale data into the terminal.
    const writeGen = ++this._chunkedWriteGen;
+    const bufferLoadOwner = this._beginBufferLoad(loadOwner);

    return new Promise((resolve) => {
      if (!buffer || buffer.length === 0) {
-        this._finishBufferLoad();
+        this._finishBufferLoad(bufferLoadOwner);
        resolve();
        return;
      }

-      // Block live SSE writes during buffer load to prevent interleaving
-      this._isLoadingBuffer = true;
-      this._loadBufferQueue = [];
-
      // Strip any DEC 2026 markers that might be in the buffer
      // (from historical SSE data that was stored with markers)
      const cleanBuffer = buffer.replace(DEC_SYNC_STRIP_RE, '');
@@ -1625,15 +1872,14 @@ Object.assign(CodemanApp.prototype, {
      const finish = () => {
        // Only finish if we're still the active write — a newer write owns buffer load state
        if (this._chunkedWriteGen === writeGen) {
-          this._finishBufferLoad();
+          this._finishBufferLoad(bufferLoadOwner);
        }
        resolve();
      };

      // For small buffers, write directly — single-frame render is fast enough
      if (cleanBuffer.length <= chunkSize) {
-        this.terminal.write(cleanBuffer);
-        finish();
+        this.terminal.write(cleanBuffer, finish);
        return;
      }

@@ -1691,9 +1937,23 @@ Object.assign(CodemanApp.prototype, {
   * (especially Ink cursor-up redraws), corrupting the terminal display.
   * After unblocking, new SSE/WS events deliver subsequent output normally.
   */
-  _finishBufferLoad() {
+  _beginBufferLoad(owner) {
+    if (this._bufferLoadSeq === undefined) this._bufferLoadSeq = 0;
+    const loadOwner = owner === undefined ? `buffer-${++this._bufferLoadSeq}` : owner;
+    this._bufferLoadOwner = loadOwner;
+    this._isLoadingBuffer = true;
+    this._loadBufferQueue = [];
+    return loadOwner;
+  },
+
+  _finishBufferLoad(owner) {
+    if (owner !== undefined && this._bufferLoadOwner !== owner) {
+      return false;
+    }
    this._isLoadingBuffer = false;
    this._loadBufferQueue = null;
+    this._bufferLoadOwner = null;
+    return true;
  },

  // ═══════════════════════════════════════════════════════════════
@@ -1765,6 +2025,23 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  _syncMobileHelperTextareaToCursor() {
+    if (!MobileDetection.isTouchDevice() || !this.terminal?.element) return;
+    try {
+      const xtermEl = this.terminal.element;
+      const cursor = this.terminal.element.querySelector('.xterm-cursor');
+      const screen = this.terminal.element.querySelector('.xterm-screen');
+      if (!(xtermEl instanceof HTMLElement) || !(cursor instanceof HTMLElement) || !(screen instanceof HTMLElement)) return;
+      const cursorRect = cursor.getBoundingClientRect();
+      const screenRect = screen.getBoundingClientRect();
+      if (!cursorRect.width && !cursorRect.height) return;
+      const left = Math.max(0, Math.round(cursorRect.left - screenRect.left));
+      const top = Math.max(0, Math.round(cursorRect.top - screenRect.top));
+      xtermEl.style.setProperty('--xterm-helper-left', `${left}px`);
+      xtermEl.style.setProperty('--xterm-helper-top', `${top}px`);
+    } catch {}
+  },
+
  increaseFontSize() {
    const current = this.terminal.options.fontSize || 14;
    this.setFontSize(Math.min(current + 2, 24));
@@ -1814,23 +2091,38 @@ Object.assign(CodemanApp.prototype, {
  /**
   * Send resize to a session with minimum dimension enforcement.
   * @param {string} sessionId
+   * @param {{ forceHttp?: boolean }} [options]
   * @returns {Promise<void>}
   */
-  async sendResize(sessionId) {
+  async sendResize(sessionId, options = {}) {
    // Fit terminal to container before reading dimensions — ensures local
    // terminal size matches what we report to the server PTY.
    if (this.fitAddon) this.fitAddon.fit();
    const dims = this.getTerminalDimensions();
-    if (!dims) return;
+    if (!dims) return false;
+    // Did the dimensions actually change since the last resize we sent? Callers
+    // use this to skip work (e.g. the post-resize TUI-redraw settle) when no
+    // real SIGWINCH was triggered — switching tabs at the same browser size is
+    // a no-op on the server and needs no redraw grace.
+    const prev = this._lastResizeDims;
+    const changed = !prev || prev.cols !== dims.cols || prev.rows !== dims.rows;
    // Update _lastResizeDims so the throttledResize handler won't redundantly
    // clear the terminal for the same dimensions (which would blank the screen
    // without a subsequent Ink redraw to repaint it).
    this._lastResizeDims = { cols: dims.cols, rows: dims.rows };
+    const viewportType =
+      typeof MobileDetection !== 'undefined' && MobileDetection.getDeviceType
+        ? MobileDetection.getDeviceType()
+        : window.innerWidth < 430
+          ? 'mobile'
+          : window.innerWidth < 768
+            ? 'tablet'
+            : 'desktop';
    // Fast path: WebSocket resize
-    if (this._wsReady && this._wsSessionId === sessionId) {
+    if (!options.forceHttp && this._wsReady && this._wsSessionId === sessionId) {
      try {
-        this._ws.send(JSON.stringify({ t: 'z', c: dims.cols, r: dims.rows }));
-        return;
+        this._ws.send(JSON.stringify({ t: 'z', c: dims.cols, r: dims.rows, v: viewportType }));
+        return changed;
      } catch {
        // Fall through to HTTP POST
      }
@@ -1838,8 +2130,9 @@ Object.assign(CodemanApp.prototype, {
    await fetch(`/api/sessions/${sessionId}/resize`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(dims),
+      body: JSON.stringify({ ...dims, viewportType }),
    });
+    return changed;
  },

  /**
@@ -1883,4 +2176,27 @@ Object.assign(CodemanApp.prototype, {
      document.getElementById('dirDisplay').textContent = value || 'No directory';
    }, 100);
  },
+
+  // Re-theme all live xterm terminals (main + teammate) to the given skin's palette.
+  // Uses the xterm v5+ live setter (full object assignment triggers a repaint for both
+  // DOM and WebGL renderers) plus a belt-and-suspenders refresh().
+  applyTerminalSkin(skin) {
+    const theme = { ...(window.CODEMAN_XTERM_THEMES[skin] || window.CODEMAN_XTERM_THEMES['daylight-blue']) };
+    if (this.terminal) {
+      this.terminal.options.theme = theme;
+      try {
+        this.terminal.refresh(0, this.terminal.rows - 1);
+      } catch {}
+    }
+    if (this.teammateTerminals) {
+      for (const [, entry] of this.teammateTerminals) {
+        if (entry && entry.terminal) {
+          entry.terminal.options.theme = { ...theme };
+          try {
+            entry.terminal.refresh(0, entry.terminal.rows - 1);
+          } catch {}
+        }
+      }
+    }
+  },
 });
@@ -262,7 +262,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    const fixPlanPath = join(casePath, '@fix_plan.md');

    if (!existsSync(fixPlanPath)) {
-      return { success: true, exists: false, content: null, todos: [] };
+      return { exists: false, content: null, todos: [] };
    }

    try {
@@ -339,7 +339,6 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
      const stats = { total: todos.length, pending, inProgress, completed };

      return {
-        success: true,
        exists: true,
        content,
        todos,
@@ -6,19 +6,20 @@
 import { FastifyInstance } from 'fastify';
 import { SseEvent } from '../sse-events.js';
 import type { EventPort } from '../ports/index.js';
+import { createErrorResponse, ApiErrorCode } from '../../types.js';

 export function registerClipboardRoutes(app: FastifyInstance, ctx: EventPort): void {
  app.post('/api/clipboard', async (req) => {
    const body = req.body as { text?: string; sessionId?: string };
    const text = body?.text;
    if (typeof text !== 'string' || text.length === 0) {
-      return { success: false, error: 'Missing or empty "text" field' };
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing or empty "text" field');
    }
    ctx.broadcast(SseEvent.ClipboardWrite, {
      text,
      sessionId: body.sessionId ?? null,
      timestamp: Date.now(),
    });
-    return { success: true };
+    return {};
  });
 }
@@ -3,16 +3,163 @@
 * Provides directory listing, file content preview, raw file serving, and tail streaming.
 */

-import { FastifyInstance } from 'fastify';
+import { FastifyInstance, type FastifyReply } from 'fastify';
 import { basename as pathBasename, join } from 'node:path';
-import { homedir } from 'node:os';
+import { createReadStream, realpathSync, type ReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import { fileStreamManager } from '../../file-stream-manager.js';
+import {
+  AttachmentRegistrationError,
+  attachmentRegistry,
+  registerExternalAttachment,
+  type AttachmentRecord,
+} from '../../attachment-registry.js';
+import { isBlockedAttachmentPath, loadAttachmentGuardConfig } from '../../config/attachment-guard.js';
 import { findSessionOrFail, validateSessionFilePath } from '../route-helpers.js';
-import type { SessionPort } from '../ports/index.js';
+import { isSensitivePath } from '../sensitive-path.js';
+import { SseEvent } from '../sse-events.js';
+import type { EventPort, SessionPort } from '../ports/index.js';

-export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void {
+const MIME_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  bmp: 'image/bmp',
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  json: 'application/json',
+  md: 'text/markdown',
+  txt: 'text/plain',
+};
+
+function sanitizeDownloadName(fileName: string): string {
+  return fileName.replace(/["\\\r\n]/g, '_');
+}
+
+function sendRawStream(reply: FastifyReply, content: ReadStream): void {
+  const headers = reply.getHeaders();
+  reply.hijack();
+
+  for (const [name, value] of Object.entries(headers)) {
+    if (value !== undefined) {
+      reply.raw.setHeader(name, value);
+    }
+  }
+
+  content.on('error', (err) => {
+    if (reply.raw.headersSent) {
+      reply.raw.destroy(err);
+      return;
+    }
+
+    reply.raw.statusCode = 500;
+    reply.raw.end('Failed to read file');
+  });
+  content.pipe(reply.raw);
+}
+
+async function serveRawFile(
+  reply: FastifyReply,
+  resolvedPath: string,
+  fileName: string,
+  extension: string,
+  download?: boolean
+): Promise<void> {
+  const stat = await fs.stat(resolvedPath);
+  const MAX_RAW_ATTACHMENT_SIZE = 50 * 1024 * 1024; // 50MB, matching file-raw / download
+  if (stat.size > MAX_RAW_ATTACHMENT_SIZE) {
+    reply
+      .code(413)
+      .send(
+        createErrorResponse(
+          ApiErrorCode.INVALID_INPUT,
+          `File too large (${Math.round(stat.size / 1024 / 1024)}MB > ${MAX_RAW_ATTACHMENT_SIZE / 1024 / 1024}MB limit)`
+        )
+      );
+    return;
+  }
+  const content = createReadStream(resolvedPath);
+  const safeName = sanitizeDownloadName(fileName);
+  if (download || extension === 'svg') {
+    reply.header(
+      'Content-Type',
+      extension === 'svg' ? 'application/octet-stream' : MIME_TYPES[extension] || 'application/octet-stream'
+    );
+    reply.header('Content-Disposition', `attachment; filename="${safeName}"`);
+    reply.header('Content-Length', stat.size);
+    reply.header('X-Content-Type-Options', 'nosniff');
+    sendRawStream(reply, content);
+    return;
+  }
+
+  reply.header('Content-Type', MIME_TYPES[extension] || 'application/octet-stream');
+  reply.header('Content-Disposition', `inline; filename="${safeName}"`);
+  reply.header('Content-Length', stat.size);
+  reply.header('X-Content-Type-Options', 'nosniff');
+  sendRawStream(reply, content);
+}
+
+function getAttachmentOr404(
+  reply: FastifyReply,
+  sessionId: string,
+  attachmentId: string
+): AttachmentRecord | undefined {
+  const record = attachmentRegistry.get(sessionId, attachmentId);
+  if (!record) {
+    reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'Attachment not found'));
+    return undefined;
+  }
+  return record;
+}
+
+/**
+ * COD-53 defense-in-depth: refuse to stream a record whose underlying path is
+ * blocked by the active attachment-guard policy, even though registration
+ * already blocks them. Guards against records that predate the guard or were
+ * crafted to point at a sensitive file. Resolves symlinks before the check so a
+ * record pointing at a symlink that now resolves to a sensitive target is also
+ * caught; if the path can't be resolved (deleted/unreadable) the check still
+ * runs on the stored path. When workspace confinement is enabled it additionally
+ * rejects any record outside the session workspace. Returns true (and sends a
+ * 403) when blocked.
+ */
+async function resolveServableAttachmentPath(
+  reply: FastifyReply,
+  record: AttachmentRecord,
+  sessionWorkingDir?: string
+): Promise<string | null> {
+  let pathToCheck = record.filePath;
+  let resolved = false;
+  try {
+    pathToCheck = realpathSync(record.filePath);
+    resolved = true;
+  } catch {
+    // Fall back to the stored (already realpath-resolved at registration) path.
+  }
+
+  const guard = await loadAttachmentGuardConfig();
+
+  const blocked =
+    isBlockedAttachmentPath(pathToCheck, guard.blockedTrees) ||
+    isBlockedAttachmentPath(record.filePath, guard.blockedTrees) ||
+    (guard.confineToWorkspace && (!sessionWorkingDir || !validateSessionFilePath(sessionWorkingDir, pathToCheck)));
+
+  if (blocked) {
+    reply.code(403).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Access to this file is blocked'));
+    return null;
+  }
+  // Serve the freshly-resolved path, not the stored one: if a path component
+  // became a symlink after registration, the guard checked the resolved target
+  // but streaming record.filePath would follow the symlink to a swapped file.
+  return resolved ? pathToCheck : record.filePath;
+}
+
+export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort & EventPort): void {
  // File tree listing
  app.get('/api/sessions/:id/files', async (req) => {
    const { id } = req.params as { id: string };
@@ -315,6 +462,59 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
    }
  });

+  // ===== Live external attachments =====
+  // Register an explicit, live external file (absolute host path) as an
+  // attachment with a stable id so browser requests never carry arbitrary
+  // paths. Registration enforces the COD-53 attachment-guard policy. Serving is
+  // by id via the /raw route below; document previews/thumbnails and the
+  // attachment-history list are layered on separately.
+  app.post('/api/sessions/:id/attachments', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const session = findSessionOrFail(ctx, id);
+    const body = (req.body || {}) as { path?: string };
+
+    if (!body.path || typeof body.path !== 'string') {
+      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing attachment path'));
+      return;
+    }
+
+    try {
+      const event = await registerExternalAttachment(id, body.path, { sessionWorkingDir: session.workingDir });
+      ctx.broadcast(SseEvent.AttachmentDetected, event);
+      return { success: true, data: event };
+    } catch (err) {
+      if (err instanceof AttachmentRegistrationError) {
+        reply.code(err.statusCode).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, err.message));
+        return;
+      }
+      return reply
+        .code(500)
+        .send(
+          createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to register attachment: ${getErrorMessage(err)}`)
+        );
+    }
+  });
+
+  // Serve the raw bytes of a registered attachment by id. Re-checks the
+  // attachment-guard policy on every request (defense-in-depth) before streaming.
+  app.get('/api/sessions/:id/attachments/:attachmentId/raw', async (req, reply) => {
+    const { id, attachmentId } = req.params as { id: string; attachmentId: string };
+    const { download } = req.query as { download?: string };
+    const session = findSessionOrFail(ctx, id);
+    const record = getAttachmentOr404(reply, id, attachmentId);
+    if (!record) return;
+    const servePath = await resolveServableAttachmentPath(reply, record, session.workingDir);
+    if (!servePath) return;
+
+    try {
+      await serveRawFile(reply, servePath, record.fileName, record.extension, download === 'true');
+    } catch (err) {
+      reply
+        .code(500)
+        .send(createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to read file: ${getErrorMessage(err)}`));
+    }
+  });
+
  // Stream file content via tail -f (SSE endpoint)
  app.get('/api/sessions/:id/tail-file', async (req, reply) => {
    const { id } = req.params as { id: string };
@@ -375,33 +575,20 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
    });
  });

-  // Close a file stream
+  // Close a file stream. Returns { closed } rather than { success: closed } —
+  // a top-level `success` key would collide with the envelope discriminator
+  // (the preSerialization hook would pass `{success:false}` through as a
+  // malformed error envelope instead of wrapping it).
  app.delete('/api/sessions/:id/tail-file/:streamId', async (req) => {
    const { id, streamId } = req.params as { id: string; streamId: string };
    findSessionOrFail(ctx, id); // Validates session exists
    const closed = fileStreamManager.closeStream(streamId);
-    return { success: closed };
+    return { closed };
  });
  // Session-scoped file download.
  // Uses the same realpath-based workspace boundary as file preview/raw routes;
-  // the sensitive-path blocklist remains defense-in-depth, not the primary boundary.
-  const SENSITIVE_PATTERNS: RegExp[] = [
-    /^\/etc\/shadow$/,
-    /^\/etc\/gshadow$/,
-    /^\/etc\/master\.passwd$/,
-    new RegExp(`^${homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\.ssh\\/`),
-    /\/\.env$/,
-    /\/\.env\./,
-    /\/credentials(\.json|\.yml|\.yaml|\.xml)?$/i,
-    /\/\.aws\/credentials$/,
-    /\/\.gcloud\/credentials\.db$/,
-    /\/\.docker\/config\.json$/,
-  ];
-
-  function isSensitivePath(absPath: string): boolean {
-    return SENSITIVE_PATTERNS.some((pattern) => pattern.test(absPath));
-  }
-
+  // the shared sensitive-path blocklist (../sensitive-path.js, also used by the
+  // attachment guard) remains defense-in-depth, not the primary boundary.
  app.get('/api/download', async (req, reply) => {
    const { path: filePath, sessionId } = req.query as { path?: string; sessionId?: string };

@@ -66,6 +66,6 @@ export function registerHookEventRoutes(
      summaryTracker.recordHookEvent(event, safeData);
    }

-    return { success: true };
+    return {};
  });
 }
@@ -19,7 +19,7 @@ export function registerMuxRoutes(app: FastifyInstance, ctx: InfraPort): void {
  app.delete('/api/mux-sessions/:sessionId', async (req) => {
    const { sessionId } = req.params as { sessionId: string };
    const success = await ctx.mux.killSession(sessionId);
-    return { success };
+    return { killed: success };
  });

  app.post('/api/mux-sessions/reconcile', async () => {
@@ -29,11 +29,11 @@ export function registerMuxRoutes(app: FastifyInstance, ctx: InfraPort): void {

  app.post('/api/mux-sessions/stats/start', async () => {
    ctx.mux.startStatsCollection(STATS_COLLECTION_INTERVAL_MS);
-    return { success: true };
+    return {};
  });

  app.post('/api/mux-sessions/stats/stop', async () => {
    ctx.mux.stopStatsCollection();
-    return { success: true };
+    return {};
  });
 }
@@ -408,7 +408,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
    }

-    return { success: true, data: tracker.getPlanHistory() };
+    return { success: true, data: { history: tracker.getPlanHistory(), currentVersion: tracker.planVersion } };
  });

  // ========== Rollback to Version ==========
@@ -35,7 +35,7 @@ export function registerPushRoutes(app: FastifyInstance, ctx: InfraPort): void {
    if (!updated) {
      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subscription not found');
    }
-    return { success: true };
+    return {};
  });

  app.delete('/api/push/subscribe/:id', async (req) => {
@@ -44,6 +44,6 @@ export function registerPushRoutes(app: FastifyInstance, ctx: InfraPort): void {
    if (!removed) {
      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subscription not found');
    }
-    return { success: true };
+    return {};
  });
 }
@@ -9,13 +9,14 @@ import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from '../../types.js';
-import { Session } from '../../session.js';
+import { Session, isExternalCliMode } from '../../session.js';
 import { RespawnController } from '../../respawn-controller.js';
 import { RalphConfigSchema, FixPlanImportSchema, RalphPromptWriteSchema, RalphLoopStartSchema } from '../schemas.js';
 import { SseEvent } from '../sse-events.js';
 import { autoConfigureRalph, CASES_DIR, SETTINGS_PATH, findSessionOrFail, parseBody } from '../route-helpers.js';
 import { writeHooksConfig, stripCaseEnvKeys } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
+import { buildRalphLoopPrompt } from '../../prompts/index.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 import { MAX_CONCURRENT_SESSIONS } from '../../config/map-limits.js';
@@ -44,9 +45,12 @@ export function registerRalphRoutes(
    };
    const session = findSessionOrFail(ctx, id);

-    // Ralph tracker is not supported for opencode sessions
-    if (session.mode === 'opencode') {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Ralph tracker is not supported for opencode sessions');
+    // Ralph tracker is not supported for external-CLI sessions (opencode/codex)
+    if (isExternalCliMode(session.mode)) {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        `Ralph tracker is not supported for ${session.mode} sessions`
+      );
    }

    // Handle reset first (before other config)
@@ -101,7 +105,7 @@ export function registerRalphRoutes(
      state: session.ralphLoopState,
    });

-    return { success: true };
+    return {};
  });

  // Reset circuit breaker for Ralph tracker
@@ -110,7 +114,7 @@ export function registerRalphRoutes(
    const session = findSessionOrFail(ctx, id);

    session.ralphTracker.resetCircuitBreaker();
-    return { success: true };
+    return {};
  });

  // Get Ralph status block and circuit breaker state
@@ -379,37 +383,12 @@ export function registerRalphRoutes(
      writeFileSync(fixPlanPath, planContent, 'utf-8');
    }

-    // Build full prompt
-    const hasPlan = enabledItems.length > 0;
-    let fullPrompt = taskDescription + '\n\n---\n\n';
-    if (hasPlan) {
-      fullPrompt += '## Task Plan\n\n';
-      fullPrompt += 'A task plan has been written to `@fix_plan.md`. Use this to track progress:\n';
-      fullPrompt += '- Reference the plan at the start of each iteration\n';
-      fullPrompt += '- Update task checkboxes as you complete items\n';
-      fullPrompt += '- Work through items in priority order (P0 > P1 > P2)\n\n';
-    }
-    fullPrompt += '## Iteration Protocol\n\n';
-    fullPrompt += 'This is an autonomous loop. Files from previous iterations persist. On each iteration:\n';
-    fullPrompt += '1. Check what work has already been done\n';
-    fullPrompt += '2. Make incremental progress toward completion\n';
-    fullPrompt += '3. Commit meaningful changes with descriptive messages\n\n';
-    fullPrompt += '## Verification\n\n';
-    fullPrompt += 'After each significant change:\n';
-    fullPrompt += '- Run tests to verify (npm test, pytest, etc.)\n';
-    fullPrompt += '- Check for type/lint errors if applicable\n';
-    fullPrompt += '- If tests fail, read the error, fix it, and retry\n\n';
-    fullPrompt += '## Completion Criteria\n\n';
-    fullPrompt += `Output \`<promise>${completionPhrase}</promise>\` when ALL of the following are true:\n`;
-    fullPrompt += '- All requirements from the task description are implemented\n';
-    fullPrompt += '- All tests pass\n';
-    fullPrompt += '- Changes are committed\n\n';
-    fullPrompt += '## If Stuck\n\n';
-    fullPrompt += 'If you encounter the same error for 3+ iterations:\n';
-    fullPrompt += "1. Document what you've tried\n";
-    fullPrompt += '2. Identify the specific blocker\n';
-    fullPrompt += '3. Try an alternative approach\n';
-    fullPrompt += '4. If truly blocked, output `<promise>BLOCKED</promise>` with an explanation\n';
+    // Build full prompt (includes the RALPH_STATUS contract)
+    const fullPrompt = buildRalphLoopPrompt({
+      taskDescription,
+      completionPhrase,
+      hasPlan: enabledItems.length > 0,
+    });

    // Write prompt to file
    const promptPath = join(casePath, '@ralph_prompt.md');
@@ -11,6 +11,7 @@ import { SseEvent } from '../sse-events.js';
 import { findSessionOrFail, autoConfigureRalph, parseBody } from '../route-helpers.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
+import { isExternalCliMode } from '../../session.js';
 import {
  AI_CHECK_MODEL,
  AI_IDLE_CHECK_MAX_CONTEXT,
@@ -62,16 +63,16 @@ export function registerRespawnRoutes(
    const controller = ctx.respawnControllers.get(id);

    if (controller) {
-      return { success: true, config: controller.getConfig(), active: true };
+      return { config: controller.getConfig(), active: true };
    }

    // Return pre-saved config from mux-sessions.json
    const preConfig = ctx.mux.getSession(id)?.respawnConfig;
    if (preConfig) {
-      return { success: true, config: preConfig, active: false };
+      return { config: preConfig, active: false };
    }

-    return { success: true, config: null, active: false };
+    return { config: null, active: false };
  });

  // ═══════════════════════════════════════════════════════════════
@@ -88,9 +89,9 @@ export function registerRespawnRoutes(
    }
    const session = findSessionOrFail(ctx, id);

-    // Respawn is not supported for opencode sessions
-    if (session.mode === 'opencode') {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
+    // Respawn is not supported for external-CLI sessions (opencode/codex)
+    if (isExternalCliMode(session.mode)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);
    }

    // Create or get existing controller
@@ -114,7 +115,7 @@ export function registerRespawnRoutes(

    ctx.broadcast(SseEvent.RespawnStarted, { sessionId: id, status: controller.getStatus() });

-    return { success: true, status: controller.getStatus() };
+    return { status: controller.getStatus() };
  });

  // ========== Stop Respawn ==========
@@ -150,7 +151,7 @@ export function registerRespawnRoutes(

    ctx.broadcast(SseEvent.RespawnStopped, { sessionId: id });

-    return { success: true };
+    return {};
  });

  // ========== Update Respawn Config ==========
@@ -169,7 +170,7 @@ export function registerRespawnRoutes(
      ctx.saveRespawnConfig(id, controller.getConfig());
      ctx.persistSessionState(session);
      ctx.broadcast(SseEvent.RespawnConfigUpdated, { sessionId: id, config: controller.getConfig() });
-      return { success: true, config: controller.getConfig() };
+      return { config: controller.getConfig() };
    }

    // No controller running - save as pre-config for when respawn starts
@@ -206,7 +207,7 @@ export function registerRespawnRoutes(
    ctx.mux.updateRespawnConfig(id, merged);
    ctx.persistSessionState(session);
    ctx.broadcast(SseEvent.RespawnConfigUpdated, { sessionId: id, config: merged });
-    return { success: true, config: merged };
+    return { config: merged };
  });

  // ═══════════════════════════════════════════════════════════════
@@ -231,9 +232,9 @@ export function registerRespawnRoutes(
      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
    }

-    // Respawn is not supported for opencode sessions
-    if (session.mode === 'opencode') {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
+    // Respawn is not supported for external-CLI sessions (opencode/codex)
+    if (isExternalCliMode(session.mode)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);
    }

    try {
@@ -296,9 +297,9 @@ export function registerRespawnRoutes(
    const body = reResult.data as { config?: Partial<RespawnConfig>; durationMinutes?: number };
    const session = findSessionOrFail(ctx, id);

-    // Respawn is not supported for opencode sessions
-    if (session.mode === 'opencode') {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Respawn is not supported for opencode sessions');
+    // Respawn is not supported for external-CLI sessions (opencode/codex)
+    if (isExternalCliMode(session.mode)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Respawn is not supported for ${session.mode} sessions`);
    }

    // Check if session is running (has a PID)
@@ -332,7 +333,6 @@ export function registerRespawnRoutes(
    ctx.broadcast(SseEvent.RespawnStarted, { sessionId: id, status: controller.getStatus() });

    return {
-      success: true,
      message: 'Respawn enabled on existing session',
      respawnStatus: controller.getStatus(),
    };
@@ -15,7 +15,7 @@ export function registerScheduledRoutes(app: FastifyInstance, ctx: SessionPort &
    return Array.from(ctx.scheduledRuns.values());
  });

-  app.post('/api/scheduled', async (req): Promise<{ success: boolean; run: ScheduledRun } | ApiResponse<never>> => {
+  app.post('/api/scheduled', async (req): Promise<{ run: ScheduledRun } | ApiResponse<never>> => {
    const { prompt, workingDir, durationMinutes } = parseBody(ScheduledRunSchema, req.body, 'Invalid request body');

    // Validate workingDir exists and is a directory
@@ -31,7 +31,7 @@ export function registerScheduledRoutes(app: FastifyInstance, ctx: SessionPort &
    }

    const run = await ctx.startScheduledRun(prompt, workingDir || process.cwd(), durationMinutes ?? 60);
-    return { success: true, run };
+    return { run };
  });

  app.delete('/api/scheduled/:id', async (req) => {
@@ -43,7 +43,7 @@ export function registerScheduledRoutes(app: FastifyInstance, ctx: SessionPort &
    }

    await ctx.stopScheduledRun(id);
-    return { success: true };
+    return {};
  });

  app.get('/api/scheduled/:id', async (req) => {
@@ -16,7 +16,6 @@ import {
  createErrorResponse,
  getErrorMessage,
  type ApiResponse,
-  type QuickStartResponse,
  type SessionColor,
 } from '../../types.js';
 import { Session } from '../../session.js';
@@ -30,6 +29,7 @@ import {
  ResizeSchema,
  AutoClearSchema,
  AutoCompactSchema,
+  AutoResumeSchema,
  ImageWatcherSchema,
  FlickerFilterSchema,
  QuickRunSchema,
@@ -66,6 +66,31 @@ const CLAUDE_BANNER_PATTERN = /\x1b\[1mClaud/;
 const CTRL_L_PATTERN = /\x0c/g;
 const LEADING_WHITESPACE_PATTERN = /^[\s\r\n]+/;

+/**
+ * Match xterm alternate-screen mode toggles + the standalone scrollback-erase.
+ *
+ * - DECSET/DECRST 47, 1047, 1049 = enter/exit alternate screen buffer
+ *   (1049 also saves cursor and clears the alt buffer).
+ * - CSI 3 J = erase saved lines (scrollback).
+ *
+ * Codex emits `\x1b[?1049h` and clear-scrollback sequences during startup and
+ * on repaint. xterm.js obeys them by switching to the alt buffer (no native
+ * scrollback) and wiping saved lines, so the user's conversation history
+ * disappears on every tab switch / pane refresh. Stripping these from the
+ * replayed byte stream keeps everything in the main buffer with scrollback
+ * intact. Mirrors the live-stream strip in Session._handleTerminalOutput.
+ */
+// eslint-disable-next-line no-control-regex
+const ALT_SCREEN_TOGGLE_PATTERN = /\x1b\[\?(?:47|1047|1049)[hl]/g;
+// eslint-disable-next-line no-control-regex
+const ERASE_SCROLLBACK_PATTERN = /\x1b\[3J/g;
+// Mouse-tracking enables (X10/button/any-event/UTF-8/SGR/alt-scroll) — once on,
+// xterm.js forwards wheel events to the app instead of scrolling the viewport.
+// Live streams are stripped at the source, but buffers persisted BEFORE that
+// strip existed can still carry them; strip on replay for parity.
+// eslint-disable-next-line no-control-regex
+const MOUSE_TRACKING_PATTERN = /\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g;
+
 /**
 * Strip redundant Ink spinner/status-bar redraw frames from the terminal buffer.
 * Ink (Claude Code's TUI) uses absolute cursor positioning (CSI n d = VPA) to animate
@@ -211,7 +236,7 @@ export function registerSessionRoutes(
      ctx.authSessions?.delete(sessionToken);
    }
    reply.clearCookie(AUTH_COOKIE_NAME, { path: '/' });
-    return { success: true };
+    return {};
  });

  // ═══════════════════════════════════════════════════════════════
@@ -283,6 +308,17 @@ export function registerSessionRoutes(
      }
    }

+    // Check Codex availability if requested
+    if (body.mode === 'codex') {
+      const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
+      if (!isCodexAvailable()) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          'Codex CLI not found. Install with: npm install -g @openai/codex'
+        );
+      }
+    }
+
    // Pre-validate resumeSessionId: check that the conversation file actually exists
    // in Claude's projects directory. If not, skip resume to avoid confusing
    // "No conversation found" errors from Claude CLI.
@@ -319,9 +355,11 @@ export function registerSessionRoutes(
    const model =
      mode === 'opencode'
        ? body.openCodeConfig?.model
-        : mode !== 'shell'
-          ? modelConfig?.defaultModel || undefined
-          : undefined;
+        : mode === 'codex'
+          ? body.codexConfig?.model
+          : mode !== 'shell'
+            ? modelConfig?.defaultModel || undefined
+            : undefined;
    const claudeModeConfig = await ctx.getClaudeModeConfig();
    const session = new Session({
      workingDir,
@@ -334,6 +372,7 @@ export function registerSessionRoutes(
      claudeMode: claudeModeConfig.claudeMode,
      allowedTools: claudeModeConfig.allowedTools,
      openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
+      codexConfig: mode === 'codex' ? body.codexConfig : undefined,
      resumeSessionId: validatedResumeId,
      envOverrides: body.envOverrides,
      effort: body.effort,
@@ -349,7 +388,7 @@ export function registerSessionRoutes(
    // Avoids serializing 2-3MB of terminal+text buffers per session creation.
    const lightState = ctx.getSessionStateWithRespawn(session);
    ctx.broadcast(SseEvent.SessionCreated, lightState);
-    return { success: true, session: lightState };
+    return { session: lightState };
  });

  // ========== Rename Session ==========
@@ -364,7 +403,7 @@ export function registerSessionRoutes(
    // Also update the mux session name if applicable
    ctx.mux.updateSessionName(id, session.name);
    persistAndBroadcastSession(ctx, session);
-    return { success: true, name: session.name };
+    return { name: session.name };
  });

  // ========== Set Session Color ==========
@@ -381,12 +420,12 @@ export function registerSessionRoutes(

    session.setColor(body.color as SessionColor);
    persistAndBroadcastSession(ctx, session);
-    return { success: true, color: session.color };
+    return { color: session.color };
  });

  // ========== Delete Session ==========

-  app.delete('/api/sessions/:id', async (req): Promise<ApiResponse> => {
+  app.delete('/api/sessions/:id', async (req) => {
    const { id } = req.params as { id: string };
    const query = req.query as { killMux?: string };
    const killMux = query.killMux !== 'false'; // Default to true
@@ -396,7 +435,7 @@ export function registerSessionRoutes(
    }

    await ctx.cleanupSession(id, killMux, 'user_delete');
-    return { success: true };
+    return {};
  });

  // ========== Delete All Sessions ==========
@@ -473,13 +512,13 @@ export function registerSessionRoutes(
      // Create a fresh tracker if one doesn't exist (shouldn't happen normally)
      const newTracker = new RunSummaryTracker(id, session.name);
      ctx.runSummaryTrackers.set(id, newTracker);
-      return { success: true, summary: newTracker.getSummary() };
+      return { summary: newTracker.getSummary() };
    }

    // Update session name in case it changed
    tracker.setSessionName(session.name);

-    return { success: true, summary: tracker.getSummary() };
+    return { summary: tracker.getSummary() };
  });

  // ========== Get Active Tools ==========
@@ -502,7 +541,7 @@ export function registerSessionRoutes(

  // ========== Run Prompt ==========

-  app.post('/api/sessions/:id/run', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/run', async (req) => {
    const { id } = req.params as { id: string };
    const { prompt } = parseBody(RunPromptSchema, req.body);
    const session = findSessionOrFail(ctx, id);
@@ -517,12 +556,12 @@ export function registerSessionRoutes(
    });

    ctx.broadcast(SseEvent.SessionRunning, { id, prompt });
-    return { success: true };
+    return {};
  });

  // ========== Start Interactive Mode ==========

-  app.post('/api/sessions/:id/interactive', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/interactive', async (req) => {
    const { id } = req.params as { id: string };
    const session = findSessionOrFail(ctx, id);

@@ -554,7 +593,7 @@ export function registerSessionRoutes(
      ctx.broadcast(SseEvent.SessionInteractive, { id });
      ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });

-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -562,7 +601,7 @@ export function registerSessionRoutes(

  // ========== Start Shell Mode ==========

-  app.post('/api/sessions/:id/shell', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/shell', async (req) => {
    const { id } = req.params as { id: string };
    const session = findSessionOrFail(ctx, id);

@@ -580,7 +619,7 @@ export function registerSessionRoutes(
      });
      ctx.broadcast(SseEvent.SessionInteractive, { id, mode: 'shell' });
      ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });
-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -592,7 +631,7 @@ export function registerSessionRoutes(

  // ========== Send Input ==========

-  app.post('/api/sessions/:id/input', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/input', async (req) => {
    const { id } = req.params as { id: string };
    const { input, useMux } = parseBody(SessionInputWithLimitSchema, req.body);
    const session = findSessionOrFail(ctx, id);
@@ -624,7 +663,7 @@ export function registerSessionRoutes(
    } else {
      session.write(inputStr);
    }
-    return { success: true };
+    return {};
  });

  // ========== Send Named Key (tmux send-keys -H) ==========
@@ -632,7 +671,7 @@ export function registerSessionRoutes(
  // Uses send-keys -H (hex) to inject 0x0a (line feed) which Claude Code's
  // Ink input recognizes as "insert newline" vs 0x0d (carriage return = submit).

-  app.post('/api/sessions/:id/send-key', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/send-key', async (req) => {
    const { id } = req.params as { id: string };
    const body = req.body as Record<string, unknown>;
    const key = typeof body?.key === 'string' ? body.key : '';
@@ -671,18 +710,22 @@ export function registerSessionRoutes(
      console.error('[Server] send-key failed:', err);
      return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'tmux send-keys failed');
    }
-    return { success: true };
+    return {};
  });

  // ========== Resize Terminal ==========

-  app.post('/api/sessions/:id/resize', async (req): Promise<ApiResponse> => {
+  app.post('/api/sessions/:id/resize', async (req) => {
    const { id } = req.params as { id: string };
-    const { cols, rows } = parseBody(ResizeSchema, req.body);
+    const { cols, rows, viewportType } = parseBody(ResizeSchema, req.body);
    const session = findSessionOrFail(ctx, id);

-    session.resize(cols, rows);
-    return { success: true };
+    if (viewportType) {
+      session.resize(cols, rows, { viewportType });
+    } else {
+      session.resize(cols, rows);
+    }
+    return {};
  });

  // ========== Get Last Response (from transcript JSONL) ==========
@@ -889,8 +932,26 @@ export function registerSessionRoutes(
    const query = req.query as { tail?: string };
    const session = findSessionOrFail(ctx, id);

+    // Prepend the live tmux pane buffer so tab-switch replay shows the current
+    // on-screen frame, not just the accumulated byte history. This matters for
+    // TUI modes (codex/opencode) that repaint only their latest frame: the
+    // accumulated buffer alone replays as the idle banner. We clear the viewport
+    // (`\x1b[H\x1b[2J`) between the history and the live pane so they don't
+    // overlap. `captureActivePaneBuffer` is a no-op ('') under test mode and
+    // returns null when unavailable, in which case we fall back to history.
+    const muxName = session.muxName;
+    const liveMuxBuffer =
+      muxName && typeof ctx.mux.captureActivePaneBuffer === 'function'
+        ? ctx.mux.captureActivePaneBuffer(muxName)
+        : null;
+    const rawBuffer =
+      liveMuxBuffer !== null && liveMuxBuffer.length > 0
+        ? session.terminalBufferLength > 0
+          ? `${session.terminalBuffer}\x1b[H\x1b[2J${liveMuxBuffer}`
+          : liveMuxBuffer
+        : session.terminalBuffer;
    const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
-    const fullSize = session.terminalBufferLength;
+    const fullSize = rawBuffer.length;
    let truncated = false;
    let cleanBuffer: string;

@@ -898,7 +959,17 @@ export function registerSessionRoutes(
    // During long thinking phases, Ink rewrites the same rows thousands of times
    // (500KB+). Without stripping, tail mode returns only spinner frames and
    // the terminal appears empty when switching tabs.
-    const strippedBuffer = stripInkRedrawBloat(session.terminalBuffer);
+    let strippedBuffer = stripInkRedrawBloat(rawBuffer);
+
+    // Strip alt-screen toggles and scrollback-erase from codex byte streams.
+    // xterm.js obeys them by switching to its scrollback-less alt buffer and
+    // wiping saved lines, so conversation history disappears on tab switch.
+    if (session.mode === 'codex') {
+      strippedBuffer = strippedBuffer
+        .replace(ALT_SCREEN_TOGGLE_PATTERN, '')
+        .replace(ERASE_SCROLLBACK_PATTERN, '')
+        .replace(MOUSE_TRACKING_PATTERN, '');
+    }

    if (tailBytes > 0 && strippedBuffer.length > tailBytes) {
      // Fast path: tail from the end, skip expensive banner search on full 2MB buffer.
@@ -985,6 +1056,27 @@ export function registerSessionRoutes(
    };
  });

+  // ========== Auto-Resume (usage-limit pause) ==========
+
+  app.post('/api/sessions/:id/auto-resume', async (req) => {
+    const { id } = req.params as { id: string };
+    const body = parseBody(AutoResumeSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
+
+    session.setAutoResume(body.enabled);
+    persistAndBroadcastSession(ctx, session);
+
+    return {
+      success: true,
+      data: {
+        autoResume: {
+          enabled: session.autoResumeEnabled,
+          resumeAt: session.autoResumeAt ?? undefined,
+        },
+      },
+    };
+  });
+
  // ========== Image Watcher ==========

  app.post('/api/sessions/:id/image-watcher', async (req) => {
@@ -1084,17 +1176,18 @@ export function registerSessionRoutes(
      const result = await session.runPrompt(prompt);
      // Clean up session after completion to prevent memory leak
      await ctx.cleanupSession(session.id, true, 'run_prompt_complete');
-      return { success: true, sessionId: session.id, ...result };
+      return { sessionId: session.id, ...result };
    } catch (err) {
-      // Clean up session on error too
+      // Clean up session on error too. The session is destroyed here, so its id
+      // is only useful for log correlation — carry it in the error message.
      await ctx.cleanupSession(session.id, true, 'run_prompt_error');
-      return { success: false, sessionId: session.id, error: getErrorMessage(err) };
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${getErrorMessage(err)} (session ${session.id})`);
    }
  });

  // ========== Quick Start ==========

-  app.post('/api/quick-start', async (req): Promise<QuickStartResponse> => {
+  app.post('/api/quick-start', async (req) => {
    // Prevent unbounded session creation
    if (ctx.sessions.size >= MAX_CONCURRENT_SESSIONS) {
      return createErrorResponse(
@@ -1107,6 +1200,7 @@ export function registerSessionRoutes(
      caseName = 'testcase',
      mode = 'claude',
      openCodeConfig,
+      codexConfig,
      envOverrides,
      effort,
    } = parseBody(QuickStartSchema, req.body);
@@ -1122,6 +1216,17 @@ export function registerSessionRoutes(
      }
    }

+    // Check Codex availability if requested
+    if (mode === 'codex') {
+      const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
+      if (!isCodexAvailable()) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          'Codex CLI not found. Install with: npm install -g @openai/codex'
+        );
+      }
+    }
+
    // Resolve case path: check linked-cases registry first, then fall back to CASES_DIR.
    // This mirrors the behaviour of resolveCasePath() in case-routes so that linked
    // external project directories are honoured by quick-start just like regular case routes.
@@ -1174,9 +1279,11 @@ export function registerSessionRoutes(
    const qsModel =
      mode === 'opencode'
        ? openCodeConfig?.model
-        : mode !== 'shell'
-          ? qsModelConfig?.defaultModel || undefined
-          : undefined;
+        : mode === 'codex'
+          ? codexConfig?.model
+          : mode !== 'shell'
+            ? qsModelConfig?.defaultModel || undefined
+            : undefined;
    const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
    const session = new Session({
      workingDir: casePath,
@@ -1188,6 +1295,7 @@ export function registerSessionRoutes(
      claudeMode: qsClaudeModeConfig.claudeMode,
      allowedTools: qsClaudeModeConfig.allowedTools,
      openCodeConfig: mode === 'opencode' ? openCodeConfig : undefined,
+      codexConfig: mode === 'codex' ? codexConfig : undefined,
      envOverrides,
      effort,
    });
@@ -1263,7 +1371,6 @@ export function registerSessionRoutes(
      }

      return {
-        success: true,
        sessionId: session.id,
        casePath,
        caseName,
@@ -1725,6 +1832,6 @@ export function registerSessionRoutes(
      await fh.close();
    }

-    return { success: true, path: filepath, filename };
+    return { path: filepath, filename };
  });
 }
@@ -14,6 +14,7 @@ import { execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { dataPath } from '../../config/instance.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
+import { isUnauthenticatedNetworkAcknowledged } from '../network-auth-policy.js';
 import {
  ConfigUpdateSchema,
  SettingsUpdateSchema,
@@ -238,7 +239,7 @@ export function registerSystemRoutes(

  app.post('/api/tunnel/qr/regenerate', async () => {
    ctx.tunnelManager.regenerateQrToken();
-    return { success: true };
+    return {};
  });

  // ========== Auth Session Revocation ==========
@@ -251,7 +252,7 @@ export function registerSystemRoutes(
      // Revoke all sessions (nuclear option)
      ctx.authSessions?.clear();
    }
-    return { success: true };
+    return {};
  });

  // ═══════════════════════════════════════════════════════════════
@@ -288,7 +289,7 @@ export function registerSystemRoutes(
      const child = spawn('bash', [scriptPath, url], { detached: true, stdio: 'ignore' });
      child.on('error', (err) => app.log.error({ err }, 'span-displays launch failed'));
      child.unref();
-      return { success: true, url };
+      return { url };
    } catch (err) {
      return reply.code(500).send(createErrorResponse(ApiErrorCode.INTERNAL_ERROR, getErrorMessage(err)));
    }
@@ -313,7 +314,7 @@ export function registerSystemRoutes(
  app.post('/api/system/update', async (_req, reply) => {
    const result = await startUpdate();
    if (result.ok) {
-      return { success: true, updateId: result.updateId, toTag: result.toTag, toVersion: result.toVersion };
+      return { updateId: result.updateId, toTag: result.toTag, toVersion: result.toVersion };
    }
    const map = {
      'in-flight': { http: 409, api: ApiErrorCode.ALREADY_EXISTS },
@@ -341,6 +342,14 @@ export function registerSystemRoutes(
    };
  });

+  app.get('/api/codex/status', async () => {
+    const { isCodexAvailable, resolveCodexDir } = await import('../../utils/codex-cli-resolver.js');
+    return {
+      available: isCodexAvailable(),
+      path: resolveCodexDir(),
+    };
+  });
+
  // ═══════════════════════════════════════════════════════════════
  // State & Lifecycle (cleanup, lifecycle log, stats)
  // ═══════════════════════════════════════════════════════════════
@@ -354,7 +363,7 @@ export function registerSystemRoutes(
    for (const s of result.cleaned) {
      lifecycleLog.log({ event: 'stale_cleaned', sessionId: s.id, name: s.name });
    }
-    return { success: true, cleanedSessions: result.count };
+    return { cleanedSessions: result.count };
  });

  app.get('/api/session-lifecycle', async (req) => {
@@ -371,7 +380,7 @@ export function registerSystemRoutes(
      since: query.since ? Number(query.since) : undefined,
      limit: query.limit ? Math.min(Number(query.limit), 1000) : 200,
    });
-    return { success: true, entries };
+    return { entries };
  });

  // ========== Stats ==========
@@ -391,7 +400,6 @@ export function registerSystemRoutes(
  app.get('/api/stats', async () => {
    const activeSessionTokens = collectActiveTokens();
    return {
-      success: true,
      stats: ctx.store.getAggregateStats(activeSessionTokens),
      raw: ctx.store.getGlobalStats(),
    };
@@ -400,7 +408,6 @@ export function registerSystemRoutes(
  app.get('/api/token-stats', async () => {
    const activeSessionTokens = collectActiveTokens();
    return {
-      success: true,
      daily: ctx.store.getDailyStats(30),
      totals: ctx.store.getAggregateStats(activeSessionTokens),
    };
@@ -413,13 +420,13 @@ export function registerSystemRoutes(
  // ========== Config ==========

  app.get('/api/config', async () => {
-    return { success: true, config: ctx.store.getConfig() };
+    return { config: ctx.store.getConfig() };
  });

  app.put('/api/config', async (req) => {
    const configData = parseBody(ConfigUpdateSchema, req.body, 'Invalid config');
    ctx.store.setConfig(configData as Partial<ReturnType<typeof ctx.store.getConfig>>);
-    return { success: true, config: ctx.store.getConfig() };
+    return { config: ctx.store.getConfig() };
  });

  // ========== Debug/Memory ==========
@@ -492,6 +499,26 @@ export function registerSystemRoutes(
  app.put('/api/settings', async (req) => {
    const settings = parseBody(SettingsUpdateSchema, req.body, 'Invalid settings') as Record<string, unknown>;

+    // COD-55: enabling the Cloudflare tunnel publishes the whole app (full terminal
+    // control = effectively RCE) to a public *.trycloudflare.com URL. Because the
+    // tunnel binds to loopback, server.ts's non-loopback bind guard never trips, and
+    // with no CODEMAN_PASSWORD the auth middleware is inactive — so the tunnel URL is
+    // unauthenticated. Refuse to start a tunnel unless auth is configured OR the
+    // operator has acknowledged unauthenticated-network exposure. A public tunnel is
+    // higher-stakes than a LAN bind, so this is REFUSE (vs the bind guard's warn).
+    // Guard runs BEFORE persisting so a refused tunnelEnabled:true is not saved.
+    if (settings.tunnelEnabled === true && !ctx.tunnelManager.isRunning() && !isUnauthenticatedNetworkAcknowledged()) {
+      const msg =
+        'Refusing to start the Cloudflare tunnel without authentication: it would publish ' +
+        'full terminal control to a public URL with no password. Set CODEMAN_PASSWORD to ' +
+        'require login, or set CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1 to acknowledge an ' +
+        'unauthenticated public tunnel.';
+      throw Object.assign(new Error(msg), {
+        statusCode: 403,
+        body: createErrorResponse(ApiErrorCode.OPERATION_FAILED, msg),
+      });
+    }
+
    try {
      const dir = dirname(SETTINGS_PATH);
      if (!existsSync(dir)) {
@@ -535,7 +562,7 @@ export function registerSystemRoutes(
        }
      }

-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -568,7 +595,7 @@ export function registerSystemRoutes(
      }
      await fs.writeFile(SETTINGS_PATH, JSON.stringify(existingSettings, null, 2));

-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -580,7 +607,6 @@ export function registerSystemRoutes(
    const { id } = req.params as { id: string };
    const session = findSessionOrFail(ctx, id);
    return {
-      success: true,
      nice: session.niceConfig,
    };
  });
@@ -596,7 +622,6 @@ export function registerSystemRoutes(
    ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });

    return {
-      success: true,
      nice: session.niceConfig,
      note: 'Nice priority only affects newly created mux sessions, not currently running ones.',
    };
@@ -620,7 +645,7 @@ export function registerSystemRoutes(
        mkdirSync(dir, { recursive: true });
      }
      await fs.writeFile(windowStatesPath, JSON.stringify(states, null, 2));
-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -640,7 +665,7 @@ export function registerSystemRoutes(
        mkdirSync(dir, { recursive: true });
      }
      await fs.writeFile(parentMapPath, JSON.stringify(parentMap, null, 2));
-      return { success: true };
+      return {};
    } catch (err) {
      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
    }
@@ -799,7 +824,7 @@ export function registerSystemRoutes(
    const filepath = join(SCREENSHOTS_DIR, filename);
    await fs.writeFile(filepath, filePart.data);

-    return { success: true, path: filepath, filename };
+    return { path: filepath, filename };
  });

  app.get('/api/screenshots', async () => {
@@ -109,6 +109,13 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
      socket.send(`{"t":"o","d":${JSON.stringify(DEC_2026_START + data + DEC_2026_END)}}`);
    };

+    // Per-connection desktop sizing claim — registered on the first
+    // desktop-typed resize and released on socket close, so Session.resize()
+    // can ignore small-viewport resizes only while a desktop is actually
+    // connected (see Session._desktopSizeClaims).
+    const sizingToken = Symbol('ws-desktop-sizing');
+    let holdsDesktopClaim = false;
+
    // Attach message handler synchronously BEFORE any async work
    // (@fastify/websocket requirement to avoid dropped messages).
    socket.on('message', (raw) => {
@@ -116,6 +123,9 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
        const msg = JSON.parse(String(raw));
        if (msg.t === 'i' && typeof msg.d === 'string') {
          if (msg.d.length > MAX_INPUT_LENGTH) return;
+          // Typed input from a claim-holding desktop keeps the claim "hot"
+          // and re-asserts the desktop layout after a mobile override.
+          if (holdsDesktopClaim) session.noteDesktopActivity();
          session.write(msg.d);
        } else if (
          msg.t === 'z' &&
@@ -126,7 +136,21 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
          msg.r >= 1 &&
          msg.r <= 200
        ) {
-          session.resize(msg.c, msg.r);
+          const viewportType = msg.v === 'mobile' || msg.v === 'tablet' || msg.v === 'desktop' ? msg.v : undefined;
+          if (viewportType === 'desktop') {
+            session.claimDesktopSizing(sizingToken);
+            holdsDesktopClaim = true;
+          } else if (viewportType) {
+            // The connection's viewport can change (e.g. browser window
+            // narrowed past the tablet breakpoint) — drop a stale claim.
+            session.releaseDesktopSizing(sizingToken);
+            holdsDesktopClaim = false;
+          }
+          if (viewportType) {
+            session.resize(msg.c, msg.r, { viewportType });
+          } else {
+            session.resize(msg.c, msg.r);
+          }
        }
      } catch {
        // Ignore malformed messages
@@ -205,6 +229,7 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
      session.off('clearTerminal', onClearTerminal);
      session.off('needsRefresh', onNeedsRefresh);
      session.off('exit', onSessionExit);
+      session.releaseDesktopSizing(sizingToken);

      // Decrement per-session connection count
      const count = sessionWsCount.get(id) ?? 1;
@@ -8,7 +8,7 @@
 */

 import { z } from 'zod';
-import { SAFE_PATH_PATTERN } from '../utils/index.js';
+import { SAFE_PATH_PATTERN, isSafePushEndpoint } from '../utils/index.js';

 // ========== Path Validation ==========

@@ -46,7 +46,7 @@ const safePathSchema = z.string().max(1000).refine(isValidWorkingDir, {
 // ========== Env Var Allowlist ==========

 /** Allowlisted env var key prefixes */
-const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_'];
+const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_'];

 /** Env var keys that are always blocked (security-sensitive) */
 const BLOCKED_ENV_KEYS = new Set([
@@ -76,7 +76,7 @@ const safeEnvOverridesSchema = z
    },
    {
      message:
-        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_* and OPENCODE_* keys are allowed.',
+        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, and CODEX_* keys are allowed.',
    }
  );

@@ -128,9 +128,30 @@ const OpenCodeConfigSchema = z
  })
  .optional();

+/** Schema for Codex (OpenAI CLI)-specific configuration */
+const CodexConfigSchema = z
+  .object({
+    model: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._\-/]+$/)
+      .optional(),
+    resumeSessionId: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9_-]+$/)
+      .optional(),
+    dangerouslyBypassApprovals: z.boolean().optional(),
+    renderMode: z
+      .enum(['scrollback', 'hybrid'])
+      .optional()
+      .transform(() => 'hybrid' as const),
+  })
+  .optional();
+
 export const CreateSessionSchema = z.object({
  workingDir: safePathSchema.optional(),
-  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex']).optional(),
  name: z.string().max(100).optional(),
  envOverrides: safeEnvOverridesSchema,
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
@@ -138,6 +159,7 @@ export const CreateSessionSchema = z.object({
  /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
  modelOverride: z.string().max(50).optional(),
  openCodeConfig: OpenCodeConfigSchema,
+  codexConfig: CodexConfigSchema,
  /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
  resumeSessionId: z
    .string()
@@ -161,6 +183,7 @@ export const RunPromptSchema = z.object({
 export const ResizeSchema = z.object({
  cols: z.number().int().min(1).max(500),
  rows: z.number().int().min(1).max(200),
+  viewportType: z.enum(['mobile', 'tablet', 'desktop']).optional(),
 });

 // ========== Case Routes ==========
@@ -187,8 +210,9 @@ export const QuickStartSchema = z.object({
    .string()
    .regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.')
    .optional(),
-  mode: z.enum(['claude', 'shell', 'opencode']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex']).optional(),
  openCodeConfig: OpenCodeConfigSchema,
+  codexConfig: CodexConfigSchema,
  envOverrides: safeEnvOverridesSchema,
  /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
  effort: effortLevelSchema,
@@ -281,6 +305,8 @@ export const SettingsUpdateSchema = z
    tunnelEnabled: z.boolean().optional(),
    tabTwoRows: z.boolean().optional(),
    agentTeamsEnabled: z.boolean().optional(),
+    /** Model for new Claude sessions (e.g. "claude-fable-5[1m]", "opus[1m]"); takes precedence over opusContext1mEnabled */
+    claudeModel: z.string().max(50).optional(),
    opusContext1mEnabled: z.boolean().optional(),
    thinkingEffort: z.string().max(20).optional(),
    // UI visibility
@@ -289,6 +315,7 @@ export const SettingsUpdateSchema = z
    showTokenCount: z.boolean().optional(),
    showCost: z.boolean().optional(),
    showLifecycleLog: z.boolean().optional(),
+    showResponseViewer: z.boolean().optional(),
    showMonitor: z.boolean().optional(),
    showProjectInsights: z.boolean().optional(),
    showFileBrowser: z.boolean().optional(),
@@ -299,6 +326,8 @@ export const SettingsUpdateSchema = z
    // Claude CLI settings
    claudeMode: z.string().max(50).optional(),
    allowedTools: z.string().max(2000).optional(),
+    // Codex CLI settings
+    codexDangerouslyBypassApprovals: z.boolean().optional(),
    // CPU priority
    nice: z
      .object({
@@ -421,6 +450,11 @@ export const AutoCompactSchema = z.object({
  prompt: z.string().max(10000).optional(),
 });

+/** POST /api/sessions/:id/auto-resume */
+export const AutoResumeSchema = z.object({
+  enabled: z.boolean(),
+});
+
 /** POST /api/sessions/:id/image-watcher */
 export const ImageWatcherSchema = z.object({
  enabled: z.boolean(),
@@ -531,7 +565,11 @@ export const RespawnEnableSchema = z.object({

 /** POST /api/push/subscribe */
 export const PushSubscribeSchema = z.object({
-  endpoint: z.string().url().max(2000),
+  endpoint: z
+    .string()
+    .url()
+    .max(2000)
+    .refine(isSafePushEndpoint, { message: 'endpoint must be an https URL to a public (non-internal) host' }),
  keys: z.object({
    p256dh: z.string().min(1).max(500),
    auth: z.string().min(1).max(500),
@@ -161,7 +161,9 @@ export function parseGitHubRepo(remoteUrl: string): { owner: string; repo: strin
 * persist — or null to leave it untouched.
 *
 * Rules (see plan "Hardening"):
- * - Terminal phases → untouched.
+ * - Terminal phases → untouched, EXCEPT `completed-needs-manual-restart`: once we
+ *   boot into the staged target version the manual restart evidently happened, so
+ *   it flips to `completed` (otherwise the stale instruction lingers in the UI).
 * - Only the `restarting` marker (written right before the updater triggers our
 *   restart) flips to completed/failed by comparing running version vs. target.
 * - Other in-flight phases are owned by the still-running updater scope — leave
@@ -174,6 +176,17 @@ export function reconcileStatusDecision(
  now: number
 ): UpdateStatus | null {
  if (!status) return null;
+
+  // A staged update that asked for a manual restart: if we're now running the
+  // target version, the user (or supervisor) did restart — mark it completed so
+  // the UI stops showing the stale "restart Codeman to apply" instruction.
+  if (status.phase === 'completed-needs-manual-restart') {
+    if (status.toVersion && runningVersion === status.toVersion) {
+      return { ...status, phase: 'completed', message: `Updated to v${runningVersion}`, updatedAt: now };
+    }
+    return null;
+  }
+
  if (!IN_FLIGHT_PHASES.has(status.phase)) return null;

  if (status.phase === 'restarting') {
@@ -275,6 +288,16 @@ function detectInstallKind(dir: string): InstallKind {
 export function detectSupervisor(): SupervisorKind {
  if (process.platform === 'darwin') {
    if (existsSync(join(homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`))) return 'launchd';
+    // Headless Macs (no GUI login → no gui domain) run Codeman as a system-level
+    // LaunchDaemon instead. Restarting one needs no root IF it has KeepAlive: the
+    // updater just kills the server and launchd respawns it on the new build. Only
+    // claim this supervisor when the daemon is actually bootstrapped and KeepAlive.
+    const daemonPlist = join('/Library/LaunchDaemons', `${LAUNCHD_LABEL}.plist`);
+    if (existsSync(daemonPlist)) {
+      const loaded = tryExec('launchctl', ['print', `system/${LAUNCHD_LABEL}`]) !== null;
+      const keepAlive = tryExec('plutil', ['-extract', 'KeepAlive', 'raw', '-o', '-', daemonPlist]);
+      if (loaded && keepAlive === 'true') return 'launchd-daemon';
+    }
    return 'none';
  }
  if (process.platform === 'linux') {
@@ -535,6 +558,10 @@ export async function startUpdate(): Promise<StartUpdateResult> {
    process.execPath,
    '--log',
    logFile,
+    // For the launchd-daemon restart path: the updater kills this PID and the
+    // KeepAlive daemon respawns the server on the freshly built dist/.
+    '--server-pid',
+    String(process.pid),
  ];
  if (prevSha) args.push('--prev-sha', prevSha);
  if (info.dirty) args.push('--stash');
@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Shared sensitive-path blocklist.
+ *
+ * A small defense-in-depth blocklist of absolute paths that must never be
+ * served to the browser regardless of how the path was obtained (workspace
+ * download, cross-workspace attachment registration, raw/preview serving).
+ *
+ * This is intentionally a BLOCKLIST, not a workspace-confinement check:
+ * cross-workspace attachment is a supported feature (codeman-publish skill +
+ * the automated review-card loop attaching files under ~/.codeman/), so a
+ * strict session-workspace boundary would break legitimate use. The blocklist
+ * rejects well-known secret locations (system password files, SSH keys, cloud
+ * credentials, dotenv files) while leaving ordinary cross-workspace files
+ * attachable.
+ *
+ * Callers MUST resolve symlinks (realpath) BEFORE calling isSensitivePath so a
+ * symlink pointing at a sensitive target is also caught.
+ */
+
+import { homedir } from 'node:os';
+
+const SENSITIVE_PATTERNS: RegExp[] = [
+  /^\/etc\/shadow$/,
+  /^\/etc\/gshadow$/,
+  /^\/etc\/master\.passwd$/,
+  new RegExp(`^${homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\.ssh\\/`),
+  /\/\.env$/,
+  /\/\.env\./,
+  /\/credentials(\.json|\.yml|\.yaml|\.xml)?$/i,
+  /\/\.aws\/credentials$/,
+  /\/\.gcloud\/credentials\.db$/,
+  /\/\.docker\/config\.json$/,
+];
+
+/**
+ * Returns true if the given ABSOLUTE, symlink-resolved path matches the
+ * sensitive-file blocklist and must not be served to the browser.
+ */
+export function isSensitivePath(absPath: string): boolean {
+  return SENSITIVE_PATTERNS.some((pattern) => pattern.test(absPath));
+}
@@ -41,8 +41,9 @@ import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
 import { hostname as getHostname } from 'node:os';
 import { dataPath } from '../config/instance.js';
+import { getHookSecret } from '../config/hook-secret.js';
 import { EventEmitter } from 'node:events';
-import { Session, type BackgroundTask } from '../session.js';
+import { Session, isExternalCliMode, type BackgroundTask } from '../session.js';
 import type { ClaudeMode, SessionState } from '../types.js';
 import { RespawnController, RespawnConfig } from '../respawn-controller.js';
 import type { TerminalMultiplexer } from '../mux-interface.js';
@@ -59,6 +60,7 @@ import {
  type SubagentToolResult,
 } from '../subagent-watcher.js';
 import { imageWatcher } from '../image-watcher.js';
+import { attachmentRegistry, registerExternalAttachment } from '../attachment-registry.js';
 import { TranscriptWatcher } from '../transcript-watcher.js';
 import { TeamWatcher } from '../team-watcher.js';
 import { TunnelManager } from '../tunnel-manager.js';
@@ -90,14 +92,35 @@ import { reconcileUpdateOnBoot } from './self-update.js';
 // Load version from package.json
 const require = createRequire(import.meta.url);
 const { version: APP_VERSION } = require('../../package.json');
+
+/**
+ * `/api/v1/*` is the versioned public alias of the (unversioned) `/api/*` routes.
+ * Rewriting at the server level lets external clients pin to a stable surface while
+ * the bundled frontend keeps using `/api/*`. See docs/api-reference.md.
+ */
+function rewriteApiV1Url(url: string): string {
+  if (url === '/api/v1') return '/api';
+  if (url.startsWith('/api/v1/')) return '/api/' + url.slice('/api/v1/'.length);
+  return url;
+}
 import {
  getErrorMessage,
+  httpStatusForErrorCode,
+  createErrorResponse,
+  ApiErrorCode,
  type PersistedRespawnConfig,
  type NiceConfig,
  type ImageDetectedEvent,
+  type AttachmentDetectedEvent,
  DEFAULT_NICE_CONFIG,
 } from '../types.js';
-import { CleanupManager, KeyedDebouncer, StaleExpirationMap, startEventLoopMonitor } from '../utils/index.js';
+import {
+  CleanupManager,
+  KeyedDebouncer,
+  StaleExpirationMap,
+  startEventLoopMonitor,
+  isSafePushEndpoint,
+} from '../utils/index.js';
 import type { EventLoopMonitorHandle } from '../utils/index.js';
 import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.js';
 import { SseEvent } from './sse-events.js';
@@ -227,12 +250,14 @@ export class WebServer extends EventEmitter {
  } | null = null;
  private imageWatcherHandlers: {
    detected: (event: ImageDetectedEvent) => void;
+    attachmentDetected: (event: AttachmentDetectedEvent) => void;
    error: (error: Error, sessionId?: string) => void;
  } | null = null;
  private tunnelManager: TunnelManager = new TunnelManager();
  private authSessions: StaleExpirationMap<string, import('./ports/auth-port.js').AuthSessionRecord> | null = null;
  private authFailures: StaleExpirationMap<string, number> | null = null;
  private qrAuthFailures: StaleExpirationMap<string, number> | null = null;
+  private hookSecretFailures: StaleExpirationMap<string, number> | null = null;
  private pushStore: PushSubscriptionStore = new PushSubscriptionStore();
  private teamWatcher: TeamWatcher = new TeamWatcher();
  private _orchestratorLoop: import('../orchestrator-loop.js').OrchestratorLoop | null = null;
@@ -268,11 +293,12 @@ export class WebServer extends EventEmitter {
    this.windowTitle = `codeman:${this.titleHostname}`;
    this.indexHtmlTemplate = readFileSync(join(__dirname, 'public', 'index.html'), 'utf-8');

+    const rewriteUrl = (req: { url?: string }): string => rewriteApiV1Url(req.url || '');
    if (https) {
      const { key, cert } = getOrCreateSelfSignedCert();
-      this.app = Fastify({ logger: false, https: { key, cert } });
+      this.app = Fastify({ logger: false, https: { key, cert }, rewriteUrl });
    } else {
-      this.app = Fastify({ logger: false });
+      this.app = Fastify({ logger: false, rewriteUrl });
    }
    this.mux = createMultiplexer();
    this.sse = new SseStreamManager(
@@ -413,12 +439,15 @@ export class WebServer extends EventEmitter {
    // Store handlers for cleanup on shutdown
    this.imageWatcherHandlers = {
      detected: (event: ImageDetectedEvent) => this.broadcast(SseEvent.ImageDetected, event),
+      attachmentDetected: (event: AttachmentDetectedEvent) =>
+        this.broadcast(SseEvent.AttachmentDetected, { ...event, source: event.source || 'detected' }),
      error: (error: Error, sessionId?: string) => {
        console.error(`[ImageWatcher] Error${sessionId ? ` for ${sessionId}` : ''}:`, error.message);
      },
    };

    imageWatcher.on('image:detected', this.imageWatcherHandlers.detected);
+    imageWatcher.on('attachment:detected', this.imageWatcherHandlers.attachmentDetected);
    imageWatcher.on('image:error', this.imageWatcherHandlers.error);
  }

@@ -428,6 +457,7 @@ export class WebServer extends EventEmitter {
  private cleanupImageWatcherListeners(): void {
    if (this.imageWatcherHandlers) {
      imageWatcher.off('image:detected', this.imageWatcherHandlers.detected);
+      imageWatcher.off('attachment:detected', this.imageWatcherHandlers.attachmentDetected);
      imageWatcher.off('image:error', this.imageWatcherHandlers.error);
      this.imageWatcherHandlers = null;
    }
@@ -555,17 +585,39 @@ export class WebServer extends EventEmitter {
    // Cookie plugin (needed for auth session tokens)
    await this.app.register(fastifyCookie);

+    // Uniform response envelope (stable HTTP contract — docs/api-reference.md):
+    // wrap bare JSON payloads as { success:true, data } and map { success:false }
+    // error envelopes to a conventional HTTP status (instead of 200). Skips
+    // non-JSON responses (buffers/streams) and non-/api routes.
+    this.app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
+      if (!req.url.startsWith('/api')) return done(null, payload);
+      if (payload === null || typeof payload !== 'object') return done(null, payload);
+      if (Buffer.isBuffer(payload) || typeof (payload as { pipe?: unknown }).pipe === 'function') {
+        return done(null, payload);
+      }
+      const p = payload as { success?: unknown; errorCode?: unknown };
+      if (p.success === false) {
+        if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
+          reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
+        }
+        return done(null, payload);
+      }
+      if (p.success === true) return done(null, payload);
+      return done(null, { success: true, data: payload });
+    });
+
    // Anti-DNS-rebinding Host allowlist + cross-site (CSRF) Origin guard. Registered
    // before auth so forged cross-site / rebound requests are rejected up front, even
    // on the default no-password install. See docs/reports/security-review-2026-06-09.md.
    registerHostGuard(this.app, () => this.getHostPolicy());

    // Auth middleware (Basic Auth + session cookies + rate limiting)
-    const authState = registerAuthMiddleware(this.app, this.https);
+    const authState = registerAuthMiddleware(this.app, this.https, () => this.tunnelManager.isRunning());
    if (authState) {
      this.authSessions = authState.authSessions;
      this.authFailures = authState.authFailures;
      this.qrAuthFailures = authState.qrAuthFailures;
+      this.hookSecretFailures = authState.hookSecretFailures;
    }

    // WebSocket support (terminal I/O — low-latency bidirectional channel)
@@ -697,7 +749,7 @@ export class WebServer extends EventEmitter {
    this.app.post('/api/events/subscribe', (req, reply) => {
      const body = (req.body || {}) as { clientId?: string; sessions?: string[] | null };
      if (typeof body.clientId !== 'string' || !SSE_CLIENT_ID_RE.test(body.clientId)) {
-        reply.code(400).send({ error: 'clientId required' });
+        reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'clientId required'));
        return;
      }
      const sessions = Array.isArray(body.sessions)
@@ -711,6 +763,18 @@ export class WebServer extends EventEmitter {
    // parseBody. Shared with the route test harness so test behavior matches prod.
    installRouteErrorHandler(this.app);

+    // Stable-contract 404 for unknown /api routes — without this, Fastify's
+    // default not-found payload {message,error,statusCode} would be wrapped by
+    // the envelope hook into a contradictory HTTP 404 {success:true,...}.
+    this.app.setNotFoundHandler((req, reply) => {
+      const notFound = `Route ${req.method}:${req.url} not found`;
+      if (req.url.startsWith('/api')) {
+        reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, notFound));
+        return;
+      }
+      reply.code(404).send({ message: notFound, error: 'Not Found', statusCode: 404 });
+    });
+
    // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them.
    // text/plain is used ONLY by this beacon (navigator.sendBeacon sends text/plain).
    // Keep the body as a RAW STRING and parse it inside the handler — a global
@@ -1010,6 +1074,8 @@ export class WebServer extends EventEmitter {
      session.removeAllListeners();
      // Close any active file streams for this session
      fileStreamManager.closeSessionStreams(sessionId);
+      // Drop live external attachment registrations for this session
+      attachmentRegistry.clearSession(sessionId);
      // Stop watching for images in this session's directory
      imageWatcher.unwatchSession(sessionId);
      // Clean up pasted images directory for this session
@@ -1135,8 +1201,8 @@ export class WebServer extends EventEmitter {
    this.runSummaryTrackers.set(session.id, summaryTracker);
    summaryTracker.recordSessionStarted(session.mode, session.workingDir);

-    // Set working directory for Ralph tracker to auto-load @fix_plan.md (not supported for opencode sessions)
-    if (session.mode !== 'opencode') {
+    // Set working directory for Ralph tracker to auto-load @fix_plan.md (not supported for external CLIs)
+    if (!isExternalCliMode(session.mode)) {
      session.ralphTracker.setWorkingDir(session.workingDir);
    }

@@ -1195,9 +1261,32 @@ export class WebServer extends EventEmitter {
        }
      },
      getStore: () => this.store,
+      registerAttachment: (id: string, filePath: string) => this.registerAttachment(id, filePath),
    };
  }

+  /**
+   * Register a terminal-requested external file as a live attachment and
+   * broadcast it. Triggered by the session's `attachmentRequested` event
+   * (codeman://attach magic links). Because terminal output is
+   * attacker-influenceable (a prompt-injected session can print an arbitrary
+   * `codeman://attach?path=` link), the scanned path is FORCE-confined to the
+   * session workspace — passive magic links can't expose arbitrary host files.
+   * Deliberate cross-workspace attachment goes through the explicit,
+   * Origin-guarded `POST /attachments` route (and `codeman attach`, which POSTs
+   * directly inside a managed session). Registration also enforces the COD-53
+   * blocklist as defense-in-depth.
+   */
+  private async registerAttachment(sessionId: string, filePath: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    const event = await registerExternalAttachment(sessionId, filePath, {
+      sessionWorkingDir: session.workingDir,
+      forceWorkspaceConfinement: true,
+    });
+    this.broadcast(SseEvent.AttachmentDetected, event);
+  }
+
  private setupRespawnListeners(sessionId: string, controller: RespawnController): void {
    wireRespawnListeners(sessionId, controller, this.buildRespawnWiringDeps());
  }
@@ -1639,6 +1728,14 @@ export class WebServer extends EventEmitter {
      // Check per-subscription preferences
      if (sub.pushPreferences[event] === false) continue;

+      // Re-validate the stored endpoint before fetching it server-side (SSRF, M7).
+      // Defense-in-depth: subscribe-time validation already rejects unsafe URLs.
+      if (!isSafePushEndpoint(sub.endpoint)) {
+        console.warn('[push] skipping notification to unsafe endpoint:', sub.endpoint);
+        this.pushStore.removeByEndpoint(sub.endpoint);
+        continue;
+      }
+
      const pushSub = {
        endpoint: sub.endpoint,
        keys: sub.keys,
@@ -1754,6 +1851,10 @@ export class WebServer extends EventEmitter {
      this.host === '0.0.0.0' || this.host === 'localhost' || this.host === '::1' ? '127.0.0.1' : this.host;
    process.env.CODEMAN_API_URL = `${protocol}://${apiHost}:${this.port}`;

+    // Ensure the COD-54 hook secret exists on disk before any session exports
+    // $CODEMAN_HOOK_SECRET_FILE — hook curls cat that path at execution time.
+    getHookSecret();
+
    // Start scheduled runs cleanup timer
    this.cleanup.setInterval(
      () => {
@@ -1931,6 +2032,12 @@ export class WebServer extends EventEmitter {
              if (savedState.autoClearEnabled !== undefined || savedState.autoClearThreshold !== undefined) {
                session.setAutoClear(savedState.autoClearEnabled ?? false, savedState.autoClearThreshold);
              }
+              // Auto-resume on usage limit (re-arms a pending schedule; an
+              // overdue one fires shortly after boot — the limit footer won't
+              // reprint on its own, so the pause would otherwise stall)
+              if (savedState.autoResumeEnabled) {
+                session.restoreAutoResume(true, savedState.autoResumeAt);
+              }
              // Token tracking
              if (
                savedState.inputTokens !== undefined ||
@@ -1954,8 +2061,8 @@ export class WebServer extends EventEmitter {
                  );
                }
              }
-              // Ralph / Todo tracker (not supported for opencode sessions)
-              if (session.mode !== 'opencode') {
+              // Ralph / Todo tracker (not supported for external-CLI sessions)
+              if (!isExternalCliMode(session.mode)) {
                if (savedState.ralphAutoEnableDisabled) {
                  session.ralphTracker.disableAutoEnable();
                  console.log(`[Server] Restored Ralph auto-enable disabled for session ${session.id}`);
@@ -1984,8 +2091,8 @@ export class WebServer extends EventEmitter {
              if (savedState.flickerFilterEnabled !== undefined) {
                session.flickerFilterEnabled = savedState.flickerFilterEnabled;
              }
-              // Respawn controller (not supported for opencode sessions)
-              if (session.mode !== 'opencode' && savedState.respawnEnabled && savedState.respawnConfig) {
+              // Respawn controller (not supported for external-CLI sessions)
+              if (!isExternalCliMode(session.mode) && savedState.respawnEnabled && savedState.respawnConfig) {
                try {
                  this.restoreRespawnController(session, savedState.respawnConfig, 'state.json');
                } catch (err) {
@@ -1994,9 +2101,9 @@ export class WebServer extends EventEmitter {
              }
            }

-            // Fallback: restore respawn from mux-sessions.json if state.json didn't have it (not supported for opencode)
+            // Fallback: restore respawn from mux-sessions.json if state.json didn't have it (not supported for external CLIs)
            if (
-              session.mode !== 'opencode' &&
+              !isExternalCliMode(session.mode) &&
              !this.respawnControllers.has(session.id) &&
              muxSession.respawnConfig?.enabled
            ) {
@@ -2011,9 +2118,9 @@ export class WebServer extends EventEmitter {
            }

            // Fallback: restore Ralph state from state-inner.json if not already set and not explicitly disabled
-            // Ralph tracker is not supported for opencode sessions
+            // Ralph tracker is not supported for external-CLI sessions
            if (
-              session.mode !== 'opencode' &&
+              !isExternalCliMode(session.mode) &&
              !session.ralphTracker.enabled &&
              !session.ralphTracker.autoEnableDisabled
            ) {
@@ -2024,9 +2131,9 @@ export class WebServer extends EventEmitter {
              }
            }

-            // Fallback: auto-detect completion phrase from CLAUDE.md (not supported for opencode)
+            // Fallback: auto-detect completion phrase from CLAUDE.md (not supported for external CLIs)
            if (
-              session.mode !== 'opencode' &&
+              !isExternalCliMode(session.mode) &&
              session.ralphTracker.enabled &&
              !session.ralphTracker.loopState.completionPhrase
            ) {
@@ -2230,6 +2337,10 @@ export class WebServer extends EventEmitter {
      this.qrAuthFailures.dispose();
      this.qrAuthFailures = null;
    }
+    if (this.hookSecretFailures) {
+      this.hookSecretFailures.dispose();
+      this.hookSecretFailures = null;
+    }
    this.activePlanOrchestrators.clear();
    this.cleaningUp.clear();

@@ -45,6 +45,9 @@ export interface SessionListenerRefs {
  taskFailed: (task: BackgroundTask, error: string) => void;
  autoClear: (data: { tokens: number; threshold: number }) => void;
  autoCompact: (data: { tokens: number; threshold: number; prompt?: string }) => void;
+  limitPauseScheduled: (data: { resetAt: number; resumeAt: number; matched: string }) => void;
+  limitResume: (data: { attempt: number }) => void;
+  limitResumeCancelled: (data: { reason: string }) => void;
  cliInfoUpdated: (data: { version?: string; model?: string; accountType?: string; latestVersion?: string }) => void;
  ralphLoopUpdate: (state: RalphTrackerState) => void;
  ralphTodoUpdate: (todos: RalphTodoItem[]) => void;
@@ -55,6 +58,7 @@ export interface SessionListenerRefs {
  bashToolStart: (tool: ActiveBashTool) => void;
  bashToolEnd: (tool: ActiveBashTool) => void;
  bashToolsUpdate: (tools: ActiveBashTool[]) => void;
+  attachmentRequested: (event: { path: string }) => void;
 }

 /** Dependencies injected by WebServer — keeps listener creation decoupled from server internals. */
@@ -74,10 +78,11 @@ interface SessionListenerDeps {
  removeSessionListenerRefs(sessionId: string): void;
  cleanupRespawnOnExit(sessionId: string): void;
  getStore(): import('../state-store.js').StateStore;
+  registerAttachment(sessionId: string, filePath: string): Promise<void>;
 }

 /**
- * Creates all 25 session listener handlers, capturing dependencies via closure.
+ * Creates all 26 session listener handlers, capturing dependencies via closure.
 * Call `attachSessionListeners()` after to wire them to the session.
 */
 export function createSessionListeners(session: Session, deps: SessionListenerDeps): SessionListenerRefs {
@@ -243,6 +248,28 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
      if (tracker) tracker.recordAutoCompact(data.tokens, data.threshold);
    },

+    /** Broadcasts `session:limitPauseScheduled` — usage-limit pause detected, auto-resume armed.
+     *  Persisted so a pending schedule survives a Codeman restart. */
+    limitPauseScheduled: (data: { resetAt: number; resumeAt: number; matched: string }) => {
+      deps.broadcast(SseEvent.SessionLimitPauseScheduled, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+      deps.persistSessionState(session);
+    },
+
+    /** Broadcasts `session:limitResume` — auto-resume prompt sent after limit reset */
+    limitResume: (data: { attempt: number }) => {
+      deps.broadcast(SseEvent.SessionLimitResume, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+      deps.persistSessionState(session);
+    },
+
+    /** Broadcasts `session:limitResumeCancelled` — pending auto-resume no longer needed */
+    limitResumeCancelled: (data: { reason: string }) => {
+      deps.broadcast(SseEvent.SessionLimitResumeCancelled, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+      deps.persistSessionState(session);
+    },
+
    // ─── CLI Info ────────────────────────────────────────────

    /** Broadcasts `session:cliInfo` — Claude Code version, model, account type parsed from terminal */
@@ -330,6 +357,13 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
    bashToolsUpdate: (tools: ActiveBashTool[]) => {
      deps.broadcast(SseEvent.SessionBashToolsUpdate, { sessionId: session.id, tools });
    },
+
+    /** Registers an explicit attachment card requested by terminal magic text. */
+    attachmentRequested: (event: { path: string }) => {
+      deps.registerAttachment(session.id, event.path).catch((err) => {
+        console.error(`[Attachment] Failed to register ${event.path} for ${session.id}:`, err);
+      });
+    },
  };
 }

@@ -350,6 +384,9 @@ export function attachSessionListeners(session: Session, refs: SessionListenerRe
  session.on('taskFailed', refs.taskFailed);
  session.on('autoClear', refs.autoClear);
  session.on('autoCompact', refs.autoCompact);
+  session.on('limitPauseScheduled', refs.limitPauseScheduled);
+  session.on('limitResume', refs.limitResume);
+  session.on('limitResumeCancelled', refs.limitResumeCancelled);
  session.on('cliInfoUpdated', refs.cliInfoUpdated);
  session.on('ralphLoopUpdate', refs.ralphLoopUpdate);
  session.on('ralphTodoUpdate', refs.ralphTodoUpdate);
@@ -360,6 +397,7 @@ export function attachSessionListeners(session: Session, refs: SessionListenerRe
  session.on('bashToolStart', refs.bashToolStart);
  session.on('bashToolEnd', refs.bashToolEnd);
  session.on('bashToolsUpdate', refs.bashToolsUpdate);
+  session.on('attachmentRequested', refs.attachmentRequested);
 }

 /** Detach all listeners from a session (prevents memory leaks from closure references). */
@@ -379,6 +417,9 @@ export function detachSessionListeners(session: Session, refs: SessionListenerRe
  session.off('taskFailed', refs.taskFailed);
  session.off('autoClear', refs.autoClear);
  session.off('autoCompact', refs.autoCompact);
+  session.off('limitPauseScheduled', refs.limitPauseScheduled);
+  session.off('limitResume', refs.limitResume);
+  session.off('limitResumeCancelled', refs.limitResumeCancelled);
  session.off('cliInfoUpdated', refs.cliInfoUpdated);
  session.off('ralphLoopUpdate', refs.ralphLoopUpdate);
  session.off('ralphTodoUpdate', refs.ralphTodoUpdate);
@@ -389,4 +430,5 @@ export function detachSessionListeners(session: Session, refs: SessionListenerRe
  session.off('bashToolStart', refs.bashToolStart);
  session.off('bashToolEnd', refs.bashToolEnd);
  session.off('bashToolsUpdate', refs.bashToolsUpdate);
+  session.off('attachmentRequested', refs.attachmentRequested);
 }
@@ -73,6 +73,12 @@ export const SessionWorking = 'session:working' as const;
 export const SessionAutoClear = 'session:autoClear' as const;
 /** Auto-compact triggered for the session. */
 export const SessionAutoCompact = 'session:autoCompact' as const;
+/** Usage-limit pause detected; auto-resume scheduled. */
+export const SessionLimitPauseScheduled = 'session:limitPauseScheduled' as const;
+/** Auto-resume prompt sent after a usage-limit reset. */
+export const SessionLimitResume = 'session:limitResume' as const;
+/** Pending usage-limit auto-resume cancelled (session resumed or feature disabled). */
+export const SessionLimitResumeCancelled = 'session:limitResumeCancelled' as const;
 /** CLI version/model info detected from session output. */
 export const SessionCliInfo = 'session:cliInfo' as const;
 /** General session message (e.g. status text). */
@@ -278,6 +284,8 @@ export const TunnelQrAuthUsed = 'tunnel:qrAuthUsed' as const;

 /** New image file detected (e.g. screenshot upload). */
 export const ImageDetected = 'image:detected' as const;
+/** New document/image attachment detected in a session working directory. */
+export const AttachmentDetected = 'attachment:detected' as const;

 // ─── Hooks ───────────────────────────────────────────────────────────────────

@@ -361,6 +369,9 @@ export const SseEvent = {
  SessionWorking,
  SessionAutoClear,
  SessionAutoCompact,
+  SessionLimitPauseScheduled,
+  SessionLimitResume,
+  SessionLimitResumeCancelled,
  SessionCliInfo,
  SessionMessage,
  SessionInteractive,
@@ -470,6 +481,7 @@ export const SseEvent = {

  // Image
  ImageDetected,
+  AttachmentDetected,

  // Hooks
  HookIdlePrompt,
@@ -5,11 +5,7 @@
 */

 import { describe, it, expect } from 'vitest';
-import {
-  ApiErrorCode,
-  createErrorResponse,
-  createSuccessResponse,
-} from '../src/types.js';
+import { ApiErrorCode, createErrorResponse } from '../src/types.js';

 describe('API Response Structures', () => {
  describe('SessionState Structure', () => {
@@ -480,34 +476,9 @@ describe('API Response Structures', () => {
  });

  describe('Response Validation', () => {
-    describe('SessionResponse', () => {
-      it('should have success property', () => {
-        const response = createSuccessResponse({ id: 'session-1' });
-        expect(response).toHaveProperty('success');
-        expect(response.success).toBe(true);
-      });
-
-      it('should have data property on success', () => {
-        const response = createSuccessResponse({ id: 'session-1', status: 'idle' });
-        expect(response).toHaveProperty('data');
-        expect(response.data?.id).toBe('session-1');
-      });
-    });
-
-    describe('QuickStartResponse', () => {
-      it('should include session and case info on success', () => {
-        const response = createSuccessResponse({
-          sessionId: 'session-1',
-          casePath: '/path/to/case',
-          caseName: 'test-case',
-        });
-
-        expect(response.success).toBe(true);
-        expect(response.data?.sessionId).toBeDefined();
-        expect(response.data?.casePath).toBeDefined();
-        expect(response.data?.caseName).toBeDefined();
-      });
-    });
+    // (SessionResponse / QuickStartResponse success-envelope tests removed — the
+    // createSuccessResponse helper they exercised no longer exists. Error-envelope
+    // coverage remains below.)

    describe('Error Responses', () => {
      it('should include error code', () => {
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { Session } from '../src/session.js';
+import { parseAttachmentMagicLinks } from '../src/attachment-magic.js';
+
+describe('attachment magic links', () => {
+  it('extracts absolute paths from codeman attach magic URLs', () => {
+    const links = parseAttachmentMagicLinks(
+      'Preview this: codeman://attach?path=%2Fmnt%2Fc%2FDecks%2FBoard%20Update.pptx'
+    );
+
+    expect(links).toEqual(['/mnt/c/Decks/Board Update.pptx']);
+  });
+
+  it('ignores duplicate links in one terminal chunk', () => {
+    const links = parseAttachmentMagicLinks(
+      [
+        'codeman://attach?path=/tmp/report.pdf',
+        'codeman://attach?path=/tmp/report.pdf',
+        'codeman://attach?path=/tmp/brief.docx',
+      ].join('\n')
+    );
+
+    expect(links).toEqual(['/tmp/report.pdf', '/tmp/brief.docx']);
+  });
+
+  it('accepts markdown and plain-text magic paths', () => {
+    const links = parseAttachmentMagicLinks(
+      ['codeman://attach?path=/tmp/notes.md', 'codeman://attach?path=/tmp/run.txt'].join('\n')
+    );
+
+    expect(links).toEqual(['/tmp/notes.md', '/tmp/run.txt']);
+  });
+
+  it('rejects relative or unsupported magic paths', () => {
+    const links = parseAttachmentMagicLinks(
+      [
+        'codeman://attach?path=relative.pdf',
+        'codeman://attach?path=/tmp/archive.zip',
+        'codeman://attach?path=/tmp/deck.pptx',
+      ].join('\n')
+    );
+
+    expect(links).toEqual(['/tmp/deck.pptx']);
+  });
+
+  it('emits attachmentRequested from raw terminal output', () => {
+    const session = new Session({ id: 'session-attach-test', workingDir: '/tmp', mode: 'codex' });
+    const requested: string[] = [];
+    session.on('attachmentRequested', (event: { path: string }) => requested.push(event.path));
+
+    (session as unknown as { _handleTerminalOutput(data: string): void })._handleTerminalOutput(
+      'codeman://attach?path=%2Ftmp%2Fdeck.pptx'
+    );
+
+    expect(requested).toEqual(['/tmp/deck.pptx']);
+  });
+});
@@ -0,0 +1,186 @@
+/**
+ * @fileoverview COD-54 — hook-event auth bypass hardening.
+ *
+ * The `/api/hook-event` localhost bypass let tunnel traffic (cloudflared
+ * --url http://127.0.0.1:port) reach the loopback origin with req.ip ===
+ * 127.0.0.1 and drive respawn/Ralph signals unauthenticated. The fix gates
+ * the bypass behind a shared hook secret WHEN A TUNNEL IS RUNNING, while
+ * keeping the plain localhost bypass for the normal loopback-only case so
+ * already-deployed (pre-secret) hooks and the loop's own channel keep working.
+ *
+ * Tests:
+ *  - tunnel running + no secret  → 401 (closes the hole)
+ *  - tunnel running + bad secret → 401
+ *  - tunnel running + good secret → not 401 (allowed)
+ *  - tunnel NOT running + no secret → not 401 (back-compat regression guard)
+ *  - rate limiting: rapid unauthorized hook POSTs eventually 429
+ *
+ * Port: 3230 (tunnel-running), 3231 (tunnel-down), 3232 (rate-limit)
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { WebServer } from '../src/web/server.js';
+import { TmuxManager } from '../src/tmux-manager.js';
+import { TunnelManager } from '../src/tunnel-manager.js';
+import { getHookSecret, HOOK_SECRET_HEADER } from '../src/config/hook-secret.js';
+import { AUTH_FAILURE_MAX } from '../src/config/auth-config.js';
+
+const TUNNEL_UP_PORT = 3230;
+const TUNNEL_DOWN_PORT = 3231;
+const RATE_LIMIT_PORT = 3232;
+const TEST_USER = 'admin';
+const TEST_PASS = 'cod54-test-password';
+
+vi.spyOn(TmuxManager, 'isTmuxAvailable').mockReturnValue(true);
+
+function hookBody(): string {
+  return JSON.stringify({ event: 'stop', sessionId: 'nonexistent-session', data: {} });
+}
+
+async function postHook(baseUrl: string, headers: Record<string, string> = {}): Promise<Response> {
+  return fetch(`${baseUrl}/api/hook-event`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: hookBody(),
+  });
+}
+
+describe('COD-54 hook-event auth — tunnel running requires secret', () => {
+  let server: WebServer;
+  let baseUrl: string;
+  let isRunningSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeAll(async () => {
+    process.env.CODEMAN_PASSWORD = TEST_PASS;
+    process.env.CODEMAN_USERNAME = TEST_USER;
+    // Force the middleware's tunnel check to report "running".
+    isRunningSpy = vi.spyOn(TunnelManager.prototype, 'isRunning').mockReturnValue(true);
+    server = new WebServer(TUNNEL_UP_PORT, false, true);
+    await server.start();
+    baseUrl = `http://localhost:${TUNNEL_UP_PORT}`;
+  });
+
+  afterAll(async () => {
+    await server.stop();
+    isRunningSpy.mockRestore();
+    delete process.env.CODEMAN_PASSWORD;
+    delete process.env.CODEMAN_USERNAME;
+  });
+
+  it('rejects a localhost hook POST WITHOUT the secret header (closes the tunnel hole)', async () => {
+    const res = await postHook(baseUrl);
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects a localhost hook POST with a WRONG secret', async () => {
+    const res = await postHook(baseUrl, { [HOOK_SECRET_HEADER]: 'wrong-secret-value' });
+    expect(res.status).toBe(401);
+  });
+
+  it('allows a localhost hook POST WITH the correct secret', async () => {
+    const res = await postHook(baseUrl, { [HOOK_SECRET_HEADER]: getHookSecret() });
+    // Passes auth (may 200 with success:false for unknown session) — key is NOT 401.
+    expect(res.status).not.toBe(401);
+  });
+});
+
+describe('COD-54 hook-event auth — tunnel down keeps localhost bypass (back-compat)', () => {
+  let server: WebServer;
+  let baseUrl: string;
+  let isRunningSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeAll(async () => {
+    process.env.CODEMAN_PASSWORD = TEST_PASS;
+    process.env.CODEMAN_USERNAME = TEST_USER;
+    // Tunnel NOT running — loopback-only normal prod case.
+    isRunningSpy = vi.spyOn(TunnelManager.prototype, 'isRunning').mockReturnValue(false);
+    server = new WebServer(TUNNEL_DOWN_PORT, false, true);
+    await server.start();
+    baseUrl = `http://localhost:${TUNNEL_DOWN_PORT}`;
+  });
+
+  afterAll(async () => {
+    await server.stop();
+    isRunningSpy.mockRestore();
+    delete process.env.CODEMAN_PASSWORD;
+    delete process.env.CODEMAN_USERNAME;
+  });
+
+  it('still allows a localhost hook POST WITHOUT a secret (existing hooks + loop channel keep working)', async () => {
+    const res = await postHook(baseUrl);
+    expect(res.status).not.toBe(401);
+  });
+});
+
+describe('COD-54 hook-event auth — rate limiting', () => {
+  let server: WebServer;
+  let baseUrl: string;
+  let isRunningSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeAll(async () => {
+    process.env.CODEMAN_PASSWORD = TEST_PASS;
+    process.env.CODEMAN_USERNAME = TEST_USER;
+    // Tunnel running so unauthorized (no-secret) hook POSTs are rejected and counted.
+    isRunningSpy = vi.spyOn(TunnelManager.prototype, 'isRunning').mockReturnValue(true);
+    server = new WebServer(RATE_LIMIT_PORT, false, true);
+    await server.start();
+    baseUrl = `http://localhost:${RATE_LIMIT_PORT}`;
+  });
+
+  afterAll(async () => {
+    await server.stop();
+    isRunningSpy.mockRestore();
+    delete process.env.CODEMAN_PASSWORD;
+    delete process.env.CODEMAN_USERNAME;
+  });
+
+  it('eventually returns 429 for rapid unauthorized hook POSTs', async () => {
+    let saw429 = false;
+    // A few more than the failure max to cross the threshold.
+    for (let i = 0; i < AUTH_FAILURE_MAX + 3; i++) {
+      const res = await postHook(baseUrl);
+      if (res.status === 429) {
+        saw429 = true;
+        expect(res.headers.get('retry-after')).toMatch(/^\d+$/);
+        break;
+      }
+      expect(res.status).toBe(401);
+    }
+    expect(saw429).toBe(true);
+  });
+
+  it('hook-secret failures do NOT lock out the Basic-Auth login path (separate bucket)', async () => {
+    // The previous test exhausted the hook bucket for 127.0.0.1. Legacy (pre-secret)
+    // hooks fire constantly, so if they shared authFailures, every cookie-less
+    // request from loopback would now 429 — locking out login (and, via a tunnel,
+    // every client). Assert the login path is unaffected:
+    // 1. A credential-less request still gets a 401 challenge, NOT 429.
+    const unauthed = await fetch(`${baseUrl}/api/status`);
+    expect(unauthed.status).toBe(401);
+    // 2. Correct Basic credentials still authenticate.
+    const authed = await fetch(`${baseUrl}/api/status`, {
+      headers: { Authorization: 'Basic ' + Buffer.from(`${TEST_USER}:${TEST_PASS}`).toString('base64') },
+    });
+    expect(authed.status).toBe(200);
+  });
+});
+
+describe('COD-54 secret delivery — generated hooks + session env present the secret', () => {
+  it('generated hook curl commands send the secret header, read from the file at exec time', async () => {
+    const { generateHooksConfig } = await import('../src/hooks-config.js');
+    const config = generateHooksConfig();
+    const commands = JSON.stringify(config);
+    // Header present, value sourced from $CODEMAN_HOOK_SECRET_FILE (not embedded).
+    expect(commands).toContain(HOOK_SECRET_HEADER);
+    expect(commands).toContain('$CODEMAN_HOOK_SECRET_FILE');
+    expect(commands).not.toContain(getHookSecret());
+  });
+
+  it('session env builders export CODEMAN_HOOK_SECRET_FILE (path only, never the value)', async () => {
+    const { buildClaudeEnv, buildShellEnv } = await import('../src/session-cli-builder.js');
+    const claudeEnv = buildClaudeEnv('test-session');
+    const shellEnv = buildShellEnv('test-session');
+    expect(claudeEnv.CODEMAN_HOOK_SECRET_FILE).toMatch(/hook-secret$/);
+    expect(shellEnv.CODEMAN_HOOK_SECRET_FILE).toMatch(/hook-secret$/);
+    expect(JSON.stringify(claudeEnv)).not.toContain(getHookSecret());
+  });
+});
@@ -0,0 +1,94 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+// Structural tests for the xterm snapshot/replay slice (COD-81). app.js has no
+// bundler and is hard to drive through a real DOM, so — following the repo's
+// existing pattern for app.js — these assert the source structure that makes
+// the snapshot first-paint correct rather than executing it.
+describe('xterm snapshot/replay (codex tab-switch)', () => {
+  const appSource = () => readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+
+  it('rejects blank xterm snapshots before saving or restoring them', () => {
+    const source = appSource();
+    const helper = source.indexOf('_isUsableXtermSnapshot(snapshot)');
+    const save = source.indexOf('this._xtermSnapshots.set(this.activeSessionId, snapshot)');
+    const restore = source.indexOf('SNAPSHOT_RESTORE:', save);
+    const restoreBlock = source.slice(save, restore);
+
+    expect(helper).toBeGreaterThan(-1);
+    // The save is gated on a usability check immediately above it.
+    const usabilityGate = source.lastIndexOf('if (this._isUsableXtermSnapshot(snapshot))', save);
+    expect(usabilityGate).toBeGreaterThan(-1);
+    expect(usabilityGate).toBeLessThan(save);
+    // …and so is each restore path (in-memory + persisted).
+    expect(restoreBlock).toContain('if (snapshot && !this._isUsableXtermSnapshot(snapshot))');
+    expect(restoreBlock).toContain('persisted && this._isUsableXtermSnapshot(persisted)');
+  });
+
+  it('declares the snapshot-restore flag before selectSession uses it', () => {
+    const source = appSource();
+    const selectStart = source.indexOf('async selectSession(sessionId, options = {})');
+    const declaration = source.indexOf('let restoredSnapshot = false;', selectStart);
+    const snapshotBranch = source.indexOf("if (snapshot && !sessionIsBusy && session?.mode !== 'shell')", selectStart);
+    const rewriteDecision = source.indexOf(
+      'restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer',
+      selectStart
+    );
+
+    expect(selectStart).toBeGreaterThan(-1);
+    expect(declaration).toBeGreaterThan(selectStart);
+    expect(declaration).toBeLessThan(snapshotBranch);
+    expect(declaration).toBeLessThan(rewriteDecision);
+  });
+
+  it('uses xterm snapshots as first paint but still fetches the canonical terminal frame', () => {
+    const source = appSource();
+    const snapshotRestore = source.indexOf('SNAPSHOT_RESTORE:');
+    const cacheRestore = source.indexOf('Instant cache restore', snapshotRestore);
+    const fetchStart = source.indexOf("FETCH_START'", snapshotRestore);
+    const needsRewrite = source.indexOf('const needsRewrite', fetchStart);
+    const snapshotBlock = source.slice(snapshotRestore, cacheRestore);
+    const postSnapshotRestore = source.slice(snapshotRestore, needsRewrite + 160);
+
+    expect(snapshotRestore).toBeGreaterThan(-1);
+    expect(cacheRestore).toBeGreaterThan(snapshotRestore);
+    expect(fetchStart).toBeGreaterThan(cacheRestore);
+    expect(needsRewrite).toBeGreaterThan(fetchStart);
+    // Snapshot restore must NOT short-circuit the canonical fetch.
+    expect(snapshotBlock).not.toContain('this._finishBufferLoad();');
+    expect(postSnapshotRestore).toContain('restoredSnapshot');
+    expect(postSnapshotRestore).toContain('restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer');
+  });
+
+  it('forces replay after clearing a busy tab even when the fetched frame matches cache', () => {
+    const source = appSource();
+    const cacheRestore = source.indexOf('Instant cache restore');
+    const busyClear = source.indexOf('CACHE_SKIP_BUSY', cacheRestore);
+    const needsRewrite = source.indexOf('const needsRewrite', busyClear);
+    const replayBlock = source.slice(cacheRestore, needsRewrite + 160);
+
+    expect(cacheRestore).toBeGreaterThan(-1);
+    expect(busyClear).toBeGreaterThan(cacheRestore);
+    expect(needsRewrite).toBeGreaterThan(busyClear);
+    expect(replayBlock).toContain('clearedForBusy');
+    expect(replayBlock).toContain('restoredSnapshot || clearedForBusy || data.terminalBuffer !== cachedBuffer');
+  });
+
+  it('loads the SerializeAddon and keeps a per-session snapshot map', () => {
+    const terminalSource = readFileSync(resolve(import.meta.dirname, '../src/web/public/terminal-ui.js'), 'utf8');
+    expect(terminalSource).toContain('this._xtermSnapshots = new Map()');
+    expect(terminalSource).toContain('new SerializeAddon.SerializeAddon()');
+    expect(terminalSource).toContain('this.terminal.loadAddon(this._serializeAddon)');
+  });
+
+  it('evicts the in-memory snapshot cache and persists with a bounded localStorage budget', () => {
+    const source = appSource();
+    // In-memory cache is LRU-bounded…
+    expect(source).toContain('if (this._xtermSnapshots.size > 20)');
+    // …per-snapshot localStorage writes are size-capped…
+    expect(source).toContain('snapshot.length < 256 * 1024');
+    // …and the persisted key set is pruned of dead sessions.
+    expect(source).toContain("k.startsWith('codeman-xs-')");
+  });
+});
@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest';
+import { Session } from '../src/session.js';
+
+type SessionInternals = {
+  _handleTerminalOutput(data: string): void;
+  _ptyRows: number;
+};
+
+function handleOutput(session: Session, data: string): void {
+  (session as unknown as SessionInternals)._handleTerminalOutput(data);
+}
+
+describe('Codex terminal output filtering', () => {
+  it('keeps browser scrollback guards but skips Codeman row repair in hybrid render mode', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex', codexConfig: { renderMode: 'hybrid' } });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+    const hybridRedraw = '\x1b[?1049h\x1b[55;1H\x1b[2m• Working (21s)\x1b[3J\x1b[?1006h\x1b[?1049l';
+
+    handleOutput(session, hybridRedraw);
+
+    expect(emitted[0]).toBe('\x1b[55;1H\x1b[2m• Working (21s)');
+    expect(emitted[0]).not.toContain('\x1b[55;1H\x1b[2K');
+    expect(session.terminalBuffer).toBe(emitted[0]);
+  });
+
+  it('preserves Codex erase-display redraws used by the TUI layout engine', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+
+    handleOutput(session, '\x1b[H\x1b[Jidle redraw');
+
+    expect(session.terminalBuffer).toBe('\x1b[H\x1b[Jidle redraw');
+  });
+
+  it('strips Codex scrollback erase without stripping visible-screen erase', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+
+    handleOutput(session, '\x1b[?1049h\x1b[2Jvisible\x1b[3Jscrollback\x1b[?1049l');
+
+    expect(session.terminalBuffer).toBe('\x1b[2Jvisiblescrollback');
+  });
+
+  it('strips sequences split across PTY chunk boundaries (carry reassembly)', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    // '\x1b[?1049h' split mid-sequence, then '\x1b[3J' split before its final byte.
+    handleOutput(session, 'before\x1b[?104');
+    handleOutput(session, '9h\x1b[2Jafter\x1b[3');
+    handleOutput(session, 'Jtail');
+
+    expect(session.terminalBuffer).toBe('before\x1b[2Jaftertail');
+    expect(emitted).toEqual(['before', '\x1b[2Jafter', 'tail']);
+  });
+
+  it('emits nothing for a chunk that is only a partial CSI, and completes it next chunk', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(session, '\x1b[?100'); // pure partial — held, nothing emitted
+    handleOutput(session, '6h\x1b[55;1H• Working'); // completes ?1006h (stripped); rest passes
+
+    expect(emitted).toEqual(['\x1b[55;1H• Working']);
+    expect(session.terminalBuffer).toBe('\x1b[55;1H• Working');
+  });
+
+  it('preserves Codex erase-display redraw when the user pressed Ctrl+L', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+
+    session.write('\x0c');
+    handleOutput(session, '\x1b[H\x1b[Jredraw after clear');
+
+    expect(session.terminalBuffer).toBe('\x1b[H\x1b[Jredraw after clear');
+  });
+
+  it('passes native Codex TUI prompt/status redraws through without row repair', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const bottomBandRedraw =
+      '\x1b[48;2;42;42;42m' +
+      '\x1b[60;2H\x1b[K' +
+      '\x1b[61;39H\x1b[K' +
+      '\x1b[62;2H\x1b[K' +
+      '\x1b[52;1H\x1b[49m\x1b[2m• \x1b[1mRunning node -e ...' +
+      '\x1b[60;1H\x1b[48;2;42;42;42m \r\n' +
+      '\x1b[1m›\x1b[0m\x1b[48;2;42;42;42m \x1b[2mUse /skills to list available skills\r\n' +
+      '\x1b[63;3H\x1b[49m\x1b[38;2;246;226;183mgpt-5.5 xhigh\x1b[39m' +
+      '\x1b[2m · \x1b[38;2;242;181;144mContext 42% left\x1b[39m' +
+      '\x1b[61;3H';
+
+    handleOutput(session, bottomBandRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[52;1H\x1b[2K');
+    expect(emitted[0]).not.toContain('\x1b[60;1H\x1b[2K');
+    expect(emitted[0]).not.toContain('\x1b[63;1H\x1b[2K');
+    expect(emitted[0]).toContain(bottomBandRedraw);
+  });
+
+  it('passes Codex advisory rows through without row repair', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const advisoryRedraw =
+      '\x1b[55;1H\x1b[2mMessages\x1b[Cto\x1b[Cbe submitted\x1b[Cafter\x1b[Cnext toolcall ' +
+      '(press esc to interrupt and send immediately)\x1b[56;1H';
+
+    handleOutput(session, advisoryRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[55;1H\x1b[2K');
+    expect(emitted[0]).toContain(advisoryRedraw);
+  });
+
+  it('does not clear Codex resume-picker rows just because an option is selected', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const resumePickerRedraw =
+      '\x1b[1;2H\x1b[36m\x1b[1mResume a previous session' +
+      '\x1b[3;2H\x1b[2mType to search      Filter: \x1b[35m[Cwd]\x1b[39m\x1b[2m All' +
+      '\x1b[5;3H\x1b[33m\x1b[48;2;42;42;42m\x1b[1m❯ \x1b[2m22h ago     ll' +
+      '\x1b[6;3H\x1b[2m  1d ago      $kb-health' +
+      '\x1b[60;1H\x1b[2m──── 2 / 2 · 100% ─' +
+      '\x1b[61;1H enter resume   esc exit   ↑/↓ browse';
+
+    handleOutput(session, resumePickerRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[4;1H\x1b[2K');
+    expect(emitted[0]).not.toContain('\x1b[5;1H\x1b[2K');
+    expect(emitted[0]).toContain(resumePickerRedraw);
+  });
+
+  it('does not full-clear sparse Codex resume-picker navigation redraws', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    let sparseResumePickerRedraw = '';
+    for (let row = 1; row <= 51; row++) {
+      const col = row % 2 === 0 ? 239 : 27;
+      sparseResumePickerRedraw += `\x1b[${row};${col}H\x1b[K`;
+    }
+    sparseResumePickerRedraw +=
+      '\x1b[21;3H  \x1b[2m9d ago      \x1b[mreview this webex room webexteams://im?space=672465b0-4fcb-11f1-9d54-51475df86e3a\x1b[K' +
+      '\x1b[22;3H\x1b[33m\x1b[1m❯ \x1b[m\x1b[33m\x1b[2m9d ago      \x1b[m\x1b[33mcisco hybrid mesh firewall includes support for smart switch enforcement...\x1b[K' +
+      '\x1b[52;229H\x1b[39m\x1b[2m8\x1b[m';
+
+    handleOutput(session, sparseResumePickerRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[H\x1b[2J');
+    expect(emitted[0]).toContain(sparseResumePickerRedraw);
+  });
+
+  it('passes Codex UI rows through when the status band moves downward', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(
+      session,
+      '\x1b[55;1H\x1b[2m• Working (1s)\x1b[56;1H\x1b[1m›\x1b[0m ask\x1b[57;3Hgpt-5.5 · Context 80% left'
+    );
+    handleOutput(
+      session,
+      '\x1b[58;1H\x1b[2m• Working (2s)\x1b[59;1H\x1b[1m›\x1b[0m ask\x1b[60;3Hgpt-5.5 · Context 79% left'
+    );
+
+    expect(emitted[1]).not.toContain('\x1b[55;1H\x1b[2K');
+    expect(emitted[1]).not.toContain('\x1b[56;1H\x1b[2K');
+    expect(emitted[1]).not.toContain('\x1b[57;1H\x1b[2K');
+    expect(emitted[1]).toContain('\x1b[58;1H');
+    expect(emitted[1]).not.toContain('\x1b[54;1H\x1b[2K');
+  });
+
+  it('does not full-clear the viewport for stable Codex UI rows at the same position', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const stableRedraw =
+      '\x1b[58;1H\x1b[2m• Working (2s)\x1b[59;1H\x1b[1m›\x1b[0m ask\x1b[60;3Hgpt-5.5 · Context 79% left';
+
+    handleOutput(session, stableRedraw);
+    handleOutput(session, stableRedraw.replace('2s', '3s'));
+
+    expect(emitted[1]).not.toContain('\x1b[H\x1b[2J');
+  });
+
+  it('passes status-only Codex Working redraw rows through', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const workingRedraw = '\x1b[55;1H\x1b[2m• Working (21s)';
+
+    handleOutput(session, workingRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[55;1H\x1b[2K');
+    expect(emitted[0]).toContain(workingRedraw);
+    expect(emitted[0]).not.toContain('\x1b[H\x1b[2J');
+  });
+
+  it('passes Codex spinner Working rows that omit elapsed time parentheses through', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 29;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const spinnerRedraw = '\x1b[24;1H\x1b[38;5;254m\x1b[1m•\x1b[CWorking\x1b[27;3H';
+
+    handleOutput(session, spinnerRedraw);
+
+    expect(emitted[0]).not.toContain('\x1b[24;1H\x1b[2K');
+    expect(emitted[0]).toContain(spinnerRedraw);
+    expect(emitted[0]).not.toContain('\x1b[H\x1b[2J');
+  });
+
+  it('does not treat ordinary gpt model mentions as Codex status rows', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    const outputRow = '\x1b[20;1Hnormal output comparing gpt-5 and another model';
+
+    handleOutput(session, outputRow);
+
+    expect(emitted[0]).toContain(outputRow);
+    expect(emitted[0]).not.toContain('\x1b[19;1H\x1b[2K');
+    expect(emitted[0]).not.toContain('\x1b[20;1H\x1b[2K');
+  });
+
+  it('does not inject row erases during partial Working spinner ticks', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'codex' });
+    (session as unknown as SessionInternals)._ptyRows = 63;
+
+    const emitted: string[] = [];
+    session.on('terminal', (data) => emitted.push(data));
+
+    handleOutput(
+      session,
+      '\x1b[55;1H\x1b[2m• Working (1s)' +
+        '\x1b[56;1H\x1b[1m›\x1b[0m ask' +
+        '\x1b[57;3Hgpt-5.5 xhigh fast · codeman · Working · Context 79% left'
+    );
+    handleOutput(session, '\x1b[55;1H\x1b[2m• Working (2s)');
+
+    expect(emitted[1]).not.toContain('\x1b[55;1H\x1b[2K');
+    expect(emitted[1]).not.toContain('\x1b[56;1H\x1b[2K');
+    expect(emitted[1]).not.toContain('\x1b[57;1H\x1b[2K');
+    expect(emitted[1]).toContain('\x1b[55;1H\x1b[2m• Working (2s)');
+  });
+});
@@ -41,14 +41,14 @@ describe('Edge Cases and Error Handling', () => {
      const data = await response.json();

      expect(data.success).toBe(false);
-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle getting non-existent session gracefully', async () => {
      const response = await fetch(`${baseUrl}/api/sessions/non-existent-id-12345`);
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle running prompt on non-existent session', async () => {
@@ -59,7 +59,7 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle input to non-existent session', async () => {
@@ -70,7 +70,7 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle resize on non-existent session', async () => {
@@ -81,7 +81,7 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle interactive mode on non-existent session', async () => {
@@ -90,21 +90,21 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle terminal buffer request on non-existent session', async () => {
      const response = await fetch(`${baseUrl}/api/sessions/non-existent/terminal`);
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle output request on non-existent session', async () => {
      const response = await fetch(`${baseUrl}/api/sessions/non-existent/output`);
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });
  });

@@ -190,7 +190,7 @@ describe('Edge Cases and Error Handling', () => {

      // Should succeed with valid characters, even if long
      if (data.success) {
-        createdCases.push(longName);
+        createdCases.push(data.data.caseName);
      }
      // Either succeeds or fails gracefully
      expect(data).toHaveProperty('success');
@@ -202,8 +202,8 @@ describe('Edge Cases and Error Handling', () => {
      const response = await fetch(`${baseUrl}/api/sessions/non-existent/respawn`);
      const data = await response.json();

-      expect(data.enabled).toBe(false);
-      expect(data.status).toBeNull();
+      expect(data.data.enabled).toBe(false);
+      expect(data.data.status).toBeNull();
    });

    it('should handle starting respawn on non-existent session', async () => {
@@ -212,7 +212,7 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });

    it('should handle stopping non-existent respawn controller', async () => {
@@ -232,7 +232,7 @@ describe('Edge Cases and Error Handling', () => {
      });
      const data = await response.json();

-      expect(data.error).toBe('Session not found');
+      expect(data.error).toContain('not found');
    });
  });

@@ -272,30 +272,32 @@ describe('Concurrent Session Handling', () => {

  it('should handle multiple sessions simultaneously', async () => {
    // Create multiple sessions concurrently
-    const createPromises = Array(5).fill(null).map(() =>
-      fetch(`${baseUrl}/api/sessions`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ workingDir: '/tmp' }),
-      }).then(r => r.json())
-    );
+    const createPromises = Array(5)
+      .fill(null)
+      .map(() =>
+        fetch(`${baseUrl}/api/sessions`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ workingDir: '/tmp' }),
+        }).then((r) => r.json())
+      );

    const results = await Promise.all(createPromises);

    // All should succeed
    for (const result of results) {
      expect(result.success).toBe(true);
-      expect(result.session.id).toBeDefined();
+      expect(result.data.session.id).toBeDefined();
    }

    // Verify sessions are listed
    const listRes = await fetch(`${baseUrl}/api/sessions`);
    const sessions = await listRes.json();
-    expect(sessions.length).toBeGreaterThanOrEqual(5);
+    expect(sessions.data.length).toBeGreaterThanOrEqual(5);

    // Clean up - delete all created sessions
    for (const result of results) {
-      await fetch(`${baseUrl}/api/sessions/${result.session.id}`, {
+      await fetch(`${baseUrl}/api/sessions/${result.data.session.id}`, {
        method: 'DELETE',
      });
    }
@@ -315,7 +317,7 @@ describe('Concurrent Session Handling', () => {
      expect(createData.success).toBe(true);

      // Delete immediately
-      const deleteRes = await fetch(`${baseUrl}/api/sessions/${createData.session.id}`, {
+      const deleteRes = await fetch(`${baseUrl}/api/sessions/${createData.data.session.id}`, {
        method: 'DELETE',
      });
      const deleteData = await deleteRes.json();
@@ -327,20 +329,20 @@ describe('Concurrent Session Handling', () => {
    const caseNames = ['concurrent-test-1', 'concurrent-test-2', 'concurrent-test-3'];
    const createdCases: string[] = [];

-    const quickStartPromises = caseNames.map(name =>
+    const quickStartPromises = caseNames.map((name) =>
      fetch(`${baseUrl}/api/quick-start`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ caseName: `${name}-${Date.now()}` }),
-      }).then(r => r.json())
+      }).then((r) => r.json())
    );

    const results = await Promise.all(quickStartPromises);

    for (const result of results) {
      expect(result.success).toBe(true);
-      if (result.caseName) {
-        createdCases.push(result.caseName);
+      if (result.data.caseName) {
+        createdCases.push(result.data.caseName);
      }
    }

@@ -147,7 +147,7 @@ describe('File Link Click Tests', () => {

    const data = await response.json();
    expect(data.success).toBe(true);
-    createdSessions.push(data.session.id);
+    createdSessions.push(data.data.sessionId);

    // Wait for session to appear in UI
    await new Promise((r) => setTimeout(r, 2000));
@@ -347,7 +347,7 @@ describe('File Link Click Tests', () => {
      });
      const data = await response.json();
      expect(data.success).toBe(true);
-      sessionId = data.sessionId; // quick-start returns sessionId directly
+      sessionId = data.data.sessionId; // quick-start returns sessionId under data envelope
      createdSessions.push(sessionId);
    }

@@ -24,6 +24,10 @@ vi.mock('node:fs', async (importOriginal) => {
    ...orig,
    existsSync: vi.fn(() => true),
    statSync: vi.fn(() => ({ size: 1024 })),
+    // createStream re-resolves symlinks via realpathSync right before spawn (TOCTOU
+    // guard); the test fixtures are non-existent paths, so the real realpathSync would
+    // throw. Mock it as identity so the re-check passes.
+    realpathSync: vi.fn((p: string) => p),
  };
 });

@@ -92,11 +96,9 @@ describe('FileStreamManager', () => {
        onError: vi.fn(),
      });

-      expect(mockSpawn).toHaveBeenCalledWith(
-        'tail',
-        ['-f', '-n', '50', expect.stringContaining('/var/log/app.log')],
-        { stdio: ['ignore', 'pipe', 'pipe'] },
-      );
+      expect(mockSpawn).toHaveBeenCalledWith('tail', ['-f', '-n', '50', expect.stringContaining('/var/log/app.log')], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
    });

    it('should use custom lines parameter', async () => {
@@ -113,11 +115,7 @@ describe('FileStreamManager', () => {
        onError: vi.fn(),
      });

-      expect(mockSpawn).toHaveBeenCalledWith(
-        'tail',
-        ['-f', '-n', '100', expect.any(String)],
-        expect.any(Object),
-      );
+      expect(mockSpawn).toHaveBeenCalledWith('tail', ['-f', '-n', '100', expect.any(String)], expect.any(Object));
    });

    it('should reject when file does not exist', async () => {
@@ -448,7 +446,7 @@ describe('FileStreamManager', () => {
      expect(result.success).toBe(true);
    });

-    it('should allow paths in /tmp', async () => {
+    it('should reject paths in /tmp (world-writable, intentionally excluded)', async () => {
      const proc = createMockProcess();
      mockSpawn.mockReturnValue(proc);

@@ -461,7 +459,7 @@ describe('FileStreamManager', () => {
        onError: vi.fn(),
      });

-      expect(result.success).toBe(true);
+      expect(result.success).toBe(false);
    });

    it('should handle stat errors gracefully', async () => {
@@ -32,21 +32,21 @@ describe('generateHooksConfig', () => {
  it('should configure idle_prompt matcher', () => {
    const config = generateHooksConfig();
    const notifHooks = config.hooks.Notification as Array<{ matcher?: string }>;
-    const idleHook = notifHooks.find(h => h.matcher === 'idle_prompt');
+    const idleHook = notifHooks.find((h) => h.matcher === 'idle_prompt');
    expect(idleHook).toBeDefined();
  });

  it('should configure permission_prompt matcher', () => {
    const config = generateHooksConfig();
    const notifHooks = config.hooks.Notification as Array<{ matcher?: string }>;
-    const permHook = notifHooks.find(h => h.matcher === 'permission_prompt');
+    const permHook = notifHooks.find((h) => h.matcher === 'permission_prompt');
    expect(permHook).toBeDefined();
  });

  it('should configure elicitation_dialog matcher', () => {
    const config = generateHooksConfig();
    const notifHooks = config.hooks.Notification as Array<{ matcher?: string }>;
-    const elicitHook = notifHooks.find(h => h.matcher === 'elicitation_dialog');
+    const elicitHook = notifHooks.find((h) => h.matcher === 'elicitation_dialog');
    expect(elicitHook).toBeDefined();
  });

@@ -146,7 +146,7 @@ describe('writeHooksConfig', () => {
    mkdirSync(claudeDir, { recursive: true });
    writeFileSync(
      join(claudeDir, 'settings.local.json'),
-      JSON.stringify({ existingKey: 'existingValue', permissions: { allow: ['Read'] } }, null, 2),
+      JSON.stringify({ existingKey: 'existingValue', permissions: { allow: ['Read'] } }, null, 2)
    );

    await writeHooksConfig(testDir);
@@ -160,10 +160,7 @@ describe('writeHooksConfig', () => {
  it('should overwrite existing hooks key', async () => {
    const claudeDir = join(testDir, '.claude');
    mkdirSync(claudeDir, { recursive: true });
-    writeFileSync(
-      join(claudeDir, 'settings.local.json'),
-      JSON.stringify({ hooks: { oldHook: [] } }, null, 2),
-    );
+    writeFileSync(join(claudeDir, 'settings.local.json'), JSON.stringify({ hooks: { oldHook: [] } }, null, 2));

    await writeHooksConfig(testDir);

@@ -214,7 +211,7 @@ describe('Hook Event API', () => {
      body: JSON.stringify({}),
    });
    const createData = await createRes.json();
-    testSessionId = createData.session.id;
+    testSessionId = createData.data.session.id;
  });

  afterAll(async () => {
@@ -396,7 +393,7 @@ describe('Hook Data Sanitization', () => {
      body: JSON.stringify({}),
    });
    const createData = await createRes.json();
-    testSessionId = createData.session.id;
+    testSessionId = createData.data.session.id;
  });

  afterAll(async () => {
@@ -641,7 +638,7 @@ describe('Hook Config Generation - Extended', () => {
  it('should include all event types', () => {
    const config = generateHooksConfig();
    const notifHooks = config.hooks.Notification as Array<{ matcher?: string }>;
-    const matchers = notifHooks.map(n => n.matcher);
+    const matchers = notifHooks.map((n) => n.matcher);
    expect(matchers).toContain('idle_prompt');
    expect(matchers).toContain('permission_prompt');
    expect(matchers).toContain('elicitation_dialog');
@@ -694,7 +691,10 @@ describe('Hook Config Generation - Extended', () => {

  it('should have consistent structure across all notification hooks', () => {
    const config = generateHooksConfig();
-    const notifHooks = config.hooks.Notification as Array<{ matcher: string; hooks: Array<{ type: string; command: string; timeout: number }> }>;
+    const notifHooks = config.hooks.Notification as Array<{
+      matcher: string;
+      hooks: Array<{ type: string; command: string; timeout: number }>;
+    }>;

    for (const hook of notifHooks) {
      expect(hook.matcher).toBeDefined();
@@ -0,0 +1,92 @@
+/**
+ * Live-server tests for the stable HTTP contract (docs/api-reference.md):
+ * the uniform {success,data} envelope, error envelopes with conventional
+ * HTTP statuses, the /api/v1 alias, and the /api not-found handler.
+ *
+ * These behaviors live in server.ts (preSerialization hook, setNotFoundHandler),
+ * which the route-test harness does not install — so they need a real WebServer.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { WebServer } from '../src/web/server.js';
+
+const PORT = 3168;
+
+describe('Stable HTTP contract (live server)', () => {
+  let server: WebServer;
+  const base = `http://localhost:${PORT}`;
+
+  beforeAll(async () => {
+    server = new WebServer(PORT, false, true);
+    await server.start();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  it('wraps bare payloads as { success: true, data }', async () => {
+    const res = await fetch(`${base}/api/status`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.success).toBe(true);
+    expect(body.data).toBeDefined();
+    expect(body.data.version).toBeDefined();
+  });
+
+  it('serves the same envelope on the /api/v1 alias', async () => {
+    const res = await fetch(`${base}/api/v1/status`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.success).toBe(true);
+    expect(body.data.version).toBeDefined();
+  });
+
+  it('maps error envelopes to conventional HTTP statuses', async () => {
+    const res = await fetch(`${base}/api/sessions/nonexistent/terminal`);
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(typeof body.error).toBe('string');
+    expect(body.errorCode).toBe('NOT_FOUND');
+  });
+
+  it('returns a contract-shaped 404 for unknown /api routes', async () => {
+    const res = await fetch(`${base}/api/this-route-does-not-exist`);
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('NOT_FOUND');
+  });
+
+  it('returns a contract-shaped 404 for unknown /api/v1 routes', async () => {
+    const res = await fetch(`${base}/api/v1/this-route-does-not-exist`);
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('NOT_FOUND');
+  });
+
+  it('rejects a bad /api/events/subscribe body with an error envelope', async () => {
+    const res = await fetch(`${base}/api/events/subscribe`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('INVALID_INPUT');
+  });
+
+  it('keeps validation errors on the envelope with HTTP 400', async () => {
+    const res = await fetch(`${base}/api/clipboard`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text: '' }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.success).toBe(false);
+    expect(body.errorCode).toBe('INVALID_INPUT');
+  });
+});
@@ -145,7 +145,7 @@ describe('ImageWatcher', () => {
  // ========== Image Detection ==========

  describe('image detection', () => {
-    it('should emit image:detected for .png files', () => {
+    it('should emit image:detected (popup) for .png files', () => {
      const handler = vi.fn();
      watcher.on('image:detected', handler);

@@ -161,7 +161,37 @@ describe('ImageWatcher', () => {
      expect(event.fileName).toBe('screenshot.png');
      expect(event.filePath).toBe('/home/user/project/screenshot.png');
      expect(event.relativePath).toBe('screenshot.png');
-      expect(event.size).toBe(2048);
+    });
+
+    it('should not emit attachment:detected for .png (stays on the popup path)', () => {
+      const handler = vi.fn();
+      watcher.on('attachment:detected', handler);
+
+      watcher.watchSession('session-1', '/home/user/project');
+      mockWatchers.get('/home/user/project')!.emit('add', '/home/user/project/screenshot.png');
+      vi.advanceTimersByTime(300);
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['report.pdf', 'pdf'],
+      ['brief.docx', 'document'],
+      ['deck.pptx', 'presentation'],
+    ])('should emit attachment:detected for %s files', (fileName, attachmentType) => {
+      const handler = vi.fn();
+      watcher.on('attachment:detected', handler);
+
+      watcher.watchSession('session-1', '/home/user/project');
+      mockWatchers.get('/home/user/project')!.emit('add', `/home/user/project/${fileName}`);
+      vi.advanceTimersByTime(300);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler.mock.calls[0][0]).toMatchObject({
+        sessionId: 'session-1',
+        fileName,
+        attachmentType,
+      });
    });

    it('should emit for .jpg files', () => {
@@ -250,10 +280,10 @@ describe('ImageWatcher', () => {
      watcher.on('image:detected', handler);

      watcher.watchSession('session-1', '/home/user/project');
-      mockWatchers.get('/home/user/project')!.emit('add', '/home/user/project/assets/img.png');
+      mockWatchers.get('/home/user/project')!.emit('add', '/home/user/project/assets/img.jpg');
      vi.advanceTimersByTime(300);

-      expect(handler.mock.calls[0][0].relativePath).toBe('assets/img.png');
+      expect(handler.mock.calls[0][0].relativePath).toBe('assets/img.jpg');
    });
  });

@@ -268,11 +298,11 @@ describe('ImageWatcher', () => {
      const chokidarWatcher = mockWatchers.get('/home/user/project')!;

      // Rapid adds of the same file
-      chokidarWatcher.emit('add', '/home/user/project/screenshot.png');
+      chokidarWatcher.emit('add', '/home/user/project/screenshot.jpg');
      vi.advanceTimersByTime(100); // not yet past debounce
-      chokidarWatcher.emit('add', '/home/user/project/screenshot.png');
+      chokidarWatcher.emit('add', '/home/user/project/screenshot.jpg');
      vi.advanceTimersByTime(100);
-      chokidarWatcher.emit('add', '/home/user/project/screenshot.png');
+      chokidarWatcher.emit('add', '/home/user/project/screenshot.jpg');
      vi.advanceTimersByTime(300); // now past debounce from last emit

      // Should only emit once (the last debounced one)
@@ -286,8 +316,8 @@ describe('ImageWatcher', () => {
      watcher.watchSession('session-1', '/home/user/project');
      const chokidarWatcher = mockWatchers.get('/home/user/project')!;

-      chokidarWatcher.emit('add', '/home/user/project/a.png');
-      chokidarWatcher.emit('add', '/home/user/project/b.png');
+      chokidarWatcher.emit('add', '/home/user/project/a.jpg');
+      chokidarWatcher.emit('add', '/home/user/project/b.jpg');
      vi.advanceTimersByTime(300);

      expect(handler).toHaveBeenCalledTimes(2);
@@ -306,7 +336,7 @@ describe('ImageWatcher', () => {

      // Emit 25 unique images in quick succession
      for (let i = 0; i < 25; i++) {
-        chokidarWatcher.emit('add', `/home/user/project/img${i}.png`);
+        chokidarWatcher.emit('add', `/home/user/project/img${i}.jpg`);
        vi.advanceTimersByTime(250); // past debounce, within burst window
      }

@@ -323,7 +353,7 @@ describe('ImageWatcher', () => {

      // Fill up burst limit
      for (let i = 0; i < 20; i++) {
-        chokidarWatcher.emit('add', `/home/user/project/img${i}.png`);
+        chokidarWatcher.emit('add', `/home/user/project/img${i}.jpg`);
        vi.advanceTimersByTime(250);
      }
      expect(handler).toHaveBeenCalledTimes(20);
@@ -332,7 +362,7 @@ describe('ImageWatcher', () => {
      vi.advanceTimersByTime(11_000);

      // Should accept new images
-      chokidarWatcher.emit('add', '/home/user/project/new.png');
+      chokidarWatcher.emit('add', '/home/user/project/new.jpg');
      vi.advanceTimersByTime(300);

      expect(handler).toHaveBeenCalledTimes(21);
@@ -58,24 +58,24 @@ describe('Integration Flows', () => {
      const quickStartData = await quickStartRes.json();

      expect(quickStartData.success).toBe(true);
-      expect(quickStartData.sessionId).toBeDefined();
-      expect(quickStartData.caseName).toBe(caseName);
-      createdSessions.push(quickStartData.sessionId);
+      expect(quickStartData.data.sessionId).toBeDefined();
+      expect(quickStartData.data.caseName).toBe(caseName);
+      createdSessions.push(quickStartData.data.sessionId);

      // Step 2: Verify session is in interactive mode
-      const sessionRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}`);
+      const sessionRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}`);
      const sessionData = await sessionRes.json();

-      expect(sessionData.id).toBe(quickStartData.sessionId);
-      expect(sessionData.workingDir).toContain(caseName);
-      expect(['busy', 'idle', 'running']).toContain(sessionData.status); // May transition quickly in test mode
+      expect(sessionData.data.id).toBe(quickStartData.data.sessionId);
+      expect(sessionData.data.workingDir).toContain(caseName);
+      expect(['busy', 'idle', 'running']).toContain(sessionData.data.status); // May transition quickly in test mode

      // Step 3: Verify case was created with CLAUDE.md
      const caseRes = await fetch(`${baseUrl}/api/cases/${caseName}`);
      const caseData = await caseRes.json();

-      expect(caseData.name).toBe(caseName);
-      expect(caseData.hasClaudeMd).toBe(true);
+      expect(caseData.data.name).toBe(caseName);
+      expect(caseData.data.hasClaudeMd).toBe(true);
    });

    it('should reuse existing case when quick starting with existing case name', async () => {
@@ -90,10 +90,10 @@ describe('Integration Flows', () => {
      });
      const firstData = await firstRes.json();
      expect(firstData.success).toBe(true);
-      createdSessions.push(firstData.sessionId);
+      createdSessions.push(firstData.data.sessionId);

      // Delete the session but keep the case
-      await fetch(`${baseUrl}/api/sessions/${firstData.sessionId}`, { method: 'DELETE' });
+      await fetch(`${baseUrl}/api/sessions/${firstData.data.sessionId}`, { method: 'DELETE' });

      // Second quick start - should reuse the case
      const secondRes = await fetch(`${baseUrl}/api/quick-start`, {
@@ -104,9 +104,9 @@ describe('Integration Flows', () => {
      const secondData = await secondRes.json();

      expect(secondData.success).toBe(true);
-      expect(secondData.caseName).toBe(caseName);
-      expect(secondData.casePath).toBe(firstData.casePath);
-      createdSessions.push(secondData.sessionId);
+      expect(secondData.data.caseName).toBe(caseName);
+      expect(secondData.data.casePath).toBe(firstData.data.casePath);
+      createdSessions.push(secondData.data.sessionId);
    });
  });

@@ -132,20 +132,20 @@ describe('Integration Flows', () => {
      });
      const sessionData = await sessionRes.json();
      expect(sessionData.success).toBe(true);
-      createdSessions.push(sessionData.session.id);
+      createdSessions.push(sessionData.data.session.id);

      // Step 3: Start interactive mode
-      const interactiveRes = await fetch(`${baseUrl}/api/sessions/${sessionData.session.id}/interactive`, {
+      const interactiveRes = await fetch(`${baseUrl}/api/sessions/${sessionData.data.session.id}/interactive`, {
        method: 'POST',
      });
      const interactiveData = await interactiveRes.json();
      expect(interactiveData.success).toBe(true);

      // Verify session state
-      const verifyRes = await fetch(`${baseUrl}/api/sessions/${sessionData.session.id}`);
+      const verifyRes = await fetch(`${baseUrl}/api/sessions/${sessionData.data.session.id}`);
      const verifyData = await verifyRes.json();
-      expect(['busy', 'idle', 'running']).toContain(verifyData.status);
-      expect(verifyData.workingDir).toContain(caseName);
+      expect(['busy', 'idle', 'running']).toContain(verifyData.data.status);
+      expect(verifyData.data.workingDir).toContain(caseName);
    });
  });

@@ -162,13 +162,13 @@ describe('Integration Flows', () => {
      });
      const quickStartData = await quickStartRes.json();
      expect(quickStartData.success).toBe(true);
-      createdSessions.push(quickStartData.sessionId);
+      createdSessions.push(quickStartData.data.sessionId);

      // Wait for Claude to start up
-      await new Promise(resolve => setTimeout(resolve, 2000));
+      await new Promise((resolve) => setTimeout(resolve, 2000));

      // Send input
-      const inputRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}/input`, {
+      const inputRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}/input`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ input: '/help\n' }),
@@ -177,12 +177,12 @@ describe('Integration Flows', () => {
      expect(inputData.success).toBe(true);

      // Wait for response
-      await new Promise(resolve => setTimeout(resolve, 1000));
+      await new Promise((resolve) => setTimeout(resolve, 1000));

      // Check terminal buffer has content
-      const terminalRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}/terminal`);
+      const terminalRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}/terminal`);
      const terminalData = await terminalRes.json();
-      expect(terminalData.terminalBuffer.length).toBeGreaterThan(0);
+      expect(terminalData.data.terminalBuffer.length).toBeGreaterThan(0);
    });

    it('should handle terminal resize', async () => {
@@ -197,15 +197,21 @@ describe('Integration Flows', () => {
      });
      const quickStartData = await quickStartRes.json();
      expect(quickStartData.success).toBe(true);
-      createdSessions.push(quickStartData.sessionId);
+      createdSessions.push(quickStartData.data.sessionId);

-      // Resize terminal
-      const resizeRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}/resize`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ cols: 200, rows: 50 }),
-      });
-      const resizeData = await resizeRes.json();
+      // Resize terminal (retry briefly — a just-quick-started session can be
+      // momentarily busy, which would return SESSION_BUSY; this is a transient race).
+      let resizeData;
+      for (let attempt = 0; attempt < 5; attempt++) {
+        const resizeRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}/resize`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ cols: 200, rows: 50 }),
+        });
+        resizeData = await resizeRes.json();
+        if (resizeData.success) break;
+        await new Promise((r) => setTimeout(r, 100));
+      }
      expect(resizeData.success).toBe(true);
    });
  });
@@ -225,16 +231,16 @@ describe('Integration Flows', () => {
      expect(quickStartData.success).toBe(true);

      // Delete the session
-      const deleteRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}`, {
+      const deleteRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}`, {
        method: 'DELETE',
      });
      const deleteData = await deleteRes.json();
      expect(deleteData.success).toBe(true);

      // Verify session is gone
-      const verifyRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.sessionId}`);
+      const verifyRes = await fetch(`${baseUrl}/api/sessions/${quickStartData.data.sessionId}`);
      const verifyData = await verifyRes.json();
-      expect(verifyData.error).toBe('Session not found');
+      expect(verifyData.error).toContain('not found');
    });
  });

@@ -251,20 +257,20 @@ describe('Integration Flows', () => {
      });
      const quickStartData = await quickStartRes.json();
      expect(quickStartData.success).toBe(true);
-      createdSessions.push(quickStartData.sessionId);
+      createdSessions.push(quickStartData.data.sessionId);

      // Get full status
      const statusRes = await fetch(`${baseUrl}/api/status`);
      const statusData = await statusRes.json();

-      expect(statusData.sessions).toBeDefined();
-      expect(Array.isArray(statusData.sessions)).toBe(true);
-      expect(statusData.scheduledRuns).toBeDefined();
-      expect(statusData.respawnStatus).toBeDefined();
-      expect(statusData.timestamp).toBeDefined();
+      expect(statusData.data.sessions).toBeDefined();
+      expect(Array.isArray(statusData.data.sessions)).toBe(true);
+      expect(statusData.data.scheduledRuns).toBeDefined();
+      expect(statusData.data.respawnStatus).toBeDefined();
+      expect(statusData.data.timestamp).toBeDefined();

      // Verify our session is in the list
-      const ourSession = statusData.sessions.find((s: any) => s.id === quickStartData.sessionId);
+      const ourSession = statusData.data.sessions.find((s: any) => s.id === quickStartData.data.sessionId);
      expect(ourSession).toBeDefined();
      expect(ourSession.workingDir).toContain(caseName);
    });
@@ -309,7 +315,7 @@ describe('SSE Event Flow', () => {

    const fetchPromise = fetch(`${baseUrl}/api/events`, {
      signal: controller.signal,
-    }).then(async response => {
+    }).then(async (response) => {
      const reader = response.body?.getReader();
      if (reader) {
        try {
@@ -331,7 +337,7 @@ describe('SSE Event Flow', () => {
    });

    // Wait for connection
-    await new Promise(resolve => setTimeout(resolve, 100));
+    await new Promise((resolve) => setTimeout(resolve, 100));

    // Perform quick start
    const quickStartRes = await fetch(`${baseUrl}/api/quick-start`, {
@@ -341,14 +347,16 @@ describe('SSE Event Flow', () => {
    });
    const quickStartData = await quickStartRes.json();
    expect(quickStartData.success).toBe(true);
-    createdSessions.push(quickStartData.sessionId);
+    createdSessions.push(quickStartData.data.sessionId);

    // Wait for events
-    await new Promise(resolve => setTimeout(resolve, 500));
+    await new Promise((resolve) => setTimeout(resolve, 500));

    // Stop SSE
    controller.abort();
-    try { await fetchPromise; } catch {}
+    try {
+      await fetchPromise;
+    } catch {}

    // Verify expected events were received
    expect(receivedEvents).toContain('init');
@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Regression guard for the terminal link-provider regexes in
+ * `src/web/public/terminal-ui.js`.
+ *
+ * The link provider runs its patterns against every hovered terminal line
+ * (logical lines — xterm re-joins wrapped rows, so inputs reach multiple KB).
+ * A pattern with ambiguous backtracking freezes the entire tab on hover:
+ * 0.9.10's `cmdPattern` used `(?:[^\s\/]*\s+)*` (empty-matchable token,
+ * unbounded), which went exponential on real Claude output — wrapped
+ * `git commit -m "$(cat <<'EOF'` heredoc lines hung the main thread for
+ * minutes per hover.
+ *
+ * This test extracts the pattern literals FROM THE SHIPPED SOURCE (no copies
+ * that can drift) and asserts they stay linear-time on those killer shapes,
+ * and that `cmdPattern` still links the command+path forms it exists for.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const SOURCE = readFileSync(join(__dirname, '..', 'src', 'web', 'public', 'terminal-ui.js'), 'utf-8');
+
+/** Extract `const <name> = /.../g;` from the shipped source and build the RegExp. */
+function shippedPattern(name: string): RegExp {
+  const m = SOURCE.match(new RegExp(`const ${name} =\\s*\\n?\\s*(/(?:[^/\\\\\\n]|\\\\.)+/[a-z]*)`));
+  if (!m) throw new Error(`pattern ${name} not found in terminal-ui.js`);
+  const lit = m[1];
+  const lastSlash = lit.lastIndexOf('/');
+  return new RegExp(lit.slice(1, lastSlash), lit.slice(lastSlash + 1));
+}
+
+const PATTERN_NAMES = ['urlPattern', 'cmdPattern', 'extPattern', 'bashPattern'];
+
+/** Lines that made 0.9.10's cmdPattern backtrack exponentially (>2s each). */
+const KILLER_LINES = [
+  // wrapped git-commit heredoc from real Claude tool output (the 0.9.10 freeze)
+  `      /Users/arbbot/codeman-cases/topagent-control commit -m "$(cat <<'EOF'${' '.repeat(3000)}`,
+  // aligned table row: trigger word + multi-space-separated columns + mid-token slash
+  'watch  ' + 'col   '.repeat(40) + ' BTC/USDT',
+  // trigger word followed by many tokens and no token-initial path
+  'cat ' + 'word '.repeat(800) + 'no-path-here',
+  // long URL-ish and path-ish soup for the other patterns
+  'https://example.com/' + 'a/'.repeat(1500) + ' ' + '/home/x/'.repeat(400) + '.'.repeat(2000),
+  'Bash(' + 'x'.repeat(4000),
+];
+
+describe('terminal link-provider regexes (shipped source)', () => {
+  it('all patterns stay linear-time on killer lines', () => {
+    const patterns = PATTERN_NAMES.map((n) => [n, shippedPattern(n)] as const);
+    const start = Date.now();
+    for (const [, re] of patterns) {
+      for (const line of KILLER_LINES) {
+        re.lastIndex = 0;
+        while (re.exec(line) !== null) {
+          /* drain all matches like the provider does */
+        }
+      }
+    }
+    const elapsed = Date.now() - start;
+    // 20 pattern×line runs over multi-KB inputs: linear patterns finish in a few
+    // ms; the 0.9.10 cmdPattern alone needed minutes for ONE line.
+    expect(elapsed).toBeLessThan(500);
+  });
+
+  it('cmdPattern still links command + path forms', () => {
+    const cmd = shippedPattern('cmdPattern');
+    const cases: Array<[string, string]> = [
+      ['tail -f /var/log/app.log', '/var/log/app.log'],
+      ['cat -n /tmp/x.json', '/tmp/x.json'],
+      ['grep -rn pattern /home/user/src', '/home/user/src'],
+      ['watch ls /opt/data', '/opt/data'],
+      ['head -c 100 /etc/hosts', '/etc/hosts'],
+    ];
+    for (const [line, want] of cases) {
+      cmd.lastIndex = 0;
+      const m = cmd.exec(line);
+      expect(m, line).not.toBeNull();
+      expect(m![2]).toBe(want);
+    }
+  });
+
+  it('cmdPattern arg group cannot match empty tokens (the exponential trigger)', () => {
+    // structural guard: the dangerous construct is an empty-matchable token
+    // inside a repeated group — `[^\s\/]*\s+` repeated. Check the pattern
+    // literal itself (not the whole file — the warning comment quotes it).
+    const lit = shippedPattern('cmdPattern').source;
+    expect(lit).not.toContain('[^\\s\\/]*\\s+)*');
+  });
+});
--- a/Show More
+++ b/Show More