chore: version packages

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

CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 | Task | Command |
 |------|---------|
-| Dev server | `npx tsx src/index.ts web` |
+| Dev server | `npm run dev` (or `npx tsx src/index.ts web`) |
 | Type check | `tsc --noEmit` |
 | Lint | `npm run lint` (fix: `npm run lint:fix`) |
 | Format | `npm run format` (check: `npm run format:check`) |
@@ -52,7 +52,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.5.2 (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/**`.
 

package.json

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

src/ralph-tracker.ts

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

src/respawn-controller.ts

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

src/session-auto-ops.ts

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

src/session.ts

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

src/state-store.ts

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

src/subagent-watcher.ts

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

src/tmux-manager.ts

@@ -98,6 +98,9 @@ const LEGACY_MUX_NAME_PATTERN = /^claudeman-[a-f0-9-]+$/;
 /** Regex to validate tmux pane targets (e.g., "%0", "%1", "0", "1") */
 const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;
 
+/** Characters unsafe in paths — shell metacharacters, quotes, and control chars */
+const UNSAFE_PATH_CHARS = /[;&|$`(){}<>'"\n\r]/;
+
 /**
  * Validates that a session name contains only safe characters.
  * Prevents command injection via malformed session IDs.
@@ -111,23 +114,7 @@ function isValidMuxName(name: string): boolean {
  * Prevents command injection via malformed paths.
  */
 function isValidPath(path: string): boolean {
-  if (
-    path.includes(';') ||
-    path.includes('&') ||
-    path.includes('|') ||
-    path.includes('$') ||
-    path.includes('`') ||
-    path.includes('(') ||
-    path.includes(')') ||
-    path.includes('{') ||
-    path.includes('}') ||
-    path.includes('<') ||
-    path.includes('>') ||
-    path.includes("'") ||
-    path.includes('"') ||
-    path.includes('\n') ||
-    path.includes('\r')
-  ) {
+  if (UNSAFE_PATH_CHARS.test(path)) {
     return false;
   }
   if (path.includes('..')) {
@@ -371,6 +358,52 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
   }
 
+  /**
+   * Build the array of environment export commands shared by createSession() and respawnPane().
+   * Includes locale, mux markers, session identity, and API URL.
+   */
+  private buildEnvExports(sessionId: string, muxName: string, mode: SessionMode): string[] {
+    const exports = [
+      'export LANG=en_US.UTF-8',
+      'export LC_ALL=en_US.UTF-8',
+      'unset COLORTERM',
+      'export CODEMAN_MUX=1',
+      `export CODEMAN_SESSION_ID=${sessionId}`,
+      `export CODEMAN_MUX_NAME=${muxName}`,
+      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
+    ];
+    // Only unset CLAUDECODE for Claude sessions
+    if (mode === 'claude') exports.splice(2, 0, 'unset CLAUDECODE');
+    return exports;
+  }
+
+  /**
+   * Resolve the CLI binary directory and return the PATH export prefix string.
+   * Returns '' if no override is needed (shell mode) or the binary dir is not found.
+   * In createSession(), a missing binary dir throws — the caller handles that separately.
+   */
+  private buildPathExport(mode: SessionMode): { pathExport: string; dir: string | null } {
+    if (mode === 'claude') {
+      const dir = findClaudeDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
+    if (mode === 'opencode') {
+      const dir = resolveOpenCodeDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
+    return { pathExport: '', dir: null };
+  }
+
+  /**
+   * Configure OpenCode-specific environment on a tmux session.
+   * Sets sensitive API keys and config content via tmux setenv
+   * (not visible in ps output or tmux history, inherited by panes).
+   */
+  private _configureOpenCode(muxName: string, openCodeConfig?: OpenCodeConfig): void {
+    setOpenCodeEnvVars(muxName);
+    setOpenCodeConfigContent(muxName, openCodeConfig);
+  }
+
   /**
    * Creates a new tmux session wrapping Claude CLI or a shell.
    * In test mode: creates an in-memory session only (no real tmux session).
@@ -415,33 +448,15 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     // Resolve CLI binary directory based on mode
-    let pathExport = '';
-    if (mode === 'claude') {
-      const claudeDir = findClaudeDir();
-      if (!claudeDir) {
-        throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
-      }
-      pathExport = `export PATH="${claudeDir}:$PATH" && `;
-    } else if (mode === 'opencode') {
-      const openCodeDir = resolveOpenCodeDir();
-      if (!openCodeDir) {
-        throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
-      }
-      pathExport = `export PATH="${openCodeDir}:$PATH" && `;
+    const { pathExport, dir: cliDir } = this.buildPathExport(mode);
+    if (mode === 'claude' && !cliDir) {
+      throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
+    }
+    if (mode === 'opencode' && !cliDir) {
+      throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
     }
 
-    const envExports = [
-      'export LANG=en_US.UTF-8',
-      'export LC_ALL=en_US.UTF-8',
-      'unset COLORTERM',
-      'export CODEMAN_MUX=1',
-      `export CODEMAN_SESSION_ID=${sessionId}`,
-      `export CODEMAN_MUX_NAME=${muxName}`,
-      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
-    ];
-    // Only unset CLAUDECODE for Claude sessions
-    if (mode === 'claude') envExports.splice(2, 0, 'unset CLAUDECODE');
-    const envExportsStr = envExports.join(' && ');
+    const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
     const baseCmd = buildSpawnCommand({
       mode,
@@ -489,8 +504,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // For OpenCode: set sensitive env vars and config via tmux setenv
       // (not visible in ps output or tmux history, inherited by panes)
       if (mode === 'opencode') {
-        setOpenCodeEnvVars(muxName);
-        setOpenCodeConfigContent(muxName, openCodeConfig);
+        this._configureOpenCode(muxName, openCodeConfig);
       }
 
       // Replace the shell with the actual command (no echo in terminal)
@@ -641,26 +655,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
 
     // Resolve CLI binary directory based on mode
-    let pathExport = '';
-    if (mode === 'claude') {
-      const claudeDir = findClaudeDir();
-      pathExport = claudeDir ? `export PATH="${claudeDir}:$PATH" && ` : '';
-    } else if (mode === 'opencode') {
-      const openCodeDir = resolveOpenCodeDir();
-      pathExport = openCodeDir ? `export PATH="${openCodeDir}:$PATH" && ` : '';
-    }
+    const { pathExport } = this.buildPathExport(mode);
 
-    const envExports = [
-      'export LANG=en_US.UTF-8',
-      'export LC_ALL=en_US.UTF-8',
-      'unset COLORTERM',
-      'export CODEMAN_MUX=1',
-      `export CODEMAN_SESSION_ID=${sessionId}`,
-      `export CODEMAN_MUX_NAME=${muxName}`,
-      `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
-    ];
-    if (mode === 'claude') envExports.splice(2, 0, 'unset CLAUDECODE');
-    const envExportsStr = envExports.join(' && ');
+    const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
     const baseCmd = buildSpawnCommand({
       mode,
@@ -678,8 +675,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     try {
       // For OpenCode: set sensitive env vars via tmux setenv before respawn
       if (mode === 'opencode') {
-        setOpenCodeEnvVars(muxName);
-        setOpenCodeConfigContent(muxName, openCodeConfig);
+        this._configureOpenCode(muxName, openCodeConfig);
       }
 
       await execAsync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {

src/web/public/app.js

@@ -432,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) {
@@ -588,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
 
@@ -682,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) {
@@ -742,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.
@@ -1168,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
@@ -1317,35 +1298,12 @@ class CodemanApp {
     if (!showCjk) window.cjkActive = false;
   }
 
-  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: 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();
-
+  /**
+   * 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();
@@ -1359,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;
@@ -1428,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)
@@ -2001,23 +1983,13 @@ class CodemanApp {
     return this.getShortId(session.id);
   }
 
-  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
-
+  /**
+   * 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();
 
@@ -2026,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;
 
@@ -2037,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;
@@ -2094,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();
@@ -2186,7 +2172,7 @@ class CodemanApp {
         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) {
@@ -2198,7 +2184,7 @@ class CodemanApp {
 
       _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}`);
 
@@ -2217,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();
         }
@@ -2624,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();

src/web/public/session-ui.js

@@ -109,16 +109,10 @@ Object.assign(CodemanApp.prototype, {
 
   async saveLastUsedCase(caseName) {
     try {
-      // Get current settings
-      const res = await fetch('/api/settings');
-      const settings = res.ok ? await res.json() : {};
-      // Update lastUsedCase
-      settings.lastUsedCase = caseName;
-      // Save back
       await fetch('/api/settings', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(settings)
+        body: JSON.stringify({ lastUsedCase: caseName })
       });
     } catch (err) {
       console.error('Failed to save last used case:', err);

src/web/route-helpers.ts

@@ -6,6 +6,8 @@
  */
 
 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';
@@ -33,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;
 

src/web/routes/case-routes.ts

@@ -14,7 +14,7 @@ import { ApiErrorCode, createErrorResponse, getErrorMessage } from '../../types.
 import { CreateCaseSchema, LinkCaseSchema } from '../schemas.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { writeHooksConfig } from '../../hooks-config.js';
-import { CASES_DIR, validatePathWithinBase, parseBody } 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. */

src/web/routes/file-routes.ts

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

src/web/routes/system-routes.ts

@@ -24,7 +24,7 @@ import {
 import { subagentWatcher } from '../../subagent-watcher.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
-import { findSessionOrFail, formatUptime, parseBody, 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';
@@ -393,15 +393,7 @@ 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) => {
@@ -472,16 +464,8 @@ 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) => {
@@ -545,15 +529,7 @@ 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) => {
@@ -573,15 +549,7 @@ 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) => {

test/routes/system-routes.test.ts

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