failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/bin/failproofai.mjs

@@ -124,13 +124,13 @@ if (hookIdx >= 0) {
     // machine until `failproofai config` has installed failproofaid AND
     // written the daemonConfigured marker (Stage 4). Until then this is
     // byte-for-byte the same handleHookEvent(...) call below.
-    const { isDaemonConfigured, tryDaemonHook } = await import("../src/hooks/daemon-client");
+    const { isDaemonConfigured, attemptDaemonHook } = await import("../src/hooks/daemon-client");
     if (isDaemonConfigured()) {
       const { readStdinPayload } = await import("../src/hooks/read-stdin");
       const { evaluateHookEvent } = await import("../src/hooks/handler");
       const stdinRead = await readStdinPayload();
 
-      const daemonResult = await tryDaemonHook({
+      const attempt = await attemptDaemonHook({
         hookEvent: eventType,
         cli,
         stdin: stdinRead.payload,
@@ -140,21 +140,40 @@ if (hookIdx >= 0) {
         cwd: process.cwd(),
       });
 
-      // No silent fallback to in-process evaluation here: this machine was
-      // explicitly configured to run through the daemon, so an unreachable
-      // daemon fails closed instead — a loud, correctly-shaped deny (real
-      // per-CLI response shaping, not a generic denial) rather than a
-      // silent downgrade. See the plan's "Confirmed scope decisions".
-      const result =
-        daemonResult ??
-        (await evaluateHookEvent(eventType, cli, stdinRead.payload, {
-          forceDecision: {
-            decision: "deny",
-            reason:
-              "failproofaid could not be reached. This machine is configured to run hooks through it " +
-              "— check the daemon (see `failproofai config`) rather than retrying blindly.",
-          },
-        }));
+      // On a daemon-configured machine the daemon is the ONLY evaluator. Every
+      // way of not getting an answer from it denies, and in-process evaluation
+      // is never reached from this branch — that is what "all enforcement is
+      // routed through the daemon" means, and a fallback here would be a second
+      // policy engine reachable by breaking the first.
+      //
+      // The two failures still differ in what the USER has to do, so they are
+      // told apart in the message and nowhere else:
+      //
+      //   protocol-mismatch: a daemon answered, so it is alive; the CLI and the
+      //     daemon are different versions, which is what an `npm update` that
+      //     has not been followed by `failproofai config` looks like. The remedy
+      //     is an upgrade, and naming it is the difference between a one-command
+      //     fix and a support ticket. `daemonVersionSkew()` has already been
+      //     hinting this on every CLI command.
+      //
+      //   unreachable: nothing answered. A stopped service, a deleted socket and
+      //     deliberate tampering are indistinguishable from here — and a machine
+      //     where stopping one service silently disables every guardrail is not
+      //     a guarded machine.
+      let result;
+      if (attempt.ok) {
+        result = attempt.response;
+      } else {
+        const reason =
+          attempt.failure === "protocol-mismatch"
+            ? "failproofaid is running a different protocol version than this CLI, so it " +
+              "cannot evaluate this call. Run `failproofai config` to update the daemon."
+            : "failproofaid could not be reached. This machine is configured to run hooks through it " +
+              "— check the daemon (see `failproofai config`) rather than retrying blindly.";
+        result = await evaluateHookEvent(eventType, cli, stdinRead.payload, {
+          forceDecision: { decision: "deny", reason },
+        });
+      }
 
       if (result.stdout) process.stdout.write(result.stdout);
       if (result.stderr) process.stderr.write(result.stderr);
@@ -168,6 +187,64 @@ if (hookIdx >= 0) {
     await exitAfterFlush(exitCode);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+
+    // The outer fail-closed boundary. This wrote NOTHING to stdout and exited 2,
+    // which is a deny for Claude and Factory's non-Stop events and a silent
+    // ALLOW for the eight CLIs that read their verdict from stdout JSON —
+    // Cursor, Pi, Hermes, OpenClaw, Devin, Antigravity, Goose, and Factory's
+    // Stop. Everything above can land here, INCLUDING the forced-deny call that
+    // handles an unreachable daemon, so the one path whose entire job is to fail
+    // closed failed open instead.
+    //
+    // Emitted BEFORE any telemetry: `flushHookTelemetry` loops until its queue
+    // drains and is not bounded, so draining first meant a stuck send could hold
+    // the verdict back indefinitely — and a verdict that arrives after the agent
+    // has moved on is the same as no verdict.
+    const reason =
+      "failproofai could not evaluate this call and is failing closed. " +
+      `Check the failproofai installation (\`failproofai config\`). Underlying error: ${msg}`;
+    let emitted = false;
+    let denyExitCode = 2;
+    try {
+      // The real evaluator does the shaping, exactly as the unreachable-daemon
+      // path above does — that is what keeps this deny from being inert on some
+      // CLI whose contract nobody remembered here. It can only work if the
+      // handler module is loadable, which is why the fallback below exists.
+      const { evaluateHookEvent } = await import("../src/hooks/handler");
+      const forced = await evaluateHookEvent(eventType, cli, "", {
+        forceDecision: { decision: "deny", reason },
+      });
+      if (forced.stdout) process.stdout.write(forced.stdout);
+      if (forced.stderr) process.stderr.write(forced.stderr);
+      emitted = true;
+      denyExitCode = forced.exitCode;
+    } catch {
+      // Last ditch: the module that knows each CLI's exact deny shape is itself
+      // the thing that just failed, so this emits the union of them — every CLI
+      // reads only the keys it knows and ignores the rest. Deliberately NOT a
+      // per-CLI table: a second copy of those twelve contracts would drift from
+      // the real one, and this runs only when the install is already broken.
+      // Imperfect enforcement beats the zero bytes that were written before.
+      try {
+        process.stdout.write(
+          JSON.stringify({
+            decision: "block",
+            reason,
+            permission: "deny",
+            followup_message: reason,
+            hookSpecificOutput: {
+              hookEventName: eventType,
+              permissionDecision: "deny",
+              permissionDecisionReason: reason,
+            },
+          }),
+        );
+        emitted = true;
+      } catch {}
+    }
+    if (!emitted) console.error(`Unexpected error: ${msg}`);
+    else console.error(`[failproofai] failing closed: ${msg}`);
+
     await track("hook_dispatch_error", {
       event_type: eventType,
       cli,
@@ -180,8 +257,10 @@ if (hookIdx >= 0) {
       const { flushHookTelemetry } = await import("../src/hooks/hook-telemetry");
       await flushHookTelemetry();
     } catch {}
-    console.error(`Unexpected error: ${msg}`);
-    process.exit(2);
+    // `exitAfterFlush`, not a bare `process.exit`: this was the one exit in
+    // `--hook` handling that skipped it, so under load `process.exit` could
+    // truncate the very bytes carrying the deny.
+    await exitAfterFlush(denyExitCode);
   }
 }
 
@@ -191,18 +270,8 @@ if (hookIdx >= 0) {
  * Error     → unexpected; shows message only, exits 2
  */
 async function runCli() {
-  // Report a fresh install / upgrade. Deliberately here rather than at module
-  // scope: everything above this point is the --hook fast path, which runs on
-  // every tool call. No-ops after the first run on a given version.
-  try {
-    const { maybeReportInstall } = await import("../lib/install-check");
-    await maybeReportInstall(version);
-  } catch {
-    // never block a command on reporting
-  }
-
   // --help / -h  (only when not inside a subcommand that handles its own --help)
-  const SUBCOMMANDS = ["policies", "policy", "auth", "audit", "config"];
+  const SUBCOMMANDS = ["policies", "policy", "audit", "config", "uninstall", "backfill", "flush", "harness"];
   if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
     const extraArgs = args.filter((a) => a !== "--help" && a !== "-h");
     if (extraArgs.length > 0) {
@@ -217,6 +286,13 @@ USAGE
 COMMANDS
   (no args)                      Launch the policy dashboard
   config                         Interactive setup — pick scope, agents & policies
+    --connect <url> --token <key>  Connect to Failproof Cloud non-interactively
+    --machine-id <id>              Stable id for this machine
+    --machine-label <name>         Human-readable name in the dashboard
+    --no-transcripts               Report decisions only, never transcripts
+    --disconnect                   Stop pulling policy and sending activity
+    --status                       Show connection, daemon and pause state
+    --pause / --resume             Pause or resume enforcement
 
   policy add <name>              Enable a single policy (see \`policy --help\`)
   policy remove <name>           Disable a single policy
@@ -243,16 +319,52 @@ COMMANDS
 
   policies --help, -h            Show this help for the policies command
 
-  auth                           Sign in / out of FailproofAI from the CLI.
-    login                          Email + OTP flow; writes ~/.failproofai/auth.json
-    logout                         Revoke this session and remove auth.json
-    whoami                         Print the currently authenticated identity
-  auth --help, -h                Show this help for the auth command
+  harness list                   Show extra capture paths per agent CLI
+  harness add-path <h> <path>    Also capture sessions from <path> for harness
+                                 <h>. Accepts \`<label>=<path>\`; the label
+                                 namespaces agent ids so two copies of one
+                                 project stay distinct.
+  harness remove-path <h> <p>    Stop capturing that path
+  harness --help, -h             Show this help for the harness command
 
   audit                          Audit your agent's behavior, then open the
                                  dashboard at http://localhost:8020/audit
   audit --help, -h               Show this help for the audit command
 
+  backfill                       Re-send history the collector already read past
+                                 — after clearing the dashboard, re-enrolling a
+                                 machine, or connecting later than the work
+    --since <when>                 How far back: 30d, 6m, or YYYY-MM-DD
+                                   (default: 30 days)
+    --dry-run                      Report what would be re-read, change nothing
+
+  flush                          Deliver everything already spooled, now,
+                                 instead of waiting for the next sweep
+    --wait                         Block until the spool drains (or --timeout)
+    --timeout <secs>               How long to wait with --wait (default: 60)
+
+  update                         Finish an upgrade npm cannot: migrate
+                                 ~/.failproofai to this version's layout, put the
+                                 matching daemon binary in place, restart it.
+                                 Run after \`npm install -g failproofai@latest\`.
+    --no-daemon                    Migrate the home only
+
+  migrate                        Run pending layout migrations on their own,
+                                 keyed on the layout in ~/.failproofai/VERSION
+                                 (not the npm version, so skipping releases with
+                                 no layout change runs nothing)
+    --dry-run                      Print the steps and change nothing
+
+  uninstall                      Remove failproofai from this machine: hook
+                                 entries from every agent CLI, and the daemon
+                                 service. Run this BEFORE \`npm rm -g failproofai\`
+                                 — npm runs no uninstall script, so removing the
+                                 package alone leaves both behind.
+    --purge                        Also delete ~/.failproofai (settings,
+                                   credentials, audit history, daemon binary)
+    --dry-run                      Show what would be removed, change nothing
+    --yes, -y                      Skip the confirmation prompt
+
   --version, -v                  Print version and exit
   --help, -h                     Show this help message
 
@@ -282,6 +394,10 @@ EXAMPLES
   failproofai policies --uninstall --cli opencode
   failproofai policies --uninstall --cli pi
   failproofai policies --uninstall --custom
+  failproofai backfill --since 6m
+  failproofai backfill --dry-run
+  failproofai flush --wait
+  failproofai config --status
 
 LINKS
   ⭐ Star us:      https://github.com/failproofai/failproofai
@@ -301,6 +417,698 @@ LINKS
     process.exit(0);
   }
 
+  // First-run onboarding — before any subcommand runs its own work.
+  //
+  // On a machine that has never been set up, the first thing the user typed is
+  // almost never the thing they need first, so we run the wizard and then let
+  // their original command proceed. Exemptions matter more than the rule:
+  //
+  //   --hook            never reaches here (it exits above) — it runs on every
+  //                     tool call, and a wizard on that path would hang an agent
+  //   --version/--help  answering "what is this" must not require setup
+  //   config            IS the wizard
+  //   policies/policy   explicit configuration actions. Intercepting these would
+  //                     fight the intent the user just stated, and would break
+  //                     non-interactive scripts that call them to do setup.
+  //
+  // `maybeFirstRunConfigure` is itself a no-op on a configured machine, on a
+  // non-TTY, and under sudo — so this is a cheap check, not a second gate.
+  // Layout check, before onboarding decides anything. A home written by an
+  // older layout is reset here — visibly, in a real command the user typed —
+  // rather than from a hook, which runs unattended once per tool call. A home
+  // written by a NEWER layout stops the command instead: that data is fine and
+  // an upgrade would read it, so deleting it would destroy something
+  // recoverable.
+  //
+  // `audit --scheduled` is the exception, and it takes the HOOK's branch: it is
+  // spawned by failproofaid on a timer, so "visibly, in a real command the user
+  // typed" is exactly what it is not. `checkLayoutForCli()` deletes
+  // config.toml and credentials.toml (see `resettablePaths`), so letting a
+  // background process reach it would silently revoke a user's
+  // `[telemetry] enabled = false`, erase their cloud enrolment, and switch off
+  // `[audit] auto` — the setting that scheduled the run — with the explanation
+  // going only to the service journal. Reachable on every machine at the next
+  // LAYOUT_VERSION bump, when a home carrying `auto = true` is by definition
+  // stale. Verified live: one scheduled tick took a home's whole config.
+  //
+  // `--help` / `--version` take the same exemption `first-run-gate.ts` gives
+  // them, and for a stronger reason. Those two answer "what is this / how do I
+  // use it"; the subcommands that parse their own help (`policies --help`) fall
+  // past the help block above and reach here, so without this a user typing
+  // `failproofai policies --help` had their home reset by a question. The
+  // adjacent, far less destructive first-run gate exempted help from the start.
+  {
+    const isHelpOrVersion =
+      args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v");
+    if (args[0] === "audit" && args.includes("--scheduled")) {
+      // NOT `layoutWarningForHook` — that one answers the hook's question
+      // ("are policies unenforced?") and deliberately stays quiet when the
+      // global config is readable. This gate is about the LAYOUT, and must
+      // fire whenever completing the run would reset the home.
+      const { layoutBlockerForScheduledRun } = await import("../src/hooks/fp-reset");
+      const warning = layoutBlockerForScheduledRun();
+      if (warning) {
+        // Exit 1, not 75: 75 means "another audit holds the lock" and is retried
+        // in fifteen minutes, which here would just re-warn four times an hour
+        // forever. A stale home is a real failure that `failproofai config`
+        // fixes, so it is reported and retried at the ordinary cadence.
+        console.error(warning);
+        process.exit(1);
+      }
+    } else if (!isHelpOrVersion && args[0] !== "migrate" && args[0] !== "update") {
+      // `migrate` and `update` are exempt because they ARE this step, and letting
+      // it run first breaks them both. `migrate --dry-run` promises to change
+      // nothing and print what would happen — with the check ahead of it, the home
+      // was already migrated by the time the subcommand looked, so it reported
+      // "nothing to migrate" on every stale machine it was ever pointed at, which
+      // is the one answer a dry run must never give wrongly. Caught by a smoke
+      // test on a seeded layout-2 home, not by a unit test: nothing below the CLI
+      // entry point can see this ordering.
+      const { checkLayoutForCli } = await import("../src/hooks/fp-reset");
+      const check = await checkLayoutForCli();
+      for (const line of check.lines) console.error(line);
+      if (check.fatal) process.exit(1);
+      // `check.didReset` is deliberately not read. It used to force the wizard
+      // below; see the note at `shouldOfferFirstRun` for why a migrated machine
+      // no longer needs setup re-run, and `didReset` in `fp-reset.ts` for what
+      // the field means now.
+    }
+  }
+
+  // Report a fresh install / upgrade. AFTER the layout check above, never
+  // before: this writes the `last-version` marker, and while that file lived at
+  // the root of the home it was one of the landmarks `detectLayout()` reads as
+  // "layout 1". Running first meant the CLI created the file and then read it
+  // back as evidence of an old layout, so every genuinely fresh machine had its
+  // very first command open with "failproofai reorganised … Removed 1 item(s)
+  // from the old layout." Nothing was lost — there was nothing there — but
+  // training every new user to ignore that banner is expensive given what it
+  // says on a real layout-1 home. The file has also moved under `state/`, so
+  // the two are independent now; the order is kept because it is the correct
+  // one regardless.
+  //
+  // Deliberately not at module scope: everything above the CLI entry is the
+  // --hook fast path, which runs on every tool call. No-ops after the first run
+  // on a given version.
+  try {
+    const { maybeReportInstall } = await import("../lib/install-check");
+    await maybeReportInstall(version);
+  } catch {
+    // never block a command on reporting
+  }
+
+  const { shouldOfferFirstRun } = await import("../src/hooks/first-run-gate");
+  // `|| layoutWasReset` stood here, with `force: layoutWasReset` below, because a
+  // migration used to delete the home's policy config while leaving the agent
+  // CLIs' settings files alone — so `isConfigured()` read true off
+  // `hasGlobalHooks` and setup was skipped, leaving hooks firing against no
+  // policies, silently and permanently.
+  //
+  // The migration keeps that file now (`HOME_CLASSES` classes it `user-typed`),
+  // along with `config.json` and `credentials.json`, so a migrated machine is
+  // configured in fact and not merely in appearance. Forcing the wizard here
+  // would open an interactive prompt with nothing to answer — and on a fleet box,
+  // a CI runner or a headless gateway, nobody to answer it. A home that never
+  // finished setup still gets here on its own: `isConfigured()` is false for it.
+  // See `didReset` in `fp-reset.ts`.
+  if (shouldOfferFirstRun(args)) {
+    try {
+      const { maybeFirstRunConfigure } = await import("../src/hooks/configure-wizard");
+      // `audit` runs its own scan immediately after this returns; firing the
+      // post-setup audit too would scan the whole history twice in a row.
+      await maybeFirstRunConfigure({}, { postSetupAudit: args[0] !== "audit" });
+    } catch {
+      // Onboarding is never allowed to block the command the user actually typed.
+    }
+  }
+
+  // backfill [--since <YYYY-MM-DD|Nd>] [--dry-run]
+  //
+  // Hands off to the daemon rather than doing the work: the cursors it rewinds
+  // are held in memory by the RUNNING collector, which would write them back
+  // over. Every precondition a person can get wrong is still checked HERE,
+  // synchronously, because reporting success and leaving the real failure in the
+  // journal is what already cost twenty minutes on a live machine.
+  if (args[0] === "flush") {
+    const subArgs = args.slice(1);
+    if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai flush — deliver what is already spooled, now
+
+USAGE
+  failproofai flush [--wait] [--timeout <secs>]
+
+WHY
+  The collector is unhurried on purpose: a batch is swept once it is older than
+  two minutes, at most 64 per pass, on a 60-second cadence. That pacing keeps a
+  backlog from stampeding the server, and it is exactly wrong when you are
+  standing at a dashboard waiting to see your own events — "not delivered yet"
+  and "not working" look identical from there.
+
+  This asks the daemon to make a pass right now, with no minimum age and no
+  per-pass cap. It re-sends nothing: only batches already spooled and not yet
+  delivered. For history the collector has already read past, use \`backfill\`.
+
+OPTIONS
+  --wait             Block until the spool drains, or --timeout elapses.
+  --timeout <secs>   How long --wait waits. Default: 60.
+`);
+      process.exit(0);
+    }
+
+    const KNOWN = new Set(["--wait", "--timeout"]);
+    const unknown = subArgs.find(
+      (a, i) => a.startsWith("-") && !KNOWN.has(a) && subArgs[i - 1] !== "--timeout",
+    );
+    if (unknown) {
+      throw new CliError(`Unexpected argument: ${unknown}\nRun \`failproofai flush --help\` for usage.`);
+    }
+
+    let timeoutSecs;
+    const tIdx = subArgs.indexOf("--timeout");
+    if (tIdx >= 0) {
+      const raw = subArgs[tIdx + 1];
+      if (!raw || raw.startsWith("-")) throw new CliError("Missing value after --timeout.");
+      const n = Number(raw);
+      // Rejected rather than coerced: NaN would silently become "wait forever
+      // or not at all" depending on the comparison, and neither is what was asked.
+      if (!Number.isFinite(n) || n <= 0) {
+        throw new CliError(`Could not read --timeout ${raw}. Give a number of seconds.`);
+      }
+      timeoutSecs = n;
+    }
+
+    lastSubcommand = "flush";
+    const { runFlushCommand } = await import("../src/hooks/flush-cli");
+    const result = await runFlushCommand({ wait: subArgs.includes("--wait"), timeoutSecs });
+    for (const line of result.lines) {
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    await track("cli_flush", {
+      ok: result.exitCode === 0,
+      waited: subArgs.includes("--wait"),
+      pending: result.pending,
+    });
+    lastSubcommand = null;
+    await exitAfterFlush(result.exitCode);
+    return;
+  }
+
+  if (args[0] === "backfill") {
+    const subArgs = args.slice(1);
+    if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai backfill — re-send history the collector has already read past
+
+USAGE
+  failproofai backfill [--since <when>] [--dry-run]
+
+WHY
+  The collector never re-reads a file it has a cursor for, which is right until
+  the dashboard's data is cleared, a machine is re-enrolled, or cursors advanced
+  before there was anywhere to send. Then the history exists on disk and nowhere
+  else, with no way to ask for it again.
+
+  Re-sending is safe: redaction is deterministic, so a re-sent event hashes
+  identically to its first send and collapses into the row already there.
+
+OPTIONS
+  --since <when>   How far back. \`30d\`, \`6m\`, or \`YYYY-MM-DD\`.
+                   Default: 30 days.
+  --dry-run        Report what would be re-read and change nothing.
+
+  Which streams are sent follows [collector] in ~/.failproofai/config.toml —
+  a backfill never sends something your config says you do not want.
+`);
+      process.exit(0);
+    }
+
+    const KNOWN = new Set(["--since", "--dry-run"]);
+    const unknown = subArgs.find((a, i) => a.startsWith("-") && !KNOWN.has(a) && subArgs[i - 1] !== "--since");
+    if (unknown) {
+      throw new CliError(`Unexpected argument: ${unknown}\nRun \`failproofai backfill --help\` for usage.`);
+    }
+
+    let sinceMs;
+    const sinceIdx = subArgs.indexOf("--since");
+    if (sinceIdx >= 0) {
+      const raw = subArgs[sinceIdx + 1];
+      if (!raw || raw.startsWith("-")) throw new CliError("Missing value after --since.");
+      // `30d` / `6m` / an ISO date. Rejected rather than guessed at: silently
+      // reading an unparseable window as "the default" would send a different
+      // amount of history than was asked for, and nothing would say so.
+      const rel = /^(\d+)([dmy])$/.exec(raw);
+      if (rel) {
+        const n = Number(rel[1]);
+        const days = rel[2] === "d" ? n : rel[2] === "m" ? n * 30 : n * 365;
+        sinceMs = Date.now() - days * 24 * 60 * 60 * 1000;
+      } else {
+        const t = Date.parse(raw);
+        if (Number.isNaN(t)) {
+          throw new CliError(`Could not read --since ${raw}. Use 30d, 6m, or YYYY-MM-DD.`);
+        }
+        sinceMs = t;
+      }
+    }
+
+    lastSubcommand = "backfill";
+    const { runBackfillCommand } = await import("../src/hooks/backfill-cli");
+    const result = runBackfillCommand({ sinceMs, dryRun: subArgs.includes("--dry-run") });
+    for (const line of result.lines) {
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    await track("cli_backfill", { ok: result.exitCode === 0, dry_run: subArgs.includes("--dry-run"), explicit_since: sinceIdx >= 0 });
+    lastSubcommand = null;
+    await exitAfterFlush(result.exitCode);
+    return;
+  }
+
+  // harness list | add-path | remove-path
+  //
+  // Extra capture paths per harness. Writes ~/.failproofai/config.toml and
+  // nothing else — no root, no daemon call — so it works on a machine whose
+  // daemon is stopped, which is when someone is most likely to be fixing what
+  // it captures.
+  if (args[0] === "harness") {
+    const subArgs = args.slice(1);
+    if (subArgs.length === 0 || subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai harness — capture sessions from more than one location per agent CLI
+
+USAGE
+  failproofai harness list [<harness>]
+  failproofai harness add-path <harness> [<label>=]<path>
+  failproofai harness remove-path <harness> <path|label>
+
+WHY
+  Each agent CLI is watched wherever its own installer put it — ~/.claude/projects,
+  ~/.hermes/state.db, and so on. That misses every other arrangement: a second
+  profile, a mounted team share, a container's home beside the host's, an agent
+  an operator moved. Those hold real sessions and nothing collects them.
+
+THE LABEL
+  An entry is \`<path>\` or \`<label>=<path>\`. The label namespaces agent ids as
+  <label>-<agentId>, and it matters: two locations holding the same project
+  derive the SAME id (it comes from the cwd inside the transcript, identical in
+  both copies), so without a label they merge into one agent whose sessions
+  interleave from two machines' worth of history. Omit it and one is derived
+  from the folder name.
+
+HARNESSES
+  claude, codex, copilot, openclaw, pi, factory, antigravity, cursor,
+  goose, opencode, devin, hermes
+
+  \`claude\` covers subagent transcripts too — they live under the same root.
+
+NOTES
+  • Session collection must be on for any of this to be read; extra paths live
+    under "collector" in ~/.failproofai/config.json like the default ones do.
+  • A path overlapping one already captured is REFUSED by the daemon at startup
+    rather than collected twice under two ids. It says so in the journal.
+  • Two entries sharing a LABEL are refused too: they would share one cursor
+    directory, whose whole map is written at once, so each would clobber the
+    other's watermark and re-read from zero after every restart.
+  • Takes effect within seconds — the daemon re-reads config.json on an interval
+    and cycles its collector. No restart, no sudo.
+
+EXAMPLES
+  failproofai harness add-path claude work=/srv/team/.claude/projects
+  failproofai harness add-path hermes prod=/srv/hermes-prod/state.db
+  failproofai harness add-path codex /mnt/other-home/.codex/sessions
+  failproofai harness list
+  failproofai harness remove-path claude work
+
+  One home per person — label them, or both derive the same folder-name label
+  and the second is refused:
+  failproofai harness add-path openclaw user1=/srv/.openclaw-user1
+  failproofai harness add-path openclaw user2=/srv/.openclaw-user2
+
+  Containers: FAILPROOFAI_<HARNESS>_EXTRA_PATHS replaces the file's entries.
+  FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/.openclaw-user1,user2=/srv/.openclaw-user2"
+
+`.trimStart());
+      process.exit(0);
+    }
+
+    lastSubcommand = "harness";
+    const { runHarnessCommand } = await import("../src/hooks/harness-cli");
+    const result = runHarnessCommand(subArgs);
+    for (const line of result.lines) {
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    await track("cli_harness", {
+      ok: result.exitCode === 0,
+      // The subcommand only — never the harness name, the label or the path.
+      // A path is a value the user typed, and `enterprise-docs/product-analytics.md`
+      // promises we send shape, never value.
+      sub: ["list", "add-path", "remove-path"].includes(subArgs[0]) ? subArgs[0] : "unknown",
+    });
+    lastSubcommand = null;
+    await exitAfterFlush(result.exitCode);
+    return;
+  }
+
+  // uninstall [--purge] [--dry-run] [--yes|-y]
+  //
+  // Top-level, and deliberately NOT a flag on `policies`. `policies --uninstall`
+  // disables policies; this removes the product — hook entries across every
+  // agent CLI plus the root-owned daemon service — and the two must not be one
+  // keystroke apart.
+  if (args[0] === "migrate") {
+    const subArgs = args.slice(1);
+    if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai migrate — bring ~/.failproofai up to the layout this version speaks
+
+USAGE
+  failproofai migrate [--dry-run]
+
+WHY
+  npm cannot update an installed package on its own, so a machine can sit on an
+  old version for months and then jump several layouts at once. This runs the
+  steps for that jump in order, keyed on the LAYOUT recorded in
+  ~/.failproofai/VERSION rather than on the npm version — so skipping thirty
+  releases with no layout change runs nothing at all.
+
+  It normally happens by itself, on the first command after an upgrade. This is
+  for running it deliberately, and for seeing what it would do first.
+
+  Your settings, cloud enrolment, policy selection, your own policy files,
+  decision history and undelivered events are carried across, not removed. The
+  irreplaceable files are copied to migrations/backup-layout<n>/ before anything
+  runs, and every step is recorded in migrations/applied.json.
+
+OPTIONS
+  --dry-run   Print the steps and the files that would be saved. Change nothing.
+`);
+      process.exit(0);
+    }
+
+    const KNOWN = new Set(["--dry-run"]);
+    const unknown = subArgs.find((a) => a.startsWith("-") && !KNOWN.has(a));
+    if (unknown) {
+      throw new CliError(
+        `Unexpected argument: ${unknown}\nRun \`failproofai migrate --help\` for usage.`,
+      );
+    }
+
+    lastSubcommand = "migrate";
+    const { detectLayout } = await import("../src/hooks/fp-config");
+    const { LAYOUT_VERSION } = await import("../src/hooks/fp-home");
+    const { describePlan, runMigrations } = await import("../src/hooks/migrations");
+    const state = detectLayout();
+
+    // A NEWER home is refused here exactly as `checkLayoutForCli` refuses it: the
+    // data is fine and an upgrade would read it, so migrating "forward" from it
+    // is not a thing that exists.
+    if (state.kind === "future") {
+      console.error(
+        `This machine's failproofai directory was written by a newer version (layout ${state.found};`,
+      );
+      console.error(`this build speaks ${LAYOUT_VERSION}). Upgrade rather than migrate:`);
+      console.error(`  npm install -g failproofai@latest`);
+      await track("cli_migrate", { ok: false, reason: "future_layout" });
+      lastSubcommand = null;
+      await exitAfterFlush(1);
+      return;
+    }
+
+    const from = state.kind === "stale" ? state.found : LAYOUT_VERSION;
+    if (subArgs.includes("--dry-run")) {
+      for (const line of describePlan(from)) console.log(line);
+      await track("cli_migrate", { ok: true, dry_run: true, from });
+      lastSubcommand = null;
+      await exitAfterFlush(0);
+      return;
+    }
+
+    if (state.kind !== "stale") {
+      console.log(`Already at layout ${LAYOUT_VERSION}. Nothing to migrate.`);
+      await track("cli_migrate", { ok: true, from, steps: 0 });
+      lastSubcommand = null;
+      await exitAfterFlush(0);
+      return;
+    }
+
+    const run = runMigrations(from);
+    for (const step of run.steps) {
+      console.log(`${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`);
+    }
+    if (run.backedUp.length > 0) {
+      console.log(`Saved first: ${run.backedUp.join(", ")}`);
+    }
+    if (run.failed) {
+      console.error(`Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`);
+      console.error(`The home is still marked layout ${from} and will be retried.`);
+    }
+    await track("cli_migrate", {
+      ok: !run.failed,
+      from,
+      steps: run.steps.length,
+      removed: run.outcome.removed.length,
+    });
+    lastSubcommand = null;
+    await exitAfterFlush(run.failed ? 1 : 0);
+    return;
+  }
+
+  if (args[0] === "update") {
+    const subArgs = args.slice(1);
+    if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai update — finish an upgrade: migrate the home, match the daemon
+
+USAGE
+  npm install -g failproofai@latest && failproofai update [--no-daemon]
+
+WHY
+  npm replaces the CLI and nothing else. The daemon binary lives at
+  ~/.failproofai/bin/failproofaid-<version> and stays exactly where it was, so
+  after an npm upgrade the two halves are different versions — and failproofaid
+  refuses to start against a layout it does not speak, which is the loud version
+  of that problem rather than the silent one.
+
+  This does the rest of the upgrade: runs any pending layout migrations, puts the
+  matching daemon binary in place, and restarts the service.
+
+OPTIONS
+  --no-daemon   Migrate the home only. Leaves a version-skewed daemon in place,
+                so prefer letting it run.
+`);
+      process.exit(0);
+    }
+
+    const KNOWN = new Set(["--no-daemon"]);
+    const unknown = subArgs.find((a) => a.startsWith("-") && !KNOWN.has(a));
+    if (unknown) {
+      throw new CliError(
+        `Unexpected argument: ${unknown}\nRun \`failproofai update --help\` for usage.`,
+      );
+    }
+
+    lastSubcommand = "update";
+    // Runs the migration itself rather than leaning on the check at the top of
+    // this file, which this command is exempt from. Reading the ledger and
+    // inferring "the top-level check must have done it" was the first version, and
+    // it is the kind of indirection that reads fine and reports the wrong thing
+    // the moment either half moves.
+    const { detectLayout } = await import("../src/hooks/fp-config");
+    const { LAYOUT_VERSION } = await import("../src/hooks/fp-home");
+    const { runMigrations } = await import("../src/hooks/migrations");
+    const state = detectLayout();
+
+    if (state.kind === "future") {
+      console.error(
+        `This machine's failproofai directory was written by a NEWER version (layout ${state.found};`,
+      );
+      console.error(`this build speaks ${LAYOUT_VERSION}). This CLI is the stale half:`);
+      console.error(`  npm install -g failproofai@latest`);
+      await track("cli_update", { ok: false, reason: "future_layout" });
+      lastSubcommand = null;
+      await exitAfterFlush(1);
+      return;
+    }
+
+    let migrationsRan = 0;
+    let migrationFailed = false;
+    if (state.kind === "stale") {
+      const run = runMigrations(state.found);
+      migrationsRan = run.steps.length;
+      migrationFailed = Boolean(run.failed);
+      for (const step of run.steps) {
+        console.log(`${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`);
+      }
+      if (run.backedUp.length > 0) console.log(`Saved first: ${run.backedUp.join(", ")}`);
+      if (run.failed) {
+        console.error(
+          `Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`,
+        );
+        console.error(`The home is still marked layout ${state.found} and will be retried.`);
+      }
+    } else {
+      console.log(`Home is at layout ${LAYOUT_VERSION}; no migration was needed.`);
+    }
+
+    // The daemon is refreshed even when a step failed, and deliberately: the
+    // binary and the layout are independent halves, and leaving a version-skewed
+    // daemon behind on top of a failed migration is strictly worse than fixing
+    // the half that can be fixed. The exit code still reports the failure.
+    let daemonOk = true;
+    if (subArgs.includes("--no-daemon")) {
+      console.log("Skipped the daemon (--no-daemon). Its version may not match this CLI.");
+    } else {
+      const svc = await import("../src/hooks/daemon-service");
+      if (!svc.isDaemonSupportedPlatform()) {
+        console.log(`failproofaid does not run on ${process.platform}; nothing to update.`);
+      } else {
+        // `refreshDaemonToCliVersion` answers "is there a service at all" itself,
+        // so there is no separate installed check to get out of step with it.
+        const result = await svc.refreshDaemonToCliVersion();
+        for (const line of result.lines) console.log(line);
+        daemonOk = result.ok;
+      }
+    }
+
+    await track("cli_update", {
+      ok: daemonOk && !migrationFailed,
+      migrations: migrationsRan,
+      migration_failed: migrationFailed,
+    });
+    lastSubcommand = null;
+    await exitAfterFlush(daemonOk && !migrationFailed ? 0 : 1);
+    return;
+  }
+
+  if (args[0] === "uninstall") {
+    const subArgs = args.slice(1);
+    if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai uninstall — remove failproofai from this machine
+
+USAGE
+  failproofai uninstall [--purge] [--dry-run] [--yes]
+
+WHAT IT REMOVES
+  • failproofai hook entries from every agent CLI that has them
+  • the failproofaid daemon service — ASKED on a plain uninstall (kept unless
+    you say yes); always removed with --purge, which prompts for your password
+    rather than printing commands to paste
+  • the "require the daemon" flag — cleared FIRST, so a partial uninstall can
+    never leave this machine denying every tool call
+
+OPTIONS
+  --purge         Also delete ~/.failproofai — settings, credentials, audit
+                  history and the downloaded daemon binary. Off by default so a
+                  reinstall keeps your history.
+  --dry-run       Print what would be removed and change nothing.
+  --yes, -y       Skip the confirmation prompt. Required when there is no TTY.
+
+WHY THIS EXISTS
+  npm runs no uninstall script, so \`npm rm -g failproofai\` removes the package
+  and leaves the hook entries and the service behind. Run this first, then:
+      npm rm -g failproofai
+`);
+      process.exit(0);
+    }
+
+    const KNOWN = new Set(["--purge", "--dry-run", "--yes", "-y"]);
+    const unknown = subArgs.find((a) => !KNOWN.has(a));
+    if (unknown) {
+      throw new CliError(
+        `Unexpected argument: ${unknown}\nRun \`failproofai uninstall --help\` for usage.`,
+      );
+    }
+
+    lastSubcommand = "uninstall_command";
+    const { runUninstallCommand } = await import("../src/hooks/uninstall-cli");
+    const purge = subArgs.includes("--purge");
+    const dryRun = subArgs.includes("--dry-run");
+    const yes = subArgs.includes("--yes") || subArgs.includes("-y");
+
+    // Set only when the prompt actually rendered the plan, which is the one
+    // case where printing it again would duplicate it.
+    let planWasShown = false;
+    const result = await runUninstallCommand({
+      purge,
+      dryRun,
+      yes,
+      cwd: process.cwd(),
+      // Only offered when a person can actually answer. Without a TTY the
+      // command requires --yes rather than assuming consent — see the module.
+      confirm: process.stdin.isTTY
+        ? async (planLines) => {
+            planWasShown = true;
+            const { selectOne } = await import("../src/hooks/tui");
+            // "No" first, so the default landing position on Enter is the
+            // non-destructive one.
+            const answer = await selectOne({
+              message: purge
+                ? "Remove failproofai and DELETE ~/.failproofai?"
+                : "Remove failproofai from this machine?",
+              body: planLines,
+              choices: [
+                { label: "No, cancel", value: false },
+                { label: purge ? "Yes, remove and purge" : "Yes, remove it", value: true },
+              ],
+            });
+            return answer === true;
+          }
+        : undefined,
+      // Only on a plain uninstall: `--purge` removes the service unconditionally
+      // because it deletes the binary the service points at. Absent without a TTY,
+      // which the module reads as "keep it".
+      confirmDaemon:
+        process.stdin.isTTY && !purge
+          ? async () => {
+              const { selectOne } = await import("../src/hooks/tui");
+              const answer = await selectOne({
+                message: "Remove the failproofaid background service too?",
+                body: [
+                  "It runs as a system service and needs sudo to remove, so you",
+                  "will be asked for your password.",
+                  "",
+                  "Keeping it is fine if you plan to reinstall — the hooks are",
+                  "already gone either way, so nothing is being enforced.",
+                ],
+                choices: [
+                  { label: "Yes, remove the service", value: true },
+                  { label: "No, leave it installed", value: false },
+                ],
+              });
+              return answer === true;
+            }
+          : undefined,
+    });
+
+    // The prompt already rendered the plan as its body; re-printing it would
+    // show the same block twice. `planLines` is reported by the command rather
+    // than guessed from the text — see UninstallResult.
+    const skip = planWasShown ? result.planLines : 0;
+    for (const line of result.lines.slice(skip)) {
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    // NOT after a purge. `track` resolves the instance id, and `getInstanceId()`
+    // lazily WRITES ~/.failproofai/state/telemetry-id — which re-created the
+    // whole directory seconds after the purge deleted it, leaving a machine the
+    // user had just wiped holding a brand-new tracking identifier and making
+    // the command's own "✓ deleted" line false. A purge means gone; nothing
+    // gets to touch the home afterwards, least of all telemetry.
+    if (!result.purged) {
+      await track("cli_uninstall_command", {
+        ok: result.exitCode === 0,
+        purge,
+        dry_run: dryRun,
+      });
+    }
+    lastSubcommand = null;
+    await exitAfterFlush(result.exitCode);
+    return;
+  }
+
   // policies [--install|-i|--uninstall|-u|--help|-h] [names...] [--scope] [--beta] [--custom|-c <path>]
   if (args[0] === "policies") {
     const subArgs = args.slice(1);
@@ -566,19 +1374,6 @@ EXAMPLES
     process.exit(0);
   }
 
-  // auth — email-OTP login flow against the FailproofAI api-server.
-  if (args[0] === "auth") {
-    lastSubcommand = "auth";
-    const { runAuthCli } = await import("../src/auth/cli");
-    await runAuthCli(args.slice(1));
-    await track("cli_auth_invoked", {
-      args_count: args.length - 1,
-      subcommand: args[1] ?? "help",
-      exit_code: process.exitCode ?? 0,
-    });
-    process.exit(process.exitCode ?? 0);
-  }
-
   // audit — scan local agent-CLI history, then launch the dashboard at /audit.
   if (args[0] === "audit") {
     lastSubcommand = "audit";
@@ -765,23 +1560,203 @@ USAGE
 WHAT IT DOES
   Walks you through 4 quick steps and writes everything for you:
     1. Where      — global (all projects) or just this project
-    2. Assistants — which agent CLIs to protect (Claude, Codex, ...)
+    2. Harnesses  — which agent CLIs to protect (Claude, Codex, ...)
     3. Policies   — presets (combine any), Everything, or a custom pick
     4. Review     — confirms the exact files it will change, then applies
 
+FAILPROOF CLOUD
+  failproofai config --connect <url> --token <key> [--machine-id <id>]
+                                    Connect this machine to Failproof Cloud
+                                    [--no-transcripts] decisions only, no transcripts
+  failproofai config --disconnect   Stop pulling policy and sending activity
+  failproofai config --status       Show connection, daemon and pause state
+  failproofai config --pause [--session <id>]
+                                    Pause enforcement, time-boxed
+  failproofai config --resume [--all]
+                                    Resume enforcement
+
+    --machine-label <name>          Human-readable name in the dashboard
+                                    (use alone to rename an already-connected machine)
+
+  One connection, two capabilities: this machine PULLS centrally-managed
+  policies and SENDS what its hooks decided, so the dashboard shows the fleet
+  it is enforcing on. Both are checked against the server before anything is
+  written, and reported separately — a key carrying policies:pull but not
+  events:add connects for policy and says exactly why the dashboard is empty.
+
+  Tokens are stored owner-only in ~/.failproofai/, never in the service unit —
+  that file is world-readable. Connecting needs no sudo, and the machine id
+  defaults to this host's name.
+
+  Connecting sends BOTH policy decisions and full session transcripts. A
+  transcript carries prompts, file contents and whatever was pasted into a
+  terminal — that is the point of connecting, and it is stated here rather than
+  buried behind a flag nobody finds. Use --no-transcripts for decisions only.
+
+PAUSING ENFORCEMENT (one session, always time-boxed)
+  failproofai config --pause         Pause this directory's newest agent session (30m)
+  failproofai config --pause 10m     Pause for a given time (max 8h; s/m/h, bare = minutes)
+  failproofai config --resume        End the pause early
+  failproofai config --status        Show what is paused and when it lifts
+    --session <id>                     Target a specific session
+    --all                              With --resume, end every active pause
+
+  A pause suspends builtin, custom and convention policies for that session
+  only, and always expires on its own. Cloud-managed policies keep enforcing.
+
   Prefer flags? See \`failproofai policies --help\`.
 `.trimStart());
       process.exit(0);
     }
     lastSubcommand = "config";
+
+    // --pause / --resume / --status are non-interactive session actions that
+    // share `config`'s surface but not the wizard. They write session state,
+    // never the config file — a pause that reached policies-config.json would
+    // be committed and outlive the session that asked for it.
+    // Cloud enrolment. Deliberately writes a credential file the daemon reads
+    // rather than an Environment= line in the service unit: that unit is
+    // installed world-readable (0644, /etc/systemd/system), so a token there
+    // would be readable by every local user. Keeping it out also means no
+    // sudo, and lets an already-installed daemon be connected.
+    const connectIdx = args.indexOf("--connect");
+    const wantsDisconnect = args.includes("--disconnect");
+    // `--machine-label` ALONE is a rename, not an enrolment. Alongside --connect it
+    // keeps its old meaning (the name to enrol under); on its own it changes the
+    // name of a machine that is already connected, which previously required
+    // re-running enrolment with the url and token again just to fix a display name.
+    const wantsRename =
+      connectIdx < 0 && !wantsDisconnect && args.includes("--machine-label");
+    if (connectIdx >= 0 || wantsDisconnect || wantsRename) {
+      if (connectIdx >= 0 && wantsDisconnect) {
+        throw new CliError("--connect and --disconnect cannot be combined.");
+      }
+      const valueAfter = (flag) => {
+        const i = args.indexOf(flag);
+        if (i < 0) return undefined;
+        const v = args[i + 1];
+        if (!v || v.startsWith("-")) throw new CliError(`Missing value after ${flag}.`);
+        return v;
+      };
+      let result;
+      if (wantsRename) {
+        const { runRenameCommand } = await import("../src/hooks/cloud-enrollment-cli");
+        result = await runRenameCommand(valueAfter("--machine-label"));
+      } else if (wantsDisconnect) {
+        const { runDisconnectCommand } = await import("../src/hooks/cloud-enrollment-cli");
+        result = runDisconnectCommand();
+      } else {
+        const { hostname } = await import("node:os");
+        const { runConnectCommand } = await import("../src/hooks/cloud-enrollment-cli");
+        result = await runConnectCommand({
+          url: valueAfter("--connect"),
+          token: valueAfter("--token"),
+          machineId: valueAfter("--machine-id"),
+          machineLabel: valueAfter("--machine-label"),
+          defaultMachineId: hostname(),
+          // Transcripts are what connecting is FOR, so they default on and the
+          // disclosure is made at the point of connection rather than hidden
+          // behind an opt-in flag most people never discover — a dashboard
+          // showing only decisions is the empty-dashboard problem in a
+          // different costume. --no-transcripts is the explicit way out, and
+          // `failproofai config --status` always says which is in effect.
+          sessions: !args.includes("--no-transcripts"),
+        });
+      }
+      for (const line of result.lines) {
+        if (result.exitCode === 0) console.log(line);
+        else console.error(line);
+      }
+      await track("cli_cloud_enrollment", {
+        action: wantsRename ? "rename" : wantsDisconnect ? "disconnect" : "connect",
+        ok: result.exitCode === 0,
+      });
+      await exitAfterFlush(result.exitCode);
+      return;
+    }
+
+    const pauseIdx = args.indexOf("--pause");
+    const wantsResume = args.includes("--resume");
+    const wantsStatus = args.includes("--status");
+    if (pauseIdx >= 0 || wantsResume || wantsStatus) {
+      const chosen = [pauseIdx >= 0 && "--pause", wantsResume && "--resume", wantsStatus && "--status"].filter(Boolean);
+      if (chosen.length > 1) {
+        throw new CliError(`${chosen.join(" and ")} cannot be combined.`);
+      }
+      const sessionIdx = args.indexOf("--session");
+      if (sessionIdx >= 0 && !args[sessionIdx + 1]) {
+        throw new CliError("Missing session id after --session.");
+      }
+      // A bare `--pause` takes the default duration, so only treat the next
+      // token as a duration when it isn't another flag.
+      const next = pauseIdx >= 0 ? args[pauseIdx + 1] : undefined;
+      const duration = next && !next.startsWith("-") ? next : undefined;
+
+      const { runPauseCommand } = await import("../src/hooks/session-pause-cli");
+      const result = runPauseCommand({
+        action: pauseIdx >= 0 ? "pause" : wantsResume ? "resume" : "status",
+        duration,
+        sessionId: sessionIdx >= 0 ? args[sessionIdx + 1] : undefined,
+        all: args.includes("--all"),
+        cwd: process.cwd(),
+      });
+      // `--status` answers "what is this machine's state?", which is both
+      // halves: whether enforcement is paused AND whether cloud is connected.
+      if (wantsStatus) {
+        const { connectionStatusLines } = await import("../src/hooks/cloud-enrollment-cli");
+        for (const line of connectionStatusLines()) console.log(line);
+        // Always printed, including where reports can never work: "why am I
+        // not getting them?" is the question --status exists to answer, and an
+        // omitted line answers it with silence.
+        console.log("");
+      }
+      for (const line of result.lines) {
+        if (result.exitCode === 0) console.log(line);
+        else console.error(line);
+      }
+      await track("cli_pause_invoked", {
+        action: pauseIdx >= 0 ? "pause" : wantsResume ? "resume" : "status",
+        ok: result.exitCode === 0,
+        affected: result.affected,
+      });
+      await exitAfterFlush(result.exitCode);
+      return;
+    }
+
     const { runConfigureWizard } = await import("../src/hooks/configure-wizard");
     const result = await runConfigureWizard();
     await track("cli_configure_invoked", {
       applied: result.applied,
-      scope: result.scope ?? null,
+      // `target` and `scopes`, not `scope`: the wizard rework replaced that
+      // field and nothing caught it, because `.mjs` is outside the tsconfig
+      // include so `tsc --noEmit` never type-checks this file. Every
+      // `cli_configure_invoked` since has reported `scope: null`.
+      target: result.target ?? null,
+      scopes: result.scopes ?? [],
       cli_count: result.clis?.length ?? 0,
+      abort: result.abort ?? null,
     });
-    process.exit(0);
+    // `abort` is the field `WizardAbort` exists to expose, and exiting 0
+    // regardless discarded it: a fleet script could not tell "the user pressed
+    // Esc" from "this machine could not install the required daemon and is
+    // unconfigured". Cancelling is not a failure; the other two are.
+    await exitAfterFlush(!result.applied && result.abort && result.abort !== "cancelled" ? 1 : 0);
+    return;
+  }
+
+  // Shared by both "unknown thing" guards below, so a mistyped SUBCOMMAND gets
+  // the same nearest-match treatment a mistyped flag already got.
+  function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) =>
+      Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+    );
+    for (let i = 1; i <= m; i++)
+      for (let j = 1; j <= n; j++)
+        dp[i][j] = a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    return dp[m][n];
   }
 
   // Unknown flag guard — must appear after all known-flag branches
@@ -789,20 +1764,7 @@ WHAT IT DOES
   const unknownFlag = args.find(a => a.startsWith("-") && !knownFlags.includes(a));
 
   if (unknownFlag) {
-    function levenshtein(a, b) {
-      const m = a.length, n = b.length;
-      const dp = Array.from({ length: m + 1 }, (_, i) =>
-        Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
-      );
-      for (let i = 1; i <= m; i++)
-        for (let j = 1; j <= n; j++)
-          dp[i][j] = a[i - 1] === b[j - 1]
-            ? dp[i - 1][j - 1]
-            : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-      return dp[m][n];
-    }
-
-    const primary = ["--version", "--help", "--hook", "policies", "policy", "auth", "audit"];
+    const primary = ["--version", "--help", "--hook", "policies", "policy", "audit"];
     const closest = primary.reduce((best, flag) => {
       const dist = levenshtein(unknownFlag, flag);
       return dist < best.dist ? { flag, dist } : best;
@@ -818,29 +1780,27 @@ WHAT IT DOES
   // Unknown subcommand guard (non-flag args that aren't a known subcommand)
   const unknownSubcommand = args.find(a => !a.startsWith("-") && !SUBCOMMANDS.includes(a));
   if (unknownSubcommand) {
+    // Nearest match rather than a hardcoded "policies", which was wrong for
+    // every input that was not a typo of it. `auth` made that concrete: it was
+    // a real subcommand until this release, so an old script or plain muscle
+    // memory lands here, and answering "did you mean policies?" sends someone
+    // to the one command that has nothing to do with what they typed.
+    const nearest = SUBCOMMANDS.reduce(
+      (best, name) => {
+        const dist = levenshtein(unknownSubcommand, name);
+        return dist < best.dist ? { name, dist } : best;
+      },
+      { name: SUBCOMMANDS[0], dist: Infinity },
+    );
     throw new CliError(
       `Unknown command: ${unknownSubcommand}\n` +
-      `Did you mean: failproofai policies?\n` +
+      `Did you mean: failproofai ${nearest.name}?\n` +
       `Run \`failproofai --help\` for usage details.`
     );
   }
 
-  // First-run onboarding — on the first bare `failproofai` invocation, run the
-  // configure wizard (which also fires the post-setup audit) BEFORE the
-  // dashboard. Unlike before, we then fall through to launch the dashboard, so a
-  // fresh user gets: setup → audit → dashboard, and every later `failproofai`
-  // goes straight to the dashboard. Best-effort: any error must not block launch.
-  if (args.length === 0) {
-    try {
-      const { maybeFirstRunConfigure } = await import("../src/hooks/configure-wizard");
-      await maybeFirstRunConfigure();
-    } catch {
-      // First-run onboarding is non-critical; fall through to the dashboard.
-    }
-  }
-
   // Dashboard launch — always production mode. Runs on every bare `failproofai`
-  // (after first-run onboarding, if any).
+  // (first-run onboarding, if any, already ran above).
   const { launch } = await import("../scripts/launch");
   launch("start");
 }