gentle-pi 2.3.0 → 2.5.0

package/tests/codegraph-tools.test.ts

@@ -1,12 +1,14 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import codeGraphTools, {
 	createCodeGraphTool,
+	codeGraphNodeScript,
+	findCodeGraphNodeScriptOnPath,
 	type CodeGraphRunner,
 } from "../extensions/codegraph-tools.ts";
 
@@ -211,3 +213,110 @@ test("CodeGraph tool registration exposes a single constrained custom tool", ()
 		},
 	});
 });
+
+function writeCodeGraphPackage(binDir: string, scriptSource = "#!/usr/bin/env node\n"): string {
+	const pkgRoot = join(binDir, "node_modules", "@colbymchenry", "codegraph");
+	mkdirSync(pkgRoot, { recursive: true });
+	const scriptTarget = join(pkgRoot, "npm-shim.js");
+	writeFileSync(scriptTarget, scriptSource);
+	writeFileSync(
+		join(pkgRoot, "package.json"),
+		JSON.stringify({
+			name: "@colbymchenry/codegraph",
+			version: "1.0.0",
+			bin: { codegraph: "npm-shim.js" },
+		}),
+	);
+	writeFileSync(
+		join(binDir, "codegraph.cmd"),
+		"@ECHO off\nnode \"%~dp0\\node_modules\\@colbymchenry\\codegraph\\npm-shim.js\" %*\n",
+	);
+	return scriptTarget;
+}
+
+function withWindowsPath(t: test.TestContext, path: string): void {
+	const previousPath = process.env.PATH;
+	const previousWindowsPath = process.env.Path;
+	const windowsPath = process.platform === "win32"
+		? `${path};${previousWindowsPath ?? previousPath ?? ""}`
+		: path;
+	process.env.Path = windowsPath;
+	process.env.PATH = windowsPath;
+	t.after(() => {
+		if (previousPath === undefined) delete process.env.PATH;
+		else process.env.PATH = previousPath;
+		if (previousWindowsPath === undefined) delete process.env.Path;
+		else process.env.Path = previousWindowsPath;
+	});
+}
+
+test("Windows shim helpers skip stale PATH shims before resolving the npm script", (t) => {
+	const staleBinDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-stale-bin-")));
+	const validBinDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-valid-bin-")));
+	t.after(() => rmSync(staleBinDir, { recursive: true, force: true }));
+	t.after(() => rmSync(validBinDir, { recursive: true, force: true }));
+	writeFileSync(join(staleBinDir, "codegraph.cmd"), "@ECHO off\n");
+	const stalePkgRoot = join(staleBinDir, "node_modules", "@colbymchenry", "codegraph");
+	mkdirSync(stalePkgRoot, { recursive: true });
+	writeFileSync(join(stalePkgRoot, "package.json"), JSON.stringify({ bin: { codegraph: "." } }));
+	const scriptTarget = writeCodeGraphPackage(validBinDir);
+
+	withWindowsPath(t, `${staleBinDir};${validBinDir}`);
+
+	assert.equal(codeGraphNodeScript(join(staleBinDir, "codegraph.cmd")), undefined);
+	assert.equal(findCodeGraphNodeScriptOnPath(), scriptTarget);
+});
+
+test("Windows shim helpers resolve quoted PATH entries in order without stripping unmatched quotes", (t) => {
+	const root = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-quoted-bin-")));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const firstBin = join(root, "Program Files", "nodejs");
+	const secondBin = join(root, "other-bin");
+	const firstScript = writeCodeGraphPackage(firstBin);
+	const secondScript = writeCodeGraphPackage(secondBin);
+	withWindowsPath(t, `"${firstBin}";${secondBin}`);
+
+	assert.equal(findCodeGraphNodeScriptOnPath(), firstScript);
+	for (const [path, expected] of [
+		[`${firstBin};"${secondBin}"`, firstScript],
+		[`"${firstBin};${secondBin}`, secondScript],
+		[`${firstBin}";${secondBin}`, secondScript],
+		[`${secondBin};"${firstBin}"`, secondScript],
+	]) {
+		process.env.Path = path;
+		process.env.PATH = path;
+		assert.equal(findCodeGraphNodeScriptOnPath(), expected);
+	}
+});
+
+test("Windows launcher passes command metacharacters as one literal argv value", async (t) => {
+	const binDir = realpathSync(mkdtempSync(join(tmpdir(), "gentle-pi-codegraph-bin-")));
+	t.after(() => rmSync(binDir, { recursive: true, force: true }));
+	writeCodeGraphPackage(binDir, "process.stdout.write(JSON.stringify(process.argv.slice(2)));\n");
+	const cwd = workspace(t);
+	if (process.platform !== "win32") {
+		const gitShim = join(binDir, "git");
+		writeFileSync(gitShim, "#!/bin/sh\nprintf '%s\\n' \"$PWD\"\n");
+		chmodSync(gitShim, 0o755);
+	}
+	withWindowsPath(t, binDir);
+
+	const previousPlatform = process.platform;
+	Object.defineProperty(process, "platform", { configurable: true, value: "win32" });
+	t.after(() => Object.defineProperty(process, "platform", { configurable: true, value: previousPlatform }));
+
+	const query = "literal & echo injected > shell-injection.txt";
+	const result = await createCodeGraphTool().execute(
+		"test",
+		{ operation: "query", query },
+		undefined,
+		undefined,
+		{ cwd } as ExtensionContext,
+	);
+
+	assert.deepEqual(result.content, [{
+		type: "text",
+		text: JSON.stringify(["query", "--path", cwd, "--limit", "10", "--", query]),
+	}]);
+	assert.equal(existsSync(join(cwd, "shell-injection.txt")), false);
+});

package/tests/devbinary/native-review-parity.devtest.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { __testing } from "../../extensions/gentle-ai.ts";
+import { CandidateViewRegistry } from "../../lib/review-candidate-view.ts";
 import {
 	NATIVE_REVIEW_ERROR_CODE,
 	NativeReviewCliError,
@@ -13,6 +14,7 @@ import {
 	createNodeExecFileAdapter,
 	type ExecFileAdapter,
 } from "../../lib/native-review-cli.ts";
+import type { ReviewStatusV3 } from "../../lib/review-integration-v2.ts";
 import { requireDevBinary } from "../support/native-binary-gate.ts";
 
 // Organic RDD Parity: candidate-bound dev-binary journeys.
@@ -43,6 +45,35 @@ function bridgeAdapter(binary: string, calls: NativeCall[]): ExecFileAdapter {
 	};
 }
 
+function selectedStatusFieldNames(stdout: string): string {
+	try {
+		const status = JSON.parse(stdout) as Record<string, unknown>;
+		const projection = status.projection as Record<string, unknown> | undefined;
+		const transition = status.next_transition as Record<string, unknown> | undefined;
+		const execute = transition?.execute as Record<string, unknown> | undefined;
+		const argument = Array.isArray(execute?.arguments) ? execute.arguments[0] as Record<string, unknown> | undefined : undefined;
+		const names = (prefix: string, value?: Record<string, unknown>) => value === undefined ? [] : Object.keys(value).sort().map((key) => `${prefix}.${key}`);
+		return [...names("status", status), ...names("status.projection", projection), ...names("status.next_transition", transition), ...names("status.next_transition.execute", execute), ...names("status.next_transition.execute.arguments[]", argument)].join(", ");
+	} catch {
+		return "status JSON";
+	}
+}
+
+function controllerResultStructure(result: Record<string, unknown>): string {
+	const diagnostics = typeof result.diagnostics === "object" && result.diagnostics !== null && !Array.isArray(result.diagnostics)
+		? result.diagnostics as Record<string, unknown>
+		: undefined;
+	const safeCode = (name: string, value: unknown) => typeof value === "string" && /^[a-z0-9][a-z0-9._-]*$/.test(value) ? `${name}=${value}` : undefined;
+	const safeBooleanNames = ["candidate_view_created", "candidate_view_pre_native", "native_invocation_attempted", "lineage_created", "mutation_performed", "reset_eligible"];
+	return [
+		`keys=[${Object.keys(result).sort().join(",")}]`,
+		...(diagnostics === undefined ? [] : [`diagnostics.keys=[${Object.keys(diagnostics).sort().join(",")}]`]),
+		safeCode("operation", result.operation), safeCode("status", result.status), safeCode("outcome", result.outcome), safeCode("reason", result.reason),
+		safeCode("diagnostics.error_code", diagnostics?.error_code), safeCode("diagnostics.code", diagnostics?.code), safeCode("diagnostics.reason", diagnostics?.reason),
+		...safeBooleanNames.flatMap((name) => typeof result[name] === "boolean" ? [`${name}=${String(result[name])}`] : []),
+	].filter((value): value is string => value !== undefined).join("; ");
+}
+
 function journeyNative(binary: string): { native: NativeReviewCliV216; calls: NativeCall[] } {
 	const calls: NativeCall[] = [];
 	return { native: new NativeReviewCliV216(bridgeAdapter(binary, calls), binary), calls };
@@ -202,6 +233,83 @@ test("dev-binary: an empty candidate exposes the current STATUS refusal and neve
 	assert.equal(calls.filter((arguments_) => arguments_.at(0) === "review" && arguments_.at(1) === "start").length, 0);
 });
 
+test("dev-binary: v7 intended-untracked selection decodes both selected statuses before START", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
+	git(cwd, "add", "app.ts");
+	git(cwd, "commit", "-qm", "test: base candidate");
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	writeFileSync(join(cwd, "chosen.md"), "# Chosen\n");
+
+	const calls: NativeCall[] = [], selectedWireFields: string[] = [];
+	let interceptedStarts = 0;
+	let delegatedStarts = 0;
+	const startIntercept = new Error("test-only native START intercept");
+	const real = createNodeExecFileAdapter();
+	const adapter: ExecFileAdapter = async (request) => {
+		calls.push([...request.arguments]);
+		if (request.arguments.at(0) === "review" && request.arguments.at(1) === "start") {
+			interceptedStarts += 1;
+			throw startIntercept;
+		}
+		if (request.arguments.at(0) === "review" && request.arguments.at(1) === "start") delegatedStarts += 1;
+		const result = await real({ ...request, file: DEV_BINARY! });
+		if (request.arguments.some((argument) => argument.startsWith("--intended-untracked-selection="))) selectedWireFields.push(selectedStatusFieldNames(result.stdout));
+		return result;
+	};
+	const native = new NativeReviewCliV216(adapter, DEV_BINARY!);
+	const targetStatus = native.targetStatus.bind(native);
+	const selectedStatuses: ReviewStatusV3[] = [];
+	const selectedFailures: Array<{ call: number; code: string }> = [];
+	let selectedStatusCalls = 0;
+	native.targetStatus = async (request) => {
+		if (request.intendedUntrackedSelection === undefined) return targetStatus(request);
+		selectedStatusCalls += 1;
+		try {
+			const status = await targetStatus(request);
+			selectedStatuses.push(status);
+			return status;
+		} catch (error) {
+			selectedFailures.push({ call: selectedStatusCalls, code: error instanceof NativeReviewCliError ? error.code : "unexpected-error" });
+			throw error;
+		}
+	};
+
+	const candidateViews = new CandidateViewRegistry(), retainedSelections = new Map();
+	await enableReview(native, cwd);
+	const initial = await __testing.executeReviewControllerOperation({ operation: "status" }, cwd, native, undefined, candidateViews, undefined, retainedSelections);
+	assert.equal((initial.result as Record<string, unknown> | undefined)?.schema, "gentle-ai.review-integration.status/v7", "initial status.schema");
+	assert.equal(typeof initial.selectionBinding, "string", "initial selectionBinding");
+	const result = await __testing.executeReviewControllerOperation({ operation: "select-intended-untracked", selectionBinding: initial.selectionBinding as string, intendedUntracked: ["chosen.md"] } as never, cwd, native, undefined, candidateViews, undefined, retainedSelections);
+
+	if (selectedStatusCalls !== 2) assert.fail(`intended-selection STATUS call count=${selectedStatusCalls}; ${controllerResultStructure(result)}`);
+	if (selectedFailures.length > 0) {
+		const failure = selectedFailures[0]!;
+		assert.fail(`selected STATUS call ${failure.call} decode failed at fields: ${selectedWireFields[failure.call - 1] ?? "status"}; error=${failure.code}`);
+	}
+	assert.equal(selectedStatusCalls, 2, "intended-selection STATUS call count");
+	assert.equal(selectedStatuses.length, 2, "decoded intended-selection STATUS count");
+	for (const [index, status] of selectedStatuses.entries()) {
+		assert.equal(status.raw.schema, "gentle-ai.review-integration.status/v7", `selected STATUS call ${index + 1} status.schema`);
+		assert.deepEqual(status.projection.intendedUntracked, ["chosen.md"], `selected STATUS call ${index + 1} status.projection.intended_untracked`);
+		assert.equal(status.nextTransition?.kind, "execute", `selected STATUS call ${index + 1} status.next_transition.kind`);
+		assert.equal(status.nextTransition?.execute?.operation, "review.start", `selected STATUS call ${index + 1} status.next_transition.execute.operation`);
+		assert.ok((status.nextTransition?.execute?.arguments.length ?? 0) > 0, `selected STATUS call ${index + 1} status.next_transition.execute.arguments`);
+		assert.equal(status.nextTransition?.execute?.arguments.every((argument) => typeof argument.token === "string" && argument.token.length > 0), true, `selected STATUS call ${index + 1} status.next_transition.execute.arguments[].token`);
+	}
+	assert.equal(interceptedStarts, 1, "adapter must intercept the one native review.start attempt");
+	assert.equal(delegatedStarts, 0, "intercepted native START must not reach the real adapter");
+	assert.equal(calls.filter((arguments_) => arguments_.at(0) === "review" && arguments_.at(1) === "start").length, 1, "native review.start adapter attempt count");
+	assert.equal(result.outcome, "native-mutation-status-reconciled", "controller result after intentional START intercept");
+	assert.equal("lineage_id" in result, false, "intercepted START must report no lineage binding");
+	assert.equal("authority" in result, false, "intercepted START must report no authority binding");
+	assert.equal("lineage_created" in result, false, "reconciled unknown mutation must not claim lineage creation");
+	assert.equal("mutation_performed" in result, false, "reconciled unknown mutation must not claim a mutation result");
+	assert.equal(result.mutation_outcome, "unknown", "the controller cannot prove mutation status after an intercepted launch");
+	const after = await native.targetStatus({ cwd, agent: "pi" });
+	assert.equal(after.authority, undefined, "post-intercept STATUS must not expose authority");
+});
+
 test("dev-binary: a low-risk START closes the review with no receipt or follow-up capture", { skip: !RUNNABLE }, async (t) => {
 	const cwd = repository(t);
 	writeFileSync(join(cwd, "guide.md"), "# Guide\n\nBase\n");

package/tests/fixtures/agents-process-child.mjs

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+
+const descendant = spawn(process.execPath, ["-e", "process.on('SIGTERM', () => {}); process.stdout.write('ready'); setInterval(() => {}, 1000);"], { stdio: ["ignore", "pipe", "ignore"] });
+descendant.stdout.once("data", () => {
+	console.log(`DESCENDANT:${descendant.pid}`);
+	if (process.env.AGENTS_PROCESS_CHILD_EXIT_AFTER_READY === "1") process.exit(0);
+});
+process.on("SIGTERM", () => {
+	if (process.env.AGENTS_PROCESS_CHILD_EXIT_ON_TERM === "1") process.exit(0);
+});
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	for (const line of chunk.split("\n")) {
+		if (!line) continue;
+		try {
+			const command = JSON.parse(line);
+			process.stdout.write(`${JSON.stringify({ type: "response", id: command.id, success: true })}\n`);
+		} catch {
+			// Ignore malformed input; the runner owns the RPC protocol.
+		}
+	}
+});
+setInterval(() => {}, 1000);

package/tests/fixtures/provider-contract-bundle/v1.2.0/README.md

@@ -0,0 +1,22 @@
+# Gentle AI review provider contract
+
+This data-only bundle describes the provider result contracts admitted by Gentle AI.
+
+## Activation
+
+1. Verify the signed release checksum manifest before using this archive.
+2. Verify every listed file hash and the transport capability before activation.
+3. Confirm your runtime identity appears in the manifest's registered runtimes before trusting the layout.
+4. Pass the Go-materialized opaque prompt to the provider and return only raw output or an error.
+
+## Orchestration
+
+manifest.json's orchestration array lists, for closed runtimes only, one
+orchestration/<runtime>.md file: the exact review execution contract text
+Gentle AI's own installer would have spliced into that runtime's system
+prompt, for a runtime whose adapter has no system prompt to splice it into.
+It carries no executable content, same as every other file in this bundle: a
+runtime mirrors and delivers the text as-is and still relies on Go for every
+review decision, prompt, receipt, and delivery gate.
+
+Go remains the admission authority for prompts, results, receipts, and delivery gates.

package/{contracts/review-provider-contract-mirror/v1.1.0/bundle → tests/fixtures/provider-contract-bundle/v1.2.0}/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-ai.review-provider-contract-bundle/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "runtimes": [
     "claude-code",
@@ -10,7 +10,7 @@
   ],
   "readme": {
     "path": "README.md",
-    "sha256": "d14647c8753bd85e18b8a593bef9dfcb4c9d8ea01e32ecd36847dc4304027b1d"
+    "sha256": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085"
   },
   "roles": [
     {
@@ -61,5 +61,14 @@
         "sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
       }
     }
+  ],
+  "orchestration": [
+    {
+      "runtime": "pi",
+      "file": {
+        "path": "orchestration/pi.md",
+        "sha256": "54fba57b11b280f56f7f15e91ddad3d844c70e0127e5c1adeff0a9d1b7a98e64"
+      }
+    }
   ]
 }

package/tests/fixtures/provider-contract-bundle/v1.2.0/orchestration/pi.md

@@ -0,0 +1,97 @@
+# Native Compact Review Orchestration
+
+**When a final capture returns `status_continuation`, execute its operation and ordered argument tokens unchanged. Do not reconstruct lifecycle selectors from retained prose or transcript state.**
+
+The parent orchestrator coordinates one native transaction; reviewers, refuters, correction actors, and validators receive only their provider-issued role input. Prompt prose never creates authority or decides delivery.
+
+## Entry rule
+
+Enter this lifecycle once per candidate, after an authorized source-mutating implementation is complete and normalized and before reporting it complete, whenever the user-owned review switch is enabled (`gentle-ai review mode status` reads it without changing it). Run the selectorless STATUS in step 1 and route only from its returned `next_transition`; the START consent envelope lets the human decide this candidate, so never skip the preflight because the user did not ask for a review. Skip it only for a trivial passive documentation-only edit, when the user explicitly left this candidate unreviewed, or while a transaction is already bound to it. A runtime that runs this preflight itself hands the agent the exact returned START tokens and never runs START.
+
+## Atomic lifecycle
+
+1. **Preflight only.** Selectorless STATUS only preflights the current worktree candidate and returns one exact START invocation. It never discovers, resumes, recovers, or evaluates ambient authority from another lineage or worktree: `gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --agent pi --next-transition`.
+
+2. **Freeze once.** Invoke only the returned START operation and its ordered tokens unchanged. START freezes one compact atomic transaction with an explicit lineage, worktree, and target binding. It ignores every other lineage and worktree. Capture the returned lineage, revision, and target tokens. An exact replay of an active START may return `replayed`; a genuinely new START is independent.
+
+3. **Stay bound.** A reviewing START carries `next_transition.execute(review.status)` — the provider-issued re-entry for its frozen binding: run that provider-issued command verbatim, with the repository as process cwd, and satisfy every later STATUS and collection call only with the exact tokens each returned transition names. Route only from that transaction's returned `next_transition`; the root `action` field is informational. Never infer a command from prose, ambient state, a gate, or a stale reply. Do not start another lineage, reuse an acknowledged-and-burned lineage, or perform ambient recovery. For `execute`, run the exact operation and ordered arguments. For `collect`, satisfy only the named inputs and their exact capture operations, then ask STATUS again with the same binding. For `stop`, run no lifecycle operation.
+
+4. **Acknowledge exactly.** Native Go owns frozen lenses, provider context and admission, refutation, one bounded correction, repository evidence, targeted validation, and approved closure. A final approved capture commits one pending acknowledgement token and returns `review.acknowledge-approved`; restarted STATUS returns the same operation, ordered arguments, token, and live revision. Only that exact invocation burns authority and artifacts, and on success it prints one `gentle-ai.review-acknowledged/v1` envelope; report the burn from that envelope, never from a later STATUS. Wrong, stale, or replayed acknowledgement refuses without creating a receipt, tombstone, witness, mirror, sidecar, or delivery authority. Unrelated transactions survive unchanged.
+
+The final reviewer, refuter, or targeted-validator capture owns closure. A malformed, incomplete, or unavailable capture never reaches acknowledgement: issue one retained target-bound read-only STATUS and relaunch only when it reoffers the same bound slot. Never invent a binding or retry from prose.
+
+When v2 returns `forecast`, relay it losslessly in the user's language: preserve every step's order and fields (`step`, `kind`, `reason_code`, `description`) and the horizon. Forecast is informational; route only from `next_transition`.
+
+### Cross-repository lifecycle root
+
+A session in repository A may review an explicitly selected nested target in unrelated repository B only after explicit user authorization. Native Go resolves the requested path to the canonical B worktree root; adapters never parse authorization or roots.
+
+- After B is selected, retain canonical B as the lifecycle working root from selectorless STATUS through consent, collection, correction, targeted validation, acknowledgement, and burn. Do not fall back to A.
+- Run provider-issued command tokens exactly. Never append, remove, or rebuild provider-issued command tokens. When a command omits `--cwd`, run it with process cwd B.
+- Opaque `repository_context` can capture or materialize from any process cwd, but the host still retains B for lifecycle continuity. Go owns repository binding; adapters never parse authorization or roots.
+- The same lineage text in A and B is independent. Approval awaits acknowledgement in B; exact acknowledgement burns B only, and A remains untouched.
+
+This lifecycle is rendered for exactly Claude Code, Codex, OpenCode, and Pi. Unsupported runtimes remain unavailable before repository or authority mutation.
+
+## Capture and correction
+
+For each returned `review.capture-result` input, run the exact capture operation once. The reviewer prompt begins with the exact literal prefix `GENTLE_AI_REVIEW_BINDING ` (trailing space, never `=`), followed by one-line JSON assembled only from that input: `lineage`, `target`, `lens`, `order`, `revision` from `expected-revision`, `repository_context`, and `subject_hash` from `artifact_subject.subject_hash`; omit only provider-omitted fields. Return one JSON object that echoes `subject_hash`, reports completed inspection of every manifest path in order, and contains findings/evidence with severe evidence class and causality. Access failure is incomplete inspection, never completion.
+
+After an empty, malformed, schema-invalid, access/provider-failed, or incomplete capture, query the same exact-lineage STATUS. Relaunch only if its fresh `next_transition` reoffers the same bound slot. Never infer a retry from transcript text. A relayed capture passes its result through `--input <path|->`, one per lens in lens order; BOM-less UTF-8 is required on Windows PowerShell 5.1. Tokens carrying `--agent` capture in process with no `--input`.
+
+Only candidate-caused severe findings block. Pre-existing/base-only findings are follow-ups; unknown causality escalates. A deterministic blocker needs no refuter; inferential blockers share one read-only refuter batch. A four-lens review is long work: before its first lens, give one forecast covering four reviewer runs, the frozen correction budget, and the at-most-one bounded correction.
+
+A correction is native-scoped. When the final reviewer or refuter capture opens `correction_required`, its `status_continuation` is the only re-entry: run its `review.status` operation and ordered tokens unchanged before acting again. Native Go maps edits only to corroborated frozen findings, owns repository evidence and the targeted validator, and permits at most one bounded correction. A validator that cannot inspect the immutable trees produced no verdict: surface one blocked human decision and submit nothing. Do not route it to a refuter or another actor without read-only immutable-tree access. Independent requirements/runtime verification never starts another reviewer, refuter, correction, or validator.
+
+## Consent and immutable inspection
+
+If exact provider-returned START returns the typed `gentle-ai.review-integration.consent/v3` envelope, relay it as a Lossless Blocking Prompt. Global RDD enabled permits review; it never grants consent for this candidate. For medium/high candidates, faithfully translate the headline, reason, `value`, risk evidence, choice labels, every choice `effect`, and the off-path note while preserving original groups/order, selection mode, allowed-answer domain, answer tokens, commands, target IDs, and invocations. Project `value` as benefits and every `effect` as consequences. Do not translate machine answer tokens (`granted`, `declined`). Run exactly the invocation selected by the human; a decline is candidate-scoped and is not the kill switch.
+
+Claude Code, OpenCode, Codex, and Pi use the shared Go provider contract. Go owns frozen evidence, binding, schema, byte bounds, validation, admission, and capture; runtime adapters transport opaque provider output. Claude uses a tool-free fresh reviewer; OpenCode relays one host Task through its live Go transport; Codex uses its provider-bound subprocess; Pi uses its gentle-pi-owned relay. Compiled capability is authoritative before repository, target, authority, collection, or process work.
+
+Reviewers inspect only the provider-bound immutable trees. Never hand candidate bytes through `/tmp`, an external file, a repository scratch file, or `GENTLE_AI_FROZEN_CANDIDATE_CONTEXT`. Use the provider-issued inspection path, never the live worktree, index, `HEAD`, or an unbound revision. Never pass `--binary`, change checkout, or substitute live files.
+
+<!-- authority-first-terminal-procedure:start -->
+### Authority-First Terminal Procedure
+
+| Order | Operation | Required result |
+| --- | --- | --- |
+| 01 | canonical initial STATUS above | exactly one current-worktree START preflight; no authority discovery |
+| 02 | exact returned START | one compact lineage/worktree/target binding; retain lineage, revision, and target |
+| 03 | exact-lineage STATUS and collect | only returned transaction actions; no ambient resume, reuse, or delivery gate |
+| 04 | final admitted capture | native readback, approved authority, and one exact acknowledgement continuation |
+| 05 | STATUS restart + exact acknowledgement | replayed operation/token/revision; only exact acknowledgement burns authority |
+| 06 | terminal lifecycle stop | ordinary repository policy owns any later delivery decision |
+
+<!-- authority-first-terminal-procedure:end -->
+
+### Continue after a stop reason code
+
+A `stop` ends its transition, never approves delivery. Complete atomic inventory: B stays target root; gates stay unmanaged. `D` means `gentle-ai review mode disable --scope clone --cwd <B>`; B ordinary policy decides delivery. `S` means re-query the exact captured target-root STATUS command with lineage and target.
+
+| Reason codes | Continuation |
+| --- | --- |
+| `captured_artifacts_unverifiable` | Terminal — maintainer inspects B authority, or `D`. |
+| `captured_result_selection_unavailable` | Terminal — maintainer inspects lineage, or `D`. |
+| `missing_authority_binding` | Terminal — file a bounded defect with lineage, or `D`. |
+| `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal — maintainer inspects authority/lineage, or `D`. |
+| `empty_base_diff_bootstrap_required` | Terminal — authorized empty-root bootstrap for a new target, or `D`. |
+| `lens_context_budget_exceeded` | Terminal — reduce B scope and start a new transaction, or `D`. |
+| `staged_workspace_overlay_recovery_unavailable` | Terminal — pass `--lineage <id>` to recover, or drop `--workspace-overlay` and start fresh; otherwise `D`. |
+| `corrected_candidate_unavailable` | Change B correction candidate, then `S`; do not reuse the pre-correction target. |
+| `recovery_scope_unchanged` | Change B target identity, then retry the exact returned `gentle-ai review recover`. |
+| `rdd_disabled` | `--scope clone` only clears a clone-local off; `gentle-ai review mode enable --scope global`, then `S`. |
+
+## Delivery follows ordinary repository policy
+
+Shipped `review validate` and gate commands are compatibility/informational only. They never discover authority or decide delivery: enabled gates return `invalidated/unmanaged`; disabled gates return `disabled/unmanaged`. They never allow, approve, block, commit, push, open a PR, or govern release.
+
+After exact acknowledgement burns terminal `approved` authority, the review lifecycle stops. Commit, push, PR, and release remain separate human decisions under ordinary repository policy. A review outcome is informational and never authorizes delivery, including when the selected repository is B.
+
+Historical compatibility commands may read older artifacts manually, but they are never the ordinary lifecycle and never restore delivery authority.
+
+### Concurrent Reviewer Group (MANDATORY)
+
+When one fresh `collect.inputs` set contains multiple distinct independent `review.capture-result` reviewer slots, launch every returned capture operation concurrently in provider order: start all without waiting between launches, then wait for every result. For canonical 4R, preserve `review-risk`, `review-resilience`, `review-readability`, `review-reliability` order.
+
+Each launch runs only its own provider-issued `review.capture-result` argument tokens exactly as returned. Completion order is not authority: shared Go admission/election owns reduction and semantics. The final admitted capture owns reduction and closure. On `approved`, authority is already burned: do not FINALIZE or issue a trailing STATUS. On `correction_required`, continue only through exact bound STATUS and the provider-issued `review.capture-correction-plan` binding. After a malformed or nonterminal capture, reconcile through exact bound STATUS and retry only an identically reoffered slot.

package/tests/fixtures/provider-contract-bundle/v1.2.0/schemas/lens.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/schema/review/reviewer/v1",
+  "title": "Gentle AI reviewer result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subject_hash", "inspection", "findings", "evidence"],
+  "properties": {
+    "subject_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "inspection": {"type": "object", "additionalProperties": false, "required": ["status", "paths"], "properties": {"status": {"const": "completed"}, "paths": {"type": "array", "description": "Complete unique unordered set of every changed_path_manifest.path.", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}},
+    "lens": {"type": "string", "description": "Optional selected lens binding. Omission canonicalizes to the selected subject lens.", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]},
+    "findings": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["location", "severity", "claim", "proof_refs"], "allOf": [{"if": {"properties": {"severity": {"enum": ["BLOCKER", "CRITICAL"]}}, "required": ["severity"]}, "then": {"required": ["evidence_class", "causal_disposition"]}}], "properties": {"id": {"type": "string", "pattern": "^R[1-4]-[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "Optional explicit ID; omit it to receive a native-assigned ID. When present it must carry the prefix bound to the selected lens, not the selection order: review-risk=R1-, review-readability=R2-, review-reliability=R3-, review-resilience=R4-."}, "lens": {"type": "string", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]}, "location": {"type": "string", "description": "One canonical repository-relative path:line or inclusive path:start-end span.", "pattern": "^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"}, "severity": {"type": "string", "enum": ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"]}, "claim": {"type": "string", "minLength": 1}, "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}, "evidence_class": {"type": "string", "enum": ["deterministic", "inferential", "insufficient"]}, "causal_disposition": {"type": "string", "enum": ["introduced", "behavior-activated", "worsened", "pre-existing", "base-only", "unknown"]}}}},
+    "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}
+  },
+  "examples": [{"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "completed", "paths": ["internal/example.go"]}, "findings": [], "evidence": ["reviewed the complete candidate scope"]}]
+}

package/tests/fixtures/provider-contract-bundle/v1.2.0/schemas/refuter.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/refuter/v1","title":"Gentle AI refuter result","type":"object","additionalProperties":false,"required":["refuter_request_hash","results"],"properties":{"refuter_request_hash":{"$ref":"#/$defs/sha256"},"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["finding_id","outcome","proof_refs"],"properties":{"finding_id":{"type":"string"},"outcome":{"type":"string","enum":["corroborated","refuted","inconclusive"]},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}},"examples":[{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/lens.json

@@ -0,0 +1 @@
+{"subject_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","inspection":{"status":"completed","paths":["internal/example.go"]},"findings":[],"evidence":["reviewed the complete candidate scope"]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/refuter.json

@@ -0,0 +1 @@
+{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/targeted-validator.json

@@ -0,0 +1 @@
+{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}