gentle-pi 2.1.2 → 2.2.0

package/tests/maintainer/provider-relay.maintest.ts

@@ -0,0 +1,265 @@
+// Maintainer provider-relay matrix — behavior-first tests (gentle-pi#311).
+//
+// `pnpm test` never picks this up: it globs `tests/*.test.ts` only, and this
+// file lives one directory deeper and ends in `.maintest.ts`. It runs only
+// via `pnpm run test:maintainer`. Strict validation + no-production-resolution
+// always run; real-binary tests run only when env-supplied maintainer binaries
+// exist (self-skip; fail-loud under GENTLE_PI_REQUIRE_MAINTAINER=1). Never fakes
+// green. Tests never hardcode machine-specific paths; the verifier supplies
+// them via env. The baseline is described generically; external evidence
+// establishes whether it is the immutable RC8 runtime.
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, runReviewHostRelaySlot } from "../../lib/review-host-relay.ts";
+import { ARM_POSITIVE_ENV, CASE_KINDS, DESCRIPTOR_SCHEMA, DescriptorValidationError, POSITIVE_JOURNEY_COMMAND, loadDescriptor, resolveDeclaredExecutable, runMatrix, validateDescriptor } from "../../scripts/maintainer/provider-relay-matrix.mjs";
+const BASELINE_ENV = "GENTLE_PI_MAINTAINER_BASELINE_BINARY";
+const CAPABLE_ENV = "GENTLE_PI_MAINTAINER_CAPABLE_BINARY";
+const REQUIRE_ENV = "GENTLE_PI_REQUIRE_MAINTAINER";
+// Every declared-but-nonexistent executable path these tests use lives inside
+// one private sandbox. A predictable /tmp path is squattable: another user can
+// pre-create it between runs, and a test that resolves it would then spawn a
+// file it never wrote. mkdtemp's unpredictable name plus 0700 removes that.
+const SANDBOX = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-sandbox-"));
+chmodSync(SANDBOX, 0o700);
+process.on("exit", () => rmSync(SANDBOX, { recursive: true, force: true }));
+const sandboxPath = (name: string) => join(SANDBOX, name);
+const PLACEHOLDER_BINARY = sandboxPath("not-a-real-gentle-ai-binary");
+const baselineBinary = process.env[BASELINE_ENV];
+const capableBinary = process.env[CAPABLE_ENV];
+const armed = process.env[REQUIRE_ENV] === "1";
+
+const BINDING_TOKENS = Object.freeze([
+	"--lineage=review-1d5aadacc600e167",
+	`--expected-revision=sha256:${"c".repeat(64)}`,
+	`--target=sha256:${"d".repeat(64)}`,
+	`--repository-context=rctx1_${"e".repeat(64)}`,
+	"--lens=review-reliability",
+	"--order=0",
+	`--subject-hash=sha256:${"a".repeat(64)}`,
+]);
+const CAPTURE_TOKENS = Object.freeze([...BINDING_TOKENS, "--agent=pi", "--materialize=true"]);
+const SUBMISSION = Object.freeze({
+	operationToken: "capture-result",
+	argumentTokens: Object.freeze([...BINDING_TOKENS, "--input={{value}}"]),
+	values: Object.freeze([{ slot: "reviewer_result", domain: "artifact_path_or_stdin", substitutionLocation: BINDING_TOKENS.length }]),
+});
+
+function descriptor(overrides = {}) {
+	return {
+		schema: DESCRIPTOR_SCHEMA,
+		gentleAiExecutable: PLACEHOLDER_BINARY,
+		piExecutable: "pi",
+		cases: [{ name: "baseline-negative-control", kind: "relay-unavailable", captureArgumentTokens: [...CAPTURE_TOKENS], submission: structuredClone(SUBMISSION) }],
+		...overrides,
+	};
+}
+function rejects(obj, fragment) {
+	assert.throws(() => validateDescriptor(obj), (error) => error instanceof DescriptorValidationError && error.message.includes(fragment));
+}
+function tempDescriptor(t, obj) {
+	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-"));
+	t.after(() => rmSync(directory, { recursive: true, force: true }));
+	const path = join(directory, "d.json");
+	writeFileSync(path, JSON.stringify(obj));
+	return path;
+}
+
+// ---------------------------------------------------------------------------
+// Strict descriptor validation — exact shape, no defaults, no production
+// resolution. Pure/deterministic; always runs.
+// ---------------------------------------------------------------------------
+test("valid descriptor validates and returns a normalized copy", () => {
+	const d = validateDescriptor(descriptor());
+	assert.equal(d.schema, DESCRIPTOR_SCHEMA);
+	assert.deepEqual(d.cases[0]!.captureArgumentTokens, [...CAPTURE_TOKENS]);
+	assert.deepEqual(d.cases[0]!.submission.values, SUBMISSION.values);
+});
+test("rejects malformed descriptor fields with exact-shape errors (no defaults, no production resolution)", () => {
+	rejects({ ...descriptor(), schema: "gentle-pi.maintainer.provider-relay-descriptor/v2" }, "descriptor.schema must be exactly");
+	rejects({ ...descriptor(), gentleAiExecutable: "gentle-ai" }, "absolute path");
+	rejects({ ...descriptor(), gentleAiExecutable: undefined }, "absolute path");
+	rejects({ ...descriptor(), extra: 1 }, "descriptor.extra");
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, extra: 1 }] }, "extra");
+	assert.deepEqual([...CASE_KINDS], ["relay-unavailable", "positive-lens"]);
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, kind: "bogus" }] }, "kind must be one of");
+	const dup = { ...descriptor().cases[0]!, name: "dup" };
+	rejects({ ...descriptor(), cases: [structuredClone(dup), structuredClone(dup)] }, "duplicated");
+	// Every case must declare the real provider-issued materialize slot.
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, captureArgumentTokens: [...CAPTURE_TOKENS].filter((t) => t !== "--agent=pi") }] }, "--agent=pi");
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, captureArgumentTokens: [...CAPTURE_TOKENS].filter((t) => t !== "--materialize=true") }] }, "--materialize=true");
+});
+test("submission is validated through the real relay resolver before any process launches (exact shape)", () => {
+	const twoValues = structuredClone(SUBMISSION);
+	twoValues.values = [...SUBMISSION.values, { slot: "extra", domain: "artifact_path_or_stdin", substitutionLocation: 0 }];
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: twoValues }] }, "not a bindable provider form");
+	const noSlot = structuredClone(SUBMISSION);
+	noSlot.argumentTokens = [...BINDING_TOKENS, "--input=/no/value/slot"];
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: noSlot }] }, "not a bindable provider form");
+	rejects({ ...descriptor(), cases: [{ ...descriptor().cases[0]!, submission: { ...structuredClone(SUBMISSION), extra: 1 } }] }, "extra");
+});
+test("loadDescriptor reads and validates a descriptor file", (t) => {
+	const path = tempDescriptor(t, descriptor());
+	assert.equal(loadDescriptor(path).schema, DESCRIPTOR_SCHEMA);
+	assert.throws(() => loadDescriptor(join(dirname(path), "missing.json")), /could not read descriptor/);
+	writeFileSync(join(dirname(path), "bad.json"), "{not json");
+	assert.throws(() => loadDescriptor(join(dirname(path), "bad.json")), /not valid JSON/);
+});
+
+// ---------------------------------------------------------------------------
+// No-production-resolution — the runner uses only declared executables and
+// never falls through to the package-local production binary.
+// ---------------------------------------------------------------------------
+test("runMatrix uses only the declared executable, never the production resolver", async () => {
+	const [verdict] = await runMatrix(validateDescriptor({ ...descriptor(), gentleAiExecutable: sandboxPath("not-a-gentle-ai-binary") }));
+	assert.equal(verdict!.verdict, "blocked");
+	assert.match(verdict!.reason, /gentleAiExecutable/);
+	assert.notEqual(verdict!.verdict, "pass");
+});
+test("resolveDeclaredExecutable checks absolute paths verbatim and bare names on PATH only", () => {
+	assert.equal(resolveDeclaredExecutable(sandboxPath("nonexistent-absolute-123")), null);
+	assert.equal(resolveDeclaredExecutable(""), null);
+});
+
+// ---------------------------------------------------------------------------
+// Mis-declared capable binary — a `relay-unavailable` case is a negative
+// control, so the arm gate must not trust the maintainer-declared `kind`. A
+// declaration-only gate pointed at a CAPABLE binary would materialize, launch
+// a REAL pi model, and run a REAL `capture-result --input=...` submission
+// before reporting `fail`: the mutation would already have happened. Driven by
+// local stub executables (the repo's fake-executable idiom), so it is
+// deterministic and needs no arming.
+// ---------------------------------------------------------------------------
+function capableStubHarness(t: test.TestContext) {
+	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-capable-stub-"));
+	chmodSync(directory, 0o700);
+	t.after(() => rmSync(directory, { recursive: true, force: true }));
+	const materializeLog = join(directory, "materialized");
+	const submitLog = join(directory, "submitted");
+	const piLog = join(directory, "pi-launched");
+	const gentleAi = join(directory, "gentle-ai");
+	// Deliberately CAPABLE: it honours --materialize=true and would accept a
+	// submission, exactly like a binary a maintainer mis-declared as incapable.
+	writeFileSync(
+		gentleAi,
+		`#!/usr/bin/env node
+const fs = require("node:fs");
+const argv = process.argv.slice(2);
+if (argv.includes("--materialize=true")) {
+	fs.writeFileSync(${JSON.stringify(materializeLog)}, JSON.stringify(argv));
+	process.stdout.write("prompt-bytes");
+	process.exit(0);
+}
+fs.writeFileSync(${JSON.stringify(submitLog)}, JSON.stringify(argv));
+process.stdout.write(JSON.stringify({ schema: "gentle-ai.review-result-artifact/v2", admission_decision: "completed" }));
+process.exit(0);
+`,
+	);
+	chmodSync(gentleAi, 0o755);
+	const pi = join(directory, "pi");
+	writeFileSync(
+		pi,
+		`#!/usr/bin/env node
+const fs = require("node:fs");
+fs.writeFileSync(${JSON.stringify(piLog)}, "launched");
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => { process.stdout.write("pi-result-bytes"); process.exit(0); });
+`,
+	);
+	chmodSync(pi, 0o755);
+	return { gentleAi, pi, materializeLog, submitLog, piLog };
+}
+test("a relay-unavailable case against a CAPABLE binary fails closed at pi: zero pi launch, zero submission", async (t) => {
+	const stub = capableStubHarness(t);
+	const [verdict] = await runMatrix(validateDescriptor({ ...descriptor(), gentleAiExecutable: stub.gentleAi, piExecutable: stub.pi }));
+	// The declared binary really is capable, so the negative control cannot
+	// pass — but it must fail WITHOUT mutating anything.
+	assert.equal(verdict!.verdict, "fail");
+	assert.match(verdict!.reason, /kind=pi-launch-failed stage=pi mutationOutcome=none/);
+	// The load-bearing assertions: the real pi never ran and the real
+	// submission never fired.
+	assert.equal(existsSync(stub.piLog), false, "pi must never launch for a relay-unavailable case");
+	assert.equal(existsSync(stub.submitLog), false, "a relay-unavailable case must never reach submit");
+	// Materialize still happens: it is the honest capability probe, and it is
+	// read-only (mutationOutcome stays "none" before submit).
+	assert.equal(existsSync(stub.materializeLog), true);
+});
+// ---------------------------------------------------------------------------
+// Negative control — a baseline runtime without --materialize fails closed as
+// relay-unavailable with zero Pi launch and zero submission. The baseline is
+// env-supplied (GENTLE_PI_MAINTAINER_BASELINE_BINARY); external evidence
+// establishes whether it is the immutable RC8 runtime. Self-skip / fail-loud.
+// ---------------------------------------------------------------------------
+const baselineArmed = typeof baselineBinary === "string" && baselineBinary.length > 0 && baselineBinary.startsWith("/") && existsSync(baselineBinary);
+const baselineReason = () => `${BASELINE_ENV} is unset or not an existing absolute path; supply the baseline gentle-ai binary (external evidence establishes whether it is RC8), or set ${REQUIRE_ENV}=1 to fail instead of skip.`;
+if (!baselineArmed && armed) throw new Error(baselineReason());
+if (!baselineArmed) console.log(`tests/maintainer/provider-relay.maintest.ts: ${baselineReason()}`);
+function baselineDescriptor(kind = "relay-unavailable" as const) {
+	return validateDescriptor({ ...descriptor(), gentleAiExecutable: baselineBinary, cases: [{ name: "baseline-negative-control", kind, captureArgumentTokens: [...CAPTURE_TOKENS], submission: structuredClone(SUBMISSION) }] });
+}
+test("negative control: runMatrix proves the baseline fails closed as relay-unavailable with zero mutation", { skip: !baselineArmed }, async () => {
+	const [verdict] = await runMatrix(baselineDescriptor());
+	assert.equal(verdict!.kind, "relay-unavailable");
+	assert.equal(verdict!.verdict, "pass");
+	assert.equal(verdict!.stage, "materialize");
+	assert.equal(verdict!.mutationOutcome, "none");
+	assert.equal(verdict!.reason, REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE);
+});
+test("negative control: the real relay returns a typed relay-unavailable error before Pi launches", { skip: !baselineArmed }, async () => {
+	// The baseline lacks --materialize, so it fails at materialize before any
+	// pi launch; RELAY_UNAVAILABLE at materialize proves Pi never launched.
+	let caught: unknown;
+	try {
+		await runReviewHostRelaySlot({ captureArgumentTokens: [...CAPTURE_TOKENS], submission: structuredClone(SUBMISSION), gentleAiExecutable: baselineBinary!, piExecutable: "pi" });
+	} catch (error) {
+		caught = error;
+	}
+	assert.ok(caught instanceof ReviewHostRelayError);
+	const e = caught as ReviewHostRelayError;
+	assert.equal(e.kind, REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE);
+	assert.equal(e.stage, "materialize");
+	assert.equal(e.mutationOutcome, "none");
+	assert.match(e.stderr, /flag provided but not defined: -(?:materialize|agent)/);
+});
+test("negative control: an armed positive-lens against the baseline blocks because it lacks the surface", { skip: !baselineArmed }, async () => {
+	const [verdict] = await runMatrix(baselineDescriptor("positive-lens"), { armPositive: true });
+	assert.equal(verdict!.verdict, "blocked");
+	assert.match(verdict!.reason, /lacks the pi host relay surface/);
+	assert.equal(verdict!.command, POSITIVE_JOURNEY_COMMAND);
+});
+// ---------------------------------------------------------------------------
+// Honest positive arming/skip — the organic journey needs a real capable
+// binary, a real pi, and a real review session (lifecycle machinery beyond
+// this work unit). The runner blocks the positive leg before materialize
+// unless armed. These tests run WITHOUT the arm (the verifier arms it).
+// ---------------------------------------------------------------------------
+const capableArmed = typeof capableBinary === "string" && capableBinary.length > 0 && capableBinary.startsWith("/") && existsSync(capableBinary);
+const capableReason = () => `${CAPABLE_ENV} is unset or not an existing absolute path; supply a capable gentle-ai binary (local build of origin/main with the pi host-relay surface), or set ${REQUIRE_ENV}=1 to fail instead of skip.`;
+if (!capableArmed && armed) throw new Error(capableReason());
+if (!capableArmed) console.log(`tests/maintainer/provider-relay.maintest.ts: ${capableReason()}`);
+function positiveDescriptor(gentleAi = capableBinary, pi = "pi") {
+	return validateDescriptor({ ...descriptor(), gentleAiExecutable: gentleAi!, piExecutable: pi, cases: [{ name: "positive-lens-relay", kind: "positive-lens", captureArgumentTokens: [...CAPTURE_TOKENS], submission: structuredClone(SUBMISSION) }] });
+}
+test("positive arming/skip: an unarmed positive leg blocks loudly and never fakes green", { skip: !capableArmed }, async () => {
+	const [verdict] = await runMatrix(positiveDescriptor());
+	assert.equal(verdict!.kind, "positive-lens");
+	assert.equal(verdict!.verdict, "blocked");
+	assert.match(verdict!.reason, new RegExp(ARM_POSITIVE_ENV));
+	assert.equal(verdict!.command, POSITIVE_JOURNEY_COMMAND);
+	assert.notEqual(verdict!.verdict, "pass");
+	assert.notEqual(verdict!.verdict, "fail");
+});
+test("positive arming/skip: a missing pi blocks at the pi pre-arm before materialize", { skip: !capableArmed }, async () => {
+	const [verdict] = await runMatrix(positiveDescriptor(capableBinary, sandboxPath("not-a-real-pi")));
+	assert.equal(verdict!.verdict, "blocked");
+	assert.match(verdict!.reason, /piExecutable/);
+	assert.equal(verdict!.command, POSITIVE_JOURNEY_COMMAND);
+});
+test("positive arming/skip: the exact next evidence command is surfaced for the separate verifier", { skip: !capableArmed }, async () => {
+	const [verdict] = await runMatrix(positiveDescriptor());
+	assert.match(verdict!.command!, /node --experimental-strip-types scripts\/maintainer\/provider-relay-matrix.mjs --descriptor/);
+	assert.match(verdict!.command!, /GENTLE_PI_MAINTAINER_ARM_POSITIVE=1/);
+});

package/tests/native-review-capability-contract.test.ts

@@ -80,8 +80,54 @@ test("2.2.2 repeats 2.2.1 because the lane Pi speaks still did not move", () =>
 	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["2.2.1"] as Record<string, boolean>);
 });
 
+test("2.2.3 repeats 2.2.2 because Pi's consumed capability columns did not move", () => {
+	// Ground-truthed against the released v2.2.3 binary: the v2 lane reports
+	// protocol 2.0, the same eight negotiated operations, and the same START
+	// fields represented by this table.
+	const contract = NATIVE_CLI_CONTRACTS["2.2.3"] as Record<string, boolean>;
+	assert.equal(contract.mode, true);
+	assert.equal(contract.delivery, true);
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["2.2.2"] as Record<string, boolean>);
+});
+
+test("2.4.0 repeats 2.2.3 because the START envelope Pi consumes still omits risk_evidence and hint", () => {
+	// Ground-truthed against the published v2.4.0 linux_amd64 release binary
+	// (sha256:0be4467... , captured 2026-08-17), not against a main build:
+	//
+	//   mode      `gentle-ai review mode status --json` still answers
+	//             `gentle-ai.rdd-mode-status/v1`. The RESOLVED value moved --
+	//             an unconfigured install now reports effective "off" with
+	//             source "default" instead of "on" -- but that is a decision
+	//             the envelope carries, not a capability it lost.
+	//   delivery  `review validate --gate pre-commit` still answers
+	//             `gentle-ai.review-gate-result/v1` with
+	//             `delivery: "disabled/unmanaged"` at exit 0. Under opt-in RDD
+	//             this is now the DEFAULT delivery answer for an install that
+	//             never enabled review, so the column matters more, not less.
+	//
+	// riskEvidence and hint stay dark for exactly the reason the 2.2.0 comment
+	// gives, re-proven rather than inherited: the negotiated
+	// `gentle-ai.review-integration.start/v3` envelope captured from this
+	// binary carries `risk_reasons: [{ code: "non_executable_only" }]` and no
+	// `risk_evidence` and no `hint`. `risk_evidence` does appear in v2.4.0, but
+	// only on the `gentle-ai.review-integration.consent/v3` blocking envelope,
+	// which is a different envelope on a different branch of START and is not
+	// what these columns describe.
+	const contract = NATIVE_CLI_CONTRACTS["2.4.0"] as Record<string, boolean>;
+	assert.equal(contract.mode, true);
+	assert.equal(contract.delivery, true);
+	assert.equal(contract.riskEvidence, false);
+	assert.equal(contract.hint, false);
+	assert.deepEqual(contract, NATIVE_CLI_CONTRACTS["2.2.3"] as Record<string, boolean>);
+});
+
 test("no shipped version key was added beyond the pin bump", () => {
 	// Rows are promises to consumers, so a new key only ever appears in a
-	// dedicated commit alongside a pin bump, never as a side effect.
-	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2"]);
+	// dedicated commit alongside a pin bump, never as a side effect. v2.2.4 and
+	// v2.3.0 shipped upstream while Pi stayed on 2.2.3 and were never pinned,
+	// so they get no row: a row asserts ground truth measured against a binary
+	// Pi actually ran, and the table only has to be ascending, not gapless.
+	assert.deepEqual(Object.keys(NATIVE_CLI_CONTRACTS), [...DARK_VERSIONS, "2.2.0", "2.2.1", "2.2.2", "2.2.3", "2.4.0"]);
 });

package/tests/native-review-cli.test.ts

@@ -4,13 +4,19 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import {
+	NATIVE_REVIEW_DEFAULT_MAX_BUFFER_BYTES,
 	NATIVE_REVIEW_ERROR_CODE,
 	NativeReviewCliError,
 	NativeReviewCliV213 as NativeReviewCliV213Production,
+	NativeReviewCliV216,
 	createNodeExecFileAdapter,
 	type ExecFileAdapter,
 	type NativeStartRequest,
 } from "../lib/native-review-cli.ts";
+import {
+	NativeReviewCliV214 as RuntimeNativeReviewCliV214,
+	NativeReviewCliV216 as RuntimeNativeReviewCliV216,
+} from "../runtime/native-review-cli.mjs";
 
 // The queued-adapter unit tests never execute a real process; default to a fixed
 // absolute package-local path so they do not depend on an installed binary
@@ -260,6 +266,23 @@ test("version process failures retain their typed failure code", async () => {
 	}
 });
 
+test("native output limits dominate killed timeout signals and expose the bounded configuration guidance", async () => {
+	const assertOutputLimit = (error: unknown): boolean => {
+		const value = error as { name?: unknown; code?: unknown; diagnostics?: { timed_out?: unknown; output_limit_exceeded?: unknown; max_buffer_bytes?: unknown; configuration_hint?: unknown } };
+		const diagnostics = value.diagnostics;
+		return value.name === "NativeReviewCliError"
+			&& value.code === NATIVE_REVIEW_ERROR_CODE.OUTPUT_LIMIT
+			&& diagnostics?.timed_out === false
+			&& diagnostics?.output_limit_exceeded === true
+			&& diagnostics?.max_buffer_bytes === NATIVE_REVIEW_DEFAULT_MAX_BUFFER_BYTES
+			&& diagnostics?.configuration_hint === "Inspect native review state before any new START; GENTLE_PI_REVIEW_MAX_BUFFER_BYTES accepts a positive decimal up to 67108864.";
+	};
+	const queue = queuedAdapter([VERSION, { stdout: "", timedOut: true, outputLimitExceeded: true }]);
+	await assert.rejects(() => new NativeReviewCliV213(queue.adapter).start({ cwd: "/repo" }), assertOutputLimit);
+	const runtimeQueue = queuedAdapter([VERSION, { stdout: "", timedOut: true, outputLimitExceeded: true }]);
+	await assert.rejects(() => new RuntimeNativeReviewCliV214(runtimeQueue.adapter).start({ cwd: "/repo" }), assertOutputLimit);
+});
+
 test("native mutation uncertainty requires target status before any replay decision", async () => {
 	const queue = queuedAdapter([VERSION, { stdout: "", timedOut: true }]);
 	await assert.rejects(
@@ -271,6 +294,39 @@ test("native mutation uncertainty requires target status before any replay decis
 	);
 });
 
+test("native clients resolve a bounded review output buffer override at construction and propagate it to child processes", async () => {
+	const expectedDefault = 16 * 1024 * 1024;
+	const override = "2097152";
+	const invalidOverrides = ["", "0", "-1", "1.5", "not-a-number", "67108865"];
+	const withOverride = <T>(value: string | undefined, callback: () => T): T => {
+		const previous = process.env.GENTLE_PI_REVIEW_MAX_BUFFER_BYTES;
+		try {
+			if (value === undefined) delete process.env.GENTLE_PI_REVIEW_MAX_BUFFER_BYTES;
+			else process.env.GENTLE_PI_REVIEW_MAX_BUFFER_BYTES = value;
+			return callback();
+		} finally {
+			if (previous === undefined) delete process.env.GENTLE_PI_REVIEW_MAX_BUFFER_BYTES;
+			else process.env.GENTLE_PI_REVIEW_MAX_BUFFER_BYTES = previous;
+		}
+	};
+	for (const [name, overrideValue, expected] of [
+		["default", undefined, expectedDefault],
+		["valid override", override, Number(override)],
+		...invalidOverrides.map((value) => [`invalid override ${JSON.stringify(value)}`, value, expectedDefault] as const),
+	] as const) {
+		const queue = queuedAdapter([VERSION, START]);
+		const client = withOverride(overrideValue, () => new NativeReviewCliV213(queue.adapter));
+		const v216 = withOverride(overrideValue, () => new NativeReviewCliV216(queue.adapter, "/package/.gentle-ai/gentle-ai"));
+		const runtimeV214 = withOverride(overrideValue, () => new RuntimeNativeReviewCliV214(queue.adapter, "/package/.gentle-ai/gentle-ai"));
+		const runtimeV216 = withOverride(overrideValue, () => new RuntimeNativeReviewCliV216(queue.adapter, "/package/.gentle-ai/gentle-ai"));
+		assert.equal(Reflect.get(v216, "maxBufferBytes"), expected, name);
+		assert.equal(Reflect.get(runtimeV214, "maxBufferBytes"), expected, `${name} runtime v214`);
+		assert.equal(Reflect.get(runtimeV216, "maxBufferBytes"), expected, `${name} runtime v216`);
+		await client.start({ cwd: "/repo" });
+		assert.deepEqual(queue.calls.map((call) => call.maxBufferBytes), [expected, expected], name);
+	}
+});
+
 test("native mutating commands omit the automatic timeout while preserving output caps", async () => {
 	const queue = queuedAdapter([
 		VERSION,

package/tests/native-review-consent.test.ts

@@ -10,6 +10,10 @@ import {
 	clearNativeReviewCapabilitiesCacheForTesting,
 	type ExecFileAdapter,
 } from "../lib/native-review-cli.ts";
+import {
+	NativeReviewCliV216 as RuntimeNativeReviewCliV216,
+	clearNativeReviewCapabilitiesCacheForTesting as clearRuntimeNativeReviewCapabilitiesCacheForTesting,
+} from "../runtime/native-review-cli.mjs";
 import type { ReviewConsentV2 } from "../lib/review-integration-v2.ts";
 
 const fixtureRoot = join(process.cwd(), "contracts", "review-integration", "v2", "fixtures");
@@ -58,6 +62,11 @@ function client(adapter: ExecFileAdapter): NativeReviewCliV216 {
 	return new NativeReviewCliV216(adapter, "/package/.gentle-ai/gentle-ai", 30_000, 1024 * 1024, async () => undefined, () => executableDigest);
 }
 
+function runtimeClient(adapter: ExecFileAdapter): RuntimeNativeReviewCliV216 {
+	clearRuntimeNativeReviewCapabilitiesCacheForTesting();
+	return new RuntimeNativeReviewCliV216(adapter, "/package/.gentle-ai/gentle-ai", 30_000, 1024 * 1024, async () => undefined, () => executableDigest);
+}
+
 test("negotiated ordinary START declares relay and preserves the complete target-bound consent envelope", async () => {
 	const consent = fixture<Record<string, unknown>>("consent.fixture.json");
 	const target = String(consent.target_identity);
@@ -97,18 +106,40 @@ test("controller-prebound START target is used without projecting a second works
 	assert.equal(queue.calls.some((arguments_) => arguments_[1] === "status"), false, "a prebound START target must not be projected again");
 });
 
-test("consent follow-up executes the provider-named invocation exactly once and refuses a changed target binding", async () => {
+test("consent follow-up executes the provider-named invocation exactly once and refuses changed lineage or target bindings", async () => {
 	const consent = fixture<ReviewConsentV2 extends never ? never : Record<string, unknown>>("consent.fixture.json");
 	const decodedConsent = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(consent);
-	const started = JSON.parse(JSON.stringify(fixture<Record<string, unknown>>("start.fixture.json"))
-		.replaceAll("review-start-fixture", "review-consent-fixture")) as Record<string, unknown>;
+	const preboundLineage = "Review.Lineage_42";
+	for (const choice of decodedConsent.choices) {
+		choice.invocation = choice.invocation.replace("review-consent-fixture", preboundLineage);
+	}
+	const started = fixture<Record<string, unknown>>("start.fixture.json");
+	started.lineage_id = preboundLineage;
+	started.artifact_subjects = [];
 	const queue = queuedAdapter([capabilities(), started]);
 	const native = client(queue.adapter);
 	const result = await native.answerConsent!({ cwd: "/repo", consent: decodedConsent, answer: "granted" });
 	assert.equal(result.kind, "started");
+	assert.ok(result.kind === "started");
+	assert.equal(result.start.lineageId, preboundLineage);
 	assert.deepEqual(queue.calls.at(-1), decodedConsent.choices[0].invocation.split(" ").slice(1));
 	assert.equal(queue.calls.filter((arguments_) => arguments_.includes("granted")).length, 1);
 
+	const runtimeQueue = queuedAdapter([capabilities(), structuredClone(started)]);
+	const runtimeResult = await runtimeClient(runtimeQueue.adapter).answerConsent({ cwd: "/repo", consent: decodedConsent, answer: "granted" });
+	assert.equal(runtimeResult.kind, "started");
+	assert.ok(runtimeResult.kind === "started");
+	assert.equal(runtimeResult.start.lineageId, preboundLineage);
+	assert.equal(runtimeQueue.calls.filter((arguments_) => arguments_.includes("granted")).length, 1);
+
+	const changedLineage = JSON.parse(JSON.stringify(started).replaceAll(preboundLineage, "different-lineage")) as Record<string, unknown>;
+	const lineageQueue = queuedAdapter([capabilities(), changedLineage]);
+	await assert.rejects(
+		() => client(lineageQueue.adapter).answerConsent!({ cwd: "/repo", consent: decodedConsent, answer: "granted" }),
+		/lineage mismatch/,
+	);
+	assert.equal(lineageQueue.calls.filter((arguments_) => arguments_[0] === "review" && arguments_[1] === "start").length, 1);
+
 	const changed = structuredClone(decodedConsent);
 	changed.targetIdentity = `sha256:${"b".repeat(64)}`;
 	await assert.rejects(
@@ -177,6 +208,68 @@ test("every consent invocation binding guard reports its own reason without laun
 	}
 });
 
+test("fresh consent START accepts the strictly decoded provider-created lineage and rejects a mismatched target", async () => {
+	const decoded = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(fixture<Record<string, unknown>>("consent.fixture.json"));
+	const freshConsent = structuredClone(decoded);
+	for (const choice of freshConsent.choices) {
+		choice.invocation = choice.invocation.replace(" --lineage review-consent-fixture", "");
+	}
+	const freshStart = JSON.parse(JSON.stringify(fixture<Record<string, unknown>>("start.fixture.json"))
+		.replaceAll("review-start-fixture", "provider-created-lineage")) as Record<string, unknown>;
+	const queue = queuedAdapter([capabilities(), freshStart]);
+	const result = await client(queue.adapter).answerConsent!({ cwd: "/repo", consent: freshConsent, answer: "granted" });
+	assert.equal(result.kind, "started");
+	assert.ok(result.kind === "started");
+	assert.equal(result.start.lineageId, "provider-created-lineage");
+	assert.equal(queue.calls.filter((arguments_) => arguments_[0] === "review" && arguments_[1] === "start").length, 1);
+	assert.equal(queue.calls.at(-1)?.includes("--lineage"), false);
+
+	const runtimeQueue = queuedAdapter([capabilities(), structuredClone(freshStart)]);
+	const runtimeResult = await runtimeClient(runtimeQueue.adapter).answerConsent({ cwd: "/repo", consent: freshConsent, answer: "granted" });
+	assert.equal(runtimeResult.kind, "started");
+	assert.ok(runtimeResult.kind === "started");
+	assert.equal(runtimeResult.start.lineageId, "provider-created-lineage");
+	assert.equal(runtimeQueue.calls.filter((arguments_) => arguments_[0] === "review" && arguments_[1] === "start").length, 1);
+	assert.equal(runtimeQueue.calls.at(-1)?.includes("--lineage"), false);
+
+	const mismatchedTarget = structuredClone(freshStart);
+	((mismatchedTarget.repository_context as Record<string, unknown>).target_identity as string) = `sha256:${"b".repeat(64)}`;
+	const mismatchQueue = queuedAdapter([capabilities(), mismatchedTarget]);
+	await assert.rejects(
+		() => client(mismatchQueue.adapter).answerConsent!({ cwd: "/repo", consent: freshConsent, answer: "granted" }),
+		/target mismatch/,
+	);
+	assert.equal(mismatchQueue.calls.filter((arguments_) => arguments_[0] === "review" && arguments_[1] === "start").length, 1);
+});
+
+test("duplicate, empty, missing, and malformed consent lineages fail before provider launch", async () => {
+	const decoded = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(fixture<Record<string, unknown>>("consent.fixture.json"));
+	const drifted = (replace: (invocation: string) => string): ReviewConsentV2 => {
+		const consent = structuredClone(decoded);
+		const choice = consent.choices.find((candidate) => candidate.answer === "granted") as { invocation: string };
+		choice.invocation = replace(choice.invocation);
+		return consent;
+	};
+	const cases = [
+		{ label: "duplicate", consent: drifted((value) => `${value} --lineage duplicate-lineage`) },
+		{ label: "empty", consent: drifted((value) => value.replace("--lineage review-consent-fixture", "--lineage=")) },
+		{ label: "missing", consent: drifted((value) => value.replace("--lineage review-consent-fixture", "--lineage")) },
+		{ label: "malformed", consent: drifted((value) => value.replace("--lineage review-consent-fixture", "--lineage invalid/lineage")) },
+	] as const;
+	for (const scenario of cases) {
+		const queue = queuedAdapter([]);
+		await assert.rejects(
+			() => client(queue.adapter).answerConsent!({ cwd: "/repo", consent: scenario.consent, answer: "granted" }),
+			(error: unknown) => {
+				assert.ok(error instanceof NativeReviewConsentBindingError, `${scenario.label} lineage must be a typed binding error`);
+				assert.equal(error.reason, "consent-invocation-option-invalid");
+				return true;
+			},
+		);
+		assert.deepEqual(queue.calls, [], `${scenario.label} lineage must not launch the provider`);
+	}
+});
+
 test("declined consent decodes the provider's explicit empty authority fields without creating a lineage", async () => {
 	const rawConsent = fixture<Record<string, unknown>>("consent.fixture.json");
 	const consent = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV2(rawConsent);
@@ -203,3 +296,71 @@ test("declined consent decodes the provider's explicit empty authority fields wi
 	assert.equal("lineageId" in result, false);
 	assert.deepEqual(queue.calls.at(-1), consent.choices[1].invocation.split(" ").slice(1));
 });
+
+// --- consent/v3 (dev-binary field-test lane) ---
+//
+// Fixture provenance: consent-v3.captured.json, start-v3-consent-granted
+// .captured.json, and start-v3-consent-declined.captured.json were captured
+// 2026-08-16 from the real binary at /home/gentleman/.cargo/bin/gentle-ai
+// reporting "gentle-ai 2.4.0-main.b1afef46"; full capture commands are
+// documented in tests/review-integration-v2-forward.test.ts.
+
+const devbinaryFixtureRoot = join(process.cwd(), "tests", "fixtures", "devbinary");
+const devbinaryFixture = <T = Record<string, unknown>>(name: string): T => JSON.parse(readFileSync(join(devbinaryFixtureRoot, name), "utf8")) as T;
+
+test("negotiated START surfaces the captured consent/v3 envelope instead of failing schema-incompatible", async () => {
+	const consent = devbinaryFixture<Record<string, unknown>>("consent-v3.captured.json");
+	const target = String(consent.target_identity);
+	const queue = queuedAdapter([capabilities(), unrelatedStatus(target), consent]);
+	await assert.rejects(
+		() => client(queue.adapter).start({ cwd: "/repo" }),
+		(error: unknown) => {
+			assert.ok(error instanceof NativeReviewConsentRequiredError, `expected NativeReviewConsentRequiredError, got ${String(error)}`);
+			assert.deepEqual(error.consent.raw, consent);
+			assert.equal(error.consent.schema, "gentle-ai.review-integration.consent/v3");
+			assert.equal(error.consent.targetIdentity, target);
+			return true;
+		},
+	);
+	assert.deepEqual(queue.calls.at(-1), [
+		"review", "start", "--contract", "gentle-ai.review-integration/v2", "--cwd", "/repo",
+		"--target", target, "--projection", "workspace", "--consent", "relay",
+	]);
+
+	const runtimeQueue = queuedAdapter([capabilities(), unrelatedStatus(target), structuredClone(consent)]);
+	await assert.rejects(
+		() => runtimeClient(runtimeQueue.adapter).start({ cwd: "/repo" }),
+		(error: unknown) => (error as Error).name === "NativeReviewConsentRequiredError",
+	);
+});
+
+test("a granted consent/v3 answer decodes the captured start/v3 result with its event binding", async () => {
+	const decoded = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV3(devbinaryFixture<Record<string, unknown>>("consent-v3.captured.json"));
+	const cwd = decoded.choices[0].invocation.split(" --cwd ")[1]!.split(" ")[0]!;
+	const started = devbinaryFixture<Record<string, unknown>>("start-v3-consent-granted.captured.json");
+	const queue = queuedAdapter([capabilities(), started]);
+	const result = await client(queue.adapter).answerConsent!({ cwd, consent: decoded, answer: "granted" });
+	assert.equal(result.kind, "started");
+	assert.ok(result.kind === "started");
+	assert.equal(result.start.lineageId, "review-377c60e10b852cfc");
+	assert.equal(result.start.selectedLenses.length, 4);
+	// The follow-up runs the provider-owned invocation verbatim, exactly once.
+	assert.deepEqual(queue.calls.at(-1), decoded.choices[0].invocation.split(" ").slice(1));
+	assert.equal(queue.calls.filter((arguments_) => arguments_.includes("granted")).length, 1);
+
+	const runtimeQueue = queuedAdapter([capabilities(), structuredClone(started)]);
+	const runtimeResult = await runtimeClient(runtimeQueue.adapter).answerConsent({ cwd, consent: decoded, answer: "granted" });
+	assert.equal(runtimeResult.kind, "started");
+});
+
+test("a declined consent/v3 answer accepts the captured declined result and creates no authority", async () => {
+	const decoded = (await import("../lib/review-integration-v2.ts")).decodeReviewConsentV3(devbinaryFixture<Record<string, unknown>>("consent-v3.captured.json"));
+	const cwd = decoded.choices[1].invocation.split(" --cwd ")[1]!.split(" ")[0]!;
+	const declined = devbinaryFixture<Record<string, unknown>>("start-v3-consent-declined.captured.json");
+	const queue = queuedAdapter([capabilities(), declined]);
+	const result = await client(queue.adapter).answerConsent!({ cwd, consent: decoded, answer: "declined" });
+	assert.equal(result.kind, "declined");
+	assert.ok(result.kind === "declined");
+	assert.equal(result.consent, "declined_this_candidate");
+	assert.equal(result.targetIdentity, decoded.targetIdentity);
+});