Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
71.9 KB
Raw Blame
import { afterEach, describe, expect, jest, test } from "bun:test";
import { execFile } from "node:child_process";
import { mkdir, symlink, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { promisify } from "node:util";

import { FakeArchiveServer } from "./fake-archive-server.js";
import { SessionArchiver, type CaptureResult, type DrainResult, type FinalReason } from "./index.js";
import {
  completedTurnCount,
  projectArchiveEnabled,
  ProjectArchiveLifecycle,
  type ArchiveEngineReads,
  type ProjectArchiver,
} from "./lifecycle.js";
import { cleanupTempDirs, manifestOf, openArchive, tempDir } from "./test-helpers.js";

const execFileAsync = promisify(execFile);

afterEach(cleanupTempDirs);

const queued = (kind: "base" | "delta", sequence = 0): CaptureResult => ({ status: "queued", archiveId: `archive-${kind}-${sequence}`, kind, sequence, size: 1 });
const skipped = (reason: Extract<CaptureResult, { status: "skipped" }>["reason"]): CaptureResult => ({ status: "skipped", reason });
const drained: DrainResult = { uploaded: 0, pending: 0, dropped: 0, blocked: null, disabled: false };

/** Records every call; each result can be swapped per test. */
class FakeArchiver implements ProjectArchiver {
  readonly calls: string[] = [];
  base: (sessionId: string, turn: number) => Promise<CaptureResult> = async () => queued("base");
  delta: (sessionId: string, turn: number | null) => Promise<CaptureResult> = async (_sessionId, turn) => queued("delta", turn ?? 0);
  final: (sessionId: string, reason: FinalReason, signal?: AbortSignal) => Promise<CaptureResult> = async () => skipped("unchanged");
  drainResult: () => Promise<DrainResult> = async () => drained;
  /** What startFinalCandidates answers (not recorded as a call). */
  startFinals: string[] = [];
  /** The options of each stop() call. */
  readonly stops: Array<{ finals?: readonly string[]; budgetMs?: number }> = [];
  /** recordTouched and forgetTouched calls (not in `calls`). */
  readonly touched: string[] = [];
  /** What touchedBaseDue answers (a touched-files chain still without its base). */
  baseDue = false;

  async touchedBaseDue(_sessionId: string): Promise<boolean> {
    return this.baseDue;
  }

  async captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {
    this.calls.push(`base ${sessionId} ${root} ${turn}`);
    return this.base(sessionId, turn);
  }

  async captureDelta(sessionId: string, root: string, turn: number | null, _options: { before?: number | (() => number | undefined) } = {}): Promise<CaptureResult> {
    this.calls.push(`delta ${sessionId} ${root} ${turn}`);
    return this.delta(sessionId, turn);
  }

  async captureFinal(sessionId: string, reason: FinalReason, options: { signal?: AbortSignal } = {}): Promise<CaptureResult> {
    this.calls.push(`final ${sessionId} ${reason}`);
    return this.final(sessionId, reason, options.signal);
  }

  async startFinalCandidates(): Promise<string[]> {
    return this.startFinals;
  }

  recordTouched(sessionId: string, path: string): void {
    this.touched.push(`record ${sessionId} ${path}`);
  }

  forgetTouched(sessionId: string): void {
    this.touched.push(`forget ${sessionId}`);
  }

  async drain(): Promise<DrainResult> {
    this.calls.push("drain");
    return this.drainResult();
  }

  async signOut(): Promise<void> {
    this.calls.push("signOut");
  }

  async stop(options: { finals?: readonly string[]; budgetMs?: number } = {}): Promise<void> {
    this.calls.push("stop");
    this.stops.push(options);
  }

  captures(): string[] {
    return this.calls.filter((call) => call.startsWith("base") || call.startsWith("delta"));
  }

  finals(): string[] {
    return this.calls.filter((call) => call.startsWith("final"));
  }
}

type Message = { info: Record<string, unknown>; parts: unknown[] };

/** A v1 engine message list: `completed` answered prompts, then optionally one still running. */
function messages(completed: number, running = false): Message[] {
  const list: Message[] = [];
  for (let turn = 1; turn <= completed + (running ? 1 : 0); turn += 1) {
    list.push({ info: { id: `user_${turn}`, role: "user", time: { created: turn } }, parts: [] });
    if (turn <= completed) list.push({ info: { id: `assistant_${turn}`, role: "assistant", time: { created: turn, completed: turn + 1 } }, parts: [] });
  }
  return list;
}

/** Engine reads for one session, counting how often each route is read. */
function engine(input: { parentID?: string; messages?: () => unknown; session?: () => unknown } = {}) {
  const reads = { session: 0, messages: 0 };
  const reader: ArchiveEngineReads = {
    session: async () => {
      reads.session += 1;
      return input.session ? input.session() : { id: "ses_root_0001", ...(input.parentID ? { parentID: input.parentID } : {}) };
    },
    messages: async () => {
      reads.messages += 1;
      return input.messages ? input.messages() : [];
    },
  };
  return { reader, reads };
}

function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; accountMissing?: boolean; now?: () => number; concurrency?: number; finalIdleMs?: number; quitBudgetMs?: number; turnDeltaWaitMs?: number; touchedBaseDelayMs?: number } = {}) {
  const logs: Array<{ level: string; message: string; attributes?: Record<string, unknown> }> = [];
  const subject = new ProjectArchiveLifecycle({
    archiver,
    enabled: options.enabled ?? true,
    ...(options.accountMissing ? { accountMissing: true } : {}),
    log: (level, message, attributes) => logs.push({ level, message, ...(attributes ? { attributes } : {}) }),
    consentRecheckMs: 60_000,
    ...(options.now ? { now: options.now } : {}),
    ...(options.concurrency ? { concurrency: options.concurrency } : {}),
    ...(options.finalIdleMs !== undefined ? { finalIdleMs: options.finalIdleMs } : {}),
    ...(options.quitBudgetMs !== undefined ? { quitBudgetMs: options.quitBudgetMs } : {}),
    ...(options.turnDeltaWaitMs !== undefined ? { turnDeltaWaitMs: options.turnDeltaWaitMs } : {}),
    ...(options.touchedBaseDelayMs !== undefined ? { touchedBaseDelayMs: options.touchedBaseDelayMs } : {}),
  });
  return { subject, logs };
}

function deferred<T>() {
  let resolve!: (value: T) => void;
  const promise = new Promise<T>((resolvePromise) => { resolve = resolvePromise; });
  return { promise, resolve };
}

describe("completedTurnCount", () => {
  test("counts prompts answered by an assistant message that ended, v1 and v2 shapes", () => {
    expect(completedTurnCount(messages(0))).toBe(0);
    expect(completedTurnCount(messages(3))).toBe(3);
    // The running turn is not complete yet.
    expect(completedTurnCount(messages(2, true))).toBe(2);
    // Several assistant steps of one turn count once; a finish part or an error also ends a turn.
    expect(completedTurnCount([
      { info: { role: "user" } },
      { info: { role: "assistant", finish: "tool-calls" } },
      { info: { role: "assistant", time: { completed: 5 } } },
      { info: { role: "user" } },
      { info: { role: "assistant" }, parts: [{ type: "step-finish" }] },
      { info: { role: "user" } },
      { info: { role: "assistant", error: { name: "MessageAbortedError" } } },
    ])).toBe(3);
    // v2 context entries carry the role as `type`.
    expect(completedTurnCount([
      { id: "u1", type: "user" },
      { id: "a1", type: "assistant", time: { created: 1, completed: 2 } },
      { id: "c1", type: "compaction" },
      { id: "u2", type: "user" },
      { id: "a2", type: "assistant", content: [{ type: "text" }] },
    ])).toBe(1);
    expect(completedTurnCount(null)).toBeNull();
    expect(completedTurnCount({ status: 500, unavailable: true })).toBeNull();
  });

  test("a compaction and synthetic notices are no turn: the count follows the prompts", () => {
    const prompt = (id: string) => ({ info: { id, role: "user" }, parts: [{ type: "text" }] });
    const answer = (id: string) => ({ info: { id, role: "assistant", time: { completed: 1 } } });
    expect(completedTurnCount([
      prompt("u1"), answer("a1"),
      prompt("u2"), answer("a2"),
      // An automatic compaction inside turn 2 (1.x: a "compaction" part; the 2.x adapter: its compaction agent)...
      { info: { id: "c1", role: "user", agent: "build" }, parts: [{ type: "compaction" }] },
      { info: { id: "s1", role: "assistant", summary: true, mode: "compaction", finish: "stop" } },
      { info: { id: "c2", role: "user", agent: "compaction" }, parts: [] },
      { info: { id: "s2", role: "assistant", summary: true, agent: "compaction", finish: "stop" } },
      // ...the engine's continue nudge and its reply...
      { info: { id: "n1", role: "user" }, parts: [{ type: "text", synthetic: true }] },
      answer("a3"),
      // ...a user-run shell command, an activated skill (synthetic text alone).
      { info: { id: "sh", role: "user" }, parts: [{ type: "text", synthetic: true }] },
      { info: { id: "sh-a", role: "assistant", time: { completed: 2 } }, parts: [{ type: "tool" }] },
      prompt("u3"), answer("a4"),
    ])).toBe(3);
    // A prompt with a synthetic note beside what was typed (an attachment path) is one.
    expect(completedTurnCount([
      { info: { role: "user" }, parts: [{ type: "text", synthetic: true }, { type: "text" }] },
      answer("a1"),
      { info: { role: "user" }, parts: [{ type: "text", synthetic: true }, { type: "file" }] },
      answer("a2"),
    ])).toBe(2);
  });

  test("a prompt stopped before any answer is a turn once the next prompt follows it", () => {
    const prompt = { info: { role: "user" }, parts: [{ type: "text" }] };
    const answer = { info: { role: "assistant", time: { completed: 1 } } };
    // Stopped with Esc before the engine answered: still the running turn...
    expect(completedTurnCount([prompt, answer, prompt])).toBe(1);
    // ...and a turn once the next prompt was sent, so turn numbers keep matching the prompts.
    expect(completedTurnCount([prompt, answer, prompt, prompt, answer])).toBe(3);
  });
});

describe("projectArchiveEnabled", () => {
  test("is on by default and off only when OMNIRUSH_ARCHIVE_ENABLED says so", () => {
    expect(projectArchiveEnabled({})).toBe(true);
    expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "1" })).toBe(true);
    expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "" })).toBe(true);
    for (const off of ["0", "false", "FALSE", " no ", "off"]) expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: off })).toBe(false);
  });
});

describe("ProjectArchiveLifecycle", () => {
  test("app start resumes the queue; a root session gets one base per app run at its real path and completed turns", async () => {
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver);
    subject.start();
    await subject.settled();
    expect(archiver.calls).toEqual(["drain"]);

    const real = await tempDir("root");
    const link = join(await tempDir("links"), "project");
    await symlink(real, link);
    const reads = engine({ messages: () => messages(2, true) });
    subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
    // Every prompt dispatch calls this; only the first one reaches the archiver.
    subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
    await subject.settled();
    subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
    await subject.settled();

    expect(archiver.captures()).toEqual([`base ses_root_0001 ${real} 2`]);
    expect(reads.reads).toEqual({ session: 1, messages: 1 });
    // A queued base is uploaded right away.
    expect(archiver.calls.slice(1)).toEqual([`base ses_root_0001 ${real} 2`, "drain"]);
    expect(logs).toEqual([]);
  });

  test("child (sub-agent) sessions are never archived", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const child = engine({ parentID: "ses_root_0001", messages: () => messages(1) });
    subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
    await subject.settled();
    subject.turnCompleted("ses_child_0001", messages(1));
    subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
    await subject.settled();

    // v2 session records nest the fields under `info`.
    const v2Child = engine({ session: () => ({ info: { id: "ses_child_0002", parentID: "ses_root_0001" } }) });
    subject.sessionStarted({ sessionId: "ses_child_0002", root, engine: v2Child.reader });
    await subject.settled();

    expect(archiver.captures()).toEqual([]);
    // Known to be a child: the engine is not asked again, and its messages are never read.
    expect(child.reads).toEqual({ session: 1, messages: 0 });
  });

  test("touched paths reach the archiver only for a session this run started that may be archived", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    // Before its first prompt, the session is not known here.
    subject.pathTouched("ses_touch_0001", "early.txt");
    subject.sessionStarted({ sessionId: "ses_touch_0001", root, engine: engine().reader });
    // While its start step waits, and once it is resolved with a root.
    subject.pathTouched("ses_touch_0001", "brief.pdf");
    await subject.settled();
    subject.pathTouched("ses_touch_0001", "out/render.png");
    // Not archivable: nothing more.
    archiver.base = async () => skipped("not_archivable");
    subject.sessionStarted({ sessionId: "ses_touch_0002", root, engine: engine().reader });
    await subject.settled();
    subject.pathTouched("ses_touch_0002", "x.txt");
    // A child session: what it reported goes, and nothing more is passed on.
    subject.sessionStarted({ sessionId: "ses_touch_child", root, engine: engine({ parentID: "ses_touch_0001" }).reader });
    subject.pathTouched("ses_touch_child", "child.txt");
    await subject.settled();
    subject.pathTouched("ses_touch_child", "later.txt");
    // Deleted: forgotten.
    subject.sessionEnded("ses_touch_0001");
    subject.pathTouched("ses_touch_0001", "after.txt");
    await subject.settled();
    expect(archiver.touched).toEqual([
      "record ses_touch_0001 brief.pdf",
      "record ses_touch_0001 out/render.png",
      "record ses_touch_child child.txt",
      "forget ses_touch_child",
    ]);
    // Signed out: nothing.
    await subject.signOut();
    subject.pathTouched("ses_touch_0001", "signed-out.txt");
    expect(archiver.touched).toHaveLength(4);
  });

  test("a touched-files base is taken soon after the first touched path, not at the turn's end", async () => {
    const archiver = new FakeArchiver();
    archiver.base = async () => skipped("unchanged");
    archiver.baseDue = true;
    archiver.final = async () => queued("base");
    const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 10 });
    const root = await tempDir("root");
    subject.sessionStarted({ sessionId: "ses_touch_0003", root, engine: engine().reader });
    await subject.settled();
    subject.pathTouched("ses_touch_0003", "a.py");
    subject.pathTouched("ses_touch_0003", "b.py");
    await new Promise((resolve) => setTimeout(resolve, 40));
    await subject.settled();
    // One ask per session and run, though two paths came.
    expect(archiver.finals()).toEqual(["final ses_touch_0003 first_touch"]);
    // A chain that has its base (a git or project folder, or a base taken since): no extra capture.
    archiver.baseDue = false;
    subject.sessionStarted({ sessionId: "ses_touch_0004", root, engine: engine().reader });
    await subject.settled();
    subject.pathTouched("ses_touch_0004", "c.py");
    await new Promise((resolve) => setTimeout(resolve, 40));
    await subject.settled();
    expect(archiver.finals()).toEqual(["final ses_touch_0003 first_touch"]);
  });

  test("a path touched while the start is unresolved gets one base, timed from that touch", async () => {
    const archiver = new FakeArchiver();
    archiver.base = async () => skipped("unchanged");
    archiver.baseDue = true;
    archiver.final = async () => queued("base");
    let clock = 1_000;
    const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 30, now: () => clock });
    const root = await tempDir("root");
    let release: () => void = () => {};
    const slow = new Promise<void>((resolve) => { release = resolve; });
    subject.sessionStarted({ sessionId: "ses_touch_0005", root, engine: engine({ session: async () => { await slow; return { id: "ses_touch_0005" }; } }).reader });
    // Exactly one touch while the engine read is pending: no root yet.
    subject.pathTouched("ses_touch_0005", "early.py");
    // Resolution comes after the base delay has already passed since that touch.
    clock += 30;
    release();
    await subject.settled();
    await new Promise((resolve) => setTimeout(resolve, 20));
    await subject.settled();
    expect(archiver.finals()).toEqual(["final ses_touch_0005 first_touch"]);
  });

  test("a stop or a deletion while the touched-files base is being asked for captures nothing late", async () => {
    for (const end of ["stop", "deleted"] as const) {
      const archiver = new FakeArchiver();
      archiver.base = async () => skipped("unchanged");
      archiver.final = async () => queued("base");
      const sessionId = end === "stop" ? "ses_touch_0006" : "ses_touch_0007";
      const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 5 });
      let answer: (due: boolean) => void = () => {};
      let asked = false;
      archiver.touchedBaseDue = () => { asked = true; return new Promise<boolean>((resolve) => { answer = resolve; }); };
      const root = await tempDir("root");
      subject.sessionStarted({ sessionId, root, engine: engine().reader });
      await subject.settled();
      subject.pathTouched(sessionId, "a.py");
      await new Promise((resolve) => setTimeout(resolve, 20));
      expect(asked).toBe(true);
      if (end === "stop") await subject.stop({ finals: false });
      else subject.sessionEnded(sessionId);
      answer(true);
      await subject.settled();
      expect(archiver.finals().filter((call) => call.endsWith("first_touch"))).toEqual([]);
    }
  });

  test("delta turn numbers come from the engine's completed turns, in order after the base", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const baseGate = deferred<CaptureResult>();
    archiver.base = () => baseGate.promise;
    subject.sessionStarted({ sessionId: "ses_turns_0001", root, engine: engine({ messages: () => messages(0, true) }).reader });
    // The turn ends while the base is still packing: its delta waits for the base.
    subject.turnCompleted("ses_turns_0001", messages(1));
    subject.turnCompleted("ses_turns_0001", messages(2));
    // Unreadable messages still get their delta, with no turn: the archiver numbers it after the last one.
    subject.turnCompleted("ses_turns_0001", null);
    // Unknown sessions (never started in this app run) are left alone.
    subject.turnCompleted("ses_unknown_0001", messages(4));
    baseGate.resolve(queued("base"));
    await subject.settled();

    expect(archiver.captures()).toEqual([
      `base ses_turns_0001 ${root} 0`,
      `delta ses_turns_0001 ${root} 1`,
      `delta ses_turns_0001 ${root} 2`,
      `delta ses_turns_0001 ${root} null`,
    ]);
  });

  test("a prompt right after a turn ended waits for the observer's settle and that turn's delta, then goes out", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const reads = engine({ messages: () => messages(0) });
    subject.sessionStarted({ sessionId: "ses_gate_0001", root, engine: reads.reader });
    await subject.settled();
    const order: string[] = [];
    archiver.delta = async (_sessionId, turn) => { order.push(`delta ${turn}`); return queued("delta", turn ?? 0); };
    // Turn 1 ended in the engine; the next prompt comes before the observer settled it.
    const gate = subject.startGate("ses_gate_0001", root, { previousEnded: true }).then(() => order.push("prompt"));
    await Bun.sleep(30);
    expect(order).toEqual([]);
    subject.turnCompleted("ses_gate_0001", messages(1), 1_000);
    await gate;
    expect(order).toEqual(["delta 1", "prompt"]);
    // The turn before is archived now: the next gate waits for nothing and reads nothing.
    const before = { ...reads.reads };
    const started = Date.now();
    await subject.startGate("ses_gate_0001", root, { previousEnded: true });
    expect(Date.now() - started).toBeLessThan(50);
    expect(reads.reads).toEqual(before);
    expect(archiver.captures()).toEqual([`base ses_gate_0001 ${root} 0`, `delta ses_gate_0001 ${root} 1`]);
  });

  test("a prompt into a running turn, or a first prompt, waits for nothing", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const started = Date.now();
    await subject.startGate("ses_gate_0002", root, { previousEnded: true });
    subject.sessionStarted({ sessionId: "ses_gate_0002", root, engine: engine({ messages: () => messages(0) }).reader });
    await subject.settled();
    await subject.startGate("ses_gate_0002", root, { previousEnded: false });
    await subject.startGate("ses_gate_0002", root);
    expect(Date.now() - started).toBeLessThan(200);
  });

  test("the wait ends after turnDeltaWaitMs; a delta that runs after the next prompt went out is cut at that prompt", async () => {
    const archiver = new FakeArchiver();
    let clock = 10_000;
    const { subject, logs } = lifecycle(archiver, { turnDeltaWaitMs: 100, now: () => clock });
    const root = await tempDir("root");
    const reads = engine({ messages: () => messages(0) });
    subject.sessionStarted({ sessionId: "ses_gate_0003", root, engine: reads.reader });
    await subject.settled();
    const cuts: Array<number | undefined> = [];
    const deltaGate = deferred<CaptureResult>();
    archiver.delta = () => deltaGate.promise;
    const capture = archiver.captureDelta.bind(archiver);
    archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
      const result = await capture(sessionId, root2, turn, options);
      // The archiver reads the cut when its scan ends: here, once the capture finished.
      cuts.push(typeof options.before === "function" ? options.before() : options.before);
      return result;
    };
    // Turn 1 went idle at 10_500 and settled; its delta is slow. The next prompt waits 100 ms, then goes out at 11_000.
    clock = 10_600;
    subject.turnCompleted("ses_gate_0003", messages(1), 10_500);
    const started = Date.now();
    await subject.startGate("ses_gate_0003", root, { previousEnded: true });
    expect(Date.now() - started).toBeLessThan(1_000);
    expect(logs.some((line) => line.message.includes("cut at the prompt"))).toBe(true);
    clock = 11_000;
    subject.sessionStarted({ sessionId: "ses_gate_0003", root, engine: reads.reader });
    deltaGate.resolve(queued("delta", 1));
    await subject.settled();
    // The delta read its cut when it ran: the prompt at 11_000, the first one after the turn went idle.
    expect(cuts).toEqual([11_000]);
  });

  test("a turn the next prompt cut before the observer saw it end: the delta is cut at the first prompt after the turn's own", async () => {
    const archiver = new FakeArchiver();
    let clock = 1_000;
    const { subject } = lifecycle(archiver, { now: () => clock });
    const root = await tempDir("root");
    const turn1 = [
      { info: { id: "user_1", role: "user", time: { created: 1_010 } }, parts: [] },
      { info: { id: "assistant_1", role: "assistant", time: { created: 1_020, completed: 1_500 }, finish: "stop" }, parts: [] },
    ];
    const reads = engine({ messages: () => [] });
    subject.sessionStarted({ sessionId: "ses_gate_0005", root, engine: reads.reader });
    await subject.settled();
    const cuts: Array<number | undefined> = [];
    const deltaGate = deferred<CaptureResult>();
    archiver.delta = () => deltaGate.promise;
    const capture = archiver.captureDelta.bind(archiver);
    archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
      const result = await capture(sessionId, root2, turn, options);
      cuts.push(typeof options.before === "function" ? options.before() : options.before);
      return result;
    };
    // No idle time (the observer saw the turn cut by the next prompt); the next prompt went out at 1_600.
    clock = 1_550;
    subject.turnCompleted("ses_gate_0005", turn1, null);
    clock = 1_600;
    subject.sessionStarted({ sessionId: "ses_gate_0005", root, engine: reads.reader });
    deltaGate.resolve(queued("delta", 1));
    await subject.settled();
    expect(cuts).toEqual([1_600]);
  });

  test("the cut skips a prompt sent while the turn still answered, and falls back to the idle time for a turn opened before this run", async () => {
    const cutFor = async (turn: Message[], promptsAt: number[], idleAt: number | null) => {
      const archiver = new FakeArchiver();
      let clock = promptsAt[0]!;
      const { subject } = lifecycle(archiver, { now: () => clock });
      const root = await tempDir("root");
      const reads = engine({ messages: () => [] });
      subject.sessionStarted({ sessionId: "ses_gate_0006", root, engine: reads.reader });
      await subject.settled();
      const cuts: Array<number | undefined> = [];
      const deltaGate = deferred<CaptureResult>();
      archiver.delta = () => deltaGate.promise;
      const capture = archiver.captureDelta.bind(archiver);
      archiver.captureDelta = async (sessionId, root2, number, options = {}) => {
        const result = await capture(sessionId, root2, number, options);
        cuts.push(typeof options.before === "function" ? options.before() : options.before);
        return result;
      };
      subject.turnCompleted("ses_gate_0006", turn, idleAt);
      for (const at of promptsAt.slice(1)) {
        clock = at;
        subject.sessionStarted({ sessionId: "ses_gate_0006", root, engine: reads.reader });
      }
      deltaGate.resolve(queued("delta", 1));
      await subject.settled();
      return cuts[0];
    };
    const steered = [
      { info: { id: "user_1", role: "user", time: { created: 1_010 } }, parts: [] },
      { info: { id: "assistant_1", role: "assistant", time: { created: 1_020, completed: 1_300 }, finish: "tool-calls" }, parts: [] },
      // Sent at 1_200 while the turn still answered: a steer, part of turn 1.
      { info: { id: "user_2", role: "user", time: { created: 1_205 } }, parts: [] },
      { info: { id: "assistant_2", role: "assistant", time: { created: 1_310, completed: 1_500 }, finish: "stop" }, parts: [] },
    ];
    // Prompts went out at 1_000 (turn 1), 1_200 (the steer) and 1_600 (the next turn): the cut is 1_600.
    expect(await cutFor(steered, [1_000, 1_200, 1_600], null)).toBe(1_600);
    // A turn opened before this run (its prompt is older than every prompt time here): the idle time decides.
    const older = [
      { info: { id: "user_1", role: "user", time: { created: 500 } }, parts: [] },
      { info: { id: "assistant_1", role: "assistant", time: { created: 510, completed: 900 }, finish: "stop" }, parts: [] },
    ];
    expect(await cutFor(older, [1_000, 2_000], 1_500)).toBe(2_000);
    expect(await cutFor(older, [1_000, 2_000], null)).toBeUndefined();
  });

  test("a delta that runs before the next prompt has no cut; an aborted prompt still gets its final archive", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const reads = engine({ messages: () => messages(1) });
    subject.sessionStarted({ sessionId: "ses_gate_0004", root, engine: reads.reader });
    await subject.settled();
    const cuts: Array<number | undefined> = [];
    const capture = archiver.captureDelta.bind(archiver);
    archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
      const result = await capture(sessionId, root2, turn, options);
      // The archiver reads the cut when its scan ends: here, once the capture finished.
      cuts.push(typeof options.before === "function" ? options.before() : options.before);
      return result;
    };
    subject.turnCompleted("ses_gate_0004", messages(1), Date.now());
    await subject.settled();
    await subject.startGate("ses_gate_0004", root, { previousEnded: true });
    subject.sessionStarted({ sessionId: "ses_gate_0004", root, engine: reads.reader });
    // The prompt is stopped before any answer: the count did not move, so the archiver answers stale_turn and a final follows.
    archiver.delta = async () => skipped("stale_turn");
    subject.turnCompleted("ses_gate_0004", messages(1), Date.now());
    await subject.settled();
    expect(cuts).toEqual([undefined, undefined]);
    expect(archiver.finals()).toEqual(["final ses_gate_0004 turn_incomplete"]);
  });

  test("after a restart, a resumed session continues from the engine's turn count", async () => {
    const archiver = new FakeArchiver();
    const root = await tempDir("root");
    // The first app run archived turns 0 to 3 of this session; the archiver's state says so.
    archiver.base = async () => skipped("exists");
    const { subject } = lifecycle(archiver);
    subject.start();
    subject.sessionStarted({ sessionId: "ses_resumed_0001", root, engine: engine({ messages: () => messages(3, true) }).reader });
    subject.turnCompleted("ses_resumed_0001", messages(4));
    await subject.settled();
    expect(archiver.calls).toEqual(["drain", `base ses_resumed_0001 ${root} 3`, `delta ses_resumed_0001 ${root} 4`, "drain"]);
  });

  test("without an account the queue a previous run left waits for it (a refused refresh never clears it) and nothing is captured", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver, { enabled: false, accountMissing: true });
    subject.start();
    const root = await tempDir("root");
    subject.sessionStarted({ sessionId: "ses_retired_0001", root, engine: engine().reader });
    subject.turnCompleted("ses_retired_0001", messages(1));
    await subject.settled();
    expect(archiver.calls).toEqual([]);
  });

  test("with an account, start first claims the queue for it, then drains", async () => {
    const archiver = new FakeArchiver();
    const calls = archiver.calls;
    const claiming = Object.assign(archiver, { claimAccount: async () => { calls.push("claim"); } });
    const { subject } = lifecycle(claiming);
    subject.start();
    await subject.settled();
    expect(calls.slice(0, 2)).toEqual(["claim", "drain"]);
  });

  test("with archiving turned off on this device start clears what a previous run left and nothing is captured", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver, { enabled: false });
    subject.start();
    const root = await tempDir("root");
    subject.sessionStarted({ sessionId: "ses_signed_out_01", root, engine: engine().reader });
    subject.turnCompleted("ses_signed_out_01", messages(1));
    subject.sessionEnded("ses_signed_out_01");
    await subject.settled();
    expect(archiver.calls).toEqual(["signOut"]);
  });

  test("sign-out stops the archiver: queued steps never run and nothing is captured or uploaded afterwards", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const first = deferred<CaptureResult>();
    archiver.base = (sessionId) => (sessionId === "ses_first_0001" ? first.promise : Promise.resolve(queued("base")));
    subject.sessionStarted({ sessionId: "ses_first_0001", root, engine: engine().reader });
    // One capture at a time: the second session waits behind the first.
    subject.sessionStarted({ sessionId: "ses_second_001", root, engine: engine().reader });
    await Bun.sleep(5);
    expect(archiver.captures()).toEqual([`base ses_first_0001 ${root} 0`]);

    await subject.signOut();
    first.resolve(queued("base"));
    subject.sessionStarted({ sessionId: "ses_third_0001", root, engine: engine().reader });
    subject.turnCompleted("ses_first_0001", messages(1));
    subject.sessionEnded("ses_first_0001");
    await subject.settled();
    expect(archiver.calls).toEqual([`base ses_first_0001 ${root} 0`, "signOut"]);
  });

  test("428 (archive consent missing) turns archiving off quietly until the consent recheck", async () => {
    let now = 1_000;
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver, { now: () => now });
    const root = await tempDir("root");
    archiver.base = async () => skipped("disabled");
    subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
    await subject.settled();
    // Off: no capture, no consent check and no upload for any session.
    subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
    subject.sessionStarted({ sessionId: "ses_consent_002", root, engine: engine().reader });
    subject.turnCompleted("ses_consent_001", messages(1));
    subject.sessionEnded("ses_consent_003");
    await subject.settled();
    expect(archiver.calls).toEqual([`base ses_consent_001 ${root} 0`]);

    // Past the recheck time the session's next prompt checks consent again, which is now given.
    now += 60_001;
    archiver.base = async () => queued("base");
    subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine({ messages: () => messages(1, true) }).reader });
    await subject.settled();
    expect(archiver.calls.slice(1)).toEqual([`base ses_consent_001 ${root} 1`, "drain"]);

    // Consent withdrawn while uploading: the drain turns archiving off the same way.
    archiver.drainResult = async () => ({ ...drained, dropped: 1, disabled: true });
    subject.turnCompleted("ses_consent_001", messages(2));
    await subject.settled();
    subject.turnCompleted("ses_consent_001", messages(3));
    subject.sessionStarted({ sessionId: "ses_consent_004", root, engine: engine().reader });
    await subject.settled();
    expect(archiver.calls.slice(3)).toEqual([`delta ses_consent_001 ${root} 2`, "drain"]);
    expect(logs).toEqual([]);
  });

  test("failures never reach the caller: one warn line each, and archiving carries on", async () => {
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver);
    const root = await tempDir("root");
    archiver.base = async (sessionId) => {
      if (sessionId === "ses_throws_0001") throw new Error("disk full");
      return queued("base");
    };
    archiver.drainResult = async () => { throw new Error("drain exploded"); };
    subject.sessionStarted({ sessionId: "ses_throws_0001", root, engine: engine().reader });
    // The engine could not be read: skipped now, tried again on the next prompt.
    let engineUp = false;
    const flaky = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_flaky_00001" }; } });
    subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
    // A root that no longer exists is not archivable; nothing to warn about.
    subject.sessionStarted({ sessionId: "ses_gone_000001", root: join(root, "missing"), engine: engine().reader });
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_throws_0001 ${root} 0`]);
    expect(logs.map((log) => [log.level, log.message, log.attributes?.step ?? log.attributes?.reason])).toEqual([
      ["warn", "OmniRush project archive step failed", "base"],
      ["warn", "OmniRush project archive could not read the engine for a session; its next prompt or turn tries again", "the engine session could not be read"],
    ]);

    engineUp = true;
    subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
    await subject.settled();
    expect(archiver.captures().at(-1)).toBe(`base ses_flaky_00001 ${root} 0`);
    expect(logs.at(-1)).toMatchObject({ level: "warn", message: "OmniRush project archive step failed", attributes: { step: "drain", error: "Error: drain exploded" } });
    // Resolved once: later prompts do not read the engine again.
    subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
    await subject.settled();
    expect(flaky.reads).toEqual({ session: 2, messages: 1 });
  });

  test("after a restart the engine can still be starting: the session is resolved when its turn completes, and the turn's delta is not lost", async () => {
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver);
    const root = await tempDir("root");
    // The previous app run archived the base and turns 1 to 7.
    archiver.base = async () => skipped("exists");
    let engineUp = false;
    const slow = engine({
      session: () => {
        if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
        return { id: "ses_restart_0001" };
      },
      messages: () => messages(7, true),
    });
    subject.start();
    subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
    await subject.settled();
    expect(archiver.captures()).toEqual([]);
    expect(logs.map((log) => log.attributes?.reason)).toEqual(["the engine session could not be read"]);

    // The engine came up and ran turn 8; the observer read its messages.
    engineUp = true;
    subject.turnCompleted("ses_restart_0001", messages(8));
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_restart_0001 ${root} 8`, `delta ses_restart_0001 ${root} 8`]);
    // The observer's messages give the count: the message list is not read again.
    expect(slow.reads).toEqual({ session: 2, messages: 0 });

    // Resolved: the next turn is an ordinary delta, with no engine read.
    subject.turnCompleted("ses_restart_0001", messages(9));
    subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
    await subject.settled();
    expect(archiver.captures().slice(2)).toEqual([`delta ses_restart_0001 ${root} 9`]);
    expect(slow.reads).toEqual({ session: 2, messages: 0 });
  });

  test("a base whose folder policy could not be asked is tried again at the next turn, not skipped for the session", async () => {
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver);
    const root = await tempDir("root");
    const outage: CaptureResult = { status: "skipped", reason: "unavailable", detail: "policy_unavailable" };
    let serverUp = false;
    archiver.base = async () => (serverUp ? queued("base") : outage);
    subject.sessionStarted({ sessionId: "ses_policy_0001", root, engine: engine().reader });
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_policy_0001 ${root} 0`]);
    expect(logs.map((log) => log.attributes?.reason)).toEqual(["the folder policy could not be asked"]);
    // The server answers again by the turn's end: the base is taken then, the turn's delta after it.
    serverUp = true;
    subject.turnCompleted("ses_policy_0001", messages(1));
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_policy_0001 ${root} 0`, `base ses_policy_0001 ${root} 1`, `delta ses_policy_0001 ${root} 1`]);
    await subject.stop({ finals: false });
  });

  test("a path touched while the folder policy is unavailable gets its base once the policy answers", async () => {
    const archiver = new FakeArchiver();
    archiver.baseDue = true;
    archiver.final = async () => queued("base");
    const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 10 });
    const root = await tempDir("root");
    const outage: CaptureResult = { status: "skipped", reason: "unavailable", detail: "policy_unavailable" };
    let serverUp = false;
    archiver.base = async () => (serverUp ? skipped("unchanged") : outage);
    subject.sessionStarted({ sessionId: "ses_policy_0003", root, engine: engine().reader });
    await subject.settled();
    subject.pathTouched("ses_policy_0003", "a.py");
    // The delay passes while the base is still unresolved: nothing is asked yet.
    await new Promise((resolve) => setTimeout(resolve, 30));
    await subject.settled();
    expect(archiver.finals()).toEqual([]);
    // The policy answers at the next turn: the base resolves, then the touched-files base follows at once.
    serverUp = true;
    subject.turnCompleted("ses_policy_0003", messages(1));
    await subject.settled();
    await new Promise((resolve) => setTimeout(resolve, 20));
    await subject.settled();
    expect(archiver.finals()).toEqual(["final ses_policy_0003 first_touch"]);
    await subject.stop({ finals: false });
  });

  test("a folder policy that is really off still ends the session's archiving: no base asked again", async () => {
    const archiver = new FakeArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    archiver.base = async () => ({ status: "skipped", reason: "not_archivable", detail: "no_git_folder_policy_off" });
    subject.sessionStarted({ sessionId: "ses_policy_0002", root, engine: engine().reader });
    await subject.settled();
    subject.turnCompleted("ses_policy_0002", messages(1));
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_policy_0002 ${root} 0`]);
    await subject.stop({ finals: false });
  });

  test("a session still unreadable when its turn completes stays pending; a child resolved at turn end is never archived", async () => {
    const archiver = new FakeArchiver();
    const { subject, logs } = lifecycle(archiver);
    const root = await tempDir("root");
    let engineUp = false;
    const down = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_down_000001" }; } });
    subject.sessionStarted({ sessionId: "ses_down_000001", root, engine: down.reader });
    subject.turnCompleted("ses_down_000001", messages(1));
    await subject.settled();
    expect(archiver.captures()).toEqual([]);
    expect(logs).toHaveLength(2);
    // The changes are not lost: the first turn that can resolve the session captures the folder.
    engineUp = true;
    subject.turnCompleted("ses_down_000001", messages(2));
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_down_000001 ${root} 2`, `delta ses_down_000001 ${root} 2`]);

    let childUp = false;
    const child = engine({ session: () => { if (!childUp) throw new Error("ECONNREFUSED"); return { id: "ses_child_0003", parentID: "ses_down_000001" }; } });
    subject.sessionStarted({ sessionId: "ses_child_0003", root, engine: child.reader });
    await subject.settled();
    childUp = true;
    subject.turnCompleted("ses_child_0003", messages(1));
    subject.turnCompleted("ses_child_0003", messages(2));
    await subject.settled();
    expect(archiver.captures()).toHaveLength(2);
    expect(child.reads).toEqual({ session: 2, messages: 0 });
  });

  test("an engine too slow to answer at session start is read again a minute later, so a session whose first turn runs for hours still gets its base", async () => {
    jest.useFakeTimers();
    try {
      const archiver = new FakeArchiver();
      const { subject, logs } = lifecycle(archiver);
      const root = await tempDir("root");
      let engineUp = false;
      const slow = engine({
        session: () => {
          if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
          return { id: "ses_retried_0001" };
        },
        messages: () => messages(2, true),
      });
      subject.sessionStarted({ sessionId: "ses_retried_0001", root, engine: slow.reader });
      await subject.settled();
      expect(archiver.captures()).toEqual([]);
      expect(logs.map((log) => [log.attributes?.reason, log.attributes?.retryInMs])).toEqual([["the engine session could not be read", 60_000]]);

      // The engine answers by the time the retry runs, with the first turn of this app run still going.
      engineUp = true;
      jest.advanceTimersByTime(59_999);
      await subject.settled();
      expect(slow.reads.session).toBe(1);
      jest.advanceTimersByTime(1);
      await subject.settled();
      expect(archiver.captures()).toEqual([`base ses_retried_0001 ${root} 2`]);
      // Resolved: no further retry, and the turn's delta follows the base.
      jest.advanceTimersByTime(60 * 60_000);
      subject.turnCompleted("ses_retried_0001", messages(3));
      await subject.settled();
      expect(archiver.captures()).toEqual([`base ses_retried_0001 ${root} 2`, `delta ses_retried_0001 ${root} 3`]);
      expect(slow.reads).toEqual({ session: 2, messages: 1 });
    } finally {
      jest.useRealTimers();
    }
  });

  test("an engine that stays unreadable is read again after 1, 2, 5 and 10 minutes, then at the session's next prompt or turn", async () => {
    jest.useFakeTimers();
    try {
      const archiver = new FakeArchiver();
      const { subject, logs } = lifecycle(archiver);
      const root = await tempDir("root");
      let engineUp = false;
      const down = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_down_retry_01" }; } });
      subject.sessionStarted({ sessionId: "ses_down_retry_01", root, engine: down.reader });
      await subject.settled();
      // A prompt while a retry is waiting reads the engine at once but does not add another retry.
      subject.sessionStarted({ sessionId: "ses_down_retry_01", root, engine: down.reader });
      await subject.settled();
      expect(down.reads.session).toBe(2);
      for (const minutes of [1, 2, 5, 10]) {
        const reads = down.reads.session;
        jest.advanceTimersByTime(minutes * 60_000 - 1);
        await subject.settled();
        expect(down.reads.session).toBe(reads);
        jest.advanceTimersByTime(1);
        await subject.settled();
        expect(down.reads.session).toBe(reads + 1);
      }
      jest.advanceTimersByTime(24 * 60 * 60_000);
      await subject.settled();
      expect(down.reads.session).toBe(6);
      expect(logs.map((log) => log.attributes?.retryInMs)).toEqual([60_000, undefined, 120_000, 300_000, 600_000, undefined]);

      // Past the retries, the next completed turn still resolves it.
      engineUp = true;
      subject.turnCompleted("ses_down_retry_01", messages(1));
      await subject.settled();
      expect(archiver.captures()).toEqual([`base ses_down_retry_01 ${root} 1`, `delta ses_down_retry_01 ${root} 1`]);

      // A retry never runs once archiving stopped.
      const stopped = engine({ session: () => { throw new Error("ECONNREFUSED"); } });
      subject.sessionStarted({ sessionId: "ses_stopped_0001", root, engine: stopped.reader });
      await subject.settled();
      await subject.stop();
      jest.advanceTimersByTime(60_000);
      await subject.settled();
      expect(stopped.reads.session).toBe(1);
    } finally {
      jest.useRealTimers();
    }
  });

  test("with the real archiver: base at session start, a delta per changed turn, and the next app run resumes the upload", async () => {
    const server = new FakeArchiveServer();
    const root = await tempDir("project");
    const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
    await git("init", "-q", "-b", "main");
    await writeFile(join(root, "app.ts"), "export const app = 1;\n");
    await git("add", "app.ts");
    await git("commit", "-q", "-m", "initial");
    const state = await tempDir("state");
    const archiverFor = (now?: () => Date) => new SessionArchiver({
      gatewayUrl: server.gatewayUrl,
      accessToken: server.token,
      fetch: server.respond,
      stateDir: state,
      retry: { baseMs: 1, maxMs: 2, attempts: 2 },
      ...(now ? { now } : {}),
    });

    const first = lifecycle(archiverFor());
    first.subject.start();
    first.subject.sessionStarted({ sessionId: "ses_real_000001", root, engine: engine({ messages: () => messages(0, true) }).reader });
    await first.subject.settled();
    // Nothing changed during turn 1: no delta.
    first.subject.turnCompleted("ses_real_000001", messages(1));
    await first.subject.settled();
    expect(server.objects().map((archive) => [archive.request.kind, archive.request.turn])).toEqual([["base", 0]]);

    // Turn 2 changes the folder, but S3 is unreachable until the app restarts.
    await mkdir(join(root, "src"));
    await writeFile(join(root, "src/feature.ts"), "export const feature = true;\n");
    server.putHook = () => "network";
    first.subject.turnCompleted("ses_real_000001", messages(2));
    await first.subject.settled();
    await first.subject.stop();
    expect(server.objects()).toHaveLength(1);

    // The next app run, after the failed job's backoff.
    server.putHook = null;
    const later = new Date(Date.now() + 2 * 60_000);
    const second = lifecycle(archiverFor(() => later));
    second.subject.start();
    await second.subject.settled();
    const archives = server.objects();
    expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 2]]);
    const delta = await openArchive(archives[1]!.object!);
    expect(delta.map((member) => member.name)).toContain("src/feature.ts");
    expect(manifestOf(delta)).toMatchObject({ kind: "delta", turn: 2 });
    expect([...first.logs, ...second.logs].filter((log) => log.level === "warn" && !log.message.includes("deferred"))).toEqual([]);
  });

  test("with the real archiver: after an app restart whose engine is still starting, the first turn's change is archived with its turn", async () => {
    const server = new FakeArchiveServer();
    const root = await tempDir("project");
    const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
    await git("init", "-q", "-b", "main");
    await writeFile(join(root, "app.ts"), "export const app = 1;\n");
    await git("add", "app.ts");
    await git("commit", "-q", "-m", "initial");
    const state = await tempDir("state");
    const archiverFor = () => new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir: state, retry: { baseMs: 1, maxMs: 2, attempts: 2 } });

    const first = lifecycle(archiverFor());
    first.subject.start();
    first.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: engine({ messages: () => messages(0, true) }).reader });
    await first.subject.settled();
    await writeFile(join(root, "after.txt"), "after restart\n");
    first.subject.turnCompleted("ses_restarted_01", messages(1));
    await first.subject.settled();
    await first.subject.stop();

    // The next app run: the engine does not answer the session start's reads.
    const second = lifecycle(archiverFor());
    second.subject.start();
    let engineUp = false;
    const reads = engine({
      session: () => {
        if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
        return { id: "ses_restarted_01" };
      },
      messages: () => messages(1, true),
    });
    second.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: reads.reader });
    await second.subject.settled();
    engineUp = true;
    await writeFile(join(root, "after.txt"), "after restart 2\n");
    second.subject.turnCompleted("ses_restarted_01", messages(2));
    await second.subject.settled();

    // A turn whose messages the observer could not read follows the last archived turn.
    await writeFile(join(root, "after.txt"), "unread turn\n");
    second.subject.turnCompleted("ses_restarted_01", null);
    await second.subject.settled();

    const archives = server.objects();
    expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 1], ["delta", 2, 2], ["delta", 3, 3]]);
    const latest = await openArchive(archives[2]!.object!);
    expect(latest.find((member) => member.name === "after.txt")!.content.toString()).toBe("after restart 2\n");
    expect(manifestOf(latest)).toMatchObject({ kind: "delta", turn: 2 });
    expect(manifestOf(await openArchive(archives[3]!.object!))).toMatchObject({ kind: "delta", turn: 3 });
  });
});

describe("ProjectArchiveLifecycle base quiet period", () => {
  const sleep = (ms: number) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));

  function deferring(archiver: ProjectArchiver, baseIdleMs: number, baseMaxDeferMs: number) {
    return new ProjectArchiveLifecycle({ archiver, enabled: true, log: () => undefined, consentRecheckMs: 60_000, baseIdleMs, baseMaxDeferMs });
  }

  test("bases wait until no prompt has been dispatched for baseIdleMs", async () => {
    const archiver = new FakeArchiver();
    const packedAt = new Map<string, number>();
    archiver.base = async (sessionId) => {
      packedAt.set(sessionId, Date.now());
      return queued("base");
    };
    const subject = deferring(archiver, 300, 5_000);
    const [first, second] = [await tempDir("first"), await tempDir("second")];
    subject.sessionStarted({ sessionId: "ses_first_00001", root: first, engine: engine().reader });
    await sleep(200);
    const lastPromptAt = Date.now();
    subject.sessionStarted({ sessionId: "ses_second_0001", root: second, engine: engine().reader });
    await sleep(200);
    // The first prompt is 400 ms old, but the second only 200 ms: nothing packed yet.
    expect(archiver.captures()).toEqual([]);
    await subject.settled();
    expect(archiver.captures().map((call) => call.split(" ")[1]).sort()).toEqual(["ses_first_00001", "ses_second_0001"]);
    for (const at of packedAt.values()) expect(at - lastPromptAt).toBeGreaterThanOrEqual(290);
  });

  test("a steady stream of prompts delays a base by at most baseMaxDeferMs", async () => {
    const archiver = new FakeArchiver();
    let packedAt = 0;
    archiver.base = async () => {
      packedAt = Date.now();
      return queued("base");
    };
    const subject = deferring(archiver, 200, 600);
    const startedAt = Date.now();
    subject.sessionStarted({ sessionId: "ses_busy_000001", root: await tempDir("busy"), engine: engine().reader });
    const other = await tempDir("other");
    for (let prompt = 0; prompt < 10 && packedAt === 0; prompt += 1) {
      await sleep(100);
      subject.sessionStarted({ sessionId: "ses_other_00001", root: other, engine: engine().reader });
    }
    await subject.settled();
    expect(packedAt - startedAt).toBeGreaterThanOrEqual(590);
    expect(packedAt - startedAt).toBeLessThan(1_000);
  });

  test("stop and sign-out end the wait without packing", async () => {
    for (const end of ["stop", "signOut"] as const) {
      const archiver = new FakeArchiver();
      const subject = deferring(archiver, 60_000, 120_000);
      subject.sessionStarted({ sessionId: "ses_waiting_0001", root: await tempDir("waiting"), engine: engine().reader });
      await sleep(50);
      const endedAt = Date.now();
      await subject[end]();
      await subject.settled();
      expect(Date.now() - endedAt).toBeLessThan(1_000);
      expect(archiver.captures()).toEqual([]);
    }
  });
});

describe("ProjectArchiveLifecycle final archives", () => {
  const sleep = (ms: number) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));

  /** Turn deltas numbered like the real archiver: a count that did not move is stale. */
  function turnArchiver(): FakeArchiver {
    const archiver = new FakeArchiver();
    const lastTurn = new Map<string, number>();
    archiver.base = async (sessionId, turn) => {
      lastTurn.set(sessionId, turn);
      return queued("base");
    };
    archiver.delta = async (sessionId, turn) => {
      const next = turn ?? (lastTurn.get(sessionId) ?? 0) + 1;
      if (next <= (lastTurn.get(sessionId) ?? -1)) return skipped("stale_turn");
      lastTurn.set(sessionId, next);
      return queued("delta", next);
    };
    return archiver;
  }

  test("a session quiet after its turn gets one idle final archive; a new prompt cancels the pending one", async () => {
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver, { finalIdleMs: 300 });
    const root = await tempDir("root");
    const reads = engine({ messages: () => messages(0, true) }).reader;
    subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
    await subject.settled();
    // The next prompt comes within the quiet window: no final archive.
    subject.turnCompleted("ses_idle_000001", messages(1));
    await sleep(30);
    subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
    await sleep(400);
    await subject.settled();
    expect(archiver.finals()).toEqual([]);

    // Turn 2 ends and nothing follows: one final archive, however long the quiet lasts.
    subject.turnCompleted("ses_idle_000001", messages(2));
    await sleep(400);
    await subject.settled();
    expect(archiver.finals()).toEqual(["final ses_idle_000001 idle"]);
    await sleep(400);
    await subject.settled();
    expect(archiver.finals()).toHaveLength(1);
    expect(archiver.captures()).toEqual([`base ses_idle_000001 ${root} 0`, `delta ses_idle_000001 ${root} 1`, `delta ses_idle_000001 ${root} 2`]);

    // A prompt while the idle final is packing cancels it.
    let signal: AbortSignal | undefined;
    archiver.final = (_sessionId, _reason, given) => new Promise((resolvePromise) => {
      signal = given;
      given?.addEventListener("abort", () => resolvePromise(skipped("cancelled")), { once: true });
    });
    subject.turnCompleted("ses_idle_000001", messages(3));
    await sleep(400);
    expect(archiver.finals()).toHaveLength(2);
    expect(signal?.aborted).toBe(false);
    subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
    await subject.settled();
    expect(signal?.aborted).toBe(true);
  });

  test("a turn the observer follows keeps the idle final archive off until it ends, even when its prompt came before the previous turn's end", async () => {
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver, { finalIdleMs: 100 });
    const root = await tempDir("root");
    const reads = engine().reader;
    subject.sessionStarted({ sessionId: "ses_followed_001", root, engine: reads });
    await subject.settled();
    // The next prompt went out while turn 1 settled: its session start comes first, then turn 1's end,
    // then the observer follows turn 2.
    subject.sessionStarted({ sessionId: "ses_followed_001", root, engine: reads });
    subject.turnCompleted("ses_followed_001", messages(1));
    subject.turnFollowed("ses_followed_001");
    await sleep(250);
    await subject.settled();
    expect(archiver.finals()).toEqual([]);
    // Turn 2 ends: its quiet window gets the idle final archive.
    subject.turnCompleted("ses_followed_001", messages(2));
    await sleep(250);
    await subject.settled();
    expect(archiver.finals()).toEqual(["final ses_followed_001 idle"]);
    expect(archiver.captures()).toEqual([`base ses_followed_001 ${root} 0`, `delta ses_followed_001 ${root} 1`, `delta ses_followed_001 ${root} 2`]);

    // An idle final already packing when a turn is followed is cancelled like one a prompt ends.
    let signal: AbortSignal | undefined;
    archiver.final = (_sessionId, _reason, given) => new Promise((resolvePromise) => {
      signal = given;
      given?.addEventListener("abort", () => resolvePromise(skipped("cancelled")), { once: true });
    });
    subject.turnCompleted("ses_followed_001", messages(3));
    await sleep(250);
    expect(signal?.aborted).toBe(false);
    subject.turnFollowed("ses_followed_001");
    await subject.settled();
    expect(signal?.aborted).toBe(true);
    // A session this run does not know is left alone.
    subject.turnFollowed("ses_unknown_0002");
    await subject.settled();
    expect(archiver.finals()).toHaveLength(2);
  });

  test("a session deleted, a sign-out and a shutdown clear both an idle final archive and an unresolved start's retry; neither runs afterwards", async () => {
    const root = await tempDir("root");
    jest.useFakeTimers();
    try {
      for (const end of ["sessionEnded", "signOut", "stop"] as const) {
        const archiver = turnArchiver();
        const { subject } = lifecycle(archiver);
        // One session's turn ended: its idle final archive waits for FINAL_IDLE_MS.
        subject.sessionStarted({ sessionId: "ses_timer_idle01", root, engine: engine().reader });
        await subject.settled();
        subject.turnCompleted("ses_timer_idle01", messages(1));
        await subject.settled();
        // Another's engine could not be read at its start: its retry waits a minute.
        const down = engine({ session: () => { throw new Error("ECONNREFUSED"); } });
        subject.sessionStarted({ sessionId: "ses_timer_retry1", root, engine: down.reader });
        await subject.settled();
        expect(jest.getTimerCount()).toBe(2);

        if (end === "sessionEnded") {
          subject.sessionEnded("ses_timer_idle01");
          subject.sessionEnded("ses_timer_retry1");
        } else if (end === "signOut") {
          await subject.signOut();
        } else {
          await subject.stop();
        }
        await subject.settled();
        expect(jest.getTimerCount()).toBe(0);
        jest.advanceTimersByTime(24 * 60 * 60_000);
        await subject.settled();
        expect(down.reads.session).toBe(1);
        // Only a deleted session gets its own (session_deleted) final archive; shutdown hands its finals to the archiver.
        expect(archiver.finals().sort()).toEqual(end === "sessionEnded"
          ? ["final ses_timer_idle01 session_deleted", "final ses_timer_retry1 session_deleted"]
          : []);
        expect(archiver.captures()).toEqual([`base ses_timer_idle01 ${root} 0`, `delta ses_timer_idle01 ${root} 1`]);
      }
    } finally {
      jest.useRealTimers();
    }
  });

  test("a start read still running when the session is deleted, at a sign-out or at shutdown arms no retry when it fails", async () => {
    const root = await tempDir("root");
    jest.useFakeTimers();
    try {
      for (const end of ["sessionEnded", "signOut", "stop"] as const) {
        const archiver = turnArchiver();
        const { subject, logs } = lifecycle(archiver);
        const read = deferred<unknown>();
        const slow = engine({ session: () => read.promise });
        subject.sessionStarted({ sessionId: "ses_inflight_001", root, engine: slow.reader });
        for (let tick = 0; tick < 100 && slow.reads.session === 0; tick += 1) await Promise.resolve();
        expect(slow.reads.session).toBe(1);
        if (end === "sessionEnded") subject.sessionEnded("ses_inflight_001");
        else if (end === "signOut") await subject.signOut();
        else await subject.stop();
        // The engine gives up only now.
        read.resolve(null);
        await subject.settled();
        expect(logs.filter((log) => log.attributes?.reason === "the engine session could not be read").map((log) => log.attributes?.retryInMs)).toEqual([undefined]);
        expect(jest.getTimerCount()).toBe(0);
        jest.advanceTimersByTime(24 * 60 * 60_000);
        await subject.settled();
        expect(slow.reads.session).toBe(1);
        expect(archiver.captures()).toEqual([]);
      }
    } finally {
      jest.useRealTimers();
    }
  });

  test("a turn that ends without completing: its delta when the engine's count moved, else a final archive", async () => {
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver, { finalIdleMs: 60_000 });
    const root = await tempDir("root");
    let count: number | null = 0;
    const reads = engine({ messages: () => (count === null ? Promise.reject(new Error("ECONNREFUSED")) : messages(count)) });
    subject.sessionStarted({ sessionId: "ses_abnormal_001", root, engine: reads.reader });
    await subject.settled();
    // The observer gave up (or failed) after the turn had completed in the engine.
    count = 1;
    subject.turnIncomplete("ses_abnormal_001");
    await subject.settled();
    // Aborted before any answer: the count did not move.
    subject.turnIncomplete("ses_abnormal_001");
    await subject.settled();
    // The engine went away: no count to go by.
    count = null;
    subject.turnIncomplete("ses_abnormal_001");
    await subject.settled();
    // A settled turn whose count did not move (a prompt aborted at once) is final too.
    subject.turnCompleted("ses_abnormal_001", messages(1, true));
    await subject.settled();
    expect(archiver.calls.filter((call) => call !== "drain")).toEqual([
      `base ses_abnormal_001 ${root} 0`,
      `delta ses_abnormal_001 ${root} 1`,
      `delta ses_abnormal_001 ${root} 1`,
      "final ses_abnormal_001 turn_incomplete",
      "final ses_abnormal_001 turn_incomplete",
      `delta ses_abnormal_001 ${root} 1`,
      "final ses_abnormal_001 turn_incomplete",
    ]);
    // Unknown sessions are left alone.
    subject.turnIncomplete("ses_unknown_0001");
    await subject.settled();
    expect(archiver.finals()).toHaveLength(3);
  });

  test("a deleted session gets a final archive before it is forgotten; a child never, an unknown one if the archiver has its base", async () => {
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    subject.sessionStarted({ sessionId: "ses_deleted_0001", root, engine: engine().reader });
    subject.sessionStarted({ sessionId: "ses_child_00001", root, engine: engine({ parentID: "ses_deleted_0001" }).reader });
    await subject.settled();
    subject.turnCompleted("ses_deleted_0001", messages(1));
    subject.sessionEnded("ses_deleted_0001");
    subject.sessionEnded("ses_child_00001");
    // A session this app run has not seen (the archiver answers no_base when it never had one).
    subject.sessionEnded("ses_earlier_0001");
    await subject.settled();
    expect(archiver.finals().sort()).toEqual(["final ses_deleted_0001 session_deleted", "final ses_earlier_0001 session_deleted"]);
    // Forgotten: its pending turn step was dropped, and later calls are ignored.
    subject.turnCompleted("ses_deleted_0001", messages(2));
    await subject.settled();
    expect(archiver.captures()).toEqual([`base ses_deleted_0001 ${root} 0`]);
  });

  test("shutdown hands this run's sessions to the archiver's final archives, most recent first, within the budget", async () => {
    let now = 1_000;
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver, { now: () => now });
    const root = await tempDir("root");
    subject.sessionStarted({ sessionId: "ses_quit_old_001", root, engine: engine().reader });
    now += 1_000;
    subject.sessionStarted({ sessionId: "ses_quit_new_001", root, engine: engine().reader });
    subject.sessionStarted({ sessionId: "ses_quit_child_1", root, engine: engine({ parentID: "ses_quit_new_001" }).reader });
    await subject.settled();
    now += 1_000;
    subject.turnCompleted("ses_quit_old_001", messages(1));
    await subject.settled();
    await subject.stop();
    expect(archiver.stops).toEqual([{ finals: ["ses_quit_old_001", "ses_quit_new_001"], budgetMs: 5_000 }]);

    // No budget, consent off, or the account gone (a user sign-out restarts the server): a plain stop.
    const noBudget = turnArchiver();
    const off = lifecycle(noBudget, { quitBudgetMs: 0 });
    off.subject.sessionStarted({ sessionId: "ses_quit_none_01", root, engine: engine().reader });
    await off.subject.settled();
    await off.subject.stop();
    const refused = turnArchiver();
    refused.base = async () => skipped("disabled");
    const consent = lifecycle(refused);
    consent.subject.sessionStarted({ sessionId: "ses_quit_none_02", root, engine: engine().reader });
    await consent.subject.settled();
    await consent.subject.stop();
    const gone = turnArchiver();
    const signedOut = lifecycle(gone);
    signedOut.subject.sessionStarted({ sessionId: "ses_quit_none_03", root, engine: engine().reader });
    await signedOut.subject.settled();
    await signedOut.subject.stop({ finals: false });
    expect([...noBudget.stops, ...refused.stops, ...gone.stops]).toEqual([{}, {}, {}]);
  });

  test("app start: the sessions the archiver names get a final archive, behind every other waiting step", async () => {
    const archiver = turnArchiver();
    const { subject } = lifecycle(archiver);
    const root = await tempDir("root");
    const first = deferred<CaptureResult>();
    archiver.base = (sessionId) => (sessionId === "ses_start_first1" ? first.promise : Promise.resolve(queued("base")));
    // A base is packing when the app-start check comes back.
    subject.sessionStarted({ sessionId: "ses_start_first1", root, engine: engine().reader });
    await sleep(10);
    expect(archiver.captures()).toEqual([`base ses_start_first1 ${root} 0`]);
    archiver.startFinals = ["ses_start_final1", "ses_start_final2"];
    subject.start();
    await sleep(10);
    subject.sessionStarted({ sessionId: "ses_start_next01", root, engine: engine().reader });
    first.resolve(queued("base"));
    await subject.settled();
    expect(archiver.calls.filter((call) => call !== "drain")).toEqual([
      `base ses_start_first1 ${root} 0`,
      `base ses_start_next01 ${root} 0`,
      "final ses_start_final1 app_start",
      "final ses_start_final2 app_start",
    ]);
  });

  test("with the real archiver: after the last turn, the folder is archived when the chat goes quiet, when the app quits and at the next start", async () => {
    const server = new FakeArchiveServer();
    const root = await tempDir("project");
    const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
    await git("init", "-q", "-b", "main");
    await writeFile(join(root, "app.ts"), "export const app = 1;\n");
    await git("add", "app.ts");
    await git("commit", "-q", "-m", "initial");
    const state = await tempDir("state");
    const archiverFor = () => new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir: state, retry: { baseMs: 1, maxMs: 2, attempts: 2 } });
    const id = "ses_final_real_1";

    const first = lifecycle(archiverFor(), { finalIdleMs: 100 });
    first.subject.start();
    first.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(0, true) }).reader });
    await first.subject.settled();
    await writeFile(join(root, "turn.txt"), "turn 1\n");
    first.subject.turnCompleted(id, messages(1));
    await first.subject.settled();
    // The user edits after the turn; the chat stays quiet.
    await writeFile(join(root, "idle.txt"), "after the turn\n");
    await sleep(200);
    await first.subject.settled();
    // More edits, then the app quits.
    await writeFile(join(root, "quit.txt"), "before quitting\n");
    await first.subject.stop();
    // And edits while it is closed.
    await writeFile(join(root, "closed.txt"), "while closed\n");

    const second = lifecycle(archiverFor());
    second.subject.start();
    await second.subject.settled();
    second.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(1, true) }).reader });
    await second.subject.settled();
    await writeFile(join(root, "turn.txt"), "turn 2\n");
    second.subject.turnCompleted(id, messages(2));
    await second.subject.settled();
    await second.subject.stop();

    const objects = server.objects();
    expect(objects.map((object) => [object.request.kind, object.request.sequence, object.request.turn])).toEqual([
      ["base", 0, 0], ["delta", 1, 1], ["delta", 2, 1], ["delta", 3, 1], ["delta", 4, 1], ["delta", 5, 2],
    ]);
    const manifests = await Promise.all(objects.map(async (object) => {
      const members = await openArchive(object.object!);
      return { manifest: manifestOf(members), names: members.slice(1).map((member) => member.name) };
    }));
    expect(manifests.slice(1).map(({ manifest }) => [manifest.trigger, manifest.reason])).toEqual([["turn", undefined], ["final", "idle"], ["final", "app_quit"], ["final", "app_start"], ["turn", undefined]]);
    expect(manifests[2]!.names).toContain("idle.txt");
    expect(manifests[3]!.names).toContain("quit.txt");
    expect(manifests[4]!.names).toContain("closed.txt");
    expect(manifests[5]!.names).toContain("turn.txt");
    expect([...first.logs, ...second.logs].filter((log) => log.level === "warn")).toEqual([]);
  });
});