Add a Windows Counterpart to the Linux Bootstrap Loader

[ptr727]

What

Adds host-setup/bootstrap.ps1, a Windows counterpart to host-setup/bootstrap.sh, so a Windows host with nothing can be stood up from a copy-paste console snippet the same way a Linux host already can.

Why

Windows previously carried no loader, by a documented decision (host-setup/README.md, docs/host-setup.md, host-setup/windows/README.md's "Why There Is No bootstrap.ps1"): "the Windows form of that problem has no one-liner anybody here has run, and an unverified loader is worse than none." This PR supersedes that decision rather than ignoring it — the reasoning is kept and repurposed as the reason bootstrap.ps1 does more defensive work than its Linux peer (TLS pinning, a tree-ownership marker, execution-policy handling, self-installing its own prerequisite) rather than as the reason none exists.

How

• bootstrap.ps1 runs under Windows PowerShell 5.1, the one shell a fresh Windows host guarantees. It finds or installs PowerShell 7 via winget, then hands the rest of the run to itself under pwsh.
• From there it mirrors bootstrap.sh: resolves the ref to a commit, fetches/extracts the tarball with an ownership marker guarding cleanup, and drives upgrade-host.ps1 → install-tools.ps1 → setup-github.ps1 in the same fixed order (packages first, GitHub last since it's the only step waiting on a human in a browser).
• Adds a new -Wsl action (report-only — setup-wsl.ps1 has no Linux peer, and no flag here collects a distribution name to install one unattended).
• Sits beside bootstrap.sh at host-setup/ rather than inside host-setup/windows/, the same one-concern-two-platforms shape agent-safety/install.sh + install.ps1 already uses.
• Docs (host-setup/README.md, docs/host-setup.md, host-setup/windows/README.md) updated to describe the new loader and its Windows one-liner, replacing the "no bootstrap.ps1" sections.
• scripts/test_bootstrap.py extended: the loader-invariant tests (fetched-tree-path, no-Python) now run against both loaders, plus a new presence/no-shebang test for bootstrap.ps1.

What this does not verify

Neither loader (the existing bootstrap.sh nor this new bootstrap.ps1) has ever been run against a genuinely fresh host — only dry runs and reads against an already-configured checkout. TODO.md now tracks that as its own work cluster ("Neither Host Bootstrap Has Run Against a Truly Fresh Host"), since closing it needs a human watching a real run on a real fresh VM image, not more code.

Verification performed

• PSScriptAnalyzer (pinned 1.23.0, matching CI): clean.
• scripts/test_bootstrap.py: passing.
• scripts/prose_lint.py . --diff HEAD and scripts/repo_gate.py --check eol: clean (the local pre-commit gate).
• Parsed and ran -Help under actual Windows PowerShell 5.1.
• Full -DryRun runs against develop under pwsh for -Report, -Host -Yes, -Wsl, and the PS5.1→pwsh7 reinvocation handoff forced via powershell.exe — all completed cleanly, correctly drove the real tool scripts, and left no orphaned trees afterward.
• Confirmed two-actions-given correctly refuses, matching the sibling scripts' convention.

[Copilot]

Pull request overview

Adds a Windows bootstrap loader (host-setup/bootstrap.ps1) that mirrors the existing Linux loader (bootstrap.sh), enabling “copy/paste from a stock host” setup on native Windows. The PR also updates docs and tests to reflect/support having two platform bootstraps.

Changes:

• Add host-setup/bootstrap.ps1 (PowerShell 5.1 entrypoint that installs/locates PowerShell 7, fetches/extracts a tarball, and drives host-setup/windows/* scripts).
• Extend scripts/test_bootstrap.py to assert the loader invariants for both bootstraps and to validate bootstrap.ps1 presence/no-shebang.
• Update host setup documentation and TODO tracking to describe the new Windows bootstrap path and record the still-unverified “fresh host” runs.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
TODO.md	Adds a tracked work cluster for verifying both bootstraps on truly fresh images; adds link refs for the two loaders.
scripts/test_bootstrap.py	Refactors loader-invariant assertions to run against both bootstrap.sh and bootstrap.ps1; adds a bootstrap.ps1 presence/no-shebang test.
host-setup/windows/README.md	Replaces the “no bootstrap.ps1” rationale with usage/behavior notes for the new Windows loader and updates examples/status list.
host-setup/README.md	Documents the new Windows one-liner and explains the PS 5.1 → PS 7 handoff behavior.
host-setup/bootstrap.ps1	New Windows bootstrap loader implementing ref resolution, tarball fetch/extract with ownership marker, and fixed-order tool execution (plus report-only WSL action).
docs/host-setup.md	Updates the host-setup contract narrative to include the Windows loader and its “no Python” implications.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

host-setup/bootstrap.ps1:137

• Resolve-Pwsh unconditionally calls Join-Path ${env:ProgramFiles(x86)} .... On systems where ProgramFiles(x86) is unset (e.g., 32-bit Windows / unusual environments), Join-Path will throw (and $ErrorActionPreference = 'Stop' makes it terminating), preventing the loader from running.

    foreach ($candidate in @(
            (Join-Path $env:ProgramFiles 'PowerShell\7\pwsh.exe')
            (Join-Path ${env:ProgramFiles(x86)} 'PowerShell\7\pwsh.exe')
        )) {
        if (Test-Path $candidate) { return $candidate }

host-setup/bootstrap.ps1:150

• Install-Pwsh doesn't check winget's exit code. If winget install fails, the script still continues and then errors with a misleading message about winget reported installing PowerShell 7.

    step 'Installing PowerShell 7'
    & winget install --id Microsoft.PowerShell --exact --source winget --accept-source-agreements --accept-package-agreements --silent --disable-interactivity | Out-Host
    $found = Resolve-Pwsh
    if (-not $found) {
        die 'winget reported installing PowerShell 7, but pwsh could still not be found. Close this console and paste the setup lines again, or install it from https://aka.ms/PSWindows.'

[ptr727]

Answering the 2 suppressed (low-confidence) findings from the review round on 5a700a7 ("Suppressed comments (2)"):

host-setup/bootstrap.ps1:137 — Resolve-Pwsh unconditionally Join-Paths ${env:ProgramFiles(x86)}, which is unset on a host with no WOW64 layer, and Join-Path on a null path is a terminating error under Set-StrictMode.
Fixed in 157689f: that candidate is now only added to the search list when the variable actually carries a value.

host-setup/bootstrap.ps1:150 — Install-Pwsh didn't check winget's exit code, so a genuine winget install failure surfaced only as the generic "reported installing... but pwsh could still not be found" message.
Fixed in 157689f: winget's exit code is now named in the die message when pwsh still can't be found afterward. Kept the existing "check whether pwsh was actually found" as the authoritative signal rather than trusting the exit code alone — that's still the more reliable check (a 0 exit with pwsh still missing is a real, if unlikely, case worth surfacing too) — but the exit code is now included for diagnosis either way.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.