failproofai 1.0.0-beta.14 → 1.0.0-beta.16

package/src/hooks/fp-reset.ts

@@ -2,11 +2,33 @@
  * What happens when this CLI meets a home directory written by a different
  * layout.
  *
- * The decision was wipe-and-re-setup rather than migrate. A migration has to
- * be right on every path or it half-moves a home, and a half-moved home fails
- * in the worst available way: the daemon writes where the dashboard does not
- * read, and an absent directory is indistinguishable from an idle one. A reset
- * is one destructive operation that is either done or not done.
+ * ## This was wipe-and-re-setup. It is a migration now.
+ *
+ * The original decision, and the reasoning for it, was: a migration has to be
+ * right on every path or it half-moves a home, and a half-moved home fails in the
+ * worst available way — the daemon writes where the dashboard does not read, and
+ * an absent directory is indistinguishable from an idle one. A reset is one
+ * destructive operation that is either done or not done.
+ *
+ * That was correct while there were no customers, no cloud tokens on real
+ * machines, no fleet enrolment and no undelivered event spools. All four now
+ * exist, and the cost landed on the other side of the ledger: a wipe deleted the
+ * cloud token (so the machine dropped off the fleet, silently, still reporting
+ * healthy), `daemon.configured` (so it stopped failing closed), every
+ * `extra_paths` a person had typed, and events already read out of transcripts
+ * and queued — the last of those PERMANENTLY, because `cursors/` survived and the
+ * watermark had already moved past them.
+ *
+ * So the shape inverted. `HOME_CLASSES` in `fp-home.ts` classifies every path by
+ * what it HOLDS and the delete list is derived from that, which means the default
+ * is now "carried" and deletion is the exception a class has to earn. The
+ * half-moved-home worry is answered by keeping the property that made a reset
+ * safe: `VERSION` is stamped only after a step completes, so a step that fails
+ * leaves the home marked with the OLD layout and the next command retries it. No
+ * home is ever marked current on the strength of a partial migration.
+ *
+ * `migrations.ts` owns the ORDER and the record — which steps exist, which ran,
+ * and what was copied aside first. This file owns the MOVES.
  *
  * ## Where the deletion happens, and where it deliberately does not
  *
@@ -49,10 +71,23 @@ import {
   globalPolicyConfigFile,
   hookActivityDir,
   legacy,
+  migrationBackupDir,
   policiesDir,
   resettablePaths,
 } from "./fp-home";
-import { detectLayout, readConfig, updateConfig, writeVersionFile, type LayoutState } from "./fp-config";
+import {
+  detectLayout,
+  projectConfig,
+  projectCredentials,
+  readConfig,
+  updateConfig,
+  writeConfig,
+  writeCredentials,
+  writeVersionFile,
+  type FpConfig,
+  type FpCredentials,
+  type LayoutState,
+} from "./fp-config";
 import {
   daemonServiceStatus,
   daemonStatusCommand,
@@ -278,30 +313,23 @@ export function migrateHookActivity(): string[] {
 }
 
 /**
- * Fields of layout 1's `policies-config.json` that layout 2's still means.
+ * The eight keys the layout-2 carry used to move, kept only as a record.
+ *
+ * It was an ALLOWLIST, and that was the bug: anything outside these eight names
+ * was dropped, including a key a NEWER build had written into a layout-2 file.
+ * The carry preserves every key now and deletes only the retired ones
+ * (`RETIRED_POLICY_CONFIG_KEYS`), which is the same rule `writeConfig` follows for
+ * `config.json` — unowned keys survive, dead ones go.
  *
- * An allowlist, not a copy, and the exclusion is the point: layout 1's file
- * ALSO carried a `collector` block, and layout 2 moved collector settings to
- * `[collector]` in `config.toml` — in snake_case, deliberately, because
+ * The one exclusion this list existed for is still enforced, by that other
+ * constant: layout 1's file also carried a `collector` block, and layout 2 moved
+ * collector settings to `config.toml` in snake_case — deliberately, because
  * `fpai-collect`'s `Settings` deserializes them and camelCase keys would make
  * every field silently fall back to its default (see the note on `Settings` in
  * `crates/fpai-collect/src/config.rs`, which records that exact bug). Carrying
  * `collector` forward would put a block into the new file that nothing reads,
- * where it would look like a preserved setting and behave like an absent one.
- *
- * The `llm` block moves because the loader still reads it from here, and its
- * value is an endpoint and a model name a person configured by hand.
+ * looking like a preserved setting and behaving like an absent one.
  */
-const CARRIED_POLICY_CONFIG_KEYS = [
-  "enabledPolicies",
-  "customPoliciesPaths",
-  "customPoliciesPath",
-  "disabledCustomPolicies",
-  "conventionPolicies",
-  "disabledConventionPolicies",
-  "policyParams",
-  "llm",
-] as const;
 
 /**
  * Carry the user's policy SELECTION across the layout-1 → layout-2 move.
@@ -336,20 +364,75 @@ const CARRIED_POLICY_CONFIG_KEYS = [
  *
  * So: READ before, WRITE after.
  */
+/**
+ * Keys the policy config used to hold that nothing reads any more.
+ *
+ * `collector` is the whole list, and it is why the layout-1 carry was an
+ * ALLOWLIST rather than a copy: layout 1 kept collector settings here in
+ * camelCase, and layout 2 moved them to `config.toml`/`config.json` in
+ * snake_case, where `fpai-collect`'s `Settings` deserializes them. A camelCase
+ * `collector` block sitting in the layout-3 file reads as a preserved setting and
+ * does nothing — the worst of both, because it looks answered.
+ *
+ * A NAMED list, not "everything outside the keep-list". The file survives the
+ * reset now (`HOME_CLASSES` classes it `user-typed`), so dropping by exclusion
+ * would delete every key a NEWER build had written — which is the bug Phase 1
+ * fixed for `config.json`, arriving here by a different door.
+ */
+const RETIRED_POLICY_CONFIG_KEYS = ["collector"] as const;
+
+/**
+ * Remove the retired keys from the policy config, in place.
+ *
+ * Runs regardless of which layout we came from: a key is retired or it is not,
+ * and a layout-2 home carrying a stray layout-1 root file should be cleaned the
+ * same way. Returns what it removed.
+ *
+ * The file is DELETED if stripping empties it — a `{}` policy config is not a
+ * selection, and the old behaviour for a file holding nothing but `collector`
+ * was no file at all.
+ */
+export function retirePolicyConfigKeys(): string[] {
+  const at = globalPolicyConfigFile();
+  let parsed: Record<string, unknown>;
+  try {
+    const raw = JSON.parse(readFileSync(at, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
+    parsed = raw as Record<string, unknown>;
+  } catch {
+    // Absent or unparseable. Not worth aborting a reset over, and there is
+    // nothing to retire — the same answer the carry gives for the same input.
+    return [];
+  }
+  const removed = RETIRED_POLICY_CONFIG_KEYS.filter((k) => parsed[k] !== undefined);
+  if (removed.length === 0) return [];
+  for (const key of removed) delete parsed[key];
+  try {
+    if (Object.keys(parsed).length === 0) rmSync(at, { force: true });
+    else writeFileSync(at, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+  } catch {
+    // A file we cannot rewrite keeps its dead key. Misleading, but not fatal,
+    // and not worth failing the migration over.
+    return [];
+  }
+  return [...removed];
+}
+
 export function readCarriedPolicyConfig(): Record<string, unknown> | null {
-  const to = globalPolicyConfigFile();
-  // NEWEST SOURCE WINS. Two older layouts kept this file in two places, and a
-  // home being upgraded may hold either:
+  // LAYOUT 2's NESTED COPY ONLY — `policies/local-policies/policies-config.json`.
   //
-  //   layout 2 — `policies/local-policies/policies-config.json`
-  //   layout 1 — `policies-config.json` at the home root
+  // This used to prefer that path and fall back to `legacy.policyConfig()`, the
+  // layout-1 file at the home root. That fallback is gone because the file is:
+  // layout 3 puts the live config back at exactly that path, `HOME_CLASSES`
+  // classes it `user-typed`, and it is no longer deleted — so a layout-1 home
+  // keeps it untouched, with EVERY key rather than the eight this function knows
+  // to carry. Reading it here and writing it back would be the only thing that
+  // could still narrow it.
   //
-  // Layout 3 puts it back at the ROOT, so layout 1's path and the destination
-  // are now the same file. Reading layout 1's copy while a layout-2 one exists
-  // would carry the OLDER answer forward and silently undo whatever the user
-  // chose since — so layout 2's nested file is preferred whenever it is there.
-  const layoutTwo = resolve(legacy.localPoliciesDir(), "policies-config.json");
-  const from = existsSync(layoutTwo) ? layoutTwo : legacy.policyConfig();
+  // Layout 2's copy is different: `legacy.localPoliciesDir()` is on the retired
+  // list and really is deleted, so without this it is lost. A home cannot hold
+  // both — layout 2 never wrote the root file, and going 1 → 2 removed it.
+  const from = resolve(legacy.localPoliciesDir(), "policies-config.json");
   if (!existsSync(from)) return null;
 
   let parsed: Record<string, unknown>;
@@ -363,17 +446,23 @@ export function readCarriedPolicyConfig(): Record<string, unknown> | null {
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
 
+  // EVERY key except the retired ones. This was an eight-name ALLOWLIST, and it
+  // dropped anything outside it — including a key a NEWER build had written into a
+  // layout-2 file, which is the same loss Phase 1 fixed for `config.json` arriving
+  // by a third door. Caught by a smoke test on a seeded home: a `futureKey` in the
+  // nested config was gone after the migration, silently.
+  //
+  // Retired keys still go, because they are dead rather than unknown — see
+  // `RETIRED_POLICY_CONFIG_KEYS` for why leaving `collector` here is worse than
+  // deleting it.
   const carried: Record<string, unknown> = {};
-  let found = false;
-  for (const key of CARRIED_POLICY_CONFIG_KEYS) {
-    if (parsed[key] !== undefined) {
-      carried[key] = parsed[key];
-      found = true;
-    }
+  for (const [key, value] of Object.entries(parsed)) {
+    if ((RETIRED_POLICY_CONFIG_KEYS as readonly string[]).includes(key)) continue;
+    carried[key] = value;
   }
-  // Nothing worth carrying — a file holding only excluded fields must not
-  // produce an empty layout-2 config that looks like a real one.
-  if (!found) return null;
+  // Nothing worth carrying — a file holding only retired fields must not produce
+  // an empty config that looks like a real one.
+  if (Object.keys(carried).length === 0) return null;
 
   // `enabledPolicies` is required by the type and by every reader. A layout-1
   // file that somehow lacked it would otherwise produce a layout-2 file that
@@ -382,13 +471,30 @@ export function readCarriedPolicyConfig(): Record<string, unknown> | null {
   return carried;
 }
 
-/** Second phase of {@link readCarriedPolicyConfig}; runs AFTER the deletions. */
+/**
+ * Second phase of {@link readCarriedPolicyConfig}; runs AFTER the deletions.
+ *
+ * MERGES onto whatever is at the destination rather than replacing it. The
+ * destination is `user-typed` now and survives the reset, so a plain write would
+ * truncate a live file down to the keys this carry happens to know about — the
+ * same class of loss the carry exists to prevent, arriving by the other door.
+ * The carried values still win: they are the ones being migrated.
+ */
 export function writeCarriedPolicyConfig(carried: Record<string, unknown> | null): string[] {
   if (!carried) return [];
   const to = globalPolicyConfigFile();
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(readFileSync(to, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      existing = parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Absent or unparseable — the carry is the whole file, as before.
+  }
   try {
     mkdirSync(dirname(to), { recursive: true });
-    writeFileSync(to, JSON.stringify(carried, null, 2) + "\n", "utf8");
+    writeFileSync(to, JSON.stringify({ ...existing, ...carried }, null, 2) + "\n", "utf8");
   } catch {
     // A destination we cannot write is not worth aborting the reset over; the
     // user re-runs setup, which is the pre-existing behaviour.
@@ -455,25 +561,201 @@ export function readCarriedTelemetryOptOut(): boolean {
   }
 }
 
+/**
+ * Parse the TOML subset layout 2 actually wrote, into the object shape layout 3
+ * parses out of JSON.
+ *
+ * NOT a TOML implementation, and it does not need to be: layout 2's `config.toml`
+ * and `credentials.toml` were written by this codebase, by two functions that
+ * emitted nothing but `[table]` / `[dotted.table]` headers and `key = <value>`
+ * lines where every value went through `JSON.stringify`. So `JSON.parse` on the
+ * right-hand side is EXACT rather than approximate — strings, booleans, numbers
+ * and the one array (`extra_paths`) all round-trip by construction. Removing the
+ * `toml` dependency was half the point of layout 3; adding it back to read two
+ * files we wrote ourselves would undo that.
+ *
+ * The output uses layout 2's own snake_case key names, unchanged, because layout
+ * 3's JSON uses exactly the same ones (`hooks_verbosity`, `machine_id`,
+ * `interval_days`, `sources.<h>.extra_paths`). That is what lets the carry run
+ * `projectConfig` / `projectCredentials` — the SAME projections the JSON readers
+ * use — instead of a second reader that would have to be kept in step. The only
+ * thing that differs between the two layouts is how bytes become an object.
+ *
+ * A dotted header nests: `[collector.sources.claude]` lands at
+ * `collector.sources.claude`, which is where `readSources` looks for it.
+ * Anything unparseable is skipped rather than throwing, because a single
+ * malformed line must not cost the user the whole file.
+ */
+export function parseLegacyToml(text: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  let table = root;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const header = /^\[([^\]]+)\]$/.exec(line);
+    if (header) {
+      table = root;
+      for (const part of header[1].split(".")) {
+        const key = part.trim();
+        if (!key) break;
+        const existing = table[key];
+        if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+          table = existing as Record<string, unknown>;
+        } else {
+          const created: Record<string, unknown> = {};
+          table[key] = created;
+          table = created;
+        }
+      }
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key) continue;
+    try {
+      table[key] = JSON.parse(line.slice(eq + 1).trim()) as unknown;
+    } catch {
+      // A value this codebase did not write, or a hand-edit that broke it. Skip
+      // the line; the projection then falls back to that field's default, which
+      // is the same answer an absent key gets.
+    }
+  }
+  return root;
+}
+
+/**
+ * Carry the whole layout-2 `config.toml` across, not just the telemetry opt-out.
+ *
+ * `readCarriedTelemetryOptOut()` above rescued one field, and the reason it was
+ * only one was that the rest was described as "re-derived by setup or a thing the
+ * wizard re-asks". That is true of a machine whose owner is about to re-run
+ * setup, and false of every other machine — `config.toml` also holds:
+ *
+ *   mode                    a machine reverting to `oss` stops reporting entirely
+ *   daemon.configured       the flag that makes the machine FAIL CLOSED
+ *   collector.*             sessions/hooks/verbosity/redact/environment/machine_id
+ *   collector.sources.*     every extra_paths a person typed
+ *   audit.auto/interval     the scheduled scan they switched on
+ *
+ * Losing `daemon.configured` silently downgrades a machine from fail-closed
+ * enforcement to the in-process path, and losing `mode` disconnects it from the
+ * fleet — neither with any message, and neither re-derivable without a human.
+ * Those are the same failures `HOME_CLASSES` stopped for `config.json`; this is
+ * the layout-2 leg of the same problem, in the other format.
+ *
+ * Read BEFORE the deletions (the source is on the retired list), applied after.
+ */
+export function readCarriedLegacyConfig(): FpConfig | null {
+  const from = legacy.configToml();
+  if (!existsSync(from)) return null;
+  try {
+    return projectConfig(parseLegacyToml(readFileSync(from, "utf8")));
+  } catch {
+    // Unreadable is not worth aborting a reset over, and the telemetry carry
+    // below still gets its own chance at the same bytes.
+    return null;
+  }
+}
+
+/**
+ * Carry the layout-2 `credentials.toml` across.
+ *
+ * This is the one that takes a machine off the fleet. `credentials.toml` is on
+ * the retired list and NOTHING carried it, so a layout-2 → 3 upgrade deleted the
+ * cloud token and the ingest key outright: the machine stops reconciling
+ * cloud-managed policy, stops delivering anything it spools, and says nothing —
+ * it keeps enforcing whatever it last had and keeps reporting healthy. On a fleet
+ * that is every box going quiet at once, with no operator action that caused it.
+ *
+ * `HOME_CLASSES` classes `credentials.json` `user-typed` so this cannot happen
+ * again from layout 3 onwards, but 2 → 3 is the upgrade that actually exists to
+ * be run, and it needed this.
+ *
+ * Written through `writeCredentials`, so the file lands 0600 with the home
+ * tightened to 0700 — a token must not arrive here by a path that skips that.
+ */
+export function readCarriedLegacyCredentials(): FpCredentials | null {
+  // NEWEST SOURCE WINS, and both older layouts have to be handled here because
+  // BOTH of their credential files are on the retired list with nothing else
+  // carrying them:
+  //
+  //   layout 2 — `credentials.toml`, one file, TOML
+  //   layout 1 — `cloud.json` + `ingest.json`, two files, JSON, camelCase
+  //
+  // Layout 1 is the one that matters most in practice: the published `latest`
+  // npm tag is still a pre-daemon 0.0.x release, so "install the current stable,
+  // then upgrade" is a LAYOUT-1 → 3 migration, which makes this the upgrade real
+  // users actually perform. Losing the token there takes the machine off the
+  // fleet exactly as the layout-2 case does — silently, still enforcing whatever
+  // it last had, still reporting healthy.
+  const toml = legacy.credentialsToml();
+  if (existsSync(toml)) {
+    try {
+      const creds = projectCredentials(parseLegacyToml(readFileSync(toml, "utf8")));
+      // An empty object means the file held nothing that passed validation — a
+      // cloud table with no token, say. Writing that would create a credentials
+      // file that looks present and authenticates nothing.
+      if (Object.keys(creds).length > 0) return creds;
+    } catch {
+      // Fall through to layout 1's files rather than returning: an unreadable
+      // layout-2 file is not evidence that a layout-1 one is absent.
+    }
+  }
+
+  // Layout 1. `machineId` is CAMELCASE in `cloud.json` — layout 2 moved to
+  // snake_case — so the raw object is rebuilt in the shape `projectCredentials`
+  // reads rather than passed through. Reusing that projection is the point: "a
+  // cloud block without a token is not a cloud block" is a security property,
+  // and a second validator here is how a half-written credential comes to be
+  // treated as live.
+  const readJson = (path: string): Record<string, unknown> | null => {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : null;
+    } catch {
+      return null;
+    }
+  };
+  const cloud = readJson(legacy.cloudCredentials());
+  const ingest = readJson(legacy.ingestCredentials());
+  if (!cloud && !ingest) return null;
+  const raw: Record<string, unknown> = {};
+  if (cloud) {
+    raw.cloud = {
+      url: cloud.url,
+      machine_id: cloud.machineId,
+      token: cloud.token,
+      // Layout 1 had no machine label; absent is correct rather than empty.
+      ...(typeof cloud.machineLabel === "string" ? { machine_label: cloud.machineLabel } : {}),
+    };
+  }
+  if (ingest) raw.ingest = { url: ingest.url, key: ingest.key };
+  const creds = projectCredentials(raw);
+  return Object.keys(creds).length > 0 ? creds : null;
+}
+
 export function resetHome(from: number): ResetOutcome {
   // BEFORE the deletions, so a file that is mid-move is never one the reset
   // then walks over.
   const migrated = migrateConventionPolicies();
   const activity = migrateHookActivity();
   const pendingPolicyConfig = readCarriedPolicyConfig();
-  // Read before the deletions for the same reason as the policy config: its
-  // source (`config.toml`) is on the list below.
+  // Read before the deletions for the same reason as the policy config: their
+  // sources (`config.toml`, `credentials.toml`) are both on the list below.
+  const pendingConfig = readCarriedLegacyConfig();
+  const pendingCredentials = readCarriedLegacyCredentials();
   const telemetryOptOut = readCarriedTelemetryOptOut();
   const removed: string[] = [];
   for (const path of resettablePaths()) {
-    // A reset FROM the current layout is not a layout migration, and the only
-    // thing under `local-policies/` is the user's enabled-policy selection.
-    // Clearing it is right when moving off an old layout (setup re-asks) and
-    // wrong when nothing is being migrated — there it would silently discard a
-    // current, valid selection, including one this function had just carried.
-    // The single production caller always passes a DETECTED stale layout, so
-    // this only ever changes the forced same-layout case.
-    if (from === LAYOUT_VERSION && path === globalPolicyConfigFile()) continue;
+    // The guard that stood here skipped `globalPolicyConfigFile()` when the
+    // reset was not a layout migration, because clearing a current, valid
+    // policy selection is only right when setup is about to re-ask. That path is
+    // `user-typed` in `HOME_CLASSES` now and therefore never on this list at
+    // all, for either kind of reset — so the special case has nothing left to
+    // guard. See the `legacy.policyConfig()` note in `retiredLayoutPaths()`.
     if (!existsSync(path)) continue;
     try {
       rmSync(path, { recursive: true, force: true });
@@ -485,8 +767,21 @@ export function resetHome(from: number): ResetOutcome {
     }
   }
   const policyConfig = writeCarriedPolicyConfig(pendingPolicyConfig);
-  // After the deletions, onto the fresh config, so the upgrade cannot revoke a
+  // AFTER the carry, so a layout-2 value that happens to be named `collector`
+  // is retired too rather than surviving because it arrived a moment later.
+  retirePolicyConfigKeys();
+  // After the deletions, onto the fresh files, so the upgrade cannot revoke a
   // choice the user made.
+  //
+  // The credentials go first and unconditionally: `daemon.configured` below makes
+  // the machine fail closed, and a machine that fails closed against a fleet it
+  // can no longer authenticate to is worse than either half alone.
+  if (pendingCredentials) writeCredentials(pendingCredentials);
+  if (pendingConfig) writeConfig(pendingConfig);
+  // AFTER the config carry, or a carried `telemetry.enabled: true` — the default,
+  // which is not a choice anyone made — would overwrite the opt-out this reads
+  // straight out of the same file. Both paths end at the same key, and only one
+  // of them represents something a person typed.
   if (telemetryOptOut) updateConfig({ telemetry: { enabled: false } });
   writeVersionFile();
   return { removed, migrated, activity, policyConfig, from };
@@ -499,15 +794,32 @@ export interface LayoutCheck {
   /** True when the caller should stop rather than continue. */
   fatal: boolean;
   /**
-   * True when this call actually reset the home.
+   * True when this call actually migrated the home.
+   *
+   * **Reporting only. The caller must NOT force setup on it.**
    *
-   * The caller must force setup when it is set. A reset removes the global
-   * policy config, but `isConfigured()` is a union that also counts the agent
-   * CLIs' settings files — which the reset deliberately leaves alone — so the
-   * machine still reads as configured, the wizard is skipped, and
-   * `markLauncherSeen()` back-fills the marker so every later run skips it too.
-   * The user is left with hooks firing on every tool call against no policies
-   * at all, and nothing ever says so again.
+   * It used to mean "force the wizard", and the reason was a real gap: the reset
+   * removed the global policy config while `isConfigured()` is a union that also
+   * counts the agent CLIs' settings files — which the reset deliberately leaves
+   * alone — so the machine read as configured, the wizard was skipped, and
+   * `markLauncherSeen()` back-filled the marker so every later run skipped it
+   * too. The user was left with hooks firing on every tool call against no
+   * policies at all, and nothing ever said so again.
+   *
+   * That gap is closed at the source. `policies-config.json`, `config.json` and
+   * `credentials.json` are `user-typed` in `HOME_CLASSES` and are no longer
+   * removed, so after a migration `isConfigured()` is true because the machine
+   * genuinely IS configured — its policy selection, its `daemon.configured`
+   * flag and its cloud enrolment all survived. Everything the migration still
+   * drops (audit cache, cloud deployments, daemon scratch) is re-derived or
+   * re-fetched with nobody present.
+   *
+   * Forcing setup from here would now mean opening an interactive wizard for a
+   * machine with nothing to answer — and on the machines that matter most (a
+   * fleet box, a CI runner, a headless gateway) there is nobody to answer it. A
+   * home that genuinely never finished setup still reaches the wizard by the
+   * ordinary route: `isConfigured()` is false for it, so `shouldOfferFirstRun`
+   * fires on its own. That is why forcing was redundant even before it was wrong.
    */
   didReset: boolean;
 }
@@ -520,6 +832,61 @@ export interface LayoutCheck {
  * written by a NEWER CLI holds data this build cannot read but a simple
  * upgrade could, and deleting it would destroy something recoverable.
  */
+/**
+ * Deliver what is already spooled, immediately AFTER the migration.
+ *
+ * The order is the whole subtlety here, and the obvious one is wrong. Flushing
+ * FIRST reads intuitive — get the events out before touching the disk — and it
+ * cannot work: everything a flush needs to run is in a file the stale layout
+ * hasn't got. `readConfig()` reads `config.json` and `readIngestCredential()`
+ * reads `credentials.json`, both of which are LAYOUT-3 files, and a stale home by
+ * definition has neither. Called before the migration, the flush would find no
+ * ingest credential on every machine it ever ran on, refuse, and report nothing
+ * pending — a step that looks like it protects data and is structurally incapable
+ * of doing anything at all.
+ *
+ * Afterwards, both files exist: `readCarriedLegacyCredentials()` has just put the
+ * token back and `readCarriedLegacyConfig()` the mode. So this runs where it can
+ * actually succeed.
+ *
+ * What makes that safe rather than a gamble is that this is NOT the thing
+ * protecting the events. `HOME_CLASSES` classes the spool `undelivered`, so it
+ * survives the migration whatever happens here — losing it would be permanent,
+ * because `cursors/` survives too and the watermark has already advanced past
+ * every batch in it. This is the difference between "delivered" and "delivered on
+ * the next collector pass", which matters only because 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) and somebody standing at a dashboard cannot tell
+ * "not yet" from "not working".
+ *
+ * BEST-EFFORT BY CONSTRUCTION. `runFlushCommand` refuses, with its own message
+ * and a non-zero code, on every machine where a flush cannot work: collection
+ * off, no ingest credential, an unsupported platform, no daemon listening. All of
+ * those are ordinary here rather than errors, so the result is read for its COUNT
+ * and its exit code discarded. Bounded at 30s: this sits in front of a command
+ * the user typed, and a spool that will not drain is not a reason to hold their
+ * terminal.
+ */
+async function drainSpoolAfterMigrating(): Promise<number> {
+  try {
+    // Cheap gates first, so an OSS machine and one that never connected cost
+    // nothing at all — no dynamic import, no daemon probe. Read AFTER the
+    // migration, so these see the carried values rather than the defaults a
+    // missing layout-3 file would have produced.
+    const cfg = readConfig();
+    if (cfg.mode !== "cloud") return 0;
+    if (!cfg.collector.hooks && !cfg.collector.sessions) return 0;
+    const { runFlushCommand } = await import("./flush-cli");
+    const result = await runFlushCommand({ wait: true, timeoutSecs: 30 });
+    return result.pending;
+  } catch {
+    // A flush that throws is not a migration failure. Reported as "nothing
+    // pending" because the number only adds a line to a message, and inventing a
+    // count from a failed probe would be worse than saying nothing.
+    return 0;
+  }
+}
+
 export async function checkLayoutForCli(): Promise<LayoutCheck> {
   const state = detectLayout();
 
@@ -539,7 +906,18 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
   }
 
   if (state.kind === "stale") {
-    const { removed, migrated, activity } = resetHome(state.found);
+    // Through the registry, not `resetHome` directly. The two look identical for
+    // today's layouts — the chain from 1 or 2 is one step, and that step IS
+    // `resetHome` — and they stop being identical the moment a layout 4 exists,
+    // at which point this call site needs no change. It also means every
+    // migration this machine has ever run is recorded, and the irreplaceable
+    // files are copied aside first. See `migrations.ts`.
+    const { runMigrations } = await import("./migrations");
+    const run = runMigrations(state.found);
+    const { removed, migrated, activity } = run.outcome;
+    // After, not before — see the function's own note for why the intuitive
+    // order cannot work.
+    const pending = await drainSpoolAfterMigrating();
     return {
       state,
       fatal: false,
@@ -547,11 +925,15 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
       lines: [
         `failproofai reorganised ${failproofaiHome()} in this version.`,
         // "activity history" was in this sentence while the reset was deleting
-        // it. It is carried over now, so the message says what was KEPT as well
-        // as what went — a user who reads "removed" and nothing else has no way
-        // to know their decision log survived.
-        `Removed ${removed.length} item(s) from the old layout — policy config and`,
-        `audit cache. Your daemon binary and decision history were kept.`,
+        // it, and "policy config" stayed in it after that file stopped being
+        // removed. Both are the same failure: a message describing a delete list
+        // it is not derived from. It names the CLASSES now, which is what
+        // `HOME_CLASSES` actually decides — so it cannot drift again without the
+        // rule itself changing.
+        `Removed ${removed.length} item(s) that this version rebuilds — the audit`,
+        `cache, cloud deployments (re-fetched on the next poll) and daemon scratch.`,
+        `Your settings, cloud enrolment, policy selection, decision history,`,
+        `undelivered events and daemon binary were all kept.`,
         // Named individually rather than counted. These are files a person
         // wrote; "moved 3 items" is not something you can check at a glance,
         // and the whole point of saying it is that they can.
@@ -573,8 +955,35 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
               `Carried ${activity.length} page(s) of decision history into ${hookActivityDir()}.`,
             ]
           : []),
-        ``,
-        `Run \`failproofai config\` to set up again.`,
+        // Said only when a backlog actually survived the flush. Silence here
+        // would be the wrong kind: the events are safe, but "safe" and
+        // "delivered" are different states and only one of them shows up on a
+        // dashboard. Naming the count is what stops a user reading an incomplete
+        // dashboard as data loss.
+        ...(pending > 0
+          ? [
+              ``,
+              `${pending} batch(es) were still undelivered and were carried across.`,
+              `They ship on the next collector pass — \`failproofai flush --wait\` now if you`,
+              `are waiting on a dashboard.`,
+            ]
+          : []),
+        // A step that threw leaves the home marked with the OLD layout, so the
+        // next command tries again — which is right, and is also why this must
+        // say so rather than let a partial migration pass for a finished one.
+        ...(run.failed
+          ? [
+              ``,
+              `Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`,
+              `The home is still marked layout ${state.found} and will be retried. Copies of`,
+              `your settings and enrolment were saved first, in ${migrationBackupDir(state.found)}.`,
+            ]
+          : []),
+        // No "run `failproofai config` to set up again". There is nothing to set
+        // up: the settings, the enrolment and the policy selection all survived,
+        // so the machine enforces exactly as it did before this command ran. A
+        // home that genuinely never finished setup reaches the wizard through
+        // `shouldOfferFirstRun`, which reads `isConfigured()` — see `didReset`.
       ],
     };
   }