getculpa 1.0.9 → 1.1.0

package/assets/launch-culpa.ps1

@@ -1,415 +1,415 @@
-# Culpa launcher (Culpaflight #2, 2026-07-27). The Desktop/Start-Menu shortcut
-# runs THIS instead of a bare URL: a bare .url dead-ends at "connection
-# refused" whenever Docker Desktop isn't running. This launcher makes launch
-# mean launch: ensure Docker is up (starting it if installed, asking if not),
-# ensure the Culpa stack is up, then open the dashboard. Bounded waits, loud
-# failures - same posture as the installer.
-
-$ErrorActionPreference = "Stop"
-# IWR's progress rendering throws in hidden/redirected consoles (PS 5.1) and
-# slows every request - silence it globally
-$ProgressPreference = "SilentlyContinue"
-
-# CF5-F11: the shortcut runs this from the install directory, wherever the
-# founder put it; LOCALAPPDATA stays the fallback for the zip layout.
-$AppDir = if (Test-Path (Join-Path $PSScriptRoot "docker-compose.yml")) {
-    $PSScriptRoot
-} else {
-    Join-Path $env:LOCALAPPDATA "Culpa"
-}
-$ComposeDst = Join-Path $AppDir "docker-compose.yml"
-$DashboardUrl = "http://localhost:3000"
-# probe by literal IPv4 - "localhost" can resolve to ::1 where nothing listens
-$ProbeUrl = "http://127.0.0.1:3000"
-
-function Write-Step([string]$msg) { Write-Host "==> $msg" }
-
-function Fail([string]$msg) {
-    Write-Host ""
-    Write-Host "CULPA COULD NOT START: $msg" -ForegroundColor Red
-    Read-Host "Press Enter to close"
-    exit 1
-}
-
-function Test-DockerUp {
-    try { $null = docker info --format "ok" 2>&1; return $LASTEXITCODE -eq 0 } catch { return $false }
-}
-
-# --- QW-1..QW-4 (D-073 aftermath): the container-upgrade guards the v0.8.1
-# --- upgrade had to do by hand. Each is a plain function with injectable
-# --- inputs so scripts/cf8-qw-verify-launch-guards.ps1 can execute every
-# --- branch without Docker or a real install (the repo's AST-probe pattern).
-
-# The server tag pinned in a compose text; $null when absent (QW-1/2/3 all
-# read the pin through this ONE function so they can never disagree).
-# Full-line YAML comments, removed before ANY pin is parsed. Review finding
-# (2026-08-23): the unanchored parser below matched the cosign-verify EXAMPLE
-# at installers/culpa-compose.yml:29 - a COMMENT - which precedes the real
-# image: pin at line 58 and so won the first-match race. Both read v1.0.3
-# today, but publish.sh rewrites the example and the pin with SEPARATE seds,
-# so a server release whose example sed missed would leave QW-3 comparing a
-# stale version and REFUSING to launch a perfectly good pin.
-function Remove-ComposeComments([string]$ComposeText) {
-    if ([string]::IsNullOrEmpty($ComposeText)) { return "" }
-    return ((($ComposeText -split "`r?`n") | Where-Object { $_ -notmatch '^\s*#' }) -join "`n")
-}
-
-# Anchored on image: as well as comment-stripped - a pin is something docker
-# would actually pull, never prose that happens to name the image.
-function Get-PinnedServerVersion([string]$ComposeText) {
-    # Comment-stripping is what cures the defect; the image: anchor is preferred
-    # but NOT required, because callers legitimately pass a bare
-    # "culpa-server:vX.Y.Z" fragment. Anchored first, then an unanchored fallback
-    # over the SAME comment-stripped text.
-    $text = Remove-ComposeComments $ComposeText
-    if ($text -match '(?m)^[ 	]*image:\s*\S*?culpa-server:([^"''\s]+)') { return $Matches[1] }
-    if ($text -match 'culpa-server:([^"''\s]+)') { return $Matches[1] }
-    return $null
-}
-
-# vX.Y.Z comparison: -1 (A older), 0 (equal/unparsable), 1 (A newer).
-# Unparsable tags return 0 deliberately - the guards must fail OPEN on exotic
-# tags (a dev tag must not brick launch), and QW-4 still backs up on ANY
-# difference, so an unparsable tag still gets the backup.
-function Compare-CulpaVersions([string]$A, [string]$B) {
-    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
-    if ($A -notmatch $rx) { return 0 }
-    $pa = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
-    if ($B -notmatch $rx) { return 0 }
-    $pb = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
-    for ($i = 0; $i -lt 3; $i++) {
-        if ($pa[$i] -lt $pb[$i]) { return -1 }
-        if ($pa[$i] -gt $pb[$i]) { return 1 }
-    }
-    return 0
-}
-
-# ISS-V103-12 - every pinned CULPA image in a compose text, as a hashtable
-# @{ "culpa-server" = "v1.0.3"; "culpa-dashboard" = "v1.0.5" }. Scoped to
-# culpa-* deliberately: the compose also pins postgres, and a postgres bump
-# must never read as a Culpa release.
-function Get-PinnedImageVersions([string]$ComposeText) {
-    $out = @{}
-    if ($null -eq $ComposeText) { return $out }
-    foreach ($m in [regex]::Matches((Remove-ComposeComments $ComposeText), '(?m)^[ 	]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"''\s]+)')) {
-        $out[$m.Groups[1].Value] = $m.Groups[2].Value
-    }
-    return $out
-}
-
-# ISS-V103-12 - is the SHIPPED compose a release the LIVE one has not had?
-#
-# This used to be Compare-CulpaVersions on the culpa-server pin and nothing
-# else, so any per-component release (D-087) that did not bump culpa-server
-# never re-pinned: new npm files over old containers. Observed on v1.0.4.
-#
-# Rule: at least one pinned Culpa image is NEWER, and none is OLDER.
-#   - an image in shipped but not live counts as NEWER (a release that ADDS a
-#     service must reach the live file, or that service never starts);
-#   - an image in live but not shipped is ignored, not "older";
-#   - unparsable tags still compare 0, so exotic dev tags contribute neither
-#     direction and can never brick a launch.
-#
-# MUST stay behaviourally identical to isComposeUpgrade in
-# packaging/npm-getculpa/lib/preflight.mjs - tests/npm-ps1-repin-parity.test.ts
-# executes both against one shared table of cases.
-function Test-ComposeUpgrade([string]$ShippedText, [string]$LiveText) {
-    $shipped = Get-PinnedImageVersions $ShippedText
-    $live = Get-PinnedImageVersions $LiveText
-    if ($shipped.Count -eq 0 -or $live.Count -eq 0) { return $false }
-
-    $anyNewer = $false
-    foreach ($name in $shipped.Keys) {
-        if (-not $live.ContainsKey($name)) { $anyNewer = $true; continue }
-        $cmp = Compare-CulpaVersions $shipped[$name] $live[$name]
-        if ($cmp -eq -1) {
-            # not silent: an ambiguous file must not look like "nothing to do"
-            Write-Warning "The shipped compose moves $name BACKWARD ($($live[$name]) -> $($shipped[$name])) while moving others forward; refusing to re-pin from an ambiguous file."
-            return $false
-        }
-        if ($cmp -eq 1) { $anyNewer = $true }
-    }
-    return $anyNewer
-}
-
-# QW-1 - ONE canonical compose. The live file ($LivePath) owns the pin; the
-# shipped culpa-compose.yml beside the install ($ShippedPath) is only a
-# SOURCE: when an upgrade drops a NEWER shipped file, the live one is
-# re-pinned from it here, on launch - the step the v0.8.1 upgrade needed a
-# human for, three files at a time. An OLDER shipped file never wins.
-# Returns: "synced" | "kept" | "no-shipped" | "no-live".
-function Sync-CanonicalCompose([string]$ShippedPath, [string]$LivePath) {
-    if (-not (Test-Path $LivePath)) { return "no-live" }
-    if (-not (Test-Path $ShippedPath)) { return "no-shipped" }
-    if (Test-ComposeUpgrade (Get-Content $ShippedPath -Raw) (Get-Content $LivePath -Raw)) {
-        Copy-Item $ShippedPath $LivePath -Force
-        return "synced"
-    }
-    return "kept"
-}
-
-# QW-3 - refuse-and-explain on a backward pin. $true = refuse. A pinned
-# server OLDER than the version that last booted healthily means its known
-# migrations disagree with the database's history - culpa-migrate would die
-# with a cryptic error AFTER the recreate. Refuse BEFORE touching anything.
-#
-# CodeRabbit PR13 #6: Compare-CulpaVersions fails OPEN (0, "equal") on any
-# unparsable tag so exotic dev tags never brick launch - but that means a
-# MALFORMED pin against a well-formed, known baseline used to read as
-# "equal" and launch anyway. That pin cannot be proven newer, so it must
-# fail CLOSED instead: refuse (the CULPA_ALLOW_DOWNGRADE escape still
-# applies). Both-unparsable and no-baseline stay permissive (dev installs).
-function Test-BackwardPin([string]$PinnedVersion, [string]$LastBootVersion) {
-    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $false }
-    if ([string]::IsNullOrWhiteSpace($LastBootVersion)) { return $false }
-    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
-    if (($PinnedVersion -notmatch $rx) -and ($LastBootVersion -match $rx)) { return $true }
-    return ((Compare-CulpaVersions $PinnedVersion $LastBootVersion) -eq -1)
-}
-
-# QW-4 - automatic pg_dump before any launch that can migrate (pin differs
-# from the last healthy boot). Fails CLOSED: no verified dump, no launch -
-# unless the caller passed an explicit skip. $DumpExec/$CopyExec are
-# injectable for the probe script. Returns the dump path on success; throws
-# with a human-readable reason on failure.
-function Invoke-PreMigrationBackup {
-    param(
-        [string]$BackupDir,
-        [string]$Tag,
-        [scriptblock]$DumpExec = {
-            docker exec culpa-db sh -c "pg_dump -Fc -U culpa culpa > /tmp/culpa-pre-upgrade.dump" 2>&1 | Out-Null
-            return $LASTEXITCODE
-        },
-        [scriptblock]$CopyExec = {
-            param($Dest)
-            docker cp culpa-db:/tmp/culpa-pre-upgrade.dump $Dest 2>&1 | Out-Null
-            return $LASTEXITCODE
-        }
-    )
-    New-Item -ItemType Directory -Force -Path $BackupDir | Out-Null
-    $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
-    $dest = Join-Path $BackupDir "pre-$Tag-$stamp.dump"
-    if ((& $DumpExec) -ne 0) { throw "pg_dump inside culpa-db failed" }
-    if ((& $CopyExec $dest) -ne 0) { throw "copying the dump out of culpa-db failed" }
-    $item = Get-Item -Path $dest -ErrorAction SilentlyContinue
-    if ($null -eq $item -or $item.Length -lt 1024) {
-        throw "the dump at '$dest' is missing or implausibly small ($(if ($item) { $item.Length } else { 0 }) bytes)"
-    }
-    return $dest
-}
-
-# QW-4's baseline resolver (CF8 review Critical-2): the recorded last
-# healthy boot wins; when NO record exists yet (first run of this guard on
-# an existing install - exactly the rollout population) the baseline is
-# derived from the culpa-server container's ACTUAL running image tag; if
-# neither source yields a version the baseline is UNKNOWN ("").
-function Resolve-BackupBaseline(
-    [string]$Recorded,
-    [scriptblock]$InspectExec = {
-        $old = $ErrorActionPreference; $ErrorActionPreference = "Continue"
-        try { docker inspect culpa-server --format "{{.Config.Image}}" 2>&1 } finally { $ErrorActionPreference = $old }
-    }
-) {
-    if (-not [string]::IsNullOrWhiteSpace($Recorded)) { return $Recorded.Trim() }
-    $image = ""
-    try { $image = ("$(& $InspectExec)").Trim() } catch { $image = "" }
-    if ($image -match ':(v[0-9][^:\s]*)$') { return $Matches[1] }
-    return ""
-}
-
-# QW-4's decision, extracted so the probe can execute the WIRED condition
-# (the review proved the old inline gate was silently false at
-# baseline="" + data present - the exact first-activation state): data
-# present + an UNKNOWN baseline means BACK UP, never skip; only a baseline
-# that is known AND equal to the pin skips the backup.
-function Test-BackupNeeded([bool]$DbExists, [string]$PinnedVersion, [string]$Baseline) {
-    if (-not $DbExists) { return $false }
-    if ([string]::IsNullOrWhiteSpace($Baseline)) { return $true }
-    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $true }
-    return ($PinnedVersion -ne $Baseline)
-}
-
-# QW-2 - reconcile the Add/Remove Programs DisplayVersion from the pin that
-# is ACTUALLY about to run, so Settings can never report a stale version
-# again (it read v0.8.0 while v0.8.1 ran). No-op when the key is absent.
-function Sync-RegistryDisplayVersion([string]$PinnedVersion, [string]$ArpKey) {
-    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return "no-pin" }
-    if (-not (Test-Path $ArpKey)) { return "no-key" }
-    $current = (Get-ItemProperty -Path $ArpKey -Name "DisplayVersion" -ErrorAction SilentlyContinue).DisplayVersion
-    if ($current -eq $PinnedVersion) { return "unchanged" }
-    New-ItemProperty -Path $ArpKey -Name "DisplayVersion" -Value $PinnedVersion -PropertyType String -Force | Out-Null
-    return "updated"
-}
-
-# --- 1. Docker present? (CF6-9: scan, then authorize before any download) ---
-# Test-DockerInstalled takes an overridable -Probe so this exact detection can
-# be exercised with a fake "not found" result without touching a real install.
-function Test-DockerInstalled {
-    param([scriptblock]$Probe = { Get-Command docker -ErrorAction SilentlyContinue })
-    return ($null -ne (& $Probe))
-}
-
-# Real WPF dialog - not a console prompt. Names what's missing, what would be
-# downloaded, and from where; returns $false unless the user explicitly agrees.
-function Show-DockerAuthorizationModal {
-    Add-Type -AssemblyName PresentationFramework
-    $msg = "Culpa needs Docker Desktop and it was not found on this machine.`n`n" +
-        "If you authorize, Culpa will install it via winget (Windows Package Manager) " +
-        "using the official package 'Docker.DockerDesktop', or open the official " +
-        "download page at https://www.docker.com/products/docker-desktop/ if winget " +
-        "is unavailable.`n`nNothing is downloaded until you click Yes."
-    $btns = [System.Windows.MessageBoxButton]::YesNo
-    $icon = [System.Windows.MessageBoxImage]::Warning
-    $result = [System.Windows.MessageBox]::Show($msg, "Culpa - Docker Desktop required", $btns, $icon)
-    return ($result -eq [System.Windows.MessageBoxResult]::Yes)
-}
-
-# Only called after explicit authorization. Prefers winget (the user's own,
-# auditable package manager); falls back to opening the official vendor page.
-# Returns WHICH path it took (see install-culpa.ps1 for the full rationale):
-# "installed" | "page-opened" | "failed:<exit code>". A bare $false made the
-# caller claim a download page had been opened when winget was present and the
-# install simply failed - no page is opened on that path.
-function Install-DockerDesktop {
-    $winget = Get-Command winget -ErrorAction SilentlyContinue
-    if ($null -eq $winget) {
-        Start-Process "https://www.docker.com/products/docker-desktop/"
-        return "page-opened"
-    }
-    Write-Step "Installing Docker Desktop via winget (Docker.DockerDesktop)"
-    $wingetArgs = @("install", "--id", "Docker.DockerDesktop", "-e", "--accept-package-agreements", "--accept-source-agreements")
-    $p = Start-Process -FilePath "winget" -ArgumentList $wingetArgs -Wait -PassThru -NoNewWindow
-    if ($p.ExitCode -eq 0) { return "installed" }
-    return "failed:$($p.ExitCode)"
-}
-
-if (-not (Test-DockerInstalled)) {
-    if (-not (Show-DockerAuthorizationModal)) {
-        Fail "Docker Desktop download was not authorized. Nothing was changed."
-    }
-    $outcome = Install-DockerDesktop
-    if ($outcome -eq "page-opened") {
-        Fail "winget is not available, so Docker Desktop could not be installed automatically. The official download page has been opened - install it, start it once, then launch Culpa again."
-    }
-    if ($outcome -ne "installed") {
-        $code = $outcome -replace "^failed:", ""
-        Fail "winget could not install Docker Desktop (exit code $code). No download page was opened and nothing was changed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/, start it once, then launch Culpa again."
-    }
-    Fail "Docker Desktop was installed. Close this window and open Culpa again to finish starting the stack."
-}
-
-# --- 2. Docker running? Start it if not (the whole point of this launcher) ---
-if (-not (Test-DockerUp)) {
-    Write-Step "Docker Desktop is not running - starting it"
-    $desktop = Join-Path $env:ProgramFiles "Docker\Docker\Docker Desktop.exe"
-    if (Test-Path $desktop) {
-        Start-Process $desktop
-    } else {
-        Fail "Docker Desktop is installed but its executable was not found at '$desktop'. Start Docker Desktop yourself, then launch Culpa again."
-    }
-    # bounded wait: up to 120s for the engine
-    $up = $false
-    for ($i = 0; $i -lt 60; $i++) {
-        Start-Sleep -Seconds 2
-        if (Test-DockerUp) { $up = $true; break }
-    }
-    if (-not $up) { Fail "Docker Desktop did not come up within 2 minutes. Wait for the whale icon to settle, then launch Culpa again." }
-}
-
-# --- 3. Stack up (idempotent; also recovers a stopped stack) ---
-if (-not (Test-Path $ComposeDst)) { Fail "Culpa's compose file is missing at '$ComposeDst'. Re-run the installer." }
-
-# --- 3a. QW-1: one canonical compose - a newer shipped culpa-compose.yml
-# --- re-pins the live file here, never by hand across three copies
-$ShippedCompose = Join-Path $AppDir "culpa-compose.yml"
-$syncOutcome = Sync-CanonicalCompose -ShippedPath $ShippedCompose -LivePath $ComposeDst
-if ($syncOutcome -eq "synced") { Write-Step "Upgrade detected: live compose re-pinned from the shipped culpa-compose.yml" }
-
-# --- 3b. QW-3: refuse-and-explain when the pin goes BACKWARD vs the last
-# --- healthy boot (a stale pin against a migrated DB dies cryptically in
-# --- culpa-migrate - refuse before touching anything)
-$PinnedVersion = Get-PinnedServerVersion (Get-Content $ComposeDst -Raw)
-$LastBootFile = Join-Path $AppDir "last-boot-version.txt"
-$LastBootVersion = if (Test-Path $LastBootFile) { (Get-Content $LastBootFile -Raw).Trim() } else { "" }
-if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -eq "1")) {
-    Write-Host "WARNING: CULPA_ALLOW_DOWNGRADE=1 - launching an OLDER server ($PinnedVersion) against a database last used by $LastBootVersion." -ForegroundColor Yellow
-}
-if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -ne "1")) {
-    Fail @"
-The compose file pins culpa-server $PinnedVersion, but this machine last ran $LastBootVersion.
-Starting an OLDER server against a newer database would fail inside its migration step with a
-cryptic error. Nothing was started.
-
-Fix: re-run the current installer (which lays down the right compose), or restore the
-$LastBootVersion pin in '$ComposeDst'. To force this downgrade anyway (only after restoring a
-matching database backup), set CULPA_ALLOW_DOWNGRADE=1 and launch again.
-"@
-}
-
-# --- 3c. QW-4: automatic pg_dump before any launch that can migrate. Fails
-# --- closed: no verified backup, no launch (CULPA_SKIP_BACKUP=1 overrides,
-# --- loudly). Only runs when the DB container already exists - a first
-# --- install has nothing to back up.
-$oldEapQw = $ErrorActionPreference
-$ErrorActionPreference = "Continue"
-$containerNames = docker ps -a --format "{{.Names}}" 2>&1
-$dbExists = ($LASTEXITCODE -eq 0 -and "$containerNames" -match "culpa-db")
-$ErrorActionPreference = $oldEapQw
-$BackupBaseline = Resolve-BackupBaseline $LastBootVersion
-$BaselineLabel = if ([string]::IsNullOrWhiteSpace($BackupBaseline)) { "unknown" } else { $BackupBaseline }
-if (Test-BackupNeeded $dbExists $PinnedVersion $BackupBaseline) {
-    if ($env:CULPA_SKIP_BACKUP -eq "1") {
-        Write-Host "WARNING: CULPA_SKIP_BACKUP=1 - upgrading $BaselineLabel -> $PinnedVersion WITHOUT a database backup." -ForegroundColor Yellow
-    } else {
-        Write-Step "Version change ($BaselineLabel -> $PinnedVersion): backing up the database first"
-        & { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d db 2>&1 | ForEach-Object { "$_" } }
-        if ($LASTEXITCODE -ne 0) { Fail "Could not start the database container to take the pre-upgrade backup. Nothing else was started." }
-        $pgReady = $false
-        for ($i = 0; $i -lt 30; $i++) {
-            & { $ErrorActionPreference = "Continue"; $null = docker exec culpa-db pg_isready -U culpa 2>&1 }
-            if ($LASTEXITCODE -eq 0) { $pgReady = $true; break }
-            Start-Sleep -Seconds 2
-        }
-        if (-not $pgReady) { Fail "The database did not become ready within 60s, so the pre-upgrade backup could not be taken. Nothing was upgraded." }
-        try {
-            $dump = Invoke-PreMigrationBackup -BackupDir (Join-Path $AppDir "backups") -Tag $BaselineLabel
-            Write-Step "Backup verified: $dump"
-        } catch {
-            Fail "Pre-upgrade backup failed ($($_.Exception.Message)). Nothing was upgraded. Set CULPA_SKIP_BACKUP=1 to launch without a backup (not recommended)."
-        }
-    }
-}
-
-Write-Step "Starting Culpa"
-# compose writes PROGRESS to stderr; under EAP=Stop with redirected streams
-# (PS 5.1) that becomes a terminating NativeCommandError - stringify the
-# records and judge by the exit code, which is the real signal
-& { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d 2>&1 | ForEach-Object { "$_" } }
-if ($LASTEXITCODE -ne 0) { Fail "Docker could not start the Culpa services. The message above says why." }
-
-# --- 3b. Capture collector (CF18): idempotent restart with the stack ---
-# The collector is a host process (loopback-bound by design), so the compose
-# restart policy cannot revive it after a reboot; this launcher is what does.
-$CollectorCtl = Join-Path $PSScriptRoot "culpa-collector.ps1"
-if (Test-Path $CollectorCtl) { & $CollectorCtl -Start }
-
-# --- 4. Wait for the dashboard (bounded: 120s), then open it ---
-Write-Step "Waiting for the dashboard"
-$ready = $false
-for ($i = 0; $i -lt 60; $i++) {
-    try {
-        $resp = Invoke-WebRequest -Uri $ProbeUrl -UseBasicParsing -TimeoutSec 3
-        if ($resp.StatusCode -eq 200) { $ready = $true; break }
-    } catch { Start-Sleep -Seconds 2 }
-}
-if (-not $ready) { Fail "The services started but the dashboard did not answer within 2 minutes. Run 'docker logs culpa-dashboard' to see why." }
-
-# --- 5. Healthy boot: record it (QW-3's baseline) + reconcile the registry
-# --- version from the pin that actually runs (QW-2)
-if ($PinnedVersion) {
-    Set-Content -Path $LastBootFile -Value $PinnedVersion
-    $ArpKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1"
-    $null = Sync-RegistryDisplayVersion -PinnedVersion $PinnedVersion -ArpKey $ArpKey
-}
-
-Start-Process $DashboardUrl
+# Culpa launcher (Culpaflight #2, 2026-07-27). The Desktop/Start-Menu shortcut
+# runs THIS instead of a bare URL: a bare .url dead-ends at "connection
+# refused" whenever Docker Desktop isn't running. This launcher makes launch
+# mean launch: ensure Docker is up (starting it if installed, asking if not),
+# ensure the Culpa stack is up, then open the dashboard. Bounded waits, loud
+# failures - same posture as the installer.
+
+$ErrorActionPreference = "Stop"
+# IWR's progress rendering throws in hidden/redirected consoles (PS 5.1) and
+# slows every request - silence it globally
+$ProgressPreference = "SilentlyContinue"
+
+# CF5-F11: the shortcut runs this from the install directory, wherever the
+# founder put it; LOCALAPPDATA stays the fallback for the zip layout.
+$AppDir = if (Test-Path (Join-Path $PSScriptRoot "docker-compose.yml")) {
+    $PSScriptRoot
+} else {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+}
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+$DashboardUrl = "http://localhost:3000"
+# probe by literal IPv4 - "localhost" can resolve to ::1 where nothing listens
+$ProbeUrl = "http://127.0.0.1:3000"
+
+function Write-Step([string]$msg) { Write-Host "==> $msg" }
+
+function Fail([string]$msg) {
+    Write-Host ""
+    Write-Host "CULPA COULD NOT START: $msg" -ForegroundColor Red
+    Read-Host "Press Enter to close"
+    exit 1
+}
+
+function Test-DockerUp {
+    try { $null = docker info --format "ok" 2>&1; return $LASTEXITCODE -eq 0 } catch { return $false }
+}
+
+# --- QW-1..QW-4 (D-073 aftermath): the container-upgrade guards the v0.8.1
+# --- upgrade had to do by hand. Each is a plain function with injectable
+# --- inputs so scripts/cf8-qw-verify-launch-guards.ps1 can execute every
+# --- branch without Docker or a real install (the repo's AST-probe pattern).
+
+# The server tag pinned in a compose text; $null when absent (QW-1/2/3 all
+# read the pin through this ONE function so they can never disagree).
+# Full-line YAML comments, removed before ANY pin is parsed. Review finding
+# (2026-08-23): the unanchored parser below matched the cosign-verify EXAMPLE
+# at installers/culpa-compose.yml:29 - a COMMENT - which precedes the real
+# image: pin at line 58 and so won the first-match race. Both read v1.0.3
+# today, but publish.sh rewrites the example and the pin with SEPARATE seds,
+# so a server release whose example sed missed would leave QW-3 comparing a
+# stale version and REFUSING to launch a perfectly good pin.
+function Remove-ComposeComments([string]$ComposeText) {
+    if ([string]::IsNullOrEmpty($ComposeText)) { return "" }
+    return ((($ComposeText -split "`r?`n") | Where-Object { $_ -notmatch '^\s*#' }) -join "`n")
+}
+
+# Anchored on image: as well as comment-stripped - a pin is something docker
+# would actually pull, never prose that happens to name the image.
+function Get-PinnedServerVersion([string]$ComposeText) {
+    # Comment-stripping is what cures the defect; the image: anchor is preferred
+    # but NOT required, because callers legitimately pass a bare
+    # "culpa-server:vX.Y.Z" fragment. Anchored first, then an unanchored fallback
+    # over the SAME comment-stripped text.
+    $text = Remove-ComposeComments $ComposeText
+    if ($text -match '(?m)^[ 	]*image:\s*\S*?culpa-server:([^"''\s]+)') { return $Matches[1] }
+    if ($text -match 'culpa-server:([^"''\s]+)') { return $Matches[1] }
+    return $null
+}
+
+# vX.Y.Z comparison: -1 (A older), 0 (equal/unparsable), 1 (A newer).
+# Unparsable tags return 0 deliberately - the guards must fail OPEN on exotic
+# tags (a dev tag must not brick launch), and QW-4 still backs up on ANY
+# difference, so an unparsable tag still gets the backup.
+function Compare-CulpaVersions([string]$A, [string]$B) {
+    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
+    if ($A -notmatch $rx) { return 0 }
+    $pa = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
+    if ($B -notmatch $rx) { return 0 }
+    $pb = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3])
+    for ($i = 0; $i -lt 3; $i++) {
+        if ($pa[$i] -lt $pb[$i]) { return -1 }
+        if ($pa[$i] -gt $pb[$i]) { return 1 }
+    }
+    return 0
+}
+
+# ISS-V103-12 - every pinned CULPA image in a compose text, as a hashtable
+# @{ "culpa-server" = "v1.0.3"; "culpa-dashboard" = "v1.0.5" }. Scoped to
+# culpa-* deliberately: the compose also pins postgres, and a postgres bump
+# must never read as a Culpa release.
+function Get-PinnedImageVersions([string]$ComposeText) {
+    $out = @{}
+    if ($null -eq $ComposeText) { return $out }
+    foreach ($m in [regex]::Matches((Remove-ComposeComments $ComposeText), '(?m)^[ 	]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"''\s]+)')) {
+        $out[$m.Groups[1].Value] = $m.Groups[2].Value
+    }
+    return $out
+}
+
+# ISS-V103-12 - is the SHIPPED compose a release the LIVE one has not had?
+#
+# This used to be Compare-CulpaVersions on the culpa-server pin and nothing
+# else, so any per-component release (D-087) that did not bump culpa-server
+# never re-pinned: new npm files over old containers. Observed on v1.0.4.
+#
+# Rule: at least one pinned Culpa image is NEWER, and none is OLDER.
+#   - an image in shipped but not live counts as NEWER (a release that ADDS a
+#     service must reach the live file, or that service never starts);
+#   - an image in live but not shipped is ignored, not "older";
+#   - unparsable tags still compare 0, so exotic dev tags contribute neither
+#     direction and can never brick a launch.
+#
+# MUST stay behaviourally identical to isComposeUpgrade in
+# packaging/npm-getculpa/lib/preflight.mjs - tests/npm-ps1-repin-parity.test.ts
+# executes both against one shared table of cases.
+function Test-ComposeUpgrade([string]$ShippedText, [string]$LiveText) {
+    $shipped = Get-PinnedImageVersions $ShippedText
+    $live = Get-PinnedImageVersions $LiveText
+    if ($shipped.Count -eq 0 -or $live.Count -eq 0) { return $false }
+
+    $anyNewer = $false
+    foreach ($name in $shipped.Keys) {
+        if (-not $live.ContainsKey($name)) { $anyNewer = $true; continue }
+        $cmp = Compare-CulpaVersions $shipped[$name] $live[$name]
+        if ($cmp -eq -1) {
+            # not silent: an ambiguous file must not look like "nothing to do"
+            Write-Warning "The shipped compose moves $name BACKWARD ($($live[$name]) -> $($shipped[$name])) while moving others forward; refusing to re-pin from an ambiguous file."
+            return $false
+        }
+        if ($cmp -eq 1) { $anyNewer = $true }
+    }
+    return $anyNewer
+}
+
+# QW-1 - ONE canonical compose. The live file ($LivePath) owns the pin; the
+# shipped culpa-compose.yml beside the install ($ShippedPath) is only a
+# SOURCE: when an upgrade drops a NEWER shipped file, the live one is
+# re-pinned from it here, on launch - the step the v0.8.1 upgrade needed a
+# human for, three files at a time. An OLDER shipped file never wins.
+# Returns: "synced" | "kept" | "no-shipped" | "no-live".
+function Sync-CanonicalCompose([string]$ShippedPath, [string]$LivePath) {
+    if (-not (Test-Path $LivePath)) { return "no-live" }
+    if (-not (Test-Path $ShippedPath)) { return "no-shipped" }
+    if (Test-ComposeUpgrade (Get-Content $ShippedPath -Raw) (Get-Content $LivePath -Raw)) {
+        Copy-Item $ShippedPath $LivePath -Force
+        return "synced"
+    }
+    return "kept"
+}
+
+# QW-3 - refuse-and-explain on a backward pin. $true = refuse. A pinned
+# server OLDER than the version that last booted healthily means its known
+# migrations disagree with the database's history - culpa-migrate would die
+# with a cryptic error AFTER the recreate. Refuse BEFORE touching anything.
+#
+# CodeRabbit PR13 #6: Compare-CulpaVersions fails OPEN (0, "equal") on any
+# unparsable tag so exotic dev tags never brick launch - but that means a
+# MALFORMED pin against a well-formed, known baseline used to read as
+# "equal" and launch anyway. That pin cannot be proven newer, so it must
+# fail CLOSED instead: refuse (the CULPA_ALLOW_DOWNGRADE escape still
+# applies). Both-unparsable and no-baseline stay permissive (dev installs).
+function Test-BackwardPin([string]$PinnedVersion, [string]$LastBootVersion) {
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $false }
+    if ([string]::IsNullOrWhiteSpace($LastBootVersion)) { return $false }
+    $rx = '^v?(\d+)\.(\d+)\.(\d+)'
+    if (($PinnedVersion -notmatch $rx) -and ($LastBootVersion -match $rx)) { return $true }
+    return ((Compare-CulpaVersions $PinnedVersion $LastBootVersion) -eq -1)
+}
+
+# QW-4 - automatic pg_dump before any launch that can migrate (pin differs
+# from the last healthy boot). Fails CLOSED: no verified dump, no launch -
+# unless the caller passed an explicit skip. $DumpExec/$CopyExec are
+# injectable for the probe script. Returns the dump path on success; throws
+# with a human-readable reason on failure.
+function Invoke-PreMigrationBackup {
+    param(
+        [string]$BackupDir,
+        [string]$Tag,
+        [scriptblock]$DumpExec = {
+            docker exec culpa-db sh -c "pg_dump -Fc -U culpa culpa > /tmp/culpa-pre-upgrade.dump" 2>&1 | Out-Null
+            return $LASTEXITCODE
+        },
+        [scriptblock]$CopyExec = {
+            param($Dest)
+            docker cp culpa-db:/tmp/culpa-pre-upgrade.dump $Dest 2>&1 | Out-Null
+            return $LASTEXITCODE
+        }
+    )
+    New-Item -ItemType Directory -Force -Path $BackupDir | Out-Null
+    $stamp = Get-Date -Format "yyyyMMdd-HHmmss"
+    $dest = Join-Path $BackupDir "pre-$Tag-$stamp.dump"
+    if ((& $DumpExec) -ne 0) { throw "pg_dump inside culpa-db failed" }
+    if ((& $CopyExec $dest) -ne 0) { throw "copying the dump out of culpa-db failed" }
+    $item = Get-Item -Path $dest -ErrorAction SilentlyContinue
+    if ($null -eq $item -or $item.Length -lt 1024) {
+        throw "the dump at '$dest' is missing or implausibly small ($(if ($item) { $item.Length } else { 0 }) bytes)"
+    }
+    return $dest
+}
+
+# QW-4's baseline resolver (CF8 review Critical-2): the recorded last
+# healthy boot wins; when NO record exists yet (first run of this guard on
+# an existing install - exactly the rollout population) the baseline is
+# derived from the culpa-server container's ACTUAL running image tag; if
+# neither source yields a version the baseline is UNKNOWN ("").
+function Resolve-BackupBaseline(
+    [string]$Recorded,
+    [scriptblock]$InspectExec = {
+        $old = $ErrorActionPreference; $ErrorActionPreference = "Continue"
+        try { docker inspect culpa-server --format "{{.Config.Image}}" 2>&1 } finally { $ErrorActionPreference = $old }
+    }
+) {
+    if (-not [string]::IsNullOrWhiteSpace($Recorded)) { return $Recorded.Trim() }
+    $image = ""
+    try { $image = ("$(& $InspectExec)").Trim() } catch { $image = "" }
+    if ($image -match ':(v[0-9][^:\s]*)$') { return $Matches[1] }
+    return ""
+}
+
+# QW-4's decision, extracted so the probe can execute the WIRED condition
+# (the review proved the old inline gate was silently false at
+# baseline="" + data present - the exact first-activation state): data
+# present + an UNKNOWN baseline means BACK UP, never skip; only a baseline
+# that is known AND equal to the pin skips the backup.
+function Test-BackupNeeded([bool]$DbExists, [string]$PinnedVersion, [string]$Baseline) {
+    if (-not $DbExists) { return $false }
+    if ([string]::IsNullOrWhiteSpace($Baseline)) { return $true }
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return $true }
+    return ($PinnedVersion -ne $Baseline)
+}
+
+# QW-2 - reconcile the Add/Remove Programs DisplayVersion from the pin that
+# is ACTUALLY about to run, so Settings can never report a stale version
+# again (it read v0.8.0 while v0.8.1 ran). No-op when the key is absent.
+function Sync-RegistryDisplayVersion([string]$PinnedVersion, [string]$ArpKey) {
+    if ([string]::IsNullOrWhiteSpace($PinnedVersion)) { return "no-pin" }
+    if (-not (Test-Path $ArpKey)) { return "no-key" }
+    $current = (Get-ItemProperty -Path $ArpKey -Name "DisplayVersion" -ErrorAction SilentlyContinue).DisplayVersion
+    if ($current -eq $PinnedVersion) { return "unchanged" }
+    New-ItemProperty -Path $ArpKey -Name "DisplayVersion" -Value $PinnedVersion -PropertyType String -Force | Out-Null
+    return "updated"
+}
+
+# --- 1. Docker present? (CF6-9: scan, then authorize before any download) ---
+# Test-DockerInstalled takes an overridable -Probe so this exact detection can
+# be exercised with a fake "not found" result without touching a real install.
+function Test-DockerInstalled {
+    param([scriptblock]$Probe = { Get-Command docker -ErrorAction SilentlyContinue })
+    return ($null -ne (& $Probe))
+}
+
+# Real WPF dialog - not a console prompt. Names what's missing, what would be
+# downloaded, and from where; returns $false unless the user explicitly agrees.
+function Show-DockerAuthorizationModal {
+    Add-Type -AssemblyName PresentationFramework
+    $msg = "Culpa needs Docker Desktop and it was not found on this machine.`n`n" +
+        "If you authorize, Culpa will install it via winget (Windows Package Manager) " +
+        "using the official package 'Docker.DockerDesktop', or open the official " +
+        "download page at https://www.docker.com/products/docker-desktop/ if winget " +
+        "is unavailable.`n`nNothing is downloaded until you click Yes."
+    $btns = [System.Windows.MessageBoxButton]::YesNo
+    $icon = [System.Windows.MessageBoxImage]::Warning
+    $result = [System.Windows.MessageBox]::Show($msg, "Culpa - Docker Desktop required", $btns, $icon)
+    return ($result -eq [System.Windows.MessageBoxResult]::Yes)
+}
+
+# Only called after explicit authorization. Prefers winget (the user's own,
+# auditable package manager); falls back to opening the official vendor page.
+# Returns WHICH path it took (see install-culpa.ps1 for the full rationale):
+# "installed" | "page-opened" | "failed:<exit code>". A bare $false made the
+# caller claim a download page had been opened when winget was present and the
+# install simply failed - no page is opened on that path.
+function Install-DockerDesktop {
+    $winget = Get-Command winget -ErrorAction SilentlyContinue
+    if ($null -eq $winget) {
+        Start-Process "https://www.docker.com/products/docker-desktop/"
+        return "page-opened"
+    }
+    Write-Step "Installing Docker Desktop via winget (Docker.DockerDesktop)"
+    $wingetArgs = @("install", "--id", "Docker.DockerDesktop", "-e", "--accept-package-agreements", "--accept-source-agreements")
+    $p = Start-Process -FilePath "winget" -ArgumentList $wingetArgs -Wait -PassThru -NoNewWindow
+    if ($p.ExitCode -eq 0) { return "installed" }
+    return "failed:$($p.ExitCode)"
+}
+
+if (-not (Test-DockerInstalled)) {
+    if (-not (Show-DockerAuthorizationModal)) {
+        Fail "Docker Desktop download was not authorized. Nothing was changed."
+    }
+    $outcome = Install-DockerDesktop
+    if ($outcome -eq "page-opened") {
+        Fail "winget is not available, so Docker Desktop could not be installed automatically. The official download page has been opened - install it, start it once, then launch Culpa again."
+    }
+    if ($outcome -ne "installed") {
+        $code = $outcome -replace "^failed:", ""
+        Fail "winget could not install Docker Desktop (exit code $code). No download page was opened and nothing was changed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/, start it once, then launch Culpa again."
+    }
+    Fail "Docker Desktop was installed. Close this window and open Culpa again to finish starting the stack."
+}
+
+# --- 2. Docker running? Start it if not (the whole point of this launcher) ---
+if (-not (Test-DockerUp)) {
+    Write-Step "Docker Desktop is not running - starting it"
+    $desktop = Join-Path $env:ProgramFiles "Docker\Docker\Docker Desktop.exe"
+    if (Test-Path $desktop) {
+        Start-Process $desktop
+    } else {
+        Fail "Docker Desktop is installed but its executable was not found at '$desktop'. Start Docker Desktop yourself, then launch Culpa again."
+    }
+    # bounded wait: up to 120s for the engine
+    $up = $false
+    for ($i = 0; $i -lt 60; $i++) {
+        Start-Sleep -Seconds 2
+        if (Test-DockerUp) { $up = $true; break }
+    }
+    if (-not $up) { Fail "Docker Desktop did not come up within 2 minutes. Wait for the whale icon to settle, then launch Culpa again." }
+}
+
+# --- 3. Stack up (idempotent; also recovers a stopped stack) ---
+if (-not (Test-Path $ComposeDst)) { Fail "Culpa's compose file is missing at '$ComposeDst'. Re-run the installer." }
+
+# --- 3a. QW-1: one canonical compose - a newer shipped culpa-compose.yml
+# --- re-pins the live file here, never by hand across three copies
+$ShippedCompose = Join-Path $AppDir "culpa-compose.yml"
+$syncOutcome = Sync-CanonicalCompose -ShippedPath $ShippedCompose -LivePath $ComposeDst
+if ($syncOutcome -eq "synced") { Write-Step "Upgrade detected: live compose re-pinned from the shipped culpa-compose.yml" }
+
+# --- 3b. QW-3: refuse-and-explain when the pin goes BACKWARD vs the last
+# --- healthy boot (a stale pin against a migrated DB dies cryptically in
+# --- culpa-migrate - refuse before touching anything)
+$PinnedVersion = Get-PinnedServerVersion (Get-Content $ComposeDst -Raw)
+$LastBootFile = Join-Path $AppDir "last-boot-version.txt"
+$LastBootVersion = if (Test-Path $LastBootFile) { (Get-Content $LastBootFile -Raw).Trim() } else { "" }
+if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -eq "1")) {
+    Write-Host "WARNING: CULPA_ALLOW_DOWNGRADE=1 - launching an OLDER server ($PinnedVersion) against a database last used by $LastBootVersion." -ForegroundColor Yellow
+}
+if ((Test-BackwardPin $PinnedVersion $LastBootVersion) -and ($env:CULPA_ALLOW_DOWNGRADE -ne "1")) {
+    Fail @"
+The compose file pins culpa-server $PinnedVersion, but this machine last ran $LastBootVersion.
+Starting an OLDER server against a newer database would fail inside its migration step with a
+cryptic error. Nothing was started.
+
+Fix: re-run the current installer (which lays down the right compose), or restore the
+$LastBootVersion pin in '$ComposeDst'. To force this downgrade anyway (only after restoring a
+matching database backup), set CULPA_ALLOW_DOWNGRADE=1 and launch again.
+"@
+}
+
+# --- 3c. QW-4: automatic pg_dump before any launch that can migrate. Fails
+# --- closed: no verified backup, no launch (CULPA_SKIP_BACKUP=1 overrides,
+# --- loudly). Only runs when the DB container already exists - a first
+# --- install has nothing to back up.
+$oldEapQw = $ErrorActionPreference
+$ErrorActionPreference = "Continue"
+$containerNames = docker ps -a --format "{{.Names}}" 2>&1
+$dbExists = ($LASTEXITCODE -eq 0 -and "$containerNames" -match "culpa-db")
+$ErrorActionPreference = $oldEapQw
+$BackupBaseline = Resolve-BackupBaseline $LastBootVersion
+$BaselineLabel = if ([string]::IsNullOrWhiteSpace($BackupBaseline)) { "unknown" } else { $BackupBaseline }
+if (Test-BackupNeeded $dbExists $PinnedVersion $BackupBaseline) {
+    if ($env:CULPA_SKIP_BACKUP -eq "1") {
+        Write-Host "WARNING: CULPA_SKIP_BACKUP=1 - upgrading $BaselineLabel -> $PinnedVersion WITHOUT a database backup." -ForegroundColor Yellow
+    } else {
+        Write-Step "Version change ($BaselineLabel -> $PinnedVersion): backing up the database first"
+        & { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d db 2>&1 | ForEach-Object { "$_" } }
+        if ($LASTEXITCODE -ne 0) { Fail "Could not start the database container to take the pre-upgrade backup. Nothing else was started." }
+        $pgReady = $false
+        for ($i = 0; $i -lt 30; $i++) {
+            & { $ErrorActionPreference = "Continue"; $null = docker exec culpa-db pg_isready -U culpa 2>&1 }
+            if ($LASTEXITCODE -eq 0) { $pgReady = $true; break }
+            Start-Sleep -Seconds 2
+        }
+        if (-not $pgReady) { Fail "The database did not become ready within 60s, so the pre-upgrade backup could not be taken. Nothing was upgraded." }
+        try {
+            $dump = Invoke-PreMigrationBackup -BackupDir (Join-Path $AppDir "backups") -Tag $BaselineLabel
+            Write-Step "Backup verified: $dump"
+        } catch {
+            Fail "Pre-upgrade backup failed ($($_.Exception.Message)). Nothing was upgraded. Set CULPA_SKIP_BACKUP=1 to launch without a backup (not recommended)."
+        }
+    }
+}
+
+Write-Step "Starting Culpa"
+# compose writes PROGRESS to stderr; under EAP=Stop with redirected streams
+# (PS 5.1) that becomes a terminating NativeCommandError - stringify the
+# records and judge by the exit code, which is the real signal
+& { $ErrorActionPreference = "Continue"; docker compose -f $ComposeDst -p culpa up -d 2>&1 | ForEach-Object { "$_" } }
+if ($LASTEXITCODE -ne 0) { Fail "Docker could not start the Culpa services. The message above says why." }
+
+# --- 3b. Capture collector (CF18): idempotent restart with the stack ---
+# The collector is a host process (loopback-bound by design), so the compose
+# restart policy cannot revive it after a reboot; this launcher is what does.
+$CollectorCtl = Join-Path $PSScriptRoot "culpa-collector.ps1"
+if (Test-Path $CollectorCtl) { & $CollectorCtl -Start }
+
+# --- 4. Wait for the dashboard (bounded: 120s), then open it ---
+Write-Step "Waiting for the dashboard"
+$ready = $false
+for ($i = 0; $i -lt 60; $i++) {
+    try {
+        $resp = Invoke-WebRequest -Uri $ProbeUrl -UseBasicParsing -TimeoutSec 3
+        if ($resp.StatusCode -eq 200) { $ready = $true; break }
+    } catch { Start-Sleep -Seconds 2 }
+}
+if (-not $ready) { Fail "The services started but the dashboard did not answer within 2 minutes. Run 'docker logs culpa-dashboard' to see why." }
+
+# --- 5. Healthy boot: record it (QW-3's baseline) + reconcile the registry
+# --- version from the pin that actually runs (QW-2)
+if ($PinnedVersion) {
+    Set-Content -Path $LastBootFile -Value $PinnedVersion
+    $ArpKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1"
+    $null = Sync-RegistryDisplayVersion -PinnedVersion $PinnedVersion -ArpKey $ArpKey
+}
+
+Start-Process $DashboardUrl