@namzu/sdk 59.0.0 → 60.1.0

package/src/contracts/session/api.ts

@@ -91,6 +91,12 @@ export type SessionStreamEventType =
 	 * a provider it did not ask for, at a different price.
 	 */
 	| 'provider.fallback'
+	/**
+	 * The model declined to answer, and what the turn did about it: moved to
+	 * another model, retried once, or gave up. Without it a client cannot tell
+	 * a declined request from an empty answer.
+	 */
+	| 'model.refusal'
 	| 'tool.executing'
 	/** Ephemeral progress from a long-running tool. Not in the transcript. */
 	| 'tool.progress'

package/src/execution/workflow/index.ts

@@ -1,8 +1,21 @@
 export { WorkflowScriptError } from './errors.js'
 export { FileWorkflowJournal } from './journal.js'
 export { parseWorkflowMeta } from './meta.js'
+export {
+	formatWorkflowJournalLine,
+	loadWorkflowResume,
+	readWorkflowJournalChecked,
+	workflowCallKey,
+	workflowJournalLineHash,
+	workflowJournalSeed,
+} from './resume.js'
+export type { WorkflowCallIdentity } from './resume.js'
 export { summarizeWorkflowPhases } from './phases.js'
 export type { PhaseAgentView, PhaseRecord } from './phases.js'
-export { resolveWorkflowLimits, WORKFLOW_HOST_CALL, WorkflowRuntime } from './runtime.js'
+export {
+	resolveWorkflowLimits,
+	WORKFLOW_HOST_CALL,
+	WorkflowRuntime,
+} from './runtime.js'
 export type { WorkflowRuntimeOptions } from './runtime.js'
 export type * from './types.js'

package/src/execution/workflow/journal.ts

@@ -1,8 +1,19 @@
 import { createHash } from 'node:crypto'
-import { appendFile, mkdir, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { mkdir, open, readFile, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
 
-import type { WorkflowJournal, WorkflowJournalRecord } from './types.js'
+import {
+	formatWorkflowJournalLine,
+	readWorkflowJournalChecked,
+	workflowJournalLineHash,
+	workflowJournalSeed,
+} from './resume.js'
+import type {
+	CheckedWorkflowJournal,
+	WorkflowJournal,
+	WorkflowJournalReader,
+	WorkflowJournalRecord,
+} from './types.js'
 
 export function sha256(text: string): string {
 	return createHash('sha256').update(text).digest('hex')
@@ -17,30 +28,169 @@ export function preview(text: string, max = 500): string {
 	return `${text.slice(0, end)}…`
 }
 
+/** The chain state of one journal file, shared by every writer in this process. */
+interface ChainState {
+	queue: Promise<void>
+	loaded: boolean
+	seq: number
+	prev: string
+	needsNewline: boolean
+	finished: boolean
+	/** Bytes the file had after the last write this process made; a different size means someone else wrote. */
+	size: number
+	/** Appends queued or running; the state is dropped once a pass's end is written and none are left. */
+	pending: number
+}
+
+const chains = new Map<string, ChainState>()
+
+/** Records after which a crash must not lose the line: a saved result, the end of a pass, the start of one. */
+function mustSurviveCrash(record: WorkflowJournalRecord): boolean {
+	return (
+		record.type === 'run_finished' ||
+		record.type === 'run_started' ||
+		(record.type === 'agent_outcome' && Object.hasOwn(record, 'result'))
+	)
+}
+
 /**
  * A journal in a directory: `script.js` (the exact script text, mode 0600)
  * and `journal.jsonl` (one JSON record per line, append-only). The caller
  * chooses the directory, normally `<session>/runs/<runId>/workflow/`.
+ *
+ * Every line carries `seq` and `prev` (the hash of the line before it, the
+ * first chaining from a seed bound to the run id), so a line that was edited,
+ * removed or cut short is found when the journal is read back. One writer per
+ * file serves the whole process: a resumed pass and a late agent of the pass
+ * before it append through the same queue and the same chain, and nothing is
+ * appended after a pass's `run_finished` until the next pass starts. This
+ * assumes one process writes the file at a time, which the session lease
+ * already guarantees. A chain proves the file was not damaged or edited by
+ * accident; someone who can rewrite the whole file can rewrite the chain too.
  */
-export class FileWorkflowJournal implements WorkflowJournal {
+export class FileWorkflowJournal implements WorkflowJournal, WorkflowJournalReader {
 	private ready: Promise<void> | undefined
+	private readonly file: string
 
-	constructor(private readonly dir: string) {}
+	constructor(
+		private readonly dir: string,
+		private readonly options: {
+			readonly runId?: string
+			/** A secret that signs every line; see `readWorkflowJournalChecked`. */
+			readonly key?: string | Uint8Array
+		} = {},
+	) {
+		this.file = resolve(dir, 'journal.jsonl')
+	}
 
 	private ensure(): Promise<void> {
 		this.ready ??= mkdir(this.dir, { recursive: true, mode: 0o700 }).then(() => undefined)
 		return this.ready
 	}
 
-	async writeScript(source: string): Promise<void> {
-		await this.ensure()
-		await writeFile(join(this.dir, 'script.js'), source, { mode: 0o600 })
+	/** The run id of the file's first line, learned from the file or from the first `run_started` written. */
+	private learned: string | undefined
+
+	private runId(record?: WorkflowJournalRecord, text?: string): string {
+		if (this.options.runId !== undefined) return this.options.runId
+		if (record?.type === 'run_started') this.learned = record.runId
+		if (this.learned !== undefined) return this.learned
+		const first = text?.slice(0, text.indexOf('\n') < 0 ? undefined : text.indexOf('\n'))
+		if (first) {
+			try {
+				const parsed = JSON.parse(first) as { type?: unknown; runId?: unknown }
+				if (parsed.type === 'run_started' && typeof parsed.runId === 'string') {
+					this.learned = parsed.runId
+					return parsed.runId
+				}
+			} catch {
+				// Not a record: fall back to the folder name below.
+			}
+		}
+		return basename(dirname(resolve(this.dir)))
 	}
 
-	async append(record: WorkflowJournalRecord): Promise<void> {
+	async writeScript(source: string, _sha256?: string, pass = 1): Promise<void> {
 		await this.ensure()
-		await appendFile(join(this.dir, 'journal.jsonl'), `${JSON.stringify(record)}\n`, {
-			mode: 0o600,
+		const name = pass <= 1 ? 'script.js' : `script.${pass}.js`
+		await writeFile(join(this.dir, name), source, { mode: 0o600 })
+	}
+
+	async read(): Promise<CheckedWorkflowJournal> {
+		let text: string
+		try {
+			text = await readFile(this.file, 'utf8')
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+			text = ''
+		}
+		return readWorkflowJournalChecked(text, this.runId(undefined, text), {
+			...(this.options.key !== undefined ? { key: this.options.key } : {}),
+		})
+	}
+
+	append(record: WorkflowJournalRecord): Promise<void> {
+		let state = chains.get(this.file)
+		if (state === undefined) {
+			state = {
+				queue: Promise.resolve(),
+				loaded: false,
+				seq: 0,
+				prev: '',
+				needsNewline: false,
+				finished: false,
+				size: 0,
+				pending: 0,
+			}
+			chains.set(this.file, state)
+		}
+		const chain = state
+		chain.pending++
+		const run = chain.queue.then(async () => {
+			await this.ensure()
+			const onDisk = await stat(this.file).then(
+				(info) => info.size,
+				() => 0,
+			)
+			if (!chain.loaded || onDisk !== chain.size) {
+				const checked = await this.read()
+				chain.seq = checked.lastSeq
+				chain.prev = checked.lastHash
+				chain.needsNewline = !checked.endsWithNewline
+				chain.finished = checked.records.at(-1)?.type === 'run_finished'
+				chain.loaded = true
+				chain.size = onDisk
+			}
+			if (record.type === 'run_started') chain.finished = false
+			// Nothing belongs after the pass's end; a late agent of that pass is dropped here.
+			else if (chain.finished) return
+			if (chain.seq === 0) chain.prev = workflowJournalSeed(this.runId(record))
+			const seq = chain.seq + 1
+			const line = formatWorkflowJournalLine(record, seq, chain.prev, this.options.key)
+			const handle = await open(this.file, 'a', 0o600)
+			try {
+				const text = `${chain.needsNewline ? '\n' : ''}${line}\n`
+				await handle.appendFile(text)
+				chain.size += Buffer.byteLength(text)
+				if (mustSurviveCrash(record)) await handle.datasync()
+			} finally {
+				await handle.close()
+			}
+			chain.needsNewline = false
+			chain.seq = seq
+			chain.prev = workflowJournalLineHash(line)
+			if (record.type === 'run_finished') chain.finished = true
 		})
+		chain.queue = run
+			.catch(() => undefined)
+			.then(() => {
+				chain.pending--
+				// A finished run keeps no state: the next append reads the file again, and
+				// what it finds (a last `run_finished`) is the same thing the state held.
+				if (chain.pending === 0 && chain.finished && chains.get(this.file) === chain) {
+					chains.delete(this.file)
+				}
+			})
+		return run
 	}
 }

package/src/execution/workflow/prelude.ts

@@ -28,7 +28,7 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 	}
 	function phase(title) {
 		var t = clean(title, 120);
-		if (!t) throw new TypeError('phase() needs a non-empty title.');
+		if (!t) throw misuse('phase() needs a non-empty title.');
 		cursor = t;
 		emit({ k: 'phase', title: t });
 	}
@@ -53,13 +53,26 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 		return e;
 	}
 	function isBudgetError(e) { return !!e && e.name === 'WorkflowBudgetExceededError'; }
+	function misuse(message) {
+		var e = new TypeError(message);
+		e.workflowMisuse = true;
+		return e;
+	}
+	function isMisuse(e) { return !!e && e.workflowMisuse === true; }
+	var optionNames = ['label', 'phase', 'schema', 'agentType', 'model', 'effort'];
 	async function agent(prompt, opts) {
 		if (typeof prompt !== 'string' || prompt.length === 0) {
-			throw new TypeError('agent(prompt, options?): the prompt must be a non-empty string, got ' + kind(prompt));
+			throw misuse('agent(prompt, options?): the prompt must be a non-empty string, got ' + kind(prompt));
 		}
 		var o = opts == null ? {} : opts;
 		if (typeof o !== 'object' || Array.isArray(o)) {
-			throw new TypeError('agent(prompt, options?): options must be an object, got ' + kind(o));
+			throw misuse('agent(prompt, options?): options must be an object, got ' + kind(o));
+		}
+		var unknown = Object.keys(o).filter(function (k) { return optionNames.indexOf(k) < 0; });
+		if (unknown.length > 0) {
+			// Ignored, as it always was, but no longer silently: a saved script that
+			// misspells an option keeps running and the line says why it had no effect.
+			log('agent(prompt, options?): ignoring unknown option "' + unknown[0] + '"; the options are ' + optionNames.join(', ') + '.');
 		}
 		if (overBudget()) throw budgetError();
 		var request = { prompt: prompt, cursor: cursor };
@@ -69,23 +82,32 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 		if (o.agentType != null) request.agentType = clean(o.agentType, 120);
 		if (o.model != null) request.model = clean(o.model, 120);
 		if (o.effort != null) request.effort = clean(o.effort, 32);
-		var reply = await rawCall('agent', request);
+		var reply;
+		try {
+			reply = await rawCall('agent', request);
+		} catch (e) {
+			// The host rejects a malformed request with an "agent(): ..." message;
+			// that is the script's mistake, not a failed child.
+			if (e && typeof e.message === 'string' && e.message.indexOf('agent(): ') === 0) throw misuse(e.message);
+			throw e;
+		}
 		spent.tokensUsed = reply.t;
 		return reply.v;
 	}
 	async function parallel(thunks) {
 		if (!Array.isArray(thunks)) {
-			throw new TypeError('parallel(thunks): the argument must be an array of functions, got ' + kind(thunks));
+			throw misuse('parallel(thunks): the argument must be an array of functions, got ' + kind(thunks));
 		}
 		for (var p = 0; p < thunks.length; p++) {
 			if (typeof thunks[p] !== 'function') {
-				throw new TypeError('parallel(thunks): item ' + (p + 1) + ' must be a function (wrap the work as () => agent(...)), got ' + kind(thunks[p]));
+				throw misuse('parallel(thunks): item ' + (p + 1) + ' must be a function (wrap the work as () => agent(...)), got ' + kind(thunks[p]));
 			}
 		}
 		var dropped = 0;
 		var results = await Promise.all(thunks.map(function (t, n) {
 			return Promise.resolve().then(t).catch(function (e) {
 				if (isBudgetError(e)) { dropped++; return null; }
+				if (isMisuse(e)) throw e;
 				log('Step ' + (n + 1) + ' stopped: ' + clean(e && e.message ? e.message : e, 300));
 				return null;
 			});
@@ -95,12 +117,12 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 	}
 	async function pipeline(items) {
 		if (!Array.isArray(items)) {
-			throw new TypeError('pipeline(items, ...stages): the first argument must be an array, got ' + kind(items));
+			throw misuse('pipeline(items, ...stages): the first argument must be an array, got ' + kind(items));
 		}
 		var stages = Array.prototype.slice.call(arguments, 1);
 		for (var s = 0; s < stages.length; s++) {
 			if (typeof stages[s] !== 'function') {
-				throw new TypeError('pipeline(items, ...stages): stage ' + (s + 1) + ' must be a function, got ' + kind(stages[s]));
+				throw misuse('pipeline(items, ...stages): stage ' + (s + 1) + ' must be a function, got ' + kind(stages[s]));
 			}
 		}
 		if (items.length > 0 && overBudget()) throw budgetError();
@@ -112,6 +134,7 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 					value = await stages[i](value, item, index);
 				} catch (e) {
 					if (isBudgetError(e)) { dropped++; return null; }
+					if (isMisuse(e)) throw e;
 					log('Item ' + (index + 1) + ' stopped at step ' + (i + 1) + ': ' + clean(e && e.message ? e.message : e, 300));
 					return null;
 				}
@@ -141,6 +164,24 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 	install('log', log);
 	install('budget', budget);
 	install('args', config.args);
+	if (config.deterministic) {
+		var RealDate = Date;
+		var clockMessage = 'Date.now() / new Date() are unavailable in workflow scripts (breaks resume). Stamp results after the workflow returns, or pass timestamps through args.';
+		var randomMessage = 'Math.random() is unavailable in workflow scripts (breaks resume). For N independent samples, include the index in the agent label or prompt.';
+		var ShimDate = function Date(a, b, c, d, e, f, g) {
+			if (!new.target || arguments.length === 0) throw new Error(clockMessage);
+			return Reflect.construct(RealDate, Array.prototype.slice.call(arguments), new.target === ShimDate ? RealDate : new.target);
+		};
+		Object.defineProperty(ShimDate, 'prototype', { value: RealDate.prototype, writable: false, configurable: false });
+		Object.defineProperty(ShimDate, 'now', { value: function now() { throw new Error(clockMessage); }, writable: false, configurable: false });
+		Object.defineProperty(ShimDate, 'parse', { value: RealDate.parse, writable: false, configurable: false });
+		Object.defineProperty(ShimDate, 'UTC', { value: RealDate.UTC, writable: false, configurable: false });
+		Object.defineProperty(RealDate.prototype, 'constructor', { value: ShimDate, writable: false, configurable: false });
+		Object.defineProperty(globalThis, 'Date', { value: ShimDate, writable: false, configurable: false, enumerable: false });
+		Object.defineProperty(Math, 'random', { value: function random() { throw new Error(randomMessage); }, writable: false, configurable: false });
+		try { delete globalThis.eval; } catch (ignored) {}
+		Object.freeze(RealDate);
+	}
 })`
 
 /**
@@ -151,6 +192,7 @@ const PRELUDE_SOURCE = String.raw`(function (config) {
 export function preludeLineCount(config: {
 	args: unknown
 	tokenLimit: number | null
+	deterministic?: boolean
 }): number {
 	return buildPrelude(config).split('\n').length
 }
@@ -159,6 +201,7 @@ export function preludeLineCount(config: {
 export function buildPrelude(config: {
 	args: unknown
 	tokenLimit: number | null
+	deterministic?: boolean
 }): string {
 	const literal = JSON.stringify(config)
 		.split(String.fromCharCode(0x2028))

package/src/execution/workflow/resume.ts

@@ -0,0 +1,313 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+
+import type {
+	ChainedWorkflowJournalRecord,
+	CheckedWorkflowJournal,
+	WorkflowFinishStatus,
+	WorkflowJournalRecord,
+	WorkflowResumeState,
+} from './types.js'
+
+/** The key version. A change to how keys are made bumps it, so old keys simply never match. */
+const KEY_VERSION = 'k1'
+
+function sha256Hex(text: string): string {
+	return createHash('sha256').update(text).digest('hex')
+}
+
+/** JSON with every object's keys sorted and `__proto__` dropped, so equal values give equal text. */
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(',')}]`
+	if (typeof value === 'object' && value !== null) {
+		const record = value as Record<string, unknown>
+		const keys = Object.keys(record)
+			.filter((key) => key !== '__proto__' && record[key] !== undefined)
+			.sort()
+		return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`
+	}
+	return JSON.stringify(value) ?? 'null'
+}
+
+/** What of an `agent()` call decides its result. `label`, `phase` and progress callbacks do not. */
+export interface WorkflowCallIdentity {
+	readonly schema?: unknown
+	readonly model?: string
+	readonly effort?: string
+	readonly agentType?: string
+}
+
+/**
+ * The key a call is saved and looked up under: the prompt, the options that
+ * change what the agent does (schema, model, effort, agent type) and how many
+ * identical calls came before it in the same pass. Each part is length-prefixed
+ * so one cannot be read as part of another.
+ */
+export function workflowCallKey(
+	prompt: string,
+	call: WorkflowCallIdentity,
+	ordinal: number,
+): string {
+	return `${KEY_VERSION}:${sha256Hex(`${workflowCallContent(prompt, call)}${ordinal}`)}`
+}
+
+/**
+ * What makes two calls the same call: the prompt and the options that change
+ * the agent, in a form where key order and `undefined` do not matter. The
+ * runtime counts repeats of this text to give identical calls distinct slots,
+ * and the key hashes the same text, so the two can never disagree.
+ */
+export function workflowCallContent(prompt: string, call: WorkflowCallIdentity): string {
+	const options = canonicalJson({
+		schema: call.schema,
+		model: call.model,
+		effort: call.effort,
+		agentType: call.agentType,
+	})
+	return `${prompt.length}:${prompt}${options.length}:${options}`
+}
+
+/** The hash the first line of a run's journal chains from. It binds the file to its run id. */
+export function workflowJournalSeed(runId: string): string {
+	return sha256Hex(`namzu-workflow-journal\0${runId}`)
+}
+
+/** The hash a line contributes to the next one: its exact bytes, newline included. */
+export function workflowJournalLineHash(line: string): string {
+	return sha256Hex(`${line}\n`)
+}
+
+/** The line `record` is written as. With a key, a `mac` over the rest of the line is added last. */
+export function formatWorkflowJournalLine(
+	record: WorkflowJournalRecord,
+	seq: number,
+	prev: string,
+	key?: string | Uint8Array,
+): string {
+	const body = { seq, prev, ...record }
+	if (key === undefined) return JSON.stringify(body)
+	const mac = createHmac('sha256', key).update(JSON.stringify(body)).digest('hex')
+	return JSON.stringify({ ...body, mac })
+}
+
+function macMatches(record: Record<string, unknown>, key: string | Uint8Array): boolean {
+	const { mac, ...rest } = record
+	if (typeof mac !== 'string') return false
+	const expected = createHmac('sha256', key).update(JSON.stringify(rest)).digest()
+	const actual = Buffer.from(mac, 'hex')
+	return actual.length === expected.length && timingSafeEqual(actual, expected)
+}
+
+function parseLine(line: string): Record<string, unknown> | undefined {
+	try {
+		const value: unknown = JSON.parse(line)
+		return typeof value === 'object' && value !== null && !Array.isArray(value)
+			? (value as Record<string, unknown>)
+			: undefined
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Reads a journal's text and keeps only the records that can be trusted.
+ *
+ * Every line carries `seq` (counting trusted lines from 1) and `prev` (the hash
+ * of the line before; the first chains from a seed bound to the run id). A
+ * line that does not chain, a line that does not parse, and anything after
+ * one is dropped until a `run_started` of a resumed pass picks the chain up
+ * again at the last trusted line. A last line without its newline that is not
+ * whole JSON is a torn write and is ignored; one that is whole JSON is read
+ * like any other line. The file is never rewritten.
+ *
+ * The chain alone cannot notice an edit to the final line (nothing chains from
+ * it yet). With `key`, every line must also carry a `mac` made with that
+ * secret, which closes that gap against anyone who does not hold the key.
+ */
+export function readWorkflowJournalChecked(
+	text: string,
+	runId: string,
+	options: { readonly key?: string | Uint8Array } = {},
+): CheckedWorkflowJournal {
+	const endsWithNewline = text === '' || text.endsWith('\n')
+	const pieces = text.split('\n')
+	const fragment = endsWithNewline ? undefined : pieces.pop()
+	if (endsWithNewline) pieces.pop()
+	// A last line without its newline that is whole JSON was only missing the newline: it is
+	// judged like any other line (the writer adds the newline before the next record, so the
+	// hash it contributes is the one of the line with its newline). Anything else is a torn write.
+	const wholeFragment =
+		fragment !== undefined && fragment !== '' && parseLine(fragment) !== undefined
+	if (wholeFragment) pieces.push(fragment as string)
+	const tornTail = fragment !== undefined && fragment !== '' && !wholeFragment
+
+	const parsed = pieces.map((line) => parseLine(line))
+	const firstRecord = parsed.find((record) => record !== undefined)
+	if (firstRecord !== undefined && typeof firstRecord.seq !== 'number') {
+		return {
+			records: [],
+			legacy: true,
+			tornTail,
+			lastSeq: 0,
+			lastHash: workflowJournalSeed(runId),
+			endsWithNewline,
+			untrusted: parsed.filter((record) => record !== undefined) as WorkflowJournalRecord[],
+		}
+	}
+
+	const records: ChainedWorkflowJournalRecord[] = []
+	let lastSeq = 0
+	let lastHash = workflowJournalSeed(runId)
+	let gapStart: number | undefined
+	let gapLines = 0
+	let gapParsed = false
+	let brokenAt: number | undefined
+	const closeGap = (): void => {
+		if (gapStart !== undefined && (gapLines > 1 || gapParsed)) brokenAt ??= gapStart
+		gapStart = undefined
+		gapLines = 0
+		gapParsed = false
+	}
+
+	for (let i = 0; i < pieces.length; i++) {
+		const line = pieces[i] as string
+		const record = parsed[i]
+		const chains =
+			record !== undefined &&
+			record.seq === lastSeq + 1 &&
+			record.prev === lastHash &&
+			(options.key === undefined || macMatches(record, options.key))
+		const first = records.length === 0
+		const acceptable =
+			chains &&
+			(first
+				? record.type === 'run_started' && record.runId === runId
+				: gapStart === undefined || record.type === 'run_started')
+		if (acceptable) {
+			closeGap()
+			records.push(record as unknown as ChainedWorkflowJournalRecord)
+			lastSeq = record.seq as number
+			lastHash = workflowJournalLineHash(line)
+			continue
+		}
+		if (gapStart === undefined) gapStart = i + 1
+		gapLines++
+		if (record !== undefined) gapParsed = true
+	}
+	// A gap that runs to the end is a change, except a single line that does not parse
+	// (what a torn write leaves once the next pass closed it with a newline).
+	closeGap()
+
+	return {
+		records,
+		legacy: false,
+		tornTail,
+		...(brokenAt !== undefined ? { brokenAt } : {}),
+		lastSeq,
+		lastHash,
+		endsWithNewline,
+		untrusted: [],
+	}
+}
+
+function hasResult(record: { readonly result?: unknown }): boolean {
+	return Object.hasOwn(record, 'result') && record.result !== undefined && record.result !== null
+}
+
+/**
+ * Folds a checked journal into what a resumed pass needs.
+ *
+ * The last saved result for a key wins. An agent that was asked for again
+ * after a result was saved gives that result up until it finishes again. A
+ * failed or skipped outcome removes the result and marks the key failed; an
+ * outcome the run recorded as interrupted (stopped, not failed) leaves the key
+ * as seen but unfinished. Lines marked `cached` repeat an earlier result and
+ * are skipped, and so is any agent record from a pass older than the latest
+ * `run_started`, which a slow agent of an earlier pass can still write.
+ */
+export function loadWorkflowResume(checked: CheckedWorkflowJournal): WorkflowResumeState {
+	const results = new Map<
+		string,
+		{ value: unknown; pass: number; index: number; childSessionId?: string }
+	>()
+	const seen = new Set<string>()
+	const failed = new Set<string>()
+	const demoted = new Set<string>()
+	const problems: string[] = []
+	const keysByIndex = new Map<string, string>()
+	let currentPass = 0
+	let scriptSha256: string | undefined
+	let previousFinish: WorkflowFinishStatus | 'unfinished' = 'unfinished'
+
+	for (const record of checked.records) {
+		if (record.type === 'run_started') {
+			currentPass = record.resume?.pass ?? 1
+			scriptSha256 = record.scriptSha256
+			previousFinish = 'unfinished'
+			keysByIndex.clear()
+			continue
+		}
+		if (record.type === 'run_finished') {
+			previousFinish = record.status
+			continue
+		}
+		if (record.type !== 'agent_request' && record.type !== 'agent_outcome') continue
+		const pass = record.pass ?? 1
+		if (pass < currentPass || record.cached === true) continue
+		if (record.type === 'agent_request') {
+			if (record.key === undefined) continue
+			keysByIndex.set(`${pass}:${record.index}`, record.key)
+			seen.add(record.key)
+			if (results.delete(record.key)) demoted.add(record.key)
+			continue
+		}
+		const key = record.key ?? keysByIndex.get(`${pass}:${record.index}`)
+		if (key === undefined) continue
+		seen.add(key)
+		if (record.state === 'done' && hasResult(record)) {
+			results.set(key, {
+				value: record.result,
+				pass,
+				index: record.index,
+				...(record.childSessionId !== undefined ? { childSessionId: record.childSessionId } : {}),
+			})
+			failed.delete(key)
+			demoted.delete(key)
+		} else if (record.state === 'done' && record.unsaved === true) {
+			results.delete(key)
+			demoted.add(key)
+		} else if (record.interrupted === true) {
+			// Stopped, not failed: the agent runs again and the cache stays open.
+			results.delete(key)
+		} else {
+			results.delete(key)
+			demoted.delete(key)
+			failed.add(key)
+		}
+	}
+
+	if (checked.legacy) {
+		problems.push(
+			'This run was saved before resuming was possible, so its agents cannot be reused.',
+		)
+	}
+	if (checked.brokenAt !== undefined) {
+		problems.push(
+			`The journal was changed or cut short at line ${checked.brokenAt}. Results after that point are not trusted and those agents will run again.`,
+		)
+	}
+	const started = checked.records.some((record) => record.type === 'run_started')
+	if (!checked.legacy && !started) problems.push('The journal has no usable record of the run.')
+
+	return {
+		pass: currentPass + 1,
+		results,
+		seen,
+		failed,
+		demoted,
+		...(scriptSha256 !== undefined ? { scriptSha256 } : {}),
+		previousFinish,
+		problems,
+		resumable: !checked.legacy && started,
+		...(checked.brokenAt !== undefined ? { brokenAt: checked.brokenAt } : {}),
+	}
+}