@ulearning/ai-sdk-adapter 0.0.0-stage → 1.0.0-next.0

package/src/runtime/useExternalHistory.test.ts

@@ -0,0 +1,4187 @@
+// @vitest-environment jsdom
+
+import { act, renderHook, waitFor as waitForAssertion } from "./__tests__/tap";
+import { beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";
+import { bindExternalStoreMessage } from "@ulearning/ai-core";
+import type {
+  AssistantRuntime,
+  ExportedMessageRepository,
+  MessageFormatAdapter,
+  MessageFormatRepository,
+  ThreadAssistantMessage,
+  ThreadHistoryAdapter,
+  ThreadMessage,
+  RespondToToolApprovalOptions,
+  Unstable_ToolInteractionLog,
+} from "@ulearning/ai-core";
+
+const mocks = vi.hoisted(() => ({
+  remoteId: undefined as string | undefined,
+  hasThreadListItem: false,
+  listeners: new Set<() => void>(),
+}));
+
+const auiClient = {
+  threadListItem: {
+    get source() {
+      return mocks.hasThreadListItem ? "threads" : null;
+    },
+    getState: () => ({ remoteId: mocks.remoteId }),
+  },
+  subscribe: (listener: () => void) => {
+    mocks.listeners.add(listener);
+    return () => {
+      mocks.listeners.delete(listener);
+    };
+  },
+};
+
+vi.mock("@ulearning/ai-store", () => ({
+  useAui: () => auiClient,
+}));
+
+import { MessageRepository } from "@ulearning/ai-core/internal";
+import {
+  toExportedMessageRepository,
+  useExternalHistory,
+} from "./useExternalHistory";
+
+const waitFor = (assertion: () => void) =>
+  waitForAssertion(assertion, { interval: 10 });
+
+const noopThread = {
+  subscribe: () => () => {},
+  getState: () => ({ isRunning: false, messages: [] }),
+  import: () => {},
+  export: () => ({ headId: null, messages: [] }),
+} as unknown as AssistantRuntime["thread"];
+
+const runtimeRef = {
+  current: { thread: noopThread } as AssistantRuntime,
+};
+
+const storageFormat: MessageFormatAdapter<unknown, Record<string, unknown>> = {
+  format: "test",
+  encode: (item) => ({ data: item.message }),
+  decode: (stored) => ({
+    parentId: stored.parent_id,
+    message: stored.content,
+  }),
+  getId: () => "id",
+};
+
+const toThreadMessages = (_messages: unknown[]): ThreadMessage[] => [];
+const onSetMessages = () => {};
+
+describe("useExternalHistory withFormat contract", () => {
+  beforeEach(() => {
+    mocks.remoteId = undefined;
+    mocks.hasThreadListItem = false;
+    mocks.listeners.clear();
+  });
+
+  it("throws when the adapter omits withFormat", () => {
+    const adapterWithoutWithFormat: ThreadHistoryAdapter = {
+      load: vi.fn().mockResolvedValue({ headId: null, messages: [] }),
+      append: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() =>
+      renderHook(() =>
+        useExternalHistory(
+          runtimeRef,
+          adapterWithoutWithFormat,
+          toThreadMessages,
+          storageFormat,
+          onSetMessages,
+        ),
+      ),
+    ).toThrow(/withFormat/);
+
+    errorSpy.mockRestore();
+  });
+
+  it("does not throw when no adapter is supplied", () => {
+    expect(() =>
+      renderHook(() =>
+        useExternalHistory(
+          runtimeRef,
+          undefined,
+          toThreadMessages,
+          storageFormat,
+          onSetMessages,
+        ),
+      ),
+    ).not.toThrow();
+  });
+
+  it("accepts an adapter that implements withFormat", () => {
+    const withFormatResult = {
+      load: vi.fn().mockResolvedValue({ headId: null, messages: [] }),
+      append: vi.fn().mockResolvedValue(undefined),
+    };
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue(withFormatResult),
+    };
+
+    expect(() =>
+      renderHook(() =>
+        useExternalHistory(
+          runtimeRef,
+          adapter,
+          toThreadMessages,
+          storageFormat,
+          onSetMessages,
+        ),
+      ),
+    ).not.toThrow();
+
+    expect(adapter.withFormat).toHaveBeenCalledWith(storageFormat);
+  });
+
+  it("loads history when threadListItem.remoteId appears after the first paint", async () => {
+    const load = vi.fn().mockResolvedValue({ headId: null, messages: [] });
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    const { rerender } = renderHook(() =>
+      useExternalHistory(
+        runtimeRef,
+        adapter,
+        toThreadMessages,
+        storageFormat,
+        onSetMessages,
+      ),
+    );
+
+    await act(async () => {});
+    expect(load).not.toHaveBeenCalled();
+
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    await act(async () => {
+      for (const listener of mocks.listeners) listener();
+    });
+    rerender();
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+  });
+
+  it("loads when a mounted thread later receives a remoteId", async () => {
+    mocks.hasThreadListItem = true;
+    const load = vi.fn().mockResolvedValue({ headId: null, messages: [] });
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    renderHook(() =>
+      useExternalHistory(
+        runtimeRef,
+        adapter,
+        toThreadMessages,
+        storageFormat,
+        onSetMessages,
+      ),
+    );
+
+    await act(async () => {});
+    expect(load).not.toHaveBeenCalled();
+
+    mocks.remoteId = "remote-thread";
+    await act(async () => {
+      for (const listener of mocks.listeners) listener();
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+  });
+
+  it("re-enters loading when remoteId arrives before history settles", async () => {
+    mocks.hasThreadListItem = true;
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    const { result } = renderHook(() =>
+      useExternalHistory(
+        runtimeRef,
+        adapter,
+        toThreadMessages,
+        storageFormat,
+        onSetMessages,
+      ),
+    );
+
+    await act(async () => {});
+    expect(result.current.isLoading).toBe(false);
+    expect(load).not.toHaveBeenCalled();
+
+    mocks.remoteId = "remote-thread";
+    await act(async () => {
+      for (const listener of mocks.listeners) listener();
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    expect(result.current.isLoading).toBe(true);
+
+    await act(async () => {
+      resolveLoad({ headId: null, messages: [] });
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+  });
+
+  it("does not load history when remoteId appears during an active run", async () => {
+    mocks.hasThreadListItem = true;
+    const load = vi.fn().mockResolvedValue({ headId: null, messages: [] });
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+    const runningRuntimeRef = {
+      current: {
+        thread: {
+          subscribe: () => () => {},
+          getState: () => ({ isRunning: true, messages: [{ id: "u1" }] }),
+          import: () => {},
+          export: () => ({ headId: null, messages: [] }),
+        },
+      } as unknown as AssistantRuntime,
+    };
+
+    renderHook(() =>
+      useExternalHistory(
+        runningRuntimeRef,
+        adapter,
+        toThreadMessages,
+        storageFormat,
+        onSetMessages,
+      ),
+    );
+
+    await act(async () => {});
+    expect(load).not.toHaveBeenCalled();
+
+    mocks.remoteId = "remote-thread";
+    await act(async () => {
+      for (const listener of mocks.listeners) listener();
+    });
+
+    await act(async () => {});
+    expect(load).not.toHaveBeenCalled();
+  });
+
+  it("reports loading before an asynchronous history load settles", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    const { result } = renderHook(() =>
+      useExternalHistory(
+        runtimeRef,
+        adapter,
+        toThreadMessages,
+        storageFormat,
+        onSetMessages,
+      ),
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+
+    await act(async () => {
+      resolveLoad({ headId: null, messages: [] });
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+  });
+
+  it("imports history beneath live messages when a run wins the load race", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const threadState = {
+      isRunning: false,
+      messages: [] as ThreadMessage[],
+    };
+    const threadImport = vi.fn();
+    const setMessages = vi.fn();
+    const thread = {
+      subscribe: () => () => {},
+      getState: () => threadState,
+      import: threadImport,
+      export: () => ({ headId: null, messages: [] }),
+    } as unknown as AssistantRuntime["thread"];
+    const historyRuntimeRef = {
+      current: { thread } as AssistantRuntime,
+    };
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    const { result } = renderHook(() =>
+      useExternalHistory(
+        historyRuntimeRef,
+        adapter,
+        (messages) => messages.map((message) => message as ThreadMessage),
+        storageFormat,
+        setMessages,
+      ),
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    const liveMessages = [
+      { id: "live-user" },
+      { id: "live-assistant" },
+    ] as ThreadMessage[];
+    await act(async () => {
+      threadState.isRunning = true;
+      threadState.messages = liveMessages;
+      resolveLoad({
+        headId: "stored",
+        messages: [{ parentId: null, message: { id: "stored" } }],
+      });
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(threadState.messages).toBe(liveMessages);
+    expect(threadImport).toHaveBeenCalledTimes(1);
+    expect(threadImport).toHaveBeenCalledWith({
+      headId: "live-assistant",
+      messages: [
+        { parentId: null, message: { id: "stored" } },
+        { parentId: "stored", message: { id: "live-user" } },
+        { parentId: "live-user", message: { id: "live-assistant" } },
+      ],
+    });
+    expect(setMessages).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps a live message out of the merged tail when history already holds it", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const threadState = {
+      isRunning: false,
+      messages: [] as ThreadMessage[],
+    };
+    const threadImport = vi.fn();
+    const thread = {
+      subscribe: () => () => {},
+      getState: () => threadState,
+      import: threadImport,
+      export: () => ({ headId: null, messages: [] }),
+    } as unknown as AssistantRuntime["thread"];
+    const historyRuntimeRef = {
+      current: { thread } as AssistantRuntime,
+    };
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    const { result } = renderHook(() =>
+      useExternalHistory(
+        historyRuntimeRef,
+        adapter,
+        (messages) => messages.map((message) => message as ThreadMessage),
+        storageFormat,
+        () => {},
+      ),
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await act(async () => {
+      threadState.isRunning = true;
+      threadState.messages = [
+        { id: "stored-user" },
+        { id: "live-assistant" },
+      ] as ThreadMessage[];
+      resolveLoad({
+        headId: "stored-user",
+        messages: [{ parentId: null, message: { id: "stored-user" } }],
+      });
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(threadImport).toHaveBeenCalledWith({
+      headId: "live-assistant",
+      messages: [
+        { parentId: null, message: { id: "stored-user" } },
+        { parentId: "stored-user", message: { id: "live-assistant" } },
+      ],
+    });
+  });
+
+  it("keeps the live content of a resumed assistant reply with a stored id", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const threadState = {
+      isRunning: false,
+      messages: [] as ThreadMessage[],
+    };
+    const threadImport = vi.fn();
+    const thread = {
+      subscribe: () => () => {},
+      getState: () => threadState,
+      import: threadImport,
+      export: () => ({ headId: null, messages: [] }),
+    } as unknown as AssistantRuntime["thread"];
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    renderHook(() =>
+      useExternalHistory(
+        { current: { thread } as AssistantRuntime },
+        adapter,
+        (messages) => messages.map((message) => message as ThreadMessage),
+        storageFormat,
+        () => {},
+      ),
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    const liveReply: ThreadAssistantMessage = {
+      id: "assistant",
+      role: "assistant",
+      content: [{ type: "text", text: "complete streamed reply" }],
+      createdAt: new Date(),
+      status: { type: "running" },
+      metadata: {
+        unstable_state: null,
+        unstable_annotations: [],
+        unstable_data: [],
+        steps: [],
+        custom: {},
+      },
+    };
+    await act(async () => {
+      threadState.isRunning = true;
+      threadState.messages = [liveReply];
+      resolveLoad({
+        headId: "assistant",
+        messages: [
+          { parentId: null, message: { id: "user" } },
+          {
+            parentId: "user",
+            message: {
+              id: "assistant",
+              content: [{ type: "text", text: "partial reply" }],
+            },
+          },
+        ],
+      });
+    });
+
+    expect(threadImport).toHaveBeenCalledWith({
+      headId: "assistant",
+      messages: [
+        { parentId: null, message: { id: "user" } },
+        { parentId: "user", message: liveReply },
+      ],
+    });
+  });
+
+  it("merges live and stored tool interactions when history loads during a run", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const threadState = {
+      isRunning: false,
+      messages: [] as ThreadMessage[],
+    };
+    const thread = {
+      subscribe: () => () => {},
+      getState: () => threadState,
+      import: vi.fn(),
+    } as unknown as AssistantRuntime["thread"];
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const shared = { type: "action" as const, occurredAt: 1, payload: {} };
+    const stored = {
+      type: "human-response" as const,
+      occurredAt: 2,
+      payload: "stored",
+    };
+    const live = {
+      type: "human-response" as const,
+      occurredAt: 3,
+      payload: "live",
+    };
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    renderHook(() =>
+      useExternalHistory(
+        { current: { thread } as AssistantRuntime },
+        adapter,
+        (messages) => messages.map((message) => message as ThreadMessage),
+        storageFormat,
+        () => {},
+        undefined,
+        undefined,
+        () => toolInteractions,
+        (next) => {
+          toolInteractions.clear();
+          for (const [id, log] of next) toolInteractions.set(id, log);
+        },
+      ),
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await act(async () => {
+      threadState.isRunning = true;
+      threadState.messages = [{ id: "live" } as ThreadMessage];
+      toolInteractions.set("call-1", { entries: [shared, live] });
+      resolveLoad({
+        headId: "stored",
+        messages: [
+          {
+            parentId: null,
+            message: {
+              id: "stored",
+              metadata: {
+                __aui_toolInteractions: {
+                  "call-1": { entries: [shared, stored] },
+                  "call-2": { entries: [stored] },
+                },
+              },
+            },
+          },
+        ],
+      });
+    });
+
+    expect(toolInteractions.get("call-1")?.entries).toEqual([
+      shared,
+      stored,
+      live,
+    ]);
+    expect(toolInteractions.get("call-2")?.entries).toEqual([stored]);
+  });
+
+  it("discards a pending history load after switching threads", async () => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "thread-a";
+    let resolveLoad!: (repo: MessageFormatRepository<unknown>) => void;
+    const load = vi.fn(
+      () =>
+        new Promise<MessageFormatRepository<unknown>>((resolve) => {
+          resolveLoad = resolve;
+        }),
+    );
+    const threadState = {
+      isRunning: false,
+      messages: [] as ThreadMessage[],
+    };
+    const threadImport = vi.fn();
+    const setMessages = vi.fn();
+    const thread = {
+      subscribe: () => () => {},
+      getState: () => threadState,
+      import: threadImport,
+      export: () => ({ headId: null, messages: [] }),
+    } as unknown as AssistantRuntime["thread"];
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load,
+        append: vi.fn().mockResolvedValue(undefined),
+      }),
+    };
+
+    renderHook(() =>
+      useExternalHistory(
+        { current: { thread } as AssistantRuntime },
+        adapter,
+        (messages) => messages.map((message) => message as ThreadMessage),
+        storageFormat,
+        setMessages,
+      ),
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await act(async () => {
+      mocks.remoteId = "thread-b";
+      threadState.isRunning = true;
+      threadState.messages = [{ id: "thread-b-live" } as ThreadMessage];
+      resolveLoad({
+        headId: "thread-a-stored",
+        messages: [{ parentId: null, message: { id: "thread-a-stored" } }],
+      });
+    });
+
+    expect(threadImport).not.toHaveBeenCalled();
+    expect(setMessages).not.toHaveBeenCalled();
+  });
+});
+
+describe("toExportedMessageRepository", () => {
+  const convert = (items: { id: string; ok: boolean }[]): ThreadMessage[] =>
+    items[0]!.ok ? [{ id: items[0]!.id } as ThreadMessage] : [];
+
+  it("keeps descendants listed before their parents and preserves the head", () => {
+    const repo: MessageFormatRepository<{ id: string; ok: boolean }> = {
+      headId: "c",
+      messages: [
+        { parentId: "b", message: { id: "c", ok: true } },
+        { parentId: "a", message: { id: "b", ok: true } },
+        { parentId: null, message: { id: "a", ok: true } },
+      ],
+    };
+
+    const result = toExportedMessageRepository(convert, repo);
+    const repository = new MessageRepository();
+    repository.import(result);
+
+    expect(result.messages.map((m) => m.message.id)).toEqual(["a", "b", "c"]);
+    expect(result.headId).toBe("c");
+    expect(repository.getMessages().map((m) => m.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("drops missing and malformed parents' descendants regardless of row order", () => {
+    const repo: MessageFormatRepository<{ id: string; ok: boolean }> = {
+      headId: "c",
+      messages: [
+        { parentId: "b", message: { id: "c", ok: true } },
+        { parentId: "missing", message: { id: "orphan", ok: true } },
+        { parentId: "a", message: { id: "b", ok: false } },
+        { parentId: "a", message: { id: "valid", ok: true } },
+        { parentId: null, message: { id: "a", ok: true } },
+      ],
+    };
+
+    const result = toExportedMessageRepository(convert, repo);
+
+    expect(result.messages.map((m) => m.message.id)).toEqual(["a", "valid"]);
+    expect(result.headId).toBeNull();
+    expect(() => new MessageRepository().import(result)).not.toThrow();
+  });
+
+  it("drops a malformed row together with its now-orphaned descendants", () => {
+    const repo: MessageFormatRepository<{ id: string; ok: boolean }> = {
+      headId: "c",
+      messages: [
+        { parentId: null, message: { id: "a", ok: true } },
+        { parentId: "a", message: { id: "b", ok: false } },
+        { parentId: "b", message: { id: "c", ok: true } },
+      ],
+    };
+
+    const result = toExportedMessageRepository(convert, repo);
+
+    expect(result.messages.map((m) => m.message.id)).toEqual(["a"]);
+    expect(result.headId).toBeNull();
+    expect(() => new MessageRepository().import(result)).not.toThrow();
+  });
+
+  it("drops a headId that points at a filtered row", () => {
+    const repo: MessageFormatRepository<{ id: string; ok: boolean }> = {
+      headId: "b",
+      messages: [
+        { parentId: null, message: { id: "a", ok: true } },
+        { parentId: "a", message: { id: "b", ok: false } },
+      ],
+    };
+
+    const result = toExportedMessageRepository(convert, repo);
+
+    expect(result.messages.map((m) => m.message.id)).toEqual(["a"]);
+    expect(result.headId).toBeNull();
+    expect(() => new MessageRepository().import(result)).not.toThrow();
+  });
+
+  it("drops a malformed root and its entire subtree", () => {
+    const repo: MessageFormatRepository<{ id: string; ok: boolean }> = {
+      headId: "b",
+      messages: [
+        { parentId: null, message: { id: "a", ok: false } },
+        { parentId: "a", message: { id: "b", ok: true } },
+      ],
+    };
+
+    const result = toExportedMessageRepository(convert, repo);
+
+    expect(result.messages).toHaveLength(0);
+    expect(result.headId).toBeNull();
+    expect(() => new MessageRepository().import(result)).not.toThrow();
+  });
+});
+
+describe("useExternalHistory persistence", () => {
+  beforeEach(() => {
+    mocks.remoteId = undefined;
+    mocks.hasThreadListItem = false;
+    mocks.listeners.clear();
+  });
+
+  type InnerMessage = {
+    id: string;
+    parts: unknown[];
+    role?: string;
+    metadata?: Record<string, unknown>;
+  };
+
+  const persistenceStorageFormat: MessageFormatAdapter<
+    InnerMessage,
+    Record<string, unknown>
+  > = {
+    format: "test",
+    encode: (item) => ({ data: item.message }),
+    decode: (stored) => ({
+      parentId: stored.parent_id,
+      message: stored.content as unknown as InnerMessage,
+    }),
+    getId: (message) => message.id,
+  };
+
+  const createAssistantMessage = (
+    status: ThreadAssistantMessage["status"],
+    innerMessages: InnerMessage[],
+    id = "assistant-a",
+  ): ThreadMessage => {
+    const message: ThreadAssistantMessage = {
+      id,
+      role: "assistant",
+      content: [],
+      createdAt: new Date(),
+      status,
+      metadata: {
+        unstable_state: null,
+        unstable_annotations: [],
+        unstable_data: [],
+        steps: [],
+        custom: {},
+      },
+    };
+    bindExternalStoreMessage(message, innerMessages);
+    return message;
+  };
+
+  const createUserMessage = (inner: InnerMessage) => {
+    const message = {
+      id: inner.id,
+      role: "user",
+      content: [],
+    } as unknown as ThreadMessage;
+    bindExternalStoreMessage(message, inner);
+    return message;
+  };
+
+  const stoppedPrompt: InnerMessage = {
+    id: "user-1",
+    role: "user",
+    parts: ["prompt"],
+  };
+
+  const createSlowLoadHarness = (resolveOnUnmount = true) => {
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+
+    const stored: MessageFormatRepository<InnerMessage> = {
+      headId: "stored",
+      messages: [
+        {
+          parentId: null,
+          message: { id: "stored", parts: ["earlier"] },
+        },
+      ],
+    };
+    let resolveLoad!: (repo: MessageFormatRepository<InnerMessage>) => void;
+    let rejectLoad!: (error: Error) => void;
+    const load = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<MessageFormatRepository<InnerMessage>>(
+            (resolve, reject) => {
+              resolveLoad = resolve;
+              rejectLoad = reject;
+            },
+          ),
+      )
+      .mockImplementation(async () => ({
+        headId: stored.headId,
+        messages: [...stored.messages],
+      }));
+    const append = vi.fn(
+      async (
+        item: MessageFormatRepository<InnerMessage>["messages"][number],
+      ) => {
+        stored.messages.push(item);
+        stored.headId = item.message.id;
+      },
+    );
+    const reportTelemetry = vi.fn();
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({ load, append, reportTelemetry }),
+    };
+    const toMessages = (messages: InnerMessage[]) =>
+      messages.map((message) =>
+        createAssistantMessage(
+          { type: "complete", reason: "stop" },
+          [message],
+          message.id,
+        ),
+      );
+    const mount = () => {
+      let listener: (() => void) | undefined;
+      let isRunning = false;
+      let messages: ThreadMessage[] = [];
+      const importMessages = vi.fn((repo: ExportedMessageRepository) => {
+        messages = repo.messages.map((item) => item.message);
+      });
+      const thread = {
+        subscribe: (next: () => void) => {
+          listener = next;
+          return () => {};
+        },
+        getState: () => ({ isRunning, messages }),
+        import: importMessages,
+      } as unknown as AssistantRuntime["thread"];
+      const slowRuntimeRef = { current: { thread } as AssistantRuntime };
+      const hook = renderHook(() =>
+        useExternalHistory(
+          slowRuntimeRef,
+          adapter,
+          toMessages,
+          persistenceStorageFormat,
+          () => {},
+        ),
+      );
+      return {
+        ...hook,
+        importMessages,
+        step: async (next: {
+          isRunning: boolean;
+          messages: ThreadMessage[];
+        }) => {
+          await act(async () => {
+            isRunning = next.isRunning;
+            messages = next.messages;
+            listener?.();
+          });
+        },
+        settle: async () => {
+          await act(async () => {
+            isRunning = true;
+            messages = toMessages([{ id: "live", parts: ["reply"] }]);
+            listener?.();
+          });
+          await act(async () => {
+            isRunning = false;
+            listener?.();
+          });
+        },
+      };
+    };
+
+    const first = mount();
+    const unmount = first.unmount;
+    first.unmount = () => {
+      unmount();
+      if (resolveOnUnmount) {
+        resolveLoad({ headId: "stored", messages: [stored.messages[0]!] });
+      }
+    };
+    const settleBeforeLoad = async () => {
+      await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+      await first.settle();
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+      const appendCountBeforeLoad = append.mock.calls.length;
+      await act(async () => {
+        resolveLoad({ headId: "stored", messages: [stored.messages[0]!] });
+      });
+      await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+      return appendCountBeforeLoad;
+    };
+    return {
+      append,
+      reportTelemetry,
+      first,
+      mount,
+      settleBeforeLoad,
+      resolveLoad: () =>
+        resolveLoad({ headId: "stored", messages: [stored.messages[0]!] }),
+      resolveEmptyLoad: () => resolveLoad({ headId: null, messages: [] }),
+      rejectLoad: () => rejectLoad(new Error("load failed")),
+    };
+  };
+
+  it("waits for slow history before persisting a settled live turn", async () => {
+    const { append, settleBeforeLoad } = createSlowLoadHarness();
+
+    const appendCountBeforeLoad = await settleBeforeLoad();
+
+    expect(append).toHaveBeenCalledWith({
+      parentId: "stored",
+      message: { id: "live", parts: ["reply"] },
+    });
+    expect(appendCountBeforeLoad).toBe(0);
+  });
+
+  it("persists a prompt sent before history loads beneath the loaded history", async () => {
+    const { append, first, resolveLoad } = createSlowLoadHarness(false);
+    const userInner: InnerMessage = {
+      id: "user-1",
+      role: "user",
+      parts: ["prompt"],
+    };
+    const user = createUserMessage(userInner);
+    const runningAssistant = createAssistantMessage(
+      { type: "running" },
+      [{ id: "assistant-1", role: "assistant", parts: ["partial"] }],
+      "assistant-1",
+    );
+
+    await first.step({ isRunning: true, messages: [user, runningAssistant] });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(append).not.toHaveBeenCalled();
+
+    await act(async () => resolveLoad());
+
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    expect(append).toHaveBeenCalledWith({
+      parentId: "stored",
+      message: userInner,
+    });
+  });
+
+  it("persists a settled live turn when unmounted before history loads", async () => {
+    const { append, first } = createSlowLoadHarness();
+    await first.settle();
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(append).not.toHaveBeenCalled();
+
+    first.unmount();
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: "stored",
+      message: { id: "live", parts: ["reply"] },
+    });
+  });
+
+  it("reloads an unmounted settled turn after its earlier history on one branch", async () => {
+    const { append, first, mount, resolveLoad } = createSlowLoadHarness(false);
+    await first.settle();
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    first.unmount();
+    expect(append).not.toHaveBeenCalled();
+
+    await act(async () => resolveLoad());
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    const second = mount();
+    await waitFor(() => expect(second.importMessages).toHaveBeenCalledTimes(1));
+    const imported = second.importMessages.mock.calls[0]![0];
+    const repository = new MessageRepository();
+    repository.import(imported);
+
+    expect(imported.headId).toBe("live");
+    expect(
+      imported.messages.map((item) => [item.parentId, item.message.id]),
+    ).toEqual([
+      [null, "stored"],
+      ["stored", "live"],
+    ]);
+    expect(repository.getMessages().map((message) => message.id)).toEqual([
+      "stored",
+      "live",
+    ]);
+  });
+
+  it("persists an unmounted settled turn when loaded history is empty", async () => {
+    const { append, first, resolveEmptyLoad } = createSlowLoadHarness(false);
+    await first.settle();
+    first.unmount();
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(append).not.toHaveBeenCalled();
+
+    await act(async () => resolveEmptyLoad());
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: { id: "live", parts: ["reply"] },
+    });
+  });
+
+  it("persists an unmounted settled turn when history loading fails", async () => {
+    const { append, first, rejectLoad } = createSlowLoadHarness(false);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    onTestFinished(() => errorSpy.mockRestore());
+    await first.settle();
+    first.unmount();
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(append).not.toHaveBeenCalled();
+
+    await act(async () => rejectLoad());
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: { id: "live", parts: ["reply"] },
+    });
+  });
+
+  it("reloads the persisted turn after its earlier history on one branch", async () => {
+    const { first, mount, settleBeforeLoad } = createSlowLoadHarness();
+    await settleBeforeLoad();
+    first.unmount();
+
+    const second = mount();
+    await waitFor(() => expect(second.importMessages).toHaveBeenCalledTimes(1));
+    const imported = second.importMessages.mock.calls[0]![0];
+    const repository = new MessageRepository();
+    repository.import(imported);
+
+    expect(imported.headId).toBe("live");
+    expect(
+      imported.messages.map((item) => [item.parentId, item.message.id]),
+    ).toEqual([
+      [null, "stored"],
+      ["stored", "live"],
+    ]);
+    expect(repository.getMessages().map((message) => message.id)).toEqual([
+      "stored",
+      "live",
+    ]);
+  });
+
+  const createPersistenceHarness = (
+    supportsUpdate: boolean,
+    options?: {
+      loadMessages?: MessageFormatRepository<InnerMessage>;
+      toThreadMessages?: (messages: InnerMessage[]) => ThreadMessage[];
+      initialIsRunning?: boolean;
+      skipRemoteId?: boolean;
+      onSetMessages?: (messages: InnerMessage[]) => void;
+      toolArtifacts?: Map<string, unknown>;
+      onToolArtifactsRestored?: (next: Map<string, unknown>) => void;
+      toolInteractions?: Map<string, Unstable_ToolInteractionLog>;
+      onToolInteractionsRestored?: (
+        next: Map<string, Unstable_ToolInteractionLog>,
+      ) => void;
+      toolApprovalResponses?: Map<string, RespondToToolApprovalOptions>;
+      onToolApprovalResponsesRestored?: () => void;
+    },
+  ) => {
+    const append = vi.fn(
+      async (_item: { parentId: string | null; message: InnerMessage }) => {},
+    );
+    const update = vi.fn(
+      async (
+        _item: { parentId: string | null; message: InnerMessage },
+        _localMessageId: string,
+      ) => {},
+    );
+    const deleteItems = vi.fn(
+      async (
+        _items: { parentId: string | null; message: InnerMessage }[],
+      ) => {},
+    );
+    const reportTelemetry = vi.fn();
+    const load = vi
+      .fn()
+      .mockResolvedValue(options?.loadMessages ?? { messages: [] });
+    const formattedAdapter = {
+      load,
+      append,
+      delete: deleteItems,
+      reportTelemetry,
+      ...(supportsUpdate ? { update } : {}),
+    };
+    const historyAdapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue(formattedAdapter),
+    };
+
+    let listener: (() => void) | undefined;
+    let isRunning = options?.initialIsRunning ?? false;
+    let messages: ThreadMessage[] = [];
+    const getState = vi.fn(() => ({ isRunning, messages }));
+    const importMessages = vi.fn();
+    const thread = {
+      subscribe: (nextListener: () => void) => {
+        listener = nextListener;
+        return () => {};
+      },
+      getState,
+      import: importMessages,
+      export: vi.fn(() => ({ headId: null, messages: [] })),
+    } as unknown as AssistantRuntime["thread"];
+    const persistenceRuntimeRef = {
+      current: { thread } as AssistantRuntime,
+    };
+
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = options?.skipRemoteId ? undefined : "remote-thread";
+
+    const { result, unmount } = renderHook(() =>
+      useExternalHistory(
+        persistenceRuntimeRef,
+        historyAdapter,
+        options?.toThreadMessages ?? (() => []),
+        persistenceStorageFormat,
+        options?.onSetMessages ?? (() => {}),
+        options?.toolArtifacts && (() => options.toolArtifacts!),
+        (next) => {
+          options?.toolArtifacts?.clear();
+          for (const [id, artifact] of next)
+            options?.toolArtifacts?.set(id, artifact);
+          options?.onToolArtifactsRestored?.(next);
+        },
+        options?.toolInteractions && (() => options.toolInteractions!),
+        (next) => {
+          options?.toolInteractions?.clear();
+          for (const [id, log] of next) options?.toolInteractions?.set(id, log);
+          options?.onToolInteractionsRestored?.(next);
+        },
+        options?.toolApprovalResponses,
+        options?.onToolApprovalResponsesRestored,
+      ),
+    );
+
+    const runCycle = async (nextMessages: ThreadMessage[]) => {
+      await act(async () => {
+        messages = nextMessages;
+        isRunning = true;
+        listener?.();
+      });
+      await act(async () => {
+        isRunning = false;
+        listener?.();
+      });
+    };
+
+    const flush = () =>
+      act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+
+    const step = (partial: {
+      isRunning?: boolean;
+      messages?: ThreadMessage[];
+    }) =>
+      act(async () => {
+        if (partial.messages !== undefined) messages = partial.messages;
+        if (partial.isRunning !== undefined) isRunning = partial.isRunning;
+        listener?.();
+      });
+
+    return {
+      append,
+      update,
+      deleteItems,
+      formattedAdapter,
+      importMessages,
+      deleteMessage: result.current.deleteMessage,
+      markRunCancelled: () => result.current.markRunCancelled(),
+      reportTelemetry,
+      load,
+      persistToolInteractions: result.current.persistToolInteractions,
+      persistToolApprovalResponses: result.current.persistToolApprovalResponses,
+      runCycle,
+      flush,
+      step,
+      unmount,
+    };
+  };
+
+  it("clears tool data and invokes restore callbacks when loaded history is empty", async () => {
+    const toolArtifacts = new Map<string, unknown>([
+      ["call-1", { preview: "72°F and sunny" }],
+    ]);
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>([
+      ["call-1", { entries: [{ type: "action", occurredAt: 1, payload: {} }] }],
+    ]);
+    const toolApprovalResponses = new Map<string, RespondToToolApprovalOptions>(
+      [["approval-1", { approvalId: "approval-1", approved: true }]],
+    );
+    const onToolArtifactsRestored = vi.fn();
+    const onToolInteractionsRestored = vi.fn();
+    const onToolApprovalResponsesRestored = vi.fn();
+    const { importMessages, load } = createPersistenceHarness(false, {
+      loadMessages: { messages: [] },
+      toolArtifacts,
+      onToolArtifactsRestored,
+      toolInteractions,
+      onToolInteractionsRestored,
+      toolApprovalResponses,
+      onToolApprovalResponsesRestored,
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+
+    expect(toolArtifacts).toEqual(new Map());
+    expect(toolInteractions).toEqual(new Map());
+    expect(toolApprovalResponses).toEqual(new Map());
+    expect(onToolArtifactsRestored).toHaveBeenCalledOnce();
+    expect(onToolInteractionsRestored).toHaveBeenCalledOnce();
+    expect(onToolApprovalResponsesRestored).toHaveBeenCalledOnce();
+    expect(importMessages).not.toHaveBeenCalled();
+  });
+
+  it("persists a message that lands while the thread is idle", async () => {
+    const { append, step } = createPersistenceHarness(false);
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "spoken-1", parts: ["spoken"] }],
+    );
+
+    await step({ messages: [message] });
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: { id: "spoken-1", parts: ["spoken"] },
+    });
+  });
+
+  it("persists a settled turn without a remote history load", async () => {
+    const { append, load, runCycle } = createPersistenceHarness(false, {
+      skipRemoteId: true,
+    });
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "local", parts: ["reply"] }],
+    );
+
+    await runCycle([message]);
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(load).not.toHaveBeenCalled();
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: { id: "local", parts: ["reply"] },
+    });
+  });
+
+  it("updates stored tool artifacts without mutating chat messages", async () => {
+    const toolArtifacts = new Map<string, unknown>();
+    const { append, update, runCycle } = createPersistenceHarness(true, {
+      toolArtifacts,
+    });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+          input: { city: "New York" },
+          output: { temperature: 72 },
+        },
+      ],
+    };
+    const content: ThreadAssistantMessage["content"] = [
+      {
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "weather",
+        args: { city: "New York" },
+        argsText: '{"city":"New York"}',
+        result: { temperature: 72 },
+        isError: false,
+      },
+    ];
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      { content },
+    );
+
+    await runCycle([message]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: innerMessage,
+    });
+
+    toolArtifacts.set("call-1", { preview: "72°F and sunny" });
+    await runCycle([message]);
+
+    await waitFor(() =>
+      expect(update).toHaveBeenCalledWith(
+        {
+          parentId: null,
+          message: {
+            ...innerMessage,
+            metadata: {
+              __aui_toolArtifacts: {
+                "call-1": { preview: "72°F and sunny" },
+              },
+            },
+          },
+        },
+        "inner-a",
+      ),
+    );
+    expect(innerMessage.metadata).toBeUndefined();
+  });
+
+  it.each([
+    [
+      "a stopped run whose prompt core moved to the composer",
+      true,
+      [],
+      "cancelled",
+      true,
+    ],
+    [
+      "a stopped run whose prompt the composer could not take back",
+      true,
+      [createUserMessage(stoppedPrompt)],
+      "cancelled",
+      false,
+    ],
+    [
+      "a run that settled without output",
+      false,
+      [createUserMessage(stoppedPrompt)],
+      "other",
+      false,
+    ],
+    [
+      "a run that settled without output after its prompt disappeared",
+      false,
+      [],
+      "other",
+      false,
+    ],
+  ] as const)(
+    "reports %s",
+    async (
+      _,
+      cancelled,
+      settledMessages: readonly ThreadMessage[],
+      reason,
+      shouldDelete,
+    ) => {
+      const {
+        append,
+        deleteItems,
+        load,
+        markRunCancelled,
+        reportTelemetry,
+        step,
+        flush,
+      } = createPersistenceHarness(false);
+      await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+
+      await step({
+        isRunning: true,
+        messages: [createUserMessage(stoppedPrompt)],
+      });
+      await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+      if (cancelled) markRunCancelled();
+      await step({ isRunning: false, messages: [...settledMessages] });
+      await flush();
+
+      await waitFor(() =>
+        expect(reportTelemetry).toHaveBeenCalledWith(
+          [],
+          expect.objectContaining({
+            message: expect.objectContaining({
+              role: "assistant",
+              status: { type: "incomplete", reason },
+            }),
+          }),
+        ),
+      );
+      expect(
+        reportTelemetry.mock.calls.filter(
+          ([, options]) => options?.message?.role === "assistant",
+        ),
+      ).toHaveLength(1);
+      if (shouldDelete) {
+        expect(deleteItems).toHaveBeenCalledOnce();
+        expect(deleteItems).toHaveBeenCalledWith([
+          { parentId: null, message: stoppedPrompt },
+        ]);
+      } else {
+        expect(deleteItems).not.toHaveBeenCalled();
+      }
+    },
+  );
+
+  it("reports a reply that waited for tool approval with the prompt it answers", async () => {
+    const { load, reportTelemetry, step, flush } =
+      createPersistenceHarness(true);
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    const first = createUserMessage({
+      id: "user-1",
+      role: "user",
+      parts: ["first"],
+    });
+    const second = createUserMessage({
+      id: "user-2",
+      role: "user",
+      parts: ["second"],
+    });
+
+    await step({ isRunning: true, messages: [first] });
+    await step({
+      isRunning: false,
+      messages: [
+        first,
+        createAssistantMessage(
+          { type: "requires-action", reason: "tool-calls" },
+          [{ id: "inner-a", parts: ["pending"] }],
+          "assistant-a",
+        ),
+      ],
+    });
+    await flush();
+    await step({
+      isRunning: true,
+      messages: [
+        first,
+        createAssistantMessage(
+          { type: "requires-action", reason: "tool-calls" },
+          [{ id: "inner-a", parts: ["pending"] }],
+          "assistant-a",
+        ),
+        second,
+      ],
+    });
+    await step({
+      isRunning: false,
+      messages: [
+        first,
+        createAssistantMessage(
+          { type: "complete", reason: "stop" },
+          [{ id: "inner-a", parts: ["pending", "final"] }],
+          "assistant-a",
+        ),
+        second,
+        createAssistantMessage(
+          { type: "complete", reason: "stop" },
+          [{ id: "inner-b", parts: ["answer"] }],
+          "assistant-b",
+        ),
+      ],
+    });
+    await flush();
+
+    const reportedPrompts = () =>
+      Object.fromEntries(
+        reportTelemetry.mock.calls
+          .filter(([, options]) => options?.message?.role === "assistant")
+          .map(([, options]) => [options.message.id, options.userMessageId]),
+      );
+    await waitFor(() =>
+      expect(reportedPrompts()).toEqual({
+        "assistant-a": "user-1",
+        "assistant-b": "user-2",
+      }),
+    );
+  });
+
+  it("reports an unanswered cancelled run even when prompt deletion fails", async () => {
+    const {
+      append,
+      deleteItems,
+      load,
+      markRunCancelled,
+      reportTelemetry,
+      step,
+      flush,
+    } = createPersistenceHarness(false);
+    const failure = new Error("delete failed");
+    deleteItems.mockRejectedValueOnce(failure);
+    const log = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await waitFor(() => expect(load).toHaveBeenCalledOnce());
+      await step({
+        isRunning: true,
+        messages: [createUserMessage(stoppedPrompt)],
+      });
+      await waitFor(() => expect(append).toHaveBeenCalledOnce());
+      markRunCancelled();
+      await step({ isRunning: false, messages: [] });
+      await flush();
+      expect(deleteItems).toHaveBeenCalledOnce();
+      expect(log).toHaveBeenCalledWith(
+        "Failed to delete message history:",
+        failure,
+      );
+      expect(reportTelemetry).toHaveBeenCalledWith(
+        [],
+        expect.objectContaining({
+          message: expect.objectContaining({
+            status: { type: "incomplete", reason: "cancelled" },
+          }),
+        }),
+      );
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  it("reports a run stopped while history is still loading", async () => {
+    const { first, reportTelemetry, resolveEmptyLoad } =
+      createSlowLoadHarness(false);
+
+    await first.step({
+      isRunning: true,
+      messages: [createUserMessage(stoppedPrompt)],
+    });
+    first.result.current.markRunCancelled();
+    await first.step({ isRunning: false, messages: [] });
+    await act(async () => {
+      resolveEmptyLoad();
+    });
+
+    await waitFor(() =>
+      expect(reportTelemetry).toHaveBeenCalledWith(
+        [],
+        expect.objectContaining({
+          message: expect.objectContaining({
+            status: { type: "incomplete", reason: "cancelled" },
+          }),
+        }),
+      ),
+    );
+  });
+
+  it("reports only the reply of a run that answered its prompt", async () => {
+    const { load, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    const reply = createAssistantMessage({ type: "complete", reason: "stop" }, [
+      { id: "assistant-1", role: "assistant", parts: ["hi"] },
+    ]);
+
+    await runCycle([createUserMessage(stoppedPrompt), reply]);
+    await flush();
+
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalled());
+    expect(
+      reportTelemetry.mock.calls.filter(
+        ([, options]) => options?.message?.role === "assistant",
+      ),
+    ).toEqual([
+      [expect.any(Array), expect.objectContaining({ message: reply })],
+    ]);
+  });
+
+  it("keeps tool artifacts out of run telemetry", async () => {
+    const toolArtifacts = new Map<string, unknown>([
+      ["call-1", { preview: "72°F and sunny" }],
+    ]);
+    const { append, load, reportTelemetry, runCycle } =
+      createPersistenceHarness(false, { toolArtifacts });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: { temperature: 72 },
+            isError: false,
+          },
+        ],
+      },
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    toolArtifacts.set("call-1", { preview: "72°F and sunny" });
+
+    await runCycle([message]);
+
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(1));
+    expect(append.mock.calls[0]?.[0].message).toHaveProperty(
+      "metadata.__aui_toolArtifacts",
+    );
+    expect(reportTelemetry.mock.calls[0]?.[0]).toEqual([
+      { parentId: null, message: innerMessage },
+    ]);
+  });
+
+  it("keeps tool interactions and approval responses out of run telemetry", async () => {
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>([
+      [
+        "call-1",
+        {
+          entries: [
+            {
+              type: "action",
+              occurredAt: 1,
+              payload: { refresh: true },
+            },
+          ],
+        },
+      ],
+    ]);
+    const toolApprovalResponses = new Map<string, RespondToToolApprovalOptions>(
+      [
+        [
+          "approval-1",
+          { approvalId: "approval-1", approved: true, reason: "Approved" },
+        ],
+      ],
+    );
+    const { append, load, reportTelemetry, runCycle } =
+      createPersistenceHarness(false, {
+        toolInteractions,
+        toolApprovalResponses,
+      });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+        {
+          type: "tool-deploy",
+          toolCallId: "call-2",
+          state: "approval-requested",
+          approval: { id: "approval-1" },
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: { temperature: 72 },
+            isError: false,
+          },
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-2",
+            toolName: "deploy",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+            approval: { id: "approval-1" },
+          },
+        ],
+      },
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    toolInteractions.set("call-1", {
+      entries: [
+        {
+          type: "action",
+          occurredAt: 1,
+          payload: { refresh: true },
+        },
+      ],
+    });
+    toolApprovalResponses.set("approval-1", {
+      approvalId: "approval-1",
+      approved: true,
+      reason: "Approved",
+    });
+
+    await runCycle([message]);
+
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(1));
+    expect(append.mock.calls[0]?.[0].message).toMatchObject({
+      metadata: {
+        __aui_toolInteractions: { "call-1": toolInteractions.get("call-1") },
+        __aui_toolApprovalResponses: {
+          "approval-1": { approved: true, reason: "Approved" },
+        },
+      },
+    });
+    expect(reportTelemetry.mock.calls[0]?.[0]).toEqual([
+      { parentId: null, message: innerMessage },
+    ]);
+  });
+
+  it("stores host approval responses with the first message write", async () => {
+    const toolApprovalResponses = new Map<string, RespondToToolApprovalOptions>(
+      [
+        [
+          "approval-1",
+          {
+            approvalId: "approval-1",
+            approved: true,
+            optionId: "allow-once",
+            text: "Staging only",
+            reason: "Approved by operator",
+          },
+        ],
+      ],
+    );
+    const { append, load, runCycle } = createPersistenceHarness(false, {
+      toolApprovalResponses,
+    });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-deploy",
+          toolCallId: "call-1",
+          state: "approval-requested",
+          approval: { id: "approval-1" },
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "deploy",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+            approval: { id: "approval-1" },
+          },
+        ],
+      },
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    toolApprovalResponses.set("approval-1", {
+      approvalId: "approval-1",
+      approved: true,
+      optionId: "allow-once",
+      text: "Staging only",
+      reason: "Approved by operator",
+    });
+
+    await runCycle([message]);
+
+    await waitFor(() =>
+      expect(append).toHaveBeenCalledWith({
+        parentId: null,
+        message: {
+          ...innerMessage,
+          metadata: {
+            __aui_toolApprovalResponses: {
+              "approval-1": {
+                approved: true,
+                optionId: "allow-once",
+                text: "Staging only",
+                reason: "Approved by operator",
+              },
+            },
+          },
+        },
+      }),
+    );
+    expect(innerMessage.metadata).toBeUndefined();
+  });
+
+  it("logs and retries a failed host approval response update after a settled run", async () => {
+    const toolApprovalResponses = new Map<
+      string,
+      RespondToToolApprovalOptions
+    >();
+    const { append, update, persistToolApprovalResponses, runCycle } =
+      createPersistenceHarness(true, { toolApprovalResponses });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-deploy",
+          toolCallId: "call-1",
+          state: "approval-requested",
+          approval: { id: "approval-1" },
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "deploy",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+            approval: { id: "approval-1" },
+          },
+        ],
+      },
+    );
+
+    await runCycle([message]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    toolApprovalResponses.set("approval-1", {
+      approvalId: "approval-1",
+      approved: false,
+      reason: "Not now",
+    });
+    const failure = new Error("storage unavailable");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    update.mockRejectedValueOnce(failure);
+
+    try {
+      await act(async () => {
+        await persistToolApprovalResponses("inner-a");
+      });
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Failed to persist tool data:",
+        failure,
+      );
+      await act(async () => {
+        await persistToolApprovalResponses("inner-a");
+      });
+
+      expect(update).toHaveBeenCalledTimes(2);
+      expect(update).toHaveBeenLastCalledWith(
+        {
+          parentId: null,
+          message: {
+            ...innerMessage,
+            metadata: {
+              __aui_toolApprovalResponses: {
+                "approval-1": { approved: false, reason: "Not now" },
+              },
+            },
+          },
+        },
+        "inner-a",
+      );
+      expect(append).toHaveBeenCalledTimes(1);
+      expect(innerMessage.metadata).toBeUndefined();
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("stores tool interactions with the first message write", async () => {
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>([
+      [
+        "call-1",
+        {
+          entries: [
+            {
+              type: "action",
+              occurredAt: 1,
+              payload: { refresh: true },
+            },
+          ],
+        },
+      ],
+    ]);
+    const { append, load, runCycle } = createPersistenceHarness(false, {
+      toolArtifacts: new Map(),
+      toolInteractions,
+    });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: { temperature: 72 },
+            isError: false,
+          },
+        ],
+      },
+    );
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    toolInteractions.set("call-1", {
+      entries: [
+        {
+          type: "action",
+          occurredAt: 1,
+          payload: { refresh: true },
+        },
+      ],
+    });
+
+    await runCycle([message]);
+
+    await waitFor(() =>
+      expect(append).toHaveBeenCalledWith({
+        parentId: null,
+        message: {
+          ...innerMessage,
+          metadata: {
+            __aui_toolInteractions: {
+              "call-1": toolInteractions.get("call-1"),
+            },
+          },
+        },
+      }),
+    );
+    expect(innerMessage.metadata).toBeUndefined();
+  });
+
+  it("leaves stored rows unchanged without tool artifacts", async () => {
+    const toolArtifacts = new Map<string, unknown>();
+    const { append, runCycle } = createPersistenceHarness(false, {
+      toolArtifacts,
+    });
+    const innerMessage = { id: "inner-a", parts: ["answer"] };
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [innerMessage],
+    );
+
+    await runCycle([message]);
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: innerMessage,
+    });
+    expect(append.mock.calls[0]?.[0].message).toBe(innerMessage);
+  });
+
+  it("logs and retries a failed tool interaction update after a settled run", async () => {
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const { append, update, persistToolInteractions, runCycle } =
+      createPersistenceHarness(true, { toolInteractions });
+    const initialInnerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+      ],
+    };
+    const createMessage = (innerMessage: InnerMessage) =>
+      Object.assign(
+        createAssistantMessage({ type: "complete", reason: "stop" }, [
+          innerMessage,
+        ]),
+        {
+          content: [
+            {
+              type: "tool-call" as const,
+              toolCallId: "call-1",
+              toolName: "weather",
+              args: {},
+              argsText: "{}",
+              result: undefined,
+              isError: false,
+            },
+          ],
+        },
+      );
+
+    await runCycle([createMessage(initialInnerMessage)]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    const log: Unstable_ToolInteractionLog = {
+      entries: [
+        {
+          type: "human-response",
+          occurredAt: 2,
+          payload: "yes",
+        },
+      ],
+    };
+    toolInteractions.set("call-1", log);
+    const failure = new Error("storage unavailable");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    update.mockRejectedValueOnce(failure);
+
+    try {
+      await act(async () => {
+        await persistToolInteractions("assistant-a");
+      });
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Failed to persist tool data:",
+        failure,
+      );
+      await act(async () => {
+        await persistToolInteractions("assistant-a");
+      });
+
+      expect(update).toHaveBeenCalledTimes(2);
+      expect(update).toHaveBeenLastCalledWith(
+        {
+          parentId: null,
+          message: {
+            ...initialInnerMessage,
+            metadata: {
+              __aui_toolInteractions: { "call-1": log },
+            },
+          },
+        },
+        "inner-a",
+      );
+      expect(append).toHaveBeenCalledTimes(1);
+
+      const rewrittenInnerMessage = {
+        ...initialInnerMessage,
+        parts: [...initialInnerMessage.parts, { type: "text", text: "done" }],
+      };
+      await runCycle([createMessage(rewrittenInnerMessage)]);
+
+      await waitFor(() =>
+        expect(update).toHaveBeenLastCalledWith(
+          {
+            parentId: null,
+            message: {
+              ...rewrittenInnerMessage,
+              metadata: {
+                __aui_toolInteractions: { "call-1": log },
+              },
+            },
+          },
+          "inner-a",
+        ),
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("leaves stored rows unchanged without tool artifacts or interactions", async () => {
+    const toolArtifacts = new Map<string, unknown>();
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const { append, runCycle } = createPersistenceHarness(false, {
+      toolArtifacts,
+      toolInteractions,
+    });
+    const innerMessage = {
+      id: "inner-a",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+          },
+        ],
+      },
+    );
+
+    await runCycle([message]);
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: innerMessage,
+    });
+    expect(append.mock.calls[0]?.[0].message).toBe(innerMessage);
+  });
+
+  it("restores stored tool interactions without returning metadata to the chat", async () => {
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const onSetMessages = vi.fn();
+    const log: Unstable_ToolInteractionLog = {
+      entries: [
+        {
+          type: "human-response",
+          occurredAt: 3,
+          payload: "yes",
+        },
+      ],
+    };
+    const storedMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+        },
+      ],
+      metadata: {
+        __aui_toolInteractions: { "call-1": log },
+      },
+    };
+    const { importMessages, load } = createPersistenceHarness(true, {
+      loadMessages: {
+        messages: [{ parentId: null, message: storedMessage }],
+      },
+      toThreadMessages: (messages) =>
+        messages.map((message) => {
+          const tool = message.parts[0] as { toolCallId: string };
+          const converted = createAssistantMessage(
+            { type: "complete", reason: "stop" },
+            [message],
+            message.id,
+          ) as ThreadAssistantMessage;
+          return Object.assign(converted, {
+            content: [
+              {
+                type: "tool-call" as const,
+                toolCallId: tool.toolCallId,
+                toolName: "weather",
+                args: {},
+                argsText: "{}",
+                result: undefined,
+                isError: false,
+                unstable_interactions: toolInteractions.get(tool.toolCallId),
+              },
+            ],
+          });
+        }),
+      onSetMessages,
+      toolInteractions,
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(importMessages).toHaveBeenCalledTimes(1));
+
+    const imported = importMessages.mock.calls[0]?.[0] as {
+      messages: { message: ThreadMessage }[];
+    };
+    expect(imported.messages[0]?.message.content[0]).toMatchObject({
+      type: "tool-call",
+      toolCallId: "call-1",
+      unstable_interactions: log,
+    });
+    expect(toolInteractions.get("call-1")).toEqual(log);
+    expect(onSetMessages.mock.calls[0]?.[0][0]).not.toHaveProperty(
+      "metadata.__aui_toolInteractions",
+    );
+  });
+
+  it("restores host approval responses without returning metadata to the chat", async () => {
+    const toolApprovalResponses = new Map<
+      string,
+      RespondToToolApprovalOptions
+    >();
+    const onSetMessages = vi.fn();
+    const storedMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-deploy",
+          toolCallId: "call-1",
+          state: "approval-requested",
+          approval: { id: "approval-1" },
+        },
+      ],
+      metadata: {
+        __aui_toolApprovalResponses: {
+          "approval-1": {
+            approved: true,
+            optionId: "allow-once",
+            text: "Staging only",
+            reason: "Approved by operator",
+          },
+        },
+      },
+    };
+    const { importMessages, load } = createPersistenceHarness(true, {
+      loadMessages: {
+        messages: [{ parentId: null, message: storedMessage }],
+      },
+      toThreadMessages: (messages) =>
+        messages.map((message) => {
+          const tool = message.parts[0] as {
+            toolCallId: string;
+            approval: { id: string };
+          };
+          const response = toolApprovalResponses.get(tool.approval.id);
+          const converted = createAssistantMessage(
+            { type: "complete", reason: "stop" },
+            [message],
+            message.id,
+          ) as ThreadAssistantMessage;
+          return Object.assign(converted, {
+            content: [
+              {
+                type: "tool-call" as const,
+                toolCallId: tool.toolCallId,
+                toolName: "deploy",
+                args: {},
+                argsText: "{}",
+                result: undefined,
+                isError: false,
+                approval: {
+                  id: tool.approval.id,
+                  ...(response && { approved: response.approved }),
+                  ...(response?.optionId && { optionId: response.optionId }),
+                  ...(response?.text && { text: response.text }),
+                  ...(response?.reason && { reason: response.reason }),
+                },
+              },
+            ],
+          });
+        }),
+      onSetMessages,
+      toolApprovalResponses,
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(importMessages).toHaveBeenCalledTimes(1));
+
+    const imported = importMessages.mock.calls[0]?.[0] as {
+      messages: { message: ThreadMessage }[];
+    };
+    expect(imported.messages[0]?.message.content[0]).toMatchObject({
+      type: "tool-call",
+      toolCallId: "call-1",
+      approval: {
+        id: "approval-1",
+        approved: true,
+        optionId: "allow-once",
+        text: "Staging only",
+        reason: "Approved by operator",
+      },
+    });
+    expect(toolApprovalResponses.get("approval-1")).toEqual({
+      approvalId: "approval-1",
+      approved: true,
+      optionId: "allow-once",
+      text: "Staging only",
+      reason: "Approved by operator",
+    });
+    expect(onSetMessages.mock.calls[0]?.[0][0]).not.toHaveProperty(
+      "metadata.__aui_toolApprovalResponses",
+    );
+  });
+
+  it("stores and restores questionnaire answers with the approval response", async () => {
+    const answers = {
+      scope: { optionIds: ["src", "tests"] },
+      note: { text: "keep it short" },
+    };
+    const saved = new Map<string, RespondToToolApprovalOptions>();
+    const writer = createPersistenceHarness(false, {
+      toolApprovalResponses: saved,
+    });
+    const innerMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-ask",
+          toolCallId: "call-1",
+          state: "approval-requested",
+          approval: { id: "approval-1" },
+        },
+      ],
+    };
+    const message = Object.assign(
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "ask",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+            approval: { id: "approval-1" },
+          },
+        ],
+      },
+    );
+    await waitFor(() => expect(writer.load).toHaveBeenCalledTimes(1));
+    saved.set("approval-1", {
+      approvalId: "approval-1",
+      approved: true,
+      answers,
+    });
+    await writer.runCycle([message]);
+    await waitFor(() =>
+      expect(writer.append).toHaveBeenCalledWith({
+        parentId: null,
+        message: {
+          ...innerMessage,
+          metadata: {
+            __aui_toolApprovalResponses: {
+              "approval-1": { approved: true, answers },
+            },
+          },
+        },
+      }),
+    );
+    writer.unmount();
+
+    const restored = new Map<string, RespondToToolApprovalOptions>();
+    const reader = createPersistenceHarness(true, {
+      loadMessages: {
+        messages: [
+          {
+            parentId: null,
+            message: {
+              ...innerMessage,
+              metadata: {
+                __aui_toolApprovalResponses: {
+                  "approval-1": {
+                    approved: true,
+                    answers: { ...answers, junk: { optionIds: [1] } },
+                  },
+                },
+              },
+            },
+          },
+        ],
+      },
+      toolApprovalResponses: restored,
+    });
+    await waitFor(() => expect(reader.load).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(restored.get("approval-1")).toEqual({
+        approvalId: "approval-1",
+        approved: true,
+        answers,
+      }),
+    );
+  });
+
+  it("restores stored tool artifacts without returning metadata to the chat", async () => {
+    const toolArtifacts = new Map<string, unknown>();
+    const onSetMessages = vi.fn();
+    const storedMessage: InnerMessage = {
+      id: "inner-a",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-weather",
+          toolCallId: "call-1",
+          state: "output-available",
+          input: { city: "New York" },
+          output: { temperature: 72 },
+        },
+      ],
+      metadata: {
+        __aui_toolArtifacts: {
+          "call-1": { preview: "72°F and sunny" },
+        },
+      },
+    };
+    const { importMessages, load } = createPersistenceHarness(true, {
+      loadMessages: {
+        messages: [{ parentId: null, message: storedMessage }],
+      },
+      toThreadMessages: (messages) =>
+        messages.map((message) => {
+          const tool = message.parts[0] as { toolCallId: string };
+          const converted = createAssistantMessage(
+            { type: "complete", reason: "stop" },
+            [message],
+            message.id,
+          ) as ThreadAssistantMessage;
+          return Object.assign(converted, {
+            content: [
+              {
+                type: "tool-call" as const,
+                toolCallId: tool.toolCallId,
+                toolName: "weather",
+                args: { city: "New York" },
+                argsText: '{"city":"New York"}',
+                result: { temperature: 72 },
+                isError: false,
+                artifact: toolArtifacts.get(tool.toolCallId),
+              },
+            ],
+          });
+        }),
+      onSetMessages,
+      toolArtifacts,
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(importMessages).toHaveBeenCalledTimes(1));
+
+    const imported = importMessages.mock.calls[0]?.[0] as {
+      messages: { message: ThreadMessage }[];
+    };
+    expect(imported.messages[0]?.message.content[0]).toMatchObject({
+      type: "tool-call",
+      toolCallId: "call-1",
+      artifact: { preview: "72°F and sunny" },
+    });
+    expect(toolArtifacts.get("call-1")).toEqual({
+      preview: "72°F and sunny",
+    });
+    expect(onSetMessages.mock.calls[0]?.[0][0]).not.toHaveProperty(
+      "metadata.__aui_toolArtifacts",
+    );
+  });
+
+  it("schedules one idle persistence attempt per landed message when append fails", async () => {
+    const { append, step, flush } = createPersistenceHarness(false);
+    append.mockRejectedValueOnce(new Error("offline"));
+    const first = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "spoken-1", parts: ["first"] }],
+      "assistant-a",
+    );
+
+    await step({ messages: [first] });
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    await step({ messages: [first] });
+    await step({ messages: [first] });
+    await flush();
+    expect(append).toHaveBeenCalledTimes(1);
+
+    const second = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "spoken-2", parts: ["second"] }],
+      "assistant-b",
+    );
+    await step({ messages: [first, second] });
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(3));
+    expect(append.mock.calls.map(([item]) => item)).toEqual([
+      { parentId: null, message: { id: "spoken-1", parts: ["first"] } },
+      { parentId: null, message: { id: "spoken-1", parts: ["first"] } },
+      { parentId: "spoken-1", message: { id: "spoken-2", parts: ["second"] } },
+    ]);
+  });
+
+  it("persists a settled turn when the history adapter becomes active after it", async () => {
+    let listener: (() => void) | undefined;
+    let isRunning = false;
+    let messages: ThreadMessage[] = [];
+    const append = vi.fn(async () => {});
+    const formattedAdapter = {
+      load: vi.fn().mockResolvedValue({ messages: [] }),
+      append,
+    };
+    const historyAdapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue(formattedAdapter),
+    };
+    let activeAdapter: ThreadHistoryAdapter | undefined;
+    const thread = {
+      subscribe: (next: () => void) => {
+        listener = next;
+        return () => {};
+      },
+      getState: () => ({ isRunning, messages }),
+      import: vi.fn(),
+      export: vi.fn(() => ({ headId: null, messages: [] })),
+    } as unknown as AssistantRuntime["thread"];
+    const persistenceRuntimeRef = {
+      current: { thread } as AssistantRuntime,
+    };
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-1", parts: ["answer"] }],
+    );
+
+    mocks.hasThreadListItem = true;
+    mocks.remoteId = "remote-thread";
+
+    const { rerender } = renderHook(() =>
+      useExternalHistory(
+        persistenceRuntimeRef,
+        activeAdapter,
+        () => [],
+        persistenceStorageFormat,
+        () => {},
+      ),
+    );
+
+    await act(async () => {
+      messages = [message];
+      isRunning = true;
+      listener?.();
+      isRunning = false;
+      listener?.();
+    });
+
+    activeAdapter = historyAdapter;
+    await act(async () => rerender());
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: { id: "inner-1", parts: ["answer"] },
+    });
+  });
+
+  it("persists a turn that is already running when the subscription starts", async () => {
+    const { append, step } = createPersistenceHarness(false, {
+      initialIsRunning: true,
+    });
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-1", parts: ["answer"] }],
+    );
+
+    await step({ isRunning: false, messages: [message] });
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+  });
+
+  it("persists a prompt that reaches the thread after its run started", async () => {
+    const { append, flush, load, step } = createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    const promptInner: InnerMessage = {
+      id: "late-prompt",
+      role: "user",
+      parts: ["prompt"],
+    };
+
+    await step({ isRunning: true, messages: [] });
+    await step({ messages: [createUserMessage(promptInner)] });
+
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    expect(append).toHaveBeenCalledWith({
+      parentId: null,
+      message: promptInner,
+    });
+  });
+
+  it("retries an unstored prompt when the next run starts", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+    const { append, flush, load, step } = createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    append
+      .mockRejectedValueOnce(new Error("temporary storage failure"))
+      .mockRejectedValueOnce(new Error("temporary storage failure"));
+    const promptInner: InnerMessage = {
+      id: "user-retry",
+      role: "user",
+      parts: ["prompt"],
+    };
+    const prompt = createUserMessage(promptInner);
+
+    await step({ isRunning: true, messages: [prompt] });
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+    await step({ isRunning: false, messages: [prompt] });
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    await step({ isRunning: true, messages: [prompt] });
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(3));
+    expect(append).toHaveBeenLastCalledWith({
+      parentId: null,
+      message: promptInner,
+    });
+  });
+
+  it("persists a new user message while its run is active", async () => {
+    const previousInner: InnerMessage = {
+      id: "previous-assistant",
+      parts: ["previous"],
+    };
+    const userInner: InnerMessage = {
+      id: "user-1",
+      role: "user",
+      parts: ["prompt"],
+    };
+    const previous = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [previousInner],
+      "previous-assistant",
+    );
+    const user = {
+      id: "user-1",
+      role: "user",
+      content: [],
+    } as unknown as ThreadMessage;
+    bindExternalStoreMessage(user, userInner);
+    const partialInner: InnerMessage = {
+      id: "assistant-1",
+      role: "assistant",
+      parts: ["partial"],
+    };
+    const partialAssistant = createAssistantMessage(
+      { type: "running" },
+      [partialInner],
+      "assistant-1",
+    );
+    const { append, flush, load, step } = createPersistenceHarness(false, {
+      loadMessages: {
+        headId: previousInner.id,
+        messages: [{ parentId: null, message: previousInner }],
+      },
+      toThreadMessages: (messages) =>
+        messages.map((message) =>
+          createAssistantMessage(
+            { type: "complete", reason: "stop" },
+            [message],
+            message.id,
+          ),
+        ),
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+
+    await step({
+      isRunning: true,
+      messages: [previous, user, partialAssistant],
+    });
+
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    expect(append).toHaveBeenCalledWith({
+      parentId: previousInner.id,
+      message: userInner,
+    });
+
+    const completeAssistant = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ ...partialInner, parts: ["complete"] }],
+      "assistant-1",
+    );
+    await step({
+      isRunning: false,
+      messages: [previous, user, completeAssistant],
+    });
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    expect(append).toHaveBeenNthCalledWith(1, {
+      parentId: previousInner.id,
+      message: userInner,
+    });
+    expect(append).toHaveBeenNthCalledWith(2, {
+      parentId: userInner.id,
+      message: { ...partialInner, parts: ["complete"] },
+    });
+  });
+
+  it("keeps a prompt deleted during its pending write deleted after the subscription restarts", async () => {
+    type Item = { parentId: string | null; message: InnerMessage };
+    const stored = new Map<string, Item>();
+    let releaseAppend!: () => void;
+    const appendGate = new Promise<void>((resolve) => {
+      releaseAppend = resolve;
+    });
+    const adapter: ThreadHistoryAdapter = {
+      load: vi.fn(),
+      append: vi.fn(),
+      withFormat: vi.fn().mockReturnValue({
+        load: async () => ({ messages: [] }),
+        append: async (item: Item) => {
+          await appendGate;
+          stored.set(item.message.id, item);
+        },
+        delete: async (items: Item[]) => {
+          for (const item of items) stored.delete(item.message.id);
+        },
+      }),
+    };
+    let listener = () => {};
+    let isRunning = false;
+    let messages: ThreadMessage[] = [];
+    const deletionRuntimeRef = {
+      current: {
+        thread: {
+          getState: () => ({ isRunning, messages }),
+          subscribe: (next: () => void) => {
+            listener = next;
+            return () => {};
+          },
+        },
+      } as unknown as AssistantRuntime,
+    };
+    const hook = renderHook(
+      ({ toolArtifacts }) =>
+        useExternalHistory(
+          deletionRuntimeRef,
+          adapter,
+          () => [],
+          persistenceStorageFormat,
+          () => {},
+          () => toolArtifacts,
+        ),
+      { initialProps: { toolArtifacts: new Map<string, unknown>() } },
+    );
+    const user = createUserMessage({
+      id: "user-1",
+      role: "user",
+      parts: ["prompt"],
+    });
+
+    await act(async () => {
+      messages = [user];
+      isRunning = true;
+      listener();
+    });
+    const deletion = hook.result.current.deleteMessage("user-1");
+    hook.rerender({ toolArtifacts: new Map() });
+    await act(async () => {
+      releaseAppend();
+      await deletion;
+      messages = [];
+      listener();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    expect(stored.has("user-1")).toBe(false);
+  });
+
+  const createDeletionRace = async () => {
+    const { append, deleteItems, deleteMessage, flush, load, step } =
+      createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    const stored = new Set<string>();
+    let releaseReply!: () => void;
+    const replyGate = new Promise<void>((resolve) => {
+      releaseReply = resolve;
+    });
+    append.mockImplementation(async (item) => {
+      if (item.message.id === "reply-a") await replyGate;
+      stored.add(item.message.id);
+    });
+    deleteItems.mockImplementation(async (items) => {
+      for (const item of items) stored.delete(item.message.id);
+    });
+    const promptA = createUserMessage({
+      id: "prompt-a",
+      role: "user",
+      parts: [],
+    });
+    const replyAInner: InnerMessage = { id: "reply-a", parts: ["a"] };
+    const replyA = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [replyAInner],
+      "reply-a",
+    );
+    const promptB = createUserMessage({
+      id: "prompt-b",
+      role: "user",
+      parts: [],
+    });
+    const replyBInner: InnerMessage = { id: "reply-b", parts: ["b"] };
+
+    await step({
+      isRunning: true,
+      messages: [
+        promptA,
+        createAssistantMessage({ type: "running" }, [replyAInner], "reply-a"),
+      ],
+    });
+    await step({ isRunning: false, messages: [promptA, replyA] });
+    await flush();
+    const deletion = deleteMessage("prompt-a");
+
+    return {
+      stored,
+      startNextRun: () =>
+        step({
+          isRunning: true,
+          messages: [
+            promptA,
+            replyA,
+            promptB,
+            createAssistantMessage(
+              { type: "running" },
+              [replyBInner],
+              "reply-b",
+            ),
+          ],
+        }),
+      settleNextRun: async () => {
+        await step({
+          isRunning: false,
+          messages: [
+            promptA,
+            replyA,
+            promptB,
+            createAssistantMessage(
+              { type: "complete", reason: "stop" },
+              [replyBInner],
+              "reply-b",
+            ),
+          ],
+        });
+        await flush();
+      },
+      finishDeletion: async () => {
+        releaseReply();
+        await act(async () => {
+          await deletion;
+        });
+        await flush();
+      },
+    };
+  };
+
+  it("keeps a prompt deleted when the next run starts before its deletion lands", async () => {
+    const race = await createDeletionRace();
+
+    await race.startNextRun();
+    await race.finishDeletion();
+
+    expect([...race.stored]).toEqual(["reply-a", "prompt-b"]);
+  });
+
+  it("keeps a prompt deleted when the next run settles before its deletion lands", async () => {
+    const race = await createDeletionRace();
+
+    await race.startNextRun();
+    await race.settleNextRun();
+    await race.finishDeletion();
+
+    expect([...race.stored]).toEqual(["reply-a", "prompt-b", "reply-b"]);
+  });
+
+  it("keeps a prompt deleted during its run when the run resumes before the prompt leaves the chat", async () => {
+    const { append, deleteItems, deleteMessage, flush, load, step } =
+      createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    const prompt = createUserMessage({
+      id: "prompt",
+      role: "user",
+      parts: ["prompt"],
+    });
+
+    await step({
+      isRunning: true,
+      messages: [
+        prompt,
+        createAssistantMessage(
+          { type: "running" },
+          [{ id: "reply", parts: [] }],
+          "reply",
+        ),
+      ],
+    });
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    await act(async () => {
+      await deleteMessage("prompt");
+    });
+    expect(deleteItems).toHaveBeenCalledOnce();
+    await step({ isRunning: false });
+    await step({ isRunning: true });
+    await flush();
+
+    expect(append).toHaveBeenCalledOnce();
+  });
+
+  it("stores a message that reuses a deleted id once the deleted one has left the chat", async () => {
+    const { append, deleteItems, deleteMessage, flush, load, runCycle, step } =
+      createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    await runCycle([
+      createAssistantMessage(
+        { type: "complete", reason: "stop" },
+        [{ id: "reused", parts: ["old"] }],
+        "reused",
+      ),
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    await act(async () => {
+      await deleteMessage("reused");
+    });
+    expect(deleteItems).toHaveBeenCalledOnce();
+    await step({ messages: [] });
+    await flush();
+
+    const replacementInner: InnerMessage = { id: "reused", parts: ["new"] };
+    await runCycle([
+      createAssistantMessage(
+        { type: "complete", reason: "stop" },
+        [replacementInner],
+        "reused",
+      ),
+    ]);
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    expect(append).toHaveBeenLastCalledWith({
+      parentId: null,
+      message: replacementInner,
+    });
+  });
+
+  it("releases a deleted message that left the chat before its delete resolved", async () => {
+    const { append, deleteItems, deleteMessage, flush, load, runCycle, step } =
+      createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    await runCycle([
+      createAssistantMessage(
+        { type: "complete", reason: "stop" },
+        [{ id: "reused", parts: ["old"] }],
+        "reused",
+      ),
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledOnce());
+    let resolveDelete!: () => void;
+    deleteItems.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveDelete = resolve;
+        }),
+    );
+    const deletion = deleteMessage("reused");
+    await step({ messages: [] });
+    await act(async () => {
+      resolveDelete();
+      await deletion;
+    });
+    await flush();
+
+    const replacementInner: InnerMessage = { id: "reused", parts: ["new"] };
+    await runCycle([
+      createAssistantMessage(
+        { type: "complete", reason: "stop" },
+        [replacementInner],
+        "reused",
+      ),
+    ]);
+
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    expect(append).toHaveBeenLastCalledWith({
+      parentId: null,
+      message: replacementInner,
+    });
+  });
+
+  it("parents a tool interaction update past a deleted message that is still in the chat", async () => {
+    type Item = { parentId: string | null; message: InnerMessage };
+    const stored = new Map<string, Item>();
+    const toolInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const {
+      append,
+      update,
+      deleteItems,
+      deleteMessage,
+      flush,
+      load,
+      persistToolInteractions,
+      runCycle,
+      step,
+    } = createPersistenceHarness(true, { toolInteractions });
+    append.mockImplementation(async (item) => {
+      stored.set(item.message.id, item);
+    });
+    update.mockImplementation(async (item) => {
+      stored.set(item.message.id, item);
+    });
+    deleteItems.mockImplementation(async (items) => {
+      for (const item of items) stored.delete(item.message.id);
+      const reply = stored.get("reply");
+      if (reply?.parentId === "prompt")
+        stored.set("reply", { ...reply, parentId: null });
+    });
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    const prompt = createUserMessage({ id: "prompt", role: "user", parts: [] });
+    const reply = Object.assign(
+      createAssistantMessage(
+        { type: "complete", reason: "stop" },
+        [{ id: "reply", parts: [{ toolCallId: "call-1" }] }],
+        "reply",
+      ),
+      {
+        content: [
+          {
+            type: "tool-call" as const,
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: undefined,
+            isError: false,
+          },
+        ],
+      },
+    );
+
+    await runCycle([prompt, reply]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    await flush();
+    await act(async () => {
+      await deleteMessage("prompt");
+    });
+    await step({ isRunning: false });
+    await flush();
+    toolInteractions.set("call-1", {
+      entries: [{ type: "human-response", occurredAt: 2, payload: "yes" }],
+    });
+    await act(async () => {
+      await persistToolInteractions("reply");
+    });
+
+    expect(update).toHaveBeenCalledOnce();
+    expect(stored.get("reply")?.parentId).toBeNull();
+  });
+
+  it("stores a new prompt after an earlier reply that failed to store", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+    const userAInner: InnerMessage = { id: "user-a", role: "user", parts: [] };
+    const replyAInner: InnerMessage = { id: "reply-a", parts: ["a"] };
+    const userBInner: InnerMessage = { id: "user-b", role: "user", parts: [] };
+    const replyBInner: InnerMessage = { id: "reply-b", parts: ["b"] };
+    const userA = createUserMessage(userAInner);
+    const replyA = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [replyAInner],
+      "reply-a",
+    );
+    const userB = createUserMessage(userBInner);
+    const { append, flush, load, step } = createPersistenceHarness(false);
+    await waitFor(() => expect(load).toHaveBeenCalledOnce());
+    await flush();
+    append.mockImplementation(async (item) => {
+      if (item.message.id === "reply-a" && append.mock.calls.length === 2)
+        throw new Error("temporary storage failure");
+    });
+
+    await step({
+      isRunning: true,
+      messages: [
+        userA,
+        createAssistantMessage({ type: "running" }, [replyAInner], "reply-a"),
+      ],
+    });
+    await step({ isRunning: false, messages: [userA, replyA] });
+    await flush();
+    await step({
+      isRunning: true,
+      messages: [
+        userA,
+        replyA,
+        userB,
+        createAssistantMessage({ type: "running" }, [replyBInner], "reply-b"),
+      ],
+    });
+    await flush();
+    await step({
+      isRunning: false,
+      messages: [
+        userA,
+        replyA,
+        userB,
+        createAssistantMessage(
+          { type: "complete", reason: "stop" },
+          [replyBInner],
+          "reply-b",
+        ),
+      ],
+    });
+    await flush();
+
+    expect(append.mock.calls.map(([item]) => item)).toEqual([
+      { parentId: null, message: userAInner },
+      { parentId: "user-a", message: replyAInner },
+      { parentId: "user-a", message: replyAInner },
+      { parentId: "reply-a", message: userBInner },
+      { parentId: "user-b", message: replyBInner },
+    ]);
+  });
+
+  it("retries a failed append on the next persistence pass", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+    const { append, runCycle, flush } = createPersistenceHarness(false);
+    const innerMessage = { id: "inner-a", parts: ["final"] };
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [innerMessage],
+    );
+    append.mockRejectedValueOnce(new Error("temporary storage failure"));
+
+    await runCycle([message]);
+    await flush();
+    expect(append).toHaveBeenCalledTimes(1);
+
+    await runCycle([message]);
+    await flush();
+    expect(append).toHaveBeenCalledTimes(2);
+    expect(append).toHaveBeenLastCalledWith({
+      parentId: null,
+      message: innerMessage,
+    });
+
+    await runCycle([message]);
+    await flush();
+    expect(append).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not replay appends that succeeded before a mid-batch failure", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+    const { append, runCycle, flush } = createPersistenceHarness(false);
+    const first = { id: "inner-1", parts: ["first"] };
+    const second = { id: "inner-2", parts: ["second"] };
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [first, second],
+    );
+    append.mockImplementationOnce(async () => {});
+    append.mockRejectedValueOnce(new Error("temporary storage failure"));
+
+    await runCycle([message]);
+    await flush();
+    expect(append).toHaveBeenCalledTimes(2);
+
+    await runCycle([message]);
+    await flush();
+    expect(append).toHaveBeenCalledTimes(3);
+    expect(append.mock.calls.map((c) => c[0].message.id)).toEqual([
+      "inner-1",
+      "inner-2",
+      "inner-2",
+    ]);
+  });
+
+  it("persists assistant messages awaiting tool approval when the adapter supports update", async () => {
+    const { append, runCycle } = createPersistenceHarness(true);
+    const innerMessage = { id: "inner-a", parts: ["pending"] };
+
+    await runCycle([
+      createAssistantMessage(
+        { type: "requires-action", reason: "tool-calls" },
+        [innerMessage],
+      ),
+    ]);
+
+    await waitFor(() =>
+      expect(append).toHaveBeenCalledWith({
+        parentId: null,
+        message: innerMessage,
+      }),
+    );
+    expect(append).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps paused messages unpersisted when the adapter lacks update", async () => {
+    const { append, runCycle, flush } = createPersistenceHarness(false);
+    const finalInnerMessage = { id: "inner-a", parts: ["pending", "final"] };
+
+    await runCycle([
+      createAssistantMessage(
+        { type: "requires-action", reason: "tool-calls" },
+        [{ id: "inner-a", parts: ["pending"] }],
+      ),
+    ]);
+
+    await flush();
+    expect(append).not.toHaveBeenCalled();
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        finalInnerMessage,
+      ]),
+    ]);
+
+    await waitFor(() =>
+      expect(append).toHaveBeenCalledWith({
+        parentId: null,
+        message: finalInnerMessage,
+      }),
+    );
+    expect(append).toHaveBeenCalledTimes(1);
+  });
+
+  it("updates the previously persisted message when its run completes", async () => {
+    const { append, update, runCycle } = createPersistenceHarness(true);
+    const pendingInnerMessage = { id: "inner-a", parts: ["pending"] };
+    const finalInnerMessage = { id: "inner-a", parts: ["pending", "final"] };
+
+    await runCycle([
+      createAssistantMessage(
+        { type: "requires-action", reason: "tool-calls" },
+        [pendingInnerMessage],
+      ),
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        finalInnerMessage,
+      ]),
+    ]);
+
+    await waitFor(() =>
+      expect(update).toHaveBeenCalledWith(
+        { parentId: null, message: finalInnerMessage },
+        "inner-a",
+      ),
+    );
+    expect(append).toHaveBeenCalledTimes(1);
+  });
+
+  it("appends continuation inner messages after approval", async () => {
+    const { append, update, runCycle } = createPersistenceHarness(true);
+    const pendingInnerMessage = { id: "inner-a", parts: ["pending"] };
+    const finalInnerMessage = { id: "inner-a", parts: ["pending", "final"] };
+    const continuationInnerMessage = { id: "inner-b", parts: ["answer"] };
+
+    await runCycle([
+      createAssistantMessage(
+        { type: "requires-action", reason: "tool-calls" },
+        [pendingInnerMessage],
+      ),
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        finalInnerMessage,
+        continuationInnerMessage,
+      ]),
+    ]);
+
+    await waitFor(() =>
+      expect(append).toHaveBeenCalledWith({
+        parentId: "inner-a",
+        message: continuationInnerMessage,
+      }),
+    );
+    expect(append.mock.calls.map(([item]) => item.message.id)).toEqual([
+      "inner-a",
+      "inner-b",
+    ]);
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledWith(
+      { parentId: null, message: finalInnerMessage },
+      "inner-a",
+    );
+  });
+
+  it("defers run telemetry until the paused message completes", async () => {
+    const { reportTelemetry, runCycle, flush } = createPersistenceHarness(true);
+    const pendingInnerMessage = { id: "inner-a", parts: ["pending"] };
+    const finalInnerMessage = { id: "inner-a", parts: ["pending", "final"] };
+    const continuationInnerMessage = { id: "inner-b", parts: ["answer"] };
+
+    await runCycle([
+      createAssistantMessage(
+        { type: "requires-action", reason: "tool-calls" },
+        [pendingInnerMessage],
+      ),
+    ]);
+    await flush();
+    expect(reportTelemetry).not.toHaveBeenCalled();
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        finalInnerMessage,
+        continuationInnerMessage,
+      ]),
+    ]);
+    await flush();
+
+    expect(reportTelemetry).toHaveBeenCalledTimes(1);
+    expect(reportTelemetry).toHaveBeenCalledWith(
+      [
+        { parentId: null, message: finalInnerMessage },
+        { parentId: "inner-a", message: continuationInnerMessage },
+      ],
+      expect.any(Object),
+    );
+    expect(reportTelemetry.mock.calls[0]![1]).toMatchObject({
+      message: expect.objectContaining({
+        id: "assistant-a",
+        status: { type: "complete", reason: "stop" },
+      }),
+    });
+  });
+
+  it("reports a run that failed before any assistant message", async () => {
+    const { append, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(true);
+    const failed = createAssistantMessage(
+      {
+        type: "incomplete",
+        reason: "error",
+        error: { code: "AI_APICallError", message: "upstream failed" },
+      },
+      [],
+    );
+
+    await runCycle([failed]);
+    await flush();
+
+    expect(append).not.toHaveBeenCalled();
+    expect(reportTelemetry).toHaveBeenCalledTimes(1);
+    expect(reportTelemetry).toHaveBeenCalledWith(
+      [],
+      expect.objectContaining({ message: failed }),
+    );
+  });
+
+  it("restores deferred telemetry for reloaded paused messages", async () => {
+    const { append, update, reportTelemetry, load, runCycle, flush } =
+      createPersistenceHarness(true, {
+        loadMessages: {
+          messages: [
+            {
+              parentId: null,
+              message: { id: "inner-a", parts: ["pending"] },
+            },
+          ],
+        },
+        toThreadMessages: (msgs) => [
+          createAssistantMessage(
+            { type: "requires-action", reason: "tool-calls" },
+            msgs,
+          ),
+        ],
+      });
+
+    await waitFor(() => expect(load).toHaveBeenCalled());
+    await flush();
+
+    const finalInnerMessage = { id: "inner-a", parts: ["pending", "final"] };
+    const continuationInnerMessage = { id: "inner-b", parts: ["answer"] };
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        finalInnerMessage,
+        continuationInnerMessage,
+      ]),
+    ]);
+    await flush();
+
+    expect(append).toHaveBeenCalledTimes(1);
+    expect(append).toHaveBeenCalledWith({
+      parentId: "inner-a",
+      message: continuationInnerMessage,
+    });
+    expect(update).toHaveBeenCalledWith(
+      { parentId: null, message: finalInnerMessage },
+      "inner-a",
+    );
+    expect(reportTelemetry).toHaveBeenCalledTimes(1);
+    expect(reportTelemetry).toHaveBeenCalledWith(
+      [
+        { parentId: null, message: finalInnerMessage },
+        { parentId: "inner-a", message: continuationInnerMessage },
+      ],
+      expect.any(Object),
+    );
+  });
+
+  it("serializes overlapping persistence passes", async () => {
+    const { append, runCycle, flush } = createPersistenceHarness(true);
+    let releaseFirstAppend!: () => void;
+    const firstAppend = new Promise<void>((resolve) => {
+      releaseFirstAppend = resolve;
+    });
+    append.mockImplementationOnce(() => firstAppend);
+
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["answer"] }],
+    );
+
+    await runCycle([message]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    await runCycle([message]);
+    await flush();
+    const callsWhileFirstAppendWasPending = append.mock.calls.length;
+
+    releaseFirstAppend();
+    await flush();
+    await flush();
+
+    expect(callsWhileFirstAppendWasPending).toBe(1);
+    expect(append).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves telemetry timing for runs queued behind a pending append", async () => {
+    const { append, reportTelemetry, step, flush } =
+      createPersistenceHarness(false);
+    let releaseFirstAppend!: () => void;
+    const firstAppend = new Promise<void>((resolve) => {
+      releaseFirstAppend = resolve;
+    });
+    append.mockImplementationOnce(() => firstAppend);
+
+    let now = 0;
+    const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => now);
+    const firstMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+    const secondMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-b", parts: ["second"] }],
+      "assistant-b",
+    );
+    const thirdMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-c", parts: ["third"] }],
+      "assistant-c",
+    );
+
+    try {
+      await step({ isRunning: true, messages: [firstMessage] });
+      now = 10;
+      await step({ isRunning: false });
+      await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+      now = 100;
+      await step({
+        isRunning: true,
+        messages: [firstMessage, secondMessage],
+      });
+      now = 110;
+      await step({ isRunning: false });
+      await flush();
+
+      now = 200;
+      await step({
+        isRunning: true,
+        messages: [firstMessage, secondMessage, thirdMessage],
+      });
+      now = 230;
+      await step({ isRunning: false });
+      await flush();
+
+      releaseFirstAppend();
+      await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(3));
+
+      const durations = Object.fromEntries(
+        reportTelemetry.mock.calls.map(([items, options]) => [
+          items[0]?.message.id,
+          options.durationMs,
+        ]),
+      );
+      expect(durations).toEqual({
+        "inner-a": 10,
+        "inner-b": 10,
+        "inner-c": 30,
+      });
+    } finally {
+      releaseFirstAppend();
+      nowSpy.mockRestore();
+    }
+  });
+
+  it("finishes queued persistence passes after unmount", async () => {
+    const { append, runCycle, flush, unmount } =
+      createPersistenceHarness(false);
+    let releaseFirstAppend!: () => void;
+    const firstAppend = new Promise<void>((resolve) => {
+      releaseFirstAppend = resolve;
+    });
+    append.mockImplementationOnce(() => firstAppend);
+
+    const firstMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+    const secondMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-b", parts: ["second"] }],
+      "assistant-b",
+    );
+
+    await runCycle([firstMessage]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    await runCycle([firstMessage, secondMessage]);
+    await flush();
+    unmount();
+
+    releaseFirstAppend();
+    await flush();
+    await flush();
+
+    expect(append.mock.calls.map(([item]) => item.message.id)).toEqual([
+      "inner-a",
+      "inner-b",
+    ]);
+  });
+
+  it("serializes deletion after pending persistence passes", async () => {
+    const { append, deleteItems, deleteMessage, runCycle, flush } =
+      createPersistenceHarness(false);
+    const events: string[] = [];
+    let releaseFirstAppend!: () => void;
+    const firstAppend = new Promise<void>((resolve) => {
+      releaseFirstAppend = resolve;
+    });
+    append.mockImplementation(async (item) => {
+      events.push(`append:${item.message.id}`);
+    });
+    append.mockImplementationOnce(async (item) => {
+      events.push(`append:${item.message.id}:start`);
+      await firstAppend;
+      events.push(`append:${item.message.id}:end`);
+    });
+    deleteItems.mockImplementation(async (items) => {
+      events.push(`delete:${items[0]?.message.id}`);
+    });
+
+    const firstMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+    const secondMessage = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-b", parts: ["second"] }],
+      "assistant-b",
+    );
+
+    try {
+      await runCycle([firstMessage]);
+      await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+      await runCycle([firstMessage, secondMessage]);
+      await flush();
+      const deletion = deleteMessage("assistant-a");
+      await flush();
+      expect(deleteItems).not.toHaveBeenCalled();
+
+      releaseFirstAppend();
+      await deletion;
+
+      expect(events).toEqual([
+        "append:inner-a:start",
+        "append:inner-a:end",
+        "append:inner-b",
+        "delete:inner-a",
+      ]);
+    } finally {
+      releaseFirstAppend();
+    }
+  });
+
+  it("uses the requested deletion snapshot after runtime state changes", async () => {
+    const { append, deleteItems, deleteMessage, runCycle, flush, step } =
+      createPersistenceHarness(false);
+    let releaseAppend!: () => void;
+    const pendingAppend = new Promise<void>((resolve) => {
+      releaseAppend = resolve;
+    });
+    append.mockImplementationOnce(() => pendingAppend);
+
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+
+    try {
+      await runCycle([message]);
+      await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+      const deletion = deleteMessage("assistant-a");
+      await step({ messages: [] });
+      await flush();
+      expect(deleteItems).not.toHaveBeenCalled();
+
+      releaseAppend();
+      await deletion;
+
+      expect(deleteItems).toHaveBeenCalledWith([
+        {
+          parentId: null,
+          message: { id: "inner-a", parts: ["first"] },
+        },
+      ]);
+    } finally {
+      releaseAppend();
+    }
+  });
+
+  it("preserves the history adapter receiver during deletion", async () => {
+    const { deleteItems, formattedAdapter, deleteMessage, step } =
+      createPersistenceHarness(false);
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+
+    await step({ messages: [message] });
+    await deleteMessage("assistant-a");
+
+    expect(deleteItems).toHaveBeenCalledOnce();
+    expect(deleteItems.mock.contexts[0]).toBe(formattedAdapter);
+  });
+
+  it("reports a failed append as a persistence error once", async () => {
+    const { append, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(false);
+    const failure = new Error("temporary storage failure");
+    append.mockRejectedValueOnce(failure);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    onTestFinished(() => errorSpy.mockRestore());
+    const message = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["answer"] }],
+    );
+
+    await runCycle([message]);
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(1));
+    expect(reportTelemetry).toHaveBeenCalledWith(
+      [{ parentId: null, message: { id: "inner-a", parts: ["answer"] } }],
+      expect.objectContaining({ message, persistenceError: failure }),
+    );
+
+    await runCycle([message]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+    await flush();
+    expect(reportTelemetry).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports messages after a failed append without storing them", async () => {
+    const { append, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(false);
+    const failure = new Error("temporary storage failure");
+    append.mockRejectedValueOnce(failure);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    onTestFinished(() => errorSpy.mockRestore());
+    const first = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["first"] }],
+      "assistant-a",
+    );
+    const second = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-b", parts: ["second"] }],
+      "assistant-b",
+    );
+
+    await runCycle([first, second]);
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(2));
+    await flush();
+
+    expect(append).toHaveBeenCalledTimes(1);
+    expect(reportTelemetry.mock.calls.map(([, options]) => options)).toEqual([
+      expect.objectContaining({ message: first, persistenceError: failure }),
+      expect.objectContaining({ message: second, persistenceError: failure }),
+    ]);
+  });
+
+  it("reports a failed update of a settled message as a persistence error", async () => {
+    const { update, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(true);
+    const failure = new Error("temporary storage failure");
+    update.mockRejectedValueOnce(failure);
+    const pending = createAssistantMessage(
+      { type: "requires-action", reason: "tool-calls" },
+      [{ id: "inner-a", parts: ["pending"] }],
+    );
+    const settled = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["pending", "final"] }],
+    );
+
+    await runCycle([pending]);
+    await flush();
+    await runCycle([settled]);
+    await waitFor(() => expect(reportTelemetry).toHaveBeenCalledTimes(1));
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(reportTelemetry).toHaveBeenCalledWith(
+      expect.any(Array),
+      expect.objectContaining({ message: settled, persistenceError: failure }),
+    );
+  });
+
+  it("does not reappend a stored inner message whose outer message was filtered", async () => {
+    const innerMessage = { id: "inner-a", parts: ["stored"] };
+    const { append, load, runCycle, flush } = createPersistenceHarness(false, {
+      loadMessages: {
+        messages: [{ parentId: null, message: innerMessage }],
+      },
+      toThreadMessages: () => [],
+    });
+
+    await waitFor(() => expect(load).toHaveBeenCalled());
+    await flush();
+
+    await runCycle([
+      createAssistantMessage({ type: "complete", reason: "stop" }, [
+        innerMessage,
+      ]),
+    ]);
+    await flush();
+
+    expect(append).not.toHaveBeenCalled();
+  });
+
+  it("skips unchanged persisted messages on later runs", async () => {
+    const { append, update, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(true);
+    const completeStatus: ThreadAssistantMessage["status"] = {
+      type: "complete",
+      reason: "stop",
+    };
+    const old = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-old", parts: ["old"] }],
+      "old",
+    );
+    const active = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-active", parts: ["initial"] }],
+      "active",
+    );
+    const tail = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-tail", parts: ["tail"] }],
+      "tail",
+    );
+
+    await runCycle([old, active, tail]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(3));
+
+    append.mockClear();
+    update.mockClear();
+    reportTelemetry.mockClear();
+
+    const changedActive = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-active", parts: ["completed"] }],
+      "active",
+    );
+    await runCycle([old, changedActive, tail]);
+    await flush();
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledWith(
+      {
+        parentId: "inner-old",
+        message: { id: "inner-active", parts: ["completed"] },
+      },
+      "inner-active",
+    );
+    expect(append).not.toHaveBeenCalled();
+    expect(reportTelemetry).not.toHaveBeenCalled();
+  });
+
+  it("skips updates for a persisted message restored by a branch switch", async () => {
+    const { append, update, runCycle, flush } = createPersistenceHarness(true);
+    const completeStatus: ThreadAssistantMessage["status"] = {
+      type: "complete",
+      reason: "stop",
+    };
+    const createUserMessage = (
+      id: string,
+      inner: InnerMessage,
+    ): ThreadMessage => {
+      const message: ThreadMessage = {
+        id,
+        role: "user",
+        content: [{ type: "text", text: "hi" }],
+        attachments: [],
+        createdAt: new Date(),
+        metadata: { custom: {} },
+      };
+      bindExternalStoreMessage(message, [inner]);
+      return message;
+    };
+    const branchA = () => [
+      createUserMessage("user-a", { id: "inner-user-a", parts: ["question"] }),
+      createAssistantMessage(
+        completeStatus,
+        [{ id: "inner-assistant-a", parts: ["answer"] }],
+        "assistant-a",
+      ),
+    ];
+
+    await runCycle(branchA());
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+
+    await runCycle([
+      createUserMessage("user-b", { id: "inner-user-b", parts: ["edited"] }),
+      createAssistantMessage(
+        completeStatus,
+        [{ id: "inner-assistant-b", parts: ["answer"] }],
+        "assistant-b",
+      ),
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(4));
+
+    append.mockClear();
+    update.mockClear();
+
+    await runCycle([
+      ...branchA(),
+      createUserMessage("user-c", { id: "inner-user-c", parts: ["follow-up"] }),
+      createAssistantMessage(
+        completeStatus,
+        [{ id: "inner-assistant-c", parts: ["answer"] }],
+        "assistant-c",
+      ),
+    ]);
+    await flush();
+
+    expect(update).not.toHaveBeenCalled();
+    expect(append.mock.calls.map(([item]) => item.message.id)).toEqual([
+      "inner-user-c",
+      "inner-assistant-c",
+    ]);
+  });
+
+  it("absorbs agentic flickers without losing change detection", async () => {
+    const { append, update, reportTelemetry, runCycle, flush, step } =
+      createPersistenceHarness(true);
+    const completeStatus: ThreadAssistantMessage["status"] = {
+      type: "complete",
+      reason: "stop",
+    };
+    const old = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-old", parts: ["old"] }],
+      "old",
+    );
+    const active = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-active", parts: ["initial"] }],
+      "active",
+    );
+    const tail = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-tail", parts: ["tail"] }],
+      "tail",
+    );
+
+    await runCycle([old, active, tail]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(3));
+
+    append.mockClear();
+    update.mockClear();
+    reportTelemetry.mockClear();
+
+    const changedActive = createAssistantMessage(
+      completeStatus,
+      [{ id: "inner-active", parts: ["completed"] }],
+      "active",
+    );
+    await step({ isRunning: true });
+    await step({ messages: [old, changedActive, tail] });
+    await step({ isRunning: false });
+    await step({ isRunning: true });
+    await step({ isRunning: false });
+    await flush();
+
+    await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+    expect(update).toHaveBeenCalledWith(
+      {
+        parentId: "inner-old",
+        message: { id: "inner-active", parts: ["completed"] },
+      },
+      "inner-active",
+    );
+    expect(append).not.toHaveBeenCalled();
+    expect(reportTelemetry).not.toHaveBeenCalled();
+  });
+
+  it("persists idle-time changes on the next run stop", async () => {
+    const { append, update, reportTelemetry, runCycle, flush, step } =
+      createPersistenceHarness(true);
+    const initialActive = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["initial"] }],
+      "active",
+    );
+
+    await runCycle([initialActive]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    append.mockClear();
+    update.mockClear();
+    reportTelemetry.mockClear();
+
+    const changedActive = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["initial", "tool-result"] }],
+      "active",
+    );
+    await step({ messages: [changedActive] });
+
+    await runCycle([changedActive]);
+    await flush();
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledWith(
+      {
+        parentId: null,
+        message: { id: "inner-a", parts: ["initial", "tool-result"] },
+      },
+      "inner-a",
+    );
+    expect(append).not.toHaveBeenCalled();
+  });
+
+  it("retries a failed update on the next run", async () => {
+    const { append, update, reportTelemetry, runCycle, flush } =
+      createPersistenceHarness(true);
+    const initialActive = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["initial"] }],
+      "active",
+    );
+
+    await runCycle([initialActive]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(1));
+
+    append.mockClear();
+    update.mockClear();
+    reportTelemetry.mockClear();
+    update.mockRejectedValueOnce(new Error("boom"));
+
+    const changedActive = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["changed"] }],
+      "active",
+    );
+    const changedMessages = [changedActive];
+
+    await runCycle(changedMessages);
+    await flush();
+    await runCycle(changedMessages);
+    await flush();
+
+    expect(update).toHaveBeenCalledTimes(2);
+    expect(update).toHaveBeenNthCalledWith(
+      1,
+      {
+        parentId: null,
+        message: { id: "inner-a", parts: ["changed"] },
+      },
+      "inner-a",
+    );
+    expect(update).toHaveBeenNthCalledWith(
+      2,
+      {
+        parentId: null,
+        message: { id: "inner-a", parts: ["changed"] },
+      },
+      "inner-a",
+    );
+    expect(append).not.toHaveBeenCalled();
+  });
+
+  it("detects changes on non-assistant messages", async () => {
+    const { append, update, runCycle, flush } = createPersistenceHarness(true);
+    const makeUserMessage = (inner: InnerMessage): ThreadMessage => {
+      const message: ThreadMessage = {
+        id: "user-1",
+        role: "user",
+        content: [{ type: "text", text: "hi" }],
+        attachments: [],
+        createdAt: new Date(),
+        metadata: { custom: {} },
+      };
+      bindExternalStoreMessage(message, [inner]);
+      return message;
+    };
+    const assistant = createAssistantMessage(
+      { type: "complete", reason: "stop" },
+      [{ id: "inner-a", parts: ["answer"] }],
+    );
+
+    await runCycle([
+      makeUserMessage({ id: "inner-user", parts: ["hi"] }),
+      assistant,
+    ]);
+    await waitFor(() => expect(append).toHaveBeenCalledTimes(2));
+
+    append.mockClear();
+    update.mockClear();
+
+    await runCycle([
+      makeUserMessage({ id: "inner-user", parts: ["hi", "attachment"] }),
+      assistant,
+    ]);
+    await flush();
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledWith(
+      {
+        parentId: null,
+        message: { id: "inner-user", parts: ["hi", "attachment"] },
+      },
+      "inner-user",
+    );
+    expect(append).not.toHaveBeenCalled();
+  });
+});