Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
30.0 KB
Raw Blame
/**
 * Removal of the legacy tree (task 2.5) and the two doctor findings of
 * the transition (task 2.12): the cohort gate closed and open, `--force`
 * with its report, a cohort device offline for months that keeps the gate
 * closed, the dated device-local archive, the doctor naming devices still
 * on the legacy layout, and a legacy directory that comes back.
 */
import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { spawn } from "node:child_process";
import {
  chmodSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";

import { writeVaultIdentity } from "../../../src/core/brain/vault-identity.ts";
import { proceduralMemoryUsagePath } from "../../../src/core/brain/paths.ts";
import { runDoctor } from "../../../src/core/brain/doctor.ts";
import {
  LEGACY_DEVICES_PENDING_CODE,
  LEGACY_TREE_REAPPEARED_CODE,
  MIGRATION_DONE_TWICE_CODE,
} from "../../../src/core/brain/doctor/migration-check.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import { planMigrationDryRun } from "../../../src/core/store-migration/dry-run.ts";
import { runMigration } from "../../../src/core/store-migration/migrate.ts";
import {
  holdMigrationGate,
  migrationGatePath,
  readMigrationGate,
} from "../../../src/core/migration-gate.ts";
import { migrateStore, removeLegacy, rollback } from "../../../src/core/store-migration/outcome.ts";
import { MigrationGateBusyError } from "../../../src/core/store-migration/quiesce.ts";
import {
  LEGACY_ARCHIVE_DIR,
  readRemovalInProgress,
  removeLegacyTree,
} from "../../../src/core/store-migration/removal.ts";
import { migrationDir } from "../../../src/core/store-migration/journal.ts";
import {
  readRemovalMarker,
  sameVaultPath,
} from "../../../src/core/store-migration/removal-marker.ts";
import { RollbackRefusedError } from "../../../src/core/store-migration/rollback.ts";
import { makeFleet, type Fleet, type Machine } from "./fixtures/fleet.ts";
import { moveNeverHeld } from "../../helpers/held-partitions.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const FAST = { settleMs: 0 } as const;

/** Whether this host lets the test create a symlink (Windows needs a privilege). */
const CAN_SYMLINK = ((): boolean => {
  const probe = mkdtempSync(join(tmpdir(), "osb-symlink-probe-"));
  try {
    symlinkSync(probe, join(probe, "link"), "dir");
    return true;
  } catch {
    return false;
  } finally {
    rmSync(probe, { recursive: true, force: true });
  }
})();
const RACER = join(import.meta.dir, "fixtures", "removal-racer.ts");
let fleet: Fleet | null = null;
afterEach(() => {
  fleet?.cleanup();
  fleet = null;
});

function retire(machine: Machine, device: string): void {
  appendRecord(machine.store(), {
    partition: "shared",
    stream: "settings",
    kind: "device-retire",
    agent: "t",
    body: { authority: "human", device },
  });
}

function doctorWarningCodes(vault: string): string[] {
  return runDoctor(vault).warnings.map((w) => w.code);
}

describe("removing the legacy tree", () => {
  test("the gate stays closed while cohort devices are on the legacy layout, and doctor names them", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    // The fixture's legacy shards name dev-b and dev-c, which never migrated.
    const blocked = removeLegacy(a.vault);
    expect(blocked).toEqual({
      removed: false,
      reason: "cohort-pending",
      pending: ["dev-b", "dev-c"],
    });
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);

    const result = runDoctor(a.vault);
    const pending = (result.uncertain ?? []).find((u) => u.code === LEGACY_DEVICES_PENDING_CODE);
    expect(pending?.message).toContain("dev-b, dev-c still write the legacy Brain/ tree");
    expect(result.warnings.map((w) => w.code)).not.toContain(LEGACY_DEVICES_PENDING_CODE);
  });

  test("doctor also names a device that writes legacy log shards but is in no cohort", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    // dev-d joined after the cohort was recorded and still writes the tree.
    writeFileSync(
      join(a.vault, "Brain", "log", "2026-11-03.dev-d.jsonl"),
      `${JSON.stringify({ ts: "2026-11-03T10:00:00Z", event_type: "note", text: "late" })}\n`,
    );
    const pending = (runDoctor(a.vault).uncertain ?? []).find(
      (u) => u.code === LEGACY_DEVICES_PENDING_CODE,
    );
    expect(pending?.message).toContain("dev-d");
  });

  test("a cohort device offline for more than 30 days keeps the gate closed", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    // dev-c's shard is 60 days old: off the 30-day roster, still in the cohort.
    const devices = planMigrationDryRun(a.vault).devices;
    expect(devices.cohort.map((d) => d.device)).toContain("dev-c");
    expect(devices.roster).not.toContain("dev-c");
    retire(a, "dev-b");
    expect(removeLegacy(a.vault)).toEqual({
      removed: false,
      reason: "cohort-pending",
      pending: ["dev-c"],
    });
  });

  test("a retired device that writes again is back in the cohort until it is retired again", () => {
    fleet = makeFleet(["dev-a", "dev-b"]);
    const [a, b] = [fleet.machine("dev-a"), fleet.machine("dev-b")];
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    retire(a, "dev-b");
    retire(a, "dev-c");
    // dev-b, retired, writes a record afterwards (on its own clock, later).
    fleet.syncStore("dev-a", "dev-b");
    b.use();
    appendRecord(
      b.store(),
      { partition: "shared", stream: "events", kind: "note", agent: "t", body: { text: "back" } },
      { now: () => Date.now() + 60_000 },
    );
    fleet.syncStore("dev-b", "dev-a");
    a.use();
    expect(removeLegacy(a.vault)).toEqual({
      removed: false,
      reason: "cohort-pending",
      pending: ["dev-b"],
    });
    // Retired again, after that write: out of the cohort, the gate opens.
    appendRecord(
      a.store(),
      {
        partition: "shared",
        stream: "settings",
        kind: "device-retire",
        agent: "t",
        body: { authority: "human", device: "dev-b" },
      },
      { now: () => Date.now() + 120_000 },
    );
    expect(removeLegacy(a.vault).removed).toBe(true);
  });

  test("the gate opens once every cohort device switched or retired; the tree goes to a dated archive", () => {
    fleet = makeFleet(["dev-a", "dev-b"]);
    const [a, b] = [fleet.machine("dev-a"), fleet.machine("dev-b")];
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    fleet.syncVaultFile("dev-a", "dev-b", "Brain/vault-id.json");
    fleet.syncStore("dev-a", "dev-b");
    b.use();
    expect(migrateStore(b.vault, FAST).ok).toBe(true);
    fleet.syncStore("dev-b", "dev-a");
    a.use();
    retire(a, "dev-c");

    const removed = removeLegacy(a.vault);
    if (!removed.removed) throw new Error(`not removed: ${removed.reason}`);
    expect(removed.forced).toBe(false);
    expect(removed.stopped).toEqual([]);
    expect(removed.moved).toEqual([".open-second-brain", "Brain"]);
    expect(existsSync(join(a.vault, "Brain"))).toBe(false);
    expect(existsSync(join(a.vault, ".open-second-brain"))).toBe(false);
    expect(existsSync(join(removed.archive, "Brain", "inbox", "2026-11-01-tabs.md"))).toBe(true);
    expect(removed.archive).toContain("legacy-archive");
    // Rebuildable files are not archived: the index and the log day pages.
    expect(removed.skipped).toContain(".open-second-brain/brain.sqlite");
    expect(removed.skipped).toContain("Brain/log/2026-11-01.dev-a.md");
    expect(existsSync(join(removed.archive, ".open-second-brain", "brain.sqlite"))).toBe(false);
    expect(existsSync(join(removed.archive, ".open-second-brain", "secrets", "keyfile"))).toBe(
      true,
    );
    expect(doctorWarningCodes(a.vault)).not.toContain(LEGACY_TREE_REAPPEARED_CODE);

    // An agent following stale instructions writes the legacy layout again.
    mkdirSync(join(a.vault, "Brain", "preferences"), { recursive: true });
    writeFileSync(
      join(a.vault, "Brain", "preferences", "pref-stale.md"),
      '---\nid: pref-stale\nagent: "@stale-agent"\n---\n',
    );
    const result = runDoctor(a.vault);
    const back = result.warnings.find((w) => w.code === LEGACY_TREE_REAPPEARED_CODE);
    expect(back?.message).toContain("@stale-agent");
  });

  test("--force removes the tree and names the devices that stop reaching the store", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    const removed = removeLegacy(a.vault, { force: true });
    if (!removed.removed) throw new Error("not removed");
    expect(removed.forced).toBe(true);
    expect(removed.stopped).toEqual(["dev-b", "dev-c"]);
    expect(readdirSync(removed.archive).toSorted()).toEqual([".open-second-brain", "Brain"]);
    expect(a.records().some((r) => r.kind === "legacy-tree-removed")).toBe(true);
  });

  test("a removal interrupted after its first move is finished into the same archive", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    const first = new Date("2026-11-09T10:00:00.000Z");
    const archive = join(
      a.store().deviceStateDir,
      LEGACY_ARCHIVE_DIR,
      first.toISOString().replace(/[:.]/g, "-"),
    );
    // `Brain` cannot move: something already sits at its archive place.
    mkdirSync(join(archive, "Brain", "blocker"), { recursive: true });
    expect(() =>
      removeLegacyTree(a.vault, a.store(), { agent: "t", force: true, now: first }),
    ).toThrow();
    expect(existsSync(join(a.vault, ".open-second-brain"))).toBe(false);
    expect(readRemovalInProgress(a.store())?.archive).toBe(archive);
    // Half removed: a rollback would rebuild half a tree.
    expect(() => rollback(a.vault)).toThrow(RollbackRefusedError);

    rmSync(join(archive, "Brain"), { recursive: true, force: true });
    const done = removeLegacyTree(a.vault, a.store(), {
      agent: "t",
      force: true,
      now: new Date("2026-11-10T10:00:00.000Z"),
    });
    if (!done.removed) throw new Error("not removed");
    expect(done.archive).toBe(archive);
    expect(done.moved).toEqual([".open-second-brain", "Brain"]);
    expect(readRemovalInProgress(a.store())).toBeNull();
    expect(a.records().filter((r) => r.kind === "legacy-tree-removed")).toHaveLength(1);
  });

  test("holds the migration gate, and never takes it from a live run", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    // This process stands in for a live run holding the gate.
    holdMigrationGate(a.vault, "other-run");
    expect(() => removeLegacy(a.vault, { force: true })).toThrow(MigrationGateBusyError);
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);
    expect(readMigrationGate()?.run_id).toBe("other-run");
  });

  test("never replaces another vault's unfinished removal journal", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    const journal = join(migrationDir(a.store()), "removal.json");
    const other = { vault: join(fleet.parent, "other-vault"), at: "x", archive: "y" };
    writeFileSync(journal, `${JSON.stringify(other)}\n`);
    expect(() => removeLegacy(a.vault, { force: true })).toThrow(/unfinished/);
    expect(readRemovalInProgress(a.store())?.vault).toBe(other.vault);
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);
  });

  test("never lifts the gate an interrupted migration of the vault still holds", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    const gate = { vault: a.vault, run_id: "migrate-interrupted", since: "", pid: 0 };
    writeFileSync(migrationGatePath(), JSON.stringify(gate));
    expect(() => removeLegacy(a.vault, { force: true })).toThrow(MigrationGateBusyError);
    expect(readMigrationGate()?.run_id).toBe("migrate-interrupted");
  });
});

const PRIVATE_PAGE = "Brain/inbox/2026-11-08-secret.md";
const PRIVATE_SIGNAL =
  "---\nid: sig-secret\ntopic: secret\nprinciple: secret\nvisibility: private\n---\nRaw.\n";

/**
 * dev-a switched alone, every other cohort device retired, and the private
 * partition taken off this machine (it now holds only shared). Returns a
 * function that brings the partition back.
 */
function switchedWithoutPrivate(): { a: Machine; restorePrivate: () => void } {
  fleet = makeFleet(["dev-a"]);
  const a = fleet.machine("dev-a");
  a.use();
  expect(runMigration(a.vault, FAST).ok).toBe(true);
  retire(a, "dev-b");
  retire(a, "dev-c");
  const aside = join(fleet.parent, "private-aside");
  moveNeverHeld(a.storeRoot, aside);
  return { a, restorePrivate: () => renameSync(aside, join(a.storeRoot, "private")) };
}

describe("a removal while a settings shard cannot be read", () => {
  test.skipIf(!CAN_SYMLINK)(
    "refuses: a cohort record in that shard may name a device still on the legacy layout",
    () => {
      fleet = makeFleet(["dev-a"]);
      const a = fleet.machine("dev-a");
      a.use();
      expect(runMigration(a.vault, FAST).ok).toBe(true);
      retire(a, "dev-b");
      retire(a, "dev-c");
      // A peer's cohort record names a device that never wrote a legacy shard.
      appendRecord(openStore({ root: a.storeRoot, device: "dev-p" }), {
        partition: "shared",
        stream: "settings",
        kind: "migration-cohort",
        agent: "t",
        body: { authority: "human", vault_id: null, devices: ["dev-q"] },
      });
      const kept = removeLegacy(a.vault);
      expect(kept).toMatchObject({ removed: false, reason: "cohort-pending", pending: ["dev-q"] });
      // The peer's shard turns into something the reader refuses (a link).
      const peer = join(a.storeRoot, "shared", "settings", "dev-p");
      for (const name of readdirSync(peer)) {
        renameSync(join(peer, name), join(a.storeRoot, `moved-${name}`));
        symlinkSync(join(a.storeRoot, `moved-${name}`), join(peer, name));
      }
      expect(() => removeLegacy(a.vault)).toThrow(/cannot be read/);
      expect(existsSync(join(a.vault, "Brain"))).toBe(true);
    },
  );
});

/** dev-a switched, dev-b and dev-c retired, and dev-p's cohort names dev-q. */
function withPeerCohort(): { a: Machine; shard: string } {
  fleet = makeFleet(["dev-a"]);
  const a = fleet.machine("dev-a");
  a.use();
  expect(runMigration(a.vault, FAST).ok).toBe(true);
  retire(a, "dev-b");
  retire(a, "dev-c");
  const peer = openStore({ root: a.storeRoot, device: "dev-p" });
  appendRecord(peer, {
    partition: "shared",
    stream: "settings",
    kind: "migration-cohort",
    agent: "t",
    body: { authority: "human", vault_id: null, devices: ["dev-q"] },
  });
  // A later line of the same shard stays readable.
  appendRecord(peer, {
    partition: "shared",
    stream: "settings",
    kind: "setting-set",
    agent: "t",
    body: { authority: "human", key: "view.language", value: "en" },
  });
  const dir = join(a.storeRoot, "shared", "settings", "dev-p");
  const [name] = readdirSync(dir);
  return { a, shard: join(dir, name!) };
}

describe("a removal while a settings shard is read only in part", () => {
  test("a corrupt cohort line refuses without --force, and --force removes the tree", () => {
    const { a, shard } = withPeerCohort();
    const lines = readFileSync(shard, "utf8").split("\n");
    expect(lines[0]).toContain("migration-cohort");
    // One byte flipped inside the line: it no longer parses, nor is it a cut-short line.
    lines[0] = lines[0]!.replace('"kind":', '"kind";');
    writeFileSync(shard, lines.join("\n"));
    expect(() => removeLegacy(a.vault)).toThrow(/cannot be read in full/);
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);
    expect(removeLegacy(a.vault, { force: true })).toMatchObject({ removed: true, forced: true });
  });

  test("a cohort record whose blob has not arrived refuses without --force", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    retire(a, "dev-b");
    retire(a, "dev-c");
    // A cohort long enough to go to a blob; the blob has not arrived here.
    const devices = Array.from({ length: 900 }, (_, i) => `dev-q${String(i).padStart(3, "0")}`);
    appendRecord(openStore({ root: a.storeRoot, device: "dev-p" }), {
      partition: "shared",
      stream: "settings",
      kind: "migration-cohort",
      agent: "t",
      body: { authority: "human", vault_id: null, devices, note: "x".repeat(20_000) },
    });
    rmSync(join(a.storeRoot, "shared", "blobs"), { recursive: true, force: true });
    expect(() => removeLegacy(a.vault)).toThrow(/cannot be read in full/);
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);
  });

  test("a line cut short by a crash and closed by the next append does not refuse", () => {
    const { a, shard } = withPeerCohort();
    // Rewrite dev-p's shard: a torn fragment, then the next record whole.
    const lines = readFileSync(shard, "utf8").split("\n");
    writeFileSync(shard, `${lines[1]!.slice(0, 40)}\n${lines[1]}\n`);
    // dev-p's cohort record is gone with the rewrite; nothing else is pending.
    expect(removeLegacy(a.vault)).toMatchObject({ removed: true, forced: false });
  });
});

describe("a removal with late items held back for a partition this machine lacks", () => {
  test("refuses, even with --force, names the count and the partition, and moves nothing", () => {
    const { a, restorePrivate } = switchedWithoutPrivate();
    a.write(PRIVATE_PAGE, PRIVATE_SIGNAL);
    for (const force of [false, true]) {
      expect(removeLegacy(a.vault, { force })).toEqual({
        removed: false,
        reason: "held-back",
        pending: [],
        held_back: 1,
        missing: ["private"],
      });
      expect(existsSync(join(a.vault, ...PRIVATE_PAGE.split("/")))).toBe(true);
      expect(readRemovalMarker(a.store(), a.vault)).toBeNull();
      expect(a.records().some((r) => r.kind === "legacy-tree-removed")).toBe(false);
    }

    restorePrivate();
    const removed = removeLegacy(a.vault);
    if (!removed.removed) throw new Error(`not removed: ${removed.reason}`);
    expect(a.byKey().has(PRIVATE_PAGE)).toBe(true);
  });

  test("an item the archive import holds back puts the tree back into the vault", () => {
    const { a } = switchedWithoutPrivate();
    // A removal interrupted after it moved Brain/, and sync delivered a
    // private page into the tree just before that move.
    const archive = join(a.store().deviceStateDir, LEGACY_ARCHIVE_DIR, "2026-11-08T10-00-00-000Z");
    mkdirSync(archive, { recursive: true });
    renameSync(join(a.vault, "Brain"), join(archive, "Brain"));
    writeFileSync(join(archive, ...PRIVATE_PAGE.split("/")), PRIVATE_SIGNAL);
    writeFileSync(
      join(migrationDir(a.store()), "removal.json"),
      `${JSON.stringify({ vault: a.vault, at: "2026-11-08T10:00:00.000Z", archive })}\n`,
    );

    const result = removeLegacy(a.vault);
    expect(result).toEqual({
      removed: false,
      reason: "held-back",
      pending: [],
      held_back: 1,
      missing: ["private"],
    });
    expect(existsSync(join(a.vault, ...PRIVATE_PAGE.split("/")))).toBe(true);
    expect(existsSync(join(a.vault, ".open-second-brain"))).toBe(true);
    expect(readRemovalInProgress(a.store())).toBeNull();
    expect(readRemovalMarker(a.store(), a.vault)).toBeNull();
    expect(a.records().some((r) => r.kind === "legacy-tree-removed")).toBe(false);
  });
});

describe("a legacy writer still appending into the moved tree", () => {
  test("the removal puts the tree back and records nothing", () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    // A removal interrupted after it moved Brain/, with one late page in it.
    const archive = join(a.store().deviceStateDir, LEGACY_ARCHIVE_DIR, "2026-11-08T10-00-00-000Z");
    mkdirSync(archive, { recursive: true });
    renameSync(join(a.vault, "Brain"), join(archive, "Brain"));
    const page = (n: number): string => join(archive, "Brain", "inbox", `2026-11-08-late-${n}.md`);
    const signal = (n: number): string =>
      `---\nid: sig-late-${n}\ntopic: late-${n}\nprinciple: late ${n}\n---\nRaw.\n`;
    writeFileSync(page(0), signal(0));
    writeFileSync(
      join(migrationDir(a.store()), "removal.json"),
      `${JSON.stringify({ vault: a.vault, at: "2026-11-08T10:00:00.000Z", archive })}\n`,
    );
    // Every import of an archived item is followed by one more written
    // through a handle opened before the move: the import never settles.
    let written = 0;
    const archiveImportHooks = {
      afterItemAppended: (): void => {
        written += 1;
        writeFileSync(page(written), signal(written));
      },
    };

    expect(() =>
      removeLegacyTree(a.vault, a.store(), { agent: "t", force: true, archiveImportHooks }),
    ).toThrow(/kept changing .* put back/);
    expect(existsSync(join(a.vault, "Brain", "inbox", `2026-11-08-late-${written}.md`))).toBe(true);
    expect(readRemovalInProgress(a.store())).toBeNull();
    expect(readRemovalMarker(a.store(), a.vault)).toBeNull();
    expect(a.records().some((r) => r.kind === "legacy-tree-removed")).toBe(false);
  });
});

/** Wait, with a hard budget, until every path exists. */
async function waitForFiles(paths: ReadonlyArray<string>, budgetMs: number): Promise<void> {
  const deadline = Date.now() + budgetMs;
  while (!paths.every((p) => existsSync(p))) {
    if (Date.now() > deadline) throw new Error(`timed out waiting for ${paths.join(", ")}`);
    await Bun.sleep(5);
  }
}

describe("two removals at once", () => {
  test("exactly one proceeds, and the marker names the archive that holds the tree", async () => {
    fleet = makeFleet(["dev-a"]);
    const a = fleet.machine("dev-a");
    a.use();
    expect(runMigration(a.vault, FAST).ok).toBe(true);
    const go = join(fleet.parent, "race-go");
    const outs = [join(fleet.parent, "race-1.json"), join(fleet.parent, "race-2.json")];
    const exits = outs.map((out) => {
      const child = spawn(process.execPath, [RACER, a.vault, go, out], {
        env: { ...process.env },
        stdio: "ignore",
      });
      return new Promise<number | null>((done) => child.on("exit", done));
    });
    await waitForFiles(
      outs.map((o) => `${o}.ready`),
      30_000,
    );
    writeFileSync(go, "go");
    expect(await Promise.all(exits)).toEqual([0, 0]);

    const results = outs.map((o) => JSON.parse(readFileSync(o, "utf8")) as Record<string, unknown>);
    const winners = results.filter((r) => r["removed"] === true);
    expect(winners).toHaveLength(1);
    // The loser was refused at the gate, or came after and found no tree.
    const loser = results.find((r) => r["removed"] !== true)!;
    if (loser["error"] !== undefined) expect(loser["error"]).toBe("MigrationGateBusyError");
    else expect(loser["removed"]).toBe(false);

    const archive = winners[0]!["archive"] as string;
    expect(readdirSync(archive).toSorted()).toEqual([".open-second-brain", "Brain"]);
    expect(existsSync(join(archive, "Brain", "inbox", "2026-11-01-tabs.md"))).toBe(true);
    expect(readRemovalMarker(a.store(), a.vault)?.archive).toBe(archive);
    expect(readRemovalInProgress(a.store())).toBeNull();
    expect(a.records().filter((r) => r.kind === "legacy-tree-removed")).toHaveLength(1);
    expect(existsSync(join(a.vault, "Brain"))).toBe(false);
  }, 60_000);
});

describe("two first machines", () => {
  test("two devices that both ran the first migration are named by doctor", () => {
    fleet = makeFleet(["dev-a", "dev-b"]);
    const [a, b] = [fleet.machine("dev-a"), fleet.machine("dev-b")];
    // One vault with its identity marker on both devices (a vault without
    // one would get a marker from each run, and the two runs would name
    // two vaults). Both migrate before either completion record has synced.
    writeVaultIdentity(a.vault);
    fleet.syncVaultFile("dev-a", "dev-b", "Brain/vault-id.json");
    a.use();
    expect(runMigration(a.vault, FAST).role).toBe("first");
    b.use();
    expect(runMigration(b.vault, FAST).role).toBe("first");
    fleet.syncStore("dev-b", "dev-a");
    a.use();
    const warning = runDoctor(a.vault).warnings.find((w) => w.code === MIGRATION_DONE_TWICE_CODE);
    expect(warning?.message).toContain("dev-a and dev-b");
    fleet.syncStore("dev-a", "dev-b");
    b.use();
    expect(runDoctor(b.vault).warnings.map((w) => w.code)).toContain(MIGRATION_DONE_TWICE_CODE);
  });

  test("a first migration that was rolled back is no second first machine", () => {
    fleet = makeFleet(["dev-a", "dev-b"]);
    const [a, b] = [fleet.machine("dev-a"), fleet.machine("dev-b")];
    a.use();
    expect(runMigration(a.vault, FAST).role).toBe("first");
    rollback(a.vault);
    fleet.syncStore("dev-a", "dev-b");
    b.use();
    expect(runMigration(b.vault, FAST).ok).toBe(true);
    expect(runDoctor(b.vault).warnings.map((w) => w.code)).not.toContain(MIGRATION_DONE_TWICE_CODE);
  });
});

describe("sameVaultPath", () => {
  test("folds case on Windows only", () => {
    expect(sameVaultPath("C:\\Vault", "c:\\vault", "win32")).toBe(true);
    expect(sameVaultPath("C:\\Vault", "C:\\Other", "win32")).toBe(false);
    expect(sameVaultPath("/home/u/Vault", "/home/u/vault", "linux")).toBe(false);
    expect(sameVaultPath("/home/u/vault/", "/home/u/vault", "linux")).toBe(true);
  });
});

/** Dev-a switched, every legacy cohort device retired: the removal may run. */
function switchedAlone(): Machine {
  fleet = makeFleet(["dev-a"]);
  const a = fleet.machine("dev-a");
  a.use();
  expect(runMigration(a.vault, FAST).ok).toBe(true);
  retire(a, "dev-b");
  retire(a, "dev-c");
  // This machine reads its shards, as any reader would.
  expect(a.records().length).toBeGreaterThan(0);
  return a;
}

describe("the store records of files that became machine state", () => {
  test("are adopted, then retired by the removal, when no rollback can run any more", () => {
    const a = switchedAlone();
    // What the migration of an earlier release imported: the procedural
    // usage counters as a lane entry.
    const usage = `${JSON.stringify({ id: "pmem-1", usedCount: 3, lastUsedAt: null })}\n`;
    appendRecord(a.store(), {
      partition: "shared",
      stream: "events",
      kind: "lane-entry",
      agent: "o2b",
      body: {
        authority: "agent",
        lane: "procedural-memory",
        entry: "usage.jsonl",
        fields: {},
        text: usage,
      },
    });
    const removed = removeLegacy(a.vault, { force: true });
    if (!removed.removed) throw new Error("not removed");
    const tombstones = a
      .records()
      .filter((r) => r.kind === "lane-entry-remove" && r.body["lane"] === "procedural-memory");
    expect(tombstones.map((r) => r.body["entry"])).toEqual(["usage.jsonl"]);
    expect(readFileSync(proceduralMemoryUsagePath(a.vault), "utf8")).toBe(usage);
  });
});

describe("a store record this machine could not adopt", () => {
  test.skipIf(CHMOD_CANNOT_DENY)("stays live through the removal, the one copy there is", () => {
    const a = switchedAlone();
    appendRecord(a.store(), {
      partition: "shared",
      stream: "events",
      kind: "lane-entry",
      agent: "o2b",
      body: {
        authority: "agent",
        lane: "procedural-memory",
        entry: "usage.jsonl",
        fields: {},
        text: `${JSON.stringify({ id: "pmem-1", usedCount: 3, lastUsedAt: null })}\n`,
      },
    });
    // The device-local folder the copy would land in refuses writes.
    const dir = dirname(proceduralMemoryUsagePath(a.vault));
    mkdirSync(dir, { recursive: true });
    chmodSync(dir, 0o500);
    try {
      const removed = removeLegacy(a.vault, { force: true });
      if (!removed.removed) throw new Error("not removed");
    } finally {
      chmodSync(dir, 0o700);
    }
    const tombstones = a
      .records()
      .filter((r) => r.kind === "lane-entry-remove" && r.body["lane"] === "procedural-memory");
    expect(tombstones).toEqual([]);
  });
});

describe("a removal while a data shard of the store cannot be seen", () => {
  test("an imported record's shard gone since this machine read it refuses, even with --force", () => {
    const a = switchedAlone();
    const dir = join(a.storeRoot, "shared", "events", "dev-a");
    const [name] = readdirSync(dir);
    const shard = join(dir, name!);
    const bytes = readFileSync(shard);
    rmSync(shard);
    for (const force of [false, true]) {
      expect(() => removeLegacy(a.vault, { force })).toThrow(/shared\/events\/dev-a\//);
      expect(existsSync(join(a.vault, "Brain"))).toBe(true);
      expect(readRemovalMarker(a.store(), a.vault)).toBeNull();
    }
    writeFileSync(shard, bytes);
    expect(removeLegacy(a.vault)).toMatchObject({ removed: true, forced: false });
  });

  test("a corrupt line in the middle of an events shard refuses without --force", () => {
    const a = switchedAlone();
    const peer = openStore({ root: a.storeRoot, device: "dev-p" });
    let shard = "";
    for (const text of ["peer one", "peer two"]) {
      shard = appendRecord(peer, {
        partition: "shared",
        stream: "events",
        kind: "log-event",
        agent: "t",
        body: { timestamp: "2026-11-08T10:00:00Z", event_type: "note", body: { text } },
      }).path;
    }
    writeFileSync(shard, readFileSync(shard, "utf8").replace("peer one", "peer 0ne"));
    expect(() => removeLegacy(a.vault)).toThrow(/cannot be read in full/);
    expect(existsSync(join(a.vault, "Brain"))).toBe(true);
    expect(removeLegacy(a.vault, { force: true })).toMatchObject({ removed: true, forced: true });
  });
});