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 verification; incorrect resolution could still break provider status or sessions, but scope is limited to Windows and both call sites share one helper with tests.

Overview
Fixes Windows npm installs where the Claude Agent SDK could not spawn the configured claude command (bare name or .cmd/.bat/.ps1 shims) because the SDK spawns without a shell or PATH/PATHEXT resolution.

Introduces resolveClaudeSdkExecutablePath, which on Windows resolves the binary via SpawnExecutableResolution, then follows npm launcher shims to bin/claude.exe or cli.js when present. Non-Windows platforms return the configured path unchanged.

Wires the resolved path into both Agent SDK entry points: the capabilities/auth probe in ClaudeProvider and pathToClaudeCodeExecutable at session startup in ClaudeAdapter. Adds unit tests for platform passthrough, native exe, shim following, and fallbacks.

^{Reviewed by Cursor Bugbot for commit ef7f1d2. 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 ef7f1d2.}

[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: e0e71f33-6bb2-4c17-b534-f3f839b29081

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.}