gstack/scripts/lib/windows-curation.ts

/**
 * Windows-safe curation for the free suite (`--windows-only`): POSIX-only
 * source patterns, explicit known-incompatible files, and force-includes for
 * pattern hits that do not apply. Pinned by test/test-free-shards.test.ts and
 * test/windows-native-workflows.test.ts.
 */
import * as fs from 'node:fs';
import * as path from 'node:path';

const ROOT = path.resolve(import.meta.dir, '../..');

// POSIX-only patterns that indicate a test will fail on windows-latest no
// matter how the runner shards. Codex's v1.18.0.0 review flagged the first
// three as concrete examples in the existing free suite (test/ship-version-sync.test.ts:72,
// test/helpers/providers/claude.ts:22, package.json:12). We scan the test's
// own content here so the filter stays automatic as new tests land. The
// "Windows-incompatible APIs" patterns at the bottom were added after the
// first windows-free-tests CI run surfaced concrete failure modes.
const WINDOWS_FRAGILE_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
  // Hardcoded POSIX shells / commands.
  { pattern: /['"`]\/bin\/(?:ba)?sh/, reason: 'hardcoded /bin/sh or /bin/bash' },
  { pattern: /spawnSync\(['"]sh['"],|spawn\(['"]sh['"],|exec\(['"]sh /, reason: 'spawn("sh", ...)' },
  { pattern: /['"]bash -c['"]|['"]sh -c['"]/, reason: 'bash -c / sh -c' },
  { pattern: /['"`]\/tmp\//, reason: 'raw /tmp/ path (use os.tmpdir())' },
  { pattern: /['"]chmod\b/, reason: 'chmod shell command' },
  { pattern: /['"]xargs\b/, reason: 'xargs pipeline' },
  { pattern: /\bwhich claude\b/, reason: 'which claude (use Bun.which)' },
  // Windows-incompatible APIs.
  { pattern: /\.mode\s*&\s*0o[0-7]+/, reason: 'POSIX file mode bitmask (mode & 0o600 etc — Windows fakes mode bits)' },
  { pattern: /\.endsWith\(['"]\//, reason: 'hardcoded forward-slash path assertion (Windows uses \\\\)' },
  { pattern: /['"]\.\/[a-zA-Z][^"']*['"]\)\s*\.\s*toBe\(true\)/, reason: 'forward-slash path comparison' },
  // Tests that spawn a bash shebang script in bin/ via spawnSync. Git Bash on
  // Windows can run `bash /path/to/script` but spawnSync(scriptPath, ...)
  // tries to execute the file directly via CreateProcess, which fails on the
  // shebang. The pattern matches `, 'bin'` as a path-join argument (closing
  // OR followed by another segment), which catches:
  //   - path.join(ROOT, 'bin', 'script-name')        — typical
  //   - join(import.meta.dir, '..', 'bin', 'name')   — destructured (diff-scope)
  //   - path.join(ROOT, 'bin')                       — bare BIN constant (brain-sync)
  { pattern: /,\s*['"]bin['"]\s*[,)]|['"]\.?\/?bin\/[a-z][\w-]+['"]/, reason: 'spawns bin/ shebang script (Windows CreateProcess does not parse shebangs)' },
  // Tests that spawn the browse server as a subprocess via `bun run server.ts`.
  // The Bun → server.ts → Playwright path is the same one that doesn't work
  // on Windows (PR #1238 windows-pty-bun-pty-fix). Tests typically set
  // BROWSE_HEADLESS_SKIP=1 to skip the browser launch but still need a working
  // server, which they don't get on Windows.
  { pattern: /BROWSE_HEADLESS_SKIP|spawn\(\[['"]bun['"],\s*['"]run['"]/, reason: 'spawns the browse server subprocess (Bun-driven path is Windows-broken)' },
];

// Explicit known-Windows-incompatible test files that don't fit a regex
// pattern. Listed here with the precise reason. Prefer adding a pattern above
// when possible; this list is for environment-/runtime-specific tests where
// the failure mode is structural rather than detectable via source-file scan.
export const KNOWN_WINDOWS_INCOMPATIBLE: Array<{ file: string; reason: string }> = [
  // Like test/paid-rerun.test.ts (excluded by pattern), it replays a gate capture through the paid lane's --report and --rerun-plan CLI.
  { file: 'test/credential-rejection.test.ts', reason: 'replays run 39696775546 through the --report and --rerun-plan CLI of the paid lane, which runs only on Linux CI; on windows-latest that CLI exits 1 with EINVAL in open() (windows-free-shard run 39982914852)' },
  // Field list 2, W11: the review-voice install is a POSIX launcher contract, exercised end to end on Linux and macOS.
  { file: 'test/capy-review-voice.test.ts', reason: 'copies the checkout with tar -C into the temp root (GNU tar reads a D: path as a remote host) and launches the bash --for review-voice installer with a colon-joined GSTACK_LAUNCH PATH' },
  // C-pregate. Since fix wave PR 5 (item 10b) test/helpers/pregate-fixture.ts and restamp-fixture.ts
  // runBin launch bins through lib/script-invocation.ts, so gstack-pregate runs on windows-latest
  // (fix wave PR 5 windows-free-tests run). These still fail there on Linux-host expectations, not
  // on launching: the fixture's test lanes are Linux workflow jobs, which a Windows host records as
  // requires-remote obligations instead of running.
  { file: 'test/pregate-guards.test.ts', reason: 'expects the Linux-host lanes verdict and POSIX-spelled Bun paths ($HOME/.bun/bin, /gone/bun) and the POSIX fixture runner\'s runs.log; gstack-pregate itself launches through lib/script-invocation.ts' },
  { file: 'test/pregate-remote.test.ts', reason: 'expects the Linux-host lanes verdict: on Windows the fixture\'s Linux lane is a requires-remote obligation, so the small-machine and --remote cases see no local tier; gstack-pregate itself launches through lib/script-invocation.ts' },
  { file: 'test/pregate-regate.test.ts', reason: 'its REGATE and MIGRATION_COLLISION verdicts differ on windows-latest, not diagnosed in fix wave PR 5; gstack-pregate regate itself launches through lib/script-invocation.ts' },
  { file: 'test/pregate-invalidation.test.ts', reason: 'expects the Linux-host lanes verdict (the windows lane as the requires-remote obligation); on Windows the Linux lane is the obligation instead; gstack-pregate itself launches through lib/script-invocation.ts' },
  { file: 'test/pregate-selection.test.ts', reason: 'its gstack-pregate (bin) cases expect the Linux-host lanes verdict (a local lane run); on Windows the fixture\'s Linux lane is a requires-remote obligation' },
  { file: 'test/pregate-stamp-only.test.ts', reason: 'its gstack-pregate (bin) cases expect the Linux-host lanes verdict for the mapped-file and test-reads-manifest fixtures, and its mode-change case needs a POSIX exec bit and symlink; the stamp rule it drives is POSIX-run like the other pregate fixtures' },
  { file: 'test/pregate-starter.test.ts', reason: 'expects the Linux-host lanes verdict (the fixture\'s Linux lane runs locally and the no-policy row is warn); on Windows that lane is a requires-remote obligation; gstack-pregate itself launches through lib/script-invocation.ts' },
  { file: 'test/pregate-allowlist.test.ts', reason: 'spawns bin/gstack-pregate through test/helpers/pregate-fixture.ts runBin and gstack-redact through the bin shebang; the allowlist rules it drives are POSIX-run like the other pregate fixtures' },
  { file: 'test/pregate-environment.test.ts', reason: 'drives exit-127 and spawn-failure classification through a POSIX shell (bash\'s command-not-found exit) and expects the Linux-host lanes verdict; on Windows the fixture\'s Linux lane is a requires-remote obligation' },
  { file: 'test/pregate-scratch.test.ts', reason: 'asserts the 0700 mode of the per-run scratch directory and the Linux-host lanes verdict (lane and guard logs written locally); Windows fakes mode bits and makes the Linux lane a requires-remote obligation' },
  { file: 'test/pregate-bats-nested.test.ts', reason: 'expects the bats lane to run locally, which it does on a Linux host; on Windows the fixture\'s Linux lane is a requires-remote obligation' },
  { file: 'test/pregate-docs-lane-review.test.ts', reason: 'spawns bin/gstack-pregate through test/helpers/pregate-fixture.ts runBin (shebang via CreateProcess); the docs-lane selection rules it drives are POSIX-run like the other pregate fixtures' },
  { file: 'test/pregate-dart.test.ts', reason: 'its dart, flutter and fvm stand-ins are bash scripts on a colon-joined PATH, which Bun.which and CreateProcess cannot use on Windows, and its containment case needs a POSIX symlink; the Dart lane code it drives is POSIX-run like the other pregate fixtures' },
  { file: 'test/pregate-non-js.test.ts', reason: 'spawns bin/gstack-pregate through test/helpers/pregate-fixture.ts runBin and expects the Linux-host lanes verdict, like test/pregate-docs-lane-review.test.ts and test/pregate-selection.test.ts' },
  { file: 'test/pregate-remote-gbrain.test.ts', reason: 'spawns bin/gstack-pregate through test/helpers/pregate-fixture.ts runBin (shebang via CreateProcess) and runs the gbrain-shaped ci:ubicloud package script through the POSIX lane runner, like test/pregate-remote.test.ts' },
  { file: 'test/pregate-remote-stamp-only.test.ts', reason: 'expects the Linux-host lanes verdict like test/pregate-remote.test.ts (on Windows the fixture\'s Linux lane is a requires-remote obligation) and skips itself on win32 (describe.skipIf), so the curated lane would run an empty file (#3485, #3486)' },
  // C-pregate: these drive bin/gstack-issue-links and bin/gstack-ship-receipt through
  // test/helpers/pregate-fixture.ts runBin.
  { file: 'test/stamp-templates.test.ts', reason: 'spawns bin/gstack-tree-receipt through test/helpers/restamp-fixture.ts runBin (shebang via CreateProcess)' },
  { file: 'test/ship-issue-intent.test.ts', reason: 'spawns bin/gstack-issue-links and bin/gstack-ship-receipt through test/helpers/pregate-fixture.ts runBin (shebang via CreateProcess) with a `gh` shell shim on PATH' },
  // PR E2: lane ownership and evidence verification run bin/gstack-lane-check and bin/gstack-evidence
  // through test/helpers/restamp-fixture.ts runBin (shebang via CreateProcess); the lib paths are
  // exercised in the same file, so there is no Windows-safe split to keep.
  { file: 'test/lane-coordination.test.ts', reason: 'spawns bin/gstack-lane-check and bin/gstack-evidence through test/helpers/restamp-fixture.ts runBin (shebang via CreateProcess) and reruns POSIX lane commands' },
  {
    file: 'test/ship-measure-seeded-fixture.test.ts',
    reason: 'drives a POSIX shell stub project (`./evals.sh` with a shebang) that CreateProcess cannot exec; the measure runner itself is covered by ship-measure.test.ts with in-process fake runners',
  },
  {
    file: 'test/qa-evidence-producer.test.ts',
    reason: 'executes the registered Linux native actor and its inotify observer; portable capture and Windows job behavior are covered by qa-evidence.test.ts',
  },
  {
    file: 'test/qa-functional-fixture.test.ts',
    reason: 'executes graceful POSIX signal cancellation; Bun on Windows uses TerminateProcess and cannot run the fixture SIGTERM cleanup handler',
  },
  {
    file: 'test/qa-functional-observer-atomic.test.ts',
    reason: 'exercises real Linux inotify inode and directory watches through libc.so.6; Windows has no equivalent kernel interface',
  },
  {
    file: 'test/docsync-report-interface.test.ts',
    reason: 'executes registered native documentation callbacks with their real Linux inotify write observer before the model boundary',
  },
  {
    file: 'test/setup-gbrain-fixture.test.ts',
    reason: 'the fixture invokes real POSIX detector/verifier helpers through executable shebang wrappers',
  },
  {
    file: 'test/setup-gbrain-windows-mcp.test.ts',
    reason: 'drives the Windows MCP registration branch on POSIX by putting uname/claude shebang stubs on a colon-separated PATH and comparing POSIX path spellings; the console behavior it guards needs a manual Windows check',
  },
  {
    file: 'test/hermetic-skills-seeding.test.ts',
    reason: 'seeds the POSIX PTY skill runtime, whose embedded shell paths require a POSIX temporary root',
  },
  {
    file: 'test/hermetic-wiring.test.ts',
    reason: 'its runtime contract check seeds the POSIX PTY skill runtime; the curated Windows lane does not run that harness',
  },
  {
    file: 'test/pty-workspace-trust.test.ts',
    reason: 'launches the POSIX PTY harness with a fake executable and bound skill runtime',
  },
  {
    file: 'test/host-config.test.ts',
    reason: 'asserts "claude" binary on PATH (only true when running inside Claude Code, not on bare CI runner)',
  },
  {
    file: 'browse/test/findport.test.ts',
    reason: 'asserts Bun.serve.stop() is fire-and-forget — Bun behavior differs on Windows for this polyfill',
  },
  // First full run of the expanded lane (v1.66, 13 → ~258 files) surfaced
  // seven POSIX-bound files the content patterns cannot see (their
  // POSIX-ness is what they TEST, or arrives via a variable). Receipts:
  // PR #2593 windows-free-tests run 31918591602.
  {
    file: 'test/codex-under-codex-detection.test.ts',
    reason: 'drives the rendered preflight bash under a hardcoded POSIX PATH (/usr/bin:/bin) — bash is unreachable through that PATH on Windows, so every case sees empty output (v1.67 windows lane run 95234224148)',
  },
  {
    file: 'test/regression-pr1169-build-app-sed.test.ts',
    reason: 'tests sed escape sequences in build-app.sh — sed/bash are the subject under test',
  },
  {
    file: 'test/setup-conductor-worktree.test.ts',
    reason: 'tests ln -snf symlink semantics in the setup script — POSIX ln is the subject under test',
  },
  {
    file: 'test/artifacts-init-migration.test.ts',
    reason: 'runs a bash migration script + jq against a scaffolded git state — POSIX toolchain paths break under cmd spawn',
  },
  {
    file: 'test/gstack-decision-semantic.test.ts',
    reason: 'installs a fake gbrain SHEBANG SHIM on PATH; Windows spawn cannot exec shebang scripts',
  },
  {
    file: 'test/question-log-hook.test.ts',
    reason: 'spawns the PostToolUse hook script (bash shebang) directly; Windows spawn cannot exec it',
  },
  {
    file: 'browse/test/browser-skills-e2e.test.ts',
    reason: 'asserts forward-slash tier paths (<repo>/browser-skills/) that resolve with backslashes on Windows',
  },
  {
    file: 'design/test/variants-retry-after.test.ts',
    reason: 'wall-clock retry-timing assertions — flaky on the slow windows-latest runner even with widened bounds',
  },
  // Round-2 census (PR #2593 run 31919227507) after the first seven:
  {
    file: 'test/skill-census.test.ts',
    reason: 'census walk throws at module load on Windows (skill-census.ts:63) — the skills-tree symlink layout needs Developer Mode that CI runners lack',
  },
  {
    file: 'browse/test/browser-manager-unit.test.ts',
    reason: 'wedges the shard to its wall deadline on windows-latest (in-flight at kill); needs a Windows repro to diagnose — macOS + Linux lanes cover the file',
  },
  // Round-3 census (PR #2593 run 31919871680): the round-2 wedge had been
  // TRUNCATING its shard, so these seven only surfaced once shard 2 completed.
  // All the same POSIX-environment classes: PID/cmdline identity probing,
  // bash scripts as the subject under test, env-scrubbed child spawns.
  {
    file: 'browse/test/server-embedder-terminal-port.test.ts',
    reason: 'identity-based terminal-agent kill probes PID/cmdline with POSIX semantics; teardown asserts fail on windows-latest',
  },
  {
    file: 'design/test/daemon-discovery.test.ts',
    reason: 'verifyIdentity matches a spawned daemon via /proc-style cmdline probing — POSIX identity semantics',
  },
  {
    file: 'test/context-save-hardening.test.ts',
    reason: 'bash context-save/migration scripts (HOME-unset semantics, random-suffix path) are the subject under test',
  },
  {
    file: 'test/eval-list-cli.test.ts',
    reason: 'spawns the eval:list CLI via bun with a constructed env — bun resolution fails under Windows spawn',
  },
  {
    file: 'test/memory-cache-injection.test.ts',
    reason: 'exercises hook/deny-enforcement shell scripts — POSIX toolchain is the subject under test',
  },
  {
    file: 'test/migrations-v1.65.0.0.test.ts',
    reason: 'bash migration script (bunx re-fetch, .done markers) is the subject under test',
  },
  {
    file: 'test/question-preference-hook.test.ts',
    reason: 'spawns the PreToolUse preference hook (shebang script) directly; Windows spawn cannot exec it',
  },
  // Round-4 census (PR #2593 run 31920052810): unhandled errors with no
  // (fail) lines — attributed statically (the lane had no log artifact yet).
  {
    file: 'browse/test/browser-skill-commands.test.ts',
    reason: 'spawnSkill spawns bun with a constructed env — bun resolution fails under Windows spawn (unhandled, no (fail) line)',
  },
  {
    file: 'browse/test/security-audit-r2.test.ts',
    reason: 'symlink-attack fixtures (evil-link) need Developer Mode CI runners lack; expect(toThrow) fires unhandled on Windows',
  },
  // CSO comprehensive execution is qualified only for Linux containers behind
  // the POSIX watchdog and Unix-domain registry broker. Keep the portable
  // static/parser contracts in the Windows lane while leaving these exact
  // containment suites to the Linux and macOS gates.
  {
    file: 'test/cso-preparation-adversarial.test.ts',
    reason: 'exercises POSIX prepared-tree and archive-cache containment for qualified Linux Docker execution, which Windows does not admit',
  },
  {
    file: 'test/cso-preparation-container.test.ts',
    reason: 'asserts POSIX permission and symlink semantics for inert exports consumed by qualified Linux Docker execution',
  },
  {
    file: 'test/cso-preparation-executor.test.ts',
    reason: 'executes the Linux Docker acquisition path and its Unix-domain registry broker; comprehensive execution is unavailable on Windows',
  },
  {
    file: 'test/cso-verification-cleanup.test.ts',
    reason: 'spawns the POSIX detached watchdog used by contained repair verification, which Windows intentionally leaves unavailable',
  },
  {
    file: 'test/cso-witness.test.ts',
    reason: 'tests the contained repair witness with POSIX private-directory and compiled-helper assumptions; comprehensive execution is unavailable on Windows',
  },
  {
    file: 'test/shard-engine-equivalence.test.ts',
    reason: 'its classification golden was recorded from the POSIX runners (process-group wall kill); the win32 engine path is pinned by the mocked-platform case in shard-engine.test.ts',
  },
  {
    file: 'test/claude-overlay-setup-default.test.ts',
    reason: 'every case runs the real ./setup under describe.skipIf(win32); its bin/ spawns live in test/helpers/claude-overlay-fixture.ts, so the source scan misses them',
  },
  {
    file: 'test/claude-overlay-setup-installs.test.ts',
    reason: 'every case runs the real ./setup under describe.skipIf(win32); its bin/ spawns live in test/helpers/claude-overlay-fixture.ts, so the source scan misses them',
  },
  {
    file: 'test/cso-scanner-cli.test.ts',
    reason: 'drives the prebuilt POSIX CSO launcher with /usr/bin/git and a POSIX-only PATH; native Windows launcher behavior is covered by the dedicated cso-windows-launcher gate',
  },
  // C-stamp (ship policy, restamp, tree receipt, evidence bundle, ship receipt):
  // every case spawns bin/ shebang scripts and a #!/bin/sh `gh` shim through
  // test/helpers/restamp-fixture.ts, so the source scan misses them.
  {
    file: 'test/gstack-ship-policy.test.ts',
    reason: 'spawns bin/gstack-ship-policy (shebang) through test/helpers/restamp-fixture.ts; the policy schema and loader are pure lib code covered on the POSIX gates',
  },
  {
    file: 'test/restamp-command-boundary.test.ts',
    reason: 'spawns bin/gstack-restamp (shebang) and a POSIX release tool through test/helpers/restamp-fixture.ts',
  },
  {
    file: 'test/tree-receipt-stamp-sensitive.test.ts',
    reason: 'spawns bin/gstack-tree-receipt, bin/gstack-restamp and bin/gstack-evidence (shebangs) plus a #!/bin/sh gh shim through test/helpers/restamp-fixture.ts',
  },
  {
    file: 'test/evidence-bundle-portability.test.ts',
    reason: 'spawns bin/gstack-evidence and bin/gstack-tree-receipt (shebangs) through test/helpers/restamp-fixture.ts',
  },
  {
    file: 'test/gstack-ship-receipt.test.ts',
    reason: 'spawns bin/gstack-ship-receipt and bin/gstack-artifact (shebangs) plus a #!/bin/sh gh shim through test/helpers/restamp-fixture.ts',
  },
  // Field list 2, W1 (shared merge queue): same fixture helpers, same shebang spawns.
  {
    file: 'test/gstack-ship-queue.test.ts',
    reason: 'spawns bin/gstack-ship-queue (shebang) and a #!/bin/sh gh shim through test/helpers/restamp-fixture.ts and test/helpers/ship-queue-fixture.ts',
  },
  // GSTA-49 T1 (merge trains): the train lib logic runs on Windows in test/ship-queue-train-logic.test.ts.
  {
    file: 'test/ship-queue-train.test.ts',
    reason: 'drives bin/gstack-ship-queue against the stateful #!/bin/sh gh shim in test/helpers/ship-queue-train-fixture.ts; on windows-latest spawnSync(\'gh\') resolves the runner\'s gh.exe instead of the shim (windows-free-shard run 39152702056)',
  },
  {
    file: 'test/ship-queue-train-cost.test.ts',
    reason: 'drives bin/gstack-ship-queue train verdict against the same #!/bin/sh gh shim in test/helpers/ship-queue-train-fixture.ts; on windows-latest spawnSync(\'gh\') resolves the runner\'s gh.exe instead of the shim (windows-free-shard 2 on #3478 at d5e6a7d)',
  },
  {
    file: 'test/ship-queue-train-ops.test.ts',
    reason: 'drives bin/gstack-ship-queue (screen verdicts, scratch-merge screens, prune --stale, watch, forget, verify --post-merge, ready --dispatch-ci, --stack-tests) against the same #!/bin/sh gh shim in test/helpers/ship-queue-train-fixture.ts',
  },
  {
    file: 'test/ship-policy-compat.test.ts',
    reason: 'spawns bin/gstack-ship-policy, bin/gstack-restamp and bin/gstack-tree-receipt (shebangs) through test/helpers/restamp-fixture.ts',
  },
  {
    file: 'test/tree-receipt-gbrain-pair.test.ts',
    reason: 'spawns bin/gstack-tree-receipt and bin/gstack-ship-policy (shebangs) through test/helpers/restamp-fixture.ts',
  },
  {
    file: 'test/restamp-gate-ahead-changelog.test.ts',
    reason: 'spawns bin/gstack-restamp (shebang) and a POSIX release tool through test/helpers/restamp-fixture.ts',
  },
];

// Force-include overrides: files a WINDOWS_FRAGILE_PATTERNS regex excludes for
// a reason that does not actually apply to them. Each entry documents WHY the
// pattern hit is a false positive — the point of these files is Windows
// coverage, so auto-excluding them defeats the regression tests they carry.
export const KNOWN_WINDOWS_SAFE: Array<{ file: string; reason: string }> = [
  // Named Windows coverage for fixes whose bug only bites on Windows: kept in
  // the curated lane even if a future edit trips a content pattern.
  { file: 'browse/test/cli-chain-stdin.test.ts', reason: 'piped-stdin browse chain against a stub daemon, and no-flow usage errors before any daemon boots; spawns the CLI through Bun argv' },
  { file: 'browse/test/runtime-root-server-bundle.test.ts', reason: 'a runtime root copy without node_modules resolves the checkout bundle via .source-path and refuses on version skew; os.tmpdir layouts only' },
  { file: 'test/cso-windows-docker.test.ts', reason: '/cso docker.exe discovery under known-folder roots (real path, no reparse points) and the native-transport-unsupported outcome; pure win32 path logic' },
  { file: 'test/copilot-windows-bash.test.ts', reason: 'the Copilot glossary line that runs bash blocks in Git for Windows Bash; reads host config only' },
  { file: 'test/ship-hook-windows-paths.test.ts', reason: 'runs bin/ helpers through explicit bash and Bun argv with forward-slash paths; never executes a shebang; the path-spelling simulation is skipIf win32' },
  { file: 'test/gstack-wtree-windows-paths.test.ts', reason: '#3101: runs bin/gstack-wtree through explicit bash in an os.tmpdir linked worktree with forward-slash paths; never executes a shebang; the drive-letter simulation is skipIf win32' },
  { file: 'test/setup-hook-syntax-gate.test.ts', reason: '#3088/#3100: runs bin/gstack-hook-check and the setup hook sections through explicit bash with forward-slash paths; never executes a shebang. Its Bun drive-path spelling is the Windows bug it guards' },
  { file: 'test/bun-config-shell-bins.test.ts', reason: '#3415: runs the record bins through lib/script-invocation.ts (Git Bash on Windows) with MSYS path conversion off, the case it guards; its bun and cygpath stand-ins and simulated-OSTYPE cases are skipIf win32' },
  { file: 'test/path-spelling.test.ts', reason: 'sources bin/gstack-path-spelling.sh through explicit bash and checks lib/path-spelling.ts; on Windows it exercises the real Git Bash spellings' },
  { file: 'test/state-root-parity.test.ts', reason: 'runs the bash twin and lib/state-root.ts over an env table with PATH empty; no shebang execution, raw-string comparison is platform-neutral' },
  { file: 'test/generator-eexist.test.ts',
    reason: 'E4: runs the generators through Bun argv with the Windows EEXIST emulation preload; no shebang execution' },
  { file: 'test/gstack-config-gbrain-refresh.test.ts', reason: 'E6: runs bin/gstack-config through explicit bash; its gbrain/python3 shims are found by bash PATH lookup, never launched by CreateProcess' },
  { file: 'test/hook-scripts.test.ts', reason: '#3067 PowerShell and NotebookEdit hook coverage: every hook runs through spawnSync("bash", [script]) with the payload on stdin, scratch state lives under os.tmpdir(); its /tmp/ literals are payload strings, never opened; symlink, newline-path and POSIX-PATH cases are skipIf win32' },
  { file: 'test/gstack-doctor.test.ts', reason: 'runs bin/gstack-doctor and setup --status through explicit bash argv in an os.tmpdir fixture; its bun/codex/claude/probe stubs are found by bash PATH lookup, and expected paths use bash spellings' },
  // Fix wave PR 5 (item 10b, #3197): the fixture runBin launches bins through lib/script-invocation.ts
  // (bun bins as Bun argv, bash bins through Git Bash); passed on windows-latest in the fix wave PR 5 windows-free-tests run.
  { file: 'test/gstack-regen.test.ts', reason: 'runs bin/gstack-regen through the fixture runBin (lib/script-invocation.ts) and its regen commands through the resolved Git Bash' },
  {
    file: 'test/qa-evidence.test.ts',
    reason: 'invokes the production helper through Bun argv and exercises native Windows job cleanup, private file captures and backpressured receipt output',
  },
  {
    file: 'test/qa-evidence-selection.test.ts',
    reason: 'bin/ strings are literal dependency and Windows-selection assertions; no native actor or shebang command is launched',
  },
  {
    file: 'test/qa-deadline.test.ts',
    reason: 'launches the guard through Bun argv; mode assertions and POSIX signal cases are platform-gated, while Windows job cleanup must execute natively',
  },
  {
    file: 'test/qa-deadline-selection.test.ts',
    reason: 'bin/ strings are dependency-selection inputs; this suite never launches a shebang executable',
  },
  {
    file: 'test/shared-libs-source-reads.test.ts',
    reason: 'bin/ literal is a mocked launch assertion; actual worktree fingerprinting explicitly invokes Bash on Windows',
  },
  {
    file: 'test/claude-code-windows-job.test.ts',
    reason: 'invokes Bun directly; verifies Windows job containment at the standalone CLI boundary',
  },
  {
    file: 'test/claude-code-runner.test.ts',
    // The bin/ path is launched through process.execPath (Bun), never as a shebang; keep taskkill supervision in the Windows lane.
    reason: 'invokes the runner via Bun argv; fake CLI and timeout descendant assertions cover native Windows taskkill',
  },
  {
    file: 'test/setup-gbrain-remote-caller.test.ts',
    // bin is an expected PATH component; the adapter injects the SDK boundary
    // and never launches a shebang. Keep the native delimiter cases in CI.
    reason: 'replays the registered SDK callback with fixture-only bin paths; covers native Windows PATH composition',
  },
  {
    file: 'test/cso-windows-build-contract.test.ts',
    // bin is a temporary staging directory. The adapter injects spawnSync;
    // real PowerShell/native execution remains in cso-windows-launcher.
    reason: 'replays the native build callbacks with an injected subprocess; bin paths are staging fixtures, not shebang launches',
  },
  {
    file: 'test/setup-windows-rerun-refresh.test.ts',
    // Trips the "spawns bin/ shebang script" pattern via path.join(..., 'bin',
    // 'tool.sh') fixture paths, but every spawn goes through test/helpers/bash-script.ts
    // (bash <tempfile>) — Git Bash executes it fine on windows-latest, with no argv-length ceiling. This file IS
    // the #2444 Windows regression coverage (IS_WINDOWS=1 copy-refresh path);
    // excluding it here would keep the bug class unexercised on the one
    // platform it bites.
    reason: 'bin/ hits are fixture path segments; spawns bash explicitly — the IS_WINDOWS=1 refresh path must run on windows-latest',
  },
  {
    file: 'test/uninstall-windows-copies.test.ts',
    // Trips the "spawns bin/ shebang script" pattern via the
    // path.join(ROOT, 'bin', 'gstack-uninstall') constant, but the script is
    // always spawned through spawnSync('bash', [UNINSTALL, ...]). This file
    // carries the #2563 Windows real-dir-copy uninstall coverage — the bug
    // ONLY reproduces on the copy install shape windows-latest exercises.
    // The symlink-shape describe block self-skips on win32.
    reason: 'bin/ hit is a bash-spawned script path; #2563 real-dir uninstall coverage must run on windows-latest',
  },
  {
    file: 'browse/test/file-permissions.test.ts',
    // Trips the POSIX-mode-bitmask pattern, but every `mode & 0o777` assertion
    // is platform-guarded: win32-only tests return early, POSIX-only tests
    // guard the bitmask behind `process.platform !== 'win32'`, and the
    // symlink-skip regression test both wraps symlinkSync in try/catch
    // (runners without Developer Mode can't create symlinks) and guards its
    // bitmask — on win32 it asserts behavior (warns, skips, doesn't throw,
    // target stays usable), never fake Windows mode bits (dirs stat 0o777
    // there, so a 0o755 expectation fails on runner semantics, not our code).
    // This file carries the win32-only icacls-by-SID regression tests, which
    // can ONLY execute on windows-latest — excluding it here means the
    // machine-account ACL lockout regression is never exercised on the one
    // platform it bricks.
    reason: 'every mode-bitmask assertion is guarded off win32 (behavior asserted instead); win32-only ACL regression tests must run on windows-latest',
  },
  {
    file: 'browse/test/terminal-agent-owner-watchdog.test.ts',
    // Trips the spawn(['bun','run',...]) pattern, whose reason is the
    // Playwright-bound browse server. This test spawns terminal-agent.ts,
    // which imports only fs/path/crypto + local helpers (no Playwright, no
    // PTY at module scope) and boots under Bun on Windows — the owner-PID
    // orphan leak it pins was reported on Windows (#2019).
    reason: 'spawns terminal-agent (no Playwright), not the browse server; owner-orphan leak is a Windows defect',
  },
  {
    file: 'test/timeline-stop-hook-slug.test.ts',
    // Trips the "spawns bin/ shebang script" pattern via the fixture's
    // path.join(tree, 'bin', 'gstack-slug') stub, but the hook runs through
    // Bun argv and reaches the stub through runBin, which hands it to Git
    // Bash on win32. #3103 is a Windows latency defect: this lane is the one
    // place the hook's return-within-budget assertion meets real Windows
    // process startup.
    reason: '#3103: the hook runs through Bun argv and its gstack-slug stub through runBin (Git Bash on win32); the return-within-budget timing must run on windows-latest',
  },
];

/**
 * Pattern hits disproved by running each excluded file alone on windows-latest
 * (temporary probe run 37221995077, Bun 1.4.0, Chromium installed): every case
 * passed and at least one case executed. Their /tmp/ literals are fixture
 * strings or platform-gated, never opened on Windows.
 */
export const WINDOWS_PROBE_SAFE: string[] = [
  'browse/test/data-platform.test.ts',
  'browse/test/dual-listener.test.ts',
  'browse/test/error-handling.test.ts',
  'browse/test/learnings-injection.test.ts',
  'browse/test/pdf-flags.test.ts',
  'browse/test/security-adversarial.test.ts',
  'browse/test/tunnel-gate-unit.test.ts',
  'browse/test/xprotect-heal.test.ts',
  'design/test/feedback-roundtrip.test.ts',
  'ios-qa/daemon/test/tailscale-localapi.test.ts',
  'make-pdf/test/asideClient.test.ts',
  'make-pdf/test/e2e/diagram-gate.test.ts',
  'make-pdf/test/e2e/emoji-gate.test.ts',
  'make-pdf/test/e2e/format-gate.test.ts',
  'make-pdf/test/e2e/landscape-gate.test.ts',
  'test/brain-preflight.test.ts',
  'test/ceo-barless-submit.test.ts',
  'test/ceo-split-collection.test.ts',
  'test/ceo-split-question-policy.test.ts',
  'test/ci-paid-coordination.test.ts',
  'test/design-md.test.ts',
  'test/document-skills-redaction.test.ts',
  'test/evals-workflow-wiring.test.ts',
  'test/gbrain-guards.test.ts',
  'test/global-discover.test.ts',
  'test/helpers-unit.test.ts',
  'test/helpers/hermetic-env.test.ts',
  'test/office-hours-review.test.ts',
  'test/paid-run-manifest.test.ts',
  'test/paid-shards.test.ts',
  'test/plan-count-completion.test.ts',
  'test/plan-design-floor-fixture.test.ts',
  'test/pty-skill-seeding-wiring.test.ts',
  'test/regression-issue2091-bsd-mktemp.test.ts',
  'test/regression-pr1169-mktemp-fallbacks.test.ts',
  'test/resolvers-gbrain-save-results.test.ts',
  'test/skill-preflight-budget.test.ts',
  'test/takes-fence-fallback.test.ts',
  'test/terse-build.test.ts',
  'test/typecheck-test-ratchet.test.ts',
];

/**
 * Returns the first POSIX-only pattern hit in the file, or null if Windows-safe.
 */
export function detectWindowsFragility(absolutePath: string): { reason: string } | null {
  let content: string;
  try {
    content = fs.readFileSync(absolutePath, 'utf-8');
  } catch {
    return null;
  }
  for (const { pattern, reason } of WINDOWS_FRAGILE_PATTERNS) {
    if (pattern.test(content)) return { reason };
  }
  return null;
}

export interface CurationResult {
  safe: string[];
  excluded: Array<{ file: string; reason: string }>;
}

export function curateWindowsSafe(files: string[], rootDir = ROOT): CurationResult {
  const safe: string[] = [];
  const excluded: Array<{ file: string; reason: string }> = [];
  const knownBad = new Map(KNOWN_WINDOWS_INCOMPATIBLE.map((e) => [e.file, e.reason]));
  const knownSafe = new Set([...KNOWN_WINDOWS_SAFE.map((e) => e.file), ...WINDOWS_PROBE_SAFE]);
  for (const relativePath of files) {
    const knownReason = knownBad.get(relativePath);
    if (knownReason) {
      excluded.push({ file: relativePath, reason: knownReason });
      continue;
    }
    if (knownSafe.has(relativePath)) {
      safe.push(relativePath);
      continue;
    }
    const absolute = path.join(rootDir, relativePath);
    const fragility = detectWindowsFragility(absolute);
    if (fragility) {
      excluded.push({ file: relativePath, reason: fragility.reason });
    } else {
      safe.push(relativePath);
    }
  }
  return { safe, excluded };
}