fix: resolve Claude CLI not found on Windows - PATH, prompt size, cwd (#1661)

apps/backend/core/client.py

@@ -29,6 +29,18 @@
 
 logger = logging.getLogger(__name__)
 
+# =============================================================================
+# Windows System Prompt Limits
+# =============================================================================
+# Windows CreateProcessW has a 32,768 character limit for the entire command line.
+# When CLAUDE.md is very large and passed as --system-prompt, the command can exceed
+# this limit, causing ERROR_FILE_NOT_FOUND. We cap CLAUDE.md content to stay safe.
+# 20,000 chars leaves ~12KB headroom for CLI overhead (model, tools, MCP config, etc.)
+WINDOWS_MAX_SYSTEM_PROMPT_CHARS = 20000
+WINDOWS_TRUNCATION_MESSAGE = (
+    "\n\n[... CLAUDE.md truncated due to Windows command-line length limit ...]"
+)
+
 # =============================================================================
 # Project Index Cache
 # =============================================================================
@@ -821,8 +833,31 @@ def create_client(
     if should_use_claude_md():
         claude_md_content = load_claude_md(project_dir)
         if claude_md_content:
+            # On Windows, the SDK passes system_prompt as a --system-prompt CLI argument.
+            # Windows CreateProcessW has a 32,768 character limit for the entire command line.
+            # When CLAUDE.md is very large, the command can exceed this limit, causing Windows
+            # to return ERROR_FILE_NOT_FOUND which the SDK misreports as "Claude Code not found".
+            # Cap CLAUDE.md content to keep total command line under the limit. (#1661)
+            was_truncated = False
+            if is_windows():
+                max_claude_md_chars = (
+                    WINDOWS_MAX_SYSTEM_PROMPT_CHARS
+                    - len(base_prompt)
+                    - len(WINDOWS_TRUNCATION_MESSAGE)
+                    - len("\n\n# Project Instructions (from CLAUDE.md)\n\n")
+                )
+                if len(claude_md_content) > max_claude_md_chars > 0:
+                    claude_md_content = (
+                        claude_md_content[:max_claude_md_chars]
+                        + WINDOWS_TRUNCATION_MESSAGE
+                    )
+                    print(
+                        "   - CLAUDE.md: truncated (exceeded Windows command-line limit)"
+                    )
+                    was_truncated = True
             base_prompt = f"{base_prompt}\n\n# Project Instructions (from CLAUDE.md)\n\n{claude_md_content}"
-            print("   - CLAUDE.md: included in system prompt")
+            if not was_truncated:
+                print("   - CLAUDE.md: included in system prompt")
         else:
             print("   - CLAUDE.md: not found in project root")
     else:

apps/frontend/src/__tests__/integration/subprocess-spawn.test.ts

@@ -186,7 +186,7 @@ describe('Subprocess Spawn Integration', () => {
           'Test task description'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE,  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH,  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
           env: expect.objectContaining({
             PYTHONUNBUFFERED: '1'
           })
@@ -218,7 +218,7 @@ describe('Subprocess Spawn Integration', () => {
           'spec-001'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
         })
       );
     }, 30000);  // Increase timeout for Windows CI (dynamic imports are slow)
@@ -248,7 +248,7 @@ describe('Subprocess Spawn Integration', () => {
           '--qa'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
         })
       );
     }, 30000);  // Increase timeout for Windows CI (dynamic imports are slow)

apps/frontend/src/main/agent/agent-manager.ts

@@ -329,7 +329,9 @@ export class AgentManager extends EventEmitter {
     this.registerTaskWithOperationRegistry(taskId, 'spec-creation', { projectPath, taskDescription, specDir });
 
     // Note: This is spec-creation but it chains to task-execution via run.py
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive file access
+    // issues on Windows. The script path is absolute so Python finds its modules via sys.path[0]. (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'task-execution', projectId);
   }
 
   /**
@@ -410,7 +412,10 @@ export class AgentManager extends EventEmitter {
     // Register with unified OperationRegistry for proactive swap support
     this.registerTaskWithOperationRegistry(taskId, 'task-execution', { projectPath, specId, options });
 
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive file access
+    // issues on Windows. The script path (runPath) is absolute so Python finds its modules
+    // via sys.path[0] which is set to the script's directory. (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'task-execution', projectId);
   }
 
   /**
@@ -448,7 +453,8 @@ export class AgentManager extends EventEmitter {
 
     const args = [runPath, '--spec', specId, '--project-dir', projectPath, '--qa'];
 
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'qa-process', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive issues on Windows (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'qa-process', projectId);
   }
 
   /**

apps/frontend/src/main/agent/agent-process.ts

@@ -25,7 +25,7 @@ import type { AppSettings } from '../../shared/types/settings';
 import { getOAuthModeClearVars } from './env-utils';
 import { getAugmentedEnv } from '../env-utils';
 import { getToolInfo, getClaudeCliPathForSdk } from '../cli-tool-manager';
-import { killProcessGracefully, isWindows } from '../platform';
+import { killProcessGracefully, isWindows, getPathDelimiter } from '../platform';
 import { debugLog } from '../../shared/utils/debug-logger';
 
 /**
@@ -679,15 +679,55 @@ export class AgentProcessManager {
       },
     });
 
-    // Parse Python commandto handle space-separated commands like "py -3"
+    // Merge PATH from pythonEnv with augmented PATH from env.
+    // pythonEnv may contain its own PATH (e.g., on Windows with pywin32_system32 prepended).
+    // Simply spreading pythonEnv after env would overwrite the augmented PATH (which includes
+    // npm globals, homebrew, etc.), causing "Claude code not found" on Windows (#1661).
+    // Instead, merge PATH entries: prepend pythonEnv-specific paths to the augmented PATH.
+    const mergedPythonEnv = { ...pythonEnv };
+    const pathSep = getPathDelimiter();
+
+    // Normalize env to a single uppercase 'PATH' key to avoid duplicate PATH keys on Windows.
+    // On Windows, process.env spread produces 'Path' (system) while getAugmentedEnv() writes 'PATH'.
+    // Without normalization, Object.keys().find() returns 'Path' first (insertion order), missing
+    // augmented entries, and the final spread produces both 'Path' and 'PATH' keys. (#1661)
+    const envPathKey = 'PATH' in env ? 'PATH' : (Object.keys(env).find(k => k.toUpperCase() === 'PATH') || 'PATH');
+    if (envPathKey !== 'PATH' && envPathKey in env) {
+      env['PATH'] = env[envPathKey] as string;
+      delete env[envPathKey];
+    }
+
+    // Also normalize pythonEnv PATH key to uppercase
+    const pythonPathKey = Object.keys(mergedPythonEnv).find(k => k.toUpperCase() === 'PATH');
+    if (pythonPathKey && pythonPathKey !== 'PATH') {
+      mergedPythonEnv['PATH'] = mergedPythonEnv[pythonPathKey] as string;
+      delete mergedPythonEnv[pythonPathKey];
+    }
+
+    if (mergedPythonEnv['PATH'] && env['PATH']) {
+      const augmentedPathEntries = new Set(
+        (env['PATH'] as string).split(pathSep).filter(Boolean)
+      );
+      // Extract only new entries from pythonEnv.PATH that aren't already in the augmented PATH
+      const pythonPathEntries = (mergedPythonEnv['PATH'] as string)
+        .split(pathSep)
+        .filter(entry => entry && !augmentedPathEntries.has(entry));
+
+      // Prepend python-specific paths (e.g., pywin32_system32) to the augmented PATH
+      mergedPythonEnv['PATH'] = pythonPathEntries.length > 0
+        ? [...pythonPathEntries, env['PATH'] as string].join(pathSep)
+        : env['PATH'] as string;
+    }
+
+    // Parse Python command to handle space-separated commands like "py -3"
     const [pythonCommand, pythonBaseArgs] = parsePythonCommand(this.getPythonPath());
     let childProcess;
     try {
       childProcess = spawn(pythonCommand, [...pythonBaseArgs, ...args], {
         cwd,
         env: {
           ...env, // Already includes process.env, extraEnv, profileEnv, PYTHONUNBUFFERED, PYTHONUTF8
-          ...pythonEnv, // Include Python environment (PYTHONPATH for bundled packages)
+          ...mergedPythonEnv, // Python env with merged PATH (preserves augmented PATH entries)
           ...oauthModeClearVars, // Clear stale ANTHROPIC_* vars when in OAuth mode
           ...apiProfileEnv // Include active API profile config (highest priority for ANTHROPIC_* vars)
         }