failproofai 1.0.0 → 1.0.1-beta.0

package/src/hooks/fp-home.ts

@@ -56,7 +56,12 @@
  *   policies/                every policy: the user's *.mjs sit directly here
  *     cloud-policies/        the fleet's — flat: active.json, desired-state.json, artifacts/
  *   cursors/<source>/        per-source collector watermarks
- *   audit/                   audit report + per-session cache
+ *   audit/                   MIXED — see the classification note below
+ *     dashboard.json         last result          (derived)
+ *     cache/                 per-transcript cache (derived)
+ *     schedule.json          daemon's scan timer  (derived)
+ *     session.json    0600   the signed-in user   (user-typed)
+ *     machine.json           this machine's report identity (identity)
  *   hook-activity/           decision log the dashboard reads
  *   custom-agents/           SDK spool (events/ + failed/)
  *   run/                     sockets + flock  — MUST stay shallow, see below
@@ -88,9 +93,17 @@ import { resolve } from "node:path";
  * yields "no data" instead of an error.
  *
  * 1 — the original flat/`cache`-based layout, through 1.0.0-beta.5.
- * 2 — this file.
+ * 2 — `config.toml` / `credentials.toml`, policies nested two levels down.
+ * 3 — JSON config + credentials, policies flattened back up.
+ * 4 — everything the audit owns moved under `audit/`: the signed-in session
+ *     (from `auth.json`), the daemon's scan timer (from
+ *     `state/audit-schedule.json`), and the re-audit reminder (from
+ *     `next-audit.json`, parked at `audit/reminder.json` and retired in the
+ *     same release — see `legacy.auditReminder`). The point is that one
+ *     directory now answers "what does the audit know about this machine", the
+ *     way `policies/` answers it for enforcement.
  */
-export const LAYOUT_VERSION = 3;
+export const LAYOUT_VERSION = 4;
 
 /**
  * `~/.failproofai`, or `FAILPROOFAI_HOME`.
@@ -212,10 +225,54 @@ export const customAgentsFailedDir = (home?: string) => resolve(customAgentsDir(
 
 // ── Audit ────────────────────────────────────────────────────────────────────
 
+/**
+ * Everything the audit owns, and a MIXED directory as of layout 4.
+ *
+ * `auditDir` is deliberately NOT classified in `HOME_CLASSES`, for exactly the
+ * reason `stateDir` is not: it now holds a credential and a machine identity
+ * alongside two caches, so one class cannot be right for all of it. Before
+ * layout 4 the whole directory was `derived` — correct then, and the trap the
+ * moment `session.json` moved in, because `resettablePaths()` is a filter over
+ * that table and would have deleted the user's tokens on every reset and every
+ * future migration. Classify the CHILDREN; never the parent.
+ */
 export const auditDir = (home?: string) => atHome(home, "audit");
 export const auditDashboardFile = (home?: string) => resolve(auditDir(home), "dashboard.json");
 export const auditCacheDir = (home?: string) => resolve(auditDir(home), "cache");
 
+/**
+ * The signed-in user's tokens. `0600`, written only by the dashboard's auth
+ * routes and the audit child (`lib/auth/auth-store.ts`).
+ *
+ * Layout 3 kept this at the home root as `auth.json`, where it was invisible to
+ * `HOME_CLASSES` altogether — neither classified nor deleted, safe by accident
+ * rather than by decision. It is `user-typed`: nothing regenerates a session,
+ * and dropping it silently signs the machine out.
+ *
+ * TS-only, so it is absent from `paths.rs` by design: the daemon never opens
+ * it. The audit child does the reporting precisely so the daemon holds no human
+ * credential — see `audit_lane.rs`.
+ */
+export const auditSessionFile = (home?: string) => resolve(auditDir(home), "session.json");
+
+/**
+ * This machine's report identity: the id the api-server keys reports on, and
+ * the watermark saying how far the last digest reached.
+ *
+ * SEPARATE from `auditSessionFile` on purpose, and the separation is the whole
+ * design. Both fields have to outlive a sign-out: regenerate the id and the
+ * server sees a brand-new machine and burns a slot off the account's cap on
+ * every logout; reset the watermark and the next digest re-reports months of
+ * history as though it just happened. So this is `identity` — never deleted,
+ * like `cursors/` and `telemetryIdFile` — while the tokens beside it come and
+ * go with the session.
+ *
+ * Minted fresh rather than reusing `telemetryIdFile`, so opting into emailed
+ * reports never links the anonymous telemetry person to a verified address.
+ */
+export const auditMachineFile = (home?: string) => resolve(auditDir(home), "machine.json");
+
+
 // ── Hook activity ────────────────────────────────────────────────────────────
 
 /** The decision log: page-sized JSONL the dashboard's activity tab reads. */
@@ -270,10 +327,17 @@ export const sessionPauseDir = () => resolve(stateDir(), "sessions");
  * mirrors this path in `paths.rs`) — it owns the schedule, and a second writer
  * racing it could hand a machine two full scans back to back. Everything on this
  * side reads it: the interval itself lives in `config.json`'s `audit` object,
- * which a human edits, while this file is derived state a human never opens,
- * which is why it sits under `state/` rather than beside the audit results.
+ * which a human edits, while this file is derived state a human never opens.
+ *
+ * Layout 4 moved it out of `state/` and in beside the audit results. It stays
+ * `derived` — losing it costs one rescheduled scan, nothing more — but it now
+ * sits with the rest of what the audit owns rather than in the daemon's scratch
+ * drawer, which is what makes `audit/` answerable as one directory.
+ *
+ * Declared here, below `stateDir`, only because the section order of this file
+ * is historical; the path itself is under `auditDir`.
  */
-export const auditScheduleFile = (home?: string) => resolve(stateDir(home), "audit-schedule.json");
+export const auditScheduleFile = (home?: string) => resolve(auditDir(home), "schedule.json");
 /**
  * The anonymous instance id this machine reports telemetry under.
  *
@@ -427,6 +491,13 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // source destroyed, while `isConfigured()` still read true so the wizard never
   // re-asked and hooks kept firing against an empty policy set.
   { path: policiesDir, class: "user-typed" },
+  // The signed-in session. `auth.json` at the home root through layout 3, where
+  // it was in NEITHER this table nor the delete list — undeleted by oversight
+  // rather than by decision, which is the state this table exists to make
+  // impossible. Nothing regenerates a session; losing it signs the machine out
+  // with no notice, and the machine only finds out the next time it tries to
+  // report.
+  { path: auditSessionFile, class: "user-typed" },
 
   // ── Never deleted: recorded and not yet shipped ──
   // Batches read out of transcripts and queued for upload. The reason losing
@@ -471,10 +542,23 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // deleting the backup is deleting the undo for the step that just ran.
   { path: migrationsDir, class: "identity" },
 
+  // This machine's report identity + digest watermark. `identity` for the same
+  // reason `cursorsDir` is: a new id is a new machine to the api-server, which
+  // burns a slot off the account's machine cap, and a reset watermark re-reports
+  // history the user was already told about. Kept OUT of `auditSessionFile`
+  // precisely so both survive a sign-out.
+  { path: auditMachineFile, class: "identity" },
+
   // ── May be dropped: rebuilt on demand ──
-  { path: auditDir, class: "derived" },
-  { path: collectorHealthFile, class: "derived" },
+  // NOTE: `auditDir` itself is deliberately absent. Layout 4 made it MIXED — it
+  // holds the session and the machine identity above alongside these three — so
+  // it is classified per-file, exactly like `stateDir`. Listing the parent here
+  // (which layout 3 did, correctly for what it then held) would put the token on
+  // the delete list.
+  { path: auditDashboardFile, class: "derived" },
+  { path: auditCacheDir, class: "derived" },
   { path: auditScheduleFile, class: "derived" },
+  { path: collectorHealthFile, class: "derived" },
   { path: codexSessionPathsFile, class: "derived" },
   { path: shimsDir, class: "derived" },
   { path: sessionPauseDir, class: "derived" },
@@ -555,6 +639,28 @@ export const legacy = {
   launcherMarker: () => at(".launcher-configured"),
   lastVersion: () => at("last-version"),
   auditDashboard: () => at("audit-dashboard.json"),
+  /**
+   * Layout 3's audit-owned files, before layout 4 gathered them under `audit/`.
+   *
+   * The first two were never classified in `HOME_CLASSES`, so unlike every other
+   * entry in this map they were not on any delete list — the layout-4 step MOVES
+   * them and there is no older copy to prune. They are here so that step can
+   * find them, and so `filesToBackUp()` copies them aside first: a bug in the
+   * move would otherwise take a live session with it.
+   */
+  authJson: () => at("auth.json"),
+  nextAudit: () => at("next-audit.json"),
+  /**
+   * Layout 4's `audit/reminder.json`, retired before it was ever written to.
+   *
+   * The layout-4 step MOVES `next-audit.json` here rather than deleting it,
+   * because the scheduled-audit work that replaces reminders had not landed yet
+   * and dropping a cadence someone chose would have been unrecoverable if it
+   * slipped. It has landed; the reminder concept is gone, and this is the
+   * position the file was parked in. Listed so a reset clears it.
+   */
+  auditReminder: () => at("audit", "reminder.json"),
+  auditSchedule: () => at("state", "audit-schedule.json"),
   cacheDir: () => at("cache"),
   hookActivityDir: () => at("cache", "hook-activity"),
   auditCacheDir: () => at("cache", "audit"),
@@ -640,6 +746,10 @@ function retiredLayoutPaths(): string[] {
     // `migrateHookActivity()`, and everything else in `cache/` still goes —
     // both remaining entries are re-derived on demand.
     legacy.auditCacheDir(),
+    // The reminder, at the position layout 4 parked it in. It is on this list
+    // rather than in `HOME_CLASSES` because the path is RETIRED: nothing writes
+    // it any more, so it has no class to carry — only a location to clear.
+    legacy.auditReminder(),
     legacy.codexSessionPaths(),
     legacy.spoolDir(),
     legacy.failedDir(),

package/src/hooks/fp-reset.ts

@@ -910,7 +910,12 @@ export function readCarriedLegacyCredentials(): FpCredentials | null {
   return Object.keys(creds).length > 0 ? creds : null;
 }
 
-export function resetHome(from: number): ResetOutcome {
+/**
+ * @param to The layout this step LANDS on, which is not always the current one.
+ *   Defaults to `LAYOUT_VERSION` for a direct call, but the registry passes the
+ *   step's own `to` — see the stamp at the end of this function.
+ */
+export function resetHome(from: number, to: number = LAYOUT_VERSION): ResetOutcome {
   // BEFORE the deletions, so a file that is mid-move is never one the reset
   // then walks over.
   const migrated = migrateConventionPolicies();
@@ -959,7 +964,22 @@ export function resetHome(from: number): ResetOutcome {
   // 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();
+  // The step's OWN target, not LAYOUT_VERSION.
+  //
+  // Every step used to end stamping the current layout, which was harmless
+  // while every chain was one hop. On `1 → 3 → 4` it means the first step
+  // marks the home layout 4 with its files still at layout 3, and the window
+  // between that stamp and the next step completing is a real one: a SIGKILL,
+  // an OOM or a power loss inside it leaves a home that reads as `current`
+  // forever. `detectLayout()` short-circuits on the marker, so no later
+  // command re-examines the landmarks, and `auth.json` sits at the root while
+  // layout 4 reads `audit/session.json` — a machine silently signed out with
+  // its session on disk and nothing that would ever move it.
+  //
+  // `runMigrations` also repairs an over-stamp in its `catch`, but a killed
+  // process runs no catch. Stamping the truth in the first place is what makes
+  // that repair a second line of defence rather than the only one.
+  writeVersionFile({ layout: to });
   return { removed, migrated, activity, policyConfig, spooled, from };
 }
 
@@ -1094,6 +1114,10 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
     // After, not before — see the function's own note for why the intuitive
     // order cannot work.
     const pending = await drainSpoolAfterMigrating();
+    // Read AFTER the migration: on a machine coming from layout 1 or 2 the
+    // config this reads is the one the migration just carried across, so asking
+    // any earlier would read a file that is about to move.
+    const daemonHint = staleDaemonHint();
     return {
       state,
       fatal: false,
@@ -1160,6 +1184,14 @@ export async function checkLayoutForCli(): Promise<LayoutCheck> {
         // 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`.
+        //
+        // The daemon hint belongs HERE above all, and was missing. This branch
+        // is the one that moves the home and stamps the new layout marker — it
+        // is the command that CREATES the incompatibility with an unrefreshed
+        // daemon, and it was the one command saying nothing about it. Every
+        // later command reached the non-stale return below and got the hint;
+        // the one where the user is watching the reorganisation happen did not.
+        ...(daemonHint.length > 0 ? ["", ...daemonHint] : []),
       ],
     };
   }
@@ -1269,20 +1301,58 @@ async function healDaemonFlag(): Promise<string[]> {
 }
 
 /**
- * One line when the daemon is older than the CLI.
- *
- * Deliberately NOT on the hook path. A stale daemon still enforces every policy
- * correctly — it is slower to notice an upgrade, not broken — so a warning once
- * per tool call would be noise about something that is working. CLI commands
- * are where a person is present to act on it.
+ * What to say when the daemon's version does not match the CLI's.
+ *
+ * Deliberately NOT on the hook path. CLI commands are where a person is present
+ * to act on it, and once per tool call would be noise.
+ *
+ * Two messages, because the stakes are not the same on both kinds of machine.
+ *
+ * On a machine that does NOT require the daemon, a stale one is what it looks
+ * like: slower to notice an upgrade, still enforcing correctly.
+ *
+ * On a machine that DOES — `daemon.configured` — it is a scheduled outage.
+ * failproofaid calls `refuse_foreign_layout()` before it binds its socket and
+ * exits when the home's layout marker is not the one its binary was built
+ * against, and a release that moves `~/.failproofai` therefore strands every
+ * daemon that has not been refreshed. Nothing looks wrong in the meantime: the
+ * running process read the marker once at startup and keeps serving from
+ * memory. The failure lands at the next restart — a reboot, a crash,
+ * `systemctl restart` — where the unit exits nonzero, `Restart=on-failure`
+ * trips the start limit, and the service latches `failed`. From there the
+ * machine fails closed and denies every tool call across all 11 CLIs, and
+ * `healDaemonFlag()` will not rescue it because a layout-refusing unit reads as
+ * `stopped`, which it deliberately excludes.
+ *
+ * This used to say a stale daemon "is slower to notice an upgrade, not broken"
+ * to everybody, and pointed at `failproofai config`. Across a layout bump that
+ * is the wrong sentence and the wrong command.
  */
 function staleDaemonHint(): string[] {
   try {
     const skew = daemonVersionSkew();
     if (!skew) return [];
+    let requiresDaemon = false;
+    try {
+      requiresDaemon = readConfig().daemon.configured;
+    } catch {
+      // Unreadable config: fall through to the mild message rather than
+      // frightening somebody whose machine may not require the daemon at all.
+    }
+    if (requiresDaemon) {
+      return [
+        `[failproofai] daemon is ${skew.installed}, CLI is ${skew.expected}.`,
+        `This machine is configured to REQUIRE the daemon. A daemon built against a`,
+        `different on-disk layout refuses to start, and this version moved it — so the`,
+        `next reboot or restart can leave the service down, which denies every tool`,
+        `call until it is fixed.`,
+        `Run \`failproofai update\` now to bring the daemon in line.`,
+        ``,
+      ];
+    }
     return [
       `[failproofai] daemon is ${skew.installed}, CLI is ${skew.expected} — ` +
-        `run \`failproofai config\` to update it.`,
+        `run \`failproofai update\` to update it.`,
       ``,
     ];
   } catch {

package/src/hooks/migrations.ts

@@ -37,11 +37,22 @@
  * than counting. A chain from 1 today is one step; when layout 4 lands it becomes
  * `1 → 3` then `3 → 4`, and only the second has to be written.
  */
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { version as cliVersion } from "../../package.json";
 import {
   LAYOUT_VERSION,
+  auditScheduleFile,
+  auditSessionFile,
   configFile,
   credentialsFile,
   failproofaiHome,
@@ -52,6 +63,7 @@ import {
   migrationsDir,
   versionFile,
 } from "./fp-home";
+import { readVersionFile, writeVersionFile } from "./fp-config";
 import { resetHome, type ResetOutcome } from "./fp-reset";
 
 export interface Migration {
@@ -78,17 +90,154 @@ export const MIGRATIONS: readonly Migration[] = [
     to: 3,
     describe:
       "layout 1 → 3: carry the decision log out of cache/, keep the policy config in place, drop the layout-1 credential files",
-    run: () => resetHome(1),
+    run: () => resetHome(1, 3),
   },
   {
     from: 2,
     to: 3,
     describe:
       "layout 2 → 3: carry config.toml and credentials.toml into JSON, move custom-policies/ back up into policies/, nest the policy config at the root",
-    run: () => resetHome(2),
+    run: () => resetHome(2, 3),
+  },
+  {
+    from: 3,
+    to: 4,
+    describe:
+      "layout 3 → 4: gather the audit's files under audit/ — auth.json becomes audit/session.json, next-audit.json becomes audit/reminder.json, state/audit-schedule.json becomes audit/schedule.json",
+    run: migrateToLayout4,
   },
 ];
 
+/**
+ * Layout 3 → 4. The first step written against this registry rather than
+ * delegating to `resetHome`, which is what the header promised: additive.
+ *
+ * Three moves, no deletions. Each is a rename with a copy fallback, because
+ * `audit/` and the home root can sit on different filesystems once `$HOME` is a
+ * network mount or the home has been assembled by a container bind — `rename(2)`
+ * returns `EXDEV` there, and a step that threw on it would strand the machine at
+ * layout 3 forever.
+ *
+ * The reminder's destination is `legacy.auditReminder()`, a RETIRED path. The
+ * feature it belonged to is deleted in this same release, so nothing will ever
+ * read the file again — but a migration that DESTROYS something a person chose
+ * is a different act from one that moves it, and the difference matters even
+ * when the thing is obsolete. It is moved here and cleared by the next reset,
+ * via `retiredLayoutPaths()`.
+ *
+ * **A missing source is success, not failure.** Most homes have never signed in,
+ * so `auth.json` and `next-audit.json` are absent on the majority of machines,
+ * and a scheduled scan that has never run leaves no `audit-schedule.json`. Only
+ * a source that EXISTS and could not be moved is an error worth stopping for.
+ *
+ * **A destination that already exists wins.** Re-running the step — which is
+ * exactly what happens when a later step in the same chain throws and the user
+ * retries — must not copy a stale layout-3 file back over the layout-4 one that
+ * has since been written to.
+ */
+function migrateToLayout4(): ResetOutcome {
+  const moves: { from: string; to: string }[] = [
+    { from: legacy.authJson(), to: auditSessionFile() },
+    { from: legacy.nextAudit(), to: legacy.auditReminder() },
+    { from: legacy.auditSchedule(), to: auditScheduleFile() },
+  ];
+
+  // `FAILPROOFAI_AUTH_DIR` names a directory OUTSIDE the managed home — a
+  // documented env var, not a test hook — and `auth-store` resolves the session
+  // relative to it. Every path above comes from `FAILPROOFAI_HOME`, so without
+  // this the override directory is never visited: the file stays `auth.json`,
+  // layout 4 reads `session.json`, and the upgrade signs the user out silently.
+  // Their scans keep running and their digests stop, which is the failure this
+  // whole area is built to avoid.
+  //
+  // The same two moves, in their directory, so one naming scheme holds
+  // everywhere rather than the file having a different name depending on how
+  // the process was configured.
+  const authDirOverride = process.env.FAILPROOFAI_AUTH_DIR;
+  if (authDirOverride) {
+    moves.push(
+      { from: join(authDirOverride, "auth.json"), to: join(authDirOverride, "session.json") },
+      {
+        from: join(authDirOverride, "next-audit.json"),
+        to: join(authDirOverride, "reminder.json"),
+      },
+    );
+  }
+
+  const migrated: string[] = [];
+  for (const { from, to } of moves) {
+    if (!existsSync(from)) continue;
+    if (existsSync(to)) {
+      // The layout-4 file is already authoritative. Drop the stale original
+      // rather than leaving a second copy of a credential lying at the root.
+      //
+      // A failure here PROPAGATES. Swallowing it continued to `writeVersionFile`
+      // and stamped the home as layout 4 with `auth.json` — a live bearer token
+      // — still sitting at the root, where nothing would ever look at it again
+      // and nothing would ever clean it up. Throwing leaves the home at layout 3
+      // and the next command retries, which is exactly what `runMigrations`
+      // documents a failed step to mean; the destination is already
+      // authoritative, so the retry is a no-op plus one more delete attempt.
+      rmSync(from, { force: true });
+      continue;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    try {
+      renameSync(from, to);
+    } catch {
+      // EXDEV, or a rename racing something holding the file open on Windows.
+      try {
+        copyFileSync(from, to);
+      } catch (err) {
+        // Remove the PARTIAL destination before giving up.
+        //
+        // `copyFileSync` is not atomic: ENOSPC or a kill part-way through
+        // leaves a truncated `to` on disk. The source is still intact at this
+        // point, so nothing is lost yet — but the next attempt takes the
+        // `existsSync(to)` branch above, reads that fragment as the
+        // authoritative layout-4 file, and deletes the good original. A
+        // half-written session file is not a session, so the retry would have
+        // signed the machine out using the very branch that exists to protect
+        // the credential.
+        try {
+          rmSync(to, { force: true });
+        } catch {
+          // Nothing better to do. The throw below still leaves the home at
+          // layout 3, so `deleteAuth`'s sweep and the backup both still apply.
+        }
+        throw err;
+      }
+      rmSync(from, { force: true });
+    }
+    migrated.push(`${basename(from)} → audit/${basename(to)}`);
+  }
+
+  // `session.json` carries tokens and `auth.json` was written 0600 by
+  // `writeJsonAtomically`. A rename preserves the mode, but a copy fallback
+  // inherits the process umask — so reassert it rather than assume which branch
+  // ran. Belt and braces on a file whose whole content is a bearer credential.
+  for (const secret of [auditSessionFile()]) {
+    if (!existsSync(secret)) continue;
+    try {
+      chmodSync(secret, 0o600);
+    } catch {
+      // Best effort, exactly as `writeJsonAtomically` treats it.
+    }
+  }
+
+  // The same stamper every other write of this file goes through. Hand-rolling
+  // the JSON here would drop `daemon`, which nothing on this path touches and
+  // which `daemonVersionSkew()` reads on every CLI command.
+  //
+  // This step's own `to`, spelled out for the same reason `resetHome` takes
+  // one: a step must never mark the home as a layout it did not reach. Here
+  // they happen to be equal, and writing the literal is what keeps them equal
+  // by intent rather than by coincidence when layout 5 arrives.
+  writeVersionFile({ layout: 4 });
+
+  return { removed: [], migrated, activity: [], policyConfig: [], spooled: [], from: 3 };
+}
+
 /**
  * The steps that take `from` to {@link LAYOUT_VERSION}.
  *
@@ -256,6 +405,14 @@ const BACKED_UP_LEGACY: BackedUpFile[] = [
   // most incomplete exactly where it mattered most.
   { at: legacy.cloudCredentials },
   { at: legacy.ingestCredentials },
+  // The three files the layout-4 step MOVES. `auth.json` is the one that
+  // matters: it is a live bearer credential, and unlike every other entry here
+  // it was never on a delete list — so it has never had a copy taken before a
+  // migration touched it. A move is not a deletion, but a move with a bug in it
+  // is, and this is the only insurance against that.
+  { at: legacy.authJson },
+  { at: legacy.nextAudit },
+  { at: legacy.auditSchedule },
 ];
 
 /** The name a file is saved under inside `backup-layout<n>/`. */
@@ -263,6 +420,57 @@ function backupNameOf(f: BackedUpFile): string {
   return f.as ?? basename(f.at());
 }
 
+/**
+ * Backup copies deleted once the whole chain has succeeded.
+ *
+ * The backup above is insurance against a migration that goes wrong. Insurance
+ * you keep forever on a live credential is not insurance, it is a second copy
+ * of the credential — and this one is worse than the original, because
+ * `migrationsDir` is classed `identity` in `HOME_CLASSES`, so no reset class
+ * ever removes it, and `deleteAuth()` only ever knew about the live path.
+ * Signing out of the dashboard, a 401 auto-delete and `failproofai reset` all
+ * left a working bearer and refresh token sitting at
+ * `migrations/backup-layout3/auth.json`, where every dotfile backup, container
+ * image, snapshot and handed-over machine would carry it. There is no CLI
+ * sign-out at all, so the headless boxes this feature targets had no supported
+ * way to remove it. A stale refresh token is also exactly the input
+ * `auth-store.ts` documents as triggering server-side replay revocation.
+ *
+ * Only entries whose source was MOVED are prunable, never ones that were
+ * DELETED: for `credentials.json` the backup is the only remaining copy, so
+ * removing it would be the data loss the backup exists to prevent. `landsAt` is
+ * checked rather than assumed, so a copy is dropped only once the file is
+ * provably readable at its new home.
+ */
+const PRUNED_AFTER_SUCCESS: ReadonlyArray<{ as: string; landsAt: () => string }> = [
+  { as: basename(legacy.authJson()), landsAt: auditSessionFile },
+];
+
+/**
+ * Remove the credential copies a completed chain no longer needs.
+ *
+ * Never throws: a chain that migrated correctly must not be reported as failed
+ * because a cleanup could not delete a file.
+ */
+export function pruneMigratedCredentials(from: number): string[] {
+  const pruned: string[] = [];
+  for (let layout = from; layout < LAYOUT_VERSION; layout++) {
+    for (const { as, landsAt } of PRUNED_AFTER_SUCCESS) {
+      try {
+        if (!existsSync(landsAt())) continue;
+        const copy = resolve(migrationBackupDir(layout), as);
+        if (!existsSync(copy)) continue;
+        rmSync(copy, { force: true });
+        pruned.push(as);
+      } catch {
+        // Best effort. `deleteAuth()` sweeps these too, so a copy that survives
+        // here is still removed the next time somebody signs out.
+      }
+    }
+  }
+  return pruned;
+}
+
 /**
  * The files that exist right now and would be backed up, each exactly once.
  *
@@ -385,6 +593,31 @@ export function runMigrations(
       });
     } catch (err) {
       steps.push({ from: step.from, to: step.to, ok: false });
+      // Undo an EARLIER step's over-stamp, if there was one.
+      //
+      // A step ends by stamping `VERSION`, and `writeVersionFile()` writes
+      // {@link LAYOUT_VERSION} rather than the step's own `to`. That was harmless
+      // while every chain was one hop and became a trap the moment one was two:
+      // on `2 → 3 → 4` the FIRST step stamps 4, so a `3 → 4` that then throws
+      // leaves a home marked CURRENT that was never migrated. `detectLayout()`
+      // reports `current`, no later command ever retries, and `auth.json` stays
+      // at the root while layout 4 reads `audit/session.json` — a machine
+      // silently signed out, with its session sitting on disk and nothing left
+      // that would ever move it.
+      //
+      // Only touched when the marker already claims the home is current, so a
+      // chain whose steps never got that far keeps whatever they left. `step.from`
+      // is where this one actually got to: every earlier step succeeded, and a
+      // failing step is documented not to roll back — which is exactly the state
+      // the next command should try to migrate again.
+      try {
+        const marker = readVersionFile();
+        if (marker && marker.layout >= LAYOUT_VERSION) writeVersionFile({ layout: step.from });
+      } catch {
+        // A marker we cannot rewrite leaves the home reading as whatever the last
+        // successful step claimed. Nothing further can be done about it here, and
+        // failing the run a second way would only hide the real error below.
+      }
       failed = {
         from: step.from,
         to: step.to,
@@ -402,6 +635,10 @@ export function runMigrations(
     }
   }
 
+  // Only on a clean chain. A run that failed still needs its copies: the whole
+  // point of the backup is the state this branch is in.
+  if (!failed) pruneMigratedCredentials(from);
+
   return { from, steps, backedUp, outcome, failed };
 }