gentle-pi 3.2.0 → 3.3.0

package/runtime/review-integration-v2.mjs

@@ -200,6 +200,22 @@ const CAPABILITIES_SCHEMA_IDENTITIES
 		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
 		optionalFeatureFloor: 14,
 	}),
+	// Ground-truthed against the published v3.4.0 binary: capabilities/v2.6
+	// advertises the same required surface as v2.5 (status/v6 is still
+	// advertised for compatibility) plus the status/v7 and status/v8 schemas,
+	// which are superset-checked additions, not requirements --
+	// decodeReviewStatusV3 already accepts v7/v8/v9 as additive extensions of
+	// v6, so the required-schema floor stays unchanged. `review assess` also
+	// gained review_due/review_due_reason/next_transition, which is unrelated
+	// to this negotiated capabilities surface. The v3.4.0 binary advertised
+	// 15 optional features, same as v2.5's binary (floor stays at 14, its
+	// established minimum).
+	"gentle-ai.review-integration.capabilities/v2.6": Object.freeze({
+		protocolMinor: 6,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.6", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v6", "gentle-ai.review-intended-untracked-selection/v1"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
 });
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
 	"base_ref_workspace_overlay",
@@ -439,11 +455,21 @@ const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "
 
 
 
-// The two Go-owned non-lens provider role capture operations (gentle-pi#311
-// P4-roles; provider side gentle-ai#3264). Their collect inputs are
-// self-contained authority-advancing vectors: binding tokens plus
-// `--agent=pi --execute=true`, with NO submission descriptor. The known set
-// is closed — an unknown role capture operation is never executed.
+// The two non-lens provider role capture operations (gentle-pi#311 P4-roles;
+// provider side gentle-ai#3264). An older gentle-ai still renders each one as
+// a self-contained authority-advancing vector: binding tokens plus
+// `--agent=pi --execute=true`, with NO submission descriptor — executing the
+// exact rendered tokens makes Go materialize the role prompt, run its own
+// locked-down pi subprocess, and admit the verdict itself.
+//
+// gentle-ai's v9 contract makes both roles host-mediated exactly like a lens
+// materialize slot instead (gentle-pi#311 P3): the collect input carries
+// `--materialize=true` (never alongside `--execute`) plus a provider-owned
+// `submission` descriptor, and the host completes the frozen prompt
+// in-process and submits the result through that exact descriptor. The two
+// wire forms are mutually exclusive on one input; see the gating in
+// decodeCollectInput below. The known operation set is closed — an unknown
+// role capture operation is never executed either way.
 export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION = {
 	CAPTURE_REFUTER: "review.capture-refuter",
 	CAPTURE_VALIDATION: "review.capture-validation",
@@ -1452,11 +1478,18 @@ function decodeCaptureSubmission(value         , label        , v5         , v6
 	// one-entry values array the host relay already consumes. A payload
 	// carrying both wire forms at once matches no captured shape and falls
 	// through to the legacy decoder, which rejects the unknown `value` key.
+	//
+	// gentle-ai's v9 contract renders the same singular-value shape for the
+	// two host-mediated provider role operations (capture-refuter,
+	// capture-validation): they carry a `schema` key exactly like
+	// capture-result, since both bind one artifact-path-or-stdin value, never
+	// the correction-plan's numeric bounds (gentle-pi#311 P3).
 	if (v5 && typeof value === "object" && value !== null && "value" in value && !("values" in value)) {
 		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
-		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan"]         , `${label}.operation_token`);
+		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan", "capture-refuter", "capture-validation"]         , `${label}.operation_token`);
 		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
-		const row = operationToken === "capture-result"
+		const bindsArtifactSchema = operationToken === "capture-result" || operationToken === "capture-refuter" || operationToken === "capture-validation";
+		const row = bindsArtifactSchema
 			? exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"])
 			: exactRecord(submission.value, `${label}.value`, ["slot", "domain", "minimum", "maximum", "substitution_location"]);
 		return {
@@ -1465,7 +1498,11 @@ function decodeCaptureSubmission(value         , label        , v5         , v6
 			values: [{
 				slot: operationToken === "capture-result"
 					? enumeration(row.slot, ["reviewer_result"]         , `${label}.value.slot`)
-					: enumeration(row.slot, ["correction_lines"]         , `${label}.value.slot`),
+					: operationToken === "capture-correction-plan"
+					? enumeration(row.slot, ["correction_lines"]         , `${label}.value.slot`)
+					: operationToken === "capture-refuter"
+					? enumeration(row.slot, ["provider_refuter"]         , `${label}.value.slot`)
+					: enumeration(row.slot, ["provider_targeted_validator"]         , `${label}.value.slot`),
 				domain: nonempty(row.domain, `${label}.value.domain`),
 				...(row.schema === undefined ? {} : { schema: nonempty(row.schema, `${label}.value.schema`) }),
 				...(row.minimum === undefined ? {} : { minimum: integer(row.minimum, `${label}.value.minimum`, 1, 200) }),
@@ -1606,7 +1643,7 @@ const CORRECTION_REQUEST_REASON_CODES = Object.freeze(["correction_plan_required
 // v5 capture operations that must carry a submission descriptor.
 const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["review.capture-correction-plan"]         );
 
-function decodeCollectInput(value         , label        , v5         , v6         )                       {
+function decodeCollectInput(value         , label        , v5         , v6         , v9         )                       {
 	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "submission", ...(v5 ? ["provider_task", "validation_request"] : [])]);
 	const name = text(input.name, `${label}.name`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const schema = nonempty(input.schema, `${label}.schema`);
@@ -1657,13 +1694,18 @@ function decodeCollectInput(value         , label        , v5         , v6
 		sha256(argumentsList[5] .value, `${label}.arguments[5].value`);
 	}
 
-	// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
-	// operations render SELF-CONTAINED authority-advancing vectors. Executing
+	// gentle-pi#311 P4-roles / P3: the two non-lens provider role capture
+	// operations render either wire form on one input, never both at once.
+	// An older gentle-ai renders a SELF-CONTAINED authority-advancing vector
+	// (binding tokens + --agent=pi --execute=true, no submission): executing
 	// the exact rendered tokens makes Go materialize the role prompt, run its
-	// own locked-down pi subprocess, and admit the raw verdict — so a
-	// submission descriptor (the host-mediated completing form) on one of
-	// these inputs would hand the caller a way to author the verdict and is
-	// rejected as a provider contract violation.
+	// own locked-down pi subprocess, and admit the raw verdict. gentle-ai's
+	// v9 contract instead renders a HOST-MEDIATED form: the same binding
+	// tokens plus --materialize=true (never --execute) and a provider-owned
+	// submission descriptor, exactly like a lens capture-result materialize
+	// slot — the host completes the frozen prompt in-process and submits
+	// through that descriptor.
+	const isRoleCaptureOperation = (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS                     ).includes(captureOperation);
 	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_REFUTER && schema !== "https://gentle-ai.dev/schema/review/refuter/v1") {
 		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/refuter/v1`);
 	}
@@ -1694,8 +1736,30 @@ function decodeCollectInput(value         , label        , v5         , v6
 		if (providerArgument("target") !== validationRequest.correctionTargetIdentity) throw new TypeError(`${label}.arguments target must bind validation_request.correction_target_identity`);
 		if (providerArgument("request-hash") !== validationRequest.requestHash) throw new TypeError(`${label}.arguments request-hash must bind validation_request.request_hash`);
 	}
-	if (input.submission !== undefined && (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS                     ).includes(captureOperation)) {
-		throw new TypeError(`${label}.submission is not allowed on the self-contained ${captureOperation} vector`);
+	if (isRoleCaptureOperation && input.submission !== undefined) {
+		// A submission descriptor only ever rides the v9 host-mediated form
+		// (gentle-ai's v9 provider contract; the sibling branch ahead of the
+		// currently-released v8). A v8-or-earlier provider (status/v3..v8) never
+		// renders one, even if it happened to carry a submission-shaped payload,
+		// so this is gated on v9 specifically — not on v5, which v8 already
+		// satisfies. Within a v9 payload the discriminator is exactly the
+		// materialize slot's --materialize=true with no --execute, the same one
+		// a lens capture-result materialize slot already uses. Mixing a
+		// submission with the old self-contained --execute=true vector, or with
+		// neither flag, is a malformed vector.
+		if (!v9) {
+			throw new TypeError(`${label}.submission requires the v9 provider contract for the host-mediated ${captureOperation} form`);
+		}
+		const argumentNamed = (argumentName        )                     => {
+			const matches = argumentsList.filter((argument) => argument.name === argumentName);
+			return matches.length === 1 ? matches[0] .value : undefined;
+		};
+		if (argumentNamed("materialize") !== "true") {
+			throw new TypeError(`${label}.submission requires --materialize=true on the host-mediated ${captureOperation} form`);
+		}
+		if (argumentNamed("execute") !== undefined) {
+			throw new TypeError(`${label} must not carry --execute alongside a submission descriptor on ${captureOperation}`);
+		}
 	}
 
 	if (captureOperation === "review.capture-result") {
@@ -1712,7 +1776,12 @@ function decodeCollectInput(value         , label        , v5         , v6
 	const submissionOperations                    = v5
 		? ["review.capture-result", "review.capture-correction-plan", ...(v6 ? ["external.select_intended_untracked"] : [])]
 		: ["review.capture-result"];
-	if (input.submission !== undefined && !submissionOperations.includes(captureOperation)) {
+	// Role operations are gated above by the materialize/execute discriminator
+	// instead of this allowlist: an older gentle-ai's self-contained vector
+	// legitimately carries no submission regardless of v5/v6, so they cannot
+	// simply join the list the way every other submission-carrying operation
+	// does.
+	if (input.submission !== undefined && !isRoleCaptureOperation && !submissionOperations.includes(captureOperation)) {
 		throw new TypeError(v5 ? `${label}.submission is only valid for ${submissionOperations.join(", ")}` : `${label}.submission is only valid for review.capture-result`);
 	}
 	if (intendedUntracked && input.submission === undefined) throw new TypeError(`${label}.submission is required for external.select_intended_untracked`);
@@ -1750,8 +1819,14 @@ export function decodeReviewManagedAssetsContinuationV1(value         , label
 	return { operation, command, ...(agent === undefined ? {} : { agent }), ...(staleAssets === undefined ? {} : { staleAssets }) };
 }
 
-export function decodeReviewNextTransitionV3(value         , options                                 = {})                         {
-	const v6 = options.v6 === true;
+export function decodeReviewNextTransitionV3(value         , options                                               = {})                         {
+	// v9 (gentle-ai's next contract, ahead of the currently-released v8) is
+	// the only rung this sub-decoder distinguishes beyond v6: v7 and v8 add
+	// nothing to next_transition/collect-input decoding (v8 only extended the
+	// reviewer-result transition for OpenCode provider tasks at the top
+	// status level), so they decode on the exact v6 surface here.
+	const v9 = options.v9 === true;
+	const v6 = options.v6 === true || v9;
 	const v5 = options.v5 === true || v6;
 	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : []), "continuation", "unachievable_lens_slots"]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"]         , "next_transition.kind");
@@ -1813,7 +1888,7 @@ export function decodeReviewNextTransitionV3(value         , options
 	}
 	if (kind === "collect") {
 		const collect = exactRecord(transition.collect, "next_transition.collect", ["inputs"]);
-		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6), { minimum: 1 });
+		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6, v9), { minimum: 1 });
 		if (transition.execute !== undefined) throw new TypeError("next_transition.execute is incompatible with collect");
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
@@ -1926,16 +2001,25 @@ export function decodeReviewStatusV3(value         )                 {
 	// surfaces. status/v6 adds the intended-untracked selection; status/v7
 	// (gentle-ai v2.6.0, advertised through capabilities/v2.5 alongside v6)
 	// adds optional `eligible_untracked_inventory` and escalation metadata,
-	// so it is decoded on the v6 surface. v3 keeps rejecting every v5/v6/v7-only
-	// field.
+	// so it is decoded on the v6 surface. status/v8 (gentle-ai main, PR #4765;
+	// the current released contract) only extended the reviewer-result
+	// transition for OpenCode provider tasks -- no new top-level key -- so it
+	// decodes on the exact v7 surface too. status/v9 (the sibling gentle-ai
+	// branch's contract, ahead of the released v8) adds nothing at this top
+	// level either: its one addition is the host-mediated role `submission`
+	// on a next_transition.collect input (gentle-pi#311 P3), gated on v9 in
+	// decodeCollectInput, not here. v3 keeps rejecting every
+	// v5/v6/v7/v8/v9-only field.
 	const schema = typeof value === "object" && value !== null ? (value                           ).schema : undefined;
-	const v7 = schema === "gentle-ai.review-integration.status/v7";
+	const v9 = schema === "gentle-ai.review-integration.status/v9";
+	const v8 = v9 || schema === "gentle-ai.review-integration.status/v8";
+	const v7 = v8 || schema === "gentle-ai.review-integration.status/v7";
 	const v6 = v7 || schema === "gentle-ai.review-integration.status/v6";
 	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
 		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
 	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory", "escalation"] : [])]);
-	requireIdentity(body, v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+	requireIdentity(body, v9 ? "gentle-ai.review-integration.status/v9" : v8 ? "gentle-ai.review-integration.status/v8" : v7 ? "gentle-ai.review-integration.status/v7" : v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"]         , "status.applicability");
 	let receipt                                   ;
@@ -1983,7 +2067,7 @@ export function decodeReviewStatusV3(value         )                 {
 	if (action === "recover" && actionDisposition === undefined) throw new TypeError("recover status requires action_disposition");
 	if (action !== "recover" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover action");
 	if (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6 });
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6, v9 });
 	const validationRequest = v5 && body.validation_request !== undefined
 		? decodeReviewTargetedValidationRequestV1(body.validation_request, "status.validation_request")
 		: undefined;

package/scripts/gentle-ai-installer.mjs

@@ -36,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 = "3.1.0";
+export const INSTALLER_VERSION = "3.4.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",
@@ -45,10 +45,10 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v3";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.1.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v3@v3.4.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit cfc415ce, the published v3.1.0 release head.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:CrZlui5N8/RSmxvn/7usKe6q1EvRt7y6dyfEwjstmJw=";
+// tag resolves to commit 82a6de96, the published v3.4.0 release head.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:bQOM+Xa3WN5+idTagEk15rgEEQQWVhZvq8BPF/FHtSs=";
 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";
@@ -67,7 +67,7 @@ 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 v3.1.0 digests are pinned from the published release:
+// still holds it. The v3.4.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.
@@ -109,15 +109,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v3.1.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v3.4.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_3.1.0_darwin_amd64.tar.gz", "613f0e11adeebb421daae4c68cb9f207f55c559a70595549ff25f988559226e4", "98340df0102825072431a2c0373ea4d9db1bacafced234f51fb58661ed3d731f", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_3.1.0_darwin_arm64.tar.gz", "bfcbf8df2682fcf1535b26c604e8dbb445df0ca00a651de204fdc2d013dfe472", "3cdc9689ea0d71186b896341b4181e2df13a82b64d236a26a3273171150d802f", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_3.1.0_linux_amd64.tar.gz", "dc55c44a2eb46212a38eca0dfd4d778481ec37e765f40d5a0752d03c28e1ee49", "70e335d25809a0d358c12f48b2f0d1da00741e725584ceeb8c1318c60d0a6e9e", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_3.1.0_linux_arm64.tar.gz", "3a89d5f5a549004cc2b01949014ed59f9c28e1ff0c9958531bb539504286e407", "6cf9f20fc390b13e2b9b427ca1c2df404d1bbb9248201f9a592c7f0a37ef5416", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_3.4.0_darwin_amd64.tar.gz", "7d13fa45489098ff9e82dee2232204f72bf1c04ef998ceadfe1ea972697f2e56", "d9096b4bb13e56aae1251dfacd2487821a15c40b7c9397555ad615ede47e658a", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_3.4.0_darwin_arm64.tar.gz", "b9052d8dc02923663d4451a4b031c4ef7328cd866c0cb6729e8ff2b9853603f0", "0aca1239cafd87ce63b194ab69da90e762801d82a96418fd6b7b12ea3806dc07", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_3.4.0_linux_amd64.tar.gz", "c287289a514420381e890991bb3fbea4a2c36d7b4b1774fcf6bc4deb83378915", "309d9aafb48de5ef90ba0a212e8a98e8fdbb82d0852e24015e36a5ce0fe04c06", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_3.4.0_linux_arm64.tar.gz", "dfd1fe70acfe577d2a36e3a658895f481467518a2923b7200403dbcca0181399", "83ba7d27d250019115690be51664bd356e09085da8858761e362e6053c6290d3", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

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

@@ -9,10 +9,11 @@
 // `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 { randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { delimiter, isAbsolute, resolve } from "node:path";
+import { fauxAssistantMessage, registerFauxProvider } from "@earendil-works/pi-ai/compat";
 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";
@@ -88,13 +89,17 @@ const exactKeys = (obj, allowed, label) => {
 // the completing form is provably bindable before any process launches.
 export function validateDescriptor(value) {
 	if (!isObj(value)) fail("descriptor must be a JSON object");
-	exactKeys(value, new Set(["schema", "gentleAiExecutable", "piExecutable", "cases"]), "descriptor");
+	exactKeys(value, new Set(["schema", "gentleAiExecutable", "reviewerSelection", "cases"]), "descriptor");
 	if (value.schema !== DESCRIPTOR_SCHEMA) fail(`descriptor.schema must be exactly "${DESCRIPTOR_SCHEMA}"`);
 	if (!isStr(value.gentleAiExecutable) || !isAbsolute(value.gentleAiExecutable)) fail("descriptor.gentleAiExecutable must be a non-empty absolute path; the runner never re-resolves the production binary");
-	if (!isStr(value.piExecutable)) fail("descriptor.piExecutable must be a non-empty string");
+	// gentle-pi#311 P4: the positive-lens journey used to need a declared real
+	// `pi` binary; lens captures now run in-process, so it instead needs a
+	// "provider/id" reviewer selection the armed run resolves through a
+	// scripted-but-real completion (never a fake pi child).
+	if (!isStr(value.reviewerSelection)) fail("descriptor.reviewerSelection must be a non-empty string");
 	if (!Array.isArray(value.cases) || value.cases.length === 0) fail("descriptor.cases must be a non-empty array");
 	const seen = new Set();
-	return { schema: value.schema, gentleAiExecutable: value.gentleAiExecutable, piExecutable: value.piExecutable, cases: value.cases.map((entry, index) => {
+	return { schema: value.schema, gentleAiExecutable: value.gentleAiExecutable, reviewerSelection: value.reviewerSelection, cases: value.cases.map((entry, index) => {
 			if (!isObj(entry)) fail(`descriptor.cases[${index}] must be an object`);
 			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`);
@@ -205,13 +210,77 @@ export function resolveDeclaredExecutable(executable) {
 	return null;
 }
 const missingReason = (executable, label) => `${label} "${executable}" is not an existing executable; arm the descriptor with a real binary, or set GENTLE_PI_REQUIRE_MAINTAINER=1 to fail instead of block.`;
-// A guaranteed-nonexistent pi path inside a fresh private directory. mkdtemp
-// picks an unpredictable name and 0700 keeps it ours, so nothing can race a
-// file into the slot between the mkdtemp and the spawn.
-function unlaunchablePi() {
-	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-no-pi-"));
-	chmodSync(directory, 0o700);
-	return { directory, executable: join(directory, "pi-must-never-launch") };
+// A reviewer registry whose `find` always misses. Mirrors the pre-in-process
+// "unlaunchable pi" trick this replaced: the maintainer-declared `kind` is
+// not evidence that the declared gentle-ai binary is actually incapable, so
+// a `relay-unavailable` negative control against a mis-declared CAPABLE
+// binary must still never complete a reviewer or submit anything. Resolving
+// nothing guarantees a typed MODEL_NOT_FOUND refusal before any completion
+// or submission, so the control cannot become a hidden real mutation even
+// against a binary that turns out to be capable (gentle-pi#311 P4).
+function unresolvableReviewerRegistry() {
+	return {
+		find: () => undefined,
+		getApiKeyAndHeaders: async () => ({ ok: false, error: "the relay-unavailable negative control never resolves a reviewer" }),
+	};
+}
+// The armed, organic positive-lens journey needs the real gentle-ai binary's
+// materialize/submit protocol exercised end-to-end, but this harness cannot
+// assume a maintainer's real provider credentials. Instead of a fake pi
+// child, this registers pi-ai's own faux provider -- the SAME api-registry
+// the real `completeSimple` dispatches through in production -- so the real
+// `runInProcessReviewer` -> real `completeSimple` path runs with no network.
+// The scripted response reads the frozen prompt's `GENTLE_AI_REVIEW_BINDING`
+// line for the subject_hash and its `GENTLE_AI_REVIEW_CONTEXT` line for the
+// changed-path manifest, and answers with every field the reviewer result
+// contract requires -- subject_hash, a completed inspection over exactly the
+// frozen paths, findings, evidence -- so the real Go admission accepts it
+// (gentle-pi#311 P4). Not unregistered: each
+// call uses a fresh random api id, and this runs at most once per short-lived
+// process (the CLI's single `main()` or one test), so a leaked entry in the
+// process-global api-registry is harmless.
+// Reads the one-line JSON that follows a frozen prompt marker (the binding
+// and context lines Go writes at the top of every reviewer task). Returns
+// undefined when the marker is absent or its JSON is malformed, so the faux
+// reviewer answers with an incomplete result that real admission refuses
+// instead of throwing inside the provider and masking the contract drift.
+function frozenPromptMarkerJson(promptText, marker) {
+	const prefix = `${marker} `;
+	for (const line of promptText.split("\n")) {
+		if (!line.startsWith(prefix)) continue;
+		try { return JSON.parse(line.slice(prefix.length)); } catch { return undefined; }
+	}
+	return undefined;
+}
+function armedFauxReviewerRegistry(reviewerSelection) {
+	const separatorIndex = reviewerSelection.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex === reviewerSelection.length - 1) {
+		throw new DescriptorValidationError(`descriptor.reviewerSelection "${reviewerSelection}" must have the "provider/id" shape`);
+	}
+	const provider = reviewerSelection.slice(0, separatorIndex);
+	const modelId = reviewerSelection.slice(separatorIndex + 1);
+	const api = `gentle-pi-maintainer-faux-reviewer-${randomUUID()}`;
+	const faux = registerFauxProvider({ api, provider, models: [{ id: modelId }] });
+	faux.setResponses([(context) => {
+		const content = context.messages[0]?.content;
+		const textPart = Array.isArray(content) ? content.find((part) => part.type === "text") : undefined;
+		const promptText = textPart?.text ?? "";
+		const binding = frozenPromptMarkerJson(promptText, "GENTLE_AI_REVIEW_BINDING");
+		const frozenContext = frozenPromptMarkerJson(promptText, "GENTLE_AI_REVIEW_CONTEXT");
+		const manifest = Array.isArray(frozenContext?.changed_path_manifest) ? frozenContext.changed_path_manifest : [];
+		const paths = manifest.map((entry) => entry?.path).filter((path) => typeof path === "string" && path.length > 0);
+		return fauxAssistantMessage(JSON.stringify({
+			subject_hash: binding?.subject_hash,
+			inspection: { status: "completed", paths },
+			findings: [],
+			evidence: ["armed maintainer faux reviewer inspected every frozen candidate path"],
+		}));
+	}]);
+	const model = faux.getModel();
+	return {
+		find: () => model,
+		getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "faux-key" }),
+	};
 }
 function terminateRoleProcessTree(child) {
 	if (child.pid === undefined) return false;
@@ -317,39 +386,41 @@ export async function runMatrix(descriptor, options = {}) {
 			}
 			continue;
 		}
-		// The positive lens needs a real pi AND an explicit arm; the negative
-		// 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") {
-			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;
-			}
-			if (!positiveArmed) {
-				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: `positive-lens 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 journey. The runner never synthesizes a provider result.`, command: POSITIVE_JOURNEY_COMMAND });
-				continue;
-			}
+		// The positive lens needs an explicit arm; the negative control never
+		// resolves a reviewer (fails closed at the reviewer stage or earlier).
+		if (caseEntry.kind === "positive-lens" && !positiveArmed) {
+			verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: `positive-lens case is not explicitly armed; set ${ARM_POSITIVE_ENV}=1 with a real capable gentle-ai binary and a real review session (real binding tokens from \`gentle-ai review status --next-transition\`) to run the organic journey. The runner never synthesizes a provider result.`, command: POSITIVE_JOURNEY_COMMAND });
+			continue;
 		}
-		// `relay-unavailable` is a NEGATIVE CONTROL: it must never launch pi and
-		// never submit. The maintainer-declared `kind` is not evidence that the
-		// declared binary is actually incapable, so the arm gate cannot key off
-		// the declaration alone. Pointed at a mis-declared CAPABLE binary, a
-		// declaration-only gate materializes, runs a REAL pi model, and executes
-		// a REAL `capture-result --input=...` submission, and only then reports
-		// `fail` — the mutation already happened. So give the negative control a
-		// pi that cannot exist: an incapable binary still classifies
-		// relay-unavailable at materialize (the control stays genuine, since it
-		// never reached pi anyway), while a capable one fails closed at the pi
-		// 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 ? piPath : negativeControl.executable, ...(options.signal === undefined ? {} : { signal: options.signal }) };
+		// `relay-unavailable` is a NEGATIVE CONTROL: it must never complete a
+		// reviewer and never submit. The maintainer-declared `kind` is not
+		// evidence that the declared binary is actually incapable, so the arm
+		// gate cannot key off the declaration alone. Pointed at a mis-declared
+		// CAPABLE binary, a declaration-only gate materializes, runs a REAL
+		// reviewer completion, and executes a REAL `capture-result --input=...`
+		// submission, and only then reports `fail` — the mutation already
+		// happened. So give the negative control a reviewer registry that can
+		// never resolve: an incapable binary still classifies relay-unavailable
+		// at materialize (the control stays genuine, since it never reached the
+		// reviewer stage anyway), while a capable one fails closed at the
+		// reviewer stage as kind=reviewer-model-not-found stage=pi
+		// mutationOutcome=none, with zero completion and zero submission
+		// (gentle-pi#311 P4, superseding the pre-in-process "unlaunchable pi").
 		try {
+			// A malformed `reviewerSelection` (caught here rather than at
+			// descriptor-validation time, since it is only ever exercised by an
+			// armed positive-lens case) must fail this case the same way a real
+			// relay error would, never crash the whole matrix.
+			const reviewerRegistry = caseEntry.kind === "relay-unavailable" ? unresolvableReviewerRegistry() : armedFauxReviewerRegistry(descriptor.reviewerSelection);
+			const request = {
+				captureArgumentTokens: caseEntry.captureArgumentTokens,
+				submission: caseEntry.submission,
+				gentleAiExecutable: gentleAiPath,
+				reviewerRegistry,
+				selection: descriptor.reviewerSelection,
+				routingKey: "review-relay-matrix",
+				...(options.signal === undefined ? {} : { signal: options.signal }),
+			};
 			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" });
@@ -357,7 +428,9 @@ export async function runMatrix(descriptor, options = {}) {
 				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "pass", promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submissionByteLength: result.submission.length });
 			}
 		} catch (error) {
-			if (error instanceof ReviewHostRelayError) {
+			if (error instanceof DescriptorValidationError) {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: error.message });
+			} else if (error instanceof ReviewHostRelayError) {
 				if (caseEntry.kind === "relay-unavailable") {
 					if (error.kind === REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE && error.stage === "materialize" && error.mutationOutcome === "none") {
 						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "pass", stage: error.stage, mutationOutcome: error.mutationOutcome, reason: REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE });
@@ -372,8 +445,6 @@ export async function runMatrix(descriptor, options = {}) {
 			} else {
 				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `unexpected non-relay error: ${error instanceof Error ? error.message : String(error)}` });
 			}
-		} finally {
-			if (negativeControl !== null) rmSync(negativeControl.directory, { recursive: true, force: true });
 		}
 	}
 	return verdicts;