commandmate 0.2.6 → 0.2.8

package/README.md

@@ -132,6 +132,12 @@ A: It supports Claude Code and Codex CLI. Thanks to the extensible Strategy patt
 **Q: Can multiple people use it?**
 A: Currently designed for individual use. Simultaneous multi-user access is not supported.
 
+**Q: Session start fails after updating Claude CLI. What should I do?**
+A: If you switch between npm and standalone versions of Claude CLI, the path may change. CommandMate will automatically detect the new path on the next session start attempt. If you want to specify a custom path, set the `CLAUDE_PATH` environment variable in `.env` (e.g., `CLAUDE_PATH=/opt/homebrew/bin/claude`).
+
+**Q: Sessions fail to start when launching CommandMate from within Claude Code. Why?**
+A: Claude Code sets the `CLAUDECODE=1` environment variable to prevent nested sessions. CommandMate automatically removes this variable from tmux sessions, so sessions should start normally. If the issue persists, manually run `tmux set-environment -g -u CLAUDECODE` to clear it from tmux's global environment.
+
 ## Documentation
 
 | Document | Description |

package/dist/cli/utils/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/daemon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOtD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAY;gBAEd,WAAW,EAAE,MAAM;IAK/B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA6EnD;;;;OAIG;IACG,IAAI,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BpD;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA6B/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;OAEG;YACW,WAAW;CAiB1B"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/daemon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOtD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAY;gBAEd,WAAW,EAAE,MAAM;IAK/B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAiFnD;;;;OAIG;IACG,IAAI,CAAC,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BpD;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA6B/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;OAEG;YACW,WAAW;CAiB1B"}

package/dist/cli/utils/daemon.js

@@ -53,6 +53,9 @@ class DaemonManager {
             ...process.env,
             ...(envResult.parsed || {}),
         };
+        // SF-003: Remove CLAUDECODE from env object to prevent nested session detection
+        // Uses env object (not process.env) to avoid global side effects (DIP)
+        delete env.CLAUDECODE;
         // Command line options override .env values
         if (options.port) {
             env.CM_PORT = String(options.port);

package/dist/server/src/lib/claude-session.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLAUDE_PROMPT_POLL_INTERVAL = exports.CLAUDE_SEND_PROMPT_WAIT_TIMEOUT = exports.CLAUDE_PROMPT_WAIT_TIMEOUT = exports.CLAUDE_POST_PROMPT_DELAY = exports.CLAUDE_INIT_POLL_INTERVAL = exports.CLAUDE_INIT_TIMEOUT = void 0;
+exports.clearCachedClaudePath = clearCachedClaudePath;
 exports.getSessionName = getSessionName;
 exports.isClaudeInstalled = isClaudeInstalled;
 exports.isClaudeRunning = isClaudeRunning;
@@ -20,6 +21,7 @@ const cli_patterns_1 = require("./cli-patterns");
 const pasted_text_helper_1 = require("./pasted-text-helper");
 const child_process_1 = require("child_process");
 const util_1 = require("util");
+const promises_1 = require("fs/promises");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 // ----- Helper Functions -----
 /**
@@ -32,6 +34,24 @@ const execAsync = (0, util_1.promisify)(child_process_1.exec);
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+// ----- Shell Prompt Detection Constants -----
+/**
+ * Shell prompt ending characters for detecting shell-only tmux sessions
+ * Extensible array to support multiple shell types (MF-002: OCP)
+ * Placed in claude-session.ts as private constant (SF-S2-002: ISP - used only by isSessionHealthy())
+ * - '$': bash/sh default prompt
+ * - '%': zsh default prompt
+ * - '#': root prompt (bash/zsh)
+ *
+ * C-S2-002: False positive risk assessment:
+ * These characters are checked only at the END of trimmed output. This limits false
+ * positives to cases where Claude CLI output ends with one of these characters
+ * (e.g., output containing "$" at end of a code block). The risk is acceptable because:
+ * (1) Claude CLI output typically ends with a prompt (❯) or thinking indicator, not shell chars
+ * (2) A false positive triggers session recreation, which is a safe recovery action
+ * (3) The check is combined with error pattern detection for multiple signals
+ */
+const SHELL_PROMPT_ENDINGS = ['$', '%', '#'];
 // ----- Timeout and Polling Constants (OCP-001) -----
 // These constants are exported to allow configuration and testing.
 // Changing these values affects Claude CLI session startup behavior.
@@ -108,19 +128,67 @@ exports.CLAUDE_PROMPT_POLL_INTERVAL = 200;
  * Cached Claude CLI path
  */
 let cachedClaudePath = null;
+/**
+ * Clear cached Claude CLI path
+ * Called when session start fails to allow path re-resolution
+ * on next attempt (e.g., after CLI update or path change)
+ * @internal Exported for testing purposes only.
+ * Follows the same pattern as version-checker.ts resetCacheForTesting().
+ * Function name clearCachedClaudePath() is retained (without ForTesting suffix)
+ * because it is also called in production code (catch block), not only in tests.
+ * (SF-S2-005: Consistent @internal usage with version-checker.ts precedent)
+ */
+function clearCachedClaudePath() {
+    cachedClaudePath = null;
+}
+/**
+ * Validate CLAUDE_PATH environment variable to prevent command injection
+ * SEC-MF-001: OWASP A03:2021 - Injection prevention
+ *
+ * @param claudePath - Value from process.env.CLAUDE_PATH
+ * @returns true if the path is safe to use
+ */
+function isValidClaudePath(claudePath) {
+    // (1) Whitelist validation: only allow alphanumeric, path separators, dots, hyphens, underscores
+    // SEC-MF-001: Rejects shell metacharacters (;, |, &, $, `, newlines, spaces in dangerous positions, etc.)
+    const SAFE_PATH_PATTERN = /^[/a-zA-Z0-9._-]+$/;
+    if (!SAFE_PATH_PATTERN.test(claudePath)) {
+        console.log(`[claude-session] CLAUDE_PATH contains invalid characters, ignoring: ${claudePath.substring(0, 50)}`);
+        return false;
+    }
+    // (2) Path traversal prevention: reject ../ sequences
+    // SEC-MF-001: Prevents path traversal attacks
+    if (claudePath.includes('..')) {
+        console.log('[claude-session] CLAUDE_PATH contains path traversal sequence, ignoring');
+        return false;
+    }
+    return true;
+}
 /**
  * Get Claude CLI path dynamically
  * Uses CLAUDE_PATH environment variable if set, otherwise finds via 'which'
+ * SEC-MF-001: Validates CLAUDE_PATH before caching
  */
 async function getClaudePath() {
     // Return cached path if available
     if (cachedClaudePath) {
         return cachedClaudePath;
     }
-    // Check environment variable first
-    if (process.env.CLAUDE_PATH) {
-        cachedClaudePath = process.env.CLAUDE_PATH;
-        return cachedClaudePath;
+    // Check environment variable first with validation (SEC-MF-001)
+    const envClaudePath = process.env.CLAUDE_PATH;
+    if (envClaudePath) {
+        if (isValidClaudePath(envClaudePath)) {
+            try {
+                await (0, promises_1.access)(envClaudePath, promises_1.constants.X_OK);
+                cachedClaudePath = envClaudePath;
+                return cachedClaudePath;
+            }
+            catch {
+                console.log(`[claude-session] CLAUDE_PATH is not executable: ${envClaudePath}`);
+                // Fall through to fallback paths
+            }
+        }
+        // If validation fails, ignore CLAUDE_PATH and proceed with fallback resolution
     }
     // Find claude via 'which' command
     try {
@@ -148,6 +216,111 @@ async function getClaudePath() {
         throw new Error('Claude CLI not found. Set CLAUDE_PATH environment variable or install Claude CLI.');
     }
 }
+// ----- Common Helper Functions (SF-001) -----
+/**
+ * Capture tmux pane output and strip ANSI escape sequences
+ * Consolidates the common capturePane + stripAnsi pattern (SF-001: DRY)
+ *
+ * @param sessionName - tmux session name
+ * @param lines - Number of lines to capture (default: 50, captures from -lines)
+ * @returns Clean pane output with ANSI codes removed
+ */
+async function getCleanPaneOutput(sessionName, lines = 50) {
+    const output = await (0, tmux_1.capturePane)(sessionName, { startLine: -lines });
+    return (0, cli_patterns_1.stripAnsi)(output);
+}
+// ----- Health Check Functions (Bug 2) -----
+/**
+ * Verify that Claude CLI is actually running inside a tmux session
+ * Detects broken sessions where tmux exists but Claude failed to start
+ *
+ * @param sessionName - tmux session name
+ * @returns true if Claude CLI is responsive (prompt detected or initializing)
+ */
+async function isSessionHealthy(sessionName) {
+    try {
+        // SF-001: Use shared helper instead of inline capturePane + stripAnsi
+        const cleanOutput = await getCleanPaneOutput(sessionName);
+        // MF-001: Check error patterns from cli-patterns.ts (SRP - pattern management centralized)
+        for (const pattern of cli_patterns_1.CLAUDE_SESSION_ERROR_PATTERNS) {
+            if (cleanOutput.includes(pattern)) {
+                return false;
+            }
+        }
+        for (const regex of cli_patterns_1.CLAUDE_SESSION_ERROR_REGEX_PATTERNS) {
+            if (regex.test(cleanOutput)) {
+                return false;
+            }
+        }
+        // MF-002: Check shell prompt endings from extensible array (OCP)
+        const trimmed = cleanOutput.trim();
+        // C-S2-001: Empty output means tmux session exists but Claude CLI has no output.
+        // This is treated as unhealthy because a properly running Claude CLI always
+        // produces output (prompt, spinner, or response). An empty pane indicates
+        // the CLI process has exited or failed to start.
+        if (trimmed === '') {
+            return false;
+        }
+        if (SHELL_PROMPT_ENDINGS.some(ending => trimmed.endsWith(ending))) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure the existing tmux session has a healthy Claude CLI process
+ * If unhealthy, kill the session so it can be recreated
+ * (SF-002: SRP - session health management separated from session creation)
+ *
+ * @param sessionName - tmux session name
+ * @returns true if session is healthy and can be reused, false if it was killed
+ */
+async function ensureHealthySession(sessionName) {
+    const healthy = await isSessionHealthy(sessionName);
+    if (!healthy) {
+        await (0, tmux_1.killSession)(sessionName);
+        return false;
+    }
+    return true;
+}
+// ----- Environment Sanitization (Bug 3) -----
+/**
+ * Remove CLAUDECODE environment variable from tmux session environment
+ * Prevents Claude Code from detecting nested session and refusing to start
+ * (SF-002: SRP - environment sanitization separated from session creation)
+ *
+ * MF-S3-002: tmux set-environment -g -u operates on the global tmux environment.
+ * Impact analysis:
+ * - CLAUDECODE is a Claude Code-specific variable, so Codex/Gemini sessions
+ *   (CLI_TOOL_IDS: ['claude', 'codex', 'gemini']) are NOT affected by its removal.
+ * - Multiple Claude sessions concurrently calling unset (-g -u) is safe because
+ *   the unset operation is idempotent (unsetting an already-unset variable is a no-op).
+ *
+ * SEC-SF-001: sessionName is validated by the caller chain:
+ * ClaudeTool.startSession() -> BaseCLITool.getSessionName() -> validateSessionName()
+ * This ensures sessionName contains only safe characters (alphanumeric + hyphen).
+ *
+ * SEC-SF-003: Migration trigger for session-scoped set-environment (without -g flag):
+ * - When sanitization of additional environment variables (e.g., CODEX_*, GEMINI_*)
+ *   is required, migrate to session-scoped operations to prevent cross-session side effects.
+ * - Current scope (CLAUDECODE only) is safe with global scope due to idempotent unset.
+ *
+ * @param sessionName - tmux session name
+ */
+async function sanitizeSessionEnvironment(sessionName) {
+    // 3-1: Remove from tmux global environment
+    // MF-S3-002: -g flag affects global tmux environment.
+    // Safe because: (1) CLAUDECODE is Claude-specific, (2) unset is idempotent.
+    await execAsync('tmux set-environment -g -u CLAUDECODE 2>/dev/null || true');
+    // 3-2: Unset inside the session shell (safety net)
+    // 100ms wait: empirically determined time for sendKeys command to reach the shell
+    // SF-S3-004: 100ms is 0.67% of CLAUDE_INIT_TIMEOUT (15000ms), acceptable overhead
+    await (0, tmux_1.sendKeys)(sessionName, 'unset CLAUDECODE', true);
+    await new Promise(resolve => setTimeout(resolve, 100));
+}
 /**
  * Get tmux session name for a worktree
  *
@@ -178,9 +351,15 @@ async function isClaudeInstalled() {
 }
 /**
  * Check if Claude session is running
+ * MF-S3-001: Includes health check to prevent reporting broken sessions as running.
+ * Without this, API routes (especially send/route.ts) would skip startSession()
+ * for broken sessions and attempt to send messages to a non-functional CLI.
+ *
+ * Performance: adds ~50ms overhead (capturePane + pattern match) per call.
+ * This is acceptable given that API route response times are typically 100-500ms.
  *
  * @param worktreeId - Worktree ID
- * @returns True if Claude session exists and is running
+ * @returns True if Claude session exists AND Claude CLI is healthy
  *
  * @example
  * ```typescript
@@ -192,13 +371,27 @@ async function isClaudeInstalled() {
  */
 async function isClaudeRunning(worktreeId) {
     const sessionName = getSessionName(worktreeId);
-    return await (0, tmux_1.hasSession)(sessionName);
+    const exists = await (0, tmux_1.hasSession)(sessionName);
+    if (!exists) {
+        return false;
+    }
+    // MF-S3-001: Verify session health to avoid reporting broken sessions as running
+    return isSessionHealthy(sessionName);
 }
 /**
  * Get Claude session state
  *
+ * C-S3-002: This function checks tmux session existence via hasSession() but
+ * does NOT perform health checks (unlike isClaudeRunning()). This is intentional:
+ * getClaudeSessionState() is a lightweight status query for UI display purposes,
+ * while isClaudeRunning() performs the more expensive health check for operational
+ * decisions (e.g., whether to recreate a session).
+ *
+ * If health-aware state is needed, callers should use isClaudeRunning() instead
+ * or call ensureHealthySession() separately.
+ *
  * @param worktreeId - Worktree ID
- * @returns Session state information
+ * @returns Session state information (existence-based, not health-based)
  */
 async function getClaudeSessionState(worktreeId) {
     const sessionName = getSessionName(worktreeId);
@@ -227,11 +420,10 @@ async function waitForPrompt(sessionName, timeout = exports.CLAUDE_PROMPT_WAIT_T
     const startTime = Date.now();
     const pollInterval = exports.CLAUDE_PROMPT_POLL_INTERVAL;
     while (Date.now() - startTime < timeout) {
-        // Use -50 lines to capture more context including status bars
-        const output = await (0, tmux_1.capturePane)(sessionName, { startLine: -50 });
+        // SF-001: Use getCleanPaneOutput helper (DRY)
+        const cleanOutput = await getCleanPaneOutput(sessionName);
         // DRY-001: Use CLAUDE_PROMPT_PATTERN from cli-patterns.ts
-        // Strip ANSI escape sequences before pattern matching (Issue #152)
-        if (cli_patterns_1.CLAUDE_PROMPT_PATTERN.test((0, cli_patterns_1.stripAnsi)(output))) {
+        if (cli_patterns_1.CLAUDE_PROMPT_PATTERN.test(cleanOutput)) {
             return; // Prompt detected
         }
         await new Promise((resolve) => setTimeout(resolve, pollInterval));
@@ -263,8 +455,15 @@ async function startClaudeSession(options) {
     // Check if session already exists
     const exists = await (0, tmux_1.hasSession)(sessionName);
     if (exists) {
-        console.log(`Claude session ${sessionName} already exists`);
-        return;
+        // SF-S2-004: Health check on existing session
+        const healthy = await ensureHealthySession(sessionName);
+        if (healthy) {
+            console.log(`Claude session ${sessionName} already exists and is healthy`);
+            return;
+        }
+        // If not healthy, ensureHealthySession() already killed the session.
+        // Fall through to the session creation logic below.
+        // (SF-S2-004: Explicit fall-through instead of hidden re-entry)
     }
     try {
         // Create tmux session with large history buffer for Claude output
@@ -273,6 +472,8 @@ async function startClaudeSession(options) {
             workingDirectory: worktreePath,
             historyLimit: 50000,
         });
+        // SF-S2-003: Sanitize environment after createSession, before launching Claude CLI
+        await sanitizeSessionEnvironment(sessionName);
         // Get Claude CLI path dynamically
         const claudePath = await getClaudePath();
         // Start Claude CLI in interactive mode using dynamically resolved path
@@ -287,13 +488,11 @@ async function startClaudeSession(options) {
         while (Date.now() - startTime < maxWaitTime) {
             await new Promise((resolve) => setTimeout(resolve, pollInterval));
             try {
-                const output = await (0, tmux_1.capturePane)(sessionName, { startLine: -50 });
+                // SF-001: Use getCleanPaneOutput helper (DRY)
+                const cleanOutput = await getCleanPaneOutput(sessionName);
                 // Claude is ready when we see the prompt (DRY-001)
                 // Use CLAUDE_PROMPT_PATTERN from cli-patterns.ts for consistency
-                // Strip ANSI escape sequences before pattern matching (Issue #152)
                 // Note: CLAUDE_SEPARATOR_PATTERN was removed from initialization check (Issue #187, P1-1)
-                // because separator early-detection caused premature returns before prompt was ready
-                const cleanOutput = (0, cli_patterns_1.stripAnsi)(output);
                 if (cli_patterns_1.CLAUDE_PROMPT_PATTERN.test(cleanOutput)) {
                     // Wait for stability after prompt detection (CONS-007, DOC-001)
                     await new Promise((resolve) => setTimeout(resolve, exports.CLAUDE_POST_PROMPT_DELAY));
@@ -306,7 +505,6 @@ async function startClaudeSession(options) {
                 if (!trustDialogHandled && cli_patterns_1.CLAUDE_TRUST_DIALOG_PATTERN.test(cleanOutput)) {
                     await (0, tmux_1.sendKeys)(sessionName, '', true);
                     trustDialogHandled = true;
-                    // TODO: Log output method unification (console.log vs createLogger) to be addressed in a separate Issue (SF-002)
                     console.log('Trust dialog detected, sending Enter to confirm');
                     // Continue polling to wait for prompt detection
                 }
@@ -322,7 +520,11 @@ async function startClaudeSession(options) {
         console.log(`Started Claude session: ${sessionName}`);
     }
     catch (error) {
-        throw new Error(`Failed to start Claude session: ${getErrorMessage(error)}`);
+        // MF-S2-002: Clear cached path on all failures (harmless for non-path failures)
+        clearCachedClaudePath();
+        // SEC-SF-002: Log detailed error server-side, throw generic message to client
+        console.log(`[claude-session] Session start failed: ${getErrorMessage(error)}`);
+        throw new Error('Failed to start Claude session');
     }
 }
 /**
@@ -345,17 +547,13 @@ async function sendMessageToClaude(worktreeId, message) {
         throw new Error(`Claude session ${sessionName} does not exist. Start the session first.`);
     }
     // Verify prompt state before sending (CONS-006, DRY-001)
-    const output = await (0, tmux_1.capturePane)(sessionName, { startLine: -50 });
-    if (!cli_patterns_1.CLAUDE_PROMPT_PATTERN.test((0, cli_patterns_1.stripAnsi)(output))) {
+    // SF-001: Use getCleanPaneOutput helper (DRY)
+    const cleanOutput = await getCleanPaneOutput(sessionName);
+    if (!cli_patterns_1.CLAUDE_PROMPT_PATTERN.test(cleanOutput)) {
         // Path B: Prompt not detected - wait for it (P1: throw on timeout)
         await waitForPrompt(sessionName, exports.CLAUDE_SEND_PROMPT_WAIT_TIMEOUT);
     }
     // P0: Stability delay after prompt detection (both Path A and Path B)
-    // Same delay as startClaudeSession() to ensure Claude CLI input handler is ready
-    // NOTE: This 500ms delay also applies to 2nd+ messages. Currently acceptable since
-    // Claude CLI response time (seconds to tens of seconds) dwarfs this overhead.
-    // If future batch-send use cases arise, this could be optimized to first-message-only,
-    // but that optimization is deferred per YAGNI principle. (ref: F-3)
     await new Promise((resolve) => setTimeout(resolve, exports.CLAUDE_POST_PROMPT_DELAY));
     // Send message using sendKeys consistently (CONS-001)
     await (0, tmux_1.sendKeys)(sessionName, message, false);
@@ -420,7 +618,7 @@ async function stopClaudeSession(worktreeId) {
         // Kill the tmux session
         const killed = await (0, tmux_1.killSession)(sessionName);
         if (killed) {
-            console.log(`✓ Stopped Claude session: ${sessionName}`);
+            console.log(`Stopped Claude session: ${sessionName}`);
         }
         return killed;
     }

package/dist/server/src/lib/cli-patterns.js

@@ -4,7 +4,7 @@
  * Shared between response-poller.ts and API routes
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GEMINI_PROMPT_PATTERN = exports.MAX_PASTED_TEXT_RETRIES = exports.PASTED_TEXT_DETECT_DELAY = exports.PASTED_TEXT_PATTERN = exports.CODEX_SEPARATOR_PATTERN = exports.CODEX_PROMPT_PATTERN = exports.CLAUDE_TRUST_DIALOG_PATTERN = exports.CLAUDE_SEPARATOR_PATTERN = exports.CLAUDE_PROMPT_PATTERN = exports.CODEX_THINKING_PATTERN = exports.CLAUDE_THINKING_PATTERN = exports.CLAUDE_SPINNER_CHARS = void 0;
+exports.CLAUDE_SESSION_ERROR_REGEX_PATTERNS = exports.CLAUDE_SESSION_ERROR_PATTERNS = exports.GEMINI_PROMPT_PATTERN = exports.MAX_PASTED_TEXT_RETRIES = exports.PASTED_TEXT_DETECT_DELAY = exports.PASTED_TEXT_PATTERN = exports.CODEX_SEPARATOR_PATTERN = exports.CODEX_PROMPT_PATTERN = exports.CLAUDE_TRUST_DIALOG_PATTERN = exports.CLAUDE_SEPARATOR_PATTERN = exports.CLAUDE_PROMPT_PATTERN = exports.CODEX_THINKING_PATTERN = exports.CLAUDE_THINKING_PATTERN = exports.CLAUDE_SPINNER_CHARS = void 0;
 exports.detectThinking = detectThinking;
 exports.getCliToolPatterns = getCliToolPatterns;
 exports.stripAnsi = stripAnsi;
@@ -237,6 +237,39 @@ function stripAnsi(str) {
  * @param cliToolId - CLI tool identifier
  * @returns DetectPromptOptions for the tool, or undefined for default behavior
  */
+/**
+ * Error patterns that indicate a Claude session failed to start properly
+ * Used by isSessionHealthy() to detect broken sessions (MF-001: SRP)
+ * Style: readonly + as const for type safety (SF-S2-001: follows response-poller.ts precedent)
+ *
+ * SEC-SF-004: Pattern maintenance process:
+ * - When Claude CLI is updated, verify that error messages still match these patterns.
+ * - Test procedure: Intentionally trigger each error condition (e.g., nested session launch)
+ *   and confirm the error message is captured by the patterns.
+ * - If Claude CLI introduces localized error messages, add locale-aware patterns or
+ *   consider switching to exit code-based detection as a more robust alternative.
+ * - Pattern additions should be accompanied by corresponding test cases in
+ *   claude-session.test.ts.
+ *
+ * C-S3-001: Codex/Gemini monitoring note:
+ * These patterns are currently Claude-specific. If Codex or Gemini exhibit similar
+ * "nested session" or startup failure behaviors, analogous error patterns should be
+ * added to their respective tool configurations (codex.ts, gemini.ts) rather than
+ * extending these arrays, to maintain SRP per CLI tool type.
+ */
+exports.CLAUDE_SESSION_ERROR_PATTERNS = [
+    'Claude Code cannot be launched inside another Claude Code session',
+];
+/**
+ * Regex patterns for Claude session errors requiring context matching
+ * Used by isSessionHealthy() for multi-condition error detection (MF-001: SRP)
+ * Style: readonly + as const for type safety (SF-S2-001: follows response-poller.ts precedent)
+ *
+ * SEC-SF-004: See CLAUDE_SESSION_ERROR_PATTERNS JSDoc for pattern maintenance process.
+ */
+exports.CLAUDE_SESSION_ERROR_REGEX_PATTERNS = [
+    /Error:.*Claude/,
+];
 function buildDetectPromptOptions(cliToolId) {
     if (cliToolId === 'claude') {
         return { requireDefaultIndicator: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Git worktree management with Claude CLI and tmux sessions",
   "repository": {
     "type": "git",