getculpa 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,41 @@
+Culpa — proprietary software licence
+====================================
+
+Copyright (c) 2026 Myaigi AI Labs (Proprietary) Limited.
+All rights reserved.
+
+Culpa is proprietary software. It is licensed, not sold.
+
+Your use of this package, the `getculpa` and `culpa` commands it installs, the
+binaries it downloads, and the Culpa container images it runs is governed by
+the Culpa End User Licence Agreement ("EULA") between you and Myaigi AI Labs
+(Proprietary) Limited.
+
+  Licensor:      Myaigi AI Labs (Proprietary) Limited
+                 Registration number 2025/688531/07
+                 121 Senior Drive, Randburg, Gauteng, 2195, South Africa
+  Product:       Culpa
+  Governing law: Republic of South Africa
+
+To obtain the current EULA, contact the licensor at the address below.
+
+Except as the EULA expressly permits, you may not copy, modify, merge,
+publish, distribute, sublicense, sell, rent, lease, reverse engineer, or
+create derivative works of the Software, and you may not remove or alter any
+proprietary notice in it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, TO THE FULLEST EXTENT PERMITTED BY LAW. The EULA governs warranties,
+liability, and your statutory rights, and prevails over this notice wherever
+the two differ. Nothing here limits any right you have under applicable
+consumer law that cannot lawfully be excluded.
+
+This package downloads and installs additional Culpa components at install
+time and at update time, from Culpa's official release channel, with each
+artifact verified by checksum before it is used.
+
+Third-party open-source components distributed with or downloaded by Culpa
+remain under their own licences; those licences continue to apply to them and
+nothing in this notice restricts rights granted by them.
+
+Legal notices and licensing questions: info@myaigi.ai

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.1 PUBLISHED AND SIGNED (2026-08-16) ─────────
+# ── RELEASE STATE: v1.0.2 PUBLISHED AND SIGNED (2026-08-17) ─────────
 # 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.1
+#     ghcr.io/myaigidev/culpa-server:v1.0.2
 # 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.1
+    image: ghcr.io/myaigidev/culpa-server:v1.0.2
     container_name: culpa-server
     environment:
       DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
@@ -115,8 +115,8 @@ services:
       # and keep it live. Only these two dirs, never the whole home.
       # NARROW scope (review M2): only the session-log subdirs — ~/.claude
       # also holds credentials/settings, which the container must never see
-      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME}}}/.claude/projects:/host/.claude/projects:ro
-      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME}}}/.codex/sessions:/host/.codex/sessions:ro
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME:-}}}/.claude/projects:/host/.claude/projects:ro
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME:-}}}/.codex/sessions:/host/.codex/sessions:ro
     depends_on:
       db:
         condition: service_healthy
@@ -127,7 +127,7 @@ services:
     # black-surface palette — no server, migration or API change, so the server
     # above deliberately stays at v0.11.0 rather than being re-tagged for a
     # release it has no diff in (D-072: never rebuild a tag that already exists).
-    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.1
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.2
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

package/assets/uninstall-culpa.ps1

@@ -8,7 +8,23 @@
 # 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.
-param([switch]$FromUninstaller)
+# 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
@@ -19,23 +35,117 @@ $AppDir = $PSScriptRoot
 # 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.
-$Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
-$Canonical = if ([string]::IsNullOrWhiteSpace($Recorded)) {
+#
+# 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 {
-    $Recorded.TrimEnd('\')
+    $CanonicalOverrideForTest.TrimEnd('\')
 }
+$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
+$Canonical = $Resolved.Dir
 $ComposeDst = Join-Path $AppDir "docker-compose.yml"
 
-if ($AppDir -ne $Canonical) {
+$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

package/lib/bootstrap.d.mts

@@ -0,0 +1,25 @@
+// Unlike docker.d.mts's SpawnSyncLike, this one carries `error`: a spawn that
+// never ran (missing binary, timeout kill) reports it there, not via status.
+export type LauncherSpawnSync = (
+  cmd: string,
+  args?: string[],
+  opts?: Record<string, unknown>,
+) => { status: number | null; error?: Error };
+
+export const PAYLOAD_STAGE_TIMEOUT_MS: number;
+
+export function vendoredLauncherPath(packageRoot: string, platform?: string): string | null;
+
+export interface StageInitialPayloadOptions {
+  launcherPath: string | null;
+  spawnSync?: LauncherSpawnSync;
+  log?: (msg: string) => void;
+  env?: Record<string, string | undefined>;
+}
+
+export interface StageInitialPayloadResult {
+  staged: boolean;
+  reason: "no-launcher" | "spawn-failed" | "update-failed" | "staged";
+}
+
+export function stageInitialPayload(opts: StageInitialPayloadOptions): StageInitialPayloadResult;

package/lib/bootstrap.mjs

@@ -0,0 +1,73 @@
+// T-CF28-4b — stage the CLI payload during `npm i -g getculpa`.
+//
+// THE DEFECT. A fresh install fetched the LAUNCHER (lib/fetch.mjs) but never
+// the PAYLOAD the launcher runs. `state.json` was left with `current: null`,
+// so the very first `getculpa` reached
+// native/culpa-launcher/src/main.rs:79-88, found nothing to exec, and printed
+// the no-payload message. The Mac tester had to work out `getculpa update` for
+// themselves and then run a SECOND command before anything happened. An
+// install that leaves nothing runnable is not an install.
+//
+// WHY THIS IS NOT AN UNCONSENTED UPDATE. `culpa update` is an explicit,
+// user-initiated verb and is not consent-gated: consent gates the BACKGROUND
+// check (`cli.rs:421-452`, `run_background_check` `cli.rs:316-318`). The user
+// ran `npm i -g getculpa`; downloading the program they just asked to install
+// is completing that install. The auto-update consent model is untouched, and
+// nothing here records a preference on the user's behalf.
+//
+// WHY IT SHELLS OUT RATHER THAN DOWNLOADING. The launcher already owns a
+// verified path: manifest fetch, sha256 verification, self-test, atomic
+// promotion. A second downloader in Node would be a second trust boundary to
+// audit and keep in step. This calls the one that already exists.
+//
+// EVERY FAILURE IS SOFT. Offline, a stalled mirror, a missing binary — none of
+// them fail the install. They leave the payload deferred, exactly as before
+// this module existed, and lib/install-summary.mjs says so and names the
+// command. The install never claims more than it did.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+// A real payload is tens of MB over a network Culpa does not control. Long
+// enough not to abort a slow-but-working download; short enough that a hung
+// mirror degrades to a clear deferred message instead of hanging `npm install`
+// indefinitely, which is the failure mode that matters — npm gives no progress
+// output of its own here.
+export const PAYLOAD_STAGE_TIMEOUT_MS = 10 * 60 * 1000;
+
+// Where lib/fetch.mjs puts the launcher (see stageStubLauncher in
+// scripts/install.js for the same naming: `culpa-launcher` + platform suffix).
+export function vendoredLauncherPath(packageRoot, platform = process.platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const candidate = path.join(packageRoot, "vendor", `culpa-launcher${exe}`);
+  return existsSync(candidate) ? candidate : null;
+}
+
+export function stageInitialPayload(opts) {
+  const { launcherPath, spawnSync = realSpawnSync, log = console.log, env = process.env } = opts;
+
+  // No launcher means the fetch above already failed and said so; there is
+  // nothing to invoke and nothing further worth reporting here.
+  if (!launcherPath) return { staged: false, reason: "no-launcher" };
+
+  log("getculpa: downloading the Culpa CLI (this is the program `getculpa` runs).");
+  const result = spawnSync(launcherPath, ["update"], {
+    stdio: "inherit",
+    timeout: PAYLOAD_STAGE_TIMEOUT_MS,
+    // Inherit the install's own environment so CULPA_HOME / CULPA_APP_DIR
+    // resolve to the SAME root scripts/install.js provisioned into (D-108
+    // unified that chain across the launcher and the Node CLI).
+    env,
+  });
+
+  if (result.error) {
+    log(`getculpa: could not download the Culpa CLI (${result.error.message}) - run \`getculpa update\` to finish.`);
+    return { staged: false, reason: "spawn-failed" };
+  }
+  if (result.status !== 0) {
+    log("getculpa: could not download the Culpa CLI - run `getculpa update` to finish.");
+    return { staged: false, reason: "update-failed" };
+  }
+  return { staged: true, reason: "staged" };
+}

package/lib/docker.d.mts

@@ -20,6 +20,10 @@ export function waitForDockerEngine(opts?: {
   sleepFn?: (ms: number) => Promise<void>;
 }): Promise<boolean>;
 
+export type DarwinDockerInstallOutcome = "installed" | "no-brew" | `failed:${string}`;
+
+export function installDockerDarwin(spawnSync?: SpawnSyncLike): DarwinDockerInstallOutcome;
+
 export function startEngineIfPossible(
   platform: string,
   spawnSync?: SpawnSyncLike,

package/lib/docker.mjs

@@ -80,6 +80,25 @@ export function startEngineIfPossible(platform, spawnSync = realSpawnSync, log =
   return { attempted: false, ok: false };
 }
 
+// T-CF28-7 — the macOS half of the ask-and-install flow Windows already
+// ships (installers/windows/launch-culpa.ps1:208-219). Called ONLY after the
+// user has explicitly agreed; this function does not ask. It reports WHICH
+// path it took rather than a bare boolean, for the same reason
+// Install-DockerDesktop does: a bare false made the .ps1's caller claim a
+// download page had been opened when the package manager was present and the
+// install had simply failed. Returns "installed" | "no-brew" | "failed:<code>".
+//
+// Homebrew is the only automatic path offered on darwin: it is the user's own
+// auditable package manager, and `--cask docker` is the official cask. There
+// is deliberately no curl-and-run fallback.
+export function installDockerDarwin(spawnSync = realSpawnSync) {
+  const brew = spawnSync("brew", ["--version"], { timeout: PROBE_TIMEOUT_MS });
+  if (brew.status !== 0) return "no-brew";
+  const result = spawnSync("brew", ["install", "--cask", "docker"], { stdio: "inherit" });
+  if (result.status === 0) return "installed";
+  return `failed:${result.status}`;
+}
+
 // --- IDEMPOTENCY (spec sec 23) ----------------------------------------------
 //
 // `docker ps` (RUNNING containers only — a `docker compose stop`ped stack

package/lib/doctor.mjs

@@ -20,7 +20,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findPortOwner, probeHealth, PROBE_TIMEOUT_MS } from "./docker.mjs";
 import { checkDockerPresent, checkDockerEngineReachable, classifyUpgrade, parsePinnedServerVersion } from "./preflight.mjs";
-import { PARITY_ASSETS } from "./provision.mjs";
+import { parityAssetsFor } from "./provision.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(__dirname, "..");
@@ -101,7 +101,7 @@ function checkVendoredLauncher(vendorDir, platform) {
   );
 }
 
-function checkInstallationIntegrity(appDir) {
+function checkInstallationIntegrity(appDir, platform) {
   const checks = [];
   const liveComposePath = path.join(appDir, "docker-compose.yml");
   const installed = existsSync(liveComposePath);
@@ -115,7 +115,11 @@ function checkInstallationIntegrity(appDir) {
 
   checks.push(check("Installation integrity", "Live compose", "ok", liveComposePath));
 
-  for (const name of PARITY_ASSETS) {
+  // T-CF28-6: grade only the files this platform is supposed to have. On
+  // darwin/linux the four Windows .ps1 scripts are correctly absent — listing
+  // them at all (as [OK] before, as a failure after the staging fix) reports
+  // on an install that does not exist.
+  for (const name of parityAssetsFor(platform)) {
     const assetPath = path.join(appDir, name);
     const present = existsSync(assetPath);
     checks.push(
@@ -311,14 +315,23 @@ function checkUpdateState(appDir, currentVersion, installed) {
 
   const updateStatePath = path.join(appDir, "updates", "state.json");
   const launcherState = readJsonSafe(updateStatePath);
+  // Audit (flows) finding 2: this reported "ok" whenever the JSON merely
+  // PARSED, never looking at current. So on the exact stranded install
+  // T-CF28-4b exists to prevent - no payload ever staged - doctor printed
+  // "Overall: OK" while the very next getculpa dead-ended with "no installed
+  // version found". Diagnostics that reassure you about the broken thing are
+  // worse than none.
+  const noPayload = launcherState !== null && (launcherState.current ?? null) === null;
   checks.push(
     check(
       "Update state",
       "Launcher self-update state",
-      launcherState ? "ok" : "info",
-      launcherState
-        ? `current=${launcherState.current ?? "n/a"}, pending=${launcherState.pending ?? "none"}, mode=${launcherState.mode ?? "n/a"}`
-        : "unknown (no update state recorded yet)",
+      launcherState === null ? "info" : noPayload ? "fail" : "ok",
+      launcherState === null
+        ? "unknown (no update state recorded yet)"
+        : noPayload
+          ? "no CLI payload is staged (current=null) - run `getculpa update`, then `getculpa`"
+          : `current=${launcherState.current}, pending=${launcherState.pending ?? "none"}, mode=${launcherState.mode ?? "n/a"}`,
     ),
   );
   return checks;
@@ -339,7 +352,7 @@ export async function doctor(opts) {
   const checks = [];
   checks.push(...checkVersionPlatform(currentVersion, platform, arch));
 
-  const integrity = checkInstallationIntegrity(appDir);
+  const integrity = checkInstallationIntegrity(appDir, platform);
   checks.push(...integrity.checks);
   checks.push(checkVendoredLauncher(vendorDir, platform));
 

package/lib/install-summary.d.mts

@@ -0,0 +1,18 @@
+import type { UpgradeClassification } from "./preflight.d.mts";
+import type { DockerState } from "./provision.d.mts";
+
+export interface InstallSummaryOptions {
+  classification: UpgradeClassification;
+  version: string;
+  previousVersion?: string | null;
+  appDir: string;
+  dockerState: DockerState;
+  imagesStaged?: boolean;
+  collectorStaged?: boolean;
+  payloadStaged?: boolean;
+  platform?: string;
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function buildInstallSummary(opts: InstallSummaryOptions): string[];

package/lib/install-summary.mjs

@@ -0,0 +1,144 @@
+// T-CF28-5 (postinstall output) + T-CF28-7 (the install-time half of the
+// Docker ask) — the lines postinstall prints when it finishes.
+//
+// Extracted from scripts/install.js's main() as a PURE function. The words
+// are the product here: the shipped 1.0.1 printed "Culpa installed
+// successfully." on a fresh Mac with no Docker, where nothing could actually
+// start. That line lived inline in a CommonJS script with no export, so no
+// test could assert it. It is a line-builder now so the claims it makes are
+// checked by tests/npm-core-install-summary.test.ts.
+//
+// TWO RULES THIS FILE EXISTS TO ENFORCE:
+//
+// 1. Never claim "ready" unless it IS ready. The founder's ruled headline is
+//    "Culpa is installed and ready." with `ready` in green — printed when
+//    Docker is genuinely usable. When Docker is missing or stopped, the
+//    headline drops to "Culpa is installed." and the Docker requirement is
+//    stated plainly. Printing the ruled line unconditionally would repeat the
+//    exact defect that created T-CF28-7.
+//
+// 2. Say what each platform will really do. postinstall CANNOT prompt
+//    (scripts/install.js:13-15 — npm installs run headless and a stdin read
+//    would hang), so this file only DETECTS and TELLS; the asking happens at
+//    first `getculpa`. win32 already ships that flow
+//    (installers/windows/launch-culpa.ps1:179-234); darwin gains it in
+//    lib/start.mjs; linux stays guidance-only, because installing a system
+//    package without explicit consent is out of bounds (the same rule
+//    lib/docker.mjs:73-79 already follows for starting the engine).
+
+import { green } from "./tty.mjs";
+
+const DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop/";
+const DOCKER_ENGINE_DOCS_URL = "https://docs.docker.com/engine/install/";
+
+function headline(classification, version, previousVersion, dockerReady, colour) {
+  switch (classification) {
+    case "upgrade":
+      return `Culpa updated: ${previousVersion} -> ${version} (staged; applies at next \`getculpa\`).`;
+    case "downgrade-package":
+      return `Culpa ${previousVersion} is already installed; this package (${version}) is older and was not applied.`;
+    case "same-version":
+    case "repair":
+      return "Culpa installation repaired.";
+    default:
+      // "fresh" — the only case the founder's ruled wording describes.
+      return dockerReady ? `Culpa is installed and ${green("ready", colour)}.` : "Culpa is installed.";
+  }
+}
+
+function inventory(appDir, imagesStaged, collectorStaged, payloadStaged) {
+  return [
+    `  Location:  ${appDir}`,
+    // T-CF28-4b: the CLI payload is the program `getculpa` actually runs. When
+    // it is missing the install is not usable at all, so this row names the
+    // one command that finishes the job rather than leaving a dead first run.
+    `  Culpa CLI: ${payloadStaged ? "installed" : "deferred - run `getculpa update` to finish"}`,
+    `  Images:    ${imagesStaged ? "staged" : "deferred to first run"}`,
+    `  Capture:   ${collectorStaged ? "collector installed" : "off (collector not installed)"}`,
+  ];
+}
+
+// Docker is MISSING. Each platform gets only what is true for it.
+function dockerMissingLines(platform) {
+  const lines = [
+    "Culpa needs Docker to run: its database and services run in containers.",
+    "Docker was not found on this machine.",
+  ];
+  if (platform === "darwin") {
+    lines.push(
+      "  Install it with:  brew install --cask docker",
+      "    Homebrew asks for your password, and you must open Docker once from",
+      "    Applications before Culpa can start - it is not a one-click install.",
+      `  Or download it:   ${DOCKER_DESKTOP_URL}`,
+      "Culpa will offer to do this for you the first time you run `getculpa`.",
+    );
+  } else if (platform === "win32") {
+    lines.push(
+      "Culpa will offer to install Docker for you the first time you run `getculpa`.",
+      `  Or download it:   ${DOCKER_DESKTOP_URL}`,
+    );
+  } else {
+    lines.push(
+      `  Install Docker Engine:  ${DOCKER_ENGINE_DOCS_URL}`,
+      "Culpa will not install system packages for you - install it yourself, then",
+      "run `getculpa`.",
+    );
+  }
+  return lines;
+}
+
+// Docker is PRESENT but the engine is stopped. Starting it is something Culpa
+// really does do on darwin (lib/docker.mjs:69-72, `open -a Docker`) and win32
+// (installers/windows/launch-culpa.ps1:236-244) — but never on linux.
+function dockerStoppedLines(platform) {
+  const lines = ["Docker is installed but its engine is not running."];
+  if (platform === "linux") {
+    lines.push("  Start it yourself, for example:  sudo systemctl start docker");
+  } else {
+    lines.push("  Culpa will start it for you when you run `getculpa`.");
+  }
+  return lines;
+}
+
+export function buildInstallSummary(opts) {
+  const {
+    classification,
+    version,
+    previousVersion = null,
+    appDir,
+    dockerState,
+    imagesStaged = false,
+    collectorStaged = false,
+    // T-CF28-4b. Fail-CLOSED, matching imagesStaged/collectorStaged above: a
+    // caller that cannot say whether the payload is there has no evidence for
+    // "ready", and this function exists precisely to stop readiness being
+    // claimed without evidence. scripts/install.js always passes the real value.
+    payloadStaged = false,
+    platform = process.platform,
+    isTTY = false,
+    env = {},
+  } = opts;
+
+  const dockerReady = dockerState === "ready";
+  // "ready" means the next command will work. A missing CLI payload breaks
+  // that just as completely as a missing Docker, so it gates the word too.
+  const ready = dockerReady && payloadStaged;
+  const colour = { isTTY, env };
+  const lines = [headline(classification, version, previousVersion, ready, colour)];
+
+  // A refused downgrade staged nothing — an inventory there would describe a
+  // state this run did not produce (lib/provision.mjs:175-183).
+  if (classification !== "downgrade-package") {
+    lines.push(...inventory(appDir, imagesStaged, collectorStaged, payloadStaged));
+  }
+
+  if (!dockerReady) {
+    lines.push("");
+    lines.push(...(dockerState === "missing" ? dockerMissingLines(platform) : dockerStoppedLines(platform)));
+  }
+
+  lines.push("");
+  lines.push(ready ? "Run:" : "Then run:");
+  lines.push("  getculpa");
+  return lines;
+}

package/lib/paths.mjs

@@ -19,6 +19,12 @@ import path from "node:path";
 // "a test set this" from "an operator set this" from inside the module, and
 // refusing a real operator's override would be a worse failure mode than
 // honoring it.
+//
+// D-108 (cli-v1.0.2): the vendored Rust launcher honors CULPA_APP_DIR too —
+// as a fallback when its own CULPA_HOME is unset (native/culpa-launcher/
+// src/home.rs). So relocating with this variable moves BOTH halves: the
+// stack/licence state this module resolves AND the launcher's
+// versions/updates state. Keep the two sides in step if either changes.
 export function getAppDir(opts = {}) {
   const env = opts.env ?? process.env;
   const platform = opts.platform ?? process.platform;