getculpa 0.0.1 → 1.0.2

package/assets/install-culpa.ps1

@@ -0,0 +1,310 @@
+# Culpa installer for Windows (T-087).
+# CR: Compose on Windows is brittle with backslashed bind sources - hand it a
+# forward-slashed home explicitly
+#
+# CF20-T3: -DeferStart / -NonInteractive let `getculpa` (npm) delegate to
+# this EXACT script for shortcuts + HKCU registration, without ever showing
+# a dialog, starting anything, or overwriting an existing live
+# docker-compose.yml (the live file owns the pin - QW-1; see section 3).
+# The Inno [Run] line passes neither switch, so the interactive installer's
+# own behavior is unchanged (culpa-setup.iss:60).
+param(
+    [switch]$DeferStart,
+    [switch]$NonInteractive
+)
+
+$env:CULPA_HOST_HOME = $env:USERPROFILE -replace "\\", "/"
+
+# Net effect = the CLI install: docker compose up on the release stack.
+# Non-technical flow: checks Docker Desktop, starts the stack, adds
+# shortcuts, opens the dashboard. Bounded waits everywhere; loud failures.
+
+$ErrorActionPreference = "Stop"
+
+$AppName = "Culpa"
+# CF5-F11: install where the founder chose. When this script was INSTALLED
+# (setup.exe drops it into {app} beside the compose and the uninstaller), the
+# install directory is simply where it lives. The LOCALAPPDATA default is kept
+# for the zip layout, where the script runs from a scratch folder.
+$InstalledHere = (Test-Path (Join-Path $PSScriptRoot "culpa-compose.yml")) -or
+                 (Test-Path (Join-Path $PSScriptRoot "unins000.exe"))
+$AppDir = if ($InstalledHere) { $PSScriptRoot } else { Join-Path $env:LOCALAPPDATA $AppName }
+# zip layout keeps the compose one level up; the setup.exe installs it beside us
+$ComposeSrc = Join-Path $PSScriptRoot "..\culpa-compose.yml"
+if (-not (Test-Path $ComposeSrc)) { $ComposeSrc = Join-Path $PSScriptRoot "culpa-compose.yml" }
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+$DashboardUrl = "http://localhost:3000"
+
+function Write-Step([string]$msg) { Write-Host "==> $msg" }
+
+function Fail([string]$msg) {
+    Write-Host ""
+    Write-Host "INSTALL STOPPED: $msg" -ForegroundColor Red
+    Write-Host "Nothing was broken. Fix the item above and run the installer again."
+    # -NonInteractive (CF20-T3): never block an automated caller on a keypress.
+    if (-not $NonInteractive) { Read-Host "Press Enter to close" }
+    exit 1
+}
+
+Write-Host ""
+Write-Host "  CULPA --- local install" -ForegroundColor Cyan
+Write-Host "  Your prompts and responses never leave this machine."
+Write-Host ""
+
+# --- 1. Docker Desktop 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, not just pass/fail. Review finding: the caller used
+# to print "the official download page has been opened" for every failure, but
+# the page is only opened when winget is ABSENT. With winget present and the
+# install failing (UAC declined, no network, a transient winget error) the user
+# was sent to look for a browser tab that was never opened — during exactly the
+# moment this flow exists to make trustworthy.
+#   "installed"   - winget reported success
+#   "page-opened" - no winget; the vendor page was opened instead
+#   "failed:<n>"  - winget ran and exited <n>; nothing else was opened
+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)"
+}
+
+Write-Step "Checking Docker Desktop"
+if (-not (Test-DockerInstalled)) {
+    if ($NonInteractive -and $DeferStart) {
+        # CF20-T3: no dialog, no winget without a TTY consent - refuse and
+        # instruct instead, then let the rest of provisioning proceed. Only
+        # safe with -DeferStart: provisioning never reaches the engine check
+        # below. Without -DeferStart, "continue" would walk straight into
+        # Test-DockerEngine with no `docker` binary on PATH - fail here
+        # instead (CF20-R review).
+        Write-Host "Docker Desktop was not found. Culpa is installed but needs Docker Desktop to run." -ForegroundColor Yellow
+        Write-Host "Install it from https://www.docker.com/products/docker-desktop/, then run 'getculpa' (or this installer) again."
+    } elseif ($NonInteractive) {
+        Fail "Docker Desktop was not found. Install it from https://www.docker.com/products/docker-desktop/, then run this installer again."
+    } else {
+        if (-not (Show-DockerAuthorizationModal)) {
+            Fail "Docker Desktop download was not authorized. Nothing was changed. Install Docker Desktop yourself, then run this installer again."
+        }
+        $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 run this installer 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 run this installer again."
+        }
+        Fail "Docker Desktop was installed. Close this window, open a NEW PowerShell window (so PATH picks it up), then run this installer again to finish setup."
+    }
+}
+
+# --- 2. Docker engine running? (start it if not, wait up to 3 minutes) ---
+function Test-DockerEngine {
+    # docker prints warnings to stderr even when healthy; merge streams so
+    # strict error mode never mistakes a warning for a dead engine.
+    $old = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    try {
+        $null = docker info --format "ok" 2>&1
+        return ($LASTEXITCODE -eq 0)
+    } finally {
+        $ErrorActionPreference = $old
+    }
+}
+
+# -DeferStart (CF20-T3): provisioning-only, never starts the engine - that
+# is getculpa's / launch-culpa.ps1's job at actual start time.
+if (-not $DeferStart) {
+    $engineUp = Test-DockerEngine
+    if (-not $engineUp) {
+        Write-Step "Starting Docker Desktop (this can take a minute)"
+        $desktop = Join-Path $env:ProgramFiles "Docker\Docker\Docker Desktop.exe"
+        if (Test-Path $desktop) { Start-Process $desktop } else { Fail "Docker Desktop is installed but could not be started automatically. Start it yourself, then run this installer again." }
+        for ($i = 0; $i -lt 36; $i++) {
+            Start-Sleep -Seconds 5
+            if (Test-DockerEngine) { $engineUp = $true; break }
+        }
+        if (-not $engineUp) { Fail "Docker Desktop did not become ready within 3 minutes. Wait for its whale icon to settle, then run this installer again." }
+    }
+}
+
+# --- 3. Install files (always - -DeferStart still performs dir/compose) ---
+Write-Step "Installing to $AppDir"
+New-Item -ItemType Directory -Force -Path $AppDir | Out-Null
+# CF20-T3 review (Critical): under -DeferStart an EXISTING live compose is
+# never overwritten. The live file owns the pin (QW-1); version deltas are
+# reconciled by launch-culpa.ps1 at next start, where QW-3 can refuse a
+# downgrade and QW-4 takes a backup first. A blind copy here would silently
+# re-pin (or downgrade) a customer's stack on every npm reinstall/update with
+# no refusal, no backup, and no trace. The interactive installer path (no
+# -DeferStart) keeps its historical refresh behavior unchanged.
+if ($DeferStart -and (Test-Path $ComposeDst)) {
+    Write-Step "Existing live docker-compose.yml preserved (version reconciliation happens at next launch)"
+} else {
+    Copy-Item $ComposeSrc $ComposeDst -Force
+}
+
+# --- 4/5. Start the stack + wait for the dashboard (skipped under -DeferStart) ---
+if (-not $DeferStart) {
+    Write-Step "Starting Culpa (docker compose up -d)"
+    # Culpa's images are PRIVATE during the testing phase, so an unauthenticated
+    # machine dies at the pull with a bare "denied" that means nothing to a
+    # founder. Capture the output and name that case explicitly.
+    # EAP note (Culpaflight #2 lesson): native stderr under Stop kills compose
+    # progress - drop to Continue for the call and judge the exit code instead.
+    $composeOutput = ""
+    $oldEap = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    try {
+        $composeOutput = (docker compose -f $ComposeDst -p culpa up -d 2>&1 | Out-String)
+    } finally {
+        $ErrorActionPreference = $oldEap
+    }
+    Write-Host $composeOutput
+    if ($LASTEXITCODE -ne 0) {
+        if ($composeOutput -match "denied|unauthorized|403|authentication required") {
+            Fail @"
+Culpa's images are private while it is in testing, and this machine is not signed in to the registry.
+
+One-time fix:
+  1. Create a GitHub token with ONLY the 'read:packages' scope:
+     https://github.com/settings/tokens/new?scopes=read:packages
+  2. Sign in (paste the token when it asks for a password):
+     docker login ghcr.io -u YOUR_GITHUB_USERNAME
+  3. Run this installer again.
+
+Nothing was changed on this machine.
+"@
+        }
+        Fail "Docker could not start the Culpa services. The message above says why (most often: no internet to pull images, or ports 3000/4545 already in use)."
+    }
+
+    Write-Step "Waiting for the dashboard to come up"
+    $ready = $false
+    for ($i = 0; $i -lt 24; $i++) {
+        Start-Sleep -Seconds 5
+        try {
+            $resp = Invoke-WebRequest -Uri $DashboardUrl -UseBasicParsing -TimeoutSec 5
+            if ($resp.StatusCode -eq 200) { $ready = $true; break }
+        } catch {}
+    }
+    if (-not $ready) { Fail "The services started but the dashboard did not answer within 2 minutes. Run 'docker logs culpa-server' and 'docker logs culpa-dashboard' to see why." }
+}
+
+# --- 6. Shortcuts (Desktop + Start Menu) ---
+# Culpaflight #2: shortcuts run the LAUNCHER, not a bare URL — a .url dead-ends
+# at "connection refused" whenever Docker Desktop is off; the launcher starts
+# Docker (bounded wait), brings the stack up, THEN opens the dashboard.
+Write-Step "Creating shortcuts"
+# setup.exe already installed the scripts into $AppDir — copying a file onto
+# itself is an error under Stop, so only copy from the zip layout
+if ($PSScriptRoot -ne $AppDir) { Copy-Item (Join-Path $PSScriptRoot "launch-culpa.ps1") (Join-Path $AppDir "launch-culpa.ps1") -Force }
+$launcher = Join-Path $AppDir "launch-culpa.ps1"
+$shell = New-Object -ComObject WScript.Shell
+foreach ($dir in @([Environment]::GetFolderPath("Desktop"), (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa"))) {
+    New-Item -ItemType Directory -Force -Path $dir | Out-Null
+    $lnk = $shell.CreateShortcut((Join-Path $dir "Culpa.lnk"))
+    $lnk.TargetPath = "powershell.exe"
+    $lnk.Arguments = "-NoProfile -ExecutionPolicy Bypass -File `"$launcher`""
+    $lnk.WorkingDirectory = $AppDir
+    $lnk.Description = "Culpa - LLM spend forensics (starts Docker if needed)"
+    $lnk.Save()
+    # the old bare-URL shortcut from earlier installs is superseded
+    Remove-Item -Path (Join-Path $dir "Culpa Dashboard.url") -ErrorAction SilentlyContinue
+}
+if ($PSScriptRoot -ne $AppDir) { Copy-Item (Join-Path $PSScriptRoot "uninstall-culpa.ps1") (Join-Path $AppDir "uninstall-culpa.ps1") -Force }
+
+# --- 7. Register in Add/Remove Programs (T-171) ---
+# This path wrote NO registry key at all, so a machine installed by the script
+# (or by the documented CLI/compose route) never appeared in Windows Settings
+# -> Installed apps - even though installers/README.md names that as THE
+# uninstall route. setup.exe installs are already listed, because Inno writes
+# its own key; a second key would show two Culpas whose uninstallers each
+# delete the other's files. The wizard's own uninstaller is the signal to skip.
+$UninsExe = Join-Path $AppDir "unins000.exe"
+if (Test-Path $UninsExe) {
+    Write-Step "Add/Remove Programs entry belongs to the installer - not adding a second"
+} else {
+    Write-Step "Registering in Add/Remove Programs"
+    # the SAME key name Inno uses ({AppId}_is1), so the two paths can never
+    # both be listed: a later exe install overwrites this entry instead of
+    # racing it, and its uninstaller then removes the only one there is
+    $ArpKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1"
+    # the version is the PINNED image tag in the compose just installed - the
+    # release this machine actually runs. A literal here would drift at every
+    # release and then report the wrong version forever, silently.
+    $installedVersion = "unknown"
+    $composeText = Get-Content $ComposeDst -Raw
+    if ($composeText -match 'culpa-server:([^"\s]+)') { $installedVersion = $Matches[1] }
+    $uninstaller = Join-Path $AppDir "uninstall-culpa.ps1"
+    $psRun = "powershell.exe -NoProfile -ExecutionPolicy Bypass -File `"$uninstaller`""
+    New-Item -Path $ArpKey -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "DisplayName" -Value "Culpa - LLM spend forensics" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "DisplayVersion" -Value $installedVersion -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "Publisher" -Value "Myaigi" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "InstallLocation" -Value $AppDir -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "UninstallString" -Value $psRun -PropertyType String -Force | Out-Null
+    # what Settings runs for its unattended path. -FromUninstaller is the
+    # branch that ALWAYS keeps the data volume, so a click in Settings can
+    # never silently destroy recorded spend.
+    New-ItemProperty -Path $ArpKey -Name "QuietUninstallString" -Value "$psRun -FromUninstaller" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "NoModify" -Value 1 -PropertyType DWord -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "NoRepair" -Value 1 -PropertyType DWord -Force | Out-Null
+}
+
+# --- 7b. Start the capture collector (CF18, D-088 items 4/5; skipped under -DeferStart) ---
+# The capture plane wires itself: no hand-assembly. Never fails the install —
+# the helper degrades to "capture OFF, everything else works" loudly.
+if (-not $DeferStart) {
+    $CollectorCtl = Join-Path $PSScriptRoot "culpa-collector.ps1"
+    if (Test-Path $CollectorCtl) {
+        Write-Step "Starting the capture collector"
+        & $CollectorCtl -Start
+    } else {
+        Write-Step "Capture collector not in this package - skipping (zip layout pre-CF18)"
+    }
+}
+
+# --- 8. Open it (skipped under -DeferStart: provisioning leaves Culpa dormant) ---
+if ($DeferStart) {
+    Write-Step "Done. Culpa is installed but not started (deferred)."
+    Write-Host ""
+    Write-Host "Culpa is installed. Run 'getculpa' (or launch-culpa.ps1 in $AppDir) to start it." -ForegroundColor Green
+} else {
+    Write-Step "Done. Opening the dashboard."
+    Start-Process $DashboardUrl
+    Write-Host ""
+    Write-Host "Culpa is running. It starts again automatically when Docker Desktop starts." -ForegroundColor Green
+}
+Write-Host "To remove it later: run uninstall-culpa.ps1 in $AppDir"
+if (-not $NonInteractive) { Read-Host "Press Enter to close" }

package/assets/launch-culpa.ps1

@@ -0,0 +1,350 @@
+# 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).
+function Get-PinnedServerVersion([string]$ComposeText) {
+    if ($ComposeText -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
+}
+
+# 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" }
+    $shipped = Get-PinnedServerVersion (Get-Content $ShippedPath -Raw)
+    $live = Get-PinnedServerVersion (Get-Content $LivePath -Raw)
+    if ($null -eq $shipped -or $null -eq $live) { return "kept" }
+    if ((Compare-CulpaVersions $shipped $live) -eq 1) {
+        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