@sixb/core 0.1.20 → 0.1.22

package/src/testing/agent-storage-contract.ts

@@ -1,17 +1,25 @@
 import { describe, expect, test } from "bun:test"
+import { createHash } from "node:crypto"
 import { AGENT_MESSAGE_CONTENT_VERSION } from "../agents/message"
+import { projectAgentThreadModelContext } from "../agents/thread-context-projection"
 import type { Principal } from "../auth"
+import type { FileRef } from "../blob-storage/types"
 import type { SixbFailure } from "../errors/types"
 import {
+  type AddAgentThreadParticipantsInput,
   type AgentRunExecution,
   type AgentRunFailureCode,
   type AgentStorage,
   AgentStorageError,
   type AgentStorageErrorCode,
+  type AgentThreadParticipantRecord,
+  type ConversationAgentRunSpec,
   type CreateAgentContextCheckpointInput,
   type CreateAgentRunInput,
   type CreateAgentThreadInput,
   type CreateSubagentRunInput,
+  type ForkAgentThreadInput,
+  type ListAgentThreadChildrenInput,
   type StartAgentRunInput,
 } from "../storage/agents"
 import type { AuthStorage } from "../storage/auth"
@@ -37,6 +45,7 @@ export interface AgentStorageContractSuiteOptions<
 const projectId = "project-a"
 const otherProjectId = "project-b"
 const owner: Principal = { type: "user", id: "usr_1" }
+const otherUser: Principal = { type: "user", id: "usr_2" }
 const serviceAccount: Extract<Principal, { readonly type: "serviceAccount" }> = {
   type: "serviceAccount",
   id: "svc_agent_sales",
@@ -72,6 +81,30 @@ function threadInput(overrides: Partial<CreateAgentThreadInput> = {}): CreateAge
   }
 }
 
+function participantsInput(
+  userIds: readonly string[],
+  addedAt = at("2026-06-23T11:00:00.000Z")
+): AddAgentThreadParticipantsInput {
+  return {
+    projectId,
+    threadId: "thr_1",
+    principals: userIds.map((id) => ({ type: "user", id })),
+    addedBy: owner,
+    maxParticipants: 10,
+    addedAt,
+  }
+}
+
+function participant(userId: string, addedAt: Date): AgentThreadParticipantRecord {
+  return {
+    projectId,
+    threadId: "thr_1",
+    principal: { type: "user", id: userId },
+    addedAt,
+    addedBy: owner,
+  }
+}
+
 function execution(
   token: string,
   queueLeaseExpiresAt = at("2026-06-23T10:05:00.000Z")
@@ -103,6 +136,18 @@ function runInput(overrides: Partial<TestRunInput> = {}): TestRunInput {
   }
 }
 
+/** A content-addressed reference, as blob storage returns it. */
+function testFileRef(fileName: string): FileRef {
+  const hex = createHash("sha256").update(fileName).digest("hex")
+  return {
+    blobId: `blob_${hex}`,
+    digest: `sha256:${hex}`,
+    sizeBytes: 12,
+    fileName,
+    mediaType: "text/csv",
+  }
+}
+
 function subagentInput(
   parentExecutionToken: string,
   overrides: Partial<CreateSubagentRunInput> = {}
@@ -121,7 +166,10 @@ function subagentInput(
       task: "Research the open orders.",
       toolNames: ["search_orders"],
       maxSteps: 25,
+      files: [{ path: "reports/orders.csv", fileRef: testFileRef("orders.csv") }],
     },
+    thread: { id: `thread_${id}`, create: true },
+    trigger: { id: `task_${id}`, parts: [{ type: "text", text: "Research the open orders." }] },
     maxActiveChildren: 4,
     createdAt: at("2026-06-23T10:01:00.000Z"),
     ...overrides,
@@ -267,6 +315,143 @@ async function prepareCheckpointCandidate(
   )
 }
 
+const forkedFile = {
+  blobId: "blob_report",
+  digest: `sha256:${"a".repeat(64)}`,
+  sizeBytes: 12,
+  fileName: "report.csv",
+  mediaType: "text/csv",
+} as const
+
+function forkInput(overrides: Partial<ForkAgentThreadInput> = {}): ForkAgentThreadInput {
+  return {
+    projectId,
+    sourceThreadId: "thr_1",
+    id: "thr_fork",
+    ownerPrincipal: otherUser,
+    title: "Slipped deals",
+    createdAt: at("2026-06-23T11:00:00.000Z"),
+    ...overrides,
+  }
+}
+
+/**
+ * Two finished turns, then a third still running, each compacted by the run that follows:
+ * `checkpoint_1` (written by finished `run_2`) and `checkpoint_2` (written by running `run_3`,
+ * anchored on its trigger `m5`).
+ */
+async function prepareForkSource(
+  storage: AgentStorage,
+  fixture: AgentStorageContractStorage,
+  /** The summary of the checkpoint the third turn writes. */
+  summary = "Three deals slipped; Acme waits on legal review."
+): Promise<void> {
+  await storage.threads.create(threadInput({ title: "Slipped deals" }))
+  await storage.messages.append({
+    id: "m1",
+    projectId,
+    threadId: "thr_1",
+    runId: null,
+    role: "user",
+    authorPrincipal: owner,
+    parts: [
+      { type: "text", text: "Which deals slipped?" },
+      { type: "file", fileRef: forkedFile },
+    ],
+    metadata: { source: "chat" },
+    createdAt: at("2026-06-23T10:00:01.000Z"),
+  })
+  await createAndStartRun(storage, fixture, runInput({ id: "run_1", triggerMessageId: "m1" }))
+  await storage.messages.append({
+    id: "m2",
+    projectId,
+    threadId: "thr_1",
+    runId: "run_1",
+    role: "assistant",
+    authorPrincipal: owner,
+    parts: [
+      { type: "step-start" },
+      {
+        type: "tool-call",
+        toolCallId: "call_1",
+        toolName: "bash",
+        input: { cmd: "report" },
+        state: "output-available",
+        output: { file: forkedFile },
+      },
+      { type: "text", text: "Three deals slipped." },
+    ],
+    createdAt: at("2026-06-23T10:00:02.000Z"),
+    completedAt: at("2026-06-23T10:00:03.000Z"),
+  })
+  await storage.runs.finish({
+    id: "run_1",
+    projectId,
+    executionToken: "exec_1",
+    status: "succeeded",
+  })
+
+  await storage.messages.append({
+    id: "m3",
+    projectId,
+    threadId: "thr_1",
+    runId: null,
+    role: "user",
+    authorPrincipal: owner,
+    parts: [{ type: "text", text: "Why did Acme slip?" }],
+    createdAt: at("2026-06-23T10:00:04.000Z"),
+  })
+  await createAndStartRun(
+    storage,
+    fixture,
+    runInput({ id: "run_2", triggerMessageId: "m3", execution: execution("exec_2") })
+  )
+  await storage.checkpoints.create(checkpointInput())
+  await storage.messages.append({
+    id: "m4",
+    projectId,
+    threadId: "thr_1",
+    runId: "run_2",
+    role: "assistant",
+    parts: [{ type: "text", text: "Legal review." }],
+    createdAt: at("2026-06-23T10:00:05.000Z"),
+  })
+  await storage.runs.finish({
+    id: "run_2",
+    projectId,
+    executionToken: "exec_2",
+    status: "succeeded",
+  })
+
+  await storage.messages.append({
+    id: "m5",
+    projectId,
+    threadId: "thr_1",
+    runId: null,
+    role: "user",
+    parts: [{ type: "text", text: "Draft the emails." }],
+    createdAt: at("2026-06-23T10:00:06.000Z"),
+  })
+  await createAndStartRun(
+    storage,
+    fixture,
+    runInput({ id: "run_3", triggerMessageId: "m5", execution: execution("exec_3") })
+  )
+  await storage.checkpoints.create(
+    checkpointInput({
+      id: "checkpoint_2",
+      createdByRunId: "run_3",
+      expectedPreviousCheckpointId: "checkpoint_1",
+      expectedHeadSeq: 5,
+      executionToken: "exec_3",
+      summary,
+      summarizedThroughSeq: 4,
+      observedHeadSeq: 5,
+      createdAt: at("2026-06-23T10:05:00.000Z"),
+    })
+  )
+}
+
 /**
  * Runs the shared `AgentStorage` contract against any storage implementation.
  *
@@ -565,6 +750,20 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
       })
     })
 
+    test("reads several threads at once, in the order asked", async () => {
+      await withStorage(async (storage) => {
+        const first = await storage.threads.create(threadInput())
+        const second = await storage.threads.create(threadInput({ id: "thr_2" }))
+        await storage.threads.create(threadInput({ id: "thr_3", projectId: otherProjectId }))
+
+        await expect(
+          storage.threads.getByIds({ projectId, ids: ["thr_2", "missing", "thr_1", "thr_2"] })
+        ).resolves.toEqual([second, first])
+        await expect(storage.threads.getByIds({ projectId, ids: ["thr_3"] })).resolves.toEqual([])
+        await expect(storage.threads.getByIds({ projectId, ids: [] })).resolves.toEqual([])
+      })
+    })
+
     test("lists threads with filters, ordering, and pagination", async () => {
       await withStorage(async (storage) => {
         await storage.threads.create(
@@ -609,6 +808,200 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
       })
     })
 
+    // ── participants ───────────────────────────────────────────────────────────────────────────
+
+    test("adds participants once and keeps when and by whom they were first added", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const first = await storage.threads.addParticipants(
+          participantsInput(["usr_cleo", "usr_bob"], at("2026-06-23T11:00:00.000Z"))
+        )
+        expect(first).toEqual([
+          participant("usr_bob", at("2026-06-23T11:00:00.000Z")),
+          participant("usr_cleo", at("2026-06-23T11:00:00.000Z")),
+        ])
+
+        const again = await storage.threads.addParticipants({
+          ...participantsInput(["usr_cleo", "usr_dan"], at("2026-06-23T12:00:00.000Z")),
+          addedBy: { type: "system", id: "system" },
+        })
+        expect(again).toEqual([
+          participant("usr_bob", at("2026-06-23T11:00:00.000Z")),
+          participant("usr_cleo", at("2026-06-23T11:00:00.000Z")),
+          {
+            ...participant("usr_dan", at("2026-06-23T12:00:00.000Z")),
+            addedBy: { type: "system", id: "system" },
+          },
+        ])
+
+        expect(
+          await storage.threads.listParticipants({ projectId, threadIds: ["thr_1", "thr_1"] })
+        ).toEqual(again)
+      })
+    })
+
+    // Regression proof: compare ids with localeCompare in compareAgentThreadParticipants; it puts
+    // "usr_a" before "usr_B", where PostgreSQL's "C" collation and SQLite put "usr_B" first.
+    test("orders participants added at once by their ids' bytes, alike everywhere", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await storage.threads.create(threadInput({ id: "thr_2" }))
+        for (const threadId of ["thr_2", "thr_1"]) {
+          await storage.threads.addParticipants({
+            ...participantsInput(["usr_a", "usr_B", "usr_é"]),
+            threadId,
+          })
+        }
+
+        const listed = await storage.threads.listParticipants({
+          projectId,
+          threadIds: ["thr_2", "thr_1"],
+        })
+        expect(listed.map((record) => `${record.principal.id}@${record.threadId}`)).toEqual([
+          "usr_B@thr_1",
+          "usr_B@thr_2",
+          "usr_a@thr_1",
+          "usr_a@thr_2",
+          "usr_é@thr_1",
+          "usr_é@thr_2",
+        ])
+      })
+    })
+
+    test("lets one of several adds racing for the last place win", async () => {
+      // Concurrent calls rarely interleave here; the PostgreSQL suite holds a transaction open to
+      // prove its row lock. This checks the outcome every provider must give.
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await storage.threads.addParticipants(participantsInput(["usr_bob"]))
+
+        const racers = ["usr_cleo", "usr_dan", "usr_eve", "usr_fay", "usr_gus"]
+        const race = await Promise.allSettled(
+          racers.map((id) =>
+            storage.threads.addParticipants({ ...participantsInput([id]), maxParticipants: 2 })
+          )
+        )
+        expect(race.filter((result) => result.status === "fulfilled")).toHaveLength(1)
+        for (const result of race) {
+          if (result.status === "rejected") {
+            expect(result.reason).toMatchObject({ code: "participant_limit" })
+          }
+        }
+
+        expect(
+          await storage.threads.listParticipants({ projectId, threadIds: ["thr_1"] })
+        ).toHaveLength(2)
+      })
+    })
+
+    test("refuses participants past the limit, and missing threads", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await storage.threads.addParticipants(participantsInput(["usr_bob"]))
+
+        // Regression proof: drop the limit check in participantsToAdd; the third user is added.
+        await expectAgentError(
+          storage.threads.addParticipants({
+            ...participantsInput(["usr_cleo", "usr_dan"]),
+            maxParticipants: 2,
+          }),
+          "participant_limit"
+        )
+        await expectAgentError(
+          storage.threads.addParticipants({ ...participantsInput(["usr_bob"]), threadId: "nope" }),
+          "thread_not_found"
+        )
+
+        // A refused add adds no one, and someone already there does not count twice.
+        const kept = await storage.threads.addParticipants({
+          ...participantsInput(["usr_bob", "usr_cleo"]),
+          maxParticipants: 2,
+        })
+        expect(kept.map((record) => record.principal.id)).toEqual(["usr_bob", "usr_cleo"])
+      })
+    })
+
+    test("removes a participant and lists the threads shared with a user", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(
+          threadInput({ id: "thr_a", createdAt: at("2026-06-23T10:00:00.000Z") })
+        )
+        await storage.threads.create(
+          threadInput({ id: "thr_b", createdAt: at("2026-06-23T10:01:00.000Z") })
+        )
+        await storage.threads.create(
+          threadInput({ id: "thr_c", createdAt: at("2026-06-23T10:02:00.000Z") })
+        )
+        await storage.threads.create(threadInput({ id: "thr_a", projectId: otherProjectId }))
+        for (const threadId of ["thr_a", "thr_c"]) {
+          await storage.threads.addParticipants({ ...participantsInput(["usr_bob"]), threadId })
+        }
+        await storage.threads.addParticipants({
+          ...participantsInput(["usr_bob"]),
+          projectId: otherProjectId,
+          threadId: "thr_a",
+        })
+
+        const bob = { type: "user", id: "usr_bob" } as const
+        const shared = await storage.threads.list({
+          projectId,
+          participantPrincipal: bob,
+          order: "asc",
+        })
+        expect(shared.threads.map((thread) => thread.id)).toEqual(["thr_a", "thr_c"])
+        expect(shared.total).toBe(2)
+
+        const page = await storage.threads.list({
+          projectId,
+          participantPrincipal: bob,
+          order: "desc",
+          limit: 1,
+        })
+        expect(page.threads.map((thread) => thread.id)).toEqual(["thr_c"])
+        expect(page.hasMore).toBe(true)
+
+        expect(
+          await storage.threads.removeParticipant({ projectId, threadId: "thr_a", principal: bob })
+        ).toBe(true)
+        expect(
+          await storage.threads.removeParticipant({ projectId, threadId: "thr_a", principal: bob })
+        ).toBe(false)
+        expect(
+          await storage.threads.removeParticipant({ projectId, threadId: "nope", principal: bob })
+        ).toBe(false)
+
+        const after = await storage.threads.list({ projectId, participantPrincipal: bob })
+        expect(after.threads.map((thread) => thread.id)).toEqual(["thr_c"])
+        expect(
+          await storage.threads.listParticipants({ projectId, threadIds: ["thr_a", "thr_b"] })
+        ).toEqual([])
+        expect(
+          await storage.threads.listParticipants({
+            projectId: otherProjectId,
+            threadIds: ["thr_a"],
+          })
+        ).toHaveLength(1)
+      })
+    })
+
+    test("rolls participants back with their transaction", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput())
+
+        await expect(
+          fixture.transaction(async (tx) => {
+            await tx.agents?.threads.addParticipants(participantsInput(["usr_bob"]))
+            throw new Error("rollback")
+          })
+        ).rejects.toThrow("rollback")
+
+        expect(await storage.threads.listParticipants({ projectId, threadIds: ["thr_1"] })).toEqual(
+          []
+        )
+      })
+    })
+
     // ── durable queued runs ────────────────────────────────────────────────────────────────────
 
     test("creates a queued run before execution and claims the thread", async () => {
@@ -648,6 +1041,37 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
       })
     })
 
+    test("keeps a turn's tier and the probabilities Sixb picked it from", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput())
+        const spec = {
+          model: { provider: "test", modelId: "large" },
+          tier: "heavy" as const,
+          tierProbabilities: { light: 0.05, standard: 0.25, heavy: 0.7 },
+          reasoning: "high" as const,
+        }
+
+        await createRun(storage, fixture, runInput({ id: "run_1", spec }))
+        expect((await storage.runs.getById({ projectId, id: "run_1" }))?.spec).toEqual(spec)
+
+        // Proven by removal: drop the tier checks from assertConversationAgentRunSpec.
+        for (const invalid of [
+          { ...spec, tier: "medium" },
+          { ...spec, tierProbabilities: { light: 0.3, standard: 0.7 } },
+          { ...spec, tierProbabilities: { ...spec.tierProbabilities, heavy: 1.5 } },
+        ]) {
+          await expectAgentError(
+            createRun(
+              storage,
+              fixture,
+              runInput({ id: "run_2", spec: invalid as ConversationAgentRunSpec })
+            ),
+            "invalid_input"
+          )
+        }
+      })
+    })
+
     test("rejects a run whose durable execution does not match its Agent authority", async () => {
       await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
@@ -723,7 +1147,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
 
     // ── durable child runs ─────────────────────────────────────────────────────────────────────
 
-    test("creates and exactly replays a child run without claiming a thread", async () => {
+    test("creates a child's thread, its task and its run at once, and replays them exactly", async () => {
       await withStorage(async (storage, fixture) => {
         await createRunningParent(storage, fixture)
         const input = subagentInput("parent_token")
@@ -732,14 +1156,51 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
         expect(child).toMatchObject({
           kind: "subagent",
           id: "child_1",
+          threadId: "thread_child_1",
+          triggerMessageId: "task_child_1",
           parentRunId: "parent_1",
           spawnKey: "research-orders",
           status: "queued",
           attempt: 0,
           spec: input.spec,
         })
-        expect(child).not.toHaveProperty("threadId")
-        await expect(storage.runs.createSubagent(input)).resolves.toEqual(child)
+        await expect(storage.threads.getById({ projectId, id: "thread_child_1" })).resolves.toEqual(
+          {
+            id: "thread_child_1",
+            projectId,
+            kind: "subagent",
+            parent: { threadId: "parent_thread", spawnedBy: "parent_1", key: "research-orders" },
+            ownerPrincipal: owner,
+            status: "active",
+            activeRunId: "child_1",
+            lastMessageAt: at("2026-06-23T10:01:00.000Z"),
+            messageCount: 1,
+            createdAt: at("2026-06-23T10:01:00.000Z"),
+            updatedAt: at("2026-06-23T10:01:00.000Z"),
+          }
+        )
+        const task = {
+          id: "task_child_1",
+          projectId,
+          threadId: "thread_child_1",
+          runId: "child_1",
+          role: "user",
+          seq: 1,
+          parts: [{ type: "text", text: "Research the open orders." }],
+          contentVersion: AGENT_MESSAGE_CONTENT_VERSION,
+          createdAt: at("2026-06-23T10:01:00.000Z"),
+        }
+        await expect(
+          storage.messages.list({ projectId, threadId: "thread_child_1" })
+        ).resolves.toMatchObject({ messages: [task], total: 1 })
+
+        // A replay writes nothing more, whatever trigger it brings.
+        await expect(
+          storage.runs.createSubagent({ ...input, trigger: { ...input.trigger, id: "other" } })
+        ).resolves.toEqual(child)
+        await expect(
+          storage.messages.list({ projectId, threadId: "thread_child_1" })
+        ).resolves.toMatchObject({ total: 1 })
         await expectAgentError(
           storage.runs.createSubagent({
             ...input,
@@ -754,12 +1215,332 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
           parentRunId: "parent_1",
         })
         expect(listed.runs.map((run) => run.id)).toEqual(["child_1"])
+        await expect(
+          storage.runs.list({ projectId, threadId: "thread_child_1" })
+        ).resolves.toMatchObject({ runs: [{ id: "child_1" }], total: 1 })
         await expect(
           storage.runs.list({ projectId, kinds: ["conversation"] })
         ).resolves.toMatchObject({ runs: [{ id: "parent_1" }], total: 1 })
         await expect(
-          storage.threads.getById({ projectId, id: "parent_thread" })
-        ).resolves.toMatchObject({ activeRunId: "parent_1" })
+          storage.threads.getById({ projectId, id: "parent_thread" })
+        ).resolves.toMatchObject({ activeRunId: "parent_1", messageCount: 0 })
+      })
+    })
+
+    test("rolls a child's thread back with its run", async () => {
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        const input = subagentInput("parent_token")
+        await createTestAgentExecution(fixture, {
+          projectId,
+          runId: input.id,
+          executionId: input.executionId,
+          sourceExecutionId: "test_agent_execution:parent_1",
+          authority: "inherited",
+        })
+
+        const rolledBack = await fixture
+          .transaction(async (tx) => {
+            await tx.agents?.runs.createSubagent(input)
+            throw new Error("rollback")
+          })
+          .catch((error: unknown) => error)
+        expect(rolledBack).toMatchObject({ message: "rollback" })
+
+        await expect(storage.threads.getById({ projectId, id: "thread_child_1" })).resolves.toBe(
+          null
+        )
+        await expect(storage.messages.getById({ projectId, id: "task_child_1" })).resolves.toBe(
+          null
+        )
+        await expect(storage.runs.getById({ projectId, id: "child_1" })).resolves.toBe(null)
+      })
+    })
+
+    test("keeps a sub-agent's workspace on its thread, fenced by the thread's active run", async () => {
+      // Removal proofs: require `sandboxParams` again in transitionAgentThreadSandbox, and the
+      // child's acquire is refused as unconfigured; fence on `run.kind === "conversation"` again,
+      // and it is refused as lost; drop `startSubagentWorkspaceAgain`, and the destroyed
+      // workspace cannot be started again.
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture)
+        await storage.runs.start({
+          projectId,
+          id: "child_1",
+          execution: execution("child_token", new Date("2099-01-01")),
+        })
+        const acquire = {
+          projectId,
+          id: "thread_child_1",
+          action: "acquire" as const,
+          runId: "child_1",
+          executionToken: "child_token",
+          name: "child-workspace",
+          sourceFingerprint: "b".repeat(64),
+        }
+
+        // The turn it runs under does not own the child's thread.
+        await expectAgentError(
+          storage.threads.transitionSandbox({
+            ...acquire,
+            runId: "parent_1",
+            executionToken: "parent_token",
+          }),
+          "execution_lost"
+        )
+        await expect(storage.threads.transitionSandbox(acquire)).resolves.toMatchObject({
+          name: "child-workspace",
+          status: "busy",
+          owner: { runId: "child_1", executionToken: "child_token" },
+        })
+        await storage.threads.transitionSandbox({
+          ...acquire,
+          action: "settle",
+          status: "ready",
+          initialized: true,
+        })
+        await expect(
+          storage.threads.getById({ projectId, id: "thread_child_1" })
+        ).resolves.toMatchObject({
+          sandboxState: { name: "child-workspace", status: "ready", initialized: true },
+        })
+
+        // A run that destroyed it, or left it unsaved, leaves the next a fresh one to start.
+        await storage.threads.transitionSandbox(acquire)
+        await storage.threads.transitionSandbox({
+          ...acquire,
+          action: "settle",
+          status: "unavailable",
+          initialized: true,
+        })
+        await expectAgentError(storage.threads.transitionSandbox(acquire), "invalid_state")
+        await expect(
+          storage.threads.transitionSandbox({ ...acquire, name: "child-workspace-2" })
+        ).resolves.toEqual({
+          name: "child-workspace-2",
+          status: "busy",
+          initialized: false,
+          resetAt: expect.any(String),
+          sourceFingerprint: acquire.sourceFingerprint,
+          owner: { runId: "child_1", executionToken: "child_token" },
+        })
+      })
+    })
+
+    test("runs one child run at a time in its thread", async () => {
+      // Removal proof: drop the active-run check on a child's thread; `child_2` is admitted while
+      // `child_1` still runs.
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture)
+        await storage.runs.start({
+          projectId,
+          id: "child_1",
+          execution: execution("child_token"),
+        })
+        await storage.runs.finish({
+          projectId,
+          id: "parent_1",
+          executionToken: "parent_token",
+          status: "succeeded",
+        })
+        await createAndStartRun(
+          storage,
+          fixture,
+          runInput({
+            id: "parent_2",
+            threadId: "parent_thread",
+            triggerMessageId: "msg_user_2",
+            execution: execution("parent_token_2"),
+          })
+        )
+        const next = subagentInput("parent_token_2", {
+          id: "child_2",
+          parentRunId: "parent_2",
+          thread: { id: "thread_child_1", create: false },
+          trigger: { id: "trigger_child_2", parts: [{ type: "text", text: "Go on." }] },
+          createdAt: at("2026-06-23T10:03:00.000Z"),
+        })
+        await createTestAgentExecution(fixture, {
+          projectId,
+          runId: next.id,
+          executionId: next.executionId,
+          sourceExecutionId: "test_agent_execution:parent_2",
+          authority: "inherited",
+        })
+
+        await expectAgentError(storage.runs.createSubagent(next), "active_run_exists")
+        await expectAgentError(
+          storage.runs.createSubagent({ ...next, spawnKey: "another-child" }),
+          "invalid_input"
+        )
+        await expectAgentError(
+          storage.runs.createSubagent({ ...next, thread: { id: "missing", create: false } }),
+          "thread_not_found"
+        )
+        await expectAgentError(
+          storage.runs.createSubagent({ ...next, thread: { id: "thread_child_1", create: true } }),
+          "duplicate_id"
+        )
+
+        await storage.runs.finish({
+          projectId,
+          id: "child_1",
+          executionToken: "child_token",
+          status: "succeeded",
+          result: { text: "Three open orders." },
+        })
+        await expect(
+          storage.threads.getById({ projectId, id: "thread_child_1" })
+        ).resolves.toMatchObject({ activeRunId: null })
+
+        await expect(storage.runs.createSubagent(next)).resolves.toMatchObject({
+          id: "child_2",
+          threadId: "thread_child_1",
+          triggerMessageId: "trigger_child_2",
+          parentRunId: "parent_2",
+        })
+        await expect(
+          storage.threads.getById({ projectId, id: "thread_child_1" })
+        ).resolves.toMatchObject({
+          parent: { threadId: "parent_thread", spawnedBy: "parent_1", key: "research-orders" },
+          activeRunId: "child_2",
+          messageCount: 2,
+          lastMessageAt: at("2026-06-23T10:03:00.000Z"),
+        })
+        const { messages } = await storage.messages.list({ projectId, threadId: "thread_child_1" })
+        expect(messages.map(({ id, seq, runId }) => ({ id, seq, runId }))).toEqual([
+          { id: "task_child_1", seq: 1, runId: "child_1" },
+          { id: "trigger_child_2", seq: 2, runId: "child_2" },
+        ])
+      })
+    })
+
+    test("deletes a dead child run's messages whole, its trigger included", async () => {
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture)
+        await storage.runs.start({ projectId, id: "child_1", execution: execution("child_token") })
+        await storage.messages.append({
+          id: "work_child_1",
+          projectId,
+          threadId: "thread_child_1",
+          runId: "child_1",
+          role: "assistant",
+          parts: [{ type: "text", text: "Looking." }],
+          createdAt: at("2026-06-23T10:02:00.000Z"),
+        })
+
+        await expect(
+          storage.messages.deleteByRunId({
+            projectId,
+            threadId: "thread_child_1",
+            runId: "child_1",
+          })
+        ).resolves.toBe(2)
+        await expect(
+          storage.threads.getById({ projectId, id: "thread_child_1" })
+        ).resolves.toMatchObject({ messageCount: 0, lastMessageAt: undefined })
+      })
+    })
+
+    test("never lists a child's thread", async () => {
+      // Removal proof: drop the conversation filter from `threads.list`; the child's thread is
+      // listed with its owner's conversations.
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture)
+        // A participant of the conversation lists it among what is shared with them, alone.
+        const reader = { type: "user", id: "usr_reader" } as const
+        await storage.threads.addParticipants({
+          ...participantsInput([reader.id]),
+          threadId: "parent_thread",
+        })
+
+        for (const input of [
+          {},
+          { ownerPrincipal: owner },
+          { participantPrincipal: reader },
+          { statuses: ["active" as const] },
+        ]) {
+          await expect(storage.threads.list({ projectId, ...input })).resolves.toMatchObject({
+            threads: [{ id: "parent_thread" }],
+            total: 1,
+          })
+        }
+      })
+    })
+
+    test("lists a conversation's sub-agent threads, oldest first, by the turn that spawned them", async () => {
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture, {
+          id: "child_b",
+          spawnKey: "b",
+          createdAt: at("2026-06-23T10:02:00.000Z"),
+        })
+        await createSubagent(storage, fixture, {
+          id: "child_a",
+          spawnKey: "a",
+          createdAt: at("2026-06-23T10:01:00.000Z"),
+        })
+        const children = (input: Partial<ListAgentThreadChildrenInput> = {}) =>
+          storage.threads
+            .listChildren({ projectId, parentThreadId: "parent_thread", ...input })
+            .then((threads) => threads.map((thread) => thread.id))
+
+        expect(await children()).toEqual(["thread_child_a", "thread_child_b"])
+        expect(await children({ parentRunId: "parent_1" })).toEqual([
+          "thread_child_a",
+          "thread_child_b",
+        ])
+        expect(await children({ parentRunId: "parent_2" })).toEqual([])
+        expect(await children({ limit: 1, offset: 1 })).toEqual(["thread_child_b"])
+        expect(
+          await storage.threads.listChildren({ projectId, parentThreadId: "thread_child_a" })
+        ).toEqual([])
+        expect(
+          (await storage.threads.listChildren({ projectId, parentThreadId: "parent_thread" }))[0]
+        ).toMatchObject({
+          kind: "subagent",
+          parent: { threadId: "parent_thread", spawnedBy: "parent_1", key: "a" },
+        })
+      })
+    })
+
+    test("keeps a child's thread out of what only a conversation does", async () => {
+      await withStorage(async (storage, fixture) => {
+        await createRunningParent(storage, fixture)
+        await createSubagent(storage, fixture)
+
+        await expectAgentError(
+          storage.threads.fork(forkInput({ sourceThreadId: "thread_child_1" })),
+          "thread_not_conversation"
+        )
+        await expectAgentError(
+          storage.threads.addParticipants({
+            ...participantsInput(["usr_bob"]),
+            threadId: "thread_child_1",
+          }),
+          "thread_not_conversation"
+        )
+        await expectAgentError(
+          createRun(
+            storage,
+            fixture,
+            runInput({ id: "turn_in_child", threadId: "thread_child_1" })
+          ),
+          "thread_not_conversation"
+        )
+
+        // A fork of the conversation copies its messages, never its children's.
+        const fork = await storage.threads.fork(forkInput({ sourceThreadId: "parent_thread" }))
+        expect(fork).toMatchObject({ kind: "conversation", messageCount: 0 })
+        expect(fork).not.toHaveProperty("parent")
+        await expect(
+          storage.threads.list({ projectId, ownerPrincipal: otherUser })
+        ).resolves.toMatchObject({ threads: [{ id: "thr_fork" }], total: 1 })
       })
     })
 
@@ -861,22 +1642,28 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
             id: "child_1",
             executionToken: "child_token",
             status: "succeeded",
-            result: {},
+            result: { text: "  " },
+          }),
+          "invalid_input"
+        )
+
+        await expectAgentError(
+          storage.runs.finish({
+            projectId,
+            id: "child_1",
+            executionToken: "child_token",
+            status: "succeeded",
+            result: {
+              text: "Three open orders.",
+              files: [{ path: "../orders.png", fileRef: testFileRef("orders.png") }],
+            },
           }),
           "invalid_input"
         )
 
         const result = {
           text: "Three open orders.",
-          files: [
-            {
-              blobId: `blob_${"a".repeat(64)}`,
-              digest: `sha256:${"a".repeat(64)}` as const,
-              fileName: "orders.csv",
-              mediaType: "text/csv",
-              sizeBytes: 42,
-            },
-          ],
+          files: [{ path: "charts/orders.png", fileRef: testFileRef("orders.png") }],
         }
         const completed = await storage.runs.finish({
           projectId,
@@ -950,32 +1737,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
 
     // ── execution reclaim ───────────────────────────────────────────────────────────────────────
 
-    test("reclaim rotates the execution token and bumps the attempt", async () => {
-      await withStorage(async (storage, fixture) => {
-        await storage.threads.create(threadInput())
-        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
-
-        const reclaimed = await storage.runs.reclaim({
-          projectId,
-          id: "run_1",
-          execution: execution("exec_2"),
-        })
-        expect(reclaimed).toMatchObject({ status: "running", attempt: 2 })
-        expect(reclaimed.execution?.token).toBe("exec_2")
-
-        await expectAgentError(
-          storage.runs.finish({
-            projectId,
-            id: "run_1",
-            executionToken: "exec_1",
-            status: "succeeded",
-          }),
-          "execution_lost"
-        )
-      })
-    })
-
-    test("projects confirmed queue ownership monotonically and fences stale executions", async () => {
+    test("projects confirmed queue ownership monotonically and reclaim fences stale executions", async () => {
       await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
         await createAndStartRun(
@@ -1005,11 +1767,22 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
         })
         expect(older.execution?.queueLeaseExpiresAt.toISOString()).toBe("2026-06-23T10:03:00.000Z")
 
-        await storage.runs.reclaim({
+        const reclaimed = await storage.runs.reclaim({
           projectId,
           id: "run_1",
           execution: execution("exec_2", at("2026-06-23T10:04:00.000Z")),
         })
+        expect(reclaimed).toMatchObject({ status: "running", attempt: 2 })
+        expect(reclaimed.execution?.token).toBe("exec_2")
+        await expectAgentError(
+          storage.runs.finish({
+            projectId,
+            id: "run_1",
+            executionToken: "exec_1",
+            status: "succeeded",
+          }),
+          "execution_lost"
+        )
         await expectAgentError(
           storage.runs.confirmExecutionOwnership({
             projectId,
@@ -1087,11 +1860,10 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
           finishReason: "stop",
           diagnostics: [
             {
-              code: "output_file_too_large",
+              code: "step_limit_reached",
               severity: "warning",
-              scope: "output",
-              path: "reports/full.csv",
-              message: "This generated file was skipped.",
+              scope: "run",
+              message: "The Agent reached its 100-step limit before producing a final answer.",
             },
           ],
           completedAt: at("2026-06-23T10:07:00.000Z"),
@@ -1103,11 +1875,10 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
         })
         expect(finished.diagnostics).toEqual([
           {
-            code: "output_file_too_large",
+            code: "step_limit_reached",
             severity: "warning",
-            scope: "output",
-            path: "reports/full.csv",
-            message: "This generated file was skipped.",
+            scope: "run",
+            message: "The Agent reached its 100-step limit before producing a final answer.",
           },
         ])
         await expect(
@@ -1397,6 +2168,70 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
       })
     })
 
+    // Guard proof: make `countsAsThreadMessage` return true; the thread, its fork and the count
+    // after a run's messages go read 2, 2 and 2.
+    test("counts only the messages the conversation shows", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput())
+        await storage.messages.append({
+          id: "msg_user_1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "Mark INV-2041 paid" }],
+          createdAt: at("2026-06-23T10:00:30.000Z"),
+        })
+        // What Sixb writes to resume a turn once its calls are decided: the chat shows none of it.
+        await storage.messages.append({
+          id: "msg_resume_1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          authorPrincipal: owner,
+          parts: [
+            {
+              type: "approval-outcome",
+              approvalId: "apr_1",
+              status: "approved",
+              call: {
+                kind: "action",
+                actionId: "mark-paid",
+                subject: { kind: "object", objectTypeId: "invoice", primaryId: "INV-2041" },
+              },
+            },
+          ],
+          createdAt: at("2026-06-23T10:02:00.000Z"),
+        })
+
+        const thread = await storage.threads.getById({ projectId, id: "thr_1" })
+        expect(thread).toMatchObject({ messageCount: 1 })
+        // It is still the thread's latest message.
+        expect(thread?.lastMessageAt?.toISOString()).toBe("2026-06-23T10:02:00.000Z")
+        expect((await storage.threads.fork(forkInput())).messageCount).toBe(1)
+
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
+        await storage.messages.append({
+          id: "msg_asst_1",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_1",
+          role: "assistant",
+          parts: [{ type: "text", text: "Marked paid." }],
+          createdAt: at("2026-06-23T10:03:00.000Z"),
+        })
+        expect(await storage.threads.getById({ projectId, id: "thr_1" })).toMatchObject({
+          messageCount: 2,
+        })
+
+        await storage.messages.deleteByRunId({ projectId, threadId: "thr_1", runId: "run_1" })
+        expect(await storage.threads.getById({ projectId, id: "thr_1" })).toMatchObject({
+          messageCount: 1,
+        })
+      })
+    })
+
     test("lists messages with role filter, ordering, and pagination", async () => {
       await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
@@ -1542,15 +2377,20 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
         await expect(
           storage.checkpoints.getByRunIds({
             projectId,
+            threadId: "thr_1",
             runIds: ["run_2", "missing", "run_2"],
           })
         ).resolves.toEqual([created])
         await expect(
           storage.checkpoints.getByRunIds({
             projectId: otherProjectId,
+            threadId: "thr_1",
             runIds: ["run_2"],
           })
         ).resolves.toEqual([])
+        await expect(
+          storage.checkpoints.getByRunIds({ projectId, threadId: "thr_2", runIds: ["run_2"] })
+        ).resolves.toEqual([])
 
         const retained = await storage.messages.list({
           projectId,
@@ -1728,5 +2568,321 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorageContra
         )
       })
     })
+
+    test("forks the finished history into a thread its caller owns alone", async () => {
+      // Removal proof: copy every message while a turn is running; `m5` lands in the fork.
+      await withStorage(async (storage, fixture) => {
+        await prepareForkSource(storage, fixture)
+        const sourceBefore = await storage.threads.getById({ projectId, id: "thr_1" })
+        const source = await storage.messages.list({ projectId, threadId: "thr_1" })
+
+        const fork = await storage.threads.fork(forkInput())
+
+        expect(fork).toEqual({
+          id: "thr_fork",
+          projectId,
+          kind: "conversation",
+          ownerPrincipal: otherUser,
+          title: "Slipped deals",
+          status: "active",
+          activeRunId: null,
+          messageCount: 4,
+          createdAt: at("2026-06-23T11:00:00.000Z"),
+          updatedAt: at("2026-06-23T11:00:00.000Z"),
+        })
+        expect(await storage.threads.getById({ projectId, id: "thr_fork" })).toEqual(fork)
+
+        const copied = await storage.messages.list({ projectId, threadId: "thr_fork" })
+        const finished = source.messages.slice(0, 4)
+        expect(copied.messages.map(({ id: _id, threadId: _threadId, ...rest }) => rest)).toEqual(
+          finished.map(({ id: _id, threadId: _threadId, ...rest }) => rest)
+        )
+        expect(copied.messages.every((message) => message.threadId === "thr_fork")).toBe(true)
+
+        const copiedIds = copied.messages.map((message) => message.id)
+        expect(new Set(copiedIds).size).toBe(4)
+        expect(copiedIds.some((id) => source.messages.some((message) => message.id === id))).toBe(
+          false
+        )
+
+        // A fork of an old conversation sorts with what its owner just did.
+        // Removal proof: give the fork the last copied message's time; it sorts after the source.
+        const listed = await storage.threads.list({ projectId })
+        expect(listed.threads.map((thread) => thread.id)).toEqual(["thr_fork", "thr_1"])
+
+        // The source keeps everything, its running turn included.
+        expect(await storage.threads.getById({ projectId, id: "thr_1" })).toEqual(sourceBefore)
+        expect((await storage.messages.list({ projectId, threadId: "thr_1" })).messages).toEqual(
+          source.messages
+        )
+
+        const next = await storage.messages.append({
+          id: "m_fork_next",
+          projectId,
+          threadId: "thr_fork",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "Draft them for me." }],
+        })
+        expect(next.seq).toBe(5)
+        expect(await storage.threads.getById({ projectId, id: "thr_fork" })).toMatchObject({
+          messageCount: 5,
+          lastMessageAt: next.createdAt,
+        })
+      })
+    })
+
+    test("copies a failed last turn with the checkpoint it wrote", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareForkSource(storage, fixture)
+        await storage.runs.finish({
+          id: "run_3",
+          projectId,
+          executionToken: "exec_3",
+          status: "failed",
+        })
+
+        const fork = await storage.threads.fork(forkInput())
+
+        expect(fork.messageCount).toBe(5)
+        expect(
+          await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork" })
+        ).toMatchObject({ createdByRunId: "run_3", summarizedThroughSeq: 4, observedHeadSeq: 5 })
+      })
+    })
+
+    test("forks a fork, which copies the same run's checkpoint again", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareForkSource(storage, fixture)
+        await storage.threads.fork(forkInput())
+
+        const second = await storage.threads.fork(
+          forkInput({ id: "thr_fork_of_fork", sourceThreadId: "thr_fork" })
+        )
+
+        expect(second.messageCount).toBe(4)
+        const copies = await Promise.all(
+          ["thr_1", "thr_fork", "thr_fork_of_fork"].map((threadId) =>
+            storage.checkpoints.getByRunIds({ projectId, threadId, runIds: ["run_2"] })
+          )
+        )
+        expect(copies.map(([checkpoint]) => checkpoint?.threadId)).toEqual([
+          "thr_1",
+          "thr_fork",
+          "thr_fork_of_fork",
+        ])
+        expect(new Set(copies.map(([checkpoint]) => checkpoint?.id)).size).toBe(3)
+        expect(
+          await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork_of_fork" })
+        ).toEqual(copies[2]?.[0])
+      })
+    })
+
+    test("keeps the latest checkpoint that does not anchor on the running turn", async () => {
+      // Removal proof: drop the observed-head condition when choosing the checkpoint; the fork
+      // keeps `checkpoint_2`, which anchors on the running turn's message the fork does not have.
+      await withStorage(async (storage, fixture) => {
+        await prepareForkSource(storage, fixture)
+        const [first, second] = await storage.checkpoints.getByRunIds({
+          projectId,
+          threadId: "thr_1",
+          runIds: ["run_2", "run_3"],
+        })
+
+        await storage.threads.fork(forkInput())
+
+        const kept = await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork" })
+        if (!kept || !first) throw new Error("Expected the fork to keep checkpoint_1.")
+
+        const { id: keptId, threadId: keptThreadId, previousCheckpointId, ...copied } = kept
+        const { id: _firstId, threadId: _firstThreadId, ...original } = first
+        expect(copied).toEqual(original)
+        expect(keptId).not.toBe(first.id)
+        expect(keptThreadId).toBe("thr_fork")
+        expect(previousCheckpointId).toBeUndefined()
+
+        // The fork's projection reads the kept checkpoint and the copied tail after it.
+        const tail = await storage.messages.list({
+          projectId,
+          threadId: "thr_fork",
+          afterSeq: kept.summarizedThroughSeq,
+          order: "asc",
+        })
+        expect(
+          projectAgentThreadModelContext({ checkpoint: kept, messages: tail.messages })
+        ).toHaveLength(3)
+
+        await expect(
+          storage.checkpoints.getByRunIds({ projectId, threadId: "thr_fork", runIds: ["run_2"] })
+        ).resolves.toEqual([kept])
+        await expect(
+          storage.checkpoints.getByRunIds({
+            projectId,
+            threadId: "thr_1",
+            runIds: ["run_2", "run_3"],
+          })
+        ).resolves.toEqual([first, second])
+
+        // Once the turn has finished, the checkpoint it wrote anchors on copied history.
+        await storage.messages.append({
+          id: "m6",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_3",
+          role: "assistant",
+          parts: [{ type: "text", text: "Drafted." }],
+        })
+        await storage.runs.finish({
+          id: "run_3",
+          projectId,
+          executionToken: "exec_3",
+          status: "succeeded",
+        })
+        await storage.threads.fork(forkInput({ id: "thr_fork_2" }))
+
+        expect(
+          await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork_2" })
+        ).toMatchObject({
+          createdByRunId: "run_3",
+          threadId: "thr_fork_2",
+          summarizedThroughSeq: 4,
+          observedHeadSeq: 5,
+        })
+        expect((await storage.threads.getById({ projectId, id: "thr_fork_2" }))?.messageCount).toBe(
+          6
+        )
+      })
+    })
+
+    test("forks an empty thread and rejects a missing source or a taken id", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const fork = await storage.threads.fork(forkInput({ title: undefined }))
+        expect(fork).toMatchObject({ messageCount: 0, activeRunId: null })
+        expect(fork.createdAt).toEqual(at("2026-06-23T11:00:00.000Z"))
+        expect(fork.lastMessageAt).toBeUndefined()
+        expect(fork.title).toBeUndefined()
+
+        await expectAgentError(storage.threads.fork(forkInput()), "duplicate_id")
+        await expectAgentError(
+          storage.threads.fork(forkInput({ id: "thr_other", sourceThreadId: "missing" })),
+          "thread_not_found"
+        )
+        await expectAgentError(
+          storage.threads.fork(forkInput({ id: "thr_other", projectId: otherProjectId })),
+          "thread_not_found"
+        )
+      })
+    })
+
+    // Regression proof: drop the remap from a provider's fork; the copy then names the source's
+    // artifact, which the fork's readers may not reach.
+    test("names the fork's copies of the source's artifacts in the messages it copies", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        const text = "See ![Revenue](artifact:art_0000000001#chart=revenue) and art_0000000009."
+        await storage.messages.append({
+          id: "msg_shown",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text }],
+        })
+
+        await storage.threads.fork(
+          forkInput({ artifactCopies: { art_0000000001: "art_000000copy1" } })
+        )
+
+        const [copy] = (await storage.messages.list({ projectId, threadId: "thr_fork" })).messages
+        expect(copy?.parts).toEqual([
+          {
+            type: "text",
+            text: "See ![Revenue](artifact:art_000000copy1#chart=revenue) and art_0000000009.",
+          },
+        ])
+        const [source] = (await storage.messages.list({ projectId, threadId: "thr_1" })).messages
+        expect(source?.parts).toEqual([{ type: "text", text }])
+      })
+    })
+
+    // Regression proof: drop the summary's remap in planAgentThreadFork; the copied checkpoint
+    // then names the source's artifact.
+    test("names the fork's copies in the checkpoint summary it copies", async () => {
+      await withStorage(async (storage, fixture) => {
+        const summary = "Drafted art_0000000001 for Acme; art_0000000009 is the source data."
+        await prepareForkSource(storage, fixture, summary)
+        await storage.runs.finish({
+          id: "run_3",
+          projectId,
+          executionToken: "exec_3",
+          status: "failed",
+        })
+
+        await storage.threads.fork(
+          forkInput({ artifactCopies: { art_0000000001: "art_000000copy1" } })
+        )
+
+        expect(
+          (await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork" }))?.summary
+        ).toBe("Drafted art_000000copy1 for Acme; art_0000000009 is the source data.")
+        expect(
+          (await storage.checkpoints.getLatest({ projectId, threadId: "thr_1" }))?.summary
+        ).toBe(summary)
+      })
+    })
+
+    test("starts a forked workspace with a new, reset sandbox", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput({ sandboxParams: { repo: "deals" } }))
+
+        const fork = await storage.threads.fork(
+          forkInput({ sandboxParams: { repo: "deals" }, sandboxName: "sixb-sb-fork" })
+        )
+        expect(fork.sandboxParams).toEqual({ repo: "deals" })
+        expect(fork.sandboxState).toEqual({
+          name: "sixb-sb-fork",
+          status: "new",
+          initialized: false,
+          resetAt: "2026-06-23T11:00:00.000Z",
+        })
+
+        await expectAgentError(
+          storage.threads.fork(forkInput({ id: "thr_2", sandboxParams: { repo: "deals" } })),
+          "invalid_input"
+        )
+        await expectAgentError(
+          storage.threads.fork(forkInput({ id: "thr_2", sandboxName: "sixb-sb-fork" })),
+          "invalid_input"
+        )
+        await expectAgentError(
+          storage.threads.fork(
+            forkInput({ id: "thr_2", sandboxParams: {}, sandboxName: "../invalid" })
+          ),
+          "invalid_input"
+        )
+        expect(await storage.threads.getById({ projectId, id: "thr_2" })).toBeNull()
+      })
+    })
+
+    test("rolls back a fork with its containing storage transaction", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareForkSource(storage, fixture)
+        const rollback = new Error("rollback fork")
+
+        await expect(
+          fixture.transaction(async (tx) => {
+            if (!tx.agents) throw new Error("Expected agent storage in transaction.")
+            await tx.agents.threads.fork(forkInput())
+            throw rollback
+          })
+        ).rejects.toBe(rollback)
+
+        expect(await storage.threads.getById({ projectId, id: "thr_fork" })).toBeNull()
+        expect((await storage.messages.list({ projectId, threadId: "thr_fork" })).total).toBe(0)
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_fork" })).toBeNull()
+      })
+    })
   })
 }