@namzu/sdk 19.0.0 → 20.1.0

package/src/manager/run/persistence.ts

@@ -45,12 +45,26 @@ export class RunPersistence {
 
 		// Checkpoints go through the injectable seam; the disk layout under
 		// `outputDir` (same tree the runStore writes to) stays the default.
+		//
+		// The attribution is handed over because the layout does not record
+		// it — there is no tenant segment in the path at all — and without it
+		// the default store can persist checkpoints but cannot ENUMERATE
+		// them, which is the state the contract just stopped being in. A
+		// listing capability the default store declines is a capability no
+		// host reaches.
 		this.checkpointStore =
 			config.checkpointStore ??
-			new DiskCheckpointStore({
-				baseDir: config.outputDir,
-				logger: config.log,
-			})
+			new DiskCheckpointStore(
+				{
+					baseDir: config.outputDir,
+					logger: config.log,
+				},
+				{
+					tenantId: config.tenantId,
+					projectId: config.projectId,
+					sessionId: config.sessionId,
+				},
+			)
 
 		this.run = {
 			id: config.runId,
@@ -266,8 +280,36 @@ export class RunPersistence {
 		this.resultOverridden = true
 	}
 
+	/**
+	 * Record the schema-validated answer, and make `result` agree with it.
+	 *
+	 * `result` used to be left alone here, and the consequence was not "empty"
+	 * but "wrong": `resolveResult` walks back from the message tail and stops at
+	 * the first non-assistant message, so a structured run — whose last
+	 * assistant turn is a tool call, not prose — kept whatever text an EARLIER
+	 * turn happened to produce. A host reading `run.result` got a sentence from
+	 * the middle of the run presented as its answer.
+	 *
+	 * Three options, and the other two are worse:
+	 *
+	 *  - leave it: a stale value read as a fact, which is the defect;
+	 *  - clear it: a run that plainly answered reports no answer, so a host
+	 *    testing `if (run.result)` concludes nothing was produced;
+	 *  - serialize the structured value into it, which is what this does.
+	 *
+	 * The serialization is not an invention. Every text-shaped consumer — the
+	 * transcript, `Run.result`, both delegation tools handing a child's answer
+	 * back to a parent model — needs the answer as a string, and each of them
+	 * would otherwise serialize it again, differently. One serialization, at the
+	 * moment the value is known.
+	 *
+	 * Sticky, via `setResult`: `resolveResult` runs again when the run settles,
+	 * and without the override flag it would walk the tail and put the stale
+	 * prose back.
+	 */
 	setStructuredOutput(value: unknown): void {
 		this.run.structuredOutput = value
+		this.setResult(typeof value === 'string' ? value : JSON.stringify(value))
 	}
 
 	/**

package/src/public-runtime.ts

@@ -198,12 +198,25 @@ export {
 	DiskCheckpointStore,
 	DiskMemoryStore,
 	DiskTaskStore,
+	InMemoryCheckpointStore,
 	InMemoryMemoryIndex,
 	InMemoryMemoryStore,
 	InMemoryStore,
 	InMemoryTaskStore,
 	RunDiskStore,
 } from './store/index.js'
+export type { DiskCheckpointStoreAttribution } from './store/index.js'
+// Enumerating runs above a run id — the read an approval inbox and a park
+// sweep are built from, and the one the contract had no way to express.
+// `listDurableRuns` REFUSES on a store that cannot list rather than
+// reporting an empty page, because "nothing is waiting on a human" is not
+// what "I cannot tell" means.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './store/index.js'
 
 export {
 	AgentRegistry,

package/src/runtime/query/executor.ts

@@ -144,6 +144,20 @@ export interface ToolExecutorConfig {
 	repairToolCall?: RepairToolCall
 }
 
+/**
+ * What a `post_tool_use` hook decided to show the model instead.
+ *
+ * `isError` is the field this type exists for. The override used to be a bare
+ * string, so the executor had no way to tell "the call failed" from "the call
+ * succeeded and the model may not see all of it" — and it assumed the first,
+ * which turned every redaction into a reported tool failure.
+ */
+interface PostToolOverride {
+	readonly output: string
+	readonly isError: boolean
+	readonly content?: ToolResultContent
+}
+
 type PreToolHookOutcome =
 	| { kind: 'continue'; input: unknown }
 	| { kind: 'skip'; input: unknown; output: string }
@@ -708,10 +722,14 @@ export class ToolExecutor {
 
 		const postOverride = post.override
 		if (postOverride !== null) {
-			output = postOverride
+			output = postOverride.output
 		}
 
-		const effectiveIsError = !result.success || postOverride !== null
+		// A failed call, or an override that says the call failed. A `replace`
+		// says the opposite, and reading it as a failure is what made redaction
+		// unusable: the model was told a successful call had gone wrong, and
+		// routed around it.
+		const effectiveIsError = !result.success || (postOverride?.isError ?? false)
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
@@ -756,17 +774,31 @@ export class ToolExecutor {
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
 		})
 
+		const resolveContent = (): { content?: ToolResultContent } => {
+			if (postOverride?.content !== undefined) {
+				return { content: this.budgetContent(postOverride.content, toolName) }
+			}
+			if (postOverride?.isError) return {}
+			if (budgeted.truncated || result.content === undefined) return {}
+			return { content: this.budgetContent(result.content, toolName) }
+		}
+
 		return {
 			toolCallId: toolCall.id,
 			toolName,
 			output,
 			isError: effectiveIsError,
-			// A plugin override replaces what the model sees, and a spilled
-			// preview is no longer the tool's own payload — neither may carry
-			// rich content through.
-			...(result.content !== undefined && postOverride === null && !budgeted.truncated
-				? { content: this.budgetContent(result.content, toolName) }
-				: {}),
+			// Rich content follows the override's own decision.
+			//
+			// An ERROR override drops it: the payload is no longer the tool's,
+			// and shipping an image beside a failure message describes something
+			// the model was just told did not happen. A spilled preview drops it
+			// for the same reason.
+			//
+			// A REPLACE keeps it, because the common case is redacting text from
+			// a result whose image is unaffected — and a hook that needs it gone
+			// says so with `content`, which wins over both.
+			...resolveContent(),
 		}
 	}
 
@@ -919,6 +951,11 @@ export class ToolExecutor {
 						output: `Error: ${result.message}`,
 					}
 				case 'retry':
+				// There is no result to replace yet. Rejecting loudly beats
+				// silently ignoring it: a hook author who returned this here
+				// meant to redact something and would otherwise watch the secret
+				// go through.
+				case 'replace':
 					throw new Error(
 						`Plugin hook pre_tool_use returned unsupported action '${result.action}' for tool ${toolName}`,
 					)
@@ -1120,21 +1157,32 @@ export class ToolExecutor {
 		toolName: string,
 		input: unknown,
 		toolResult: ToolResult,
-	): Promise<{ override: string | null; retry: boolean }> {
+	): Promise<{ override: PostToolOverride | null; retry: boolean }> {
 		if (!this.config.pluginManager) return { override: null, retry: false }
 		const results = await this.config.pluginManager.executeHooks(
 			'post_tool_use',
 			{ runId: this.config.runId, toolName, toolInput: input, toolResult },
 			this.emitEvent,
 		)
-		let override: string | null = null
+		let override: PostToolOverride | null = null
 		let retry = false
 		for (const result of results) {
 			switch (result.action) {
 				case 'continue':
 					continue
 				case 'error':
-					override = `Error: ${result.message}`
+					override = { output: `Error: ${result.message}`, isError: true }
+					continue
+				// A redaction, not a failure. The call stood; the model is shown
+				// less of it. Rich content survives unless the hook replaced it —
+				// see the variant's own documentation for why that default, and
+				// for what a hook redacting a secret in an image has to do.
+				case 'replace':
+					override = {
+						output: result.output,
+						isError: false,
+						...(result.content !== undefined ? { content: result.content } : {}),
+					}
 					continue
 				// `retry` was a declared variant with no implementation: every
 				// site that consumed it threw. Here it finally means something

package/src/runtime/query/plugin-hooks.ts

@@ -26,6 +26,7 @@ export function applyLifecycleHookResults(
 			case 'skip':
 			case 'modify':
 			case 'retry':
+			case 'replace':
 				throw new Error(
 					`Plugin hook ${event} returned unsupported action '${result.action}' for a lifecycle event`,
 				)

package/src/store/index.ts

@@ -3,6 +3,24 @@ export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
 export { RunDiskStore } from './run/disk.js'
 export { DiskCheckpointStore } from './run/checkpoint-disk.js'
+export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js'
+export { InMemoryCheckpointStore } from './run/checkpoint-memory.js'
+// The refusing entry point to the optional listing capability, plus the two
+// projections a host implementing its own backend actually calls: one turns
+// a run's checkpoints into a row, the other applies the contract's filter,
+// ordering and cursor. Re-deriving either is how two stores start
+// disagreeing about what "outstanding" means or where a page ends.
+//
+// `summarizePark` and `DEFAULT_DURABLE_RUN_LIMIT` are deliberately NOT here.
+// The first is an internal of `toDurableRunEntry` and no caller wants half a
+// row; the second is a number a host reads by omitting `limit`. A name a
+// host has no use for is surface to keep correct forever for nobody.
+export {
+	assertContiguousListingScope,
+	listDurableRuns,
+	paginateDurableRuns,
+	toDurableRunEntry,
+} from './run/listing.js'
 
 export { ActivityStore } from './activity/memory.js'
 export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'

package/src/store/run/checkpoint-disk.ts

@@ -1,8 +1,40 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { NamzuError } from '../../types/errors/index.js'
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { RunId } from '../../types/ids/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
 import type { RunStoreConfig } from '../../types/run/index.js'
-import { RunDiskStore } from './disk.js'
+import type { ProjectId } from '../../types/session/ids.js'
+import { RunDiskStore, readCheckpointsIn } from './disk.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * The attribution a disk store's own layout does not record.
+ *
+ * The canonical layout is
+ * `{root}/projects/{projectId}/sessions/{sessionId}/runs/{runId}` — there is
+ * no tenant segment anywhere in it, and `baseDir` is already one session's
+ * `runs/` directory, so the project and session are implicit in a string the
+ * store cannot parse back out without knowing the layout that built it.
+ *
+ * A per-run read never needed any of it: the caller supplies a full
+ * `CheckpointRunScope` and the store only uses `runId`. A LISTING does — its
+ * rows have to be addressable, and a row with no tenant is a row nothing can
+ * be resumed from. So the store is told, once, what tree it is holding.
+ */
+export interface DiskCheckpointStoreAttribution {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly sessionId: SessionId
+}
 
 /**
  * Disk conformance layer for {@link CheckpointStore}: adapts the existing
@@ -20,10 +52,20 @@ import { RunDiskStore } from './disk.js'
  */
 export class DiskCheckpointStore implements CheckpointStore {
 	private readonly config: RunStoreConfig
+	private readonly attribution?: DiskCheckpointStoreAttribution
 	private readonly bound = new Map<RunId, Promise<RunDiskStore>>()
 
-	constructor(config: RunStoreConfig) {
+	/**
+	 * @param config the run-store config; `baseDir` is one session's `runs/`
+	 *   directory.
+	 * @param attribution what tree this is, for
+	 *   {@link DiskCheckpointStore.listDurableRuns}. Optional so that adding
+	 *   the listing did not change an existing construction; a store built
+	 *   without it refuses to list rather than inventing a tenant.
+	 */
+	constructor(config: RunStoreConfig, attribution?: DiskCheckpointStoreAttribution) {
 		this.config = config
+		this.attribution = attribution
 	}
 
 	private bind(scope: CheckpointRunScope): Promise<RunDiskStore> {
@@ -64,4 +106,86 @@ export class DiskCheckpointStore implements CheckpointStore {
 		const store = await this.bind(scope)
 		await store.deleteCheckpoint(checkpointId)
 	}
+
+	/**
+	 * Every run with checkpoints under this store's tree.
+	 *
+	 * Reads the directories rather than binding a {@link RunDiskStore} per
+	 * run, because binding CREATES the run directory — a listing that
+	 * materialized a directory for every run it looked at would grow the tree
+	 * it is reporting on.
+	 *
+	 * ### Why a two-level walk reaches every depth
+	 *
+	 * `initRun` nests exactly one level: a run with a parent goes to
+	 * `{baseDir}/{parentRunId}/children/{runId}`, and a grandchild goes to
+	 * `{baseDir}/{itsOwnParentRunId}/children/{runId}` — beside the top-level
+	 * runs, not beneath its grandparent. So the tree is flat-with-one-nesting
+	 * at every depth, `{baseDir}/*` plus `{baseDir}/* /children/*` enumerates
+	 * all of it, and each run's `parentRunId` is the directory it sits under.
+	 * A deep run leaves a bare shell directory under its own id at the top
+	 * level (`{baseDir}/{parentRunId}` created by `mkdir -p` for a child of a
+	 * run whose own data lives elsewhere); those hold no `checkpoints/` and
+	 * drop out as entries with no durable state.
+	 */
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'DiskCheckpointStore.listDurableRuns')
+
+		const attribution = this.attribution
+		if (!attribution) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message:
+					'DiskCheckpointStore.listDurableRuns: this store was constructed without attribution, so it cannot say which tenant, project or session its runs belong to — and a listing row that carries no scope is a row nothing can be resumed or swept from. Pass the second constructor argument. Refusing rather than returning rows stamped with a guessed tenant.',
+				details: { baseDir: this.config.baseDir },
+			})
+		}
+
+		// A listing is scoped, not addressed: a query for another tenant is a
+		// question this tree has no rows for, not an isolation violation. Same
+		// reasoning `SessionStore.listSessions` already states for sessions
+		// that happen to share a thread id across tenants.
+		if (
+			scope.tenantId !== attribution.tenantId ||
+			(scope.projectId !== undefined && scope.projectId !== attribution.projectId) ||
+			(scope.sessionId !== undefined && scope.sessionId !== attribution.sessionId)
+		) {
+			return { entries: [] }
+		}
+
+		const now = options?.now ?? Date.now()
+		const entries: DurableRunEntry[] = []
+
+		for (const runId of await this.readRunDirs(this.config.baseDir)) {
+			const runDir = join(this.config.baseDir, runId)
+
+			const own = toDurableRunEntry({ ...attribution, runId }, await readCheckpointsIn(runDir), now)
+			if (own) entries.push(own)
+
+			for (const childId of await this.readRunDirs(join(runDir, 'children'))) {
+				const child = toDurableRunEntry(
+					{ ...attribution, runId: childId, parentRunId: runId },
+					await readCheckpointsIn(join(runDir, 'children', childId)),
+					now,
+				)
+				if (child) entries.push(child)
+			}
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+
+	/** Directory names under `dir`, or none when `dir` does not exist. */
+	private async readRunDirs(dir: string): Promise<RunId[]> {
+		try {
+			const found = await readdir(dir, { withFileTypes: true })
+			return found.filter((e) => e.isDirectory()).map((e) => e.name as RunId)
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw err
+		}
+	}
 }

package/src/store/run/checkpoint-memory.ts

@@ -0,0 +1,101 @@
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type {
+	CheckpointListingScope,
+	CheckpointRunScope,
+	CheckpointStore,
+	DurableRunEntry,
+	DurableRunPage,
+	ListDurableRunsOptions,
+} from '../../types/run/checkpoint-store.js'
+import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js'
+
+/**
+ * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
+ *
+ * Shipped rather than left as a test fixture for two reasons. It is the
+ * reference a host reads when writing a backend of its own — the disk store
+ * is path-addressed and answers "what does an attribution-keyed store look
+ * like" with a directory layout, which is the wrong lesson. And it is the
+ * only implementation that can hold more than one tenant at once, because
+ * the disk layout has no tenant in it: a test that two tenants' listings
+ * stay separate is not expressible against disk, and a rule that cannot be
+ * tested on the store a host will actually inject is a rule on paper.
+ *
+ * Not durable, deliberately: it is for tests, for a single-process host that
+ * genuinely wants checkpoints to die with the process, and as the parity
+ * partner that proves the listing contract is not a filesystem in disguise.
+ */
+export class InMemoryCheckpointStore implements CheckpointStore {
+	/** `tenant/project/session/run` → checkpoint id → checkpoint. */
+	private readonly runs = new Map<string, Map<CheckpointId, IterationCheckpoint>>()
+	/** Same key → the run's scope, so a listing can rebuild an addressable entry. */
+	private readonly scopes = new Map<string, CheckpointRunScope>()
+
+	private key(scope: CheckpointRunScope): string {
+		return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/')
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		const key = this.key(scope)
+		let run = this.runs.get(key)
+		if (!run) {
+			run = new Map()
+			this.runs.set(key, run)
+		}
+		// The run's scope is kept beside its checkpoints because the key is a
+		// joined string and a listing has to hand back the parts — above all
+		// `parentRunId`, which is what makes a sub-run's row addressable.
+		//
+		// Written on every call rather than only the first, and that is
+		// simplicity, not defence: a run's scope is fixed when the run is
+		// constructed, so the two cannot differ, and a `has` guard here would
+		// be a branch no input can take.
+		this.scopes.set(key, {
+			tenantId: scope.tenantId,
+			projectId: scope.projectId,
+			sessionId: scope.sessionId,
+			runId: scope.runId,
+			...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+		})
+		run.set(checkpoint.id, checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		checkpointId: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		return this.runs.get(this.key(scope))?.get(checkpointId) ?? null
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const run = this.runs.get(this.key(scope))
+		if (!run) return []
+		return [...run.values()].sort((a, b) => a.createdAt - b.createdAt)
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
+		this.runs.get(this.key(scope))?.delete(checkpointId)
+	}
+
+	async listDurableRuns(
+		scope: CheckpointListingScope,
+		options?: ListDurableRunsOptions,
+	): Promise<DurableRunPage> {
+		assertContiguousListingScope(scope, 'InMemoryCheckpointStore.listDurableRuns')
+		const now = options?.now ?? Date.now()
+
+		const entries: DurableRunEntry[] = []
+		for (const [key, checkpoints] of this.runs) {
+			const runScope = this.scopes.get(key)
+			if (!runScope) continue
+			if (runScope.tenantId !== scope.tenantId) continue
+			if (scope.projectId !== undefined && runScope.projectId !== scope.projectId) continue
+			if (scope.sessionId !== undefined && runScope.sessionId !== scope.sessionId) continue
+
+			const entry = toDurableRunEntry(runScope, [...checkpoints.values()], now)
+			if (entry) entries.push(entry)
+		}
+
+		return paginateDurableRuns(entries, options)
+	}
+}

package/src/store/run/disk.ts

@@ -136,6 +136,12 @@ export class RunDiskStore {
 			messageCount: run.messages.length,
 		}
 
+		// The schema-validated answer belongs in the durable record for the same
+		// reason `result` does: a run reloaded by id that has lost its answer has
+		// lost the thing it was run for. Written only when present, so a run that
+		// asked for no schema carries no key rather than an explicit `undefined`.
+		if (run.structuredOutput !== undefined) meta.structuredOutput = run.structuredOutput
+
 		if (run.parentRunId) meta.parentRunId = run.parentRunId
 		if (run.depth !== undefined && run.depth > 0) meta.depth = run.depth
 
@@ -186,33 +192,7 @@ export class RunDiskStore {
 	}
 
 	async listCheckpoints(): Promise<IterationCheckpoint[]> {
-		const dir = this.requireInit()
-		const cpDir = join(dir, 'checkpoints')
-		try {
-			const files = await readdir(cpDir)
-			const checkpoints: IterationCheckpoint[] = []
-			for (const file of files) {
-				if (!file.endsWith('.json')) continue
-				// An unreadable checkpoint used to be logged and skipped, so
-				// this returned a silently short list that four callers treat
-				// as complete. A missing NEWEST checkpoint quietly resumes
-				// from an older point and re-runs a whole iteration of tool
-				// calls; a missing PARKED one reports "not parked" and drops
-				// an approval a human already granted, because the file is
-				// the only durable record of a park. Pruning under-deletes
-				// too: a file the keep-count cannot see is immortal.
-				//
-				// The by-id read next door was already strict. Two read paths
-				// disagreeing about whether damage matters is how the lenient
-				// one gets trusted.
-				const content = await readFile(join(cpDir, file), 'utf-8')
-				checkpoints.push(parseCheckpoint(content, file))
-			}
-			return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
-		} catch (err) {
-			if (isFileNotFound(err)) return []
-			throw err
-		}
+		return readCheckpointsIn(this.requireInit())
 	}
 
 	async deleteCheckpoint(checkpointId: CheckpointId): Promise<void> {
@@ -224,6 +204,29 @@ export class RunDiskStore {
 		}
 	}
 
+	/**
+	 * @deprecated Superseded by
+	 *   {@link import('../../types/run/checkpoint-store.js').CheckpointStore.listDurableRuns},
+	 *   reached through {@link import('./listing.js').listDurableRuns}.
+	 *   Removed in the next major.
+	 *
+	 *   Three things are wrong with `index.json` as the answer to "which runs
+	 *   are there":
+	 *
+	 *   1. Its entries carry no tenant, project or session, so a row cannot be
+	 *      turned back into an addressable scope — nothing can be resumed or
+	 *      swept from it.
+	 *   2. `addToIndex` skips every sub-run, so an inbox built on it drops
+	 *      every approval raised by delegated work, and the symptom looks like
+	 *      a hung specialist rather than a blind listing.
+	 *   3. It is a catalogue of runs that STARTED, not of runs with durable
+	 *      state, so it cannot tell a run something could resume from one that
+	 *      left nothing behind.
+	 *
+	 *   Deprecated for one minor rather than deleted outright: this is public
+	 *   surface and a consumer calling it today gets real data back, so the
+	 *   deprecate-before-you-remove rule applies.
+	 */
 	static async listRuns(baseDir: string): Promise<
 		Array<{
 			id: string
@@ -291,6 +294,54 @@ export class RunDiskStore {
 	}
 }
 
+/**
+ * Every checkpoint stored under one run directory, ascending by `createdAt`.
+ *
+ * A free function rather than a method because the scope-level listing walks
+ * run directories it has never bound a {@link RunDiskStore} to — and binding
+ * one would CREATE the directory, which is not something a read should do.
+ * Sharing the function is what keeps the two read paths from disagreeing
+ * about what a damaged file means.
+ *
+ * An unreadable checkpoint used to be logged and skipped, so this returned a
+ * silently short list that four callers treat as complete. A missing NEWEST
+ * checkpoint quietly resumes from an older point and re-runs a whole
+ * iteration of tool calls; a missing PARKED one reports "not parked" and
+ * drops an approval a human already granted, because the file is the only
+ * durable record of a park. Pruning under-deletes too: a file the keep-count
+ * cannot see is immortal. The by-id read next door was already strict, and
+ * two read paths disagreeing about whether damage matters is how the lenient
+ * one gets trusted.
+ *
+ * The same reasoning carries up to the listing, which is why the throw
+ * propagates there rather than dropping the run: a damaged checkpoint that
+ * removed a run from an approval inbox is the missing-park failure again,
+ * one level up.
+ *
+ * A missing `checkpoints/` directory is the only absence that reads as
+ * empty — the run genuinely has none. A file that disappears BETWEEN the
+ * directory listing and its read throws, where the old shape returned the
+ * empty array and discarded every checkpoint it had already parsed.
+ */
+export async function readCheckpointsIn(runDir: string): Promise<IterationCheckpoint[]> {
+	const cpDir = join(runDir, 'checkpoints')
+	let files: string[]
+	try {
+		files = await readdir(cpDir)
+	} catch (err) {
+		if (isFileNotFound(err)) return []
+		throw err
+	}
+
+	const checkpoints: IterationCheckpoint[] = []
+	for (const file of files) {
+		if (!file.endsWith('.json')) continue
+		const content = await readFile(join(cpDir, file), 'utf-8')
+		checkpoints.push(parseCheckpoint(content, file))
+	}
+	return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
+}
+
 async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
 	await atomicWriteFile(filePath, JSON.stringify(stamp(SCHEMA, value), null, 2))
 }