gentle-pi 2.1.2 → 2.3.0

package/runtime/review-relay-contract.mjs

@@ -0,0 +1,17 @@
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
+// gentle-pi.review-relay/v1 — the Pi host relay handshake (gentle-pi#311 P4,
+// provider side gentle-ai#3249/#3254).
+//
+// gentle-ai admits `pi` as a host-mediated runtime identity only when the
+// launcher that relays the invocation declares this exact contract through
+// this exact environment variable. Any other value (or none) keeps Pi
+// fail-closed at admission, before any repository, target, or authority work.
+// That refusal is correct provider behavior and is never worked around here;
+// the single central gentle-ai process runner injects this declaration on
+// every invocation the extension makes.
+//
+// Both values are compiled constants: the contract identity is versioned by
+// release, never by configuration.
+
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV = "GENTLE_PI_REVIEW_RELAY_CONTRACT";
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT = "gentle-pi.review-relay/v1";

package/scripts/{build-git-commit-transaction-runner.mjs → build-runtime-modules.mjs}

@@ -8,11 +8,11 @@ import { fileURLToPath } from "node:url";
 const root = fileURLToPath(new URL("..", import.meta.url));
 const sources = [
 	"gentle-ai-binary",
+	"review-relay-contract",
 	"review-integration-v2",
 	"native-review-cli",
-	"git-commit-transaction",
 ];
-const header = "// Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.\n";
+const header = "// Generated by scripts/build-runtime-modules.mjs. Do not edit.\n";
 
 function assertNoTrailingWhitespace(content, label) {
 	const line = content.split("\n").findIndex((value) => /[ \t]+$/.test(value));
@@ -34,7 +34,7 @@ async function generatedBytes(name) {
 async function main() {
 	const mode = process.argv[2];
 	if ((mode !== "--write" && mode !== "--check") || process.argv.length !== 3) {
-		throw new Error("usage: build-git-commit-transaction-runner.mjs --write|--check");
+		throw new Error("usage: build-runtime-modules.mjs --write|--check");
 	}
 	const runtime = join(root, "runtime");
 	if (mode === "--write") await mkdir(runtime, { recursive: true });
@@ -55,9 +55,9 @@ async function main() {
 		if (actual !== expected) drift.push(destination);
 	}
 	if (drift.length > 0) {
-		throw new Error(`generated commit transaction runtime is stale: ${drift.join(", ")}`);
+		throw new Error(`generated runtime is stale: ${drift.join(", ")}`);
 	}
-	process.stdout.write(`commit transaction runtime ${mode === "--write" ? "generated" : "matches TypeScript sources"} (${sources.length} modules)\n`);
+	process.stdout.write(`runtime ${mode === "--write" ? "generated" : "matches TypeScript sources"} (${sources.length} modules)\n`);
 }
 
 main().catch((error) => {

package/scripts/check-provider-contract.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Offline drift check for the mirrored gentle-ai provider contract bundle
+// (gentle-pi#311 P2).
+//
+// Fails when the mirror, the lock record, the schemas, the vectors, or the
+// generated consumer baselines disagree in any direction. Runs completely
+// offline against `contracts/review-provider-contract-mirror/` and never
+// touches the network or the Gentle AI release pin.
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+	generateProviderContractBaselines,
+	piRuntimeRegistration,
+	verifyProviderContractBundleTree,
+} from "../lib/provider-contract-bundle.ts";
+import {
+	PROVIDER_CONTRACT_ACQUISITION,
+	PROVIDER_CONTRACT_LOCK_FILE,
+	PROVIDER_CONTRACT_LOCK_SCHEMA,
+	PROVIDER_CONTRACT_MIRROR_ROOT,
+} from "./mirror-provider-contract.mjs";
+
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function recordEquals(problems, label, expected, actual) {
+	const expectedKeys = Object.keys(expected).sort();
+	const actualKeys = Object.keys(actual).sort();
+	for (const key of expectedKeys) {
+		if (!(key in actual)) problems.push(`${label}: ${key} is recorded in the lock but absent from the mirror`);
+		else if (actual[key] !== expected[key]) problems.push(`${label}: ${key} drifted (lock ${expected[key]}, mirror ${actual[key]})`);
+	}
+	for (const key of actualKeys) {
+		if (!(key in expected)) problems.push(`${label}: ${key} exists in the mirror but is not recorded in the lock`);
+	}
+}
+
+// Returns a list of drift problems; an empty list means the mirror, lock,
+// schemas, vectors, and generated baselines all agree.
+export function checkProviderContractMirror(packageRoot) {
+	const problems = [];
+	const mirrorRoot = join(packageRoot, ...PROVIDER_CONTRACT_MIRROR_ROOT.split("/"));
+	const lockPath = join(mirrorRoot, PROVIDER_CONTRACT_LOCK_FILE);
+	if (!existsSync(lockPath)) {
+		return [`${PROVIDER_CONTRACT_MIRROR_ROOT}/${PROVIDER_CONTRACT_LOCK_FILE} is missing; run scripts/mirror-provider-contract.mjs against a verified local bundle`];
+	}
+
+	let lock;
+	try {
+		lock = JSON.parse(readFileSync(lockPath, "utf8"));
+	} catch (error) {
+		return [`lock record is not valid JSON: ${error instanceof Error ? error.message : String(error)}`];
+	}
+	if (lock === null || typeof lock !== "object" || Array.isArray(lock)) return ["lock record is not a JSON object"];
+	if (lock.schema !== PROVIDER_CONTRACT_LOCK_SCHEMA) problems.push(`lock schema is ${JSON.stringify(lock.schema)}; expected ${JSON.stringify(PROVIDER_CONTRACT_LOCK_SCHEMA)}`);
+	if (lock.acquisition !== PROVIDER_CONTRACT_ACQUISITION) problems.push(`lock acquisition is ${JSON.stringify(lock.acquisition)}; expected ${JSON.stringify(PROVIDER_CONTRACT_ACQUISITION)}`);
+	if (typeof lock.contract_semver !== "string") return [...problems, "lock contract_semver is not a string"];
+	if (lock.pi_registered !== true) problems.push("lock does not record pi as a registered runtime identity");
+
+	// The mirror directory must contain exactly the lock and the locked version.
+	const expectedVersionDirectory = `v${lock.contract_semver}`;
+	for (const entry of readdirSync(mirrorRoot)) {
+		if (entry !== PROVIDER_CONTRACT_LOCK_FILE && entry !== expectedVersionDirectory) {
+			problems.push(`mirror has unexpected entry ${JSON.stringify(entry)}; only ${PROVIDER_CONTRACT_LOCK_FILE} and ${expectedVersionDirectory} belong there`);
+		}
+	}
+
+	const versionRoot = join(mirrorRoot, expectedVersionDirectory);
+	let bundle;
+	try {
+		bundle = verifyProviderContractBundleTree(join(versionRoot, "bundle"));
+	} catch (error) {
+		return [...problems, `mirrored bundle failed verification: ${error instanceof Error ? error.message : String(error)}`];
+	}
+
+	if (bundle.contractSemver !== lock.contract_semver) {
+		problems.push(`mirrored bundle declares contract ${bundle.contractSemver}; lock records ${lock.contract_semver}`);
+	}
+	if (bundle.treeSha256 !== lock.tree_sha256) {
+		problems.push(`mirrored bundle tree digest ${bundle.treeSha256} does not match lock tree_sha256 ${lock.tree_sha256}`);
+	}
+	recordEquals(problems, "bundle entries", lock.entries ?? {}, Object.fromEntries(bundle.entrySha256));
+	const lockRuntimes = Array.isArray(lock.runtimes) ? lock.runtimes : [];
+	const bundleRuntimes = [...(bundle.runtimes ?? [])];
+	if (JSON.stringify(lockRuntimes) !== JSON.stringify(bundleRuntimes)) {
+		problems.push(`lock runtimes ${JSON.stringify(lockRuntimes)} do not match mirrored manifest runtimes ${JSON.stringify(bundleRuntimes)}`);
+	}
+	if (!piRuntimeRegistration(bundle).registered) {
+		problems.push("mirrored bundle does not register the pi runtime identity");
+	}
+
+	// Regenerate the consumer contract surface from the verified mirror and
+	// require byte-identical generated files plus matching lock digests.
+	const baselines = generateProviderContractBaselines(bundle);
+	const generatedRoot = join(versionRoot, "generated");
+	const onDisk = existsSync(generatedRoot) ? readdirSync(generatedRoot).sort() : [];
+	const expectedGenerated = [...baselines.keys()].sort();
+	for (const name of onDisk) {
+		if (!baselines.has(name)) problems.push(`generated/${name} exists on disk but is not a generated provider baseline`);
+	}
+	const actualGeneratedSha256 = {};
+	for (const name of expectedGenerated) {
+		const path = join(generatedRoot, name);
+		if (!existsSync(path)) {
+			problems.push(`generated/${name} is missing from the mirror`);
+			continue;
+		}
+		const actual = readFileSync(path);
+		const expected = Buffer.from(baselines.get(name), "utf8");
+		if (!actual.equals(expected)) problems.push(`generated/${name} is not byte-identical to the baseline derived from the verified mirror`);
+		actualGeneratedSha256[`generated/${name}`] = sha256Hex(actual);
+	}
+	recordEquals(problems, "generated baselines", lock.generated ?? {}, actualGeneratedSha256);
+
+	return problems;
+}
+
+async function main() {
+	const packageRoot = join(fileURLToPath(new URL("..", import.meta.url)));
+	const problems = checkProviderContractMirror(packageRoot);
+	if (problems.length > 0) {
+		console.error("gentle-pi provider contract mirror has drifted:");
+		for (const problem of problems) console.error(`- ${problem}`);
+		console.error("\nRe-run scripts/mirror-provider-contract.mjs against a verified local bundle, or restore the mirrored bytes.");
+		process.exit(1);
+	}
+	const lock = JSON.parse(readFileSync(join(packageRoot, ...PROVIDER_CONTRACT_MIRROR_ROOT.split("/"), PROVIDER_CONTRACT_LOCK_FILE), "utf8"));
+	console.log(`gentle-pi provider contract mirror check passed (contract ${lock.contract_semver}, ${Object.keys(lock.entries).length} bundle entries, ${Object.keys(lock.generated).length} generated baselines, acquisition ${lock.acquisition}).`);
+}
+
+const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+	await main();
+}

package/scripts/gentle-ai-installer.mjs

@@ -19,24 +19,36 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
-const RELEASE_BASE_URL = "https://github.com/Gentleman-Programming/gentle-ai/releases/download/v2.2.2/";
 const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
 const MAX_REDIRECTS = 3;
 const DOWNLOAD_TIMEOUTS = { headers: 10_000, body: 30_000, attempts: 2, retryDelay: 100 };
 const GO_COMMAND_TIMEOUT_MS = 120_000;
+// `go install` compiles the pinned module from source on Windows. A clean
+// build on a cold module cache measured about 232 s (#400), so the 120 s
+// probe bound killed a healthy build; fifteen minutes leaves close to a 4x
+// margin for slower disks and real-time scanners while still bounding a hung
+// toolchain. The `go version` and `where.exe` probes keep the 120 s bound.
+const GO_INSTALL_TIMEOUT_MS = 15 * 60_000;
 const GO_COMMAND_MAX_BUFFER = 1024 * 1024;
 const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
-export const INSTALLER_VERSION = "2.2.2";
+// The one authoritative pinned Gentle AI version. Every other location in this
+// module (the release download URL, the Windows source tag, and the reported
+// version check below) derives from this constant instead of repeating the
+// literal, so a pin bump cannot leave a stale copy behind. See
+// scripts/install-gentle-ai.mjs for the incident that motivated this.
+export const INSTALLER_VERSION = "2.5.0";
+export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
 	GO_SUMDB_SOURCE_BUILD: "go-sumdb-source-build",
 });
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v2";
-export const GENTLE_AI_WINDOWS_SOURCE_TAG = "v2.2.2";
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.2.2`
-// with GOSUMDB=sum.golang.org reports this exact module SumDB checksum.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:YZcI5dRvoHm82I2CULvgBkB2M3UQQGarYO/u/Nt5LSc=";
+export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.5.0`
+// with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
+// tag resolves to commit f5dd1a6c, the published v2.5.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0nvTLJFAf9ruBDwTvi+aDrWt/dt/GKvUP2cFVB6c2DI=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -55,28 +67,73 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v2.2.2 digests are pinned from the published release:
+// still holds it. The v2.5.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
 export const GENTLE_AI_PENDING_DIGEST = "PENDING-GENTLE-AI-RELEASE-DIGEST";
 
+// A raw prerelease asset is less durable than a signed stable archive, and the
+// install path has no other Darwin/Linux source, so the gentle-pi repository
+// hosts a byte-identical mirror of the pinned prerelease assets under its own
+// release tag. The mirror is only a second download source: every byte from
+// either source must still match the same pinned SHA-256 digests, and a
+// checksum mismatch never falls through to the other source.
+export const GENTLE_AI_MIRROR_RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-pi/releases/download/gentle-ai-mirror-v${INSTALLER_VERSION}/`;
+export const GENTLE_AI_ASSET_UNAVAILABLE_CODE = "GENTLE_AI_ASSET_UNAVAILABLE";
+
 function asset(name, sha256, binarySha256, executable) {
-	return Object.freeze({ name, sha256, binarySha256, executable, url: `${RELEASE_BASE_URL}${name}` });
+	const mirrorUrl = INSTALLER_VERSION.includes("-") ? `${GENTLE_AI_MIRROR_RELEASE_BASE_URL}${name}` : undefined;
+	return Object.freeze({ name, sha256, binarySha256, executable, url: `${RELEASE_BASE_URL}${name}`, ...(mirrorUrl === undefined ? {} : { mirrorUrl }) });
+}
+
+// Download failure (not integrity failure) is the only condition that falls
+// through to the mirror; when both sources are unavailable the error names the
+// documented recovery instead of leaving a dead end until the next repin.
+async function downloadPinnedGentleAiAsset(asset, destination, options) {
+	const download = options.download ?? downloadGentleAiAsset;
+	try {
+		await download(asset.url, destination);
+	} catch (primaryError) {
+		if (asset.mirrorUrl === undefined) throw primaryError;
+		try {
+			await download(asset.mirrorUrl, destination);
+		} catch (mirrorError) {
+			throw new GentleAiInstallerError(
+				GENTLE_AI_ASSET_UNAVAILABLE_CODE,
+				`Gentle AI ${asset.name} is unavailable from the pinned release and its gentle-pi mirror. Retry later, or set GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1 and register a locally built v${INSTALLER_VERSION} binary through ~/.pi/gentle-ai/dev-binary.json.`,
+				mirrorError,
+			);
+		}
+	}
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v2.2.2 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v2.5.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_2.2.2_darwin_amd64.tar.gz", "5ca67829903bf4c6b14665664f80f9d8216c84b10c8e50870d297f452cefb9dc", "9b239423450562d026384f482bbd2f1e3f2820431a84f0921743ac3df9d632de", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_2.2.2_darwin_arm64.tar.gz", "0193e1a284444dccee2863d31b8dbb76a982e8f9111955908d6a9131c1a5490e", "149b97248552c5e03ebc4d991f86b1360fb847a40fc315555a8aa256f95baca0", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_2.2.2_linux_amd64.tar.gz", "b85bbb20eb2236de97b261df16cfc8d8394dfd07a137e885c4889b62d0c20fa1", "00d5732e8dd3945956800217a4f60213c2d9ca63351092a2cb7f4e5f9ece54f9", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_2.2.2_linux_arm64.tar.gz", "61e7077342448273f0c43af49ce4d182594bab5e4f86f812975af2fbe69e3b0b", "a92685aa7dbea0cc4297d016569b3defe9bb30a7374a620021e245b74f50eb68", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_2.5.0_darwin_amd64.tar.gz", "8204ed692d7ff16fae2eb8bd7b3132b5e4e4dd7b9ea40e93bfced57394da27c0", "929817d320e94ad62be7ed546ad8746e62bd63ab97e3f38c94456f221f163eca", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_2.5.0_darwin_arm64.tar.gz", "ce06831cea9fd2ac7b2b36d9e98e63988246e0fbafbbd2cc7c003ec2f1463a23", "c859cd88138eb41e83ef9b75309697aaff2acb9f720c9a029b432095f66aea02", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_2.5.0_linux_amd64.tar.gz", "2ba84a3a7ba2b1193019bde2acb05b02cbf222b667568c919686352b3caab113", "5acedd14b7927a7665636bf728c14a614597ce85dd91313bc50cbc96881c6cab", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_2.5.0_linux_arm64.tar.gz", "16a6243d17c146e3fc0024f6f005c5bd141fbb2dda4b56e269318e499ddc170b", "ce75ba1174955813ef462f4e7a50dd59a8e8167575033f6e17aa8d8488630cb8", "gentle-ai"),
 });
 
+// A pinned asset is either a signed archive or, for a prerelease pin only,
+// the raw executable itself: prereleases are hand-built and ship raw binaries,
+// while every stable release publishes signed archives, so a raw asset under a
+// stable pin means the pin itself is wrong. Anything else fails closed before
+// a byte is downloaded.
+export function gentleAiAssetForm(name, installerVersion = INSTALLER_VERSION) {
+	if (name.endsWith(".tar.gz") || name.endsWith(".zip")) return "archive";
+	if (/^gentle-ai_[0-9A-Za-z.+~-]+_(darwin|linux|windows)_(amd64|arm64)(\.exe)?$/.test(name)) {
+		if (!installerVersion.includes("-")) throw new Error(`raw Gentle AI release asset ${name} is only admitted for a prerelease pin; stable pin ${installerVersion} requires a signed archive`);
+		return "raw-binary";
+	}
+	throw new Error(`unsupported Gentle AI release asset form: ${name}`);
+}
+
 function upstreamArchitecture(architecture) {
 	return architecture === "x64" ? "amd64" : architecture;
 }
@@ -96,7 +153,7 @@ export function resolveGentleAiReleaseAsset(platform = process.platform, archite
 		const windowsSource = isWindowsGoSumdbSourceTarget(platform, architecture)
 			? "; Windows x64/arm64 use Go SumDB source installation because no signed Windows archive is published"
 			: "";
-		throw new Error(`unsupported Gentle AI platform/architecture: ${platform}/${architecture}; signed archive pairs are darwin/x64, darwin/arm64, linux/x64, and linux/arm64${windowsSource}`);
+		throw new Error(`unsupported Gentle AI platform/architecture: ${platform}/${architecture}; pinned release asset pairs are darwin/x64, darwin/arm64, linux/x64, and linux/arm64${windowsSource}`);
 	}
 	return resolved;
 }
@@ -241,8 +298,8 @@ function isCanonicalManifest(contents, parsed, expected) {
 
 function commandOutput(result) { return typeof result?.stdout === "string" ? result.stdout : ""; }
 
-function commandOptions(env, cwd) {
-	return { cwd, env, shell: false, windowsHide: true, timeout: GO_COMMAND_TIMEOUT_MS, maxBuffer: GO_COMMAND_MAX_BUFFER };
+function commandOptions(env, cwd, timeout = GO_COMMAND_TIMEOUT_MS) {
+	return { cwd, env, shell: false, windowsHide: true, timeout, maxBuffer: GO_COMMAND_MAX_BUFFER };
 }
 
 function outputVersion(output) {
@@ -330,11 +387,13 @@ async function verifyGoBuildMetadata(execute, goPath, binaryPath, environment, c
 	catch (error) { if (error instanceof GentleAiInstallerError) throw error; throw new GentleAiInstallerError(GENTLE_AI_GO_INSTALL_FAILED_CODE, "Gentle AI source build metadata could not be verified.", error); }
 }
 
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
 async function assertExactGentleAiVersion(execute, binaryPath, environment, cwd) {
 	let result;
 	try { result = await runCommand(execute, binaryPath, ["version"], commandOptions(environment, cwd)); }
 	catch (error) { throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build at ${binaryPath} could not report its version.`, error); }
-	if (!/^gentle-ai 2\.2\.2\r?\n?$/.test(commandOutput(result))) throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build reported ${JSON.stringify(commandOutput(result).trim())}; expected gentle-ai ${INSTALLER_VERSION}.`);
+	if (!new RegExp(`^gentle-ai ${escapeRegExp(INSTALLER_VERSION)}\\r?\\n?$`).test(commandOutput(result))) throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build reported ${JSON.stringify(commandOutput(result).trim())}; expected gentle-ai ${INSTALLER_VERSION}.`);
 }
 
 function sameFile(before, after) { return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs; }
@@ -574,7 +633,7 @@ async function installWindowsGentleAiFromGoSumdb(options, packageRoot, architect
 			const existing = versionBundlePath(runtimeRoot);
 			if (await existingWindowsSourceBundleMatches(existing, execute, goPath, environment, architecture)) return { installed: false, binaryPath: join(existing, "gentle-ai.exe"), method: GENTLE_AI_INSTALL_METHOD.GO_SUMDB_SOURCE_BUILD };
 			await assertGoToolchain(execute, goPath, environment, stagingDirectory);
-			try { await runCommand(execute, goPath, ["install", GENTLE_AI_WINDOWS_SOURCE_PACKAGE], commandOptions(environment, stagingDirectory)); }
+			try { await runCommand(execute, goPath, ["install", GENTLE_AI_WINDOWS_SOURCE_PACKAGE], commandOptions(environment, stagingDirectory, GO_INSTALL_TIMEOUT_MS)); }
 			catch (error) { throw new GentleAiInstallerError(GENTLE_AI_GO_INSTALL_FAILED_CODE, `Gentle AI Go SumDB source installation failed for ${GENTLE_AI_WINDOWS_SOURCE_PACKAGE}.`, error); }
 			const builtBinary = join(environment.GOBIN, "gentle-ai.exe"), binaryPath = join(stagingDirectory, "gentle-ai.exe");
 			const details = await lstat(builtBinary);
@@ -599,18 +658,22 @@ async function installSignedRelease(options, packageRoot, platform, arch, asset)
 		if (await existingSignedBundleMatches(existing, asset, platform)) return { installed: false, binaryPath: join(existing, asset.executable), asset };
 		const stagingDirectory = await mkdtemp(join(runtimeRoot, `.v${INSTALLER_VERSION}.staging-`));
 		try {
+			const form = gentleAiAssetForm(asset.name);
 			const archive = join(stagingDirectory, asset.name);
-			await (options.download ?? downloadGentleAiAsset)(asset.url, archive);
+			await downloadPinnedGentleAiAsset(asset, archive, options);
 			if ((await sha256File(archive)) !== asset.sha256) throw new Error(`Gentle AI archive checksum mismatch for ${asset.name}`);
+			let source = archive;
 			const extracted = join(stagingDirectory, "extracted");
-			await (options.extractArchive ?? extractGentleAiArchive)(archive, extracted);
-			const source = await expectedRegularFile(extracted, asset.executable);
+			if (form === "archive") {
+				await (options.extractArchive ?? extractGentleAiArchive)(archive, extracted);
+				source = await expectedRegularFile(extracted, asset.executable);
+			}
 			if (asset.binarySha256 && (await sha256File(source)) !== asset.binarySha256) throw new Error(`Gentle AI binary checksum mismatch for ${asset.name}`);
 			const binaryPath = join(stagingDirectory, asset.executable);
 			await copyFile(source, binaryPath);
 			if (platform !== "win32") await chmod(binaryPath, 0o700);
 			await writeFile(join(stagingDirectory, "integrity.json"), canonicalManifest(signedReleaseManifest(asset, await sha256File(binaryPath))), { mode: 0o600 });
-			await safeRemoveDirectory(extracted);
+			if (form === "archive") await safeRemoveDirectory(extracted);
 			await rm(archive, { force: true });
 			const published = await publishBundle(runtimeRoot, stagingDirectory, options);
 			return { installed: true, binaryPath: join(published, asset.executable), asset };