@tangle-network/agent-knowledge 17.1.9 → 18.0.0

package/dist/index.js

@@ -1,10 +1,11 @@
-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 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-BVT9JWDL.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";
@@ -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);
-			const result = await options.evaluateAnswers({
+			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 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 },
@@ -6296,7 +6341,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 +6353,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 +6446,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 +6454,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 +6482,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) {
@@ -6856,7 +6904,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,
@@ -7672,8 +7721,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 +7894,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 +7916,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 +7960,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 +7983,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 +8011,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);
 	}
 	/**