fix(win): agents/ batch arg escape (.cmd → cmd /C wrapping, v0.1.8-beta-5 hotfix)

[hang-in]

Summary

외부 Windows 사용자 보고 (메신저, 2026-05-20):

[gemini error] Failed to spawn gemini (C:\Users\bery5\AppData\Roaming\npm\gemini.cmd):
batch file arguments are invalid

Rust 1.77+ 의 std::process::Command 가 .cmd/.bat 파일을 직접 spawn 시 batch arg escape 강화 (CVE-2024-24576) 로 raw 특수문자 포함 인자를 InvalidInput reject. npm 글로벌 CLI (gemini / codex / claude / opencode) 가 Windows 에서 %APPDATA%\npm\<name>.cmd wrapper 형태라 회귀 발생.

PR #278 이 onboarding 영역 (commands/project_onboarding.rs) 에 도입한 .cmd → cmd /C wrapping 패턴이 agents/ 영역에 누락 되어 일반 send 경로에서 회귀. 본 PR 은 agents::win_spawn::wrap_windows_script SSOT 로 추출 후 5 spawn site 에 적용.

Changes (T1~T6)

• T1 + T6 (feat(agents): wrap_windows_script helper): 신규 agents/win_spawn.rs — cfg(target_os = "windows") 분기 + .cmd/.bat case-insensitive (.BAT 도 cover) + 4 unit test (no-extension / .exe / .cmd / .BAT)
• T2 (fix(gemini)): agents/gemini.rs run() + stream_run() 2 spawn site 적용
• T3 (fix(codex)): agents/codex.rs run() + stream_run() 2 spawn site 적용
• T4 (fix(opencode)): agents/opencode.rs 의 helper 함수를 wrap_windows_script SSOT 로 통일 + 사용 안 되는 resolve::build_command 제거 (helper 통합)
• T5 (chore(claude)): agents/claude.rs:370, :647 bare name "claude" 를 helper 통과 형태로 통일. 현재는 .cmd/.bat 분기 도달 X (동작 변경 0), 후속 PR 에서 resolve_claude_binary() full path 로 전환 시 자동 cmd /C 분기 활성. 회귀 가드 grep 단일화 효과.

Verification

cd src-tauri && cargo check                  → clean
cd src-tauri && cargo test --lib             → 656 passed (baseline 652 + T6 +4)
npx tsc --noEmit                             → 0 errors (frontend 변경 0)
npx vitest run                               → 478 passed (baseline 동일)

회귀 가드 grep:

• git diff main...HEAD -- src/ → 0 lines (frontend 변경 0)
• git diff main...HEAD -- src-tauri/src/commands/project_onboarding.rs → 0 lines (PR fix(win): agent CLI 동작 정상화 — PATHEXT / no_console / cwd / args #278 영역 보존)
• git diff main...HEAD -- src-tauri/src/commands/pty/session.rs → 0 lines (별 path 보존)
• rg "Command::new\(.*\.cmd" src-tauri/src/agents/ → 0 hits (모두 helper 통과)

Test plan

• cargo test --lib baseline 652 → 656 (T6 helper unit test 4건 추가)
• cargo check warning 0
• tsc --noEmit clean
• vitest run 478 PASS
• Windows 환경 e2e: v0.1.8-beta-5 publish 후 외부 사용자 (bery5) 가 gemini.cmd 호출 정상 — 메신저 회신 확인 (사용자 영역)
• 같은 환경에서 codex.cmd / claude.cmd 도 정상

CI 정책

cross-platform 회귀 영역이라 admin merge 회피 — Windows runner SUCCESS 확인 후 squash merge.

다음 step (본 PR scope 외)

• T5 의 진짜 fix (claude.rs Command::new("claude") bare name → resolve+wrap 패턴): 별 PR claudeWindowsResolvePlan scope. 본 PR 은 helper 통과 형태로 통일만 (동작 변경 0).

Refs:

• Plan: docs/plans/windowsAgentCmdSpawnFixPlan_2026-05-20.md
• 핸드오프: docs/prompts/windowsAgentCmdSpawnFixDeveloperHandoff_2026-05-20.md
• PR fix(win): agent CLI 동작 정상화 — PATHEXT / no_console / cwd / args #278 패턴 참고: src-tauri/src/commands/project_onboarding.rs:587~613

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request extracts the Windows .cmd/.bat script spawning logic into a single helper function, wrap_windows_script, in a new module win_spawn.rs. It updates various agent modules (claude, codex, gemini, and opencode) to use this helper, and removes the deprecated build_command from resolve.rs. The review feedback highlights a critical potential bug regarding cmd.exe quote-stripping when paths or arguments contain spaces, and suggests refactoring the helper to accept AsRef<Path> to avoid unnecessary string allocations.

[gemini-code-assist]

⚠️ Potential Bug: cmd.exe Quote-Stripping with Spaces in Paths and Arguments

There is a well-known and extremely subtle behavior in cmd.exe regarding how it parses quotes after /C.

According to cmd.exe's internal rules, if /C is used, it will strip the first and last quote of the command line if any of the following conditions are met:

1. There are more than two quote characters on the entire command line.
2. There are special characters like &<>()@^| inside the quotes.

How this causes failures:

If a user has a space in their Windows username (e.g., C:\Users\John Doe\AppData\Roaming\npm\gemini.cmd), Rust will automatically quote the executable path:
"C:\Users\John Doe\AppData\Roaming\npm\gemini.cmd"

If all other arguments have no spaces (and thus no quotes), there are exactly two quotes on the command line, and cmd.exe preserves them. It runs successfully.

However, if any argument also contains spaces or special characters (e.g., a prompt or a path like -p "hello world"), Rust will quote that argument as well. Now, the command line has four quotes:
cmd /C "C:\Users\John Doe\AppData\Roaming\npm\gemini.cmd" -p "hello world"

Because there are more than two quotes, cmd.exe will strip the first quote (before C:\) and the last quote (after world). The resulting command line executed by cmd.exe becomes:
C:\Users\John Doe\AppData\Roaming\npm\gemini.cmd" -p "hello world

This will fail with:
'C:\Users\John' is not recognized as an internal or external command...

Recommendations:

1. Short-term / Mitigation: Consider warning the team or documenting this limitation.
2. Long-term / Robust Fix: To completely bypass cmd.exe's quote-stripping behavior, we can wrap the entire command string in an extra set of outer quotes and pass it via std::os::windows::process::CommandExt::raw_arg. However, this requires wrap_windows_script to accept all arguments at once so it can build the entire command line, rather than allowing callers to chain .arg() afterwards.

[gemini-code-assist]

Using string manipulation (to_ascii_lowercase and ends_with) on the entire path string is less idiomatic in Rust and can be inefficient because it allocates a new String for the entire path.

We can refactor wrap_windows_script to be generic over AsRef<std::path::Path>. This allows us to use Path::extension to cleanly extract and check the file extension, avoiding unnecessary allocations and making the function more robust and idiomatic.

pub fn wrap_windows_script<P: AsRef<std::path::Path>>(cmd_path: P, args: &[&str]) -> Command {
    #[cfg(target_os = "windows")]
    {
        let path = cmd_path.as_ref();
        if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
            let lower = ext.to_ascii_lowercase();
            if lower == "cmd" || lower == "bat" {
                let mut c = Command::new("cmd");
                c.arg("/C").arg(path);
                for a in args {
                    c.arg(a);
                }
                return c;
            }
        }
    }
    let mut c = Command::new(cmd_path.as_ref());
    for a in args {
        c.arg(a);
    }
    c
}

[gemini-code-assist]

If wrap_windows_script is refactored to accept AsRef<std::path::Path>, we can simplify build_command to take &std::path::Path and pass it directly, avoiding the to_string_lossy allocation entirely.

fn build_command(bin: &std::path::Path) -> Command {
    let mut c = wrap_windows_script(bin, &[]);
    c.no_console();
    c
}