gentle-pi 4.0.0 → 4.2.0

package/scripts/bootstrap.cmd

@@ -0,0 +1,255 @@
+@echo off
+setlocal DisableDelayedExpansion
+rem Trusted extracted/checkout bundle only. Never pipe a remote script here.
+rem Fixed stock PowerShell commands; paths are environment DATA, not PS source.
+rem Each invocation is below CMD's logical command length limit.
+set "GENTLE_BOOTSTRAP_BUNDLE=%~dp0.."
+set "GENTLE_BOOTSTRAP_TOOLS=%LOCALAPPDATA%\.gentle-shell-bootstrap-tools.%RANDOM%.%RANDOM%.%RANDOM%"
+set "GENTLE_BOOTSTRAP_FALLBACK_TOOLS=%USERPROFILE%\.gentle-shell-bootstrap-tools.%RANDOM%.%RANDOM%.%RANDOM%"
+set "GENTLE_BOOTSTRAP_OWNED="
+set "GENTLE_BOOTSTRAP_PS=%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe"
+if not exist "%GENTLE_BOOTSTRAP_PS%" goto unavailable
+
+rem Bundle/dependency checks precede ALL acquisition and per-user writes.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$bundle = [IO.Path]::GetFullPath($env:GENTLE_BOOTSTRAP_BUNDLE);" ^
+  "foreach ($file in @('bin/gentle-shell-install.mjs','package.json','scripts/installer-downloads.mjs','scripts/installer-windows.mjs','scripts/installer-windows-artifacts.json')) {" ^
+  "  $item = Get-Item -LiteralPath (Join-Path $bundle $file) -Force;" ^
+  "  if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Unsafe bundle file' };" ^
+  "};" ^
+  "$metadata = Get-Content -LiteralPath (Join-Path $bundle 'package.json') -Raw | ConvertFrom-Json;" ^
+  "if ($metadata.engines.node -notmatch '^>=[0-9]+\.[0-9]+\.[0-9]+$' -or $metadata.packageManager -ne 'pnpm@11.1.1') { throw 'Repository prerequisite unknown' };" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: future wizard/dependent bundle file missing, unsupported metadata, or managed policy denial. No acquisition attempted.'); exit 1 } }"
+if errorlevel 1 goto failed
+
+rem Claim an absent unique directory beneath a verified local per-user parent:
+rem %LOCALAPPDATA% first, then one %USERPROFILE% fallback only when the first fails
+rem acl-mask or home-owner. Each candidate gets the exact-parent rule and the whole
+rem walk; exit 2 means the fallback was claimed. Its owner may be the user, SYSTEM
+rem or Administrators; the new directory's owner is set to the user explicitly.
+rem No security changes outside this new prerequisite directory.
+rem Strict target/parent rights: ReadAndExecute + Synchronize (0x1200a9).
+rem Distant existing ancestors additionally permit sibling CreateDirectories (4).
+rem WriteData/reparse-affecting writes, deletion and ACL/owner changes still fail.
+rem Failures append one fixed reason code (the failed check), then one line per
+rem candidate naming its folder and, for acl-mask, the principal and its rights;
+rem other exceptions report unexpected-<step>. ACLs use .NET, not Security-module
+rem cmdlets: PowerShell 7's inherited PSModulePath breaks their 5.1 autoload.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { $claimed = $false; $step = 'policy'; $tools = $null; $tried = @(); try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'policy' };" ^
+  "$me = [Security.Principal.WindowsIdentity]::GetCurrent().User;" ^
+  "$trusted = @($me.Value,'S-1-5-18','S-1-5-32-544','S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464');" ^
+  "$owners = @($me.Value,'S-1-5-18','S-1-5-32-544'); $account = { param($sid) try { ' (' + $sid.Translate([Security.Principal.NTAccount]).Value + ')' } catch { '' } };" ^
+  "$candidates = @(,@($env:GENTLE_BOOTSTRAP_TOOLS,$env:LOCALAPPDATA)); if ($env:GENTLE_BOOTSTRAP_FALLBACK_TOOLS) { $candidates += ,@($env:GENTLE_BOOTSTRAP_FALLBACK_TOOLS,$env:USERPROFILE) };" ^
+  "for ($index = 0; $index -lt $candidates.Count; $index++) { $base = $candidates[$index][1]; $detail = ''; try {" ^
+  "  $step = 'path-mismatch'; $tools = [IO.Path]::GetFullPath($candidates[$index][0]); $path = [IO.Directory]::GetParent($tools).FullName;" ^
+  "  if (-not [IO.Path]::IsPathRooted($base) -or $tools.StartsWith('\\') -or $path -ne [IO.Path]::GetFullPath($base)) { throw 'path-mismatch' };" ^
+  "  $depth = 1;" ^
+  "  $step = 'home-owner'; $owner = ([IO.Directory]::GetAccessControl($path)).GetOwner([Security.Principal.SecurityIdentifier]); if ($owners -notcontains $owner.Value) { $detail = ' owned by ' + $owner.Value + (& $account $owner); throw 'home-owner' };" ^
+  "  $step = 'ancestor-walk'; while ($path) {" ^
+  "    $item = Get-Item -LiteralPath $path -Force; if (-not $item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'ancestor-reparse' };" ^
+  "    $acl = [IO.Directory]::GetAccessControl($path); if ($trusted -notcontains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value) { throw 'ancestor-owner' };" ^
+  "    $allowedRights = 0x1200a9; if ($depth -ge 2) { $allowedRights = 0x1200ad };" ^
+  "    foreach ($rule in $acl.GetAccessRules($true,$true,[Security.Principal.SecurityIdentifier])) {" ^
+  "      if ($rule.AccessControlType -eq 'Allow' -and -not ($rule.PropagationFlags -band [Security.AccessControl.PropagationFlags]::InheritOnly) -and ([long]$rule.FileSystemRights -band (-bnot [long]$allowedRights)) -and $trusted -notcontains $rule.IdentityReference.Value) {" ^
+  "        $detail = ' at ' + $path + ': ' + $rule.IdentityReference.Value + (& $account $rule.IdentityReference) + ' allowed 0x' + ([int]$rule.FileSystemRights).ToString('X8'); throw 'acl-mask' };" ^
+  "    }; $parent = [IO.Directory]::GetParent($path); if ($null -eq $parent) { break }; $path = $parent.FullName; $depth++;" ^
+  "  }; break;" ^
+  "} catch { $code = 'unexpected-' + $step; if ($_.Exception.Message -cmatch '^(path-mismatch|home-owner|ancestor-reparse|ancestor-owner|acl-mask)$') { $code = $_.Exception.Message };" ^
+  "  $tried += ($base + ': ' + $code + $detail); if ($index -eq 0 -and $candidates.Count -gt 1 -and $code -cmatch '^(acl-mask|home-owner)$') { continue }; throw } };" ^
+  "$step = 'create'; if (Test-Path -LiteralPath $tools) { throw 'collision' }; $null = New-Item -ItemType Directory -Path $tools; $claimed = $true;" ^
+  "$step = 'private-acl'; $acl = New-Object Security.AccessControl.DirectorySecurity; $acl.SetOwner($me); $acl.SetAccessRuleProtection($true,$false);" ^
+  "foreach ($sid in @($me.Value,'S-1-5-18','S-1-5-32-544')) {" ^
+  "  $identity = New-Object Security.Principal.SecurityIdentifier($sid);" ^
+  "  $rule = New-Object Security.AccessControl.FileSystemAccessRule($identity,'FullControl','ContainerInherit,ObjectInherit','None','Allow'); $acl.AddAccessRule($rule);" ^
+  "}; [IO.Directory]::SetAccessControl($tools,$acl);" ^
+  "$verified = [IO.Directory]::GetAccessControl($tools); if (-not $verified.AreAccessRulesProtected) { throw 'protected-dacl' };" ^
+  "if ($verified.GetOwner([Security.Principal.SecurityIdentifier]).Value -ne $me.Value) { throw 'private-owner' };" ^
+  "foreach ($rule in $verified.GetAccessRules($true,$true,[Security.Principal.SecurityIdentifier])) { if ($rule.AccessControlType -ne 'Allow' -or @($me.Value,'S-1-5-18','S-1-5-32-544') -notcontains $rule.IdentityReference.Value) { throw 'private-ace' } };" ^
+  "$step = 'marker'; $null = New-Item -ItemType File -Path (Join-Path $tools '.bootstrap-owned') -Value 'gentle-pi prerequisite tooling only';" ^
+  "if ($index -gt 0) { exit 2 };" ^
+  "} catch { $reason = 'unexpected-' + $step; if ($_.Exception.Message -cmatch '^(policy|path-mismatch|home-owner|ancestor-reparse|ancestor-owner|acl-mask|collision|protected-dacl|private-owner|private-ace)$') { $reason = $_.Exception.Message };" ^
+  "if ($step -cmatch '^(create|private-acl|marker)$') { $tried += ($tools + ': ' + $reason) };" ^
+  "if ($claimed) { Remove-Item -LiteralPath $tools -Recurse -Force -ErrorAction SilentlyContinue }; [Console]::Error.WriteLine('Bootstrap: private storage ACL/reparse/ownership claim failed or policy denied it. Reason: ' + $reason); foreach ($line in $tried) { [Console]::Error.WriteLine('Bootstrap: storage candidate ' + $line) }; exit 1 } }"
+if errorlevel 3 goto failed
+if errorlevel 2 goto fallbackclaimed
+if errorlevel 1 goto failed
+goto claimed
+:fallbackclaimed
+set "GENTLE_BOOTSTRAP_TOOLS=%GENTLE_BOOTSTRAP_FALLBACK_TOOLS%"
+:claimed
+set "GENTLE_BOOTSTRAP_FALLBACK_TOOLS="
+set "GENTLE_BOOTSTRAP_OWNED=1"
+
+rem Select an existing native Node without invoking any command interpreter shim.
+rem Absence authorizes pinned acquisition, and so does an older stable Node or one
+rem whose storage the probe below cannot trust: it is never replaced or run again.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$command = $null; try { $command = Get-Command node.exe -CommandType Application -ErrorAction Stop | Select-Object -First 1 } catch [Management.Automation.CommandNotFoundException] { $command = $null };" ^
+  "if ($null -ne $command) { $bytes = (New-Object Text.UTF8Encoding($false)).GetBytes($command.Source); $record = [IO.File]::Open((Join-Path $env:GENTLE_BOOTSTRAP_TOOLS '.node-target'),[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None); try { $record.Write($bytes,0,$bytes.Length) } finally { $record.Dispose() } };" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: existing Node resolution failed or policy denied it.'); exit 1 } }"
+if errorlevel 1 goto failed
+
+:acquirenode
+rem Fixed official ZIP transport: no redirects, bounded bytes/time, no TLS changes.
+rem Integrity is verified before ZIP processing or executable publication.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$tools = $env:GENTLE_BOOTSTRAP_TOOLS; if (Test-Path -LiteralPath (Join-Path $tools '.node-target')) { exit 0 };" ^
+  "$architecture = $env:PROCESSOR_ARCHITECTURE; if ($env:PROCESSOR_ARCHITEW6432) { $architecture = $env:PROCESSOR_ARCHITEW6432 };" ^
+  "switch ($architecture) { 'AMD64' { $arch = 'x64' } 'ARM64' { $arch = 'arm64' } default { throw 'Unsupported architecture' } };" ^
+  "$pins = Get-Content -LiteralPath (Join-Path $env:GENTLE_BOOTSTRAP_BUNDLE 'scripts/installer-windows-artifacts.json') -Raw | ConvertFrom-Json; $pin = $pins.node.$arch;" ^
+  "$stem = 'node-v24.21.0-win-' + $arch;" ^
+  "if ($pins.node.version -ne '24.21.0' -or $pin.url -ne ('https://nodejs.org/dist/v24.21.0/' + $stem + '.zip') -or $pin.sha256 -notmatch '^[a-f0-9]{64}$' -or $pins.node.maxBytes -ne 104857600) { throw 'Artifact pin rejected' };" ^
+  "$request = [Net.HttpWebRequest]::Create($pin.url); $request.AllowAutoRedirect = $false; $request.Timeout = 60000; $request.ReadWriteTimeout = 10000;" ^
+  "$watch = [Diagnostics.Stopwatch]::StartNew(); $response = $null; $output = $null; $input = $null;" ^
+  "try {" ^
+  "  $response = $request.GetResponse(); if ([int]$response.StatusCode -ne 200 -or $response.ContentLength -gt 104857600) { throw 'Download rejected' };" ^
+  "  $input = $response.GetResponseStream(); $output = [IO.File]::Open((Join-Path $tools 'node.zip'),[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None);" ^
+  "  $buffer = New-Object byte[] 65536; $total = 0;" ^
+  "  while (($count = $input.Read($buffer,0,$buffer.Length)) -gt 0) { $total += $count; if ($total -gt 104857600 -or $watch.ElapsedMilliseconds -gt 60000) { throw 'Download bound exceeded' }; $output.Write($buffer,0,$count) };" ^
+  "  if ($total -eq 0 -or ($response.ContentLength -ge 0 -and $response.ContentLength -ne $total) -or $watch.ElapsedMilliseconds -gt 60000) { throw 'Download truncated or timed out' };" ^
+  "} finally { if ($output) { $output.Dispose() }; if ($input) { $input.Dispose() }; if ($response) { $response.Dispose() } };" ^
+  "$actual = (Get-FileHash -LiteralPath (Join-Path $tools 'node.zip') -Algorithm SHA256).Hash; if ($actual -ne $pin.sha256) { throw 'Integrity mismatch' };" ^
+  "$null = New-Item -ItemType File -Path (Join-Path $tools '.node-stem') -Value $stem;" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: Node download, bounds, integrity or policy check failed.'); exit 1 } }"
+if errorlevel 1 goto failed
+
+rem Inspect the entire ZIP namespace before extracting ONLY its regular node.exe.
+rem Reject links, Windows device/ADS names, traversal and case aliases.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$tools = $env:GENTLE_BOOTSTRAP_TOOLS; if (Test-Path -LiteralPath (Join-Path $tools '.node-target')) { exit 0 };" ^
+  "Add-Type -AssemblyName System.IO.Compression.FileSystem;" ^
+  "$stem = (Get-Content -LiteralPath (Join-Path $tools '.node-stem') -Raw).Trim();" ^
+  "$zip = [IO.Compression.ZipFile]::OpenRead((Join-Path $tools 'node.zip'));" ^
+  "try {" ^
+  "  if ($zip.Entries.Count -eq 0 -or $zip.Entries.Count -gt 50000) { throw 'ZIP count rejected' };" ^
+  "  $explicit = @{}; $names = @{}; $types = @{}; $selected = $null; $expanded = 0;" ^
+  "  foreach ($entry in $zip.Entries) {" ^
+  "    $name = $entry.FullName; $directory = $name.EndsWith('/'); if ($directory) { $name = $name.Substring(0,$name.Length - 1) };" ^
+  "    $unixType = ($entry.ExternalAttributes -shr 16) -band 61440;" ^
+  "    if (($entry.ExternalAttributes -band 1024) -or ($unixType -ne 0 -and $unixType -ne 32768 -and $unixType -ne 16384) -or ($unixType -eq 16384 -and -not $directory) -or ($directory -and $entry.Length -ne 0)) { throw 'ZIP links/types rejected' };" ^
+  "    if ($entry.FullName.Contains('\') -or $explicit.ContainsKey($name)) { throw 'ZIP duplicate/path rejected' }; $explicit[$name] = $true;" ^
+  "    $parts = $name.Split('/'); $path = '';" ^
+  "    for ($index = 0; $index -lt $parts.Length; $index++) {" ^
+  "      $part = $parts[$index];" ^
+  "      if (-not $part -or $part -eq '.' -or $part -eq '..' -or $part -match '[<>:\x22|?*\x00-\x1f\x7f]' -or $part -match '[. ]$' -or $part -match '^(CON|PRN|AUX|NUL|COM[1-9\u00b9\u00b2\u00b3]|LPT[1-9\u00b9\u00b2\u00b3])(\.|$)') { throw 'ZIP Windows name rejected' };" ^
+  "      if ($path) { $path += '/' }; $path += $part; $isDirectory = $directory -or $index -lt ($parts.Length - 1);" ^
+  "      if ($names.ContainsKey($path) -and ($names[$path] -cne $path -or $types[$path] -ne $isDirectory)) { throw 'ZIP case/type alias rejected' }; $names[$path] = $path; $types[$path] = $isDirectory;" ^
+  "    };" ^
+  "    $expanded += $entry.Length; if ($expanded -gt 536870912 -or ($name -ne $stem -and -not $name.StartsWith($stem + '/',[StringComparison]::Ordinal))) { throw 'ZIP root/size rejected' };" ^
+  "    if ($name -ceq ($stem + '/node.exe')) { if ($directory -or $entry.Length -eq 0 -or $entry.Length -gt 157286400) { throw 'Node member rejected' }; $selected = $entry };" ^
+  "  }; if ($null -eq $selected) { throw 'Node member missing' };" ^
+  "  $destination = Join-Path $tools 'node'; $null = New-Item -ItemType Directory -Path $destination;" ^
+  "  $target = Join-Path $destination 'node.exe'; $output = [IO.File]::Open($target,[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None); $input = $selected.Open();" ^
+  "  try { $input.CopyTo($output) } finally { $input.Dispose(); $output.Dispose() };" ^
+  "  $bytes = (New-Object Text.UTF8Encoding($false)).GetBytes($target); $record = [IO.File]::Open((Join-Path $tools '.node-target'),[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None); try { $record.Write($bytes,0,$bytes.Length) } finally { $record.Dispose() };" ^
+  "} finally { $zip.Dispose() };" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: Node ZIP namespace, extraction or policy check failed.'); exit 1 } }"
+if errorlevel 1 goto failed
+
+rem Production direct non-forking Node probe: 10s deadline and combined 1-MiB cap.
+rem Drain both pipes asynchronously; valid output followed by a hang still fails.
+rem Failures append one fixed reason code; walk codes name the component role only.
+rem .node-target holds a possibly non-ASCII path: written and read as explicit UTF-8.
+rem The user's Node (no .node-stem) is left as it is when it is an older stable
+rem version, or when its storage fails the reparse/owner/ACL checks before it ever
+rem runs: its record is removed and the pinned Node is acquired as when absent.
+rem The acquired Node still has to pass every check; unknown versions still refuse.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { $child = $null; $started = $false; $acquired = $true; $step = 'policy'; try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'policy' };" ^
+  "$step = 'target'; $tools = $env:GENTLE_BOOTSTRAP_TOOLS; $record = Join-Path $tools '.node-target'; if (-not [IO.File]::Exists($record)) { throw 'missing-target' }; $acquired = Test-Path -LiteralPath (Join-Path $tools '.node-stem');" ^
+  "$node = [IO.File]::ReadAllText($record,[Text.Encoding]::UTF8).TrimEnd([char]13,[char]10); if (-not $node) { throw 'missing-target' };" ^
+  "$item = Get-Item -LiteralPath $node -Force; if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'unsafe-target' };" ^
+  "if (-not [IO.Path]::IsPathRooted($node) -or $node.StartsWith('\\')) { throw 'unsafe-path' };" ^
+  "$me = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value; $trusted = @($me,'S-1-5-18','S-1-5-32-544','S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464'); $path = $node;" ^
+  "$depth = 0;" ^
+  "$step = 'acl-walk'; while ($path) {" ^
+  "  $role = 'ancestor'; if ($depth -eq 0) { $role = 'target' } elseif ($depth -eq 1) { $role = 'parent' };" ^
+  "  $item = Get-Item -LiteralPath $path -Force; if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw ($role + '-reparse') };" ^
+  "  if ($item.PSIsContainer) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };" ^
+  "  if ($trusted -notcontains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value) { throw ($role + '-owner') };" ^
+  "  $allowedRights = 0x1200a9; if ($depth -ge 2) { $allowedRights = 0x1200ad };" ^
+  "  foreach ($rule in $acl.GetAccessRules($true,$true,[Security.Principal.SecurityIdentifier])) { if ($rule.AccessControlType -eq 'Allow' -and -not ($rule.PropagationFlags -band [Security.AccessControl.PropagationFlags]::InheritOnly) -and ([long]$rule.FileSystemRights -band (-bnot [long]$allowedRights)) -and $trusted -notcontains $rule.IdentityReference.Value) { throw ($role + '-acl-mask') } };" ^
+  "  $parent = [IO.Directory]::GetParent($path); if ($null -eq $parent) { break }; $path = $parent.FullName; $depth++;" ^
+  "};" ^
+  "$start = New-Object Diagnostics.ProcessStartInfo; $start.FileName = $node; $start.Arguments = '--version'; $start.UseShellExecute = $false; $start.CreateNoWindow = $true; $start.RedirectStandardOutput = $true; $start.RedirectStandardError = $true;" ^
+  "$step = 'start'; $child = New-Object Diagnostics.Process; $child.StartInfo = $start; if (-not $child.Start()) { throw 'no-start' }; $started = $true;" ^
+  "$step = 'drain'; $streams = @($child.StandardOutput.BaseStream,$child.StandardError.BaseStream); $buffers = @((New-Object byte[] 4096),(New-Object byte[] 4096));" ^
+  "$tasks = @($streams[0].ReadAsync($buffers[0],0,4096),$streams[1].ReadAsync($buffers[1],0,4096)); $closed = @($false,$false); $text = ''; $total = 0; $watch = [Diagnostics.Stopwatch]::StartNew();" ^
+  "while (-not ($closed[0] -and $closed[1] -and $child.HasExited)) {" ^
+  "  if ($watch.ElapsedMilliseconds -ge 10000) { throw 'deadline' };" ^
+  "  for ($index = 0; $index -lt 2; $index++) { if (-not $closed[$index] -and $tasks[$index].IsCompleted) {" ^
+  "    $count = $tasks[$index].GetAwaiter().GetResult(); if ($count -eq 0) { $closed[$index] = $true } else {" ^
+  "      $total += $count; if ($total -gt 1048576) { throw 'output-limit' };" ^
+  "      if ($index -eq 0) { $text += [Text.Encoding]::UTF8.GetString($buffers[$index],0,$count) };" ^
+  "      $tasks[$index] = $streams[$index].ReadAsync($buffers[$index],0,4096);" ^
+  "    }" ^
+  "  } }; Start-Sleep -Milliseconds 10;" ^
+  "}; if ($child.ExitCode -ne 0) { throw 'exit-code' };" ^
+  "$step = 'version'; $version = $text.Trim(); if ($version -notmatch '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$') { throw 'version-format' };" ^
+  "$actual = [Version]$version.Substring(1); $metadata = Get-Content -LiteralPath (Join-Path $env:GENTLE_BOOTSTRAP_BUNDLE 'package.json') -Raw | ConvertFrom-Json;" ^
+  "if ($acquired -and $version -ne 'v24.21.0') { throw 'acquired-version' };" ^
+  "if ($actual -lt [Version]'24.3.0' -or $actual -lt [Version]$metadata.engines.node.Substring(2)) { if ($acquired) { throw 'engine' }; [IO.File]::Delete((Join-Path $tools '.node-target')) };" ^
+  "} catch { $reason = 'unexpected-' + $step; if ($_.Exception.Message -cmatch '^(policy|missing-target|unsafe-target|unsafe-path|(target|parent|ancestor)-(reparse|owner|acl-mask)|no-start|deadline|output-limit|exit-code|version-format|engine|acquired-version)$') { $reason = $_.Exception.Message };" ^
+  "if (-not $acquired -and $reason -cmatch '^(unsafe-target|unsafe-path|(target|parent|ancestor)-(reparse|owner|acl-mask))$') { [IO.File]::Delete((Join-Path $env:GENTLE_BOOTSTRAP_TOOLS '.node-target')) }" ^
+  "else { [Console]::Error.WriteLine('Bootstrap: Node version, execution, deadline, output bound or policy check failed; refusing replacement. Reason: ' + $reason); exit 1 } }" ^
+  "finally { try { if ($child) { if ($started -and -not $child.HasExited) { $child.Kill(); if (-not $child.WaitForExit(1000)) { throw 'Child termination unconfirmed' } }; $child.Dispose() } } catch { [Console]::Error.WriteLine('Bootstrap: direct-child termination could not be confirmed.'); exit 1 } } }"
+if errorlevel 1 goto failed
+if not exist "%GENTLE_BOOTSTRAP_TOOLS%\.node-target" goto acquirenode
+
+rem Launch the existing Node helper with data arguments; no shell evaluation.
+rem Interactive wizard duration is intentionally unbounded. Only child PATH changes.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$tools = $env:GENTLE_BOOTSTRAP_TOOLS; $record = Join-Path $tools '.node-target'; $node = [IO.File]::ReadAllText($record,[Text.Encoding]::UTF8).TrimEnd([char]13,[char]10);" ^
+  "$env:PATH = [IO.Path]::GetDirectoryName($node) + ';' + $env:PATH;" ^
+  "$helper = Join-Path $env:GENTLE_BOOTSTRAP_BUNDLE 'scripts/installer-downloads.mjs';" ^
+  "if (Test-Path -LiteralPath (Join-Path $tools 'node.zip')) { Remove-Item -LiteralPath (Join-Path $tools 'node.zip') };" ^
+  "& $node $helper '--bootstrap-windows' $env:GENTLE_BOOTSTRAP_BUNDLE $tools; if ($LASTEXITCODE -ne 0) { throw 'Helper failed' };" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: prerequisite helper/wizard failed or managed policy denied execution.'); exit 1 } }"
+if errorlevel 1 goto failed
+
+rem Success: node/npm/pnpm now persist under PNPM_HOME or were already the user's.
+rem Remove only our exact claimed, marked root; Directory.Delete does not recurse
+rem through reparse points. A removal problem never fails the installation.
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$tools = [IO.Path]::GetFullPath($env:GENTLE_BOOTSTRAP_TOOLS); $parent = [IO.Directory]::GetParent($tools).FullName;" ^
+  "if ($tools.StartsWith('\\') -or ($parent -ne [IO.Path]::GetFullPath($env:LOCALAPPDATA) -and $parent -ne [IO.Path]::GetFullPath($env:USERPROFILE)) -or -not [IO.Path]::GetFileName($tools).StartsWith('.gentle-shell-bootstrap-tools.',[StringComparison]::Ordinal)) { throw 'Cleanup target rejected' };" ^
+  "$item = Get-Item -LiteralPath $tools -Force;" ^
+  "if (-not $item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Cleanup target rejected' };" ^
+  "$marker = Get-Item -LiteralPath (Join-Path $tools '.bootstrap-owned') -Force;" ^
+  "if ($marker.PSIsContainer -or ($marker.Attributes -band [IO.FileAttributes]::ReparsePoint) -or (Get-Content -LiteralPath $marker.FullName -Raw) -ne 'gentle-pi prerequisite tooling only') { throw 'Cleanup marker rejected' };" ^
+  "[IO.Directory]::Delete($tools, $true);" ^
+  "} catch { $message = 'Bootstrap: installation finished, but temporary tools could not be removed: ' + $env:GENTLE_BOOTSTRAP_TOOLS;" ^
+  "if ([Console]::IsErrorRedirected) { $bytes = [Text.Encoding]::UTF8.GetBytes($message + [Environment]::NewLine); $stderr = [Console]::OpenStandardError(); $stderr.Write($bytes, 0, $bytes.Length); $stderr.Flush() } else { [Console]::Error.WriteLine($message) }; exit 1 } }"
+endlocal & exit /b 0
+
+:unavailable
+>&2 echo Bootstrap: stock Windows PowerShell is unavailable. No acquisition attempted.
+:failed
+rem Never scan/reuse/clean other attempts. Only our successfully claimed root.
+if not defined GENTLE_BOOTSTRAP_OWNED goto finishfailure
+"%GENTLE_BOOTSTRAP_PS%" -NoLogo -NoProfile -NonInteractive -Command ^
+  "& { try { $ErrorActionPreference = 'Stop';" ^
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { throw 'Managed policy constraint' };" ^
+  "$tools = $env:GENTLE_BOOTSTRAP_TOOLS; $item = Get-Item -LiteralPath $tools -Force;" ^
+  "if (-not $item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Cleanup target rejected' };" ^
+  "$marker = Get-Item -LiteralPath (Join-Path $tools '.bootstrap-owned') -Force;" ^
+  "if ($marker.PSIsContainer -or ($marker.Attributes -band [IO.FileAttributes]::ReparsePoint) -or (Get-Content -LiteralPath $marker.FullName -Raw) -ne 'gentle-pi prerequisite tooling only') { throw 'Cleanup marker rejected' };" ^
+  "Remove-Item -LiteralPath $tools -Recurse -Force;" ^
+  "} catch { [Console]::Error.WriteLine('Bootstrap: attempt-owned cleanup unavailable; no other storage touched.'); exit 1 } }"
+:finishfailure
+endlocal & exit /b 1

package/scripts/bootstrap.sh

@@ -0,0 +1,168 @@
+#!/bin/sh
+# Run from an extracted/checkout bundle, not from a remote pipe.
+# Only prerequisite tooling is acquired here; standard installation belongs to T4.
+set -eu
+umask 077
+fail() { printf '%s\n' "Bootstrap: $1" >&2; exit 1; }
+need() { command -v "$1" >/dev/null 2>&1 || fail "Required utility missing: $1"; }
+for utility in dirname awk; do need "$utility"; done
+bundle=$(CDPATH= cd -P "$(dirname "$0")/.." && pwd) || fail 'Cannot locate installation bundle'
+entry=$bundle/bin/gentle-shell-install.mjs
+[ -f "$entry" ] && [ ! -L "$entry" ] || fail 'Future wizard entry is missing; this bundle cannot start a live wizard'
+[ -f "$bundle/scripts/installer-downloads.mjs" ] || fail 'Download helper missing from bundle'
+for utility in uname mkdir mktemp chmod mv rm sleep wc id ls; do need "$utility"; done
+case ${HOME:-} in /*) ;; *) fail 'HOME must be an absolute per-user directory';; esac
+# Refuse symlink ancestors and group/world-writable acquisition parents.
+check_home=$HOME
+while [ "$check_home" != / ]; do
+    [ ! -L "$check_home" ] || fail 'Unsafe symlink in HOME path'
+    check_home=$(dirname "$check_home")
+done
+[ -d "$HOME" ] || fail 'HOME directory is missing'
+uid=$(id -u)
+ls -nd "$HOME" | awk -v uid="$uid" '$3 == uid && substr($1,6,1) != "w" && substr($1,9,1) != "w" {ok=1} END {exit !ok}' || fail 'Unsafe HOME ownership or permissions'
+minimum=$(awk -F '"' '{for (i=2; i<=NF-2; i+=2) if ($i == "node" && $(i+2) ~ /^>=[0-9]+\.[0-9]+\.[0-9]+$/) {value=$(i+2); sub(/^>=/, "", value); count++}} END {if (count == 1) print value}' "$bundle/package.json")
+[ -n "$minimum" ] || fail 'Cannot establish repository Node minimum'
+version_ok() {
+    awk -v value="$1" -v minimum="$2" 'BEGIN {
+        sub(/^v/, "", value)
+        if (value !~ /^[0-9]+\.[0-9]+\.[0-9]+$/) exit 1
+        split(value, a, "."); split(minimum, b, ".")
+        for (i=1; i<=3; i++) if (length(a[i]) > 9 || (length(a[i]) > 1 && substr(a[i],1,1) == "0")) exit 1
+        for (i=1; i<=3; i++) {
+            if (a[i]+0 > b[i]+0) exit 0
+            if (a[i]+0 < b[i]+0) exit 1
+        }
+    }'
+}
+# Any stable version at all: version_ok against 0.0.0 accepts exactly those.
+stable_version() { version_ok "$1" 0.0.0; }
+# A stock POSIX watchdog avoids assuming GNU timeout on macOS.
+# These fixed prerequisite probes get an unignorable deadline, not graceful TERM.
+# Signal only our direct child PID; do not kill inherited process groups.
+bounded() {
+    seconds=$1
+    shift
+    "$@" &
+    version_pid=$!
+    (
+        sleep "$seconds" &
+        sleeper=$!
+        trap 'kill -s KILL "$sleeper" 2>/dev/null || :; wait "$sleeper" 2>/dev/null || :; exit 0' TERM
+        wait "$sleeper" || :
+        kill -s KILL "$version_pid" 2>/dev/null || :
+    ) >/dev/null 2>&1 &
+    watchdog=$!
+    result=0
+    wait "$version_pid" || result=$?
+    kill "$watchdog" 2>/dev/null || :
+    wait "$watchdog" 2>/dev/null || :
+    return "$result"
+}
+tools=
+owned=0
+# Only the exact directory this attempt claimed; rm -rf never follows links in it.
+owned_tools() {
+    [ "$owned" = 1 ] && [ -n "$tools" ] || return 1
+    case "$tools" in "$HOME"/.gentle-shell-bootstrap-tools.*/*) return 1;; "$HOME"/.gentle-shell-bootstrap-tools.*) ;; *) return 1;; esac
+    [ -d "$tools" ] && [ ! -L "$tools" ] && [ -d "$tools/.claim" ] && [ ! -L "$tools/.claim" ]
+}
+cleanup() {
+    if owned_tools; then
+        rm -rf "$tools"
+    fi
+}
+trap cleanup EXIT
+trap 'exit 1' HUP INT TERM
+make_tools() {
+    tools=$(mktemp -d "$HOME/.gentle-shell-bootstrap-tools.XXXXXXXX") || fail 'Cannot create private tooling directory'
+    case "$tools" in "$HOME"/.gentle-shell-bootstrap-tools.*) ;; *) fail 'Conflicting tooling destination';; esac
+    [ -d "$tools" ] && [ ! -L "$tools" ] || fail 'Unsafe tooling destination'
+    ls -nd "$tools" | awk -v uid="$uid" '$3 == uid && $1 == "drwx------" {ok=1} END {exit !ok}' || fail 'Unsafe tooling ownership'
+    # No existing destination is ever reused or replaced.
+    mkdir "$tools/.claim" || fail 'Conflicting tooling destination'
+    owned=1
+    printf '%s\n' 'gentle-pi prerequisite tooling only' > "$tools/.bootstrap-owned" || fail 'Cannot mark tooling ownership'
+}
+acquire_node=1
+if command -v node >/dev/null 2>&1; then
+    node=$(command -v node)
+    version=$(bounded 10 "$node" --version 2>/dev/null) || fail 'Existing Node version probe failed'
+    if version_ok "$version" "$minimum"; then acquire_node=0
+    # An older stable Node is left as it is: the verified Node below runs the
+    # installer instead, exactly as when Node is absent.
+    elif ! stable_version "$version"; then fail 'Existing Node is incompatible or unknown; refusing replacement'; fi
+fi
+if [ "$acquire_node" = 1 ]; then
+    os=$(uname -s)
+    arch=$(uname -m)
+    case "$os" in Darwin) os=darwin;; Linux) os=linux;; *) fail 'Unsupported POSIX platform';; esac
+    case "$arch" in x86_64|amd64) arch=x64;; aarch64|arm64) arch=arm64;; *) fail 'Unsupported architecture';; esac
+    if [ "$os" = linux ]; then
+        need getconf
+        libc=$(getconf GNU_LIBC_VERSION 2>/dev/null) || fail 'Cannot establish native glibc compatibility; musl is not supported'
+        case "$libc" in 'glibc '*) ;; *) fail 'Unsupported libc; only native glibc acquisition is planned';; esac
+        version_ok "${libc#glibc }.0" '2.28.0' || fail 'Native Node requires glibc >=2.28; musl is not supported'
+    fi
+    # Primary source: https://nodejs.org/dist/latest-v24.x/SHASUMS256.txt
+    # Exact release URLs are fixed, even though the provenance page is moving.
+    case "$os-$arch" in
+        darwin-arm64) hash=bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057;;
+        darwin-x64) hash=1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097;;
+        linux-arm64) hash=724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5;;
+        linux-x64) hash=6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff;;
+    esac
+    need curl
+    need tar
+    if command -v sha256sum >/dev/null 2>&1; then hasher=sha256sum
+    elif command -v shasum >/dev/null 2>&1; then hasher=shasum
+    else fail 'Required SHA256 utility missing: sha256sum or shasum'; fi
+    make_tools
+    stem=node-v24.21.0-$os-$arch
+    archive=$tools/node.tar.gz
+    # Also bound disk use on older curl versions lacking streamed-size enforcement.
+    # POSIX uses 512-byte blocks; shells using KiB still impose a 200-MiB ceiling.
+    (
+        ulimit -f 204800 || exit 1
+        curl --fail --silent --show-error --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 120 --max-filesize 104857600 --output "$archive" "https://nodejs.org/dist/v24.21.0/$stem.tar.gz"
+    ) 2>/dev/null || fail 'Node download failed, was truncated, or its file-size bound is unavailable'
+    size=$(wc -c < "$archive")
+    [ "$size" -gt 0 ] && [ "$size" -le 104857600 ] || fail 'Node download size is invalid'
+    if [ "$hasher" = sha256sum ]; then actual=$(bounded 30 sha256sum "$archive" 2>/dev/null) || fail 'SHA256 process failed'
+    else actual=$(bounded 30 shasum -a 256 "$archive" 2>/dev/null) || fail 'SHA256 process failed'; fi
+    actual=${actual%% *}
+    # Hash tools prefix escaped filenames (e.g. newline/backslash) with a backslash.
+    actual=${actual#\\}
+    [ "$actual" = "$hash" ] || fail 'Node checksum integrity mismatch'
+    mkdir "$tools/staging" || fail 'Conflicting staging destination'
+    # Extract only the trusted regular executable, not npm/Corepack or archive links.
+    member=$stem/bin/node
+    listing=$(bounded 30 tar -tvzf "$archive" "$member" 2>/dev/null) || fail 'Node archive is invalid'
+    case "$listing" in -*) ;; *) fail 'Node archive executable is not a regular file';; esac
+    bounded 30 tar -xzf "$archive" -C "$tools/staging" "$member" 2>/dev/null || fail 'Node extraction failed'
+    candidate=$tools/staging/$member
+    [ -f "$candidate" ] && [ ! -L "$candidate" ] || fail 'Node executable missing or unsafe'
+    version=$(bounded 10 "$candidate" --version 2>/dev/null) || fail 'Acquired Node cannot execute on this native platform'
+    [ "$version" = v24.21.0 ] && version_ok "$version" "$minimum" || fail 'Acquired Node version rejected'
+    bounded 10 chmod 700 "$candidate" 2>/dev/null || fail 'Cannot secure acquired Node executable'
+    [ ! -e "$tools/node" ] && [ ! -L "$tools/node" ] || fail 'Conflicting Node destination'
+    mv "$tools/staging/$stem" "$tools/node" || fail 'Cannot publish verified Node'
+    rm -f "$archive" || fail 'Cannot clean owned Node archive'
+    rm -rf "$tools/staging" || fail 'Cannot clean owned Node staging'
+    node=$tools/node/bin/node
+    PATH=$tools/node/bin:$PATH
+    export PATH
+fi
+# The helper creates an equally private tooling directory only if pnpm is absent.
+# Do not exec: retain ownership cleanup on any helper/child failure.
+"$node" "$bundle/scripts/installer-downloads.mjs" --bootstrap "$bundle" "$tools" || fail 'Prerequisite acquisition or wizard child failed'
+# Exit 0 means node/npm/pnpm now persist under $PNPM_HOME or were already the
+# user's. A removal problem never turns the completed installation into failure.
+if [ "$owned" = 1 ]; then
+    mark=
+    if owned_tools && [ -f "$tools/.bootstrap-owned" ] && [ ! -L "$tools/.bootstrap-owned" ] &&
+        { IFS= read -r mark < "$tools/.bootstrap-owned"; } 2>/dev/null && [ "$mark" = 'gentle-pi prerequisite tooling only' ] &&
+        rm -rf "$tools" 2>/dev/null; then :
+    else printf '%s\n' "Bootstrap: installation finished, but temporary tools could not be removed: $tools" >&2; fi
+fi
+owned=0

package/scripts/build-distribution.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Release distribution assets (S3, T1b): gentle-pi at the release version and
+// the exact Pi (PI_INSTALL_VERSION), with the pnpm-lock.yaml our pinned pnpm
+// resolves for them, published as two release assets that installVersion
+// installs with --frozen-lockfile. pnpm records every platform's optional
+// packages (ffi-rs, fff-bin, esbuild prebuilds) in the lockfile whatever system
+// resolves it, so one lockfile serves Linux, macOS and Windows.
+//
+//   node scripts/build-distribution.mjs build --shell <version> [--pi <version>] --out <dir>
+//   node scripts/build-distribution.mjs verify --assets <dir>
+//
+// Both commands work in a fresh temporary prefix with our own pinned Node and
+// pnpm (and Go on Windows); the user's tools and home are never used.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { DISTRIBUTION_ASSETS, activateVersion, claimPrefix, distributionAsset, distributionFiles, ensureLauncher, ensureRuntime, installVersion,
+	pnpmEnvironment, readDistribution, runCommand } from "./bundled-install.mjs";
+import { PI_INSTALL_VERSION } from "./installer-preflight.mjs";
+
+const RESOLVE_TIMEOUT = 10 * 60 * 1000;
+// Right after `npm publish` the registry may not list gentle-pi@<version> yet:
+// 10 attempts 30 seconds apart wait about five minutes for it.
+const RESOLVE_ATTEMPTS = 10;
+const RESOLVE_DELAY = 30 * 1000;
+const output = (result) => `${result.stdout ?? ""}${result.stderr ?? ""}`.slice(-4000);
+
+/** Resolves the lockfile for gentle-pi `shell` and Pi `pi` with our pnpm
+ * (`install --lockfile-only`) in a fresh folder under the prefix, from the
+ * unmodified distributionFiles() output and the same environment installVersion
+ * uses. Only "no matching version" for this gentle-pi is retried (pnpm prints it
+ * on stdout); any other failure stops at once. Returns { manifest, assets }
+ * keyed by the release asset names.
+ */
+export async function buildDistribution({ layout, shell, pi = PI_INSTALL_VERSION, env = {}, adapters = {} }) {
+	const manifest = { shell, pi };
+	const files = distributionFiles(manifest);
+	const sleep = adapters.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	// `shell` is an exact SemVer here, so only its dots need escaping.
+	const unpublished = new RegExp(`ERR_PNPM_NO_(?:MATURE_)?MATCHING_VERSION\\] No matching version found for gentle-pi@${shell.replaceAll(".", "\\.")}(?![\\w.+-])`);
+	for (let attempt = 1; ; attempt += 1) {
+		const folder = mkdtempSync(join(layout.tmp, "lockfile-"));
+		try {
+			for (const [name, text] of Object.entries(files)) writeFileSync(join(folder, name), text, { flag: "wx", mode: 0o600 });
+			const result = await (adapters.run ?? runCommand)(layout.node, [layout.pnpm, "install", "--lockfile-only"],
+				{ cwd: folder, env: pnpmEnvironment(layout, { env }), timeout: RESOLVE_TIMEOUT });
+			if (result.status === 0) {
+				// Only the lockfile is read back: pnpm may rewrite pnpm-workspace.yaml with placeholders.
+				const lockfile = readFileSync(join(folder, "pnpm-lock.yaml"), "utf8");
+				return { manifest, assets: { [DISTRIBUTION_ASSETS.distribution]: distributionAsset(manifest, lockfile), [DISTRIBUTION_ASSETS.lockfile]: lockfile } };
+			}
+			if (!unpublished.test(output(result))) throw Object.assign(new Error("pnpm lockfile resolution failed"), { output: output(result) });
+			if (attempt === RESOLVE_ATTEMPTS) {
+				throw Object.assign(new Error(`gentle-pi@${shell} is not on the registry after ${RESOLVE_ATTEMPTS} attempts; check its npm publication`), { output: output(result) });
+			}
+		} finally {
+			rmSync(folder, { recursive: true, force: true });
+		}
+		await sleep(RESOLVE_DELAY);
+	}
+}
+
+/** Runs the launcher with `--version`; the .cmd one through cmd.exe. */
+function launch(launcher, { env, platform }) {
+	const options = { env, encoding: "utf8", timeout: 120000, windowsHide: true };
+	if (platform !== "win32") return spawnSync(launcher, ["--version"], options);
+	const cmd = join(env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows", "System32", "cmd.exe");
+	return spawnSync(cmd, ["/d", "/s", "/c", `""${launcher}" --version"`], { ...options, windowsVerbatimArguments: true });
+}
+
+/** Proves a release asset pair: our runtimes (Go too on Windows, as
+ * installVersion requires), a frozen install of the pair, `current` switched to
+ * it, the launcher written, and `gentle-shell --version` reporting exactly the
+ * pair's gentle-pi and Pi. Returns { id, version }.
+ */
+export async function verifyDistribution({ layout, distribution, lockfile, platform, arch, env = {}, adapters = {} }) {
+	const { manifest } = readDistribution(distribution, lockfile);
+	const runtime = await ensureRuntime({ layout, platform, arch, go: platform === "win32", env, adapters });
+	const { id } = await installVersion({ layout, manifest, lockfile, platform, env, go: runtime.go, adapters });
+	activateVersion(layout, id);
+	ensureLauncher(layout);
+	// The environment our pnpm ran in (no NODE_OPTIONS, NODE_PATH or npm/pnpm
+	// settings from the host), without any Pi or Gentle override that could point
+	// the launcher at another Pi or agent home.
+	const launchEnv = Object.fromEntries(Object.entries(pnpmEnvironment(layout, { platform, env })).filter(([key]) => !/^(?:gentle_|pi_)/i.test(key)));
+	const result = await (adapters.launch ?? launch)(layout.launcher, { env: launchEnv, platform });
+	const version = String(result.stdout ?? "").trim();
+	const [shellLine, piLine] = version.split(/\r?\n/);
+	if (result.status !== 0 || shellLine !== `gentle-shell ${manifest.shell}` || piLine !== `pi ${manifest.pi}`) {
+		throw Object.assign(new Error(`The launcher reported ${JSON.stringify(version)}, not gentle-shell ${manifest.shell} with pi ${manifest.pi}`),
+			{ output: output(result) });
+	}
+	return { id, version };
+}
+
+/** A fresh prefix in a new temporary folder. On Windows the private-folder claim
+ * (owner, ACL, marker) has its own native tests; here the new folder stands in
+ * for it, as in those tests.
+ */
+function temporaryPrefix(root, platform, base) {
+	if (platform !== "win32") {
+		const home = join(root, "home");
+		mkdirSync(home, { mode: 0o700 });
+		const env = { ...base, HOME: home };
+		return { env, layout: claimPrefix({ platform, env, home }) };
+	}
+	const [local, roaming, profile] = ["local", "roaming", "profile"].map((name) => join(root, name));
+	for (const folder of [local, roaming, profile]) mkdirSync(folder);
+	const kept = Object.entries(base).filter(([key]) => !/^(?:localappdata|appdata|userprofile|home)$/i.test(key));
+	const env = { ...Object.fromEntries(kept), LOCALAPPDATA: local, APPDATA: roaming, USERPROFILE: profile, HOME: profile };
+	const claim = (folder) => { mkdirSync(folder); return "claimed"; };
+	return { env, layout: claimPrefix({ platform, env, home: profile, adapters: { storage: () => {}, claim } }) };
+}
+
+/** The CLI. Its temporary prefix (`gsd-*`) is always removed, whether the
+ * command succeeded or failed; invalid input is refused before it exists.
+ */
+export async function main(argv, { platform = process.platform, arch = process.arch, env = process.env, temporaryRoot = tmpdir(), adapters = {} } = {}) {
+	const { positionals: [command], values } = parseArgs({ args: argv, allowPositionals: true,
+		options: { shell: { type: "string" }, pi: { type: "string" }, out: { type: "string" }, assets: { type: "string" } } });
+	const build = command === "build" && values.shell && values.out;
+	if (!build && !(command === "verify" && values.assets)) {
+		throw new Error("Usage: build-distribution.mjs build --shell <version> [--pi <version>] --out <dir> | verify --assets <dir>");
+	}
+	// A non-exact version is refused before anything is downloaded.
+	if (build) distributionFiles({ shell: values.shell, pi: values.pi ?? PI_INSTALL_VERSION });
+	const root = realpathSync(mkdtempSync(join(temporaryRoot, "gsd-")));
+	try {
+		const prefix = temporaryPrefix(root, platform, env);
+		if (build) {
+			await ensureRuntime({ layout: prefix.layout, platform, arch, env: prefix.env, adapters });
+			const { manifest, assets } = await buildDistribution({ layout: prefix.layout, shell: values.shell, pi: values.pi, env: prefix.env, adapters });
+			mkdirSync(values.out, { recursive: true });
+			for (const [name, text] of Object.entries(assets)) writeFileSync(join(values.out, name), text, { flag: "wx" });
+			console.log(`Built ${Object.keys(assets).join(" and ")} for gentle-pi ${manifest.shell} with pi ${manifest.pi} in ${values.out}`);
+		} else {
+			const read = (name) => readFileSync(join(values.assets, name), "utf8");
+			const result = await verifyDistribution({ layout: prefix.layout, distribution: read(DISTRIBUTION_ASSETS.distribution), lockfile: read(DISTRIBUTION_ASSETS.lockfile),
+				platform, arch, env: prefix.env, adapters });
+			console.log(`Verified ${result.id}:\n${result.version}`);
+		}
+	} finally {
+		// Windows may hold a file a moment after its process exits.
+		rmSync(root, { recursive: true, force: true, maxRetries: 5 });
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	main(process.argv.slice(2)).catch((error) => {
+		const detail = error.output ?? error.stderr;
+		console.error(detail ? `${error.message}\n${detail}` : error.message);
+		process.exitCode = 1;
+	});
+}