getculpa 1.0.1 → 1.0.3

package/lib/repair.mjs

@@ -1,135 +1,174 @@
-// CF20-T5 — `getculpa repair`. Re-stages missing/corrupt parity files from
-// the packaged assets, regenerates install-state.json if unreadable,
-// re-fetches a missing launcher/collectord, and does none of this
-// destructively: an EXISTING docker-compose.yml (the live pin) is never
-// touched (the edcf97f invariant this task's reviewer condition names), no
-// `docker volume` command is ever issued (data is never touched), and a
-// second run changes nothing that was already healthy (idempotent).
-//
-// Reuses lib/provision.mjs's own stageParityFiles/stageLiveComposeIfAbsent
-// (exported additively for this purpose — see that file's comment) instead
-// of re-implementing file staging here.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { stageLiveComposeIfAbsent, stageParityFiles, PARITY_ASSETS } from "./provision.mjs";
-import { fetchCollectord, fetchLauncher } from "./fetch.mjs";
-import { checkDockerEngineReachable, checkDockerPresent } from "./preflight.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.join(__dirname, "..");
-
-function readJsonSafe(filePath) {
-  try {
-    return JSON.parse(readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function detectDockerState(dockerSpawnSync) {
-  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
-  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
-  return "ready";
-}
-
-function vendorBinaryPath(vendorDir, name, platform) {
-  const exe = platform === "win32" ? ".exe" : "";
-  return path.join(vendorDir, `${name}${exe}`);
-}
-
-export async function repair(opts) {
-  const {
-    appDir,
-    currentVersion,
-    platform = process.platform,
-    vendorDir = path.join(packageRoot, "vendor"),
-    dockerSpawnSync = realSpawnSync,
-    fetchLauncherFn = fetchLauncher,
-    fetchCollectordFn = fetchCollectord,
-    log = console.log,
-  } = opts;
-
-  const actions = [];
-
-  if (!existsSync(appDir)) {
-    mkdirSync(appDir, { recursive: true });
-    actions.push(`created the missing app directory (${appDir})`);
-  }
-
-  // 1. Parity files — re-stage anything missing. stageParityFiles never
-  //    touches docker-compose.yml (it doesn't reference that name at all),
-  //    so this step alone already satisfies "never touch a live compose".
-  const missingBefore = PARITY_ASSETS.filter((name) => !existsSync(path.join(appDir, name)));
-  stageParityFiles(appDir);
-  for (const name of missingBefore) {
-    actions.push(`restored missing parity file: ${name}`);
-  }
-
-  // 2. Live compose — created ONLY if entirely absent; an existing one is
-  //    never overwritten (stageLiveComposeIfAbsent's own contract).
-  const composeCreated = stageLiveComposeIfAbsent(appDir);
-  if (composeCreated) {
-    actions.push("live docker-compose.yml was missing - recreated from the shipped culpa-compose.yml");
-  }
-
-  // 3. install-state.json — regenerate only when missing/corrupt. The
-  //    regenerated state is a conservative snapshot of what is actually on
-  //    disk right now: dockerState/collectorStaged are re-detected,
-  //    imagesStaged is set false (safe default — worst case is one extra
-  //    `docker compose pull` message at the next `getculpa`, never data
-  //    loss, mirroring deferredPullCatchUp's own contract in lib/start.mjs).
-  const existingState = readJsonSafe(path.join(appDir, "install-state.json"));
-  if (!existingState) {
-    const dockerState = detectDockerState(dockerSpawnSync);
-    const collectorStaged = existsSync(vendorBinaryPath(vendorDir, "culpa-collectord", platform));
-    const regenerated = {
-      packageVersion: currentVersion,
-      provisionedAt: new Date().toISOString(),
-      dockerState,
-      imagesStaged: false,
-      collectorStaged,
-      platform,
-    };
-    writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(regenerated, null, 2)}\n`);
-    actions.push("install-state.json was missing or unreadable - regenerated");
-  }
-
-  // 4. Launcher / collectord — re-fetch only when the vendored binary is
-  //    genuinely absent. Never re-fetches when present (idempotent, and the
-  //    task's explicit invocation-recording fact). The launcher is REQUIRED
-  //    (doctor.mjs's checkVendoredLauncher fails the same way when it's
-  //    missing) — a failed re-fetch must make repair's own result say so,
-  //    not just log and report ok:true (CF20-R review). The collector stays
-  //    optional/non-fatal: capture-off is a valid degraded state.
-  const launcherPath = vendorBinaryPath(vendorDir, "culpa-launcher", platform);
-  if (!existsSync(launcherPath)) {
-    try {
-      await fetchLauncherFn({ vendorDir });
-      actions.push("the launcher was missing - re-fetched and verified");
-    } catch (e) {
-      log(`getculpa repair: could not re-fetch the launcher (${e.message}). Run \`getculpa repair\` again once online.`);
-    }
-  }
-
-  const collectordPath = vendorBinaryPath(vendorDir, "culpa-collectord", platform);
-  if (!existsSync(collectordPath)) {
-    try {
-      await fetchCollectordFn({ vendorDir });
-      actions.push("the capture collector was missing - re-fetched and verified");
-    } catch (e) {
-      // fetchCollectord's own contract: "not published for this release yet"
-      // is an expected, non-fatal outcome (see lib/fetch.mjs) — repair must
-      // degrade the same way, never abort over an optional component.
-      log(`getculpa repair: capture collector not re-fetched (${e.message}).`);
-    }
-  }
-
-  if (actions.length === 0) log("getculpa repair: nothing to do - this install is already healthy.");
-  else for (const a of actions) log(`getculpa repair: ${a}`);
-
-  const launcherOk = existsSync(launcherPath);
-  return { ok: launcherOk, actions };
-}
+// CF20-T5 — `getculpa repair`. Re-stages missing/corrupt parity files from
+// the packaged assets, regenerates install-state.json if unreadable,
+// re-fetches a missing launcher/collectord, and does none of this
+// destructively: an EXISTING docker-compose.yml (the live pin) is never
+// touched (the edcf97f invariant this task's reviewer condition names), no
+// `docker volume` command is ever issued (data is never touched), and a
+// second run changes nothing that was already healthy (idempotent).
+//
+// Reuses lib/provision.mjs's own stageParityFiles/stageLiveComposeIfAbsent
+// (exported additively for this purpose — see that file's comment) instead
+// of re-implementing file staging here.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync as realSpawnSync } from "node:child_process";
+import {
+  collectorBinaryName,
+  parityAssetsFor,
+  stageCollectorBinary,
+  stageLiveComposeIfAbsent,
+  stageParityFiles,
+} from "./provision.mjs";
+import { fetchCollectord, fetchLauncher } from "./fetch.mjs";
+import { checkDockerEngineReachable, checkDockerPresent } from "./preflight.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectDockerState(dockerSpawnSync) {
+  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
+  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
+  return "ready";
+}
+
+function vendorBinaryPath(vendorDir, name, platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return path.join(vendorDir, `${name}${exe}`);
+}
+
+export async function repair(opts) {
+  const {
+    appDir,
+    currentVersion,
+    platform = process.platform,
+    arch = process.arch,
+    vendorDir = path.join(packageRoot, "vendor"),
+    dockerSpawnSync = realSpawnSync,
+    fetchLauncherFn = fetchLauncher,
+    fetchCollectordFn = fetchCollectord,
+    log = console.log,
+  } = opts;
+
+  const actions = [];
+
+  if (!existsSync(appDir)) {
+    mkdirSync(appDir, { recursive: true });
+    actions.push(`created the missing app directory (${appDir})`);
+  }
+
+  // 1. Parity files — re-stage anything missing. stageParityFiles never
+  //    touches docker-compose.yml (it doesn't reference that name at all),
+  //    so this step alone already satisfies "never touch a live compose".
+  // T-CF28-6: platform-scoped, or repair would restore the four Windows .ps1
+  // files provisioning deliberately skips on darwin/linux — and report each
+  // one as a "restored missing parity file" action while doing it.
+  const missingBefore = parityAssetsFor(platform).filter((name) => !existsSync(path.join(appDir, name)));
+  stageParityFiles(appDir, process.env, platform);
+  for (const name of missingBefore) {
+    actions.push(`restored missing parity file: ${name}`);
+  }
+
+  // 2. Live compose — created ONLY if entirely absent; an existing one is
+  //    never overwritten (stageLiveComposeIfAbsent's own contract).
+  const composeCreated = stageLiveComposeIfAbsent(appDir);
+  if (composeCreated) {
+    actions.push("live docker-compose.yml was missing - recreated from the shipped culpa-compose.yml");
+  }
+
+  // 3. install-state.json — regenerate only when missing/corrupt. The
+  //    regenerated state is a conservative snapshot of what is actually on
+  //    disk right now: dockerState/collectorStaged are re-detected,
+  //    imagesStaged is set false (safe default — worst case is one extra
+  //    `docker compose pull` message at the next `getculpa`, never data
+  //    loss, mirroring deferredPullCatchUp's own contract in lib/start.mjs).
+  const existingState = readJsonSafe(path.join(appDir, "install-state.json"));
+  if (!existingState) {
+    const dockerState = detectDockerState(dockerSpawnSync);
+    // Review of 0e4b2e2: this derived collectorStaged from the PACKAGE
+    // vendor dir, which is not what culpa-collector.ps1:35 reads. It could
+    // therefore regenerate install-state.json saying capture was staged
+    // while the app dir held no collector at all — the same false positive
+    // T-CF29-8 removed from provision(). One invariant, both writers.
+    const collectorStaged = existsSync(path.join(appDir, collectorBinaryName(platform, arch)));
+    const regenerated = {
+      packageVersion: currentVersion,
+      provisionedAt: new Date().toISOString(),
+      dockerState,
+      imagesStaged: false,
+      collectorStaged,
+      platform,
+    };
+    writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(regenerated, null, 2)}\n`);
+    actions.push("install-state.json was missing or unreadable - regenerated");
+  }
+
+  // 4. Launcher / collectord — re-fetch only when the vendored binary is
+  //    genuinely absent. Never re-fetches when present (idempotent, and the
+  //    task's explicit invocation-recording fact). The launcher is REQUIRED
+  //    (doctor.mjs's checkVendoredLauncher fails the same way when it's
+  //    missing) — a failed re-fetch must make repair's own result say so,
+  //    not just log and report ok:true (CF20-R review). The collector stays
+  //    optional/non-fatal: capture-off is a valid degraded state.
+  const launcherPath = vendorBinaryPath(vendorDir, "culpa-launcher", platform);
+  if (!existsSync(launcherPath)) {
+    try {
+      await fetchLauncherFn({ vendorDir });
+      actions.push("the launcher was missing - re-fetched and verified");
+    } catch (e) {
+      log(`getculpa repair: could not re-fetch the launcher (${e.message}). Run \`getculpa repair\` again once online.`);
+    }
+  }
+
+  const collectordPath = vendorBinaryPath(vendorDir, "culpa-collectord", platform);
+  if (!existsSync(collectordPath)) {
+    try {
+      await fetchCollectordFn({ vendorDir });
+      actions.push("the capture collector was missing - re-fetched and verified");
+    } catch (e) {
+      // fetchCollectord's own contract: "not published for this release yet"
+      // is an expected, non-fatal outcome (see lib/fetch.mjs) — repair must
+      // degrade the same way, never abort over an optional component.
+      log(`getculpa repair: capture collector not re-fetched (${e.message}).`);
+    }
+  }
+
+  // Review of 0e4b2e2: re-fetching only refilled the PACKAGE vendor dir, so
+  // "re-fetched and verified" claimed a repair that left capture exactly as
+  // broken as it found it. The app-dir copy is the one that matters.
+  const appCollector = path.join(appDir, collectorBinaryName(platform, arch));
+  if (!existsSync(appCollector) && stageCollectorBinary({ appDir, vendorDir, platform, arch })) {
+    actions.push("the capture collector was missing from the app directory - staged it");
+  }
+
+  // The state file may have been regenerated BEFORE the staging above, so
+  // correct it to what is now true rather than leaving a stale answer.
+  const statePath = path.join(appDir, "install-state.json");
+  const finalState = readJsonSafe(statePath);
+  const collectorTruth = existsSync(appCollector);
+  // Review of 4e45f81: this used to correct the file and say NOTHING, so a
+  // run that really did change something reported "nothing to do - this
+  // install is already healthy". Same class of false claim the rest of this
+  // commit removes, just relocated into the action log.
+  if (finalState && finalState.collectorStaged !== collectorTruth) {
+    actions.push(
+      `install-state.json claimed capture was ${finalState.collectorStaged ? "staged" : "absent"} - corrected to match the app directory`,
+    );
+    writeFileSync(statePath, `${JSON.stringify({ ...finalState, collectorStaged: collectorTruth }, null, 2)}\n`);
+  }
+
+  if (actions.length === 0) log("getculpa repair: nothing to do - this install is already healthy.");
+  else for (const a of actions) log(`getculpa repair: ${a}`);
+
+  const launcherOk = existsSync(launcherPath);
+  return { ok: launcherOk, actions };
+}

package/lib/start.d.mts

@@ -28,6 +28,8 @@ export interface StartOptions {
   openBrowser?: (url: string) => void;
   isTTY?: boolean;
   delegateWindowsLaunch?: (appDir: string) => { ok: boolean; output?: string };
+  isInteractive?: boolean;
+  askYesNo?: (question: string) => Promise<boolean>;
 }
 
 export interface StartResult {

package/lib/start.mjs

@@ -34,12 +34,14 @@ import {
   preMigrationBackup,
   probeHealth,
   resolveBackupBaseline,
+  installDockerDarwin,
   startEngineIfPossible,
   waitForDockerEngine,
   waitForHealth,
   waitForPgReady,
 } from "./docker.mjs";
 import { checkDockerPresent, compareVersions, parsePinnedServerVersion } from "./preflight.mjs";
+import { askYesNo as realAskYesNo } from "./tty.mjs";
 
 export const STAGES = Object.freeze({
   CHECK_INSTALLATION: "CHECK_INSTALLATION",
@@ -186,6 +188,85 @@ async function runVersionGuards({ appDir, liveCompose, spawnSync, env, log, warn
   return { pinnedVersion };
 }
 
+// T-CF28-7 — "The install fails to ask for docker and other dependencies. IT
+// MUST ASK AND INSTALL THESE" (founder). This is the ASK half; the DETECT half
+// runs at npm-install time (lib/install-summary.mjs), because postinstall
+// cannot prompt (scripts/install.js:13-15).
+//
+// Reached only when Docker is genuinely absent on a non-win32 platform. Every
+// branch ends in a fail() — even a SUCCESSFUL install, because Docker Desktop
+// still needs one manual launch before its engine answers. That mirrors
+// launch-culpa.ps1:233, which likewise stops after installing rather than
+// pretending the stack is coming up.
+const DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop/";
+const DOCKER_ENGINE_DOCS_URL = "https://docs.docker.com/engine/install/";
+const DOCKER_MISSING = "Culpa couldn't start: Docker is not installed.";
+
+// The consent text IS the disclosure. It names the exact command, that a
+// password will be asked for, and that a manual first launch is still
+// required — so nobody agrees to a "one-click install" that isn't one.
+const DARWIN_CONSENT_QUESTION =
+  "Culpa needs Docker to run, and it was not found on this machine.\n" +
+  "Install it now with `brew install --cask docker`?\n" +
+  "  Homebrew will ask for your password, and afterwards you must open Docker once\n" +
+  "  from Applications - this cannot be a fully hands-off install.\n" +
+  "  Nothing is downloaded unless you answer yes.\n" +
+  "Install Docker now? (y/N) ";
+
+async function offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive }) {
+  // linux: installing a system package without explicit consent is out of
+  // bounds — the same rule startEngineIfPossible already follows for merely
+  // STARTING the engine (docker.mjs:73-79). Guidance only, and no prompt: a
+  // yes here could not be honoured anyway.
+  if (platform !== "darwin") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install Docker Engine (${DOCKER_ENGINE_DOCS_URL}), then run \`getculpa\` again. Culpa will not install system packages for you.`,
+    );
+  }
+
+  if (!isInteractive) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Culpa runs its database and services in containers. Install it with \`brew install --cask docker\` (or download it from ${DOCKER_DESKTOP_URL}), open Docker once, then run \`getculpa\` again.`,
+    );
+  }
+
+  if (!(await askYesNo(DARWIN_CONSENT_QUESTION))) {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `The Docker install was not authorized, so nothing was installed and nothing was changed. Install it yourself with \`brew install --cask docker\` or from ${DOCKER_DESKTOP_URL}, then run \`getculpa\` again.`,
+    );
+  }
+
+  log("==> Installing Docker Desktop with Homebrew (brew install --cask docker)");
+  const outcome = installDockerDarwin(spawnSync);
+
+  if (outcome === "no-brew") {
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew is not available, so Docker could not be installed automatically. Nothing was changed. Download Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  if (outcome !== "installed") {
+    const code = outcome.replace(/^failed:/, "");
+    return fail(
+      STAGES.CHECK_DOCKER,
+      DOCKER_MISSING,
+      `Homebrew could not install Docker (exit code ${code}). Nothing else was changed. Install Docker Desktop from ${DOCKER_DESKTOP_URL}, open it once, then run \`getculpa\` again.`,
+    );
+  }
+  return fail(
+    STAGES.CHECK_DOCKER,
+    "Docker was installed. Culpa has not started yet.",
+    "Open Docker once from Applications and wait for it to finish starting, then run `getculpa` again.",
+  );
+}
+
 function maybeOpenBrowser({ env, isTTY, openBrowser }) {
   if (!isTTY) return;
   if (env.CULPA_NO_BROWSER) return;
@@ -334,10 +415,15 @@ async function runPosixStateMachine({ appDir, liveCompose, platform, spawnSync,
     };
   }
 
-  // No collectord build/staging exists for macOS/Linux yet (task scope) —
-  // degrade honestly rather than fail the whole launch over capture.
+  // V102 T-V102-14 (M4, D-113): the old line here said "no collector build
+  // ships for macOS/Linux yet" — verified FALSE on real hardware (the arm64
+  // collectord ships, was staged executable, install-state recorded
+  // collectorStaged: true). What IS true: the collector is not auto-started
+  // on this platform yet, while the server-side coding-tool log sweep works
+  // (proven live on the Mac: calls landed unattended, ~45 min cadence). Say
+  // exactly that — neither direction of the old overclaim.
   stagesRun.push(STAGES.START_CULPA);
-  log("getculpa: capture is OFF on this platform for now (no collector build ships for macOS/Linux yet) - everything else works normally.");
+  log("getculpa: your local coding-tool usage is captured by the built-in log sweep. The production traffic collector is not started automatically on this platform yet - everything else works normally.");
 
   stagesRun.push(STAGES.OPEN_UI);
   if (pinnedVersion) writeFileSync(path.join(appDir, "last-boot-version.txt"), `${pinnedVersion}\n`);
@@ -359,6 +445,11 @@ export async function start(opts) {
     openBrowser = defaultOpenBrowser,
     isTTY = process.stdout.isTTY,
     delegateWindowsLaunch = defaultDelegateWindowsLaunch,
+    // T-CF28-7: consent needs BOTH ends of the terminal — stdin to read the
+    // answer, stdout for the question. isTTY above is stdout-only (it gates
+    // the browser open), so it cannot stand in for this.
+    isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    askYesNo = (question) => realAskYesNo(question, { isInteractive }),
   } = opts;
 
   const stagesRun = [STAGES.CHECK_INSTALLATION];
@@ -369,10 +460,11 @@ export async function start(opts) {
 
   stagesRun.push(STAGES.CHECK_DOCKER);
   if (platform !== "win32" && !checkDockerPresent(spawnSync)) {
-    return {
-      ...fail(STAGES.CHECK_DOCKER, "Culpa couldn't start Docker.", "Install Docker (https://docs.docker.com/get-docker/), then run `getculpa` again."),
-      stagesRun,
-    };
+    // T-CF28-7: was a dead end with a bare URL. Still a hard gate — nothing
+    // below can work without Docker — but on darwin it now offers to install
+    // it first. win32 is deliberately excluded (see this file's header):
+    // launch-culpa.ps1:179-234 owns that flow and must not be short-circuited.
+    return { ...(await offerDockerInstall({ platform, spawnSync, log, askYesNo, isInteractive })), stagesRun };
   }
 
   stagesRun.push(STAGES.IDEMPOTENCY_CHECK);

package/lib/tty.d.mts

@@ -0,0 +1,18 @@
+export interface ColourOptions {
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function colourEnabled(opts?: ColourOptions): boolean;
+export function green(text: string, opts?: ColourOptions): string;
+
+export interface AskYesNoOptions {
+  isInteractive?: boolean;
+  createInterface?: (opts: { input: unknown; output: unknown }) => {
+    question: (q: string, cb: (answer: string) => void) => void;
+    once: (event: string, cb: () => void) => void;
+    close: () => void;
+  };
+}
+
+export function askYesNo(question: string, opts?: AskYesNoOptions): Promise<boolean>;

package/lib/tty.mjs

@@ -0,0 +1,58 @@
+// T-CF28-5 / T-CF28-7 — terminal helpers: colour, and the yes/no consent
+// prompt. Both are gated on there actually being a human attached.
+//
+// The founder's ruling for the postinstall message is "Culpa is installed and
+// ready." with "ready" in GREEN. Colour is emitted ONLY when the destination
+// is a real terminal and NO_COLOR is unset: `npm i -g` output is routinely
+// piped, redirected to a log, or captured by CI, and a raw ANSI escape there
+// is visible garbage in the one place a human later reads to find out what
+// went wrong. Plain text is the fallback, never a degraded message.
+//
+// isTTY and env are parameters rather than reads of the live process, for the
+// same reason lib/start.mjs:360 and lib/uninstall.mjs:77 inject theirs: a test
+// asserts both branches deliberately instead of depending on how the runner
+// happens to be attached.
+//
+// NO_COLOR follows the https://no-color.org convention: any value, including
+// an empty string, disables colour. Only an ABSENT variable allows it.
+
+// String.fromCharCode(27) rather than a literal escape: this file is edited by
+// tools that have silently converted the six-character sequence into a raw
+// control byte, which is invisible in review and breaks on the next edit.
+const ESC = String.fromCharCode(27);
+const GREEN = `${ESC}[32m`;
+const DEFAULT_FG = `${ESC}[39m`;
+
+export function colourEnabled({ isTTY, env = {} } = {}) {
+  if (!isTTY) return false;
+  return env.NO_COLOR === undefined;
+}
+
+export function green(text, opts = {}) {
+  if (!colourEnabled(opts)) return text;
+  return `${GREEN}${text}${DEFAULT_FG}`;
+}
+
+// T-CF28-7 — explicit consent before Culpa installs anything on the user's
+// machine. Same safety posture as lib/uninstall.mjs:61-69: a non-interactive
+// caller is never prompted and always gets NO, so a scripted or CI run can
+// neither hang on a stdin read nor have an install decided for it by default.
+// The caller supplies the whole question, including the "(y/N)" — the wording
+// of what is about to happen is part of the consent, not decoration.
+export async function askYesNo(question, opts = {}) {
+  const { isInteractive = false, createInterface } = opts;
+  if (!isInteractive) return false;
+  const { createInterface: realCreateInterface } = await import("node:readline");
+  const rl = (createInterface ?? realCreateInterface)({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => {
+    // EOF (Ctrl-D, or a stdin that ends mid-prompt) fires `close` and NEVER
+    // invokes question()'s callback. Without this listener the promise stays
+    // pending and `getculpa` hangs forever at the consent prompt with no
+    // error and no way out. An unanswered question is a NO, exactly as the
+    // non-interactive path above already decides.
+    rl.once("close", () => resolve(""));
+    rl.question(question, resolve);
+  });
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}

package/lib/uninstall.mjs

@@ -62,12 +62,36 @@ 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;
@@ -82,13 +106,28 @@ export async function uninstall(opts = {}) {
     if (!ok) console.error("getculpa: uninstall did not complete cleanly - see the output above.");
   } else {
     ok = composeDown(appDir, spawnSync);
-    removeShortcutEquivalents(homedir);
-    const wipe = await promptPgdataRemoval(createInterface, isTTY);
-    if (wipe) {
-      spawnSync("docker", ["volume", "rm", "culpa_pgdata"], { stdio: "inherit" });
-      console.log("Data volume removed.");
+    // 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 {
-      console.log("Data kept (volume culpa_pgdata). Reinstalling later will find it again.");
+      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);
     }
   }