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
27.8 KB
Raw Blame
/**
 * The migration on the first machine (task 2.3): a clean run, a run killed
 * half way and resumed, a write attempted during the run, two legacy items
 * with identical content, a file that grows during conversion, a
 * verification gap and a backup failure.
 */
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  appendFileSync,
  existsSync,
  mkdirSync,
  readdirSync,
  chmodSync,
  readFileSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { join } from "node:path";

import { frozenMarkerPath, resetFreezeMarkerCache } from "../../../src/core/brain/freeze-marker.ts";
import {
  holdMigrationGate,
  MigrationInProgressError,
  readMigrationGate,
} from "../../../src/core/migration-gate.ts";
import { appendLogEvent } from "../../../src/core/brain/log.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { STORE_DUAL_WRITE_ENV } from "../../../src/core/store/constants.ts";
import { MigrationBackupError } from "../../../src/core/store-migration/backup.ts";
import {
  migrationDir,
  readMigrationState,
  writeMigrationState,
} from "../../../src/core/store-migration/journal.ts";
import { MigrationRefusedError, runMigration } from "../../../src/core/store-migration/migrate.ts";
import { MigrationGateBusyError } from "../../../src/core/store-migration/quiesce.ts";
import {
  DEVICE_SWITCHED_KIND,
  isDeviceSwitched,
  MIGRATION_COHORT_KIND,
  MIGRATION_DONE_KIND,
  MIGRATION_STREAM,
  migrationDoneBody,
} from "../../../src/core/store-migration/migration-records.ts";
import { migrateStore } from "../../../src/core/store-migration/outcome.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import {
  readVaultBindings,
  vaultBindingPath,
} from "../../../src/core/vault-adapter/vault-binding.ts";
import { readViewWriter } from "../../../src/core/view/writer.ts";
import { BENCH_DEVICE, makeMigrationBench, type MigrationBench } from "./fixtures/migration-env.ts";
import {
  addProviderProfile,
  loadProviderRegistry,
  type ProviderProfile,
} from "../../../src/core/search/embeddings/registry.ts";
import {
  addRerankProviderProfile,
  loadRerankRegistry,
  type RerankProviderProfile,
} from "../../../src/core/search/rerank/registry.ts";
import { forgetMachineStateCache } from "../../../src/core/state/machine-state.ts";
import { proceduralMemoryUsagePath } from "../../../src/core/brain/paths.ts";
import {
  listProceduralMemory,
  markProceduralMemoryUsed,
} from "../../../src/core/brain/procedural-memory.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { digestVaultTree } from "../../helpers/vault-digest.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

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

let bench: MigrationBench;
beforeEach(() => {
  bench = makeMigrationBench();
});
afterEach(() => bench.cleanup());

const FAST = { settleMs: 0 } as const;
const KILL_CHILD = join(import.meta.dir, "fixtures", "kill-child.ts");

/** The legacy item keys of the fixture vault with nothing unmapped. */
const FIXTURE_ITEM_KEYS = [
  ".open-second-brain/hook-audit/2026-W45.dev-b.jsonl#1",
  "Brain/inbox/2026-11-01-tabs.md",
  "Brain/inbox/processed/2026-10-01-old.md",
  "Brain/log/2026-10-01.jsonl#1",
  "Brain/log/2026-11-01.dev-a.jsonl#1",
  "Brain/log/2026-11-01.dev-a.jsonl#2",
  "Brain/log/2026-11-01.dev-b.jsonl#1",
  "Brain/log/2026-11-01.dev-b.jsonl#3",
  "Brain/log/continuity/2026-09.dev-c.jsonl#1",
  "Brain/log/continuity/2026-11.dev-a.jsonl#1",
  "Brain/log/pref-audit/pref-secret/device.dev-a.jsonl#1",
  "Brain/logs/idempotency/2026-11.dev-b.jsonl#1",
  "Brain/metrics/recall.dev-a.jsonl#1",
  "Brain/obligations/archive/obl-old.md",
  "Brain/pending/2026-11-02-staged.md",
  "Brain/pinned.md",
  "Brain/preferences/pref-open.history.dev-a.jsonl#1",
  "Brain/preferences/pref-open.md",
  "Brain/preferences/pref-secret.md",
  "Brain/procedures/deploy.md",
  "Brain/retired/ret-gone.md",
  "Brain/standing-rules.md",
  "Brain/standing-rules/project/osb.md",
  "Brain/state/current-focus.md",
];

function kinds(): string[] {
  return bench.records().map((r) => r.kind);
}

describe("runMigration", () => {
  test("accepted skills under Brain/skills move to the vault's skills/ as files, not records", () => {
    const legacy = join(bench.vault, "Brain", "skills", "release-ritual", "SKILL.md");
    mkdirSync(join(legacy, ".."), { recursive: true });
    writeFileSync(legacy, "---\nname: release-ritual\ndescription: d\n---\nBody.\n");
    const taken = join(bench.vault, "skills", "mine", "SKILL.md");
    mkdirSync(join(taken, ".."), { recursive: true });
    writeFileSync(taken, "the user's own\n");
    const clash = join(bench.vault, "Brain", "skills", "mine", "SKILL.md");
    mkdirSync(join(clash, ".."), { recursive: true });
    writeFileSync(clash, "the legacy copy\n");
    const result = runMigration(bench.vault, FAST);
    expect(result.ok).toBe(true);
    expect(
      readFileSync(join(bench.vault, "skills", "release-ritual", "SKILL.md"), "utf8"),
    ).toContain("release-ritual");
    expect(result.vault_files).toContain("Brain/skills/release-ritual/SKILL.md");
    // A different file already there is the user's: kept and named.
    expect(readFileSync(taken, "utf8")).toBe("the user's own\n");
    expect(result.vault_files_kept).toEqual(["Brain/skills/mine/SKILL.md"]);
    expect(bench.records().some((r) => String(r.body["entry"] ?? "").includes("skills"))).toBe(
      false,
    );
  });

  test("a custom search provider registered before the switch still resolves after it", () => {
    const embed: ProviderProfile = {
      name: "my-embed",
      baseUrl: "http://127.0.0.1:9/v1",
      defaultModel: "m",
      envKey: "O2B_TEST_EMBED_KEY",
    };
    const rerank: RerankProviderProfile = {
      name: "my-rerank",
      baseUrl: "http://127.0.0.1:9/v1",
      defaultModel: "r",
      envKey: "O2B_TEST_RERANK_KEY",
    };
    addProviderProfile(bench.vault, embed);
    addRerankProviderProfile(bench.vault, rerank);
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    forgetMachineStateCache();
    expect(loadProviderRegistry(bench.vault).map((p) => p.name)).toEqual(["my-embed"]);
    expect(loadRerankRegistry(bench.vault).map((p) => p.name)).toEqual(["my-rerank"]);
    // Device-local, never a shared record.
    expect(bench.records().some((r) => JSON.stringify(r.body).includes("my-embed"))).toBe(false);
  });

  test("procedural usage counters move into the device-local state, never into a record", () => {
    // A legacy machine used the procedure; its counters sit beside the index.
    const pmem = join(bench.vault, "Brain", "procedural-memory");
    mkdirSync(pmem, { recursive: true });
    const id = "pmem-000000000001";
    const entry = {
      id,
      kind: "procedure",
      sourcePath: "Brain/procedures/deploy.md",
      title: "Deploy",
      triggers: [],
      tags: [],
      permissions: [],
      source: null,
      version: null,
      lastUsedAt: "2026-11-01T09:00:00.000Z",
      usedCount: 3,
      successCount: 2,
      failureCount: 1,
    };
    writeFileSync(
      join(pmem, "index.json"),
      `${JSON.stringify({ schema_version: 1, entries: [entry] })}\n`,
    );
    writeFileSync(
      join(pmem, "usage.jsonl"),
      `${JSON.stringify({ id, usedCount: 3, lastUsedAt: entry.lastUsedAt, successCount: 2, failureCount: 1 })}\n`,
    );
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    forgetMachineStateCache();
    expect(proceduralMemoryUsagePath(bench.vault).startsWith(bench.vault)).toBe(false);
    expect(readFileSync(proceduralMemoryUsagePath(bench.vault), "utf8")).toContain(id);
    expect(listProceduralMemory(bench.vault)).toEqual([
      expect.objectContaining({ id, usedCount: 3, successCount: 2, failureCount: 1 }),
    ]);
    const laneEntries = bench.records().filter((r) => r.kind === "lane-entry");
    expect(laneEntries.some((r) => String(r.body["entry"]).startsWith("usage"))).toBe(false);
    // A tick on the switched machine counts on, and appends no record.
    const before = bench.records().length;
    markProceduralMemoryUsed(bench.vault, id, new Date("2026-11-15T10:00:00Z"));
    expect(bench.records()).toHaveLength(before);
    expect(listProceduralMemory(bench.vault)[0]?.usedCount).toBe(4);
  });

  test("a clean run imports every item once, backs up, archives and records the switch", () => {
    const prefsBefore = digestVaultTree(join(bench.vault, "Brain", "preferences"), { mtime: true });
    const result = runMigration(bench.vault, FAST);
    expect(result.ok).toBe(true);
    expect(result.gaps).toEqual([]);

    const byKey = bench.byKey();
    for (const [key, records] of byKey) expect([key, records.length]).toEqual([key, 1]);
    // Every item the fixture plants (legacy-vault.ts), by its own key; the
    // malformed dev-b line 2 is archived, not imported. The one key beyond
    // them is the run's own log row of today (the snapshot audit).
    const runOwn = [...byKey.keys()].filter(
      (k) =>
        /^Brain\/log\/\d{4}-\d{2}-\d{2}\.dev-a\.jsonl#1$/.test(k) &&
        !k.startsWith("Brain/log/2026-11-01."),
    );
    expect(runOwn).toHaveLength(1);
    expect([...byKey.keys()].filter((k) => k !== runOwn[0]).toSorted()).toEqual(FIXTURE_ITEM_KEYS);
    expect(byKey.get("Brain/inbox/2026-11-01-tabs.md")?.[0]?.kind).toBe("signal");
    expect(byKey.get("Brain/log/2026-11-01.dev-b.jsonl#3")?.[0]?.kind).toBe("log-event");
    expect(byKey.get("Brain/standing-rules.md")?.[0]?.body["authority"]).toBe("human");
    expect(byKey.get("Brain/preferences/pref-secret.md")?.[0]?.partition).toBe("private");

    expect(kinds().filter((k) => k === MIGRATION_COHORT_KIND)).toHaveLength(1);
    expect(kinds().filter((k) => k === MIGRATION_DONE_KIND)).toHaveLength(1);
    expect(kinds().filter((k) => k === DEVICE_SWITCHED_KIND)).toHaveLength(1);
    expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(true);
    expect(isDeviceSwitched(bench.store(), "dev-b")).toBe(false);
    expect(result.cohort).toEqual(["dev-a", "dev-b", "dev-c"]);
    expect(result.view_writer).toBe(BENCH_DEVICE);
    expect(readViewWriter(bench.store()).writer).toBe(BENCH_DEVICE);

    // Backups: the snapshot copy and the explicit backup of the secrets.
    expect(result.backup?.snapshot).toMatch(/^store-migration-/);
    expect(result.backup?.files.map((f) => f.path)).toContain(".open-second-brain/secrets/keyfile");
    // The malformed line is kept with its path, line and bytes.
    const archived = readFileSync(result.unparseable_archive, "utf8").trim().split("\n");
    const row = JSON.parse(archived[0]!) as Record<string, unknown>;
    expect(row).toMatchObject({
      path: "Brain/log/2026-11-01.dev-b.jsonl",
      line: 2,
      reason: "not JSON",
    });
    expect(Buffer.from(row["bytes_base64"] as string, "base64").toString()).toBe("{not json");

    expect(existsSync(frozenMarkerPath(bench.vault))).toBe(false);
    expect(readMigrationGate()).toBeNull();
    expect(digestVaultTree(join(bench.vault, "Brain", "preferences"), { mtime: true })).toBe(
      prefsBefore,
    );
    expect(readMigrationState(migrationDir(bench.store()))?.phase).toBe("done");
    expect(() => runMigration(bench.vault, FAST)).toThrow("already switched");
    // Device-local state: the backup-class secrets live in `local/` after
    // the switch; the vault's search index is not copied (it is rebuilt).
    const local = join(migrationDir(bench.store()), "local", ".open-second-brain");
    expect(readFileSync(join(local, "secrets", "keyfile"), "utf8")).toBe("secret-bytes");
    expect(existsSync(join(local, "brain.sqlite"))).toBe(false);
  });

  test("a run killed half way keeps the gate, refuses writers and resumes with --resume once", () => {
    // A real kill: the child SIGKILLs itself after the fifth item's records
    // are appended and before its journal row, so no `finally` lifts the
    // gate and no state is saved on the way out.
    const child = Bun.spawnSync(
      [process.execPath, "run", KILL_CHILD, "migrate", bench.vault, "5"],
      { env: { ...process.env, ...bench.env }, stdout: "ignore", stderr: "pipe" },
    );
    expect(child.success).toBe(false);
    expect(child.exitCode).not.toBe(3);
    if (process.platform !== "win32") expect(child.signalCode).toBe("SIGKILL");
    resetFreezeMarkerCache();

    // What the kill left: an interrupted run that still holds the gate,
    // and part of the vault in the store.
    const state = readMigrationState(migrationDir(bench.store()));
    expect(state?.phase).toBe("in-progress");
    expect(readMigrationGate()?.run_id).toBe(state!.run_id);
    const partial = bench.byKey().size;
    expect(partial).toBeGreaterThanOrEqual(5);

    // Between the crash and the resume this machine's writers are refused
    // and nothing lands in the legacy tree.
    const inbox = join(bench.vault, "Brain", "inbox");
    const inboxBefore = readdirSync(inbox).toSorted();
    expect(() =>
      writeSignal(bench.vault, {
        topic: "after-crash",
        signal: "positive",
        agent: "@late",
        principle: "Written after the crash",
        created_at: "2026-11-06T10:00:00Z",
        date: "2026-11-06",
        slug: "after-crash",
      }),
    ).toThrow(MigrationInProgressError);
    expect(readdirSync(inbox).toSorted()).toEqual(inboxBefore);
    // A fresh run is refused: only --resume continues the interrupted one.
    expect(() => runMigration(bench.vault, FAST)).toThrow(MigrationRefusedError);

    const result = runMigration(bench.vault, { ...FAST, resume: true });
    expect(result.ok).toBe(true);
    expect(result.run_id).toBe(state!.run_id);
    expect(bench.byKey().size).toBeGreaterThan(partial);
    for (const [key, records] of bench.byKey()) expect([key, records.length]).toEqual([key, 1]);
    expect(kinds().filter((k) => k === MIGRATION_COHORT_KIND)).toHaveLength(1);
    expect(readMigrationGate()).toBeNull();
  });

  test("a write attempted during the migration is refused and leaves no legacy file", () => {
    const inbox = join(bench.vault, "Brain", "inbox");
    const before = readdirSync(inbox).toSorted();
    let refused: unknown = null;
    const result = runMigration(bench.vault, {
      ...FAST,
      hooks: {
        afterBackup: () => {
          try {
            writeSignal(bench.vault, {
              topic: "late",
              signal: "positive",
              agent: "@late",
              principle: "Written while migrating",
              created_at: "2026-11-06T10:00:00Z",
              date: "2026-11-06",
              slug: "late",
            });
          } catch (error) {
            refused = error;
          }
        },
      },
    });
    expect(refused).toBeInstanceOf(MigrationInProgressError);
    expect(readdirSync(inbox).toSorted()).toEqual(before);
    // The refused write left the run itself whole.
    expect(result.ok).toBe(true);
  });

  test("two legacy items with identical content stay two records", () => {
    const line = JSON.stringify({
      ts: "2026-11-02T00:00:00Z",
      kind: "note",
      payload: { text: "same" },
    });
    bench.fx.write("Brain/log/2026-11-02.dev-a.jsonl", `${line}\n${line}\n`);
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    const byKey = bench.byKey();
    const a = byKey.get("Brain/log/2026-11-02.dev-a.jsonl#1")!;
    const b = byKey.get("Brain/log/2026-11-02.dev-a.jsonl#2")!;
    expect(a).toHaveLength(1);
    expect(b).toHaveLength(1);
    expect(a[0]!.id).not.toBe(b[0]!.id);
  });

  test("a legacy file that grows during conversion is imported by the delta pass", () => {
    const shard = join(bench.vault, "Brain", "log", "2026-11-01.dev-a.jsonl");
    const late = JSON.stringify({
      ts: "2026-11-01T23:00:00Z",
      kind: "note",
      payload: { text: "late" },
    });
    let grown = false;
    const result = runMigration(bench.vault, {
      ...FAST,
      hooks: {
        afterItemAppended: () => {
          if (grown) return;
          grown = true;
          appendFileSync(shard, `${late}\n`);
        },
      },
    });
    expect(result.ok).toBe(true);
    expect(result.passes).toBeGreaterThan(1);
    const lines = readFileSync(shard, "utf8").trim().split("\n").length;
    const imported = bench.byKey().get(`Brain/log/2026-11-01.dev-a.jsonl#${lines}`);
    expect(imported?.[0]?.body["body"]).toMatchObject({ text: "late" });
  });

  test("a verification gap fails the run, names the item and leaves the legacy tree", () => {
    const signal = join(bench.vault, "Brain", "inbox", "2026-11-01-tabs.md");
    const before = readFileSync(signal, "utf8");
    const result = runMigration(bench.vault, {
      ...FAST,
      hooks: {
        beforeVerify: () => {
          // Lose the signal's record, as a damaged shard would.
          const dir = join(bench.storeRoot, "shared", "events", BENCH_DEVICE);
          for (const name of readdirSync(dir)) {
            const path = join(dir, name);
            const kept = readFileSync(path, "utf8")
              .split("\n")
              .filter((l) => !l.includes('"sig-tabs"'));
            writeFileSync(path, kept.join("\n"));
          }
        },
      },
    });
    expect(result.ok).toBe(false);
    expect(result.gaps.map((g) => g.key)).toContain("Brain/inbox/2026-11-01-tabs.md");
    expect(result.migration_done).toBeNull();
    expect(kinds()).not.toContain(MIGRATION_DONE_KIND);
    expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(false);
    expect(readFileSync(signal, "utf8")).toBe(before);
    expect(readMigrationState(migrationDir(bench.store()))?.phase).toBe("failed");
  });

  test("a backup failure stops the run before anything is imported", () => {
    const dir = migrationDir(bench.store());
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, "backup"), "a file where the backup folder goes");
    expect(() => runMigration(bench.vault, FAST)).toThrow(MigrationBackupError);
    expect(bench.byKey().size).toBe(0);
    expect(kinds()).not.toContain(MIGRATION_COHORT_KIND);
    expect(readMigrationState(dir)?.phase).toBe("failed");
    expect(existsSync(frozenMarkerPath(bench.vault))).toBe(false);
  });

  test("imported records name the device of their legacy shard", () => {
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    const byKey = bench.byKey();
    expect(byKey.get("Brain/log/2026-11-01.dev-b.jsonl#3")?.[0]?.body["legacy_device"]).toBe(
      "dev-b",
    );
    expect(byKey.get("Brain/log/2026-10-01.jsonl#1")?.[0]?.body["legacy_device"]).toBe("");
    expect(byKey.get("Brain/inbox/2026-11-01-tabs.md")?.[0]?.body["legacy_device"]).toBe("");
  });

  test("an item cut off between its two records is completed on resume", () => {
    bench.fx.write(
      "Brain/preferences/pref-mine.md",
      "---\nid: pref-mine\nprinciple: Mine\norigin_channel: cli\nstatus: active\n---\n",
    );
    expect(() =>
      runMigration(bench.vault, {
        ...FAST,
        hooks: {
          afterPartAppended: (part, parts) => {
            if (parts === 2 && part === 0) throw new Error("killed between parts");
          },
        },
      }),
    ).toThrow("killed between parts");
    expect(runMigration(bench.vault, { ...FAST, resume: true }).ok).toBe(true);
    const records = bench.byKey().get("Brain/preferences/pref-mine.md")!;
    expect(records.map((r) => (r.body["migrated"] as { part: number }).part).toSorted()).toEqual([
      0, 1,
    ]);
    expect(records.map((r) => r.body["authority"]).toSorted()).toEqual(["agent", "human"]);
  });

  test("copies a dual write already stored are matched, not imported again", () => {
    const prior = process.env[STORE_DUAL_WRITE_ENV];
    process.env[STORE_DUAL_WRITE_ENV] = "1";
    try {
      const event = {
        timestamp: "2026-11-03T10:00:00Z",
        eventType: "note",
        agent: "@dw",
        body: { text: "dw" },
      } as const;
      appendLogEvent(bench.vault, event);
      appendLogEvent(bench.vault, event);
      writeSignal(bench.vault, {
        topic: "dw",
        signal: "positive",
        agent: "@dw",
        principle: "Dual written",
        created_at: "2026-11-03T10:00:00Z",
        date: "2026-11-03",
        slug: "dw-sig",
      });
    } finally {
      if (prior === undefined) delete process.env[STORE_DUAL_WRITE_ENV];
      else process.env[STORE_DUAL_WRITE_ENV] = prior;
    }
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    const all = bench.records();
    const dwEvents = all.filter(
      (r) => r.kind === "log-event" && (r.body["body"] as { text?: string })?.text === "dw",
    );
    expect(dwEvents).toHaveLength(2);
    expect(dwEvents.every((r) => r.body["migrated"] === undefined)).toBe(true);
    const dwSignals = all.filter(
      (r) => r.kind === "signal" && String(r.body["id"]).includes("dw-sig"),
    );
    expect(dwSignals).toHaveLength(1);
  });

  test("a run that recorded its own completion before a kill stays the first machine", () => {
    // What a kill between `migration-done` and `device-switched` leaves.
    const own = appendRecord(bench.store(), {
      partition: "shared",
      stream: MIGRATION_STREAM,
      kind: MIGRATION_DONE_KIND,
      agent: "test",
      body: migrationDoneBody({ vaultId: null, device: BENCH_DEVICE, cuts: {}, imported: 0 }),
    }).record.id;
    const result = runMigration(bench.vault, FAST);
    expect(result.ok).toBe(true);
    expect(result.role).toBe("first");
    expect(result.migration_done).toBe(own);
    expect(kinds().filter((k) => k === MIGRATION_DONE_KIND)).toHaveLength(1);
    expect(readViewWriter(bench.store()).writer).toBe(BENCH_DEVICE);
  });

  test("a run killed after its switch record is finished by the next migrate-store", () => {
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    // What a kill right after `device-switched` leaves: the run still
    // in progress, the gate held and the vault not bound yet.
    const dir = migrationDir(bench.store());
    const state = readMigrationState(dir)!;
    writeMigrationState(dir, { ...state, phase: "in-progress" });
    holdMigrationGate(bench.vault, state.run_id);
    rmSync(vaultBindingPath(), { force: true });

    const outcome = migrateStore(bench.vault, FAST);
    expect(outcome.mode).toBe("transition");
    expect(readMigrationState(dir)?.phase).toBe("done");
    expect(readMigrationGate()).toBeNull();
    expect(readVaultBindings().map((b) => b.device)).toEqual([BENCH_DEVICE]);
  });

  // POSIX modes only, and root reads a 0000 file anyway.
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a store shard this machine cannot read refuses the run before anything is imported",
    () => {
      const shard = appendRecord(bench.store(), {
        partition: "shared",
        stream: "events",
        kind: "note",
        agent: "test",
        body: { text: "x" },
      }).path;
      chmodSync(shard, 0o000);
      try {
        expect(() => runMigration(bench.vault, FAST)).toThrow(MigrationRefusedError);
        expect(readMigrationState(migrationDir(bench.store()))).toBeNull();
      } finally {
        chmodSync(shard, 0o644);
      }
    },
  );

  /** A peer's events shard with two records, which this machine has read. */
  function peerShard(): string {
    const peer = openStore({ root: bench.storeRoot, device: "dev-p" });
    let shard = "";
    for (const text of ["peer one", "peer two"]) {
      shard = appendRecord(peer, {
        partition: "shared",
        stream: "events",
        kind: "note",
        agent: "test",
        body: { text },
      }).path;
    }
    expect(bench.records().length).toBeGreaterThan(0);
    return shard;
  }

  test("a store shard read only in part refuses the run before anything is imported", () => {
    const shard = peerShard();
    writeFileSync(shard, readFileSync(shard, "utf8").replace("peer one", "peer 0ne"));
    expect(() => runMigration(bench.vault, FAST)).toThrow(/shared\/events\/dev-p\//);
    expect(readMigrationState(migrationDir(bench.store()))).toBeNull();
    expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(false);
  });

  test("a store shard gone during the run refuses the switch, and a later run switches", () => {
    const shard = peerShard();
    const bytes = readFileSync(shard);
    expect(() =>
      runMigration(bench.vault, { ...FAST, hooks: { beforeVerify: () => rmSync(shard) } }),
    ).toThrow(/shared\/events\/dev-p\//);
    expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(false);
    expect(readMigrationState(migrationDir(bench.store()))?.phase).toBe("failed");
    expect(readMigrationGate()).toBeNull();
    writeFileSync(shard, bytes);
    expect(runMigration(bench.vault, FAST).ok).toBe(true);
    expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(true);
  });

  test("a log line that is not UTF-8 is archived with its exact bytes, never imported", () => {
    const good = JSON.stringify({
      ts: "2026-11-04T10:00:00Z",
      kind: "note",
      payload: { text: "ok" },
      prev: null,
      h: "0".repeat(64),
    });
    // Valid JSON once a lenient decoder turns 0xff into U+FFFD.
    const bad = Buffer.concat([
      Buffer.from('{"ts":"2026-11-04T11:00:00Z","kind":"note","payload":{"text":"'),
      Buffer.from([0xff, 0xfe]),
      Buffer.from('"},"prev":null,"h":"' + "0".repeat(64) + '"}'),
    ]);
    const path = join(bench.vault, "Brain", "log", "2026-11-04.dev-b.jsonl");
    writeFileSync(path, Buffer.concat([Buffer.from(`${good}\n`), bad, Buffer.from("\n")]));

    const result = runMigration(bench.vault, FAST);
    expect(result.ok).toBe(true);
    expect(bench.byKey().has("Brain/log/2026-11-04.dev-b.jsonl#1")).toBe(true);
    expect(bench.byKey().has("Brain/log/2026-11-04.dev-b.jsonl#2")).toBe(false);
    const rows = readFileSync(result.unparseable_archive, "utf8")
      .trim()
      .split("\n")
      .map((line) => JSON.parse(line) as Record<string, unknown>);
    const row = rows.find((r) => r["path"] === "Brain/log/2026-11-04.dev-b.jsonl");
    expect(row).toMatchObject({ line: 2, reason: "not UTF-8 text" });
    expect(Buffer.from(row!["bytes_base64"] as string, "base64").equals(bad)).toBe(true);
  });

  // A directory symlink needs a privilege Windows CI does not grant.
  test.skipIf(process.platform === "win32")(
    "a link planted at the vault's skills/ refuses the move and writes nothing outside the vault",
    () => {
      const legacy = join(bench.vault, "Brain", "skills", "release-ritual", "SKILL.md");
      mkdirSync(join(legacy, ".."), { recursive: true });
      writeFileSync(legacy, "---\nname: release-ritual\ndescription: d\n---\nBody.\n");
      const outside = join(bench.fx.parent, "outside");
      mkdirSync(outside);
      symlinkSync(outside, join(bench.vault, "skills"));
      expect(() => runMigration(bench.vault, FAST)).toThrow(/leads out of the vault/);
      expect(readdirSync(outside)).toEqual([]);
      expect(isDeviceSwitched(bench.store(), BENCH_DEVICE)).toBe(false);
    },
  );

  test.skipIf(process.platform === "win32")(
    "a dangling link planted at the vault's skills/ refuses the move and writes nothing outside the vault",
    () => {
      const legacy = join(bench.vault, "Brain", "skills", "release-ritual", "SKILL.md");
      mkdirSync(join(legacy, ".."), { recursive: true });
      writeFileSync(legacy, "---\nname: release-ritual\ndescription: d\n---\nBody.\n");
      // The link's destination does not exist yet: the copy would create it.
      const outside = join(bench.fx.parent, "outside-not-yet");
      symlinkSync(outside, join(bench.vault, "skills"));
      expect(() => runMigration(bench.vault, FAST)).toThrow(/leads out of the vault/);
      expect(existsSync(outside)).toBe(false);
    },
  );

  test("a gate another vault's interrupted run holds is never taken or released", () => {
    const other = join(bench.fx.parent, "other-vault");
    mkdirSync(other);
    holdMigrationGate(other, "migrate-other");
    expect(() => runMigration(bench.vault, FAST)).toThrow(MigrationGateBusyError);
    expect(readMigrationGate()?.run_id).toBe("migrate-other");
    // Refused before it started: no interrupted run is left to resume.
    expect(readMigrationState(migrationDir(bench.store()))).toBeNull();
  });
});