gentle-pi 2.3.0 → 2.5.0

package/tests/orchestrator-budget.test.ts

@@ -114,8 +114,21 @@ function measureOrchestratorPromptBytes(assetsDir: string): number {
 // 2.2 — Byte budget (Spec: Always-On Injection Byte Budget)
 // ---------------------------------------------------------------------------
 
+// gentle-pi#661: `renderOrchestratorPrompt`/`getOrchestratorPrompt` default
+// `rddStatusLine` to the "unknown (native status unavailable)" line -- the
+// longest of the three renderable RDD status lines -- precisely so that a
+// no-argument call renders the worst case this budget measures, not a
+// smaller placeholder that production would later exceed. Assert that line
+// is actually present so a future default change cannot silently start
+// measuring a shorter render again.
+const RDD_WORST_CASE_LINE = "Receipt-driven development: unknown (native status unavailable)";
+
 test("getOrchestratorPrompt return value stays within the canonical 8,192 B budget at a short assets root", () => {
 	const rendered = __testing.renderOrchestratorPrompt(representativeProductionAssetsDir);
+	assert.ok(
+		rendered.includes(RDD_WORST_CASE_LINE),
+		"the default render must include the worst-case RDD status line to measure the real production budget",
+	);
 	const bytes = Buffer.byteLength(rendered, "utf8");
 	assert.ok(
 		bytes <= BUDGET_BYTES,
@@ -125,6 +138,10 @@ test("getOrchestratorPrompt return value stays within the canonical 8,192 B budg
 
 test(`getOrchestratorPrompt keeps a controlled long (>= ${MIN_CONTROLLED_LONG_ASSETS_ROOT_CHARS} char) assets root within the canonical budget`, () => {
 	const rendered = __testing.renderOrchestratorPrompt(controlledLongAssetsDir);
+	assert.ok(
+		rendered.includes(RDD_WORST_CASE_LINE),
+		"the default render must include the worst-case RDD status line to measure the real production budget",
+	);
 	const bytes = measureOrchestratorPromptBytes(controlledLongAssetsDir);
 	assert.equal(bytes, Buffer.byteLength(rendered, "utf8"), "child-process and direct render byte counts must match");
 	assert.ok(
@@ -347,8 +364,8 @@ test("core-alone: load-bearing direct-delegation tokens remain without lazy unio
 
 test("core-alone: dynamic Gentle AI ownership replaces package lifecycle instructions", () => {
 	const core = readRealAsset("orchestrator.md");
-	assert.match(core, /dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition/);
-	assert.match(core, /if absent or unsupported, this package does not invent or fall back/);
+	assert.match(core, /injects the mirrored provider-bundle review execution contract into this session's system prompt at start/);
+	assert.match(core, /Absent that mirrored contract, this package invents no lifecycle instructions/);
 	assert.doesNotMatch(core, /start -> finalize -> validate/i);
 	assert.doesNotMatch(core, /receipt validation/i);
 });
@@ -420,3 +437,55 @@ test("getOrchestratorPrompt memoizes the return across calls", () => {
 	const second = __testing.getOrchestratorPrompt();
 	assert.equal(second, first, "second call must return the memoized string");
 });
+
+// ---------------------------------------------------------------------------
+// gentle-pi#661 follow-up: byte-budget compression must not turn a pointer
+// into an opaque "Detail: `file.md`" -- each pointer line must still name
+// the lazy-loaded material it points to, in the shortest form that still
+// says what is over there.
+// ---------------------------------------------------------------------------
+
+test("every compressed lazy-file pointer in the core still names the material it points to", () => {
+	const core = readFileSync(join(REAL_ASSETS_DIR, "orchestrator.md"), "utf8");
+	// One-sentence "<named material>: `file.md`." pointers, compressed for the
+	// byte budget -- each must keep naming what is over there, not collapse
+	// to an opaque "Detail: `file.md`.".
+	const namedPointers: ReadonlyArray<{ file: string; mustName: readonly string[] }> = [
+		{
+			file: "orchestrator-delegation.md",
+			mustName: ["Per-action table", "Work Routing Ladder", "Canonical Workflows", "blocking-prompt relays"],
+		},
+		{
+			file: "orchestrator-memory.md",
+			mustName: ["Phase table", "artifact keys"],
+		},
+		{
+			file: "orchestrator-skills.md",
+			mustName: ["Discovery order", "intent hints"],
+		},
+	];
+	for (const { file, mustName } of namedPointers) {
+		// The pointer sentence: from the previous sentence boundary up to and
+		// including the backtick-quoted filename. `orchestrator-delegation.md`
+		// is referenced more than once in the core (a language-boundary pointer
+		// earlier, this compressed per-action pointer later) -- take the LAST
+		// occurrence, which is the one under test here.
+		const fileToken = `\`${file}\``;
+		const fileIndex = core.lastIndexOf(fileToken);
+		assert.ok(fileIndex >= 0, `core is missing a pointer to ${file}`);
+		const sentenceStart = core.lastIndexOf(".", fileIndex);
+		const pointerSentence = core.slice(sentenceStart + 1, fileIndex + fileToken.length);
+		for (const name of mustName) {
+			assert.ok(
+				pointerSentence.includes(name),
+				`the pointer to ${file} must name "${name}", got: ${JSON.stringify(pointerSentence.trim())}`,
+			);
+		}
+	}
+	// The SDD workflow pointer was never compressed to a bare filename; its
+	// surrounding paragraphs already name the material at length.
+	assert.match(
+		core,
+		/SDD phases, native dispatcher rules, status contract, preflight\/init guards, artifact-store policy, execution mode, Strict TDD forwarding, phase result contract, and review workload guard/,
+	);
+});

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

@@ -6,7 +6,7 @@ import test from "node:test";
 const ROOT = join(import.meta.dirname, "..");
 const ASSETS = join(ROOT, "assets");
 const BOUNDARY =
-	"Gentle AI dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition. Follow only those exact native instructions; if absent or unsupported, this package does not invent or fall back.";
+	"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");
@@ -60,6 +60,15 @@ test("rendered parent prompt keeps the RDD boundary while omitting lifecycle mir
 	for (const marker of ["Authority-First Terminal Procedure", "reconcile-terminal-mirrors", "next_transition"]) {
 		assert.ok(!rendered.includes(marker), `rendered parent prompt leaked: ${marker}`);
 	}
+	// gentle-pi#661: getOrchestratorPrompt()'s no-argument default renders the
+	// "unknown (native status unavailable)" RDD status line -- the longest of
+	// the three renderable forms -- so this IS the worst-case render the 8 KiB
+	// budget below must cover, not a smaller placeholder production later
+	// exceeds.
+	assert.ok(
+		rendered.includes("Receipt-driven development: unknown (native status unavailable)"),
+		"the default render must include the worst-case RDD status line",
+	);
 	assert.ok(Buffer.byteLength(rendered, "utf8") <= 8192, "the rendered parent prompt must stay below the reduced 8 KiB budget");
 });
 

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)));
@@ -79,6 +80,8 @@ interface PackageJson {
 	files?: string[];
 	scripts?: Record<string, string>;
 	dependencies?: Record<string, string>;
+	peerDependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
 	bundledDependencies?: string[];
 	bundleDependencies?: string[];
 	repository?: {
@@ -98,6 +101,15 @@ function readPackageJson(): PackageJson {
 	}
 }
 
+test("package declares the tested Pi minimum required for agent_settled", () => {
+	const manifest = readPackageJson();
+	assert.equal(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"], ">=0.85.1");
+	assert.equal(manifest.devDependencies?.["@earendil-works/pi-coding-agent"], "0.85.1");
+	const readme = readFileSync(join(PACKAGE_ROOT, "README.md"), "utf8");
+	assert.match(readme, /Pi 0\.85\.1 or newer/);
+	assert.match(readme, /agent_settled/);
+});
+
 test("package manifest has no obsolete native activation build surface", () => {
 	const packageJson = readPackageJson();
 	const manifest = JSON.stringify(packageJson);
@@ -261,20 +273,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v2.5.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v2.7.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\.5\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "2\.7\.0"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0nvTLJFAf9ruBDwTvi\+aDrWt\/dt\/GKvUP2cFVB6c2DI="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:SE4KCLo3y1qWaTq\+7HJKZ1DkAAAl\+w\+82YY0\+qQkFwM="/);
 	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\.5\.0/);
+	assert.match(verifier, /v2\.7\.0/);
 });
 
 
@@ -895,6 +907,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");
@@ -1055,6 +1083,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 = {
@@ -1146,8 +1271,8 @@ test("orchestrator routes generic roles without static RDD lens routing", () =>
 	}
 
 	const core = readFileSync(join(PACKAGE_ROOT, "assets", "orchestrator.md"), "utf8");
-	assert.match(core, /Gentle AI dynamically supplies runtime-specific RDD instructions/);
-	assert.match(core, /this package does not invent or fall back/);
+	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", () => {
@@ -1163,9 +1288,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v2.3.0 release package and runtime stop before publication", () => {
+test("v2.5.0 release package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "2.3.0", "the release manifest must remain explicitly pinned to v2.3.0");
+	assert.equal(packageJson.version, "2.5.0", "the release manifest must remain explicitly pinned to v2.5.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",

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");