[INSTALL-03] [P1] Add a per-user PowerShell installer for Windows #553

Goal

Install the published Windows CLI and daemon without manual ZIP extraction, editing environment settings by hand, or requiring administrator access.

Priority: P1 · Classification: New distribution feature

Reviewed baseline: main 56ad6438653f, 6 October 2026. Published distribution inspected: v0.8.0 (CLI build commit 615e501). Recheck these installation surfaces against the current branch before implementing.

Current behavior and evidence

The Windows release is a ZIP containing semaprax.exe and semapraxd.exe. There is no public PowerShell bootstrap or native installer attached to v0.8.0.

The current technical guide tells Windows users to unzip an archive and arrange PATH themselves. scripts/package-release.ps1 is a build/package script, not a user installer.

The shared release/install contract must keep compiler and daemon from the same version together. semapraxd does not support --version; derive its identity from the verified archive and installed-file receipt.

• Maintainer package script
• Windows archive contents
• Manual Windows ZIP installation
• Full CLI naming in archives
• Current Windows x64 release target
• v0.8.0 Windows archive

Implementation scope

1. Add scripts/install.ps1 and publish it as an explicitly inventoried release asset. Use the version, asset-selection, ownership and verification contract established by [INSTALL-02] [P1] Add a one-command Unix installer with version pinning and clean removal #552, with native PowerShell implementation and parameters such as -Version, -InstallDir, -NoModifyPath and -Uninstall.
2. Install under a user-owned LocalAppData location by default, without requiring elevation. Cover Windows PowerShell 5.1 and supported PowerShell 7, or publish an intentional narrower prerequisite before advertising the command.
3. Detect Windows process/OS architecture deliberately. Initially support the actual x64 asset. On an unsupported native architecture, explain available tested choices instead of silently claiming ARM64 support.
4. Resolve a release once, download the exact ZIP and its selected-platform verification material, verify before execution/activation, and validate extraction paths. Use native facilities for archive extraction and hashing while sharing the existing provenance trust policy; do not depend on Git Bash, a Rust toolchain or manual jq installation.
5. Stage both executables and metadata as one managed installation. Handle in-use Windows files with a clear close/retry instruction and preserve the installed version on failure; do not kill arbitrary user processes or leave only one executable updated.
6. Update only the user PATH using proper Windows APIs when requested, preserve existing entries and length, and avoid duplicate entries or truncating setx patterns. Report that already-running terminals/editors need refresh; make the exact current-session action available.
7. Support idempotent reinstallation, explicit version pinning, managed upgrades and receipt-scoped removal. Honor a custom path with spaces or non-ASCII characters and do not take over a Homebrew/WinGet/manual installation.
8. Document an inspectable download-and-run flow as well as the concise command. Do not permanently change PowerShell execution policy or disable Windows security controls. A managed workstation that blocks scripts must receive a useful supported alternative.

Acceptance criteria

• A standard non-admin user installs semaprax.exe and semapraxd.exe, opens a new shell and runs new/check/test/run with result 42.
• The advertised PowerShell versions both pass the real installation journey, including a path with spaces.
• User PATH is updated at most once and unrelated PATH content survives install, upgrade and uninstall.
• Wrong architecture, missing utilities, corrupted ZIP, failed verification, download failure and a running locked binary produce a clear nonzero result while retaining the old installation.
• Version selection is consistent across archive and metadata requests, and unsupported emulation is never silently assumed.
• Uninstall removes only owned installation data/PATH changes and retains projects, credentials and unrelated executables.
• The PowerShell installer is covered by the existing release checksum, attestation/provenance and explicit asset-inventory policy, and is advertised only after its release asset exists. This does not introduce a separate Authenticode-certificate requirement.

Verification

• Add native PowerShell tests for parameter binding, PATH idempotence, traversal refusal, same-version reinstall and locked-file failure.
• Run the public bootstrap on a clean Windows x64 user account against the exact produced release artifact, then use the documented first-project commands.
• Use installed receipt hashes or a supported daemon handshake for daemon identity; do not add a bogus semapraxd --version assertion.

Existing issues and boundaries

• #167 owns exact-tag release admission. Extend its asset contract for install.ps1.
• #454 explicitly distinguishes Windows harness availability. Installing the Windows CLI does not establish Windows support for all harness operations.
• WinGet packaging is separate channel work; this script provides a supported manual/automation route and the common lifecycle semantics.

Implementation dependencies

• [INSTALL-02] [P1] Add a one-command Unix installer with version pinning and clean removal #552

Delivery notes

Implement in the existing owning modules and test harnesses. Follow AGENTS.md and the relevant release/editor contracts. Keep fixes focused, preserve unrelated behavior, and attach the actual verification results. Do not replace existing signing, publication, project generation or harness setup with a second system.