Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
56.3 KB
Raw Blame
import { afterEach, describe, expect, test } from "bun:test";
import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { zstdDecompressSync } from "node:zlib";

import {
  createSessionObservers,
  engineReplaced,
  messageOutline,
  observeUploadedSession,
  projectArchiveEngineReads,
  promptDispatched,
  type EngineTarget,
  type ObservedUploader,
  type ObserverTiming,
  type SessionObservers,
  turnOutcome,
} from "./session-upload-observer.js";
import type { CaptureResult, DrainResult, FinalReason } from "./session-archive/index.js";
import { ProjectArchiveLifecycle, type ProjectArchiver } from "./session-archive/lifecycle.js";
import { SessionUploader, type UploadChildSession } from "./session-uploader.js";

/** Schema 1/2 trace uploads carry their events only in files[0] (__omnirush__/trace.json): read them back as `trace`. */
function withTraceEvents<T>(envelope: T): T {
  const record = envelope as Record<string, unknown>;
  if (record.trace !== undefined || !Array.isArray(record.files)) return envelope;
  const file = (record.files as Array<{ path?: string; content?: string }>).find((item) => item.path === "__omnirush__/trace.json");
  if (!file?.content) return envelope;
  return { ...record, trace: (JSON.parse(file.content) as { events?: unknown[] }).events ?? [] } as T;
}

/**
 * The turn observer against a fake engine, on a fake clock: a turn is
 * followed for as long as it runs (hours of it pass without real waiting), an
 * engine that does not answer is waited out, and messages a turn could not
 * flush go out with the next settled one, over several flushes when needed.
 */

const SESSION = "ses_observed_0001";
const HOUR = 60 * 60_000;
const MIB = 1024 * 1024;

const cleanups: Array<() => void | Promise<void>> = [];
afterEach(async () => {
  while (cleanups.length) await cleanups.pop()?.();
});

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

function message(id: string, role: "user" | "assistant", text = `${role} ${id}`): EngineMessage {
  return {
    info: {
      id,
      sessionID: SESSION,
      role,
      time: role === "assistant" ? { created: 1, completed: 2 } : { created: 1 },
      ...(role === "assistant" ? { providerID: "omnirush", modelID: "gpt-6-astra", mode: "build" } : {}),
    },
    parts: [{ id: `${id}_part`, messageID: id, sessionID: SESSION, type: "text", text }],
  };
}

/** A long answer: `mib` MiB of agent output. */
function longAnswer(id: string, mib: number): EngineMessage {
  return message(id, "assistant", "agent output line\n".repeat(Math.floor((mib * MIB) / 18)));
}

/** The engine's message paging (`?limit=&before=`): the newest `limit` messages before the cursor, oldest first. */
function messagePage(url: URL, list: EngineMessage[]): Response {
  const limit = Number(url.searchParams.get("limit") ?? 0);
  if (!limit) return Response.json(list);
  const end = url.searchParams.has("before") ? Number(url.searchParams.get("before")) : list.length;
  const start = Math.max(0, end - limit);
  return Response.json(list.slice(start, end), start > 0 ? { headers: { "X-Next-Cursor": String(start) } } : {});
}

/** A fake v1 engine holding one session: its status, its messages, and hooks on its reads. */
function startEngine() {
  const control = {
    status: (): string => "idle",
    messages: [] as EngineMessage[],
    /** Real milliseconds the next status reads take to answer, one entry per read. */
    statusDelaysMs: [] as number[],
    statusReads: 0,
    /** The Authorization header of every request. */
    authorizations: [] as string[],
    /** Runs once a page of messages was read. */
    onMessagesRead: null as (() => void) | null,
    /** The engine's /session/:id/children answers, by session id. */
    children: {} as Record<string, Array<{ id: string }>>,
    childrenReads: 0,
    /** POST /session/:id/abort requests; `onAbort` runs for each. */
    aborts: 0,
    onAbort: null as (() => void) | null,
  };
  const server = Bun.serve({
    hostname: "127.0.0.1",
    port: 0,
    async fetch(request) {
      const url = new URL(request.url);
      control.authorizations.push(request.headers.get("authorization") ?? "");
      if (url.pathname === "/session/status") {
        control.statusReads += 1;
        const delay = control.statusDelaysMs.shift();
        if (delay) await Bun.sleep(delay);
        const type = control.status();
        return Response.json(type === "idle" ? {} : { [SESSION]: { type } });
      }
      if (request.method === "POST" && url.pathname === `/session/${SESSION}/abort`) {
        control.aborts += 1;
        control.onAbort?.();
        return Response.json(true);
      }
      if (url.pathname === `/session/${SESSION}/message`) {
        const page = messagePage(url, control.messages);
        control.onMessagesRead?.();
        return page;
      }
      const childrenOf = /^\/session\/([^/]+)\/children$/.exec(url.pathname);
      if (childrenOf) {
        control.childrenReads += 1;
        const id = decodeURIComponent(childrenOf[1]!);
        return id === SESSION || id in control.children ? Response.json(control.children[id] ?? []) : Response.json({ code: "not_found" }, { status: 404 });
      }
      if (url.pathname === `/session/${SESSION}`) return Response.json({ id: SESSION });
      return Response.json({ code: "not_found" }, { status: 404 });
    },
  });
  cleanups.push(() => server.stop(true));
  const target: EngineTarget = { baseUrl: `http://127.0.0.1:${server.port}`, headers: [["authorization", "Basic ZW5naW5l"]], search: "", engine: "v1" };
  return { control, server, target };
}

/**
 * A clock that only moves when the observer waits: each wait passes at once,
 * adds its length to the time and runs whatever was scheduled up to then.
 */
function fakeClock() {
  const start = Date.parse("2026-09-23T07:34:00.000Z");
  let now = start;
  const scheduled: Array<{ at: number; run: () => void }> = [];
  const waits: number[] = [];
  const timing: Partial<ObserverTiming> = {
    now: () => now,
    sleep: async (ms, signal) => {
      if (signal.aborted) throw signal.reason;
      waits.push(ms);
      now += ms;
      for (const task of scheduled.filter((entry) => entry.at <= now)) {
        scheduled.splice(scheduled.indexOf(task), 1);
        task.run();
      }
      await new Promise((resolvePromise) => setImmediate(resolvePromise));
      if (signal.aborted) throw signal.reason;
    },
    // These cases follow a turn to its end only; a running turn's progress has its own (session-upload-observer-progress.test.ts).
    progressMs: 0,
  };
  return {
    timing,
    waits,
    elapsed: () => now - start,
    /** Runs `run` once the clock reaches `offsetMs` past its start. */
    at: (offsetMs: number, run: () => void) => { scheduled.push({ at: start + offsetMs, run }); },
  };
}

type Entry =
  | { kind: "trace"; type: string; data?: unknown }
  | { kind: "snapshot"; trigger: string; outcome?: string }
  | { kind: "flush"; final?: unknown };

/** Records what the observer hands the session uploader, in order. */
class FakeUploader implements ObservedUploader {
  readonly enabled = true;
  checkpoint: string | undefined;
  readonly entries: Entry[] = [];

  async sessionCheckpoint(): Promise<{ resumed: boolean; lastMessageId?: string }> {
    return { resumed: false, ...(this.checkpoint ? { lastMessageId: this.checkpoint } : {}) };
  }

  async setSessionCheckpoint(_sessionId: string, messageId: string): Promise<void> {
    this.checkpoint = messageId;
  }

  recordTrace(_sessionId: string, type: string, data?: unknown): void {
    this.entries.push({ kind: "trace", type, ...(data === undefined ? {} : { data }) });
  }

  recordSessionModel(): void {}

  async childCheckpoints(): Promise<Record<string, string>> {
    return {};
  }

  async childSessionIds(): Promise<string[]> {
    return [];
  }

  recordChildSession(_sessionId: string, _child: UploadChildSession): void {}

  /** Every batch of ids noted while a turn ran. */
  readonly notedChildIds: string[][] = [];

  noteChildSessionIds(_sessionId: string, ids: readonly string[]): number {
    this.notedChildIds.push([...ids]);
    return ids.length;
  }

  captureSnapshot(_sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void {
    this.entries.push({ kind: "snapshot", trigger, ...(outcome ? { outcome } : {}) });
  }

  flushTrace(_sessionId: string, finalTrace?: unknown): void {
    this.entries.push({ kind: "flush", ...(finalTrace === undefined ? {} : { final: finalTrace }) });
  }

  /** The entries as short labels: trace types, `snapshot:<trigger>`, `flush` and `flush:turn` (with the turn's messages). */
  labels(): string[] {
    return this.entries.map((entry) => {
      if (entry.kind === "trace") return entry.type;
      if (entry.kind === "snapshot") return `snapshot:${entry.trigger}`;
      return entry.final === undefined ? "flush" : "flush:turn";
    });
  }

  trace(type: string): unknown[] {
    return this.entries.flatMap((entry) => (entry.kind === "trace" && entry.type === type ? [entry.data] : []));
  }

  /** The message ids each turn.completed flush carried. */
  turnMessageIds(): string[][] {
    return this.entries.flatMap((entry) => (entry.kind === "flush" && entry.final !== undefined
      ? [((entry.final as { messages: EngineMessage[] }).messages).map((each) => String(each.info.id))]
      : []));
  }
}

/** What the observer tells the project archive: the messages of each completed turn, and every call in order. */
function fakeArchive() {
  const turns: Array<unknown[] | null> = [];
  const calls: Array<"followed" | "completed" | "incomplete"> = [];
  return {
    turns,
    calls,
    turnFollowed: () => { calls.push("followed"); },
    turnCompleted: (_sessionId: string, messages: unknown) => {
      turns.push(messages as unknown[] | null);
      calls.push("completed");
    },
    turnIncomplete: () => { calls.push("incomplete"); },
  };
}

type ObservedArchive = Parameters<typeof observeUploadedSession>[0]["archive"];

function observe(input: { sessionUploader: ObservedUploader; archive: ObservedArchive; observers: SessionObservers; target: EngineTarget; timing: Partial<ObserverTiming> }) {
  return observeUploadedSession({ ...input, sessionId: SESSION });
}

/** A project archiver that records what the real lifecycle asks of it (bases and deltas numbered like the real one). */
class RecordingArchiver implements ProjectArchiver {
  readonly calls: string[] = [];
  private lastTurn = -1;

  async captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {
    this.calls.push(`base ${sessionId} ${root} ${turn}`);
    this.lastTurn = turn;
    return { status: "queued", archiveId: "archive-base", kind: "base", sequence: 0, size: 1 };
  }

  async captureDelta(sessionId: string, root: string, turn: number | null): Promise<CaptureResult> {
    this.calls.push(`delta ${sessionId} ${root} ${turn}`);
    const next = turn ?? this.lastTurn + 1;
    if (next <= this.lastTurn) return { status: "skipped", reason: "stale_turn" };
    this.lastTurn = next;
    return { status: "queued", archiveId: `archive-delta-${next}`, kind: "delta", sequence: next, size: 1 };
  }

  async captureFinal(sessionId: string, reason: FinalReason): Promise<CaptureResult> {
    this.calls.push(`final ${sessionId} ${reason}`);
    return { status: "queued", archiveId: `archive-final-${this.calls.length}`, kind: "delta", sequence: this.calls.length, size: 1 };
  }

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

  recordTouched(): void {}

  forgetTouched(): void {}

  async drain(): Promise<DrainResult> {
    return { uploaded: 0, pending: 0, dropped: 0, blocked: null, disabled: false };
  }

  async signOut(): Promise<void> {}

  async stop(): Promise<void> {}
}

/** The real project archive lifecycle on a recording archiver, a session of the fake engine started on a fresh folder. */
async function archivedSession(engine: ReturnType<typeof startEngine>, finalIdleMs: number) {
  const folder = await mkdtemp(join(tmpdir(), "omnirush-observer-archive-"));
  cleanups.push(() => rm(folder, { recursive: true, force: true }));
  const root = await realpath(folder);
  const archiver = new RecordingArchiver();
  const archive = new ProjectArchiveLifecycle({ archiver, enabled: true, log: () => undefined, finalIdleMs });
  cleanups.push(() => archive.stop({ finals: false }));
  archive.sessionStarted({ sessionId: SESSION, root, engine: projectArchiveEngineReads(engine.target, SESSION) });
  await archive.settled();
  return { root, archiver, archive };
}

describe("session upload observer", () => {
  test("a turn busy for three hours, past the old one-hour cap, gets its messages, snapshot and archive delta, with status reads easing off", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    engine.control.messages = [message("msg_user_0001", "user", "Work on issue 42")];
    engine.control.status = () => (clock.elapsed() < 3 * HOUR ? "busy" : "idle");
    clock.at(3 * HOUR, () => engine.control.messages.push(message("msg_assistant_0001", "assistant", "Fixed issue 42")));

    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: clock.timing });

    expect(sessionUploader.labels()).not.toContain("session.observer_timeout");
    expect(sessionUploader.labels()).not.toContain("session.observer_failed");
    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(sessionUploader.turnMessageIds()).toEqual([["msg_user_0001", "msg_assistant_0001"]]);
    expect(sessionUploader.checkpoint).toBe("msg_assistant_0001");
    expect(archive.turns).toHaveLength(1);
    expect(archive.turns[0]).toHaveLength(2);
    // A settled turn, however long, is a completed one for the project archive.
    expect(archive.calls).toEqual(["followed", "completed"]);
    expect(clock.elapsed()).toBeGreaterThanOrEqual(3 * HOUR);
    // A read a second for the first two minutes, then less often, at most every 10 s:
    // about 1,250 reads over three hours instead of 10,800.
    expect(clock.waits.slice(0, 120).every((ms) => ms === 1_000)).toBe(true);
    expect(Math.max(...clock.waits)).toBe(10_000);
    expect(engine.control.statusReads).toBeLessThan(1_300);
  });

  test("the sub-agents below a running turn are listed about once a minute, ids only, before the turn settles", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    engine.control.messages = [message("msg_user_0001", "user", "Split the work")];
    engine.control.status = () => (clock.elapsed() < 5 * 60_000 ? "busy" : "idle");
    clock.at(90_000, () => {
      engine.control.children[SESSION] = [{ id: "ses_child_1" }, { id: "ses_child_2" }];
      engine.control.children.ses_child_1 = [{ id: "ses_grand_1" }];
      engine.control.children.ses_grand_1 = [{ id: "ses_great_1" }];
      engine.control.children.ses_great_1 = [{ id: "ses_too_deep" }];
    });
    clock.at(5 * 60_000, () => engine.control.messages.push(message("msg_assistant_0001", "assistant", "Done")));

    await observe({ sessionUploader, archive: fakeArchive(), observers: createSessionObservers(), target: engine.target, timing: clock.timing });

    // About one listing a minute while busy (the first finds none yet), three layers down.
    expect(sessionUploader.notedChildIds.length).toBeGreaterThanOrEqual(3);
    expect(sessionUploader.notedChildIds.length).toBeLessThanOrEqual(5);
    expect(sessionUploader.notedChildIds[0]).toEqual([]);
    expect(sessionUploader.notedChildIds.at(-1)).toEqual(["ses_child_1", "ses_child_2", "ses_grand_1", "ses_great_1"]);
    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
  });

  test("a turn stopped with Esc is recorded as aborted: session.idle outcome, the snapshot's outcome and turn.completed's", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const stoppedReply = message("msg_assistant_0001", "assistant", "Working on");
    stoppedReply.info = { ...stoppedReply.info, error: { name: "MessageAbortedError", data: { message: "Aborted" } } };
    engine.control.messages = [message("msg_user_0001", "user", "Write a long file"), stoppedReply];
    engine.control.status = () => (clock.elapsed() < 60_000 ? "busy" : "idle");

    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: clock.timing });

    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(sessionUploader.trace("session.idle")).toEqual([{ status: "idle", outcome: "stopped" }]);
    expect(sessionUploader.entries.find((entry) => entry.kind === "snapshot")).toMatchObject({ trigger: "turn_completed", outcome: "aborted" });
    expect(sessionUploader.entries.find((entry) => entry.kind === "flush")).toMatchObject({ final: { outcome: "aborted" } });
  });

  test("a turn whose model stream died right after a tool call goes up with that call closed as aborted", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const dropped = message("msg_assistant_0001", "assistant", "Editing");
    dropped.info = { ...dropped.info, time: { created: 1, completed: 50 }, finish: "error", error: { name: "APIError", data: { message: "The upstream stream ended" } } };
    const call = { id: "prt_tool_0001", messageID: "msg_assistant_0001", sessionID: SESSION, type: "tool", tool: "edit", callID: "call_x|fc_y", state: { status: "running", input: { filePath: "a.ts" }, time: { start: 40 } } };
    dropped.parts = [...dropped.parts, call];
    engine.control.messages = [message("msg_user_0001", "user", "Edit a.ts"), dropped];
    engine.control.status = () => (clock.elapsed() < 60_000 ? "busy" : "idle");

    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: clock.timing });

    expect(sessionUploader.trace("turn.tools_closed")).toEqual([{ count: 1 }]);
    const final = sessionUploader.entries.find((entry) => entry.kind === "flush" && entry.final !== undefined) as { final: { messages: EngineMessage[] } };
    const part = final.final.messages[1]!.parts[1] as { callID: string; state: Record<string, unknown> };
    expect(part.callID).toBe("call_x|fc_y");
    expect(part.state).toEqual({ status: "error", input: { filePath: "a.ts" }, error: "Tool execution aborted", metadata: { interrupted: true }, time: { start: 40, end: 50 } });
    // The engine's own copy is left as it is.
    expect((engine.control.messages[1]!.parts[1] as { state: { status: string } }).state.status).toBe("running");
  });

  test("the app quits mid tool: the engine is stopped first and the upload carries its own aborted call, never a later completion", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const running = message("msg_assistant_0001", "assistant", "Installing");
    running.info = { ...running.info, time: { created: 1 } };
    const call = { id: "prt_tool_0001", messageID: "msg_assistant_0001", sessionID: SESSION, type: "tool", tool: "bash", callID: "call_npm", state: { status: "running", input: { command: "npm install" }, time: { start: 40 } } as Record<string, unknown> };
    running.parts = [...running.parts, call];
    engine.control.messages = [message("msg_user_0001", "user", "Install"), running];
    let busy = true;
    engine.control.status = () => (busy ? "busy" : "idle");
    // The engine's own stop: its cleanup marks the running call aborted.
    engine.control.onAbort = () => {
      busy = false;
      running.info = { ...running.info, time: { created: 1, completed: 70 }, error: { name: "MessageAbortedError", data: { message: "Aborted" } } };
      call.state = { status: "error", input: { command: "npm install" }, error: "Tool execution aborted", metadata: { interrupted: true }, time: { start: 40, end: 69 } };
    };
    const observers = createSessionObservers();
    let quit: Promise<void> | undefined;
    clock.at(60_000, () => { quit = observers.sessions.get(SESSION)?.settleNow?.(); });

    await observe({ sessionUploader, archive: fakeArchive(), observers, target: engine.target, timing: clock.timing });
    await quit;

    expect(engine.control.aborts).toBe(1);
    expect(sessionUploader.trace("turn.stopped_on_quit")).toEqual([{ idle: true }]);
    expect(sessionUploader.trace("turn.tools_closed")).toEqual([]);
    const final = sessionUploader.entries.find((entry) => entry.kind === "flush" && entry.final !== undefined) as { final: { messages: EngineMessage[] } };
    expect((final.final.messages[1]!.parts[1] as { state: Record<string, unknown> }).state).toEqual(call.state);
  });

  test("the app quits mid tool and the engine does not stop in time: a bounded wait, then the upload closes the call", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const running = message("msg_assistant_0001", "assistant", "Installing");
    running.info = { ...running.info, time: { created: 1 } };
    running.parts = [...running.parts, { id: "prt_tool_0001", type: "tool", tool: "bash", callID: "call_npm", state: { status: "running", input: {}, time: { start: 40 } } }];
    engine.control.messages = [message("msg_user_0001", "user", "Install"), running];
    engine.control.status = () => (clock.elapsed() < 10 * 60_000 ? "busy" : "idle");
    const observers = createSessionObservers();
    let quit: Promise<void> | undefined;
    let quitAt = 0;
    let quitEnded = 0;
    clock.at(60_000, () => { quitAt = Date.now(); quit = observers.sessions.get(SESSION)?.settleNow?.().then(() => { quitEnded = Date.now(); }); });

    await observe({ sessionUploader, archive: fakeArchive(), observers, target: engine.target, timing: clock.timing });
    await quit;

    expect(engine.control.aborts).toBe(1);
    // Real time: the stop is asked once and waited for a bounded number of status reads.
    expect(quitEnded - quitAt).toBeLessThan(3_000);
    expect(sessionUploader.trace("turn.stopped_on_quit")).toEqual([{ idle: false }]);
    expect(sessionUploader.trace("turn.tools_closed")).toEqual([{ count: 1 }]);
  });

  test("a turn whose calls all finished records no closing", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const reply = message("msg_assistant_0001", "assistant", "Done");
    reply.parts = [...reply.parts, { id: "prt_tool_0001", type: "tool", tool: "read", callID: "c1", state: { status: "completed", input: {}, output: "ok", time: { start: 1, end: 2 } } }];
    engine.control.messages = [message("msg_user_0001", "user", "Read"), reply];
    engine.control.status = () => (clock.elapsed() < 60_000 ? "busy" : "idle");

    await observe({ sessionUploader, archive: fakeArchive(), observers: createSessionObservers(), target: engine.target, timing: clock.timing });

    expect(sessionUploader.trace("turn.tools_closed")).toEqual([]);
  });

  test("a status read that times out twice, then answers, does not end the observation", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant")];
    engine.control.status = () => (clock.elapsed() < 5 * 60_000 ? "busy" : "idle");
    // The engine is busy with a large session: its first two status answers take longer than a status read waits.
    engine.control.statusDelaysMs = [400, 400];

    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: { ...clock.timing, statusTimeoutMs: 50 } });

    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(sessionUploader.turnMessageIds()).toEqual([["msg_user_0001", "msg_assistant_0001"]]);
    expect(archive.calls).toEqual(["followed", "completed"]);
    // The failed reads backed off (1 s, then 2 s) before the next one.
    expect(clock.waits.slice(0, 3)).toEqual([1_000, 1_000, 2_000]);
  });

  test("an engine restarting mid-turn is waited out and noted once past a minute; a request that finds the session followed points it at the new engine", async () => {
    const clock = fakeClock();
    const before = startEngine();
    const after = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    before.control.messages = [message("msg_user_0001", "user")];
    before.control.status = () => "busy";
    after.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant")];
    after.control.status = () => (clock.elapsed() < 40 * 60_000 ? "busy" : "idle");
    // Twenty minutes in, the engine goes away; five minutes later a request reaches the restarted one.
    clock.at(20 * 60_000, () => void before.server.stop(true));
    let rejoined: Promise<void> | null = null;
    clock.at(25 * 60_000, () => {
      rejoined = observe({ sessionUploader, archive, observers, target: after.target, timing: clock.timing });
    });

    const observation = observe({ sessionUploader, archive, observers, target: before.target, timing: clock.timing });
    await observation;

    expect(rejoined as Promise<void> | null).toBe(observation);
    expect(sessionUploader.labels()).toEqual([
      "session.engine_unavailable",
      "session.engine_recovered",
      "session.idle",
      "snapshot:turn_completed",
      "flush:turn",
    ]);
    const [unavailable] = sessionUploader.trace("session.engine_unavailable") as Array<{ error: string; failures: number }>;
    expect(unavailable?.failures).toBeGreaterThan(1);
    const [recovered] = sessionUploader.trace("session.engine_recovered") as Array<{ unavailable_ms: number }>;
    expect(recovered?.unavailable_ms).toBeGreaterThanOrEqual(4 * 60_000);
    expect(sessionUploader.turnMessageIds()).toEqual([["msg_user_0001", "msg_assistant_0001"]]);
    expect(archive.turns).toHaveLength(1);
    // Waiting out the engine is not an incomplete turn, and the request that rejoined followed no turn of its own.
    expect(archive.calls).toEqual(["followed", "completed"]);
    expect(observers.sessions.size).toBe(0);
  });

  test("a prompt sent while the turn settles is followed as a turn of its own", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant")];
    let busyUntil = 2 * 60_000;
    engine.control.status = () => (clock.elapsed() < busyUntil ? "busy" : "idle");
    // The next prompt reaches the engine right as the settled turn's messages are read.
    engine.control.onMessagesRead = () => {
      engine.control.onMessagesRead = null;
      busyUntil = clock.elapsed() + 5 * 60_000;
      engine.control.messages.push(message("msg_user_0002", "user"), message("msg_assistant_0002", "assistant"));
      void observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    };

    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });

    expect(sessionUploader.labels()).toEqual([
      "session.idle", "snapshot:turn_completed", "flush:turn",
      "session.idle", "snapshot:turn_completed", "flush:turn",
    ]);
    expect(sessionUploader.turnMessageIds()).toEqual([
      ["msg_user_0001", "msg_assistant_0001"],
      ["msg_user_0002", "msg_assistant_0002"],
    ]);
    expect(archive.turns.map((turn) => turn?.length)).toEqual([2, 4]);
    // The second turn is announced before it is followed: the idle final archive the first one armed is off.
    expect(archive.calls).toEqual(["followed", "completed", "followed", "completed"]);
  });

  test("a turn after a revert was made final says which messages the session kept, and sends the kept history", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant"), message("msg_user_0002", "user"), message("msg_assistant_0002", "assistant")];
    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    expect(sessionUploader.trace("session.reverted")).toEqual([]);
    expect(sessionUploader.checkpoint).toBe("msg_assistant_0002");

    // Reverted to the second prompt, then a new one: the engine deleted the second turn.
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant"), message("msg_user_0003", "user"), message("msg_assistant_0003", "assistant")];
    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    expect(sessionUploader.trace("session.reverted")).toEqual([{
      missing_message_id: "msg_assistant_0002",
      kept_message_ids: ["msg_user_0001", "msg_assistant_0001", "msg_user_0003", "msg_assistant_0003"],
    }]);
    expect(sessionUploader.labels().slice(3)).toEqual(["session.reverted", "session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(sessionUploader.turnMessageIds().at(-1)).toEqual(["msg_user_0001", "msg_assistant_0001", "msg_user_0003", "msg_assistant_0003"]);
    expect(sessionUploader.checkpoint).toBe("msg_assistant_0003");

    // The next ordinary turn carries no marker.
    engine.control.messages.push(message("msg_user_0004", "user"), message("msg_assistant_0004", "assistant"));
    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    expect(sessionUploader.trace("session.reverted")).toHaveLength(1);
    expect(sessionUploader.turnMessageIds().at(-1)).toEqual(["msg_user_0004", "msg_assistant_0004"]);
  });

  test("the server stopping mid-turn ends the observation quietly and leaves the checkpoint where it was", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    sessionUploader.checkpoint = "msg_assistant_0000";
    const observers = createSessionObservers();
    engine.control.status = () => "busy";
    clock.at(2 * HOUR, () => observers.controller.abort());
    const archive = fakeArchive();
    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    expect(sessionUploader.entries).toEqual([]);
    expect(sessionUploader.checkpoint).toBe("msg_assistant_0000");
    // A quit is no incomplete turn: the project archive's stop() packs its final archives.
    expect(archive.calls).toEqual(["followed"]);
  });

  test("an unexpected error ends the observation with the turn's snapshot and trace, and the project archive hears once that the turn did not complete", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    // A session uploader that fails on the second turn's idle event, before that turn's snapshot.
    let idles = 0;
    const sessionUploader = new (class extends FakeUploader {
      override recordTrace(sessionId: string, type: string, data?: unknown): void {
        if (type === "session.idle" && ++idles === 2) throw new Error("the session uploader failed");
        super.recordTrace(sessionId, type, data);
      }
    })();
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant")];
    let busyUntil = 2 * 60_000;
    engine.control.status = () => (clock.elapsed() < busyUntil ? "busy" : "idle");
    engine.control.onMessagesRead = () => {
      engine.control.onMessagesRead = null;
      busyUntil = clock.elapsed() + 5 * 60_000;
      engine.control.messages.push(message("msg_user_0002", "user"), message("msg_assistant_0002", "assistant"));
      void observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    };

    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });

    expect(sessionUploader.labels()).toEqual([
      "session.idle", "snapshot:turn_completed", "flush:turn",
      "session.observer_failed", "snapshot:turn_completed", "flush",
    ]);
    // The first turn completed; the second, which failed, is incomplete, and neither is told twice.
    expect(archive.calls).toEqual(["followed", "completed", "followed", "incomplete"]);
    expect(observers.sessions.size).toBe(0);
  });
});

describe("session upload observer across engine rollovers and queued prompts", () => {
  /** A message the engine created at `created` (epoch ms); an assistant one finished. */
  const at = (id: string, role: "user" | "assistant", created: number): EngineMessage => {
    const each = message(id, role);
    each.info.time = role === "assistant" ? { created, completed: created + 1 } : { created };
    if (role === "assistant") each.info.finish = "stop";
    return each;
  };

  test("an engine closed mid-turn by a rollover hands the observation to the engine that took over: the turn settles there with its messages and snapshot", async () => {
    const clock = fakeClock();
    // Two engine generations over one shared database: the same messages answer on both.
    const draining = startEngine();
    const primary = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    const shared = [message("msg_user_0001", "user")];
    draining.control.messages = shared;
    primary.control.messages = shared;
    // The turn runs on the draining engine; the new primary never ran it, so it reports the session idle.
    draining.control.status = () => (clock.elapsed() < 90_000 ? "busy" : "idle");
    primary.control.status = () => "idle";
    // The turn ends; a moment later (before the observer saw it idle twice) the pool retires the
    // drained engine: it tells the observers first, then closes it.
    clock.at(90_000, () => shared.push(message("msg_assistant_0001", "assistant")));
    clock.at(90_500, () => {
      engineReplaced(observers, draining.target.baseUrl, { baseUrl: primary.target.baseUrl, authorization: "Basic bmV3LWVuZ2luZQ==" });
      void draining.server.stop(true);
    });

    await observe({ sessionUploader, archive, observers, target: draining.target, timing: clock.timing });

    expect(sessionUploader.labels()).not.toContain("session.engine_unavailable");
    expect(sessionUploader.labels()).not.toContain("session.observer_timeout");
    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(sessionUploader.turnMessageIds()).toEqual([["msg_user_0001", "msg_assistant_0001"]]);
    expect(archive.calls).toEqual(["followed", "completed"]);
    // It settled within seconds of the turn's end, reading the new engine with that engine's credentials.
    expect(clock.elapsed()).toBeLessThan(100_000);
    expect(primary.control.authorizations.length).toBeGreaterThan(0);
    expect(new Set(primary.control.authorizations)).toEqual(new Set(["Basic bmV3LWVuZ2luZQ=="]));
    // A request that still names the closed engine (it was routed before the close) is read from the new one.
    const late = new FakeUploader();
    const lateArchive = fakeArchive();
    await observe({ sessionUploader: late, archive: lateArchive, observers, target: draining.target, timing: clock.timing });
    expect(late.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(observers.sessions.size).toBe(0);
  });

  test("a prompt sent within two seconds of the turn going idle ends that turn: each prompt gets its own snapshot, messages and settle", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    const start = clock.timing.now!();
    engine.control.messages = [at("msg_user_0001", "user", start)];
    let busyUntil = 59_500;
    engine.control.status = () => (clock.elapsed() < busyUntil ? "busy" : "idle");
    clock.at(59_500, () => engine.control.messages.push(at("msg_assistant_0001", "assistant", start + 59_000)));
    // A queued prompt goes out a second after the turn went idle, between the observer's first idle
    // read and the second one it settles on: the server records the dispatch, then the engine stores
    // the prompt and runs a second turn.
    clock.at(60_500, () => {
      const dispatchedAt = clock.timing.now!();
      promptDispatched(observers, sessionUploader, SESSION, dispatchedAt);
      busyUntil = 3 * 60_000;
      engine.control.messages.push(at("msg_user_0002", "user", dispatchedAt + 5));
      // The prompt's response reaches the observer like any captured request.
      void observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    });
    clock.at(3 * 60_000, () => engine.control.messages.push(at("msg_assistant_0002", "assistant", start + 179_000)));

    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });

    expect(sessionUploader.labels()).toEqual([
      // Turn 1's end snapshot is taken as prompt 2 goes out (ahead of prompt 2's own snapshot).
      "snapshot:turn_completed",
      "session.idle", "flush:turn",
      "session.idle", "snapshot:turn_completed", "flush:turn",
    ]);
    expect(sessionUploader.turnMessageIds()).toEqual([
      ["msg_user_0001", "msg_assistant_0001"],
      ["msg_user_0002", "msg_assistant_0002"],
    ]);
    expect(sessionUploader.checkpoint).toBe("msg_assistant_0002");
    expect(archive.calls).toEqual(["followed", "completed", "followed", "completed"]);
    expect(archive.turns.map((turn) => turn?.length)).toEqual([2, 4]);
  });

  test("a prompt sent into a turn still answering waits for that answer to finish before the turn settles", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    const sessionUploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    const start = clock.timing.now!();
    const answering = at("msg_assistant_0001", "assistant", start + 1_000);
    answering.info.time = { created: start + 1_000 };
    delete answering.info.finish;
    engine.control.messages = [at("msg_user_0001", "user", start), answering];
    engine.control.status = () => (clock.elapsed() < 5 * 60_000 ? "busy" : "idle");
    clock.at(30_000, () => {
      const dispatchedAt = clock.timing.now!();
      promptDispatched(observers, sessionUploader, SESSION, dispatchedAt);
      engine.control.messages.push(at("msg_user_0002", "user", dispatchedAt + 5));
    });
    // Turn 1's answer ends a minute later; turn 2 answers after it.
    clock.at(90_000, () => { answering.info.time = { created: start + 1_000, completed: start + 90_000 }; answering.info.finish = "stop"; });
    clock.at(5 * 60_000, () => engine.control.messages.push(at("msg_assistant_0002", "assistant", start + 200_000)));

    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });

    expect(sessionUploader.turnMessageIds()).toEqual([
      ["msg_user_0001", "msg_assistant_0001"],
      ["msg_user_0002", "msg_assistant_0002"],
    ]);
    expect(sessionUploader.labels().filter((label) => label === "snapshot:turn_completed")).toHaveLength(2);
    expect(archive.calls).toEqual(["followed", "completed", "followed", "completed"]);
  });
});

describe("session upload observer with the project archive", () => {
  // Turn n's prompt is sent after turn n-1's answer completed (an earlier one would steer that turn).
  const timed = (entry: EngineMessage, time: Record<string, number>): EngineMessage => ({ ...entry, info: { ...entry.info, time } });
  const user = (id: string) => timed(message(`msg_user_${id}`, "user"), { created: Number(id) * 10 });
  const answer = (id: string) => timed(message(`msg_assistant_${id}`, "assistant"), { created: Number(id) * 10 + 1, completed: Number(id) * 10 + 2 });

  test("a turn that runs past the old one-hour cap and then settles gets its delta, and the idle final archive once the session stays quiet", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    engine.control.messages = [user("0001")];
    const { root, archiver, archive } = await archivedSession(engine, 100);
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`]);
    engine.control.status = () => (clock.elapsed() < 3 * HOUR ? "busy" : "idle");
    clock.at(3 * HOUR, () => engine.control.messages.push(answer("0001")));

    const sessionUploader = new FakeUploader();
    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: clock.timing });
    await archive.settled();

    expect(clock.elapsed()).toBeGreaterThanOrEqual(3 * HOUR);
    expect(sessionUploader.labels()).toEqual(["session.idle", "snapshot:turn_completed", "flush:turn"]);
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`, `delta ${SESSION} ${root} 1`]);
    // No prompt follows: the quiet window after the turn ends in a final archive of the folder.
    await Bun.sleep(250);
    await archive.settled();
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`, `delta ${SESSION} ${root} 1`, `final ${SESSION} idle`]);
  });

  test("a turn still busy at the 24-hour safety bound gets its delta when the engine's count moved, then the idle final archive", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    engine.control.messages = [user("0001")];
    const { root, archiver, archive } = await archivedSession(engine, 100);
    // The answer ends five hours in, but the engine never reports the session idle again.
    engine.control.status = () => "busy";
    clock.at(5 * HOUR, () => engine.control.messages.push(answer("0001")));

    const sessionUploader = new FakeUploader();
    await observe({ sessionUploader, archive, observers: createSessionObservers(), target: engine.target, timing: clock.timing });
    await archive.settled();

    expect(clock.elapsed()).toBeGreaterThanOrEqual(24 * HOUR);
    expect(sessionUploader.labels()).toEqual(["session.observer_timeout", "snapshot:turn_completed", "flush"]);
    // turnIncomplete read the engine's count again: it moved, so the turn gets its delta.
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`, `delta ${SESSION} ${root} 1`]);
    await Bun.sleep(250);
    await archive.settled();
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`, `delta ${SESSION} ${root} 1`, `final ${SESSION} idle`]);
  }, 60_000);

  test("a prompt sent while a turn settles keeps the idle final archive off while its own turn runs", async () => {
    const clock = fakeClock();
    const engine = startEngine();
    engine.control.messages = [user("0001")];
    const { root, archiver, archive } = await archivedSession(engine, 100);
    const sessionUploader = new FakeUploader();
    const observers = createSessionObservers();
    let busyUntil = 2 * 60_000;
    engine.control.status = () => (clock.elapsed() < busyUntil ? "busy" : "idle");
    clock.at(busyUntil, () => engine.control.messages.push(answer("0001")));
    // The next prompt reaches the server while turn 1's messages are read: its session start
    // reaches the archive before turn 1's end does.
    engine.control.onMessagesRead = () => {
      engine.control.onMessagesRead = null;
      busyUntil = clock.elapsed() + 30 * 60_000;
      engine.control.messages.push(user("0002"));
      clock.at(busyUntil, () => engine.control.messages.push(answer("0002")));
      archive.sessionStarted({ sessionId: SESSION, root, engine: projectArchiveEngineReads(engine.target, SESSION) });
      void observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
      // Turn 2's first status answer takes longer than the quiet window.
      engine.control.statusDelaysMs = [300];
    };

    await observe({ sessionUploader, archive, observers, target: engine.target, timing: clock.timing });
    await archive.settled();

    expect(sessionUploader.turnMessageIds()).toEqual([["msg_user_0001", "msg_assistant_0001"], ["msg_user_0002", "msg_assistant_0002"]]);
    // No idle final archive while turn 2 ran, only after it.
    expect(archiver.calls).toEqual([`base ${SESSION} ${root} 0`, `delta ${SESSION} ${root} 1`, `delta ${SESSION} ${root} 2`]);
    await Bun.sleep(250);
    await archive.settled();
    expect(archiver.calls).toEqual([
      `base ${SESSION} ${root} 0`,
      `delta ${SESSION} ${root} 1`,
      `delta ${SESSION} ${root} 2`,
      `final ${SESSION} idle`,
    ]);
  });
});

describe("session upload observer with the session uploader", () => {
  type Envelope = {
    snapshot_type: string;
    files: Array<{ path: string; content: string }>;
    trace?: Array<{ type: string; data?: Record<string, unknown> }>;
  };

  test("a turn left unsettled past the safety bound leaves its messages to the next settled turn, which sends them over several traces and counts what exceeds the backlog", async () => {
    const root = await mkdtemp(join(tmpdir(), "omnirush-observer-"));
    cleanups.push(() => rm(root, { recursive: true, force: true }));
    await writeFile(join(root, "app.txt"), "hello\n");
    const uploads: Envelope[] = [];
    const sessionUploader = new SessionUploader({
      upload: async (_sessionId, compressed) => {
        uploads.push(withTraceEvents(JSON.parse(zstdDecompressSync(compressed).toString("utf8"))) as Envelope);
        return Response.json({ ok: true }, { status: 201 });
      },
      changeDebounceMs: 60_000,
      fallbackScanMs: 60_000,
    });
    cleanups.push(() => sessionUploader.stop());
    sessionUploader.startSession(SESSION, "workspace-observer", root);
    const engine = startEngine();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    const traces = () => uploads.filter((upload) => upload.snapshot_type === "trace");
    const events = (envelope: Envelope | undefined) => envelope?.trace ?? [];
    const document = (envelope: Envelope) => JSON.parse(envelope.files[0]!.content) as { trace_truncated: boolean; dropped_event_count: number };
    const ids = (list: unknown) => (list as EngineMessage[]).map((each) => String(each.info.id));
    let clock = fakeClock();
    /** One observation on a fresh clock, with the engine busy for `busyMs` (Infinity: throughout). */
    const turn = async (busyMs: number, maxTurnMs?: number) => {
      clock = fakeClock();
      const current = clock;
      engine.control.status = () => (current.elapsed() < busyMs ? "busy" : "idle");
      await observe({ sessionUploader, archive, observers, target: engine.target, timing: { ...current.timing, ...(maxTurnMs ? { maxTurnMs } : {}) } });
      await sessionUploader.idle(SESSION);
    };

    // Turn 1 settles normally: the checkpoint is its answer.
    engine.control.messages = [message("msg_user_0001", "user"), message("msg_assistant_0001", "assistant")];
    await turn(60_000);
    expect((await sessionUploader.sessionCheckpoint(SESSION)).lastMessageId).toBe("msg_assistant_0001");

    // Turn 2 is still running when the observer's safety bound (two hours here) runs out.
    engine.control.messages.push(message("msg_user_0002", "user", "Continue"));
    for (let index = 1; index <= 8; index += 1) engine.control.messages.push(longAnswer(`msg_long_${String(index).padStart(4, "0")}`, 3));
    await turn(Infinity, 2 * HOUR);
    const timedOut = traces().at(-1)!;
    expect(events(timedOut).map((event) => event.type)).toContain("session.observer_timeout");
    expect(events(timedOut).map((event) => event.type)).not.toContain("turn.completed");
    expect(events(timedOut).filter((event) => event.type === "collector.trigger").map((event) => event.data?.trigger)).toEqual(["turn_completed"]);
    expect(archive.turns).toHaveLength(1);
    // The project archive hears the turn ended without completing (its delta, or a final archive).
    expect(archive.calls).toEqual(["followed", "completed", "followed", "incomplete"]);
    // Its messages were not sent, so the checkpoint did not move.
    expect((await sessionUploader.sessionCheckpoint(SESSION)).lastMessageId).toBe("msg_assistant_0001");

    // Turn 3 ("continue") settles: 24 MiB of turn 2 plus its own messages go out in four traces of at most 8 MiB of messages.
    const sent = traces().length;
    engine.control.messages.push(message("msg_user_0003", "user", "continue"), message("msg_assistant_0003", "assistant"));
    await turn(3 * 60_000);
    const backlog = traces().slice(sent);
    expect(backlog).toHaveLength(4);
    const parts = backlog.slice(0, 3).map((envelope) => events(envelope).find((event) => event.type === "turn.messages")?.data);
    expect(parts.map((part) => [part?.part, part?.parts])).toEqual([[1, 4], [2, 4], [3, 4]]);
    const completed = events(backlog[3]).find((event) => event.type === "turn.completed")?.data;
    expect([...parts.flatMap((part) => ids(part?.messages)), ...ids(completed?.messages)]).toEqual([
      "msg_user_0002",
      ...Array.from({ length: 8 }, (_, index) => `msg_long_${String(index + 1).padStart(4, "0")}`),
      "msg_user_0003",
      "msg_assistant_0003",
    ]);
    for (const envelope of backlog) {
      expect(document(envelope)).toMatchObject({ trace_truncated: false, dropped_event_count: 0 });
      expect(events(envelope).map((event) => event.type)).not.toContain("session.messages_omitted");
    }
    expect((await sessionUploader.sessionCheckpoint(SESSION)).lastMessageId).toBe("msg_assistant_0003");
    // The archive delta counts every completed turn the engine holds.
    expect(archive.turns.at(-1)).toHaveLength(13);

    // A backlog past 32 MiB keeps the newest messages and counts the rest, as a single turn did before,
    // but never drops the user's prompt.
    const beforeOmission = traces().length;
    engine.control.messages.push(message("msg_user_0004", "user"));
    for (let index = 1; index <= 12; index += 1) engine.control.messages.push(longAnswer(`msg_huge_${String(index).padStart(4, "0")}`, 3));
    await turn(60_000);
    const omitted = traces().slice(beforeOmission);
    expect(omitted.flatMap((envelope) => events(envelope)).filter((event) => event.type === "session.messages_omitted").map((event) => event.data))
      .toEqual([{ count: 2 }]);
    const kept = omitted.flatMap((envelope) => events(envelope))
      .filter((event) => event.type === "turn.messages" || event.type === "turn.completed")
      .flatMap((event) => ids(event.data?.messages));
    expect(kept).toEqual(["msg_user_0004", ...Array.from({ length: 10 }, (_, index) => `msg_huge_${String(index + 3).padStart(4, "0")}`)]);
    for (const envelope of omitted) expect(document(envelope)).toMatchObject({ trace_truncated: false, dropped_event_count: 0 });
  }, 60_000);
});

describe("message outlines and turn outcomes", () => {
  test("a user message's outline keeps what turn counting reads of its parts, never their text", () => {
    const outline = messageOutline({
      info: { id: "u1", role: "user", summary: { diffs: [{ file: "a.ts", before: "x", after: "y" }] } },
      parts: [
        { id: "p1", type: "text", text: "secret prompt", synthetic: true },
        { id: "p2", type: "text", text: "typed" },
        { id: "p3", type: "file", url: "file:///a.png" },
        { id: "p4", type: "compaction", auto: true },
      ],
    });
    expect(outline).toEqual({
      info: { id: "u1", role: "user" },
      parts: [{ type: "text", synthetic: true }, { type: "text" }, { type: "file" }, { type: "compaction" }],
    });
    // An assistant message keeps only its finish parts.
    expect(messageOutline({ info: { id: "a1", role: "assistant" }, parts: [{ type: "text", text: "answer" }, { type: "step-finish", reason: "stop" }] }))
      .toEqual({ info: { id: "a1", role: "assistant" }, parts: [{ type: "step-finish", reason: "stop" }] });
  });

  test("how the latest turn ended", () => {
    const prompt = { info: { role: "user" }, parts: [{ type: "text" }] };
    expect(turnOutcome([])).toBeNull();
    expect(turnOutcome([prompt, { info: { role: "assistant", time: { completed: 2 } } }])).toBe("completed");
    // Stopped with Esc: the 1.x engine (and the 2.x adapter) record MessageAbortedError, the 2.x context an "aborted" error.
    expect(turnOutcome([prompt, { info: { role: "assistant", finish: "tool-calls" } }, { info: { role: "assistant", error: { name: "MessageAbortedError" } } }])).toBe("stopped");
    expect(turnOutcome([{ type: "user" }, { type: "assistant", error: { type: "aborted", message: "Aborted" } }])).toBe("stopped");
    expect(turnOutcome([prompt, { info: { role: "assistant", error: { name: "APIError" } } }])).toBe("error");
    expect(turnOutcome([prompt, { info: { role: "assistant" } }])).toBe("incomplete");
    expect(turnOutcome([prompt, { info: { role: "assistant", time: { completed: 1 } } }, prompt])).toBe("no_reply");
    // A compaction's summary after the reply does not hide how the turn ended.
    expect(turnOutcome([
      prompt,
      { info: { role: "assistant", error: { name: "MessageAbortedError" } } },
      { info: { role: "user", agent: "compaction" }, parts: [{ type: "compaction" }] },
      { info: { role: "assistant", summary: true, finish: "stop" } },
    ])).toBe("stopped");
  });
});

describe("turns left open by an ended process, and turns open at quit", () => {
  test("a recovered turn on an idle session settles at the first read, with its messages, marked recovered", async () => {
    const { control, target } = startEngine();
    control.messages = [message("msg_1", "user"), message("msg_2", "assistant")];
    const uploader = new FakeUploader();
    const archive = fakeArchive();
    const clock = fakeClock();
    await observeUploadedSession({ sessionUploader: uploader, archive, observers: createSessionObservers(), target, timing: clock.timing, sessionId: SESSION, recovered: true });
    expect(control.statusReads).toBe(1);
    expect(uploader.turnMessageIds()).toEqual([["msg_1", "msg_2"]]);
    const final = uploader.entries.find((entry) => entry.kind === "flush" && entry.final !== undefined);
    expect(final).toMatchObject({ final: { recovered: true } });
    expect(uploader.checkpoint).toBe("msg_2");
    expect(archive.calls).toEqual(["followed", "completed"]);
  });

  test("a recovered turn still running (a restarted worker) is followed to its end as usual", async () => {
    const { control, target } = startEngine();
    let busy = true;
    control.status = () => (busy ? "busy" : "idle");
    control.messages = [message("msg_1", "user")];
    const uploader = new FakeUploader();
    const archive = fakeArchive();
    const clock = fakeClock();
    clock.at(30_000, () => {
      busy = false;
      control.messages.push(message("msg_2", "assistant"));
    });
    await observeUploadedSession({ sessionUploader: uploader, archive, observers: createSessionObservers(), target, timing: clock.timing, sessionId: SESSION, recovered: true });
    expect(clock.elapsed()).toBeGreaterThanOrEqual(30_000);
    expect(uploader.turnMessageIds()).toEqual([["msg_1", "msg_2"]]);
  });

  test("settleNow (an app quit) ends a running turn with the messages so far, once", async () => {
    const { control, target } = startEngine();
    control.status = () => "busy";
    control.messages = [message("msg_1", "user"), message("msg_2", "assistant")];
    const uploader = new FakeUploader();
    const archive = fakeArchive();
    const observers = createSessionObservers();
    // A real clock: the observer is between status reads when the app quits.
    void observeUploadedSession({ sessionUploader: uploader, archive, observers, target, sessionId: SESSION });
    await Bun.sleep(50);
    const observed = observers.sessions.get(SESSION);
    expect(observed?.settleNow).toBeDefined();
    await observed!.settleNow!();
    await observed!.settleNow!();
    observers.controller.abort();
    expect(uploader.turnMessageIds()).toEqual([["msg_1", "msg_2"]]);
    expect(uploader.labels()).toContain("session.quit_settled");
    expect(uploader.entries.find((entry) => entry.kind === "flush" && entry.final !== undefined)).toMatchObject({ final: { reason: "app_quit" } });
  });
});