Skip to content

Write HTML. Render video. Built for agents.

112 KB
Raw Blame
// @vitest-environment node
// fallow-ignore-file code-duplication
import {
  appendFileSync,
  chmodSync,
  cpSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  statSync,
  symlinkSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { spawnSync } from "node:child_process";
import { tmpdir } from "node:os";
import { basename, dirname, join, relative } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { fileContentVersion, hashOfVersion, recordFileWriteReceipt } from "../helpers/fileVersion";
import { HistoryBusyError } from "./ownerLock";
import { HistoryIdError } from "./historyId";
import {
  HistoryClosedError,
  openProjectHistory,
  readProjectHistory,
  type ProjectHistory,
} from "./projectHistory";
import { START, type HistoryWho } from "./historyLog";
import { openBlobStore } from "./blobStore";

// A test can hold a media copy, and run work after its blob is stored but before history records it.
const mediaCopy = vi.hoisted(() => ({
  held: null as Promise<void> | null,
  stored: null as (() => Promise<unknown>) | null,
  copies: [] as string[],
  fails: null as ((copy: number) => boolean) | null,
}));
vi.mock("./blobStore", async (importOriginal) => {
  const real = await importOriginal<typeof import("./blobStore")>();
  return {
    ...real,
    openBlobStore: async (dir: string) => {
      const store = await real.openBlobStore(dir);
      return {
        ...store,
        put: async (path: string) => {
          if (path.endsWith(".mp4")) {
            await mediaCopy.held;
            mediaCopy.copies.push(basename(path));
            if (mediaCopy.fails?.(mediaCopy.copies.length)) throw new Error("The disk is full.");
          }
          const hash = await store.put(path);
          if (path.endsWith(".mp4")) await mediaCopy.stored?.();
          return hash;
        },
      };
    },
  };
});

const you: HistoryWho = { kind: "person", name: "You" };
const pause = (ms: number) => new Promise((settle) => setTimeout(settle, ms));
const agent: HistoryWho = { kind: "agent", name: "Agent" };
const cleanup: Array<() => unknown> = [];

afterEach(async () => {
  for (const step of cleanup.splice(0).reverse()) await step();
  Object.assign(mediaCopy, { held: null, stored: null, copies: [], fails: null });
});

const inside = (dir: string, path: string) => readFileSync(join(dir, path), "utf-8");

function caseInsensitive(): boolean {
  const dir = mkdtempSync(join(tmpdir(), "hf-history-case-"));
  try {
    return existsSync(dir.toUpperCase());
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

function tempDir(prefix: string): string {
  const dir = mkdtempSync(join(tmpdir(), prefix));
  cleanup.push(() => rmSync(dir, { recursive: true, force: true }));
  return dir;
}

async function open(projectDir: string, historyRoot: string, options = {}) {
  const history = await openProjectHistory({ projectDir, historyRoot, ...options });
  cleanup.push(() => history.close());
  return history;
}

async function project(files: Record<string, string | Buffer>, options = {}) {
  const projectDir = tempDir("hf-history-project-");
  const historyRoot = tempDir("hf-history-root-");
  const write = (path: string, content: string | Buffer) => {
    mkdirSync(dirname(join(projectDir, path)), { recursive: true });
    writeFileSync(join(projectDir, path), content);
  };
  for (const [path, content] of Object.entries(files)) write(path, content);
  const history = await open(projectDir, historyRoot, options);
  const read = (path: string) => readFileSync(join(projectDir, path), "utf-8");
  const has = (path: string) => existsSync(join(projectDir, path));
  return { projectDir, historyRoot, history, write, read, has };
}

/** A log as an older version leaves it: no marker; 0.8.123's baseline also never names the media ledger. */
function asWrittenBy(version: "0.8.122" | "0.8.123", logFile: string) {
  const lines = readFileSync(logFile, "utf-8")
    .trim()
    .split("\n")
    .map((line) => JSON.parse(line));
  for (const record of lines.filter((line) => line.type === "baseline")) {
    if (version === "0.8.123") delete record.files[".media/manifest.jsonl"];
    delete record.keepsLedger;
  }
  writeFileSync(logFile, lines.map((record) => JSON.stringify(record)).join("\n") + "\n");
}

/** Undoes the newest change still in effect, whoever made it; Cmd+Z steps only over the caller's own. */
async function undoNewest(history: ProjectHistory) {
  const newest = [...history.list()].reverse().find((entry) => !entry.undoes && !entry.undone);
  return history.undo(newest!.id, { who: you });
}

/** An agent turn writes B, C, D; the person's drag claims C (written over B) and is held when the turn closes. */
async function dragDuringTurn(
  history: ProjectHistory,
  write: (path: string, content: string) => void,
) {
  const window = await history.beginWindow(agent, "Agent turn");
  write("index.html", "B");
  await history.claim(you, "sweep", []);
  write("index.html", "C");
  await history.claim(you, "Dragged Title", ["index.html"], {
    coalesceKey: "drag",
    idleMs: 60_000,
    overwrote: { "index.html": fileContentVersion("B") },
  });
  write("index.html", "D");
  await window.close();
}

/** Runs `writes` inside a window of `who`'s and returns the entry it became. */
async function change(history: ProjectHistory, who: HistoryWho, label: string, writes: () => void) {
  const window = await history.beginWindow(who, label);
  writes();
  const entry = await window.close();
  if (!entry) throw new Error("the window recorded nothing");
  return entry;
}

describe("openProjectHistory", () => {
  it("never writes a hidden file an older log still names, on undo or restore", async () => {
    const { history, write, read, projectDir, historyRoot } = await project({
      "index.html": "v1",
      "turn-record": "A",
    });
    const turn = await change(history, agent, "Agent turn", () => {
      write("index.html", "v2");
      write("turn-record", "B");
    });
    await history.close();
    // What an older log holds: the record under its hidden name, as history filed it before.
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    writeFileSync(
      logFile,
      readFileSync(logFile, "utf-8").replaceAll('"turn-record"', '".turn-record"'),
    );
    renameSync(join(projectDir, "turn-record"), join(projectDir, ".turn-record"));
    const reopened = await open(projectDir, historyRoot);
    write(".turn-record", "C");
    expect((await reopened.undo(turn.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("v1");
    expect(read(".turn-record")).toBe("C");
    await reopened.restore(START, you);
    expect(read(".turn-record")).toBe("C");
  });

  it("steps Undo past an older log's entry that changed only a hidden file", async () => {
    const { history, write, read, projectDir, historyRoot } = await project(
      { "index.html": "v1", "turn-record": "A" },
      { quietMs: 30 },
    );
    await change(history, you, "Your edit", () => write("index.html", "v2"));
    write("turn-record", "B");
    history.noteChange("turn-record");
    await history.flush();
    expect(history.list().map((entry) => entry.who.kind)).toEqual(["person", "outside"]);
    await history.close();
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    writeFileSync(
      logFile,
      readFileSync(logFile, "utf-8").replaceAll('"turn-record"', '".turn-record"'),
    );
    renameSync(join(projectDir, "turn-record"), join(projectDir, ".turn-record"));
    const reopened = await open(projectDir, historyRoot);
    expect(reopened.list().map((entry) => entry.files.length)).toEqual([1, 0]);
    expect(await reopened.step("back", you)).toMatchObject({ ok: true });
    expect(read("index.html")).toBe("v1");
  });

  it("keeps every entry an older log names, emptied ones too, and undoing one still lands", async () => {
    const { history, write, projectDir, historyRoot } = await project(
      { "index.html": "v1", "turn-record": "A" },
      { quietMs: 30 },
    );
    write("turn-record", "B");
    history.noteChange("turn-record");
    await history.flush();
    const [hidden] = history.list();
    await history.pin(hidden!.id, true);
    await history.close();
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    writeFileSync(
      logFile,
      readFileSync(logFile, "utf-8").replaceAll('"turn-record"', '".turn-record"'),
    );
    renameSync(join(projectDir, "turn-record"), join(projectDir, ".turn-record"));
    const reopened = await open(projectDir, historyRoot);
    expect(reopened.list()).toMatchObject([{ id: hidden!.id, files: [], pinned: true }]);
    const undone = await reopened.undo(hidden!.id, { who: you });
    expect(undone).toMatchObject({ ok: true, entry: { undoes: hidden!.id, files: [] } });
  });

  it("keeps an older log's Undo that only reverted a hidden file, so its target stays undone", async () => {
    const { history, write, projectDir, historyRoot } = await project({
      "index.html": "A",
      "turn-record": "H0",
    });
    const yours = await change(history, you, "Your edit", () => {
      write("index.html", "B");
      write("turn-record", "H1");
    });
    await change(history, agent, "Agent turn", () => write("index.html", "C"));
    const keep = { who: you, mode: "keep-later-edits" } as const;
    expect(await history.undo(yours.id, keep)).toMatchObject({ ok: true });
    expect(history.next("back", you)).toBeUndefined();
    await history.close();
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    writeFileSync(
      logFile,
      readFileSync(logFile, "utf-8").replaceAll('"turn-record"', '".turn-record"'),
    );
    renameSync(join(projectDir, "turn-record"), join(projectDir, ".turn-record"));
    const reopened = await open(projectDir, historyRoot);
    expect(reopened.next("back", you)).toBeUndefined();
    expect(reopened.next("forward", you)).toBeUndefined();
  });

  it("a log 0.8.123 wrote without the media ledger takes it in, so the first Undo undoes the edit", async () => {
    const { history, write, read, projectDir, historyRoot } = await project({
      "index.html": "A",
      ".media/manifest.jsonl": "{}\n",
    });
    await change(history, you, "Your edit", () => write("index.html", "B"));
    await history.close();
    asWrittenBy("0.8.123", join(historyRoot, history.projectId, "log.jsonl"));
    const reopened = await open(projectDir, historyRoot);
    expect(await reopened.step("back", you)).toMatchObject({ ok: true });
    expect([read("index.html"), read(".media/manifest.jsonl")]).toEqual(["A", "{}\n"]);
  });

  // Windows needs a privilege to create symlinks.
  it.skipIf(process.platform === "win32")(
    "a log 0.8.123 wrote never takes in a ledger behind a link",
    async () => {
      const { history, projectDir, historyRoot } = await project(
        { "index.html": "A" },
        { quietMs: 30 },
      );
      await history.close();
      asWrittenBy("0.8.123", join(historyRoot, history.projectId, "log.jsonl"));
      const outside = tempDir("hf-history-linked-");
      writeFileSync(join(outside, "manifest.jsonl"), "{}\n");
      symlinkSync(outside, join(projectDir, ".media"), "dir");
      const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
      await reopened.flush();
      expect(reopened.list()).toEqual([]);
    },
  );

  it("a ledger made while the project was closed is a change like any file, once a log keeps the ledger", async () => {
    const { history, write, read, has, projectDir, historyRoot } = await project(
      { "index.html": "A" },
      { quietMs: 30 },
    );
    await history.close();
    write("index.html", "B");
    write(".media/manifest.jsonl", "{}\n");
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await reopened.flush();
    const [outside] = reopened.list();
    expect(outside!.files.map((file) => file.path).sort()).toEqual([
      ".media/manifest.jsonl",
      "index.html",
    ]);
    expect((await reopened.undo(outside!.id, { who: you })).ok).toBe(true);
    expect([read("index.html"), has(".media/manifest.jsonl")]).toEqual(["A", false]);
  });

  it("a ledger made while closed is still a change after the project's media was copied in the background", async () => {
    const { history, write, has, projectDir, historyRoot } = await project(
      { "index.html": "A", "clip.mp4": Buffer.alloc(2 * 1024 ** 2, 7) },
      { quietMs: 30 },
    );
    await vi.waitFor(() => expect(history.peek(START)).toHaveProperty(["clip.mp4"]), {
      timeout: 10_000,
    });
    await history.close();
    write("b.png", "png");
    write(".media/manifest.jsonl", '{"path":"b.png"}\n');
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await reopened.flush();
    const [outside] = reopened.list();
    expect(outside!.files.map((file) => file.path).sort()).toEqual([
      ".media/manifest.jsonl",
      "b.png",
    ]);
    expect((await reopened.undo(outside!.id, { who: you })).ok).toBe(true);
    expect([has("b.png"), has(".media/manifest.jsonl")]).toEqual([false, false]);
  });

  it("names media in adopting.json until its copy is recorded, so an exit mid-copy resumes it", async () => {
    let release = () => {};
    mediaCopy.held = new Promise<void>((resolve) => (release = resolve));
    const { history, historyRoot } = await project({
      "index.html": "A",
      "clip.mp4": Buffer.alloc(2 * 1024 ** 2, 7),
    });
    const adopting = join(historyRoot, history.projectId, "adopting.json");
    expect(JSON.parse(readFileSync(adopting, "utf-8"))).toEqual(["clip.mp4"]);
    release();
    await vi.waitFor(() => expect(history.peek(START)).toHaveProperty(["clip.mp4"]), {
      timeout: 10_000,
    });
    expect(existsSync(adopting)).toBe(false);
  });

  it("keeps media whose recording failed for the next open, rather than log it as added", async () => {
    const { history, write, historyRoot } = await project(
      { "index.html": "A", "clip.mp4": Buffer.alloc(2 * 1024 ** 2, 7) },
      { budgetBytes: 1, quietMs: 30 },
    );
    // The edit's prune takes the first copy; storing it again then fails.
    mediaCopy.fails = (copy) => copy === 2;
    mediaCopy.stored = () => {
      mediaCopy.stored = null;
      return change(history, you, "Color", () => write("index.html", "B"));
    };
    await vi.waitFor(() => expect(mediaCopy.copies).toHaveLength(2), { timeout: 10_000 });
    await history.flush();
    expect(history.list().flatMap((entry) => entry.files.map((file) => file.path))).not.toContain(
      "clip.mp4",
    );
    const adopting = join(historyRoot, history.projectId, "adopting.json");
    expect(JSON.parse(readFileSync(adopting, "utf-8"))).toEqual(["clip.mp4"]);
  });

  it("never copies the media of a folder that replaced the project", async () => {
    let release = () => {};
    mediaCopy.held = new Promise<void>((resolve) => (release = resolve));
    const media = {
      "a.mp4": Buffer.alloc(2 * 1024 ** 2, 1),
      "b.mp4": Buffer.alloc(2 * 1024 ** 2, 2),
    };
    const { history, write, projectDir } = await project({ "index.html": "A", ...media });
    renameSync(projectDir, `${projectDir}-moved`);
    cleanup.push(() => rmSync(`${projectDir}-moved`, { recursive: true, force: true }));
    mkdirSync(projectDir);
    for (const [path, bytes] of Object.entries(media)) write(path, bytes);
    release();
    await history.close();
    // Only the copy already running when the folder changed may finish.
    expect(mediaCopy.copies).toEqual(["a.mp4"]);
  });

  it("undoes a clip replaced while closed, though the history closed before its copy finished", async () => {
    const clip = Buffer.alloc(2 * 1024 ** 2, 7);
    let release = () => {};
    mediaCopy.held = new Promise<void>((resolve) => (release = resolve));
    const { history, write, projectDir, historyRoot } = await project(
      { "index.html": "A", "clip.mp4": clip },
      { quietMs: 30 },
    );
    const closed = history.close();
    release();
    await closed;
    write("clip.mp4", Buffer.alloc(2 * 1024 ** 2, 9));
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await reopened.flush();
    expect(reopened.list().map((entry) => entry.files.map((file) => file.path))).toEqual([
      ["clip.mp4"],
    ]);
    expect(await reopened.step("back", you)).toMatchObject({ ok: true });
    expect(readFileSync(join(projectDir, "clip.mp4")).equals(clip)).toBe(true);
  });

  it("adopts media whose copy a process exit cut short, rather than log it as added", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "A" });
    await history.close();
    // What an exit mid-copy leaves: the clip on disk, named as still being copied, not in the baseline.
    write("clip.mp4", Buffer.alloc(2 * 1024 ** 2, 7));
    writeFileSync(join(historyRoot, history.projectId, "adopting.json"), '["clip.mp4"]');
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await vi.waitFor(() => expect(reopened.peek(START)).toHaveProperty(["clip.mp4"]), {
      timeout: 10_000,
    });
    await reopened.flush();
    expect(reopened.list()).toEqual([]);
  });

  it("keeps a media copy that a budget prune ran into before history recorded it", async () => {
    const clip = Buffer.alloc(2 * 1024 ** 2, 7);
    let release = () => {};
    mediaCopy.held = new Promise<void>((resolve) => (release = resolve));
    const { history, write } = await project(
      { "index.html": "A", "clip.mp4": clip },
      { budgetBytes: 1, quietMs: 30 },
    );
    // The copy is stored; an edit commits and prunes before history records the copy.
    mediaCopy.stored = () => {
      mediaCopy.stored = null;
      return change(history, you, "Color", () => write("index.html", "B"));
    };
    release();
    await vi.waitFor(() => expect(history.peek(START)).toHaveProperty(["clip.mp4"]), {
      timeout: 10_000,
    });
    const start = history.peek(START)["clip.mp4"]!;
    expect((await history.readBlob(start)).equals(clip)).toBe(true);
  });

  it("a log 0.8.123 wrote without a ledger takes none in, and one made later while closed is a change", async () => {
    const { history, write, projectDir, historyRoot } = await project(
      { "index.html": "A" },
      { quietMs: 30 },
    );
    await history.close();
    asWrittenBy("0.8.123", join(historyRoot, history.projectId, "log.jsonl"));
    await (await open(projectDir, historyRoot, { quietMs: 30 })).close();
    write(".media/manifest.jsonl", "{}\n");
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await reopened.flush();
    expect(reopened.list().map((entry) => entry.files.map((file) => file.path))).toEqual([
      [".media/manifest.jsonl"],
    ]);
  });

  it("an older log keeps a ledger one of its changes made out of the start", async () => {
    const { history, write, has, projectDir, historyRoot } = await project({ "index.html": "A" });
    await change(history, agent, "Cut out the logo", () => {
      write("index.html", "B");
      write(".media/manifest.jsonl", "{}\n");
    });
    await history.close();
    asWrittenBy("0.8.122", join(historyRoot, history.projectId, "log.jsonl"));
    const reopened = await open(projectDir, historyRoot);
    await reopened.restore(START, you);
    expect(has(".media/manifest.jsonl")).toBe(false);
  });

  it("an older log keeps the ledger its start names, so a change made while closed is filed", async () => {
    const { history, write, projectDir, historyRoot } = await project(
      { "index.html": "A", ".media/manifest.jsonl": "{}\n" },
      { quietMs: 30 },
    );
    await history.close();
    asWrittenBy("0.8.122", join(historyRoot, history.projectId, "log.jsonl"));
    write(".media/manifest.jsonl", '{}\n{"id":"logo"}\n');
    const reopened = await open(projectDir, historyRoot, { quietMs: 30 });
    await reopened.flush();
    expect(reopened.list().map((entry) => entry.files.map((file) => file.path))).toEqual([
      [".media/manifest.jsonl"],
    ]);
  });

  it("takes the media ledger back with the film when a change is undone", async () => {
    const { history, write, read } = await project({
      "index.html": "<h1>Hello</h1>",
      ".media/manifest.jsonl": "{}\n",
    });
    const cutout = await change(history, agent, "Cut out the logo", () => {
      write("index.html", "<h1>Hello</h1><img src='logo.png'>");
      write(".media/manifest.jsonl", '{}\n{"id":"logo"}\n');
      write(".media/images/logo.png", "png");
      write(".tools/manifest.jsonl", "{}\n");
    });
    expect(cutout.files.map((file) => file.path)).toEqual([".media/manifest.jsonl", "index.html"]);
    expect((await history.undo(cutout.id, { who: you })).ok).toBe(true);
    expect(read(".media/manifest.jsonl")).toBe("{}\n");
  });

  it("never files a hidden file name as a change, but keeps Studio's two manifests", async () => {
    const { history, write } = await project({ "index.html": "<h1>Hello</h1>" }, { quietMs: 30 });
    const turn = await history.beginWindow(agent, "Agent turn");
    write("index.html", "<h1>Bye</h1>");
    write(".turn-record", "a tool's own record");
    write("sub/.DS_Store", "finder");
    write(".hyperframes/studio-motion.json", "{}");
    const entry = await turn.close();
    expect(entry!.files.map((file) => file.path)).toEqual([
      ".hyperframes/studio-motion.json",
      "index.html",
    ]);
    const records = await history.beginWindow(agent, "Records only");
    write(".spawn-record", "pid");
    expect(await records.close()).toBeNull();
    history.noteChange(".spawn-record");
    await history.flush();
    expect(history.list()).toHaveLength(1);
  });

  it("records a write nobody announced as one outside entry, and undo puts the bytes back as a new entry", async () => {
    const { history, write, read, projectDir } = await project(
      { "index.html": "<h1>Hello</h1>", "assets/logo.png": Buffer.from([1, 2, 3]) },
      { quietMs: 30 },
    );
    write("index.html", "<h1>Bye</h1>");
    write("assets/logo.png", Buffer.from([9, 9]));
    history.noteChange("index.html");
    history.noteChange(join(projectDir, "assets/logo.png"));

    await vi.waitFor(() => expect(history.list()).toHaveLength(1));
    const [outside] = history.list();
    expect(outside).toMatchObject({ who: { kind: "outside" }, label: "Changed outside the app" });
    expect(outside!.files.map((file) => file.path)).toEqual(["assets/logo.png", "index.html"]);

    const undone = await history.undo(outside!.id, { who: you });
    expect(undone).toMatchObject({ ok: true, entry: { label: "Undid: Changed outside the app" } });
    expect(read("index.html")).toBe("<h1>Hello</h1>");
    expect([...readFileSync(join(projectDir, "assets/logo.png"))]).toEqual([1, 2, 3]);
    expect(history.list().find((entry) => entry.id === outside!.id)?.undone).toBe(true);

    expect(await history.step("forward", you)).toMatchObject({
      entry: { label: "Redid: Changed outside the app" },
    });
    expect(read("index.html")).toBe("<h1>Bye</h1>");
    await history.step("back", you);
    expect(read("index.html")).toBe("<h1>Hello</h1>");
    expect(history.list()).toHaveLength(4);
  });

  it("gives a window's writes to its writer, and undoes a create, a delete and Studio's manifest", async () => {
    const { history, write, read, has, projectDir } = await project({
      "index.html": "<h1>Hello</h1>",
      "old.css": "h1 {}",
    });
    expect(await (await history.beginWindow(agent, "nothing")).close()).toBeNull();

    const entry = await change(history, agent, "add Flash Through White", () => {
      write("index.html", "<h1>Flash</h1>");
      write("new.html", "<p>new</p>");
      write(".hyperframes/studio-manual-edits.json", "{}");
      rmSync(join(projectDir, "old.css"));
    });
    expect(entry.who).toEqual(agent);
    expect(entry.files.map((file) => [file.path, !!file.before, !!file.after])).toEqual([
      [".hyperframes/studio-manual-edits.json", false, true],
      ["index.html", true, true],
      ["new.html", false, true],
      ["old.css", true, false],
    ]);

    expect((await history.undo(entry.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("<h1>Hello</h1>");
    expect(read("old.css")).toBe("h1 {}");
    expect(has("new.html")).toBe(false);
    expect(has(".hyperframes/studio-manual-edits.json")).toBe(false);
  });

  it("names a file changed since and the newer change, then takes 'undo just this' when asked", async () => {
    const { history, write, read } = await project({ "index.html": "A", "notes.txt": "n1" });
    const first = await change(history, you, "Title", () => {
      write("index.html", "B");
      write("notes.txt", "n2");
    });
    const newer = await change(history, agent, "Retitle", () => write("index.html", "C"));

    expect(await history.undo(first.id, { who: you })).toEqual({
      ok: false,
      conflict: { files: ["index.html"], newer: [newer.id] },
    });
    expect([read("index.html"), read("notes.txt")]).toEqual(["C", "n2"]);

    expect((await history.undo(first.id, { who: you, mode: "just-this" })).ok).toBe(true);
    expect([read("index.html"), read("notes.txt")]).toEqual(["A", "n1"]);
  });

  it("'go back to before this' reverts the change and everything after it as one entry", async () => {
    const { history, write, read, has } = await project({ "index.html": "A" });
    const first = await change(history, you, "Title", () => write("index.html", "B"));
    await change(history, agent, "Extra", () => {
      write("index.html", "C");
      write("extra.txt", "x");
    });

    const back = await history.undo(first.id, { who: you, mode: "back-to-before" });
    expect(back).toMatchObject({ ok: true, entry: { restoredTo: START } });
    expect(read("index.html")).toBe("A");
    expect(has("extra.txt")).toBe(false);
  });

  it("restores any point, and peek reads a point's bytes without writing", async () => {
    const { history, write, read } = await project({ "index.html": "v1" });
    const second = await change(history, you, "Second", () => write("index.html", "v2"));
    await change(history, you, "Third", () => write("index.html", "v3"));

    const at = (point: string) => history.peek(point)!["index.html"]!;
    expect((await history.readBlob(at(second.id))).toString()).toBe("v2");
    expect((await history.readBlob(at(START))).toString()).toBe("v1");
    expect(read("index.html")).toBe("v3");

    const restored = await history.restore(second.id, you);
    expect(restored).toMatchObject({ label: "Restored: Second", restoredTo: second.id });
    expect(read("index.html")).toBe("v2");
  });

  it("checks out an entry's before and after into a folder, leaving the project and its history alone", async () => {
    const { history, write, read } = await project({ "index.html": "v1", "assets/a.txt": "a" });
    const second = await change(history, you, "Second", () => {
      write("index.html", "v2");
      write("extra/b.txt", "b");
    });
    await change(history, you, "Third", () => write("index.html", "v3"));

    const before = tempDir("hf-history-checkout-");
    const after = tempDir("hf-history-checkout-");
    await history.checkout(second.id, "before", before);
    await history.checkout(second.id, "after", after);
    expect([inside(before, "index.html"), inside(before, "assets/a.txt")]).toEqual(["v1", "a"]);
    expect(existsSync(join(before, "extra/b.txt"))).toBe(false);
    expect([inside(after, "index.html"), inside(after, "extra/b.txt")]).toEqual(["v2", "b"]);
    const beforeThird = join(tempDir("hf-history-checkout-"), "made-by-checkout");
    await history.checkout(history.list()[1]!.id, "before", beforeThird);
    expect([inside(beforeThird, "index.html"), inside(beforeThird, "extra/b.txt")]).toEqual([
      "v2",
      "b",
    ]);

    expect(read("index.html")).toBe("v3");
    expect(history.list()).toHaveLength(2);
    await expect(history.checkout(second.id, "after", after)).rejects.toThrow("empty folder");
    await expect(
      history.checkout("gone", "after", tempDir("hf-history-checkout-")),
    ).rejects.toThrow("no longer kept");
  });

  it("checks out each entry's own change around a drag held when an agent turn starts", async () => {
    const { history, write } = await project({ "index.html": "A" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "C");
    await window.close();
    write("index.html", "D");
    await drag("C");
    await history.flush();

    const sides = async (id: string) => {
      const pair: string[] = [];
      for (const side of ["before", "after"] as const) {
        const dir = tempDir("hf-history-checkout-");
        await history.checkout(id, side, dir);
        pair.push(inside(dir, "index.html"));
      }
      return pair.join(">");
    };
    const changes = [];
    for (const entry of history.list()) changes.push(`${entry.label}: ${await sides(entry.id)}`);
    expect(changes).toEqual(["Dragged Title: A>B", "Agent turn: B>C", "Dragged Title: C>D"]);
  });

  it("logs the outside change that turned a file into a folder before the agent turn that followed", async () => {
    const { history, projectDir, write } = await project({ a: "file", "r.txt": "R0" });
    rmSync(join(projectDir, "a"));
    mkdirSync(join(projectDir, "a"));
    writeFileSync(join(projectDir, "a", "b.txt"), "b0");
    const window = await history.beginWindow(agent, "Agent turn");
    writeFileSync(join(projectDir, "a", "b.txt"), "b1");
    const turn = await window.close();
    write("r.txt", "R1");
    await history.flush();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Changed outside the app",
      "Agent turn",
      "Changed outside the app",
    ]);

    for (const [side, content] of [
      ["before", "b0"],
      ["after", "b1"],
    ] as const) {
      const dir = tempDir("hf-history-checkout-");
      await history.checkout(turn!.id, side, dir);
      expect([inside(dir, "a/b.txt"), inside(dir, "r.txt")]).toEqual([content, "R0"]);
    }
  });

  it.each([
    ["a file into a folder", { a: "file" }, "a/b.html", ["a", "a/b.html"]],
    ["a folder into a file", { "a/b.html": "b" }, "a", ["a", "a/b.html"]],
  ])(
    "checks out a turn that turned %s and idled before the next scan",
    async (_, files, made, paths) => {
      const { history, projectDir } = await project(files);
      await history.beginWindow(agent, "Agent turn", { idleMs: 60_000 });
      rmSync(join(projectDir, "a"), { recursive: true });
      mkdirSync(dirname(join(projectDir, made)), { recursive: true });
      writeFileSync(join(projectDir, made), "made");
      vi.useFakeTimers({ toFake: ["Date"] });
      try {
        vi.setSystemTime(Date.now() + 120_000);
        await history.flush();
      } finally {
        vi.useRealTimers();
      }

      const [first] = history.list();
      expect([first!.who.kind, first!.files.map((file) => file.path).sort()]).toEqual([
        "agent",
        paths,
      ]);
      const dir = tempDir("hf-history-checkout-");
      await history.checkout(first!.id, "after", dir);
      expect(inside(dir, made)).toBe("made");
    },
  );

  it("undoes and redoes a turn that turned a file into a folder", async () => {
    const { history, projectDir, read } = await project({ a: "file" });
    const turn = await change(history, agent, "Agent turn", () => {
      rmSync(join(projectDir, "a"));
      mkdirSync(join(projectDir, "a", "c"), { recursive: true });
      writeFileSync(join(projectDir, "a", "c", "b.html"), "b");
    });

    const undone = await history.undo(turn.id, { who: you });
    expect(undone.ok && read("a")).toBe("file");
    const redone = await history.undo(undone.ok ? undone.entry!.id : "", { who: you });
    expect(redone.ok && read("a/c/b.html")).toBe("b");
  });

  it("refuses an undo that would have to delete a file added since, and leaves the files alone", async () => {
    const { history, projectDir, read } = await project({ a: "file" });
    const turn = await change(history, agent, "Agent turn", () => {
      rmSync(join(projectDir, "a"));
      mkdirSync(join(projectDir, "a"));
      writeFileSync(join(projectDir, "a", "b.html"), "b");
    });
    mkdirSync(join(projectDir, "a", "sub"));
    writeFileSync(join(projectDir, "a", "sub", "new.html"), "new");
    await history.flush();
    const entries = history.list().length;

    await expect(history.undo(turn.id, { who: you })).rejects.toThrow(
      "a/sub/new.html is in the way",
    );
    expect([read("a/b.html"), read("a/sub/new.html"), history.list().length]).toEqual([
      "b",
      "new",
      entries,
    ]);
  });

  // Windows needs a privilege to create symlinks.
  it.skipIf(process.platform === "win32")(
    "refuses an undo that would have to replace a link added since, and leaves its folder alone",
    async () => {
      const { history, projectDir, read } = await project({ a: "file" });
      const turn = await change(history, agent, "Agent turn", () => {
        rmSync(join(projectDir, "a"));
        writeFileSync(join(projectDir, "c.html"), "c");
      });
      const outside = tempDir("hf-history-linked-");
      mkdirSync(join(outside, "empty"));
      symlinkSync(outside, join(projectDir, "a"), "dir");

      await expect(history.undo(turn.id, { who: you })).rejects.toThrow("a is in the way");
      expect([read("c.html"), existsSync(join(outside, "empty"))]).toEqual(["c", true]);
    },
  );

  it.skipIf(process.platform === "win32")(
    "refuses an undo that would write through a link standing where a folder was",
    async () => {
      const { history, projectDir } = await project({ "a/b.html": "b" });
      const turn = await change(history, agent, "Agent turn", () => {
        rmSync(join(projectDir, "a"), { recursive: true });
        writeFileSync(join(projectDir, "a"), "file");
      });
      rmSync(join(projectDir, "a"));
      const outside = tempDir("hf-history-linked-");
      symlinkSync(outside, join(projectDir, "a"), "dir");
      await history.flush();

      await expect(history.undo(turn.id, { who: you, mode: "just-this" })).rejects.toThrow(
        "a is in the way",
      );
      expect(existsSync(join(outside, "b.html"))).toBe(false);
    },
  );

  it.skipIf(!caseInsensitive())(
    "undoes and redoes a turn that turned file A into folder a/, and undoes the reverse",
    async () => {
      const { history, projectDir, read } = await project({ A: "file" });
      const turn = await change(history, agent, "Agent turn", () => {
        rmSync(join(projectDir, "A"));
        mkdirSync(join(projectDir, "a"));
        writeFileSync(join(projectDir, "a", "b.html"), "b");
      });

      const undone = await history.undo(turn.id, { who: you });
      expect(undone.ok && read("A")).toBe("file");
      const redone = await history.undo(undone.ok ? undone.entry!.id : "", { who: you });
      expect(redone.ok && read("a/b.html")).toBe("b");
      const reverse = await change(history, agent, "Reverse turn", () => {
        rmSync(join(projectDir, "a"), { recursive: true });
        writeFileSync(join(projectDir, "A"), "file");
      });
      const reversed = await history.undo(reverse.id, { who: you });
      expect(reversed.ok && read("a/b.html")).toBe("b");
    },
  );

  it.each([["a"], ...(caseInsensitive() ? [["A"]] : [])])(
    "logs a folder a/ moved over an agent's file %s after its turn idled out as the outside's, however old its files",
    async (file) => {
      const { history, projectDir } = await project({ [file]: "file" });
      const staged = tempDir("hf-history-folder-");
      vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
      try {
        const window = await history.beginWindow(agent, "Agent turn", { idleMs: 50 });
        writeFileSync(join(staged, "b.html"), "b");
        for (const until = Date.now() + 150; Date.now() < until; );
        rmSync(join(projectDir, file));
        renameSync(staged, join(projectDir, "a"));
        await window.close();
        await history.flush();
      } finally {
        vi.useRealTimers();
      }

      const entries = history.list();
      expect(
        entries.map((entry) => [entry.who.kind, entry.files.map((f) => f.path).sort()]),
      ).toEqual([["outside", [file, "a/b.html"]]]);
      const dir = tempDir("hf-history-checkout-");
      await history.checkout(entries[0]!.id, "after", dir);
      expect(inside(dir, "a/b.html")).toBe("b");
    },
  );

  it("refuses the working folder as a checkout written as an empty path, and writes nothing there", async () => {
    const name = `hf-checkout-probe-${process.pid}.html`;
    cleanup.push(() => rmSync(join(process.cwd(), name), { force: true }));
    const { history, write } = await project({ [name]: "v1" });
    const entry = await change(history, you, "Second", () => write(name, "v2"));

    await expect(history.checkout(entry.id, "before", "")).rejects.toThrow("empty folder only");
    expect(existsSync(join(process.cwd(), name))).toBe(false);
  });

  // Windows needs a privilege to create symlinks.
  it.skipIf(process.platform === "win32")(
    "refuses a nonempty checkout folder reached through a link and `..`",
    async () => {
      const { history, write } = await project({ "index.html": "v1" });
      const entry = await change(history, you, "Second", () => write("index.html", "v2"));
      const out = tempDir("hf-history-out-");
      const other = tempDir("hf-history-other-");
      mkdirSync(join(other, "sub"));
      symlinkSync(join(other, "sub"), join(out, "link"), "dir");
      mkdirSync(join(out, "co"));
      writeFileSync(join(out, "co", "index.html"), "kept");

      await expect(history.checkout(entry.id, "before", `${out}/link/../co`)).rejects.toThrow(
        "empty folder only",
      );
      expect(inside(join(out, "co"), "index.html")).toBe("kept");
    },
  );

  it("refuses a checkout folder inside the project, however it is reached", async () => {
    const { history, write, projectDir, has } = await project({ "index.html": "v1" });
    const entry = await change(history, you, "Second", () => write("index.html", "v2"));
    const alias = join(tempDir("hf-history-alias-"), "alias");
    symlinkSync(projectDir, alias);

    for (const dir of [join(projectDir, "archive"), join(alias, "archive"), projectDir])
      await expect(history.checkout(entry.id, "after", dir)).rejects.toThrow("outside the project");
    expect(has("archive")).toBe(false);
    await history.flush();
    expect(history.list()).toHaveLength(1);
  });

  it.skipIf(!caseInsensitive())(
    "refuses a checkout folder inside the project spelled in other letter case",
    async () => {
      const { history, write, projectDir, has } = await project({ "index.html": "v1" });
      const entry = await change(history, you, "Second", () => write("index.html", "v2"));
      const recased = join(dirname(projectDir), basename(projectDir).toUpperCase(), "archive");

      await expect(history.checkout(entry.id, "after", recased)).rejects.toThrow(
        "outside the project",
      );
      expect(has("archive")).toBe(false);
    },
  );

  it("checks out beside the project into a folder whose name starts with the project's", async () => {
    const { history, write, projectDir } = await project({ "index.html": "v1" });
    const entry = await change(history, you, "Second", () => write("index.html", "v2"));
    const sibling = `${projectDir}-copy`;
    cleanup.push(() => rmSync(sibling, { recursive: true, force: true }));

    await history.checkout(entry.id, "after", sibling);
    expect(inside(sibling, "index.html")).toBe("v2");
  });

  it("refuses a checkout once the project folder is gone", async () => {
    const { history, write, projectDir } = await project({ "index.html": "v1" });
    const entry = await change(history, you, "Second", () => write("index.html", "v2"));
    rmSync(projectDir, { recursive: true, force: true });

    await expect(history.checkout(entry.id, "after", join(projectDir, "archive"))).rejects.toThrow(
      "project folder is gone",
    );
    expect(existsSync(projectDir)).toBe(false);
  });

  it("leaves the folder empty when a checkout fails partway, so it can be retried", async () => {
    const { history, write, historyRoot } = await project({ "a/a.txt": "a", "z.txt": "z" });
    const entry = await change(history, you, "Edit", () => write("z.txt", "z2"));
    const lost = history.peek(entry.id)!["z.txt"]!;
    const blob = readdirSync(historyRoot, { recursive: true }).find((path) =>
      String(path).endsWith(lost),
    );
    rmSync(join(historyRoot, String(blob)));

    const dir = tempDir("hf-history-checkout-");
    await expect(history.checkout(entry.id, "after", dir)).rejects.toThrow();
    expect(readdirSync(dir)).toEqual([]);
  });

  it("refuses every call after close, even through a window begun before it", async () => {
    const { history, write } = await project({ "index.html": "v1" });
    const entry = await change(history, you, "Second", () => write("index.html", "v2"));
    const window = await history.beginWindow(agent, "Turn");
    await history.close();

    await expect(window.close()).rejects.toThrow(HistoryClosedError);
    await expect(history.claim(you, "Edit", ["index.html"])).rejects.toThrow(HistoryClosedError);
    await expect(history.undo(entry.id, { who: you })).rejects.toThrow(HistoryClosedError);
    await expect(history.restore(START, you)).rejects.toThrow(HistoryClosedError);
    await expect(history.readBlob("a")).rejects.toThrow(HistoryClosedError);
    expect(() => history.list()).toThrow(HistoryClosedError);
  });

  it("releases ownership only after every close has settled", async () => {
    const { history } = await project({ "index.html": "v1" });
    let firstDone = false;
    const first = history.close().then(() => (firstDone = true));
    await history.close();
    expect(firstDone).toBe(true);
    await first;
  });

  it("refuses once a new project takes the folder's path, leaving both projects' files alone", async () => {
    const { history, write, read, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Second", () => write("index.html", "v2"));
    const window = await history.beginWindow(agent, "Turn");
    write("index.html", "v3");
    history.noteChange("index.html");
    await pause(100);
    const moved = `${projectDir}-moved`;
    renameSync(projectDir, moved);
    cleanup.push(() => rmSync(moved, { recursive: true, force: true }));
    mkdirSync(projectDir);
    writeFileSync(join(projectDir, "index.html"), "new project");

    expect(history.replacedAtPath()).toBe(true);
    await expect(history.restore(START, you)).rejects.toThrow(HistoryClosedError);
    expect(() => history.list()).toThrow(HistoryClosedError);
    // What the turn wrote before the swap is still its entry; nothing of the new project is.
    expect((await window.close())?.files.map((file) => file.path)).toEqual(["index.html"]);
    await history.close();
    expect([read("index.html"), readFileSync(join(moved, "index.html"), "utf-8")]).toEqual([
      "new project",
      "v3",
    ]);
    const again = await open(moved, historyRoot);
    expect(again.list().map((entry) => entry.label)).toEqual(["Second", "Turn"]);
  });

  it("refuses to write into a folder moved away, so the old path is not recreated", async () => {
    const { history, write, projectDir } = await project({ "index.html": "v1" });
    await change(history, you, "Second", () => write("index.html", "v2"));
    renameSync(projectDir, `${projectDir}-moved`);
    cleanup.push(() => rmSync(`${projectDir}-moved`, { recursive: true, force: true }));

    await expect(history.restore(START, you)).rejects.toThrow("The project folder is gone");
    expect(existsSync(projectDir)).toBe(false);
    expect(history.replacedAtPath()).toBe(false);
  });

  it.each([
    ["a new project took the folder's path", "new"],
    ["a copy carrying its id took the folder's path", "copy"],
    ["the folder moved away", "none"],
  ])(
    "refuses to open, so a server can retry, once %s while it waited for the history",
    async (_, replacement) => {
      const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
      const waiting = openProjectHistory({ projectDir, historyRoot });
      waiting.then((late) => cleanup.push(() => late.close())).catch(() => {});
      await pause(50);
      renameSync(projectDir, `${projectDir}-moved`);
      cleanup.push(() => rmSync(`${projectDir}-moved`, { recursive: true, force: true }));
      if (replacement === "new") mkdirSync(projectDir);
      if (replacement === "copy") cpSync(`${projectDir}-moved`, projectDir, { recursive: true });
      await history.close();

      await expect(waiting).rejects.toThrow(HistoryClosedError);
    },
  );

  it("refuses, so a server can retry, to open a folder that is not there", async () => {
    const projectDir = join(tempDir("hf-history-gone-"), "project");
    const historyRoot = tempDir("hf-history-root-");
    await expect(openProjectHistory({ projectDir, historyRoot })).rejects.toThrow(
      HistoryClosedError,
    );
  });

  it("keeps the history of a record 0.8.78 wrote for this folder, and records the folder's identity", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Old change", () => write("index.html", "v2"));
    await history.close();
    const record = join(historyRoot, history.projectId, "project.json");
    writeFileSync(record, JSON.stringify({ dir: projectDir }));

    const again = await open(projectDir, historyRoot);
    expect(again.projectId).toBe(history.projectId);
    expect(again.list().map((entry) => entry.label)).toEqual(["Old change"]);
    expect(JSON.parse(readFileSync(record, "utf-8"))).toMatchObject({
      dir: projectDir,
      ino: expect.any(Number),
    });
  });

  describe("a history 0.8.78 wrote", () => {
    const fixture = join(import.meta.dirname, "__fixtures__", "history-0.8.78");
    const fixtureId = readFileSync(join(fixture, "history-id"), "utf-8").trim();

    /** The fixture's project and history root, laid out as 0.8.78 left them. */
    function legacyProject(recordedDir: (projectDir: string) => string) {
      const projectDir = tempDir("hf-history-legacy-");
      const historyRoot = tempDir("hf-history-legacy-root-");
      cpSync(join(fixture, "root"), historyRoot, { recursive: true });
      mkdirSync(join(projectDir, ".hyperframes"));
      cpSync(join(fixture, "history-id"), join(projectDir, ".hyperframes", "history-id"));
      cpSync(join(fixture, "index.html"), join(projectDir, "index.html"));
      const record = join(historyRoot, fixtureId, "project.json");
      writeFileSync(record, JSON.stringify({ dir: recordedDir(projectDir) }));
      return { projectDir, historyRoot };
    }

    it.each([
      ["at the path it was recorded for", (projectDir: string) => projectDir],
      ["moved since", (projectDir: string) => `${projectDir}-before-the-move`],
    ])("opens %s with every entry, and can undo them", async (_, recordedDir) => {
      const { projectDir, historyRoot } = legacyProject(recordedDir);

      const history = await open(projectDir, historyRoot);
      expect(history.projectId).toBe(fixtureId);
      expect(inside(projectDir, ".hyperframes/history-id").trim()).toBe(fixtureId);
      const entries = history.list();
      expect(entries.map((entry) => [entry.who.name, entry.label])).toEqual([
        ["You", "Moved Title"],
        ["Agent", "Agent turn"],
      ]);
      expect(await history.undo(entries[1]!.id, { who: you })).toMatchObject({ ok: true });
      expect(inside(projectDir, "index.html")).toBe("<p>v2</p>\n");
    });

    it.each([
      ["empty", ""],
      ["null", "null"],
    ])("keeps the id when the record is %s, as 0.8.78 did", async (_, record) => {
      const { projectDir, historyRoot } = legacyProject((projectDir) => projectDir);
      writeFileSync(join(historyRoot, fixtureId, "project.json"), record);

      const history = await open(projectDir, historyRoot);
      expect([history.projectId, history.list().length]).toEqual([fixtureId, 2]);
    });

    it("keeps the history when the record names the folder by another path to it", async () => {
      const { projectDir, historyRoot } = legacyProject((projectDir) => `${projectDir}-link`);
      symlinkSync(projectDir, `${projectDir}-link`, "junction");
      cleanup.push(() => rmSync(`${projectDir}-link`, { force: true }));

      const history = await open(projectDir, historyRoot);
      expect([history.projectId, history.list().length]).toEqual([fixtureId, 2]);
    });

    it("gives a copy its own history while the recorded folder still carries the id", async () => {
      const original = legacyProject((projectDir) => projectDir);
      const copy = tempDir("hf-history-legacy-copy-");
      cpSync(original.projectDir, copy, { recursive: true });

      const copied = await open(copy, original.historyRoot);
      expect([copied.projectId === fixtureId, copied.list()]).toEqual([false, []]);
      expect((await open(original.projectDir, original.historyRoot)).list()).toHaveLength(2);
    });
  });

  it("refuses to open, and leaves the file alone, when the history id cannot be read", async () => {
    const projectDir = tempDir("hf-history-bad-id-");
    writeFileSync(join(projectDir, "index.html"), "v1");
    mkdirSync(join(projectDir, ".hyperframes"));
    writeFileSync(join(projectDir, ".hyperframes", "history-id"), "not-an-id\n");

    await expect(open(projectDir, tempDir("hf-history-root-"))).rejects.toThrow(HistoryIdError);
    expect(inside(projectDir, ".hyperframes/history-id")).toBe("not-an-id\n");
  });

  it("leaves the id alone for a history root that has no history under it, so the open one keeps recording", async () => {
    const { history, write, projectDir } = await project({ "index.html": "v1" });
    const other = await open(projectDir, tempDir("hf-history-other-root-"));

    await change(history, you, "Edit", () => write("index.html", "v2"));
    expect([other.projectId, history.list().length]).toEqual([history.projectId, 1]);
  });

  it("gives a folder on a reused inode, created at another time, a history of its own", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Old change", () => write("index.html", "v2"));
    await history.close();
    const record = join(historyRoot, history.projectId, "project.json");
    const was = JSON.parse(readFileSync(record, "utf-8"));
    writeFileSync(record, JSON.stringify({ ...was, born: was.born - 1000 }));

    const again = await open(projectDir, historyRoot);
    expect([again.projectId === history.projectId, again.list()]).toEqual([false, []]);
  });

  it("keeps the history when the disk's device number changed, as a remounted drive's does", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Old change", () => write("index.html", "v2"));
    await history.close();
    const record = join(historyRoot, history.projectId, "project.json");
    writeFileSync(
      record,
      JSON.stringify({ ...JSON.parse(readFileSync(record, "utf-8")), dev: -1 }),
    );

    const again = await open(projectDir, historyRoot);
    expect(again.list().map((entry) => entry.label)).toEqual(["Old change"]);
  });

  it("counts a folder whose history id is gone as another project, as a recreated folder on a reused inode is", async () => {
    const { history, write, read, projectDir } = await project({ "index.html": "v1" });
    await change(history, you, "Second", () => write("index.html", "v2"));
    rmSync(join(projectDir, ".hyperframes"), { recursive: true });
    write("index.html", "new project");

    expect(history.replacedAtPath()).toBe(true);
    await expect(history.restore(START, you)).rejects.toThrow(HistoryClosedError);
    expect(read("index.html")).toBe("new project");
  });

  it.each([["the copy"], ["the moved original"]])(
    "gives a copy put where the original was its own history, and the moved original keeps its own, %s opened first",
    async (first) => {
      const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
      await change(history, you, "Old change", () => write("index.html", "v2"));
      await history.close();
      const moved = `${projectDir}-moved`;
      cpSync(projectDir, `${projectDir}-copy`, { recursive: true });
      renameSync(projectDir, moved);
      renameSync(`${projectDir}-copy`, projectDir);
      cleanup.push(() => rmSync(moved, { recursive: true, force: true }));

      const labels = async (dir: string) => {
        const opened = await open(dir, historyRoot);
        const list = opened.list().map((entry) => entry.label);
        await opened.close();
        return list;
      };
      const order = first === "the copy" ? [projectDir, moved] : [moved, projectDir];
      const [a, b] = [await labels(order[0]!), await labels(order[1]!)];
      const [copy, original] = first === "the copy" ? [a, b] : [b, a];
      expect({ copy, original }).toEqual({ copy: [], original: ["Old change"] });
    },
  );

  it("keeps the history across a move and a reopen, and a copy of the folder starts its own", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    write("index.html", "v2");
    await history.flush();
    const moved = `${projectDir}-moved`;
    renameSync(projectDir, moved);
    cleanup.push(() => rmSync(moved, { recursive: true, force: true }));
    await history.flush();
    expect(history.list(), "a moved folder is not every file deleted").toHaveLength(1);
    await history.close();
    writeFileSync(join(moved, "index.html"), "v3");

    const reopened = await open(moved, historyRoot);
    expect(reopened.projectId).toBe(history.projectId);
    expect(reopened.list()).toHaveLength(2);
    await undoNewest(reopened);
    expect(readFileSync(join(moved, "index.html"), "utf-8")).toBe("v2");

    const copy = tempDir("hf-history-copy-");
    cpSync(moved, copy, { recursive: true });
    const copied = await open(copy, historyRoot);
    expect(copied.projectId).not.toBe(history.projectId);
    expect(copied.list()).toEqual([]);
  });

  it("lets one process at a time hold a project's history, so a second opener cannot fork its log", async () => {
    const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await expect(openProjectHistory({ projectDir, historyRoot, ownerWaitMs: 0 })).rejects.toThrow(
      `pid ${process.pid}`,
    );
    const waiting = open(projectDir, historyRoot, { ownerWaitMs: 5000 });
    await history.close();
    expect((await waiting).projectId).toBe(history.projectId);
  });

  it("reads a history another process owns without its lock, past a half-appended last line", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    const second = await change(history, you, "Second", () => write("index.html", "v2"));
    const home = join(historyRoot, history.projectId);
    appendFileSync(join(home, "log.jsonl"), '{"type":"entry","entry":{"id":"torn"');
    const files = () =>
      readdirSync(home).map((name) =>
        statSync(join(home, name)).isFile() ? [name, inside(home, name)] : [name],
      );
    const before = files();

    const view = readProjectHistory({ projectDir, historyRoot });
    expect(view.list()).toEqual(history.list());
    expect(view.list().map((entry) => entry.label)).toEqual(["Second"]);
    expect(view.peek(START)).toEqual(history.peek(START));
    expect((await view.readBlob(view.peek(second.id)!["index.html"]!)).toString()).toBe("v2");
    expect(files()).toEqual(before);
  });

  it("reads a copied folder as having no history, and leaves hidden paths out as the owner does", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Second", () => write("index.html", "v2"));
    const copy = tempDir("hf-history-copy-");
    cpSync(projectDir, copy, { recursive: true });
    expect(readProjectHistory({ projectDir: copy, historyRoot }).list()).toEqual([]);

    const [entry] = history.list();
    const hidden = { path: ".hidden/x", before: null, after: entry!.files[0]!.after };
    const older = { ...entry!, id: "older", files: [...entry!.files, hidden] };
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    appendFileSync(logFile, `${JSON.stringify({ type: "entry", entry: older })}\n`);
    const paths = readProjectHistory({ projectDir, historyRoot })
      .list()
      .map((item) => item.files.map((file) => file.path));
    expect(paths).toEqual([["index.html"], ["index.html"]]);
  });

  it("files what changed while closed to a window begun on an earlier open, under its id", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await history.close();
    write("index.html", "v2");
    const closedWindow = {
      id: "turn-1",
      who: agent,
      label: "Bigger title",
      startedAt: 1,
      lastWriteAt: Date.now(),
      idleMs: 60_000,
    };

    const reopened = await open(projectDir, historyRoot, { closedWindow });
    expect(reopened.list()).toMatchObject([{ id: "turn-1", who: agent, label: "Bigger title" }]);
    await reopened.close();

    write("index.html", "v3");
    const again = await open(projectDir, historyRoot, { closedWindow });
    expect(
      again.list().map((entry) => entry.who),
      "an id already kept is not reused",
    ).toEqual([agent, { kind: "outside", name: "Outside" }]);
  });

  it("files to a closed window only the writes before its idle limit ran out, counting from each write", async () => {
    const { history, write, projectDir, historyRoot } = await project({
      "a.html": "a1",
      "b.html": "b1",
      "c.html": "c1",
    });
    await history.close();
    // A file's change time is its ctime, which only the clock sets: the writes are spaced in real time.
    const lastWriteAt = Date.now();
    await pause(300);
    write("a.html", "2");
    await pause(300);
    write("b.html", "2"); // 600 ms after the window's last write, but 300 ms after a.html: still the window's
    await pause(700);
    write("c.html", "2"); // 700 ms without a write: the window had ended
    const closedWindow = { id: "turn-1", who: agent, label: "Turn", startedAt: 1, lastWriteAt };

    const reopened = await open(projectDir, historyRoot, {
      closedWindow: { ...closedWindow, idleMs: 400 },
    });
    const [turn, outside] = reopened.list();
    expect([turn, outside].map((entry) => entry?.files.map((file) => file.path))).toEqual([
      ["a.html", "b.html"],
      ["c.html"],
    ]);
    expect(outside?.who.kind).toBe("outside");
    const onDisk = readFileSync(join(historyRoot, reopened.projectId, "log.jsonl"), "utf-8");
    expect(Object.keys(JSON.parse(onDisk.trim().split("\n")[1]!).entry).sort()).toEqual([
      "endedAt",
      "files",
      "id",
      "label",
      "startedAt",
      "who",
    ]);
  });

  it("times each write by its file: oldest first, a copy that keeps an old mtime as now, a removal as now", async () => {
    const { history, write, projectDir, historyRoot } = await project({
      "a.html": "a1",
      "b.html": "b1",
      "c.html": "c1",
    });
    await history.close();
    const writeAt = (path: string, text: string, at: number) => {
      write(path, text);
      utimesSync(join(projectDir, path), at / 1000, at / 1000);
    };
    const turn = (id: string, lastWriteAt: number) => ({
      closedWindow: { id, who: agent, label: "Turn", startedAt: 1, lastWriteAt, idleMs: 400 },
    });

    // b.html comes first in time though not by name: taken in order, both are the window's.
    const first = Date.now();
    await pause(300);
    write("b.html", "b2");
    await pause(300);
    write("a.html", "a2"); // past the limit from the window's last write, so it counts only after b.html
    const lastWrite = statSync(join(projectDir, "a.html")).ctimeMs;
    const reopened = await open(projectDir, historyRoot, turn("turn-1", first));
    const [kept] = reopened.list();
    expect(kept?.files.map((file) => file.path)).toEqual(["a.html", "b.html"]);
    expect(Math.abs(kept!.endedAt - lastWrite), "ends at its last write").toBeLessThan(2);
    await reopened.close();

    // Long after the window's last write: an old mtime does not hide a write made now, nor does a removal.
    const stale = Date.now() - 5000;
    writeAt("a.html", "a3", stale + 100);
    rmSync(join(projectDir, "c.html"));
    const again = await open(projectDir, historyRoot, turn("turn-2", stale));
    expect(again.list().at(-1)).toMatchObject({
      who: { kind: "outside" },
      files: [{ path: "a.html" }, { path: "c.html" }],
    });
  });

  it("logs an agent window past its idle limit before a later Studio edit that claims its file", async () => {
    const { history, write } = await project({ "index.html": "A" });
    // The idle timer stays asleep (a laptop lid closed) while real time passes the limit.
    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
    try {
      const window = await history.beginWindow(agent, "Retitle", { idleMs: 50 });
      write("index.html", "A2");
      await history.claim(you, "Nothing", []); // a claim scans first: the agent's write is seen
      for (const until = Date.now() + 150; Date.now() < until; );
      write("index.html", "A3");
      await history.claim(you, "Dragged Title", ["index.html"], {
        overwrote: { "index.html": fileContentVersion("A2") },
      });
      await window.close();
    } finally {
      vi.useRealTimers();
    }

    expect(history.list().map((entry) => entry.label)).toEqual(["Retitle", "Dragged Title"]);
  });

  it("counts a file time ahead of the scan as the scan's time, so it does not end an open turn", async () => {
    const { projectDir, history, write } = await project({ "a.js": "1", "b.js": "1" });
    const window = await history.beginWindow(agent, "Build", { idleMs: 2000 });
    write("a.js", "2");
    const ahead = Date.now() + 60_000;
    utimesSync(join(projectDir, "a.js"), ahead / 1000, ahead / 1000);
    await history.claim(you, "Nothing", []);
    write("b.js", "2");

    expect((await window.close())?.files.map((file) => file.path)).toEqual(["a.js", "b.js"]);
  });

  it("ends every entry at or after the one logged before it, though a window ends at its last write", async () => {
    const { history, write } = await project({ "index.html": "A", "notes.html": "N" });
    const window = await history.beginWindow(agent, "Retitle");
    write("index.html", "A2");
    write("notes.html", "N2");
    await new Promise((settle) => setTimeout(settle, 20));
    await history.claim(you, "Edited notes", ["notes.html"]);
    await window.close();

    const ends = history.list().map((entry) => entry.endedAt);
    expect(ends).toEqual([...ends].sort((a, b) => a - b));
  });

  it("takes over the lock of an owner that died without closing", async () => {
    const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await history.close();
    const dead = spawnSync(process.execPath, ["-e", "process.stdout.write(String(process.pid))"]);
    writeFileSync(join(historyRoot, history.projectId, "owner.pid"), dead.stdout);
    expect((await open(projectDir, historyRoot, { ownerWaitMs: 0 })).projectId).toBe(
      history.projectId,
    );
  });

  it("never removes a lock another process holds: not on close, not while another evicts a dead owner", async () => {
    const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
    const lock = join(historyRoot, history.projectId, "owner.pid");
    const other = String(process.ppid); // a live process that is not this one
    writeFileSync(lock, other);
    await history.close();
    expect(readFileSync(lock, "utf-8"), "a close leaves a later owner's lock").toBe(other);

    const dead = spawnSync(process.execPath, ["-e", "process.stdout.write(String(process.pid))"]);
    writeFileSync(lock, dead.stdout);
    writeFileSync(`${lock}.evict`, other);
    await expect(
      openProjectHistory({ projectDir, historyRoot, ownerWaitMs: 200 }),
      "only the evictor that holds the evict lock removes a dead owner",
    ).rejects.toThrow(HistoryBusyError);

    writeFileSync(`${lock}.evict`, dead.stdout);
    expect((await open(projectDir, historyRoot, { ownerWaitMs: 200 })).projectId).toBe(
      history.projectId,
    );
  });

  it("fails an open whose lock cannot be read, instead of retrying it forever", async () => {
    const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await history.close();
    mkdirSync(join(historyRoot, history.projectId, "owner.pid"));
    await expect(openProjectHistory({ projectDir, historyRoot, ownerWaitMs: 0 })).rejects.toThrow(
      /EISDIR/,
    );
  });

  it("takes over a lock file that holds no pid", async () => {
    const { history, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await history.close();
    writeFileSync(join(historyRoot, history.projectId, "owner.pid"), "");
    expect((await open(projectDir, historyRoot, { ownerWaitMs: 0 })).projectId).toBe(
      history.projectId,
    );
  });

  it("rewrites a history folder removed while open, so a reopen still has the change", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    const earlier = await change(history, you, "Second", () => write("index.html", "v2"));
    rmSync(historyRoot, { recursive: true, force: true });
    const entry = await change(history, you, "Third", () => write("index.html", "v3"));
    await history.close();

    const reopened = await open(projectDir, historyRoot);
    expect(reopened.list().map((kept) => kept.id)).toEqual([earlier.id, entry.id]);
    const hash = reopened.peek(entry.id)!["index.html"]!;
    expect((await reopened.readBlob(hash)).toString()).toBe("v3");
  });

  it("reports a damaged log line and keeps every line around it", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "v1" });
    await change(history, you, "Second", () => write("index.html", "v2"));
    await change(history, you, "Third", () => write("index.html", "v3"));
    await history.close();
    const logFile = join(historyRoot, history.projectId, "log.jsonl");
    const lines = readFileSync(logFile, "utf-8").split("\n");
    writeFileSync(logFile, [lines[0], "{not json", ...lines.slice(1)].join("\n"));

    const onError = vi.fn();
    const reopened = await open(projectDir, historyRoot, { onError });
    expect(onError).toHaveBeenCalledOnce();
    expect(String(onError.mock.calls[0]![0])).toMatch(/line 2 /);
    expect(reopened.list().map((kept) => kept.label)).toEqual(["Second", "Third"]);
  });

  it("refuses a history-id that is anything else, so a project cannot pick where history is written", async () => {
    const projectDir = tempDir("hf-history-project-");
    const historyRoot = tempDir("hf-history-root-");
    const victim = tempDir("hf-history-victim-");
    writeFileSync(join(projectDir, "index.html"), "v1");
    writeFileSync(join(victim, "project.json"), '{"precious":true}');
    mkdirSync(join(projectDir, ".hyperframes"));
    writeFileSync(join(projectDir, ".hyperframes", "history-id"), relative(historyRoot, victim));

    await expect(open(projectDir, historyRoot)).rejects.toThrow(/history-id/);
    expect(readdirSync(victim)).toEqual(["project.json"]);
    expect(readFileSync(join(victim, "project.json"), "utf-8")).toBe('{"precious":true}');
    const idFile = join(projectDir, ".hyperframes", "history-id");
    expect(readFileSync(idFile, "utf-8")).toBe(relative(historyRoot, victim));
  });

  it("commits a window that is never closed when the history flushes, so an undo still reaches its writes", async () => {
    const { history, write, read } = await project({ "index.html": "a" });
    await history.beginWindow(agent, "never closed");
    write("index.html", "b, an outside edit");
    await history.flush();
    expect(history.list()).toHaveLength(1);
    expect(await undoNewest(history)).toMatchObject({
      ok: true,
      entry: { label: "Undid: never closed" },
    });
    expect(read("index.html")).toBe("a");
  });

  it("ends a window idle past its lifetime, so later writes are the outside's", async () => {
    const { history, write } = await project({ "index.html": "a" });
    const window = await history.beginWindow(agent, "Short", { idleMs: 40 });
    write("index.html", "b");
    await vi.waitFor(() => expect(history.list()).toHaveLength(1));
    write("index.html", "c");
    await history.flush();
    expect(history.list().map((entry) => [entry.label, entry.who.kind])).toEqual([
      ["Short", "agent"],
      ["Changed outside the app", "outside"],
    ]);
    expect((await window.close())?.id).toBe(window.id);
  });

  it.each([
    ["while the claim runs", Infinity],
    ["before the claim comes", 1],
  ])("keeps the bytes a claim cut at through a budget fold %s", async (_when, dragIdleMs) => {
    const saved = "B".repeat(3000);
    const { history, write, read, projectDir } = await project(
      { "index.html": "a", "other.html": "o" },
      { budgetBytes: 2000 },
    );
    await change(history, you, "Old", () => write("other.html", "o2"));
    history.pin((await change(history, you, "Pinned", () => write("other.html", "o3"))).id, true);
    write("other.html", "o4");
    await history.claim(you, "Drag", ["other.html"], { coalesceKey: "drag", idleMs: dragIdleMs });
    // Studio's write of `edited` replaced a save it never read.
    const edited = `${saved}!`;
    write("index.html", edited);
    recordFileWriteReceipt(join(projectDir, "index.html"), {
      path: "index.html",
      version: fileContentVersion(edited),
      writeToken: "studio",
      overwrote: saved,
    });
    await new Promise((settle) => setTimeout(settle, 20));

    const edit = await history.claim(you, "Edit", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("a") },
    });
    expect((await history.undo(edit!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe(saved);
  });

  it("keeps the bytes an API write replaced when its history folder was removed while open", async () => {
    const { history, write, read, projectDir, historyRoot } = await project({ "index.html": "a" });
    rmSync(historyRoot, { recursive: true, force: true });
    write("index.html", "E");
    recordFileWriteReceipt(join(projectDir, "index.html"), {
      path: "index.html",
      version: fileContentVersion("E"),
      writeToken: "studio",
      overwrote: "S",
    });

    const edit = await history.claim(you, "Edit", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("a") },
    });
    expect((await history.undo(edit!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("S");
  });

  it("forgets what an API write replaced once the file is removed", async () => {
    const { history, write, read, projectDir } = await project({ "index.html": "a" });
    write("index.html", "E");
    recordFileWriteReceipt(join(projectDir, "index.html"), {
      path: "index.html",
      version: fileContentVersion("E"),
      writeToken: "studio",
      overwrote: "S",
    });
    rmSync(join(projectDir, "index.html"));
    await history.claim(you, "sweep", []);
    // Re-created outside Studio with the bytes the API wrote: nothing Studio wrote is on disk now.
    write("index.html", "E");

    const edit = await history.claim(you, "Edit", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("a") },
    });
    expect((await history.undo(edit!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("a");
  });

  it("frees unreferenced bytes past its budget even when nothing is left to fold", async () => {
    const saved = "B".repeat(3000);
    const { history, write, projectDir } = await project(
      { "index.html": "a", "other.html": "o" },
      { budgetBytes: 2000 },
    );
    history.pin((await change(history, you, "Pinned", () => write("other.html", "o2"))).id, true);
    const edited = `${saved}!`;
    write("index.html", edited);
    recordFileWriteReceipt(join(projectDir, "index.html"), {
      path: "index.html",
      version: fileContentVersion(edited),
      writeToken: "agent",
      overwrote: saved,
    });
    write("index.html", "x");
    await history.flush();

    await expect(history.readBlob(hashOfVersion(fileContentVersion(saved))!)).rejects.toThrow();
  });

  it("cuts a claim at a restored save, not at bytes an earlier claim already used", async () => {
    const { history, write, read, projectDir } = await project({ "index.html": "W" });
    const studioWrites = (content: string, overwrote: string) => {
      write("index.html", content);
      recordFileWriteReceipt(join(projectDir, "index.html"), {
        path: "index.html",
        version: fileContentVersion(content),
        writeToken: "studio",
        overwrote,
      });
    };
    const told = (content: string) => ({
      overwrote: { "index.html": fileContentVersion(content) },
    });
    studioWrites("X", "W");
    await history.claim(you, "First", ["index.html"], told("W"));
    studioWrites("Y", "X");
    await history.claim(you, "Second", ["index.html"], told("X"));
    // An editor restores X; Studio, still holding Y, patches it before the history sees X.
    write("index.html", "X");
    studioWrites("Z", "X");

    const third = await history.claim(you, "Third", ["index.html"], told("Y"));
    expect((await history.undo(third!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("X");
  });

  it("keeps what a Studio write replaced over an unseen save, for the next claim", async () => {
    const { history, write, read, projectDir } = await project({ "index.html": "W" });
    const receipt = (content: string, overwrote: string) =>
      recordFileWriteReceipt(join(projectDir, "index.html"), {
        path: "index.html",
        version: fileContentVersion(content),
        writeToken: "studio",
        overwrote,
      });
    const told = (content: string) => ({
      overwrote: { "index.html": fileContentVersion(content) },
    });
    write("index.html", "X");
    receipt("X", "W");
    await history.claim(you, "First", ["index.html"], told("W"));
    // Studio's next write lands over an editor's save B that the history never saw.
    write("index.html", "Y");
    receipt("Y", "B");

    const second = await history.claim(you, "Second", ["index.html"], told("X"));
    expect((await history.undo(second!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("B");
  });

  it.each([
    ["once its change is committed", true],
    ["once an editor wrote over it", false],
  ])(
    "forgets what an API write replaced %s, so a later claim cannot cut at it",
    async (_when, commit) => {
      const { history, write, read, projectDir } = await project({ "index.html": "W" });
      write("index.html", "X");
      recordFileWriteReceipt(join(projectDir, "index.html"), {
        path: "index.html",
        version: fileContentVersion("X"),
        writeToken: "agent",
        overwrote: "W",
      });
      if (commit) await history.flush();
      write("index.html", "C");
      await history.flush();
      // An editor, not the API, brings X back.
      write("index.html", "X");

      const edit = await history.claim(you, "Edit", ["index.html"], {
        overwrote: { "index.html": fileContentVersion("C") },
      });
      expect((await history.undo(edit!.id, { who: you })).ok).toBe(true);
      expect(read("index.html")).toBe("C");
    },
  );

  it("cuts at an editor's save, not at what a rolled-back API write replaced", async () => {
    const { history, write, read, projectDir } = await project({ "index.html": "W" });
    const apiWrites = (content: string, overwrote?: string) => {
      write("index.html", content);
      recordFileWriteReceipt(join(projectDir, "index.html"), {
        path: "index.html",
        version: fileContentVersion(content),
        writeToken: "api",
        overwrote,
      });
    };
    apiWrites("X", "W");
    apiWrites("W");
    apiWrites("K", "W");
    await history.claim(you, "First", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("W") },
    });
    write("index.html", "X");
    apiWrites("P", "X");

    const second = await history.claim(you, "Second", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("K") },
    });
    expect((await history.undo(second!.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("X");
  });

  it("lets the budget free the bytes a committed API write replaced", async () => {
    const saved = "B".repeat(3000);
    const { history, write, projectDir } = await project(
      { "index.html": "a", "other.html": "o" },
      { budgetBytes: 2000 },
    );
    const edited = `${saved}!`;
    write("index.html", edited);
    recordFileWriteReceipt(join(projectDir, "index.html"), {
      path: "index.html",
      version: fileContentVersion(edited),
      writeToken: "agent",
      overwrote: saved,
    });
    await history.flush();

    await change(history, you, "Other", () => write("other.html", "o2"));
    expect(history.list().map((entry) => entry.label)).toContain("Other");
  });

  it("keeps the history of a small edit in a project larger than its budget", async () => {
    const { history, write } = await project(
      { "media.bin": Buffer.alloc(4096, 1), "index.html": "a" },
      { budgetBytes: 2048 },
    );
    await change(history, you, "Title", () => write("index.html", "b"));
    expect(history.list()).toHaveLength(1);
  });

  it("past its budget folds the oldest entries away and deletes their bytes, but never past a pin", async () => {
    const { history, write, read } = await project(
      { "index.html": "a".repeat(40) },
      { budgetBytes: 50 },
    );
    const pinned = await change(history, you, "B", () => write("index.html", "b".repeat(40)));
    history.pin(pinned.id, true);
    await change(history, you, "C", () => write("index.html", "c".repeat(40)));
    expect(history.list()).toHaveLength(2);

    history.pin(pinned.id, false);
    const last = await change(history, you, "D", () => write("index.html", "d".repeat(40)));
    expect(history.list().map((entry) => entry.id)).toEqual([last.id]);
    expect(history.peek(pinned.id)).toBeNull();
    await expect(history.readBlob(history.peek(START)!["index.html"]!)).resolves.toEqual(
      Buffer.from("c".repeat(40)),
    );
    expect((await history.undo(last.id, { who: you })).ok).toBe(true);
    expect(read("index.html")).toBe("c".repeat(40));
  });
});

describe("claim: a writer that records after writing", () => {
  it("files the claimed paths' writes as the claimer's entry; other outside writes stay outside, logged first", async () => {
    const { history, write, read } = await project({ "index.html": "A", "notes.md": "n" });
    write("index.html", "B");
    write("notes.md", "agent notes");
    const claimed = await history.claim(you, "Moved Title", ["index.html"]);
    expect(history.list().map((entry) => [entry.who.kind, entry.files[0]!.path])).toEqual([
      ["outside", "notes.md"],
      ["person", "index.html"],
    ]);
    expect(history.list()[1]).toMatchObject({ id: claimed!.id, label: "Moved Title" });
    await history.undo(claimed!.id, { who: you });
    expect(read("index.html")).toBe("A");
    expect(await history.claim(you, "Nothing", ["index.html"]), "nothing left to claim").toBeNull();
  });

  it("merges claims with one coalesceKey into one entry, and Cmd+Z right after undoes all of it", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    write("index.html", "B");
    const first = await history.claim(you, "Dragged Title", ["./index.html"], {
      coalesceKey: "drag",
    });
    write("index.html", "C");
    const second = await history.claim(you, "Dragged Title", ["index.html"], {
      coalesceKey: "drag",
    });
    expect(second!.id).toBe(first!.id);
    expect(history.list(), "still open for the next write of the drag").toEqual([]);

    expect(await history.step("back", you)).toMatchObject({
      ok: true,
      entry: { label: "Undid: Dragged Title" },
    });
    expect(read("index.html")).toBe("A");
    expect(history.list()[0]).toMatchObject({ id: first!.id, files: [{ path: "index.html" }] });
  });

  it("dates a held claim by its last write, not by the later edit that commits it", async () => {
    let clock = 1_000;
    const { history, write } = await project({ "index.html": "A" }, { now: () => clock });
    const held = { idleMs: Number.POSITIVE_INFINITY };
    write("index.html", "B");
    await history.claim(you, "Moved clip", ["index.html"], { ...held, coalesceKey: "move:1" });
    clock = 600_000;
    write("index.html", "C");
    await history.claim(you, "Moved clip", ["index.html"], { ...held, coalesceKey: "move:2" });

    expect(history.list().map((entry) => entry.endedAt)).toEqual([1_000]);
  });

  it("a coalescing claim whose writes net to nothing returns null and records nothing", async () => {
    const { history, write } = await project({ "index.html": "A" });
    write("index.html", "B");
    expect(
      await history.claim(you, "Dragged Title", ["index.html"], { coalesceKey: "drag" }),
    ).not.toBeNull();
    write("index.html", "A");
    expect(
      await history.claim(you, "Dragged Title", ["index.html"], { coalesceKey: "drag" }),
    ).toBeNull();
    await history.flush();
    expect(history.list()).toEqual([]);
  });

  it("an agent's write seconds before Studio's stays the agent's, cut at the version Studio overwrote", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    write("index.html", "B");
    await history.claim(you, "sweep", []);
    write("index.html", "C");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("B") },
    });
    expect(history.list().map((entry) => [entry.who.kind, entry.label])).toEqual([
      ["outside", "Changed outside the app"],
      ["person", "Moved Title"],
    ]);
    await undoNewest(history);
    expect(read("index.html"), "undoing the turn leaves only the person's edit").toBe("B");
    await undoNewest(history);
    expect(read("index.html")).toBe("A");
  });

  it("an agent's turn cut by Studio's edit becomes an entry before it and one after, so undoing walks back in order", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await history.claim(you, "sweep", []);
    write("index.html", "C");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("B") },
    });
    write("index.html", "D");
    expect(await window.close(), "the window still returns the entry it became").toMatchObject({
      id: window.id,
    });
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Agent turn",
      "Moved Title",
      "Agent turn",
    ]);
    for (const expected of ["C", "B", "A"]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect(read("index.html")).toBe(expected);
    }
  });

  it("a cut agent turn with nothing after the cut ends as the entry it became at the cut", async () => {
    const { history, write, read } = await project({ "index.html": "A", "b.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await history.claim(you, "sweep", []);
    write("index.html", "C");
    write("b.js", "2");
    await history.claim(you, "Moved Title", ["index.html", "b.js"], {
      overwrote: { "index.html": fileContentVersion("B"), "b.js": fileContentVersion("1") },
    });
    write("b.js", "3");
    await history.claim(you, "Recolored", ["b.js"], {
      overwrote: { "b.js": fileContentVersion("2") },
    });
    const cutAt = history.list()[0]!;
    expect(cutAt).toMatchObject({ label: "Agent turn", who: agent });
    expect(
      await window.close(),
      "close returns the entry the window became at the cut",
    ).toMatchObject({ id: cutAt.id });
    for (const [index, b] of [
      ["C", "2"],
      ["B", "1"],
      ["A", "1"],
    ]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect([read("index.html"), read("b.js")]).toEqual([index, b]);
    }
  });

  it("a held drag across an agent's write ends at that write, so undoing walks back every step", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    // A claim under the drag's key that names no file: a scan that keeps the drag held.
    const scan = () => history.claim(you, "scan", [], { coalesceKey: "drag" });
    write("index.html", "B");
    await scan();
    write("index.html", "C");
    await drag("B");
    write("index.html", "D");
    await scan();
    write("index.html", "E");
    await drag("D");
    await history.flush();
    await window.close();
    for (const expected of ["D", "C", "B", "A"]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect(read("index.html")).toBe(expected);
    }
  });

  it("a held drag across a write made outside ends at that write too", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    write("index.html", "C");
    await history.claim(you, "scan", [], { coalesceKey: "drag" });
    write("index.html", "D");
    await drag("C");
    await history.flush();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Dragged Title",
      "Changed outside the app",
      "Dragged Title",
    ]);
    for (const expected of ["C", "B", "A"]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect(read("index.html")).toBe(expected);
    }
  });

  it("a held drag across an agent turn that already closed ends at the turn too", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "C");
    await window.close();
    write("index.html", "D");
    await drag("C");
    await history.flush();
    for (const expected of ["C", "B", "A"]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect(read("index.html")).toBe(expected);
    }
  });

  it("a held drag ends when someone else changed a file it holds, even if its next step writes another", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    const drag = (path: string, overwrote: string) =>
      history.claim(you, "Dragged Title", [path], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { [path]: fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("index.html", "A");
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "C");
    write("r.js", "2");
    await window.close();
    write("r.js", "3");
    await drag("r.js", "2");
    await history.flush();
    for (const expected of [
      ["C", "2"],
      ["B", "1"],
      ["A", "1"],
    ]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect([read("index.html"), read("r.js")]).toEqual(expected);
    }
  });

  it("a held drag ends when one file of its next step continues and another does not", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    const drag = (overwrote: Record<string, string>) =>
      history.claim(you, "Dragged Title", Object.keys(overwrote), {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: Object.fromEntries(
          Object.entries(overwrote).map(([path, text]) => [path, fileContentVersion(text)]),
        ),
      });
    write("index.html", "B");
    await drag({ "index.html": "A" });
    write("index.html", "C");
    await history.claim(you, "scan", [], { coalesceKey: "drag" });
    write("index.html", "D");
    write("r.js", "2");
    await drag({ "index.html": "C", "r.js": "1" });
    await history.flush();
    for (const expected of [
      ["C", "1"],
      ["B", "1"],
      ["A", "1"],
    ]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect([read("index.html"), read("r.js")]).toEqual(expected);
    }
  });

  it("a held claim that deleted a file ends where someone else recreated it", async () => {
    const { history, write, read, has, projectDir } = await project({ "index.html": "A" });
    const claim = (overwrote: string) =>
      history.claim(you, "Edited", ["index.html"], {
        coalesceKey: "edit",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    rmSync(join(projectDir, "index.html"));
    await claim("A");
    write("index.html", "X");
    await history.claim(you, "scan", [], { coalesceKey: "edit" });
    write("index.html", "Y");
    await claim("X");
    await history.flush();
    await undoNewest(history);
    expect(read("index.html")).toBe("X");
    await undoNewest(history);
    expect(has("index.html")).toBe(false);
    await undoNewest(history);
    expect(read("index.html")).toBe("A");
  });

  it("a drag stays one entry when a file it adds midway was cut from an agent's turn", async () => {
    const { history, write } = await project({ "index.html": "A", "b.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("b.js", "2");
    await history.claim(you, "scan", []);
    const drag = (paths: string[], overwrote: Record<string, string>) =>
      history.claim(you, "Dragged Title", paths, {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: Object.fromEntries(
          Object.entries(overwrote).map(([path, text]) => [path, fileContentVersion(text)]),
        ),
      });
    write("index.html", "B");
    await drag(["index.html"], { "index.html": "A" });
    write("index.html", "C");
    write("b.js", "3");
    await drag(["index.html", "b.js"], { "index.html": "B", "b.js": "2" });
    await history.flush();
    await window.close();
    expect(history.list().filter((entry) => entry.label === "Dragged Title")).toHaveLength(1);
  });

  it("a person's edit during an agent turn splits the turn around it, each part logged in write order", async () => {
    const { history, write, read } = await project({ "index.html": "A", "b.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    write("b.js", "2");
    await history.claim(you, "scan", []);
    write("index.html", "C");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("B") },
    });
    write("index.html", "D");
    const turn = await window.close();
    expect(
      history.list().map((entry) => [entry.label, entry.files.map((file) => file.path)]),
    ).toEqual([
      ["Agent turn", ["b.js", "index.html"]],
      ["Moved Title", ["index.html"]],
      ["Agent turn", ["index.html"]],
    ]);
    expect(turn).toMatchObject({ id: window.id });
    expect(await history.undo(turn!.id, { who: agent })).toMatchObject({ ok: true });
    expect([read("index.html"), read("b.js")]).toEqual(["C", "2"]);
  });

  it("a drag claimed during an agent turn ends at the turn and is logged before the turn's last part", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    await dragDuringTurn(history, write);
    await history.flush();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Agent turn",
      "Dragged Title",
      "Agent turn",
    ]);
    for (const expected of ["C", "B", "A"]) {
      expect(await undoNewest(history)).toMatchObject({ ok: true });
      expect(read("index.html")).toBe(expected);
    }
  });

  it("a drag held when an agent turn starts ends there, and its next step logs after the turn's earlier writes", async () => {
    const { history, write } = await project({ "index.html": "A", "other.js": "1" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    const window = await history.beginWindow(agent, "Agent turn");
    write("other.js", "2");
    write("index.html", "C");
    await drag("B");
    await window.close();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Dragged Title",
      "Agent turn",
      "Dragged Title",
    ]);
  });

  it("logs an agent turn's writes before a second agent's overlapping turn that closes first", async () => {
    const { history, projectDir } = await project({ a: "file" });
    const first = await history.beginWindow(agent, "Agent one");
    rmSync(join(projectDir, "a"));
    mkdirSync(join(projectDir, "a"));
    writeFileSync(join(projectDir, "a", "b.txt"), "b0");
    const second = await history.beginWindow({ kind: "agent", name: "Other" }, "Agent two");
    writeFileSync(join(projectDir, "a", "b.txt"), "b1");
    const two = await second.close();
    await first.close();
    expect(history.list().map((entry) => entry.label)).toEqual(["Agent one", "Agent two"]);

    for (const [side, content] of [
      ["before", "b0"],
      ["after", "b1"],
    ] as const) {
      const dir = tempDir("hf-history-checkout-");
      await history.checkout(two!.id, side, dir);
      expect(inside(dir, "a/b.txt")).toBe(content);
    }
  });

  it("reopens after a restore run inside an open agent turn without inventing an outside change", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await history.restore(START, you);
    await window.close();
    await history.close();

    const reopened = await open(projectDir, historyRoot);
    await reopened.flush();
    expect(reopened.list().map((entry) => entry.label)).toEqual([
      "Agent turn",
      "Restored: the start",
    ]);
  });

  it("a held drag ends when a write to another file is pending", async () => {
    const { history, write } = await project({ "index.html": "A", "r.js": "1" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    write("r.js", "2");
    write("index.html", "C");
    await drag("B");
    await history.flush();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Dragged Title",
      "Changed outside the app",
      "Dragged Title",
    ]);
  });

  it("Cmd+Z during an agent turn reverts the person's last edit, names it, and leaves the agent's writes", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    write("index.html", "B");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("A") },
    });
    const window = await history.beginWindow(agent, "Agent turn");
    write("r.js", "2");

    expect(history.next("back", you)?.label).toBe("Moved Title");
    expect(await history.step("back", you)).toMatchObject({ ok: true });
    expect([read("index.html"), read("r.js")]).toEqual(["A", "2"]);
    await window.close();
    expect(history.next("back", you)).toBeUndefined();
  });

  it("Cmd+Z names a held drag and reverts it", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    write("index.html", "B");
    await history.claim(you, "Dragged Title", ["index.html"], {
      coalesceKey: "drag",
      idleMs: 60_000,
      overwrote: { "index.html": fileContentVersion("A") },
    });

    expect(history.next("back", you)?.label).toBe("Dragged Title");
    expect(await history.step("back", you)).toMatchObject({ ok: true });
    expect(read("index.html")).toBe("A");
  });

  it("Cmd+Z names an outside edit still pending and reverts it before the person's own", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    write("index.html", "B");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("A") },
    });
    write("r.js", "2");
    history.noteChange("r.js");

    await vi.waitFor(() =>
      expect(history.next("back", you)?.label).toBe("Changed outside the app"),
    );
    expect(await history.step("back", you)).toMatchObject({
      entry: { label: "Undid: Changed outside the app" },
    });
    expect([read("index.html"), read("r.js")]).toEqual(["B", "1"]);
  });

  it("Cmd+Z names an outside edit pending over a held drag and reverts the outside edit first", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    write("index.html", "B");
    await history.claim(you, "Dragged Title", ["index.html"], {
      coalesceKey: "drag",
      idleMs: 60_000,
      overwrote: { "index.html": fileContentVersion("A") },
    });
    write("r.js", "2");
    history.noteChange("r.js");

    await vi.waitFor(() =>
      expect(history.next("back", you)?.label).toBe("Changed outside the app"),
    );
    expect(await history.step("back", you)).toMatchObject({
      entry: { label: "Undid: Changed outside the app" },
    });
    expect([read("index.html"), read("r.js")]).toEqual(["B", "1"]);
  });

  it("Cmd+Z names a window the person has open and reverts its writes", async () => {
    const { history, write, read } = await project({ "index.html": "A" });
    await history.beginWindow(you, "Moved Title");
    write("index.html", "B");
    history.noteChange("index.html");

    await vi.waitFor(() => expect(history.next("back", you)?.label).toBe("Moved Title"));
    expect(await history.step("back", you)).toMatchObject({
      entry: { label: "Undid: Moved Title" },
    });
    expect(read("index.html")).toBe("A");
  });

  it("Cmd+Shift+Z never redoes an agent's own undo of its turn", async () => {
    const { history, write } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await window.close();
    const [turn] = history.list();
    await history.undo(turn!.id, { who: agent });

    expect(history.next("forward", you)).toBeUndefined();
  });

  it("Cmd+Shift+Z redoes the person's edit across an agent's write to another file", async () => {
    const { history, write, read } = await project({ "index.html": "A", "r.js": "1" });
    write("index.html", "B");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("A") },
    });
    await history.step("back", you);
    const window = await history.beginWindow(agent, "Agent turn");
    write("r.js", "2");
    await window.close();

    expect(await history.step("forward", you)).toMatchObject({
      entry: { label: "Redid: Moved Title" },
    });
    expect([read("index.html"), read("r.js")]).toEqual(["B", "2"]);
  });

  describe("with undoScope everyone", () => {
    async function editThenTurn() {
      const opened = await project({ "index.html": "A" }, { undoScope: "everyone" });
      await change(opened.history, you, "Moved Title", () => opened.write("index.html", "B"));
      const window = await opened.history.beginWindow(agent, "Agent turn");
      opened.write("index.html", "C");
      await window.close();
      return opened;
    }

    it("Cmd+Z undoes the newest change whoever made it: the agent's turn, then the person's edit", async () => {
      const { history, read } = await editThenTurn();

      expect(await history.step("back", you)).toMatchObject({
        ok: true,
        entry: { label: "Undid: Agent turn" },
      });
      expect(read("index.html")).toBe("B");
      expect(await history.step("back", you)).toMatchObject({
        ok: true,
        entry: { label: "Undid: Moved Title" },
      });
      expect(read("index.html")).toBe("A");
    });

    it("Shift+Cmd+Z brings them back in turn", async () => {
      const { history, read } = await editThenTurn();
      await history.step("back", you);
      await history.step("back", you);

      await history.step("forward", you);
      expect(read("index.html")).toBe("B");
      await history.step("forward", you);
      expect(read("index.html")).toBe("C");
    });

    it("a new change by anyone ends Shift+Cmd+Z", async () => {
      const { history, write } = await editThenTurn();
      await history.step("back", you);
      await change(history, agent, "Another turn", () => write("index.html", "D"));

      expect(history.next("forward", you)).toBeUndefined();
    });

    it("leaves an agent's turn that is still open alone", async () => {
      const { history, write, read } = await project(
        { "index.html": "A", "r.js": "1" },
        { undoScope: "everyone" },
      );
      await change(history, you, "Moved Title", () => write("index.html", "B"));
      const window = await history.beginWindow(agent, "Agent turn");
      write("r.js", "2");

      expect(history.next("back", you)?.label).toBe("Moved Title");
      await history.step("back", you);
      expect([read("index.html"), read("r.js")]).toEqual(["A", "2"]);
      await window.close();
    });
  });

  it("an agent's turn the person undid and redid is the person's to Cmd+Z", async () => {
    const { history, write } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await window.close();
    const [turn] = history.list();
    await history.undo(turn!.id, { who: you });
    await history.step("forward", you);

    expect(history.next("back", you)?.id).toBe(turn!.id);
  });

  it("undoes a turn's parts last first and keeps the person's edit between them", async () => {
    const { history, write, read } = await project({ "index.html": "A", "b.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    write("b.js", "2");
    await history.claim(you, "scan", []);
    write("index.html", "C");
    await history.claim(you, "Moved Title", ["index.html"], {
      overwrote: { "index.html": fileContentVersion("B") },
    });
    write("index.html", "D");
    await window.close();
    const [first, , last] = history.list();
    const keep = { who: agent, mode: "keep-later-edits" } as const;

    expect(await history.undo(last!.id, keep)).toMatchObject({ ok: true });
    expect(await history.undo(first!.id, keep)).toMatchObject({ ok: true });
    expect([read("index.html"), read("b.js")]).toEqual(["C", "1"]);
    expect(await history.undo(first!.id, keep)).toEqual({ ok: true, entry: null });
  });

  it("a window opening ends a held drag even when nothing else was written", async () => {
    const { history, write } = await project({ "index.html": "A" });
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "C");
    await drag("B");
    await window.close();
    expect(history.list().map((entry) => entry.label)).toEqual(["Dragged Title", "Dragged Title"]);
  });

  it("a drag held inside an agent turn ends when the agent writes another file", async () => {
    const { history, write } = await project({ "index.html": "A", "other.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    const drag = (overwrote: string) =>
      history.claim(you, "Dragged Title", ["index.html"], {
        coalesceKey: "drag",
        idleMs: 60_000,
        overwrote: { "index.html": fileContentVersion(overwrote) },
      });
    write("index.html", "B");
    await drag("A");
    write("other.js", "2");
    write("index.html", "C");
    await drag("B");
    await window.close();
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Dragged Title",
      "Agent turn",
      "Dragged Title",
    ]);
  });

  it("an outside write logs after a drag held before it, however long it waits", async () => {
    const { history, write } = await project({ "index.html": "A", "r.js": "1" }, { quietMs: 20 });
    write("index.html", "B");
    await history.claim(you, "Dragged Title", ["index.html"], {
      coalesceKey: "drag",
      idleMs: 60_000,
      overwrote: { "index.html": fileContentVersion("A") },
    });
    write("r.js", "2");
    history.noteChange("r.js");
    await vi.waitFor(() => expect(history.list()).toHaveLength(2));
    expect(history.list().map((entry) => entry.label)).toEqual([
      "Dragged Title",
      "Changed outside the app",
    ]);
  });

  it("reopens after a drag claimed during an agent turn without inventing an outside change", async () => {
    const { history, write, projectDir, historyRoot } = await project({ "index.html": "A" });
    await dragDuringTurn(history, write);
    await history.close();

    const reopened = await open(projectDir, historyRoot);
    await reopened.flush();
    expect(reopened.list().map((entry) => entry.label)).toEqual([
      "Agent turn",
      "Dragged Title",
      "Agent turn",
    ]);
  });

  it("logs an entry with only its own fields, not its window's timer", async () => {
    const { history, write } = await project({ "index.html": "A" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("index.html", "B");
    await window.close();
    expect(Object.keys(history.list()[0]!).sort()).toEqual([
      "endedAt",
      "files",
      "id",
      "label",
      "pinned",
      "startedAt",
      "undone",
      "who",
    ]);
  });

  it("takes Studio's write out of an agent's open window, and leaves the agent's own writes there", async () => {
    const { history, write } = await project({ "index.html": "A", "a.js": "1" });
    const window = await history.beginWindow(agent, "Agent turn");
    write("a.js", "2");
    write("index.html", "B");
    const claimed = await history.claim(you, "Moved Title", ["index.html"]);
    const entry = await window.close();
    expect(claimed).not.toBeNull();
    expect(entry?.files.map((file) => file.path)).toEqual(["a.js"]);
    expect(history.list().find((item) => item.id === claimed!.id)?.files).toMatchObject([
      { path: "index.html" },
    ]);
  });

  it("a claim under another key that takes nothing still ends the held one", async () => {
    const { history, write } = await project({ "index.html": "A" });
    write("index.html", "B");
    await history.claim(you, "Dragged Title", ["index.html"], { coalesceKey: "drag" });
    expect(
      await history.claim(you, "Nothing", ["index.html"], { coalesceKey: "other" }),
    ).toBeNull();
    expect(history.list()).toMatchObject([{ label: "Dragged Title" }]);
  });

  it("reads no blob outside its store", async () => {
    const { history } = await project({ "index.html": "A" });
    await expect(history.readBlob("../../../../../../../../etc/hostname")).rejects.toThrow(
      "not a history blob",
    );
  });

  it("a claim with another key, or its idle time, ends the coalescing claim", async () => {
    const { history, write } = await project({ "a.html": "A", "b.html": "B" });
    write("a.html", "A2");
    await history.claim(you, "Dragged A", ["a.html"], { coalesceKey: "a", idleMs: 30 });
    await vi.waitFor(() => expect(history.list()).toMatchObject([{ label: "Dragged A" }]));
    write("b.html", "B2");
    await history.claim(you, "Dragged B", ["b.html"], { coalesceKey: "b" });
    write("a.html", "A3");
    await history.claim(you, "Dragged A again", ["a.html"], { coalesceKey: "a" });
    expect(history.list().map((entry) => entry.label)).toEqual(["Dragged A", "Dragged B"]);
  });

  it("an outside write to a claimed path between the write and its claim folds into the claim (the ceiling)", async () => {
    const { history, write } = await project({ "index.html": "A" });
    write("index.html", "B");
    write("index.html", "C");
    await history.claim(you, "Moved Title", ["index.html"]);
    const [entry] = history.list();
    expect(entry).toMatchObject({ who: you, label: "Moved Title" });
    const blob = async (hash: string | null) =>
      hash ? String(await history.readBlob(hash)) : null;
    expect([await blob(entry!.files[0]!.before), await blob(entry!.files[0]!.after)]).toEqual([
      "A",
      "C",
    ]);
  });
});

describe("idle windows", () => {
  it("sleeps a window with an idle limit past Node's timer range instead of waking every millisecond", async () => {
    const { history } = await project({ "index.html": "A" });
    const timer = vi.spyOn(globalThis, "setTimeout");
    const window = await history.beginWindow(agent, "Long turn", { idleMs: 30 * 86_400_000 });
    const delays = timer.mock.calls.map(([, delay]) => delay ?? 0);
    timer.mockRestore();
    expect(Math.max(...delays)).toBeLessThanOrEqual(2 ** 31 - 1);
    expect(Math.max(...delays)).toBeGreaterThan(86_400_000);
    await window.close();
  });
});

describe("a file shortened while the history copies it in", () => {
  /** Fails, instead of hanging the run, when `work` has not returned in 10 s. */
  const within = (work: Promise<unknown>, what: string) =>
    Promise.race([
      work,
      pause(10_000).then(() => {
        throw new Error(`${what} never returned`);
      }),
    ]);

  it("never stalls the sweep or the undo behind it", { timeout: 30_000 }, async () => {
    const { projectDir, historyRoot, history } = await project({ "index.html": "<h1>Hello</h1>" });
    const clip = join(projectDir, "clip.bin");
    writeFileSync(clip, Buffer.alloc(64 * 1024 * 1024, 1));
    let settled = false;
    const swept = history.flush().finally(() => (settled = true));
    // The clip's copy is under way once a temp copy passes 1 MB; a disk that clones may finish before it is seen.
    const copying = () =>
      readdirSync(historyRoot, { recursive: true }).some((name) => {
        const path = join(historyRoot, String(name));
        return (
          basename(path).startsWith("incoming-") &&
          (statSync(path, { throwIfNoEntry: false })?.size ?? 0) > 2 ** 20
        );
      });
    while (!settled && !copying()) await new Promise(setImmediate);
    writeFileSync(clip, "");
    await within(swept, "the sweep");
    await within(history.step("back", you), "the undo");
  });
});

describe("the history's copy of a file", () => {
  it.skipIf(process.platform === "win32")("keeps the file's mode", async () => {
    const dir = tempDir("hf-history-blobs-");
    const store = await openBlobStore(join(dir, "blobs"));
    const script = join(dir, "build.sh");
    writeFileSync(script, "echo hi\n");
    chmodSync(script, 0o755);
    const hash = await store.put(script);
    const [stored] = readdirSync(join(dir, "blobs"), { recursive: true }).filter((name) =>
      String(name).endsWith(hash),
    );
    expect(statSync(join(dir, "blobs", String(stored))).mode & 0o777).toBe(0o755);
  });

  it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
    "leaves no partial copy in the store",
    async () => {
      const dir = tempDir("hf-history-blobs-");
      const store = await openBlobStore(join(dir, "blobs"));
      const locked = join(dir, "locked.html");
      writeFileSync(locked, "<h1>Hello</h1>");
      chmodSync(locked, 0o000);
      await expect(store.put(join(dir, "gone.html"))).rejects.toMatchObject({ code: "ENOENT" });
      await expect(store.put(locked)).rejects.toMatchObject({ code: "EACCES" });
      expect(readdirSync(join(dir, "blobs"))).toEqual([]);
    },
  );
});