gentle-pi 2.3.0 → 2.4.0

package/lib/agent-home.ts

@@ -0,0 +1,8 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Pi Subagents resolves its global directory as `PI_CODING_AGENT_DIR || ~/.pi/agent`,
+// so an empty value must fall through here too or the two homes diverge again.
+export function resolveGentlePiAgentHome(env: NodeJS.ProcessEnv = process.env): string {
+	return env.GENTLE_PI_AGENT_HOME || env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}

package/lib/native-review-cli.ts

@@ -789,6 +789,21 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// the columns match the 2.5.0-rc.3 row. riskEvidence and hint stay dark:
 	// still not proven to reach the negotiated START path Pi reads.
 	"2.5.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the published v2.6.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. Declining the consent/v3 prompt during `review start`
+	// still returns `risk_evidence` only on that blocking envelope, never on
+	// the negotiated `start/v4` continuation, so riskEvidence and hint stay
+	// dark for the same reason they have on every row since 2.2.0: still not
+	// proven to reach the negotiated START path Pi reads. The closed fields Pi
+	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
+	// the 2.5.0 row.
+	"2.6.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/provider-contract-bundle.ts

@@ -31,6 +31,8 @@ export const PI_RUNTIME_IDENTITY = "pi";
 export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
 // `runtimes` became part of the manifest in contract 1.1.0.
 export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
+// `orchestration` became part of the manifest in contract 1.2.0.
+export const ORCHESTRATION_REQUIRED_SINCE_MINOR = 2;
 // Exactly the provider roles gentle-pi supports, in the manifest's strict order.
 export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
 // Every mandatory capability a role may declare. An unknown mandatory
@@ -42,6 +44,13 @@ const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
 const MAX_MANIFEST_BYTES = 64 * 1024;
 const BUNDLE_ENTRY_COUNT = 8;
+// Generous fixed safety bound on raw archive/tree entries read BEFORE the
+// manifest itself is parsed (the exact expected count, base entries plus one
+// per `orchestration` runtime, is known only after manifest decode). Real
+// contracts register a handful of runtimes; this bound only rules out an
+// absurd smuggled inventory, it is not the exact-count check.
+const MAX_ORCHESTRATION_ENTRIES = 64;
+const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + MAX_ORCHESTRATION_ENTRIES;
 // setuid/setgid/sticky, any execute bit, or world-writable content is never
 // acceptable for a data-only contract bundle.
 const FORBIDDEN_MODE_BITS = 0o7113;
@@ -84,7 +93,13 @@ export interface VerifiedProviderContractBundle {
 	/** Present exactly when the manifest declares the runtime registry (>= 1.1.0). */
 	readonly runtimes: readonly string[] | undefined;
 	readonly roles: readonly VerifiedProviderRole[];
-	/** Canonical path -> exact verified bytes for all eight entries. */
+	/**
+	 * Verified runtime-bound review execution contract text, runtime identity
+	 * -> UTF-8 `orchestration/<runtime>.md` contents. Empty before contract
+	 * 1.2.0, where `orchestration` does not exist in the manifest.
+	 */
+	readonly orchestration: ReadonlyMap<string, string>;
+	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration runtime). */
 	readonly entries: ReadonlyMap<string, Buffer>;
 	/** Canonical path -> SHA-256 of the exact verified bytes. */
 	readonly entrySha256: ReadonlyMap<string, string>;
@@ -306,6 +321,23 @@ function parseManifestRole(value: unknown, index: number): ManifestRole {
 	};
 }
 
+interface ManifestOrchestrationEntry {
+	readonly runtime: string;
+	readonly file: ManifestFileReference;
+}
+
+function parseOrchestrationEntry(value: unknown, index: number): ManifestOrchestrationEntry {
+	const where = `manifest.orchestration[${index}]`;
+	const object = requireObject(value, where);
+	requireExactKeys(object, ["runtime", "file"], ["runtime", "file"], where);
+	const runtime = requireString(object.runtime, `${where}.runtime`);
+	if (!RUNTIME_IDENTITY_PATTERN.test(runtime)) invalid(`${where}.runtime ${JSON.stringify(runtime)} is not a runtime identity`);
+	const file = parseFileReference(object.file, `${where}.file`);
+	const expectedPath = `orchestration/${runtime}.md`;
+	if (file.path !== expectedPath) invalid(`${where}.file.path must be ${JSON.stringify(expectedPath)}`);
+	return { runtime, file };
+}
+
 interface ParsedManifest {
 	readonly contractSemver: string;
 	readonly major: number;
@@ -315,13 +347,14 @@ interface ParsedManifest {
 	readonly runtimes: readonly string[] | undefined;
 	readonly readme: ManifestFileReference;
 	readonly roles: readonly ManifestRole[];
+	readonly orchestration: readonly ManifestOrchestrationEntry[];
 }
 
 function parseManifest(payload: Buffer): ParsedManifest {
 	const object = decodeStrictManifestObject(payload);
 	requireExactKeys(
 		object,
-		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles"],
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration"],
 		["schema", "contract_semver", "transport_capability", "readme", "roles"],
 		"manifest",
 	);
@@ -365,6 +398,33 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
 	}
 
+	const orchestrationRequired = minor >= ORCHESTRATION_REQUIRED_SINCE_MINOR;
+	let orchestration: readonly ManifestOrchestrationEntry[] = [];
+	if (Object.prototype.hasOwnProperty.call(object, "orchestration")) {
+		if (!orchestrationRequired) {
+			invalid(`manifest.orchestration is not part of contract ${contractSemver}; it exists from 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0`);
+		}
+		if (!Array.isArray(object.orchestration) || object.orchestration.length === 0) {
+			invalid("manifest.orchestration must be a non-empty array");
+		}
+		const parsedOrchestration = object.orchestration.map((entry, index) => parseOrchestrationEntry(entry, index));
+		for (let position = 0; position < parsedOrchestration.length; position += 1) {
+			const entry = parsedOrchestration[position] as ManifestOrchestrationEntry;
+			if (position > 0 && (parsedOrchestration[position - 1] as ManifestOrchestrationEntry).runtime >= entry.runtime) {
+				invalid("manifest.orchestration must be strictly sorted by runtime and unique");
+			}
+			if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
+				invalid(`manifest.orchestration[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
+			}
+		}
+		if (!parsedOrchestration.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
+			invalid(`manifest.orchestration does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+		}
+		orchestration = parsedOrchestration;
+	} else if (orchestrationRequired) {
+		invalid(`manifest.orchestration is required from contract 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
+	}
+
 	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
 	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
 	if (roles.length !== PROVIDER_CONTRACT_ROLE_IDS.length) {
@@ -385,6 +445,7 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		runtimes,
 		readme: parseFileReference(object.readme, "manifest.readme"),
 		roles,
+		orchestration,
 	};
 }
 
@@ -467,8 +528,8 @@ export function bundleTreeSha256(entrySha256: ReadonlyMap<string, string>): stri
 
 /** Verifies a complete in-memory bundle inventory. The single trust anchor. */
 export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<string, Buffer>): VerifiedProviderContractBundle {
-	if (rawEntries.size !== BUNDLE_ENTRY_COUNT) {
-		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${BUNDLE_ENTRY_COUNT} are expected`);
+	if (rawEntries.size > MAX_RAW_BUNDLE_ENTRIES) {
+		invalid(`bundle inventory has ${rawEntries.size} files; at most ${MAX_RAW_BUNDLE_ENTRIES} are ever expected`);
 	}
 	for (const [name, payload] of rawEntries) {
 		if (!isCanonicalBundlePath(name)) invalid(`bundle path ${JSON.stringify(name)} is unsafe`);
@@ -478,6 +539,14 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 	if (manifestPayload === undefined) invalid("bundle is missing manifest.json");
 	const manifest = parseManifest(manifestPayload);
 
+	// The exact expected inventory size is only known once the manifest is
+	// decoded: base entries plus exactly one `orchestration/<runtime>.md` per
+	// registered orchestration runtime.
+	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length;
+	if (rawEntries.size !== expectedEntryCount) {
+		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${expectedEntryCount} are expected`);
+	}
+
 	verifyFileReference(rawEntries, manifest.readme, "README.md");
 	const expected = new Set(["README.md", "manifest.json"]);
 	for (const role of manifest.roles) {
@@ -485,6 +554,13 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 		expected.add(`schemas/${role.id}.schema.json`);
 		expected.add(`vectors/${role.id}.json`);
 	}
+	const orchestration = new Map<string, string>();
+	for (const entry of manifest.orchestration) {
+		const path = `orchestration/${entry.runtime}.md`;
+		const payload = verifyFileReference(rawEntries, entry.file, path);
+		orchestration.set(entry.runtime, payload.toString("utf8"));
+		expected.add(path);
+	}
 	for (const name of rawEntries.keys()) {
 		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
 	}
@@ -514,6 +590,7 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 			vectorPath: role.vector.path,
 			vectorSha256: role.vector.sha256,
 		})),
+		orchestration,
 		entries,
 		entrySha256,
 		treeSha256: bundleTreeSha256(entrySha256),
@@ -566,7 +643,7 @@ export function verifyProviderContractBundleTree(directory: string): VerifiedPro
 			}
 			if (!isCanonicalBundlePath(relativeName)) invalid(`bundle tree path ${JSON.stringify(relativeName)} is unsafe`);
 			if (details.size > MAX_FILE_BYTES) invalid(`bundle tree entry ${JSON.stringify(relativeName)} exceeds its size limit`);
-			if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`bundle tree has more than ${BUNDLE_ENTRY_COUNT} files`);
+			if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`bundle tree has more than ${MAX_RAW_BUNDLE_ENTRIES} files`);
 			entries.set(relativeName, readFileSync(absolute));
 		}
 	};
@@ -628,7 +705,7 @@ function readTarEntries(expanded: Buffer): Map<string, Buffer> {
 		if (size > MAX_FILE_BYTES) invalid(`tar entry ${JSON.stringify(name)} exceeds its size limit`);
 		totalBytes += size;
 		if (totalBytes > MAX_BUNDLE_BYTES) invalid("tar entries exceed the bundle size limit");
-		if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`tar has more than ${BUNDLE_ENTRY_COUNT} entries`);
+		if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`tar has more than ${MAX_RAW_BUNDLE_ENTRIES} entries`);
 		const padding = (TAR_BLOCK_SIZE - (size % TAR_BLOCK_SIZE)) % TAR_BLOCK_SIZE;
 		if (expanded.length - offset < size + padding) invalid("tar stream ends before a complete entry");
 		entries.set(name, Buffer.from(expanded.subarray(offset, offset + size)));
@@ -696,6 +773,11 @@ export function generateProviderContractBaselines(bundle: VerifiedProviderContra
 		mandatory_capabilities: mandatory,
 		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
 		pi_registered: piRuntimeRegistration(bundle).registered,
+		orchestration: [...bundle.orchestration.keys()].sort().map((runtime) => ({
+			runtime,
+			path: `orchestration/${runtime}.md`,
+			sha256: bundle.entrySha256.get(`orchestration/${runtime}.md`),
+		})),
 	};
 	return new Map([
 		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],

package/lib/review-host-relay.ts

@@ -284,7 +284,19 @@ export interface ReviewHostRelayResult {
 	readonly submission: string;
 }
 
+/** Opaque materialize-and-review result, not yet submitted to the provider. */
+export interface ReviewHostRelayPreparedResult {
+	/** Copy-safe request snapshot captured before materialization starts. */
+	readonly request: ReviewHostRelayRequest;
+	readonly promptByteLength: number;
+	readonly resultByteLength: number;
+}
+
+const preparedResultBytes = new WeakMap<ReviewHostRelayPreparedResult, Buffer>();
+
 export type ReviewHostRelayRunner = (request: ReviewHostRelayRequest) => Promise<ReviewHostRelayResult>;
+export type ReviewHostRelayPreparationRunner = (request: ReviewHostRelayRequest) => Promise<ReviewHostRelayPreparedResult>;
+export type ReviewHostRelaySubmissionRunner = (prepared: ReviewHostRelayPreparedResult) => Promise<ReviewHostRelayResult>;
 
 const DEFAULT_GENTLE_AI_TIMEOUT_MS = 120_000;
 
@@ -442,38 +454,54 @@ function assertTokens(name: string, tokens: readonly string[]): void {
 	}
 }
 
+function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): ReviewHostRelayRequest {
+	assertTokens("capture", request.captureArgumentTokens);
+	// The completing form is validated before any process launches: a materialize
+	// slot without a provider-owned submission is a typed contract mismatch,
+	// never a synthesized invocation.
+	resolveReviewHostRelaySubmission(request.submission);
+	const gentleAiExecutable = request.gentleAiExecutable ?? resolveGentleAiBinary();
+	if (!isAbsolute(gentleAiExecutable)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
+	const environment = Object.freeze({ ...(request.environment ?? process.env) }) as NodeJS.ProcessEnv;
+	const submission = request.submission === undefined ? undefined : Object.freeze({
+		operationToken: request.submission.operationToken,
+		argumentTokens: Object.freeze([...request.submission.argumentTokens]),
+		values: Object.freeze(request.submission.values.map((value) => Object.freeze({ ...value }))),
+	});
+	return Object.freeze({
+		...request,
+		captureArgumentTokens: Object.freeze([...request.captureArgumentTokens]),
+		...(submission === undefined ? {} : { submission }),
+		gentleAiExecutable,
+		environment,
+		gentleAiTimeoutMs: request.gentleAiTimeoutMs ?? DEFAULT_GENTLE_AI_TIMEOUT_MS,
+		targetCwd: request.targetCwd ?? process.cwd(),
+	});
+}
+
 /**
- * Runs one complete host-relay capture for one provider-bound slot:
- * materialize → opaque Pi adapter → submit. Throws a typed
- * {@link ReviewHostRelayError} on every failure leg and submits nothing after
- * a failure; the caller re-queries negotiated STATUS instead of retrying.
+ * Materializes one provider-bound reviewer prompt and runs its opaque Pi
+ * subprocess. It does not submit anything, so independent reviewer work can
+ * finish before the caller performs provider-ordered admission.
  */
-export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): Promise<ReviewHostRelayResult> {
-	assertTokens("capture", request.captureArgumentTokens);
-	// The completing form is validated before any process launches: a
-	// materialize slot without a provider-owned submission is a typed
-	// contract mismatch, never a synthesized invocation.
-	const submissionBinding = resolveReviewHostRelaySubmission(request.submission);
-	const gentleAi = request.gentleAiExecutable ?? resolveGentleAiBinary();
-	if (!isAbsolute(gentleAi)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
-	const baseEnvironment = request.environment ?? process.env;
-	// Every gentle-ai invocation the relay makes carries the handshake; the
-	// pi subprocess environment stays exactly as the user configured it.
-	const gentleAiEnvironment = { ...baseEnvironment, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT };
-	const gentleAiTimeoutMs = request.gentleAiTimeoutMs ?? DEFAULT_GENTLE_AI_TIMEOUT_MS;
-	const targetCwd = request.targetCwd ?? process.cwd();
-
-	// (a) Materialize the Go-issued opaque prompt. This invocation is also the
-	// capability detection: an old binary's unknown-flag refusal proves the
-	// relay surface is absent, and the provider's handshake refusal surfaces
-	// verbatim. No version sniffing.
+export async function prepareReviewHostRelaySlot(
+	request: ReviewHostRelayRequest,
+	reviewer: typeof runOpaquePiReviewer = runOpaquePiReviewer,
+): Promise<ReviewHostRelayPreparedResult> {
+	// Copy mutable transport configuration before the first async boundary. The
+	// supplied AbortSignal intentionally stays live across materialize, reviewer,
+	// and submit, preserving the established cancellation behavior.
+	const preparedRequest = snapshotReviewHostRelayRequest(request);
+
+	// The provider materializes the opaque prompt and detects whether this relay
+	// surface is available. No version sniffing or prompt reconstruction occurs.
 	let materialized: ProcessCapture;
 	try {
-		materialized = await collectGentleAiProcess(gentleAi, ["review", "capture-result", ...request.captureArgumentTokens], {
-			cwd: targetCwd,
-			env: gentleAiEnvironment,
-			timeoutMs: gentleAiTimeoutMs,
-			...(request.signal === undefined ? {} : { signal: request.signal }),
+		materialized = await collectGentleAiProcess(preparedRequest.gentleAiExecutable!, ["review", "capture-result", ...preparedRequest.captureArgumentTokens], {
+			cwd: preparedRequest.targetCwd!,
+			env: { ...preparedRequest.environment!, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT },
+			timeoutMs: preparedRequest.gentleAiTimeoutMs!,
+			...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),
 		});
 	} catch (error) {
 		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, "materialize", `gentle-ai prompt materialization could not start: ${error instanceof Error ? error.message : String(error)}`);
@@ -481,45 +509,91 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 	if (materialized.exitCode !== 0 || materialized.timedOut) {
 		const stderr = materialized.stderr.toString("utf8");
 		const refusal = classifyReviewHostRelayRefusal(stderr);
-		const timing = { elapsedMs: materialized.elapsedMs, timeoutMs: gentleAiTimeoutMs };
+		const timing = { elapsedMs: materialized.elapsedMs, timeoutMs: preparedRequest.gentleAiTimeoutMs! };
 		if (refusal === "unknown-flag") {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE, "materialize", REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE, { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut, ...timing });
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE, "materialize", REVIEW_HOST_RELAY_UNAVAILABLE_MESSAGE, {
+				exitCode: materialized.exitCode,
+				stderr,
+				timedOut: materialized.timedOut,
+				...timing,
+			});
 		}
 		if (refusal === "handshake") {
-			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.HANDSHAKE_REFUSED, "materialize", stderr, { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut, ...timing });
+			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.HANDSHAKE_REFUSED, "materialize", stderr, {
+				exitCode: materialized.exitCode,
+				stderr,
+				timedOut: materialized.timedOut,
+				...timing,
+			});
 		}
 		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.MATERIALIZE_FAILED, "materialize", materialized.timedOut
-			? `gentle-ai prompt materialization exceeded its ${gentleAiTimeoutMs}ms bound after ${materialized.elapsedMs}ms`
+			? `gentle-ai prompt materialization exceeded its ${preparedRequest.gentleAiTimeoutMs!}ms bound after ${materialized.elapsedMs}ms`
 			: "gentle-ai prompt materialization failed", { exitCode: materialized.exitCode, stderr, timedOut: materialized.timedOut, ...timing });
 	}
 	const promptBytes = materialized.stdout;
 	if (promptBytes.length === 0) {
-		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.EMPTY_PROMPT, "materialize", "gentle-ai prompt materialization produced no bytes", { exitCode: 0, stderr: materialized.stderr.toString("utf8"), elapsedMs: materialized.elapsedMs, timeoutMs: gentleAiTimeoutMs });
+		throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.EMPTY_PROMPT, "materialize", "gentle-ai prompt materialization produced no bytes", {
+			exitCode: 0,
+			stderr: materialized.stderr.toString("utf8"),
+			elapsedMs: materialized.elapsedMs,
+			timeoutMs: preparedRequest.gentleAiTimeoutMs!,
+		});
 	}
 	// The reviewer bound is derived from the prompt the provider actually
-	// materialized, so it can only be resolved here. An explicit request
-	// timeout (the test seam) still wins over both the override and the scale.
-	const piTimeoutMs = request.piTimeoutMs ?? resolveReviewHostRelayPiTimeoutMs(promptBytes.length, baseEnvironment);
+	// materialized. The explicit request timeout is a test seam that wins over
+	// both the user-owned environment override and the scale-derived bound.
+	const piTimeoutMs = preparedRequest.piTimeoutMs ?? resolveReviewHostRelayPiTimeoutMs(promptBytes.length, preparedRequest.environment);
 
-	// (b) The pure adapter owns the fresh isolated Pi process. Its input and
-	// output are opaque bytes; this coordinator only maps transport failures to
-	// the established relay boundary.
+	// The pure adapter owns the fresh isolated Pi process. Its input and output
+	// are opaque bytes; this coordinator only maps transport failures.
 	let piResult: OpaquePiReviewerResult;
 	try {
-		piResult = await runOpaquePiReviewer(promptBytes, {
-			...(request.piExecutable === undefined ? {} : { piExecutable: request.piExecutable }),
-			environment: baseEnvironment,
+		piResult = await reviewer(promptBytes, {
+			...(preparedRequest.piExecutable === undefined ? {} : { piExecutable: preparedRequest.piExecutable }),
+			environment: preparedRequest.environment,
 			timeoutMs: piTimeoutMs,
-			...(request.signal === undefined ? {} : { signal: request.signal }),
+			...(preparedRequest.signal === undefined ? {} : { signal: preparedRequest.signal }),
 		});
 	} catch (error) {
 		throw relayPiTransportError(error, promptBytes.length, piTimeoutMs);
 	}
-	const resultBytes = piResult.stdout;
+	const prepared = Object.freeze({
+		request: preparedRequest,
+		promptByteLength: promptBytes.length,
+		resultByteLength: piResult.stdoutByteLength,
+	});
+	preparedResultBytes.set(prepared, Buffer.from(piResult.stdout));
+	return prepared;
+}
+
+/**
+ * Starts every reviewer before awaiting any result. If one or more reviewers
+ * fail, it rejects only after every started transport has settled and reports
+ * the earliest failed request in provider order.
+ */
+export async function runReviewHostRelayReviewerGroup(
+	requests: readonly ReviewHostRelayRequest[],
+	prepare: ReviewHostRelayPreparationRunner = prepareReviewHostRelaySlot,
+): Promise<readonly ReviewHostRelayPreparedResult[]> {
+	if (requests.length === 0) {
+		throw new TypeError("Pi host relay reviewer group requires at least one provider-bound request");
+	}
+	const settled = await Promise.allSettled(requests.map(async (request) => await prepare(request)));
+	const failed = settled.find((result) => result.status === "rejected");
+	if (failed?.status === "rejected") throw failed.reason;
+	return settled.map((result) => (result as PromiseFulfilledResult<ReviewHostRelayPreparedResult>).value);
+}
 
-	// (c) Submit the raw final bytes untouched through the provider-owned
-	// completing form: its exact operation and argument tokens, with only the
-	// artifact path substituted into the declared {{value}} slot.
+/**
+ * Submits one already-reviewed opaque result through the exact provider-owned
+ * completing form. Only the provider-declared artifact slot is substituted.
+ */
+export async function submitReviewHostRelayPreparedResult(prepared: ReviewHostRelayPreparedResult): Promise<ReviewHostRelayResult> {
+	const resultBytes = preparedResultBytes.get(prepared);
+	if (resultBytes === undefined) throw new TypeError("Pi host relay requires a recognized prepared result");
+	const { request } = prepared;
+	assertTokens("capture", request.captureArgumentTokens);
+	const submissionBinding = resolveReviewHostRelaySubmission(request.submission);
 	const stagingDirectory = await mkdtemp(join(tmpdir(), "gentle-pi-host-relay-result-"));
 	let primaryFailure = false;
 	try {
@@ -528,14 +602,16 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 		await writeFile(resultFile, resultBytes, { mode: 0o600 });
 		await chmod(resultFile, 0o600);
 		const submitTokens = submissionBinding.argumentTokens.map((token, index) =>
-			index === submissionBinding.substitutionLocation ? token.split(REVIEW_HOST_RELAY_SUBMISSION_VALUE_SLOT).join(resultFile) : token,
+			index === submissionBinding.substitutionLocation
+				? token.split(REVIEW_HOST_RELAY_SUBMISSION_VALUE_SLOT).join(resultFile)
+				: token,
 		);
 		let submission: ProcessCapture;
 		try {
-			submission = await collectGentleAiProcess(gentleAi, ["review", submissionBinding.operationToken, ...submitTokens], {
-				cwd: targetCwd,
-				env: gentleAiEnvironment,
-				timeoutMs: gentleAiTimeoutMs,
+			submission = await collectGentleAiProcess(request.gentleAiExecutable!, ["review", submissionBinding.operationToken, ...submitTokens], {
+				cwd: request.targetCwd!,
+				env: { ...request.environment!, [GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV]: GENTLE_PI_REVIEW_RELAY_CONTRACT },
+				timeoutMs: request.gentleAiTimeoutMs!,
 				...(request.signal === undefined ? {} : { signal: request.signal }),
 			});
 		} catch (error) {
@@ -543,20 +619,22 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 		}
 		if (submission.exitCode !== 0 || submission.timedOut || submission.stdout.length === 0) {
 			const stderr = submission.stderr.toString("utf8");
-			const details = { exitCode: submission.exitCode, stderr, timedOut: submission.timedOut, elapsedMs: submission.elapsedMs, timeoutMs: gentleAiTimeoutMs };
-			// A typed admission refusal is a proven non-mutation whose reason is
-			// the refusal text itself; everything else that launched (timeout,
-			// signal, untyped exit) stays unknown pending STATUS.
+			const details = { exitCode: submission.exitCode, stderr, timedOut: submission.timedOut, elapsedMs: submission.elapsedMs, timeoutMs: request.gentleAiTimeoutMs! };
+			// A typed admission refusal proves the provider consumed no slot.
+			// Every other launched submission stays unknown pending fresh STATUS.
 			if (isReviewHostRelayAdmissionRefusal(submission, stderr)) {
-				throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", stderr.trim(), { ...details, mutationOutcome: "none" });
+				throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", stderr.trim(), {
+					...details,
+					mutationOutcome: "none",
+				});
 			}
 			throw new ReviewHostRelayError(REVIEW_HOST_RELAY_FAILURE.SUBMISSION_REFUSED, "submit", submission.timedOut
-				? `gentle-ai capture submission exceeded its ${gentleAiTimeoutMs}ms bound after ${submission.elapsedMs}ms`
+				? `gentle-ai capture submission exceeded its ${request.gentleAiTimeoutMs!}ms bound after ${submission.elapsedMs}ms`
 				: "gentle-ai refused the relayed capture submission", details);
 		}
 		return {
-			promptByteLength: promptBytes.length,
-			resultByteLength: piResult.stdoutByteLength,
+			promptByteLength: prepared.promptByteLength,
+			resultByteLength: prepared.resultByteLength,
 			submission: submission.stdout.toString("utf8"),
 		};
 	} catch (error) {
@@ -576,3 +654,11 @@ export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): P
 		}
 	}
 }
+
+/**
+ * Compatibility one-binding path: materialize → opaque Pi adapter → submit.
+ * It preserves the established API and its typed failure behavior exactly.
+ */
+export async function runReviewHostRelaySlot(request: ReviewHostRelayRequest): Promise<ReviewHostRelayResult> {
+	return await submitReviewHostRelayPreparedResult(await prepareReviewHostRelaySlot(request));
+}

package/lib/review-integration-v2.ts

@@ -183,6 +183,19 @@ const CAPABILITIES_SCHEMA_IDENTITIES: Readonly<Record<string, { protocolMinor: n
 		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
 		optionalFeatureFloor: 14,
 	}),
+	// Ground-truthed against the published v2.6.0 binary: capabilities/v2.5
+	// advertises the same required surface as v2.4 (status/v6 is still
+	// advertised for compatibility) plus the new status/v7 schema, which is a
+	// superset-checked addition, not a requirement -- decodeReviewStatusV3
+	// accepts v7 as an additive extension of v6, so the required-schema floor
+	// stays unchanged. The v2.6.0 binary advertised 15 optional features
+	// (floor stays at 14, its established minimum).
+	"gentle-ai.review-integration.capabilities/v2.5": Object.freeze({
+		protocolMinor: 5,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.5", "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",
@@ -569,6 +582,8 @@ export interface ReviewStatusV3 {
 	repositoryContext?: ReviewRepositoryContextV2;
 	/** status/v5 only: the provider-owned request mirrored by the targeted-validator collect input. */
 	validationRequest?: ReviewTargetedValidationRequestV1;
+	/** status/v7 only: the eligible untracked-path inventory digest, absent on the `staged` projection. */
+	eligibleUntrackedInventory?: string;
 	raw: Readonly<Record<string, unknown>>;
 }
 
@@ -1761,15 +1776,19 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	// Additive forward acceptance: status/v5 (gentle-ai main; ground-truthed
 	// against a live capture and the vendored status-v5.schema.json) is the v3
 	// key set plus the optional forecast and the v5-only next_transition
-	// surfaces. status/v6 adds the intended-untracked selection; v3 keeps
-	// rejecting every v5/v6-only field.
+	// surfaces. status/v6 adds the intended-untracked selection; status/v7
+	// (gentle-ai v2.6.0, advertised through capabilities/v2.5 alongside v6)
+	// adds only the top-level optional `eligible_untracked_inventory` digest,
+	// so it is decoded on the v6 surface. v3 keeps rejecting every v5/v6/v7-only
+	// field.
 	const schema = typeof value === "object" && value !== null ? (value as Record<string, unknown>).schema : undefined;
-	const v6 = schema === "gentle-ai.review-integration.status/v6";
+	const v7 = 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"] : [])]);
-	requireIdentity(body, v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : []), ...(v7 ? ["eligible_untracked_inventory"] : [])]);
+	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);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"] as const, "status.applicability");
 	let receipt: ReviewStatusReceiptV1 | undefined;
@@ -1851,6 +1870,15 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		};
 	}
 
+	// status/v7 top-level optional digest (gentle-ai v2.6.0): resolves #4066's
+	// closed loop where `sdd-attempt finish` named a digest status never
+	// published. Absent on the `staged` projection, which never resolves an
+	// inventory, so it stays structurally optional rather than a required v7
+	// field.
+	const eligibleUntrackedInventory = v7 && body.eligible_untracked_inventory !== undefined
+		? sha256(body.eligible_untracked_inventory, "status.eligible_untracked_inventory")
+		: undefined;
+
 	return {
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		applicability,
@@ -1869,6 +1897,7 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		...(forecast === undefined ? {} : { forecast }),
 		...(repositoryContext === undefined ? {} : { repositoryContext }),
 		...(validationRequest === undefined ? {} : { validationRequest }),
+		...(eligibleUntrackedInventory === undefined ? {} : { eligibleUntrackedInventory }),
 		raw: body,
 	};
 }

package/lib/sdd-preflight.ts

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveGentlePiAgentHome } from "./agent-home.ts";
 import type { SddArtifactStore } from "./sdd-status.ts";
 
 export type { SddArtifactStore };
@@ -19,7 +19,7 @@ const LEGACY_MANAGED_ASSET_MANIFESTS = Object.freeze([
 ]);
 
 function gentlePiAgentHome(): string {
-	return process.env.GENTLE_PI_AGENT_HOME ?? join(homedir(), ".pi", "agent");
+	return resolveGentlePiAgentHome();
 }
 
 export type SddExecutionMode = "interactive" | "auto";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "2.3.0",
+	"version": "2.4.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",

package/runtime/native-review-cli.mjs

@@ -790,6 +790,21 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// the columns match the 2.5.0-rc.3 row. riskEvidence and hint stay dark:
 	// still not proven to reach the negotiated START path Pi reads.
 	"2.5.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the published v2.6.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. Declining the consent/v3 prompt during `review start`
+	// still returns `risk_evidence` only on that blocking envelope, never on
+	// the negotiated `start/v4` continuation, so riskEvidence and hint stay
+	// dark for the same reason they have on every row since 2.2.0: still not
+	// proven to reach the negotiated START path Pi reads. The closed fields Pi
+	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
+	// the 2.5.0 row.
+	"2.6.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });