getculpa 1.0.1 → 1.0.3

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.3 PUBLISHED AND SIGNED (2026-08-20) ─────────
 # 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.3
 # 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.3
     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.3
     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/bin/getculpa.js

@@ -121,21 +121,49 @@ async function runUninstall() {
 
 async function main(argv) {
   const [cmd] = argv;
-  if (cmd === undefined || cmd === "start") return runStart();
-  if (cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP);
-    return process.exit(0);
-  }
   if (cmd === "-v" || cmd === "--version") {
     printVersion();
     return process.exit(0);
   }
+  // V102 T-V102-04 (M8, D-113): `getculpa uninstall --help` once EXECUTED the
+  // uninstall — the help flag was only recognised as argv[0]. All help and
+  // uninstall-consent decisions now happen here, BEFORE anything is imported
+  // or spawned. Passthrough verbs fall through untouched (the launcher owns
+  // their help).
+  const { decideDispatch, verbHelp } = await import("../lib/dispatch.mjs");
+  const decision = decideDispatch(argv, {
+    isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
+  });
+  if (decision.kind === "help") {
+    console.log(decision.verb === null ? HELP : verbHelp(decision.verb));
+    return process.exit(0);
+  }
+  if (decision.kind === "refuse-uninstall") {
+    console.error(
+      "getculpa: uninstall removes Culpa's containers and network. Run it from a terminal to confirm interactively, or pass --yes to consent from a script. Nothing was changed.",
+    );
+    return process.exit(1);
+  }
+  if (decision.kind === "confirm-uninstall") {
+    const { askYesNo } = await import("../lib/tty.mjs");
+    const consented = await askYesNo(
+      "This stops and removes Culpa's containers and network (recorded cost data is kept unless you separately confirm deleting it). Continue? (y/N) ",
+      { isInteractive: true },
+    );
+    if (!consented) {
+      console.log("getculpa: uninstall cancelled. Nothing was changed.");
+      return process.exit(0);
+    }
+    return runUninstall();
+  }
+  if (decision.kind === "run-uninstall") return runUninstall();
+  if (cmd === undefined || cmd === "start") return runStart();
   if (cmd === "stop") return runStop();
   if (cmd === "restart") return runRestart();
   if (cmd === "status") return runStatus();
   if (cmd === "doctor") return runDoctor();
   if (cmd === "repair") return runRepair();
-  if (cmd === "uninstall") return runUninstall();
+  // `uninstall` never reaches here — every argv shape is decided above.
   // scan / connect / update / config / anything unrecognized: the launcher
   // owns USAGE and exit-code semantics for its own surface, same as culpa.js.
   return runLauncherPassthrough(argv);

package/lib/bootstrap.d.mts

@@ -0,0 +1,29 @@
+// 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;
+
+export type PayloadState = "installed" | "staged" | "missing";
+
+export function readPayloadState(opts?: { env?: Record<string, string | undefined> }): PayloadState;

package/lib/bootstrap.mjs

@@ -0,0 +1,97 @@
+// 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, readFileSync } from "node:fs";
+import path from "node:path";
+import { getAppDir } from "./paths.mjs";
+
+// 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;
+}
+
+/** V102 T-V102-15 (M3, D-113): what the launcher's updates/state.json
+ *  actually says — EVIDENCE for the install summary, never the updater's
+ *  exit code (which claimed "Culpa CLI: installed" on a Mac whose state read
+ *  current: null while doctor FAILed the same install).
+ *  "installed": current is set. "staged": pending only — activates at the
+ *  next `getculpa`. "missing": neither, no file, or unreadable.
+ *  NB (review-3): getAppDir honours CULPA_APP_DIR but not CULPA_HOME — the
+ *  known-open T-CF28-3c asymmetry (see paths.mjs:17-27 and open-loops
+ *  §T-CF28-3c). A CULPA_HOME-only relocation therefore reads the default
+ *  location and reports "missing" — underselling, never a false claim. */
+export function readPayloadState(opts = {}) {
+  const { env = process.env } = opts;
+  try {
+    const raw = readFileSync(path.join(getAppDir({ env }), "updates", "state.json"), "utf8");
+    const state = JSON.parse(raw);
+    if (typeof state.current === "string" && state.current.length > 0) return "installed";
+    if (typeof state.pending === "string" && state.pending.length > 0) return "staged";
+    return "missing";
+  } catch {
+    return "missing"; // absent or corrupt: no evidence, no claim
+  }
+}
+
+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/dispatch.d.mts

@@ -0,0 +1,12 @@
+export type DispatchDecision =
+  | { kind: "help"; verb: string | null }
+  | { kind: "refuse-uninstall" }
+  | { kind: "confirm-uninstall" }
+  | { kind: "run-uninstall" }
+  | { kind: "dispatch" };
+
+export const LOCAL_VERBS: string[];
+
+export function verbHelp(verb: string): string;
+
+export function decideDispatch(argv: string[], opts?: { isTTY?: boolean }): DispatchDecision;

package/lib/dispatch.mjs

@@ -0,0 +1,59 @@
+// V102 T-V102-04 (M8/P0-2, D-113) — dispatch decisions for bin/getculpa.js.
+//
+// Executed on real hardware: `getculpa uninstall --help` stopped and removed
+// all three containers and the network, because the router recognised a help
+// flag only as argv[0] and dispatched on argv[0] without reading argv[1].
+// `stop`, `restart` and `repair` shared the shape. The rule now: for every
+// verb THIS bin routes locally, a help flag anywhere in argv decides HELP
+// before anything is imported or spawned. Passthrough verbs (scan, connect,
+// update, config, …) keep their argv untouched — the vendored launcher owns
+// their help and exit-code semantics.
+//
+// Pure decisions, no side effects: the bin acts on the returned kind, and the
+// facts in tests/npm-cli-dispatch.test.ts assert the decisions directly.
+
+const HELP_FLAGS = new Set(["-h", "--help", "help"]);
+
+/** Every verb bin/getculpa.js routes locally (everything else passes through). */
+export const LOCAL_VERBS = ["start", "stop", "restart", "status", "doctor", "repair", "uninstall"];
+const LOCAL = new Set(LOCAL_VERBS);
+
+const VERB_HELP = {
+  start: "Start (or resume) the Culpa stack. Data is kept.",
+  stop: "Stop the running stack. Containers stop, nothing is removed, all data is kept. Start again with `getculpa`.",
+  restart: "Stop, then start the stack. No data is touched.",
+  status: "Show install/docker/stack/license status. Read-only.",
+  doctor: "Diagnose this install. Read-only.",
+  repair: "Re-stage missing or corrupt install files. No data touched.",
+  uninstall:
+    "Stop and REMOVE Culpa's containers and network. Asks for confirmation first; pass --yes to consent from a script (a non-interactive run without --yes refuses). Recorded cost data is kept unless you separately confirm deleting it.",
+};
+
+/** One verb's help block, prefixed with its usage line. */
+export function verbHelp(verb) {
+  const text = VERB_HELP[verb] ?? "No help recorded for this verb.";
+  return `Usage: getculpa ${verb}\n\n  ${text}\n`;
+}
+
+/**
+ * Decide what argv means BEFORE any dispatch. Returns one of:
+ *   { kind: "help", verb: string | null }  print help (general when verb null)
+ *   { kind: "refuse-uninstall" }           non-interactive, no --yes: refuse
+ *   { kind: "confirm-uninstall" }          interactive: ask, then uninstall
+ *   { kind: "run-uninstall" }              consent given via --yes/-y
+ *   { kind: "dispatch" }                   fall through to the existing router
+ */
+export function decideDispatch(argv, { isTTY = false } = {}) {
+  const [cmd] = argv;
+  if (cmd === undefined) return { kind: "dispatch" };
+  if (HELP_FLAGS.has(cmd)) return { kind: "help", verb: null };
+  if (LOCAL.has(cmd) && argv.slice(1).some((a) => HELP_FLAGS.has(a))) {
+    return { kind: "help", verb: cmd };
+  }
+  if (cmd === "uninstall") {
+    if (argv.includes("--yes") || argv.includes("-y")) return { kind: "run-uninstall" };
+    if (!isTTY) return { kind: "refuse-uninstall" };
+    return { kind: "confirm-uninstall" };
+  }
+  return { kind: "dispatch" };
+}

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(
@@ -240,9 +244,24 @@ async function checkHealth(fetchFn, running) {
 }
 
 function scanLicenseKeyPresence(env, appDir) {
-  if (env.CULPA_LICENSE_KEY) return true;
+  // CodeRabbit PR#19 [6]: "   " is truthy — trim before believing the env
+  if ((env.CULPA_LICENSE_KEY ?? "").trim() !== "") return true;
   const compose = readTextSafe(path.join(appDir, "docker-compose.yml"));
-  return /CULPA_LICENSE_KEY/.test(compose);
+  // V102 T-V102-15 (M6/W3, D-113): the old bare /CULPA_LICENSE_KEY/ regex
+  // matched a COMMENT line in the shipped compose, so doctor reported
+  // "[OK] present (redacted)" with no key set — on real hardware, both
+  // platforms, while `status` said "License: unknown" beside it. Only an
+  // uncommented env ENTRY carrying a non-empty value counts.
+  return compose.split(/\r?\n/).some((line) => {
+    const t = line.trim();
+    if (t.startsWith("#")) return false;
+    const m = /^-?\s*["']?CULPA_LICENSE_KEY["']?\s*[:=]\s*(.+)$/.exec(t);
+    if (m === null) return false;
+    // PR#19 [6]: "KEY: # configured elsewhere" is YAML for an EMPTY value
+    // plus a trailing comment — never a configured key
+    const value = m[1].trim().replace(/^["']|["']$/g, "").trim();
+    return value.length > 0 && !value.startsWith("#");
+  });
 }
 
 // Extracts ONLY configured/state/plan — even if the (possibly stubbed, in
@@ -311,14 +330,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 +367,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;
+  payloadState?: "installed" | "staged" | "missing";
+  platform?: string;
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function buildInstallSummary(opts: InstallSummaryOptions): string[];