fix(windows): route every gh and release command through the shared launcher

The previous attempt fixed runQuiet and left the rest on Bun.$, which looked
equivalent and is not. The built-in shell resolves PATH itself: the release
tests put shims on PATH as an extension-less launcher, a .js, and a .cmd, and
Windows can execute none of the first, does not retry as .cmd, and so reached
the real git. The branch guard then saw dev instead of the faked main and
aborted before logging a single call -- four release-helper tests failing on
windows-latest only, with an empty call log, while macOS stayed green.

The same defect was costing two sidebar tests five seconds each. A bare gh
spawn against a .cmd shim does not fail fast; it hangs until the timeout. That
is the star-state poll and the startup star prompt, so both move over too.

Three source-assertion tests pinned the old spellings. Their invariants are
about which resolver runs and which arguments are passed, not about a command
being a shell string, so they now assert the argv form and the launcher.
Rewriting the assertion rather than the code would have re-broken Windows.

A source assertion is the honest check here: no host-platform run can observe
which resolver executed, which is exactly how the suite stayed green on macOS
through three red CI rounds.

Author: lidge-jun

scripts/release.ts

@@ -16,7 +16,6 @@
  *
  * Requires: gh CLI (authed). Publishing is tokenless via Trusted Publishing (OIDC) — no NPM_TOKEN.
  */
-import { $ } from "bun";
 import { commandInvocation } from "../src/lib/win-exec";
 
 const args = process.argv.slice(2);
@@ -64,6 +63,44 @@ async function runQuiet(command: string[]): Promise<CommandResult> {
   return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
 }
 
+/**
+ * Capture stdout from a command, failing loudly on a non-zero exit.
+ *
+ * Everything in this script goes through `commandInvocation` rather than
+ * `Bun.$`. The shell form looked equivalent but is not on Windows: a test that
+ * puts shims on PATH writes an extension-less launcher (shebang), a `.js`, and a
+ * `.cmd`. Unix honours the shebang launcher; Windows cannot execute it and the
+ * built-in shell does not retry as `.cmd`, so `$` walked past the shim straight
+ * to the real `git` — the branch guard then saw `dev` instead of the faked
+ * `main` and aborted before a single command was logged. That is what made four
+ * release-helper tests fail on windows-latest only, with an empty call log.
+ */
+async function capture(command: string[]): Promise<string> {
+  const result = await runQuiet(command);
+  if (result.exitCode !== 0) {
+    console.error(`✗ ${command.join(" ")} failed (exit ${result.exitCode})`);
+    if (result.stderr) console.error(result.stderr);
+    process.exit(1);
+  }
+  return result.stdout;
+}
+
+/** Run a command with its output attached to this terminal; abort on failure. */
+async function runLoud(command: string[]): Promise<void> {
+  const [bin, ...rest] = command;
+  const invocation = commandInvocation(bin ?? "", rest);
+  const proc = Bun.spawn([invocation.file, ...invocation.args], {
+    stdout: "inherit",
+    stderr: "inherit",
+    ...(invocation.options.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    console.error(`✗ ${command.join(" ")} failed (exit ${exitCode})`);
+    process.exit(1);
+  }
+}
+
 async function readPackageName(): Promise<string> {
   try {
     const pkg = JSON.parse(await Bun.file("package.json").text()) as { name?: unknown };
@@ -139,21 +176,21 @@ async function assertUnusedReleaseVersion(packageName: string, version: string):
 }
 
 async function watchLatest(): Promise<void> {
-  const id = (await $`gh run list --workflow release.yml --limit 1 --json databaseId -q '.[0].databaseId'`.text()).trim();
+  const id = await capture(["gh", "run", "list", "--workflow", "release.yml", "--limit", "1", "--json", "databaseId", "-q", ".[0].databaseId"]);
   if (!id) { console.error("No Release runs found yet."); process.exit(1); }
   await watchRun(id);
 }
 
 async function watchRun(id: string | number): Promise<void> {
   console.log(`→ watching Release run ${id}`);
-  await $`gh run watch ${String(id)} --exit-status --interval 10`;
+  await runLoud(["gh", "run", "watch", String(id), "--exit-status", "--interval", "10"]);
 }
 
 async function waitForReleaseWorkflowRun(sha: string, branch: string, createdAfterIso: string): Promise<GhRun> {
   const deadline = Date.now() + 2 * 60 * 1000;
   let attempt = 1;
   while (Date.now() < deadline) {
-    const raw = await $`gh run list --workflow release.yml --branch ${branch} --commit ${sha} --limit 20 --json createdAt,databaseId,headSha,status,url`.text();
+    const raw = await capture(["gh", "run", "list", "--workflow", "release.yml", "--branch", branch, "--commit", sha, "--limit", "20", "--json", "createdAt,databaseId,headSha,status,url"]);
     const runs = (JSON.parse(raw) as GhRun[])
       .filter(run => run.headSha === sha)
       .filter(run => !run.createdAt || run.createdAt >= createdAfterIso)
@@ -172,7 +209,7 @@ async function waitForReleaseWorkflowRun(sha: string, branch: string, createdAft
 }
 
 async function listCiRuns(sha: string, workflow: string = CI_WORKFLOW): Promise<GhRun[]> {
-  const raw = await $`gh run list --workflow ${workflow} --commit ${sha} --limit 20 --json conclusion,databaseId,headSha,status,url`.text();
+  const raw = await capture(["gh", "run", "list", "--workflow", workflow, "--commit", sha, "--limit", "20", "--json", "conclusion,databaseId,headSha,status,url"]);
   const runs = JSON.parse(raw) as GhRun[];
   return runs.filter(run => run.headSha === sha);
 }
@@ -207,7 +244,7 @@ async function waitForSuccessfulCi(sha: string, workflow: string = CI_WORKFLOW,
 }
 
 async function _remoteMainSha(): Promise<string> {
-  const out = (await $`git ls-remote origin refs/heads/main`.text()).trim();
+  const out = await capture(["git", "ls-remote", "origin", "refs/heads/main"]);
   const [sha] = out.split(/\s+/);
   if (!sha) {
     console.error("✗ could not resolve origin/main");
@@ -218,7 +255,7 @@ async function _remoteMainSha(): Promise<string> {
 
 /** Live (network) head of a remote branch — never the local remote-tracking ref. */
 async function remoteBranchHead(branch: string): Promise<string> {
-  const out = (await $`git ls-remote origin refs/heads/${branch}`.text()).trim();
+  const out = await capture(["git", "ls-remote", "origin", `refs/heads/${branch}`]);
   const [sha] = out.split(/\s+/);
   if (!sha) {
     console.error(`✗ could not resolve origin/${branch}`);
@@ -240,7 +277,7 @@ if (!version || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version)) {
 const dryRun = !args.includes("--publish");
 
 // 1. Preflight — must be on main or preview, and local verification must pass.
-const branch = (await $`git rev-parse --abbrev-ref HEAD`.text()).trim();
+const branch = await capture(["git", "rev-parse", "--abbrev-ref", "HEAD"]);
 const allowedBranches = ["main", "preview"];
 const expectedTag = branch === "preview" ? "preview" : "latest";
 const tag = args.includes("--tag") ? (args[args.indexOf("--tag") + 1] ?? expectedTag) : expectedTag;
@@ -257,27 +294,27 @@ if (branch === "main" && version.includes("-")) {
   process.exit(1);
 }
 if (!allowedBranches.includes(branch)) { console.error(`✗ must be on ${allowedBranches.join(" or ")} (currently ${branch}).`); process.exit(1); }
-if ((await $`git status --porcelain`.text()).trim()) { console.error("✗ working tree not clean — commit or stash first."); process.exit(1); }
+if ((await capture(["git", "status", "--porcelain"])).trim()) { console.error("✗ working tree not clean — commit or stash first."); process.exit(1); }
 const packageName = await readPackageName();
 console.log(`→ release metadata preflight (${packageName}@${version})`);
 await assertUnusedReleaseVersion(packageName, version);
 console.log("→ typecheck");
-await $`bun x tsc --noEmit`;
+await runLoud(["bun", "x", "tsc", "--noEmit"]);
 console.log("→ test suite");
-await $`bun test --isolate tests`;
+await runLoud(["bun", "test", "--isolate", "tests"]);
 console.log("→ privacy scan");
-await $`bun run privacy:scan`;
+await runLoud(["bun", "run", "privacy:scan"]);
 
 // 2. Bump package.json only; the workflow creates the version tag after npm publish.
 console.log(`→ bump package.json → ${version}`);
-await $`npm version ${version} --no-git-tag-version`;
+await runLoud(["npm", "version", version, "--no-git-tag-version"]);
 
 // 3. Commit + push the version bump.
-await $`git add package.json`;
-await $`git commit -m ${`release: v${version}`}`;
-const releaseSha = (await $`git rev-parse HEAD`.text()).trim();
+await runLoud(["git", "add", "package.json"]);
+await runLoud(["git", "commit", "-m", `release: v${version}`]);
+const releaseSha = await capture(["git", "rev-parse", "HEAD"]);
 console.log(`→ push origin ${branch}`);
-await $`git push origin ${branch}`;
+await runLoud(["git", "push", "origin", branch]);
 
 // 4. Wait for the pushed release commit to pass CI, then dispatch the Release workflow.
 console.log(`→ wait for Cross-platform CI (${releaseSha})`);
@@ -301,7 +338,7 @@ if (liveOriginSha !== releaseSha) {
 
 console.log(`→ dispatch Release (tag=${tag}, dry-run=${dryRun})`);
 const dispatchStartedAt = new Date(Date.now() - 5_000).toISOString();
-await $`gh workflow run release.yml --ref ${branch} -f version=${version} -f tag=${tag} -f expected-sha=${releaseSha} -f dry-run=${String(dryRun)}`;
+await runLoud(["gh", "workflow", "run", "release.yml", "--ref", branch, "-f", `version=${version}`, "-f", `tag=${tag}`, "-f", `expected-sha=${releaseSha}`, "-f", `dry-run=${String(dryRun)}`]);
 
 // 5. Watch it.
 const releaseRun = await waitForReleaseWorkflowRun(releaseSha, branch, dispatchStartedAt);

src/cli/star-prompt.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { getConfigDir } from "../config";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { commandInvocation } from "../lib/win-exec";
 import { isAgentDriven } from "./agent-driven";
 import { interactiveConfirm } from "./interactive-confirm";
 
@@ -29,16 +30,37 @@ export function hasStarPromptRun(): boolean {
  * that case the prompt stays silent instead of asking for something it would
  * then fail to do.
  */
+/**
+ * On Windows `gh` is a `.cmd` shim; a shell-less spawn of the bare name skips
+ * PATHEXT and refuses `.cmd` targets, so it stalls until the timeout instead of
+ * failing fast. Route every call through the launcher the rest of the CLI uses.
+ */
+/** Resolve `gh` once; callers keep their own spawnSync overload. */
+function ghInvocation(args: string[]) {
+  const invocation = commandInvocation("gh", args);
+  return {
+    file: invocation.file,
+    args: invocation.args,
+    verbatim: invocation.options.windowsVerbatimArguments === true,
+  };
+}
+
 function ghAvailable(): boolean {
-  const version = spawnSync("gh", ["--version"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+  const v = ghInvocation(["--version"]);
+  const version = spawnSync(v.file, v.args,
+    { stdio: "ignore", timeout: 3000, windowsHide: true, windowsVerbatimArguments: v.verbatim });
   if (version.error || version.status !== 0) return false;
-  const auth = spawnSync("gh", ["auth", "status"], { stdio: "ignore", timeout: 5000, windowsHide: true });
+  const a = ghInvocation(["auth", "status"]);
+  const auth = spawnSync(a.file, a.args,
+    { stdio: "ignore", timeout: 5000, windowsHide: true, windowsVerbatimArguments: a.verbatim });
   return !auth.error && auth.status === 0;
 }
 
 function starRepo(): { ok: boolean; error?: string } {
-  const r = spawnSync("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`],
-    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true });
+  const star = ghInvocation(["api", "-X", "PUT", `/user/starred/${REPO}`]);
+  const r = spawnSync(star.file, star.args,
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true,
+      windowsVerbatimArguments: star.verbatim });
   if (r.error) return { ok: false, error: r.error.message };
   if (r.status !== 0) return { ok: false, error: (r.stderr || r.stdout || "").trim() || `gh exited ${r.status}` };
   return { ok: true };

src/github/star-state.ts

@@ -13,6 +13,8 @@
  * invalidates the cache immediately, which is why the click path never has to
  * wait for the TTL to see its own result.
  */
+import { commandInvocation } from "../lib/win-exec";
+
 export const STAR_REPO = "lidge-jun/opencodex";
 export const STAR_REPO_URL = `https://github.com/${STAR_REPO}`;
 /**
@@ -52,11 +54,18 @@ export interface StarDeps {
  */
 async function spawnGh(args: string[], timeoutMs: number): Promise<{ status: number | null } | null> {
   try {
-    const proc = Bun.spawn(["gh", ...args], {
+    // On Windows `gh` is a `.cmd` shim, and a shell-less spawn of the bare name
+    // neither consults PATHEXT nor accepts a `.cmd` target. It does not fail
+    // fast either — it hangs until the timeout below fires, which is how these
+    // sidebar tests turned into 5s timeouts on windows-latest while passing
+    // everywhere else. `commandInvocation` is the resolver the CLI already uses.
+    const invocation = commandInvocation("gh", args);
+    const proc = Bun.spawn([invocation.file, ...invocation.args], {
       stdin: "ignore",
       stdout: "ignore",
       stderr: "ignore",
       windowsHide: true,
+      ...(invocation.options.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
     });
     const timer = setTimeout(() => { try { proc.kill(); } catch { /* already gone */ } }, timeoutMs);
     try {

tests/install-scripts.test.ts

@@ -106,8 +106,12 @@ describe("install scripts", () => {
     const script = await readText("scripts/release.ts");
 
     expect(script).toContain("waitForReleaseWorkflowRun");
-    expect(script).toContain("gh run list --workflow release.yml --branch");
-    expect(script).toContain("--commit");
+    // The invariant is that the dispatched run is located by workflow, branch
+    // and commit — not that the call is a shell string. Every external command
+    // now goes through the shared launcher as an argv array, because Bun.$
+    // resolved PATH itself and walked past the Windows `.cmd` test shims.
+    expect(script).toContain('"gh", "run", "list", "--workflow", "release.yml", "--branch"');
+    expect(script).toContain('"--commit"');
     expect(script).toContain("createdAt,databaseId,headSha,status,url");
     expect(script).toContain("await watchRun(releaseRun.databaseId)");
   });

tests/release-helper.test.ts

@@ -321,4 +321,31 @@ describe("release helper", () => {
     expect(git.file.toLowerCase()).toBe("c:\\shims\\git.exe");
     expect(git.options.windowsVerbatimArguments).toBeUndefined();
   });
+
+  /**
+   * The test above proves the LAUNCHER is correct; this one proves the release
+   * script actually uses it. That distinction is not academic: `runQuiet` was
+   * already routed through `commandInvocation` while every `git`/`bun`/`npm`
+   * call still went through `Bun.$`, and the suite stayed green on macOS while
+   * windows-latest failed. The built-in shell resolved PATH itself, walked past
+   * the extension-less shim it could not execute, and reached the real `git` —
+   * so the branch guard saw `dev` rather than the faked `main` and aborted
+   * before logging a single call.
+   *
+   * A source assertion is the honest check here: the failure is "which resolver
+   * ran", and no host-platform execution can observe that.
+   */
+  test("every external command goes through the shared launcher, not the built-in shell", () => {
+    const source = readFileSync(releaseScriptPath, "utf8");
+    const withoutComments = source
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/^\s*\/\/.*$/gm, "");
+
+    // Bun.$ resolves PATH with its own shell; that is exactly the bypass.
+    expect(withoutComments).not.toMatch(/\$`/);
+    expect(withoutComments).not.toMatch(/from\s+"bun"/);
+
+    // And the launcher must still be the thing it reaches for.
+    expect(withoutComments).toContain("commandInvocation");
+  });
 });

tests/startup-prompt.test.ts

@@ -55,7 +55,12 @@ describe("startup star prompt", () => {
   test("the star prompt only appears when gh can actually star", async () => {
     const prompt = await readText("src/cli/star-prompt.ts");
 
-    expect(prompt).toContain('spawnSync("gh", ["auth", "status"]');
+    // The invariant is that the prompt is gated on a real `gh auth status`
+    // check, not that the call is spelled a particular way. The call now goes
+    // through the shared Windows launcher (a bare `gh` spawn stalls on a `.cmd`
+    // shim), so assert the arguments and the resolver rather than the literal.
+    expect(prompt).toContain('ghInvocation(["auth", "status"])');
+    expect(prompt).toContain('commandInvocation("gh"');
     expect(prompt).toContain("if (!ghAvailable()) return;");
   });