gentle-pi 1.2.0 → 2.0.0

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

@@ -0,0 +1,348 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { 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 { createGentleAiExtension } from "../../extensions/gentle-ai.ts";
+import {
+	NativeReviewCliV214,
+	createNodeExecFileAdapter,
+	setNativeCliContractForTesting,
+	type ExecFileAdapter,
+	type NativeReviewCli,
+} from "../../lib/native-review-cli.ts";
+import { CandidateViewRegistry } from "../../lib/review-candidate-view.ts";
+import { readReviewConsentLatch } from "../../lib/review-consent-latch.ts";
+import type { AuthorityRepairAssessmentV1, ReviewStatusV3 } from "../../lib/review-integration-v2.ts";
+import { requireDevBinary } from "../support/native-binary-gate.ts";
+
+// Organic RDD Parity, Phase 6: non-gating dev-binary journey.
+//
+// `pnpm test` never picks this file up — it globs `tests/*.test.ts` only, and
+// this file both lives one directory deeper and ends in `.devtest.ts`. It
+// only runs via `pnpm run test:dev-binary`, and only when GENTLE_AI_DEV_BINARY
+// names an existing absolute path. It never reads or writes the shipped
+// 2.1.11 pins (lib/gentle-ai-binary.ts, scripts/gentle-ai-installer.mjs) —
+// every capability stays negotiated per-process through the executable
+// override seam below, exactly like every other native-review-cli test.
+//
+// Gated through the same loud-skip machinery as the two `tests/*.test.ts`
+// binary-verified suites (Phase 4), extended here to cover this THIRD
+// self-skipping suite (Phase 13.12/13.13 follow-up): under
+// GENTLE_PI_REQUIRE_DEV_BINARY=1 a missing/invalid dev binary throws instead
+// of silently reporting 5 tests / 0 pass / 0 fail, which is exactly how the
+// v2.2.2 "receipt-driven development" terminology rot went unnoticed.
+const DEV_BINARY = process.env.GENTLE_AI_DEV_BINARY;
+const devBinaryGate = requireDevBinary({
+	devBinaryPath: DEV_BINARY,
+	exists: typeof DEV_BINARY === "string" && DEV_BINARY.length > 0 && DEV_BINARY.startsWith("/") && existsSync(DEV_BINARY),
+	env: process.env,
+});
+if (!devBinaryGate.run) console.log(`tests/devbinary/native-review-parity.devtest.ts: ${devBinaryGate.reason}`);
+const RUNNABLE = devBinaryGate.run;
+
+// A synthetic capable version, exactly like native-review-parity.test.ts's
+// CAPABLE_VERSION overlay. Real dev binaries never carry a pinned three-part
+// semver (the live binary under test reports "gentle-ai dev-organic-...",
+// confirmed live during Phase 6 ground-truthing), so `verifyVersion`'s frozen
+// `/^gentle-ai ([0-9]+\.[0-9]+\.[0-9]+)\n$/` regex can never match it — by
+// design, a dev build is never a pinned release. The bridge below substitutes
+// exactly one in-memory version response and forwards every other call to the
+// real process untouched, so argv fidelity is guaranteed: NativeReviewCliV214
+// itself builds every argv array here, never this file.
+const BRIDGE_VERSION = "9.8.7";
+
+function bridgeAdapter(binary: string): ExecFileAdapter {
+	const real = createNodeExecFileAdapter();
+	return async (request) => {
+		if (request.arguments[0] === "version") {
+			return { stdout: `gentle-ai ${BRIDGE_VERSION}\n`, stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false };
+		}
+		return real({ ...request, file: binary });
+	};
+}
+
+// A NativeReviewCli backed by the real dev binary for reviewMode/start/
+// validate (the organic-parity surface under test), with a synthetic
+// targetStatus fixture standing in for the negotiated review-integration/v2
+// contract; the plain-CLI decode path in lib/native-review-cli.ts (reviewMode,
+// start, validate here) stays independent of the negotiated status shape.
+function journeyNative(binary: string): NativeReviewCli {
+	const bridge = new NativeReviewCliV214(bridgeAdapter(binary), binary);
+	return {
+		start: (request) => bridge.start(request),
+		validate: (request) => bridge.validate(request),
+		reviewMode: (request) => bridge.reviewMode(request),
+		async targetStatus(request) {
+			return request.lineageId === undefined
+				? unrelatedStartTargetStatus()
+				: currentTargetStatusFixture(request.lineageId, request.cwd);
+		},
+	} as unknown as NativeReviewCli;
+}
+
+function git(cwd: string, ...args: string[]): string {
+	return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+
+function repository(t: test.TestContext): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-dev-binary-"));
+	t.after(() => {
+		try { execFileSync("chmod", ["-R", "u+w", cwd]); } catch { /* best effort */ }
+		rmSync(cwd, { recursive: true, force: true });
+	});
+	git(cwd, "init", "-b", "main");
+	git(cwd, "config", "user.email", "devbinary@example.com");
+	git(cwd, "config", "user.name", "Dev Binary Journey");
+	return cwd;
+}
+
+const UNSUPPORTED_REPAIR_ASSESSMENT: AuthorityRepairAssessmentV1 = {
+	schema: "gentle-ai.review-authority-repair-assessment/v1",
+	status: "unsupported",
+	counts: { lineages: 0, compactLineages: 0, legacyLineages: 0, events: 0, bytes: 0, eligibleCandidates: 0, unsupportedLineages: 0, conflicts: 0 },
+	supportedOperations: ["review/complete-fix", "review/validate-fix"],
+	authorizationSchema: "gentle-ai.review-repair-authorization/v1",
+};
+const RAW_UNSUPPORTED_REPAIR_ASSESSMENT = {
+	schema: UNSUPPORTED_REPAIR_ASSESSMENT.schema,
+	status: UNSUPPORTED_REPAIR_ASSESSMENT.status,
+	counts: {
+		lineages: 0, compact_lineages: 0, legacy_lineages: 0, events: 0, bytes: 0,
+		eligible_candidates: 0, unsupported_lineages: 0, conflicts: 0,
+	},
+	supported_operations: UNSUPPORTED_REPAIR_ASSESSMENT.supportedOperations,
+	authorization_schema: UNSUPPORTED_REPAIR_ASSESSMENT.authorizationSchema,
+};
+
+function unrelatedStartTargetStatus(): ReviewStatusV3 {
+	const sha = `sha256:${"a".repeat(64)}`;
+	const tree = "b".repeat(40);
+	const projection = {
+		schema: "gentle-ai.review-integration.projection/v1" as const, kind: "current-changes" as const, projection: "workspace" as const,
+		baseTree: tree, initialReviewTree: tree, currentCandidateTree: tree, pathsDigest: sha, paths: [], intendedUntracked: [],
+		intendedUntrackedProof: sha, initialSnapshotIdentity: sha, currentSnapshotIdentity: sha,
+	};
+	return {
+		contract: "gentle-ai.review-integration/v2", applicability: "unrelated", receipt: { status: "not_applicable" }, action: "start",
+		replayability: "not_replayable", targetIdentity: sha, projection, repair: UNSUPPORTED_REPAIR_ASSESSMENT, candidates: [],
+		raw: {
+			schema: "gentle-ai.review-integration.status/v3", contract: "gentle-ai.review-integration/v2", operation: "review.status",
+			applicability: "unrelated", receipt: { status: "not_applicable" }, action: "start", replayability: "not_replayable", target_identity: sha,
+			repair: RAW_UNSUPPORTED_REPAIR_ASSESSMENT,
+			projection: { schema: projection.schema, kind: projection.kind, projection: projection.projection, base_tree: tree, initial_review_tree: tree, current_candidate_tree: tree, paths_digest: sha, paths: [], intended_untracked: [], intended_untracked_proof: sha, initial_snapshot_identity: sha, current_snapshot_identity: sha },
+			candidates: [],
+		},
+	};
+}
+
+function currentTargetStatusFixture(lineageId: string, cwd: string): ReviewStatusV3 {
+	const sha = `sha256:${"a".repeat(64)}`;
+	const baseTree = git(cwd, "rev-parse", "HEAD^{tree}");
+	const candidateTree = git(cwd, "write-tree");
+	const projection = {
+		schema: "gentle-ai.review-integration.projection/v1" as const, kind: "current-changes" as const, projection: "workspace" as const,
+		baseTree, initialReviewTree: candidateTree, currentCandidateTree: candidateTree, pathsDigest: sha, paths: ["app.ts"], intendedUntracked: [],
+		intendedUntrackedProof: sha, initialSnapshotIdentity: sha, currentSnapshotIdentity: sha,
+	};
+	return {
+		contract: "gentle-ai.review-integration/v2", applicability: "current_target",
+		authority: { version: "compact-v2", lineageId, state: "reviewing", generation: 1, revision: sha },
+		receipt: { status: "expected_missing" }, action: "finalize", replayability: "not_replayable",
+		frozen: { tier: "medium", originalChangedLines: 1, correctionBudget: 1 },
+		targetIdentity: sha, projection, repair: UNSUPPORTED_REPAIR_ASSESSMENT, candidates: [],
+		raw: {
+			schema: "gentle-ai.review-integration.status/v3", contract: "gentle-ai.review-integration/v2", operation: "review.status",
+			applicability: "current_target", receipt: { status: "expected_missing" }, action: "finalize", replayability: "not_replayable", target_identity: sha,
+			authority: { version: "compact-v2", lineage_id: lineageId, state: "reviewing", generation: 1, revision: sha },
+			frozen: { tier: "medium", original_changed_lines: 1, correction_budget: 1 },
+			repair: RAW_UNSUPPORTED_REPAIR_ASSESSMENT,
+			projection: { schema: projection.schema, kind: projection.kind, projection: projection.projection, base_tree: baseTree, initial_review_tree: candidateTree, current_candidate_tree: candidateTree, paths_digest: sha, paths: ["app.ts"], intended_untracked: [], intended_untracked_proof: sha, initial_snapshot_identity: sha, current_snapshot_identity: sha },
+			candidates: [],
+		},
+	};
+}
+
+interface RegisteredTool {
+	execute: (toolCallId: string, params: unknown, signal: AbortSignal | undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ details?: unknown }>;
+}
+interface RegisteredCommandFixture {
+	handler: (args: string, ctx: ExtensionContext) => Promise<void>;
+}
+
+function runtime(nativeReviewCli: NativeReviewCli): { controller: RegisteredTool; commands: Map<string, RegisteredCommandFixture> } {
+	const tools = new Map<string, RegisteredTool>();
+	const commands = new Map<string, RegisteredCommandFixture>();
+	const dependencies = { nativeReviewCli, candidateViews: new CandidateViewRegistry() } as unknown as Parameters<typeof createGentleAiExtension>[0];
+	createGentleAiExtension(dependencies)({
+		on() {},
+		registerTool(definition: RegisteredTool & { name: string }) { tools.set(definition.name, definition); },
+		registerCommand(name: string, definition: RegisteredCommandFixture) { commands.set(name, definition); },
+	} as unknown as ExtensionAPI);
+	const controller = tools.get("gentle_review");
+	assert.ok(controller);
+	return { controller: controller!, commands };
+}
+
+function headlessContext(cwd: string, notices: Array<{ message: string; type?: string }> = []): ExtensionContext {
+	return { cwd, hasUI: false, ui: { notify: (message: string, type?: string) => { notices.push({ message, type }); } } } as unknown as ExtensionContext;
+}
+function confirmContext(cwd: string, answer: boolean): ExtensionContext {
+	return { cwd, hasUI: true, ui: { confirm: async () => answer, notify: () => {} } } as unknown as ExtensionContext;
+}
+
+const START_ORDINARY = { operation: "start", input: JSON.stringify({ mode: "ordinary" }) };
+async function execStart(controller: RegisteredTool, id: string, ctx: ExtensionContext): Promise<Record<string, unknown>> {
+	const { details } = await controller.execute(id, START_ORDINARY, undefined, undefined, ctx);
+	return details as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Kill switch round trip (mirrors /gentle:review-mode status|disable|enable
+// from the community guide flows).
+// ---------------------------------------------------------------------------
+
+test("dev-binary: gentle:review-mode round-trips status, disable, and enable against the real binary", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	const { commands } = runtime(journeyNative(DEV_BINARY!));
+	const command = commands.get("gentle:review-mode")!;
+	const notices: Array<{ message: string; type?: string }> = [];
+
+	await command.handler("status", headlessContext(cwd, notices));
+	assert.match(notices.at(-1)!.message, /receipt-driven development: on \(decided by \w+\)/);
+
+	await command.handler("disable", headlessContext(cwd, notices));
+	assert.match(notices.at(-1)!.message, /receipt-driven development: off \(decided by \w+\)/);
+
+	await command.handler("status", headlessContext(cwd, notices));
+	assert.match(notices.at(-1)!.message, /receipt-driven development: off \(decided by \w+\)/);
+
+	await command.handler("enable", headlessContext(cwd, notices));
+	assert.match(notices.at(-1)!.message, /receipt-driven development: on \(decided by \w+\)/);
+});
+
+// ---------------------------------------------------------------------------
+// Tier 0 silence: an empty candidate surfaces its hint verbatim and never
+// triggers a consent prompt or notice.
+// ---------------------------------------------------------------------------
+
+test("dev-binary: an empty candidate stays silent (no consent notice) and surfaces the real hint verbatim", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
+	git(cwd, "add", ".");
+	git(cwd, "commit", "-qm", "initial");
+	const { controller } = runtime(journeyNative(DEV_BINARY!));
+	const notices: Array<{ message: string; type?: string }> = [];
+	const result = await execStart(controller, "tier-0", headlessContext(cwd, notices));
+	const rendered = result.result as Record<string, unknown>;
+	assert.equal(rendered.lenses_required, false);
+	assert.equal(typeof rendered.hint, "string");
+	assert.match(rendered.hint as string, /the candidate has no pending changes/);
+	assert.equal(result.consent_notice, undefined, "tier 0 must never surface a consent notice");
+	assert.equal(notices.length, 0, "tier 0 must never notify the user at all");
+});
+
+// ---------------------------------------------------------------------------
+// Tier 2 evidence + consent envelope via a fake UI seam.
+// ---------------------------------------------------------------------------
+
+test("dev-binary: a high-risk change carries real risk_evidence and drives the consent envelope through a fake UI seam", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	const workflowDirectory = join(cwd, ".github", "workflows");
+	execFileSync("mkdir", ["-p", workflowDirectory]);
+	writeFileSync(join(workflowDirectory, "deploy.yml"), "name: x\n");
+	git(cwd, "add", ".");
+	git(cwd, "commit", "-qm", "initial");
+	writeFileSync(join(workflowDirectory, "deploy.yml"), "name: x\non: push\njobs:\n  deploy:\n    steps:\n      - run: curl -s | bash\n");
+
+	const acceptedRun = journeyNative(DEV_BINARY!);
+	const { controller } = runtime(acceptedRun);
+	const accepted = await execStart(controller, "tier-2-accept", confirmContext(cwd, true));
+	const rendered = accepted.result as Record<string, unknown>;
+	assert.equal(rendered.risk_tier, "high");
+	assert.ok(Array.isArray(rendered.risk_evidence) && (rendered.risk_evidence as unknown[]).length > 0, "high risk must carry a non-empty risk_evidence phrase array");
+	assert.ok((rendered.risk_evidence as string[])[0]!.includes("deploy.yml"));
+	assert.ok(accepted.actor_binding, "accepting consent must proceed to actor_binding");
+	assert.equal(readReviewConsentLatch(cwd), true, "accepting consent must record the per-clone latch");
+});
+
+test("dev-binary: declining the fake-UI consent prompt withholds actor_binding for this work unit only, against the real binary's own evidence", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	const workflowDirectory = join(cwd, ".github", "workflows");
+	execFileSync("mkdir", ["-p", workflowDirectory]);
+	writeFileSync(join(workflowDirectory, "deploy.yml"), "name: x\n");
+	git(cwd, "add", ".");
+	git(cwd, "commit", "-qm", "initial");
+	writeFileSync(join(workflowDirectory, "deploy.yml"), "name: x\non: push\njobs:\n  deploy:\n    steps:\n      - run: curl -s | bash\n");
+
+	const { controller } = runtime(journeyNative(DEV_BINARY!));
+	const declined = await execStart(controller, "tier-2-decline", confirmContext(cwd, false));
+	assert.equal(declined.actor_binding, undefined, "declining must withhold actor dispatch for this work unit");
+	assert.equal(readReviewConsentLatch(cwd), false, "declining must never persist the latch");
+	assert.ok(declined.result, "the native start result itself is still reported even on decline");
+});
+
+// ---------------------------------------------------------------------------
+// Disabled/unmanaged delivery renders as a successful skip, never a failure.
+// ---------------------------------------------------------------------------
+
+// IMPORTANT reachability finding (Phase 6 ground-truthing): gentle-ai only
+// emits the disabled/unmanaged delivery envelope through lineage
+// AUTO-DISCOVERY (`review validate --gate <gate>` with no `--lineage`) — its
+// Go source (internal/cli/review_facade.go:2412-2433,1904-1916) routes an
+// explicit `--lineage <id>` through discoverCompactFacadeReview's
+// lineage-specific branch, whose failures are plain `fmt.Errorf` values, never
+// the `*ReviewReceiptDiscoveryError` the disabled/unmanaged check requires —
+// confirmed live against both a nonexistent lineage id ("load compact facade
+// review lineage: ... no such file or directory", exit 1) and a real
+// previously-started lineage under a disabled switch ("facade review receipt
+// is not available", exit 1). Neither is the structured JSON envelope.
+// Pi's `gentle_review` VALIDATE operation always binds an explicit
+// lineageId (extensions/gentle-ai.ts throws "Review controller validate
+// requires a lineageId" otherwise), so this envelope is structurally
+// unreachable through today's controller wiring — this is a pre-existing
+// property of the VALIDATE contract, not something Phase 5.2 introduced.
+// This is flagged as a risk for a future design revision, not silently
+// papered over here. What Phase 6 CAN and does prove against the real binary
+// is that Pi's decoder correctly decodes the envelope gentle-ai actually
+// sends via auto-discovery; the controller-level mapping/early-return
+// (mapNativeValidateResult + the skip response) is proven separately with a
+// synthetic fixture in tests/review-controller-native-routing.test.ts,
+// because gentle-ai's own explicit-lineage code path can never supply it.
+test("dev-binary: VALIDATE via lineage auto-discovery decodes the real disabled/unmanaged delivery envelope", { skip: !RUNNABLE }, async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "app.ts"), "export const value = 1;\n");
+	git(cwd, "add", ".");
+	git(cwd, "commit", "-qm", "initial");
+	writeFileSync(join(cwd, "app.ts"), "export const value = 2;\n");
+	git(cwd, "add", "--", "app.ts");
+
+	// Each journey uses its own throwaway temp repository (deleted in
+	// repository(t)'s cleanup), so there is no shared clone-local state to
+	// restore afterward.
+	const native = journeyNative(DEV_BINARY!);
+	await native.reviewMode!({ cwd, operation: "disable" });
+
+	// No lineageId: this is the one shape gentle-ai actually routes through
+	// its disabled/unmanaged discovery branch.
+	const result = await native.validate({ cwd, gate: "pre-commit" });
+	assert.equal(result.delivery, "disabled/unmanaged");
+	assert.equal(result.allowed, false);
+	assert.equal(result.result, "invalidated");
+	assert.equal(result.action, "repository-policy");
+});
+
+test.before(() => {
+	if (RUNNABLE) {
+		setNativeCliContractForTesting(BRIDGE_VERSION, {
+			start: true, finalize: true, validate: true, bindSdd: true, sddStatus: true, status: true, inventory: true,
+			reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true,
+			mode: true, riskEvidence: true, hint: true, delivery: true,
+		});
+	}
+});
+test.after(() => {
+	if (RUNNABLE) setNativeCliContractForTesting(BRIDGE_VERSION, undefined);
+});

package/tests/gentle-ai-binary.test.ts

@@ -13,6 +13,7 @@ import {
 } from "../lib/gentle-ai-binary.ts";
 import { NativeReviewCliV213, createNativeReviewCli, type ExecFileAdapter } from "../lib/native-review-cli.ts";
 import { resolveGentleAiReleaseAsset } from "../scripts/gentle-ai-installer.mjs";
+import { requireNativeBinary } from "./support/native-binary-gate.ts";
 
 const VERSION = { stdout: `gentle-ai ${GENTLE_AI_VERSION}\n`, stderr: "", exitCode: 0, signal: null, timedOut: false, outputLimitExceeded: false } as const;
 const RUNTIME_DIRECTORY = `v${GENTLE_AI_VERSION}`;
@@ -20,7 +21,13 @@ const repoRuntimeBinary = join(import.meta.dirname, "..", ".gentle-ai", RUNTIME_
 const releaseDigestsPinned = /^[0-9a-f]{64}$/.test(resolveGentleAiReleaseAsset(process.platform, process.arch).sha256);
 // These integrity tests need the published official binary; they skip while a
 // re-pinned release's archives and digest table are still pending.
-const verifiedBinaryTest = releaseDigestsPinned && existsSync(repoRuntimeBinary) ? test : test.skip;
+const nativeBinaryGate = requireNativeBinary({
+	resolvedBinary: existsSync(repoRuntimeBinary) ? repoRuntimeBinary : undefined,
+	digestsPinned: releaseDigestsPinned,
+	env: process.env,
+});
+if (!nativeBinaryGate.run) console.log(`gentle-ai-binary: ${nativeBinaryGate.reason}`);
+const verifiedBinaryTest = nativeBinaryGate.run ? test : test.skip;
 
 async function writeVerifiedBinary(packageRoot: string, platform = process.platform): Promise<string> {
 	const asset = resolveGentleAiReleaseAsset(platform, process.arch);

package/tests/gentle-ai-installer.test.ts

@@ -18,16 +18,14 @@ import {
 	trustedSystemExtractor,
 } from "../scripts/gentle-ai-installer.mjs";
 
-// v2.1.11 digests pinned from the published release: archive sha256 values match
+// v2.2.2 digests pinned from the published release: archive sha256 values match
 // checksums.txt and freshly computed hashes; binary sha256 values were computed
 // from the extracted executables of each verified archive.
 const EXPECTED_ASSETS = {
-	"darwin/amd64": { name: "gentle-ai_2.1.11_darwin_amd64.tar.gz", sha256: "80c2a6bba981fd0ec1fdc9b21d9b80c03853cacc644b307ca7baf1faa6b376d2", binarySha256: "bffca50cb51b07cc1c428e21616ea1cf7d25970643fed13ab0aa10fd359bbd02" },
-	"darwin/arm64": { name: "gentle-ai_2.1.11_darwin_arm64.tar.gz", sha256: "27e49a5104ff1ab156276e191b845f266135afe9339f111689ddf340b562c926", binarySha256: "4e39e520abf116a53ff5e36a0cd65756b6fadfa528489f21e9c722bfa00af620" },
-	"linux/amd64": { name: "gentle-ai_2.1.11_linux_amd64.tar.gz", sha256: "d115aaf5724a71503150ebf740769e7aa52e41e673ac39bf5b0ff1be4e3324b0", binarySha256: "45788ac6cf37a6165f50aca3503d4af4e7e375e518fc67010064dccf78f98d2d" },
-	"linux/arm64": { name: "gentle-ai_2.1.11_linux_arm64.tar.gz", sha256: "aea3a4b0064b57df5f831fdf6b27b29e9898a8f9393fd648dea4a8ba563e477e", binarySha256: "2bf929993ba03dd02401a3c35d8b0bff7801717e43d17b39e29f3cd389894e63" },
-	"windows/amd64": { name: "gentle-ai_2.1.11_windows_amd64.zip", sha256: "43fb4e66cf36a7f01d2d343f59fe8ff37396fc0e98fb24abcd95bc79c2450e9a", binarySha256: "1c92cdcaf826d4bec6a6560770e5a0edefc09997364a664a5033abc6ab932b2b" },
-	"windows/arm64": { name: "gentle-ai_2.1.11_windows_arm64.zip", sha256: "9c2884075161715f0efac1ce55cd08f2d9313068f125443ade8de3a83645258a", binarySha256: "a903bface64af274a28cfdd08b5c55c67fc554bac9279d7d466fc3f99020bd89" },
+	"darwin/amd64": { name: "gentle-ai_2.2.2_darwin_amd64.tar.gz", sha256: "5ca67829903bf4c6b14665664f80f9d8216c84b10c8e50870d297f452cefb9dc", binarySha256: "9b239423450562d026384f482bbd2f1e3f2820431a84f0921743ac3df9d632de" },
+	"darwin/arm64": { name: "gentle-ai_2.2.2_darwin_arm64.tar.gz", sha256: "0193e1a284444dccee2863d31b8dbb76a982e8f9111955908d6a9131c1a5490e", binarySha256: "149b97248552c5e03ebc4d991f86b1360fb847a40fc315555a8aa256f95baca0" },
+	"linux/amd64": { name: "gentle-ai_2.2.2_linux_amd64.tar.gz", sha256: "b85bbb20eb2236de97b261df16cfc8d8394dfd07a137e885c4889b62d0c20fa1", binarySha256: "00d5732e8dd3945956800217a4f60213c2d9ca63351092a2cb7f4e5f9ece54f9" },
+	"linux/arm64": { name: "gentle-ai_2.2.2_linux_arm64.tar.gz", sha256: "61e7077342448273f0c43af49ce4d182594bab5e4f86f812975af2fbe69e3b0b", binarySha256: "a92685aa7dbea0cc4297d016569b3defe9bb30a7374a620021e245b74f50eb68" },
 } as const;
 
 test("default installer package root is the package containing scripts, not its parent", () => {
@@ -38,15 +36,15 @@ test("default installer package root is the package containing scripts, not its
 	assert.notEqual(resolveGentleAiInstallerPackageRoot(), dirname(expectedPackageRoot));
 });
 
-test("release mapping selects only the supported official v2.1.11 archive and pinned digests", () => {
+test("release mapping selects only the supported official v2.2.2 archive and pinned digests", () => {
 	assert.deepEqual(
 		Object.fromEntries(Object.entries(GENTLE_AI_RELEASE_ASSETS).map(([key, asset]) => [key, { name: asset.name, sha256: asset.sha256, binarySha256: asset.binarySha256 }])),
 		EXPECTED_ASSETS,
 	);
-	assert.equal(resolveGentleAiReleaseAsset("linux", "x64").name, "gentle-ai_2.1.11_linux_amd64.tar.gz");
-	assert.equal(resolveGentleAiReleaseAsset("windows", "arm64").name, "gentle-ai_2.1.11_windows_arm64.zip");
+	assert.equal(resolveGentleAiReleaseAsset("linux", "x64").name, "gentle-ai_2.2.2_linux_amd64.tar.gz");
+	assert.equal(resolveGentleAiReleaseAsset("darwin", "arm64").name, "gentle-ai_2.2.2_darwin_arm64.tar.gz");
 	for (const asset of Object.values(GENTLE_AI_RELEASE_ASSETS)) {
-		assert.match(asset.url, /^https:\/\/github\.com\/Gentleman-Programming\/gentle-ai\/releases\/download\/v2\.1\.11\//);
+		assert.match(asset.url, /^https:\/\/github\.com\/Gentleman-Programming\/gentle-ai\/releases\/download\/v2\.2\.2\//);
 	}
 });
 
@@ -67,13 +65,18 @@ test("release digests are all-or-none and install fails closed while any digest
 			}),
 			/checksum mismatch/,
 		);
-		assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai")), false);
+		assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai")), false);
 	}
 });
 
-test("win32 platform normalizes to windows for asset lookup", () => {
-	assert.equal(resolveGentleAiReleaseAsset("win32", "x64").name, "gentle-ai_2.1.11_windows_amd64.zip");
-	assert.equal(resolveGentleAiReleaseAsset("win32", "arm64").name, "gentle-ai_2.1.11_windows_arm64.zip");
+test("win32 is rejected with the same clear error as any other unsupported platform", () => {
+	// v2.2.2 publishes no Windows archive, so there is nothing honest to
+	// resolve. Failing here, by name, beats resolving an asset that would 404
+	// at download time and blame the network for a packaging decision.
+	for (const arch of ["x64", "arm64"]) {
+		assert.throws(() => resolveGentleAiReleaseAsset("win32", arch), /unsupported Gentle AI platform\/architecture/);
+		assert.throws(() => resolveGentleAiReleaseAsset("windows", arch), /unsupported Gentle AI platform\/architecture/);
+	}
 });
 
 test("unsupported platform pairs fail clearly before download", () => {
@@ -141,7 +144,7 @@ test("checksum mismatch cleans temporary state without promoting a binary", asyn
 		}),
 		/checksum mismatch/,
 	);
-	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai")), false);
+	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai")), false);
 	assert.deepEqual((await readdir(packageRoot)).filter((entry) => entry.startsWith(".gentle-ai-install-")), []);
 });
 
@@ -163,7 +166,7 @@ test("installer promotes only the expected regular executable with executable PO
 			await chmod(extracted, 0o700);
 		},
 	});
-	const binary = join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai");
+	const binary = join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai");
 	assert.equal(existsSync(binary), true);
 	assert.equal(await readFile(binary, "utf8"), "native executable");
 	assert.ok(((await stat(binary)).mode & 0o111) !== 0);
@@ -194,7 +197,7 @@ test("installer rejects an extracted binary that differs from its pinned digest"
 		}),
 		/binary checksum mismatch/,
 	);
-	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai")), false);
+	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai")), false);
 });
 
 test("installer repairs a valid non-executable POSIX binary instead of reusing it", async (t) => {
@@ -217,7 +220,7 @@ test("installer repairs a valid non-executable POSIX binary instead of reusing i
 		},
 	};
 	await installGentleAi(options);
-	const binary = join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai");
+	const binary = join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai");
 	await chmod(binary, 0o600);
 	const repaired = await installGentleAi(options);
 	assert.equal(repaired.installed, true);
@@ -254,7 +257,7 @@ test("installer rejects archives with multiple expected executable entries", asy
 		}),
 		/exactly one regular gentle-ai/,
 	);
-	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai")), false);
+	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai")), false);
 });
 
 test("installer rejects an archive without the expected regular executable", async () => {
@@ -272,5 +275,5 @@ test("installer rejects an archive without the expected regular executable", asy
 		}),
 		/non-regular gentle-ai/,
 	);
-	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.1.11", "gentle-ai")), false);
+	assert.equal(existsSync(join(packageRoot, ".gentle-ai", "v2.2.2", "gentle-ai")), false);
 });

package/tests/native-binary-gate.test.ts

@@ -0,0 +1,145 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	NativeBinaryUnavailableError,
+	REQUIRE_DEV_BINARY_ENV,
+	REQUIRE_NATIVE_BINARY_ENV,
+	requireDevBinary,
+	requireNativeBinary,
+} from "./support/native-binary-gate.ts";
+
+// Two suites used to decide for themselves whether to run:
+//
+//   tests/native-review-parity-runtime.test.ts
+//     const test = resolvedBinary === undefined ? baseTest.skip : baseTest;
+//   tests/gentle-ai-binary.test.ts
+//     const verifiedBinaryTest = releaseDigestsPinned && existsSync(...) ? test : test.skip;
+//
+// Both skip silently when the pinned runtime is absent, so a fresh clone or a
+// CI job that never installed the binary reports green with zero real coverage
+// of the thing those suites exist to cover. That is exactly how an earlier
+// protocol-minor gap stayed hidden: the suite reported 0 fail while every test
+// in it had skipped. The gate keeps the local convenience and removes the
+// silence -- under GENTLE_PI_REQUIRE_NATIVE_BINARY=1 an absent binary is a
+// failure, not a skip.
+
+const PINNED = { resolvedBinary: "/tmp/gentle-ai", digestsPinned: true } as const;
+
+test("the env var name is the one CI sets", () => {
+	assert.equal(REQUIRE_NATIVE_BINARY_ENV, "GENTLE_PI_REQUIRE_NATIVE_BINARY");
+});
+
+test("a resolved binary with pinned digests runs, and names no skip reason", () => {
+	for (const env of [{}, { GENTLE_PI_REQUIRE_NATIVE_BINARY: "1" }]) {
+		const gate = requireNativeBinary({ ...PINNED, env });
+		assert.equal(gate.run, true);
+		assert.equal(Object.hasOwn(gate, "reason"), false);
+	}
+});
+
+test("without the env var an unresolved binary yields a skip carrying a concrete reason", () => {
+	const gate = requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: {} });
+
+	assert.equal(gate.run, false);
+	assert.match(gate.reason as string, /\S/);
+	// The reason must name what is missing and how to get it, so a reader of CI
+	// output does not have to go read the gate to understand the skip.
+	assert.match(gate.reason as string, /binary/i);
+	assert.match(gate.reason as string, new RegExp(REQUIRE_NATIVE_BINARY_ENV));
+});
+
+test("without the env var unpinned digests yield a skip with a distinct reason", () => {
+	const unresolved = requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: {} });
+	const unpinned = requireNativeBinary({ ...PINNED, digestsPinned: false, env: {} });
+
+	assert.equal(unpinned.run, false);
+	assert.match(unpinned.reason as string, /digest/i);
+	assert.notEqual(unpinned.reason, unresolved.reason, "the two causes must be distinguishable in output");
+});
+
+test("under the env var an unresolved binary throws instead of skipping", () => {
+	assert.throws(
+		() => requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: { GENTLE_PI_REQUIRE_NATIVE_BINARY: "1" } }),
+		(error: unknown) => error instanceof NativeBinaryUnavailableError && /binary/i.test((error as Error).message),
+	);
+});
+
+test("under the env var unpinned digests throw instead of skipping", () => {
+	assert.throws(
+		() => requireNativeBinary({ ...PINNED, digestsPinned: false, env: { GENTLE_PI_REQUIRE_NATIVE_BINARY: "1" } }),
+		(error: unknown) => error instanceof NativeBinaryUnavailableError && /digest/i.test((error as Error).message),
+	);
+});
+
+test("only an exact \"1\" arms the gate, so a stray value cannot silently disarm CI", () => {
+	// A truthy-looking value that is not "1" must not be treated as armed, and
+	// must not be treated as arming either: the contract is one exact value.
+	for (const value of ["0", "", "true", "yes", "false"]) {
+		const gate = requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: { GENTLE_PI_REQUIRE_NATIVE_BINARY: value } });
+		assert.equal(gate.run, false, `${JSON.stringify(value)} must not arm the gate`);
+	}
+	assert.throws(() => requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: { GENTLE_PI_REQUIRE_NATIVE_BINARY: "1" } }), NativeBinaryUnavailableError);
+});
+
+// Phase 13.12/13.13 follow-up: the same loud-skip gate, extended to the
+// third self-skipping suite (tests/devbinary/native-review-parity.devtest.ts),
+// gated behind its OWN env var so ordinary CI (no dev binary provisioned)
+// keeps skipping silently by default.
+
+test("the dev-binary env var name is distinct from the pinned-binary one", () => {
+	assert.equal(REQUIRE_DEV_BINARY_ENV, "GENTLE_PI_REQUIRE_DEV_BINARY");
+	assert.notEqual(REQUIRE_DEV_BINARY_ENV, REQUIRE_NATIVE_BINARY_ENV);
+});
+
+test("an existing dev binary path runs, and names no skip reason", () => {
+	for (const env of [{}, { GENTLE_PI_REQUIRE_DEV_BINARY: "1" }]) {
+		const gate = requireDevBinary({ devBinaryPath: "/opt/dev/gentle-ai", exists: true, env });
+		assert.equal(gate.run, true);
+		assert.equal(Object.hasOwn(gate, "reason"), false);
+	}
+});
+
+test("without the env var a missing GENTLE_AI_DEV_BINARY yields a skip carrying a concrete reason", () => {
+	const gate = requireDevBinary({ devBinaryPath: undefined, exists: false, env: {} });
+	assert.equal(gate.run, false);
+	assert.match(gate.reason as string, /GENTLE_AI_DEV_BINARY/);
+	assert.match(gate.reason as string, new RegExp(REQUIRE_DEV_BINARY_ENV));
+});
+
+test("without the env var a set but non-existent dev binary path yields a distinct skip reason", () => {
+	const missingVar = requireDevBinary({ devBinaryPath: undefined, exists: false, env: {} });
+	const badPath = requireDevBinary({ devBinaryPath: "/no/such/gentle-ai", exists: false, env: {} });
+	assert.equal(badPath.run, false);
+	assert.match(badPath.reason as string, /\/no\/such\/gentle-ai/);
+	assert.notEqual(badPath.reason, missingVar.reason, "the two causes must be distinguishable in output");
+});
+
+test("under the env var a missing dev binary throws instead of skipping", () => {
+	assert.throws(
+		() => requireDevBinary({ devBinaryPath: undefined, exists: false, env: { GENTLE_PI_REQUIRE_DEV_BINARY: "1" } }),
+		(error: unknown) => error instanceof NativeBinaryUnavailableError && /GENTLE_AI_DEV_BINARY/.test((error as Error).message),
+	);
+	assert.throws(
+		() => requireDevBinary({ devBinaryPath: "/no/such/gentle-ai", exists: false, env: { GENTLE_PI_REQUIRE_DEV_BINARY: "1" } }),
+		(error: unknown) => error instanceof NativeBinaryUnavailableError && /\/no\/such\/gentle-ai/.test((error as Error).message),
+	);
+});
+
+test("GENTLE_PI_REQUIRE_NATIVE_BINARY never arms the dev-binary gate, and vice versa", () => {
+	assert.equal(requireDevBinary({ devBinaryPath: undefined, exists: false, env: { GENTLE_PI_REQUIRE_NATIVE_BINARY: "1" } }).run, false);
+	assert.equal(requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: { GENTLE_PI_REQUIRE_DEV_BINARY: "1" } }).run, false);
+});
+
+test("the gate reads the passed env, never the ambient process env", () => {
+	const original = process.env[REQUIRE_NATIVE_BINARY_ENV];
+	try {
+		process.env[REQUIRE_NATIVE_BINARY_ENV] = "1";
+		// An explicit empty env must win: tests have to be able to exercise the
+		// unarmed branch even on a CI runner where the variable is set.
+		const gate = requireNativeBinary({ resolvedBinary: undefined, digestsPinned: true, env: {} });
+		assert.equal(gate.run, false);
+	} finally {
+		if (original === undefined) delete process.env[REQUIRE_NATIVE_BINARY_ENV];
+		else process.env[REQUIRE_NATIVE_BINARY_ENV] = original;
+	}
+});