fix(worktrees): respect Windows shell for setup runners

[rodboev]

Summary

• Makes Windows worktree setup runners follow the configured Orca terminal shell instead of forcing cmd.exe semantics for every native Windows worktree.
• Preserves that shell selection through deferred setup launch paths, including wait-for-setup sequencing and automation background setup tabs or splits.
• Keeps existing cmd.exe batch fail-fast behavior for cmd users, while allowing Git Bash, WSL, or PowerShell setup scripts to run with matching runner content and launch commands.

Closes #6896.

Testing

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build
• Added or updated high-quality tests that would catch regressions, or explained why tests were not needed

Focused validation run in this session:

• rtk pnpm.CMD exec vitest run --config config/vitest.config.ts src/main/hooks.test.ts src/shared/setup-runner-command.test.ts src/shared/setup-agent-sequencing.test.ts src/main/ipc/worktrees.test.ts src/main/ipc/worktrees-windows.test.ts src/main/runtime/orca-runtime.test.ts src/renderer/src/lib/worktree-activation.test.ts src/renderer/src/lib/launch-worktree-background-terminals.test.ts - passed (815 tests, 4 skipped).
• rtk pnpm.CMD run typecheck:node - passed.
• rtk pnpm.CMD run typecheck:web - passed.
• rtk pnpm.CMD exec oxlint src/main/hooks.test.ts src/main/hooks.ts src/main/ipc/worktree-remote.ts src/main/ipc/worktrees-windows.test.ts src/main/ipc/worktrees.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/orca-runtime.ts src/renderer/src/lib/launch-worktree-background-terminals.test.ts src/renderer/src/lib/launch-worktree-background-terminals.ts src/renderer/src/lib/setup-runner.ts src/renderer/src/lib/worktree-activation.test.ts src/renderer/src/lib/worktree-activation.ts src/shared/setup-agent-sequencing.test.ts src/shared/setup-agent-sequencing.ts src/shared/setup-runner-command.test.ts src/shared/setup-runner-command.ts src/shared/types.ts - passed.
• rtk pnpm.CMD exec oxfmt --check src/main/hooks.test.ts src/main/hooks.ts src/main/ipc/worktree-remote.ts src/main/ipc/worktrees-windows.test.ts src/main/ipc/worktrees.test.ts src/main/runtime/orca-runtime.test.ts src/main/runtime/orca-runtime.ts src/renderer/src/lib/launch-worktree-background-terminals.test.ts src/renderer/src/lib/launch-worktree-background-terminals.ts src/renderer/src/lib/setup-runner.ts src/renderer/src/lib/worktree-activation.test.ts src/renderer/src/lib/worktree-activation.ts src/shared/setup-agent-sequencing.test.ts src/shared/setup-agent-sequencing.ts src/shared/setup-runner-command.test.ts src/shared/setup-runner-command.ts src/shared/types.ts - passed.
• rtk git diff --check - passed.

AI Review Report

Reviewed the final diff for Windows cmd, PowerShell, Git Bash, and WSL setup behavior across local worktree creation, SSH worktree setup, wait-for-setup sequencing, runtime-spawned and renderer-spawned setup terminals, path quoting, and automation background setup launches. The change is scoped to setup runner generation plus setup runner launch command routing.

Security Audit

Setup still runs only through the existing user-approved setup flow. The change adds explicit shell metadata, selects .cmd, .ps1, or .sh runner content from that metadata, and reuses the existing setup terminal launch path. No new background execution path is added.

Notes

Scope is limited to worktree setup runner generation and launch semantics on Windows. Ordinary terminal spawning, archive hooks, notification behavior, and unrelated git provider behavior are unchanged.

---

[stage-review]

Ready to review this PR? Stage has broken it down into 6 individual chapters for you:

	Title
1	Define shell metadata types and command resolution
2	Implement shell-aware setup runner generation
3	Update setup-agent sequencing for custom shells
4	Wire shell selection through IPC handlers
5	Integrate shell selection into Orca runtime
6	Update renderer to respect setup shell metadata

_{Chapters generated by Stage for commit 5b717f1 on Jul 1, 2026 1:07am UTC.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: be2bf6c2-eebe-480a-8fb6-f972c62b6a09

📥 Commits

Reviewing files that changed from the base of the PR and between aa8723d and 5b717f1.

📒 Files selected for processing (5)

• src/main/hooks.test.ts
• src/main/hooks.ts
• src/renderer/src/lib/launch-worktree-background-terminals.ts
• src/renderer/src/lib/worktree-activation.test.ts
• src/shared/setup-runner-command.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• src/renderer/src/lib/launch-worktree-background-terminals.ts
• src/renderer/src/lib/worktree-activation.test.ts
• src/main/hooks.test.ts
• src/main/hooks.ts
• src/shared/setup-runner-command.ts

---

📝 Walkthrough

Walkthrough

This PR adds a SetupRunnerShell abstraction for posix, cmd, and powershell setup-runner execution. Main-process hooks now generate PowerShell scripts, resolve a shell from terminal settings, and include shell metadata in setup-launch results. IPC, runtime, and renderer paths pass that shell metadata through setup script generation and startup sequencing. Tests were expanded for Windows path handling, WSL, PowerShell, cmd, and shell-resolution behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: honoring the configured Windows shell for setup runners.
Description check	✅ Passed	The description covers summary, testing, AI review, security audit, and notes, matching the repository template closely.
Linked Issues check	✅ Passed	The changes address #6896 by threading shell choice into setup runner generation and launch paths, including Git Bash, WSL, and PowerShell.
Out of Scope Changes check	✅ Passed	The diff stays focused on Windows setup-runner shell handling and related tests, with no clear unrelated changes.

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

src/shared/setup-runner-command.ts (1)

59-83: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a short “why” comment for the Windows shell/path translation logic.

This branching is doing non-obvious behavior (/c/... vs /mnt/c/..., PowerShell vs cmd fallback), so a brief rationale here would make future edits much safer.

As per coding guidelines, **/*.{ts,tsx,js,jsx}: "When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does."

Also applies to: 121-144

Source: Coding guidelines

src/renderer/src/lib/launch-worktree-background-terminals.ts (1)

121-126: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document why background setup launches must reuse setup.shell.

The extra argument is easy to remove in a later cleanup unless this helper states that deferred/background setup tabs must preserve the shell chosen when the runner was generated.

As per coding guidelines, **/*.{ts,tsx,js,jsx}: "When writing or modifying code driven by a design doc or non-obvious constraint, add a comment explaining why the code behaves the way it does."

Source: Coding guidelines

src/renderer/src/lib/worktree-activation.test.ts (1)

75-121: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add one shell-aware issueCommand case.

These additions cover setup launches well, but Line 723 in src/renderer/src/lib/worktree-activation.ts now forwards issueCommand.shell through buildSetupRunnerCommand(), and the suite still only exercises the shell-less issue-command path. A single PowerShell or WSL issue-command assertion would keep that new branch from regressing unnoticed.

Also applies to: 419-441, 596-624

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: fc5113fa-9220-4c39-9fa8-b692d0d63a89

📥 Commits

Reviewing files that changed from the base of the PR and between 764e2fe and aa8723d.

📒 Files selected for processing (17)

• src/main/hooks.test.ts
• src/main/hooks.ts
• src/main/ipc/worktree-remote.ts
• src/main/ipc/worktrees-windows.test.ts
• src/main/ipc/worktrees.test.ts
• src/main/runtime/orca-runtime.test.ts
• src/main/runtime/orca-runtime.ts
• src/renderer/src/lib/launch-worktree-background-terminals.test.ts
• src/renderer/src/lib/launch-worktree-background-terminals.ts
• src/renderer/src/lib/setup-runner.ts
• src/renderer/src/lib/worktree-activation.test.ts
• src/renderer/src/lib/worktree-activation.ts
• src/shared/setup-agent-sequencing.test.ts
• src/shared/setup-agent-sequencing.ts
• src/shared/setup-runner-command.test.ts
• src/shared/setup-runner-command.ts
• src/shared/types.ts

[rodboev]

Addressed the CodeRabbit pass in 5b717f120: deferred setup now preserves an explicit Git Bash bash.exe path, the renderer suite now covers the shell-aware issue-command path, and I added short why-comments around the Windows POSIX path translations and deferred background setup shell handoff.