getculpa 1.0.7 → 1.0.9

package/assets/culpa-compose.yml

@@ -5,7 +5,7 @@
 # name is used when present, which is how these pins were verified before
 # publication.
 #
-# ── RELEASE STATE: v1.0.7 PUBLISHED AND SIGNED (2026-08-29) ─────────
+# ── RELEASE STATE: v1.0.9 PUBLISHED AND SIGNED (2026-09-03) ─────────
 # The line above is REWRITTEN BY installers/publish.sh at real-publish time —
 # this file has shipped a hand-edited, wrong publication claim twice, so the
 # claim is now mechanical, never prose. While it reads NOT PUBLISHED, the pins
@@ -26,7 +26,7 @@
 #   cosign verify \
 #     --certificate-identity 'info@myaigi.ai' \
 #     --certificate-oidc-issuer 'https://github.com/login/oauth' \
-#     ghcr.io/myaigidev/culpa-server:v1.0.6
+#     ghcr.io/myaigidev/culpa-server:v1.0.9
 # Repeat for culpa-dashboard. Both must report VERIFIED.
 #
 # If a pull fails with an authentication or "denied" error rather than a
@@ -55,7 +55,7 @@ services:
     restart: unless-stopped
 
   server:
-    image: ghcr.io/myaigidev/culpa-server:v1.0.7
+    image: ghcr.io/myaigidev/culpa-server:v1.0.9
     container_name: culpa-server
     environment:
       DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
@@ -129,7 +129,7 @@ services:
     # (D-072: never rebuild a tag that already exists). The example this note
     # used to give was CF14's v0.11.0/v0.11.1 pair, which no longer matches
     # either pin in this file.
-    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.7
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.9
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

package/assets/uninstall-culpa.ps1

@@ -1,227 +1,251 @@
-# Culpa uninstaller for Windows (T-087, T-IX-01).
-# Stops and removes the containers and shortcuts. Your recorded data is
-# KEPT unless you answer Y to the final question.
-# -FromUninstaller: run by the setup.exe's uninstaller - no interactive
-# prompts, data always kept (never delete data without an explicit yes).
-#
-# CR-PR5 round 2 (SAFETY ORDERING): the canonical-path check now gates EVERY
-# destructive action - docker down, the data-volume prompt, and file removal.
-# A copy of this script run from anywhere else previously could stop the real
-# `culpa` project and offer to delete culpa_pgdata, the shared data volume.
-# T-CF29-2 params:
-#   -Force                      proceed from THIS directory even when the
-#                               canonical check disagrees (explicit opt-in;
-#                               never automatic)
-#   -RecordedInstallLocation    inject what the registry would return, so the
-#                               resolution can be tested without touching HKCU
-#                               (same -Probe precedent as install-culpa.ps1)
-#   -CanonicalOverrideForTest   inject the fallback directory, for the same reason
-#   -PrintPlanOnly              resolve, print the decision as JSON, exit 0
-#                               BEFORE any destructive action
-param(
-    [switch]$FromUninstaller,
-    [switch]$Force,
-    [string]$RecordedInstallLocation,
-    [string]$CanonicalOverrideForTest,
-    [switch]$PrintPlanOnly
-)
-
-$ErrorActionPreference = "SilentlyContinue"
-$AppDir = $PSScriptRoot
-# CF5-F11: the install directory is the founder's choice now, so "canonical"
-# is what SETUP RECORDED, not a hardcoded path. Inno writes InstallLocation
-# into its own uninstall key; fall back to %LOCALAPPDATA%\Culpa for installs
-# made before the directory page existed, and for the zip layout.
-# The guard itself is unchanged and still load-bearing: a stray COPY of this
-# script must never stop containers or delete files belonging to the real
-# install.
-#
-# T-CF29-2: a recorded value that POINTS AT A DELETED DIRECTORY used to be
-# trusted anyway, so the guard below could never match and Culpa became
-# impossible to uninstall. That is not hypothetical — the CF20 npm gate
-# overwrote this shared value with a scratch dir which was then removed.
-# A path that does not exist cannot be shadowing a real install, so it is
-# ignored in favour of the default. Everything else about the guard stands.
-# T-CF29-2: the guard compared raw strings, so two spellings of the SAME
-# directory read as different installs — an 8.3 short path (C:\Users\ZOLANI~1)
-# versus its long form, a trailing backslash, or different casing. Each of
-# those turns the uninstaller into the same dead end a stale registry value
-# does. Resolve-Path returns the canonical long form for a path that exists;
-# a path that does not exist falls back to a trimmed, lowercased comparison.
-function Normalize-Dir {
-    param([string]$Path)
-    if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
-    $trimmed = $Path.TrimEnd('\', '/')
-    # GetFullPath expands an 8.3 short component (ZOLANI~1) to its long form;
-    # Resolve-Path does NOT (verified on this machine), so it cannot be relied
-    # on for that. Both are best-effort: a path that cannot be expanded falls
-    # through to the trimmed, lowercased comparison.
-    try { $trimmed = [System.IO.Path]::GetFullPath($trimmed).TrimEnd('\', '/') } catch { }
-    return $trimmed.ToLowerInvariant()
-}
-
-function Resolve-CanonicalDir {
-    param(
-        [string]$Recorded,
-        [string]$Default,
-        [scriptblock]$PathExists = { param($p) Test-Path -LiteralPath $p }
-    )
-    if ([string]::IsNullOrWhiteSpace($Recorded)) {
-        return [PSCustomObject]@{ Dir = $Default; Source = "default" }
-    }
-    $trimmed = $Recorded.TrimEnd('\')
-    if (-not (& $PathExists $trimmed)) {
-        return [PSCustomObject]@{ Dir = $Default; Source = "stale-registry" }
-    }
-    return [PSCustomObject]@{ Dir = $trimmed; Source = "registry" }
-}
-
-# SAFETY (review of 8da2b2e, CRITICAL): -RecordedInstallLocation and
-# -CanonicalOverrideForTest are ordinary parameters on the SHIPPED script, so
-# they are reachable through exactly the `-File` invocation surface Inno and
-# the shortcuts use. As first written they fed the canonical decision directly,
-# which let a stray copy pass -CanonicalOverrideForTest <its own dir> and reach
-# `docker compose -p culpa down` and the culpa_pgdata prompt with NO -Force and
-# none of the -Force warnings. Proven by probe: wouldProceed:true, forced:false.
-# That is the precise scenario CR-PR5 round 2 exists to prevent, and the
-# -Probe precedent cited above does not excuse it: that one is a parameter of
-# an INTERNAL FUNCTION, reachable only by dot-sourcing, never a top-level flag.
-#
-# They are therefore honoured ONLY under -PrintPlanOnly, which cannot touch
-# docker, the data volume, the registry or any file. In a run that could do
-# something destructive they are ignored outright, so the canonical decision
-# always comes from the real registry or the real default.
-$InjectionRequested = $PSBoundParameters.ContainsKey('RecordedInstallLocation') -or
-                      -not [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)
-$InjectionHonoured = $InjectionRequested -and $PrintPlanOnly.IsPresent
-
-if ($InjectionHonoured -and $PSBoundParameters.ContainsKey('RecordedInstallLocation')) {
-    $Recorded = $RecordedInstallLocation
-} else {
-    $Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
-}
-$DefaultDir = if (-not $InjectionHonoured -or [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)) {
-    Join-Path $env:LOCALAPPDATA "Culpa"
-} else {
-    $CanonicalOverrideForTest.TrimEnd('\')
-}
-$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
-$Canonical = $Resolved.Dir
-$ComposeDst = Join-Path $AppDir "docker-compose.yml"
-
-$Matches_ = ((Normalize-Dir $AppDir) -eq (Normalize-Dir $Canonical))
-$WouldProceed = ($Matches_ -or $Force.IsPresent)
-
-if ($PrintPlanOnly) {
-    [PSCustomObject]@{
-        appDir          = $AppDir
-        canonical       = $Canonical
-        canonicalSource = $Resolved.Source
-        wouldProceed    = $WouldProceed
-        forced          = ($Force.IsPresent -and -not $Matches_)
-        # so plan output can never be mistaken for a real registry read
-        injected        = $InjectionHonoured
-    } | ConvertTo-Json -Compress
-    exit 0
-}
-
-if (-not $WouldProceed) {
-    # non-canonical copy: touch NOTHING (no docker, no volume, no files)
-    Write-Host "This copy is not the installed one - nothing was changed." -ForegroundColor Yellow
-    Write-Host "To uninstall Culpa: Windows Settings -> Installed apps -> Culpa,"
-    Write-Host "or run uninstall-culpa.ps1 in $Canonical."
-    if ($Resolved.Source -eq "stale-registry") {
-        Write-Host "(The recorded install location no longer exists, so the default was used.)"
-    }
-    # T-CF29-2: never leave the user with no way out. If the canonical
-    # directory is wrong or gone, this is the escape hatch — explicit, so it
-    # can never fire by accident on a stray copy.
-    Write-Host "If Culpa really is installed HERE, re-run with -Force:" -ForegroundColor Yellow
-    Write-Host "  powershell -ExecutionPolicy Bypass -File `"$AppDir\uninstall-culpa.ps1`" -Force"
-    if (-not $FromUninstaller) { Read-Host "Press Enter to close" }
-    exit 0
-}
-
-if ($Force.IsPresent -and -not $Matches_) {
-    Write-Host "-Force: uninstalling from $AppDir even though the recorded location is $Canonical." -ForegroundColor Yellow
-}
-
-# CF19 (CodeRabbit PR#16 #289): collector shutdown runs AFTER the
-# canonical-path guard — a stray COPY of this script must not change the real
-# installation, and stopping its collector is a change. Stopping capture is
-# otherwise always safe, so it precedes the container teardown.
-$CollectorCtl = Join-Path $AppDir "culpa-collector.ps1"
-if (Test-Path $CollectorCtl) { & $CollectorCtl -Stop }
-
-Write-Host "==> Stopping Culpa"
-# CR-PR5: judge the native exit code explicitly (SilentlyContinue does NOT
-# catch it), and NEVER infer "stopped" from a missing compose file - a prior
-# failed cleanup can leave containers running. Absent file => ask docker.
-$stackStopped = $false
-# CR-PR5 r4: check docker EXPLICITLY. SilentlyContinue swallows a missing
-# executable and leaves $LASTEXITCODE at its PRIOR value - verified on
-# Windows PowerShell 5.1: after any earlier successful native command that
-# value is 0, so the old implicit test would have read "stopped" having
-# stopped nothing, and deleted files while containers ran. Fail-closed now
-# by construction, not by the accident of call ordering.
-if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
-    Write-Host "Docker was not found on PATH - cannot confirm Culpa is stopped." -ForegroundColor Yellow
-} elseif (Test-Path $ComposeDst) {
-    docker compose -f $ComposeDst -p culpa down
-    $stackStopped = ($LASTEXITCODE -eq 0)
-} else {
-    Write-Host "No compose file here - checking for running Culpa containers directly."
-    docker compose -p culpa down
-    $stackStopped = ($LASTEXITCODE -eq 0)
-}
-if (-not $stackStopped) {
-    Write-Host "Culpa did not stop cleanly - leaving files in place so you can retry:" -ForegroundColor Yellow
-    Write-Host "  docker compose -p culpa down"
-}
-
-Write-Host "==> Removing shortcuts"
-Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa.lnk") -Force
-Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa Dashboard.url") -Force
-Remove-Item (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa") -Recurse -Force
-
-if (-not $FromUninstaller) {
-    $wipe = Read-Host "Also DELETE all recorded cost data? This cannot be undone. (y/N)"
-    if ($wipe -eq "y" -or $wipe -eq "Y") {
-        docker volume rm culpa_pgdata
-        Write-Host "Data volume removed."
-    } else {
-        Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
-    }
-    if ($stackStopped) {
-        $unins = Join-Path $AppDir "unins000.exe"
-        if (Test-Path $unins) {
-            # exe install: hand off so the Windows Settings entry is cleaned too
-            Start-Process $unins "/VERYSILENT"
-        } else {
-            # T-171 script install: WE own the Settings entry, so we remove it.
-            # An exe install never reaches here - Inno owns and removes its own
-            # key, and deleting it from this side would strand the wizard with
-            # a listing it can no longer clean up.
-            Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Recurse -Force
-            Remove-Item $AppDir -Recurse -Force
-        }
-        Write-Host "Culpa removed."
-    } else {
-        Write-Host "Files kept because the stack is still running - stop it, then run this again."
-    }
-    Read-Host "Press Enter to close"
-} else {
-    # setup.exe's uninstaller removes the installed files itself; we only
-    # clean up what install-culpa.ps1 created at runtime - and ONLY when the
-    # stack actually stopped
-    # CR-PR5 round 3: SIGNAL the failure. Printing alone let Inno delete the
-    # scripts while containers were still running; culpa-setup.iss now runs
-    # this from InitializeUninstall and CANCELS the uninstall on a nonzero
-    # exit, so the files stay put and the retry is possible.
-    if (-not $stackStopped) {
-        Write-Host "Refusing to remove Culpa while its containers are running." -ForegroundColor Red
-        exit 1
-    }
-    Remove-Item $ComposeDst -Force
-    Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
-}
+# Culpa uninstaller for Windows (T-087, T-IX-01).
+# Stops and removes the containers and shortcuts. Your recorded data is
+# KEPT unless you answer Y to the final question.
+# -FromUninstaller: run by the setup.exe's uninstaller - no interactive
+# prompts, data always kept (never delete data without an explicit yes). Inno
+# removes the installed files and its own Add/Remove key itself, so this mode
+# only cleans the runtime compose file and refuses (exit 1) while running.
+# -Unattended: run by the npm `preuninstall` hook (D-126) - ALSO non-interactive
+# and data-always-kept, but there is NO Inno wizard to clean up after us, so this
+# mode removes the app dir and the (script-install) Add/Remove key itself.
+# Exactly one of these is set by a non-interactive caller; a human CLI run sets
+# neither and gets the prompts.
+#
+# CR-PR5 round 2 (SAFETY ORDERING): the canonical-path check now gates EVERY
+# destructive action - docker down, the data-volume prompt, and file removal.
+# A copy of this script run from anywhere else previously could stop the real
+# `culpa` project and offer to delete culpa_pgdata, the shared data volume.
+# T-CF29-2 params:
+#   -Force                      proceed from THIS directory even when the
+#                               canonical check disagrees (explicit opt-in;
+#                               never automatic)
+#   -RecordedInstallLocation    inject what the registry would return, so the
+#                               resolution can be tested without touching HKCU
+#                               (same -Probe precedent as install-culpa.ps1)
+#   -CanonicalOverrideForTest   inject the fallback directory, for the same reason
+#   -PrintPlanOnly              resolve, print the decision as JSON, exit 0
+#                               BEFORE any destructive action
+param(
+    [switch]$FromUninstaller,
+    [switch]$Force,
+    [string]$RecordedInstallLocation,
+    [string]$CanonicalOverrideForTest,
+    [switch]$PrintPlanOnly,
+    [switch]$Unattended
+)
+
+$ErrorActionPreference = "SilentlyContinue"
+$AppDir = $PSScriptRoot
+# A human CLI uninstall is the only INTERACTIVE caller: both -FromUninstaller
+# (Inno) and -Unattended (npm preuninstall hook) run without prompts. Every
+# Read-Host below is gated on this so a non-interactive caller can never block.
+$Interactive = (-not $FromUninstaller) -and (-not $Unattended)
+# CF5-F11: the install directory is the founder's choice now, so "canonical"
+# is what SETUP RECORDED, not a hardcoded path. Inno writes InstallLocation
+# into its own uninstall key; fall back to %LOCALAPPDATA%\Culpa for installs
+# made before the directory page existed, and for the zip layout.
+# The guard itself is unchanged and still load-bearing: a stray COPY of this
+# script must never stop containers or delete files belonging to the real
+# install.
+#
+# T-CF29-2: a recorded value that POINTS AT A DELETED DIRECTORY used to be
+# trusted anyway, so the guard below could never match and Culpa became
+# impossible to uninstall. That is not hypothetical — the CF20 npm gate
+# overwrote this shared value with a scratch dir which was then removed.
+# A path that does not exist cannot be shadowing a real install, so it is
+# ignored in favour of the default. Everything else about the guard stands.
+# T-CF29-2: the guard compared raw strings, so two spellings of the SAME
+# directory read as different installs — an 8.3 short path (C:\Users\ZOLANI~1)
+# versus its long form, a trailing backslash, or different casing. Each of
+# those turns the uninstaller into the same dead end a stale registry value
+# does. Resolve-Path returns the canonical long form for a path that exists;
+# a path that does not exist falls back to a trimmed, lowercased comparison.
+function Normalize-Dir {
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
+    $trimmed = $Path.TrimEnd('\', '/')
+    # GetFullPath expands an 8.3 short component (ZOLANI~1) to its long form;
+    # Resolve-Path does NOT (verified on this machine), so it cannot be relied
+    # on for that. Both are best-effort: a path that cannot be expanded falls
+    # through to the trimmed, lowercased comparison.
+    try { $trimmed = [System.IO.Path]::GetFullPath($trimmed).TrimEnd('\', '/') } catch { }
+    return $trimmed.ToLowerInvariant()
+}
+
+function Resolve-CanonicalDir {
+    param(
+        [string]$Recorded,
+        [string]$Default,
+        [scriptblock]$PathExists = { param($p) Test-Path -LiteralPath $p }
+    )
+    if ([string]::IsNullOrWhiteSpace($Recorded)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "default" }
+    }
+    $trimmed = $Recorded.TrimEnd('\')
+    if (-not (& $PathExists $trimmed)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "stale-registry" }
+    }
+    return [PSCustomObject]@{ Dir = $trimmed; Source = "registry" }
+}
+
+# SAFETY (review of 8da2b2e, CRITICAL): -RecordedInstallLocation and
+# -CanonicalOverrideForTest are ordinary parameters on the SHIPPED script, so
+# they are reachable through exactly the `-File` invocation surface Inno and
+# the shortcuts use. As first written they fed the canonical decision directly,
+# which let a stray copy pass -CanonicalOverrideForTest <its own dir> and reach
+# `docker compose -p culpa down` and the culpa_pgdata prompt with NO -Force and
+# none of the -Force warnings. Proven by probe: wouldProceed:true, forced:false.
+# That is the precise scenario CR-PR5 round 2 exists to prevent, and the
+# -Probe precedent cited above does not excuse it: that one is a parameter of
+# an INTERNAL FUNCTION, reachable only by dot-sourcing, never a top-level flag.
+#
+# They are therefore honoured ONLY under -PrintPlanOnly, which cannot touch
+# docker, the data volume, the registry or any file. In a run that could do
+# something destructive they are ignored outright, so the canonical decision
+# always comes from the real registry or the real default.
+$InjectionRequested = $PSBoundParameters.ContainsKey('RecordedInstallLocation') -or
+                      -not [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)
+$InjectionHonoured = $InjectionRequested -and $PrintPlanOnly.IsPresent
+
+if ($InjectionHonoured -and $PSBoundParameters.ContainsKey('RecordedInstallLocation')) {
+    $Recorded = $RecordedInstallLocation
+} else {
+    $Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
+}
+$DefaultDir = if (-not $InjectionHonoured -or [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)) {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+} else {
+    $CanonicalOverrideForTest.TrimEnd('\')
+}
+$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
+$Canonical = $Resolved.Dir
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+
+$Matches_ = ((Normalize-Dir $AppDir) -eq (Normalize-Dir $Canonical))
+$WouldProceed = ($Matches_ -or $Force.IsPresent)
+
+if ($PrintPlanOnly) {
+    [PSCustomObject]@{
+        appDir          = $AppDir
+        canonical       = $Canonical
+        canonicalSource = $Resolved.Source
+        wouldProceed    = $WouldProceed
+        forced          = ($Force.IsPresent -and -not $Matches_)
+        # so plan output can never be mistaken for a real registry read
+        injected        = $InjectionHonoured
+    } | ConvertTo-Json -Compress
+    exit 0
+}
+
+if (-not $WouldProceed) {
+    # non-canonical copy: touch NOTHING (no docker, no volume, no files)
+    Write-Host "This copy is not the installed one - nothing was changed." -ForegroundColor Yellow
+    Write-Host "To uninstall Culpa: Windows Settings -> Installed apps -> Culpa,"
+    Write-Host "or run uninstall-culpa.ps1 in $Canonical."
+    if ($Resolved.Source -eq "stale-registry") {
+        Write-Host "(The recorded install location no longer exists, so the default was used.)"
+    }
+    # T-CF29-2: never leave the user with no way out. If the canonical
+    # directory is wrong or gone, this is the escape hatch — explicit, so it
+    # can never fire by accident on a stray copy.
+    Write-Host "If Culpa really is installed HERE, re-run with -Force:" -ForegroundColor Yellow
+    Write-Host "  powershell -ExecutionPolicy Bypass -File `"$AppDir\uninstall-culpa.ps1`" -Force"
+    if ($Interactive) { Read-Host "Press Enter to close" }
+    exit 0
+}
+
+if ($Force.IsPresent -and -not $Matches_) {
+    Write-Host "-Force: uninstalling from $AppDir even though the recorded location is $Canonical." -ForegroundColor Yellow
+}
+
+# CF19 (CodeRabbit PR#16 #289): collector shutdown runs AFTER the
+# canonical-path guard — a stray COPY of this script must not change the real
+# installation, and stopping its collector is a change. Stopping capture is
+# otherwise always safe, so it precedes the container teardown.
+$CollectorCtl = Join-Path $AppDir "culpa-collector.ps1"
+if (Test-Path $CollectorCtl) { & $CollectorCtl -Stop }
+
+Write-Host "==> Stopping Culpa"
+# CR-PR5: judge the native exit code explicitly (SilentlyContinue does NOT
+# catch it), and NEVER infer "stopped" from a missing compose file - a prior
+# failed cleanup can leave containers running. Absent file => ask docker.
+$stackStopped = $false
+# CR-PR5 r4: check docker EXPLICITLY. SilentlyContinue swallows a missing
+# executable and leaves $LASTEXITCODE at its PRIOR value - verified on
+# Windows PowerShell 5.1: after any earlier successful native command that
+# value is 0, so the old implicit test would have read "stopped" having
+# stopped nothing, and deleted files while containers ran. Fail-closed now
+# by construction, not by the accident of call ordering.
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "Docker was not found on PATH - cannot confirm Culpa is stopped." -ForegroundColor Yellow
+} elseif (Test-Path $ComposeDst) {
+    docker compose -f $ComposeDst -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+} else {
+    Write-Host "No compose file here - checking for running Culpa containers directly."
+    docker compose -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+}
+if (-not $stackStopped) {
+    Write-Host "Culpa did not stop cleanly - leaving files in place so you can retry:" -ForegroundColor Yellow
+    Write-Host "  docker compose -p culpa down"
+}
+
+Write-Host "==> Removing shortcuts"
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa.lnk") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa Dashboard.url") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa") -Recurse -Force
+
+# The data-wipe question is the ONLY place data can be deleted, and it is
+# offered ONLY to an interactive human. Both non-interactive callers keep data.
+if ($Interactive) {
+    $wipe = Read-Host "Also DELETE all recorded cost data? This cannot be undone. (y/N)"
+    if ($wipe -eq "y" -or $wipe -eq "Y") {
+        docker volume rm culpa_pgdata
+        Write-Host "Data volume removed."
+    } else {
+        Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+    }
+}
+
+if ($FromUninstaller) {
+    # setup.exe's uninstaller removes the installed files AND its own Add/Remove
+    # key itself; we only clean up the runtime compose file - and ONLY when the
+    # stack actually stopped.
+    # CR-PR5 round 3: SIGNAL the failure. Printing alone let Inno delete the
+    # scripts while containers were still running; culpa-setup.iss now runs
+    # this from InitializeUninstall and CANCELS the uninstall on a nonzero
+    # exit, so the files stay put and the retry is possible.
+    if (-not $stackStopped) {
+        Write-Host "Refusing to remove Culpa while its containers are running." -ForegroundColor Red
+        exit 1
+    }
+    Remove-Item $ComposeDst -Force
+    Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+} else {
+    # An interactive CLI uninstall OR the npm preuninstall hook (-Unattended):
+    # there is NO Inno wizard to clean up after us, so WE remove the install dir
+    # and the (script-install) Add/Remove key - but ONLY when the stack stopped.
+    if (-not $stackStopped) {
+        Write-Host "Files kept because the stack is still running - stop it, then run this again."
+        # -Unattended (npm): nothing was removed, so report failure (exit 1) —
+        # lib/uninstall.mjs reads this and the hook then warns loudly; npm still
+        # removes the CLI. A human sees the message above and can retry.
+        if ($Unattended) { exit 1 }
+    } else {
+        $unins = Join-Path $AppDir "unins000.exe"
+        if (Test-Path $unins) {
+            # exe install: hand off so the Windows Settings entry is cleaned too
+            Start-Process $unins "/VERYSILENT"
+        } else {
+            # T-171 script/npm install: WE own the Settings entry, so we remove it.
+            # An exe install never reaches here - Inno owns and removes its own
+            # key, and deleting it from this side would strand the wizard with
+            # a listing it can no longer clean up.
+            Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Recurse -Force
+            Remove-Item $AppDir -Recurse -Force
+        }
+        Write-Host "Culpa removed."
+    }
+    if ($Interactive) { Read-Host "Press Enter to close" }
+}

package/lib/uninstall.d.mts

@@ -1,17 +1,20 @@
-export interface UninstallOptions {
-  appDir?: string;
-  platform?: string;
-  spawnSync?: (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
-  homedir?: string;
-  createInterface?: (opts: { input: NodeJS.ReadStream; output: NodeJS.WriteStream }) => {
-    question: (prompt: string, cb: (answer: string) => void) => void;
-    close: () => void;
-  };
-  isTTY?: boolean;
-}
-
-export interface UninstallResult {
-  ok: boolean;
-}
-
-export function uninstall(opts?: UninstallOptions): Promise<UninstallResult>;
+export interface UninstallOptions {
+  appDir?: string;
+  platform?: string;
+  spawnSync?: (cmd: string, args?: string[], opts?: unknown) => { status: number | null };
+  homedir?: string;
+  createInterface?: (opts: { input: NodeJS.ReadStream; output: NodeJS.WriteStream }) => {
+    question: (prompt: string, cb: (answer: string) => void) => void;
+    close: () => void;
+  };
+  isTTY?: boolean;
+  /** Set by the npm `preuninstall` hook: suppress the "npm uninstall -g getculpa"
+   *  next-step hint (we are already inside that command). D-126 / v1.0.9. */
+  fromNpmHook?: boolean;
+}
+
+export interface UninstallResult {
+  ok: boolean;
+}
+
+export function uninstall(opts?: UninstallOptions): Promise<UninstallResult>;

package/lib/uninstall.mjs

@@ -1,138 +1,158 @@
-// CF20-T3 — `getculpa uninstall`. win32 delegates to the same
-// uninstall-culpa.ps1 the Windows installer ships (canonical-path guard,
-// collector stop, compose down, pgdata prompt all live there already).
-// macOS/Linux implement the same net effect once: compose down, remove the
-// shortcut equivalents this core lays down, prompt for pgdata removal
-// (TTY only — never destructive without an interactive terminal), then
-// point at `npm uninstall -g getculpa` to remove the CLI itself.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import readline from "node:readline";
-import { getAppDir } from "./paths.mjs";
-
-function delegateWindowsUninstall(appDir, spawnSync) {
-  const script = path.join(appDir, "uninstall-culpa.ps1");
-  const result = spawnSync("powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script], {
-    stdio: "inherit",
-  });
-  // uninstall-culpa.ps1 stops the capture collector itself before stopping
-  // the stack (CF19 CodeRabbit PR#16 #289) — non-fatally, with no exit-code
-  // gate on that one step, so a collector-stop hiccup alone never fails this
-  // delegate. This return value IS the delegate's true overall outcome
-  // (stack stop + everything else the script does), inherited straight to
-  // the console via stdio:"inherit" either way.
-  return result.status === 0;
-}
-
-// CF20-R: guard the case where there is nothing to bring down (a fresh app
-// dir, or one already fully torn down) — running `docker compose -f
-// <nonexistent file> ... down` would just fail loudly for no real reason.
-// A genuine compose-down failure (the file exists, the command ran, and
-// docker refused) DOES surface as a failure — see the caller.
-function composeDown(appDir, spawnSync) {
-  const compose = path.join(appDir, "docker-compose.yml");
-  if (!existsSync(compose)) {
-    console.log("getculpa: no docker-compose.yml found - nothing to stop.");
-    return true;
-  }
-  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "down"], { stdio: "inherit" });
-  if (result.status !== 0) {
-    console.error("getculpa: `docker compose down` did not complete cleanly - see the output above.");
-  }
-  return result.status === 0;
-}
-
-// The only shortcut this core lays down outside the app dir on macOS is the
-// Desktop .webloc (installers/macos/install-culpa.command:132-142); Linux
-// ships no shortcut convention yet, so there is nothing else to remove.
-function removeShortcutEquivalents(homedir) {
-  rmSync(path.join(homedir, "Desktop", "Culpa Dashboard.webloc"), { force: true });
-}
-
-// Never destructive without a real interactive terminal — a non-TTY caller
-// (CI, a script, npm's own postinstall/preuninstall hooks) always gets NO.
-// isTTY is injectable (same pattern as lib/start.mjs's maybeOpenBrowser)
-// rather than read from the live process.stdin.isTTY directly, so tests
-// assert the safe default deliberately instead of relying on vitest's own
-// stdin happening to be non-TTY.
-async function promptPgdataRemoval(createInterface, isTTY) {
-  if (!isTTY) return false;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise((resolve) => {
-    // V102 T-V102-16 (D-113): EOF (Ctrl-D, or a stdin that ends mid-prompt)
-    // fires `close` and NEVER invokes question()'s callback — this promise
-    // used to hang forever at the one prompt guarding DELETION of the cost
-    // database. An unanswered question is a NO, exactly like tty.mjs.
-    // Optional-call: older injected fakes without `once` keep working.
-    rl.once?.("close", () => resolve(""));
-    rl.question("Also DELETE all recorded cost data? This cannot be undone. (y/N) ", resolve);
-  });
-  rl.close();
-  return answer.trim().toLowerCase() === "y";
-}
-
-// V102 T-V102-16 (M11/W2, D-113): macOS uninstall exited 0 leaving ~7.3 MB
-// (launcher, collector, compose, register.mjs) silently behind — the Windows
-// ps1 removes the app dir and is "the more complete of the two" (W2). Remove
-// the dir ONLY when it is provably a Culpa install dir (install-state.json,
-// which every install writes); a mistargeted CULPA_APP_DIR is kept and said.
-// Truthful beats a surprise rm -rf in both directions.
-function removeAppDir(appDir) {
-  if (!existsSync(appDir)) return;
-  if (existsSync(path.join(appDir, "install-state.json"))) {
-    rmSync(appDir, { recursive: true, force: true });
-    console.log(`Removed: ${appDir} (launcher, collector, compose and capture shims).`);
-    return;
-  }
-  console.log(
-    `Kept: ${appDir} - no install-state.json found there, so it is not provably a Culpa install directory. Remove it yourself if you are sure.`,
-  );
-}
-
-export async function uninstall(opts = {}) {
-  const appDir = opts.appDir ?? getAppDir();
-  const platform = opts.platform ?? process.platform;
-  const spawnSync = opts.spawnSync ?? realSpawnSync;
-  const homedir = opts.homedir ?? os.homedir();
-  const createInterface = opts.createInterface ?? readline.createInterface;
-  const isTTY = opts.isTTY ?? process.stdin.isTTY;
-
-  let ok;
-  if (platform === "win32") {
-    ok = delegateWindowsUninstall(appDir, spawnSync);
-    if (!ok) console.error("getculpa: uninstall did not complete cleanly - see the output above.");
-  } else {
-    ok = composeDown(appDir, spawnSync);
-    // Review-4 IMPORTANT + CodeRabbit PR#19 [7] (Major): a FAILED stop skips
-    // EVERY destructive step — the ps1's $stackStopped gate, whose comment
-    // records the prior real incident (CR-PR5 round 3). Not even the pgdata
-    // PROMPT is offered: after a partial teardown the volume can be
-    // unreferenced, so a user confirming deletion here could lose the cost
-    // database while being told the stack is still running. Nothing is
-    // removed; the one honest instruction is to stop the stack and rerun.
-    if (!ok) {
-      console.log(
-        `Files kept: ${appDir} - the stack is still running (\`docker compose down\` failed above). Nothing was removed. Stop the stack, then run this again.`,
-      );
-    } else {
-      removeShortcutEquivalents(homedir);
-      const wipe = await promptPgdataRemoval(createInterface, isTTY);
-      if (wipe) {
-        spawnSync("docker", ["volume", "rm", "culpa_pgdata"], { stdio: "inherit" });
-        console.log("Data volume removed.");
-      } else {
-        console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
-      }
-      // M11/W2: after the data decision, remove the app dir itself (ps1 parity)
-      removeAppDir(appDir);
-    }
-  }
-
-  console.log("");
-  console.log("To finish removing the Culpa CLI: npm uninstall -g getculpa");
-
-  return { ok };
-}
+// CF20-T3 — `getculpa uninstall`. win32 delegates to the same
+// uninstall-culpa.ps1 the Windows installer ships (canonical-path guard,
+// collector stop, compose down, pgdata prompt all live there already).
+// macOS/Linux implement the same net effect once: compose down, remove the
+// shortcut equivalents this core lays down, prompt for pgdata removal
+// (TTY only — never destructive without an interactive terminal), then
+// point at `npm uninstall -g getculpa` to remove the CLI itself.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { getAppDir } from "./paths.mjs";
+
+function delegateWindowsUninstall(appDir, spawnSync, isTTY) {
+  const script = path.join(appDir, "uninstall-culpa.ps1");
+  // D-126: a non-interactive caller (the npm `preuninstall` hook, or any non-TTY
+  // run) MUST pass -Unattended so uninstall-culpa.ps1 skips every Read-Host — it
+  // would otherwise PROMPT to delete the cost database and BLOCK on "Press Enter"
+  // inside a silent `npm uninstall -g`. -Unattended still does the full
+  // self-teardown (remove the app dir + the script-install Add/Remove key), which
+  // -FromUninstaller (Inno's mode) deliberately does not. powershell's own
+  // -NonInteractive is added as a fail-fast: any stray prompt errors, never hangs.
+  const nonInteractive = !isTTY;
+  const args = ["-NoProfile"];
+  if (nonInteractive) args.push("-NonInteractive");
+  args.push("-ExecutionPolicy", "Bypass", "-File", script);
+  if (nonInteractive) args.push("-Unattended");
+  const result = spawnSync("powershell.exe", args, {
+    stdio: "inherit",
+  });
+  // uninstall-culpa.ps1 stops the capture collector itself before stopping
+  // the stack (CF19 CodeRabbit PR#16 #289) — non-fatally, with no exit-code
+  // gate on that one step, so a collector-stop hiccup alone never fails this
+  // delegate. This return value IS the delegate's true overall outcome
+  // (stack stop + everything else the script does), inherited straight to
+  // the console via stdio:"inherit" either way.
+  return result.status === 0;
+}
+
+// CF20-R: guard the case where there is nothing to bring down (a fresh app
+// dir, or one already fully torn down) — running `docker compose -f
+// <nonexistent file> ... down` would just fail loudly for no real reason.
+// A genuine compose-down failure (the file exists, the command ran, and
+// docker refused) DOES surface as a failure — see the caller.
+function composeDown(appDir, spawnSync) {
+  const compose = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(compose)) {
+    console.log("getculpa: no docker-compose.yml found - nothing to stop.");
+    return true;
+  }
+  const result = spawnSync("docker", ["compose", "-f", compose, "-p", "culpa", "down"], { stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error("getculpa: `docker compose down` did not complete cleanly - see the output above.");
+  }
+  return result.status === 0;
+}
+
+// The only shortcut this core lays down outside the app dir on macOS is the
+// Desktop .webloc (installers/macos/install-culpa.command:132-142); Linux
+// ships no shortcut convention yet, so there is nothing else to remove.
+function removeShortcutEquivalents(homedir) {
+  rmSync(path.join(homedir, "Desktop", "Culpa Dashboard.webloc"), { force: true });
+}
+
+// Never destructive without a real interactive terminal — a non-TTY caller
+// (CI, a script, npm's own postinstall/preuninstall hooks) always gets NO.
+// isTTY is injectable (same pattern as lib/start.mjs's maybeOpenBrowser)
+// rather than read from the live process.stdin.isTTY directly, so tests
+// assert the safe default deliberately instead of relying on vitest's own
+// stdin happening to be non-TTY.
+async function promptPgdataRemoval(createInterface, isTTY) {
+  if (!isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    // V102 T-V102-16 (D-113): EOF (Ctrl-D, or a stdin that ends mid-prompt)
+    // fires `close` and NEVER invokes question()'s callback — this promise
+    // used to hang forever at the one prompt guarding DELETION of the cost
+    // database. An unanswered question is a NO, exactly like tty.mjs.
+    // Optional-call: older injected fakes without `once` keep working.
+    rl.once?.("close", () => resolve(""));
+    rl.question("Also DELETE all recorded cost data? This cannot be undone. (y/N) ", resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}
+
+// V102 T-V102-16 (M11/W2, D-113): macOS uninstall exited 0 leaving ~7.3 MB
+// (launcher, collector, compose, register.mjs) silently behind — the Windows
+// ps1 removes the app dir and is "the more complete of the two" (W2). Remove
+// the dir ONLY when it is provably a Culpa install dir (install-state.json,
+// which every install writes); a mistargeted CULPA_APP_DIR is kept and said.
+// Truthful beats a surprise rm -rf in both directions.
+function removeAppDir(appDir) {
+  if (!existsSync(appDir)) return;
+  if (existsSync(path.join(appDir, "install-state.json"))) {
+    rmSync(appDir, { recursive: true, force: true });
+    console.log(`Removed: ${appDir} (launcher, collector, compose and capture shims).`);
+    return;
+  }
+  console.log(
+    `Kept: ${appDir} - no install-state.json found there, so it is not provably a Culpa install directory. Remove it yourself if you are sure.`,
+  );
+}
+
+export async function uninstall(opts = {}) {
+  const appDir = opts.appDir ?? getAppDir();
+  const platform = opts.platform ?? process.platform;
+  const spawnSync = opts.spawnSync ?? realSpawnSync;
+  const homedir = opts.homedir ?? os.homedir();
+  const createInterface = opts.createInterface ?? readline.createInterface;
+  const isTTY = opts.isTTY ?? process.stdin.isTTY;
+  // D-126 / v1.0.9: set by the npm `preuninstall` hook (scripts/preuninstall.js).
+  // When true we are ALREADY inside `npm uninstall -g getculpa`, so the trailing
+  // "To finish removing the Culpa CLI: npm uninstall -g getculpa" hint below is
+  // wrong/confusing — the hook owns the closing "what's left behind" summary.
+  // Teardown behaviour is otherwise identical.
+  const fromNpmHook = opts.fromNpmHook ?? false;
+
+  let ok;
+  if (platform === "win32") {
+    ok = delegateWindowsUninstall(appDir, spawnSync, isTTY);
+    if (!ok) console.error("getculpa: uninstall did not complete cleanly - see the output above.");
+  } else {
+    ok = composeDown(appDir, spawnSync);
+    // Review-4 IMPORTANT + CodeRabbit PR#19 [7] (Major): a FAILED stop skips
+    // EVERY destructive step — the ps1's $stackStopped gate, whose comment
+    // records the prior real incident (CR-PR5 round 3). Not even the pgdata
+    // PROMPT is offered: after a partial teardown the volume can be
+    // unreferenced, so a user confirming deletion here could lose the cost
+    // database while being told the stack is still running. Nothing is
+    // removed; the one honest instruction is to stop the stack and rerun.
+    if (!ok) {
+      console.log(
+        `Files kept: ${appDir} - the stack is still running (\`docker compose down\` failed above). Nothing was removed. Stop the stack, then run this again.`,
+      );
+    } else {
+      removeShortcutEquivalents(homedir);
+      const wipe = await promptPgdataRemoval(createInterface, isTTY);
+      if (wipe) {
+        spawnSync("docker", ["volume", "rm", "culpa_pgdata"], { stdio: "inherit" });
+        console.log("Data volume removed.");
+      } else {
+        console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
+      }
+      // M11/W2: after the data decision, remove the app dir itself (ps1 parity)
+      removeAppDir(appDir);
+    }
+  }
+
+  if (!fromNpmHook) {
+    console.log("");
+    console.log("To finish removing the Culpa CLI: npm uninstall -g getculpa");
+  }
+
+  return { ok };
+}

package/package.json

@@ -1,25 +1,26 @@
-{
-  "name": "getculpa",
-  "version": "1.0.7",
-  "description": "Culpa CLI: `npm i -g getculpa` provisions the full Culpa install (Windows-installer parity) and leaves it dormant. `getculpa` wakes the stack.",
-  "license": "SEE LICENSE IN LICENSE",
-  "bin": {
-    "getculpa": "bin/getculpa.js",
-    "culpa": "bin/culpa.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/install.js",
-    "prepack": "node scripts/prepack.js"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "scripts/",
-    "assets/",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "getculpa",
+  "version": "1.0.9",
+  "description": "Culpa CLI: `npm i -g getculpa` provisions the full Culpa install (Windows-installer parity) and leaves it dormant. `getculpa` wakes the stack.",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "getculpa": "bin/getculpa.js",
+    "culpa": "bin/culpa.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "preuninstall": "node scripts/preuninstall.js",
+    "prepack": "node scripts/prepack.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/preuninstall.js

@@ -0,0 +1,82 @@
+// v1.0.9 (findings: ~/Downloads/10-uninstall-findings.md) — npm `preuninstall`
+// hook so `npm uninstall -g getculpa` actually DEPROVISIONS instead of leaving a
+// running stack, ~400MB of images and the stored credentials behind (the P1
+// findings: the CLI that could clean up was the very thing being deleted).
+//
+// npm runs this NON-INTERACTIVELY (no TTY), so it drives the same teardown as
+// `getculpa uninstall` in its safe, data-preserving default: stop the stack +
+// remove the `culpa` network, the Desktop shortcut and the app dir (which also
+// clears the stale install-state.json — findings P3). It NEVER deletes the data
+// volumes: a silent hook must not destroy the cost database or the stored
+// licence. It then prints exactly what is left behind, with the one-line removal
+// command (the findings' suggested fix).
+//
+// A nonzero exit does NOT stop `npm uninstall -g` (verified: node 20.19.6 /
+// npm 11.x, D-126), so the Windows Inno "cancel-on-nonzero" control cannot be
+// replicated here. The honest ceiling npm allows is a loud warning on a failed
+// stop; we give it and still exit 0 (a nonzero exit only adds "npm error" noise
+// while npm removes the package anyway).
+
+"use strict";
+
+// Dependency-injected so the summary / stop-failure messaging is unit-testable in
+// isolation (a fake `uninstall`, captured log/err) — mirrors the injection style
+// of tests/npm-core-uninstall.test.ts. The npm entry (bottom) wires the real deps.
+async function runPreuninstall(deps = {}) {
+  const importUninstall = deps.importUninstall ?? (() => import("../lib/uninstall.mjs"));
+  const log = deps.log ?? console.log;
+  const err = deps.err ?? console.error;
+
+  const { uninstall } = await importUninstall();
+
+  log("");
+  log("getculpa: uninstalling — stopping the Culpa stack and removing install files...");
+
+  let ok = false;
+  try {
+    ({ ok } = await uninstall({ isTTY: false, fromNpmHook: true }));
+  } catch (e) {
+    // A teardown error must never crash the hook or abort the package removal.
+    err(`getculpa: preuninstall teardown hit an error: ${(e && e.message) || e}`);
+    ok = false;
+  }
+
+  if (!ok) {
+    // "Refuse to leave a running stack silently" — the ceiling npm allows (D-126):
+    // npm removes getculpa regardless, so warn loudly with the manual command.
+    err("");
+    err("getculpa: WARNING — the Culpa stack may still be RUNNING (its stop did not complete cleanly).");
+    err("getculpa: getculpa is about to be removed, so stop the stack yourself with:");
+    err("    docker compose -p culpa down");
+    err("");
+    return { ok: false };
+  }
+
+  // Data + credentials are KEPT on purpose (never deleted by a silent hook).
+  // culpa_pgdata holds the recorded cost data AND the stored licence key + sync
+  // secret (culpa/api/claim_client.ts stores them in the SQL settings table);
+  // culpa_data holds the machine secret. No host-side licence file exists (D-126).
+  log("");
+  log("getculpa: Culpa's containers and network are stopped and the install files are removed.");
+  log("Two data volumes were KEPT on purpose (reinstalling later reuses them):");
+  log("  - culpa_pgdata : your recorded cost data AND your stored licence key + sync secret");
+  log("  - culpa_data   : the machine secret");
+  log("To remove them too (this DELETES your recorded data and stored licence, and cannot be undone):");
+  log("    docker volume rm culpa_pgdata culpa_data");
+  log("");
+  return { ok: true };
+}
+
+module.exports = { runPreuninstall };
+
+// Always exit 0: a failed teardown is surfaced as a loud warning above, not as a
+// nonzero exit (which npm ignores for uninstall while still removing the package).
+if (require.main === module) {
+  runPreuninstall().then(
+    () => process.exit(0),
+    (e) => {
+      console.error(`getculpa: preuninstall hook error (uninstall still proceeds): ${(e && e.message) || e}`);
+      process.exit(0);
+    },
+  );
+}