pi-plans 0.1.2 → 0.3.0

package/tests/ask-choice.test.ts

@@ -0,0 +1,263 @@
+/** 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, /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

@@ -0,0 +1,147 @@
+/** Tests for run-scoped Auto-complete and planning continuation. */
+
+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 {
+	autoCompleteStatus,
+	disableAutoComplete,
+	enableAutoComplete,
+	isAutoCompleteEnabled,
+	markPlanWritten,
+	recordAskChoice,
+	registerAutoCompleteTurnHandlers,
+	restoreAutoCompleteFromSession,
+	setAutoCompleteApi,
+} from "../src/autocomplete.ts";
+import { initState, setRunStatus, startRun } from "../src/state.ts";
+
+let root: string;
+
+function makeRun(name: string): { workdir: string; runId: string } {
+	const workdir = path.join(root, name);
+	fs.mkdirSync(workdir, { recursive: true });
+	initState(workdir);
+	const { run } = startRun(workdir, { topic: name, skill: "plan-small", requestText: "test" });
+	return { workdir, runId: run.run_id };
+}
+
+function makeContext(workdir: string, sessionManager: any = {}): any {
+	return {
+		cwd: workdir,
+		hasUI: true,
+		mode: "tui",
+		sessionManager,
+		ui: {
+			select: async (_question: string, options: string[]) => options.at(-1),
+			input: async () => "typed",
+		},
+	};
+}
+
+before(() => {
+	root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-autocomplete-"));
+});
+
+after(() => {
+	setAutoCompleteApi(null);
+	fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe("Auto-complete state", () => {
+	it("enables only for the active planning run and restores only while planning", () => {
+		const { workdir, runId } = makeRun("restore");
+		const entries: any[] = [];
+		setAutoCompleteApi({ appendEntry: (customType: string, data: unknown) => entries.push({ type: "custom", customType, data }) } as any);
+		const ctx = makeContext(workdir);
+
+		assert.equal(enableAutoComplete(ctx), true);
+		assert.equal(autoCompleteStatus(ctx), "enabled");
+		assert.equal(entries.at(-1)?.data.runId, runId);
+
+		const restored = makeContext(workdir);
+		restoreAutoCompleteFromSession(restored, entries);
+		assert.equal(isAutoCompleteEnabled(restored), true);
+
+		setRunStatus(workdir, runId, "done");
+		const finished = makeContext(workdir);
+		restoreAutoCompleteFromSession(finished, entries);
+		assert.equal(autoCompleteStatus(finished), "disabled");
+
+		const stoppedEntries = [...entries, { type: "custom", customType: "pi-plans-autocomplete", data: { runId, enabled: false } }];
+		const stopped = makeContext(workdir);
+		restoreAutoCompleteFromSession(stopped, stoppedEntries);
+		assert.equal(autoCompleteStatus(stopped), "disabled");
+	});
+
+	it("clears explicitly and marks plan writes as a continuation boundary", () => {
+		const { workdir } = makeRun("clear");
+		const entries: any[] = [];
+		setAutoCompleteApi({ appendEntry: (customType: string, data: unknown) => entries.push({ customType, data }) } as any);
+		const ctx = makeContext(workdir);
+		enableAutoComplete(ctx);
+		markPlanWritten(ctx);
+		recordAskChoice(ctx, true);
+		assert.equal(disableAutoComplete(ctx, "test"), true);
+		assert.equal(autoCompleteStatus(ctx), "disabled");
+		assert.equal(entries.at(-1)?.data.enabled, false);
+	});
+});
+
+describe("Auto-complete continuation", () => {
+	it("queues one follow-up after an early stop and none after a natural next question", async () => {
+		const { workdir } = makeRun("continuation");
+		const session = {};
+		const sent: any[] = [];
+		const handlers = new Map<string, Function[]>();
+		const pi: any = {
+			on: (name: string, handler: Function) => handlers.set(name, [...(handlers.get(name) ?? []), handler]),
+			appendEntry: () => {},
+			sendUserMessage: async (content: string, options: unknown) => sent.push({ content, options }),
+		};
+		setAutoCompleteApi(pi);
+		registerAutoCompleteTurnHandlers(pi);
+		const ctx = makeContext(workdir, session);
+		enableAutoComplete(ctx);
+		await handlers.get("turn_start")?.[0]?.({}, ctx);
+		recordAskChoice(ctx, true);
+		await handlers.get("turn_end")?.[0]?.({ message: { role: "assistant" } }, ctx);
+		await handlers.get("turn_end")?.[0]?.({ message: { role: "assistant" } }, ctx);
+		assert.equal(sent.length, 1);
+		assert.equal((sent[0]!.options as any).deliverAs, "followUp");
+
+		await handlers.get("turn_start")?.[0]?.({}, ctx);
+		recordAskChoice(ctx, true);
+		markPlanWritten(ctx);
+		await handlers.get("turn_end")?.[0]?.({ message: { role: "assistant" } }, ctx);
+		assert.equal(sent.length, 1);
+
+		await handlers.get("turn_start")?.[0]?.({}, ctx);
+		recordAskChoice(ctx, true);
+		recordAskChoice(ctx, false);
+		await handlers.get("turn_end")?.[0]?.({ message: { role: "assistant" } }, ctx);
+		assert.equal(sent.length, 1);
+	});
+});
+
+describe("ask_choice Auto-complete wiring", () => {
+	it("routes eligible questions through the run-scoped mode", () => {
+		const source = fs.readFileSync(path.join(process.cwd(), "tools", "ask-choice.ts"), "utf8");
+		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.doesNotMatch(execSource, /customType === AUTOCOMPLETE_ENTRY/);
+		assert.match(execSource, /shouldTriggerPlanningCompaction\(_ctx: ExtensionContext\): boolean \{\n\s+return false;/);
+	});
+});

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);
+});