@namzu/sdk 62.6.1 → 62.8.0

package/src/sandbox/file-walk.ts

@@ -15,6 +15,9 @@ import { VCS_NAMES, createIgnoreStack } from './ignore-matcher.js'
 /** Entries a walk examines before it stops with what it has: a safety valve, not a budget. */
 export const DEFAULT_MAX_VISITED_ENTRIES = 500_000
 
+/** Longest the walk holds the event loop between yields. */
+const WALK_SLICE_MS = 8
+
 const GLOBSTAR = Symbol('globstar')
 type Segment = string | { source: string; flags: string } | typeof GLOBSTAR
 
@@ -185,6 +188,7 @@ async function* executeWalk(
 	plan: WalkPlan,
 	signal?: AbortSignal,
 	onSummary?: (summary: SandboxWalkSummary) => void,
+	withoutSizes = false,
 ): AsyncGenerator<SandboxFileEntry> {
 	const fs = await import('node:fs/promises')
 	const path = await import('node:path')
@@ -196,6 +200,7 @@ async function* executeWalk(
 		/** Whether leaving this directory also drops its ignore layer. */
 		layered: boolean
 	}[] = []
+	let sliceStart = performance.now()
 	let visited = 0
 	let emitted = 0
 	let ignoredDirectories = 0
@@ -327,8 +332,22 @@ async function* executeWalk(
 		while (open.length > 0) {
 			check()
 			const frame = open[open.length - 1] as (typeof open)[number]
-			const entry = await wait(frame.dir.read())
-			check()
+			let entry: import('node:fs').Dirent | null
+			if (withoutSizes) {
+				// A local search consumer reads a directory's buffered entries
+				// synchronously: one promise per entry costs more than the listing.
+				// The loop yields on a time slice, and a blocked read cannot be
+				// raced, which only the default path promises.
+				if (performance.now() - sliceStart > WALK_SLICE_MS) {
+					await new Promise<void>((done) => setImmediate(done))
+					sliceStart = performance.now()
+				}
+				check()
+				entry = frame.dir.readSync()
+			} else {
+				entry = await wait(frame.dir.read())
+				check()
+			}
 			if (!entry) {
 				open.pop()
 				if (frame.layered) ignore?.leave()
@@ -351,6 +370,13 @@ async function* executeWalk(
 			}
 			if (!entry.isFile() || !matchers.some((matcher) => matcher.test(relative))) continue
 			if (ignore?.isIgnored(absolute, false)) continue
+			if (withoutSizes) {
+				// The caller opens the file anyway and reads its size from the handle.
+				emitted += 1
+				yield { path: absolute, size: 0 }
+				if (emitted >= plan.maxEntries) return
+				continue
+			}
 			let info: import('node:fs').Stats
 			try {
 				info = await wait(fs.lstat(absolute))
@@ -384,10 +410,21 @@ function globalIgnoreFiles(): string[] {
 /** Internal host path; the caller first resolves its authorized filesystem root. */
 export async function* walkFilesLocally(
 	rootPath: string,
-	options: SandboxWalkFilesOptions,
+	options: SandboxWalkFilesOptions & {
+		/**
+		 * Skip the per-file size read: entries carry `size: 0`. For a caller that
+		 * opens every file itself and takes the size from the handle.
+		 */
+		readonly withoutSizes?: boolean
+	},
 ): AsyncGenerator<SandboxFileEntry> {
 	options.signal?.throwIfAborted()
-	yield* executeWalk(planWalk(rootPath, options), options.signal, options.onSummary)
+	yield* executeWalk(
+		planWalk(rootPath, options),
+		options.signal,
+		options.onSummary,
+		options.withoutSizes === true,
+	)
 }
 
 /** The existing sandbox execution seam; no separate worker protocol is needed. */

package/src/sandbox/glob-segment.ts

@@ -7,22 +7,24 @@
  */
 
 // Written for the `u` flag, which every compiled expression carries.
-const POSIX_CLASSES: Record<string, string> = {
-	alnum: '\\p{L}\\p{Nl}\\p{Nd}',
-	alpha: '\\p{L}\\p{Nl}',
-	ascii: '\\x00-\\x7f',
-	blank: '\\p{Zs}\\t',
-	cntrl: '\\p{Cc}',
-	digit: '\\p{Nd}',
-	graph: '\\x21-\\x7e',
-	lower: '\\p{Ll}',
-	print: '\\x20-\\x7e',
-	punct: '\\p{P}\\p{S}',
-	space: '\\s',
-	upper: '\\p{Lu}',
-	word: '\\p{L}\\p{Nl}\\p{Nd}_',
-	xdigit: '0-9a-fA-F',
-}
+const POSIX_CLASSES: ReadonlyMap<string, string> = new Map(
+	Object.entries({
+		alnum: '\\p{L}\\p{Nl}\\p{Nd}',
+		alpha: '\\p{L}\\p{Nl}',
+		ascii: '\\x00-\\x7f',
+		blank: '\\p{Zs}\\t',
+		cntrl: '\\p{Cc}',
+		digit: '\\p{Nd}',
+		graph: '\\x21-\\x7e',
+		lower: '\\p{Ll}',
+		print: '\\x20-\\x7e',
+		punct: '\\p{P}\\p{S}',
+		space: '\\s',
+		upper: '\\p{Lu}',
+		word: '\\p{L}\\p{Nl}\\p{Nd}_',
+		xdigit: '0-9a-fA-F',
+	}),
+)
 
 export interface CompiledSegment {
 	/** Set when the segment has no magic: the exact name it matches. */
@@ -31,6 +33,23 @@ export interface CompiledSegment {
 	source: string
 }
 
+/**
+ * The longest segment, in UTF-16 code units, that `compileSegment` accepts. A
+ * file name is at most 255 bytes on the file systems Namzu runs on, so a
+ * pattern for one name beyond four times that is never legitimate, while
+ * compiling a segment costs time in proportion to the square of its length.
+ */
+export const MAX_GLOB_SEGMENT_LENGTH = 1024
+
+/** How much of an over-long pattern an error message shows, in code points. */
+const PREVIEW_LENGTH = 60
+
+/** The first `PREVIEW_LENGTH` code points of `text`, never cutting a surrogate pair. */
+const preview = (text: string) =>
+	Array.from(text.slice(0, PREVIEW_LENGTH * 2))
+		.slice(0, PREVIEW_LENGTH)
+		.join('')
+
 /**
  * Raised for a segment that repeats a group (`*( )` or `+( )`) which could match
  * the same text more than one way. Such a group backtracks exponentially on a
@@ -38,14 +57,17 @@ export interface CompiledSegment {
  */
 export class GlobTooComplexError extends Error {
 	readonly segment: string
-	constructor(segment: string, reason: 'ambiguous' | 'stretch' = 'ambiguous') {
+	constructor(segment: string, reason: 'ambiguous' | 'stretch' | 'length' = 'ambiguous') {
 		super(
-			reason === 'stretch'
-				? `The pattern '${segment}' has more than three wildcards that can stretch; split it across folders or use fewer *.`
-				: `The pattern '${segment}' repeats a group that can match the same text more than one way; use ** or {a,b} instead.`,
+			reason === 'length'
+				? `The pattern '${preview(segment)}...' is too long (${segment.length} characters; at most ${MAX_GLOB_SEGMENT_LENGTH} between slashes); shorten it or split it across folders.`
+				: reason === 'stretch'
+					? `The pattern '${segment}' has more than three wildcards that can stretch; split it across folders or use fewer *.`
+					: `The pattern '${segment}' repeats a group that can match the same text more than one way; use ** or {a,b} instead.`,
 		)
 		this.name = 'GlobTooComplexError'
-		this.segment = segment
+		// An over-long pattern is not kept whole: the error may be logged.
+		this.segment = reason === 'length' ? preview(segment) : segment
 	}
 }
 
@@ -85,7 +107,7 @@ function classEnd(text: string, start: number): number {
 		if (ch === '\\') index += 1
 		else if (ch === '[' && text[index + 1] === ':') {
 			const end = text.indexOf(':]', index + 2)
-			if (end > 0 && POSIX_CLASSES[text.slice(index + 2, end)]) index = end + 1
+			if (end > 0 && POSIX_CLASSES.has(text.slice(index + 2, end))) index = end + 1
 		} else if (ch === ']') return index
 	}
 	return -1
@@ -134,8 +156,9 @@ function classSource(body: string): string {
 		if (ch === '[' && body[index + 1] === ':') {
 			const end = body.indexOf(':]', index + 2)
 			const name = end > 0 ? body.slice(index + 2, end) : ''
-			if (POSIX_CLASSES[name]) {
-				out += POSIX_CLASSES[name]
+			const members = POSIX_CLASSES.get(name)
+			if (members !== undefined) {
+				out += members
 				index = end + 1
 				continue
 			}
@@ -268,6 +291,7 @@ function isOneGroup(text: string): boolean {
  * segment that itself begins with a literal `.` can.
  */
 export function compileSegment(segment: string, dot: boolean): CompiledSegment {
+	if (segment.length > MAX_GLOB_SEGMENT_LENGTH) throw new GlobTooComplexError(segment, 'length')
 	const guard = dot ? '' : '(?!\\.)'
 	let parsed: Parsed
 	try {

package/src/store/checkpoint/contract.ts

@@ -62,6 +62,21 @@ export interface CheckpointLogView {
 	 * `decision_resolved` or `decision_expired` yet. `prune` never deletes one.
 	 */
 	openDecisionCheckpoints(scope: CheckpointScope): Promise<Iterable<CheckpointId>>
+	/**
+	 * Both answers `prune` needs in one read of the log: for each of
+	 * `checkpointIds`, what `writtenDocSha256` would return (absent from
+	 * `written` when there is no record), and what `openDecisionCheckpoints`
+	 * would return. Optional: a view without it is asked the two questions
+	 * separately, one walk of the log each, which costs a walk per stored
+	 * checkpoint on every prune.
+	 */
+	pruneFacts?(
+		scope: CheckpointScope,
+		checkpointIds: readonly CheckpointId[],
+	): Promise<{
+		readonly written: ReadonlyMap<CheckpointId, string>
+		readonly open: Iterable<CheckpointId>
+	}>
 }
 
 /** Why a restore refused a checkpoint. */

package/src/store/checkpoint/disk.ts

@@ -1,4 +1,4 @@
-import { link, mkdir, open, readFile, readdir, unlink } from 'node:fs/promises'
+import { link, mkdir, open, readFile, readdir, stat, unlink } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import type { SessionLocator, SessionPaths } from '../../session/paths.js'
@@ -38,6 +38,17 @@ export interface DiskSessionCheckpointStoreOptions {
 
 const DOCUMENT = /^(.+)\.json$/
 
+/**
+ * Which turn a checkpoint document on disk belongs to, as last read, with the
+ * size and mtime it had then. A session keeps its checkpoints for every turn
+ * in one directory, so listing one turn's used to read and parse every
+ * document of the session, and the directory only grows. A document is not
+ * read again while a `stat` says it is the one that was; one that belonged to
+ * another turn is skipped on that evidence alone.
+ */
+const documentTurns = new Map<string, { turnId: string; size: number; mtimeMs: number }>()
+const DOCUMENT_TURNS_KEPT = 20_000
+
 /**
  * {@link SessionCheckpointStore} at `<session-dir>/checkpoints/<id>.json`.
  *
@@ -145,10 +156,31 @@ export class DiskSessionCheckpointStore implements SessionCheckpointStore {
 			// Sidecars (`<id>.json.<pid>.<n>.<hex>.tmp`) and strangers are not documents.
 			const id = DOCUMENT.exec(name)?.[1]
 			if (id === undefined || !isEntityId(id, 'checkpoint')) continue
-			const text = await readIfPresent(this.#paths.checkpointFile(locator, id))
+			const path = this.#paths.checkpointFile(locator, id)
+			const seen = await stat(path).catch((error: NodeJS.ErrnoException) => {
+				if (error.code === 'ENOENT') return null
+				throw error
+			})
 			// Deleted between the listing and the read: a concurrent prune, not damage.
+			if (seen === null) continue
+			const known = documentTurns.get(path)
+			if (
+				known !== undefined &&
+				known.turnId !== checked.turnId &&
+				known.size === seen.size &&
+				known.mtimeMs === seen.mtimeMs
+			) {
+				continue
+			}
+			const text = await readIfPresent(path)
 			if (text === null) continue
 			const checkpoint = parseStoredCheckpoint(text, checked, id)
+			if (documentTurns.size >= DOCUMENT_TURNS_KEPT) documentTurns.clear()
+			documentTurns.set(path, {
+				turnId: checkpoint.turnId,
+				size: seen.size,
+				mtimeMs: seen.mtimeMs,
+			})
 			if (checkpoint.turnId === checked.turnId) checkpoints.push(checkpoint)
 		}
 		return checkpoints.sort(compareCheckpoints)

package/src/store/checkpoint/prune.ts

@@ -79,6 +79,19 @@ export async function selectStoredCheckpointsToPrune(
 	if (!Number.isSafeInteger(keepLast) || keepLast < 0) {
 		throw new RangeError(`keepLast must be a nonnegative integer, got ${String(keepLast)}`)
 	}
+	if (log.pruneFacts) {
+		// One read of the log answers both questions for every stored
+		// checkpoint, instead of one full walk each.
+		const facts = await log.pruneFacts(
+			scope,
+			stored.map((checkpoint) => checkpoint.checkpointId),
+		)
+		return selectSessionCheckpointsToPrune(
+			stored.filter((checkpoint) => facts.written.has(checkpoint.checkpointId)),
+			keepLast,
+			new Set(facts.open),
+		)
+	}
 	const committed: Checkpoint[] = []
 	for (const checkpoint of stored) {
 		if ((await log.writtenDocSha256(scope, checkpoint.checkpointId)) !== null) {

package/src/store/evidence/disk.ts

@@ -157,22 +157,64 @@ export function createSessionEvidenceSource(
 	})
 }
 
+/** What a scan of a session log's complete records, from byte 0 up to `consumed`, found. */
+interface SessionScan {
+	readonly identity: string
+	/** Offset just past the last complete record scanned. */
+	readonly consumed: number
+	readonly first: Buffer
+	readonly active: string | undefined
+	readonly turnClosed: boolean
+}
+
+/**
+ * Scans already done, by log file and scope, so that an access reads only the
+ * records appended since the last one instead of parsing the whole log again.
+ * A session log only grows, and every search page makes several accesses.
+ */
+const SCAN_CACHE_LIMIT = 64
+const scanCache = new Map<string, SessionScan>()
+
+function remember(key: string, scan: SessionScan): void {
+	scanCache.delete(key)
+	scanCache.set(key, scan)
+	if (scanCache.size > SCAN_CACHE_LIMIT) {
+		const oldest = scanCache.keys().next().value
+		if (oldest !== undefined) scanCache.delete(oldest)
+	}
+}
+
 /**
  * The first record of a session log (its `session_started`) and whether the
  * scope is closed: no turn of the session active, or — for a scope narrowed
  * to one turn — that turn settled.
+ *
+ * The scan resumes from the one a previous access left in `scanCache` when it
+ * is of the same file (same identity, first record unchanged on disk) and
+ * ended at or before `size`; otherwise it starts again from byte 0.
  */
 async function sessionState(
 	handle: FileHandle,
 	size: number,
 	scope: z.infer<typeof scopeSchema>,
+	cacheKey: string,
+	identity: string,
 ): Promise<{ first: Buffer; closed: boolean }> {
 	const unmetered: EvidenceBudget = { bytes: 0, limit: Number.MAX_SAFE_INTEGER }
 	let first: Buffer | undefined
 	let active: string | undefined
 	let turnClosed = false
-	let buffered = Buffer.alloc(0)
 	let offset = 0
+	const cached = scanCache.get(cacheKey)
+	if (cached && cached.identity === identity && cached.consumed <= size) {
+		const head = await readBytes(handle, 0, cached.first.length, unmetered)
+		if (head.equals(cached.first)) {
+			;({ first, active, turnClosed } = cached)
+			offset = cached.consumed
+		}
+	}
+	let consumed = offset
+	let buffered = Buffer.alloc(0)
 	while (offset < size || buffered.length > 0) {
 		let newline = buffered.indexOf(10)
 		if (newline < 0) {
@@ -186,6 +228,7 @@ async function sessionState(
 		const raw = buffered.subarray(0, newline + 1)
 		buffered = buffered.subarray(newline + 1)
 		newline = -1
+		consumed += raw.length
 		const record = JSON.parse(decode(raw)) as Record<string, unknown>
 		if (!first) {
 			if (
@@ -206,6 +249,12 @@ async function sessionState(
 		}
 	}
 	if (!first) throw new Error('The session log is empty; evidence is incomplete.')
+	// A source anchored earlier in the log scans less than another access has;
+	// keep the longer scan for the next one.
+	const kept = scanCache.get(cacheKey)
+	if (!kept || kept.identity !== identity || kept.consumed <= consumed) {
+		remember(cacheKey, { identity, consumed, first, active, turnClosed })
+	}
 	return { first, closed: scope.turnId !== undefined ? turnClosed : active === undefined }
 }
 
@@ -258,7 +307,13 @@ function createSource(
 						? await completePrefix(handle, before.size, budget)
 						: before.size
 			}
-			const state = await sessionState(handle, size, scope)
+			const state = await sessionState(
+				handle,
+				size,
+				scope,
+				`${logPath}\0${scopeKey}`,
+				fileIdentity(before),
+			)
 			if (!state.closed && consistency === 'closed') {
 				throw new Error('Evidence scope has an active turn; it is not closed.')
 			}

package/src/store/session-log/incremental.ts

@@ -0,0 +1,147 @@
+import type { RecordPointer } from '../../types/session/records.js'
+import { type SessionLogEntry, SessionLogIntegrityError } from './chain.js'
+import type { SessionLog } from './core.js'
+
+/**
+ * Reductions over a whole session log, advanced rather than recomputed.
+ *
+ * A session log only grows, and every turn asks it the same questions (which
+ * checkpoints were committed, which turn ids exist, what the folded context
+ * is). Answering each from byte 0 parses and verifies every record the
+ * session ever wrote, so a turn cost more the longer the session. A reduction
+ * held here remembers the last record it folded and, on the next ask, walks
+ * only what was appended after it. `SessionLog.read({ after })` checks that
+ * record against the log byte for byte before continuing, so a log that was
+ * replaced, truncated or rewritten at that record is noticed and the
+ * reduction starts again from byte 0 with the original behaviour (strict reads
+ * refuse a broken chain, tolerant reads stop at the break).
+ *
+ * What a resumed read does not do is re-verify the records before the anchor:
+ * they were verified when they were first folded, by this process. A byte
+ * flipped in them afterwards, with every later record left as it was, is not
+ * noticed by this path; a fresh process (a resume) always starts from byte 0.
+ *
+ * The cache is keyed by session id and the reduction's own name and mode,
+ * holds a few sessions, and is anchored by content, so two logs that share a
+ * session id never share a result.
+ *
+ * Cost that remains: the state of the "every message ever recorded" reduction
+ * holds each message the log ever recorded, superseded and compacted ones
+ * included, so it grows with the log and not with the live context, and it
+ * lives for the life of the process (for the sessions kept). Reading it
+ * returns a copy of all of them, which is O(history) per turn. Both are small
+ * next to the whole-log walks this file removes, and are left as they are.
+ * More than SESSIONS_KEPT sessions in use at once evict one another, and each
+ * eviction restarts from byte 0, the cost before this file existed.
+ */
+
+const SESSIONS_KEPT = 4
+
+interface Kept {
+	state: unknown
+	/** The last record folded; the next read resumes after it. */
+	anchor: RecordPointer | undefined
+	/** Calls on one reduction take turns: the state is advanced in place. */
+	turn: Promise<unknown>
+}
+
+const sessions = new Map<string, Map<string, Kept>>()
+
+function keptFor(sessionId: string, key: string): Kept {
+	let reductions = sessions.get(sessionId)
+	if (reductions === undefined) {
+		reductions = new Map()
+		if (sessions.size >= SESSIONS_KEPT) {
+			const oldest = sessions.keys().next().value
+			if (oldest !== undefined) sessions.delete(oldest)
+		}
+	} else {
+		sessions.delete(sessionId)
+	}
+	sessions.set(sessionId, reductions)
+	let kept = reductions.get(key)
+	if (kept === undefined) {
+		kept = { state: undefined, anchor: undefined, turn: Promise.resolve() }
+		reductions.set(key, kept)
+	}
+	return kept
+}
+
+export interface IncrementalFold<S, R> {
+	/** The reduction's name; one cache slot per name and read mode. */
+	readonly name: string
+	readonly mode: 'strict' | 'tolerant'
+	/** A fresh, empty state. */
+	create(): S
+	/** Fold one record into the state, in place. */
+	apply(state: S, entry: SessionLogEntry): void
+	/**
+	 * The answer, from a state that is current for as long as this call runs.
+	 * It must not keep or hand out the state itself, which later calls advance.
+	 */
+	result(state: S): Promise<R> | R
+}
+
+/**
+ * Fold `log` into `fold.create()` through `fold.apply`, resuming from the
+ * record the previous call for this session stopped at when the log still
+ * holds it, and answer with `fold.result`.
+ */
+export async function foldSessionLog<S, R>(
+	log: SessionLog,
+	fold: IncrementalFold<S, R>,
+): Promise<R> {
+	const kept = keptFor(log.sessionId, `${fold.name}:${fold.mode}`)
+	const run = async (): Promise<R> => {
+		let state = kept.state as S | undefined
+		let anchor = kept.anchor
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const resuming = state !== undefined && anchor !== undefined
+			if (!resuming) {
+				state = fold.create()
+				anchor = undefined
+			}
+			let moved = false
+			try {
+				const walk = log.read({ mode: fold.mode, ...(anchor ? { after: anchor } : {}) })
+				let summary: Awaited<ReturnType<typeof walk.next>>
+				for (;;) {
+					summary = await walk.next()
+					if (summary.done) break
+					moved = true
+					fold.apply(state as S, summary.value)
+				}
+				const ended = summary.value
+				if (resuming && !moved && ended.break?.reason === 'anchor-mismatch') {
+					kept.state = undefined
+					kept.anchor = undefined
+					state = undefined
+					anchor = undefined
+					continue
+				}
+				kept.state = state
+				kept.anchor = ended.head?.pointer ?? anchor
+				return await fold.result(state as S)
+			} catch (error) {
+				// The state may be half-advanced: never reuse it.
+				kept.state = undefined
+				kept.anchor = undefined
+				if (
+					resuming &&
+					!moved &&
+					error instanceof SessionLogIntegrityError &&
+					error.reason === 'anchor-mismatch'
+				) {
+					state = undefined
+					anchor = undefined
+					continue
+				}
+				throw error
+			}
+		}
+		throw new Error('unreachable')
+	}
+	const result = kept.turn.then(run, run)
+	kept.turn = result.catch(() => undefined)
+	return result
+}

package/src/store/session-log/index.ts

@@ -61,6 +61,13 @@ export {
 	withMessageId,
 } from './fold.js'
 export { type TornTailRepair, repairRecordDraft } from './heal.js'
+export {
+	foldChildOutcomes,
+	foldTurnOutcomes,
+	parseTurnOutcome,
+	readOutcomeProgress,
+	readTurnOutcome,
+} from './turn-outcome.js'
 export {
 	type ReleaseHeldSessionLeasesOptions,
 	type ReleaseHeldSessionLeasesResult,

package/src/store/session-log/turn-outcome.ts

@@ -0,0 +1,84 @@
+import type { CheckpointId, SessionId, TurnId } from '../../types/ids/index.js'
+import { type TurnOutcome, TurnOutcomeSchema } from '../../types/session/outcome.js'
+import type { SessionRecord } from '../../types/session/records.js'
+import type { SessionLog } from './core.js'
+
+/**
+ * Reading the turn's outcome record back out of the session log.
+ *
+ * It lives in three records of its own (`turn_outcome_recorded`,
+ * `child_outcome_recorded`, `outcome_progress_written`), each flagged
+ * `ignorable`, and never in a field of an older record: a release that
+ * validates `turn_completed`, `child_session_ended` or the checkpoint strictly
+ * reads a log that has them and loses only the outcome. The fold of messages
+ * does not look at them. A body that does not parse as a `TurnOutcome` reads
+ * as no outcome, never as a guess.
+ */
+
+/** `value` as a {@link TurnOutcome}, or `undefined` when it is not one. */
+export function parseTurnOutcome(value: unknown): TurnOutcome | undefined {
+	const parsed = TurnOutcomeSchema.safeParse(value)
+	return parsed.success ? parsed.data : undefined
+}
+
+/**
+ * The outcome of each turn that recorded one, from records in log order. A
+ * turn that recorded none is absent, so a caller never reads `unchanged` into
+ * a turn nobody measured.
+ */
+export function foldTurnOutcomes(records: Iterable<SessionRecord>): Map<TurnId, TurnOutcome> {
+	const outcomes = new Map<TurnId, TurnOutcome>()
+	for (const record of records) {
+		if (record.type !== 'turn_outcome_recorded') continue
+		const outcome = parseTurnOutcome(record.outcome)
+		if (outcome) outcomes.set(record.turnId, outcome)
+		else outcomes.delete(record.turnId)
+	}
+	return outcomes
+}
+
+/** The outcome `turnId` recorded, or `undefined`. */
+export async function readTurnOutcome(
+	log: SessionLog,
+	turnId: TurnId,
+): Promise<TurnOutcome | undefined> {
+	let found: TurnOutcome | undefined
+	for await (const { record } of log.read({ mode: 'tolerant' })) {
+		if (record.type !== 'turn_outcome_recorded' || record.turnId !== turnId) continue
+		found = parseTurnOutcome(record.outcome)
+	}
+	return found
+}
+
+/**
+ * The outcome a child's settled turn recorded in the parent's log, by child
+ * session id. A child with no record is absent.
+ */
+export function foldChildOutcomes(records: Iterable<SessionRecord>): Map<SessionId, TurnOutcome> {
+	const outcomes = new Map<SessionId, TurnOutcome>()
+	for (const record of records) {
+		if (record.type !== 'child_outcome_recorded') continue
+		const outcome = parseTurnOutcome(record.outcome)
+		if (outcome) outcomes.set(record.childSessionId, outcome)
+		else outcomes.delete(record.childSessionId)
+	}
+	return outcomes
+}
+
+/**
+ * What the outcome record had gathered when `checkpointId` was written, or
+ * `undefined` when no progress record names it (a checkpoint written before
+ * the record existed, or by a release that does not write it).
+ */
+export async function readOutcomeProgress(
+	log: SessionLog,
+	checkpointId: CheckpointId,
+): Promise<Readonly<Record<string, unknown>> | undefined> {
+	let found: Readonly<Record<string, unknown>> | undefined
+	for await (const { record } of log.read({ mode: 'tolerant' })) {
+		if (record.type === 'outcome_progress_written' && record.checkpointId === checkpointId) {
+			found = record.progress
+		}
+	}
+	return found
+}

package/src/tools/admit-facts.ts

@@ -189,6 +189,7 @@ export function admitToolFacts(value: unknown): ToolFacts | undefined {
 				kind: 'failure',
 				reason,
 				subject: text(value.subject),
+				note: text(value.note),
 			})
 		}
 		default: