gentle-pi 4.3.0 → 4.4.0

package/tests/main-channel-upgrade.test.ts

@@ -4,7 +4,7 @@ import * as fsPromises from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { CHANNEL_SCHEMA, MainChannelError, ownerManager, readChannel, removeGlobalShell, runUpgrade, writeChannel } from "../scripts/main-channel.mjs";
+import { CHANNEL_SCHEMA, GENTLE_AI_MODULE, MainChannelError, ownerManager, readChannel, removeGlobalShell, runUpgrade, writeChannel } from "../scripts/main-channel.mjs";
 import { requirements } from "../scripts/installer-preflight.mjs";
 
 const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
@@ -19,7 +19,8 @@ type Invocation = { command: string; prefix: string[] } | null;
  * `which` finds `<bin>/<name><suffix>`; `invocation`, when given, is the host's adapter. */
 function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell: SHELL_SHA }, tools = ["go", "pnpm", "npm"], platform = "darwin",
 	bin = "/usr/bin", suffix = "", invocation = undefined as ((name: string) => Promise<Invocation>) | undefined, fs = fsPromises as typeof fsPromises,
-	migrate = undefined as ((input: { latest: string; owner: () => Promise<unknown> }) => Promise<unknown>) | undefined } = {}) {
+	migrate = undefined as ((input: { latest: string; owner: () => Promise<unknown> }) => Promise<unknown>) | undefined,
+	failGoInstall = false, failShellInstall = false } = {}) {
 	// owner "linked": `npm link` of a source checkout, so npm's global entry points outside npm's root.
 	const root = realpathSync(mkdtempSync(join(tmpdir(), "upgrade-")));
 	const home = join(root, "home");
@@ -50,13 +51,22 @@ function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell
 		}
 		calls.push({ command, argv });
 		if (argv[0] === "install" && argv[1]?.includes("gentle-ai/v4/cmd/gentle-ai@")) {
+			if (failGoInstall) return { code: 1, stdout: "" };
 			mkdirSync(options.env!.GOBIN, { recursive: true });
 			for (const name of ["gentle-ai", "gentle-ai.exe"]) writeFileSync(join(options.env!.GOBIN, name), "#!/bin/sh\n", { mode: 0o755 });
 			return { code: 0, stdout: "" };
 		}
 		if (argv[0] === "version" && command === `${bin}/go`) {
+			if (argv[1] === "-m") {
+				const commit = String(argv[2] ?? "").split("/").at(-2) ?? "";
+				return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\tv4.0.1-0.20261008202137-${commit.slice(0, 12)}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+			}
 			return { code: 0, stdout: `go version go${requirements.go} ${platform}/amd64\n` };
 		}
+		if (argv[0] === "list" && command === `${bin}/go`) {
+			const commit = String(argv[3] ?? "").slice(`${GENTLE_AI_MODULE}@`.length);
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: `v4.0.1-0.20261008202137-${commit.slice(0, 12)}`, Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: commit } }) };
+		}
 		if (argv[0] === "version") {
 			const sha = command.split("/").at(-2) ?? "";
 			return { code: 0, stdout: `gentle-ai 4.0.1-0.20261008202137-${sha.slice(0, 12)}\n` };
@@ -65,6 +75,7 @@ function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell
 			writeFileSync(join(argv[argv.indexOf("-C") + 1], "package.json"), JSON.stringify({ name: "gentle-pi", version: "4.1.0", scripts: { prepack: "x" } }));
 			return { code: 0, stdout: "" };
 		}
+		if (failShellInstall && argv.includes("-g") && argv.some((arg) => arg.endsWith(".tgz"))) return { code: 1, stdout: "" };
 		if (argv.includes("pack")) {
 			const version = JSON.parse(readFileSync(join(options.cwd!, "package.json"), "utf8")).version;
 			writeFileSync(join(argv[argv.indexOf("--pack-destination") + 1], `gentle-pi-${version}.tgz`), "tgz");
@@ -186,6 +197,225 @@ test("a main install rebuilds only what moved on main and records the new commit
 	} finally { w.cleanup(); }
 });
 
+// #2356: a Gentle AI step that fails still installs a main Shell that moved, so the
+// retry runs the new Shell's code; the channel is recorded only when both succeed.
+const GO_INSTALL_FAILED = `main-gentle-ai-build-failed: go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@${NEW_AI} failed`;
+const PRIOR_REGISTRATION = JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: "/prior/main/gentle-ai" });
+const NEW_SHELL_TGZ = (home: string) => join(home, ".pi", "gentle-ai", "main", "packages", "gentle-pi-4.1.0-main.333333333333.tgz");
+async function onPriorMain(w: ReturnType<typeof world>) {
+	await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+	writeFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), PRIOR_REGISTRATION);
+	return () => ({ channel: readFileSync(join(w.home, ".pi", "gentle-ai", "channel.json"), "utf8"), registration: readFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8") });
+}
+
+test("a failed Gentle AI build still installs the main Shell that moved, records no channel and names the retry", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, failGoInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-gentle-ai-build-failed");
+			assert.equal(error.message, `${GO_INSTALL_FAILED}; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish`);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+		assert.deepEqual(JSON.parse(before.registration), JSON.parse(PRIOR_REGISTRATION));
+	} finally { w.cleanup(); }
+});
+
+test("a Go that cannot be obtained for the Gentle AI build still installs the main Shell that moved", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, tools: ["pnpm", "npm"] });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-requires-tools");
+			assert.match(error.message, /^main-requires-tools: the main channel builds Gentle AI with Go .*Unexpected Go acquisition in sandboxed upgrade fixture.*; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish$/);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("after a fail-forward, the retry from the new Shell builds Gentle AI and records both commits", posixOnly, async () => {
+	// The first copy of the built binary fails (as a rejected build would); the retry's succeeds.
+	let copies = 0;
+	const fs = { ...fsPromises, copyFile: async (...args: Parameters<typeof fsPromises.copyFile>) => {
+		if (copies++ === 0) throw new MainChannelError("main-gentle-ai-unverified", "first attempt rejected");
+		return fsPromises.copyFile(...args);
+	} } as typeof fsPromises;
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.deepEqual(files(), before);
+		// The retry is simulated as the new Shell's run: the same runUpgrade with the new
+		// version (the installed package itself is not executed). No channel was recorded,
+		// so it rebuilds Gentle AI and repacks the Shell before recording both commits.
+		w.lines.length = 0;
+		assert.equal(await w.upgrade([], "4.1.0-main.333333333333"), 0);
+		assert.deepEqual(w.lines, ["Updated to the latest main: Gentle Shell 333333333333, Gentle AI 222222222222."]);
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`, `/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "main", shellCommit: NEW_SHELL, gentleAiCommit: NEW_AI });
+		assert.equal(JSON.parse(readFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8")).path,
+			join(w.home, ".pi", "gentle-ai", "main", "gentle-ai", NEW_AI, "gentle-ai"));
+		// A third run is a no-op: both commits are current.
+		w.lines.length = 0;
+		assert.equal(await w.upgrade([], "4.1.0-main.333333333333"), 0);
+		assert.deepEqual(w.lines, ["gentle-shell is already at the latest main: Gentle Shell 333333333333, Gentle AI 222222222222."]);
+	} finally { w.cleanup(); }
+});
+
+test("a failed Gentle AI build with the main Shell already current fails as before: nothing installed or recorded", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: SHELL_SHA }, failGoInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-gentle-ai-build-failed");
+			assert.equal(error.message, GO_INSTALL_FAILED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("when the Gentle AI build and the Shell install both fail, the Shell failure is reported with the Gentle AI one", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, failGoInstall: true, failShellInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "upgrade-install-failed");
+			assert.equal(error.message, `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (${GO_INSTALL_FAILED})`);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+// An ordinary failure that is not a MainChannelError (EACCES) keeps the retry advice and both errors.
+const eacces = (what: string) => Object.assign(new Error(`EACCES: permission denied, ${what}`), { code: "EACCES" });
+const COPY_DENIED = eacces("copyfile");
+const MANIFEST_DENIED = eacces("open package.json");
+const deniedFs = ({ copy = false, manifest = false }) => ({ ...fsPromises,
+	copyFile: async (...args: Parameters<typeof fsPromises.copyFile>) => { if (copy) throw COPY_DENIED; return fsPromises.copyFile(...args); },
+	readFile: (async (path: string, options?: unknown) => {
+		if (manifest && String(path).endsWith(join(".source", "src", "package.json"))) throw MANIFEST_DENIED;
+		return fsPromises.readFile(path, options as never);
+	}) as typeof fsPromises.readFile }) as typeof fsPromises;
+
+test("an ordinary error in the Gentle AI step still installs the main Shell that moved and names the retry", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: deniedFs({ copy: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.ok(error instanceof MainChannelError);
+			assert.equal(error.code, "main-upgrade-incomplete");
+			assert.equal(error.message, "main-upgrade-incomplete: EACCES: permission denied, copyfile; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish");
+			assert.equal(error.cause, COPY_DENIED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("ordinary errors in both steps report the Shell error with the Gentle AI one", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: deniedFs({ copy: true, manifest: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.ok(error instanceof MainChannelError);
+			assert.equal(error.code, "main-upgrade-incomplete");
+			assert.equal(error.message, "main-upgrade-incomplete: EACCES: permission denied, open package.json; Gentle AI was not updated either (EACCES: permission denied, copyfile)");
+			assert.equal(error.cause, MANIFEST_DENIED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("an ordinary error in the Gentle AI step with the main Shell already current is rethrown unchanged", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: SHELL_SHA }, fs: deniedFs({ copy: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: Error) => error === COPY_DENIED);
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+// A rejection that is not an Error, even a falsy one, is still a failed Gentle AI step.
+const rejectingCopy = (value: unknown) => ({ ...fsPromises, copyFile: async () => { throw value; } }) as typeof fsPromises;
+
+test("a falsy rejection in the Gentle AI step still records no channel and names the retry", posixOnly, async () => {
+	for (const value of [undefined, null, 0, false]) {
+		const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy(value) });
+		try {
+			const files = await onPriorMain(w);
+			const before = files();
+			await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+				assert.ok(error instanceof MainChannelError);
+				assert.equal(error.code, "main-upgrade-incomplete");
+				assert.equal(error.message, `main-upgrade-incomplete: ${String(value)}; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish`);
+				return true;
+			});
+			assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+			assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+			assert.deepEqual(files(), before);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("a rejection that is not an Error but has a message keeps that message", posixOnly, async () => {
+	for (const failShellInstall of [false, true]) {
+		const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy({ message: "EACCES: copy denied", code: "EACCES" }), failShellInstall });
+		try {
+			const files = await onPriorMain(w);
+			const before = files();
+			await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+				assert.equal(error.message, failShellInstall
+					? `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (EACCES: copy denied)`
+					: "main-upgrade-incomplete: EACCES: copy denied; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish");
+				return true;
+			});
+			assert.deepEqual(files(), before);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("a null rejection in the Gentle AI step is kept when the Shell install fails too", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy(null), failShellInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "upgrade-install-failed");
+			assert.equal(error.message, `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (null)`);
+			return true;
+		});
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
 test("a main install whose Gentle AI did not move rebuilds only Gentle Shell", posixOnly, async () => {
 	const w = world({ commits: { ai: AI_SHA, shell: NEW_SHELL } });
 	try {

package/tests/main-channel.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, win32 } from "node:path";
@@ -7,6 +7,7 @@ import test from "node:test";
 import {
 	CHANNEL_SCHEMA,
 	GENTLE_AI_MAIN_PACKAGE,
+	GENTLE_AI_MODULE,
 	MainChannelError,
 	buildMainGentleAi,
 	channelStatePath,
@@ -23,6 +24,8 @@ import { artifactFor } from "../scripts/installer-downloads.mjs";
 
 const SHELL_SHA = "6e7e3a18f794223396527a54c7c36d19c7d236c6";
 const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
+const PSEUDO = "v4.0.1-0.20261008202137-1f9d5e6423e3";
+const LIST_FAILURE = "go: github.com/gentleman-programming/gentle-ai/v4@v4.0.1-0.20261008202137-1f9d5e6423e3: module lookup failed";
 const posixOnly = { skip: process.platform === "win32" };
 
 function sandbox() {
@@ -33,6 +36,38 @@ function sandbox() {
 }
 type Call = { command: string; argv: string[]; options: { env?: Record<string, string>; cwd?: string } };
 
+// Emulates the Go and binary invocations buildMainGentleAi makes, each driven by
+// what `go list -m -json` resolves, what the binary embeds, and what it prints.
+function gentleAiBuildRun(world: {
+	commit: string;
+	listVersion?: string;
+	originHash?: string;
+	embeddedVersion?: string;
+	probeVersion?: string;
+	listFails?: boolean;
+}) {
+	const { commit, listVersion = "v4.2.0", originHash = commit, embeddedVersion = listVersion, probeVersion = listVersion.replace(/^v/, ""), listFails = false } = world;
+	const calls: Call[] = [];
+	const run = async (command: string, argv: string[], options: Call["options"]) => {
+		calls.push({ command, argv, options });
+		if (argv[0] === "install") {
+			mkdirSync(options.env!.GOBIN, { recursive: true });
+			writeFileSync(join(options.env!.GOBIN, "gentle-ai"), "#!/bin/sh\n", { mode: 0o755 });
+			return { code: 0, stdout: "" };
+		}
+		if (argv[0] === "list") {
+			if (listFails) return { code: 1, stdout: "", stderrTail: `${LIST_FAILURE}\n` };
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: listVersion,
+				Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: originHash, Ref: "refs/tags/v4.2.0" } }) };
+		}
+		if (argv[0] === "version" && argv[1] === "-m") {
+			return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\t${embeddedVersion}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+		}
+		return { code: 0, stdout: `gentle-ai ${probeVersion}\n` };
+	};
+	return { calls, run };
+}
+
 test("channel state defaults to release and round-trips a main record", async () => {
 	const s = sandbox();
 	try {
@@ -169,18 +204,7 @@ test("Gentle AI main is built from the exact commit through Go's checksum databa
 	const s = sandbox();
 	try {
 		const goPath = join(s.root, "go", "bin", "go");
-		const calls: Call[] = [];
-		const run = async (command: string, argv: string[], options: Call["options"]) => {
-			calls.push({ command, argv, options });
-			if (argv[0] === "install") {
-				mkdirSync(options.env!.GOBIN, { recursive: true });
-				const binary = join(options.env!.GOBIN, "gentle-ai");
-				writeFileSync(binary, "#!/bin/sh\n");
-				chmodSync(binary, 0o755);
-				return { code: 0, stdout: "" };
-			}
-			return { code: 0, stdout: "gentle-ai 4.0.1-0.20261008202137-1f9d5e6423e3\n" };
-		};
+		const { calls, run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO });
 		const built = await buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath, run, fs: fsPromises });
 		const install = calls[0];
 		assert.equal(install.command, goPath);
@@ -194,19 +218,107 @@ test("Gentle AI main is built from the exact commit through Go's checksum databa
 	} finally { s.cleanup(); }
 });
 
-test("a Gentle AI build whose version names another commit is rejected and never registered", posixOnly, async () => {
+// #2301: when main's HEAD is exactly a tag commit, Go stamps the tag (v4.2.0), not a
+// pseudo-version, so the suffix check alone rejects every tagged release.
+test("a main commit that is exactly a release tag is accepted when Go resolves that tag to the commit", posixOnly, async () => {
 	const s = sandbox();
 	try {
-		const run = async (_command: string, argv: string[], options: Call["options"]) => {
-			if (argv[0] === "install") {
-				mkdirSync(options.env!.GOBIN, { recursive: true });
-				writeFileSync(join(options.env!.GOBIN, "gentle-ai"), "#!/bin/sh\n", { mode: 0o755 });
-			}
-			return { code: 0, stdout: "gentle-ai 4.0.1-0.20261008202137-aaaaaaaaaaaa\n" };
-		};
+		const TAGGED = "4acaf4241beae1e0c977c92dfe406a270f8d40de";
+		const { run } = gentleAiBuildRun({ commit: TAGGED, listVersion: "v4.2.0", originHash: TAGGED });
+		const built = await buildMainGentleAi({ commit: TAGGED, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises });
+		assert.equal(built.binaryPath, join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", TAGGED, "gentle-ai"));
+		assert.equal(built.version, "4.2.0");
+		assert.deepEqual(JSON.parse(readFileSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8")),
+			{ schema: "gentle-pi.dev-binary/v1", path: built.binaryPath });
+	} finally { s.cleanup(); }
+});
+
+test("a go list whose Origin.Hash names another commit is rejected, and the build is removed", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const OTHER = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, originHash: OTHER });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified" && error.message.includes(OTHER) && error.message.includes(AI_SHA.slice(0, 12)));
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", ".build")), false);
+	} finally { s.cleanup(); }
+});
+
+test("a binary whose embedded module version differs from what Go resolved is rejected and never registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, embeddedVersion: "v4.1.2" });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+	} finally { s.cleanup(); }
+});
+
+test("a failed go list is rejected as unverified, with its stderr tail as the cause, and nothing is registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, listFails: true });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified" && error.cause instanceof Error && error.cause.message === LIST_FAILURE);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
+	} finally { s.cleanup(); }
+});
+
+// Rebuilding a commit that is already registered (a rerun wizard step, a lost
+// channel record) must not delete the working override when verification fails.
+for (const [name, failure] of Object.entries({
+	"go list fails": { listFails: true },
+	"the embedded version differs": { embeddedVersion: "v4.1.2" },
+	"the reported version differs": { probeVersion: "4.0.1-0.20261008202137-aaaaaaaaaaaa" },
+})) test(`a registered build of the same commit survives a rebuild whose verification fails because ${name}`, posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const directory = join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA);
+		const binary = join(directory, "gentle-ai");
+		const registration = join(s.home, ".pi", "gentle-ai", "dev-binary.json");
+		mkdirSync(directory, { recursive: true });
+		writeFileSync(binary, "#!/bin/sh\n# registered\n", { mode: 0o755 });
+		const record = JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: binary });
+		writeFileSync(registration, record);
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, ...failure });
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.equal(readFileSync(binary, "utf8"), "#!/bin/sh\n# registered\n");
+		assert.equal(readFileSync(registration, "utf8"), record);
+		assert.deepEqual(readdirSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai")), [AI_SHA]);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", ".build")), false);
+	} finally { s.cleanup(); }
+});
+
+test("go list and go version -m run with the same sealed environment and cwd as go install", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const goPath = join(s.root, "go", "bin", "go");
+		const { calls, run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO });
+		await buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath, run, fs: fsPromises });
+		const sealed = { GOPROXY: "https://proxy.golang.org", GOSUMDB: "sum.golang.org", GOTOOLCHAIN: "local",
+			GOFLAGS: "-modcacherw", GONOSUMDB: "", GOPRIVATE: "", GOINSECURE: "", GOENV: "off", GOWORK: "off" };
+		const goCalls = calls.filter((call) => call.command === goPath);
+		assert.deepEqual(goCalls.map((call) => call.argv[0]), ["install", "list", "version"]);
+		for (const call of goCalls) {
+			assert.equal(call.options.cwd, join(s.home, ".pi", "gentle-ai", "main", ".build"), call.argv.join(" "));
+			for (const [key, value] of Object.entries(sealed)) assert.equal(call.options.env![key], value, `${key} for ${call.argv.join(" ")}`);
+		}
+	} finally { s.cleanup(); }
+});
+
+test("a Gentle AI build whose reported version differs from the resolved module version is rejected and never registered", posixOnly, async () => {
+	const s = sandbox();
+	try {
+		const { run } = gentleAiBuildRun({ commit: AI_SHA, listVersion: PSEUDO, probeVersion: "4.0.1-0.20261008202137-aaaaaaaaaaaa" });
 		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath: "/go/bin/go", run, fs: fsPromises }),
 			(error: MainChannelError) => error.code === "main-gentle-ai-unverified");
 		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "dev-binary.json")), false);
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA)), false);
 	} finally { s.cleanup(); }
 });
 
@@ -278,6 +390,13 @@ async function upgradeWorld({ userGo = null as string | null, pinned = false, ac
 	const fetch = async (url: string) => ({ ok: true, status: 200, text: async () => (url.endsWith("/gentle-ai/commits/main") ? NEW_AI : SHELL_SHA) });
 	const run = async (command: string, argv: string[], options: Call["options"]) => {
 		calls.push({ command, argv, options });
+		const isGo = command === "/usr/bin/go" || command === pinnedGo;
+		const pseudo = (commit: string) => `v4.0.1-0.20261008202137-${commit.slice(0, 12)}`;
+		if (isGo && argv[0] === "version" && argv[1] === "-m") return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\t${pseudo(NEW_AI)}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+		if (isGo && argv[0] === "list") {
+			const requested = argv[3].slice(`${GENTLE_AI_MODULE}@`.length);
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: pseudo(requested), Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: requested } }) };
+		}
 		if (command === "/usr/bin/go" && argv[0] === "version") return { code: 0, stdout: `go version ${userGo === "devel" ? "devel go1.26-abc" : `go${userGo}`} darwin/arm64\n` };
 		if (argv[0] === "install") {
 			mkdirSync(options.env!.GOBIN, { recursive: true });

package/tests/nan-provider.test.ts

@@ -3,6 +3,7 @@ import test from "node:test";
 import type { RefreshModelsContext } from "@earendil-works/pi-ai";
 import { clampThinkingLevel, createModels, getSupportedThinkingLevels, InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import type { Provider } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
 import nanProviderExtension from "../extensions/nan-provider.ts";
 import { createNanProviderConfig as createNativeProvider, isNanAdaptiveReasoningModel, NAN_PROVIDER_BASE_URL, NAN_PROVIDER_ID } from "../lib/nan-provider.ts";
 
@@ -195,6 +196,41 @@ test("initial catalog contains all seven documented chat models with configured
 	assert.deepEqual(model?.cost, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
 });
 
+test("only NaN DeepSeek serializes its unchanged output cap as max_tokens", async () => {
+	const models = createNativeProvider().getModels();
+	const model = models.find((model) => model.id === "deepseek-v4-flash")!;
+	let body: Record<string, unknown> | undefined;
+	const result = await completeSimple(model, { messages: [{ role: "user", content: "offline probe", timestamp: 0 }] }, {
+		apiKey: "synthetic-key", reasoning: "minimal",
+		fetch: async (input, init) => {
+			assert.equal(String(input), `${NAN_PROVIDER_BASE_URL}/chat/completions`);
+			body = JSON.parse(String(init?.body));
+			return new Response('data: {"id":"offline","choices":[{"index":0,"delta":{"role":"assistant","content":"ok"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n', {
+				headers: { "content-type": "text/event-stream" },
+			});
+		},
+	});
+	assert.equal(result.stopReason, "stop");
+	assert.equal(body?.max_tokens, 16_384);
+	assert.ok(!Object.hasOwn(body!, "max_completion_tokens"));
+	assert.equal(body?.reasoning_effort, "minimal");
+	assert.equal(model.maxTokens, 16_384);
+	assert.equal(model.compat?.maxTokensField, "max_tokens");
+	assert.ok(models.filter((candidate) => candidate.id !== model.id).every((candidate) => candidate.compat === undefined));
+});
+
+test("DeepSeek compat is isolated across snapshots, providers, and live refreshes", async () => {
+	const provider = createNativeProvider({ fetchImpl: async () => jsonResponse({ data: [{ id: "deepseek-v4-flash" }] }) });
+	for (const live of [false, true]) {
+		if (live) await provider.refreshModels!(refreshContext({ type: "api_key", key: "synthetic-key" }));
+		const model = provider.getModels().find((model) => model.id === "deepseek-v4-flash")!;
+		assert.equal(model.compat?.maxTokensField, "max_tokens");
+		model.compat!.maxTokensField = "max_completion_tokens";
+		assert.equal(provider.getModels().find((candidate) => candidate.id === model.id)!.compat?.maxTokensField, "max_tokens");
+		assert.equal(createNativeProvider().getModels().find((model) => model.id === "deepseek-v4-flash")!.compat?.maxTokensField, "max_tokens");
+	}
+});
+
 test("GLM models expose exactly NaN's four efforts and no off", () => {
 	const models = createNativeProvider().getModels();
 	for (const id of ["glm5.3", "glm5.3-flash"]) {

package/tests/native-review-capability-contract.test.ts

@@ -103,9 +103,10 @@ test("2.4.0 repeats 2.2.3 because the START envelope Pi consumes still omits ris
 	//             the envelope carries, not a capability it lost.
 	//   delivery  `review validate --gate pre-commit` still answers
 	//             `gentle-ai.review-gate-result/v1` with
-	//             `delivery: "disabled/unmanaged"` at exit 0. Under opt-in RDD
-	//             this is now the DEFAULT delivery answer for an install that
-	//             never enabled review, so the column matters more, not less.
+	//             `delivery: "disabled/unmanaged"` at exit 0. RDD is on by
+	//             default again since gentle-ai v4.0.0, so this is the answer
+	//             for an install that turned review off, and the column still
+	//             matters.
 	//
 	// riskEvidence and hint stay dark for exactly the reason the 2.2.0 comment
 	// gives, re-proven rather than inherited: the negotiated
@@ -385,11 +386,17 @@ test("4.2.0 explicitly repeats 4.1.1 because capabilities/v2.6 is unchanged desp
 	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["4.1.1"] as Record<string, boolean>);
 });
 
+test("4.3.1 explicitly repeats 4.2.0 because capabilities/v2.6 and provider contract 1.4.0 are unchanged", () => {
+	const contract = NATIVE_CLI_CONTRACTS["4.3.1"] as Record<string, boolean>;
+	assert.ok(contract);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["4.2.0"] as Record<string, boolean>);
+});
+
 test("no shipped version key was added beyond the pin bump", () => {
 	// Rows are promises to consumers, so a new key only ever appears in a
 	// dedicated commit alongside a pin bump, never as a side effect. v2.2.4 and
 	// v2.3.0 shipped upstream while Pi stayed on 2.2.3 and were never pinned,
 	// so they get no row: a row asserts ground truth measured against a binary
 	// Pi actually ran, and the table only has to be ascending, not gapless.
-	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1", "3.1.0", "3.2.1", "3.4.0", "3.5.0", "3.6.0", "3.6.1", "3.7.0", "4.0.0", "4.1.1", "4.2.0"]);
+	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0", "2.5.0-rc.3", "2.5.0", "2.6.0", "2.7.0", "2.8.0", "2.8.1", "2.8.2", "2.9.0", "2.9.1", "3.0.0", "3.0.1", "3.1.0", "3.2.1", "3.4.0", "3.5.0", "3.6.0", "3.6.1", "3.7.0", "4.0.0", "4.1.1", "4.2.0", "4.3.1"]);
 });

package/tests/native-review-parity.test.ts

@@ -384,7 +384,7 @@ test("review-mode gate retains every off-source continuation and fails closed on
 	for (const [source, expected] of [
 		["clone_local", /clear this clone-local override/],
 		["global", /cannot override a global off/],
-		["default", /off by default until explicitly enabled/],
+		["default", /RDD is on by default, but this install could not resolve the review mode and failed closed to off/],
 	] as const) {
 		const native = {
 			reviewMode: async () => ({ operation: "status", scope: "clone", status: { global: source === "global" ? "off" : "", cloneLocal: source === "clone_local" ? "off" : "", effective: "off" as const, source } }),