chore: version packages

Filter readdir and linked-case names through /^[a-zA-Z0-9_-]+$/ before
returning them from GET /api/cases. Prevents XSS via maliciously-named
directories reaching frontend inline onclick handlers where escapeHtml
is insufficient (HTML-decoded back to quotes before JS execution).

Also fix misleading "Drag or use arrows" hint (no drag-and-drop exists).

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

CHANGELOG.md

@@ -1,5 +1,102 @@
 # aicodeman
 
+## 0.5.9
+
+### Patch Changes
+
+- Mobile keyboard accessory bar: add configurable "Extended Keyboard Bar" setting (Settings > Display > Input) that toggles between simple mode (up/down arrows, /init, /clear, /compact, paste, dismiss) and extended mode (adds left/right arrows, Tab, Shift+Tab, Ctrl+O, Alt+Enter, Esc). Default is simple mode. Setting is device-specific (not synced to server).
+
+  Restyle dismiss button: muted steel-blue tone, fills remaining bar space via flex, larger tap target. Arrow buttons now blue.
+
+  Fix paste overlay visibility on mobile: dialog repositioned to top of screen (15vh from top) so the virtual keyboard doesn't cover it. Textarea enlarged for better usability.
+
+  (Also includes all v0.5.8 changes: case reorder/delete, XSS sanitization, auto-attach PTY on restart, mobile keyboard buttons, macOS installer fixes, terminal flicker fix, state store collision fix.)
+
+## 0.5.8
+
+### Patch Changes
+
+- Case management: add Manage tab with reorder (up/down arrows) and delete for cases; linked cases are unlinked (folder preserved), CASES_DIR cases are permanently deleted. New endpoints: DELETE /api/cases/:name, PUT /api/cases/order. SSE events: case:deleted, case:order-changed.
+
+  Security: sanitize case names from filesystem with /^[a-zA-Z0-9_-]+$/ regex before returning from GET /api/cases to prevent XSS via maliciously-named directories reaching frontend inline onclick handlers.
+
+  Auto-attach PTY: server now calls startInteractive() for recovered tmux sessions during startup so all sessions resume capturing output immediately after deploy, instead of waiting for client selection. Frontend auto-attach condition relaxed from (pid===null && status==='idle') to (pid===null && !\_ended).
+
+  Mobile keyboard accessory: add Shift+Tab, Tab, Esc, Alt+Enter, Left/Right arrow, and Ctrl+O buttons.
+
+  Terminal: fix flicker regression by moving viewport clear inside dimension guard.
+
+  State store: fix temp file collisions on concurrent writes.
+
+  macOS: fix installer failures when piped via curl | bash, add HTML cache support, launchd service template, and trust dialog handling.
+
+  Housekeeping: remove accidentally committed dist/state-store.js build artifact.
+
+## 0.5.7
+
+### Patch Changes
+
+- feat: support "Default (CLI default)" option for model selection. Adds a new empty-value option to the model dropdown that defers to the CLI's own default model instead of forcing a specific model. Ensures empty defaultModel values are treated as undefined when passed to session creation and Ralph loop start, preventing empty strings from being sent as model flags.
+
+## 0.5.6
+
+### Patch Changes
+
+- fix: default new sessions to opus[1m] (1M context window) instead of plain opus (200k context)
+
+## 0.5.5
+
+### Patch Changes
+
+- Add 1M Opus context quick setting — per-case and global toggle that writes `model: "opus[1m]"` to `.claude/settings.local.json` when creating new sessions. Fix mobile layout: banners (respawn, timer, orchestrator) between header and main content now visible by switching from margin-top on `.main` to padding-top on `.app`. Add tablet-optimized respawn banner styles and mobile phone banner refinements.
+
+## 0.5.4
+
+### Patch Changes
+
+- Fix terminal flicker regression — re-add server-side DEC 2026 synchronized output wrapping around batched terminal data. Ink spinner frames (cursor-up + redraw cycles) do not emit their own DEC 2026 markers, so without the server wrapper each partial cursor update rendered individually causing visible flicker. Also: extract SSE stream management, session listener wiring, and respawn event wiring from server.ts into dedicated modules; deduplicate error message extraction across 7 files with shared getErrorMessage() helper; update SSE event count in CLAUDE.md (106 → 117).
+
+## 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

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.5.0 (must match `package.json`)
+**Version**: 0.5.9 (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/**`.
 
@@ -111,7 +111,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **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` (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` → 15 domain files | See `@fileoverview` in index.ts |
+| **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.
 
@@ -119,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`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks).
+**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
 
@@ -167,7 +167,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ### SSE Event Registry
 
-~106 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
+~117 event types in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). Both must be kept in sync.
 
 ### API Routes
 

install.sh

@@ -7,7 +7,7 @@
 # Environment variables:
 #   CODEMAN_NONINTERACTIVE=1  - Skip all prompts (for CI/automation)
 #   CODEMAN_INSTALL_DIR       - Custom install directory (default: ~/.codeman/app)
-#   CODEMAN_SKIP_SYSTEMD=1    - Skip systemd service setup prompt
+#   CODEMAN_SKIP_SYSTEMD=1    - Skip systemd/launchd service setup prompt
 #   CODEMAN_NODE_VERSION      - Node.js major version to install (default: 22)
 #   CODEMAN_REPO_URL          - Custom git repository URL (default: upstream Codeman)
 #   CODEMAN_BRANCH            - Git branch to install (default: master)
@@ -353,8 +353,15 @@ ensure_sudo() {
         die "sudo is required but not installed. Please install packages manually or run as root."
     fi
     # Validate sudo access
-    if ! sudo -v 2>/dev/null; then
-        die "Failed to obtain sudo privileges."
+    # When piped (curl | bash), stdin is the pipe — redirect from /dev/tty so sudo can prompt
+    if [[ -e /dev/tty ]]; then
+        if ! sudo -v 2>/dev/null < /dev/tty; then
+            die "Failed to obtain sudo privileges."
+        fi
+    else
+        if ! sudo -v 2>/dev/null; then
+            die "Failed to obtain sudo privileges. Try running the script directly instead of piping."
+        fi
     fi
 }
 
@@ -372,7 +379,12 @@ ensure_homebrew() {
     fi
 
     info "Installing Homebrew first..."
-    /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    # When piped (curl | bash), stdin is the pipe — Homebrew needs TTY for sudo password prompt
+    if [[ -e /dev/tty ]]; then
+        /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" < /dev/tty
+    else
+        NONINTERACTIVE=1 /bin/bash -c "$(download_to_stdout https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    fi
 
     # Add Homebrew to PATH for Apple Silicon
     if [[ -f /opt/homebrew/bin/brew ]]; then
@@ -787,9 +799,84 @@ setup_sc_alias() {
 }
 
 # ============================================================================
-# Systemd Service Setup (Linux only)
+# Service Setup (Linux systemd / macOS launchd)
 # ============================================================================
 
+setup_launchd_service() {
+    local plist_label="com.codeman.web"
+    local agent_dir="$HOME/Library/LaunchAgents"
+    local agent_plist="$agent_dir/$plist_label.plist"
+    local daemon_plist="/Library/LaunchDaemons/$plist_label.plist"
+
+    info "Setting up macOS LaunchAgent..."
+
+    # Remove any existing LaunchDaemon (system-level) to prevent duplicates.
+    # We standardize on LaunchAgent (user-level) — it doesn't require sudo,
+    # inherits the user's environment, and is the correct choice for user apps.
+    if [[ -f "$daemon_plist" ]]; then
+        warn "Found system-level LaunchDaemon at $daemon_plist — removing to prevent duplicate"
+        sudo launchctl unload "$daemon_plist" 2>/dev/null || true
+        sudo rm -f "$daemon_plist"
+        success "Removed duplicate LaunchDaemon"
+    fi
+
+    # Unload existing agent before overwriting
+    if [[ -f "$agent_plist" ]]; then
+        launchctl unload "$agent_plist" 2>/dev/null || true
+    fi
+
+    mkdir -p "$agent_dir"
+
+    # Build PATH: ensure /opt/homebrew/bin (Apple Silicon) and ~/.local/bin are included
+    local svc_path="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+    # Find node binary path
+    local node_path
+    node_path=$(command -v node)
+
+    cat > "$agent_plist" << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>$plist_label</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$node_path</string>
+    <string>$INSTALL_DIR/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>$svc_path</string>
+    <key>HOME</key>
+    <string>$HOME</string>
+    <key>LANG</key>
+    <string>en_US.UTF-8</string>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>$HOME</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+
+    launchctl load "$agent_plist" 2>/dev/null || true
+
+    success "LaunchAgent installed and started"
+}
+
 setup_systemd_service() {
     local service_dir="$HOME/.config/systemd/user"
     local service_file="$service_dir/codeman-web.service"
@@ -1139,17 +1226,25 @@ main() {
     echo ""
 
     local launch_choice=""
-    local has_systemd=false
+    local has_service=false
+    local service_type=""
 
     if [[ "$os" == "linux" ]] && [[ "$SKIP_SYSTEMD" != "1" ]] && command -v systemctl &>/dev/null; then
-        has_systemd=true
+        has_service=true
+        service_type="systemd"
+    elif [[ "$os" == "macos" ]] && [[ "$SKIP_SYSTEMD" != "1" ]]; then
+        has_service=true
+        service_type="launchd"
     fi
 
-    if [[ "$has_systemd" == "true" ]]; then
+    if [[ "$has_service" == "true" ]]; then
+        local service_label="systemd service"
+        [[ "$service_type" == "launchd" ]] && service_label="LaunchAgent"
+
         echo -e "  ${BOLD}How would you like to run Codeman?${NC}"
         echo ""
         echo -e "    ${CYAN}1)${NC} Run now in this terminal"
-        echo -e "    ${CYAN}2)${NC} Install as systemd service (auto-start on boot)"
+        echo -e "    ${CYAN}2)${NC} Install as $service_label (auto-start on boot)"
         echo -e "    ${CYAN}3)${NC} Don't start — I'll run it later"
         echo ""
 
@@ -1166,7 +1261,7 @@ main() {
             done
         fi
     else
-        # macOS or no systemd — only offer run now or skip
+        # No service manager available — only offer run now or skip
         echo -e "  ${BOLD}Would you like to start Codeman now?${NC}"
         echo ""
         echo -e "    ${CYAN}1)${NC} Run now in this terminal"
@@ -1192,12 +1287,16 @@ main() {
 
     echo ""
 
-    # Handle systemd setup
+    # Handle service setup
     if [[ "$launch_choice" == "2" ]]; then
-        setup_systemd_service
+        if [[ "$service_type" == "launchd" ]]; then
+            setup_launchd_service
+        else
+            setup_systemd_service
+        fi
 
-        # Offer tunnel service if cloudflared is available
-        if check_cloudflared && [[ -f "$INSTALL_DIR/scripts/codeman-tunnel.service" ]]; then
+        # Offer tunnel service if cloudflared is available (Linux only — systemd tunnel service)
+        if [[ "$service_type" == "systemd" ]] && check_cloudflared && [[ -f "$INSTALL_DIR/scripts/codeman-tunnel.service" ]]; then
             echo ""
             if prompt_yes_no "Also set up Cloudflare tunnel service? (requires CODEMAN_PASSWORD)" "n"; then
                 setup_tunnel_service
@@ -1212,10 +1311,16 @@ main() {
         echo ""
         echo -e "  ${BOLD}Manage the service:${NC}"
         echo ""
-        echo -e "    ${CYAN}systemctl --user stop codeman-web${NC}    # Stop"
-        echo -e "    ${CYAN}systemctl --user restart codeman-web${NC} # Restart"
-        echo -e "    ${CYAN}systemctl --user status codeman-web${NC}  # Check status"
-        echo -e "    ${CYAN}journalctl --user -u codeman-web -f${NC}  # View logs"
+        if [[ "$service_type" == "launchd" ]]; then
+            echo -e "    ${CYAN}launchctl unload ~/Library/LaunchAgents/com.codeman.web.plist${NC}   # Stop"
+            echo -e "    ${CYAN}launchctl load ~/Library/LaunchAgents/com.codeman.web.plist${NC}     # Start"
+            echo -e "    ${CYAN}tail -f /tmp/codeman.log${NC}                                        # View logs"
+        else
+            echo -e "    ${CYAN}systemctl --user stop codeman-web${NC}    # Stop"
+            echo -e "    ${CYAN}systemctl --user restart codeman-web${NC} # Restart"
+            echo -e "    ${CYAN}systemctl --user status codeman-web${NC}  # Check status"
+            echo -e "    ${CYAN}journalctl --user -u codeman-web -f${NC}  # View logs"
+        fi
         echo ""
     fi
 
@@ -1289,11 +1394,17 @@ update() {
     success "Updated to $(node -e "console.log(require('./package.json').version)")"
     echo ""
 
-    # Auto-restart systemd service if it's running, otherwise tell the user
-    if systemctl --user is-active codeman-web.service &>/dev/null; then
+    # Auto-restart service if running, otherwise tell the user
+    local agent_plist="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+    if systemctl --user is-active codeman-web.service &>/dev/null 2>&1; then
         info "Restarting codeman-web service..."
         systemctl --user restart codeman-web.service
         success "codeman-web service restarted"
+    elif [[ -f "$agent_plist" ]]; then
+        info "Restarting LaunchAgent..."
+        launchctl unload "$agent_plist" 2>/dev/null || true
+        launchctl load "$agent_plist" 2>/dev/null || true
+        success "LaunchAgent restarted"
     else
         echo -e "  ${DIM}Restart codeman web to use the new version:${NC}"
         echo -e "    ${CYAN}pkill -f 'codeman.*web'; codeman web &${NC}"
@@ -1306,9 +1417,9 @@ uninstall() {
     info "Uninstalling Codeman..."
     echo ""
 
-    # Stop and remove systemd services
+    # Stop and remove systemd services (Linux)
     for svc in codeman-web codeman-tunnel; do
-        if systemctl --user is-active "${svc}.service" &>/dev/null; then
+        if systemctl --user is-active "${svc}.service" &>/dev/null 2>&1; then
             info "Stopping ${svc} service..."
             systemctl --user stop "${svc}.service"
         fi
@@ -1324,6 +1435,20 @@ uninstall() {
     done
     systemctl --user daemon-reload 2>/dev/null || true
 
+    # Stop and remove launchd services (macOS)
+    local agent_plist="$HOME/Library/LaunchAgents/com.codeman.web.plist"
+    local daemon_plist="/Library/LaunchDaemons/com.codeman.web.plist"
+    if [[ -f "$agent_plist" ]]; then
+        launchctl unload "$agent_plist" 2>/dev/null || true
+        rm -f "$agent_plist"
+        success "Removed LaunchAgent"
+    fi
+    if [[ -f "$daemon_plist" ]]; then
+        sudo launchctl unload "$daemon_plist" 2>/dev/null || true
+        sudo rm -f "$daemon_plist"
+        success "Removed LaunchDaemon"
+    fi
+
     # Remove symlinks
     local symlink_dir="$HOME/.local/bin"
     if [[ -L "$symlink_dir/codeman" ]]; then

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.5.0",
+  "version": "0.5.9",
   "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",

src/ai-checker-base.ts

@@ -30,6 +30,7 @@ import { join } from 'node:path';
 import { EventEmitter } from 'node:events';
 import { getAugmentedPath, ANSI_ESCAPE_PATTERN_SIMPLE } from './utils/index.js';
 import { AI_CHECK_MAX_BACKOFF_MS } from './config/ai-defaults.js';
+import { getErrorMessage } from './types.js';
 
 // ========== Security Validation ==========
 
@@ -293,7 +294,7 @@ export abstract class AiCheckerBase<
       this.emit('checkCompleted', result);
       return result;
     } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
+      const errorMsg = getErrorMessage(err);
       this.handleError(errorMsg);
       const result = this.createErrorResult(errorMsg, Date.now() - this.checkStartTime);
       this.emit('checkFailed', errorMsg);
@@ -412,9 +413,7 @@ export abstract class AiCheckerBase<
       });
       muxProcess.unref();
     } catch (err) {
-      throw new Error(
-        `Failed to spawn ${this.checkDescription} tmux session: ${err instanceof Error ? err.message : String(err)}`
-      );
+      throw new Error(`Failed to spawn ${this.checkDescription} tmux session: ${getErrorMessage(err)}`);
     }
 
     // Poll the temp file for completion

src/bash-tool-parser.ts

@@ -470,113 +470,91 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
    * Process a single pre-stripped line of terminal output.
    */
   private processCleanLine(cleanLine: string): void {
-    // Check for tool start
+    if (this._handleToolStart(cleanLine)) return;
+    if (this._handleToolCompletion(cleanLine)) return;
+    if (this._handleTextCommand(cleanLine)) return;
+    this._handleLogFileMention(cleanLine);
+  }
+
+  private _handleToolStart(cleanLine: string): boolean {
     const startMatch = cleanLine.match(BASH_TOOL_START_PATTERN);
-    if (startMatch) {
-      const command = startMatch[1];
-      const timeout = startMatch[2]?.trim();
+    if (!startMatch) return false;
 
-      // Check if this is a file-viewing command
-      if (this.isFileViewerCommand(command)) {
-        const filePaths = this.extractFilePaths(command);
+    const command = startMatch[1];
+    const timeout = startMatch[2]?.trim();
 
-        // Skip if any file path is already tracked (cross-pattern dedup)
-        if (filePaths.some((fp) => this.isFilePathTracked(fp))) {
-          return;
-        }
+    if (!this.isFileViewerCommand(command)) return true;
 
-        if (filePaths.length > 0) {
-          const tool: ActiveBashTool = {
-            id: uuidv4(),
-            command,
-            filePaths,
-            timeout,
-            startedAt: Date.now(),
-            status: 'running',
-            sessionId: this._sessionId,
-          };
+    const filePaths = this.extractFilePaths(command);
 
-          // 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]);
-            }
+    // Skip if any file path is already tracked (cross-pattern dedup)
+    if (filePaths.some((fp) => this.isFilePathTracked(fp))) return true;
+
+    if (filePaths.length > 0) {
+      const tool = this._createActiveTool(command, filePaths, 'running', timeout);
+
+      // Enforce max tools limit
+      if (this._activeTools.size >= MAX_ACTIVE_TOOLS) {
+        // 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;
           }
-
-          this._activeTools.set(tool.id, tool);
-          this._lastToolId = tool.id;
-
-          this.emit('toolStart', tool);
-          this.scheduleUpdate();
         }
-      }
-      return;
-    }
-
-    // Check for tool completion
-    if (TOOL_COMPLETION_PATTERN.test(cleanLine) && this._lastToolId) {
-      const tool = this._activeTools.get(this._lastToolId);
-      if (tool && tool.status === 'running') {
-        tool.status = 'completed';
-        this.emit('toolEnd', tool);
-        this.scheduleUpdate();
-
-        // Remove completed tool after a short delay to allow UI to show completion
-        this.cleanup.setTimeout(
-          () => {
-            if (this._destroyed) return;
-            this._activeTools.delete(tool.id);
-            this.scheduleUpdate();
-          },
-          2000,
-          { description: 'auto-remove completed tool' }
-        );
-      }
-      this._lastToolId = null;
-      return;
-    }
-
-    // Fallback: Check for command suggestions in plain text (e.g., "tail -f /tmp/file.log")
-    const textCmdMatch = cleanLine.match(TEXT_COMMAND_PATTERN);
-    if (textCmdMatch) {
-      const filePath = textCmdMatch[2];
-
-      // Create a suggestion tool (marked as 'suggestion' status)
-      const tool: ActiveBashTool = {
-        id: uuidv4(),
-        command: cleanLine.trim(),
-        filePaths: [filePath],
-        timeout: undefined,
-        startedAt: Date.now(),
-        status: 'running', // Shows as clickable
-        sessionId: this._sessionId,
-      };
-
-      // Don't add if file path already tracked (cross-pattern dedup)
-      if (this.isFilePathTracked(filePath)) {
-        return;
+        if (oldestKey) {
+          this._activeTools.delete(oldestKey);
+        }
       }
 
       this._activeTools.set(tool.id, tool);
+      this._lastToolId = tool.id;
+
       this.emit('toolStart', tool);
       this.scheduleUpdate();
-
-      // Auto-remove suggestions after 30 seconds
-      this.cleanup.setTimeout(
-        () => {
-          if (this._destroyed) return;
-          this._activeTools.delete(tool.id);
-          this.scheduleUpdate();
-        },
-        30000,
-        { description: 'auto-remove suggestion tool' }
-      );
-      return;
     }
 
-    // Last fallback: Check for log file paths mentioned anywhere in the line
+    return true;
+  }
+
+  private _handleToolCompletion(cleanLine: string): boolean {
+    if (!TOOL_COMPLETION_PATTERN.test(cleanLine) || !this._lastToolId) return false;
+
+    const tool = this._activeTools.get(this._lastToolId);
+    if (tool && tool.status === 'running') {
+      tool.status = 'completed';
+      this.emit('toolEnd', tool);
+      this.scheduleUpdate();
+
+      this._scheduleAutoRemove(tool.id, 2000, 'auto-remove completed tool');
+    }
+    this._lastToolId = null;
+    return true;
+  }
+
+  private _handleTextCommand(cleanLine: string): boolean {
+    const textCmdMatch = cleanLine.match(TEXT_COMMAND_PATTERN);
+    if (!textCmdMatch) return false;
+
+    const filePath = textCmdMatch[2];
+
+    // Don't add if file path already tracked (cross-pattern dedup)
+    if (this.isFilePathTracked(filePath)) return true;
+
+    const tool = this._createActiveTool(cleanLine.trim(), [filePath], 'running');
+
+    this._activeTools.set(tool.id, tool);
+    this.emit('toolStart', tool);
+    this.scheduleUpdate();
+
+    // Auto-remove suggestions after 30 seconds
+    this._scheduleAutoRemove(tool.id, 30000, 'auto-remove suggestion tool');
+    return true;
+  }
+
+  private _handleLogFileMention(cleanLine: string): void {
     LOG_FILE_MENTION_PATTERN.lastIndex = 0;
     let logMatch;
     while ((logMatch = LOG_FILE_MENTION_PATTERN.exec(cleanLine)) !== null) {
@@ -588,33 +566,46 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {
       // Skip if file path already tracked (cross-pattern dedup)
       if (this.isFilePathTracked(filePath)) continue;
 
-      const tool: ActiveBashTool = {
-        id: uuidv4(),
-        command: `View: ${filePath}`,
-        filePaths: [filePath],
-        timeout: undefined,
-        startedAt: Date.now(),
-        status: 'running',
-        sessionId: this._sessionId,
-      };
+      const tool = this._createActiveTool(`View: ${filePath}`, [filePath], 'running');
 
       this._activeTools.set(tool.id, tool);
       this.emit('toolStart', tool);
       this.scheduleUpdate();
 
       // Auto-remove after 60 seconds
-      this.cleanup.setTimeout(
-        () => {
-          if (this._destroyed) return;
-          this._activeTools.delete(tool.id);
-          this.scheduleUpdate();
-        },
-        60000,
-        { description: 'auto-remove log file tool' }
-      );
+      this._scheduleAutoRemove(tool.id, 60000, 'auto-remove log file tool');
     }
   }
 
+  private _createActiveTool(
+    command: string,
+    filePaths: string[],
+    status: ActiveBashTool['status'],
+    timeout?: string
+  ): ActiveBashTool {
+    return {
+      id: uuidv4(),
+      command,
+      filePaths,
+      timeout,
+      startedAt: Date.now(),
+      status,
+      sessionId: this._sessionId,
+    };
+  }
+
+  private _scheduleAutoRemove(toolId: string, delayMs: number, description: string): void {
+    this.cleanup.setTimeout(
+      () => {
+        if (this._destroyed) return;
+        this._activeTools.delete(toolId);
+        this.scheduleUpdate();
+      },
+      delayMs,
+      { description }
+    );
+  }
+
   /**
    * Check if a command is a file-viewing command worth tracking.
    */

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/file-stream-manager.ts

@@ -16,6 +16,7 @@ import { existsSync, statSync, realpathSync } from 'node:fs';
 import { resolve, relative, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { EventEmitter } from 'node:events';
+import { getErrorMessage } from './types.js';
 import { CLEANUP_CHECK_INTERVAL_MS, INACTIVITY_TIMEOUT_MS } from './config/server-timing.js';
 
 // ========== Configuration Constants ==========
@@ -172,10 +173,7 @@ export class FileStreamManager extends EventEmitter {
       }
     } catch (err) {
       const errorCode = err instanceof Error && 'code' in err ? (err as NodeJS.ErrnoException).code : 'UNKNOWN';
-      console.warn(
-        `[FileStreamManager] Failed to stat file "${absolutePath}" (${errorCode}):`,
-        err instanceof Error ? err.message : String(err)
-      );
+      console.warn(`[FileStreamManager] Failed to stat file "${absolutePath}" (${errorCode}):`, getErrorMessage(err));
       return { success: false, error: 'File not found or not accessible' };
     }
 

src/hooks-config.ts

@@ -116,6 +116,34 @@ export async function updateCaseEnvVars(casePath: string, envVars: Record<string
   await writeFile(settingsPath, JSON.stringify(existing, null, 2) + '\n');
 }
 
+/**
+ * Updates the `model` field in .claude/settings.local.json for the given case path.
+ * Pass a non-empty string to set, or empty/null to remove.
+ */
+export async function updateCaseModel(casePath: string, model: string | null): Promise<void> {
+  const claudeDir = join(casePath, '.claude');
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  const settingsPath = join(claudeDir, 'settings.local.json');
+  let existing: Record<string, unknown> = {};
+
+  try {
+    existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    existing = {};
+  }
+
+  if (model) {
+    existing.model = model;
+  } else {
+    delete existing.model;
+  }
+
+  await writeFile(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+}
+
 /**
  * Writes hooks config to .claude/settings.local.json in the given case path.
  * Merges with existing file content, only touching the `hooks` key.

src/orchestrator-loop.ts

@@ -499,27 +499,34 @@ export class OrchestratorLoop extends EventEmitter {
     }
   }
 
-  private handleTaskCompleted(queueTaskId: string): void {
+  private _finalizeTask(queueTaskId: string, status: 'completed' | 'failed', error?: string): OrchestratorTask | null {
     const orchTask = this.findOrchestratorTaskByQueueId(queueTaskId);
+    if (!orchTask) return null;
+
+    orchTask.status = status;
+    if (status === 'completed') {
+      orchTask.completedAt = Date.now();
+      this.stats.totalTasksCompleted++;
+    } else {
+      orchTask.error = error ?? null;
+      this.stats.totalTasksFailed++;
+    }
+    this.persist();
+    return orchTask;
+  }
+
+  private handleTaskCompleted(queueTaskId: string): void {
+    const orchTask = this._finalizeTask(queueTaskId, 'completed');
     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);
+    const orchTask = this._finalizeTask(queueTaskId, 'failed', error);
     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
@@ -553,19 +560,20 @@ export class OrchestratorLoop extends EventEmitter {
     }, this.config.phaseTimeoutMs);
   }
 
+  private _clearTimer(
+    timerKey: 'phasePollTimer' | 'phaseTimeoutTimer' | 'postPhaseTimer',
+    clearFn: typeof clearInterval | typeof clearTimeout
+  ): void {
+    if (this[timerKey]) {
+      clearFn(this[timerKey]);
+      this[timerKey] = null;
+    }
+  }
+
   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;
-    }
+    this._clearTimer('phasePollTimer', clearInterval);
+    this._clearTimer('phaseTimeoutTimer', clearTimeout);
+    this._clearTimer('postPhaseTimer', clearTimeout);
   }
 
   private pollPhaseStatus(phase: OrchestratorPhase): void {

src/orchestrator-verifier.ts

@@ -20,7 +20,13 @@
  */
 
 import type { Session } from './session.js';
-import type { OrchestratorPhase, OrchestratorConfig, VerificationResult, VerificationCheck } from './types.js';
+import {
+  getErrorMessage,
+  type OrchestratorPhase,
+  type OrchestratorConfig,
+  type VerificationResult,
+  type VerificationCheck,
+} from './types.js';
 
 // ═══════════════════════════════════════════════════════════════
 // Constants
@@ -111,7 +117,7 @@ export class OrchestratorVerifier {
           type: 'test_command',
           description: `Run: ${command}`,
           passed: false,
-          output: err instanceof Error ? err.message : String(err),
+          output: getErrorMessage(err),
         });
       }
     }
@@ -164,7 +170,7 @@ export class OrchestratorVerifier {
         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)}`,
+        output: `AI review timed out or failed: ${getErrorMessage(err)}`,
       };
     }
   }

src/plan-orchestrator.ts

@@ -20,7 +20,7 @@ import type { TerminalMultiplexer } from './mux-interface.js';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { RESEARCH_AGENT_PROMPT, PLANNER_PROMPT } from './prompts/index.js';
-import type { PlanItem } from './types.js';
+import { getErrorMessage, type PlanItem } from './types.js';
 
 // Re-export for backward compatibility
 export type { PlanItem };
@@ -231,6 +231,49 @@ export class PlanOrchestrator {
     return md;
   }
 
+  private _extractJsonFromResponse(response: string): string | null {
+    let jsonMatch = response.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+    if (jsonMatch) {
+      jsonMatch = [jsonMatch[1]]; // Use captured group (inside code block)
+    } else {
+      jsonMatch = response.match(/\{[\s\S]*\}/);
+    }
+    return jsonMatch ? jsonMatch[0] : null;
+  }
+
+  private _emitAgentFailure(
+    onSubagent: SubagentCallback | undefined,
+    agentId: string,
+    agentType: 'research' | 'planner',
+    model: string,
+    error: string,
+    durationMs: number
+  ): void {
+    onSubagent?.({
+      type: 'failed',
+      agentId,
+      agentType,
+      model,
+      status: 'failed',
+      error,
+      durationMs,
+    });
+  }
+
+  private _formatResearchSection(
+    parts: string[],
+    title: string,
+    items: unknown[],
+    formatter: (item: unknown) => string[]
+  ): void {
+    if (items.length === 0) return;
+    parts.push(title);
+    for (const item of items.slice(0, 5)) {
+      parts.push(...formatter(item));
+    }
+    parts.push('');
+  }
+
   async cancel(): Promise<void> {
     this.cancelled = true;
     // Stop all running sessions and await cleanup to prevent PTY process leaks
@@ -312,7 +355,7 @@ export class PlanOrchestrator {
     } catch (err) {
       return {
         success: false,
-        error: err instanceof Error ? err.message : String(err),
+        error: getErrorMessage(err),
       };
     }
   }
@@ -322,32 +365,23 @@ export class PlanOrchestrator {
 
     const parts: string[] = ['## Research Context\n'];
 
-    if (research.findings.externalResources.length > 0) {
-      parts.push('### External Resources');
-      for (const r of research.findings.externalResources.slice(0, 5)) {
-        parts.push(`- ${r.title}${r.url ? ` (${r.url})` : ''}`);
-        if (r.keyInsights.length > 0) {
-          parts.push(`  Key insights: ${r.keyInsights.slice(0, 3).join(', ')}`);
-        }
+    this._formatResearchSection(parts, '### External Resources', research.findings.externalResources, (item) => {
+      const r = item as ResearchResult['findings']['externalResources'][number];
+      const lines = [`- ${r.title}${r.url ? ` (${r.url})` : ''}`];
+      if (r.keyInsights.length > 0) {
+        lines.push(`  Key insights: ${r.keyInsights.slice(0, 3).join(', ')}`);
       }
-      parts.push('');
-    }
+      return lines;
+    });
 
-    if (research.findings.codebasePatterns.length > 0) {
-      parts.push('### Existing Codebase Patterns');
-      for (const p of research.findings.codebasePatterns.slice(0, 5)) {
-        parts.push(`- ${p.pattern} at ${p.location}`);
-      }
-      parts.push('');
-    }
+    this._formatResearchSection(parts, '### Existing Codebase Patterns', research.findings.codebasePatterns, (item) => {
+      const p = item as ResearchResult['findings']['codebasePatterns'][number];
+      return [`- ${p.pattern} at ${p.location}`];
+    });
 
-    if (research.findings.technicalRecommendations.length > 0) {
-      parts.push('### Recommendations');
-      for (const r of research.findings.technicalRecommendations.slice(0, 5)) {
-        parts.push(`- ${r}`);
-      }
-      parts.push('');
-    }
+    this._formatResearchSection(parts, '### Recommendations', research.findings.technicalRecommendations, (item) => [
+      `- ${item as string}`,
+    ]);
 
     return parts.join('\n');
   }
@@ -414,18 +448,20 @@ export class PlanOrchestrator {
 
       const durationMs = Date.now() - startTime;
 
-      // Extract JSON from response
-      const jsonMatch = response.match(/\{[\s\S]*\}/);
-      if (!jsonMatch) {
-        onSubagent?.({
-          type: 'failed',
-          agentId,
-          agentType: 'research',
-          model: this.researchModel,
-          status: 'failed',
-          error: 'No JSON found',
-          durationMs,
-        });
+      console.log(
+        `[PlanOrchestrator] Research response length: ${response.length}, first 500 chars:`,
+        response.substring(0, 500)
+      );
+
+      // Extract JSON from response — try multiple strategies
+      const jsonStr = this._extractJsonFromResponse(response);
+
+      if (!jsonStr) {
+        console.error(
+          `[PlanOrchestrator] No JSON found in research response. Full response:`,
+          response.substring(0, 2000)
+        );
+        this._emitAgentFailure(onSubagent, agentId, 'research', this.researchModel, 'No JSON found', durationMs);
         return {
           success: false,
           findings: {
@@ -441,17 +477,9 @@ export class PlanOrchestrator {
         };
       }
 
-      const parsed = tryParseJSON(jsonMatch[0]);
+      const parsed = tryParseJSON(jsonStr);
       if (!parsed.success) {
-        onSubagent?.({
-          type: 'failed',
-          agentId,
-          agentType: 'research',
-          model: this.researchModel,
-          status: 'failed',
-          error: parsed.error,
-          durationMs,
-        });
+        this._emitAgentFailure(onSubagent, agentId, 'research', this.researchModel, parsed.error!, durationMs);
         return {
           success: false,
           findings: {
@@ -495,16 +523,8 @@ export class PlanOrchestrator {
       return result;
     } catch (err) {
       const durationMs = Date.now() - startTime;
-      const error = err instanceof Error ? err.message : String(err);
-      onSubagent?.({
-        type: 'failed',
-        agentId,
-        agentType: 'research',
-        model: this.researchModel,
-        status: 'failed',
-        error,
-        durationMs,
-      });
+      const error = getErrorMessage(err);
+      this._emitAgentFailure(onSubagent, agentId, 'research', this.researchModel, error, durationMs);
       return {
         success: false,
         findings: {
@@ -587,32 +607,26 @@ export class PlanOrchestrator {
 
       const durationMs = Date.now() - startTime;
 
-      // Extract JSON from response
-      const jsonMatch = response.match(/\{[\s\S]*\}/);
-      if (!jsonMatch) {
-        onSubagent?.({
-          type: 'failed',
-          agentId,
-          agentType: 'planner',
-          model: this.plannerModel,
-          status: 'failed',
-          error: 'No JSON found',
-          durationMs,
-        });
+      console.log(
+        `[PlanOrchestrator] Planner response length: ${response.length}, first 500 chars:`,
+        response.substring(0, 500)
+      );
+
+      // Extract JSON from response — try multiple strategies
+      const jsonStr = this._extractJsonFromResponse(response);
+
+      if (!jsonStr) {
+        console.error(
+          `[PlanOrchestrator] No JSON found in planner response. Full response:`,
+          response.substring(0, 2000)
+        );
+        this._emitAgentFailure(onSubagent, agentId, 'planner', this.plannerModel, 'No JSON found', durationMs);
         return { success: false, error: 'No JSON in response' };
       }
 
-      const parsed = tryParseJSON(jsonMatch[0]);
+      const parsed = tryParseJSON(jsonStr);
       if (!parsed.success) {
-        onSubagent?.({
-          type: 'failed',
-          agentId,
-          agentType: 'planner',
-          model: this.plannerModel,
-          status: 'failed',
-          error: parsed.error,
-          durationMs,
-        });
+        this._emitAgentFailure(onSubagent, agentId, 'planner', this.plannerModel, parsed.error!, durationMs);
         return { success: false, error: parsed.error };
       }
 
@@ -637,16 +651,8 @@ export class PlanOrchestrator {
       return { success: true, items, gaps, warnings };
     } catch (err) {
       const durationMs = Date.now() - startTime;
-      const error = err instanceof Error ? err.message : String(err);
-      onSubagent?.({
-        type: 'failed',
-        agentId,
-        agentType: 'planner',
-        model: this.plannerModel,
-        status: 'failed',
-        error,
-        durationMs,
-      });
+      const error = getErrorMessage(err);
+      this._emitAgentFailure(onSubagent, agentId, 'planner', this.plannerModel, error, durationMs);
       return { success: false, error };
     } finally {
       // Always clean up session and progress interval — centralizing here

src/ralph-status-parser.ts

@@ -91,6 +91,67 @@ const COMPLETION_INDICATOR_PATTERNS = [
   /project\s+(?:is\s+)?(?:completed?|done|finished)/i,
 ];
 
+interface FieldParser<T> {
+  pattern: RegExp;
+  field: keyof RalphStatusBlock;
+  validate: (value: string) => boolean;
+  transform: (value: string) => T;
+  errorMsg: (value: string) => string;
+}
+
+const FIELD_PARSERS: FieldParser<RalphStatusValue | RalphTestsStatus | RalphWorkType | number | boolean | string>[] = [
+  {
+    pattern: RALPH_STATUS_FIELD_PATTERN,
+    field: 'status',
+    validate: (v) => ['IN_PROGRESS', 'COMPLETE', 'BLOCKED'].includes(v.toUpperCase()),
+    transform: (v) => v.toUpperCase() as RalphStatusValue,
+    errorMsg: (v) => `Invalid STATUS value: "${v}". Expected: IN_PROGRESS, COMPLETE, or BLOCKED`,
+  },
+  {
+    pattern: RALPH_TASKS_COMPLETED_PATTERN,
+    field: 'tasksCompletedThisLoop',
+    validate: (v) => !Number.isNaN(parseInt(v, 10)) && parseInt(v, 10) >= 0,
+    transform: (v) => parseInt(v, 10),
+    errorMsg: (v) => `Invalid TASKS_COMPLETED_THIS_LOOP value: "${v}". Expected: non-negative integer`,
+  },
+  {
+    pattern: RALPH_FILES_MODIFIED_PATTERN,
+    field: 'filesModified',
+    validate: (v) => !Number.isNaN(parseInt(v, 10)) && parseInt(v, 10) >= 0,
+    transform: (v) => parseInt(v, 10),
+    errorMsg: (v) => `Invalid FILES_MODIFIED value: "${v}". Expected: non-negative integer`,
+  },
+  {
+    pattern: RALPH_TESTS_STATUS_PATTERN,
+    field: 'testsStatus',
+    validate: (v) => ['PASSING', 'FAILING', 'NOT_RUN'].includes(v.toUpperCase()),
+    transform: (v) => v.toUpperCase() as RalphTestsStatus,
+    errorMsg: (v) => `Invalid TESTS_STATUS value: "${v}". Expected: PASSING, FAILING, or NOT_RUN`,
+  },
+  {
+    pattern: RALPH_WORK_TYPE_PATTERN,
+    field: 'workType',
+    validate: (v) => ['IMPLEMENTATION', 'TESTING', 'DOCUMENTATION', 'REFACTORING'].includes(v.toUpperCase()),
+    transform: (v) => v.toUpperCase() as RalphWorkType,
+    errorMsg: (v) =>
+      `Invalid WORK_TYPE value: "${v}". Expected: IMPLEMENTATION, TESTING, DOCUMENTATION, or REFACTORING`,
+  },
+  {
+    pattern: RALPH_EXIT_SIGNAL_PATTERN,
+    field: 'exitSignal',
+    validate: () => true,
+    transform: (v) => v.toLowerCase() === 'true',
+    errorMsg: () => '',
+  },
+  {
+    pattern: RALPH_RECOMMENDATION_PATTERN,
+    field: 'recommendation',
+    validate: () => true,
+    transform: (v) => v.trim(),
+    errorMsg: () => '',
+  },
+];
+
 /**
  * RalphStatusParser - Parses RALPH_STATUS blocks and manages circuit breaker.
  *
@@ -303,85 +364,21 @@ export class RalphStatusParser extends EventEmitter {
       const trimmedLine = line.trim();
       if (!trimmedLine) continue;
 
-      // Track whether this line matched any known field
       let matched = false;
 
-      // STATUS field (required)
-      const statusMatch = trimmedLine.match(RALPH_STATUS_FIELD_PATTERN);
-      if (statusMatch) {
-        const value = statusMatch[1].toUpperCase();
-        if (['IN_PROGRESS', 'COMPLETE', 'BLOCKED'].includes(value)) {
-          block.status = value as RalphStatusValue;
-        } else {
-          parseErrors.push(`Invalid STATUS value: "${value}". Expected: IN_PROGRESS, COMPLETE, or BLOCKED`);
+      for (const parser of FIELD_PARSERS) {
+        const match = trimmedLine.match(parser.pattern);
+        if (match) {
+          const rawValue = match[1];
+          if (parser.validate(rawValue)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (block as any)[parser.field] = parser.transform(rawValue);
+          } else {
+            parseErrors.push(parser.errorMsg(rawValue));
+          }
+          matched = true;
+          break;
         }
-        matched = true;
-      }
-
-      // TASKS_COMPLETED_THIS_LOOP field
-      const tasksMatch = trimmedLine.match(RALPH_TASKS_COMPLETED_PATTERN);
-      if (tasksMatch) {
-        const value = parseInt(tasksMatch[1], 10);
-        if (!Number.isNaN(value) && value >= 0) {
-          block.tasksCompletedThisLoop = value;
-        } else {
-          parseErrors.push(
-            `Invalid TASKS_COMPLETED_THIS_LOOP value: "${tasksMatch[1]}". Expected: non-negative integer`
-          );
-        }
-        matched = true;
-      }
-
-      // FILES_MODIFIED field
-      const filesMatch = trimmedLine.match(RALPH_FILES_MODIFIED_PATTERN);
-      if (filesMatch) {
-        const value = parseInt(filesMatch[1], 10);
-        if (!Number.isNaN(value) && value >= 0) {
-          block.filesModified = value;
-        } else {
-          parseErrors.push(`Invalid FILES_MODIFIED value: "${filesMatch[1]}". Expected: non-negative integer`);
-        }
-        matched = true;
-      }
-
-      // TESTS_STATUS field
-      const testsMatch = trimmedLine.match(RALPH_TESTS_STATUS_PATTERN);
-      if (testsMatch) {
-        const value = testsMatch[1].toUpperCase();
-        if (['PASSING', 'FAILING', 'NOT_RUN'].includes(value)) {
-          block.testsStatus = value as RalphTestsStatus;
-        } else {
-          parseErrors.push(`Invalid TESTS_STATUS value: "${value}". Expected: PASSING, FAILING, or NOT_RUN`);
-        }
-        matched = true;
-      }
-
-      // WORK_TYPE field
-      const workMatch = trimmedLine.match(RALPH_WORK_TYPE_PATTERN);
-      if (workMatch) {
-        const value = workMatch[1].toUpperCase();
-        if (['IMPLEMENTATION', 'TESTING', 'DOCUMENTATION', 'REFACTORING'].includes(value)) {
-          block.workType = value as RalphWorkType;
-        } else {
-          parseErrors.push(
-            `Invalid WORK_TYPE value: "${value}". Expected: IMPLEMENTATION, TESTING, DOCUMENTATION, or REFACTORING`
-          );
-        }
-        matched = true;
-      }
-
-      // EXIT_SIGNAL field
-      const exitMatch = trimmedLine.match(RALPH_EXIT_SIGNAL_PATTERN);
-      if (exitMatch) {
-        block.exitSignal = exitMatch[1].toLowerCase() === 'true';
-        matched = true;
-      }
-
-      // RECOMMENDATION field
-      const recMatch = trimmedLine.match(RALPH_RECOMMENDATION_PATTERN);
-      if (recMatch) {
-        block.recommendation = recMatch[1].trim();
-        matched = true;
       }
 
       // Track unknown fields for debugging (only if looks like a field)
@@ -475,38 +472,9 @@ export class RalphStatusParser extends EventEmitter {
     const prevState = this._circuitBreaker.state;
 
     if (hasProgress) {
-      // Progress detected - reset counters, possibly close circuit
-      this._circuitBreaker.consecutiveNoProgress = 0;
-      this._circuitBreaker.consecutiveSameError = 0;
-      this._circuitBreaker.lastProgressIteration = this._cycleCount;
-
-      if (this._circuitBreaker.state === 'HALF_OPEN') {
-        this._circuitBreaker.state = 'CLOSED';
-        this._circuitBreaker.reason = 'Progress detected, circuit closed';
-        this._circuitBreaker.reasonCode = 'progress_detected';
-      }
+      this._handleProgressDetected();
     } else {
-      // No progress
-      this._circuitBreaker.consecutiveNoProgress++;
-
-      // State transitions based on consecutive no-progress
-      if (this._circuitBreaker.state === 'CLOSED') {
-        if (this._circuitBreaker.consecutiveNoProgress >= 3) {
-          this._circuitBreaker.state = 'OPEN';
-          this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
-          this._circuitBreaker.reasonCode = 'no_progress_open';
-        } else if (this._circuitBreaker.consecutiveNoProgress >= 2) {
-          this._circuitBreaker.state = 'HALF_OPEN';
-          this._circuitBreaker.reason = 'Warning: no progress detected';
-          this._circuitBreaker.reasonCode = 'no_progress_warning';
-        }
-      } else if (this._circuitBreaker.state === 'HALF_OPEN') {
-        if (this._circuitBreaker.consecutiveNoProgress >= 3) {
-          this._circuitBreaker.state = 'OPEN';
-          this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
-          this._circuitBreaker.reasonCode = 'no_progress_open';
-        }
-      }
+      this._handleNoProgress();
     }
 
     // Track tests failure
@@ -535,6 +503,40 @@ export class RalphStatusParser extends EventEmitter {
     }
   }
 
+  private _handleProgressDetected(): void {
+    this._circuitBreaker.consecutiveNoProgress = 0;
+    this._circuitBreaker.consecutiveSameError = 0;
+    this._circuitBreaker.lastProgressIteration = this._cycleCount;
+
+    if (this._circuitBreaker.state === 'HALF_OPEN') {
+      this._circuitBreaker.state = 'CLOSED';
+      this._circuitBreaker.reason = 'Progress detected, circuit closed';
+      this._circuitBreaker.reasonCode = 'progress_detected';
+    }
+  }
+
+  private _handleNoProgress(): void {
+    this._circuitBreaker.consecutiveNoProgress++;
+
+    if (this._circuitBreaker.state === 'CLOSED') {
+      if (this._circuitBreaker.consecutiveNoProgress >= 3) {
+        this._circuitBreaker.state = 'OPEN';
+        this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
+        this._circuitBreaker.reasonCode = 'no_progress_open';
+      } else if (this._circuitBreaker.consecutiveNoProgress >= 2) {
+        this._circuitBreaker.state = 'HALF_OPEN';
+        this._circuitBreaker.reason = 'Warning: no progress detected';
+        this._circuitBreaker.reasonCode = 'no_progress_warning';
+      }
+    } else if (this._circuitBreaker.state === 'HALF_OPEN') {
+      if (this._circuitBreaker.consecutiveNoProgress >= 3) {
+        this._circuitBreaker.state = 'OPEN';
+        this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
+        this._circuitBreaker.reasonCode = 'no_progress_open';
+      }
+    }
+  }
+
   /**
    * Check line for completion indicators (natural language patterns).
    * Used for dual-condition exit gate.

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

@@ -70,12 +70,13 @@ import {
   AI_PLAN_CHECK_TIMEOUT_MS,
   AI_PLAN_CHECK_COOLDOWN_MS,
 } from './config/ai-defaults.js';
-import type {
-  RespawnCycleMetrics,
-  RespawnAggregateMetrics,
-  RalphLoopHealthScore,
-  TimingHistory,
-  CycleOutcome,
+import {
+  getErrorMessage,
+  type RespawnCycleMetrics,
+  type RespawnAggregateMetrics,
+  type RalphLoopHealthScore,
+  type TimingHistory,
+  type CycleOutcome,
 } from './types.js';
 
 // ========== Constants ==========
@@ -551,6 +552,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,27 +848,42 @@ export class RespawnController extends EventEmitter {
   private validateConfig(): void {
     const c = this.config;
 
-    // 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;
+    /**
+     * 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];
+      }
+    };
+
+    const REQUIRED_TIMEOUT_FIELDS = [
+      'idleTimeoutMs',
+      'completionConfirmMs',
+      'noOutputTimeoutMs',
+      'interStepDelayMs',
+      'aiIdleCheckTimeoutMs',
+      'aiIdleCheckMaxContext',
+      'aiPlanCheckTimeoutMs',
+      'aiPlanCheckMaxContext',
+    ] as const;
+    for (const field of REQUIRED_TIMEOUT_FIELDS) {
+      validatePositiveTimeout(field);
+    }
+
+    const ALLOW_ZERO_FIELDS = ['autoAcceptDelayMs', 'aiIdleCheckCooldownMs', 'aiPlanCheckCooldownMs'] as const;
+    for (const field of ALLOW_ZERO_FIELDS) {
+      validatePositiveTimeout(field, true);
+    }
 
     // Ensure completion confirm doesn't exceed no-output timeout
     if (c.completionConfirmMs > c.noOutputTimeoutMs) {
       c.completionConfirmMs = c.noOutputTimeoutMs;
     }
-
-    // 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;
-
-    // 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;
   }
 
   /** Wire up AI checker events to controller events (removes existing listeners first to prevent duplicates) */
@@ -987,11 +1011,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) {
@@ -1364,98 +1388,13 @@ export class RespawnController extends EventEmitter {
       this.lastTokenChangeTime = now;
     }
 
-    // Detect completion message FIRST (Layer 1) - PRIMARY DETECTION
-    // Check this before working patterns because completion message indicates
-    // the work is done, even if working patterns are still in the rolling window
-    if (isCompletionMessage(data)) {
-      // Clear the rolling window - completion marks a transition point
-      this.clearWorkingPatternWindow();
-      this.workingDetected = false;
-      this.completionMessageTime = now;
-      this.cancelAutoAcceptTimer(); // Normal idle flow handles this
-      this.log(`Completion message detected: "${data.trim().substring(0, 50)}..."`);
+    // Layer 1: Completion message (PRIMARY) — checked before working patterns
+    if (this._detectCompletionMessage(data, now)) return;
 
-      // In watching state, start completion confirmation timer
-      if (this._state === 'watching') {
-        this.startCompletionConfirmTimer();
-        return;
-      }
+    // Layer 4: Working patterns
+    if (this._detectWorkingPattern(data, now)) return;
 
-      // In waiting states, also use confirmation timer (same detection logic)
-      // This ensures we wait for Claude to finish before proceeding
-      // Note: 'watching' is already handled above and returns early
-      switch (this._state) {
-        case 'waiting_update':
-          this.startStepConfirmTimer('update');
-          break;
-        case 'waiting_clear':
-          this.checkClearComplete(); // /clear is quick, no need to wait
-          break;
-        case 'waiting_init':
-          this.startStepConfirmTimer('init');
-          break;
-        case 'waiting_kickstart':
-          this.startStepConfirmTimer('kickstart');
-          break;
-        // Non-waiting states: completion message is ignored
-        case 'confirming_idle':
-        case 'ai_checking':
-        case 'sending_update':
-        case 'sending_clear':
-        case 'sending_init':
-        case 'monitoring_init':
-        case 'sending_kickstart':
-        case 'stopped':
-          // Completion message during these states is ignored
-          break;
-        default:
-          assertNever(this._state, `Unhandled RespawnState in completion detection: ${this._state}`);
-      }
-      return;
-    }
-
-    // Detect working patterns (Layer 4)
-    const isWorking = this.checkWorkingPattern(data);
-    if (isWorking) {
-      this.workingDetected = true;
-      this.promptDetected = false;
-      this.elicitationDetected = false; // Clear on new work cycle
-      this.resetHookState(); // Clear hook signals on new work
-      this.lastWorkingPatternTime = now;
-
-      // Cancel hook confirmation timer if running
-      this.cancelTrackedTimer('hook-confirm', 'working patterns detected');
-
-      // Cancel any pending completion confirmation
-      this.cancelCompletionConfirm();
-
-      // Cancel any pending step confirmation (Claude is still working)
-      this.cancelStepConfirm();
-
-      // If AI check is running, cancel it (Claude is working)
-      if (this._state === 'ai_checking') {
-        this.log('Working patterns detected during AI check, cancelling');
-        this.aiChecker.cancel();
-        this.setState('watching');
-      }
-
-      // Cancel plan check if running (Claude started working)
-      if (this.planChecker.status === 'checking') {
-        this.log('Working patterns detected during plan check, cancelling');
-        this.planChecker.cancel();
-      }
-
-      // If we're monitoring init and work started, go to watching (no kickstart needed)
-      if (this._state === 'monitoring_init') {
-        this.log('/init triggered work, skipping kickstart');
-        this.emit('stepCompleted', 'init');
-        this.completeCycle();
-      }
-      return;
-    }
-
-    // In confirming_idle or ai_checking state, substantial output cancels the flow.
-    // This prevents false triggers when Claude pauses briefly mid-work.
+    // Substantial output during confirming_idle/ai_checking cancels the flow
     if (this._state === 'confirming_idle' || this._state === 'ai_checking') {
       // Strip ANSI escape codes to check if there's real content
       ANSI_ESCAPE_PATTERN_SIMPLE.lastIndex = 0;
@@ -1476,43 +1415,137 @@ export class RespawnController extends EventEmitter {
       }
     }
 
-    // Legacy fallback: detect prompt characters (still useful for waiting_* states)
-    const hasPrompt = PROMPT_PATTERNS.some((pattern) => data.includes(pattern));
-    if (hasPrompt) {
-      this.promptDetected = true;
-      this.workingDetected = false;
+    // Legacy fallback: prompt detection
+    this._detectPrompt(data);
+  }
 
-      // Handle legacy detection in waiting states - also use confirmation timers
-      switch (this._state) {
-        case 'waiting_update':
-          this.startStepConfirmTimer('update');
-          break;
-        case 'waiting_clear':
-          this.checkClearComplete(); // /clear is quick, no need to wait
-          break;
-        case 'waiting_init':
-          this.startStepConfirmTimer('init');
-          break;
-        case 'monitoring_init':
-          this.checkMonitoringInitIdle();
-          break;
-        case 'waiting_kickstart':
-          this.startStepConfirmTimer('kickstart');
-          break;
-        // Non-waiting states: prompt detection is informational only
-        case 'watching':
-        case 'confirming_idle':
-        case 'ai_checking':
-        case 'sending_update':
-        case 'sending_clear':
-        case 'sending_init':
-        case 'sending_kickstart':
-        case 'stopped':
-          // Prompt detection during these states doesn't trigger action
-          break;
-        default:
-          assertNever(this._state, `Unhandled RespawnState in prompt detection: ${this._state}`);
-      }
+  private _detectCompletionMessage(data: string, now: number): boolean {
+    if (!isCompletionMessage(data)) return false;
+
+    // Clear the rolling window - completion marks a transition point
+    this.clearWorkingPatternWindow();
+    this.workingDetected = false;
+    this.completionMessageTime = now;
+    this.cancelAutoAcceptTimer(); // Normal idle flow handles this
+    this.log(`Completion message detected: "${data.trim().substring(0, 50)}..."`);
+
+    // In watching state, start completion confirmation timer
+    if (this._state === 'watching') {
+      this.startCompletionConfirmTimer();
+      return true;
+    }
+
+    // In waiting states, also use confirmation timer (same detection logic)
+    // This ensures we wait for Claude to finish before proceeding
+    // Note: 'watching' is already handled above and returns early
+    switch (this._state) {
+      case 'waiting_update':
+        this.startStepConfirmTimer('update');
+        break;
+      case 'waiting_clear':
+        this.checkClearComplete(); // /clear is quick, no need to wait
+        break;
+      case 'waiting_init':
+        this.startStepConfirmTimer('init');
+        break;
+      case 'waiting_kickstart':
+        this.startStepConfirmTimer('kickstart');
+        break;
+      // Non-waiting states: completion message is ignored
+      case 'confirming_idle':
+      case 'ai_checking':
+      case 'sending_update':
+      case 'sending_clear':
+      case 'sending_init':
+      case 'monitoring_init':
+      case 'sending_kickstart':
+      case 'stopped':
+        // Completion message during these states is ignored
+        break;
+      default:
+        assertNever(this._state, `Unhandled RespawnState in completion detection: ${this._state}`);
+    }
+    return true;
+  }
+
+  private _detectWorkingPattern(data: string, now: number): boolean {
+    const isWorking = this.checkWorkingPattern(data);
+    if (!isWorking) return false;
+
+    this.workingDetected = true;
+    this.promptDetected = false;
+    this.elicitationDetected = false; // Clear on new work cycle
+    this.resetHookState(); // Clear hook signals on new work
+    this.lastWorkingPatternTime = now;
+
+    // Cancel hook confirmation timer if running
+    this.cancelTrackedTimer('hook-confirm', 'working patterns detected');
+
+    // Cancel any pending completion confirmation
+    this.cancelCompletionConfirm();
+
+    // Cancel any pending step confirmation (Claude is still working)
+    this.cancelStepConfirm();
+
+    // If AI check is running, cancel it (Claude is working)
+    if (this._state === 'ai_checking') {
+      this.log('Working patterns detected during AI check, cancelling');
+      this.aiChecker.cancel();
+      this.setState('watching');
+    }
+
+    // Cancel plan check if running (Claude started working)
+    if (this.planChecker.status === 'checking') {
+      this.log('Working patterns detected during plan check, cancelling');
+      this.planChecker.cancel();
+    }
+
+    // If we're monitoring init and work started, go to watching (no kickstart needed)
+    if (this._state === 'monitoring_init') {
+      this.log('/init triggered work, skipping kickstart');
+      this.emit('stepCompleted', 'init');
+      this.completeCycle();
+    }
+    return true;
+  }
+
+  private _detectPrompt(data: string): void {
+    const hasPrompt = PROMPT_PATTERNS.some((pattern) => data.includes(pattern));
+    if (!hasPrompt) return;
+
+    this.promptDetected = true;
+    this.workingDetected = false;
+
+    // Handle legacy detection in waiting states - also use confirmation timers
+    switch (this._state) {
+      case 'waiting_update':
+        this.startStepConfirmTimer('update');
+        break;
+      case 'waiting_clear':
+        this.checkClearComplete(); // /clear is quick, no need to wait
+        break;
+      case 'waiting_init':
+        this.startStepConfirmTimer('init');
+        break;
+      case 'monitoring_init':
+        this.checkMonitoringInitIdle();
+        break;
+      case 'waiting_kickstart':
+        this.startStepConfirmTimer('kickstart');
+        break;
+      // Non-waiting states: prompt detection is informational only
+      case 'watching':
+      case 'confirming_idle':
+      case 'ai_checking':
+      case 'sending_update':
+      case 'sending_clear':
+      case 'sending_init':
+      case 'sending_kickstart':
+      case 'stopped':
+        // Prompt detection during these states doesn't trigger action
+        break;
+      default:
+        assertNever(this._state, `Unhandled RespawnState in prompt detection: ${this._state}`);
     }
   }
 
@@ -1798,24 +1831,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();
     }
   }
 
@@ -2041,6 +2078,18 @@ export class RespawnController extends EventEmitter {
       return;
     }
 
+    // Check for active child processes (bash tools, test suites, builds, etc.)
+    // These may produce no terminal output, so restart timers to retry periodically.
+    const activeProcesses = this.session.getActiveChildProcesses();
+    if (activeProcesses.length > 0) {
+      const names = activeProcesses.map((p) => p.command).join(', ');
+      this.log(`Skipping AI check - ${activeProcesses.length} active child process(es): ${names}`);
+      this.logAction('detection', `Skipped AI check: child processes running (${names})`);
+      this.startNoOutputTimer();
+      this.startPreFilterTimer();
+      return;
+    }
+
     // If AI check is disabled or errored out, fall back to direct idle confirmation
     if (!this.config.aiIdleCheckEnabled || this.aiChecker.status === 'disabled') {
       this.log(`AI check unavailable (${this.aiChecker.status}), confirming idle directly via: ${reason}`);
@@ -2051,7 +2100,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;
     }
@@ -2136,7 +2185,7 @@ export class RespawnController extends EventEmitter {
         }
         if (this._state === 'stopped') return; // Guard against stopped state
         if (this._state === 'ai_checking') {
-          const errorMsg = err instanceof Error ? err.message : String(err);
+          const errorMsg = getErrorMessage(err);
           this.logAction('ai-check', `Failed: ${errorMsg.substring(0, 50)}`);
           this.emit('aiCheckFailed', errorMsg);
           this.setState('watching');
@@ -2198,36 +2247,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 +2272,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).
@@ -2322,7 +2384,7 @@ export class RespawnController extends EventEmitter {
         }
       })
       .catch((err) => {
-        const errorMsg = err instanceof Error ? err.message : String(err);
+        const errorMsg = getErrorMessage(err);
         this.emit('planCheckFailed', errorMsg);
         this.logAction('plan-check', `Failed: ${errorMsg.substring(0, 50)}`);
       });
@@ -2632,6 +2694,18 @@ export class RespawnController extends EventEmitter {
       return;
     }
 
+    // Safety check: if child processes are running (bash tools, test suites, builds, etc.)
+    const activeProcesses = this.session.getActiveChildProcesses();
+    if (activeProcesses.length > 0) {
+      const names = activeProcesses.map((p) => p.command).join(', ');
+      this.log(`Idle confirmation rejected - ${activeProcesses.length} active child process(es): ${names}`);
+      this.logAction('detection', `Rejected: child processes running (${names})`);
+      this.setState('watching');
+      this.startNoOutputTimer();
+      this.startPreFilterTimer();
+      return;
+    }
+
     this.log(`Idle confirmed via: ${reason}`);
     const status = this.getDetectionStatus();
     this.log(

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

@@ -29,6 +29,7 @@
  */
 
 import { EventEmitter } from 'node:events';
+import { execSync } from 'node:child_process';
 import { v4 as uuidv4 } from 'uuid';
 import * as pty from 'node-pty';
 import {
@@ -40,6 +41,7 @@ import {
   ActiveBashTool,
   NiceConfig,
   DEFAULT_NICE_CONFIG,
+  getErrorMessage,
   type ClaudeMode,
   type SessionMode,
   type OpenCodeConfig,
@@ -64,6 +66,7 @@ import {
   MAX_MESSAGES,
   MAX_LINE_BUFFER_SIZE,
 } from './config/buffer-limits.js';
+import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
 import {
   buildInteractiveArgs,
   buildPromptArgs,
@@ -271,6 +274,7 @@ export class Session extends EventEmitter {
   private _lastPromptTime: number = 0;
   private activityTimeout: NodeJS.Timeout | null = null;
   private _awaitingIdleConfirmation: boolean = false; // Prevents timeout reset during idle detection
+  private _trustDialogAccepted: boolean = false; // Prevents repeated trust dialog auto-accept
   private _taskTracker: TaskTracker;
 
   // Token tracking for auto-clear
@@ -538,6 +542,49 @@ export class Session extends EventEmitter {
     return this._isWorking;
   }
 
+  /**
+   * Check if the session's process tree has active child processes beyond Claude itself.
+   * Detects running bash tools, test suites, builds, servers, etc. that Claude spawned.
+   *
+   * The tmux pane PID is typically "claude" directly (bash exec'd into it). When Claude
+   * runs a bash tool, it spawns child processes: claude → bash → npm/node/python/etc.
+   * We check direct children of the pane PID, filtering out "claude" itself (for the rare
+   * case where bash wraps claude and didn't exec).
+   *
+   * Returns an array of {pid, command} for each child process, or empty array if none.
+   * Returns empty array if no mux session or on error (fail-open to avoid blocking respawn).
+   */
+  getActiveChildProcesses(): { pid: number; command: string }[] {
+    if (!this._muxSession) return [];
+
+    try {
+      const panePid = this._muxSession.pid;
+
+      // Single call: get direct children with their command names
+      const output = execSync(`ps -o pid=,comm= --ppid ${panePid} 2>/dev/null`, {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      }).trim();
+      if (!output) return [];
+
+      const activeProcesses: { pid: number; command: string }[] = [];
+      for (const line of output.split('\n')) {
+        const match = line.trim().match(/^(\d+)\s+(.+)/);
+        if (!match) continue;
+        const pid = parseInt(match[1], 10);
+        const command = match[2].trim();
+        // Skip the claude process itself (pane_pid may be bash wrapping claude)
+        if (command === 'claude') continue;
+        activeProcesses.push({ pid, command });
+      }
+
+      return activeProcesses;
+    } catch {
+      // ps returns exit code 1 when no matches — normal (no children)
+      return [];
+    }
+  }
+
   get lastPromptTime(): number {
     return this._lastPromptTime;
   }
@@ -871,18 +918,77 @@ export class Session extends EventEmitter {
    * session.write('help me with this code\r');
    * ```
    */
+  private async _setupOrAttachMuxSession(options: {
+    respawnPaneOptions: import('./mux-interface.js').RespawnPaneOptions;
+    createSessionOptions: import('./mux-interface.js').CreateSessionOptions;
+    spawnErrLabel: string;
+  }): Promise<{ isRestored: boolean }> {
+    const mux = this._mux!;
+
+    // Verify stale mux session — tmux may have been destroyed (e.g., killed externally)
+    if (this._muxSession && !mux.muxSessionExists(this._muxSession.muxName)) {
+      console.log('[Session] Stale mux session detected (tmux gone):', this._muxSession.muxName);
+      this._muxSession = null;
+    }
+
+    // Check if session exists but pane is dead (remain-on-exit keeps it alive)
+    // Respawn the pane instead of creating a whole new session — preserves tmux scrollback
+    let needsNewSession = false;
+    if (this._muxSession && mux.isPaneDead(this._muxSession.muxName)) {
+      console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
+      const newPid = await mux.respawnPane(options.respawnPaneOptions);
+      if (!newPid) {
+        console.error('[Session] Failed to respawn pane, will create new session');
+        needsNewSession = true;
+      } else {
+        // Wait a moment for the respawned process to fully start
+        await new Promise((resolve) => setTimeout(resolve, MUX_STARTUP_DELAY_MS));
+      }
+    }
+
+    // Check if we already have a mux session (restored session)
+    const isRestored = this._muxSession !== null && !needsNewSession;
+    if (isRestored) {
+      console.log('[Session] Attaching to existing mux session:', this._muxSession!.muxName);
+    } else {
+      // Create a new mux session
+      this._muxSession = await mux.createSession(options.createSessionOptions);
+      console.log('[Session] Created mux session:', this._muxSession.muxName);
+      // No extra sleep — createSession() already waits for tmux readiness
+    }
+
+    // Attach to the mux session via PTY
+    try {
+      this.ptyProcess = pty.spawn(mux.getAttachCommand(), mux.getAttachArgs(this._muxSession!.muxName), {
+        name: 'xterm-256color',
+        cols: 120,
+        rows: 40,
+        cwd: this.workingDir,
+        env: buildMuxAttachEnv(),
+      });
+    } catch (spawnErr) {
+      console.error(`[Session] Failed to spawn PTY for ${options.spawnErrLabel}:`, spawnErr);
+      this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
+      throw spawnErr;
+    }
+
+    return { isRestored };
+  }
+
+  private _handleTerminalOutput(data: string): void {
+    // BufferAccumulator handles auto-trimming when max size exceeded
+    this._terminalBuffer.append(data);
+    this._lastActivityAt = Date.now();
+    this.emit('terminal', data);
+    this.emit('output', data);
+  }
+
   async startInteractive(): Promise<void> {
     if (this.ptyProcess) {
       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(
@@ -892,18 +998,8 @@ export class Session extends EventEmitter {
     // If mux wrapping is enabled, create or attach to a mux session
     if (this._useMux && this._mux) {
       try {
-        // Verify stale mux session — tmux may have been destroyed (e.g., killed externally)
-        if (this._muxSession && !this._mux.muxSessionExists(this._muxSession.muxName)) {
-          console.log('[Session] Stale mux session detected (tmux gone):', this._muxSession.muxName);
-          this._muxSession = null;
-        }
-
-        // Check if session exists but pane is dead (remain-on-exit keeps it alive)
-        // Respawn the pane instead of creating a whole new session — preserves tmux scrollback
-        let needsNewSession = false;
-        if (this._muxSession && this._mux.isPaneDead(this._muxSession.muxName)) {
-          console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
-          const newPid = await this._mux.respawnPane({
+        const { isRestored } = await this._setupOrAttachMuxSession({
+          respawnPaneOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
             mode: this.mode,
@@ -913,23 +1009,8 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
-          });
-          if (!newPid) {
-            console.error('[Session] Failed to respawn pane, will create new session');
-            needsNewSession = true;
-          } else {
-            // Wait a moment for the respawned process to fully start
-            await new Promise((resolve) => setTimeout(resolve, MUX_STARTUP_DELAY_MS));
-          }
-        }
-
-        // Check if we already have a mux session (restored session)
-        const isRestoredSession = this._muxSession !== null && !needsNewSession;
-        if (isRestoredSession) {
-          console.log('[Session] Attaching to existing mux session:', this._muxSession!.muxName);
-        } else {
-          // Create a new mux session
-          this._muxSession = await this._mux.createSession({
+          },
+          createSessionOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
             mode: this.mode,
@@ -940,36 +1021,16 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
-          });
-          console.log('[Session] Created mux session:', this._muxSession.muxName);
-          // No extra sleep — createSession() already waits for tmux readiness
-        }
+          },
+          spawnErrLabel: 'mux attachment',
+        });
 
-        // Attach to the mux session via PTY
-        try {
-          this.ptyProcess = pty.spawn(
-            this._mux.getAttachCommand(),
-            this._mux.getAttachArgs(this._muxSession!.muxName),
-            {
-              name: 'xterm-256color',
-              cols: 120,
-              rows: 40,
-              cwd: this.workingDir,
-              env: buildMuxAttachEnv(),
-            }
-          );
-
-          // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
-          this._claudeSessionId = this._resumeSessionId || this.id;
-        } catch (spawnErr) {
-          console.error('[Session] Failed to spawn PTY for mux attachment:', spawnErr);
-          this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
-          throw spawnErr;
-        }
+        // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
+        this._claudeSessionId = this._resumeSessionId || this.id;
 
         // For NEW mux sessions: wait for readiness then clean buffer
         // For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
-        if (!isRestoredSession) {
+        if (!isRestored) {
           if (this.mode === 'opencode') {
             // OpenCode uses Bubble Tea TUI — no ❯ prompt to detect.
             // Wait for TUI to stabilize (output stops changing), then mark ready.
@@ -1056,12 +1117,17 @@ export class Session extends EventEmitter {
       const data = rawData.replace(FOCUS_ESCAPE_FILTER, '').replace(CTRL_L_PATTERN, ''); // Remove Ctrl+L
       if (!data) return; // Skip if only filtered sequences
 
-      // BufferAccumulator handles auto-trimming when max size exceeded
-      this._terminalBuffer.append(data);
-      this._lastActivityAt = Date.now();
+      this._handleTerminalOutput(data);
 
-      this.emit('terminal', data);
-      this.emit('output', data);
+      // === Auto-accept workspace trust dialog ===
+      // Claude CLI 2.x shows "Yes, I trust this folder" prompt on first launch per directory.
+      // Codeman sessions always use --dangerously-skip-permissions, so auto-accept.
+      if (!this._trustDialogAccepted && data.includes('trust this folder')) {
+        this._trustDialogAccepted = true;
+        console.log(`[Session] Auto-accepting workspace trust dialog for: ${this.id}`);
+        // Send Enter to accept the default selection ("Yes, I trust this folder")
+        this.writeViaMux('\r');
+      }
 
       // === Idle/working detection runs on every chunk (latency-sensitive) ===
       // Detect if Claude is working or at prompt
@@ -1257,13 +1323,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';
@@ -1275,69 +1335,26 @@ export class Session extends EventEmitter {
     // If mux wrapping is enabled, create or attach to a mux session
     if (this._useMux && this._mux) {
       try {
-        // Verify stale mux session — tmux may have been destroyed externally
-        if (this._muxSession && !this._mux.muxSessionExists(this._muxSession.muxName)) {
-          console.log('[Session] Stale mux session detected (tmux gone):', this._muxSession.muxName);
-          this._muxSession = null;
-        }
-
-        // Check if session exists but pane is dead (remain-on-exit keeps it alive)
-        let needsNewSession = false;
-        if (this._muxSession && this._mux.isPaneDead(this._muxSession.muxName)) {
-          console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
-          const newPid = await this._mux.respawnPane({
+        const { isRestored } = await this._setupOrAttachMuxSession({
+          respawnPaneOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
             mode: 'shell',
             niceConfig: this._niceConfig,
-          });
-          if (!newPid) {
-            console.error('[Session] Failed to respawn pane, will create new session');
-            needsNewSession = true;
-          } else {
-            await new Promise((resolve) => setTimeout(resolve, MUX_STARTUP_DELAY_MS));
-          }
-        }
-
-        // Check if we already have a mux session (restored session)
-        const isRestoredSession = this._muxSession !== null && !needsNewSession;
-        if (isRestoredSession) {
-          console.log('[Session] Attaching to existing mux session:', this._muxSession!.muxName);
-        } else {
-          // Create a new mux session
-          this._muxSession = await this._mux.createSession({
+          },
+          createSessionOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
             mode: 'shell',
             name: this._name,
             niceConfig: this._niceConfig,
-          });
-          console.log('[Session] Created mux session:', this._muxSession.muxName);
-          // No extra sleep — createSession() already waits for tmux readiness
-        }
-
-        // Attach to the mux session via PTY
-        try {
-          this.ptyProcess = pty.spawn(
-            this._mux.getAttachCommand(),
-            this._mux.getAttachArgs(this._muxSession!.muxName),
-            {
-              name: 'xterm-256color',
-              cols: 120,
-              rows: 40,
-              cwd: this.workingDir,
-              env: buildMuxAttachEnv(),
-            }
-          );
-        } catch (spawnErr) {
-          console.error('[Session] Failed to spawn PTY for shell mux attachment:', spawnErr);
-          this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
-          throw spawnErr;
-        }
+          },
+          spawnErrLabel: 'shell mux attachment',
+        });
 
         // For NEW sessions: clear by sending 'clear' command to the shell
         // For RESTORED sessions: don't clear - we want to see the existing output
-        if (!isRestoredSession) {
+        if (!isRestored) {
           setTimeout(() => {
             if (this.ptyProcess) {
               this._terminalBuffer.clear();
@@ -1378,12 +1395,7 @@ export class Session extends EventEmitter {
       const data = rawData.replace(FOCUS_ESCAPE_FILTER, '');
       if (!data) return; // Skip if only focus sequences
 
-      // BufferAccumulator handles auto-trimming when max size exceeded
-      this._terminalBuffer.append(data);
-      this._lastActivityAt = Date.now();
-
-      this.emit('terminal', data);
-      this.emit('output', data);
+      this._handleTerminalOutput(data);
     });
 
     this.ptyProcess.onExit(({ exitCode }) => {
@@ -1448,13 +1460,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;
@@ -1497,12 +1503,7 @@ export class Session extends EventEmitter {
           const data = rawData.replace(FOCUS_ESCAPE_FILTER, '');
           if (!data) return; // Skip if only focus sequences
 
-          // BufferAccumulator handles auto-trimming when max size exceeded
-          this._terminalBuffer.append(data);
-          this._lastActivityAt = Date.now();
-
-          this.emit('terminal', data);
-          this.emit('output', data);
+          this._handleTerminalOutput(data);
 
           // Also try to parse JSON lines for structured data
           this.processOutput(data);
@@ -1534,9 +1535,11 @@ export class Session extends EventEmitter {
             this._status = 'idle';
             const cost = resultMsg.total_cost_usd || 0;
             this._totalCost += cost;
-            this.emit('completion', resultMsg.result || '', cost);
+            // Claude CLI stream-json may return empty result field — fall back to accumulated text output
+            const result = resultMsg.result || this._textOutput.value || '';
+            this.emit('completion', result, cost);
             if (resolve) {
-              resolve({ result: resultMsg.result || '', cost });
+              resolve({ result, cost });
             }
           } else if (exitCode !== 0 || (resultMsg && resultMsg.is_error)) {
             this._status = 'error';
@@ -1565,6 +1568,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 +1720,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');
       }
@@ -1955,7 +2012,7 @@ export class Session extends EventEmitter {
     this._status = 'busy';
     this._lastActivityAt = Date.now();
     this.runPrompt(input).catch((err) => {
-      const errorMsg = err instanceof Error ? err.message : String(err);
+      const errorMsg = getErrorMessage(err);
       // Clean up task state so the task queue doesn't get stuck
       if (this._currentTaskId) {
         const taskId = this._currentTaskId;
@@ -2030,43 +2087,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

@@ -116,6 +116,26 @@ export class StateStore {
     this.loadRalphStates();
   }
 
+  private _mergeWithInitialState(parsed: Partial<AppState>): AppState {
+    const initial = createInitialState();
+    return {
+      ...initial,
+      ...parsed,
+      sessions: { ...parsed.sessions },
+      tasks: { ...parsed.tasks },
+      ralphLoop: { ...initial.ralphLoop, ...parsed.ralphLoop },
+      config: { ...initial.config, ...parsed.config },
+    };
+  }
+
+  private _resetCircuitBreaker(): void {
+    this.consecutiveSaveFailures = 0;
+    if (this.circuitBreakerOpen) {
+      console.log('[StateStore] Circuit breaker CLOSED - save succeeded');
+      this.circuitBreakerOpen = false;
+    }
+  }
+
   private ensureDir(): void {
     const dir = dirname(this.filePath);
     if (!existsSync(dir)) {
@@ -132,15 +152,7 @@ export class StateStore {
         if (existsSync(path)) {
           const data = readFileSync(path, 'utf-8');
           const parsed = JSON.parse(data) as Partial<AppState>;
-          const initial = createInitialState();
-          const result = {
-            ...initial,
-            ...parsed,
-            sessions: { ...parsed.sessions },
-            tasks: { ...parsed.tasks },
-            ralphLoop: { ...initial.ralphLoop, ...parsed.ralphLoop },
-            config: { ...initial.config, ...parsed.config },
-          };
+          const result = this._mergeWithInitialState(parsed);
           if (path !== this.filePath) {
             console.warn(`[StateStore] Recovered state from backup: ${path}`);
           }
@@ -195,16 +207,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 +221,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 +248,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 +273,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) {
@@ -263,30 +309,12 @@ export class StateStore {
 
     this.ensureDir();
 
-    const tempPath = this.filePath + '.tmp';
+    const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.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.
@@ -305,11 +333,7 @@ export class StateStore {
       await writeFile(tempPath, json, 'utf-8');
       await rename(tempPath, this.filePath);
 
-      this.consecutiveSaveFailures = 0;
-      if (this.circuitBreakerOpen) {
-        console.log('[StateStore] Circuit breaker CLOSED - save succeeded');
-        this.circuitBreakerOpen = false;
-      }
+      this._resetCircuitBreaker();
     } catch (err) {
       console.error('[StateStore] Failed to write state file:', err);
       // Re-mark dirty so the data is retried on the next save cycle
@@ -349,29 +373,11 @@ export class StateStore {
 
     this.ensureDir();
 
-    const tempPath = this.filePath + '.tmp';
+    const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.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 {
@@ -387,11 +393,7 @@ export class StateStore {
       renameSync(tempPath, this.filePath);
       // Clear dirty flag only AFTER successful write
       this.dirty = false;
-      this.consecutiveSaveFailures = 0;
-      if (this.circuitBreakerOpen) {
-        console.log('[StateStore] Circuit breaker CLOSED - save succeeded');
-        this.circuitBreakerOpen = false;
-      }
+      this._resetCircuitBreaker();
     } catch (err) {
       console.error('[StateStore] Failed to write state file:', err);
       this.consecutiveSaveFailures++;
@@ -417,15 +419,7 @@ export class StateStore {
       if (existsSync(backupPath)) {
         const backupContent = readFileSync(backupPath, 'utf-8');
         const parsed = JSON.parse(backupContent) as Partial<AppState>;
-        const initial = createInitialState();
-        this.state = {
-          ...initial,
-          ...parsed,
-          sessions: { ...parsed.sessions },
-          tasks: { ...parsed.tasks },
-          ralphLoop: { ...initial.ralphLoop, ...parsed.ralphLoop },
-          config: { ...initial.config, ...parsed.config },
-        };
+        this.state = this._mergeWithInitialState(parsed);
         console.log('[StateStore] Successfully recovered state from backup');
         // Reset circuit breaker after successful recovery
         this.circuitBreakerOpen = false;

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)}`);
         }
       }
     }
@@ -930,6 +988,24 @@ export class SubagentWatcher extends EventEmitter {
     return truncated.replace(/[.!?,:\s]+$/, '');
   }
 
+  private async _resolveDescription(
+    projectHash: string,
+    sessionId: string,
+    agentId: string,
+    filePath: string,
+    fallbackText?: string
+  ): Promise<string | undefined> {
+    // First try parent transcript (most reliable)
+    const fromParent = await this.extractDescriptionFromParentTranscript(projectHash, sessionId, agentId);
+    if (fromParent) return fromParent;
+
+    // Fallback: inline text (from processEntry) or file extraction
+    if (fallbackText) {
+      return this.extractSmartTitle(fallbackText);
+    }
+    return this.extractDescriptionFromFile(filePath);
+  }
+
   /**
    * Extract the short description from the parent session's transcript.
    * This is the most reliable method because it reads the actual Task tool result
@@ -1027,15 +1103,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();
@@ -1195,18 +1263,13 @@ export class SubagentWatcher extends EventEmitter {
 
       // Retry description extraction if missing (race condition fix)
       if (!existingInfo.description) {
-        // First try parent transcript (most reliable)
-        let extractedDescription = await this.extractDescriptionFromParentTranscript(
+        const extractedDescription = await this._resolveDescription(
           existingInfo.projectHash,
           existingInfo.sessionId,
-          agentId
+          agentId,
+          filePath
         );
-        // Fallback to subagent file
-        if (!extractedDescription) {
-          extractedDescription = await this.extractDescriptionFromFile(filePath);
-        }
         if (extractedDescription) {
-          // Check if this is an internal agent - if so, remove it
           if (this.isInternalAgent(extractedDescription)) {
             this.removeAgent(agentId);
             return;
@@ -1257,13 +1320,7 @@ export class SubagentWatcher extends EventEmitter {
     }
 
     // Extract description - prefer reading from parent transcript (most reliable)
-    // The parent transcript has the exact Task tool call with description parameter
-    let description = await this.extractDescriptionFromParentTranscript(projectHash, sessionId, agentId);
-
-    // Fallback: extract a smart title from the subagent's prompt if parent lookup failed
-    if (!description) {
-      description = await this.extractDescriptionFromFile(filePath);
-    }
+    const description = await this._resolveDescription(projectHash, sessionId, agentId, filePath);
 
     // Skip internal Claude Code agents (e.g., suggestion mode) - not real subagents
     if (this.isInternalAgent(description)) {
@@ -1286,14 +1343,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);
       }
@@ -1363,51 +1413,11 @@ export class SubagentWatcher extends EventEmitter {
   private async processEntry(entry: SubagentTranscriptEntry, agentId: string, sessionId: string): Promise<void> {
     const info = this.agentInfo.get(agentId);
 
-    // Extract model from assistant messages (first one sets the model)
-    if (info && entry.type === 'assistant' && entry.message?.model && !info.model) {
-      info.model = entry.message.model;
-      info.modelShort = this.extractModelShort(entry.message.model);
-      this.emit('subagent:updated', info);
-    }
+    if (info) {
+      this._processModelInfo(entry, info);
+      this._processTokenInfo(entry, info);
 
-    // Aggregate token usage from messages
-    if (info && entry.message?.usage) {
-      if (entry.message.usage.input_tokens) {
-        info.totalInputTokens = (info.totalInputTokens || 0) + entry.message.usage.input_tokens;
-      }
-      if (entry.message.usage.output_tokens) {
-        info.totalOutputTokens = (info.totalOutputTokens || 0) + entry.message.usage.output_tokens;
-      }
-    }
-
-    // Check if this is first user message and description is missing
-    if (info && !info.description && entry.type === 'user' && entry.message?.content) {
-      // First try parent transcript (most reliable)
-      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();
-          }
-        }
-        if (text) {
-          description = this.extractSmartTitle(text);
-        }
-      }
-      if (description) {
-        // Check if this is an internal agent - if so, remove it
-        if (this.isInternalAgent(description)) {
-          this.removeAgent(agentId);
-          return;
-        }
-        info.description = description;
-        this.emit('subagent:updated', info);
-      }
+      if (await this._processDescription(entry, agentId, info)) return;
     }
 
     if (entry.type === 'progress' && entry.data) {
@@ -1418,7 +1428,6 @@ export class SubagentWatcher extends EventEmitter {
         progressType: entry.data.type,
         query: entry.data.query,
         resultCount: entry.data.resultCount,
-        // Extract hook event info if present
         hookEvent: entry.data.hookEvent,
         hookName:
           entry.data.hookName ||
@@ -1428,139 +1437,166 @@ export class SubagentWatcher extends EventEmitter {
       };
       this.emit('subagent:progress', progress);
     } else if (entry.type === 'assistant' && 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 > 0) {
-          const message: SubagentMessage = {
+      this._processAssistantContent(entry, agentId, sessionId);
+    } else if (entry.type === 'user' && entry.message?.content) {
+      this._processUserContent(entry, agentId, sessionId);
+    }
+  }
+
+  private _processModelInfo(entry: SubagentTranscriptEntry, agent: SubagentInfo): void {
+    if (entry.type === 'assistant' && entry.message?.model && !agent.model) {
+      agent.model = entry.message.model;
+      agent.modelShort = this.extractModelShort(entry.message.model);
+      this.emit('subagent:updated', agent);
+    }
+  }
+
+  private _processTokenInfo(entry: SubagentTranscriptEntry, agent: SubagentInfo): void {
+    if (!entry.message?.usage) return;
+    if (entry.message.usage.input_tokens) {
+      agent.totalInputTokens = (agent.totalInputTokens || 0) + entry.message.usage.input_tokens;
+    }
+    if (entry.message.usage.output_tokens) {
+      agent.totalOutputTokens = (agent.totalOutputTokens || 0) + entry.message.usage.output_tokens;
+    }
+  }
+
+  private async _processDescription(
+    entry: SubagentTranscriptEntry,
+    agentId: string,
+    agent: SubagentInfo
+  ): Promise<boolean> {
+    if (agent.description || entry.type !== 'user' || !entry.message?.content) return false;
+
+    const fallbackText = this.extractFirstTextContent(entry.message.content);
+    const description = await this._resolveDescription(
+      agent.projectHash,
+      agent.sessionId,
+      agentId,
+      agent.filePath,
+      fallbackText
+    );
+    if (description) {
+      if (this.isInternalAgent(description)) {
+        this.removeAgent(agentId);
+        return true;
+      }
+      agent.description = description;
+      this.emit('subagent:updated', agent);
+    }
+    return false;
+  }
+
+  private _processAssistantContent(entry: SubagentTranscriptEntry, agentId: string, sessionId: string): void {
+    const messageContent = entry.message!.content;
+    if (typeof messageContent === 'string') {
+      const text = messageContent.trim();
+      if (text.length > 0) {
+        const message: SubagentMessage = {
+          agentId,
+          sessionId,
+          timestamp: entry.timestamp,
+          role: 'assistant',
+          text: text.substring(0, MESSAGE_TEXT_LIMIT),
+        };
+        this.emit('subagent:message', message);
+      }
+    } else {
+      for (const content of messageContent) {
+        if (content.type === 'tool_use' && content.name) {
+          // Store toolUseId for linking to results, with timestamp for TTL cleanup
+          if (content.id) {
+            if (!this.pendingToolCalls.has(agentId)) {
+              this.pendingToolCalls.set(agentId, new Map());
+            }
+            const agentCalls = this.pendingToolCalls.get(agentId)!;
+            // Enforce size limit to prevent memory leak from rapid tool calls
+            if (agentCalls.size >= MAX_PENDING_TOOL_CALLS) {
+              // FIFO eviction: delete first (oldest) entry using Map insertion order
+              const firstKey = agentCalls.keys().next().value;
+              if (firstKey !== undefined) agentCalls.delete(firstKey);
+            }
+            agentCalls.set(content.id, {
+              toolName: content.name,
+              timestamp: Date.now(),
+            });
+          }
+
+          const toolCall: SubagentToolCall = {
             agentId,
             sessionId,
             timestamp: entry.timestamp,
-            role: 'assistant',
-            text: text.substring(0, MESSAGE_TEXT_LIMIT),
+            tool: content.name,
+            input: this.getTruncatedInput(content.name, content.input || {}),
+            toolUseId: content.id,
+            fullInput: content.input || {},
           };
-          this.emit('subagent:message', message);
-        }
-      } else {
-        for (const content of entry.message.content) {
-          if (content.type === 'tool_use' && content.name) {
-            // Store toolUseId for linking to results, with timestamp for TTL cleanup
-            if (content.id) {
-              if (!this.pendingToolCalls.has(agentId)) {
-                this.pendingToolCalls.set(agentId, new Map());
-              }
-              const agentCalls = this.pendingToolCalls.get(agentId)!;
-              // Enforce size limit to prevent memory leak from rapid tool calls
-              if (agentCalls.size >= MAX_PENDING_TOOL_CALLS) {
-                // FIFO eviction: delete first (oldest) entry using Map insertion order
-                const firstKey = agentCalls.keys().next().value;
-                if (firstKey !== undefined) agentCalls.delete(firstKey);
-              }
-              agentCalls.set(content.id, {
-                toolName: content.name,
-                timestamp: Date.now(),
-              });
-            }
+          this.emit('subagent:tool_call', toolCall);
 
-            const toolCall: SubagentToolCall = {
+          // Update tool call count
+          const agentInfo = this.agentInfo.get(agentId);
+          if (agentInfo) {
+            agentInfo.toolCallCount++;
+          }
+        } else if (content.type === 'tool_result' && content.tool_use_id) {
+          this.emitToolResult(
+            { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
+            agentId,
+            sessionId,
+            entry.timestamp
+          );
+        } else if (content.type === 'text' && content.text) {
+          const text = content.text.trim();
+          if (text.length > 0) {
+            const message: SubagentMessage = {
               agentId,
               sessionId,
               timestamp: entry.timestamp,
-              tool: content.name,
-              input: this.getTruncatedInput(content.name, content.input || {}),
-              toolUseId: content.id,
-              fullInput: content.input || {},
+              role: 'assistant',
+              text: text.substring(0, MESSAGE_TEXT_LIMIT),
             };
-            this.emit('subagent:tool_call', toolCall);
-
-            // Update tool call count
-            const agentInfo = this.agentInfo.get(agentId);
-            if (agentInfo) {
-              agentInfo.toolCallCount++;
-            }
-          } 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 = {
-              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);
-          } else if (content.type === 'text' && content.text) {
-            const text = content.text.trim();
-            if (text.length > 0) {
-              const message: SubagentMessage = {
-                agentId,
-                sessionId,
-                timestamp: entry.timestamp,
-                role: 'assistant',
-                text: text.substring(0, MESSAGE_TEXT_LIMIT), // Limit text length
-              };
-              this.emit('subagent:message', message);
-            }
+            this.emit('subagent:message', message);
           }
         }
       }
-    } else if (entry.type === 'user' && entry.message?.content) {
-      // Handle both string and array content formats - also check for tool_result in user messages
-      if (typeof entry.message.content === 'string') {
-        const userText = entry.message.content.trim();
-        if (userText.length > 0 && userText.length < 500) {
-          const message: SubagentMessage = {
+    }
+  }
+
+  private _processUserContent(entry: SubagentTranscriptEntry, agentId: string, sessionId: string): void {
+    const messageContent = entry.message!.content;
+    if (typeof messageContent === 'string') {
+      const userText = messageContent.trim();
+      if (userText.length > 0 && userText.length < 500) {
+        const message: SubagentMessage = {
+          agentId,
+          sessionId,
+          timestamp: entry.timestamp,
+          role: 'user',
+          text: userText,
+        };
+        this.emit('subagent:message', message);
+      }
+    } else {
+      // Check for tool_result blocks in user messages (common pattern)
+      for (const content of messageContent) {
+        if (content.type === 'tool_result' && content.tool_use_id) {
+          this.emitToolResult(
+            { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
             agentId,
             sessionId,
-            timestamp: entry.timestamp,
-            role: 'user',
-            text: userText,
-          };
-          this.emit('subagent:message', message);
-        }
-      } else {
-        // 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 = {
+            entry.timestamp
+          );
+        } else if (content.type === 'text' && content.text) {
+          const userText = content.text.trim();
+          if (userText.length > 0 && userText.length < 500) {
+            const message: SubagentMessage = {
               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,
+              role: 'user',
+              text: userText,
             };
-            this.emit('subagent:tool_result', toolResult);
-          } else if (content.type === 'text' && content.text) {
-            const userText = content.text.trim();
-            if (userText.length > 0 && userText.length < 500) {
-              const message: SubagentMessage = {
-                agentId,
-                sessionId,
-                timestamp: entry.timestamp,
-                role: 'user',
-                text: userText,
-              };
-              this.emit('subagent:message', message);
-            }
+            this.emit('subagent:message', message);
           }
         }
       }

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)}`, {

src/tunnel-manager.ts

@@ -29,6 +29,7 @@ import {
   RESTART_DELAY_MS,
   FORCE_KILL_MS,
 } from './config/tunnel-config.js';
+import { getErrorMessage } from './types.js';
 
 // ========== Types ==========
 
@@ -164,7 +165,7 @@ export class TunnelManager extends EventEmitter {
         detached: false,
       });
     } catch (err) {
-      this.emit('error', `Failed to spawn cloudflared: ${err instanceof Error ? err.message : String(err)}`);
+      this.emit('error', `Failed to spawn cloudflared: ${getErrorMessage(err)}`);
       return;
     }
 

src/web/public/app.js

@@ -380,11 +380,8 @@ class CodemanApp {
     this.flickerFilterActive = false;
     this.flickerFilterTimeout = null;
 
-    // Render debouncing
-    this.renderSessionTabsTimeout = null;
-    this.renderRalphStatePanelTimeout = null;
-    this.renderTaskPanelTimeout = null;
-    this.renderMuxSessionsTimeout = null;
+    // Render debounce timers (managed by _debouncedCall)
+    this._debounceTimers = Object.create(null);
 
     // System stats polling
     this.systemStatsInterval = null;
@@ -435,6 +432,25 @@ class CodemanApp {
     return this._elemCache[id];
   }
 
+  // Clear a named timeout property: if (this[name]) { clearTimeout(this[name]); this[name] = null; }
+  _clearTimer(timerName) {
+    if (this[timerName]) {
+      clearTimeout(this[timerName]);
+      this[timerName] = null;
+    }
+  }
+
+  // Check if a selectSession generation is stale (a newer tab switch has started).
+  // If stale, cleans up buffer-loading state and returns true.
+  _isStaleSelect(selectGen) {
+    if (selectGen !== this._selectGeneration) {
+      if (this._isLoadingBuffer) this._finishBufferLoad();
+      this._restoringFlushedState = false;
+      return true;
+    }
+    return false;
+  }
+
   // Format token count: 1000k -> 1m, 1450k -> 1.45m, 500 -> 500
   formatTokens(count) {
     if (count >= 1000000) {
@@ -507,6 +523,9 @@ class CodemanApp {
     SwipeHandler.init();
     VoiceInput.init();
     KeyboardAccessoryBar.init();
+    // Apply keyboard bar mode from settings
+    const _kbSettings = this.loadAppSettingsFromStorage();
+    if (_kbSettings.extendedKeyboardBar) KeyboardAccessoryBar.setMode('extended');
     this.applyHeaderVisibilitySettings();
     this.applyTabWrapSettings();
     this.applyMonitorVisibility();
@@ -591,73 +610,43 @@ class CodemanApp {
   // ═══════════════════════════════════════════════════════════════
 
   setupEventListeners() {
+    // Keyboard shortcut lookup table — data-driven to avoid 12 separate if-blocks.
+    // Each entry: { key, altKey? (alternative key match), ctrl? (require Ctrl/Cmd),
+    //               shift? (require Shift), action }.
+    const SHORTCUTS = [
+      { key: '?', altKey: '/', ctrl: true, action: () => this.showHelp() },
+      { key: 'Enter', ctrl: true, action: () => this.quickStart() },
+      { key: 'w', ctrl: true, action: () => this.killActiveSession() },
+      { key: 'Tab', ctrl: true, action: () => this.nextSession() },
+      { key: 'k', ctrl: true, action: () => this.killAllSessions() },
+      { key: 'l', ctrl: true, action: () => this.clearTerminal() },
+      { key: 'R', ctrl: true, shift: true, action: () => this.restoreTerminalSize() },
+      { key: '=', altKey: '+', ctrl: true, action: () => this.increaseFontSize() },
+      { key: '-', ctrl: true, action: () => this.decreaseFontSize() },
+      { key: 'V', ctrl: true, shift: true, action: () => VoiceInput.toggle() },
+    ];
+
     // Use capture to handle before terminal
     document.addEventListener('keydown', (e) => {
       // Don't intercept keys during CJK IME composition
       if (e.isComposing || e.keyCode === 229) return;
 
-      // Escape - close panels and modals
+      // Escape - close panels and modals (different logic: no preventDefault, no return)
       if (e.key === 'Escape') {
         this.closeAllPanels();
         this.closeHelp();
       }
 
-      // Ctrl/Cmd + ? - help
-      if ((e.ctrlKey || e.metaKey) && (e.key === '?' || e.key === '/')) {
-        e.preventDefault();
-        this.showHelp();
-      }
-
-      // Ctrl/Cmd + Enter - quick start
-      if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
-        e.preventDefault();
-        this.quickStart();
-      }
-
-      // Ctrl/Cmd + W - close active session
-      if ((e.ctrlKey || e.metaKey) && e.key === 'w') {
-        e.preventDefault();
-        this.killActiveSession();
-      }
-
-      // Ctrl/Cmd + Tab - next session
-      if ((e.ctrlKey || e.metaKey) && e.key === 'Tab') {
-        e.preventDefault();
-        this.nextSession();
-      }
-
-      // Ctrl/Cmd + K - kill all
-      if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
-        e.preventDefault();
-        this.killAllSessions();
-      }
-
-      // Ctrl/Cmd + L - clear terminal
-      if ((e.ctrlKey || e.metaKey) && e.key === 'l') {
-        e.preventDefault();
-        this.clearTerminal();
-      }
-
-      // Ctrl/Cmd + Shift + R - restore terminal size (after mobile squeeze)
-      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'R') {
-        e.preventDefault();
-        this.restoreTerminalSize();
-      }
-
-      // Ctrl/Cmd + +/- - font size
-      if ((e.ctrlKey || e.metaKey) && (e.key === '=' || e.key === '+')) {
-        e.preventDefault();
-        this.increaseFontSize();
-      }
-      if ((e.ctrlKey || e.metaKey) && e.key === '-') {
-        e.preventDefault();
-        this.decreaseFontSize();
-      }
-
-      // Ctrl/Cmd + Shift + V - toggle voice input
-      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'V') {
-        e.preventDefault();
-        VoiceInput.toggle();
+      // Match against shortcut table
+      for (const s of SHORTCUTS) {
+        const keyMatch = e.key === s.key || (s.altKey && e.key === s.altKey);
+        const ctrlMatch = s.ctrl ? (e.ctrlKey || e.metaKey) : true;
+        const shiftMatch = s.shift ? e.shiftKey : !e.shiftKey;
+        if (keyMatch && ctrlMatch && shiftMatch) {
+          e.preventDefault();
+          s.action();
+          return;
+        }
       }
     }, true); // Use capture phase to handle before terminal
 
@@ -685,10 +674,7 @@ class CodemanApp {
     }
 
     // Clear any pending reconnect timeout to prevent duplicate connections
-    if (this.sseReconnectTimeout) {
-      clearTimeout(this.sseReconnectTimeout);
-      this.sseReconnectTimeout = null;
-    }
+    this._clearTimer('sseReconnectTimeout');
 
     // Clean up existing SSE listeners before creating new connection (prevents listener accumulation)
     if (this._sseListenerCleanup) {
@@ -745,9 +731,7 @@ class CodemanApp {
         this.eventSource = null;
       }
       // Clear any existing reconnect timeout before setting new one (prevents orphaned timeouts)
-      if (this.sseReconnectTimeout) {
-        clearTimeout(this.sseReconnectTimeout);
-      }
+      this._clearTimer('sseReconnectTimeout');
       // Exponential backoff: 200ms, 500ms, 1s, 2s, 4s, ... up to 30s
       // Fast first retry (200ms) for server-restart case (COM deploy),
       // then ramp up for real network issues.
@@ -889,6 +873,8 @@ class CodemanApp {
     // Server sends this after SSE backpressure clears — terminal data was dropped,
     // so reload the buffer to recover from any display corruption.
     if (!this.activeSessionId || !this.terminal) return;
+    // Skip if buffer load already in progress — avoids competing clear+rewrite cycles
+    if (this._isLoadingBuffer) return;
     try {
       const res = await fetch(`/api/sessions/${this.activeSessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
       const data = await res.json();
@@ -912,6 +898,12 @@ class CodemanApp {
 
   async _onSessionClearTerminal(data) {
     if (data.id === this.activeSessionId) {
+      // Skip if selectSession is already loading the buffer — clearTerminal arriving
+      // during buffer load would clear the terminal mid-write, causing visible flicker
+      // and a race between two concurrent chunkedTerminalWrite calls (especially on mobile
+      // where rAF is slower). selectSession will handle the final buffer state.
+      if (this._isLoadingBuffer) return;
+
       // Fetch buffer, clear terminal, write buffer, resize (no Ctrl+L needed)
       try {
         const res = await fetch(`/api/sessions/${data.id}/terminal`);
@@ -950,15 +942,7 @@ class CodemanApp {
     if (data.id === this.activeSessionId) {
       this.terminal.writeln(`\x1b[1;31m Error: ${data.error}\x1b[0m`);
     }
-    const session = this.sessions.get(data.id);
-    this.notificationManager?.notify({
-      urgency: 'critical',
-      category: 'session-error',
-      sessionId: data.id,
-      sessionName: session?.name || this.getShortId(data.id),
-      title: 'Session Error',
-      message: data.error || 'Unknown error',
-    });
+    this._notifySession(data.id, 'critical', 'session-error', 'Session Error', data.error || 'Unknown error');
   }
 
   _onSessionExit(data) {
@@ -971,14 +955,7 @@ class CodemanApp {
     }
     // Notify on unexpected exit (non-zero code)
     if (data.code && data.code !== 0) {
-      this.notificationManager?.notify({
-        urgency: 'critical',
-        category: 'session-crash',
-        sessionId: data.id,
-        sessionName: session?.name || this.getShortId(data.id),
-        title: 'Session Crashed',
-        message: `Exited with code ${data.code}`,
-      });
+      this._notifySession(data.id, 'critical', 'session-crash', 'Session Crashed', `Exited with code ${data.code}`);
     }
   }
 
@@ -995,15 +972,7 @@ class CodemanApp {
       const threshold = this.notificationManager?.preferences?.stuckThresholdMs || 600000;
       clearTimeout(this.idleTimers.get(data.id));
       this.idleTimers.set(data.id, setTimeout(() => {
-        const s = this.sessions.get(data.id);
-        this.notificationManager?.notify({
-          urgency: 'warning',
-          category: 'session-stuck',
-          sessionId: data.id,
-          sessionName: s?.name || this.getShortId(data.id),
-          title: 'Session Idle',
-          message: `Idle for ${Math.round(threshold / 60000)}+ minutes`,
-        });
+        this._notifySession(data.id, 'warning', 'session-stuck', 'Session Idle', `Idle for ${Math.round(threshold / 60000)}+ minutes`);
         this.idleTimers.delete(data.id);
       }, threshold));
     }
@@ -1034,15 +1003,7 @@ class CodemanApp {
       this.showToast(`Auto-cleared at ${data.tokens.toLocaleString()} tokens`, 'info');
       this.updateRespawnTokens(0);
     }
-    const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'auto-clear',
-      sessionId: data.sessionId,
-      sessionName: session?.name || this.getShortId(data.sessionId),
-      title: 'Auto-Cleared',
-      message: `Context reset at ${(data.tokens || 0).toLocaleString()} tokens`,
-    });
+    this._notifySession(data.sessionId, 'info', 'auto-clear', 'Auto-Cleared', `Context reset at ${(data.tokens || 0).toLocaleString()} tokens`);
   }
 
   _onSessionCliInfo(data) {
@@ -1163,10 +1124,7 @@ class CodemanApp {
 
   /** Close the active WebSocket connection (if any). */
   _disconnectWs() {
-    if (this._wsReconnectTimer) {
-      clearTimeout(this._wsReconnectTimer);
-      this._wsReconnectTimer = null;
-    }
+    this._clearTimer('_wsReconnectTimer');
     this._wsReconnectAttempts = 0;
     if (this._ws) {
       this._ws.onclose = null; // Prevent re-entrant cleanup
@@ -1302,38 +1260,22 @@ class CodemanApp {
     });
   }
 
-  handleInit(data) {
-    // Clear the init fallback timer since we got data
-    if (this._initFallbackTimer) {
-      clearTimeout(this._initFallbackTimer);
-      this._initFallbackTimer = null;
-    }
-    const gen = ++this._initGeneration;
-
-    // CJK input form: show/hide based on server env INPUT_CJK_FORM=ON
+  /** Show/hide the CJK input textarea based on user setting or server override */
+  _updateCjkInputState() {
     const cjkEl = document.getElementById('cjkInput');
-    if (cjkEl) {
-      cjkEl.style.display = data.inputCjkForm ? 'block' : 'none';
-      if (!data.inputCjkForm) window.cjkActive = false;
-    }
-
-    // Update version displays (header and toolbar)
-    if (data.version) {
-      const versionEl = this.$('versionDisplay');
-      const headerVersionEl = this.$('headerVersion');
-      if (versionEl) {
-        versionEl.textContent = `v${data.version}`;
-        versionEl.title = `Codeman v${data.version}`;
-      }
-      if (headerVersionEl) {
-        headerVersionEl.textContent = `v${data.version}`;
-        headerVersionEl.title = `Codeman v${data.version}`;
-      }
-    }
-
-    // Stop any active voice recording on reconnect
-    VoiceInput.cleanup();
+    if (!cjkEl) return;
+    const settings = this.loadAppSettingsFromStorage();
+    const showCjk = this._serverCjkOverride || settings.cjkInputEnabled || false;
+    cjkEl.style.display = showCjk ? 'block' : 'none';
+    if (!showCjk) window.cjkActive = false;
+  }
 
+  /**
+   * Reset all app state maps, timers, and handlers to a clean baseline.
+   * Called by handleInit() on SSE reconnect / page reload to prevent
+   * memory leaks and stale data.
+   */
+  _resetAllAppState() {
     this.sessions.clear();
     this.ralphStates.clear();
     this.terminalBuffers.clear();
@@ -1347,17 +1289,11 @@ class CodemanApp {
     }
     this.idleTimers.clear();
     // Clear flicker filter state
-    if (this.flickerFilterTimeout) {
-      clearTimeout(this.flickerFilterTimeout);
-      this.flickerFilterTimeout = null;
-    }
+    this._clearTimer('flickerFilterTimeout');
     this.flickerFilterBuffer = '';
     this.flickerFilterActive = false;
     // Clear pending terminal writes
-    if (this.syncWaitTimeout) {
-      clearTimeout(this.syncWaitTimeout);
-      this.syncWaitTimeout = null;
-    }
+    this._clearTimer('syncWaitTimeout');
     this.pendingWrites = [];
     this.writeFrameScheduled = false;
     this._isLoadingBuffer = false;
@@ -1416,6 +1352,36 @@ class CodemanApp {
       clearInterval(this.runSummaryAutoRefreshTimer);
       this.runSummaryAutoRefreshTimer = null;
     }
+  }
+
+  handleInit(data) {
+    // Clear the init fallback timer since we got data
+    this._clearTimer('_initFallbackTimer');
+    const gen = ++this._initGeneration;
+
+    // CJK input form: controlled by user setting (with server env as override)
+    this._serverCjkOverride = data.inputCjkForm || false;
+    this._updateCjkInputState();
+
+    // Update version displays (header and toolbar)
+    if (data.version) {
+      const versionEl = this.$('versionDisplay');
+      const headerVersionEl = this.$('headerVersion');
+      if (versionEl) {
+        versionEl.textContent = `v${data.version}`;
+        versionEl.title = `Codeman v${data.version}`;
+      }
+      if (headerVersionEl) {
+        headerVersionEl.textContent = `v${data.version}`;
+        headerVersionEl.title = `Codeman v${data.version}`;
+      }
+    }
+
+    // Stop any active voice recording on reconnect
+    VoiceInput.cleanup();
+
+    this._resetAllAppState();
+
     data.sessions.forEach(s => {
       this.sessions.set(s.id, s);
       // Load ralph state from session data (only if not explicitly closed by user)
@@ -1543,18 +1509,27 @@ class CodemanApp {
     }
   }
 
+  // ═══════════════════════════════════════════════════════════════
+  // Debounce Utility
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Debounce a method call using a named timer key. */
+  _debouncedCall(timerKey, fn, delayMs = 100) {
+    if (this._debounceTimers[timerKey]) {
+      clearTimeout(this._debounceTimers[timerKey]);
+    }
+    this._debounceTimers[timerKey] = setTimeout(() => {
+      this._debounceTimers[timerKey] = null;
+      fn.call(this);
+    }, delayMs);
+  }
+
   // ═══════════════════════════════════════════════════════════════
   // Session Tabs
   // ═══════════════════════════════════════════════════════════════
 
   renderSessionTabs() {
-    // Debounce renders at 100ms to prevent excessive DOM updates
-    if (this.renderSessionTabsTimeout) {
-      clearTimeout(this.renderSessionTabsTimeout);
-    }
-    this.renderSessionTabsTimeout = setTimeout(() => {
-      this._renderSessionTabsImmediate();
-    }, 100);
+    this._debouncedCall('sessionTabs', this._renderSessionTabsImmediate);
   }
 
   /** Toggle .active class on tabs immediately (no debounce). Used by selectSession(). */
@@ -1980,17 +1955,25 @@ class CodemanApp {
     return this.getShortId(session.id);
   }
 
-  async selectSession(sessionId) {
-    if (this.activeSessionId === sessionId) return;
-    const _selStart = performance.now();
-    const _selName = this.sessions.get(sessionId)?.name || sessionId.slice(0,8);
-    _crashDiag.log(`SELECT: ${_selName}`);
-    console.log(`[CRASH-DIAG] selectSession START: ${sessionId.slice(0,8)}`);
-
-    const selectGen = ++this._selectGeneration;
-
-    if (selectGen !== this._selectGeneration) return; // newer tab switch won
+  _notifySession(sessionId, urgency, category, title, message) {
+    const session = this.sessions.get(sessionId);
+    this.notificationManager?.notify({
+      urgency,
+      category,
+      sessionId,
+      sessionName: session?.name || this.getShortId(sessionId),
+      title,
+      message,
+    });
+  }
 
+  /**
+   * Clean up state from the previous session before switching tabs.
+   * Handles: WebSocket teardown, CJK clear, flicker filter, tab completion,
+   * terminal write queue, IME composition, and local echo flush.
+   * @param {string} newSessionId - The session being switched TO.
+   */
+  _cleanupPreviousSession(newSessionId) {
     // Close WebSocket for previous session (new one opens after buffer load)
     this._disconnectWs();
 
@@ -1999,10 +1982,7 @@ class CodemanApp {
     if (cjkEl) cjkEl.value = '';
 
     // Clean up flicker filter state when switching sessions
-    if (this.flickerFilterTimeout) {
-      clearTimeout(this.flickerFilterTimeout);
-      this.flickerFilterTimeout = null;
-    }
+    this._clearTimer('flickerFilterTimeout');
     this.flickerFilterBuffer = '';
     this.flickerFilterActive = false;
 
@@ -2010,14 +1990,11 @@ class CodemanApp {
     this._tabCompletionSessionId = null;
     this._tabCompletionRetries = 0;
     this._tabCompletionBaseText = null;
-    if (this._tabCompletionFallback) { clearTimeout(this._tabCompletionFallback); this._tabCompletionFallback = null; }
-    if (this._clientDropRecoveryTimer) { clearTimeout(this._clientDropRecoveryTimer); this._clientDropRecoveryTimer = null; }
+    this._clearTimer('_tabCompletionFallback');
+    this._clearTimer('_clientDropRecoveryTimer');
 
     // Clean up pending terminal writes to prevent old session data from appearing in new session
-    if (this.syncWaitTimeout) {
-      clearTimeout(this.syncWaitTimeout);
-      this.syncWaitTimeout = null;
-    }
+    this._clearTimer('syncWaitTimeout');
     this.pendingWrites = [];
     this.writeFrameScheduled = false;
     this._isLoadingBuffer = false;
@@ -2067,9 +2044,29 @@ class CodemanApp {
     // Only sessions with prior flushed text (from tab-switch-away) need detection.
     // After the user's first Enter, clear() resets _bufferDetectDone = false,
     // re-enabling detection for tab completion and other legitimate cases.
-    if (this._localEchoOverlay && !this._flushedOffsets?.has(sessionId)) {
+    if (this._localEchoOverlay && !this._flushedOffsets?.has(newSessionId)) {
       this._localEchoOverlay.suppressBufferDetection();
     }
+  }
+
+  async selectSession(sessionId) {
+    if (this.activeSessionId === sessionId) return;
+    // Focus terminal SYNCHRONOUSLY before any await — iOS Safari only honors
+    // programmatic focus() within the user-gesture call stack (e.g. tab click).
+    // After the first await the gesture context is lost and focus() is silently
+    // ignored, leaving the keyboard unable to send input to the terminal.
+    if (this.terminal) this.terminal.focus();
+
+    const _selStart = performance.now();
+    const _selName = this.sessions.get(sessionId)?.name || sessionId.slice(0,8);
+    _crashDiag.log(`SELECT: ${_selName}`);
+    console.log(`[CRASH-DIAG] selectSession START: ${sessionId.slice(0,8)}`);
+
+    const selectGen = ++this._selectGeneration;
+
+    if (selectGen !== this._selectGeneration) return; // newer tab switch won
+
+    this._cleanupPreviousSession(sessionId);
     this.activeSessionId = sessionId;
     try { localStorage.setItem('codeman-active-session', sessionId); } catch {}
     this.hideWelcome();
@@ -2111,8 +2108,9 @@ class CodemanApp {
 
     // Track working directory for path normalization in Project Insights
     this.currentSessionWorkingDir = session?.workingDir || null;
-    if (session && session.pid === null && session.status === 'idle') {
-      // This is a restored session - attach to the existing screen/shell
+    if (session && session.pid === null && !session._ended) {
+      // Session has no PTY attached — either restored after server restart
+      // or detached for some other reason. Re-attach regardless of status.
       try {
         const endpoint = session.mode === 'shell'
           ? `/api/sessions/${sessionId}/shell`
@@ -2147,23 +2145,31 @@ class CodemanApp {
       // canvas may be at stale dimensions — content would render at wrong width.
       if (this.fitAddon) this.fitAddon.fit();
 
-      // Instant cache restore — show previous buffer via chunked write to avoid WebGL GPU stalls.
-      // Direct terminal.write() of large cached buffers (256KB+) can block the main thread
-      // for 5+ seconds while the WebGL renderer processes ReadPixels synchronously.
+      // Instant cache restore for IDLE sessions only.
+      // For busy sessions, the cache is always stale — writing it first causes a
+      // jarring double-render: stale content appears, then the terminal flashes
+      // blank and rewrites with fresh data. Skip the cache and write the fresh
+      // buffer once for a single clean transition.
       const cachedBuffer = this.terminalBufferCache.get(sessionId);
-      if (cachedBuffer) {
+      const sessionIsBusy = session && (session.status === 'busy' || session.status === 'working');
+      if (cachedBuffer && !sessionIsBusy) {
         _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
         this.terminal.clear();
         this.terminal.reset();
         await this.chunkedTerminalWrite(cachedBuffer);
-        if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
+        if (this._isStaleSelect(selectGen)) return;
         this.terminal.scrollToBottom();
         _crashDiag.log('CACHE_DONE');
+      } else if (sessionIsBusy) {
+        // Clear stale content immediately — fresh buffer is being fetched
+        this.terminal.clear();
+        this.terminal.reset();
+        _crashDiag.log('CACHE_SKIP_BUSY');
       }
 
       _crashDiag.log('FETCH_START');
       const res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
-      if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
+      if (this._isStaleSelect(selectGen)) return;
       const data = await res.json();
       _crashDiag.log(`FETCH_DONE: ${data.terminalBuffer ? (data.terminalBuffer.length/1024).toFixed(0) + 'KB' : 'empty'} truncated=${data.truncated}`);
 
@@ -2182,7 +2188,7 @@ class CodemanApp {
           }
           // Use chunked write for large buffers to avoid UI jank
           await this.chunkedTerminalWrite(data.terminalBuffer);
-          if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
+          if (this._isStaleSelect(selectGen)) return;
           // Ensure terminal is scrolled to bottom after buffer load
           this.terminal.scrollToBottom();
         }
@@ -2200,9 +2206,9 @@ class CodemanApp {
         this.terminal.reset();
       }
 
-      // Buffer load complete — unblock live SSE writes and flush any queued events.
-      // chunkedTerminalWrite calls _finishBufferLoad internally, but if we skipped
-      // the chunked write (small buffer, cache hit, or empty), we must call it here.
+      // Buffer load complete — unblock live SSE writes (queued events are discarded
+      // to prevent duplicate content). chunkedTerminalWrite calls _finishBufferLoad
+      // internally, but if we skipped the write (cache hit or empty), call it here.
       if (this._isLoadingBuffer) {
         this._finishBufferLoad();
       }
@@ -2226,9 +2232,19 @@ class CodemanApp {
         });
       }
 
-      // Fire-and-forget resize — don't await to avoid blocking UI.
-      // The resize triggers an Ink redraw in Claude which streams back via SSE.
-      this.sendResize(sessionId);
+      // Fire-and-forget resize + Ctrl+L to force Ink redraw.
+      // Tailed buffers accumulate stale CUP-positioned Ink frames that overlap
+      // in the viewport (e.g. duplicate "bypass permissions" bars). Ctrl+L
+      // triggers a full Ink redraw which overwrites all stale frame content.
+      // sendResize may be a no-op if dimensions match, so Ctrl+L is essential.
+      this.sendResize(sessionId).then(() => {
+        if (selectGen !== this._selectGeneration) return;
+        fetch(`/api/sessions/${sessionId}/input`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ input: '\x0c' })
+        }).catch(() => {});
+      });
 
       // Defer secondary panel updates so they don't block the main thread
       // after terminal content is already visible.
@@ -2579,9 +2595,7 @@ class CodemanApp {
   updateTokens() {
     // Debounce at 200ms — token display is non-critical and shouldn't
     // compete with input handling on the main thread
-    if (this._updateTokensTimeout) {
-      clearTimeout(this._updateTokensTimeout);
-    }
+    this._clearTimer('_updateTokensTimeout');
     this._updateTokensTimeout = setTimeout(() => {
       this._updateTokensTimeout = null;
       this._updateTokensImmediate();

src/web/public/constants.js

@@ -291,6 +291,12 @@ const SSE_EVENTS = {
   ORCHESTRATOR_TASK_FAILED: 'orchestrator:taskFailed',
   ORCHESTRATOR_COMPLETED: 'orchestrator:completed',
   ORCHESTRATOR_ERROR: 'orchestrator:error',
+
+  // Cases
+  CASE_CREATED: 'case:created',
+  CASE_LINKED: 'case:linked',
+  CASE_DELETED: 'case:deleted',
+  CASE_ORDER_CHANGED: 'case:order-changed',
 };
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/index.html

@@ -384,6 +384,11 @@
                 <span>Agent Teams</span>
               </label>
               <span class="form-hint">Enable experimental Agent Teams for new sessions in this case</span>
+              <label class="checkbox-inline" style="margin-top: 6px;">
+                <input type="checkbox" id="caseOpusContext1m" onchange="app.onCaseSettingChanged()">
+                <span>1M Opus Context</span>
+              </label>
+              <span class="form-hint">Use 1M token context window for new sessions</span>
             </div>
           </div>
           <!-- Mobile-only case button + gear -->
@@ -408,6 +413,11 @@
               <span>Agent Teams</span>
             </label>
             <span class="form-hint">Enable Agent Teams for new sessions</span>
+            <label class="checkbox-inline" style="margin-top: 6px;">
+              <input type="checkbox" id="caseOpusContext1mMobile" onchange="app.onCaseSettingChangedMobile()">
+              <span>1M Opus Context</span>
+            </label>
+            <span class="form-hint">Use 1M token context window</span>
           </div>
         </div>
 
@@ -871,6 +881,27 @@
                   <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>
+
+              <div class="settings-item settings-item-multiline" title="Show additional buttons (Tab, Shift+Tab, Ctrl+O, Esc, Alt+Enter, left/right arrows) in the mobile keyboard accessory bar.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Extended Keyboard Bar</span>
+                  <span class="settings-item-desc">Extra keys: Tab, Esc, arrows, Ctrl+O</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsExtendedKeyboardBar">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Header Displays Section -->
               <div class="settings-section-header">Header Displays</div>
@@ -1036,6 +1067,14 @@
               </label>
               <span class="form-hint">Enable experimental Agent Teams for all new Claude sessions (disabled by default)</span>
             </div>
+            <div class="form-row form-row-switch">
+              <label>1M Opus Context</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsOpusContext1m">
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Use 1M token context window (model: opus[1m]) for all new sessions</span>
+            </div>
             <!-- Nice Priority Section -->
             <div class="form-section-header">Nice Priority</div>
             <div class="form-row form-row-switch">
@@ -1057,6 +1096,7 @@
             <div class="form-row">
               <label>Default Model</label>
               <select id="appSettingsDefaultModel" class="form-select">
+                <option value="">Default (CLI default)</option>
                 <option value="opus">Opus (Most capable)</option>
                 <option value="sonnet">Sonnet (Balanced)</option>
                 <option value="haiku">Haiku (Fast & cheap)</option>
@@ -1331,6 +1371,7 @@
         <div class="modal-tabs">
           <button class="modal-tab-btn active" data-tab="case-create">Create New</button>
           <button class="modal-tab-btn" data-tab="case-link">Link Existing</button>
+          <button class="modal-tab-btn" data-tab="case-manage">Manage</button>
         </div>
         <div class="modal-body">
           <!-- Create New Tab -->
@@ -1358,6 +1399,13 @@
               <span class="form-hint">Absolute path to an existing project folder, e.g. /home/you/my-project</span>
             </div>
           </div>
+          <!-- Manage Tab -->
+          <div class="modal-tab-content hidden" id="case-manage">
+            <div class="case-manage-list" id="caseManageList">
+              <!-- Populated by JS -->
+            </div>
+            <span class="form-hint" style="margin-top: 8px; display: block;">Use arrows to reorder. Changes are saved automatically.</span>
+          </div>
         </div>
         <div class="form-actions">
           <button class="btn-toolbar" onclick="app.closeCreateCaseModal()">Cancel</button>

src/web/public/input-cjk.js

@@ -3,10 +3,36 @@
  *
  * 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 15 — loaded after keyboard-accessory.js, before app.js
@@ -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

@@ -33,16 +33,10 @@
  */
 const KeyboardAccessoryBar = {
   element: null,
+  _mode: 'simple', // 'simple' or 'extended'
 
-  /** Create and inject the accessory bar */
-  init() {
-    // Only on mobile
-    if (!MobileDetection.isTouchDevice()) return;
-
-    // Create accessory bar element
-    this.element = document.createElement('div');
-    this.element.className = 'keyboard-accessory-bar';
-    this.element.innerHTML = `
+  /** HTML for simple mode: arrows, commands, paste, dismiss */
+  _simpleButtons: `
       <button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
           <path d="M5 15l7-7 7 7"/>
@@ -66,8 +60,59 @@ const KeyboardAccessoryBar = {
         <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
           <path d="M19 9l-7 7-7-7"/>
         </svg>
+      </button>`,
+
+  /** HTML for extended mode: all keys including arrows, Tab, Esc, etc. */
+  _extendedButtons: `
+      <button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
+          <path d="M5 15l7-7 7 7"/>
+        </svg>
       </button>
-    `;
+      <button class="accessory-btn accessory-btn-arrow" data-action="scroll-down" title="Arrow down">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
+          <path d="M19 9l-7 7-7-7"/>
+        </svg>
+      </button>
+      <button class="accessory-btn accessory-btn-arrow" data-action="arrow-left" title="Arrow left">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
+          <path d="M15 19l-7-7 7-7"/>
+        </svg>
+      </button>
+      <button class="accessory-btn accessory-btn-arrow" data-action="arrow-right" title="Arrow right">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
+          <path d="M9 5l7 7-7 7"/>
+        </svg>
+      </button>
+      <button class="accessory-btn" data-action="paste" title="Paste from clipboard">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>
+          <rect x="8" y="2" width="8" height="4" rx="1" ry="1"/>
+        </svg>
+      </button>
+      <button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
+      <button class="accessory-btn" data-action="shift-tab" title="Shift+Tab">⇧Tab</button>
+      <button class="accessory-btn" data-action="ctrl-o" title="Ctrl+O">⌃O</button>
+      <button class="accessory-btn" data-action="opt-enter" title="Option+Enter (newline)">⌥Enter</button>
+      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
+      <button class="accessory-btn" data-action="init" title="/init">/init</button>
+      <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
+      <button class="accessory-btn" data-action="compact" title="/compact">/compact</button>
+      <button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
+        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
+          <path d="M19 9l-7 7-7-7"/>
+        </svg>
+      </button>`,
+
+  /** Create and inject the accessory bar */
+  init() {
+    // Only on mobile
+    if (!MobileDetection.isTouchDevice()) return;
+
+    // Create accessory bar element
+    this.element = document.createElement('div');
+    this.element.className = 'keyboard-accessory-bar';
+    this.element.innerHTML = this._simpleButtons;
 
     // Add click handlers — preventDefault stops event from reaching terminal
     this.element.addEventListener('click', (e) => {
@@ -80,7 +125,8 @@ const KeyboardAccessoryBar = {
       this.handleAction(action, btn);
 
       // Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
-      if ((action === 'scroll-up' || action === 'scroll-down') ||
+      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc']);
+      if (refocusActions.has(action) ||
           ((action === 'clear' || action === 'compact') && this._confirmAction)) {
         if (typeof app !== 'undefined' && app.terminal) {
           app.terminal.focus();
@@ -95,6 +141,14 @@ const KeyboardAccessoryBar = {
     }
   },
 
+  /** Switch between 'simple' and 'extended' button layouts */
+  setMode(mode) {
+    if (mode === this._mode || !this.element) return;
+    this._mode = mode;
+    this.clearConfirm();
+    this.element.innerHTML = mode === 'extended' ? this._extendedButtons : this._simpleButtons;
+  },
+
   _confirmTimer: null,
   _confirmAction: null,
 
@@ -109,6 +163,27 @@ const KeyboardAccessoryBar = {
       case 'scroll-down':
         this.sendKey('\x1b[B');
         break;
+      case 'arrow-left':
+        this.sendKey('\x1b[D');
+        break;
+      case 'arrow-right':
+        this.sendKey('\x1b[C');
+        break;
+      case 'esc':
+        this.sendKey('\x1b');
+        break;
+      case 'opt-enter':
+        this.sendKey('\x1b\r');
+        break;
+      case 'tab':
+        this.sendKey('\t');
+        break;
+      case 'shift-tab':
+        this.sendKey('\x1b[Z');
+        break;
+      case 'ctrl-o':
+        this.sendKey('\x0f');
+        break;
       case 'init':
         this.sendCommand('/init');
         break;

src/web/public/mobile.css

@@ -65,13 +65,14 @@ html.mobile-init .file-browser-panel {
     max-height: calc(48px + var(--safe-area-top));
   }
 
-  /* Add top margin to main content to account for fixed header */
-  .main {
-    margin-top: 54px;
+  /* Push ALL content below fixed header (not just .main) so banners
+     (respawn, timer, orchestrator) between header and main are visible */
+  .app {
+    padding-top: 54px;
   }
 
-  .ios-device .main {
-    margin-top: calc(54px + var(--safe-area-top));
+  .ios-device .app {
+    padding-top: calc(54px + var(--safe-area-top));
   }
 
   /* Font controls - smaller on tablet, visibility controlled by JS */
@@ -235,6 +236,37 @@ html.mobile-init .file-browser-panel {
     font-size: 0.7rem;
   }
 
+  /* ---- Respawn Banner: Tablet Optimizations ---- */
+
+  .respawn-banner {
+    padding: 0.25rem 0.5rem;
+    padding-left: calc(0.5rem + var(--safe-area-left));
+    padding-right: calc(0.5rem + var(--safe-area-right));
+    font-size: 0.65rem;
+  }
+
+  .respawn-compact-layout {
+    gap: 0.75rem;
+  }
+
+  .respawn-status-row1 {
+    gap: 0.4rem;
+  }
+
+  .respawn-action-log {
+    max-height: 2.6em;
+    font-size: 0.6rem;
+  }
+
+  .respawn-countdown-timer {
+    font-size: 0.55rem;
+  }
+
+  /* Respawn timer bar — slimmer on tablet */
+  .respawn-timer-bar {
+    width: 24px;
+  }
+
   /* Show desktop voice button on tablet (hidden by max-width:1023px in styles.css,
      mobile .btn-voice-mobile only shows at <430px) */
   .toolbar-center .btn-toolbar.btn-voice {
@@ -327,18 +359,22 @@ 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,
-     and bottom padding for the fixed toolbar (40px) so terminal
-     content doesn't extend behind it. JS overrides paddingBottom
+  /* Push ALL content below fixed header (not just .main) so banners
+     (respawn, timer, orchestrator) between header and main are visible.
+     Bottom padding for the fixed toolbar (40px) so terminal content
+     doesn't extend behind it. JS overrides paddingBottom on .main
      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));
+  .app {
+    padding-top: 42px;
   }
 
-  .ios-device .main {
-    margin-top: calc(42px + var(--safe-area-top));
+  .ios-device .app {
+    padding-top: calc(42px + var(--safe-area-top));
+  }
+
+  .main {
+    padding-bottom: calc(40px + var(--safe-area-bottom));
   }
 
   /* iOS Safari: toolbar is pushed up by (100vh - --app-height) to clear the
@@ -850,7 +886,8 @@ html.mobile-init .file-browser-panel {
     padding-right: calc(8px + var(--safe-area-right));
     gap: 8px;
     align-items: center;
-    justify-content: center;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
     z-index: 51;
     transition: transform 0.15s ease-out;
     will-change: transform;
@@ -860,10 +897,16 @@ html.mobile-init .file-browser-panel {
     display: flex;
   }
 
+  /* 隐藏滚动条但保留滑动能力 */
+  .keyboard-accessory-bar::-webkit-scrollbar {
+    display: none;
+  }
+
   .accessory-btn {
     display: inline-flex;
     align-items: center;
     justify-content: center;
+    flex-shrink: 0;
     gap: 4px;
     padding: 6px 12px;
     background: #2a2a2a;
@@ -894,31 +937,33 @@ html.mobile-init .file-browser-panel {
 
   .accessory-btn-arrow {
     padding: 6px 10px;
-    background: #1e3a5f;
-    border-color: rgba(59, 130, 246, 0.3);
-    color: #93c5fd;
+    background: #2563eb;
+    border-color: rgba(59, 130, 246, 0.5);
+    color: #fff;
   }
 
   .accessory-btn-arrow:active {
-    background: #2563eb;
+    background: #1d4ed8;
   }
 
   .accessory-btn-dismiss {
-    padding: 8px 14px;
-    background: #2a2a2a;
-    border: 1.5px solid rgba(255, 255, 255, 0.25);
-    border-radius: 6px;
-    color: #e5e5e5;
+    margin-left: auto;
+    flex: 1 1 0;
+    max-width: 100px;
+    padding: 10px 8px;
+    background: #2563eb;
+    border-color: rgba(59, 130, 246, 0.5);
+    color: #fff;
+    font-weight: 600;
   }
 
   .accessory-btn-dismiss svg {
     width: 22px;
     height: 22px;
-    stroke-width: 3;
   }
 
   .accessory-btn-dismiss:active {
-    background: #3a3a3a;
+    background: #1d4ed8;
   }
 
   /* Voice preview — positioned above accessory bar on mobile */
@@ -950,9 +995,9 @@ html.mobile-init .file-browser-panel {
     background: rgba(0, 0, 0, 0.6);
     z-index: 10000;
     display: flex;
-    align-items: flex-end;
+    align-items: flex-start;
     justify-content: center;
-    padding-bottom: env(safe-area-inset-bottom, 12px);
+    padding-top: 15vh;
   }
 
   .paste-dialog {
@@ -962,13 +1007,12 @@ html.mobile-init .file-browser-panel {
     padding: 12px;
     width: calc(100% - 24px);
     max-width: 400px;
-    margin-bottom: 8px;
   }
 
   .paste-textarea {
     width: 100%;
-    min-height: 60px;
-    max-height: 120px;
+    min-height: 80px;
+    max-height: 200px;
     background: var(--bg-primary, #0d0d14);
     color: var(--text-primary, #e0e0e0);
     border: 1px solid var(--border-color, #444);
@@ -1147,6 +1191,7 @@ html.mobile-init .file-browser-panel {
 
   /* Compact welcome overlay for mobile */
   .welcome-content {
+    max-width: calc(100vw - 1.5rem);
     padding: 1rem 0.75rem;
   }
 
@@ -1212,31 +1257,70 @@ html.mobile-init .file-browser-panel {
   /* ---- Respawn Banner: Mobile Optimizations ---- */
 
   .respawn-banner {
-    padding: 0.4rem 0.5rem;
+    padding: 0.3rem 0.5rem;
     padding-left: calc(0.5rem + var(--safe-area-left));
     padding-right: calc(0.5rem + var(--safe-area-right));
-    font-size: 0.7rem;
+    font-size: 0.65rem;
   }
 
   /* Stack banner vertically on mobile — status on top, action log below */
   .respawn-compact-layout {
     flex-direction: column;
-    gap: 0.25rem;
+    gap: 0.15rem;
   }
 
   /* Let status column shrink to fit */
   .respawn-status-col {
     flex-shrink: 1;
     min-width: 0;
+    gap: 0.1rem;
   }
 
-  /* Wrap status row items — tokens/timer may go to second line */
+  /* Row1: wrap allowed, key info prioritized via order */
   .respawn-status-row1 {
     flex-wrap: wrap;
-    gap: 0.35rem;
+    gap: 0.25rem;
+    row-gap: 0.1rem;
   }
 
-  /* Stop button — 44px touch target */
+  /* State label — smaller on phone, stays first */
+  .respawn-state {
+    font-size: 0.6rem;
+    padding: 0.05rem 0.3rem;
+  }
+
+  /* Confidence badge — compact */
+  .respawn-banner .detection-confidence {
+    font-size: 0.5rem;
+    padding: 0.02rem 0.2rem;
+  }
+
+  /* Cycles — compact */
+  .respawn-cycles {
+    font-size: 0.55rem;
+  }
+
+  /* Run timer — compact */
+  .respawn-timer {
+    font-size: 0.55rem;
+    padding: 0 0.25rem;
+  }
+
+  /* Tokens — compact, truncate if long */
+  .respawn-tokens {
+    font-size: 0.55rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    max-width: 120px;
+  }
+
+  /* Spinner icon — smaller on phone */
+  .respawn-indicator {
+    font-size: 0.65rem;
+  }
+
+  /* Stop button — 36px touch target, pushed right */
   .respawn-banner .btn-icon-only {
     min-width: 36px;
     min-height: 36px;
@@ -1246,26 +1330,50 @@ html.mobile-init .file-browser-panel {
     justify-content: center;
     margin-left: auto;
     border-radius: 6px;
+    flex-shrink: 0;
   }
 
-  /* Action log — horizontal strip below status, border on top instead of left */
-  .respawn-action-log {
-    border-left: none;
-    border-top: 1px solid rgba(34, 197, 94, 0.2);
-    padding-left: 0;
-    padding-top: 0.25rem;
-    max-height: 2em;
-    font-size: 0.6rem;
+  /* Row2: tighter spacing, smaller text */
+  .respawn-status-row2 {
+    font-size: 0.55rem;
+    gap: 0.3rem;
+    min-height: 0;
+    flex-wrap: wrap;
   }
 
-  /* Countdown timers — tighter on mobile */
+  /* Detection badges — smaller on phone */
+  .respawn-banner .detection-hook,
+  .respawn-banner .detection-ai-check,
+  .respawn-banner .detection-status {
+    font-size: 0.55rem;
+    padding: 0.02rem 0.2rem;
+  }
+
+  /* Countdown timers — inline, no progress bars */
   .respawn-countdown-timers {
     gap: 0.2rem;
   }
 
   .respawn-countdown-timer {
+    font-size: 0.5rem;
+    padding: 0.02rem 0.2rem;
+    gap: 0.15rem;
+  }
+
+  /* Hide progress bars on phone — values are enough */
+  .respawn-countdown-timer .respawn-timer-bar {
+    display: none;
+  }
+
+  /* Action log — single-line strip below status, show latest entry only */
+  .respawn-action-log {
+    border-left: none;
+    border-top: 1px solid rgba(34, 197, 94, 0.15);
+    padding-left: 0;
+    padding-top: 0.15rem;
+    max-height: 1.4em;
     font-size: 0.55rem;
-    padding: 0.05rem 0.25rem;
+    overflow: hidden;
   }
 
   /* ---- Session Options Modal: Respawn Tab Mobile Optimizations ---- */
@@ -1291,28 +1399,27 @@ html.mobile-init .file-browser-panel {
     border-radius: 5px;
   }
 
-  /* Duration preset buttons — single row, all 7 items */
+  /* Duration preset buttons — grid layout, 4 columns for even spacing */
   .duration-presets {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.25rem;
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 0.2rem;
   }
 
   .duration-preset-btn {
-    min-height: 28px;
-    padding: 0.2rem 0.4rem;
+    min-height: 32px;
+    padding: 0.2rem 0.25rem;
     font-size: 0.65rem;
     border-radius: 5px;
     text-align: center;
-    flex: 1 1 auto;
-    min-width: 0;
   }
 
-  /* Custom duration — inline with other presets */
+  /* Custom duration — spans full row below */
   .duration-custom {
-    flex-wrap: wrap;
+    grid-column: 1 / -1;
+    display: flex;
     gap: 0.25rem;
-    flex: 1 1 100%;
+    align-items: center;
   }
 
   .duration-custom .duration-preset-btn {
@@ -1330,24 +1437,23 @@ html.mobile-init .file-browser-panel {
     font-size: 16px; /* Prevents iOS zoom */
   }
 
-  /* Preset selector row — compact inline */
+  /* Preset selector row — full-width dropdown, buttons below */
   .preset-selector {
-    display: flex;
-    flex-wrap: wrap;
+    display: grid;
+    grid-template-columns: 1fr 1fr;
     gap: 0.25rem;
   }
 
   .preset-selector select {
-    width: 100%;
-    min-height: 28px;
+    grid-column: 1 / -1;
+    min-height: 32px;
     font-size: 16px; /* Prevents iOS zoom */
     border-radius: 5px;
     padding: 0.2rem 0.4rem;
   }
 
   .preset-selector .btn {
-    flex: 1;
-    min-height: 28px;
+    min-height: 32px;
     font-size: 0.65rem;
     border-radius: 5px;
     padding: 0.2rem 0.4rem;
@@ -1970,7 +2076,8 @@ html.mobile-init .file-browser-panel {
   padding: 6px 8px;
   gap: 8px;
   align-items: center;
-  justify-content: center;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
   z-index: 51;
 }
 
@@ -1978,10 +2085,15 @@ html.mobile-init .file-browser-panel {
   display: flex;
 }
 
+.keyboard-accessory-bar::-webkit-scrollbar {
+  display: none;
+}
+
 .accessory-btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
+  flex-shrink: 0;
   gap: 4px;
   padding: 6px 12px;
   background: #2a2a2a;
@@ -2011,31 +2123,33 @@ html.mobile-init .file-browser-panel {
 
 .accessory-btn-arrow {
   padding: 6px 10px;
-  background: #1e3a5f;
-  border-color: rgba(59, 130, 246, 0.3);
-  color: #93c5fd;
+  background: #2563eb;
+  border-color: rgba(59, 130, 246, 0.5);
+  color: #fff;
 }
 
 .accessory-btn-arrow:active {
-  background: #2563eb;
+  background: #1d4ed8;
 }
 
 .accessory-btn-dismiss {
-  padding: 8px 14px;
-  background: #2a2a2a;
-  border: 1.5px solid rgba(255, 255, 255, 0.25);
-  border-radius: 6px;
-  color: #e5e5e5;
+  margin-left: auto;
+  flex: 1 1 0;
+  max-width: 80px;
+  padding: 10px 8px;
+  background: #334d6e;
+  border-color: rgba(100, 150, 200, 0.4);
+  color: #c0d4e8;
+  font-weight: 600;
 }
 
 .accessory-btn-dismiss svg {
-  width: 22px;
-  height: 22px;
-  stroke-width: 3;
+  width: 20px;
+  height: 20px;
 }
 
 .accessory-btn-dismiss:active {
-  background: #3a3a3a;
+  background: #3d5f85;
 }
 
 /* ============================================================================

src/web/public/panels-ui.js

@@ -14,6 +14,13 @@
  */
 
 Object.assign(CodemanApp.prototype, {
+  _addActivityEntry(agentId, entry, maxSize = 50) {
+    const activity = this.subagentActivity.get(agentId) || [];
+    activity.push(entry);
+    if (activity.length > maxSize) activity.shift();
+    this.subagentActivity.set(agentId, activity);
+  },
+
   // Tasks
   _onTaskCreated(data) {
     this.renderSessionTabs();
@@ -106,15 +113,7 @@ Object.assign(CodemanApp.prototype, {
 
     // Notify about new subagent discovery
     const parentId = this.subagentParentMap.get(data.agentId);
-    const parentSession = parentId ? this.sessions.get(parentId) : null;
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'subagent-spawn',
-      sessionId: parentId || data.sessionId,
-      sessionName: parentSession?.name || parentId || data.sessionId,
-      title: 'Subagent Spawned',
-      message: data.description || 'New background agent started',
-    });
+    this._notifySession(parentId || data.sessionId, 'info', 'subagent-spawn', 'Subagent Spawned', data.description || 'New background agent started');
   },
 
   _onSubagentUpdated(data) {
@@ -135,10 +134,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   _onSubagentToolCall(data) {
-    const activity = this.subagentActivity.get(data.agentId) || [];
-    activity.push({ type: 'tool', ...data });
-    if (activity.length > 50) activity.shift(); // Keep last 50 entries
-    this.subagentActivity.set(data.agentId, activity);
+    this._addActivityEntry(data.agentId, { type: 'tool', ...data });
     if (this.activeSubagentId === data.agentId) {
       this.renderSubagentDetail();
     }
@@ -150,10 +146,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   _onSubagentProgress(data) {
-    const activity = this.subagentActivity.get(data.agentId) || [];
-    activity.push({ type: 'progress', ...data });
-    if (activity.length > 50) activity.shift();
-    this.subagentActivity.set(data.agentId, activity);
+    this._addActivityEntry(data.agentId, { type: 'progress', ...data });
     if (this.activeSubagentId === data.agentId) {
       this.renderSubagentDetail();
     }
@@ -164,10 +157,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   _onSubagentMessage(data) {
-    const activity = this.subagentActivity.get(data.agentId) || [];
-    activity.push({ type: 'message', ...data });
-    if (activity.length > 50) activity.shift();
-    this.subagentActivity.set(data.agentId, activity);
+    this._addActivityEntry(data.agentId, { type: 'message', ...data });
     if (this.activeSubagentId === data.agentId) {
       this.renderSubagentDetail();
     }
@@ -190,10 +180,7 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Add to activity stream
-    const activity = this.subagentActivity.get(data.agentId) || [];
-    activity.push({ type: 'tool_result', ...data });
-    if (activity.length > 50) activity.shift();
-    this.subagentActivity.set(data.agentId, activity);
+    this._addActivityEntry(data.agentId, { type: 'tool_result', ...data });
 
     if (this.activeSubagentId === data.agentId) {
       this.renderSubagentDetail();
@@ -224,15 +211,7 @@ Object.assign(CodemanApp.prototype, {
 
     // Notify about subagent completion
     const parentId = this.subagentParentMap.get(data.agentId);
-    const parentSession = parentId ? this.sessions.get(parentId) : null;
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'subagent-complete',
-      sessionId: parentId || existing?.sessionId || data.sessionId,
-      sessionName: parentSession?.name || parentId || data.sessionId,
-      title: 'Subagent Completed',
-      message: existing?.description || data.description || 'Background agent finished',
-    });
+    this._notifySession(parentId || existing?.sessionId || data.sessionId, 'info', 'subagent-complete', 'Subagent Completed', existing?.description || data.description || 'Background agent finished');
 
     // Clean up activity/tool data for completed agents after 5 minutes
     // This prevents memory leaks from long-running sessions with many subagents
@@ -613,13 +592,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   renderTaskPanel() {
-    // Debounce renders at 100ms to prevent excessive DOM updates
-    if (this.renderTaskPanelTimeout) {
-      clearTimeout(this.renderTaskPanelTimeout);
-    }
-    this.renderTaskPanelTimeout = setTimeout(() => {
-      this._renderTaskPanelImmediate();
-    }, 100);
+    this._debouncedCall('taskPanel', this._renderTaskPanelImmediate);
   },
 
   _renderTaskPanelImmediate() {
@@ -2974,13 +2947,7 @@ Object.assign(CodemanApp.prototype, {
 
 
   renderMuxSessions() {
-    // Debounce renders at 100ms to prevent excessive DOM updates
-    if (this.renderMuxSessionsTimeout) {
-      clearTimeout(this.renderMuxSessionsTimeout);
-    }
-    this.renderMuxSessionsTimeout = setTimeout(() => {
-      this._renderMuxSessionsImmediate();
-    }, 100);
+    this._debouncedCall('muxSessions', this._renderMuxSessionsImmediate);
   },
 
   _renderMuxSessionsImmediate() {

src/web/public/ralph-panel.js

@@ -45,15 +45,7 @@ Object.assign(CodemanApp.prototype, {
       this.updateRalphState(data.sessionId, existing);
     }
 
-    const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'warning',
-      category: 'ralph-complete',
-      sessionId: data.sessionId,
-      sessionName: session?.name || this.getShortId(data.sessionId),
-      title: 'Loop Complete',
-      message: `Completion: ${data.phrase || 'unknown'}`,
-    });
+    this._notifySession(data.sessionId, 'warning', 'ralph-complete', 'Loop Complete', `Completion: ${data.phrase || 'unknown'}`);
   },
 
   _onRalphStatusUpdate(data) {
@@ -68,28 +60,12 @@ Object.assign(CodemanApp.prototype, {
     this.updateRalphState(data.sessionId, { circuitBreaker: data.status });
     // Notify if circuit breaker opens
     if (data.status.state === 'OPEN') {
-      const session = this.sessions.get(data.sessionId);
-      this.notificationManager?.notify({
-        urgency: 'critical',
-        category: 'circuit-breaker',
-        sessionId: data.sessionId,
-        sessionName: session?.name || this.getShortId(data.sessionId),
-        title: 'Circuit Breaker Open',
-        message: data.status.reason || 'Loop stuck - no progress detected',
-      });
+      this._notifySession(data.sessionId, 'critical', 'circuit-breaker', 'Circuit Breaker Open', data.status.reason || 'Loop stuck - no progress detected');
     }
   },
 
   _onExitGateMet(data) {
-    const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'warning',
-      category: 'exit-gate',
-      sessionId: data.sessionId,
-      sessionName: session?.name || this.getShortId(data.sessionId),
-      title: 'Exit Gate Met',
-      message: `Loop ready to exit (indicators: ${data.completionIndicators})`,
-    });
+    this._notifySession(data.sessionId, 'warning', 'exit-gate', 'Exit Gate Met', `Loop ready to exit (indicators: ${data.completionIndicators})`);
   },
 
   // Bash tools
@@ -471,13 +447,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   renderRalphStatePanel() {
-    // Debounce renders at 50ms to prevent excessive DOM updates
-    if (this.renderRalphStatePanelTimeout) {
-      clearTimeout(this.renderRalphStatePanelTimeout);
-    }
-    this.renderRalphStatePanelTimeout = setTimeout(() => {
-      this._renderRalphStatePanelImmediate();
-    }, 50);
+    this._debouncedCall('ralphStatePanel', this._renderRalphStatePanelImmediate, 50);
   },
 
   _renderRalphStatePanelImmediate() {

src/web/public/respawn-ui.js

@@ -44,21 +44,13 @@ Object.assign(CodemanApp.prototype, {
   },
 
   _onRespawnBlocked(data) {
-    const session = this.sessions.get(data.sessionId);
     const reasonMap = {
       circuit_breaker_open: 'Circuit Breaker Open',
       exit_signal: 'Exit Signal Detected',
       status_blocked: 'Claude Reported BLOCKED',
     };
     const title = reasonMap[data.reason] || 'Respawn Blocked';
-    this.notificationManager?.notify({
-      urgency: 'critical',
-      category: 'respawn-blocked',
-      sessionId: data.sessionId,
-      sessionName: session?.name || this.getShortId(data.sessionId),
-      title,
-      message: data.details,
-    });
+    this._notifySession(data.sessionId, 'critical', 'respawn-blocked', title, data.details);
     // Update respawn panel to show blocked state
     if (data.sessionId === this.activeSessionId) {
       const stateEl = document.getElementById('respawnStateLabel');
@@ -71,14 +63,7 @@ Object.assign(CodemanApp.prototype, {
 
   _onRespawnAutoAcceptSent(data) {
     const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'auto-accept',
-      sessionId: data.sessionId,
-      sessionName: session?.name || this.getShortId(data.sessionId),
-      title: 'Plan Accepted',
-      message: `Accepted plan mode for ${session?.name || 'session'}`,
-    });
+    this._notifySession(data.sessionId, 'info', 'auto-accept', 'Plan Accepted', `Accepted plan mode for ${session?.name || 'session'}`);
   },
 
   _onRespawnDetectionUpdate(data) {
@@ -144,15 +129,7 @@ Object.assign(CodemanApp.prototype, {
   },
 
   _onRespawnError(data) {
-    const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'critical',
-      category: 'session-error',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Respawn Error',
-      message: data.error || data.message || 'Respawn encountered an error',
-    });
+    this._notifySession(data.sessionId, 'critical', 'session-error', 'Respawn Error', data.error || data.message || 'Respawn encountered an error');
   },
 
   _onRespawnActionLog(data) {

src/web/public/session-ui.js

@@ -109,16 +109,10 @@ Object.assign(CodemanApp.prototype, {
 
   async saveLastUsedCase(caseName) {
     try {
-      // Get current settings
-      const res = await fetch('/api/settings');
-      const settings = res.ok ? await res.json() : {};
-      // Update lastUsedCase
-      settings.lastUsedCase = caseName;
-      // Save back
       await fetch('/api/settings', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(settings)
+        body: JSON.stringify({ lastUsedCase: caseName })
       });
     } catch (err) {
       console.error('Failed to save last used case:', err);
@@ -273,6 +267,11 @@ Object.assign(CodemanApp.prototype, {
     this.terminal.clear();
     this.terminal.writeln(`\x1b[1;32m Starting ${tabCount} Claude session(s) in ${caseName}...\x1b[0m`);
     this.terminal.writeln('');
+    // Focus terminal NOW, in the synchronous user-gesture context (button click).
+    // iOS Safari ignores programmatic focus() after any await, so this must happen
+    // before the first async call. The keyboard opens here and stays open through
+    // the session creation flow; selectSession at the end inherits the focus state.
+    this.terminal.focus();
 
     try {
       // Get case path first
@@ -325,6 +324,8 @@ Object.assign(CodemanApp.prototype, {
         envOverrides.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
       }
       const hasEnvOverrides = Object.keys(envOverrides).length > 0;
+      const useOpus1m = caseSettings.opusContext1m || globalSettings.opusContext1mEnabled;
+      const modelOverride = useOpus1m ? 'opus[1m]' : '';
 
       // Step 1: Create all sessions in parallel
       this.terminal.writeln(`\x1b[90m Creating ${tabCount} session(s)...\x1b[0m`);
@@ -332,7 +333,11 @@ Object.assign(CodemanApp.prototype, {
         fetch('/api/sessions', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ workingDir, name, ...(hasEnvOverrides ? { envOverrides } : {}) })
+          body: JSON.stringify({
+            workingDir, name,
+            ...(hasEnvOverrides ? { envOverrides } : {}),
+            ...(modelOverride !== undefined ? { modelOverride } : {}),
+          })
         }).then(r => r.json())
       );
       const createResults = await Promise.all(createPromises);
@@ -493,6 +498,8 @@ Object.assign(CodemanApp.prototype, {
     this.terminal.clear();
     this.terminal.writeln(`\x1b[1;32m Starting OpenCode session in ${caseName}...\x1b[0m`);
     this.terminal.writeln('');
+    // Focus in sync gesture context (see runClaude comment)
+    this.terminal.focus();
 
     try {
       // Check if OpenCode is available
@@ -912,6 +919,7 @@ Object.assign(CodemanApp.prototype, {
       const caseName = document.getElementById('quickStartCase').value || 'testcase';
       const settings = this.getCaseSettings(caseName);
       document.getElementById('caseAgentTeams').checked = settings.agentTeams;
+      document.getElementById('caseOpusContext1m').checked = settings.opusContext1m;
       popover.classList.remove('hidden');
 
       // Close on outside click (one-shot listener)
@@ -933,7 +941,7 @@ Object.assign(CodemanApp.prototype, {
       const stored = localStorage.getItem('caseSettings_' + caseName);
       if (stored) return JSON.parse(stored);
     } catch { /* ignore */ }
-    return { agentTeams: false };
+    return { agentTeams: false, opusContext1m: true };
   },
 
   saveCaseSettings(caseName, settings) {
@@ -944,10 +952,13 @@ Object.assign(CodemanApp.prototype, {
     const caseName = document.getElementById('quickStartCase').value || 'testcase';
     const settings = this.getCaseSettings(caseName);
     settings.agentTeams = document.getElementById('caseAgentTeams').checked;
+    settings.opusContext1m = document.getElementById('caseOpusContext1m').checked;
     this.saveCaseSettings(caseName, settings);
-    // Sync mobile checkbox
+    // Sync mobile checkboxes
     const mobileCheckbox = document.getElementById('caseAgentTeamsMobile');
     if (mobileCheckbox) mobileCheckbox.checked = settings.agentTeams;
+    const mobileOpusCheckbox = document.getElementById('caseOpusContext1mMobile');
+    if (mobileOpusCheckbox) mobileOpusCheckbox.checked = settings.opusContext1m;
   },
 
   toggleCaseSettingsMobile() {
@@ -956,6 +967,7 @@ Object.assign(CodemanApp.prototype, {
       const caseName = document.getElementById('quickStartCase').value || 'testcase';
       const settings = this.getCaseSettings(caseName);
       document.getElementById('caseAgentTeamsMobile').checked = settings.agentTeams;
+      document.getElementById('caseOpusContext1mMobile').checked = settings.opusContext1m;
       popover.classList.remove('hidden');
 
       const closeHandler = (e) => {
@@ -974,10 +986,13 @@ Object.assign(CodemanApp.prototype, {
     const caseName = document.getElementById('quickStartCase').value || 'testcase';
     const settings = this.getCaseSettings(caseName);
     settings.agentTeams = document.getElementById('caseAgentTeamsMobile').checked;
+    settings.opusContext1m = document.getElementById('caseOpusContext1mMobile').checked;
     this.saveCaseSettings(caseName, settings);
-    // Sync desktop checkbox
+    // Sync desktop checkboxes
     const desktopCheckbox = document.getElementById('caseAgentTeams');
     if (desktopCheckbox) desktopCheckbox.checked = settings.agentTeams;
+    const desktopOpusCheckbox = document.getElementById('caseOpusContext1m');
+    if (desktopOpusCheckbox) desktopOpusCheckbox.checked = settings.opusContext1m;
   },
 
   // ═══════════════════════════════════════════════════════════════
@@ -1023,13 +1038,19 @@ Object.assign(CodemanApp.prototype, {
     modal.querySelectorAll('.modal-tab-content').forEach(content => {
       content.classList.toggle('hidden', content.id !== tabName);
     });
-    // Update submit button text
+    // Update submit button (hide for manage tab)
     const submitBtn = document.getElementById('caseModalSubmit');
-    submitBtn.textContent = tabName === 'case-create' ? 'Create' : 'Link';
+    if (tabName === 'case-manage') {
+      submitBtn.style.display = 'none';
+      this.renderCaseManageList();
+    } else {
+      submitBtn.style.display = '';
+      submitBtn.textContent = tabName === 'case-create' ? 'Create' : 'Link';
+    }
     // Focus appropriate input
     if (tabName === 'case-create') {
       document.getElementById('newCaseName').focus();
-    } else {
+    } else if (tabName === 'case-link') {
       document.getElementById('linkCaseName').focus();
     }
   },
@@ -1137,6 +1158,107 @@ Object.assign(CodemanApp.prototype, {
   },
 
 
+  // ═══════════════════════════════════════════════════════════════
+  // Case Management (reorder + delete)
+  // ═══════════════════════════════════════════════════════════════
+
+  renderCaseManageList() {
+    const container = document.getElementById('caseManageList');
+    const cases = this.cases || [];
+    if (cases.length === 0) {
+      container.innerHTML = '<div class="form-hint" style="text-align: center; padding: 2rem 0;">No cases yet</div>';
+      return;
+    }
+
+    let html = '';
+    cases.forEach((c, idx) => {
+      const isFirst = idx === 0;
+      const isLast = idx === cases.length - 1;
+      const pathDisplay = c.path ? c.path.replace(/^\/Users\/[^/]+/, '~') : '';
+      html += `
+        <div class="case-manage-item" data-case="${escapeHtml(c.name)}">
+          <div class="case-manage-info">
+            <span class="case-manage-name">${escapeHtml(c.name)}</span>
+            <span class="case-manage-path">${escapeHtml(pathDisplay)}</span>
+          </div>
+          <div class="case-manage-actions">
+            <button class="case-manage-btn" onclick="app.moveCaseUp('${escapeHtml(c.name)}')"
+                    title="Move up" ${isFirst ? 'disabled' : ''}>&#x25B2;</button>
+            <button class="case-manage-btn" onclick="app.moveCaseDown('${escapeHtml(c.name)}')"
+                    title="Move down" ${isLast ? 'disabled' : ''}>&#x25BC;</button>
+            <button class="case-manage-btn case-manage-btn-delete" onclick="app.deleteCase('${escapeHtml(c.name)}')"
+                    title="Delete case">&#x2715;</button>
+          </div>
+        </div>
+      `;
+    });
+    container.innerHTML = html;
+  },
+
+  async moveCaseUp(name) {
+    const cases = this.cases || [];
+    const idx = cases.findIndex(c => c.name === name);
+    if (idx <= 0) return;
+    // Swap positions (immutable)
+    const reordered = [...cases];
+    [reordered[idx - 1], reordered[idx]] = [reordered[idx], reordered[idx - 1]];
+    this.cases = reordered;
+    this.renderCaseManageList();
+    await this.saveCaseOrder(reordered.map(c => c.name));
+  },
+
+  async moveCaseDown(name) {
+    const cases = this.cases || [];
+    const idx = cases.findIndex(c => c.name === name);
+    if (idx < 0 || idx >= cases.length - 1) return;
+    const reordered = [...cases];
+    [reordered[idx], reordered[idx + 1]] = [reordered[idx + 1], reordered[idx]];
+    this.cases = reordered;
+    this.renderCaseManageList();
+    await this.saveCaseOrder(reordered.map(c => c.name));
+  },
+
+  async deleteCase(name) {
+    if (!confirm(`Delete case "${name}"? Linked cases will only be unlinked (folder preserved). Created cases will be permanently deleted.`)) {
+      return;
+    }
+
+    try {
+      const res = await fetch(`/api/cases/${encodeURIComponent(name)}`, { method: 'DELETE' });
+      const data = await res.json();
+      if (data.success) {
+        this.showToast(`Case "${name}" ${data.data?.type === 'unlinked' ? 'unlinked' : 'deleted'}`, 'success');
+        // Remove from current list and refresh
+        this.cases = (this.cases || []).filter(c => c.name !== name);
+        this.renderCaseManageList();
+        // Refresh the dropdown
+        const select = document.getElementById('quickStartCase');
+        const currentCase = select.value;
+        await this.loadQuickStartCases(currentCase === name ? null : currentCase);
+      } else {
+        this.showToast(data.error || 'Failed to delete case', 'error');
+      }
+    } catch (err) {
+      this.showToast('Failed to delete case: ' + err.message, 'error');
+    }
+  },
+
+  async saveCaseOrder(order) {
+    try {
+      await fetch('/api/cases/order', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ order })
+      });
+      // Refresh dropdown to reflect new order
+      const select = document.getElementById('quickStartCase');
+      const currentCase = select.value;
+      await this.loadQuickStartCases(currentCase);
+    } catch (err) {
+      this.showToast('Failed to save case order: ' + err.message, 'error');
+    }
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // Mobile Case Picker
   // ═══════════════════════════════════════════════════════════════
@@ -1166,6 +1288,11 @@ Object.assign(CodemanApp.prototype, {
             </svg>
           </span>
           <span class="mobile-case-item-name">${escapeHtml(c.name)}</span>
+          <span class="mobile-case-item-delete" onclick="event.stopPropagation(); app.deleteCaseMobile('${escapeHtml(c.name)}')" title="Delete">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
+            </svg>
+          </span>
           <span class="mobile-case-item-check">
             <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
               <polyline points="20 6 9 17 4 12"/>
@@ -1211,6 +1338,25 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  async deleteCaseMobile(name) {
+    if (!confirm(`Delete case "${name}"?`)) return;
+    try {
+      const res = await fetch(`/api/cases/${encodeURIComponent(name)}`, { method: 'DELETE' });
+      const data = await res.json();
+      if (data.success) {
+        this.showToast(`Case "${name}" ${data.data?.type === 'unlinked' ? 'unlinked' : 'deleted'}`, 'success');
+        this.cases = (this.cases || []).filter(c => c.name !== name);
+        // Refresh mobile picker and dropdown
+        this.closeMobileCasePicker();
+        await this.loadQuickStartCases();
+      } else {
+        this.showToast(data.error || 'Failed to delete case', 'error');
+      }
+    } catch (err) {
+      this.showToast('Failed to delete case: ' + err.message, 'error');
+    }
+  },
+
   showCreateCaseFromMobile() {
     // Close mobile picker first
     this.closeMobileCasePicker();

src/web/public/settings-ui.js

@@ -14,92 +14,46 @@
 Object.assign(CodemanApp.prototype, {
   // Hooks (Claude Code hook events)
   _onHookIdlePrompt(data) {
-    const session = this.sessions.get(data.sessionId);
     // Always track pending hook - alert will show when switching away from session
     if (data.sessionId) {
       this.setPendingHook(data.sessionId, 'idle_prompt');
     }
-    this.notificationManager?.notify({
-      urgency: 'warning',
-      category: 'hook-idle',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Waiting for Input',
-      message: data.message || 'Claude is idle and waiting for a prompt',
-    });
+    this._notifySession(data.sessionId, 'warning', 'hook-idle', 'Waiting for Input', data.message || 'Claude is idle and waiting for a prompt');
   },
 
   _onHookPermissionPrompt(data) {
-    const session = this.sessions.get(data.sessionId);
     // Always track pending hook - action alerts need user interaction to clear
     if (data.sessionId) {
       this.setPendingHook(data.sessionId, 'permission_prompt');
     }
     const toolInfo = data.tool ? `${data.tool}${data.command ? ': ' + data.command : data.file ? ': ' + data.file : ''}` : '';
-    this.notificationManager?.notify({
-      urgency: 'critical',
-      category: 'hook-permission',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Permission Required',
-      message: toolInfo || 'Claude needs tool approval to continue',
-    });
+    this._notifySession(data.sessionId, 'critical', 'hook-permission', 'Permission Required', toolInfo || 'Claude needs tool approval to continue');
   },
 
   _onHookElicitationDialog(data) {
-    const session = this.sessions.get(data.sessionId);
     // Always track pending hook - action alerts need user interaction to clear
     if (data.sessionId) {
       this.setPendingHook(data.sessionId, 'elicitation_dialog');
     }
-    this.notificationManager?.notify({
-      urgency: 'critical',
-      category: 'hook-elicitation',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Question Asked',
-      message: data.question || 'Claude is asking a question and waiting for your answer',
-    });
+    this._notifySession(data.sessionId, 'critical', 'hook-elicitation', 'Question Asked', data.question || 'Claude is asking a question and waiting for your answer');
   },
 
   _onHookStop(data) {
-    const session = this.sessions.get(data.sessionId);
     // Clear all pending hooks when Claude finishes responding
     if (data.sessionId) {
       this.clearPendingHooks(data.sessionId);
     }
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'hook-stop',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Response Complete',
-      message: data.reason || 'Claude has finished responding',
-    });
+    this._notifySession(data.sessionId, 'info', 'hook-stop', 'Response Complete', data.reason || 'Claude has finished responding');
   },
 
   _onHookTeammateIdle(data) {
     const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'warning',
-      category: 'hook-teammate-idle',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Teammate Idle',
-      message: `A teammate is idle in ${session?.name || data.sessionId}`,
-    });
+    this._notifySession(data.sessionId, 'warning', 'hook-teammate-idle', 'Teammate Idle', `A teammate is idle in ${session?.name || data.sessionId}`);
   },
 
   _onHookTaskCompleted(data) {
     const session = this.sessions.get(data.sessionId);
-    this.notificationManager?.notify({
-      urgency: 'info',
-      category: 'hook-task-completed',
-      sessionId: data.sessionId,
-      sessionName: session?.name || data.sessionId,
-      title: 'Task Completed',
-      message: `A team task completed in ${session?.name || data.sessionId}`,
-    });
+    this._notifySession(data.sessionId, 'info', 'hook-task-completed', 'Task Completed', `A team task completed in ${session?.name || data.sessionId}`);
   },
 
 
@@ -364,6 +318,8 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsTunnelEnabled').checked = settings.tunnelEnabled ?? false;
     this.loadTunnelStatus();
     document.getElementById('appSettingsLocalEcho').checked = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
+    document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? false;
+    document.getElementById('appSettingsExtendedKeyboardBar').checked = settings.extendedKeyboardBar ?? false;
     document.getElementById('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
     // Claude CLI settings
     const claudeModeSelect = document.getElementById('appSettingsClaudeMode');
@@ -377,6 +333,7 @@ Object.assign(CodemanApp.prototype, {
     };
     // Claude Permissions settings
     document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
+    document.getElementById('appSettingsOpusContext1m').checked = settings.opusContext1mEnabled ?? false;
     // CPU Priority settings
     const niceSettings = settings.nice || {};
     document.getElementById('appSettingsNiceEnabled').checked = niceSettings.enabled ?? false;
@@ -516,16 +473,17 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-  _updateTunnelUrlDisplay(url) {
-    const row = document.getElementById('tunnelUrlRow');
-    const display = document.getElementById('tunnelUrlDisplay');
+  _updateTunnelUrlRow(rowId, displayId, url, suffix = '') {
+    const row = document.getElementById(rowId);
+    const display = document.getElementById(displayId);
     if (!row || !display) return;
     if (url) {
+      const fullUrl = url + suffix;
       row.style.display = '';
-      display.textContent = url;
+      display.textContent = fullUrl;
       display.onclick = () => {
-        navigator.clipboard.writeText(url).then(() => {
-          this.showToast('Tunnel URL copied', 'success');
+        navigator.clipboard.writeText(fullUrl).then(() => {
+          this.showToast(`${suffix ? 'Upload' : 'Tunnel'} URL copied`, 'success');
         });
       };
     } else {
@@ -533,24 +491,11 @@ Object.assign(CodemanApp.prototype, {
       display.textContent = '';
       display.onclick = null;
     }
-    // Upload URL row
-    const uploadRow = document.getElementById('tunnelUploadUrlRow');
-    const uploadDisplay = document.getElementById('tunnelUploadUrlDisplay');
-    if (!uploadRow || !uploadDisplay) return;
-    if (url) {
-      const uploadUrl = url + '/upload.html';
-      uploadRow.style.display = '';
-      uploadDisplay.textContent = uploadUrl;
-      uploadDisplay.onclick = () => {
-        navigator.clipboard.writeText(uploadUrl).then(() => {
-          this.showToast('Upload URL copied', 'success');
-        });
-      };
-    } else {
-      uploadRow.style.display = 'none';
-      uploadDisplay.textContent = '';
-      uploadDisplay.onclick = null;
-    }
+  },
+
+  _updateTunnelUrlDisplay(url) {
+    this._updateTunnelUrlRow('tunnelUrlRow', 'tunnelUrlDisplay', url);
+    this._updateTunnelUrlRow('tunnelUploadUrlRow', 'tunnelUploadUrlDisplay', url, '/upload.html');
   },
 
   showTunnelQR() {
@@ -1180,12 +1125,15 @@ Object.assign(CodemanApp.prototype, {
       imageWatcherEnabled: document.getElementById('appSettingsImageWatcherEnabled').checked,
       tunnelEnabled: document.getElementById('appSettingsTunnelEnabled').checked,
       localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
+      cjkInputEnabled: document.getElementById('appSettingsCjkInput').checked,
+      extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
       tabTwoRows: document.getElementById('appSettingsTabTwoRows').checked,
       // Claude CLI settings
       claudeMode: document.getElementById('appSettingsClaudeMode').value,
       allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(),
       // Claude Permissions settings
       agentTeamsEnabled: document.getElementById('appSettingsAgentTeams').checked,
+      opusContext1mEnabled: document.getElementById('appSettingsOpusContext1m').checked,
       // CPU Priority settings
       nice: {
         enabled: document.getElementById('appSettingsNiceEnabled').checked,
@@ -1296,9 +1244,15 @@ Object.assign(CodemanApp.prototype, {
     this.renderProjectInsightsPanel();  // Re-render to apply visibility setting
     this.updateSubagentWindowVisibility();  // Apply subagent window visibility setting
 
+    // Apply CJK input visibility immediately
+    this._updateCjkInputState();
+
+    // Apply keyboard bar mode
+    KeyboardAccessoryBar.setMode(settings.extendedKeyboardBar ? 'extended' : 'simple');
+
     // Save to server (includes notification prefs for cross-browser persistence)
-    // Strip device-specific keys — localEchoEnabled is per-platform (touch default differs)
-    const { localEchoEnabled: _leo, ...serverSettings } = settings;
+    // Strip device-specific keys — localEchoEnabled/cjkInputEnabled are per-platform
+    const { localEchoEnabled: _leo, cjkInputEnabled: _cjk, extendedKeyboardBar: _ekb, ...serverSettings } = settings;
     try {
       await this._apiPut('/api/settings', { ...serverSettings, notificationPreferences: notifPrefsToSave, voiceSettings });
 
@@ -1329,7 +1283,7 @@ Object.assign(CodemanApp.prototype, {
         // Default model
         const defaultModelEl = document.getElementById('appSettingsDefaultModel');
         if (defaultModelEl) {
-          defaultModelEl.value = config.defaultModel || 'opus';
+          defaultModelEl.value = config.defaultModel || '';
         }
         // Show recommendations
         const showRecsEl = document.getElementById('appSettingsShowModelRecommendations');
@@ -1368,7 +1322,7 @@ Object.assign(CodemanApp.prototype, {
     if (reviewEl?.value) agentTypeOverrides.review = reviewEl.value;
 
     const config = {
-      defaultModel: defaultModelEl?.value || 'opus',
+      defaultModel: defaultModelEl?.value || '',
       showRecommendations: showRecsEl?.checked ?? true,
       agentTypeOverrides,
     };
@@ -1682,7 +1636,7 @@ Object.assign(CodemanApp.prototype, {
         const displayKeys = new Set([
           'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled',
+          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
         ]);
         // Merge settings: non-display keys always sync from server,
         // display keys only seed from server when localStorage has no value

src/web/public/styles.css

@@ -94,7 +94,11 @@ textarea:focus-visible {
   outline: none;
 }
 
-/* xterm.js hidden textarea — must never show focus ring or caret */
+/* xterm.js hidden textarea — must never show focus ring or caret.
+ * On mobile (touch devices), override xterm.css defaults that position the
+ * textarea at left:-9999em with width/height:0. iOS Safari ignores keyboard
+ * input to off-screen zero-size textareas, so we move it on-screen with a
+ * minimal size while keeping it visually invisible. */
 .xterm-helper-textarea {
   border: none !important;
   box-shadow: none !important;
@@ -102,6 +106,14 @@ textarea:focus-visible {
   opacity: 0 !important;
   caret-color: transparent !important;
 }
+.touch-device .xterm .xterm-helper-textarea {
+  left: 0 !important;
+  top: 0 !important;
+  width: 1px !important;
+  height: 1px !important;
+  z-index: -1 !important;
+  font-size: 16px !important; /* prevent iOS auto-zoom on focus */
+}
 
 /* Session tab focus */
 .session-tab:focus-visible {
@@ -2952,6 +2964,93 @@ body {
   font-size: 0.6rem;
 }
 
+/* Case Management List (Manage tab) */
+.case-manage-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+.case-manage-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 10px;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 6px;
+  transition: background var(--transition-smooth);
+}
+
+.case-manage-item:hover {
+  background: rgba(255, 255, 255, 0.06);
+}
+
+.case-manage-info {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+  flex: 1;
+}
+
+.case-manage-name {
+  font-size: 0.8rem;
+  font-weight: 500;
+  color: var(--text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.case-manage-path {
+  font-size: 0.65rem;
+  color: var(--text-dim);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.case-manage-actions {
+  display: flex;
+  gap: 4px;
+  margin-left: 10px;
+  flex-shrink: 0;
+}
+
+.case-manage-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  border-radius: 4px;
+  color: var(--text-dim);
+  font-size: 0.65rem;
+  cursor: pointer;
+  transition: all var(--transition-smooth);
+}
+
+.case-manage-btn:hover:not(:disabled) {
+  background: rgba(255, 255, 255, 0.1);
+  color: var(--text);
+}
+
+.case-manage-btn:disabled {
+  opacity: 0.25;
+  cursor: not-allowed;
+}
+
+.case-manage-btn-delete:hover:not(:disabled) {
+  background: rgba(239, 68, 68, 0.15);
+  border-color: rgba(239, 68, 68, 0.3);
+  color: #ef4444;
+}
+
 .toolbar-input {
   padding: 0.4rem 0.5rem;
   background: var(--bg-input);
@@ -3680,6 +3779,25 @@ body {
   opacity: 1;
 }
 
+.mobile-case-item-delete {
+  width: 28px;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-dim);
+  opacity: 0.4;
+  flex-shrink: 0;
+  border-radius: 4px;
+  transition: all var(--transition-smooth);
+}
+
+.mobile-case-item-delete:active {
+  opacity: 1;
+  color: #ef4444;
+  background: rgba(239, 68, 68, 0.15);
+}
+
 .mobile-case-picker-footer {
   padding: 12px 20px 16px;
   border-top: 1px solid rgba(255, 255, 255, 0.1);

src/web/public/terminal-ui.js

@@ -64,7 +64,9 @@ Object.assign(CodemanApp.prototype, {
         const unicode11Addon = new Unicode11Addon.Unicode11Addon();
         this.terminal.loadAddon(unicode11Addon);
         this.terminal.unicode.activeVersion = '11';
-      } catch (_e) { /* Unicode11 addon failed — default Unicode handling used */ }
+      } catch (_e) {
+        /* Unicode11 addon failed — default Unicode handling used */
+      }
     }
 
     const container = document.getElementById('terminalContainer');
@@ -115,8 +117,8 @@ Object.assign(CodemanApp.prototype, {
 
     // On mobile Safari, delay initial fit() to allow layout to settle
     // This prevents 0-column terminals caused by fit() running before container is sized
-    const isMobileSafari = MobileDetection.getDeviceType() === 'mobile' &&
-                           document.body.classList.contains('safari-browser');
+    const isMobileSafari =
+      MobileDetection.getDeviceType() === 'mobile' && document.body.classList.contains('safari-browser');
     if (isMobileSafari) {
       // Wait for layout, then fit multiple times to ensure proper sizing
       requestAnimationFrame(() => {
@@ -133,11 +135,15 @@ Object.assign(CodemanApp.prototype, {
 
     // Always use mouse wheel for terminal scrollback, never forward to application.
     // Prevents Claude's Ink UI (plan mode selector) from capturing scroll as option navigation.
-    container.addEventListener('wheel', (ev) => {
-      ev.preventDefault();
-      const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
-      this.terminal.scrollLines(lines);
-    }, { passive: false });
+    container.addEventListener(
+      'wheel',
+      (ev) => {
+        ev.preventDefault();
+        const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
+        this.terminal.scrollLines(lines);
+      },
+      { passive: false }
+    );
 
     // Touch scrolling — use terminal.scrollLines() for all devices.
     // xterm.js DOM renderer doesn't populate xterm-viewport's scroll area,
@@ -145,8 +151,7 @@ Object.assign(CodemanApp.prototype, {
     // has nothing to scroll. Instead, convert touch deltas into scrollLines()
     // calls, matching the wheel handler above.
     {
-      const cellHeight = () =>
-        this.terminal._core?._renderService?.dimensions?.css?.cell?.height || 13;
+      const cellHeight = () => this.terminal._core?._renderService?.dimensions?.css?.cell?.height || 13;
       let touchLastY = 0;
       let velocity = 0;
       let lastTime = 0;
@@ -174,46 +179,74 @@ Object.assign(CodemanApp.prototype, {
       // Accumulate sub-line pixel deltas so slow swipes still scroll
       let pixelAccum = 0;
 
-      container.addEventListener('touchstart', (ev) => {
-        if (ev.touches.length === 1) {
-          touchLastY = ev.touches[0].clientY;
+      let didScroll = false; // track whether touchmove fired (tap vs scroll)
+      container.addEventListener(
+        'touchstart',
+        (ev) => {
+          if (ev.touches.length === 1) {
+            touchLastY = ev.touches[0].clientY;
+            velocity = 0;
+            pixelAccum = 0;
+            isTouching = true;
+            didScroll = false;
+            lastTime = 0;
+            if (scrollFrame) {
+              cancelAnimationFrame(scrollFrame);
+              scrollFrame = null;
+            }
+          }
+        },
+        { passive: true }
+      );
+
+      container.addEventListener(
+        'touchmove',
+        (ev) => {
+          if (ev.touches.length === 1 && isTouching) {
+            didScroll = true;
+            const touchY = ev.touches[0].clientY;
+            const delta = touchLastY - touchY; // positive = scroll down
+            pixelAccum += delta;
+            velocity = delta * 1.2;
+            touchLastY = touchY;
+            // Convert accumulated pixels to whole lines
+            const ch = cellHeight();
+            const lines = Math.trunc(pixelAccum / ch);
+            if (lines !== 0) {
+              this.terminal.scrollLines(lines);
+              pixelAccum -= lines * ch;
+            }
+          }
+        },
+        { passive: true }
+      );
+
+      container.addEventListener(
+        'touchend',
+        () => {
+          isTouching = false;
+          if (!scrollFrame && Math.abs(velocity) > 0.3) {
+            scrollFrame = requestAnimationFrame(scrollLoop);
+          }
+          // Tap (no scroll): refocus xterm's hidden textarea so keyboard input
+          // routes back to the terminal. Without this, a tap on the terminal area
+          // consumes the touch event but xterm's textarea never regains focus.
+          if (!didScroll && this.terminal) {
+            this.terminal.focus();
+          }
+        },
+        { passive: true }
+      );
+
+      container.addEventListener(
+        'touchcancel',
+        () => {
+          isTouching = false;
           velocity = 0;
           pixelAccum = 0;
-          isTouching = true;
-          lastTime = 0;
-          if (scrollFrame) { cancelAnimationFrame(scrollFrame); scrollFrame = null; }
-        }
-      }, { passive: true });
-
-      container.addEventListener('touchmove', (ev) => {
-        if (ev.touches.length === 1 && isTouching) {
-          const touchY = ev.touches[0].clientY;
-          const delta = touchLastY - touchY; // positive = scroll down
-          pixelAccum += delta;
-          velocity = delta * 1.2;
-          touchLastY = touchY;
-          // Convert accumulated pixels to whole lines
-          const ch = cellHeight();
-          const lines = Math.trunc(pixelAccum / ch);
-          if (lines !== 0) {
-            this.terminal.scrollLines(lines);
-            pixelAccum -= lines * ch;
-          }
-        }
-      }, { passive: true });
-
-      container.addEventListener('touchend', () => {
-        isTouching = false;
-        if (!scrollFrame && Math.abs(velocity) > 0.3) {
-          scrollFrame = requestAnimationFrame(scrollLoop);
-        }
-      }, { passive: true });
-
-      container.addEventListener('touchcancel', () => {
-        isTouching = false;
-        velocity = 0;
-        pixelAccum = 0;
-      }, { passive: true });
+        },
+        { passive: true }
+      );
     }
 
     // Welcome message
@@ -260,17 +293,6 @@ Object.assign(CodemanApp.prototype, {
           }
           this.flushFlickerBuffer();
         }
-        // Clear viewport + scrollback for Ink-based sessions before sending SIGWINCH.
-        // fitAddon.fit() reflows content: lines at old width may wrap to more rows,
-        // pushing overflow into scrollback. Ink's cursor-up count is based on the
-        // pre-reflow line count, so ghost renders accumulate in scrollback.
-        // Fix: \x1b[3J (Erase Saved Lines) clears scrollback reflow debris,
-        // then \x1b[H\x1b[2J clears the viewport for a clean Ink redraw.
-        const activeResizeSession = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
-        if (activeResizeSession && activeResizeSession.mode !== 'shell' && !activeResizeSession._ended
-            && this.terminal && this.isTerminalAtBottom()) {
-          this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
-        }
         // Skip server resize while mobile keyboard is visible — sending SIGWINCH
         // causes Ink to re-render at the new row count, garbling terminal output.
         // Local fit() still runs so xterm knows the viewport size for scrolling.
@@ -281,14 +303,30 @@ Object.assign(CodemanApp.prototype, {
           const cols = dims ? Math.max(dims.cols, MIN_COLS) : MIN_COLS;
           const rows = dims ? Math.max(dims.rows, MIN_ROWS) : MIN_ROWS;
           // Only send resize if dimensions actually changed
-          if (!this._lastResizeDims ||
-              cols !== this._lastResizeDims.cols ||
-              rows !== this._lastResizeDims.rows) {
+          if (!this._lastResizeDims || cols !== this._lastResizeDims.cols || rows !== this._lastResizeDims.rows) {
+            // Clear viewport + scrollback ONLY when dimensions actually change.
+            // fitAddon.fit() reflows content: lines at old width may wrap to more rows,
+            // pushing overflow into scrollback. Ink's cursor-up count is based on the
+            // pre-reflow line count, so ghost renders accumulate in scrollback.
+            // Fix: \x1b[3J (Erase Saved Lines) clears scrollback reflow debris,
+            // then \x1b[H\x1b[2J clears the viewport for a clean Ink redraw.
+            // IMPORTANT: Only clear when we're actually sending SIGWINCH (dims changed).
+            // Clearing without a subsequent Ink redraw leaves the terminal blank.
+            const activeResizeSession = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
+            if (
+              activeResizeSession &&
+              activeResizeSession.mode !== 'shell' &&
+              !activeResizeSession._ended &&
+              this.terminal &&
+              this.isTerminalAtBottom()
+            ) {
+              this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
+            }
             this._lastResizeDims = { cols, rows };
             fetch(`/api/sessions/${this.activeSessionId}/resize`, {
               method: 'POST',
               headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ cols, rows })
+              body: JSON.stringify({ cols, rows }),
             }).catch(() => {});
           }
         }
@@ -442,7 +480,11 @@ Object.assign(CodemanApp.prototype, {
                 if (p) {
                   const buf = this.terminal.buffer.active;
                   const line = buf.getLine(buf.viewportY + p.row);
-                  if (line) baseText = line.translateToString(true).slice(p.col + 2).trimEnd();
+                  if (line)
+                    baseText = line
+                      .translateToString(true)
+                      .slice(p.col + 2)
+                      .trimEnd();
                 }
               } catch {}
               this._tabCompletionBaseText = baseText;
@@ -457,7 +499,8 @@ Object.assign(CodemanApp.prototype, {
               const selfTab = this;
               this._tabCompletionFallback = setTimeout(() => {
                 selfTab._tabCompletionFallback = null;
-                if (!selfTab._tabCompletionSessionId || selfTab._tabCompletionSessionId !== selfTab.activeSessionId) return;
+                if (!selfTab._tabCompletionSessionId || selfTab._tabCompletionSessionId !== selfTab.activeSessionId)
+                  return;
                 const ov = selfTab._localEchoOverlay;
                 if (!ov || ov.pendingText) return;
                 selfTab.terminal.write('', () => {
@@ -556,7 +599,8 @@ Object.assign(CodemanApp.prototype, {
         }
 
         const buffer = self.terminal.buffer.active;
-        const line = buffer.getLine(bufferLineNumber);
+        // provideLinks passes 1-based line number, getLine expects 0-based
+        const line = buffer.getLine(bufferLineNumber - 1);
 
         if (!line) {
           callback(undefined);
@@ -573,12 +617,37 @@ Object.assign(CodemanApp.prototype, {
 
         const links = [];
 
+        // Pattern 0: URLs (https://, http://) — matched first so they take priority
+        const urlPattern = /https?:\/\/[^\s"'<>|;&)\]\x00-\x1f]+/g;
+
+        const addUrlLink = (url, matchIndex) => {
+          // Strip trailing punctuation that's likely not part of the URL
+          const cleaned = url.replace(/[.,;:!?)]+$/, '');
+          const startCol = lineText.indexOf(cleaned, matchIndex);
+          if (startCol === -1) return;
+
+          if (links.some((l) => l.range.start.x === startCol + 1)) return;
+
+          links.push({
+            text: cleaned,
+            range: {
+              start: { x: startCol + 1, y: bufferLineNumber },
+              end: { x: startCol + cleaned.length + 1, y: bufferLineNumber },
+            },
+            decorations: { pointerCursor: true, underline: true },
+            activate(_event, text) {
+              window.open(text, '_blank', 'noopener,noreferrer');
+            },
+          });
+        };
+
         // Pattern 1: Commands with file paths (tail -f, cat, head, grep pattern, etc.)
         // Handles: tail -f /path, grep pattern /path, cat -n /path
         const cmdPattern = /(tail|cat|head|less|grep|watch|vim|nano)\s+(?:[^\s\/]*\s+)*(\/[^\s"'<>|;&\n\x00-\x1f]+)/g;
 
         // Pattern 2: Paths with common extensions
-        const extPattern = /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js))\b/g;
+        const extPattern =
+          /(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\n\x00-\x1f]*\.(?:log|txt|json|md|yaml|yml|csv|xml|sh|py|ts|js))\b/g;
 
         // Pattern 3: Bash() tool output
         const bashPattern = /Bash\([^)]*?(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\)\n\x00-\x1f]+)/g;
@@ -588,27 +657,32 @@ Object.assign(CodemanApp.prototype, {
           if (startCol === -1) return;
 
           // Skip if already have link at this position
-          if (links.some(l => l.range.start.x === startCol + 1)) return;
+          if (links.some((l) => l.range.start.x === startCol + 1)) return;
 
           links.push({
             text: filePath,
             range: {
-              start: { x: startCol + 1, y: bufferLineNumber },      // 1-based
-              end: { x: startCol + filePath.length + 1, y: bufferLineNumber }
+              start: { x: startCol + 1, y: bufferLineNumber }, // 1-based
+              end: { x: startCol + filePath.length + 1, y: bufferLineNumber },
             },
             decorations: {
               pointerCursor: true,
-              underline: true
+              underline: true,
             },
             activate(event, text) {
               self.openLogViewerWindow(text, self.activeSessionId);
-            }
+            },
           });
         };
 
-        // Match all patterns
+        // Match all patterns — URLs first so they take priority
         let match;
 
+        urlPattern.lastIndex = 0;
+        while ((match = urlPattern.exec(lineText)) !== null) {
+          addUrlLink(match[0], match.index);
+        }
+
         cmdPattern.lastIndex = 0;
         while ((match = cmdPattern.exec(lineText)) !== null) {
           addLink(match[2], match.index);
@@ -625,10 +699,13 @@ Object.assign(CodemanApp.prototype, {
         }
 
         if (links.length > 0) {
-          console.debug('[LinkProvider] Found links:', links.map(l => l.text));
+          console.debug(
+            '[LinkProvider] Found links:',
+            links.map((l) => l.text)
+          );
         }
         callback(links.length > 0 ? links : undefined);
-      }
+      },
     });
 
     console.log('[LinkProvider] File path link provider registered');
@@ -694,12 +771,17 @@ Object.assign(CodemanApp.prototype, {
       // Build DOM safely (no innerHTML with user data)
       list.replaceChildren();
       for (const s of display) {
-        const size = s.sizeBytes < 1024 ? `${s.sizeBytes}B`
-          : s.sizeBytes < 1048576 ? `${(s.sizeBytes / 1024).toFixed(0)}K`
-          : `${(s.sizeBytes / 1048576).toFixed(1)}M`;
+        const size =
+          s.sizeBytes < 1024
+            ? `${s.sizeBytes}B`
+            : s.sizeBytes < 1048576
+              ? `${(s.sizeBytes / 1024).toFixed(0)}K`
+              : `${(s.sizeBytes / 1048576).toFixed(1)}M`;
         const date = new Date(s.lastModified);
-        const timeStr = date.toLocaleDateString('en', { month: 'short', day: 'numeric' })
-          + ' ' + date.toLocaleTimeString('en', { hour: '2-digit', minute: '2-digit', hour12: false });
+        const timeStr =
+          date.toLocaleDateString('en', { month: 'short', day: 'numeric' }) +
+          ' ' +
+          date.toLocaleTimeString('en', { hour: '2-digit', minute: '2-digit', hour12: false });
         const shortDir = s.workingDir.replace(/^\/home\/[^/]+\//, '~/');
 
         const item = document.createElement('div');
@@ -762,7 +844,7 @@ Object.assign(CodemanApp.prototype, {
       const createRes = await fetch('/api/sessions', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ workingDir, name, resumeSessionId: sessionId })
+        body: JSON.stringify({ workingDir, name, resumeSessionId: sessionId }),
       });
       const createData = await createRes.json();
       if (!createData.success) throw new Error(createData.error);
@@ -780,7 +862,6 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-
   // ═══════════════════════════════════════════════════════════════
   // Terminal Rendering
   // ═══════════════════════════════════════════════════════════════
@@ -825,9 +906,10 @@ Object.assign(CodemanApp.prototype, {
 
     // Opt-in flicker filter: buffer screen clear patterns (for sessions that enable it)
     if (flickerFilterEnabled) {
-      const hasScreenClear = data.includes('\x1b[2J') ||
-                             data.includes('\x1b[H\x1b[J') ||
-                             (data.includes('\x1b[H') && data.includes('\x1b[?25l'));
+      const hasScreenClear =
+        data.includes('\x1b[2J') ||
+        data.includes('\x1b[H\x1b[J') ||
+        (data.includes('\x1b[H') && data.includes('\x1b[?25l'));
 
       if (hasScreenClear) {
         this.flickerFilterActive = true;
@@ -893,47 +975,49 @@ Object.assign(CodemanApp.prototype, {
    * Position is tracked dynamically by _findPrompt() on every render.
    */
   _updateLocalEchoState() {
-      const settings = this.loadAppSettingsFromStorage();
-      const session = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
-      const echoEnabled = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
-      const shouldEnable = !!(echoEnabled && session);
-      if (this._localEchoEnabled && !shouldEnable) {
-          this._localEchoOverlay?.clear();
-      }
-      this._localEchoEnabled = shouldEnable;
+    const settings = this.loadAppSettingsFromStorage();
+    const session = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
+    const echoEnabled = settings.localEchoEnabled ?? MobileDetection.isTouchDevice();
+    const shouldEnable = !!(echoEnabled && session);
+    if (this._localEchoEnabled && !shouldEnable) {
+      this._localEchoOverlay?.clear();
+    }
+    this._localEchoEnabled = shouldEnable;
 
-      // Swap prompt finder based on session mode
-      if (this._localEchoOverlay && session) {
-        if (session.mode === 'opencode') {
-          // OpenCode (Bubble Tea TUI): find the ┃ border on the cursor's row.
-          // The input area is "┃  <text>" — the ┃ is the anchor, offset 3 skips "┃  ".
-          // We use the cursor row (cursorY) to find the right line, then scan for ┃.
-          this._localEchoOverlay.setPrompt({
-            type: 'custom',
-            offset: 3,
-            find: (terminal) => {
-              try {
-                const buf = terminal.buffer.active;
-                const row = buf.cursorY;
-                const line = buf.getLine(buf.viewportY + row);
-                if (!line) return null;
-                const text = line.translateToString(true);
-                const idx = text.indexOf('\u2503'); // ┃ (BOX DRAWINGS HEAVY VERTICAL)
-                if (idx >= 0) return { row, col: idx };
-                return null;
-              } catch { return null; }
+    // Swap prompt finder based on session mode
+    if (this._localEchoOverlay && session) {
+      if (session.mode === 'opencode') {
+        // OpenCode (Bubble Tea TUI): find the ┃ border on the cursor's row.
+        // The input area is "┃  <text>" — the ┃ is the anchor, offset 3 skips "┃  ".
+        // We use the cursor row (cursorY) to find the right line, then scan for ┃.
+        this._localEchoOverlay.setPrompt({
+          type: 'custom',
+          offset: 3,
+          find: (terminal) => {
+            try {
+              const buf = terminal.buffer.active;
+              const row = buf.cursorY;
+              const line = buf.getLine(buf.viewportY + row);
+              if (!line) return null;
+              const text = line.translateToString(true);
+              const idx = text.indexOf('\u2503'); // ┃ (BOX DRAWINGS HEAVY VERTICAL)
+              if (idx >= 0) return { row, col: idx };
+              return null;
+            } catch {
+              return null;
             }
-          });
-        } else if (session.mode === 'shell') {
-          // Shell mode: the shell provides its own PTY echo so the overlay isn't needed.
-          // Disable it by clearing any pending text.
-          this._localEchoOverlay.clear();
-          this._localEchoEnabled = false;
-        } else {
-          // Claude Code: scan for ❯ prompt character
-          this._localEchoOverlay.setPrompt({ type: 'character', char: '\u276f', offset: 2 });
-        }
+          },
+        });
+      } else if (session.mode === 'shell') {
+        // Shell mode: the shell provides its own PTY echo so the overlay isn't needed.
+        // Disable it by clearing any pending text.
+        this._localEchoOverlay.clear();
+        this._localEchoEnabled = false;
+      } else {
+        // Claude Code: scan for ❯ prompt character
+        this._localEchoOverlay.setPrompt({ type: 'character', char: '\u276f', offset: 2 });
       }
+    }
   },
 
   /**
@@ -950,7 +1034,7 @@ Object.assign(CodemanApp.prototype, {
     const joined = this.pendingWrites.join('');
     this.pendingWrites = [];
     const _joinedLen = joined.length;
-    if (_joinedLen > 16384) _crashDiag.log(`FLUSH: ${(_joinedLen/1024).toFixed(0)}KB`);
+    if (_joinedLen > 16384) _crashDiag.log(`FLUSH: ${(_joinedLen / 1024).toFixed(0)}KB`);
 
     // Per-frame byte budget to prevent main thread blocking.
     // Large writes (141KB+) can freeze Chrome for 2+ minutes.
@@ -974,7 +1058,10 @@ Object.assign(CodemanApp.prototype, {
     }
     const bytesThisFrame = deferred ? MAX_FRAME_BYTES : _joinedLen;
     const _dt = performance.now() - _t0;
-    if (_dt > 100 || deferred) console.warn(`[CRASH-DIAG] flushPendingWrites: ${_dt.toFixed(0)}ms, ${(bytesThisFrame/1024).toFixed(0)}KB written${deferred ? ', rest deferred' : ''} (total ${(_joinedLen/1024).toFixed(0)}KB)`);
+    if (_dt > 100 || deferred)
+      console.warn(
+        `[CRASH-DIAG] flushPendingWrites: ${_dt.toFixed(0)}ms, ${(bytesThisFrame / 1024).toFixed(0)}KB written${deferred ? ', rest deferred' : ''} (total ${(_joinedLen / 1024).toFixed(0)}KB)`
+      );
 
     // Sticky scroll: if user was at bottom, keep them there after new output
     if (this._wasAtBottomBeforeWrite) {
@@ -991,8 +1078,12 @@ Object.assign(CodemanApp.prototype, {
     // Use terminal.write('', callback) to defer detection until xterm.js
     // finishes processing ALL queued writes — direct buffer reads after
     // terminal.write(data) can miss text if xterm processes asynchronously.
-    if (this._tabCompletionSessionId && this._tabCompletionSessionId === this.activeSessionId
-        && this._localEchoOverlay && !this._localEchoOverlay.pendingText) {
+    if (
+      this._tabCompletionSessionId &&
+      this._tabCompletionSessionId === this.activeSessionId &&
+      this._localEchoOverlay &&
+      !this._localEchoOverlay.pendingText
+    ) {
       const overlay = this._localEchoOverlay;
       const self = this;
       this.terminal.write('', () => {
@@ -1013,7 +1104,10 @@ Object.assign(CodemanApp.prototype, {
             self._tabCompletionSessionId = null;
             self._tabCompletionRetries = 0;
             self._tabCompletionBaseText = null;
-            if (self._tabCompletionFallback) { clearTimeout(self._tabCompletionFallback); self._tabCompletionFallback = null; }
+            if (self._tabCompletionFallback) {
+              clearTimeout(self._tabCompletionFallback);
+              self._tabCompletionFallback = null;
+            }
             overlay.rerender();
           }
         } else {
@@ -1085,7 +1179,9 @@ Object.assign(CodemanApp.prototype, {
 
         if (offset >= cleanBuffer.length) {
           const _totalMs = performance.now() - _chunkStart;
-          console.log(`[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`);
+          console.log(
+            `[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`
+          );
           // Wait one more frame for xterm to finish rendering before resolving
           requestAnimationFrame(finish);
           return;
@@ -1096,7 +1192,10 @@ Object.assign(CodemanApp.prototype, {
         this.terminal.write(chunk);
         const _cdt = performance.now() - _ct0;
         _chunkCount++;
-        if (_cdt > 50) console.warn(`[CRASH-DIAG] chunk #${_chunkCount} write took ${_cdt.toFixed(0)}ms (${chunk.length} bytes at offset ${offset})`);
+        if (_cdt > 50)
+          console.warn(
+            `[CRASH-DIAG] chunk #${_chunkCount} write took ${_cdt.toFixed(0)}ms (${chunk.length} bytes at offset ${offset})`
+          );
         offset += chunkSize;
 
         // Schedule next chunk on next frame
@@ -1109,21 +1208,20 @@ Object.assign(CodemanApp.prototype, {
   },
 
   /**
-   * Complete a buffer load: unblock live SSE writes and flush any queued events.
+   * Complete a buffer load: unblock live SSE writes.
    * Called when chunkedTerminalWrite finishes (or is skipped for empty buffers).
+   *
+   * Queued SSE events are DISCARDED, not flushed. The loaded buffer from the API
+   * is the source of truth up to the response timestamp. SSE events queued during
+   * the fetch+write overlap with the buffer — flushing them writes duplicate data
+   * (especially Ink cursor-up redraws), corrupting the terminal display.
+   * After unblocking, new SSE/WS events deliver subsequent output normally.
    */
   _finishBufferLoad() {
-    const queue = this._loadBufferQueue;
     this._isLoadingBuffer = false;
     this._loadBufferQueue = null;
-    if (queue && queue.length > 0) {
-      for (const data of queue) {
-        this.batchTerminalWrite(data);
-      }
-    }
   },
 
-
   // ═══════════════════════════════════════════════════════════════
   // Terminal Controls
   // ═══════════════════════════════════════════════════════════════
@@ -1157,7 +1255,7 @@ Object.assign(CodemanApp.prototype, {
       await fetch(`/api/sessions/${this.activeSessionId}/input`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ input: '\x0c' })
+        body: JSON.stringify({ input: '\x0c' }),
       });
 
       this.showToast(`Terminal restored to ${dims.cols}x${dims.rows}`, 'success');
@@ -1184,7 +1282,7 @@ Object.assign(CodemanApp.prototype, {
       fetch(`/api/sessions/${sessionId}/input`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ input: '\x0c' })
+        body: JSON.stringify({ input: '\x0c' }),
       });
     });
   },
@@ -1246,7 +1344,7 @@ Object.assign(CodemanApp.prototype, {
     if (!dims) return null;
     return {
       cols: Math.max(dims.cols, MIN_COLS),
-      rows: Math.max(dims.rows, MIN_ROWS)
+      rows: Math.max(dims.rows, MIN_ROWS),
     };
   },
 
@@ -1261,6 +1359,10 @@ Object.assign(CodemanApp.prototype, {
     if (this.fitAddon) this.fitAddon.fit();
     const dims = this.getTerminalDimensions();
     if (!dims) return;
+    // Update _lastResizeDims so the throttledResize handler won't redundantly
+    // clear the terminal for the same dimensions (which would blank the screen
+    // without a subsequent Ink redraw to repaint it).
+    this._lastResizeDims = { cols: dims.cols, rows: dims.rows };
     // Fast path: WebSocket resize
     if (this._wsReady && this._wsSessionId === sessionId) {
       try {
@@ -1273,7 +1375,7 @@ Object.assign(CodemanApp.prototype, {
     await fetch(`/api/sessions/${sessionId}/resize`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(dims)
+      body: JSON.stringify(dims),
     });
   },
 
@@ -1287,11 +1389,10 @@ Object.assign(CodemanApp.prototype, {
     await fetch(`/api/sessions/${this.activeSessionId}/input`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ input, useMux: true })
+      body: JSON.stringify({ input, useMux: true }),
     });
   },
 
-
   // ═══════════════════════════════════════════════════════════════
   // Directory Input
   // ═══════════════════════════════════════════════════════════════

src/web/respawn-event-wiring.ts

@@ -0,0 +1,360 @@
+/**
+ * @fileoverview Respawn event wiring — pure functions that connect RespawnController
+ * events to SSE broadcasts, push notifications, and run summary tracking.
+ *
+ * Extracted from WebServer to keep respawn-specific event plumbing separate from
+ * HTTP/session concerns. Follows the same DI pattern as session-listener-wiring.ts.
+ */
+
+import { Session } from '../session.js';
+import { RespawnController, RespawnConfig, RespawnState } from '../respawn-controller.js';
+import type { PersistedRespawnConfig } from '../types.js';
+import type { RunSummaryTracker } from '../run-summary.js';
+import type { TerminalMultiplexer } from '../mux-interface.js';
+import type { TeamWatcher } from '../team-watcher.js';
+import { SseEvent } from './sse-events.js';
+
+// ============================================================================
+// Dependency Interface
+// ============================================================================
+
+export interface RespawnWiringDeps {
+  broadcast(event: string, data: unknown): void;
+  sendPushNotifications(event: string, data: Record<string, unknown>): void;
+  persistSessionState(session: Session): void;
+  getSession(sessionId: string): Session | undefined;
+  sessionExists(sessionId: string): boolean;
+  getRunSummaryTracker(sessionId: string): RunSummaryTracker | undefined;
+  getRespawnControllers(): Map<string, RespawnController>;
+  getRespawnTimers(): Map<string, { timer: NodeJS.Timeout; endAt: number; startedAt: number }>;
+  getPendingRespawnStarts(): Map<string, NodeJS.Timeout>;
+  teamWatcher: TeamWatcher;
+  serverStartTime: number;
+  respawnRestoreGracePeriodMs: number;
+  mux: TerminalMultiplexer;
+}
+
+// ============================================================================
+// Respawn Listener Wiring
+// ============================================================================
+
+/**
+ * Wire a RespawnController's events to SSE broadcasts, push notifications,
+ * and run summary tracking.
+ */
+export function wireRespawnListeners(sessionId: string, controller: RespawnController, deps: RespawnWiringDeps): void {
+  // Wire team watcher for team-aware idle detection
+  controller.setTeamWatcher(deps.teamWatcher);
+
+  // Helper to get tracker lazily (may not exist at setup time for restored sessions)
+  const getTracker = () => deps.getRunSummaryTracker(sessionId);
+
+  // ─── Respawn State Machine ──────────────────────────────
+
+  /** Broadcasts `respawn:stateChanged` — state machine transition (e.g., IDLE → DETECTING → RESPAWNING) */
+  controller.on('stateChanged', (state: RespawnState, prevState: RespawnState) => {
+    deps.broadcast(SseEvent.RespawnStateChanged, { sessionId, state, prevState });
+    const tracker = getTracker();
+    if (tracker) tracker.recordStateChange(state, `${prevState} → ${state}`);
+  });
+
+  // ─── Respawn Cycle Lifecycle ────────────────────────────
+
+  /** Broadcasts `respawn:cycleStarted` — new respawn cycle begins */
+  controller.on('respawnCycleStarted', (cycleNumber: number) => {
+    deps.broadcast(SseEvent.RespawnCycleStarted, { sessionId, cycleNumber });
+  });
+
+  /** Broadcasts `respawn:cycleCompleted` — respawn cycle finished */
+  controller.on('respawnCycleCompleted', (cycleNumber: number) => {
+    deps.broadcast(SseEvent.RespawnCycleCompleted, { sessionId, cycleNumber });
+  });
+
+  /** Broadcasts `respawn:blocked` + push notification — respawn blocked by error/circuit breaker */
+  controller.on('respawnBlocked', (data: { reason: string; details: string }) => {
+    deps.broadcast(SseEvent.RespawnBlocked, { sessionId, reason: data.reason, details: data.details });
+    const sessionForPush = deps.getSession(sessionId);
+    deps.sendPushNotifications(SseEvent.RespawnBlocked, {
+      sessionId,
+      sessionName: sessionForPush?.name ?? sessionId.slice(0, 8),
+      reason: data.reason,
+    });
+    const tracker = getTracker();
+    if (tracker) tracker.recordWarning(`Respawn blocked: ${data.reason}`, data.details);
+  });
+
+  // ─── Respawn Step Progress ──────────────────────────────
+
+  /** Broadcasts `respawn:stepSent` — respawn step input sent (e.g., /clear, kickstart prompt) */
+  controller.on('stepSent', (step: string, input: string) => {
+    deps.broadcast(SseEvent.RespawnStepSent, { sessionId, step, input });
+  });
+
+  /** Broadcasts `respawn:stepCompleted` — respawn step finished */
+  controller.on('stepCompleted', (step: string) => {
+    deps.broadcast(SseEvent.RespawnStepCompleted, { sessionId, step });
+  });
+
+  /** Broadcasts `respawn:detectionUpdate` — idle/completion detection state changed */
+  controller.on('detectionUpdate', (detection: unknown) => {
+    deps.broadcast(SseEvent.RespawnDetectionUpdate, { sessionId, detection });
+  });
+
+  /** Broadcasts `respawn:autoAcceptSent` — auto-accepted a permission prompt */
+  controller.on('autoAcceptSent', () => {
+    deps.broadcast(SseEvent.RespawnAutoAcceptSent, { sessionId });
+  });
+
+  // ─── AI Checker Events ──────────────────────────────────
+
+  /** Broadcasts `respawn:aiCheckStarted` — AI idle checker invoked */
+  controller.on('aiCheckStarted', () => {
+    deps.broadcast(SseEvent.RespawnAiCheckStarted, { sessionId });
+  });
+
+  /** Broadcasts `respawn:aiCheckCompleted` — AI idle check returned verdict (idle/working/stuck) */
+  controller.on('aiCheckCompleted', (result: { verdict: string; reasoning: string; durationMs: number }) => {
+    deps.broadcast(SseEvent.RespawnAiCheckCompleted, {
+      sessionId,
+      verdict: result.verdict,
+      reasoning: result.reasoning,
+      durationMs: result.durationMs,
+    });
+    const tracker = getTracker();
+    if (tracker) tracker.recordAiCheckResult(result.verdict);
+  });
+
+  /** Broadcasts `respawn:aiCheckFailed` — AI idle check errored */
+  controller.on('aiCheckFailed', (error: string) => {
+    deps.broadcast(SseEvent.RespawnAiCheckFailed, { sessionId, error });
+    const tracker = getTracker();
+    if (tracker) tracker.recordError('AI check failed', error);
+  });
+
+  /** Broadcasts `respawn:aiCheckCooldown` — AI check on cooldown after failure */
+  controller.on('aiCheckCooldown', (active: boolean, endsAt: number | null) => {
+    deps.broadcast(SseEvent.RespawnAiCheckCooldown, { sessionId, active, endsAt });
+  });
+
+  // ─── Plan Checker Events ────────────────────────────────
+
+  /** Broadcasts `respawn:planCheckStarted` — AI plan completion checker invoked */
+  controller.on('planCheckStarted', () => {
+    deps.broadcast(SseEvent.RespawnPlanCheckStarted, { sessionId });
+  });
+
+  /** Broadcasts `respawn:planCheckCompleted` — plan check returned verdict */
+  controller.on('planCheckCompleted', (result: { verdict: string; reasoning: string; durationMs: number }) => {
+    deps.broadcast(SseEvent.RespawnPlanCheckCompleted, {
+      sessionId,
+      verdict: result.verdict,
+      reasoning: result.reasoning,
+      durationMs: result.durationMs,
+    });
+  });
+
+  /** Broadcasts `respawn:planCheckFailed` — plan check errored */
+  controller.on('planCheckFailed', (error: string) => {
+    deps.broadcast(SseEvent.RespawnPlanCheckFailed, { sessionId, error });
+  });
+
+  // ─── Timer Events (UI countdown display) ────────────────
+
+  /** Broadcasts `respawn:timerStarted` — countdown timer started (idle, cooldown, etc.) */
+  controller.on('timerStarted', (timer) => {
+    deps.broadcast(SseEvent.RespawnTimerStarted, { sessionId, timer });
+  });
+
+  /** Broadcasts `respawn:timerCancelled` — timer cancelled before expiry */
+  controller.on('timerCancelled', (timerName, reason) => {
+    deps.broadcast(SseEvent.RespawnTimerCancelled, { sessionId, timerName, reason });
+  });
+
+  /** Broadcasts `respawn:timerCompleted` — timer expired */
+  controller.on('timerCompleted', (timerName) => {
+    deps.broadcast(SseEvent.RespawnTimerCompleted, { sessionId, timerName });
+  });
+
+  // ─── Logging & Errors ───────────────────────────────────
+
+  /** Broadcasts `respawn:actionLog` — respawn action logged for audit/debugging */
+  controller.on('actionLog', (action) => {
+    deps.broadcast(SseEvent.RespawnActionLog, { sessionId, action });
+  });
+
+  /** Broadcasts `respawn:log` — general respawn log message */
+  controller.on('log', (message: string) => {
+    deps.broadcast(SseEvent.RespawnLog, { sessionId, message });
+  });
+
+  /** Broadcasts `respawn:error` — respawn controller error */
+  controller.on('error', (error: Error) => {
+    deps.broadcast(SseEvent.RespawnError, { sessionId, error: error.message });
+    const tracker = getTracker();
+    if (tracker) tracker.recordError('Respawn error', error.message);
+  });
+}
+
+// ============================================================================
+// Timed Respawn
+// ============================================================================
+
+/**
+ * Set up a duration-limited respawn timer that stops respawn after N minutes.
+ */
+export function setupTimedRespawn(sessionId: string, durationMinutes: number, deps: RespawnWiringDeps): void {
+  const timers = deps.getRespawnTimers();
+
+  // Clear existing timer if any
+  const existing = timers.get(sessionId);
+  if (existing) {
+    clearTimeout(existing.timer);
+  }
+
+  const now = Date.now();
+  const endAt = now + durationMinutes * 60 * 1000;
+
+  const timer = setTimeout(
+    () => {
+      // Stop respawn when time is up
+      const controllers = deps.getRespawnControllers();
+      const controller = controllers.get(sessionId);
+      if (controller) {
+        controller.stop();
+        controller.removeAllListeners();
+        controllers.delete(sessionId);
+        deps.broadcast(SseEvent.RespawnStopped, { sessionId, reason: 'duration_expired' });
+      }
+      timers.delete(sessionId);
+      // Update persisted state (respawn no longer active)
+      const session = deps.getSession(sessionId);
+      if (session) {
+        deps.persistSessionState(session);
+      }
+    },
+    durationMinutes * 60 * 1000
+  );
+
+  timers.set(sessionId, { timer, endAt, startedAt: now });
+  deps.broadcast(SseEvent.RespawnTimerStarted, { sessionId, durationMinutes, endAt, startedAt: now });
+}
+
+// ============================================================================
+// Respawn Controller Restore
+// ============================================================================
+
+/**
+ * Restore a RespawnController from persisted configuration.
+ * Creates the controller, wires listeners, and starts after a grace period.
+ */
+export function restoreRespawnController(
+  session: Session,
+  config: PersistedRespawnConfig,
+  source: string,
+  deps: RespawnWiringDeps
+): void {
+  const controller = new RespawnController(session, {
+    idleTimeoutMs: config.idleTimeoutMs,
+    updatePrompt: config.updatePrompt,
+    interStepDelayMs: config.interStepDelayMs,
+    enabled: true,
+    sendClear: config.sendClear,
+    sendInit: config.sendInit,
+    kickstartPrompt: config.kickstartPrompt,
+    completionConfirmMs: config.completionConfirmMs,
+    noOutputTimeoutMs: config.noOutputTimeoutMs,
+    autoAcceptPrompts: config.autoAcceptPrompts,
+    autoAcceptDelayMs: config.autoAcceptDelayMs,
+    aiIdleCheckEnabled: config.aiIdleCheckEnabled,
+    aiIdleCheckModel: config.aiIdleCheckModel,
+    aiIdleCheckMaxContext: config.aiIdleCheckMaxContext,
+    aiIdleCheckTimeoutMs: config.aiIdleCheckTimeoutMs,
+    aiIdleCheckCooldownMs: config.aiIdleCheckCooldownMs,
+    aiPlanCheckEnabled: config.aiPlanCheckEnabled,
+    aiPlanCheckModel: config.aiPlanCheckModel,
+    aiPlanCheckMaxContext: config.aiPlanCheckMaxContext,
+    aiPlanCheckTimeoutMs: config.aiPlanCheckTimeoutMs,
+    aiPlanCheckCooldownMs: config.aiPlanCheckCooldownMs,
+  });
+
+  const controllers = deps.getRespawnControllers();
+  controllers.set(session.id, controller);
+  wireRespawnListeners(session.id, controller, deps);
+
+  // Calculate delay: wait until grace period after server start before starting respawn
+  // This prevents false idle detection immediately after a server restart/rebuild
+  const timeSinceStart = Date.now() - deps.serverStartTime;
+  const delayMs = Math.max(0, deps.respawnRestoreGracePeriodMs - timeSinceStart);
+
+  const pendingStarts = deps.getPendingRespawnStarts();
+
+  if (delayMs > 0) {
+    console.log(
+      `[Server] Restored respawn controller for session ${session.id} from ${source} (will start in ${Math.ceil(delayMs / 1000)}s)`
+    );
+    const delayTimer = setTimeout(() => {
+      pendingStarts.delete(session.id);
+      // Verify session still exists (may have been deleted during grace period)
+      if (!deps.sessionExists(session.id)) {
+        console.log(`[Server] Skipping restored respawn start - session ${session.id} no longer exists`);
+        return;
+      }
+      // Double-check controller still exists and is stopped
+      const ctrl = controllers.get(session.id);
+      if (ctrl && ctrl.state === 'stopped') {
+        ctrl.start();
+        deps.broadcast(SseEvent.RespawnStarted, { sessionId: session.id });
+        console.log(`[Server] Restored respawn controller started for session ${session.id}`);
+      }
+    }, delayMs);
+    pendingStarts.set(session.id, delayTimer);
+  } else {
+    // Grace period has passed, start immediately
+    controller.start();
+    console.log(`[Server] Restored respawn controller for session ${session.id} from ${source} (started immediately)`);
+  }
+
+  if (config.durationMinutes && config.durationMinutes > 0) {
+    setupTimedRespawn(session.id, config.durationMinutes, deps);
+  }
+}
+
+// ============================================================================
+// Respawn Config Persistence
+// ============================================================================
+
+/**
+ * Save respawn config to mux for restart recovery.
+ */
+export function saveRespawnConfig(
+  sessionId: string,
+  config: RespawnConfig,
+  mux: TerminalMultiplexer,
+  durationMinutes?: number
+): void {
+  const persistedConfig: PersistedRespawnConfig = {
+    enabled: config.enabled,
+    idleTimeoutMs: config.idleTimeoutMs,
+    updatePrompt: config.updatePrompt,
+    interStepDelayMs: config.interStepDelayMs,
+    sendClear: config.sendClear,
+    sendInit: config.sendInit,
+    kickstartPrompt: config.kickstartPrompt,
+    autoAcceptPrompts: config.autoAcceptPrompts,
+    autoAcceptDelayMs: config.autoAcceptDelayMs,
+    completionConfirmMs: config.completionConfirmMs,
+    noOutputTimeoutMs: config.noOutputTimeoutMs,
+    aiIdleCheckEnabled: config.aiIdleCheckEnabled,
+    aiIdleCheckModel: config.aiIdleCheckModel,
+    aiIdleCheckMaxContext: config.aiIdleCheckMaxContext,
+    aiIdleCheckTimeoutMs: config.aiIdleCheckTimeoutMs,
+    aiIdleCheckCooldownMs: config.aiIdleCheckCooldownMs,
+    aiPlanCheckEnabled: config.aiPlanCheckEnabled,
+    aiPlanCheckModel: config.aiPlanCheckModel,
+    aiPlanCheckMaxContext: config.aiPlanCheckMaxContext,
+    aiPlanCheckTimeoutMs: config.aiPlanCheckTimeoutMs,
+    aiPlanCheckCooldownMs: config.aiPlanCheckCooldownMs,
+    durationMinutes,
+  };
+  mux.updateRespawnConfig(sessionId, persistedConfig);
+}

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").
  */
@@ -118,6 +185,26 @@ export function sanitizeHookData(data: Record<string, unknown> | null | undefine
   return safeFields;
 }
 
+/**
+ * Toggles a service (watcher/manager) on or off based on an enabled flag.
+ * Logs start/stop to console with the given label. Runs an optional callback after starting.
+ */
+export function toggleService(
+  enabled: boolean,
+  service: { isRunning(): boolean; start(): void; stop(): void },
+  label: string,
+  onStart?: () => void
+): void {
+  if (enabled && !service.isRunning()) {
+    service.start();
+    onStart?.();
+    console.log(`${label} started via settings change`);
+  } else if (!enabled && service.isRunning()) {
+    service.stop();
+    console.log(`${label} stopped via settings change`);
+  }
+}
+
 /**
  * Auto-configure Ralph tracker for a session.
  *

src/web/routes/case-routes.ts

@@ -11,26 +11,19 @@ import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import type { ApiResponse, CaseInfo } from '../../types.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.js';
-import { CreateCaseSchema, LinkCaseSchema } from '../schemas.js';
+import { CreateCaseSchema, LinkCaseSchema, CaseOrderSchema } 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, SETTINGS_PATH, 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');
+const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;
 
 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
 async function readLinkedCases(): Promise<Record<string, string>> {
-  try {
-    return JSON.parse(await fs.readFile(LINKED_CASES_FILE, 'utf-8'));
-  } catch (err) {
-    // Only warn on real I/O errors, not ENOENT (file missing) or SyntaxError (corrupted JSON)
-    if ((err as NodeJS.ErrnoException).code && (err as NodeJS.ErrnoException).code !== 'ENOENT') {
-      console.warn('[Server] Failed to read linked cases:', err);
-    }
-    return {};
-  }
+  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. */
@@ -54,7 +47,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     try {
       const entries = await fs.readdir(CASES_DIR, { withFileTypes: true });
       for (const e of entries) {
-        if (e.isDirectory()) {
+        if (e.isDirectory() && SAFE_CASE_NAME.test(e.name)) {
           cases.push({
             name: e.name,
             path: join(CASES_DIR, e.name),
@@ -70,7 +63,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     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)) {
+      if (!existingNames.has(name) && SAFE_CASE_NAME.test(name) && existsSync(path)) {
         cases.push({
           name,
           path,
@@ -79,15 +72,23 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       }
     }
 
+    // Sort by persisted caseOrder from settings.json
+    const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'settings', {});
+    const caseOrder = Array.isArray(settings.caseOrder) ? (settings.caseOrder as string[]) : [];
+    if (caseOrder.length > 0) {
+      const orderMap = new Map(caseOrder.map((name, idx) => [name, idx]));
+      cases.sort((a, b) => {
+        const ai = orderMap.get(a.name) ?? Number.MAX_SAFE_INTEGER;
+        const bi = orderMap.get(b.name) ?? Number.MAX_SAFE_INTEGER;
+        return ai - bi;
+      });
+    }
+
     return cases;
   });
 
   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) {
@@ -120,11 +121,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;
@@ -166,6 +163,68 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
     }
   });
 
+  // ========== Delete / Unlink Case ==========
+
+  app.delete('/api/cases/:name', async (req): Promise<ApiResponse<{ name: string }>> => {
+    const { name } = req.params as { name: string };
+
+    if (!validatePathWithinBase(name, CASES_DIR)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case name');
+    }
+
+    // Check linked cases first — unlink only, don't delete the actual directory
+    const linkedCases = await readLinkedCases();
+    if (linkedCases[name]) {
+      delete linkedCases[name];
+      try {
+        await fs.writeFile(LINKED_CASES_FILE, JSON.stringify(linkedCases, null, 2));
+        ctx.broadcast(SseEvent.CaseDeleted, { name, type: 'unlinked' });
+        return { success: true, data: { name } };
+      } catch (err) {
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
+      }
+    }
+
+    // Case in CASES_DIR — delete the entire directory
+    const casePath = join(CASES_DIR, name);
+    if (!existsSync(casePath)) {
+      return createErrorResponse(ApiErrorCode.NOT_FOUND, `Case "${name}" not found`);
+    }
+
+    try {
+      await fs.rm(casePath, { recursive: true, force: true });
+      ctx.broadcast(SseEvent.CaseDeleted, { name, type: 'deleted' });
+      return { success: true, data: { name } };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
+    }
+  });
+
+  // ========== Reorder Cases ==========
+
+  app.put('/api/cases/order', async (req): Promise<ApiResponse<{ order: string[] }>> => {
+    const { order } = parseBody(CaseOrderSchema, req.body, 'Invalid order data');
+
+    try {
+      const dir = join(homedir(), '.codeman');
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      let existing: Record<string, unknown> = {};
+      try {
+        existing = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf-8'));
+      } catch {
+        /* ignore */
+      }
+      const merged = { ...existing, caseOrder: order };
+      await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2));
+      ctx.broadcast(SseEvent.CaseOrderChanged, { order });
+      return { success: true, data: { order } };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
+    }
+  });
+
   app.get('/api/cases/:name', async (req) => {
     const { name } = req.params as { name: string };
 

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/orchestrator-routes.ts

@@ -19,6 +19,7 @@
 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';
 
@@ -38,43 +39,37 @@ export function registerOrchestratorRoutes(app: FastifyInstance, ctx: Orchestrat
     return loop;
   }
 
+  const EVENT_MAP: [string, (typeof SseEvent)[keyof typeof SseEvent], string[]][] = [
+    ['stateChanged', SseEvent.OrchestratorStateChanged, ['state', 'prevState']],
+    ['planProgress', SseEvent.OrchestratorPlanProgress, ['phase', 'detail']],
+    ['planReady', SseEvent.OrchestratorPlanReady, ['plan']],
+    ['phaseStarted', SseEvent.OrchestratorPhaseStarted, ['phase']],
+    ['phaseCompleted', SseEvent.OrchestratorPhaseCompleted, ['phase']],
+    ['phaseFailed', SseEvent.OrchestratorPhaseFailed, ['phase', 'reason']],
+    ['taskAssigned', SseEvent.OrchestratorTaskAssigned, ['task', 'sessionId']],
+    ['taskCompleted', SseEvent.OrchestratorTaskCompleted, ['task']],
+    ['taskFailed', SseEvent.OrchestratorTaskFailed, ['task', 'error']],
+    ['completed', SseEvent.OrchestratorCompleted, ['stats']],
+  ];
+
   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 });
-    });
+    for (const [event, sseEvent, argNames] of EVENT_MAP) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      loop.on(event, (...args: any[]) => {
+        const payload: Record<string, unknown> = {};
+        argNames.forEach((name, i) => {
+          payload[name] = args[i];
+        });
+        ctx.broadcast(sseEvent, payload);
+      });
+    }
+    // Special cases with non-trivial payload transforms
     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 });
     });
@@ -85,12 +80,7 @@ export function registerOrchestratorRoutes(app: FastifyInstance, ctx: Orchestrat
   // ═══════════════════════════════════════════════════════════════
 
   app.post('/api/orchestrator/start', async (req) => {
-    const parsed = OrchestratorStartSchema.safeParse(req.body);
-    if (!parsed.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-
-    const { goal, config } = parsed.data;
+    const { goal, config } = parseBody(OrchestratorStartSchema, req.body, 'Invalid request body');
 
     // Initialize loop if needed
     let loop = ctx.orchestratorLoop;
@@ -141,13 +131,10 @@ export function registerOrchestratorRoutes(app: FastifyInstance, ctx: Orchestrat
   app.post('/api/orchestrator/reject', async (req) => {
     const loop = getLoop();
 
-    const parsed = OrchestratorRejectSchema.safeParse(req.body);
-    if (!parsed.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Feedback is required');
-    }
+    const { feedback } = parseBody(OrchestratorRejectSchema, req.body, 'Feedback is required');
 
     try {
-      loop.reject(parsed.data.feedback).catch((err) => {
+      loop.reject(feedback).catch((err) => {
         console.error('[Orchestrator Route] Reject failed:', getErrorMessage(err));
       });
       return { ok: true, state: loop.state };

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);
 
@@ -349,7 +308,7 @@ export function registerRalphRoutes(
       useMux: true,
       mode: 'claude',
       niceConfig,
-      model: rlModelConfig?.defaultModel,
+      model: rlModelConfig?.defaultModel || undefined,
       claudeMode: rlClaudeModeConfig.claudeMode,
       allowedTools: rlClaudeModeConfig.allowedTools,
     });

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,9 +32,17 @@ 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 { writeHooksConfig, updateCaseEnvVars, updateCaseModel } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
@@ -138,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
@@ -162,6 +166,11 @@ export function registerSessionRoutes(
       await updateCaseEnvVars(workingDir, body.envOverrides);
     }
 
+    // Write model override to .claude/settings.local.json if provided
+    if (body.modelOverride !== undefined) {
+      await updateCaseModel(workingDir, body.modelOverride || null);
+    }
+
     // Check OpenCode availability if requested
     if (body.mode === 'opencode') {
       const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
@@ -177,7 +186,11 @@ export function registerSessionRoutes(
     const modelConfig = await ctx.getModelConfig();
     const mode = body.mode || 'claude';
     const model =
-      mode === 'opencode' ? body.openCodeConfig?.model : mode !== 'shell' ? modelConfig?.defaultModel : undefined;
+      mode === 'opencode'
+        ? body.openCodeConfig?.model
+        : mode !== 'shell'
+          ? modelConfig?.defaultModel || undefined
+          : undefined;
     const claudeModeConfig = await ctx.getClaudeModeConfig();
     const session = new Session({
       workingDir,
@@ -210,23 +223,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 };
   });
 
@@ -234,16 +238,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)) {
@@ -251,8 +247,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 };
   });
 
@@ -291,11 +286,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).
@@ -310,11 +301,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,
@@ -330,11 +317,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,
@@ -350,11 +333,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) {
@@ -374,11 +353,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,
@@ -396,16 +371,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');
@@ -424,11 +391,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');
@@ -468,11 +431,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');
@@ -502,16 +461,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) {
@@ -547,16 +498,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 };
@@ -569,11 +512,7 @@ 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;
@@ -632,20 +571,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,
@@ -662,20 +592,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,
@@ -693,16 +614,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);
@@ -726,20 +639,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,
@@ -764,11 +668,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');
@@ -824,11 +724,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') {
@@ -874,7 +770,11 @@ export function registerSessionRoutes(
     const niceConfig = await ctx.getGlobalNiceConfig();
     const qsModelConfig = await ctx.getModelConfig();
     const qsModel =
-      mode === 'opencode' ? openCodeConfig?.model : mode !== 'shell' ? qsModelConfig?.defaultModel : undefined;
+      mode === 'opencode'
+        ? openCodeConfig?.model
+        : mode !== 'shell'
+          ? qsModelConfig?.defaultModel || undefined
+          : undefined;
     const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
     const session = new Session({
       workingDir: casePath,

src/web/routes/system-routes.ts

@@ -24,7 +24,14 @@ 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,
+  toggleService,
+  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';
@@ -281,15 +288,20 @@ export function registerSystemRoutes(
 
   // ========== Stats ==========
 
-  app.get('/api/stats', async () => {
-    const activeSessionTokens: Record<string, { inputTokens?: number; outputTokens?: number; totalCost?: number }> = {};
+  function collectActiveTokens(): Record<string, { inputTokens?: number; outputTokens?: number; totalCost?: number }> {
+    const tokens: Record<string, { inputTokens?: number; outputTokens?: number; totalCost?: number }> = {};
     for (const [sessionId, session] of ctx.sessions) {
-      activeSessionTokens[sessionId] = {
+      tokens[sessionId] = {
         inputTokens: session.inputTokens,
         outputTokens: session.outputTokens,
         totalCost: session.totalCost,
       };
     }
+    return tokens;
+  }
+
+  app.get('/api/stats', async () => {
+    const activeSessionTokens = collectActiveTokens();
     return {
       success: true,
       stats: ctx.store.getAggregateStats(activeSessionTokens),
@@ -298,14 +310,7 @@ export function registerSystemRoutes(
   });
 
   app.get('/api/token-stats', async () => {
-    const activeSessionTokens: Record<string, { inputTokens?: number; outputTokens?: number; totalCost?: number }> = {};
-    for (const [sessionId, session] of ctx.sessions) {
-      activeSessionTokens[sessionId] = {
-        inputTokens: session.inputTokens,
-        outputTokens: session.outputTokens,
-        totalCost: session.totalCost,
-      };
-    }
+    const activeSessionTokens = collectActiveTokens();
     return {
       success: true,
       daily: ctx.store.getDailyStats(30),
@@ -324,11 +329,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 +398,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);
@@ -429,30 +419,17 @@ export function registerSystemRoutes(
       await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2));
 
       // Handle subagent tracking toggle dynamically
-      const subagentEnabled = settings.subagentTrackingEnabled ?? true;
-      if (subagentEnabled && !subagentWatcher.isRunning()) {
-        subagentWatcher.start();
-        console.log('Subagent watcher started via settings change');
-      } else if (!subagentEnabled && subagentWatcher.isRunning()) {
-        subagentWatcher.stop();
-        console.log('Subagent watcher stopped via settings change');
-      }
+      toggleService((settings.subagentTrackingEnabled as boolean) ?? true, subagentWatcher, 'Subagent watcher');
 
       // Handle image watcher toggle dynamically
-      const imageWatcherEnabled = settings.imageWatcherEnabled ?? false;
-      if (imageWatcherEnabled && !imageWatcher.isRunning()) {
-        imageWatcher.start();
+      toggleService((settings.imageWatcherEnabled as boolean) ?? false, imageWatcher, 'Image watcher', () => {
         // Re-watch all active sessions that have image watcher enabled
         for (const session of ctx.sessions.values()) {
           if (session.imageWatcherEnabled) {
             imageWatcher.watchSession(session.id, session.workingDir);
           }
         }
-        console.log('Image watcher started via settings change');
-      } else if (!imageWatcherEnabled && imageWatcher.isRunning()) {
-        imageWatcher.stop();
-        console.log('Image watcher stopped via settings change');
-      }
+      });
 
       // Handle tunnel toggle dynamically
       if ('tunnelEnabled' in settings) {
@@ -479,24 +456,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 +501,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 +521,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 +541,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)) {

src/web/schemas.ts

@@ -124,6 +124,8 @@ export const CreateSessionSchema = z.object({
   mode: z.enum(['claude', 'shell', 'opencode']).optional(),
   name: z.string().max(100).optional(),
   envOverrides: safeEnvOverridesSchema,
+  /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
+  modelOverride: z.string().max(50).optional(),
   openCodeConfig: OpenCodeConfigSchema,
   /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
   resumeSessionId: z
@@ -429,6 +431,11 @@ export const LinkCaseSchema = z.object({
   path: safePathSchema,
 });
 
+/** PUT /api/cases/order */
+export const CaseOrderSchema = z.object({
+  order: z.array(z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format')),
+});
+
 /** POST /api/auth/revoke */
 export const RevokeSessionSchema = z.object({
   sessionToken: z.string().min(1).max(200).optional(),

src/web/session-listener-wiring.ts

@@ -0,0 +1,392 @@
+/**
+ * @fileoverview Session event listener wiring — creates, attaches, and detaches session listeners.
+ *
+ * Extracted from server.ts for modularity. Provides:
+ * - `SessionListenerRefs` interface (named listener references for leak-free cleanup)
+ * - `createSessionListeners()` — builds all 25 listener handlers via dependency injection
+ * - `attachSessionListeners()` / `detachSessionListeners()` — symmetric attach/detach
+ *
+ * The detach function deduplicates a pattern that was previously copy-pasted 3 times
+ * in server.ts (_doCleanupSession, exit handler, stop()).
+ *
+ * @dependencies session.ts (Session, event types), sse-events.ts, types.ts
+ * @consumedby web/server.ts (WebServer delegates listener lifecycle here)
+ *
+ * @module web/session-listener-wiring
+ */
+
+import type {
+  Session,
+  ClaudeMessage,
+  BackgroundTask,
+  RalphTrackerState,
+  RalphTodoItem,
+  ActiveBashTool,
+} from '../session.js';
+import type { RalphStatusBlock, CircuitBreakerStatus } from '../types.js';
+import { SseEvent } from './sse-events.js';
+import { getLifecycleLog } from '../session-lifecycle-log.js';
+import { fileStreamManager } from '../file-stream-manager.js';
+
+/** Stored listener references for session cleanup (prevents memory leaks) */
+export interface SessionListenerRefs {
+  terminal: (data: string) => void;
+  clearTerminal: () => void;
+  needsRefresh: () => void;
+  message: (msg: ClaudeMessage) => void;
+  error: (error: string) => void;
+  completion: (result: string, cost: number) => void;
+  exit: (code: number | null) => void;
+  working: () => void;
+  idle: () => void;
+  taskCreated: (task: BackgroundTask) => void;
+  taskUpdated: (task: BackgroundTask) => void;
+  taskCompleted: (task: BackgroundTask) => void;
+  taskFailed: (task: BackgroundTask, error: string) => void;
+  autoClear: (data: { tokens: number; threshold: number }) => void;
+  autoCompact: (data: { tokens: number; threshold: number; prompt?: string }) => void;
+  cliInfoUpdated: (data: { version?: string; model?: string; accountType?: string; latestVersion?: string }) => void;
+  ralphLoopUpdate: (state: RalphTrackerState) => void;
+  ralphTodoUpdate: (todos: RalphTodoItem[]) => void;
+  ralphCompletionDetected: (phrase: string) => void;
+  ralphStatusBlockDetected: (block: RalphStatusBlock) => void;
+  ralphCircuitBreakerUpdate: (status: CircuitBreakerStatus) => void;
+  ralphExitGateMet: (data: { completionIndicators: number; exitSignal: boolean }) => void;
+  bashToolStart: (tool: ActiveBashTool) => void;
+  bashToolEnd: (tool: ActiveBashTool) => void;
+  bashToolsUpdate: (tools: ActiveBashTool[]) => void;
+}
+
+/** Dependencies injected by WebServer — keeps listener creation decoupled from server internals. */
+export interface SessionListenerDeps {
+  broadcast(event: string, data: unknown): void;
+  batchTerminalData(sessionId: string, data: string): void;
+  batchTaskUpdate(sessionId: string, task: BackgroundTask): void;
+  broadcastSessionStateDebounced(sessionId: string): void;
+  sendPushNotifications(event: string, data: Record<string, unknown>): void;
+  persistSessionState(session: Session): void;
+  getSessionStateWithRespawn(session: Session): unknown;
+  getRunSummaryTracker(sessionId: string): import('../run-summary.js').RunSummaryTracker | undefined;
+  stopTranscriptWatcher(sessionId: string): void;
+  cleanupSessionBatches(sessionId: string): void;
+  cancelPersistDebounce(sessionId: string): void;
+  removeRunSummaryTracker(sessionId: string): void;
+  removeSessionListenerRefs(sessionId: string): void;
+  cleanupRespawnOnExit(sessionId: string): void;
+  getStore(): import('../state-store.js').StateStore;
+}
+
+/**
+ * Creates all 25 session listener handlers, capturing dependencies via closure.
+ * Call `attachSessionListeners()` after to wire them to the session.
+ */
+export function createSessionListeners(session: Session, deps: SessionListenerDeps): SessionListenerRefs {
+  return {
+    // ─── Terminal Output ─────────────────────────────────────
+
+    /** Batches PTY output → broadcasts `session:terminal` at 16-50ms intervals */
+    terminal: (data) => {
+      deps.batchTerminalData(session.id, data);
+    },
+
+    /** Broadcasts `session:clearTerminal` — tells clients to wipe their xterm buffer (after mux attach) */
+    clearTerminal: () => {
+      deps.broadcast(SseEvent.SessionClearTerminal, { id: session.id });
+    },
+
+    /** Broadcasts `session:needsRefresh` — tells clients to reload buffer */
+    needsRefresh: () => {
+      deps.broadcast(SseEvent.SessionNeedsRefresh, { id: session.id });
+    },
+
+    // ─── Session Messages & Errors ──────────────────────────
+
+    /** Broadcasts `session:message` — structured Claude JSON messages (assistant, tool_use, etc.) */
+    message: (msg: ClaudeMessage) => {
+      deps.broadcast(SseEvent.SessionMessage, { id: session.id, message: msg });
+    },
+
+    /** Broadcasts `session:error` + sends push notification */
+    error: (error) => {
+      deps.broadcast(SseEvent.SessionError, { id: session.id, error });
+      deps.sendPushNotifications(SseEvent.SessionError, {
+        sessionId: session.id,
+        sessionName: session.name,
+        error: String(error),
+      });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) tracker.recordError('Session error', String(error));
+    },
+
+    /** Broadcasts `session:completion` + `session:updated` — prompt finished, persists state */
+    completion: (result, cost) => {
+      deps.broadcast(SseEvent.SessionCompletion, { id: session.id, result, cost });
+      deps.broadcast(SseEvent.SessionUpdated, deps.getSessionStateWithRespawn(session));
+      deps.persistSessionState(session);
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) tracker.recordTokens(session.inputTokens, session.outputTokens);
+    },
+
+    // ─── Session Lifecycle ──────────────────────────────────
+
+    /** Broadcasts `session:exit` + `session:updated` — PTY process exited; cleans up respawn, timers, listeners */
+    exit: (code) => {
+      getLifecycleLog().log({
+        event: 'exit',
+        sessionId: session.id,
+        name: session.name,
+        exitCode: code,
+      });
+      // Wrap in try/catch to ensure cleanup always happens
+      try {
+        deps.broadcast(SseEvent.SessionExit, { id: session.id, code });
+        deps.broadcast(SseEvent.SessionUpdated, deps.getSessionStateWithRespawn(session));
+        deps.persistSessionState(session);
+      } catch (err) {
+        console.error(`[Server] Error broadcasting session exit for ${session.id}:`, err);
+      }
+
+      // Always clean up respawn controller, even if broadcast failed
+      try {
+        deps.cleanupRespawnOnExit(session.id);
+      } catch (err) {
+        console.error(`[Server] Error cleaning up respawn controller for ${session.id}:`, err);
+      }
+
+      // Clean up per-session resources that are stale after PTY exit.
+      try {
+        // Transcript watcher is tied to the specific PTY run
+        deps.stopTranscriptWatcher(session.id);
+
+        // Finalize run summary tracker
+        deps.removeRunSummaryTracker(session.id);
+
+        // Flush/clear terminal batching state (no more output coming)
+        deps.cleanupSessionBatches(session.id);
+
+        // Clear pending persist-debounce timer
+        deps.cancelPersistDebounce(session.id);
+
+        // Close any active file streams
+        fileStreamManager.closeSessionStreams(session.id);
+
+        // Remove stored listener refs to break closure references (prevents memory leak).
+        deps.removeSessionListenerRefs(session.id);
+      } catch (err) {
+        console.error(`[Server] Error cleaning up session resources on exit for ${session.id}:`, err);
+      }
+    },
+
+    // ─── Activity State ─────────────────────────────────────
+
+    /** Broadcasts `session:working` — Claude started processing */
+    working: () => {
+      deps.broadcast(SseEvent.SessionWorking, { id: session.id });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) {
+        tracker.recordWorking();
+        tracker.recordTokens(session.inputTokens, session.outputTokens);
+      }
+    },
+
+    /** Broadcasts `session:idle` — Claude finished processing, waiting for input */
+    idle: () => {
+      deps.broadcast(SseEvent.SessionIdle, { id: session.id });
+      deps.broadcastSessionStateDebounced(session.id);
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) {
+        tracker.recordIdle();
+        tracker.recordTokens(session.inputTokens, session.outputTokens);
+      }
+    },
+
+    // ─── Background Task Events ──────────────────────────────
+
+    /** Broadcasts `task:created` — new background task discovered */
+    taskCreated: (task: BackgroundTask) => {
+      deps.broadcast(SseEvent.TaskCreated, { sessionId: session.id, task });
+      deps.broadcastSessionStateDebounced(session.id);
+    },
+
+    /** Batched broadcast of `task:updated` — high-frequency progress updates */
+    taskUpdated: (task: BackgroundTask) => {
+      deps.batchTaskUpdate(session.id, task);
+    },
+
+    /** Broadcasts `task:completed` — background task finished successfully */
+    taskCompleted: (task: BackgroundTask) => {
+      deps.broadcast(SseEvent.TaskCompleted, { sessionId: session.id, task });
+      deps.broadcastSessionStateDebounced(session.id);
+    },
+
+    /** Broadcasts `task:failed` — background task errored */
+    taskFailed: (task: BackgroundTask, error: string) => {
+      deps.broadcast(SseEvent.TaskFailed, { sessionId: session.id, task, error });
+      deps.broadcastSessionStateDebounced(session.id);
+    },
+
+    // ─── Auto-Operations ────────────────────────────────────
+
+    /** Broadcasts `session:autoClear` — context window auto-cleared at token threshold */
+    autoClear: (data: { tokens: number; threshold: number }) => {
+      deps.broadcast(SseEvent.SessionAutoClear, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) tracker.recordAutoClear(data.tokens, data.threshold);
+    },
+
+    /** Broadcasts `session:autoCompact` — context window auto-compacted at token threshold */
+    autoCompact: (data: { tokens: number; threshold: number; prompt?: string }) => {
+      deps.broadcast(SseEvent.SessionAutoCompact, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) tracker.recordAutoCompact(data.tokens, data.threshold);
+    },
+
+    // ─── CLI Info ────────────────────────────────────────────
+
+    /** Broadcasts `session:cliInfo` — Claude Code version, model, account type parsed from terminal */
+    cliInfoUpdated: (data: { version?: string; model?: string; accountType?: string; latestVersion?: string }) => {
+      deps.broadcast(SseEvent.SessionCliInfo, { sessionId: session.id, ...data });
+      deps.broadcastSessionStateDebounced(session.id);
+    },
+
+    // ─── Ralph Tracking Events ──────────────────────────────
+
+    /** Broadcasts `session:ralphLoopUpdate` — Ralph tracker loop state changed (iteration, phase) */
+    ralphLoopUpdate: (state: RalphTrackerState) => {
+      deps.broadcast(SseEvent.SessionRalphLoopUpdate, { sessionId: session.id, state });
+      deps.getStore().updateRalphState(session.id, { loop: state });
+    },
+
+    /** Broadcasts `session:ralphTodoUpdate` — todo items added, completed, or modified */
+    ralphTodoUpdate: (todos: RalphTodoItem[]) => {
+      deps.broadcast(SseEvent.SessionRalphTodoUpdate, { sessionId: session.id, todos });
+      deps.getStore().updateRalphState(session.id, { todos });
+    },
+
+    /** Broadcasts `session:ralphCompletionDetected` + push notification — completion phrase matched */
+    ralphCompletionDetected: (phrase: string) => {
+      deps.broadcast(SseEvent.SessionRalphCompletionDetected, { sessionId: session.id, phrase });
+      deps.sendPushNotifications(SseEvent.SessionRalphCompletionDetected, {
+        sessionId: session.id,
+        sessionName: session.name,
+        phrase,
+      });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) tracker.recordRalphCompletion(phrase);
+    },
+
+    /** Broadcasts `session:ralphStatusUpdate` — RALPH_STATUS block parsed from output */
+    ralphStatusBlockDetected: (block: RalphStatusBlock) => {
+      deps.broadcast(SseEvent.SessionRalphStatusUpdate, { sessionId: session.id, block });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) {
+        tracker.addEvent(
+          block.status === 'BLOCKED' ? 'warning' : 'idle_detected',
+          block.status === 'BLOCKED' ? 'warning' : 'info',
+          `Ralph Status: ${block.status}`,
+          `Tasks: ${block.tasksCompletedThisLoop}, Files: ${block.filesModified}, Tests: ${block.testsStatus}`
+        );
+      }
+    },
+
+    /** Broadcasts `session:circuitBreakerUpdate` — circuit breaker state changed (CLOSED/HALF_OPEN/OPEN) */
+    ralphCircuitBreakerUpdate: (status: CircuitBreakerStatus) => {
+      deps.broadcast(SseEvent.SessionCircuitBreakerUpdate, { sessionId: session.id, status });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker && status.state === 'OPEN') {
+        tracker.addEvent('warning', 'warning', 'Circuit Breaker Opened', status.reason);
+      }
+    },
+
+    /** Broadcasts `session:exitGateMet` — all completion indicators met, ready to exit */
+    ralphExitGateMet: (data: { completionIndicators: number; exitSignal: boolean }) => {
+      deps.broadcast(SseEvent.SessionExitGateMet, { sessionId: session.id, ...data });
+      const tracker = deps.getRunSummaryTracker(session.id);
+      if (tracker) {
+        tracker.addEvent(
+          'ralph_completion',
+          'success',
+          'Exit Gate Met',
+          `Indicators: ${data.completionIndicators}, EXIT_SIGNAL: ${data.exitSignal}`
+        );
+      }
+    },
+
+    // ─── Bash Tool Tracking ────────────────────────────────
+
+    /** Broadcasts `session:bashToolStart` — bash tool invocation started */
+    bashToolStart: (tool: ActiveBashTool) => {
+      deps.broadcast(SseEvent.SessionBashToolStart, { sessionId: session.id, tool });
+    },
+
+    /** Broadcasts `session:bashToolEnd` — bash tool invocation completed */
+    bashToolEnd: (tool: ActiveBashTool) => {
+      deps.broadcast(SseEvent.SessionBashToolEnd, { sessionId: session.id, tool });
+    },
+
+    /** Broadcasts `session:bashToolsUpdate` — full active bash tools list refreshed */
+    bashToolsUpdate: (tools: ActiveBashTool[]) => {
+      deps.broadcast(SseEvent.SessionBashToolsUpdate, { sessionId: session.id, tools });
+    },
+  };
+}
+
+/** Attach all listeners to a session. */
+export function attachSessionListeners(session: Session, refs: SessionListenerRefs): void {
+  session.on('terminal', refs.terminal);
+  session.on('clearTerminal', refs.clearTerminal);
+  session.on('needsRefresh', refs.needsRefresh);
+  session.on('message', refs.message);
+  session.on('error', refs.error);
+  session.on('completion', refs.completion);
+  session.on('exit', refs.exit);
+  session.on('working', refs.working);
+  session.on('idle', refs.idle);
+  session.on('taskCreated', refs.taskCreated);
+  session.on('taskUpdated', refs.taskUpdated);
+  session.on('taskCompleted', refs.taskCompleted);
+  session.on('taskFailed', refs.taskFailed);
+  session.on('autoClear', refs.autoClear);
+  session.on('autoCompact', refs.autoCompact);
+  session.on('cliInfoUpdated', refs.cliInfoUpdated);
+  session.on('ralphLoopUpdate', refs.ralphLoopUpdate);
+  session.on('ralphTodoUpdate', refs.ralphTodoUpdate);
+  session.on('ralphCompletionDetected', refs.ralphCompletionDetected);
+  session.on('ralphStatusBlockDetected', refs.ralphStatusBlockDetected);
+  session.on('ralphCircuitBreakerUpdate', refs.ralphCircuitBreakerUpdate);
+  session.on('ralphExitGateMet', refs.ralphExitGateMet);
+  session.on('bashToolStart', refs.bashToolStart);
+  session.on('bashToolEnd', refs.bashToolEnd);
+  session.on('bashToolsUpdate', refs.bashToolsUpdate);
+}
+
+/** Detach all listeners from a session (prevents memory leaks from closure references). */
+export function detachSessionListeners(session: Session, refs: SessionListenerRefs): void {
+  session.off('terminal', refs.terminal);
+  session.off('clearTerminal', refs.clearTerminal);
+  session.off('needsRefresh', refs.needsRefresh);
+  session.off('message', refs.message);
+  session.off('error', refs.error);
+  session.off('completion', refs.completion);
+  session.off('exit', refs.exit);
+  session.off('working', refs.working);
+  session.off('idle', refs.idle);
+  session.off('taskCreated', refs.taskCreated);
+  session.off('taskUpdated', refs.taskUpdated);
+  session.off('taskCompleted', refs.taskCompleted);
+  session.off('taskFailed', refs.taskFailed);
+  session.off('autoClear', refs.autoClear);
+  session.off('autoCompact', refs.autoCompact);
+  session.off('cliInfoUpdated', refs.cliInfoUpdated);
+  session.off('ralphLoopUpdate', refs.ralphLoopUpdate);
+  session.off('ralphTodoUpdate', refs.ralphTodoUpdate);
+  session.off('ralphCompletionDetected', refs.ralphCompletionDetected);
+  session.off('ralphStatusBlockDetected', refs.ralphStatusBlockDetected);
+  session.off('ralphCircuitBreakerUpdate', refs.ralphCircuitBreakerUpdate);
+  session.off('ralphExitGateMet', refs.ralphExitGateMet);
+  session.off('bashToolStart', refs.bashToolStart);
+  session.off('bashToolEnd', refs.bashToolEnd);
+  session.off('bashToolsUpdate', refs.bashToolsUpdate);
+}

src/web/sse-events.ts

@@ -325,6 +325,10 @@ export const OrchestratorError = 'orchestrator:error' as const;
 export const CaseCreated = 'case:created' as const;
 /** Existing directory linked as a case. */
 export const CaseLinked = 'case:linked' as const;
+/** Case deleted or unlinked. */
+export const CaseDeleted = 'case:deleted' as const;
+/** Case ordering changed. */
+export const CaseOrderChanged = 'case:order-changed' as const;
 
 // ─── Namespace Re-export ─────────────────────────────────────────────────────
 
@@ -485,4 +489,6 @@ export const SseEvent = {
   // Cases
   CaseCreated,
   CaseLinked,
+  CaseDeleted,
+  CaseOrderChanged,
 } as const;

src/web/sse-stream-manager.ts

@@ -0,0 +1,488 @@
+/**
+ * @fileoverview SSE stream manager — owns all SSE client state, broadcasting, and event batching.
+ *
+ * Extracted from server.ts for modularity. Handles:
+ * - SSE client connection tracking with subscription filtering
+ * - Backpressure-aware message delivery
+ * - Terminal data batching with adaptive intervals (16-50ms for 60fps)
+ * - Task update and session state batching
+ * - Dead client cleanup and keepalive
+ * - Cloudflare tunnel padding for proxy buffer flushing
+ *
+ * @dependencies CleanupManager (managed timers), config/server-timing (constants)
+ * @consumedby web/server.ts (WebServer delegates all SSE operations here)
+ *
+ * @module web/sse-stream-manager
+ */
+
+import type { FastifyReply } from 'fastify';
+import type { BackgroundTask } from '../session.js';
+import { CleanupManager, StaleExpirationMap } from '../utils/index.js';
+import { SseEvent } from './sse-events.js';
+import {
+  TERMINAL_BATCH_INTERVAL,
+  TASK_UPDATE_BATCH_INTERVAL,
+  STATE_UPDATE_DEBOUNCE_INTERVAL,
+  BATCH_FLUSH_THRESHOLD,
+  SSE_PADDING_SIZE,
+  INACTIVITY_TIMEOUT_MS,
+} from '../config/server-timing.js';
+
+// SSE padding for Cloudflare tunnel buffer flushing.
+// Cloudflare quick tunnels buffer small SSE responses, causing lag for real-time events.
+// Appending SSE comment padding (ignored by EventSource) forces the proxy to flush.
+// Pre-computed once at startup to avoid repeated string allocation.
+const SSE_PADDING = ':' + 'p'.repeat(SSE_PADDING_SIZE) + '\n';
+
+/** Dependencies injected by WebServer — keeps SseStreamManager decoupled from session/respawn state. */
+export interface SseStreamManagerDeps {
+  /** Get session state with respawn info for session:updated broadcasts */
+  getSessionStateWithRespawn(sessionId: string): unknown;
+}
+
+export class SseStreamManager {
+  // ─── SSE Client Tracking ────────────────────────────────
+  /**
+   * SSE clients mapped to their session subscription filter.
+   * Value is a Set of session IDs the client wants events for,
+   * or `null` meaning "receive all events" (backwards-compatible default).
+   */
+  private sseClients: Map<FastifyReply, Set<string> | null> = new Map();
+  /** SSE clients connecting from non-localhost (i.e. through tunnel) */
+  private remoteSseClients: Set<FastifyReply> = new Set();
+  /** Clients with backpressure — skip writes until 'drain' fires */
+  private backpressuredClients: Set<FastifyReply> = new Set();
+
+  // ─── Tunnel State ───────────────────────────────────────
+  /** Cached tunnel active state — updated on TunnelStarted/TunnelStopped to avoid getUrl() on every broadcast */
+  private _isTunnelActive: boolean = false;
+
+  // ─── Terminal Batching ──────────────────────────────────
+  private terminalBatches: Map<string, string[]> = new Map();
+  private terminalBatchSizes: Map<string, number> = new Map(); // Running total avoids O(n) reduce per push
+  private terminalBatchTimers: Map<string, NodeJS.Timeout> = new Map(); // Per-session timers (staggered flushes)
+  // Adaptive batching: track rapid events to extend batch window (per-session)
+  // StaleExpirationMap auto-cleans entries for sessions that stop generating output
+  private lastTerminalEventTime: StaleExpirationMap<string, number>;
+
+  // ─── Event Batching ─────────────────────────────────────
+  private taskUpdateBatches: Map<string, { sessionId: string; task: BackgroundTask }> = new Map();
+  private taskUpdateBatchTimerId: string | null = null;
+  // State update batching (reduce expensive toDetailedState() serialization)
+  private stateUpdatePending: Set<string> = new Set();
+  private stateUpdateTimerId: string | null = null;
+
+  // ─── Lifecycle ──────────────────────────────────────────
+  private _isStopping: boolean = false;
+
+  constructor(
+    private deps: SseStreamManagerDeps,
+    private cleanup: CleanupManager
+  ) {
+    this.lastTerminalEventTime = new StaleExpirationMap({
+      ttlMs: INACTIVITY_TIMEOUT_MS, // 5 minutes - auto-expire stale session timing data
+      refreshOnGet: false, // Don't refresh on reads, only on explicit sets
+    });
+  }
+
+  // ========== SSE Connection Management ==========
+
+  get clientCount(): number {
+    return this.sseClients.size;
+  }
+
+  get remoteClientCount(): number {
+    return this.remoteSseClients.size;
+  }
+
+  get isTunnelActive(): boolean {
+    return this._isTunnelActive;
+  }
+
+  setTunnelActive(active: boolean): void {
+    this._isTunnelActive = active;
+  }
+
+  addClient(reply: FastifyReply, sessionFilter: Set<string> | null, isRemote: boolean): void {
+    this.sseClients.set(reply, sessionFilter);
+    if (isRemote) {
+      this.remoteSseClients.add(reply);
+    }
+  }
+
+  removeClient(reply: FastifyReply): void {
+    this.sseClients.delete(reply);
+    this.remoteSseClients.delete(reply);
+    this.backpressuredClients.delete(reply);
+  }
+
+  /** Send a single SSE event to a specific client. */
+  sendSSE(reply: FastifyReply, event: string, data: unknown): void {
+    try {
+      reply.raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    } catch {
+      this.sseClients.delete(reply);
+      this.remoteSseClients.delete(reply);
+    }
+  }
+
+  /** Send pre-formatted tunnel padding to a specific client. */
+  sendPadding(reply: FastifyReply): void {
+    if (!this._isTunnelActive) return;
+    try {
+      reply.raw.write(SSE_PADDING);
+    } catch {
+      /* client gone */
+    }
+  }
+
+  // Optimized: send pre-formatted SSE message to a client
+  // Returns false if client is backpressured or dead
+  private sendSSEPreformatted(reply: FastifyReply, message: string): void {
+    // Skip backpressured clients to prevent unbounded memory growth.
+    // Terminal data dropped here is recovered via session:needsRefresh on drain.
+    if (this.backpressuredClients.has(reply)) return;
+
+    try {
+      const ok = reply.raw.write(message);
+      if (!ok) {
+        // Buffer is full — mark as backpressured, resume on drain
+        this.backpressuredClients.add(reply);
+        reply.raw.once('drain', () => {
+          this.backpressuredClients.delete(reply);
+          // Client may have missed terminal data during backpressure.
+          // Tell it to reload the active session's buffer to recover.
+          try {
+            const drainPadding = this._isTunnelActive ? SSE_PADDING : '';
+            reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n${drainPadding}`);
+          } catch {
+            /* client gone */
+          }
+        });
+      }
+    } catch {
+      this.sseClients.delete(reply);
+      this.remoteSseClients.delete(reply);
+      this.backpressuredClients.delete(reply);
+    }
+  }
+
+  // ========== Broadcasting ==========
+
+  broadcast(event: string, data: unknown): void {
+    // Skip serialization entirely when no clients are listening
+    if (this.sseClients.size === 0) return;
+
+    // Performance optimization: serialize JSON once for all clients.
+    // Only append Cloudflare tunnel padding for latency-sensitive events —
+    // Recovery events need immediate proxy flush; low-frequency metadata events
+    // (session:created, ralph:*, respawn:*, etc.) don't need padding.
+    // Note: session:terminal has its own padding in flushSessionTerminalBatch().
+    const needsPadding = this._isTunnelActive && event === SseEvent.SessionNeedsRefresh;
+    const padding = needsPadding ? SSE_PADDING : '';
+    let message: string;
+    try {
+      message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n` + padding;
+    } catch (err) {
+      // Handle circular references or non-serializable values
+      console.error(`[Server] Failed to serialize SSE event "${event}":`, err);
+      return;
+    }
+    // Extract sessionId from event data for subscription filtering.
+    const eventSessionId = this.extractSessionId(event, data);
+
+    for (const [client, filter] of this.sseClients) {
+      // No filter (null) = receive everything. Otherwise, skip if event is
+      // session-scoped and the session isn't in the client's subscription set.
+      if (filter && eventSessionId && !filter.has(eventSessionId)) continue;
+      this.sendSSEPreformatted(client, message);
+    }
+  }
+
+  /**
+   * Extract the session ID from an event's data payload for subscription filtering.
+   * Returns the sessionId string if the event is session-scoped, or null for global events.
+   */
+  private extractSessionId(event: string, data: unknown): string | null {
+    if (data == null || typeof data !== 'object') return null;
+    const record = data as Record<string, unknown>;
+
+    // Most session-scoped events use `sessionId`
+    if (typeof record.sessionId === 'string') return record.sessionId;
+
+    // Session lifecycle events (session:*) use `id` from the session state object
+    if (typeof record.id === 'string' && event.startsWith('session:')) return record.id;
+
+    // No session ID found — treat as global event (sent to all clients)
+    return null;
+  }
+
+  // ========== Terminal Data Batching ==========
+
+  // Batch terminal data for better performance (60fps)
+  // Uses per-session timers with adaptive intervals to prevent thundering herd:
+  // each session flushes independently rather than all sessions flushing in one burst.
+  batchTerminalData(sessionId: string, data: string): void {
+    // Skip if server is stopping
+    if (this._isStopping) return;
+
+    let chunks = this.terminalBatches.get(sessionId);
+    if (!chunks) {
+      chunks = [];
+      this.terminalBatches.set(sessionId, chunks);
+    }
+    chunks.push(data);
+    const prevSize = this.terminalBatchSizes.get(sessionId) ?? 0;
+    const totalLength = prevSize + data.length;
+    this.terminalBatchSizes.set(sessionId, totalLength);
+
+    // Adaptive batching: detect rapid events and extend batch window (per-session)
+    const now = Date.now();
+    const lastEvent = this.lastTerminalEventTime.get(sessionId) ?? 0;
+    const eventGap = now - lastEvent;
+    this.lastTerminalEventTime.set(sessionId, now);
+
+    // Adjust batch interval based on event frequency (per-session)
+    // Rapid events (<10ms gap) = 50ms batch, moderate (<20ms) = 32ms, else 16ms
+    let sessionInterval: number;
+    if (eventGap > 0 && eventGap < 10) {
+      sessionInterval = 50;
+    } else if (eventGap > 0 && eventGap < 20) {
+      sessionInterval = 32;
+    } else {
+      sessionInterval = TERMINAL_BATCH_INTERVAL;
+    }
+
+    // Flush immediately if batch is large for responsiveness
+    if (totalLength > BATCH_FLUSH_THRESHOLD) {
+      const existingTimer = this.terminalBatchTimers.get(sessionId);
+      if (existingTimer) {
+        clearTimeout(existingTimer);
+        this.terminalBatchTimers.delete(sessionId);
+      }
+      this.flushSessionTerminalBatch(sessionId);
+      return;
+    }
+
+    // Start per-session batch timer if not already running
+    // Each session flushes independently — prevents one busy session from
+    // forcing all sessions to flush at its rate (thundering herd)
+    if (!this.terminalBatchTimers.has(sessionId)) {
+      this.terminalBatchTimers.set(
+        sessionId,
+        setTimeout(() => {
+          this.terminalBatchTimers.delete(sessionId);
+          this.flushSessionTerminalBatch(sessionId);
+        }, sessionInterval)
+      );
+    }
+  }
+
+  /** Flush a single session's batched terminal data */
+  private flushSessionTerminalBatch(sessionId: string): void {
+    if (this._isStopping) {
+      this.terminalBatches.delete(sessionId);
+      this.terminalBatchSizes.delete(sessionId);
+      return;
+    }
+    const chunks = this.terminalBatches.get(sessionId);
+    if (chunks && chunks.length > 0) {
+      // Join chunks only at flush time (avoids O(n^2) string concatenation in batchTerminalData)
+      const data = chunks.join('');
+      // Wrap batched output in DEC 2026 synchronized output markers so xterm.js
+      // renders the entire batch atomically. Ink spinner frames (cursor-up + redraw)
+      // do NOT emit their own 2026 markers, so without this wrapper each partial
+      // cursor update renders individually, causing visible flicker.
+      // xterm.js 6.0+ handles DEC 2026 natively: it buffers everything between
+      // 2026h/2026l and renders in one pass.
+      const syncData = '\x1b[?2026h' + data + '\x1b[?2026l';
+      // Fast path: build SSE message directly without JSON.stringify on wrapper object.
+      // Only the terminal data string needs escaping; sessionId is a UUID (safe to template).
+      const escapedData = JSON.stringify(syncData);
+      // Append tunnel padding for immediate Cloudflare proxy flush —
+      // terminal data is high-frequency and latency-sensitive.
+      const padding = this._isTunnelActive ? SSE_PADDING : '';
+      const message = `event: session:terminal\ndata: {"id":"${sessionId}","data":${escapedData}}\n\n` + padding;
+      for (const [client, filter] of this.sseClients) {
+        // Skip clients that have a session filter and aren't subscribed to this session
+        if (filter && !filter.has(sessionId)) continue;
+        this.sendSSEPreformatted(client, message);
+      }
+    }
+    this.terminalBatches.delete(sessionId);
+    this.terminalBatchSizes.delete(sessionId);
+  }
+
+  // ========== Task Update Batching ==========
+
+  // Batch task:updated events at 100ms - only send latest update per task
+  // Key is sessionId:taskId to avoid collisions when multiple tasks update concurrently
+  batchTaskUpdate(sessionId: string, task: BackgroundTask): void {
+    // Skip if server is stopping
+    if (this._isStopping) return;
+
+    // Use composite key to avoid losing updates when multiple tasks update in same batch window
+    const key = `${sessionId}:${task.id}`;
+    this.taskUpdateBatches.set(key, { sessionId, task });
+
+    if (!this.taskUpdateBatchTimerId) {
+      this.taskUpdateBatchTimerId = this.cleanup.setTimeout(
+        () => {
+          this.taskUpdateBatchTimerId = null;
+          this.flushTaskUpdateBatches();
+        },
+        TASK_UPDATE_BATCH_INTERVAL,
+        { description: 'task update batch flush' }
+      );
+    }
+  }
+
+  private flushTaskUpdateBatches(): void {
+    // Skip if server is stopping (timer may have been queued before stop() was called)
+    if (this._isStopping) {
+      this.taskUpdateBatches.clear();
+      return;
+    }
+    for (const [, { sessionId, task }] of this.taskUpdateBatches) {
+      this.broadcast(SseEvent.TaskUpdated, { sessionId, task });
+    }
+    this.taskUpdateBatches.clear();
+  }
+
+  // ========== Session State Batching ==========
+
+  /**
+   * Debounce expensive session:updated broadcasts.
+   * Instead of calling toDetailedState() on every event, batch requests
+   * and only serialize once per STATE_UPDATE_DEBOUNCE_INTERVAL.
+   */
+  broadcastSessionStateDebounced(sessionId: string): void {
+    // Skip if server is stopping
+    if (this._isStopping) return;
+
+    this.stateUpdatePending.add(sessionId);
+
+    if (!this.stateUpdateTimerId) {
+      this.stateUpdateTimerId = this.cleanup.setTimeout(
+        () => {
+          this.stateUpdateTimerId = null;
+          this.flushStateUpdates();
+        },
+        STATE_UPDATE_DEBOUNCE_INTERVAL,
+        { description: 'state update debounce flush' }
+      );
+    }
+  }
+
+  private flushStateUpdates(): void {
+    // Skip if server is stopping (timer may have been queued before stop() was called)
+    if (this._isStopping) {
+      this.stateUpdatePending.clear();
+      return;
+    }
+    for (const sessionId of this.stateUpdatePending) {
+      // Single expensive serialization per batch interval
+      const state = this.deps.getSessionStateWithRespawn(sessionId);
+      if (state) {
+        this.broadcast(SseEvent.SessionUpdated, state);
+      }
+    }
+    this.stateUpdatePending.clear();
+  }
+
+  // ========== Client Health ==========
+
+  /**
+   * Clean up dead SSE clients and send keep-alive comments.
+   * Keep-alive prevents proxy/load-balancer timeouts on idle connections.
+   * Dead client cleanup prevents memory leaks from abruptly terminated connections.
+   */
+  cleanupDeadClients(): void {
+    const deadClients: FastifyReply[] = [];
+
+    for (const [client] of this.sseClients) {
+      try {
+        // Check if the underlying socket is still writable
+        const socket = client.raw.socket;
+        if (!socket || socket.destroyed || !socket.writable) {
+          deadClients.push(client);
+        } else {
+          // Send SSE comment as keep-alive. Only add padding when tunnel is
+          // active — it flushes Cloudflare proxy buffers but wastes bandwidth
+          // for direct/Tailscale connections.
+          const ka = this._isTunnelActive ? ':keepalive\n' + SSE_PADDING : ':keepalive\n\n';
+          client.raw.write(ka);
+        }
+      } catch {
+        // Error accessing socket means client is dead
+        deadClients.push(client);
+      }
+    }
+
+    // Remove dead clients
+    for (const client of deadClients) {
+      this.sseClients.delete(client);
+      this.remoteSseClients.delete(client);
+      this.backpressuredClients.delete(client);
+    }
+
+    if (deadClients.length > 0) {
+      console.log(`[Server] Cleaned up ${deadClients.length} dead SSE client(s)`);
+    }
+  }
+
+  // ========== Session Cleanup ==========
+
+  /** Clean up all batching state for a session (call on session exit or deletion). */
+  cleanupSessionBatches(sessionId: string): void {
+    this.terminalBatches.delete(sessionId);
+    this.terminalBatchSizes.delete(sessionId);
+    const batchTimer = this.terminalBatchTimers.get(sessionId);
+    if (batchTimer) {
+      clearTimeout(batchTimer);
+      this.terminalBatchTimers.delete(sessionId);
+    }
+    this.taskUpdateBatches.delete(sessionId);
+    this.stateUpdatePending.delete(sessionId);
+    this.lastTerminalEventTime.delete(sessionId);
+  }
+
+  // ========== Lifecycle ==========
+
+  setStopping(): void {
+    this._isStopping = true;
+  }
+
+  /** Graceful shutdown: notify clients, close connections, clear all state. */
+  stop(): void {
+    this._isStopping = true;
+
+    // Gracefully close all SSE connections before clearing
+    for (const [client] of this.sseClients) {
+      try {
+        // Send a final event to notify clients of shutdown
+        this.sendSSE(client, 'server:shutdown', { reason: 'Server stopping' });
+        client.raw.end();
+      } catch {
+        // Client may already be disconnected
+      }
+    }
+    this.sseClients.clear();
+    this.remoteSseClients.clear();
+    this.backpressuredClients.clear();
+
+    // Clear per-session batch timers
+    for (const timer of this.terminalBatchTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.terminalBatchTimers.clear();
+    this.terminalBatches.clear();
+    this.terminalBatchSizes.clear();
+
+    this.taskUpdateBatches.clear();
+    this.stateUpdatePending.clear();
+
+    // Dispose StaleExpirationMap (stops internal cleanup timer)
+    this.lastTerminalEventTime.dispose();
+  }
+}

test/mocks/mock-session.ts

@@ -17,6 +17,7 @@ export class MockSession extends EventEmitter {
   status: 'idle' | 'working' = 'idle';
   pid: number = 12345;
   isWorking: boolean = false;
+  private _activeChildProcesses: { pid: number; command: string }[] = [];
   ralphTracker: null = null;
   writeBuffer: string[] = [];
   terminalBuffer: string = '';
@@ -52,9 +53,7 @@ export class MockSession extends EventEmitter {
 
   /** Check if a specific command was written */
   hasWritten(pattern: string | RegExp): boolean {
-    return this.writeBuffer.some((data) =>
-      typeof pattern === 'string' ? data.includes(pattern) : pattern.test(data),
-    );
+    return this.writeBuffer.some((data) => (typeof pattern === 'string' ? data.includes(pattern) : pattern.test(data)));
   }
 
   // ========== Terminal Output Simulation ==========
@@ -113,10 +112,7 @@ export class MockSession extends EventEmitter {
    */
   simulatePlanModePrompt(): void {
     this.simulateTerminalOutput(
-      'Would you like to proceed with this plan?\n' +
-        '\u276f 1. Yes\n' +
-        '  2. No\n' +
-        '  3. Type your own\n',
+      'Would you like to proceed with this plan?\n' + '\u276f 1. Yes\n' + '  2. No\n' + '  3. Type your own\n'
     );
   }
 
@@ -131,11 +127,7 @@ export class MockSession extends EventEmitter {
   /** Simulate token count display */
   simulateTokenCount(tokens: number | string): void {
     const formatted =
-      typeof tokens === 'number'
-        ? tokens >= 1000
-          ? `${(tokens / 1000).toFixed(1)}k`
-          : String(tokens)
-        : tokens;
+      typeof tokens === 'number' ? (tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens)) : tokens;
     this.simulateTerminalOutput(`${formatted} tokens used`);
   }
 
@@ -167,6 +159,16 @@ export class MockSession extends EventEmitter {
     return this._muxName;
   }
 
+  /** Check for active child processes (mock returns configurable list) */
+  getActiveChildProcesses(): { pid: number; command: string }[] {
+    return this._activeChildProcesses;
+  }
+
+  /** Set active child processes for testing */
+  setActiveChildProcesses(processes: { pid: number; command: string }[]): void {
+    this._activeChildProcesses = processes;
+  }
+
   // ========== Route-test conveniences ==========
 
   /** Session display name */

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',