pi-plans 0.2.0 → 0.3.1

package/tests/ask-choice.test.ts

@@ -0,0 +1,264 @@
+/** Behavior tests for the ask_choice trailing option (post-execution
+ * amelioration prompt): Auto-refine loop replaces Auto-complete, the
+ * auto-answer mode is suppressed, and headless sessions stop instead of
+ * auto-answering. */
+
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, before, describe, it } from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fitAskChoicePanel, OPTION_MAX_LINES, PANEL_CHROME_LINES, PANEL_SAFETY_MARGIN, SELECTOR_WIDTH_OVERHEAD, STATUS_BAR_HEIGHT, registerAskChoiceTool } from "../tools/ask-choice.ts";
+import { visibleWidth } from "../src/refine-ui-helpers.ts";
+
+type ToolDef = {
+	execute: (id: string, params: any, signal: undefined, update: undefined, ctx: any) => Promise<any>;
+};
+
+let root: string;
+
+before(() => {
+	root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-ask-choice-"));
+});
+
+after(() => {
+	fs.rmSync(root, { recursive: true, force: true });
+});
+
+function loadTool(): ToolDef {
+	let tool: ToolDef | undefined;
+	const pi = {
+		registerTool: (definition: ToolDef) => {
+			tool = definition;
+		},
+	} as unknown as ExtensionAPI;
+	registerAskChoiceTool(pi);
+	if (!tool) throw new Error("ask_choice tool not registered");
+	return tool;
+}
+
+let notifyCalls: Array<{ message: string; severity?: string }> = [];
+
+function makeCtx(opts: {
+	hasUI?: boolean;
+	select: (question: string, labels: string[]) => Promise<string | undefined>;
+}) {
+	notifyCalls = [];
+	return {
+		cwd: root,
+		hasUI: opts.hasUI ?? true,
+		sessionManager: {},
+		ui: {
+			select: opts.select,
+			input: async () => "typed",
+			notify: (message: string, severity?: string) => {
+				notifyCalls.push({ message, severity });
+			},
+		},
+	};
+}
+
+const OPTIONS = [
+	{ label: "Run one Reviewer round", recommended: true },
+	{ label: "Run a Criticizer round" },
+	{ label: "Finish here" },
+];
+
+describe("ask_choice trailing option", () => {
+	it("renders Auto-refine loop as the trailing option and suppresses Auto-complete", async () => {
+		const tool = loadTool();
+		let seenLabels: string[] = [];
+		const ctx = makeCtx({
+			select: async (_question, labels) => {
+				seenLabels = labels;
+				return labels.find((label) => label.startsWith("Auto-refine loop"));
+			},
+		});
+		const result = await tool.execute("t1", {
+			question: "Ameliorate?",
+			options: OPTIONS,
+			autoComplete: true, // deliberately erroneous: trailing must suppress it
+			trailing: "auto-refine-loop",
+		}, undefined, undefined, ctx);
+
+		assert.equal(seenLabels.at(-1)?.startsWith("Auto-refine loop"), true, "Auto-refine loop must be last");
+		assert.equal(seenLabels.some((label) => label.startsWith("Auto-complete")), false, "Auto-complete must be absent");
+		const text = result.content[0].text as string;
+		assert.match(text, /User selected Auto-refine loop/);
+		assert.match(text, /until no high-severity finding \(hard cap 5 rounds\)/);
+		assert.match(text, /goal wait: continue until no unpassed VCs remain/);
+		assert.match(text, /refine \(role: "reviewer", target: "implementation"\)/);
+		assert.equal(result.details.source, "user");
+		assert.equal(result.details.answer, "Auto-refine loop");
+	});
+
+	it("keeps Auto-complete as the trailing option without the trailing param", async () => {
+		const tool = loadTool();
+		let seenLabels: string[] = [];
+		const ctx = makeCtx({
+			select: async (_question, labels) => {
+				seenLabels = labels;
+				return labels[0];
+			},
+		});
+		await tool.execute("t2", {
+			question: "Planning question?",
+			options: OPTIONS,
+			autoComplete: true,
+		}, undefined, undefined, ctx);
+		assert.equal(seenLabels.at(-1)?.startsWith("Auto-complete"), true);
+		assert.equal(seenLabels.some((label) => label.startsWith("Auto-refine loop")), false);
+	});
+
+	it("never auto-answers a trailing question in headless sessions", async () => {
+		const tool = loadTool();
+		const ctx = makeCtx({ hasUI: false, select: async () => undefined });
+		await assert.rejects(
+			tool.execute("t3", {
+				question: "Ameliorate?",
+				options: OPTIONS,
+				autoComplete: true,
+				trailing: "auto-refine-loop",
+			}, undefined, undefined, ctx),
+			/No UI available/,
+		);
+	});
+});
+
+describe("ask_choice panel fitting", () => {
+	it("sanitizes newlines in the question and labels", () => {
+		const fitted = fitAskChoicePanel("Q line1\nQ line2", [{ core: "1. a\nb", display: "1. a\nb — desc" }], 100, 30);
+		assert.doesNotMatch(fitted.question, /\r?\n/);
+		for (const label of fitted.labels) assert.doesNotMatch(label, /\r?\n/);
+	});
+
+	it("caps each label at the 3-line budget with a .. marker (CJK included)", () => {
+		const columns = 100;
+		const budget = OPTION_MAX_LINES * Math.max(20, columns - SELECTOR_WIDTH_OVERHEAD);
+		const cjkLabel = `1. ${"选项".repeat(200)}`; // 800 visible columns, far over the budget
+		const fitted = fitAskChoicePanel("q", [{ core: cjkLabel, display: cjkLabel }], columns, 60);
+		assert.equal(fitted.labels.length, 1);
+		assert.ok(visibleWidth(fitted.labels[0]) <= budget, `label exceeds 3-line budget: ${visibleWidth(fitted.labels[0])}`);
+		assert.match(fitted.labels[0], /\.\.$/);
+	});
+
+	it("degrades: stage 1 strips descriptions before touching labels", () => {
+		const columns = 100;
+		const rows = 30; // rowBudget = 27 → content budget 17 lines after chrome
+		const items = Array.from({ length: 12 }, (_, i) => ({
+			core: `${i + 1}. option-${i}`,
+			display: `${i + 1}. option-${i} — ${"detail ".repeat(40)}`,
+		}));
+		const fitted = fitAskChoicePanel("q", items, columns, rows);
+		for (const label of fitted.labels) assert.doesNotMatch(label, /detail/);
+		assert.match(fitted.labels[0] ?? "", /^1\. option-0/);
+	});
+
+	it("degrades: stage 2 collapses labels to one line before truncating the question", () => {
+		const columns = 100;
+		const rows = 30;
+		const items = Array.from({ length: 15 }, (_, i) => ({
+			core: `${i + 1}. ${"x".repeat(170)}`,
+			display: `${i + 1}. ${"x".repeat(170)} — description`,
+		}));
+		const fitted = fitAskChoicePanel("the question", items, columns, rows);
+		for (const label of fitted.labels) assert.ok(visibleWidth(label) <= Math.max(20, columns - SELECTOR_WIDTH_OVERHEAD));
+		assert.equal(fitted.question, "the question"); // question untouched at stage 2
+	});
+
+	it("warns once when even the minimal form exceeds a tiny terminal", () => {
+		const columns = 60;
+		const rows = 12; // rowBudget = 9; 30 options can never fit
+		const items = Array.from({ length: 30 }, (_, i) => ({ core: `${i + 1}. opt-${i}`, display: `${i + 1}. opt-${i}` }));
+		const fitted = fitAskChoicePanel("q", items, columns, rows);
+		assert.equal(fitted.overflowWarned, true);
+		for (const label of fitted.labels) assert.ok(visibleWidth(label) <= 20);
+	});
+
+	it("degrades: stage 3 truncates the question only after labels are single-lined", () => {
+		const columns = 100;
+		const rows = 32; // rowBudget = 29; chrome 9 → content budget 20 lines
+		const longQuestion = "q".repeat(300);
+		const items = Array.from({ length: 18 }, (_, i) => ({ core: `${i + 1}. opt-${i}`, display: `${i + 1}. opt-${i}` }));
+		const fitted = fitAskChoicePanel(longQuestion, items, columns, rows);
+		assert.equal(fitted.overflowWarned, false); // stops at stage 3, not the minimal form
+		assert.ok(visibleWidth(fitted.question) <= Math.max(20, columns - SELECTOR_WIDTH_OVERHEAD));
+		assert.match(fitted.question, /\.\.$/);
+		assert.match(fitted.labels[0] ?? "", /^1\. opt-0$/); // labels stay single-line and untruncated
+	});
+
+	it("keeps Other/Auto-complete/Auto-refine prefixes alive even on tiny terminals", () => {
+		const columns = 26;
+		const rows = 12; // minimal form: 20-column floor
+		const items = [
+			{ core: "1. keep-current", display: "1. keep-current" },
+			{ core: "Other…  (type your own answer)", display: "Other…  (type your own answer)", fixed: true },
+			{ core: "Auto-complete  (take the recommended option)", display: "Auto-complete  (take the recommended option)", fixed: true },
+			{ core: "Auto-refine loop  (run refinement rounds until no high-severity finding or the 5-round cap)", display: "Auto-refine loop  (run refinement rounds until no high-severity finding or the 5-round cap)", fixed: true },
+		];
+		const fitted = fitAskChoicePanel("q", items, columns, rows);
+		assert.match(fitted.labels[1] ?? "", /^Other…/);
+		assert.match(fitted.labels[2] ?? "", /^Auto-complete/);
+		assert.match(fitted.labels[3] ?? "", /^Auto-refine loop/);
+	});
+
+	it("execute notifies once when the minimal form still overflows a tiny terminal", async () => {
+		const tool = loadTool();
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-ask-choice-overflow-"));
+		const rowsDesc = Object.getOwnPropertyDescriptor(process.stdout, "rows");
+		const colsDesc = Object.getOwnPropertyDescriptor(process.stdout, "columns");
+		Object.defineProperty(process.stdout, "rows", { value: 12, configurable: true });
+		Object.defineProperty(process.stdout, "columns", { value: 60, configurable: true });
+		try {
+			const ctx = makeCtx({
+				select: async (_question, labels) => labels[0],
+			});
+			// makeCtx binds cwd at construction; point it at the temp dir via workdir param instead.
+			await tool.execute(
+				"id",
+				{
+					question: "Pick one",
+					options: Array.from({ length: 30 }, (_, i) => ({ label: `opt-${i}`, description: `${"detail ".repeat(20)}` })),
+					autoComplete: false,
+					allowOther: false,
+					workdir: dir,
+				},
+				undefined,
+				undefined,
+				ctx,
+			);
+			assert.equal(notifyCalls.length, 1);
+			assert.match(notifyCalls[0]!.message, /Terminal too small/);
+		} finally {
+			if (rowsDesc) Object.defineProperty(process.stdout, "rows", rowsDesc);
+			if (colsDesc) Object.defineProperty(process.stdout, "columns", colsDesc);
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("pi-tui Text renders every fitted label within 3 lines at real panel width", async () => {
+		let Text: any;
+		try {
+			({ Text } = await import("@earendil-works/pi-tui"));
+		} catch {
+			return; // D-007 sanctioned fallback: pi-tui not resolvable in this layout
+		}
+		const columns = 100;
+		const rows = 60;
+		const realWidth = columns - 4; // border + padding + marker, per extension-selector.js
+		const items = Array.from({ length: 8 }, (_, i) => ({
+			core: `${i + 1}. option-${i}`,
+			display: `${i + 1}. option-${i} — ${"中文描述 " .repeat(30)}mixed ascii tail ${"x".repeat(60)}`,
+		}));
+		const fitted = fitAskChoicePanel("q", items, columns, rows);
+		let totalLines = PANEL_CHROME_LINES + 1; // chrome + question line
+		for (const label of fitted.labels) {
+			const component = new Text(label, 1, 0);
+			const rendered = component.render(realWidth);
+			assert.ok(rendered.length <= OPTION_MAX_LINES, `label renders ${rendered.length} lines: ${JSON.stringify(label.slice(0, 60))}`);
+			totalLines += rendered.length;
+		}
+		assert.ok(totalLines < rows - STATUS_BAR_HEIGHT - PANEL_SAFETY_MARGIN);
+	});
+});

package/tests/autocomplete.test.ts

@@ -132,11 +132,16 @@ describe("ask_choice Auto-complete wiring", () => {
 		assert.match(source, /isAutoCompleteEnabled/);
 		assert.match(source, /recordAskChoice\(ctx, true\)/);
 		assert.match(source, /autoComplete && selected\.startsWith\("Auto-complete"\)/);
+		// Trailing option: Auto-refine loop replaces Auto-complete and is suppressed in headless sessions.
+		assert.match(source, /trailing === undefined/);
+		assert.match(source, /AUTO_REFINE_LOOP_LABEL/);
+		assert.match(source, /trailing && selected\.startsWith\("Auto-refine loop"\)/);
 		const indexSource = fs.readFileSync(path.join(process.cwd(), "index.ts"), "utf8");
 		assert.match(indexSource, /plans-autocomplete-stop/);
 		assert.match(indexSource, /autoCompleteStatus\(ctx\)/);
 		assert.match(indexSource, /restoreAutoCompleteFromSession/);
 		const execSource = fs.readFileSync(path.join(process.cwd(), "src", "exec.ts"), "utf8");
-		assert.match(execSource, /customType === AUTOCOMPLETE_ENTRY/);
+		assert.doesNotMatch(execSource, /customType === AUTOCOMPLETE_ENTRY/);
+		assert.match(execSource, /shouldTriggerPlanningCompaction\(_ctx: ExtensionContext\): boolean \{\n\s+return false;/);
 	});
 });

package/tests/code-graph-apply-action.test.ts

@@ -0,0 +1,173 @@
+/** Tests for the agent-invokable code_graph "apply" action and its gates. */
+
+import * as assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
+import { test } from "node:test";
+import { Store } from "../src/code-graph/store.ts";
+import { runIndex } from "../src/code-graph/indexer.ts";
+import { applyGraphCore } from "../src/code-graph/commands.ts";
+import { updateFile } from "../src/code-graph/mutations.ts";
+import { makeBackend } from "../src/code-graph/parsers/javascript.ts";
+import { PythonBackend } from "../src/code-graph/parsers/python.ts";
+import { loadGraphRuntime } from "../src/code-graph/runtime.ts";
+import type { ParserBackend } from "../src/code-graph/parser.ts";
+import type { Language } from "../src/code-graph/types.ts";
+import { initState, setRunStatus, startRun } from "../src/state.ts";
+import { registerCodeGraphTool } from "../tools/code-graph.ts";
+
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+
+function git(cwd: string, args: string[]): void {
+	const env: Record<string, string | undefined> = { ...process.env };
+	for (const key of ["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE"]) delete env[key];
+	const result = spawnSync("git", args, { cwd, env, encoding: "utf8" });
+	assert.equal(result.status, 0, `${args.join(" ")} failed: ${result.stderr}`);
+}
+
+async function setupIndexedRepo(): Promise<{ root: string; store: Store; cleanup: () => void } | null> {
+	const runtime = await loadGraphRuntime();
+	if (!runtime.status.parserAvailable || !runtime.status.sqliteAvailable) return null;
+
+	const raw = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-apply-action-"));
+	git(raw, ["init", "--initial-branch=main"]);
+	git(raw, ["config", "user.email", "test@example.com"]);
+	git(raw, ["config", "user.name", "test"]);
+	fs.writeFileSync(path.join(raw, "math.js"), "function add(a, b) { return a + b; }\n");
+	git(raw, ["add", "-A"]);
+	git(raw, ["commit", "-m", "init"]);
+	const root = fs.realpathSync(raw);
+
+	const ParserCtor = runtime.runtime.parser.Parser as unknown as new () => {
+		parse(input: string | Buffer): unknown;
+		setLanguage(language: unknown): void;
+	};
+	const parsers: Record<Language, ParserBackend> = {
+		javascript: makeBackend("javascript", ParserCtor, runtime.runtime.parser.javascript),
+		typescript: makeBackend("typescript", ParserCtor, runtime.runtime.parser.typescript),
+		tsx: makeBackend("tsx", ParserCtor, runtime.runtime.parser.tsx),
+		python: new PythonBackend(ParserCtor, runtime.runtime.parser.python),
+	};
+	fs.mkdirSync(path.join(root, ".git", "pi_plans"), { recursive: true });
+	const store = new Store(
+		{ dbPath: path.join(root, ".git", "pi_plans", "code_graph.db"), worktreeRoot: root, gitCommonDir: path.join(root, ".git") },
+		runtime.runtime.sqlite,
+	);
+	runIndex({ store, worktreeRoot: root, parsers, reindex: false });
+	return {
+		root,
+		store,
+		cleanup: () => {
+			store.close();
+			try {
+				fs.rmSync(raw, { recursive: true, force: true });
+			} catch {
+				/* ignore */
+			}
+		},
+	};
+}
+
+test("applyGraphCore refuses during planning runs and allows once executing or done", async (t) => {
+	const opened = await setupIndexedRepo();
+	if (!opened) return;
+	t.after(() => opened.cleanup());
+	const { root } = opened;
+
+	initState(root);
+	const { run } = startRun(root, { topic: "apply-gate", skill: "plan-small", requestText: "x" });
+
+	const planning = await applyGraphCore(root);
+	assert.match(planning.refused ?? "", /planning run is currently planning or accepted/);
+	assert.equal(planning.report, undefined);
+
+	setRunStatus(root, run.run_id, "executing");
+	const mathBefore = fs.readFileSync(path.join(root, "math.js"), "utf8");
+	const allowed = await applyGraphCore(root);
+	assert.equal(allowed.refused, undefined);
+	assert.ok(allowed.report, "expected a report once allowed");
+	assert.ok(allowed.drift, "expected a drift summary once allowed");
+	// Safe no-op with no pending staged edits: disk untouched, nothing stale or errored.
+	assert.equal(fs.readFileSync(path.join(root, "math.js"), "utf8"), mathBefore);
+	const noPendingCounts: Record<string, number> = { ok: 0, deleted: 0, stale: 0, "skipped-missing": 0, error: 0 };
+	for (const file of allowed.report!.files) noPendingCounts[file.status] = (noPendingCounts[file.status] ?? 0) + 1;
+	assert.equal(noPendingCounts.stale, 0);
+	assert.equal(noPendingCounts.error, 0);
+
+	setRunStatus(root, run.run_id, "done");
+	const doneAllowed = await applyGraphCore(root);
+	assert.equal(doneAllowed.refused, undefined);
+	assert.ok(doneAllowed.report, "done runs must still be allowed");
+});
+
+test("applyGraphCore materializes pending DB edits and reports counts plus drift", async (t) => {
+	const opened = await setupIndexedRepo();
+	if (!opened) return;
+	t.after(() => opened.cleanup());
+	const { root, store } = opened;
+	initState(root); // no active run → allowed
+
+	const next = "function add(a, b) { return a + b + 1; }\n";
+	const mutation = updateFile(store, { fileDir: ".", fileName: "math.js", text: next });
+	assert.equal(mutation.ok, true);
+	// Disk still has the original content before apply.
+	assert.equal(fs.readFileSync(path.join(root, "math.js"), "utf8"), "function add(a, b) { return a + b; }\n");
+
+	const core = await applyGraphCore(root);
+	assert.equal(core.refused, undefined);
+	assert.ok(core.report);
+	const counts: Record<string, number> = { ok: 0, deleted: 0, stale: 0, "skipped-missing": 0, error: 0 };
+	for (const file of core.report.files) counts[file.status] = (counts[file.status] ?? 0) + 1;
+	assert.ok(counts.ok >= 1, "at least the staged file must materialize");
+	assert.equal(fs.readFileSync(path.join(root, "math.js"), "utf8"), next);
+	assert.ok(core.drift);
+	assert.equal(core.drift.pending, 0);
+	assert.equal(core.drift.ok, true);
+});
+
+test("code_graph tool apply action: refiner env refuses, planning gate holds, wiring present", async (t) => {
+	const source = fs.readFileSync(path.join(ROOT, "tools", "code-graph.ts"), "utf8");
+	assert.match(source, /"apply"/);
+	assert.match(source, /PI_PLANS_REFINER/);
+	assert.match(source, /applyGraphCore/);
+
+	const opened = await setupIndexedRepo();
+	if (!opened) return;
+	t.after(() => opened.cleanup());
+	const { root } = opened;
+	initState(root);
+	const { run } = startRun(root, { topic: "apply-tool", skill: "plan-small", requestText: "x" });
+
+	let captured: {
+		execute: (id: string, params: any, signal: unknown, onUpdate: unknown, ctx: any) => Promise<{ content: Array<{ type: string; text: string }> }>;
+	} | undefined;
+	registerCodeGraphTool({
+		registerTool: (definition: never) => {
+			captured = definition as typeof captured;
+		},
+	} as never);
+	assert.ok(captured, "registerTool was not called");
+
+	// Refiner marker refuses before any run-state lookup.
+	const previous = process.env.PI_PLANS_REFINER;
+	process.env.PI_PLANS_REFINER = "1";
+	try {
+		const refused = await captured!.execute("c1", { action: "apply", workdir: root }, undefined, undefined, { cwd: root });
+		const payload = JSON.parse(refused.content[0]!.text) as { ok: boolean; reason: string };
+		assert.equal(payload.ok, false);
+		assert.match(payload.reason, /PI_PLANS_REFINER/);
+	} finally {
+		if (previous === undefined) delete process.env.PI_PLANS_REFINER;
+		else process.env.PI_PLANS_REFINER = previous;
+	}
+
+	// Planning run (without the marker) is refused by the run-state gate.
+	setRunStatus(root, run.run_id, "planning");
+	const gateRefused = await captured!.execute("c2", { action: "apply", workdir: root }, undefined, undefined, { cwd: root });
+	const gatePayload = JSON.parse(gateRefused.content[0]!.text) as { ok: boolean; reason: string };
+	assert.equal(gatePayload.ok, false);
+	assert.match(gatePayload.reason, /planning run is currently planning or accepted/);
+});

package/tests/code-graph-apply.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Verifies the DB-to-source materializer refuses stale source unless force,
+ * and roundtrips bytes for unchanged content.
+ */
+
+import { test } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Store } from "../src/code-graph/store.ts";
+import { materialize, materializeFile } from "../src/code-graph/materialize.ts";
+import { runIndex } from "../src/code-graph/indexer.ts";
+import { makeBackend } from "../src/code-graph/parsers/javascript.ts";
+import { PythonBackend } from "../src/code-graph/parsers/python.ts";
+import { loadGraphRuntime } from "../src/code-graph/runtime.ts";
+import type { ParserBackend } from "../src/code-graph/parser.ts";
+import type { Language } from "../src/code-graph/types.ts";
+
+async function setup(): Promise<{ store: Store; cleanup: () => void } | null> {
+	try {
+		const sqlite = await import("node:sqlite");
+		const worktreeRoot = fs.realpathSync(os.tmpdir());
+		const dbPath = path.join(os.tmpdir(), `code-graph-apply-${process.pid}-${Date.now()}.db`);
+		const store = new Store({ dbPath, worktreeRoot, gitCommonDir: worktreeRoot }, sqlite);
+		store.close();
+		const reopened = new Store({ dbPath, worktreeRoot, gitCommonDir: worktreeRoot }, sqlite);
+		return { store: reopened, cleanup: () => {
+			reopened.close();
+			try { fs.unlinkSync(dbPath); } catch { /* ignore */ }
+		} };
+	} catch {
+		return null;
+	}
+}
+
+function hashText(text: string): string {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+test("materialize refuses stale source unless force is set", async (t) => {
+	const opened = await setup();
+	if (!opened) return;
+	t.after(() => opened.cleanup());
+	const { store } = opened;
+	const worktreeRoot = fs.realpathSync(os.tmpdir());
+	const fileDir = "graph-apply-fixture";
+	const fileName = "demo.txt";
+	const absoluteDir = path.join(worktreeRoot, fileDir);
+	fs.mkdirSync(absoluteDir, { recursive: true });
+	const original = "hello graph";
+	fs.writeFileSync(path.join(absoluteDir, fileName), original);
+	const sourceHash = hashText(original);
+	store.tx(() => {
+		store.db
+			.prepare(
+				`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, updated_at)
+				 VALUES (?, ?, ?, ?, ?, ?)`,
+			)
+			.run(fileDir, fileName, "javascript", sourceHash, original, new Date().toISOString());
+		store.db
+			.prepare(
+				`INSERT INTO file_entries (file_dir, file_name, ordinal, kind, function_name, start_byte, end_byte, text)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+			)
+			.run(fileDir, fileName, 0, "raw", null, 0, original.length, original);
+	});
+	// File matches DB hash: write succeeds.
+	const okResult = materializeFile(store, worktreeRoot, fileDir, fileName);
+	assert.equal(okResult.status, "ok");
+	// Now mutate the source on disk to be stale.
+	fs.writeFileSync(path.join(absoluteDir, fileName), "external change");
+	const staleResult = materializeFile(store, worktreeRoot, fileDir, fileName);
+	assert.equal(staleResult.status, "stale");
+	const forceResult = materializeFile(store, worktreeRoot, fileDir, fileName, { force: true });
+	assert.equal(forceResult.status, "ok");
+	assert.equal(fs.readFileSync(path.join(absoluteDir, fileName), "utf8"), original);
+	fs.rmSync(absoluteDir, { recursive: true, force: true });
+});
+
+test("pending_kind drives convergence: update writes/creates, delete purges, missing skips", async (t) => {
+	const sqliteAvailable = (async () => { try { await import("node:sqlite"); return true; } catch { return false; } })();
+	if (!(await sqliteAvailable)) return;
+	const sqlite = await import("node:sqlite");
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-graph-pending-"));
+	t.after(() => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ } });
+	const store = new Store({ dbPath: path.join(dir, "g.db"), worktreeRoot: dir, gitCommonDir: path.join(dir, ".git") }, sqlite);
+	t.after(() => store.close());
+	const now = new Date().toISOString();
+
+	// 1. pending update creates a missing file (new-file path).
+	store.tx(() => {
+		store.db.prepare(
+			`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, pending_kind, updated_at)
+			 VALUES ('.', 'new.js', 'javascript', 'x', 'function n() { return 1; }\n', 'update', ?)`,
+		).run(now);
+	});
+	const created = materializeFile(store, dir, ".", "new.js");
+	assert.equal(created.status, "ok");
+	assert.equal(fs.readFileSync(path.join(dir, "new.js"), "utf8"), "function n() { return 1; }\n");
+	const cleared = store.read(() => store.db.prepare(`SELECT pending_kind FROM files WHERE file_name = 'new.js'`).get()) as { pending_kind: string | null };
+	assert.equal(cleared.pending_kind, null, "pending cleared after apply");
+
+	// 2. pending delete removes disk file and DB rows.
+	fs.writeFileSync(path.join(dir, "doomed.js"), "function d() {}\n");
+	store.tx(() => {
+		store.db.prepare(
+			`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, pending_kind, updated_at)
+			 VALUES ('.', 'doomed.js', 'javascript', 'x', 'function d() {}\n', 'delete', ?)`,
+		).run(now);
+		store.db.prepare(
+			`INSERT INTO functions (file_dir, file_name, function_name, language, kind, full_code, full_code_hash, render_code, render_code_hash,
+			 move_supported, is_primary, provenance_start_byte, provenance_end_byte, provenance_start_line, provenance_start_col,
+			 provenance_end_line, provenance_end_col, version)
+			 VALUES ('.', 'doomed.js', 'd', 'javascript', 'declaration', 'function d() {}', 'h', 'function d() {}', 'h', 1, 1, 0, 18, 1, 1, 1, 19, 1)`,
+		).run();
+	});
+	const deleted = materializeFile(store, dir, ".", "doomed.js");
+	assert.equal(deleted.status, "deleted");
+	assert.equal(fs.existsSync(path.join(dir, "doomed.js")), false, "disk file removed");
+	const rows = store.read(() => store.db.prepare(`SELECT COUNT(*) AS c FROM files WHERE file_name = 'doomed.js'`).get()) as { c: number };
+	assert.equal(rows.c, 0, "DB rows purged");
+
+	// 3. pending-NULL + missing on disk: skipped, not resurrected.
+	store.tx(() => {
+		store.db.prepare(
+			`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, pending_kind, updated_at)
+			 VALUES ('.', 'ghost.js', 'javascript', 'x', 'function g() {}\n', NULL, ?)`,
+		).run(now);
+	});
+	const skipped = materializeFile(store, dir, ".", "ghost.js");
+	assert.equal(skipped.status, "skipped-missing");
+	assert.equal(fs.existsSync(path.join(dir, "ghost.js")), false, "ghost not resurrected");
+});
+
+test("materialize never rewrites pending-NULL files from real-index manifests", async (t) => {
+	let sqlite: typeof import("node:sqlite");
+	try {
+		sqlite = await import("node:sqlite");
+	} catch {
+		return;
+	}
+	const runtime = await loadGraphRuntime();
+	if (!runtime.status.parserAvailable || !runtime.status.sqliteAvailable) return;
+	const ParserCtor = runtime.runtime.parser.Parser as unknown as new () => {
+		parse(input: string | Buffer): unknown;
+		setLanguage(language: unknown): void;
+	};
+	const parsers: Record<Language, ParserBackend> = {
+		javascript: makeBackend("javascript", ParserCtor, runtime.runtime.parser.javascript),
+		typescript: makeBackend("typescript", ParserCtor, runtime.runtime.parser.typescript),
+		tsx: makeBackend("tsx", ParserCtor, runtime.runtime.parser.tsx),
+		python: new PythonBackend(ParserCtor, runtime.runtime.parser.python),
+	};
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-graph-apply-real-"));
+	t.after(() => {
+		try {
+			fs.rmSync(dir, { recursive: true, force: true });
+		} catch {
+			/* ignore */
+		}
+	});
+	const source = "export function add(a: number, b: number): number { return a + b; }\n";
+	fs.writeFileSync(path.join(dir, "math.ts"), source);
+	const store = new Store({ dbPath: path.join(dir, "g.db"), worktreeRoot: dir, gitCommonDir: path.join(dir, ".git") }, sqlite);
+	t.after(() => store.close());
+	await runIndex({ store, worktreeRoot: dir, parsers });
+
+	// Real indexes store empty/overlapping render-unit texts; a pending-NULL
+	// apply must treat source_text as canonical and not rewrite the file.
+	const report = materialize({ store, worktreeRoot: dir });
+	assert.ok(report.files.every((file) => file.status === "ok"), JSON.stringify(report.files));
+	assert.equal(fs.readFileSync(path.join(dir, "math.ts"), "utf8"), source);
+
+	// force converges from source_text, never from manifest reassembly.
+	fs.writeFileSync(path.join(dir, "math.ts"), "tampered\n");
+	const forced = materialize({ store, worktreeRoot: dir, force: true });
+	assert.ok(forced.files.every((file) => file.status === "ok"), JSON.stringify(forced.files));
+	assert.equal(fs.readFileSync(path.join(dir, "math.ts"), "utf8"), source);
+});