chore: version packages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
refactor: codebase cleanup — dead code, regex helper, centralized constants, tests
2026-09-30 12:39:42 +02:00 · 2026-03-07 07:34:24 +01:00 · 2026-03-07 07:33:44 +01:00 · 2026-03-07 07:04:27 +01:00 · 2026-03-07 07:00:18 +01:00 · 2026-03-07 06:40:09 +01:00
54 changed files with 10105 additions and 1810 deletions
@@ -1,5 +1,41 @@
 # aicodeman

+## 0.3.7
+
+### Patch Changes
+
+- Codebase cleanup: remove dead code (unused token validation exports, PlanPhase alias), add execPattern() regex helper to eliminate repetitive .lastIndex resets, centralize 11 magic number constants into config files, fix CLAUDE.md inaccuracies, and add 316 new tests for utilities, respawn helpers, and system-routes
+
+## 0.3.6
+
+### Patch Changes
+
+- Re-enable WebGL renderer with 48KB/frame flush cap protection against GPU stalls
+
+## 0.3.5
+
+### Patch Changes
+
+- Fix Chrome "page unresponsive" crashes caused by xterm.js WebGL renderer GPU stalls during heavy terminal output. Disable WebGL by default (canvas renderer used instead), gate SSE terminal writes during tab switches, and add crash diagnostics with server-side breadcrumb collection.
+
+## 0.3.4
+
+### Patch Changes
+
+- Fix Chrome tab freeze from flicker filter buffer accumulation during active sessions, and fix shell mode feedback delay by excluding shell sessions from cursor-up filter
+
+## 0.3.3
+
+### Patch Changes
+
+- fix: eliminate WebGL re-render flicker during tab switch by keeping renderer active instead of toggling it off/on around large buffer writes
+
+## 0.3.2
+
+### Patch Changes
+
+- Make file browser panel draggable by its header
+
 ## 0.3.1

 ### Patch Changes
@@ -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.1 (must match `package.json`)
+**Version**: 0.3.7 (must match `package.json`)

 ## Project Overview

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

 **CI**: `.github/workflows/ci.yml` runs `typecheck`, `lint`, `format:check` on push to master (Node 22). Tests excluded (they spawn tmux).

-**Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`). ESLint allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Does not lint `app.js` or `scripts/**/*.mjs`.
+**Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`). ESLint flat config (`eslint.config.js`) allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Ignores: `app.js`, `scripts/**/*.mjs`, `src/web/public/vendor/**`, `tools/**`, `remotion/**`.

 ## Common Gotchas

@@ -98,7 +98,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | Domain | Key files | Notes |
 |--------|-----------|-------|
 | **Entry** | `src/index.ts`, `src/cli.ts` | |
-| **Session** | `src/session.ts` ★, `src/session-manager.ts`, `src/session-auto-ops.ts`, `src/session-cli-builder.ts` | |
+| **Session** | `src/session.ts` ★, `src/session-manager.ts`, `src/session-auto-ops.ts`, `src/session-cli-builder.ts`, `src/session-lifecycle-log.ts`, `src/session-task-cache.ts` | |
 | **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` | |
 | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
 | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
@@ -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` (13 modules), `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` ★ (~11.7K lines) + 9 JS modules | |
-| **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` (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` → 13 domain files | See `@fileoverview` in index.ts |

 ★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in.

@@ -170,7 +170,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L

 ### API Routes

-~111 handlers across 13 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.
+~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.

 ## Adding Features

@@ -179,7 +179,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 - **Session setting**: Add to `SessionState`, include in `session.toState()`, call `persistSessionState()`
 - **Hook event**: Add to `HookEventType`, add hook in `hooks-config.ts:generateHooksConfig()`, update `HookEventSchema`
 - **Mobile feature**: Add to relevant singleton, guard with `MobileDetection.isMobile()`
- **New test**: Pick unique port (search `const PORT =`). Integration: ports 3099-3211. Route tests: `app.inject()` — see `test/routes/_route-test-utils.ts`.
+- **New test**: Pick unique port (search `const PORT =`). Route tests use `app.inject()` (no port needed) — see `test/routes/_route-test-utils.ts`.

 **Validation**: Zod v4 (different API from v3). Define schemas in `schemas.ts`, use `.parse()`/`.safeParse()`.

@@ -238,7 +238,6 @@ Key: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh` (tunnel sta
 ## Common Workflows

 **Bug investigation**: Dev server → reproduce in browser → check terminal + `~/.codeman/state.json`.
-**API endpoint**: Types in `src/types/*.ts` → route in `src/web/routes/*-routes.ts` → SSE event if needed → handle in `app.js`.
 **Respawn changes**: Read `docs/respawn-state-machine.md` first. Use `MockSession` from `test/respawn-test-utils.ts`.

 ## Tunnel
@@ -0,0 +1,423 @@
+# Performance Analysis & Optimization Opportunities
+
+**Date**: 2026-03-07
+**Scope**: Full-stack performance analysis — backend PTY handling, SSE broadcasting, frontend terminal rendering, local echo overlay, DOM updates, config/scaling limits.
+**Constraint**: All recommendations preserve existing functionality including local echo, backpressure, anti-flicker pipeline, and mobile support.
+
+---
+
+## Executive Summary
+
+The codebase is already well-optimized in critical paths. The multi-layer backpressure system, adaptive terminal batching, DEC 2026 sync markers, and incremental state serialization are strong. The main opportunities are in **reducing unnecessary work** (SSE filtering, DOM rebuilds, lazy terminal init) rather than algorithmic changes.
+
+**Top 5 high-impact opportunities:**
+
+| # | Optimization | Impact | Risk | Effort |
+|---|-------------|--------|------|--------|
+| 1 | Session-scoped SSE subscriptions | Bandwidth -60-80%, CPU -40% | Medium | Medium |
+| 2 | Lazy xterm.js for minimized subagent windows | Memory -3.5MB at 50 agents | Low | Low |
+| 3 | Targeted badge update (skip full tab rebuild) | Eliminates O(n) reflow on badge change | Low | Low |
+| 4 | Conditional SSE padding (tunnel-only, terminal-only) | Bandwidth -70% when tunneled | Low | Low |
+| 5 | Canvas renderer on mobile | GPU pressure reduction, battery savings | Low | Low |
+
+---
+
+## 1. SSE Broadcasting
+
+### Current State
+- **92 event types** broadcast to all connected clients (max 100)
+- Single `JSON.stringify()` per event, shared across all clients (efficient)
+- **No per-client filtering** — every client receives every event regardless of which session they're viewing
+- 8KB padding appended to **every** event when tunnel is active (forces Cloudflare proxy flush)
+- Backpressure: clients marked as backpressured if `reply.raw.write()` returns false; recovery via `session:needsRefresh`
+
+### Bottlenecks
+
+**B1: No session-scoped SSE subscriptions** (`server.ts:1986`)
+- Client viewing session A still receives all events for sessions B through T
+- With 20 active sessions, ~95% of terminal events are irrelevant to any given client
+- Cost: wasted bandwidth, CPU for JSON parsing, and event handler dispatch on client
+
+**B2: Unconditional 8KB padding** (`server.ts:1977`)
+- Every event gets 8KB comment padding when tunnel is active
+- A `task:updated` event (~200 bytes payload) becomes ~8.2KB
+- High-frequency events like `session:terminal` need the padding; low-frequency events like `session:created` don't
+
+### Recommendations
+
+**R1: Session-scoped SSE subscriptions** (High impact)
+- Add `?sessions=id1,id2` query param to `/api/events` SSE endpoint
+- Server filters events by session ID before broadcasting
+- Client subscribes to active session + "global" events (session lifecycle, system)
+- Re-subscribes on tab switch (or subscribe to all with client-side filter as fallback)
+- **Savings**: ~80% bandwidth reduction for single-session viewers; ~60% for multi-session dashboards
+
+**R2: Tiered SSE padding** (Medium impact)
+- Only pad `session:terminal` events and SSE heartbeats (the two that need proxy flush)
+- Skip padding for low-frequency structural events (`session:created`, `task:updated`, etc.)
+- **Savings**: ~70% padding overhead reduction; terminal events already large enough to flush
+
+---
+
+## 2. Terminal Rendering
+
+### Current State (Well-Optimized)
+- **6-layer anti-flicker pipeline**: Server batching (adaptive 16-50ms) → DEC 2026 sync wrap → single JSON serialize → client rAF batching → sync segment parser → chunked buffer loading (32KB/frame)
+- **64KB/frame write budget** with DEC 2026 sync-segment awareness (prevents 141KB single-frame freezes)
+- **3-layer backpressure**: SSE cap (128KB queued → drop + refresh), frame budget (64KB/frame), chunked restore (32KB/frame)
+- WebGL renderer enabled by default with canvas fallback on context loss
+- Typical latency: 16-32ms; worst case: ~115ms (50ms server batch + 50ms sync wait + 16ms rAF)
+
+### Bottlenecks
+
+**B3: WebGL on mobile** (`app.js:627-637`)
+- Mobile GPUs are weaker; WebGL context loss more likely on low-end devices
+- Canvas renderer is sufficient for mobile (typically 1 session, smaller viewport)
+
+**B4: Static scrollback for all sessions** (`app.js:572`)
+- Default 5000 lines scrollback for all sessions regardless of activity level
+- Heavy output sessions (build logs, test runners) accumulate large scroll buffers
+
+**B5: No addon lazy loading**
+- FitAddon, Unicode11Addon, and WebGLAddon all loaded at terminal init
+- Unicode11Addon only needed for CJK content; WebGLAddon is large
+
+### Recommendations
+
+**R3: Force canvas renderer on mobile** (Low risk)
+- Detect `MobileDetection.isMobile()` and skip WebGL addon loading
+- Reduces GPU memory pressure, prevents context loss crashes
+- Mobile typically has 1-2 sessions — canvas performance is more than adequate
+
+**R4: Dynamic scrollback based on session activity** (Low risk)
+- Active sessions (working state): 5000 lines (current default)
+- Inactive/idle sessions: reduce to 2000 lines
+- Restore on session select (fetch from server buffer)
+- **Savings**: ~60% scrollback memory for idle sessions
+
+**R5: Lazy-load Unicode11Addon** (Low risk)
+- Only load when CJK content is detected in terminal output
+- Detection: check for characters in CJK Unicode ranges during ANSI stripping (already iterating)
+- Most sessions never need it
+
+---
+
+## 3. DOM & Session Tab Rendering
+
+### Current State
+- Session tabs use **intelligent incremental updates** with debounced 100ms rendering
+- Incremental path: only updates changed properties (classes, textContent, badges) when session list is stable
+- Full rebuild path: triggered when sessions added/removed **or badge count changes**
+- Subagent windows: per-window xterm.js instances, even when minimized
+
+### Bottlenecks
+
+**B6: Badge count change triggers full tab rebuild** (`app.js:3207-3209`)
+- A single subagent badge increment on one tab triggers `_fullRenderSessionTabs()` — rebuilds entire sidebar HTML via `innerHTML =`
+- With 20 sessions, this is an O(n) reflow for a single badge number change
+- Badge changes are frequent during active subagent work
+
+**B7: Minimized subagent windows retain xterm.js instances** (`subagent-windows.js`)
+- 50 subagent windows × ~75KB per xterm.js instance = ~3.75MB DOM memory
+- Minimized windows are invisible but their terminals remain in DOM
+- xterm.js instances continue processing resize events even when hidden
+
+**B8: `backdrop-filter: blur()` on overlays** (`styles.css:2246-2247, 3098`)
+- Forces new stacking context, disables browser compositing optimizations
+- 50-100ms layout thrashing on modal open/close
+- Only 2 uses, but they're on frequently toggled overlays
+
+### Recommendations
+
+**R6: Targeted badge update without full rebuild** (Low risk)
+- When badge count changes but session list is stable, update only the badge `<span>` textContent
+- Keep incremental path for badge changes; only use full rebuild for structural changes (add/remove sessions)
+- **Savings**: Eliminates O(n) reflow per badge change; reduces to O(1) targeted update
+
+**R7: Lazy xterm.js initialization for subagent windows** (Medium impact)
+- Only create xterm.js Terminal instance when window is restored/maximized
+- On minimize: serialize terminal buffer, dispose Terminal instance, keep buffer in memory
+- On restore: create new Terminal, write buffer back
+- **Savings**: ~3.5MB DOM reduction at 50 minimized agents; eliminates hidden resize processing
+- **Trade-off**: ~200-500ms restore delay (buffer write), mitigated by chunked loading
+
+**R8: Replace `backdrop-filter: blur()` with `background: rgba()`** (Low risk)
+- Use semi-transparent background instead of blur effect
+- Or use `will-change: transform` hint if blur is kept
+- **Savings**: Eliminates forced recomposition layer; 50-100ms faster overlay open
+
+---
+
+## 4. Backend PTY & State Management
+
+### Current State (Excellent)
+- **BufferAccumulator**: Array-based chunking with lazy join on read — avoids O(n) string concatenation
+- **ANSI stripping**: Throttled at 150ms intervals with lazy evaluation (not per-chunk)
+- **State persistence**: 500ms debounce + incremental JSON caching per session (only dirty sessions re-serialized)
+- **Expensive parsers**: Throttled to 150ms window, accumulated data capped at 64KB
+- **Memory**: All buffers have hard limits (2MB terminal, 1MB text, 1000 messages, 64KB line buffer)
+
+### Bottlenecks
+
+**B9: Pending clean data cap at 64KB** (`session.ts:1097-1133`)
+- Between 150ms processing windows, raw PTY data accumulates in `_pendingCleanData`
+- Capped at 64KB — excess data rolls off (old data discarded)
+- During heavy output (large build logs), this means parsers may miss content
+- Acceptable trade-off for performance, but worth documenting
+
+**B10: `LRUMap.delete()` is O(n) worst case** (`utils/lru-map.ts:137-138`)
+- When deleting the newest entry, iterates all keys to find new newest
+- Rare in practice (delete is uncommon; set/get are hot paths)
+- Could matter during mass cleanup of 500 agents
+
+### Recommendations
+
+**R9: Consider adaptive pending data cap** (Low priority)
+- During idle detection (critical to get right), increase cap to 128KB
+- During active working state, keep at 64KB (parsers less critical)
+- **Benefit**: More accurate idle detection during heavy output
+
+**R10: Track second-newest in LRUMap** (Low priority)
+- Maintain a `_secondNewestKey` alongside `_newestKey`
+- On delete of newest, promote second-newest without iteration
+- Only matters at scale (500+ agents with frequent eviction)
+
+---
+
+## 5. Local Echo & Input Path
+
+### Current State (Well-Designed)
+- **DOM overlay approach** — `<span>` elements in `.xterm-screen` at z-index 7, completely independent of `terminal.write()`
+- **Render caching**: `_lastRenderKey` includes text, position, column offsets — skips redundant re-renders
+- **Input flow**: Char accumulation → Enter triggers flush → 80ms delay before `\r` (ensures text reaches PTY first)
+- **Tab completion**: Baseline snapshot → detect buffer change → 300ms fallback timer
+- **CJK support**: Per-character width detection with `terminal.unicode.getStringCellWidth()` preferred, manual fallback
+- **Prompt detection**: Bottom-up line scan, O(rows) — cached position, column-lock prevents jitter
+
+### Bottlenecks
+
+**B11: tmux send-keys latency** (~50-100ms per input)
+- Each `writeViaMux()` spawns a child process (`tmux send-keys`)
+- Text and Enter sent separately with 50ms delay between
+- For rapid typing: characters batch before Enter, so overhead is per-command not per-keystroke
+- **Acceptable trade-off** for session persistence (tmux survives server restarts)
+
+**B12: 80ms delay between text flush and Enter** (`app.js:872-875`)
+- Intentional: ensures text reaches PTY before Enter, preventing Ink from processing empty input
+- Adds 80ms to perceived Enter-to-response latency
+- Could potentially be reduced with acknowledgment-based approach
+
+**B13: Scroll listener on terminal viewport** (`zerolag-input-addon.ts:139`)
+- 50ms debounced re-render on scroll — acceptable but fires frequently during heavy output
+- Overlay hidden when scrolled up (correct behavior), shown when at bottom
+
+### Recommendations
+
+**R11: Reduce Enter delay from 80ms to 50ms** (Low risk, test carefully)
+- The tmux `send-keys` already has 50ms internal delay
+- Combined with network latency, 80ms client-side may be excessive
+- Test with Ink-heavy sessions (Claude Code's status bar) — if text arrives before Enter at 50ms, reduce
+- **Savings**: 30ms perceived latency reduction per command
+
+**R12: Batch tmux send-keys via stdin pipe** (Medium effort, high impact for rapid input)
+- Instead of spawning `tmux send-keys` per input, maintain a persistent connection
+- Use `tmux -C` (control mode) for programmatic interaction without child process spawning
+- **Savings**: Eliminate ~50-100ms process spawn overhead per input
+- **Risk**: Control mode has different semantics; needs careful testing with session persistence
+
+**R13: Skip overlay re-render during heavy output scroll** (Low risk)
+- When terminal is receiving >10KB/s output, hide overlay entirely (user isn't typing during heavy output)
+- Re-show overlay after 500ms of output silence
+- **Savings**: Eliminates unnecessary DOM overlay re-renders during build logs / test output
+
+---
+
+## 6. Polling & File Watchers
+
+### Current State
+- **SubagentWatcher**: 1s base poll, full scan throttled to every 5s, fs.watch() on known directories
+- **TranscriptWatcher**: 1 per session, fs.watch() primary with 1s poll fallback
+- **ImageWatcher**: chokidar per session with 100ms stability poll, burst limit 20/10s
+- **TeamWatcher**: chokidar primary with 30s poll fallback, LRU caches (50 teams, 200 tasks)
+- **RalphTracker**: Todo cleanup every 5 minutes
+
+### Scaling Profile (20 sessions)
+| Component | Instances | Frequency | Total ops/sec |
+|-----------|-----------|-----------|---------------|
+| SubagentWatcher | 1 (global) | Full scan every 5s | 0.2/s |
+| TranscriptWatcher | 20 | 1s poll (fallback) | 20/s max |
+| ImageWatcher | 20 | 100ms poll (during writes only) | 200/s burst |
+| TeamWatcher | 1 (global) | 30s poll (fallback) | 0.03/s |
+| SSE heartbeat | 1 (global) | 15s | 0.07/s |
+| SSE dead client check | 1 (global) | 30s | 0.03/s |
+| Mux stats collection | 1 (global) | 2s | 0.5/s |
+| **Total steady-state** | | | **~21/s** |
+
+### Recommendations
+
+**R14: Increase TranscriptWatcher poll interval to 2s** (Low risk)
+- Transcript changes are infrequent (new messages every few seconds at most)
+- fs.watch() is the primary mechanism; polling is fallback
+- **Savings**: Halves fallback filesystem checks (20/s → 10/s for 20 sessions)
+
+**R15: Share chokidar instances for co-located session directories** (Medium effort)
+- Sessions in the same parent directory could share a single chokidar watcher with depth:3
+- Common case: multiple sessions in `~/projects/foo/` — one watcher covers all
+- **Savings**: Reduce chokidar instances from 20 to ~5-10 for typical workloads
+
+---
+
+## 7. Frontend Asset Delivery
+
+### Current State
+- **app.js**: 12,027 lines (source) → esbuild minified → gzip/brotli compressed (~30-40KB gzipped)
+- **Static caching**: `maxAge: '1y'` via `@fastify/static`
+- **Service worker**: Push notification handler only — no asset caching
+- **No code splitting**: Single monolithic app.js bundle
+
+### Bottlenecks
+
+**B14: No cache-busting mechanism**
+- `maxAge: '1y'` means browsers cache aggressively
+- After deployment, users need `Ctrl+Shift+R` to see updates
+- No content hash in filenames or ETags for automatic invalidation
+
+**B15: Monolithic app.js**
+- All 12K lines loaded on initial page load regardless of which features are used
+- Ralph wizard, plan orchestrator UI, team management — all loaded upfront
+- Mobile loads the same bundle as desktop
+
+### Recommendations
+
+**R16: Add content hash to asset filenames** (Medium impact)
+- Build step: rename `app.js` → `app.[hash].js`
+- Generate a manifest or inject hash into HTML template
+- Keep `maxAge: '1y'` — cache invalidation happens via filename change
+- **Savings**: Eliminates stale cache issues after deployment; removes need for manual hard refresh
+
+**R17: Code-split app.js into core + feature modules** (High effort, medium impact)
+- Core (~4K lines): terminal, SSE, session management, tabs, input handling
+- Deferred (~8K lines): Ralph wizard, plan UI, team management, subagent windows, image viewer
+- Load deferred modules on first use via dynamic `import()` or lazy `<script>` injection
+- **Savings**: ~60% reduction in initial load size; faster time-to-interactive
+- **Risk**: Complexity increase; need to handle loading states for deferred features
+- **Note**: May not be worth the effort given the app is already gzipped to ~30-40KB
+
+---
+
+## 8. CSS Performance
+
+### Current State
+- **styles.css**: 7,153 lines with ~45 box-shadow uses, 2 backdrop-filter uses
+- Animations: GPU-accelerated keyframes for pulsing alerts, loading spinners
+- Z-index layering: well-organized (subagent 1000, plan 1100, log 2000, image 3000, overlay 7)
+
+### Recommendations
+
+**R18: Replace backdrop-filter with opaque overlay** (Low risk, covered in R8)
+
+**R19: Use `contain: content` on subagent windows** (Low risk)
+- Add CSS containment to subagent window containers
+- Prevents layout changes inside windows from triggering reflow on parent
+- Especially valuable with 50 windows: changes in one window won't invalidate others
+- ```css
+  .subagent-window { contain: content; }
+  ```
+- **Savings**: Reduces layout recalculation scope from global to per-window
+
+**R20: Use `content-visibility: auto` on off-screen subagent windows** (Low risk)
+- Browser skips rendering of off-screen windows entirely
+- Combined with `contain-intrinsic-size` to prevent layout shift
+- ```css
+  .subagent-window.minimized { content-visibility: hidden; }
+  ```
+- **Savings**: Browser skips paint/layout for minimized windows; complements R7
+
+---
+
+## 9. Memory & Scaling Limits
+
+### Current Budget (20 sessions)
+| Component | Per Session | Total | Status |
+|-----------|-----------|-------|--------|
+| Terminal buffer | 2MB | 40MB | Hard-limited, auto-trim |
+| Text output | 1MB | 20MB | Hard-limited, auto-trim |
+| Messages | ~1MB | 20MB | Capped at 1000, trims to 800 |
+| Respawn buffer | 1MB | 20MB | Hard-limited |
+| **Buffers total** | | **100MB** | Acceptable |
+| TranscriptWatcher | ~100KB | 2MB | |
+| ImageWatcher | ~50KB | 1MB | |
+| SubagentWatcher | ~500KB | 500KB | Global |
+| Frontend terminal cache | ~256KB | 5MB | LRU, max 20 entries |
+| **Total estimated** | | **~110MB** | Comfortable |
+
+### At Max Scale (50 sessions)
+- Buffers: ~250MB
+- Watchers: ~5MB
+- **Total: ~255MB** + Node.js overhead — acceptable on modern hardware
+
+### Potential Leak Vectors (All Mitigated)
+- `_shortIdCache` in server — unbounded Map, but entries are tiny (string→string); grows at O(sessions created), not O(events)
+- All CleanupManager-registered resources tracked and disposed on session stop
+- `isStopped` guard prevents new timers after session cleanup
+
+---
+
+## 10. Implementation Priority Matrix
+
+### Phase 1 — Quick Wins (1-2 hours each, low risk)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R6 | Targeted badge update | `app.js` (3207-3209) |
+| R3 | Canvas renderer on mobile | `app.js` (627-637) |
+| R8 | Replace backdrop-filter blur | `styles.css` (2246, 3098) |
+| R19 | CSS containment on subagent windows | `styles.css` |
+| R20 | `content-visibility: hidden` on minimized windows | `styles.css` |
+
+### Phase 2 — Medium Effort (half-day each)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R2 | Tiered SSE padding | `server.ts` (broadcast function) |
+| R7 | Lazy xterm.js for minimized subagents | `subagent-windows.js` |
+| R11 | Reduce Enter delay to 50ms | `app.js` (872-875), test with Ink |
+| R14 | TranscriptWatcher 2s poll | `transcript-watcher.ts` |
+| R16 | Content-hash asset filenames | `build.mjs`, `server.ts` |
+
+### Phase 3 — Larger Initiatives (1-2 days each)
+| # | Optimization | Files to Change |
+|---|-------------|-----------------|
+| R1 | Session-scoped SSE subscriptions | `server.ts`, `app.js` (SSE connect) |
+| R5 | Lazy Unicode11Addon loading | `app.js`, build pipeline |
+| R12 | Persistent tmux control mode | `tmux-manager.ts` |
+| R17 | Code-split app.js | `app.js`, `build.mjs`, HTML template |
+
+### Not Recommended (Low ROI or High Risk)
+| # | Why Not |
+|---|---------|
+| R4 | Dynamic scrollback adds complexity; memory savings marginal vs total budget |
+| R9 | Adaptive pending data cap adds state; current 64KB cap rarely matters |
+| R10 | LRUMap.delete() O(n) is theoretical; never triggered at current scale |
+| R15 | Shared chokidar instances add directory-matching complexity for minimal gain |
+
+---
+
+## Appendix: Key File Locations
+
+| Area | File | Key Lines |
+|------|------|-----------|
+| SSE broadcast | `src/web/server.ts` | 1961-1989 (broadcast), 1934-1959 (backpressure) |
+| Terminal batching | `src/web/server.ts` | 1994-2048 (per-session adaptive batching) |
+| Frame budget | `src/web/public/app.js` | 1370-1478 (flushPendingWrites, 64KB cap) |
+| Flicker filter | `src/web/public/app.js` | 1176-1255 (50ms sync wait, 256KB safety) |
+| Tab rendering | `src/web/public/app.js` | 3108-3357 (incremental + full rebuild) |
+| Tab switching | `src/web/public/app.js` | 3560-3760 (cache + chunked load + deferred UI) |
+| Local echo | `packages/xterm-zerolag-input/src/` | All files (overlay, prompt, CJK) |
+| Local echo integration | `src/web/public/app.js` | 640, 815-988 (input flow) |
+| Subagent windows | `src/web/public/subagent-windows.js` | Full file (window mgmt, drag, minimize) |
+| State persistence | `src/state-store.ts` | 161-250 (debounced save, incremental JSON) |
+| Buffer accumulator | `src/utils/buffer-accumulator.ts` | Full file (array chunks, lazy join) |
+| PTY handling | `src/session.ts` | 1046-1133 (data flow), 1173-1230 (parsing) |
+| Config limits | `src/config/` | 9 files (buffer, map, timing, auth, etc.) |
+| Anti-flicker docs | `docs/terminal-anti-flicker.md` | Architecture reference |
+| CSS | `src/web/public/styles.css` | 2246 (backdrop-filter), full file |
+| Build pipeline | `scripts/build.mjs` | 59-68 (minify + compress) |
@@ -1,12 +1,12 @@
 {
  "name": "aicodeman",
-  "version": "0.3.0",
+  "version": "0.3.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "aicodeman",
-      "version": "0.3.0",
+      "version": "0.3.1",
      "hasInstallScript": true,
      "license": "MIT",
      "workspaces": [
@@ -17,6 +17,8 @@
        "@fastify/compress": "^8.3.1",
        "@fastify/cookie": "^11.0.2",
        "@fastify/static": "^8.0.0",
+        "@remotion/compositor-linux-x64-gnu": "^4.0.432",
+        "@rspack/binding-linux-x64-gnu": "^1.7.7",
        "chalk": "^5.3.0",
        "chokidar": "^3.6.0",
        "commander": "^12.1.0",
@@ -515,6 +517,40 @@
        "node": ">=18"
      }
    },
+    "node_modules/@emnapi/core": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.8.1.tgz",
+      "integrity": "sha512-AvT9QFpxK0Zd8J0jopedNm+w/2fIzvtPKPjqyw9jwvBaReTTqPBk9Hixaz7KbjimP+QNz605/XnjFcDAL2pqBg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.1.0",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz",
+      "integrity": "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.1.0.tgz",
+      "integrity": "sha512-WI0DdZ8xFSbgMjR1sFsKABJ/C5OnRrjT06JXbZKexJGrDuPTzZdDYfFlsgcCXCyf+suG5QU2e/y1Wo2V/OapLQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
    "node_modules/@eslint-community/eslint-utils": {
      "version": "4.9.1",
      "dev": true,
@@ -1163,6 +1199,19 @@
        "@module-federation/sdk": "0.22.0"
      }
    },
+    "node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.0.7.tgz",
+      "integrity": "sha512-SeDnOO0Tk7Okiq6DbXmmBODgOAb9dp9gjlphokTUxmt8U3liIP1ZsozBahH69j/RJv+Rfs6IwUKHTgQYJ/HBAw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "^1.5.0",
+        "@emnapi/runtime": "^1.5.0",
+        "@tybys/wasm-util": "^0.10.1"
+      }
+    },
    "node_modules/@nodelib/fs.scandir": {
      "version": "2.1.5",
      "dev": true,
@@ -1324,6 +1373,95 @@
        "react-dom": ">=16.8.0"
      }
    },
+    "node_modules/@remotion/compositor-darwin-arm64": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-darwin-arm64/-/compositor-darwin-arm64-4.0.429.tgz",
+      "integrity": "sha512-V3Cv7TZyKulBPOBQJu2GONiKA+DDjGT6rWAc3WX4M9J9EDUwKiFFTDuTEpC7s4mcUDoAUXbnYE8ZlnWGaAuJhQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@remotion/compositor-darwin-x64": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-darwin-x64/-/compositor-darwin-x64-4.0.429.tgz",
+      "integrity": "sha512-vB8NM0j7gvCniu1dZ0p4MmTDN44Dvgd2iq6vStigzEQ1P2vlcx7qHEdVfaZBHsjdjMXD/UdwNmb34+lw3v6KEw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@remotion/compositor-linux-arm64-gnu": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-linux-arm64-gnu/-/compositor-linux-arm64-gnu-4.0.429.tgz",
+      "integrity": "sha512-F8N1HsRiCDw1EWWWI9hLNFTQy1mY7QLsWh0ywnrNCx62aF+8NpdYdW4pt/e7s4SQmkLh7enrkuqI0a6aGw4rpw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@remotion/compositor-linux-arm64-musl": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-linux-arm64-musl/-/compositor-linux-arm64-musl-4.0.429.tgz",
+      "integrity": "sha512-rvDjjascY9HAQ1nfbrdlVxyQ/xYj84jf0LylLmWJgr0kZVw5l8D/QXH4HTQeoPKhM3cBsCMKpW7oseHMoDyM5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@remotion/compositor-linux-x64-gnu": {
+      "version": "4.0.432",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-linux-x64-gnu/-/compositor-linux-x64-gnu-4.0.432.tgz",
+      "integrity": "sha512-KR/oSdCX6PBjO6K2KhYpC+QBbVMo8aXwQoTHaVwNl94+t7tyXDj7Vi8b3EJaIDSeXAc7lNjs54Tzx/WQ615Avg==",
+      "cpu": [
+        "x64"
+      ],
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@remotion/compositor-linux-x64-musl": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-linux-x64-musl/-/compositor-linux-x64-musl-4.0.429.tgz",
+      "integrity": "sha512-tlgWyrOWFDw1Z8IyPGDrQhd2B3saZ/sGRC7nN0XhcbMnaq3wxWe+cUSCJPT9kFNR9tKNCZ0y/jG/B8h6Z0GiHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@remotion/compositor-win32-x64-msvc": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-win32-x64-msvc/-/compositor-win32-x64-msvc-4.0.429.tgz",
+      "integrity": "sha512-YnpRTVwrOnDA8nYCZEP6Tdx+Ea+LQO4kXm9sjg2Rxe3s55lt+dUURl1yvOSKTW8nKZlfDAqldI1YDVvfD8NnCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
    "node_modules/@remotion/licensing": {
      "version": "4.0.429",
      "dev": true,
@@ -1393,6 +1531,19 @@
        "react-dom": ">=16.8.0"
      }
    },
+    "node_modules/@remotion/renderer/node_modules/@remotion/compositor-linux-x64-gnu": {
+      "version": "4.0.429",
+      "resolved": "https://registry.npmjs.org/@remotion/compositor-linux-x64-gnu/-/compositor-linux-x64-gnu-4.0.429.tgz",
+      "integrity": "sha512-YRe6+oSnNFpc2jgkrmAISAO2xUA0LqzE49ykqe0zCH3MXKtof76lMwDPoFJT1C4vDKErjSedltQNnnG7bPQGlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
    "node_modules/@remotion/renderer/node_modules/source-map": {
      "version": "0.8.0-beta.0",
      "dev": true,
@@ -1646,6 +1797,158 @@
        "@rspack/binding-win32-x64-msvc": "1.7.6"
      }
    },
+    "node_modules/@rspack/binding-darwin-arm64": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-1.7.6.tgz",
+      "integrity": "sha512-NZ9AWtB1COLUX1tA9HQQvWpTy07NSFfKBU8A6ylWd5KH8AePZztpNgLLAVPTuNO4CZXYpwcoclf8jG/luJcQdQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rspack/binding-darwin-x64": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-darwin-x64/-/binding-darwin-x64-1.7.6.tgz",
+      "integrity": "sha512-J2g6xk8ZS7uc024dNTGTHxoFzFovAZIRixUG7PiciLKTMP78svbSSWrmW6N8oAsAkzYfJWwQpVgWfFNRHvYxSw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rspack/binding-linux-arm64-gnu": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.7.6.tgz",
+      "integrity": "sha512-eQfcsaxhFrv5FmtaA7+O1F9/2yFDNIoPZzV/ZvqvFz5bBXVc4FAm/1fVpBg8Po/kX1h0chBc7Xkpry3cabFW8w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rspack/binding-linux-arm64-musl": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.7.6.tgz",
+      "integrity": "sha512-DfQXKiyPIl7i1yECHy4eAkSmlUzzsSAbOjgMuKn7pudsWf483jg0UUYutNgXSlBjc/QSUp7906Cg8oty9OfwPA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rspack/binding-linux-x64-gnu": {
+      "version": "1.7.7",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.7.7.tgz",
+      "integrity": "sha512-aRvf8gCI7jDeEN9i4u9fY5coa3ZAyHzGVA4ZhTJCgZ5wWA5A9SQewMSq7khS1WAAFE1USlk1tUuPujnrGoYrGg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rspack/binding-linux-x64-musl": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-1.7.6.tgz",
+      "integrity": "sha512-rEy6MHKob02t/77YNgr6dREyJ0e0tv1X6Xsg8Z5E7rPXead06zefUbfazj4RELYySWnM38ovZyJAkPx/gOn3VA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rspack/binding-wasm32-wasi": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-wasm32-wasi/-/binding-wasm32-wasi-1.7.6.tgz",
+      "integrity": "sha512-YupOrz0daSG+YBbCIgpDgzfMM38YpChv+afZpaxx5Ml7xPeAZIIdgWmLHnQ2rts73N2M1NspAiBwV00Xx0N4Vg==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@napi-rs/wasm-runtime": "1.0.7"
+      }
+    },
+    "node_modules/@rspack/binding-win32-arm64-msvc": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.7.6.tgz",
+      "integrity": "sha512-INj7aVXjBvlZ84kEhSK4kJ484ub0i+BzgnjDWOWM1K+eFYDZjLdAsQSS3fGGXwVc3qKbPIssFfnftATDMTEJHQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rspack/binding-win32-ia32-msvc": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.7.6.tgz",
+      "integrity": "sha512-lXGvC+z67UMcw58In12h8zCa9IyYRmuptUBMItQJzu+M278aMuD1nETyGLL7e4+OZ2lvrnnBIcjXN1hfw2yRzw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rspack/binding-win32-x64-msvc": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.7.6.tgz",
+      "integrity": "sha512-zeUxEc0ZaPpmaYlCeWcjSJUPuRRySiSHN23oJ2Xyw0jsQ01Qm4OScPdr0RhEOFuK/UE+ANyRtDo4zJsY52Hadw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rspack/binding/node_modules/@rspack/binding-linux-x64-gnu": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.7.6.tgz",
+      "integrity": "sha512-NdA+2X3lk2GGrMMnTGyYTzM3pn+zNjaqXqlgKmFBXvjfZqzSsKq3pdD1KHZCd5QHN+Fwvoszj0JFsquEVhE1og==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
    "node_modules/@rspack/core": {
      "version": "1.7.6",
      "dev": true,
@@ -1700,6 +2003,17 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+      "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
    "node_modules/@types/chai": {
      "version": "5.2.3",
      "dev": true,
@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "0.3.1",
+  "version": "0.3.7",
  "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",
@@ -51,6 +51,8 @@
    "@fastify/compress": "^8.3.1",
    "@fastify/cookie": "^11.0.2",
    "@fastify/static": "^8.0.0",
+    "@remotion/compositor-linux-x64-gnu": "^4.0.432",
+    "@rspack/binding-linux-x64-gnu": "^1.7.7",
    "chalk": "^5.3.0",
    "chokidar": "^3.6.0",
    "commander": "^12.1.0",
@@ -1,4 +1,50 @@
-import type { RenderParams, FontStyle } from './types.js';
+import type { RenderParams, FontStyle, XtermTerminal } from './types.js';
+
+// ─── CJK / fullwidth character width detection ───────────────────────
+
+/**
+ * Get visual cell width of a single character.
+ * CJK wide characters occupy 2 cells, others occupy 1.
+ * Prefers the terminal's Unicode addon when available.
+ */
+export function charCellWidth(terminal: XtermTerminal | null | undefined, ch: string): number {
+  if (terminal?.unicode?.getStringCellWidth) {
+    return terminal.unicode.getStringCellWidth(ch);
+  }
+  // Fallback: detect CJK wide characters by Unicode range
+  const code = ch.codePointAt(0);
+  if (
+    code !== undefined &&
+    code >= 0x1100 &&
+    (code <= 0x115f || // Hangul Jamo
+      (code >= 0x2e80 && code <= 0x303e) || // CJK Radicals, Kangxi, Ideographic
+      (code >= 0x3040 && code <= 0x33bf) || // Hiragana, Katakana, Bopomofo, CJK Compat
+      (code >= 0x3400 && code <= 0x4dbf) || // CJK Unified Ext A
+      (code >= 0x4e00 && code <= 0xa4cf) || // CJK Unified, Yi
+      (code >= 0xa960 && code <= 0xa97c) || // Hangul Jamo Extended-A
+      (code >= 0xac00 && code <= 0xd7a3) || // Hangul Syllables
+      (code >= 0xf900 && code <= 0xfaff) || // CJK Compat Ideographs
+      (code >= 0xfe30 && code <= 0xfe6f) || // CJK Compat Forms
+      (code >= 0xff01 && code <= 0xff60) || // Fullwidth Forms
+      (code >= 0xffe0 && code <= 0xffe6) || // Fullwidth Signs
+      (code >= 0x1f000 && code <= 0x1fbff) || // Mahjong, Domino, Emoji
+      (code >= 0x20000 && code <= 0x2ffff) || // CJK Unified Ext B-F
+      (code >= 0x30000 && code <= 0x3ffff)) // CJK Unified Ext G+
+  )
+    return 2;
+  return 1;
+}
+
+/**
+ * Get visual cell width of a string (sum of all character widths).
+ */
+export function stringCellWidth(terminal: XtermTerminal | null | undefined, str: string): number {
+  let w = 0;
+  for (const ch of str) w += charCellWidth(terminal, ch);
+  return w;
+}
+
+// ─── Overlay rendering ────────────────────────────────────────────────

 /**
 * Render the overlay content into the container element.
@@ -6,100 +52,114 @@ import type { RenderParams, FontStyle } from './types.js';
 * Creates per-character `<span>` elements positioned on an exact grid
 * matching xterm.js's canvas renderer. This avoids sub-pixel drift that
 * occurs with normal DOM text flow.
+ *
+ * CJK wide characters are rendered with double-width spans.
 */
 export function renderOverlay(container: HTMLDivElement, params: RenderParams): void {
-    const { lines, startCol, totalCols, cellW, cellH, charTop, charHeight, promptRow, font, showCursor, cursorColor } = params;
+  const {
+    lines,
+    startCol,
+    totalCols,
+    cellW,
+    cellH,
+    charTop,
+    charHeight,
+    promptRow,
+    font,
+    showCursor,
+    cursorColor,
+    terminal,
+  } = params;

-    // Position container at prompt row.
-    container.style.left = '0px';
-    container.style.top = (promptRow * cellH) + 'px';
+  // Position container at prompt row.
+  container.style.left = '0px';
+  container.style.top = promptRow * cellH + 'px';

-    // Clear and rebuild (typically 1-3 line divs, negligible cost)
-    container.innerHTML = '';
-    const fullWidthPx = totalCols * cellW;
+  // Clear and rebuild (typically 1-3 line divs, negligible cost)
+  container.innerHTML = '';
+  const fullWidthPx = totalCols * cellW;

-    for (let i = 0; i < lines.length; i++) {
-        const leftPx = i === 0 ? startCol * cellW : 0;
-        const widthPx = i === 0 ? (fullWidthPx - leftPx) : fullWidthPx;
-        const topPx = i * cellH;
-        const lineEl = makeLine(lines[i], leftPx, topPx, widthPx, cellH, cellW, charTop, charHeight, font);
-        container.appendChild(lineEl);
+  for (let i = 0; i < lines.length; i++) {
+    const leftPx = i === 0 ? startCol * cellW : 0;
+    const widthPx = i === 0 ? fullWidthPx - leftPx : fullWidthPx;
+    const topPx = i * cellH;
+    const lineEl = makeLine(lines[i], leftPx, topPx, widthPx, cellH, cellW, charTop, charHeight, font, terminal);
+    container.appendChild(lineEl);
+  }
+
+  // Block cursor at end of last line (use visual width for CJK support)
+  if (showCursor) {
+    const lastLine = lines[lines.length - 1];
+    const lastLineLeft = lines.length === 1 ? startCol : 0;
+    const cursorCol = lastLineLeft + stringCellWidth(terminal, lastLine);
+    if (cursorCol < totalCols) {
+      const cursor = document.createElement('span');
+      cursor.style.cssText = 'position:absolute;display:inline-block';
+      cursor.style.left = cursorCol * cellW + 'px';
+      cursor.style.top = (lines.length - 1) * cellH + 'px';
+      cursor.style.width = cellW + 'px';
+      cursor.style.height = cellH + 'px';
+      cursor.style.backgroundColor = cursorColor;
+      container.appendChild(cursor);
    }
+  }

-    // Block cursor at end of last line
-    if (showCursor) {
-        const lastLine = lines[lines.length - 1];
-        const lastLineLeft = lines.length === 1 ? startCol : 0;
-        const cursorCol = lastLineLeft + lastLine.length;
-        if (cursorCol < totalCols) {
-            const cursor = document.createElement('span');
-            cursor.style.cssText = 'position:absolute;display:inline-block';
-            cursor.style.left = (cursorCol * cellW) + 'px';
-            cursor.style.top = ((lines.length - 1) * cellH) + 'px';
-            cursor.style.width = cellW + 'px';
-            cursor.style.height = cellH + 'px';
-            cursor.style.backgroundColor = cursorColor;
-            container.appendChild(cursor);
-        }
-    }
-
-    container.style.display = '';
+  container.style.display = '';
 }

 /**
 * Create a styled line `<div>` with per-character grid positioning.
 *
- * Each character gets its own `<span>` placed at `i * cellW` pixels.
- * This matches xterm's canvas renderer where each glyph occupies exactly
- * one cell width, regardless of the actual glyph metrics.
+ * Each character gets its own `<span>` positioned by visual column offset.
+ * CJK wide characters occupy 2 cell widths.
 */
 function makeLine(
-    text: string,
-    leftPx: number,
-    topPx: number,
-    widthPx: number,
-    cellH: number,
-    cellW: number,
-    charTop: number,
-    charHeight: number,
-    font: FontStyle,
+  text: string,
+  leftPx: number,
+  topPx: number,
+  widthPx: number,
+  cellH: number,
+  cellW: number,
+  _charTop: number,
+  _charHeight: number,
+  font: FontStyle,
+  terminal?: XtermTerminal | null
 ): HTMLDivElement {
-    const el = document.createElement('div');
-    el.style.cssText = 'position:absolute;pointer-events:none';
-    el.style.backgroundColor = font.backgroundColor;
-    el.style.left = leftPx + 'px';
-    el.style.top = topPx + 'px';
-    el.style.width = widthPx + 'px';
-    // Extend background 1px past cell boundary to cover the compositing
-    // seam between the overlay layer (z-index:7) and the canvas layer below.
-    // The extra 1px lands in the next row's charTop gap (empty area before
-    // text rendering starts), so no canvas content is obscured.
-    el.style.height = (cellH + 1) + 'px';
+  const el = document.createElement('div');
+  el.style.cssText = 'position:absolute;pointer-events:none';
+  el.style.backgroundColor = font.backgroundColor;
+  el.style.left = leftPx + 'px';
+  el.style.top = topPx + 'px';
+  el.style.width = widthPx + 'px';
+  // Extend background 1px past cell boundary to cover the compositing
+  // seam between the overlay layer (z-index:7) and the canvas layer below.
+  // The extra 1px lands in the next row's charTop gap (empty area before
+  // text rendering starts), so no canvas content is obscured.
+  el.style.height = cellH + 1 + 'px';

-    // Spans fill the full cell height with matching lineHeight for natural
-    // CSS vertical centering.  No transform — any sub-pixel overhang past
-    // the line div causes visible anti-aliasing artifacts at the boundary.
-    // The ≤0.5px difference from canvas ceil() rounding is imperceptible.
+  // CJK wide chars occupy 2 cells — position by visual column offset
+  let colOffset = 0;
+  for (const ch of text) {
+    const cw = charCellWidth(terminal, ch);
+    const span = document.createElement('span');
+    // No ligatures — canvas renders each glyph independently.
+    span.style.cssText =
+      'position:absolute;display:inline-block;text-align:center;pointer-events:none;' +
+      "font-feature-settings:'liga' 0,'calt' 0";
+    span.style.left = colOffset * cellW + 'px';
+    span.style.top = '0px';
+    span.style.width = cw * cellW + 'px';
+    span.style.height = cellH + 'px';
+    span.style.lineHeight = cellH + 'px';
+    span.style.fontFamily = font.fontFamily;
+    span.style.fontSize = font.fontSize;
+    span.style.fontWeight = font.fontWeight;
+    span.style.color = font.color;
+    if (font.letterSpacing) span.style.letterSpacing = font.letterSpacing;
+    span.textContent = ch;
+    el.appendChild(span);
+    colOffset += cw;
+  }

-    for (let i = 0; i < text.length; i++) {
-        const span = document.createElement('span');
-        // No ligatures — canvas renders each glyph independently.
-        span.style.cssText =
-            'position:absolute;display:inline-block;text-align:center;pointer-events:none;' +
-            "font-feature-settings:'liga' 0,'calt' 0";
-        span.style.left = (i * cellW) + 'px';
-        span.style.top = '0px';
-        span.style.width = cellW + 'px';
-        span.style.height = cellH + 'px';
-        span.style.lineHeight = cellH + 'px';
-        span.style.fontFamily = font.fontFamily;
-        span.style.fontSize = font.fontSize;
-        span.style.fontWeight = font.fontWeight;
-        span.style.color = font.color;
-        if (font.letterSpacing) span.style.letterSpacing = font.letterSpacing;
-        span.textContent = text[i];
-        el.appendChild(span);
-    }
-
-    return el;
+  return el;
 }
@@ -5,28 +5,35 @@
 * Consumers pass their real Terminal instance — we only use these properties.
 */
 export interface XtermTerminal {
-    readonly element: HTMLElement | undefined;
-    readonly cols: number;
-    readonly rows: number;
-    readonly options: {
-        fontFamily?: string;
-        fontSize?: number;
-        fontWeight?: string | number;
-        theme?: {
-            background?: string;
-            foreground?: string;
-            cursor?: string;
-        };
+  readonly element: HTMLElement | undefined;
+  readonly cols: number;
+  readonly rows: number;
+  readonly options: {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    theme?: {
+      background?: string;
+      foreground?: string;
+      cursor?: string;
    };
-    readonly buffer: {
-        readonly active: {
-            readonly viewportY: number;
-            readonly baseY: number;
-            getLine(y: number): {
-                translateToString(trimRight?: boolean): string;
-            } | undefined;
-        };
+  };
+  readonly buffer: {
+    readonly active: {
+      readonly viewportY: number;
+      readonly baseY: number;
+      getLine(y: number):
+        | {
+            translateToString(trimRight?: boolean): string;
+          }
+        | undefined;
    };
+  };
+  /** Unicode addon (e.g. Unicode11Addon) for CJK wide character width */
+  readonly unicode?: {
+    getStringCellWidth(str: string): number;
+    activeVersion?: string;
+  };
 }

 /**
@@ -35,18 +42,18 @@ export interface XtermTerminal {
 * The consumer calls `terminal.loadAddon(addon)` which invokes `activate()`.
 */
 export interface XtermAddon {
-    activate(terminal: XtermTerminal): void;
-    dispose(): void;
+  activate(terminal: XtermTerminal): void;
+  dispose(): void;
 }

 /**
 * Position of the prompt in the terminal viewport.
 */
 export interface PromptPosition {
-    /** Viewport-relative row (0 = top of viewport) */
-    row: number;
-    /** Column of the prompt marker character */
-    col: number;
+  /** Viewport-relative row (0 = top of viewport) */
+  row: number;
+  /** Column of the prompt marker character */
+  col: number;
 }

 /**
@@ -60,112 +67,114 @@ export interface PromptPosition {
 * - `custom`: Full escape hatch — provide your own finder function
 */
 export type PromptFinder =
-    | { type: 'character'; char: string; offset?: number }
-    | { type: 'regex'; pattern: RegExp; offset?: number }
-    | { type: 'custom'; find: (terminal: XtermTerminal) => PromptPosition | null; offset?: number };
+  | { type: 'character'; char: string; offset?: number }
+  | { type: 'regex'; pattern: RegExp; offset?: number }
+  | { type: 'custom'; find: (terminal: XtermTerminal) => PromptPosition | null; offset?: number };

 /**
 * Configuration options for ZerolagInputAddon.
 */
 export interface ZerolagInputOptions {
-    /**
-     * How to find the prompt in the terminal buffer.
-     *
-     * The `offset` controls how many characters after the prompt marker
-     * the user input begins (e.g., `"> "` = offset 2).
-     *
-     * @default { type: 'character', char: '>', offset: 2 }
-     */
-    prompt?: PromptFinder;
+  /**
+   * How to find the prompt in the terminal buffer.
+   *
+   * The `offset` controls how many characters after the prompt marker
+   * the user input begins (e.g., `"> "` = offset 2).
+   *
+   * @default { type: 'character', char: '>', offset: 2 }
+   */
+  prompt?: PromptFinder;

-    /**
-     * Z-index for the overlay element.
-     * @default 7
-     */
-    zIndex?: number;
+  /**
+   * Z-index for the overlay element.
+   * @default 7
+   */
+  zIndex?: number;

-    /**
-     * Background color for the overlay.
-     * Set to `'transparent'` to disable the opaque background.
-     * @default Read from terminal.options.theme.background
-     */
-    backgroundColor?: string;
+  /**
+   * Background color for the overlay.
+   * Set to `'transparent'` to disable the opaque background.
+   * @default Read from terminal.options.theme.background
+   */
+  backgroundColor?: string;

-    /**
-     * Foreground color for overlay text.
-     * @default Read from terminal.options.theme.foreground
-     */
-    foregroundColor?: string;
+  /**
+   * Foreground color for overlay text.
+   * @default Read from terminal.options.theme.foreground
+   */
+  foregroundColor?: string;

-    /**
-     * Whether to show a block cursor at the end of the overlay text.
-     * @default true
-     */
-    showCursor?: boolean;
+  /**
+   * Whether to show a block cursor at the end of the overlay text.
+   * @default true
+   */
+  showCursor?: boolean;

-    /**
-     * Cursor color (block cursor at end of text).
-     * @default Read from terminal.options.theme.cursor
-     */
-    cursorColor?: string;
+  /**
+   * Cursor color (block cursor at end of text).
+   * @default Read from terminal.options.theme.cursor
+   */
+  cursorColor?: string;

-    /**
-     * Scroll debounce time in ms for re-rendering when user scrolls
-     * back to the bottom of the terminal.
-     * @default 50
-     */
-    scrollDebounceMs?: number;
+  /**
+   * Scroll debounce time in ms for re-rendering when user scrolls
+   * back to the bottom of the terminal.
+   * @default 50
+   */
+  scrollDebounceMs?: number;
 }

 /**
 * Read-only state snapshot of the overlay.
 */
 export interface ZerolagInputState {
-    /** Characters typed but not yet acknowledged by the server */
-    pendingText: string;
-    /** Number of characters flushed to PTY but echo not yet received */
-    flushedLength: number;
-    /** Text content of the flushed portion */
-    flushedText: string;
-    /** Whether the overlay is currently visible */
-    visible: boolean;
-    /** Last detected prompt position, if any */
-    promptPosition: PromptPosition | null;
+  /** Characters typed but not yet acknowledged by the server */
+  pendingText: string;
+  /** Number of characters flushed to PTY but echo not yet received */
+  flushedLength: number;
+  /** Text content of the flushed portion */
+  flushedText: string;
+  /** Whether the overlay is currently visible */
+  visible: boolean;
+  /** Last detected prompt position, if any */
+  promptPosition: PromptPosition | null;
 }

 /** Cell dimensions in CSS pixels. */
 export interface CellDimensions {
-    width: number;
-    height: number;
-    /** Vertical offset (px) from cell top to where characters render. */
-    charTop: number;
-    /** Height of the character rendering area (px). */
-    charHeight: number;
+  width: number;
+  height: number;
+  /** Vertical offset (px) from cell top to where characters render. */
+  charTop: number;
+  /** Height of the character rendering area (px). */
+  charHeight: number;
 }

 /** Parameters for the overlay renderer. */
 export interface RenderParams {
-    lines: string[];
-    startCol: number;
-    totalCols: number;
-    cellW: number;
-    cellH: number;
-    /** Vertical offset (px) from cell top to character rendering area. */
-    charTop: number;
-    /** Height of the character rendering area (px). */
-    charHeight: number;
-    promptRow: number;
-    font: FontStyle;
-    showCursor: boolean;
-    cursorColor: string;
+  lines: string[];
+  startCol: number;
+  totalCols: number;
+  cellW: number;
+  cellH: number;
+  /** Vertical offset (px) from cell top to character rendering area. */
+  charTop: number;
+  /** Height of the character rendering area (px). */
+  charHeight: number;
+  promptRow: number;
+  font: FontStyle;
+  showCursor: boolean;
+  cursorColor: string;
+  /** Terminal instance for CJK wide character width detection */
+  terminal?: XtermTerminal | null;
 }

 /** Cached font style properties for overlay rendering. */
 export interface FontStyle {
-    fontFamily: string;
-    fontSize: string;
-    fontWeight: string;
-    color: string;
-    backgroundColor: string;
-    letterSpacing: string;
+  fontFamily: string;
+  fontSize: string;
+  fontWeight: string;
+  color: string;
+  backgroundColor: string;
+  letterSpacing: string;
 }
@@ -0,0 +1,843 @@
+/**
+ * Comprehensive CJK wide character test plan for PR #30.
+ *
+ * Tests all 7 items from the test plan:
+ * 1. Chinese text input — no character overlap
+ * 2. CJK text renders with correct double-width spacing
+ * 3. Japanese (こんにちは) and Korean (안녕하세요) input
+ * 4. Cursor positions correctly after CJK characters
+ * 5. Long CJK input wraps at correct column boundary
+ * 6. Existing ASCII input is unaffected
+ * 7. Teammate terminal panels render CJK correctly (app.js embedded copy)
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { renderOverlay, charCellWidth, stringCellWidth } from '../src/overlay-renderer.js';
+import type { RenderParams, FontStyle } from '../src/types.js';
+import { createMockTerminal } from './helpers.js';
+import { ZerolagInputAddon } from '../src/zerolag-input-addon.js';
+
+// ─── Shared fixtures ─────────────────────────────────────────────────
+
+const FONT: FontStyle = {
+  fontFamily: 'monospace',
+  fontSize: '14px',
+  fontWeight: 'normal',
+  color: '#eeeeee',
+  backgroundColor: '#0d0d0d',
+  letterSpacing: '',
+};
+
+function makeParams(overrides: Partial<RenderParams> = {}): RenderParams {
+  return {
+    lines: ['hello'],
+    startCol: 2,
+    totalCols: 80,
+    cellW: 10,
+    cellH: 17,
+    charTop: 2,
+    charHeight: 14,
+    promptRow: 0,
+    font: FONT,
+    showCursor: true,
+    cursorColor: '#e0e0e0',
+    ...overrides,
+  };
+}
+
+/** Extract span data from a rendered line div */
+function getSpans(lineDiv: HTMLDivElement) {
+  const spans: { text: string; left: number; width: number }[] = [];
+  for (let i = 0; i < lineDiv.children.length; i++) {
+    const span = lineDiv.children[i] as HTMLSpanElement;
+    spans.push({
+      text: span.textContent || '',
+      left: parseFloat(span.style.left),
+      width: parseFloat(span.style.width),
+    });
+  }
+  return spans;
+}
+
+// ─── Addon setup helpers ─────────────────────────────────────────────
+
+let cleanups: (() => void)[] = [];
+
+afterEach(() => {
+  for (const fn of cleanups) fn();
+  cleanups = [];
+});
+
+function tracked(lines: string[] = ['$ '], promptChar = '$') {
+  const mock = createMockTerminal({ buffer: { lines }, cols: 80 });
+  const addon = new ZerolagInputAddon({
+    prompt: { type: 'character', char: promptChar, offset: 2 },
+  });
+  mock.terminal.loadAddon(addon);
+  cleanups.push(() => {
+    addon.dispose();
+    mock.cleanup();
+  });
+  return { addon, mock };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 1: Chinese text input — no character overlap
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 1: Chinese text — no character overlap', () => {
+  it('consecutive Chinese characters have contiguous non-overlapping spans', () => {
+    const container = document.createElement('div');
+    const text = '你好世界';
+    renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+
+    expect(spans.length).toBe(4);
+
+    // Each span: left = previous span's (left + width), width = 20px (2 cells)
+    for (let i = 0; i < spans.length; i++) {
+      expect(spans[i].width).toBe(20); // 2 cells * 10px
+      if (i > 0) {
+        const expectedLeft = spans[i - 1].left + spans[i - 1].width;
+        expect(spans[i].left).toBe(expectedLeft);
+      }
+    }
+  });
+
+  it('Chinese sentence (simulated pinyin output) renders without gaps or overlaps', () => {
+    const container = document.createElement('div');
+    const text = '我是一个测试';
+    renderOverlay(container, makeParams({ lines: [text], cellW: 8 }));
+
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+
+    expect(spans.length).toBe(6);
+
+    // Verify contiguous positioning
+    let expectedLeft = 0;
+    for (const span of spans) {
+      expect(span.left).toBe(expectedLeft);
+      expect(span.width).toBe(16); // 2 * 8px
+      expectedLeft += span.width;
+    }
+
+    // Total visual width should be 6 chars * 2 cells * 8px = 96px
+    expect(expectedLeft).toBe(96);
+  });
+
+  it('mixed Chinese + ASCII has no gaps between spans', () => {
+    const container = document.createElement('div');
+    const text = 'hello你好world';
+    renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+
+    // h(10) e(10) l(10) l(10) o(10) 你(20) 好(20) w(10) o(10) r(10) l(10) d(10)
+    expect(spans.length).toBe(12);
+
+    // Verify contiguity: no gaps between any adjacent spans
+    for (let i = 1; i < spans.length; i++) {
+      const prevEnd = spans[i - 1].left + spans[i - 1].width;
+      expect(spans[i].left).toBe(prevEnd);
+    }
+  });
+
+  it('addChar with Chinese characters accumulates correctly in addon', () => {
+    const { addon } = tracked();
+    for (const ch of '你好世界') {
+      addon.addChar(ch);
+    }
+    expect(addon.pendingText).toBe('你好世界');
+    expect(addon.hasPending).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 2: CJK text renders with correct double-width spacing
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 2: CJK double-width spacing', () => {
+  it('charCellWidth returns 2 for CJK Unified Ideographs (0x4E00-0x9FFF)', () => {
+    // Common Chinese characters
+    const chars = '中文测试你好世界天地人';
+    for (const ch of chars) {
+      expect(charCellWidth(null, ch)).toBe(2);
+    }
+  });
+
+  it('charCellWidth returns 2 for CJK Extension A (0x3400-0x4DBF)', () => {
+    expect(charCellWidth(null, '\u3400')).toBe(2); // First Extension A char
+    expect(charCellWidth(null, '\u4DB5')).toBe(2); // One of the last Extension A chars
+  });
+
+  it('charCellWidth returns 2 for CJK Radicals (0x2E80-0x2EFF)', () => {
+    expect(charCellWidth(null, '\u2E80')).toBe(2); // CJK Radical Repeat
+  });
+
+  it('charCellWidth returns 2 for fullwidth ASCII forms (0xFF01-0xFF5E)', () => {
+    expect(charCellWidth(null, '\uFF01')).toBe(2); // ！
+    expect(charCellWidth(null, '\uFF21')).toBe(2); // Ａ
+    expect(charCellWidth(null, '\uFF41')).toBe(2); // ａ
+    expect(charCellWidth(null, '\uFF10')).toBe(2); // ０
+  });
+
+  it('charCellWidth returns 2 for CJK Compatibility Ideographs (0xF900-0xFAFF)', () => {
+    expect(charCellWidth(null, '\uF900')).toBe(2);
+  });
+
+  it('stringCellWidth calculates correct visual width for CJK strings', () => {
+    expect(stringCellWidth(null, '你好')).toBe(4); // 2 + 2
+    expect(stringCellWidth(null, '你好世界')).toBe(8); // 4 * 2
+    expect(stringCellWidth(null, 'hi你好')).toBe(6); // 1 + 1 + 2 + 2
+    expect(stringCellWidth(null, '你a好b')).toBe(6); // 2 + 1 + 2 + 1
+    expect(stringCellWidth(null, 'abc你好def')).toBe(10); // 3 + 4 + 3
+  });
+
+  it('CJK span widths are exactly 2 * cellW pixels', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['你'], cellW: 8.4 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.width).toBe('16.8px'); // 2 * 8.4
+  });
+
+  it('ASCII span widths remain 1 * cellW pixels', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['a'], cellW: 8.4 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.width).toBe('8.4px'); // 1 * 8.4
+  });
+
+  it('terminal unicode addon is preferred over fallback when available', () => {
+    const mockTerminal = {
+      unicode: {
+        getStringCellWidth: (s: string) => {
+          // Custom width: treat 'W' as wide
+          return s === 'W' ? 2 : 1;
+        },
+      },
+    } as any;
+    expect(charCellWidth(mockTerminal, 'W')).toBe(2);
+    expect(charCellWidth(mockTerminal, 'a')).toBe(1);
+    // Fallback ignores terminal addon result for actual CJK
+    expect(charCellWidth(null, '你')).toBe(2);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 3: Japanese (こんにちは) and Korean (안녕하세요) input
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 3: Japanese and Korean input', () => {
+  describe('Japanese', () => {
+    it('charCellWidth returns 2 for Hiragana (0x3040-0x309F)', () => {
+      const hiragana = 'あいうえおかきくけこさしすせそ';
+      for (const ch of hiragana) {
+        expect(charCellWidth(null, ch)).toBe(2);
+      }
+    });
+
+    it('charCellWidth returns 2 for Katakana (0x30A0-0x30FF)', () => {
+      const katakana = 'アイウエオカキクケコサシスセソ';
+      for (const ch of katakana) {
+        expect(charCellWidth(null, ch)).toBe(2);
+      }
+    });
+
+    it('Japanese greeting renders with correct span positions', () => {
+      const container = document.createElement('div');
+      const text = 'こんにちは';
+      renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+
+      const lineDiv = container.children[0] as HTMLDivElement;
+      const spans = getSpans(lineDiv);
+
+      expect(spans.length).toBe(5);
+      // こ(0,20) ん(20,20) に(40,20) ち(60,20) は(80,20)
+      expect(spans[0]).toEqual({ text: 'こ', left: 0, width: 20 });
+      expect(spans[1]).toEqual({ text: 'ん', left: 20, width: 20 });
+      expect(spans[2]).toEqual({ text: 'に', left: 40, width: 20 });
+      expect(spans[3]).toEqual({ text: 'ち', left: 60, width: 20 });
+      expect(spans[4]).toEqual({ text: 'は', left: 80, width: 20 });
+    });
+
+    it('mixed Japanese + ASCII positions correctly', () => {
+      const container = document.createElement('div');
+      const text = 'hello こんにちは';
+      renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+
+      const lineDiv = container.children[0] as HTMLDivElement;
+      const spans = getSpans(lineDiv);
+
+      // h(0) e(10) l(20) l(30) o(40) space(50) こ(60) ん(80) に(100) ち(120) は(140)
+      expect(spans.length).toBe(11);
+      expect(spans[5]).toEqual({ text: ' ', left: 50, width: 10 }); // space
+      expect(spans[6]).toEqual({ text: 'こ', left: 60, width: 20 }); // first CJK after ASCII
+    });
+
+    it('addon handles Japanese input via addChar', () => {
+      const { addon } = tracked();
+      for (const ch of 'こんにちは') {
+        addon.addChar(ch);
+      }
+      expect(addon.pendingText).toBe('こんにちは');
+    });
+
+    it('addon handles Japanese input via appendText (paste)', () => {
+      const { addon } = tracked();
+      addon.appendText('こんにちは世界');
+      expect(addon.pendingText).toBe('こんにちは世界');
+      expect(addon.hasPending).toBe(true);
+    });
+
+    it('stringCellWidth correct for Japanese greeting', () => {
+      expect(stringCellWidth(null, 'こんにちは')).toBe(10); // 5 * 2
+    });
+  });
+
+  describe('Korean', () => {
+    it('charCellWidth returns 2 for Hangul Syllables (0xAC00-0xD7A3)', () => {
+      const hangul = '가나다라마바사아자차카타파하';
+      for (const ch of hangul) {
+        expect(charCellWidth(null, ch)).toBe(2);
+      }
+    });
+
+    it('charCellWidth returns 2 for Hangul Jamo (0x1100-0x115F)', () => {
+      expect(charCellWidth(null, '\u1100')).toBe(2); // ᄀ
+      expect(charCellWidth(null, '\u1112')).toBe(2); // ᄒ
+    });
+
+    it('Korean greeting renders with correct span positions', () => {
+      const container = document.createElement('div');
+      const text = '안녕하세요';
+      renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+
+      const lineDiv = container.children[0] as HTMLDivElement;
+      const spans = getSpans(lineDiv);
+
+      expect(spans.length).toBe(5);
+      expect(spans[0]).toEqual({ text: '안', left: 0, width: 20 });
+      expect(spans[1]).toEqual({ text: '녕', left: 20, width: 20 });
+      expect(spans[2]).toEqual({ text: '하', left: 40, width: 20 });
+      expect(spans[3]).toEqual({ text: '세', left: 60, width: 20 });
+      expect(spans[4]).toEqual({ text: '요', left: 80, width: 20 });
+    });
+
+    it('addon handles Korean input', () => {
+      const { addon } = tracked();
+      addon.appendText('안녕하세요');
+      expect(addon.pendingText).toBe('안녕하세요');
+      expect(addon.hasPending).toBe(true);
+    });
+
+    it('removeChar removes Korean characters one at a time', () => {
+      const { addon } = tracked();
+      addon.appendText('안녕');
+      addon.removeChar();
+      expect(addon.pendingText).toBe('안');
+      addon.removeChar();
+      expect(addon.pendingText).toBe('');
+    });
+
+    it('stringCellWidth correct for Korean greeting', () => {
+      expect(stringCellWidth(null, '안녕하세요')).toBe(10); // 5 * 2
+    });
+  });
+
+  describe('mixed CJK scripts', () => {
+    it('Chinese + Japanese + Korean in one string', () => {
+      const text = '你好こんにちは안녕';
+      expect(stringCellWidth(null, text)).toBe(18); // 9 chars * 2 each
+
+      const container = document.createElement('div');
+      renderOverlay(container, makeParams({ lines: [text], cellW: 10 }));
+      const lineDiv = container.children[0] as HTMLDivElement;
+      const spans = getSpans(lineDiv);
+
+      // All 9 CJK chars: contiguous double-width spans
+      expect(spans.length).toBe(9);
+      let expectedLeft = 0;
+      for (const span of spans) {
+        expect(span.left).toBe(expectedLeft);
+        expect(span.width).toBe(20);
+        expectedLeft += 20;
+      }
+    });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 4: Cursor positions correctly after CJK characters
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 4: Cursor positioning after CJK', () => {
+  it('cursor after Chinese text on first line', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世界'],
+        startCol: 2,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // cursorCol = startCol(2) + stringCellWidth('你好世界')(8) = 10
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('100px'); // 10 * 10px
+  });
+
+  it('cursor after Japanese text on first line', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['こんにちは'],
+        startCol: 2,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // cursorCol = 2 + 10 = 12
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('120px');
+  });
+
+  it('cursor after Korean text on first line', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['안녕하세요'],
+        startCol: 2,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // cursorCol = 2 + 10 = 12
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('120px');
+  });
+
+  it('cursor after mixed ASCII + CJK', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['hi你好'],
+        startCol: 3,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // cursorCol = 3 + stringCellWidth('hi你好')(6) = 9
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('90px');
+  });
+
+  it('cursor on wrapped line after CJK text', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世界', '再见'],
+        startCol: 2,
+        cellW: 10,
+        cellH: 20,
+        showCursor: true,
+      })
+    );
+    // Last line is '再见', starts at col 0 (wrapped line), width = 4
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('40px'); // 0 + 4 = 4, * 10 = 40
+    expect(cursor.style.top).toBe('20px'); // row 1 * cellH
+  });
+
+  it('cursor hidden when it would exceed totalCols', () => {
+    const container = document.createElement('div');
+    // 4 CJK chars = 8 visual cols, startCol=73, cursorCol = 73 + 8 = 81 > 80
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世界'],
+        startCol: 73,
+        totalCols: 80,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // Should be 1 line div, no cursor span (cursor at col 81 >= totalCols 80)
+    // Actually cursor check is cursorCol < totalCols, so at 81 it's hidden
+    const children = container.children;
+    // If cursor is rendered, last child would be a cursor span
+    // With cursorCol 81 >= 80, cursor should NOT be rendered
+    expect(children.length).toBe(1); // only line div
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 5: Long CJK input wraps at correct column boundary
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 5: CJK line wrapping at column boundaries', () => {
+  it('CJK chars wrap when they would overflow first line', () => {
+    const container = document.createElement('div');
+    // totalCols=10, startCol=2 → firstLineCols=8
+    // Each CJK char = 2 cols → first line fits 4 chars (8 cols)
+    // 5th char wraps to second line
+    const text = '你好世界啊'; // 5 chars = 10 visual cols
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世界', '啊'],
+        startCol: 2,
+        totalCols: 10,
+        cellW: 10,
+        cellH: 20,
+      })
+    );
+
+    expect(container.children.length).toBe(3); // 2 line divs + cursor
+
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.children.length).toBe(4); // 你好世界
+    expect(line1.style.left).toBe('20px'); // startCol * cellW
+
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.children.length).toBe(1); // 啊
+    expect(line2.style.left).toBe('0px'); // wrapped line starts at col 0
+    expect(line2.style.top).toBe('20px'); // second row
+  });
+
+  it('CJK char that would partially overflow stays on next line', () => {
+    // totalCols=9, startCol=2 → firstLineCols=7
+    // CJK chars are 2-wide. 3 chars = 6 cols (fits). 4th char = 8 cols > 7. Wraps.
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世', '界'],
+        startCol: 2,
+        totalCols: 9,
+        cellW: 10,
+      })
+    );
+
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.children.length).toBe(3); // 3 CJK chars fit (6 cols <= 7)
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.children.length).toBe(1); // 界 wraps
+  });
+
+  it('addon _render splits CJK text into visual lines correctly', () => {
+    // Narrow terminal: 10 cols, startCol=2 → firstLineCols=8 → 4 CJK chars
+    const mock = createMockTerminal({
+      buffer: { lines: ['$ '] },
+      cols: 10,
+    });
+    const addon = new ZerolagInputAddon({
+      prompt: { type: 'character', char: '$', offset: 2 },
+    });
+    mock.terminal.loadAddon(addon);
+    cleanups.push(() => {
+      addon.dispose();
+      mock.cleanup();
+    });
+
+    // Type 6 CJK chars (12 visual cols)
+    for (const ch of '你好世界再见') {
+      addon.addChar(ch);
+    }
+    expect(addon.pendingText).toBe('你好世界再见');
+    expect(addon.hasPending).toBe(true);
+  });
+
+  it('mixed ASCII + CJK wraps correctly', () => {
+    const container = document.createElement('div');
+    // totalCols=10, startCol=2 → firstLineCols=8
+    // 'ab' = 2 cols, '你好' = 4 cols, 'cd' = 2 cols → total 8 cols (fits line 1)
+    // '世' = 2 cols → wraps to line 2
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['ab你好cd', '世'],
+        startCol: 2,
+        totalCols: 10,
+        cellW: 10,
+      })
+    );
+
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.children.length).toBe(6); // a,b,你,好,c,d
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.children.length).toBe(1); // 世
+  });
+
+  it('odd column count: CJK char does not split across boundary', () => {
+    // totalCols=11, startCol=2 → firstLineCols=9
+    // 4 CJK chars = 8 cols (fits). 5th CJK = 10 cols > 9 (wraps).
+    // 1 empty column remains on first line (CJK can't fit in 1 col).
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世界', '啊'],
+        startCol: 2,
+        totalCols: 11,
+        cellW: 10,
+      })
+    );
+
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.children.length).toBe(4); // 4 chars = 8 cols, 5th would need 10 > 9
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.children.length).toBe(1);
+  });
+
+  it('CJK fills entire wrapped line', () => {
+    const container = document.createElement('div');
+    // totalCols=6, startCol=0 → firstLineCols=6
+    // 3 CJK chars = 6 cols (fills line 1), next 3 fill line 2
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好世', '界再见'],
+        startCol: 0,
+        totalCols: 6,
+        cellW: 10,
+      })
+    );
+
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.children.length).toBe(3);
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.children.length).toBe(3);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 6: Existing ASCII input is unaffected
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 6: ASCII input — no regression', () => {
+  it('ASCII characters still get 1-cell-wide spans', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['abcdef'], cellW: 10 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+
+    for (const span of spans) {
+      expect(span.width).toBe(10); // 1 * cellW
+    }
+  });
+
+  it('ASCII span positions are sequential at 1-cell intervals', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['xyz'], cellW: 8.4 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+
+    expect(spans[0].left).toBe(0);
+    expect(spans[1].left).toBeCloseTo(8.4, 5);
+    expect(spans[2].left).toBeCloseTo(16.8, 5);
+  });
+
+  it('ASCII cursor positions at correct column', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['hello'],
+        startCol: 3,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // cursor at startCol(3) + 5 = 8
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('80px');
+  });
+
+  it('charCellWidth returns 1 for all printable ASCII', () => {
+    for (let code = 32; code < 127; code++) {
+      const ch = String.fromCharCode(code);
+      expect(charCellWidth(null, ch)).toBe(1);
+    }
+  });
+
+  it('stringCellWidth equals length for pure ASCII', () => {
+    expect(stringCellWidth(null, 'hello world')).toBe(11);
+    expect(stringCellWidth(null, 'test123!@#')).toBe(10);
+    expect(stringCellWidth(null, '')).toBe(0);
+  });
+
+  it('ASCII multi-line wrapping is unaffected', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['abcde', 'fgh'],
+        startCol: 5,
+        totalCols: 10,
+        cellW: 10,
+        cellH: 20,
+      })
+    );
+
+    expect(container.children.length).toBe(3); // 2 lines + cursor
+    const line1 = container.children[0] as HTMLDivElement;
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line1.children.length).toBe(5);
+    expect(line2.children.length).toBe(3);
+    expect(line1.style.left).toBe('50px'); // startCol * cellW
+    expect(line2.style.left).toBe('0px');
+  });
+
+  it('addon addChar/removeChar/clear work for ASCII', () => {
+    const { addon } = tracked();
+    addon.addChar('h');
+    addon.addChar('e');
+    addon.addChar('l');
+    addon.addChar('l');
+    addon.addChar('o');
+    expect(addon.pendingText).toBe('hello');
+
+    addon.removeChar();
+    expect(addon.pendingText).toBe('hell');
+
+    addon.clear();
+    expect(addon.pendingText).toBe('');
+    expect(addon.hasPending).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST 7: Teammate terminal panels render CJK correctly
+//
+// Teammate panels share the global xterm-zerolag-input.js vendor bundle
+// (loaded via <script> in index.html). This is the IIFE build of the
+// same package source tested in tests 1-6. The build pipeline is:
+//   src/overlay-renderer.ts → tsup → dist/index.global.js → vendor copy
+//
+// Since all terminals (main + teammate) use the same LocalEchoOverlay
+// class from the global scope, CJK correctness is guaranteed by:
+// (a) The package source handles CJK correctly (tests 1-6 above)
+// (b) The IIFE build bundles the exact same charCellWidth / makeLine code
+//
+// These tests verify the exported module includes CJK-aware functions
+// and that teammate-style terminal instances work identically.
+// ═══════════════════════════════════════════════════════════════════════
+
+describe('Test 7: Teammate terminal panels render CJK correctly', () => {
+  it('package exports charCellWidth and stringCellWidth', () => {
+    // These are the CJK-aware functions that the IIFE build exposes
+    expect(typeof charCellWidth).toBe('function');
+    expect(typeof stringCellWidth).toBe('function');
+  });
+
+  it('ZerolagInputAddon (used by LocalEchoOverlay) handles CJK in teammate terminals', () => {
+    // Simulate a teammate terminal panel: separate terminal instance,
+    // same addon class, different prompt character
+    const mock = createMockTerminal({
+      buffer: { lines: ['❯ '] },
+      cols: 40,
+    });
+    const addon = new ZerolagInputAddon({
+      prompt: { type: 'character', char: '❯', offset: 2 },
+    });
+    mock.terminal.loadAddon(addon);
+    cleanups.push(() => {
+      addon.dispose();
+      mock.cleanup();
+    });
+
+    // Type CJK in teammate terminal
+    for (const ch of '你好世界') {
+      addon.addChar(ch);
+    }
+    expect(addon.pendingText).toBe('你好世界');
+    expect(addon.hasPending).toBe(true);
+  });
+
+  it('teammate terminal with narrow width wraps CJK correctly', () => {
+    // Teammate panels are often narrower (sidebar, split view)
+    const mock = createMockTerminal({
+      buffer: { lines: ['❯ '] },
+      cols: 12, // narrow panel
+    });
+    const addon = new ZerolagInputAddon({
+      prompt: { type: 'character', char: '❯', offset: 2 },
+    });
+    mock.terminal.loadAddon(addon);
+    cleanups.push(() => {
+      addon.dispose();
+      mock.cleanup();
+    });
+
+    // Type 6 CJK chars (12 visual cols) with startCol=2 → only 10 available
+    // First line: 5 CJK = 10 cols. 6th wraps.
+    for (const ch of '你好世界再见') {
+      addon.addChar(ch);
+    }
+    expect(addon.pendingText).toBe('你好世界再见');
+  });
+
+  it('mixed CJK scripts render identically in teammate and main terminals', () => {
+    // Verify that the same input produces the same overlay output
+    // regardless of which terminal instance it's on
+    const text = '你好こんにちは안녕';
+
+    // "Main" terminal
+    const container1 = document.createElement('div');
+    renderOverlay(container1, makeParams({ lines: [text], cellW: 10 }));
+    const line1 = container1.children[0] as HTMLDivElement;
+    const spans1 = getSpans(line1);
+
+    // "Teammate" terminal (same params — same bundle)
+    const container2 = document.createElement('div');
+    renderOverlay(container2, makeParams({ lines: [text], cellW: 10 }));
+    const line2 = container2.children[0] as HTMLDivElement;
+    const spans2 = getSpans(line2);
+
+    // Identical rendering
+    expect(spans1.length).toBe(spans2.length);
+    for (let i = 0; i < spans1.length; i++) {
+      expect(spans1[i]).toEqual(spans2[i]);
+    }
+  });
+
+  it('CJK rendering correct in overlay with teammate-typical prompt (❯)', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['こんにちは世界'],
+        startCol: 2, // after ❯ prompt
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const spans = getSpans(lineDiv);
+    expect(spans.length).toBe(7);
+
+    // All CJK, all double-width, contiguous
+    let expectedLeft = 0;
+    for (const span of spans) {
+      expect(span.left).toBe(expectedLeft);
+      expect(span.width).toBe(20);
+      expectedLeft += 20;
+    }
+
+    // Cursor position: startCol(2) + 14 visual cols = 16
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('160px');
+  });
+});
@@ -1,300 +1,420 @@
 import { describe, it, expect } from 'vitest';
-import { renderOverlay } from '../src/overlay-renderer.js';
+import { renderOverlay, charCellWidth, stringCellWidth } from '../src/overlay-renderer.js';
 import type { RenderParams, FontStyle } from '../src/types.js';

 const FONT: FontStyle = {
-    fontFamily: 'monospace',
-    fontSize: '14px',
-    fontWeight: 'normal',
-    color: '#eeeeee',
-    backgroundColor: '#0d0d0d',
-    letterSpacing: '',
+  fontFamily: 'monospace',
+  fontSize: '14px',
+  fontWeight: 'normal',
+  color: '#eeeeee',
+  backgroundColor: '#0d0d0d',
+  letterSpacing: '',
 };

 function makeParams(overrides: Partial<RenderParams> = {}): RenderParams {
-    return {
-        lines: ['hello'],
-        startCol: 2,
-        totalCols: 80,
-        cellW: 8.4,
-        cellH: 17,
-        charTop: 2,
-        charHeight: 14,
-        promptRow: 10,
-        font: FONT,
-        showCursor: true,
-        cursorColor: '#e0e0e0',
-        ...overrides,
-    };
+  return {
+    lines: ['hello'],
+    startCol: 2,
+    totalCols: 80,
+    cellW: 8.4,
+    cellH: 17,
+    charTop: 2,
+    charHeight: 14,
+    promptRow: 10,
+    font: FONT,
+    showCursor: true,
+    cursorColor: '#e0e0e0',
+    ...overrides,
+  };
 }

 describe('renderOverlay', () => {
-    it('positions container at prompt row', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ promptRow: 5 }));
-        expect(container.style.top).toBe((5 * 17) + 'px');
-        expect(container.style.left).toBe('0px');
-    });
+  it('positions container at prompt row', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ promptRow: 5 }));
+    expect(container.style.top).toBe(5 * 17 + 'px');
+    expect(container.style.left).toBe('0px');
+  });

-    it('creates per-character spans in a line div', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['abc'] }));
+  it('creates per-character spans in a line div', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['abc'] }));

-        // Line div + cursor span
-        expect(container.children.length).toBe(2);
+    // Line div + cursor span
+    expect(container.children.length).toBe(2);

-        const lineDiv = container.children[0] as HTMLDivElement;
-        expect(lineDiv.children.length).toBe(3); // a, b, c
+    const lineDiv = container.children[0] as HTMLDivElement;
+    expect(lineDiv.children.length).toBe(3); // a, b, c

-        const spanA = lineDiv.children[0] as HTMLSpanElement;
-        expect(spanA.textContent).toBe('a');
-        expect(spanA.style.left).toBe('0px');
+    const spanA = lineDiv.children[0] as HTMLSpanElement;
+    expect(spanA.textContent).toBe('a');
+    expect(spanA.style.left).toBe('0px');

-        const spanB = lineDiv.children[1] as HTMLSpanElement;
-        expect(spanB.textContent).toBe('b');
-        expect(spanB.style.left).toBe('8.4px');
+    const spanB = lineDiv.children[1] as HTMLSpanElement;
+    expect(spanB.textContent).toBe('b');
+    expect(spanB.style.left).toBe('8.4px');

-        const spanC = lineDiv.children[2] as HTMLSpanElement;
-        expect(spanC.textContent).toBe('c');
-        expect(spanC.style.left).toBe('16.8px');
-    });
+    const spanC = lineDiv.children[2] as HTMLSpanElement;
+    expect(spanC.textContent).toBe('c');
+    expect(spanC.style.left).toBe('16.8px');
+  });

-    it('sets span width to cellW', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['x'], cellW: 9.5 }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.width).toBe('9.5px');
-    });
+  it('sets span width to cellW', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['x'], cellW: 9.5 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.width).toBe('9.5px');
+  });

-    it('applies font styles to spans', () => {
-        const font: FontStyle = {
-            fontFamily: 'Fira Code',
-            fontSize: '16px',
-            fontWeight: 'bold',
-            color: '#ff0000',
-            backgroundColor: '#000000',
-            letterSpacing: '0.5px',
-        };
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['A'], font }));
+  it('applies font styles to spans', () => {
+    const font: FontStyle = {
+      fontFamily: 'Fira Code',
+      fontSize: '16px',
+      fontWeight: 'bold',
+      color: '#ff0000',
+      backgroundColor: '#000000',
+      letterSpacing: '0.5px',
+    };
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['A'], font }));

-        const lineDiv = container.children[0] as HTMLDivElement;
-        // jsdom normalizes hex to rgb()
-        expect(lineDiv.style.backgroundColor).toBe('rgb(0, 0, 0)');
+    const lineDiv = container.children[0] as HTMLDivElement;
+    // jsdom normalizes hex to rgb()
+    expect(lineDiv.style.backgroundColor).toBe('rgb(0, 0, 0)');

-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.fontFamily).toBe('Fira Code');
-        expect(span.style.fontSize).toBe('16px');
-        expect(span.style.fontWeight).toBe('bold');
-        expect(span.style.color).toBe('rgb(255, 0, 0)');
-        expect(span.style.letterSpacing).toBe('0.5px');
-    });
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.fontFamily).toBe('Fira Code');
+    expect(span.style.fontSize).toBe('16px');
+    expect(span.style.fontWeight).toBe('bold');
+    expect(span.style.color).toBe('rgb(255, 0, 0)');
+    expect(span.style.letterSpacing).toBe('0.5px');
+  });

-    it('offsets first line by startCol', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['hi'], startCol: 5, cellW: 10 }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        // First line left = startCol * cellW
-        expect(lineDiv.style.left).toBe('50px');
-    });
+  it('offsets first line by startCol', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['hi'], startCol: 5, cellW: 10 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    // First line left = startCol * cellW
+    expect(lineDiv.style.left).toBe('50px');
+  });

-    it('renders cursor at end of text', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({
-            lines: ['ab'],
-            startCol: 3,
-            cellW: 10,
-            cellH: 20,
-            showCursor: true,
-            cursorColor: '#ff00ff',
-        }));
+  it('renders cursor at end of text', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['ab'],
+        startCol: 3,
+        cellW: 10,
+        cellH: 20,
+        showCursor: true,
+        cursorColor: '#ff00ff',
+      })
+    );

-        // Last child is cursor (after line div)
-        const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
-        // cursorCol = startCol(3) + text.length(2) = 5
-        expect(cursor.style.left).toBe('50px');
-        expect(cursor.style.width).toBe('10px');
-        expect(cursor.style.height).toBe('20px');
-        // jsdom normalizes hex to rgb()
-        expect(cursor.style.backgroundColor).toBe('rgb(255, 0, 255)');
-    });
+    // Last child is cursor (after line div)
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    // cursorCol = startCol(3) + text.length(2) = 5
+    expect(cursor.style.left).toBe('50px');
+    expect(cursor.style.width).toBe('10px');
+    expect(cursor.style.height).toBe('20px');
+    // jsdom normalizes hex to rgb()
+    expect(cursor.style.backgroundColor).toBe('rgb(255, 0, 255)');
+  });

-    it('does not render cursor when showCursor is false', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['ab'], showCursor: false }));
-        // Only line div, no cursor
-        expect(container.children.length).toBe(1);
-    });
+  it('does not render cursor when showCursor is false', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['ab'], showCursor: false }));
+    // Only line div, no cursor
+    expect(container.children.length).toBe(1);
+  });

-    it('renders multi-line text', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({
-            lines: ['first', 'second'],
-            startCol: 5,
-            cellW: 10,
-            cellH: 20,
-        }));
+  it('renders multi-line text', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['first', 'second'],
+        startCol: 5,
+        cellW: 10,
+        cellH: 20,
+      })
+    );

-        // 2 line divs + cursor
-        expect(container.children.length).toBe(3);
+    // 2 line divs + cursor
+    expect(container.children.length).toBe(3);

-        const line1 = container.children[0] as HTMLDivElement;
-        expect(line1.style.left).toBe('50px'); // startCol * cellW
-        expect(line1.style.top).toBe('0px');
-        expect(line1.children.length).toBe(5); // 'first'
+    const line1 = container.children[0] as HTMLDivElement;
+    expect(line1.style.left).toBe('50px'); // startCol * cellW
+    expect(line1.style.top).toBe('0px');
+    expect(line1.children.length).toBe(5); // 'first'

-        const line2 = container.children[1] as HTMLDivElement;
-        expect(line2.style.left).toBe('0px'); // wrapped lines start at col 0
-        expect(line2.style.top).toBe('20px'); // second row
-        expect(line2.children.length).toBe(6); // 'second'
-    });
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line2.style.left).toBe('0px'); // wrapped lines start at col 0
+    expect(line2.style.top).toBe('20px'); // second row
+    expect(line2.children.length).toBe(6); // 'second'
+  });

-    it('clears previous content on re-render', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['abc'] }));
-        expect(container.children.length).toBe(2); // line + cursor
+  it('clears previous content on re-render', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['abc'] }));
+    expect(container.children.length).toBe(2); // line + cursor

-        renderOverlay(container, makeParams({ lines: ['xy'] }));
-        expect(container.children.length).toBe(2); // line + cursor (rebuilt)
+    renderOverlay(container, makeParams({ lines: ['xy'] }));
+    expect(container.children.length).toBe(2); // line + cursor (rebuilt)

-        const lineDiv = container.children[0] as HTMLDivElement;
-        expect(lineDiv.children.length).toBe(2); // x, y
-    });
+    const lineDiv = container.children[0] as HTMLDivElement;
+    expect(lineDiv.children.length).toBe(2); // x, y
+  });

-    it('shows container (display not none)', () => {
-        const container = document.createElement('div');
-        container.style.display = 'none';
-        renderOverlay(container, makeParams());
-        expect(container.style.display).toBe('');
-    });
+  it('shows container (display not none)', () => {
+    const container = document.createElement('div');
+    container.style.display = 'none';
+    renderOverlay(container, makeParams());
+    expect(container.style.display).toBe('');
+  });

-    // ─── Anti-flicker / compositing seam tests ────────────────────
+  // ─── Anti-flicker / compositing seam tests ────────────────────

-    it('line div height extends 1px past cellH to cover compositing seam', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['abc'], cellH: 19 }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        // cellH + 1 = 20px — the extra 1px covers the compositing seam
-        expect(lineDiv.style.height).toBe('20px');
-    });
+  it('line div height extends 1px past cellH to cover compositing seam', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['abc'], cellH: 19 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    // cellH + 1 = 20px — the extra 1px covers the compositing seam
+    expect(lineDiv.style.height).toBe('20px');
+  });

-    it('line div height is cellH+1 for various cell heights', () => {
-        for (const cellH of [15, 17, 19, 22]) {
-            const container = document.createElement('div');
-            renderOverlay(container, makeParams({ lines: ['x'], cellH }));
-            const lineDiv = container.children[0] as HTMLDivElement;
-            expect(lineDiv.style.height).toBe((cellH + 1) + 'px');
-        }
-    });
+  it('line div height is cellH+1 for various cell heights', () => {
+    for (const cellH of [15, 17, 19, 22]) {
+      const container = document.createElement('div');
+      renderOverlay(container, makeParams({ lines: ['x'], cellH }));
+      const lineDiv = container.children[0] as HTMLDivElement;
+      expect(lineDiv.style.height).toBe(cellH + 1 + 'px');
+    }
+  });

-    it('multi-line overlay has cellH+1 height on each line div', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({
-            lines: ['first', 'second'],
-            cellH: 19,
-        }));
-        const line1 = container.children[0] as HTMLDivElement;
-        const line2 = container.children[1] as HTMLDivElement;
-        expect(line1.style.height).toBe('20px');
-        expect(line2.style.height).toBe('20px');
-    });
+  it('multi-line overlay has cellH+1 height on each line div', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['first', 'second'],
+        cellH: 19,
+      })
+    );
+    const line1 = container.children[0] as HTMLDivElement;
+    const line2 = container.children[1] as HTMLDivElement;
+    expect(line1.style.height).toBe('20px');
+    expect(line2.style.height).toBe('20px');
+  });

-    // ─── Span vertical centering tests ────────────────────────────
+  // ─── Span vertical centering tests ────────────────────────────

-    it('span uses full cellH for height and lineHeight (CSS centering)', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['a'], cellH: 19 }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.height).toBe('19px');
-        expect(span.style.lineHeight).toBe('19px');
-    });
+  it('span uses full cellH for height and lineHeight (CSS centering)', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['a'], cellH: 19 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.height).toBe('19px');
+    expect(span.style.lineHeight).toBe('19px');
+  });

-    it('span top is 0px (no vertical offset / no transform)', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['a'], cellH: 19 }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.top).toBe('0px');
-        // No translateY transform — sub-pixel overhang causes artifacts
-        expect(span.style.transform).toBe('');
-    });
+  it('span top is 0px (no vertical offset / no transform)', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['a'], cellH: 19 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.top).toBe('0px');
+    // No translateY transform — sub-pixel overhang causes artifacts
+    expect(span.style.transform).toBe('');
+  });

-    // ─── Font rendering tests ─────────────────────────────────────
+  // ─── Font rendering tests ─────────────────────────────────────

-    it('span disables ligatures via font-feature-settings', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['fi'] }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        // Check cssText includes the ligature-disabling settings
-        // jsdom may normalize whitespace; check that both liga and calt are disabled
-        expect(span.style.cssText).toContain("font-feature-settings:");
-        expect(span.style.cssText).toContain("'liga' 0");
-        expect(span.style.cssText).toContain("'calt' 0");
-    });
+  it('span disables ligatures via font-feature-settings', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['fi'] }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    // Check cssText includes the ligature-disabling settings
+    // jsdom may normalize whitespace; check that both liga and calt are disabled
+    expect(span.style.cssText).toContain('font-feature-settings:');
+    expect(span.style.cssText).toContain("'liga' 0");
+    expect(span.style.cssText).toContain("'calt' 0");
+  });

-    it('span has text-align: center for glyph centering', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['m'] }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.textAlign).toBe('center');
-    });
+  it('span has text-align: center for glyph centering', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['m'] }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.textAlign).toBe('center');
+  });

-    it('span has pointer-events: none', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: ['a'] }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        const span = lineDiv.children[0] as HTMLSpanElement;
-        expect(span.style.pointerEvents).toBe('none');
-    });
+  it('span has pointer-events: none', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['a'] }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    const span = lineDiv.children[0] as HTMLSpanElement;
+    expect(span.style.pointerEvents).toBe('none');
+  });

-    // ─── Multi-line cursor positioning ────────────────────────────
+  // ─── Multi-line cursor positioning ────────────────────────────

-    it('cursor on wrapped line uses col 0 as base', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({
-            lines: ['first', 'ab'],
-            startCol: 5,
-            cellW: 10,
-            cellH: 20,
-            showCursor: true,
-        }));
-        // Cursor at end of second line: col = 0 + 2 = 2
-        const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
-        expect(cursor.style.left).toBe('20px'); // 2 * 10
-        expect(cursor.style.top).toBe('20px'); // row 1 * cellH
-    });
+  it('cursor on wrapped line uses col 0 as base', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['first', 'ab'],
+        startCol: 5,
+        cellW: 10,
+        cellH: 20,
+        showCursor: true,
+      })
+    );
+    // Cursor at end of second line: col = 0 + 2 = 2
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('20px'); // 2 * 10
+    expect(cursor.style.top).toBe('20px'); // row 1 * cellH
+  });

-    // ─── charTop/charHeight passed through ────────────────────────
+  // ─── charTop/charHeight passed through ────────────────────────

-    it('accepts charTop and charHeight params without error', () => {
-        const container = document.createElement('div');
-        expect(() => renderOverlay(container, makeParams({
-            lines: ['test'],
-            charTop: 2,
-            charHeight: 14,
-        }))).not.toThrow();
-        expect(container.children.length).toBeGreaterThan(0);
-    });
+  it('accepts charTop and charHeight params without error', () => {
+    const container = document.createElement('div');
+    expect(() =>
+      renderOverlay(
+        container,
+        makeParams({
+          lines: ['test'],
+          charTop: 2,
+          charHeight: 14,
+        })
+      )
+    ).not.toThrow();
+    expect(container.children.length).toBeGreaterThan(0);
+  });

-    // ─── Line div positioning regression ──────────────────────────
+  // ─── Line div positioning regression ──────────────────────────

-    it('line div background color matches font.backgroundColor', () => {
-        const container = document.createElement('div');
-        const font: FontStyle = { ...FONT, backgroundColor: '#1a1a1a' };
-        renderOverlay(container, makeParams({ lines: ['x'], font }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        // jsdom normalizes hex to rgb()
-        expect(lineDiv.style.backgroundColor).toBe('rgb(26, 26, 26)');
-    });
+  it('line div background color matches font.backgroundColor', () => {
+    const container = document.createElement('div');
+    const font: FontStyle = { ...FONT, backgroundColor: '#1a1a1a' };
+    renderOverlay(container, makeParams({ lines: ['x'], font }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    // jsdom normalizes hex to rgb()
+    expect(lineDiv.style.backgroundColor).toBe('rgb(26, 26, 26)');
+  });

-    it('empty line produces line div with no spans', () => {
-        const container = document.createElement('div');
-        renderOverlay(container, makeParams({ lines: [''] }));
-        const lineDiv = container.children[0] as HTMLDivElement;
-        expect(lineDiv.children.length).toBe(0);
-    });
+  it('empty line produces line div with no spans', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: [''] }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    expect(lineDiv.children.length).toBe(0);
+  });
+
+  // ─── CJK wide character support ───────────────────────────────
+
+  it('CJK characters get double-width spans', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['a你b'], cellW: 10 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    expect(lineDiv.children.length).toBe(3);
+
+    const spanA = lineDiv.children[0] as HTMLSpanElement;
+    expect(spanA.textContent).toBe('a');
+    expect(spanA.style.left).toBe('0px');
+    expect(spanA.style.width).toBe('10px'); // 1 cell
+
+    const spanCJK = lineDiv.children[1] as HTMLSpanElement;
+    expect(spanCJK.textContent).toBe('你');
+    expect(spanCJK.style.left).toBe('10px'); // col 1
+    expect(spanCJK.style.width).toBe('20px'); // 2 cells
+
+    const spanB = lineDiv.children[2] as HTMLSpanElement;
+    expect(spanB.textContent).toBe('b');
+    expect(spanB.style.left).toBe('30px'); // col 3
+    expect(spanB.style.width).toBe('10px'); // 1 cell
+  });
+
+  it('cursor position accounts for CJK width', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({
+        lines: ['你好'],
+        startCol: 2,
+        cellW: 10,
+        showCursor: true,
+      })
+    );
+    // 你(2) + 好(2) = 4 visual cols, cursor at startCol(2) + 4 = 6
+    const cursor = container.children[container.children.length - 1] as HTMLSpanElement;
+    expect(cursor.style.left).toBe('60px');
+  });
+
+  it('mixed ASCII and CJK characters position correctly', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: ['hi你'], cellW: 8 }));
+    const lineDiv = container.children[0] as HTMLDivElement;
+    // h(col 0), i(col 1), 你(col 2, width 2)
+    const spanH = lineDiv.children[0] as HTMLSpanElement;
+    expect(spanH.style.left).toBe('0px');
+    const spanI = lineDiv.children[1] as HTMLSpanElement;
+    expect(spanI.style.left).toBe('8px');
+    const spanCJK = lineDiv.children[2] as HTMLSpanElement;
+    expect(spanCJK.style.left).toBe('16px');
+    expect(spanCJK.style.width).toBe('16px');
+  });
+});
+
+describe('charCellWidth', () => {
+  it('returns 1 for ASCII characters', () => {
+    expect(charCellWidth(null, 'a')).toBe(1);
+    expect(charCellWidth(null, '!')).toBe(1);
+    expect(charCellWidth(null, ' ')).toBe(1);
+  });
+
+  it('returns 2 for CJK ideographs', () => {
+    expect(charCellWidth(null, '你')).toBe(2);
+    expect(charCellWidth(null, '好')).toBe(2);
+    expect(charCellWidth(null, '中')).toBe(2);
+  });
+
+  it('returns 2 for Japanese hiragana', () => {
+    expect(charCellWidth(null, 'こ')).toBe(2);
+    expect(charCellWidth(null, 'ん')).toBe(2);
+  });
+
+  it('returns 2 for Korean syllables', () => {
+    expect(charCellWidth(null, '안')).toBe(2);
+    expect(charCellWidth(null, '녕')).toBe(2);
+  });
+
+  it('returns 2 for fullwidth forms', () => {
+    expect(charCellWidth(null, '\uff01')).toBe(2); // ！
+    expect(charCellWidth(null, '\uff21')).toBe(2); // Ａ
+  });
+
+  it('uses terminal unicode addon when available', () => {
+    const mockTerminal = {
+      unicode: { getStringCellWidth: (s: string) => (s === 'W' ? 2 : 1) },
+    } as any;
+    expect(charCellWidth(mockTerminal, 'W')).toBe(2);
+    expect(charCellWidth(mockTerminal, 'n')).toBe(1);
+  });
+});
+
+describe('stringCellWidth', () => {
+  it('sums individual character widths', () => {
+    expect(stringCellWidth(null, 'abc')).toBe(3);
+    expect(stringCellWidth(null, '你好')).toBe(4);
+    expect(stringCellWidth(null, 'a你b')).toBe(4);
+  });
+
+  it('returns 0 for empty string', () => {
+    expect(stringCellWidth(null, '')).toBe(0);
+  });
 });
@@ -0,0 +1 @@
+tools/remotion/public
@@ -56,7 +56,7 @@ appendFileSync(
 );

 // 4. Minify frontend assets
-run('minify app.js', 'npx esbuild dist/web/public/app.js --minify --drop:console --outfile=dist/web/public/app.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 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');

@@ -30,6 +30,7 @@ import { join } from 'node:path';
 import { EventEmitter } from 'node:events';
 import { getAugmentedPath } from './utils/claude-cli-resolver.js';
 import { ANSI_ESCAPE_PATTERN_SIMPLE } from './utils/index.js';
+import { AI_CHECK_MAX_BACKOFF_MS } from './config/ai-defaults.js';

 // ========== Security Validation ==========

@@ -534,10 +535,7 @@ export abstract class AiCheckerBase<
      // P1-005: Exponential backoff for errors
      // Base cooldown * 2^(consecutiveErrors-1), capped at 5 minutes
      const backoffMultiplier = Math.pow(2, this.consecutiveErrors - 1);
-      const backoffCooldownMs = Math.min(
-        this.config.errorCooldownMs * backoffMultiplier,
-        5 * 60 * 1000 // Max 5 minutes
-      );
+      const backoffCooldownMs = Math.min(this.config.errorCooldownMs * backoffMultiplier, AI_CHECK_MAX_BACKOFF_MS);
      this.log(`Exponential backoff: ${Math.round(backoffCooldownMs / 1000)}s (error #${this.consecutiveErrors})`);
      this.startCooldown(backoffCooldownMs);
    }
@@ -30,7 +30,14 @@ import {
  type AiCheckerResultBase,
  type AiCheckerStateBase,
 } from './ai-checker-base.js';
-import { AI_CHECK_MODEL, AI_IDLE_CHECK_MAX_CONTEXT } from './config/ai-defaults.js';
+import {
+  AI_CHECK_MODEL,
+  AI_IDLE_CHECK_MAX_CONTEXT,
+  AI_IDLE_CHECK_TIMEOUT_MS,
+  AI_IDLE_CHECK_COOLDOWN_MS,
+  AI_IDLE_CHECK_ERROR_COOLDOWN_MS,
+  AI_CHECK_MAX_CONSECUTIVE_ERRORS,
+} from './config/ai-defaults.js';

 // ========== Types ==========

@@ -48,10 +55,10 @@ const DEFAULT_AI_CHECK_CONFIG: AiIdleCheckConfig = {
  enabled: true,
  model: AI_CHECK_MODEL,
  maxContextChars: AI_IDLE_CHECK_MAX_CONTEXT,
-  checkTimeoutMs: 90000,
-  cooldownMs: 180000,
-  errorCooldownMs: 60000,
-  maxConsecutiveErrors: 3,
+  checkTimeoutMs: AI_IDLE_CHECK_TIMEOUT_MS,
+  cooldownMs: AI_IDLE_CHECK_COOLDOWN_MS,
+  errorCooldownMs: AI_IDLE_CHECK_ERROR_COOLDOWN_MS,
+  maxConsecutiveErrors: AI_CHECK_MAX_CONSECUTIVE_ERRORS,
 };

 /** Pattern to match IDLE or WORKING as the first word of output */
@@ -29,7 +29,14 @@ import {
  type AiCheckerResultBase,
  type AiCheckerStateBase,
 } from './ai-checker-base.js';
-import { AI_CHECK_MODEL, AI_PLAN_CHECK_MAX_CONTEXT } from './config/ai-defaults.js';
+import {
+  AI_CHECK_MODEL,
+  AI_PLAN_CHECK_MAX_CONTEXT,
+  AI_PLAN_CHECK_TIMEOUT_MS,
+  AI_PLAN_CHECK_COOLDOWN_MS,
+  AI_PLAN_CHECK_ERROR_COOLDOWN_MS,
+  AI_CHECK_MAX_CONSECUTIVE_ERRORS,
+} from './config/ai-defaults.js';

 // ========== Types ==========

@@ -47,10 +54,10 @@ const DEFAULT_PLAN_CHECK_CONFIG: AiPlanCheckConfig = {
  enabled: true,
  model: AI_CHECK_MODEL,
  maxContextChars: AI_PLAN_CHECK_MAX_CONTEXT,
-  checkTimeoutMs: 60000,
-  cooldownMs: 30000,
-  errorCooldownMs: 30000,
-  maxConsecutiveErrors: 3,
+  checkTimeoutMs: AI_PLAN_CHECK_TIMEOUT_MS,
+  cooldownMs: AI_PLAN_CHECK_COOLDOWN_MS,
+  errorCooldownMs: AI_PLAN_CHECK_ERROR_COOLDOWN_MS,
+  maxConsecutiveErrors: AI_CHECK_MAX_CONSECUTIVE_ERRORS,
 };

 /** Pattern to match PLAN_MODE or NOT_PLAN_MODE as the first word(s) of output */
@@ -1,13 +1,17 @@
 /**
- * @fileoverview Default model and context limits for AI-powered checkers.
+ * @fileoverview Default model, context limits, and timing for AI-powered checkers.
 *
- * Centralizes the AI model identifier and context window sizes used by
- * the idle checker, plan checker, respawn controller defaults, and
- * respawn route fallbacks. Change the model here when upgrading.
+ * Centralizes the AI model identifier, context window sizes, and timeout/cooldown
+ * defaults used by the idle checker, plan checker, respawn controller defaults,
+ * and respawn route fallbacks. Change values here when tuning AI check behavior.
 *
 * @module config/ai-defaults
 */

+// ============================================================================
+// Model & Context
+// ============================================================================
+
 /** Default model for AI idle and plan checkers */
 export const AI_CHECK_MODEL = 'claude-opus-4-5-20251101';

@@ -16,3 +20,39 @@ export const AI_IDLE_CHECK_MAX_CONTEXT = 16000;

 /** Max context chars for plan checker (~2k tokens, plan mode UI is compact) */
 export const AI_PLAN_CHECK_MAX_CONTEXT = 8000;
+
+// ============================================================================
+// AI Idle Checker Timing
+// ============================================================================
+
+/** Timeout for AI idle check (90 seconds — thinking can be slow) */
+export const AI_IDLE_CHECK_TIMEOUT_MS = 90_000;
+
+/** Cooldown after WORKING verdict (3 minutes) */
+export const AI_IDLE_CHECK_COOLDOWN_MS = 180_000;
+
+/** Cooldown after AI idle check error (1 minute) */
+export const AI_IDLE_CHECK_ERROR_COOLDOWN_MS = 60_000;
+
+// ============================================================================
+// AI Plan Checker Timing
+// ============================================================================
+
+/** Timeout for AI plan check (60 seconds — allows time for thinking) */
+export const AI_PLAN_CHECK_TIMEOUT_MS = 60_000;
+
+/** Cooldown after NOT_PLAN_MODE verdict (30 seconds) */
+export const AI_PLAN_CHECK_COOLDOWN_MS = 30_000;
+
+/** Cooldown after AI plan check error (30 seconds) */
+export const AI_PLAN_CHECK_ERROR_COOLDOWN_MS = 30_000;
+
+// ============================================================================
+// Shared AI Checker Limits
+// ============================================================================
+
+/** Max consecutive errors before disabling an AI checker */
+export const AI_CHECK_MAX_CONSECUTIVE_ERRORS = 3;
+
+/** Maximum exponential backoff cap for AI checker errors (5 minutes) */
+export const AI_CHECK_MAX_BACKOFF_MS = 5 * 60 * 1000;
@@ -73,3 +73,16 @@ export const MAX_CONSECUTIVE_ERRORS = 5;

 /** Error counter reset interval — forgives errors after quiet period (ms) */
 export const ERROR_RESET_MS = 60_000;
+
+// ============================================================================
+// Common Cleanup Intervals
+// ============================================================================
+
+/** Standard 1-minute cleanup/check interval used by multiple subsystems (ms) */
+export const CLEANUP_CHECK_INTERVAL_MS = 60_000;
+
+/** Standard 1-hour max age for stale/completed data (ms) */
+export const STALE_DATA_MAX_AGE_MS = 60 * 60 * 1000;
+
+/** Standard 5-minute inactivity timeout for streams and caches (ms) */
+export const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
@@ -16,6 +16,7 @@ import { existsSync, statSync, realpathSync } from 'node:fs';
 import { resolve, relative, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { EventEmitter } from 'node:events';
+import { CLEANUP_CHECK_INTERVAL_MS, INACTIVITY_TIMEOUT_MS } from './config/server-timing.js';

 // ========== Configuration Constants ==========

@@ -39,7 +40,7 @@ const MAX_STREAMS_PER_SESSION = 5;
 * Inactivity timeout for streams (5 minutes).
 * Streams with no data for this long will be auto-closed.
 */
-const STREAM_INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
+const STREAM_INACTIVITY_TIMEOUT_MS = INACTIVITY_TIMEOUT_MS;

 // ========== Types ==========

@@ -129,7 +130,7 @@ export class FileStreamManager extends EventEmitter {
  constructor() {
    super();
    // Start cleanup timer for inactive streams
-    this.cleanupTimer = setInterval(() => this.cleanupInactiveStreams(), 60 * 1000);
+    this.cleanupTimer = setInterval(() => this.cleanupInactiveStreams(), CLEANUP_CHECK_INTERVAL_MS);
  }

  // ========== Public Methods ==========
@@ -9,6 +9,7 @@

 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { execPattern } from './utils/index.js';

 // Pattern to extract completion phrase from CLAUDE.md
 // Matches <promise>PHRASE</promise> with optional whitespace
@@ -83,9 +84,7 @@ export function parseRalphLoopConfigFromContent(content: string): RalphLoopConfi
  };

  // Parse each YAML line
-  let match;
-  YAML_LINE_PATTERN.lastIndex = 0;
-  while ((match = YAML_LINE_PATTERN.exec(yaml)) !== null) {
+  execPattern(YAML_LINE_PATTERN, yaml, (match) => {
    const key = match[1].toLowerCase();
    const value = match[2].trim();

@@ -103,7 +102,7 @@ export function parseRalphLoopConfigFromContent(content: string): RalphLoopConfi
        config.completionPromise = value.toUpperCase();
        break;
    }
-  }
+  });

  return config;
 }
@@ -10,6 +10,7 @@
 */

 import { EventEmitter } from 'node:events';
+import { CLEANUP_CHECK_INTERVAL_MS } from './config/server-timing.js';

 /**
 * RalphStallDetector - Detects iteration stalls in the Ralph loop.
@@ -57,7 +58,7 @@ export class RalphStallDetector extends EventEmitter {
    // Check every minute
    this._iterationStallTimer = setInterval(() => {
      this.checkIterationStall();
-    }, 60 * 1000);
+    }, CLEANUP_CHECK_INTERVAL_MS);
  }

  /**
@@ -55,6 +55,7 @@ import {
  stringSimilarity,
  Debouncer,
  CleanupManager,
+  execPattern,
 } from './utils/index.js';
 import { MAX_LINE_BUFFER_SIZE } from './config/buffer-limits.js';
 import { MAX_TODOS_PER_SESSION } from './config/map-limits.js';
@@ -63,6 +64,7 @@ import type { EnhancedPlanTask, CheckpointReview } from './ralph-plan-tracker.js
 import { RalphFixPlanWatcher, generateFixPlanMarkdown, importFixPlanMarkdown } from './ralph-fix-plan-watcher.js';
 import { RalphStallDetector } from './ralph-stall-detector.js';
 import { RalphStatusParser } from './ralph-status-parser.js';
+import { STALE_DATA_MAX_AGE_MS, INACTIVITY_TIMEOUT_MS } from './config/server-timing.js';

 // Re-export sub-module types for backward compatibility
 export type { EnhancedPlanTask, CheckpointReview } from './ralph-plan-tracker.js';
@@ -72,9 +74,9 @@ export type { EnhancedPlanTask, CheckpointReview } from './ralph-plan-tracker.js

 /**
 * Todo items older than this duration (in milliseconds) will be auto-expired.
- * Default: 1 hour (60 * 60 * 1000)
+ * Default: 1 hour
 */
-const TODO_EXPIRY_MS = 60 * 60 * 1000;
+const TODO_EXPIRY_MS = STALE_DATA_MAX_AGE_MS;

 /**
 * Minimum interval between on-demand cleanup checks (in milliseconds).
@@ -88,7 +90,7 @@ const CLEANUP_THROTTLE_MS = 30 * 1000;
 * Actively purges expired todos even when no terminal data is flowing.
 * Default: 5 minutes
 */
-const TODO_CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const TODO_CLEANUP_INTERVAL_MS = INACTIVITY_TIMEOUT_MS;

 /**
 * Similarity threshold for todo deduplication.
@@ -1666,35 +1668,32 @@ export class RalphTracker extends EventEmitter {
    let match: RegExpExecArray | null;

    if (hasCheckbox) {
-      TODO_CHECKBOX_PATTERN.lastIndex = 0;
-      while ((match = TODO_CHECKBOX_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_CHECKBOX_PATTERN, line, (match) => {
        const checked = match[1].toLowerCase() === 'x';
        const content = match[2].trim();
        const status: RalphTodoStatus = checked ? 'completed' : 'pending';
        this.upsertTodo(content, status);
        updated = true;
-      }
+      });
    }

    if (hasTodoIndicator) {
-      TODO_INDICATOR_PATTERN.lastIndex = 0;
-      while ((match = TODO_INDICATOR_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_INDICATOR_PATTERN, line, (match) => {
        const icon = match[1];
        const content = match[2].trim();
        const status = this.iconToStatus(icon);
        this.upsertTodo(content, status);
        updated = true;
-      }
+      });
    }

    if (hasStatus) {
-      TODO_STATUS_PATTERN.lastIndex = 0;
-      while ((match = TODO_STATUS_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_STATUS_PATTERN, line, (match) => {
        const content = match[1].trim();
        const status = match[2] as RalphTodoStatus;
        this.upsertTodo(content, status);
        updated = true;
-      }
+      });
    }

    if (hasNativeCheckbox) {
@@ -1715,8 +1714,7 @@ export class RalphTracker extends EventEmitter {
    }

    if (hasCheckmark) {
-      TODO_TASK_CREATED_PATTERN.lastIndex = 0;
-      while ((match = TODO_TASK_CREATED_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_TASK_CREATED_PATTERN, line, (match) => {
        const taskNum = parseInt(match[1], 10);
        const content = match[2].trim();
        if (content.length >= 5) {
@@ -1725,10 +1723,9 @@ export class RalphTracker extends EventEmitter {
          this.upsertTodo(content, 'pending');
          updated = true;
        }
-      }
+      });

-      TODO_TASK_SUMMARY_PATTERN.lastIndex = 0;
-      while ((match = TODO_TASK_SUMMARY_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_TASK_SUMMARY_PATTERN, line, (match) => {
        const taskNum = parseInt(match[1], 10);
        const content = match[2].trim();
        if (content.length >= 5) {
@@ -1739,10 +1736,9 @@ export class RalphTracker extends EventEmitter {
          this.upsertTodo(this._taskNumberToContent.get(taskNum) || content, 'pending');
          updated = true;
        }
-      }
+      });

-      TODO_TASK_STATUS_PATTERN.lastIndex = 0;
-      while ((match = TODO_TASK_STATUS_PATTERN.exec(line)) !== null) {
+      execPattern(TODO_TASK_STATUS_PATTERN, line, (match) => {
        const taskNum = parseInt(match[1], 10);
        const statusStr = match[2].trim();
        const status: RalphTodoStatus =
@@ -1752,7 +1748,7 @@ export class RalphTracker extends EventEmitter {
          this.upsertTodo(content, status);
          updated = true;
        }
-      }
+      });

      if (!updated) {
        TODO_PLAIN_CHECKMARK_PATTERN.lastIndex = 0;
@@ -62,7 +62,15 @@ import {
 import { RespawnAdaptiveTiming } from './respawn-adaptive-timing.js';
 import { RespawnCycleMetricsTracker } from './respawn-metrics.js';
 import { calculateHealthScore, shouldSkipClear, type HealthInputs } from './respawn-health.js';
-import { AI_CHECK_MODEL, AI_IDLE_CHECK_MAX_CONTEXT, AI_PLAN_CHECK_MAX_CONTEXT } from './config/ai-defaults.js';
+import {
+  AI_CHECK_MODEL,
+  AI_IDLE_CHECK_MAX_CONTEXT,
+  AI_PLAN_CHECK_MAX_CONTEXT,
+  AI_IDLE_CHECK_TIMEOUT_MS,
+  AI_IDLE_CHECK_COOLDOWN_MS,
+  AI_PLAN_CHECK_TIMEOUT_MS,
+  AI_PLAN_CHECK_COOLDOWN_MS,
+} from './config/ai-defaults.js';
 import type {
  RespawnCycleMetrics,
  RespawnAggregateMetrics,
@@ -559,13 +567,13 @@ const DEFAULT_CONFIG: RespawnConfig = {
  aiIdleCheckEnabled: true, // use AI to confirm idle state
  aiIdleCheckModel: AI_CHECK_MODEL,
  aiIdleCheckMaxContext: AI_IDLE_CHECK_MAX_CONTEXT,
-  aiIdleCheckTimeoutMs: 90000, // 90 seconds (thinking can be slow)
-  aiIdleCheckCooldownMs: 180000, // 3 minutes after WORKING verdict
+  aiIdleCheckTimeoutMs: AI_IDLE_CHECK_TIMEOUT_MS,
+  aiIdleCheckCooldownMs: AI_IDLE_CHECK_COOLDOWN_MS,
  aiPlanCheckEnabled: true, // use AI to confirm plan mode before auto-accept
  aiPlanCheckModel: AI_CHECK_MODEL,
  aiPlanCheckMaxContext: AI_PLAN_CHECK_MAX_CONTEXT,
-  aiPlanCheckTimeoutMs: 60000, // 60 seconds (thinking can be slow)
-  aiPlanCheckCooldownMs: 30000, // 30 seconds after NOT_PLAN_MODE
+  aiPlanCheckTimeoutMs: AI_PLAN_CHECK_TIMEOUT_MS,
+  aiPlanCheckCooldownMs: AI_PLAN_CHECK_COOLDOWN_MS,
  stuckStateDetectionEnabled: true, // detect stuck states
  stuckStateWarningMs: 300000, // 5 minutes warning threshold
  stuckStateRecoveryMs: 600000, // 10 minutes recovery threshold
@@ -22,6 +22,7 @@ import {
  RunSummaryStats,
  createInitialRunSummaryStats,
 } from './types.js';
+import { CLEANUP_CHECK_INTERVAL_MS } from './config/server-timing.js';

 /** Maximum events to keep per session (FIFO trimming) */
 const MAX_EVENTS = 1000;
@@ -36,7 +37,7 @@ const TOKEN_MILESTONE_INTERVAL = 50000;
 const STATE_STUCK_WARNING_MS = 10 * 60 * 1000; // 10 minutes

 /** State stuck check interval (ms) */
-const STATE_STUCK_CHECK_INTERVAL = 60 * 1000; // 1 minute
+const STATE_STUCK_CHECK_INTERVAL = CLEANUP_CHECK_INTERVAL_MS;

 /**
 * Tracks events and statistics for a session's run summary.
@@ -49,7 +49,13 @@ import { TaskTracker, type BackgroundTask } from './task-tracker.js';
 import { RalphTracker } from './ralph-tracker.js';
 import { BashToolParser } from './bash-tool-parser.js';
 import { BufferAccumulator } from './utils/buffer-accumulator.js';
-import { ANSI_ESCAPE_PATTERN_FULL, TOKEN_PATTERN, SPINNER_PATTERN, MAX_SESSION_TOKENS } from './utils/index.js';
+import {
+  ANSI_ESCAPE_PATTERN_FULL,
+  TOKEN_PATTERN,
+  SPINNER_PATTERN,
+  MAX_SESSION_TOKENS,
+  execPattern,
+} from './utils/index.js';
 import {
  MAX_TERMINAL_BUFFER_SIZE,
  TRIM_TERMINAL_TO as TERMINAL_BUFFER_TRIM_SIZE,
@@ -1692,16 +1698,12 @@ export class Session extends EventEmitter {
    // Quick pre-check: skip expensive regex if no common tool patterns present
    if (!cleanLine.includes('(') || !cleanLine.includes(')')) return;

-    // Reset regex lastIndex for global pattern
-    TASK_TOOL_PATTERN.lastIndex = 0;
-
-    let match;
-    while ((match = TASK_TOOL_PATTERN.exec(cleanLine)) !== null) {
+    execPattern(TASK_TOOL_PATTERN, cleanLine, (match) => {
      const description = match[2].trim();
      if (description && description.length > 0) {
        this._taskCache.add(Date.now(), description);
      }
-    }
+    });
  }

  /**
@@ -34,6 +34,7 @@ import { join, basename } from 'node:path';
 import { execFile } from 'node:child_process';
 import { readFile, readdir, stat as statAsync } from 'node:fs/promises';
 import { PENDING_TOOL_CALL_TTL_MS, MAX_PENDING_TOOL_CALLS, MAX_TRACKED_AGENTS } from './config/map-limits.js';
+import { STALE_DATA_MAX_AGE_MS } from './config/server-timing.js';
 import { CleanupManager, KeyedDebouncer } from './utils/index.js';

 // ========== Types ==========
@@ -151,7 +152,7 @@ const POLL_INTERVAL_MS = 1000; // Base poll interval (lightweight checks)
 const FULL_SCAN_EVERY_N_POLLS = 5; // Full directory traversal every 5th poll (5s)
 const LIVENESS_CHECK_MS = 10000; // Check if subagent processes are still alive every 10s
 const FILE_ALIVE_THRESHOLD_MS = 30000; // File mtime within 30s = agent alive (primary check)
-const STALE_COMPLETED_MAX_AGE_MS = 60 * 60 * 1000; // Remove completed agents older than 1 hour
+const STALE_COMPLETED_MAX_AGE_MS = STALE_DATA_MAX_AGE_MS; // Remove completed agents older than 1 hour
 const STALE_IDLE_MAX_AGE_MS = 4 * 60 * 60 * 1000; // Remove idle agents older than 4 hours
 const STARTUP_MAX_FILE_AGE_MS = 4 * 60 * 60 * 1000; // Only load files modified in last 4 hours on startup

@@ -22,6 +22,7 @@

 import { EventEmitter } from 'node:events';
 import { assertNever } from './utils/index.js';
+import { STALE_DATA_MAX_AGE_MS } from './config/server-timing.js';

 // ========== Configuration Constants ==========

@@ -36,7 +37,7 @@ const MAX_COMPLETED_TASKS = 100;
 * Entries older than this are cleaned up to prevent unbounded growth.
 * Default: 1 hour
 */
-const PENDING_TOOL_USE_MAX_AGE_MS = 60 * 60 * 1000;
+const PENDING_TOOL_USE_MAX_AGE_MS = STALE_DATA_MAX_AGE_MS;

 /**
 * Maximum number of pending tool uses to allow.
@@ -6,7 +6,7 @@
 * Key exports:
 * - PlanItem — a single task with priority (P0/P1/P2), TDD phase, dependencies, verification criteria
 * - PlanTaskStatus — 'pending' | 'in_progress' | 'completed' | 'failed' | 'blocked'
- * - TddPhase / PlanPhase — 'setup' | 'test' | 'impl' | 'verify' | 'review'
+ * - TddPhase — 'setup' | 'test' | 'impl' | 'verify' | 'review'
 *
 * Used by PlanOrchestrator (`src/plan-orchestrator.ts`) and the plan API routes
 * (`src/web/routes/plan-routes.ts`). Served at `GET /api/sessions/:id/plan/tasks`.
@@ -21,9 +21,6 @@ export type PlanTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed'
 /** TDD phase categories */
 export type TddPhase = 'setup' | 'test' | 'impl' | 'verify' | 'review';

-/** Development phase in TDD cycle (alias for TddPhase) */
-export type PlanPhase = TddPhase;
-
 /**
 * A single plan item for plan orchestration.
 * Moved here from plan-orchestrator.ts to break circular dependency.
@@ -42,7 +39,7 @@ export interface PlanItem {
  lastError?: string;
  completedAt?: number;
  complexity?: 'low' | 'medium' | 'high';
-  tddPhase?: PlanPhase;
+  tddPhase?: TddPhase;
  pairedWith?: string;
  reviewChecklist?: string[];
 }
@@ -20,8 +20,9 @@ export {
  createAnsiPatternSimple,
  stripAnsi,
  SAFE_PATH_PATTERN,
+  execPattern,
 } from './regex-patterns.js';
-export { MAX_SESSION_TOKENS, validateTokenCounts, validateTokensAndCost } from './token-validation.js';
+export { MAX_SESSION_TOKENS } from './token-validation.js';
 export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
 export { assertNever } from './type-safety.js';
 export { wrapWithNice } from './nice-wrapper.js';
@@ -79,3 +79,15 @@ export function stripAnsi(text: string): string {
 export const SPINNER_PATTERN = /[⠋⠙⠹⠸⠼⠴⠦⠧]/;

 export const SAFE_PATH_PATTERN = /^[a-zA-Z0-9_/\-. ~]+$/;
+
+/**
+ * Execute a global regex pattern against data, calling the callback for each match.
+ * Automatically resets lastIndex before execution.
+ */
+export function execPattern(pattern: RegExp, data: string, callback: (match: RegExpExecArray) => void): void {
+  pattern.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(data)) !== null) {
+    callback(match);
+  }
+}
@@ -1,7 +1,6 @@
 /**
- * @fileoverview Token validation utilities.
+ * @fileoverview Token validation constants.
 *
- * Centralizes token count validation logic used across the codebase.
 * Claude's context window is ~200k tokens, so 500k is a generous upper bound.
 *
 * @module utils/token-validation
@@ -12,58 +11,3 @@
 * Claude's context is ~200k, so 500k is a safe upper bound for validation.
 */
 export const MAX_SESSION_TOKENS = 500_000;
-
-/**
- * Validates token counts are within acceptable bounds.
- * Rejects negative values and values exceeding MAX_SESSION_TOKENS.
- *
- * @param inputTokens - Input token count to validate
- * @param outputTokens - Output token count to validate
- * @returns Object with isValid flag and optional error reason
- */
-export function validateTokenCounts(inputTokens: number, outputTokens: number): { isValid: boolean; reason?: string } {
-  if (inputTokens < 0 || outputTokens < 0) {
-    return {
-      isValid: false,
-      reason: `Negative token values: input=${inputTokens}, output=${outputTokens}`,
-    };
-  }
-
-  if (inputTokens > MAX_SESSION_TOKENS || outputTokens > MAX_SESSION_TOKENS) {
-    return {
-      isValid: false,
-      reason: `Token values exceed maximum (${MAX_SESSION_TOKENS}): input=${inputTokens}, output=${outputTokens}`,
-    };
-  }
-
-  return { isValid: true };
-}
-
-/**
- * Validates token counts and cost for restoration/persistence.
- * Returns true if all values are valid.
- *
- * @param inputTokens - Input token count
- * @param outputTokens - Output token count
- * @param cost - Cost value (must be non-negative)
- * @returns Object with isValid flag and optional error reason
- */
-export function validateTokensAndCost(
-  inputTokens: number,
-  outputTokens: number,
-  cost: number
-): { isValid: boolean; reason?: string } {
-  const tokenValidation = validateTokenCounts(inputTokens, outputTokens);
-  if (!tokenValidation.isValid) {
-    return tokenValidation;
-  }
-
-  if (cost < 0) {
-    return {
-      isValid: false,
-      reason: `Negative cost value: ${cost}`,
-    };
-  }
-
-  return { isValid: true };
-}
@@ -78,6 +78,82 @@
 // MobileDetection, KeyboardHandler, SwipeHandler are in mobile-handlers.js
 // DeepgramProvider, VoiceInput are in voice-input.js

+// ═══════════════════════════════════════════════════════════════
+// Global Error & Performance Diagnostics
+// ═══════════════════════════════════════════════════════════════
+// Writes breadcrumbs to localStorage so they survive tab freezes.
+// After a crash, check: localStorage.getItem('codeman-crash-diag')
+
+const _crashDiag = {
+  _entries: [],
+  _maxEntries: 50,
+  log(msg) {
+    const entry = `${new Date().toISOString().slice(11,23)} ${msg}`;
+    this._entries.push(entry);
+    if (this._entries.length > this._maxEntries) this._entries.shift();
+    try { localStorage.setItem('codeman-crash-diag', this._entries.join('\n')); } catch {}
+  }
+};
+
+// Log previous crash breadcrumbs on startup
+try {
+  const prev = localStorage.getItem('codeman-crash-diag');
+  if (prev) console.log('[CRASH-DIAG] Previous session breadcrumbs:\n' + prev);
+} catch {}
+_crashDiag.log('PAGE LOAD');
+
+// Heartbeat: send breadcrumbs to server every 2s so they survive tab freezes.
+setInterval(() => {
+  try {
+    localStorage.setItem('codeman-crash-heartbeat', String(Date.now()));
+    if (_crashDiag._entries.length > 0) {
+      navigator.sendBeacon('/api/crash-diag', JSON.stringify({ data: _crashDiag._entries.join('\n') }));
+    }
+  } catch {}
+}, 2000);
+
+window.addEventListener('error', (e) => {
+  _crashDiag.log(`ERROR: ${e.message} at ${e.filename}:${e.lineno}`);
+  console.error('[CRASH-DIAG] Uncaught error:', e.message, '\n  File:', e.filename, ':', e.lineno, ':', e.colno, '\n  Stack:', e.error?.stack);
+});
+
+window.addEventListener('unhandledrejection', (e) => {
+  _crashDiag.log(`UNHANDLED: ${e.reason?.message || e.reason}`);
+  console.error('[CRASH-DIAG] Unhandled promise rejection:', e.reason?.message || e.reason, '\n  Stack:', e.reason?.stack);
+});
+
+// Detect long tasks (>50ms main thread blocks) — these cause "page unresponsive"
+if (typeof PerformanceObserver !== 'undefined') {
+  try {
+    const longTaskObserver = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.duration > 200) {
+          _crashDiag.log(`LONG_TASK: ${entry.duration.toFixed(0)}ms`);
+          console.warn(`[CRASH-DIAG] Long task: ${entry.duration.toFixed(0)}ms (type: ${entry.entryType}, name: ${entry.name})`);
+        }
+      }
+    });
+    longTaskObserver.observe({ type: 'longtask', buffered: true });
+  } catch { /* longtask not supported */ }
+}
+
+// Track WebGL context loss/restore events on all canvases
+const _origGetContext = HTMLCanvasElement.prototype.getContext;
+HTMLCanvasElement.prototype.getContext = function(type, ...args) {
+  const ctx = _origGetContext.call(this, type, ...args);
+  if (type === 'webgl2' || type === 'webgl') {
+    this.addEventListener('webglcontextlost', (e) => {
+      _crashDiag.log(`WEBGL_LOST: ${this.width}x${this.height}`);
+      console.error('[CRASH-DIAG] WebGL context LOST on canvas', this.width, 'x', this.height, '— prevented:', e.defaultPrevented);
+    });
+    this.addEventListener('webglcontextrestored', () => {
+      _crashDiag.log('WEBGL_RESTORED');
+      console.warn('[CRASH-DIAG] WebGL context restored');
+    });
+  }
+  return ctx;
+};
+



@@ -542,12 +618,23 @@ class CodemanApp {
    const container = document.getElementById('terminalContainer');
    this.terminal.open(container);

-    // Activate WebGL renderer for up to 900% faster rendering (fallback to canvas on failure)
-    if (typeof WebglAddon !== 'undefined') {
+    // WebGL renderer for GPU-accelerated terminal rendering.
+    // Previously caused "page unresponsive" crashes from synchronous GPU stalls,
+    // but the 48KB/frame flush cap in flushPendingWrites() now prevents
+    // oversized terminal.write() calls that triggered the stalls.
+    // Disable with ?nowebgl URL param if GPU issues return.
+    this._webglAddon = null;
+    const skipWebGL = MobileDetection.getDeviceType() !== 'desktop';
+    if (!skipWebGL && !new URLSearchParams(location.search).has('nowebgl') && typeof WebglAddon !== 'undefined') {
      try {
-        const webglAddon = new WebglAddon.WebglAddon();
-        webglAddon.onContextLoss(() => { webglAddon.dispose(); });
-        this.terminal.loadAddon(webglAddon);
+        this._webglAddon = new WebglAddon.WebglAddon();
+        this._webglAddon.onContextLoss(() => {
+          console.error('[CRASH-DIAG] WebGL context LOST — falling back to canvas renderer');
+          this._webglAddon.dispose();
+          this._webglAddon = null;
+        });
+        this.terminal.loadAddon(this._webglAddon);
+        console.log('[CRASH-DIAG] WebGL renderer enabled via ?webgl param');
      } catch (_e) { /* WebGL2 unavailable — canvas renderer used */ }
    }

@@ -1095,18 +1182,47 @@ class CodemanApp {
    // Ink's status bar updates use cursor-up + erase-line + rewrite, which can split
    // across render frames causing old/new status text to overlap (garbled output).
    // Buffering for 50ms ensures the full redraw arrives atomically.
-    const hasCursorUpRedraw = /\x1b\[\d{1,2}A/.test(data);
+    //
+    // Shell mode is excluded: shell readline also uses cursor-up for prompt redraws
+    // (e.g. zsh syntax highlighting on every keystroke), and there's no Ink status bar
+    // to protect. Applying the filter in shell mode delays character feedback until the
+    // user stops typing for 50ms, making the terminal feel unresponsive.
+    const isShellMode = session?.mode === 'shell';
+    const hasCursorUpRedraw = !isShellMode && /\x1b\[\d{1,2}A/.test(data);
    if (hasCursorUpRedraw || (this.flickerFilterActive && !flickerFilterEnabled)) {
      this.flickerFilterActive = true;
      this.flickerFilterBuffer += data;

-      if (this.flickerFilterTimeout) {
-        clearTimeout(this.flickerFilterTimeout);
+      // Only reset the 50ms timer on cursor-up events (start of a new Ink redraw cycle).
+      // Non-cursor-up events while the filter is active are trailing data from the same
+      // redraw — don't extend the deadline further. Without this guard, a busy Claude
+      // session emitting terminal data faster than SYNC_WAIT_TIMEOUT_MS never flushes,
+      // accumulating MBs in flickerFilterBuffer that freeze Chrome all at once.
+      if (hasCursorUpRedraw) {
+        if (this.flickerFilterTimeout) {
+          clearTimeout(this.flickerFilterTimeout);
+        }
+        this.flickerFilterTimeout = setTimeout(() => {
+          this.flickerFilterTimeout = null;
+          this.flushFlickerBuffer();
+        }, SYNC_WAIT_TIMEOUT_MS); // 50ms buffer window
+      } else if (!this.flickerFilterTimeout) {
+        // Safety: if no timer is running for some reason, ensure we eventually flush.
+        this.flickerFilterTimeout = setTimeout(() => {
+          this.flickerFilterTimeout = null;
+          this.flushFlickerBuffer();
+        }, SYNC_WAIT_TIMEOUT_MS);
      }
-      this.flickerFilterTimeout = setTimeout(() => {
-        this.flickerFilterTimeout = null;
+
+      // Safety valve: if buffer grew very large (e.g. from a burst before the timer fired),
+      // flush immediately to avoid writing a huge block all at once.
+      if (this.flickerFilterBuffer.length > 256 * 1024) {
+        if (this.flickerFilterTimeout) {
+          clearTimeout(this.flickerFilterTimeout);
+          this.flickerFilterTimeout = null;
+        }
        this.flushFlickerBuffer();
-      }, SYNC_WAIT_TIMEOUT_MS); // 50ms buffer window
+      }

      return;
    }
@@ -1236,6 +1352,11 @@ class CodemanApp {
              } catch { return null; }
            }
          });
+        } else if (session.mode === 'shell') {
+          // Shell mode: the shell provides its own PTY echo so the overlay isn't needed.
+          // Disable it by clearing any pending text.
+          this._localEchoOverlay.clear();
+          this._localEchoEnabled = false;
        } else {
          // Claude Code: scan for ❯ prompt character
          this._localEchoOverlay.setPrompt({ type: 'character', char: '\u276f', offset: 2 });
@@ -1250,24 +1371,60 @@ class CodemanApp {
  flushPendingWrites() {
    if (this.pendingWrites.length === 0 || !this.terminal) return;

+    const _t0 = performance.now();
    // Extract segments, stripping DEC 2026 markers
    // This implements synchronized output for xterm.js which doesn't support DEC 2026 natively
-    const segments = extractSyncSegments(this.pendingWrites.join(''));
+    const _joinedLen = this.pendingWrites.reduce((s, w) => s + w.length, 0);
+    if (_joinedLen > 16384) _crashDiag.log(`FLUSH: ${(_joinedLen/1024).toFixed(0)}KB`);
+    const joined = this.pendingWrites.join('');
    this.pendingWrites = [];

-    // Write all segments in a single batch (atomic within this frame)
-    // xterm.js internally batches multiple write() calls within same frame
-    // Never discard content from incomplete sync blocks — xterm.js doesn't support
-    // DEC 2026 natively anyway, so strip the marker and write content regardless.
-    // Discarding causes real data loss (including Ink's erase-line escapes).
-    for (const segment of segments) {
-      if (segment) {
-        const content = segment.startsWith(DEC_SYNC_START)
-          ? segment.slice(DEC_SYNC_START.length)
-          : segment;
-        if (content) this.terminal.write(content);
+    const segments = extractSyncSegments(joined);
+
+    // Write segments respecting a per-frame byte budget.
+    // Each DEC 2026 sync segment is a complete Ink redraw — writing whole segments
+    // preserves atomicity (no flicker). But when total data exceeds 48KB, defer
+    // remaining segments to the next frame to prevent terminal.write() from blocking
+    // the main thread. 141KB single-frame writes have been observed to freeze Chrome
+    // for 2+ minutes even with the canvas renderer.
+    const MAX_FRAME_BYTES = 65536; // 64KB budget per frame
+    let bytesThisFrame = 0;
+    let deferred = false;
+
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      if (!segment) continue;
+      const content = segment.startsWith(DEC_SYNC_START)
+        ? segment.slice(DEC_SYNC_START.length)
+        : segment;
+      if (!content) continue;
+
+      // If we'd exceed the budget, defer this and all remaining segments
+      if (bytesThisFrame > 0 && bytesThisFrame + content.length > MAX_FRAME_BYTES) {
+        // Re-queue remaining segments as raw content for next flush
+        const remaining = segments.slice(i).map(s => {
+          if (!s) return '';
+          return s.startsWith(DEC_SYNC_START) ? s.slice(DEC_SYNC_START.length) : s;
+        }).filter(Boolean).join('');
+        if (remaining) {
+          this.pendingWrites.push(remaining);
+          if (!this.writeFrameScheduled) {
+            this.writeFrameScheduled = true;
+            requestAnimationFrame(() => {
+              this.flushPendingWrites();
+              this.writeFrameScheduled = false;
+            });
+          }
+        }
+        deferred = true;
+        break;
      }
+
+      this.terminal.write(content);
+      bytesThisFrame += content.length;
    }
+    const _dt = performance.now() - _t0;
+    if (_dt > 100 || deferred) console.warn(`[CRASH-DIAG] flushPendingWrites: ${_dt.toFixed(0)}ms, ${(bytesThisFrame/1024).toFixed(0)}KB written${deferred ? ', rest deferred' : ''} (total ${(_joinedLen/1024).toFixed(0)}KB)`);

    // Sticky scroll: if user was at bottom, keep them there after new output
    if (this._wasAtBottomBeforeWrite) {
@@ -1349,23 +1506,34 @@ class CodemanApp {
        resolve();
      };

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

+      // Large buffers: write in chunks across animation frames.
+      // Each 32KB chunk keeps per-frame WebGL render work under ~5ms,
+      // avoiding GPU stalls without needing to toggle the renderer.
      let offset = 0;
+      const _chunkStart = performance.now();
+      let _chunkCount = 0;
      const writeChunk = () => {
        if (offset >= cleanBuffer.length) {
+          const _totalMs = performance.now() - _chunkStart;
+          console.log(`[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`);
          // Wait one more frame for xterm to finish rendering before resolving
          requestAnimationFrame(finish);
          return;
        }

+        const _ct0 = performance.now();
        const chunk = cleanBuffer.slice(offset, offset + chunkSize);
        this.terminal.write(chunk);
+        const _cdt = performance.now() - _ct0;
+        _chunkCount++;
+        if (_cdt > 50) console.warn(`[CRASH-DIAG] chunk #${_chunkCount} write took ${_cdt.toFixed(0)}ms (${chunk.length} bytes at offset ${offset})`);
        offset += chunkSize;

        // Schedule next chunk on next frame
@@ -1588,6 +1756,7 @@ class CodemanApp {
  // Async handlers have their own internal try/catch for fetch errors.

  _onInit(data) {
+    _crashDiag.log(`INIT: ${data.sessions?.length || 0} sessions`);
    this.handleInit(data);
  }

@@ -1646,6 +1815,27 @@ class CodemanApp {

  _onSessionTerminal(data) {
    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.
+      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
+        // queue drains (debounced to avoid hammering the API during sustained bursts).
+        if (!this._clientDropRecoveryTimer) {
+          this._clientDropRecoveryTimer = setTimeout(() => {
+            this._clientDropRecoveryTimer = null;
+            this._onSessionNeedsRefresh();
+          }, 2000);
+        }
+        return;
+      }
+
      this.batchTerminalWrite(data.data);
    }
  }
@@ -1655,8 +1845,7 @@ class CodemanApp {
    // so reload the buffer to recover from any display corruption.
    if (!this.activeSessionId || !this.terminal) return;
    try {
-      const tailSize = 256 * 1024;
-      const res = await fetch(`/api/sessions/${this.activeSessionId}/terminal?tail=${tailSize}`);
+      const res = await fetch(`/api/sessions/${this.activeSessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
      const data = await res.json();
      if (data.terminalBuffer) {
        this.terminal.clear();
@@ -3019,15 +3208,38 @@ class CodemanApp {
          return;
        }

-        // Update subagent badge - check if count changed
+        // Update subagent badge - targeted update without full rebuild
        const subagentBadgeEl = tab.querySelector('.tab-subagent-badge');
        const minimizedAgents = this.minimizedSubagents.get(id);
        const minimizedCount = minimizedAgents?.size || 0;
-        const currentCount = subagentBadgeEl ? parseInt(subagentBadgeEl.querySelector('.subagent-count')?.textContent || '0') : 0;
-        if (minimizedCount !== currentCount) {
-          // Count changed - need full rebuild for dropdown update
-          this._fullRenderSessionTabs();
-          return;
+        if (minimizedCount > 0 && subagentBadgeEl) {
+          // Badge exists and still has agents - update label and dropdown in-place
+          const labelEl = subagentBadgeEl.querySelector('.subagent-label');
+          const newLabel = minimizedCount === 1 ? 'AGENT' : `AGENTS (${minimizedCount})`;
+          if (labelEl && labelEl.textContent !== newLabel) {
+            labelEl.textContent = newLabel;
+          }
+          // Rebuild dropdown items (agent list may have changed)
+          const dropdownEl = subagentBadgeEl.querySelector('.subagent-dropdown');
+          if (dropdownEl) {
+            const newBadgeHtml = this.renderSubagentTabBadge(id, minimizedAgents);
+            const temp = document.createElement('div');
+            temp.innerHTML = newBadgeHtml;
+            const newDropdown = temp.querySelector('.subagent-dropdown');
+            if (newDropdown) {
+              dropdownEl.innerHTML = newDropdown.innerHTML;
+            }
+          }
+        } else if (minimizedCount > 0 && !subagentBadgeEl) {
+          // Need to add badge - insert before gear icon
+          const badgeHtml = this.renderSubagentTabBadge(id, minimizedAgents);
+          const gearEl = tab.querySelector('.tab-gear');
+          if (gearEl) {
+            gearEl.insertAdjacentHTML('beforebegin', badgeHtml);
+          }
+        } else if (minimizedCount === 0 && subagentBadgeEl) {
+          // Count went to 0 - remove badge
+          subagentBadgeEl.remove();
        }
      }
    } else {
@@ -3307,6 +3519,10 @@ class CodemanApp {

  async selectSession(sessionId) {
    if (this.activeSessionId === sessionId) return;
+    const _selStart = performance.now();
+    const _selName = this.sessions.get(sessionId)?.name || sessionId.slice(0,8);
+    _crashDiag.log(`SELECT: ${_selName}`);
+    console.log(`[CRASH-DIAG] selectSession START: ${sessionId.slice(0,8)}`);

    const selectGen = ++this._selectGeneration;

@@ -3325,6 +3541,7 @@ class CodemanApp {
    this._tabCompletionRetries = 0;
    this._tabCompletionBaseText = null;
    if (this._tabCompletionFallback) { clearTimeout(this._tabCompletionFallback); this._tabCompletionFallback = null; }
+    if (this._clientDropRecoveryTimer) { clearTimeout(this._clientDropRecoveryTimer); this._clientDropRecoveryTimer = null; }

    // Clean up pending terminal writes to prevent old session data from appearing in new session
    if (this.syncWaitTimeout) {
@@ -3427,7 +3644,7 @@ class CodemanApp {

    // Load terminal buffer for this session
    // Show cached content instantly while fetching fresh data in background.
-    // Use tail mode for faster initial load (256KB is enough for recent visible content).
+    // Use tail mode for faster initial load (128KB is enough for recent visible content).
    //
    // Protect flushed state during buffer load: terminal.write() can trigger
    // xterm.js onData responses (DA, OSC, etc.) that would otherwise clear
@@ -3435,20 +3652,32 @@ class CodemanApp {
    // filter catches most cases, but _restoringFlushedState provides a
    // belt-and-suspenders guard for any edge cases.
    this._restoringFlushedState = true;
+    // Gate live SSE terminal writes for the ENTIRE buffer load sequence.
+    // Without this, SSE events arriving during the fetch() gap compete with
+    // the buffer write, causing 70KB+ single-frame flushes that stall WebGL.
+    // chunkedTerminalWrite also sets this, but we need it before the fetch too.
+    this._isLoadingBuffer = true;
+    this._loadBufferQueue = [];
    try {
-      // Instant cache restore — show previous buffer immediately while network fetch runs
+      // Instant cache restore — show previous buffer via chunked write to avoid WebGL GPU stalls.
+      // Direct terminal.write() of large cached buffers (256KB+) can block the main thread
+      // for 5+ seconds while the WebGL renderer processes ReadPixels synchronously.
      const cachedBuffer = this.terminalBufferCache.get(sessionId);
      if (cachedBuffer) {
+        _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
        this.terminal.clear();
        this.terminal.reset();
-        this.terminal.write(cachedBuffer);
+        await this.chunkedTerminalWrite(cachedBuffer);
+        if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
        this.terminal.scrollToBottom();
+        _crashDiag.log('CACHE_DONE');
      }

-      const tailSize = 256 * 1024;
-      const res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${tailSize}`);
-      if (selectGen !== this._selectGeneration) { this._restoringFlushedState = false; return; }
+      _crashDiag.log('FETCH_START');
+      const res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
+      if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
      const data = await res.json();
+      _crashDiag.log(`FETCH_DONE: ${data.terminalBuffer ? (data.terminalBuffer.length/1024).toFixed(0) + 'KB' : 'empty'} truncated=${data.truncated}`);

      if (data.terminalBuffer) {
        // Skip rewrite if fresh buffer matches cache — avoids visible clear+rewrite flash.
@@ -3456,6 +3685,7 @@ class CodemanApp {
        // very visible, causing the terminal to flash blank then repaint.
        const needsRewrite = data.terminalBuffer !== cachedBuffer;
        if (needsRewrite) {
+          _crashDiag.log(`REWRITE: ${(data.terminalBuffer.length/1024).toFixed(0)}KB`);
          this.terminal.clear();
          this.terminal.reset();
          // Show truncation indicator if buffer was cut
@@ -3464,7 +3694,7 @@ class CodemanApp {
          }
          // Use chunked write for large buffers to avoid UI jank
          await this.chunkedTerminalWrite(data.terminalBuffer);
-          if (selectGen !== this._selectGeneration) { this._restoringFlushedState = false; return; }
+          if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
          // Ensure terminal is scrolled to bottom after buffer load
          this.terminal.scrollToBottom();
        }
@@ -3482,7 +3712,13 @@ class CodemanApp {
        this.terminal.reset();
      }

-      // Buffer load complete — drop the guard so user input clears state normally
+      // Buffer load complete — unblock live SSE writes and flush any queued events.
+      // chunkedTerminalWrite calls _finishBufferLoad internally, but if we skipped
+      // the chunked write (small buffer, cache hit, or empty), we must call it here.
+      if (this._isLoadingBuffer) {
+        this._finishBufferLoad();
+      }
+      // Drop the guard so user input clears state normally
      this._restoringFlushedState = false;

      // Restore flushed offset and text for this session so the overlay positions
@@ -3560,13 +3796,35 @@ class CodemanApp {
          if (fileBrowserPanel) {
            fileBrowserPanel.classList.add('visible');
            this.loadFileBrowser(sessionId);
+            // Attach drag listeners if not already attached
+            if (!this.fileBrowserDragListeners) {
+              const header = fileBrowserPanel.querySelector('.file-browser-header');
+              if (header) {
+                const onFirstDrag = () => {
+                  if (!fileBrowserPanel.style.left) {
+                    const rect = fileBrowserPanel.getBoundingClientRect();
+                    fileBrowserPanel.style.left = `${rect.left}px`;
+                    fileBrowserPanel.style.top = `${rect.top}px`;
+                    fileBrowserPanel.style.right = 'auto';
+                  }
+                };
+                header.addEventListener('mousedown', onFirstDrag);
+                header.addEventListener('touchstart', onFirstDrag, { passive: true });
+                this.fileBrowserDragListeners = this.makeWindowDraggable(fileBrowserPanel, header);
+                this.fileBrowserDragListeners._onFirstDrag = onFirstDrag;
+              }
+            }
          }
        }
      });

+      _crashDiag.log('FOCUS');
      this.terminal.focus();
      this.terminal.scrollToBottom();
+      _crashDiag.log(`SELECT_DONE: ${(performance.now() - _selStart).toFixed(0)}ms`);
+      console.log(`[CRASH-DIAG] selectSession DONE: ${sessionId.slice(0,8)} in ${(performance.now() - _selStart).toFixed(0)}ms`);
    } catch (err) {
+      if (this._isLoadingBuffer) this._finishBufferLoad();
      this._restoringFlushedState = false;
      console.error('Failed to load session terminal:', err);
    }
@@ -7050,6 +7308,25 @@ class CodemanApp {
      if (showFileBrowser && this.activeSessionId) {
        fileBrowserPanel.classList.add('visible');
        this.loadFileBrowser(this.activeSessionId);
+        // Attach drag listeners if not already attached
+        if (!this.fileBrowserDragListeners) {
+          const header = fileBrowserPanel.querySelector('.file-browser-header');
+          if (header) {
+            // Convert right-positioned to left/top before drag so makeWindowDraggable works
+            const onFirstDrag = () => {
+              if (!fileBrowserPanel.style.left) {
+                const rect = fileBrowserPanel.getBoundingClientRect();
+                fileBrowserPanel.style.left = `${rect.left}px`;
+                fileBrowserPanel.style.top = `${rect.top}px`;
+                fileBrowserPanel.style.right = 'auto';
+              }
+            };
+            header.addEventListener('mousedown', onFirstDrag);
+            header.addEventListener('touchstart', onFirstDrag, { passive: true });
+            this.fileBrowserDragListeners = this.makeWindowDraggable(fileBrowserPanel, header);
+            this.fileBrowserDragListeners._onFirstDrag = onFirstDrag;
+          }
+        }
      } else {
        fileBrowserPanel.classList.remove('visible');
      }
@@ -9355,10 +9632,16 @@ class CodemanApp {
        // Show window (unless it was minimized by user)
        if (!windowInfo.minimized) {
          windowInfo.element.style.display = 'flex';
+          // Lazily re-create teammate terminal if it was disposed when hidden
+          if (windowInfo._lazyTerminal) {
+            this._restoreTeammateTerminalFromLazy(agentId);
+          }
        }
        windowInfo.hidden = false;
      } else {
        // Hide window (but don't close it)
+        // Dispose teammate terminal to free memory while hidden on inactive tab
+        this._disposeTeammateTerminalForMinimize(agentId);
        windowInfo.element.style.display = 'none';
        windowInfo.hidden = true;
      }
@@ -9441,6 +9724,8 @@ class CodemanApp {
  minimizeSubagentWindow(agentId) {
    const windowData = this.subagentWindows.get(agentId);
    if (windowData) {
+      // Dispose teammate terminal on minimize to free DOM/memory (lazy re-creation on restore)
+      this._disposeTeammateTerminalForMinimize(agentId);
      windowData.element.style.display = 'none';
      windowData.minimized = true;
      this.updateConnectionLines();
@@ -9451,6 +9736,10 @@ class CodemanApp {
  // Debounced wrapper — coalesces rapid subagent events (tool_call, progress,
  // message) into a single DOM update per 100ms per agent window.
  scheduleSubagentWindowRender(agentId) {
+    // Skip DOM updates for windows with lazy (disposed) terminals — they're minimized
+    const windowData = this.subagentWindows.get(agentId);
+    if (windowData?.minimized) return;
+
    if (!this._subagentWindowRenderTimeouts) this._subagentWindowRenderTimeouts = new Map();
    if (this._subagentWindowRenderTimeouts.has(agentId)) {
      clearTimeout(this._subagentWindowRenderTimeouts.get(agentId));
@@ -9464,6 +9753,9 @@ class CodemanApp {
  renderSubagentWindowContent(agentId) {
    // Skip if this window has a live terminal (don't overwrite xterm with activity HTML)
    if (this.teammateTerminals.has(agentId)) return;
+    // Skip if this window has a lazy (disposed) terminal — it will be re-created on restore
+    const windowData = this.subagentWindows.get(agentId);
+    if (windowData?._lazyTerminal) return;

    const body = document.getElementById(`subagent-window-body-${agentId}`);
    if (!body) return;
@@ -9866,8 +10158,18 @@ class CodemanApp {
    resizeObserver.observe(win);
    this.subagentWindows.get(windowId).resizeObserver = resizeObserver;

-    // Init the xterm.js terminal
-    this.initTeammateTerminal(windowId, paneData, win);
+    // Init the xterm.js terminal (lazy if hidden)
+    if (shouldHide) {
+      // Window starts hidden — defer terminal creation until visible (lazy init)
+      const windowEntry = this.subagentWindows.get(windowId);
+      if (windowEntry) {
+        windowEntry._lazyTerminal = true;
+        windowEntry._lazyPaneTarget = paneData.paneTarget;
+        windowEntry._lazySessionId = paneData.sessionId;
+      }
+    } else {
+      this.initTeammateTerminal(windowId, paneData, win);
+    }

    // Animate in
    requestAnimationFrame(() => {
@@ -10349,6 +10651,7 @@ class CodemanApp {
  fileBrowserExpandedDirs = new Set();
  fileBrowserFilter = '';
  fileBrowserAllExpanded = false;
+  fileBrowserDragListeners = null;
  filePreviewContent = '';

  async loadFileBrowser(sessionId) {
@@ -10532,6 +10835,29 @@ class CodemanApp {
    const panel = this.$('fileBrowserPanel');
    if (panel) {
      panel.classList.remove('visible');
+      // Reset position so it reopens at default location
+      panel.style.left = '';
+      panel.style.top = '';
+      panel.style.bottom = '';
+      panel.style.right = '';
+    }
+    // Clean up drag listeners
+    if (this.fileBrowserDragListeners) {
+      const dl = this.fileBrowserDragListeners;
+      document.removeEventListener('mousemove', dl.move);
+      document.removeEventListener('mouseup', dl.up);
+      document.removeEventListener('touchmove', dl.touchMove);
+      document.removeEventListener('touchend', dl.up);
+      document.removeEventListener('touchcancel', dl.up);
+      if (dl.handle) {
+        dl.handle.removeEventListener('mousedown', dl.handleMouseDown);
+        dl.handle.removeEventListener('touchstart', dl.handleTouchStart);
+        if (dl._onFirstDrag) {
+          dl.handle.removeEventListener('mousedown', dl._onFirstDrag);
+          dl.handle.removeEventListener('touchstart', dl._onFirstDrag);
+        }
+      }
+      this.fileBrowserDragListeners = null;
    }
    // Save setting
    const settings = this.loadAppSettingsFromStorage();
@@ -52,8 +52,8 @@ const TITLE_FLASH_INTERVAL_MS = 1500;       // Title flash rate
 const BROWSER_NOTIF_RATE_LIMIT_MS = 3000;   // Rate limit for browser notifications
 const AUTO_CLOSE_NOTIFICATION_MS = 8000;    // Auto-close browser notifications
 const THROTTLE_DELAY_MS = 100;              // General UI throttle delay
-const TERMINAL_CHUNK_SIZE = 128 * 1024;     // 128KB chunks for terminal data
-const TERMINAL_TAIL_SIZE = 256 * 1024;      // 256KB tail for initial load
+const TERMINAL_CHUNK_SIZE = 32 * 1024;      // 32KB chunks for terminal buffer loading
+const TERMINAL_TAIL_SIZE = 128 * 1024;      // 128KB tail for initial load
 const SYNC_WAIT_TIMEOUT_MS = 50;            // Wait timeout for terminal sync
 const STATS_POLLING_INTERVAL_MS = 2000;     // System stats polling

@@ -20,7 +20,7 @@
  <script defer src="vendor/xterm-addon-fit.min.js"></script>
  <script defer src="vendor/xterm-addon-webgl.min.js"></script>
  <script defer src="vendor/xterm-addon-unicode11.min.js"></script>
-  <script defer src="vendor/xterm-zerolag-input.js?v=0.3.0"></script>
+  <script defer src="vendor/xterm-zerolag-input.js?v=0.3.2"></script>
  <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
  <script>if(window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024))document.documentElement.classList.add('mobile-init');</script>
  <!-- Inline critical CSS for instant skeleton paint (before styles.css loads) -->
@@ -1674,14 +1674,14 @@
    <!-- Lines drawn dynamically -->
  </svg>

-  <script defer src="constants.js?v=0.3.0"></script>
-  <script defer src="mobile-handlers.js?v=0.3.0"></script>
-  <script defer src="voice-input.js?v=0.3.0"></script>
-  <script defer src="notification-manager.js?v=0.3.0"></script>
-  <script defer src="keyboard-accessory.js?v=0.3.0"></script>
-  <script defer src="app.js?v=0.3.0"></script>
-  <script defer src="ralph-wizard.js?v=0.3.0"></script>
-  <script defer src="api-client.js?v=0.3.0"></script>
-  <script defer src="subagent-windows.js?v=0.3.0"></script>
+  <script defer src="constants.js?v=0.3.2"></script>
+  <script defer src="mobile-handlers.js?v=0.3.2"></script>
+  <script defer src="voice-input.js?v=0.3.2"></script>
+  <script defer src="notification-manager.js?v=0.3.2"></script>
+  <script defer src="keyboard-accessory.js?v=0.3.2"></script>
+  <script defer src="app.js?v=0.3.2"></script>
+  <script defer src="ralph-wizard.js?v=0.3.2"></script>
+  <script defer src="api-client.js?v=0.3.2"></script>
+  <script defer src="subagent-windows.js?v=0.3.2"></script>
 </body>
 </html>
@@ -5825,6 +5825,8 @@ kbd {
  background: var(--bg-input);
  border-bottom: 1px solid var(--border);
  flex-shrink: 0;
+  cursor: move;
+  user-select: none;
 }

 .file-browser-title {
@@ -121,7 +121,7 @@ Object.assign(CodemanApp.prototype, {
      if (!windowData.minimized) {
        openWindows.push({
          agentId,
-          position: windowData.position || null
+          position: windowData.position || null,
        });
      }
    }
@@ -163,8 +163,7 @@ Object.assign(CodemanApp.prototype, {
          // Use the PERSISTENT parent map (THE source of truth)
          // Fall back to saved sessionId only if it exists in current sessions
          const parentFromMap = this.subagentParentMap.get(agentId);
-          const correctSessionId = parentFromMap ||
-            (this.sessions.has(savedSessionId) ? savedSessionId : null);
+          const correctSessionId = parentFromMap || (this.sessions.has(savedSessionId) ? savedSessionId : null);

          if (correctSessionId) {
            // Ensure the parent map has this association
@@ -184,7 +183,7 @@ Object.assign(CodemanApp.prototype, {
    // Restore open windows (for recent, non-completed agents only)
    const now = Date.now();
    const maxAgeMs = 10 * 60 * 1000; // 10 minutes - don't restore windows for old agents
-    for (const { agentId, position } of (states.open || [])) {
+    for (const { agentId, position } of states.open || []) {
      const agent = this.subagents.get(agentId);
      // Only restore window if agent exists, is recent, and is still active/idle
      const agentAge = agent?.startedAt ? now - agent.startedAt : Infinity;
@@ -458,6 +457,83 @@ Object.assign(CodemanApp.prototype, {
    }
  },

+  // ═══════════════════════════════════════════════════════════════
+  // Lazy Terminal Lifecycle
+  // ═══════════════════════════════════════════════════════════════
+  //
+  // Teammate terminal windows use xterm.js Terminal instances that consume
+  // ~75KB of DOM memory each. With 50 agents minimized, that's ~3.75MB of
+  // invisible terminals. To avoid this, we dispose the Terminal when a
+  // window is minimized and lazily re-create it when restored.
+  //
+  // Flow:
+  //   minimize → _disposeTeammateTerminalForMinimize() → sets _lazyTerminal flag
+  //   restore  → _restoreTeammateTerminalFromLazy()   → re-creates Terminal
+  //   create (hidden/minimized) → skip initTeammateTerminal, set _lazyTerminal
+  //
+  // The tmux pane buffer is re-fetched from the API on restore. Regular
+  // (non-teammate) subagent windows use activity HTML and are unaffected
+  // by this optimization.
+
+  /**
+   * Dispose a teammate terminal when its window is minimized.
+   * Saves pane metadata so the terminal can be re-created on restore.
+   * No-op if the window has no teammate terminal.
+   */
+  _disposeTeammateTerminalForMinimize(agentId) {
+    const termData = this.teammateTerminals.get(agentId);
+    if (!termData) return; // Not a teammate terminal window
+
+    const windowData = this.subagentWindows.get(agentId);
+
+    // Save pane metadata needed to re-create the terminal on restore
+    if (windowData) {
+      windowData._lazyTerminal = true;
+      windowData._lazyPaneTarget = termData.paneTarget;
+      windowData._lazySessionId = termData.sessionId;
+    }
+
+    // Dispose the resize observer
+    if (termData.resizeObserver) {
+      termData.resizeObserver.disconnect();
+    }
+
+    // Dispose the xterm.js Terminal instance (frees DOM nodes and internal buffers)
+    if (termData.terminal) {
+      try {
+        termData.terminal.dispose();
+      } catch {}
+    }
+
+    // Remove from teammateTerminals map so renderSubagentWindowContent won't skip this window
+    // (the activity HTML can serve as a lightweight placeholder while minimized)
+    this.teammateTerminals.delete(agentId);
+  },
+
+  /**
+   * Re-create a teammate terminal when its window is restored from minimized state.
+   * Fetches the current pane buffer from the API (tmux is the source of truth).
+   * No-op if the window doesn't have the _lazyTerminal flag.
+   */
+  _restoreTeammateTerminalFromLazy(agentId) {
+    const windowData = this.subagentWindows.get(agentId);
+    if (!windowData || !windowData._lazyTerminal) return;
+
+    const paneTarget = windowData._lazyPaneTarget;
+    const sessionId = windowData._lazySessionId;
+
+    // Clear lazy state
+    windowData._lazyTerminal = false;
+    windowData._lazyPaneTarget = null;
+    windowData._lazySessionId = null;
+
+    if (!paneTarget || !sessionId) return;
+
+    // Re-create the terminal using the same initTeammateTerminal flow
+    const paneInfo = { paneTarget, sessionId };
+    this.initTeammateTerminal(agentId, paneInfo, windowData.element);
+  },
+
  // ═══════════════════════════════════════════════════════════════
  // Subagent Floating Windows
  // ═══════════════════════════════════════════════════════════════
@@ -495,7 +571,7 @@ Object.assign(CodemanApp.prototype, {
    // Only open windows for agents that belong to a Codeman-managed session tab.
    // Agents from external Claude sessions (not tracked by Codeman) should not pop up.
    if (agent.sessionId) {
-      const hasMatchingTab = Array.from(this.sessions.values()).some(s => s.claudeSessionId === agent.sessionId);
+      const hasMatchingTab = Array.from(this.sessions.values()).some((s) => s.claudeSessionId === agent.sessionId);
      if (!hasMatchingTab) return;
    }

@@ -600,9 +676,7 @@ Object.assign(CodemanApp.prototype, {
    }

    // Get parent TAB element for spawn animation
-    const parentTab = parentSessionId
-      ? document.querySelector(`.session-tab[data-id="${parentSessionId}"]`)
-      : null;
+    const parentTab = parentSessionId ? document.querySelector(`.session-tab[data-id="${parentSessionId}"]`) : null;

    // Create window element
    const win = document.createElement('div');
@@ -611,17 +685,19 @@ Object.assign(CodemanApp.prototype, {
    win.style.zIndex = ++this.subagentWindowZIndex;

    // Build parent header if we have parent info
-    const parentHeader = parentSessionId && parentSessionName
-      ? `<div class="subagent-window-parent" data-parent-session="${parentSessionId}">
+    const parentHeader =
+      parentSessionId && parentSessionName
+        ? `<div class="subagent-window-parent" data-parent-session="${parentSessionId}">
          <span class="parent-label">from</span>
          <span class="parent-name" onclick="app.selectSession('${escapeHtml(parentSessionId)}')">${escapeHtml(parentSessionName)}</span>
        </div>`
-      : '';
+        : '';

    const teammateInfo = this.getTeammateInfo(agent);
-    const windowTitle = teammateInfo ? teammateInfo.name : (agent.description || agentId.substring(0, 7));
+    const windowTitle = teammateInfo ? teammateInfo.name : agent.description || agentId.substring(0, 7);
    const maxTitleLen = isMobile ? 30 : 50;
-    const truncatedTitle = windowTitle.length > maxTitleLen ? windowTitle.substring(0, maxTitleLen) + '...' : windowTitle;
+    const truncatedTitle =
+      windowTitle.length > maxTitleLen ? windowTitle.substring(0, maxTitleLen) + '...' : windowTitle;
    const modelBadge = agent.modelShort
      ? `<span class="subagent-model-badge ${agent.modelShort}">${agent.modelShort}</span>`
      : '';
@@ -695,7 +771,18 @@ Object.assign(CodemanApp.prototype, {
    // Render content — check if this teammate has a tmux pane
    const paneInfo = teammateInfo ? this.teammatePanesByName.get(teammateInfo.name) : null;
    if (paneInfo) {
-      this.initTeammateTerminal(agentId, paneInfo, win);
+      if (shouldHide) {
+        // Window starts hidden — defer terminal creation until visible (lazy init).
+        // Saves ~75KB of DOM memory per hidden teammate terminal window.
+        const windowEntry = this.subagentWindows.get(agentId);
+        if (windowEntry) {
+          windowEntry._lazyTerminal = true;
+          windowEntry._lazyPaneTarget = paneInfo.paneTarget;
+          windowEntry._lazySessionId = paneInfo.sessionId;
+        }
+      } else {
+        this.initTeammateTerminal(agentId, paneInfo, win);
+      }
    } else {
      this.renderSubagentWindowContent(agentId);
    }
@@ -755,6 +842,10 @@ Object.assign(CodemanApp.prototype, {
      this.setAgentParentSessionId(agentId, parentSessionId);
    }

+    // Dispose teammate terminal on minimize to free DOM/memory (~75KB per instance).
+    // The terminal will be lazily re-created on restore via initTeammateTerminal().
+    this._disposeTeammateTerminalForMinimize(agentId);
+
    // Always minimize to tab
    windowData.element.style.display = 'none';
    windowData.minimized = true;
@@ -829,7 +920,9 @@ Object.assign(CodemanApp.prototype, {
    for (const [, termData] of this.teammateTerminals) {
      if (termData.resizeObserver) termData.resizeObserver.disconnect();
      if (termData.terminal) {
-        try { termData.terminal.dispose(); } catch {}
+        try {
+          termData.terminal.dispose();
+        } catch {}
      }
    }
    this.teammateTerminals.clear();
@@ -959,6 +1052,13 @@ Object.assign(CodemanApp.prototype, {
        windowData.hidden = false;
      }
      windowData.minimized = false;
+
+      // Lazily re-create teammate terminal if it was disposed on minimize.
+      // Only re-create when the window is actually becoming visible.
+      if (shouldShow && windowData._lazyTerminal) {
+        this._restoreTeammateTerminalFromLazy(agentId);
+      }
+
      this.updateConnectionLines();
      // Restack all visible mobile windows so restored ones don't overlap
      this.relayoutMobileSubagentWindows();
@@ -1067,7 +1167,7 @@ Object.assign(CodemanApp.prototype, {
    if (!dropdown || dropdown.classList.contains('open')) return;

    // Close other dropdowns first
-    document.querySelectorAll('.subagent-dropdown.open').forEach(d => {
+    document.querySelectorAll('.subagent-dropdown.open').forEach((d) => {
      d.classList.remove('open', 'pinned');
      if (d.parentElement === document.body && d._originalParent) {
        d._originalParent.appendChild(d);
@@ -1089,8 +1189,8 @@ Object.assign(CodemanApp.prototype, {
  // Schedule hide after delay (allows moving mouse to dropdown)
  scheduleHideSubagentDropdown(badgeEl) {
    this._subagentHideTimeout = setTimeout(() => {
-      const dropdown = badgeEl?.querySelector?.('.subagent-dropdown') ||
-                       document.querySelector('.subagent-dropdown.open');
+      const dropdown =
+        badgeEl?.querySelector?.('.subagent-dropdown') || document.querySelector('.subagent-dropdown.open');
      if (dropdown && !dropdown.classList.contains('pinned')) {
        dropdown.classList.remove('open');
        if (dropdown._originalParent) {
@@ -11,7 +11,15 @@ import { SseEvent } from '../sse-events.js';
 import { findSessionOrFail, autoConfigureRalph } from '../route-helpers.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
-import { AI_CHECK_MODEL, AI_IDLE_CHECK_MAX_CONTEXT, AI_PLAN_CHECK_MAX_CONTEXT } from '../../config/ai-defaults.js';
+import {
+  AI_CHECK_MODEL,
+  AI_IDLE_CHECK_MAX_CONTEXT,
+  AI_PLAN_CHECK_MAX_CONTEXT,
+  AI_IDLE_CHECK_TIMEOUT_MS,
+  AI_IDLE_CHECK_COOLDOWN_MS,
+  AI_PLAN_CHECK_TIMEOUT_MS,
+  AI_PLAN_CHECK_COOLDOWN_MS,
+} from '../../config/ai-defaults.js';

 /** No-op EventPort used to suppress broadcasts during pre-start ralph configuration. */
 const noopEventPort: EventPort = {
@@ -188,14 +196,18 @@ export function registerRespawnRoutes(
      aiIdleCheckModel: config.aiIdleCheckModel ?? currentConfig?.aiIdleCheckModel ?? AI_CHECK_MODEL,
      aiIdleCheckMaxContext:
        config.aiIdleCheckMaxContext ?? currentConfig?.aiIdleCheckMaxContext ?? AI_IDLE_CHECK_MAX_CONTEXT,
-      aiIdleCheckTimeoutMs: config.aiIdleCheckTimeoutMs ?? currentConfig?.aiIdleCheckTimeoutMs ?? 90000,
-      aiIdleCheckCooldownMs: config.aiIdleCheckCooldownMs ?? currentConfig?.aiIdleCheckCooldownMs ?? 180000,
+      aiIdleCheckTimeoutMs:
+        config.aiIdleCheckTimeoutMs ?? currentConfig?.aiIdleCheckTimeoutMs ?? AI_IDLE_CHECK_TIMEOUT_MS,
+      aiIdleCheckCooldownMs:
+        config.aiIdleCheckCooldownMs ?? currentConfig?.aiIdleCheckCooldownMs ?? AI_IDLE_CHECK_COOLDOWN_MS,
      aiPlanCheckEnabled: config.aiPlanCheckEnabled ?? currentConfig?.aiPlanCheckEnabled ?? true,
      aiPlanCheckModel: config.aiPlanCheckModel ?? currentConfig?.aiPlanCheckModel ?? AI_CHECK_MODEL,
      aiPlanCheckMaxContext:
        config.aiPlanCheckMaxContext ?? currentConfig?.aiPlanCheckMaxContext ?? AI_PLAN_CHECK_MAX_CONTEXT,
-      aiPlanCheckTimeoutMs: config.aiPlanCheckTimeoutMs ?? currentConfig?.aiPlanCheckTimeoutMs ?? 60000,
-      aiPlanCheckCooldownMs: config.aiPlanCheckCooldownMs ?? currentConfig?.aiPlanCheckCooldownMs ?? 30000,
+      aiPlanCheckTimeoutMs:
+        config.aiPlanCheckTimeoutMs ?? currentConfig?.aiPlanCheckTimeoutMs ?? AI_PLAN_CHECK_TIMEOUT_MS,
+      aiPlanCheckCooldownMs:
+        config.aiPlanCheckCooldownMs ?? currentConfig?.aiPlanCheckCooldownMs ?? AI_PLAN_CHECK_COOLDOWN_MS,
      durationMinutes: currentConfig?.durationMinutes,
    };
    ctx.mux.updateRespawnConfig(id, merged);
@@ -120,6 +120,7 @@ import {
  ITERATION_PAUSE_MS,
  BATCH_FLUSH_THRESHOLD,
  STATS_COLLECTION_INTERVAL_MS,
+  INACTIVITY_TIMEOUT_MS,
 } from '../config/server-timing.js';

 // DEC mode 2026 - Synchronized Output
@@ -210,7 +211,12 @@ export class WebServer extends EventEmitter {
  // Store session listener references for explicit cleanup (prevents memory leaks)
  private sessionListenerRefs: Map<string, SessionListenerRefs> = new Map();
  private scheduledRuns: Map<string, ScheduledRun> = new Map();
-  private sseClients: Set<FastifyReply> = new Set();
+  /**
+   * SSE clients mapped to their session subscription filter.
+   * Value is a Set of session IDs the client wants events for,
+   * or `null` meaning "receive all events" (backwards-compatible default).
+   */
+  private sseClients: Map<FastifyReply, Set<string> | null> = new Map();
  /** Clients with backpressure — skip writes until 'drain' fires */
  private backpressuredClients: Set<FastifyReply> = new Set();
  private store = getStore();
@@ -225,7 +231,7 @@ export class WebServer extends EventEmitter {
  // Adaptive batching: track rapid events to extend batch window (per-session)
  // StaleExpirationMap auto-cleans entries for sessions that stop generating output
  private lastTerminalEventTime: StaleExpirationMap<string, number> = new StaleExpirationMap({
-    ttlMs: 5 * 60 * 1000, // 5 minutes - auto-expire stale session timing data
+    ttlMs: INACTIVITY_TIMEOUT_MS, // 5 minutes - auto-expire stale session timing data
    refreshOnGet: false, // Don't refresh on reads, only on explicit sets
  });
  // Centralized cleanup for standalone timers (intervals + resettable timeouts)
@@ -590,6 +596,21 @@ export class WebServer extends EventEmitter {
        return;
      }

+      // Parse optional session subscription filter from query parameter.
+      // /api/events?sessions=id1,id2 — client only receives events for those sessions.
+      // /api/events (no param) — client receives all events (backwards-compatible).
+      const query = req.query as { sessions?: string };
+      let sessionFilter: Set<string> | null = null;
+      if (query.sessions) {
+        const ids = query.sessions
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean);
+        if (ids.length > 0) {
+          sessionFilter = new Set(ids);
+        }
+      }
+
      reply.raw.writeHead(200, {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
@@ -597,7 +618,7 @@ export class WebServer extends EventEmitter {
        'X-Accel-Buffering': 'no', // Disable nginx buffering
      });

-      this.sseClients.add(reply);
+      this.sseClients.set(reply, sessionFilter);

      // Send initial state
      // Use light state for SSE init to avoid sending 2MB+ terminal buffers
@@ -630,6 +651,30 @@ export class WebServer extends EventEmitter {
      }
    });

+    // Crash diagnostics beacon — frontend POSTs breadcrumbs, GET to read them
+    let _crashBreadcrumbs = '';
+    this.app.addContentTypeParser('text/plain;charset=UTF-8', { parseAs: 'string' }, (_req, body, done) => {
+      try {
+        done(null, JSON.parse(body as string));
+      } catch {
+        done(null, { data: body });
+      }
+    });
+    this.app.addContentTypeParser('text/plain', { parseAs: 'string' }, (_req, body, done) => {
+      try {
+        done(null, JSON.parse(body as string));
+      } catch {
+        done(null, { data: body });
+      }
+    });
+    this.app.post('/api/crash-diag', (req, reply) => {
+      _crashBreadcrumbs = String((req.body as { data?: string })?.data || '');
+      reply.code(204).send();
+    });
+    this.app.get('/api/crash-diag', (_req, reply) => {
+      reply.code(200).send({ breadcrumbs: _crashBreadcrumbs, timestamp: Date.now() });
+    });
+
    // Register all route modules
    const ctx = this.createRouteContext();
    registerPushRoutes(this.app, ctx);
@@ -1922,7 +1967,8 @@ export class WebServer extends EventEmitter {
          // Client may have missed terminal data during backpressure.
          // Tell it to reload the active session's buffer to recover.
          try {
-            reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n`);
+            const drainPadding = this._isTunnelActive ? SSE_PADDING : '';
+            reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n${drainPadding}`);
          } catch {
            /* client gone */
          }
@@ -1948,9 +1994,12 @@ export class WebServer extends EventEmitter {
      this.cachedSessionsList = null;
    }
    // Performance optimization: serialize JSON once for all clients.
-    // Only append Cloudflare tunnel padding when tunnel is actually active —
-    // direct/Tailscale clients don't need 8KB padding on every event.
-    const padding = this._isTunnelActive ? SSE_PADDING : '';
+    // Only append Cloudflare tunnel padding for latency-sensitive events —
+    // Recovery events need immediate proxy flush; low-frequency metadata events
+    // (session:created, ralph:*, respawn:*, etc.) don't need padding.
+    // Note: session:terminal has its own padding in flushSessionTerminalBatch().
+    const needsPadding = this._isTunnelActive && event === SseEvent.SessionNeedsRefresh;
+    const padding = needsPadding ? SSE_PADDING : '';
    let message: string;
    try {
      message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n` + padding;
@@ -1959,11 +2008,35 @@ export class WebServer extends EventEmitter {
      console.error(`[Server] Failed to serialize SSE event "${event}":`, err);
      return;
    }
-    for (const client of this.sseClients) {
+    // Extract sessionId from event data for subscription filtering.
+    const eventSessionId = this.extractSessionId(event, data);
+
+    for (const [client, filter] of this.sseClients) {
+      // No filter (null) = receive everything. Otherwise, skip if event is
+      // session-scoped and the session isn't in the client's subscription set.
+      if (filter && eventSessionId && !filter.has(eventSessionId)) continue;
      this.sendSSEPreformatted(client, message);
    }
  }

+  /**
+   * Extract the session ID from an event's data payload for subscription filtering.
+   * Returns the sessionId string if the event is session-scoped, or null for global events.
+   */
+  private extractSessionId(event: string, data: unknown): string | null {
+    if (data == null || typeof data !== 'object') return null;
+    const record = data as Record<string, unknown>;
+
+    // Most session-scoped events use `sessionId`
+    if (typeof record.sessionId === 'string') return record.sessionId;
+
+    // Session lifecycle events (session:*) use `id` from the session state object
+    if (typeof record.id === 'string' && event.startsWith('session:')) return record.id;
+
+    // No session ID found — treat as global event (sent to all clients)
+    return null;
+  }
+
  // Batch terminal data for better performance (60fps)
  // Uses per-session timers with adaptive intervals to prevent thundering herd:
  // each session flushes independently rather than all sessions flushing in one burst.
@@ -2042,8 +2115,13 @@ export class WebServer extends EventEmitter {
      // Fast path: build SSE message directly without JSON.stringify on wrapper object.
      // Only the terminal data string needs escaping; sessionId is a UUID (safe to template).
      const escapedData = JSON.stringify(syncData);
-      const message = `event: session:terminal\ndata: {"id":"${sessionId}","data":${escapedData}}\n\n`;
-      for (const client of this.sseClients) {
+      // Append tunnel padding for immediate Cloudflare proxy flush —
+      // terminal data is high-frequency and latency-sensitive.
+      const padding = this._isTunnelActive ? SSE_PADDING : '';
+      const message = `event: session:terminal\ndata: {"id":"${sessionId}","data":${escapedData}}\n\n` + padding;
+      for (const [client, filter] of this.sseClients) {
+        // Skip clients that have a session filter and aren't subscribed to this session
+        if (filter && !filter.has(sessionId)) continue;
        this.sendSSEPreformatted(client, message);
      }
    }
@@ -2216,7 +2294,7 @@ export class WebServer extends EventEmitter {
  private cleanupDeadSSEClients(): void {
    const deadClients: FastifyReply[] = [];

-    for (const client of this.sseClients) {
+    for (const [client] of this.sseClients) {
      try {
        // Check if the underlying socket is still writable
        const socket = client.raw.socket;
@@ -2320,7 +2398,7 @@ export class WebServer extends EventEmitter {
      () => {
        this.recordPeriodicTokenUsage();
      },
-      5 * 60 * 1000,
+      INACTIVITY_TIMEOUT_MS,
      { description: 'periodic token recording' }
    );

@@ -2616,7 +2694,7 @@ export class WebServer extends EventEmitter {
    this.cleanup.dispose();

    // Gracefully close all SSE connections before clearing
-    for (const client of this.sseClients) {
+    for (const [client] of this.sseClients) {
      try {
        // Send a final event to notify clients of shutdown
        this.sendSSE(client, 'server:shutdown', { reason: 'Server stopping' });
@@ -0,0 +1,279 @@
+import { describe, it, expect, vi } from 'vitest';
+import { BufferAccumulator } from '../src/utils/buffer-accumulator.js';
+
+describe('BufferAccumulator', () => {
+  describe('construction', () => {
+    it('creates with simple size parameters', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      expect(buf.isEmpty).toBe(true);
+      expect(buf.length).toBe(0);
+      expect(buf.value).toBe('');
+    });
+
+    it('creates with BufferConfig object', () => {
+      const buf = new BufferAccumulator({ maxSize: 1000, trimSize: 800 });
+      expect(buf.isEmpty).toBe(true);
+    });
+
+    it('creates with BufferConfig including onTrim', () => {
+      const onTrim = vi.fn();
+      const buf = new BufferAccumulator({ maxSize: 100, trimSize: 50, onTrim });
+      buf.append('x'.repeat(101));
+      expect(onTrim).toHaveBeenCalled();
+    });
+  });
+
+  describe('append', () => {
+    it('appends data and updates length', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello');
+      expect(buf.length).toBe(5);
+      expect(buf.isEmpty).toBe(false);
+      buf.append(' world');
+      expect(buf.length).toBe(11);
+      expect(buf.value).toBe('hello world');
+    });
+
+    it('ignores empty strings', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('');
+      expect(buf.length).toBe(0);
+      expect(buf.isEmpty).toBe(true);
+    });
+
+    it('handles multiple chunks efficiently', () => {
+      const buf = new BufferAccumulator(10000, 8000);
+      for (let i = 0; i < 100; i++) {
+        buf.append(`chunk${i}`);
+      }
+      expect(buf.length).toBeGreaterThan(0);
+      const value = buf.value;
+      expect(value).toContain('chunk0');
+      expect(value).toContain('chunk99');
+    });
+  });
+
+  describe('value', () => {
+    it('returns empty string when empty', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      expect(buf.value).toBe('');
+    });
+
+    it('returns single chunk without joining', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('single');
+      expect(buf.value).toBe('single');
+    });
+
+    it('consolidates chunks on access', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('a');
+      buf.append('b');
+      buf.append('c');
+      expect(buf.value).toBe('abc');
+      // Access again should be same (consolidated)
+      expect(buf.value).toBe('abc');
+    });
+  });
+
+  describe('clear', () => {
+    it('resets buffer to empty', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('some data');
+      buf.clear();
+      expect(buf.isEmpty).toBe(true);
+      expect(buf.length).toBe(0);
+      expect(buf.value).toBe('');
+    });
+  });
+
+  describe('set', () => {
+    it('replaces buffer content', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('old data');
+      buf.set('new data');
+      expect(buf.value).toBe('new data');
+      expect(buf.length).toBe(8);
+    });
+
+    it('handles empty string', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('some data');
+      buf.set('');
+      expect(buf.isEmpty).toBe(true);
+      expect(buf.length).toBe(0);
+    });
+  });
+
+  describe('tail', () => {
+    it('returns last N characters', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world');
+      expect(buf.tail(5)).toBe('world');
+    });
+
+    it('returns entire buffer when N >= length', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('short');
+      expect(buf.tail(100)).toBe('short');
+    });
+
+    it('returns empty string on empty buffer', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      expect(buf.tail(5)).toBe('');
+    });
+  });
+
+  describe('endsWith', () => {
+    it('returns true when buffer ends with suffix', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world');
+      expect(buf.endsWith('world')).toBe(true);
+    });
+
+    it('returns false when buffer does not end with suffix', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world');
+      expect(buf.endsWith('hello')).toBe(false);
+    });
+
+    it('returns true for empty suffix', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello');
+      expect(buf.endsWith('')).toBe(true);
+    });
+
+    it('returns false when suffix is longer than buffer', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hi');
+      expect(buf.endsWith('hello world')).toBe(false);
+    });
+  });
+
+  describe('contains', () => {
+    it('finds string pattern in buffer', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world foo bar');
+      expect(buf.contains('world')).toBe(true);
+      expect(buf.contains('baz')).toBe(false);
+    });
+
+    it('finds regex pattern in buffer', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world 123');
+      expect(buf.contains(/\d+/)).toBe(true);
+      expect(buf.contains(/[A-Z]{3}/)).toBe(false);
+    });
+
+    it('searches within last N characters when fromEnd provided', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('hello world');
+      expect(buf.contains('hello', 5)).toBe(false); // last 5 = 'world'
+      expect(buf.contains('world', 5)).toBe(true);
+    });
+
+    it('regex search with fromEnd', () => {
+      const buf = new BufferAccumulator(1000, 800);
+      buf.append('abc 123 xyz');
+      expect(buf.contains(/\d+/, 4)).toBe(false); // last 4 = ' xyz'
+      expect(buf.contains(/\d+/, 8)).toBe(true); // last 8 = '123 xyz'
+    });
+  });
+
+  describe('trimming', () => {
+    it('trims when maxSize is exceeded', () => {
+      const buf = new BufferAccumulator(100, 50);
+      buf.append('x'.repeat(60));
+      buf.append('y'.repeat(50)); // total 110, triggers trim
+      expect(buf.length).toBeLessThanOrEqual(100);
+      // After trim, should keep most recent data
+      expect(buf.value).toContain('y');
+    });
+
+    it('calls onTrim callback with trimmed byte count', () => {
+      const onTrim = vi.fn();
+      const buf = new BufferAccumulator({ maxSize: 100, trimSize: 50, onTrim });
+      buf.append('x'.repeat(101)); // triggers trim
+      expect(onTrim).toHaveBeenCalledTimes(1);
+      expect(onTrim).toHaveBeenCalledWith(expect.any(Number));
+      const trimmedBytes = onTrim.mock.calls[0][0] as number;
+      expect(trimmedBytes).toBeGreaterThan(0);
+    });
+
+    it('keeps most recent data after trim', () => {
+      const buf = new BufferAccumulator(100, 50);
+      buf.append('A'.repeat(60));
+      buf.append('B'.repeat(50)); // total 110, triggers trim to ~50 chars
+      const value = buf.value;
+      // The end should be B's
+      expect(value.endsWith('B')).toBe(true);
+    });
+
+    it('advances past first newline within 4KB to avoid mid-ANSI-escape', () => {
+      const buf = new BufferAccumulator(100, 80);
+      // Create content that when trimmed, has a newline near the start of the kept portion
+      const prefix = 'A'.repeat(30);
+      const newlineSection = 'X'.repeat(10) + '\n' + 'Y'.repeat(10);
+      const suffix = 'B'.repeat(60);
+      buf.append(prefix + newlineSection + suffix);
+      // After trimming, the buffer should start after the first newline in the kept portion
+      const value = buf.value;
+      // Should not start with partial X's before the newline
+      if (value.includes('\n')) {
+        // If the newline fell within the kept window, it should be skipped
+        expect(value.startsWith('X')).toBe(false);
+      }
+    });
+
+    it('handles trim with no newline in first 4KB', () => {
+      const buf = new BufferAccumulator(100, 50);
+      // No newlines at all
+      buf.append('A'.repeat(110));
+      // Should still trim without error
+      expect(buf.length).toBeLessThanOrEqual(100);
+    });
+
+    it('does not call onTrim when trimmedBytes is 0 or negative', () => {
+      const onTrim = vi.fn();
+      // trimSize equal to maxSize means nothing actually gets trimmed in bytes
+      // But this scenario is unusual; just test that onTrim is only called with positive values
+      const buf = new BufferAccumulator({ maxSize: 50, trimSize: 50, onTrim });
+      buf.append('x'.repeat(51)); // triggers trim, but trimSize == 50 so 1 byte trimmed
+      // The trim logic: full.length(51) - trimSize(50) = 1 > 0, so onTrim IS called
+      expect(onTrim).toHaveBeenCalledWith(expect.any(Number));
+    });
+  });
+
+  describe('edge cases', () => {
+    it('works with very small maxSize', () => {
+      const buf = new BufferAccumulator(5, 3);
+      buf.append('abcdef'); // 6 chars, triggers trim to 3
+      expect(buf.length).toBeLessThanOrEqual(5);
+    });
+
+    it('handles rapid appends', () => {
+      const buf = new BufferAccumulator(10000, 8000);
+      for (let i = 0; i < 1000; i++) {
+        buf.append('data');
+      }
+      expect(buf.length).toBeLessThanOrEqual(10000);
+      expect(buf.length).toBeGreaterThan(0);
+    });
+
+    it('set after trim works correctly', () => {
+      const buf = new BufferAccumulator(100, 50);
+      buf.append('x'.repeat(110)); // triggers trim
+      buf.set('fresh start');
+      expect(buf.value).toBe('fresh start');
+      expect(buf.length).toBe(11);
+    });
+
+    it('clear after trim works correctly', () => {
+      const buf = new BufferAccumulator(100, 50);
+      buf.append('x'.repeat(110)); // triggers trim
+      buf.clear();
+      expect(buf.isEmpty).toBe(true);
+      expect(buf.value).toBe('');
+    });
+  });
+});
@@ -0,0 +1,356 @@
+import { describe, it, expect, vi } from 'vitest';
+import { LRUMap } from '../src/utils/lru-map.js';
+
+describe('LRUMap', () => {
+  describe('construction', () => {
+    it('creates an empty map with maxSize', () => {
+      const map = new LRUMap<string, number>({ maxSize: 5 });
+      expect(map.size).toBe(0);
+      expect(map.maxEntries).toBe(5);
+      expect(map.freeSlots).toBe(5);
+    });
+
+    it('accepts an onEvict callback', () => {
+      const onEvict = vi.fn();
+      const map = new LRUMap<string, number>({ maxSize: 2, onEvict });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3); // evicts 'a'
+      expect(onEvict).toHaveBeenCalledWith('a', 1);
+    });
+  });
+
+  describe('set/get', () => {
+    it('stores and retrieves values', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      expect(map.get('a')).toBe(1);
+      expect(map.get('b')).toBe(2);
+    });
+
+    it('returns undefined for missing keys', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.get('nonexistent')).toBeUndefined();
+    });
+
+    it('overwrites existing key and refreshes position', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('a', 10); // refresh 'a' position
+      expect(map.get('a')).toBe(10);
+      expect(map.keysInOrder()).toEqual(['b', 'a']);
+    });
+
+    it('supports chaining on set', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      const result = map.set('a', 1).set('b', 2);
+      expect(result).toBe(map);
+      expect(map.size).toBe(2);
+    });
+  });
+
+  describe('has', () => {
+    it('returns true for existing keys', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      expect(map.has('a')).toBe(true);
+    });
+
+    it('returns false for missing keys', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.has('a')).toBe(false);
+    });
+
+    it('does not refresh position', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.has('a'); // should NOT refresh 'a'
+      expect(map.keysInOrder()).toEqual(['a', 'b']);
+    });
+  });
+
+  describe('delete', () => {
+    it('removes an existing key', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      expect(map.delete('a')).toBe(true);
+      expect(map.has('a')).toBe(false);
+      expect(map.size).toBe(0);
+    });
+
+    it('returns false for non-existent key', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.delete('nonexistent')).toBe(false);
+    });
+
+    it('updates newestKey when deleting the newest entry', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3);
+      map.delete('c'); // delete newest
+      expect(map.newest()).toEqual(['b', 2]);
+    });
+
+    it('handles deleting the only entry', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.delete('a');
+      expect(map.newest()).toBeUndefined();
+      expect(map.oldest()).toBeUndefined();
+    });
+  });
+
+  describe('clear', () => {
+    it('removes all entries', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.clear();
+      expect(map.size).toBe(0);
+      expect(map.newest()).toBeUndefined();
+      expect(map.oldest()).toBeUndefined();
+    });
+  });
+
+  describe('eviction', () => {
+    it('evicts oldest entry when exceeding maxSize', () => {
+      const map = new LRUMap<string, number>({ maxSize: 2 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3); // evicts 'a'
+      expect(map.has('a')).toBe(false);
+      expect(map.has('b')).toBe(true);
+      expect(map.has('c')).toBe(true);
+      expect(map.size).toBe(2);
+    });
+
+    it('evicts multiple entries to stay within maxSize', () => {
+      const map = new LRUMap<string, number>({ maxSize: 1 });
+      map.set('a', 1);
+      map.set('b', 2); // evicts 'a'
+      expect(map.size).toBe(1);
+      expect(map.has('a')).toBe(false);
+      expect(map.get('b')).toBe(2);
+    });
+
+    it('calls onEvict for each evicted entry', () => {
+      const onEvict = vi.fn();
+      const map = new LRUMap<string, number>({ maxSize: 2, onEvict });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3); // evicts 'a'
+      map.set('d', 4); // evicts 'b'
+      expect(onEvict).toHaveBeenCalledTimes(2);
+      expect(onEvict).toHaveBeenCalledWith('a', 1);
+      expect(onEvict).toHaveBeenCalledWith('b', 2);
+    });
+
+    it('get() refreshes position and changes eviction order', () => {
+      const map = new LRUMap<string, number>({ maxSize: 2 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.get('a'); // refresh 'a' — now 'b' is oldest
+      map.set('c', 3); // evicts 'b', not 'a'
+      expect(map.has('a')).toBe(true);
+      expect(map.has('b')).toBe(false);
+      expect(map.has('c')).toBe(true);
+    });
+  });
+
+  describe('peek', () => {
+    it('returns value without refreshing position', () => {
+      const map = new LRUMap<string, number>({ maxSize: 2 });
+      map.set('a', 1);
+      map.set('b', 2);
+      expect(map.peek('a')).toBe(1);
+      // 'a' should still be oldest since peek doesn't refresh
+      map.set('c', 3); // should evict 'a'
+      expect(map.has('a')).toBe(false);
+    });
+
+    it('returns undefined for missing keys', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.peek('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('oldest/newest', () => {
+    it('returns undefined on empty map', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.oldest()).toBeUndefined();
+      expect(map.newest()).toBeUndefined();
+    });
+
+    it('returns correct oldest and newest', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3);
+      expect(map.oldest()).toEqual(['a', 1]);
+      expect(map.newest()).toEqual(['c', 3]);
+    });
+
+    it('newest updates after get()', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.get('a'); // 'a' becomes newest
+      expect(map.newest()).toEqual(['a', 1]);
+      expect(map.oldest()).toEqual(['b', 2]);
+    });
+
+    it('newest updates after set() overwrites', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('a', 10); // 'a' refreshed to newest
+      expect(map.newest()).toEqual(['a', 10]);
+    });
+  });
+
+  describe('expireOlderThan', () => {
+    it('removes entries older than cutoff', () => {
+      const map = new LRUMap<string, { ts: number }>({ maxSize: 5 });
+      const now = Date.now();
+      map.set('old1', { ts: now - 10000 });
+      map.set('old2', { ts: now - 8000 });
+      map.set('new1', { ts: now - 1000 });
+
+      const evicted = map.expireOlderThan(5000, (v) => v.ts);
+      expect(evicted).toBe(2);
+      expect(map.size).toBe(1);
+      expect(map.has('new1')).toBe(true);
+    });
+
+    it('calls onEvict for expired entries', () => {
+      const onEvict = vi.fn();
+      const map = new LRUMap<string, { ts: number }>({ maxSize: 5, onEvict });
+      const now = Date.now();
+      map.set('old', { ts: now - 10000 });
+      map.set('new', { ts: now - 100 });
+
+      map.expireOlderThan(5000, (v) => v.ts);
+      expect(onEvict).toHaveBeenCalledTimes(1);
+      expect(onEvict).toHaveBeenCalledWith('old', { ts: now - 10000 });
+    });
+
+    it('returns 0 when nothing to expire', () => {
+      const map = new LRUMap<string, { ts: number }>({ maxSize: 5 });
+      const now = Date.now();
+      map.set('a', { ts: now });
+      expect(map.expireOlderThan(5000, (v) => v.ts)).toBe(0);
+    });
+
+    it('handles empty map', () => {
+      const map = new LRUMap<string, { ts: number }>({ maxSize: 5 });
+      expect(map.expireOlderThan(5000, (v) => v.ts)).toBe(0);
+    });
+
+    it('updates newestKey when all entries expired', () => {
+      const map = new LRUMap<string, { ts: number }>({ maxSize: 5 });
+      const now = Date.now();
+      map.set('a', { ts: now - 20000 });
+      map.set('b', { ts: now - 10000 });
+      map.expireOlderThan(5000, (v) => v.ts);
+      expect(map.newest()).toBeUndefined();
+      expect(map.size).toBe(0);
+    });
+  });
+
+  describe('keysInOrder/valuesInOrder', () => {
+    it('returns keys from oldest to newest', () => {
+      const map = new LRUMap<string, number>({ maxSize: 5 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3);
+      expect(map.keysInOrder()).toEqual(['a', 'b', 'c']);
+    });
+
+    it('returns values from oldest to newest', () => {
+      const map = new LRUMap<string, number>({ maxSize: 5 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3);
+      expect(map.valuesInOrder()).toEqual([1, 2, 3]);
+    });
+
+    it('reflects refreshed order', () => {
+      const map = new LRUMap<string, number>({ maxSize: 5 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3);
+      map.get('a'); // 'a' moves to end
+      expect(map.keysInOrder()).toEqual(['b', 'c', 'a']);
+      expect(map.valuesInOrder()).toEqual([2, 3, 1]);
+    });
+
+    it('returns empty arrays for empty map', () => {
+      const map = new LRUMap<string, number>({ maxSize: 5 });
+      expect(map.keysInOrder()).toEqual([]);
+      expect(map.valuesInOrder()).toEqual([]);
+    });
+  });
+
+  describe('maxEntries/freeSlots', () => {
+    it('freeSlots decreases as entries are added', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      expect(map.freeSlots).toBe(3);
+      map.set('a', 1);
+      expect(map.freeSlots).toBe(2);
+      map.set('b', 2);
+      expect(map.freeSlots).toBe(1);
+      map.set('c', 3);
+      expect(map.freeSlots).toBe(0);
+    });
+
+    it('freeSlots does not go below 0 after eviction', () => {
+      const map = new LRUMap<string, number>({ maxSize: 2 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.set('c', 3); // evicts 'a'
+      expect(map.freeSlots).toBe(0);
+      expect(map.size).toBe(2);
+    });
+  });
+
+  describe('iteration', () => {
+    it('iterates entries via for..of', () => {
+      const map = new LRUMap<string, number>({ maxSize: 3 });
+      map.set('a', 1);
+      map.set('b', 2);
+      const entries: [string, number][] = [];
+      for (const [k, v] of map) {
+        entries.push([k, v]);
+      }
+      expect(entries).toEqual([
+        ['a', 1],
+        ['b', 2],
+      ]);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('works with maxSize of 1', () => {
+      const map = new LRUMap<string, number>({ maxSize: 1 });
+      map.set('a', 1);
+      expect(map.get('a')).toBe(1);
+      map.set('b', 2);
+      expect(map.has('a')).toBe(false);
+      expect(map.get('b')).toBe(2);
+      expect(map.size).toBe(1);
+    });
+
+    it('handles non-string keys', () => {
+      const map = new LRUMap<number, string>({ maxSize: 3 });
+      map.set(1, 'one');
+      map.set(2, 'two');
+      expect(map.get(1)).toBe('one');
+      // get(1) refreshes key 1, so order is now [2, 1]
+      expect(map.keysInOrder()).toEqual([2, 1]);
+    });
+  });
+});
@@ -0,0 +1,248 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RespawnAdaptiveTiming, AdaptiveTimingConfig } from '../src/respawn-adaptive-timing.js';
+
+describe('RespawnAdaptiveTiming', () => {
+  let timing: RespawnAdaptiveTiming;
+  const defaultConfig: AdaptiveTimingConfig = {
+    adaptiveMinConfirmMs: 5000,
+    adaptiveMaxConfirmMs: 30000,
+  };
+
+  beforeEach(() => {
+    timing = new RespawnAdaptiveTiming(defaultConfig);
+  });
+
+  describe('initial state', () => {
+    it('should start with default 10000ms completion confirm', () => {
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(10000);
+    });
+
+    it('should start with empty timing history', () => {
+      const history = timing.getTimingHistory();
+      expect(history.recentIdleDetectionMs).toEqual([]);
+      expect(history.recentCycleDurationMs).toEqual([]);
+      expect(history.sampleCount).toBe(0);
+      expect(history.maxSamples).toBe(20);
+    });
+  });
+
+  describe('recordTimingData', () => {
+    it('should add samples to rolling windows', () => {
+      timing.recordTimingData(1000, 5000);
+
+      const history = timing.getTimingHistory();
+      expect(history.recentIdleDetectionMs).toEqual([1000]);
+      expect(history.recentCycleDurationMs).toEqual([5000]);
+      expect(history.sampleCount).toBe(1);
+    });
+
+    it('should accumulate multiple samples', () => {
+      timing.recordTimingData(1000, 5000);
+      timing.recordTimingData(2000, 6000);
+      timing.recordTimingData(3000, 7000);
+
+      const history = timing.getTimingHistory();
+      expect(history.recentIdleDetectionMs).toEqual([1000, 2000, 3000]);
+      expect(history.recentCycleDurationMs).toEqual([5000, 6000, 7000]);
+      expect(history.sampleCount).toBe(3);
+    });
+
+    it('should trim to maxSamples when exceeded', () => {
+      // Add 22 samples (exceeds maxSamples of 20)
+      for (let i = 1; i <= 22; i++) {
+        timing.recordTimingData(i * 100, i * 500);
+      }
+
+      const history = timing.getTimingHistory();
+      expect(history.recentIdleDetectionMs.length).toBe(20);
+      expect(history.recentCycleDurationMs.length).toBe(20);
+      // First two should have been shifted off
+      expect(history.recentIdleDetectionMs[0]).toBe(300); // 3rd sample
+      expect(history.recentCycleDurationMs[0]).toBe(1500);
+      expect(history.sampleCount).toBe(20);
+    });
+
+    it('should update lastUpdatedAt timestamp', () => {
+      const before = Date.now();
+      timing.recordTimingData(1000, 5000);
+      const after = Date.now();
+
+      const history = timing.getTimingHistory();
+      expect(history.lastUpdatedAt).toBeGreaterThanOrEqual(before);
+      expect(history.lastUpdatedAt).toBeLessThanOrEqual(after);
+    });
+  });
+
+  describe('adaptive timing calculation', () => {
+    it('should not recalculate with fewer than 5 samples', () => {
+      // Add 4 samples -- below the threshold
+      for (let i = 0; i < 4; i++) {
+        timing.recordTimingData(8000, 20000);
+      }
+
+      // Should still be the default
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(10000);
+    });
+
+    it('should recalculate at exactly 5 samples', () => {
+      // All the same value = easy to predict
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(10000, 20000);
+      }
+
+      // P75 of [10000, 10000, 10000, 10000, 10000] = 10000
+      // With 20% buffer = 12000, clamped to [5000, 30000] = 12000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(12000);
+    });
+
+    it('should use 75th percentile with 20% buffer', () => {
+      // 5 sorted values: 1000, 2000, 3000, 4000, 5000
+      timing.recordTimingData(3000, 10000);
+      timing.recordTimingData(1000, 10000);
+      timing.recordTimingData(5000, 10000);
+      timing.recordTimingData(2000, 10000);
+      timing.recordTimingData(4000, 10000);
+
+      // Sorted: [1000, 2000, 3000, 4000, 5000]
+      // P75 index = floor(5 * 0.75) = 3 -> value = 4000
+      // With 20% buffer: 4000 * 1.2 = 4800
+      // Clamped to min 5000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(5000);
+    });
+
+    it('should clamp to minimum configured value', () => {
+      // Very small idle detection times
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(1000, 5000);
+      }
+
+      // P75 = 1000, with buffer = 1200, clamped to min 5000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(5000);
+    });
+
+    it('should clamp to maximum configured value', () => {
+      // Very large idle detection times
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(50000, 100000);
+      }
+
+      // P75 = 50000, with buffer = 60000, clamped to max 30000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(30000);
+    });
+
+    it('should handle varying values correctly', () => {
+      // 10 values, spread out
+      const values = [2000, 4000, 6000, 8000, 10000, 12000, 14000, 16000, 18000, 20000];
+      for (const v of values) {
+        timing.recordTimingData(v, v * 2);
+      }
+
+      // Sorted: [2000, 4000, 6000, 8000, 10000, 12000, 14000, 16000, 18000, 20000]
+      // P75 index = floor(10 * 0.75) = 7 -> value = 16000
+      // With 20% buffer: 16000 * 1.2 = 19200
+      // Clamped to [5000, 30000] = 19200
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(19200);
+    });
+
+    it('should adapt as new data arrives', () => {
+      // Start with small values
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(3000, 10000);
+      }
+      // P75 = 3000, buffer = 3600, clamped to min 5000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(5000);
+
+      // Now add larger values that shift the P75 up
+      for (let i = 0; i < 10; i++) {
+        timing.recordTimingData(20000, 40000);
+      }
+      // P75 of mostly-20000 values = 20000, buffer = 24000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(24000);
+    });
+  });
+
+  describe('getTimingHistory', () => {
+    it('should return a new object each call (shallow copy)', () => {
+      timing.recordTimingData(1000, 5000);
+      const history1 = timing.getTimingHistory();
+      const history2 = timing.getTimingHistory();
+
+      // Different object references each time
+      expect(history1).not.toBe(history2);
+      // But equal content
+      expect(history1).toEqual(history2);
+    });
+
+    it('should allow overwriting top-level fields on the copy without affecting source', () => {
+      timing.recordTimingData(1000, 5000);
+      const copy = timing.getTimingHistory();
+      copy.sampleCount = 999;
+
+      expect(timing.getTimingHistory().sampleCount).toBe(1);
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all timing history', () => {
+      // Add some data
+      for (let i = 0; i < 10; i++) {
+        timing.recordTimingData(i * 1000, i * 5000);
+      }
+
+      timing.reset();
+
+      const history = timing.getTimingHistory();
+      expect(history.recentIdleDetectionMs).toEqual([]);
+      expect(history.recentCycleDurationMs).toEqual([]);
+      expect(history.adaptiveCompletionConfirmMs).toBe(10000);
+      expect(history.sampleCount).toBe(0);
+      expect(history.maxSamples).toBe(20);
+    });
+
+    it('should allow re-recording after reset', () => {
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(10000, 20000);
+      }
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(12000);
+
+      timing.reset();
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(10000);
+
+      // Record new data -- below 5 samples, should stay at default
+      timing.recordTimingData(5000, 10000);
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(10000);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle zero idle detection times', () => {
+      for (let i = 0; i < 5; i++) {
+        timing.recordTimingData(0, 5000);
+      }
+      // P75 = 0, buffer = 0, clamped to min 5000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(5000);
+    });
+
+    it('should handle identical values', () => {
+      for (let i = 0; i < 20; i++) {
+        timing.recordTimingData(15000, 30000);
+      }
+      // P75 = 15000, buffer = 18000
+      expect(timing.getAdaptiveCompletionConfirmMs()).toBe(18000);
+    });
+
+    it('should handle config with very narrow bounds', () => {
+      const narrowTiming = new RespawnAdaptiveTiming({
+        adaptiveMinConfirmMs: 10000,
+        adaptiveMaxConfirmMs: 10000,
+      });
+
+      for (let i = 0; i < 5; i++) {
+        narrowTiming.recordTimingData(50000, 100000);
+      }
+
+      // Always clamped to 10000 regardless of data
+      expect(narrowTiming.getAdaptiveCompletionConfirmMs()).toBe(10000);
+    });
+  });
+});
@@ -0,0 +1,517 @@
+import { describe, it, expect } from 'vitest';
+import { calculateHealthScore, shouldSkipClear, HealthInputs } from '../src/respawn-health.js';
+import type { RespawnAggregateMetrics, CircuitBreakerStatus } from '../src/types/index.js';
+
+/**
+ * Helper to create a default healthy HealthInputs object.
+ * Override specific fields as needed.
+ */
+function createHealthInputs(overrides: Partial<HealthInputs> = {}): HealthInputs {
+  return {
+    aggregateMetrics: {
+      totalCycles: 10,
+      successfulCycles: 10,
+      stuckRecoveryCycles: 0,
+      blockedCycles: 0,
+      errorCycles: 0,
+      avgCycleDurationMs: 5000,
+      avgIdleDetectionMs: 1000,
+      p90CycleDurationMs: 8000,
+      successRate: 100,
+      lastUpdatedAt: Date.now(),
+    },
+    circuitBreakerStatus: null,
+    iterationStallMetrics: null,
+    aiCheckerState: { status: 'ready', consecutiveErrors: 0 },
+    stuckRecoveryCount: 0,
+    maxStuckRecoveries: 5,
+    ...overrides,
+  };
+}
+
+function createCircuitBreakerStatus(state: 'CLOSED' | 'HALF_OPEN' | 'OPEN'): CircuitBreakerStatus {
+  return {
+    state,
+    consecutiveNoProgress: state === 'OPEN' ? 5 : state === 'HALF_OPEN' ? 2 : 0,
+    consecutiveSameError: 0,
+    consecutiveTestsFailure: 0,
+    lastProgressIteration: 0,
+    reason: `State: ${state}`,
+    reasonCode: 'no_progress',
+    lastTransitionAt: Date.now(),
+    lastErrorMessage: null,
+  };
+}
+
+describe('calculateHealthScore', () => {
+  describe('overall score calculation', () => {
+    it('should return 100 for perfectly healthy system', () => {
+      const result = calculateHealthScore(createHealthInputs());
+
+      expect(result.score).toBe(100);
+      expect(result.status).toBe('excellent');
+      expect(result.components.cycleSuccess).toBe(100);
+      expect(result.components.circuitBreaker).toBe(100);
+      expect(result.components.iterationProgress).toBe(100);
+      expect(result.components.aiChecker).toBe(100);
+      expect(result.components.stuckRecovery).toBe(100);
+    });
+
+    it('should return excellent for score >= 90', () => {
+      const result = calculateHealthScore(createHealthInputs());
+      expect(result.score).toBeGreaterThanOrEqual(90);
+      expect(result.status).toBe('excellent');
+    });
+
+    it('should return good for score >= 70 and < 90', () => {
+      // AI checker disabled = 30 (weight 0.15), everything else 100
+      // Score = 100*0.35 + 100*0.2 + 100*0.2 + 30*0.15 + 100*0.1 = 35+20+20+4.5+10 = 89.5 -> 90
+      // That's still excellent. Let's use circuitBreaker half-open for 50 (weight 0.2):
+      // Score = 100*0.35 + 50*0.2 + 100*0.2 + 100*0.15 + 100*0.1 = 35+10+20+15+10 = 90
+      // Still excellent. Use a lower cycleSuccess:
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 8,
+            stuckRecoveryCycles: 1,
+            blockedCycles: 1,
+            errorCycles: 0,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 80,
+            lastUpdatedAt: Date.now(),
+          },
+          circuitBreakerStatus: createCircuitBreakerStatus('HALF_OPEN'),
+        })
+      );
+      // cycleSuccess=80, circuitBreaker=50, iterationProgress=100, aiChecker=100, stuckRecovery=100
+      // 80*0.35 + 50*0.2 + 100*0.2 + 100*0.15 + 100*0.1 = 28+10+20+15+10 = 83
+      expect(result.score).toBe(83);
+      expect(result.status).toBe('good');
+    });
+
+    it('should return degraded for score >= 50 and < 70', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 5,
+            stuckRecoveryCycles: 2,
+            blockedCycles: 2,
+            errorCycles: 1,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 50,
+            lastUpdatedAt: Date.now(),
+          },
+          circuitBreakerStatus: createCircuitBreakerStatus('HALF_OPEN'),
+          aiCheckerState: { status: 'cooldown', consecutiveErrors: 0 },
+        })
+      );
+      // cycleSuccess=50, circuitBreaker=50, iterationProgress=100, aiChecker=70, stuckRecovery=100
+      // 50*0.35 + 50*0.2 + 100*0.2 + 70*0.15 + 100*0.1 = 17.5+10+20+10.5+10 = 68
+      expect(result.score).toBe(68);
+      expect(result.status).toBe('degraded');
+    });
+
+    it('should return critical for score < 50', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 0,
+            stuckRecoveryCycles: 3,
+            blockedCycles: 4,
+            errorCycles: 3,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 0,
+            lastUpdatedAt: Date.now(),
+          },
+          circuitBreakerStatus: createCircuitBreakerStatus('OPEN'),
+          iterationStallMetrics: {
+            stallDurationMs: 600000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+          aiCheckerState: { status: 'error', consecutiveErrors: 3 },
+          stuckRecoveryCount: 5,
+          maxStuckRecoveries: 5,
+        })
+      );
+      // cycleSuccess=0, circuitBreaker=0, iterationProgress=0, aiChecker=50, stuckRecovery=0
+      // 0*0.35 + 0*0.2 + 0*0.2 + 50*0.15 + 0*0.1 = 7.5 -> 8
+      expect(result.score).toBeLessThan(50);
+      expect(result.status).toBe('critical');
+    });
+  });
+
+  describe('component: cycleSuccess', () => {
+    it('should return 100 when no cycles have been tracked', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 0,
+            successfulCycles: 0,
+            stuckRecoveryCycles: 0,
+            blockedCycles: 0,
+            errorCycles: 0,
+            avgCycleDurationMs: 0,
+            avgIdleDetectionMs: 0,
+            p90CycleDurationMs: 0,
+            successRate: 100,
+            lastUpdatedAt: Date.now(),
+          },
+        })
+      );
+      expect(result.components.cycleSuccess).toBe(100);
+    });
+
+    it('should use successRate from aggregate metrics', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 20,
+            successfulCycles: 15,
+            stuckRecoveryCycles: 3,
+            blockedCycles: 1,
+            errorCycles: 1,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 75,
+            lastUpdatedAt: Date.now(),
+          },
+        })
+      );
+      expect(result.components.cycleSuccess).toBe(75);
+    });
+  });
+
+  describe('component: circuitBreaker', () => {
+    it('should return 100 when circuit breaker is null', () => {
+      const result = calculateHealthScore(createHealthInputs({ circuitBreakerStatus: null }));
+      expect(result.components.circuitBreaker).toBe(100);
+    });
+
+    it('should return 100 for CLOSED state', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ circuitBreakerStatus: createCircuitBreakerStatus('CLOSED') })
+      );
+      expect(result.components.circuitBreaker).toBe(100);
+    });
+
+    it('should return 50 for HALF_OPEN state', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ circuitBreakerStatus: createCircuitBreakerStatus('HALF_OPEN') })
+      );
+      expect(result.components.circuitBreaker).toBe(50);
+    });
+
+    it('should return 0 for OPEN state', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ circuitBreakerStatus: createCircuitBreakerStatus('OPEN') })
+      );
+      expect(result.components.circuitBreaker).toBe(0);
+    });
+  });
+
+  describe('component: iterationProgress', () => {
+    it('should return 100 when stall metrics are null', () => {
+      const result = calculateHealthScore(createHealthInputs({ iterationStallMetrics: null }));
+      expect(result.components.iterationProgress).toBe(100);
+    });
+
+    it('should return 100 when stall duration is below half the warning threshold', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 10000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.components.iterationProgress).toBe(100);
+    });
+
+    it('should return 70 when stall duration is at half the warning threshold', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 150000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.components.iterationProgress).toBe(70);
+    });
+
+    it('should return 30 when stall duration hits warning threshold', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 300000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.components.iterationProgress).toBe(30);
+    });
+
+    it('should return 0 when stall duration hits critical threshold', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 600000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.components.iterationProgress).toBe(0);
+    });
+
+    it('should return 0 when stall duration exceeds critical threshold', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 900000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.components.iterationProgress).toBe(0);
+    });
+  });
+
+  describe('component: aiChecker', () => {
+    it('should return 100 for ready status with no errors', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ aiCheckerState: { status: 'ready', consecutiveErrors: 0 } })
+      );
+      expect(result.components.aiChecker).toBe(100);
+    });
+
+    it('should return 30 for disabled status', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ aiCheckerState: { status: 'disabled', consecutiveErrors: 0 } })
+      );
+      expect(result.components.aiChecker).toBe(30);
+    });
+
+    it('should return 70 for cooldown status', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ aiCheckerState: { status: 'cooldown', consecutiveErrors: 0 } })
+      );
+      expect(result.components.aiChecker).toBe(70);
+    });
+
+    it('should return 50 for ready status with consecutive errors', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({ aiCheckerState: { status: 'ready', consecutiveErrors: 2 } })
+      );
+      expect(result.components.aiChecker).toBe(50);
+    });
+  });
+
+  describe('component: stuckRecovery', () => {
+    it('should return 100 when no stuck recoveries', () => {
+      const result = calculateHealthScore(createHealthInputs({ stuckRecoveryCount: 0, maxStuckRecoveries: 5 }));
+      expect(result.components.stuckRecovery).toBe(100);
+    });
+
+    it('should return 0 when stuck recoveries reach max', () => {
+      const result = calculateHealthScore(createHealthInputs({ stuckRecoveryCount: 5, maxStuckRecoveries: 5 }));
+      expect(result.components.stuckRecovery).toBe(0);
+    });
+
+    it('should return proportional score for partial recoveries', () => {
+      const result = calculateHealthScore(createHealthInputs({ stuckRecoveryCount: 2, maxStuckRecoveries: 5 }));
+      // 100 - (2/5) * 100 = 60
+      expect(result.components.stuckRecovery).toBe(60);
+    });
+
+    it('should return 0 when stuck recoveries exceed max', () => {
+      const result = calculateHealthScore(createHealthInputs({ stuckRecoveryCount: 10, maxStuckRecoveries: 5 }));
+      expect(result.components.stuckRecovery).toBe(0);
+    });
+  });
+
+  describe('recommendations', () => {
+    it('should recommend no action for healthy system', () => {
+      const result = calculateHealthScore(createHealthInputs());
+      expect(result.recommendations).toEqual(['System is healthy. No action needed.']);
+    });
+
+    it('should recommend checking cycle success when low', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 5,
+            stuckRecoveryCycles: 3,
+            blockedCycles: 1,
+            errorCycles: 1,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 50,
+            lastUpdatedAt: Date.now(),
+          },
+        })
+      );
+      expect(result.recommendations).toContainEqual(expect.stringContaining('Cycle success rate is low'));
+    });
+
+    it('should recommend reviewing circuit breaker when open', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          circuitBreakerStatus: createCircuitBreakerStatus('OPEN'),
+        })
+      );
+      expect(result.recommendations).toContainEqual(expect.stringContaining('Circuit breaker is open'));
+    });
+
+    it('should recommend checking iteration when stalled', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          iterationStallMetrics: {
+            stallDurationMs: 400000,
+            warningThresholdMs: 300000,
+            criticalThresholdMs: 600000,
+          },
+        })
+      );
+      expect(result.recommendations).toContainEqual(expect.stringContaining('Iteration progress has stalled'));
+    });
+
+    it('should recommend checking AI checker when disabled', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aiCheckerState: { status: 'disabled', consecutiveErrors: 3 },
+        })
+      );
+      // aiChecker score = 30 (disabled), which is < 50 -> triggers recommendation
+      expect(result.recommendations).toContainEqual(expect.stringContaining('AI idle checker has errors'));
+    });
+
+    it('should recommend adjusting timeouts when stuck recoveries are high', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          stuckRecoveryCount: 4,
+          maxStuckRecoveries: 5,
+        })
+      );
+      expect(result.recommendations).toContainEqual(expect.stringContaining('Multiple stuck-state recoveries'));
+    });
+
+    it('should include multiple recommendations when multiple components are degraded', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 3,
+            stuckRecoveryCycles: 3,
+            blockedCycles: 2,
+            errorCycles: 2,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 30,
+            lastUpdatedAt: Date.now(),
+          },
+          circuitBreakerStatus: createCircuitBreakerStatus('OPEN'),
+          stuckRecoveryCount: 4,
+          maxStuckRecoveries: 5,
+        })
+      );
+      expect(result.recommendations.length).toBeGreaterThanOrEqual(3);
+    });
+  });
+
+  describe('summary', () => {
+    it('should include score in summary', () => {
+      const result = calculateHealthScore(createHealthInputs());
+      expect(result.summary).toContain('100/100');
+    });
+
+    it('should describe excellent status', () => {
+      const result = calculateHealthScore(createHealthInputs());
+      expect(result.summary).toContain('excellently');
+    });
+
+    it('should describe critical status with lowest component', () => {
+      const result = calculateHealthScore(
+        createHealthInputs({
+          aggregateMetrics: {
+            totalCycles: 10,
+            successfulCycles: 0,
+            stuckRecoveryCycles: 5,
+            blockedCycles: 3,
+            errorCycles: 2,
+            avgCycleDurationMs: 5000,
+            avgIdleDetectionMs: 1000,
+            p90CycleDurationMs: 8000,
+            successRate: 0,
+            lastUpdatedAt: Date.now(),
+          },
+          circuitBreakerStatus: createCircuitBreakerStatus('OPEN'),
+        })
+      );
+      expect(result.summary).toContain('critical');
+    });
+
+    it('should include calculatedAt timestamp', () => {
+      const before = Date.now();
+      const result = calculateHealthScore(createHealthInputs());
+      const after = Date.now();
+
+      expect(result.calculatedAt).toBeGreaterThanOrEqual(before);
+      expect(result.calculatedAt).toBeLessThanOrEqual(after);
+    });
+  });
+});
+
+describe('shouldSkipClear', () => {
+  it('should not skip when token count is 0 (unknown)', () => {
+    expect(shouldSkipClear(0, 50, 200000)).toBe(false);
+  });
+
+  it('should skip when usage is below threshold', () => {
+    // 10000 / 200000 = 5% < 50%
+    expect(shouldSkipClear(10000, 50, 200000)).toBe(true);
+  });
+
+  it('should not skip when usage is above threshold', () => {
+    // 150000 / 200000 = 75% > 50%
+    expect(shouldSkipClear(150000, 50, 200000)).toBe(false);
+  });
+
+  it('should not skip when usage equals threshold', () => {
+    // 100000 / 200000 = 50% == 50% -> not less than, so false
+    expect(shouldSkipClear(100000, 50, 200000)).toBe(false);
+  });
+
+  it('should handle edge case of very small threshold', () => {
+    // 1000 / 200000 = 0.5% < 1%
+    expect(shouldSkipClear(1000, 1, 200000)).toBe(true);
+  });
+
+  it('should handle 100% threshold (always skip)', () => {
+    // 190000 / 200000 = 95% < 100%
+    expect(shouldSkipClear(190000, 100, 200000)).toBe(true);
+  });
+
+  it('should handle 0% threshold (never skip except when unknown)', () => {
+    // Any positive count / total > 0% so not < 0%
+    expect(shouldSkipClear(1, 0, 200000)).toBe(false);
+  });
+});
@@ -0,0 +1,332 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RespawnCycleMetricsTracker } from '../src/respawn-metrics.js';
+import type { CycleOutcome } from '../src/types/index.js';
+
+describe('RespawnCycleMetricsTracker', () => {
+  let tracker: RespawnCycleMetricsTracker;
+
+  beforeEach(() => {
+    tracker = new RespawnCycleMetricsTracker();
+  });
+
+  describe('initial state', () => {
+    it('should have no current cycle', () => {
+      expect(tracker.getCurrentCycle()).toBeNull();
+    });
+
+    it('should have empty recent metrics', () => {
+      expect(tracker.getRecent()).toEqual([]);
+    });
+
+    it('should have zeroed aggregate metrics', () => {
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(0);
+      expect(agg.successfulCycles).toBe(0);
+      expect(agg.stuckRecoveryCycles).toBe(0);
+      expect(agg.blockedCycles).toBe(0);
+      expect(agg.errorCycles).toBe(0);
+      expect(agg.avgCycleDurationMs).toBe(0);
+      expect(agg.avgIdleDetectionMs).toBe(0);
+      expect(agg.p90CycleDurationMs).toBe(0);
+      expect(agg.successRate).toBe(100);
+    });
+  });
+
+  describe('startCycle', () => {
+    it('should create a current cycle with correct fields', () => {
+      const idleDetectionStartTime = Date.now() - 1500;
+      tracker.startCycle('session-1', 1, 'completion_message', idleDetectionStartTime, 50000, 10000);
+
+      const cycle = tracker.getCurrentCycle();
+      expect(cycle).not.toBeNull();
+      expect(cycle!.cycleId).toBe('session-1:1');
+      expect(cycle!.sessionId).toBe('session-1');
+      expect(cycle!.cycleNumber).toBe(1);
+      expect(cycle!.idleReason).toBe('completion_message');
+      expect(cycle!.stepsCompleted).toEqual([]);
+      expect(cycle!.clearSkipped).toBe(false);
+      expect(cycle!.tokenCountAtStart).toBe(50000);
+      expect(cycle!.completionConfirmMsUsed).toBe(10000);
+      // idleDetectionMs should be approximately 1500 (within margin)
+      expect(cycle!.idleDetectionMs).toBeGreaterThanOrEqual(1400);
+      expect(cycle!.idleDetectionMs).toBeLessThanOrEqual(2000);
+    });
+
+    it('should overwrite a previous current cycle', () => {
+      tracker.startCycle('session-1', 1, 'reason1', Date.now(), 10000, 5000);
+      tracker.startCycle('session-1', 2, 'reason2', Date.now(), 20000, 6000);
+
+      const cycle = tracker.getCurrentCycle();
+      expect(cycle!.cycleNumber).toBe(2);
+      expect(cycle!.idleReason).toBe('reason2');
+    });
+  });
+
+  describe('recordStep', () => {
+    it('should add steps to current cycle', () => {
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+
+      tracker.recordStep('update');
+      tracker.recordStep('clear');
+      tracker.recordStep('init');
+
+      const cycle = tracker.getCurrentCycle();
+      expect(cycle!.stepsCompleted).toEqual(['update', 'clear', 'init']);
+    });
+
+    it('should be a no-op when no cycle is in progress', () => {
+      // Should not throw
+      tracker.recordStep('update');
+      expect(tracker.getCurrentCycle()).toBeNull();
+    });
+  });
+
+  describe('markClearSkipped', () => {
+    it('should set clearSkipped flag on current cycle', () => {
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+
+      tracker.markClearSkipped();
+
+      const cycle = tracker.getCurrentCycle();
+      expect(cycle!.clearSkipped).toBe(true);
+    });
+
+    it('should be a no-op when no cycle is in progress', () => {
+      // Should not throw
+      tracker.markClearSkipped();
+      expect(tracker.getCurrentCycle()).toBeNull();
+    });
+  });
+
+  describe('completeCycle', () => {
+    it('should return null when no cycle is in progress', () => {
+      const result = tracker.completeCycle('success', 60000);
+      expect(result).toBeNull();
+    });
+
+    it('should return completed metrics with correct fields', () => {
+      tracker.startCycle('session-1', 1, 'completion_message', Date.now(), 50000, 10000);
+      tracker.recordStep('update');
+      tracker.recordStep('clear');
+
+      const result = tracker.completeCycle('success', 60000);
+
+      expect(result).not.toBeNull();
+      expect(result!.outcome).toBe('success');
+      expect(result!.tokenCountAtEnd).toBe(60000);
+      expect(result!.completedAt).toBeGreaterThan(0);
+      expect(result!.durationMs).toBeGreaterThanOrEqual(0);
+      expect(result!.stepsCompleted).toEqual(['update', 'clear']);
+    });
+
+    it('should include error message for error outcome', () => {
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+
+      const result = tracker.completeCycle('error', 0, 'Something went wrong');
+
+      expect(result!.outcome).toBe('error');
+      expect(result!.errorMessage).toBe('Something went wrong');
+    });
+
+    it('should clear current cycle after completion', () => {
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+      tracker.completeCycle('success', 0);
+
+      expect(tracker.getCurrentCycle()).toBeNull();
+    });
+
+    it('should add to recent metrics', () => {
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+      tracker.completeCycle('success', 0);
+
+      const recent = tracker.getRecent();
+      expect(recent.length).toBe(1);
+      expect(recent[0].outcome).toBe('success');
+    });
+  });
+
+  describe('aggregate metrics updates', () => {
+    function completeOneCycle(outcome: CycleOutcome): void {
+      tracker.startCycle('session-1', tracker.getAggregate().totalCycles + 1, 'test', Date.now(), 0, 10000);
+      tracker.completeCycle(outcome, 0);
+    }
+
+    it('should count successful cycles', () => {
+      completeOneCycle('success');
+      completeOneCycle('success');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(2);
+      expect(agg.successfulCycles).toBe(2);
+      expect(agg.successRate).toBe(100);
+    });
+
+    it('should count stuck_recovery cycles', () => {
+      completeOneCycle('stuck_recovery');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(1);
+      expect(agg.stuckRecoveryCycles).toBe(1);
+      expect(agg.successRate).toBe(0);
+    });
+
+    it('should count blocked cycles', () => {
+      completeOneCycle('blocked');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(1);
+      expect(agg.blockedCycles).toBe(1);
+    });
+
+    it('should count error cycles', () => {
+      completeOneCycle('error');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(1);
+      expect(agg.errorCycles).toBe(1);
+    });
+
+    it('should count cancelled cycles in total but no specific category', () => {
+      completeOneCycle('cancelled');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(1);
+      expect(agg.successfulCycles).toBe(0);
+      expect(agg.stuckRecoveryCycles).toBe(0);
+      expect(agg.blockedCycles).toBe(0);
+      expect(agg.errorCycles).toBe(0);
+    });
+
+    it('should calculate success rate correctly', () => {
+      completeOneCycle('success');
+      completeOneCycle('success');
+      completeOneCycle('error');
+      completeOneCycle('success');
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(4);
+      expect(agg.successfulCycles).toBe(3);
+      expect(agg.successRate).toBe(75);
+    });
+
+    it('should update lastUpdatedAt timestamp', () => {
+      const before = Date.now();
+      completeOneCycle('success');
+      const after = Date.now();
+
+      const agg = tracker.getAggregate();
+      expect(agg.lastUpdatedAt).toBeGreaterThanOrEqual(before);
+      expect(agg.lastUpdatedAt).toBeLessThanOrEqual(after);
+    });
+  });
+
+  describe('getRecent', () => {
+    it('should return newest first', () => {
+      for (let i = 1; i <= 5; i++) {
+        tracker.startCycle('session-1', i, `reason-${i}`, Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      const recent = tracker.getRecent();
+      expect(recent.length).toBe(5);
+      expect(recent[0].cycleNumber).toBe(5);
+      expect(recent[4].cycleNumber).toBe(1);
+    });
+
+    it('should respect limit parameter', () => {
+      for (let i = 1; i <= 10; i++) {
+        tracker.startCycle('session-1', i, 'test', Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      const recent = tracker.getRecent(3);
+      expect(recent.length).toBe(3);
+      expect(recent[0].cycleNumber).toBe(10);
+    });
+
+    it('should default to 20 items', () => {
+      for (let i = 1; i <= 25; i++) {
+        tracker.startCycle('session-1', i, 'test', Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      const recent = tracker.getRecent();
+      expect(recent.length).toBe(20);
+    });
+  });
+
+  describe('memory limit (MAX_CYCLE_METRICS_IN_MEMORY)', () => {
+    it('should trim recent metrics beyond 100 entries', () => {
+      for (let i = 1; i <= 105; i++) {
+        tracker.startCycle('session-1', i, 'test', Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      // Internal storage should be capped at 100
+      // We can verify via getRecent with a high limit
+      const recent = tracker.getRecent(200);
+      expect(recent.length).toBe(100);
+      // The earliest should be cycle 6 (first 5 were shifted off)
+      expect(recent[recent.length - 1].cycleNumber).toBe(6);
+    });
+  });
+
+  describe('getAggregate', () => {
+    it('should return a copy, not a reference', () => {
+      const agg1 = tracker.getAggregate();
+      const agg2 = tracker.getAggregate();
+
+      expect(agg1).not.toBe(agg2);
+      expect(agg1).toEqual(agg2);
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all state', () => {
+      // Add some cycles
+      for (let i = 1; i <= 5; i++) {
+        tracker.startCycle('session-1', i, 'test', Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      // Start another cycle
+      tracker.startCycle('session-1', 6, 'test', Date.now(), 0, 10000);
+
+      tracker.reset();
+
+      expect(tracker.getCurrentCycle()).toBeNull();
+      expect(tracker.getRecent()).toEqual([]);
+
+      const agg = tracker.getAggregate();
+      expect(agg.totalCycles).toBe(0);
+      expect(agg.successfulCycles).toBe(0);
+      expect(agg.successRate).toBe(100);
+    });
+  });
+
+  describe('aggregate averages and P90', () => {
+    it('should calculate average cycle duration across recent cycles', () => {
+      // We can't directly control durationMs since it's computed from Date.now(),
+      // but we can verify the aggregate fields are populated after completing cycles
+      tracker.startCycle('session-1', 1, 'test', Date.now(), 0, 10000);
+      tracker.completeCycle('success', 0);
+
+      const agg = tracker.getAggregate();
+      // durationMs should be very small (within the same tick)
+      expect(agg.avgCycleDurationMs).toBeGreaterThanOrEqual(0);
+      expect(agg.p90CycleDurationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should calculate P90 from sorted durations', () => {
+      // Complete multiple cycles to populate P90
+      for (let i = 1; i <= 10; i++) {
+        tracker.startCycle('session-1', i, 'test', Date.now(), 0, 10000);
+        tracker.completeCycle('success', 0);
+      }
+
+      const agg = tracker.getAggregate();
+      // P90 should be >= avg (for uniform values, P90 ~= avg)
+      expect(agg.p90CycleDurationMs).toBeGreaterThanOrEqual(0);
+    });
+  });
+});
@@ -0,0 +1,255 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isCompletionMessage,
+  hasWorkingPattern,
+  extractTokenCount,
+  PROMPT_PATTERNS,
+  WORKING_PATTERNS,
+} from '../src/respawn-patterns.js';
+
+describe('isCompletionMessage', () => {
+  describe('valid completion messages', () => {
+    it('should match "Worked for 2m 46s"', () => {
+      expect(isCompletionMessage('Worked for 2m 46s')).toBe(true);
+    });
+
+    it('should match "Worked for 46s"', () => {
+      expect(isCompletionMessage('Worked for 46s')).toBe(true);
+    });
+
+    it('should match "Worked for 1h 2m 3s"', () => {
+      expect(isCompletionMessage('Worked for 1h 2m 3s')).toBe(true);
+    });
+
+    it('should match "Worked for 5m"', () => {
+      expect(isCompletionMessage('Worked for 5m')).toBe(true);
+    });
+
+    it('should match "Worked for 2h"', () => {
+      expect(isCompletionMessage('Worked for 2h')).toBe(true);
+    });
+
+    it('should match case-insensitively', () => {
+      expect(isCompletionMessage('worked for 10s')).toBe(true);
+      expect(isCompletionMessage('WORKED FOR 10s')).toBe(true);
+    });
+
+    it('should match when embedded in larger string', () => {
+      expect(isCompletionMessage('Some prefix text Worked for 5m 30s and more text')).toBe(true);
+    });
+
+    it('should not match when ANSI escape codes break the word boundary', () => {
+      // The regex uses \b word boundary, so ANSI codes right before "Worked"
+      // break the match. In practice, data is ANSI-stripped before reaching this function.
+      expect(isCompletionMessage('\x1b[32mWorked for 3m 15s\x1b[0m')).toBe(false);
+    });
+
+    it('should match ANSI-stripped output', () => {
+      // After stripping ANSI codes, the pattern works fine
+      expect(isCompletionMessage('Worked for 3m 15s')).toBe(true);
+    });
+  });
+
+  describe('invalid patterns (should not match)', () => {
+    it('should not match "wait for 5s"', () => {
+      expect(isCompletionMessage('wait for 5s')).toBe(false);
+    });
+
+    it('should not match "run for 2m"', () => {
+      expect(isCompletionMessage('run for 2m')).toBe(false);
+    });
+
+    it('should not match "for 3s the system..."', () => {
+      expect(isCompletionMessage('for 3s the system responded')).toBe(false);
+    });
+
+    it('should not match bare time durations', () => {
+      expect(isCompletionMessage('2m 46s')).toBe(false);
+    });
+
+    it('should not match empty string', () => {
+      expect(isCompletionMessage('')).toBe(false);
+    });
+
+    it('should not match "Worked" without time pattern', () => {
+      expect(isCompletionMessage('Worked on the task')).toBe(false);
+    });
+
+    it('should not match "Worked for" without time', () => {
+      expect(isCompletionMessage('Worked for a long time')).toBe(false);
+    });
+  });
+});
+
+describe('hasWorkingPattern', () => {
+  describe('text working indicators', () => {
+    it('should detect "Thinking" in window', () => {
+      expect(hasWorkingPattern('Claude is Thinking about your request')).toBe(true);
+    });
+
+    it('should detect "Writing" in window', () => {
+      expect(hasWorkingPattern('Writing to file src/main.ts')).toBe(true);
+    });
+
+    it('should detect "Reading" in window', () => {
+      expect(hasWorkingPattern('Reading file contents')).toBe(true);
+    });
+
+    it('should detect "Running" in window', () => {
+      expect(hasWorkingPattern('Running npm install')).toBe(true);
+    });
+
+    it('should detect "Searching" in window', () => {
+      expect(hasWorkingPattern('Searching for patterns')).toBe(true);
+    });
+
+    it('should detect "Editing" in window', () => {
+      expect(hasWorkingPattern('Editing src/utils.ts')).toBe(true);
+    });
+
+    it('should detect all defined text patterns', () => {
+      const textPatterns = WORKING_PATTERNS.filter((p) => p.length > 2);
+      for (const pattern of textPatterns) {
+        expect(hasWorkingPattern(`Some text with ${pattern} in it`)).toBe(true);
+      }
+    });
+  });
+
+  describe('spinner characters', () => {
+    it('should detect braille spinner characters', () => {
+      expect(hasWorkingPattern('Loading... \u280B')).toBe(true);
+      expect(hasWorkingPattern('\u2839 processing')).toBe(true);
+    });
+
+    it('should detect circle spinner characters', () => {
+      expect(hasWorkingPattern('\u25D0 working')).toBe(true);
+      expect(hasWorkingPattern('status: \u25D3')).toBe(true);
+    });
+
+    it('should detect braille block spinners', () => {
+      expect(hasWorkingPattern('\u28FE loading')).toBe(true); // ⣾
+      expect(hasWorkingPattern('\u28FD processing')).toBe(true); // ⣽
+    });
+  });
+
+  describe('negative cases', () => {
+    it('should return false for empty string', () => {
+      expect(hasWorkingPattern('')).toBe(false);
+    });
+
+    it('should return false for prompt characters only', () => {
+      expect(hasWorkingPattern('\u276F ')).toBe(false);
+    });
+
+    it('should return false for regular output text', () => {
+      expect(hasWorkingPattern('Here is the result of the computation')).toBe(false);
+    });
+
+    it('should return false for completion messages', () => {
+      expect(hasWorkingPattern('Worked for 2m 46s')).toBe(false);
+    });
+  });
+});
+
+describe('extractTokenCount', () => {
+  describe('basic token patterns', () => {
+    it('should extract plain number tokens', () => {
+      expect(extractTokenCount('500 tokens')).toBe(500);
+    });
+
+    it('should extract decimal number tokens', () => {
+      expect(extractTokenCount('123.4 tokens')).toBe(123);
+    });
+
+    it('should extract k suffix (thousands)', () => {
+      expect(extractTokenCount('123.4k tokens')).toBe(123400);
+    });
+
+    it('should extract K suffix (uppercase)', () => {
+      expect(extractTokenCount('50K tokens')).toBe(50000);
+    });
+
+    it('should extract m suffix (millions)', () => {
+      expect(extractTokenCount('1.5m tokens')).toBe(1500000);
+    });
+
+    it('should extract M suffix (uppercase)', () => {
+      expect(extractTokenCount('2M tokens')).toBe(2000000);
+    });
+
+    it('should handle whitespace between number and suffix', () => {
+      expect(extractTokenCount('123.4 k tokens')).toBe(123400);
+    });
+  });
+
+  describe('embedded in text', () => {
+    it('should extract from terminal output', () => {
+      expect(extractTokenCount('Current usage: 45.2k tokens remaining')).toBe(45200);
+    });
+
+    it('should extract from completion message', () => {
+      expect(extractTokenCount('Worked for 2m 46s | 150.3k tokens used')).toBe(150300);
+    });
+  });
+
+  describe('negative cases', () => {
+    it('should return null for empty string', () => {
+      expect(extractTokenCount('')).toBeNull();
+    });
+
+    it('should return null for string without token pattern', () => {
+      expect(extractTokenCount('Hello world')).toBeNull();
+    });
+
+    it('should return null for "tokens" without a number', () => {
+      expect(extractTokenCount('many tokens')).toBeNull();
+    });
+  });
+
+  describe('rounding', () => {
+    it('should round to nearest integer', () => {
+      // 1.7k = 1700 (exact, no rounding needed)
+      expect(extractTokenCount('1.7k tokens')).toBe(1700);
+    });
+
+    it('should round fractional results', () => {
+      // 1.23456k = 1234.56 -> rounds to 1235
+      expect(extractTokenCount('1.23456k tokens')).toBe(1235);
+    });
+  });
+});
+
+describe('PROMPT_PATTERNS', () => {
+  it('should contain standard prompt characters', () => {
+    expect(PROMPT_PATTERNS).toContain('\u276F'); // Unicode right-pointing angle
+    expect(PROMPT_PATTERNS).toContain('\u23F5'); // Play button variant
+  });
+
+  it('should be a non-empty array', () => {
+    expect(PROMPT_PATTERNS.length).toBeGreaterThan(0);
+  });
+});
+
+describe('WORKING_PATTERNS', () => {
+  it('should be a non-empty array', () => {
+    expect(WORKING_PATTERNS.length).toBeGreaterThan(0);
+  });
+
+  it('should contain common Claude activity indicators', () => {
+    expect(WORKING_PATTERNS).toContain('Thinking');
+    expect(WORKING_PATTERNS).toContain('Writing');
+    expect(WORKING_PATTERNS).toContain('Reading');
+    expect(WORKING_PATTERNS).toContain('Running');
+  });
+
+  it('should contain spinner characters', () => {
+    expect(WORKING_PATTERNS).toContain('\u280B');
+    expect(WORKING_PATTERNS).toContain('\u2819');
+  });
+
+  it('should not contain completion indicators like stars', () => {
+    // Per source comment: "Note: \u273B and \u273D removed - they appear in completion messages too."
+    expect(WORKING_PATTERNS).not.toContain('\u273B');
+    expect(WORKING_PATTERNS).not.toContain('\u273D');
+  });
+});
@@ -4,20 +4,119 @@
 * Uses app.inject() — no real HTTP ports needed.
 * Port: N/A (app.inject doesn't open ports)
 *
- * Note: Some system routes access singleton modules (subagentWatcher, imageWatcher)
- * directly. Those routes are tested lightly here since we can't easily mock singletons
- * without vi.mock(). Focus is on routes that use the port context.
+ * Mocks: fs (promises + sync), subagentWatcher, imageWatcher,
+ * session-lifecycle-log, and opencode-cli-resolver singletons.
 */

-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
 import { registerSystemRoutes } from '../../src/web/routes/system-routes.js';

+// ── Mocks ──────────────────────────────────────────────────────────
+
+vi.mock('node:fs/promises', () => ({
+  default: {
+    readFile: vi.fn(async () => '{}'),
+    writeFile: vi.fn(async () => undefined),
+  },
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    existsSync: vi.fn(() => true),
+    mkdirSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+  };
+});
+
+vi.mock('../../src/subagent-watcher.js', () => ({
+  subagentWatcher: {
+    getSubagents: vi.fn(() => []),
+    getRecentSubagents: vi.fn(() => []),
+    getSubagentsForSession: vi.fn(() => []),
+    getSubagent: vi.fn(() => null),
+    getTranscript: vi.fn(async () => []),
+    formatTranscript: vi.fn(() => ''),
+    killSubagent: vi.fn(async () => false),
+    cleanupNow: vi.fn(() => 0),
+    clearAll: vi.fn(() => 0),
+    getStats: vi.fn(() => ({
+      totalAgents: 0,
+      activeAgents: 0,
+      fileDebouncerCount: 0,
+      dirWatcherCount: 0,
+      idleTimerCount: 0,
+    })),
+    isRunning: vi.fn(() => true),
+    start: vi.fn(),
+    stop: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/image-watcher.js', () => ({
+  imageWatcher: {
+    isRunning: vi.fn(() => false),
+    start: vi.fn(),
+    stop: vi.fn(),
+    watchSession: vi.fn(),
+  },
+}));
+
+vi.mock('../../src/session-lifecycle-log.js', () => ({
+  getLifecycleLog: vi.fn(() => ({
+    log: vi.fn(),
+    query: vi.fn(async () => []),
+  })),
+}));
+
+vi.mock('../../src/utils/opencode-cli-resolver.js', () => ({
+  isOpenCodeAvailable: vi.fn(() => false),
+  resolveOpenCodeDir: vi.fn(() => null),
+}));
+
+import fs from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { subagentWatcher } from '../../src/subagent-watcher.js';
+import { getLifecycleLog } from '../../src/session-lifecycle-log.js';
+import { isOpenCodeAvailable, resolveOpenCodeDir } from '../../src/utils/opencode-cli-resolver.js';
+
+const mockedReadFile = vi.mocked(fs.readFile);
+const mockedWriteFile = vi.mocked(fs.writeFile);
+const mockedExistsSync = vi.mocked(existsSync);
+const mockedReaddirSync = vi.mocked(readdirSync);
+const mockedSubagentWatcher = vi.mocked(subagentWatcher);
+const mockedGetLifecycleLog = vi.mocked(getLifecycleLog);
+const mockedIsOpenCodeAvailable = vi.mocked(isOpenCodeAvailable);
+const mockedResolveOpenCodeDir = vi.mocked(resolveOpenCodeDir);
+
 describe('system-routes', () => {
  let harness: RouteTestHarness;

  beforeEach(async () => {
    harness = await createRouteTestHarness(registerSystemRoutes);
+    vi.clearAllMocks();
+
+    // Re-apply defaults after clearAllMocks
+    mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    mockedWriteFile.mockResolvedValue(undefined);
+    mockedExistsSync.mockReturnValue(true);
+    mockedReaddirSync.mockReturnValue([]);
+    mockedSubagentWatcher.getSubagents.mockReturnValue([]);
+    mockedSubagentWatcher.getStats.mockReturnValue({
+      totalAgents: 0,
+      activeAgents: 0,
+      fileDebouncerCount: 0,
+      dirWatcherCount: 0,
+      idleTimerCount: 0,
+    } as never);
+    mockedGetLifecycleLog.mockReturnValue({
+      log: vi.fn(),
+      query: vi.fn(async () => []),
+    } as never);
+    mockedIsOpenCodeAvailable.mockReturnValue(false);
+    mockedResolveOpenCodeDir.mockReturnValue(null);
  });

  afterEach(async () => {
@@ -147,6 +246,13 @@ describe('system-routes', () => {
      expect(body.success).toBe(true);
      expect(body.data).toBeDefined();
    });
+
+    it('filters by minutes when query param provided', async () => {
+      mockedSubagentWatcher.getRecentSubagents.mockReturnValue([]);
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagents?minutes=30' });
+      expect(res.statusCode).toBe(200);
+      expect(mockedSubagentWatcher.getRecentSubagents).toHaveBeenCalledWith(30);
+    });
  });

  // ========== POST /api/auth/revoke ==========
@@ -162,5 +268,681 @@ describe('system-routes', () => {
      const body = JSON.parse(res.body);
      expect(body.success).toBe(true);
    });
+
+    it('revokes a specific session token', async () => {
+      const authSessions = new Map();
+      authSessions.set('tok-123', { ip: '1.2.3.4', ua: 'test', createdAt: Date.now(), method: 'basic' });
+      harness.ctx.authSessions = authSessions;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/auth/revoke',
+        payload: { sessionToken: 'tok-123' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+      expect(authSessions.has('tok-123')).toBe(false);
+    });
+
+    it('clears all sessions when no token specified', async () => {
+      const authSessions = new Map();
+      authSessions.set('a', { ip: '1', ua: '', createdAt: 0, method: 'basic' });
+      authSessions.set('b', { ip: '2', ua: '', createdAt: 0, method: 'qr' });
+      harness.ctx.authSessions = authSessions;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/auth/revoke',
+        payload: {},
+      });
+      expect(res.statusCode).toBe(200);
+      expect(authSessions.size).toBe(0);
+    });
+  });
+
+  // ========== GET /api/settings ==========
+
+  describe('GET /api/settings', () => {
+    it('returns empty object when settings file does not exist', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/settings' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual({});
+    });
+
+    it('returns parsed settings when file exists', async () => {
+      const settings = { subagentTrackingEnabled: true, showSystemStats: false };
+      mockedReadFile.mockResolvedValue(JSON.stringify(settings) as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/settings' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual(settings);
+    });
+  });
+
+  // ========== PUT /api/settings ==========
+
+  describe('PUT /api/settings', () => {
+    it('saves valid settings', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: { showSystemStats: true, subagentTrackingEnabled: false },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(mockedWriteFile).toHaveBeenCalled();
+    });
+
+    it('merges with existing settings', async () => {
+      mockedReadFile.mockResolvedValue(JSON.stringify({ showCost: true }) as never);
+
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: { showTokenCount: false },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+
+      // Verify writeFile was called with merged content
+      const writtenContent = JSON.parse(mockedWriteFile.mock.calls[0][1] as string);
+      expect(writtenContent.showCost).toBe(true);
+      expect(writtenContent.showTokenCount).toBe(false);
+    });
+
+    it('rejects unknown settings fields (strict schema)', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: { unknownField: 'bad' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+
+    it('rejects non-object body', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: 'not-an-object',
+        headers: { 'content-type': 'application/json' },
+      });
+      // Fastify will reject non-object JSON before it reaches the handler
+      expect(res.statusCode).not.toBe(200);
+    });
+  });
+
+  // ========== GET /api/subagent-window-states ==========
+
+  describe('GET /api/subagent-window-states', () => {
+    it('returns default when file does not exist', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagent-window-states' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual({ minimized: {}, open: [] });
+    });
+
+    it('returns persisted window states', async () => {
+      const states = { minimized: { 'agent-1': true }, open: ['agent-2'] };
+      mockedReadFile.mockResolvedValue(JSON.stringify(states) as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagent-window-states' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual(states);
+    });
+  });
+
+  // ========== PUT /api/subagent-window-states ==========
+
+  describe('PUT /api/subagent-window-states', () => {
+    it('saves valid window states', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-window-states',
+        payload: { minimized: { 'agent-1': true }, open: ['agent-2'] },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+      expect(mockedWriteFile).toHaveBeenCalled();
+    });
+
+    it('accepts empty state', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-window-states',
+        payload: { minimized: {}, open: [] },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+    });
+
+    it('rejects invalid minimized values', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-window-states',
+        payload: { minimized: { 'agent-1': 'not-a-boolean' } },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+  });
+
+  // ========== GET /api/subagent-parents ==========
+
+  describe('GET /api/subagent-parents', () => {
+    it('returns empty object when file does not exist', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagent-parents' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual({});
+    });
+
+    it('returns persisted parent map', async () => {
+      const parents = { 'agent-1': 'session-abc', 'agent-2': 'session-xyz' };
+      mockedReadFile.mockResolvedValue(JSON.stringify(parents) as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagent-parents' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual(parents);
+    });
+  });
+
+  // ========== PUT /api/subagent-parents ==========
+
+  describe('PUT /api/subagent-parents', () => {
+    it('saves valid parent map', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-parents',
+        payload: { 'agent-1': 'session-abc' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+      expect(mockedWriteFile).toHaveBeenCalled();
+    });
+
+    it('accepts empty parent map', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-parents',
+        payload: {},
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+    });
+
+    it('rejects non-string values in parent map', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/subagent-parents',
+        payload: { 'agent-1': 123 },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+  });
+
+  // ========== GET /api/screenshots ==========
+
+  describe('GET /api/screenshots', () => {
+    it('returns empty list when directory does not exist', async () => {
+      mockedExistsSync.mockReturnValue(false);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/screenshots' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body)).toEqual({ files: [] });
+    });
+
+    it('returns image files sorted in reverse order', async () => {
+      mockedExistsSync.mockReturnValue(true);
+      mockedReaddirSync.mockReturnValue([
+        'screenshot_2026-01-01_00-00-00.png',
+        'screenshot_2026-01-02_00-00-00.png',
+        'not-an-image.txt',
+        'screenshot_2026-01-03_00-00-00.jpg',
+      ] as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/screenshots' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.files).toHaveLength(3); // excludes .txt
+      // Sorted reverse: 03, 02, 01
+      expect(body.files[0].name).toBe('screenshot_2026-01-03_00-00-00.jpg');
+      expect(body.files[1].name).toBe('screenshot_2026-01-02_00-00-00.png');
+      expect(body.files[2].name).toBe('screenshot_2026-01-01_00-00-00.png');
+    });
+  });
+
+  // ========== GET /api/screenshots/:name ==========
+
+  describe('GET /api/screenshots/:name', () => {
+    it('rejects path traversal attempts', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/screenshots/..%2F..%2Fetc%2Fpasswd',
+      });
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('returns 404 when screenshot does not exist', async () => {
+      mockedExistsSync.mockReturnValue(false);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/screenshots/nonexistent.png',
+      });
+      expect(res.statusCode).toBe(404);
+    });
+
+    it('serves existing screenshot with correct content type', async () => {
+      mockedExistsSync.mockReturnValue(true);
+      mockedReadFile.mockResolvedValue(Buffer.from('fake-png-data') as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/screenshots/test-image.png',
+      });
+      expect(res.statusCode).toBe(200);
+      expect(res.headers['content-type']).toBe('image/png');
+    });
+
+    it('serves jpeg with correct content type', async () => {
+      mockedExistsSync.mockReturnValue(true);
+      mockedReadFile.mockResolvedValue(Buffer.from('fake-jpg-data') as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/screenshots/photo.jpg',
+      });
+      expect(res.statusCode).toBe(200);
+      expect(res.headers['content-type']).toBe('image/jpeg');
+    });
+  });
+
+  // ========== POST /api/screenshots ==========
+
+  describe('POST /api/screenshots', () => {
+    it('rejects non-multipart content type', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/screenshots',
+        payload: { file: 'data' },
+        headers: { 'content-type': 'application/json' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.error).toContain('multipart');
+    });
+  });
+
+  // ========== GET /api/session-lifecycle ==========
+
+  describe('GET /api/session-lifecycle', () => {
+    it('returns lifecycle entries', async () => {
+      const mockEntries = [{ event: 'session_created', sessionId: 'test-1', timestamp: Date.now() }];
+      mockedGetLifecycleLog.mockReturnValue({
+        log: vi.fn(),
+        query: vi.fn(async () => mockEntries),
+      } as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/session-lifecycle' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.entries).toEqual(mockEntries);
+    });
+
+    it('passes filter query params to lifecycle log', async () => {
+      const queryFn = vi.fn(async () => []);
+      mockedGetLifecycleLog.mockReturnValue({
+        log: vi.fn(),
+        query: queryFn,
+      } as never);
+
+      await harness.app.inject({
+        method: 'GET',
+        url: '/api/session-lifecycle?sessionId=s1&event=session_created&since=1000&limit=50',
+      });
+
+      expect(queryFn).toHaveBeenCalledWith({
+        sessionId: 's1',
+        event: 'session_created',
+        since: 1000,
+        limit: 50,
+      });
+    });
+
+    it('caps limit at 1000', async () => {
+      const queryFn = vi.fn(async () => []);
+      mockedGetLifecycleLog.mockReturnValue({
+        log: vi.fn(),
+        query: queryFn,
+      } as never);
+
+      await harness.app.inject({
+        method: 'GET',
+        url: '/api/session-lifecycle?limit=5000',
+      });
+
+      expect(queryFn).toHaveBeenCalledWith(expect.objectContaining({ limit: 1000 }));
+    });
+
+    it('defaults limit to 200 when not specified', async () => {
+      const queryFn = vi.fn(async () => []);
+      mockedGetLifecycleLog.mockReturnValue({
+        log: vi.fn(),
+        query: queryFn,
+      } as never);
+
+      await harness.app.inject({ method: 'GET', url: '/api/session-lifecycle' });
+
+      expect(queryFn).toHaveBeenCalledWith(expect.objectContaining({ limit: 200 }));
+    });
+  });
+
+  // ========== GET /api/opencode/status ==========
+
+  describe('GET /api/opencode/status', () => {
+    it('returns unavailable when opencode is not installed', async () => {
+      mockedIsOpenCodeAvailable.mockReturnValue(false);
+      mockedResolveOpenCodeDir.mockReturnValue(null);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/opencode/status' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.available).toBe(false);
+      expect(body.path).toBeNull();
+    });
+
+    it('returns available with path when opencode is installed', async () => {
+      mockedIsOpenCodeAvailable.mockReturnValue(true);
+      mockedResolveOpenCodeDir.mockReturnValue('/usr/local/bin');
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/opencode/status' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.available).toBe(true);
+      expect(body.path).toBe('/usr/local/bin');
+    });
+  });
+
+  // ========== GET /api/execution/model-config ==========
+
+  describe('GET /api/execution/model-config', () => {
+    it('returns empty data when settings file does not exist', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/execution/model-config' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toEqual({});
+    });
+
+    it('returns model config from settings', async () => {
+      const settings = { modelConfig: { model: 'claude-3', temperature: 0.7 } };
+      mockedReadFile.mockResolvedValue(JSON.stringify(settings) as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/execution/model-config' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toEqual(settings.modelConfig);
+    });
+
+    it('returns empty data when settings has no modelConfig', async () => {
+      mockedReadFile.mockResolvedValue(JSON.stringify({ showCost: true }) as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/execution/model-config' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toEqual({});
+    });
+  });
+
+  // ========== PUT /api/execution/model-config ==========
+
+  describe('PUT /api/execution/model-config', () => {
+    it('saves valid model config', async () => {
+      mockedReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/execution/model-config',
+        payload: { model: 'claude-3', temperature: 0.5 },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+      expect(mockedWriteFile).toHaveBeenCalled();
+
+      // Verify the written content contains modelConfig
+      const writtenContent = JSON.parse(mockedWriteFile.mock.calls[0][1] as string);
+      expect(writtenContent.modelConfig).toEqual({ model: 'claude-3', temperature: 0.5 });
+    });
+
+    it('preserves existing settings when updating model config', async () => {
+      mockedReadFile.mockResolvedValue(JSON.stringify({ showCost: true, other: 'value' }) as never);
+
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/execution/model-config',
+        payload: { model: 'new-model' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+
+      const writtenContent = JSON.parse(mockedWriteFile.mock.calls[0][1] as string);
+      expect(writtenContent.showCost).toBe(true);
+      expect(writtenContent.other).toBe('value');
+      expect(writtenContent.modelConfig).toEqual({ model: 'new-model' });
+    });
+  });
+
+  // ========== GET /api/subagents/:agentId ==========
+
+  describe('GET /api/subagents/:agentId', () => {
+    it('returns 200 with error for unknown agent', async () => {
+      mockedSubagentWatcher.getSubagent.mockReturnValue(null);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagents/unknown-agent' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.error).toContain('not found');
+    });
+
+    it('returns agent info for known agent', async () => {
+      const agentInfo = { agentId: 'agent-1', status: 'active', pid: 1234 };
+      mockedSubagentWatcher.getSubagent.mockReturnValue(agentInfo as never);
+
+      const res = await harness.app.inject({ method: 'GET', url: '/api/subagents/agent-1' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toEqual(agentInfo);
+    });
+  });
+
+  // ========== GET /api/subagents/:agentId/transcript ==========
+
+  describe('GET /api/subagents/:agentId/transcript', () => {
+    it('returns raw transcript by default', async () => {
+      const transcript = [{ role: 'assistant', content: 'hello' }];
+      mockedSubagentWatcher.getTranscript.mockResolvedValue(transcript as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/subagents/agent-1/transcript',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toEqual(transcript);
+    });
+
+    it('returns formatted transcript when format=formatted', async () => {
+      const transcript = [{ role: 'assistant', content: 'hello' }];
+      mockedSubagentWatcher.getTranscript.mockResolvedValue(transcript as never);
+      mockedSubagentWatcher.formatTranscript.mockReturnValue('## Formatted\nhello');
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/subagents/agent-1/transcript?format=formatted',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.formatted).toBe('## Formatted\nhello');
+      expect(body.data.entryCount).toBe(1);
+    });
+
+    it('passes limit parameter', async () => {
+      mockedSubagentWatcher.getTranscript.mockResolvedValue([] as never);
+
+      await harness.app.inject({
+        method: 'GET',
+        url: '/api/subagents/agent-1/transcript?limit=10',
+      });
+      expect(mockedSubagentWatcher.getTranscript).toHaveBeenCalledWith('agent-1', 10);
+    });
+  });
+
+  // ========== DELETE /api/subagents/:agentId ==========
+
+  describe('DELETE /api/subagents/:agentId', () => {
+    it('returns error for unknown agent', async () => {
+      mockedSubagentWatcher.getSubagent.mockReturnValue(null);
+
+      const res = await harness.app.inject({ method: 'DELETE', url: '/api/subagents/unknown' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.error).toContain('not found');
+    });
+
+    it('kills a known agent successfully', async () => {
+      mockedSubagentWatcher.getSubagent.mockReturnValue({ agentId: 'agent-1' } as never);
+      mockedSubagentWatcher.killSubagent.mockResolvedValue(true);
+
+      const res = await harness.app.inject({ method: 'DELETE', url: '/api/subagents/agent-1' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.status).toBe('killed');
+    });
+
+    it('returns error when kill fails', async () => {
+      mockedSubagentWatcher.getSubagent.mockReturnValue({ agentId: 'agent-1' } as never);
+      mockedSubagentWatcher.killSubagent.mockResolvedValue(false);
+
+      const res = await harness.app.inject({ method: 'DELETE', url: '/api/subagents/agent-1' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+      expect(body.error).toContain('already completed');
+    });
+  });
+
+  // ========== POST /api/subagents/cleanup ==========
+
+  describe('POST /api/subagents/cleanup', () => {
+    it('triggers cleanup and returns count', async () => {
+      mockedSubagentWatcher.cleanupNow.mockReturnValue(3);
+      mockedSubagentWatcher.getSubagents.mockReturnValue([{ agentId: 'a' }, { agentId: 'b' }] as never);
+
+      const res = await harness.app.inject({ method: 'POST', url: '/api/subagents/cleanup' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.removed).toBe(3);
+      expect(body.data.remaining).toBe(2);
+    });
+  });
+
+  // ========== DELETE /api/subagents ==========
+
+  describe('DELETE /api/subagents', () => {
+    it('clears all subagents', async () => {
+      mockedSubagentWatcher.clearAll.mockReturnValue(5);
+
+      const res = await harness.app.inject({ method: 'DELETE', url: '/api/subagents' });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.cleared).toBe(5);
+    });
+  });
+
+  // ========== GET /api/sessions/:id/subagents ==========
+
+  describe('GET /api/sessions/:id/subagents', () => {
+    it('returns 404 for unknown session', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/sessions/nonexistent/subagents',
+      });
+      expect(res.statusCode).toBe(404);
+    });
+
+    it('returns subagents for valid session', async () => {
+      mockedSubagentWatcher.getSubagentsForSession.mockReturnValue([{ agentId: 'sub-1', status: 'active' }] as never);
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: `/api/sessions/${harness.ctx._sessionId}/subagents`,
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data).toHaveLength(1);
+    });
+  });
+
+  // ========== POST /api/tunnel/qr/regenerate ==========
+
+  describe('POST /api/tunnel/qr/regenerate', () => {
+    it('calls regenerateQrToken on tunnel manager', async () => {
+      // Set up a mock tunnel manager
+      harness.ctx.tunnelManager = {
+        regenerateQrToken: vi.fn(),
+        getStatus: vi.fn(() => ({ running: false })),
+        getUrl: vi.fn(() => null),
+        getQrSvg: vi.fn(),
+        consumeToken: vi.fn(),
+        isRunning: vi.fn(() => false),
+        start: vi.fn(),
+        stop: vi.fn(),
+      } as never;
+
+      // Re-create the harness since tunnelManager was null originally
+      await harness.app.close();
+      harness = await createRouteTestHarness(registerSystemRoutes);
+      harness.ctx.tunnelManager = {
+        regenerateQrToken: vi.fn(),
+        getStatus: vi.fn(() => ({ running: false })),
+        getUrl: vi.fn(() => null),
+        getQrSvg: vi.fn(),
+        consumeToken: vi.fn(),
+        isRunning: vi.fn(() => false),
+        start: vi.fn(),
+        stop: vi.fn(),
+      } as never;
+
+      const res = await harness.app.inject({ method: 'POST', url: '/api/tunnel/qr/regenerate' });
+      expect(res.statusCode).toBe(200);
+      expect(JSON.parse(res.body).success).toBe(true);
+    });
  });
 });
@@ -0,0 +1,445 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { WebServer } from '../src/web/server.js';
+
+const TEST_PORT = 3212;
+
+// Helper to parse SSE events from raw text
+function parseSSEEvents(text: string): Array<{ event: string; data: unknown }> {
+  const events: Array<{ event: string; data: unknown }> = [];
+  const lines = text.split('\n');
+  let currentEvent = '';
+  let currentData = '';
+
+  for (const line of lines) {
+    if (line.startsWith('event: ')) {
+      currentEvent = line.substring(7);
+    } else if (line.startsWith('data: ')) {
+      currentData = line.substring(6);
+    } else if (line === '') {
+      if (currentEvent && currentData) {
+        try {
+          events.push({ event: currentEvent, data: JSON.parse(currentData) });
+        } catch {
+          events.push({ event: currentEvent, data: currentData });
+        }
+      }
+      currentEvent = '';
+      currentData = '';
+    }
+  }
+
+  return events;
+}
+
+// Helper to collect SSE events for a given duration
+async function collectSSEEvents(
+  baseUrl: string,
+  queryParams: string,
+  durationMs: number
+): Promise<Array<{ event: string; data: unknown }>> {
+  const controller = new AbortController();
+  let receivedData = '';
+
+  const fetchPromise = fetch(`${baseUrl}/api/events${queryParams}`, {
+    signal: controller.signal,
+  }).then(async (response) => {
+    const reader = response.body?.getReader();
+    if (reader) {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          receivedData += new TextDecoder().decode(value);
+        }
+      } catch {
+        /* AbortError expected */
+      }
+    }
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, durationMs));
+  controller.abort();
+  try {
+    await fetchPromise;
+  } catch {
+    /* AbortError expected */
+  }
+
+  return parseSSEEvents(receivedData);
+}
+
+describe('SSE Subscription Filtering', () => {
+  let server: WebServer;
+  let baseUrl: string;
+
+  beforeAll(async () => {
+    server = new WebServer(TEST_PORT, false, true);
+    await server.start();
+    baseUrl = `http://localhost:${TEST_PORT}`;
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  }, 60000);
+
+  it('should accept sessions query parameter without error', async () => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 500);
+
+    try {
+      const response = await fetch(`${baseUrl}/api/events?sessions=abc,def`, {
+        signal: controller.signal,
+      });
+
+      expect(response.headers.get('content-type')).toBe('text/event-stream');
+    } catch (err: any) {
+      if (err.name !== 'AbortError') throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  });
+
+  it('should send init event regardless of session filter', async () => {
+    const events = await collectSSEEvents(baseUrl, '?sessions=nonexistent-id', 500);
+
+    const initEvent = events.find((e) => e.event === 'init');
+    expect(initEvent).toBeDefined();
+    expect((initEvent?.data as any).sessions).toBeDefined();
+  });
+
+  it('should receive all events when no sessions param is provided (backwards-compatible)', async () => {
+    // Start two SSE listeners: one with no filter, one with a filter for a nonexistent session
+    const controller1 = new AbortController();
+    const controller2 = new AbortController();
+    let unfilteredData = '';
+    let filteredData = '';
+
+    const fetch1 = fetch(`${baseUrl}/api/events`, {
+      signal: controller1.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            unfilteredData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    const fetch2 = fetch(`${baseUrl}/api/events?sessions=nonexistent-session`, {
+      signal: controller2.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            filteredData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    // Wait for connections to establish
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Create a session — this emits session:created (a global-ish event that has id but
+    // the nonexistent filter won't match it)
+    const createRes = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const createData = await createRes.json();
+    const sessionId = createData.session.id;
+
+    // Wait for events to arrive
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    // Stop listening
+    controller1.abort();
+    controller2.abort();
+    try {
+      await fetch1;
+    } catch {
+      /* expected */
+    }
+    try {
+      await fetch2;
+    } catch {
+      /* expected */
+    }
+
+    const unfilteredEvents = parseSSEEvents(unfilteredData);
+    const filteredEvents = parseSSEEvents(filteredData);
+
+    // Unfiltered client should receive the session:created event
+    const unfilteredCreated = unfilteredEvents.find((e) => e.event === 'session:created');
+    expect(unfilteredCreated).toBeDefined();
+    expect((unfilteredCreated?.data as any).id).toBe(sessionId);
+
+    // Filtered client (subscribed to nonexistent-session) should NOT receive session:created
+    // because session:created has an `id` field that doesn't match the filter
+    const filteredCreated = filteredEvents.find((e) => e.event === 'session:created');
+    expect(filteredCreated).toBeUndefined();
+
+    // Both should have received the init event (it has no sessionId)
+    expect(unfilteredEvents.find((e) => e.event === 'init')).toBeDefined();
+    expect(filteredEvents.find((e) => e.event === 'init')).toBeDefined();
+
+    // Cleanup
+    await fetch(`${baseUrl}/api/sessions/${sessionId}`, { method: 'DELETE' });
+  });
+
+  it('should deliver session events to a client subscribed to that session', async () => {
+    // First create a session so we know the ID
+    const createRes = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const createData = await createRes.json();
+    const sessionId = createData.session.id;
+
+    // Now connect SSE with the session filter
+    const controller = new AbortController();
+    let receivedData = '';
+
+    const fetchPromise = fetch(`${baseUrl}/api/events?sessions=${sessionId}`, {
+      signal: controller.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            receivedData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    // Wait for connection
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Delete the session — this emits session:deleted with { id: sessionId }
+    await fetch(`${baseUrl}/api/sessions/${sessionId}`, { method: 'DELETE' });
+
+    // Wait for events
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    controller.abort();
+    try {
+      await fetchPromise;
+    } catch {
+      /* expected */
+    }
+
+    const events = parseSSEEvents(receivedData);
+
+    // Should receive session:deleted because we're subscribed to this session
+    const deletedEvent = events.find((e) => e.event === 'session:deleted');
+    expect(deletedEvent).toBeDefined();
+    expect((deletedEvent?.data as any).id).toBe(sessionId);
+  });
+
+  it('should filter out events for sessions not in the subscription', async () => {
+    // Create two sessions
+    const createRes1 = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const session1 = (await createRes1.json()).session;
+
+    const createRes2 = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const session2 = (await createRes2.json()).session;
+
+    // Connect SSE subscribed ONLY to session1
+    const controller = new AbortController();
+    let receivedData = '';
+
+    const fetchPromise = fetch(`${baseUrl}/api/events?sessions=${session1.id}`, {
+      signal: controller.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            receivedData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    // Wait for connection
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Delete both sessions — emits session:deleted for each
+    await fetch(`${baseUrl}/api/sessions/${session1.id}`, { method: 'DELETE' });
+    await fetch(`${baseUrl}/api/sessions/${session2.id}`, { method: 'DELETE' });
+
+    // Wait for events
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    controller.abort();
+    try {
+      await fetchPromise;
+    } catch {
+      /* expected */
+    }
+
+    const events = parseSSEEvents(receivedData);
+
+    // Should receive session:deleted for session1
+    const deleted1 = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1.id);
+    expect(deleted1).toBeDefined();
+
+    // Should NOT receive session:deleted for session2
+    const deleted2 = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2.id);
+    expect(deleted2).toBeUndefined();
+  });
+
+  it('should support subscribing to multiple sessions', async () => {
+    // Create two sessions
+    const createRes1 = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const session1 = (await createRes1.json()).session;
+
+    const createRes2 = await fetch(`${baseUrl}/api/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workingDir: '/tmp' }),
+    });
+    const session2 = (await createRes2.json()).session;
+
+    // Connect SSE subscribed to both sessions
+    const controller = new AbortController();
+    let receivedData = '';
+
+    const fetchPromise = fetch(`${baseUrl}/api/events?sessions=${session1.id},${session2.id}`, {
+      signal: controller.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            receivedData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    // Wait for connection
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Delete both sessions
+    await fetch(`${baseUrl}/api/sessions/${session1.id}`, { method: 'DELETE' });
+    await fetch(`${baseUrl}/api/sessions/${session2.id}`, { method: 'DELETE' });
+
+    // Wait for events
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    controller.abort();
+    try {
+      await fetchPromise;
+    } catch {
+      /* expected */
+    }
+
+    const events = parseSSEEvents(receivedData);
+
+    // Should receive session:deleted for both sessions
+    const deleted1 = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === session1.id);
+    const deleted2 = events.find((e) => e.event === 'session:deleted' && (e.data as any).id === session2.id);
+    expect(deleted1).toBeDefined();
+    expect(deleted2).toBeDefined();
+  });
+
+  it('should deliver global events (no sessionId) to filtered clients', async () => {
+    // Connect with a filter — global events like case:created should still arrive
+    const controller = new AbortController();
+    let receivedData = '';
+
+    const fetchPromise = fetch(`${baseUrl}/api/events?sessions=some-session-id`, {
+      signal: controller.signal,
+    }).then(async (response) => {
+      const reader = response.body?.getReader();
+      if (reader) {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            receivedData += new TextDecoder().decode(value);
+          }
+        } catch {
+          /* expected */
+        }
+      }
+    });
+
+    // Wait for connection
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Create a case — case:created is a global event (no sessionId or id matching a session)
+    const caseName = `test-filter-case-${Date.now()}`;
+    await fetch(`${baseUrl}/api/cases`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: caseName }),
+    });
+
+    // Wait for events
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    controller.abort();
+    try {
+      await fetchPromise;
+    } catch {
+      /* expected */
+    }
+
+    const events = parseSSEEvents(receivedData);
+
+    // case:created should arrive because it has no sessionId — it's a global event
+    const caseCreated = events.find((e) => e.event === 'case:created');
+    expect(caseCreated).toBeDefined();
+    expect((caseCreated?.data as any).name).toBe(caseName);
+
+    // Cleanup
+    const { rmSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const { homedir } = await import('node:os');
+    try {
+      rmSync(join(homedir(), 'codeman-cases', caseName), { recursive: true });
+    } catch {
+      /* may not exist */
+    }
+  });
+});
@@ -0,0 +1,402 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { StaleExpirationMap } from '../src/utils/stale-expiration-map.js';
+
+describe('StaleExpirationMap', () => {
+  let map: StaleExpirationMap<string, number>;
+
+  afterEach(() => {
+    // Always dispose to clear cleanup timers
+    map?.dispose();
+  });
+
+  describe('construction', () => {
+    it('creates an empty map', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.size).toBe(0);
+      expect(map.isDisposed).toBe(false);
+    });
+
+    it('defaults refreshOnGet to true', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      // Verify by setting, advancing time partially, getting (refreshes), advancing again
+      vi.useFakeTimers();
+      map.set('a', 1);
+      vi.advanceTimersByTime(800); // 800ms of 1000ms TTL
+      map.get('a'); // should refresh
+      vi.advanceTimersByTime(800); // 1600ms total, but only 800ms since last access
+      expect(map.has('a')).toBe(true);
+      vi.useRealTimers();
+    });
+  });
+
+  describe('set/get', () => {
+    beforeEach(() => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+    });
+
+    it('stores and retrieves values', () => {
+      map.set('a', 1);
+      map.set('b', 2);
+      expect(map.get('a')).toBe(1);
+      expect(map.get('b')).toBe(2);
+    });
+
+    it('returns undefined for missing keys', () => {
+      expect(map.get('nonexistent')).toBeUndefined();
+    });
+
+    it('overwrites existing values', () => {
+      map.set('a', 1);
+      map.set('a', 10);
+      expect(map.get('a')).toBe(10);
+    });
+
+    it('supports chaining on set', () => {
+      const result = map.set('a', 1).set('b', 2);
+      expect(result).toBe(map);
+      expect(map.size).toBe(2);
+    });
+
+    it('ignores set when disposed', () => {
+      map.dispose();
+      map.set('a', 1);
+      expect(map.size).toBe(0);
+    });
+  });
+
+  describe('TTL expiration', () => {
+    it('expires entries after TTL', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(1001);
+      expect(map.get('a')).toBeUndefined();
+      expect(map.size).toBe(0);
+      vi.useRealTimers();
+    });
+
+    it('entries are accessible before TTL', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(500);
+      expect(map.get('a')).toBe(1);
+      vi.useRealTimers();
+    });
+
+    it('get refreshes TTL when refreshOnGet is true', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000, refreshOnGet: true });
+      map.set('a', 1);
+      vi.advanceTimersByTime(800);
+      map.get('a'); // refreshes to now
+      vi.advanceTimersByTime(800); // 800ms after refresh, still within TTL
+      expect(map.get('a')).toBe(1);
+      vi.useRealTimers();
+    });
+
+    it('get does not refresh TTL when refreshOnGet is false', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000, refreshOnGet: false });
+      map.set('a', 1);
+      vi.advanceTimersByTime(800);
+      map.get('a'); // does NOT refresh
+      vi.advanceTimersByTime(300); // 1100ms total, past TTL
+      expect(map.get('a')).toBeUndefined();
+      vi.useRealTimers();
+    });
+  });
+
+  describe('has', () => {
+    it('returns true for non-expired keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      expect(map.has('a')).toBe(true);
+    });
+
+    it('returns false for missing keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.has('nonexistent')).toBe(false);
+    });
+
+    it('returns false and deletes expired keys', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(1001);
+      expect(map.has('a')).toBe(false);
+      vi.useRealTimers();
+    });
+  });
+
+  describe('peek', () => {
+    it('returns value without refreshing TTL', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(800);
+      expect(map.peek('a')).toBe(1); // does not refresh
+      vi.advanceTimersByTime(300); // 1100ms total
+      expect(map.peek('a')).toBeUndefined();
+      vi.useRealTimers();
+    });
+
+    it('returns undefined for missing keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.peek('nonexistent')).toBeUndefined();
+    });
+
+    it('deletes expired entries on peek', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(1001);
+      map.peek('a');
+      // The internal entry should be deleted
+      expect(map.size).toBe(0);
+      vi.useRealTimers();
+    });
+  });
+
+  describe('delete', () => {
+    it('removes an existing key', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      expect(map.delete('a')).toBe(true);
+      expect(map.has('a')).toBe(false);
+      expect(map.size).toBe(0);
+    });
+
+    it('returns false for non-existent key', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.delete('nonexistent')).toBe(false);
+    });
+
+    it('does not call onExpire on manual delete', () => {
+      const onExpire = vi.fn();
+      map = new StaleExpirationMap({ ttlMs: 1000, onExpire });
+      map.set('a', 1);
+      map.delete('a');
+      expect(onExpire).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('clear', () => {
+    it('removes all entries', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      map.set('b', 2);
+      map.clear();
+      expect(map.size).toBe(0);
+      expect(map.get('a')).toBeUndefined();
+    });
+  });
+
+  describe('touch', () => {
+    it('refreshes TTL without returning value', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(800);
+      expect(map.touch('a')).toBe(true);
+      vi.advanceTimersByTime(800); // 1600ms total, but 800ms since touch
+      expect(map.has('a')).toBe(true);
+      vi.useRealTimers();
+    });
+
+    it('returns false for non-existent keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.touch('nonexistent')).toBe(false);
+    });
+
+    it('returns false for expired keys', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(1001);
+      expect(map.touch('a')).toBe(false);
+      vi.useRealTimers();
+    });
+  });
+
+  describe('getAge', () => {
+    it('returns age since creation', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 10000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(3000);
+      const age = map.getAge('a');
+      expect(age).toBe(3000);
+      vi.useRealTimers();
+    });
+
+    it('returns undefined for missing keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.getAge('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('getRemainingTtl', () => {
+    it('returns remaining time before expiration', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(300);
+      const remaining = map.getRemainingTtl('a');
+      expect(remaining).toBe(700);
+      vi.useRealTimers();
+    });
+
+    it('returns 0 for expired entries (before cleanup removes them)', () => {
+      vi.useFakeTimers();
+      // Use a long cleanup interval so the entry is not auto-removed
+      map = new StaleExpirationMap({ ttlMs: 1000, cleanupIntervalMs: 60000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(2000);
+      expect(map.getRemainingTtl('a')).toBe(0);
+      vi.useRealTimers();
+    });
+
+    it('returns undefined after cleanup removes expired entry', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(2000); // cleanup fires and removes 'a'
+      expect(map.getRemainingTtl('a')).toBeUndefined();
+      vi.useRealTimers();
+    });
+
+    it('returns undefined for missing keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.getRemainingTtl('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('cleanup', () => {
+    it('removes expired entries and returns count', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      map.set('b', 2);
+      vi.advanceTimersByTime(500);
+      map.set('c', 3);
+      vi.advanceTimersByTime(600); // 'a' and 'b' at 1100ms, 'c' at 600ms
+      const removed = map.cleanup();
+      expect(removed).toBe(2);
+      expect(map.size).toBe(1);
+      expect(map.has('c')).toBe(true);
+      vi.useRealTimers();
+    });
+
+    it('calls onExpire for each expired entry', () => {
+      vi.useFakeTimers();
+      const onExpire = vi.fn();
+      map = new StaleExpirationMap({ ttlMs: 1000, onExpire });
+      map.set('a', 1);
+      map.set('b', 2);
+      vi.advanceTimersByTime(1001);
+      map.cleanup();
+      expect(onExpire).toHaveBeenCalledTimes(2);
+      expect(onExpire).toHaveBeenCalledWith('a', 1);
+      expect(onExpire).toHaveBeenCalledWith('b', 2);
+      vi.useRealTimers();
+    });
+
+    it('returns 0 when nothing is expired', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      expect(map.cleanup()).toBe(0);
+    });
+
+    it('periodic cleanup runs automatically', () => {
+      vi.useFakeTimers();
+      const onExpire = vi.fn();
+      map = new StaleExpirationMap({ ttlMs: 1000, cleanupIntervalMs: 500, onExpire });
+      map.set('a', 1);
+      vi.advanceTimersByTime(1500); // past TTL, and cleanup interval fires
+      expect(onExpire).toHaveBeenCalledWith('a', 1);
+      vi.useRealTimers();
+    });
+  });
+
+  describe('iteration', () => {
+    it('iterates non-expired entries via for..of', () => {
+      map = new StaleExpirationMap({ ttlMs: 5000 });
+      map.set('a', 1);
+      map.set('b', 2);
+      const entries: [string, number][] = [];
+      for (const [k, v] of map) {
+        entries.push([k, v]);
+      }
+      expect(entries).toEqual([
+        ['a', 1],
+        ['b', 2],
+      ]);
+    });
+
+    it('skips expired entries during iteration', () => {
+      vi.useFakeTimers();
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      vi.advanceTimersByTime(500);
+      map.set('b', 2);
+      vi.advanceTimersByTime(600); // 'a' expired at 1100ms, 'b' at 600ms
+
+      const entries: [string, number][] = [];
+      for (const [k, v] of map) {
+        entries.push([k, v]);
+      }
+      expect(entries).toEqual([['b', 2]]);
+      vi.useRealTimers();
+    });
+
+    it('keys() yields non-expired keys', () => {
+      map = new StaleExpirationMap({ ttlMs: 5000 });
+      map.set('a', 1);
+      map.set('b', 2);
+      expect([...map.keys()]).toEqual(['a', 'b']);
+    });
+
+    it('values() yields non-expired values', () => {
+      map = new StaleExpirationMap({ ttlMs: 5000 });
+      map.set('a', 1);
+      map.set('b', 2);
+      expect([...map.values()]).toEqual([1, 2]);
+    });
+  });
+
+  describe('dispose', () => {
+    it('marks map as disposed', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      expect(map.isDisposed).toBe(false);
+      map.dispose();
+      expect(map.isDisposed).toBe(true);
+    });
+
+    it('clears all entries on dispose', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.set('a', 1);
+      map.dispose();
+      expect(map.size).toBe(0);
+    });
+
+    it('is idempotent', () => {
+      map = new StaleExpirationMap({ ttlMs: 1000 });
+      map.dispose();
+      map.dispose(); // should not throw
+      expect(map.isDisposed).toBe(true);
+    });
+
+    it('stops periodic cleanup after dispose', () => {
+      vi.useFakeTimers();
+      const onExpire = vi.fn();
+      map = new StaleExpirationMap({ ttlMs: 1000, cleanupIntervalMs: 500, onExpire });
+      map.set('a', 1);
+      map.dispose();
+      vi.advanceTimersByTime(2000);
+      // onExpire should not be called because timer was stopped
+      expect(onExpire).not.toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+  });
+});
@@ -1,16 +1,27 @@
 import React from 'react';
 import { Composition } from 'remotion';
 import { CodemanDemo, TOTAL_FRAMES } from './compositions/CodemanDemo';
+import { ZerolagDemo, ZEROLAG_TOTAL_FRAMES } from './compositions/ZerolagDemo';

 export const RemotionRoot: React.FC = () => {
  return (
-    <Composition
-      id="CodemanDemo"
-      component={CodemanDemo}
-      durationInFrames={TOTAL_FRAMES}
-      fps={30}
-      width={1920}
-      height={1080}
-    />
+    <>
+      <Composition
+        id="CodemanDemo"
+        component={CodemanDemo}
+        durationInFrames={TOTAL_FRAMES}
+        fps={30}
+        width={1920}
+        height={1080}
+      />
+      <Composition
+        id="ZerolagDemo"
+        component={ZerolagDemo}
+        durationInFrames={ZEROLAG_TOTAL_FRAMES}
+        fps={30}
+        width={1920}
+        height={1080}
+      />
+    </>
  );
 };
@@ -0,0 +1,207 @@
+import React from 'react';
+import { fonts } from '../lib/theme';
+
+type IOSKeyboardProps = {
+  activeKey?: string;
+  /** How many frames since the key was pressed (for highlight decay) */
+  pressAge?: number;
+};
+
+const ROW_1 = ['q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p'];
+const ROW_2 = ['a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l'];
+const ROW_3 = ['z', 'x', 'c', 'v', 'b', 'n', 'm'];
+
+const KEY_H = 42;
+const KEY_GAP = 6;
+const ROW_GAP = 11;
+const SIDE_PAD = 3;
+
+const KEYBOARD_BG = '#1c1c1e';
+const KEY_BG = '#3a3a3c';
+const KEY_BG_ACTIVE = '#636366';
+const KEY_TEXT = '#fff';
+const SPECIAL_BG = '#2c2c2e';
+
+const Key: React.FC<{
+  label: string;
+  width: number;
+  isActive: boolean;
+  pressAge: number;
+  fontSize?: number;
+}> = ({ label, width, isActive, pressAge, fontSize = 22 }) => {
+  // Highlight decays over 4 frames
+  const highlightOpacity = isActive && pressAge < 4 ? 1 - pressAge / 4 : 0;
+  const bg = highlightOpacity > 0
+    ? lerpColor(KEY_BG, KEY_BG_ACTIVE, highlightOpacity)
+    : KEY_BG;
+
+  return (
+    <div
+      style={{
+        width,
+        height: KEY_H,
+        borderRadius: 5,
+        background: bg,
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+        fontSize,
+        fontFamily: fonts.ui,
+        color: KEY_TEXT,
+        fontWeight: 300,
+        flexShrink: 0,
+      }}
+    >
+      {label}
+    </div>
+  );
+};
+
+function lerpColor(a: string, b: string, t: number): string {
+  const pa = parseInt(a.slice(1), 16);
+  const pb = parseInt(b.slice(1), 16);
+  const r = Math.round(((pa >> 16) & 0xff) * (1 - t) + ((pb >> 16) & 0xff) * t);
+  const g = Math.round(((pa >> 8) & 0xff) * (1 - t) + ((pb >> 8) & 0xff) * t);
+  const bl = Math.round((pa & 0xff) * (1 - t) + (pb & 0xff) * t);
+  return `#${((r << 16) | (g << 8) | bl).toString(16).padStart(6, '0')}`;
+}
+
+export const IOSKeyboard: React.FC<IOSKeyboardProps> = ({ activeKey, pressAge = 99 }) => {
+  const isActive = (key: string) =>
+    activeKey !== undefined && key.toLowerCase() === activeKey.toLowerCase();
+  const age = (key: string) => (isActive(key) ? pressAge : 99);
+
+  // Backspace/delete key highlight
+  const deleteHighlight = activeKey === '⌫' && pressAge < 4 ? 1 - pressAge / 4 : 0;
+  const deleteBg = deleteHighlight > 0 ? lerpColor(SPECIAL_BG, KEY_BG_ACTIVE, deleteHighlight) : SPECIAL_BG;
+
+  // Key widths: 10 keys + 9 gaps in ~375px row → each key ~33px
+  const letterKeyW = 33;
+  // Row 2 has 9 keys → same key width but centered with side padding
+  // Row 3 has shift + 7 keys + delete
+
+  return (
+    <div
+      style={{
+        width: '100%',
+        background: KEYBOARD_BG,
+        padding: `${ROW_GAP}px ${SIDE_PAD}px 20px`,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: ROW_GAP,
+      }}
+    >
+      {/* Row 1: q-p */}
+      <div style={{ display: 'flex', gap: KEY_GAP, justifyContent: 'center' }}>
+        {ROW_1.map((k) => (
+          <Key key={k} label={k} width={letterKeyW} isActive={isActive(k)} pressAge={age(k)} />
+        ))}
+      </div>
+
+      {/* Row 2: a-l */}
+      <div style={{ display: 'flex', gap: KEY_GAP, justifyContent: 'center' }}>
+        {ROW_2.map((k) => (
+          <Key key={k} label={k} width={letterKeyW} isActive={isActive(k)} pressAge={age(k)} />
+        ))}
+      </div>
+
+      {/* Row 3: shift + z-m + delete */}
+      <div style={{ display: 'flex', gap: KEY_GAP, justifyContent: 'center' }}>
+        <div
+          style={{
+            width: 42,
+            height: KEY_H,
+            borderRadius: 5,
+            background: SPECIAL_BG,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+          }}
+        >
+          <svg width="20" height="16" viewBox="0 0 20 16" fill="none">
+            <path d="M10 2L17 9H13V14H7V9H3L10 2Z" fill="#fff" />
+          </svg>
+        </div>
+        {ROW_3.map((k) => (
+          <Key key={k} label={k} width={letterKeyW} isActive={isActive(k)} pressAge={age(k)} />
+        ))}
+        <div
+          style={{
+            width: 42,
+            height: KEY_H,
+            borderRadius: 5,
+            background: deleteBg,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+          }}
+        >
+          <svg width="22" height="16" viewBox="0 0 22 16" fill="none">
+            <path d="M7 1L1 8L7 15H21V1H7Z" stroke="#fff" strokeWidth="1.5" fill="none" />
+            <path d="M12 5L17 10M17 5L12 10" stroke="#fff" strokeWidth="1.5" strokeLinecap="round" />
+          </svg>
+        </div>
+      </div>
+
+      {/* Row 4: 123 / globe / space / return */}
+      <div style={{ display: 'flex', gap: KEY_GAP, justifyContent: 'center' }}>
+        <div
+          style={{
+            width: 42,
+            height: KEY_H,
+            borderRadius: 5,
+            background: SPECIAL_BG,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+            fontSize: 15,
+            fontFamily: fonts.ui,
+            color: '#fff',
+          }}
+        >
+          123
+        </div>
+        <div
+          style={{
+            width: 38,
+            height: KEY_H,
+            borderRadius: 5,
+            background: SPECIAL_BG,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+          }}
+        >
+          <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+            <circle cx="10" cy="10" r="8" stroke="#fff" strokeWidth="1.2" />
+            <path d="M4 10H16M10 4C7 7 7 13 10 16M10 4C13 7 13 13 10 16" stroke="#fff" strokeWidth="1" />
+          </svg>
+        </div>
+        {/* Space bar */}
+        <Key
+          label="space"
+          width={186}
+          isActive={isActive(' ')}
+          pressAge={age(' ')}
+          fontSize={15}
+        />
+        <div
+          style={{
+            width: 88,
+            height: KEY_H,
+            borderRadius: 5,
+            background: SPECIAL_BG,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+            fontSize: 15,
+            fontFamily: fonts.ui,
+            color: '#fff',
+          }}
+        >
+          return
+        </div>
+      </div>
+    </div>
+  );
+};
@@ -0,0 +1,171 @@
+import React from 'react';
+import { spring, useCurrentFrame, useVideoConfig } from 'remotion';
+
+/**
+ * Pixel-accurate iPhone 17 Pro frame.
+ *
+ * Dimensions based on iPhone 16 Pro (same form factor):
+ * - Screen: 393×852 CSS points (2622×1206 @3x)
+ * - Corner radius: 55px (device), 50px (screen inner)
+ * - Bezel: ~3.5px (thinnest in any iPhone)
+ * - Dynamic Island: 126×37 pill, centered 13px from top
+ * - Safe area: top 59px, bottom 34px (home indicator)
+ * - Frame: natural titanium (#8a8a8e border)
+ */
+
+type IPhone17ProFrameProps = {
+  children: React.ReactNode;
+  /** Disable the spring entrance animation */
+  noAnimation?: boolean;
+};
+
+// Device dimensions (CSS points)
+const SCREEN_W = 393;
+const SCREEN_H = 852;
+const BEZEL = 4;
+const DEVICE_W = SCREEN_W + BEZEL * 2; // 401
+const DEVICE_H = SCREEN_H + BEZEL * 2; // 860
+const DEVICE_RADIUS = 55;
+const SCREEN_RADIUS = 50;
+
+// Dynamic Island
+const DI_W = 126;
+const DI_H = 37;
+const DI_TOP = 13; // from top of screen
+const DI_RADIUS = DI_H / 2; // pill shape
+
+export { SCREEN_W, SCREEN_H };
+
+export const IPhone17ProFrame: React.FC<IPhone17ProFrameProps> = ({ children, noAnimation }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const scale = noAnimation
+    ? 1
+    : spring({ frame, fps, config: { damping: 15, stiffness: 80 } });
+
+  return (
+    <div
+      style={{
+        width: DEVICE_W,
+        height: DEVICE_H,
+        transform: `scale(${scale})`,
+        transformOrigin: 'center center',
+        position: 'relative',
+      }}
+    >
+      {/* Titanium frame (outer body) */}
+      <div
+        style={{
+          width: DEVICE_W,
+          height: DEVICE_H,
+          borderRadius: DEVICE_RADIUS,
+          background: '#2c2c2e', // dark titanium
+          border: '1.5px solid #48484a', // subtle edge highlight
+          boxShadow: [
+            '0 2px 4px rgba(0,0,0,0.3)', // close shadow
+            '0 12px 40px rgba(0,0,0,0.5)', // mid shadow
+            '0 30px 80px rgba(0,0,0,0.4)', // far shadow
+            'inset 0 1px 0 rgba(255,255,255,0.05)', // top edge gleam
+          ].join(', '),
+          position: 'relative',
+          overflow: 'hidden',
+        }}
+      >
+        {/* Side button (right) — power */}
+        <div
+          style={{
+            position: 'absolute',
+            right: -2,
+            top: 180,
+            width: 3,
+            height: 65,
+            borderRadius: '0 2px 2px 0',
+            background: '#48484a',
+          }}
+        />
+
+        {/* Side buttons (left) — volume up, down, action */}
+        <div
+          style={{
+            position: 'absolute',
+            left: -2,
+            top: 140,
+            width: 3,
+            height: 28,
+            borderRadius: '2px 0 0 2px',
+            background: '#48484a',
+          }}
+        />
+        <div
+          style={{
+            position: 'absolute',
+            left: -2,
+            top: 185,
+            width: 3,
+            height: 50,
+            borderRadius: '2px 0 0 2px',
+            background: '#48484a',
+          }}
+        />
+        <div
+          style={{
+            position: 'absolute',
+            left: -2,
+            top: 250,
+            width: 3,
+            height: 50,
+            borderRadius: '2px 0 0 2px',
+            background: '#48484a',
+          }}
+        />
+
+        {/* Screen */}
+        <div
+          style={{
+            position: 'absolute',
+            top: BEZEL,
+            left: BEZEL,
+            width: SCREEN_W,
+            height: SCREEN_H,
+            borderRadius: SCREEN_RADIUS,
+            overflow: 'hidden',
+            background: '#000',
+          }}
+        >
+          {/* App content */}
+          {children}
+
+          {/* Dynamic Island (on top of everything) */}
+          <div
+            style={{
+              position: 'absolute',
+              top: DI_TOP,
+              left: (SCREEN_W - DI_W) / 2,
+              width: DI_W,
+              height: DI_H,
+              borderRadius: DI_RADIUS,
+              background: '#000',
+              zIndex: 50,
+            }}
+          />
+        </div>
+      </div>
+
+      {/* Home indicator */}
+      <div
+        style={{
+          position: 'absolute',
+          bottom: BEZEL + 8,
+          left: '50%',
+          transform: 'translateX(-50%)',
+          width: 134,
+          height: 5,
+          borderRadius: 3,
+          background: 'rgba(255,255,255,0.2)',
+          zIndex: 60,
+        }}
+      />
+    </div>
+  );
+};
@@ -0,0 +1,117 @@
+import React from 'react';
+import { useCurrentFrame } from 'remotion';
+import { colors, fonts } from '../lib/theme';
+
+type OverlayChar = {
+  char: string;
+  confirmed: boolean;
+};
+
+type TerminalScreenProps = {
+  typed: string;
+  cursorVisible: boolean;
+  overlayChars?: OverlayChar[];
+  fontSize?: number;
+};
+
+/**
+ * Renders a terminal area styled exactly like the real Codeman xterm.js terminal.
+ * Background #0d0d0d, Fira Code font, block cursor, Claude Code prompt.
+ */
+export const TerminalScreen: React.FC<TerminalScreenProps> = ({
+  typed,
+  cursorVisible,
+  overlayChars,
+  fontSize = 28,
+}) => {
+  const frame = useCurrentFrame();
+
+  // Block cursor — solid, no blink (matches Codeman's cursorBlink: false)
+  const cursorOn = cursorVisible;
+  // But add a subtle blink for video clarity so viewers notice it
+  const cursorOpacity = cursorOn ? (Math.floor(frame / 20) % 2 === 0 ? 0.9 : 0.6) : 0;
+
+  const lineHeight = Math.round(fontSize * 1.35);
+  const charWidth = fontSize * 0.6;
+
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        background: '#0d0d0d',
+        position: 'relative',
+        fontFamily: '"Fira Code", "Cascadia Code", "JetBrains Mono", "SF Mono", Monaco, monospace',
+        overflow: 'hidden',
+      }}
+    >
+      {/* Previous terminal output lines (fake history for realism) */}
+      <div
+        style={{
+          padding: '16px 20px',
+          fontSize: fontSize * 0.65,
+          lineHeight: `${Math.round(fontSize * 0.65 * 1.4)}px`,
+          color: '#495057',
+        }}
+      >
+        <div>
+          <span style={{ color: '#339af0' }}>❯</span>
+          <span style={{ color: '#495057' }}> claude --dangerously-skip-permissions</span>
+        </div>
+        <div style={{ color: '#3a3a3a', marginTop: 4 }}>
+          ╭────────────────────────────────────╮
+        </div>
+        <div style={{ color: '#3a3a3a' }}>
+          │ Claude Code session active         │
+        </div>
+        <div style={{ color: '#3a3a3a' }}>
+          ╰────────────────────────────────────╯
+        </div>
+      </div>
+
+      {/* Active prompt line — this is where the typing happens */}
+      <div
+        style={{
+          padding: '8px 20px',
+          fontSize,
+          lineHeight: `${lineHeight}px`,
+          display: 'flex',
+          alignItems: 'baseline',
+        }}
+      >
+        {/* Prompt character */}
+        <span style={{ color: '#339af0', fontWeight: 700, marginRight: charWidth * 0.8 }}>❯</span>
+
+        {/* Typed text */}
+        {overlayChars ? (
+          // Zerolag mode: show overlay chars with confirmed/unconfirmed color
+          overlayChars.map((oc, i) => (
+            <span
+              key={i}
+              style={{
+                color: oc.confirmed ? '#e0e0e0' : '#7a7a7a',
+                letterSpacing: '0.5px',
+              }}
+            >
+              {oc.char}
+            </span>
+          ))
+        ) : (
+          <span style={{ color: '#e0e0e0', letterSpacing: '0.5px' }}>{typed}</span>
+        )}
+
+        {/* Block cursor */}
+        <span
+          style={{
+            display: 'inline-block',
+            width: charWidth,
+            height: lineHeight * 0.85,
+            background: `rgba(224, 224, 224, ${cursorOpacity})`,
+            verticalAlign: 'text-bottom',
+            marginLeft: 1,
+          }}
+        />
+      </div>
+    </div>
+  );
+};
@@ -0,0 +1,422 @@
+import React from 'react';
+import {
+  AbsoluteFill,
+  Img,
+  interpolate,
+  Sequence,
+  spring,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from 'remotion';
+import { colors, fonts } from '../lib/theme';
+import { IPhone17ProFrame, SCREEN_W, SCREEN_H } from '../components/IPhone17ProFrame';
+import { IOSKeyboard } from '../components/IOSKeyboard';
+
+// ─── Scene timing (frames @ 30fps) ───
+const TITLE_DUR = 60;
+const PHONES_DUR = 30;
+const TYPING_DUR = 468;
+const HOLD_DUR = 60;
+const OUTRO_DUR = 45;
+
+const TITLE_START = 0;
+const PHONES_START = TITLE_DUR; // 60
+const TYPING_START = PHONES_START + PHONES_DUR; // 90
+const HOLD_START = TYPING_START + TYPING_DUR; // 558
+const OUTRO_START = HOLD_START + HOLD_DUR; // 618
+
+export const ZEROLAG_TOTAL_FRAMES = OUTRO_START + OUTRO_DUR; // 663
+
+// ─── iPhone 17 Pro safe area ───
+const SAFE_AREA_TOP = 59; // Below Dynamic Island
+const PHONE_SCALE = 1.12; // Scale up to fill more of the frame
+
+// The Codeman screenshot starts content at y=0 (the session tab).
+// On a real device it would sit below the safe area, so we offset it.
+const SCREENSHOT_Y_OFFSET = SAFE_AREA_TOP;
+
+// Terminal typing overlay position (relative to screenshot top)
+// Session tab is ~44px, then terminal starts. Adding safe area offset:
+const TERMINAL_TOP = SAFE_AREA_TOP + 52;
+const TERMINAL_LEFT = 14;
+const TERMINAL_FONT = 22; // Large for video readability
+
+// ─── Typing schedule (with typo + backspace correction) ───
+const CORRECT_TEXT = 'fix the auth bug in the login flow';
+const FRAME_GAP = 12; // ~400ms between keystrokes
+const TYPO_INDEX = 28; // After "logi", type "m" instead of "n"
+
+// Remote connection lag: 600ms-1.2s+ per char (18-36+ frames)
+const LAGGY_DELAYS = [
+  24, 30, 36, 32, 26, 22, 34, 28, 38, 20, 30, 24, 32, 26, 36, 22,
+  30, 24, 32, 28, 34, 26, 30, 22, 28, 36, 24, 30, 32, 26, 34, 28, 24, 30,
+  26, 32, 28, 34,
+];
+
+type KeyAction = { frame: number; action: 'type' | 'backspace'; char: string; lagDelay: number };
+
+const buildSchedule = (): KeyAction[] => {
+  const actions: KeyAction[] = [];
+  let idx = 0;
+  const lag = (i: number) => LAGGY_DELAYS[i % LAGGY_DELAYS.length];
+
+  // Type correctly up to typo point: "fix the auth bug in the logi"
+  for (let i = 0; i < TYPO_INDEX; i++) {
+    actions.push({ frame: idx * FRAME_GAP, action: 'type', char: CORRECT_TEXT[i], lagDelay: lag(idx) });
+    idx++;
+  }
+
+  // Typo: type "m" instead of "n"
+  actions.push({ frame: idx * FRAME_GAP, action: 'type', char: 'm', lagDelay: lag(idx) });
+  idx++;
+
+  // Backspace to fix it
+  actions.push({ frame: idx * FRAME_GAP, action: 'backspace', char: '⌫', lagDelay: lag(idx) });
+  idx++;
+
+  // Type correct remaining: "n flow"
+  for (let i = TYPO_INDEX; i < CORRECT_TEXT.length; i++) {
+    actions.push({ frame: idx * FRAME_GAP, action: 'type', char: CORRECT_TEXT[i], lagDelay: lag(idx) });
+    idx++;
+  }
+
+  return actions;
+};
+
+const TYPING_SCHEDULE = buildSchedule();
+
+/** Replay actions in order up to current frame, computing the visible text buffer */
+const computeVisibleText = (frame: number, withLag: boolean): string => {
+  let buffer = '';
+  for (const a of TYPING_SCHEDULE) {
+    const threshold = withLag ? a.frame + a.lagDelay : a.frame;
+    if (frame < threshold) break; // TCP-ordered: stop at first unresolved
+    if (a.action === 'backspace') buffer = buffer.slice(0, -1);
+    else buffer += a.char;
+  }
+  return buffer;
+};
+
+// ─── iOS Status Bar (sits in the safe area, flanking Dynamic Island) ───
+const IOSStatusBar: React.FC = () => (
+  <div
+    style={{
+      position: 'absolute',
+      top: 17,
+      left: 0,
+      right: 0,
+      height: 20,
+      display: 'flex',
+      justifyContent: 'space-between',
+      padding: '0 30px',
+      fontSize: 15,
+      fontFamily: fonts.ui,
+      fontWeight: 600,
+      color: '#fff',
+      zIndex: 40,
+    }}
+  >
+    <span>9:41</span>
+    <div style={{ display: 'flex', gap: 6, alignItems: 'center' }}>
+      {/* Signal */}
+      <svg width="17" height="12" viewBox="0 0 17 12">
+        <rect x="0" y="8" width="3" height="4" rx="0.5" fill="#fff" />
+        <rect x="4.5" y="5" width="3" height="7" rx="0.5" fill="#fff" />
+        <rect x="9" y="2" width="3" height="10" rx="0.5" fill="#fff" />
+        <rect x="13.5" y="0" width="3" height="12" rx="0.5" fill="#fff" />
+      </svg>
+      {/* WiFi */}
+      <svg width="16" height="12" viewBox="0 0 16 12">
+        <path d="M4.5 8.5C5.5 7.2 6.7 6.5 8 6.5s2.5.7 3.5 2" stroke="#fff" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+        <path d="M1.5 5.5C3.5 3 5.7 1.5 8 1.5s4.5 1.5 6.5 4" stroke="#fff" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+        <circle cx="8" cy="11" r="1.5" fill="#fff" />
+      </svg>
+      {/* Battery */}
+      <svg width="27" height="12" viewBox="0 0 27 12">
+        <rect x="0" y="0.5" width="23" height="11" rx="2" stroke="#fff" strokeWidth="1" fill="none" />
+        <rect x="24" y="3.5" width="2.5" height="5" rx="1" fill="#fff" opacity="0.4" />
+        <rect x="1.5" y="2" width="20" height="8" rx="1" fill="#32d74b" />
+      </svg>
+    </div>
+  </div>
+);
+
+// ─── Typing overlay ───
+const TypingOverlay: React.FC<{
+  typed: string;
+  overlayChars?: { char: string; confirmed: boolean }[];
+  cursorVisible: boolean;
+}> = ({ typed, overlayChars, cursorVisible }) => {
+  const frame = useCurrentFrame();
+  const cursorOpacity = cursorVisible ? (Math.floor(frame / 18) % 2 === 0 ? 0.85 : 0.5) : 0;
+  const lineH = Math.round(TERMINAL_FONT * 1.4);
+  const charW = TERMINAL_FONT * 0.62;
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: TERMINAL_TOP,
+        left: TERMINAL_LEFT,
+        right: TERMINAL_LEFT,
+        fontFamily: '"Fira Code", "Cascadia Code", "JetBrains Mono", "SF Mono", Monaco, monospace',
+        fontSize: TERMINAL_FONT,
+        lineHeight: `${lineH}px`,
+        zIndex: 10,
+      }}
+    >
+      <span style={{ color: '#339af0', fontWeight: 700 }}>{'❯ '}</span>
+      {overlayChars
+        ? overlayChars.map((oc, i) => (
+            <span key={i} style={{ color: oc.confirmed ? '#e0e0e0' : '#666' }}>
+              {oc.char}
+            </span>
+          ))
+        : <span style={{ color: '#e0e0e0' }}>{typed}</span>}
+      <span
+        style={{
+          display: 'inline-block',
+          width: charW,
+          height: lineH * 0.82,
+          background: `rgba(224, 224, 224, ${cursorOpacity})`,
+          verticalAlign: 'text-bottom',
+          marginLeft: 1,
+        }}
+      />
+    </div>
+  );
+};
+
+// ─── Single phone: iPhone 17 Pro + real screenshot + typing + keyboard ───
+const MobileCodeman: React.FC<{
+  typed: string;
+  overlayChars?: { char: string; confirmed: boolean }[];
+  cursorVisible: boolean;
+  activeKey?: string;
+  pressAge?: number;
+  showKeyboard?: boolean;
+  noAnimation?: boolean;
+}> = ({ typed, overlayChars, cursorVisible, activeKey, pressAge, showKeyboard = true, noAnimation }) => (
+  <IPhone17ProFrame noAnimation={noAnimation}>
+    <div style={{ width: SCREEN_W, height: SCREEN_H, position: 'relative', overflow: 'hidden', background: '#000' }}>
+      {/* Real Codeman mobile screenshot, pushed down by safe area */}
+      <Img
+        src={staticFile('mobile-claude.png')}
+        style={{
+          width: SCREEN_W,
+          height: SCREEN_H - SCREENSHOT_Y_OFFSET,
+          objectFit: 'cover',
+          objectPosition: 'top',
+          position: 'absolute',
+          top: SCREENSHOT_Y_OFFSET,
+          left: 0,
+        }}
+      />
+
+      {/* iOS status bar in the safe area */}
+      <IOSStatusBar />
+
+      {/* Typing animation */}
+      <TypingOverlay typed={typed} overlayChars={overlayChars} cursorVisible={cursorVisible} />
+
+      {/* iOS keyboard at bottom */}
+      {showKeyboard && (
+        <div style={{ position: 'absolute', bottom: 0, left: 0, right: 0, zIndex: 20 }}>
+          <IOSKeyboard activeKey={activeKey} pressAge={pressAge} />
+        </div>
+      )}
+    </div>
+  </IPhone17ProFrame>
+);
+
+// ─── Label beneath phone ───
+const PhoneLabel: React.FC<{
+  title: string;
+  detail: string;
+  dotColor: string;
+  detailColor: string;
+}> = ({ title, detail, dotColor, detailColor }) => (
+  <div style={{ textAlign: 'center', marginTop: 20 }}>
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 10,
+        fontSize: 24,
+        fontWeight: 600,
+        fontFamily: fonts.ui,
+        color: '#fff',
+      }}
+    >
+      <div
+        style={{
+          width: 12,
+          height: 12,
+          borderRadius: '50%',
+          background: dotColor,
+          boxShadow: `0 0 12px ${dotColor}`,
+        }}
+      />
+      {title}
+    </div>
+    <div style={{ fontSize: 16, fontFamily: fonts.mono, color: detailColor, marginTop: 6, opacity: 0.9 }}>
+      {detail}
+    </div>
+  </div>
+);
+
+// ─── Title scene ───
+const TitleScene: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const titleScale = spring({ frame, fps, config: { damping: 15, stiffness: 80 } });
+  const titleOpacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: 'clamp' });
+  const subtitleOpacity = interpolate(frame, [15, 35], [0, 1], { extrapolateRight: 'clamp' });
+
+  return (
+    <AbsoluteFill style={{ background: colors.bg.dark, justifyContent: 'center', alignItems: 'center' }}>
+      <div style={{ textAlign: 'center', transform: `scale(${titleScale})` }}>
+        <div
+          style={{
+            fontSize: 80,
+            fontWeight: 700,
+            fontFamily: fonts.ui,
+            color: '#fff',
+            opacity: titleOpacity,
+            letterSpacing: -1.5,
+          }}
+        >
+          Zerolag Input
+        </div>
+        <div
+          style={{
+            fontSize: 30,
+            fontFamily: fonts.ui,
+            color: colors.text.dim,
+            opacity: subtitleOpacity,
+            marginTop: 16,
+          }}
+        >
+          Local echo for remote terminal sessions
+        </div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// ─── Outro ───
+const OutroScene: React.FC = () => {
+  const frame = useCurrentFrame();
+  const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: 'clamp' });
+
+  return (
+    <AbsoluteFill style={{ background: colors.bg.dark, justifyContent: 'center', alignItems: 'center', opacity }}>
+      <div style={{ textAlign: 'center' }}>
+        <div style={{ fontSize: 56, fontWeight: 700, fontFamily: fonts.ui, color: '#fff' }}>Codeman</div>
+        <div style={{ fontSize: 26, fontFamily: fonts.ui, color: colors.accent.green, marginTop: 10 }}>
+          Zero-latency mobile input
+        </div>
+        <div style={{ fontSize: 16, fontFamily: fonts.mono, color: colors.text.muted, marginTop: 20 }}>
+          npm i xterm-zerolag-input
+        </div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// ─── Typing demo scene ───
+const TypingDemo: React.FC = () => {
+  const frame = useCurrentFrame();
+
+  const laggyTyped = computeVisibleText(frame, true);
+  const zerolagTyped = computeVisibleText(frame, false);
+
+  let activeKey: string | undefined;
+  let pressAge = 99;
+  for (let i = TYPING_SCHEDULE.length - 1; i >= 0; i--) {
+    const ev = TYPING_SCHEDULE[i];
+    if (frame >= ev.frame && frame < ev.frame + 5) {
+      activeKey = ev.char;
+      pressAge = frame - ev.frame;
+      break;
+    }
+  }
+
+  return (
+    <AbsoluteFill style={{ background: colors.bg.dark, justifyContent: 'center', alignItems: 'center' }}>
+      <div
+        style={{
+          display: 'flex',
+          gap: 50,
+          alignItems: 'flex-start',
+          transform: `scale(${PHONE_SCALE})`,
+          transformOrigin: 'center center',
+        }}
+      >
+        <div>
+          <MobileCodeman typed={zerolagTyped} cursorVisible activeKey={activeKey} pressAge={pressAge} noAnimation />
+          <PhoneLabel title="With Zerolag" detail="0ms delay" dotColor={colors.accent.green} detailColor={colors.accent.green} />
+        </div>
+        <div>
+          <MobileCodeman typed={laggyTyped} cursorVisible activeKey={activeKey} pressAge={pressAge} noAnimation />
+          <PhoneLabel title="Without Zerolag" detail="600ms–1.2s delay" dotColor={colors.accent.red} detailColor={colors.accent.red} />
+        </div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// ─── Phones entrance ───
+const PanelsEntrance: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const scale = spring({ frame, fps, config: { damping: 15, stiffness: 80 } });
+  const opacity = interpolate(frame, [0, 10], [0, 1], { extrapolateRight: 'clamp' });
+
+  return (
+    <AbsoluteFill
+      style={{
+        background: colors.bg.dark,
+        justifyContent: 'center',
+        alignItems: 'center',
+        opacity,
+        transform: `scale(${scale * PHONE_SCALE})`,
+      }}
+    >
+      <div style={{ display: 'flex', gap: 50, alignItems: 'flex-start' }}>
+        <div>
+          <MobileCodeman typed="" cursorVisible noAnimation />
+          <PhoneLabel title="With Zerolag" detail="0ms delay" dotColor={colors.accent.green} detailColor={colors.accent.green} />
+        </div>
+        <div>
+          <MobileCodeman typed="" cursorVisible noAnimation />
+          <PhoneLabel title="Without Zerolag" detail="600ms–1.2s delay" dotColor={colors.accent.red} detailColor={colors.accent.red} />
+        </div>
+      </div>
+    </AbsoluteFill>
+  );
+};
+
+// ─── Main composition ───
+export const ZerolagDemo: React.FC = () => {
+  return (
+    <AbsoluteFill style={{ background: colors.bg.dark }}>
+      <Sequence from={TITLE_START} durationInFrames={TITLE_DUR}>
+        <TitleScene />
+      </Sequence>
+      <Sequence from={PHONES_START} durationInFrames={PHONES_DUR} premountFor={5}>
+        <PanelsEntrance />
+      </Sequence>
+      <Sequence from={TYPING_START} durationInFrames={TYPING_DUR + HOLD_DUR} premountFor={5}>
+        <TypingDemo />
+      </Sequence>
+      <Sequence from={OUTRO_START} durationInFrames={OUTRO_DUR} premountFor={5}>
+        <OutroScene />
+      </Sequence>
+    </AbsoluteFill>
+  );
+};
@@ -23,5 +23,5 @@
    "allowUnusedLabels": false
  },
  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "src/tui"]
+  "exclude": ["node_modules", "dist"]
 }
Author	SHA1	Message	Date
arkonandClaude Opus 4.6	e799c83b39	chore: version packages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-07 07:34:24 +01:00
arkonandClaude Opus 4.6	0717cfbfec	refactor: codebase cleanup — dead code, regex helper, centralized constants, tests - Remove unused validateTokenCounts/validateTokensAndCost exports and PlanPhase type alias - Add execPattern() helper to eliminate 8 repetitive .lastIndex=0 + exec() loops - Centralize 11 magic number constants into config/ai-defaults.ts and config/server-timing.ts - Remove stale src/tui from tsconfig.json exclude - Fix CLAUDE.md inaccuracies (session helpers, app.js line count, module count) - Add 316 new tests: LRUMap (38), StaleExpirationMap (42), BufferAccumulator (33), respawn helpers (142), system-routes expansion (11→61) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-07 07:33:44 +01:00
arkonandClaude Opus 4.6	b7b2555dc0	test: add Operation Lightspeed tests — tab switching, local echo, SSE filters 14 new tests covering tab switch SSE reconnect, terminal buffer edge cases (tail=0, negative, non-numeric, huge values), extractSessionId filtering, session lifecycle churn, and concurrent SSE client limits. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-07 07:04:27 +01:00
arkonandClaude Opus 4.6	a609c435fa	fix: use TERMINAL_TAIL_SIZE constant and add client-drop recovery Two hardcoded `256 * 1024` tail sizes in app.js bypassed the TERMINAL_TAIL_SIZE constant (128KB), causing stale cached browsers to fetch 256KB buffers even after the constant was reduced to prevent WebGL GPU stalls. Also adds a self-recovery timer that reloads the terminal buffer after client-side data drops, preventing permanent display corruption. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-07 07:00:18 +01:00
arkonandClaude Opus 4.6	3268a12e5e	fix: Operation Lightspeed review fixes — padding, dead code, tablet WebGL - Add SSE padding to backpressure drain write for tunnel clients - Remove dead SessionTerminal from broadcast padding check - Trim whitespace in SSE session filter query params - Remove unused _bufferLazyTerminalData scaffolding code - Skip WebGL on tablets too, not just phones (canvas fallback) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-07 06:40:09 +01:00
arkonandClaude Opus 4.6	1f30ed445c	perf: Operation Lightspeed — 5 parallel performance optimizations 1. Session-scoped SSE subscriptions: server filters events by session ID, clients can subscribe via ?sessions=id1,id2 (backwards-compatible) 2. Lazy xterm.js for subagent windows: terminals created on restore, disposed on minimize — saves ~3.75MB DOM at 50 agents 3. Targeted badge updates: badge count changes update the <span> directly instead of rebuilding the entire session tab sidebar (O(1) vs O(n)) 4. Conditional SSE padding: 8KB Cloudflare padding only on session:terminal and session:needsRefresh, not every event (~70% bandwidth reduction) 5. Canvas renderer on mobile: skip WebGL addon on mobile devices to reduce GPU pressure and prevent context loss on weaker mobile GPUs All 5 implemented in parallel via isolated git worktrees, merged conflict-free. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-07 06:14:16 +01:00
arkonandClaude Opus 4.6	415f02e680	fix: multi-layer backpressure to prevent terminal write freezes Add three layers of protection against oversized terminal.write() calls that freeze Chrome's main thread: 1. SSE entry cap: _onSessionTerminal drops data when total queued bytes (pendingWrites + flickerFilterBuffer) exceeds 128KB. Server sends session:needsRefresh to recover dropped content. 2. Flush cap: flushPendingWrites splits at DEC 2026 sync segment boundaries with 64KB per-frame budget. Excess segments deferred to next requestAnimationFrame. Segment-level splitting preserves Ink redraw atomicity (no flicker). 3. Reduced tail size: initial buffer fetch reduced to 128KB (from 256KB) to limit data volume during tab switch. Re-enable WebGL renderer — root cause was unbounded terminal.write() volume, not the GPU renderer itself. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-06 17:10:25 +01:00
arkon	d5814947d6	chore: version packages	2026-03-05 23:09:24 +01:00
arkonandClaude Opus 4.6	b620511d0e	fix: cap terminal writes at 48KB/frame to prevent page unresponsive freezes Root cause was NOT WebGL — breadcrumbs showed 141KB single-frame terminal.write() calls freezing Chrome for 2+ minutes even with the canvas renderer. During heavy Ink output, multiple SSE terminal events accumulate between animation frames and flush all at once. Fix: split flushPendingWrites at DEC 2026 sync segment boundaries with a 48KB per-frame budget. Each segment is a complete Ink redraw, so splitting between them preserves atomicity (no flicker). Excess segments are deferred to the next requestAnimationFrame. Also re-enable WebGL since it was not the cause — the flush cap protects both renderers equally. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-05 18:36:27 +01:00
arkon	525f02f502	chore: version packages	2026-03-05 17:59:33 +01:00
arkonandClaude Opus 4.6	e07c59477d	fix: disable WebGL renderer to prevent Chrome page unresponsive crashes Root cause: xterm.js WebGL addon performs synchronous GPU ReadPixels calls during terminal.write(). When heavy terminal output floods in (~1MB/4s from active Claude sessions), single-frame writes of 70-105KB block Chrome's main thread for 10+ seconds, triggering "page unresponsive" dialogs. This happens both during tab switches (buffer load + live SSE data competing) and during normal use (Ink redraw bursts). Fix: disable WebGL by default, use canvas renderer instead. Canvas handles the same workloads without GPU stalls. Re-enable with ?webgl URL param for testing. Also: gate live SSE terminal writes during the entire selectSession() buffer load sequence (not just during chunkedTerminalWrite), preventing live data from competing with historical buffer restoration. Crash investigation data (from server-side breadcrumb collection): - 27 flushes totaling 937KB in 4 seconds preceded crash - Two 105KB and one 104KB single-frame flushes observed - Crash occurred when user switched tabs during output flood - Tab froze for 2m54s before recovering - Backend always stable (0 crashes); pure frontend GPU issue Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-05 17:52:28 +01:00
arkonandClaude Opus 4.6	2b8a522cbd	fix: add server-side crash breadcrumbs and remove --drop:console from build The --drop:console esbuild flag was silently stripping all diagnostic console.* calls from production builds, making crash investigation impossible. Remove it temporarily for debugging. Add server-side crash breadcrumb collection: - Frontend writes breadcrumbs to localStorage AND POSTs to /api/crash-diag - Server stores latest breadcrumbs in memory, readable via GET /api/crash-diag - Granular breadcrumbs in selectSession: CACHE_WRITE, FETCH_START, FETCH_DONE, REWRITE, FOCUS, SELECT_DONE - 2s heartbeat beacon so breadcrumbs survive tab freezes - text/plain content-type parser for navigator.sendBeacon compatibility Initial findings from breadcrumbs: - Crash happens during selectSession() for sessions with large buffers - Pattern: cached buffer exists from prior visit + live SSE data arriving - Backend is always stable (0 crashes); this is a pure frontend issue Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-05 16:44:17 +01:00
arkonandClaude Opus 4.6	4abe055182	feat: add frontend crash diagnostics for page unresponsive investigation Add global error handlers, long task detection, WebGL context tracking, and performance timing to identify root cause of intermittent Chrome "page unresponsive" freezes during session switching and typing. Diagnostics: - window error/unhandledrejection handlers ([CRASH-DIAG] prefix) - PerformanceObserver for long tasks (>200ms main thread blocks) - WebGL context loss/restore tracking on all canvases - ?nowebgl URL param to disable WebGL renderer for testing - Timing on flushPendingWrites, chunkedTerminalWrite, selectSession Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-05 12:42:32 +01:00
arkon	15a3b3996b	chore: version packages	2026-03-05 00:28:13 +01:00
arkonandSigurður Guðbrandsson	1b76e6e2e2	fix: prevent Chrome freeze and shell feedback delay from flicker filter Bug 1: Every incoming SSE terminal event reset the 50ms flush timer, not just cursor-up events. During active Claude runs the timer never fired, accumulating MBs in flickerFilterBuffer that froze Chrome on flush. Fix: only reset timer on cursor-up events; add 256KB safety valve. Bug 2: Shell sessions emit cursor-up on every keystroke for readline prompt redraws, triggering the flicker filter and delaying feedback. Fix: skip cursor-up filter for shell mode; disable local echo overlay. Based on PR #31 by @SGudbrandsson. Co-Authored-By: Sigurður Guðbrandsson <SGudbrandsson@users.noreply.github.com>	2026-03-05 00:27:07 +01:00
arkonandClaude Opus 4.6	f8b81b8478	fix: eliminate WebGL re-render flicker during tab switch Stop toggling WebGL renderer off/on around large buffer writes in chunkedTerminalWrite(). The dispose+loadAddon cycle caused visible re-render flashes and (before the deferred fix) synchronous GPU stalls from ReadPixels blocking the main thread. Instead, keep WebGL active and rely on 32KB chunked writes to keep per-frame render work under ~5ms. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-04 16:01:16 +01:00
arkonandClaude Opus 4.6	d79e25d5d8	test: comprehensive CJK wide character test plan for PR #30 Covers all 7 test plan items: Chinese overlap prevention, double-width spacing, Japanese/Korean input, cursor positioning, line wrapping at column boundaries, ASCII regression, and teammate terminal panels. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 13:29:23 +01:00
arkonandClaude Opus 4.6	b1df5319d5	fix: prevent page unresponsive crashes from WebGL GPU stalls during session switch Disable WebGL renderer during large buffer loads (>32KB) and fall back to canvas, which handles bulk ANSI writes without synchronous GPU ReadPixels calls. Re-enable WebGL after the buffer load completes so live terminal streaming still benefits from GPU acceleration. Also reduce chunk size from 128KB to 32KB and use chunked writes for cached buffer restores instead of synchronous terminal.write(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-04 13:18:02 +01:00
arkonandClaude Opus 4.6	fc92d8a8a4	fix: restore CJK wide character support in ZerolagInput overlay (#30 ) Add charCellWidth/stringCellWidth helpers for Unicode-aware width detection, fix makeLine to use for...of iteration with visual column positioning, and fix line splitting in _render to use visual column widths instead of string length. CJK/fullwidth characters now correctly occupy 2 cell widths. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 13:12:30 +01:00
arkonandClaude Opus 4.6	c7cd4f9e17	fix: prevent page unresponsive crashes from WebGL GPU stalls during session switch Reduce terminal chunk size from 128KB to 32KB and use double-RAF between chunks to give the WebGL renderer time to flush GPU operations. Also switch cached buffer restore from direct terminal.write() to chunked writes — the synchronous 256KB write was blocking the main thread for 5+ seconds via synchronous ReadPixels calls. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-04 13:09:10 +01:00
arkonandClaude Opus 4.6	9433de75b8	chore: version packages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-04 12:17:38 +01:00