gentle-pi 2.2.0 → 2.3.0

package/runtime/review-relay-contract.mjs

@@ -1,4 +1,4 @@
-// Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.
+// 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).
 //

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

@@ -11,9 +11,8 @@ const sources = [
 	"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));
@@ -35,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 });
@@ -56,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/gentle-ai-installer.mjs

@@ -23,6 +23,12 @@ 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";
 // The one authoritative pinned Gentle AI version. Every other location in this
@@ -30,7 +36,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // 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.4.0";
+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",
@@ -39,12 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 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 = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.4.0`
-// with GOSUMDB=sum.golang.org reports this exact module SumDB checksum. The
-// same response resolves the tag to commit 301fb2ad, which is also the
-// `vcs_revision` the published v2.4.0 binary self-reports in its capabilities
-// envelope -- the two independent provenance paths agree.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:XKkcy+t76cyUKQnRwL1UnqHbhh8o416I8HQ1UsdvWSI=";
+// `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";
@@ -63,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.4.0 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.4.0 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.4.0_darwin_amd64.tar.gz", "c3f5a4251e927c41864e7a9a5670ac3fce97c6282755ec8e9b2e7e064067f750", "c4d25b98bae0d06b33baa23ba997cb64ab63c2e93e97983bcb9c239139bceaba", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_2.4.0_darwin_arm64.tar.gz", "2240ae797119dd1dc5a0dd2fd2711077ce6712e66ab0b67461344c983478f7f4", "54a8a5957ce4f10f36b46ef818c888f484a3e213a71faca6b7783af6c029eb77", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_2.4.0_linux_amd64.tar.gz", "517eb8420cf966b74be1413a7ea1036119a5ccbb376e0778aa9f4d4d283e2e9a", "0be446737f8f1a9458fd2891d488beb2d72786578afead9bbf2d6ddddc9ec113", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_2.4.0_linux_arm64.tar.gz", "1badec9cad1f2bbeb22b5c6804c3a88c601d844abae231264e416e8095f2a15f", "cdd8fa43c3417e844cc11d2e436d4667edb0a54f086e0eb1d6cd3f7493bfee5a", "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;
 }
@@ -104,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;
 }
@@ -249,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) {
@@ -584,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);
@@ -609,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 };

package/scripts/maintainer/provider-relay-matrix.mjs

@@ -9,12 +9,55 @@
 // `pnpm test` never imports it; `pnpm run test:maintainer` runs the tests;
 // the CLI is the entry point the separate verifier uses for the real organic
 // positive journey after a user-visible forecast.
+import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { isAbsolute, join } from "node:path";
-import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, resolveReviewHostRelaySubmission, runReviewHostRelaySlot } from "../../lib/review-host-relay.ts";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, classifyReviewHostRelayRefusal, resolveReviewHostRelaySubmission, runReviewHostRelaySlot } from "../../lib/review-host-relay.ts";
+import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "../../lib/review-relay-contract.ts";
 export const DESCRIPTOR_SCHEMA = "gentle-pi.maintainer.provider-relay-descriptor/v1";
-export const CASE_KINDS = Object.freeze(["relay-unavailable", "positive-lens"]);
+export const PROVIDER_ROLE_VECTOR_KINDS = Object.freeze(["provider-role-refuter", "provider-role-validator"]);
+export const CASE_KINDS = Object.freeze(["relay-unavailable", "positive-lens", ...PROVIDER_ROLE_VECTOR_KINDS]);
+export const PROVIDER_ROLE_VECTOR_VERB = Object.freeze({ "provider-role-refuter": "capture-refuter", "provider-role-validator": "capture-validation" });
+export const PROVIDER_ROLE_VECTOR_ROLE = Object.freeze({ "provider-role-refuter": "refuter", "provider-role-validator": "targeted-validator" });
+export const PROVIDER_ROLE_CAPTURE_ARTIFACT_SCHEMA = "gentle-ai.review-provider-role-capture/v1";
+export const ROLE_STREAM_MAX_BYTES = 1024 * 1024;
+export const ROLE_VECTOR_FAILURE = Object.freeze({
+	ROLE_SURFACE_UNAVAILABLE: "role-surface-unavailable",
+	ROLE_LAUNCH_FAILED: "role-launch-failed",
+	ROLE_FAILED: "role-failed",
+	ROLE_TIMED_OUT: "role-timed-out",
+	ROLE_OUTPUT_OVERFLOW: "role-output-overflow",
+	ROLE_TERMINATION_FAILED: "role-termination-failed",
+	ROLE_ABORTED: "role-aborted",
+	EMPTY_ARTIFACT: "empty-artifact",
+	HANDSHAKE_REFUSED: "handshake-refused",
+});
+const REQUEST_HASH_RE = /^sha256:[0-9a-f]{64}$/;
+const RCTX_RE = /^rctx1_[0-9a-f]{64}$/;
+// Provider-returned lineage and target bindings are the sole authority and must be unique.
+const ROLE_BINDING_RE = Object.freeze({ "--lineage=": /^.+$/, "--expected-revision=": REQUEST_HASH_RE, "--target=": REQUEST_HASH_RE, "--repository-context=": RCTX_RE });
+// The 900s watchdog FIRES after the provider-owned 600s deadline and leaves setup/cancellation margin.
+export const DEFAULT_ROLE_VECTOR_TIMEOUT_MS = 900_000;
+export class ProviderRoleVectorError extends Error {
+	kind;
+	stage;
+	exitCode;
+	stderr;
+	timedOut;
+	mutationOutcome;
+	// Unreadable outcomes after launch are unknown and require STATUS re-query.
+	constructor(kind, stage, message, details) {
+		super(message);
+		this.name = "ProviderRoleVectorError";
+		this.kind = kind;
+		this.stage = stage;
+		this.exitCode = details?.exitCode ?? null;
+		this.stderr = details?.stderr ?? "";
+		this.timedOut = details?.timedOut ?? false;
+		this.mutationOutcome = details?.mutationOutcome ?? (kind === ROLE_VECTOR_FAILURE.ROLE_FAILED || kind === ROLE_VECTOR_FAILURE.ROLE_TIMED_OUT || kind === ROLE_VECTOR_FAILURE.ROLE_OUTPUT_OVERFLOW ? "unknown" : "none");
+	}
+}
 // The positive lens runs only when explicitly armed: the organic journey
 // needs a real capable binary, a real pi, and a real review session. Without
 // the arm the runner blocks the positive leg before materialize.
@@ -53,11 +96,14 @@ export function validateDescriptor(value) {
 	const seen = new Set();
 	return { schema: value.schema, gentleAiExecutable: value.gentleAiExecutable, piExecutable: value.piExecutable, cases: value.cases.map((entry, index) => {
 			if (!isObj(entry)) fail(`descriptor.cases[${index}] must be an object`);
-			exactKeys(entry, new Set(["name", "kind", "captureArgumentTokens", "submission"]), `descriptor.cases[${index}]`);
 			if (!isStr(entry.name)) fail(`descriptor.cases[${index}].name must be a non-empty string`);
 			if (seen.has(entry.name)) fail(`descriptor.cases[${index}].name "${entry.name}" is duplicated`);
 			seen.add(entry.name);
 			if (!CASE_KINDS.includes(entry.kind)) fail(`descriptor.cases[${index}].kind must be one of ${JSON.stringify([...CASE_KINDS])}`);
+			if (PROVIDER_ROLE_VECTOR_KINDS.includes(entry.kind)) {
+				return validateRoleCaseEntry(entry, index);
+			}
+			exactKeys(entry, new Set(["name", "kind", "captureArgumentTokens", "submission"]), `descriptor.cases[${index}]`);
 			if (!isStrArr(entry.captureArgumentTokens)) fail(`descriptor.cases[${index}].captureArgumentTokens must be a non-empty array of non-empty strings`);
 			// A real host-relay materialize slot is the provider-issued
 			// --agent=pi --materialize=true pair; the descriptor must declare
@@ -93,6 +139,43 @@ export function validateDescriptor(value) {
 		}),
 	};
 }
+// Validates provider-issued role tokens and the validator's minimal request-hash binding.
+function validateRoleCaseEntry(entry, index) {
+	const label = `descriptor.cases[${index}]`;
+	const allowedKeys = new Set(["name", "kind", "argumentTokens", ...(entry.kind === "provider-role-validator" ? ["validationRequest"] : [])]);
+	exactKeys(entry, allowedKeys, label);
+	if (!isStrArr(entry.argumentTokens)) fail(`${label}.argumentTokens must be a non-empty array of non-empty strings`);
+	// Each self-contained execute control must appear exactly once at its exact value.
+	for (const required of ["--agent=pi", "--execute=true"]) {
+		const prefix = `${required.slice(0, required.indexOf("=") + 1)}`;
+		const matches = entry.argumentTokens.filter((token) => token.startsWith(prefix));
+		if (matches.length !== 1 || matches[0] !== required) fail(`${label}.argumentTokens must include exactly one provider-issued "${required}" token`);
+	}
+	if (entry.argumentTokens.includes("--materialize=true")) {
+		fail(`${label}.argumentTokens must not include --materialize=true; a role vector is self-contained, never a lens materialize slot`);
+	}
+	const bindings = {};
+	for (const [prefix, pattern] of Object.entries(ROLE_BINDING_RE)) {
+		const matches = entry.argumentTokens.filter((t) => t.startsWith(prefix));
+		if (matches.length !== 1) fail(`${label}.argumentTokens must include exactly one "${prefix}" token, found ${matches.length}`);
+		const value = matches[0].slice(prefix.length);
+		if (!pattern.test(value)) fail(`${label}.argumentTokens "${prefix}" value is malformed`);
+		bindings[prefix] = value;
+	}
+	const result = { name: entry.name, kind: entry.kind, argumentTokens: [...entry.argumentTokens], lineage: bindings["--lineage="], targetIdentity: bindings["--target="] };
+	if (entry.kind === "provider-role-validator") {
+		const vr = entry.validationRequest;
+		if (!isObj(vr)) fail(`${label}.validationRequest must be an object; the provider-embedded validation_request binding is required on the targeted-validator vector`);
+		exactKeys(vr, new Set(["schema", "requestHash"]), `${label}.validationRequest`);
+		if (vr.schema !== "gentle-ai.review-targeted-validation-request/v1") fail(`${label}.validationRequest.schema must be exactly "gentle-ai.review-targeted-validation-request/v1"`);
+		if (!isStr(vr.requestHash) || !REQUEST_HASH_RE.test(vr.requestHash)) fail(`${label}.validationRequest.requestHash must be a sha256 digest`);
+		const expectedToken = `--request-hash=${vr.requestHash}`;
+		const requestHashTokens = entry.argumentTokens.filter((token) => token.startsWith("--request-hash="));
+		if (requestHashTokens.length !== 1 || requestHashTokens[0] !== expectedToken) fail(`${label}.argumentTokens must include exactly one provider-issued "${expectedToken}" token that binds the embedded validation_request`);
+		result.validationRequest = { schema: vr.schema, requestHash: vr.requestHash };
+	}
+	return Object.freeze(result);
+}
 export function loadDescriptor(path) {
 	if (!isStr(path)) fail("a descriptor path is required");
 	let raw, parsed;
@@ -109,12 +192,14 @@ export function loadDescriptor(path) {
 	return validateDescriptor(parsed);
 }
 // Resolves a declared executable without a shell: absolute path checked
-// verbatim, bare name searched on PATH. Never re-resolves production.
+// verbatim, bare name searched on PATH. Never re-resolves production. PATH
+// matches are normalized to absolute paths (a relative component like `.`
+// must not yield a relative candidate; the relay launches from scratch).
 export function resolveDeclaredExecutable(executable) {
 	if (isAbsolute(executable)) return existsSync(executable) && statSync(executable).isFile() ? executable : null;
-	for (const directory of (process.env.PATH ?? "").split(process.platform === "win32" ? ";" : ":")) {
+	for (const directory of (process.env.PATH ?? "").split(delimiter)) {
 		if (!directory) continue;
-		const candidate = join(directory, executable);
+		const candidate = resolve(directory, executable);
 		if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
 	}
 	return null;
@@ -128,10 +213,76 @@ function unlaunchablePi() {
 	chmodSync(directory, 0o700);
 	return { directory, executable: join(directory, "pi-must-never-launch") };
 }
+function terminateRoleProcessTree(child) {
+	if (child.pid === undefined) return false;
+	if (process.platform === "win32") {
+		try { const result = spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", shell: false, windowsHide: true, timeout: 5_000 }); if (result.error === undefined && result.status === 0) return true; } catch {}
+		child.kill("SIGKILL"); return false;
+	}
+	try { process.kill(-child.pid, "SIGKILL"); return true; } catch (error) { if (error?.code === "ESRCH") return true; child.kill("SIGKILL"); return false; }
+}
+export async function runProviderRoleVector(request) {
+	const verb = PROVIDER_ROLE_VECTOR_VERB[request.kind];
+	if (verb === undefined) throw new TypeError(`runProviderRoleVector received an unknown role vector kind: ${request.kind}`);
+	if (request.signal?.aborted) throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_ABORTED, "launch", "gentle-ai role vector was aborted before launch", { mutationOutcome: "none" });
+	const argv = ["review", verb, ...request.argumentTokens], env = { ...process.env, ...request.env, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT };
+	let capture, launched = false;
+	try {
+		capture = await new Promise((resolve, reject) => {
+			const child = spawn(request.gentleAiExecutable, argv, { cwd: process.cwd(), env, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true, ...(process.platform === "win32" ? {} : { detached: true }) });
+			launched = child.pid !== undefined;
+			const stdout = [], stderr = []; let stdoutBytes = 0, stderrBytes = 0, terminationCause = null, treeTerminationFailed = false, settled = false;
+			const captured = (exitCode) => ({ stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), exitCode, terminationCause, treeTerminationFailed });
+			const collect = (stream, chunks) => (chunk) => { if (terminationCause !== null) return; const bytes = chunk.length; if ((stream === "stdout" ? stdoutBytes : stderrBytes) + bytes > ROLE_STREAM_MAX_BYTES) { terminate(stream); return; } if (stream === "stdout") stdoutBytes += bytes; else stderrBytes += bytes; chunks.push(chunk); };
+			const onStdout = collect("stdout", stdout), onStderr = collect("stderr", stderr);
+			const abort = () => terminate("abort");
+			const cleanup = () => { clearTimeout(timer); request.signal?.removeEventListener("abort", abort); child.stdout.off("data", onStdout); child.stderr.off("data", onStderr); child.off("error", onError); child.off("close", onClose); };
+			const settle = (result) => { if (settled) return; settled = true; cleanup(); resolve(result); };
+			const onError = (error) => { if (terminationCause === null) { if (settled) return; settled = true; cleanup(); reject(error); } else settle(captured(null)); };
+			const onClose = (code) => settle(captured(code));
+			const terminate = (cause) => {
+				if (terminationCause !== null) return;
+				terminationCause = cause;
+				treeTerminationFailed = !(request.terminateProcessTree ?? terminateRoleProcessTree)(child);
+				if (treeTerminationFailed) { child.stdout.destroy(); child.stderr.destroy(); settle(captured(null)); }
+			};
+			child.stdout.on("data", onStdout); child.stderr.on("data", onStderr); child.on("error", onError); child.on("close", onClose);
+			const timer = setTimeout(() => terminate("timeout"), request.timeoutMs ?? DEFAULT_ROLE_VECTOR_TIMEOUT_MS); timer.unref();
+			if (request.signal?.aborted) abort(); else request.signal?.addEventListener("abort", abort, { once: true });
+		});
+	} catch (error) {
+		if (request.signal?.aborted && launched) throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_ABORTED, "execute", "gentle-ai role vector was aborted after launch", { mutationOutcome: "unknown" });
+		throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_LAUNCH_FAILED, "launch", `gentle-ai role vector could not start: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const stderrText = capture.stderr.toString("utf8");
+	if (capture.treeTerminationFailed) throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_TERMINATION_FAILED, "execute", "gentle-ai role vector tree termination could not be confirmed; re-query negotiated STATUS before any retry", { exitCode: capture.exitCode, stderr: stderrText, mutationOutcome: "unknown" });
+	if (capture.terminationCause === "abort") throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_ABORTED, "execute", "gentle-ai role vector was aborted after launch", { exitCode: capture.exitCode, stderr: stderrText, mutationOutcome: "unknown" });
+	if (capture.terminationCause === "stdout" || capture.terminationCause === "stderr") throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_OUTPUT_OVERFLOW, "execute", `gentle-ai role vector ${capture.terminationCause} exceeded the ${ROLE_STREAM_MAX_BYTES}-byte limit; re-query negotiated STATUS before any retry`, { exitCode: capture.exitCode, stderr: stderrText });
+	if (capture.terminationCause === "timeout") throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_TIMED_OUT, "execute", "gentle-ai role vector exceeded its outer watchdog; re-query negotiated STATUS before any retry, and the same transcript must not relaunch blindly", { exitCode: capture.exitCode, stderr: stderrText, timedOut: true });
+	if (capture.exitCode !== 0) {
+		const refusal = classifyReviewHostRelayRefusal(stderrText);
+		if (refusal === "handshake") throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.HANDSHAKE_REFUSED, "execute", stderrText, { exitCode: capture.exitCode, stderr: stderrText });
+		if (refusal === "unknown-flag") throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_SURFACE_UNAVAILABLE, "execute", "the declared gentle-ai binary lacks the provider role capture surface", { exitCode: capture.exitCode, stderr: stderrText });
+		throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_FAILED, "execute", "gentle-ai role vector failed", { exitCode: capture.exitCode, stderr: stderrText });
+	}
+	if (capture.stdout.length === 0) throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.EMPTY_ARTIFACT, "execute", "gentle-ai role vector produced no artifact bytes; re-query negotiated STATUS before any retry", { exitCode: 0, stderr: stderrText, mutationOutcome: "unknown" });
+	let artifact;
+	try { artifact = JSON.parse(capture.stdout.toString("utf8")); } catch (error) { throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_FAILED, "execute", `gentle-ai role vector returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { exitCode: 0, stderr: stderrText }); }
+	const expectedRole = PROVIDER_ROLE_VECTOR_ROLE[request.kind];
+	if (!isObj(artifact) || artifact.schema !== PROVIDER_ROLE_CAPTURE_ARTIFACT_SCHEMA || artifact.role !== expectedRole || artifact.captured !== true || !isStr(artifact.lineage_id) || !REQUEST_HASH_RE.test(artifact.target_identity)) throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_FAILED, "execute", "gentle-ai role vector returned an artifact that does not match the expected typed shape", { exitCode: 0, stderr: stderrText });
+	return { schema: artifact.schema, lineageId: artifact.lineage_id, targetIdentity: artifact.target_identity, role: artifact.role, captured: true };
+}
 // Runs the matrix against the REAL relay. A case that cannot run honestly is
 // `blocked` (never `pass`); `fail` is an armed case whose outcome mismatched.
 export async function runMatrix(descriptor, options = {}) {
 	const positiveArmed = options.armPositive ?? (process.env[ARM_POSITIVE_ENV] === "1");
+	// Smallest test seam: an optional injected relay function. Defaults to
+	// the real relay so production CLI behavior is identical when unset; tests
+	// inject a fake to assert the exact resolved path reaches the boundary
+	// without executing a real subprocess (platform-neutral #324 evidence).
+	const relay = options.relay ?? runReviewHostRelaySlot;
+	// Test seam only; production defaults to the real role runner.
+	const roleRunner = options.roleRunner ?? runProviderRoleVector;
 	const verdicts = [];
 	for (const caseEntry of descriptor.cases) {
 		const gentleAiPath = resolveDeclaredExecutable(descriptor.gentleAiExecutable);
@@ -139,10 +290,43 @@ export async function runMatrix(descriptor, options = {}) {
 			verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: missingReason(descriptor.gentleAiExecutable, "gentleAiExecutable") });
 			continue;
 		}
+		// Self-contained role vectors require explicit arming and a real provider result.
+		if (PROVIDER_ROLE_VECTOR_KINDS.includes(caseEntry.kind)) {
+			if (!positiveArmed) {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: `${caseEntry.kind} case is not explicitly armed; set ${ARM_POSITIVE_ENV}=1 with a real capable gentle-ai binary, a real pi, and a real review session (real binding tokens from \`gentle-ai review status --next-transition\`) to run the organic role vector. The runner never synthesizes a provider verdict.`, command: POSITIVE_JOURNEY_COMMAND });
+				continue;
+			}
+			try {
+				const artifact = await roleRunner({ kind: caseEntry.kind, argumentTokens: caseEntry.argumentTokens, gentleAiExecutable: gentleAiPath, ...(caseEntry.validationRequest === undefined ? {} : { validationRequest: caseEntry.validationRequest }), ...(options.signal === undefined ? {} : { signal: options.signal }) });
+				if (artifact.lineageId !== caseEntry.lineage || artifact.targetIdentity !== caseEntry.targetIdentity) {
+					throw new ProviderRoleVectorError(ROLE_VECTOR_FAILURE.ROLE_FAILED, "execute", `role vector returned a stale artifact: expected lineage=${caseEntry.lineage} target=${caseEntry.targetIdentity}, got lineage=${artifact.lineageId} target=${artifact.targetIdentity}`);
+				}
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "pass", role: artifact.role, lineageId: artifact.lineageId, targetIdentity: artifact.targetIdentity, captured: artifact.captured });
+			} catch (error) {
+				if (error instanceof ProviderRoleVectorError) {
+					if (error.kind === ROLE_VECTOR_FAILURE.HANDSHAKE_REFUSED) {
+						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", stage: error.stage, mutationOutcome: error.mutationOutcome, reason: `the declared gentle-ai binary refused relay-contract negotiation: ${error.message}`, command: POSITIVE_JOURNEY_COMMAND });
+					} else if (error.kind === ROLE_VECTOR_FAILURE.ROLE_SURFACE_UNAVAILABLE) {
+						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", stage: error.stage, mutationOutcome: error.mutationOutcome, reason: `the declared gentle-ai binary lacks the provider role capture surface: ${error.message}`, command: POSITIVE_JOURNEY_COMMAND });
+					} else {
+						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `role vector error kind=${error.kind} stage=${error.stage} mutationOutcome=${error.mutationOutcome}: ${error.message}`, stderr: error.stderr, timedOut: error.timedOut });
+					}
+				} else {
+					verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `unexpected non-role error: ${error instanceof Error ? error.message : String(error)}` });
+				}
+			}
+			continue;
+		}
 		// The positive lens needs a real pi AND an explicit arm; the negative
-		// control never launches pi (fails closed at materialize).
+		// control never launches pi (fails closed at materialize). The precheck
+		// resolves the declared Pi executable ONCE and reuses that exact
+		// concrete path for launch; a bare declaration is never re-resolved
+		// between precheck and spawn, so the relay launches exactly the
+		// executable the harness checked (issue #324).
+		let piPath = null;
 		if (caseEntry.kind === "positive-lens") {
-			if (resolveDeclaredExecutable(descriptor.piExecutable) === null) {
+			piPath = resolveDeclaredExecutable(descriptor.piExecutable);
+			if (piPath === null) {
 				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: missingReason(descriptor.piExecutable, "piExecutable"), command: POSITIVE_JOURNEY_COMMAND });
 				continue;
 			}
@@ -164,9 +348,9 @@ export async function runMatrix(descriptor, options = {}) {
 		// stage as kind=pi-launch-failed stage=pi mutationOutcome=none, with
 		// zero pi launch and zero submission.
 		const negativeControl = caseEntry.kind === "relay-unavailable" ? unlaunchablePi() : null;
-		const request = { captureArgumentTokens: caseEntry.captureArgumentTokens, submission: caseEntry.submission, gentleAiExecutable: gentleAiPath, piExecutable: negativeControl === null ? descriptor.piExecutable : negativeControl.executable, ...(options.signal === undefined ? {} : { signal: options.signal }) };
+		const request = { captureArgumentTokens: caseEntry.captureArgumentTokens, submission: caseEntry.submission, gentleAiExecutable: gentleAiPath, piExecutable: negativeControl === null ? piPath : negativeControl.executable, ...(options.signal === undefined ? {} : { signal: options.signal }) };
 		try {
-			const result = await runReviewHostRelaySlot(request);
+			const result = await relay(request);
 			if (caseEntry.kind === "relay-unavailable") {
 				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: "expected relay-unavailable (runtime without --materialize) but the relay succeeded; the descriptor's binary is unexpectedly capable" });
 			} else {

package/scripts/test-packed-runner.mjs

@@ -50,12 +50,9 @@ try {
 		stdio: "inherit",
 	});
 	const packageRoot = join(installDirectory, "node_modules", "gentle-pi");
-	const runner = join(packageRoot, "scripts", "run-git-commit-transaction.mjs");
-	const result = JSON.parse(execFileSync(process.execPath, [runner, "self-test"], { cwd: installDirectory, encoding: "utf8" }));
-	if (result.schema !== "gentle-pi.git-commit-transaction-runner-self-test/v1" || !Array.isArray(result.states) || !result.states.includes("prepared") || !result.states.includes("committed")) {
-		throw new Error("installed transaction runner self-test returned an incompatible result");
-	}
-	const versions = readdirSync(join(packageRoot, ".gentle-ai"), { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^v\d+\.\d+\.\d+$/.test(entry.name));
+	// Accept prerelease pins too: a stable-only pattern here was a second,
+	// silent pin that refused the first prerelease version directory.
+	const versions = readdirSync(join(packageRoot, ".gentle-ai"), { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.]*)?$/.test(entry.name));
 	if (versions.length !== 1) throw new Error("packed install did not contain exactly one package-local Gentle AI version");
 	const executable = join(packageRoot, ".gentle-ai", versions[0].name, process.platform === "win32" ? "gentle-ai.exe" : "gentle-ai");
 	const capabilities = JSON.parse(execFileSync(executable, ["review", "capabilities", "--contract", "gentle-ai.review-integration/v2"], { cwd: installDirectory, encoding: "utf8" }));
@@ -74,7 +71,7 @@ try {
 	const decoded = decodeReviewCapabilitiesV2(capabilities, executableDigest);
 	if (decoded.contract !== "gentle-ai.review-integration/v2" || decoded.packageVersion !== versions[0].name.slice(1)) throw new Error("package-local Gentle AI returned incompatible capabilities");
 	const packageManifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-	process.stdout.write(`packed runner E2E passed (gentle-pi ${packageManifest.version ?? "unknown"}; Gentle AI ${capabilities.package?.version ?? "unknown"}; ${result.states.length} states)\n`);
+	process.stdout.write(`packed package E2E passed (gentle-pi ${packageManifest.version ?? "unknown"}; Gentle AI ${decoded.packageVersion ?? "unknown"})\n`);
 } finally {
 	rmSync(temporary, { recursive: true, force: true });
 }