@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/domains/context/bootstrap.ts

@@ -1,9 +1,11 @@
 import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, parse } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import type { ContextActivityPayload } from "../../core/bus-events.js";
 import { createTomlFileReader, type TomlFileReader, tomlTableAt } from "../../core/toml.js";
-import { classifyProjectPreload, type ProjectPreloadClass } from "../prompts/preload.js";
+import { INTEROP_AGENT_KINDS } from "../interop/registry.js";
+import { type ProjectPreloadClass, selectProjectPreload } from "../prompts/preload.js";
 import { detectProjectType, type ProjectType } from "../session/workspace/project-type.js";
 import {
 	type AdoptionScanResult,
@@ -139,7 +141,7 @@ export interface RunBootstrapResult {
 	};
 	/**
 	 * How the session compiler will preload the project context that exists
-	 * on disk after this run: full, synopsis (with the limit that forced it),
+	 * on disk after this run with unknown tool capability: full, partial,
 	 * or none. In preview mode this reflects the current on-disk state, since
 	 * preview writes nothing.
 	 */
@@ -249,6 +251,23 @@ function projectTypeLabel(projectType: ProjectType): string {
 	}
 }
 
+/** Only project-wide instructions may become unconditional handbook rules. */
+function handbookInstructionFiles(input: BootstrapGenerateInput): SiblingContextFile[] {
+	const projectPaths = new Set(
+		INTEROP_AGENT_KINDS.flatMap((kind) => kind.instructionFiles.map((file) => resolve(input.cwd, file))),
+	);
+	const allowed = new Set(
+		input.adoption.sources
+			.filter((source) => {
+				if (source.kind !== "instructions") return false;
+				if (source.scope === "project") return projectPaths.has(source.path);
+				return input.adoption.includeGlobal && source.path === resolve(input.adoption.homeDir, ".codex/AGENTS.md");
+			})
+			.map((source) => source.path),
+	);
+	return input.siblingFiles.filter((file) => allowed.has(file.path));
+}
+
 function allContextText(files: ReadonlyArray<SiblingContextFile>): string {
 	return files.map((file) => file.content).join("\n\n");
 }
@@ -308,7 +327,7 @@ function resolveDefaultIdentity(
  * strictly better than that, and only than that.
  */
 function stabilizedIdentity(input: BootstrapGenerateInput, modelIdentity: unknown, tomlFiles: TomlFileReader): string {
-	const deterministic = resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles, tomlFiles);
+	const deterministic = resolveDefaultIdentity(input.cwd, input.projectType, handbookInstructionFiles(input), tomlFiles);
 	const model = typeof modelIdentity === "string" ? modelIdentity.trim() : "";
 	if (deterministic.bare && model.length > 0) return model;
 	return deterministic.text;
@@ -423,7 +442,7 @@ function indexedSourceFileCount(codewiki: Codewiki): number {
 /** Measure how the session compiler will preload the on-disk project context. */
 function measureProjectPreload(cwd: string): ProjectPreloadClass {
 	const promptContext = renderPromptContext(cwd);
-	return classifyProjectPreload({ hasClioMd: promptContext.clioMd !== null, text: promptContext.text });
+	return selectProjectPreload(promptContext, null).classification;
 }
 
 function packageScripts(cwd: string): Record<string, string> {
@@ -724,12 +743,12 @@ function stabilizeGeneratedOutput(
 	const existing = input.existingClioMd;
 	const conventions: string[] = [];
 	for (const convention of existing?.conventions ?? []) pushUnique(conventions, convention);
-	for (const convention of inferConventions(input.cwd, input.siblingFiles, input.codewiki)) {
+	for (const convention of inferConventions(input.cwd, handbookInstructionFiles(input), input.codewiki)) {
 		pushUnique(conventions, convention);
 	}
 	const invariants: string[] = [];
 	for (const invariant of existing?.invariants ?? []) pushUnique(invariants, invariant);
-	for (const invariant of inferInvariants(input.siblingFiles)) pushUnique(invariants, invariant);
+	for (const invariant of inferInvariants(handbookInstructionFiles(input))) pushUnique(invariants, invariant);
 
 	const verification = verificationSection(input.cwd, tomlFiles);
 	const inferredSections = inferHeuristicSections(input);
@@ -776,7 +795,7 @@ function stabilizeGeneratedOutput(
  * precise number is falsified by any single added file and carries no
  * navigational value the entry-point list does not.
  */
-export function codewikiSections(codewiki: Codewiki): ClioMdSection[] {
+function codewikiSections(codewiki: Codewiki): ClioMdSection[] {
 	const sections: ClioMdSection[] = [];
 	const entryPoints = codewikiEntryPoints(codewiki, 8);
 	if (entryPoints.length > 0) {
@@ -793,7 +812,7 @@ export function codewikiSections(codewiki: Codewiki): ClioMdSection[] {
 
 function inferHeuristicSections(input: BootstrapGenerateInput): ClioMdSection[] {
 	const sections: ClioMdSection[] = [...codewikiSections(input.codewiki)];
-	const invariants = inferInvariants(input.siblingFiles);
+	const invariants = inferInvariants(handbookInstructionFiles(input));
 	if (invariants.length > 0) {
 		sections.push({
 			title: "Architecture boundaries",
@@ -827,9 +846,9 @@ function heuristicBootstrapOutputSync(input: BootstrapGenerateInput): BootstrapS
 	const sharedInput = input.tomlFiles ? input : { ...input, tomlFiles };
 	return stabilizeGeneratedOutput(sharedInput, {
 		projectName: projectName(input.cwd, tomlFiles),
-		identity: resolveDefaultIdentity(input.cwd, input.projectType, input.siblingFiles, tomlFiles).text,
-		conventions: inferConventions(input.cwd, input.siblingFiles, input.codewiki),
-		invariants: inferInvariants(input.siblingFiles),
+		identity: resolveDefaultIdentity(input.cwd, input.projectType, handbookInstructionFiles(input), tomlFiles).text,
+		conventions: inferConventions(input.cwd, handbookInstructionFiles(input), input.codewiki),
+		invariants: inferInvariants(handbookInstructionFiles(input)),
 		sections: inferHeuristicSections(input),
 	});
 }
@@ -852,7 +871,7 @@ function bootstrapOutputFromParsed(parsed: ParsedClioMd): BootstrapStructuredOut
 
 function existingClioMdBootstrapOutput(cwd: string): BootstrapStructuredOutput | null {
 	const parsed = tryReadClioMd(cwd);
-	if (!parsed?.ok) return null;
+	if (!parsed?.ok || !parsed.value) return null;
 	return bootstrapOutputFromParsed(parsed.value);
 }
 
@@ -1048,15 +1067,16 @@ async function ensureGitignore(cwd: string, input: RunBootstrapInput): Promise<v
 }
 
 function serializeBootstrapOutput(output: BootstrapStructuredOutput): string {
-	return serializeClioMd({ ...output, fingerprint: null });
+	const serialized = serializeClioMd({ ...output, fingerprint: null });
+	const parsed = parseClioMd(serialized);
+	if (!parsed.ok) throw new Error(`bootstrap produced invalid CLIO-CODER.md: ${parsed.errors.join("; ")}`);
+	return serialized;
 }
 
 function writeClioMdFile(cwd: string, output: BootstrapStructuredOutput): string {
 	const clioMdPath = join(cwd, "CLIO-CODER.md");
 	mkdirSync(dirname(clioMdPath), { recursive: true });
 	const serialized = serializeBootstrapOutput(output);
-	const parsed = parseClioMd(serialized);
-	if (!parsed.ok) throw new Error(`bootstrap produced invalid CLIO-CODER.md: ${parsed.errors.join("; ")}`);
 	writeFileSync(clioMdPath, serialized, "utf8");
 	return clioMdPath;
 }
@@ -1068,11 +1088,31 @@ function timestampForPath(now: Date): string {
 		.replace(/\.\d{3}Z$/, "Z");
 }
 
-function writeClioMdProposal(cwd: string, now: Date, output: BootstrapStructuredOutput): string {
+function writeClioMdProposal(
+	cwd: string,
+	now: Date,
+	output: BootstrapStructuredOutput,
+	generation: BootstrapGenerationTelemetry,
+	existingSource: string | null,
+): string {
 	const dir = join(cwd, ".clio-coder", "proposals");
 	mkdirSync(dir, { recursive: true });
-	const proposalPath = join(dir, `CLIO-CODER-${timestampForPath(now)}.md`);
-	writeFileSync(proposalPath, serializeBootstrapOutput(output), "utf8");
+	const proposalPath = join(dir, `CLIO-CODER-${timestampForPath(now)}-${randomUUID()}.md`);
+	const serialized = serializeBootstrapOutput(output);
+	writeFileSync(proposalPath, serialized, { encoding: "utf8", flag: "wx" });
+	// Proposal provenance belongs to the candidate, never to the untouched handbook.
+	writeFileSync(
+		`${proposalPath}.json`,
+		`${JSON.stringify({
+			version: 1,
+			createdAt: now.toISOString(),
+			handbookPath: join(cwd, "CLIO-CODER.md"),
+			sourceHash: existingSource === null ? null : createHash("sha256").update(existingSource).digest("hex"),
+			proposalHash: createHash("sha256").update(serialized).digest("hex"),
+			generation: durableGenerationTelemetry(generation),
+		})}\n`,
+		{ encoding: "utf8", flag: "wx" },
+	);
 	return proposalPath;
 }
 
@@ -1130,17 +1170,13 @@ function writeProjectState(
 	codewikiVersion: number,
 	fingerprint: Fingerprint,
 	generation: BootstrapGenerationTelemetry,
-	generated: boolean,
+	published: boolean,
 ): string {
 	const statePath = resolveStatePath(cwd);
 	const prev = readClioState(cwd);
 	// lastBootstrap describes how the CLIO-CODER.md on disk was produced, not what the
-	// most recent run happened to do. A run that generated nothing leaves the
-	// handbook untouched, so overwriting a recorded `model` provenance with
-	// `existing` would claim the handbook has no model authorship behind it.
-	const lastBootstrap = generated
-		? durableGenerationTelemetry(generation)
-		: (prev?.lastBootstrap ?? durableGenerationTelemetry(generation));
+	// most recent run happened to do. Proposals retain their own generation record.
+	const lastBootstrap = published ? durableGenerationTelemetry(generation) : prev?.lastBootstrap;
 	const contextSources = recordAdoption ? adoption.sourceSnapshots : prev?.contextSources;
 	const contextSourceHash = contextSources ? adoptionSnapshotsHash(contextSources) : undefined;
 	writeClioState(cwd, {
@@ -1151,7 +1187,7 @@ function writeProjectState(
 		lastInitAt: now.toISOString(),
 		lastSessionAt: now.toISOString(),
 		lastIndexedAt: indexedAt,
-		lastBootstrap,
+		...(lastBootstrap ? { lastBootstrap } : {}),
 		...(contextSources ? { contextSources } : {}),
 		...(contextSourceHash ? { contextSourceHash } : {}),
 	});
@@ -1304,17 +1340,16 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 	) {
 		const detail = existingClioMd && !existingClioMd.ok ? ` (${existingClioMd.error})` : "";
 		throw new Error(
-			`cannot refresh Imported agent context because CLIO-CODER.md is malformed${detail}; use --apply or --rewrite after reviewing the handbook`,
+			`cannot refresh Imported agent context because CLIO-CODER.md has no structured projection${detail}; use --apply or --rewrite after reviewing the handbook`,
 		);
 	}
 	// A supplied generator *is* the request to generate: both entry points
 	// withhold `generate` for --heuristic and --preview and supply it otherwise.
-	// An existing CLIO-CODER.md used to suppress generation entirely, so a plain
-	// `clio-coder context init` on an initialized repository dispatched nothing, wrote
-	// `lastBootstrap.mode: "existing"`, and looked identical to a run that had no
-	// route at all. The handbook still reaches the generator as source (see
-	// `useExistingClioMdAsSource`), so this refreshes rather than replaces.
+	// For an existing handbook, retain that work as a proposal unless replacement
+	// or adoption was explicitly requested. Generation never implies publication.
 	const shouldGenerate = !hadClioMd || replaceClioMd || input.proposeClioMd === true || input.generate !== undefined;
+	const shouldPropose =
+		input.proposeClioMd === true || (hadClioMd && input.generate !== undefined && !replaceClioMd && input.adopt !== true);
 	let output: BootstrapStructuredOutput;
 	let generation: BootstrapGenerationTelemetry = {
 		mode: shouldGenerate ? "heuristic" : existingParsed ? "existing" : "heuristic",
@@ -1427,7 +1462,10 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		status: "started",
 		message: hadClioMd ? "preserving CLIO-CODER.md" : "writing CLIO-CODER.md",
 	});
-	if (!hadClioMd) {
+	if (shouldPropose) {
+		proposalPath = writeClioMdProposal(cwd, now, output, generation, existingClioMdText);
+		action = "proposed";
+	} else if (!hadClioMd) {
 		clioMdPath = writeClioMdFile(cwd, output);
 		action = "wrote";
 	} else if (replaceClioMd) {
@@ -1436,9 +1474,6 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 	} else if (input.adopt === true && existingParsed) {
 		clioMdPath = writeClioMdFile(cwd, output);
 		action = "refreshed";
-	} else if (input.proposeClioMd === true) {
-		proposalPath = writeClioMdProposal(cwd, now, output);
-		action = "proposed";
 	}
 	progress(input, {
 		phase: "clio-md",
@@ -1465,7 +1500,7 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 		codewiki.version,
 		codewikiFingerprint,
 		generation,
-		shouldGenerate,
+		action === "wrote" || action === "refreshed",
 	);
 	progress(input, {
 		phase: "state",
@@ -1489,7 +1524,7 @@ export async function runBootstrap(input: RunBootstrapInput = {}): Promise<RunBo
 	if (preload.mode === "full" && preload.nearLimit) {
 		warn(
 			input.io,
-			`  warning: project context is within 10% of the preload limit (${preload.chars} chars of 8000, ${preload.lines} lines of 220); the next growth may flip it to a synopsis\n`,
+			`  warning: project context is within 10% of the preload limit (${preload.chars} UTF-16 units of 8000, ${preload.lines} rendered lines of 220); further growth may omit authored suffixes\n`,
 		);
 	}
 	progress(input, {

package/src/domains/context/clio-md.ts

@@ -28,7 +28,10 @@ export interface ParsedClioMd {
 
 export interface LoadedClioMdFile {
 	path: string;
-	value: ParsedClioMd;
+	/** Exact UTF-8 authored source for prompt rendering. */
+	source: string;
+	/** Optional generator-format projection; never the authority for authored text. */
+	value: ParsedClioMd | null;
 }
 
 export interface ClioMdLoadError {
@@ -39,9 +42,9 @@ export interface ClioMdLoadError {
 export interface LoadedProjectClioMd {
 	/** Effective files in ancestor-to-descendant order. */
 	files: LoadedClioMdFile[];
-	/** Selected files that could not be read or parsed. */
+	/** Selected files that could not be read or were empty. */
 	errors: ClioMdLoadError[];
-	/** The layered effective handbook, or null when no selected file parsed. */
+	/** The layered structured projection, or null when no selected file matches the generator format. */
 	value: ParsedClioMd | null;
 }
 
@@ -77,10 +80,60 @@ function normalizeInline(value: string): string {
 		.trim();
 }
 
+/**
+ * The same text with every character inside a fenced code block or an HTML
+ * comment replaced by a filler, newlines kept, so offsets into the mask are
+ * offsets into the original. Heading scans run on the mask and slice from the
+ * source: a `# comment` line in a fenced shell example used to read as a
+ * second H1 and reject the whole handbook, and a `## not a heading` inside a
+ * fence split into a section whose serialization then rewrote the fence.
+ */
+function maskNonHeadingRegions(text: string): string {
+	const lines = text.split("\n");
+	const out: string[] = [];
+	let fence: { char: string; length: number } | null = null;
+	let inComment = false;
+	for (const line of lines) {
+		let masked = false;
+		if (fence) {
+			masked = true;
+			const close = /^\s{0,3}(`{3,}|~{3,})\s*$/.exec(line);
+			if (close?.[1] && close[1][0] === fence.char && close[1].length >= fence.length) fence = null;
+		} else if (inComment) {
+			masked = true;
+			if (line.includes("-->")) inComment = false;
+		} else {
+			const open = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+			if (open?.[1]) {
+				fence = { char: open[1][0] ?? "`", length: open[1].length };
+				masked = true;
+			} else if (/^\s*<!--/.test(line)) {
+				masked = true;
+				if (!line.includes("-->")) inComment = true;
+			}
+		}
+		// A non-whitespace filler: the heading regexes end in `\s*$`, which would
+		// otherwise run through a blank-masked block and swallow it into the
+		// heading match.
+		out.push(masked ? "_".repeat(line.length) : line);
+	}
+	return out.join("\n");
+}
+
 function normalizeNestedMarkdown(value: string): string {
-	return normalizeSource(value)
-		.trim()
-		.replace(/^(#{1,2})(\s+)/gm, "###$2");
+	const body = normalizeSource(value).trim();
+	// Demote authored H1/H2 inside a section body so it cannot outrank the
+	// section, but only where a heading scan would see one: a fence or comment
+	// keeps its bytes.
+	const mask = maskNonHeadingRegions(body);
+	let out = "";
+	let cursor = 0;
+	for (const match of mask.matchAll(/^(#{1,2})(\s+)/gm)) {
+		if (match.index === undefined) continue;
+		out += body.slice(cursor, match.index) + "###" + (match[2] ?? "");
+		cursor = match.index + match[0].length;
+	}
+	return out + body.slice(cursor);
 }
 
 function charLen(value: string): number {
@@ -112,7 +165,7 @@ function parseFooter(source: string): {
 
 	const footerEnd = match.index + match[0].length;
 	const trailing = source.slice(footerEnd).trim();
-	if (trailing.length > 0) warnings.push("trailing content after fingerprint footer ignored");
+	if (trailing.length > 0) warnings.push("trailing content after fingerprint footer omitted from structured fields");
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(match[1] ?? "");
@@ -162,7 +215,7 @@ function validateFooter(value: unknown): ClioMdFingerprintFooter | null {
 }
 
 function readSections(body: string): ClioMdSection[] {
-	const headings = [...body.matchAll(H2_RE)];
+	const headings = [...maskNonHeadingRegions(body).matchAll(H2_RE)];
 	const sections: ClioMdSection[] = [];
 	for (let i = 0; i < headings.length; i += 1) {
 		const heading = headings[i];
@@ -187,7 +240,8 @@ function extraSections(sections: ReadonlyArray<ClioMdSection>): ClioMdSection[]
 }
 
 function identityParagraph(afterH1: string): string {
-	const beforeFirstSection = afterH1.split(/^##\s+/m)[0] ?? "";
+	const firstSection = /^##\s+/m.exec(maskNonHeadingRegions(afterH1));
+	const beforeFirstSection = firstSection ? afterH1.slice(0, firstSection.index) : afterH1;
 	const paragraphs = beforeFirstSection
 		.trim()
 		.split(/\n\s*\n/)
@@ -219,7 +273,7 @@ export function parseClioMd(source: string): ClioMdParseResult {
 	warnings.push(...footerResult.warnings);
 	if (footerResult.errors.length > 0) return { ok: false, errors: footerResult.errors, warnings };
 
-	const h1Matches = [...footerResult.body.matchAll(H1_RE)];
+	const h1Matches = [...maskNonHeadingRegions(footerResult.body).matchAll(H1_RE)];
 	if (h1Matches.length === 0) return { ok: false, errors: ["missing H1 heading"], warnings };
 	if (h1Matches.length > 1) return { ok: false, errors: ["more than one H1 heading"], warnings };
 
@@ -317,7 +371,9 @@ function escapeXmlAttribute(value: string): string {
 	return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
 
-export function renderProjectContextFragment(parsed: ParsedClioMd, sourcePath?: string): string {
+export function renderProjectContextFragment(parsed: ParsedClioMd | string, sourcePath?: string): string {
+	const source = sourcePath ? ` path="${escapeXmlAttribute(sourcePath)}"` : "";
+	if (typeof parsed === "string") return `<project-context${source}>\n${parsed}\n</project-context>`;
 	const sections: string[] = [`# ${parsed.projectName}`, parsed.identity];
 	if (parsed.conventions.length > 0) {
 		sections.push("## Conventions", ...parsed.conventions.map((item) => `- ${item}`));
@@ -331,7 +387,6 @@ export function renderProjectContextFragment(parsed: ParsedClioMd, sourcePath?:
 	if (parsed.importedAgentContext) {
 		sections.push("## Imported agent context", parsed.importedAgentContext);
 	}
-	const source = sourcePath ? ` path="${escapeXmlAttribute(sourcePath)}"` : "";
 	return `<project-context${source}>\n${sections.join("\n\n")}\n</project-context>`;
 }
 
@@ -352,35 +407,40 @@ function selectedClioMdPath(directory: string): string | null {
 	return null;
 }
 
-function readClioMdPath(filePath: string): { ok: true; value: ParsedClioMd } | { ok: false; error: string } {
+function readClioMdPath(
+	filePath: string,
+): { ok: true; source: string; value: ParsedClioMd | null } | { ok: false; error: string } {
 	let content: string;
 	try {
 		content = readFileSync(filePath, "utf8");
 	} catch (err) {
 		return { ok: false, error: err instanceof Error ? err.message : String(err) };
 	}
+	if (content.trim().length === 0) return { ok: false, error: "handbook is empty" };
+	// Authored Markdown needs no generator schema. Preserve it even when a
+	// structured projection cannot be derived; producer validation stays strict.
 	const parsed = parseClioMd(content);
-	if (!parsed.ok) return { ok: false, error: parsed.errors.join("; ") };
-	return { ok: true, value: parsed.value };
+	return { ok: true, source: content, value: parsed.ok ? parsed.value : null };
 }
 
 function mergeClioMdFiles(files: ReadonlyArray<LoadedClioMdFile>): ParsedClioMd | null {
-	const nearest = files.at(-1)?.value;
+	const values = files.flatMap((file) => (file.value ? [file.value] : []));
+	const nearest = values.at(-1);
 	if (!nearest) return null;
 	return {
 		projectName: nearest.projectName,
-		identity: files.map((file) => file.value.identity).join("\n\n"),
-		conventions: files.flatMap((file) => file.value.conventions),
-		invariants: files.flatMap((file) => file.value.invariants),
-		sections: files.flatMap((file) => file.value.sections),
+		identity: values.map((value) => value.identity).join("\n\n"),
+		conventions: values.flatMap((value) => value.conventions),
+		invariants: values.flatMap((value) => value.invariants),
+		sections: values.flatMap((value) => value.sections),
 		importedAgentContext:
-			files
-				.map((file) => file.value.importedAgentContext)
+			values
+				.map((value) => value.importedAgentContext)
 				.filter((value): value is string => value !== null)
 				.join("\n\n") || null,
 		fingerprint: nearest.fingerprint,
 		firstInit: nearest.firstInit,
-		warnings: files.flatMap((file) => file.value.warnings),
+		warnings: values.flatMap((value) => value.warnings),
 	};
 }
 
@@ -388,7 +448,7 @@ function mergeClioMdFiles(files: ReadonlyArray<LoadedClioMdFile>): ParsedClioMd
  * Load effective project handbooks from filesystem root through `cwd`.
  * Candidate selection follows pi-coding-agent 0.84's
  * `loadProjectContextFiles`: an override wins over the base file in the same
- * directory. Clio's structured override additionally resets the inherited
+ * directory. Clio's override additionally resets the inherited
  * handbook chain for that subtree, as required by the project-context
  * contract. Handbooks below the override may add new layers.
  */
@@ -416,13 +476,15 @@ export function loadProjectClioMd(cwd: string): LoadedProjectClioMd {
 	const errors: ClioMdLoadError[] = [];
 	for (const filePath of selectedPaths) {
 		const read = readClioMdPath(filePath);
-		if (read.ok) files.push({ path: filePath, value: read.value });
+		if (read.ok) files.push({ path: filePath, source: read.source, value: read.value });
 		else errors.push({ path: filePath, error: read.error });
 	}
 	return { files, errors, value: mergeClioMdFiles(files) };
 }
 
-export function tryReadClioMd(cwd: string): { ok: true; value: ParsedClioMd } | { ok: false; error: string } | null {
+export function tryReadClioMd(
+	cwd: string,
+): { ok: true; source: string; value: ParsedClioMd | null } | { ok: false; error: string } | null {
 	const filePath = join(cwd, "CLIO-CODER.md");
 	if (!existsSync(filePath)) return null;
 	return readClioMdPath(filePath);

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

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import { detectProjectType } from "../../session/workspace/project-type.js";
+import { computeFingerprint, isStale } from "../fingerprint.js";
+import { codewikiNeedsBackfill, readCodewiki } from "./artifact.js";
+import type {
+	CodewikiArtifactRef,
+	CodewikiBuildWorkerOutcome,
+	CodewikiBuildWorkerRequest,
+	CodewikiBuildWorkerResult,
+} from "./build-worker-protocol.js";
+import { buildCodewiki, type CodewikiBuildOptions, syncCodewiki, updateCodewikiPaths } from "./indexer.js";
+import type { Codewiki } from "./schema.js";
+
+function isArtifactRef(value: Codewiki | CodewikiArtifactRef | null): value is CodewikiArtifactRef {
+	return value !== null && "source" in value && value.source === "artifact";
+}
+
+/**
+ * Worker-side build policy; options use the indexer's source reader for
+ * deterministic race tests. The outcome omits the artifact when it was handed
+ * in by reference and left unchanged, so the coordinator never receives a
+ * clone of what it already holds.
+ */
+export async function executeCodewikiBuildOutcome(
+	request: CodewikiBuildWorkerRequest,
+	options: CodewikiBuildOptions = {},
+): Promise<CodewikiBuildWorkerOutcome> {
+	const handed = request.kind === "build" ? null : request.current;
+	// Resolved lazily: the unchanged-ensure path below never needs the artifact's
+	// contents, and parsing it there would put the cost back that the reference
+	// took out. Read once, then reused by every later step.
+	let resolved: Codewiki | null | undefined = isArtifactRef(handed) ? undefined : handed;
+	const resolveCurrent = (): Codewiki | null => {
+		if (resolved === undefined) resolved = readCodewiki(request.cwd);
+		return resolved;
+	};
+	// A reference the disk no longer honors (deleted or corrupt between the
+	// coordinator's read and this resolution) is exactly the "no artifact" case:
+	// an ensure rebuilds from source as it would have with `current: null`,
+	// and an incremental refuses rather than fabricating an index from one path.
+	const requireCurrent = (): Codewiki => {
+		const current = resolveCurrent();
+		if (!current) throw new Error("codewiki artifact referenced by the coordinator is unreadable; rebuild it");
+		return current;
+	};
+	let unreadable = false;
+	const buildOptions: CodewikiBuildOptions = {
+		...options,
+		readFile: (path) => {
+			try {
+				const text = options.readFile ? options.readFile(path) : readFileSync(path, "utf8");
+				if (text === null) unreadable = true;
+				return text;
+			} catch {
+				unreadable = true;
+				return null;
+			}
+		},
+	};
+	if (request.kind === "ensure" && handed !== null) {
+		const needsBackfill = isArtifactRef(handed) ? handed.needsBackfill : codewikiNeedsBackfill(handed);
+		if (!needsBackfill) {
+			const fingerprint = isArtifactRef(handed)
+				? computeFingerprint(request.cwd, null, { artifactLoc: handed.loc })
+				: computeFingerprint(request.cwd, handed);
+			if (request.previous && !isStale(request.previous, fingerprint)) {
+				return { codewiki: isArtifactRef(handed) ? null : handed, fingerprint, changed: false };
+			}
+		}
+	}
+	let current: Codewiki | null = handed === null ? null : resolveCurrent();
+	if (request.kind === "incremental") {
+		const base = requireCurrent();
+		current = await updateCodewikiPaths(request.cwd, base, request.paths, buildOptions);
+		// An unchanged notification proves nothing about unrelated files. Retain
+		// the old global baseline so the next ensure still detects external edits.
+		if (current === base && request.previous && !unreadable) {
+			return { codewiki: isArtifactRef(handed) ? null : base, fingerprint: request.previous, changed: false };
+		}
+	}
+
+	for (let attempt = 0; attempt < 3; attempt += 1) {
+		// Both scans bracket all source reads, including sync's cached parse inputs.
+		// Never stamp a post-build tree that changed after an earlier file was read.
+		const before = computeFingerprint(request.cwd, current);
+		unreadable = false;
+		current = current
+			? await syncCodewiki(request.cwd, current, buildOptions)
+			: await buildCodewiki(
+					{
+						cwd: request.cwd,
+						language:
+							(request.kind === "incremental" ? requireCurrent().language : request.language) ??
+							detectProjectType(request.cwd),
+					},
+					buildOptions,
+				);
+		const after = computeFingerprint(request.cwd, current);
+		if (!isStale(before, after) && !unreadable) {
+			return { codewiki: current, fingerprint: after, changed: true };
+		}
+	}
+	throw new Error("codewiki source snapshot did not stabilize after 3 attempts; previous index preserved");
+}
+
+/**
+ * In-process form for callers that hold the artifact: the worker outcome with
+ * the handed object substituted wherever the reconciliation left it unchanged.
+ */
+export async function executeCodewikiBuild(
+	request: CodewikiBuildWorkerRequest,
+	options: CodewikiBuildOptions = {},
+): Promise<CodewikiBuildWorkerResult> {
+	const outcome = await executeCodewikiBuildOutcome(request, options);
+	if (outcome.codewiki)
+		return { codewiki: outcome.codewiki, fingerprint: outcome.fingerprint, changed: outcome.changed };
+	const handed = request.kind === "build" ? null : request.current;
+	const current = handed && !isArtifactRef(handed) ? handed : readCodewiki(request.cwd);
+	if (!current) throw new Error("codewiki reconciliation returned no artifact");
+	return { codewiki: current, fingerprint: outcome.fingerprint, changed: outcome.changed };
+}

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

@@ -1,6 +1,22 @@
 import type { Fingerprint } from "../fingerprint.js";
 import type { Codewiki } from "./schema.js";
 
+/**
+ * The committed artifact, named instead of shipped. Structured-cloning a
+ * parsed index into the worker and back costs main-thread time proportional to
+ * the index size on every reconciliation, including the `code_nav` calls that
+ * reconcile nothing. The coordinator already holds the artifact lease, so the
+ * file on disk is exactly the object it would have cloned; the worker reads it
+ * only on the paths that need its contents.
+ */
+export interface CodewikiArtifactRef {
+	source: "artifact";
+	/** `codewikiNeedsBackfill(current)`, computed where the object is already parsed. */
+	needsBackfill: boolean;
+	/** Source line total the artifact records, so an unchanged fingerprint matches the committed one exactly. */
+	loc: number;
+}
+
 export type CodewikiBuildWorkerRequest =
 	| { kind: "build"; cwd: string; language: Codewiki["language"] }
 	| {
@@ -8,10 +24,17 @@ export type CodewikiBuildWorkerRequest =
 			cwd: string;
 			/** Optional when neither state nor an existing artifact identifies the project. */
 			language?: Codewiki["language"];
-			current: Codewiki | null;
+			current: Codewiki | CodewikiArtifactRef | null;
 			previous: Fingerprint | null;
 	  }
-	| { kind: "incremental"; cwd: string; current: Codewiki; paths: string[] };
+	| {
+			kind: "incremental";
+			cwd: string;
+			current: Codewiki | CodewikiArtifactRef;
+			paths: string[];
+			/** Retained for no-op batches; absence requires global reconciliation. */
+			previous?: Fingerprint | null;
+	  };
 
 export interface CodewikiBuildWorkerResult {
 	codewiki: Codewiki;
@@ -19,6 +42,17 @@ export interface CodewikiBuildWorkerResult {
 	changed: boolean;
 }
 
+/**
+ * What the worker posts back. An unchanged reconciliation of an artifact it
+ * was handed by reference leaves `codewiki` null: the caller still holds the
+ * object, and returning it would clone the whole artifact a second time.
+ */
+export interface CodewikiBuildWorkerOutcome {
+	codewiki: Codewiki | null;
+	fingerprint: Fingerprint;
+	changed: boolean;
+}
+
 export type CodewikiBuildWorkerMessage =
-	| { ok: true; result: CodewikiBuildWorkerResult }
+	| { ok: true; result: CodewikiBuildWorkerOutcome }
 	| { ok: false; error: string; stack?: string };