failproofai 1.0.0-beta.6 → 1.0.0-beta.8

package/src/hooks/daemon-service.ts

@@ -94,7 +94,25 @@ export function setDaemonConfigured(value: boolean, installedVersion?: string):
   }
 }
 
-export type DaemonServiceStatus = "running" | "stopped" | "not-installed" | "unsupported-platform";
+export type DaemonServiceStatus =
+  | "running"
+  | "stopped"
+  /**
+   * Installed, but systemd evaluated its `ConditionPathExists=` and refused to
+   * start it — the daemon binary or the worker script is gone.
+   *
+   * Deliberately its own state rather than folded into "stopped". "Stopped" is
+   * ambiguous on purpose (a restart in flight looks identical), which is why
+   * nothing is allowed to act destructively on it. A failed condition carries
+   * no such ambiguity: systemd has already decided this unit will not run, and
+   * will keep deciding that at every boot until the missing path returns. That
+   * is provable enough to clear `daemonConfigured` on, and leaving it
+   * indistinguishable from a transient stop is what kept a machine denying
+   * every tool call with no explanation.
+   */
+  | "condition-failed"
+  | "not-installed"
+  | "unsupported-platform";
 
 /** Linux + macOS only, per the plan's platform scope — full stop. */
 export function isDaemonSupportedPlatform(): boolean {
@@ -261,6 +279,28 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The raw, unquoted path to the worker script the service will run — the same
+ * file `resolveWorkerCommand` builds its shell command around.
+ *
+ * It exists separately because the unit needs the path as a PATH (for
+ * `ConditionPathExists=`), not as a shell word, and recovering one from the
+ * other means unparsing POSIX quoting for a value we already had.
+ *
+ * Returns null when `FAILPROOFAI_WORKER_CMD` is set: that value is an arbitrary
+ * shell command — a wrapper script, an interpreter with flags, `exec`ing
+ * something else entirely — and guessing which token in it is "the file that
+ * must exist" would gate the service on a path nobody promised. An absent
+ * condition is the correct answer to a question we cannot answer.
+ */
+export function workerScriptPath(): string | null {
+  if (process.env.FAILPROOFAI_WORKER_CMD) return null;
+  const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT;
+  if (!packageRoot) return null;
+  const workerScript = resolve(packageRoot, "dist", "worker.mjs");
+  return existsSync(workerScript) ? workerScript : null;
+}
+
 /**
  * The environment the service definition carries, built once so the systemd
  * and launchd renderers cannot drift apart — a variable added to one and not
@@ -450,8 +490,16 @@ export function primeElevation(): boolean {
   }
 }
 
-/** True when privileged commands can run without prompting for a password. */
-function canElevate(): boolean {
+/**
+ * True when privileged commands can run without prompting for a password.
+ *
+ * Exported because onboarding re-checks it: `needs_root` is the most common
+ * reason setup aborts, and it is the one most likely to stop being true (the
+ * user gets sudo rights, or primes their timestamp in another terminal). One
+ * `sudo -n true`, no prompt, milliseconds — and never on the hook path, which
+ * does not reach the first-run gate at all.
+ */
+export function canElevate(): boolean {
   if (typeof process.getuid === "function" && process.getuid() === 0) return true;
   try {
     execFileSync("sudo", ["-n", "true"], { stdio: "ignore", timeout: SERVICE_CMD_TIMEOUT_MS });
@@ -568,10 +616,58 @@ export function systemdUnitContents(
   const user = assertUnitSafe(serviceUser(), "User");
   assertUnitSafe(binaryPath, "ExecStart");
   assertUnitSafe(homedir(), "HOME");
+
+  // Gate the unit on the two files it cannot run without, so that an install
+  // which is no longer there STOPS rather than thrashes.
+  //
+  // `npm rm -g failproofai` is the case this is for, and npm runs no uninstall
+  // script — see the note on `failproofai uninstall`. It deletes the package,
+  // which takes `dist/worker.mjs` with it, while the daemon binary under
+  // ~/.failproofai survives. Without a condition systemd keeps a daemon alive
+  // whose worker cannot spawn; with a deleted BINARY it is worse, because
+  // ExecStart fails 203/EXEC under `Restart=on-failure` and cycles until it
+  // trips the start-limit and latches into "start request repeated too
+  // quickly" — a state that then refuses a legitimate restart later.
+  //
+  // A failed condition is not a failure: systemd SKIPS the job, leaves the unit
+  // inactive, and `systemctl status` names the exact path that was missing.
+  // That turns an unexplained crash-loop into a one-line diagnosis, and
+  // `daemonServiceStatus()` reads it back as `condition-failed` so the next CLI
+  // command can clear `daemonConfigured` instead of leaving the machine denying
+  // every tool call.
+  //
+  // This deliberately does NOT soften the hook path's fail-closed deny. A
+  // machine that was configured to require the daemon still denies while the
+  // daemon is absent — being skipped by systemd is not consent to stop
+  // enforcing. It shortens how long that lasts and explains why.
+  // Only paths that EXIST right now are gated on, and that filter is load-
+  // bearing rather than belt-and-braces.
+  //
+  // `binaryPath` is an ExecStart value, not necessarily a bare path: systemd
+  // accepts arguments there, and `FAILPROOFAI_DAEMON_BINARY` is documented as
+  // "someone named a binary explicitly" — this repo's own systemd tests set it
+  // to `/usr/bin/sleep infinity`. `ConditionPathExists=` takes a PATH, so
+  // gating on that string looks for a file literally named "sleep infinity",
+  // never finds it, and skips a unit that would have run perfectly. Splitting
+  // on whitespace to recover the binary is worse, because a path may legally
+  // contain spaces and there is no way to tell the two apart from here.
+  //
+  // Existence at render time answers it without guessing: a real binary is on
+  // disk when its unit is written (installDaemonService just put it there), and
+  // a command-with-arguments is not. Same rule the worker script already
+  // follows — never gate on a path that is not there, or the freshly installed
+  // unit skips on its very first start.
+  const conditionPaths = [binaryPath, workerScriptPath()].filter(
+    (p): p is string => typeof p === "string" && existsSync(p),
+  );
+  const conditionLines = conditionPaths
+    .map((p) => `ConditionPathExists=${assertUnitSafe(p, "ConditionPathExists")}\n`)
+    .join("");
+
   return `[Unit]
 Description=failproofai background daemon (failproofaid) for ${user}
 After=network.target
-
+${conditionLines}
 [Service]
 Type=simple
 User=${user}
@@ -790,6 +886,15 @@ export async function installDaemonService(): Promise<DaemonInstallResult> {
  */
 const DAEMON_PROBE_TIMEOUT_MS = 5_000;
 
+/**
+ * How long the probe keeps waiting for the socket to come up before calling the
+ * daemon unreachable. Generous on purpose: this runs once, from an interactive
+ * setup command, and the cost of being impatient is aborting setup at a machine
+ * whose daemon is merely still starting.
+ */
+const DAEMON_PROBE_READY_TIMEOUT_MS = 10_000;
+const DAEMON_PROBE_RETRY_MS = 150;
+
 /**
  * Ask the daemon to evaluate a real hook, end to end.
  *
@@ -810,26 +915,81 @@ const DAEMON_PROBE_TIMEOUT_MS = 5_000;
  * policy would deny and records no tool decision, so probing cannot itself
  * change what the machine does.
  */
-export async function probeDaemonEndToEnd(): Promise<boolean> {
+export type DaemonProbe =
+  | { ok: true }
+  | {
+      ok: false;
+      /**
+       * `unreachable` — nothing ever accepted a connection on the socket.
+       * `worker`      — the daemon accepted a connection but could not answer a
+       *                 hook, which is the worker failing to run.
+       *
+       * Kept apart because the remedies are different, and because reporting
+       * "your worker will not start" at someone whose worker is fine sends them
+       * to inspect a healthy process. `DaemonFailure` cannot make this
+       * distinction: it reports `unreachable` for a refused connection AND for
+       * a request that was accepted and never answered.
+       */
+      reason: "unreachable" | "worker";
+    };
+
+/**
+ * Ask the daemon to evaluate a real hook, end to end.
+ *
+ * The thing this catches that nothing else did: a unit that is *running* while
+ * the worker behind it cannot start. `ExecStart` bakes in `process.execPath`
+ * and an absolute `dist/worker.mjs`, so an `nvm uninstall 20` leaves a service
+ * systemd reports as perfectly active and a worker that dies on every spawn.
+ *
+ * **Why this retries.** It is called moments after `systemctl enable --now`, and
+ * a `Type=simple` unit is reported ACTIVE the instant systemd forks it — before
+ * the daemon has bound its socket. A single attempt therefore raced the bind
+ * and, because the hook path's connect budget is deliberately 150ms, lost that
+ * race on any loaded machine. Setup then aborted with "its worker process could
+ * not be run" at a daemon that was seconds away from serving happily — the
+ * worker had already logged that it was listening. Waiting for the socket is
+ * the fix; relaxing the 150ms is NOT, because that budget is what keeps a dead
+ * daemon from adding latency to every tool call on the hook path.
+ */
+export async function probeDaemon(): Promise<DaemonProbe> {
   try {
-    const { attemptDaemonHook } = await import("./daemon-client");
-    const attempt = await attemptDaemonHook(
-      {
-        hookEvent: "SessionStart",
-        cli: "claude",
-        stdin: JSON.stringify({ hook_event_name: "SessionStart", source: "failproofai-health-probe" }),
-      },
-      { responseTimeoutMs: DAEMON_PROBE_TIMEOUT_MS },
-    );
-    // A protocol mismatch is a REACHABLE daemon of the wrong vintage. The hook
-    // path already falls back rather than denying for that case, so it is not
-    // the lockout this probe exists to find.
-    return attempt.ok || attempt.failure === "protocol-mismatch";
+    const { attemptDaemonHook, daemonAcceptsConnections } = await import("./daemon-client");
+    const deadline = Date.now() + DAEMON_PROBE_READY_TIMEOUT_MS;
+    let everConnected = false;
+
+    for (;;) {
+      if (await daemonAcceptsConnections()) {
+        everConnected = true;
+        const attempt = await attemptDaemonHook(
+          {
+            hookEvent: "SessionStart",
+            cli: "claude",
+            stdin: JSON.stringify({
+              hook_event_name: "SessionStart",
+              source: "failproofai-health-probe",
+            }),
+          },
+          { responseTimeoutMs: DAEMON_PROBE_TIMEOUT_MS },
+        );
+        // A protocol mismatch is a REACHABLE daemon of the wrong vintage, which
+        // is a version problem rather than the lockout this probe exists to
+        // find. It is reported, and acted on, elsewhere.
+        if (attempt.ok || attempt.failure === "protocol-mismatch") return { ok: true };
+      }
+      if (Date.now() >= deadline) break;
+      await new Promise((r) => setTimeout(r, DAEMON_PROBE_RETRY_MS));
+    }
+    return { ok: false, reason: everConnected ? "worker" : "unreachable" };
   } catch {
-    return false;
+    return { ok: false, reason: "unreachable" };
   }
 }
 
+/** Boolean form, for callers that only branch on healthy/not. */
+export async function probeDaemonEndToEnd(): Promise<boolean> {
+  return (await probeDaemon()).ok;
+}
+
 /**
  * Waits for the service to report running, then re-checks after a settle
  * window (see `SERVICE_SETTLE_MS`) so a daemon that dies at startup doesn't
@@ -1283,6 +1443,59 @@ export function daemonVersionSkew(): { installed: string; expected: string } | n
   return recorded === version ? null : { installed: recorded, expected: version };
 }
 
+/**
+ * Why a Linux unit that exists is not active: skipped on a condition, or
+ * merely stopped.
+ *
+ * Only reached once `is-active` has already said "not active", so it costs a
+ * second `systemctl` call on the unhealthy path and nothing at all on the
+ * healthy one.
+ *
+ * `ConditionResult` is systemd's own record of the last condition evaluation
+ * and is `no` only after it actually ran them and one failed. A unit that has
+ * never been started since boot reports `yes` (the field's default), so this
+ * cannot invent a `condition-failed` for a unit systemd has not judged — it
+ * under-reports rather than over-reports, which is the safe direction for a
+ * signal that clears `daemonConfigured`.
+ */
+function inactiveLinuxStatus(): DaemonServiceStatus {
+  try {
+    return interpretConditionResult(
+      execFileSync(
+        "systemctl",
+        ["show", systemdUnitName(), "--property=ConditionResult", "--value"],
+        { stdio: ["ignore", "pipe", "ignore"], timeout: SERVICE_CMD_TIMEOUT_MS },
+      ).toString(),
+    );
+  } catch {
+    // No systemd, no systemctl, or a version without `--value`. The unit file
+    // exists, so "stopped" remains the honest answer — and it is the
+    // conservative one, because nothing acts destructively on it.
+    return "stopped";
+  }
+}
+
+/**
+ * `systemctl show --property=ConditionResult --value` → a status.
+ *
+ * Split out from the subprocess so the interpretation can be tested without
+ * `/etc/systemd/system`, which this code reads at a fixed path and no test may
+ * write. The live behaviour — that systemd actually skips a unit whose
+ * `ConditionPathExists=` fails, and records `no` when it does — is proven
+ * against a real systemd in the container test rather than asserted here.
+ *
+ * Only a literal `no` means condition-failed. Anything else — `yes`, an empty
+ * string from a unit systemd has not evaluated since boot, an unfamiliar word
+ * from a future version — is "stopped", which is the state nothing acts
+ * destructively on. This under-reports rather than over-reports on purpose: the
+ * cost of a missed `condition-failed` is a flag cleared one command later, and
+ * the cost of a false one is a healthy machine silently dropped to the
+ * in-process path.
+ */
+export function interpretConditionResult(raw: string): DaemonServiceStatus {
+  return raw.trim() === "no" ? "condition-failed" : "stopped";
+}
+
 export function daemonServiceStatus(): DaemonServiceStatus {
   if (!isDaemonSupportedPlatform()) return "unsupported-platform";
 
@@ -1297,14 +1510,14 @@ export function daemonServiceStatus(): DaemonServiceStatus {
       })
         .toString()
         .trim();
-      return out === "active" ? "running" : "stopped";
+      return out === "active" ? "running" : inactiveLinuxStatus();
     } catch {
       // `systemctl is-active` exits non-zero (and execFileSync throws) for
       // every non-"active" state — inactive, failed, or the command not
-      // working at all (no systemd user session, systemctl missing). All
-      // of those are indistinguishable from "stopped" from here, and the
-      // unit file existing is what already ruled out "not-installed".
-      return "stopped";
+      // working at all (no systemd user session, systemctl missing). The unit
+      // file existing already ruled out "not-installed", so the only question
+      // left is whether systemd skipped it on a condition.
+      return inactiveLinuxStatus();
     }
   }
 

package/src/hooks/first-run-gate.ts

@@ -15,15 +15,23 @@
 /**
  * Subcommands that must never be interrupted by onboarding.
  *
- * All three are configuration actions in their own right: `config` IS the
+ * The first three are configuration actions in their own right: `config` IS the
  * wizard, and `policies` / `policy` are the non-interactive way to do setup.
  * Putting a wizard in front of them would override an intent the user just
  * stated, and would hang any script that calls them.
+ *
+ * `uninstall` is here for the sharper version of the same reason: it states the
+ * exact OPPOSITE intent. Offering to set this machine up, on the way to tearing
+ * it down, would install hooks and a root-owned systemd unit seconds before the
+ * command removes them — and on a machine that had drifted to unconfigured
+ * (a cleared flag, a reset home), that is the difference between a clean
+ * uninstall and one that leaves behind more than it found.
  */
 export const FIRST_RUN_EXEMPT_SUBCOMMANDS: readonly string[] = [
   "config",
   "policies",
   "policy",
+  "uninstall",
 ];
 
 export function shouldOfferFirstRun(args: readonly string[]): boolean {

package/src/hooks/fp-home.ts

@@ -233,6 +233,19 @@ export const auditScheduleFile = (home?: string) => resolve(stateDir(home), "aud
  */
 export const telemetryIdFile = (home?: string) => resolve(stateDir(home), "telemetry-id");
 export const launcherMarker = (home?: string) => resolve(stateDir(home), "launcher-configured");
+/**
+ * The last first-run setup attempt that ABORTED, and why.
+ *
+ * Deliberately NOT one of `isConfigured()`'s signals: a failed attempt must
+ * never make a machine read as set up. It exists only so the next command can
+ * tell "never tried" from "tried and could not finish" — the wizard writes
+ * nothing on an abort, so without this the two are identical and setup
+ * relaunches on every single command forever.
+ *
+ * Under `state/` with the other derived markers a human never opens.
+ */
+export const onboardingAttemptFile = (home?: string) =>
+  resolve(stateDir(home), "onboarding-attempt.json");
 /**
  * The version that last reported an install, so an upgrade is reported once.
  *

package/src/hooks/fp-reset.ts

@@ -41,6 +41,7 @@ import {
 import { detectLayout, readConfig, updateConfig, writeVersionFile, type LayoutState } from "./fp-config";
 import {
   daemonServiceStatus,
+  daemonStatusCommand,
   daemonVersionSkew,
   isDaemonSupportedPlatform,
   probeDaemonEndToEnd,
@@ -253,6 +254,30 @@ async function healDaemonFlag(): Promise<string[]> {
       ];
     }
 
+    // Installed, and systemd has refused to start it: one of the paths the unit
+    // is gated on is gone. This is what `npm rm -g failproofai` leaves behind —
+    // npm runs no uninstall script, so the unit survives the package that
+    // supplies its worker, and every tool call on the machine then denies with
+    // nothing to point at.
+    //
+    // Treated like "not-installed" rather than like "stopped" because systemd
+    // has already made the call and will keep making it at every boot. That is
+    // the distinction `condition-failed` exists to carry; see its definition.
+    if (status === "condition-failed") {
+      updateConfig({ daemon: { configured: false } });
+      return [
+        `failproofaid is installed but cannot start — a file its service requires is`,
+        `gone (most often because failproofai was removed with \`npm rm -g\`, which`,
+        `deletes the worker but leaves the service behind). This machine was`,
+        `configured to require the daemon, which denies every tool call, so that flag`,
+        `is cleared; policies now evaluate in-process.`,
+        ``,
+        `Run \`failproofai uninstall\` to remove the leftover service, or`,
+        `\`failproofai config\` to rebuild it. \`${daemonStatusCommand()}\` names the missing path.`,
+        ``,
+      ];
+    }
+
     // Installed and RUNNING is not the same as working, and the difference is
     // a total lockout. `ExecStart` bakes in `process.execPath`, so an
     // `nvm uninstall 20` months later leaves a unit systemd still calls active

package/src/hooks/onboarding-attempt.ts

@@ -0,0 +1,179 @@
+/**
+ * Why the last first-run setup stopped, and whether it is worth offering again.
+ *
+ * # The problem this exists for
+ *
+ * Setup is deliberately all-or-nothing: every abort path writes NOTHING, so a
+ * machine that could not be configured is left exactly as it was found rather
+ * than carrying half a configuration (a `daemonConfigured` flag with no daemon
+ * behind it denies every tool call across all twelve CLIs). That invariant is
+ * right and is not changed here.
+ *
+ * But it left onboarding with no memory. `isConfigured()` reads three signals —
+ * a global policy config, live user-scope hooks, the legacy marker — and an
+ * abort sets none of them, so "never tried" and "tried twenty times and could
+ * not finish" are indistinguishable. On a machine without passwordless sudo,
+ * every single command relaunched the whole wizard, forever.
+ *
+ * # What this is NOT
+ *
+ * Not a fourth "configured" signal. Nothing here may make `isConfigured()` true.
+ * A machine that failed setup is unconfigured and must keep saying so — to the
+ * hook path, to `--status`, and to the wizard when it is asked for by name.
+ * This only changes whether the wizard is *offered unprompted*.
+ *
+ * # Re-offering
+ *
+ * A hint that never becomes an offer again is its own failure: the common case
+ * is someone who hits the sudo prompt, gives up, and comes back later able to
+ * elevate. So each reason carries a cheap local check for whether its blocker
+ * is gone, and the wizard offers itself again the moment one is:
+ *
+ *   needs_root     -> elevation is now possible without a prompt
+ *   daemon_failed  -> the service manager now reports something different
+ *   cancelled      -> the CLI version changed; an upgrade is a fair moment to
+ *                     ask again, and nothing else about a deliberate cancel
+ *                     should re-nag
+ *
+ * Every probe is local and takes milliseconds. None of them runs on the hook
+ * path — `--hook` never reaches the first-run gate at all.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { onboardingAttemptFile } from "./fp-home";
+import type { WizardAbort } from "./configure-wizard";
+
+/** Bumped only for a deliberate shape change; an unreadable record is ignored. */
+const SCHEMA_VERSION = 1;
+
+export interface OnboardingAttempt {
+  schemaVersion: number;
+  /** Why the wizard stopped. */
+  reason: WizardAbort;
+  /** The CLI that made the attempt, so an upgrade can re-offer. */
+  cliVersion: string;
+  /**
+   * What the service manager said at the time. Compared, never trusted — the
+   * point is only whether it has CHANGED since.
+   */
+  daemonStatus: string;
+  /** Epoch ms, for support and for nothing else. */
+  at: number;
+}
+
+export function readOnboardingAttempt(): OnboardingAttempt | null {
+  const path = onboardingAttemptFile();
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<OnboardingAttempt>;
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    if (typeof raw.reason !== "string" || typeof raw.cliVersion !== "string") return null;
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      reason: raw.reason as WizardAbort,
+      cliVersion: raw.cliVersion,
+      daemonStatus: typeof raw.daemonStatus === "string" ? raw.daemonStatus : "",
+      at: typeof raw.at === "number" ? raw.at : 0,
+    };
+  } catch {
+    // A corrupt record reads as "no record", which degrades to today's
+    // behaviour — offering the wizard. Never to "configured".
+    return null;
+  }
+}
+
+/** Best-effort: a machine that cannot record this simply keeps being offered. */
+export function recordOnboardingAttempt(
+  reason: WizardAbort,
+  cliVersion: string,
+  daemonStatus: string,
+  now: number = Date.now(),
+): void {
+  try {
+    const path = onboardingAttemptFile();
+    mkdirSync(dirname(path), { recursive: true });
+    const record: OnboardingAttempt = {
+      schemaVersion: SCHEMA_VERSION,
+      reason,
+      cliVersion,
+      daemonStatus,
+      at: now,
+    };
+    writeFileSync(path, JSON.stringify(record, null, 2), "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Called on a completed apply. A stale record would keep suppressing the offer
+ * on a machine that has since been reconfigured by hand and un-configured again.
+ */
+export function clearOnboardingAttempt(): void {
+  try {
+    rmSync(onboardingAttemptFile(), { force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+export interface RetryProbe {
+  /** Elevation is possible without prompting. */
+  canElevate: () => boolean;
+  /** What the service manager says right now. */
+  daemonStatus: () => string;
+  /** This CLI's version. */
+  cliVersion: string;
+}
+
+/**
+ * Whether the thing that stopped setup last time has since changed.
+ *
+ * `true` means offer the wizard again; `false` means a one-line hint. An
+ * unrecognised reason returns `true` — an unknown blocker is one we cannot
+ * prove is still present, and the safe direction is offering setup rather than
+ * silently withholding it.
+ */
+export function blockerCleared(attempt: OnboardingAttempt, probe: RetryProbe): boolean {
+  switch (attempt.reason) {
+    case "needs_root":
+      return probe.canElevate();
+    case "daemon_failed":
+      // Any movement at all: not-installed -> stopped, stopped -> running, or a
+      // platform that has gained a service manager. Comparing rather than
+      // demanding "running" is what lets a partially-repaired machine be
+      // offered setup again instead of waiting for a state it cannot reach on
+      // its own.
+      return probe.daemonStatus() !== attempt.daemonStatus || probe.canElevate();
+    case "cancelled":
+      // A deliberate stop. Re-asking on the next command is exactly the nagging
+      // this module removes — but an upgrade is a new thing to say, so it is
+      // allowed to ask once more.
+      return probe.cliVersion !== attempt.cliVersion;
+    case "not_a_tty":
+    case "running_as_sudo":
+      // Both are properties of the invocation, not of the machine, so the next
+      // one may well be fine.
+      return true;
+    default:
+      return true;
+  }
+}
+
+/** The one line shown instead of relaunching the wizard. */
+export function attemptHintLines(attempt: OnboardingAttempt): string[] {
+  const why: Record<string, string> = {
+    needs_root: "it needs root to install the failproofaid service",
+    daemon_failed: "the failproofaid service could not be started",
+    cancelled: "it was cancelled",
+    not_a_tty: "there was no terminal to ask in",
+    running_as_sudo: "it was run under sudo",
+  };
+  const detail = why[attempt.reason] ?? "it did not finish";
+  return [
+    ``,
+    `[failproofai] Setup is not finished — ${detail}.`,
+    `              Run \`failproofai config\` when you are ready.`,
+    ``,
+  ];
+}