chore: version packages

1. Rewrote getActiveChildProcesses() to use a single `ps --ppid` call
   instead of two-level pgrep. The pane PID is typically claude itself
   (bash exec'd into it), not a bash wrapper — so direct children of
   pane_pid ARE the tool processes.

2. Added timer restart in tryStartAiCheck() when skipping due to child
   processes. Without this, the pre-filter and no-output timers (both
   one-shot) would never fire again, permanently stalling idle detection
   for sessions with silent long-running processes.

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

CHANGELOG.md

@@ -1,5 +1,64 @@
 # aicodeman
 
+## 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
+
+- Visual redesign with glass morphism, refined colors, and polished UI. Optimize history endpoint with buffer reuse and line iterator. Fix Ink frame search window (4KB→64KB) to prevent partial frames. Fix stale terminal data on tab switch via chunkedTerminalWrite cancellation. Improve history prompt extraction with expanded command filtering and tail scan fallback. Align case select group height to match dropdown. Fix no-control-regex lint error for ANSI strip pattern. Add browser-testing-guide to CLAUDE.md references.
+
 ## 0.4.7
 
 ### Patch Changes

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 | Task | Command |
 |------|---------|
-| Dev server | `npx tsx src/index.ts web` |
+| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
 | Type check | `tsc --noEmit` |
 | Lint | `npm run lint` (fix: `npm run lint:fix`) |
 | Format | `npm run format` (check: `npm run format:check`) |
@@ -52,7 +52,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.4.7 (must match `package.json`)
+**Version**: 0.5.5 (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/**`.
 
@@ -109,9 +109,9 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **State** | `src/state-store.ts`, `src/run-summary.ts`, `src/session-lifecycle-log.ts` | |
 | **Infra** | `src/hooks-config.ts`, `src/push-store.ts`, `src/tunnel-manager.ts`, `src/image-watcher.ts`, `src/file-stream-manager.ts` | |
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
-| **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (14 route modules incl. `ws-routes.ts` + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.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
 
@@ -226,7 +226,7 @@ Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: termina
 
 ## References
 
-Deep-dive docs in `docs/`: `respawn-state-machine.md`, `ralph-wiggum-guide.md`, `claude-code-hooks-reference.md`, `terminal-anti-flicker.md`, `opencode-integration.md`, `qr-auth-plan.md`, `orchestrator-loop-architecture.md`. Agent Teams: `agent-teams/README.md`. SSE events: `src/web/sse-events.ts` + `constants.js`.
+Deep-dive docs in `docs/`: `respawn-state-machine.md`, `ralph-wiggum-guide.md`, `claude-code-hooks-reference.md`, `terminal-anti-flicker.md`, `opencode-integration.md`, `qr-auth-plan.md`, `orchestrator-loop-architecture.md`, `browser-testing-guide.md`. Agent Teams: `agent-teams/README.md`. SSE events: `src/web/sse-events.ts` + `constants.js`.
 
 ## Scripts
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "0.4.7",
+  "version": "0.5.5",
   "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,
@@ -538,6 +541,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 +917,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 +997,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 +1008,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 +1020,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 +1116,7 @@ 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.emit('terminal', data);
-      this.emit('output', data);
+      this._handleTerminalOutput(data);
 
       // === Idle/working detection runs on every chunk (latency-sensitive) ===
       // Detect if Claude is working or at prompt
@@ -1257,13 +1312,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 +1324,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 +1384,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 +1449,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 +1492,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 +1524,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 +1557,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 +1709,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 +2001,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 +2076,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) {
@@ -265,28 +311,10 @@ export class StateStore {
 
     const tempPath = this.filePath + '.tmp';
     const backupPath = this.filePath + '.bak';
-    let json: string;
 
     // Step 1: Serialize state (validates it's JSON-safe)
-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;
 
     // Clear dirty flag BEFORE async I/O so mutations during write re-set it.
     // The state snapshot is already captured in `json` above.
@@ -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
@@ -351,27 +375,9 @@ export class StateStore {
 
     const tempPath = this.filePath + '.tmp';
     const backupPath = this.filePath + '.bak';
-    let json: string;
 
-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;
 
     // Backup via atomic copy (avoids reading entire file into memory)
     try {
@@ -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) {
@@ -591,73 +607,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 +671,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 +728,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 +870,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 +895,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 +939,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 +952,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 +969,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 +1000,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 +1121,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 +1257,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,21 +1286,17 @@ 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;
     this._loadBufferQueue = null;
+    // Abort any in-flight chunkedTerminalWrite (SSE reconnect reloads buffers)
+    this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
     // Preserve local echo overlay text across SSE reconnect — just hide until
     // terminal buffer reloads and prompt is visible again.  _render() re-scans
     // for the ❯ prompt on every call, so rerender() after buffer load repositions it.
@@ -1414,6 +1349,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)
@@ -1541,18 +1506,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(). */
@@ -1978,17 +1952,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();
 
@@ -1997,10 +1979,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;
 
@@ -2008,18 +1987,19 @@ 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;
     this._loadBufferQueue = null;
+    // Abort any in-flight chunkedTerminalWrite from the previous session.
+    // Without this, old rAF-scheduled chunks continue writing stale data
+    // into the terminal, interleaving with the new session's buffer.
+    this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
     // End any in-flight IME composition.
     // iOS Safari keeps autocorrect composing; switching tabs without ending it
     // leaves xterm's _compositionHelper._isComposing stuck true, which blocks
@@ -2061,9 +2041,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();
@@ -2136,23 +2136,36 @@ class CodemanApp {
     this._isLoadingBuffer = true;
     this._loadBufferQueue = [];
     try {
-      // 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.
+      // Fit terminal to container BEFORE writing any buffer data.
+      // If the browser was resized while viewing another session, the terminal
+      // canvas may be at stale dimensions — content would render at wrong width.
+      if (this.fitAddon) this.fitAddon.fit();
+
+      // 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}`);
 
@@ -2171,7 +2184,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();
         }
@@ -2189,9 +2202,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();
       }
@@ -2215,9 +2228,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.
@@ -2568,9 +2591,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/index.html

@@ -30,13 +30,13 @@
   <script>if(window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024))document.documentElement.classList.add('mobile-init');</script>
   <!-- Inline critical CSS for instant skeleton paint (before styles.css loads) -->
   <style>
-    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#0a0a0a}
-    .skeleton-header{height:40px;background:#111;border-bottom:1px solid #1a1a2e;display:flex;align-items:center;padding:0 12px}
-    .skeleton-brand{color:#60a5fa;font-size:14px;font-weight:600;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.7}
+    .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:#09090b}
+    .skeleton-header{height:40px;background:rgba(19,19,22,0.85);border-bottom:1px solid rgba(255,255,255,0.06);display:flex;align-items:center;padding:0 12px}
+    .skeleton-brand{color:#60a5fa;font-size:14px;font-weight:700;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;opacity:.7}
     .skeleton-tabs{display:flex;gap:4px;margin-left:16px}
-    .skeleton-tab{width:80px;height:24px;background:#1a1a2e;border-radius:4px}
+    .skeleton-tab{width:80px;height:24px;background:rgba(255,255,255,0.04);border-radius:6px}
     .skeleton-terminal{flex:1;background:#0d0d0d}
-    .skeleton-toolbar{height:32px;background:#111;border-top:1px solid #1a1a2e}
+    .skeleton-toolbar{height:42px;background:rgba(19,19,22,0.85);border-top:1px solid rgba(255,255,255,0.06)}
     .app-loaded .loading-skeleton{display:none}
   </style>
 </head>
@@ -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,16 @@
                   <span class="slider"></span>
                 </label>
               </div>
+              <div class="settings-item settings-item-multiline" title="Show a dedicated input field below the terminal for CJK (Chinese/Japanese/Korean) IME composition. Recommended for mobile devices with Chinese input methods where xterm's native input handling may drop characters.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">CJK Input</span>
+                  <span class="settings-item-desc">Dedicated IME input field for CJK languages</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsCjkInput">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Header Displays Section -->
               <div class="settings-section-header">Header Displays</div>
@@ -1036,6 +1056,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">

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/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
@@ -1147,6 +1183,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 +1249,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 +1322,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 +1391,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 +1429,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;

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: false };
   },
 
   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;
   },
 
   // ═══════════════════════════════════════════════════════════════

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,7 @@ 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('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
     // Claude CLI settings
     const claudeModeSelect = document.getElementById('appSettingsClaudeMode');
@@ -377,6 +332,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 +472,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 +490,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 +1124,14 @@ Object.assign(CodemanApp.prototype, {
       imageWatcherEnabled: document.getElementById('appSettingsImageWatcherEnabled').checked,
       tunnelEnabled: document.getElementById('appSettingsTunnelEnabled').checked,
       localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
+      cjkInputEnabled: document.getElementById('appSettingsCjkInput').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 +1242,12 @@ 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();
+
     // 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, ...serverSettings } = settings;
     try {
       await this._apiPut('/api/settings', { ...serverSettings, notificationPreferences: notifPrefsToSave, voiceSettings });
 
@@ -1682,7 +1631,7 @@ Object.assign(CodemanApp.prototype, {
         const displayKeys = new Set([
           'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled',
+          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled',
         ]);
         // Merge settings: non-display keys always sync from server,
         // display keys only seed from server when localStorage has no value

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,51 +179,73 @@ 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;
+      container.addEventListener(
+        'touchstart',
+        (ev) => {
+          if (ev.touches.length === 1) {
+            touchLastY = ev.touches[0].clientY;
+            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;
-          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
     this.showWelcome();
 
+    // Generation counter for chunkedTerminalWrite — aborts stale writes on tab switch
+    this._chunkedWriteGen = 0;
+
     // Handle resize with throttling for performance
     this._resizeTimeout = null;
     this._lastResizeDims = null;
@@ -264,8 +291,13 @@ Object.assign(CodemanApp.prototype, {
         // 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()) {
+        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
@@ -278,14 +310,12 @@ 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) {
             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(() => {});
           }
         }
@@ -439,7 +469,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;
@@ -454,7 +488,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('', () => {
@@ -553,7 +588,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);
@@ -570,12 +606,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;
@@ -585,27 +646,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);
@@ -622,10 +688,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');
@@ -691,12 +760,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');
@@ -759,7 +833,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);
@@ -777,7 +851,6 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-
   // ═══════════════════════════════════════════════════════════════
   // Terminal Rendering
   // ═══════════════════════════════════════════════════════════════
@@ -822,9 +895,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;
@@ -890,47 +964,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 });
       }
+    }
   },
 
   /**
@@ -947,7 +1023,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.
@@ -971,7 +1047,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) {
@@ -988,8 +1067,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('', () => {
@@ -1010,7 +1093,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 {
@@ -1033,6 +1119,10 @@ Object.assign(CodemanApp.prototype, {
    * @returns {Promise<void>} - Resolves when all chunks written
    */
   chunkedTerminalWrite(buffer, chunkSize = TERMINAL_CHUNK_SIZE) {
+    // Generation counter: if a newer chunkedTerminalWrite starts (tab switch),
+    // older writes abort instead of continuing to push stale data into the terminal.
+    const writeGen = ++this._chunkedWriteGen;
+
     return new Promise((resolve) => {
       if (!buffer || buffer.length === 0) {
         this._finishBufferLoad();
@@ -1049,7 +1139,10 @@ Object.assign(CodemanApp.prototype, {
       const cleanBuffer = buffer.replace(DEC_SYNC_STRIP_RE, '');
 
       const finish = () => {
-        this._finishBufferLoad();
+        // Only finish if we're still the active write — a newer write owns buffer load state
+        if (this._chunkedWriteGen === writeGen) {
+          this._finishBufferLoad();
+        }
         resolve();
       };
 
@@ -1067,9 +1160,17 @@ Object.assign(CodemanApp.prototype, {
       const _chunkStart = performance.now();
       let _chunkCount = 0;
       const writeChunk = () => {
+        // Abort if a newer chunked write started (user switched tabs)
+        if (this._chunkedWriteGen !== writeGen) {
+          resolve();
+          return;
+        }
+
         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;
@@ -1080,7 +1181,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
@@ -1093,21 +1197,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
   // ═══════════════════════════════════════════════════════════════
@@ -1141,7 +1244,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');
@@ -1168,7 +1271,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' }),
       });
     });
   },
@@ -1230,7 +1333,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),
     };
   },
 
@@ -1240,6 +1343,9 @@ Object.assign(CodemanApp.prototype, {
    * @returns {Promise<void>}
    */
   async sendResize(sessionId) {
+    // Fit terminal to container before reading dimensions — ensures local
+    // terminal size matches what we report to the server PTY.
+    if (this.fitAddon) this.fitAddon.fit();
     const dims = this.getTerminalDimensions();
     if (!dims) return;
     // Fast path: WebSocket resize
@@ -1254,7 +1360,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),
     });
   },
 
@@ -1268,11 +1374,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

@@ -14,7 +14,7 @@ import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.
 import { CreateCaseSchema, LinkCaseSchema } from '../schemas.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { writeHooksConfig } from '../../hooks-config.js';
-import { CASES_DIR, validatePathWithinBase } from '../route-helpers.js';
+import { CASES_DIR, validatePathWithinBase, parseBody, readJsonConfig } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { EventPort, ConfigPort } from '../ports/index.js';
 
@@ -22,15 +22,7 @@ const LINKED_CASES_FILE = join(homedir(), '.codeman', 'linked-cases.json');
 
 /** Read and parse linked-cases.json, returning empty object on missing/invalid file. */
 async function readLinkedCases(): Promise<Record<string, string>> {
-  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. */
@@ -83,11 +75,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
   });
 
   app.post('/api/cases', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
-    const result = CreateCaseSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { name, description } = result.data;
+    const { name, description } = parseBody(CreateCaseSchema, req.body);
 
     const casePath = validatePathWithinBase(name, CASES_DIR);
     if (!casePath) {
@@ -120,11 +108,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
 
   // Link an existing folder as a case
   app.post('/api/cases/link', async (req): Promise<ApiResponse<{ case: { name: string; path: string } }>> => {
-    const lcResult = LinkCaseSchema.safeParse(req.body);
-    if (!lcResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { name, path: folderPath } = lcResult.data;
+    const { name, path: folderPath } = parseBody(LinkCaseSchema, req.body, 'Invalid request body');
 
     // Expand ~ to home directory
     const expandedPath = folderPath.startsWith('~') ? join(homedir(), folderPath.slice(1)) : folderPath;

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);
 

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';
@@ -73,15 +81,28 @@ function stripInkRedrawBloat(buffer: string): string {
   // If the redraw section is small (<16KB), not worth stripping
   if (redrawPart.length < 16384) return buffer;
 
-  // Keep only the last 4KB of redraw frames — this preserves the final visual state
-  // (spinner position, status bar text, token count, etc.)
-  const tail = redrawPart.slice(-4096);
-  // Avoid starting mid-escape: find first complete frame boundary
-  // eslint-disable-next-line no-control-regex
-  const frameStart = tail.search(/\x1b\(B\x1b\[m|\x1b\[\d+d|\x1b\[\d+;\d+H/);
-  const cleanTail = frameStart > 0 ? tail.slice(frameStart) : tail;
+  // Find the last complete Ink frame by searching for where the VPA row
+  // number drops (cursor jumps back to viewport top for a new render cycle).
+  // Search the last 64KB — a single Ink frame with response content can be
+  // 10-20KB, so 4KB was too small and caused partial frames (blank gap).
+  const searchLen = Math.min(redrawPart.length, 65536);
+  const searchWindow = redrawPart.slice(-searchLen);
 
-  return contentPart + cleanTail;
+  // eslint-disable-next-line no-control-regex
+  const vpaRe = /\x1b\[(\d+)d/g;
+  let lastFrameStart = 0;
+  let prevRow = -1;
+  let match;
+  while ((match = vpaRe.exec(searchWindow)) !== null) {
+    const row = parseInt(match[1], 10);
+    // Row number dropped significantly — Ink started a new frame
+    if (prevRow > 0 && row < prevRow - 5) {
+      lastFrameStart = match.index;
+    }
+    prevRow = row;
+  }
+
+  return contentPart + searchWindow.slice(lastFrameStart);
 }
 
 export function registerSessionRoutes(
@@ -125,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
@@ -149,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');
@@ -197,23 +219,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 };
   });
 
@@ -221,16 +234,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)) {
@@ -238,8 +243,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 };
   });
 
@@ -278,11 +282,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).
@@ -297,11 +297,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,
@@ -317,11 +313,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,
@@ -337,11 +329,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) {
@@ -361,11 +349,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,
@@ -383,16 +367,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');
@@ -411,11 +387,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');
@@ -455,11 +427,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');
@@ -489,16 +457,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) {
@@ -534,16 +494,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 };
@@ -556,11 +508,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;
@@ -619,20 +567,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,
@@ -649,20 +588,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,
@@ -680,16 +610,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);
@@ -713,20 +635,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,
@@ -751,11 +664,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');
@@ -811,11 +720,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') {
@@ -965,7 +870,12 @@ export function registerSessionRoutes(
   /** Extract the text of the first user message from a JSONL transcript head. */
   function extractFirstUserPrompt(head: string): string | undefined {
     const MAX_PROMPT_LEN = 120;
-    for (const line of head.split('\n')) {
+    // Iterate lines without allocating a full split array
+    let start = 0;
+    while (start < head.length) {
+      const end = head.indexOf('\n', start);
+      const line = end === -1 ? head.slice(start) : head.slice(start, end);
+      start = end === -1 ? head.length : end + 1;
       if (!line.includes('"type":"user"')) continue;
       try {
         const entry = JSON.parse(line);
@@ -979,14 +889,25 @@ export function registerSessionRoutes(
           if (textBlock) text = textBlock.text;
         }
         if (!text) continue;
-        // Strip XML-like system/command tags that Claude Code injects into transcripts
+        // Strip XML-like system/command tags and ANSI escapes from transcripts
         text = text
           .replace(/<[^>]+>/g, '')
+          .replace(new RegExp(String.raw`\x1b\[[0-9;]*[a-zA-Z]`, 'g'), '')
           .trim()
           .replace(/\s+/g, ' ');
         if (!text) continue;
-        // Skip system-injected messages and slash command artifacts (not real user prompts)
-        if (/^(Caveat:|init\b|clear\b|\/\w+ \w+$|You are a )/i.test(text)) continue;
+        // Skip system-injected messages, slash command artifacts, and expanded skill prompts
+        if (
+          /^(Caveat:|init\b|clear\b|resume\b|\/[a-z][\w-]*\b|You are a |\[Request |Set model to )/i.test(text) ||
+          /^(Please )?(analyze|review) this codebase/i.test(text) ||
+          /^(Read|Implement the following) .+, then (search|list|check) /i.test(text) ||
+          /^\d+ vulnerabilit/i.test(text) ||
+          /\btoolu_/.test(text) ||
+          /^[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/.test(text) ||
+          /\b(sk-ant-|ANTHROPIC_API_KEY|API_KEY=|SECRET|TOKEN=)/i.test(text) ||
+          text.length < 8
+        )
+          continue;
         return text.length > MAX_PROMPT_LEN ? text.slice(0, MAX_PROMPT_LEN) + '…' : text;
       } catch {
         // Malformed line — skip
@@ -995,6 +916,37 @@ export function registerSessionRoutes(
     return undefined;
   }
 
+  /** Read the first 16KB of a file for content sniffing. */
+  async function readFileHead(path: string, buf: Buffer): Promise<string | null> {
+    try {
+      const fd = await fs.open(path, 'r');
+      const { bytesRead } = await fd.read(buf, 0, buf.length, 0);
+      await fd.close();
+      return buf.toString('utf8', 0, bytesRead);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Read the last `buf.length` bytes of a file (for tail-scanning user prompts). */
+  async function readFileTail(path: string, buf: Buffer, fileSize: number): Promise<string | null> {
+    try {
+      const fd = await fs.open(path, 'r');
+      const offset = Math.max(0, fileSize - buf.length);
+      const { bytesRead } = await fd.read(buf, 0, buf.length, offset);
+      await fd.close();
+      const text = buf.toString('utf8', 0, bytesRead);
+      // Skip first partial line when we didn't read from the start
+      if (offset > 0) {
+        const nl = text.indexOf('\n');
+        return nl >= 0 ? text.slice(nl + 1) : null;
+      }
+      return text;
+    } catch {
+      return null;
+    }
+  }
+
   app.get('/api/history/sessions', async () => {
     const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects');
     const results: Array<{
@@ -1005,6 +957,7 @@ export function registerSessionRoutes(
       lastModified: string;
       firstPrompt?: string;
     }> = [];
+    const headBuf = Buffer.alloc(16384);
 
     try {
       const projectDirs = await fs.readdir(projectsDir);
@@ -1042,20 +995,9 @@ export function registerSessionRoutes(
           // no "user"/"assistant" messages and will fail claude --resume.
           // Read first 16KB to check content and extract first user prompt.
           let firstPrompt: string | undefined;
-          const readHead = async (): Promise<string | null> => {
-            try {
-              const fd = await fs.open(filePath, 'r');
-              const buf = Buffer.alloc(16384);
-              const { bytesRead } = await fd.read(buf, 0, 16384, 0);
-              await fd.close();
-              return buf.toString('utf8', 0, bytesRead);
-            } catch {
-              return null;
-            }
-          };
+          const head = await readFileHead(filePath, headBuf);
 
           if (fileStat.size < 50000) {
-            const head = await readHead();
             if (
               !head ||
               (!head.includes('"type":"user"') &&
@@ -1064,11 +1006,15 @@ export function registerSessionRoutes(
             ) {
               continue; // No conversation content — skip
             }
-            firstPrompt = extractFirstUserPrompt(head);
-          } else {
-            // Large files are almost certainly real conversations; still read head for prompt
-            const head = await readHead();
-            if (head) firstPrompt = extractFirstUserPrompt(head);
+          }
+          if (head) firstPrompt = extractFirstUserPrompt(head);
+
+          // If head scan found no usable prompt (e.g. session started with /init),
+          // try reading the tail for a recent user message.
+          if (!firstPrompt && fileStat.size > 65536) {
+            const tailBuf = Buffer.alloc(32768);
+            const tail = await readFileTail(filePath, tailBuf, fileStat.size);
+            if (tail) firstPrompt = extractFirstUserPrompt(tail);
           }
 
           results.push({

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

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