gentle-pi 2.1.2 → 2.3.0

package/tests/fixtures/devbinary/status-v5-repository-context.captured.json

@@ -0,0 +1,138 @@
+{
+  "schema": "gentle-ai.review-integration.status/v5",
+  "contract": "gentle-ai.review-integration/v2",
+  "operation": "review.status",
+  "applicability": "current_target",
+  "authority": {
+    "version": "compact-v2",
+    "lineage_id": "review-bbfbf9af2dc27936",
+    "state": "reviewing",
+    "generation": 1,
+    "revision": "sha256:b330774b56c764047e6041de2b9071b16a772abf7cdc311c2f77cb4ecaa3a707"
+  },
+  "receipt": {
+    "status": "expected_missing"
+  },
+  "action": "finalize",
+  "replayability": "not_replayable",
+  "frozen": {
+    "tier": "medium",
+    "original_changed_lines": 1,
+    "correction_budget": 1
+  },
+  "target_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab",
+  "projection": {
+    "schema": "gentle-ai.review-integration.projection/v1",
+    "kind": "current-changes",
+    "projection": "workspace",
+    "base_tree": "7bee507cb7f5aa4dce34e6962366eeea27935c74",
+    "initial_review_tree": "a044376c6cfb84e30c676ff7307e92bcfef5b6ec",
+    "current_candidate_tree": "a044376c6cfb84e30c676ff7307e92bcfef5b6ec",
+    "paths_digest": "sha256:4d916b1a185d946866be1c2f945425ea650ea045dec13bb0ec972744f0f9bd61",
+    "paths": [
+      "file.txt"
+    ],
+    "intended_untracked": [],
+    "intended_untracked_proof": "sha256:b97229718d4c7fe50a8892eb474ae5aa6491697bccb400e3e31dbaca4894d2f3",
+    "initial_snapshot_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab",
+    "current_snapshot_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab"
+  },
+  "repair": {
+    "schema": "gentle-ai.review-authority-repair-assessment/v1",
+    "status": "unsupported",
+    "counts": {
+      "lineages": 0,
+      "compact_lineages": 0,
+      "legacy_lineages": 0,
+      "events": 0,
+      "bytes": 0,
+      "eligible_candidates": 0,
+      "unsupported_lineages": 0,
+      "conflicts": 0
+    },
+    "supported_operations": [
+      "review/complete-fix",
+      "review/validate-fix"
+    ],
+    "authorization_schema": "gentle-ai.review-repair-authorization/v1"
+  },
+  "candidates": [],
+  "forecast": {
+    "horizon": "partial",
+    "steps": [
+      {
+        "step": 1,
+        "kind": "execute",
+        "reason_code": "captured_results_ready",
+        "description": "Captured reviewer results are complete and ready for finalization"
+      }
+    ]
+  },
+  "next_transition": {
+    "kind": "execute",
+    "reason_code": "captured_results_ready",
+    "execute": {
+      "operation": "review.finalize",
+      "command": "gentle-ai review finalize --lineage=review-bbfbf9af2dc27936 --captured-results=true --contract=gentle-ai.review-integration/v2 --agent=claude-code",
+      "arguments": [
+        {
+          "name": "lineage",
+          "value": "review-bbfbf9af2dc27936",
+          "token": "--lineage=review-bbfbf9af2dc27936"
+        },
+        {
+          "name": "captured_results",
+          "value": "true",
+          "token": "--captured-results=true"
+        },
+        {
+          "name": "contract",
+          "value": "gentle-ai.review-integration/v2",
+          "token": "--contract=gentle-ai.review-integration/v2"
+        },
+        {
+          "name": "agent",
+          "value": "claude-code",
+          "token": "--agent=claude-code"
+        }
+      ],
+      "preconditions": [
+        {
+          "name": "state",
+          "value": "reviewing"
+        },
+        {
+          "name": "captured_artifacts",
+          "value": "complete"
+        }
+      ],
+      "binding": {
+        "lineage_id": "review-bbfbf9af2dc27936",
+        "revision": "sha256:b330774b56c764047e6041de2b9071b16a772abf7cdc311c2f77cb4ecaa3a707",
+        "target_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab",
+        "repository_context": "rctx1_7da80fda377da87da8aae62204c531e697bd6a4a6bbd5de21ddd3861150fb725"
+      },
+      "artifacts": [
+        {
+          "schema": "gentle-ai.review-result-artifact/v2",
+          "capability": "review.native_result_artifact",
+          "sha256": "sha256:02a403472b0bb0c7ad5dddd1010b006af257f516e425795996f276d423d33c9d",
+          "lineage_id": "review-bbfbf9af2dc27936",
+          "target_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab",
+          "lens": "review-reliability",
+          "selected_order": 0,
+          "subject_hash": "sha256:620703b2e6f074e031712f501eb9fe460bb17bd0cbbd70db10be5dc4fa2dfead",
+          "admission_decision": "completed"
+        }
+      ]
+    }
+  },
+  "repository_context": {
+    "capability": "review.opaque_repository_context",
+    "handle": "rctx1_7da80fda377da87da8aae62204c531e697bd6a4a6bbd5de21ddd3861150fb725",
+    "revision": "sha256:b330774b56c764047e6041de2b9071b16a772abf7cdc311c2f77cb4ecaa3a707",
+    "target_identity": "sha256:bbfbf9af2dc27936d5fbc0c30579d5122d65bf4ccc65d9a00cde816f3aa6d3ab",
+    "event_id": "sha256:5d2588ff1422f4568588986a2e2872bae60f0fef4131df81a6e3bdad9f8fa76a",
+    "outcome": "applied"
+  }
+}

package/tests/fixtures/devbinary/status-v5.captured.json

@@ -0,0 +1,88 @@
+{
+  "schema": "gentle-ai.review-integration.status/v5",
+  "contract": "gentle-ai.review-integration/v2",
+  "operation": "review.status",
+  "applicability": "unrelated",
+  "receipt": {
+    "status": "not_applicable"
+  },
+  "action": "start",
+  "replayability": "not_replayable",
+  "target_identity": "sha256:50d13aa33f913bbf99df6ad5b94ac1db2aba969445ffc08aadffd8b42b79f1c4",
+  "projection": {
+    "schema": "gentle-ai.review-integration.projection/v1",
+    "kind": "current-changes",
+    "projection": "workspace",
+    "base_tree": "619289f137abd616d94899f2c9b6726de091ac92",
+    "initial_review_tree": "619289f137abd616d94899f2c9b6726de091ac92",
+    "current_candidate_tree": "619289f137abd616d94899f2c9b6726de091ac92",
+    "paths_digest": "sha256:2286a180488f90f2e97062d500a629bc747716d55a34c2861a8309e1b02589a1",
+    "paths": [],
+    "intended_untracked": [],
+    "intended_untracked_proof": "sha256:b97229718d4c7fe50a8892eb474ae5aa6491697bccb400e3e31dbaca4894d2f3",
+    "initial_snapshot_identity": "sha256:50d13aa33f913bbf99df6ad5b94ac1db2aba969445ffc08aadffd8b42b79f1c4",
+    "current_snapshot_identity": "sha256:50d13aa33f913bbf99df6ad5b94ac1db2aba969445ffc08aadffd8b42b79f1c4"
+  },
+  "repair": {
+    "schema": "gentle-ai.review-authority-repair-assessment/v1",
+    "status": "unsupported",
+    "counts": {
+      "lineages": 0,
+      "compact_lineages": 0,
+      "legacy_lineages": 0,
+      "events": 0,
+      "bytes": 0,
+      "eligible_candidates": 0,
+      "unsupported_lineages": 0,
+      "conflicts": 0
+    },
+    "supported_operations": [
+      "review/complete-fix",
+      "review/validate-fix"
+    ],
+    "authorization_schema": "gentle-ai.review-repair-authorization/v1"
+  },
+  "candidates": [],
+  "forecast": {
+    "horizon": "partial",
+    "steps": [
+      {
+        "step": 1,
+        "kind": "collect",
+        "reason_code": "empty_candidate_base_ref_required",
+        "description": "empty candidate base ref required"
+      }
+    ]
+  },
+  "next_transition": {
+    "kind": "collect",
+    "reason_code": "empty_candidate_base_ref_required",
+    "collect": {
+      "inputs": [
+        {
+          "name": "base_ref",
+          "schema": "gentle-ai.review-base-ref-selection/v1",
+          "capture_operation": "external.select_base_ref",
+          "arguments": [
+            {
+              "name": "target_identity",
+              "value": "sha256:50d13aa33f913bbf99df6ad5b94ac1db2aba969445ffc08aadffd8b42b79f1c4"
+            },
+            {
+              "name": "projection",
+              "value": "workspace"
+            },
+            {
+              "name": "base_tree",
+              "value": "619289f137abd616d94899f2c9b6726de091ac92"
+            },
+            {
+              "name": "candidate_tree",
+              "value": "619289f137abd616d94899f2c9b6726de091ac92"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}

package/tests/fixtures/native-review-cli/v2.5.0-rc.1/PROVENANCE.txt

@@ -0,0 +1,15 @@
+Captured from a real gentle-ai binary, not hand-authored.
+
+binary:  gentle-ai 2.5.0-rc.1.0.20260827194839-f654764e231f (published prerelease channel)
+date:    2026-08-28
+command: gentle-ai sdd-status agent-builder --cwd <repo> --json --instructions
+repo:    a gentle-ai checkout with an OpenSpec-backed change present
+
+Why this fixture exists: gentle-ai commit 3c4c7fb6 (2026-08-24, "refactor(sdd)!:
+replace status v1 with clean v2") moved SchemaVersion from 1 to 2. gentle-pi had
+no v2 decoder, so lib/native-review-cli.ts rejected every current status with
+IDENTITY_MISMATCH on `body.schemaVersion !== 1`.
+
+The v2 object shape is key-compatible with the v1 decoder's exactObject list:
+17 required keys plus the optional phaseInstructions. Only the version value and
+the widened artifactStore domain (which gains "hybrid") differ.

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

@@ -0,0 +1,12 @@
+# 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.
+
+Go remains the admission authority for prompts, results, receipts, and delivery gates.

package/tests/fixtures/provider-contract-bundle/v1.1.0/manifest.json

@@ -0,0 +1,65 @@
+{
+  "schema": "gentle-ai.review-provider-contract-bundle/v1",
+  "contract_semver": "1.1.0",
+  "transport_capability": "gentle-ai.provider-transport/v1",
+  "runtimes": [
+    "claude-code",
+    "codex",
+    "opencode",
+    "pi"
+  ],
+  "readme": {
+    "path": "README.md",
+    "sha256": "d14647c8753bd85e18b8a593bef9dfcb4c9d8ea01e32ecd36847dc4304027b1d"
+  },
+  "roles": [
+    {
+      "id": "lens",
+      "request_schema_id": "gentle-ai.review-lens-context/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/reviewer/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/lens.schema.json",
+        "sha256": "ffef79cfb763333282285ff5c795a32b5a88d840b4a8d125ce012188b04cffe1"
+      },
+      "vector": {
+        "path": "vectors/lens.json",
+        "sha256": "7ef0b08404645eeb5dba92aba5f8e4780667b6ec775f43ed8547ff9f2a7148c8"
+      }
+    },
+    {
+      "id": "refuter",
+      "request_schema_id": "gentle-ai.review-provider-refuter-request/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/refuter/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/refuter.schema.json",
+        "sha256": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646"
+      },
+      "vector": {
+        "path": "vectors/refuter.json",
+        "sha256": "f42d71906e49c4191660b2da7e70f01f1778b23d32089005bd2d7ae9cbb73039"
+      }
+    },
+    {
+      "id": "targeted-validator",
+      "request_schema_id": "gentle-ai.review-targeted-validation-request/v1",
+      "result_schema_id": "https://gentle-ai.dev/schema/review/validator/v1",
+      "required_capabilities": [
+        "gentle-ai.provider-transport/v1"
+      ],
+      "schema": {
+        "path": "schemas/targeted-validator.schema.json",
+        "sha256": "58f5efca0fb8089a51e998d5cf07209528a6b6e3782246b34ee1e825132063a8"
+      },
+      "vector": {
+        "path": "vectors/targeted-validator.json",
+        "sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
+      }
+    }
+  ]
+}

package/tests/fixtures/provider-contract-bundle/v1.1.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.1.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.1.0/schemas/targeted-validator.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean"},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}}}}},"examples":[{"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":[]}]}

package/tests/fixtures/provider-contract-bundle/v1.1.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.1.0/vectors/refuter.json

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

package/tests/fixtures/provider-contract-bundle/v1.1.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":[]}

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

@@ -1,17 +1,23 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import test from "node:test";
 import {
 	GENTLE_AI_BINARY_MISSING_CODE,
+	GENTLE_AI_DEV_BINARY_ENV,
 	GENTLE_AI_VERSION,
+	gentleAiDevBinaryRegistrationPath,
 	PackageLocalGentleAiBinaryMissingError,
+	registerGentleAiDevBinary,
 	resolveGentleAiBinary,
+	setGentleAiDevBinaryEnvironmentForTesting,
+	unregisterGentleAiDevBinary,
+	type GentleAiDevBinaryEnvironment,
 } from "../lib/gentle-ai-binary.ts";
-import { NativeReviewCliV213, createNativeReviewCli, type ExecFileAdapter } from "../lib/native-review-cli.ts";
+import { NativeReviewCliV216, createNativeReviewCli, type ExecFileAdapter } from "../lib/native-review-cli.ts";
 import { GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM, resolveGentleAiReleaseAsset } from "../scripts/gentle-ai-installer.mjs";
 import { requireNativeBinary } from "./support/native-binary-gate.ts";
 
@@ -29,6 +35,47 @@ const nativeBinaryGate = requireNativeBinary({
 if (!nativeBinaryGate.run) console.log(`gentle-ai-binary: ${nativeBinaryGate.reason}`);
 const verifiedBinaryTest = nativeBinaryGate.run && process.platform !== "win32" ? test : test.skip;
 
+interface PinnedBinaryIsolation {
+	environment: GentleAiDevBinaryEnvironment;
+	savedEnvironmentValue: string | undefined;
+	savedRegistration: string | undefined;
+}
+
+let pinnedBinaryIsolation: PinnedBinaryIsolation | undefined;
+
+test.beforeEach((t) => {
+	const home = mkdtempSync(join(tmpdir(), "gentle-pi-pinned-binary-home-"));
+	const environment: GentleAiDevBinaryEnvironment = { env: { ...process.env }, home };
+	delete environment.env.GENTLE_PI_CONFIG_HOME;
+	const savedEnvironmentValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	const savedRegistration = existsSync(registrationPath)
+		? readFileSync(registrationPath, "utf8")
+		: undefined;
+
+	delete environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	unregisterGentleAiDevBinary(environment);
+	setGentleAiDevBinaryEnvironmentForTesting(environment);
+	pinnedBinaryIsolation = { environment, savedEnvironmentValue, savedRegistration };
+
+	t.after(() => {
+		if (savedEnvironmentValue === undefined) {
+			delete environment.env[GENTLE_AI_DEV_BINARY_ENV];
+		} else {
+			environment.env[GENTLE_AI_DEV_BINARY_ENV] = savedEnvironmentValue;
+		}
+		if (savedRegistration === undefined) {
+			unregisterGentleAiDevBinary(environment);
+		} else {
+			mkdirSync(dirname(registrationPath), { recursive: true });
+			writeFileSync(registrationPath, savedRegistration);
+		}
+		setGentleAiDevBinaryEnvironmentForTesting(undefined);
+		pinnedBinaryIsolation = undefined;
+		rmSync(home, { recursive: true, force: true });
+	});
+});
+
 async function writeVerifiedBinary(packageRoot: string, platform = process.platform): Promise<string> {
 	const asset = resolveGentleAiReleaseAsset(platform, process.arch);
 	const binaryPath = join(packageRoot, ".gentle-ai", RUNTIME_DIRECTORY, asset.executable);
@@ -50,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v2",
-		tag: "v2.2.2",
+		tag: "v2.5.0",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
@@ -64,13 +111,34 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 	return { binaryPath, manifestPath };
 }
 
-verifiedBinaryTest("runtime resolves an absolute package-local binary path without PATH fallback", async () => {
+verifiedBinaryTest("runtime resolves an absolute package-local binary path without PATH fallback or ambient dev contamination", async () => {
 	const packageRoot = await mkdtemp(join(tmpdir(), "gentle-pi-binary-"));
 	const executable = process.platform === "win32" ? "gentle-ai.exe" : "gentle-ai";
 	const binaryPath = await writeVerifiedBinary(packageRoot);
+	const devBinary = join(packageRoot, "maintainer-dev-binary");
+	await writeFile(devBinary, "maintainer dev binary");
+	if (process.platform !== "win32") await chmod(devBinary, 0o700);
+	const isolation = pinnedBinaryIsolation;
+	assert.ok(isolation, "the pinned-binary fixture must install its isolated environment");
+
+	const ambientValue = process.env[GENTLE_AI_DEV_BINARY_ENV];
+	process.env[GENTLE_AI_DEV_BINARY_ENV] = devBinary;
+	try {
+		assert.equal(resolveGentleAiBinary(packageRoot, process.platform), binaryPath, "a maintainer's ambient override must not contaminate a pinned-package case");
+	} finally {
+		if (ambientValue === undefined) delete process.env[GENTLE_AI_DEV_BINARY_ENV];
+		else process.env[GENTLE_AI_DEV_BINARY_ENV] = ambientValue;
+	}
+
+	isolation.environment.env[GENTLE_AI_DEV_BINARY_ENV] = devBinary;
+	assert.equal(resolveGentleAiBinary(packageRoot, process.platform), devBinary, "an explicit dev-binary test may opt in through the isolated environment seam");
+	delete isolation.environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	registerGentleAiDevBinary(devBinary, isolation.environment);
+	assert.equal(resolveGentleAiBinary(packageRoot, process.platform), devBinary, "an explicit persistent dev registration may opt in through the isolated environment seam");
+	assert.equal(unregisterGentleAiDevBinary(isolation.environment), true);
 
 	const resolved = resolveGentleAiBinary(packageRoot, process.platform);
-	assert.equal(resolved, binaryPath);
+	assert.equal(resolved, binaryPath, "clearing the explicit registration restores the pinned resolver");
 	assert.equal(isAbsolute(resolved), true);
 	assert.equal(basename(resolved), executable);
 	assert.doesNotMatch(resolved, /(^|[/\\])PATH($|[/\\])/i);
@@ -124,7 +192,7 @@ test("runtime rejects an unverified binary, a symlinked manifest, and ambient ex
 	await writeFile(manifestTarget, `${JSON.stringify({ version: GENTLE_AI_VERSION, asset: `gentle-ai_${GENTLE_AI_VERSION}_${process.platform}_${process.arch === "x64" ? "amd64" : process.arch}.tar.gz`, assetSha256: "a".repeat(64), binarySha256 })}\n`);
 	await symlink(manifestTarget, manifestPath);
 	assert.throws(() => resolveGentleAiBinary(packageRoot, process.platform), /package-local-binary-missing/);
-	assert.throws(() => new NativeReviewCliV213(async () => VERSION, "gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(async () => VERSION, "gentle-ai"), /absolute package-local executable/);
 });
 
 verifiedBinaryTest("runtime rejects malformed, unknown, wrong, and symlinked integrity paths", async () => {
@@ -224,16 +292,18 @@ verifiedBinaryTest("production native client never invokes a global gentle-ai ex
 	const calls: string[] = [];
 	const adapter: ExecFileAdapter = async (request) => {
 		calls.push(request.file);
-		if (request.arguments[0] === "version") return VERSION;
 		return {
 			...VERSION,
-			stdout: JSON.stringify({ operation: "review/start", lineage_id: "lineage", state: "reviewing", risk_level: "low", selected_lenses: [], changed_files: 0, changed_lines: 0, correction_budget: 0, action: "created", lenses_required: false, projection: "workspace" }),
+			stdout: readFileSync(join(import.meta.dirname, "..", "contracts", "review-integration", "v2", "fixtures", "status.fixture.json"), "utf8"),
 		};
 	};
 
-	await createNativeReviewCli(adapter, () => resolveGentleAiBinary(packageRoot, process.platform)).start({ cwd: packageRoot });
-	assert.deepEqual(calls, [binaryPath, binaryPath]);
+	await assert.rejects(
+		() => createNativeReviewCli(adapter, () => resolveGentleAiBinary(packageRoot, process.platform)).targetStatus!({ cwd: packageRoot, lineageId: "review-status-fixture" }),
+		/schema incompatible/,
+	);
+	assert.deepEqual(calls, [binaryPath]);
 	assert.ok(calls.every((file) => file !== "gentle-ai"));
-	assert.throws(() => new NativeReviewCliV213(adapter, "gentle-ai"), /absolute package-local executable/);
-	assert.throws(() => new NativeReviewCliV213(adapter, "./gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(adapter, "gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(adapter, "./gentle-ai"), /absolute package-local executable/);
 });