chore: version packages

Split the monolithic app.js (~12.5K lines) into 6 focused mixin modules
that extend CodemanApp.prototype via Object.assign:

- terminal-ui.js — terminal setup, rendering pipeline, controls
- respawn-ui.js — respawn banner, countdown, presets, run summary
- ralph-panel.js — Ralph state panel, fix_plan, plan versioning
- settings-ui.js — app settings, visibility, web push, tunnel/QR, help
- panels-ui.js — subagent panel, teams, insights, file browser, log viewer
- session-ui.js — quick start, session options, case settings

Fix deferred script init ordering: wrap CodemanApp instantiation in
DOMContentLoaded so all defer'd mixin modules execute their
Object.assign before the constructor runs. Without this, init() calls
methods like applyHeaderVisibilitySettings() that don't exist yet.

Guard missing cleanupWizardDragging() call in subagent-windows.js.
Update build.mjs to minify/hash all new modules. Update CLAUDE.md
with new frontend architecture and load order.

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

.github/workflows/ci.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: 'npm'

.github/workflows/release.yml

@@ -16,12 +16,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
           registry-url: https://registry.npmjs.org
 

CHANGELOG.md

@@ -1,5 +1,37 @@
 # aicodeman
 
+## 0.4.2
+
+### Patch Changes
+
+- Extract monolithic app.js (~12.5K lines) into 6 focused domain modules that extend CodemanApp.prototype via Object.assign: terminal-ui.js (terminal setup, rendering pipeline, controls), respawn-ui.js (respawn banner, countdown, presets, run summary), ralph-panel.js (Ralph state panel, fix_plan, plan versioning), settings-ui.js (app settings, visibility, web push, tunnel/QR, help), panels-ui.js (subagent panel, teams, insights, file browser, log viewer), session-ui.js (quick start, session options, case settings). Fix critical deferred script init ordering bug: wrap CodemanApp instantiation in DOMContentLoaded so all defer'd mixin modules execute their Object.assign before the constructor runs. Guard missing cleanupWizardDragging() call in subagent-windows.js. Update build.mjs to minify/hash all new modules.
+
+## 0.4.1
+
+### Patch Changes
+
+- Performance optimizations: V8 compile cache for 10-20% faster cold starts, lazy-load WebGL addon (244KB saved on mobile), preload hints for critical scripts, batch tmux reconciliation (N subprocess calls → 1). Also: WebSocket session lifecycle fixes, CJK IME input support, CI upgrade to Node 24/actions v6, install.sh fork support, and CLAUDE.md/README documentation refresh.
+
+## 0.4.0
+
+### Minor Changes
+
+- Add CJK IME input textarea for xterm.js terminal (env toggle INPUT_CJK_FORM=ON). Always-visible textarea below terminal handles native browser IME composition, forwarding completed text to PTY on Enter. Supports arrow keys, Ctrl combos, backspace passthrough, and Escape to clear.
+
+  Add fork installation support to install.sh with CODEMAN_REPO_URL and CODEMAN_BRANCH env vars, allowing custom repository and branch for git clone/update operations. README updated with fork installation instructions.
+
+  Fix WebSocket session lifecycle: close WS connections when session exits (prevents orphaned listeners and stale writes to dead PTY), add readyState guard in onTerminal to stop buffering after socket closes, simplify heartbeat by removing redundant alive flag.
+
+  Add WebSocket reconnection with exponential backoff (1s-10s) on unexpected close, skipping server rejection codes (4004/4008/4009). Falls back gracefully to SSE+POST during reconnection.
+
+  Clear CJK textarea on session switch to prevent sending stale text to wrong session.
+
+## 0.3.12
+
+### Patch Changes
+
+- Add WebSocket terminal I/O with server-side DEC 2026 synchronized update markers. Replaces per-keystroke HTTP POST + SSE terminal output with a single bidirectional WebSocket connection for dramatically lower input latency. Server-side 8ms micro-batching with 16KB flush threshold groups rapid PTY events into single WS frames wrapped in DEC 2026 markers for flicker-free atomic rendering. Includes 30s ping/pong heartbeat with 10s timeout for stale connection detection through tunnels. Existing SSE + HTTP POST paths remain fully functional as transparent fallback. Resize messages validated to match HTTP route bounds (cols 1-500, rows 1-200, integers only). 16 automated route tests added for WS endpoint. Also patches 5 dependency vulnerabilities (basic-ftp, fastify, minimatch, serialize-javascript).
+
 ## 0.3.11
 
 ### Patch Changes

CLAUDE.md

@@ -52,7 +52,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.3.11 (must match `package.json`)
+**Version**: 0.4.2 (must match `package.json`)
 
 ## Project Overview
 
@@ -108,9 +108,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **State** | `src/state-store.ts`, `src/run-summary.ts`, `src/session-lifecycle-log.ts` | |
 | **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
-| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (12 route modules + barrel), `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` ★ (~12.1K lines) + 9 JS modules (incl. `sw.js` service worker) | |
-| **Types** | `src/types/index.ts` → 14 domain files | See `@fileoverview` in index.ts |
+| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (13 route modules incl. `ws-routes.ts` + barrel), `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
+| **Frontend** | `src/web/public/app.js` (~2.6K lines, core) + 6 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 5 existing modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `sw.js`, `input-cjk.js`) | |
+| **Types** | `src/types/index.ts` → 13 domain files | See `@fileoverview` in index.ts |
 
 ★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in.
 
@@ -118,7 +118,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Config**: `src/config/` — 9 files. Import from specific files, not barrel.
 
-**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`.
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks).
 
 ### Data Flow
 
@@ -143,7 +143,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `app.js`(6) → `ralph-wizard.js`(7) → `api-client.js`(8) → `subagent-windows.js`(9).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `settings-ui.js`(10) → `panels-ui.js`(11) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15). `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
 
 **Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).
 
@@ -170,7 +170,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### API Routes
 
-~111 handlers across 12 route files in `src/web/routes/`: system (35), sessions (24), ralph (9), plan (8), respawn (7), cases (7), files (5), mux (5), scheduled (4), push (4), teams (2), hooks (1). Each file has `@fileoverview` with endpoint details.
+~114 handlers across 13 route files in `src/web/routes/`: system (36), sessions (25), ralph (9), plan (8), respawn (7), cases (7), files (5), mux (5), scheduled (4), push (4), teams (2), hooks (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 ## Adding Features
 

README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.5"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
   <img src="https://img.shields.io/badge/Tests-1435%20total-22c55e?style=flat-square" alt="Tests">
 </p>
@@ -28,7 +28,27 @@
 curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash
 ```
 
-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai) (or both). After install:
+This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it.
+
+**Install from a fork or specific branch:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/<user>/Codeman/<branch>/install.sh | \
+  CODEMAN_REPO_URL=https://github.com/<user>/Codeman.git \
+  CODEMAN_BRANCH=<branch> bash
+```
+
+The installer supports these environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEMAN_REPO_URL` | upstream Codeman | Custom git repository URL |
+| `CODEMAN_BRANCH` | `master` | Git branch to install |
+| `CODEMAN_INSTALL_DIR` | `~/.codeman/app` | Custom install directory |
+| `CODEMAN_SKIP_SYSTEMD` | `0` | Skip systemd service setup prompt |
+| `CODEMAN_NODE_VERSION` | `22` | Node.js major version to install |
+| `CODEMAN_NONINTERACTIVE` | `0` | Skip all prompts (for CI/automation) |
+
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai) (or both). After install:
 
 ```bash
 codeman web
@@ -479,9 +499,9 @@ The codebase went through a comprehensive 7-phase refactoring that eliminated go
 | Phase | What changed | Impact |
 |-------|-------------|--------|
 | **Performance** | Cached endpoints, SSE adaptive batching, buffer chunking | Sub-16ms terminal latency |
-| **Route extraction** | `server.ts` split into 12 domain route modules + auth middleware + port interfaces | **−60%** server.ts LOC (6,736 → 2,697) |
+| **Route extraction** | `server.ts` split into 13 domain route modules + auth middleware + port interfaces | **−60%** server.ts LOC (6,736 → 2,697) |
 | **Domain splitting** | `types.ts` → 14 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files |
-| **Frontend modules** | `app.js` → 8 extracted modules (constants, mobile, voice, notifications, keyboard, API, subagent windows) | **−24%** app.js LOC (15.2K → 11.5K) |
+| **Frontend modules** | `app.js` → 9 extracted modules (constants, mobile, voice, notifications, keyboard, CJK input, API, Ralph wizard, subagent windows) | **−24%** app.js LOC (15.2K → 11.5K) |
 | **Config consolidation** | ~70 scattered magic numbers → 9 domain-focused config files | Zero cross-file duplicates |
 | **Test infrastructure** | Shared mock library, 12 route test files, consolidated MockSession | Testable route handlers via `app.inject()` |
 

docs/performance-plan.md

@@ -0,0 +1,74 @@
+# Codeman Performance Optimization Plan
+
+## Current State
+
+The backend is **already production-grade** — SSE broadcasting, state persistence, terminal batching, buffer management, and memory patterns are all well-optimized. The biggest gains are on the **frontend delivery** side.
+
+## Implemented Optimizations
+
+### 1. V8 Compile Cache (10-20% faster cold start)
+
+**Files:** `scripts/codeman-web.service`, `package.json`
+
+Node.js re-parses and compiles all JS on every cold start. `NODE_COMPILE_CACHE` caches V8 compiled bytecode to disk, reusing it on subsequent starts.
+
+- Added `Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache` to systemd service
+- Added to `npm start` script for non-systemd usage
+- Zero code changes, immediate win on every restart
+
+### 2. WebGL Addon Lazy-Loading (244KB saved on mobile, non-blocking on desktop)
+
+**Files:** `src/web/public/index.html`, `src/web/public/app.js`
+
+`xterm-addon-webgl.min.js` (244KB) was loaded eagerly for all users via `<script defer>`, but only used on desktop with WebGL2 support.
+
+- Removed `<script defer>` from `index.html`
+- Added dynamic script loading in `app.js` — only downloads on desktop when WebGL is needed
+- Mobile users never download the file at all (244KB saved)
+- Desktop: loads in parallel with page rendering, addon initializes when ready
+- Graceful fallback: canvas renderer used if WebGL unavailable or script fails
+
+### 3. Preload Hints (~50-100ms faster perceived load)
+
+**Files:** `src/web/public/index.html`
+
+Browser discovers `<script defer>` tags only when the parser reaches them at the bottom of `<body>`. By then, the HTML parse has blocked for hundreds of lines.
+
+- Added `<link rel="preload" as="script">` in `<head>` for `vendor/xterm.min.js`, `constants.js`, `app.js`
+- Browser starts fetching critical scripts immediately during HTML parse (before reaching `<body>`)
+- Zero runtime overhead — just hints for the browser's preload scanner
+
+### 4. Batch Tmux Reconciliation (N subprocess calls → 1)
+
+**Files:** `src/tmux-manager.ts`
+
+`reconcileSessions()` previously called `tmux has-session` + `tmux display-message` per known session, plus `tmux list-sessions` for discovery, plus `tmux display-message` per discovered session. With 20 sessions: 41+ subprocess calls.
+
+- Replaced with single `tmux list-panes -a -F '#{session_name}\t#{pane_pid}'` call
+- Builds a Map from the result, then does O(1) lookups for both known and discovered sessions
+- Also replaced inner O(n) `isKnown` scan with a Set lookup
+- 20 sessions: 41 subprocess calls → 1, with faster lookups
+
+### 5. Asset Hashing / Cache Busting (already implemented)
+
+**Files:** `scripts/build.mjs` (pre-existing)
+
+Content-hash cache busting was already implemented in the build script:
+- All app JS/CSS files get content hashes (`app.abc123.js`)
+- `index.html` rewritten to reference hashed filenames
+- Pre-compressed with gzip + Brotli
+- 1-year immutable cache works correctly — new deploys get new filenames
+
+## Already Optimized (No Action Needed)
+
+| Area | Why It's Fine |
+|------|---------------|
+| **SSE Broadcasting** | Single serialization per broadcast, preformatted frames, backpressure handling, session subscription filtering |
+| **State Persistence** | 500ms debounce, incremental per-session JSON caching, async atomic writes, circuit breaker on failures |
+| **Terminal Batching** | Adaptive intervals (16-50ms), per-session queues, immediate flush at 32KB, array-based accumulation |
+| **Buffer Management** | BufferAccumulator (array-push, lazy join), auto-trim at 2MB/1MB, no string concatenation in hot paths |
+| **ANSI Stripping** | Pre-compiled regex via factory functions, single-pass processing |
+| **Static File Serving** | @fastify/static with 1-year cache, pre-compressed Brotli/gzip, no-cache for HTML |
+| **Memory Management** | CleanupManager, LRUMap, StaleExpirationMap, bounded buffers, explicit listener cleanup |
+| **Import Patterns** | Pure ESM, lazy web server import, no circular deps, no dynamic imports in hot paths |
+| **Config Loading** | Small constant files, no I/O at import time, specific imports (no barrel) |

install.sh

@@ -9,6 +9,8 @@
 #   CODEMAN_INSTALL_DIR       - Custom install directory (default: ~/.codeman/app)
 #   CODEMAN_SKIP_SYSTEMD=1    - Skip systemd service setup prompt
 #   CODEMAN_NODE_VERSION      - Node.js major version to install (default: 22)
+#   CODEMAN_REPO_URL          - Custom git repository URL (default: upstream Codeman)
+#   CODEMAN_BRANCH            - Git branch to install (default: master)
 
 set -euo pipefail
 
@@ -17,7 +19,8 @@ set -euo pipefail
 # ============================================================================
 
 INSTALL_DIR="${CODEMAN_INSTALL_DIR:-$HOME/.codeman/app}"
-REPO_URL="https://github.com/Ark0N/Codeman.git"
+REPO_URL="${CODEMAN_REPO_URL:-https://github.com/Ark0N/Codeman.git}"
+BRANCH="${CODEMAN_BRANCH:-master}"
 MIN_NODE_VERSION=18
 TARGET_NODE_VERSION="${CODEMAN_NODE_VERSION:-22}"
 NONINTERACTIVE="${CODEMAN_NONINTERACTIVE:-0}"
@@ -1062,26 +1065,27 @@ main() {
     if [[ -d "$INSTALL_DIR/.git" ]]; then
         info "Existing installation found, updating..."
         cd "$INSTALL_DIR"
+        git remote set-url origin "$REPO_URL" 2>/dev/null || true
 
         # Check for local changes
         if ! git diff --quiet 2>/dev/null || ! git diff --staged --quiet 2>/dev/null; then
             warn "Local changes detected in $INSTALL_DIR"
             if prompt_yes_no "Discard local changes and update?" "n"; then
                 git fetch --quiet origin
-                git reset --hard origin/master --quiet
+                git reset --hard "origin/$BRANCH" --quiet
             else
                 info "Keeping existing installation, skipping update"
             fi
         else
             git fetch --quiet origin
-            git reset --hard origin/master --quiet
+            git reset --hard "origin/$BRANCH" --quiet
         fi
     else
         # Create parent directory
         mkdir -p "$(dirname "$INSTALL_DIR")"
 
         # Clone repository (shallow for speed)
-        git clone --quiet --depth 1 "$REPO_URL" "$INSTALL_DIR"
+        git clone --quiet --depth 1 --branch "$BRANCH" "$REPO_URL" "$INSTALL_DIR"
         cd "$INSTALL_DIR"
     fi
 
@@ -1277,8 +1281,9 @@ update() {
 
     info "Updating Codeman..."
     cd "$INSTALL_DIR"
+    git remote set-url origin "$REPO_URL" 2>/dev/null || true
     git fetch --quiet origin
-    git reset --hard origin/master --quiet
+    git reset --hard "origin/$BRANCH" --quiet
     npm install --quiet --no-fund --no-audit 2>/dev/null || npm install --no-fund --no-audit
     npm run build --quiet 2>/dev/null || npm run build
     success "Updated to $(node -e "console.log(require('./package.json').version)")"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.3.11",
+  "version": "0.4.2",
   "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "build": "node scripts/build.mjs",
-    "start": "node dist/index.js",
+    "start": "NODE_COMPILE_CACHE=${HOME}/.codeman/compile-cache node dist/index.js",
     "dev": "tsx src/index.ts web",
     "web": "node dist/index.js web",
     "clean": "rm -rf dist",

scripts/build.mjs

@@ -59,7 +59,14 @@ appendFileSync(
 );
 
 // 4. Minify frontend assets
+run('minify input-cjk.js', 'npx esbuild dist/web/public/input-cjk.js --minify --outfile=dist/web/public/input-cjk.js --allow-overwrite');
 run('minify app.js', 'npx esbuild dist/web/public/app.js --minify --outfile=dist/web/public/app.js --allow-overwrite');
+run('minify terminal-ui.js', 'npx esbuild dist/web/public/terminal-ui.js --minify --outfile=dist/web/public/terminal-ui.js --allow-overwrite');
+run('minify respawn-ui.js', 'npx esbuild dist/web/public/respawn-ui.js --minify --outfile=dist/web/public/respawn-ui.js --allow-overwrite');
+run('minify ralph-panel.js', 'npx esbuild dist/web/public/ralph-panel.js --minify --outfile=dist/web/public/ralph-panel.js --allow-overwrite');
+run('minify settings-ui.js', 'npx esbuild dist/web/public/settings-ui.js --minify --outfile=dist/web/public/settings-ui.js --allow-overwrite');
+run('minify panels-ui.js', 'npx esbuild dist/web/public/panels-ui.js --minify --outfile=dist/web/public/panels-ui.js --allow-overwrite');
+run('minify session-ui.js', 'npx esbuild dist/web/public/session-ui.js --minify --outfile=dist/web/public/session-ui.js --allow-overwrite');
 run('minify styles.css', 'npx esbuild dist/web/public/styles.css --minify --outfile=dist/web/public/styles.css --allow-overwrite');
 run('minify mobile.css', 'npx esbuild dist/web/public/mobile.css --minify --outfile=dist/web/public/mobile.css --allow-overwrite');
 
@@ -75,7 +82,14 @@ console.log('\n[build] content-hash cache busting');
     'voice-input.js',
     'notification-manager.js',
     'keyboard-accessory.js',
+    'input-cjk.js',
     'app.js',
+    'terminal-ui.js',
+    'respawn-ui.js',
+    'ralph-panel.js',
+    'settings-ui.js',
+    'panels-ui.js',
+    'session-ui.js',
     'ralph-wizard.js',
     'api-client.js',
     'subagent-windows.js',

scripts/codeman-web.service

@@ -11,6 +11,7 @@ RestartSec=5
 KillMode=process
 Environment=NODE_ENV=production
 Environment=HOME=/home/arkon
+Environment=NODE_COMPILE_CACHE=/home/arkon/.codeman/compile-cache
 
 # Logging
 StandardOutput=journal

src/tmux-manager.ts

@@ -905,13 +905,34 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const dead: string[] = [];
     const discovered: string[] = [];
 
-    // Check known sessions
+    // Batch: single tmux call to get all session names + pane PIDs (replaces N per-session subprocess calls)
+    const activeSessions = new Map<string, number>();
+    try {
+      const output = execSync("tmux list-panes -a -F '#{session_name}\t#{pane_pid}' 2>/dev/null || true", {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      }).trim();
+
+      for (const line of output.split('\n')) {
+        if (!line) continue;
+        const sep = line.indexOf('\t');
+        if (sep === -1) continue;
+        const name = line.slice(0, sep);
+        const pid = parseInt(line.slice(sep + 1), 10);
+        if (name && !Number.isNaN(pid)) {
+          activeSessions.set(name, pid);
+        }
+      }
+    } catch (err) {
+      console.error('[TmuxManager] Failed to list tmux panes:', err);
+    }
+
+    // Check known sessions against the batch result (O(1) map lookup instead of subprocess per session)
     for (const [sessionId, session] of this.sessions) {
-      if (this.sessionExists(session.muxName)) {
+      const pid = activeSessions.get(session.muxName);
+      if (pid !== undefined) {
         alive.push(sessionId);
-        // Update PID if it changed
-        const pid = this.getPanePid(session.muxName);
-        if (pid && pid !== session.pid) {
+        if (pid !== session.pid) {
           session.pid = pid;
         }
       } else {
@@ -921,33 +942,18 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       }
     }
 
-    // Discover unknown codeman sessions
-    try {
-      const output = execSync("tmux list-sessions -F '#{session_name}' 2>/dev/null || true", {
-        encoding: 'utf-8',
-        timeout: EXEC_TIMEOUT_MS,
-      }).trim();
-
-      for (const line of output.split('\n')) {
-        const sessionName = line.trim();
-        if (!sessionName || (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-'))) continue;
-
-        // Check if this session is already known
-        let isKnown = false;
+    // Discover unknown codeman/claudeman sessions from the same batch result
+    const knownMuxNames = new Set<string>();
     for (const session of this.sessions.values()) {
-          if (session.muxName === sessionName) {
-            isKnown = true;
-            break;
-          }
+      knownMuxNames.add(session.muxName);
     }
 
-        if (!isKnown) {
-          // Extract session ID fragment from name
+    for (const [sessionName, pid] of activeSessions) {
+      if (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-')) continue;
+      if (knownMuxNames.has(sessionName)) continue;
+
       const fragment = sessionName.replace(/^(?:codeman|claudeman)-/, '');
       const sessionId = `restored-${fragment}`;
-          const pid = this.getPanePid(sessionName);
-
-          if (pid) {
       const session: MuxSession = {
         sessionId,
         muxName: sessionName,
@@ -962,11 +968,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       discovered.push(sessionId);
       console.log(`[TmuxManager] Discovered unknown tmux session: ${sessionName} (PID ${pid})`);
     }
-        }
-      }
-    } catch (err) {
-      console.error('[TmuxManager] Failed to discover sessions:', err);
-    }
 
     if (dead.length > 0 || discovered.length > 0) {
       this.saveSessions();

src/web/public/api-client.js

@@ -7,7 +7,7 @@
  *
  * @mixin Extends CodemanApp.prototype via Object.assign
  * @dependency app.js (CodemanApp class must be defined)
- * @loadorder 8 of 9 — loaded after app.js
+ * @loadorder 14 of 15 — loaded after ralph-wizard.js
  */
 
 // Codeman — Centralized API fetch helpers for CodemanApp

src/web/public/constants.js

@@ -14,8 +14,10 @@
  * @globals {Array} BUILTIN_RESPAWN_PRESETS - Built-in respawn configuration presets
  *
  * @dependency None (first in load order)
- * @loadorder 1 of 9 — constants.js → mobile-handlers.js → voice-input.js → notification-manager.js
- *   → keyboard-accessory.js → app.js → ralph-wizard.js → api-client.js → subagent-windows.js
+ * @loadorder 1 of 15 — constants.js → mobile-handlers.js → voice-input.js → notification-manager.js
+ *   → keyboard-accessory.js → input-cjk.js → app.js → terminal-ui.js → respawn-ui.js
+ *   → ralph-panel.js → settings-ui.js → panels-ui.js → session-ui.js → ralph-wizard.js
+ *   → api-client.js → subagent-windows.js
  */
 
 // Codeman — Shared constants and utility functions for frontend modules

src/web/public/index.html

@@ -14,11 +14,16 @@
   <!-- xterm.css loaded async — terminal won't display until xterm.js runs anyway -->
   <link rel="preload" href="vendor/xterm.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
   <noscript><link rel="stylesheet" href="vendor/xterm.css"></noscript>
+  <!-- Preload critical resources — lets browser discover these during HTML parse
+       instead of waiting until <script> tags at bottom-of-body are reached. -->
+  <link rel="preload" href="vendor/xterm.min.js" as="script">
+  <link rel="preload" href="constants.js" as="script">
+  <link rel="preload" href="app.js" as="script">
   <!-- Self-hosted xterm.js — eliminates CDN DNS/TLS latency (~100ms).
        'defer' preserves execution order (xterm loads before fit addon). -->
   <script defer src="vendor/xterm.min.js"></script>
   <script defer src="vendor/xterm-addon-fit.min.js"></script>
-  <script defer src="vendor/xterm-addon-webgl.min.js"></script>
+  <!-- WebGL addon lazy-loaded by app.js on desktop only (skipped on mobile, saving 244KB) -->
   <script defer src="vendor/xterm-addon-unicode11.min.js"></script>
   <script defer src="vendor/xterm-zerolag-input.js"></script>
   <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
@@ -231,7 +236,12 @@
 
     <!-- Main Terminal Area -->
     <main class="main">
+      <div class="terminal-wrap">
         <div class="terminal-container" id="terminalContainer"></div>
+        <textarea id="cjkInput" rows="1" placeholder="CJK input (Enter = send, Esc = clear)"
+          maxlength="65536" aria-label="CJK IME input field"
+          autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
+      </div>
 
       <!-- Welcome Overlay (shown when no session active) -->
       <div class="welcome-overlay" id="welcomeOverlay">
@@ -1689,7 +1699,14 @@
   <script defer src="voice-input.js"></script>
   <script defer src="notification-manager.js"></script>
   <script defer src="keyboard-accessory.js"></script>
+  <script defer src="input-cjk.js"></script>
   <script defer src="app.js"></script>
+  <script defer src="terminal-ui.js"></script>
+  <script defer src="respawn-ui.js"></script>
+  <script defer src="ralph-panel.js"></script>
+  <script defer src="settings-ui.js"></script>
+  <script defer src="panels-ui.js"></script>
+  <script defer src="session-ui.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
   <script defer src="subagent-windows.js"></script>

src/web/public/input-cjk.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview CJK IME input for xterm.js terminal.
+ *
+ * Always-visible textarea below the terminal (in index.html).
+ * The browser handles IME composition natively — we just read
+ * textarea.value on Enter and send it to PTY.
+ * While this textarea has focus, window.cjkActive = true blocks xterm's onData.
+ * Arrow keys and function keys are forwarded to PTY directly.
+ *
+ * @dependency index.html (#cjkInput textarea)
+ * @globals {object} CjkInput — window.cjkActive (boolean) signals app.js to block xterm onData
+ * @loadorder 5.5 of 15 — loaded after keyboard-accessory.js, before app.js
+ */
+
+// eslint-disable-next-line no-unused-vars
+const CjkInput = (() => {
+  let _textarea = null;
+  let _send = null;
+  let _initialized = false;
+  let _onMousedown = null;
+  let _onFocus = null;
+  let _onBlur = null;
+  let _onKeydown = null;
+
+  const PASSTHROUGH_KEYS = {
+    ArrowUp:    '\x1b[A',
+    ArrowDown:  '\x1b[B',
+    ArrowLeft:  '\x1b[D',
+    ArrowRight: '\x1b[C',
+    Home:       '\x1b[H',
+    End:        '\x1b[F',
+    Tab:        '\t',
+  };
+
+  const CTRL_KEYS = {
+    c: '\x03', d: '\x04', l: '\x0c', z: '\x1a', a: '\x01', e: '\x05',
+  };
+
+  return {
+    init({ send }) {
+      // Guard against double-init: remove previous listeners
+      if (_initialized) this.destroy();
+
+      _send = send;
+      _textarea = document.getElementById('cjkInput');
+      if (!_textarea) return this;
+
+      _onMousedown = (e) => { e.stopPropagation(); };
+      _onFocus = () => { window.cjkActive = true; };
+      _onBlur = () => { window.cjkActive = false; };
+      _textarea.addEventListener('mousedown', _onMousedown);
+      _textarea.addEventListener('focus', _onFocus);
+      _textarea.addEventListener('blur', _onBlur);
+
+      _onKeydown = (e) => {
+        if (e.isComposing || e.keyCode === 229) return;
+
+        // Enter: send accumulated text (or bare Enter if empty)
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          if (_textarea.value) {
+            _send(_textarea.value + '\r');
+            _textarea.value = '';
+          } else {
+            _send('\r');
+          }
+          return;
+        }
+
+        // Escape: clear textarea
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          _textarea.value = '';
+          return;
+        }
+
+        // Ctrl combos: forward to PTY
+        if (e.ctrlKey && CTRL_KEYS[e.key]) {
+          e.preventDefault();
+          _send(CTRL_KEYS[e.key]);
+          return;
+        }
+
+        // Backspace: delete from textarea if has text, else forward to PTY
+        if (e.key === 'Backspace' && !_textarea.value) {
+          e.preventDefault();
+          _send('\x7f');
+          return;
+        }
+
+        // Arrow/function keys: forward to PTY when textarea is empty
+        if (PASSTHROUGH_KEYS[e.key] && !_textarea.value) {
+          e.preventDefault();
+          _send(PASSTHROUGH_KEYS[e.key]);
+          return;
+        }
+      };
+      _textarea.addEventListener('keydown', _onKeydown);
+
+      _initialized = true;
+      return this;
+    },
+
+    destroy() {
+      if (_textarea) {
+        if (_onMousedown) _textarea.removeEventListener('mousedown', _onMousedown);
+        if (_onFocus) _textarea.removeEventListener('focus', _onFocus);
+        if (_onBlur) _textarea.removeEventListener('blur', _onBlur);
+        if (_onKeydown) _textarea.removeEventListener('keydown', _onKeydown);
+      }
+      window.cjkActive = false;
+      _onMousedown = _onFocus = _onBlur = _onKeydown = null;
+      _initialized = false;
+    },
+
+    get element() { return _textarea; },
+  };
+})();

src/web/public/keyboard-accessory.js

@@ -18,7 +18,7 @@
  *
  * @dependency mobile-handlers.js (MobileDetection.isTouchDevice)
  * @dependency app.js (uses global `app` for sendInput, activeSessionId, terminal)
- * @loadorder 5 of 9 — loaded after notification-manager.js, before app.js
+ * @loadorder 5 of 15 — loaded after notification-manager.js, before app.js
  */
 
 // Codeman — Keyboard accessory bar and focus trap for modals

src/web/public/mobile-handlers.js

@@ -19,7 +19,7 @@
  * @globals {object} SwipeHandler
  *
  * @dependency keyboard-accessory.js (KeyboardAccessoryBar reference in KeyboardHandler.onKeyboardShow, soft — guarded with typeof check)
- * @loadorder 2 of 9 — loaded after constants.js, before voice-input.js
+ * @loadorder 2 of 15 — loaded after constants.js, before voice-input.js
  */
 
 // Codeman — Mobile detection, keyboard handling, and swipe navigation

src/web/public/notification-manager.js

@@ -22,7 +22,7 @@
  *
  * @dependency constants.js (STUCK_THRESHOLD_DEFAULT_MS, timing constants)
  * @dependency mobile-handlers.js (MobileDetection.getDeviceType for device-specific defaults)
- * @loadorder 4 of 9 — loaded after voice-input.js, before keyboard-accessory.js
+ * @loadorder 4 of 15 — loaded after voice-input.js, before keyboard-accessory.js
  */
 
 // Codeman — Multi-layer notification system

src/web/public/ralph-wizard.js

@@ -19,7 +19,7 @@
  * @dependency app.js (CodemanApp class must be defined)
  * @dependency keyboard-accessory.js (FocusTrap class for modal focus management)
  * @dependency constants.js (escapeHtml)
- * @loadorder 7 of 9 — loaded after app.js, before api-client.js
+ * @loadorder 13 of 15 — loaded after session-ui.js, before api-client.js
  */
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/styles.css

@@ -1882,6 +1882,13 @@ body {
   position: relative;
 }
 
+.terminal-wrap {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
 .terminal-container {
   flex: 1;
   background: #0d0d0d;
@@ -7502,3 +7509,34 @@ kbd {
 .advanced-options-content {
   padding-left: 0.5rem;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+   CJK IME Input
+   ═══════════════════════════════════════════════════════════════ */
+
+#cjkInput {
+  display: none;
+  flex-shrink: 0;
+  width: 100%;
+  font-family: 'Fira Code', 'Cascadia Code', 'JetBrains Mono', 'SF Mono', Monaco, monospace;
+  font-size: 14px;
+  background: #1a1a2e;
+  color: #e0e0e0;
+  border: 1px solid #333;
+  border-top: none;
+  padding: 6px 10px;
+  outline: none;
+  resize: none;
+  line-height: 1.4;
+  box-sizing: border-box;
+}
+
+#cjkInput:focus {
+  border-color: #339af0;
+  background: #111;
+}
+
+#cjkInput::placeholder {
+  color: #495057;
+  font-size: 12px;
+}

src/web/public/subagent-windows.js

@@ -15,7 +15,7 @@
  * @mixin Extends CodemanApp.prototype via Object.assign
  * @dependency app.js (CodemanApp class, this.subagents, this.subagentWindows, this.minimizedSubagents)
  * @dependency constants.js (escapeHtml)
- * @loadorder 9 of 9 — loaded last, after api-client.js
+ * @loadorder 15 of 15 — loaded last, after api-client.js
  */
 
 // Codeman — Subagent window management for CodemanApp
@@ -991,7 +991,7 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Clean up wizard drag listeners (leak fix: document-level handlers)
-    this.cleanupWizardDragging();
+    if (typeof this.cleanupWizardDragging === 'function') this.cleanupWizardDragging();
 
     // Deactivate focus trap if wizard was open (leak fix: keydown listener)
     if (this.activeFocusTrap) {

src/web/public/voice-input.js

@@ -19,7 +19,7 @@
  *
  * @dependency mobile-handlers.js (MobileDetection for device checks)
  * @dependency app.js (uses global `app` for sendInput, showToast, terminal focus)
- * @loadorder 3 of 9 — loaded after mobile-handlers.js, before notification-manager.js
+ * @loadorder 3 of 15 — loaded after mobile-handlers.js, before notification-manager.js
  */
 
 // Codeman — Voice input with Deepgram Nova-3 and Web Speech API fallback

src/web/routes/ws-routes.ts

@@ -38,6 +38,13 @@ const WS_BATCH_INTERVAL_MS = 8;
 /** Flush immediately when batch exceeds this size (bytes) for responsiveness. */
 const WS_BATCH_FLUSH_THRESHOLD = 16384;
 
+/** How often to ping each WebSocket client (ms). Detects stale connections that
+ *  TCP keepalive won't catch for minutes, especially through tunnels/proxies. */
+const WS_PING_INTERVAL_MS = 30_000;
+
+/** If pong isn't received within this window after a ping, terminate the socket. */
+const WS_PONG_TIMEOUT_MS = 10_000;
+
 /** DEC 2026 synchronized update markers. Wrapping output in these tells xterm.js
  *  to buffer all content and render atomically in a single frame — eliminates
  *  flicker from cursor-up redraws that Ink sends without its own sync markers
@@ -45,6 +52,12 @@ const WS_BATCH_FLUSH_THRESHOLD = 16384;
 const DEC_2026_START = '\x1b[?2026h';
 const DEC_2026_END = '\x1b[?2026l';
 
+/** Max concurrent WS connections per session. Prevents listener/bandwidth multiplication. */
+const MAX_WS_PER_SESSION = 5;
+
+/** Track active WS connections per session for connection limiting. */
+const sessionWsCount = new Map<string, number>();
+
 export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort): void {
   app.get<{ Params: { id: string } }>('/ws/sessions/:id/terminal', { websocket: true }, (socket: WebSocket, req) => {
     const { id } = req.params;
@@ -55,6 +68,17 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort): void {
       return;
     }
 
+    // Enforce per-session connection limit
+    const currentCount = sessionWsCount.get(id) ?? 0;
+    if (currentCount >= MAX_WS_PER_SESSION) {
+      socket.close(4008, 'Too many connections');
+      return;
+    }
+    sessionWsCount.set(id, currentCount + 1);
+
+    // Swallow socket errors — cleanup happens in 'close'
+    socket.on('error', () => {});
+
     // Per-connection micro-batch state
     let batchChunks: string[] = [];
     let batchSize = 0;
@@ -99,6 +123,7 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort): void {
 
     // Terminal output -> micro-batched WS send
     const onTerminal = (data: string) => {
+      if (socket.readyState !== 1) return;
       batchChunks.push(data);
       batchSize += data.length;
 
@@ -129,16 +154,53 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort): void {
       }
     };
 
+    // Close WS when session exits (deleted, respawned, or crashed) — prevents
+    // orphaned listeners and stale writes to a dead PTY.
+    const onSessionExit = () => {
+      socket.close(4009, 'Session terminated');
+    };
+
     session.on('terminal', onTerminal);
     session.on('clearTerminal', onClearTerminal);
     session.on('needsRefresh', onNeedsRefresh);
+    session.on('exit', onSessionExit);
+
+    // Heartbeat: detect stale connections (especially through tunnels where
+    // TCP RST can take minutes to propagate).
+    let pongTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    socket.on('pong', () => {
+      if (pongTimeout) {
+        clearTimeout(pongTimeout);
+        pongTimeout = null;
+      }
+    });
+
+    const pingInterval = setInterval(() => {
+      if (socket.readyState !== 1) return;
+      socket.ping();
+      pongTimeout = setTimeout(() => {
+        socket.terminate();
+      }, WS_PONG_TIMEOUT_MS);
+    }, WS_PING_INTERVAL_MS);
 
     socket.on('close', () => {
+      clearInterval(pingInterval);
+      if (pongTimeout) clearTimeout(pongTimeout);
       if (batchTimer) clearTimeout(batchTimer);
       batchChunks = [];
       session.off('terminal', onTerminal);
       session.off('clearTerminal', onClearTerminal);
       session.off('needsRefresh', onNeedsRefresh);
+      session.off('exit', onSessionExit);
+
+      // Decrement per-session connection count
+      const count = sessionWsCount.get(id) ?? 1;
+      if (count <= 1) {
+        sessionWsCount.delete(id);
+      } else {
+        sessionWsCount.set(id, count - 1);
+      }
     });
   });
 }

src/web/server.ts

@@ -1953,6 +1953,7 @@ export class WebServer extends EventEmitter {
       globalStats: this.store.getAggregateStats(activeSessionTokens),
       subagents: subagentWatcher.getRecentSubagents(15), // 15 min to avoid stale agents
       timestamp: now,
+      inputCjkForm: process.env.INPUT_CJK_FORM?.toUpperCase() === 'ON',
     };
 
     this.cachedLightState = { data: result, timestamp: now };

test/routes/ws-routes.test.ts

@@ -5,6 +5,8 @@
  * a real listening server since inject() doesn't support upgrade requests.
  * Uses the `ws` package (transitive dep of @fastify/websocket) as the client.
  *
+ * @dependency test/mocks/mock-route-context.ts (createMockRouteContext)
+ * @dependency src/web/routes/ws-routes.ts (registerWsRoutes)
  * Port: 3170 (ws-routes tests)
  */
 
@@ -14,15 +16,23 @@ import fastifyWebsocket from '@fastify/websocket';
 import WebSocket from 'ws';
 import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
 import { registerWsRoutes } from '../../src/web/routes/ws-routes.js';
+import { MAX_INPUT_LENGTH } from '../../src/config/terminal-limits.js';
 
 const PORT = 3170;
 
 /** Helper: open a WebSocket connection and wait for it to reach OPEN state. */
-function connectWs(path: string): Promise<WebSocket> {
+function connectWs(path: string, timeoutMs = 5000): Promise<WebSocket> {
   return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('WS connection timeout')), timeoutMs);
     const ws = new WebSocket(`ws://127.0.0.1:${PORT}${path}`);
-    ws.on('open', () => resolve(ws));
-    ws.on('error', reject);
+    ws.on('open', () => {
+      clearTimeout(timer);
+      resolve(ws);
+    });
+    ws.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
   });
 }
 
@@ -48,6 +58,23 @@ function waitForClose(ws: WebSocket, timeoutMs = 2000): Promise<{ code: number;
   });
 }
 
+/** Helper: collect N messages from a WebSocket. */
+function collectMessages(ws: WebSocket, count: number, timeoutMs = 3000): Promise<unknown[]> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Only received ${msgs.length}/${count} messages`)), timeoutMs);
+    const msgs: unknown[] = [];
+    const onMessage = (raw: WebSocket.RawData) => {
+      msgs.push(JSON.parse(String(raw)));
+      if (msgs.length >= count) {
+        clearTimeout(timer);
+        ws.off('message', onMessage);
+        resolve(msgs);
+      }
+    };
+    ws.on('message', onMessage);
+  });
+}
+
 describe('ws-routes', () => {
   let app: FastifyInstance;
   let ctx: MockRouteContext;
@@ -123,6 +150,43 @@ describe('ws-routes', () => {
         ws.close();
       }
     });
+
+    it('coalesces rapid terminal emissions into a single frame', async () => {
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+      try {
+        const session = ctx._session;
+
+        // Emit multiple small chunks in rapid succession (within the 8ms batch window)
+        session.emit('terminal', 'chunk1');
+        session.emit('terminal', 'chunk2');
+        session.emit('terminal', 'chunk3');
+
+        // Should arrive as a single coalesced message
+        const msg = (await nextMessage(ws)) as { t: string; d: string };
+        expect(msg.t).toBe('o');
+        expect(msg.d).toContain('chunk1chunk2chunk3');
+      } finally {
+        ws.close();
+      }
+    });
+
+    it('flushes immediately when batch exceeds size threshold', async () => {
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+      try {
+        const session = ctx._session;
+
+        // Emit data larger than WS_BATCH_FLUSH_THRESHOLD (16384)
+        const largeData = 'X'.repeat(17000);
+        session.emit('terminal', largeData);
+
+        // Should flush immediately (no 8ms wait) — use a tight timeout
+        const msg = (await nextMessage(ws, 500)) as { t: string; d: string };
+        expect(msg.t).toBe('o');
+        expect(msg.d).toContain(largeData);
+      } finally {
+        ws.close();
+      }
+    });
   });
 
   // ========== Client input ==========
@@ -132,7 +196,6 @@ describe('ws-routes', () => {
       const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
       try {
         const session = ctx._session;
-        session.writeBuffer = [];
 
         ws.send(JSON.stringify({ t: 'i', d: 'ls -la\r' }));
 
@@ -149,10 +212,8 @@ describe('ws-routes', () => {
       const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
       try {
         const session = ctx._session;
-        session.writeBuffer = [];
 
-        // MAX_INPUT_LENGTH is 64KB
-        const hugeInput = 'x'.repeat(65 * 1024);
+        const hugeInput = 'x'.repeat(MAX_INPUT_LENGTH + 1);
         ws.send(JSON.stringify({ t: 'i', d: hugeInput }));
 
         // Send a valid message after to confirm the connection still works
@@ -173,7 +234,6 @@ describe('ws-routes', () => {
       const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
       try {
         const session = ctx._session;
-        session.writeBuffer = [];
 
         ws.send('not-json{{{');
 
@@ -190,6 +250,28 @@ describe('ws-routes', () => {
         ws.close();
       }
     });
+
+    it('ignores unknown message types without breaking the connection', async () => {
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+      try {
+        const session = ctx._session;
+
+        // Send unknown type
+        ws.send(JSON.stringify({ t: 'x', d: 'mystery' }));
+
+        // Connection should still work
+        ws.send(JSON.stringify({ t: 'i', d: 'still-alive' }));
+
+        await vi.waitFor(() => {
+          expect(session.writeBuffer).toContain('still-alive');
+        });
+
+        // Unknown type should not have been written
+        expect(session.writeBuffer).toHaveLength(1);
+      } finally {
+        ws.close();
+      }
+    });
   });
 
   // ========== Resize validation ==========
@@ -332,6 +414,64 @@ describe('ws-routes', () => {
     });
   });
 
+  // ========== Connection limit ==========
+
+  describe('connection limit', () => {
+    it('closes with 4008 when too many connections per session', async () => {
+      const connections: WebSocket[] = [];
+      try {
+        // Open 5 connections (the max)
+        for (let i = 0; i < 5; i++) {
+          connections.push(await connectWs('/ws/sessions/ws-test-session/terminal'));
+        }
+
+        // 6th connection should be rejected
+        const ws6 = new WebSocket(`ws://127.0.0.1:${PORT}/ws/sessions/ws-test-session/terminal`);
+        const { code, reason } = await waitForClose(ws6);
+        expect(code).toBe(4008);
+        expect(reason).toBe('Too many connections');
+      } finally {
+        for (const ws of connections) ws.close();
+      }
+    });
+  });
+
+  // ========== Heartbeat ==========
+
+  describe('heartbeat', () => {
+    it('responds to server ping with pong (connection stays alive)', async () => {
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+      try {
+        // The ws library automatically responds to pings with pongs.
+        // Verify the connection survives by sending data after a brief delay.
+        const session = ctx._session;
+        session.emit('terminal', 'heartbeat-test');
+
+        const msg = (await nextMessage(ws)) as { t: string; d: string };
+        expect(msg.t).toBe('o');
+        expect(msg.d).toContain('heartbeat-test');
+      } finally {
+        ws.close();
+      }
+    });
+  });
+
+  // ========== readyState guards ==========
+
+  describe('readyState guards', () => {
+    it('does not throw when clearTerminal fires after close', async () => {
+      const session = ctx._session;
+      const ws = await connectWs('/ws/sessions/ws-test-session/terminal');
+
+      ws.close();
+      await waitForClose(ws);
+
+      // These should be no-ops, not throw
+      expect(() => session.emit('clearTerminal')).not.toThrow();
+      expect(() => session.emit('needsRefresh')).not.toThrow();
+    });
+  });
+
   // ========== Connection cleanup ==========
 
   describe('connection cleanup', () => {
@@ -350,11 +490,11 @@ describe('ws-routes', () => {
       ws.close();
       await waitForClose(ws);
 
-      // Give the server-side close handler time to run
-      await new Promise((resolve) => setTimeout(resolve, 50));
-
-      // Listeners should be cleaned up
+      // Wait for server-side close handler
+      await vi.waitFor(() => {
         expect(session.listenerCount('terminal')).toBe(listenersBefore);
+      });
+
       expect(session.listenerCount('clearTerminal')).toBe(0);
       expect(session.listenerCount('needsRefresh')).toBe(0);
     });