@tangle-network/agent-knowledge 22.0.7 → 22.0.9

package/dist/{inspect-DOQ_h1p6.js → inspect-CTpCsUB2.js}

@@ -5,10 +5,10 @@ import { contentHash } from "@tangle-network/agent-eval";
 import { z } from "zod";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
-import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, rmdir } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { hostname } from "node:os";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/adapters.ts
 const textSourceAdapter = {
 	id: "text",
@@ -401,6 +401,253 @@ function normalizePagesDirectory(value = DEFAULT_PAGES_DIRECTORY) {
 	return normalized;
 }
 //#endregion
+//#region src/lock-holder.ts
+const DEFAULT_STALE_MS = 9e5;
+/** The lease a caller's `staleMs` resolves to: the default, floored at 5 s. */
+function staleWindow(staleMs) {
+	return Math.max(5e3, staleMs ?? 9e5);
+}
+/** The store's cross-process lock, inside the cache directory. */
+const STORE_LOCK = {
+	directory: "mutation.lock.durable",
+	owner: "mutation.lock.owner.json",
+	guard: "mutation.lock.takeover",
+	noun: "knowledge store lock"
+};
+/** One knowledge-improvement run's lease, inside its run directory. */
+const RUN_LEASE = {
+	directory: "run.lock.durable",
+	owner: "run.lock.owner.json",
+	guard: "run.lock.takeover",
+	noun: "knowledge improvement run lease"
+};
+/** A broken lock directory is renamed to `<lock>.dead-<uuid>` beside it, then removed. */
+const TOMBSTONE_INFIX = ".dead-";
+/** How far before `staleMs` a takeover yields to proper-lockfile's own stale removal. */
+const STALE_MARGIN_MS = 6e4;
+function describeHolder(holder, now = Date.now()) {
+	const heldS = Math.max(0, Math.round((now - holder.since) / 1e3));
+	return `${holder.label} (pid ${holder.pid} on ${holder.host}, holding since ${new Date(holder.since).toISOString()}, ${heldS} s)`;
+}
+let lockfileModule;
+function loadLockfile() {
+	lockfileModule ??= import("proper-lockfile");
+	return lockfileModule;
+}
+/**
+* The OS start token of a live pid, the way agent-runtime's `readProcessStart` reads it: the same
+* for a process's whole life and different for every later holder of its pid. `undefined` when
+* the host cannot report one. `node:child_process` loads lazily because the package root, which
+* Cloudflare consumers bundle, imports this module.
+*/
+async function readProcessStart(pid) {
+	if (!Number.isSafeInteger(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 { execFile } = await import("node:child_process");
+		return (await new Promise((resolve, reject) => execFile("ps", [
+			"-o",
+			"lstart=",
+			"-p",
+			String(pid)
+		], (error, out) => error ? reject(error) : resolve(out)))).trim() || void 0;
+	} catch {
+		return;
+	}
+}
+let ownIdentity;
+function readOwnIdentity() {
+	ownIdentity ??= (async () => {
+		const [processStart, bootId, pidNamespace] = await Promise.all([
+			readProcessStart(process.pid),
+			readFile("/proc/sys/kernel/random/boot_id", "utf8").then((text) => text.trim() || void 0, () => void 0),
+			readlink("/proc/self/ns/pid").catch(() => void 0)
+		]);
+		return {
+			...processStart ? { processStart } : {},
+			...bootId ? { bootId } : {},
+			...pidNamespace ? { pidNamespace } : {}
+		};
+	})();
+	return ownIdentity;
+}
+async function readLockDirectoryIdentity(cacheDir, held) {
+	try {
+		const entry = await lstat(join(cacheDir, held.directory), { bigint: true });
+		if (!entry.isDirectory()) return void 0;
+		return {
+			dev: entry.dev.toString(),
+			ino: entry.ino.toString(),
+			birthtimeNs: entry.birthtimeNs.toString()
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* Record who holds the file lock, and which lock directory, inside the directory that holds it.
+* Call it right after acquiring. Exported for the confinement tests; src/index.ts does not
+* re-export it.
+*/
+async function recordLockOwner(cacheDir, label, held = STORE_LOCK) {
+	try {
+		const [identity, lock] = await Promise.all([readOwnIdentity(), readLockDirectoryIdentity(cacheDir, held)]);
+		const owner = {
+			label,
+			pid: process.pid,
+			host: hostname(),
+			since: Date.now(),
+			...identity,
+			...lock ? { lock } : {}
+		};
+		await writeJsonDurableWithinRoot(cacheDir, held.owner, owner);
+	} catch {}
+}
+/**
+* `cacheDir` is withSafeDirectory's anchored path, so only the owner file itself can be swapped.
+* Anyone who can write the cache directory can plant a FIFO there, so the open adds O_NONBLOCK
+* and fstat refuses it. The shared readRegularFileNoFollow stays blocking: the event store and
+* file transactions read through it, and their descriptor use must not change.
+*
+* The old shape `{ label, pid, host, since }` still parses. A newer field that is missing or
+* malformed is dropped, which leaves the holder named but never provably dead.
+*/
+async function readLockOwner(cacheDir, held = STORE_LOCK) {
+	let handle;
+	try {
+		handle = await open(join(cacheDir, held.owner), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		if (!(await handle.stat()).isFile()) return void 0;
+		const value = JSON.parse(await handle.readFile("utf8"));
+		if (typeof value?.label !== "string" || !Number.isSafeInteger(value.pid) || typeof value.host !== "string" || typeof value.since !== "number" || Number.isNaN(new Date(value.since).getTime())) return;
+		const text = (field) => typeof field === "string" && field.length > 0 ? field : void 0;
+		const lock = value.lock;
+		const decimal = (field) => typeof field === "string" && /^\d+$/u.test(field);
+		const processStart = text(value.processStart);
+		const bootId = text(value.bootId);
+		const pidNamespace = text(value.pidNamespace);
+		return {
+			label: value.label,
+			pid: value.pid,
+			host: value.host,
+			since: value.since,
+			...processStart ? { processStart } : {},
+			...bootId ? { bootId } : {},
+			...pidNamespace ? { pidNamespace } : {},
+			...lock && decimal(lock.dev) && decimal(lock.ino) && decimal(lock.birthtimeNs) ? { lock: {
+				dev: lock.dev,
+				ino: lock.ino,
+				birthtimeNs: lock.birthtimeNs
+			} } : {}
+		};
+	} catch {
+		return;
+	} finally {
+		await handle?.close().catch(() => void 0);
+	}
+}
+/** Only ESRCH proves a pid gone; EPERM means it exists under another user. */
+function pidIsGone(pid) {
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch (error) {
+		return error.code === "ESRCH";
+	}
+}
+/**
+* The holder of the current lock, when its record proves it dead; otherwise `undefined`,
+* and the caller keeps the `staleMs` lease. Proof needs a record with every identity field,
+* written for this very lock directory (dev, ino and a nonzero birthtime), on this host and pid
+* namespace, and then a rebooted host, a gone pid, or a pid whose start token changed. Anything
+* else is unknown, so a live holder's lease is never shortened.
+*/
+async function holderIsProvablyDead(cacheDir, held = STORE_LOCK) {
+	const holder = await readLockOwner(cacheDir, held);
+	if (!holder?.processStart || !holder.lock || holder.pid <= 0) return void 0;
+	const lock = await readLockDirectoryIdentity(cacheDir, held);
+	if (!lock || lock.birthtimeNs === "0" || lock.dev !== holder.lock.dev || lock.ino !== holder.lock.ino || lock.birthtimeNs !== holder.lock.birthtimeNs || holder.host !== hostname()) return;
+	const own = await readOwnIdentity();
+	if (holder.pidNamespace !== own.pidNamespace) return void 0;
+	if (holder.bootId === void 0 !== (own.bootId === void 0)) return void 0;
+	if (holder.bootId !== own.bootId) return {
+		holder,
+		lock,
+		reason: "host rebooted"
+	};
+	if (pidIsGone(holder.pid)) return {
+		holder,
+		lock,
+		reason: "pid gone"
+	};
+	const start = await readProcessStart(holder.pid);
+	if (start !== void 0 && start !== holder.processStart) return {
+		holder,
+		lock,
+		reason: "pid reused"
+	};
+}
+/**
+* Break the lock of a provably dead holder, and report whether this call broke it. The
+* guard is proper-lockfile itself: a taker that finds it held breaks nothing and returns to its
+* wait, because another taker is already breaking the lock. Its target is the guard path, not the
+* locked target, because proper-lockfile keys its held locks by target and a second lock on that
+* target would replace this process's entry for it and break that lock's heartbeat and release.
+*
+* proper-lockfile's own stale removal does not take the guard. Once the lock directory's mtime is
+* near `staleMs`, another process may remove it as stale and create its own between our re-check
+* and our rename, so that lock is left to the stale path, which frees it within the margin.
+*/
+async function takeOverDeadHolder(cacheDir, staleMs, held = STORE_LOCK) {
+	if (!await holderIsProvablyDead(cacheDir, held)) return false;
+	const { lock } = await loadLockfile();
+	const guard = join(cacheDir, held.guard);
+	let release;
+	try {
+		release = await lock(guard, {
+			lockfilePath: guard,
+			realpath: false,
+			stale: 3e4,
+			retries: 0,
+			onCompromised: () => void 0
+		});
+	} catch (error) {
+		if (error.code === "ELOCKED") return false;
+		throw error;
+	}
+	try {
+		const dead = await holderIsProvablyDead(cacheDir, held);
+		if (!dead) return false;
+		const lockDirectory = join(cacheDir, held.directory);
+		const { mtimeMs } = await lstat(lockDirectory);
+		const stale = staleWindow(staleMs);
+		if (Date.now() - mtimeMs >= stale - Math.min(STALE_MARGIN_MS, stale / 3)) return false;
+		const tombstone = `${lockDirectory}${TOMBSTONE_INFIX}${randomUUID()}`;
+		try {
+			await rename(lockDirectory, tombstone);
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+		for (const entry of await readdir(cacheDir).catch(() => [])) if (entry.startsWith(`${held.directory}${TOMBSTONE_INFIX}`)) await rmdir(join(cacheDir, entry)).catch(() => void 0);
+		process.emitWarning(`took over the ${held.noun} of a dead holder, ${describeHolder(dead.holder)}: ${dead.reason}`, {
+			type: "AgentKnowledgeRecovery",
+			code: "AGENT_KNOWLEDGE_LOCK_TAKEOVER"
+		});
+		return true;
+	} finally {
+		await release().catch(() => void 0);
+	}
+}
+//#endregion
 //#region src/bounded-file-io.ts
 /** Keep filesystem descriptors bounded and drain a failed batch before its owner releases handles. */
 async function mapFileIo(values, operation) {
@@ -884,7 +1131,6 @@ function fileMatches(file, hash, mode) {
 }
 //#endregion
 //#region src/mutation-lock.ts
-const DEFAULT_STALE_MS = 9e5;
 const DEFAULT_READ_WAIT_MS = 25;
 const MAX_POLL_MS = 250;
 function sleep(ms) {
@@ -907,18 +1153,18 @@ const WRITER_WAIT_MS = DEFAULT_STALE_MS;
 * A read changes nothing, so failing one loses no work, which is why it waits less than a writer.
 */
 const READER_WAIT_MS = 12e4;
+/** Purpose prefix of a proposal write; its purpose hashes the exact proposal. */
+const KNOWLEDGE_PROPOSAL_PURPOSE_PREFIX = "knowledge-proposal:";
 /**
-* Purpose prefix of a proposal write. Its purpose hashes the exact proposal, so only a byte-identical
-* retry could resume it, and a writer killed mid-proposal never told its caller it succeeded. Found
-* under the exclusive lock with no recovery owner, such a transaction is abandoned and rolls back
-* instead of refusing every later reader and writer of the store.
+* A pending transaction with no recovery owner, found by a caller that holds the exclusive lock
+* and is not resuming that purpose. The transaction belongs to the lock hold that opened it, and
+* holding the lock now proves that hold ended: released on an error or exit, expired, or broken
+* because its holder was provably dead. Its caller never saw success, so rolling it back leaves
+* the store as that caller last saw it, and an identical retry still writes cleanly.
 */
-const KNOWLEDGE_PROPOSAL_PURPOSE_PREFIX = "knowledge-proposal:";
-function isAbandonedProposal(pending) {
-	return pending.purpose.startsWith("knowledge-proposal:") && !pending.recoveryOwner;
+function isAbandonedTransaction(pending, resumingPurpose) {
+	return !pending.recoveryOwner && pending.purpose !== resumingPurpose;
 }
-/** Diagnostic record of the current cross-process holder, read only to name it in a timeout. */
-const LOCK_OWNER_FILE = "mutation.lock.owner.json";
 const holderLabels = new AsyncLocalStorage();
 /**
 * Name the store mutations `body` performs, so a writer or reader that times out behind them can
@@ -927,18 +1173,9 @@ const holderLabels = new AsyncLocalStorage();
 function withKnowledgeMutationLabel(label, body) {
 	return holderLabels.run(label, body);
 }
-function describeHolder(holder, now = Date.now()) {
-	const heldS = Math.max(0, Math.round((now - holder.since) / 1e3));
-	return `${holder.label} (pid ${holder.pid} on ${holder.host}, holding since ${new Date(holder.since).toISOString()}, ${heldS} s)`;
-}
 function seconds(ms) {
 	return `${Math.round(ms / 100) / 10} s`;
 }
-let lockfileModule;
-function loadLockfile() {
-	lockfileModule ??= import("proper-lockfile");
-	return lockfileModule;
-}
 const activeRoots = new AsyncLocalStorage();
 const activeReadRoots = new AsyncLocalStorage();
 const gates = /* @__PURE__ */ new Map();
@@ -1092,7 +1329,7 @@ async function withKnowledgeMutation(root, mutate, options = {}) {
 * fixed number of attempts delays a write instead of failing it.
 */
 async function acquireStoreLock(root, cacheDir, options) {
-	const lockfilePath = join(cacheDir, "mutation.lock.durable");
+	const lockfilePath = join(cacheDir, STORE_LOCK.directory);
 	const deadline = options.started + WRITER_WAIT_MS;
 	let pause = 10;
 	for (;;) try {
@@ -1102,6 +1339,7 @@ async function acquireStoreLock(root, cacheDir, options) {
 			retries: options.retries ?? 0
 		});
 	} catch (error) {
+		if (isLocked(error) && await takeOverDeadHolder(cacheDir, options.staleMs)) continue;
 		const remaining = deadline - performance.now();
 		if (options.retries !== void 0 || error.code !== "ELOCKED" || remaining <= 0) throw await namedLockError(error, root, cacheDir, performance.now() - options.started);
 		await sleep(Math.min(remaining, pause * (.5 + Math.random())));
@@ -1110,43 +1348,12 @@ async function acquireStoreLock(root, cacheDir, options) {
 }
 /** A contended file lock, restated with the holder its owner record names. */
 async function namedLockError(error, root, cacheDir, waitedMs) {
-	if (error?.code !== "ELOCKED") return error;
+	if (!isLocked(error)) return error;
 	const owner = await readLockOwner(cacheDir);
 	return Object.assign(new Error(`knowledge store is locked by another process: ${root}; waited ${seconds(waitedMs)} for ${owner ? describeHolder(owner) : "a holder that recorded no owner"}`, { cause: error }), { code: "ELOCKED" });
 }
-/**
-* Record who holds the file lock, for a waiter's timeout, inside the store's confinement.
-* Exported for the confinement tests only; src/index.ts does not re-export it.
-*/
-async function recordLockOwner(cacheDir, label) {
-	const owner = {
-		label,
-		pid: process.pid,
-		host: hostname(),
-		since: Date.now()
-	};
-	try {
-		await writeJsonDurableWithinRoot(cacheDir, LOCK_OWNER_FILE, owner);
-	} catch {}
-}
-/**
-* `cacheDir` is withSafeDirectory's anchored path, so only the owner file itself can be swapped.
-* Anyone who can write the cache directory can plant a FIFO there, so the open adds O_NONBLOCK
-* and fstat refuses it. The shared readRegularFileNoFollow stays blocking: the event store and
-* file transactions read through it, and their descriptor use must not change.
-*/
-async function readLockOwner(cacheDir) {
-	let handle;
-	try {
-		handle = await open(join(cacheDir, LOCK_OWNER_FILE), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-		if (!(await handle.stat()).isFile()) return void 0;
-		const value = JSON.parse(await handle.readFile("utf8"));
-		return typeof value.label === "string" && Number.isSafeInteger(value.pid) && typeof value.host === "string" && Number.isFinite(value.since) && !Number.isNaN(new Date(value.since).getTime()) ? value : void 0;
-	} catch {
-		return;
-	} finally {
-		await handle?.close().catch(() => void 0);
-	}
+function isLocked(error) {
+	return error?.code === "ELOCKED";
 }
 function noRetries(retries) {
 	return retries === 0 || typeof retries === "object" && !Array.isArray(retries) && retries.retries === 0;
@@ -1163,6 +1370,8 @@ function noRetries(retries) {
 * an externally held lock carries the same guarantee and not a weaker one. Entering a scope for a
 * lock the caller does not actually hold is the one way to defeat the store's single-writer rule;
 * the hold is required, rather than assumed, so that is a statement the caller has to make.
+* Holding it also authorizes rolling back a pending transaction with no recovery owner, as every
+* holder of the store lock does.
 */
 async function runInKnowledgeMutationScope(root, hold, body, options = {}) {
 	const resolvedRoot = resolve(root);
@@ -1197,7 +1406,8 @@ async function runOwnedMutation(resolvedRoot, cacheDir, hold, options, mutate) {
 			transactionRoot: mutationLock.transactionRoot
 		});
 		const pending = pendingState?.transaction ?? null;
-		const resume = pending ? assertKnowledgeTransactionResume(pending, options.resumeTransaction) : void 0;
+		const abandoned = pending !== null && isAbandonedTransaction(pending, options.resumeTransaction?.purpose);
+		const resume = pending && !abandoned ? assertKnowledgeTransactionResume(pending, options.resumeTransaction) : void 0;
 		const locks = new Map(activeRoots.getStore());
 		locks.set(resolvedRoot, scope);
 		return await activeRoots.run(locks, async () => {
@@ -1212,8 +1422,8 @@ async function runOwnedMutation(resolvedRoot, cacheDir, hold, options, mutate) {
 				if (!stillPending) await finishMutationEpoch(cacheDir, epoch);
 			};
 			try {
-				if (pending) {
-					if (!resume) throw new Error(`knowledge transaction '${pending.purpose}' requires its owner to resume`);
+				if (pending && abandoned) await rollBackAbandonedTransaction(resolvedRoot, mutationLock.transactionRoot, pending, mutationLock.assertOwned);
+				else if (pending && resume) {
 					await recoverKnowledgeFileTransaction({
 						root: resolvedRoot,
 						transactionRoot: mutationLock.transactionRoot,
@@ -1265,20 +1475,32 @@ async function inspectPendingKnowledgeMutation(root) {
 		paths: transaction.entries.map((entry) => entry.path)
 	};
 }
+/** Called once the abandoned case is excluded, so a mismatched purpose names a recovery owner. */
 function assertKnowledgeTransactionResume(pending, resume) {
-	if (!resume || pending.purpose !== resume.purpose) {
-		if (isAbandonedProposal(pending)) return {
-			purpose: pending.purpose,
-			direction: "rollback"
-		};
-		throw new Error(`knowledge transaction '${pending.purpose}' requires its owner to resume`);
-	}
-	if (pending.recoveryOwner !== resume.recoveryOwner) {
-		if (pending.recoveryOwner) throw new Error(`knowledge transaction '${pending.purpose}' must be resumed by '${pending.recoveryOwner}'`);
-		throw new Error(`knowledge transaction '${pending.purpose}' has no recovery owner`);
-	}
+	if (!resume || pending.purpose !== resume.purpose || pending.recoveryOwner && pending.recoveryOwner !== resume.recoveryOwner) throw ownerResumeRefusal(pending);
+	if (pending.recoveryOwner !== resume.recoveryOwner) throw new Error(`knowledge transaction '${pending.purpose}' has no recovery owner`);
 	return resume;
 }
+/** The refusal every reader and writer meets while an owned transaction is pending. */
+function ownerResumeRefusal(pending) {
+	const owner = pending.recoveryOwner ?? "its recovery owner";
+	const transition = pending.purpose.startsWith("knowledge-promotion:") ? "promoteKnowledgeCandidate" : pending.purpose.startsWith("knowledge-restore:") ? "restoreKnowledgeCandidateBaseline" : void 0;
+	const resumeCall = transition ? `re-run ${transition} with the same candidate${owner.startsWith("knowledge-improvement-activation:") ? " and the same activation" : ""}` : `re-run the call that owns '${owner}' with the same purpose`;
+	return /* @__PURE__ */ new Error(`knowledge transaction '${pending.purpose}' requires its owner to resume: it must be resumed by '${owner}' (transaction ${pending.transactionId}, created ${pending.createdAt}); ${resumeCall}`);
+}
+async function rollBackAbandonedTransaction(root, transactionRoot, pending, assertOwned) {
+	await recoverKnowledgeFileTransaction({
+		root,
+		transactionRoot,
+		expectedPurpose: pending.purpose,
+		direction: "rollback",
+		assertOwned
+	});
+	process.emitWarning(`rolled back abandoned knowledge transaction ${pending.transactionId} ('${pending.purpose}', created ${pending.createdAt}): its writer ended without success and named no recovery owner`, {
+		type: "AgentKnowledgeRecovery",
+		code: "AGENT_KNOWLEDGE_TRANSACTION_ROLLBACK"
+	});
+}
 async function recoverPendingKnowledgeMutation(root, options) {
 	const pending = await inspectPendingKnowledgeMutation(root);
 	if (!pending) throw new Error("knowledge base has no pending mutation");
@@ -1341,7 +1563,7 @@ async function describeWriter(root) {
 	return owner ? describeHolder(owner) : "a writer that recorded no owner";
 }
 async function acquireDurableFileLock(target, options) {
-	const stale = Math.max(5e3, options.staleMs ?? DEFAULT_STALE_MS);
+	const stale = staleWindow(options.staleMs);
 	const update = Math.max(1e3, Math.floor(stale / 3));
 	let compromised;
 	let released = false;
@@ -1417,17 +1639,17 @@ async function waitForActiveMutationEpoch(root, epoch, options, pauseMs) {
 }
 async function healAbandonedMutationEpoch(root, expectedEpoch, options) {
 	await withSafeDirectory(root, ".agent-knowledge", false, async (cacheDir) => {
-		let acquired;
-		try {
-			acquired = await acquireDurableFileLock(root, {
-				lockfilePath: join(cacheDir, "mutation.lock.durable"),
-				staleMs: options.staleMs,
-				retries: 0
-			});
-		} catch (error) {
-			if (error.code === "ELOCKED") return;
+		const acquire = () => acquireDurableFileLock(root, {
+			lockfilePath: join(cacheDir, STORE_LOCK.directory),
+			staleMs: options.staleMs,
+			retries: 0
+		}).catch((error) => {
+			if (isLocked(error)) return void 0;
 			throw error;
-		}
+		});
+		const acquired = await acquire() ?? (await takeOverDeadHolder(cacheDir, options.staleMs) ? await acquire() : void 0);
+		if (!acquired) return;
+		await recordLockOwner(cacheDir, "heal of an abandoned mutation epoch");
 		try {
 			const currentEpoch = await readMutationEpochFromCache(cacheDir);
 			if (currentEpoch !== expectedEpoch || !isOdd(currentEpoch)) return;
@@ -1435,14 +1657,8 @@ async function healAbandonedMutationEpoch(root, expectedEpoch, options) {
 				root,
 				transactionRoot: join(cacheDir, "file-transactions")
 			});
-			if (pending && isAbandonedProposal(pending.transaction)) await recoverKnowledgeFileTransaction({
-				root,
-				transactionRoot: join(cacheDir, "file-transactions"),
-				expectedPurpose: pending.transaction.purpose,
-				direction: "rollback",
-				assertOwned: () => acquired.assertOwned()
-			});
-			else if (pending) throw new Error(`knowledge transaction '${pending.transaction.purpose}' requires its owner to resume`);
+			if (pending && isAbandonedTransaction(pending.transaction)) await rollBackAbandonedTransaction(root, join(cacheDir, "file-transactions"), pending.transaction, () => acquired.assertOwned());
+			else if (pending) throw ownerResumeRefusal(pending.transaction);
 			await finishMutationEpoch(cacheDir, currentEpoch);
 		} finally {
 			await acquired.release();
@@ -1452,11 +1668,11 @@ async function healAbandonedMutationEpoch(root, expectedEpoch, options) {
 async function hasActiveMutationLock(root, options) {
 	try {
 		const { check } = await loadLockfile();
-		return await withSafeDirectory(root, ".agent-knowledge", false, (cacheDir) => check(root, {
-			lockfilePath: join(cacheDir, "mutation.lock.durable"),
+		return await withSafeDirectory(root, ".agent-knowledge", false, async (cacheDir) => await check(root, {
+			lockfilePath: join(cacheDir, STORE_LOCK.directory),
 			realpath: false,
-			stale: Math.max(5e3, options.staleMs ?? DEFAULT_STALE_MS)
-		}));
+			stale: staleWindow(options.staleMs)
+		}) && !await holderIsProvablyDead(cacheDir));
 	} catch (error) {
 		if (isMissingFile(error)) return false;
 		throw error;
@@ -5042,6 +5258,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { loadSourceRegistry as $, mediaTypeFor$1 as $n, KNOWLEDGE_EVENT_TYPES as $t, validateKnowledgePage as A, finishKnowledgeFileTransaction as An, isScaffoldPath as At, CHECKABLE_RUNG_THRESHOLD as B, listRegularFilesWithinRoot as Bn, KnowledgeEventSchema as Bt, immutablePageDigest as C, runInKnowledgeMutationScope as Cn, resolveKnowledgeCitation as Ct, normalizeVisibilityArtifact as D, applyKnowledgeFileTransaction as Dn, SCAFFOLD_PAGE_BASENAMES as Dt, nonEmpty as E, withKnowledgeRead as En, resolveRunScopedCitations as Et, detectNearDuplicatePages as F, normalizePagesDirectory as Fn, WIKILINK_REGEX as Ft, gradeClaims as G, renameDurable as Gn, KnowledgePageSchema as Gt, UncheckableClaimError as H, readRegularFileWithinRoot as Hn, KnowledgeGraphNodeSchema as Ht, normalizePageText as I, canonicalPathsEqual as In, extractWikilinks as It, verifyGradeableEvidence as J, withSafeDirectory as Jn, ResearchClaimLedgerSchema as Jt, gradeFor as K, syncDirectory as Kn, KnowledgeRelationSchema as Kt, prepareKnowledgeValidation as L, canonicalRelativeWithinRoot as Ln, normalizeLinkTarget as Lt, verifyKnowledgeVisibilitySnapshot as M, prepareKnowledgeFileTransaction as Mn, layoutFor as Mt, visibilityIdentity as N, rollbackKnowledgeFileTransaction as Nn, loadKnowledgePages as Nt, normalizeVisibilityRef as O, assertKnowledgeMutationPath as On, initKnowledgeBase as Ot, visibilityIndexOf as P, DEFAULT_PAGES_DIRECTORY as Pn, writeJson as Pt, addSourceText as Q, writeJsonDurableWithinRoot as Qn, SourceRecordSchema as Qt, validateKnowledgeIndex as R, isKernelAnchoredPath as Rn, DeepQuestionSchema as Rt, encodeKnowledgeVisibilitySnapshot as S, recoverPendingKnowledgeMutation as Sn, parseKnowledgeCitationReference as St, knowledgeVisibilityArtifactRef as T, withKnowledgeMutationLabel as Tn, resolveRunScopedCitation as Tt, assertGradeableEvidence as U, relativeWithinRoot as Un, KnowledgeIndexSchema as Ut, DEADLINE_EXIT_CODE as V, readRegularFileNoFollow as Vn, KnowledgeGraphEdgeSchema as Vt, claimCheckKey as W, removeDurable as Wn, KnowledgePageInvalidationSchema as Wt, writeKnowledgeIndex as X, writeFileDurableWithinRoot as Xn, ResearchSourceVersionSchema as Xt, buildKnowledgeIndex as Y, writeFileDurable as Yn, ResearchClaimRecordSchema as Yt, addSourcePath as Z, writeJsonDurable as Zn, SourceAnchorSchema as Zt, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION as _, parseFrontmatter as _n, assertKnowledgeCitationsResolved as _t, applyKnowledgeWriteBlocksFile as a, claimEvidenceId as an, KB_CLAIM_LEDGER_DIR as at, decodeKnowledgeVisibilitySnapshot as b, isKnowledgeMutationHeld as bn, auditKnowledgeCitations as bt, KnowledgeDuplicateIntakeError as c, deepQuestionId as cn, KB_STORE_DIR as ct, createFileRunLineageAuthority as d, materializeRegisteredClaimEvidence as dn, buildKnowledgeGraph as dt, ClaimLedgerGoalConflictError as en, textSourceAdapter as er, snapshotSourceTextInput as et, createRunScopedStores as f, mergeClaimLedgers as fn, knowledgePageRelations as ft, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM as g, formatFrontmatter as gn, assertKnowledgeCitationAudit as gt, originatedPages as h, researchSourceVersionKey as hn, assertCurrentRunCitationsResolved as ht, applyKnowledgeWriteBlocks as i, assertTrackedClaimIntegrity as in, FileSystemKbStore as it, validateOrigin as j, knowledgeFileTransactionPlanHash as jn, knowledgePageFromMarkdown as jt, snapshotImmutableVisibility as k, commitKnowledgeFileMutations as kn, isKnowledgePagePath as kt, assertKnowledgeWriteIntake as l, emptyClaimLedger as ln, MemoryKbStore as lt, loadKnowledgeToolChain as m, normalizeClaimText as mn, KnowledgeCitationResolutionError as mt, inspectKnowledgeIndex as n, assertResearchClaimEvidenceIntegrity as nn, writeSourceRegistry as nt, isSafeKnowledgePath as o, claimId as on, KB_EVENTS_PATH as ot, isKnowledgeToolChain as p, mergeTrackedClaims as pn, KnowledgeCitationAuditError as pt, verdictFor as q, withSafeDescendant as qn, ResearchClaimEvidenceSchema as qt, stringMetadata as r, assertResearchClaimLedgerIntegrity as rn, ClaimLedgerMigrationRequiredError as rt, parseKnowledgeWriteBlocks as s, claimSourceHost as sn, KB_INDEX_PATH as st, explainKnowledgeTarget as t, assertDeepQuestionIntegrity as tn, sourceRegistryPath as tt, RUN_LINEAGE_BASENAME as u, linkClaimContradictions as un, assertClaimLedgerId as ut, assertSchemaVersion as v, acquireDurableFileLock as vn, assertRunScopedCitationsResolved as vt, knowledgePageDigest as w, withKnowledgeMutation as wn, resolveKnowledgeCitations as wt, digest as x, measureKnowledgeMutation as xn, formatKnowledgeCitationReference as xt, createKnowledgeVisibilitySnapshot as y, inspectPendingKnowledgeMutation as yn, auditCurrentRunCitations as yt, lintKnowledgeIndex as z, isMissingFile as zn, KnowledgeBaseCandidateSchema as zt };
+export { loadSourceRegistry as $, writeFileDurableWithinRoot as $n, KNOWLEDGE_EVENT_TYPES as $t, validateKnowledgePage as A, finishKnowledgeFileTransaction as An, isScaffoldPath as At, CHECKABLE_RUNG_THRESHOLD as B, canonicalRelativeWithinRoot as Bn, KnowledgeEventSchema as Bt, immutablePageDigest as C, runInKnowledgeMutationScope as Cn, resolveKnowledgeCitation as Ct, normalizeVisibilityArtifact as D, applyKnowledgeFileTransaction as Dn, SCAFFOLD_PAGE_BASENAMES as Dt, nonEmpty as E, withKnowledgeRead as En, resolveRunScopedCitations as Et, detectNearDuplicatePages as F, recordLockOwner as Fn, WIKILINK_REGEX as Ft, gradeClaims as G, readRegularFileWithinRoot as Gn, KnowledgePageSchema as Gt, UncheckableClaimError as H, isMissingFile as Hn, KnowledgeGraphNodeSchema as Ht, normalizePageText as I, takeOverDeadHolder as In, extractWikilinks as It, verifyGradeableEvidence as J, renameDurable as Jn, ResearchClaimLedgerSchema as Jt, gradeFor as K, relativeWithinRoot as Kn, KnowledgeRelationSchema as Kt, prepareKnowledgeValidation as L, DEFAULT_PAGES_DIRECTORY as Ln, normalizeLinkTarget as Lt, verifyKnowledgeVisibilitySnapshot as M, prepareKnowledgeFileTransaction as Mn, layoutFor as Mt, visibilityIdentity as N, rollbackKnowledgeFileTransaction as Nn, loadKnowledgePages as Nt, normalizeVisibilityRef as O, assertKnowledgeMutationPath as On, initKnowledgeBase as Ot, visibilityIndexOf as P, RUN_LEASE as Pn, writeJson as Pt, addSourceText as Q, writeFileDurable as Qn, SourceRecordSchema as Qt, validateKnowledgeIndex as R, normalizePagesDirectory as Rn, DeepQuestionSchema as Rt, encodeKnowledgeVisibilitySnapshot as S, recoverPendingKnowledgeMutation as Sn, parseKnowledgeCitationReference as St, knowledgeVisibilityArtifactRef as T, withKnowledgeMutationLabel as Tn, resolveRunScopedCitation as Tt, assertGradeableEvidence as U, listRegularFilesWithinRoot as Un, KnowledgeIndexSchema as Ut, DEADLINE_EXIT_CODE as V, isKernelAnchoredPath as Vn, KnowledgeGraphEdgeSchema as Vt, claimCheckKey as W, readRegularFileNoFollow as Wn, KnowledgePageInvalidationSchema as Wt, writeKnowledgeIndex as X, withSafeDescendant as Xn, ResearchSourceVersionSchema as Xt, buildKnowledgeIndex as Y, syncDirectory as Yn, ResearchClaimRecordSchema as Yt, addSourcePath as Z, withSafeDirectory as Zn, SourceAnchorSchema as Zt, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION as _, parseFrontmatter as _n, assertKnowledgeCitationsResolved as _t, applyKnowledgeWriteBlocksFile as a, claimEvidenceId as an, KB_CLAIM_LEDGER_DIR as at, decodeKnowledgeVisibilitySnapshot as b, isKnowledgeMutationHeld as bn, auditKnowledgeCitations as bt, KnowledgeDuplicateIntakeError as c, deepQuestionId as cn, KB_STORE_DIR as ct, createFileRunLineageAuthority as d, materializeRegisteredClaimEvidence as dn, buildKnowledgeGraph as dt, ClaimLedgerGoalConflictError as en, writeJsonDurable as er, snapshotSourceTextInput as et, createRunScopedStores as f, mergeClaimLedgers as fn, knowledgePageRelations as ft, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM as g, formatFrontmatter as gn, assertKnowledgeCitationAudit as gt, originatedPages as h, researchSourceVersionKey as hn, assertCurrentRunCitationsResolved as ht, applyKnowledgeWriteBlocks as i, assertTrackedClaimIntegrity as in, FileSystemKbStore as it, validateOrigin as j, knowledgeFileTransactionPlanHash as jn, knowledgePageFromMarkdown as jt, snapshotImmutableVisibility as k, commitKnowledgeFileMutations as kn, isKnowledgePagePath as kt, assertKnowledgeWriteIntake as l, emptyClaimLedger as ln, MemoryKbStore as lt, loadKnowledgeToolChain as m, normalizeClaimText as mn, KnowledgeCitationResolutionError as mt, inspectKnowledgeIndex as n, assertResearchClaimEvidenceIntegrity as nn, mediaTypeFor$1 as nr, writeSourceRegistry as nt, isSafeKnowledgePath as o, claimId as on, KB_EVENTS_PATH as ot, isKnowledgeToolChain as p, mergeTrackedClaims as pn, KnowledgeCitationAuditError as pt, verdictFor as q, removeDurable as qn, ResearchClaimEvidenceSchema as qt, stringMetadata as r, assertResearchClaimLedgerIntegrity as rn, textSourceAdapter as rr, ClaimLedgerMigrationRequiredError as rt, parseKnowledgeWriteBlocks as s, claimSourceHost as sn, KB_INDEX_PATH as st, explainKnowledgeTarget as t, assertDeepQuestionIntegrity as tn, writeJsonDurableWithinRoot as tr, sourceRegistryPath as tt, RUN_LINEAGE_BASENAME as u, linkClaimContradictions as un, assertClaimLedgerId as ut, assertSchemaVersion as v, acquireDurableFileLock as vn, assertRunScopedCitationsResolved as vt, knowledgePageDigest as w, withKnowledgeMutation as wn, resolveKnowledgeCitations as wt, digest as x, measureKnowledgeMutation as xn, formatKnowledgeCitationReference as xt, createKnowledgeVisibilitySnapshot as y, inspectPendingKnowledgeMutation as yn, auditCurrentRunCitations as yt, lintKnowledgeIndex as z, canonicalPathsEqual as zn, KnowledgeBaseCandidateSchema as zt };
 
-//# sourceMappingURL=inspect-DOQ_h1p6.js.map
+//# sourceMappingURL=inspect-CTpCsUB2.js.map