chore: version packages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/ci.yml

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

.github/workflows/release.yml

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

CHANGELOG.md

@@ -1,5 +1,111 @@
 # aicodeman
 
+## 0.5.3
+
+### Patch Changes
+
+- Readability refactor across 12 core files, extracting ~35 helper methods to reduce duplication:
+  - state-store: extract serializeState(), split assembleStateJson() into focused sub-methods
+  - session: extract \_resetBuffers() (3x dedup), \_clearAllTimers() (10 timer cleanups), \_handleJsonMessage()
+  - ralph-tracker: extract completeAllTodos() (4x dedup), emitValidationWarning(), named similarity constants
+  - subagent-watcher: extract markSubagentAsCompleted(), extractFirstTextContent(), emitToolResult(), findOldestInactiveAgent()
+  - respawn-controller: extract recoveryResetToWatching(), canAutoAccept(), formatRemainingSeconds(), validatePositiveTimeout()
+  - tmux-manager: replace 15 path.includes() with UNSAFE_PATH_CHARS regex, extract buildEnvExports/buildPathExport/\_configureOpenCode helpers
+  - session-auto-ops: extract executeWhenIdle() shared retry helper, convert to options object, add validateThreshold()
+  - app.js: add \_clearTimer() (11 call sites), \_isStaleSelect(), keyboard shortcut lookup table, \_cleanupPreviousSession(), \_resetAllAppState()
+  - route-helpers: add readJsonConfig() (5 inline patterns replaced), validateSessionFilePath() (2 duplicated blocks replaced)
+
+## 0.5.2
+
+### Patch Changes
+
+- Make buffer size limits configurable via CODEMAN\_\* environment variables (MAX_TERMINAL_BUFFER, TRIM_TERMINAL_TO, MAX_TEXT_OUTPUT, TRIM_TEXT_TO, MAX_MESSAGES), falling back to existing defaults. Allows users with fewer sessions or more RAM to tune buffer sizes without patching source.
+
+  Fix duplicate terminal output on tab switch to busy sessions by clearing the terminal before writing the new buffer.
+
+  Fix stale Ink CUP frames after tab switch by sending Ctrl+L to force a clean redraw.
+
+  Fix mobile CJK input handling: resolve textarea positioning, terminal flicker during composition, and layout overflow on small screens. Improve CJK composition lifecycle with better event handling and fallback flush timers.
+
+## 0.5.1
+
+### Patch Changes
+
+- refactor: codebase cleanup — extract route helpers, eliminate boilerplate, optimize hot paths
+  - Add `parseBody()` helper to route-helpers.ts: validates request body against Zod schema with structured 400 error on failure, replacing 37 identical safeParse + error-check blocks across 10 route files
+  - Add `persistAndBroadcastSession()` helper: combines persist + SessionUpdated broadcast into one call, replacing 5 repeated 2-line pairs
+  - Migrate session-routes.ts to use `findSessionOrFail()` consistently (17 inline session lookups replaced) and `parseBody()` (12 patterns)
+  - Migrate ralph-routes.ts to use `findSessionOrFail()` (9 lookups) and `parseBody()` (4 patterns)
+  - Migrate 8 remaining route files to use `parseBody()` (21 patterns total)
+  - Fix O(n log n) eviction in bash-tool-parser.ts: replace `Array.from().sort()[0]` with O(n) min-scan for oldest active tool
+  - Extract `_debouncedCall()` utility in frontend: replaces 4 manual debounce patterns (7 lines each → 1 line) in app.js, panels-ui.js, ralph-panel.js
+  - Net reduction: 208 lines removed across 16 files
+
+## 0.5.0
+
+### Minor Changes
+
+- Visual redesign with glass morphism, refined colors, and polished UI. Optimize history endpoint with buffer reuse and line iterator. Fix Ink frame search window (4KB→64KB) to prevent partial frames. Fix stale terminal data on tab switch via chunkedTerminalWrite cancellation. Improve history prompt extraction with expanded command filtering and tail scan fallback. Align case select group height to match dropdown. Fix no-control-regex lint error for ANSI strip pattern. Add browser-testing-guide to CLAUDE.md references.
+
+## 0.4.7
+
+### Patch Changes
+
+- feat: improve session navigability in history and monitor panel (closes #45)
+  - History items now show the first user prompt as the title with the project path as a subtitle, making it much easier to distinguish sessions from the same project
+  - The `/api/history/sessions` endpoint extracts the first user message from each transcript JSONL, stripping system-injected XML tags and command artifacts, truncating to 120 chars
+  - Monitor panel session rows are now clickable — clicking navigates directly to that session's tab via `selectSession()`; Kill button retains independent behavior via `stopPropagation()`
+  - Updated CLAUDE.md architecture tables to reflect Orchestrator Loop additions (14 route modules, 15 type files, orchestrator domain files, orchestrator-panel.js frontend module)
+  - fix: stop subagent monitor windows from auto-opening on discovery
+  - feat: add Orchestrator Loop with phased plan execution, live progress during plan generation, and toolbar button (hidden until fully tested)
+  - fix: patch 3 production bugs found during deep audit
+  - fix: restore mobile terminal scrollback using JS scrollLines() instead of broken native scroll
+
+## 0.4.6
+
+### Patch Changes
+
+- Fix mobile keyboard scroll and layout issues:
+  - Prevent iOS Safari from scrolling the page when typing with the keyboard open (position:fixed on .app + window.scroll reset)
+  - Eliminate dead space between terminal and keyboard accessory bar by removing redundant CSS padding, tightening JS padding constant, and adding row quantization gap compensation
+  - Fix toolbar overlapping terminal content when keyboard is hidden by adding proper padding-bottom to .main, including iOS Safari bottom bar offset
+  - Strip Ink spinner bloat from terminal buffer before tailing
+  - Fix resolveCasePath priority order and suppress JSON parse warnings
+
+## 0.4.5
+
+### Patch Changes
+
+- Fix mobile keyboard toolbar positioning on iOS Safari: toolbar (Run/Stop/Run Shell) was hidden behind the accessory bar when virtual keyboard was active due to overlapping CSS positions. Remove the aggressive safety check in `updateLayoutForKeyboard()` that incorrectly dismissed keyboard state when iOS scrolled the visual viewport during typing. Add Safari-bar CSS offset to accessory bar so it properly stacks above the toolbar. Remove the double-counted Safari-bar offset when keyboard is visible since the JS transform already covers the full distance.
+
+## 0.4.4
+
+### Patch Changes
+
+- fix: mobile keyboard hides terminal content on iPhone
+
+  Fixed a bug where opening the virtual keyboard on iPhone left zero visible terminal space. Two independent mechanisms were both accounting for the keyboard height: `MobileDetection.updateAppHeight()` shrunk `--app-height` to the visual viewport height, while `KeyboardHandler.updateLayoutForKeyboard()` added a large `paddingBottom`. These double-counted, leaving negative space for the terminal (user saw accessory bar + toolbar but no terminal content).
+
+  Fix: `updateAppHeight()` now skips when the keyboard is visible, and `handleViewportResize()` restores `--app-height` to the pre-keyboard value on first detection (since MobileDetection's listener fires before KeyboardHandler's). On keyboard close, `--app-height` is re-synced to the current visual viewport.
+
+## 0.4.3
+
+### Patch Changes
+
+- Refactor case routes: extract readLinkedCases() and resolveCasePath() helpers to eliminate 6x duplicated linked-cases.json path construction and 5x duplicated file read/parse logic. Replace O(n) .some() duplicate check with O(1) Set.has() in case listing. Un-export unused isError() type guard. Standardize reply.status() to reply.code() in system routes. Update CLAUDE.md frontend module listing and SSE event count.
+
+## 0.4.2
+
+### Patch Changes
+
+- Extract monolithic app.js (~12.5K lines) into 6 focused domain modules that extend CodemanApp.prototype via Object.assign: terminal-ui.js (terminal setup, rendering pipeline, controls), respawn-ui.js (respawn banner, countdown, presets, run summary), ralph-panel.js (Ralph state panel, fix_plan, plan versioning), settings-ui.js (app settings, visibility, web push, tunnel/QR, help), panels-ui.js (subagent panel, teams, insights, file browser, log viewer), session-ui.js (quick start, session options, case settings). Fix critical deferred script init ordering bug: wrap CodemanApp instantiation in DOMContentLoaded so all defer'd mixin modules execute their Object.assign before the constructor runs. Guard missing cleanupWizardDragging() call in subagent-windows.js. Update build.mjs to minify/hash all new modules.
+
+## 0.4.1
+
+### Patch Changes
+
+- Performance optimizations: V8 compile cache for 10-20% faster cold starts, lazy-load WebGL addon (244KB saved on mobile), preload hints for critical scripts, batch tmux reconciliation (N subprocess calls → 1). Also: WebSocket session lifecycle fixes, CJK IME input support, CI upgrade to Node 24/actions v6, install.sh fork support, and CLAUDE.md/README documentation refresh.
+
 ## 0.4.0
 
 ### Minor Changes

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 | Task | Command |
 |------|---------|
-| Dev server | `npx tsx src/index.ts web` |
+| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
 | Type check | `tsc --noEmit` |
 | Lint | `npm run lint` (fix: `npm run lint:fix`) |
 | Format | `npm run format` (check: `npm run format:check`) |
@@ -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.4.0 (must match `package.json`)
+**Version**: 0.5.3 (must match `package.json`)
 
 ## Project Overview
 
@@ -78,7 +78,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | Production start | `npm run start` |
 | Production logs | `journalctl --user -u codeman-web -f` |
 
-**CI**: `.github/workflows/ci.yml` runs `typecheck`, `lint`, `format:check` on push to master (Node 22). Tests excluded (they spawn tmux).
+**CI**: `.github/workflows/ci.yml` runs `typecheck`, `lint`, `format:check` on push to master/main and on PRs (Node 22). Tests excluded (they spawn tmux).
 
 **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/**`.
 
@@ -102,15 +102,16 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Mux** | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` | |
 | **Respawn** | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`) | Read `docs/respawn-state-machine.md` first |
 | **Ralph** | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first |
+| **Orchestrator** | `src/orchestrator-loop.ts`, `src/orchestrator-planner.ts`, `src/orchestrator-verifier.ts` | Read `docs/orchestrator-loop-architecture.md` first |
 | **Agents** | `src/subagent-watcher.ts` ★, `src/team-watcher.ts`, `src/bash-tool-parser.ts`, `src/transcript-watcher.ts` | |
 | **AI** | `src/ai-checker-base.ts`, `src/ai-idle-checker.ts`, `src/ai-plan-checker.ts` | |
 | **Tasks** | `src/task.ts`, `src/task-queue.ts`, `src/task-tracker.ts` | |
 | **State** | `src/state-store.ts`, `src/run-summary.ts`, `src/session-lifecycle-log.ts` | |
 | **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
-| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (12 route modules + barrel), `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
-| **Frontend** | `src/web/public/app.js` ★ (~12.5K lines) + 9 JS modules (incl. `sw.js` service worker) | |
-| **Types** | `src/types/index.ts` → 13 domain files | See `@fileoverview` in index.ts |
+| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (14 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
+| **Frontend** | `src/web/public/app.js` (~2.6K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 4 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`) + `sw.js` | |
+| **Types** | `src/types/index.ts` → 14 domain files | See `@fileoverview` in index.ts |
 
 ★ = Large file (>50KB). All files have `@fileoverview` JSDoc — read that before diving in.
 
@@ -118,7 +119,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Config**: `src/config/` — 9 files. Import from specific files, not barrel.
 
-**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`.
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
 
 ### Data Flow
 
@@ -143,7 +144,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `app.js`(6) → `ralph-wizard.js`(7) → `api-client.js`(8) → `subagent-windows.js`(9).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `settings-ui.js`(10) → `panels-ui.js`(11) → `session-ui.js`(12) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15). `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
 
 **Z-index layers**: subagent windows (1000), plan agents (1100), log viewers (2000), image popups (3000), local echo overlay (7).
 
@@ -166,11 +167,11 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### SSE Event Registry
 
-~100 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
+~106 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
 
 ### API Routes
 
-~111 handlers across 12 route files in `src/web/routes/`: system (35), sessions (24), ralph (9), plan (8), respawn (7), cases (7), files (5), mux (5), scheduled (4), push (4), teams (2), hooks (1). Each file has `@fileoverview` with endpoint details.
+~124 handlers across 14 route files in `src/web/routes/`: system (36), sessions (25), orchestrator (10), ralph (9), plan (8), respawn (7), cases (7), files (5), mux (5), scheduled (4), push (4), teams (2), hooks (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 ## Adding Features
 
@@ -225,7 +226,7 @@ Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: termina
 
 ## References
 
-Deep-dive docs in `docs/`: `respawn-state-machine.md`, `ralph-wiggum-guide.md`, `claude-code-hooks-reference.md`, `terminal-anti-flicker.md`, `opencode-integration.md`, `qr-auth-plan.md`. Agent Teams: `agent-teams/README.md`. SSE events: `src/web/sse-events.ts` + `constants.js`.
+Deep-dive docs in `docs/`: `respawn-state-machine.md`, `ralph-wiggum-guide.md`, `claude-code-hooks-reference.md`, `terminal-anti-flicker.md`, `opencode-integration.md`, `qr-auth-plan.md`, `orchestrator-loop-architecture.md`, `browser-testing-guide.md`. Agent Teams: `agent-teams/README.md`. SSE events: `src/web/sse-events.ts` + `constants.js`.
 
 ## Scripts
 

README.md

@@ -11,7 +11,7 @@
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.5"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
   <img src="https://img.shields.io/badge/Tests-1435%20total-22c55e?style=flat-square" alt="Tests">
 </p>
@@ -499,9 +499,9 @@ The codebase went through a comprehensive 7-phase refactoring that eliminated go
 | Phase | What changed | Impact |
 |-------|-------------|--------|
 | **Performance** | Cached endpoints, SSE adaptive batching, buffer chunking | Sub-16ms terminal latency |
-| **Route extraction** | `server.ts` split into 12 domain route modules + auth middleware + port interfaces | **−60%** server.ts LOC (6,736 → 2,697) |
+| **Route extraction** | `server.ts` split into 13 domain route modules + auth middleware + port interfaces | **−60%** server.ts LOC (6,736 → 2,697) |
 | **Domain splitting** | `types.ts` → 14 domain files, `ralph-tracker` → 7 files, `respawn-controller` → 5 files, `session` → 6 files | No more god files |
-| **Frontend modules** | `app.js` → 8 extracted modules (constants, mobile, voice, notifications, keyboard, API, subagent windows) | **−24%** app.js LOC (15.2K → 11.5K) |
+| **Frontend modules** | `app.js` → 9 extracted modules (constants, mobile, voice, notifications, keyboard, CJK input, API, Ralph wizard, subagent windows) | **−24%** app.js LOC (15.2K → 11.5K) |
 | **Config consolidation** | ~70 scattered magic numbers → 9 domain-focused config files | Zero cross-file duplicates |
 | **Test infrastructure** | Shared mock library, 12 route test files, consolidated MockSession | Testable route handlers via `app.inject()` |
 

docs/orchestrator-loop-architecture.md

@@ -0,0 +1,367 @@
+# Orchestrator Loop — Architecture & Data Flow
+
+> Technical architecture document. Not for GitHub.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          CODEMAN WEB UI                             │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Orchestrator Dashboard                                       │  │
+│  │  [Goal Input] [Plan View] [Phase Progress] [Agent Activity]  │  │
+│  └───────────────────────────┬──────────────────────────────────┘  │
+│                               │ SSE Events                         │
+│                               ▼                                    │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Orchestrator API Routes (/api/orchestrator/*)                │  │
+│  └───────────────────────────┬──────────────────────────────────┘  │
+└───────────────────────────────┼─────────────────────────────────────┘
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      ORCHESTRATOR LOOP                               │
+│                                                                      │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
+│  │ Orchestrator │    │ Orchestrator │    │ Orchestrator         │  │
+│  │ Planner      │    │ Loop (state  │    │ Verifier             │  │
+│  │              │    │ machine)     │    │                      │  │
+│  │ • Research   │◄──►│ • Phase mgmt │◄──►│ • Test runner        │  │
+│  │ • Plan gen   │    │ • Task queue │    │ • AI review          │  │
+│  │ • Phasing    │    │ • Event loop │    │ • Output checks      │  │
+│  └──────┬───────┘    └──────┬───────┘    └──────────┬───────────┘  │
+│         │                   │                       │              │
+│         ▼                   ▼                       ▼              │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │              EXISTING CODEMAN INFRASTRUCTURE                  │  │
+│  │                                                               │  │
+│  │  SessionManager ←→ Sessions ←→ PTY (Claude CLI)              │  │
+│  │       ↑                ↑              ↑                       │  │
+│  │       │                │              │                       │  │
+│  │  TaskQueue      RalphTracker    RespawnController             │  │
+│  │  StateStore     HooksConfig     TeamWatcher                   │  │
+│  │  Auto-Ops       SubagentWatcher SSE Broadcast                 │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow: Complete Lifecycle
+
+### 1. User Submits Goal
+
+```
+User → POST /api/orchestrator/start { goal: "Build a REST API...", config: {...} }
+  → OrchestratorLoop.start(goal)
+    → state = PLANNING
+    → emit('stateChanged', 'planning')
+    → SSE: orchestrator:stateChanged
+```
+
+### 2. Planning Phase
+
+```
+OrchestratorPlanner.generatePlan(goal)
+  → PlanOrchestrator.generateDetailedPlan(goal)
+    → [Research Agent] → enriched task description
+    → [Planner Agent] → PlanItem[]
+  → groupIntoPhases(planItems)
+    → topological sort by dependencies
+    → group into layers
+    → assign team strategies
+  → OrchestratorPlan { phases: [...] }
+  → state = APPROVAL
+  → emit('planReady', plan)
+  → SSE: orchestrator:planReady
+```
+
+### 3. User Approves Plan
+
+```
+User → POST /api/orchestrator/approve
+  → OrchestratorLoop.approvePlan()
+    → state = EXECUTING
+    → executePhase(phases[0])
+```
+
+### 4. Phase Execution
+
+```
+executePhase(phase)
+  → For each task in phase:
+    → Convert to CreateTaskOptions
+    → Add to TaskQueue with completion phrase "PHASE_{N}_TASK_{M}_DONE"
+  → If phase.teamStrategy.type === 'team':
+    → Start session with AGENT_TEAMS enabled
+    → Send team orchestration prompt to lead
+  → Else:
+    → Assign tasks to available sessions (same as RalphLoop)
+
+  → Listen for task completion events:
+    → TaskQueue emits taskCompleted
+    → Check: all phase tasks done?
+      → Yes → state = VERIFYING → verifyPhase(phase)
+      → No → wait for more completions
+```
+
+### 5. Verification
+
+```
+verifyPhase(phase)
+  → OrchestratorVerifier.verify(phase, session)
+    → Run test commands via session
+    → Check file existence
+    → AI review (optional)
+  → If passed:
+    → phase.status = 'passed'
+    → emit('phaseCompleted', phase)
+    → If more phases: executePhase(nextPhase)
+    → If last phase: state = COMPLETED
+  → If failed:
+    → phase.attempts++
+    → If attempts < maxAttempts:
+      → state = REPLANNING
+      → Generate recovery tasks
+      → state = EXECUTING (retry)
+    → Else:
+      → state = FAILED
+      → emit('phaseFailed', phase, reason)
+```
+
+### 6. Context Management Between Phases
+
+```
+After phase completion:
+  → If config.compactBetweenPhases:
+    → session.sendInput('/compact')
+    → Wait for compact to complete
+  → If config.respawnBetweenMilestones && phase is a milestone:
+    → Save orchestrator state to StateStore
+    → Respawn session (kill + recreate)
+    → Send resume prompt with phase context
+```
+
+## File Layout
+
+```
+src/
+├── orchestrator-loop.ts          # Main state machine (~400 lines)
+├── orchestrator-planner.ts       # Plan generation + phase grouping (~300 lines)
+├── orchestrator-verifier.ts      # Phase verification (~200 lines)
+├── types/
+│   └── orchestrator.ts           # All orchestrator types (~150 lines)
+├── prompts/
+│   └── orchestrator.ts           # Prompt templates (~200 lines)
+├── web/
+│   ├── routes/
+│   │   └── orchestrator-routes.ts  # API endpoints (~250 lines)
+│   └── public/
+│       └── orchestrator-ui.js    # Frontend panel (~500 lines)
+```
+
+## Integration Points with Existing Code
+
+### StateStore (`src/state-store.ts`)
+```typescript
+// Add to AppState interface
+orchestrator?: OrchestratorPersistState;
+
+// Add methods
+getOrchestratorState(): OrchestratorPersistState;
+setOrchestratorState(state: Partial<OrchestratorPersistState>): void;
+```
+
+### SSE Events (`src/web/sse-events.ts`)
+```typescript
+// Add ~8 new events
+export const SseEvent = {
+  // ... existing
+  ORCHESTRATOR_STATE_CHANGED: 'orchestrator:stateChanged',
+  ORCHESTRATOR_PLAN_READY: 'orchestrator:planReady',
+  ORCHESTRATOR_PHASE_STARTED: 'orchestrator:phaseStarted',
+  ORCHESTRATOR_PHASE_COMPLETED: 'orchestrator:phaseCompleted',
+  ORCHESTRATOR_PHASE_FAILED: 'orchestrator:phaseFailed',
+  ORCHESTRATOR_VERIFICATION: 'orchestrator:verificationResult',
+  ORCHESTRATOR_COMPLETED: 'orchestrator:completed',
+  ORCHESTRATOR_ERROR: 'orchestrator:error',
+} as const;
+```
+
+### Frontend Constants (`src/web/public/constants.js`)
+```javascript
+// Mirror SSE events
+SSE_EVENTS.ORCHESTRATOR_STATE_CHANGED = 'orchestrator:stateChanged';
+// ... etc
+```
+
+### Route Registration (`src/web/routes/index.ts`)
+```typescript
+import { registerOrchestratorRoutes } from './orchestrator-routes.js';
+// Add to barrel export
+```
+
+### Server (`src/web/server.ts`)
+```typescript
+// Initialize OrchestratorLoop alongside RalphLoop
+const orchestratorLoop = new OrchestratorLoop(config);
+
+// Register routes
+registerOrchestratorRoutes(app, { ...ctx, orchestrator: orchestratorLoop });
+```
+
+### Port Interface (`src/web/ports/`)
+```typescript
+// New port
+export interface OrchestratorPort {
+  orchestrator: OrchestratorLoop;
+}
+```
+
+## Prompt Flow Through System
+
+The key insight is how prompts flow from Orchestrator → Session → Claude:
+
+```
+OrchestratorLoop decides to execute Phase 3, Task 2
+  │
+  ▼
+Converts OrchestratorTask to CreateTaskOptions:
+  {
+    prompt: "Implement the rate limiter middleware. Read src/middleware/auth.ts
+             for the pattern. Add to src/middleware/rate-limiter.ts. Must export
+             a Fastify plugin. When done: <promise>PHASE_3_TASK_2_DONE</promise>",
+    priority: 100,
+    dependencies: ["phase-3-task-1"],  // Must finish auth middleware first
+    completionPhrase: "PHASE_3_TASK_2_DONE",
+    timeoutMs: 600000  // 10 minutes
+  }
+  │
+  ▼
+TaskQueue.addTask(options)
+  │
+  ▼
+RalphLoop.tick() → assignTasks()  // OR OrchestratorLoop does its own assignment
+  │
+  ▼
+session.sendInput(task.prompt)
+  │
+  ▼
+writeViaMux() → tmux send-keys -l "prompt..." + Enter
+  │
+  ▼
+Claude CLI receives prompt, executes, outputs results
+  │
+  ▼
+RalphTracker.processData() → detects "PHASE_3_TASK_2_DONE"
+  │
+  ▼
+emit('completionDetected') → OrchestratorLoop.handleTaskCompleted()
+  │
+  ▼
+Check: all tasks in Phase 3 done? → If yes → verifyPhase(phase3)
+```
+
+## Team Agent Flow (When Enabled)
+
+```
+Phase has teamStrategy.type === 'team'
+  │
+  ▼
+OrchestratorLoop creates/reuses a session with:
+  env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1' }
+  │
+  ▼
+Sends team orchestration prompt:
+  "You're the team lead for Phase 3: Core Implementation.
+
+   Your team should work on these tasks in parallel:
+   1. Rate limiter middleware (teammate 1)
+   2. Error handling middleware (teammate 2)
+   3. Validation layer (teammate 3)
+
+   Context files to read first: [...]
+   Each teammate should output their task's completion phrase when done.
+   When ALL tasks are complete, output: <promise>PHASE_3_COMPLETE</promise>"
+  │
+  ▼
+Claude Code team-lead spawns teammates
+  │
+  ▼
+TeamWatcher detects new team in ~/.claude/teams/
+  → Matches to session via leadSessionId
+  → Tracks teammate activity
+  │
+  ▼
+Teammates work in parallel (in-process threads)
+  │
+  ▼
+hook: teammate_idle → POST /api/hook-event
+  → OrchestratorLoop notes teammate finished
+  │
+  ▼
+hook: task_completed → POST /api/hook-event
+  → Or: RalphTracker detects PHASE_3_COMPLETE
+  → OrchestratorLoop → phase complete → verify
+```
+
+## Error Recovery Strategy
+
+```
+Task fails (timeout, error, session crash)
+  │
+  ├─ Task-level retry (up to 2 retries per task)
+  │   → Reset task to pending
+  │   → Re-queue with modified prompt: "Previous attempt failed: {error}. Try again..."
+  │
+  ├─ Phase-level retry (up to 3 retries per phase)
+  │   → Respawn session (fresh context)
+  │   → Re-execute entire phase with learnings from failure
+  │   → Modified prompt includes what went wrong
+  │
+  └─ Orchestration-level failure
+      → All retries exhausted
+      → state = FAILED
+      → Notify user with detailed failure report
+      → User can: modify plan → retry, skip phase → continue, or stop
+```
+
+## Interaction with Ralph Loop
+
+Ralph Loop and Orchestrator Loop are **mutually exclusive** on the same sessions:
+
+```
+if (orchestratorLoop.isRunning()) {
+  // Orchestrator controls task assignment
+  // Ralph Loop should not interfere
+  // Respawn Controller uses 'orchestrator' preset
+}
+
+if (ralphLoop.isRunning()) {
+  // Ralph controls task assignment
+  // Orchestrator should not start
+}
+```
+
+The Orchestrator can optionally USE the Ralph Loop internally for phase execution (delegate phase tasks to Ralph's queue), or manage task assignment directly. Decision: **manage directly** — gives more control over phase boundaries and verification timing.
+
+## Summary of What Touches What
+
+| Existing File | Change |
+|---|---|
+| `src/types/index.ts` | Export orchestrator types |
+| `src/state-store.ts` | Add orchestrator state persistence |
+| `src/web/sse-events.ts` | Add ~8 orchestrator events |
+| `src/web/routes/index.ts` | Register orchestrator routes |
+| `src/web/server.ts` | Initialize OrchestratorLoop |
+| `src/web/public/constants.js` | Mirror SSE events |
+| `src/web/public/app.js` | Add orchestrator event listeners, panel toggle |
+| `src/web/route-helpers.ts` | Add 'orchestrator' respawn preset |
+
+| New File | Purpose |
+|---|---|
+| `src/orchestrator-loop.ts` | Core state machine |
+| `src/orchestrator-planner.ts` | Plan generation + phasing |
+| `src/orchestrator-verifier.ts` | Phase verification |
+| `src/types/orchestrator.ts` | Type definitions |
+| `src/prompts/orchestrator.ts` | Prompt templates |
+| `src/web/routes/orchestrator-routes.ts` | API endpoints |
+| `src/web/public/orchestrator-ui.js` | Frontend panel |
+| `src/web/ports/orchestrator-port.ts` | Port interface |

docs/orchestrator-loop-plan.md

@@ -0,0 +1,633 @@
+# Orchestrator Loop — Detailed Implementation Plan (v2)
+
+> Internal research/planning document. Not for GitHub.
+
+## Vision
+
+The **Orchestrator Loop** is a new autonomous execution mode that transforms high-level user goals into phased, verified, team-coordinated implementations. Unlike Ralph Loop (flat task queue → idle sessions), the Orchestrator manages the full lifecycle: **plan → approve → execute → verify → adapt → complete**.
+
+```
+USER: "Add OAuth2 login with Google/GitHub, role-based access control, and API key management"
+
+ORCHESTRATOR:
+  Phase 1: Research & Setup      ✅ (3m)  — scaffold, deps, config
+  Phase 2: Auth Core             ✅ (8m)  — OAuth2 flow, session mgmt
+  Phase 3: Provider Integration  🔄 (12m) — Google + GitHub (parallel via team agents)
+  Phase 4: RBAC                  ⏳       — roles, permissions, middleware
+  Phase 5: API Keys              ⏳       — generation, validation, rate limits
+  Phase 6: Testing & Review      ⏳       — integration tests, security review
+
+  Progress: ━━━━━━━━━━━━━━━━━━━━ 40%   |   Agents: 3 active   |   Time: 23m
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    OrchestratorLoop                               │
+│                                                                  │
+│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐  │
+│  │ Orchestrator   │  │ Orchestrator   │  │ Orchestrator     │  │
+│  │ Planner        │  │ Executor       │  │ Verifier         │  │
+│  │                │  │                │  │                  │  │
+│  │ PlanOrchestrator│ │ TaskQueue      │  │ AI review        │  │
+│  │ + phase grouper│  │ SessionManager │  │ Test commands    │  │
+│  │ + team strategy│  │ Team prompts   │  │ File checks      │  │
+│  └───────┬────────┘  └───────┬────────┘  └─────────┬────────┘  │
+│          │                   │                      │           │
+│          └───────────────────┼──────────────────────┘           │
+│                              │                                  │
+│                    ┌─────────▼─────────┐                       │
+│                    │  Existing Codeman  │                       │
+│                    │  Infrastructure    │                       │
+│                    │                    │                       │
+│                    │  SessionManager    │                       │
+│                    │  TaskQueue         │                       │
+│                    │  RespawnController │                       │
+│                    │  TeamWatcher       │                       │
+│                    │  PlanOrchestrator  │                       │
+│                    │  StateStore        │                       │
+│                    │  Hooks + SSE       │                       │
+│                    └────────────────────┘                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## State Machine
+
+```
+                              ┌─────────┐
+                              │  IDLE   │
+                              └────┬────┘
+                                   │ start(goal)
+                                   ▼
+                              ┌─────────┐
+                     ┌────────│PLANNING │────────┐
+                     │ fail   └────┬────┘        │
+                     ▼             │ plan ready   │ user cancels
+                ┌────────┐        ▼              ▼
+                │ FAILED │   ┌─────────┐    ┌────────┐
+                └────────┘   │APPROVAL │    │ IDLE   │
+                     ▲       └────┬────┘    └────────┘
+                     │            │ approve
+                     │            ▼
+                     │       ┌──────────┐
+                     │  ┌───►│EXECUTING │◄────────────────────┐
+                     │  │    └────┬─────┘                     │
+                     │  │         │ all tasks in phase done    │
+                     │  │         ▼                            │
+                     │  │    ┌──────────┐                     │
+                     │  │    │VERIFYING │                     │
+                     │  │    └────┬─────┘                     │
+                     │  │    pass │    │ fail                  │
+                     │  │         ▼    ▼                       │
+                     │  │   more  ┌──────────┐                │
+                     │  │  phases?│REPLANNING│── retry ────────┘
+                     │  │    │    └────┬─────┘
+                     │  │    │         │ max retries
+                     │  │    │         ▼
+                     │  │    │    ┌────────┐
+                     │  └────┘    │ FAILED │
+                     │  next      └────────┘
+                     │  phase
+                     │    │
+                     │    ▼
+                     │ ┌───────────┐
+                     └─│ COMPLETED │
+                       └───────────┘
+```
+
+**States:** `idle` | `planning` | `approval` | `executing` | `verifying` | `replanning` | `completed` | `failed` | `paused`
+
+Transitions are event-driven. The state machine is the single source of truth — all methods check `this.state` before acting.
+
+## Type Definitions
+
+### `src/types/orchestrator.ts`
+
+```typescript
+// ═══════════════════════════════════════════════════════════════
+// State Machine
+// ═══════════════════════════════════════════════════════════════
+
+export type OrchestratorState =
+  | 'idle'
+  | 'planning'
+  | 'approval'
+  | 'executing'
+  | 'verifying'
+  | 'replanning'
+  | 'completed'
+  | 'failed'
+  | 'paused';
+
+// ═══════════════════════════════════════════════════════════════
+// Plan Structure
+// ═══════════════════════════════════════════════════════════════
+
+export interface OrchestratorPlan {
+  id: string;
+  goal: string;
+  createdAt: number;
+  phases: OrchestratorPhase[];
+  metadata: {
+    totalTasks: number;
+    estimatedComplexity: 'low' | 'medium' | 'high';
+    modelUsed: string;
+    planDurationMs: number;
+  };
+}
+
+export interface OrchestratorPhase {
+  id: string;                      // "phase-1", "phase-2"
+  name: string;                    // Human-readable name
+  description: string;
+  order: number;
+  status: PhaseStatus;
+  tasks: OrchestratorTask[];
+  verificationCriteria: string[];
+  testCommands: string[];
+  maxAttempts: number;             // Default: 3
+  attempts: number;                // Current attempt count
+  startedAt: number | null;
+  completedAt: number | null;
+  durationMs: number | null;
+  teamStrategy: TeamStrategy;
+}
+
+export type PhaseStatus =
+  | 'pending'
+  | 'executing'
+  | 'verifying'
+  | 'passed'
+  | 'failed'
+  | 'skipped';
+
+export interface OrchestratorTask {
+  id: string;                      // "phase-1-task-1"
+  phaseId: string;
+  prompt: string;                  // Single-line prompt for Claude
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  assignedSessionId: string | null;
+  queueTaskId: string | null;     // Links to TaskQueue task
+  parallel: boolean;               // Can run in parallel with sibling tasks
+  completionPhrase: string;        // Unique phrase for completion detection
+  timeoutMs: number;
+  startedAt: number | null;
+  completedAt: number | null;
+  error: string | null;
+  retries: number;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Team Strategy
+// ═══════════════════════════════════════════════════════════════
+
+export type TeamStrategy =
+  | { type: 'single' }                          // One session handles all
+  | { type: 'parallel'; maxSessions: number }   // Multiple sessions
+  | { type: 'team'; config: TeamSetup }          // Agent teams
+
+export interface TeamSetup {
+  leadPrompt: string;
+  suggestedTeammates: string[];    // Role descriptions
+  maxTeammates: number;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Verification
+// ═══════════════════════════════════════════════════════════════
+
+export interface VerificationResult {
+  passed: boolean;
+  checks: VerificationCheck[];
+  summary: string;
+  suggestions: string[];           // Recovery hints for replanning
+}
+
+export interface VerificationCheck {
+  type: 'test_command' | 'ai_review' | 'file_check';
+  description: string;
+  passed: boolean;
+  output?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Configuration
+// ═══════════════════════════════════════════════════════════════
+
+export interface OrchestratorConfig {
+  plannerModel: string;            // Default: 'opus'
+  researchEnabled: boolean;        // Default: true
+  autoApprove: boolean;            // Default: false
+  maxPhaseRetries: number;         // Default: 3
+  phaseTimeoutMs: number;          // Default: 1800000 (30min)
+  enableTeamAgents: boolean;       // Default: true
+  maxParallelSessions: number;     // Default: 3
+  verificationMode: 'strict' | 'moderate' | 'lenient';
+  compactBetweenPhases: boolean;   // Default: true
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Persistence (saved to ~/.codeman/state.json)
+// ═══════════════════════════════════════════════════════════════
+
+export interface OrchestratorPersistState {
+  state: OrchestratorState;
+  plan: OrchestratorPlan | null;
+  currentPhaseIndex: number;
+  startedAt: number | null;
+  completedAt: number | null;
+  config: OrchestratorConfig;
+  stats: OrchestratorStats;
+}
+
+export interface OrchestratorStats {
+  phasesCompleted: number;
+  phasesFailed: number;
+  totalTasksCompleted: number;
+  totalTasksFailed: number;
+  totalDurationMs: number;
+  replanCount: number;
+}
+```
+
+## New Files (Implementation Order)
+
+### Step 1: `src/types/orchestrator.ts` — Type definitions
+All interfaces above. No dependencies. ~120 lines.
+
+### Step 2: `src/orchestrator-planner.ts` — Plan generation + phase grouping
+~300 lines. Wraps existing PlanOrchestrator.
+
+```typescript
+/**
+ * @fileoverview Orchestrator plan generation — converts goals into phased plans.
+ *
+ * Uses PlanOrchestrator for AI plan generation, then groups PlanItems into
+ * sequential phases with team strategies and verification criteria.
+ *
+ * @module orchestrator-planner
+ */
+
+export class OrchestratorPlanner {
+  constructor(mux: TerminalMultiplexer, workingDir: string, config: OrchestratorConfig);
+
+  /** Generate plan from goal. Uses PlanOrchestrator internally. */
+  async generatePlan(goal: string, onProgress?: ProgressCallback): Promise<OrchestratorPlan>;
+
+  /** Cancel in-progress plan generation. */
+  async cancel(): Promise<void>;
+
+  // Internal
+  private groupIntoPhases(items: PlanItem[], goal: string): OrchestratorPhase[];
+  private assignTeamStrategies(phases: OrchestratorPhase[]): void;
+  private generateCompletionPhrases(plan: OrchestratorPlan): void;
+}
+```
+
+**Phase grouping algorithm:**
+1. Topological sort by `PlanItem.dependencies`
+2. Group into dependency layers (Kahn's algorithm)
+3. Within each layer, sub-group by `tddPhase` (setup → test → impl → verify → review)
+4. Merge adjacent small phases (< 2 tasks) if they share the same tddPhase
+5. Assign team strategies:
+   - 1-2 tasks → `{ type: 'single' }`
+   - 3+ independent tasks → `{ type: 'parallel', maxSessions: Math.min(taskCount, config.maxParallelSessions) }`
+   - 4+ tasks with high complexity → `{ type: 'team', config: { ... } }`
+6. Generate unique completion phrases per task: `ORCH_P{phaseOrder}_T{taskIndex}`
+
+### Step 3: `src/orchestrator-verifier.ts` — Phase verification
+~200 lines.
+
+```typescript
+/**
+ * @fileoverview Orchestrator phase verification.
+ *
+ * Runs verification checks after each phase completes:
+ * test commands, AI review, and file existence checks.
+ *
+ * @module orchestrator-verifier
+ */
+
+export class OrchestratorVerifier {
+  constructor(config: OrchestratorConfig);
+
+  /** Run all verification checks for a completed phase. */
+  async verifyPhase(
+    phase: OrchestratorPhase,
+    session: Session,
+    mode: 'strict' | 'moderate' | 'lenient'
+  ): Promise<VerificationResult>;
+
+  // Verification strategies
+  private async runTestCommands(commands: string[], session: Session): Promise<VerificationCheck[]>;
+  private async aiReview(phase: OrchestratorPhase, session: Session): Promise<VerificationCheck>;
+}
+```
+
+**Verification modes:**
+- `strict`: ALL test commands must pass AND AI review must approve
+- `moderate`: Test commands must pass, AI review is advisory
+- `lenient`: At least one test command passes, AI review skipped
+
+**AI review prompt (sent as a task to the session):**
+```
+Review Phase "{phase.name}" completion. Check:
+1. Expected functionality works
+2. No obvious regressions
+3. Code quality is acceptable
+
+Criteria: {phase.verificationCriteria.join('\n')}
+
+If ALL criteria are met, respond: ORCH_VERIFY_PASS
+If ANY criteria fail, respond: ORCH_VERIFY_FAIL and explain what failed.
+```
+
+### Step 4: `src/orchestrator-loop.ts` — Core state machine
+~500 lines. Main orchestrator engine.
+
+```typescript
+/**
+ * @fileoverview Orchestrator Loop — phased plan execution with team agents.
+ *
+ * State machine that generates plans from user goals, executes them
+ * phase-by-phase with verification gates, and adapts on failure.
+ *
+ * @module orchestrator-loop
+ */
+
+export interface OrchestratorLoopEvents {
+  stateChanged: (state: OrchestratorState, prevState: OrchestratorState) => void;
+  planReady: (plan: OrchestratorPlan) => void;
+  phaseStarted: (phase: OrchestratorPhase) => void;
+  phaseCompleted: (phase: OrchestratorPhase) => void;
+  phaseFailed: (phase: OrchestratorPhase, reason: string) => void;
+  taskAssigned: (task: OrchestratorTask, sessionId: string) => void;
+  taskCompleted: (task: OrchestratorTask) => void;
+  taskFailed: (task: OrchestratorTask, error: string) => void;
+  verificationResult: (phase: OrchestratorPhase, result: VerificationResult) => void;
+  completed: (stats: OrchestratorStats) => void;
+  error: (error: Error) => void;
+}
+
+export class OrchestratorLoop extends EventEmitter {
+  private state: OrchestratorState = 'idle';
+  private plan: OrchestratorPlan | null = null;
+  private currentPhaseIndex = 0;
+  private config: OrchestratorConfig;
+  private planner: OrchestratorPlanner;
+  private verifier: OrchestratorVerifier;
+  private sessionManager: SessionManager;
+  private taskQueue: TaskQueue;
+  private store: StateStore;
+  private stats: OrchestratorStats;
+  private cleanup: CleanupManager;
+  private pausedState: OrchestratorState | null = null; // State before pause
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  constructor(mux: TerminalMultiplexer, workingDir: string, config?: Partial<OrchestratorConfig>);
+
+  /** Start orchestration with a goal. Transitions: idle → planning */
+  async start(goal: string): Promise<void>;
+
+  /** Approve the generated plan. Transitions: approval → executing */
+  async approve(): Promise<void>;
+
+  /** Reject plan with feedback. Transitions: approval → planning (regenerate) */
+  async reject(feedback: string): Promise<void>;
+
+  /** Pause execution. Saves current state. */
+  pause(): void;
+
+  /** Resume from pause. */
+  resume(): void;
+
+  /** Stop everything and clean up. → idle */
+  async stop(): Promise<void>;
+
+  /** Skip current phase. → executing (next phase) or completed */
+  async skipPhase(phaseId: string): Promise<void>;
+
+  /** Retry a failed phase. → executing */
+  async retryPhase(phaseId: string): Promise<void>;
+
+  // ── Getters ────────────────────────────────────────────────
+
+  getState(): OrchestratorState;
+  getPlan(): OrchestratorPlan | null;
+  getCurrentPhase(): OrchestratorPhase | null;
+  getStats(): OrchestratorStats;
+  getStatus(): OrchestratorPersistState;
+
+  // ── Internal: Phase Execution ──────────────────────────────
+
+  private async executeCurrentPhase(): Promise<void>;
+  private async executePhase(phase: OrchestratorPhase): Promise<void>;
+  private async assignPhaseTasks(phase: OrchestratorPhase): Promise<void>;
+  private handleTaskCompleted(taskId: string): void;
+  private handleTaskFailed(taskId: string, error: string): void;
+  private async onPhaseTasksComplete(phase: OrchestratorPhase): Promise<void>;
+
+  // ── Internal: Verification ─────────────────────────────────
+
+  private async verifyCurrentPhase(): Promise<void>;
+  private async handleVerificationResult(phase: OrchestratorPhase, result: VerificationResult): Promise<void>;
+
+  // ── Internal: Replanning ───────────────────────────────────
+
+  private async replanPhase(phase: OrchestratorPhase, failures: string[]): Promise<void>;
+
+  // ── Internal: State Machine ────────────────────────────────
+
+  private setState(newState: OrchestratorState): void;
+  private advanceToNextPhase(): Promise<void>;
+  private persist(): void;
+  private restore(): void;
+}
+```
+
+**Key execution flow in `executePhase()`:**
+1. Mark phase as `executing`, emit `phaseStarted`
+2. For each task in phase:
+   - Create a `CreateTaskOptions` from `OrchestratorTask`
+   - Add to `TaskQueue` with proper dependencies + completion phrase
+   - Store the TaskQueue task ID in `OrchestratorTask.queueTaskId`
+3. Poll task completion (listen to TaskQueue events)
+4. When all tasks complete → call `onPhaseTasksComplete()`
+5. `onPhaseTasksComplete()` triggers verification
+
+**How tasks get assigned to sessions:**
+The OrchestratorLoop does NOT manage session assignment directly. It adds tasks to the existing TaskQueue and starts a mini poll loop that assigns pending tasks to idle sessions — the same pattern as RalphLoop's `assignTasks()`. This reuses existing session management.
+
+**Team agent flow:**
+For phases with `teamStrategy.type === 'team'`:
+- Start a single session with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+- Instead of adding individual tasks to TaskQueue, send ONE comprehensive prompt to the lead
+- The prompt instructs the lead to create teammates and delegate
+- Monitor via TeamWatcher for team task completion + hook events
+- Phase completion is detected via the lead's completion phrase
+
+### Step 5: `src/web/routes/orchestrator-routes.ts` — API endpoints
+~300 lines.
+
+```
+POST   /api/orchestrator/start          — { goal, config? } → start planning
+POST   /api/orchestrator/approve        — approve generated plan
+POST   /api/orchestrator/reject         — { feedback } → reject + replan
+POST   /api/orchestrator/pause          — pause execution
+POST   /api/orchestrator/resume         — resume execution
+POST   /api/orchestrator/stop           — stop orchestration
+GET    /api/orchestrator/status         — full state + plan + stats
+GET    /api/orchestrator/plan           — plan details only
+POST   /api/orchestrator/phase/:id/skip — skip a phase
+POST   /api/orchestrator/phase/:id/retry — retry a failed phase
+```
+
+Port dependency: `SessionPort & EventPort & RespawnPort & ConfigPort & InfraPort`
+
+The route module receives the OrchestratorLoop instance via the InfraPort (added to `createRouteContext()`).
+
+### Step 6: SSE Events — `src/web/sse-events.ts` additions
+
+```typescript
+// ─── Orchestrator ────────────────────────────────────────────────────────────
+
+/** Orchestrator state machine transitioned. */
+export const OrchestratorStateChanged = 'orchestrator:stateChanged' as const;
+/** Orchestrator plan generated and ready for approval. */
+export const OrchestratorPlanReady = 'orchestrator:planReady' as const;
+/** Orchestrator phase started executing. */
+export const OrchestratorPhaseStarted = 'orchestrator:phaseStarted' as const;
+/** Orchestrator phase completed successfully. */
+export const OrchestratorPhaseCompleted = 'orchestrator:phaseCompleted' as const;
+/** Orchestrator phase failed. */
+export const OrchestratorPhaseFailed = 'orchestrator:phaseFailed' as const;
+/** Orchestrator verification result for a phase. */
+export const OrchestratorVerification = 'orchestrator:verification' as const;
+/** Orchestrator task assigned to session. */
+export const OrchestratorTaskAssigned = 'orchestrator:taskAssigned' as const;
+/** Orchestrator task completed. */
+export const OrchestratorTaskCompleted = 'orchestrator:taskCompleted' as const;
+/** Orchestrator task failed. */
+export const OrchestratorTaskFailed = 'orchestrator:taskFailed' as const;
+/** All phases completed successfully. */
+export const OrchestratorCompleted = 'orchestrator:completed' as const;
+/** Orchestrator error. */
+export const OrchestratorError = 'orchestrator:error' as const;
+```
+
+11 new events. Add to `SseEvent` namespace object + mirror in `constants.js`.
+
+### Step 7: State persistence — `src/state-store.ts` additions
+
+Add to `AppState`:
+```typescript
+orchestrator?: OrchestratorPersistState;
+```
+
+Add methods:
+```typescript
+getOrchestratorState(): OrchestratorPersistState | null;
+setOrchestratorState(state: Partial<OrchestratorPersistState>): void;
+clearOrchestratorState(): void;
+```
+
+### Step 8: Server integration — `src/web/server.ts` modifications
+
+1. Import `OrchestratorLoop` and `registerOrchestratorRoutes`
+2. Add `private orchestratorLoop: OrchestratorLoop` field
+3. Initialize in constructor (lazy — created on first start, not at boot)
+4. Add to `createRouteContext()` InfraPort: `orchestratorLoop: this.orchestratorLoop`
+5. Wire up OrchestratorLoop events → SSE broadcasts
+6. Register routes: `registerOrchestratorRoutes(this.app, ctx)`
+7. Clean up in `stop()`
+
+### Step 9: `src/web/public/orchestrator-ui.js` — Frontend panel
+~500 lines. New frontend module.
+
+**Load order**: After `panels-ui.js` (11), before `ralph-wizard.js` (13). So load order = 11.5.
+
+**UI elements:**
+- Goal input form (text area + config toggles)
+- Plan approval view (phase list, task details, approve/reject buttons)
+- Execution dashboard (progress bar, phase cards, task status indicators)
+- Agent activity panel (session count, team status)
+- Controls (pause, resume, stop, skip phase, retry phase)
+
+**SSE listeners:**
+- All 11 orchestrator events → update UI state
+- Reuses existing session/respawn/team event handlers for agent monitoring
+
+### Step 10: `src/prompts/orchestrator.ts` — Prompt templates
+~200 lines.
+
+Templates for:
+- Phase execution prompt (tells Claude what to do in this phase)
+- Team lead delegation prompt (instructs lead to create and coordinate teammates)
+- Verification prompt (asks Claude to verify phase output)
+- Replan prompt (gives failure context, asks for recovery steps)
+
+### Step 11: Constants, schemas, route barrel updates
+
+- `src/web/public/constants.js` — Add 11 SSE event mirrors
+- `src/web/schemas.ts` — Add Zod schemas for orchestrator API input validation
+- `src/web/routes/index.ts` — Export `registerOrchestratorRoutes`
+- `src/web/ports/infra-port.ts` — Add `orchestratorLoop` to InfraPort
+- `src/types/index.ts` — Export orchestrator types
+
+## Existing File Modifications Summary
+
+| File | Change | Lines |
+|------|--------|-------|
+| `src/types/index.ts` | Add orchestrator barrel export | +1 |
+| `src/web/sse-events.ts` | Add 11 orchestrator events + SseEvent entries | +30 |
+| `src/web/public/constants.js` | Mirror 11 SSE events | +15 |
+| `src/web/routes/index.ts` | Export registerOrchestratorRoutes | +1 |
+| `src/web/ports/infra-port.ts` | Add orchestratorLoop to InfraPort | +3 |
+| `src/web/server.ts` | Initialize OrchestratorLoop, wire events, register routes | +40 |
+| `src/web/schemas.ts` | Add orchestrator Zod schemas | +20 |
+| `src/state-store.ts` | Add orchestrator state persistence | +20 |
+| `src/web/public/app.js` | Add orchestrator SSE listeners + panel toggle | +30 |
+| `src/web/public/index.html` | Add orchestrator-ui.js script tag | +1 |
+
+**Total new code**: ~2,300 lines across 6 new files
+**Total modifications**: ~160 lines across 10 existing files
+
+## Implementation Execution Order
+
+This is the actual build order — each step is a commit checkpoint:
+
+1. **Types** — `src/types/orchestrator.ts` + barrel export. Zero risk, pure types.
+2. **SSE events** — Add all 11 events to both `sse-events.ts` and `constants.js`. Wire in SseEvent namespace.
+3. **State persistence** — Add orchestrator state to StateStore. Small, isolated change.
+4. **Schemas** — Add Zod validation schemas for API input.
+5. **Planner** — `src/orchestrator-planner.ts`. Can test in isolation.
+6. **Verifier** — `src/orchestrator-verifier.ts`. Can test in isolation.
+7. **Core loop** — `src/orchestrator-loop.ts`. The big one. Depends on planner + verifier.
+8. **Prompts** — `src/prompts/orchestrator.ts`. Templates used by core loop.
+9. **Port + routes** — `src/web/ports/infra-port.ts` update + `src/web/routes/orchestrator-routes.ts`.
+10. **Server integration** — Wire OrchestratorLoop into WebServer. Routes become live.
+11. **Frontend** — `src/web/public/orchestrator-ui.js` + app.js listeners + index.html script tag.
+12. **Tests** — `test/orchestrator-*.test.ts`.
+13. **Typecheck + lint** — Fix all issues, ensure CI passes.
+
+## Edge Cases & Error Handling
+
+- **Session limit reached**: Queue tasks and wait for sessions to free up (existing SessionManager handles this)
+- **All sessions crash during phase**: Mark phase as failed, attempt replan
+- **Verification flaky**: `moderate` mode allows test retries; `lenient` skips AI review
+- **Plan too large**: Cap at 10 phases, 50 total tasks. Warn user.
+- **Context overflow**: Auto-compact between phases. Respawn if needed (orchestrator state is external).
+- **User pauses mid-phase**: Pause task assignment, don't cancel running tasks. Resume picks up where it left off.
+- **Network/API errors during planning**: Retry plan generation up to 2 times, then fail with clear message.
+- **Orchestrator vs Ralph conflict**: Mutually exclusive. Starting orchestrator stops Ralph if running. Starting Ralph stops orchestrator.
+
+## Testing Strategy
+
+- **Unit tests**: `test/orchestrator-planner.test.ts` — phase grouping algorithm, team strategy assignment
+- **Unit tests**: `test/orchestrator-verifier.test.ts` — verification logic with mocked sessions
+- **Integration tests**: `test/orchestrator-loop.test.ts` — state machine transitions, task lifecycle
+- **Route tests**: `test/routes/orchestrator-routes.test.ts` — API validation, status responses
+
+All tests use `MockSession` pattern from existing test infrastructure. No real tmux needed.

docs/orchestrator-loop-research.md

@@ -0,0 +1,157 @@
+# Orchestrator Loop — Research Findings
+
+> Research doc for the new "Orchestrator Loop" feature. Not for GitHub.
+
+## What We're Building
+
+A new autonomous loop variant — **Orchestrator Loop** — that takes high-level user tasks, decomposes them into a detailed plan using team agents, and executes the plan step-by-step with quality gates. Unlike Ralph Loop (which executes a flat task queue), the Orchestrator coordinates **planning, delegation, and verification** as a continuous cycle.
+
+**Core idea**: User inputs a goal → Orchestrator creates a detailed plan → spins up team agents for parallel execution → validates each step → adapts the plan based on results → delivers polished output.
+
+## Existing Infrastructure Analysis
+
+### What We Can Reuse
+
+#### 1. Ralph Loop (`src/ralph-loop.ts`)
+- **Pattern**: Poll loop with `start() → tick() → stop()` lifecycle
+- **Reusable**: Event-driven task assignment, session completion handling, timeout management
+- **Limitation**: Flat task queue — no concept of phases, dependencies between task groups, or adaptive replanning
+- **Key insight**: `assignTaskToSession()` uses `session.sendInput(task.prompt)` — simple prompt injection into PTY
+
+#### 2. Task Queue (`src/task-queue.ts`) + Task (`src/task.ts`)
+- **Already has**: Priority ordering, dependency tracking between tasks, completion phrase detection
+- **Limitation**: No task *groups* or *phases*. Dependencies are task-to-task, not phase-to-phase
+- **Key insight**: Tasks support `completionPhrase` — a string the task watches for in output. This is how Ralph knows a task is done
+
+#### 3. Plan Orchestrator (`src/plan-orchestrator.ts`)
+- **Already has**: 2-agent plan generation (Research Agent → Planner Agent), TDD-aware plan items with P0/P1/P2 priorities
+- **Output**: `PlanItem[]` with dependencies, verification criteria, TDD phases, complexity ratings
+- **Limitation**: Plan generation only — no execution. Plans are generated then sit in state/UI for human review
+- **Key insight**: Uses `Session` directly to run Claude subagent instances for research and planning. Returns structured JSON
+
+#### 4. Team Agents (`src/team-watcher.ts`, `~/.claude/teams/`)
+- **Already has**: Team creation, member tracking, filesystem inbox messaging, task management via `~/.claude/tasks/{team-name}/`
+- **Limitation**: Codeman can only *observe* teams (TeamWatcher is read-only polling), not *create* or *orchestrate* them
+- **Key insight**: Teams are a Claude Code feature. Codeman monitors them but doesn't control them. We can't programmatically create teammates — Claude Code does that when you use `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+
+#### 5. Respawn Controller (`src/respawn-controller.ts`)
+- **Already has**: Preset-based automation (ralph-todo, overnight-autonomous), circuit breaker, health scoring
+- **Key insight**: The `ralph-todo` preset (8s idle, 480min max) is designed for autonomous task execution. We'd need a new preset or make Orchestrator Loop set its own timing
+
+#### 6. Session Auto-Ops (`src/session-auto-ops.ts`)
+- **Already has**: Auto-compact at token thresholds, auto-clear for context management
+- **Key insight**: Critical for long Orchestrator runs — prevents context overflow during multi-step execution
+
+#### 7. Hooks (`src/hooks-config.ts`)
+- **Already has**: `idle_prompt`, `stop`, `teammate_idle`, `task_completed` hook events
+- **Key insight**: Hooks fire POST to `/api/hook-event` — this is how Codeman knows when Claude is idle, stopped, or completed a task. The Orchestrator Loop can listen to these same events
+
+### What We Need to Build New
+
+1. **Plan → Task decomposition**: Convert PlanOrchestrator output (PlanItem[]) into executable task groups with phase ordering
+2. **Multi-phase execution engine**: Execute plan phases sequentially, tasks within phases in parallel
+3. **Verification gates**: After each phase, run verification (test commands, AI review) before proceeding
+4. **Adaptive replanning**: When a task fails or verification fails, generate a recovery plan
+5. **Team agent orchestration**: Leverage Claude Code's agent teams for parallel execution within phases
+6. **Progress tracking & UI**: Real-time dashboard showing plan progress, phase status, agent activity
+
+## How Teams Actually Work (Important Constraint)
+
+After deep research, here's the reality of agent teams:
+
+```
+User starts session with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+  → Claude Code creates a team-lead
+  → Team-lead spawns teammates (in-process threads)
+  → Teammates appear as subagents (detected by SubagentWatcher)
+  → Communication via ~/.claude/teams/{name}/inboxes/{member}.json
+  → Tasks tracked in ~/.claude/tasks/{team-name}/{N}.json
+```
+
+**Codeman cannot programmatically create team members.** This is a Claude Code internal feature. However, Codeman CAN:
+- Start a session that has teams enabled
+- Send a prompt to the lead that instructs it to use agent teams
+- Monitor team activity via TeamWatcher
+- React to teammate_idle and task_completed hook events
+- Read team task status from the filesystem
+
+**This means**: The Orchestrator Loop orchestrates at the *session prompt* level, not the *team member* level. We tell the lead what to do, and the lead decides how to use its team.
+
+## Architecture Decision: Prompt-Level Orchestration
+
+Given the team constraint, the Orchestrator Loop works by:
+
+1. **Planning phase**: Use PlanOrchestrator to generate a detailed plan from user input
+2. **Execution phase**: Feed plan steps as prompts to sessions, one phase at a time
+3. **Verification phase**: After each phase, run verification prompts and check results
+4. **Adaptation phase**: If verification fails, generate recovery prompts
+
+The "team agents" aspect works by:
+- Starting sessions with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+- Crafting prompts that *instruct the lead to delegate* to teammates
+- Monitoring team activity to track parallel progress
+- The lead agent is smart enough to decompose work across its team
+
+## Key Technical Findings
+
+### Session Input Mechanics
+```typescript
+// From session.ts - how we send prompts
+await session.sendInput(task.prompt);  // Uses writeViaMux() internally
+// writeViaMux() does: tmux send-keys -l "prompt text" + tmux send-keys Enter
+// CRITICAL: Single-line only! Multi-line breaks Ink rendering
+```
+
+### Completion Detection Chain
+```
+PTY output → RalphTracker.processData() → completion phrase fuzzy match
+  → CompletionConfidence scoring (multi-signal: promise tag + todos + exit signal)
+  → If confident → emit 'completionDetected'
+  → RalphLoop listens → marks task complete → assigns next
+```
+
+### How Plan Items Map to Tasks
+```typescript
+// PlanItem has:
+interface PlanItem {
+  id: string;            // "P0-001"
+  content: string;       // "Implement error handling for API endpoints"
+  priority: 'P0' | 'P1' | 'P2';
+  dependencies: string[]; // ["P0-000"] — other PlanItem IDs
+  verificationCriteria: string;
+  testCommand: string;
+  tddPhase: 'setup' | 'test' | 'impl' | 'verify' | 'review';
+  complexity: 'low' | 'medium' | 'high';
+}
+
+// Task has:
+interface CreateTaskOptions {
+  prompt: string;
+  priority: number;
+  dependencies: string[];  // Task IDs
+  completionPhrase: string;
+  timeoutMs: number;
+}
+
+// Natural mapping: PlanItem.content → Task.prompt
+// PlanItem.dependencies → Task.dependencies
+// PlanItem.priority → Task.priority (P0=100, P1=50, P2=10)
+// PlanItem.verificationCriteria → verification task prompt
+```
+
+### Context Management for Long Runs
+- Auto-compact at ~110k tokens (configurable)
+- Auto-clear at ~140k tokens (configurable)
+- Respawn cycling: kill + restart session to reset context entirely
+- For Orchestrator: we want compact between phases, respawn between major milestones
+
+## Risk Assessment
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| Context overflow during complex phases | High | Auto-compact between tasks, respawn between phases |
+| Team agents not predictable | Medium | Orchestrate at session level, let Claude decide team delegation |
+| Plan too ambitious → infinite loop | High | Phase budgets (max attempts per phase), circuit breaker |
+| Verification too strict → blocks progress | Medium | Configurable strictness, human override via UI |
+| Single-line prompt limit | Medium | Use CLAUDE.md file for complex instructions, prompt references file |
+| Long planning phase delays execution | Low | Show plan for approval before execution |

docs/performance-plan.md

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

package.json

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

scripts/build.mjs

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

scripts/codeman-web.service

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

src/bash-tool-parser.ts

@@ -498,10 +498,17 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
 
           // Enforce max tools limit
           if (this._activeTools.size >= MAX_ACTIVE_TOOLS) {
-            // Remove oldest tool
-            const oldest = Array.from(this._activeTools.entries()).sort((a, b) => a[1].startedAt - b[1].startedAt)[0];
-            if (oldest) {
-              this._activeTools.delete(oldest[0]);
+            // Remove oldest tool (O(n) min-scan instead of O(n log n) sort)
+            let oldestKey: string | undefined;
+            let oldestTime = Infinity;
+            for (const [key, entry] of this._activeTools) {
+              if (entry.startedAt < oldestTime) {
+                oldestTime = entry.startedAt;
+                oldestKey = key;
+              }
+            }
+            if (oldestKey) {
+              this._activeTools.delete(oldestKey);
             }
           }
 

src/config/buffer-limits.ts

@@ -22,14 +22,16 @@
  * Maximum terminal buffer size in characters.
  * Contains raw terminal output with ANSI escape sequences.
  * Reduced from 5MB to 2MB for better render performance.
+ * Override: CODEMAN_MAX_TERMINAL_BUFFER (bytes)
  */
-export const MAX_TERMINAL_BUFFER_SIZE = 2 * 1024 * 1024; // 2MB
+export const MAX_TERMINAL_BUFFER_SIZE = parseInt(process.env.CODEMAN_MAX_TERMINAL_BUFFER || '') || 2 * 1024 * 1024;
 
 /**
  * Size to trim terminal buffer to when max is exceeded.
  * Keeps the most recent portion to preserve context.
+ * Override: CODEMAN_TRIM_TERMINAL_TO (bytes)
  */
-export const TRIM_TERMINAL_TO = 1.5 * 1024 * 1024; // 1.5MB
+export const TRIM_TERMINAL_TO = parseInt(process.env.CODEMAN_TRIM_TERMINAL_TO || '') || 1.5 * 1024 * 1024;
 
 // ============================================================================
 // Text Output Buffer Limits
@@ -38,13 +40,15 @@ export const TRIM_TERMINAL_TO = 1.5 * 1024 * 1024; // 1.5MB
 /**
  * Maximum text output buffer size in characters.
  * Contains ANSI-stripped text for search and analysis.
+ * Override: CODEMAN_MAX_TEXT_OUTPUT (bytes)
  */
-export const MAX_TEXT_OUTPUT_SIZE = 1 * 1024 * 1024; // 1MB
+export const MAX_TEXT_OUTPUT_SIZE = parseInt(process.env.CODEMAN_MAX_TEXT_OUTPUT || '') || 1 * 1024 * 1024;
 
 /**
  * Size to trim text output buffer to when max is exceeded.
+ * Override: CODEMAN_TRIM_TEXT_TO (bytes)
  */
-export const TRIM_TEXT_TO = 768 * 1024; // 768KB
+export const TRIM_TEXT_TO = parseInt(process.env.CODEMAN_TRIM_TEXT_TO || '') || 768 * 1024;
 
 // ============================================================================
 // Message Buffer Limits
@@ -53,8 +57,9 @@ export const TRIM_TEXT_TO = 768 * 1024; // 768KB
 /**
  * Maximum number of Claude JSON messages to keep in memory per session.
  * Older messages are discarded when limit is exceeded.
+ * Override: CODEMAN_MAX_MESSAGES (count)
  */
-export const MAX_MESSAGES = 1000;
+export const MAX_MESSAGES = parseInt(process.env.CODEMAN_MAX_MESSAGES || '') || 1000;
 
 // ============================================================================
 // Line Buffer Limits

src/orchestrator-loop.ts

@@ -0,0 +1,985 @@
+/**
+ * @fileoverview Orchestrator Loop — phased plan execution with team agents.
+ *
+ * State machine that generates plans from user goals, executes them
+ * phase-by-phase with verification gates, and adapts on failure.
+ *
+ * States: idle → planning → approval → executing → verifying → (replanning) → completed/failed
+ *
+ * Key exports:
+ * - `OrchestratorLoop` class — main engine, extends EventEmitter
+ * - `OrchestratorLoopEvents` interface — typed event map
+ *
+ * Lifecycle: `start(goal)` → plan → approve → execute phases → verify → complete
+ *
+ * @dependencies orchestrator-planner (plan generation), orchestrator-verifier (phase verification),
+ *   session-manager (sessions), task-queue (task execution), state-store (persistence),
+ *   prompts/orchestrator (prompt templates)
+ * @consumedby web/server (orchestrator routes, SSE)
+ * @emits stateChanged, planReady, phaseStarted, phaseCompleted, phaseFailed,
+ *   taskAssigned, taskCompleted, taskFailed, verificationResult, completed, error
+ * @persistence Orchestrator state saved to `~/.codeman/state.json` (orchestrator key)
+ *
+ * @module orchestrator-loop
+ */
+
+import { EventEmitter } from 'node:events';
+import { getSessionManager, SessionManager } from './session-manager.js';
+import { getTaskQueue, TaskQueue } from './task-queue.js';
+import { getStore, StateStore } from './state-store.js';
+import { OrchestratorPlanner } from './orchestrator-planner.js';
+import { OrchestratorVerifier } from './orchestrator-verifier.js';
+import { PHASE_EXECUTION_PROMPT, REPLAN_PROMPT, SINGLE_TASK_PROMPT, TEAM_LEAD_PROMPT } from './prompts/index.js';
+import type { TerminalMultiplexer } from './mux-interface.js';
+import type { CreateTaskOptions } from './task.js';
+import {
+  type OrchestratorState,
+  type OrchestratorPlan,
+  type OrchestratorPhase,
+  type OrchestratorTask,
+  type OrchestratorConfig,
+  type OrchestratorStats,
+  type OrchestratorPersistState,
+  type VerificationResult,
+  DEFAULT_ORCHESTRATOR_CONFIG,
+  createInitialOrchestratorStats,
+  getErrorMessage,
+} from './types.js';
+
+// ═══════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════
+
+/** Poll interval for checking task completion within a phase (2 seconds) */
+const PHASE_POLL_INTERVAL_MS = 2000;
+
+/** Delay between phase completion and verification (1 second) */
+const POST_PHASE_DELAY_MS = 1000;
+
+// ═══════════════════════════════════════════════════════════════
+// Events
+// ═══════════════════════════════════════════════════════════════
+
+export interface OrchestratorLoopEvents {
+  stateChanged: (state: OrchestratorState, prevState: OrchestratorState) => void;
+  planProgress: (phase: string, detail: string) => void;
+  planReady: (plan: OrchestratorPlan) => void;
+  phaseStarted: (phase: OrchestratorPhase) => void;
+  phaseCompleted: (phase: OrchestratorPhase) => void;
+  phaseFailed: (phase: OrchestratorPhase, reason: string) => void;
+  taskAssigned: (task: OrchestratorTask, sessionId: string) => void;
+  taskCompleted: (task: OrchestratorTask) => void;
+  taskFailed: (task: OrchestratorTask, error: string) => void;
+  verificationResult: (phase: OrchestratorPhase, result: VerificationResult) => void;
+  completed: (stats: OrchestratorStats) => void;
+  error: (error: Error) => void;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// OrchestratorLoop
+// ═══════════════════════════════════════════════════════════════
+
+export class OrchestratorLoop extends EventEmitter {
+  private _state: OrchestratorState = 'idle';
+  private plan: OrchestratorPlan | null = null;
+  private currentPhaseIndex = 0;
+  private config: OrchestratorConfig;
+  private stats: OrchestratorStats;
+  private startedAt: number | null = null;
+  private completedAt: number | null = null;
+
+  private workingDir: string;
+  private planner: OrchestratorPlanner;
+  private verifier: OrchestratorVerifier;
+  private sessionManager: SessionManager;
+  private taskQueue: TaskQueue;
+  private store: StateStore;
+
+  /** State before pause (to resume to correct state) */
+  private pausedState: OrchestratorState | null = null;
+
+  /** Phase poll timer for checking task completion */
+  private phasePollTimer: NodeJS.Timeout | null = null;
+
+  /** Phase-level timeout timer */
+  private phaseTimeoutTimer: NodeJS.Timeout | null = null;
+
+  /** Post-phase delay timer before verification */
+  private postPhaseTimer: NodeJS.Timeout | null = null;
+
+  /** Session completion listener (bound for cleanup) */
+  private sessionCompletionListener: ((sessionId: string, phrase: string) => void) | null = null;
+
+  /** Active sessions assigned to current phase */
+  private phaseSessionIds: Set<string> = new Set();
+
+  constructor(mux: TerminalMultiplexer, workingDir: string, config?: Partial<OrchestratorConfig>) {
+    super();
+    this.workingDir = workingDir;
+    this.config = { ...DEFAULT_ORCHESTRATOR_CONFIG, ...config };
+    this.stats = createInitialOrchestratorStats();
+    this.sessionManager = getSessionManager();
+    this.taskQueue = getTaskQueue();
+    this.store = getStore();
+    this.planner = new OrchestratorPlanner(mux, workingDir, this.config);
+    this.verifier = new OrchestratorVerifier(this.config);
+
+    // Restore state if crashed while running
+    this.restore();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Public API — Lifecycle
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Start orchestration with a goal. Transitions: idle → planning */
+  async start(goal: string): Promise<void> {
+    if (this._state !== 'idle' && this._state !== 'failed' && this._state !== 'completed') {
+      throw new Error(`Cannot start from state "${this._state}"`);
+    }
+
+    this.reset();
+    this.startedAt = Date.now();
+    this.setState('planning');
+
+    try {
+      const plan = await this.planner.generatePlan(goal, (phase, detail) => {
+        this.emit('planProgress', phase, detail);
+      });
+
+      if (this.currentState() !== 'planning') {
+        // Cancelled during planning
+        return;
+      }
+
+      this.plan = plan;
+      this.persist();
+
+      if (this.config.autoApprove) {
+        this.setState('executing');
+        await this.executeCurrentPhase();
+      } else {
+        this.setState('approval');
+        this.emit('planReady', plan);
+      }
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /** Approve the generated plan. Transitions: approval → executing */
+  async approve(): Promise<void> {
+    this.requireState('approval');
+    if (!this.plan) {
+      throw new Error('No plan to approve');
+    }
+
+    this.setState('executing');
+    await this.executeCurrentPhase();
+  }
+
+  /** Reject plan with feedback. Transitions: approval → planning (regenerate) */
+  async reject(feedback: string): Promise<void> {
+    this.requireState('approval');
+    if (!this.plan) {
+      throw new Error('No plan to reject');
+    }
+
+    const goal = this.plan.goal + '\n\nFeedback on previous plan: ' + feedback;
+    this.plan = null;
+    this.setState('planning');
+
+    try {
+      const plan = await this.planner.generatePlan(goal);
+
+      if ((this._state as OrchestratorState) !== 'planning') return;
+
+      this.plan = plan;
+      this.persist();
+      this.setState('approval');
+      this.emit('planReady', plan);
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /** Pause execution. Saves current state. */
+  pause(): void {
+    if (this._state === 'idle' || this._state === 'paused' || this._state === 'completed' || this._state === 'failed') {
+      return;
+    }
+    this.pausedState = this._state;
+    this.clearPhasePoll();
+    this.cleanupTaskHandlers();
+    this.setState('paused');
+  }
+
+  /** Resume from pause. */
+  async resume(): Promise<void> {
+    if (this._state !== 'paused' || !this.pausedState) {
+      throw new Error('Not paused');
+    }
+
+    const resumeTo = this.pausedState;
+    this.pausedState = null;
+    this.setState(resumeTo);
+
+    // Re-enter the appropriate phase of execution
+    if (resumeTo === 'executing') {
+      await this.executeCurrentPhase();
+    } else if (resumeTo === 'verifying') {
+      await this.verifyCurrentPhase();
+    }
+  }
+
+  /** Stop everything and clean up. */
+  async stop(): Promise<void> {
+    this.clearPhasePoll();
+    this.cleanupTaskHandlers();
+    await this.planner.cancel();
+    this.setState('idle');
+    this.store.clearOrchestratorState();
+  }
+
+  /** Skip a specific phase. */
+  async skipPhase(phaseId: string): Promise<void> {
+    if (!this.plan) return;
+
+    const phase = this.plan.phases.find((p) => p.id === phaseId);
+    if (!phase) throw new Error(`Phase "${phaseId}" not found`);
+
+    phase.status = 'skipped';
+    phase.completedAt = Date.now();
+    this.persist();
+
+    // If this is the current phase, advance
+    if (this.plan.phases[this.currentPhaseIndex]?.id === phaseId) {
+      await this.advanceToNextPhase();
+    }
+  }
+
+  /** Retry a failed phase. */
+  async retryPhase(phaseId: string): Promise<void> {
+    if (!this.plan) return;
+    if (this._state !== 'executing' && this._state !== 'failed') {
+      throw new Error(`Cannot retry from state "${this._state}"`);
+    }
+
+    const phaseIndex = this.plan.phases.findIndex((p) => p.id === phaseId);
+    if (phaseIndex === -1) throw new Error(`Phase "${phaseId}" not found`);
+
+    const phase = this.plan.phases[phaseIndex];
+    phase.status = 'pending';
+    phase.attempts = 0;
+    for (const task of phase.tasks) {
+      task.status = 'pending';
+      task.error = null;
+      task.assignedSessionId = null;
+      task.queueTaskId = null;
+    }
+
+    this.currentPhaseIndex = phaseIndex;
+    this.setState('executing');
+    await this.executeCurrentPhase();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Public API — Getters
+  // ═══════════════════════════════════════════════════════════════
+
+  get state(): OrchestratorState {
+    return this._state;
+  }
+
+  getPlan(): OrchestratorPlan | null {
+    return this.plan;
+  }
+
+  getCurrentPhase(): OrchestratorPhase | null {
+    if (!this.plan) return null;
+    return this.plan.phases[this.currentPhaseIndex] ?? null;
+  }
+
+  getStats(): OrchestratorStats {
+    return { ...this.stats };
+  }
+
+  getStatus(): OrchestratorPersistState {
+    return {
+      state: this._state,
+      plan: this.plan,
+      currentPhaseIndex: this.currentPhaseIndex,
+      startedAt: this.startedAt,
+      completedAt: this.completedAt,
+      config: this.config,
+      stats: this.stats,
+    };
+  }
+
+  isRunning(): boolean {
+    return this._state !== 'idle' && this._state !== 'completed' && this._state !== 'failed';
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — Phase Execution
+  // ═══════════════════════════════════════════════════════════════
+
+  private async executeCurrentPhase(): Promise<void> {
+    if (!this.plan || this._state !== 'executing') return;
+
+    const phase = this.plan.phases[this.currentPhaseIndex];
+    if (!phase) {
+      // All phases done
+      await this.handleCompletion();
+      return;
+    }
+
+    // Skip already completed/skipped phases
+    if (phase.status === 'passed' || phase.status === 'skipped') {
+      await this.advanceToNextPhase();
+      return;
+    }
+
+    phase.status = 'executing';
+    phase.startedAt = Date.now();
+    phase.attempts++;
+    this.persist();
+    this.emit('phaseStarted', phase);
+
+    try {
+      await this.assignPhaseTasks(phase);
+      this.startPhasePoll(phase);
+    } catch (err) {
+      this.handlePhaseError(phase, getErrorMessage(err));
+    }
+  }
+
+  private async assignPhaseTasks(phase: OrchestratorPhase): Promise<void> {
+    // For team strategy, send a single comprehensive prompt to a lead session
+    if (phase.teamStrategy.type === 'team') {
+      await this.assignTeamPhase(phase);
+      return;
+    }
+
+    // For single/parallel strategy, add individual tasks to TaskQueue
+    for (const task of phase.tasks) {
+      if (task.status !== 'pending') continue;
+
+      const prompt = this.buildTaskPrompt(task, phase);
+      const taskOptions: CreateTaskOptions = {
+        prompt,
+        workingDir: this.workingDir,
+        priority: 100 - phase.order, // Earlier phases get higher priority
+        completionPhrase: task.completionPhrase,
+        timeoutMs: Math.min(task.timeoutMs, this.config.phaseTimeoutMs),
+      };
+
+      const queueTask = this.taskQueue.addTask(taskOptions);
+      task.queueTaskId = queueTask.id;
+      task.status = 'running';
+    }
+
+    this.persist();
+    this.setupTaskHandlers();
+
+    // Manually assign tasks to idle sessions
+    await this.assignQueuedTasksToSessions();
+  }
+
+  private async assignTeamPhase(phase: OrchestratorPhase): Promise<void> {
+    const teamConfig = phase.teamStrategy.type === 'team' ? phase.teamStrategy.config : null;
+    if (!teamConfig) return;
+
+    // Find or use an idle session
+    const sessions = this.sessionManager.getIdleSessions();
+    if (sessions.length === 0) {
+      throw new Error('No idle sessions available for team phase execution');
+    }
+
+    const session = sessions[0];
+    this.phaseSessionIds.add(session.id);
+
+    // Mark all tasks as running under this session
+    for (const task of phase.tasks) {
+      task.status = 'running';
+      task.assignedSessionId = session.id;
+    }
+
+    // Build and send the team lead prompt
+    const prompt = TEAM_LEAD_PROMPT.replace('{PHASE_NAME}', phase.name)
+      .replace('{TASK_LIST}', phase.tasks.map((t, i) => `${i + 1}. ${t.prompt}`).join('\n'))
+      .replace('{TEAMMATE_HINTS}', teamConfig.suggestedTeammates.map((h, i) => `${i + 1}. ${h}`).join('\n'))
+      .replace('{COMPLETION_PHRASE}', `${phase.id.toUpperCase()}_COMPLETE`);
+
+    // Create a TaskQueue task for the entire phase
+    const queueTask = this.taskQueue.addTask({
+      prompt,
+      workingDir: this.workingDir,
+      priority: 100 - phase.order,
+      completionPhrase: `${phase.id.toUpperCase()}_COMPLETE`,
+      timeoutMs: this.config.phaseTimeoutMs,
+    });
+
+    // Link all phase tasks to this single queue task
+    for (const task of phase.tasks) {
+      task.queueTaskId = queueTask.id;
+    }
+
+    this.persist();
+    this.setupTaskHandlers();
+
+    // Assign the task to the session
+    try {
+      queueTask.assign(session.id);
+      session.assignTask(queueTask.id);
+      this.taskQueue.updateTask(queueTask);
+      await session.sendInput(prompt);
+    } catch (err) {
+      queueTask.fail(getErrorMessage(err));
+      this.taskQueue.updateTask(queueTask);
+      throw err;
+    }
+  }
+
+  private async assignQueuedTasksToSessions(): Promise<void> {
+    const idleSessions = this.sessionManager.getIdleSessions();
+    const maxSessions =
+      this.getCurrentPhase()?.teamStrategy.type === 'parallel'
+        ? (this.getCurrentPhase()?.teamStrategy as { type: 'parallel'; maxSessions: number }).maxSessions
+        : 1;
+
+    const sessionsToUse = idleSessions.slice(0, maxSessions);
+
+    for (const session of sessionsToUse) {
+      const task = this.taskQueue.next();
+      if (!task) break;
+
+      try {
+        task.assign(session.id);
+        session.assignTask(task.id);
+        this.taskQueue.updateTask(task);
+        await session.sendInput(task.prompt);
+
+        this.phaseSessionIds.add(session.id);
+
+        // Find the orchestrator task linked to this queue task
+        const orchTask = this.findOrchestratorTaskByQueueId(task.id);
+        if (orchTask) {
+          orchTask.assignedSessionId = session.id;
+          orchTask.startedAt = Date.now();
+          this.emit('taskAssigned', orchTask, session.id);
+        }
+      } catch (err) {
+        task.fail(getErrorMessage(err));
+        session.clearTask();
+        this.taskQueue.updateTask(task);
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — Task Completion Tracking
+  // ═══════════════════════════════════════════════════════════════
+
+  private setupTaskHandlers(): void {
+    this.cleanupTaskHandlers();
+
+    this.sessionCompletionListener = (_sessionId: string, _phrase: string) => {
+      // Session completion — check if it's related to our phase tasks
+      this.checkPhaseCompletion();
+    };
+
+    this.sessionManager.on('sessionCompletion', this.sessionCompletionListener);
+  }
+
+  private cleanupTaskHandlers(): void {
+    if (this.sessionCompletionListener) {
+      this.sessionManager.off('sessionCompletion', this.sessionCompletionListener);
+      this.sessionCompletionListener = null;
+    }
+  }
+
+  private handleTaskCompleted(queueTaskId: string): void {
+    const orchTask = this.findOrchestratorTaskByQueueId(queueTaskId);
+    if (!orchTask) return;
+
+    orchTask.status = 'completed';
+    orchTask.completedAt = Date.now();
+    this.stats.totalTasksCompleted++;
+    this.persist();
+    this.emit('taskCompleted', orchTask);
+
+    this.checkPhaseCompletion();
+  }
+
+  private handleTaskFailed(queueTaskId: string, error: string): void {
+    const orchTask = this.findOrchestratorTaskByQueueId(queueTaskId);
+    if (!orchTask) return;
+
+    orchTask.status = 'failed';
+    orchTask.error = error;
+    this.stats.totalTasksFailed++;
+    this.persist();
+    this.emit('taskFailed', orchTask, error);
+
+    // Check if we should retry the task or fail the phase
+    if (orchTask.retries < 2) {
+      orchTask.retries++;
+      orchTask.status = 'pending';
+      orchTask.error = null;
+      orchTask.queueTaskId = null;
+      // Will be re-queued on next poll
+    } else {
+      this.checkPhaseCompletion();
+    }
+  }
+
+  private startPhasePoll(phase: OrchestratorPhase): void {
+    this.clearPhasePoll();
+    this.phasePollTimer = setInterval(() => {
+      if (this._state !== 'executing') {
+        this.clearPhasePoll();
+        return;
+      }
+      this.pollPhaseStatus(phase);
+    }, PHASE_POLL_INTERVAL_MS);
+
+    // Phase-level timeout — fail the phase if it exceeds the configured timeout
+    this.phaseTimeoutTimer = setTimeout(() => {
+      if (this._state === 'executing' && phase.status === 'executing') {
+        console.warn(`[Orchestrator] Phase "${phase.name}" timed out after ${this.config.phaseTimeoutMs}ms`);
+        this.handlePhaseError(phase, `Phase timed out after ${Math.round(this.config.phaseTimeoutMs / 60000)} minutes`);
+      }
+    }, this.config.phaseTimeoutMs);
+  }
+
+  private clearPhasePoll(): void {
+    if (this.phasePollTimer) {
+      clearInterval(this.phasePollTimer);
+      this.phasePollTimer = null;
+    }
+    if (this.phaseTimeoutTimer) {
+      clearTimeout(this.phaseTimeoutTimer);
+      this.phaseTimeoutTimer = null;
+    }
+    if (this.postPhaseTimer) {
+      clearTimeout(this.postPhaseTimer);
+      this.postPhaseTimer = null;
+    }
+  }
+
+  private pollPhaseStatus(phase: OrchestratorPhase): void {
+    // Check for queued tasks that need assignment
+    const pendingTasks = phase.tasks.filter((t) => t.status === 'pending' && !t.queueTaskId);
+    if (pendingTasks.length > 0) {
+      // Re-queue pending tasks
+      for (const task of pendingTasks) {
+        const prompt = this.buildTaskPrompt(task, phase);
+        const queueTask = this.taskQueue.addTask({
+          prompt,
+          workingDir: this.workingDir,
+          priority: 100 - phase.order,
+          completionPhrase: task.completionPhrase,
+          timeoutMs: Math.min(task.timeoutMs, this.config.phaseTimeoutMs),
+        });
+        task.queueTaskId = queueTask.id;
+        task.status = 'running';
+      }
+      this.assignQueuedTasksToSessions().catch(() => {}); // Best effort
+    }
+
+    // Check completion status of queue tasks
+    for (const task of phase.tasks) {
+      if (task.status === 'running' && task.queueTaskId) {
+        const queueTask = this.taskQueue.getTask(task.queueTaskId);
+        if (queueTask) {
+          if (queueTask.isCompleted()) {
+            this.handleTaskCompleted(task.queueTaskId);
+          } else if (queueTask.isFailed()) {
+            this.handleTaskFailed(task.queueTaskId, queueTask.error || 'Task failed');
+          }
+        }
+      }
+    }
+
+    this.checkPhaseCompletion();
+  }
+
+  private checkPhaseCompletion(): void {
+    if (this._state !== 'executing') return;
+
+    const phase = this.getCurrentPhase();
+    if (!phase) return;
+
+    const allDone = phase.tasks.every((t) => t.status === 'completed' || t.status === 'failed');
+    if (!allDone) return;
+
+    const anyFailed = phase.tasks.some((t) => t.status === 'failed');
+
+    this.clearPhasePoll();
+
+    if (anyFailed) {
+      // Phase has failed tasks
+      this.handlePhaseError(phase, 'One or more tasks failed');
+    } else {
+      // All tasks completed — run verification after brief delay
+      this.postPhaseTimer = setTimeout(() => {
+        this.postPhaseTimer = null;
+        this.verifyCurrentPhase().catch((err) => this.handleError(err));
+      }, POST_PHASE_DELAY_MS);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — Verification
+  // ═══════════════════════════════════════════════════════════════
+
+  private async verifyCurrentPhase(): Promise<void> {
+    if (!this.plan) return;
+
+    const phase = this.plan.phases[this.currentPhaseIndex];
+    if (!phase) return;
+
+    // Skip verification if no criteria defined
+    if (phase.verificationCriteria.length === 0 && phase.testCommands.length === 0) {
+      phase.status = 'passed';
+      phase.completedAt = Date.now();
+      phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+      this.stats.phasesCompleted++;
+      this.persist();
+      this.emit('phaseCompleted', phase);
+      await this.advanceToNextPhase();
+      return;
+    }
+
+    this.setState('verifying');
+
+    // Get a session for verification — wait briefly for sessions to become idle
+    let sessions = this.sessionManager.getIdleSessions();
+    if (sessions.length === 0) {
+      // Wait up to 10s for a session to become idle
+      await new Promise((resolve) => setTimeout(resolve, 10_000));
+      sessions = this.sessionManager.getIdleSessions();
+    }
+    if (sessions.length === 0) {
+      // Still no sessions — log warning and skip verification (don't silently pass)
+      console.warn('[Orchestrator] No idle sessions for verification — skipping (marking passed with warning)');
+      phase.status = 'passed';
+      phase.completedAt = Date.now();
+      phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+      this.stats.phasesCompleted++;
+      this.persist();
+      this.emit('phaseCompleted', phase);
+      this.setState('executing');
+      await this.advanceToNextPhase();
+      return;
+    }
+
+    try {
+      const result = await this.verifier.verifyPhase(phase, sessions[0]);
+      this.emit('verificationResult', phase, result);
+
+      if (result.passed) {
+        phase.status = 'passed';
+        phase.completedAt = Date.now();
+        phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+        this.stats.phasesCompleted++;
+        this.persist();
+        this.emit('phaseCompleted', phase);
+        this.setState('executing');
+        await this.advanceToNextPhase();
+      } else {
+        // Verification failed — attempt replan
+        await this.handleVerificationFailure(phase, result);
+      }
+    } catch (err) {
+      // Verification error — treat as pass (don't block on verification bugs)
+      console.warn('[Orchestrator] Verification error, treating as pass:', err);
+      phase.status = 'passed';
+      phase.completedAt = Date.now();
+      phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+      this.stats.phasesCompleted++;
+      this.persist();
+      this.emit('phaseCompleted', phase);
+      this.setState('executing');
+      await this.advanceToNextPhase();
+    }
+  }
+
+  private async handleVerificationFailure(phase: OrchestratorPhase, result: VerificationResult): Promise<void> {
+    if (phase.attempts >= phase.maxAttempts) {
+      // Max retries exceeded
+      phase.status = 'failed';
+      phase.completedAt = Date.now();
+      phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+      this.stats.phasesFailed++;
+      this.persist();
+      this.emit('phaseFailed', phase, `Verification failed after ${phase.attempts} attempts: ${result.summary}`);
+      this.setState('failed');
+      return;
+    }
+
+    // Replan and retry
+    this.stats.replanCount++;
+    this.setState('replanning');
+
+    try {
+      await this.replanPhase(phase, result);
+      // Reset task states for retry
+      for (const task of phase.tasks) {
+        task.status = 'pending';
+        task.error = null;
+        task.assignedSessionId = null;
+        task.queueTaskId = null;
+        task.completedAt = null;
+        task.startedAt = null;
+      }
+      phase.status = 'pending';
+      phase.startedAt = null;
+      this.persist();
+
+      this.setState('executing');
+      await this.executeCurrentPhase();
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  private async replanPhase(phase: OrchestratorPhase, result: VerificationResult): Promise<void> {
+    const completionPhrase = phase.tasks[0]?.completionPhrase || `${phase.id.toUpperCase()}_FIXED`;
+
+    const prompt = REPLAN_PROMPT.replace('{PHASE_NAME}', phase.name)
+      .replace('{ATTEMPT_NUMBER}', String(phase.attempts))
+      .replace('{MAX_ATTEMPTS}', String(phase.maxAttempts))
+      .replace('{FAILURE_SUMMARY}', result.summary)
+      .replace('{SUGGESTIONS}', result.suggestions.join('\n'))
+      .replace('{ORIGINAL_TASKS}', phase.tasks.map((t, i) => `${i + 1}. ${t.prompt}`).join('\n'))
+      .replace('{COMPLETION_PHRASE}', completionPhrase);
+
+    // Create a tracked queue task for the replan (so completion is detected)
+    const queueTask = this.taskQueue.addTask({
+      prompt,
+      workingDir: this.workingDir,
+      priority: 100,
+      completionPhrase,
+      timeoutMs: this.config.phaseTimeoutMs,
+    });
+
+    // Link to first phase task for tracking
+    if (phase.tasks[0]) {
+      phase.tasks[0].queueTaskId = queueTask.id;
+      phase.tasks[0].status = 'running';
+    }
+
+    this.persist();
+
+    // Set up handlers so task completion is tracked
+    this.setupTaskHandlers();
+
+    // Assign to a session
+    const sessions = this.sessionManager.getIdleSessions();
+    if (sessions.length === 0) {
+      console.warn('[Orchestrator] No idle sessions for replan — task queued, will pick up on next poll');
+      // Start polling so the task gets assigned when a session becomes idle
+      this.startPhasePoll(phase);
+      return;
+    }
+
+    try {
+      queueTask.assign(sessions[0].id);
+      sessions[0].assignTask(queueTask.id);
+      this.taskQueue.updateTask(queueTask);
+      await sessions[0].sendInput(prompt);
+    } catch (err) {
+      queueTask.fail(getErrorMessage(err));
+      this.taskQueue.updateTask(queueTask);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — State Machine
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Read current state (bypasses TypeScript narrowing from guards) */
+  private currentState(): OrchestratorState {
+    return this._state;
+  }
+
+  /** Assert state matches expected or throw */
+  private requireState(...expected: OrchestratorState[]): void {
+    if (!expected.includes(this._state)) {
+      throw new Error(`Expected state "${expected.join('|')}", got "${this._state}"`);
+    }
+  }
+
+  private setState(newState: OrchestratorState): void {
+    const prev = this._state;
+    if (prev === newState) return;
+    this._state = newState;
+    this.persist();
+    this.emit('stateChanged', newState, prev);
+  }
+
+  private async advanceToNextPhase(): Promise<void> {
+    this.currentPhaseIndex++;
+    this.phaseSessionIds.clear();
+    this.persist();
+
+    if (!this.plan || this.currentPhaseIndex >= this.plan.phases.length) {
+      await this.handleCompletion();
+    } else {
+      // Compact between phases if configured
+      if (this.config.compactBetweenPhases) {
+        const sessions = this.sessionManager.getIdleSessions();
+        for (const session of sessions) {
+          try {
+            await session.writeViaMux('/compact');
+          } catch {
+            // Best effort
+          }
+        }
+        // Brief delay for compact to take effect
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+      }
+
+      await this.executeCurrentPhase();
+    }
+  }
+
+  private async handleCompletion(): Promise<void> {
+    this.completedAt = Date.now();
+    this.stats.totalDurationMs = this.startedAt ? this.completedAt - this.startedAt : 0;
+    this.clearPhasePoll();
+    this.cleanupTaskHandlers();
+    this.setState('completed');
+    this.emit('completed', this.stats);
+  }
+
+  private handlePhaseError(phase: OrchestratorPhase, error: string): void {
+    if (phase.attempts >= phase.maxAttempts) {
+      phase.status = 'failed';
+      phase.completedAt = Date.now();
+      phase.durationMs = phase.startedAt ? Date.now() - phase.startedAt : null;
+      this.stats.phasesFailed++;
+      this.persist();
+      this.emit('phaseFailed', phase, error);
+      this.setState('failed');
+    } else {
+      // Retry the phase
+      for (const task of phase.tasks) {
+        if (task.status === 'failed') {
+          task.status = 'pending';
+          task.error = null;
+          task.queueTaskId = null;
+          task.assignedSessionId = null;
+        }
+      }
+      phase.status = 'pending';
+      this.persist();
+      this.executeCurrentPhase().catch((err) => this.handleError(err));
+    }
+  }
+
+  private handleError(err: unknown): void {
+    const error = err instanceof Error ? err : new Error(getErrorMessage(err));
+    console.error('[Orchestrator] Error:', error.message);
+    this.setState('failed');
+    this.emit('error', error);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — Persistence
+  // ═══════════════════════════════════════════════════════════════
+
+  private persist(): void {
+    this.store.setOrchestratorState(this.getStatus());
+  }
+
+  private restore(): void {
+    const saved = this.store.getOrchestratorState();
+    if (!saved) return;
+
+    // If we crashed while running, reset to failed
+    if (saved.state === 'executing' || saved.state === 'verifying' || saved.state === 'replanning') {
+      this._state = 'failed';
+      this.plan = saved.plan;
+      this.currentPhaseIndex = saved.currentPhaseIndex;
+      this.startedAt = saved.startedAt;
+      this.config = saved.config;
+      this.stats = saved.stats;
+      this.store.setOrchestratorState({ ...saved, state: 'failed' });
+    } else if (saved.state === 'planning' || saved.state === 'approval') {
+      // Planning/approval — reset to idle (plan is lost)
+      this.store.clearOrchestratorState();
+    } else if (saved.state === 'completed' || saved.state === 'failed') {
+      // Preserve completed/failed state for UI display
+      this._state = saved.state;
+      this.plan = saved.plan;
+      this.currentPhaseIndex = saved.currentPhaseIndex;
+      this.startedAt = saved.startedAt;
+      this.completedAt = saved.completedAt;
+      this.config = saved.config;
+      this.stats = saved.stats;
+    }
+  }
+
+  private reset(): void {
+    this._state = 'idle';
+    this.plan = null;
+    this.currentPhaseIndex = 0;
+    this.startedAt = null;
+    this.completedAt = null;
+    this.stats = createInitialOrchestratorStats();
+    this.pausedState = null;
+    this.phaseSessionIds.clear();
+    this.clearPhasePoll();
+    this.cleanupTaskHandlers();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal — Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private buildTaskPrompt(task: OrchestratorTask, phase: OrchestratorPhase): string {
+    if (phase.tasks.length === 1) {
+      // Single task — use simpler prompt
+      const completedPhases = this.getCompletedPhasesSummary();
+      return SINGLE_TASK_PROMPT.replace('{TASK}', task.prompt)
+        .replace('{GOAL}', this.plan?.goal || '')
+        .replace('{CONTEXT}', completedPhases ? `Previous phases completed: ${completedPhases}` : '')
+        .replace('{COMPLETION_PHRASE}', task.completionPhrase);
+    }
+
+    // Multi-task phase — use full prompt
+    return PHASE_EXECUTION_PROMPT.replace('{PHASE_NAME}', phase.name)
+      .replace('{GOAL}', this.plan?.goal || '')
+      .replace('{COMPLETED_PHASES}', this.getCompletedPhasesSummary() || 'None yet')
+      .replace('{TASK_LIST}', phase.tasks.map((t, i) => `${i + 1}. ${t.prompt}`).join('\n'))
+      .replace('{VERIFICATION_CRITERIA}', phase.verificationCriteria.join('\n') || 'No specific criteria')
+      .replace('{COMPLETION_PHRASE}', task.completionPhrase);
+  }
+
+  private getCompletedPhasesSummary(): string {
+    if (!this.plan) return '';
+    return this.plan.phases
+      .filter((p) => p.status === 'passed' || p.status === 'skipped')
+      .map((p) => `${p.name}: ${p.status}`)
+      .join(', ');
+  }
+
+  private findOrchestratorTaskByQueueId(queueTaskId: string): OrchestratorTask | null {
+    if (!this.plan) return null;
+    for (const phase of this.plan.phases) {
+      for (const task of phase.tasks) {
+        if (task.queueTaskId === queueTaskId) return task;
+      }
+    }
+    return null;
+  }
+
+  /** Clean up resources when the loop is being destroyed. */
+  destroy(): void {
+    this.clearPhasePoll();
+    this.cleanupTaskHandlers();
+  }
+}

src/orchestrator-planner.ts

@@ -0,0 +1,412 @@
+/**
+ * @fileoverview Orchestrator plan generation — converts goals into phased plans.
+ *
+ * Wraps PlanOrchestrator for AI-powered plan generation, then groups the
+ * resulting PlanItems into sequential phases with team strategies and
+ * verification criteria.
+ *
+ * Phase grouping algorithm:
+ * 1. Topological sort by dependencies (Kahn's algorithm)
+ * 2. Group into dependency layers
+ * 3. Sub-group by TDD phase within layers
+ * 4. Merge small adjacent phases
+ * 5. Assign team strategies based on parallelism potential
+ *
+ * Key exports:
+ * - `OrchestratorPlanner` class — plan generation + phase grouping
+ *
+ * @dependencies plan-orchestrator (AI plan generation), types (OrchestratorPlan, PlanItem)
+ * @consumedby orchestrator-loop
+ *
+ * @module orchestrator-planner
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import { PlanOrchestrator, type DetailedPlanResult, type ProgressCallback } from './plan-orchestrator.js';
+import type { TerminalMultiplexer } from './mux-interface.js';
+import type {
+  PlanItem,
+  TddPhase,
+  OrchestratorPlan,
+  OrchestratorPhase,
+  OrchestratorTask,
+  OrchestratorConfig,
+  TeamStrategy,
+  PhaseStatus,
+} from './types.js';
+
+// ═══════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════
+
+/** Maximum number of phases (prevents runaway plans) */
+const MAX_PHASES = 10;
+
+/** Maximum total tasks across all phases */
+const MAX_TOTAL_TASKS = 50;
+
+/** Default task timeout (10 minutes) */
+const DEFAULT_TASK_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** Minimum tasks in a phase before it gets merged with adjacent */
+const MIN_PHASE_TASKS = 2;
+
+/** TDD phase ordering for grouping */
+const TDD_PHASE_ORDER: Record<TddPhase, number> = {
+  setup: 0,
+  test: 1,
+  impl: 2,
+  verify: 3,
+  review: 4,
+};
+
+// ═══════════════════════════════════════════════════════════════
+// OrchestratorPlanner
+// ═══════════════════════════════════════════════════════════════
+
+export class OrchestratorPlanner {
+  private mux: TerminalMultiplexer;
+  private workingDir: string;
+  private config: OrchestratorConfig;
+  private orchestrator: PlanOrchestrator | null = null;
+
+  constructor(mux: TerminalMultiplexer, workingDir: string, config: OrchestratorConfig) {
+    this.mux = mux;
+    this.workingDir = workingDir;
+    this.config = config;
+  }
+
+  /**
+   * Generate a phased plan from a user goal.
+   *
+   * Uses PlanOrchestrator for AI plan generation, then groups results into phases.
+   */
+  async generatePlan(goal: string, onProgress?: ProgressCallback): Promise<OrchestratorPlan> {
+    const startTime = Date.now();
+
+    // Create a PlanOrchestrator for this plan generation
+    this.orchestrator = new PlanOrchestrator(this.mux, this.workingDir, undefined, {
+      defaultModel: this.config.plannerModel,
+    });
+
+    try {
+      onProgress?.('planning', 'Generating detailed plan...');
+
+      const result: DetailedPlanResult = await this.orchestrator.generateDetailedPlan(goal, onProgress);
+
+      if (!result.success || !result.items || result.items.length === 0) {
+        throw new Error(result.error || 'Plan generation returned no items');
+      }
+
+      // Cap total tasks
+      const items = result.items.slice(0, MAX_TOTAL_TASKS);
+
+      onProgress?.('grouping', 'Organizing plan into phases...');
+
+      // Group items into phases
+      const phases = this.groupIntoPhases(items, goal);
+
+      // Assign team strategies
+      this.assignTeamStrategies(phases);
+
+      // Generate unique completion phrases
+      this.generateCompletionPhrases(phases);
+
+      const plan: OrchestratorPlan = {
+        id: uuidv4(),
+        goal,
+        createdAt: Date.now(),
+        phases,
+        metadata: {
+          totalTasks: phases.reduce((sum, p) => sum + p.tasks.length, 0),
+          estimatedComplexity: this.estimateComplexity(items),
+          modelUsed: this.config.plannerModel,
+          planDurationMs: Date.now() - startTime,
+        },
+      };
+
+      return plan;
+    } finally {
+      this.orchestrator = null;
+    }
+  }
+
+  /** Cancel in-progress plan generation. */
+  async cancel(): Promise<void> {
+    if (this.orchestrator) {
+      await this.orchestrator.cancel();
+      this.orchestrator = null;
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Phase Grouping
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Group PlanItems into sequential phases.
+   *
+   * Algorithm:
+   * 1. Build dependency graph and assign IDs to items without them
+   * 2. Topological sort into dependency layers (Kahn's algorithm)
+   * 3. Sub-group within each layer by TDD phase
+   * 4. Merge small phases with their neighbors
+   */
+  private groupIntoPhases(items: PlanItem[], _goal: string): OrchestratorPhase[] {
+    // Ensure all items have IDs
+    const indexedItems = items.map((item, i) => ({
+      ...item,
+      id: item.id || `task-${i}`,
+    }));
+
+    // Build adjacency and in-degree for Kahn's algorithm
+    const idSet = new Set(indexedItems.map((item) => item.id!));
+    const inDegree = new Map<string, number>();
+    const dependents = new Map<string, string[]>(); // id → items that depend on it
+
+    for (const item of indexedItems) {
+      inDegree.set(item.id!, 0);
+      dependents.set(item.id!, []);
+    }
+
+    for (const item of indexedItems) {
+      const deps = (item.dependencies || []).filter((d) => idSet.has(d));
+      inDegree.set(item.id!, deps.length);
+      for (const dep of deps) {
+        dependents.get(dep)!.push(item.id!);
+      }
+    }
+
+    // Kahn's algorithm — produce dependency layers
+    const layers: PlanItem[][] = [];
+    const remaining = new Set(indexedItems.map((item) => item.id!));
+
+    while (remaining.size > 0) {
+      // Find items with no remaining dependencies (in-degree 0)
+      const layer: PlanItem[] = [];
+      for (const id of remaining) {
+        if (inDegree.get(id)! === 0) {
+          layer.push(indexedItems.find((item) => item.id === id)!);
+        }
+      }
+
+      if (layer.length === 0) {
+        // Circular dependency — add all remaining items as a single layer
+        for (const id of remaining) {
+          layer.push(indexedItems.find((item) => item.id === id)!);
+        }
+      }
+
+      layers.push(layer);
+
+      // Remove this layer's items and update in-degrees
+      for (const item of layer) {
+        remaining.delete(item.id!);
+        for (const dep of dependents.get(item.id!) || []) {
+          if (remaining.has(dep)) {
+            inDegree.set(dep, Math.max(0, inDegree.get(dep)! - 1));
+          }
+        }
+      }
+    }
+
+    // Sub-group each layer by TDD phase
+    const rawPhases: PlanItem[][] = [];
+    for (const layer of layers) {
+      const byPhase = new Map<string, PlanItem[]>();
+      for (const item of layer) {
+        const phase = item.tddPhase || 'impl';
+        if (!byPhase.has(phase)) byPhase.set(phase, []);
+        byPhase.get(phase)!.push(item);
+      }
+
+      // Sort sub-groups by TDD phase order
+      const sorted = [...byPhase.entries()].sort(
+        ([a], [b]) => (TDD_PHASE_ORDER[a as TddPhase] ?? 2) - (TDD_PHASE_ORDER[b as TddPhase] ?? 2)
+      );
+
+      for (const [, items] of sorted) {
+        rawPhases.push(items);
+      }
+    }
+
+    // Merge small phases with their previous neighbor
+    const mergedPhases: PlanItem[][] = [];
+    for (const phase of rawPhases) {
+      if (mergedPhases.length > 0 && phase.length < MIN_PHASE_TASKS) {
+        const prev = mergedPhases[mergedPhases.length - 1];
+        if (prev.length < MIN_PHASE_TASKS) {
+          // Merge with previous
+          prev.push(...phase);
+          continue;
+        }
+      }
+      mergedPhases.push([...phase]);
+    }
+
+    // Cap at MAX_PHASES by merging tail phases
+    while (mergedPhases.length > MAX_PHASES) {
+      const last = mergedPhases.pop()!;
+      mergedPhases[mergedPhases.length - 1].push(...last);
+    }
+
+    // Convert to OrchestratorPhase objects
+    return mergedPhases.map((phaseItems, index) => this.createPhase(phaseItems, index));
+  }
+
+  private createPhase(items: PlanItem[], order: number): OrchestratorPhase {
+    // Derive phase name from TDD phases and priorities
+    const tddPhases = [...new Set(items.map((i) => i.tddPhase).filter(Boolean))];
+    const name = this.generatePhaseName(items, tddPhases as TddPhase[], order);
+    const description = items.map((i) => i.content).join('; ');
+
+    const tasks: OrchestratorTask[] = items.map((item, i) => ({
+      id: `phase-${order + 1}-task-${i + 1}`,
+      phaseId: `phase-${order + 1}`,
+      prompt: item.content,
+      status: 'pending' as const,
+      assignedSessionId: null,
+      queueTaskId: null,
+      parallel: items.length > 1, // Tasks within a phase are parallel by default
+      completionPhrase: '', // Assigned later
+      timeoutMs: DEFAULT_TASK_TIMEOUT_MS,
+      startedAt: null,
+      completedAt: null,
+      error: null,
+      retries: 0,
+    }));
+
+    // Extract verification criteria and test commands from items
+    const verificationCriteria = items
+      .map((i) => i.verificationCriteria)
+      .filter((v): v is string => v != null && v.length > 0);
+
+    const testCommands = items.map((i) => i.testCommand).filter((t): t is string => t != null && t.length > 0);
+
+    return {
+      id: `phase-${order + 1}`,
+      name,
+      description,
+      order,
+      status: 'pending' as PhaseStatus,
+      tasks,
+      verificationCriteria,
+      testCommands,
+      maxAttempts: this.config.maxPhaseRetries,
+      attempts: 0,
+      startedAt: null,
+      completedAt: null,
+      durationMs: null,
+      teamStrategy: { type: 'single' }, // Assigned later
+    };
+  }
+
+  private generatePhaseName(items: PlanItem[], tddPhases: TddPhase[], order: number): string {
+    // Try to create a meaningful name based on content
+    const priorities = [...new Set(items.map((i) => i.priority).filter(Boolean))];
+
+    if (tddPhases.length === 1) {
+      const phaseNames: Record<TddPhase, string> = {
+        setup: 'Setup & Configuration',
+        test: 'Test Definition',
+        impl: 'Implementation',
+        verify: 'Verification',
+        review: 'Review & Polish',
+      };
+      return `Phase ${order + 1}: ${phaseNames[tddPhases[0]]}`;
+    }
+
+    if (priorities.includes('P0') && priorities.length === 1) {
+      return `Phase ${order + 1}: Critical Foundation`;
+    }
+
+    return `Phase ${order + 1}: ${items.length > 1 ? 'Parallel Tasks' : items[0].content.slice(0, 50)}`;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Team Strategy Assignment
+  // ═══════════════════════════════════════════════════════════════
+
+  private assignTeamStrategies(phases: OrchestratorPhase[]): void {
+    for (const phase of phases) {
+      phase.teamStrategy = this.computeTeamStrategy(phase);
+    }
+  }
+
+  private computeTeamStrategy(phase: OrchestratorPhase): TeamStrategy {
+    const taskCount = phase.tasks.length;
+    const parallelTasks = phase.tasks.filter((t) => t.parallel).length;
+
+    // Single task or no parallel potential → single session
+    if (taskCount <= 2 || parallelTasks <= 1) {
+      return { type: 'single' };
+    }
+
+    // If team agents are disabled, use parallel sessions instead
+    if (!this.config.enableTeamAgents) {
+      return {
+        type: 'parallel',
+        maxSessions: Math.min(parallelTasks, this.config.maxParallelSessions),
+      };
+    }
+
+    // 4+ parallel tasks with team agents enabled → team mode
+    if (parallelTasks >= 4) {
+      return {
+        type: 'team',
+        config: {
+          leadPrompt: this.buildTeamLeadPrompt(phase),
+          suggestedTeammates: phase.tasks.slice(0, 4).map((t) => `Specialist for: ${t.prompt.slice(0, 80)}`),
+          maxTeammates: Math.min(parallelTasks, 4),
+        },
+      };
+    }
+
+    // 3 parallel tasks → parallel sessions
+    return {
+      type: 'parallel',
+      maxSessions: Math.min(parallelTasks, this.config.maxParallelSessions),
+    };
+  }
+
+  private buildTeamLeadPrompt(phase: OrchestratorPhase): string {
+    const taskList = phase.tasks.map((t, i) => `${i + 1}. ${t.prompt}`).join('\n');
+
+    return [
+      `You are the team lead for "${phase.name}".`,
+      `Create teammates and delegate the following tasks for parallel execution:`,
+      '',
+      taskList,
+      '',
+      `Each teammate should focus on one task area.`,
+      `When all tasks are complete, verify the results and output: <promise>${phase.id.toUpperCase()}_COMPLETE</promise>`,
+    ].join('\n');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Completion Phrases
+  // ═══════════════════════════════════════════════════════════════
+
+  private generateCompletionPhrases(phases: OrchestratorPhase[]): void {
+    for (const phase of phases) {
+      for (const task of phase.tasks) {
+        // Generate a unique, deterministic completion phrase per task
+        task.completionPhrase = `ORCH_P${phase.order + 1}_T${phase.tasks.indexOf(task) + 1}`;
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private estimateComplexity(items: PlanItem[]): 'low' | 'medium' | 'high' {
+    const total = items.length;
+    const highComplexity = items.filter((i) => i.complexity === 'high').length;
+    const p0Count = items.filter((i) => i.priority === 'P0').length;
+
+    if (total > 20 || highComplexity > 5 || p0Count > 8) return 'high';
+    if (total > 10 || highComplexity > 2 || p0Count > 4) return 'medium';
+    return 'low';
+  }
+}

src/orchestrator-verifier.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Orchestrator phase verification.
+ *
+ * Runs verification checks after each phase completes:
+ * - Test commands (shell commands via session)
+ * - AI review (ask Claude to evaluate phase results)
+ *
+ * Three verification modes:
+ * - strict: ALL test commands must pass AND AI review must approve
+ * - moderate: Test commands must pass, AI review is advisory
+ * - lenient: At least one test command passes, AI review skipped
+ *
+ * Key exports:
+ * - `OrchestratorVerifier` class — phase verification engine
+ *
+ * @dependencies types (OrchestratorPhase, VerificationResult, VerificationCheck, OrchestratorConfig)
+ * @consumedby orchestrator-loop
+ *
+ * @module orchestrator-verifier
+ */
+
+import type { Session } from './session.js';
+import type { OrchestratorPhase, OrchestratorConfig, VerificationResult, VerificationCheck } from './types.js';
+
+// ═══════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════
+
+/** Timeout for individual test command execution (2 minutes) */
+const TEST_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
+
+/** Timeout for AI review (3 minutes) */
+const AI_REVIEW_TIMEOUT_MS = 3 * 60 * 1000;
+
+/** Completion phrase for AI verification pass */
+const VERIFY_PASS_PHRASE = 'ORCH_VERIFY_PASS';
+
+/** Completion phrase for AI verification fail */
+const VERIFY_FAIL_PHRASE = 'ORCH_VERIFY_FAIL';
+
+// ═══════════════════════════════════════════════════════════════
+// OrchestratorVerifier
+// ═══════════════════════════════════════════════════════════════
+
+export class OrchestratorVerifier {
+  private config: OrchestratorConfig;
+
+  constructor(config: OrchestratorConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Run all verification checks for a completed phase.
+   *
+   * @param phase - The phase to verify
+   * @param session - Session to use for running commands/reviews
+   * @returns Verification result with pass/fail and suggestions
+   */
+  async verifyPhase(phase: OrchestratorPhase, session: Session): Promise<VerificationResult> {
+    const checks: VerificationCheck[] = [];
+    const mode = this.config.verificationMode;
+
+    // Skip verification entirely in lenient mode with no test commands
+    if (mode === 'lenient' && phase.testCommands.length === 0 && phase.verificationCriteria.length === 0) {
+      return {
+        passed: true,
+        checks: [],
+        summary: 'Verification skipped (lenient mode, no checks defined)',
+        suggestions: [],
+      };
+    }
+
+    // Run test commands if any are defined
+    if (phase.testCommands.length > 0) {
+      const testChecks = await this.runTestCommands(phase.testCommands, session);
+      checks.push(...testChecks);
+    }
+
+    // Run AI review in strict and moderate modes
+    if (mode !== 'lenient' && phase.verificationCriteria.length > 0) {
+      const aiCheck = await this.aiReview(phase, session);
+      checks.push(aiCheck);
+    }
+
+    // Determine pass/fail based on mode
+    const passed = this.evaluateChecks(checks, mode);
+
+    // Generate suggestions for failed checks
+    const suggestions = this.generateSuggestions(checks, phase);
+
+    const passedCount = checks.filter((c) => c.passed).length;
+    const summary =
+      checks.length === 0 ? 'No verification checks defined' : `${passedCount}/${checks.length} checks passed`;
+
+    return { passed, checks, summary, suggestions };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Test Command Execution
+  // ═══════════════════════════════════════════════════════════════
+
+  private async runTestCommands(commands: string[], session: Session): Promise<VerificationCheck[]> {
+    const checks: VerificationCheck[] = [];
+
+    for (const command of commands) {
+      try {
+        const check = await this.runSingleTestCommand(command, session);
+        checks.push(check);
+      } catch (err) {
+        checks.push({
+          type: 'test_command',
+          description: `Run: ${command}`,
+          passed: false,
+          output: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return checks;
+  }
+
+  private async runSingleTestCommand(command: string, session: Session): Promise<VerificationCheck> {
+    // Send the test command to the session and wait for completion
+    // We use a unique marker to detect when the command finishes
+    const marker = `ORCH_TEST_${Date.now()}`;
+    const wrappedCommand = `${command} && echo ${marker}_PASS || echo ${marker}_FAIL`;
+
+    const result = await this.sendAndWaitForMarker(session, wrappedCommand, marker, TEST_COMMAND_TIMEOUT_MS);
+
+    return {
+      type: 'test_command',
+      description: `Run: ${command}`,
+      passed: result.includes(`${marker}_PASS`),
+      output: result.slice(0, 2000), // Truncate output
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // AI Review
+  // ═══════════════════════════════════════════════════════════════
+
+  private async aiReview(phase: OrchestratorPhase, session: Session): Promise<VerificationCheck> {
+    const prompt = this.buildVerificationPrompt(phase);
+
+    try {
+      const result = await this.sendAndWaitForMarker(
+        session,
+        prompt,
+        VERIFY_PASS_PHRASE,
+        AI_REVIEW_TIMEOUT_MS,
+        VERIFY_FAIL_PHRASE
+      );
+
+      const passed = result.includes(VERIFY_PASS_PHRASE);
+
+      return {
+        type: 'ai_review',
+        description: `AI review of "${phase.name}"`,
+        passed,
+        output: result.slice(0, 3000),
+      };
+    } catch (err) {
+      return {
+        type: 'ai_review',
+        description: `AI review of "${phase.name}"`,
+        passed: false,
+        output: `AI review timed out or failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  private buildVerificationPrompt(phase: OrchestratorPhase): string {
+    const criteria = phase.verificationCriteria.map((c, i) => `${i + 1}. ${c}`).join('\n');
+
+    return [
+      `Review the work done in "${phase.name}". Check these criteria:`,
+      '',
+      criteria,
+      '',
+      `If ALL criteria are met, respond with: ${VERIFY_PASS_PHRASE}`,
+      `If ANY criteria fail, respond with: ${VERIFY_FAIL_PHRASE} and explain what failed.`,
+    ].join('\n');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Evaluation
+  // ═══════════════════════════════════════════════════════════════
+
+  private evaluateChecks(checks: VerificationCheck[], mode: OrchestratorConfig['verificationMode']): boolean {
+    if (checks.length === 0) return true;
+
+    const testChecks = checks.filter((c) => c.type === 'test_command');
+    const aiChecks = checks.filter((c) => c.type === 'ai_review');
+
+    switch (mode) {
+      case 'strict':
+        // ALL checks must pass
+        return checks.every((c) => c.passed);
+
+      case 'moderate':
+        // All test commands must pass; AI review is advisory
+        return testChecks.length === 0 || testChecks.every((c) => c.passed);
+
+      case 'lenient':
+        // At least one test passes (AI review skipped in lenient mode)
+        return testChecks.length === 0 || testChecks.some((c) => c.passed);
+
+      default:
+        return aiChecks.every((c) => c.passed) && testChecks.every((c) => c.passed);
+    }
+  }
+
+  private generateSuggestions(checks: VerificationCheck[], phase: OrchestratorPhase): string[] {
+    const suggestions: string[] = [];
+    const failedChecks = checks.filter((c) => !c.passed);
+
+    if (failedChecks.length === 0) return suggestions;
+
+    for (const check of failedChecks) {
+      if (check.type === 'test_command') {
+        suggestions.push(`Fix failing test: ${check.description}`);
+      } else if (check.type === 'ai_review' && check.output) {
+        // Extract failure reasons from AI review output
+        suggestions.push(`Address AI review feedback for "${phase.name}"`);
+      }
+    }
+
+    return suggestions;
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Session Communication
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Send a prompt to a session and wait for a marker phrase in the output.
+   *
+   * @param session - Session to send to
+   * @param input - Prompt/command to send
+   * @param marker - Primary marker to watch for
+   * @param timeoutMs - Maximum wait time
+   * @param altMarker - Alternative marker (for pass/fail detection)
+   * @returns Captured output containing the marker
+   */
+  private sendAndWaitForMarker(
+    session: Session,
+    input: string,
+    marker: string,
+    timeoutMs: number,
+    altMarker?: string
+  ): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      let output = '';
+      let resolved = false;
+
+      const timer = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          cleanup();
+          reject(new Error(`Timeout waiting for marker "${marker}" after ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+
+      const handler = (data: string) => {
+        if (resolved) return;
+        output += data;
+
+        if (output.includes(marker) || (altMarker && output.includes(altMarker))) {
+          resolved = true;
+          cleanup();
+          resolve(output);
+        }
+      };
+
+      const cleanup = () => {
+        clearTimeout(timer);
+        session.off('terminal', handler);
+      };
+
+      session.on('terminal', handler);
+
+      // Send the input
+      session.sendInput(input).catch((err) => {
+        if (!resolved) {
+          resolved = true;
+          cleanup();
+          reject(err);
+        }
+      });
+    });
+  }
+}

src/prompts/index.ts

@@ -7,3 +7,10 @@
 
 export { RESEARCH_AGENT_PROMPT } from './research-agent.js';
 export { PLANNER_PROMPT } from './planner.js';
+export {
+  PHASE_EXECUTION_PROMPT,
+  TEAM_LEAD_PROMPT,
+  VERIFICATION_PROMPT,
+  REPLAN_PROMPT,
+  SINGLE_TASK_PROMPT,
+} from './orchestrator.js';

src/prompts/orchestrator.ts

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Orchestrator Loop prompt templates.
+ *
+ * Templates for phase execution, team delegation, verification, and replanning.
+ * Placeholders use {VARIABLE} syntax and are replaced at runtime.
+ *
+ * @module prompts/orchestrator
+ */
+
+/**
+ * Phase execution prompt — tells Claude what to accomplish in this phase.
+ *
+ * Placeholders:
+ * - {PHASE_NUMBER}: Phase index (1-based)
+ * - {PHASE_NAME}: Human-readable phase name
+ * - {GOAL}: Original user goal
+ * - {COMPLETED_PHASES}: Summary of previously completed phases
+ * - {TASK_LIST}: Numbered task list for this phase
+ * - {VERIFICATION_CRITERIA}: What will be checked after this phase
+ * - {COMPLETION_PHRASE}: The phrase to output when done
+ */
+export const PHASE_EXECUTION_PROMPT = `You are executing {PHASE_NAME} of a larger project.
+
+OVERALL GOAL: {GOAL}
+
+COMPLETED SO FAR:
+{COMPLETED_PHASES}
+
+YOUR TASKS FOR THIS PHASE:
+{TASK_LIST}
+
+Complete each task thoroughly. Run tests after each change to catch issues early.
+
+VERIFICATION (will be checked after you finish):
+{VERIFICATION_CRITERIA}
+
+When ALL tasks in this phase are complete and verified, output: <promise>{COMPLETION_PHRASE}</promise>`;
+
+/**
+ * Team lead delegation prompt — instructs a lead to coordinate teammates.
+ *
+ * Placeholders:
+ * - {PHASE_NAME}: Phase name
+ * - {TASK_LIST}: Numbered task list
+ * - {TEAMMATE_HINTS}: Suggested teammate specializations
+ * - {COMPLETION_PHRASE}: Phrase for when all work is done
+ */
+export const TEAM_LEAD_PROMPT = `You are the team lead for {PHASE_NAME}.
+
+Create teammates and delegate the following tasks for parallel execution:
+
+{TASK_LIST}
+
+Suggested teammate roles:
+{TEAMMATE_HINTS}
+
+Each teammate should focus on their assigned task area. Monitor their progress.
+When ALL tasks are complete and you've verified the results, output: <promise>{COMPLETION_PHRASE}</promise>`;
+
+/**
+ * Verification prompt — asks Claude to verify phase completion.
+ *
+ * Placeholders:
+ * - {PHASE_NAME}: Phase name
+ * - {CRITERIA}: Numbered verification criteria
+ * - {PASS_PHRASE}: Phrase to output on success
+ * - {FAIL_PHRASE}: Phrase to output on failure
+ */
+export const VERIFICATION_PROMPT = `Review the work done in "{PHASE_NAME}". Check these criteria:
+
+{CRITERIA}
+
+If ALL criteria are met, respond with: {PASS_PHRASE}
+If ANY criteria fail, respond with: {FAIL_PHRASE} and explain what failed.`;
+
+/**
+ * Replan prompt — gives failure context and asks for recovery.
+ *
+ * Placeholders:
+ * - {PHASE_NAME}: Phase name
+ * - {ATTEMPT_NUMBER}: Current retry attempt
+ * - {MAX_ATTEMPTS}: Maximum attempts allowed
+ * - {FAILURE_SUMMARY}: What went wrong
+ * - {SUGGESTIONS}: Recovery suggestions from verification
+ * - {ORIGINAL_TASKS}: The original task list
+ * - {COMPLETION_PHRASE}: Phrase for when recovery is done
+ */
+export const REPLAN_PROMPT = `Phase "{PHASE_NAME}" verification failed (attempt {ATTEMPT_NUMBER}/{MAX_ATTEMPTS}).
+
+WHAT WENT WRONG:
+{FAILURE_SUMMARY}
+
+SUGGESTIONS:
+{SUGGESTIONS}
+
+ORIGINAL TASKS:
+{ORIGINAL_TASKS}
+
+Fix the issues identified above. Focus on making the verification criteria pass.
+When the fixes are complete, output: <promise>{COMPLETION_PHRASE}</promise>`;
+
+/**
+ * Single-task execution prompt — for phases with a single task.
+ *
+ * Placeholders:
+ * - {TASK}: The task description
+ * - {GOAL}: Original user goal
+ * - {CONTEXT}: Any relevant context
+ * - {COMPLETION_PHRASE}: Phrase for when done
+ */
+export const SINGLE_TASK_PROMPT = `{TASK}
+
+Context: This is part of a larger project — {GOAL}
+{CONTEXT}
+
+When done, output: <promise>{COMPLETION_PHRASE}</promise>`;

src/ralph-tracker.ts

@@ -100,6 +100,18 @@ const TODO_CLEANUP_INTERVAL_MS = INACTIVITY_TIMEOUT_MS;
  */
 const TODO_SIMILARITY_THRESHOLD = 0.85;
 
+/**
+ * Similarity threshold for short todo content (<30 chars).
+ * Higher threshold reduces false positive deduplication of short strings.
+ */
+const SIMILARITY_THRESHOLD_SHORT = 0.95;
+
+/**
+ * Similarity threshold for medium-length todo content (30-60 chars).
+ * Slightly relaxed compared to short strings.
+ */
+const SIMILARITY_THRESHOLD_MEDIUM = 0.9;
+
 /**
  * Debounce interval for event emissions (milliseconds).
  * Prevents UI jitter from rapid consecutive updates.
@@ -1299,6 +1311,24 @@ export class RalphTracker extends EventEmitter {
     this.detectTodoItems(trimmed);
   }
 
+  /**
+   * Mark all tracked todos as completed and emit todoUpdate if any changed.
+   * @returns true if any todo was updated
+   */
+  private completeAllTodos(): boolean {
+    let updated = false;
+    for (const todo of this._todos.values()) {
+      if (todo.status !== 'completed') {
+        todo.status = 'completed';
+        updated = true;
+      }
+    }
+    if (updated) {
+      this.emit('todoUpdate', this.todos);
+    }
+    return updated;
+  }
+
   /**
    * Detect "all tasks complete" messages.
    */
@@ -1318,16 +1348,7 @@ export class RalphTracker extends EventEmitter {
       return;
     }
 
-    let updated = false;
-    for (const todo of this._todos.values()) {
-      if (todo.status !== 'completed') {
-        todo.status = 'completed';
-        updated = true;
-      }
-    }
-    if (updated) {
-      this.emit('todoUpdate', this.todos);
-    }
+    this.completeAllTodos();
 
     if (this._loopState.completionPhrase) {
       this._loopState.active = false;
@@ -1425,16 +1446,7 @@ export class RalphTracker extends EventEmitter {
 
     if (bareCount > 1) return;
 
-    let updated = false;
-    for (const todo of this._todos.values()) {
-      if (todo.status !== 'completed') {
-        todo.status = 'completed';
-        updated = true;
-      }
-    }
-    if (updated) {
-      this.emit('todoUpdate', this.todos);
-    }
+    this.completeAllTodos();
 
     this._loopState.active = false;
     this._loopState.lastActivity = Date.now();
@@ -1480,16 +1492,7 @@ export class RalphTracker extends EventEmitter {
       if (canonicalCount >= 2 || this._loopState.active) {
         this._loopState.active = false;
         this._loopState.lastActivity = Date.now();
-        let updated = false;
-        for (const todo of this._todos.values()) {
-          if (todo.status !== 'completed') {
-            todo.status = 'completed';
-            updated = true;
-          }
-        }
-        if (updated) {
-          this.emit('todoUpdate', this.todos);
-        }
+        this.completeAllTodos();
         this.emit('completionDetected', matchedPhrase);
         this.emit('loopUpdate', this.loopState);
         return;
@@ -1497,16 +1500,7 @@ export class RalphTracker extends EventEmitter {
     }
 
     if (this._loopState.active || count >= 2) {
-      let updated = false;
-      for (const todo of this._todos.values()) {
-        if (todo.status !== 'completed') {
-          todo.status = 'completed';
-          updated = true;
-        }
-      }
-      if (updated) {
-        this.emit('todoUpdate', this.todos);
-      }
+      this.completeAllTodos();
 
       this._loopState.active = false;
       this._loopState.lastActivity = Date.now();
@@ -1532,41 +1526,39 @@ export class RalphTracker extends EventEmitter {
     const suggestedPhrase = `${phrase}_${uniqueSuffix}`;
 
     if (COMMON_COMPLETION_PHRASES.has(normalized)) {
-      console.warn(
-        `[RalphTracker] Warning: Completion phrase "${phrase}" is very common and may cause false positives. Consider using: "${suggestedPhrase}"`
-      );
-      this.emit('phraseValidationWarning', {
-        phrase,
-        reason: 'common',
-        suggestedPhrase,
-      });
+      this.emitValidationWarning(phrase, 'common', suggestedPhrase);
       return;
     }
 
     if (normalized.length < MIN_RECOMMENDED_PHRASE_LENGTH) {
-      console.warn(
-        `[RalphTracker] Warning: Completion phrase "${phrase}" is too short (${normalized.length} chars). Consider using: "${suggestedPhrase}"`
-      );
-      this.emit('phraseValidationWarning', {
-        phrase,
-        reason: 'short',
-        suggestedPhrase,
-      });
+      this.emitValidationWarning(phrase, 'short', suggestedPhrase);
       return;
     }
 
     if (/^\d+$/.test(normalized)) {
-      console.warn(
-        `[RalphTracker] Warning: Completion phrase "${phrase}" is numeric-only and may cause false positives. Consider using: "${suggestedPhrase}"`
-      );
-      this.emit('phraseValidationWarning', {
-        phrase,
-        reason: 'numeric',
-        suggestedPhrase,
-      });
+      this.emitValidationWarning(phrase, 'numeric', suggestedPhrase);
     }
   }
 
+  /**
+   * Emit a phrase validation warning with a console message and event.
+   */
+  private emitValidationWarning(phrase: string, reason: 'common' | 'short' | 'numeric', suggestedPhrase: string): void {
+    const descriptions: Record<'common' | 'short' | 'numeric', string> = {
+      common: 'is very common and may cause false positives',
+      short: `is too short (${phrase.toUpperCase().replace(/[\s_\-.]+/g, '').length} chars)`,
+      numeric: 'is numeric-only and may cause false positives',
+    };
+    console.warn(
+      `[RalphTracker] Warning: Completion phrase "${phrase}" ${descriptions[reason]}. Consider using: "${suggestedPhrase}"`
+    );
+    this.emit('phraseValidationWarning', {
+      phrase,
+      reason,
+      suggestedPhrase,
+    });
+  }
+
   /**
    * Activate the loop if not already active.
    */
@@ -1977,9 +1969,9 @@ export class RalphTracker extends EventEmitter {
 
     let threshold: number;
     if (normalized.length < 30) {
-      threshold = 0.95;
+      threshold = SIMILARITY_THRESHOLD_SHORT;
     } else if (normalized.length < 60) {
-      threshold = 0.9;
+      threshold = SIMILARITY_THRESHOLD_MEDIUM;
     } else {
       threshold = TODO_SIMILARITY_THRESHOLD;
     }

src/respawn-controller.ts

@@ -551,6 +551,14 @@ export interface RespawnEvents {
   respawnBlocked: (data: { reason: string; details: string }) => void;
 }
 
+/**
+ * Convert milliseconds to a non-negative whole number of seconds for countdown display.
+ * Rounds up so that e.g. 1200 ms shows as 2 s (never under-reports remaining time).
+ */
+function formatRemainingSeconds(ms: number): number {
+  return Math.max(0, Math.ceil(ms / 1000));
+}
+
 /** Default configuration values */
 const DEFAULT_CONFIG: RespawnConfig = {
   idleTimeoutMs: 10000, // 10 seconds of no activity after prompt (legacy, still used as fallback)
@@ -839,12 +847,25 @@ export class RespawnController extends EventEmitter {
   private validateConfig(): void {
     const c = this.config;
 
+    /**
+     * Validate that a timeout value is positive (or non-negative when allowZero is true).
+     * Falls back to the DEFAULT_CONFIG value if invalid.
+     */
+    const validatePositiveTimeout = (field: keyof RespawnConfig, allowZero = false): void => {
+      const value = c[field] as number;
+      const invalid = allowZero ? value < 0 : value <= 0;
+      if (invalid) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (c as any)[field] = DEFAULT_CONFIG[field];
+      }
+    };
+
     // Ensure timeouts are positive
-    if (c.idleTimeoutMs <= 0) c.idleTimeoutMs = DEFAULT_CONFIG.idleTimeoutMs;
-    if (c.completionConfirmMs <= 0) c.completionConfirmMs = DEFAULT_CONFIG.completionConfirmMs;
-    if (c.noOutputTimeoutMs <= 0) c.noOutputTimeoutMs = DEFAULT_CONFIG.noOutputTimeoutMs;
-    if (c.autoAcceptDelayMs < 0) c.autoAcceptDelayMs = DEFAULT_CONFIG.autoAcceptDelayMs;
-    if (c.interStepDelayMs <= 0) c.interStepDelayMs = DEFAULT_CONFIG.interStepDelayMs;
+    validatePositiveTimeout('idleTimeoutMs');
+    validatePositiveTimeout('completionConfirmMs');
+    validatePositiveTimeout('noOutputTimeoutMs');
+    validatePositiveTimeout('autoAcceptDelayMs', true);
+    validatePositiveTimeout('interStepDelayMs');
 
     // Ensure completion confirm doesn't exceed no-output timeout
     if (c.completionConfirmMs > c.noOutputTimeoutMs) {
@@ -852,14 +873,14 @@ export class RespawnController extends EventEmitter {
     }
 
     // Ensure AI check timeouts are positive
-    if (c.aiIdleCheckTimeoutMs <= 0) c.aiIdleCheckTimeoutMs = DEFAULT_CONFIG.aiIdleCheckTimeoutMs;
-    if (c.aiIdleCheckCooldownMs < 0) c.aiIdleCheckCooldownMs = DEFAULT_CONFIG.aiIdleCheckCooldownMs;
-    if (c.aiIdleCheckMaxContext <= 0) c.aiIdleCheckMaxContext = DEFAULT_CONFIG.aiIdleCheckMaxContext;
+    validatePositiveTimeout('aiIdleCheckTimeoutMs');
+    validatePositiveTimeout('aiIdleCheckCooldownMs', true);
+    validatePositiveTimeout('aiIdleCheckMaxContext');
 
     // Ensure plan check timeouts are positive
-    if (c.aiPlanCheckTimeoutMs <= 0) c.aiPlanCheckTimeoutMs = DEFAULT_CONFIG.aiPlanCheckTimeoutMs;
-    if (c.aiPlanCheckCooldownMs < 0) c.aiPlanCheckCooldownMs = DEFAULT_CONFIG.aiPlanCheckCooldownMs;
-    if (c.aiPlanCheckMaxContext <= 0) c.aiPlanCheckMaxContext = DEFAULT_CONFIG.aiPlanCheckMaxContext;
+    validatePositiveTimeout('aiPlanCheckTimeoutMs');
+    validatePositiveTimeout('aiPlanCheckCooldownMs', true);
+    validatePositiveTimeout('aiPlanCheckMaxContext');
   }
 
   /** Wire up AI checker events to controller events (removes existing listeners first to prevent duplicates) */
@@ -987,11 +1008,11 @@ export class RespawnController extends EventEmitter {
       waitingFor = 'AI verdict (IDLE or WORKING)';
     } else if (this._state === 'confirming_idle') {
       statusText = `Confirming idle (${confidence}% confidence)`;
-      waitingFor = `${Math.max(0, Math.ceil((this.config.completionConfirmMs - msSinceLastOutput) / 1000))}s more silence`;
+      waitingFor = `${formatRemainingSeconds(this.config.completionConfirmMs - msSinceLastOutput)}s more silence`;
     } else if (this._state === 'watching') {
       const aiState = this.aiChecker.getState();
       if (aiState.status === 'cooldown') {
-        const remaining = Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000);
+        const remaining = formatRemainingSeconds(this.aiChecker.getCooldownRemainingMs());
         statusText = `AI Check: WORKING (cooldown ${remaining}s)`;
         waitingFor = 'Cooldown to expire';
       } else if (completionMessageDetected) {
@@ -1798,24 +1819,28 @@ export class RespawnController extends EventEmitter {
       case 'sending_init':
       case 'sending_kickstart':
         // For sending states, retry the send
-        this.log('Recovery: returning to watching state');
-        this.setState('watching');
-        this.startNoOutputTimer();
-        this.startPreFilterTimer();
-        if (this.config.autoAcceptPrompts) {
-          this.startAutoAcceptTimer();
-        }
+        this.recoveryResetToWatching('returning to watching state');
         break;
 
       default:
         // Fallback: reset to watching
-        this.log('Recovery: fallback to watching state');
-        this.setState('watching');
-        this.startNoOutputTimer();
-        this.startPreFilterTimer();
-        if (this.config.autoAcceptPrompts) {
-          this.startAutoAcceptTimer();
-        }
+        this.recoveryResetToWatching('fallback to watching state');
+    }
+  }
+
+  /**
+   * Reset the controller to watching state during stuck-state recovery.
+   * Sets state to watching and restarts all detection timers.
+   *
+   * @param reason - Human-readable reason for the reset (logged)
+   */
+  private recoveryResetToWatching(reason: string): void {
+    this.log(`Recovery: ${reason}`);
+    this.setState('watching');
+    this.startNoOutputTimer();
+    this.startPreFilterTimer();
+    if (this.config.autoAcceptPrompts) {
+      this.startAutoAcceptTimer();
     }
   }
 
@@ -2051,7 +2076,7 @@ export class RespawnController extends EventEmitter {
     // If on cooldown, don't start check - wait for cooldown to expire
     if (this.aiChecker.isOnCooldown()) {
       this.log(
-        `AI check on cooldown (${Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000)}s remaining), waiting...`
+        `AI check on cooldown (${formatRemainingSeconds(this.aiChecker.getCooldownRemainingMs())}s remaining), waiting...`
       );
       return;
     }
@@ -2198,36 +2223,15 @@ export class RespawnController extends EventEmitter {
    * @fires planCheckStarted
    */
   private tryAutoAccept(): void {
-    // Only auto-accept in watching state (not during a respawn cycle)
-    if (this._state !== 'watching') return;
+    if (!this.canAutoAccept()) return;
 
-    // Don't auto-accept if a completion message was detected (normal idle handles it)
-    if (this.completionMessageTime !== null) return;
-
-    // Don't auto-accept if disabled
-    if (!this.config.autoAcceptPrompts) return;
-
-    // Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
-    if (!this.hasReceivedOutput) return;
-
-    // Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
-    if (this.elicitationDetected) {
-      this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
-      return;
-    }
-
-    // Stage 1: Pre-filter — check if buffer looks like plan mode
     const buffer = this.terminalBuffer.value;
-    if (!this.isPlanModePreFilterMatch(buffer)) {
-      this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
-      return;
-    }
 
     // Stage 2: AI confirmation (if enabled and available)
     if (this.config.aiPlanCheckEnabled && this.planChecker.status !== 'disabled') {
       if (this.planChecker.isOnCooldown()) {
         this.log(
-          `Skipping auto-accept: plan checker on cooldown (${Math.ceil(this.planChecker.getCooldownRemainingMs() / 1000)}s remaining)`
+          `Skipping auto-accept: plan checker on cooldown (${formatRemainingSeconds(this.planChecker.getCooldownRemainingMs())}s remaining)`
         );
         return;
       }
@@ -2244,6 +2248,40 @@ export class RespawnController extends EventEmitter {
     this.sendAutoAcceptEnter();
   }
 
+  /**
+   * Check whether all preconditions for auto-accept are met.
+   * Validates state, config, and pre-filter conditions before attempting auto-accept.
+   *
+   * @returns True if auto-accept should proceed to the AI confirmation stage
+   */
+  private canAutoAccept(): boolean {
+    // Only auto-accept in watching state (not during a respawn cycle)
+    if (this._state !== 'watching') return false;
+
+    // Don't auto-accept if a completion message was detected (normal idle handles it)
+    if (this.completionMessageTime !== null) return false;
+
+    // Don't auto-accept if disabled
+    if (!this.config.autoAcceptPrompts) return false;
+
+    // Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
+    if (!this.hasReceivedOutput) return false;
+
+    // Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
+    if (this.elicitationDetected) {
+      this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
+      return false;
+    }
+
+    // Stage 1: Pre-filter — check if buffer looks like plan mode
+    if (!this.isPlanModePreFilterMatch(this.terminalBuffer.value)) {
+      this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
+      return false;
+    }
+
+    return true;
+  }
+
   /**
    * Check if the terminal buffer matches plan mode pre-filter patterns.
    * Only checks the last 2000 chars (plan mode UI appears at the bottom).

src/session-auto-ops.ts

@@ -27,6 +27,57 @@ const COMPACT_COOLDOWN_MS = 10000;
 /** Cooldown after clear completes before re-enabling (5 seconds) */
 const CLEAR_COOLDOWN_MS = 5000;
 
+/**
+ * Executes an action when the session becomes idle, retrying if currently working.
+ *
+ * @param action - The async action to execute once idle
+ * @param isActive - Returns whether this operation is still active (not cancelled)
+ * @param isWorking - Returns whether the session is currently working
+ * @param isStopped - Returns whether the session has been stopped
+ * @param retryMs - Delay between retry attempts when working
+ * @param cooldownMs - Delay after action completes before calling onCooldownDone
+ * @param setTimer - Stores the timer reference for cleanup
+ * @param onCooldownDone - Called after cooldown to reset state
+ */
+async function executeWhenIdle(
+  action: () => Promise<void>,
+  isActive: () => boolean,
+  isWorking: () => boolean,
+  isStopped: () => boolean,
+  retryMs: number,
+  cooldownMs: number,
+  setTimer: (timer: NodeJS.Timeout | null) => void,
+  onCooldownDone: () => void
+): Promise<void> {
+  if (isStopped()) return;
+  if (!isActive()) return;
+
+  if (!isWorking()) {
+    if (isStopped()) return;
+
+    await action();
+
+    if (!isStopped()) {
+      setTimer(
+        setTimeout(() => {
+          if (isStopped()) return;
+          setTimer(null);
+          onCooldownDone();
+        }, cooldownMs)
+      );
+    }
+  } else {
+    if (!isStopped()) {
+      setTimer(
+        setTimeout(
+          () => executeWhenIdle(action, isActive, isWorking, isStopped, retryMs, cooldownMs, setTimer, onCooldownDone),
+          retryMs
+        )
+      );
+    }
+  }
+}
+
 /** Minimum valid threshold for auto-clear/compact (1000 tokens) */
 const MIN_AUTO_THRESHOLD = 1000;
 
@@ -181,37 +232,35 @@ export class SessionAutoOps extends EventEmitter {
         `[SessionAutoOps] Auto-compact triggered: ${totalTokens} tokens >= ${this._autoCompactThreshold} threshold`
       );
 
-      const checkAndCompact = async () => {
-        if (this.callbacks.isStopped()) return;
-        if (!this._isCompacting) return;
-
-        if (!this.callbacks.isWorking()) {
-          if (this.callbacks.isStopped()) return;
-
-          const compactCmd = this._autoCompactPrompt ? `/compact ${this._autoCompactPrompt}\r` : '/compact\r';
-          await this.callbacks.writeCommand(compactCmd);
-          this.emit('autoCompact', {
-            tokens: totalTokens,
-            threshold: this._autoCompactThreshold,
-            prompt: this._autoCompactPrompt || undefined,
-          });
-
-          if (!this.callbacks.isStopped()) {
-            this._autoCompactTimer = setTimeout(() => {
-              if (this.callbacks.isStopped()) return;
-              this._autoCompactTimer = null;
-              this._isCompacting = false;
-            }, COMPACT_COOLDOWN_MS);
-          }
-        } else {
-          if (!this.callbacks.isStopped()) {
-            this._autoCompactTimer = setTimeout(checkAndCompact, AUTO_RETRY_DELAY_MS);
-          }
-        }
+      const action = async () => {
+        const compactCmd = this._autoCompactPrompt ? `/compact ${this._autoCompactPrompt}\r` : '/compact\r';
+        await this.callbacks.writeCommand(compactCmd);
+        this.emit('autoCompact', {
+          tokens: totalTokens,
+          threshold: this._autoCompactThreshold,
+          prompt: this._autoCompactPrompt || undefined,
+        });
       };
 
       if (!this.callbacks.isStopped()) {
-        this._autoCompactTimer = setTimeout(checkAndCompact, AUTO_INITIAL_DELAY_MS);
+        this._autoCompactTimer = setTimeout(
+          () =>
+            executeWhenIdle(
+              action,
+              () => this._isCompacting,
+              () => this.callbacks.isWorking(),
+              () => this.callbacks.isStopped(),
+              AUTO_RETRY_DELAY_MS,
+              COMPACT_COOLDOWN_MS,
+              (timer) => {
+                this._autoCompactTimer = timer;
+              },
+              () => {
+                this._isCompacting = false;
+              }
+            ),
+          AUTO_INITIAL_DELAY_MS
+        );
       }
     }
   }
@@ -231,32 +280,30 @@ export class SessionAutoOps extends EventEmitter {
         `[SessionAutoOps] Auto-clear triggered: ${totalTokens} tokens >= ${this._autoClearThreshold} threshold`
       );
 
-      const checkAndClear = async () => {
-        if (this.callbacks.isStopped()) return;
-        if (!this._isClearing) return;
-
-        if (!this.callbacks.isWorking()) {
-          if (this.callbacks.isStopped()) return;
-
-          await this.callbacks.writeCommand('/clear\r');
-          this.emit('autoClear', { tokens: totalTokens, threshold: this._autoClearThreshold });
-
-          if (!this.callbacks.isStopped()) {
-            this._autoClearTimer = setTimeout(() => {
-              if (this.callbacks.isStopped()) return;
-              this._autoClearTimer = null;
-              this._isClearing = false;
-            }, CLEAR_COOLDOWN_MS);
-          }
-        } else {
-          if (!this.callbacks.isStopped()) {
-            this._autoClearTimer = setTimeout(checkAndClear, AUTO_RETRY_DELAY_MS);
-          }
-        }
+      const action = async () => {
+        await this.callbacks.writeCommand('/clear\r');
+        this.emit('autoClear', { tokens: totalTokens, threshold: this._autoClearThreshold });
       };
 
       if (!this.callbacks.isStopped()) {
-        this._autoClearTimer = setTimeout(checkAndClear, AUTO_INITIAL_DELAY_MS);
+        this._autoClearTimer = setTimeout(
+          () =>
+            executeWhenIdle(
+              action,
+              () => this._isClearing,
+              () => this.callbacks.isWorking(),
+              () => this.callbacks.isStopped(),
+              AUTO_RETRY_DELAY_MS,
+              CLEAR_COOLDOWN_MS,
+              (timer) => {
+                this._autoClearTimer = timer;
+              },
+              () => {
+                this._isClearing = false;
+              }
+            ),
+          AUTO_INITIAL_DELAY_MS
+        );
       }
     }
   }

src/session.ts

@@ -876,13 +876,7 @@ export class Session extends EventEmitter {
       throw new Error('Session already has a running process');
     }
 
-    this._status = 'busy';
-    this._terminalBuffer.clear();
-    this._textOutput.clear();
-    this._errorBuffer = '';
-    this._messages = [];
-    this._lineBuffer = '';
-    this._lastActivityAt = Date.now();
+    this._resetBuffers();
 
     const modeLabel = this.mode === 'opencode' ? 'OpenCode' : 'Claude';
     console.log(
@@ -1257,13 +1251,7 @@ export class Session extends EventEmitter {
       throw new Error('Session already has a running process');
     }
 
-    this._status = 'busy';
-    this._terminalBuffer.clear();
-    this._textOutput.clear();
-    this._errorBuffer = '';
-    this._messages = [];
-    this._lineBuffer = '';
-    this._lastActivityAt = Date.now();
+    this._resetBuffers();
 
     // Use user's default shell or bash
     const shell = process.env.SHELL || '/bin/bash';
@@ -1448,13 +1436,7 @@ export class Session extends EventEmitter {
         return;
       }
 
-      this._status = 'busy';
-      this._terminalBuffer.clear();
-      this._textOutput.clear();
-      this._errorBuffer = '';
-      this._messages = [];
-      this._lineBuffer = '';
-      this._lastActivityAt = Date.now();
+      this._resetBuffers();
       this._promptResolved = false; // Reset race condition guard
 
       this.resolvePromise = resolve;
@@ -1565,6 +1547,117 @@ export class Session extends EventEmitter {
     });
   }
 
+  private _resetBuffers(): void {
+    this._status = 'busy';
+    this._terminalBuffer.clear();
+    this._textOutput.clear();
+    this._errorBuffer = '';
+    this._messages = [];
+    this._lineBuffer = '';
+    this._lastActivityAt = Date.now();
+  }
+
+  private _clearAllTimers(): void {
+    // Clear activity timeout to prevent memory leak
+    if (this.activityTimeout) {
+      clearTimeout(this.activityTimeout);
+      this.activityTimeout = null;
+    }
+
+    // Clear line buffer flush timer
+    if (this._lineBufferFlushTimer) {
+      clearTimeout(this._lineBufferFlushTimer);
+      this._lineBufferFlushTimer = null;
+    }
+
+    // Destroy auto-compact/auto-clear automation (clears its timers)
+    this._autoOps.destroy();
+
+    // Clear prompt check timers
+    if (this._promptCheckInterval) {
+      clearInterval(this._promptCheckInterval);
+      this._promptCheckInterval = null;
+    }
+    if (this._promptCheckTimeout) {
+      clearTimeout(this._promptCheckTimeout);
+      this._promptCheckTimeout = null;
+    }
+
+    // Clear shell idle timer
+    if (this._shellIdleTimer) {
+      clearTimeout(this._shellIdleTimer);
+      this._shellIdleTimer = null;
+    }
+
+    // Clear expensive processing timer
+    if (this._expensiveProcessTimer) {
+      clearTimeout(this._expensiveProcessTimer);
+      this._expensiveProcessTimer = null;
+    }
+    this._pendingCleanData = '';
+  }
+
+  private _handleJsonMessage(cleanLine: string, rawLine: string): void {
+    try {
+      const msg = JSON.parse(cleanLine) as ClaudeMessage;
+      this._messages.push(msg);
+      this.emit('message', msg);
+
+      // Trim messages array for long-running sessions
+      if (this._messages.length > MAX_MESSAGES) {
+        this._messages = this._messages.slice(-Math.floor(MAX_MESSAGES * 0.8));
+      }
+
+      // Extract Claude session ID from messages (can be in any message type)
+      // Support both sessionId (camelCase) and session_id (snake_case)
+      const msgSessionId =
+        ((msg as unknown as Record<string, unknown>).sessionId as string | undefined) ?? msg.session_id;
+      if (msgSessionId && !this._claudeSessionId) {
+        this._claudeSessionId = msgSessionId;
+      }
+
+      // Process message for task tracking
+      this._taskTracker.processMessage(msg);
+
+      if (msg.type === 'assistant' && msg.message?.content) {
+        for (const block of msg.message.content) {
+          if (block.type === 'text' && block.text) {
+            this._textOutput.append(block.text);
+          }
+        }
+        // Track tokens from usage (with validation)
+        if (msg.message.usage) {
+          const inputDelta = msg.message.usage.input_tokens || 0;
+          const outputDelta = msg.message.usage.output_tokens || 0;
+
+          // Sanity check: max 100k tokens per message (generous limit)
+          const MAX_TOKENS_PER_MESSAGE = 100_000;
+          if (inputDelta > 0 && inputDelta <= MAX_TOKENS_PER_MESSAGE) {
+            this._totalInputTokens += inputDelta;
+          }
+          if (outputDelta > 0 && outputDelta <= MAX_TOKENS_PER_MESSAGE) {
+            this._totalOutputTokens += outputDelta;
+          }
+
+          // Check if we should auto-compact or auto-clear
+          this._autoOps.checkAutoCompact();
+          this._autoOps.checkAutoClear();
+        }
+      }
+
+      if (msg.type === 'result' && msg.total_cost_usd) {
+        this._totalCost = msg.total_cost_usd;
+      }
+    } catch (parseErr) {
+      // Not JSON, just regular output - this is expected for non-JSON lines
+      console.debug(
+        '[Session] Line not JSON (expected for text output):',
+        parseErr instanceof Error ? parseErr.message : parseErr
+      );
+      this._textOutput.append(rawLine + '\n');
+    }
+  }
+
   private processOutput(data: string): void {
     // Early return if session is stopped to prevent any processing or timer creation
     if (this._isStopped) return;
@@ -1606,64 +1699,7 @@ export class Session extends EventEmitter {
       const cleanLine = trimmed.replace(ANSI_ESCAPE_PATTERN_FULL, '');
 
       if (cleanLine.startsWith('{') && cleanLine.endsWith('}')) {
-        try {
-          const msg = JSON.parse(cleanLine) as ClaudeMessage;
-          this._messages.push(msg);
-          this.emit('message', msg);
-
-          // Trim messages array for long-running sessions
-          if (this._messages.length > MAX_MESSAGES) {
-            this._messages = this._messages.slice(-Math.floor(MAX_MESSAGES * 0.8));
-          }
-
-          // Extract Claude session ID from messages (can be in any message type)
-          // Support both sessionId (camelCase) and session_id (snake_case)
-          const msgSessionId =
-            ((msg as unknown as Record<string, unknown>).sessionId as string | undefined) ?? msg.session_id;
-          if (msgSessionId && !this._claudeSessionId) {
-            this._claudeSessionId = msgSessionId;
-          }
-
-          // Process message for task tracking
-          this._taskTracker.processMessage(msg);
-
-          if (msg.type === 'assistant' && msg.message?.content) {
-            for (const block of msg.message.content) {
-              if (block.type === 'text' && block.text) {
-                this._textOutput.append(block.text);
-              }
-            }
-            // Track tokens from usage (with validation)
-            if (msg.message.usage) {
-              const inputDelta = msg.message.usage.input_tokens || 0;
-              const outputDelta = msg.message.usage.output_tokens || 0;
-
-              // Sanity check: max 100k tokens per message (generous limit)
-              const MAX_TOKENS_PER_MESSAGE = 100_000;
-              if (inputDelta > 0 && inputDelta <= MAX_TOKENS_PER_MESSAGE) {
-                this._totalInputTokens += inputDelta;
-              }
-              if (outputDelta > 0 && outputDelta <= MAX_TOKENS_PER_MESSAGE) {
-                this._totalOutputTokens += outputDelta;
-              }
-
-              // Check if we should auto-compact or auto-clear
-              this._autoOps.checkAutoCompact();
-              this._autoOps.checkAutoClear();
-            }
-          }
-
-          if (msg.type === 'result' && msg.total_cost_usd) {
-            this._totalCost = msg.total_cost_usd;
-          }
-        } catch (parseErr) {
-          // Not JSON, just regular output - this is expected for non-JSON lines
-          console.debug(
-            '[Session] Line not JSON (expected for text output):',
-            parseErr instanceof Error ? parseErr.message : parseErr
-          );
-          this._textOutput.append(line + '\n');
-        }
+        this._handleJsonMessage(cleanLine, line);
       } else if (trimmed) {
         this._textOutput.append(line + '\n');
       }
@@ -2030,43 +2066,7 @@ export class Session extends EventEmitter {
     // Set stopped flag first to prevent new timers from being created
     this._isStopped = true;
 
-    // Clear activity timeout to prevent memory leak
-    if (this.activityTimeout) {
-      clearTimeout(this.activityTimeout);
-      this.activityTimeout = null;
-    }
-
-    // Clear line buffer flush timer
-    if (this._lineBufferFlushTimer) {
-      clearTimeout(this._lineBufferFlushTimer);
-      this._lineBufferFlushTimer = null;
-    }
-
-    // Destroy auto-compact/auto-clear automation (clears its timers)
-    this._autoOps.destroy();
-
-    // Clear prompt check timers
-    if (this._promptCheckInterval) {
-      clearInterval(this._promptCheckInterval);
-      this._promptCheckInterval = null;
-    }
-    if (this._promptCheckTimeout) {
-      clearTimeout(this._promptCheckTimeout);
-      this._promptCheckTimeout = null;
-    }
-
-    // Clear shell idle timer
-    if (this._shellIdleTimer) {
-      clearTimeout(this._shellIdleTimer);
-      this._shellIdleTimer = null;
-    }
-
-    // Clear expensive processing timer
-    if (this._expensiveProcessTimer) {
-      clearTimeout(this._expensiveProcessTimer);
-      this._expensiveProcessTimer = null;
-    }
-    this._pendingCleanData = '';
+    this._clearAllTimers();
 
     // Immediately cleanup Promise callbacks to prevent orphaned references
     // during the rest of stop() processing (e.g., if mux kill times out)

src/state-store.ts

@@ -195,16 +195,7 @@ export class StateStore {
    * Only dirty sessions are re-serialized; clean sessions use cached JSON fragments.
    */
   private assembleStateJson(): string {
-    // Re-serialize dirty sessions and update cache
-    for (const id of this.dirtySessions) {
-      const session = this.state.sessions[id];
-      if (session) {
-        this.cachedSessionJsons.set(id, JSON.stringify(session));
-      } else {
-        this.cachedSessionJsons.delete(id);
-      }
-    }
-    this.dirtySessions.clear();
+    this.updateDirtySessionCache();
 
     // Build sessions object from cached fragments
     const sessionParts: string[] = [];
@@ -218,6 +209,25 @@ export class StateStore {
       sessionParts.push(`${JSON.stringify(id)}:${json}`);
     }
 
+    this.pruneStaleCacheEntries();
+
+    return this.buildPartialJson(sessionParts);
+  }
+
+  private updateDirtySessionCache(): void {
+    // Re-serialize dirty sessions and update cache
+    for (const id of this.dirtySessions) {
+      const session = this.state.sessions[id];
+      if (session) {
+        this.cachedSessionJsons.set(id, JSON.stringify(session));
+      } else {
+        this.cachedSessionJsons.delete(id);
+      }
+    }
+    this.dirtySessions.clear();
+  }
+
+  private pruneStaleCacheEntries(): void {
     // Prune stale cache entries (sessions removed via direct state mutation)
     if (this.cachedSessionJsons.size > Object.keys(this.state.sessions).length) {
       for (const cachedId of this.cachedSessionJsons.keys()) {
@@ -226,7 +236,9 @@ export class StateStore {
         }
       }
     }
+  }
 
+  private buildPartialJson(sessionParts: string[]): string {
     // Build final JSON: sessions from cache, everything else re-serialized (tiny)
     const sessionsJson = `{${sessionParts.join(',')}}`;
 
@@ -249,6 +261,28 @@ export class StateStore {
     return `{${parts.join(',')}}`;
   }
 
+  private serializeState(): string | null {
+    try {
+      return this.assembleStateJson();
+    } catch (assembleErr) {
+      // Fallback to full serialization if incremental assembly fails
+      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
+      this.cachedSessionJsons.clear();
+      this.dirtySessions.clear();
+      try {
+        return JSON.stringify(this.state);
+      } catch (err) {
+        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
+        this.consecutiveSaveFailures++;
+        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
+          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
+          this.circuitBreakerOpen = true;
+        }
+        return null;
+      }
+    }
+  }
+
   private async _doSaveAsync(): Promise<void> {
     this.saveDeb.cancel();
     if (!this.dirty) {
@@ -265,28 +299,10 @@ export class StateStore {
 
     const tempPath = this.filePath + '.tmp';
     const backupPath = this.filePath + '.bak';
-    let json: string;
 
     // Step 1: Serialize state (validates it's JSON-safe)
-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;
 
     // Clear dirty flag BEFORE async I/O so mutations during write re-set it.
     // The state snapshot is already captured in `json` above.
@@ -351,27 +367,9 @@ export class StateStore {
 
     const tempPath = this.filePath + '.tmp';
     const backupPath = this.filePath + '.bak';
-    let json: string;
 
-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;
 
     // Backup via atomic copy (avoids reading entire file into memory)
     try {
@@ -547,6 +545,30 @@ export class StateStore {
     this.save();
   }
 
+  // ========== Orchestrator Loop State Methods ==========
+
+  /** Returns the orchestrator loop state, or null if never initialized. */
+  getOrchestratorState() {
+    return this.state.orchestrator ?? null;
+  }
+
+  /** Updates orchestrator loop state (partial merge) and triggers a debounced save. */
+  setOrchestratorState(orchestrator: Partial<NonNullable<AppState['orchestrator']>>) {
+    if (this.state.orchestrator) {
+      this.state.orchestrator = { ...this.state.orchestrator, ...orchestrator };
+    } else {
+      // First initialization — caller must provide full state
+      this.state.orchestrator = orchestrator as NonNullable<AppState['orchestrator']>;
+    }
+    this.save();
+  }
+
+  /** Clears orchestrator state and triggers a debounced save. */
+  clearOrchestratorState() {
+    this.state.orchestrator = undefined;
+    this.save();
+  }
+
   /** Returns the application configuration. */
   getConfig() {
     return this.state.config;

src/subagent-watcher.ts

@@ -222,6 +222,83 @@ export class SubagentWatcher extends EventEmitter {
     return INTERNAL_AGENT_PATTERNS.some((pattern) => pattern.test(description));
   }
 
+  /**
+   * Mark a subagent as completed: clear PID, set status, clean up pending tool calls, emit event.
+   */
+  private markSubagentAsCompleted(info: SubagentInfo): void {
+    info.pid = undefined;
+    info.status = 'completed';
+    this.pendingToolCalls.delete(info.agentId);
+    this.emit('subagent:completed', info);
+  }
+
+  /**
+   * Extract text from message content, handling both string and array formats.
+   * For array content, returns the text from the first 'text' block.
+   */
+  private extractFirstTextContent(
+    content: string | Array<{ type: string; text?: string }> | undefined
+  ): string | undefined {
+    if (!content) return undefined;
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+      return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (Array.isArray(content)) {
+      const firstContent = content[0];
+      if (firstContent?.type === 'text' && firstContent.text) {
+        const trimmed = firstContent.text.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Process a tool_result content block: look up pending tool call, emit tool_result event.
+   */
+  private emitToolResult(
+    content: { tool_use_id: string; content?: string | Array<{ type: string; text?: string }>; is_error?: boolean },
+    agentId: string,
+    sessionId: string,
+    timestamp: string
+  ): void {
+    const resultContent = this.extractToolResultContent(content.content);
+    const agentPendingCalls = this.pendingToolCalls.get(agentId);
+    const pendingCall = agentPendingCalls?.get(content.tool_use_id);
+    const toolName = pendingCall?.toolName;
+    // Delete after lookup to prevent memory leak
+    agentPendingCalls?.delete(content.tool_use_id);
+
+    const toolResult: SubagentToolResult = {
+      agentId,
+      sessionId,
+      timestamp,
+      toolUseId: content.tool_use_id,
+      tool: toolName,
+      preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
+      contentLength: resultContent.length,
+      isError: content.is_error || false,
+    };
+    this.emit('subagent:tool_result', toolResult);
+  }
+
+  /**
+   * Find the oldest inactive (non-active) agent for LRU eviction.
+   * Returns the agent ID of the oldest inactive agent, or null if all are active.
+   */
+  private findOldestInactiveAgent(): string | null {
+    let oldestId: string | null = null;
+    let oldestTime = Infinity;
+    for (const [id, existing] of this.agentInfo) {
+      if (existing.status !== 'active' && existing.lastActivityAt < oldestTime) {
+        oldestTime = existing.lastActivityAt;
+        oldestId = id;
+      }
+    }
+    return oldestId;
+  }
+
   /**
    * Extract short model identifier from full model name
    */
@@ -307,10 +384,7 @@ export class SubagentWatcher extends EventEmitter {
 
               const alive = this.checkSubagentAliveFromPidMap(info, pidMap);
               if (!alive) {
-                info.pid = undefined;
-                info.status = 'completed';
-                this.pendingToolCalls.delete(info.agentId);
-                this.emit('subagent:completed', info);
+                this.markSubagentAsCompleted(info);
               }
             }
           }
@@ -677,10 +751,7 @@ export class SubagentWatcher extends EventEmitter {
       const pid = await this.findSubagentProcess(info.sessionId);
       if (pid) {
         process.kill(pid, 'SIGTERM');
-        info.pid = undefined;
-        info.status = 'completed';
-        this.pendingToolCalls.delete(info.agentId);
-        this.emit('subagent:completed', info);
+        this.markSubagentAsCompleted(info);
         return true;
       }
     } catch {
@@ -688,10 +759,7 @@ export class SubagentWatcher extends EventEmitter {
     }
 
     // Mark as completed even if we couldn't find the process
-    info.pid = undefined;
-    info.status = 'completed';
-    this.pendingToolCalls.delete(info.agentId);
-    this.emit('subagent:completed', info);
+    this.markSubagentAsCompleted(info);
     return true;
   }
 
@@ -843,19 +911,9 @@ export class SubagentWatcher extends EventEmitter {
         }
       } else if (entry.type === 'user' && entry.message?.content) {
         // Handle both string and array content formats
-        if (typeof entry.message.content === 'string') {
-          const text = entry.message.content.trim();
-          if (text.length < 100 && !text.includes('{')) {
-            lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
-          }
-        } else {
-          const firstContent = entry.message.content[0];
-          if (firstContent?.type === 'text' && firstContent.text) {
-            const text = firstContent.text.trim();
-            if (text.length < 100 && !text.includes('{')) {
-              lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
-            }
-          }
+        const text = this.extractFirstTextContent(entry.message.content);
+        if (text && text.length < 100 && !text.includes('{')) {
+          lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
         }
       }
     }
@@ -1027,15 +1085,7 @@ export class SubagentWatcher extends EventEmitter {
           try {
             const entry = JSON.parse(line);
             if (entry.type === 'user' && entry.message?.content) {
-              let text: string | undefined;
-              if (typeof entry.message.content === 'string') {
-                text = entry.message.content.trim();
-              } else if (Array.isArray(entry.message.content)) {
-                const firstContent = entry.message.content[0];
-                if (firstContent?.type === 'text' && firstContent.text) {
-                  text = firstContent.text.trim();
-                }
-              }
+              const text = this.extractFirstTextContent(entry.message.content);
               if (text) {
                 resolved = true;
                 rl.close();
@@ -1286,14 +1336,7 @@ export class SubagentWatcher extends EventEmitter {
 
     // Enforce MAX_TRACKED_AGENTS during insertion — evict oldest inactive agent
     if (this.agentInfo.size >= MAX_TRACKED_AGENTS) {
-      let oldestId: string | null = null;
-      let oldestTime = Infinity;
-      for (const [id, existing] of this.agentInfo) {
-        if (existing.status !== 'active' && existing.lastActivityAt < oldestTime) {
-          oldestTime = existing.lastActivityAt;
-          oldestId = id;
-        }
-      }
+      const oldestId = this.findOldestInactiveAgent();
       if (oldestId) {
         this.removeAgent(oldestId);
       }
@@ -1386,15 +1429,7 @@ export class SubagentWatcher extends EventEmitter {
       let description = await this.extractDescriptionFromParentTranscript(info.projectHash, info.sessionId, agentId);
       // Fallback: extract smart title from the prompt content
       if (!description) {
-        let text: string | undefined;
-        if (typeof entry.message.content === 'string') {
-          text = entry.message.content.trim();
-        } else if (Array.isArray(entry.message.content)) {
-          const firstContent = entry.message.content[0];
-          if (firstContent?.type === 'text' && firstContent.text) {
-            text = firstContent.text.trim();
-          }
-        }
+        const text = this.extractFirstTextContent(entry.message.content);
         if (text) {
           description = this.extractSmartTitle(text);
         }
@@ -1480,24 +1515,12 @@ export class SubagentWatcher extends EventEmitter {
             }
           } else if (content.type === 'tool_result' && content.tool_use_id) {
             // Extract tool result
-            const resultContent = this.extractToolResultContent(content.content);
-            const agentPendingCalls = this.pendingToolCalls.get(agentId);
-            const pendingCall = agentPendingCalls?.get(content.tool_use_id);
-            const toolName = pendingCall?.toolName;
-            // Delete after lookup to prevent memory leak
-            agentPendingCalls?.delete(content.tool_use_id);
-
-            const toolResult: SubagentToolResult = {
+            this.emitToolResult(
+              { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
               agentId,
               sessionId,
-              timestamp: entry.timestamp,
-              toolUseId: content.tool_use_id,
-              tool: toolName,
-              preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
-              contentLength: resultContent.length,
-              isError: content.is_error || false,
-            };
-            this.emit('subagent:tool_result', toolResult);
+              entry.timestamp
+            );
           } else if (content.type === 'text' && content.text) {
             const text = content.text.trim();
             if (text.length > 0) {
@@ -1531,24 +1554,12 @@ export class SubagentWatcher extends EventEmitter {
         // Check for tool_result blocks in user messages (common pattern)
         for (const content of entry.message.content) {
           if (content.type === 'tool_result' && content.tool_use_id) {
-            const resultContent = this.extractToolResultContent(content.content);
-            const agentPendingCalls = this.pendingToolCalls.get(agentId);
-            const pendingCall = agentPendingCalls?.get(content.tool_use_id);
-            const toolName = pendingCall?.toolName;
-            // Delete after lookup to prevent memory leak
-            agentPendingCalls?.delete(content.tool_use_id);
-
-            const toolResult: SubagentToolResult = {
+            this.emitToolResult(
+              { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
               agentId,
               sessionId,
-              timestamp: entry.timestamp,
-              toolUseId: content.tool_use_id,
-              tool: toolName,
-              preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
-              contentLength: resultContent.length,
-              isError: content.is_error || false,
-            };
-            this.emit('subagent:tool_result', toolResult);
+              entry.timestamp
+            );
           } else if (content.type === 'text' && content.text) {
             const userText = content.text.trim();
             if (userText.length > 0 && userText.length < 500) {

src/tmux-manager.ts

@@ -98,6 +98,9 @@ const LEGACY_MUX_NAME_PATTERN = /^claudeman-[a-f0-9-]+$/;
 /** Regex to validate tmux pane targets (e.g., "%0", "%1", "0", "1") */
 const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;
 
+/** Characters unsafe in paths — shell metacharacters, quotes, and control chars */
+const UNSAFE_PATH_CHARS = /[;&|$`(){}<>'"\n\r]/;
+
 /**
  * Validates that a session name contains only safe characters.
  * Prevents command injection via malformed session IDs.
@@ -111,23 +114,7 @@ function isValidMuxName(name: string): boolean {
  * Prevents command injection via malformed paths.
  */
 function isValidPath(path: string): boolean {
-  if (
-    path.includes(';') ||
-    path.includes('&') ||
-    path.includes('|') ||
-    path.includes('$') ||
-    path.includes('`') ||
-    path.includes('(') ||
-    path.includes(')') ||
-    path.includes('{') ||
-    path.includes('}') ||
-    path.includes('<') ||
-    path.includes('>') ||
-    path.includes("'") ||
-    path.includes('"') ||
-    path.includes('\n') ||
-    path.includes('\r')
-  ) {
+  if (UNSAFE_PATH_CHARS.test(path)) {
     return false;
   }
   if (path.includes('..')) {
@@ -371,6 +358,52 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
   }
 
+  /**
+   * Build the array of environment export commands shared by createSession() and respawnPane().
+   * Includes locale, mux markers, session identity, and API URL.
+   */
+  private buildEnvExports(sessionId: string, muxName: string, mode: SessionMode): string[] {
+    const exports = [
+      'export LANG=en_US.UTF-8',
+      'export LC_ALL=en_US.UTF-8',
+      'unset COLORTERM',
+      'export CODEMAN_MUX=1',
+      `export CODEMAN_SESSION_ID=${sessionId}`,
+      `export CODEMAN_MUX_NAME=${muxName}`,
+      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
+    ];
+    // Only unset CLAUDECODE for Claude sessions
+    if (mode === 'claude') exports.splice(2, 0, 'unset CLAUDECODE');
+    return exports;
+  }
+
+  /**
+   * Resolve the CLI binary directory and return the PATH export prefix string.
+   * Returns '' if no override is needed (shell mode) or the binary dir is not found.
+   * In createSession(), a missing binary dir throws — the caller handles that separately.
+   */
+  private buildPathExport(mode: SessionMode): { pathExport: string; dir: string | null } {
+    if (mode === 'claude') {
+      const dir = findClaudeDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
+    if (mode === 'opencode') {
+      const dir = resolveOpenCodeDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
+    return { pathExport: '', dir: null };
+  }
+
+  /**
+   * Configure OpenCode-specific environment on a tmux session.
+   * Sets sensitive API keys and config content via tmux setenv
+   * (not visible in ps output or tmux history, inherited by panes).
+   */
+  private _configureOpenCode(muxName: string, openCodeConfig?: OpenCodeConfig): void {
+    setOpenCodeEnvVars(muxName);
+    setOpenCodeConfigContent(muxName, openCodeConfig);
+  }
+
   /**
    * Creates a new tmux session wrapping Claude CLI or a shell.
    * In test mode: creates an in-memory session only (no real tmux session).
@@ -415,33 +448,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     // Resolve CLI binary directory based on mode
-    let pathExport = '';
-    if (mode === 'claude') {
-      const claudeDir = findClaudeDir();
-      if (!claudeDir) {
-        throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
-      }
-      pathExport = `export PATH="${claudeDir}:$PATH" && `;
-    } else if (mode === 'opencode') {
-      const openCodeDir = resolveOpenCodeDir();
-      if (!openCodeDir) {
-        throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
-      }
-      pathExport = `export PATH="${openCodeDir}:$PATH" && `;
+    const { pathExport, dir: cliDir } = this.buildPathExport(mode);
+    if (mode === 'claude' && !cliDir) {
+      throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
+    }
+    if (mode === 'opencode' && !cliDir) {
+      throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
     }
 
-    const envExports = [
-      'export LANG=en_US.UTF-8',
-      'export LC_ALL=en_US.UTF-8',
-      'unset COLORTERM',
-      'export CODEMAN_MUX=1',
-      `export CODEMAN_SESSION_ID=${sessionId}`,
-      `export CODEMAN_MUX_NAME=${muxName}`,
-      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
-    ];
-    // Only unset CLAUDECODE for Claude sessions
-    if (mode === 'claude') envExports.splice(2, 0, 'unset CLAUDECODE');
-    const envExportsStr = envExports.join(' && ');
+    const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
     const baseCmd = buildSpawnCommand({
       mode,
@@ -489,8 +504,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // For OpenCode: set sensitive env vars and config via tmux setenv
       // (not visible in ps output or tmux history, inherited by panes)
       if (mode === 'opencode') {
-        setOpenCodeEnvVars(muxName);
-        setOpenCodeConfigContent(muxName, openCodeConfig);
+        this._configureOpenCode(muxName, openCodeConfig);
       }
 
       // Replace the shell with the actual command (no echo in terminal)
@@ -641,26 +655,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
 
     // Resolve CLI binary directory based on mode
-    let pathExport = '';
-    if (mode === 'claude') {
-      const claudeDir = findClaudeDir();
-      pathExport = claudeDir ? `export PATH="${claudeDir}:$PATH" && ` : '';
-    } else if (mode === 'opencode') {
-      const openCodeDir = resolveOpenCodeDir();
-      pathExport = openCodeDir ? `export PATH="${openCodeDir}:$PATH" && ` : '';
-    }
+    const { pathExport } = this.buildPathExport(mode);
 
-    const envExports = [
-      'export LANG=en_US.UTF-8',
-      'export LC_ALL=en_US.UTF-8',
-      'unset COLORTERM',
-      'export CODEMAN_MUX=1',
-      `export CODEMAN_SESSION_ID=${sessionId}`,
-      `export CODEMAN_MUX_NAME=${muxName}`,
-      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
-    ];
-    if (mode === 'claude') envExports.splice(2, 0, 'unset CLAUDECODE');
-    const envExportsStr = envExports.join(' && ');
+    const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
     const baseCmd = buildSpawnCommand({
       mode,
@@ -678,8 +675,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     try {
       // For OpenCode: set sensitive env vars via tmux setenv before respawn
       if (mode === 'opencode') {
-        setOpenCodeEnvVars(muxName);
-        setOpenCodeConfigContent(muxName, openCodeConfig);
+        this._configureOpenCode(muxName, openCodeConfig);
       }
 
       await execAsync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
@@ -905,13 +901,34 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const dead: string[] = [];
     const discovered: string[] = [];
 
-    // Check known sessions
+    // Batch: single tmux call to get all session names + pane PIDs (replaces N per-session subprocess calls)
+    const activeSessions = new Map<string, number>();
+    try {
+      const output = execSync("tmux list-panes -a -F '#{session_name}\t#{pane_pid}' 2>/dev/null || true", {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      }).trim();
+
+      for (const line of output.split('\n')) {
+        if (!line) continue;
+        const sep = line.indexOf('\t');
+        if (sep === -1) continue;
+        const name = line.slice(0, sep);
+        const pid = parseInt(line.slice(sep + 1), 10);
+        if (name && !Number.isNaN(pid)) {
+          activeSessions.set(name, pid);
+        }
+      }
+    } catch (err) {
+      console.error('[TmuxManager] Failed to list tmux panes:', err);
+    }
+
+    // Check known sessions against the batch result (O(1) map lookup instead of subprocess per session)
     for (const [sessionId, session] of this.sessions) {
-      if (this.sessionExists(session.muxName)) {
+      const pid = activeSessions.get(session.muxName);
+      if (pid !== undefined) {
         alive.push(sessionId);
-        // Update PID if it changed
-        const pid = this.getPanePid(session.muxName);
-        if (pid && pid !== session.pid) {
+        if (pid !== session.pid) {
           session.pid = pid;
         }
       } else {
@@ -921,51 +938,31 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       }
     }
 
-    // Discover unknown codeman sessions
-    try {
-      const output = execSync("tmux list-sessions -F '#{session_name}' 2>/dev/null || true", {
-        encoding: 'utf-8',
-        timeout: EXEC_TIMEOUT_MS,
-      }).trim();
+    // Discover unknown codeman/claudeman sessions from the same batch result
+    const knownMuxNames = new Set<string>();
+    for (const session of this.sessions.values()) {
+      knownMuxNames.add(session.muxName);
+    }
 
-      for (const line of output.split('\n')) {
-        const sessionName = line.trim();
-        if (!sessionName || (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-'))) continue;
+    for (const [sessionName, pid] of activeSessions) {
+      if (!sessionName.startsWith('codeman-') && !sessionName.startsWith('claudeman-')) continue;
+      if (knownMuxNames.has(sessionName)) continue;
 
-        // Check if this session is already known
-        let isKnown = false;
-        for (const session of this.sessions.values()) {
-          if (session.muxName === sessionName) {
-            isKnown = true;
-            break;
-          }
-        }
-
-        if (!isKnown) {
-          // Extract session ID fragment from name
-          const fragment = sessionName.replace(/^(?:codeman|claudeman)-/, '');
-          const sessionId = `restored-${fragment}`;
-          const pid = this.getPanePid(sessionName);
-
-          if (pid) {
-            const session: MuxSession = {
-              sessionId,
-              muxName: sessionName,
-              pid,
-              createdAt: Date.now(),
-              workingDir: process.cwd(),
-              mode: 'claude',
-              attached: false,
-              name: `Restored: ${sessionName}`,
-            };
-            this.sessions.set(sessionId, session);
-            discovered.push(sessionId);
-            console.log(`[TmuxManager] Discovered unknown tmux session: ${sessionName} (PID ${pid})`);
-          }
-        }
-      }
-    } catch (err) {
-      console.error('[TmuxManager] Failed to discover sessions:', err);
+      const fragment = sessionName.replace(/^(?:codeman|claudeman)-/, '');
+      const sessionId = `restored-${fragment}`;
+      const session: MuxSession = {
+        sessionId,
+        muxName: sessionName,
+        pid,
+        createdAt: Date.now(),
+        workingDir: process.cwd(),
+        mode: 'claude',
+        attached: false,
+        name: `Restored: ${sessionName}`,
+      };
+      this.sessions.set(sessionId, session);
+      discovered.push(sessionId);
+      console.log(`[TmuxManager] Discovered unknown tmux session: ${sessionName} (PID ${pid})`);
     }
 
     if (dead.length > 0 || discovered.length > 0) {

src/types/api.ts

@@ -117,7 +117,7 @@ export interface CaseInfo {
  * @param value The value to check
  * @returns True if the value is an Error instance
  */
-export function isError(value: unknown): value is Error {
+function isError(value: unknown): value is Error {
   return value instanceof Error;
 }
 

src/types/app-state.ts

@@ -109,6 +109,8 @@ export interface AppState {
   globalStats?: GlobalStats;
   /** Daily token usage statistics */
   tokenStats?: TokenStats;
+  /** Orchestrator Loop state (phased plan execution) */
+  orchestrator?: import('./orchestrator.js').OrchestratorPersistState;
 }
 
 // ========== Default Configuration ==========

src/types/index.ts

@@ -26,6 +26,7 @@
  * | teams        | TeamConfig, TeamMember, TeamTask, InboxMessage, PaneInfo              | `~/.claude/teams/`, `~/.claude/tasks/` → `GET /api/teams` |
  * | push         | PushSubscriptionRecord, VapidKeys                                     | `~/.codeman/push-keys.json`, `~/.codeman/push-subscriptions.json` |
  * | plan         | PlanItem, PlanTaskStatus, TddPhase                                    | In-memory → `GET /api/sessions/:id/plan/tasks` |
+ * | orchestrator | OrchestratorState, OrchestratorPlan, OrchestratorConfig, OrchestratorPersistState | `~/.codeman/state.json` → `GET /api/orchestrator/status` |
  *
  * ## Cross-domain relationship map
  *
@@ -64,3 +65,4 @@ export * from './tools.js';
 export * from './teams.js';
 export * from './push.js';
 export * from './plan.js';
+export * from './orchestrator.js';

src/types/orchestrator.ts

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview Orchestrator Loop type definitions.
+ *
+ * Types for the phased plan execution system: state machine, plan structure,
+ * phase grouping, team strategies, verification, configuration, and persistence.
+ *
+ * Key exports:
+ * - OrchestratorState — state machine states (idle → planning → approval → executing → verifying → ...)
+ * - OrchestratorPlan / OrchestratorPhase / OrchestratorTask — hierarchical plan structure
+ * - TeamStrategy — how agents are coordinated per phase (single, parallel, team)
+ * - VerificationResult / VerificationCheck — phase verification output
+ * - OrchestratorConfig — user-configurable options
+ * - OrchestratorPersistState / OrchestratorStats — persistence and metrics
+ *
+ * Cross-domain relationships:
+ * - OrchestratorTask.queueTaskId links to TaskState.id (task domain)
+ * - OrchestratorTask.assignedSessionId links to SessionState.id (session domain)
+ * - OrchestratorPersistState is embedded in AppState.orchestrator (app-state domain)
+ *
+ * Served at `GET /api/orchestrator/status` and `GET /api/orchestrator/plan`.
+ * No dependencies on other domain modules.
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// State Machine
+// ═══════════════════════════════════════════════════════════════
+
+/** Orchestrator loop states */
+export type OrchestratorState =
+  | 'idle'
+  | 'planning'
+  | 'approval'
+  | 'executing'
+  | 'verifying'
+  | 'replanning'
+  | 'completed'
+  | 'failed'
+  | 'paused';
+
+// ═══════════════════════════════════════════════════════════════
+// Plan Structure
+// ═══════════════════════════════════════════════════════════════
+
+/** Top-level orchestrator plan generated from a user goal */
+export interface OrchestratorPlan {
+  /** Unique plan identifier */
+  id: string;
+  /** Original user goal/task description */
+  goal: string;
+  /** When the plan was generated */
+  createdAt: number;
+  /** Ordered list of execution phases */
+  phases: OrchestratorPhase[];
+  /** Plan generation metadata */
+  metadata: OrchestratorPlanMetadata;
+}
+
+/** Metadata from plan generation */
+export interface OrchestratorPlanMetadata {
+  /** Total tasks across all phases */
+  totalTasks: number;
+  /** Estimated overall complexity */
+  estimatedComplexity: 'low' | 'medium' | 'high';
+  /** Model used for plan generation */
+  modelUsed: string;
+  /** Time taken to generate the plan */
+  planDurationMs: number;
+}
+
+/** A sequential execution phase containing parallel tasks */
+export interface OrchestratorPhase {
+  /** Phase identifier (e.g., "phase-1") */
+  id: string;
+  /** Human-readable phase name */
+  name: string;
+  /** Detailed description of what this phase accomplishes */
+  description: string;
+  /** Execution order (0-based) */
+  order: number;
+  /** Current phase status */
+  status: PhaseStatus;
+  /** Tasks within this phase */
+  tasks: OrchestratorTask[];
+  /** Criteria to verify after phase completion */
+  verificationCriteria: string[];
+  /** Shell commands to run for verification */
+  testCommands: string[];
+  /** Maximum retry attempts for this phase */
+  maxAttempts: number;
+  /** Current attempt count */
+  attempts: number;
+  /** When execution started */
+  startedAt: number | null;
+  /** When phase completed (passed or failed) */
+  completedAt: number | null;
+  /** Total execution duration */
+  durationMs: number | null;
+  /** How to coordinate agents for this phase */
+  teamStrategy: TeamStrategy;
+}
+
+/** Phase execution status */
+export type PhaseStatus = 'pending' | 'executing' | 'verifying' | 'passed' | 'failed' | 'skipped';
+
+/** A single executable task within a phase */
+export interface OrchestratorTask {
+  /** Task identifier (e.g., "phase-1-task-1") */
+  id: string;
+  /** Parent phase identifier */
+  phaseId: string;
+  /** Single-line prompt to send to Claude */
+  prompt: string;
+  /** Current task status */
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /** Session running this task */
+  assignedSessionId: string | null;
+  /** Links to TaskQueue task ID (for completion tracking) */
+  queueTaskId: string | null;
+  /** Whether this task can run in parallel with siblings */
+  parallel: boolean;
+  /** Unique phrase for completion detection */
+  completionPhrase: string;
+  /** Timeout in milliseconds */
+  timeoutMs: number;
+  /** When task started executing */
+  startedAt: number | null;
+  /** When task completed */
+  completedAt: number | null;
+  /** Error message if task failed */
+  error: string | null;
+  /** Number of retry attempts */
+  retries: number;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Team Strategy
+// ═══════════════════════════════════════════════════════════════
+
+/** How agents are coordinated for a phase */
+export type TeamStrategy =
+  | { type: 'single' }
+  | { type: 'parallel'; maxSessions: number }
+  | { type: 'team'; config: TeamSetup };
+
+/** Configuration for team-based phase execution */
+export interface TeamSetup {
+  /** Prompt to send to the team lead */
+  leadPrompt: string;
+  /** Suggested teammate role descriptions */
+  suggestedTeammates: string[];
+  /** Maximum number of teammates to create */
+  maxTeammates: number;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Verification
+// ═══════════════════════════════════════════════════════════════
+
+/** Result of phase verification */
+export interface VerificationResult {
+  /** Whether all checks passed */
+  passed: boolean;
+  /** Individual verification checks */
+  checks: VerificationCheck[];
+  /** Human-readable summary */
+  summary: string;
+  /** Suggestions for replanning if verification failed */
+  suggestions: string[];
+}
+
+/** A single verification check result */
+export interface VerificationCheck {
+  /** Type of check performed */
+  type: 'test_command' | 'ai_review' | 'file_check';
+  /** What was checked */
+  description: string;
+  /** Whether this check passed */
+  passed: boolean;
+  /** Command output or review text */
+  output?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Configuration
+// ═══════════════════════════════════════════════════════════════
+
+/** User-configurable orchestrator options */
+export interface OrchestratorConfig {
+  /** Model to use for plan generation (default: 'opus') */
+  plannerModel: string;
+  /** Whether to run research agent before planning (default: true) */
+  researchEnabled: boolean;
+  /** Auto-approve generated plans without user review (default: false) */
+  autoApprove: boolean;
+  /** Maximum retry attempts per phase (default: 3) */
+  maxPhaseRetries: number;
+  /** Phase execution timeout in ms (default: 1800000 = 30min) */
+  phaseTimeoutMs: number;
+  /** Enable Claude Code agent teams for parallel phases (default: true) */
+  enableTeamAgents: boolean;
+  /** Maximum parallel sessions for task execution (default: 3) */
+  maxParallelSessions: number;
+  /** Verification strictness (default: 'moderate') */
+  verificationMode: 'strict' | 'moderate' | 'lenient';
+  /** Run /compact between phases to manage context (default: true) */
+  compactBetweenPhases: boolean;
+}
+
+/** Default orchestrator configuration */
+export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
+  plannerModel: 'opus',
+  researchEnabled: true,
+  autoApprove: false,
+  maxPhaseRetries: 3,
+  phaseTimeoutMs: 30 * 60 * 1000, // 30 minutes
+  enableTeamAgents: true,
+  maxParallelSessions: 3,
+  verificationMode: 'moderate',
+  compactBetweenPhases: true,
+};
+
+// ═══════════════════════════════════════════════════════════════
+// Persistence
+// ═══════════════════════════════════════════════════════════════
+
+/** Orchestrator state persisted to ~/.codeman/state.json */
+export interface OrchestratorPersistState {
+  /** Current state machine state */
+  state: OrchestratorState;
+  /** Generated plan (null before planning) */
+  plan: OrchestratorPlan | null;
+  /** Index of currently executing phase */
+  currentPhaseIndex: number;
+  /** When orchestration started */
+  startedAt: number | null;
+  /** When orchestration completed */
+  completedAt: number | null;
+  /** User configuration */
+  config: OrchestratorConfig;
+  /** Execution statistics */
+  stats: OrchestratorStats;
+}
+
+/** Orchestrator execution statistics */
+export interface OrchestratorStats {
+  /** Number of phases completed successfully */
+  phasesCompleted: number;
+  /** Number of phases that failed (after all retries) */
+  phasesFailed: number;
+  /** Total individual tasks completed */
+  totalTasksCompleted: number;
+  /** Total individual tasks failed */
+  totalTasksFailed: number;
+  /** Total time spent executing (ms) */
+  totalDurationMs: number;
+  /** Number of times replanning was triggered */
+  replanCount: number;
+}
+
+/** Factory function for initial orchestrator stats */
+export function createInitialOrchestratorStats(): OrchestratorStats {
+  return {
+    phasesCompleted: 0,
+    phasesFailed: 0,
+    totalTasksCompleted: 0,
+    totalTasksFailed: 0,
+    totalDurationMs: 0,
+    replanCount: 0,
+  };
+}
+
+/** Factory function for initial orchestrator persist state */
+export function createInitialOrchestratorPersistState(
+  config: OrchestratorConfig = DEFAULT_ORCHESTRATOR_CONFIG
+): OrchestratorPersistState {
+  return {
+    state: 'idle',
+    plan: null,
+    currentPhaseIndex: 0,
+    startedAt: null,
+    completedAt: null,
+    config,
+    stats: createInitialOrchestratorStats(),
+  };
+}

src/web/ports/index.ts

@@ -12,3 +12,4 @@ export type { RespawnPort } from './respawn-port.js';
 export type { ConfigPort } from './config-port.js';
 export type { InfraPort, ScheduledRun } from './infra-port.js';
 export type { AuthPort, AuthSessionRecord } from './auth-port.js';
+export type { OrchestratorPort } from './orchestrator-port.js';

src/web/ports/orchestrator-port.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Orchestrator port — capabilities for orchestrator loop management.
+ * Route modules that interact with the orchestrator depend on this port.
+ */
+
+import type { OrchestratorLoop } from '../../orchestrator-loop.js';
+
+export interface OrchestratorPort {
+  readonly orchestratorLoop: OrchestratorLoop | null;
+  initOrchestratorLoop(): OrchestratorLoop;
+}

src/web/public/api-client.js

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

src/web/public/constants.js

@@ -14,8 +14,10 @@
  * @globals {Array} BUILTIN_RESPAWN_PRESETS - Built-in respawn configuration presets
  *
  * @dependency None (first in load order)
- * @loadorder 1 of 9 — constants.js → mobile-handlers.js → voice-input.js → notification-manager.js
- *   → keyboard-accessory.js → app.js → ralph-wizard.js → api-client.js → subagent-windows.js
+ * @loadorder 1 of 15 — constants.js → mobile-handlers.js → voice-input.js → notification-manager.js
+ *   → keyboard-accessory.js → input-cjk.js → app.js → terminal-ui.js → respawn-ui.js
+ *   → ralph-panel.js → settings-ui.js → panels-ui.js → session-ui.js → ralph-wizard.js
+ *   → api-client.js → subagent-windows.js
  */
 
 // Codeman — Shared constants and utility functions for frontend modules
@@ -275,6 +277,20 @@ const SSE_EVENTS = {
   PLAN_STARTED: 'plan:started',
   PLAN_CANCELLED: 'plan:cancelled',
   PLAN_COMPLETED: 'plan:completed',
+
+  // Orchestrator Loop
+  ORCHESTRATOR_STATE_CHANGED: 'orchestrator:stateChanged',
+  ORCHESTRATOR_PLAN_PROGRESS: 'orchestrator:planProgress',
+  ORCHESTRATOR_PLAN_READY: 'orchestrator:planReady',
+  ORCHESTRATOR_PHASE_STARTED: 'orchestrator:phaseStarted',
+  ORCHESTRATOR_PHASE_COMPLETED: 'orchestrator:phaseCompleted',
+  ORCHESTRATOR_PHASE_FAILED: 'orchestrator:phaseFailed',
+  ORCHESTRATOR_VERIFICATION: 'orchestrator:verification',
+  ORCHESTRATOR_TASK_ASSIGNED: 'orchestrator:taskAssigned',
+  ORCHESTRATOR_TASK_COMPLETED: 'orchestrator:taskCompleted',
+  ORCHESTRATOR_TASK_FAILED: 'orchestrator:taskFailed',
+  ORCHESTRATOR_COMPLETED: 'orchestrator:completed',
+  ORCHESTRATOR_ERROR: 'orchestrator:error',
 };
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/index.html

@@ -14,24 +14,29 @@
   <!-- xterm.css loaded async — terminal won't display until xterm.js runs anyway -->
   <link rel="preload" href="vendor/xterm.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
   <noscript><link rel="stylesheet" href="vendor/xterm.css"></noscript>
+  <!-- Preload critical resources — lets browser discover these during HTML parse
+       instead of waiting until <script> tags at bottom-of-body are reached. -->
+  <link rel="preload" href="vendor/xterm.min.js" as="script">
+  <link rel="preload" href="constants.js" as="script">
+  <link rel="preload" href="app.js" as="script">
   <!-- Self-hosted xterm.js — eliminates CDN DNS/TLS latency (~100ms).
        'defer' preserves execution order (xterm loads before fit addon). -->
   <script defer src="vendor/xterm.min.js"></script>
   <script defer src="vendor/xterm-addon-fit.min.js"></script>
-  <script defer src="vendor/xterm-addon-webgl.min.js"></script>
+  <!-- WebGL addon lazy-loaded by app.js on desktop only (skipped on mobile, saving 244KB) -->
   <script defer src="vendor/xterm-addon-unicode11.min.js"></script>
   <script defer src="vendor/xterm-zerolag-input.js"></script>
   <!-- Synchronous mobile detection — runs before first paint to prevent panel flash -->
   <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) -->
   <style>
-    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#0a0a0a}
-    .skeleton-header{height:40px;background:#111;border-bottom:1px solid #1a1a2e;display:flex;align-items:center;padding:0 12px}
-    .skeleton-brand{color:#60a5fa;font-size:14px;font-weight:600;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.7}
+    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#09090b}
+    .skeleton-header{height:40px;background:rgba(19,19,22,0.85);border-bottom:1px solid rgba(255,255,255,0.06);display:flex;align-items:center;padding:0 12px}
+    .skeleton-brand{color:#60a5fa;font-size:14px;font-weight:700;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.7}
     .skeleton-tabs{display:flex;gap:4px;margin-left:16px}
-    .skeleton-tab{width:80px;height:24px;background:#1a1a2e;border-radius:4px}
+    .skeleton-tab{width:80px;height:24px;background:rgba(255,255,255,0.04);border-radius:6px}
     .skeleton-terminal{flex:1;background:#0d0d0d}
-    .skeleton-toolbar{height:32px;background:#111;border-top:1px solid #1a1a2e}
+    .skeleton-toolbar{height:42px;background:rgba(19,19,22,0.85);border-top:1px solid rgba(255,255,255,0.06)}
     .app-loaded .loading-skeleton{display:none}
   </style>
 </head>
@@ -132,6 +137,17 @@
       </div>
     </div>
 
+    <!-- Orchestrator Loop Panel -->
+    <div class="orchestrator-panel" id="orchestratorPanel" style="display: none;">
+      <div class="orchestrator-header">
+        <span class="orchestrator-title">Orchestrator</span>
+        <span class="orchestrator-state-badge" id="orchestratorStateBadge">idle</span>
+        <div class="orchestrator-actions" id="orchestratorActions"></div>
+        <button class="orchestrator-close-btn" onclick="app.closeOrchestratorPanel()" title="Close">&times;</button>
+      </div>
+      <div class="orchestrator-body" id="orchestratorBody"></div>
+    </div>
+
     <!-- Ralph / Todo Tracker Panel -->
     <div class="ralph-panel collapsed" id="ralphStatePanel" style="display: none;">
       <!-- Collapsed Summary Bar -->
@@ -417,6 +433,8 @@
       </div>
 
       <div class="toolbar-right">
+        <!-- Orchestrator button hidden until feature is ready -->
+        <!-- <button class="btn-toolbar btn-sm" onclick="app.toggleOrchestratorPanel()" title="Orchestrator Loop">&#x2699; Orchestrator</button> -->
         <span class="version-display" id="versionDisplay" title="Codeman version">v0.0.0</span>
       </div>
     </footer>
@@ -853,6 +871,16 @@
                   <span class="slider"></span>
                 </label>
               </div>
+              <div class="settings-item settings-item-multiline" title="Show a dedicated input field below the terminal for CJK (Chinese/Japanese/Korean) IME composition. Recommended for mobile devices with Chinese input methods where xterm's native input handling may drop characters.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">CJK Input</span>
+                  <span class="settings-item-desc">Dedicated IME input field for CJK languages</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsCjkInput">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Header Displays Section -->
               <div class="settings-section-header">Header Displays</div>
@@ -1696,6 +1724,13 @@
   <script defer src="keyboard-accessory.js"></script>
   <script defer src="input-cjk.js"></script>
   <script defer src="app.js"></script>
+  <script defer src="terminal-ui.js"></script>
+  <script defer src="respawn-ui.js"></script>
+  <script defer src="ralph-panel.js"></script>
+  <script defer src="orchestrator-panel.js"></script>
+  <script defer src="settings-ui.js"></script>
+  <script defer src="panels-ui.js"></script>
+  <script defer src="session-ui.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
   <script defer src="subagent-windows.js"></script>

src/web/public/input-cjk.js

@@ -3,13 +3,39 @@
  *
  * Always-visible textarea below the terminal (in index.html).
  * The browser handles IME composition natively — we just read
- * textarea.value on Enter and send it to PTY.
+ * textarea.value and send it to PTY.
  * While this textarea has focus, window.cjkActive = true blocks xterm's onData.
  * Arrow keys and function keys are forwarded to PTY directly.
  *
+ * ## Android IME challenge
+ *
+ * Android virtual keyboards (WeChat, Sogou, Gboard in Chinese mode) use
+ * composition for EVERYTHING — including English prediction and punctuation.
+ * This means compositionstart fires even for English text, and compositionend
+ * may not fire until the user explicitly confirms (space, candidate tap).
+ *
+ * We use InputEvent.inputType to distinguish:
+ * - `insertCompositionText`: tentative text, may change (CJK candidates, pinyin)
+ * - `insertText`: final committed text (confirmed word, punctuation, space)
+ *
+ * During composition, `insertText` events are flushed immediately (punctuation,
+ * English words confirmed by IME). `insertCompositionText` waits for
+ * compositionend (CJK candidate selection).
+ *
+ * ## Phantom character for Android backspace
+ *
+ * Android virtual keyboards don't generate key-repeat keydown events for held
+ * keys. When the textarea is empty, backspace produces no `input` event either
+ * (nothing to delete). We keep a zero-width space (U+200B) "phantom" in the
+ * textarea at all times. Backspace deletes the phantom → `input` fires with
+ * `deleteContentBackward` → we send \x7f to PTY and restore the phantom.
+ * Long-press backspace generates rapid deleteContentBackward events, each
+ * handled the same way — giving continuous deletion at the keyboard's native
+ * repeat rate.
+ *
  * @dependency index.html (#cjkInput textarea)
  * @globals {object} CjkInput — window.cjkActive (boolean) signals app.js to block xterm onData
- * @loadorder 5.5 of 10 — loaded after keyboard-accessory.js, before app.js
+ * @loadorder 5.5 of 15 — loaded after keyboard-accessory.js, before app.js
  */
 
 // eslint-disable-next-line no-unused-vars
@@ -17,10 +43,12 @@ const CjkInput = (() => {
   let _textarea = null;
   let _send = null;
   let _initialized = false;
-  let _onMousedown = null;
-  let _onFocus = null;
-  let _onBlur = null;
-  let _onKeydown = null;
+  let _composing = false;
+  const _listeners = {};
+
+  // Zero-width space: always present in textarea so Android backspace has
+  // something to delete, triggering the `input` event we need to detect it.
+  const PHANTOM = '\u200B';
 
   const PASSTHROUGH_KEYS = {
     ArrowUp:    '\x1b[A',
@@ -36,66 +64,176 @@ const CjkInput = (() => {
     c: '\x03', d: '\x04', l: '\x0c', z: '\x1a', a: '\x01', e: '\x05',
   };
 
+  /** Strip phantom characters from a string */
+  function _strip(str) {
+    return str.replace(/\u200B/g, '');
+  }
+
+  /** Reset textarea to phantom-only state with cursor at end */
+  function _resetToPhantom() {
+    _textarea.value = PHANTOM;
+    _textarea.setSelectionRange(1, 1);
+  }
+
+  /** Check if textarea contains only phantom(s) or is empty — no real user text */
+  function _isEffectivelyEmpty() {
+    return !_strip(_textarea.value);
+  }
+
+  /** Flush textarea: send real text to PTY and reset to phantom */
+  function _flush() {
+    const val = _strip(_textarea.value);
+    if (val) {
+      _send(val);
+    }
+    _resetToPhantom();
+  }
+
   return {
     init({ send }) {
-      // Guard against double-init: remove previous listeners
       if (_initialized) this.destroy();
 
       _send = send;
+      _composing = false;
       _textarea = document.getElementById('cjkInput');
       if (!_textarea) return this;
 
-      _onMousedown = (e) => { e.stopPropagation(); };
-      _onFocus = () => { window.cjkActive = true; };
-      _onBlur = () => { window.cjkActive = false; };
-      _textarea.addEventListener('mousedown', _onMousedown);
-      _textarea.addEventListener('focus', _onFocus);
-      _textarea.addEventListener('blur', _onBlur);
+      // Seed the phantom character
+      _resetToPhantom();
 
-      _onKeydown = (e) => {
-        if (e.isComposing || e.keyCode === 229) return;
+      _listeners.mousedown = (e) => { e.stopPropagation(); };
+      _listeners.focus = () => {
+        window.cjkActive = true;
+        // Restore phantom if textarea was emptied while blurred
+        if (!_textarea.value) _resetToPhantom();
+      };
+      _listeners.blur = () => { window.cjkActive = false; };
+      _textarea.addEventListener('mousedown', _listeners.mousedown);
+      _textarea.addEventListener('focus', _listeners.focus);
+      _textarea.addEventListener('blur', _listeners.blur);
 
-        // Enter: send accumulated text (or bare Enter if empty)
+      // ── Composition tracking ──
+      _listeners.compositionstart = () => {
+        _composing = true;
+        // Clear phantom so IME sees a clean textarea — some IMEs include
+        // existing text in the composition region which would corrupt input.
+        if (_textarea.value === PHANTOM) {
+          _textarea.value = '';
+        }
+      };
+      _listeners.compositionend = () => {
+        _composing = false;
+        // Defer flush: some Android IMEs haven't committed text to textarea
+        // when compositionend fires. setTimeout(0) ensures we read the final value.
+        setTimeout(_flush, 0);
+      };
+      _textarea.addEventListener('compositionstart', _listeners.compositionstart);
+      _textarea.addEventListener('compositionend', _listeners.compositionend);
+
+      // ── Keydown: special keys work REGARDLESS of composition state ──
+      _listeners.keydown = (e) => {
+        // Enter: flush accumulated text (or bare Enter if empty).
+        // No isComposing guard — Android IMEs set isComposing=true for English
+        // prediction, but Enter should ALWAYS send. We preventDefault to stop
+        // the IME from also handling Enter (which could double-send or do nothing).
         if (e.key === 'Enter') {
           e.preventDefault();
-          if (_textarea.value) {
-            _send(_textarea.value + '\r');
-            _textarea.value = '';
+          _composing = false;
+          const val = _strip(_textarea.value);
+          if (val) {
+            _send(val + '\r');
           } else {
             _send('\r');
           }
+          _resetToPhantom();
           return;
         }
 
-        // Escape: clear textarea
+        // Escape: clear textarea (always works)
         if (e.key === 'Escape') {
           e.preventDefault();
-          _textarea.value = '';
+          _composing = false;
+          _resetToPhantom();
           return;
         }
 
-        // Ctrl combos: forward to PTY
+        // Ctrl combos: forward to PTY (always works)
         if (e.ctrlKey && CTRL_KEYS[e.key]) {
           e.preventDefault();
           _send(CTRL_KEYS[e.key]);
           return;
         }
 
-        // Backspace: delete from textarea if has text, else forward to PTY
-        if (e.key === 'Backspace' && !_textarea.value) {
+        // Below: only when NOT composing (composing keystrokes belong to IME)
+        if (_composing) return;
+
+        // Backspace: forward to PTY when no real text in textarea
+        // (Desktop path — Android uses the input event + phantom approach)
+        if (e.key === 'Backspace' && _isEffectivelyEmpty()) {
           e.preventDefault();
           _send('\x7f');
+          _resetToPhantom();
           return;
         }
 
-        // Arrow/function keys: forward to PTY when textarea is empty
-        if (PASSTHROUGH_KEYS[e.key] && !_textarea.value) {
+        // Arrow/function keys: forward to PTY when no real text
+        if (PASSTHROUGH_KEYS[e.key] && _isEffectivelyEmpty()) {
           e.preventDefault();
           _send(PASSTHROUGH_KEYS[e.key]);
           return;
         }
+
+        // Single printable character: send immediately to PTY
+        // (Desktop keyboards with physical keys — Android sends 'Unidentified')
+        if (e.key.length === 1 && !e.ctrlKey && !e.altKey && !e.metaKey && _isEffectivelyEmpty()) {
+          e.preventDefault();
+          _send(e.key);
+          return;
+        }
       };
-      _textarea.addEventListener('keydown', _onKeydown);
+      _textarea.addEventListener('keydown', _listeners.keydown);
+
+      // ── Input event: the primary path for Android virtual keyboards ──
+      // Android sends keyCode 229 + key "Unidentified" for virtual key presses,
+      // making keydown unreliable. input fires AFTER character insertion and
+      // carries inputType which tells us whether the text is final or tentative.
+      _listeners.input = (e) => {
+        // ── Backspace / delete detection ──
+        // Android long-press backspace generates rapid deleteContentBackward events.
+        // The phantom character ensures the textarea is never truly empty, so each
+        // press/repeat fires an input event that we can catch here.
+        if (e.inputType === 'deleteContentBackward' || e.inputType === 'deleteWordBackward') {
+          if (_isEffectivelyEmpty()) {
+            // No real text left — forward backspace to PTY
+            _send('\x7f');
+            _resetToPhantom();
+            return;
+          }
+          // User is editing their own text in the textarea — let it be.
+          // Ensure phantom is still present for the NEXT backspace.
+          if (!_textarea.value.startsWith(PHANTOM)) {
+            _textarea.value = PHANTOM + _textarea.value;
+            _textarea.setSelectionRange(1, 1);
+          }
+          return;
+        }
+
+        if (_composing) {
+          // insertText during composition = IME committed final text
+          // (e.g., punctuation key inserts 。directly, or IME confirms a word).
+          // Flush immediately — this text won't change.
+          if (e.inputType === 'insertText') {
+            _flush();
+            return;
+          }
+          // insertCompositionText = IME is still working (pinyin, candidates,
+          // English prediction). Wait for compositionend to flush.
+          return;
+        }
+        // Outside composition: send immediately
+        _flush();
+      };
+      _textarea.addEventListener('input', _listeners.input);
 
       _initialized = true;
       return this;
@@ -103,13 +241,13 @@ const CjkInput = (() => {
 
     destroy() {
       if (_textarea) {
-        if (_onMousedown) _textarea.removeEventListener('mousedown', _onMousedown);
-        if (_onFocus) _textarea.removeEventListener('focus', _onFocus);
-        if (_onBlur) _textarea.removeEventListener('blur', _onBlur);
-        if (_onKeydown) _textarea.removeEventListener('keydown', _onKeydown);
+        for (const [event, handler] of Object.entries(_listeners)) {
+          if (handler) _textarea.removeEventListener(event, handler);
+        }
       }
       window.cjkActive = false;
-      _onMousedown = _onFocus = _onBlur = _onKeydown = null;
+      _composing = false;
+      for (const key of Object.keys(_listeners)) delete _listeners[key];
       _initialized = false;
     },
 

src/web/public/keyboard-accessory.js

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

src/web/public/mobile-handlers.js

@@ -19,7 +19,7 @@
  * @globals {object} SwipeHandler
  *
  * @dependency keyboard-accessory.js (KeyboardAccessoryBar reference in KeyboardHandler.onKeyboardShow, soft — guarded with typeof check)
- * @loadorder 2 of 9 — loaded after constants.js, before voice-input.js
+ * @loadorder 2 of 15 — loaded after constants.js, before voice-input.js
  */
 
 // Codeman — Mobile detection, keyboard handling, and swipe navigation
@@ -36,15 +36,19 @@
 const MobileDetection = {
   /** Check if device supports touch input */
   isTouchDevice() {
-    return 'ontouchstart' in window ||
+    return (
+      'ontouchstart' in window ||
       navigator.maxTouchPoints > 0 ||
-      (window.matchMedia && window.matchMedia('(pointer: coarse)').matches);
+      (window.matchMedia && window.matchMedia('(pointer: coarse)').matches)
+    );
   },
 
   /** Check if device is iOS (iPhone, iPad, iPod) */
   isIOS() {
-    return /iPad|iPhone|iPod/.test(navigator.userAgent) ||
-      (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
+    return (
+      /iPad|iPhone|iPod/.test(navigator.userAgent) ||
+      (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1)
+    );
   },
 
   /** Check if browser is Safari */
@@ -77,7 +81,14 @@ const MobileDetection = {
     const isTouch = this.isTouchDevice();
 
     // Remove existing device classes
-    body.classList.remove('device-mobile', 'device-tablet', 'device-desktop', 'touch-device', 'ios-device', 'safari-browser');
+    body.classList.remove(
+      'device-mobile',
+      'device-tablet',
+      'device-desktop',
+      'touch-device',
+      'ios-device',
+      'safari-browser'
+    );
 
     // Add current device class
     body.classList.add(`device-${deviceType}`);
@@ -100,8 +111,12 @@ const MobileDetection = {
 
   /** Set --app-height CSS variable from visual viewport.
    *  On iPad Safari with tabs, 100vh extends behind the tab bar.
-   *  visualViewport.height reflects the actual visible area. */
+   *  visualViewport.height reflects the actual visible area.
+   *  Skips when virtual keyboard is open — KeyboardHandler manages
+   *  layout via translateY + paddingBottom; shrinking --app-height
+   *  would double-count and leave zero space for the terminal. */
   updateAppHeight() {
+    if (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) return;
     const vh = window.visualViewport?.height || window.innerHeight;
     document.documentElement.style.setProperty('--app-height', `${vh}px`);
   },
@@ -149,7 +164,7 @@ const MobileDetection = {
       this._gestureStartHandler = null;
       this._gestureChangeHandler = null;
     }
-  }
+  },
 };
 
 // ═══════════════════════════════════════════════════════════════
@@ -198,6 +213,17 @@ const KeyboardHandler = {
       // Also handle scroll (iOS scrolls viewport when keyboard appears)
       window.visualViewport.addEventListener('scroll', this._viewportScrollHandler);
     }
+
+    // Prevent page-level scroll when keyboard is visible.
+    // iOS Safari scrolls the document to bring xterm's hidden textarea into
+    // view when the user types, pushing the entire UI off-screen. The CSS
+    // position:fixed on .app prevents most cases, but reset as a safety net.
+    this._windowScrollHandler = () => {
+      if (this.keyboardVisible) {
+        window.scrollTo(0, 0);
+      }
+    };
+    window.addEventListener('scroll', this._windowScrollHandler);
   },
 
   /** Remove event listeners */
@@ -214,6 +240,10 @@ const KeyboardHandler = {
       window.visualViewport.removeEventListener('scroll', this._viewportScrollHandler);
       this._viewportScrollHandler = null;
     }
+    if (this._windowScrollHandler) {
+      window.removeEventListener('scroll', this._windowScrollHandler);
+      this._windowScrollHandler = null;
+    }
   },
 
   /** Handle viewport resize (keyboard show/hide) */
@@ -225,6 +255,10 @@ const KeyboardHandler = {
     if (heightDiff > 150 && !this.keyboardVisible) {
       this.keyboardVisible = true;
       document.body.classList.add('keyboard-visible');
+      // Restore --app-height: MobileDetection's resize listener fires before ours
+      // and may have already shrunk it for the keyboard viewport change.
+      // Use initialViewportHeight (captured before keyboard opened).
+      document.documentElement.style.setProperty('--app-height', `${this.initialViewportHeight}px`);
       this.onKeyboardShow();
     }
     // Keyboard hidden (viewport grew back close to initial)
@@ -234,6 +268,9 @@ const KeyboardHandler = {
       this.keyboardVisible = false;
       document.body.classList.remove('keyboard-visible');
       this.onKeyboardHide();
+      // Re-sync --app-height now that keyboard is gone (MobileDetection skipped
+      // updates while keyboardVisible was true)
+      MobileDetection.updateAppHeight();
     }
 
     // Update baseline when keyboard is not visible — adapts to address bar
@@ -261,35 +298,32 @@ const KeyboardHandler = {
     const main = document.querySelector('.main');
 
     if (this.keyboardVisible) {
-      // Calculate keyboard offset
+      // Calculate how far the toolbar (position:fixed, bottom:0) needs to
+      // translate up so it sits at the bottom of the visual viewport.
+      // This formula accounts for iOS scrolling the visual viewport (offsetTop)
+      // when the user types in xterm's hidden textarea.
       const layoutHeight = window.innerHeight;
       const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
-      const keyboardOffset = layoutHeight - visualBottom;
+      const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
 
-      // Safety: if keyboard is supposedly visible but offset is 0 or negative,
-      // the keyboard is actually gone — force dismiss. This catches cases where
-      // visualViewport.resize fires late or with intermediate values on iOS.
-      if (keyboardOffset <= 0) {
-        this.keyboardVisible = false;
-        document.body.classList.remove('keyboard-visible');
-        this.onKeyboardHide();
-        return;
-      }
-
-      // Move toolbar up above keyboard
+      // Move toolbar and accessory bar above keyboard.
+      // When keyboardOffset is 0 (viewport scrolled to layout bottom),
+      // the bars are naturally positioned via their CSS bottom values —
+      // just clear the transforms.  Never dismiss keyboard state here;
+      // that's handleViewportResize's job.
       if (toolbar) {
-        toolbar.style.transform = `translateY(${-keyboardOffset}px)`;
+        toolbar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
       }
-
-      // Move accessory bar up (it sits above toolbar)
       if (accessoryBar) {
-        accessoryBar.style.transform = `translateY(${-keyboardOffset}px)`;
+        accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
       }
 
-      // Shrink main content area so terminal doesn't extend behind keyboard
-      // Account for keyboard height + toolbar height (40px) + accessory bar (44px)
-      if (main) {
-        main.style.paddingBottom = `${keyboardOffset + 94}px`;
+      // Shrink main content area so terminal doesn't extend behind keyboard.
+      // Use stable keyboard height (not scroll-dependent) for padding.
+      // 84px = toolbar (40px) + accessory bar (44px).
+      const keyboardHeight = this.initialViewportHeight - (window.visualViewport.height || window.innerHeight);
+      if (main && keyboardHeight > 0) {
+        main.style.paddingBottom = `${keyboardHeight + 84}px`;
       }
     } else {
       this.resetLayout();
@@ -320,6 +354,10 @@ const KeyboardHandler = {
       KeyboardAccessoryBar.show();
     }
 
+    // Reset any page scroll that occurred during keyboard open.
+    // iOS Safari may scroll the document to reveal xterm's hidden textarea.
+    window.scrollTo(0, 0);
+
     // Refit terminal locally AND send resize to server so Claude Code (Ink)
     // knows the actual terminal dimensions. Without this, Ink redraws at the
     // old (larger) row count when the user types, causing content to scroll
@@ -328,11 +366,21 @@ const KeyboardHandler = {
     // while keyboard is up — this one-shot resize on open/close is sufficient.
     setTimeout(() => {
       if (typeof app !== 'undefined' && app.terminal) {
-        if (app.fitAddon) try { app.fitAddon.fit(); } catch {}
+        if (app.fitAddon)
+          try {
+            app.fitAddon.fit();
+          } catch {}
+        // Eliminate terminal row quantization gap: xterm can only show whole
+        // rows, so leftover pixels create dead space below the last row.
+        // Shrink .main's paddingBottom by the gap so the terminal fills flush
+        // to the accessory bar.
+        this._shrinkPaddingToFit();
         app.terminal.scrollToBottom();
         // Send resize to server so PTY dimensions match xterm
         this._sendTerminalResize();
       }
+      // Reset again after fit/resize in case layout changes triggered scroll
+      window.scrollTo(0, 0);
     }, 150);
 
     // Reposition subagent windows to stack from bottom (above keyboard)
@@ -351,7 +399,9 @@ const KeyboardHandler = {
     // Refit terminal, scroll to bottom, and send resize to restore original dimensions
     setTimeout(() => {
       if (typeof app !== 'undefined' && app.fitAddon) {
-        try { app.fitAddon.fit(); } catch {}
+        try {
+          app.fitAddon.fit();
+        } catch {}
         if (app.terminal) app.terminal.scrollToBottom();
         // Send resize to server to restore full terminal size
         this._sendTerminalResize();
@@ -374,12 +424,37 @@ const KeyboardHandler = {
         fetch(`/api/sessions/${app.activeSessionId}/resize`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ cols, rows })
+          body: JSON.stringify({ cols, rows }),
         }).catch(() => {});
       }
     } catch {}
   },
 
+  /**
+   * Shrink .main paddingBottom to eliminate the terminal row quantization gap.
+   * xterm can only render whole rows, so fractional-row pixels create dead
+   * space below the last row. After fitAddon.fit(), measure the gap and
+   * reduce padding by that amount so the terminal sits flush against the bars.
+   */
+  _shrinkPaddingToFit() {
+    try {
+      const container = document.getElementById('terminalContainer');
+      const main = document.querySelector('.main');
+      if (!container || !main || typeof app === 'undefined' || !app.terminal) return;
+      const cellH = app.terminal._core?._renderService?.dimensions?.css?.cell?.height;
+      if (!cellH) return;
+      const gap = container.clientHeight - app.terminal.rows * cellH;
+      if (gap > 0 && gap < cellH) {
+        const currentPadding = parseInt(main.style.paddingBottom) || 0;
+        main.style.paddingBottom = Math.max(0, currentPadding - gap) + 'px';
+        if (app.fitAddon)
+          try {
+            app.fitAddon.fit();
+          } catch {}
+      }
+    } catch {}
+  },
+
   /** Check if element is an input that triggers keyboard (excludes terminal) */
   isInputElement(el) {
     if (!el) return false;
@@ -397,11 +472,7 @@ const KeyboardHandler = {
         return false;
       }
     }
-    return (
-      tagName === 'input' ||
-      tagName === 'textarea' ||
-      el.isContentEditable
-    );
+    return tagName === 'input' || tagName === 'textarea' || el.isContentEditable;
   },
 
   /** Scroll input into view above the keyboard */
@@ -427,7 +498,7 @@ const KeyboardHandler = {
       // For page-level - use scrollIntoView
       input.scrollIntoView({ block: 'center', behavior: 'smooth' });
     }
-  }
+  },
 };
 
 // ═══════════════════════════════════════════════════════════════
@@ -442,8 +513,8 @@ const SwipeHandler = {
   startX: 0,
   startY: 0,
   startTime: 0,
-  minSwipeDistance: 80,  // Minimum pixels for a valid swipe
-  maxSwipeTime: 300,     // Maximum ms for a swipe gesture
+  minSwipeDistance: 80, // Minimum pixels for a valid swipe
+  maxSwipeTime: 300, // Maximum ms for a swipe gesture
   maxVerticalDrift: 100, // Max vertical movement allowed
 
   _touchStartHandler: null,
@@ -494,9 +565,9 @@ const SwipeHandler = {
     const deltaX = endX - this.startX;
     const deltaY = Math.abs(endY - this.startY);
 
-    if (elapsed > this.maxSwipeTime) return;  // Too slow
-    if (deltaY > this.maxVerticalDrift) return;  // Too much vertical movement
-    if (Math.abs(deltaX) < this.minSwipeDistance) return;  // Too short
+    if (elapsed > this.maxSwipeTime) return; // Too slow
+    if (deltaY > this.maxVerticalDrift) return; // Too much vertical movement
+    if (Math.abs(deltaX) < this.minSwipeDistance) return; // Too short
 
     // Valid swipe detected
     if (deltaX > 0) {
@@ -506,5 +577,5 @@ const SwipeHandler = {
       // Swipe left -> next session
       if (typeof app !== 'undefined') app.nextSession();
     }
-  }
+  },
 };

src/web/public/mobile.css

@@ -327,15 +327,27 @@ html.mobile-init .file-browser-panel {
     max-height: calc(36px + var(--safe-area-top));
   }
 
-  /* Add top margin to main content to account for fixed header */
+  /* Add top margin to main content to account for fixed header,
+     and bottom padding for the fixed toolbar (40px) so terminal
+     content doesn't extend behind it. JS overrides paddingBottom
+     when keyboard is visible, and resetLayout() clears the inline
+     style to re-expose this CSS value. */
   .main {
     margin-top: 42px;
+    padding-bottom: calc(40px + var(--safe-area-bottom));
   }
 
   .ios-device .main {
     margin-top: calc(42px + var(--safe-area-top));
   }
 
+  /* iOS Safari: toolbar is pushed up by (100vh - --app-height) to clear the
+     browser's bottom bar. Match that offset in main's padding so the terminal
+     doesn't extend behind the toolbar. */
+  .ios-device.safari-browser .main {
+    padding-bottom: calc(40px + var(--safe-area-bottom) + (100vh - var(--app-height, 100vh)));
+  }
+
   .header-right {
     padding-left: 0.2rem;
     gap: 0.1rem;
@@ -428,6 +440,18 @@ html.mobile-init .file-browser-panel {
     position: relative;
   }
 
+  /* When keyboard is visible, pin the app container to the viewport.
+     iOS Safari scrolls the page to bring the focused input (xterm's hidden
+     textarea) into view, even with overflow:hidden. position:fixed prevents
+     the browser from scrolling the document under the app. */
+  .keyboard-visible .app {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+  }
+
   /* Ultra-compact session tabs — .tabs-two-rows override needed to match
      specificity of .session-tabs.tabs-two-rows in styles.css (0,2,0) */
   .session-tabs,
@@ -534,6 +558,17 @@ html.mobile-init .file-browser-panel {
     bottom: calc(var(--safe-area-bottom) + (100vh - var(--app-height, 100vh)));
   }
 
+  /* When keyboard is visible the JS translateY already accounts for the full
+     distance from the visual-viewport bottom to the layout-viewport bottom
+     (keyboard + Safari bar).  Remove the CSS Safari-bar offset to avoid
+     double-counting, which otherwise creates a visible gap above the keyboard. */
+  .keyboard-visible.ios-device.safari-browser .toolbar {
+    bottom: var(--safe-area-bottom);
+  }
+  .keyboard-visible.ios-device.safari-browser .keyboard-accessory-bar {
+    bottom: calc(var(--safe-area-bottom) + 40px);
+  }
+
   /* Show case selector in center */
   .toolbar-center {
     display: flex !important;
@@ -1093,40 +1128,26 @@ html.mobile-init .file-browser-panel {
     display: block;
   }
 
-  /* Mobile terminal - native touch scrolling via xterm-viewport */
+  /* Mobile terminal — JS touch handler (terminal.scrollLines()) drives
+     scrollback because xterm.js DOM renderer doesn't populate xterm-viewport's
+     scroll area.  touch-action:none lets our JS handler own the gesture. */
   .terminal-container {
     height: 100%;
     min-height: 0;
     position: relative;
-    overflow: visible; /* Must not be hidden — blocks touch scroll on viewport */
-    touch-action: pan-y;
-  }
-
-  .terminal-container .xterm {
-    touch-action: pan-y;
-  }
-
-  /* xterm-viewport is the scrollable element inside xterm.js.
-     It must sit above xterm-screen to receive touch events.
-     See: https://github.com/xtermjs/xterm.js/issues/5377 */
-  .terminal-container .xterm-viewport {
-    position: absolute !important;
-    top: 0 !important;
-    left: 0 !important;
-    right: 0 !important;
-    bottom: 0 !important;
-    z-index: 10 !important;
-    touch-action: pan-y;
-    -webkit-overflow-scrolling: touch;
-    overflow-y: scroll !important;
+    overflow: visible;
+    touch-action: none;
   }
 
+  .terminal-container .xterm,
+  .terminal-container .xterm-viewport,
   .terminal-container .xterm-screen {
-    touch-action: pan-y;
+    touch-action: none;
   }
 
   /* Compact welcome overlay for mobile */
   .welcome-content {
+    max-width: calc(100vw - 1.5rem);
     padding: 1rem 0.75rem;
   }
 
@@ -1563,11 +1584,9 @@ html.mobile-init .file-browser-panel {
     scroll-margin-top: 80px;
   }
 
-  /* When keyboard is visible, adjust content to account for moved toolbar */
-  .keyboard-visible .terminal-container {
-    /* Reduce terminal height when keyboard is up so it doesn't overlap toolbar */
-    padding-bottom: 50px;
-  }
+  /* When keyboard is visible, the JS paddingBottom on .main already reserves
+     space for toolbar + accessory bar. No extra padding needed here — it was
+     double-counting and creating dead space between terminal and the bars. */
 
   /* Ensure modals scroll properly when keyboard is visible */
   .keyboard-visible .modal-body {
@@ -2028,14 +2047,8 @@ html.mobile-init .file-browser-panel {
   overscroll-behavior: none;
 }
 
-.ios-device.safari-browser .terminal-container {
-  /* Keep momentum scrolling but prevent page bounce */
-  -webkit-overflow-scrolling: touch;
-}
-
-.ios-device.safari-browser .terminal-container .xterm-viewport {
-  -webkit-overflow-scrolling: touch;
-}
+/* JS touch handler now drives terminal scrollback — no native scroll needed.
+   -webkit-overflow-scrolling and overflow-y:scroll on xterm-viewport removed. */
 
 /* ============================================================================
    Hover State Fallbacks for Touch

src/web/public/notification-manager.js

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

src/web/public/orchestrator-panel.js

@@ -0,0 +1,475 @@
+/**
+ * @fileoverview Orchestrator loop panel — plan-based autonomous execution UI.
+ * Shows orchestrator state, plan phases, task progress, and verification results.
+ * Provides controls for start, approve, reject, pause, resume, stop, skip, retry.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (CodemanApp class, this.orchestratorState)
+ * @dependency constants.js (SSE_EVENTS, escapeHtml)
+ * @loadorder 9.5 of 16 — loaded after ralph-panel.js, before settings-ui.js
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// State color/label mappings
+// ═══════════════════════════════════════════════════════════════
+
+const ORCH_STATE_COLORS = {
+  idle: '#6b7280',
+  planning: '#f59e0b',
+  approval: '#8b5cf6',
+  executing: '#3b82f6',
+  verifying: '#06b6d4',
+  replanning: '#f97316',
+  completed: '#22c55e',
+  failed: '#ef4444',
+  paused: '#9ca3af',
+};
+
+const ORCH_PHASE_STATUS_ICONS = {
+  pending: '\u25cb',    // ○
+  executing: '\u25d4',  // ◔
+  passed: '\u2713',     // ✓
+  failed: '\u2717',     // ✗
+  skipped: '\u2192',    // →
+};
+
+Object.assign(CodemanApp.prototype, {
+
+  // ═══════════════════════════════════════════════════════════════
+  // SSE Event Handlers
+  // ═══════════════════════════════════════════════════════════════
+
+  _onOrchestratorStateChanged(data) {
+    if (!this.orchestratorState) this.orchestratorState = {};
+    this.orchestratorState.state = data.state;
+    if (data.state === 'planning') {
+      this.orchestratorState.planProgress = [];
+      this.showOrchestratorPanel();
+    }
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorPlanProgress(data) {
+    if (!this.orchestratorState) this.orchestratorState = {};
+    if (!this.orchestratorState.planProgress) this.orchestratorState.planProgress = [];
+    this.orchestratorState.planProgress.push({ phase: data.phase, detail: data.detail, time: Date.now() });
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorPlanReady(data) {
+    if (!this.orchestratorState) this.orchestratorState = {};
+    this.orchestratorState.plan = data.plan;
+    this.orchestratorState.state = 'approval';
+    this.showOrchestratorPanel();
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorPhaseStarted(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorPhase(data.phase);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorPhaseCompleted(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorPhase(data.phase);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorPhaseFailed(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorPhase(data.phase);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorVerification(data) {
+    if (!this.orchestratorState) return;
+    // Store verification result on the phase
+    if (this.orchestratorState.plan) {
+      const phase = this.orchestratorState.plan.phases.find(p => p.id === data.phaseId);
+      if (phase) phase._lastVerification = data.result;
+    }
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorTaskAssigned(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorTask(data.task);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorTaskCompleted(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorTask(data.task);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorTaskFailed(data) {
+    if (!this.orchestratorState) return;
+    this._updateOrchestratorTask(data.task);
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorCompleted(data) {
+    if (!this.orchestratorState) this.orchestratorState = {};
+    this.orchestratorState.state = 'completed';
+    this.orchestratorState.stats = data.stats;
+    this.renderOrchestratorPanel();
+  },
+
+  _onOrchestratorError(data) {
+    if (!this.orchestratorState) this.orchestratorState = {};
+    this.orchestratorState.state = 'failed';
+    this.orchestratorState.lastError = data.error;
+    this.renderOrchestratorPanel();
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Internal helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  _updateOrchestratorPhase(updatedPhase) {
+    if (!this.orchestratorState?.plan) return;
+    const idx = this.orchestratorState.plan.phases.findIndex(p => p.id === updatedPhase.id);
+    if (idx >= 0) this.orchestratorState.plan.phases[idx] = updatedPhase;
+  },
+
+  _updateOrchestratorTask(updatedTask) {
+    if (!this.orchestratorState?.plan) return;
+    for (const phase of this.orchestratorState.plan.phases) {
+      const idx = phase.tasks.findIndex(t => t.id === updatedTask.id);
+      if (idx >= 0) {
+        phase.tasks[idx] = updatedTask;
+        return;
+      }
+    }
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Panel visibility
+  // ═══════════════════════════════════════════════════════════════
+
+  showOrchestratorPanel() {
+    this.orchestratorPanelVisible = true;
+    const panel = document.getElementById('orchestratorPanel');
+    if (panel) panel.style.display = '';
+    this.renderOrchestratorPanel();
+  },
+
+  closeOrchestratorPanel() {
+    this.orchestratorPanelVisible = false;
+    const panel = document.getElementById('orchestratorPanel');
+    if (panel) panel.style.display = 'none';
+  },
+
+  toggleOrchestratorPanel() {
+    if (this.orchestratorPanelVisible) {
+      this.closeOrchestratorPanel();
+    } else {
+      this.showOrchestratorPanel();
+    }
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // API calls
+  // ═══════════════════════════════════════════════════════════════
+
+  async orchestratorStart(goal, config) {
+    try {
+      const res = await fetch('/api/orchestrator/start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ goal, config }),
+      });
+      const data = await res.json();
+      if (data.ok) {
+        this.orchestratorState = { state: 'planning', plan: null };
+        this.showOrchestratorPanel();
+        this.renderOrchestratorPanel();
+      }
+      return data;
+    } catch (err) {
+      console.error('[Orchestrator] Start failed:', err);
+    }
+  },
+
+  async orchestratorApprove() {
+    try {
+      await fetch('/api/orchestrator/approve', { method: 'POST' });
+    } catch (err) {
+      console.error('[Orchestrator] Approve failed:', err);
+    }
+  },
+
+  async orchestratorReject(feedback) {
+    try {
+      await fetch('/api/orchestrator/reject', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ feedback }),
+      });
+    } catch (err) {
+      console.error('[Orchestrator] Reject failed:', err);
+    }
+  },
+
+  async orchestratorPause() {
+    try {
+      await fetch('/api/orchestrator/pause', { method: 'POST' });
+    } catch (err) {
+      console.error('[Orchestrator] Pause failed:', err);
+    }
+  },
+
+  async orchestratorResume() {
+    try {
+      await fetch('/api/orchestrator/resume', { method: 'POST' });
+    } catch (err) {
+      console.error('[Orchestrator] Resume failed:', err);
+    }
+  },
+
+  async orchestratorStop() {
+    try {
+      await fetch('/api/orchestrator/stop', { method: 'POST' });
+      this.orchestratorState = { state: 'idle' };
+      this.renderOrchestratorPanel();
+    } catch (err) {
+      console.error('[Orchestrator] Stop failed:', err);
+    }
+  },
+
+  async orchestratorSkipPhase(phaseId) {
+    try {
+      await fetch(`/api/orchestrator/phase/${phaseId}/skip`, { method: 'POST' });
+    } catch (err) {
+      console.error('[Orchestrator] Skip failed:', err);
+    }
+  },
+
+  async orchestratorRetryPhase(phaseId) {
+    try {
+      await fetch(`/api/orchestrator/phase/${phaseId}/retry`, { method: 'POST' });
+    } catch (err) {
+      console.error('[Orchestrator] Retry failed:', err);
+    }
+  },
+
+  async refreshOrchestratorStatus() {
+    try {
+      const res = await fetch('/api/orchestrator/status');
+      const data = await res.json();
+      if (data.ok) {
+        this.orchestratorState = data;
+        this.renderOrchestratorPanel();
+      }
+    } catch (err) {
+      console.error('[Orchestrator] Status fetch failed:', err);
+    }
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // Rendering
+  // ═══════════════════════════════════════════════════════════════
+
+  renderOrchestratorPanel() {
+    const panel = document.getElementById('orchestratorPanel');
+    if (!panel) return;
+
+    const state = this.orchestratorState?.state || 'idle';
+    const plan = this.orchestratorState?.plan;
+
+    // Update badge
+    const badge = document.getElementById('orchestratorStateBadge');
+    if (badge) {
+      badge.textContent = state;
+      badge.style.background = ORCH_STATE_COLORS[state] || '#6b7280';
+    }
+
+    // Update action buttons
+    const actions = document.getElementById('orchestratorActions');
+    if (actions) {
+      actions.innerHTML = this._renderOrchestratorActions(state);
+    }
+
+    // Update body
+    const body = document.getElementById('orchestratorBody');
+    if (body) {
+      body.innerHTML = this._renderOrchestratorBody(state, plan);
+    }
+  },
+
+  _renderOrchestratorActions(state) {
+    const btn = (label, onclick, cls = '') =>
+      `<button class="orch-btn ${cls}" onclick="${onclick}">${label}</button>`;
+
+    switch (state) {
+      case 'idle':
+      case 'completed':
+      case 'failed':
+        return btn('New Goal', 'app.promptOrchestratorGoal()', 'orch-btn-primary');
+      case 'planning':
+        return btn('Cancel', 'app.orchestratorStop()', 'orch-btn-danger');
+      case 'approval':
+        return [
+          btn('Approve', 'app.orchestratorApprove()', 'orch-btn-primary'),
+          btn('Reject', 'app.promptOrchestratorReject()', 'orch-btn-warn'),
+          btn('Cancel', 'app.orchestratorStop()', 'orch-btn-danger'),
+        ].join('');
+      case 'executing':
+      case 'verifying':
+      case 'replanning':
+        return [
+          btn('Pause', 'app.orchestratorPause()'),
+          btn('Stop', 'app.orchestratorStop()', 'orch-btn-danger'),
+        ].join('');
+      case 'paused':
+        return [
+          btn('Resume', 'app.orchestratorResume()', 'orch-btn-primary'),
+          btn('Stop', 'app.orchestratorStop()', 'orch-btn-danger'),
+        ].join('');
+      default:
+        return '';
+    }
+  },
+
+  _renderOrchestratorBody(state, plan) {
+    if (state === 'idle' && !plan) {
+      return '<div class="orch-empty">No orchestration active. Click "New Goal" to start.</div>';
+    }
+
+    if (state === 'planning') {
+      const progress = this.orchestratorState?.planProgress || [];
+      let progressHtml = '';
+      if (progress.length > 0) {
+        const items = progress.map(p =>
+          `<div class="orch-progress-item"><span class="orch-progress-phase">${escapeHtml(p.phase)}</span> ${escapeHtml(p.detail)}</div>`
+        ).join('');
+        progressHtml = `<div class="orch-progress-log">${items}</div>`;
+      }
+      return `<div class="orch-planning"><div class="orch-spinner"></div>Generating plan...${progressHtml}</div>`;
+    }
+
+    if (!plan) return '';
+
+    const parts = [];
+
+    // Goal
+    parts.push(`<div class="orch-goal"><strong>Goal:</strong> ${escapeHtml(plan.goal.slice(0, 200))}</div>`);
+
+    // Progress summary
+    const completed = plan.phases.filter(p => p.status === 'passed' || p.status === 'skipped').length;
+    const total = plan.phases.length;
+    const pct = total > 0 ? Math.round((completed / total) * 100) : 0;
+    parts.push(`<div class="orch-progress-bar"><div class="orch-progress-fill" style="width:${pct}%"></div><span>${completed}/${total} phases</span></div>`);
+
+    // Phase list
+    parts.push('<div class="orch-phases">');
+    for (const phase of plan.phases) {
+      parts.push(this._renderOrchestratorPhase(phase, state));
+    }
+    parts.push('</div>');
+
+    // Stats (if completed/failed)
+    if (state === 'completed' || state === 'failed') {
+      const stats = this.orchestratorState?.stats;
+      if (stats) {
+        parts.push(this._renderOrchestratorStats(stats));
+      }
+      if (this.orchestratorState?.lastError) {
+        parts.push(`<div class="orch-error">Error: ${escapeHtml(this.orchestratorState.lastError)}</div>`);
+      }
+    }
+
+    return parts.join('');
+  },
+
+  _renderOrchestratorPhase(phase, orchState) {
+    const icon = ORCH_PHASE_STATUS_ICONS[phase.status] || '\u25cb';
+    const isActive = phase.status === 'executing';
+    const cls = `orch-phase ${isActive ? 'orch-phase-active' : ''} orch-phase-${phase.status}`;
+
+    let actions = '';
+    if (orchState === 'executing' || orchState === 'failed') {
+      if (phase.status === 'pending') {
+        actions += `<button class="orch-phase-btn" onclick="app.orchestratorSkipPhase('${phase.id}')" title="Skip">skip</button>`;
+      }
+      if (phase.status === 'failed') {
+        actions += `<button class="orch-phase-btn" onclick="app.orchestratorRetryPhase('${phase.id}')" title="Retry">retry</button>`;
+      }
+    }
+
+    // Task summary
+    const tasksDone = phase.tasks.filter(t => t.status === 'completed').length;
+    const tasksFailed = phase.tasks.filter(t => t.status === 'failed').length;
+    const tasksTotal = phase.tasks.length;
+    const taskSummary = `${tasksDone}/${tasksTotal}${tasksFailed > 0 ? ` (${tasksFailed} failed)` : ''}`;
+
+    // Duration
+    let duration = '';
+    if (phase.durationMs) {
+      const secs = Math.round(phase.durationMs / 1000);
+      duration = secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m ${secs % 60}s`;
+    }
+
+    let html = `<div class="${cls}">`;
+    html += `<div class="orch-phase-header">`;
+    html += `<span class="orch-phase-icon">${icon}</span>`;
+    html += `<span class="orch-phase-name">${escapeHtml(phase.name)}</span>`;
+    html += `<span class="orch-phase-tasks">${taskSummary}</span>`;
+    if (duration) html += `<span class="orch-phase-duration">${duration}</span>`;
+    if (actions) html += `<span class="orch-phase-actions">${actions}</span>`;
+    html += `</div>`;
+
+    // Expanded task list for active phase
+    if (isActive || phase.status === 'failed') {
+      html += '<div class="orch-phase-tasks-list">';
+      for (const task of phase.tasks) {
+        const taskIcon = ORCH_PHASE_STATUS_ICONS[task.status] || '\u25cb';
+        const taskCls = `orch-task orch-task-${task.status}`;
+        html += `<div class="${taskCls}"><span class="orch-task-icon">${taskIcon}</span>`;
+        html += `<span class="orch-task-prompt">${escapeHtml(task.prompt.slice(0, 100))}</span>`;
+        if (task.error) html += `<span class="orch-task-error">${escapeHtml(task.error.slice(0, 80))}</span>`;
+        html += '</div>';
+      }
+      html += '</div>';
+    }
+
+    // Verification result
+    if (phase._lastVerification) {
+      const v = phase._lastVerification;
+      const vCls = v.passed ? 'orch-verify-pass' : 'orch-verify-fail';
+      html += `<div class="${vCls}">${v.passed ? 'Verified' : 'Failed'}: ${escapeHtml(v.summary || '')}</div>`;
+    }
+
+    html += '</div>';
+    return html;
+  },
+
+  _renderOrchestratorStats(stats) {
+    return `<div class="orch-stats">
+      <span>Phases: ${stats.phasesCompleted} done, ${stats.phasesFailed} failed</span>
+      <span>Tasks: ${stats.totalTasksCompleted} done, ${stats.totalTasksFailed} failed</span>
+      ${stats.replanCount > 0 ? `<span>Replans: ${stats.replanCount}</span>` : ''}
+      ${stats.totalDurationMs ? `<span>Duration: ${Math.round(stats.totalDurationMs / 60000)}m</span>` : ''}
+    </div>`;
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // User prompts
+  // ═══════════════════════════════════════════════════════════════
+
+  promptOrchestratorGoal() {
+    const goal = prompt('Enter your goal for the orchestrator:');
+    if (goal && goal.trim()) {
+      this.orchestratorStart(goal.trim());
+    }
+  },
+
+  promptOrchestratorReject() {
+    const feedback = prompt('Feedback on the plan (what should change?):');
+    if (feedback && feedback.trim()) {
+      this.orchestratorReject(feedback.trim());
+    }
+  },
+});

src/web/public/ralph-wizard.js

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

src/web/public/subagent-windows.js

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

src/web/public/voice-input.js

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

src/web/route-helpers.ts

@@ -6,7 +6,10 @@
  */
 
 import { join, resolve, relative, isAbsolute } from 'node:path';
+import { realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
 import { homedir } from 'node:os';
+import type { z } from 'zod';
 import { Session } from '../session.js';
 import { ApiErrorCode, createErrorResponse } from '../types.js';
 import { parseRalphLoopConfig, extractCompletionPhrase } from '../ralph-config.js';
@@ -32,6 +35,45 @@ export function validatePathWithinBase(name: string, baseDir: string): string |
   return fullPath;
 }
 
+/**
+ * Reads and parses a JSON config file, returning a default value on ENOENT.
+ * Logs an error for any I/O failure other than a missing file.
+ */
+export async function readJsonConfig<T>(filePath: string, logLabel: string, defaultValue: T): Promise<T> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      console.error(`Failed to read ${logLabel}:`, err);
+    }
+    return defaultValue;
+  }
+}
+
+/**
+ * Validates that a file path (possibly containing symlinks) resolves to a location
+ * within the given session working directory. Returns the resolved and relative paths,
+ * or null if the path escapes the directory or doesn't exist.
+ */
+export function validateSessionFilePath(
+  sessionWorkingDir: string,
+  filePath: string
+): { resolvedPath: string; relativePath: string } | null {
+  const fullPath = resolve(sessionWorkingDir, filePath);
+  let resolvedPath: string;
+  try {
+    resolvedPath = realpathSync(fullPath);
+  } catch {
+    return null;
+  }
+  const relativePath = relative(sessionWorkingDir, resolvedPath);
+  if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+    return null;
+  }
+  return { resolvedPath, relativePath };
+}
+
 // Maximum hook data size (prevents oversized SSE broadcasts)
 const MAX_HOOK_DATA_SIZE = 8 * 1024;
 
@@ -50,6 +92,31 @@ export function findSessionOrFail(ctx: SessionPort, sessionId: string): Session
   return session;
 }
 
+/**
+ * Parse and validate a request body against a Zod schema, or throw a structured 400 error.
+ * Replaces the repeated pattern: `const r = Schema.safeParse(body); if (!r.success) return createErrorResponse(...)`.
+ */
+export function parseBody<T>(schema: z.ZodType<T>, body: unknown, errorMessage?: string): T {
+  const result = schema.safeParse(body);
+  if (!result.success) {
+    const msg = errorMessage ?? result.error.issues[0]?.message ?? 'Validation failed';
+    throw Object.assign(new Error(msg), {
+      statusCode: 400,
+      body: createErrorResponse(ApiErrorCode.INVALID_INPUT, msg),
+    });
+  }
+  return result.data;
+}
+
+/**
+ * Persist session state and broadcast a SessionUpdated event.
+ * Replaces the repeated two-line pattern across route handlers.
+ */
+export function persistAndBroadcastSession(ctx: SessionPort & EventPort, session: Session): void {
+  ctx.persistSessionState(session);
+  ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+}
+
 /**
  * Formats uptime in seconds to a human-readable string (e.g., "1d 2h 30m 15s").
  */

src/web/routes/case-routes.ts

@@ -14,10 +14,24 @@ import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.
 import { CreateCaseSchema, LinkCaseSchema } from '../schemas.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { writeHooksConfig } from '../../hooks-config.js';
-import { CASES_DIR, validatePathWithinBase } from '../route-helpers.js';
+import { CASES_DIR, validatePathWithinBase, parseBody, readJsonConfig } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { EventPort, ConfigPort } from '../ports/index.js';
 
+const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
+
+/** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
+async function readLinkedCases(): Promise<Record<string, string>> {
+  return readJsonConfig<Record<string, string>>(LINKED_CASES_FILE, 'linked cases', {});
+}
+
+/** Resolve a case name to its directory path, checking linked cases first, then CASES_DIR. */
+async function resolveCasePath(name: string): Promise<string> {
+  const linkedCases = await readLinkedCases();
+  if (linkedCases[name]) return linkedCases[name];
+  return join(CASES_DIR, name);
+}
+
 export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & ConfigPort): void {
   // ═══════════════════════════════════════════════════════════════
   // Case CRUD (list, create, link, detail, fix-plan)
@@ -45,22 +59,15 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     }
 
     // Get linked cases
-    const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-    try {
-      const linkedCases: Record<string, string> = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-      for (const [name, path] of Object.entries(linkedCases)) {
-        // Only add if not already in cases (avoid duplicates) and path exists
-        if (!cases.some((c) => c.name === name) && existsSync(path)) {
-          cases.push({
-            name,
-            path,
-            hasClaudeMd: existsSync(join(path, 'CLAUDE.md')),
-          });
-        }
-      }
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.warn('[Server] Failed to read linked cases:', err);
+    const linkedCases = await readLinkedCases();
+    const existingNames = new Set(cases.map((c) => c.name));
+    for (const [name, path] of Object.entries(linkedCases)) {
+      if (!existingNames.has(name) && existsSync(path)) {
+        cases.push({
+          name,
+          path,
+          hasClaudeMd: existsSync(join(path, 'CLAUDE.md')),
+        });
       }
     }
 
@@ -68,11 +75,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
   });
 
   app.post('/api/cases', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
-    const result = CreateCaseSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { name, description } = result.data;
+    const { name, description } = parseBody(CreateCaseSchema, req.body);
 
     const casePath = validatePathWithinBase(name, CASES_DIR);
     if (!casePath) {
@@ -105,11 +108,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
 
   // Link an existing folder as a case
   app.post('/api/cases/link', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
-    const lcResult = LinkCaseSchema.safeParse(req.body);
-    if (!lcResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { name, path: folderPath } = lcResult.data;
+    const { name, path: folderPath } = parseBody(LinkCaseSchema, req.body, 'Invalid request body');
 
     // Expand ~ to home directory
     const expandedPath = folderPath.startsWith('~') ? join(homedir(), folderPath.slice(1)) : folderPath;
@@ -126,15 +125,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     }
 
     // Load existing linked cases
-    const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-    let linkedCases: Record<string, string> = {};
-    try {
-      linkedCases = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.warn('[Server] Failed to read linked cases:', err);
-      }
-    }
+    const linkedCases = await readLinkedCases();
 
     // Check if name is already linked
     if (linkedCases[name]) {
@@ -151,7 +142,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       if (!existsSync(codemanDir)) {
         mkdirSync(codemanDir, { recursive: true });
       }
-      await fs.writeFile(linkedCasesFile, JSON.stringify(linkedCases, null, 2));
+      await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(linkedCases, null, 2));
       ctx.broadcast(SseEvent.CaseLinked, { name, path: expandedPath });
       return { success: true, data: { case: { name, path: expandedPath } } };
     } catch (err) {
@@ -166,34 +157,18 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
     }
 
-    // First check linked cases
-    const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-    try {
-      const linkedCases: Record<string, string> = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-      if (linkedCases[name]) {
-        const linkedPath = linkedCases[name];
-        return {
-          name,
-          path: linkedPath,
-          hasClaudeMd: existsSync(join(linkedPath, 'CLAUDE.md')),
-          linked: true,
-        };
-      }
-    } catch {
-      // ENOENT or parse errors - fall through to CASES_DIR check
-    }
-
-    // Then check CASES_DIR
-    const casePath = join(CASES_DIR, name);
+    const casePath = await resolveCasePath(name);
 
     if (!existsSync(casePath)) {
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Case not found');
     }
 
+    const linked = casePath !== join(CASES_DIR, name);
     return {
       name,
       path: casePath,
       hasClaudeMd: existsSync(join(casePath, 'CLAUDE.md')),
+      ...(linked && { linked: true }),
     };
   });
 
@@ -206,21 +181,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     }
 
     // Get case path (check linked cases first, then CASES_DIR)
-    let casePath: string | null = null;
-
-    const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-    try {
-      const linkedCases: Record<string, string> = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-      if (linkedCases[name]) {
-        casePath = linkedCases[name];
-      }
-    } catch {
-      // ENOENT or parse errors - fall through to CASES_DIR
-    }
-
-    if (!casePath) {
-      casePath = join(CASES_DIR, name);
-    }
+    const casePath = await resolveCasePath(name);
 
     const fixPlanPath = join(casePath, '@fix_plan.md');
 
@@ -321,23 +282,11 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
 
   app.get('/api/cases/:caseName/ralph-wizard/files', async (req) => {
     const { caseName } = req.params as { caseName: string };
-    let casePath = validatePathWithinBase(caseName, CASES_DIR);
-    if (!casePath) {
+    if (!validatePathWithinBase(caseName, CASES_DIR)) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
     }
 
-    // Check linked cases if path doesn't exist
-    if (!existsSync(casePath)) {
-      const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-      try {
-        const linkedCases: Record<string, string> = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-        if (linkedCases[caseName]) {
-          casePath = linkedCases[caseName];
-        }
-      } catch {
-        // No linked cases file
-      }
-    }
+    const casePath = await resolveCasePath(caseName);
 
     const wizardDir = join(casePath, 'ralph-wizard');
 
@@ -376,8 +325,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
   // Cache disabled to ensure fresh prompts when starting new plan generations
   app.get('/api/cases/:caseName/ralph-wizard/file/:filePath', async (req, reply) => {
     const { caseName, filePath } = req.params as { caseName: string; filePath: string };
-    let casePath = validatePathWithinBase(caseName, CASES_DIR);
-    if (!casePath) {
+    if (!validatePathWithinBase(caseName, CASES_DIR)) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
     }
 
@@ -386,18 +334,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     reply.header('Pragma', 'no-cache');
     reply.header('Expires', '0');
 
-    // Check linked cases if path doesn't exist
-    if (!existsSync(casePath)) {
-      const linkedCasesFile = join(homedir(), '.codeman', 'linked-cases.json');
-      try {
-        const linkedCases: Record<string, string> = JSON.parse(await fs.readFile(linkedCasesFile, 'utf-8'));
-        if (linkedCases[caseName]) {
-          casePath = linkedCases[caseName];
-        }
-      } catch {
-        // No linked cases file
-      }
-    }
+    const casePath = await resolveCasePath(caseName);
 
     const wizardDir = join(casePath, 'ralph-wizard');
 

src/web/routes/file-routes.ts

@@ -4,12 +4,11 @@
  */
 
 import { FastifyInstance } from 'fastify';
-import { join, resolve, relative, isAbsolute } from 'node:path';
-import { realpathSync } from 'node:fs';
+import { join } from 'node:path';
 import fs from 'node:fs/promises';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
 import { fileStreamManager } from '../../file-stream-manager.js';
-import { findSessionOrFail } from '../route-helpers.js';
+import { findSessionOrFail, validateSessionFilePath } from '../route-helpers.js';
 import type { SessionPort } from '../ports/index.js';
 
 export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void {
@@ -148,17 +147,11 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
     }
 
     // Validate path is within working directory (security: resolve symlinks to prevent traversal)
-    const fullPath = resolve(session.workingDir, filePath);
-    let resolvedPath: string;
-    try {
-      resolvedPath = realpathSync(fullPath);
-    } catch {
+    const validated = validateSessionFilePath(session.workingDir, filePath);
+    if (!validated) {
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found');
     }
-    const relativePath = relative(session.workingDir, resolvedPath);
-    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory');
-    }
+    const { resolvedPath } = validated;
 
     try {
       const stat = await fs.stat(resolvedPath);
@@ -255,19 +248,12 @@ export function registerFileRoutes(app: FastifyInstance, ctx: SessionPort): void
     }
 
     // Validate path is within working directory (security: resolve symlinks to prevent traversal)
-    const fullPath = resolve(session.workingDir, filePath);
-    let resolvedPath: string;
-    try {
-      resolvedPath = realpathSync(fullPath);
-    } catch {
+    const validated = validateSessionFilePath(session.workingDir, filePath);
+    if (!validated) {
       reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
       return;
     }
-    const relativePath = relative(session.workingDir, resolvedPath);
-    if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
-      reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory'));
-      return;
-    }
+    const { resolvedPath } = validated;
 
     try {
       // Validate file size before reading (DoS protection - prevent memory exhaustion)

src/web/routes/hook-event-routes.ts

@@ -7,7 +7,7 @@
 import { FastifyInstance } from 'fastify';
 import { ApiErrorCode, createErrorResponse } from '../../types.js';
 import { HookEventSchema, isValidWorkingDir } from '../schemas.js';
-import { sanitizeHookData } from '../route-helpers.js';
+import { sanitizeHookData, parseBody } from '../route-helpers.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 
 export function registerHookEventRoutes(
@@ -15,11 +15,7 @@ export function registerHookEventRoutes(
   ctx: SessionPort & EventPort & RespawnPort & ConfigPort & InfraPort
 ): void {
   app.post('/api/hook-event', async (req) => {
-    const result = HookEventSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { event, sessionId, data } = result.data;
+    const { event, sessionId, data } = parseBody(HookEventSchema, req.body);
     if (!ctx.sessions.has(sessionId)) {
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
     }

src/web/routes/index.ts

@@ -14,4 +14,5 @@ export { registerSessionRoutes } from './session-routes.js';
 export { registerRespawnRoutes } from './respawn-routes.js';
 export { registerRalphRoutes } from './ralph-routes.js';
 export { registerPlanRoutes } from './plan-routes.js';
+export { registerOrchestratorRoutes } from './orchestrator-routes.js';
 export { registerWsRoutes } from './ws-routes.js';

src/web/routes/orchestrator-routes.ts

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview Orchestrator loop routes — plan-based autonomous execution.
+ *
+ * Endpoints:
+ * - POST   /api/orchestrator/start       — Start orchestration with a goal
+ * - POST   /api/orchestrator/approve      — Approve generated plan
+ * - POST   /api/orchestrator/reject       — Reject plan with feedback
+ * - POST   /api/orchestrator/pause        — Pause execution
+ * - POST   /api/orchestrator/resume       — Resume from pause
+ * - POST   /api/orchestrator/stop         — Stop and clean up
+ * - GET    /api/orchestrator/status       — Get current status
+ * - GET    /api/orchestrator/plan         — Get current plan
+ * - POST   /api/orchestrator/phase/:id/skip  — Skip a phase
+ * - POST   /api/orchestrator/phase/:id/retry — Retry a failed phase
+ *
+ * @module web/routes/orchestrator-routes
+ */
+
+import { FastifyInstance } from 'fastify';
+import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
+import { OrchestratorStartSchema, OrchestratorRejectSchema } from '../schemas.js';
+import { parseBody } from '../route-helpers.js';
+import { SseEvent } from '../sse-events.js';
+import type { EventPort, OrchestratorPort } from '../ports/index.js';
+
+export function registerOrchestratorRoutes(app: FastifyInstance, ctx: OrchestratorPort & EventPort): void {
+  // ═══════════════════════════════════════════════════════════════
+  // Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  function getLoop() {
+    const loop = ctx.orchestratorLoop;
+    if (!loop) {
+      throw Object.assign(new Error('Orchestrator not initialized'), {
+        statusCode: 503,
+        body: createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'Orchestrator not initialized'),
+      });
+    }
+    return loop;
+  }
+
+  let forwardingLoop: import('../../orchestrator-loop.js').OrchestratorLoop | null = null;
+  function setupEventForwarding(loop: import('../../orchestrator-loop.js').OrchestratorLoop) {
+    if (forwardingLoop === loop) return; // Already attached to this loop instance
+    forwardingLoop = loop;
+    loop.on('stateChanged', (state, prevState) => {
+      ctx.broadcast(SseEvent.OrchestratorStateChanged, { state, prevState });
+    });
+    loop.on('planProgress', (phase, detail) => {
+      ctx.broadcast(SseEvent.OrchestratorPlanProgress, { phase, detail });
+    });
+    loop.on('planReady', (plan) => {
+      ctx.broadcast(SseEvent.OrchestratorPlanReady, { plan });
+    });
+    loop.on('phaseStarted', (phase) => {
+      ctx.broadcast(SseEvent.OrchestratorPhaseStarted, { phase });
+    });
+    loop.on('phaseCompleted', (phase) => {
+      ctx.broadcast(SseEvent.OrchestratorPhaseCompleted, { phase });
+    });
+    loop.on('phaseFailed', (phase, reason) => {
+      ctx.broadcast(SseEvent.OrchestratorPhaseFailed, { phase, reason });
+    });
+    loop.on('verificationResult', (phase, result) => {
+      ctx.broadcast(SseEvent.OrchestratorVerification, { phaseId: phase.id, result });
+    });
+    loop.on('taskAssigned', (task, sessionId) => {
+      ctx.broadcast(SseEvent.OrchestratorTaskAssigned, { task, sessionId });
+    });
+    loop.on('taskCompleted', (task) => {
+      ctx.broadcast(SseEvent.OrchestratorTaskCompleted, { task });
+    });
+    loop.on('taskFailed', (task, error) => {
+      ctx.broadcast(SseEvent.OrchestratorTaskFailed, { task, error });
+    });
+    loop.on('completed', (stats) => {
+      ctx.broadcast(SseEvent.OrchestratorCompleted, { stats });
+    });
+    loop.on('error', (error) => {
+      ctx.broadcast(SseEvent.OrchestratorError, { error: error.message });
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Start
+  // ═══════════════════════════════════════════════════════════════
+
+  app.post('/api/orchestrator/start', async (req) => {
+    const { goal, config } = parseBody(OrchestratorStartSchema, req.body, 'Invalid request body');
+
+    // Initialize loop if needed
+    let loop = ctx.orchestratorLoop;
+    if (!loop) {
+      loop = ctx.initOrchestratorLoop();
+      setupEventForwarding(loop);
+    }
+
+    // Check if already running
+    if (loop.isRunning()) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Orchestrator is already running');
+    }
+
+    try {
+      // Start is async — kicks off planning
+      loop.start(goal).catch((err) => {
+        console.error('[Orchestrator Route] Start failed:', getErrorMessage(err));
+      });
+
+      return {
+        ok: true,
+        state: loop.state,
+        message: 'Orchestrator started — generating plan',
+        config: config ?? null,
+      };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, getErrorMessage(err));
+    }
+  });
+
+  // ═══════════════════════════════════════════════════════════════
+  // Approve / Reject Plan
+  // ═══════════════════════════════════════════════════════════════
+
+  app.post('/api/orchestrator/approve', async () => {
+    const loop = getLoop();
+
+    try {
+      loop.approve().catch((err) => {
+        console.error('[Orchestrator Route] Approve failed:', getErrorMessage(err));
+      });
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+
+  app.post('/api/orchestrator/reject', async (req) => {
+    const loop = getLoop();
+
+    const { feedback } = parseBody(OrchestratorRejectSchema, req.body, 'Feedback is required');
+
+    try {
+      loop.reject(feedback).catch((err) => {
+        console.error('[Orchestrator Route] Reject failed:', getErrorMessage(err));
+      });
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+
+  // ═══════════════════════════════════════════════════════════════
+  // Pause / Resume / Stop
+  // ═══════════════════════════════════════════════════════════════
+
+  app.post('/api/orchestrator/pause', async () => {
+    const loop = getLoop();
+
+    try {
+      loop.pause();
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+
+  app.post('/api/orchestrator/resume', async () => {
+    const loop = getLoop();
+
+    try {
+      loop.resume().catch((err) => {
+        console.error('[Orchestrator Route] Resume failed:', getErrorMessage(err));
+      });
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+
+  app.post('/api/orchestrator/stop', async () => {
+    const loop = getLoop();
+
+    try {
+      await loop.stop();
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, getErrorMessage(err));
+    }
+  });
+
+  // ═══════════════════════════════════════════════════════════════
+  // Status / Plan
+  // ═══════════════════════════════════════════════════════════════
+
+  app.get('/api/orchestrator/status', async () => {
+    const loop = ctx.orchestratorLoop;
+    if (!loop) {
+      return { ok: true, state: 'idle', plan: null, stats: null };
+    }
+
+    return {
+      ok: true,
+      ...loop.getStatus(),
+    };
+  });
+
+  app.get('/api/orchestrator/plan', async () => {
+    const loop = ctx.orchestratorLoop;
+    if (!loop) {
+      return { ok: true, plan: null };
+    }
+
+    return {
+      ok: true,
+      plan: loop.getPlan(),
+      currentPhase: loop.getCurrentPhase(),
+    };
+  });
+
+  // ═══════════════════════════════════════════════════════════════
+  // Phase Operations
+  // ═══════════════════════════════════════════════════════════════
+
+  app.post('/api/orchestrator/phase/:id/skip', async (req) => {
+    const loop = getLoop();
+    const { id } = req.params as { id: string };
+
+    try {
+      await loop.skipPhase(id);
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+
+  app.post('/api/orchestrator/phase/:id/retry', async (req) => {
+    const loop = getLoop();
+    const { id } = req.params as { id: string };
+
+    try {
+      loop.retryPhase(id).catch((err) => {
+        console.error('[Orchestrator Route] Retry failed:', getErrorMessage(err));
+      });
+      return { ok: true, state: loop.state };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err));
+    }
+  });
+}

src/web/routes/plan-routes.ts

@@ -17,7 +17,7 @@ import {
   PlanTaskUpdateSchema,
   PlanTaskAddSchema,
 } from '../schemas.js';
-import { findSessionOrFail, CASES_DIR, validatePathWithinBase } from '../route-helpers.js';
+import { findSessionOrFail, parseBody, CASES_DIR, validatePathWithinBase } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort } from '../ports/index.js';
 
@@ -29,11 +29,11 @@ export function registerPlanRoutes(app: FastifyInstance, ctx: SessionPort & Even
   // ========== Generate Plan (Simple) ==========
 
   app.post('/api/generate-plan', async (req): Promise<ApiResponse> => {
-    const gpResult = GeneratePlanSchema.safeParse(req.body);
-    if (!gpResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { taskDescription, detailLevel = 'standard' } = gpResult.data;
+    const { taskDescription, detailLevel = 'standard' } = parseBody(
+      GeneratePlanSchema,
+      req.body,
+      'Invalid request body'
+    );
 
     // Build sophisticated prompt based on Ralph Wiggum methodology
     const detailConfig = {
@@ -223,11 +223,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
   // ========== Generate Plan (Detailed Orchestration) ==========
 
   app.post('/api/generate-plan-detailed', async (req): Promise<ApiResponse> => {
-    const gpdResult = GeneratePlanDetailedSchema.safeParse(req.body);
-    if (!gpdResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { taskDescription, caseName } = gpdResult.data;
+    const { taskDescription, caseName } = parseBody(GeneratePlanDetailedSchema, req.body, 'Invalid request body');
 
     // Determine output directory for saving wizard results
     let outputDir: string | undefined;
@@ -327,11 +323,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
   // ========== Cancel Plan Generation ==========
 
   app.post('/api/cancel-plan-generation', async (req): Promise<ApiResponse> => {
-    const cpResult = CancelPlanSchema.safeParse(req.body);
-    if (!cpResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { orchestratorId } = cpResult.data;
+    const { orchestratorId } = parseBody(CancelPlanSchema, req.body, 'Invalid request body');
 
     // If specific orchestrator ID provided, cancel just that one
     if (orchestratorId) {
@@ -374,11 +366,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
       return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
     }
 
-    const ptuResult = PlanTaskUpdateSchema.safeParse(req.body);
-    if (!ptuResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const update = ptuResult.data as {
+    const update = parseBody(PlanTaskUpdateSchema, req.body, 'Invalid request body') as {
       status?: 'pending' | 'in_progress' | 'completed' | 'failed' | 'blocked';
       error?: string;
       incrementAttempts?: boolean;
@@ -454,11 +442,7 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
       return createErrorResponse(ApiErrorCode.OPERATION_FAILED, 'Ralph tracker not available');
     }
 
-    const ptaResult = PlanTaskAddSchema.safeParse(req.body);
-    if (!ptaResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const task = ptaResult.data;
+    const task = parseBody(PlanTaskAddSchema, req.body, 'Invalid request body');
 
     const result = tracker.addPlanTask(task);
     ctx.broadcast(SseEvent.SessionPlanTaskAdded, { sessionId: id, task: result.task });

src/web/routes/push-routes.ts

@@ -7,6 +7,7 @@ import { FastifyInstance } from 'fastify';
 import { v4 as uuidv4 } from 'uuid';
 import { ApiErrorCode, createErrorResponse } from '../../types.js';
 import { PushSubscribeSchema, PushPreferencesUpdateSchema } from '../schemas.js';
+import { parseBody } from '../route-helpers.js';
 import type { InfraPort } from '../ports/index.js';
 
 export function registerPushRoutes(app: FastifyInstance, ctx: InfraPort): void {
@@ -15,11 +16,7 @@ export function registerPushRoutes(app: FastifyInstance, ctx: InfraPort): void {
   });
 
   app.post('/api/push/subscribe', async (req) => {
-    const result = PushSubscribeSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { endpoint, keys, userAgent, pushPreferences } = result.data;
+    const { endpoint, keys, userAgent, pushPreferences } = parseBody(PushSubscribeSchema, req.body);
     const record = ctx.pushStore.addSubscription({
       id: uuidv4(),
       endpoint,
@@ -33,11 +30,8 @@ export function registerPushRoutes(app: FastifyInstance, ctx: InfraPort): void {
 
   app.put('/api/push/subscribe/:id', async (req) => {
     const { id } = req.params as { id: string };
-    const result = PushPreferencesUpdateSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const updated = ctx.pushStore.updatePreferences(id, result.data.pushPreferences);
+    const { pushPreferences } = parseBody(PushPreferencesUpdateSchema, req.body);
+    const updated = ctx.pushStore.updatePreferences(id, pushPreferences);
     if (!updated) {
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Subscription not found');
     }

src/web/routes/ralph-routes.ts

@@ -13,7 +13,7 @@ import { Session } from '../../session.js';
 import { RespawnController } from '../../respawn-controller.js';
 import { RalphConfigSchema, FixPlanImportSchema, RalphPromptWriteSchema, RalphLoopStartSchema } from '../schemas.js';
 import { SseEvent } from '../sse-events.js';
-import { autoConfigureRalph, CASES_DIR, SETTINGS_PATH } from '../route-helpers.js';
+import { autoConfigureRalph, CASES_DIR, SETTINGS_PATH, findSessionOrFail, parseBody } from '../route-helpers.js';
 import { writeHooksConfig } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
@@ -31,22 +31,18 @@ export function registerRalphRoutes(
   // Configure Ralph tracker for a session
   app.post('/api/sessions/:id/ralph-config', async (req) => {
     const { id } = req.params as { id: string };
-    const ralphResult = RalphConfigSchema.safeParse(req.body);
-    if (!ralphResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { enabled, completionPhrase, maxIterations, reset, disableAutoEnable } = ralphResult.data as {
+    const { enabled, completionPhrase, maxIterations, reset, disableAutoEnable } = parseBody(
+      RalphConfigSchema,
+      req.body,
+      'Invalid request body'
+    ) as {
       enabled?: boolean;
       completionPhrase?: string;
       maxIterations?: number;
       reset?: boolean | 'full';
       disableAutoEnable?: boolean;
     };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     // Ralph tracker is not supported for opencode sessions
     if (session.mode === 'opencode') {
@@ -111,11 +107,7 @@ export function registerRalphRoutes(
   // Reset circuit breaker for Ralph tracker
   app.post('/api/sessions/:id/ralph-circuit-breaker/reset', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     session.ralphTracker.resetCircuitBreaker();
     return { success: true };
@@ -124,11 +116,7 @@ export function registerRalphRoutes(
   // Get Ralph status block and circuit breaker state
   app.get('/api/sessions/:id/ralph-status', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     return {
       success: true,
@@ -148,11 +136,7 @@ export function registerRalphRoutes(
   // Generate @fix_plan.md content from todos
   app.get('/api/sessions/:id/fix-plan', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     const content = session.ralphTracker.generateFixPlanMarkdown();
     return {
@@ -167,16 +151,8 @@ export function registerRalphRoutes(
   // Import todos from @fix_plan.md content
   app.post('/api/sessions/:id/fix-plan/import', async (req) => {
     const { id } = req.params as { id: string };
-    const importResult = FixPlanImportSchema.safeParse(req.body);
-    if (!importResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { content } = importResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { content } = parseBody(FixPlanImportSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     const importedCount = session.ralphTracker.importFixPlanMarkdown(content);
     ctx.persistSessionState(session);
@@ -193,11 +169,7 @@ export function registerRalphRoutes(
   // Write @fix_plan.md to session's working directory
   app.post('/api/sessions/:id/fix-plan/write', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     const workingDir = session.workingDir;
     if (!workingDir) {
@@ -224,11 +196,7 @@ export function registerRalphRoutes(
   // Read @fix_plan.md from session's working directory and import
   app.post('/api/sessions/:id/fix-plan/read', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     const workingDir = session.workingDir;
     if (!workingDir) {
@@ -266,16 +234,8 @@ export function registerRalphRoutes(
   // This avoids mux input escaping issues with long multi-line prompts
   app.post('/api/sessions/:id/ralph-prompt/write', async (req) => {
     const { id } = req.params as { id: string };
-    const promptResult = RalphPromptWriteSchema.safeParse(req.body);
-    if (!promptResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { content } = promptResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { content } = parseBody(RalphPromptWriteSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     const workingDir = session.workingDir;
     if (!workingDir) {
@@ -308,11 +268,10 @@ export function registerRalphRoutes(
       );
     }
 
-    const rlResult = RalphLoopStartSchema.safeParse(req.body);
-    if (!rlResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, rlResult.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { caseName, taskDescription, completionPhrase, maxIterations, enableRespawn, planItems } = rlResult.data;
+    const { caseName, taskDescription, completionPhrase, maxIterations, enableRespawn, planItems } = parseBody(
+      RalphLoopStartSchema,
+      req.body
+    );
 
     const casePath = join(CASES_DIR, caseName);
 

src/web/routes/respawn-routes.ts

@@ -8,7 +8,7 @@ import { ApiErrorCode, createErrorResponse, getErrorMessage, type PersistedRespa
 import { RespawnController, type RespawnConfig } from '../../respawn-controller.js';
 import { RespawnConfigSchema, InteractiveRespawnSchema, RespawnEnableSchema } from '../schemas.js';
 import { SseEvent } from '../sse-events.js';
-import { findSessionOrFail, autoConfigureRalph } from '../route-helpers.js';
+import { findSessionOrFail, autoConfigureRalph, parseBody } from '../route-helpers.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
 import {
@@ -84,11 +84,7 @@ export function registerRespawnRoutes(
     const { id } = req.params as { id: string };
     let body: Partial<RespawnConfig> | undefined;
     if (req.body) {
-      const result = RespawnConfigSchema.safeParse(req.body);
-      if (!result.success) {
-        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid respawn config');
-      }
-      body = result.data as Partial<RespawnConfig>;
+      body = parseBody(RespawnConfigSchema, req.body, 'Invalid respawn config') as Partial<RespawnConfig>;
     }
     const session = findSessionOrFail(ctx, id);
 
@@ -162,11 +158,7 @@ export function registerRespawnRoutes(
   app.put('/api/sessions/:id/respawn/config', async (req) => {
     const { id } = req.params as { id: string };
     // Validate respawn config to prevent arbitrary field injection
-    const parseResult = RespawnConfigSchema.safeParse(req.body);
-    if (!parseResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Invalid respawn config: ${parseResult.error.message}`);
-    }
-    const config = parseResult.data as Partial<RespawnConfig>;
+    const config = parseBody(RespawnConfigSchema, req.body, 'Invalid respawn config') as Partial<RespawnConfig>;
     const session = findSessionOrFail(ctx, id);
 
     const controller = ctx.respawnControllers.get(id);

src/web/routes/scheduled-routes.ts

@@ -7,6 +7,7 @@ import { FastifyInstance } from 'fastify';
 import { statSync } from 'node:fs';
 import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
 import { ScheduledRunSchema } from '../schemas.js';
+import { parseBody } from '../route-helpers.js';
 import type { SessionPort, EventPort, InfraPort, ScheduledRun } from '../ports/index.js';
 
 export function registerScheduledRoutes(app: FastifyInstance, ctx: SessionPort & EventPort & InfraPort): void {
@@ -15,11 +16,7 @@ export function registerScheduledRoutes(app: FastifyInstance, ctx: SessionPort &
   });
 
   app.post('/api/scheduled', async (req): Promise<{ success: boolean; run: ScheduledRun } | ApiResponse<never>> => {
-    const srResult = ScheduledRunSchema.safeParse(req.body);
-    if (!srResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { prompt, workingDir, durationMinutes } = srResult.data;
+    const { prompt, workingDir, durationMinutes } = parseBody(ScheduledRunSchema, req.body, 'Invalid request body');
 
     // Validate workingDir exists and is a directory
     if (workingDir) {

src/web/routes/session-routes.ts

@@ -32,7 +32,15 @@ import {
   QuickRunSchema,
   QuickStartSchema,
 } from '../schemas.js';
-import { autoConfigureRalph, CASES_DIR, SETTINGS_PATH, validatePathWithinBase } from '../route-helpers.js';
+import {
+  autoConfigureRalph,
+  CASES_DIR,
+  findSessionOrFail,
+  parseBody,
+  persistAndBroadcastSession,
+  SETTINGS_PATH,
+  validatePathWithinBase,
+} from '../route-helpers.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { writeHooksConfig, updateCaseEnvVars } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
@@ -51,6 +59,52 @@ const CLAUDE_BANNER_PATTERN = /\x1b\[1mClaud/;
 const CTRL_L_PATTERN = /\x0c/g;
 const LEADING_WHITESPACE_PATTERN = /^[\s\r\n]+/;
 
+/**
+ * Strip redundant Ink spinner/status-bar redraw frames from the terminal buffer.
+ * Ink (Claude Code's TUI) uses absolute cursor positioning (CSI n d = VPA, CSI n;m H = CUP)
+ * to animate the spinner and update the status bar. During long thinking phases, these frames
+ * accumulate to 500KB+ of repeated overwrites to the same rows. When the buffer is tailed,
+ * only spinner frames are returned, making the terminal appear empty.
+ *
+ * Strategy: find where absolute-positioned redraws begin (first VPA sequence), then keep
+ * only the last ~4KB of redraw frames (the final visual state) and discard the rest.
+ */
+function stripInkRedrawBloat(buffer: string): string {
+  // Find where Ink's absolute-positioned redraws start (first CSI n d = VPA)
+  // eslint-disable-next-line no-control-regex
+  const firstVPA = buffer.search(/\x1b\[\d+d/);
+  if (firstVPA === -1) return buffer; // No Ink redraws
+
+  const contentPart = buffer.slice(0, firstVPA);
+  const redrawPart = buffer.slice(firstVPA);
+
+  // If the redraw section is small (<16KB), not worth stripping
+  if (redrawPart.length < 16384) return buffer;
+
+  // Find the last complete Ink frame by searching for where the VPA row
+  // number drops (cursor jumps back to viewport top for a new render cycle).
+  // Search the last 64KB — a single Ink frame with response content can be
+  // 10-20KB, so 4KB was too small and caused partial frames (blank gap).
+  const searchLen = Math.min(redrawPart.length, 65536);
+  const searchWindow = redrawPart.slice(-searchLen);
+
+  // eslint-disable-next-line no-control-regex
+  const vpaRe = /\x1b\[(\d+)d/g;
+  let lastFrameStart = 0;
+  let prevRow = -1;
+  let match;
+  while ((match = vpaRe.exec(searchWindow)) !== null) {
+    const row = parseInt(match[1], 10);
+    // Row number dropped significantly — Ink started a new frame
+    if (prevRow > 0 && row < prevRow - 5) {
+      lastFrameStart = match.index;
+    }
+    prevRow = row;
+  }
+
+  return contentPart + searchWindow.slice(lastFrameStart);
+}
+
 export function registerSessionRoutes(
   app: FastifyInstance,
   ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
@@ -92,11 +146,7 @@ export function registerSessionRoutes(
       );
     }
 
-    const result = CreateSessionSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const body = result.data;
+    const body = parseBody(CreateSessionSchema, req.body);
     const workingDir = body.workingDir || process.cwd();
 
     // Validate workingDir exists and is a directory
@@ -164,23 +214,14 @@ export function registerSessionRoutes(
 
   app.put('/api/sessions/:id/name', async (req) => {
     const { id } = req.params as { id: string };
-    const result = SessionNameSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(SessionNameSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     const name = String(body.name || '').slice(0, MAX_SESSION_NAME_LENGTH);
     session.name = name;
     // Also update the mux session name if applicable
     ctx.mux.updateSessionName(id, session.name);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
     return { success: true, name: session.name };
   });
 
@@ -188,16 +229,8 @@ export function registerSessionRoutes(
 
   app.put('/api/sessions/:id/color', async (req) => {
     const { id } = req.params as { id: string };
-    const result = SessionColorSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(SessionColorSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     const validColors = ['default', 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink'];
     if (!validColors.includes(body.color)) {
@@ -205,8 +238,7 @@ export function registerSessionRoutes(
     }
 
     session.setColor(body.color as SessionColor);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
     return { success: true, color: session.color };
   });
 
@@ -245,11 +277,7 @@ export function registerSessionRoutes(
 
   app.get('/api/sessions/:id', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     // Use light state (no full buffers) — terminal buffer available via /terminal endpoint.
     // Full buffers were 2-3MB and caused slowness when polled frequently (e.g. Ralph wizard).
@@ -264,11 +292,7 @@ export function registerSessionRoutes(
 
   app.get('/api/sessions/:id/output', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     return {
       success: true,
@@ -284,11 +308,7 @@ export function registerSessionRoutes(
 
   app.get('/api/sessions/:id/ralph-state', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     return {
       success: true,
@@ -304,11 +324,7 @@ export function registerSessionRoutes(
 
   app.get('/api/sessions/:id/run-summary', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     const tracker = ctx.runSummaryTrackers.get(id);
     if (!tracker) {
@@ -328,11 +344,7 @@ export function registerSessionRoutes(
 
   app.get('/api/sessions/:id/active-tools', async (req) => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     return {
       success: true,
@@ -350,16 +362,8 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/run', async (req): Promise<ApiResponse> => {
     const { id } = req.params as { id: string };
-    const result = RunPromptSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { prompt } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { prompt } = parseBody(RunPromptSchema, req.body);
+    const session = findSessionOrFail(ctx, id);
 
     if (session.isBusy()) {
       return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -378,11 +382,7 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/interactive', async (req): Promise<ApiResponse> => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     if (session.isBusy()) {
       return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -422,11 +422,7 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/shell', async (req): Promise<ApiResponse> => {
     const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     if (session.isBusy()) {
       return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -456,16 +452,8 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/input', async (req): Promise<ApiResponse> => {
     const { id } = req.params as { id: string };
-    const result = SessionInputWithLimitSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { input, useMux } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { input, useMux } = parseBody(SessionInputWithLimitSchema, req.body);
+    const session = findSessionOrFail(ctx, id);
 
     const inputStr = String(input);
     if (inputStr.length > MAX_INPUT_LENGTH) {
@@ -501,16 +489,8 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/resize', async (req): Promise<ApiResponse> => {
     const { id } = req.params as { id: string };
-    const result = ResizeSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { cols, rows } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { cols, rows } = parseBody(ResizeSchema, req.body);
+    const session = findSessionOrFail(ctx, id);
 
     session.resize(cols, rows);
     return { success: true };
@@ -523,21 +503,23 @@ export function registerSessionRoutes(
   app.get('/api/sessions/:id/terminal', async (req) => {
     const { id } = req.params as { id: string };
     const query = req.query as { tail?: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);
 
     const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
     const fullSize = session.terminalBufferLength;
     let truncated = false;
     let cleanBuffer: string;
 
-    if (tailBytes > 0 && fullSize > tailBytes) {
+    // Strip redundant Ink spinner/status redraws BEFORE tailing.
+    // During long thinking phases, Ink rewrites the same rows thousands of times
+    // (500KB+). Without stripping, tail mode returns only spinner frames and
+    // the terminal appears empty when switching tabs.
+    const strippedBuffer = stripInkRedrawBloat(session.terminalBuffer);
+
+    if (tailBytes > 0 && strippedBuffer.length > tailBytes) {
       // Fast path: tail from the end, skip expensive banner search on full 2MB buffer.
       // Banner is near the top and gets discarded by tail anyway.
-      cleanBuffer = session.terminalBuffer.slice(-tailBytes);
+      cleanBuffer = strippedBuffer.slice(-tailBytes);
       truncated = true;
       // Avoid starting mid-ANSI-escape: find first newline within the first 4KB
       // and start from there. This prevents xterm.js from parsing a partial escape
@@ -548,7 +530,7 @@ export function registerSessionRoutes(
       }
     } else {
       // Full buffer: clean junk before actual Claude content
-      cleanBuffer = session.terminalBuffer;
+      cleanBuffer = strippedBuffer;
 
       // Find where Claude banner starts (has color codes before "Claude")
       const claudeMatch = cleanBuffer.match(CLAUDE_BANNER_PATTERN);
@@ -580,20 +562,11 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/auto-clear', async (req) => {
     const { id } = req.params as { id: string };
-    const acResult = AutoClearSchema.safeParse(req.body);
-    if (!acResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = acResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(AutoClearSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     session.setAutoClear(body.enabled, body.threshold);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
 
     return {
       success: true,
@@ -610,20 +583,11 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/auto-compact', async (req) => {
     const { id } = req.params as { id: string };
-    const compactResult = AutoCompactSchema.safeParse(req.body);
-    if (!compactResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = compactResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(AutoCompactSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     session.setAutoCompact(body.enabled, body.threshold, body.prompt);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
 
     return {
       success: true,
@@ -641,16 +605,8 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/image-watcher', async (req) => {
     const { id } = req.params as { id: string };
-    const iwResult = ImageWatcherSchema.safeParse(req.body);
-    if (!iwResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = iwResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(ImageWatcherSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     if (body.enabled) {
       imageWatcher.watchSession(session.id, session.workingDir);
@@ -674,20 +630,11 @@ export function registerSessionRoutes(
 
   app.post('/api/sessions/:id/flicker-filter', async (req) => {
     const { id } = req.params as { id: string };
-    const ffResult = FlickerFilterSchema.safeParse(req.body);
-    if (!ffResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = ffResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(FlickerFilterSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);
 
     session.flickerFilterEnabled = body.enabled;
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
 
     return {
       success: true,
@@ -712,11 +659,7 @@ export function registerSessionRoutes(
       );
     }
 
-    const qrResult = QuickRunSchema.safeParse(req.body);
-    if (!qrResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { prompt, workingDir } = qrResult.data;
+    const { prompt, workingDir } = parseBody(QuickRunSchema, req.body, 'Invalid request body');
 
     if (!prompt.trim()) {
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'prompt is required');
@@ -772,11 +715,7 @@ export function registerSessionRoutes(
       );
     }
 
-    const result = QuickStartSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { caseName = 'testcase', mode = 'claude', openCodeConfig } = result.data;
+    const { caseName = 'testcase', mode = 'claude', openCodeConfig } = parseBody(QuickStartSchema, req.body);
 
     // Check OpenCode availability if requested
     if (mode === 'opencode') {
@@ -923,6 +862,86 @@ export function registerSessionRoutes(
   // History — list past Claude conversations for resume
   // ═══════════════════════════════════════════════════════════════
 
+  /** Extract the text of the first user message from a JSONL transcript head. */
+  function extractFirstUserPrompt(head: string): string | undefined {
+    const MAX_PROMPT_LEN = 120;
+    // Iterate lines without allocating a full split array
+    let start = 0;
+    while (start < head.length) {
+      const end = head.indexOf('\n', start);
+      const line = end === -1 ? head.slice(start) : head.slice(start, end);
+      start = end === -1 ? head.length : end + 1;
+      if (!line.includes('"type":"user"')) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type !== 'user' || !entry.message) continue;
+        const content = entry.message.content;
+        let text: string | undefined;
+        if (typeof content === 'string') {
+          text = content;
+        } else if (Array.isArray(content)) {
+          const textBlock = content.find((b: { type: string }) => b.type === 'text');
+          if (textBlock) text = textBlock.text;
+        }
+        if (!text) continue;
+        // Strip XML-like system/command tags and ANSI escapes from transcripts
+        text = text
+          .replace(/<[^>]+>/g, '')
+          .replace(new RegExp(String.raw`\x1b\[[0-9;]*[a-zA-Z]`, 'g'), '')
+          .trim()
+          .replace(/\s+/g, ' ');
+        if (!text) continue;
+        // Skip system-injected messages, slash command artifacts, and expanded skill prompts
+        if (
+          /^(Caveat:|init\b|clear\b|resume\b|\/[a-z][\w-]*\b|You are a |\[Request |Set model to )/i.test(text) ||
+          /^(Please )?(analyze|review) this codebase/i.test(text) ||
+          /^(Read|Implement the following) .+, then (search|list|check) /i.test(text) ||
+          /^\d+ vulnerabilit/i.test(text) ||
+          /\btoolu_/.test(text) ||
+          /^[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/.test(text) ||
+          /\b(sk-ant-|ANTHROPIC_API_KEY|API_KEY=|SECRET|TOKEN=)/i.test(text) ||
+          text.length < 8
+        )
+          continue;
+        return text.length > MAX_PROMPT_LEN ? text.slice(0, MAX_PROMPT_LEN) + '…' : text;
+      } catch {
+        // Malformed line — skip
+      }
+    }
+    return undefined;
+  }
+
+  /** Read the first 16KB of a file for content sniffing. */
+  async function readFileHead(path: string, buf: Buffer): Promise<string | null> {
+    try {
+      const fd = await fs.open(path, 'r');
+      const { bytesRead } = await fd.read(buf, 0, buf.length, 0);
+      await fd.close();
+      return buf.toString('utf8', 0, bytesRead);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Read the last `buf.length` bytes of a file (for tail-scanning user prompts). */
+  async function readFileTail(path: string, buf: Buffer, fileSize: number): Promise<string | null> {
+    try {
+      const fd = await fs.open(path, 'r');
+      const offset = Math.max(0, fileSize - buf.length);
+      const { bytesRead } = await fd.read(buf, 0, buf.length, offset);
+      await fd.close();
+      const text = buf.toString('utf8', 0, bytesRead);
+      // Skip first partial line when we didn't read from the start
+      if (offset > 0) {
+        const nl = text.indexOf('\n');
+        return nl >= 0 ? text.slice(nl + 1) : null;
+      }
+      return text;
+    } catch {
+      return null;
+    }
+  }
+
   app.get('/api/history/sessions', async () => {
     const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects');
     const results: Array<{
@@ -931,7 +950,9 @@ export function registerSessionRoutes(
       projectKey: string;
       sizeBytes: number;
       lastModified: string;
+      firstPrompt?: string;
     }> = [];
+    const headBuf = Buffer.alloc(16384);
 
     try {
       const projectDirs = await fs.readdir(projectsDir);
@@ -967,25 +988,29 @@ export function registerSessionRoutes(
           // Quick content check: verify actual conversation data exists.
           // Sessions with only file-history-snapshot or hook_progress entries have
           // no "user"/"assistant" messages and will fail claude --resume.
-          // Files > 50KB are almost certainly real conversations (skip the read).
+          // Read first 16KB to check content and extract first user prompt.
+          let firstPrompt: string | undefined;
+          const head = await readFileHead(filePath, headBuf);
+
           if (fileStat.size < 50000) {
-            try {
-              const fd = await fs.open(filePath, 'r');
-              const buf = Buffer.alloc(16384);
-              const { bytesRead } = await fd.read(buf, 0, 16384, 0);
-              await fd.close();
-              const head = buf.toString('utf8', 0, bytesRead);
-              if (
-                !head.includes('"type":"user"') &&
+            if (
+              !head ||
+              (!head.includes('"type":"user"') &&
                 !head.includes('"type":"assistant"') &&
-                !head.includes('"type":"summary"')
-              ) {
-                continue; // No conversation content — skip
-              }
-            } catch {
-              continue;
+                !head.includes('"type":"summary"'))
+            ) {
+              continue; // No conversation content — skip
             }
           }
+          if (head) firstPrompt = extractFirstUserPrompt(head);
+
+          // If head scan found no usable prompt (e.g. session started with /init),
+          // try reading the tail for a recent user message.
+          if (!firstPrompt && fileStat.size > 65536) {
+            const tailBuf = Buffer.alloc(32768);
+            const tail = await readFileTail(filePath, tailBuf, fileStat.size);
+            if (tail) firstPrompt = extractFirstUserPrompt(tail);
+          }
 
           results.push({
             sessionId,
@@ -993,6 +1018,7 @@ export function registerSessionRoutes(
             projectKey: projDir,
             sizeBytes: fileStat.size,
             lastModified: fileStat.mtime.toISOString(),
+            firstPrompt,
           });
         }
       }

src/web/routes/system-routes.ts

@@ -24,7 +24,7 @@ import {
 import { subagentWatcher } from '../../subagent-watcher.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
-import { findSessionOrFail, formatUptime, SETTINGS_PATH } from '../route-helpers.js';
+import { findSessionOrFail, formatUptime, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
@@ -324,11 +324,8 @@ export function registerSystemRoutes(
   });
 
   app.put('/api/config', async (req) => {
-    const parseResult = ConfigUpdateSchema.safeParse(req.body);
-    if (!parseResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Invalid config: ${parseResult.error.message}`);
-    }
-    ctx.store.setConfig(parseResult.data as Partial<ReturnType<typeof ctx.store.getConfig>>);
+    const configData = parseBody(ConfigUpdateSchema, req.body, 'Invalid config');
+    ctx.store.setConfig(configData as Partial<ReturnType<typeof ctx.store.getConfig>>);
     return { success: true, config: ctx.store.getConfig() };
   });
 
@@ -396,23 +393,11 @@ export function registerSystemRoutes(
   // ========== Settings ==========
 
   app.get('/api/settings', async () => {
-    try {
-      const content = await fs.readFile(SETTINGS_PATH, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read settings:', err);
-      }
-    }
-    return {};
+    return readJsonConfig(SETTINGS_PATH, 'settings', {});
   });
 
   app.put('/api/settings', async (req) => {
-    const settingsResult = SettingsUpdateSchema.safeParse(req.body);
-    if (!settingsResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid settings');
-    }
-    const settings = settingsResult.data as Record<string, unknown>;
+    const settings = parseBody(SettingsUpdateSchema, req.body, 'Invalid settings') as Record<string, unknown>;
 
     try {
       const dir = dirname(SETTINGS_PATH);
@@ -479,24 +464,12 @@ export function registerSystemRoutes(
   // ========== Model Configuration ==========
 
   app.get('/api/execution/model-config', async () => {
-    try {
-      const content = await fs.readFile(SETTINGS_PATH, 'utf-8');
-      const settings = JSON.parse(content);
-      return { success: true, data: settings.modelConfig || {} };
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read model config:', err);
-      }
-      return { success: true, data: {} };
-    }
+    const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'model config', {});
+    return { success: true, data: settings.modelConfig || {} };
   });
 
   app.put('/api/execution/model-config', async (req) => {
-    const mcResult = ModelConfigUpdateSchema.safeParse(req.body);
-    if (!mcResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid model config');
-    }
-    const modelConfig = mcResult.data as Record<string, unknown>;
+    const modelConfig = parseBody(ModelConfigUpdateSchema, req.body, 'Invalid model config') as Record<string, unknown>;
 
     try {
       let existingSettings: Record<string, unknown> = {};
@@ -536,11 +509,7 @@ export function registerSystemRoutes(
     const { id } = req.params as { id: string };
     const session = findSessionOrFail(ctx, id);
 
-    const clResult = CpuLimitSchema.safeParse(req.body);
-    if (!clResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = clResult.data as Partial<NiceConfig>;
+    const body = parseBody(CpuLimitSchema, req.body, 'Invalid request body') as Partial<NiceConfig>;
 
     session.setNice(body);
     ctx.persistSessionState(session);
@@ -560,23 +529,11 @@ export function registerSystemRoutes(
   // ========== Subagent Window State Persistence ==========
 
   app.get('/api/subagent-window-states', async () => {
-    try {
-      const content = await fs.readFile(windowStatesPath, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read subagent window states:', err);
-      }
-    }
-    return { minimized: {}, open: [] };
+    return readJsonConfig(windowStatesPath, 'subagent window states', { minimized: {}, open: [] });
   });
 
   app.put('/api/subagent-window-states', async (req) => {
-    const swResult = SubagentWindowStatesSchema.safeParse(req.body);
-    if (!swResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid window states');
-    }
-    const states = swResult.data as Record<string, unknown>;
+    const states = parseBody(SubagentWindowStatesSchema, req.body, 'Invalid window states') as Record<string, unknown>;
     try {
       const dir = dirname(windowStatesPath);
       if (!existsSync(dir)) {
@@ -592,23 +549,11 @@ export function registerSystemRoutes(
   // ========== Subagent Parent Associations ==========
 
   app.get('/api/subagent-parents', async () => {
-    try {
-      const content = await fs.readFile(parentMapPath, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read subagent parent map:', err);
-      }
-    }
-    return {};
+    return readJsonConfig(parentMapPath, 'subagent parent map', {});
   });
 
   app.put('/api/subagent-parents', async (req) => {
-    const spResult = SubagentParentMapSchema.safeParse(req.body);
-    if (!spResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid parent map');
-    }
-    const parentMap = spResult.data;
+    const parentMap = parseBody(SubagentParentMapSchema, req.body, 'Invalid parent map');
     try {
       const dir = dirname(parentMapPath);
       if (!existsSync(dir)) {
@@ -709,7 +654,7 @@ export function registerSystemRoutes(
     for await (const chunk of req.raw) {
       totalSize += chunk.length;
       if (totalSize > MAX_SCREENSHOT_SIZE) {
-        reply.status(413);
+        reply.code(413);
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'File too large (max 10MB)');
       }
       chunks.push(chunk as Buffer);
@@ -794,12 +739,12 @@ export function registerSystemRoutes(
     const { name } = req.params as { name: string };
     // Prevent path traversal
     if (name.includes('/') || name.includes('\\') || name.includes('..')) {
-      reply.status(400);
+      reply.code(400);
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid filename');
     }
     const filepath = join(SCREENSHOTS_DIR, name);
     if (!existsSync(filepath)) {
-      reply.status(404);
+      reply.code(404);
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Screenshot not found');
     }
     const ext = name.match(/\.(png|jpg|jpeg|webp|gif)$/i)?.[1]?.toLowerCase() ?? 'png';

src/web/schemas.ts

@@ -580,3 +580,31 @@ export type RespawnEnableInput = z.infer<typeof RespawnEnableSchema>;
 export type PushSubscribeInput = z.infer<typeof PushSubscribeSchema>;
 export type PushPreferencesUpdateInput = z.infer<typeof PushPreferencesUpdateSchema>;
 export type RalphLoopStartInput = z.infer<typeof RalphLoopStartSchema>;
+
+// ========== Orchestrator Loop ==========
+
+/** POST /api/orchestrator/start */
+export const OrchestratorStartSchema = z.object({
+  goal: z.string().min(1).max(100000),
+  config: z
+    .object({
+      plannerModel: z.string().max(100).optional(),
+      researchEnabled: z.boolean().optional(),
+      autoApprove: z.boolean().optional(),
+      maxPhaseRetries: z.number().int().min(1).max(10).optional(),
+      phaseTimeoutMs: z.number().int().min(60000).max(7200000).optional(),
+      enableTeamAgents: z.boolean().optional(),
+      maxParallelSessions: z.number().int().min(1).max(10).optional(),
+      verificationMode: z.enum(['strict', 'moderate', 'lenient']).optional(),
+      compactBetweenPhases: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+/** POST /api/orchestrator/reject */
+export const OrchestratorRejectSchema = z.object({
+  feedback: z.string().min(1).max(10000),
+});
+
+export type OrchestratorStartInput = z.infer<typeof OrchestratorStartSchema>;
+export type OrchestratorRejectInput = z.infer<typeof OrchestratorRejectSchema>;

src/web/server.ts

@@ -70,6 +70,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { createRequire } from 'node:module';
 import { RunSummaryTracker } from '../run-summary.js';
 import { PlanOrchestrator } from '../plan-orchestrator.js';
+import { OrchestratorLoop } from '../orchestrator-loop.js';
 import { getLifecycleLog } from '../session-lifecycle-log.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
@@ -104,6 +105,7 @@ import {
   registerRespawnRoutes,
   registerRalphRoutes,
   registerPlanRoutes,
+  registerOrchestratorRoutes,
   registerWsRoutes,
 } from './routes/index.js';
 
@@ -280,6 +282,7 @@ export class WebServer extends EventEmitter {
   private qrAuthFailures: StaleExpirationMap<string, number> | null = null;
   private pushStore: PushSubscriptionStore = new PushSubscriptionStore();
   private teamWatcher: TeamWatcher = new TeamWatcher();
+  private _orchestratorLoop: import('../orchestrator-loop.js').OrchestratorLoop | null = null;
   private teamWatcherHandlers: {
     teamCreated: (config: unknown) => void;
     teamUpdated: (config: unknown) => void;
@@ -485,6 +488,8 @@ export class WebServer extends EventEmitter {
    * Single object with zero runtime cost — ISP enforced at the type level.
    */
   private createRouteContext() {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
     return {
       // SessionPort
       sessions: this.sessions as ReadonlyMap<string, Session>,
@@ -537,6 +542,11 @@ export class WebServer extends EventEmitter {
       // AuthPort
       authSessions: this.authSessions,
       qrAuthFailures: this.qrAuthFailures,
+      // OrchestratorPort — use getter so routes always see current value (not a null snapshot)
+      get orchestratorLoop() {
+        return self._orchestratorLoop;
+      },
+      initOrchestratorLoop: () => this.initOrchestratorLoop(),
     };
   }
 
@@ -705,6 +715,7 @@ export class WebServer extends EventEmitter {
     registerRespawnRoutes(this.app, ctx);
     registerRalphRoutes(this.app, ctx);
     registerPlanRoutes(this.app, ctx);
+    registerOrchestratorRoutes(this.app, ctx);
     registerWsRoutes(this.app, ctx);
   }
 
@@ -2705,6 +2716,13 @@ export class WebServer extends EventEmitter {
     }
   }
 
+  private initOrchestratorLoop(): import('../orchestrator-loop.js').OrchestratorLoop {
+    if (this._orchestratorLoop) return this._orchestratorLoop;
+
+    this._orchestratorLoop = new OrchestratorLoop(this.mux, process.cwd());
+    return this._orchestratorLoop;
+  }
+
   async stop(): Promise<void> {
     getLifecycleLog().log({ event: 'server_stopped', sessionId: '*' });
     // Set stopping flag to prevent new timer creation during shutdown
@@ -2767,6 +2785,13 @@ export class WebServer extends EventEmitter {
     }
     this.respawnControllers.clear();
 
+    // Stop orchestrator loop if running
+    if (this._orchestratorLoop) {
+      await this._orchestratorLoop.stop();
+      this._orchestratorLoop.destroy();
+      this._orchestratorLoop = null;
+    }
+
     // Stop all scheduled runs first (they have their own session cleanup)
     await Promise.allSettled(Array.from(this.scheduledRuns.keys()).map((id) => this.stopScheduledRun(id)));
 

src/web/sse-events.ts

@@ -5,7 +5,7 @@
  * and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
  * Both files MUST be kept in sync.
  *
- * ~90 event constants organized by category:
+ * ~117 event constants organized by category:
  * - **Core** (1): init
  * - **Session lifecycle** (17): created, updated, deleted, terminal, idle, working, ...
  * - **Session: Ralph** (6): ralphLoopUpdate, todoUpdate, completionDetected, ...
@@ -292,6 +292,33 @@ export const HookTeammateIdle = 'hook:teammate_idle' as const;
 /** Claude Code hook: teammate task completed. */
 export const HookTaskCompleted = 'hook:task_completed' as const;
 
+// ─── Orchestrator ────────────────────────────────────────────────────────────
+
+/** Orchestrator state machine transitioned. */
+export const OrchestratorStateChanged = 'orchestrator:stateChanged' as const;
+/** Orchestrator plan generation progress update. */
+export const OrchestratorPlanProgress = 'orchestrator:planProgress' as const;
+/** Orchestrator plan generated and ready for approval. */
+export const OrchestratorPlanReady = 'orchestrator:planReady' as const;
+/** Orchestrator phase started executing. */
+export const OrchestratorPhaseStarted = 'orchestrator:phaseStarted' as const;
+/** Orchestrator phase completed successfully. */
+export const OrchestratorPhaseCompleted = 'orchestrator:phaseCompleted' as const;
+/** Orchestrator phase failed. */
+export const OrchestratorPhaseFailed = 'orchestrator:phaseFailed' as const;
+/** Orchestrator verification result for a phase. */
+export const OrchestratorVerification = 'orchestrator:verification' as const;
+/** Orchestrator task assigned to session. */
+export const OrchestratorTaskAssigned = 'orchestrator:taskAssigned' as const;
+/** Orchestrator task completed. */
+export const OrchestratorTaskCompleted = 'orchestrator:taskCompleted' as const;
+/** Orchestrator task failed. */
+export const OrchestratorTaskFailed = 'orchestrator:taskFailed' as const;
+/** All orchestrator phases completed successfully. */
+export const OrchestratorCompleted = 'orchestrator:completed' as const;
+/** Orchestrator error. */
+export const OrchestratorError = 'orchestrator:error' as const;
+
 // ─── Cases ───────────────────────────────────────────────────────────────────
 
 /** New case directory created. */
@@ -441,6 +468,20 @@ export const SseEvent = {
   HookTeammateIdle,
   HookTaskCompleted,
 
+  // Orchestrator
+  OrchestratorStateChanged,
+  OrchestratorPlanProgress,
+  OrchestratorPlanReady,
+  OrchestratorPhaseStarted,
+  OrchestratorPhaseCompleted,
+  OrchestratorPhaseFailed,
+  OrchestratorVerification,
+  OrchestratorTaskAssigned,
+  OrchestratorTaskCompleted,
+  OrchestratorTaskFailed,
+  OrchestratorCompleted,
+  OrchestratorError,
+
   // Cases
   CaseCreated,
   CaseLinked,

test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}

test/mocks/mock-route-context.ts

@@ -113,6 +113,10 @@ export function createMockRouteContext(options?: { sessionId?: string }) {
     qrAuthFailures: null,
     // https already declared above in ConfigPort (shared property)
 
+    // -- OrchestratorPort --
+    orchestratorLoop: null,
+    initOrchestratorLoop: vi.fn(),
+
     // Convenience accessors (not part of any port interface)
     _session: session,
     _sessionId: sessionId,

test/orchestrator-planner.test.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Tests for OrchestratorPlanner phase grouping logic.
+ * Tests the groupIntoPhases algorithm: topological sort, TDD grouping, merging.
+ *
+ * Port: N/A (no HTTP)
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+// We test the private groupIntoPhases via the public generatePlan interface,
+// or by accessing internals. For unit testing the algorithm directly, we use
+// a subclass that exposes the private method.
+//
+// Since groupIntoPhases is private and the class requires a real mux,
+// we test the planner types and verification logic instead.
+
+import { OrchestratorVerifier } from '../src/orchestrator-verifier.js';
+import {
+  DEFAULT_ORCHESTRATOR_CONFIG,
+  createInitialOrchestratorStats,
+  type OrchestratorConfig,
+  type OrchestratorPhase,
+  type OrchestratorTask,
+} from '../src/types.js';
+
+describe('OrchestratorVerifier', () => {
+  function createTestPhase(overrides?: Partial<OrchestratorPhase>): OrchestratorPhase {
+    return {
+      id: 'phase-1',
+      name: 'Test Phase',
+      description: 'Test',
+      order: 0,
+      status: 'executing',
+      tasks: [],
+      verificationCriteria: [],
+      testCommands: [],
+      maxAttempts: 3,
+      attempts: 1,
+      startedAt: Date.now(),
+      completedAt: null,
+      durationMs: null,
+      teamStrategy: { type: 'single' },
+      ...overrides,
+    };
+  }
+
+  describe('evaluateChecks', () => {
+    it('passes with no checks', async () => {
+      const verifier = new OrchestratorVerifier(DEFAULT_ORCHESTRATOR_CONFIG);
+      const phase = createTestPhase();
+
+      // No test commands, no criteria → should pass
+      const mockSession = {
+        on: vi.fn(),
+        off: vi.fn(),
+        sendInput: vi.fn(),
+      };
+
+      const result = await verifier.verifyPhase(phase, mockSession as never);
+      expect(result.passed).toBe(true);
+      expect(result.checks).toHaveLength(0);
+    });
+
+    it('skips verification in lenient mode with no checks', async () => {
+      const config: OrchestratorConfig = { ...DEFAULT_ORCHESTRATOR_CONFIG, verificationMode: 'lenient' };
+      const verifier = new OrchestratorVerifier(config);
+      const phase = createTestPhase();
+
+      const mockSession = {
+        on: vi.fn(),
+        off: vi.fn(),
+        sendInput: vi.fn(),
+      };
+
+      const result = await verifier.verifyPhase(phase, mockSession as never);
+      expect(result.passed).toBe(true);
+      expect(result.summary).toContain('skipped');
+    });
+  });
+});
+
+describe('OrchestratorConfig defaults', () => {
+  it('has sensible defaults', () => {
+    expect(DEFAULT_ORCHESTRATOR_CONFIG.plannerModel).toBe('opus');
+    expect(DEFAULT_ORCHESTRATOR_CONFIG.verificationMode).toBe('moderate');
+    expect(DEFAULT_ORCHESTRATOR_CONFIG.maxPhaseRetries).toBe(3);
+    expect(DEFAULT_ORCHESTRATOR_CONFIG.enableTeamAgents).toBe(true);
+    expect(DEFAULT_ORCHESTRATOR_CONFIG.autoApprove).toBe(false);
+  });
+});
+
+describe('createInitialOrchestratorStats', () => {
+  it('creates zeroed stats', () => {
+    const stats = createInitialOrchestratorStats();
+    expect(stats.phasesCompleted).toBe(0);
+    expect(stats.phasesFailed).toBe(0);
+    expect(stats.totalTasksCompleted).toBe(0);
+    expect(stats.totalTasksFailed).toBe(0);
+    expect(stats.replanCount).toBe(0);
+    expect(stats.totalDurationMs).toBe(0);
+  });
+});

test/routes/orchestrator-routes.test.ts

@@ -0,0 +1,335 @@
+/**
+ * @fileoverview Tests for orchestrator-routes route handlers.
+ *
+ * Uses app.inject() — no real HTTP ports needed.
+ * Port: N/A (app.inject doesn't open ports)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
+import { registerOrchestratorRoutes } from '../../src/web/routes/orchestrator-routes.js';
+
+describe('orchestrator-routes', () => {
+  let harness: RouteTestHarness;
+
+  beforeEach(async () => {
+    harness = await createRouteTestHarness(registerOrchestratorRoutes);
+  });
+
+  afterEach(async () => {
+    await harness.app.close();
+  });
+
+  // ========== GET /api/orchestrator/status ==========
+
+  describe('GET /api/orchestrator/status', () => {
+    it('returns idle when orchestrator is not initialized', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/orchestrator/status',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(body.state).toBe('idle');
+      expect(body.plan).toBeNull();
+    });
+
+    it('returns current status when loop exists', async () => {
+      const mockLoop = {
+        getStatus: vi.fn(() => ({
+          state: 'executing',
+          plan: { id: 'plan-1', goal: 'test', phases: [] },
+          currentPhaseIndex: 0,
+          startedAt: Date.now(),
+          completedAt: null,
+          config: {},
+          stats: {},
+        })),
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/orchestrator/status',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(body.state).toBe('executing');
+    });
+  });
+
+  // ========== GET /api/orchestrator/plan ==========
+
+  describe('GET /api/orchestrator/plan', () => {
+    it('returns null plan when not initialized', async () => {
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/orchestrator/plan',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(body.plan).toBeNull();
+    });
+
+    it('returns plan and current phase when loop exists', async () => {
+      const mockPlan = { id: 'plan-1', goal: 'test', phases: [{ id: 'p1', name: 'Phase 1' }] };
+      const mockLoop = {
+        getPlan: vi.fn(() => mockPlan),
+        getCurrentPhase: vi.fn(() => mockPlan.phases[0]),
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'GET',
+        url: '/api/orchestrator/plan',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(body.plan.id).toBe('plan-1');
+      expect(body.currentPhase.id).toBe('p1');
+    });
+  });
+
+  // ========== POST /api/orchestrator/start ==========
+
+  describe('POST /api/orchestrator/start', () => {
+    it('rejects empty goal', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/start',
+        payload: { goal: '' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+
+    it('rejects missing goal', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/start',
+        payload: {},
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+
+    it('initializes loop and starts when valid', async () => {
+      const mockLoop = {
+        isRunning: vi.fn(() => false),
+        start: vi.fn(async () => {}),
+        state: 'planning',
+        on: vi.fn(),
+      };
+      harness.ctx.initOrchestratorLoop = vi.fn(() => mockLoop as never);
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/start',
+        payload: { goal: 'Build a REST API' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(harness.ctx.initOrchestratorLoop).toHaveBeenCalled();
+    });
+
+    it('rejects start when already running', async () => {
+      const mockLoop = {
+        isRunning: vi.fn(() => true),
+        state: 'executing',
+        on: vi.fn(),
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/start',
+        payload: { goal: 'Another goal' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+  });
+
+  // ========== POST /api/orchestrator/stop ==========
+
+  describe('POST /api/orchestrator/stop', () => {
+    it('returns error when loop not initialized', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/stop',
+      });
+      // Should return 503 via thrown error
+      expect(res.statusCode).toBe(503);
+    });
+
+    it('stops the loop', async () => {
+      const mockLoop = {
+        stop: vi.fn(async () => {}),
+        state: 'idle',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/stop',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(mockLoop.stop).toHaveBeenCalled();
+    });
+  });
+
+  // ========== POST /api/orchestrator/approve ==========
+
+  describe('POST /api/orchestrator/approve', () => {
+    it('returns error when loop not initialized', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/approve',
+      });
+      expect(res.statusCode).toBe(503);
+    });
+
+    it('calls approve on the loop', async () => {
+      const mockLoop = {
+        approve: vi.fn(async () => {}),
+        state: 'approval',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/approve',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+    });
+  });
+
+  // ========== POST /api/orchestrator/reject ==========
+
+  describe('POST /api/orchestrator/reject', () => {
+    it('rejects missing feedback', async () => {
+      const mockLoop = { state: 'approval' };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/reject',
+        payload: {},
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(false);
+    });
+
+    it('calls reject with feedback', async () => {
+      const mockLoop = {
+        reject: vi.fn(async () => {}),
+        state: 'approval',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/reject',
+        payload: { feedback: 'Add more tests' },
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+    });
+  });
+
+  // ========== POST /api/orchestrator/pause ==========
+
+  describe('POST /api/orchestrator/pause', () => {
+    it('calls pause on the loop', async () => {
+      const mockLoop = {
+        pause: vi.fn(),
+        state: 'paused',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/pause',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+    });
+  });
+
+  // ========== POST /api/orchestrator/resume ==========
+
+  describe('POST /api/orchestrator/resume', () => {
+    it('calls resume on the loop', async () => {
+      const mockLoop = {
+        resume: vi.fn(async () => {}),
+        state: 'executing',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/resume',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+    });
+  });
+
+  // ========== POST /api/orchestrator/phase/:id/skip ==========
+
+  describe('POST /api/orchestrator/phase/:id/skip', () => {
+    it('calls skipPhase with the phase id', async () => {
+      const mockLoop = {
+        skipPhase: vi.fn(async () => {}),
+        state: 'executing',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/phase/phase-1/skip',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(mockLoop.skipPhase).toHaveBeenCalledWith('phase-1');
+    });
+  });
+
+  // ========== POST /api/orchestrator/phase/:id/retry ==========
+
+  describe('POST /api/orchestrator/phase/:id/retry', () => {
+    it('calls retryPhase with the phase id', async () => {
+      const mockLoop = {
+        retryPhase: vi.fn(async () => {}),
+        state: 'failed',
+      };
+      (harness.ctx as Record<string, unknown>).orchestratorLoop = mockLoop;
+
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: '/api/orchestrator/phase/phase-2/retry',
+      });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.ok).toBe(true);
+      expect(mockLoop.retryPhase).toHaveBeenCalledWith('phase-2');
+    });
+  });
+});

test/routes/system-routes.test.ts

@@ -366,6 +366,36 @@ describe('system-routes', () => {
       expect(body.success).toBe(false);
     });
 
+    it('saves lastUsedCase as partial update without overwriting other settings', async () => {
+      mockedReadFile.mockResolvedValue(
+        JSON.stringify({ showCost: true, showTokenCount: false, subagentTrackingEnabled: true }) as never
+      );
+
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: { lastUsedCase: 'my-test-case' },
+      });
+      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.lastUsedCase).toBe('my-test-case');
+      expect(writtenContent.showCost).toBe(true);
+      expect(writtenContent.showTokenCount).toBe(false);
+      expect(writtenContent.subagentTrackingEnabled).toBe(true);
+    });
+
+    it('rejects settings with modelConfig (strict schema prevents full-object PUT)', async () => {
+      const res = await harness.app.inject({
+        method: 'PUT',
+        url: '/api/settings',
+        payload: { lastUsedCase: 'test', modelConfig: { model: 'something' } },
+      });
+      // Fastify rejects unknown fields at schema validation level (400) before handler runs
+      expect(res.statusCode).toBe(400);
+    });
+
     it('rejects non-object body', async () => {
       const res = await harness.app.inject({
         method: 'PUT',