gentle-pi 4.3.0 → 4.4.0

package/tests/image-paste-chips.test.ts

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import test, { afterEach } from "node:test";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { resetCapabilitiesCache, setCapabilities, stripTerminalSequences as stripAnsi } from "@earendil-works/pi-tui";
+import { GentlePromptEditor, imageAttachmentsWidget, modelAcceptsImages } from "../extensions/gentle-shell.ts";
+import type { ClipboardImage } from "../lib/clipboard-image.ts";
+import { ImageAttachments } from "../lib/image-attachments.ts";
+import { createVimEditorAdapter } from "../lib/vim-editor-adapter.ts";
+import { createRequire } from "node:module";
+
+const INSTALLED_PI = (createRequire(import.meta.url)("@earendil-works/pi-tui/package.json") as { version: string }).version;
+
+// Prompt chips for pasted images (gentle-shell#2464): the paste key inserts an
+// atomic `[Image#N]`, one Backspace removes it, and Pi's own paste handler
+// stays the fallback for files, text and unsupported formats.
+
+type CtorParams = ConstructorParameters<typeof CustomEditor>;
+
+const PNG_2X1 = new Uint8Array([
+	0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+	0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+	0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x01,
+	0x08, 0x06, 0x00, 0x00, 0x00,
+]);
+const PASTE_KEY = "\x1bv";
+const BACKSPACE = "\x7f";
+const png = (): ClipboardImage => ({ bytes: PNG_2X1, mimeType: "image/png" });
+const settle = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+afterEach(() => resetCapabilitiesCache());
+
+function chipEditor(read: (() => Promise<ClipboardImage | null>) | undefined, attachments: ImageAttachments | undefined = new ImageAttachments()) {
+	const tui = { terminal: { rows: 30, columns: 100 }, requestRender() {} } as unknown as CtorParams[0];
+	const identity = (text: string) => text;
+	const theme = { borderColor: identity, selectList: {
+		selectedPrefix: identity, selectedText: identity, description: identity, scrollInfo: identity, noMatch: identity,
+	} } as unknown as CtorParams[1];
+	const keybindings = { matches: (data: string, action: string) => action === "app.clipboard.pasteImage" && data === PASTE_KEY } as unknown as CtorParams[2];
+	const editor = new GentlePromptEditor(tui, theme, keybindings, {
+		fg: (_role, text) => text, bold: identity, requestRender() {}, pending: () => false,
+		now: () => 0, doubleEscCancelEnabled: () => false, dispatchQueuedText() {},
+		attachments: read ? attachments : undefined, readClipboardImage: read,
+		notifyCompatibility: (message) => notices.push(message),
+	});
+	editor.focused = true;
+	const piPastes: string[] = [];
+	const notices: string[] = [];
+	// Pi's interactive mode installs its handler only when none is set yet.
+	if (!editor.onPasteImage) editor.onPasteImage = () => piPastes.push(editor.getText());
+	return { editor, attachments, piPastes, notices };
+}
+
+async function pastedChip(text: string) {
+	const chip = chipEditor(async () => png());
+	chip.editor.setText(text);
+	chip.editor.handleInput(PASTE_KEY);
+	await settle();
+	return chip;
+}
+
+const CTRL_W = "\x17";
+const DELETE = "\x1b[3~";
+const CTRL_LEFT = "\x1b[1;5D";
+const HOME = "\x1b[H";
+
+test("the paste key inserts an image chip, spaced from adjacent text", async () => {
+	const { editor, attachments, piPastes } = chipEditor(async () => png());
+	editor.setText("look");
+	editor.handleInput(PASTE_KEY);
+	await settle();
+	assert.equal(editor.getText(), "look [Image#1]");
+	assert.deepEqual(piPastes, []);
+	assert.equal(attachments.size, 1);
+});
+
+test("one Backspace removes the whole chip; typed look-alike text stays ordinary", async () => {
+	const { editor } = chipEditor(async () => png());
+	editor.setText("look");
+	editor.handleInput(PASTE_KEY);
+	await settle();
+	editor.handleInput(BACKSPACE);
+	assert.equal(editor.getText(), "look ");
+	editor.setText("[Image#7]");
+	editor.handleInput(BACKSPACE);
+	assert.equal(editor.getText(), "[Image#7");
+});
+
+test("word deletion and word motion treat a chip as one word", async () => {
+	const { editor } = await pastedChip("see");
+	assert.equal(editor.getText(), "see [Image#1]");
+	editor.handleInput(CTRL_W);
+	assert.equal(editor.getText(), "see ", "Ctrl+W removes the chip, never the word before it");
+	const moved = await pastedChip("see");
+	moved.editor.handleInput(CTRL_LEFT);
+	assert.deepEqual(moved.editor.getCursor(), { line: 0, col: 4 }, "Ctrl+Left stops at the chip start");
+});
+
+test("Delete in front of a chip removes the whole chip", async () => {
+	const { editor } = await pastedChip("");
+	editor.handleInput(HOME);
+	editor.handleInput(DELETE);
+	assert.equal(editor.getText(), "");
+});
+
+test("the Vim adapter keeps NORMAL boundaries out of a registered chip", async () => {
+	const { editor } = await pastedChip("a");
+	assert.deepEqual(editor.atomicSpans("a [Image#1]"), [{ start: 2, end: 11 }]);
+	assert.deepEqual(editor.atomicSpans("a [Image#9]"), [], "unregistered look-alikes stay ordinary text");
+	const adapter = createVimEditorAdapter(editor, INSTALLED_PI);
+	assert.deepEqual(adapter.motionBoundaries()[0], [0, 1, 2, 11]);
+});
+
+test("a clipboard read that finishes after the prompt is disposed changes nothing", async () => {
+	let resolve!: (image: ClipboardImage) => void;
+	const { editor, attachments, piPastes } = chipEditor(() => new Promise((done) => { resolve = done; }));
+	editor.handleInput(PASTE_KEY);
+	editor.dispose();
+	resolve(png());
+	await settle();
+	assert.equal(editor.getText(), "");
+	assert.equal(attachments.size, 0);
+	assert.deepEqual(piPastes, []);
+});
+
+test("a clipboard read that finishes after the draft was sent is discarded with a notice", async () => {
+	let resolve!: (image: ClipboardImage) => void;
+	const { editor, attachments, piPastes, notices } = chipEditor(() => new Promise((done) => { resolve = done; }));
+	const sent: string[] = [];
+	editor.onSubmit = (text) => sent.push(text);
+	editor.setText("what is this?");
+	editor.handleInput(PASTE_KEY);
+	editor.handleInput("\r");
+	resolve(png());
+	await settle();
+	assert.deepEqual(sent, ["what is this?"]);
+	assert.equal(editor.getText(), "", "the next draft stays empty");
+	assert.equal(attachments.size, 0, "no image waits to ride along with the next message");
+	assert.deepEqual(piPastes, []);
+	assert.deepEqual(notices, ["Image paste discarded: the message was sent before the clipboard finished reading. Paste again to attach it."]);
+});
+
+test("a clipboard read during an unsent draft still lands in that draft", async () => {
+	let resolve!: (image: ClipboardImage) => void;
+	const { editor, notices } = chipEditor(() => new Promise((done) => { resolve = done; }));
+	editor.setText("look");
+	editor.handleInput(PASTE_KEY);
+	editor.handleInput("!");
+	resolve(png());
+	await settle();
+	assert.equal(editor.getText(), "look! [Image#1]");
+	assert.deepEqual(notices, []);
+});
+
+test("a failure after the clipboard read is reported, never an unhandled rejection", async () => {
+	const attachments = new ImageAttachments();
+	attachments.add = () => { throw new Error("out of memory"); };
+	const { editor, notices } = chipEditor(async () => png(), attachments);
+	const unhandled: unknown[] = [];
+	const onUnhandled = (reason: unknown) => unhandled.push(reason);
+	process.on("unhandledRejection", onUnhandled);
+	try {
+		editor.handleInput(PASTE_KEY);
+		await settle();
+		await settle();
+	} finally {
+		process.off("unhandledRejection", onUnhandled);
+	}
+	assert.deepEqual(unhandled, []);
+	assert.deepEqual(notices, ["Image paste failed: out of memory"]);
+	assert.equal(editor.getText(), "");
+});
+
+test("without a clipboard image Pi's own paste handler runs unchanged", async () => {
+	const { editor, piPastes } = chipEditor(async () => null);
+	editor.setText("draft");
+	editor.handleInput(PASTE_KEY);
+	await settle();
+	assert.equal(editor.getText(), "draft");
+	assert.deepEqual(piPastes, ["draft"]);
+	const failing = chipEditor(async () => { throw new Error("clipboard busy"); });
+	failing.editor.handleInput(PASTE_KEY);
+	await settle();
+	assert.equal(failing.piPastes.length, 1);
+});
+
+test("a repeated paste key during a slow clipboard read inserts one chip", async () => {
+	let resolve!: (image: ClipboardImage) => void;
+	const { editor, piPastes } = chipEditor(() => new Promise((done) => { resolve = done; }));
+	editor.handleInput(PASTE_KEY);
+	editor.handleInput(PASTE_KEY);
+	resolve(png());
+	await settle();
+	assert.equal(editor.getText(), "[Image#1]");
+	assert.deepEqual(piPastes, []);
+});
+
+test("an editor without attachments keeps Pi's paste handler as a plain property", async () => {
+	const { editor, piPastes } = chipEditor(undefined);
+	editor.handleInput(PASTE_KEY);
+	await settle();
+	assert.equal(piPastes.length, 1);
+	assert.equal(editor.getText(), "");
+});
+
+test("the attachment strip lists chips still in the draft and falls back to text", () => {
+	setCapabilities({ images: null, trueColor: false, hyperlinks: false });
+	const attachments = new ImageAttachments();
+	attachments.add(png());
+	let draft = "see [Image#1]";
+	let vision = true;
+	const theme = { fg: (role: string, text: string) => `<${role}>${text}</${role}>` };
+	const strip = imageAttachmentsWidget(attachments, () => draft, theme, () => vision);
+	assert.deepEqual(strip.render(80), ["<accent>[Image#1]</accent> <dim>png · 2×1 · 29 B</dim>"]);
+	vision = false;
+	assert.match(strip.render(200)[0] ?? "", /<warning> · not sent: the current model does not accept images<\/warning>/);
+	draft = "chip deleted";
+	assert.deepEqual(strip.render(80), []);
+});
+
+test("terminals with an image protocol get a thumbnail under the chip label", () => {
+	setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
+	const attachments = new ImageAttachments();
+	attachments.add(png());
+	const strip = imageAttachmentsWidget(attachments, () => "[Image#1]", { fg: (_role, text) => text }, () => true, () => true);
+	const lines = strip.render(80);
+	assert.equal(stripAnsi(lines[0] ?? ""), "[Image#1] png · 2×1 · 29 B");
+	assert.ok(lines.length > 1, "a preview row follows the label");
+	assert.ok(lines.slice(1).some((line) => line.includes("\x1b_G")), "the preview uses the Kitty graphics protocol");
+});
+
+test("models without declared input capabilities are treated as image-capable", () => {
+	assert.equal(modelAcceptsImages(undefined), true);
+	assert.equal(modelAcceptsImages({}), true);
+	assert.equal(modelAcceptsImages({ input: ["text", "image"] }), true);
+	assert.equal(modelAcceptsImages({ input: ["text"] }), false);
+});

package/tests/inprocess-reviewer.test.ts

@@ -221,7 +221,7 @@ test("refuses when the reviewer attempts a tool call", async () => {
 	assert.equal(refused.code, INPROCESS_REVIEWER_FAILURE.TOOL_CALL_ATTEMPTED);
 });
 
-test("refuses empty assistant text with stopReason evidence", async () => {
+test("refuses empty assistant text with safe completion evidence", async () => {
 	const assistant = assistantText("", { content: [], stopReason: "stop" });
 	const outcome = await runInProcessReviewer(baseRequest(), {
 		registry: fakeRegistry([fakeModel()]),
@@ -229,7 +229,60 @@ test("refuses empty assistant text with stopReason evidence", async () => {
 	});
 	const refused = expectRefused(outcome);
 	assert.equal(refused.code, INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT);
-	assert.deepEqual(refused.evidence, { stopReason: "stop" });
+	assert.deepEqual(refused.evidence, {
+		reviewerModel: "openai/gpt-5", stopReason: "stop",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 },
+		content: { blocks: 0, textBlocks: 0, thinkingBlocks: 0, textChars: 0, thinkingChars: 0 },
+	});
+});
+
+test("empty-output diagnostics allowlist facts, not provider secrets, and complete once", async () => {
+	const model = fakeModel({ provider: "nan", id: "deepseek-v4-flash" });
+	const assistant = assistantText("", {
+		content: [{ type: "text", text: "" }, { type: "thinking", thinking: "PRIVATE THINKING", thinkingSignature: "PRIVATE SIGNATURE" }],
+		stopReason: "length", errorMessage: "PRIVATE ERROR", rawStopReason: "PRIVATE STOP",
+		usage: { input: 12, output: 64, reasoning: 64, cacheRead: 0, cacheWrite: 0, totalTokens: 76, unknown: "PRIVATE USAGE", cost: { secret: "PRIVATE COST" } } as never,
+	});
+	const { complete, calls } = capturingComplete(assistant);
+	const refused = expectRefused(await runInProcessReviewer(baseRequest(), {
+		registry: { ...fakeRegistry([model]), find: () => model }, complete,
+	}));
+	assert.equal(refused.code, INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT);
+	assert.equal(calls.length, 1);
+	assert.deepEqual(refused.evidence, {
+		reviewerModel: "nan/deepseek-v4-flash", stopReason: "length",
+		usage: { input: 12, output: 64, reasoning: 64, cacheRead: 0, cacheWrite: 0, totalTokens: 76 },
+		content: { blocks: 2, textBlocks: 1, thinkingBlocks: 1, textChars: 0, thinkingChars: 16 },
+	});
+	assert.doesNotMatch(JSON.stringify(refused), /PRIVATE|errorMessage|rawStopReason|Signature|unknown|cost/);
+});
+
+test("empty-output evidence omits unknown or invalid counters and bounds resolved model identity", async () => {
+	for (const invalid of [undefined, NaN, Infinity, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, "12"]) {
+		const assistant = assistantText("", {
+			content: [], stopReason: "PRIVATE STOP" as never,
+			usage: Object.fromEntries(["input", "output", "reasoning", "cacheRead", "cacheWrite", "totalTokens"].map((key) => [key, invalid])) as never,
+		});
+		const refused = expectRefused(await runInProcessReviewer(baseRequest(), {
+			registry: { ...fakeRegistry([]), find: () => fakeModel({ id: "x".repeat(2_000) }) },
+			complete: async () => assistant,
+		}));
+		assert.equal(refused.code, INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT);
+		assert.equal(String(refused.evidence?.reviewerModel).length, 512);
+		assert.ok(!Object.hasOwn(refused.evidence!, "usage"));
+		assert.ok(!Object.hasOwn(refused.evidence!, "stopReason"));
+		assert.doesNotMatch(JSON.stringify(refused), /PRIVATE STOP/);
+	}
+});
+
+test("empty-output evidence does not invent usage or missing thinking lengths", async () => {
+	const refused = expectRefused(await runInProcessReviewer(baseRequest(), {
+		registry: fakeRegistry([fakeModel()]),
+		complete: async () => assistantText("", { content: [{ type: "thinking" } as never], usage: undefined }),
+	}));
+	assert.equal(refused.code, INPROCESS_REVIEWER_FAILURE.EMPTY_OUTPUT);
+	assert.ok(!Object.hasOwn(refused.evidence!, "usage"));
+	assert.deepEqual(refused.evidence?.content, { blocks: 1, textBlocks: 0, thinkingBlocks: 1, textChars: 0 });
 });
 
 test("refuses with PROVIDER_FAILED when the provider itself reports an aborted completion", async () => {

package/tests/installer-bundles.test.ts

@@ -10,7 +10,13 @@ import { INSTALLER_ASSETS, buildInstallerBundles, bundleFiles, relativeReference
 import { installerPaths } from "../scripts/verify-package-files.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const posixOnly = { skip: process.platform === "win32" };
+// The builder shells out to the zip binary for the archives. Repository CI
+// installs zip, but a dev machine without it cannot run the archive tests:
+// skip with a clear reason instead of failing on spawnSync ENOENT.
+const zipAvailable = spawnSync("zip", ["--version"], { stdio: "ignore" }).status === 0;
+const bundleArchive = {
+	skip: process.platform === "win32" ? "Windows host" : zipAvailable ? false : "the zip binary is not on PATH",
+};
 // Independent of the builder's scanner on purpose: imports and file URLs next to the module.
 const relativeImports = (text: string) => [...text.matchAll(/(?:from\s+|import\s*\(\s*|new URL\(\s*)["'](\.{1,2}\/[^"']+\.[a-z]+)["']/g)].map((match) => match[1]);
 
@@ -45,7 +51,7 @@ function build() {
 }
 const listing = (command: string, args: string[]) => spawnSync(command, args, { encoding: "utf8" }).stdout;
 
-test("one download per system, with stable names and SHA-256 checksums", posixOnly, () => {
+test("one download per system, with stable names and SHA-256 checksums", bundleArchive, () => {
 	const b = build();
 	try {
 		assert.deepEqual(INSTALLER_ASSETS, ["gentle-shell-installer-macos.zip", "gentle-shell-installer-windows.zip", "gentle-shell-installer-linux.tar.gz"]);
@@ -58,7 +64,7 @@ test("one download per system, with stable names and SHA-256 checksums", posixOn
 	} finally { b.cleanup(); }
 });
 
-test("macOS and Linux double-click launchers are executable and start the bundled bootstrap", posixOnly, () => {
+test("macOS and Linux double-click launchers are executable and start the bundled bootstrap", bundleArchive, () => {
 	const b = build();
 	try {
 		const mac = listing("zipinfo", [join(b.out, "gentle-shell-installer-macos.zip")]);
@@ -74,7 +80,7 @@ test("macOS and Linux double-click launchers are executable and start the bundle
 	} finally { b.cleanup(); }
 });
 
-test("the Windows launcher is a CRLF batch file that calls the bundled bootstrap and keeps its window open", posixOnly, () => {
+test("the Windows launcher is a CRLF batch file that calls the bundled bootstrap and keeps its window open", bundleArchive, () => {
 	const b = build();
 	try {
 		const zip = join(b.out, "gentle-shell-installer-windows.zip");
@@ -88,7 +94,7 @@ test("the Windows launcher is a CRLF batch file that calls the bundled bootstrap
 	} finally { b.cleanup(); }
 });
 
-test("an extracted bundle runs on its own: real files only, and every wizard module loads", posixOnly, () => {
+test("an extracted bundle runs on its own: real files only, and every wizard module loads", bundleArchive, () => {
 	const b = build();
 	const target = realpathSync(mkdtempSync(join(tmpdir(), "installer-extract-")));
 	try {
@@ -111,7 +117,7 @@ test("an extracted bundle runs on its own: real files only, and every wizard mod
 	}
 });
 
-test("the builder command writes the downloads to the requested folder", posixOnly, () => {
+test("the builder command writes the downloads to the requested folder", bundleArchive, () => {
 	const out = realpathSync(mkdtempSync(join(tmpdir(), "installer-cli-")));
 	try {
 		mkdirSync(join(out, "dist"));

package/tests/installer-posix-bootstrap.test.ts

@@ -934,19 +934,19 @@ test("Go has no descriptor for other targets", () => {
 // The Engram release the bundled install ships (S9), from its checksums.txt and
 // the GitHub asset digests; every archive was downloaded and re-hashed.
 const engramPins = {
-	"darwin-arm64": ["darwin_arm64.tar.gz", "d0aa59c9a83d17ae3fc7f5dd31fdab6a26fd8c00fc5e692195753cd0719294f7", 7470202],
-	"darwin-x64": ["darwin_amd64.tar.gz", "3c5bdc73d226af5629cf4f4a781e223142e37c1ebb443c4b596f2e284352e381", 7961674],
-	"linux-x64": ["linux_amd64.tar.gz", "715fda625556e46d65ddb4526bb7f88a3fee5339ca3c44ce44cc652f17fa57f1", 7821191],
-	"linux-arm64": ["linux_arm64.tar.gz", "3309e9c0bbb539d183fd5aa9f9a13cd7aa0e81ec2512b5bedefb8b2bdd35b3e5", 7176726],
-	"win32-x64": ["windows_amd64.zip", "3065736ec7ff8137eb3fc607275f542ea13bb743a5157318c8a8770f11ce3289", 8021225],
-	"win32-arm64": ["windows_arm64.zip", "7463872a85a5e5434cf958bdffc71dda1926bced30d3b6b38c80fec9bb98fbba", 7231641],
+	"darwin-arm64": ["darwin_arm64.tar.gz", "43d398b2fe3327a4a6436c26b2a17d3285ba80bf2f11a22d0796ea2a7fd2b78c", 7749520],
+	"darwin-x64": ["darwin_amd64.tar.gz", "aea28ebf461a4ea86c52b793c29311539d7123875354ed7411eae982fc82ec87", 8181300],
+	"linux-x64": ["linux_amd64.tar.gz", "106a43ca8f43a27c2c260a6787151c3be6d91c5ed3d5e454e6140527adf92e01", 8064598],
+	"linux-arm64": ["linux_arm64.tar.gz", "b0ba49cf5a7d5af436c9744a9a0d638b3f9ebb2a7321c8736d30e96305c2993c", 7472279],
+	"win32-x64": ["windows_amd64.zip", "ba56a36d37b2da85fcb1581bbdbed9ae1ee690e642aab8dbe1e18209bf264afe", 8272809],
+	"win32-arm64": ["windows_arm64.zip", "df5acc5dd6ee407d484074e570c77a79567c0b8dccf55e25ae25a644c1e7db5f", 7530282],
 } as const;
 test("fixed Engram descriptors are the GitHub release archives and checksums, and nothing else", () => {
 	for (const [target, [suffix, sha256, size]] of Object.entries(engramPins)) {
 		const [platform, arch] = target.split("-");
 		const artifact = artifactFor("engram", platform, arch);
-		assert.equal(artifact.version, "3.4.0");
-		assert.equal(artifact.url, `https://github.com/Gentleman-Programming/engram/releases/download/v3.4.0/engram_3.4.0_${suffix}`);
+		assert.equal(artifact.version, "3.5.2");
+		assert.equal(artifact.url, `https://github.com/Gentleman-Programming/engram/releases/download/v3.5.2/engram_3.5.2_${suffix}`);
 		assert.equal(artifact.integrity, `sha256-${sha256}`);
 		assert.deepEqual([artifact.size, artifact.maxBytes], [size, size]);
 		// GitHub serves release assets from its asset hosts.

package/tests/installer-preflight.test.ts

@@ -172,6 +172,22 @@ test("Windows requires compatible Go only before a missing native binary", () =>
 	assert.deepEqual(older.actions.slice(0, 2), goActions);
 });
 
+test("Windows acquires the pinned Go for a Shell install even when Gentle AI is already installed", () => {
+	// gentle-pi's postinstall always builds Gentle AI from source on Windows, so an
+	// existing compatible gentle-ai never removes the need for Go.
+	const compatible = { ...tool(requirements.gentleAi), compatible: true };
+	for (const inventory of [{ ...clean("win32"), gentleAi: compatible },
+		{ ...installed("win32"), shell: absent, setup: false, go: absent }]) {
+		const plan = planPreflight(inventory);
+		assert.deepEqual(plan.blockers, []);
+		assert.deepEqual(plan.tools.go, { status: "needs-acquire", required: requirements.go, version: goAcquisition.version });
+		assert.ok(ids(inventory).includes("install-shell"));
+		assert.deepEqual(plan.actions.filter((action: { target: string }) => action.target === "go"), goActions);
+	}
+	// A set-up Windows stack builds nothing, so it still needs no Go.
+	assert.equal(planPreflight({ ...installed("win32"), go: absent }).tools.go.status, "not-required");
+});
+
 for (const [name, version] of [["node", "22.18.0"], ["shell", "3.9.0"], ["node", "banana"], ["pi", "1.0.0-rc.1"]]) {
 	test(`${name} ${version} blocks rather than replacing an existing tool`, () => {
 		const inventory = { ...installed(), [name]: tool(version) };

package/tests/installer-server.test.ts

@@ -306,8 +306,8 @@ test("/api/plan names the found and required version of an older Gentle Shell an
 		const view = await plan(port, await login());
 		assert.deepEqual(view.blockers.map((blocker: { code: string; tool: string }) => [blocker.code, blocker.tool]), [["incompatible-tool", "shell"]]);
 		assert.equal(view.blockers[0].guidance,
-			"Gentle Shell 3.4.0 is installed globally with pnpm, but this installer needs 4.3.0 or newer. Nothing was replaced. " +
-			"Update it with `pnpm add -g gentle-pi@4.3.0`, or remove it with `pnpm remove -g gentle-pi`, then select Check again.");
+			"Gentle Shell 3.4.0 is installed globally with pnpm, but this installer needs 4.4.0 or newer. Nothing was replaced. " +
+			"Update it with `pnpm add -g gentle-pi@4.4.0`, or remove it with `pnpm remove -g gentle-pi`, then select Check again.");
 		assert.deepEqual(view.actions, []);
 	} finally {
 		await host.close("test");

package/tests/installer-windows-bootstrap.test.ts

@@ -1054,6 +1054,55 @@ test("the one-launch walk applies the single-path walk, per path, with its own f
 	assert.doesNotMatch(many, /Invoke-Expression|\biex\b|ScriptBlock\]::Create|EncodedCommand/);
 });
 
+test("storage metadata public adapters preserve verdicts and unexpected failures", () => {
+	const path = "D:\\metadata fixture\\tool.exe";
+	const env = { SystemRoot: "C:\\Windows" };
+	let calls = 0;
+	const single = (output: string) => verifyWindowsStorage(path, env, (_command: string, _args: string[], data: Record<string, string>) => {
+		calls++; assert.equal(data.GENTLE_WINDOWS_CHECK, path); return output;
+	});
+	if (process.platform === "win32") {
+		assert.equal(single("safe"), undefined);
+		for (const check of ["target-reparse", "parent-owner", "ancestor-acl-mask"]) {
+			assert.throws(() => single(`unsafe:${check}|${encoded(`${path}|||`)}`), (error: Error & { check?: string; detail?: { at: string } }) => error.check === check && error.detail?.at === path);
+		}
+		assert.throws(() => single("malformed"), /Windows ACL evidence rejected/);
+		assert.equal(calls, 5);
+		const failure = Object.assign(new Error("metadata read failed"), { code: "EACCES" });
+		assert.throws(() => verifyWindowsStorage(path, env, () => { throw failure; }), (error: unknown) => error === failure);
+	} else {
+		assert.throws(() => single("safe"), /Native Windows storage verification unavailable/);
+		assert.equal(calls, 0, "unsupported platforms reject before invoking the runner");
+	}
+	const paths = [path, "D:\\metadata fixture\\next.cmd"];
+	assert.deepEqual(windowsModule.verifyWindowsStorageMany(paths, env, { platform: "win32", processAdapter: (_command: string, _args: string[], data: Record<string, string>) => {
+		assert.equal(data.GENTLE_WINDOWS_CHECKS, paths.join("|")); return "unknown\nsafe";
+	} }), [{ check: "unchecked", at: path }, null]);
+});
+
+// Inspect scripts through the public process seam; never execute PowerShell.
+for (const mode of ["single", "batch"] as const) {
+	test(`storage metadata ${mode} uses throwing static attributes before ACL reads`, { skip: mode === "single" && process.platform !== "win32" ? "single-path script requires the real Windows platform" : false }, () => {
+		let script = "";
+		const processAdapter = (_command: string, args: string[], env: Record<string, string>) => {
+			script = args[4];
+			assert.equal(env[mode === "single" ? "GENTLE_WINDOWS_CHECK" : "GENTLE_WINDOWS_CHECKS"], "C:\\metadata\\node.exe");
+			return "safe";
+		};
+		if (mode === "single") verifyWindowsStorage("C:\\metadata\\node.exe", { SystemRoot: "C:\\Windows" }, processAdapter);
+		else windowsModule.verifyWindowsStorageMany(["C:\\metadata\\node.exe"], { SystemRoot: "C:\\Windows" }, { platform: "win32", processAdapter });
+		assert.ok(script.includes("$attributes = [IO.File]::GetAttributes($path);"));
+		const reparse = "if ($attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };";
+		const branch = "if ($attributes -band [IO.FileAttributes]::Directory) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };";
+		assert.ok(script.includes(reparse));
+		assert.ok(script.includes(branch));
+		assert.ok(script.indexOf("GetAttributes($path)") < script.indexOf(reparse));
+		assert.ok(script.indexOf(reparse) < script.indexOf(branch));
+		assert.doesNotMatch(script, /Get-Item|\[IO\.(?:File|Directory)\]::Exists|FileInfo|DirectoryInfo|Refresh/);
+		assert.ok(script.includes(mode === "single" ? "} else { throw } }" : "} else { 'unknown' } }"));
+	});
+}
+
 // S6 decision fixtures: an in-memory folder tree and an injected walk verdict per
 // path, the same way the helper tests inject storage. `weak` maps a walked path
 // to the check its walk fails; every other walk passes.
@@ -1197,8 +1246,9 @@ test("production and fixture PowerShell never depend on autoloading Microsoft.Po
 		assert.match(source, /\[IO\.Directory\]::SetAccessControl\(/);
 	}
 	// Walks that may reach a file read it as a file, never through a directory API.
-	for (const source of [productionAclSources()[1], productionAclSources()[2]]) {
-		assert.match(source, /if \(\$item\.PSIsContainer\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
+	assert.match(productionAclSources()[1], /if \(\$item\.PSIsContainer\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
+	for (const source of [productionAclSources()[2], manyCheck()]) {
+		assert.match(source, /if \(\$attributes -band \[IO\.FileAttributes\]::Directory\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
 	}
 });
 const psRecordLine = '  "$record = [Diagnostics.Process]::GetCurrentProcess(); [IO.File]::AppendAllText($env:GENTLE_FIXTURE_RECORDS,([string]$record.Id + [char]124 + [string]$record.StartTime.ToUniversalTime().Ticks + [Environment]::NewLine));" ^';
@@ -1317,9 +1367,17 @@ if (Test-Path -LiteralPath $env:GENTLE_FIXTURE_RECORDS) {
 if ($reaped) { [Console]::WriteLine('fixture guard reaped residual owned process') };
 exit 0;
 `;
+const GUARD_TIMEOUT_MS = 5000;
 function cleanNativeProcesses(root: string) {
 	const ps = join(process.env.SystemRoot!, "System32/WindowsPowerShell/v1.0/powershell.exe");
-	const result = spawnSync(ps, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", guardCommand], { env: nativeEnv(root), timeout: 5000, killSignal: "SIGKILL", encoding: "utf8", maxBuffer: 65536 });
+	const spawnGuard = (timeoutMs: number) => spawnSync(ps, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", guardCommand], { env: nativeEnv(root), timeout: timeoutMs, killSignal: "SIGKILL", encoding: "utf8", maxBuffer: 65536 });
+	// A hosted Windows runner can cold-start PowerShell slower than any fixed
+	// bound under load (run 40000806368: ETIMEDOUT at 5s, same commit green on
+	// rerun). The guard's job is cleanup, not a load measurement, and the guard
+	// is idempotent — it kills only verified owned processes and exits 0 — so a
+	// timeout is retried once with a wider bound before failing the fixture.
+	let result = spawnGuard(GUARD_TIMEOUT_MS);
+	if ((result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT") result = spawnGuard(GUARD_TIMEOUT_MS * 4);
 	assert.equal(result.error, undefined, "fixture guard must be bounded and available");
 	assert.equal(result.status, 0, `fixture guard must only clean verified owned processes: ${(result.stderr ?? "").slice(0, 4000)}`);
 	assert.ok(["", "fixture guard reaped residual owned process"].includes(result.stdout.trim()), "unexpected fixture guard output");

package/tests/installer-windows-diagnostics.test.ts

@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
+import { getSystemErrorName } from 'node:util';
+import { windowsProcessCheck, windowsBootstrapReason } from '../scripts/installer-windows.mjs';
+
+// Only owned inert Node children. Never invoke PowerShell, ACL/storage or setup.
+const base = resolve('odd/checks/issue-1921-windows-prerequisite-diagnostics');
+mkdirSync(base, { recursive: true });
+const root = mkdtempSync(join(base, 'inert-'));
+const fixture = join(root, 'child.mjs');
+writeFileSync(fixture, `import { writeSync } from 'node:fs';
+const mode = process.argv[2];
+if (mode === 'cap') { writeSync(2, 'overflow fixture\\n'); writeSync(1, 'x'.repeat(2*1024*1024)); }
+else if (mode === 'success') { writeSync(1, '  ' + JSON.stringify({cwd:process.cwd()}) + ' \\n'); }
+else { writeSync(1, process.argv[3]); writeSync(2, process.argv[4] ?? ''); process.exit(7); }
+`);
+const env = { SystemRoot: process.env.SystemRoot ?? process.env.SYSTEMROOT ?? 'C:\\Windows',
+  PATH: dirname(process.execPath), DIAGNOSTIC_SECRET: 'must-not-retain-env' };
+function failure(command: string, args: string[]): any {
+  let caught: any;
+  try { windowsProcessCheck(command, args, env); } catch (error) { caught = error; }
+  assert.equal(caught?.message, 'Windows prerequisite process failed');
+  assert.equal(windowsBootstrapReason(caught, 'tools-storage'), 'process-failed (tools-storage)');
+  return caught;
+}
+function causeOf(error: any): any {
+  assert.ok(error.cause instanceof Error, 'standard cause Error must survive existing cause.stack observer');
+  const cause = error.cause;
+  assert.deepEqual(Object.keys(cause).sort(), ['error', 'signal', 'status', 'stderr', 'stdout']);
+  assert.ok(cause.stack.length <= 8192);
+  assert.ok(cause.stdout.length <= 1024 && cause.stderr.length <= 1024);
+  assert.ok(!cause.stack.includes(root) && !cause.stack.includes('installer-windows.mjs'));
+  assert.ok(!cause.error?.message?.includes(root));
+  assert.ok(!JSON.stringify(cause).includes(env.DIAGNOSTIC_SECRET));
+  return cause;
+}
+
+test('metadata: nonzero exit keeps bounded streams and usable cause.stack', () => {
+  const args = [fixture, 'text', 'controlled stdout\n', 'controlled stderr\n', 'private-argv-sentinel'];
+  const before = structuredClone({ args, env });
+  const error = failure(process.execPath, args), cause = causeOf(error);
+  assert.equal(cause.status, 7); assert.equal(cause.signal, null); assert.equal(cause.error, null);
+  assert.equal(cause.stdout, 'controlled stdout\n'); assert.equal(cause.stderr, 'controlled stderr\n');
+  assert.match(error.cause?.stack, /"status":7/);
+  assert.match(error.cause?.stack, /controlled stderr/);
+  assert.ok(!JSON.stringify(cause).includes('private-argv-sentinel'));
+  assert.deepEqual({ args, env }, before);
+});
+
+test('metadata: missing synthetic executable preserves ENOENT without raw spawn error', () => {
+  const cause = causeOf(failure(join(root, 'missing.exe'), ['private-argv-sentinel']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, null);
+  assert.deepEqual(Object.keys(cause.error).sort(), ['code', 'errno', 'message', 'name']);
+  assert.equal(cause.error.code, 'ENOENT'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOENT');
+  assert.ok(cause.error.message.length <= 256);
+  assert.equal(cause.stdout, ''); assert.equal(cause.stderr, '');
+  assert.match(cause.stack, /ENOENT/);
+});
+
+test('metadata: output overflow preserves ENOBUFS and actual kill signal without waiting15s', () => {
+  const cause = causeOf(failure(process.execPath, [fixture, 'cap']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, 'SIGKILL');
+  assert.equal(cause.error.code, 'ENOBUFS'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOBUFS');
+  assert.equal(cause.stderr, 'overflow fixture\n');
+  assert.match(cause.stack, /ENOBUFS/);
+});
+
+test('privacy: private paths, SID/encoded ACL detail and sensitive output are suppressed; caps hold', () => {
+  const privateLines = ['visible', 'C:\\Users\\Synthetic Person\\private.txt', '/home/synthetic/private.txt',
+    'S-1-5-21-111-222-333-1001', 'DOMAIN\\synthetic', 'unsafe:target-owner|YWJjZA=='];
+  const cause = causeOf(failure(process.execPath, [fixture, 'text', privateLines.join('\n'),
+    'Authorization: Bearer synthetic-secret\ncontinuation-must-not-survive']));
+  assert.match(cause.stdout, /visible/);
+  for (const value of privateLines.slice(1)) assert.ok(!cause.stdout.includes(value));
+  assert.ok(!cause.stack.includes('synthetic-secret') && !cause.stack.includes('continuation-must-not-survive'));
+  const bounded = causeOf(failure(process.execPath, [fixture, 'text', 'safe line\n'.repeat(300), 'safe error\n'.repeat(300)]));
+  assert.equal(bounded.stdout.length, 1024); assert.equal(bounded.stderr.length, 1024);
+});
+
+test('PR privacy: credential markers recognize underscore separators without changing API_KEY handling', () => {
+  for (const marker of ['GITHUB_TOKEN', 'PREFIX_API_KEY_SUFFIX', 'AWS_ACCESS_KEY_ID', 'API_KEY', 'access_key']) {
+    const payload = `${marker}=synthetic-value-1921\ncontinuation-value-1921`;
+    assert.equal(payload.includes('\\'), false, 'actual argv bytes must not trigger the path filter');
+    const cause = causeOf(failure(process.execPath,
+      ['-e', 'process.stderr.write(process.argv[1]);process.exit(7)', payload]));
+    assert.equal(cause.status, 7);
+    assert.equal(cause.stderr, '[redacted]');
+    assert.ok(!cause.stack.includes('synthetic-value-1921') && !cause.stack.includes('continuation-value-1921'));
+  }
+});
+
+test('PR privacy: missing bare executable identity never enters cause message or stack', () => {
+  const command = `fixture-private-executable-1921-${basename(root)}`;
+  assert.equal(parse(command).root, '', 'a path-based probe would miss the bare-name leak');
+  const cause = causeOf(failure(command, ['private-argv-sentinel']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, null);
+  assert.equal(cause.error.code, 'ENOENT'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOENT');
+  assert.ok(!JSON.stringify(cause).includes(command) && !cause.stack.includes(command));
+  assert.match(cause.error.message, /ENOENT/);
+});
+
+test('legacy: neutral cwd, trimmed success and pre-spawn CMD/BAT rejection stay exact', () => {
+  assert.equal(windowsProcessCheck(process.execPath, [fixture, 'success'], env), JSON.stringify({ cwd: parse(process.execPath).root }));
+  for (const suffix of ['.CMD', '.bat']) assert.throws(() => windowsProcessCheck(join(root, `absent${suffix}`), [], env),
+    error => error instanceof Error && error.message === 'Unproven command interpreter target' && error.cause === undefined);
+});