@tangle-network/agent-knowledge 17.1.10 → 19.0.0

package/dist/index.js

@@ -1,13 +1,14 @@
-import { $ as formatKnowledgeCitationReference, $t as inspectPendingKnowledgeMutation, A as addSourceText, An as writeJsonDurableWithinRoot, At as ResearchSourceVersionSchema, B as KB_STORE_DIR, Bt as claimId, C as gradeClaims, Cn as renameDurable, Ct as KnowledgePageSchema, D as buildKnowledgeIndex, Dn as writeFileDurable, Dt as ResearchClaimEvidenceSchema, E as verifyGradeableEvidence, En as withSafeDirectory, Et as KnowledgeRelationSchema, F as ClaimLedgerMigrationRequiredError, Ft as assertDeepQuestionIntegrity, G as KnowledgeCitationAuditError, Gt as materializeRegisteredClaimEvidence, H as assertClaimLedgerId, Ht as deepQuestionId, I as FileSystemKbStore, It as assertResearchClaimEvidenceIntegrity, J as assertKnowledgeCitationAudit, Jt as normalizeClaimText, K as KnowledgeCitationResolutionError, Kt as mergeClaimLedgers, L as KB_CLAIM_LEDGER_DIR, Lt as assertResearchClaimLedgerIntegrity, M as snapshotSourceTextInput, Mn as textSourceAdapter, Mt as SourceRecordSchema, N as sourceRegistryPath, Nt as KNOWLEDGE_EVENT_TYPES, O as writeKnowledgeIndex, On as writeFileDurableWithinRoot, Ot as ResearchClaimLedgerSchema, P as writeSourceRegistry, Pt as ClaimLedgerGoalConflictError, Q as auditKnowledgeCitations, Qt as acquireDurableFileLock, R as KB_EVENTS_PATH, Rt as assertTrackedClaimIntegrity, S as claimCheckKey, Sn as removeDurable, St as KnowledgePageInvalidationSchema, T as verdictFor, Tn as withSafeDescendant, Tt as KnowledgeRelationNodeSchema, U as buildKnowledgeGraph, Ut as emptyClaimLedger, V as MemoryKbStore, Vt as claimSourceHost, W as knowledgePageRelations, Wt as linkClaimContradictions, X as assertRunScopedCitationsResolved, Xt as formatFrontmatter, Y as assertKnowledgeCitationsResolved, Yt as researchSourceVersionKey, Z as auditCurrentRunCitations, Zt as parseFrontmatter, _ as lintKnowledgeIndex, _n as isMissingFile, _t as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, an as applyKnowledgeFileTransaction, at as SCAFFOLD_PAGE_BASENAMES, b as UncheckableClaimError, bn as readRegularFileWithinRoot, bt as KnowledgeGraphNodeSchema, c as KnowledgeDuplicateIntakeError, cn as finishKnowledgeFileTransaction, ct as isScaffoldPath, d as createFileRunLineageAuthority, dn as rollbackKnowledgeFileTransaction, dt as loadKnowledgePages, en as isKnowledgeMutationHeld, et as parseKnowledgeCitationReference, f as createRunScopedStores, fn as DEFAULT_PAGES_DIRECTORY, ft as writeJson, g as validateKnowledgeIndex, gn as isKernelAnchoredPath, gt as DeepQuestionSchema, h as normalizePageText, hn as canonicalRelativeWithinRoot, ht as normalizeLinkTarget, i as applyKnowledgeWriteBlocks, in as withKnowledgeRead, it as resolveRunScopedCitations, j as loadSourceRegistry, jn as mediaTypeFor, jt as SourceAnchorSchema, k as addSourcePath, kn as writeJsonDurable, kt as ResearchClaimRecordSchema, l as assertKnowledgeWriteIntake, ln as knowledgeFileTransactionPlanHash, lt as knowledgePageFromMarkdown, m as detectNearDuplicatePages, mn as canonicalPathsEqual, mt as extractWikilinks, n as inspectKnowledgeIndex, nn as runInKnowledgeMutationScope, nt as resolveKnowledgeCitations, o as isSafeKnowledgePath, on as assertKnowledgeMutationPath, ot as initKnowledgeBase, p as originatedPages, pn as normalizePagesDirectory, pt as WIKILINK_REGEX, q as assertCurrentRunCitationsResolved, qt as mergeTrackedClaims, r as stringMetadata, rn as withKnowledgeMutation, rt as resolveRunScopedCitation, s as parseKnowledgeWriteBlocks, sn as commitKnowledgeFileMutations, st as isKnowledgePagePath, t as explainKnowledgeTarget, tn as recoverPendingKnowledgeMutation, tt as resolveKnowledgeCitation, u as RUN_LINEAGE_BASENAME, un as prepareKnowledgeFileTransaction, ut as layoutFor, v as CHECKABLE_RUNG_THRESHOLD, vn as listRegularFilesWithinRoot, vt as KnowledgeEventSchema, w as gradeFor, wn as syncDirectory, wt as KnowledgeRelationGraphSchema, x as assertGradeableEvidence, xn as relativeWithinRoot, xt as KnowledgeIndexSchema, y as DEADLINE_EXIT_CODE, yn as readRegularFileNoFollow, yt as KnowledgeGraphEdgeSchema, z as KB_INDEX_PATH, zt as claimEvidenceId } from "./inspect-DrJnvx5Z.js";
+import { $ as FileSystemKbStore, $t as assertResearchClaimEvidenceIntegrity, A as visibilityIndexOf, An as normalizePagesDirectory, At as WIKILINK_REGEX, B as gradeClaims, Bn as renameDurable, Bt as KnowledgePageSchema, C as nonEmpty$1, Cn as assertKnowledgeMutationPath, Ct as initKnowledgeBase, D as validateOrigin, Dn as prepareKnowledgeFileTransaction, Dt as layoutFor, E as validateKnowledgePage, En as knowledgeFileTransactionPlanHash, Et as knowledgePageFromMarkdown, F as CHECKABLE_RUNG_THRESHOLD, Fn as listRegularFilesWithinRoot, Ft as KnowledgeEventSchema, G as writeKnowledgeIndex, Gn as writeFileDurableWithinRoot, Gt as ResearchClaimLedgerSchema, H as verdictFor, Hn as withSafeDescendant, Ht as KnowledgeRelationNodeSchema, I as DEADLINE_EXIT_CODE, In as readRegularFileNoFollow, It as KnowledgeGraphEdgeSchema, J as loadSourceRegistry, Jn as mediaTypeFor, Jt as SourceAnchorSchema, K as addSourcePath, Kn as writeJsonDurable, Kt as ResearchClaimRecordSchema, L as UncheckableClaimError, Ln as readRegularFileWithinRoot, Lt as KnowledgeGraphNodeSchema, M as normalizePageText, Mn as canonicalRelativeWithinRoot, Mt as normalizeLinkTarget, N as validateKnowledgeIndex, Nn as isKernelAnchoredPath, Nt as DeepQuestionSchema, O as verifyKnowledgeVisibilitySnapshot, On as rollbackKnowledgeFileTransaction, Ot as loadKnowledgePages, P as lintKnowledgeIndex, Pn as isMissingFile, Pt as KnowledgeBaseCandidateSchema, Q as ClaimLedgerMigrationRequiredError, Qt as assertDeepQuestionIntegrity, R as assertGradeableEvidence, Rn as relativeWithinRoot, Rt as KnowledgeIndexSchema, S as knowledgeVisibilityArtifactRef, Sn as applyKnowledgeFileTransaction, St as SCAFFOLD_PAGE_BASENAMES, T as normalizeVisibilityRef, Tn as finishKnowledgeFileTransaction, Tt as isScaffoldPath, U as verifyGradeableEvidence, Un as withSafeDirectory, Ut as KnowledgeRelationSchema, V as gradeFor, Vn as syncDirectory, Vt as KnowledgeRelationGraphSchema, W as buildKnowledgeIndex, Wn as writeFileDurable, Wt as ResearchClaimEvidenceSchema, X as sourceRegistryPath, Xt as KNOWLEDGE_EVENT_TYPES, Y as snapshotSourceTextInput, Yn as textSourceAdapter, Yt as SourceRecordSchema, Z as writeSourceRegistry, Zt as ClaimLedgerGoalConflictError, _ as createKnowledgeVisibilitySnapshot, _n as isKnowledgeMutationHeld, _t as parseKnowledgeCitationReference, a as applyKnowledgeWriteBlocksFile, an as deepQuestionId, at as assertClaimLedgerId, b as encodeKnowledgeVisibilitySnapshot, bn as withKnowledgeMutation, bt as resolveRunScopedCitation, c as KnowledgeDuplicateIntakeError, cn as materializeRegisteredClaimEvidence, ct as KnowledgeCitationAuditError, d as createFileRunLineageAuthority, dn as normalizeClaimText, dt as assertKnowledgeCitationAudit, en as assertResearchClaimLedgerIntegrity, et as KB_CLAIM_LEDGER_DIR, f as createRunScopedStores, fn as researchSourceVersionKey, ft as assertKnowledgeCitationsResolved, g as assertSchemaVersion, gn as inspectPendingKnowledgeMutation, gt as formatKnowledgeCitationReference, h as KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION, hn as acquireDurableFileLock, ht as auditKnowledgeCitations, i as applyKnowledgeWriteBlocks, in as claimSourceHost, it as MemoryKbStore, j as detectNearDuplicatePages, jn as canonicalPathsEqual, jt as extractWikilinks, k as visibilityIdentity, kn as DEFAULT_PAGES_DIRECTORY, kt as writeJson, l as assertKnowledgeWriteIntake, ln as mergeClaimLedgers, lt as KnowledgeCitationResolutionError, m as KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM, mn as parseFrontmatter, mt as auditCurrentRunCitations, n as inspectKnowledgeIndex, nn as claimEvidenceId, nt as KB_INDEX_PATH, o as isSafeKnowledgePath, on as emptyClaimLedger, ot as buildKnowledgeGraph, p as originatedPages, pn as formatFrontmatter, pt as assertRunScopedCitationsResolved, q as addSourceText, qn as writeJsonDurableWithinRoot, qt as ResearchSourceVersionSchema, r as stringMetadata, rn as claimId, rt as KB_STORE_DIR, s as parseKnowledgeWriteBlocks, sn as linkClaimContradictions, st as knowledgePageRelations, t as explainKnowledgeTarget, tn as assertTrackedClaimIntegrity, tt as KB_EVENTS_PATH, u as RUN_LINEAGE_BASENAME, un as mergeTrackedClaims, ut as assertCurrentRunCitationsResolved, v as decodeKnowledgeVisibilitySnapshot, vn as recoverPendingKnowledgeMutation, vt as resolveKnowledgeCitation, w as normalizeVisibilityArtifact, wn as commitKnowledgeFileMutations, wt as isKnowledgePagePath, x as knowledgePageDigest, xn as withKnowledgeRead, xt as resolveRunScopedCitations, y as digest, yn as runInKnowledgeMutationScope, yt as resolveKnowledgeCitations, z as claimCheckKey, zn as removeDurable, zt as KnowledgePageInvalidationSchema } from "./inspect-C6YK7af7.js";
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
-import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-Bn1Xs1hY.js";
+import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-BYWNir2t.js";
 import { C as sleepForMemoryRecovery, F as buildIndustryRagBenchmarkSmokeCases, G as buildRetrievalEvalDispatch, H as createNoopMemoryBenchmarkAdapter, I as respondToIndustryMemoryBenchmarkSmokeCase, J as retrievalConfigSurface, K as partitionRetrievalScenarios, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, S as runBoundedMemoryLifecycle, U as memoryHitToSourceRecord, V as createInMemoryBenchmarkAdapter, W as memoryWriteResultToSourceRecord, X as scoreRetrievalArtifact, Y as retrievalRecallJudge, Z as mean, a as buildKnowledgeBenchmarkScenarios, b as memoryRecoveryDelayMs, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, f as acquireAgentMemoryRunLease, h as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, i as runMemoryAdapterBenchmark, j as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, m as AgentMemoryLifecycleUnsafeError, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, p as AgentMemoryLifecycleTimeoutError, q as retrievalConfigFromSurface, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact, x as resolveMemoryCleanupTimeoutMs, y as createMemoryExecutionPool } from "./benchmarks-B3kU-Yxz.js";
 import { a as buildKnowledgeLexicalIndex, c as tokenizeText, i as searchKnowledgePages, n as reciprocalRankFusion, o as scoreBm25, r as searchKnowledge, s as tokenizeQuery, t as KNOWLEDGE_SEARCH_RETRIEVER_ID } from "./search-Cbyj2shJ.js";
 import { IRS_DIMENSION_HINTS, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from "./sources/index.js";
 import { createHash } from "node:crypto";
+import { TCloudClient, TCloudError } from "@tangle-network/tcloud";
 import { cp, lstat, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { agentImprovementActivationResultSchema, agentImprovementActivationSchema, canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest, sha256Bytes, sha256DigestSchema } from "@tangle-network/agent-interface";
+import { agentImprovementActivationResultSchema, agentImprovementActivationSchema, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest, sha256Bytes, sha256DigestSchema } from "@tangle-network/agent-interface";
 import { acquisitionPlansForKnowledgeGaps, blockingKnowledgeEval, canonicalJson, contentHash, evaluateReleaseConfidence, objectiveEval, scoreKnowledgeReadiness, userQuestionsForKnowledgeGaps, validateRunRecord } from "@tangle-network/agent-eval";
 import { z } from "zod";
 import { surfaceHash } from "@tangle-network/agent-eval/campaign";
@@ -39,10 +40,9 @@ import { pathToFileURL } from "node:url";
 * worker ADDS; the driver GATES. Together they build a cleaner knowledge base
 * than a single agent at the same compute budget.
 *
-* Dependency-free on purpose: it talks to the router over `fetch` directly with
-* the published OpenAI-compatible chat shape and the `/v1/search` shape, so it
-* works whether or not the `tcloud` CLI is installed. Point it at any router by
-* passing `baseUrl`; supply the key via `apiKey` or `TANGLE_API_KEY`.
+* Model and search requests use the published TCloud SDK. Knowledge owns the
+* research policy, not HTTP, bearer headers, retries or provider rate cards.
+* Point it at any router with `baseUrl`; supply `apiKey` or `TANGLE_API_KEY`.
 */
 /** Default router model. Plain id (no namespace) — see CLAUDE/creds notes. */
 const DEFAULT_MODEL = "glm-5.2";
@@ -54,35 +54,7 @@ const DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 * reasoning model never silently yields nothing. (Verified creds note.)
 */
 const MIN_MAX_TOKENS = 1200;
-/** Transient upstream statuses worth a retry (capacity / rate-limit / gateway). */
-const transientStatuses = /* @__PURE__ */ new Set([
-	429,
-	502,
-	503,
-	504
-]);
-/**
-* POST with bounded exponential backoff on transient upstream statuses. Returns
-* the first `res.ok` response, or the LAST response (so the caller throws the
-* real status). A non-transient failure returns immediately — only 502/503/504/
-* 429 are retried. Aborts propagate at once.
-*/
-async function fetchWithRetry(url, init, opts) {
-	let lastRes;
-	for (let attempt = 0; attempt <= opts.maxRetries; attempt += 1) {
-		if (opts.signal?.aborted) throw new RouterError(0, "aborted");
-		const res = await fetch(url, init);
-		if (res.ok || !transientStatuses.has(res.status)) return res;
-		lastRes = res;
-		if (attempt === opts.maxRetries) break;
-		await res.text().catch(() => "");
-		const jitter = opts.retryBaseMs * 2 ** attempt * (.75 + Math.random() * .5);
-		await new Promise((resolve) => setTimeout(resolve, jitter));
-	}
-	if (lastRes) return lastRes;
-	throw new RouterError(0, "fetchWithRetry produced no response");
-}
-/** A small error so a failed router call fails loud rather than returning junk. */
+/** Compatibility error facade. HTTP execution and classification belong to TCloud. */
 var RouterError = class extends Error {
 	status;
 	constructor(status, message) {
@@ -91,26 +63,26 @@ var RouterError = class extends Error {
 		this.name = "RouterError";
 	}
 };
-/**
-* Build a dependency-free Tangle router client over `fetch`. This is the same
-* wire surface the `tcloud` SDK + `tcloud mcp` use (`/v1/search` for web search,
-* `/v1/chat/completions` for chat) so it needs no CLI installed.
-*/
+/** Adapt Knowledge's public contract to the published SDK, without a second transport. */
 function createTangleRouterClient(options = {}) {
-	const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
 	const apiKey = options.apiKey ?? process.env.TANGLE_API_KEY;
 	if (!apiKey) throw new RouterError(401, "no TANGLE_API_KEY (pass apiKey or set the env var)");
-	const model = options.model ?? DEFAULT_MODEL;
-	const maxRetries = Math.max(0, options.maxRetries ?? 4);
-	const retryBaseMs = Math.max(1, options.retryBaseMs ?? 1500);
-	const headers = {
-		"Content-Type": "application/json",
-		Authorization: `Bearer ${apiKey}`
-	};
-	const price = {
-		prompt: .95 / 1e6,
-		completion: 3 / 1e6
-	};
+	const client = new TCloudClient({
+		baseURL: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+		apiKey,
+		model: options.model ?? DEFAULT_MODEL,
+		timeout: 0,
+		retry: {
+			maxRetries: Math.max(0, options.maxRetries ?? 4),
+			initialBackoffMs: Math.max(1, options.retryBaseMs ?? 1500),
+			retryableStatuses: [
+				429,
+				502,
+				503,
+				504
+			]
+		}
+	});
 	const acc = {
 		chatCalls: 0,
 		searchCalls: 0,
@@ -119,70 +91,79 @@ function createTangleRouterClient(options = {}) {
 		usd: 0,
 		wallMs: 0
 	};
+	const recordCost = (cost) => {
+		acc.usd += typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? cost : NaN;
+	};
+	const translate = (error) => {
+		options.signal?.throwIfAborted();
+		if (error instanceof TCloudError) throw new RouterError(error.status, error.message);
+		throw error;
+	};
 	return {
 		async search(query, opts) {
-			const t0 = Date.now();
-			const res = await fetchWithRetry(`${baseUrl}/search`, {
-				method: "POST",
-				headers,
-				signal: options.signal,
-				body: JSON.stringify({
+			options.signal?.throwIfAborted();
+			const started = Date.now();
+			try {
+				const response = await client.search({
 					query,
 					...options.searchProvider ? { provider: options.searchProvider } : {},
-					...opts?.maxResults != null ? { maxResults: opts.maxResults } : {}
-				})
-			}, {
-				maxRetries,
-				retryBaseMs,
-				signal: options.signal
-			});
-			acc.searchCalls += 1;
-			acc.wallMs += Date.now() - t0;
-			if (!res.ok) throw new RouterError(res.status, await res.text().catch(() => res.statusText));
-			return ((await res.json()).data ?? []).filter((hit) => typeof hit?.url === "string" && hit.url.length > 0).map((hit) => ({
-				title: hit.title ?? hit.url,
-				url: hit.url,
-				snippet: hit.snippet
-			}));
+					...opts?.maxResults != null ? { maxResults: opts.maxResults } : {},
+					signal: options.signal
+				});
+				recordCost(response.usage?.billed_cost);
+				return (response.data ?? []).filter((hit) => typeof hit?.url === "string" && hit.url.length > 0).map((hit) => ({
+					title: hit.title ?? hit.url,
+					url: hit.url,
+					snippet: hit.snippet
+				}));
+			} catch (error) {
+				return translate(error);
+			} finally {
+				acc.searchCalls += 1;
+				acc.wallMs += Date.now() - started;
+			}
 		},
 		async chat(messages, maxTokens) {
-			const max_tokens = Math.max(MIN_MAX_TOKENS, maxTokens ?? MIN_MAX_TOKENS);
-			const t0 = Date.now();
-			const res = await fetchWithRetry(`${baseUrl}/chat/completions`, {
-				method: "POST",
-				headers,
-				signal: options.signal,
-				body: JSON.stringify({
-					model,
+			options.signal?.throwIfAborted();
+			const started = Date.now();
+			try {
+				const response = await client.chat({
 					messages,
-					max_tokens,
+					maxTokens: Math.max(MIN_MAX_TOKENS, maxTokens ?? MIN_MAX_TOKENS),
 					temperature: .2,
-					stream: false
-				})
-			}, {
-				maxRetries,
-				retryBaseMs,
-				signal: options.signal
-			});
-			if (!res.ok) throw new RouterError(res.status, await res.text().catch(() => res.statusText));
-			const body = await res.json();
-			const promptTokens = body.usage?.prompt_tokens ?? 0;
-			const completionTokens = body.usage?.completion_tokens ?? 0;
-			acc.chatCalls += 1;
-			acc.promptTokens += promptTokens;
-			acc.completionTokens += completionTokens;
-			acc.usd += promptTokens * price.prompt + completionTokens * price.completion;
-			acc.wallMs += Date.now() - t0;
-			return body.choices?.[0]?.message?.content ?? "";
+					signal: options.signal
+				});
+				acc.chatCalls += 1;
+				acc.promptTokens += response.usage?.prompt_tokens ?? 0;
+				acc.completionTokens += response.usage?.completion_tokens ?? 0;
+				recordCost(response.tangle?.costSource === "receipt" ? response.tangle.costUsd : void 0);
+				return response.choices?.[0]?.message?.content ?? "";
+			} catch (error) {
+				return translate(error);
+			} finally {
+				acc.wallMs += Date.now() - started;
+			}
 		},
 		usage() {
 			return { ...acc };
 		}
 	};
 }
-/** Resolve the router client lazily so a worker with an injected client never reads env. */
-function resolveRouter(opts) {
-	return opts.router ?? createTangleRouterClient(opts.router_options);
+/** Bind run cancellation to the default router without changing an injected client. */
+function resolveRouter(opts, signal) {
+	if (opts.router) return opts.router;
+	const requestSignal = combineRouterSignals(signal, opts.router_options?.signal);
+	return createTangleRouterClient({
+		...opts.router_options,
+		signal: requestSignal
+	});
+}
+function combineRouterSignals(runSignal, configuredSignal) {
+	return runSignal && configuredSignal ? AbortSignal.any([runSignal, configuredSignal]) : runSignal ?? configuredSignal;
+}
+function throwIfRouterAborted(runSignal, opts) {
+	runSignal?.throwIfAborted();
+	if (!opts.router) opts.router_options?.signal?.throwIfAborted();
 }
 /**
 * The real web-research worker. Conforms to the loop's `ResearchWorker`
@@ -196,33 +177,41 @@ function createWebResearchWorker(options = {}) {
 	const minTextChars = Math.max(1, options.minTextChars ?? 200);
 	const maxTextChars = Math.max(minTextChars, options.maxTextChars ?? 4e3);
 	return async (ctx) => {
-		const router = resolveRouter(options);
+		const assertActive = () => throwIfRouterAborted(ctx.signal, options);
+		assertActive();
+		const router = resolveRouter(options, ctx.signal);
+		const fetchSignal = options.router ? ctx.signal : combineRouterSignals(ctx.signal, options.router_options?.signal);
 		const targetGaps = ctx.gaps.filter((gap) => gap.blocking);
 		const gaps = targetGaps.length > 0 ? targetGaps : ctx.gaps;
 		if (gaps.length === 0) return {
 			sources: [],
 			notes: "no open gaps to research"
 		};
-		const queries = await formSearchQueries(router, ctx, gaps, queriesPerGap);
+		const queries = await formSearchQueries(router, ctx, gaps, queriesPerGap, assertActive);
+		assertActive();
 		const proposals = [];
 		const seenUris = /* @__PURE__ */ new Set();
 		for (const query of queries) {
 			if (proposals.length >= maxSourcesPerRound) break;
-			if (ctx.signal?.aborted) break;
+			assertActive();
 			let hits;
 			try {
 				hits = await router.search(query, { maxResults: resultsPerQuery });
 			} catch (error) {
-				if (error.name === "AbortError") break;
+				assertActive();
+				if (error?.name === "AbortError") throw error;
 				continue;
 			}
+			assertActive();
 			for (const hit of hits) {
+				assertActive();
 				if (proposals.length >= maxSourcesPerRound) break;
 				if (seenUris.has(hit.url)) continue;
 				const fetched = await politeFetch(hit.url, {
-					signal: ctx.signal,
+					signal: fetchSignal,
 					cacheDir: options.cacheDir
 				});
+				assertActive();
 				if (!fetched.verifiable) continue;
 				const text = htmlToText(fetched.body).slice(0, maxTextChars);
 				if (text.length < minTextChars) continue;
@@ -241,6 +230,7 @@ function createWebResearchWorker(options = {}) {
 				});
 			}
 		}
+		assertActive();
 		return {
 			sources: proposals,
 			buildPages: buildCitingPages(proposals),
@@ -253,7 +243,7 @@ function createWebResearchWorker(options = {}) {
 * to the gap's own readiness query if the model returns nothing parseable, so a
 * model hiccup degrades to a sane search rather than an empty round.
 */
-async function formSearchQueries(router, ctx, gaps, queriesPerGap) {
+async function formSearchQueries(router, ctx, gaps, queriesPerGap, assertActive) {
 	const gapLines = gaps.map((gap, i) => `${i + 1}. ${gap.description} (readiness query: "${gap.query}")`).join("\n");
 	const want = gaps.length * queriesPerGap;
 	const system = "You are a research librarian. Turn knowledge gaps into precise web search queries that will surface authoritative primary sources (papers, docs, standards, official pages). Return ONLY a JSON array of query strings, no prose.";
@@ -272,7 +262,10 @@ async function formSearchQueries(router, ctx, gaps, queriesPerGap) {
 			role: "user",
 			content: user
 		}], MIN_MAX_TOKENS);
-	} catch {
+		assertActive();
+	} catch (error) {
+		assertActive();
+		if (error?.name === "AbortError") throw error;
 		raw = "";
 	}
 	const fromLlm = parseQueryList(raw).slice(0, want);
@@ -354,7 +347,9 @@ function escapeYaml(value) {
 function createVerifyingResearchDriver(options = {}) {
 	const acceptOnParseFailure = options.acceptOnParseFailure ?? false;
 	return { async verifySource(source, ctx) {
-		const router = resolveRouter(options);
+		const assertActive = () => throwIfRouterAborted(ctx.signal, options);
+		assertActive();
+		const router = resolveRouter(options, ctx.signal);
 		const gapLines = ctx.gaps.map((gap) => `- ${gap.description} (query: "${gap.query}")`).join("\n");
 		const acceptedTitles = ctx.acceptedThisRound.map((accepted) => `- ${accepted.title ?? accepted.uri}`).join("\n");
 		const excerpt = source.text.slice(0, 1500);
@@ -375,8 +370,10 @@ function createVerifyingResearchDriver(options = {}) {
 				role: "user",
 				content: user
 			}], MIN_MAX_TOKENS);
+			assertActive();
 		} catch (error) {
-			if (error.name === "AbortError") throw error;
+			assertActive();
+			if (error?.name === "AbortError") throw error;
 			return acceptOnParseFailure ? { accept: true } : {
 				accept: false,
 				reason: `verifier unavailable: ${error.message}`
@@ -494,7 +491,8 @@ const trackingParams = /* @__PURE__ */ new Set([
 * mirror/syndication of an already-accepted source even when the URL differs.
 */
 function contentKey(text) {
-	return sha256(text.toLowerCase().replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim());
+	const normalized = text.toLowerCase().replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
+	return sha256(normalized);
 }
 /** Default authoritative host suffixes — papers, official docs, standards. */
 const defaultAuthoritativeHosts = [
@@ -934,7 +932,8 @@ function knowledgeImprovementRunDir(root, runId) {
 	return runDir;
 }
 async function withKnowledgeImprovementRun(root, runId, create, use) {
-	const relativePath = relativeWithinRoot(root, knowledgeImprovementRunDir(root, runId));
+	const runDir = knowledgeImprovementRunDir(root, runId);
+	const relativePath = relativeWithinRoot(root, runDir);
 	if (!relativePath) throw new Error("knowledge improvement run directory escaped its root");
 	return withSafeDirectory(root, relativePath, create, async (openedRunDir) => {
 		const result = await use(openedRunDir);
@@ -1005,8 +1004,9 @@ function parseKnowledgeImprovementEvent(value) {
 	return event;
 }
 async function acquireRunLease(runDir, options) {
+	const path = join(runDir, "run.lock.durable");
 	const acquired = await acquireDurableFileLock(runDir, {
-		lockfilePath: join(runDir, "run.lock.durable"),
+		lockfilePath: path,
 		staleMs: options.ttlMs
 	});
 	return {
@@ -2461,100 +2461,114 @@ async function runRagKnowledgeImprovementPhases(options, previous) {
 	let knowledgeUpdate = previous?.knowledgeUpdate;
 	let answerQuality = previous?.answerQuality;
 	let promotion = previous?.promotion;
-	if (phaseEnabled(options, "gap-diagnosis")) if (options.diagnose) findings = [...await runPhase(phases, now, "gap-diagnosis", async () => {
-		assertNotAborted(options.signal);
-		return options.diagnose({
-			goal: options.goal,
-			phases,
-			optimization: selectRagOptimization(optimization),
-			signal: options.signal,
-			retrieval: selectRetrievalOptimization(retrieval)
-		});
-	}, (diagnosed) => `${diagnosed.length} finding(s)`)];
-	else skipPhase(phases, now, "gap-diagnosis", "no diagnosis hook provided");
-	if (phaseEnabled(options, "knowledge-acquisition")) if (options.acquireKnowledge) acquisition = await runPhase(phases, now, "knowledge-acquisition", async () => {
-		assertNotAborted(options.signal);
-		return options.acquireKnowledge({
-			goal: options.goal,
-			phases,
-			optimization: selectRagOptimization(optimization),
-			signal: options.signal,
-			retrieval: selectRetrievalOptimization(retrieval),
-			findings
-		});
-	}, summarizeAcquisitionDecision);
-	else skipPhase(phases, now, "knowledge-acquisition", "no acquisition hook provided");
-	if (phaseEnabled(options, "knowledge-update")) if (options.updateKnowledge) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
-		assertNotAborted(options.signal);
-		return options.updateKnowledge({
-			goal: options.goal,
-			phases,
-			optimization: selectRagOptimization(optimization),
-			signal: options.signal,
-			retrieval: selectRetrievalOptimization(retrieval),
-			findings,
-			acquisition
-		});
-	}, (result) => result.summary);
-	else if (options.knowledgeResearch) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
-		assertNotAborted(options.signal);
-		return runKnowledgeResearchUpdate(options, acquisition);
-	}, (result) => result.summary);
-	else skipPhase(phases, now, "knowledge-update", "no update hook or research loop provided");
-	if (phaseEnabled(options, "rag-optimization") && (options.optimization || options.enabledPhases?.includes("rag-optimization") || options.requiredPhases?.includes("rag-optimization"))) if (options.optimization) optimization = await runPhase(phases, now, "rag-optimization", async () => {
-		assertNotAborted(options.signal);
-		return runRagOptimization(options.optimization);
-	}, summarizeRagOptimization);
-	else skipPhase(phases, now, "rag-optimization", "no full RAG optimization options provided");
-	if (phaseEnabled(options, "retrieval-tuning")) if (options.retrieval) retrieval = await runPhase(phases, now, "retrieval-tuning", async () => {
-		assertNotAborted(options.signal);
-		return runRetrievalImprovementLoop(options.retrieval);
-	}, summarizeRetrievalResult);
-	else skipPhase(phases, now, "retrieval-tuning", "no retrieval options provided");
-	if (phaseEnabled(options, "answer-quality")) if (options.evaluateAnswers) {
-		answerQuality = await runPhase(phases, now, "answer-quality", async () => {
+	if (phaseEnabled(options, "gap-diagnosis")) {
+		if (options.diagnose) findings = [...await runPhase(phases, now, "gap-diagnosis", async () => {
+			assertNotAborted(options.signal);
+			return options.diagnose({
+				goal: options.goal,
+				phases,
+				optimization: selectRagOptimization(optimization),
+				signal: options.signal,
+				retrieval: selectRetrievalOptimization(retrieval)
+			});
+		}, (diagnosed) => `${diagnosed.length} finding(s)`)];
+		else skipPhase(phases, now, "gap-diagnosis", "no diagnosis hook provided");
+	}
+	if (phaseEnabled(options, "knowledge-acquisition")) {
+		if (options.acquireKnowledge) acquisition = await runPhase(phases, now, "knowledge-acquisition", async () => {
+			assertNotAborted(options.signal);
+			return options.acquireKnowledge({
+				goal: options.goal,
+				phases,
+				optimization: selectRagOptimization(optimization),
+				signal: options.signal,
+				retrieval: selectRetrievalOptimization(retrieval),
+				findings
+			});
+		}, summarizeAcquisitionDecision);
+		else skipPhase(phases, now, "knowledge-acquisition", "no acquisition hook provided");
+	}
+	if (phaseEnabled(options, "knowledge-update")) {
+		if (options.updateKnowledge) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
+			assertNotAborted(options.signal);
+			return options.updateKnowledge({
+				goal: options.goal,
+				phases,
+				optimization: selectRagOptimization(optimization),
+				signal: options.signal,
+				retrieval: selectRetrievalOptimization(retrieval),
+				findings,
+				acquisition
+			});
+		}, (result) => result.summary);
+		else if (options.knowledgeResearch) knowledgeUpdate = await runPhase(phases, now, "knowledge-update", async () => {
+			assertNotAborted(options.signal);
+			return runKnowledgeResearchUpdate(options, acquisition);
+		}, (result) => result.summary);
+		else skipPhase(phases, now, "knowledge-update", "no update hook or research loop provided");
+	}
+	if (phaseEnabled(options, "rag-optimization") && (options.optimization || options.enabledPhases?.includes("rag-optimization") || options.requiredPhases?.includes("rag-optimization"))) {
+		if (options.optimization) optimization = await runPhase(phases, now, "rag-optimization", async () => {
+			assertNotAborted(options.signal);
+			return runRagOptimization(options.optimization);
+		}, summarizeRagOptimization);
+		else skipPhase(phases, now, "rag-optimization", "no full RAG optimization options provided");
+	}
+	if (phaseEnabled(options, "retrieval-tuning")) {
+		if (options.retrieval) retrieval = await runPhase(phases, now, "retrieval-tuning", async () => {
+			assertNotAborted(options.signal);
+			return runRetrievalImprovementLoop(options.retrieval);
+		}, summarizeRetrievalResult);
+		else skipPhase(phases, now, "retrieval-tuning", "no retrieval options provided");
+	}
+	if (phaseEnabled(options, "answer-quality")) {
+		if (options.evaluateAnswers) {
+			answerQuality = await runPhase(phases, now, "answer-quality", async () => {
+				assertNotAborted(options.signal);
+				const result = await options.evaluateAnswers({
+					goal: options.goal,
+					phases,
+					optimization: selectRagOptimization(optimization),
+					signal: options.signal,
+					retrieval: selectRetrievalOptimization(retrieval),
+					findings,
+					acquisition,
+					knowledgeUpdate
+				});
+				assertRagAnswerEvidence(result);
+				return result;
+			}, summarizeAnswerQuality);
+			findings = [...findings, ...answerQuality.findings ?? []];
+		} else skipPhase(phases, now, "answer-quality", "no answer-quality hook provided");
+	}
+	if (phaseEnabled(options, "promotion")) {
+		if (options.decidePromotion) promotion = await runPhase(phases, now, "promotion", async () => {
 			assertNotAborted(options.signal);
-			const result = await options.evaluateAnswers({
+			const evidenceRejection = rejectUnsafePromotionEvidence({
+				optimization: optimization?.comparison,
+				optimizationCostCeiling: options.optimization?.costCeiling,
+				retrieval: retrieval?.comparison,
+				retrievalCostCeiling: options.retrieval?.costCeiling,
+				answerQuality,
+				answerQualityCostCeiling: options.answerQualityCostCeiling
+			});
+			if (evidenceRejection) return evidenceRejection;
+			return options.decidePromotion({
 				goal: options.goal,
 				phases,
 				optimization: selectRagOptimization(optimization),
+				optimizationComparison: optimization?.comparison,
 				signal: options.signal,
 				retrieval: selectRetrievalOptimization(retrieval),
+				retrievalComparison: retrieval?.comparison,
 				findings,
 				acquisition,
-				knowledgeUpdate
+				knowledgeUpdate,
+				answerQuality
 			});
-			assertRagAnswerEvidence(result);
-			return result;
-		}, summarizeAnswerQuality);
-		findings = [...findings, ...answerQuality.findings ?? []];
-	} else skipPhase(phases, now, "answer-quality", "no answer-quality hook provided");
-	if (phaseEnabled(options, "promotion")) if (options.decidePromotion) promotion = await runPhase(phases, now, "promotion", async () => {
-		assertNotAborted(options.signal);
-		const evidenceRejection = rejectUnsafePromotionEvidence({
-			optimization: optimization?.comparison,
-			optimizationCostCeiling: options.optimization?.costCeiling,
-			retrieval: retrieval?.comparison,
-			retrievalCostCeiling: options.retrieval?.costCeiling,
-			answerQuality,
-			answerQualityCostCeiling: options.answerQualityCostCeiling
-		});
-		if (evidenceRejection) return evidenceRejection;
-		return options.decidePromotion({
-			goal: options.goal,
-			phases,
-			optimization: selectRagOptimization(optimization),
-			optimizationComparison: optimization?.comparison,
-			signal: options.signal,
-			retrieval: selectRetrievalOptimization(retrieval),
-			retrievalComparison: retrieval?.comparison,
-			findings,
-			acquisition,
-			knowledgeUpdate,
-			answerQuality
-		});
-	}, (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`);
-	else skipPhase(phases, now, "promotion", "no promotion decision hook provided");
+		}, (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`);
+		else skipPhase(phases, now, "promotion", "no promotion decision hook provided");
+	}
 	return {
 		goal: options.goal,
 		phases,
@@ -2801,9 +2815,11 @@ async function withMeasuredCandidateSnapshot(liveRoot, runDir, state, candidateR
 	await assertStateIdentity(liveRoot, candidateRef, state);
 	const candidate = state.candidates.find((entry) => entry.candidateId === candidateRef.candidateId);
 	if (!candidate) throw new Error(`knowledge candidate '${candidateRef.candidateId}' does not exist`);
-	if (canonicalJson(candidateRefFor(candidateRef.runId, state, candidate)) !== canonicalJson(candidateRef)) throw new Error("knowledge candidate approval does not match the measured candidate");
+	const expectedRef = candidateRefFor(candidateRef.runId, state, candidate);
+	if (canonicalJson(expectedRef) !== canonicalJson(candidateRef)) throw new Error("knowledge candidate approval does not match the measured candidate");
 	const evidence = await assertCandidateEvidence(runDir, candidateRef, state.implementationRef);
-	return withSafeDirectory(runDir, join("candidates", candidate.candidateId, "snapshots", candidateRef.candidateHash), false, async (root) => {
+	const relativePath = join("candidates", candidate.candidateId, "snapshots", candidateRef.candidateHash);
+	return withSafeDirectory(runDir, relativePath, false, async (root) => {
 		if (await hashKnowledgeBase(root, state.stateScope) !== candidateRef.candidateHash) throw new Error("knowledge candidate snapshot changed after approval");
 		const result = await use({
 			root,
@@ -2906,7 +2922,8 @@ async function withBaselineSnapshot(runDir, expectedHash, use, scope) {
 	});
 }
 async function withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, use, scope) {
-	return withSafeDirectory(runDir, join("candidates", safePathSegmentSchema.parse(candidate.candidateId), "snapshots"), true, async (snapshotsDir) => {
+	const snapshotsPath = join("candidates", safePathSegmentSchema.parse(candidate.candidateId), "snapshots");
+	return withSafeDirectory(runDir, snapshotsPath, true, async (snapshotsDir) => {
 		const preparation = await mkdtemp(join(snapshotsDir, "prepare-"));
 		let activated = false;
 		try {
@@ -3325,7 +3342,8 @@ async function knowledgePlanMutations(targetRoot, plan) {
 	}));
 }
 function assertCandidateTransitionPlan(plan, candidate, target, scope) {
-	const actualPlanHash = knowledgeFileTransactionPlanHash(target === "candidate" ? plan : reverseKnowledgeFilePlan(plan), normalizeKnowledgeStateScope(scope).pagesDirectory, scope?.researchState);
+	const approvedDirection = target === "candidate" ? plan : reverseKnowledgeFilePlan(plan);
+	const actualPlanHash = knowledgeFileTransactionPlanHash(approvedDirection, normalizeKnowledgeStateScope(scope).pagesDirectory, scope?.researchState);
 	if (actualPlanHash !== candidate.promotionPlanHash) throw new Error(`knowledge candidate plan changed after approval: expected ${candidate.promotionPlanHash}, got ${actualPlanHash}`);
 }
 function assertCandidateTransitionTransaction(transaction, candidate, target, scope) {
@@ -3929,7 +3947,7 @@ async function improveSelectedKnowledgeCandidate(options) {
 		if (sourcePlanHash !== sourceCandidate.promotionPlanHash) throw new Error("source knowledge candidate plan no longer matches its measured identity");
 		const changedSourcePlan = sourcePlan.filter(planEntryChanged).filter((entry) => notDerivedPath(entry, scope));
 		const selectedPaths = normalizeSelectedPaths(options.selectedPaths, changedSourcePlan, scope);
-		const selectionDigest = contentHash(immutableJson({
+		const selectionMaterial = immutableJson({
 			kind: "measured-knowledge-change-selection",
 			version: 1,
 			sourceCandidate,
@@ -3937,7 +3955,8 @@ async function improveSelectedKnowledgeCandidate(options) {
 			selectedPaths,
 			...options.rationale?.trim() ? { rationale: options.rationale.trim() } : {},
 			...metadata ? { metadata } : {}
-		}));
+		});
+		const selectionDigest = contentHash(selectionMaterial);
 		const derivedImplementationRef = immutableRefSchema.parse(`sha256:${contentHash({
 			engine: "agent-knowledge/measured-selection-v1",
 			implementationRef: requestedImplementationRef,
@@ -4112,7 +4131,8 @@ async function persistSelectionReceipt(root, receipt) {
 	const runDir = knowledgeImprovementRunDir(root, receipt.runId);
 	const relativePath = join("candidates", safePathSegmentSchema.parse(receipt.derivedCandidateId), "selection.json").replace(/\\/g, "/");
 	try {
-		if (canonicalJson(measuredSelectionReceiptSchema.parse(JSON.parse((await readRegularFileWithinRoot(runDir, relativePath)).bytes.toString("utf8")))) !== canonicalJson(receipt)) throw new Error("measured knowledge selection receipt conflicts with durable content");
+		const existing = measuredSelectionReceiptSchema.parse(JSON.parse((await readRegularFileWithinRoot(runDir, relativePath)).bytes.toString("utf8")));
+		if (canonicalJson(existing) !== canonicalJson(receipt)) throw new Error("measured knowledge selection receipt conflicts with durable content");
 		return;
 	} catch (error) {
 		if (!isMissingFile(error)) throw error;
@@ -5527,17 +5547,22 @@ async function materialFactsSurfaced(kb, checklist) {
 * and `searchKnowledge` — and reinvents none of them.
 */
 async function runVerifiedResearchLoop(options) {
+	const assertActive = () => options.signal?.throwIfAborted();
+	assertActive();
 	const maxRounds = Math.max(1, options.maxRounds ?? 3);
 	await initKnowledgeBase(options.root);
+	assertActive();
 	const store = new FileSystemKbStore({ root: options.root });
 	const steps = [];
 	let index = await buildKnowledgeIndex(options.root);
+	assertActive();
 	await confirmRegisteredSources(options.driver, index.sources);
+	assertActive();
 	let readiness = readinessFor(options, index);
 	let ready = isReady(readiness?.report) && (options.driver.isComplete?.() ?? true);
 	let steer;
 	for (let round = 1; round <= maxRounds && !ready; round++) {
-		if (options.signal?.aborted) throw new Error("Verified research loop aborted");
+		assertActive();
 		const gaps = gapsFromReadiness(readiness);
 		const workerContribution = await options.worker({
 			root: options.root,
@@ -5549,6 +5574,7 @@ async function runVerifiedResearchLoop(options) {
 			readiness: requireReadiness(readiness, options),
 			signal: options.signal
 		});
+		assertActive();
 		const accepted = [];
 		const rejectedWorkerSources = [];
 		const existingUris = new Set(index.sources.flatMap((source) => typeof source.metadata?.originalUri === "string" ? [source.metadata.originalUri] : []));
@@ -5570,6 +5596,7 @@ async function runVerifiedResearchLoop(options) {
 				acceptedThisRound: accepted,
 				signal: options.signal
 			});
+			assertActive();
 			if (verdict.accept) accepted.push(source);
 			else rejectedWorkerSources.push({
 				source,
@@ -5577,10 +5604,14 @@ async function runVerifiedResearchLoop(options) {
 			});
 		}
 		const acceptedWorkerSources = await registerSources(options, accepted);
+		assertActive();
 		await confirmRegisteredSources(options.driver, acceptedWorkerSources);
+		assertActive();
 		const writtenPages = [];
 		writtenPages.push(...await applyPages(options.root, workerContribution, acceptedWorkerSources));
+		assertActive();
 		index = await buildKnowledgeIndex(options.root);
+		assertActive();
 		readiness = readinessFor(options, index);
 		let driverSources = [];
 		let driverNotes;
@@ -5595,11 +5626,16 @@ async function runVerifiedResearchLoop(options) {
 				readiness: requireReadiness(readiness, options),
 				signal: options.signal
 			});
+			assertActive();
 			driverNotes = driverContribution.notes;
 			driverSources = await registerSources(options, driverContribution.sources ?? []);
+			assertActive();
 			await confirmRegisteredSources(options.driver, driverSources);
+			assertActive();
 			writtenPages.push(...await applyPages(options.root, driverContribution, driverSources));
+			assertActive();
 			index = await buildKnowledgeIndex(options.root);
+			assertActive();
 			readiness = readinessFor(options, index);
 		}
 		const driverComplete = options.driver.isComplete?.() ?? true;
@@ -5608,6 +5644,7 @@ async function runVerifiedResearchLoop(options) {
 		if (ready || remainingGaps.length === 0 && driverComplete) steer = void 0;
 		else {
 			await options.driver.prepareFold?.();
+			assertActive();
 			steer = foldGaps(options.driver, remainingGaps);
 		}
 		const step = {
@@ -5640,10 +5677,14 @@ async function runVerifiedResearchLoop(options) {
 			}
 		};
 		await options.driver.checkpoint?.();
+		assertActive();
 		await store.putEvent(step.event);
+		assertActive();
 		steps.push(step);
 		await options.onRound?.(step);
+		assertActive();
 	}
+	assertActive();
 	return {
 		root: options.root,
 		goal: options.goal,
@@ -5685,8 +5726,10 @@ function isDuplicate(source, existingUris, accepted) {
 async function registerSources(options, sources) {
 	const records = [];
 	for (const candidate of sources) {
+		options.signal?.throwIfAborted();
 		const source = snapshotSourceTextInput(candidate);
 		records.push(await addSourceText(options.root, source, options.sourceOptions));
+		options.signal?.throwIfAborted();
 	}
 	return records;
 }
@@ -5859,7 +5902,7 @@ function thesisSynthesisMessages(input, kbText) {
 async function writeThesisPage(root, input, thesis) {
 	return withKnowledgeMutation(root, async () => {
 		const relativePath = `knowledge/thesis-${slugify(input.ticker)}.md`;
-		await writeFileDurableWithinRoot(root, relativePath, [
+		const body = [
 			"---",
 			`title: Investment thesis — ${input.company} (${input.ticker})`,
 			`ticker: ${input.ticker}`,
@@ -5870,7 +5913,8 @@ async function writeThesisPage(root, input, thesis) {
 			"",
 			thesis.trim(),
 			""
-		].join("\n"), { encoding: "utf8" });
+		].join("\n");
+		await writeFileDurableWithinRoot(root, relativePath, body, { encoding: "utf8" });
 		return join(root, relativePath);
 	});
 }
@@ -5942,7 +5986,7 @@ function buildKnowledgeBrief(visiblePages, question, options = {}) {
 		origin: entry.origin
 	});
 	const originals = /* @__PURE__ */ new Map();
-	const ranked = searchKnowledgePages(visiblePages.map((entry) => {
+	const pages = visiblePages.map((entry) => {
 		const page = {
 			...entry.page,
 			id: qualified(entry),
@@ -5959,7 +6003,8 @@ function buildKnowledgeBrief(visiblePages, question, options = {}) {
 		};
 		originals.set(page, entry);
 		return page;
-	}), question, {
+	});
+	const ranked = searchKnowledgePages(pages, question, {
 		limit,
 		excludeInvalidated,
 		...options.tags === void 0 ? {} : { tags: options.tags },
@@ -6011,212 +6056,6 @@ function briefLine(hit) {
 	return snippet === "" ? `- [${hit.citationId}] ${hit.page.title}` : `- [${hit.citationId}] ${hit.page.title} — ${snippet}`;
 }
 //#endregion
-//#region src/knowledge-visibility.ts
-const KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION = "2.0.0";
-const KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM = "rfc8785-sha256";
-/** Stable content identity for one exact knowledge page. */
-function knowledgePageDigest(page) {
-	validateKnowledgePage(page);
-	return canonicalCandidateDigest({
-		id: page.id,
-		path: page.path,
-		title: page.title,
-		text: page.text,
-		frontmatter: page.frontmatter,
-		sourceIds: [...page.sourceIds],
-		tags: [...page.tags],
-		outLinks: [...page.outLinks],
-		contradicts: [...page.contradicts ?? []],
-		invalidation: page.invalidation ?? null
-	});
-}
-/** Snapshot the exact ordered current/ancestor/shared page view. */
-function createKnowledgeVisibilitySnapshot(visiblePages) {
-	if (!Array.isArray(visiblePages)) throw new TypeError("knowledge visibility must be an array");
-	const identities = /* @__PURE__ */ new Set();
-	const entries = visiblePages.map((entry, position) => {
-		if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an originated page`);
-		const origin = validateOrigin(entry.origin, `knowledge visibility[${position}].origin`);
-		validateKnowledgePage(entry.page);
-		const identity = visibilityIdentity(origin, entry.page.path);
-		if (identities.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.page.path}' at origin '${origin}'`);
-		identities.add(identity);
-		return Object.freeze({
-			position,
-			pageId: entry.page.id,
-			origin,
-			path: entry.page.path,
-			pageDigest: knowledgePageDigest(entry.page),
-			sourceIds: Object.freeze([...entry.page.sourceIds]),
-			invalidated: entry.page.invalidation !== void 0
-		});
-	});
-	const material = visibilityMaterial(entries);
-	const snapshot = Object.freeze({
-		...material,
-		snapshotDigest: canonicalCandidateDigest(material),
-		entries: Object.freeze(entries)
-	});
-	visibilityIndexes.set(snapshot, indexVisibility(snapshot));
-	return snapshot;
-}
-/**
-* Verify a snapshot's schema and canonical digest. The check runs once per
-* snapshot object; later calls with the same object are free.
-*/
-function verifyKnowledgeVisibilitySnapshot(snapshot) {
-	return visibilityIndexOf(snapshot).snapshot;
-}
-/** Canonical bytes of a verified snapshot, for durable storage. */
-function encodeKnowledgeVisibilitySnapshot(snapshot) {
-	const verified = verifyKnowledgeVisibilitySnapshot(snapshot);
-	return canonicalCandidateBytes({
-		schemaVersion: verified.schemaVersion,
-		digestAlgorithm: verified.digestAlgorithm,
-		snapshotDigest: verified.snapshotDigest,
-		entries: visibilityMaterial(verified.entries).entries
-	});
-}
-/** Parse stored snapshot bytes and verify their schema and digest. */
-function decodeKnowledgeVisibilitySnapshot(bytes) {
-	if (!(bytes instanceof Uint8Array)) throw new TypeError("knowledge visibility snapshot bytes must be a Uint8Array");
-	let parsed;
-	try {
-		parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-	} catch (error) {
-		throw new Error(`knowledge visibility snapshot bytes are not JSON: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("knowledge visibility snapshot must be an object");
-	const candidate = parsed;
-	if (!Array.isArray(candidate.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
-	return verifyKnowledgeVisibilitySnapshot(Object.freeze({
-		schemaVersion: candidate.schemaVersion,
-		digestAlgorithm: candidate.digestAlgorithm,
-		snapshotDigest: digest(candidate.snapshotDigest, "knowledge visibility snapshotDigest"),
-		entries: Object.freeze(candidate.entries.map((entry, position) => {
-			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
-			const value = entry;
-			if (!Array.isArray(value.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
-			return Object.freeze({
-				position: value.position,
-				pageId: value.pageId,
-				origin: value.origin,
-				path: value.path,
-				pageDigest: value.pageDigest,
-				sourceIds: Object.freeze([...value.sourceIds]),
-				invalidated: value.invalidated
-			});
-		}))
-	}));
-}
-/** Locator for snapshot bytes stored at `uri`. */
-function knowledgeVisibilityArtifactRef(input) {
-	if (!input || typeof input !== "object" || !(input.bytes instanceof Uint8Array)) throw new TypeError("knowledge visibility artifact bytes must be a Uint8Array");
-	if (input.bytes.byteLength === 0) throw new TypeError("knowledge visibility artifact bytes must not be empty");
-	return Object.freeze({
-		uri: nonEmpty$1(input.uri, "knowledge visibility artifact uri"),
-		digest: sha256Bytes(input.bytes),
-		byteLength: input.bytes.byteLength
-	});
-}
-const visibilityIndexes = /* @__PURE__ */ new WeakMap();
-function visibilityIndexOf(snapshot) {
-	if (!snapshot || typeof snapshot !== "object") throw new TypeError("knowledge visibility snapshot is required");
-	const cached = visibilityIndexes.get(snapshot);
-	if (cached !== void 0) return cached;
-	assertSchemaVersion(snapshot.schemaVersion, "knowledge visibility");
-	if (snapshot.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge visibility digestAlgorithm '${snapshot.digestAlgorithm}'`);
-	if (!Array.isArray(snapshot.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
-	if (canonicalCandidateDigest(visibilityMaterial(snapshot.entries)) !== digest(snapshot.snapshotDigest, "knowledge visibility snapshotDigest")) throw new Error("knowledge visibility snapshot digest mismatch");
-	const index = indexVisibility(snapshot);
-	visibilityIndexes.set(snapshot, index);
-	return index;
-}
-function indexVisibility(snapshot) {
-	const byIdentity = /* @__PURE__ */ new Map();
-	for (const entry of snapshot.entries) {
-		const identity = visibilityIdentity(entry.origin, entry.path);
-		if (byIdentity.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.path}' at origin '${entry.origin}'`);
-		byIdentity.set(identity, entry);
-	}
-	return {
-		snapshot,
-		byIdentity
-	};
-}
-function visibilityIdentity(origin, path) {
-	return `${origin}\u0000${path}`;
-}
-function assertSchemaVersion(value, label) {
-	if (value === "2.0.0") return;
-	throw new Error(`unsupported ${label} schemaVersion '${String(value)}'${value === "1.0.0" ? "; 1.0.0 records embed the visibility snapshot and have no reader, create a 2.0.0 record from the snapshot" : ""}`);
-}
-function visibilityMaterial(entries) {
-	return {
-		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
-		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
-		entries: entries.map((entry, position) => {
-			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
-			if (entry.position !== position) throw new Error(`knowledge visibility position mismatch: expected ${position}, observed ${entry.position}`);
-			if (!Array.isArray(entry.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
-			return {
-				position,
-				pageId: nonEmpty$1(entry.pageId, `knowledge visibility[${position}].pageId`),
-				origin: validateOrigin(entry.origin, `knowledge visibility[${position}].origin`),
-				path: nonEmpty$1(entry.path, `knowledge visibility[${position}].path`),
-				pageDigest: digest(entry.pageDigest, `knowledge visibility[${position}].pageDigest`),
-				sourceIds: entry.sourceIds.map((sourceId, sourceIndex) => nonEmpty$1(sourceId, `knowledge visibility[${position}].sourceIds[${sourceIndex}]`)),
-				invalidated: Boolean(entry.invalidated)
-			};
-		})
-	};
-}
-function normalizeVisibilityRef(input) {
-	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval visibility reference is required");
-	if (!Number.isSafeInteger(input.pageCount) || input.pageCount < 0) throw new TypeError("knowledge retrieval visibility pageCount must be a non-negative integer");
-	return Object.freeze({
-		snapshotDigest: digest(input.snapshotDigest, "knowledge retrieval visibility snapshotDigest"),
-		pageCount: input.pageCount,
-		...input.artifact === void 0 ? {} : { artifact: normalizeVisibilityArtifact(input.artifact, "knowledge retrieval visibility artifact") }
-	});
-}
-function normalizeVisibilityArtifact(input, label) {
-	if (!input || typeof input !== "object") throw new TypeError(`${label} must be an object`);
-	if (!Number.isSafeInteger(input.byteLength) || input.byteLength < 1) throw new TypeError(`${label} byteLength must be a positive integer`);
-	return Object.freeze({
-		uri: nonEmpty$1(input.uri, `${label} uri`),
-		digest: digest(input.digest, `${label} digest`),
-		byteLength: input.byteLength
-	});
-}
-function validateKnowledgePage(page) {
-	if (!page || typeof page !== "object") throw new TypeError("knowledge page must be an object");
-	nonEmpty$1(page.id, "knowledge page id");
-	nonEmpty$1(page.path, "knowledge page path");
-	nonEmpty$1(page.title, "knowledge page title");
-	if (typeof page.text !== "string") throw new TypeError("knowledge page text must be a string");
-	if (!page.frontmatter || typeof page.frontmatter !== "object" || Array.isArray(page.frontmatter)) throw new TypeError("knowledge page frontmatter must be an object");
-	for (const [name, values] of [
-		["sourceIds", page.sourceIds],
-		["tags", page.tags],
-		["outLinks", page.outLinks]
-	]) if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) throw new TypeError(`knowledge page ${name} must be a string array`);
-}
-function validateOrigin(value, label) {
-	if (value === "here" || value === "shared") return value;
-	if (typeof value === "string" && value.startsWith("inherited:") && value.slice(10).trim().length > 0) return value;
-	throw new TypeError(`${label} is invalid: ${String(value)}`);
-}
-function digest(value, label) {
-	const parsed = sha256DigestSchema.safeParse(value);
-	if (!parsed.success) throw new TypeError(`${label} must be a lowercase sha256 digest`);
-	return parsed.data;
-}
-function nonEmpty$1(value, label) {
-	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
-	return value.trim();
-}
-//#endregion
 //#region src/knowledge-use-receipts.ts
 /**
 * The visibility snapshot a receipt references could not be obtained, so the
@@ -6296,7 +6135,7 @@ function verifyKnowledgeRetrievalReceipt(receipt) {
 	if (receipt.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge retrieval digestAlgorithm '${receipt.digestAlgorithm}'`);
 	const visibility = normalizeVisibilityRef(receipt.visibility);
 	validateReceiptResultShape(receipt.results, visibility.pageCount);
-	if (canonicalCandidateDigest(retrievalMaterial({
+	const material = retrievalMaterial({
 		createdAt: isoTimestamp(receipt.createdAt, "knowledge retrieval createdAt"),
 		runId: nonEmpty$1(receipt.runId, "knowledge retrieval runId"),
 		actorId: optionalText(receipt.actorId, "knowledge retrieval actorId"),
@@ -6308,7 +6147,8 @@ function verifyKnowledgeRetrievalReceipt(receipt) {
 		results: receipt.results,
 		evidenceRefs: normalizeEvidenceRefs(receipt.evidenceRefs),
 		attributes: normalizeAttributes(receipt.attributes)
-	})) !== receipt.receiptDigest) throw new Error("knowledge retrieval receipt digest mismatch");
+	});
+	if (canonicalCandidateDigest(material) !== receipt.receiptDigest) throw new Error("knowledge retrieval receipt digest mismatch");
 	return receipt;
 }
 /**
@@ -6400,7 +6240,7 @@ function verifyKnowledgeUseReceipt(receipt, retrieval) {
 	if (receipt.retrievalReceiptDigest !== verifiedRetrieval.receiptDigest) throw new Error("knowledge use receipt references a different retrieval receipt");
 	const selected = verifiedRetrieval.results.find((result) => result.rank === receipt.used.rank);
 	if (!selected || selected.pageId !== receipt.used.pageId || selected.origin !== receipt.used.origin || selected.path !== receipt.used.path || selected.pageDigest !== receipt.used.pageDigest) throw new Error("knowledge use receipt selected result does not match the retrieval receipt");
-	if (canonicalCandidateDigest(useMaterial({
+	const material = useMaterial({
 		createdAt: isoTimestamp(receipt.createdAt, "knowledge use createdAt"),
 		retrieval: verifiedRetrieval,
 		used: receipt.used,
@@ -6408,7 +6248,8 @@ function verifyKnowledgeUseReceipt(receipt, retrieval) {
 		consumer: normalizeConsumer(receipt.consumer),
 		evidenceRefs: normalizeEvidenceRefs(receipt.evidenceRefs),
 		attributes: normalizeAttributes(receipt.attributes)
-	})) !== receipt.receiptDigest) throw new Error("knowledge use receipt digest mismatch");
+	});
+	if (canonicalCandidateDigest(material) !== receipt.receiptDigest) throw new Error("knowledge use receipt digest mismatch");
 	return receipt;
 }
 /** Record that one retrieval led to no use, with no rank to select. */
@@ -6435,14 +6276,15 @@ function verifyKnowledgeRetrievalDisposition(disposition, retrieval) {
 	if (disposition.kind !== "knowledge-retrieval-disposition") throw new Error(`knowledge retrieval disposition kind must be 'knowledge-retrieval-disposition'`);
 	if (disposition.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge retrieval disposition digestAlgorithm '${disposition.digestAlgorithm}'`);
 	if (disposition.retrievalReceiptDigest !== verifiedRetrieval.receiptDigest) throw new Error("knowledge retrieval disposition references a different retrieval receipt");
-	if (canonicalCandidateDigest(dispositionMaterial({
+	const material = dispositionMaterial({
 		createdAt: isoTimestamp(disposition.createdAt, "knowledge retrieval disposition createdAt"),
 		retrieval: verifiedRetrieval,
 		relation: validateDispositionRelation(disposition.relation),
 		consumer: normalizeConsumer(disposition.consumer),
 		evidenceRefs: normalizeEvidenceRefs(disposition.evidenceRefs),
 		attributes: normalizeAttributes(disposition.attributes)
-	})) !== disposition.receiptDigest) throw new Error("knowledge retrieval disposition digest mismatch");
+	});
+	if (canonicalCandidateDigest(material) !== disposition.receiptDigest) throw new Error("knowledge retrieval disposition digest mismatch");
 	return disposition;
 }
 function assertReceiptJoinsVisibility(receipt, index) {
@@ -6557,7 +6399,8 @@ function validateReceiptResultShape(results, pageCount) {
 	const seen = /* @__PURE__ */ new Set();
 	results.forEach((result, position) => {
 		if (!result || typeof result !== "object") throw new TypeError(`knowledge retrieval results[${position}] must be an object`);
-		const identity = visibilityIdentity(validateOrigin(result.origin, `knowledge retrieval results[${position}].origin`), nonEmpty$1(result.path, `knowledge retrieval results[${position}].path`));
+		const origin = validateOrigin(result.origin, `knowledge retrieval results[${position}].origin`);
+		const identity = visibilityIdentity(origin, nonEmpty$1(result.path, `knowledge retrieval results[${position}].path`));
 		if (seen.has(identity)) throw new Error(`knowledge retrieval repeats visible page '${result.path}'`);
 		seen.add(identity);
 		nonEmpty$1(result.pageId, `knowledge retrieval results[${position}].pageId`);
@@ -6680,7 +6523,10 @@ const searchInput = z.object({
 	kinds: z.array(z.string()).optional()
 });
 const readInput = z.object({ pageId: z.string().min(1) });
-const recordInput = z.object({ proposal: z.string().min(1).describe("One or more complete FILE blocks. Each begins with ---FILE: <page-path>--- and ends with ---END FILE---, each on its own line. Put the page content between them. Every block must be valid; malformed or empty proposals write nothing and return an error.") });
+const recordInput = z.object({
+	expectedPageDigests: z.record(z.string().min(1), sha256DigestSchema.nullable()).optional().describe("For each existing page, pass its path and pageDigest from knowledge_read. Null requires a new page. Missing entries permit new pages only."),
+	proposal: z.string().min(1).describe("One or more complete FILE blocks. Each begins with ---FILE: <page-path>--- and ends with ---END FILE---, each on its own line. Put the page content between them. Every block must be valid; malformed or empty proposals write nothing and return an error.")
+});
 const resolveInput = z.object({ references: z.array(z.string().min(1)).min(1) });
 /**
 * The four tools an agent needs to use a knowledge store: search, read, record,
@@ -6736,6 +6582,7 @@ function createKnowledgeTools(options) {
 					origin: resolution.resolved.origin,
 					path: resolution.resolved.page.path,
 					title: resolution.resolved.page.title,
+					pageDigest: knowledgePageDigest(resolution.resolved.page),
 					text: resolution.resolved.page.text
 				},
 				candidates: resolution.candidates.map((candidate) => ({
@@ -6745,13 +6592,16 @@ function createKnowledgeTools(options) {
 				}))
 			};
 		}),
-		tool("knowledge_record", `Write pages into this run's store. Use complete blocks exactly like:\n---FILE: ${pagesDirectory}/example.md---\n# Example\nPage content.\n---END FILE---\nUse paths under ${pagesDirectory}/. Both delimiters must be on their own lines. Malformed, unsafe, or empty proposals are rejected before writing any pages.`, recordInput, async (input) => {
+		tool("knowledge_record", `Write pages into this run's store. Use complete blocks exactly like:\n---FILE: ${pagesDirectory}/example.md---\n# Example\nPage content.\n---END FILE---\nUse paths under ${pagesDirectory}/. Both delimiters must be on their own lines. To update a page, first knowledge_read it and pass expectedPageDigests[path] = pageDigest. Stale edits and malformed, unsafe, or empty proposals are rejected before writing any pages.`, recordInput, async (input) => {
 			const parsed = parseKnowledgeWriteBlocks(input.proposal, [`${pagesDirectory}/`]);
 			if (parsed.blocks.length === 0 || parsed.warnings.length > 0) throw new Error(`knowledge_record rejected the proposal without writing any pages. Use ---FILE: ${pagesDirectory}/example.md--- followed by content and ---END FILE---, each delimiter on its own line. ${parsed.warnings.join(" ")}`);
 			const intake = options.intake;
 			return applyKnowledgeWriteBlocks(stores.storePath(runId), input.proposal, {
 				...pages,
-				retainHistory: options.retainHistory,
+				actorId: options.actorId,
+				runId,
+				expectedPageDigests: input.expectedPageDigests ?? {},
+				retainHistory: options.retainHistory ?? true,
 				...intake === void 0 ? {} : { intake: {
 					...intake,
 					inheritedPages: await inheritedOf(stores, runId)
@@ -6856,7 +6706,8 @@ async function promoteRunScopedPages(stores, runId, options) {
 		const existing = await loadKnowledgePages(sharedRoot, { pagesDirectory });
 		assertNoIdentityConflict(travellers, existing);
 		const promotedPaths = new Set(travellers.map((traveller) => traveller.entry.page.path));
-		assertKnowledgeCitationsResolved(originatedPages([...existing.filter((page) => !promotedPaths.has(page.path)), ...travellers.map((traveller) => traveller.entry.page)], "shared"), travellers.flatMap((traveller) => (traveller.entry.page.cites ?? []).map((persisted) => parseKnowledgeCitationReference(persisted))));
+		const promotedView = originatedPages([...existing.filter((page) => !promotedPaths.has(page.path)), ...travellers.map((traveller) => traveller.entry.page)], "shared");
+		assertKnowledgeCitationsResolved(promotedView, travellers.flatMap((traveller) => (traveller.entry.page.cites ?? []).map((persisted) => parseKnowledgeCitationReference(persisted))));
 		await commitKnowledgeFileMutations({
 			root: sharedRoot,
 			transactionRoot: lock.transactionRoot,
@@ -6947,7 +6798,8 @@ function assertNoIdentityConflict(travellers, existing) {
 async function readPageBytes(stores, runId, entry, pagesDirectory) {
 	const sourceRunId = sourceRunOf(entry.origin, runId);
 	const content = (await readRegularFileWithinRoot(stores.storePath(sourceRunId), entry.page.path)).bytes.toString("utf8");
-	if (knowledgePageDigest(knowledgePageFromMarkdown(entry.page.path, content, pagesDirectory)) !== knowledgePageDigest(entry.page)) throw new KnowledgePromotionError("path-conflict", `source page "${entry.page.path}" in run "${sourceRunId}" changed after the promotion snapshot`);
+	const page = knowledgePageFromMarkdown(entry.page.path, content, pagesDirectory);
+	if (knowledgePageDigest(page) !== knowledgePageDigest(entry.page)) throw new KnowledgePromotionError("path-conflict", `source page "${entry.page.path}" in run "${sourceRunId}" changed after the promotion snapshot`);
 	return content;
 }
 function sourceRunOf(origin, runId) {
@@ -7672,8 +7524,18 @@ function buildDriver(options, persistence, restored) {
 		}
 		if (goal !== nextGoal) throw new Error(`claim ledger '${persistence?.ledgerId ?? "in-memory"}' accumulated evidence for goal '${goal}' and cannot be reused for '${nextGoal}'`);
 	}
-	function resolveRouter() {
-		return options.router ?? createTangleRouterClient(options.router_options);
+	function resolveRouter(signal) {
+		if (options.router) return options.router;
+		const configuredSignal = options.router_options?.signal;
+		const requestSignal = configuredSignal && signal ? AbortSignal.any([configuredSignal, signal]) : configuredSignal ?? signal;
+		return createTangleRouterClient({
+			...options.router_options,
+			signal: requestSignal
+		});
+	}
+	function throwIfRouterAborted(signal) {
+		signal?.throwIfAborted();
+		if (!options.router) options.router_options?.signal?.throwIfAborted();
 	}
 	/** Record a claim from a source, growing its independent-source support. */
 	function recordClaim(extracted, sourceUri, round) {
@@ -7835,12 +7697,14 @@ function buildDriver(options, persistence, restored) {
 		* because such a source cannot drive the research and pollutes the KB.
 		*/
 		async verifySource(source, ctx) {
+			throwIfRouterAborted(ctx.signal);
 			const sourceSnapshot = snapshotSourceTextInput(source);
 			const goalSnapshot = ctx.goal;
 			const roundSnapshot = ctx.round;
 			const sourceVersion = sourceVersionOfProposal(sourceSnapshot);
 			bindGoal(goalSnapshot);
-			const extracted = await extractClaims(sourceSnapshot, goalSnapshot);
+			const extracted = await extractClaims(sourceSnapshot, goalSnapshot, ctx.signal);
+			throwIfRouterAborted(ctx.signal);
 			if (extracted.length === 0) return {
 				accept: false,
 				reason: "no extractable claim: source yields nothing to drive the research deeper"
@@ -7855,6 +7719,7 @@ function buildDriver(options, persistence, restored) {
 				if (registered && researchSourceVersionKey(registered) === researchSourceVersionKey(sourceVersion)) markAddressed(materializeEvidenceFor(/* @__PURE__ */ new Set([researchSourceVersionKey(sourceVersion)])));
 			}
 			await persist();
+			throwIfRouterAborted(ctx.signal);
 			return { accept: true };
 		},
 		/**
@@ -7898,8 +7763,9 @@ function buildDriver(options, persistence, restored) {
 		commitSources,
 		toLedger
 	};
-	async function extractClaims(source, goal) {
-		const fromLlm = await extractClaimsWithLlm(source, goal, claimsForExtraction());
+	async function extractClaims(source, goal, signal) {
+		const fromLlm = await extractClaimsWithLlm(source, goal, claimsForExtraction(), signal);
+		throwIfRouterAborted(signal);
 		if (fromLlm.length > 0) return fromLlm.slice(0, maxClaimsPerSource);
 		if (deterministicFallback) return deterministicClaims(source).slice(0, maxClaimsPerSource);
 		return [];
@@ -7920,11 +7786,13 @@ function buildDriver(options, persistence, restored) {
 		}
 		return [...known.values()];
 	}
-	async function extractClaimsWithLlm(source, goal, ledger) {
+	async function extractClaimsWithLlm(source, goal, ledger, signal) {
 		let router;
 		try {
-			router = resolveRouter();
-		} catch {
+			router = resolveRouter(signal);
+		} catch (error) {
+			throwIfRouterAborted(signal);
+			if (error?.name === "AbortError") throw error;
 			return [];
 		}
 		const excerpt = source.text.slice(0, 1800);
@@ -7946,9 +7814,12 @@ function buildDriver(options, persistence, restored) {
 				role: "user",
 				content: user
 			}], 1200);
-		} catch {
+		} catch (error) {
+			throwIfRouterAborted(signal);
+			if (error?.name === "AbortError") throw error;
 			return [];
 		}
+		throwIfRouterAborted(signal);
 		return parseExtractedClaims(raw, ledger);
 	}
 	/**