gentle-pi 2.2.0 → 2.4.0

package/tests/orchestrator-rdd-ownership.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT = join(import.meta.dirname, "..");
+const ASSETS = join(ROOT, "assets");
+const BOUNDARY =
+	"This package injects the mirrored provider-bundle review execution contract into this session's system prompt at start; Gentle AI writes nothing into the Pi system prompt, and this package owns everything else here. Absent that mirrored contract, this package invents no lifecycle instructions.";
+
+function read(relativePath: string): string {
+	return readFileSync(join(ROOT, relativePath), "utf8");
+}
+
+const core = read("assets/orchestrator.md");
+const delegation = read("assets/orchestrator-delegation.md");
+const staticPrompts = `${core}\n${delegation}`;
+
+test("static prompts omit stale native RDD lifecycle mirrors", () => {
+	for (const marker of [
+		"Authority-First Terminal Procedure",
+		"reconcile-terminal-mirrors",
+		"Native Bounded Review Orchestration",
+		"Continue after a stop reason code",
+		"gentle-ai review status",
+		"next_transition",
+		"start -> finalize -> validate",
+		"review.capture-result",
+		"review.validate",
+		"reviewGate.result",
+	]) {
+		assert.ok(!staticPrompts.includes(marker), `stale RDD marker remains: ${marker}`);
+	}
+});
+
+test("lossless blocking prompts route every closed single-select envelope through the native closed tool", () => {
+	for (const clause of [
+		"For every strictly closed single-select envelope",
+		"ask_user_choice",
+		"envelope-owned canonical option token as opaque `value`",
+		"returns exactly one `value`",
+		"externally owned open/free-text questionnaire",
+		"never for a closed domain",
+		"exact captured provider-owned choice invocation",
+	]) {
+		assert.ok(delegation.includes(clause), `lossless prompt is missing: ${clause}`);
+	}
+});
+
+test("static prompts declare one dynamic Gentle AI RDD ownership boundary", () => {
+	assert.equal(staticPrompts.split(BOUNDARY).length - 1, 1, "expected one dynamic RDD ownership boundary");
+	assert.ok(core.includes(BOUNDARY), "the Pi parent prompt owns the single boundary");
+	assert.ok(!delegation.includes(BOUNDARY), "generic delegation detail must not gain RDD text");
+});
+
+test("rendered parent prompt keeps the RDD boundary while omitting lifecycle mirrors", async () => {
+	const { __testing } = await import("../extensions/gentle-ai.ts");
+	const rendered = __testing.getOrchestratorPrompt();
+	assert.ok(rendered.includes(BOUNDARY));
+	for (const marker of ["Authority-First Terminal Procedure", "reconcile-terminal-mirrors", "next_transition"]) {
+		assert.ok(!rendered.includes(marker), `rendered parent prompt leaked: ${marker}`);
+	}
+	assert.ok(Buffer.byteLength(rendered, "utf8") <= 8192, "the rendered parent prompt must stay below the reduced 8 KiB budget");
+});
+
+test("static prompts retain normal SDD and delegated-work guidance", () => {
+	for (const heading of ["## SDD Workflow (lazy-loaded)", "## Memory Contract"]) {
+		assert.ok(core.includes(heading), `core lost ${heading}`);
+	}
+	for (const heading of [
+		"### Delegation Rules",
+		"#### Background Subagent Policy",
+		"#### Allowed edit surfaces (MANDATORY)",
+		"### 3. SDD (optional)",
+	]) {
+		assert.ok(delegation.includes(heading), `delegation lost ${heading}`);
+	}
+});
+
+test("always-on parent prompt requires a narrow writer edit surface before launch", () => {
+	assert.match(core, /Before launching (?:a )?bounded writer/i);
+	assert.match(core, /`gentle-ai-worker`/);
+	assert.match(core, /`worker`/);
+	assert.match(core, /## Allowed edit surfaces/);
+	assert.match(core, /repository-relative/i);
+	assert.match(core, /never `\.`|never a bare repository root/i);
+	assert.match(core, /do not ask the human to author paths or globs/i);
+});
+
+test("review integration documents the opaque Pi adapter and Go-owned authority boundary", () => {
+	const docs = read("docs/review-integration.md");
+	for (const marker of [
+		"Buffer → Buffer/error",
+		"exact Go-issued materialize/submission tokens",
+		"typed Pi transport refusal fails closed",
+		"Go owns worktree, lineage, candidate freeze, lens selection, correction, validator, approval burn, and review semantics",
+		"Delivery commands remain ordinary repository-policy operations.",
+		"package has no durable receipt or policy authority",
+		"static assets intentionally omit lifecycle instructions",
+	]) {
+		assert.ok(docs.includes(marker), `review integration doc is missing: ${marker}`);
+	}
+});

package/tests/package-manifest.test.ts

@@ -9,11 +9,12 @@ import {
 	rmSync,
 	writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { applyModelConfig } from "../extensions/gentle-ai.ts";
+import { resolveGentlePiAgentHome } from "../lib/agent-home.ts";
 import { installSddAssets } from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -114,10 +115,10 @@ test("package verification names the native review runtime boundary and packaged
 	const manifest = readPackageJson();
 
 	assert.ok(manifest.files?.includes("lib/"), "the published package must include the native review runtime module directory");
-	assert.ok(manifest.files?.includes("runtime/"), "the published package must include the generated JavaScript transaction runtime");
+	assert.ok(manifest.files?.includes("runtime/"), "the published package must include generated JavaScript runtime modules");
 	assert.match(verifier, /"lib\/native-review-cli\.ts"/, "package verification must require the native review adapter from the packaged runtime");
-	assert.match(verifier, /"runtime\/git-commit-transaction\.mjs"/, "package verification must require the installed JavaScript transaction runtime");
-	assert.match(verifier, /build-git-commit-transaction-runner\.mjs.*--check/s, "package verification must reject generated-runtime drift");
+	assert.match(verifier, /"runtime\/native-review-cli\.mjs"/, "package verification must require the generated native review adapter");
+	assert.match(verifier, /build-runtime-modules\.mjs.*--check/s, "package verification must reject generated-runtime drift");
 	assert.match(verifier, /"tests\/fixtures\/native-review-cli\/v2\.1\.3\/start\.json"/, "package verification must retain the pinned native decoder fixture");
 	assert.match(
 		readFileSync(join(PACKAGE_ROOT, "extensions", "gentle-ai.ts"), "utf8"),
@@ -187,36 +188,31 @@ test("npm publication is bound to the exact package tag and triggering commit",
 	assert.doesNotMatch(releaseSkill, /--ref "\$\{tag\}"|-f dist-tag=/);
 });
 
-test("publication gate is isolated from graph-v1 authority storage", () => {
+test("Pi delivery relay is absent from the packaged extension", () => {
 	const extension = readFileSync(join(PACKAGE_ROOT, "extensions", "gentle-ai.ts"), "utf8");
-	const gate = readFileSync(join(PACKAGE_ROOT, "lib", "review-publication-gate.ts"), "utf8");
-	const transaction = readFileSync(join(PACKAGE_ROOT, "lib", "review-transaction.ts"), "utf8");
 
-	assert.match(extension, /from "\.\.\/lib\/review-publication-gate\.ts"/);
-	assert.match(transaction, /from "\.\/review-publication-gate\.ts"/);
-	assert.doesNotMatch(gate, /review-(?:transaction|object-store|graph-schema|lock|snapshot)/);
-	assert.doesNotMatch(transaction, /export function evaluateReleaseFastPathV1|export function resolveConfiguredPushDestinationV1/);
+	assert.doesNotMatch(extension, /review-publication-gate/);
 });
 
-test("installed commit transaction runner loads JavaScript only and has deterministic build checks", () => {
+test("generated runtime modules and packed-package checks are deterministic", () => {
 	const packageJson = readPackageJson();
-	const runner = readFileSync(join(PACKAGE_ROOT, "scripts", "run-git-commit-transaction.mjs"), "utf8");
+	const generator = readFileSync(join(PACKAGE_ROOT, "scripts", "build-runtime-modules.mjs"), "utf8");
 	const packedRunner = readFileSync(join(PACKAGE_ROOT, "scripts", "test-packed-runner.mjs"), "utf8");
 	const ci = readFileSync(join(PACKAGE_ROOT, ".github", "workflows", "ci.yml"), "utf8");
-	assert.equal(packageJson.scripts?.["build:transaction-runner"], "node scripts/build-git-commit-transaction-runner.mjs --write");
-	assert.equal(packageJson.scripts?.["check:transaction-runner"], "node scripts/build-git-commit-transaction-runner.mjs --check");
-	assert.equal(packageJson.scripts?.["test:packed-runner"], "node scripts/test-packed-runner.mjs");
-	assert.match(packageJson.scripts?.prepublishOnly ?? "", /pnpm run test:packed-runner/);
-	assert.match(ci, /pnpm run test:packed-runner/);
+	assert.equal(packageJson.scripts?.["build:runtime-modules"], "node scripts/build-runtime-modules.mjs --write");
+	assert.equal(packageJson.scripts?.["check:runtime-modules"], "node scripts/build-runtime-modules.mjs --check");
+	assert.equal(packageJson.scripts?.["test:packed-package"], "node scripts/test-packed-runner.mjs");
+	assert.match(packageJson.scripts?.prepublishOnly ?? "", /pnpm run test:packed-package/);
+	assert.match(ci, /pnpm run check:runtime-modules/);
+	assert.match(ci, /pnpm run test:packed-package/);
+	assert.match(generator, /Generated by scripts\/build-runtime-modules\.mjs/);
 	assert.match(packedRunner, /\["install"[^\]]*"--ignore-scripts=false"/s, "packed install must explicitly enable postinstall");
 	assert.doesNotMatch(packedRunner, /\["install"[^\]]*"--ignore-scripts"(?!\=false)/s);
 	assert.match(packedRunner, /execFileSync\("where\.exe", \["npm"\]/);
 	assert.match(packedRunner, /could not resolve npm-cli\.js without a command shell/);
 	assert.doesNotMatch(packedRunner, /ComSpec|cmd\.exe/);
 	assert.match(packedRunner, /review", "capabilities", "--contract", "gentle-ai\.review-integration\/v2"/);
-	assert.match(runner, /\.\.\/runtime\/git-commit-transaction\.mjs/);
-	assert.doesNotMatch(runner, /\.ts["']/);
-	assert.doesNotMatch(runner, /experimental-strip-types/);
+	assert.doesNotMatch(packedRunner, /git-commit-transaction|transaction runner/i);
 });
 
 test("package manifest ships and runs the checked-in package-local Gentle AI installer", () => {
@@ -266,20 +262,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v2.4.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v2.6.0 runtime pin", () => {
 	const installer = readFileSync(join(PACKAGE_ROOT, "scripts", "gentle-ai-installer.mjs"), "utf8");
 	const binary = readFileSync(join(PACKAGE_ROOT, "lib", "gentle-ai-binary.ts"), "utf8");
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
 
-	assert.match(installer, /INSTALLER_VERSION = "2\.4\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "2\.6\.0"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:XKkcy\+t76cyUKQnRwL1UnqHbhh8o416I8HQ1UsdvWSI="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:scGoZYnPHh4oCVqlcfQAOSpm22Ii5lmB0kBbiBKvNZk="/);
 	assert.match(installer, /GOTOOLCHAIN: "local"/);
 	assert.match(installer, /GOSUMDB: "sum\.golang\.org"/);
 	assert.match(binary, /GENTLE_AI_VERSION = INSTALLER_VERSION/);
 	assert.match(binary, /GO_SUMDB_SOURCE_BUILD/);
 	assert.match(binary, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM/);
-	assert.match(verifier, /v2\.4\.0/);
+	assert.match(verifier, /v2\.6\.0/);
 });
 
 
@@ -900,6 +896,22 @@ test("jd-fix-agent packaged allowlist includes write tools", () => {
 	}
 });
 
+test("sdd-explore packages its CodeGraph-enabled exploration allowlist", () => {
+	const agentPath = join(PACKAGE_ROOT, "assets", "agents", "sdd-explore.md");
+	const { name, tools } = readAgentDefinition(agentPath);
+
+	assert.equal(name, "sdd-explore");
+	assert.deepEqual(tools, [
+		"read",
+		"grep",
+		"find",
+		"codegraph",
+		"edit",
+		"write",
+		"mem_save",
+	]);
+});
+
 test("gentle-ai-worker packages the exact scoped writer contract", () => {
 	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
 	const agentPath = join(agentsDir, "gentle-ai-worker.md");
@@ -981,6 +993,10 @@ test("gentle-ai-worker packages the exact scoped writer contract", () => {
 	const contextContract = readMarkdownSection(source, "Context contract");
 	assert.match(contextContract, /pre-existing untracked targets explicitly listed by the parent/);
 	assert.match(contextContract, /new files required by the delegated task/);
+	assert.match(contextContract, /derived candidate set the human can approve or narrow/);
+	assert.match(contextContract, /never an open request for the human to author paths or globs/);
+	assert.match(interactionContract, /closed set the human can approve, decline, or select from/);
+	assert.match(interactionContract, /never ask the human to author paths, globs, identifiers, or commands as free text/);
 
 	const implementationRules = readMarkdownSection(source, "Implementation rules");
 	assert.match(implementationRules, /`blocked` only for a non-human technical blocker/);
@@ -1056,6 +1072,103 @@ test("installSddAssets installs gentle-ai-worker with a loader-compatible scoped
 	);
 });
 
+test("agent home resolver centralizes Gentle and Pi agent-dir precedence", () => {
+	const explicitGentleHome = mkdtempSync(join(tmpdir(), "gentle-pi-resolver-explicit-"));
+	const piAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-resolver-pi-dir-"));
+
+	try {
+		assert.equal(
+			resolveGentlePiAgentHome({
+				GENTLE_PI_AGENT_HOME: explicitGentleHome,
+				PI_CODING_AGENT_DIR: piAgentDir,
+			}),
+			explicitGentleHome,
+		);
+		assert.equal(resolveGentlePiAgentHome({ PI_CODING_AGENT_DIR: piAgentDir }), piAgentDir);
+		assert.equal(resolveGentlePiAgentHome({}), join(homedir(), ".pi", "agent"));
+		assert.equal(
+			resolveGentlePiAgentHome({ GENTLE_PI_AGENT_HOME: "", PI_CODING_AGENT_DIR: piAgentDir }),
+			piAgentDir,
+			"an empty explicit override falls through like Pi Subagents does",
+		);
+		assert.equal(
+			resolveGentlePiAgentHome({ PI_CODING_AGENT_DIR: "" }),
+			join(homedir(), ".pi", "agent"),
+			"an empty PI_CODING_AGENT_DIR falls through like Pi Subagents does",
+		);
+	} finally {
+		rmSync(explicitGentleHome, { recursive: true, force: true });
+		rmSync(piAgentDir, { recursive: true, force: true });
+	}
+});
+
+test("asset installation uses PI_CODING_AGENT_DIR as the Pi agent home when no explicit Gentle override is set", () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+	const temporaryPiAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-agent-dir-"));
+	const explicitGentleHome = mkdtempSync(join(tmpdir(), "gentle-pi-explicit-home-"));
+
+	try {
+		delete process.env.GENTLE_PI_AGENT_HOME;
+		process.env.PI_CODING_AGENT_DIR = temporaryPiAgentDir;
+
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const installedPath = join(temporaryPiAgentDir, "agents", "gentle-ai-explore.md");
+		assert.ok(existsSync(installedPath), "managed agents must install where Pi Subagents reads global definitions");
+		assert.deepEqual(readAgentDefinition(installedPath).tools, MANAGED_EXEMPLAR_TOOLS);
+		assert.ok(
+			!existsSync(join(explicitGentleHome, "agents", "gentle-ai-explore.md")),
+			"the explicit override fixture must still be untouched before it is selected",
+		);
+
+		process.env.GENTLE_PI_AGENT_HOME = explicitGentleHome;
+		installSddAssets(PACKAGE_ROOT, true);
+		assert.ok(
+			existsSync(join(explicitGentleHome, "agents", "gentle-ai-explore.md")),
+			"GENTLE_PI_AGENT_HOME remains the explicit test/operator override",
+		);
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousPiAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+		rmSync(temporaryPiAgentDir, { recursive: true, force: true });
+		rmSync(explicitGentleHome, { recursive: true, force: true });
+	}
+});
+
+test("global model routing uses PI_CODING_AGENT_DIR for package-installed agents", () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+	const temporaryPiAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-model-agent-dir-"));
+	const temporaryProject = mkdtempSync(join(tmpdir(), "gentle-pi-model-project-"));
+
+	try {
+		delete process.env.GENTLE_PI_AGENT_HOME;
+		process.env.PI_CODING_AGENT_DIR = temporaryPiAgentDir;
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const result = applyModelConfig(temporaryProject, {
+			"gentle-ai-explore": { model: "provider/model", thinking: "high" },
+		});
+
+		assert.equal(result.updated, 2);
+		const config = JSON.parse(readFileSync(join(temporaryPiAgentDir, "subagents.json"), "utf8"));
+		assert.deepEqual(config.model_profiles["gentle-ai-explore"], {
+			model: "provider/model",
+			effort: "high",
+		});
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousPiAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+		rmSync(temporaryPiAgentDir, { recursive: true, force: true });
+		rmSync(temporaryProject, { recursive: true, force: true });
+	}
+});
+
 test("normal and forced installation copy generic agents with complete role contracts", () => {
 	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
 	const expectedTools = {
@@ -1129,7 +1242,7 @@ test("bounded implementation routing uses the same explicit fallback in both pol
 	);
 });
 
-test("orchestrator routes generic roles without reusing SDD or review agents", () => {
+test("orchestrator routes generic roles without static RDD lens routing", () => {
 	for (const file of ["orchestrator.md", "orchestrator-delegation.md"]) {
 		const routing = readFileSync(join(PACKAGE_ROOT, "assets", file), "utf8");
 		assert.match(routing, /generic non-SDD exploration[\s\S]*`gentle-ai-explore`/);
@@ -1139,12 +1252,16 @@ test("orchestrator routes generic roles without reusing SDD or review agents", (
 		);
 		assert.match(routing, /generic non-SDD (?:technical )?verification[\s\S]*`gentle-ai-verify`/);
 		assert.match(routing, /SDD roles stay inside SDD|Use `sdd-explore` and `sdd-verify` only inside SDD/);
-		assert.match(routing, /review lenses inside reviews|Use review lenses only inside explicit review transactions/);
-		assert.match(routing, /(?:truly local )?read-only check(?:ing)? of (?:known )?1-3 known files|1-3-file read-only check/);
+		assert.match(routing, /(?:truly local )?read-only check(?:ing)? of (?:known )?1[-–]3 known files|1[-–]3-file read-only check/);
 		assert.match(routing, /(?:verification that |verification commands →).*executes? or delegates?|executing\/delegating verification commands/);
 		assert.match(routing, /missing(?: or |\/)unusable[\s\S]*native `Agent`[\s\S]*(?:the )?same read-only/);
 		assert.match(routing, /report (?:the )?fallback/);
+		assert.doesNotMatch(routing, /review lenses? (?:inside|only inside)|review lens routing/i);
 	}
+
+	const core = readFileSync(join(PACKAGE_ROOT, "assets", "orchestrator.md"), "utf8");
+	assert.match(core, /injects the mirrored provider-bundle review execution contract/);
+	assert.match(core, /this package invents no lifecycle instructions/);
 });
 
 test("pi-pretty wrapper uses real package path resolution for pnpm symlink installs", () => {
@@ -1160,9 +1277,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v2.2.0 release package and runtime stop before publication", () => {
+test("v2.4.0 release package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "2.2.0", "the release manifest must remain explicitly pinned to v2.2.0");
+	assert.equal(packageJson.version, "2.4.0", "the release manifest must remain explicitly pinned to v2.4.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
@@ -1192,17 +1309,16 @@ test("bounded review keeps the Judgment Day skill contract at canon metadata ver
 	assert.doesNotMatch(frontmatter, /^  version: "1\.4"$/m);
 });
 
-test("README documents bounded review transactions and the honest installed permission boundary", () => {
+test("README documents dynamic Gentle AI RDD ownership and the installed permission boundary", () => {
 	const readme = readFileSync(join(PACKAGE_ROOT, "README.md"), "utf8");
 	for (const clause of [
-		"New ordinary review uses compact `gentle_review` `start -> finalize -> validate`.",
-		"Native compact gate validation is read-only.",
-		"Release from protected `main` may bypass receipt validation only when the tag targets the current immutable `origin/main` SHA, required CI for that exact SHA is successful, the remote head is rechecked before tag push, and no fresh risk evidence exists; otherwise release fails closed through native receipt validation.",
+		"Gentle AI dynamically supplies runtime-specific RDD instructions",
+		"does not define an RDD lifecycle",
 		"Dangerous-command safety remains independent and authoritative.",
-		"Adversarial review roles (the refuter and the targeted validator) are never Pi-authored",
 		"package-managed isolated installation",
 		"Project and user overrides may shadow a package asset",
 	]) {
-		assert.ok(readme.includes(clause), `README missing review v2 clause: ${clause}`);
+		assert.ok(readme.includes(clause), `README missing dynamic RDD clause: ${clause}`);
 	}
+	assert.doesNotMatch(readme, /New ordinary review uses compact `gentle_review` `start -> finalize -> validate`\./);
 });

package/tests/provider-contract-bundle.test.ts

@@ -35,6 +35,16 @@ function fixtureEntries(): Map<string, Buffer> {
 	return new Map(FIXTURE_PATHS.map((path) => [path, readFileSync(join(FIXTURE_ROOT, path))]));
 }
 
+// Fixture provenance: the real gentle-ai provider contract bundle 1.2.0
+// release archive (contract semver 1.2.0), extracted. Adds `orchestration`
+// to the manifest: gentle-pi#560 / gentle-ai#4056, #4057.
+const FIXTURE_1_2_0_ROOT = join(import.meta.dirname, "fixtures", "provider-contract-bundle", "v1.2.0");
+const FIXTURE_1_2_0_PATHS = [...FIXTURE_PATHS, "orchestration/pi.md"] as const;
+
+function fixture120Entries(): Map<string, Buffer> {
+	return new Map(FIXTURE_1_2_0_PATHS.map((path) => [path, readFileSync(join(FIXTURE_1_2_0_ROOT, path))]));
+}
+
 function sha256Hex(bytes: Buffer): string {
 	return createHash("sha256").update(bytes).digest("hex");
 }
@@ -177,11 +187,25 @@ test("generated baselines project roles, capabilities, and runtime registration
 	assert.equal(capabilities.transport_capability, PROVIDER_TRANSPORT_CAPABILITY);
 	assert.deepEqual(capabilities.mandatory_capabilities, [PROVIDER_TRANSPORT_CAPABILITY]);
 	assert.equal(capabilities.pi_registered, true);
+	assert.deepEqual(capabilities.orchestration, []);
 	// Byte determinism: regenerating from the same bundle is identical.
 	const again = generateProviderContractBaselines(verifyProviderContractBundleTree(FIXTURE_ROOT));
 	assert.deepEqual([...again.entries()], [...baselines.entries()]);
 });
 
+test("generated 1.2.0 baselines record the mirrored orchestration entry", () => {
+	const bundle = verifyProviderContractBundleTree(FIXTURE_1_2_0_ROOT);
+	const baselines = generateProviderContractBaselines(bundle);
+	const capabilities = JSON.parse(baselines.get("provider-capabilities.baseline.json") as string) as { orchestration: { runtime: string; path: string; sha256: string }[] };
+	assert.deepEqual(capabilities.orchestration, [
+		{
+			runtime: PI_RUNTIME_IDENTITY,
+			path: "orchestration/pi.md",
+			sha256: bundle.entrySha256.get("orchestration/pi.md"),
+		},
+	]);
+});
+
 // --- inventory and hash rejections ---------------------------------------------
 
 test("rejects a ninth file in the inventory", () => {
@@ -315,6 +339,58 @@ test("rejects a schema whose $id does not match the manifest result schema id",
 	);
 });
 
+// --- orchestration (contract 1.2.0) -------------------------------------------------
+
+test("verifies the 1.2.0 fixture tree and exposes the mirrored pi orchestration text", () => {
+	const bundle = verifyProviderContractBundleTree(FIXTURE_1_2_0_ROOT);
+	assert.equal(bundle.contractSemver, "1.2.0");
+	assert.deepEqual([bundle.major, bundle.minor, bundle.patch], [1, 2, 0]);
+	assert.equal(bundle.entries.size, 9);
+	assert.deepEqual([...bundle.orchestration.keys()], [PI_RUNTIME_IDENTITY]);
+	const piText = bundle.orchestration.get(PI_RUNTIME_IDENTITY);
+	assert.equal(piText, readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration/pi.md"), "utf8"));
+	assert.equal(bundle.entrySha256.get("orchestration/pi.md"), sha256Hex(readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration/pi.md"))));
+});
+
+test("rejects a 1.2.0 manifest without the required orchestration array", () => {
+	assertRejects(
+		withManifest(fixture120Entries(), (manifest) => {
+			delete manifest.orchestration;
+		}),
+		"manifest.orchestration is required from contract 1.2.0",
+	);
+});
+
+test("rejects a 1.2.0 orchestration entry whose runtime is not registered in manifest.runtimes", () => {
+	assertRejects(
+		withManifest(fixture120Entries(), (manifest) => {
+			const orchestration = manifest.orchestration as { runtime: string; file: { path: string } }[];
+			orchestration[0]!.runtime = "aider";
+			orchestration[0]!.file.path = "orchestration/aider.md";
+		}),
+		'manifest.orchestration[0].runtime "aider" is not registered in manifest.runtimes',
+	);
+});
+
+test("rejects a 1.2.0 orchestration entry whose file bytes do not match its manifest SHA-256", () => {
+	const entries = fixture120Entries();
+	const tampered = Buffer.from(entries.get("orchestration/pi.md") as Buffer);
+	tampered[tampered.length - 2] = 0x20;
+	entries.set("orchestration/pi.md", tampered);
+	assertRejects(entries, "does not match its manifest SHA-256");
+});
+
+test("rejects an orchestration array on a 1.1.0 manifest", () => {
+	assertRejects(
+		withManifest(fixtureEntries(), (manifest) => {
+			manifest.orchestration = [
+				{ runtime: PI_RUNTIME_IDENTITY, file: { path: "orchestration/pi.md", sha256: "0".repeat(64) } },
+			];
+		}),
+		"manifest.orchestration is not part of contract 1.1.0",
+	);
+});
+
 // --- archive safety ------------------------------------------------------------------
 
 test("rejects a tar entry that escapes the bundle root", () => {

package/tests/provider-contract-mirror.test.ts

@@ -27,6 +27,10 @@ const FIXTURE_PATHS = [
 	"vectors/targeted-validator.json",
 ] as const;
 
+// Fixture provenance: the real gentle-ai provider contract bundle 1.2.0
+// release archive, extracted. gentle-pi#560 / gentle-ai#4056, #4057.
+const FIXTURE_1_2_0_ROOT = join(import.meta.dirname, "fixtures", "provider-contract-bundle", "v1.2.0");
+
 interface LockRecord {
 	schema: string;
 	acquisition: string;
@@ -105,6 +109,21 @@ test("mirrors a verified local bundle tree and the offline drift check passes",
 	});
 });
 
+test("mirrors a verified local 1.2.0 bundle tree, including its orchestration entry, and the offline drift check passes", () => {
+	withTemporaryRoot((packageRoot) => {
+		mirrorProviderContractBundle(FIXTURE_1_2_0_ROOT, packageRoot);
+		const lockPath = join(packageRoot, PROVIDER_CONTRACT_MIRROR_ROOT, PROVIDER_CONTRACT_LOCK_FILE);
+		const lock = JSON.parse(readFileSync(lockPath, "utf8")) as LockRecord;
+		assert.equal(lock.contract_semver, "1.2.0");
+		assert.equal(Object.keys(lock.entries).length, 9);
+		assert.ok("orchestration/pi.md" in lock.entries, "the mirrored lock must record orchestration/pi.md");
+		const mirrored = join(packageRoot, PROVIDER_CONTRACT_MIRROR_ROOT, "v1.2.0", "bundle", "orchestration", "pi.md");
+		assert.ok(existsSync(mirrored), "orchestration/pi.md must be mirrored");
+		assert.deepEqual(readFileSync(mirrored), readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration", "pi.md")));
+		assert.deepEqual(checkProviderContractMirror(packageRoot), []);
+	});
+});
+
 test("mirrors a verified local archive and records the archive digest in the lock", () => {
 	withTemporaryRoot((packageRoot) => {
 		const archivePath = join(packageRoot, "gentle-ai-review-provider-contract-1.1.0.tar.gz");