chore: version packages

Codex plan usage in the header chip (#346), a visible inline rename in the session sidebar (#345), and the install.sh Tailscale re-run fix plus the README network-access prompt description. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merge pull request #346 from JackStuart/codex/show-codex-usage-limits
2026-09-30 20:49:41 +02:00 · 2026-08-28 00:25:32 +02:00 · 2026-08-28 00:14:54 +02:00 · 2026-08-28 00:14:48 +02:00 · 2026-08-28 00:02:33 +02:00 · 2026-08-26 18:29:15 +02:00
31 changed files with 3612 additions and 168 deletions
@@ -1,5 +1,40 @@
 # aicodeman

+## 1.23.2
+
+### Patch Changes
+
+- Codex plan usage in the header chip, a visible inline rename in the session sidebar, and an installer that no longer loses Tailscale access on a re-run.
+
+  **Codex plan usage in the header chip** (#346): the plan-usage chip used to show Claude's 5-hour and weekly limits without saying they were Claude's, which stops being a detail the moment you run more than one CLI. It now renders one compact row per provider, Claude above Codex, each labelled and colour-coded by how much is used up. Claude's numbers still come from Codeman's marked `statusLine.command` exporter; Codex's come from the signed-in host CLI's read-only `account/rateLimits/read` app-server request at startup and every five minutes, so credentials stay inside the CLI and no auth material reaches the browser. Only the main `codex` bucket is read (model-specific buckets such as Spark are separate limits and are deliberately excluded), and the Codex row is omitted entirely when no 5-hour or weekly window is available, rather than inventing one.
+
+  **Inline rename is visible in the session sidebar** (#345): starting a rename on a sidebar row opened a focused input you could not see. The row's ellipsis clamp was still painting over the live editor, so text and caret went in blind. The sidebar now gets the same unclamped editor layout the vertical tab rail already had. Covered by a Chromium regression test that asserts the painted `overflow` and the input's measured width, not just the class name.
+
+  **install.sh keeps Tailscale access on a re-run**: a re-run whose build failed could drop a working Tailscale binding instead of preserving it. The installer now offers Tailscale setup again on re-run rather than losing it, and the README describes the three-way network-access prompt (Tailscale / LAN / local-only) as it actually behaves.
+
+  ### Thanks
+  - @JackStuart for #346
+  - @fibr for #345
+  - @tailong-wu for #342, whose analysis of the terminal refresh replay loop matched a fix that had landed on master a few hours earlier
+
+## 1.23.1
+
+### Patch Changes
+
+- Fix a fresh-Linux install failure, and bound the browser terminal's live write queue.
+
+  **install.sh now installs a build toolchain.** Reported against a stock Ubuntu 24 server: node-pty publishes prebuilt binaries for darwin and win32 only, so on Linux it is always compiled from source during `npm install`. The installer set up Node, tmux and git but never a compiler, so a machine without `build-essential` died deep inside node-gyp with `not found: make` — which reads like an npm bug rather than a missing system package. `make`, a C++ compiler and `python3` are now checked up front exactly like git and tmux, installed per distro (apt / dnf / pacman / apk / zypper) behind the same consent prompt, and re-verified afterwards rather than assumed. If `npm install` fails anyway — including on `install.sh update` — it now names the missing tools and the command that installs them instead of leaving a node-gyp stack trace as the last word.
+
+  **Bounded live xterm backpressure** (#339): live output is now one chunk in flight at a time, released by xterm's own parse callback, so xterm's private WriteBuffer can no longer hide an unbounded backlog behind the browser's 128 KiB render cap; queued, loading and incoming bytes all count against that cap. Automatic drop recovery for a shell stays on the bounded 1 MiB tail — a 100k-line shell capture is tens of MiB, and parsing it on the main thread is the freeze the cap exists to prevent — while TUI modes still recover full history behind the existing downgrade guard. Duplicate SSE terminal events are dropped before JSON parsing while WebSocket owns terminal I/O, and recovery is single-flight per active session. Follow-up hardening: the three write-queue reset paths now also release the in-flight gate, so a parse callback that never lands cannot leave live output permanently stalled.
+
+  **File Viewer searches the workspace** (#340): the File Viewer search box now queries the server-side file search endpoint with a 250 ms debounce and strict response validation, instead of filtering only the part of the tree already loaded. Tree and search state are scoped to the active session, the hidden-file preference and independent request epochs, so a stale response cannot repaint the panel; cached-tree restoration, directory results and reset behaviour survive session switches and both panel-hide paths.
+
+  ### Thanks
+  - @dignfei for #339
+  - @aakhter for #340
+
+- 858b15e: Search the full session workspace from File Viewer while keeping results scoped to the active session and hidden-file preference.
+
 ## 1.23.0

 ### Minor Changes
@@ -75,7 +75,7 @@ When user says "COM":

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

-**Version**: 1.23.0 (must match `package.json`)
+**Version**: 1.23.2 (must match `package.json`)

 ## Project Overview

@@ -135,7 +135,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **`xterm-zerolag-input` is single-source** — BOTH echo addons live ONLY in `packages/xterm-zerolag-input/src/`, bundled into TWO **gitignored** vendor files: `vendor/xterm-zerolag-input.js` (buffer overlay, entry `zerolag-input-addon.ts`) and `vendor/xterm-predictive-echo.js` (codex write-through, entry `predictive-echo-addon.ts`) — dev by `scripts/postinstall.js`, prod by `scripts/build.mjs`. `app.js`/terminal-ui.js only **consume** them via `new LocalEchoOverlay(terminal)` / `new PredictiveEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundles.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
 - **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
 - **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`, and **any new `tmux -L` caller through `resolveTmuxSocketName()`** (both in `config/instance.ts`): the TUI shells out to tmux from a second process, and a hardcoded `codeman` there would point a beta instance at prod's panes. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
+- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ The flip side of that: since Linux has no prebuild, `npm install` **needs a C/C++ toolchain there** (`make`, `g++`, `python3`), so `install.sh` checks for and installs one alongside Node/tmux/git — a stock Ubuntu 24 server has none and died inside node-gyp with `not found: make`. Do not drop that step. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
 - **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)

 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
@@ -195,7 +195,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit)

-**Plan-usage chip** (statusLine telemetry, `showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the `statusLineTelemetry` flag on session create). A chip shown without telemetry renders `—` forever. Codeman injects its own `statusLine.command` exporter which POSTs Claude's `rate_limits` blob to `POST /api/status-telemetry`. The exporter is identified by a marker, so it only ever adds/updates/removes a statusLine that is **ours**, never a user's hand-authored one, and it prints the footer through so the in-terminal statusline is not blanked. Claude-mode only; distinct from auto-resume, which reacts to the limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
+**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the Claude `statusLineTelemetry` flag on session create). It renders compact Claude and Codex provider rows. Claude data comes from Codeman's marked `statusLine.command` exporter, which POSTs `rate_limits` to `POST /api/status-telemetry`, never overwrites a user's hand-authored statusLine, and prints the footer through. Main Codex usage comes from a read-only host `account/rateLimits/read` app-server poll at startup and every 5 minutes; exclude model-specific buckets such as Spark, and omit the Codex row when no signed-in limit is available. Distinct from auto-resume, which reacts to Claude's limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`

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

@@ -225,7 +225,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph

 **Circuit breakers**: the Ralph breaker prevents respawn thrashing (`CLOSED` → `HALF_OPEN` → `OPEN`; reset via `/api/sessions/:id/ralph-circuit-breaker/reset`). **Distinct: the PTY-exit breaker** (`session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits and blocks auto-restarts. ⚠️ It resets ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive`; the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. → [architecture-invariants#circuit-breakers-ralph--pty-exit](docs/architecture-invariants.md#circuit-breakers-ralph-and-pty-exit)

-**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set); Shell selection always starts from a bounded 1 MiB `?tail=` window and loads the rest only when **Load full history** is pressed. Ordinary Shell scrolling must not trigger a multi-megabyte reset+replay on xterm's main thread. Other modes may re-pull at the TOP (cooldown-guarded — tmux repaints bursty output in place, so browser scrollback shrinks while tmux's history stays complete). ⚠️ That re-pull must never DOWNGRADE the buffer: a repaint-mode CLI pane keeps no tmux history, so its capture is one frame and the reset+rewrite would delete history mid-scroll — `_replayWouldShrinkBuffer()` refuses it and slows that session's cooldown to 60s. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
+**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set); Shell selection and automatic drop recovery always use a bounded 1 MiB `?tail=` window. Shell loads the rest only when **Load full history** is pressed; ordinary scrolling must not trigger a multi-megabyte reset+replay on xterm's main thread. Other modes may re-pull at the TOP (cooldown-guarded — tmux repaints bursty output in place, so browser scrollback shrinks while tmux's history stays complete). Live writes are one-chunk-in-flight, released by xterm's parse callback, so xterm's private queue cannot bypass the browser's 128 KiB render cap. While WebSocket owns terminal I/O, duplicate SSE terminal events are dropped before JSON parsing, and recovery is single-flight per active session. ⚠️ A full re-pull must never DOWNGRADE the buffer: a repaint-mode CLI pane keeps no tmux history, so its capture is one frame and the reset+rewrite would delete history mid-scroll — `_replayWouldShrinkBuffer()` refuses it and slows that session's cooldown to 60s. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)

 **Terminal touch gestures: link taps and text selection**: on a touch device xterm's own handlers see neither — `touch-action: none` plus touchstart's preventDefault suppress the browser's compatibility mouse events, `_installMobileTapMouseGuard` drops the trusted ones that still arrive, and the synthetic `mousedown`/`mouseup` pair dispatched for mouse REPORTING goes to the `.xterm` root, an ANCESTOR of the screen element the linkifier and SelectionService listen on. So both gestures are driven explicitly. ⚠️ **A tap activates the link under it** through the SAME provider that feeds the hover linkifier (`_terminalLinkAtPoint`, containment mirroring xterm's `_linkAtPosition`), synchronously inside `touchend` — that is what keeps the user gesture `window.open` needs — and BEFORE any mouse report, mirroring `_handleDesktopTerminalClick`'s skip for a hovered link. Two rows keep their meaning: the caret's logical line (`_tapIsOnCaretLine`, where a tap places the cursor in text the USER typed) and TUI-owned rows (`_isActionableMobileTerminalTap`, answering a dialog). ⚠️ The caret line is the boundary rather than the tap INTENT, because a shell classifies every tap as `'input'` and gating on that would leave every URL in shell output inert. ⚠️ **Long-press selects** by driving xterm's public `select()` (renderer-independent — under WebGL the glyphs are pixels and native selection cannot exist), drag or a further tap extends, and Copy goes through `copyTerminalSelection()` for its execCommand fallback on plain-HTTP installs. Three guards are load-bearing and each came from a real phone: the compat mouse pair after `touchend` (xterm focuses on mousedown and SelectionService resets the model there, so the keyboard sprang up and the selection vanished on lift), the platform's own ~500ms long-press (Android Chrome focuses the nearest editable element — the helper textarea — through no event a handler can preventDefault, so a bounded focus guard blurs it and `contextmenu` is suppressed for the gesture window), and `copyTerminalSelection()`'s closing `terminal.focus()` (right on desktop, wrong on a phone). Tests: `test/terminal-touch-tap.test.ts`.

@@ -61,10 +61,10 @@ The installer asks before every system change, and re-running the same line upda
 curl -fsSL https://getcodeman.com/install | bash
 ```

-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
+This installs Node.js, tmux and a build toolchain if missing (node-pty ships no Linux prebuilds, so it compiles from source), clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:

 - **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
+- **How it's reachable, your choice.** The installer offers three ways to reach the dashboard: **Tailscale** (loopback bind fronted by `tailscale serve`, so you get `https://<machine>.<tailnet>.ts.net` with a real certificate and your tailnet as the login, no password needed), **any device on your network** (`0.0.0.0`, with a strongly recommended password prompt), or **this machine only** (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. The highlighted default reflects what is already on the machine (Tailscale when it is already in use, your existing binding on a re-run), and a bare Enter never pulls in new software. A bare `codeman web` started by hand still defaults to loopback.
 - **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
 - **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.

@@ -86,7 +86,7 @@ Model is NOT a session field: it is a composition entry in the profile's config

 ### Plan-usage chip (statusLine telemetry)

-**Plan-usage chip** (statusLine telemetry, `showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF): Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through** (so injecting our statusLine doesn't blank the in-terminal footer). `plan-usage-latest.ts` holds the process-wide last value, replayed in the SSE init snapshot (`getLightState`) so the header chip (`#planUsageChip`, revealed by `planUsageChipEnabled()` in settings-ui.js, the single resolver behind the checkbox, the chip and the create-time `statusLineTelemetry` flag) renders immediately on page load / reconnect without per-browser localStorage. Claude-mode only. **Distinct from auto-resume** (which reacts to the limit _message_; this proactively shows the live %). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`.
+**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF) renders compact Claude and Codex provider rows. Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through**. Main Codex subscription usage comes from the signed-in host CLI's read-only app-server `account/rateLimits/read` request at startup and every 5 minutes; `usage-telemetry.ts` selects only the main `codex` bucket (never model-specific buckets such as Spark), maps whatever 5-hour/7-day windows it supplies, and omits the provider row when unavailable. Credentials stay inside the CLI and no auth material is sent to the browser. `plan-usage-latest.ts` merges both process-wide sources and replays them in the SSE init snapshot (`getLightState`) so `#planUsageChip` renders immediately on page load/reconnect. `planUsageChipEnabled()` remains the single resolver behind the checkbox, chip visibility, and Claude create-time exporter flag. **Distinct from auto-resume** (which reacts to the Claude limit _message_; this proactively shows live percentages). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`, `test/codex-plan-usage.test.ts`, `test/plan-usage-chip.test.ts`, `test/plan-usage-latest.test.ts`.

 ### Cron jobs

@@ -110,7 +110,7 @@ Model is NOT a session field: it is a composition entry in the profile's config

 ### Full-scrollback replay

-**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other TUI tab one frame of history). Shell sessions instead load a bounded 1 MiB `?tail=` window on every selection: a 100k-line shell capture can be tens of MiB, and automatically parsing it makes tab-switch latency scale with the entire session. Shell full history is therefore explicit-button-only; reaching the top during an ordinary wheel/touch gesture must not reset xterm and replay the multi-megabyte capture on its main thread. Other modes may still re-pull `full=1` at the TOP, and pressing **Load full history** forces the request for any recoverably truncated session (`_maybeRefetchFullHistory`, 4s per-session gesture cooldown, in-flight + tab-switch guards, viewport position held across the replay); Shell full pulls are not retained in the tab cache, so the next switch stays bounded. Chunked replay enqueues 32 KiB pieces across safe yields, appends an xterm parse marker, then releases the live-output gate; output arriving after that release stays ordered behind the snapshot, while the marker callback supplies accurate parse timing without extending the pre-existing queued-event discard window. The route exposes capture/prepare totals in `Server-Timing`, while `[TERMINAL-PERF]` separates TTFB, body/JSON, reset+parse and total time for both selection and on-demand full pulls; parse completion is not a browser compositor/GPU paint measurement. The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`.
+**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other TUI tab one frame of history). Shell sessions instead load a bounded 1 MiB `?tail=` window on every selection and automatic drop recovery: a 100k-line shell capture can be tens of MiB, and automatically parsing it makes tab-switch latency scale with the entire session. Shell full history is explicit-button-only; reaching the top during an ordinary wheel/touch gesture must not reset xterm and replay the multi-megabyte capture on its main thread. Other modes may still re-pull `full=1` at the TOP, and pressing **Load full history** forces the request for any recoverably truncated session (`_maybeRefetchFullHistory`, 4s per-session gesture cooldown, in-flight + tab-switch guards, viewport position held across the replay); Shell full pulls are not retained in the tab cache, so the next switch stays bounded. Chunked replay enqueues 32 KiB pieces across safe yields, appends an xterm parse marker, then releases the live-output gate; output arriving after that release stays ordered behind the snapshot, while the marker callback supplies accurate parse timing without extending the pre-existing queued-event discard window. Live output is separately one-chunk-in-flight: xterm's callback releases each 32/64 KiB write before the next is submitted, keeping the remainder in the app queue where the 128 KiB cap can observe it instead of hiding an unbounded backlog in xterm's private WriteBuffer. While WebSocket owns terminal I/O, parallel SSE terminal/output-recovery events are discarded before JSON parsing; fallback recovery is single-flight per active session so backpressure cannot start overlapping reset+replay cycles. The route exposes capture/prepare totals in `Server-Timing`, while `[TERMINAL-PERF]` separates TTFB, body/JSON, reset+parse and total time for both selection and on-demand full pulls; parse completion is not a browser compositor/GPU paint measurement. The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`, `test/terminal-flush-budget.test.ts`.

 ### Terminal scrollback: strip flavors and wheel/touch forwarding

@@ -136,7 +136,7 @@ Worth knowing:
 - **Scrollback.** Agent/TUI sessions pull their entire tmux scrollback on first open.
  Shell sessions open from a bounded recent tail so a large transcript cannot stall tab
  switching; press **Load full history** to pull the rest explicitly. Ordinary Shell scrolling
-  stays within the bounded browser buffer so dragging upward remains responsive.
+  and automatic output recovery stay within the bounded browser buffer.
 - **Wheel and touch scrolling** are forwarded into Claude's own transcript on recent Claude
  versions, so the wheel scrolls the conversation rather than the terminal. `Shift+Wheel` is
  always local scrollback. Other CLIs scroll locally.
@@ -245,7 +245,11 @@ print_security_notice() {
            echo -e "  ${YELLOW}${BOLD}Security:${NC}"
            echo -e "    Codeman binds ${BOLD}127.0.0.1${NC} (this machine only) — no password needed by default."
            echo -e "    To reach it from another device, do ONE of:"
-            echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+            if check_tailscale; then
+                echo -e "      ${CYAN}•${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}   ${DIM}(Tailscale is installed here; HTTPS, recommended)${NC}, or"
+            else
+                echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+            fi
            echo -e "      ${CYAN}•${NC} ${CYAN}codeman web --host 0.0.0.0${NC}  AND set ${CYAN}CODEMAN_PASSWORD${NC}"
            echo -e "    A non-loopback bind without a password still starts, but warns loudly."
            echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
@@ -412,6 +416,27 @@ check_tmux() {
    command -v tmux &>/dev/null
 }

+# node-pty ships prebuilt binaries for darwin and win32 ONLY, so on Linux it is
+# always compiled from source during `npm install`. Without a toolchain that
+# fails deep inside node-gyp with `not found: make`, which reads like an npm bug
+# rather than a missing system package (issue: fresh Ubuntu 24 server install).
+# So the toolchain is checked up front, exactly like git and tmux.
+#
+# Returns a human-readable list of what is missing, empty when all present.
+missing_build_tools() {
+    local missing=""
+    command -v make &>/dev/null || missing="make"
+    if ! command -v c++ &>/dev/null && ! command -v g++ &>/dev/null && ! command -v clang++ &>/dev/null; then
+        missing="${missing:+$missing, }a C++ compiler (g++)"
+    fi
+    command -v python3 &>/dev/null || missing="${missing:+$missing, }python3"
+    printf '%s' "$missing"
+}
+
+check_build_tools() {
+    [[ -z "$(missing_build_tools)" ]]
+}
+
 check_claude() {
    # Check PATH first
    if command -v claude &>/dev/null; then
@@ -934,6 +959,50 @@ install_git_suse() {
    run_as_root zypper install -y git
 }

+# Build toolchain for node-pty's source compile (see missing_build_tools).
+install_buildtools_debian() {
+    info "Installing build tools via apt (build-essential, python3)..."
+    ensure_sudo
+    run_as_root apt-get update -qq
+    run_as_root apt-get install -y -qq build-essential python3
+}
+
+install_buildtools_fedora() {
+    info "Installing build tools (gcc, gcc-c++, make, python3)..."
+    ensure_sudo
+    if command -v dnf &>/dev/null; then
+        run_as_root dnf install -y gcc gcc-c++ make python3
+    else
+        run_as_root yum install -y gcc gcc-c++ make python3
+    fi
+}
+
+install_buildtools_arch() {
+    info "Installing build tools via pacman (base-devel, python)..."
+    ensure_sudo
+    run_as_root pacman -Sy --noconfirm base-devel python
+}
+
+install_buildtools_alpine() {
+    info "Installing build tools via apk (build-base, python3)..."
+    ensure_sudo
+    run_as_root apk add --no-cache build-base python3
+}
+
+install_buildtools_suse() {
+    info "Installing build tools via zypper..."
+    ensure_sudo
+    run_as_root zypper install -y gcc gcc-c++ make python3
+}
+
+install_buildtools_macos() {
+    # macOS normally never gets here: node-pty ships darwin prebuilds. Only a
+    # forced source build needs a compiler, and Xcode CLT is its only supplier.
+    info "Requesting Xcode Command Line Tools..."
+    xcode-select --install 2>/dev/null || true
+    die "Finish the Xcode Command Line Tools install in the dialog, then re-run this installer."
+}
+
 install_cloudflared_macos() {
    info "Installing cloudflared via Homebrew..."
    ensure_homebrew
@@ -1809,6 +1878,41 @@ setup_tailscale_access() {
    return 0
 }

+# A loopback install with Tailscale already connected but nothing fronting
+# Codeman is one command away from working remote access — and that is exactly
+# where a user lands when the first install died BEFORE the network-access
+# prompt (it runs after the build, so any build failure costs the network step
+# too) or when they finished a broken build by hand instead of re-running the
+# installer. Detect that state on re-run and offer the retrofit, rather than
+# leaving them to discover `install.sh tailscale` on their own. Never nags a
+# deliberate network bind, and never nags once a serve mapping already exists.
+maybe_offer_tailscale_repair() {
+    # A non-loopback bind already has network access; leave that choice alone.
+    if [[ "$EXISTING_FOUND" == "1" && -n "$EXISTING_HOST" && "$EXISTING_HOST" != "127.0.0.1" ]]; then
+        return 0
+    fi
+    check_tailscale || return 0
+    command -v node &>/dev/null || return 0
+    [[ "$(ts_status_field 's.BackendState')" == "Running" ]] || return 0
+    # Already fronting Codeman: nothing to repair.
+    [[ -z "$(detect_tailscale_serve_url)" ]] || return 0
+
+    echo ""
+    info "Tailscale is connected here, but no serve mapping fronts Codeman yet."
+    if [[ "$NONINTERACTIVE" == "1" ]] || ! has_tty; then
+        echo -e "  ${DIM}Enable HTTPS access from your tailnet with:${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}"
+        return 0
+    fi
+    if ! prompt_yes_no "Set up Tailscale HTTPS access now? (your tailnet is the login; no password needed)" "y"; then
+        echo -e "  ${DIM}Any time later:${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}"
+        return 0
+    fi
+    if setup_tailscale_access; then
+        verify_tailscale_access || true
+    fi
+    return 0
+}
+
 # `install.sh tailscale`: retrofit Tailscale access onto an existing install
 # (also the target of every "set it up later" hint above).
 setup_tailscale_subcommand() {
@@ -2061,6 +2165,29 @@ setup_tunnel_service() {
 # Installation Helpers
 # ============================================================================

+# npm install with an actionable message for the failure that actually happens
+# on a fresh Linux box: no toolchain, so node-pty cannot compile.
+npm_install_deps() {
+    if npm install --quiet --no-fund --no-audit 2>/dev/null; then
+        return 0
+    fi
+    if npm install --no-fund --no-audit; then
+        return 0
+    fi
+
+    error "npm install failed."
+    if [[ "$(detect_os)" == "linux" ]] && ! check_build_tools; then
+        error "Missing native build tools: $(missing_build_tools)"
+        error "node-pty has no Linux prebuilds, so it must compile from source."
+        error "Install them and re-run this installer:"
+        error "  Debian/Ubuntu:  sudo apt-get install -y build-essential python3"
+        error "  Fedora/RHEL:    sudo dnf install -y gcc gcc-c++ make python3"
+        error "  Arch:           sudo pacman -S --noconfirm base-devel python"
+        error "  Alpine:         sudo apk add build-base python3"
+    fi
+    exit 1
+}
+
 install_dependency() {
    local dep_name="$1"
    local os="$2"
@@ -2174,6 +2301,31 @@ main() {
        fi
    fi

+    # Native build toolchain. node-pty compiles from source on Linux, so this is
+    # a hard requirement there, not a nicety.
+    if [[ "$os" == "linux" ]]; then
+        info "Checking build tools (node-pty compiles from source on Linux)..."
+        local missing_tools
+        missing_tools="$(missing_build_tools)"
+        if [[ -z "$missing_tools" ]]; then
+            success "Build tools are installed"
+        else
+            warn "Missing build tools: $missing_tools"
+            headless_guard "install build tools (system package via sudo)"
+            if prompt_yes_no "Install the build tools now?"; then
+                install_dependency "buildtools" "$os" "$distro"
+                hash -r 2>/dev/null || true
+                missing_tools="$(missing_build_tools)"
+                if [[ -n "$missing_tools" ]]; then
+                    die "Build tools still missing after install: $missing_tools. Install them manually and re-run."
+                fi
+                success "Build tools installed"
+            else
+                die "A build toolchain (make, g++, python3) is required: node-pty has no Linux prebuilds and compiles from source."
+            fi
+        fi
+    fi
+
    # AI CLI (Codeman drives one of: Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi)
    local has_claude=false
    local has_opencode=false
@@ -2341,7 +2493,7 @@ main() {
    # ========================================================================

    info "Installing dependencies..."
-    npm install --quiet --no-fund --no-audit 2>/dev/null || npm install --no-fund --no-audit
+    npm_install_deps

    info "Building..."
    npm run build --quiet 2>/dev/null || npm run build
@@ -2637,7 +2789,7 @@ update() {

    git fetch --quiet origin
    git reset --hard "origin/$BRANCH" --quiet
-    npm install --quiet --no-fund --no-audit 2>/dev/null || npm install --no-fund --no-audit
+    npm_install_deps
    npm run build --quiet 2>/dev/null || npm run build
    date -u +%Y-%m-%dT%H:%M:%SZ > "$INSTALL_DIR/.install-complete"
    success "Updated to $(node -e "console.log(require('./package.json').version)")"
@@ -2674,6 +2826,10 @@ update() {
        BIND_ACK="$EXISTING_ACK"
    fi

+    # An update is the only place a half-configured install gets a second
+    # chance at remote access; the fresh-install path asks outright.
+    maybe_offer_tailscale_repair
+
    print_security_notice
 }

@@ -1,12 +1,12 @@
 {
  "name": "aicodeman",
-  "version": "1.23.0",
+  "version": "1.23.2",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "aicodeman",
-      "version": "1.23.0",
+      "version": "1.23.2",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "1.23.0",
+  "version": "1.23.2",
  "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
  "type": "module",
  "main": "dist/index.js",
@@ -1,5 +1,5 @@
 /**
- * @fileoverview Pure parsing + formatting of Claude Code statusline telemetry.
+ * @fileoverview Pure parsing + formatting of Claude and Codex plan telemetry.
 *
 * Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command`
 * on each render. On Pro/Max subscriptions that blob carries a `rate_limits`
@@ -15,7 +15,10 @@
 * Only those two windows exist (no Opus-weekly field). `rate_limits` is absent
 * before the first API response and for non-subscriber auth — both yield null.
 *
- * All functions are pure for testability. See `test/usage-telemetry.test.ts`.
+ * The Codex parser consumes the read-only `account/rateLimits/read` app-server
+ * response and selects only the main `codex` bucket, excluding model-specific
+ * buckets. All functions are pure for testability. See
+ * `test/usage-telemetry.test.ts` and `test/codex-plan-usage.test.ts`.
 *
 * @module usage-telemetry
 */
@@ -51,6 +54,22 @@ export interface RawStatuslinePayload {
  model?: { display_name?: string };
 }

+interface RawCodexRateLimitWindow {
+  usedPercent?: unknown;
+  windowDurationMins?: unknown;
+  resetsAt?: unknown;
+}
+
+interface RawCodexRateLimitSnapshot {
+  primary?: RawCodexRateLimitWindow | null;
+  secondary?: RawCodexRateLimitWindow | null;
+}
+
+interface RawCodexRateLimitsResponse {
+  rateLimits?: RawCodexRateLimitSnapshot | null;
+  rateLimitsByLimitId?: Record<string, RawCodexRateLimitSnapshot | null> | null;
+}
+
 function clampPct(n: number): number {
  if (!Number.isFinite(n)) return 0;
  return Math.max(0, Math.min(100, n));
@@ -88,6 +107,29 @@ export function parseStatusTelemetry(data: RawStatuslinePayload | undefined): St
  return t;
 }

+/** Normalize the main Codex app-server bucket into the chip's two known windows. */
+export function parseCodexRateLimitsResponse(value: unknown): StatusTelemetry | null {
+  if (!value || typeof value !== 'object') return null;
+  const response = value as RawCodexRateLimitsResponse;
+  const snapshot = response.rateLimitsByLimitId?.codex ?? response.rateLimits;
+  if (!snapshot || typeof snapshot !== 'object') return null;
+
+  const telemetry: StatusTelemetry = {};
+  for (const window of [snapshot.primary, snapshot.secondary]) {
+    if (!window || typeof window.usedPercent !== 'number' || !Number.isFinite(window.usedPercent)) continue;
+    if (window.windowDurationMins !== 300 && window.windowDurationMins !== 10_080) continue;
+    const resetsAt =
+      typeof window.resetsAt === 'number' && Number.isFinite(window.resetsAt) && window.resetsAt > 0
+        ? Math.round(window.resetsAt * 1000)
+        : 0;
+    const normalized = { usedPercentage: clampPct(window.usedPercent), resetAt: resetsAt };
+    if (window.windowDurationMins === 300) telemetry.fiveHour = normalized;
+    if (window.windowDurationMins === 10_080) telemetry.sevenDay = normalized;
+  }
+
+  return telemetry.fiveHour || telemetry.sevenDay ? telemetry : null;
+}
+
 /**
 * Current-session status for the in-terminal statusline footer. This is the
 * "status of the current session" the user sees in Claude's footer — distinct
@@ -9,7 +9,9 @@

 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
 import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
+import { parseCodexRateLimitsResponse, type StatusTelemetry } from '../usage-telemetry.js';

 /** Common directories where the Codex CLI binary may be installed */
 const CODEX_SEARCH_DIRS = [
@@ -21,7 +23,8 @@ const CODEX_SEARCH_DIRS = [
  join(homedir(), 'bin'), // User bin
 ];

-const codexResolver = createCliExecutableResolver({ binary: 'codex', searchDirs: CODEX_SEARCH_DIRS });
+const CODEX_BINARY = process.platform === 'win32' ? 'codex.exe' : 'codex';
+const codexResolver = createCliExecutableResolver({ binary: CODEX_BINARY, searchDirs: CODEX_SEARCH_DIRS });
 const CODEX_NOT_FOUND = 'Codex CLI not found. Install with: npm install -g @openai/codex';

 /**
@@ -35,6 +38,11 @@ export function resolveCodexDir(): string | null {
  return codexResolver.resolve()?.directory ?? null;
 }

+/** Absolute Codex executable path, for direct app-server requests. */
+export function resolveCodexBinaryPath(): string | null {
+  return codexResolver.resolve()?.binaryPath ?? null;
+}
+
 /**
 * Check if Codex CLI is available on the system.
 */
@@ -45,3 +53,80 @@ export function isCodexAvailable(): boolean {
 export function getCodexNotFoundMessage(): string {
  return formatCliNotFoundMessage(CODEX_NOT_FOUND, codexResolver.diagnostics());
 }
+
+type CodexRateLimitsRequest = (binaryPath: string, clientVersion: string) => Promise<unknown>;
+
+const APP_SERVER_TIMEOUT_MS = 10_000;
+const APP_SERVER_MAX_OUTPUT_BYTES = 256 * 1024;
+
+function requestCodexRateLimits(binaryPath: string, clientVersion: string): Promise<unknown> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let initialized = false;
+    let buffer = '';
+    const child = spawn(binaryPath, ['app-server', '--stdio'], {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    const timeout = setTimeout(() => finish(null), APP_SERVER_TIMEOUT_MS);
+
+    const finish = (value: unknown): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      child.stdin.end();
+      child.kill();
+      resolve(value);
+    };
+    const send = (message: unknown): void => {
+      if (!settled && child.stdin.writable) child.stdin.write(`${JSON.stringify(message)}\n`);
+    };
+    const handleLine = (line: string): void => {
+      if (!line.trim()) return;
+      let message: { id?: number; result?: unknown; error?: unknown };
+      try {
+        message = JSON.parse(line) as { id?: number; result?: unknown; error?: unknown };
+      } catch {
+        return;
+      }
+      if (message.id === 1) {
+        if (message.error) return finish(null);
+        if (!initialized) {
+          initialized = true;
+          send({ method: 'account/rateLimits/read', id: 2 });
+        }
+      } else if (message.id === 2) {
+        finish(message.error ? null : message.result);
+      }
+    };
+
+    child.on('error', () => finish(null));
+    child.on('close', () => finish(null));
+    child.stdin.on('error', () => finish(null));
+    child.stdout.on('data', (chunk: Buffer) => {
+      buffer += chunk.toString('utf8');
+      if (Buffer.byteLength(buffer) > APP_SERVER_MAX_OUTPUT_BYTES) return finish(null);
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() ?? '';
+      for (const line of lines) handleLine(line);
+    });
+
+    send({
+      method: 'initialize',
+      id: 1,
+      params: {
+        clientInfo: { name: 'codeman', title: 'Codeman', version: clientVersion },
+        capabilities: null,
+      },
+    });
+  });
+}
+
+/** Read the signed-in host account's main Codex limits without exposing credentials. */
+export async function readCodexPlanUsage(
+  binaryPath: string,
+  clientVersion: string,
+  request: CodexRateLimitsRequest = requestCodexRateLimits
+): Promise<StatusTelemetry | null> {
+  return parseCodexRateLimitsResponse(await request(binaryPath, clientVersion));
+}
@@ -37,7 +37,13 @@ export {
 } from './claude-cli-resolver.js';
 export { spawnPtyWithHelperRepair } from './node-pty-repair.js';
 export { resolveOpenCodeDir, getOpenCodeNotFoundMessage } from './opencode-cli-resolver.js';
-export { resolveCodexDir, isCodexAvailable, getCodexNotFoundMessage } from './codex-cli-resolver.js';
+export {
+  resolveCodexDir,
+  resolveCodexBinaryPath,
+  isCodexAvailable,
+  getCodexNotFoundMessage,
+  readCodexPlanUsage,
+} from './codex-cli-resolver.js';
 export { resolveGeminiDir, isGeminiAvailable, getGeminiNotFoundMessage } from './gemini-cli-resolver.js';
 export {
  resolveAntigravityDir,
@@ -1,10 +1,11 @@
 /**
 * @fileoverview Process-wide last-known plan-usage telemetry (account-global).
 *
- * The status-telemetry route writes the latest broadcast value here; the SSE
- * init snapshot (`getLightState`) replays it so the header "Plan Usage Limits"
- * chip shows immediately on a fresh page load / SSE reconnect — before any new
- * statusline render arrives, and without relying on per-browser localStorage.
+ * The Claude status-telemetry route and host Codex poll merge their latest
+ * values here. The SSE init snapshot (`getLightState`) replays the combined
+ * value so the header "Plan Usage Limits" chip shows immediately on a fresh
+ * page load / SSE reconnect — before either source emits another sample, and
+ * without relying on per-browser localStorage.
 *
 * Null until the first telemetry of the process; cleared naturally on restart.
 *
@@ -13,8 +14,15 @@

 let latest: Record<string, unknown> | null = null;

-export function setLatestPlanUsage(value: Record<string, unknown>): void {
-  latest = value;
+export function setLatestPlanUsage(value: Record<string, unknown>): Record<string, unknown> {
+  const codex = latest?.codex;
+  latest = { ...value, ...(codex !== undefined ? { codex } : {}) };
+  return latest;
+}
+
+export function setLatestCodexPlanUsage(value: object | null): Record<string, unknown> {
+  latest = { ...(latest ?? {}), codex: value };
+  return latest;
 }

 export function getLatestPlanUsage(): Record<string, unknown> | null {
@@ -679,12 +679,19 @@ class CodemanApp {
    // Terminal write batching with DEC 2026 sync support
    this.pendingWrites = [];
    this.writeFrameScheduled = false;
+    // xterm.write() parses asynchronously. Keep at most one live-output chunk
+    // inside xterm so its private WriteBuffer cannot bypass our 128KB cap.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
    this._wasAtBottomBeforeWrite = true; // Default to true for sticky scroll
    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;
+    // Single-flight token for terminal buffer recovery. The identity check also
+    // lets a session switch invalidate an older fetch without blocking the new tab.
+    this._terminalRefreshOwner = null;

    // Flicker filter state (buffers output after screen clears)
    this.flickerFilterBuffer = '';
@@ -1606,7 +1613,15 @@ class CodemanApp {
      this._sseHandlerWrappers = new Map();
      for (const [event, method] of _SSE_HANDLER_MAP) {
        const fn = this[method];
+        const wsOwnsTerminal =
+          method === '_onSSETerminal' ||
+          method === '_onSSENeedsRefresh' ||
+          method === '_onSSEClearTerminal';
        this._sseHandlerWrappers.set(event, (e) => {
+          // While WS owns terminal I/O, the parallel SSE stream is redundant.
+          // Drop it before JSON.parse so a busy terminal cannot turn duplicate
+          // SSE traffic/backpressure into another expensive buffer replay.
+          if (wsOwnsTerminal && this._wsReady) return;
          try {
            fn.call(this, e.data ? JSON.parse(e.data) : {});
          } catch (err) {
@@ -1853,18 +1868,18 @@ class CodemanApp {
    if (this.sessions.size === 0) this.stopSystemStatsPolling();
  }

-  // SSE wrappers — skip terminal events when WebSocket is delivering for this session.
+  // SSE wrappers — skip terminal events while WebSocket owns active terminal I/O.
  // WS handler calls the underlying _onSession* methods directly.
  _onSSETerminal(data) {
-    if (this._wsReady && this._wsSessionId === data.id) return;
+    if (this._wsReady) return;
    this._onSessionTerminal(data);
  }
  _onSSENeedsRefresh(data) {
-    if (this._wsReady && this._wsSessionId === data?.id) return;
+    if (this._wsReady) return;
    this._onSessionNeedsRefresh(data);
  }
  _onSSEClearTerminal(data) {
-    if (this._wsReady && this._wsSessionId === data?.id) return;
+    if (this._wsReady) return;
    this._onSessionClearTerminal(data);
  }

@@ -1872,15 +1887,15 @@ class CodemanApp {
    if (data.id === this.activeSessionId) {
      if (data.data.length > 32768) _crashDiag.log(`TERMINAL: ${(data.data.length/1024).toFixed(0)}KB`);

-      // Hard cap: track total bytes queued in render buffers (pendingWrites +
-      // flickerFilterBuffer). When rAF is throttled (tab
-      // backgrounded, GPU busy), data accumulates with no flush, reaching
-      // 889KB+ and freezing Chrome for minutes. Drop data beyond 128KB and
-      // schedule a buffer reload to recover the display once the burst subsides.
+      // Hard cap all app-owned render queues plus the one xterm chunk currently
+      // parsing. Check the incoming frame too; otherwise a single large frame can
+      // jump over the cap. Dropped data is recovered from the canonical buffer.
      const queued = (this.pendingWrites?.reduce((s, w) => s + w.length, 0) || 0)
-        + (this.flickerFilterBuffer?.length || 0);
-      if (queued > 131072) { // 128KB — drop to prevent accumulation
-        // Schedule a self-recovery: reload the full terminal buffer once the
+        + (this.flickerFilterBuffer?.length || 0)
+        + (this._loadBufferQueue?.reduce((s, w) => s + w.length, 0) || 0)
+        + (this._terminalWriteInFlightBytes || 0);
+      if (queued + data.data.length > 131072) { // 128KB — drop to prevent accumulation
+        // Schedule a self-recovery once the
        // queue drains (debounced to avoid hammering the API during sustained bursts).
        if (!this._clientDropRecoveryTimer) {
          this._clientDropRecoveryTimer = setTimeout(() => {
@@ -2357,33 +2372,38 @@ class CodemanApp {
    }
  }

-  async _onSessionNeedsRefresh() {
+  async _onSessionNeedsRefresh(event = {}) {
    // Server sends this after SSE backpressure clears — terminal data was dropped,
    // so reload the buffer to recover from any display corruption.
-    if (!this.activeSessionId || !this.terminal) return;
+    const sessionId = this.activeSessionId;
+    if (event?.id && event.id !== sessionId) return;
+    if (!sessionId || !this.terminal) return;
    // Skip if buffer load already in progress — avoids competing clear+rewrite cycles
    if (this._isLoadingBuffer) return;
-    const sessionId = this.activeSessionId;
+    if (this._terminalRefreshOwner?.sessionId === sessionId) return;
+    const refreshOwner = { sessionId };
+    this._terminalRefreshOwner = refreshOwner;
    try {
-      // Recovery should restore the WHOLE picture, so ask for full history
-      // rather than a tail. Measured on a 900-line shell pane: the tail rewrite
-      // replaced an 869-row buffer with 158 rows, so every backpressure refresh
-      // silently destroyed most of the scrollback it was meant to repair.
-      //
-      // A repaint-mode pane is the opposite case (tmux keeps ~one frame for it),
-      // so the full capture can be SMALLER than what xterm already holds. Reuse
-      // the same downgrade guard as the scroll-to-top re-pull and fall back to
-      // the historical tail there, leaving that case exactly as it was.
-      let res = await fetch(`/api/sessions/${sessionId}/terminal?full=1`);
+      // A shell can retain a multi-megabyte/100k-line tmux history. Automatic
+      // recovery stays bounded just like normal shell selection; only the
+      // explicit "Load full history" action is allowed to pay for a full replay.
+      // TUI modes still recover the whole picture, with the downgrade guard for
+      // repaint-mode panes whose tmux capture can be smaller than xterm's buffer.
+      const useFullHistory = this.sessions.get(sessionId)?.mode !== 'shell';
+      let res = await fetch(
+        useFullHistory
+          ? `/api/sessions/${sessionId}/terminal?full=1`
+          : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`
+      );
      let data = (await res.json())?.data ?? {};
-      if (data.terminalBuffer && this._replayWouldShrinkBuffer(data.terminalBuffer)) {
+      if (useFullHistory && data.terminalBuffer && this._replayWouldShrinkBuffer(data.terminalBuffer)) {
        res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
        data = (await res.json())?.data ?? {};
      }
      // Bail on a tab switch mid-fetch: writing here would paint this session's
      // history into the terminal the user is now looking at. The window is two
      // fetches wide in the fallback case, so this guard is not optional.
-      if (this.activeSessionId !== sessionId) return;
+      if (this.activeSessionId !== sessionId || this._terminalRefreshOwner !== refreshOwner) return;
      if (data.terminalBuffer) {
        // This refresh is SERVER-triggered, so a user quietly reading scrollback
        // did not ask for it and must not be dragged to the bottom by it (#259).
@@ -2413,6 +2433,8 @@ class CodemanApp {
      }
    } catch (err) {
      console.error('needsRefresh reload failed:', err);
+    } finally {
+      if (this._terminalRefreshOwner === refreshOwner) this._terminalRefreshOwner = null;
    }
  }

@@ -2575,8 +2597,8 @@ class CodemanApp {
    }
  }

-  // Claude plan usage limits (5-hour + weekly) — account-global, so the latest
-  // sample from any session drives the shared header chip.
+  // Claude + Codex plan usage limits — account-global, so the latest sample
+  // drives the shared header chip.
  _onSessionStatusTelemetry(data) {
    this.updatePlanUsageChip(data);
    // Persist last-known so the chip shows immediately on the next page load /
@@ -2603,9 +2625,6 @@ class CodemanApp {
    const chip = document.getElementById('planUsageChip');
    if (!chip || !data) return;
    const pct = (w) => (w && typeof w.usedPercentage === 'number' ? Math.round(w.usedPercentage) : null);
-    const five = pct(data.fiveHour);
-    const seven = pct(data.sevenDay);
-    if (five === null && seven === null) return;
    // Per-window color by how much is used up: green < 60%, yellow 60–84%, red ≥ 85%.
    const colorClass = (p) => (p >= 85 ? 'pu-red' : p >= 60 ? 'pu-yellow' : 'pu-green');
    // innerHTML here is XSS-safe ONLY because every interpolated value is a
@@ -2619,12 +2638,23 @@ class CodemanApp {
      if (!Number.isFinite(n)) return '';
      return `<span class="pu-win"><span class="pu-label">${label}</span><span class="pu-val ${colorClass(n)}">${n}%</span></span>`;
    };
-    chip.innerHTML = [seg('5h', five), seg('7d', seven)].filter(Boolean).join('<span class="pu-sep">·</span>');
+    const row = (provider, usage) => {
+      const windows = [seg('5h', pct(usage?.fiveHour)), seg('7d', pct(usage?.sevenDay))].filter(Boolean);
+      if (!windows.length) return '';
+      return `<span class="pu-row"><span class="pu-provider">${provider}</span><span class="pu-windows">${windows.join('<span class="pu-sep">·</span>')}</span></span>`;
+    };
+    const rows = [row('Claude', data), row('Codex', data.codex)].filter(Boolean);
+    chip.innerHTML = rows.length ? rows.join('') : '—';
    const resetStr = (w) => (w && w.resetAt ? new Date(w.resetAt).toLocaleString() : '—');
-    chip.title =
-      `Claude plan usage\n` +
-      `5-hour limit: ${five ?? '—'}% used (resets ${resetStr(data.fiveHour)})\n` +
-      `Weekly limit: ${seven ?? '—'}% used (resets ${resetStr(data.sevenDay)})`;
+    const details = (provider, usage) => {
+      const lines = [];
+      const five = pct(usage?.fiveHour);
+      const seven = pct(usage?.sevenDay);
+      if (five !== null) lines.push(`5-hour limit: ${five}% used (resets ${resetStr(usage.fiveHour)})`);
+      if (seven !== null) lines.push(`Weekly limit: ${seven}% used (resets ${resetStr(usage.sevenDay)})`);
+      return lines.length ? `${provider} plan usage\n${lines.join('\n')}` : '';
+    };
+    chip.title = [details('Claude', data), details('Codex', data.codex)].filter(Boolean).join('\n\n') || 'Plan usage limits';
  }

  // Scheduled runs
@@ -3466,11 +3496,21 @@ class CodemanApp {
    this.flickerFilterActive = false;
    // Clear pending terminal writes
    this._clearTimer('syncWaitTimeout');
+    this._clearTimer('_clientDropRecoveryTimer');
    this.pendingWrites = [];
    this.writeFrameScheduled = false;
+    // Release the one-chunk-in-flight gate with the rest of the write queue.
+    // flushPendingWrites() early-returns while this is set, so a reset that
+    // cleared everything EXCEPT this flag would leave live output permanently
+    // stalled if xterm's parse callback never lands (disposed terminal, or a
+    // throw inside the async parse). A late callback is harmless: it clears an
+    // already-clear flag and schedules a flush.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
    this._isLoadingBuffer = false;
    this._loadBufferQueue = null;
    this._bufferLoadOwner = null;
+    this._terminalRefreshOwner = 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
@@ -5334,11 +5374,20 @@ class CodemanApp {
    this._tabCompletionBaseText = null;
    this._clearTimer('_tabCompletionFallback');
    this._clearTimer('_clientDropRecoveryTimer');
+    this._terminalRefreshOwner = null;

    // Clean up pending terminal writes to prevent old session data from appearing in new session
    this._clearTimer('syncWaitTimeout');
    this.pendingWrites = [];
    this.writeFrameScheduled = false;
+    // Release the one-chunk-in-flight gate with the rest of the write queue.
+    // flushPendingWrites() early-returns while this is set, so a reset that
+    // cleared everything EXCEPT this flag would leave live output permanently
+    // stalled if xterm's parse callback never lands (disposed terminal, or a
+    // throw inside the async parse). A late callback is harmless: it clears an
+    // already-clear flag and schedules a flush.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
    this._isLoadingBuffer = false;
    this._loadBufferQueue = null;
    this._bufferLoadOwner = null;
@@ -5652,8 +5701,11 @@ class CodemanApp {
      this._clearTimer('syncWaitTimeout');
      this.pendingWrites = [];
      this.writeFrameScheduled = false;
+      this._terminalWriteInFlight = false;
+      this._terminalWriteInFlightBytes = 0;
      this._isLoadingBuffer = false;
      this._loadBufferQueue = null;
+      this._terminalRefreshOwner = null;
      this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
      this.activeSessionId = null;
    }
@@ -5684,6 +5736,7 @@ class CodemanApp {

    this._cleanupPreviousSession(sessionId);
    this.activeSessionId = sessionId;
+    this._activateFileBrowserSession?.(sessionId);
    // Repaint the partial-history banner for the tab being switched TO. The
    // replay paths refresh it when their fetch lands; without this the previous
    // session's notice stays on screen until then (#258).
@@ -192,7 +192,7 @@
        <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
        <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
        <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
-        <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
+        <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude and Codex plan usage limits">—</div>
        <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>
          <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
@@ -2980,54 +2980,423 @@ Object.assign(CodemanApp.prototype, {
    btn.setAttribute('aria-label', label);
  },

+  _ensureFileBrowserState() {
+    if (!this._fileBrowserState) {
+      const ownerSessionId = this.activeSessionId || null;
+      const showHidden = this.fileBrowserShowHidden === true;
+      this._fileBrowserState = {
+        treeEpoch: 0,
+        searchEpoch: 0,
+        ownerSessionId,
+        view: 'normal',
+        normalState: this.fileBrowserData
+          ? { sessionId: ownerSessionId, showHidden, treeEpoch: 0, phase: 'ready', data: this.fileBrowserData }
+          : null,
+        treeInFlight: null,
+        inFlight: null,
+        matches: [],
+        deferredDirectoryTarget: null,
+        filter: typeof this.fileBrowserFilter === 'string' ? this.fileBrowserFilter : '',
+      };
+    }
+    return this._fileBrowserState;
+  },
+
+  _activateFileBrowserSession(sessionId) {
+    if (!sessionId) return;
+
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.treeEpoch++;
+    state.ownerSessionId = sessionId;
+    state.treeInFlight = null;
+    state.inFlight = null;
+    state.normalState = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.filter = '';
+    state.view = 'normal';
+    this.fileBrowserData = null;
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs?.clear?.();
+    this.fileBrowserAllExpanded = false;
+
+    const searchInput = this.$?.('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+    const expandBtn = this.$?.('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+
+    const panel = this.$?.('fileBrowserPanel');
+    const treeEl = this.$?.('fileBrowserTree');
+    const statusEl = this.$?.('fileBrowserStatus');
+    const visible = panel?.classList.contains('visible') === true;
+    if (treeEl) {
+      treeEl.innerHTML = visible
+        ? `<div class="file-browser-loading">${escapeHtml('Loading files...')}</div>`
+        : '';
+    }
+    if (statusEl) statusEl.textContent = visible ? 'Loading files...' : '';
+
+    if (visible) {
+      const load = this.loadFileBrowser?.(sessionId);
+      load?.catch?.(() => {});
+    }
+  },
+
+  _resetFileBrowserForHide() {
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.treeEpoch++;
+    state.treeInFlight = null;
+    state.inFlight = null;
+    state.normalState = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.filter = '';
+    state.view = 'normal';
+    this.fileBrowserData = null;
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs?.clear?.();
+    this.fileBrowserAllExpanded = false;
+
+    const searchInput = this.$?.('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+    const expandBtn = this.$?.('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+    const treeEl = this.$?.('fileBrowserTree');
+    if (treeEl) treeEl.innerHTML = '';
+    const statusEl = this.$?.('fileBrowserStatus');
+    if (statusEl) statusEl.textContent = '';
+  },
+
+  _setFileBrowserExpandDisabled(disabled) {
+    const btn = this.$('fileBrowserExpandBtn');
+    if (btn) btn.disabled = disabled;
+  },
+
+  _hasFileBrowserQuery() {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const inputValue = typeof input?.value === 'string' ? input.value : '';
+    const filterValue = typeof state.filter === 'string' ? state.filter : '';
+    return inputValue.trim() !== '' || filterValue.trim() !== '';
+  },
+
+  _syncFileBrowserExpandBtn() {
+    this._setFileBrowserExpandDisabled(this._hasFileBrowserQuery());
+  },
+
+  _renderFileBrowserNormalStatus(data, showHidden) {
+    const statusEl = this.$('fileBrowserStatus');
+    if (!statusEl || !data) return;
+    const { totalFiles, totalDirectories, truncated } = data;
+    statusEl.textContent = `${totalFiles} files, ${totalDirectories} dirs${truncated ? ' (truncated)' : ''}${showHidden ? ' · hidden shown' : ''}`;
+  },
+
+  _isFileBrowserNormalCompatible(candidate, sessionId, showHidden, treeEpoch) {
+    return (
+      candidate?.sessionId === sessionId &&
+      candidate.showHidden === showHidden &&
+      candidate.treeEpoch === treeEpoch
+    );
+  },
+
+  _isFileBrowserTreeContextCurrent(request, requireCurrentRecord = false) {
+    const state = this._ensureFileBrowserState();
+    return (
+      (!requireCurrentRecord || state.treeInFlight === request) &&
+      state.ownerSessionId === request.sessionId &&
+      state.treeEpoch === request.treeEpoch &&
+      (this.fileBrowserShowHidden === true) === request.showHidden
+    );
+  },
+
+  _canRenderFileBrowserNormal(normalState) {
+    const state = this._ensureFileBrowserState();
+    return (
+      state.view === 'normal' &&
+      this.activeSessionId === normalState?.sessionId &&
+      this._isFileBrowserNormalCompatible(
+        normalState,
+        state.ownerSessionId,
+        this.fileBrowserShowHidden === true,
+        state.treeEpoch,
+      ) &&
+      this.$('fileBrowserPanel')?.classList.contains('visible') === true
+    );
+  },
+
+  _renderFileBrowserNormalState(normalState) {
+    if (!normalState || !this._canRenderFileBrowserNormal(normalState)) return;
+    const treeEl = this.$('fileBrowserTree');
+    const statusEl = this.$('fileBrowserStatus');
+    if (!treeEl) return;
+
+    if (normalState.phase === 'loading') {
+      this.fileBrowserData = null;
+      treeEl.innerHTML = `<div class="file-browser-loading">${escapeHtml('Loading files...')}</div>`;
+      if (statusEl) statusEl.textContent = 'Loading files...';
+      return;
+    }
+
+    if (normalState.phase === 'error') {
+      this.fileBrowserData = null;
+      const detail = normalState.error && normalState.error !== 'Failed to load files'
+        ? `: ${normalState.error}`
+        : '';
+      const message = `Failed to load files${detail}`;
+      treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+      if (statusEl) statusEl.textContent = message;
+      return;
+    }
+
+    if (normalState.phase !== 'ready') return;
+    this.fileBrowserData = normalState.data;
+    this._syncFileBrowserExpandBtn();
+    this.renderFileBrowserTree(normalState.sessionId);
+    this._renderFileBrowserNormalStatus(normalState.data, normalState.showHidden);
+  },
+
+  _validateFileBrowserTreeEnvelope(result) {
+    if (!result || typeof result !== 'object' || result.success !== true) return null;
+    const data = result.data;
+    if (!data || typeof data !== 'object' || !Array.isArray(data.tree)) return null;
+    if (data.mode === 'search') return null;
+    if (
+      typeof data.totalFiles !== 'number' ||
+      !Number.isFinite(data.totalFiles) ||
+      data.totalFiles < 0 ||
+      typeof data.totalDirectories !== 'number' ||
+      !Number.isFinite(data.totalDirectories) ||
+      data.totalDirectories < 0 ||
+      typeof data.truncated !== 'boolean'
+    ) {
+      return null;
+    }
+
+    const validNodes = nodes => nodes.every(node => {
+      if (!node || typeof node !== 'object') return false;
+      if (typeof node.name !== 'string' || typeof node.path !== 'string') return false;
+      if (node.type !== 'file' && node.type !== 'directory') return false;
+      if (node.size !== undefined && (typeof node.size !== 'number' || !Number.isFinite(node.size))) return false;
+      if (node.extension !== undefined && typeof node.extension !== 'string') return false;
+      if (node.children !== undefined && (!Array.isArray(node.children) || !validNodes(node.children))) return false;
+      return true;
+    });
+
+    return validNodes(data.tree) ? data : null;
+  },
+
+  _normalizeFileBrowserTreeError(error) {
+    return typeof error?.message === 'string' && error.message ? error.message : 'Failed to load files';
+  },
+
+  _validateFileBrowserSearchEnvelope(result) {
+    if (!result || typeof result !== 'object' || result.success !== true) return null;
+    const data = result.data;
+    if (!data || typeof data !== 'object' || data.mode !== 'search' || !Array.isArray(data.matches)) return null;
+    if (typeof data.truncated !== 'boolean') return null;
+    if (
+      data.matchCount !== undefined &&
+      (typeof data.matchCount !== 'number' || !Number.isFinite(data.matchCount) || data.matchCount < 0)
+    ) {
+      return null;
+    }
+    for (const match of data.matches) {
+      if (!match || typeof match !== 'object') return null;
+      if (typeof match.name !== 'string' || typeof match.path !== 'string') return null;
+      if (match.type !== 'file' && match.type !== 'directory') return null;
+      if (match.size !== undefined && (typeof match.size !== 'number' || !Number.isFinite(match.size))) return null;
+      if (match.extension !== undefined && typeof match.extension !== 'string') return null;
+    }
+    return data;
+  },
+
+  _canRenderFileBrowserSearch(request) {
+    const state = this._ensureFileBrowserState();
+    const panel = this.$('fileBrowserPanel');
+    return (
+      state.searchEpoch === request.epoch &&
+      state.ownerSessionId === request.ownerSessionId &&
+      this.activeSessionId === request.ownerSessionId &&
+      (this.fileBrowserShowHidden === true) === request.showHidden &&
+      state.filter === request.rawInput &&
+      panel?.classList.contains('visible') === true
+    );
+  },
+
+  _renderFileBrowserSearchError() {
+    const treeEl = this.$('fileBrowserTree');
+    const statusEl = this.$('fileBrowserStatus');
+    const message = 'Search failed';
+    if (treeEl) treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+    if (statusEl) statusEl.textContent = message;
+  },
+
+  _canContinueFileBrowserHiddenReload(continuation, normalState) {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const currentInput = typeof input?.value === 'string' ? input.value : state.filter;
+    return (
+      state.view === 'normal' &&
+      state.searchEpoch === continuation.searchEpoch &&
+      state.treeEpoch === continuation.treeEpoch &&
+      state.ownerSessionId === continuation.ownerSessionId &&
+      this.activeSessionId === continuation.ownerSessionId &&
+      (this.fileBrowserShowHidden === true) === continuation.showHidden &&
+      state.filter === continuation.rawInput &&
+      currentInput === continuation.rawInput &&
+      currentInput.trim() === continuation.query &&
+      this.$?.('fileBrowserPanel')?.classList.contains('visible') === true &&
+      normalState?.phase === 'ready' &&
+      this._isFileBrowserNormalCompatible(
+        normalState,
+        continuation.ownerSessionId,
+        continuation.showHidden,
+        continuation.treeEpoch,
+      )
+    );
+  },
+
  async toggleFileBrowserHidden() {
+    const state = this._ensureFileBrowserState();
+    const rawInput = typeof state.filter === 'string' ? state.filter : '';
+    const query = rawInput.trim();
    this.fileBrowserShowHidden = !this.fileBrowserShowHidden;
    try {
      localStorage.setItem(FILE_BROWSER_SHOW_HIDDEN_KEY, this.fileBrowserShowHidden ? '1' : '0');
    } catch {}
    this._syncFileBrowserHiddenBtn();
+
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.inFlight = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.normalState = null;
+    this.fileBrowserData = null;
+    if (query.length <= 256) state.view = 'normal';
+    this._syncFileBrowserExpandBtn();
+
    // Expanded-directory state is deliberately preserved so toggling does not
    // collapse the tree the user just navigated.
-    if (this.activeSessionId) await this.loadFileBrowser(this.activeSessionId);
-  },
+    const ownerSessionId = state.ownerSessionId || this.activeSessionId;
+    if (!ownerSessionId || this.activeSessionId !== ownerSessionId) return;

-  async loadFileBrowser(sessionId) {
-    if (!sessionId) return;
+    const searchEpoch = state.searchEpoch;
+    const showHidden = this.fileBrowserShowHidden === true;
+    const load = this.loadFileBrowser(ownerSessionId, { force: true });
+    const treeEpoch = state.treeEpoch;
+    if (!load?.then) return;
+    await load;

-    const treeEl = this.$('fileBrowserTree');
-    const statusEl = this.$('fileBrowserStatus');
-    this._syncFileBrowserHiddenBtn();
-    if (!treeEl) return;
-
-    // Show loading state
-    treeEl.innerHTML = '<div class="file-browser-loading">Loading files...</div>';
-
-    try {
-      const showHidden = this.fileBrowserShowHidden === true;
-      const res = await fetch(`/api/sessions/${sessionId}/files?depth=5&showHidden=${showHidden}`);
-      if (!res.ok) throw new Error('Failed to load files');
-
-      const result = await res.json();
-      if (!result.success) throw new Error(result.error || 'Failed to load files');
-
-      this.fileBrowserData = result.data;
-      this.renderFileBrowserTree();
-
-      // Update status
-      if (statusEl) {
-        const { totalFiles, totalDirectories, truncated } = result.data;
-        statusEl.textContent = `${totalFiles} files, ${totalDirectories} dirs${truncated ? ' (truncated)' : ''}${showHidden ? ' · hidden shown' : ''}`;
-      }
-    } catch (err) {
-      console.error('Failed to load file browser:', err);
-      treeEl.innerHTML = `<div class="file-browser-empty">Failed to load files: ${escapeHtml(err.message)}</div>`;
+    if (!query || query.length > 256) return;
+    const continuation = { ownerSessionId, showHidden, treeEpoch, searchEpoch, rawInput, query };
+    if (this._canContinueFileBrowserHiddenReload(continuation, state.normalState)) {
+      this.filterFileBrowser(rawInput);
    }
  },

-  renderFileBrowserTree() {
+  loadFileBrowser(sessionId, { force = false } = {}) {
+    if (!sessionId) return undefined;
+
+    const state = this._ensureFileBrowserState();
+    const treeEl = this.$('fileBrowserTree');
+    this._syncFileBrowserHiddenBtn();
+    if (!treeEl) return undefined;
+    if (!state.ownerSessionId) state.ownerSessionId = sessionId;
+    if (state.ownerSessionId !== sessionId) return undefined;
+
+    if (force) state.treeEpoch++;
+    const showHidden = this.fileBrowserShowHidden === true;
+    const treeEpoch = state.treeEpoch;
+    const inFlight = state.treeInFlight;
+    if (
+      !force &&
+      this._isFileBrowserNormalCompatible(inFlight, sessionId, showHidden, treeEpoch)
+    ) {
+      return inFlight.promise;
+    }
+
+    const settled = state.normalState;
+    if (
+      !force &&
+      this._isFileBrowserNormalCompatible(settled, sessionId, showHidden, treeEpoch) &&
+      (settled.phase === 'ready' || settled.phase === 'error')
+    ) {
+      if (settled.phase === 'ready') this.fileBrowserData = settled.data;
+      this._renderFileBrowserNormalState(settled);
+      return Promise.resolve(settled);
+    }
+
+    const loadingState = { sessionId, showHidden, treeEpoch, phase: 'loading' };
+    state.normalState = loadingState;
+    this.fileBrowserData = null;
+    this._renderFileBrowserNormalState(loadingState);
+
+    const record = { sessionId, showHidden, treeEpoch, promise: null };
+    const request = (async () => {
+      try {
+        const res = await fetch(
+          `/api/sessions/${encodeURIComponent(sessionId)}/files?depth=5&showHidden=${showHidden}`,
+        );
+        if (!res.ok) throw new Error('Failed to load files');
+        const result = await res.json();
+        const data = this._validateFileBrowserTreeEnvelope(result);
+        if (!data) {
+          const detail = result && typeof result === 'object' && typeof result.error === 'string'
+            ? result.error
+            : 'Failed to load files';
+          throw new Error(detail);
+        }
+        if (!this._isFileBrowserTreeContextCurrent(record, true)) return;
+
+        const nextNormalState = { sessionId, showHidden, treeEpoch, phase: 'ready', data };
+        state.normalState = nextNormalState;
+        this.fileBrowserData = data;
+        const deferredRendered = this._completeDeferredFileBrowserDirectory?.(nextNormalState) === true;
+        if (!deferredRendered) this._renderFileBrowserNormalState(nextNormalState);
+      } catch (error) {
+        if (!this._isFileBrowserTreeContextCurrent(record, true)) return;
+        const nextNormalState = {
+          sessionId,
+          showHidden,
+          treeEpoch,
+          phase: 'error',
+          error: this._normalizeFileBrowserTreeError(error),
+        };
+        state.normalState = nextNormalState;
+        this.fileBrowserData = null;
+        this._completeDeferredFileBrowserDirectory?.(nextNormalState);
+        console.error('Failed to load file browser:', error);
+        this._renderFileBrowserNormalState(nextNormalState);
+      }
+    })();
+    record.promise = request.finally(() => {
+      if (state.treeInFlight === record) state.treeInFlight = null;
+    });
+    state.treeInFlight = record;
+    return record.promise;
+  },
+
+  renderFileBrowserTree(ownerSessionId) {
    const treeEl = this.$('fileBrowserTree');
    if (!treeEl || !this.fileBrowserData) return;

+    const state = this._ensureFileBrowserState();
+    const owner = ownerSessionId || state.normalState?.sessionId || state.ownerSessionId || this.activeSessionId;
+    if (!owner) return;
+
    const { tree } = this.fileBrowserData;
    if (!tree || tree.length === 0) {
      treeEl.innerHTML = '<div class="file-browser-empty">No files found</div>';
@@ -3035,21 +3404,10 @@ Object.assign(CodemanApp.prototype, {
    }

    const html = [];
-    const filter = this.fileBrowserFilter.toLowerCase();

    const renderNode = (node, depth) => {
      const isDir = node.type === 'directory';
      const isExpanded = this.fileBrowserExpandedDirs.has(node.path);
-      const matchesFilter = !filter || node.name.toLowerCase().includes(filter);
-
-      // For directories, check if any children match
-      let hasMatchingChildren = false;
-      if (isDir && filter && node.children) {
-        hasMatchingChildren = this.hasMatchingChild(node, filter);
-      }
-
-      const shouldShow = matchesFilter || hasMatchingChildren;
-      const hiddenClass = !shouldShow && filter ? ' hidden-by-filter' : '';

      const icon = isDir
        ? (isExpanded ? '\uD83D\uDCC2' : '\uD83D\uDCC1')
@@ -3066,11 +3424,11 @@ Object.assign(CodemanApp.prototype, {
      const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name';

      const downloadBtn = !isDir
-        ? `<a class="file-tree-download" href="/api/sessions/${this.activeSessionId}/file-raw?path=${encodeURIComponent(node.path)}&download=true" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
+        ? `<a class="file-tree-download" href="${escapeHtml(`/api/sessions/${encodeURIComponent(owner)}/file-raw?path=${encodeURIComponent(node.path)}&download=true`)}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
        : '';

      html.push(`
-        <div class="file-tree-item${hiddenClass}" data-path="${escapeHtml(node.path)}" data-type="${node.type}" data-depth="${depth}">
+        <div class="file-tree-item" data-path="${escapeHtml(node.path)}" data-type="${escapeHtml(node.type)}" data-depth="${depth}">
          ${expandIcon}
          <span class="file-tree-icon">${icon}</span>
          <span class="${nameClass}">${escapeHtml(node.name)}</span>
@@ -3102,21 +3460,12 @@ Object.assign(CodemanApp.prototype, {
        if (type === 'directory') {
          this.toggleFileBrowserFolder(path);
        } else {
-          this.openFilePreview(path);
+          this.openFilePreview(path, owner);
        }
      });
    });
  },

-  hasMatchingChild(node, filter) {
-    if (!node.children) return false;
-    for (const child of node.children) {
-      if (child.name.toLowerCase().includes(filter)) return true;
-      if (child.type === 'directory' && this.hasMatchingChild(child, filter)) return true;
-    }
-    return false;
-  },
-
  toggleFileBrowserFolder(path) {
    if (this.fileBrowserExpandedDirs.has(path)) {
      this.fileBrowserExpandedDirs.delete(path);
@@ -3127,12 +3476,291 @@ Object.assign(CodemanApp.prototype, {
  },

  filterFileBrowser(value) {
-    this.fileBrowserFilter = value;
-    // Auto-expand all if filtering
-    if (value) {
-      this.expandAllDirectories(this.fileBrowserData?.tree || []);
+    const state = this._ensureFileBrowserState();
+    const rawInput = String(value ?? '');
+    const query = rawInput.trim();
+    state.searchEpoch++;
+    state.filter = rawInput;
+    state.deferredDirectoryTarget = null;
+    this.fileBrowserFilter = rawInput;
+    this._syncFileBrowserExpandBtn();
+
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
    }
-    this.renderFileBrowserTree();
+    state.inFlight = null;
+
+    if (!state.ownerSessionId && this.activeSessionId) state.ownerSessionId = this.activeSessionId;
+    const ownerSessionId = state.ownerSessionId || null;
+    if (!this.activeSessionId || !ownerSessionId || this.activeSessionId !== ownerSessionId) return;
+    if (!query) {
+      state.view = 'normal';
+      state.matches = [];
+      this._syncFileBrowserExpandBtn();
+      const normal = state.normalState;
+      if (
+        ownerSessionId &&
+        this._isFileBrowserNormalCompatible(
+          normal,
+          ownerSessionId,
+          this.fileBrowserShowHidden === true,
+          state.treeEpoch,
+        )
+      ) {
+        this._renderFileBrowserNormalState(normal);
+      }
+      return;
+    }
+
+    if (query.length > 256) {
+      const message = 'Search queries are limited to 256 characters';
+      state.view = 'query-error';
+      state.matches = [];
+      this._syncFileBrowserExpandBtn();
+      const treeEl = this.$('fileBrowserTree');
+      const statusEl = this.$('fileBrowserStatus');
+      if (treeEl) treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+      if (statusEl) statusEl.textContent = message;
+      return;
+    }
+
+    const panel = this.$('fileBrowserPanel');
+    const treeEl = this.$('fileBrowserTree');
+    if (!ownerSessionId || !panel || !treeEl) return;
+
+    const request = {
+      epoch: state.searchEpoch,
+      treeEpoch: state.treeEpoch,
+      ownerSessionId,
+      showHidden: this.fileBrowserShowHidden === true,
+      rawInput,
+      query,
+      timer: null,
+    };
+    state.view = 'search-pending';
+    state.matches = [];
+    state.inFlight = request;
+    this._syncFileBrowserExpandBtn();
+    treeEl.innerHTML = `<div class="file-browser-loading">${escapeHtml('Searching...')}</div>`;
+    const statusEl = this.$('fileBrowserStatus');
+    if (statusEl) statusEl.textContent = 'Searching...';
+
+    request.timer = setTimeout(async () => {
+      request.timer = null;
+      try {
+        const res = await fetch(
+          `/api/sessions/${encodeURIComponent(ownerSessionId)}/files?depth=5&showHidden=${request.showHidden}&q=${encodeURIComponent(query)}`,
+        );
+        if (!res.ok) throw new Error('Search failed');
+        const result = await res.json();
+        const data = this._validateFileBrowserSearchEnvelope(result);
+        if (!data) throw new Error('Search failed');
+        const canRender = this._canRenderFileBrowserSearch(request);
+        if (state.inFlight === request) state.inFlight = null;
+        if (!canRender) return;
+        state.view = 'search-results';
+        state.matches = data.matches;
+        this._renderFileBrowserSearchResults(data.matches, ownerSessionId, data);
+      } catch (err) {
+        const canRender = this._canRenderFileBrowserSearch(request);
+        if (state.inFlight === request) state.inFlight = null;
+        if (!canRender) return;
+        console.error('Failed to search file browser:', err);
+        state.view = 'search-error';
+        state.matches = [];
+        this._renderFileBrowserSearchError();
+      }
+    }, 250);
+  },
+
+  _renderFileBrowserSearchResults(matches, ownerSessionId, data) {
+    const treeEl = this.$('fileBrowserTree');
+    if (!treeEl || !ownerSessionId) return;
+    const state = this._ensureFileBrowserState();
+    const searchContext = {
+      ownerSessionId,
+      showHidden: this.fileBrowserShowHidden === true,
+      treeEpoch: state.treeEpoch,
+      searchEpoch: state.searchEpoch,
+      rawInput: state.filter,
+      query: state.filter.trim(),
+      view: state.view,
+    };
+    if (matches.length === 0) {
+      treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml('No matches')}</div>`;
+    } else {
+      const ownerPath = encodeURIComponent(ownerSessionId);
+      treeEl.innerHTML = matches
+        .map(match => {
+          const isDir = match.type === 'directory';
+          const icon = isDir ? '📁' : this.getFileIcon(match.extension || '');
+          const sizeStr = !isDir && match.size !== undefined
+            ? `<span class="file-tree-size">${this.formatFileSize(match.size)}</span>`
+            : '';
+          const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name';
+          const downloadBtn = !isDir
+            ? `<a class="file-tree-download" href="${escapeHtml(`/api/sessions/${ownerPath}/file-raw?path=${encodeURIComponent(match.path)}&download=true`)}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
+            : '';
+          return `
+            <div class="file-tree-item" data-path="${escapeHtml(match.path)}" data-type="${escapeHtml(match.type)}" data-owner="${escapeHtml(ownerSessionId)}">
+              <span class="file-tree-expand"></span>
+              <span class="file-tree-icon">${icon}</span>
+              <span class="${nameClass}">${escapeHtml(match.name)}</span>
+              ${sizeStr}
+              ${downloadBtn}
+            </div>
+          `;
+        })
+        .join('');
+    }
+
+    treeEl.querySelectorAll('.file-tree-item').forEach(item => {
+      item.addEventListener('click', () => {
+        const path = item.dataset.path;
+        if (item.dataset.type === 'directory') {
+          this._openFileBrowserSearchDirectory({ ...searchContext, path });
+        } else {
+          this.openFilePreview(path, ownerSessionId);
+        }
+      });
+    });
+
+    const statusEl = this.$('fileBrowserStatus');
+    if (statusEl) {
+      const count = data.matchCount === undefined ? matches.length : data.matchCount;
+      statusEl.textContent = `${count} ${count === 1 ? 'match' : 'matches'}${data.truncated ? ' (truncated)' : ''}`;
+    }
+  },
+
+  _findFileBrowserDirectory(nodes, targetPath, ancestors = []) {
+    if (!Array.isArray(nodes)) return null;
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue;
+      if (node.type === 'directory' && node.path === targetPath) {
+        return { target: node, ancestors: [...ancestors] };
+      }
+      if (node.type !== 'directory' || !Array.isArray(node.children)) continue;
+      const found = this._findFileBrowserDirectory(node.children, targetPath, [...ancestors, node.path]);
+      if (found) return found;
+    }
+    return null;
+  },
+
+  _isFileBrowserDirectoryContextCurrent(target) {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const currentInput = typeof input?.value === 'string' ? input.value : state.filter;
+    return (
+      target &&
+      state.ownerSessionId === target.ownerSessionId &&
+      this.activeSessionId === target.ownerSessionId &&
+      state.treeEpoch === target.treeEpoch &&
+      state.searchEpoch === target.searchEpoch &&
+      (this.fileBrowserShowHidden === true) === target.showHidden &&
+      state.filter === target.rawInput &&
+      currentInput === target.rawInput &&
+      currentInput.trim() === target.query &&
+      state.view === target.view &&
+      this.$?.('fileBrowserPanel')?.classList.contains('visible') === true
+    );
+  },
+
+  _promptFileBrowserDirectoryReload() {
+    this.showToast?.('Reload files before opening this folder', 'info');
+  },
+
+  _openFileBrowserSearchDirectory(target) {
+    if (!this._isFileBrowserDirectoryContextCurrent(target)) return;
+    const state = this._ensureFileBrowserState();
+    const normalState = state.normalState;
+    if (
+      !this._isFileBrowserNormalCompatible(
+        normalState,
+        target.ownerSessionId,
+        target.showHidden,
+        target.treeEpoch,
+      )
+    ) {
+      state.deferredDirectoryTarget = null;
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+
+    if (normalState.phase === 'loading') {
+      state.deferredDirectoryTarget = { ...target };
+      return;
+    }
+
+    state.deferredDirectoryTarget = null;
+    if (normalState.phase !== 'ready') {
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+
+    const found = this._findFileBrowserDirectory(normalState.data?.tree, target.path);
+    if (!found) {
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+    this._leaveFileBrowserSearchForDirectory([...found.ancestors, found.target.path], normalState);
+  },
+
+  _completeDeferredFileBrowserDirectory(normalState) {
+    const state = this._ensureFileBrowserState();
+    const target = state.deferredDirectoryTarget;
+    if (!target) return false;
+    if (!this._isFileBrowserDirectoryContextCurrent(target)) {
+      if (state.deferredDirectoryTarget === target) state.deferredDirectoryTarget = null;
+      return false;
+    }
+    if (
+      !this._isFileBrowserNormalCompatible(
+        normalState,
+        target.ownerSessionId,
+        target.showHidden,
+        target.treeEpoch,
+      ) ||
+      (normalState.phase !== 'ready' && normalState.phase !== 'error')
+    ) {
+      return false;
+    }
+
+    state.deferredDirectoryTarget = null;
+    if (normalState.phase === 'error') {
+      this._promptFileBrowserDirectoryReload();
+      return false;
+    }
+
+    const found = this._findFileBrowserDirectory(normalState.data?.tree, target.path);
+    if (!found) {
+      this._promptFileBrowserDirectoryReload();
+      return false;
+    }
+    this._leaveFileBrowserSearchForDirectory([...found.ancestors, found.target.path], normalState);
+    return true;
+  },
+
+  _leaveFileBrowserSearchForDirectory(paths, normalState) {
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.inFlight = null;
+    state.filter = '';
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.view = 'normal';
+    this.fileBrowserFilter = '';
+
+    const input = this.$?.('fileBrowserSearch');
+    if (input) input.value = '';
+    this._syncFileBrowserExpandBtn();
+    for (const path of paths) {
+      if (typeof path === 'string') this.fileBrowserExpandedDirs?.add?.(path);
+    }
+    this.fileBrowserData = normalState.data;
+    this._renderFileBrowserNormalState(normalState);
  },

  expandAllDirectories(nodes) {
@@ -3151,6 +3779,10 @@ Object.assign(CodemanApp.prototype, {
  },

  toggleFileBrowserExpand() {
+    if (this._hasFileBrowserQuery()) {
+      this._syncFileBrowserExpandBtn();
+      return;
+    }
    this.fileBrowserAllExpanded = !this.fileBrowserAllExpanded;
    const btn = this.$('fileBrowserExpandBtn');

@@ -3165,14 +3797,28 @@ Object.assign(CodemanApp.prototype, {
  },

  refreshFileBrowser() {
-    if (this.activeSessionId) {
-      this.fileBrowserExpandedDirs.clear();
-      this.fileBrowserFilter = '';
-      this.fileBrowserAllExpanded = false;
-      const searchInput = this.$('fileBrowserSearch');
-      if (searchInput) searchInput.value = '';
-      this.loadFileBrowser(this.activeSessionId);
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
    }
+    state.inFlight = null;
+    state.searchEpoch++;
+    state.filter = '';
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.view = 'normal';
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs.clear();
+    this.fileBrowserAllExpanded = false;
+    const expandBtn = this.$('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+    const searchInput = this.$('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+
+    const ownerSessionId = state.ownerSessionId || this.activeSessionId;
+    if (!ownerSessionId || this.activeSessionId !== ownerSessionId) return undefined;
+    return this.loadFileBrowser(ownerSessionId, { force: true });
  },

  // Header "File Viewer" button (opt-in via App Settings → Header Displays →
@@ -3203,6 +3849,7 @@ Object.assign(CodemanApp.prototype, {

  closeFileBrowserPanel() {
    const panel = this.$('fileBrowserPanel');
+    this._resetFileBrowserForHide();
    if (panel) {
      panel.classList.remove('visible');
      // Reset position so it reopens at default location
@@ -2901,7 +2901,8 @@ Object.assign(CodemanApp.prototype, {
            this.fileBrowserDragListeners._onFirstDrag = onFirstDrag;
          }
        }
-      } else {
+      } else if (fileBrowserPanel.classList.contains('visible')) {
+        this._resetFileBrowserForHide?.();
        fileBrowserPanel.classList.remove('visible');
      }
    }
@@ -1535,7 +1535,10 @@ html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name-prefix {
  display: inline;
 }

-html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name.tab-name-renaming {
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .session-tab .tab-name.tab-name-renaming {
  display: flex;
  align-items: center;
  -webkit-box-orient: initial;
@@ -1544,11 +1547,17 @@ html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name.tab-name-
  overflow: visible;
 }

-html[data-tab-orientation='vertical'] .tab-name-renaming .tab-rename-prefix {
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .tab-name-renaming .tab-rename-prefix {
  flex: 0 0 auto;
 }

-html[data-tab-orientation='vertical'] .tab-name-renaming .tab-rename-input {
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .tab-name-renaming .tab-rename-input {
  flex: 1 1 0;
  width: auto;
  min-width: 0;
@@ -12363,17 +12372,20 @@ kbd {
 }

 /* Plan-usage chip (App Settings → Display → "Plan Usage Limits"). Shows the
-   live 5-hour + weekly plan limits parsed from the Claude statusline. Ships
+   live Claude and Codex plan limits in provider rows. Ships
   hidden via the marker class below because display is PER-DEVICE and the
   server cannot read localStorage; settings-ui.js reveals it on load (desktop
   default ON, handhelds OFF) and on a live toggle. */
 .header-plan-usage {
  display: inline-flex !important;
-  align-items: center;
-  height: 22px;
-  padding: 0 0.5rem;
-  border-radius: 11px;
+  flex-direction: column;
+  align-items: stretch;
+  justify-content: center;
+  min-height: 22px;
+  padding: 3px 0.5rem;
+  border-radius: 8px;
  font-size: 0.7rem;
+  line-height: 1.1;
  font-weight: 500;
  font-family: 'SF Mono', Monaco, monospace;
  color: var(--text-dim);
@@ -12382,6 +12394,23 @@ kbd {
  white-space: nowrap;
  cursor: default;
 }
+.header-plan-usage .pu-row {
+  display: flex;
+  align-items: baseline;
+}
+.header-plan-usage .pu-provider {
+  width: 46px;
+  flex: 0 0 46px;
+  font-size: 0.58rem;
+  font-weight: 700;
+  color: var(--text-dim);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.header-plan-usage .pu-windows {
+  display: inline-flex;
+  align-items: baseline;
+}
 /* Readable two-window layout: dim uppercase label + bold, color-coded value. */
 .header-plan-usage .pu-win {
  display: inline-flex;
@@ -3167,7 +3167,7 @@ Object.assign(CodemanApp.prototype, {
   * arrived, which looked like truncated responses and idle shell commands.
   */
  _scheduleTerminalWriteFlush() {
-    if (this.writeFrameScheduled || this.pendingWrites.length === 0) return;
+    if (this._terminalWriteInFlight || this.writeFrameScheduled || this.pendingWrites.length === 0) return;
    this.writeFrameScheduled = true;
    this._safeYield(() => {
      this.writeFrameScheduled = false;
@@ -3358,7 +3358,7 @@ Object.assign(CodemanApp.prototype, {
   * Strips markers and writes content atomically within a single frame.
   */
  flushPendingWrites() {
-    if (this.pendingWrites.length === 0 || !this.terminal) return;
+    if (this._terminalWriteInFlight || this.pendingWrites.length === 0 || !this.terminal) return;

    const _t0 = performance.now();
    // xterm.js 6.0+ natively handles DEC 2026 synchronized output markers.
@@ -3389,14 +3389,25 @@ Object.assign(CodemanApp.prototype, {
    const preserveViewportY =
      this.terminal.buffer?.active && !this.isTerminalAtBottom() ? this.terminal.buffer.active.viewportY : null;

-    if (_joinedLen <= MAX_FRAME_BYTES) {
-      this.terminal.write(joined);
-    } else {
-      // Write first chunk now, defer rest to next frame
-      this.terminal.write(joined.slice(0, MAX_FRAME_BYTES));
+    const writeChunk = joined.slice(0, MAX_FRAME_BYTES);
+    if (_joinedLen > MAX_FRAME_BYTES) {
+      // Keep the remainder app-side where the 128KB cap can see it. The next
+      // chunk is scheduled only after xterm confirms this one was parsed.
      this.pendingWrites.push(joined.slice(MAX_FRAME_BYTES));
      deferred = true;
-      this._scheduleTerminalWriteFlush();
+    }
+    this._terminalWriteInFlight = true;
+    this._terminalWriteInFlightBytes = writeChunk.length;
+    try {
+      this.terminal.write(writeChunk, () => {
+        this._terminalWriteInFlight = false;
+        this._terminalWriteInFlightBytes = 0;
+        this._scheduleTerminalWriteFlush();
+      });
+    } catch (err) {
+      this._terminalWriteInFlight = false;
+      this._terminalWriteInFlightBytes = 0;
+      throw err;
    }
    if (
      preserveViewportY !== null &&
@@ -57,9 +57,9 @@ export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: Session
            if (!ctx.sessions.has(id)) lastSig.delete(id);
          }
        }
-        const payload = { sessionId, ...telemetry };
-        setLatestPlanUsage(payload); // replayed in the SSE init snapshot for fresh loads
-        ctx.broadcast(SessionStatusTelemetry, payload);
+        const update = { sessionId, ...telemetry };
+        const snapshot = setLatestPlanUsage(update); // replayed in the SSE init snapshot for fresh loads
+        ctx.broadcast(SessionStatusTelemetry, snapshot);
      }
    }

@@ -449,7 +449,7 @@ export const CreateSessionSchema = z.object({
  effort: effortLevelSchema,
  /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
  modelOverride: z.string().max(50).optional(),
-  /** Inject the plan-usage statusLine exporter into the case (App Settings → Display → "Plan Usage Limits"). Claude-only. */
+  /** Inject the Claude statusLine source for the shared plan-usage chip. Claude sessions only; Codex is host-polled. */
  statusLineTelemetry: z.boolean().optional(),
  openCodeConfig: OpenCodeConfigSchema,
  codexConfig: CodexConfigSchema,
@@ -143,7 +143,9 @@ import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.j
 import { MAX_PASTE_IMAGE_BYTES } from '../config/buffer-limits.js';
 import { resolveTerminalHistoryConfig } from '../config/terminal-history.js';
 import { SseEvent } from './sse-events.js';
-import { getLatestPlanUsage } from './plan-usage-latest.js';
+import { getLatestPlanUsage, setLatestCodexPlanUsage } from './plan-usage-latest.js';
+import { telemetrySignature } from '../usage-telemetry.js';
+import { readCodexPlanUsage, resolveCodexBinaryPath } from '../utils/codex-cli-resolver.js';
 import type { ScheduledRun } from './ports/index.js';
 import { registerAuthMiddleware, registerSecurityHeaders, registerHostGuard } from './middleware/auth.js';
 import { isMultiUserMode } from '../config/multiuser.js';
@@ -186,6 +188,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Length range covers crypto.randomUUID() (36 chars) plus any short stable IDs,
 // while capping growth of `sseClientsById` and blocking pathological inputs.
 const SSE_CLIENT_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+const CODEX_USAGE_POLL_INTERVAL_MS = 5 * 60_000;

 function escapeHtmlText(value: string): string {
  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
@@ -268,6 +271,8 @@ export class WebServer extends EventEmitter {
  private cachedSessionsList: { data: unknown[]; timestamp: number } | null = null;
  // Token recording for daily stats (track what's been recorded to avoid double-counting)
  private lastRecordedTokens: Map<string, { input: number; output: number }> = new Map();
+  private codexUsageRefreshInFlight = false;
+  private lastCodexUsageSignature: string | null = null;
  // Server startup time for respawn grace period calculation
  private readonly serverStartTime: number = Date.now();
  // Pending respawn start timers (for cleanup on shutdown)
@@ -2394,6 +2399,23 @@ export class WebServer extends EventEmitter {
    }
  }

+  private async refreshCodexPlanUsage(): Promise<void> {
+    if (this.codexUsageRefreshInFlight) return;
+    this.codexUsageRefreshInFlight = true;
+    try {
+      const binaryPath = resolveCodexBinaryPath();
+      const usage = binaryPath ? await readCodexPlanUsage(binaryPath, APP_VERSION) : null;
+      const signature = usage ? telemetrySignature(usage) : '';
+      if (signature === this.lastCodexUsageSignature) return;
+      this.lastCodexUsageSignature = signature;
+      const snapshot = setLatestCodexPlanUsage(usage);
+      this.cachedLightState = null;
+      this.broadcast(SseEvent.SessionStatusTelemetry, snapshot);
+    } finally {
+      this.codexUsageRefreshInFlight = false;
+    }
+  }
+
  async start(): Promise<void> {
    // Multi-user first boot: create the initial admin from CODEMAN_USERNAME/PASSWORD
    // if there are no users yet, else refuse to start (there would be no way in).
@@ -2531,6 +2553,15 @@ export class WebServer extends EventEmitter {
    // $CODEMAN_HOOK_SECRET_FILE — hook curls cat that path at execution time.
    getHookSecret();

+    // Main Codex subscription limits come from the signed-in local CLI. Keep
+    // this read-only and host-scoped; multi-user SSE routing makes it admin-only.
+    if (!this.testMode) {
+      void this.refreshCodexPlanUsage();
+      this.cleanup.setInterval(() => void this.refreshCodexPlanUsage(), CODEX_USAGE_POLL_INTERVAL_MS, {
+        description: 'Codex plan-usage refresh',
+      });
+    }
+
    // Start scheduled runs cleanup timer
    this.cleanup.setInterval(
      () => {
@@ -116,7 +116,7 @@ export const SessionMessage = 'session:message' as const;
 export const SessionInteractive = 'session:interactive' as const;
 /** Prompt sent to session for execution. */
 export const SessionRunning = 'session:running' as const;
-/** Claude plan-usage telemetry (5-hour + weekly limits) parsed from the statusline. */
+/** Combined Claude and main Codex plan-usage telemetry for the shared header chip. */
 export const SessionStatusTelemetry = 'session:statusTelemetry' as const;

 // ─── Session: Ralph ──────────────────────────────────────────────────────────
@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Main Codex subscription usage for the shared header chip.
+ *
+ * Codex can return multiple model buckets. The header deliberately follows the
+ * backward-compatible `codex` bucket only; model-specific buckets such as Spark
+ * are separate limits and are not part of the requested row.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import * as telemetryModule from '../src/usage-telemetry.js';
+import * as codexResolverModule from '../src/utils/codex-cli-resolver.js';
+
+const REAL_RESPONSE = {
+  rateLimits: {
+    limitId: 'codex',
+    primary: { usedPercent: 40, windowDurationMins: 10080, resetsAt: 1788306836 },
+    secondary: null,
+  },
+  rateLimitsByLimitId: {
+    codex_bengalfox: {
+      limitId: 'codex_bengalfox',
+      limitName: 'GPT-5.3-Codex-Spark',
+      primary: { usedPercent: 12, windowDurationMins: 300, resetsAt: 1787750984 },
+      secondary: { usedPercent: 23, windowDurationMins: 10080, resetsAt: 1788337784 },
+    },
+    codex: {
+      limitId: 'codex',
+      primary: { usedPercent: 40, windowDurationMins: 10080, resetsAt: 1788306836 },
+      secondary: null,
+    },
+  },
+};
+
+type ParseCodexRateLimits = (value: unknown) => {
+  fiveHour?: { usedPercentage: number; resetAt: number };
+  sevenDay?: { usedPercentage: number; resetAt: number };
+} | null;
+
+function parser(): ParseCodexRateLimits {
+  const candidate = (telemetryModule as Record<string, unknown>).parseCodexRateLimitsResponse;
+  expect(candidate, 'usage telemetry must expose the Codex rate-limit parser').toBeTypeOf('function');
+  return candidate as ParseCodexRateLimits;
+}
+
+describe('parseCodexRateLimitsResponse', () => {
+  it('uses only the main codex bucket and maps its duration-tagged weekly window', () => {
+    expect(parser()(REAL_RESPONSE)).toEqual({
+      sevenDay: { usedPercentage: 40, resetAt: 1788306836 * 1000 },
+    });
+  });
+
+  it('maps 5-hour and 7-day windows by duration even when their positions are reversed', () => {
+    const result = parser()({
+      rateLimitsByLimitId: {
+        codex: {
+          primary: { usedPercent: 44, windowDurationMins: 10080, resetsAt: 200 },
+          secondary: { usedPercent: 17, windowDurationMins: 300, resetsAt: 100 },
+        },
+      },
+    });
+
+    expect(result).toEqual({
+      fiveHour: { usedPercentage: 17, resetAt: 100_000 },
+      sevenDay: { usedPercentage: 44, resetAt: 200_000 },
+    });
+  });
+
+  it('falls back to the backward-compatible rateLimits snapshot', () => {
+    expect(
+      parser()({
+        rateLimits: {
+          limitId: 'codex',
+          primary: { usedPercent: 8, windowDurationMins: 300, resetsAt: 300 },
+          secondary: null,
+        },
+      })
+    ).toEqual({ fiveHour: { usedPercentage: 8, resetAt: 300_000 } });
+  });
+
+  it('ignores unrelated duration buckets and malformed percentages', () => {
+    expect(
+      parser()({
+        rateLimitsByLimitId: {
+          codex: {
+            primary: { usedPercent: '40', windowDurationMins: 10080, resetsAt: 200 },
+            secondary: { usedPercent: 20, windowDurationMins: 60, resetsAt: 100 },
+          },
+        },
+      })
+    ).toBeNull();
+  });
+});
+type CodexRequest = (
+  binaryPath: string,
+  clientVersion: string,
+  request?: (binaryPath: string, clientVersion: string) => Promise<unknown>
+) => Promise<ReturnType<ParseCodexRateLimits>>;
+
+describe('readCodexPlanUsage', () => {
+  it('queries through the supplied app-server boundary and normalizes the result', async () => {
+    const candidate = (codexResolverModule as Record<string, unknown>).readCodexPlanUsage;
+    expect(candidate, 'the Codex resolver must expose a read-only usage query').toBeTypeOf('function');
+    const request = vi.fn(async () => REAL_RESPONSE);
+
+    await expect((candidate as CodexRequest)('/opt/codex', '1.23.0', request)).resolves.toEqual({
+      sevenDay: { usedPercentage: 40, resetAt: 1788306836 * 1000 },
+    });
+    expect(request).toHaveBeenCalledWith('/opt/codex', '1.23.0');
+  });
+});
@@ -38,7 +38,7 @@ interface FakeElement {
  textContent: string;
  classes: Set<string>;
  attrs: Record<string, string>;
-  classList: { toggle: (name: string, on: boolean) => void };
+  classList: { toggle: (name: string, on: boolean) => void; contains: (name: string) => boolean };
  setAttribute: (name: string, value: string) => void;
 }

@@ -55,6 +55,9 @@ function fakeElement(): FakeElement {
        if (on) classes.add(name);
        else classes.delete(name);
      },
+      contains(name: string) {
+        return classes.has(name);
+      },
    },
    setAttribute(name: string, value: string) {
      attrs[name] = value;
@@ -92,10 +95,12 @@ function loadPanel(store: Map<string, string> | null) {
  vm.runInContext(panelsJs, context, { filename: 'panels-ui.js' });

  const elements: Record<string, FakeElement> = {
+    fileBrowserPanel: fakeElement(),
    fileBrowserTree: fakeElement(),
    fileBrowserStatus: fakeElement(),
    fileBrowserHiddenBtn: fakeElement(),
  };
+  elements.fileBrowserPanel.classList.toggle('visible', true);
  const requests: string[] = [];
  const app = new CodemanApp() as Record<string, any>;
  app.$ = (id: string) => elements[id] ?? null;
@@ -149,10 +154,12 @@ describe('File Viewer show-hidden toggle', () => {
    const { app, requests } = loadPanel(store);
    await app.loadFileBrowser('sess-1');
    expect(requests[0]).toContain('showHidden=false');
+    const previousTreeEpoch = app._fileBrowserState.treeEpoch;

    await app.toggleFileBrowserHidden();

    expect(app.fileBrowserShowHidden).toBe(true);
+    expect(app._fileBrowserState.treeEpoch).toBe(previousTreeEpoch + 1);
    expect(requests).toHaveLength(2);
    expect(requests[1]).toContain('showHidden=true');
    expect(store.get(STORAGE_KEY)).toBe('1');
@@ -541,6 +541,46 @@ describe('Inline rename input', () => {
    expect(result.firstRenameClassActive).toBe(false);
  });

+  it('Session sidebar paints typing without ellipsizing the live editor', async () => {
+    await resetState();
+    const id = 'sidebar-live-input';
+
+    await page.evaluate((sessionId) => {
+      const app = (
+        window as unknown as {
+          app: {
+            sessions: Map<string, { id: string; name: string }>;
+            startInlineRename: (id: string) => void;
+          };
+        }
+      ).app;
+      document.documentElement.dataset.sessionList = 'sidebar';
+      document.documentElement.dataset.sidebar = 'expanded';
+      const list = document.getElementById('sessionSidebarList') as HTMLElement;
+      const tab = document.createElement('div');
+      tab.setAttribute('data-test-tab', '1');
+      tab.className = 'session-tab';
+      tab.innerHTML =
+        '<span class="tab-info"><span class="tab-name-row">' +
+        `<span class="tab-name" data-session-id="${sessionId}">old title</span>` +
+        '</span></span>';
+      list.appendChild(tab);
+      app.sessions.set(sessionId, { id: sessionId, name: 'old title' });
+      app.startInlineRename(sessionId);
+    }, id);
+
+    const label = page.locator(`.tab-name[data-session-id="${id}"]`);
+    const input = label.locator('input.tab-rename-input');
+    await input.press(process.platform === 'darwin' ? 'Meta+A' : 'Control+A');
+    await page.keyboard.type('edited title');
+
+    expect(await input.inputValue()).toBe('edited title');
+    expect(await input.evaluate((node) => document.activeElement === node)).toBe(true);
+    expect(await label.evaluate((node) => node.classList.contains('tab-name-renaming'))).toBe(true);
+    expect(await label.evaluate((node) => getComputedStyle(node).overflow)).toBe('visible');
+    expect(await input.evaluate((node) => node.getBoundingClientRect().width)).toBeGreaterThan(0);
+  });
+
  it('Vertical rail paints typing in an unclamped editor and restores the clamp on cancel', async () => {
    await resetState();
    const id = 'vertical-live-input';
@@ -225,10 +225,11 @@ describe('OpenCode session initial resize', () => {
      await route.continue();
    });

-    // Dispatch the needsRefresh event directly on the EventSource
-    // (this is how the server sends SSE events — as named events)
+    // Exercise the SSE fallback path. While WebSocket owns terminal I/O these
+    // duplicate SSE terminal events are intentionally ignored.
    await page.evaluate((sid: string) => {
-      const app = (window as unknown as { app: { eventSource: EventSource } }).app;
+      const app = (window as unknown as { app: { eventSource: EventSource; _disconnectWs: () => void } }).app;
+      app._disconnectWs();
      if (app.eventSource) {
        const event = new MessageEvent('session:needsRefresh', {
          data: JSON.stringify({ id: sid }),
@@ -0,0 +1,82 @@
+/** @fileoverview Header plan-usage chip provider rows (Claude above Codex). */
+
+import { readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+function loadCodemanAppClass() {
+  const constants = readFileSync(resolve(import.meta.dirname, '../src/web/public/constants.js'), 'utf8');
+  const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+  const chip = { innerHTML: '', title: '' };
+  const context = vm.createContext({
+    console,
+    performance,
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+    setTimeout,
+    clearTimeout,
+    requestAnimationFrame: vi.fn(),
+    HTMLCanvasElement: class HTMLCanvasElement {},
+    fetch: (...args: Parameters<typeof fetch>) => global.fetch(...args),
+    document: {
+      addEventListener: vi.fn(),
+      getElementById: (id: string) => (id === 'planUsageChip' ? chip : null),
+    },
+    localStorage: {
+      length: 0,
+      key: vi.fn(),
+      getItem: vi.fn(),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    },
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+    MobileDetection: {},
+  });
+  vm.runInContext(`${constants}\n${source}\nglobalThis.__CodemanApp = CodemanApp;`, context);
+  return {
+    CodemanApp: (context as { __CodemanApp: new () => unknown }).__CodemanApp,
+    chip,
+  };
+}
+
+type UsageApp = { updatePlanUsageChip: (data: unknown) => void };
+
+describe('header plan usage chip', () => {
+  it('renders Claude first and the main Codex limits underneath', () => {
+    const { CodemanApp, chip } = loadCodemanAppClass();
+    const app = Object.create((CodemanApp as { prototype: object }).prototype) as UsageApp;
+
+    app.updatePlanUsageChip({
+      fiveHour: { usedPercentage: 97, resetAt: 1000 },
+      sevenDay: { usedPercentage: 44, resetAt: 2000 },
+      codex: { sevenDay: { usedPercentage: 40, resetAt: 3000 } },
+    });
+
+    expect(chip.innerHTML).toContain('class="pu-row"');
+    expect(chip.innerHTML).toContain('class="pu-provider">Claude</span>');
+    expect(chip.innerHTML).toContain('class="pu-provider">Codex</span>');
+    expect(chip.innerHTML.indexOf('Claude')).toBeLessThan(chip.innerHTML.indexOf('Codex'));
+    expect(chip.innerHTML).toContain('97%');
+    expect(chip.innerHTML).toContain('44%');
+    expect(chip.innerHTML).toContain('40%');
+    expect(chip.title).toContain('Claude plan usage');
+    expect(chip.title).toContain('Codex plan usage');
+  });
+
+  it('omits unavailable Codex windows instead of inventing zero usage', () => {
+    const { CodemanApp, chip } = loadCodemanAppClass();
+    const app = Object.create((CodemanApp as { prototype: object }).prototype) as UsageApp;
+
+    app.updatePlanUsageChip({
+      fiveHour: { usedPercentage: 10, resetAt: 1000 },
+      sevenDay: { usedPercentage: 20, resetAt: 2000 },
+      codex: { sevenDay: { usedPercentage: 40, resetAt: 3000 } },
+    });
+
+    const codexRow = chip.innerHTML.slice(chip.innerHTML.indexOf('Codex'));
+    expect(codexRow).not.toContain('5h');
+    expect(codexRow).toContain('7d');
+  });
+});
@@ -0,0 +1,18 @@
+/** @fileoverview Merging Claude status-line usage with polled Codex usage. */
+
+import { expect, it } from 'vitest';
+import * as latestModule from '../src/web/plan-usage-latest.js';
+
+it('preserves the Codex row when a later Claude status-line sample arrives', () => {
+  const module = latestModule as Record<string, unknown>;
+  expect(module.setLatestCodexPlanUsage).toBeTypeOf('function');
+  const setCodex = module.setLatestCodexPlanUsage as (value: unknown) => unknown;
+  const setClaude = module.setLatestPlanUsage as (value: Record<string, unknown>) => unknown;
+
+  setCodex({ sevenDay: { usedPercentage: 40, resetAt: 3000 } });
+  expect(setClaude({ sessionId: 's1', fiveHour: { usedPercentage: 97, resetAt: 1000 } })).toEqual({
+    sessionId: 's1',
+    fiveHour: { usedPercentage: 97, resetAt: 1000 },
+    codex: { sevenDay: { usedPercentage: 40, resetAt: 3000 } },
+  });
+});
@@ -38,7 +38,10 @@ function loadTerminalUiHarness(mode: string) {
  app._workerYield = () => {};
  app._chunkedWriteGen = 0;
  app.terminal = {
-    write: (data: string) => writes.push(data),
+    write: (data: string, callback?: () => void) => {
+      writes.push(data);
+      callback?.();
+    },
    scrollToBottom: () => {},
    scrollToLine: () => {},
  };
@@ -46,7 +49,90 @@ function loadTerminalUiHarness(mode: string) {
  return { app, writes };
 }

+function loadAppHarness() {
+  const dir = resolve(import.meta.dirname, '../src/web/public');
+  const fetchMock = vi.fn();
+  const context = vm.createContext({
+    console: { ...console, log: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    performance: { now: () => 0 },
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+    setTimeout,
+    clearTimeout,
+    requestAnimationFrame: vi.fn(),
+    HTMLCanvasElement: class HTMLCanvasElement {},
+    WebSocket: { OPEN: 1 },
+    fetch: fetchMock,
+    document: { addEventListener: vi.fn(), getElementById: () => null, querySelector: () => null },
+    localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+    MobileDetection: { isTouchDevice: () => false },
+  });
+  const constants = readFileSync(resolve(dir, 'constants.js'), 'utf8');
+  const appSource = readFileSync(resolve(dir, 'app.js'), 'utf8');
+  vm.runInContext(`${constants}\n${appSource}\nglobalThis.__CodemanApp = CodemanApp;`, context);
+  const CodemanApp = (context as { __CodemanApp: { prototype: object } }).__CodemanApp;
+  return { CodemanApp, fetchMock };
+}
+
 describe('terminal flush budget', () => {
+  it('counts incoming, loading, and xterm in-flight bytes before accepting live output', () => {
+    const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+    const start = source.indexOf('_onSessionTerminal(data)');
+    const body = source.slice(start, source.indexOf('\n  // ═', start));
+
+    expect(body).toContain('this._loadBufferQueue?.reduce');
+    expect(body).toContain('this._terminalWriteInFlightBytes || 0');
+    expect(body).toContain('queued + data.data.length > 131072');
+  });
+
+  it('drops redundant SSE terminal events whenever WebSocket owns terminal I/O', () => {
+    const { CodemanApp } = loadAppHarness();
+    const app = Object.create(CodemanApp.prototype) as any;
+    app._wsReady = true;
+    app._onSessionTerminal = vi.fn();
+    app._onSessionNeedsRefresh = vi.fn();
+    app._onSessionClearTerminal = vi.fn();
+
+    app._onSSETerminal({ id: 'session-1', data: 'duplicate' });
+    app._onSSENeedsRefresh({});
+    app._onSSEClearTerminal({ id: 'session-1' });
+
+    expect(app._onSessionTerminal).not.toHaveBeenCalled();
+    expect(app._onSessionNeedsRefresh).not.toHaveBeenCalled();
+    expect(app._onSessionClearTerminal).not.toHaveBeenCalled();
+  });
+
+  it('runs at most one buffer recovery per session and ignores stale-session events', async () => {
+    const { CodemanApp, fetchMock } = loadAppHarness();
+    const app = Object.create(CodemanApp.prototype) as any;
+    app.activeSessionId = 'session-1';
+    app.sessions = new Map([['session-1', { mode: 'shell' }]]);
+    app.terminal = {};
+    app._isLoadingBuffer = false;
+    app._terminalRefreshOwner = null;
+
+    let releaseFetch!: () => void;
+    fetchMock.mockImplementation(
+      () =>
+        new Promise((resolveFetch) => {
+          releaseFetch = () => resolveFetch({ json: async () => ({ data: { terminalBuffer: '' } }) });
+        })
+    );
+
+    await app._onSessionNeedsRefresh({ id: 'stale-session' });
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    const first = app._onSessionNeedsRefresh({ id: 'session-1' });
+    const duplicate = app._onSessionNeedsRefresh({ id: 'session-1' });
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledWith('/api/sessions/session-1/terminal?tail=1048576');
+
+    releaseFetch();
+    await Promise.all([first, duplicate]);
+    expect(app._terminalRefreshOwner).toBe(null);
+  });
+
  it('drains a large final batch without waiting for unrelated terminal output', () => {
    const { app, writes } = loadTerminalUiHarness('codex');
    const scheduled: Array<() => void> = [];
@@ -89,6 +175,32 @@ describe('terminal flush budget', () => {
    expect(app.pendingWrites.join('')).toHaveLength(32 * 1024);
  });

+  it('waits for xterm to parse a live chunk before submitting the next one', () => {
+    const { app, writes } = loadTerminalUiHarness('shell');
+    const scheduled: Array<() => void> = [];
+    let parsed: (() => void) | undefined;
+    app._safeYield = (callback: () => void) => scheduled.push(callback);
+    app.isTerminalAtBottom = () => true;
+    app.terminal.write = (data: string, callback?: () => void) => {
+      writes.push(data);
+      parsed = callback;
+    };
+
+    app.batchTerminalWrite('x'.repeat(96 * 1024));
+    scheduled.shift()?.();
+
+    expect(writes.map((write) => write.length)).toEqual([64 * 1024]);
+    expect(app.pendingWrites.join('')).toHaveLength(32 * 1024);
+    expect(scheduled).toHaveLength(0);
+    expect(app._terminalWriteInFlightBytes).toBe(64 * 1024);
+
+    parsed?.();
+
+    expect(scheduled).toHaveLength(1);
+    scheduled.shift()?.();
+    expect(writes.map((write) => write.length)).toEqual([64 * 1024, 32 * 1024]);
+  });
+
  it('releases the live-output gate but waits for xterm to parse a small replay', async () => {
    const { app, writes } = loadTerminalUiHarness('codex');
    let writeDone: (() => void) | undefined;
@@ -191,7 +191,7 @@ describe('backpressure refresh keeps a reader in place (issue #259)', () => {

  it('is wired into the refresh path instead of an unconditional scrollToBottom', () => {
    const app = readFileSync(resolve(PUBLIC, 'app.js'), 'utf8');
-    const start = app.indexOf('async _onSessionNeedsRefresh()');
+    const start = app.indexOf('async _onSessionNeedsRefresh(');
    expect(start).toBeGreaterThan(-1);
    const body = app.slice(start, app.indexOf('\n  async _onSessionClearTerminal', start));
    expect(body).toContain('computeRewriteScrollLine');
@@ -199,18 +199,16 @@ describe('backpressure refresh keeps a reader in place (issue #259)', () => {
    expect(body).toContain('this.terminal.scrollToLine(target)');
  });

-  it('recovers FULL history, guarded against a repaint-pane downgrade', () => {
-    // Measured before the fix: this path rewrote an 869-row buffer from a 1MB
-    // tail and left 158 rows, so the refresh meant to REPAIR the terminal was
-    // destroying most of its scrollback. It asks for full history now, and
-    // falls back to the tail only when the full capture would shrink the buffer
-    // (a repaint-mode pane keeps roughly one frame in tmux).
+  it('keeps shell recovery bounded and full TUI recovery downgrade-safe', () => {
+    // A shell's automatic recovery must not reset+replay a multi-megabyte tmux
+    // history on xterm's main thread. TUI modes still recover full history and
+    // fall back when a repaint-mode pane would shrink the browser buffer.
    const app = readFileSync(resolve(PUBLIC, 'app.js'), 'utf8');
-    const start = app.indexOf('async _onSessionNeedsRefresh()');
+    const start = app.indexOf('async _onSessionNeedsRefresh(');
    const body = app.slice(start, app.indexOf('\n  async _onSessionClearTerminal', start));
+    expect(body).toContain("const useFullHistory = this.sessions.get(sessionId)?.mode !== 'shell'");
    expect(body).toContain('terminal?full=1');
-    expect(body).toContain('this._replayWouldShrinkBuffer(data.terminalBuffer)');
-    // The tail must survive as the fallback, not vanish.
    expect(body).toContain('tail=${TERMINAL_TAIL_SIZE}');
+    expect(body).toContain('useFullHistory && data.terminalBuffer && this._replayWouldShrinkBuffer');
  });
 });
Author	SHA1	Message	Date
Codeman maintainer	23fae0c5af	chore: version packages Codex plan usage in the header chip (#346), a visible inline rename in the session sidebar (#345), and the install.sh Tailscale re-run fix plus the README network-access prompt description. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-28 00:25:32 +02:00
Ark0N	e4699159e9	Merge pull request #346 from JackStuart/codex/show-codex-usage-limits feat(web): show Codex plan usage in header	2026-08-28 00:14:54 +02:00
Ark0N	da085f5f7f	Merge pull request #345 from fibr/fix/sidebar-inline-rename fix(ui): show inline rename text in session sidebar	2026-08-28 00:14:48 +02:00
Codeman maintainer	23e32b22d5	docs(readme): describe the actual three-way network-access prompt The installer bullet still described a two-way choice with 0.0.0.0 as "the default", which predates the Tailscale option. The prompt has offered three choices for a while (Tailscale / any device on your network / this machine only), and the default is computed from what is already on the machine rather than being fixed at 0.0.0.0. Now states all three options, that the Tailscale one is a loopback bind fronted by `tailscale serve` with the tailnet as the login, and how the highlighted default is chosen. Line 220 already documented the Tailscale option correctly; this was the only stale spot. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-28 00:02:33 +02:00
Codeman maintainer	7dfb4acf24	fix(install): offer Tailscale setup on re-run instead of losing it to a failed build The network-access prompt, where Tailscale serve is configured, runs AFTER the build step. A build failure therefore exits before the question is ever asked, and a user who then finishes the build by hand (rather than re-running install.sh) ends up with a healthy loopback-only Codeman, a connected Tailscale, and no serve mapping — with nothing anywhere pointing at `install.sh tailscale`, the command that fixes it. Reported from a fresh Ubuntu 24 install that died on the node-pty compile. - maybe_offer_tailscale_repair(): on the update/re-run path, detect exactly that state (loopback bind + tailscale Running + no serve mapping fronting Codeman) and offer the retrofit. Silent for a deliberate non-loopback bind, silent once a mapping exists, silent when tailscale is absent, and prints the command instead of prompting when non-interactive. Returns 0 even when setup fails so it can never abort an update. - print_security_notice(): the loopback branch now names `install.sh tailscale` when Tailscale is installed on the box, rather than the generic "tailscale serve / cloudflared tunnel" advice. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-26 18:29:15 +02:00
Codeman maintainer	d3f851a5e5	chore: version packages install.sh installs a build toolchain on Linux (node-pty has no Linux prebuild, so a stock Ubuntu 24 server died inside node-gyp with "not found: make"), plus review hardening for #339: the write-queue reset paths now release the one-chunk-in-flight gate. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-26 18:04:44 +02:00
Ark0N	5f8d4de443	Merge pull request #340 from aakhter/pr/cod-341-file-viewer-search feat(file-viewer): COD-341 search the full workspace	2026-08-26 18:03:21 +02:00
Ark0N	00b32ad2b8	Merge pull request #339 from dignfei/fix/terminal-live-write-backpressure fix(terminal): bound live xterm backpressure	2026-08-26 18:03:14 +02:00
Jack Stuart	b00ab3ceea	feat(web): show Codex plan usage in header	2026-08-26 18:43:52 +08:00
Sergei Lupashin	134e200aec	fix(ui): show inline rename text in session sidebar	2026-08-25 19:41:48 +02:00
d fei	7c62b16e5f	fix(terminal): bound live xterm backpressure	2026-08-24 19:06:50 +08:00
Aamer Akhter	d15d979a33	fix: COD-341 correct changeset package name	2026-08-23 22:55:10 -04:00
Aamer Akhter	858b15e3f5	chore: COD-341 add File Viewer search release note	2026-08-23 22:46:58 -04:00
Aamer Akhter	c14171b534	fix(file-viewer): COD-341 finalize deferred navigation	2026-08-23 22:42:10 -04:00
Aamer Akhter	acd9ffedc8	fix(file-viewer): COD-341 complete search transitions	2026-08-23 22:27:26 -04:00
Aamer Akhter	921933775b	test(file-viewer): COD-341 execute session lifecycle path	2026-08-23 22:08:29 -04:00
Aamer Akhter	f6a1f06633	fix(file-viewer): COD-341 synchronize session lifecycle	2026-08-23 21:58:45 -04:00
Aamer Akhter	dab8e6643c	fix(file-viewer): COD-341 deduplicate normal tree loads	2026-08-23 21:40:10 -04:00
Aamer Akhter	3af36f7c34	fix(file-viewer): COD-341 preserve search row layout	2026-08-23 21:23:17 -04:00
Aamer Akhter	49797e37dd	fix(file-viewer): COD-341 gate stale search results	2026-08-23 21:09:52 -04:00
Aamer Akhter	c614331d60	feat(file-viewer): COD-341 add server-side search	2026-08-23 21:01:39 -04:00