@shanepadgett/tau-agent 0.16.0 → 0.18.0

package/extensions/context/sync.ts

@@ -1,131 +1,31 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
-import { Type, type ThinkingLevel, type Tool } from "@earendil-works/pi-ai";
-import { withFileMutationQueue, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { parse, stringify } from "smol-toml";
-import { createGitRunner, loadRepoStatus, type GitRunner } from "../../shared/git.ts";
-import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGitRunner, loadRepoStatus } from "../../shared/git.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
-import { truncAt } from "../../shared/text.ts";
+import { discoverAgents } from "../subagent/agents.ts";
 import {
-	contextEntryPaths,
-	isContextEligiblePath,
-	isSensitiveContextPath,
-	loadContextEntries,
-	normalizeProjectPath,
-	pathExists,
-	requireFiles,
-	validSlug,
-	type ContextEntry,
-} from "./definitions.ts";
+	createSubagentThread,
+	disposeSubagentThread,
+	extensionPathsForTools,
+	runSubagentTurn,
+} from "../subagent/run.ts";
+import { collectSyncEvidence, CONTEXT_SYNC_EVIDENCE_TOOL } from "./evidence.ts";
+import { pathExists } from "./definitions.ts";
 import contextSettings from "./settings.ts";
+import { formatContextValidationFailure, validateContextCatalog } from "./validation.ts";
+import { restoreOutsideContextMutations, snapshotOutsideContext } from "./write-scope.ts";
 
-const MAX_DIRTY_EVIDENCE = 4_000;
-const MAX_STRUCTURAL_PREVIEW = 1_500;
-const MAX_TOTAL_EVIDENCE = 64_000;
-const MAX_UNTRACKED_BYTES = 12_000;
-const EVIDENCE_CONCURRENCY = 4;
-
-const CONTEXT_SYNC_MODELS: ReadonlyArray<{ provider: string; model: string; reasoning: ThinkingLevel }> = [
-	{ provider: "openai-codex", model: "gpt-5.6-terra", reasoning: "medium" },
-	{ provider: "openai-codex", model: "gpt-5.6-sol", reasoning: "low" },
-	{ provider: "anthropic", model: "claude-sonnet-5", reasoning: "low" },
-	{ provider: "xai", model: "grok-4.5", reasoning: "high" },
-];
-
-const SUBMIT_TOOL = {
-	name: "submit_context_sync",
-	description: "Submit the desired context catalog changes.",
-	parameters: Type.Object(
-		{
-			outcome: Type.Union([Type.Literal("no-change"), Type.Literal("apply")]),
-			reason: Type.String({ minLength: 1 }),
-			changes: Type.Optional(
-				Type.Array(
-					Type.Union([
-						Type.Object(
-							{
-								action: Type.Literal("set-entry"),
-								tab: Type.String(),
-								concept: Type.String(),
-								conceptName: Type.String(),
-								conceptDescription: Type.String(),
-								entry: Type.String(),
-								description: Type.String(),
-								files: Type.Array(Type.String(), { minItems: 1 }),
-							},
-							{ additionalProperties: false },
-						),
-						Type.Object(
-							{
-								action: Type.Literal("delete-entry"),
-								tab: Type.String(),
-								concept: Type.String(),
-								entry: Type.String(),
-							},
-							{ additionalProperties: false },
-						),
-					]),
-					{ minItems: 1 },
-				),
-			),
-		},
-		{ additionalProperties: false },
-	),
-} satisfies Tool;
-
-export interface SyncDirtyFile {
-	id: number;
-	path: string;
-	status: string;
-	kind: "modified" | "added" | "deleted" | "renamed" | "copied" | "untracked";
-	untracked: boolean;
-	oldPath?: string;
-	memberships: string[];
-	oldMemberships: string[];
-	evidence: string;
-}
-
-export type ContextSyncChange =
-	| {
-			action: "set-entry";
-			tab: string;
-			concept: string;
-			conceptName: string;
-			conceptDescription: string;
-			entry: string;
-			description: string;
-			files: string[];
-	  }
-	| { action: "delete-entry"; tab: string; concept: string; entry: string };
-
-export type ContextSyncPlan =
-	| { outcome: "no-change"; reason: string }
-	| { outcome: "apply"; reason: string; changes: ContextSyncChange[] };
+const CONTEXT_SYNC_AGENT = "context-sync";
 
 export interface ContextSyncDetails {
-	outcome: "applied" | "no-change";
+	outcome: "applied" | "no-change" | "failed";
 	summary: string;
-	changedContextFiles: string[];
 	reason: string;
-	changes: ContextSyncChange[];
-	counts: { created: number; updated: number; deleted: number; unchanged: number };
-}
-
-export interface SyncEvidence {
-	root: string;
-	files: SyncDirtyFile[];
-	entries: ContextEntry[];
-	dirtyExisting: Set<string>;
-	dependencies: Set<string>;
-	affectedIds: Set<string>;
-	affectedConcepts: Set<string>;
-	eligibleFiles: Set<string>;
-	missingPaths: Set<string>;
-	structuralPreviews: Map<string, string>;
-	worktreeSignature: string;
-	catalogSignature: string;
+	changedContextFiles: string[];
+	agentResponse?: string;
+	validationFailure?: string;
 }
 
 let syncQueue = Promise.resolve();
@@ -133,58 +33,153 @@ let syncQueue = Promise.resolve();
 export async function runContextSync(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	onStatus?: (status: string) => void | Promise<void>,
+	options: { nudge?: string; signal?: AbortSignal; onStatus?: (status: string) => void | Promise<void> } = {},
 ): Promise<ContextSyncDetails> {
-	return withSyncLock(() => runContextSyncLocked(pi, ctx, onStatus));
+	return withSyncLock(() => runContextSyncLocked(pi, ctx, options));
 }
 
 async function runContextSyncLocked(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	onStatus?: (status: string) => void | Promise<void>,
+	options: { nudge?: string; signal?: AbortSignal; onStatus?: (status: string) => void | Promise<void> },
 ): Promise<ContextSyncDetails> {
 	if (!ctx.isProjectTrusted()) throw new Error("Context sync requires a trusted project");
-	await onStatus?.("Inspecting repository context");
+	await options.onStatus?.("Inspecting repository context");
 	const git = createGitRunner(pi, ctx);
 	const status = await loadRepoStatus(git);
 	if (!status) throw new Error("No Git repository found");
 	const settings = await loadTauExtensionSettings(ctx, contextSettings);
 	const evidence = await collectSyncEvidence(git, status.root, settings.validation.ignoreGlobs);
 	if (evidence.files.length === 0 && evidence.missingPaths.size === 0)
-		return noChange("Changed files are outside context catalog scope.");
-	const prompt = buildContextSyncPrompt(evidence);
-	const plan = await generateToolValidated(
+		return {
+			outcome: "no-change",
+			summary: "Existing context mappings already fit the changed scope.",
+			reason: "Changed files are outside context catalog scope.",
+			changedContextFiles: [],
+		};
+
+	const beforeCatalog = await catalogFileSnapshot(status.root);
+	const outsideBefore = await snapshotOutsideContext(git, status.root);
+	const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
+	const definition = discovery.agents.get(CONTEXT_SYNC_AGENT);
+	if (!definition) {
+		const reason =
+			discovery.invalid
+				.get(CONTEXT_SYNC_AGENT)
+				?.map((item) => item.reason)
+				.join("; ") ?? "unknown agent";
+		throw new Error(`Context sync agent unavailable: ${reason}`);
+	}
+
+	const task = buildContextSyncTask(status.root, options.nudge);
+	const signal = options.signal ?? ctx.signal ?? new AbortController().signal;
+
+	await options.onStatus?.("Running context-sync subagent");
+	const thread = await createSubagentThread({
+		id: `context-sync-${Date.now()}`,
+		displayName: definition.names[0] ?? definition.name,
+		definition,
+		extensionPaths: extensionPathsForTools(pi, definition.tools),
+		initialTask: task,
 		ctx,
-		await resolveCandidates(ctx, CONTEXT_SYNC_MODELS, false),
-		prompt,
-		SUBMIT_TOOL,
-		(input) => normalizeContextSyncPlan(input, evidence),
-		(error) => `Validation failed: ${error.message}\nCall submit_context_sync once with corrected arguments only.`,
-		{ statusKey: "context-sync", onStatus },
-	);
-	if (plan.outcome === "no-change") return noChange(plan.reason);
-	await onStatus?.("Applying context catalog changes");
-	return applyContextSyncPlan(evidence.root, plan, evidence.entries, async () => {
-		const currentEntries = await loadContextEntries(evidence.root);
-		const currentFiles = await collectDirtyFiles(git, evidence.root, currentEntries, settings.validation.ignoreGlobs);
-		if ((await computeWorktreeSignature(git, evidence.root, currentFiles)) !== evidence.worktreeSignature)
-			throw new Error("Repository changed during context sync. Rerun context sync.");
-		if ((await computeCatalogSignature(evidence.root)) !== evidence.catalogSignature)
-			throw new Error("Context catalog changed during context sync. Rerun context sync.");
+		thinkingLevel: pi.getThinkingLevel(),
+		signal,
+		onWarning: (warning) => {
+			ctx.ui.notify(`Context sync agent: ${warning}`, "warning");
+		},
 	});
-}
-
-function noChange(reason: string): ContextSyncDetails {
+	let agentResponse = "";
+	try {
+		const result = await runSubagentTurn({
+			thread,
+			task,
+			initial: true,
+			signal,
+			onUpdate: async (details) => {
+				const activity = details.currentActivity ?? details.response;
+				if (activity) await options.onStatus?.(activity.slice(0, 160));
+			},
+		});
+		agentResponse = result.content;
+		if (result.details.status !== "completed") {
+			const writeScopeViolations = await restoreOutsideContextMutations(git, status.root, outsideBefore);
+			return {
+				outcome: "failed",
+				summary: "Context sync subagent failed.",
+				reason: [
+					result.details.error ?? result.content,
+					writeScopeViolations.length
+						? `Restored out-of-scope writes:\n${writeScopeViolations.map((path) => `- ${path}`).join("\n")}`
+						: undefined,
+				]
+					.filter((line): line is string => Boolean(line))
+					.join("\n\n"),
+				changedContextFiles: changedCatalogPaths(beforeCatalog, await catalogFileSnapshot(status.root)),
+				agentResponse,
+			};
+		}
+	} finally {
+		await disposeSubagentThread(thread);
+	}
+
+	await options.onStatus?.("Verifying write scope");
+	const writeScopeViolations = await restoreOutsideContextMutations(git, status.root, outsideBefore);
+	const afterCatalog = await catalogFileSnapshot(status.root);
+	const changedContextFiles = changedCatalogPaths(beforeCatalog, afterCatalog);
+	if (writeScopeViolations.length > 0) {
+		return {
+			outcome: "failed",
+			summary: "Context sync wrote outside .pi/contexts; out-of-scope paths were restored.",
+			reason: `Out-of-scope writes restored:\n${writeScopeViolations.map((path) => `- ${path}`).join("\n")}`,
+			changedContextFiles,
+			agentResponse,
+		};
+	}
+
+	await options.onStatus?.("Verifying context catalog");
+	const validationFailure = formatContextValidationFailure(
+		await validateContextCatalog(git, status.root, settings.validation.ignoreGlobs),
+	);
+	if (validationFailure) {
+		return {
+			outcome: "failed",
+			summary: "Context sync finished but catalog invariants still fail.",
+			reason: validationFailure,
+			changedContextFiles,
+			agentResponse,
+			validationFailure,
+		};
+	}
+	if (changedContextFiles.length === 0) {
+		return {
+			outcome: "no-change",
+			summary: "Existing context mappings already fit the changed scope.",
+			reason: agentResponse.trim() || "Context-sync subagent made no catalog edits.",
+			changedContextFiles: [],
+			agentResponse,
+		};
+	}
 	return {
-		outcome: "no-change",
-		summary: "Existing context mappings already fit the changed scope.",
-		changedContextFiles: [],
-		reason,
-		changes: [],
-		counts: { created: 0, updated: 0, deleted: 0, unchanged: 0 },
+		outcome: "applied",
+		summary: `Updated context catalog (${changedContextFiles.length} file${changedContextFiles.length === 1 ? "" : "s"}).`,
+		reason: agentResponse.trim() || "Context-sync subagent updated the catalog.",
+		changedContextFiles,
+		agentResponse,
 	};
 }
 
+export function buildContextSyncTask(root: string, nudge?: string): string {
+	const trimmed = nudge?.trim();
+	return [
+		`Synchronize the repository context catalog at ${root}.`,
+		"Use context_sync_evidence for git/catalog facts. Edit only .pi/contexts with patch.",
+		"Walk the typology ladder out loud before path placement. Recheck invariants before finishing.",
+		trimmed ? `Human nudge (soft steer, does not skip evidence or ladder):\n${trimmed}` : undefined,
+	]
+		.filter((line): line is string => Boolean(line))
+		.join("\n\n");
+}
+
 async function withSyncLock<T>(task: () => Promise<T>): Promise<T> {
 	const previous = syncQueue;
 	let release = () => {};
@@ -199,551 +194,41 @@ async function withSyncLock<T>(task: () => Promise<T>): Promise<T> {
 	}
 }
 
-async function collectSyncEvidence(
-	git: GitRunner,
-	root: string,
-	ignoreGlobs: readonly string[],
-): Promise<SyncEvidence> {
-	const entries = await loadContextEntries(root);
-	const files = await collectDirtyFiles(git, root, entries, ignoreGlobs);
-	const dirtyExisting = new Set<string>();
-	for (const file of files)
-		if (file.kind !== "deleted" && (await isFile(join(root, file.path)))) dirtyExisting.add(file.path);
-	const dependencies = await discoverDirectDependencies(
-		root,
-		files.filter((file) => dirtyExisting.has(file.path)),
-	);
-	for (const path of dependencies) if (!isContextEligiblePath(path, ignoreGlobs)) dependencies.delete(path);
-	const missingPaths = new Set<string>();
-	for (const entry of entries)
-		for (const path of contextEntryPaths(entry))
-			if (isContextEligiblePath(path, ignoreGlobs) && !(await isFile(join(root, path)))) missingPaths.add(path);
-	const affectedIds = new Set<string>();
-	for (const entry of entries) {
-		const paths = contextEntryPaths(entry);
-		if (
-			paths.some((path) => missingPaths.has(path)) ||
-			paths.some(
-				(path) => files.some((file) => file.path === path || file.oldPath === path) || dependencies.has(path),
-			)
-		)
-			affectedIds.add(entry.id);
-	}
-	const affectedConcepts = new Set([...affectedIds].map((id) => id.split("/").slice(0, 2).join("/")));
-	const siblingEntries = entries.filter((entry) => affectedConcepts.has(`${entry.tab}/${entry.concept}`));
-	const siblingFiles = siblingEntries
-		.flatMap((entry) => contextEntryPaths(entry))
-		.filter((path) => !missingPaths.has(path) && isContextEligiblePath(path, ignoreGlobs));
-	const eligibleFiles = new Set([...dirtyExisting, ...dependencies, ...siblingFiles]);
-	const structuralPreviews = new Map<string, string>();
-	for (const path of [...new Set(siblingFiles)].sort()) {
-		try {
-			const content = await readFile(join(root, path), "utf8");
-			const lines = content
-				.split("\n")
-				.filter((line) => line.trim())
-				.slice(0, 30)
-				.join("\n");
-			structuralPreviews.set(path, truncAt(lines, MAX_STRUCTURAL_PREVIEW));
-		} catch {
-			structuralPreviews.set(path, "preview unavailable");
-		}
-	}
-	return {
-		root,
-		files,
-		entries,
-		dirtyExisting,
-		dependencies,
-		affectedIds,
-		affectedConcepts,
-		eligibleFiles,
-		missingPaths,
-		structuralPreviews,
-		worktreeSignature: await computeWorktreeSignature(git, root, files),
-		catalogSignature: await computeCatalogSignature(root),
-	};
-}
-
-async function collectDirtyFiles(
-	git: GitRunner,
-	root: string,
-	entries: readonly ContextEntry[],
-	ignoreGlobs: readonly string[],
-): Promise<SyncDirtyFile[]> {
-	const raw = await git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root });
-	const parts = raw.split("\0").filter(Boolean);
-	const parsed: Omit<SyncDirtyFile, "id" | "memberships" | "oldMemberships" | "evidence">[] = [];
-	for (let index = 0; index < parts.length; index++) {
-		const record = parts[index];
-		if (!record) continue;
-		if (record[0] === "u")
-			throw new Error("Unmerged conflict entries detected; resolve conflicts before context sync.");
-		if (record[0] === "?") {
-			parsed.push({ path: record.slice(2), status: "??", kind: "untracked", untracked: true });
-			continue;
-		}
-		const fields = record.split(" ");
-		if (record[0] === "1") {
-			const status = (fields[1] ?? "..").replace(/\./g, " ");
-			parsed.push({
-				path: fields.slice(8).join(" "),
-				status,
-				kind: status.includes("D") ? "deleted" : status.includes("A") ? "added" : "modified",
-				untracked: false,
-			});
-		} else if (record[0] === "2") {
-			const oldPath = parts[index + 1];
-			const status = (fields[1] ?? "..").replace(/\./g, " ");
-			parsed.push({
-				path: fields.slice(9).join(" "),
-				status,
-				kind: fields[8]?.startsWith("C") ? "copied" : "renamed",
-				untracked: false,
-				...(oldPath ? { oldPath } : {}),
-			});
-			index++;
-		}
-	}
-	const sensitive = parsed.filter(
-		(file) =>
-			file.kind !== "deleted" &&
-			(isSensitiveContextPath(file.path) || (file.oldPath !== undefined && isSensitiveContextPath(file.oldPath))),
-	);
-	if (sensitive.length > 0)
-		throw new Error(
-			`Sensitive files cannot be inspected by context sync:\n${sensitive.map((file) => `- ${file.path}`).join("\n")}`,
-		);
-	const sorted = parsed
-		.filter(
-			(file) =>
-				isContextEligiblePath(file.path, ignoreGlobs) ||
-				(file.oldPath !== undefined && isContextEligiblePath(file.oldPath, ignoreGlobs)),
-		)
-		.sort((a, b) => a.path.localeCompare(b.path));
-	const result: SyncDirtyFile[] = [];
-	for (let offset = 0; offset < sorted.length; offset += EVIDENCE_CONCURRENCY) {
-		result.push(
-			...(await Promise.all(
-				sorted.slice(offset, offset + EVIDENCE_CONCURRENCY).map(async (file, inner) => ({
-					...file,
-					id: offset + inner + 1,
-					memberships: entries
-						.filter((entry) => contextEntryPaths(entry).includes(file.path))
-						.map((entry) => entry.id),
-					oldMemberships: file.oldPath
-						? entries
-								.filter((entry) => contextEntryPaths(entry).includes(file.oldPath ?? ""))
-								.map((entry) => entry.id)
-						: [],
-					evidence: await dirtyEvidence(git, root, file),
-				})),
-			)),
-		);
-	}
-	return result;
-}
-
-async function dirtyEvidence(
-	git: GitRunner,
-	root: string,
-	file: { path: string; oldPath?: string; kind: string; untracked: boolean },
-): Promise<string> {
-	if (file.kind === "deleted") return "deleted file; contents omitted";
-	if (file.untracked) {
-		try {
-			const info = await stat(join(root, file.path));
-			if (!info.isFile()) return "untracked non-file; contents omitted";
-			if (info.size > MAX_UNTRACKED_BYTES) return `untracked file, ${info.size} bytes; contents omitted`;
-			const bytes = await readFile(join(root, file.path));
-			if (bytes.includes(0)) return `untracked binary file, ${info.size} bytes`;
-			return truncAt(`untracked file preview:\n${bytes.toString("utf8")}`, MAX_DIRTY_EVIDENCE);
-		} catch {
-			return "untracked preview unavailable";
-		}
-	}
-	const paths = file.oldPath ? [file.oldPath, file.path] : [file.path];
-	const diff = await git.run(["diff", "--stat", "--patch", "--no-color", "--no-ext-diff", "HEAD", "--", ...paths], {
-		cwd: root,
-		optional: true,
-	});
-	return truncAt(diff || "metadata-only change", MAX_DIRTY_EVIDENCE);
-}
-
-export async function discoverDirectDependencies(
-	root: string,
-	files: readonly Pick<SyncDirtyFile, "path" | "evidence">[],
-): Promise<Set<string>> {
-	const result = new Set<string>();
-	const knownExtensions = [
-		".ts",
-		".tsx",
-		".js",
-		".jsx",
-		".mjs",
-		".cjs",
-		".json",
-		".py",
-		".rs",
-		".go",
-		".c",
-		".cc",
-		".cpp",
-		".h",
-		".hpp",
-	];
-	for (const file of files) {
-		let content = file.evidence;
-		try {
-			content += `\n${await readFile(join(root, file.path), "utf8")}`;
-		} catch {
-			/* evidence remains */
-		}
-		const statement = /(?:import|export|require|include|use|mod(?:ule)?)\b[^\n]*?["'`]([^"'`]+)["'`]/g;
-		for (const match of content.matchAll(statement)) {
-			const specifier = match[1];
-			if (!specifier?.startsWith("./") && !specifier?.startsWith("../")) continue;
-			const absolute = resolve(dirname(join(root, file.path)), specifier);
-			const relativePath = relative(root, absolute).split(sep).join("/");
-			if (!relativePath || relativePath === ".." || relativePath.startsWith("../")) continue;
-			const candidates = extname(absolute)
-				? [absolute]
-				: [
-						...knownExtensions.map((extension) => `${absolute}${extension}`),
-						...knownExtensions.map((extension) => join(absolute, `index${extension}`)),
-					];
-			const matches: string[] = [];
-			if (await isFile(absolute)) matches.push(absolute);
-			else for (const candidate of candidates) if (await isFile(candidate)) matches.push(candidate);
-			if (matches.length === 1)
-				result.add(
-					relative(root, matches[0] ?? absolute)
-						.split(sep)
-						.join("/"),
-				);
-		}
-	}
-	return result;
-}
-
-async function isFile(path: string): Promise<boolean> {
-	try {
-		return (await stat(path)).isFile();
-	} catch {
-		return false;
-	}
-}
-
-function buildContextSyncPrompt(evidence: SyncEvidence): string {
-	const stale = evidence.entries.flatMap((entry) =>
-		contextEntryPaths(entry)
-			.filter((path) => evidence.missingPaths.has(path))
-			.map((path) => `${entry.id}: ${path}`),
-	);
-	const affected = evidence.entries.filter((entry) => evidence.affectedIds.has(entry.id));
-	const previews = [...evidence.structuralPreviews].map(([path, preview]) => `${path}\n${preview}`);
-	return truncAt(
-		[
-			"Synchronize reusable repository context scopes from the supplied Git and catalog evidence.",
-			"Call submit_context_sync exactly once and produce no prose response.",
-			"Return no-change only when every eligible changed file has context membership and no stale catalog paths remain.",
-			"Context entries are reusable work scopes, not inventories of every touched file. Prefer updating an existing entry over creating a near-duplicate. Do not create one entry per file.",
-			"The files field in your changes is desired membership, including eager files and lazy anchors. Paths already classified anywhere in the catalog preserve their loading class; new paths become eager files. Do not change loading policy.",
-			"Follow direct local dependency candidates only when needed. Do not add package dependencies, generated files, incidental imports, or recursive dependencies.",
-			"Reconsider granularity only inside affected concepts. Preserve broad entries when splitting would duplicate files without improving future work.",
-			"Every eligible changed file must belong to at least one entry. Remove every stale catalog path. Use only supplied candidate paths.",
-			"Example: replace gameplay/player/all with gameplay/player/movement and gameplay/player/input only when every still-useful file from all remains in the final entries.",
-			"Changed-file catalog and current memberships:",
-			...evidence.files.map(
-				(file) =>
-					`[${file.id}] ${file.status} ${file.path}${file.oldPath ? ` <- ${file.oldPath}` : ""}; kind=${file.kind}; memberships=${file.memberships.join(",") || "none"}; oldMemberships=${file.oldMemberships.join(",") || "none"}`,
-			),
-			"Complete context catalog:",
-			JSON.stringify(
-				evidence.entries.map((entry) => ({
-					id: entry.id,
-					conceptName: entry.conceptName,
-					conceptDescription: entry.conceptDescription,
-					description: entry.description,
-					eagerFiles: entry.files,
-					anchors: entry.anchors,
-					missingFiles: contextEntryPaths(entry).filter((path) => evidence.missingPaths.has(path)),
-				})),
-			),
-			"Changed files with no membership:",
-			evidence.files
-				.filter((file) => file.kind !== "deleted" && file.memberships.length === 0)
-				.map((file) => file.path)
-				.join("\n") || "(none)",
-			"Affected entries:",
-			affected.map((entry) => entry.id).join("\n") || "(none)",
-			"Affected concepts:",
-			[...evidence.affectedConcepts].sort().join("\n") || "(none)",
-			"Resolved direct dependency candidates:",
-			[...evidence.dependencies].sort().join("\n") || "(none)",
-			"Stale catalog paths that must be removed:",
-			stale.join("\n") || "(none)",
-			"Dirty files:",
-			...evidence.files.map(
-				(file) =>
-					`[${file.id}] ${file.status} ${file.path}${file.oldPath ? ` <- ${file.oldPath}` : ""}\nkind=${file.kind}\nmemberships=${file.memberships.join(",") || "none"}\noldMemberships=${file.oldMemberships.join(",") || "none"}\n${file.evidence}`,
-			),
-			"Bounded affected-entry structural previews:",
-			...previews,
-		].join("\n\n"),
-		MAX_TOTAL_EVIDENCE,
-	);
-}
-
-export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence): ContextSyncPlan {
-	if (!isRecord(input) || (input.outcome !== "no-change" && input.outcome !== "apply"))
-		throw new Error("Context sync submission is malformed.");
-	const reason = typeof input.reason === "string" ? input.reason.trim() : "";
-	if (!reason) throw new Error("Context sync reason is required.");
-	if (input.outcome === "no-change") {
-		if ("changes" in input) throw new Error("no-change must not include changes.");
-		const uncovered = evidence.files.filter((file) => file.kind !== "deleted" && file.memberships.length === 0);
-		if (uncovered.length > 0 || evidence.missingPaths.size > 0)
-			throw new Error("no-change cannot leave uncovered changed files or stale catalog paths.");
-		return { outcome: "no-change", reason };
-	}
-	if (!Array.isArray(input.changes) || input.changes.length === 0)
-		throw new Error("apply requires at least one change.");
-	const current = new Map(evidence.entries.map((entry) => [entry.id, entry]));
-	const changes: ContextSyncChange[] = [];
-	const seen = new Set<string>();
-	for (const raw of input.changes) {
-		if (!isRecord(raw) || (raw.action !== "set-entry" && raw.action !== "delete-entry"))
-			throw new Error("Invalid context sync change.");
-		const tab = validSlug(String(raw.tab ?? ""), "Context tab");
-		const concept = validSlug(String(raw.concept ?? ""), "Context concept");
-		const entry = validSlug(String(raw.entry ?? ""), "Context entry");
-		const id = `${tab}/${concept}/${entry}`;
-		if (seen.has(id)) throw new Error(`Duplicate context change: ${id}`);
-		seen.add(id);
-		const existing = current.get(id);
-		if (raw.action === "delete-entry") {
-			if (!existing || !evidence.affectedIds.has(id)) throw new Error(`Entry is not eligible for deletion: ${id}`);
-			changes.push({ action: "delete-entry", tab, concept, entry });
-			continue;
-		}
-		const conceptName = typeof raw.conceptName === "string" ? raw.conceptName.trim() : "";
-		const conceptDescription = typeof raw.conceptDescription === "string" ? raw.conceptDescription.trim() : "";
-		const description = typeof raw.description === "string" ? raw.description.trim() : "";
-		if (
-			!conceptName ||
-			!description ||
-			!Array.isArray(raw.files) ||
-			raw.files.length === 0 ||
-			raw.files.some((path) => typeof path !== "string")
-		)
-			throw new Error(`Invalid set-entry: ${id}`);
-		const files = [
-			...new Set((raw.files as string[]).map((path) => normalizeProjectPath(evidence.root, path))),
-		].sort();
-		if (files.some((path) => !evidence.eligibleFiles.has(path)))
-			throw new Error(`Entry uses a path outside the eligible scope: ${id}`);
-		if (existing) {
-			const conceptId = `${tab}/${concept}`;
-			if (!evidence.affectedIds.has(id) && !evidence.affectedConcepts.has(conceptId))
-				throw new Error(`Entry is unrelated: ${id}`);
-			if (conceptName !== existing.conceptName || conceptDescription !== existing.conceptDescription)
-				throw new Error(`Existing concept metadata cannot change: ${conceptId}`);
-			if (description === existing.description && files.join("\0") === contextEntryPaths(existing).join("\0"))
-				throw new Error(`Set-entry is identical: ${id}`);
-		} else {
-			const existingConcept = evidence.entries.find((item) => item.tab === tab && item.concept === concept);
-			if (
-				existingConcept &&
-				(conceptName !== existingConcept.conceptName || conceptDescription !== existingConcept.conceptDescription)
-			)
-				throw new Error(`Existing concept metadata cannot change: ${tab}/${concept}`);
-			if (!files.some((path) => evidence.dirtyExisting.has(path) || evidence.dependencies.has(path)))
-				throw new Error(`New entry lacks a dirty file or dependency: ${id}`);
-			if (
-				!existingConcept &&
-				(!files.some((path) => evidence.dirtyExisting.has(path)) ||
-					files.some((path) => !evidence.eligibleFiles.has(path)))
-			)
-				throw new Error(`New concept is outside the affected scope: ${tab}/${concept}`);
-		}
-		changes.push({ action: "set-entry", tab, concept, conceptName, conceptDescription, entry, description, files });
-	}
-	const final = new Map(evidence.entries.map((entry) => [entry.id, contextEntryPaths(entry)]));
-	for (const change of changes) {
-		const id = `${change.tab}/${change.concept}/${change.entry}`;
-		if (change.action === "delete-entry") final.delete(id);
-		else final.set(id, change.files);
-	}
-	for (const change of changes.filter(
-		(item): item is Extract<ContextSyncChange, { action: "delete-entry" }> => item.action === "delete-entry",
-	)) {
-		const old = current.get(`${change.tab}/${change.concept}/${change.entry}`);
-		if (!old) continue;
-		for (const path of contextEntryPaths(old))
-			if (evidence.eligibleFiles.has(path) && ![...final.values()].some((files) => files.includes(path)))
-				throw new Error(`Deleting entry would orphan surviving file: ${path}`);
-	}
-	for (const path of evidence.dirtyExisting)
-		if (![...final.values()].some((files) => files.includes(path)))
-			throw new Error(`Context sync would leave changed file uncovered: ${path}`);
-	for (const files of final.values())
-		for (const path of files)
-			if (evidence.missingPaths.has(path)) throw new Error(`Context sync would leave stale path: ${path}`);
-	return { outcome: "apply", reason, changes };
-}
-
-async function computeWorktreeSignature(
-	git: GitRunner,
-	root: string,
-	files: readonly Pick<SyncDirtyFile, "path" | "untracked">[],
-): Promise<string> {
-	const hash = createHash("sha256");
-	const status = await git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root });
-	const [staged, unstaged] = await Promise.all([
-		git.run(["diff", "--cached", "--no-color", "--no-ext-diff"], { cwd: root, optional: true }),
-		git.run(["diff", "--no-color", "--no-ext-diff"], { cwd: root, optional: true }),
-	]);
-	hash.update(status);
-	hash.update("\0staged\0");
-	hash.update(staged);
-	hash.update("\0unstaged\0");
-	hash.update(unstaged);
-	for (const file of files.filter((item) => item.untracked).sort((a, b) => a.path.localeCompare(b.path))) {
-		try {
-			const info = await stat(join(root, file.path));
-			hash.update(`\0${file.path}:${info.size}:${info.mtimeMs}`);
-			if (info.isFile() && info.size <= MAX_UNTRACKED_BYTES) hash.update(await readFile(join(root, file.path)));
-		} catch {
-			hash.update(`\0${file.path}:missing`);
-		}
-	}
-	return hash.digest("hex");
-}
-
-async function computeCatalogSignature(root: string): Promise<string> {
-	const hash = createHash("sha256");
+async function catalogFileSnapshot(root: string): Promise<Map<string, string>> {
+	const snapshot = new Map<string, string>();
 	const base = join(root, ".pi", "contexts");
-	if (!(await pathExists(base))) return hash.digest("hex");
+	if (!(await pathExists(base))) return snapshot;
 	for (const tab of (await readdir(base, { withFileTypes: true }))
 		.filter((item) => item.isDirectory())
 		.sort((a, b) => a.name.localeCompare(b.name))) {
 		for (const file of (await readdir(join(base, tab.name), { withFileTypes: true }))
 			.filter((item) => item.isFile() && extname(item.name) === ".toml")
 			.sort((a, b) => a.name.localeCompare(b.name))) {
-			const path = join(base, tab.name, file.name);
-			hash.update(relative(root, path));
-			hash.update("\0");
-			hash.update(await readFile(path));
-			hash.update("\0");
+			const absolute = join(base, tab.name, file.name);
+			const path = relative(root, absolute).split(sep).join("/");
+			const hash = createHash("sha256")
+				.update(await readFile(absolute))
+				.digest("hex");
+			snapshot.set(path, hash);
 		}
 	}
-	return hash.digest("hex");
+	return snapshot;
 }
 
-export async function applyContextSyncPlan(
-	root: string,
-	plan: Extract<ContextSyncPlan, { outcome: "apply" }>,
-	entries: readonly ContextEntry[],
-	verifyFreshness?: () => Promise<void>,
-): Promise<ContextSyncDetails> {
-	for (const change of plan.changes) if (change.action === "set-entry") await requireFiles(root, change.files);
-	const concepts = [...new Set(plan.changes.map((change) => `${change.tab}/${change.concept}`))].sort();
-	const eagerPaths = new Set(entries.flatMap((entry) => entry.files));
-	const anchorPaths = new Set(entries.flatMap((entry) => entry.anchors).filter((path) => !eagerPaths.has(path)));
-	const outputs = new Map<string, string | undefined>();
-	for (const key of concepts) {
-		const [tab, concept] = key.split("/");
-		if (!tab || !concept) continue;
-		const path = join(root, ".pi", "contexts", tab, `${concept}.toml`);
-		const raw: Record<string, unknown> = (await pathExists(path))
-			? (parse(await readFile(path, "utf8")) as Record<string, unknown>)
-			: {};
-		for (const change of plan.changes.filter((item) => item.tab === tab && item.concept === concept)) {
-			if (change.action === "delete-entry") delete raw[change.entry];
-			else {
-				if (raw.name === undefined) raw.name = change.conceptName;
-				if (raw.description === undefined) raw.description = change.conceptDescription;
-				const anchors = change.files.filter((path) => anchorPaths.has(path));
-				raw[change.entry] = {
-					description: change.description,
-					files: change.files.filter((path) => !anchors.includes(path)),
-					...(anchors.length ? { anchors } : {}),
-				};
-			}
-		}
-		outputs.set(
-			path,
-			Object.keys(raw).some((key) => key !== "name" && key !== "description") ? stringify(raw) : undefined,
-		);
-	}
-	const paths = [...outputs.keys()].sort();
-	const lockPaths = [...new Set([...paths, ...entries.map((entry) => entry.path)])].sort();
-	const originals = new Map<string, Buffer | undefined>();
-	for (const path of paths) originals.set(path, (await pathExists(path)) ? await readFile(path) : undefined);
-	const temporaryFiles = new Map<string, string>();
-	try {
-		await acquireMutationQueues(lockPaths, async () => {
-			await verifyFreshness?.();
-			for (const path of paths) {
-				const output = outputs.get(path);
-				if (output === undefined) continue;
-				await mkdir(dirname(path), { recursive: true });
-				const temporary = `${path}.${process.pid}.${Date.now()}.${temporaryFiles.size}.tmp`;
-				await writeFile(temporary, output, "utf8");
-				temporaryFiles.set(path, temporary);
-			}
-			const changed: string[] = [];
-			try {
-				for (const path of paths) {
-					const temporary = temporaryFiles.get(path);
-					if (!temporary) await rm(path, { force: true });
-					else await rename(temporary, path);
-					changed.push(path);
-				}
-			} catch (error) {
-				for (const path of changed.reverse()) {
-					const original = originals.get(path);
-					if (original === undefined) await rm(path, { force: true });
-					else {
-						await mkdir(dirname(path), { recursive: true });
-						await writeFile(path, original);
-					}
-				}
-				throw error;
-			}
-		});
-	} finally {
-		await Promise.all([...temporaryFiles.values()].map((path) => rm(path, { force: true })));
-	}
-	for (const path of paths.filter((path) => outputs.get(path) === undefined))
-		await rm(dirname(path), { recursive: false }).catch(() => undefined);
-	const currentIds = new Set(entries.map((entry) => entry.id));
-	const created = plan.changes.filter(
-		(change) => change.action === "set-entry" && !currentIds.has(`${change.tab}/${change.concept}/${change.entry}`),
-	).length;
-	const updated = plan.changes.filter(
-		(change) => change.action === "set-entry" && currentIds.has(`${change.tab}/${change.concept}/${change.entry}`),
-	).length;
-	const deleted = plan.changes.filter((change) => change.action === "delete-entry").length;
-	const changedContextFiles = paths.map((path) => relative(root, path).split(sep).join("/"));
-	const summary = `Updated ${updated} context entries; created ${created}; removed ${deleted}.`;
-	return {
-		outcome: "applied",
-		summary,
-		changedContextFiles,
-		reason: plan.reason,
-		changes: plan.changes,
-		counts: { created, updated, deleted, unchanged: entries.length - updated - deleted },
-	};
+function changedCatalogPaths(before: Map<string, string>, after: Map<string, string>): string[] {
+	const paths = new Set([...before.keys(), ...after.keys()]);
+	return [...paths]
+		.filter((path) => before.get(path) !== after.get(path))
+		.sort((left, right) => left.localeCompare(right));
 }
 
-async function acquireMutationQueues<T>(paths: readonly string[], task: () => Promise<T>, index = 0): Promise<T> {
-	const path = paths[index];
-	if (!path) return task();
-	return withFileMutationQueue(path, () => acquireMutationQueues(paths, task, index + 1));
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+// Ensure evidence tool name stays aligned with agent definition tooling.
+export const CONTEXT_SYNC_REQUIRED_TOOLS = [
+	"read",
+	"ls",
+	"find",
+	"grep",
+	"bash",
+	"patch",
+	CONTEXT_SYNC_EVIDENCE_TOOL,
+] as const;