fix(server): resolve Claude SDK executable path on Windows npm installs

[nsxdavid]

Addresses cause A (Windows spawn failure) in #2653.

What Changed

• Added resolveClaudeSdkExecutablePath (apps/server/src/provider/Drivers/ClaudeExecutable.ts). On Windows it resolves the configured Claude command against PATH/PATHEXT. When that lands on an npm launcher shim (.cmd/.bat/.ps1), it follows the shim to the packaged entry: bin/claude.exe, or cli.js on older @anthropic-ai/claude-code versions. Non-Windows returns the configured value unchanged.
• Wired it into both Agent SDK call sites: the capabilities probe (ClaudeProvider.ts) and session startup (ClaudeAdapter.ts).
• Unit tests covering platform passthrough, native-exe resolution, shim-following (exe and cli.js), and fallback behavior.

Why

The Claude Agent SDK spawns pathToClaudeCodeExecutable directly, with no shell and no Windows PATH/PATHEXT resolution. Both SDK call sites passed the raw configured binary path (default: bare "claude"). On Windows with an npm-installed CLI that fails two ways:

• bare "claude" fails with the SDK's "native binary not found" error (~9 ms)
• an explicit claude.cmd path fails with spawn EINVAL (Node 20.12+ refuses shell-less .cmd spawns)

Result: the provider is stuck on "Needs attention - Could not verify Claude authentication status from initialization result." despite a fully authenticated CLI, and SDK-backed sessions are broken. The version probe kept working because CLI commands go through resolveSpawnCommand, which handles .cmd via shell: true. That is why the card shows the correct version while auth verification fails.

This fixes the probe's root cause rather than adding an auth-status fallback (the approach in #3559, closed).

Validation

• Measured on Windows 11, npm-installed Claude Code 2.1.201, SDK 0.3.170: the probe previously failed in 9 ms; with resolution it returns account, subscription, and 157 slash commands in about 1.5 s. The provider card now shows "Authenticated ... Claude Max Subscription".
• vp test apps/server/src/provider/Drivers/ClaudeExecutable.test.ts passes (8 tests)
• vp run typecheck clean (15/15 packages)
• vp check 0 errors

Checklist

• This PR is small and focused (+226/-2, one concern)
• I explained what changed and why
• UI change is state-only (provider card status)

---

Note

Medium Risk
Changes how the Claude binary is chosen on Windows for SDK sessions and auth probing; incorrect resolution could break Claude provider startup, but scope is limited to Windows shim handling with fallbacks and tests.

Overview
Fixes Claude Agent SDK startup on Windows when the configured binary is a bare claude name or an npm launcher shim (.cmd/.bat/.ps1), which the SDK cannot spawn without a shell.

Adds resolveClaudeSdkExecutablePath in ClaudeExecutable.ts: on win32 it uses SpawnExecutableResolution (PATH/PATHEXT), then if the result is a shim it looks beside the shim for @anthropic-ai/claude-code entry points (bin/claude.exe first, else cli.js). Other platforms return the configured path unchanged; unknown shim layouts fall back to the original path with a warning.

Wires the resolved path into both SDK call sites: ClaudeAdapter (pathToClaudeCodeExecutable at session start) and ClaudeProvider capabilities probe (probeClaudeCapabilities), replacing raw claudeSettings.binaryPath.

Unit tests cover non-Windows passthrough, native .exe, shim following, extension normalization, cli.js fallback, and failure paths via injectable ClaudeExecutableFileCheck.

^{Reviewed by Cursor Bugbot for commit b213574. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix Claude SDK executable path resolution on Windows npm installs

• On Windows, npm installs create .cmd/.bat/.ps1 shims that the Claude Agent SDK cannot spawn directly; this fix resolves those shims to the actual binary (claude.exe or cli.js).
• resolveClaudeSdkExecutablePath in ClaudeExecutable.ts handles the resolution: on non-Windows it returns the path unchanged; on Windows it follows shims to known package entry points adjacent to node_modules.
• Both ClaudeAdapter.ts and ClaudeProvider.ts now use the resolved path when spawning the SDK and probing capabilities.
• Falls back to the original configured path with a warning log if no known entry point is found next to the shim.

^{Macroscope summarized b213574.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 76b09c32-13ee-4ee1-bf4f-765247264624

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved

Straightforward Windows-specific bug fix for resolving npm launcher shims to actual executables. The change is well-scoped with comprehensive test coverage and only affects path resolution on Windows platforms.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit d4110b3. Configure here.}