gentle-pi 4.0.0 → 4.2.0

package/tests/main-channel.test.ts

@@ -0,0 +1,344 @@
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, 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";
+import test from "node:test";
+import {
+	CHANNEL_SCHEMA,
+	GENTLE_AI_MAIN_PACKAGE,
+	MainChannelError,
+	buildMainGentleAi,
+	channelStatePath,
+	installOwner,
+	mainChannelAdapter,
+	mainVersion,
+	packMainShell,
+	readChannel,
+	resolveMainCommit,
+	runUpgrade,
+	writeChannel,
+} from "../scripts/main-channel.mjs";
+import { artifactFor } from "../scripts/installer-downloads.mjs";
+
+const SHELL_SHA = "6e7e3a18f794223396527a54c7c36d19c7d236c6";
+const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
+const posixOnly = { skip: process.platform === "win32" };
+
+function sandbox() {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "main-channel-")));
+	const home = join(root, "home");
+	mkdirSync(home);
+	return { root, home, ctx: { env: {}, home }, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+type Call = { command: string; argv: string[]; options: { env?: Record<string, string>; cwd?: string } };
+
+test("channel state defaults to release and round-trips a main record", async () => {
+	const s = sandbox();
+	try {
+		assert.equal(channelStatePath(s.ctx), join(s.home, ".pi", "gentle-ai", "channel.json"));
+		assert.equal(channelStatePath({ env: { GENTLE_PI_CONFIG_HOME: join(s.root, "cfg") }, home: s.home }), join(s.root, "cfg", "channel.json"));
+		assert.deepEqual(await readChannel(s.ctx, fsPromises), { channel: "release" });
+		await writeChannel(s.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		assert.deepEqual(JSON.parse(readFileSync(channelStatePath(s.ctx), "utf8")),
+			{ schema: CHANNEL_SCHEMA, channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA });
+		assert.deepEqual(await readChannel(s.ctx, fsPromises), { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA });
+	} finally { s.cleanup(); }
+});
+
+test("a malformed channel state fails closed instead of falling back to release", async () => {
+	const s = sandbox();
+	try {
+		mkdirSync(join(s.home, ".pi", "gentle-ai"), { recursive: true });
+		for (const bad of ["not json", JSON.stringify({ schema: CHANNEL_SCHEMA, channel: "nightly" }),
+			JSON.stringify({ schema: CHANNEL_SCHEMA, channel: "main", shellCommit: "abc", gentleAiCommit: AI_SHA })]) {
+			writeFileSync(channelStatePath(s.ctx), bad);
+			await assert.rejects(readChannel(s.ctx, fsPromises), (error: MainChannelError) => error.code === "channel-state-invalid");
+		}
+	} finally { s.cleanup(); }
+});
+
+test("the latest main commit comes from GitHub as an exact 40-character SHA", async () => {
+	const requests: Array<{ url: string; accept: string | undefined }> = [];
+	const fetch = async (url: string, init: { headers: Record<string, string> }) => {
+		requests.push({ url, accept: init.headers.Accept });
+		return { ok: true, status: 200, text: async () => `${SHELL_SHA}\n` };
+	};
+	assert.equal(await resolveMainCommit("Gentleman-Programming/gentle-shell", { fetch }), SHELL_SHA);
+	assert.deepEqual(requests, [{ url: "https://api.github.com/repos/Gentleman-Programming/gentle-shell/commits/main", accept: "application/vnd.github.sha" }]);
+	for (const response of [{ ok: true, status: 200, text: async () => "abc123" }, { ok: false, status: 403, text: async () => SHELL_SHA }]) {
+		await assert.rejects(resolveMainCommit("Gentleman-Programming/gentle-shell", { fetch: async () => response }),
+			(error: MainChannelError) => error.code === "main-commit-unavailable");
+	}
+});
+
+test("a main version marks the release version with the commit", () => {
+	assert.equal(mainVersion("4.0.0", SHELL_SHA), "4.0.0-main.6e7e3a18f794");
+});
+
+test("the Gentle Shell main package is packed from the exact commit without prepack", async () => {
+	const s = sandbox();
+	try {
+		const calls: Call[] = [];
+		let downloaded = "";
+		let packed: { version: string; scripts: Record<string, string | undefined> } | null = null;
+		const fetch = async (url: string) => {
+			downloaded = url;
+			return { ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode("archive").buffer };
+		};
+		const run = async (command: string, argv: string[], options: Call["options"]) => {
+			calls.push({ command, argv, options });
+			if (argv[0] === "-xzf") {
+				const target = argv[argv.indexOf("-C") + 1];
+				writeFileSync(join(target, "package.json"), JSON.stringify({ name: "gentle-pi", version: "4.0.0",
+					scripts: { prepack: "pnpm test", prepare: "x", postinstall: "node scripts/install-gentle-ai.mjs" } }));
+			} else {
+				packed = JSON.parse(readFileSync(join(options.cwd!, "package.json"), "utf8"));
+				const destination = argv[argv.indexOf("--pack-destination") + 1];
+				writeFileSync(join(destination, "gentle-pi-4.0.0-main.6e7e3a18f794.tgz"), "tgz");
+			}
+			return { code: 0, stdout: "" };
+		};
+		const tgz = await packMainShell({ commit: SHELL_SHA, ctx: s.ctx, fetch, run, pnpm: { command: "/bin/pnpm", prefix: [] }, fs: fsPromises });
+		assert.equal(downloaded, `https://codeload.github.com/Gentleman-Programming/gentle-shell/tar.gz/${SHELL_SHA}`);
+		assert.equal(tgz, join(s.home, ".pi", "gentle-ai", "main", "packages", "gentle-pi-4.0.0-main.6e7e3a18f794.tgz"));
+		assert.ok(existsSync(tgz));
+		const pack = calls.find((call) => call.command === "/bin/pnpm");
+		assert.ok(pack);
+		assert.deepEqual(pack.argv.slice(0, 1), ["pack"]);
+		assert.ok(packed);
+		assert.equal(packed.version, "4.0.0-main.6e7e3a18f794");
+		assert.equal(packed.scripts.prepack, undefined);
+		assert.equal(packed.scripts.prepare, undefined);
+		assert.equal(packed.scripts.postinstall, "node scripts/install-gentle-ai.mjs");
+		assert.equal(existsSync(join(s.home, ".pi", "gentle-ai", "main", ".source")), false, "the extracted source is removed");
+	} finally { s.cleanup(); }
+});
+
+// Run 38061123855: with Git for Windows' usr\bin first on PATH, MSYS tar reads `D:\...` as a remote host.
+test("on Windows the source archive is extracted by System32's tar.exe by absolute path; POSIX keeps tar from PATH", async () => {
+	const windowsTar = win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe");
+	for (const [platform, expected] of [["win32", windowsTar], ["linux", "tar"], ["darwin", "tar"]]) {
+		const s = sandbox();
+		try {
+			const extracts: string[] = [];
+			const fetch = async () => ({ ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode("archive").buffer });
+			const run = async (command: string, argv: string[], options: Call["options"]) => {
+				if (argv[0] === "-xzf") {
+					extracts.push(command);
+					writeFileSync(join(argv[argv.indexOf("-C") + 1], "package.json"), JSON.stringify({ name: "gentle-pi", version: "4.0.0" }));
+				} else {
+					writeFileSync(join(argv[argv.indexOf("--pack-destination") + 1], "gentle-pi-4.0.0-main.6e7e3a18f794.tgz"), "tgz");
+					assert.ok(options.cwd);
+				}
+				return { code: 0, stdout: "" };
+			};
+			await packMainShell({ commit: SHELL_SHA, ctx: s.ctx, fetch, run, pnpm: { command: "/bin/pnpm", prefix: [] }, fs: fsPromises, platform });
+			assert.deepEqual(extracts, [expected], platform);
+		} finally { s.cleanup(); }
+	}
+});
+
+test("a failed source extraction or Go build keeps the command's bounded stderr tail as the error's cause", async () => {
+	const s = sandbox();
+	try {
+		const tail = "tar (child): Cannot connect to D: resolve failed\ntar: Error is not recoverable: exiting now\n";
+		const requested: Array<number | undefined> = [];
+		const fetch = async () => ({ ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode("archive").buffer });
+		const tar = async (_command: string, _argv: string[], options: { stderrTail?: number }) => {
+			requested.push(options.stderrTail);
+			return { code: 2, stdout: "", stderrTail: tail };
+		};
+		await assert.rejects(packMainShell({ commit: SHELL_SHA, ctx: s.ctx, fetch, run: tar, pnpm: { command: "/bin/pnpm", prefix: [] }, fs: fsPromises, platform: "linux" }),
+			(error: MainChannelError) => error.code === "main-shell-pack-failed" && error.cause instanceof Error && error.cause.message === tail.trim());
+		const go = "go: downloading github.com/gentleman-programming/gentle-ai/v4\ngo: verifying module: checksum mismatch\n";
+		const build = async (_command: string, _argv: string[], options: { stderrTail?: number }) => {
+			requested.push(options.stderrTail);
+			return { code: 1, stdout: "", stderrTail: go };
+		};
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "linux", goPath: "/go/bin/go", run: build, fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-build-failed" && error.cause instanceof Error && error.cause.message === go.trim());
+		assert.deepEqual(requested, [4096, 4096]);
+		// Without any stderr the error has no cause, as before.
+		await assert.rejects(buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "linux", goPath: "/go/bin/go", run: async () => ({ code: 1, stdout: "" }), fs: fsPromises }),
+			(error: MainChannelError) => error.code === "main-gentle-ai-build-failed" && error.cause === undefined);
+	} finally { s.cleanup(); }
+});
+
+test("Gentle AI main is built from the exact commit through Go's checksum database and registered as the override", posixOnly, async () => {
+	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 built = await buildMainGentleAi({ commit: AI_SHA, ctx: s.ctx, platform: "darwin", goPath, run, fs: fsPromises });
+		const install = calls[0];
+		assert.equal(install.command, goPath);
+		assert.deepEqual(install.argv, ["install", `${GENTLE_AI_MAIN_PACKAGE}@${AI_SHA}`]);
+		for (const [key, value] of Object.entries({ GOPROXY: "https://proxy.golang.org", GOSUMDB: "sum.golang.org", GOTOOLCHAIN: "local",
+			GOFLAGS: "-modcacherw", GONOSUMDB: "", GOPRIVATE: "", GOINSECURE: "", GOENV: "off", GOWORK: "off" })) assert.equal(install.options.env![key], value, key);
+		assert.equal(built.binaryPath, join(s.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA, "gentle-ai"));
+		assert.equal(built.version, "4.0.1-0.20261008202137-1f9d5e6423e3");
+		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 Gentle AI build whose version names another commit is rejected and never registered", 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" };
+		};
+		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);
+	} finally { s.cleanup(); }
+});
+
+test("the runner adapter resolves commits and records the channel through the given network and files", async () => {
+	const s = sandbox();
+	try {
+		const urls: string[] = [];
+		const adapter = mainChannelAdapter({ fs: fsPromises, fetch: async (url: string) => {
+			urls.push(url);
+			return { ok: true, status: 200, text: async () => AI_SHA };
+		} });
+		assert.equal(await adapter.resolveCommit("Gentleman-Programming/gentle-ai"), AI_SHA);
+		assert.deepEqual(urls, ["https://api.github.com/repos/Gentleman-Programming/gentle-ai/commits/main"]);
+		await adapter.writeChannel(s.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA });
+		assert.deepEqual(await readChannel(s.ctx, fsPromises), { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA });
+	} finally { s.cleanup(); }
+});
+
+test("the owner of an installation is pnpm under PNPM_HOME, npm only inside npm's global root, otherwise unknown", () => {
+	const roots = { pnpmHome: "/u/Library/pnpm", npmRoot: "/u/.local/lib/node_modules" };
+	assert.equal(installOwner({ ...roots, packageRoot: "/u/Library/pnpm/global/v11/x/node_modules/gentle-pi" }), "pnpm");
+	assert.equal(installOwner({ ...roots, packageRoot: "/u/.local/lib/node_modules/gentle-pi" }), "npm");
+	for (const packageRoot of ["/u/work/gentle-pi", "/u/.local/lib/node_modules", "/u/.local/lib/node_modules/other/gentle-pi"]) {
+		assert.equal(installOwner({ ...roots, packageRoot }), null, packageRoot);
+	}
+	assert.equal(installOwner({ pnpmHome: null, npmRoot: null, packageRoot: "/u/.local/lib/node_modules/gentle-pi" }), null);
+});
+
+test("installOwner attributes another named package, such as the scoped Pi, the same way", () => {
+	const roots = { pnpmHome: "/u/Library/pnpm", npmRoot: "/u/.local/lib/node_modules", name: "@earendil-works/pi-coding-agent" };
+	assert.equal(installOwner({ ...roots, packageRoot: "/u/.local/lib/node_modules/@earendil-works/pi-coding-agent" }), "npm");
+	assert.equal(installOwner({ ...roots, packageRoot: "/u/Library/pnpm/global/v11/x/node_modules/@earendil-works/pi-coding-agent" }), "pnpm");
+	for (const packageRoot of ["/u/.local/lib/node_modules/gentle-pi", "/u/.local/lib/node_modules/@earendil-works",
+		"/u/.local/share/mise/installs/pi/lib/node_modules/@earendil-works/pi-coding-agent"]) {
+		assert.equal(installOwner({ ...roots, packageRoot }), null, packageRoot);
+	}
+});
+
+test("installOwner follows Windows paths on any host: backslashes and case-insensitive roots", () => {
+	const roots = { pnpmHome: "C:\\Users\\u\\AppData\\Local\\pnpm", npmRoot: "C:\\Users\\u\\AppData\\Roaming\\npm\\node_modules",
+		name: "@earendil-works/pi-coding-agent", platform: "win32" };
+	assert.equal(installOwner({ ...roots, packageRoot: "C:\\Users\\u\\AppData\\Roaming\\npm\\node_modules\\@earendil-works\\pi-coding-agent" }), "npm");
+	assert.equal(installOwner({ ...roots, packageRoot: "c:\\users\\U\\appdata\\roaming\\NPM\\Node_Modules\\@Earendil-Works\\Pi-Coding-Agent" }), "npm");
+	assert.equal(installOwner({ ...roots, packageRoot: "C:\\Users\\u\\AppData\\Local\\PNPM\\global\\v11\\x\\node_modules\\@earendil-works\\pi-coding-agent" }), "pnpm");
+	for (const packageRoot of ["C:\\Users\\u\\AppData\\Roaming\\npm\\node_modules\\other\\@earendil-works\\pi-coding-agent",
+		"C:\\Users\\u\\AppData\\Roaming\\npm\\node_modules", "D:\\Users\\u\\AppData\\Roaming\\npm\\node_modules\\@earendil-works\\pi-coding-agent",
+		"C:\\Users\\u\\AppData\\Local\\pnpm"]) {
+		assert.equal(installOwner({ ...roots, packageRoot }), null, packageRoot);
+	}
+	// POSIX paths keep their exact case.
+	assert.equal(installOwner({ pnpmHome: null, npmRoot: "/u/lib/node_modules", packageRoot: "/u/lib/node_modules/Gentle-Pi", platform: "linux" }), null);
+});
+
+// `gentle-shell upgrade --channel main` after the installer provided its own pinned Go.
+const NEW_AI = "2222222222222222222222222222222222222222";
+/** A main install whose Gentle Shell is current, so only Gentle AI is rebuilt with Go. */
+async function upgradeWorld({ userGo = null as string | null, pinned = false, acquireFails = false }) {
+	const s = sandbox();
+	const goDirectory = join(s.home, ".pi", "gentle-ai", "tools", "go", "1.25.14");
+	const pinnedGo = join(goDirectory, "go", "bin", "go");
+	if (pinned) {
+		mkdirSync(join(goDirectory, "go", "bin"), { recursive: true, mode: 0o700 });
+		chmodSync(goDirectory, 0o700);
+		writeFileSync(pinnedGo, "#!/bin/sh\n", { mode: 0o755 });
+		writeFileSync(join(goDirectory, ".gentle-shell-go"), `${artifactFor("go", "darwin", "arm64").url}\n`);
+	}
+	await writeChannel(s.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+	const calls: Call[] = [];
+	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 });
+		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 });
+			writeFileSync(join(options.env!.GOBIN, "gentle-ai"), "#!/bin/sh\n", { mode: 0o755 });
+			return { code: 0, stdout: "" };
+		}
+		return { code: 0, stdout: `gentle-ai 4.0.1-0.20261008202137-${NEW_AI.slice(0, 12)}\n` };
+	};
+	const which = async (name: string) => (name === "pnpm" || (name === "go" && userGo !== null) ? `/usr/bin/${name}` : null);
+	// The verified download itself is acquireGo's (installer-downloads tests); here it only publishes the pinned path.
+	const acquired: string[] = [];
+	const acquireGo = async () => {
+		acquired.push(pinnedGo);
+		// As acquireGo fails: wrapped, with the reason as its cause.
+		if (acquireFails) throw new Error("Go verified acquisition failed; nothing was published", { cause: new Error("Conflicting Go destination: /x") });
+		return { goPath: pinnedGo, version: "1.25.14", acquired: true };
+	};
+	const upgrade = () => runUpgrade({ args: ["--channel", "main"], ctx: s.ctx, platform: "darwin", arch: "arm64", packageRoot: join(s.root, "pkg"),
+		currentVersion: "4.0.0-main.6e7e3a18f794", adapters: { fetch, run, fs: fsPromises, which, acquireGo }, out: () => {} });
+	const builtWith = () => calls.find((call) => call.argv[0] === "install")?.command;
+	return { ...s, calls, pinnedGo, upgrade, builtWith, acquired };
+}
+
+test("upgrading main uses the installer's pinned Go when the user's Go is missing, older or cannot be checked, and leaves the user's Go as it is", posixOnly, async () => {
+	for (const userGo of [null, "1.24.0", "devel"]) {
+		const w = await upgradeWorld({ userGo, pinned: true });
+		try {
+			assert.equal(await w.upgrade(), 0);
+			assert.equal(w.builtWith(), w.pinnedGo, String(userGo));
+			// The user's Go only reported its version.
+			assert.deepEqual(w.calls.filter((call) => call.command === "/usr/bin/go").map((call) => call.argv), userGo ? [["version"]] : []);
+			assert.deepEqual(w.acquired, [], "an already published pinned Go is reused");
+		} finally { w.cleanup(); }
+	}
+});
+
+test("upgrading main keeps using a user's Go that meets the requirement, even next to the pinned Go", posixOnly, async () => {
+	const w = await upgradeWorld({ userGo: "1.26.0", pinned: true });
+	try {
+		assert.equal(await w.upgrade(), 0);
+		assert.equal(w.builtWith(), "/usr/bin/go");
+	} finally { w.cleanup(); }
+});
+
+test("upgrading main without a usable Go downloads the installer's pinned Go once, only to build", posixOnly, async () => {
+	for (const userGo of [null, "1.24.0", "devel"]) {
+		const w = await upgradeWorld({ userGo });
+		try {
+			assert.equal(await w.upgrade(), 0);
+			assert.deepEqual(w.acquired, [w.pinnedGo], String(userGo));
+			assert.equal(w.builtWith(), w.pinnedGo, String(userGo));
+			assert.deepEqual(w.calls.filter((call) => call.command === "/usr/bin/go").map((call) => call.argv), userGo ? [["version"]] : []);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("upgrading main stops before building when the pinned Go cannot be downloaded", posixOnly, async () => {
+	const w = await upgradeWorld({ userGo: "devel", acquireFails: true });
+	try {
+		await assert.rejects(w.upgrade(), (error: MainChannelError) => error.code === "main-requires-tools" &&
+			error.message.includes("Go 1.25.14") && error.message.includes("Conflicting Go destination: /x") && !error.message.includes("network"));
+		assert.equal(w.builtWith(), undefined);
+	} finally { w.cleanup(); }
+});

package/tests/maintainer/provider-relay.maintest.ts

@@ -66,8 +66,11 @@ function descriptor(overrides = {}) {
 		...overrides,
 	};
 }
+function isRoleError(error: unknown): error is Error & { kind: string; stage: string; mutationOutcome: string } {
+	return error instanceof Error && error instanceof ProviderRoleVectorError && "kind" in error && typeof error.kind === "string" && "stage" in error && typeof error.stage === "string" && "mutationOutcome" in error && typeof error.mutationOutcome === "string";
+}
 function rejects(obj, fragment) {
-	assert.throws(() => validateDescriptor(obj), (error) => error instanceof DescriptorValidationError && error.message.includes(fragment));
+	assert.throws(() => validateDescriptor(obj), (error) => error instanceof Error && error instanceof DescriptorValidationError && error.message.includes(fragment));
 }
 function tempDescriptor(t, obj) {
 	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-"));
@@ -102,11 +105,9 @@ test("rejects malformed descriptor fields with exact-shape errors (no defaults,
 	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, captureArgumentTokens: [...CAPTURE_TOKENS].filter((t) => t !== "--materialize=true") }] }, "--materialize=true");
 });
 test("submission is validated through the real relay resolver before any process launches (exact shape)", () => {
-	const twoValues = structuredClone(SUBMISSION);
-	twoValues.values = [...SUBMISSION.values, { slot: "extra", domain: "artifact_path_or_stdin", substitutionLocation: 0 }];
+	const twoValues = { ...structuredClone(SUBMISSION), values: [...SUBMISSION.values, { slot: "extra", domain: "artifact_path_or_stdin", substitutionLocation: 0 }] };
 	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: twoValues }] }, "not a bindable provider form");
-	const noSlot = structuredClone(SUBMISSION);
-	noSlot.argumentTokens = [...BINDING_TOKENS, "--input=/no/value/slot"];
+	const noSlot = { ...structuredClone(SUBMISSION), argumentTokens: [...BINDING_TOKENS, "--input=/no/value/slot"] };
 	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: noSlot }] }, "not a bindable provider form");
 	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: { ...structuredClone(SUBMISSION), extra: 1 } }] }, "extra");
 });
@@ -245,7 +246,7 @@ test("negative control: a role vector failure (not surface-unavailable) is repor
 });
 test("runProviderRoleVector treats a prelaunch abort as not-started with no mutation", async () => {
 	const controller = new AbortController(); controller.abort();
-	await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: process.execPath, signal: controller.signal }), (error) => error instanceof ProviderRoleVectorError && error.kind === ROLE_VECTOR_FAILURE.ROLE_ABORTED && error.stage === "launch" && error.mutationOutcome === "none");
+	await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: process.execPath, signal: controller.signal }), (error) => isRoleError(error) && error.kind === ROLE_VECTOR_FAILURE.ROLE_ABORTED && error.stage === "launch" && error.mutationOutcome === "none");
 });
 function roleChild(t: test.TestContext, name: string, source: string) {
 	const path = sandboxPath(`${name} preload.cjs`), savedNodeOptions = process.env.NODE_OPTIONS; writeFileSync(path, `const roleArgv = ["review", ...process.argv.slice(2)], Module = require("node:module"), resolveFilename = Module._resolveFilename; Module._resolveFilename = function (request, ...args) { return /[\\\\/]review$/.test(request) ? ${JSON.stringify(path)} : resolveFilename.call(this, request, ...args); }; ${source}`);
@@ -262,19 +263,19 @@ test("runProviderRoleVector executes both real stub-child verbs and decodes snak
 test("runProviderRoleVector rejects malformed artifact binding shape before stale binding comparison", async (t) => {
 	for (const malformed of [{ lineage_id: "", target_identity: ROLE_TARGET }, { lineage_id: ROLE_LINEAGE, target_identity: "not-a-sha256" }]) {
 		const child = roleChild(t, `malformed-${malformed.lineage_id || "lineage"}.cjs`, `process.stdout.write(JSON.stringify({ schema: ${JSON.stringify(PROVIDER_ROLE_CAPTURE_ARTIFACT_SCHEMA)}, role: "refuter", captured: true, ...${JSON.stringify(malformed)} })); process.exit(0);`);
-		await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env }), (error) => error instanceof ProviderRoleVectorError && error.kind === ROLE_VECTOR_FAILURE.ROLE_FAILED && /typed shape/.test(error.message));
+		await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env }), (error) => isRoleError(error) && error.kind === ROLE_VECTOR_FAILURE.ROLE_FAILED && /typed shape/.test(error.message));
 	}
 });
 test("runProviderRoleVector classifies an empty successful artifact as unknown and requires STATUS re-query", async (t) => {
 	const child = roleChild(t, "empty-artifact.cjs", "process.exit(0);");
 	await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env }), (caught) => {
-		assert.ok(caught instanceof ProviderRoleVectorError); assert.equal(caught.kind, ROLE_VECTOR_FAILURE.EMPTY_ARTIFACT); assert.equal(caught.stage, "execute"); assert.equal(caught.mutationOutcome, "unknown"); assert.match(caught.message, /re-query negotiated STATUS before any retry/); return true;
+		assert.ok(isRoleError(caught)); assert.equal(caught.kind, ROLE_VECTOR_FAILURE.EMPTY_ARTIFACT); assert.equal(caught.stage, "execute"); assert.equal(caught.mutationOutcome, "unknown"); assert.match(caught.message, /re-query negotiated STATUS before any retry/); return true;
 	});
 });
 test("runProviderRoleVector bounds each output stream before JSON or exit handling", async (t) => {
 	for (const stream of ["stdout", "stderr"] as const) {
 		const child = roleChild(t, `overflow-${stream}.cjs`, `process.${stream}.write("x".repeat(${ROLE_STREAM_MAX_BYTES + 1})); setInterval(() => {}, 1_000);`);
-		await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env, timeoutMs: 1_000 }), (error) => error instanceof ProviderRoleVectorError && error.kind === ROLE_VECTOR_FAILURE.ROLE_OUTPUT_OVERFLOW && error.mutationOutcome === "unknown");
+		await assert.rejects(runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env, timeoutMs: 1_000 }), (error) => isRoleError(error) && error.kind === ROLE_VECTOR_FAILURE.ROLE_OUTPUT_OVERFLOW && error.mutationOutcome === "unknown");
 	}
 });
 async function descendantPid(path: string) {
@@ -293,7 +294,7 @@ test("role watchdog and abort reap descendants on every platform", async (t) =>
 		t.after(() => { if (pid > 0) try { process.kill(pid, "SIGKILL"); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; } });
 		assert.ok(DEFAULT_ROLE_VECTOR_TIMEOUT_MS > 600_000, "the outer 900s watchdog FIRES after the provider-owned 600s deadline with setup/cancellation margin");
 		if (mode === "abort") controller.abort();
-		await assert.rejects(run, (error) => error instanceof ProviderRoleVectorError && error.kind === (mode === "abort" ? ROLE_VECTOR_FAILURE.ROLE_ABORTED : ROLE_VECTOR_FAILURE.ROLE_TIMED_OUT) && error.mutationOutcome === "unknown");
+		await assert.rejects(run, (error) => isRoleError(error) && error.kind === (mode === "abort" ? ROLE_VECTOR_FAILURE.ROLE_ABORTED : ROLE_VECTOR_FAILURE.ROLE_TIMED_OUT) && error.mutationOutcome === "unknown");
 		await assertReaped(pid);
 	});
 });
@@ -302,7 +303,7 @@ test("failed tree termination settles despite a surviving descendant retaining i
 	const child = roleChild(t, "pipe-holder-role-child.cjs", `const fs = require("node:fs"), { spawn } = require("node:child_process"), grandchild = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "inherit", env: { ...process.env, NODE_OPTIONS: "" } }); fs.writeFileSync(${JSON.stringify(sandboxPath("ROLE_PID_PLACEHOLDER"))}.replace("ROLE_PID_PLACEHOLDER", ${JSON.stringify("role-pipe-holder.pid")}), String(grandchild.pid)); setInterval(() => {}, 1000);`);
 	const run = runProviderRoleVector({ kind: "provider-role-refuter", argumentTokens: REFUTER_TOKENS, gentleAiExecutable: child.executable, env: child.env, signal: controller.signal, terminateProcessTree: (process) => { process.kill("SIGKILL"); return false; } });
 	const pid = await descendantPid(grandchild); t.after(() => { try { process.kill(pid, "SIGKILL"); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; } });
-	const started = Date.now(); controller.abort(); await assert.rejects(run, (error) => error instanceof ProviderRoleVectorError && error.kind === ROLE_VECTOR_FAILURE.ROLE_TERMINATION_FAILED && error.stage === "execute" && error.mutationOutcome === "unknown");
+	const started = Date.now(); controller.abort(); await assert.rejects(run, (error) => isRoleError(error) && error.kind === ROLE_VECTOR_FAILURE.ROLE_TERMINATION_FAILED && error.stage === "execute" && error.mutationOutcome === "unknown");
 	assert.ok(Date.now() - started < 500, "failed tree termination must not wait for descendant-held pipes to close"); assert.doesNotThrow(() => process.kill(pid, 0), "the fixture descendant must survive while retaining inherited pipes");
 });
 test("stale-target fail-closed: missing or duplicate required binding tokens are rejected before runner invocation", () => {
@@ -495,7 +496,7 @@ const baselineArmed = typeof baselineBinary === "string" && baselineBinary.lengt
 const baselineReason = () => `${BASELINE_ENV} is unset or not an existing absolute path; supply the baseline gentle-ai binary (external evidence establishes whether it is RC8), or set ${REQUIRE_ENV}=1 to fail instead of skip.`;
 if (!baselineArmed && armed) throw new Error(baselineReason());
 if (!baselineArmed) console.log(`tests/maintainer/provider-relay.maintest.ts: ${baselineReason()}`);
-function baselineDescriptor(kind = "relay-unavailable" as const) {
+function baselineDescriptor(kind: "relay-unavailable" | "positive-lens" = "relay-unavailable") {
 	return validateDescriptor({ ...descriptor(), gentleAiExecutable: baselineBinary, cases: [{ name: "baseline-negative-control", kind, captureArgumentTokens: [...CAPTURE_TOKENS], submission: structuredClone(SUBMISSION) }] });
 }
 test("negative control: runMatrix proves the baseline fails closed as relay-unavailable with zero mutation", { skip: !baselineArmed }, async () => {

package/tests/model-price-ratio.test.ts

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { computeModelPriceRatio, modelRoutingLine, renderModelRoutingLine, type ModelCost, type ModelPriceLookup } from "../lib/model-price-ratio.ts";
+
+// gentle-shell#1731 S3/AC3: the runtime computes the orchestrator/worker price
+// ratio from catalog prices and renders it as one fact line; the model never
+// estimates it.
+
+const catalog: Record<string, ModelCost> = {
+	"anthropic/fable": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+	"anthropic/opus": { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+	"openai/mixed": { input: 3, output: 10, cacheRead: 0.3, cacheWrite: 0 },
+	"local/free": { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	"odd/thirds": { input: 9, output: 9, cacheRead: 0, cacheWrite: 0 },
+	"odd/three": { input: 3, output: 3, cacheRead: 0, cacheWrite: 0 },
+	"odd/seven": { input: 7, output: 7, cacheRead: 0, cacheWrite: 0 },
+};
+const lookup: ModelPriceLookup = (model) => catalog[`${model.provider}/${model.id}`];
+const fable = { provider: "anthropic", id: "fable" };
+const opus = { provider: "anthropic", id: "opus" };
+
+test("renders the input, output, and blended ratio for an expensive orchestrator", () => {
+	assert.equal(
+		modelRoutingLine(fable, opus, lookup),
+		"Model routing: orchestrator anthropic/fable costs 3.0x the worker anthropic/opus (input 3.0x, output 3.0x).",
+	);
+	const ratio = computeModelPriceRatio(fable, opus, lookup);
+	assert.equal(ratio.kind, "known");
+	if (ratio.kind === "known") {
+		assert.equal(ratio.input, 3);
+		assert.equal(ratio.output, 3);
+		assert.equal(ratio.blended, 3);
+	}
+});
+
+test("the blended ratio is the larger of the input and output ratios", () => {
+	// fable/mixed: input 15/3 = 5x, output 75/10 = 7.5x.
+	assert.equal(
+		modelRoutingLine(fable, { provider: "openai", id: "mixed" }, lookup),
+		"Model routing: orchestrator anthropic/fable costs 7.5x the worker openai/mixed (input 5.0x, output 7.5x).",
+	);
+});
+
+test("the same model renders 1.0x", () => {
+	assert.equal(
+		modelRoutingLine(opus, opus, lookup),
+		"Model routing: orchestrator anthropic/opus costs 1.0x the worker anthropic/opus (input 1.0x, output 1.0x).",
+	);
+});
+
+test("a cheaper orchestrator renders a ratio below 1 normally", () => {
+	assert.equal(
+		modelRoutingLine(opus, fable, lookup),
+		"Model routing: orchestrator anthropic/opus costs 0.3x the worker anthropic/fable (input 0.3x, output 0.3x).",
+	);
+});
+
+test("ratios round to one decimal", () => {
+	// 7/3 = 2.333..., 9/7 = 1.2857...
+	assert.equal(
+		modelRoutingLine({ provider: "odd", id: "seven" }, { provider: "odd", id: "three" }, lookup),
+		"Model routing: orchestrator odd/seven costs 2.3x the worker odd/three (input 2.3x, output 2.3x).",
+	);
+	assert.equal(
+		modelRoutingLine({ provider: "odd", id: "thirds" }, { provider: "odd", id: "seven" }, lookup),
+		"Model routing: orchestrator odd/thirds costs 1.3x the worker odd/seven (input 1.3x, output 1.3x).",
+	);
+	assert.equal(renderModelRoutingLine({ kind: "known", orchestrator: "a/x", worker: "b/y", input: 2.95, output: 1.04, blended: 2.95 }),
+		"Model routing: orchestrator a/x costs 3.0x the worker b/y (input 3.0x, output 1.0x).");
+});
+
+test("a provider-less model reference renders its bare id", () => {
+	const bare: ModelPriceLookup = (model) => (model.id === "opus" ? catalog["anthropic/opus"] : undefined);
+	assert.equal(
+		modelRoutingLine({ provider: undefined, id: "opus" }, { provider: undefined, id: "opus" }, bare),
+		"Model routing: orchestrator opus costs 1.0x the worker opus (input 1.0x, output 1.0x).",
+	);
+});
+
+test("a missing orchestrator or worker model renders the unknown line", () => {
+	assert.equal(modelRoutingLine(undefined, opus, lookup), "Model routing: price ratio unknown (orchestrator model unknown).");
+	assert.equal(modelRoutingLine(fable, undefined, lookup), "Model routing: price ratio unknown (worker model unknown).");
+});
+
+test("a missing catalog price renders the unknown line naming the model", () => {
+	assert.equal(
+		modelRoutingLine(fable, { provider: "x", id: "unpriced" }, lookup),
+		"Model routing: price ratio unknown (no catalog price for x/unpriced).",
+	);
+	assert.equal(
+		modelRoutingLine({ provider: "x", id: "unpriced" }, opus, lookup),
+		"Model routing: price ratio unknown (no catalog price for x/unpriced).",
+	);
+});
+
+test("a zero or invalid input or output price renders the unknown line", () => {
+	assert.equal(
+		modelRoutingLine(fable, { provider: "local", id: "free" }, lookup),
+		"Model routing: price ratio unknown (zero or invalid price for local/free).",
+	);
+	assert.equal(
+		modelRoutingLine({ provider: "local", id: "free" }, opus, lookup),
+		"Model routing: price ratio unknown (zero or invalid price for local/free).",
+	);
+	const broken: ModelPriceLookup = (model) => (model.id === "opus" ? { input: Number.NaN, output: 25, cacheRead: 0, cacheWrite: 0 } : catalog["anthropic/fable"]);
+	assert.equal(modelRoutingLine(fable, opus, broken), "Model routing: price ratio unknown (zero or invalid price for anthropic/opus).");
+	const negative: ModelPriceLookup = (model) => (model.id === "opus" ? { input: 5, output: -1, cacheRead: 0, cacheWrite: 0 } : catalog["anthropic/fable"]);
+	assert.equal(modelRoutingLine(fable, opus, negative), "Model routing: price ratio unknown (zero or invalid price for anthropic/opus).");
+});
+
+test("a throwing price lookup never throws and renders the unknown line", () => {
+	const throwing: ModelPriceLookup = () => {
+		throw new Error("registry offline");
+	};
+	assert.equal(modelRoutingLine(fable, opus, throwing), "Model routing: price ratio unknown (price lookup failed).");
+});