@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/domains/context/extension.ts

@@ -1,29 +1,17 @@
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { BusChannels, type ContextActivityPayload } from "../../core/bus-events.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { clioDataDir } from "../../core/xdg.js";
 import { loadMemoryRecordsSync } from "../memory/index.js";
-import { detectProjectType } from "../session/workspace/project-type.js";
+import { detectProjectType, type ProjectType } from "../session/workspace/project-type.js";
 import { adoptionSourcesChanged } from "./adoption.js";
 import { runBootstrap } from "./bootstrap.js";
 import { runContextClear } from "./clear.js";
-import { tryReadClioMd } from "./clio-md.js";
-import { createSlicer } from "./codewiki/cooperative.js";
-import {
-	buildCodewiki,
-	type Codewiki,
-	codewikiNeedsBackfill,
-	codewikiPath,
-	parseCodewikiRaw,
-	readCodewikiAsync,
-	syncCodewiki,
-	updateCodewikiPaths,
-	writeCodewiki,
-} from "./codewiki/indexer.js";
+import { loadProjectClioMd } from "./clio-md.js";
+import { codewikiPath } from "./codewiki/artifact.js";
+import { coordinateCodewikiWrite, drainCodewikiWrites } from "./codewiki/coordinator.js";
 import type { ContextContract, ContextState } from "./contract.js";
-import { computeFingerprintAsync, isStale } from "./fingerprint.js";
 import { renderPromptContext } from "./prompt-context.js";
 import { runContextRefresh } from "./refresh.js";
 import { type ClioProjectState, readClioState, writeClioState } from "./state.js";
@@ -40,10 +28,11 @@ function persistState(
 	indexedAt: string,
 	prev: ClioProjectState | null,
 	codewikiVersion: number,
+	projectType: ProjectType,
 ): void {
 	writeClioState(cwd, {
 		version: 1,
-		projectType: prev?.projectType ?? detectProjectType(cwd),
+		projectType: prev?.projectType ?? projectType,
 		fingerprint,
 		codewikiVersion,
 		...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
@@ -58,8 +47,10 @@ function persistState(
 /**
  * Rebuild the codewiki when it is missing or the working tree has drifted since
  * the last full index. Runs once at session start (catches branch switches, git
- * pulls, and out-of-session edits) and again at stop. Skips projects that were
- * never indexed so we never index an arbitrary directory unprompted.
+ * pulls, and out-of-session edits). Skips projects that were never indexed so we
+ * never index an arbitrary directory unprompted. This is the only place a
+ * session reconciles the index with the tree: in-session edits arrive through
+ * `noteFileChanges`, and stop() deliberately does no indexing at all.
  *
  * Every phase runs through one shared slicer. This work overlaps a mounted TUI:
  * before slicing, a drifted tree on a 1100-file repository held the event loop
@@ -73,36 +64,27 @@ async function ensureCodewikiFresh(cwd: string): Promise<void> {
 	if (process.env.CLIO_CODER_BOOTSTRAP_GENERATE_CHILD === "1") return;
 	const state = readClioState(cwd);
 	if (!state && !existsSync(codewikiPath(cwd))) return;
-	const slicer = createSlicer();
-	const codewiki = await readCodewikiAsync(cwd);
-	const fingerprint = await computeFingerprintAsync(cwd, codewiki, { slicer });
-	const stale =
-		!state ||
-		isStale(state.fingerprint, fingerprint) ||
-		!existsSync(codewikiPath(cwd)) ||
-		!codewiki ||
-		codewikiNeedsBackfill(codewiki);
-	if (!stale) return;
 	const indexedAt = new Date().toISOString();
-	const projectType = state?.projectType ?? detectProjectType(cwd);
-	const synced = codewiki
-		? await syncCodewiki(cwd, codewiki, { slicer })
-		: await buildCodewiki({ cwd, language: projectType, generatedAt: indexedAt }, { slicer });
-	writeCodewiki(cwd, synced);
-	persistState(cwd, await computeFingerprintAsync(cwd, synced, { slicer }), indexedAt, state, synced.version);
+	await coordinateCodewikiWrite(
+		cwd,
+		(current, workspace) => {
+			const language = readClioState(workspace)?.projectType ?? current?.language;
+			return {
+				kind: "ensure",
+				cwd,
+				...(language ? { language } : {}),
+				current,
+				previous: readClioState(workspace)?.fingerprint ?? null,
+			};
+		},
+		{
+			afterCommit: ({ codewiki, fingerprint }, workspace) =>
+				persistState(workspace, fingerprint, indexedAt, readClioState(workspace), codewiki.version, codewiki.language),
+		},
+	);
 }
 
 const CONTEXT_STATE_CACHE_TTL_MS = 1500;
-const CODEWIKI_CACHE_LIMIT = 4;
-
-interface CachedCodewiki {
-	hash: string;
-	codewiki: Codewiki;
-}
-
-function codewikiContentHash(raw: string): string {
-	return createHash("sha256").update(raw).digest("hex");
-}
 
 function memoryCount(): number {
 	try {
@@ -113,11 +95,16 @@ function memoryCount(): number {
 }
 
 function resolveClioMdState(cwd: string): ContextState["clioMd"] {
-	const clio = tryReadClioMd(cwd);
-	if (!clio) return "none";
-	if (!clio.ok) return "malformed";
+	const clio = loadProjectClioMd(cwd);
+	if (clio.files.length === 0 && clio.errors.length === 0) return "none";
+	if (clio.errors.length > 0) return "malformed";
 	const state = readClioState(cwd);
-	if (state?.contextSources !== undefined && adoptionSourcesChanged(state.contextSources, { cwd })) {
+	const localStandardIsEffective = clio.files.some((file) => file.path === join(resolve(cwd), "CLIO-CODER.md"));
+	if (
+		localStandardIsEffective &&
+		state?.contextSources !== undefined &&
+		adoptionSourcesChanged(state.contextSources, { cwd })
+	) {
 		return "stale";
 	}
 	return "ok";
@@ -152,12 +139,17 @@ function collectStartupHints(cwd: string, options: ContextBundleOptions = {}): s
 	} catch {
 		projectType = "unknown";
 	}
-	const clio = tryReadClioMd(cwd);
-	if (!clio && projectType !== "unknown" && options.noContextFiles !== true) {
+	const clio = loadProjectClioMd(cwd);
+	if (
+		clio.files.length === 0 &&
+		clio.errors.length === 0 &&
+		projectType !== "unknown" &&
+		options.noContextFiles !== true
+	) {
 		hints.push("clio: No CLIO-CODER.md detected. Run /context init to explore the repo and bootstrap context.");
 	}
-	if (clio && !clio.ok) {
-		hints.push(`clio: malformed CLIO-CODER.md ignored: ${clio.error}`);
+	for (const issue of clio.errors) {
+		hints.push(`clio: malformed ${issue.path} ignored: ${issue.error}`);
 	}
 	const state = readClioState(cwd);
 	if (!state) return hints;
@@ -172,44 +164,9 @@ export function createContextBundle(
 	options: ContextBundleOptions = {},
 ): DomainBundle<ContextContract> {
 	let lastCwd = process.cwd();
+	let stopping = false;
 	let startupHints: string[] = [];
 	const contextState = createContextStateReader();
-	const codewikiCache = new Map<string, CachedCodewiki>();
-	const rememberCodewiki = (cwd: string, hash: string, codewiki: Codewiki): void => {
-		codewikiCache.delete(cwd);
-		codewikiCache.set(cwd, { hash, codewiki });
-		while (codewikiCache.size > CODEWIKI_CACHE_LIMIT) {
-			const oldest = codewikiCache.keys().next().value;
-			if (oldest === undefined) break;
-			codewikiCache.delete(oldest);
-		}
-	};
-	const readCachedCodewiki = (cwd: string): Codewiki | null => {
-		let raw: string;
-		try {
-			raw = readFileSync(codewikiPath(cwd), "utf8");
-		} catch {
-			codewikiCache.delete(cwd);
-			return null;
-		}
-		const hash = codewikiContentHash(raw);
-		const cached = codewikiCache.get(cwd);
-		if (cached && cached.hash === hash) {
-			rememberCodewiki(cwd, hash, cached.codewiki);
-			return cached.codewiki;
-		}
-		const codewiki = parseCodewikiRaw(raw);
-		if (!codewiki) {
-			codewikiCache.delete(cwd);
-			return null;
-		}
-		rememberCodewiki(cwd, hash, codewiki);
-		return codewiki;
-	};
-	const writeCachedCodewiki = (cwd: string, codewiki: Codewiki): void => {
-		const serialized = writeCodewiki(cwd, codewiki);
-		rememberCodewiki(cwd, codewikiContentHash(serialized), codewiki);
-	};
 	const onStart = (): void => {
 		lastCwd = process.cwd();
 		void ensureCodewikiFresh(lastCwd).catch(() => {
@@ -222,31 +179,38 @@ export function createContextBundle(
 
 	// Incremental updates are read-modify-write on the artifact; overlapping runs
 	// would compute from a stale base and drop each other's records, so batches
-	// serialize through this queue and stop() drains it before its final rebuild.
+	// serialize through this queue and stop() drains it before the process exits.
 	let incrementalQueue: Promise<void> = Promise.resolve();
 	const noteFileChanges = (paths: ReadonlyArray<string>, cwd: string = lastCwd): void => {
+		if (stopping) return;
+		const workspace = resolve(cwd);
 		incrementalQueue = incrementalQueue
 			.then(async () => {
 				if (paths.length === 0) return;
-				const codewiki = readCachedCodewiki(cwd);
-				if (!codewiki) return; // Not indexed yet; session start/stop owns first build.
 				const rel = paths
-					.map((p) => (isAbsolute(p) ? relative(cwd, p) : p))
+					.map((p) => (isAbsolute(p) ? relative(workspace, p) : p))
 					.filter((p) => p.length > 0 && !p.startsWith(".."));
 				// Fires after every write the agent makes, mid-turn, with the TUI
 				// mounted; an edge rebuild here is the same cost as one at start.
-				const slicer = createSlicer();
-				const updated = await updateCodewikiPaths(cwd, codewiki, rel, { slicer });
-				if (updated === codewiki) return; // No indexable file actually changed.
-				writeCachedCodewiki(cwd, updated);
-				persistState(
-					cwd,
-					await computeFingerprintAsync(cwd, updated, { slicer }),
-					new Date().toISOString(),
-					readClioState(cwd),
-					updated.version,
+				await coordinateCodewikiWrite(
+					workspace,
+					(current) => (current ? { kind: "incremental", cwd: workspace, current, paths: rel } : null),
+					{
+						requireExisting: true,
+						afterCommit: ({ codewiki, fingerprint, changed }, committedWorkspace) => {
+							if (!changed) return;
+							persistState(
+								committedWorkspace,
+								fingerprint,
+								new Date().toISOString(),
+								readClioState(committedWorkspace),
+								codewiki.version,
+								codewiki.language,
+							);
+						},
+					},
 				);
-				contextState.invalidate(cwd);
+				contextState.invalidate(workspace);
 			})
 			.catch(() => {
 				// Best-effort: never let incremental indexing surface as a tool error.
@@ -259,37 +223,23 @@ export function createContextBundle(
 			unsubscribeSessionStart = _context.bus.on(BusChannels.SessionStart, onStart);
 		},
 		async stop() {
+			stopping = true;
 			unsubscribeSessionStart?.();
 			unsubscribeSessionStart = null;
-			await incrementalQueue;
-			// Stop runs the same rebuild as start and the TUI is still mounted while
-			// it drains, so it shares the sliced path rather than blocking the quit.
-			const slicer = createSlicer();
-			const projectType = detectProjectType(lastCwd);
+			// Everything the session changed already went through noteFileChanges,
+			// so the only work still owed at stop is the tail of that queue. Nothing
+			// here re-indexes: a stop-time rebuild used to run the same full scan as
+			// start on every exit, on the shutdown path, where one synchronous
+			// tree-sitter parse of a large file holds the event loop past every
+			// shutdown budget (issue #99). Out-of-band drift is start's job on the
+			// next session, and a never-indexed cwd stays that way; indexing an
+			// arbitrary directory because a process exited in it is not a favor.
+			await Promise.all([incrementalQueue, drainCodewikiWrites(lastCwd)]);
 			const state = readClioState(lastCwd);
-			let codewiki = readCachedCodewiki(lastCwd);
-			let fingerprint = await computeFingerprintAsync(lastCwd, codewiki, { slicer });
-			let lastIndexedAt = state?.lastIndexedAt;
-			if (!state || isStale(state.fingerprint, fingerprint) || !codewiki || codewikiNeedsBackfill(codewiki)) {
-				lastIndexedAt = new Date().toISOString();
-				codewiki = codewiki
-					? await syncCodewiki(lastCwd, codewiki, { slicer })
-					: await buildCodewiki({ cwd: lastCwd, language: projectType, generatedAt: lastIndexedAt }, { slicer });
-				writeCachedCodewiki(lastCwd, codewiki);
-				fingerprint = await computeFingerprintAsync(lastCwd, codewiki, { slicer });
-			}
-			writeClioState(lastCwd, {
-				version: 1,
-				projectType,
-				fingerprint,
-				...(codewiki ? { codewikiVersion: codewiki.version } : {}),
-				...(state?.contextSources ? { contextSources: state.contextSources } : {}),
-				...(state?.contextSourceHash ? { contextSourceHash: state.contextSourceHash } : {}),
-				...(state?.lastBootstrap ? { lastBootstrap: state.lastBootstrap } : {}),
-				...(state?.lastInitAt ? { lastInitAt: state.lastInitAt } : {}),
-				lastSessionAt: new Date().toISOString(),
-				...(lastIndexedAt ? { lastIndexedAt } : {}),
-			});
+			if (!state) return;
+			// The fingerprint is left as the last index wrote it. Stamping a fresh
+			// one without re-indexing would hide drift from the next start.
+			writeClioState(lastCwd, { ...state, lastSessionAt: new Date().toISOString() });
 		},
 	};
 
@@ -381,20 +331,21 @@ export function createContextBundle(
 		},
 		renderPromptContext,
 		projectStructuredContext(cwd = process.cwd()) {
-			const clio = tryReadClioMd(cwd);
-			if (!clio?.ok) return null;
+			const clio = loadProjectClioMd(cwd).value;
+			if (!clio) return null;
 			// Exact-title allowlist: "Verification expectations" is the only
 			// custom section ever projected to workers (verification class only,
 			// enforced dispatch-side). Same case-insensitive comparison as
 			// clio-md's sectionBody().
-			const verification = clio.value.sections.find(
-				(section) => section.title.toLowerCase() === "verification expectations",
-			);
-			const verificationBody = verification?.body.trim() ?? "";
+			const verificationBody = clio.sections
+				.filter((section) => section.title.toLowerCase() === "verification expectations")
+				.map((section) => section.body.trim())
+				.filter((body) => body.length > 0)
+				.join("\n\n");
 			return {
-				projectName: clio.value.projectName,
-				conventions: [...clio.value.conventions],
-				invariants: [...clio.value.invariants],
+				projectName: clio.projectName,
+				conventions: [...clio.conventions],
+				invariants: [...clio.invariants],
 				...(verificationBody.length > 0 ? { verificationExpectations: verificationBody } : {}),
 			};
 		},

package/src/domains/context/fingerprint.ts

@@ -4,8 +4,10 @@ import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { enumerateWorkspaceFiles, enumerateWorkspaceFilesAsync } from "../../core/workspace-files.js";
+import { readCodewiki, readCodewikiAsync } from "./codewiki/artifact.js";
 import { type CooperativeSlicer, createSlicer } from "./codewiki/cooperative.js";
-import { type Codewiki, isIndexablePath, readCodewiki, readCodewikiAsync } from "./codewiki/indexer.js";
+import { isIndexablePath } from "./codewiki/paths.js";
+import type { Codewiki } from "./codewiki/schema.js";
 import { EXCLUDED_DIRS } from "./excluded-dirs.js";
 
 const execFileAsync = promisify(execFile);

package/src/domains/context/index.ts

@@ -1,19 +1,3 @@
-import type { DomainModule } from "../../core/domain-loader.js";
-import { type ContextBundleOptions, createContextBundle } from "./extension.js";
-import { ContextManifest } from "./manifest.js";
-
-export const ContextDomainModule: DomainModule = {
-	manifest: ContextManifest,
-	createExtension: createContextBundle,
-};
-
-export function createContextDomainModule(options: ContextBundleOptions = {}): DomainModule {
-	return {
-		manifest: ContextManifest,
-		createExtension: (context) => createContextBundle(context, options),
-	};
-}
-
 export {
 	type AdoptionScanResult,
 	type AdoptionSourcesChangedOptions,
@@ -39,21 +23,26 @@ export {
 	runBootstrap,
 } from "./bootstrap.js";
 export { type RunContextClearInput, type RunContextClearResult, runContextClear } from "./clear.js";
-export { parseClioMd, serializeClioMd, tryReadClioMd } from "./clio-md.js";
-export { type CooperativeSlicer, createSlicer, INDEX_SLICE_MS } from "./codewiki/cooperative.js";
-export { renderCodewikiDigest } from "./codewiki/digest.js";
+export { loadProjectClioMd, parseClioMd, serializeClioMd, tryReadClioMd } from "./clio-md.js";
 export {
-	buildCodewiki,
-	CODEWIKI_VERSION,
 	codewikiEntries,
 	codewikiNeedsBackfill,
+	codewikiPath,
+	parseCodewikiRaw,
 	readCodewiki,
 	readCodewikiAsync,
+	serializeCodewiki,
 	structuralCodewikiHash,
+	writeCodewiki,
+} from "./codewiki/artifact.js";
+export { type CooperativeSlicer, createSlicer, INDEX_SLICE_MS } from "./codewiki/cooperative.js";
+export { renderCodewikiDigest } from "./codewiki/digest.js";
+export {
+	buildCodewiki,
 	syncCodewiki,
 	updateCodewikiPaths,
-	writeCodewiki,
 } from "./codewiki/indexer.js";
+export { CODEWIKI_VERSION } from "./codewiki/schema.js";
 export type { ContextContract, ContextState, ProjectPromptContext, ProjectStructuredContext } from "./contract.js";
 export {
 	type ComputeFingerprintAsyncOptions,
@@ -80,6 +69,7 @@ export {
 	type RunContextRefreshResult,
 	runContextRefresh,
 } from "./refresh.js";
+export { type ContextBundleOptions, ContextDomainModule, createContextDomainModule } from "./runtime.js";
 export {
 	type BootstrapGenerationMode,
 	type BootstrapGenerationState,

package/src/domains/context/project-metadata.ts

@@ -112,6 +112,25 @@ function tomlTableValue(raw: string, table: string, key: string): string | null
 	return null;
 }
 
+/**
+ * Whether a TOML file declares the named top-level table, e.g. `tool.tox`.
+ * A trimmed line must start with `[table]` and carry nothing after it but an
+ * optional `# comment`, the only content TOML itself allows there. A raw
+ * `raw.includes("[table]")` check would also fire on a comment mentioning the
+ * table or a string value that happens to contain the same bracketed text;
+ * anchoring to the start of the line rules both out without a TOML parser,
+ * while still accepting the valid `[table] # comment` form that a plain
+ * equality check would have missed.
+ */
+export function hasTomlTable(raw: string, table: string): boolean {
+	const header = `[${table}]`;
+	return raw.split(/\r?\n/u).some((line) => {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith(header)) return false;
+		return /^\s*(?:#.*)?$/u.test(trimmed.slice(header.length));
+	});
+}
+
 /** One `KEY = value` line from a Doxyfile or an INI-shaped config. */
 function keyEqualsValue(raw: string, key: string): string | null {
 	const match = new RegExp(`^[ \\t]*${key}[ \\t]*(?:\\+?=)[ \\t]*(.+)$`, "mu").exec(raw);

package/src/domains/context/prompt-context.ts

@@ -1,11 +1,11 @@
 import { detectProjectType } from "../session/workspace/project-type.js";
 import {
+	loadProjectClioMd,
 	type ParsedClioMd,
 	renderProjectContextFragment,
 	renderProjectTypeFragment,
-	tryReadClioMd,
 } from "./clio-md.js";
-import { readCodewiki } from "./codewiki/indexer.js";
+import { readCodewiki } from "./codewiki/artifact.js";
 import type { ProjectPromptContext } from "./contract.js";
 import { computeFingerprintCached, isStale } from "./fingerprint.js";
 import { readClioState } from "./state.js";
@@ -14,7 +14,7 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
 
 /**
  * Render the project prompt context for `cwd`: the project-type marker, the
- * CLIO-CODER.md fragment when a parseable handbook exists, the codewiki availability
+ * effective CLIO-CODER.md fragments when parseable handbooks exist, the codewiki availability
  * marker, and the Markdown wiki marker when a valid wiki exists. Shared by the
  * prompts extension (session compile),
  * context-init preload reporting, and `clio-coder config inspect`, so every surface
@@ -24,13 +24,12 @@ export function renderPromptContext(cwd: string): ProjectPromptContext {
 	const projectType = detectProjectType(cwd);
 	const pieces = [renderProjectTypeFragment(projectType)];
 	const warnings: string[] = [];
-	const clio = tryReadClioMd(cwd);
-	let clioMd: ParsedClioMd | null = null;
-	if (clio?.ok) {
-		clioMd = clio.value;
-		pieces.push(renderProjectContextFragment(clio.value));
+	const loadedClioMd = loadProjectClioMd(cwd);
+	const clioMd: ParsedClioMd | null = loadedClioMd.value;
+	for (const file of loadedClioMd.files) pieces.push(renderProjectContextFragment(file.value, file.path));
+	for (const issue of loadedClioMd.errors) {
+		warnings.push(`clio: malformed ${issue.path} ignored: ${issue.error}`);
 	}
-	if (clio && !clio.ok) warnings.push(`clio: malformed CLIO-CODER.md ignored: ${clio.error}`);
 	const codewiki = readCodewiki(cwd);
 	if (codewiki) {
 		const state = readClioState(cwd);
@@ -58,5 +57,5 @@ export function renderPromptContext(cwd: string): ProjectPromptContext {
 		const suffix = notes.length > 0 ? ` (${notes.join("; ")}; run clio-coder context wiki --update)` : "";
 		pieces.push(`<wiki>${pages.length} pages at .clio-coder/wiki (start: quickstart.md)${suffix}</wiki>`);
 	}
-	return { text: pieces.join("\n\n"), clioMd, warnings };
+	return { text: pieces.join("\n\n"), clioMd, warnings, handbookFiles: loadedClioMd.files.map((file) => file.path) };
 }

package/src/domains/context/refresh.ts

@@ -3,8 +3,9 @@ import { join } from "node:path";
 import { detectProjectType } from "../session/workspace/project-type.js";
 import { type BootstrapIo, type BootstrapProgressSink, codewikiSections } from "./bootstrap.js";
 import { serializeClioMd, tryReadClioMd } from "./clio-md.js";
-import { buildCodewiki, type Codewiki, writeCodewiki } from "./codewiki/indexer.js";
-import { computeFingerprint, type Fingerprint } from "./fingerprint.js";
+import { coordinateCodewikiWrite } from "./codewiki/coordinator.js";
+import type { Codewiki } from "./codewiki/schema.js";
+import type { Fingerprint } from "./fingerprint.js";
 import { readClioState, writeClioState } from "./state.js";
 import { type RunWikiGenerateResult, runWikiGenerate, type WikiGenerate } from "./wiki/generate.js";
 import { readWikiMeta } from "./wiki/meta.js";
@@ -113,24 +114,30 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 	const indexedAt = now().toISOString();
 
 	input.onProgress?.({ phase: "codewiki", status: "started", message: "rebuilding codewiki" });
-	const codewiki = await buildCodewiki({ cwd, language: projectType, generatedAt: indexedAt });
-	writeCodewiki(cwd, codewiki);
-	const fingerprint = computeFingerprint(cwd, codewiki);
-	const clioMd = curateClioMd(cwd, codewiki);
-
-	input.onProgress?.({ phase: "state", status: "running", message: "writing state" });
-	writeClioState(cwd, {
-		version: 1,
-		projectType,
-		fingerprint,
-		codewikiVersion: codewiki.version,
-		...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
-		...(prev?.contextSourceHash ? { contextSourceHash: prev.contextSourceHash } : {}),
-		...(prev?.lastBootstrap ? { lastBootstrap: prev.lastBootstrap } : {}),
-		...(prev?.lastInitAt ? { lastInitAt: prev.lastInitAt } : {}),
-		lastSessionAt: prev?.lastSessionAt ?? indexedAt,
-		lastIndexedAt: indexedAt,
+	let fingerprint: Fingerprint | undefined;
+	let clioMd: ClioMdCuration = "absent";
+	const coordinated = await coordinateCodewikiWrite(cwd, () => ({ kind: "build", cwd, language: projectType }), {
+		afterCommit: (result, workspace) => {
+			fingerprint = result.fingerprint;
+			clioMd = curateClioMd(workspace, result.codewiki);
+			input.onProgress?.({ phase: "state", status: "running", message: "writing state" });
+			const latest = readClioState(workspace);
+			writeClioState(workspace, {
+				version: 1,
+				projectType,
+				fingerprint: result.fingerprint,
+				codewikiVersion: result.codewiki.version,
+				...(latest?.contextSources ? { contextSources: latest.contextSources } : {}),
+				...(latest?.contextSourceHash ? { contextSourceHash: latest.contextSourceHash } : {}),
+				...(latest?.lastBootstrap ? { lastBootstrap: latest.lastBootstrap } : {}),
+				...(latest?.lastInitAt ? { lastInitAt: latest.lastInitAt } : {}),
+				lastSessionAt: latest?.lastSessionAt ?? indexedAt,
+				lastIndexedAt: indexedAt,
+			});
+		},
 	});
+	if (!coordinated || !fingerprint) throw new Error("codewiki refresh transaction did not commit");
+	const codewiki = coordinated.codewiki;
 
 	const entries = indexedSourceFileCount(codewiki);
 	let wikiResult: RunWikiGenerateResult | undefined;
@@ -154,7 +161,8 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 		hint = incompleteWikiHint(cwd) ?? (wikiStaleness(cwd).state === "stale" ? STALE_WIKI_REFRESH_HINT : undefined);
 	}
 
-	const handbookNote = clioMd === "updated" ? "; CLIO-CODER.md index sections updated" : "";
+	const committedClioMd = clioMd as ClioMdCuration;
+	const handbookNote = committedClioMd === "updated" ? "; CLIO-CODER.md index sections updated" : "";
 	input.io?.stdout(
 		`clio-coder context refresh: codewiki rebuilt (${entries} source file${entries === 1 ? "" : "s"})${handbookNote}\n`,
 	);
@@ -163,7 +171,7 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 		action: "refreshed",
 		codewikiEntries: entries,
 		fingerprint,
-		clioMd,
+		clioMd: committedClioMd,
 		...(wikiResult ? { wiki: wikiResult } : {}),
 		...(hint ? { hint } : {}),
 	};

package/src/domains/context/runtime.ts

@@ -0,0 +1,17 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { type ContextBundleOptions, createContextBundle } from "./extension.js";
+import { ContextManifest } from "./manifest.js";
+
+export const ContextDomainModule: DomainModule = {
+	manifest: ContextManifest,
+	createExtension: createContextBundle,
+};
+
+export function createContextDomainModule(options: ContextBundleOptions = {}): DomainModule {
+	return {
+		manifest: ContextManifest,
+		createExtension: (context) => createContextBundle(context, options),
+	};
+}
+
+export type { ContextBundleOptions } from "./extension.js";