chore: version packages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
refactor: pass 2 — extract shared helpers and simplify patterns
2026-10-01 04:59:41 +02:00 · 2026-03-25 23:34:14 +01:00 · 2026-03-25 23:32:28 +01:00 · 2026-03-25 23:21:38 +01:00 · 2026-03-25 13:39:47 +01:00 · 2026-03-25 13:39:16 +01:00
35 changed files with 1460 additions and 1247 deletions
@@ -1,5 +1,46 @@
 # aicodeman

+## 0.5.3
+
+### Patch Changes
+
+- Readability refactor across 12 core files, extracting ~35 helper methods to reduce duplication:
+  - state-store: extract serializeState(), split assembleStateJson() into focused sub-methods
+  - session: extract \_resetBuffers() (3x dedup), \_clearAllTimers() (10 timer cleanups), \_handleJsonMessage()
+  - ralph-tracker: extract completeAllTodos() (4x dedup), emitValidationWarning(), named similarity constants
+  - subagent-watcher: extract markSubagentAsCompleted(), extractFirstTextContent(), emitToolResult(), findOldestInactiveAgent()
+  - respawn-controller: extract recoveryResetToWatching(), canAutoAccept(), formatRemainingSeconds(), validatePositiveTimeout()
+  - tmux-manager: replace 15 path.includes() with UNSAFE_PATH_CHARS regex, extract buildEnvExports/buildPathExport/\_configureOpenCode helpers
+  - session-auto-ops: extract executeWhenIdle() shared retry helper, convert to options object, add validateThreshold()
+  - app.js: add \_clearTimer() (11 call sites), \_isStaleSelect(), keyboard shortcut lookup table, \_cleanupPreviousSession(), \_resetAllAppState()
+  - route-helpers: add readJsonConfig() (5 inline patterns replaced), validateSessionFilePath() (2 duplicated blocks replaced)
+
+## 0.5.2
+
+### Patch Changes
+
+- Make buffer size limits configurable via CODEMAN\_\* environment variables (MAX_TERMINAL_BUFFER, TRIM_TERMINAL_TO, MAX_TEXT_OUTPUT, TRIM_TEXT_TO, MAX_MESSAGES), falling back to existing defaults. Allows users with fewer sessions or more RAM to tune buffer sizes without patching source.
+
+  Fix duplicate terminal output on tab switch to busy sessions by clearing the terminal before writing the new buffer.
+
+  Fix stale Ink CUP frames after tab switch by sending Ctrl+L to force a clean redraw.
+
+  Fix mobile CJK input handling: resolve textarea positioning, terminal flicker during composition, and layout overflow on small screens. Improve CJK composition lifecycle with better event handling and fallback flush timers.
+
+## 0.5.1
+
+### Patch Changes
+
+- refactor: codebase cleanup — extract route helpers, eliminate boilerplate, optimize hot paths
+  - Add `parseBody()` helper to route-helpers.ts: validates request body against Zod schema with structured 400 error on failure, replacing 37 identical safeParse + error-check blocks across 10 route files
+  - Add `persistAndBroadcastSession()` helper: combines persist + SessionUpdated broadcast into one call, replacing 5 repeated 2-line pairs
+  - Migrate session-routes.ts to use `findSessionOrFail()` consistently (17 inline session lookups replaced) and `parseBody()` (12 patterns)
+  - Migrate ralph-routes.ts to use `findSessionOrFail()` (9 lookups) and `parseBody()` (4 patterns)
+  - Migrate 8 remaining route files to use `parseBody()` (21 patterns total)
+  - Fix O(n log n) eviction in bash-tool-parser.ts: replace `Array.from().sort()[0]` with O(n) min-scan for oldest active tool
+  - Extract `_debouncedCall()` utility in frontend: replaces 4 manual debounce patterns (7 lines each → 1 line) in app.js, panels-ui.js, ralph-panel.js
+  - Net reduction: 208 lines removed across 16 files
+
 ## 0.5.0

 ### Minor Changes
@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 | Task | Command |
 |------|---------|
-| Dev server | `npx tsx src/index.ts web` |
+| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
 | Type check | `tsc --noEmit` |
 | Lint | `npm run lint` (fix: `npm run lint:fix`) |
 | Format | `npm run format` (check: `npm run format:check`) |
@@ -52,7 +52,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`

-**Version**: 0.5.0 (must match `package.json`)
+**Version**: 0.5.3 (must match `package.json`)

 ## Project Overview

@@ -78,7 +78,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | Production start | `npm run start` |
 | Production logs | `journalctl --user -u codeman-web -f` |

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

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

@@ -111,7 +111,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Plan** | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/claude-md.ts` | |
 | **Web** | `src/web/server.ts`, `src/web/sse-events.ts`, `src/web/routes/*.ts` (14 route modules + barrel), `src/web/route-helpers.ts`, `src/web/ports/*.ts`, `src/web/middleware/auth.ts`, `src/web/schemas.ts` | |
 | **Frontend** | `src/web/public/app.js` (~2.6K lines, core) + 5 infra modules (`constants.js`, `mobile-handlers.js`, `voice-input.js`, `notification-manager.js`, `keyboard-accessory.js`) + 7 domain modules (`terminal-ui.js`, `respawn-ui.js`, `ralph-panel.js`, `orchestrator-panel.js`, `settings-ui.js`, `panels-ui.js`, `session-ui.js`) + 4 feature modules (`ralph-wizard.js`, `api-client.js`, `subagent-windows.js`, `input-cjk.js`) + `sw.js` | |
-| **Types** | `src/types/index.ts` → 15 domain files | See `@fileoverview` in index.ts |
+| **Types** | `src/types/index.ts` → 14 domain files | See `@fileoverview` in index.ts |

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

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

 **Config**: `src/config/` — 9 files. Import from specific files, not barrel.

-**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks).
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap`, `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).

 ### Data Flow

@@ -1,6 +1,6 @@
 {
  "name": "aicodeman",
-  "version": "0.5.0",
+  "version": "0.5.3",
  "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
  "type": "module",
  "main": "dist/index.js",
@@ -498,10 +498,17 @@ export class BashToolParser extends EventEmitter<BashToolParserEvents> {

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

@@ -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
@@ -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;
    }
@@ -551,6 +551,14 @@ export interface RespawnEvents {
  respawnBlocked: (data: { reason: string; details: string }) => void;
 }

+/**
+ * Convert milliseconds to a non-negative whole number of seconds for countdown display.
+ * Rounds up so that e.g. 1200 ms shows as 2 s (never under-reports remaining time).
+ */
+function formatRemainingSeconds(ms: number): number {
+  return Math.max(0, Math.ceil(ms / 1000));
+}
+
 /** Default configuration values */
 const DEFAULT_CONFIG: RespawnConfig = {
  idleTimeoutMs: 10000, // 10 seconds of no activity after prompt (legacy, still used as fallback)
@@ -839,12 +847,25 @@ export class RespawnController extends EventEmitter {
  private validateConfig(): void {
    const c = this.config;

+    /**
+     * Validate that a timeout value is positive (or non-negative when allowZero is true).
+     * Falls back to the DEFAULT_CONFIG value if invalid.
+     */
+    const validatePositiveTimeout = (field: keyof RespawnConfig, allowZero = false): void => {
+      const value = c[field] as number;
+      const invalid = allowZero ? value < 0 : value <= 0;
+      if (invalid) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (c as any)[field] = DEFAULT_CONFIG[field];
+      }
+    };
+
    // Ensure timeouts are positive
-    if (c.idleTimeoutMs <= 0) c.idleTimeoutMs = DEFAULT_CONFIG.idleTimeoutMs;
-    if (c.completionConfirmMs <= 0) c.completionConfirmMs = DEFAULT_CONFIG.completionConfirmMs;
-    if (c.noOutputTimeoutMs <= 0) c.noOutputTimeoutMs = DEFAULT_CONFIG.noOutputTimeoutMs;
-    if (c.autoAcceptDelayMs < 0) c.autoAcceptDelayMs = DEFAULT_CONFIG.autoAcceptDelayMs;
-    if (c.interStepDelayMs <= 0) c.interStepDelayMs = DEFAULT_CONFIG.interStepDelayMs;
+    validatePositiveTimeout('idleTimeoutMs');
+    validatePositiveTimeout('completionConfirmMs');
+    validatePositiveTimeout('noOutputTimeoutMs');
+    validatePositiveTimeout('autoAcceptDelayMs', true);
+    validatePositiveTimeout('interStepDelayMs');

    // Ensure completion confirm doesn't exceed no-output timeout
    if (c.completionConfirmMs > c.noOutputTimeoutMs) {
@@ -852,14 +873,14 @@ export class RespawnController extends EventEmitter {
    }

    // Ensure AI check timeouts are positive
-    if (c.aiIdleCheckTimeoutMs <= 0) c.aiIdleCheckTimeoutMs = DEFAULT_CONFIG.aiIdleCheckTimeoutMs;
-    if (c.aiIdleCheckCooldownMs < 0) c.aiIdleCheckCooldownMs = DEFAULT_CONFIG.aiIdleCheckCooldownMs;
-    if (c.aiIdleCheckMaxContext <= 0) c.aiIdleCheckMaxContext = DEFAULT_CONFIG.aiIdleCheckMaxContext;
+    validatePositiveTimeout('aiIdleCheckTimeoutMs');
+    validatePositiveTimeout('aiIdleCheckCooldownMs', true);
+    validatePositiveTimeout('aiIdleCheckMaxContext');

    // Ensure plan check timeouts are positive
-    if (c.aiPlanCheckTimeoutMs <= 0) c.aiPlanCheckTimeoutMs = DEFAULT_CONFIG.aiPlanCheckTimeoutMs;
-    if (c.aiPlanCheckCooldownMs < 0) c.aiPlanCheckCooldownMs = DEFAULT_CONFIG.aiPlanCheckCooldownMs;
-    if (c.aiPlanCheckMaxContext <= 0) c.aiPlanCheckMaxContext = DEFAULT_CONFIG.aiPlanCheckMaxContext;
+    validatePositiveTimeout('aiPlanCheckTimeoutMs');
+    validatePositiveTimeout('aiPlanCheckCooldownMs', true);
+    validatePositiveTimeout('aiPlanCheckMaxContext');
  }

  /** Wire up AI checker events to controller events (removes existing listeners first to prevent duplicates) */
@@ -987,11 +1008,11 @@ export class RespawnController extends EventEmitter {
      waitingFor = 'AI verdict (IDLE or WORKING)';
    } else if (this._state === 'confirming_idle') {
      statusText = `Confirming idle (${confidence}% confidence)`;
-      waitingFor = `${Math.max(0, Math.ceil((this.config.completionConfirmMs - msSinceLastOutput) / 1000))}s more silence`;
+      waitingFor = `${formatRemainingSeconds(this.config.completionConfirmMs - msSinceLastOutput)}s more silence`;
    } else if (this._state === 'watching') {
      const aiState = this.aiChecker.getState();
      if (aiState.status === 'cooldown') {
-        const remaining = Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000);
+        const remaining = formatRemainingSeconds(this.aiChecker.getCooldownRemainingMs());
        statusText = `AI Check: WORKING (cooldown ${remaining}s)`;
        waitingFor = 'Cooldown to expire';
      } else if (completionMessageDetected) {
@@ -1798,24 +1819,28 @@ export class RespawnController extends EventEmitter {
      case 'sending_init':
      case 'sending_kickstart':
        // For sending states, retry the send
-        this.log('Recovery: returning to watching state');
-        this.setState('watching');
-        this.startNoOutputTimer();
-        this.startPreFilterTimer();
-        if (this.config.autoAcceptPrompts) {
-          this.startAutoAcceptTimer();
-        }
+        this.recoveryResetToWatching('returning to watching state');
        break;

      default:
        // Fallback: reset to watching
-        this.log('Recovery: fallback to watching state');
-        this.setState('watching');
-        this.startNoOutputTimer();
-        this.startPreFilterTimer();
-        if (this.config.autoAcceptPrompts) {
-          this.startAutoAcceptTimer();
-        }
+        this.recoveryResetToWatching('fallback to watching state');
+    }
+  }
+
+  /**
+   * Reset the controller to watching state during stuck-state recovery.
+   * Sets state to watching and restarts all detection timers.
+   *
+   * @param reason - Human-readable reason for the reset (logged)
+   */
+  private recoveryResetToWatching(reason: string): void {
+    this.log(`Recovery: ${reason}`);
+    this.setState('watching');
+    this.startNoOutputTimer();
+    this.startPreFilterTimer();
+    if (this.config.autoAcceptPrompts) {
+      this.startAutoAcceptTimer();
    }
  }

@@ -2051,7 +2076,7 @@ export class RespawnController extends EventEmitter {
    // If on cooldown, don't start check - wait for cooldown to expire
    if (this.aiChecker.isOnCooldown()) {
      this.log(
-        `AI check on cooldown (${Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000)}s remaining), waiting...`
+        `AI check on cooldown (${formatRemainingSeconds(this.aiChecker.getCooldownRemainingMs())}s remaining), waiting...`
      );
      return;
    }
@@ -2198,36 +2223,15 @@ export class RespawnController extends EventEmitter {
   * @fires planCheckStarted
   */
  private tryAutoAccept(): void {
-    // Only auto-accept in watching state (not during a respawn cycle)
-    if (this._state !== 'watching') return;
+    if (!this.canAutoAccept()) return;

-    // Don't auto-accept if a completion message was detected (normal idle handles it)
-    if (this.completionMessageTime !== null) return;
-
-    // Don't auto-accept if disabled
-    if (!this.config.autoAcceptPrompts) return;
-
-    // Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
-    if (!this.hasReceivedOutput) return;
-
-    // Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
-    if (this.elicitationDetected) {
-      this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
-      return;
-    }
-
-    // Stage 1: Pre-filter — check if buffer looks like plan mode
    const buffer = this.terminalBuffer.value;
-    if (!this.isPlanModePreFilterMatch(buffer)) {
-      this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
-      return;
-    }

    // Stage 2: AI confirmation (if enabled and available)
    if (this.config.aiPlanCheckEnabled && this.planChecker.status !== 'disabled') {
      if (this.planChecker.isOnCooldown()) {
        this.log(
-          `Skipping auto-accept: plan checker on cooldown (${Math.ceil(this.planChecker.getCooldownRemainingMs() / 1000)}s remaining)`
+          `Skipping auto-accept: plan checker on cooldown (${formatRemainingSeconds(this.planChecker.getCooldownRemainingMs())}s remaining)`
        );
        return;
      }
@@ -2244,6 +2248,40 @@ export class RespawnController extends EventEmitter {
    this.sendAutoAcceptEnter();
  }

+  /**
+   * Check whether all preconditions for auto-accept are met.
+   * Validates state, config, and pre-filter conditions before attempting auto-accept.
+   *
+   * @returns True if auto-accept should proceed to the AI confirmation stage
+   */
+  private canAutoAccept(): boolean {
+    // Only auto-accept in watching state (not during a respawn cycle)
+    if (this._state !== 'watching') return false;
+
+    // Don't auto-accept if a completion message was detected (normal idle handles it)
+    if (this.completionMessageTime !== null) return false;
+
+    // Don't auto-accept if disabled
+    if (!this.config.autoAcceptPrompts) return false;
+
+    // Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
+    if (!this.hasReceivedOutput) return false;
+
+    // Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
+    if (this.elicitationDetected) {
+      this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
+      return false;
+    }
+
+    // Stage 1: Pre-filter — check if buffer looks like plan mode
+    if (!this.isPlanModePreFilterMatch(this.terminalBuffer.value)) {
+      this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
+      return false;
+    }
+
+    return true;
+  }
+
  /**
   * Check if the terminal buffer matches plan mode pre-filter patterns.
   * Only checks the last 2000 chars (plan mode UI appears at the bottom).
@@ -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
+        );
      }
    }
  }
@@ -876,13 +876,7 @@ export class Session extends EventEmitter {
      throw new Error('Session already has a running process');
    }

-    this._status = 'busy';
-    this._terminalBuffer.clear();
-    this._textOutput.clear();
-    this._errorBuffer = '';
-    this._messages = [];
-    this._lineBuffer = '';
-    this._lastActivityAt = Date.now();
+    this._resetBuffers();

    const modeLabel = this.mode === 'opencode' ? 'OpenCode' : 'Claude';
    console.log(
@@ -1257,13 +1251,7 @@ export class Session extends EventEmitter {
      throw new Error('Session already has a running process');
    }

-    this._status = 'busy';
-    this._terminalBuffer.clear();
-    this._textOutput.clear();
-    this._errorBuffer = '';
-    this._messages = [];
-    this._lineBuffer = '';
-    this._lastActivityAt = Date.now();
+    this._resetBuffers();

    // Use user's default shell or bash
    const shell = process.env.SHELL || '/bin/bash';
@@ -1448,13 +1436,7 @@ export class Session extends EventEmitter {
        return;
      }

-      this._status = 'busy';
-      this._terminalBuffer.clear();
-      this._textOutput.clear();
-      this._errorBuffer = '';
-      this._messages = [];
-      this._lineBuffer = '';
-      this._lastActivityAt = Date.now();
+      this._resetBuffers();
      this._promptResolved = false; // Reset race condition guard

      this.resolvePromise = resolve;
@@ -1565,6 +1547,117 @@ export class Session extends EventEmitter {
    });
  }

+  private _resetBuffers(): void {
+    this._status = 'busy';
+    this._terminalBuffer.clear();
+    this._textOutput.clear();
+    this._errorBuffer = '';
+    this._messages = [];
+    this._lineBuffer = '';
+    this._lastActivityAt = Date.now();
+  }
+
+  private _clearAllTimers(): void {
+    // Clear activity timeout to prevent memory leak
+    if (this.activityTimeout) {
+      clearTimeout(this.activityTimeout);
+      this.activityTimeout = null;
+    }
+
+    // Clear line buffer flush timer
+    if (this._lineBufferFlushTimer) {
+      clearTimeout(this._lineBufferFlushTimer);
+      this._lineBufferFlushTimer = null;
+    }
+
+    // Destroy auto-compact/auto-clear automation (clears its timers)
+    this._autoOps.destroy();
+
+    // Clear prompt check timers
+    if (this._promptCheckInterval) {
+      clearInterval(this._promptCheckInterval);
+      this._promptCheckInterval = null;
+    }
+    if (this._promptCheckTimeout) {
+      clearTimeout(this._promptCheckTimeout);
+      this._promptCheckTimeout = null;
+    }
+
+    // Clear shell idle timer
+    if (this._shellIdleTimer) {
+      clearTimeout(this._shellIdleTimer);
+      this._shellIdleTimer = null;
+    }
+
+    // Clear expensive processing timer
+    if (this._expensiveProcessTimer) {
+      clearTimeout(this._expensiveProcessTimer);
+      this._expensiveProcessTimer = null;
+    }
+    this._pendingCleanData = '';
+  }
+
+  private _handleJsonMessage(cleanLine: string, rawLine: string): void {
+    try {
+      const msg = JSON.parse(cleanLine) as ClaudeMessage;
+      this._messages.push(msg);
+      this.emit('message', msg);
+
+      // Trim messages array for long-running sessions
+      if (this._messages.length > MAX_MESSAGES) {
+        this._messages = this._messages.slice(-Math.floor(MAX_MESSAGES * 0.8));
+      }
+
+      // Extract Claude session ID from messages (can be in any message type)
+      // Support both sessionId (camelCase) and session_id (snake_case)
+      const msgSessionId =
+        ((msg as unknown as Record<string, unknown>).sessionId as string | undefined) ?? msg.session_id;
+      if (msgSessionId && !this._claudeSessionId) {
+        this._claudeSessionId = msgSessionId;
+      }
+
+      // Process message for task tracking
+      this._taskTracker.processMessage(msg);
+
+      if (msg.type === 'assistant' && msg.message?.content) {
+        for (const block of msg.message.content) {
+          if (block.type === 'text' && block.text) {
+            this._textOutput.append(block.text);
+          }
+        }
+        // Track tokens from usage (with validation)
+        if (msg.message.usage) {
+          const inputDelta = msg.message.usage.input_tokens || 0;
+          const outputDelta = msg.message.usage.output_tokens || 0;
+
+          // Sanity check: max 100k tokens per message (generous limit)
+          const MAX_TOKENS_PER_MESSAGE = 100_000;
+          if (inputDelta > 0 && inputDelta <= MAX_TOKENS_PER_MESSAGE) {
+            this._totalInputTokens += inputDelta;
+          }
+          if (outputDelta > 0 && outputDelta <= MAX_TOKENS_PER_MESSAGE) {
+            this._totalOutputTokens += outputDelta;
+          }
+
+          // Check if we should auto-compact or auto-clear
+          this._autoOps.checkAutoCompact();
+          this._autoOps.checkAutoClear();
+        }
+      }
+
+      if (msg.type === 'result' && msg.total_cost_usd) {
+        this._totalCost = msg.total_cost_usd;
+      }
+    } catch (parseErr) {
+      // Not JSON, just regular output - this is expected for non-JSON lines
+      console.debug(
+        '[Session] Line not JSON (expected for text output):',
+        parseErr instanceof Error ? parseErr.message : parseErr
+      );
+      this._textOutput.append(rawLine + '\n');
+    }
+  }
+
  private processOutput(data: string): void {
    // Early return if session is stopped to prevent any processing or timer creation
    if (this._isStopped) return;
@@ -1606,64 +1699,7 @@ export class Session extends EventEmitter {
      const cleanLine = trimmed.replace(ANSI_ESCAPE_PATTERN_FULL, '');

      if (cleanLine.startsWith('{') && cleanLine.endsWith('}')) {
-        try {
-          const msg = JSON.parse(cleanLine) as ClaudeMessage;
-          this._messages.push(msg);
-          this.emit('message', msg);
-
-          // Trim messages array for long-running sessions
-          if (this._messages.length > MAX_MESSAGES) {
-            this._messages = this._messages.slice(-Math.floor(MAX_MESSAGES * 0.8));
-          }
-
-          // Extract Claude session ID from messages (can be in any message type)
-          // Support both sessionId (camelCase) and session_id (snake_case)
-          const msgSessionId =
-            ((msg as unknown as Record<string, unknown>).sessionId as string | undefined) ?? msg.session_id;
-          if (msgSessionId && !this._claudeSessionId) {
-            this._claudeSessionId = msgSessionId;
-          }
-
-          // Process message for task tracking
-          this._taskTracker.processMessage(msg);
-
-          if (msg.type === 'assistant' && msg.message?.content) {
-            for (const block of msg.message.content) {
-              if (block.type === 'text' && block.text) {
-                this._textOutput.append(block.text);
-              }
-            }
-            // Track tokens from usage (with validation)
-            if (msg.message.usage) {
-              const inputDelta = msg.message.usage.input_tokens || 0;
-              const outputDelta = msg.message.usage.output_tokens || 0;
-
-              // Sanity check: max 100k tokens per message (generous limit)
-              const MAX_TOKENS_PER_MESSAGE = 100_000;
-              if (inputDelta > 0 && inputDelta <= MAX_TOKENS_PER_MESSAGE) {
-                this._totalInputTokens += inputDelta;
-              }
-              if (outputDelta > 0 && outputDelta <= MAX_TOKENS_PER_MESSAGE) {
-                this._totalOutputTokens += outputDelta;
-              }
-
-              // Check if we should auto-compact or auto-clear
-              this._autoOps.checkAutoCompact();
-              this._autoOps.checkAutoClear();
-            }
-          }
-
-          if (msg.type === 'result' && msg.total_cost_usd) {
-            this._totalCost = msg.total_cost_usd;
-          }
-        } catch (parseErr) {
-          // Not JSON, just regular output - this is expected for non-JSON lines
-          console.debug(
-            '[Session] Line not JSON (expected for text output):',
-            parseErr instanceof Error ? parseErr.message : parseErr
-          );
-          this._textOutput.append(line + '\n');
-        }
+        this._handleJsonMessage(cleanLine, line);
      } else if (trimmed) {
        this._textOutput.append(line + '\n');
      }
@@ -2030,43 +2066,7 @@ export class Session extends EventEmitter {
    // Set stopped flag first to prevent new timers from being created
    this._isStopped = true;

-    // Clear activity timeout to prevent memory leak
-    if (this.activityTimeout) {
-      clearTimeout(this.activityTimeout);
-      this.activityTimeout = null;
-    }
-
-    // Clear line buffer flush timer
-    if (this._lineBufferFlushTimer) {
-      clearTimeout(this._lineBufferFlushTimer);
-      this._lineBufferFlushTimer = null;
-    }
-
-    // Destroy auto-compact/auto-clear automation (clears its timers)
-    this._autoOps.destroy();
-
-    // Clear prompt check timers
-    if (this._promptCheckInterval) {
-      clearInterval(this._promptCheckInterval);
-      this._promptCheckInterval = null;
-    }
-    if (this._promptCheckTimeout) {
-      clearTimeout(this._promptCheckTimeout);
-      this._promptCheckTimeout = null;
-    }
-
-    // Clear shell idle timer
-    if (this._shellIdleTimer) {
-      clearTimeout(this._shellIdleTimer);
-      this._shellIdleTimer = null;
-    }
-
-    // Clear expensive processing timer
-    if (this._expensiveProcessTimer) {
-      clearTimeout(this._expensiveProcessTimer);
-      this._expensiveProcessTimer = null;
-    }
-    this._pendingCleanData = '';
+    this._clearAllTimers();

    // Immediately cleanup Promise callbacks to prevent orphaned references
    // during the rest of stop() processing (e.g., if mux kill times out)
@@ -195,16 +195,7 @@ export class StateStore {
   * Only dirty sessions are re-serialized; clean sessions use cached JSON fragments.
   */
  private assembleStateJson(): string {
-    // Re-serialize dirty sessions and update cache
-    for (const id of this.dirtySessions) {
-      const session = this.state.sessions[id];
-      if (session) {
-        this.cachedSessionJsons.set(id, JSON.stringify(session));
-      } else {
-        this.cachedSessionJsons.delete(id);
-      }
-    }
-    this.dirtySessions.clear();
+    this.updateDirtySessionCache();

    // Build sessions object from cached fragments
    const sessionParts: string[] = [];
@@ -218,6 +209,25 @@ export class StateStore {
      sessionParts.push(`${JSON.stringify(id)}:${json}`);
    }

+    this.pruneStaleCacheEntries();
+
+    return this.buildPartialJson(sessionParts);
+  }
+
+  private updateDirtySessionCache(): void {
+    // Re-serialize dirty sessions and update cache
+    for (const id of this.dirtySessions) {
+      const session = this.state.sessions[id];
+      if (session) {
+        this.cachedSessionJsons.set(id, JSON.stringify(session));
+      } else {
+        this.cachedSessionJsons.delete(id);
+      }
+    }
+    this.dirtySessions.clear();
+  }
+
+  private pruneStaleCacheEntries(): void {
    // Prune stale cache entries (sessions removed via direct state mutation)
    if (this.cachedSessionJsons.size > Object.keys(this.state.sessions).length) {
      for (const cachedId of this.cachedSessionJsons.keys()) {
@@ -226,7 +236,9 @@ export class StateStore {
        }
      }
    }
+  }

+  private buildPartialJson(sessionParts: string[]): string {
    // Build final JSON: sessions from cache, everything else re-serialized (tiny)
    const sessionsJson = `{${sessionParts.join(',')}}`;

@@ -249,6 +261,28 @@ export class StateStore {
    return `{${parts.join(',')}}`;
  }

+  private serializeState(): string | null {
+    try {
+      return this.assembleStateJson();
+    } catch (assembleErr) {
+      // Fallback to full serialization if incremental assembly fails
+      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
+      this.cachedSessionJsons.clear();
+      this.dirtySessions.clear();
+      try {
+        return JSON.stringify(this.state);
+      } catch (err) {
+        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
+        this.consecutiveSaveFailures++;
+        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
+          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
+          this.circuitBreakerOpen = true;
+        }
+        return null;
+      }
+    }
+  }
+
  private async _doSaveAsync(): Promise<void> {
    this.saveDeb.cancel();
    if (!this.dirty) {
@@ -265,28 +299,10 @@ export class StateStore {

    const tempPath = this.filePath + '.tmp';
    const backupPath = this.filePath + '.bak';
-    let json: string;

    // Step 1: Serialize state (validates it's JSON-safe)
-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;

    // Clear dirty flag BEFORE async I/O so mutations during write re-set it.
    // The state snapshot is already captured in `json` above.
@@ -351,27 +367,9 @@ export class StateStore {

    const tempPath = this.filePath + '.tmp';
    const backupPath = this.filePath + '.bak';
-    let json: string;

-    try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
-      }
-    }
+    const json = this.serializeState();
+    if (json === null) return;

    // Backup via atomic copy (avoids reading entire file into memory)
    try {
@@ -222,6 +222,83 @@ export class SubagentWatcher extends EventEmitter {
    return INTERNAL_AGENT_PATTERNS.some((pattern) => pattern.test(description));
  }

+  /**
+   * Mark a subagent as completed: clear PID, set status, clean up pending tool calls, emit event.
+   */
+  private markSubagentAsCompleted(info: SubagentInfo): void {
+    info.pid = undefined;
+    info.status = 'completed';
+    this.pendingToolCalls.delete(info.agentId);
+    this.emit('subagent:completed', info);
+  }
+
+  /**
+   * Extract text from message content, handling both string and array formats.
+   * For array content, returns the text from the first 'text' block.
+   */
+  private extractFirstTextContent(
+    content: string | Array<{ type: string; text?: string }> | undefined
+  ): string | undefined {
+    if (!content) return undefined;
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+      return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (Array.isArray(content)) {
+      const firstContent = content[0];
+      if (firstContent?.type === 'text' && firstContent.text) {
+        const trimmed = firstContent.text.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Process a tool_result content block: look up pending tool call, emit tool_result event.
+   */
+  private emitToolResult(
+    content: { tool_use_id: string; content?: string | Array<{ type: string; text?: string }>; is_error?: boolean },
+    agentId: string,
+    sessionId: string,
+    timestamp: string
+  ): void {
+    const resultContent = this.extractToolResultContent(content.content);
+    const agentPendingCalls = this.pendingToolCalls.get(agentId);
+    const pendingCall = agentPendingCalls?.get(content.tool_use_id);
+    const toolName = pendingCall?.toolName;
+    // Delete after lookup to prevent memory leak
+    agentPendingCalls?.delete(content.tool_use_id);
+
+    const toolResult: SubagentToolResult = {
+      agentId,
+      sessionId,
+      timestamp,
+      toolUseId: content.tool_use_id,
+      tool: toolName,
+      preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
+      contentLength: resultContent.length,
+      isError: content.is_error || false,
+    };
+    this.emit('subagent:tool_result', toolResult);
+  }
+
+  /**
+   * Find the oldest inactive (non-active) agent for LRU eviction.
+   * Returns the agent ID of the oldest inactive agent, or null if all are active.
+   */
+  private findOldestInactiveAgent(): string | null {
+    let oldestId: string | null = null;
+    let oldestTime = Infinity;
+    for (const [id, existing] of this.agentInfo) {
+      if (existing.status !== 'active' && existing.lastActivityAt < oldestTime) {
+        oldestTime = existing.lastActivityAt;
+        oldestId = id;
+      }
+    }
+    return oldestId;
+  }
+
  /**
   * Extract short model identifier from full model name
   */
@@ -307,10 +384,7 @@ export class SubagentWatcher extends EventEmitter {

              const alive = this.checkSubagentAliveFromPidMap(info, pidMap);
              if (!alive) {
-                info.pid = undefined;
-                info.status = 'completed';
-                this.pendingToolCalls.delete(info.agentId);
-                this.emit('subagent:completed', info);
+                this.markSubagentAsCompleted(info);
              }
            }
          }
@@ -677,10 +751,7 @@ export class SubagentWatcher extends EventEmitter {
      const pid = await this.findSubagentProcess(info.sessionId);
      if (pid) {
        process.kill(pid, 'SIGTERM');
-        info.pid = undefined;
-        info.status = 'completed';
-        this.pendingToolCalls.delete(info.agentId);
-        this.emit('subagent:completed', info);
+        this.markSubagentAsCompleted(info);
        return true;
      }
    } catch {
@@ -688,10 +759,7 @@ export class SubagentWatcher extends EventEmitter {
    }

    // Mark as completed even if we couldn't find the process
-    info.pid = undefined;
-    info.status = 'completed';
-    this.pendingToolCalls.delete(info.agentId);
-    this.emit('subagent:completed', info);
+    this.markSubagentAsCompleted(info);
    return true;
  }

@@ -843,19 +911,9 @@ export class SubagentWatcher extends EventEmitter {
        }
      } else if (entry.type === 'user' && entry.message?.content) {
        // Handle both string and array content formats
-        if (typeof entry.message.content === 'string') {
-          const text = entry.message.content.trim();
-          if (text.length < 100 && !text.includes('{')) {
-            lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
-          }
-        } else {
-          const firstContent = entry.message.content[0];
-          if (firstContent?.type === 'text' && firstContent.text) {
-            const text = firstContent.text.trim();
-            if (text.length < 100 && !text.includes('{')) {
-              lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
-            }
-          }
+        const text = this.extractFirstTextContent(entry.message.content);
+        if (text && text.length < 100 && !text.includes('{')) {
+          lines.push(`${this.formatTime(entry.timestamp)} 📥 User: ${text.substring(0, USER_TEXT_PREVIEW_LENGTH)}`);
        }
      }
    }
@@ -1027,15 +1085,7 @@ export class SubagentWatcher extends EventEmitter {
          try {
            const entry = JSON.parse(line);
            if (entry.type === 'user' && entry.message?.content) {
-              let text: string | undefined;
-              if (typeof entry.message.content === 'string') {
-                text = entry.message.content.trim();
-              } else if (Array.isArray(entry.message.content)) {
-                const firstContent = entry.message.content[0];
-                if (firstContent?.type === 'text' && firstContent.text) {
-                  text = firstContent.text.trim();
-                }
-              }
+              const text = this.extractFirstTextContent(entry.message.content);
              if (text) {
                resolved = true;
                rl.close();
@@ -1286,14 +1336,7 @@ export class SubagentWatcher extends EventEmitter {

    // Enforce MAX_TRACKED_AGENTS during insertion — evict oldest inactive agent
    if (this.agentInfo.size >= MAX_TRACKED_AGENTS) {
-      let oldestId: string | null = null;
-      let oldestTime = Infinity;
-      for (const [id, existing] of this.agentInfo) {
-        if (existing.status !== 'active' && existing.lastActivityAt < oldestTime) {
-          oldestTime = existing.lastActivityAt;
-          oldestId = id;
-        }
-      }
+      const oldestId = this.findOldestInactiveAgent();
      if (oldestId) {
        this.removeAgent(oldestId);
      }
@@ -1386,15 +1429,7 @@ export class SubagentWatcher extends EventEmitter {
      let description = await this.extractDescriptionFromParentTranscript(info.projectHash, info.sessionId, agentId);
      // Fallback: extract smart title from the prompt content
      if (!description) {
-        let text: string | undefined;
-        if (typeof entry.message.content === 'string') {
-          text = entry.message.content.trim();
-        } else if (Array.isArray(entry.message.content)) {
-          const firstContent = entry.message.content[0];
-          if (firstContent?.type === 'text' && firstContent.text) {
-            text = firstContent.text.trim();
-          }
-        }
+        const text = this.extractFirstTextContent(entry.message.content);
        if (text) {
          description = this.extractSmartTitle(text);
        }
@@ -1480,24 +1515,12 @@ export class SubagentWatcher extends EventEmitter {
            }
          } else if (content.type === 'tool_result' && content.tool_use_id) {
            // Extract tool result
-            const resultContent = this.extractToolResultContent(content.content);
-            const agentPendingCalls = this.pendingToolCalls.get(agentId);
-            const pendingCall = agentPendingCalls?.get(content.tool_use_id);
-            const toolName = pendingCall?.toolName;
-            // Delete after lookup to prevent memory leak
-            agentPendingCalls?.delete(content.tool_use_id);
-
-            const toolResult: SubagentToolResult = {
+            this.emitToolResult(
+              { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
              agentId,
              sessionId,
-              timestamp: entry.timestamp,
-              toolUseId: content.tool_use_id,
-              tool: toolName,
-              preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
-              contentLength: resultContent.length,
-              isError: content.is_error || false,
-            };
-            this.emit('subagent:tool_result', toolResult);
+              entry.timestamp
+            );
          } else if (content.type === 'text' && content.text) {
            const text = content.text.trim();
            if (text.length > 0) {
@@ -1531,24 +1554,12 @@ export class SubagentWatcher extends EventEmitter {
        // Check for tool_result blocks in user messages (common pattern)
        for (const content of entry.message.content) {
          if (content.type === 'tool_result' && content.tool_use_id) {
-            const resultContent = this.extractToolResultContent(content.content);
-            const agentPendingCalls = this.pendingToolCalls.get(agentId);
-            const pendingCall = agentPendingCalls?.get(content.tool_use_id);
-            const toolName = pendingCall?.toolName;
-            // Delete after lookup to prevent memory leak
-            agentPendingCalls?.delete(content.tool_use_id);
-
-            const toolResult: SubagentToolResult = {
+            this.emitToolResult(
+              { tool_use_id: content.tool_use_id, content: content.content, is_error: content.is_error },
              agentId,
              sessionId,
-              timestamp: entry.timestamp,
-              toolUseId: content.tool_use_id,
-              tool: toolName,
-              preview: resultContent.substring(0, MESSAGE_TEXT_LIMIT),
-              contentLength: resultContent.length,
-              isError: content.is_error || false,
-            };
-            this.emit('subagent:tool_result', toolResult);
+              entry.timestamp
+            );
          } else if (content.type === 'text' && content.text) {
            const userText = content.text.trim();
            if (userText.length > 0 && userText.length < 500) {
@@ -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)}`, {
@@ -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`);
@@ -1163,10 +1152,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 +1288,22 @@ class CodemanApp {
    });
  }

-  handleInit(data) {
-    // Clear the init fallback timer since we got data
-    if (this._initFallbackTimer) {
-      clearTimeout(this._initFallbackTimer);
-      this._initFallbackTimer = null;
-    }
-    const gen = ++this._initGeneration;
-
-    // CJK input form: show/hide based on server env INPUT_CJK_FORM=ON
+  /** Show/hide the CJK input textarea based on user setting or server override */
+  _updateCjkInputState() {
    const cjkEl = document.getElementById('cjkInput');
-    if (cjkEl) {
-      cjkEl.style.display = data.inputCjkForm ? 'block' : 'none';
-      if (!data.inputCjkForm) window.cjkActive = false;
-    }
-
-    // Update version displays (header and toolbar)
-    if (data.version) {
-      const versionEl = this.$('versionDisplay');
-      const headerVersionEl = this.$('headerVersion');
-      if (versionEl) {
-        versionEl.textContent = `v${data.version}`;
-        versionEl.title = `Codeman v${data.version}`;
-      }
-      if (headerVersionEl) {
-        headerVersionEl.textContent = `v${data.version}`;
-        headerVersionEl.title = `Codeman v${data.version}`;
-      }
-    }
-
-    // Stop any active voice recording on reconnect
-    VoiceInput.cleanup();
+    if (!cjkEl) return;
+    const settings = this.loadAppSettingsFromStorage();
+    const showCjk = this._serverCjkOverride || settings.cjkInputEnabled || false;
+    cjkEl.style.display = showCjk ? 'block' : 'none';
+    if (!showCjk) window.cjkActive = false;
+  }

+  /**
+   * Reset all app state maps, timers, and handlers to a clean baseline.
+   * Called by handleInit() on SSE reconnect / page reload to prevent
+   * memory leaks and stale data.
+   */
+  _resetAllAppState() {
    this.sessions.clear();
    this.ralphStates.clear();
    this.terminalBuffers.clear();
@@ -1347,17 +1317,11 @@ class CodemanApp {
    }
    this.idleTimers.clear();
    // Clear flicker filter state
-    if (this.flickerFilterTimeout) {
-      clearTimeout(this.flickerFilterTimeout);
-      this.flickerFilterTimeout = null;
-    }
+    this._clearTimer('flickerFilterTimeout');
    this.flickerFilterBuffer = '';
    this.flickerFilterActive = false;
    // Clear pending terminal writes
-    if (this.syncWaitTimeout) {
-      clearTimeout(this.syncWaitTimeout);
-      this.syncWaitTimeout = null;
-    }
+    this._clearTimer('syncWaitTimeout');
    this.pendingWrites = [];
    this.writeFrameScheduled = false;
    this._isLoadingBuffer = false;
@@ -1416,6 +1380,36 @@ class CodemanApp {
      clearInterval(this.runSummaryAutoRefreshTimer);
      this.runSummaryAutoRefreshTimer = null;
    }
+  }
+
+  handleInit(data) {
+    // Clear the init fallback timer since we got data
+    this._clearTimer('_initFallbackTimer');
+    const gen = ++this._initGeneration;
+
+    // CJK input form: controlled by user setting (with server env as override)
+    this._serverCjkOverride = data.inputCjkForm || false;
+    this._updateCjkInputState();
+
+    // Update version displays (header and toolbar)
+    if (data.version) {
+      const versionEl = this.$('versionDisplay');
+      const headerVersionEl = this.$('headerVersion');
+      if (versionEl) {
+        versionEl.textContent = `v${data.version}`;
+        versionEl.title = `Codeman v${data.version}`;
+      }
+      if (headerVersionEl) {
+        headerVersionEl.textContent = `v${data.version}`;
+        headerVersionEl.title = `Codeman v${data.version}`;
+      }
+    }
+
+    // Stop any active voice recording on reconnect
+    VoiceInput.cleanup();
+
+    this._resetAllAppState();
+
    data.sessions.forEach(s => {
      this.sessions.set(s.id, s);
      // Load ralph state from session data (only if not explicitly closed by user)
@@ -1543,18 +1537,27 @@ class CodemanApp {
    }
  }

+  // ═══════════════════════════════════════════════════════════════
+  // Debounce Utility
+  // ═══════════════════════════════════════════════════════════════
+
+  /** Debounce a method call using a named timer key. */
+  _debouncedCall(timerKey, fn, delayMs = 100) {
+    if (this._debounceTimers[timerKey]) {
+      clearTimeout(this._debounceTimers[timerKey]);
+    }
+    this._debounceTimers[timerKey] = setTimeout(() => {
+      this._debounceTimers[timerKey] = null;
+      fn.call(this);
+    }, delayMs);
+  }
+
  // ═══════════════════════════════════════════════════════════════
  // Session Tabs
  // ═══════════════════════════════════════════════════════════════

  renderSessionTabs() {
-    // Debounce renders at 100ms to prevent excessive DOM updates
-    if (this.renderSessionTabsTimeout) {
-      clearTimeout(this.renderSessionTabsTimeout);
-    }
-    this.renderSessionTabsTimeout = setTimeout(() => {
-      this._renderSessionTabsImmediate();
-    }, 100);
+    this._debouncedCall('sessionTabs', this._renderSessionTabsImmediate);
  }

  /** Toggle .active class on tabs immediately (no debounce). Used by selectSession(). */
@@ -1980,17 +1983,13 @@ 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
-
+  /**
+   * Clean up state from the previous session before switching tabs.
+   * Handles: WebSocket teardown, CJK clear, flicker filter, tab completion,
+   * terminal write queue, IME composition, and local echo flush.
+   * @param {string} newSessionId - The session being switched TO.
+   */
+  _cleanupPreviousSession(newSessionId) {
    // Close WebSocket for previous session (new one opens after buffer load)
    this._disconnectWs();

@@ -1999,10 +1998,7 @@ class CodemanApp {
    if (cjkEl) cjkEl.value = '';

    // Clean up flicker filter state when switching sessions
-    if (this.flickerFilterTimeout) {
-      clearTimeout(this.flickerFilterTimeout);
-      this.flickerFilterTimeout = null;
-    }
+    this._clearTimer('flickerFilterTimeout');
    this.flickerFilterBuffer = '';
    this.flickerFilterActive = false;

@@ -2010,14 +2006,11 @@ class CodemanApp {
    this._tabCompletionSessionId = null;
    this._tabCompletionRetries = 0;
    this._tabCompletionBaseText = null;
-    if (this._tabCompletionFallback) { clearTimeout(this._tabCompletionFallback); this._tabCompletionFallback = null; }
-    if (this._clientDropRecoveryTimer) { clearTimeout(this._clientDropRecoveryTimer); this._clientDropRecoveryTimer = null; }
+    this._clearTimer('_tabCompletionFallback');
+    this._clearTimer('_clientDropRecoveryTimer');

    // Clean up pending terminal writes to prevent old session data from appearing in new session
-    if (this.syncWaitTimeout) {
-      clearTimeout(this.syncWaitTimeout);
-      this.syncWaitTimeout = null;
-    }
+    this._clearTimer('syncWaitTimeout');
    this.pendingWrites = [];
    this.writeFrameScheduled = false;
    this._isLoadingBuffer = false;
@@ -2067,9 +2060,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();
@@ -2147,23 +2160,31 @@ class CodemanApp {
      // canvas may be at stale dimensions — content would render at wrong width.
      if (this.fitAddon) this.fitAddon.fit();

-      // Instant cache restore — show previous buffer via chunked write to avoid WebGL GPU stalls.
-      // Direct terminal.write() of large cached buffers (256KB+) can block the main thread
-      // for 5+ seconds while the WebGL renderer processes ReadPixels synchronously.
+      // Instant cache restore for IDLE sessions only.
+      // For busy sessions, the cache is always stale — writing it first causes a
+      // jarring double-render: stale content appears, then the terminal flashes
+      // blank and rewrites with fresh data. Skip the cache and write the fresh
+      // buffer once for a single clean transition.
      const cachedBuffer = this.terminalBufferCache.get(sessionId);
-      if (cachedBuffer) {
+      const sessionIsBusy = session && (session.status === 'busy' || session.status === 'working');
+      if (cachedBuffer && !sessionIsBusy) {
        _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
        this.terminal.clear();
        this.terminal.reset();
        await this.chunkedTerminalWrite(cachedBuffer);
-        if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
+        if (this._isStaleSelect(selectGen)) return;
        this.terminal.scrollToBottom();
        _crashDiag.log('CACHE_DONE');
+      } else if (sessionIsBusy) {
+        // Clear stale content immediately — fresh buffer is being fetched
+        this.terminal.clear();
+        this.terminal.reset();
+        _crashDiag.log('CACHE_SKIP_BUSY');
      }

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

@@ -2182,7 +2203,7 @@ class CodemanApp {
          }
          // Use chunked write for large buffers to avoid UI jank
          await this.chunkedTerminalWrite(data.terminalBuffer);
-          if (selectGen !== this._selectGeneration) { if (this._isLoadingBuffer) this._finishBufferLoad(); this._restoringFlushedState = false; return; }
+          if (this._isStaleSelect(selectGen)) return;
          // Ensure terminal is scrolled to bottom after buffer load
          this.terminal.scrollToBottom();
        }
@@ -2200,9 +2221,9 @@ class CodemanApp {
        this.terminal.reset();
      }

-      // Buffer load complete — unblock live SSE writes and flush any queued events.
-      // chunkedTerminalWrite calls _finishBufferLoad internally, but if we skipped
-      // the chunked write (small buffer, cache hit, or empty), we must call it here.
+      // Buffer load complete — unblock live SSE writes (queued events are discarded
+      // to prevent duplicate content). chunkedTerminalWrite calls _finishBufferLoad
+      // internally, but if we skipped the write (cache hit or empty), call it here.
      if (this._isLoadingBuffer) {
        this._finishBufferLoad();
      }
@@ -2226,9 +2247,19 @@ class CodemanApp {
        });
      }

-      // Fire-and-forget resize — don't await to avoid blocking UI.
-      // The resize triggers an Ink redraw in Claude which streams back via SSE.
-      this.sendResize(sessionId);
+      // Fire-and-forget resize + Ctrl+L to force Ink redraw.
+      // Tailed buffers accumulate stale CUP-positioned Ink frames that overlap
+      // in the viewport (e.g. duplicate "bypass permissions" bars). Ctrl+L
+      // triggers a full Ink redraw which overwrites all stale frame content.
+      // sendResize may be a no-op if dimensions match, so Ctrl+L is essential.
+      this.sendResize(sessionId).then(() => {
+        if (selectGen !== this._selectGeneration) return;
+        fetch(`/api/sessions/${sessionId}/input`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ input: '\x0c' })
+        }).catch(() => {});
+      });

      // Defer secondary panel updates so they don't block the main thread
      // after terminal content is already visible.
@@ -2579,9 +2610,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();
@@ -871,6 +871,16 @@
                  <span class="slider"></span>
                </label>
              </div>
+              <div class="settings-item settings-item-multiline" title="Show a dedicated input field below the terminal for CJK (Chinese/Japanese/Korean) IME composition. Recommended for mobile devices with Chinese input methods where xterm's native input handling may drop characters.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">CJK Input</span>
+                  <span class="settings-item-desc">Dedicated IME input field for CJK languages</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsCjkInput">
+                  <span class="slider"></span>
+                </label>
+              </div>

              <!-- Header Displays Section -->
              <div class="settings-section-header">Header Displays</div>
@@ -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;
    },

@@ -1147,6 +1147,7 @@ html.mobile-init .file-browser-panel {

  /* Compact welcome overlay for mobile */
  .welcome-content {
+    max-width: calc(100vw - 1.5rem);
    padding: 1rem 0.75rem;
  }

@@ -613,13 +613,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 +2968,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() {
@@ -471,13 +471,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() {
@@ -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
@@ -493,6 +492,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
@@ -364,6 +364,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');
@@ -1180,6 +1181,7 @@ 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,
@@ -1296,9 +1298,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 +1687,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
@@ -94,7 +94,11 @@ textarea:focus-visible {
  outline: none;
 }

-/* xterm.js hidden textarea — must never show focus ring or caret */
+/* xterm.js hidden textarea — must never show focus ring or caret.
+ * On mobile (touch devices), override xterm.css defaults that position the
+ * textarea at left:-9999em with width/height:0. iOS Safari ignores keyboard
+ * input to off-screen zero-size textareas, so we move it on-screen with a
+ * minimal size while keeping it visually invisible. */
 .xterm-helper-textarea {
  border: none !important;
  box-shadow: none !important;
@@ -102,6 +106,14 @@ textarea:focus-visible {
  opacity: 0 !important;
  caret-color: transparent !important;
 }
+.touch-device .xterm .xterm-helper-textarea {
+  left: 0 !important;
+  top: 0 !important;
+  width: 1px !important;
+  height: 1px !important;
+  z-index: -1 !important;
+  font-size: 16px !important; /* prevent iOS auto-zoom on focus */
+}

 /* Session tab focus */
 .session-tab:focus-visible {
@@ -64,7 +64,9 @@ Object.assign(CodemanApp.prototype, {
        const unicode11Addon = new Unicode11Addon.Unicode11Addon();
        this.terminal.loadAddon(unicode11Addon);
        this.terminal.unicode.activeVersion = '11';
-      } catch (_e) { /* Unicode11 addon failed — default Unicode handling used */ }
+      } catch (_e) {
+        /* Unicode11 addon failed — default Unicode handling used */
+      }
    }

    const container = document.getElementById('terminalContainer');
@@ -115,8 +117,8 @@ Object.assign(CodemanApp.prototype, {

    // On mobile Safari, delay initial fit() to allow layout to settle
    // This prevents 0-column terminals caused by fit() running before container is sized
-    const isMobileSafari = MobileDetection.getDeviceType() === 'mobile' &&
-                           document.body.classList.contains('safari-browser');
+    const isMobileSafari =
+      MobileDetection.getDeviceType() === 'mobile' && document.body.classList.contains('safari-browser');
    if (isMobileSafari) {
      // Wait for layout, then fit multiple times to ensure proper sizing
      requestAnimationFrame(() => {
@@ -133,11 +135,15 @@ Object.assign(CodemanApp.prototype, {

    // Always use mouse wheel for terminal scrollback, never forward to application.
    // Prevents Claude's Ink UI (plan mode selector) from capturing scroll as option navigation.
-    container.addEventListener('wheel', (ev) => {
-      ev.preventDefault();
-      const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
-      this.terminal.scrollLines(lines);
-    }, { passive: false });
+    container.addEventListener(
+      'wheel',
+      (ev) => {
+        ev.preventDefault();
+        const lines = Math.round(ev.deltaY / 25) || (ev.deltaY > 0 ? 1 : -1);
+        this.terminal.scrollLines(lines);
+      },
+      { passive: false }
+    );

    // Touch scrolling — use terminal.scrollLines() for all devices.
    // xterm.js DOM renderer doesn't populate xterm-viewport's scroll area,
@@ -145,8 +151,7 @@ Object.assign(CodemanApp.prototype, {
    // has nothing to scroll. Instead, convert touch deltas into scrollLines()
    // calls, matching the wheel handler above.
    {
-      const cellHeight = () =>
-        this.terminal._core?._renderService?.dimensions?.css?.cell?.height || 13;
+      const cellHeight = () => this.terminal._core?._renderService?.dimensions?.css?.cell?.height || 13;
      let touchLastY = 0;
      let velocity = 0;
      let lastTime = 0;
@@ -174,46 +179,65 @@ 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
@@ -267,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
@@ -281,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(() => {});
          }
        }
@@ -442,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;
@@ -457,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('', () => {
@@ -556,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);
@@ -573,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;
@@ -588,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);
@@ -625,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');
@@ -694,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');
@@ -762,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);
@@ -780,7 +851,6 @@ Object.assign(CodemanApp.prototype, {
    }
  },

-
  // ═══════════════════════════════════════════════════════════════
  // Terminal Rendering
  // ═══════════════════════════════════════════════════════════════
@@ -825,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;
@@ -893,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 });
      }
+    }
  },

  /**
@@ -950,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.
@@ -974,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) {
@@ -991,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('', () => {
@@ -1013,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 {
@@ -1085,7 +1168,9 @@ Object.assign(CodemanApp.prototype, {

        if (offset >= cleanBuffer.length) {
          const _totalMs = performance.now() - _chunkStart;
-          console.log(`[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`);
+          console.log(
+            `[CRASH-DIAG] chunkedTerminalWrite complete: ${cleanBuffer.length} bytes in ${_chunkCount} chunks, ${_totalMs.toFixed(0)}ms total`
+          );
          // Wait one more frame for xterm to finish rendering before resolving
          requestAnimationFrame(finish);
          return;
@@ -1096,7 +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
@@ -1109,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
  // ═══════════════════════════════════════════════════════════════
@@ -1157,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');
@@ -1184,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' }),
      });
    });
  },
@@ -1246,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),
    };
  },

@@ -1273,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),
    });
  },

@@ -1287,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
  // ═══════════════════════════════════════════════════════════════
@@ -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").
 */
@@ -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;
@@ -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)
@@ -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');
    }
@@ -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';

@@ -85,12 +86,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 +137,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 };
@@ -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 });
@@ -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');
    }
@@ -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);

@@ -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);
@@ -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) {
@@ -32,7 +32,15 @@ import {
  QuickRunSchema,
  QuickStartSchema,
 } from '../schemas.js';
-import { autoConfigureRalph, CASES_DIR, SETTINGS_PATH, validatePathWithinBase } from '../route-helpers.js';
+import {
+  autoConfigureRalph,
+  CASES_DIR,
+  findSessionOrFail,
+  parseBody,
+  persistAndBroadcastSession,
+  SETTINGS_PATH,
+  validatePathWithinBase,
+} from '../route-helpers.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { writeHooksConfig, updateCaseEnvVars } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
@@ -138,11 +146,7 @@ export function registerSessionRoutes(
      );
    }

-    const result = CreateSessionSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const body = result.data;
+    const body = parseBody(CreateSessionSchema, req.body);
    const workingDir = body.workingDir || process.cwd();

    // Validate workingDir exists and is a directory
@@ -210,23 +214,14 @@ export function registerSessionRoutes(

  app.put('/api/sessions/:id/name', async (req) => {
    const { id } = req.params as { id: string };
-    const result = SessionNameSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(SessionNameSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    const name = String(body.name || '').slice(0, MAX_SESSION_NAME_LENGTH);
    session.name = name;
    // Also update the mux session name if applicable
    ctx.mux.updateSessionName(id, session.name);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
    return { success: true, name: session.name };
  });

@@ -234,16 +229,8 @@ export function registerSessionRoutes(

  app.put('/api/sessions/:id/color', async (req) => {
    const { id } = req.params as { id: string };
-    const result = SessionColorSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(SessionColorSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    const validColors = ['default', 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink'];
    if (!validColors.includes(body.color)) {
@@ -251,8 +238,7 @@ export function registerSessionRoutes(
    }

    session.setColor(body.color as SessionColor);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);
    return { success: true, color: session.color };
  });

@@ -291,11 +277,7 @@ export function registerSessionRoutes(

  app.get('/api/sessions/:id', async (req) => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    // Use light state (no full buffers) — terminal buffer available via /terminal endpoint.
    // Full buffers were 2-3MB and caused slowness when polled frequently (e.g. Ralph wizard).
@@ -310,11 +292,7 @@ export function registerSessionRoutes(

  app.get('/api/sessions/:id/output', async (req) => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    return {
      success: true,
@@ -330,11 +308,7 @@ export function registerSessionRoutes(

  app.get('/api/sessions/:id/ralph-state', async (req) => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    return {
      success: true,
@@ -350,11 +324,7 @@ export function registerSessionRoutes(

  app.get('/api/sessions/:id/run-summary', async (req) => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    const tracker = ctx.runSummaryTrackers.get(id);
    if (!tracker) {
@@ -374,11 +344,7 @@ export function registerSessionRoutes(

  app.get('/api/sessions/:id/active-tools', async (req) => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    return {
      success: true,
@@ -396,16 +362,8 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/run', async (req): Promise<ApiResponse> => {
    const { id } = req.params as { id: string };
-    const result = RunPromptSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { prompt } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { prompt } = parseBody(RunPromptSchema, req.body);
+    const session = findSessionOrFail(ctx, id);

    if (session.isBusy()) {
      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -424,11 +382,7 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/interactive', async (req): Promise<ApiResponse> => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    if (session.isBusy()) {
      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -468,11 +422,7 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/shell', async (req): Promise<ApiResponse> => {
    const { id } = req.params as { id: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    if (session.isBusy()) {
      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
@@ -502,16 +452,8 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/input', async (req): Promise<ApiResponse> => {
    const { id } = req.params as { id: string };
-    const result = SessionInputWithLimitSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { input, useMux } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { input, useMux } = parseBody(SessionInputWithLimitSchema, req.body);
+    const session = findSessionOrFail(ctx, id);

    const inputStr = String(input);
    if (inputStr.length > MAX_INPUT_LENGTH) {
@@ -547,16 +489,8 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/resize', async (req): Promise<ApiResponse> => {
    const { id } = req.params as { id: string };
-    const result = ResizeSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { cols, rows } = result.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const { cols, rows } = parseBody(ResizeSchema, req.body);
+    const session = findSessionOrFail(ctx, id);

    session.resize(cols, rows);
    return { success: true };
@@ -569,11 +503,7 @@ export function registerSessionRoutes(
  app.get('/api/sessions/:id/terminal', async (req) => {
    const { id } = req.params as { id: string };
    const query = req.query as { tail?: string };
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const session = findSessionOrFail(ctx, id);

    const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
    const fullSize = session.terminalBufferLength;
@@ -632,20 +562,11 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/auto-clear', async (req) => {
    const { id } = req.params as { id: string };
-    const acResult = AutoClearSchema.safeParse(req.body);
-    if (!acResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = acResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(AutoClearSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    session.setAutoClear(body.enabled, body.threshold);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);

    return {
      success: true,
@@ -662,20 +583,11 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/auto-compact', async (req) => {
    const { id } = req.params as { id: string };
-    const compactResult = AutoCompactSchema.safeParse(req.body);
-    if (!compactResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = compactResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(AutoCompactSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    session.setAutoCompact(body.enabled, body.threshold, body.prompt);
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);

    return {
      success: true,
@@ -693,16 +605,8 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/image-watcher', async (req) => {
    const { id } = req.params as { id: string };
-    const iwResult = ImageWatcherSchema.safeParse(req.body);
-    if (!iwResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = iwResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(ImageWatcherSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    if (body.enabled) {
      imageWatcher.watchSession(session.id, session.workingDir);
@@ -726,20 +630,11 @@ export function registerSessionRoutes(

  app.post('/api/sessions/:id/flicker-filter', async (req) => {
    const { id } = req.params as { id: string };
-    const ffResult = FlickerFilterSchema.safeParse(req.body);
-    if (!ffResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = ffResult.data;
-    const session = ctx.sessions.get(id);
-
-    if (!session) {
-      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
-    }
+    const body = parseBody(FlickerFilterSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id);

    session.flickerFilterEnabled = body.enabled;
-    ctx.persistSessionState(session);
-    ctx.broadcast(SseEvent.SessionUpdated, ctx.getSessionStateWithRespawn(session));
+    persistAndBroadcastSession(ctx, session);

    return {
      success: true,
@@ -764,11 +659,7 @@ export function registerSessionRoutes(
      );
    }

-    const qrResult = QuickRunSchema.safeParse(req.body);
-    if (!qrResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const { prompt, workingDir } = qrResult.data;
+    const { prompt, workingDir } = parseBody(QuickRunSchema, req.body, 'Invalid request body');

    if (!prompt.trim()) {
      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'prompt is required');
@@ -824,11 +715,7 @@ export function registerSessionRoutes(
      );
    }

-    const result = QuickStartSchema.safeParse(req.body);
-    if (!result.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, result.error.issues[0]?.message ?? 'Validation failed');
-    }
-    const { caseName = 'testcase', mode = 'claude', openCodeConfig } = result.data;
+    const { caseName = 'testcase', mode = 'claude', openCodeConfig } = parseBody(QuickStartSchema, req.body);

    // Check OpenCode availability if requested
    if (mode === 'opencode') {
@@ -24,7 +24,7 @@ import {
 import { subagentWatcher } from '../../subagent-watcher.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
-import { findSessionOrFail, formatUptime, SETTINGS_PATH } from '../route-helpers.js';
+import { findSessionOrFail, formatUptime, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
@@ -324,11 +324,8 @@ export function registerSystemRoutes(
  });

  app.put('/api/config', async (req) => {
-    const parseResult = ConfigUpdateSchema.safeParse(req.body);
-    if (!parseResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Invalid config: ${parseResult.error.message}`);
-    }
-    ctx.store.setConfig(parseResult.data as Partial<ReturnType<typeof ctx.store.getConfig>>);
+    const configData = parseBody(ConfigUpdateSchema, req.body, 'Invalid config');
+    ctx.store.setConfig(configData as Partial<ReturnType<typeof ctx.store.getConfig>>);
    return { success: true, config: ctx.store.getConfig() };
  });

@@ -396,23 +393,11 @@ export function registerSystemRoutes(
  // ========== Settings ==========

  app.get('/api/settings', async () => {
-    try {
-      const content = await fs.readFile(SETTINGS_PATH, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read settings:', err);
-      }
-    }
-    return {};
+    return readJsonConfig(SETTINGS_PATH, 'settings', {});
  });

  app.put('/api/settings', async (req) => {
-    const settingsResult = SettingsUpdateSchema.safeParse(req.body);
-    if (!settingsResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid settings');
-    }
-    const settings = settingsResult.data as Record<string, unknown>;
+    const settings = parseBody(SettingsUpdateSchema, req.body, 'Invalid settings') as Record<string, unknown>;

    try {
      const dir = dirname(SETTINGS_PATH);
@@ -479,24 +464,12 @@ export function registerSystemRoutes(
  // ========== Model Configuration ==========

  app.get('/api/execution/model-config', async () => {
-    try {
-      const content = await fs.readFile(SETTINGS_PATH, 'utf-8');
-      const settings = JSON.parse(content);
-      return { success: true, data: settings.modelConfig || {} };
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read model config:', err);
-      }
-      return { success: true, data: {} };
-    }
+    const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'model config', {});
+    return { success: true, data: settings.modelConfig || {} };
  });

  app.put('/api/execution/model-config', async (req) => {
-    const mcResult = ModelConfigUpdateSchema.safeParse(req.body);
-    if (!mcResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid model config');
-    }
-    const modelConfig = mcResult.data as Record<string, unknown>;
+    const modelConfig = parseBody(ModelConfigUpdateSchema, req.body, 'Invalid model config') as Record<string, unknown>;

    try {
      let existingSettings: Record<string, unknown> = {};
@@ -536,11 +509,7 @@ export function registerSystemRoutes(
    const { id } = req.params as { id: string };
    const session = findSessionOrFail(ctx, id);

-    const clResult = CpuLimitSchema.safeParse(req.body);
-    if (!clResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body');
-    }
-    const body = clResult.data as Partial<NiceConfig>;
+    const body = parseBody(CpuLimitSchema, req.body, 'Invalid request body') as Partial<NiceConfig>;

    session.setNice(body);
    ctx.persistSessionState(session);
@@ -560,23 +529,11 @@ export function registerSystemRoutes(
  // ========== Subagent Window State Persistence ==========

  app.get('/api/subagent-window-states', async () => {
-    try {
-      const content = await fs.readFile(windowStatesPath, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read subagent window states:', err);
-      }
-    }
-    return { minimized: {}, open: [] };
+    return readJsonConfig(windowStatesPath, 'subagent window states', { minimized: {}, open: [] });
  });

  app.put('/api/subagent-window-states', async (req) => {
-    const swResult = SubagentWindowStatesSchema.safeParse(req.body);
-    if (!swResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid window states');
-    }
-    const states = swResult.data as Record<string, unknown>;
+    const states = parseBody(SubagentWindowStatesSchema, req.body, 'Invalid window states') as Record<string, unknown>;
    try {
      const dir = dirname(windowStatesPath);
      if (!existsSync(dir)) {
@@ -592,23 +549,11 @@ export function registerSystemRoutes(
  // ========== Subagent Parent Associations ==========

  app.get('/api/subagent-parents', async () => {
-    try {
-      const content = await fs.readFile(parentMapPath, 'utf-8');
-      return JSON.parse(content);
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        console.error('Failed to read subagent parent map:', err);
-      }
-    }
-    return {};
+    return readJsonConfig(parentMapPath, 'subagent parent map', {});
  });

  app.put('/api/subagent-parents', async (req) => {
-    const spResult = SubagentParentMapSchema.safeParse(req.body);
-    if (!spResult.success) {
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid parent map');
-    }
-    const parentMap = spResult.data;
+    const parentMap = parseBody(SubagentParentMapSchema, req.body, 'Invalid parent map');
    try {
      const dir = dirname(parentMapPath);
      if (!existsSync(dir)) {
@@ -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',
Author	SHA1	Message	Date
arkonandClaude Opus 4.6	93719b41cd	chore: version packages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-25 23:34:14 +01:00
arkonandClaude Opus 4.6	a448983be3	refactor: pass 2 — extract shared helpers and simplify patterns app.js: - Add _clearTimer() helper replacing 11 inline clearTimeout patterns - Add _isStaleSelect() helper for generation check + cleanup - Replace 11 keyboard shortcut if-blocks with data-driven lookup table - Extract _cleanupPreviousSession() from selectSession() (~75 lines) - Extract _resetAllAppState() from handleInit() (~75 lines) tmux-manager: - Extract buildEnvExports() eliminating duplication in createSession/respawnPane - Extract buildPathExport() for CLI path resolution - Extract _configureOpenCode() for OpenCode setup routes: - Add readJsonConfig() to route-helpers, replacing 5 inline JSON-read patterns - Add validateSessionFilePath() to route-helpers, replacing 2 identical path traversal validation blocks in file-routes session-auto-ops: - Convert executeWhenIdle() from 8 positional params to options object - Extract validateThreshold() for shared compact/clear validation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-25 23:32:28 +01:00
arkonandClaude Opus 4.6	3145eac6d9	refactor: extract helper methods to reduce duplication and improve readability DRY up repeated patterns across 7 core files: - state-store: extract serializeState() and split assembleStateJson() into 3 focused methods - session: extract _resetBuffers(), _clearAllTimers(), _handleJsonMessage() - ralph-tracker: extract completeAllTodos() (was 4x duplicated), emitValidationWarning(), similarity constants - subagent-watcher: extract markSubagentAsCompleted(), extractFirstTextContent(), emitToolResult(), findOldestInactiveAgent() - respawn-controller: extract recoveryResetToWatching(), canAutoAccept(), formatRemainingSeconds(), validatePositiveTimeout() - tmux-manager: replace 15 path.includes() checks with single UNSAFE_PATH_CHARS regex - session-auto-ops: extract executeWhenIdle() shared retry helper for checkAutoCompact/checkAutoClear Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-25 23:21:38 +01:00
arkonandClaude Opus 4.6	e3c609f5f0	test: add coverage for lastUsedCase partial update and strict schema rejection Tests that partial PUT /api/settings with just lastUsedCase works correctly and that including modelConfig triggers strict Zod schema rejection (the bug fixed in #49). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-25 13:39:47 +01:00
Tenggan Zhang	52e774f83c	fix: case selection not persisting across page refresh (#49 ) Thank you for the clean fix! The root cause analysis in the PR description was excellent — the strict Zod schema rejecting modelConfig during the GET-then-PUT pattern was a subtle bug.	2026-03-25 13:39:16 +01:00
arkon	82d08df53f	chore: version packages	2026-03-25 00:18:14 +01:00
arkonandClaude Opus 4.6	2709b2fe49	feat: make buffer size limits configurable via environment variables Allow overriding MAX_TERMINAL_BUFFER_SIZE, TRIM_TERMINAL_TO, MAX_TEXT_OUTPUT_SIZE, TRIM_TEXT_TO, and MAX_MESSAGES via CODEMAN_* env vars, falling back to existing defaults. Enables users with fewer sessions or more RAM to tune buffer sizes without patching source. Closes #48 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-24 18:40:40 +01:00
Ark0N	b1d3b27e5b	Merge pull request #47 from TeigenZhang/fix/mobile-cjk-input-and-layout fix: mobile CJK input, terminal flicker, and layout overflow	2026-03-24 18:22:48 +01:00
Teigen	47963b54fa	fix: mobile CJK input, terminal flicker, and layout overflow Terminal flicker: - Skip buffer-recovered/clear-terminal events during active buffer load to prevent competing clear+rewrite cycles (app.js) - Move viewport+scrollback clear inside dimension-change guard so resize without actual SIGWINCH doesn't blank the terminal (terminal-ui.js) - Sync _lastResizeDims on explicit resize to prevent redundant clears CJK input rewrite (input-cjk.js): - Use InputEvent.inputType to distinguish insertText (final) from insertCompositionText (tentative) — fixes Chinese punctuation and English text being swallowed during Android IME composition - Remove isComposing guard on Enter so it always sends - Phantom character (U+200B) keeps textarea non-empty so Android long-press backspace generates continuous deleteContentBackward events at the keyboard's native repeat rate CJK input settings: - Add "CJK Input" toggle in Settings > Input (index.html, settings-ui.js) - Store as device-specific setting (cjkInputEnabled), not synced to server - Replace INPUT_CJK_FORM env var dependency with user-controlled setting (env var still works as server override) Mobile layout: - Fix welcome screen overflow on phones by constraining .welcome-content to calc(100vw - 1.5rem) (mobile.css) - Move xterm helper textarea on-screen for touch devices to fix iOS keyboard input (styles.css) - Focus terminal synchronously in user-gesture context for iOS Safari keyboard activation (session-ui.js, app.js) - Refocus terminal on tap (not scroll) in touch handler (terminal-ui.js)	2026-03-24 09:22:06 +08:00
arkonandClaude Opus 4.6	b7c3c30c8c	fix: send Ctrl+L after tab switch to clear stale Ink CUP frames Tailed terminal buffers contain multiple CUP-positioned Ink frames from different time points. When replayed in xterm, old frames at viewport positions not covered by the latest frame persist as ghost content (e.g. duplicate "bypass permissions" bars). After buffer load, send Ctrl+L via the session input API to trigger a full Ink redraw, which overwrites all stale frame content with the correct current state. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-23 16:59:48 +01:00
arkonandClaude Opus 4.6	0d80524f10	fix: prevent duplicate terminal output on tab switch to busy sessions Two fixes for the tab-switching corruption bug: 1. _finishBufferLoad() now discards queued SSE events instead of flushing them. The loaded API buffer is the source of truth — queued events overlap with it, and flushing them writes duplicate Ink cursor-up redraws that corrupt the terminal display (garbled text, wrong cursor positions). 2. Skip stale cache write for busy sessions. When a session is actively working, the cache is always outdated — writing it first and then rewriting with the fresh API buffer caused a jarring double-render flash. Now busy sessions get a single clean clear+write transition. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-23 12:32:33 +01:00
arkonandClaude Opus 4.6	a9d83ec4e3	chore: version packages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-22 23:55:39 +01:00