@namzu/sdk 0.4.0 → 0.4.2

package/src/runtime/query/__tests__/checkpoint.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest'
+import type { RunDiskStore } from '../../../store/run/disk.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { EmergencySaveId, RunId } from '../../../types/ids/index.js'
+import type { EmergencySaveData } from '../../../types/run/emergency.js'
+import { CheckpointManager, projectEmergencyToCheckpoint } from '../checkpoint.js'
+
+function makeCheckpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
+	return {
+		id: 'cp_test_a' as CheckpointId,
+		runId: 'run_test' as RunId,
+		iteration: 1,
+		messages: [{ role: 'user', content: 'hello' }],
+		tokenUsage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: {
+			inputCostPer1M: 0,
+			outputCostPer1M: 0,
+			totalCost: 0,
+			cacheDiscount: 0,
+		},
+		guardState: { iterationCount: 1, elapsedMs: 100 },
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+function makeStoreStub(checkpoints: IterationCheckpoint[]): RunDiskStore {
+	return {
+		listCheckpoints: async () => checkpoints,
+	} as unknown as RunDiskStore
+}
+
+describe('CheckpointManager.listEntries', () => {
+	it('projects stored checkpoints to CheckpointListEntry', async () => {
+		const store = makeStoreStub([
+			makeCheckpoint({
+				id: 'cp_a' as CheckpointId,
+				iteration: 1,
+				createdAt: 1000,
+				messages: [
+					{ role: 'user', content: 'hi' },
+					{ role: 'assistant', content: 'hello' },
+				],
+			}),
+			makeCheckpoint({
+				id: 'cp_b' as CheckpointId,
+				iteration: 2,
+				createdAt: 2000,
+				messages: [
+					{ role: 'user', content: 'hi' },
+					{ role: 'assistant', content: 'hello' },
+					{ role: 'user', content: 'more' },
+				],
+			}),
+		])
+
+		const mgr = new CheckpointManager(store)
+		const entries = await mgr.listEntries()
+
+		expect(entries).toHaveLength(2)
+		expect(entries[0]).toEqual({
+			id: 'cp_a',
+			runId: 'run_test',
+			iteration: 1,
+			createdAt: 1000,
+			messageCount: 2,
+		})
+		expect(entries[1]).toEqual({
+			id: 'cp_b',
+			runId: 'run_test',
+			iteration: 2,
+			createdAt: 2000,
+			messageCount: 3,
+		})
+	})
+
+	it('returns empty array when no checkpoints exist', async () => {
+		const mgr = new CheckpointManager(makeStoreStub([]))
+		expect(await mgr.listEntries()).toEqual([])
+	})
+
+	it('does not include full checkpoint payload fields', async () => {
+		const mgr = new CheckpointManager(
+			makeStoreStub([
+				makeCheckpoint({
+					toolResultHashes: { call_x: 'hash' },
+					branchStack: [{ agentId: 'a', decision: 'd', confidence: 1, timestamp: 0 }],
+				}),
+			]),
+		)
+		const [entry] = await mgr.listEntries()
+		expect(entry).not.toHaveProperty('tokenUsage')
+		expect(entry).not.toHaveProperty('costInfo')
+		expect(entry).not.toHaveProperty('toolResultHashes')
+		expect(entry).not.toHaveProperty('branchStack')
+		expect(entry).not.toHaveProperty('guardState')
+		expect(entry).not.toHaveProperty('messages')
+	})
+})
+
+function makeEmergencyDump(overrides: Partial<EmergencySaveData> = {}): EmergencySaveData {
+	return {
+		id: 'esave_dump_a' as EmergencySaveId,
+		runId: 'run_victim' as RunId,
+		messages: [
+			{ role: 'user', content: 'before the crash' },
+			{ role: 'assistant', content: 'working' },
+		],
+		tokenUsage: {
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 15,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		currentIteration: 7,
+		startedAt: 1_000,
+		savedAt: 2_500,
+		processSignal: 'SIGTERM',
+		...overrides,
+	}
+}
+
+describe('projectEmergencyToCheckpoint', () => {
+	it('produces an IterationCheckpoint with all required fields', () => {
+		const dump = makeEmergencyDump()
+		const cp = projectEmergencyToCheckpoint(dump)
+
+		expect(cp.runId).toBe('run_victim')
+		expect(cp.iteration).toBe(7)
+		expect(cp.messages).toBe(dump.messages)
+		expect(cp.tokenUsage).toBe(dump.tokenUsage)
+		expect(cp.createdAt).toBe(2_500)
+		expect(cp.guardState).toEqual({ iterationCount: 7, elapsedMs: 1_500 })
+		expect(cp.costInfo).toEqual({
+			inputCostPer1M: 0,
+			outputCostPer1M: 0,
+			totalCost: 0,
+			cacheDiscount: 0,
+		})
+	})
+
+	it('derives a deterministic CheckpointId from the emergency save id', () => {
+		const dump = makeEmergencyDump({ id: 'esave_xyz123' as EmergencySaveId })
+		const cp1 = projectEmergencyToCheckpoint(dump)
+		const cp2 = projectEmergencyToCheckpoint(dump)
+
+		expect(cp1.id).toBe('cp_emergency_xyz123')
+		expect(cp1.id).toBe(cp2.id)
+	})
+
+	it('clamps guardState.elapsedMs to 0 when savedAt precedes startedAt', () => {
+		const cp = projectEmergencyToCheckpoint(makeEmergencyDump({ startedAt: 2_000, savedAt: 1_000 }))
+		expect(cp.guardState.elapsedMs).toBe(0)
+	})
+
+	it('leaves optional fields (toolResultHashes, branchStack, activeNode) unset', () => {
+		const cp = projectEmergencyToCheckpoint(makeEmergencyDump())
+		expect(cp.toolResultHashes).toBeUndefined()
+		expect(cp.branchStack).toBeUndefined()
+		expect(cp.activeNode).toBeUndefined()
+	})
+})

package/src/runtime/query/checkpoint.ts

@@ -8,9 +8,52 @@ import type {
 	IterationCheckpoint,
 } from '../../types/hitl/index.js'
 import type { AssistantMessage } from '../../types/message/index.js'
+import type { EmergencySaveData } from '../../types/run/emergency.js'
+import type { CheckpointListEntry } from '../../types/run/replay.js'
+import { ZERO_COST } from '../../utils/cost.js'
 import { buildToolResultHashes } from '../../utils/hash.js'
 import { generateCheckpointId } from '../../utils/id.js'
 
+function toCheckpointListEntry(cp: IterationCheckpoint): CheckpointListEntry {
+	return {
+		id: cp.id,
+		runId: cp.runId,
+		iteration: cp.iteration,
+		createdAt: cp.createdAt,
+		messageCount: cp.messages.length,
+	}
+}
+
+/**
+ * Project an {@link EmergencySaveData} dump to an {@link IterationCheckpoint}
+ * shape so `replay({ fromCheckpoint: 'emergency' })` can consume it through
+ * the same restore path as any other checkpoint.
+ *
+ * The projection is lossy: `costInfo`, `guardState.elapsedMs`,
+ * `toolResultHashes`, `branchStack`, and `activeNode` are not captured at
+ * emergency-save time and default to zero/empty values. The synthetic
+ * checkpoint id is derived deterministically from the emergency save id so
+ * re-projecting the same dump yields the same {@link CheckpointId}.
+ *
+ * See ses_005-deterministic-replay design §2 + §5.2.
+ */
+export function projectEmergencyToCheckpoint(dump: EmergencySaveData): IterationCheckpoint {
+	const emergencySuffix = dump.id.replace(/^esave_/, '')
+	return {
+		id: `cp_emergency_${emergencySuffix}` as CheckpointId,
+		runId: dump.runId,
+		iteration: dump.currentIteration,
+		messages: dump.messages,
+		tokenUsage: dump.tokenUsage,
+		costInfo: { ...ZERO_COST },
+		guardState: {
+			iterationCount: dump.currentIteration,
+			elapsedMs: Math.max(0, dump.savedAt - dump.startedAt),
+		},
+		createdAt: dump.savedAt,
+	}
+}
+
 export class CheckpointManager {
 	private store: RunDiskStore
 
@@ -60,6 +103,17 @@ export class CheckpointManager {
 		return this.store.listCheckpoints()
 	}
 
+	/**
+	 * Listing projection used by the public `listCheckpoints` API. Returns
+	 * only the fields a consumer needs to pick a fork point for
+	 * {@link import('./replay/prepare.js').prepareReplayState} — not the
+	 * full checkpoint payload. See ses_005-deterministic-replay design §3.1.
+	 */
+	async listEntries(): Promise<CheckpointListEntry[]> {
+		const checkpoints = await this.store.listCheckpoints()
+		return checkpoints.map(toCheckpointListEntry)
+	}
+
 	async prune(keepLast: number): Promise<void> {
 		const all = await this.list()
 		if (all.length <= keepLast) return

package/src/runtime/query/context.ts

@@ -99,11 +99,6 @@ export interface RunContext {
  */
 const migrationPromises = new Map<string, Promise<FilesystemMigrationResult>>()
 
-/** Testing hook — clears the first-call guard cache. */
-export function __resetMigrationGuardForTests(): void {
-	migrationPromises.clear()
-}
-
 export class RunContextFactory {
 	/**
 	 * Run the boot-time filesystem migration for `rootDir` at most once per

package/src/runtime/query/index.ts

@@ -27,7 +27,7 @@ import { type Message, createSystemMessage } from '../../types/message/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
-import type { AgentRun, AgentRunConfig, RunEvent, RunEventListener } from '../../types/run/index.js'
+import type { AgentRunConfig, Run, RunEvent, RunEventListener } from '../../types/run/index.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
@@ -136,7 +136,7 @@ export interface QueryParams {
 	invocationState?: InvocationState
 }
 
-export async function* query(params: QueryParams): AsyncGenerator<RunEvent, AgentRun> {
+export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
 	// call per process per root actually runs; subsequent calls short-circuit
 	// via the in-memory guard in `context.ts`. Kept here rather than inside
@@ -335,7 +335,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 
 	const tracer = getTracer()
 
-	return yield* (async function* (): AsyncGenerator<RunEvent, AgentRun> {
+	return yield* (async function* (): AsyncGenerator<RunEvent, Run> {
 		const rootSpan = tracer.startSpan(agentRunSpanName(params.agentName))
 		rootSpan.setAttributes({
 			[NAMZU.RUN_ID]: ctx.runMgr.id,
@@ -515,7 +515,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 export async function drainQuery(
 	params: Omit<QueryParams, 'resumeHandler'> & { resumeHandler?: ResumeHandler },
 	listener?: RunEventListener,
-): Promise<AgentRun> {
+): Promise<Run> {
 	const fullParams: QueryParams = {
 		...params,
 		resumeHandler: params.resumeHandler ?? autoApproveHandler,

package/src/runtime/query/replay/__tests__/mutate.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest'
+import type { ToolCallId } from '../../../../types/ids/index.js'
+import type { AssistantMessage, Message, ToolMessage } from '../../../../types/message/index.js'
+import { type Mutation, MutationNotApplicableError } from '../../../../types/run/replay.js'
+import { applyMutations } from '../mutate.js'
+
+function assistantWithCalls(toolCallIds: string[]): AssistantMessage {
+	return {
+		role: 'assistant',
+		content: null,
+		toolCalls: toolCallIds.map((id) => ({
+			id,
+			type: 'function',
+			function: { name: 'noop', arguments: '{}' },
+		})),
+	}
+}
+
+describe('applyMutations / injectToolResponse', () => {
+	it('appends a ToolMessage when the toolCallId is pending', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'do stuff' },
+			assistantWithCalls(['call_a', 'call_b']),
+			{ role: 'tool', content: 'a done', toolCallId: 'call_a' },
+		]
+		const mutations: Mutation[] = [
+			{
+				type: 'injectToolResponse',
+				toolCallId: 'call_b' as ToolCallId,
+				response: { success: true, output: 'mocked-b', data: { x: 1 } },
+			},
+		]
+
+		const result = applyMutations(messages, mutations)
+
+		expect(result).toHaveLength(4)
+		const last = result[3] as ToolMessage
+		expect(last.role).toBe('tool')
+		expect(last.toolCallId).toBe('call_b')
+		expect(last.content).toBe('mocked-b')
+	})
+
+	it('throws MutationNotApplicableError when no pending tool calls exist', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'hi' },
+			{ role: 'assistant', content: 'hello' },
+		]
+		expect(() =>
+			applyMutations(messages, [
+				{
+					type: 'injectToolResponse',
+					toolCallId: 'call_missing' as ToolCallId,
+					response: { success: true, output: 'x' },
+				},
+			]),
+		).toThrow(MutationNotApplicableError)
+	})
+
+	it('throws with availableToolCallIds populated when toolCallId is not pending', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'do stuff' },
+			assistantWithCalls(['call_a', 'call_b']),
+		]
+		try {
+			applyMutations(messages, [
+				{
+					type: 'injectToolResponse',
+					toolCallId: 'call_z' as ToolCallId,
+					response: { success: true, output: 'x' },
+				},
+			])
+			expect.fail('expected MutationNotApplicableError')
+		} catch (err) {
+			expect(err).toBeInstanceOf(MutationNotApplicableError)
+			const e = err as MutationNotApplicableError
+			expect(e.availableToolCallIds).toEqual(['call_a', 'call_b'])
+		}
+	})
+
+	it('considers a tool call satisfied only when a subsequent ToolMessage responds to it', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'do stuff' },
+			assistantWithCalls(['call_a', 'call_b', 'call_c']),
+			{ role: 'tool', content: 'a done', toolCallId: 'call_a' },
+			{ role: 'tool', content: 'c done', toolCallId: 'call_c' },
+		]
+		try {
+			applyMutations(messages, [
+				{
+					type: 'injectToolResponse',
+					toolCallId: 'call_a' as ToolCallId,
+					response: { success: true, output: 're-answered' },
+				},
+			])
+			expect.fail('expected MutationNotApplicableError — call_a already satisfied')
+		} catch (err) {
+			const e = err as MutationNotApplicableError
+			expect(e.availableToolCallIds).toEqual(['call_b'])
+		}
+	})
+
+	it('applies mutations in order so a later mutation sees earlier ones', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'two calls pending' },
+			assistantWithCalls(['call_x', 'call_y']),
+		]
+		const result = applyMutations(messages, [
+			{
+				type: 'injectToolResponse',
+				toolCallId: 'call_x' as ToolCallId,
+				response: { success: true, output: 'x-result' },
+			},
+			{
+				type: 'injectToolResponse',
+				toolCallId: 'call_y' as ToolCallId,
+				response: { success: true, output: 'y-result' },
+			},
+		])
+
+		expect(result).toHaveLength(4)
+		expect((result[2] as ToolMessage).toolCallId).toBe('call_x')
+		expect((result[3] as ToolMessage).toolCallId).toBe('call_y')
+	})
+
+	it('returns the original messages unchanged when the mutation list is empty', () => {
+		const messages: Message[] = [
+			{ role: 'user', content: 'no-op' },
+			{ role: 'assistant', content: 'ok' },
+		]
+		const result = applyMutations(messages, [])
+		expect(result).toEqual(messages)
+		expect(result).not.toBe(messages)
+	})
+})

package/src/runtime/query/replay/__tests__/prepare.test.ts

@@ -0,0 +1,207 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { CheckpointId, IterationCheckpoint } from '../../../../types/hitl/index.js'
+import type { EmergencySaveId, RunId, ToolCallId } from '../../../../types/ids/index.js'
+import type { AssistantMessage, ToolMessage } from '../../../../types/message/index.js'
+import type { EmergencySaveData } from '../../../../types/run/emergency.js'
+import type { Mutation } from '../../../../types/run/replay.js'
+import { prepareReplayState } from '../prepare.js'
+
+const RUN_ID = 'run_source' as RunId
+
+function makeCheckpoint(overrides: Partial<IterationCheckpoint>): IterationCheckpoint {
+	return {
+		id: 'cp_default' as CheckpointId,
+		runId: RUN_ID,
+		iteration: 1,
+		messages: [{ role: 'user', content: 'hi' }],
+		tokenUsage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+		guardState: { iterationCount: 1, elapsedMs: 0 },
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+async function seedCheckpoint(baseDir: string, cp: IterationCheckpoint): Promise<void> {
+	const cpDir = join(baseDir, cp.runId, 'checkpoints')
+	await mkdir(cpDir, { recursive: true })
+	await writeFile(join(cpDir, `${cp.id}.json`), JSON.stringify(cp), 'utf-8')
+}
+
+async function seedEmergency(emergencyDir: string, dump: EmergencySaveData): Promise<void> {
+	await mkdir(emergencyDir, { recursive: true })
+	await writeFile(join(emergencyDir, `${dump.runId}.json`), JSON.stringify(dump), 'utf-8')
+}
+
+describe('prepareReplayState', () => {
+	let baseDir: string
+	let emergencyDir: string
+
+	beforeEach(async () => {
+		const wrapper = await mkdtemp(join(tmpdir(), 'namzu-prepare-replay-'))
+		baseDir = join(wrapper, 'runs')
+		emergencyDir = join(wrapper, 'emergency')
+		await mkdir(baseDir, { recursive: true })
+	})
+
+	afterEach(async () => {
+		// Per-test tmpdir isolation; vitest cleans tmpdir between runs.
+	})
+
+	it('resolves a specific CheckpointId and returns the checkpoint messages', async () => {
+		const cp = makeCheckpoint({
+			id: 'cp_one' as CheckpointId,
+			iteration: 3,
+			messages: [
+				{ role: 'user', content: 'start' },
+				{ role: 'assistant', content: 'ok' },
+			],
+		})
+		await seedCheckpoint(baseDir, cp)
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'cp_one' as CheckpointId,
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_one')
+		expect(prepared.messages).toEqual(cp.messages)
+		expect(prepared.attribution.sourceRunId).toBe(RUN_ID)
+		expect(prepared.attribution.fromCheckpointId).toBe('cp_one')
+		expect(prepared.attribution.mutations).toEqual([])
+		expect(prepared.attribution.replayedAt).toBeGreaterThan(0)
+	})
+
+	it("resolves 'latest' to the checkpoint with the highest iteration", async () => {
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_a' as CheckpointId, iteration: 1 }))
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_b' as CheckpointId, iteration: 5 }))
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_c' as CheckpointId, iteration: 3 }))
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'latest',
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_b')
+		expect(prepared.sourceCheckpoint.iteration).toBe(5)
+	})
+
+	it("throws when 'latest' is requested but no checkpoints exist", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'latest',
+			}),
+		).rejects.toThrow(/No checkpoints found/)
+	})
+
+	it('throws when a specific CheckpointId does not resolve', async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'cp_missing' as CheckpointId,
+			}),
+		).rejects.toThrow(/not found/)
+	})
+
+	it('applies injectToolResponse mutations at the fork point', async () => {
+		const assistantMsg: AssistantMessage = {
+			role: 'assistant',
+			content: null,
+			toolCalls: [{ id: 'call_a', type: 'function', function: { name: 'noop', arguments: '{}' } }],
+		}
+		const cp = makeCheckpoint({
+			id: 'cp_with_tool' as CheckpointId,
+			messages: [{ role: 'user', content: 'run tool' }, assistantMsg],
+		})
+		await seedCheckpoint(baseDir, cp)
+
+		const mutations: Mutation[] = [
+			{
+				type: 'injectToolResponse',
+				toolCallId: 'call_a' as ToolCallId,
+				response: { success: true, output: 'mocked-a' },
+			},
+		]
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'cp_with_tool' as CheckpointId,
+			mutate: mutations,
+		})
+
+		expect(prepared.messages).toHaveLength(3)
+		const appended = prepared.messages[2] as ToolMessage
+		expect(appended.role).toBe('tool')
+		expect(appended.toolCallId).toBe('call_a')
+		expect(appended.content).toBe('mocked-a')
+		expect(prepared.attribution.mutations).toEqual(mutations)
+	})
+
+	it("resolves 'emergency' via the emergency dump and projects it to a checkpoint", async () => {
+		const dump: EmergencySaveData = {
+			id: 'esave_xyz' as EmergencySaveId,
+			runId: RUN_ID,
+			messages: [{ role: 'user', content: 'before crash' }],
+			tokenUsage: {
+				promptTokens: 4,
+				completionTokens: 2,
+				totalTokens: 6,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			currentIteration: 9,
+			startedAt: 1_000,
+			savedAt: 2_000,
+			processSignal: 'SIGTERM',
+		}
+		await seedEmergency(emergencyDir, dump)
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'emergency',
+			emergencyDir,
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_emergency_xyz')
+		expect(prepared.sourceCheckpoint.iteration).toBe(9)
+		expect(prepared.messages).toEqual(dump.messages)
+		expect(prepared.attribution.fromCheckpointId).toBe('cp_emergency_xyz')
+	})
+
+	it("throws when 'emergency' is requested without emergencyDir", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'emergency',
+			}),
+		).rejects.toThrow(/emergencyDir/)
+	})
+
+	it("throws when 'emergency' dump file is missing", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'emergency',
+				emergencyDir,
+			}),
+		).rejects.toThrow(/No emergency dump/)
+	})
+})

package/src/runtime/query/replay/list.ts

@@ -0,0 +1,32 @@
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { CheckpointListEntry } from '../../../types/run/replay.js'
+import type { Logger } from '../../../utils/logger.js'
+import { CheckpointManager } from '../checkpoint.js'
+
+export interface ListCheckpointsInput {
+	/** Directory that contains `<runId>/` for the target run. */
+	baseDir: string
+	/** Run whose checkpoints should be listed. */
+	runId: RunId
+	logger?: Logger
+}
+
+/**
+ * Read-only listing of a run's checkpoints for use with {@link
+ * import('./prepare.js').prepareReplayState}. Returns the public
+ * {@link CheckpointListEntry} projection — just enough for a caller to
+ * pick a fork point — not the full `IterationCheckpoint` payload.
+ *
+ * Entries are returned in the order the underlying store returns them
+ * (disk store sorts by `createdAt` ascending). Callers that want a
+ * specific order should sort client-side.
+ *
+ * See ses_005-deterministic-replay/design.md §3.1.
+ */
+export async function listCheckpoints(input: ListCheckpointsInput): Promise<CheckpointListEntry[]> {
+	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
+	await store.initRun(input.runId)
+	const mgr = new CheckpointManager(store)
+	return mgr.listEntries()
+}