@tangle-network/agent-runtime 0.259.1 → 0.261.0

package/dist/durable.js

@@ -1,15 +1,17 @@
-import { $r as readCommittedJsonLines, Li as addSpend, Qr as prepareJsonlAppend, Si as detachedSnapshot, Zi as zeroSpend, Zr as isNoEntError, ei as writeAllBytes, zi as cloneSpend } from "./supervisor-CJyzUjc7.js";
+import { $i as zeroSpend, $r as parseCommittedJsonLines, Qr as isNoEntError, St as loadSpawnForest, Vi as cloneSpend, ai as authoredProfileDigest, ei as prepareJsonlAppend, ni as writeAllBytes, ti as readCommittedJsonLines, tr as contentAddress, vt as FileSpawnJournal, wi as detachedSnapshot, zi as addSpend } from "./supervisor-yavsoQQo.js";
+import { f as RuntimeRunStateError, i as ConfigError, m as ValidationError } from "./errors-DodWX-cb.js";
 import { a as withPursuitContext, t as composeRuntimeHooks } from "./runtime-hooks-tXpAarhW.js";
 import { a as writeAtomicDurableFile, r as publishExclusiveDurableFile } from "./durable-file-DWQA4ooo.js";
-import { _ as readRootStreamReceipt, g as readRootStream, h as ROOT_STREAM_FILE, r as supervise } from "./supervise-DsQjhLN-.js";
+import { i as applyExactAgentProfileDiff } from "./profile-D3eXNBQV.js";
+import { _ as readRootStream, g as ROOT_STREAM_FILE, i as superviseRootProfile, r as supervise, v as readRootStreamReceipt } from "./supervise-1QzYAyS2.js";
 import { h as supervisorRunDir } from "./run-layout-vwd4SwX_.js";
-import { canonicalCandidateJson } from "@tangle-network/agent-interface";
+import { canonicalCandidateDigest, canonicalCandidateJson, sha256Bytes } from "@tangle-network/agent-interface";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
-import { resolve } from "node:path";
-import { mkdir, readFile, rmdir, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { mkdir, open, readFile, realpath, rmdir, unlink } from "node:fs/promises";
 import { promisify } from "node:util";
-import { setTimeout } from "node:timers/promises";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/durable/chat-engine.ts
 const encoder = new TextEncoder();
 function encodeLine(event) {
@@ -487,6 +489,7 @@ function projectSpawnNode(nodes, record, attemptIndex) {
 	const runtime = stringField(payload, "runtime");
 	const depth = numberField(payload, "depth");
 	const assignmentId = stringField(payload, "assignmentId");
+	const successorOf = stringField(payload, "successorOf");
 	const attemptId = stringField(payload, "attemptId");
 	const startedAt = numberField(payload, "startedAt");
 	nodes.set(key, {
@@ -498,6 +501,7 @@ function projectSpawnNode(nodes, record, attemptIndex) {
 		...runtime ? { runtime } : {},
 		...depth !== void 0 ? { depth } : {},
 		...assignmentId ? { assignmentId } : {},
+		...successorOf ? { successorOf } : {},
 		...attemptId ? { attemptId } : {},
 		startedAt: startedAt ?? record.observedAt,
 		...payload && Object.hasOwn(payload, "identity") ? { identity: payload.identity } : {},
@@ -836,6 +840,227 @@ function booleanField(value, key) {
 	return typeof field === "boolean" ? field : void 0;
 }
 //#endregion
+//#region src/durable/settle-record.ts
+/** The settle record: the returned `SupervisedResult` as canonical JSON, written once. */
+const SETTLE_RECORD_FILE = "result.json";
+/** The failure record: the most recent throw, replaced by a later throw. */
+const FAILURE_RECORD_FILE = "failure.json";
+/** The directory already holds a settle record, so the run it records must not be re-entered. */
+var SettledRunDirectoryError = class extends Error {
+	path;
+	/** The root of the recorded run, which is its `runId`. */
+	recordedRunId;
+	constructor(path, recordedRunId, requestedRunId) {
+		super(recordedRunId === requestedRunId ? `supervisePursuit: ${path} records that run '${recordedRunId}' already settled; a settled run is not re-entered` : `supervisePursuit: ${path} records that run '${recordedRunId}' already settled in this directory; a directory holds one settle record, so run '${requestedRunId}' needs its own runDir`);
+		this.name = "SettledRunDirectoryError";
+		this.path = path;
+		this.recordedRunId = recordedRunId;
+	}
+};
+/** A result member whose JSON form would misstate it. */
+var UnrecordableSettleValueError = class extends TypeError {
+	path;
+	constructor(path, kind) {
+		super(`supervisePursuit: result${path} is a ${kind}, which JSON cannot record faithfully; a settle record holds plain data only`);
+		this.name = "UnrecordableSettleValueError";
+		this.path = path;
+	}
+};
+const PLAIN_PROTOTYPES = /* @__PURE__ */ new Set([
+	Object.prototype,
+	Array.prototype,
+	null
+]);
+/**
+* The JSON value of a result, or a throw naming the first member JSON would misstate. An
+* `undefined` member and a function are dropped, exactly as any JSON consumer drops them; a Map,
+* a Set, a Date, a typed array, or a class instance would be rewritten to `{}` or a string and
+* so is refused.
+*/
+function jsonValue(result) {
+	const seen = [];
+	const visit = (value, path) => {
+		if (value === null || typeof value !== "object") return;
+		if (value instanceof Map) throw new UnrecordableSettleValueError(path, "Map");
+		if (value instanceof Set) throw new UnrecordableSettleValueError(path, "Set");
+		if (value instanceof Date) throw new UnrecordableSettleValueError(path, "Date");
+		if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) throw new UnrecordableSettleValueError(path, "binary buffer");
+		if (!PLAIN_PROTOTYPES.has(Object.getPrototypeOf(value))) throw new UnrecordableSettleValueError(path, "class instance");
+		if (seen.includes(value)) throw new UnrecordableSettleValueError(path, "cycle");
+		seen.push(value);
+		if (Array.isArray(value)) for (const [index, item] of value.entries()) visit(item, `${path}[${index}]`);
+		else for (const [key, item] of Object.entries(value)) visit(item, `${path}.${key}`);
+		seen.pop();
+	};
+	visit(result, "");
+	return JSON.parse(JSON.stringify(result));
+}
+/**
+* The exact bytes `result.json` holds for a result: its JSON value serialized as RFC 8785
+* canonical JSON. Throws `UnrecordableSettleValueError` before any byte is written when the
+* result carries a value JSON would misstate.
+*/
+function settleRecordJson(result) {
+	return canonicalCandidateJson(jsonValue(result));
+}
+/** Publish `runDir/result.json` once. Throws when a record is already there. */
+async function writeSettleRecord(runDir, result) {
+	const path = resolve(runDir, SETTLE_RECORD_FILE);
+	if (!publishExclusiveDurableFile(path, settleRecordJson(result))) throw new Error(`supervisePursuit: ${path} already exists; a settle record is written once`);
+	return path;
+}
+/** Replace `runDir/failure.json` with the most recent throw. */
+async function writeFailureRecord(runDir, record) {
+	const path = resolve(runDir, FAILURE_RECORD_FILE);
+	writeAtomicDurableFile(path, `${JSON.stringify(record, null, 2)}\n`);
+	return path;
+}
+/**
+* Read the settle record a run directory holds, or `undefined` when it holds none. A file that
+* is present but is not a settle record is corruption and fails loud.
+*/
+async function readSettleRecord(runDir) {
+	const path = resolve(runDir, SETTLE_RECORD_FILE);
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (isNoEntError(error)) return void 0;
+		throw error;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause });
+	}
+	const record = parsed;
+	if (typeof record !== "object" || record === null || typeof record.kind !== "string" || typeof record.tree !== "object" || record.tree === null || typeof record.tree.root !== "string") throw new Error(`supervisePursuit: ${path} is not a settle record (no kind or tree.root)`);
+	return parsed;
+}
+/** Read the most recent failure record, or `undefined` when the directory holds none. */
+async function readFailureRecord(runDir) {
+	const path = resolve(runDir, FAILURE_RECORD_FILE);
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (isNoEntError(error)) return void 0;
+		throw error;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause });
+	}
+	const record = parsed;
+	if (typeof record !== "object" || record === null || typeof record.runId !== "string" || typeof record.pursuitId !== "string" || typeof record.at !== "string" || typeof record.error?.name !== "string" || typeof record.error.message !== "string" || record.rootStream !== void 0 && (typeof record.rootStream.ref !== "string" || typeof record.rootStream.events !== "number")) throw new Error(`supervisePursuit: ${path} is not a failure record`);
+	return parsed;
+}
+//#endregion
+//#region src/durable/run-fork.ts
+/**
+* The `execution.correlation` keys a fork records on its root. Runtime writes them; a caller that
+* supplies one is refused. `lineageRootRunId` is the first run of the chain of parents, so the
+* spend of every version of one lineage groups under one id.
+*/
+const RUN_FORK_CORRELATION_KEYS = Object.freeze([
+	"forkParentRunId",
+	"forkParentSettleDigest",
+	"forkProfileDiffId",
+	"lineageRootRunId"
+]);
+/** The correlation key an accepted uncertain parent adds: its uncertain node ids, comma-joined. */
+const FORK_PARENT_UNCERTAIN_NODES_KEY = "forkParentUncertainNodes";
+/**
+* Verify the parent and derive the fork's profile and attribution. It reads only the parent, so
+* a refused fork spends nothing and writes nothing.
+*/
+async function prepareRunFork(profile, task, opts, fork) {
+	const change = fork.change;
+	if (typeof change?.id !== "string" || change.id.trim().length === 0) throw new ValidationError("supervisePursuit fork: change.id must be a non-empty string");
+	const parentDir = await realDirectory(fork.runDir, "fork.runDir");
+	const forkDir = await realDirectory(opts.runDir, "runDir", true);
+	if (contains(parentDir, forkDir) || contains(forkDir, parentDir)) throw new ValidationError(`supervisePursuit fork: runDir ${forkDir} overlaps the parent's runDir ${parentDir}; a fork needs its own directory outside the parent's`);
+	let bytes;
+	try {
+		bytes = await readFile(resolve(parentDir, SETTLE_RECORD_FILE));
+	} catch (error) {
+		if (!isNoEntError(error)) throw error;
+		throw new RuntimeRunStateError(`supervisePursuit fork: ${parentDir} holds no ${SETTLE_RECORD_FILE}; only a settled run is forked`);
+	}
+	const observed = sha256Bytes(bytes);
+	if (observed !== fork.settleDigest) throw new RuntimeRunStateError(`supervisePursuit fork: ${SETTLE_RECORD_FILE} hashes to ${observed}, not the requested ${fork.settleDigest}`);
+	const settled = await readSettleRecord(parentDir);
+	if (settled === void 0) throw new RuntimeRunStateError(`supervisePursuit fork: ${parentDir} lost its settle record`);
+	const parentRunId = settled.tree.root;
+	if ((opts.runId ?? "supervise") === parentRunId) throw new ValidationError(`supervisePursuit fork: runId '${parentRunId}' is the parent's; a fork needs its own runId`);
+	const forest = await loadSpawnForest(new FileSpawnJournal(resolve(parentDir, "spawn-journal.jsonl")), parentRunId);
+	const uncertain = [
+		...forest.inDoubt.map((node) => `${node.nodeId} (no terminal record)`),
+		...forest.missingTrees.map((tree) => `${tree.ownerNodeId} (tree ${tree.root} never begun)`),
+		...(settled.teardownUnconfirmed ?? []).map((node) => `${node.id} (teardown unconfirmed)`)
+	];
+	if (settled.tree.inFlight > 0 && uncertain.length === 0) uncertain.push(`${settled.tree.inFlight} in flight`);
+	if (uncertain.length > 0 && fork.acceptUncertain !== true) throw new RuntimeRunStateError(`supervisePursuit fork: run '${parentRunId}' has uncertain nodes: ${uncertain.join(", ")}; set fork.acceptUncertain to fork it anyway`);
+	const root = forest.trees[0]?.events.find((event) => event.kind === "spawned" && event.parent === void 0);
+	const recorded = root?.identity;
+	if (recorded?.profileDigest === void 0 || recorded.taskDigest === void 0) throw new RuntimeRunStateError(`supervisePursuit fork: run '${parentRunId}' records no root profile and task digest`);
+	const mismatches = [
+		authoredProfileDigest(superviseRootProfile(profile, opts.profileGuidance)) !== recorded.profileDigest ? `profile is not the parent's ${recorded.profileDigest}` : void 0,
+		digestOrUndefined(task) !== recorded.taskDigest ? `task is not the parent's ${recorded.taskDigest}` : void 0,
+		contentAddress(root?.budget) !== contentAddress(opts.budget) ? "budget is not the parent's" : void 0
+	].filter((mismatch) => mismatch !== void 0);
+	if (mismatches.length > 0) throw new ValidationError(`supervisePursuit fork: ${mismatches.join("; ")}`);
+	const forked = applyExactAgentProfileDiff(profile, change, "supervisePursuit fork");
+	if (authoredProfileDigest(superviseRootProfile(forked, opts.profileGuidance)) === recorded.profileDigest) throw new ValidationError(`supervisePursuit fork: change '${change.id}' leaves the parent's profile unchanged`);
+	const supplied = opts.execution?.correlation ?? {};
+	const owned = [...RUN_FORK_CORRELATION_KEYS, FORK_PARENT_UNCERTAIN_NODES_KEY].filter((key) => Object.hasOwn(supplied, key));
+	if (owned.length > 0) throw new ValidationError(`supervisePursuit fork: execution.correlation cannot set ${owned.join(", ")}; Runtime records them`);
+	return Object.freeze({
+		profile: forked,
+		execution: Object.freeze({
+			...opts.execution,
+			correlation: Object.freeze({
+				...supplied,
+				forkParentRunId: parentRunId,
+				forkParentSettleDigest: fork.settleDigest,
+				forkProfileDiffId: change.id,
+				lineageRootRunId: recorded.correlation?.lineageRootRunId ?? parentRunId,
+				...uncertain.length === 0 ? {} : { [FORK_PARENT_UNCERTAIN_NODES_KEY]: uncertain.join(", ") }
+			})
+		})
+	});
+}
+function digestOrUndefined(value) {
+	try {
+		return canonicalCandidateDigest(value);
+	} catch {
+		return;
+	}
+}
+/**
+* Resolve a directory through symlinks. The fork's own directory may not exist yet; it resolves
+* through its nearest existing ancestor, so a symlinked ancestor cannot hide an overlap.
+*/
+async function realDirectory(path, name, mayBeAbsent = false) {
+	if (typeof path !== "string" || path.trim().length === 0) throw new ValidationError(`supervisePursuit fork: ${name} must be a non-empty string`);
+	const absolute = resolve(path.trim());
+	try {
+		return await realpath(absolute);
+	} catch (error) {
+		const ancestor = dirname(absolute);
+		if (!mayBeAbsent || !isNoEntError(error) || ancestor === absolute) throw error;
+		return join(await realDirectory(ancestor, name, true), basename(absolute));
+	}
+}
+/** Whether `inner` is `outer` or lies beneath it. */
+function contains(outer, inner) {
+	const path = relative(outer, inner);
+	return path === "" || !isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`);
+}
+//#endregion
 //#region src/durable/run-lock.ts
 /** The lock file `supervisePursuit` holds inside a run directory for the life of one call. */
 const RUN_DIRECTORY_LOCK_FILE = "supervise.lock";
@@ -1010,7 +1235,7 @@ async function withMutationGuard(path, mutate, waitForRelease = false) {
 		break;
 	} catch (cause) {
 		if (waitForRelease && cause.code === "EEXIST" && performance.now() < deadline) {
-			await setTimeout(10);
+			await setTimeout$1(10);
 			continue;
 		}
 		throw new Error(`supervisePursuit: cannot mutate ${path}; inspect ${guard} and remove it only after confirming no lock mutation is active`, { cause });
@@ -1029,123 +1254,424 @@ async function removeIfPresent(path) {
 	}
 }
 //#endregion
-//#region src/durable/settle-record.ts
-/** The settle record: the returned `SupervisedResult` as canonical JSON, written once. */
-const SETTLE_RECORD_FILE = "result.json";
-/** The failure record: the most recent throw, replaced by a later throw. */
-const FAILURE_RECORD_FILE = "failure.json";
-/** The directory already holds a settle record, so the run it records must not be re-entered. */
-var SettledRunDirectoryError = class extends Error {
-	path;
-	/** The root of the recorded run, which is its `runId`. */
-	recordedRunId;
-	constructor(path, recordedRunId, requestedRunId) {
-		super(recordedRunId === requestedRunId ? `supervisePursuit: ${path} records that run '${recordedRunId}' already settled; a settled run is not re-entered` : `supervisePursuit: ${path} records that run '${recordedRunId}' already settled in this directory; a directory holds one settle record, so run '${requestedRunId}' needs its own runDir`);
-		this.name = "SettledRunDirectoryError";
-		this.path = path;
-		this.recordedRunId = recordedRunId;
-	}
-};
-/** A result member whose JSON form would misstate it. */
-var UnrecordableSettleValueError = class extends TypeError {
-	path;
-	constructor(path, kind) {
-		super(`supervisePursuit: result${path} is a ${kind}, which JSON cannot record faithfully; a settle record holds plain data only`);
-		this.name = "UnrecordableSettleValueError";
-		this.path = path;
-	}
-};
-const PLAIN_PROTOTYPES = /* @__PURE__ */ new Set([
-	Object.prototype,
-	Array.prototype,
-	null
-]);
-/**
-* The JSON value of a result, or a throw naming the first member JSON would misstate. An
-* `undefined` member and a function are dropped, exactly as any JSON consumer drops them; a Map,
-* a Set, a Date, a typed array, or a class instance would be rewritten to `{}` or a string and
-* so is refused.
-*/
-function jsonValue(result) {
-	const seen = [];
-	const visit = (value, path) => {
-		if (value === null || typeof value !== "object") return;
-		if (value instanceof Map) throw new UnrecordableSettleValueError(path, "Map");
-		if (value instanceof Set) throw new UnrecordableSettleValueError(path, "Set");
-		if (value instanceof Date) throw new UnrecordableSettleValueError(path, "Date");
-		if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) throw new UnrecordableSettleValueError(path, "binary buffer");
-		if (!PLAIN_PROTOTYPES.has(Object.getPrototypeOf(value))) throw new UnrecordableSettleValueError(path, "class instance");
-		if (seen.includes(value)) throw new UnrecordableSettleValueError(path, "cycle");
-		seen.push(value);
-		if (Array.isArray(value)) for (const [index, item] of value.entries()) visit(item, `${path}[${index}]`);
-		else for (const [key, item] of Object.entries(value)) visit(item, `${path}.${key}`);
-		seen.pop();
+//#region src/durable/pursuit-versions.ts
+/** The longest delay Node's setTimeout honors. */
+const MAX_TIMER_MS = 2147483647;
+/** The ledger file inside the lineage directory. */
+const PURSUIT_VERSIONS_FILE = "versions.jsonl";
+/** The `<runDir>.v<n>` directory and `<runId>.v<n>` id of version `n`, beside the first. */
+function pursuitVersionRun(runDir, runId, version) {
+	return version === 1 ? {
+		runDir,
+		runId
+	} : {
+		runDir: `${runDir}.v${version}`,
+		runId: `${runId}.v${version}`
 	};
-	visit(result, "");
-	return JSON.parse(JSON.stringify(result));
 }
 /**
-* The exact bytes `result.json` holds for a result: its JSON value serialized as RFC 8785
-* canonical JSON. Throws `UnrecordableSettleValueError` before any byte is written when the
-* result carries a value JSON would misstate.
+* Validate a `versions` option before any compute. The same check runs inside `supervisePursuit`;
+* a caller that records the option as data can run it at preflight.
 */
-function settleRecordJson(result) {
-	return canonicalCandidateJson(jsonValue(result));
-}
-/** Publish `runDir/result.json` once. Throws when a record is already there. */
-async function writeSettleRecord(runDir, result) {
-	const path = resolve(runDir, SETTLE_RECORD_FILE);
-	if (!publishExclusiveDurableFile(path, settleRecordJson(result))) throw new Error(`supervisePursuit: ${path} already exists; a settle record is written once`);
-	return path;
+function assertPursuitVersions(versions) {
+	const fail = (message) => {
+		throw new ValidationError(`supervisePursuit versions: ${message}`);
+	};
+	if (typeof versions !== "object" || versions === null) fail("must be an object");
+	const { judge, next, stop, run } = versions;
+	if (typeof judge === "string") {
+		if (judge.trim().length === 0) fail("judge must name a registry entry");
+	} else if (typeof judge !== "object" || judge === null || typeof judge.judge !== "function") fail("judge must be a VersionJudge or a registry name");
+	else if (!isSha256(judge.digest)) fail("judge.digest must be a sha256 digest (sha256:<64 hex>)");
+	if (typeof next === "string" ? next.trim().length === 0 : typeof next !== "function") fail("next must be a function or a registry name");
+	if (run !== void 0 && typeof run !== "function") fail("run must be a function when set");
+	const { usd } = versions;
+	if (usd !== void 0 && typeof usd !== "function") fail("usd must be a function when set");
+	if (typeof stop !== "object" || stop === null) fail("stop must be an object");
+	const rule = stop;
+	const known = /* @__PURE__ */ new Set([
+		"patience",
+		"maxVersions",
+		"maxUsd",
+		"deadlineMs",
+		"minImprovement"
+	]);
+	const unknown = Object.keys(rule).filter((key) => !known.has(key));
+	if (unknown.length > 0) fail(`stop has unknown fields: ${unknown.join(", ")}`);
+	for (const key of ["patience", "maxVersions"]) if (!Number.isInteger(rule[key]) || rule[key] < 1) fail(`stop.${key} must be an integer of at least 1`);
+	for (const key of ["maxUsd", "deadlineMs"]) if (typeof rule[key] !== "number" || !Number.isFinite(rule[key]) || rule[key] <= 0) fail(`stop.${key} must be a finite number above 0`);
+	if (rule.minImprovement !== void 0 && (typeof rule.minImprovement !== "number" || !Number.isFinite(rule.minImprovement) || rule.minImprovement < 0)) fail("stop.minImprovement must be a finite number of at least 0");
 }
-/** Replace `runDir/failure.json` with the most recent throw. */
-async function writeFailureRecord(runDir, record) {
-	const path = resolve(runDir, FAILURE_RECORD_FILE);
-	writeAtomicDurableFile(path, `${JSON.stringify(record, null, 2)}\n`);
-	return path;
+/** Run a version chain. `supervisePursuit` calls this when `versions` is set. */
+async function runPursuitVersions(profile, task, opts, runOne) {
+	const { versions, ...rest } = opts;
+	assertPursuitVersions(versions);
+	for (const key of [
+		"journal",
+		"blobs",
+		"rootHandle",
+		"steerDir"
+	]) if (rest[key] !== void 0) throw new ValidationError(`supervisePursuit versions: ${key} names one run, and a version chain has one per version; omit it`);
+	const registry = rest.registry;
+	const judge = resolveNamed("judge", "versionJudges", versions.judge, registry?.versionJudges);
+	if (!isSha256(judge.digest)) throw new ValidationError("supervisePursuit versions: judge.digest must be a sha256 digest");
+	const next = resolveNamed("next", "nextVersions", versions.next, registry?.nextVersions);
+	const stop = versions.stop;
+	const minImprovement = stop.minImprovement ?? 0;
+	const now = rest.now ?? Date.now;
+	const pursuitId = rest.pursuitId.trim();
+	const runDir = resolve(rest.runDir.trim());
+	const runId = rest.runId ?? "supervise";
+	const { fork: firstFork, signal: callerSignal, ...base } = rest;
+	const lineageDir = `${runDir}.versions`;
+	const ledgerPath = resolve(lineageDir, PURSUIT_VERSIONS_FILE);
+	const firstProfile = firstFork === void 0 ? profile : applyExactAgentProfileDiff(profile, firstFork.change, "supervisePursuit versions");
+	await mkdir(lineageDir, { recursive: true });
+	const lock = await acquireRunDirectoryLock(lineageDir, `${runId}:versions`, now);
+	try {
+		const ledger = await readLedger(ledgerPath);
+		let chain = ledger.find((line) => line.kind === "chain");
+		if (chain === void 0) {
+			const elapsed = (await readSettleRecord(runDir))?.spentTotal?.ms;
+			const startedAt = new Date(now() - (typeof elapsed === "number" && Number.isFinite(elapsed) ? elapsed : 0)).toISOString();
+			chain = {
+				kind: "chain",
+				pursuitId,
+				runId,
+				runDir,
+				judgeDigest: judge.digest,
+				stop: canonicalStop(stop),
+				startedAt
+			};
+			await appendLedger(ledgerPath, chain);
+		} else {
+			const mismatch = [
+				chain.pursuitId !== pursuitId ? `pursuitId '${chain.pursuitId}'` : void 0,
+				chain.runId !== runId ? `runId '${chain.runId}'` : void 0,
+				chain.runDir !== runDir ? `runDir '${chain.runDir}'` : void 0,
+				chain.judgeDigest !== judge.digest ? `judge digest ${chain.judgeDigest}` : void 0,
+				contentAddress(chain.stop) !== contentAddress(canonicalStop(stop)) ? "another stop rule" : void 0
+			].filter((item) => item !== void 0);
+			if (mismatch.length > 0) throw new ValidationError(`supervisePursuit versions: ${ledgerPath} records a chain with ${mismatch.join(", ")}; a chain keeps its identity, judge and stop rule`);
+		}
+		const startedAtMs = Date.parse(chain.startedAt);
+		const deadline = new AbortController();
+		let timer;
+		const arm = () => {
+			const remaining = startedAtMs + stop.deadlineMs - now();
+			if (remaining <= 0) {
+				deadline.abort(/* @__PURE__ */ new Error("the version chain reached its deadline"));
+				return;
+			}
+			timer = setTimeout(arm, Math.min(remaining, MAX_TIMER_MS));
+			timer.unref?.();
+		};
+		arm();
+		const signal = callerSignal === void 0 ? deadline.signal : AbortSignal.any([callerSignal, deadline.signal]);
+		try {
+			const judged = [];
+			const profiles = /* @__PURE__ */ new Map([[1, firstProfile]]);
+			let pending = {
+				version: 1,
+				runId,
+				runDir
+			};
+			let stopped;
+			for (const line of ledger) if (line.kind === "start") {
+				const parentProfile = profiles.get(line.parent.version);
+				if (parentProfile === void 0) throw new RuntimeRunStateError(`supervisePursuit versions: ${ledgerPath} starts version ${line.version} from unknown version ${line.parent.version}`);
+				profiles.set(line.version, applyExactAgentProfileDiff(parentProfile, line.change, "supervisePursuit versions"));
+				pending = {
+					version: line.version,
+					runId: line.runId,
+					runDir: line.runDir,
+					parent: line.parent,
+					change: line.change
+				};
+			} else if (line.kind === "judged") {
+				if (line.version !== judged.length + 1 || line.version !== pending?.version) throw new RuntimeRunStateError(`supervisePursuit versions: ${ledgerPath} judges version ${line.version} out of order`);
+				if (line.verdict.judgeDigest !== judge.digest) throw new ValidationError(`supervisePursuit versions: version ${line.version} was judged under ${line.verdict.judgeDigest}, not ${judge.digest}`);
+				const settled = await readSettled(pending, profiles);
+				if (settled.settleDigest !== line.settleDigest) throw new RuntimeRunStateError(`supervisePursuit versions: version ${line.version}'s result.json changed after it was judged`);
+				judged.push(Object.freeze({
+					...settled,
+					verdict: line.verdict,
+					improved: line.improved,
+					usd: line.usd,
+					usdKnown: line.usdKnown,
+					usdSource: line.usdSource,
+					...line.lineage === void 0 ? {} : { lineage: line.lineage }
+				}));
+				pending = void 0;
+			} else if (line.kind === "stopped") stopped = line;
+			while (stopped === void 0) {
+				if (pending !== void 0) {
+					const spec = pending;
+					const settled = await settle(spec);
+					const verdict = await judgeVersion(settled);
+					const bestScore = bestOf(judged)?.verdict.score;
+					const improved = isFiniteNumber(verdict.score) && (!isFiniteNumber(bestScore) || verdict.score > bestScore + minImprovement);
+					const spent = settled.result.spentTotal;
+					const measured = versions.usd === void 0 ? void 0 : await versions.usd(settled, signal);
+					const usdSource = measured === void 0 ? "runtime" : "caller";
+					const usd = measured === void 0 ? isFiniteNumber(spent?.usd) ? spent.usd : null : isFiniteNumber(measured) ? measured : null;
+					const usdKnown = usd !== null && (measured !== void 0 || spent?.usdKnown !== false);
+					const lineage = versionLineage(spec, firstFork);
+					await appendLedger(ledgerPath, {
+						kind: "judged",
+						version: spec.version,
+						runId: spec.runId,
+						runDir: spec.runDir,
+						settleDigest: settled.settleDigest,
+						...spec.parent === void 0 ? {} : { parent: spec.parent },
+						...spec.change?.id === void 0 ? {} : { changeId: spec.change.id },
+						verdict,
+						improved,
+						usd,
+						usdKnown,
+						usdSource,
+						...lineage === void 0 ? {} : { lineage }
+					});
+					judged.push(Object.freeze({
+						...settled,
+						verdict,
+						improved,
+						usd,
+						usdKnown,
+						usdSource,
+						...lineage === void 0 ? {} : { lineage }
+					}));
+					pending = void 0;
+				}
+				const reason = stopReason(judged);
+				if (reason !== void 0) {
+					stopped = {
+						kind: "stopped",
+						reason,
+						at: new Date(now()).toISOString(),
+						best: (bestOf(judged) ?? judged[0]).version,
+						spentUsd: spentOf(judged)
+					};
+					await appendLedger(ledgerPath, stopped);
+					break;
+				}
+				const best = bestOf(judged) ?? judged[0];
+				const last = judged[judged.length - 1];
+				const change = await next({
+					best,
+					last,
+					versions: Object.freeze([...judged])
+				}, signal);
+				if (typeof change?.id !== "string" || change.id.trim().length === 0) throw new ValidationError("supervisePursuit versions: next must return a change with an id");
+				const version = judged.length + 1;
+				const spec = {
+					version,
+					...pursuitVersionRun(runDir, runId, version),
+					parent: {
+						version: best.version,
+						runId: best.runId,
+						settleDigest: best.settleDigest
+					},
+					change
+				};
+				profiles.set(version, applyExactAgentProfileDiff(best.profile, change, "supervisePursuit versions"));
+				await appendLedger(ledgerPath, {
+					kind: "start",
+					version,
+					runId: spec.runId,
+					runDir: spec.runDir,
+					parent: spec.parent,
+					change
+				});
+				pending = spec;
+			}
+			const bestVersion = judged.find((item) => item.version === stopped.best) ?? judged[0];
+			const record = Object.freeze({
+				lineageDir,
+				judgeDigest: judge.digest,
+				stop: canonicalStop(stop),
+				startedAt: chain.startedAt,
+				versions: Object.freeze([...judged]),
+				best: bestVersion.version,
+				spentUsd: stopped.spentUsd,
+				stopped: Object.freeze({
+					reason: stopped.reason,
+					at: stopped.at
+				})
+			});
+			const observerPath = resolve(bestVersion.runDir, "observer.jsonl");
+			return Object.freeze({
+				result: bestVersion.result,
+				pursuit: projectPursuit(await new FileObserverJournal(observerPath, pursuitId).read()),
+				observerPath,
+				settlePath: resolve(bestVersion.runDir, SETTLE_RECORD_FILE),
+				versions: record
+			});
+			/** Run the version unless its directory already settled, then read it back. */
+			async function settle(spec) {
+				if (await readSettleRecord(spec.runDir) === void 0) {
+					if (signal.aborted) throw new RuntimeRunStateError(`supervisePursuit versions: version ${spec.version} was not started: ${abortMessage(signal)}`);
+					if (spec.parent === void 0 || spec.change === void 0) await runOne(profile, task, {
+						...base,
+						...firstFork === void 0 ? {} : { fork: firstFork },
+						signal
+					});
+					else {
+						const parent = judged.find((item) => item.version === spec.parent.version);
+						if (parent === void 0) throw new RuntimeRunStateError(`supervisePursuit versions: version ${spec.version}'s parent ${spec.parent.version} is not judged`);
+						const fork = {
+							runDir: parent.runDir,
+							settleDigest: parent.settleDigest,
+							change: spec.change,
+							acceptUncertain: true
+						};
+						const options = {
+							...base,
+							runId: spec.runId,
+							runDir: spec.runDir,
+							fork,
+							signal
+						};
+						if (versions.run === void 0) await runOne(parent.profile, task, options);
+						else {
+							const prepared = await prepareRunFork(parent.profile, task, options, fork);
+							await versions.run(Object.freeze({
+								version: spec.version,
+								runId: spec.runId,
+								runDir: spec.runDir,
+								pursuitId,
+								profile: prepared.profile,
+								task,
+								budget: base.budget,
+								execution: prepared.execution,
+								fork,
+								parentProfile: parent.profile
+							}), signal);
+						}
+					}
+				}
+				const settled = await readSettled(spec, profiles);
+				if (settled === void 0) throw new RuntimeRunStateError(`supervisePursuit versions: version ${spec.version} returned without a settle record in ${spec.runDir}`);
+				return settled;
+			}
+			async function judgeVersion(settled) {
+				const verdict = await judge.judge(settled, signal);
+				if (typeof verdict !== "object" || verdict === null) throw new ValidationError("supervisePursuit versions: the judge returned no verdict");
+				if (verdict.judgeDigest !== judge.digest) throw new ValidationError(`supervisePursuit versions: the verdict for version ${settled.version} carries ${String(verdict.judgeDigest)}, not the pinned judge ${judge.digest}`);
+				if (verdict.score !== null && !isFiniteNumber(verdict.score)) throw new ValidationError("supervisePursuit versions: a verdict score must be a finite number or null");
+				return JSON.parse(JSON.stringify(verdict));
+			}
+			function stopReason(done) {
+				if (callerSignal?.aborted) return "aborted";
+				if (done.length >= stop.maxVersions) return "max-versions";
+				let stale = 0;
+				for (let index = done.length - 1; index >= 0 && !done[index].improved; index -= 1) stale += 1;
+				if (stale >= stop.patience) return "no-improvement";
+				if (done.some((item) => item.usd === null)) return "spend-unknown";
+				if (spentOf(done) >= stop.maxUsd) return "max-usd";
+				if (deadline.signal.aborted || now() - startedAtMs >= stop.deadlineMs) return "deadline";
+			}
+		} finally {
+			if (timer !== void 0) clearTimeout(timer);
+		}
+	} finally {
+		await lock.release();
+	}
 }
-/**
-* Read the settle record a run directory holds, or `undefined` when it holds none. A file that
-* is present but is not a settle record is corruption and fails loud.
-*/
-async function readSettleRecord(runDir) {
-	const path = resolve(runDir, SETTLE_RECORD_FILE);
-	let text;
+async function readSettled(spec, profiles) {
+	let bytes;
 	try {
-		text = await readFile(path, "utf8");
+		bytes = await readFile(resolve(spec.runDir, SETTLE_RECORD_FILE));
 	} catch (error) {
-		if (isNoEntError(error)) return void 0;
-		throw error;
+		if (!isNoEntError(error)) throw error;
+		throw new RuntimeRunStateError(`supervisePursuit versions: version ${spec.version} has no settle record in ${spec.runDir}`);
 	}
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch (cause) {
-		throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause });
+	const result = await readSettleRecord(spec.runDir);
+	const profile = profiles.get(spec.version);
+	if (profile === void 0) throw new RuntimeRunStateError(`supervisePursuit versions: version ${spec.version} has no recorded profile`);
+	return Object.freeze({
+		version: spec.version,
+		runId: spec.runId,
+		runDir: spec.runDir,
+		settleDigest: sha256Bytes(bytes),
+		result,
+		profile,
+		...spec.parent === void 0 ? {} : { parent: spec.parent },
+		...spec.change === void 0 ? {} : { change: spec.change }
+	});
+}
+function versionLineage(spec, firstFork) {
+	if (spec.parent !== void 0 && spec.change !== void 0) return {
+		source: lineageSource(spec.change),
+		runIds: [spec.parent.runId],
+		profileDiffIds: [spec.change.id]
+	};
+	if (firstFork !== void 0) return {
+		source: lineageSource(firstFork.change),
+		profileDiffIds: [firstFork.change.id]
+	};
+}
+/** The change's author, in the lineage's words. A trace-derived change is a compound of runs. */
+function lineageSource(change) {
+	const kind = change.source?.kind;
+	return kind === "human" || kind === "optimizer" || kind === "frontier-author" ? kind : "compound";
+}
+function bestOf(done) {
+	let best;
+	for (const item of done) {
+		if (!isFiniteNumber(item.verdict.score)) continue;
+		if (best === void 0 || item.verdict.score > best.verdict.score) best = item;
 	}
-	const record = parsed;
-	if (typeof record !== "object" || record === null || typeof record.kind !== "string" || typeof record.tree !== "object" || record.tree === null || typeof record.tree.root !== "string") throw new Error(`supervisePursuit: ${path} is not a settle record (no kind or tree.root)`);
-	return parsed;
+	return best;
 }
-/** Read the most recent failure record, or `undefined` when the directory holds none. */
-async function readFailureRecord(runDir) {
-	const path = resolve(runDir, FAILURE_RECORD_FILE);
+function spentOf(done) {
+	return done.reduce((sum, item) => sum + (item.usd ?? 0), 0);
+}
+function canonicalStop(stop) {
+	return {
+		patience: stop.patience,
+		maxVersions: stop.maxVersions,
+		maxUsd: stop.maxUsd,
+		deadlineMs: stop.deadlineMs,
+		...stop.minImprovement === void 0 ? {} : { minImprovement: stop.minImprovement }
+	};
+}
+function resolveNamed(option, table, value, registry) {
+	if (typeof value !== "string") return value;
+	if (registry === void 0) throw new ConfigError(`supervisePursuit versions: ${option} = ${JSON.stringify(value)} names a registry entry, but no registry.${table} was provided`);
+	const entry = registry.resolve(value);
+	if (entry === void 0) throw new ConfigError(`supervisePursuit versions: ${option} = ${JSON.stringify(value)} is not in registry.${table}`);
+	return entry;
+}
+async function readLedger(path) {
 	let text;
 	try {
 		text = await readFile(path, "utf8");
 	} catch (error) {
-		if (isNoEntError(error)) return void 0;
+		if (isNoEntError(error)) return [];
 		throw error;
 	}
-	let parsed;
+	return parseCommittedJsonLines(text, path);
+}
+async function appendLedger(path, line) {
+	const endsWithRecord = await prepareJsonlAppend(path);
+	const handle = await open(path, "a");
 	try {
-		parsed = JSON.parse(text);
-	} catch (cause) {
-		throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause });
+		await writeAllBytes(handle, `${endsWithRecord ? "\n" : ""}${JSON.stringify(line)}\n`);
+		await handle.sync();
+	} finally {
+		await handle.close();
 	}
-	const record = parsed;
-	if (typeof record !== "object" || record === null || typeof record.runId !== "string" || typeof record.pursuitId !== "string" || typeof record.at !== "string" || typeof record.error?.name !== "string" || typeof record.error.message !== "string" || record.rootStream !== void 0 && (typeof record.rootStream.ref !== "string" || typeof record.rootStream.events !== "number")) throw new Error(`supervisePursuit: ${path} is not a failure record`);
-	return parsed;
+}
+function isSha256(value) {
+	return typeof value === "string" && /^sha256:[0-9a-f]{64}$/u.test(value);
+}
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+function abortMessage(signal) {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason.message : String(reason ?? "aborted");
 }
 //#endregion
 //#region src/durable/supervise-pursuit.ts
@@ -1189,12 +1715,14 @@ async function supervisePursuit(profile, task, opts) {
 	const runDir = opts.runDir.trim();
 	if (runDir.length === 0) throw new TypeError("supervisePursuit: runDir must be non-empty");
 	if (opts.retainedAtSettlement === "keep") throw new TypeError("supervisePursuit: retainedAtSettlement 'keep' cannot hold, because a settled pursuit is never re-entered");
+	if (opts.versions !== void 0) return runPursuitVersions(profile, task, opts, supervisePursuit);
 	const observerPath = resolve(runDir, "observer.jsonl");
 	const settlePath = resolve(runDir, SETTLE_RECORD_FILE);
 	const failurePath = resolve(runDir, FAILURE_RECORD_FILE);
-	const { pursuitId: _pursuitId, hooks, ...superviseOptions } = opts;
+	const { pursuitId: _pursuitId, hooks, fork, versions: _versions, ...superviseOptions } = opts;
 	const runId = superviseOptions.runId ?? "supervise";
 	const now = superviseOptions.now ?? Date.now;
+	const forked = fork === void 0 ? void 0 : await prepareRunFork(profile, task, superviseOptions, fork);
 	const lock = await acquireRunDirectoryLock(runDir, runId, now);
 	try {
 		const settled = await readSettleRecord(runDir);
@@ -1203,8 +1731,9 @@ async function supervisePursuit(profile, task, opts) {
 		await observer.journal.appendEvent(rootEvent(pursuitId, runId, "before", now()));
 		let result;
 		try {
-			result = await supervise(profile, task, {
+			result = await supervise(forked?.profile ?? profile, task, {
 				...superviseOptions,
+				...forked === void 0 ? {} : { execution: forked.execution },
 				steerDir: superviseOptions.steerDir ?? supervisorRunDir(runDir, runId),
 				retainedAtSettlement: "release",
 				hooks: withPursuitContext(pursuitId, composeRuntimeHooks(observer.hooks, hooks))
@@ -1343,6 +1872,6 @@ function compareText(left, right) {
 	return left < right ? -1 : left > right ? 1 : 0;
 }
 //#endregion
-export { FAILURE_RECORD_FILE, FileObserverJournal, ROOT_STREAM_FILE, RUN_DIRECTORY_LOCK_FILE, RunDirectoryLockedError, SETTLE_RECORD_FILE, SettledRunDirectoryError, SupervisePursuitError, acquireRunDirectoryLock, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, readFailureRecord, readRootStream, readRootStreamReceipt, readRunDirectoryLock, readSettleRecord, runDirectoryHolderIsLive, settleRecordJson, supervisePursuit, verifyObserverRecords };
+export { FAILURE_RECORD_FILE, FORK_PARENT_UNCERTAIN_NODES_KEY, FileObserverJournal, PURSUIT_VERSIONS_FILE, ROOT_STREAM_FILE, RUN_DIRECTORY_LOCK_FILE, RUN_FORK_CORRELATION_KEYS, RunDirectoryLockedError, SETTLE_RECORD_FILE, SettledRunDirectoryError, SupervisePursuitError, acquireRunDirectoryLock, assertPursuitVersions, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, pursuitVersionRun, readFailureRecord, readRootStream, readRootStreamReceipt, readRunDirectoryLock, readSettleRecord, runDirectoryHolderIsLive, settleRecordJson, supervisePursuit, verifyObserverRecords };
 
 //# sourceMappingURL=durable.js.map