@iowarp/clio-coder 0.4.4 → 0.4.6

package/src/domains/context/codewiki/build-worker.ts

@@ -1,43 +1,11 @@
 import { parentPort, workerData } from "node:worker_threads";
-import { detectProjectType } from "../../session/workspace/project-type.js";
-import { computeFingerprint, isStale } from "../fingerprint.js";
-import { codewikiNeedsBackfill } from "./artifact.js";
-import type {
-	CodewikiBuildWorkerMessage,
-	CodewikiBuildWorkerRequest,
-	CodewikiBuildWorkerResult,
-} from "./build-worker-protocol.js";
-import { buildCodewiki, syncCodewiki, updateCodewikiPaths } from "./indexer.js";
-
-async function execute(request: CodewikiBuildWorkerRequest): Promise<CodewikiBuildWorkerResult> {
-	if (request.kind === "build") {
-		const codewiki = await buildCodewiki({ cwd: request.cwd, language: request.language });
-		return { codewiki, fingerprint: computeFingerprint(request.cwd, codewiki), changed: true };
-	}
-	if (request.kind === "incremental") {
-		const codewiki = await updateCodewikiPaths(request.cwd, request.current, request.paths);
-		return {
-			codewiki,
-			fingerprint: computeFingerprint(request.cwd, codewiki),
-			changed: codewiki !== request.current,
-		};
-	}
-	if (request.current && !codewikiNeedsBackfill(request.current)) {
-		const currentFingerprint = computeFingerprint(request.cwd, request.current);
-		if (request.previous && !isStale(request.previous, currentFingerprint)) {
-			return { codewiki: request.current, fingerprint: currentFingerprint, changed: false };
-		}
-	}
-	const codewiki = request.current
-		? await syncCodewiki(request.cwd, request.current)
-		: await buildCodewiki({ cwd: request.cwd, language: request.language ?? detectProjectType(request.cwd) });
-	return { codewiki, fingerprint: computeFingerprint(request.cwd, codewiki), changed: true };
-}
+import { executeCodewikiBuildOutcome } from "./build-operation.js";
+import type { CodewikiBuildWorkerMessage, CodewikiBuildWorkerRequest } from "./build-worker-protocol.js";
 
 const port = parentPort;
 if (!port) throw new Error("codewiki build worker requires a worker_threads parent");
 
-execute(workerData as CodewikiBuildWorkerRequest).then(
+executeCodewikiBuildOutcome(workerData as CodewikiBuildWorkerRequest).then(
 	(result) => {
 		port.postMessage({ ok: true, result } satisfies CodewikiBuildWorkerMessage);
 		port.close();

package/src/domains/context/codewiki/coordinator.ts

@@ -4,9 +4,11 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Worker } from "node:worker_threads";
 import { withStateFileLock } from "../../../core/state-file-lock.js";
-import { codewikiPath, readCodewiki, writeCodewiki } from "./artifact.js";
+import { codewikiNeedsBackfill, codewikiPath, readCodewiki, writeCodewiki } from "./artifact.js";
 import type {
+	CodewikiArtifactRef,
 	CodewikiBuildWorkerMessage,
+	CodewikiBuildWorkerOutcome,
 	CodewikiBuildWorkerRequest,
 	CodewikiBuildWorkerResult,
 } from "./build-worker-protocol.js";
@@ -30,7 +32,30 @@ function buildWorkerUrl(): URL {
 	);
 }
 
-async function executeInWorker(request: CodewikiBuildWorkerRequest): Promise<CodewikiBuildWorkerResult> {
+function artifactRef(current: Codewiki): CodewikiArtifactRef {
+	return {
+		source: "artifact",
+		needsBackfill: codewikiNeedsBackfill(current),
+		loc: current.files.reduce((sum, file) => (file.lang === "config" ? sum : sum + file.loc), 0),
+	};
+}
+
+/**
+ * Hand the worker a reference to the committed artifact instead of the parsed
+ * object. Cloning the object serializes it on this thread, deserializes it on
+ * the worker, and repeats both on the way back, so the cost grows with index
+ * size and lands on the thread that renders the TUI. The substitution is made
+ * only when the selector returned the very object this transaction read under
+ * the lease (`held`), which is the committed file by construction; any other
+ * object is shipped as it was given.
+ */
+function byReference(request: CodewikiBuildWorkerRequest, held: Codewiki | null): CodewikiBuildWorkerRequest {
+	if (request.kind === "build" || request.current === null || "source" in request.current) return request;
+	if (held === null || request.current !== held) return request;
+	return { ...request, current: artifactRef(held) };
+}
+
+async function executeInWorker(request: CodewikiBuildWorkerRequest): Promise<CodewikiBuildWorkerOutcome> {
 	// Do not inherit test-runner/application `--import` hooks. In particular,
 	// `--import tsx` would be re-resolved from a hermetic fixture cwd before the
 	// source bootstrap can install its absolute loader.
@@ -44,7 +69,7 @@ async function executeInWorker(request: CodewikiBuildWorkerRequest): Promise<Cod
 	});
 	let timer: NodeJS.Timeout | undefined;
 	try {
-		return await new Promise<CodewikiBuildWorkerResult>((resolve, reject) => {
+		return await new Promise<CodewikiBuildWorkerOutcome>((resolve, reject) => {
 			let settled = false;
 			const finish = (callback: () => void): void => {
 				if (settled) return;
@@ -154,7 +179,10 @@ export function coordinateCodewikiWrite(
 			const current = options.readCurrent?.(workspace) ?? readCodewiki(workspace);
 			const request = await select(current, workspace);
 			if (!request) return null;
-			const worker = await executeInWorker({ ...request, cwd: workspace });
+			const outcome = await executeInWorker(byReference({ ...request, cwd: workspace }, current));
+			const codewiki = outcome.codewiki ?? current;
+			if (!codewiki) throw new Error("codewiki reconciliation returned no artifact");
+			const worker: CodewikiBuildWorkerResult = { codewiki, fingerprint: outcome.fingerprint, changed: outcome.changed };
 			await options.beforeCommit?.(worker, workspace);
 			const wrote = worker.changed || !existsSync(codewikiPath(workspace));
 			if (wrote) writeCodewiki(workspace, worker.codewiki);
@@ -171,11 +199,13 @@ export function coordinateCodewikiExclusive<T>(cwd: string, task: (workspace: st
 }
 
 /** Build a preview candidate in the worker without acquiring a writer lease or touching disk. */
-export function buildCodewikiCandidate(
+export async function buildCodewikiCandidate(
 	cwd: string,
 	language: Codewiki["language"],
 ): Promise<CodewikiBuildWorkerResult> {
-	return executeInWorker({ kind: "build", cwd: resolve(cwd), language });
+	const outcome = await executeInWorker({ kind: "build", cwd: resolve(cwd), language });
+	if (!outcome.codewiki) throw new Error("codewiki build returned no artifact");
+	return { codewiki: outcome.codewiki, fingerprint: outcome.fingerprint, changed: outcome.changed };
 }
 
 /** Await every writer already admitted for one workspace, including idle refresh. */

package/src/domains/context/codewiki/indexer.ts

@@ -850,11 +850,6 @@ function candidatePathsForImport(cwd: string, fromRel: string, specifier: string
 		const stripped = base.replace(/\.js$/, "");
 		for (const ext of [".ts", ".tsx", ".mts", ".cts"]) candidates.push(`${stripped}${ext}`);
 	}
-	if (/^[.]+[A-Za-z_]/.test(cleaned)) {
-		const pythonModule = cleaned.replace(/^\.+/, "").replace(/\./g, "/");
-		const pythonBase = resolve(fromDir, pythonModule);
-		candidates.push(`${pythonBase}.py`, join(pythonBase, "__init__.py"));
-	}
 	return uniqueSorted(
 		candidates.map((candidate) => normalizeRel(cwd, candidate)).filter((candidate) => !candidate.startsWith("..")),
 	);
@@ -878,10 +873,36 @@ function createImportResolver(cwd: string): {
 	const candidatesFor = (fromRel: string, specifier: string): string[] => {
 		// The candidate set is a function of the directory, not the file: every
 		// sibling importing the same specifier resolves through the same list.
-		const key = `${dirname(fromRel)}\0${specifier}`;
+		const python = /\.pyw?$/.test(fromRel);
+		const key = `${python}\0${dirname(fromRel)}\0${specifier}`;
 		let candidates = candidatesByOrigin.get(key);
 		if (!candidates) {
-			candidates = candidatePathsForImport(cwd, fromRel, specifier);
+			if (python) {
+				const fromDir = dirname(fromRel);
+				let packageRoot = fromDir;
+				while (packageRoot !== "." && isFile(join(packageRoot, "__init__.py"))) {
+					packageRoot = dirname(packageRoot);
+				}
+				const dots = /^\.+/.exec(specifier)?.[0].length ?? 0;
+				const modulePath = specifier.slice(dots).replace(/\./g, "/");
+				let bases: string[];
+				if (dots > 0) {
+					const parent = resolve(cwd, fromDir, ...Array<string>(dots - 1).fill(".."));
+					// A relative import must stay inside its package tree. Without
+					// __init__.py evidence, the workspace bounds namespace packages.
+					const root = resolve(cwd, packageRoot === fromDir ? "." : packageRoot);
+					const insidePackage = parent !== root || (root === resolve(cwd) && isFile("__init__.py"));
+					bases = insidePackage && !relative(root, parent).startsWith("..") ? [join(parent, modulePath)] : [];
+				} else {
+					bases = [resolve(cwd, modulePath)];
+					if (packageRoot !== fromDir && packageRoot !== ".") bases.push(resolve(cwd, packageRoot, modulePath));
+				}
+				candidates = [...new Set(bases.flatMap((base) => [join(base, "__init__.py"), `${base}.py`]))].map((candidate) =>
+					normalizeRel(cwd, candidate),
+				);
+			} else {
+				candidates = candidatePathsForImport(cwd, fromRel, specifier);
+			}
 			candidatesByOrigin.set(key, candidates);
 		}
 		return candidates;
@@ -1020,7 +1041,8 @@ export async function buildCodewiki(input: BuildCodewikiInput, options: Codewiki
 /**
  * Apply an incremental update for a set of changed paths. The changed file
  * records and symbols are replaced in-place, and edges are rebuilt from stored
- * imports across the merged file set.
+ * imports across the merged file set. Unchanged content retains its records;
+ * a batch with no index changes returns the original artifact without parsing.
  */
 export async function updateCodewikiPaths(
 	cwd: string,
@@ -1045,30 +1067,42 @@ export async function updateCodewikiPaths(
 		// Ignore and index metadata can add or remove paths that are not present in
 		// the mutation batch itself. Re-enumerate once so incremental visibility
 		// remains byte-equivalent to a full build.
-		return buildCodewiki({ cwd, language: codewiki.language }, options);
+		return syncCodewiki(cwd, codewiki, options);
 	}
 	const slicer = options.slicer ?? createSlicer();
-	const existingPaths = new Set(codewiki.files.map((file) => file.path));
+	const existingFiles = new Map(codewiki.files.map((file) => [file.path, file]));
 	const visiblePaths = new Set(filterWorkspaceFileCandidates(cwd, normalizedPaths, EXCLUDED_DIRS));
 	const readFile = options.readFile ?? defaultReadFile;
-	const changedPathSet = new Set(normalizedPaths);
+	const currentTexts = new Map<string, string>();
+	const changedPathSet = new Set<string>();
 	const rebuildPaths: string[] = [];
-	let hasIndexChange = false;
 	for (const relPath of normalizedPaths) {
-		const wasIndexed = existingPaths.has(relPath);
+		const existing = existingFiles.get(relPath);
 		const isCurrentIndexableFile = isIndexablePath(relPath) && visiblePaths.has(relPath);
-		if (!wasIndexed && !isCurrentIndexableFile) continue;
-		hasIndexChange = true;
-		if (isCurrentIndexableFile) rebuildPaths.push(relPath);
+		if (!existing && !isCurrentIndexableFile) continue;
+		if (isCurrentIndexableFile) {
+			const text = readFile(join(cwd, relPath));
+			if (text !== null) {
+				if (existing?.hash === contentHash(text)) continue;
+				currentTexts.set(relPath, text);
+				rebuildPaths.push(relPath);
+			}
+		}
+		changedPathSet.add(relPath);
 	}
-	if (!hasIndexChange) return codewiki;
+	if (changedPathSet.size === 0) return codewiki;
 	const rebuiltFiles: BuiltFile[] = [];
 	if (rebuildPaths.length > 0) {
 		const treeSitterExtractor = await loadTreeSitterExtractor();
 		await treeSitterExtractor.ensureGrammarsForPaths(rebuildPaths);
 		for (const relPath of rebuildPaths) {
 			await slicer.tick();
-			const built = buildFile(cwd, relPath, treeSitterExtractor, readFile);
+			const built = buildFile(
+				cwd,
+				relPath,
+				treeSitterExtractor,
+				(path) => currentTexts.get(normalizeRel(cwd, path)) ?? null,
+			);
 			if (built) rebuiltFiles.push(built);
 		}
 	}
@@ -1123,7 +1157,13 @@ export async function syncCodewiki(
 	for (const relPath of indexedFiles.keys()) {
 		if (!currentFiles.has(relPath)) changedPaths.add(relPath);
 	}
-	if (changedPaths.size === 0) return codewiki;
+	if (changedPaths.size === 0) {
+		// A fingerprint-domain upgrade also reconciles resolver changes even
+		// when source hashes still match the old artifact.
+		if (!codewiki.files.some((file) => file.lang === "python")) return codewiki;
+		const edges = await buildEdges(cwd, codewiki.files, slicer);
+		return JSON.stringify(edges) === JSON.stringify(codewiki.edges) ? codewiki : { ...codewiki, edges };
+	}
 	const syncOptions: CodewikiBuildOptions = {
 		...options,
 		slicer,

package/src/domains/context/contract.ts

@@ -12,9 +12,13 @@ export interface ProjectPromptContext {
 	/**
 	 * Absolute paths of the effective project handbooks, ancestor to nearest.
 	 * An override resets the inherited chain, so this names exactly the files
-	 * whose content is in `text`; empty when no selected handbook parsed.
+	 * whose content is in `text`; empty when no selected handbook loaded.
 	 */
 	handbookFiles: string[];
+	/** Captured authored bytes from the same load as text, ancestor to nearest. */
+	handbookSources: ReadonlyArray<{ path: string; source: string }>;
+	/** Trusted renderer products, kept separate from authored Markdown. */
+	supportFragments: readonly string[];
 }
 
 /**
@@ -52,7 +56,7 @@ export interface ContextContract extends DomainContract {
 	renderPromptContext(cwd: string): ProjectPromptContext;
 	/**
 	 * Effective project handbook fields (project name, conventions, invariants)
-	 * or null when no selected handbook parses. Never returns raw handbook
+	 * or null when no selected handbook has a structured projection. Never returns raw handbook
 	 * text; used by dispatch to give workers bounded project context.
 	 */
 	projectStructuredContext(cwd?: string): ProjectStructuredContext | null;

package/src/domains/context/extension.ts

@@ -135,9 +135,13 @@ export interface ContextBundleOptions {
 
 function collectStartupHints(cwd: string, options: ContextBundleOptions = {}): string[] {
 	const hints: string[] = [];
+	// Runs at session start with the TUI mounting. Detection walks the tree and
+	// reads every header, so an indexed project answers from the type its state
+	// already records; only a never-indexed directory pays for detection.
+	const state = readClioState(cwd);
 	let projectType: ReturnType<typeof detectProjectType>;
 	try {
-		projectType = detectProjectType(cwd);
+		projectType = state?.projectType ?? detectProjectType(cwd);
 	} catch {
 		projectType = "unknown";
 	}
@@ -159,7 +163,6 @@ function collectStartupHints(cwd: string, options: ContextBundleOptions = {}): s
 	if (!contract.ok) {
 		hints.push(`clio-coder: validation contract ignored, rigor stays normal: ${describeValidationContract(contract)}`);
 	}
-	const state = readClioState(cwd);
 	if (!state) return hints;
 	if (state.contextSources !== undefined && adoptionSourcesChanged(state.contextSources, { cwd })) {
 		hints.push("clio-coder: Imported agent context changed. Run /context init --adopt to refresh.");
@@ -202,7 +205,16 @@ export function createContextBundle(
 				// mounted; an edge rebuild here is the same cost as one at start.
 				await coordinateCodewikiWrite(
 					workspace,
-					(current) => (current ? { kind: "incremental", cwd: workspace, current, paths: rel } : null),
+					(current) =>
+						current
+							? {
+									kind: "incremental",
+									cwd: workspace,
+									current,
+									paths: rel,
+									previous: readClioState(workspace)?.fingerprint ?? null,
+								}
+							: null,
 					{
 						requireExisting: true,
 						afterCommit: ({ codewiki, fingerprint, changed }, committedWorkspace) => {
@@ -251,6 +263,43 @@ export function createContextBundle(
 		},
 	};
 
+	function promptSourceState(cwd: string): string | null {
+		try {
+			return JSON.stringify(renderPromptContext(cwd));
+		} catch {
+			// Enumeration can fail on unreadable or oversized trees. Bookkeeping
+			// must not prevent clear/recovery or replace the operation's own error.
+			return null;
+		}
+	}
+
+	/**
+	 * Explicit operations are snapshot boundaries. A rejected operation can still
+	 * have published an index or handbook before failing; compare the actual
+	 * project context so that failure refreshes when visible sources changed
+	 * or could not be inspected.
+	 * These disk reads happen at the command boundary, never on ordinary turns.
+	 */
+	async function withPromptSourceBoundary<T>(
+		cwd: string,
+		operation: () => Promise<T>,
+		committed: (result: T) => boolean,
+	): Promise<T> {
+		const workspace = resolve(cwd);
+		const before = promptSourceState(workspace);
+		let refreshSources = false;
+		try {
+			const result = await operation();
+			refreshSources = committed(result);
+			return result;
+		} finally {
+			if (refreshSources || before === null || promptSourceState(workspace) !== before) {
+				contextState.invalidate(workspace);
+				_context.bus.emit(BusChannels.ContextSourcesChanged, { cwd: workspace });
+			}
+		}
+	}
+
 	const contract: ContextContract = {
 		async runBootstrap(input) {
 			const emitProgress = (event: Omit<ContextActivityPayload, "kind" | "at">): void => {
@@ -258,7 +307,11 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				const result = await runBootstrap(input ? { ...input, onProgress: emitProgress } : { onProgress: emitProgress });
+				const result = await withPromptSourceBoundary(
+					input?.cwd ?? process.cwd(),
+					() => runBootstrap({ ...input, onProgress: emitProgress }),
+					(result) => result.summary.action !== "previewed",
+				);
 				const cwd = input?.cwd ?? process.cwd();
 				contextState.invalidate(cwd);
 				if (cwd === lastCwd) startupHints = collectStartupHints(cwd, options);
@@ -279,7 +332,11 @@ export function createContextBundle(
 			};
 			emitProgress({ phase: "done", status: "started", message: "clearing context" });
 			try {
-				const result = await runContextClear(input);
+				const result = await withPromptSourceBoundary(
+					input?.cwd ?? process.cwd(),
+					() => runContextClear(input),
+					(result) => result.action === "cleared",
+				);
 				const cwd = input?.cwd ?? process.cwd();
 				contextState.invalidate(cwd);
 				if (cwd === lastCwd) startupHints = collectStartupHints(cwd, options);
@@ -301,11 +358,16 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				const result = await runContextRefresh({
-					...input,
-					...(input?.wiki ? { decisions: input.decisions ?? (await currentDecisions(_context)) } : {}),
-					onProgress: emitProgress,
-				});
+				const result = await withPromptSourceBoundary(
+					input?.cwd ?? process.cwd(),
+					async () =>
+						runContextRefresh({
+							...input,
+							...(input?.wiki ? { decisions: input.decisions ?? (await currentDecisions(_context)) } : {}),
+							onProgress: emitProgress,
+						}),
+					() => true,
+				);
 				const cwd = input?.cwd ?? process.cwd();
 				contextState.invalidate(cwd);
 				if (cwd === lastCwd) startupHints = collectStartupHints(cwd, options);

package/src/domains/context/fingerprint.ts

@@ -1,6 +1,6 @@
 import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { enumerateWorkspaceFiles, enumerateWorkspaceFilesAsync } from "../../core/workspace-files.js";
@@ -80,18 +80,13 @@ async function currentGitHeadAsync(cwd: string): Promise<string | null> {
 	}
 }
 
-function countLines(filePath: string): number {
-	try {
-		const text = readFileSync(filePath, "utf8");
-		if (text.length === 0) return 0;
-		let lines = 1;
-		for (const ch of text) {
-			if (ch === "\n") lines += 1;
-		}
-		return lines;
-	} catch {
-		return 0;
+function countLines(text: string): number {
+	if (text.length === 0) return 0;
+	let lines = 1;
+	for (const ch of text) {
+		if (ch === "\n") lines += 1;
 	}
+	return lines;
 }
 
 function locFromCodewiki(codewiki: Codewiki | null): number | null {
@@ -99,6 +94,11 @@ function locFromCodewiki(codewiki: Codewiki | null): number | null {
 	return codewiki.files.reduce((sum, file) => (file.lang === "config" ? sum : sum + file.loc), 0);
 }
 
+function createTreeHash(): ReturnType<typeof createHash> {
+	// Migrate both unsalted and v2 metadata identities, including empty trees.
+	return createHash("sha256").update("clio-codewiki-tree:v3\n");
+}
+
 /**
  * Hash one file's identity into the tree hash and accumulate its line count.
  * Shared verbatim by the sync and sliced walks so the two produce identical
@@ -110,23 +110,32 @@ function accumulateFile(
 	hash: ReturnType<typeof createHash>,
 	artifactLoc: number | null,
 ): number {
-	const absPath = join(cwd, relPath);
-	let stat: ReturnType<typeof statSync>;
-	try {
-		stat = statSync(absPath);
-	} catch {
-		return 0;
-	}
-	hash.update(`${relPath}:${stat.size}:${Math.floor(stat.mtimeMs)}\n`);
-	if (artifactLoc === null && LOC_EXTENSIONS.has(extensionOf(relPath))) return countLines(absPath);
+	// Read failures must invalidate the operation, never certify a partial tree.
+	const contents = readFileSync(join(cwd, relPath));
+	const digest = createHash("sha256").update(contents).digest("hex");
+	hash.update(`${JSON.stringify(relPath)}:${digest}\n`);
+	if (artifactLoc === null && LOC_EXTENSIONS.has(extensionOf(relPath))) return countLines(contents.toString("utf8"));
 	return 0;
 }
 
-export function computeFingerprint(cwd: string, codewiki: Codewiki | null = readCodewiki(cwd)): Fingerprint {
+export interface ComputeFingerprintOptions {
+	/**
+	 * Line total recorded by an artifact the caller chose not to parse. The
+	 * tree hash never depends on it; it only keeps `loc` byte-identical to the
+	 * fingerprint the artifact's own build stamped.
+	 */
+	artifactLoc?: number;
+}
+
+export function computeFingerprint(
+	cwd: string,
+	codewiki: Codewiki | null = readCodewiki(cwd),
+	options: ComputeFingerprintOptions = {},
+): Fingerprint {
 	const files = enumerateWorkspaceFiles(cwd, EXCLUDED_DIRS).filter(isIndexablePath);
 
-	const hash = createHash("sha256");
-	const artifactLoc = locFromCodewiki(codewiki);
+	const hash = createTreeHash();
+	const artifactLoc = options.artifactLoc ?? locFromCodewiki(codewiki);
 	let loc = 0;
 	for (const relPath of files) loc += accumulateFile(cwd, relPath, hash, artifactLoc);
 
@@ -142,13 +151,9 @@ export interface ComputeFingerprintAsyncOptions {
 }
 
 /**
- * Same fingerprint, sliced. One `statSync` per visible file plus a `git
- * rev-parse` is tens of milliseconds on a large repository, which is a dropped
- * frame if it lands in one turn. Callers on a status-surface poll or on the
- * session-start path should use this; one-shot CLI paths need not bother.
- *
- * The enumeration itself runs through `enumerateWorkspaceFilesAsync` on the
- * same slicer, so the former 34 ms synchronous floor is gone too.
+ * Same content fingerprint, with cooperative yields between file reads and
+ * during enumeration. Individual reads remain synchronous; callers on status
+ * surfaces and session-start paths avoid a single uninterrupted whole-tree scan.
  */
 export async function computeFingerprintAsync(
 	cwd: string,
@@ -160,7 +165,7 @@ export async function computeFingerprintAsync(
 	await slicer.tick();
 	const files = (await enumerateWorkspaceFilesAsync(cwd, EXCLUDED_DIRS, undefined, slicer)).filter(isIndexablePath);
 
-	const hash = createHash("sha256");
+	const hash = createTreeHash();
 	const artifactLoc = locFromCodewiki(artifact);
 	let loc = 0;
 	for (const relPath of files) {
@@ -178,13 +183,13 @@ export async function computeFingerprintAsync(
 export function computeFingerprintCached(
 	cwd: string,
 	codewiki: Codewiki | null = readCodewiki(cwd),
-	options: FingerprintCacheOptions = {},
+	options: FingerprintCacheOptions & ComputeFingerprintOptions = {},
 ): Fingerprint {
 	const now = Date.now();
 	const cached = cachedFingerprints.get(cwd);
 	if (cached && cached.expiresAtMs > now) return cached.fingerprint;
 
-	const fingerprint = computeFingerprint(cwd, codewiki);
+	const fingerprint = computeFingerprint(cwd, codewiki, options);
 	const ttlMs = options.ttlMs ?? DEFAULT_FINGERPRINT_CACHE_TTL_MS;
 	cachedFingerprints.set(cwd, {
 		fingerprint,

package/src/domains/context/index.ts

@@ -23,7 +23,13 @@ export {
 	runBootstrap,
 } from "./bootstrap.js";
 export { type RunContextClearInput, type RunContextClearResult, runContextClear } from "./clear.js";
-export { loadProjectClioMd, parseClioMd, serializeClioMd, tryReadClioMd } from "./clio-md.js";
+export {
+	loadProjectClioMd,
+	parseClioMd,
+	renderProjectContextFragment,
+	serializeClioMd,
+	tryReadClioMd,
+} from "./clio-md.js";
 export {
 	codewikiEntries,
 	codewikiNeedsBackfill,