gentle-pi 3.2.1 → 3.4.0

package/tests/devbinary/pi-host-relay.devtest.ts

@@ -1,19 +1,74 @@
 import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { delimiter, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import test from "node:test";
+import type { Api, AssistantMessage, Context, Model } from "@earendil-works/pi-ai";
+import { fauxAssistantMessage, registerFauxProvider } from "@earendil-works/pi-ai/compat";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { __testing, createGentleAiExtension } from "../../extensions/gentle-ai.ts";
 import { resolveGentleAiBinary } from "../../lib/gentle-ai-binary.ts";
-import { OPAQUE_PI_REVIEWER_ARGV } from "../../lib/opaque-pi-reviewer-adapter.ts";
+import type { InProcessReviewerRegistry } from "../../lib/inprocess-reviewer.ts";
 import { NativeReviewCliV216, type ExecFileAdapter, type NativeReviewCli } from "../../lib/native-review-cli.ts";
 import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, reviewHostRelaySlots, 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";
 import { decodeReviewStatusV3 } from "../../lib/review-integration-v2.ts";
 import { requireDevBinary } from "../support/native-binary-gate.ts";
 
+// gentle-pi#311 P4 / P3: lens captures run one in-process reviewer completion
+// through the live model registry (lib/inprocess-reviewer.ts), with no child
+// process, no `piExecutable`/`-e` forwarding, and no extension allowlist.
+// gentle-ai's v9 contract makes the refuter and targeted-validator role
+// captures host-mediated the same way (P3): each carries a submission
+// descriptor alongside `--materialize=true`, runs through the SAME relay
+// seam, and reaches the SAME `fauxReviewerFor` fixture — there is no
+// Go-owned `pi` subprocess left to fake on PATH for either role. The devtests
+// below inject a fake reviewer registry instead of a fake `pi` binary for
+// every one of these legs.
+
+// ---------------------------------------------------------------------------
+// Fake reviewer registry (gentle-pi#311 P4) — 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 end-to-end with no network and no child
+// process. The scripted response reads the frozen prompt's
+// `GENTLE_AI_REVIEW_BINDING` line for the subject_hash the real Go admission
+// requires, exactly like the fake pi child this replaced. `enqueue` must be
+// called once per expected completion (the faux provider's response queue is
+// FIFO and errors once exhausted).
+// ---------------------------------------------------------------------------
+interface FauxReviewerCall {
+	promptText: string;
+	subjectHash: string | undefined;
+}
+function fauxReviewerFor(buildResponseText: (subjectHash: string | undefined, promptText: string) => string) {
+	const id = randomUUID();
+	const provider = `dev-binary-faux-reviewer-${id}`;
+	const faux = registerFauxProvider({ api: provider, provider, models: [{ id: "dev-fixture" }] });
+	const calls: FauxReviewerCall[] = [];
+	const enqueue = () => {
+		faux.appendResponses([(context: Context): AssistantMessage => {
+			const content = context.messages[0]?.content;
+			const textPart = Array.isArray(content) ? content.find((part) => part.type === "text") : undefined;
+			const promptText = (textPart as { text?: string } | undefined)?.text ?? "";
+			const newline = promptText.indexOf("\n");
+			const firstLine = newline === -1 ? promptText : promptText.slice(0, newline);
+			const prefix = "GENTLE_AI_REVIEW_BINDING ";
+			const subjectHash = firstLine.startsWith(prefix) ? (JSON.parse(firstLine.slice(prefix.length)) as { subject_hash?: string }).subject_hash : undefined;
+			calls.push({ promptText, subjectHash });
+			return fauxAssistantMessage(buildResponseText(subjectHash, promptText));
+		}]);
+	};
+	const model = faux.getModel() as unknown as Model<Api>;
+	const registry: InProcessReviewerRegistry = {
+		find: () => model,
+		getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "faux-key" }),
+	};
+	return { registry, selection: `${model.provider}/${model.id}`, routingKey: "review-risk", enqueue, calls };
+}
+
 const DEV_BINARY = process.env.GENTLE_AI_DEV_BINARY;
 const RELAY_DEV_BINARY = process.env.GENTLE_PI_GENTLE_AI_DEV_BINARY;
 const POSIX = process.platform !== "win32";
@@ -264,50 +319,6 @@ function grantedConsentInvocation(value: unknown): string {
 	return stringValue(granted!.invocation, "granted consent invocation");
 }
 
-const FAKE_POSIX_PI = `#!/usr/bin/env node
-import fs from "node:fs";
-const expectedArgv = JSON.parse(process.env.OPAQUE_PI_REVIEWER_ARGV);
-const expectedPaths = JSON.parse(process.env.OPAQUE_PI_REVIEWER_PATHS);
-const chunks = [];
-process.stdin.on("data", (chunk) => chunks.push(chunk));
-process.stdin.on("end", () => {
-  const prompt = Buffer.concat(chunks);
-  const promptText = prompt.toString("utf8");
-  const targetedValidatorResult = process.env.OPAQUE_PI_TARGETED_VALIDATOR_RESULT;
-  let subjectHash;
-  if (targetedValidatorResult === undefined) {
-    const newline = prompt.indexOf(0x0a);
-    if (newline < 0) throw new Error("missing binding line");
-    const firstLine = prompt.subarray(0, newline).toString("utf8");
-    const prefix = "GENTLE_AI_REVIEW_BINDING ";
-    if (!firstLine.startsWith(prefix)) throw new Error("missing binding prefix");
-    const binding = JSON.parse(firstLine.slice(prefix.length));
-    if (typeof binding.subject_hash !== "string" || !/^sha256:[0-9a-f]{64}$/.test(binding.subject_hash)) throw new Error("invalid binding subject_hash");
-    if (JSON.stringify(process.argv.slice(2)) !== JSON.stringify(expectedArgv)) throw new Error("unexpected opaque Pi argv");
-    subjectHash = binding.subject_hash;
-  } else if (promptText.length === 0) {
-    throw new Error("missing targeted-validator prompt");
-  }
-  const prior = fs.existsSync(process.env.OPAQUE_PI_REVIEWER_LOG) ? JSON.parse(fs.readFileSync(process.env.OPAQUE_PI_REVIEWER_LOG, "utf8")) : { calls: [] };
-  const calls = Array.isArray(prior.calls) ? prior.calls : [];
-  calls.push({
-    argv: process.argv.slice(2), cwd: process.cwd(), entries: fs.readdirSync(process.cwd()), ...(subjectHash === undefined ? {} : { subject_hash: subjectHash }), prompt: promptText,
-    role: targetedValidatorResult === undefined ? "reviewer" : "targeted-validator",
-  });
-  fs.writeFileSync(process.env.OPAQUE_PI_REVIEWER_LOG, JSON.stringify({ calls }));
-  if (targetedValidatorResult !== undefined) {
-    process.stdout.write(targetedValidatorResult);
-    return;
-  }
-  process.stdout.write(JSON.stringify({
-    subject_hash: subjectHash,
-    inspection: { status: "completed", paths: expectedPaths },
-    findings: process.env.OPAQUE_PI_REVIEWER_FINDINGS === undefined ? [] : JSON.parse(process.env.OPAQUE_PI_REVIEWER_FINDINGS),
-    evidence: ["inspected every frozen candidate path"],
-  }));
-});
-`;
-
 // This A -> B journey deliberately stops immediately after one Go-admitted
 // reviewer capture. It proves real Pi relay transport and root continuity, but
 // does not manufacture the remaining reviewer, refuter, validator, or approval
@@ -383,21 +394,25 @@ test("dev-binary: POSIX Pi host relay captures one real B-target slot from an A-
 	assert.ok(slot.submission, "the real Pi slot must include Go's provider-owned submission form");
 	assert.ok(slot.subjectHash, "the real Pi slot must include its artifact subject hash");
 
-	const fakePi = join(sessionA, "fake-pi");
-	const fakePiLog = join(sessionA, "fake-pi-log.json");
-	writeFileSync(fakePi, FAKE_POSIX_PI);
-	chmodSync(fakePi, 0o755);
+	// gentle-pi#311 P4: the reviewer completion runs in-process — a fake
+	// registry replaces the fake `pi` binary this devtest used to spawn for
+	// the lens capture. There is no child process and no scratch sandbox to
+	// isolate or clean up for this leg any more.
+	const reviewer = fauxReviewerFor((subjectHash) => JSON.stringify({
+		subject_hash: subjectHash,
+		inspection: { status: "completed", paths: expectedPaths },
+		findings: [],
+		evidence: ["inspected every frozen candidate path"],
+	}));
+	reviewer.enqueue();
 	const relay = await runReviewHostRelaySlot({
 		captureArgumentTokens: slot.captureArgumentTokens,
 		submission: slot.submission,
 		targetCwd: canonicalB,
-		piExecutable: fakePi,
-		environment: {
-			...environment,
-			OPAQUE_PI_REVIEWER_ARGV: JSON.stringify(OPAQUE_PI_REVIEWER_ARGV),
-			OPAQUE_PI_REVIEWER_LOG: fakePiLog,
-			OPAQUE_PI_REVIEWER_PATHS: JSON.stringify(expectedPaths),
-		},
+		environment,
+		reviewerRegistry: reviewer.registry,
+		selection: reviewer.selection,
+		routingKey: reviewer.routingKey,
 		gentleAiTimeoutMs: 30_000,
 		piTimeoutMs: 30_000,
 	});
@@ -405,17 +420,8 @@ test("dev-binary: POSIX Pi host relay captures one real B-target slot from an A-
 	assert.ok(relay.resultByteLength > 0);
 	assert.equal(record(JSON.parse(relay.submission) as unknown, "capture submission").admission_decision, "completed");
 
-	const fakePiLogRecord = record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "fake Pi log");
-	assert.ok(Array.isArray(fakePiLogRecord.calls), "fake Pi log must record its subprocess calls");
-	assert.equal(fakePiLogRecord.calls.length, 1);
-	const fakePiResult = record(fakePiLogRecord.calls[0], "fake Pi result");
-	assert.deepEqual(fakePiResult.argv, OPAQUE_PI_REVIEWER_ARGV);
-	assert.deepEqual(fakePiResult.entries, []);
-	assert.equal(fakePiResult.subject_hash, slot.subjectHash);
-	const scratchCwd = stringValue(fakePiResult.cwd, "fake Pi scratch cwd");
-	assert.notEqual(scratchCwd, canonicalB);
-	assert.notEqual(scratchCwd, sessionA);
-	assert.equal(existsSync(scratchCwd), false, "opaque Pi scratch cwd must be removed after the subprocess exits");
+	assert.equal(reviewer.calls.length, 1, "the in-process reviewer must complete exactly once");
+	assert.equal(reviewer.calls[0]!.subjectHash, slot.subjectHash, "the reviewer completion must receive the real frozen binding's subject hash");
 
 	const advanced = candidateStatus(RELAY_DEV_BINARY!, sessionA, canonicalB, environment, lineage);
 	const reoffered = reviewHostRelaySlots(advanced.nextTransition?.collect?.inputs ?? []).some((candidate) =>
@@ -470,14 +476,25 @@ test("dev-binary: a garbage reviewer result is refused at admission as a proven
 	const reviewerBinding = collectBindingsFor(status, "review.capture-result")[0];
 	assert.ok(reviewerBinding, "current STATUS must publish a reviewer capture binding");
 	const subjectHash = collectBindingArgument(reviewerBinding!, "subject-hash");
-	const fakePi = join(scratch, "fake-pi");
-	writeFileSync(fakePi, "#!/usr/bin/env node\nprocess.stdin.resume();\nprocess.stdin.on('end', () => { process.stdout.write('not json at all'); });\n");
-	chmodSync(fakePi, 0o755);
+	// gentle-pi#311 P4: the in-process reviewer completion produces the
+	// garbage text directly (no fake `pi` binary); Go's real admission still
+	// refuses it exactly as before.
+	const reviewer = fauxReviewerFor(() => "not json at all");
 	let relayError: unknown;
 	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
 	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+		reviewer.enqueue();
 		try {
-			return await runReviewHostRelaySlot({ ...request, gentleAiExecutable: RELAY_DEV_BINARY!, piExecutable: fakePi, environment, gentleAiTimeoutMs: 30_000, piTimeoutMs: 30_000 });
+			return await runReviewHostRelaySlot({
+				...request,
+				gentleAiExecutable: RELAY_DEV_BINARY!,
+				environment,
+				reviewerRegistry: reviewer.registry,
+				selection: reviewer.selection,
+				routingKey: reviewer.routingKey,
+				gentleAiTimeoutMs: 30_000,
+				piTimeoutMs: 30_000,
+			});
 		} catch (error) {
 			relayError = error;
 			throw error;
@@ -514,9 +531,10 @@ test("dev-binary: a garbage reviewer result is refused at admission as a proven
 });
 
 // This completes the same organic A -> B path through correction evidence,
-// Go-owned targeted validation, and terminal approval. The only reviewer is the
-// fixed fake Pi executable below; no model, provider, or profile is selected.
-test("dev-binary: Pi controller keeps an explicit B root and selected-untracked binding through Go-owned validation approval", { skip: !RUNNABLE }, async (t) => {
+// host-mediated targeted validation, and terminal approval. The only
+// reviewers are the fixed faux registries below; no real model, provider, or
+// profile is selected.
+test("dev-binary: Pi controller keeps an explicit B root and selected-untracked binding through host-mediated validation approval", { skip: !RUNNABLE }, async (t) => {
 	const sessionA = repository(t, "gentle-pi-combined-session-a-");
 	const targetB = repository(t, "gentle-pi-combined-target-b-");
 	const nestedTarget = join(targetB, "nested", "target");
@@ -600,16 +618,6 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 	assert.equal(startedDetails.workspace_root, canonicalB);
 	const lineage = stringValue(record(startedDetails.result, "combined start result").lineage_id, "combined lineage");
 
-	const fakePiDirectory = join(sessionA, "fake-pi-bin");
-	mkdirSync(fakePiDirectory);
-	const fakePi = join(fakePiDirectory, "pi");
-	const fakePiLog = join(sessionA, "fake-pi-log.json");
-	writeFileSync(fakePi, FAKE_POSIX_PI);
-	chmodSync(fakePi, 0o755);
-	environment.PATH = [fakePiDirectory, process.env.PATH].filter((entry): entry is string => entry !== undefined && entry.length > 0).join(delimiter);
-	environment.OPAQUE_PI_REVIEWER_ARGV = JSON.stringify(OPAQUE_PI_REVIEWER_ARGV);
-	environment.OPAQUE_PI_REVIEWER_LOG = fakePiLog;
-	environment.OPAQUE_PI_REVIEWER_PATHS = JSON.stringify([".github/workflows/relay.yml", "selected.txt"]);
 	const reviewerFindings = [{
 		location: "selected.txt:1",
 		severity: "BLOCKER",
@@ -618,22 +626,46 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 		evidence_class: "deterministic",
 		causal_disposition: "introduced",
 	}];
+	// gentle-pi#311 P4 / P3: the lens reviewer capture runs in-process through
+	// a fake registry. gentle-ai's v9 contract makes the targeted-validator
+	// role host-mediated too (there is no Go-owned pi subprocess left to fake
+	// on PATH for it), so it reaches the SAME relay seam below through its own
+	// faux reviewer, armed once its request-hash and target identity are
+	// known further down.
+	const reviewer = fauxReviewerFor((subjectHash) => JSON.stringify({
+		subject_hash: subjectHash,
+		inspection: { status: "completed", paths: [".github/workflows/relay.yml", "selected.txt"] },
+		findings: reviewerFindings,
+		evidence: ["inspected every frozen candidate path"],
+	}));
+	let validatorReviewer: ReturnType<typeof fauxReviewerFor> | undefined;
 	const relayTargetRoots: string[] = [];
 	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
 	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
 		assert.equal(request.targetCwd, canonicalB, "the host relay must materialize and submit against B");
 		relayTargetRoots.push(request.targetCwd!);
+		if (request.routingKey === "review-validator") {
+			assert.ok(validatorReviewer, "the targeted-validator reviewer fixture must be armed before its slot reaches the relay");
+			validatorReviewer.enqueue();
+			return await runReviewHostRelaySlot({
+				...request,
+				gentleAiExecutable: RELAY_DEV_BINARY!,
+				environment,
+				reviewerRegistry: validatorReviewer.registry,
+				selection: validatorReviewer.selection,
+				routingKey: request.routingKey,
+				gentleAiTimeoutMs: 30_000,
+				piTimeoutMs: 30_000,
+			});
+		}
+		reviewer.enqueue();
 		return await runReviewHostRelaySlot({
 			...request,
 			gentleAiExecutable: RELAY_DEV_BINARY!,
-			piExecutable: fakePi,
-			environment: {
-				...environment,
-				OPAQUE_PI_REVIEWER_ARGV: JSON.stringify(OPAQUE_PI_REVIEWER_ARGV),
-				OPAQUE_PI_REVIEWER_LOG: fakePiLog,
-				OPAQUE_PI_REVIEWER_PATHS: JSON.stringify([".github/workflows/relay.yml", "selected.txt"]),
-				OPAQUE_PI_REVIEWER_FINDINGS: JSON.stringify(reviewerFindings),
-			},
+			environment,
+			reviewerRegistry: reviewer.registry,
+			selection: reviewer.selection,
+			routingKey: reviewer.routingKey,
 			gentleAiTimeoutMs: 30_000,
 			piTimeoutMs: 30_000,
 		});
@@ -665,10 +697,7 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 		assert.ok(publicStatusProjectionPaths(reviewerStatusDetails).includes("selected.txt"), "public STATUS must retain the selected path in B's projection");
 		assert.equal(publicStatusProjectionPaths(reviewerStatusDetails).includes("excluded.txt"), false, "public STATUS must retain the excluded path outside B's projection");
 
-		const fakeCallsBeforeForecast = existsSync(fakePiLog)
-			? record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "reviewer fake Pi forecast log").calls
-			: [];
-		assert.ok(Array.isArray(fakeCallsBeforeForecast), "reviewer fake Pi forecast log must carry calls when present");
+		const reviewerCallsBeforeForecast = reviewer.calls.length;
 		const reviewerForecast = await capture.execute(
 			`combined-reviewer-forecast-${attempt}`,
 			{ lineageId: lineage, workspaceRoot: nestedTarget, collectBinding: reviewerBinding },
@@ -679,11 +708,7 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 		const reviewerForecastDetails = record(reviewerForecast.details, "combined reviewer forecast");
 		assert.equal(reviewerForecastDetails.status, "blocked");
 		assert.equal(reviewerForecastDetails.outcome, "reviewer-model-run-forecast");
-		const fakeCallsAfterForecast = existsSync(fakePiLog)
-			? record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "reviewer fake Pi forecast result").calls
-			: [];
-		assert.ok(Array.isArray(fakeCallsAfterForecast), "reviewer fake Pi forecast result must carry calls when present");
-		assert.equal(fakeCallsAfterForecast.length, fakeCallsBeforeForecast.length, "forecast acknowledgement must not launch a reviewer capture");
+		assert.equal(reviewer.calls.length, reviewerCallsBeforeForecast, "forecast acknowledgement must not launch a reviewer completion");
 
 		const reviewerCapture = await capture.execute(
 			`combined-reviewer-capture-${attempt}`,
@@ -694,9 +719,7 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 		);
 		const reviewerCaptureDetails = record(reviewerCapture.details, "combined reviewer capture");
 		assert.ok(["captured", "closed"].includes(stringValue(reviewerCaptureDetails.status, "combined reviewer capture status")), "one acknowledged binding must perform exactly one native reviewer capture");
-		const fakeCallsAfterCapture = record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "reviewer fake Pi capture result").calls;
-		assert.ok(Array.isArray(fakeCallsAfterCapture), "reviewer fake Pi capture result must carry calls");
-		assert.equal(fakeCallsAfterCapture.length, fakeCallsBeforeForecast.length + 1, "one acknowledged binding must launch exactly one reviewer capture");
+		assert.equal(reviewer.calls.length, reviewerCallsBeforeForecast + 1, "one acknowledged binding must launch exactly one reviewer completion");
 		reviewerCaptureCount += 1;
 		const closure = reviewerCaptureDetails.closure;
 		if (closure !== undefined) {
@@ -723,17 +746,12 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 	assert.ok(reviewerCaptureCount > 0);
 	assert.ok(relayTargetRoots.length === reviewerCaptureCount);
 	assert.ok(relayTargetRoots.every((root) => root === canonicalB), "every reviewer relay leg must stay bound to B");
-	const combinedFakePiLog = record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "combined fake Pi log");
-	assert.ok(Array.isArray(combinedFakePiLog.calls), "combined fake Pi log must record reviewer subprocess calls");
-	const reviewerCalls = combinedFakePiLog.calls.map((call) => record(call, "combined fake Pi reviewer call")).filter((call) => call.role === "reviewer");
-	assert.equal(reviewerCalls.length, reviewerCaptureCount);
-	for (const call of reviewerCalls) {
-		assert.equal(call.subject_hash === undefined, false, "the fake reviewer must receive one provider-bound subject");
-		assert.deepEqual(call.argv, OPAQUE_PI_REVIEWER_ARGV);
-		assert.deepEqual(call.entries, [], "the reviewer must run from an empty isolated sandbox");
-		assert.notEqual(call.cwd, canonicalB, "the reviewer subprocess must not run in B");
-		assert.notEqual(call.cwd, sessionA, "the reviewer subprocess must not run in A");
-		assert.equal(existsSync(stringValue(call.cwd, "reviewer fake Pi scratch cwd")), false, "the reviewer sandbox must be removed after the subprocess exits");
+	// gentle-pi#311 P4: the reviewer completion runs in-process — there is no
+	// subprocess log, argv, or scratch sandbox to assert for this leg any
+	// more; `reviewer.calls` is the in-process equivalent record.
+	assert.equal(reviewer.calls.length, reviewerCaptureCount);
+	for (const call of reviewer.calls) {
+		assert.notEqual(call.subjectHash, undefined, "the in-process reviewer must receive one provider-bound subject");
 	}
 
 	const correctionStatus = await controller.execute(
@@ -775,7 +793,17 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 	const validatorBinding = collectBindingFor(validationStatus.details, "review.capture-validation");
 	const validatorInput = parsedCollectBinding(validatorBinding);
 	assert.equal(validatorInput.captureOperation, "review.capture-validation");
-	assert.equal(validatorInput.submission, undefined, "the Go-owned targeted-validator vector must not accept a caller-authored submission");
+	// gentle-pi#311 P3: gentle-ai's v9 contract renders the targeted-validator
+	// role host-mediated too, carrying a submission descriptor alongside
+	// --materialize=true exactly like a lens capture-result materialize slot.
+	const validatorSubmission = record(validatorInput.submission, "host-mediated targeted-validator submission");
+	assert.equal(validatorSubmission.operationToken, "capture-validation");
+	const validatorSubmissionValues = validatorSubmission.values;
+	assert.ok(Array.isArray(validatorSubmissionValues) && validatorSubmissionValues.length === 1, "the targeted-validator submission must bind exactly one artifact value");
+	const validatorSubmissionValue = record(validatorSubmissionValues[0], "targeted-validator submission value");
+	assert.equal(validatorSubmissionValue.slot, "provider_targeted_validator");
+	assert.equal(validatorSubmissionValue.domain, "artifact_path_or_stdin");
+	assert.equal(validatorSubmissionValue.schema, "https://gentle-ai.dev/schema/review/validator/v1");
 	const validationRequest = record(validatorInput.validationRequest, "targeted-validator validation request");
 	const validatorArgumentTokens = collectBindingArgumentTokens(validatorBinding);
 	const validatorRequestHash = collectBindingArgument(validatorBinding, "request-hash");
@@ -790,20 +818,36 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 	assert.ok(Array.isArray(validationRequest.fixClassifications) && validationRequest.fixClassifications.length > 0, "the public targeted-validator request must retain Go's classifications");
 	assert.ok(validatorArgumentTokens.includes(`--request-hash=${validatorRequestHash}`), "the public targeted-validator vector must retain its request hash");
 	assert.ok(validatorArgumentTokens.includes("--agent=pi"), "the public targeted-validator vector must retain the Pi binding");
-	assert.ok(validatorArgumentTokens.includes("--execute=true"), "the public targeted-validator vector must retain Go-owned execution");
+	assert.ok(validatorArgumentTokens.includes("--materialize=true"), "the public targeted-validator vector must retain the host-mediated materialize binding");
+	assert.equal(validatorArgumentTokens.includes("--execute=true"), false, "the v9 host-mediated form must never carry --execute alongside its submission");
 	assert.ok(publicStatusProjectionPaths(validationStatus.details).includes("selected.txt"), "the targeted-validator STATUS must remain bound to selected.txt");
 	assert.equal(publicStatusProjectionPaths(validationStatus.details).includes("excluded.txt"), false, "the targeted-validator STATUS must remain outside excluded.txt");
 
-	environment.OPAQUE_PI_TARGETED_VALIDATOR_RESULT = JSON.stringify({
+	// Arm the targeted-validator faux reviewer now that its request hash and
+	// target identity are known; the relay override above dispatches to it by
+	// routing key.
+	validatorReviewer = fauxReviewerFor(() => JSON.stringify({
 		targeted_validation_request_hash: validatorRequestHash,
 		correction_target_identity: validatorTargetIdentity,
 		original_criteria: { passed: true, evidence: ["focused acceptance proof passed"] },
 		correction_regression: { passed: true, evidence: ["focused regression proof passed"] },
 		follow_ups: [],
-	});
+	}));
+	const validatorForecast = await capture.execute(
+		"combined-targeted-validator-forecast",
+		{ lineageId: lineage, workspaceRoot: nestedTarget, collectBinding: validatorBinding },
+		undefined,
+		undefined,
+		sessionContext(sessionA),
+	);
+	const validatorForecastDetails = record(validatorForecast.details, "combined targeted-validator forecast");
+	assert.equal(validatorForecastDetails.status, "blocked");
+	assert.equal(validatorForecastDetails.outcome, "reviewer-model-run-forecast");
+	assert.equal(validatorReviewer.calls.length, 0, "forecast acknowledgement must not launch a reviewer completion");
+
 	const providerValidation = await capture.execute(
 		"combined-provider-targeted-validation",
-		{ lineageId: lineage, workspaceRoot: nestedTarget, collectBinding: validatorBinding },
+		{ lineageId: lineage, workspaceRoot: nestedTarget, collectBinding: validatorBinding, reviewerRunAcknowledged: true },
 		undefined,
 		undefined,
 		sessionContext(sessionA),
@@ -816,22 +860,16 @@ test("dev-binary: Pi controller keeps an explicit B root and selected-untracked
 	assert.equal(validationClosure.schema, "gentle-ai.review-last-event-closure/v1");
 	assert.equal(validationClosure.operation, "review/capture-validation");
 	assert.equal(validationClosure.state, "approved");
-	const validationCaptureCalls = nativeCalls.filter((call) => call.arguments[0] === "review" && call.arguments[1] === "capture-validation");
-	assert.equal(validationCaptureCalls.length, 1, "the Go-owned targeted validator must capture exactly once");
-	assert.equal(validationCaptureCalls[0]!.cwd, canonicalB);
-	assert.deepEqual(validationCaptureCalls[0]!.arguments.slice(2), validatorArgumentTokens, "the Go-owned targeted validator must receive the exact public vector");
-
-	const validatorPiLog = record(JSON.parse(readFileSync(fakePiLog, "utf8")) as unknown, "validator fake Pi log");
-	assert.ok(Array.isArray(validatorPiLog.calls), "validator fake Pi log must record the Go-owned subprocess");
-	const validatorCall = validatorPiLog.calls.map((call) => record(call, "validator fake Pi call")).find((call) => call.role === "targeted-validator");
-	assert.ok(validatorCall, "the fake Pi log must contain the Go-owned targeted-validator subprocess");
-	assert.deepEqual(validatorCall!.entries, [], "the Go-owned validator must run from an empty isolated sandbox");
-	assert.notEqual(validatorCall!.cwd, canonicalB, "the Go-owned validator subprocess must not run in B");
-	assert.notEqual(validatorCall!.cwd, sessionA, "the Go-owned validator subprocess must not run in A");
-	assert.equal(existsSync(stringValue(validatorCall!.cwd, "validator fake Pi scratch cwd")), false, "the Go-owned validator sandbox must be removed after the subprocess exits");
-	const validatorPrompt = stringValue(validatorCall!.prompt, "validator fake Pi prompt");
-	assert.ok(validatorPrompt.length > 0, "the Go-owned validator must receive a provider-rendered prompt");
-	assert.ok(validatorPrompt.includes(validatorRequestHash), "the Go-owned validator prompt must retain the provider request hash");
+
+	// gentle-pi#311 P3: the targeted validator now completes in-process
+	// through the same host relay seam as the lens reviewer above — there is
+	// no Go-owned pi subprocess, no PATH fixture, and no scratch sandbox to
+	// assert for this leg any more; it never reaches the native adapter's
+	// own `review capture-validation` invocation, since the relay spawns
+	// gentle-ai itself for both materialize and submit.
+	assert.equal(validatorReviewer.calls.length, 1, "the in-process targeted validator must complete exactly once");
+	assert.ok(validatorReviewer.calls[0]!.promptText.includes(validatorRequestHash), "the targeted-validator prompt must retain the provider request hash");
+	assert.equal(nativeCalls.some((call) => call.arguments[0] === "review" && call.arguments[1] === "capture-validation"), false, "the targeted validator must not reach the native adapter directly");
 
 	// Approval no longer burns on its own: it commits one pending
 	// acknowledgement and waits for the host to run that exact invocation

package/tests/double-esc-cancel-policy.test.ts

@@ -0,0 +1,194 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import {
+	DOUBLE_ESC_CANCEL_FILE,
+	DOUBLE_ESC_CANCEL_SCHEMA,
+	DOUBLE_ESC_CANCEL_WINDOW_MS,
+	loadDoubleEscCancelPolicy,
+	parseDoubleEscCancelPolicyFile,
+	resolveDoubleEscCancelPolicy,
+	writeDoubleEscCancelPolicy,
+} from "../lib/double-esc-cancel-policy.ts";
+
+// ---------------------------------------------------------------------------
+// Double-esc-cancel policy (issue #1163).
+//
+// Global-only resolver: global file > env var > default off. Mirrors the
+// resolution shape of lib/background-subagents-policy.ts minus the
+// project-file layer, since this preference is deliberately global-only
+// (see the feature scope in odd/tasks/double-esc-cancel.md). Strict schema
+// decode, fail-closed to "off" on any malformed input.
+// ---------------------------------------------------------------------------
+
+const scratchRoots: string[] = [];
+
+function makeScratch(prefix: string): string {
+	const dir = mkdtempSync(join(tmpdir(), prefix));
+	scratchRoots.push(dir);
+	return dir;
+}
+
+after(() => {
+	for (const dir of scratchRoots) rmSync(dir, { recursive: true, force: true });
+});
+
+function writePolicyFile(dir: string, policy: string): void {
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, DOUBLE_ESC_CANCEL_FILE), JSON.stringify({ schema: DOUBLE_ESC_CANCEL_SCHEMA, policy }));
+}
+
+const EMPTY_ENV = {} as Record<string, string | undefined>;
+
+test("the confirmation window is 1000ms, deliberately double Pi's own 500ms idle double-Esc window", () => {
+	assert.equal(DOUBLE_ESC_CANCEL_WINDOW_MS, 1000);
+});
+
+// --- strict decode ---------------------------------------------------------
+
+test("strict decode accepts exactly the v1 schema with policy on|off", () => {
+	assert.equal(parseDoubleEscCancelPolicyFile(`{"schema":"${DOUBLE_ESC_CANCEL_SCHEMA}","policy":"on"}`), "on");
+	assert.equal(parseDoubleEscCancelPolicyFile(`{"schema":"${DOUBLE_ESC_CANCEL_SCHEMA}","policy":"off"}`), "off");
+});
+
+test("strict decode rejects malformed shapes", () => {
+	for (const raw of [
+		"not json",
+		"[]",
+		"null",
+		'{"policy":"on"}',
+		'{"schema":"gentle-pi.double-esc-cancel/v2","policy":"on"}',
+		`{"schema":"${DOUBLE_ESC_CANCEL_SCHEMA}","policy":"ON"}`,
+		`{"schema":"${DOUBLE_ESC_CANCEL_SCHEMA}","policy":true}`,
+		`{"schema":"${DOUBLE_ESC_CANCEL_SCHEMA}","policy":"on","extra":1}`,
+	]) {
+		assert.equal(parseDoubleEscCancelPolicyFile(raw), undefined, `must reject: ${raw}`);
+	}
+});
+
+// --- cascade: global file > env > default off -------------------------------
+
+test("default is off with no file and no env", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	assert.equal(loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV }), "off");
+});
+
+test("the resolver reads GENTLE_PI_CONFIG_HOME from the given env, never from process.env", () => {
+	const root = makeScratch("gp-esc-envhome-");
+	writePolicyFile(root, "on");
+	const result = resolveDoubleEscCancelPolicy({ env: { GENTLE_PI_CONFIG_HOME: root } });
+	assert.equal(result.policy, "on");
+	assert.equal(result.globalFile, join(root, "double-esc-cancel.json"));
+});
+
+test("global file overrides env", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	writePolicyFile(configHome, "on");
+	assert.equal(
+		loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: { GENTLE_PI_DOUBLE_ESC_CANCEL: "off" } }),
+		"on",
+	);
+});
+
+test("env var applies only when no policy file exists, and only exact on|off", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	assert.equal(
+		loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: { GENTLE_PI_DOUBLE_ESC_CANCEL: "on" } }),
+		"on",
+	);
+	for (const invalid of ["1", "true", "ON", "yes", ""]) {
+		assert.equal(
+			loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: { GENTLE_PI_DOUBLE_ESC_CANCEL: invalid } }),
+			"off",
+			`env value "${invalid}" must fail closed to off`,
+		);
+	}
+});
+
+test("a malformed global file fails closed to off instead of falling through to env", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(join(configHome, DOUBLE_ESC_CANCEL_FILE), "{malformed");
+	assert.equal(
+		loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: { GENTLE_PI_DOUBLE_ESC_CANCEL: "on" } }),
+		"off",
+	);
+});
+
+// --- resolver attribution ---------------------------------------------------
+
+test("the resolver attributes the global file when it decides", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	writePolicyFile(configHome, "on");
+	const resolution = resolveDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV });
+	assert.deepEqual(resolution, {
+		policy: "on",
+		source: "global_file",
+		malformed: false,
+		globalFile: join(configHome, DOUBLE_ESC_CANCEL_FILE),
+		globalFileExists: true,
+		envValue: undefined,
+	});
+});
+
+test("the resolver attributes the environment variable when no file exists", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	const resolution = resolveDoubleEscCancelPolicy({
+		gentlePiConfigHome: configHome,
+		env: { GENTLE_PI_DOUBLE_ESC_CANCEL: "on" },
+	});
+	assert.equal(resolution.source, "environment");
+	assert.equal(resolution.policy, "on");
+	assert.equal(resolution.globalFileExists, false);
+});
+
+test("the resolver attributes the built-in default when nothing else decides", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	const resolution = resolveDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV });
+	assert.equal(resolution.source, "default");
+	assert.equal(resolution.policy, "off");
+	assert.equal(resolution.malformed, false);
+});
+
+test("the resolver attributes a malformed global file to that file and does not fall through", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	mkdirSync(configHome, { recursive: true });
+	writeFileSync(join(configHome, DOUBLE_ESC_CANCEL_FILE), "{malformed");
+	const resolution = resolveDoubleEscCancelPolicy({
+		gentlePiConfigHome: configHome,
+		env: { GENTLE_PI_DOUBLE_ESC_CANCEL: "on" },
+	});
+	assert.equal(resolution.source, "global_file");
+	assert.equal(resolution.policy, "off");
+	assert.equal(resolution.malformed, true);
+});
+
+test("loadDoubleEscCancelPolicy delegates to the resolver so the two can never disagree", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	writePolicyFile(configHome, "on");
+	assert.equal(
+		loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV }),
+		resolveDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV }).policy,
+	);
+});
+
+// --- writer -------------------------------------------------------------------
+
+test("writeDoubleEscCancelPolicy writes the strict v1 shape to the global file, creating the config home", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai", "nested");
+	const path = writeDoubleEscCancelPolicy("on", { gentlePiConfigHome: configHome });
+	assert.equal(path, join(configHome, DOUBLE_ESC_CANCEL_FILE));
+	assert.equal(loadDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV }), "on");
+});
+
+test("writeDoubleEscCancelPolicy(off) round-trips through the resolver", () => {
+	const configHome = join(makeScratch("gp-esc-home-"), "gentle-ai");
+	writeDoubleEscCancelPolicy("on", { gentlePiConfigHome: configHome });
+	writeDoubleEscCancelPolicy("off", { gentlePiConfigHome: configHome });
+	const resolution = resolveDoubleEscCancelPolicy({ gentlePiConfigHome: configHome, env: EMPTY_ENV });
+	assert.equal(resolution.policy, "off");
+	assert.equal(resolution.source, "global_file");
+	assert.equal(resolution.malformed, false);
+});