gentle-pi 3.3.0 → 3.4.0

package/tests/questionnaire-view.test.ts

@@ -0,0 +1,446 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	CURSOR_MARKER,
+	KeybindingsManager,
+	TUI_KEYBINDINGS,
+	visibleWidth,
+	type TuiMouseEvent,
+} from "@earendil-works/pi-tui";
+import {
+	MIN_PREVIEW_WIDTH,
+	QuestionnaireView,
+	type QuestionnaireResult,
+	type QuestionnaireTheme,
+} from "../lib/questionnaire/questionnaire-view.ts";
+import { CUSTOM_ROW_LABEL, type OptionData, type QuestionData } from "../lib/questionnaire/schema.ts";
+
+const theme: QuestionnaireTheme = {
+	fg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
+const option = (label: string, description = `${label} description`, preview?: string): OptionData =>
+	preview === undefined ? { label, description } : { label, description, preview };
+
+const question = (
+	text: string,
+	options: OptionData[],
+	overrides: { header?: string; multiSelect?: boolean } = {},
+): QuestionData => ({
+	question: text,
+	header: overrides.header ?? "Header",
+	options,
+	...(overrides.multiSelect === undefined ? {} : { multiSelect: overrides.multiSelect }),
+});
+
+const single = (preview?: string): QuestionData[] => [
+	question("Proceed?", [option("Alpha", "First choice", preview), option("Beta", "Second choice")]),
+];
+
+const two = (): QuestionData[] => [
+	question("First?", [option("Alpha"), option("Beta")], { header: "First" }),
+	question("Second?", [option("Gamma"), option("Delta")], { header: "Second" }),
+];
+
+function createView(
+	questions: QuestionData[],
+	options: { onComplete?: (result: QuestionnaireResult) => void; keybindings?: KeybindingsManager } = {},
+): QuestionnaireView {
+	return new QuestionnaireView({
+		questions,
+		theme,
+		onComplete: options.onComplete,
+		...(options.keybindings === undefined ? {} : { keybindings: options.keybindings }),
+	});
+}
+
+function viewWithResult(questions: QuestionData[], keybindings?: KeybindingsManager) {
+	const completed: QuestionnaireResult[] = [];
+	const view = createView(questions, {
+		onComplete: (result) => completed.push(result),
+		...(keybindings === undefined ? {} : { keybindings }),
+	});
+	return { view, completed };
+}
+
+function render(view: QuestionnaireView, width = 100): string {
+	return view.render(width).join("\n");
+}
+
+/** Strip SGR styling so assertions see the visible text, not cursor escape codes. */
+function plain(text: string): string {
+	return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function assertFits(view: QuestionnaireView, width: number): void {
+	for (const line of view.render(width)) {
+		assert.ok(
+			visibleWidth(line) <= width,
+			`rendered line exceeds width ${width}: ${JSON.stringify(line)}`,
+		);
+	}
+}
+
+function mouseEvent(lines: string[], row: number, type: TuiMouseEvent["type"]): TuiMouseEvent {
+	return {
+		type,
+		button: "left",
+		x: 1,
+		y: row,
+		screenX: 1,
+		screenY: row,
+		width: 100,
+		height: lines.length,
+		shift: false,
+		alt: false,
+		ctrl: false,
+	};
+}
+
+// Real terminal key sequences: legacy (ESC [) and application-cursor (ESC O).
+const KEY = {
+	up: ["\x1b[A", "\x1bOA"],
+	down: ["\x1b[B", "\x1bOB"],
+	enter: "\r",
+	space: " ",
+	tab: "\t",
+	shiftTab: "\x1b[Z",
+	escape: "\x1b",
+} as const;
+
+test("renders exactly one active question plus a tab strip for all questions", () => {
+	const { view } = viewWithResult(two());
+	const rendered = render(view);
+
+	// Tab strip: progress plus every header, active one marked.
+	assert.match(rendered, /\[1\/2\]/);
+	assert.match(rendered, /▸ First/);
+	assert.match(rendered, /Second/);
+
+	// Only the first question body renders; the second body is absent.
+	assert.match(rendered, /First\?/);
+	assert.match(rendered, /❯ Alpha/);
+	assert.doesNotMatch(rendered, /Gamma/);
+	assert.doesNotMatch(rendered, /Delta/);
+	assert.doesNotMatch(rendered, /Second\?/);
+});
+
+test("Tab and Shift-Tab switch the active question and preserve cursor and toggles", () => {
+	const { view, completed } = viewWithResult([
+		question("First?", [option("Alpha"), option("Beta")], { header: "First" }),
+		question("Second?", [option("Gamma"), option("Delta")], { header: "Second", multiSelect: true }),
+	]);
+
+	view.handleInput(KEY.down[0]); // First: cursor -> Beta
+	view.handleInput(KEY.tab);
+	let rendered = render(view);
+	assert.match(rendered, /\[2\/2\]/);
+	assert.match(rendered, /▸ Second/);
+	assert.match(rendered, /❯ \[ \] Gamma/);
+	assert.doesNotMatch(rendered, /❯ Beta/);
+	assert.doesNotMatch(rendered, /First\?/);
+
+	view.handleInput(KEY.space); // Second: toggle Gamma
+	assert.match(render(view), /❯ \[x\] Gamma/);
+
+	view.handleInput(KEY.shiftTab);
+	rendered = render(view);
+	assert.match(rendered, /\[1\/2\]/);
+	assert.match(rendered, /❯ Beta/); // cursor preserved
+	assert.doesNotMatch(rendered, /Gamma/); // second body hidden again
+
+	view.handleInput(KEY.tab);
+	assert.match(render(view), /❯ \[x\] Gamma/); // toggle preserved
+	assert.equal(completed.length, 0);
+});
+
+test("real key sequences drive the cursor and commit in legacy and application-cursor form", () => {
+	for (const down of KEY.down) {
+		const { view, completed } = viewWithResult(single());
+		view.handleInput(down);
+		assert.match(render(view), /❯ Beta/, `down sequence ${JSON.stringify(down)} should move the cursor`);
+		view.handleInput(KEY.enter);
+		assert.equal(completed.length, 1, `enter after ${JSON.stringify(down)} should commit`);
+		assert.deepEqual(view.getResult().answers, [
+			{ questionIndex: 0, question: "Proceed?", kind: "option", answer: "Beta" },
+		]);
+	}
+
+	for (const up of KEY.up) {
+		const { view } = viewWithResult(single());
+		view.handleInput(KEY.down[0]);
+		view.handleInput(KEY.down[0]);
+		view.handleInput(up);
+		assert.match(render(view), /❯ Beta/, `up sequence ${JSON.stringify(up)} should move the cursor back`);
+	}
+});
+
+test("the injected KeybindingsManager drives the same navigation and commit", () => {
+	const keybindings = new KeybindingsManager(TUI_KEYBINDINGS);
+	const { view, completed } = viewWithResult(single(), keybindings);
+
+	assert.ok(keybindings.matches(KEY.down[0], "tui.select.down"));
+	view.handleInput(KEY.down[0]);
+	assert.match(render(view), /❯ Beta/);
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 1);
+	assert.equal(view.getResult().answers[0]?.answer, "Beta");
+});
+
+test("single-select commits on Enter and advances to the next unanswered question", () => {
+	const { view, completed } = viewWithResult(two());
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 0, "the questionnaire is not done while a question is unanswered");
+	assert.equal(view.getResult().answers.length, 1);
+	assert.equal(view.activeQuestion, 1, "a commit advances to the next unanswered question");
+	assert.match(render(view), /\[2\/2\]/);
+	assert.match(render(view), /❯ Gamma/);
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 1);
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "First?", kind: "option", answer: "Alpha" },
+		{ questionIndex: 1, question: "Second?", kind: "option", answer: "Gamma" },
+	]);
+});
+
+test("multi-select toggles with space and requires a non-empty selection to commit", () => {
+	const { view, completed } = viewWithResult([
+		question("Pick?", [option("One"), option("Two")], { multiSelect: true }),
+	]);
+	assert.match(render(view), /\[ \] One/);
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 0, "an empty multiSelect commit is a no-op");
+	assert.equal(view.getResult().answers.length, 0);
+
+	view.handleInput(KEY.space);
+	assert.match(render(view), /\[x\] One/);
+
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.space);
+	assert.match(render(view), /\[x\] Two/);
+
+	view.handleInput(KEY.space);
+	assert.match(render(view), /\[ \] Two/);
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 1);
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "Pick?", kind: "multi", answer: null, selected: ["One"] },
+	]);
+});
+
+test("custom row opens the editor, empty submit returns, and the draft survives a tab switch", () => {
+	const { view, completed } = viewWithResult(two());
+
+	// Move to the custom row on question one and open the editor.
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.enter);
+	assert.match(render(view), /Custom response/);
+	assert.match(render(view), /> /);
+
+	view.handleInput("   ");
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 0, "a whitespace-only submission stays uncommitted");
+	assert.doesNotMatch(render(view), /Custom response/);
+
+	// Reopen, type a draft, switch away, and come back: the draft is preserved.
+	view.handleInput(KEY.enter);
+	view.handleInput("draft text");
+	view.handleInput(KEY.tab);
+	assert.equal(view.activeQuestion, 1, "tab switches question even while editing");
+	view.handleInput(KEY.shiftTab);
+	assert.equal(view.activeQuestion, 0);
+	view.handleInput(KEY.enter); // still on the custom row
+	assert.match(plain(render(view)), /draft text/, "the custom draft is restored on reopen");
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 0, "one of two questions answered is not completion");
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "First?", kind: "custom", answer: "draft text" },
+	]);
+});
+
+test("multi-select can commit a custom answer with the toggled options", () => {
+	const { view } = viewWithResult([question("Pick?", [option("One"), option("Two")], { multiSelect: true })]);
+	view.handleInput(KEY.space);
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.enter);
+
+	assert.match(render(view), /Custom response/);
+	view.handleInput("free note");
+	view.handleInput(KEY.enter);
+
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "Pick?", kind: "custom", answer: "free note", selected: ["One"] },
+	]);
+});
+
+test("preview renders beside the list only while the focused option has one", () => {
+	const { view } = viewWithResult(single("Preview body line"));
+	const wide = render(view, 100);
+	assert.match(wide, /Preview body line/);
+	assert.match(wide, /❯ Alpha/);
+
+	view.handleInput(KEY.down[0]); // Beta has no preview
+	const collapsed = render(view, 100);
+	assert.doesNotMatch(collapsed, /Preview body line/);
+	assert.match(collapsed, /❯ Beta/);
+	assertFits(view, 100);
+});
+
+test("the preview pane wraps cleanly and never exceeds the terminal width", () => {
+	const body = "lorem ipsum dolor sit amet ".repeat(12);
+	const { view } = viewWithResult([
+		question("Proceed?", [option("Alpha", "First choice", body), option("Beta")]),
+	]);
+	for (const width of [MIN_PREVIEW_WIDTH, 100, 120]) {
+		assertFits(view, width);
+	}
+	assert.match(render(view, 100), /lorem ipsum/);
+});
+
+test("narrow widths render the preview inline without corrupting the body", () => {
+	const { view } = viewWithResult(single("Inline preview body"));
+	const narrow = render(view, 60);
+	assert.match(narrow, /Inline preview body/);
+	assert.match(narrow, /❯ Alpha/);
+	assert.match(narrow, /Type something\./);
+	assertFits(view, 60);
+});
+
+test("height stays bounded as the question count grows", () => {
+	const one = viewWithResult([question("Only?", [option("A"), option("B")], { header: "Only" })]);
+	const many = viewWithResult([
+		question("One?", [option("A"), option("B")], { header: "One" }),
+		question("Two?", [option("C"), option("D")], { header: "Two" }),
+		question("Three?", [option("E"), option("F")], { header: "Three" }),
+		question("Four?", [option("G"), option("H")], { header: "Four" }),
+	]);
+
+	const oneLines = one.view.render(100).length;
+	const manyLines = many.view.render(100).length;
+	assert.ok(
+		manyLines <= oneLines + 2,
+		`four questions must not stack bodies (one=${oneLines}, many=${manyLines})`,
+	);
+	// Only the first body renders, so later bodies stay absent.
+	const rendered = render(many.view, 100);
+	assert.doesNotMatch(rendered, /Two\?/);
+	assert.doesNotMatch(rendered, /Four\?/);
+	assert.match(rendered, /❯ A/);
+});
+
+test("Escape cancels the questionnaire with a cancelled result", () => {
+	const { view, completed } = viewWithResult(single());
+	view.handleInput(KEY.escape);
+	assert.equal(completed.length, 1);
+	assert.deepEqual(view.getResult(), { cancelled: true, answers: [] });
+});
+
+test("focus propagates to the free-text input for IME cursor positioning", () => {
+	const { view } = viewWithResult(single());
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.down[0]);
+	view.handleInput(KEY.enter);
+
+	view.focused = true;
+	assert.ok(render(view).includes(CURSOR_MARKER), "a focused view positions the input cursor");
+
+	view.focused = false;
+	assert.ok(!render(view).includes(CURSOR_MARKER), "an unfocused view hides the input cursor");
+});
+
+test("a committed option carries its preview on the answer row", () => {
+	const { view } = viewWithResult(single("Preview body line"));
+	view.handleInput(KEY.enter);
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "Proceed?", kind: "option", answer: "Alpha", preview: "Preview body line" },
+	]);
+});
+
+test("pointer press focuses a row and click commits it", () => {
+	const { view, completed } = viewWithResult(single());
+	const lines = view.render(100);
+	const betaRow = lines.findIndex((line) => line.includes("Beta"));
+	assert.ok(betaRow >= 0);
+
+	assert.equal(view.handleMouse(mouseEvent(lines, betaRow, "press"))?.handled, true);
+	assert.equal(completed.length, 0, "press focuses but never answers");
+	const afterPress = view.render(100);
+	const betaRowAfterPress = afterPress.findIndex((line) => line.includes("Beta"));
+	assert.equal(view.handleMouse(mouseEvent(afterPress, betaRowAfterPress, "click"))?.handled, true);
+	assert.equal(completed.length, 1);
+	assert.equal(view.getResult().answers[0]?.answer, "Beta");
+});
+
+test("pointer click toggles a multi-select option instead of committing", () => {
+	const { view, completed } = viewWithResult([
+		question("Pick?", [option("One"), option("Two")], { multiSelect: true }),
+	]);
+
+	let lines = view.render(100);
+	assert.equal(view.handleMouse(mouseEvent(lines, lines.findIndex((line) => line.includes("One")), "click"))?.handled, true);
+	assert.equal(completed.length, 0, "a multi-select click toggles without committing");
+	assert.match(render(view), /\[x\] One/);
+
+	// Clicking the same option again un-toggles it; still no commit.
+	lines = view.render(100);
+	view.handleMouse(mouseEvent(lines, lines.findIndex((line) => line.includes("One")), "click"));
+	assert.match(render(view), /\[ \] One/);
+	assert.equal(completed.length, 0);
+
+	// Toggle two options with the mouse, then commit with the keyboard.
+	lines = view.render(100);
+	view.handleMouse(mouseEvent(lines, lines.findIndex((line) => line.includes("One")), "click"));
+	lines = view.render(100);
+	view.handleMouse(mouseEvent(lines, lines.findIndex((line) => line.includes("Two")), "click"));
+	assert.match(render(view), /\[x\] One/);
+	assert.match(render(view), /\[x\] Two/);
+
+	view.handleInput(KEY.enter);
+	assert.equal(completed.length, 1);
+	assert.deepEqual(view.getResult().answers, [
+		{ questionIndex: 0, question: "Pick?", kind: "multi", answer: null, selected: ["One", "Two"] },
+	]);
+});
+
+test("pointer click on the custom row opens the editor without committing", () => {
+	for (const questions of [single(), [question("Pick?", [option("One"), option("Two")], { multiSelect: true })]]) {
+		const { view, completed } = viewWithResult(questions);
+		const lines = view.render(100);
+		const customRow = lines.findIndex((line) => line.includes(CUSTOM_ROW_LABEL));
+		assert.ok(customRow >= 0);
+
+		assert.equal(view.handleMouse(mouseEvent(lines, customRow, "click"))?.handled, true);
+		assert.match(render(view), /Custom response/);
+		assert.equal(completed.length, 0, "opening the custom editor never commits");
+	}
+});
+
+test("the custom row is always appended after the authored options", () => {
+	const { view } = viewWithResult(single());
+	const lines = view.render(100);
+	const betaRow = lines.findIndex((line) => line.includes("Beta"));
+	const customRow = lines.findIndex((line) => line.includes(CUSTOM_ROW_LABEL));
+	assert.ok(betaRow >= 0 && customRow >= 0);
+	assert.ok(customRow > betaRow);
+});
+
+test("every rendered line fits the width across 1-4 questions", () => {
+	const questions = [
+		question("One?", [option("A"), option("B", "B description", "preview ".repeat(20))], { header: "One" }),
+		question("Two?", [option("C"), option("D")], { header: "Two", multiSelect: true }),
+		question("Three?", [option("E"), option("F")], { header: "Three" }),
+		question("Four?", [option("G"), option("H")], { header: "Four" }),
+	];
+	const { view } = viewWithResult(questions);
+	for (const width of [40, 60, 80, 100, 140]) {
+		assertFits(view, width);
+	}
+});

package/tests/rdd-status-line.test.ts

@@ -55,8 +55,8 @@ function modeResult(effective: "on" | "off", source: (typeof NATIVE_REVIEW_MODE_
 		operation: NATIVE_REVIEW_MODE_OPERATION.STATUS,
 		scope: "global",
 		status: {
-			global: effective,
-			cloneLocal: "",
+			global: source === NATIVE_REVIEW_MODE_SOURCE.GLOBAL ? effective : "",
+			cloneLocal: source === NATIVE_REVIEW_MODE_SOURCE.CLONE_LOCAL ? effective : "",
 			effective,
 			source,
 		},
@@ -97,6 +97,17 @@ test("renderRddStatusLine renders the effective mode and deciding source", () =>
 	);
 });
 
+test("synthetic default-ON status renders and is injected without a Shell default override", async () => {
+	clearRddStatusMemoForTesting();
+	const result = modeResult("on", NATIVE_REVIEW_MODE_SOURCE.DEFAULT);
+	assert.deepEqual(result.status, { global: "", cloneLocal: "", effective: "on", source: "default" });
+	const expected = "Receipt-driven development: on (decided by default)";
+	assert.equal(renderRddStatusLine(result.status), expected);
+	const line = await resolveRddStatusLine(fakeReviewMode(result), "/repo-synthetic-default-on");
+	assert.equal(line, expected);
+	assert.ok(getOrchestratorPrompt(process.cwd(), undefined, line).includes(expected));
+});
+
 test("renderRddStatusLine fails closed to unknown for a malformed or partial status object", () => {
 	// A bad upstream decode, a future field rename, or a hand-built fixture
 	// must never render an unrecognized value verbatim -- the render boundary
@@ -122,8 +133,8 @@ test("resolveRddModeStatus reads the on status from a stubbed native reviewMode
 	clearRddStatusMemoForTesting();
 	const status = await resolveRddModeStatus(fakeReviewMode(modeResult("on", NATIVE_REVIEW_MODE_SOURCE.CLONE_LOCAL)), "/repo-on");
 	assert.deepEqual(status, {
-		global: "on",
-		cloneLocal: "",
+		global: "",
+		cloneLocal: "on",
 		effective: "on",
 		source: "clone_local",
 	});
@@ -212,6 +223,12 @@ test("resolveRddStatusLine renders on, off, and unavailable from the stubbed nat
 		await resolveRddStatusLine(fakeReviewMode(modeResult("off", NATIVE_REVIEW_MODE_SOURCE.DEFAULT)), "/repo-line-off"),
 		"Receipt-driven development: off (decided by default)",
 	);
+	for (const source of [NATIVE_REVIEW_MODE_SOURCE.GLOBAL, NATIVE_REVIEW_MODE_SOURCE.CLONE_LOCAL]) {
+		assert.equal(
+			await resolveRddStatusLine(fakeReviewMode(modeResult("off", source)), `/repo-line-off-${source}`),
+			`Receipt-driven development: off (decided by ${source})`,
+		);
+	}
 	assert.equal(
 		await resolveRddStatusLine(undefined, "/repo-line-unknown"),
 		"Receipt-driven development: unknown (native status unavailable)",

package/tests/review-candidate-owner-retry.test.ts

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { withWindowsSystemProbeRetry } from "../lib/review-candidate-view-owner.ts";
+
+function failingProbe(code: string, attempts: { count: number }): () => string {
+	return () => {
+		attempts.count += 1;
+		const error = new Error(`fixture probe failure (${code})`) as NodeJS.ErrnoException;
+		error.code = code;
+		throw error;
+	};
+}
+
+test("windows system probe retries once on a transient timeout and returns the recovered value", () => {
+	const attempts = { count: 0 };
+	let recovered = false;
+	const value = withWindowsSystemProbeRetry(() => {
+		attempts.count += 1;
+		if (attempts.count === 1) {
+			const error = new Error("fixture probe timeout") as NodeJS.ErrnoException;
+			error.code = "ETIMEDOUT";
+			throw error;
+		}
+		recovered = true;
+		return "S-1-5-21-1";
+	});
+	assert.equal(value, "S-1-5-21-1");
+	assert.equal(recovered, true);
+	assert.equal(attempts.count, 2);
+});
+
+test("windows system probe does not retry authority-class failures", () => {
+	for (const code of ["EPERM", "EACCES", "ENOENT"]) {
+		const attempts = { count: 0 };
+		const probe = failingProbe(code, attempts);
+		assert.throws(() => withWindowsSystemProbeRetry(probe), (error: NodeJS.ErrnoException) => error.code === code);
+		assert.equal(attempts.count, 1, `code ${code} must fail closed without a retry`);
+	}
+});
+
+test("windows system probe fails closed after two transient failures", () => {
+	const attempts = { count: 0 };
+	const probe = failingProbe("ETIMEDOUT", attempts);
+	let thrown: unknown;
+	try {
+		withWindowsSystemProbeRetry(probe);
+	} catch (error) {
+		thrown = error;
+	}
+	assert.equal(attempts.count, 2);
+	assert.ok(thrown instanceof Error);
+	assert.equal((thrown as NodeJS.ErrnoException).code, "ETIMEDOUT");
+});
+
+test("windows system probe does not retry when the first attempt succeeds", () => {
+	const attempts = { count: 0 };
+	const value = withWindowsSystemProbeRetry(() => {
+		attempts.count += 1;
+		return "S-1-5-18";
+	});
+	assert.equal(value, "S-1-5-18");
+	assert.equal(attempts.count, 1);
+});

package/tests/review-candidate-view.test.ts

@@ -510,6 +510,21 @@ test("owner fsync failure prevents worktree registration", (t) => {
 	assert.equal(adds, 0);
 });
 
+test("owner preparation failure names the transient cause code in the wrapper message", (t) => {
+	const cwd = repository(t);
+	t.mock.method(fs, "fsyncSync", () => {
+		const error = new Error("fixture probe timeout") as NodeJS.ErrnoException;
+		error.code = "ETIMEDOUT";
+		throw error;
+	});
+	syncBuiltinESMExports();
+	t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+	assert.throws(
+		() => new CandidateViewRegistry().create({ contributorRoot: cwd }),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "candidate-owner-preparation-failed" && error.cause instanceof Error && (error.cause as NodeJS.ErrnoException).code === "ETIMEDOUT" && /candidate view owner preparation failed \(ETIMEDOUT\)$/.test(error.message),
+	);
+});
+
 test("ordinary cleanup preserves mismatched owner and cleanupAll continues other records", (t) => {
 	const cwd = repository(t);
 	const registry = new CandidateViewRegistry();

package/tests/review-controller-native-routing.test.ts

@@ -959,6 +959,92 @@ test("ordinary START binds the native workspace candidate and returns the native
 	assert.equal(startCalls, 1);
 });
 
+test("ordinary START materializes an excluded-untracked candidate exactly once before native START", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "unrelated.md"), "not part of the review\n");
+	const target = startStatus(cwd, undefined, []);
+	const candidateViews = new CandidateViewRegistry();
+	t.after(() => candidateViews.cleanupAll());
+	const creation = t.mock.method(candidateViews, "createOrReuse");
+	let startCalls = 0;
+	const native = {
+		targetStatus: async () => target,
+		start: async () => {
+			startCalls += 1;
+			return { lineageId: "excluded-untracked-start", state: "reviewing", riskLevel: "low", selectedLenses: [], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: false, riskReasons: [], raw: {} };
+		},
+	} as unknown as NativeReviewCli;
+
+	const result = await __testing.executeReviewControllerOperation(
+		{ operation: "start", input: JSON.stringify({ mode: "ordinary" }) },
+		cwd, native, undefined, candidateViews,
+	);
+
+	assert.equal(result.operation, "start");
+	assert.equal(creation.mock.callCount(), 1);
+	assert.deepEqual(creation.mock.calls[0]!.arguments[0].intendedUntracked, []);
+	assert.equal(startCalls, 1);
+});
+
+test("ordinary START adopts the offered committed-range base while an untracked selection is in play", async (t) => {
+	// Live-reproduced blocker (gentle-pi#874): the committed-range adoption was
+	// skipped whenever an untracked selection was in play, so the provider's
+	// base-diff projection was compared against a base-less candidate view and
+	// assertNativeStartCandidateBinding failed with
+	// candidate-target-projection-drift before native START ever ran. An in-play
+	// selection must still pay the second read-only STATUS and materialize the
+	// candidate view WITH the offered base.
+	const cwd = repository(t);
+	// Commit the candidate change so a real committed range exists: the offered
+	// base commit's tree is the projection baseTree and the committed changed
+	// path is the candidate scope.
+	execFileSync("git", ["add", "tracked.txt"], { cwd });
+	execFileSync("git", ["-c", "user.name=Routing Test", "-c", "user.email=routing@example.invalid", "commit", "-m", "candidate"], { cwd });
+	const baseRef = execFileSync("git", ["rev-parse", "HEAD~1"], { cwd, encoding: "utf8" }).trim();
+	const selection = { untrackedScope: "exclude", expectedUntrackedInventory: "inventory-sha256", intendedUntracked: [] as string[] };
+	const offered = startStatus(cwd);
+	offered.nextTransition = {
+		kind: "execute",
+		reasonCode: "start_required",
+		execute: {
+			operation: "review.start",
+			arguments: [{ name: "base-ref", value: baseRef }, { name: "committed-only", value: "true" }],
+			preconditions: [],
+			binding: {},
+		},
+	} as unknown as ReviewStatusV3["nextTransition"];
+	const adopted = startStatus(cwd, baseRef, []);
+	const requests: Array<Record<string, unknown>> = [];
+	const candidateViews = new CandidateViewRegistry();
+	t.after(() => candidateViews.cleanupAll());
+	const creation = t.mock.method(candidateViews, "createOrReuse");
+	let startCalls = 0;
+	const native = {
+		targetStatus: async (request: Record<string, unknown>) => {
+			requests.push(request);
+			return requests.length === 1 ? offered : adopted;
+		},
+		start: async () => {
+			startCalls += 1;
+			return { lineageId: "adopted-base-untracked", state: "reviewing", riskLevel: "low", selectedLenses: [], changedFiles: 1, changedLines: 1, correctionBudget: 1, action: "created", lensesRequired: false, riskReasons: [], raw: {} };
+		},
+	} as unknown as NativeReviewCli;
+
+	const result = await __testing.executeReviewControllerOperation(
+		{ operation: "start", input: JSON.stringify({ mode: "ordinary", ...selection }) },
+		cwd, native, undefined, candidateViews,
+	);
+
+	assert.equal(result.operation, "start");
+	assert.deepEqual(requests, [
+		{ cwd, agent: "pi", ...selection },
+		{ cwd, agent: "pi", baseRef, committedOnly: true, ...selection },
+	]);
+	assert.equal(creation.mock.callCount(), 1);
+	assert.equal(creation.mock.calls[0]!.arguments[0].baseRef, baseRef, "the candidate view adopts the offered base");
+	assert.equal(startCalls, 1, "native START is reached exactly once without drift");
+});
+
 test("ordinary START preserves sanitized foreign diagnostics through one ambiguous reconciliation", async (t) => {
 	const cwd = repository(t);
 	const target = startStatus(cwd);