@tangle-network/agent-runtime 0.196.0 → 0.198.1

package/dist/durable.js

@@ -1,10 +1,14 @@
-import { i as writeAllBytes, n as parseCommittedJsonLines, r as prepareJsonlAppend, t as isNoEntError } from "./jsonl-file-BEpaEYjT.js";
-import { E as zeroSpend, s as addSpend, u as cloneSpend } from "./environment-provider-1fKZh2zl.js";
+import { Mr as parseCommittedJsonLines, Nr as prepareJsonlAppend, Pr as writeAllBytes, gn as addSpend, jr as isNoEntError, kn as zeroSpend, vn as cloneSpend } from "./redact-CVyxp2AU.js";
 import { a as withPursuitContext, t as composeRuntimeHooks } from "./runtime-hooks-tXpAarhW.js";
-import { n as supervise } from "./supervise-D9aNi8_f.js";
+import { i as writeAtomicDurableFile, r as publishExclusiveDurableFile } from "./durable-file-D24y9zg7.js";
+import { n as supervise } from "./supervise-KSe4JEcg.js";
+import { canonicalCandidateJson } from "@tangle-network/agent-interface";
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
 import { resolve } from "node:path";
+import { mkdir, readFile, rmdir, unlink } from "node:fs/promises";
+import { promisify } from "node:util";
+import { setTimeout } from "node:timers/promises";
 //#region src/durable/chat-engine.ts
 const encoder = new TextEncoder();
 function encodeLine(event) {
@@ -300,8 +304,9 @@ function toError(error) {
 *
 * Topology comes only from Runtime's canonical `agent.spawn` facts. Terminal node
 * state comes only from `agent.child`; concrete run state comes only from the root
-* `agent.run` lifecycle emitted by `supervisePursuit`. Node identity is scoped to the
-* concrete Runtime run so independent trees may both contain `root:s0` without aliasing.
+* `agent.run` lifecycle emitted by `supervisePursuit`, one row per attempt. Node identity is
+* scoped to the concrete Runtime run so independent trees may both contain `root:s0` without
+* aliasing, and a node belongs to the attempt that spawned it.
 *
 * Usage, cost and timing are reported at the class the runtime measured them at. A missing
 * class stays ABSENT and the run names the node in `spendGaps`; nothing here converts an
@@ -311,14 +316,14 @@ function projectPursuit(records) {
 	if (records.length === 0) throw new TypeError("projectPursuit: at least one observer record is required");
 	const pursuitId = records[0].pursuitId;
 	const verified = verifyObserverRecords(records, pursuitId);
-	const runs = /* @__PURE__ */ new Map();
+	const attempts = /* @__PURE__ */ new Map();
 	const nodes = /* @__PURE__ */ new Map();
 	let eventCount = 0;
 	let decisionCount = 0;
 	for (const record of verified) {
 		const observed = record.event ?? record.decision;
 		if (!observed) throw new Error(`projectPursuit: record ${record.sequence} has no observation`);
-		const run = getRun(runs, observed.runId, record);
+		const run = currentAttempt(attempts, observed.runId, record);
 		run.lastSequence = record.sequence;
 		run.lastObservedAt = record.observedAt;
 		if (record.event) {
@@ -326,20 +331,21 @@ function projectPursuit(records) {
 			run.eventCount += 1;
 			increment(run.targets, record.event.target);
 			projectRunActivity(run, record);
-			projectSpawnNode(nodes, record);
+			projectSpawnNode(nodes, record, run.attemptIndex);
 			projectNodeActivity(nodes, record);
-			projectTurn(runs, nodes, record);
+			projectTurn(run, nodes, record);
 		} else if (record.decision) {
 			decisionCount += 1;
 			run.decisionCount += 1;
 			increment(run.decisions, record.decision.kind);
 		}
 	}
-	const byRun = /* @__PURE__ */ new Map();
+	const byAttempt = /* @__PURE__ */ new Map();
 	for (const node of nodes.values()) {
-		const list = byRun.get(node.runId);
+		const key = attemptKey(node.runId, node.attemptIndex);
+		const list = byAttempt.get(key);
 		if (list) list.push(node);
-		else byRun.set(node.runId, [node]);
+		else byAttempt.set(key, [node]);
 	}
 	const first = verified[0];
 	const last = verified.at(-1);
@@ -349,17 +355,37 @@ function projectPursuit(records) {
 		chainTip: last.digest,
 		firstObservedAt: first.observedAt,
 		lastObservedAt: last.observedAt,
-		runs: Object.freeze([...runs.values()].sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId)).map((run) => freezeRun(run, byRun.get(run.runId) ?? []))),
+		runs: Object.freeze([...attempts.values()].flat().sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId)).map((run) => freezeRun(run, byAttempt.get(attemptKey(run.runId, run.attemptIndex)) ?? []))),
 		nodes: Object.freeze([...nodes.values()].sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId) || a.id.localeCompare(b.id)).map(freezeNode)),
 		eventCount,
 		decisionCount
 	});
 }
-function getRun(runs, runId, record) {
-	const existing = runs.get(runId);
-	if (existing) return existing;
+function attemptKey(runId, attemptIndex) {
+	return `${runId}\u0000${attemptIndex}`;
+}
+/**
+* The attempt a record belongs to. An `agent.run` `before` opens a new attempt when the run has
+* none or its latest attempt already settled; on an open attempt it is a resume. Every other
+* record joins the latest attempt, and a journal that never emitted `before` gets attempt 0.
+*/
+function currentAttempt(attempts, runId, record) {
+	const list = attempts.get(runId) ?? [];
+	if (list.length === 0) attempts.set(runId, list);
+	const latest = list.at(-1);
+	const isStart = record.event?.target === "agent.run" && record.event.phase === "before";
+	if (latest !== void 0 && (!isStart || latest.status === "running")) {
+		if (isStart) {
+			if (latest.started) latest.resumeCount += 1;
+			latest.started = true;
+		}
+		return latest;
+	}
 	const created = {
 		runId,
+		attemptIndex: list.length,
+		resumeCount: 0,
+		started: isStart,
 		status: "running",
 		firstSequence: record.sequence,
 		lastSequence: record.sequence,
@@ -370,7 +396,7 @@ function getRun(runs, runId, record) {
 		targets: {},
 		decisions: {}
 	};
-	runs.set(runId, created);
+	list.push(created);
 	return created;
 }
 function projectRunActivity(run, record) {
@@ -392,7 +418,7 @@ function projectRunActivity(run, record) {
 function nodeKey(runId, nodeId) {
 	return `${runId}\u0000${nodeId}`;
 }
-function projectSpawnNode(nodes, record) {
+function projectSpawnNode(nodes, record, attemptIndex) {
 	const event = record.event;
 	if (event?.target !== "agent.spawn") return;
 	const payload = objectRecord(event.payload);
@@ -416,6 +442,7 @@ function projectSpawnNode(nodes, record) {
 		id: childId,
 		...event.parentId ? { parentId: event.parentId } : {},
 		runId: event.runId,
+		attemptIndex,
 		...label ? { label } : {},
 		...runtime ? { runtime } : {},
 		...depth !== void 0 ? { depth } : {},
@@ -507,7 +534,7 @@ function attachSettlementEvidence(node, payload) {
 * root drove belongs to no spawned node and lands on the run instead, so the run's totals stay
 * complete without inventing a node for the root.
 */
-function projectTurn(runs, nodes, record) {
+function projectTurn(run, nodes, record) {
 	const event = record.event;
 	if (event?.target !== "agent.turn") return;
 	const payload = objectRecord(event.payload);
@@ -517,8 +544,6 @@ function projectTurn(runs, nodes, record) {
 	const node = nodes.get(nodeKey(event.runId, subject));
 	if (!node) {
 		if (!spend) return;
-		const run = runs.get(event.runId);
-		if (!run) return;
 		run.rootInference = run.rootInference ? addSpend(run.rootInference, spend) : spend;
 		return;
 	}
@@ -679,7 +704,7 @@ function timingOf(node) {
 }
 function freezeRun(run, nodes) {
 	const gaps = runSpendGaps(nodes);
-	const { rootInference: _rootInference, ...rest } = run;
+	const { rootInference: _rootInference, started: _started, ...rest } = run;
 	return Object.freeze({
 		...rest,
 		targets: Object.freeze({ ...run.targets }),
@@ -689,7 +714,7 @@ function freezeRun(run, nodes) {
 	});
 }
 function freezeNode(node) {
-	const { modelCalls, reasoningTokens, startedAt: _startedAt, ...rest } = node;
+	const { modelCalls, reasoningTokens, startedAt: _startedAt, attemptIndex: _attemptIndex, ...rest } = node;
 	const total = nodeTotal(node);
 	const timing = timingOf(node);
 	return Object.freeze({
@@ -732,16 +757,308 @@ function booleanField(value, key) {
 	return typeof field === "boolean" ? field : void 0;
 }
 //#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";
+/** The directory is held by a live process. `holder` is what that process recorded. */
+var RunDirectoryLockedError = class extends Error {
+	path;
+	holder;
+	constructor(path, holder) {
+		super(`supervisePursuit: ${path} is held by pid ${holder.pid} (run '${holder.runId}', since ${holder.startedAt}); one process drives a run directory at a time`);
+		this.name = "RunDirectoryLockedError";
+		this.path = path;
+		this.holder = holder;
+	}
+};
+/**
+* Take `runDir/supervise.lock`, or refuse.
+*
+* The file is published with its full content or not at all, so a contender never reads a
+* half-written holder. A lock whose holder is gone (its pid no longer exists, or the pid now
+* belongs to a process with a different start token) is stale and is removed under the mutation guard;
+* a pid this process may not signal (`EPERM`) is alive and refuses. An empty file names no
+* holder and is reclaimed. A file with unreadable content is left in place and refused:
+* reclaiming it could evict a live holder written by something other than this module.
+*/
+async function acquireRunDirectoryLock(runDir, runId, now = Date.now) {
+	const dir = resolve(runDir);
+	const path = resolve(dir, RUN_DIRECTORY_LOCK_FILE);
+	await mkdir(dir, { recursive: true });
+	const processStart = await readProcessStart(process.pid);
+	const holder = Object.freeze({
+		pid: process.pid,
+		startedAt: new Date(now()).toISOString(),
+		runId,
+		...processStart === void 0 ? {} : { processStart }
+	});
+	return withMutationGuard(path, async () => {
+		const existing = await readLockFile(path);
+		if (existing.state === "holder" && await holderIsLive(existing.holder)) throw new RunDirectoryLockedError(path, existing.holder);
+		if (existing.state !== "missing") await removeIfPresent(path);
+		if (!publishExclusiveDurableFile(path, `${JSON.stringify(holder)}\n`)) throw new Error(`supervisePursuit: could not take ${path}`);
+		let released = false;
+		return Object.freeze({
+			...holder,
+			path,
+			release: async () => {
+				if (released) return;
+				await releaseHolder(path, holder);
+				released = true;
+			}
+		});
+	});
+}
+/** Read the holder a lock file names, or `undefined` when no lock file names one. */
+async function readRunDirectoryLock(runDir) {
+	const existing = await readLockFile(resolve(runDir, RUN_DIRECTORY_LOCK_FILE));
+	return existing.state === "holder" ? existing.holder : void 0;
+}
+const execFileAsync = promisify(execFile);
+/**
+* The OS's start token for a live pid: on Linux the `starttime` field of `/proc/<pid>/stat`
+* (clock ticks since boot), elsewhere the `ps` `lstart` column. The same process reports the
+* same token for its whole life and a later holder of the pid reports a different one.
+* `undefined` when the host cannot report one: the pid is gone, there is no `/proc` and no
+* `ps`, or the platform is Windows.
+*/
+async function readProcessStart(pid) {
+	if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return void 0;
+	if (process.platform === "linux") {
+		let stat;
+		try {
+			stat = await readFile(`/proc/${pid}/stat`, "utf8");
+		} catch {
+			return;
+		}
+		const startTime = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/u)[19];
+		return startTime !== void 0 && /^\d+$/u.test(startTime) ? startTime : void 0;
+	}
+	try {
+		const { stdout } = await execFileAsync("ps", [
+			"-o",
+			"lstart=",
+			"-p",
+			String(pid)
+		]);
+		const token = stdout.trim();
+		return token.length === 0 ? void 0 : token;
+	} catch {
+		return;
+	}
+}
+async function readLockFile(path) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (isNoEntError(error)) return { state: "missing" };
+		throw error;
+	}
+	if (text.trim().length === 0) return { state: "empty" };
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		throw new Error(`supervisePursuit: ${path} is not a readable lock file; remove it by hand`, { cause });
+	}
+	const record = parsed;
+	if (typeof record !== "object" || record === null || typeof record.pid !== "number" || !Number.isInteger(record.pid) || record.pid <= 0 || typeof record.startedAt !== "string" || typeof record.runId !== "string" || record.processStart !== void 0 && typeof record.processStart !== "string") throw new Error(`supervisePursuit: ${path} is not a readable lock file; remove it by hand`);
+	const { pid, startedAt, runId, processStart } = record;
+	return {
+		state: "holder",
+		holder: Object.freeze({
+			pid,
+			startedAt,
+			runId,
+			...processStart === void 0 ? {} : { processStart }
+		})
+	};
+}
+async function holderIsLive(holder) {
+	if (!processExists(holder.pid)) return false;
+	if (holder.processStart === void 0) return true;
+	const current = await readProcessStart(holder.pid);
+	return current === void 0 || current === holder.processStart;
+}
+function processExists(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+/** Remove the lock only while it still names this holder; a reclaimed lock belongs to its new owner. */
+async function releaseHolder(path, holder) {
+	await withMutationGuard(path, async () => {
+		const existing = await readLockFile(path);
+		if (existing.state !== "holder") return;
+		if (existing.holder.pid !== holder.pid || existing.holder.startedAt !== holder.startedAt || existing.holder.runId !== holder.runId || existing.holder.processStart !== holder.processStart) return;
+		await removeIfPresent(path);
+	}, true);
+}
+/** Serialize stale reclamation and release; an abandoned guard requires operator recovery. */
+async function withMutationGuard(path, mutate, waitForRelease = false) {
+	const guard = `${path}.guard`;
+	const deadline = performance.now() + (waitForRelease ? 1e3 : 0);
+	for (;;) try {
+		await mkdir(guard);
+		break;
+	} catch (cause) {
+		if (waitForRelease && cause.code === "EEXIST" && performance.now() < deadline) {
+			await setTimeout(10);
+			continue;
+		}
+		throw new Error(`supervisePursuit: cannot mutate ${path}; inspect ${guard} and remove it only after confirming no lock mutation is active`, { cause });
+	}
+	try {
+		return await mutate();
+	} finally {
+		await rmdir(guard);
+	}
+}
+async function removeIfPresent(path) {
+	try {
+		await unlink(path);
+	} catch (error) {
+		if (!isNoEntError(error)) throw error;
+	}
+}
+//#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") throw new Error(`supervisePursuit: ${path} is not a failure record`);
+	return parsed;
+}
+//#endregion
 //#region src/durable/supervise-pursuit.ts
 /** A failed Runtime execution whose complete third-person projection was retained. */
 var SupervisePursuitError = class extends Error {
 	pursuit;
 	observerPath;
-	constructor(cause, pursuit, observerPath) {
+	/** `runDir/failure.json`: the record of this throw. */
+	failurePath;
+	constructor(cause, pursuit, observerPath, failurePath) {
 		super(`supervisePursuit: ${errorMessage(cause)}`, { cause });
 		this.name = "SupervisePursuitError";
 		this.pursuit = pursuit;
 		this.observerPath = observerPath;
+		this.failurePath = failurePath;
 	}
 };
 /**
@@ -755,6 +1072,14 @@ var SupervisePursuitError = class extends Error {
 * Every concrete execution writes only inside its own `runDir`. Cross-run pursuit
 * aggregation is therefore lock-free at the observer layer: reuse `pursuitId` across
 * run directories and let Intelligence join the independently verified projections.
+*
+* The directory's terminal state is recorded beside `observer.jsonl`: `result.json` holds the
+* returned result once the run settles and `failure.json` the most recent throw. A directory
+* whose `result.json` exists refuses re-entry before any compute; a failure record alone does
+* not, because a caller can correct its input and drive the same run again. For the life of the
+* call the directory is held by `supervise.lock`, so a second process on the same directory
+* refuses and names the holder instead of sharing one journal.
+* An abandoned `supervise.lock.guard` requires removal after confirming no lock mutation is active.
 */
 async function supervisePursuit(profile, task, opts) {
 	const pursuitId = opts.pursuitId.trim();
@@ -762,36 +1087,65 @@ async function supervisePursuit(profile, task, opts) {
 	const runDir = opts.runDir.trim();
 	if (runDir.length === 0) throw new TypeError("supervisePursuit: runDir must be non-empty");
 	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 observer = createFileObserverHooks(observerPath, pursuitId);
 	const runId = superviseOptions.runId ?? "supervise";
 	const now = superviseOptions.now ?? Date.now;
-	await observer.journal.appendEvent(rootEvent(pursuitId, runId, "before", now()));
+	const lock = await acquireRunDirectoryLock(runDir, runId, now);
 	try {
-		const result = await supervise(profile, task, {
-			...superviseOptions,
-			hooks: withPursuitContext(pursuitId, composeRuntimeHooks(observer.hooks, hooks))
-		});
+		const settled = await readSettleRecord(runDir);
+		if (settled !== void 0) throw new SettledRunDirectoryError(settlePath, settled.tree.root, runId);
+		const observer = createFileObserverHooks(observerPath, pursuitId);
+		await observer.journal.appendEvent(rootEvent(pursuitId, runId, "before", now()));
+		let result;
+		try {
+			result = await supervise(profile, task, {
+				...superviseOptions,
+				hooks: withPursuitContext(pursuitId, composeRuntimeHooks(observer.hooks, hooks))
+			});
+		} catch (error) {
+			let pursuit;
+			let observerError;
+			try {
+				await observer.journal.appendEvent(rootEvent(pursuitId, runId, "error", now(), {
+					status: "failed",
+					error: errorMessage(error)
+				}));
+				pursuit = projectPursuit(await observer.journal.read());
+			} catch (failure) {
+				observerError = failure;
+			}
+			if (observerError !== void 0 || pursuit === void 0) throw new Error("supervisePursuit: Runtime failed and durable observer completeness could not be proven", { cause: new AggregateError(observerError === void 0 ? [error] : [error, observerError]) });
+			try {
+				await writeFailureRecord(runDir, {
+					runId,
+					pursuitId,
+					at: new Date(now()).toISOString(),
+					error: {
+						name: errorName(error),
+						message: errorMessage(error)
+					}
+				});
+			} catch (recordError) {
+				throw new Error(`supervisePursuit: Runtime failed and the failure record ${failurePath} could not be written`, { cause: new AggregateError([error, recordError]) });
+			}
+			throw new SupervisePursuitError(error, pursuit, observerPath, failurePath);
+		}
+		try {
+			await writeSettleRecord(runDir, result);
+		} catch (cause) {
+			throw new Error(`supervisePursuit: Runtime settled but the settle record ${settlePath} could not be written`, { cause });
+		}
 		await observer.journal.appendEvent(rootEvent(pursuitId, runId, "after", now(), { status: "done" }));
 		return Object.freeze({
 			result,
 			pursuit: projectPursuit(await observer.journal.read()),
-			observerPath
+			observerPath,
+			settlePath
 		});
-	} catch (error) {
-		let pursuit;
-		let observerError;
-		try {
-			await observer.journal.appendEvent(rootEvent(pursuitId, runId, "error", now(), {
-				status: "failed",
-				error: errorMessage(error)
-			}));
-			pursuit = projectPursuit(await observer.journal.read());
-		} catch (failure) {
-			observerError = failure;
-		}
-		if (observerError !== void 0 || pursuit === void 0) throw new Error("supervisePursuit: Runtime failed and durable observer completeness could not be proven", { cause: new AggregateError(observerError === void 0 ? [error] : [error, observerError]) });
-		throw new SupervisePursuitError(error, pursuit, observerPath);
+	} finally {
+		await lock.release();
 	}
 }
 function rootEvent(pursuitId, runId, phase, timestamp, payload) {
@@ -808,6 +1162,9 @@ function rootEvent(pursuitId, runId, phase, timestamp, payload) {
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function errorName(error) {
+	return error instanceof Error ? error.name : "NonError";
+}
 //#endregion
 //#region src/durable/supervision-discovery.ts
 /**
@@ -885,6 +1242,6 @@ function compareText(left, right) {
 	return left < right ? -1 : left > right ? 1 : 0;
 }
 //#endregion
-export { FileObserverJournal, SupervisePursuitError, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, supervisePursuit, verifyObserverRecords };
+export { FAILURE_RECORD_FILE, FileObserverJournal, RUN_DIRECTORY_LOCK_FILE, RunDirectoryLockedError, SETTLE_RECORD_FILE, SettledRunDirectoryError, SupervisePursuitError, acquireRunDirectoryLock, createFileObserverHooks, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn, observerRecordDigest, projectPursuit, readFailureRecord, readRunDirectoryLock, readSettleRecord, settleRecordJson, supervisePursuit, verifyObserverRecords };
 
 //# sourceMappingURL=durable.js.map