OrcaWinandOrcaWin
ed7849eb7b
* fix(worktrees): stop silently switching existing Windows setup scripts to Git Bash #6967 derived the Windows setup-runner shell from `terminalWindowsShell`. On upgrade, any Windows user whose terminal preference resolved to Git Bash had their existing `orca.yaml` setup script (and issue command) handed to bash instead of cmd.exe. Scripts authored against the cmd runner — `copy`, `xcopy`, `set VAR=value`, `if errorlevel 1`, `%VAR%`, backslash paths — broke with no migration and no warning, and the failure looked like Orca broke the project. The conflation is also wrong in the steady state: a terminal preference is per-user, so two people on the same repo got different interpreters for the same orca.yaml and no project could write a setup script that worked for all of its Windows contributors. The interpreter is now a property of the script, declared the standard way: a leading `#!` line. Native Windows keeps the historical `.cmd` runner unless the script declares a POSIX shell, so no existing script changes behavior. `resolveSetupRunnerShell` keeps its role as the feasibility gate — a bash runner still requires the terminal to resolve to Git Bash, since the launch command is typed into that shell and uses MSYS `/c/...` paths. `buildWindowsRunnerScript` now drops a leading `#!` line rather than `call`ing it, so a declared-bash script that falls back to cmd (Git Bash missing) fails on a real setup line instead of aborting on errorlevel at line one. WSL worktrees, POSIX platforms, and SSH hosts are untouched. * fix(worktrees): keep the cmd setup runner launchable from a Git Bash pane Adversarial review of this PR found that pinning the runner format per script reopened issue #6896 one layer down. - `WorktreeSetupLaunch.shell` had been redefined to mean "the format the runner file was written in". `resolveSetupRunnerCommand` consumes it as "the shell that types the launch command", so a Git Bash terminal with a batch setup script produced `cmd.exe /c "C:\...\setup-runner.cmd"` typed into a bash pane, where MSYS rewrites the `/c` switch into a drive path: cmd opens interactively and setup never runs. `shell` is the terminal's family again; the runner file's .cmd/.sh extension carries the format, and a batch runner launched from a POSIX pane reuses the existing PowerShell ProcessStartInfo launcher. - The cmd runner dropped a leading `#!` line and ran the rest as batch, so a bash script reaching cmd (PowerShell/cmd terminal, or any SSH-to-Windows host) got its interpreter-agnostic prefix executed before failing mid-way. It now prints why and exits 1 without running anything. - A `#!` line's option flags were discarded: `#!/usr/bin/env -S bash -euo pipefail` lost pipefail because the runner is launched as `bash <path>`. The generated posix runner now replays declared flags via `set` and drops the duplicate interpreter line. - Docs cover the per-user setup command in repository hook settings, which goes through the same `#!` rule, and describe what the `#!` line does and does not select. Tests: composed launch command for a POSIX pane + cmd runner (hooks, shared runner command, setup sequencing gate, observed-setup signal), the cmd runner's shebang refusal, and shebang flag replay. Each fails with the source reverted. * fix(worktrees): replay only real `set` flags and keep the gate in the pane's shell Two round-2 review findings: - `#!/bin/bash -l` replayed `set -l`, which exits 2 and aborted the runner under its own `set -e` before a single setup line ran (all platforms). Only the flags `set` documents are replayed now; a bare `-o` with no option name is dropped instead of dumping the shell-option table. - The wait-for-setup gate picked its language from the runner file, so a batch runner launched from a Git Bash pane got the PowerShell gate while the agent startup command was already POSIX-quoted — `Invoke-Expression` cannot parse `'\''`. The gate now follows the pane; the runner still launches through the ProcessStartInfo launcher, never through bash. --------- Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
4.5 KiB
Windows setup-runner shell
On native Windows, Orca writes the orca.yaml setup script (and the issue command) to a generated
runner file and types a launch command into a terminal. The runner is a .cmd batch file by
default, exactly as it has been since setup hooks shipped.
A script opts into bash by starting with a #! interpreter line:
scripts:
setup: |
#!/usr/bin/env bash
[ -f .env ] || cp .env.example .env
pnpm install
Without that line the script keeps running under cmd.exe:
scripts:
setup: |
copy .env.example .env
xcopy /E assets dist
Why the script declares it, not the terminal preference
terminalWindowsShell says which shell interactive terminals open in. It says nothing about the
language a project's setup script is written in. Deriving the runner from it had two consequences:
- Windows users with batch-syntax setup scripts silently switched to bash on upgrade, so
copy,xcopy,set VAR=value, andif errorlevel 1stopped working. - Two people on the same repo got different interpreters for the same
orca.yaml, so no project could write a setup script that worked for all of its Windows contributors.
A #! line is per-project, explicit, and identical for everyone who checks the repo out.
The same rule applies to the per-user setup command in Settings → repository hooks
(repo.hookSettings.scripts.setup): it is merged into the same script that reaches the runner, so a
POSIX one-liner stored there needs its own #! line to run under bash on Windows.
What the #! line does and does not select
The generated runner is always executed by bash (bash <runner>; Git Bash on native Windows), on
every platform. The #! line therefore does two things:
- It declares the script is written for a POSIX shell, which is what selects the bash runner.
- Its option flags are replayed with
set, so#!/usr/bin/env -S bash -euo pipefailreally does getpipefail. Without that replay the flags would be silently dropped, becausebash <runner>never parses the interpreter line. Only the flagssetitself accepts ([--abefhkmnptuvxBCHP] [-o option]) are replayed; invocation-only ones such as-lare dropped, becauseset -lexits 2 and would abort the runner before its first line.
The interpreter name itself is not honored beyond "is this a POSIX shell": #!/bin/sh and
#!/bin/zsh scripts run under bash, exactly as they already did on macOS and Linux.
Requirements for the bash runner
A #! line only takes effect when Orca can actually launch bash from the configured terminal — the
terminal shell must resolve to Git Bash (resolveWindowsGitBashShellPath). The generated runner
uses MSYS /c/... paths, which Cygwin and the WSL shim do not accept, and the launch command is
typed into whatever shell the terminal opened with.
When bash is not available (a PowerShell/cmd terminal, or an SSH-to-Windows host, which always uses
the remote's .cmd runner) the #! script is not executed under cmd. The generated .cmd
runner prints why and exits 1, because running the interpreter-agnostic prefix of a bash script
(pnpm install, git submodule update) and only failing at the first bash-only line leaves a
half-set-up worktree that looks finished.
Launching a .cmd runner from a Git Bash terminal
The runner format and the shell that types the launch command are independent: a Git Bash terminal
with a batch-syntax setup script gets a .cmd runner launched from a bash pane. cmd.exe /c "C:\..." cannot be used there — MSYS rewrites the bare /c switch into a drive path, so cmd opens
interactively and the runner never executes (issue #6896). Those launches reuse the PowerShell
ProcessStartInfo launcher (buildWindowsCmdRunnerDelayedLaunchCommand), which carries the switch
and the runner path outside the command line. WorktreeSetupLaunch.shell therefore describes the
launching pane; the runner file's .cmd/.sh extension describes the format.
The wait-for-setup gate follows the same split. The pane types the gate and already quoted the
agent startup command for itself, so a .cmd runner launched from a Git Bash pane still gets the
bash gate — PowerShell's Invoke-Expression cannot parse POSIX '\'' escaping. The gate wraps the
same ProcessStartInfo launcher, so the batch runner is never handed to bash.
WSL worktrees and non-Windows platforms are unaffected: they always use the bash runner. SSH hosts choose their runner from the remote path format, never from local Windows preferences.