gentle-pi 2.4.0 → 2.6.0

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

@@ -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

@@ -15,7 +15,7 @@ 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";
+import { getPackageAssetOwner, installPackageAssets, installSddAssets, type PackageAssetOwner } from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const MANAGED_EXEMPLAR_FILE = "gentle-ai-explore.md";
@@ -80,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?: {
@@ -99,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);
@@ -218,8 +229,12 @@ test("generated runtime modules and packed-package checks are deterministic", ()
 test("package manifest ships and runs the checked-in package-local Gentle AI installer", () => {
 	const packageJson = readPackageJson();
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
+	const readme = readFileSync(join(PACKAGE_ROOT, "README.md"), "utf8");
 
 	assert.equal(packageJson.scripts?.postinstall, "node scripts/install-gentle-ai.mjs");
+	assert.match(readme, /run `node scripts\/install-gentle-ai\.mjs`/, "missing-binary recovery documentation must use the package postinstall entrypoint");
+	assert.match(readme, /installed `gentle-pi` package directory/, "recovery documentation must name the package working directory");
+	assert.match(readme, /if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before/i, "recovery documentation must prevent the installer skip from repeating");
 	assert.ok(packageJson.files?.includes("scripts/"));
 	assert.match(verifier, /"scripts\/install-gentle-ai\.mjs"/);
 	assert.match(verifier, /"scripts\/gentle-ai-installer\.mjs"/);
@@ -262,20 +277,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v2.6.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v2.8.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\.6\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "2\.8\.0"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:scGoZYnPHh4oCVqlcfQAOSpm22Ii5lmB0kBbiBKvNZk="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:QNdrYDxq\/Bi08o9PCk0jc4r5YObLdFmRCLXjKMqsze8="/);
 	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\.6\.0/);
+	assert.match(verifier, /v2\.8\.0/);
 });
 
 
@@ -458,6 +473,222 @@ test("packaged agents declare only tool names a Pi child session can resolve", (
 	}
 });
 
+function withIsolatedAssetHome(run: (agentHome: string) => void): void {
+	const temporary = mkdtempSync(join(tmpdir(), "gentle-asset-owners-"));
+	const previous = process.env.GENTLE_PI_AGENT_HOME;
+	try {
+		process.env.GENTLE_PI_AGENT_HOME = temporary;
+		run(temporary);
+	} finally {
+		if (previous === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previous;
+		rmSync(temporary, { recursive: true, force: true });
+	}
+}
+
+function installedAssetManifest(agentHome: string): ManagedAssetsManifest {
+	return JSON.parse(readFileSync(join(agentHome, "gentle-ai", "managed-assets.json"), "utf8"));
+}
+
+test("selective delegation installation owns only generic agents", () => {
+	withIsolatedAssetHome((agentHome) => {
+		const result = installPackageAssets(agentHome, false, ["delegation"]);
+		assert.deepEqual(Object.keys(installedAssetManifest(agentHome).assets).sort(), [
+			"agents/gentle-ai-explore.md",
+			"agents/gentle-ai-verify.md",
+			"agents/gentle-ai-worker.md",
+		]);
+		assert.deepEqual(result, { agents: 3, chains: 0, support: 0, skipped: 0 });
+		assert.deepEqual(readdirSync(join(agentHome, "agents")).sort(), [
+			"gentle-ai-explore.md", "gentle-ai-verify.md", "gentle-ai-worker.md",
+		]);
+		assert.equal(existsSync(join(agentHome, "chains")), false);
+		assert.equal(existsSync(join(agentHome, "gentle-ai", "support")), false);
+	});
+});
+
+test("selective installation retires only assets belonging to the selected owner", () => {
+	withIsolatedAssetHome((agentHome) => {
+		installSddAssets(agentHome, false);
+		const manifestPath = join(agentHome, "gentle-ai", "managed-assets.json");
+		const manifest = installedAssetManifest(agentHome);
+		for (const name of RETIRED_ADVERSARIAL_AGENTS) {
+			writeFileSync(join(agentHome, "agents", name), "Previously managed review agent\n");
+			manifest.assets[`agents/${name}`] = sha256("Previously managed review agent\n");
+		}
+		writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+		for (const owner of ["delegation", "sdd"] as const) {
+			installPackageAssets(agentHome, true, [owner]);
+			assert.deepEqual(installedAssetManifest(agentHome), manifest);
+			for (const name of RETIRED_ADVERSARIAL_AGENTS) {
+				assert.equal(readFileSync(join(agentHome, "agents", name), "utf8"), "Previously managed review agent\n");
+			}
+		}
+		writeFileSync(join(agentHome, "agents", "review-validator.md"), "User-modified retired agent\n");
+		installPackageAssets(agentHome, false, ["review"]);
+		assert.equal(existsSync(join(agentHome, "agents", "review-refuter.md")), false);
+		assert.equal(readFileSync(join(agentHome, "agents", "review-validator.md"), "utf8"), "User-modified retired agent\n");
+		for (const name of RETIRED_ADVERSARIAL_AGENTS) {
+			assert.equal(installedAssetManifest(agentHome).assets[`agents/${name}`], undefined);
+		}
+	});
+});
+
+const EXPECTED_OWNER_ASSETS: Record<PackageAssetOwner, readonly string[]> = {
+	delegation: [
+		"agents/gentle-ai-explore.md", "agents/gentle-ai-verify.md", "agents/gentle-ai-worker.md",
+	],
+	review: [
+		"agents/jd-fix-agent.md", "agents/jd-judge-a.md", "agents/jd-judge-b.md",
+		"agents/review-readability.md", "agents/review-reliability.md",
+		"agents/review-resilience.md", "agents/review-risk.md", "chains/4r-review.chain.md",
+	],
+	sdd: [
+		"agents/sdd-apply.md", "agents/sdd-archive.md", "agents/sdd-design.md",
+		"agents/sdd-explore.md", "agents/sdd-init.md", "agents/sdd-onboard.md",
+		"agents/sdd-proposal.md", "agents/sdd-remediate.md", "agents/sdd-research.md", "agents/sdd-spec.md",
+		"agents/sdd-status.md", "agents/sdd-sync.md", "agents/sdd-tasks.md", "agents/sdd-verify.md",
+		"chains/sdd-full.chain.md", "chains/sdd-plan.chain.md", "chains/sdd-verify.chain.md",
+		"gentle-ai/support/sdd-status-contract.md", "gentle-ai/support/strict-tdd-verify.md",
+		"gentle-ai/support/strict-tdd.md",
+	],
+};
+
+function assetFileKeys(root: string, prefix = ""): string[] {
+	if (!existsSync(root)) return [];
+	return readdirSync(root, { withFileTypes: true }).flatMap(entry => {
+		const key = `${prefix}${entry.name}`;
+		return entry.isDirectory() ? assetFileKeys(join(root, entry.name), `${key}/`) : [key];
+	}).sort();
+}
+
+for (const owner of Object.keys(EXPECTED_OWNER_ASSETS) as PackageAssetOwner[]) {
+	test(`selective ${owner} installation covers its catalog without cross-owner files`, () => {
+		withIsolatedAssetHome((agentHome) => {
+			const expected = [...EXPECTED_OWNER_ASSETS[owner]].sort();
+			installPackageAssets(agentHome, false, [owner]);
+			assert.deepEqual(Object.keys(installedAssetManifest(agentHome).assets).sort(), expected);
+			assert.deepEqual(assetFileKeys(agentHome), [...expected, "gentle-ai/managed-assets.json"].sort());
+			for (const key of expected) {
+				assert.equal(getPackageAssetOwner(key), owner);
+				const source = join(PACKAGE_ROOT, "assets", key.replace(/^gentle-ai\//, ""));
+				assert.equal(readFileSync(join(agentHome, key), "utf8"), readFileSync(source, "utf8"));
+			}
+			const counts = installPackageAssets(agentHome, false, [owner, owner]);
+			assert.deepEqual(counts, { agents: 0, chains: 0, support: 0, skipped: expected.length });
+		});
+	});
+}
+
+test("legacy all-assets installation covers every packaged file with explicit ownership", () => {
+	const packaged = ["agents", "chains", "support"].flatMap(group =>
+		assetFileKeys(join(PACKAGE_ROOT, "assets", group), group === "support" ? "gentle-ai/support/" : `${group}/`),
+	).sort();
+	assert.deepEqual(packaged, Object.values(EXPECTED_OWNER_ASSETS).flat().sort());
+	for (const key of packaged) assert.notEqual(getPackageAssetOwner(key), undefined, key);
+	for (const key of ["agents/sdd-new.md", "gentle-ai/support/new.md", "toString", "__proto__"]) {
+		assert.equal(getPackageAssetOwner(key), undefined, "unknown assets must not default to SDD");
+	}
+	withIsolatedAssetHome((agentHome) => {
+		assert.deepEqual(installSddAssets(agentHome, false), { agents: 24, chains: 4, support: 3, skipped: 0 });
+		assert.deepEqual(Object.keys(installedAssetManifest(agentHome).assets).sort(), packaged);
+		assert.deepEqual(installSddAssets(agentHome, false), { agents: 0, chains: 0, support: 0, skipped: 31 });
+		assert.deepEqual(installSddAssets(agentHome, true), { agents: 24, chains: 4, support: 3, skipped: 0 });
+	});
+});
+
+test("selective refresh preserves unselected ownership and selected user changes after an all-assets install", () => {
+	withIsolatedAssetHome((agentHome) => {
+		installSddAssets(agentHome, false);
+		const manifest = installedAssetManifest(agentHome);
+		const selectedUserKey = "agents/gentle-ai-explore.md";
+		const unselectedUserKey = "agents/sdd-apply.md";
+		for (const key of [selectedUserKey, unselectedUserKey, "agents/custom.md"]) {
+			writeFileSync(join(agentHome, key), "User-authored instructions\n");
+		}
+		const before = new Map(assetFileKeys(agentHome).map(key => [key, readFileSync(join(agentHome, key), "utf8")]));
+		assert.deepEqual(installPackageAssets(agentHome, true, ["delegation"]), { agents: 2, chains: 0, support: 0, skipped: 1 });
+		delete manifest.assets[selectedUserKey];
+		assert.deepEqual(installedAssetManifest(agentHome), manifest);
+		for (const [key, content] of before) {
+			if (key !== "gentle-ai/managed-assets.json") assert.equal(readFileSync(join(agentHome, key), "utf8"), content, key);
+		}
+		const manifestBytes = readFileSync(join(agentHome, "gentle-ai", "managed-assets.json"), "utf8");
+		assert.deepEqual(installPackageAssets(agentHome, true, []), { agents: 0, chains: 0, support: 0, skipped: 0 });
+		assert.equal(readFileSync(join(agentHome, "gentle-ai", "managed-assets.json"), "utf8"), manifestBytes);
+	});
+});
+
+test("selective review migration adopts only untouched legacy copies and preserves routing", () => {
+	for (const edited of [false, true]) {
+		withIsolatedAssetHome((agentHome) => {
+			mkdirSync(join(agentHome, "agents"));
+			const legacy = readFileSync(V014_REVIEW_RISK_FIXTURE, "utf8")
+				.replace("name: review-risk\n", "name: review-risk\nmodel: custom/model\nthinking: high\n")
+				+ (edited ? "\nUser review restrictions.\n" : "");
+			const target = join(agentHome, "agents", REVIEW_RISK_FILE);
+			writeFileSync(target, legacy);
+			installPackageAssets(agentHome, true, ["delegation"]);
+			assert.equal(readFileSync(target, "utf8"), legacy);
+			assert.equal(installedAssetManifest(agentHome).assets["agents/review-risk.md"], undefined);
+			const result = installPackageAssets(agentHome, true, ["review"]);
+			const actual = readFileSync(target, "utf8");
+			const manifest = installedAssetManifest(agentHome);
+			assert.equal(result.skipped, edited ? 1 : 0);
+			if (edited) {
+				assert.equal(actual, legacy);
+				assert.equal(manifest.assets["agents/review-risk.md"], undefined);
+			} else {
+				assert.notEqual(actual, legacy);
+				assert.match(actual, /model: custom\/model\nthinking: high/);
+				assert.equal(manifest.assets["agents/review-risk.md"], sha256(actual));
+			}
+			assert.equal(existsSync(join(agentHome, "agents", "sdd-apply.md")), false);
+			assert.equal(existsSync(join(agentHome, "gentle-ai", "support")), false);
+		});
+	}
+});
+
+test("unowned legacy research migrates by exact normalized hash, preserving routing and user edits", () => {
+	const packaged = readFileSync(join(PACKAGE_ROOT, "assets", "agents", "sdd-research.md"), "utf8");
+	const oldAdmission = "- Evidence grants for this runtime are `documentation=[]; open-web=[]`. Never infer evidence capability from bash, persistence tools, or any inherited tool; persistence tools are not evidence grants. Unsupported or undeclared classes deny admission and emit no claims.\n- Because this runtime declares no evidence grants, retain the selected request, persist a `blocked` outcome with no claims, and stop.\n";
+	const legacy = packaged
+		.replace(/## Parent Preflight Transport\n[\s\S]*?(?=## Skill Resolution Contract)/, "")
+		.replace(/## Bounded artifact handoff\n[\s\S]*?(?=## Memory Contract)/, "")
+		.replace(/  - fetch_content\n  - web_search\n  - source_check\n  - get_search_content\n/, "")
+		.replace(/- Use the injected `## SDD Research Capabilities`[\s\S]*?(?=- Admission denial)/, oldAdmission)
+		.replace(/Use `done` only when all selected questions[\s\S]*?product decisions remain separately confirmed by the parent\./i, "For this runtime the outcome is `blocked` with an admission denial and no claims.");
+	const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "assets", "migrations", "managed-assets-v2.5.0.json"), "utf8"));
+	assert.equal(sha256(legacy), manifest.assets["agents/sdd-research.md"], "fixture reconstruction must match observed old package bytes");
+	const temporary = mkdtempSync(join(tmpdir(), "gentle-research-migration-"));
+	const previous = process.env.GENTLE_PI_AGENT_HOME;
+	try {
+		for (const edited of [false, true]) {
+			const agentHome = join(temporary, edited ? "edited" : "legacy");
+			process.env.GENTLE_PI_AGENT_HOME = agentHome;
+			mkdirSync(join(agentHome, "agents"), { recursive: true });
+			const target = join(agentHome, "agents", "sdd-research.md");
+			const routed = legacy.replace("name: sdd-research\n", "name: sdd-research\nmodel: custom/model\nthinking: high\n") + (edited ? "\nUser research restrictions.\n" : "");
+			writeFileSync(target, routed);
+			installSddAssets(temporary, true);
+			const actual = readFileSync(target, "utf8");
+			if (edited) assert.equal(actual, routed);
+			else {
+				assert.match(actual, /  - fetch_content/);
+				assert.match(actual, /model: custom\/model\nthinking: high/);
+				const ownership = JSON.parse(readFileSync(join(agentHome, "gentle-ai", "managed-assets.json"), "utf8"));
+				assert.equal(ownership.assets["agents/sdd-research.md"], sha256(actual));
+				installSddAssets(temporary, true);
+				assert.equal(readFileSync(target, "utf8"), actual, "subsequent refresh keeps adopted model routing");
+			}
+		}
+	} finally {
+		if (previous === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previous;
+		rmSync(temporary, { recursive: true, force: true });
+	}
+});
+
 test("the retired Pi adversarial role agents are not packaged", () => {
 	// gentle-pi#311 P5: the refuter and targeted validator verdicts execute
 	// through Go-owned pi processes via provider-rendered self-contained
@@ -1277,9 +1508,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v2.4.0 release package and runtime stop before publication", () => {
+test("v2.6.0 release package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "2.4.0", "the release manifest must remain explicitly pinned to v2.4.0");
+	assert.equal(packageJson.version, "2.6.0", "the release manifest must remain explicitly pinned to v2.6.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",
@@ -1322,3 +1553,8 @@ test("README documents dynamic Gentle AI RDD ownership and the installed permiss
 	}
 	assert.doesNotMatch(readme, /New ordinary review uses compact `gentle_review` `start -> finalize -> validate`\./);
 });
+
+
+test("package verification explicitly requires the managed remediation actor", () => {
+	assert.match(readFileSync(join(PACKAGE_ROOT, "scripts/verify-package-files.mjs"), "utf8"), /assets\/agents\/sdd-remediate\.md/);
+});

package/tests/profiles-orchestrator.test.ts

@@ -0,0 +1,208 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+	applyOrchestratorSettings,
+	parseOrchestratorModelRef,
+	readOrchestratorSettings,
+	restoreOrchestratorSettings,
+} from "../lib/profiles-orchestrator.ts";
+
+function fixture(t: test.TestContext) {
+	const root = mkdtempSync(join(tmpdir(), "gentle-pi-orchestrator-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	return { root, settingsPath: join(root, "settings.json") };
+}
+
+test("orchestrator model refs split only on a real provider boundary", () => {
+	assert.deepEqual(parseOrchestratorModelRef("nan/glm5.3"), {
+		provider: "nan",
+		model: "glm5.3",
+	});
+	assert.deepEqual(parseOrchestratorModelRef("  openai-codex/gpt-6-astra  "), {
+		provider: "openai-codex",
+		model: "gpt-6-astra",
+	});
+	// A nested slash stays with the model half.
+	assert.deepEqual(parseOrchestratorModelRef("nan/qwen3.8/flash"), {
+		provider: "nan",
+		model: "qwen3.8/flash",
+	});
+	for (const value of ["glm5.3", "/glm5.3", "nan/", "nan", "", "   ", 42, undefined, null]) {
+		assert.equal(parseOrchestratorModelRef(value), undefined, `rejects ${JSON.stringify(value)}`);
+	}
+});
+
+test("reading the orchestrator distinguishes missing, unreadable, unset and set", (t) => {
+	const { settingsPath } = fixture(t);
+	assert.deepEqual(readOrchestratorSettings(settingsPath), { status: "missing" });
+
+	writeFileSync(settingsPath, "{ not json");
+	assert.equal(readOrchestratorSettings(settingsPath).status, "invalid");
+
+	writeFileSync(settingsPath, JSON.stringify(["not", "an", "object"]));
+	assert.equal(readOrchestratorSettings(settingsPath).status, "invalid");
+
+	writeFileSync(settingsPath, JSON.stringify({ theme: "Gentleman-Cute" }));
+	const unset = readOrchestratorSettings(settingsPath);
+	assert.equal(unset.status, "valid");
+	assert.equal(unset.status === "valid" ? unset.entry : undefined, undefined);
+
+	writeFileSync(
+		settingsPath,
+		JSON.stringify({
+			defaultProvider: "nan",
+			defaultModel: "glm5.3",
+			defaultThinkingLevel: "high",
+		}),
+	);
+	const set = readOrchestratorSettings(settingsPath);
+	assert.deepEqual(set.status === "valid" ? set.entry : undefined, {
+		model: "nan/glm5.3",
+		thinking: "high",
+	});
+
+	// A half-written pair is "unset", never a fabricated provider or model.
+	writeFileSync(settingsPath, JSON.stringify({ defaultProvider: "nan" }));
+	const half = readOrchestratorSettings(settingsPath);
+	assert.equal(half.status, "valid");
+	assert.equal(half.status === "valid" ? half.entry : undefined, undefined);
+});
+
+test("an orchestrator entry without a model never touches the settings file", (t) => {
+	const { root, settingsPath } = fixture(t);
+	const before = '{\n  "packages": [\n    "npm:pi-mcp-adapter"\n  ],\n  "theme": "Gentleman-Cute"\n}\n';
+	writeFileSync(settingsPath, before);
+	assert.deepEqual(applyOrchestratorSettings(settingsPath, { thinking: "high" }), {
+		status: "unchanged",
+	});
+	assert.equal(readFileSync(settingsPath, "utf8"), before);
+
+	// Also true when there is no file at all: nothing to write, nothing created.
+	const absent = join(root, "absent-settings.json");
+	assert.deepEqual(applyOrchestratorSettings(absent, {}), { status: "unchanged" });
+	assert.equal(existsSync(absent), false);
+});
+
+test("applying the orchestrator preserves every unrelated settings key", (t) => {
+	const { settingsPath } = fixture(t);
+	const before =
+		JSON.stringify(
+			{
+				packages: ["npm:pi-mcp-adapter", "some-package"],
+				theme: "Gentleman-Cute",
+				tuiMode: "fullscreen",
+				telemetry: { enabled: true },
+				defaultProvider: "nan",
+				defaultModel: "deepseek-v4-flash",
+				defaultThinkingLevel: "high",
+				images: { autoResize: true },
+			},
+			null,
+			2,
+		) + "\n";
+	writeFileSync(settingsPath, before);
+
+	const result = applyOrchestratorSettings(settingsPath, {
+		model: "nan/glm5.3",
+		thinking: "max",
+	});
+	assert.equal(result.status, "written");
+	assert.equal(result.status === "written" ? result.previous : undefined, before);
+
+	const after = JSON.parse(readFileSync(settingsPath, "utf8"));
+	assert.equal(after.defaultProvider, "nan");
+	assert.equal(after.defaultModel, "glm5.3");
+	assert.equal(after.defaultThinkingLevel, "max");
+	assert.deepEqual(after.packages, ["npm:pi-mcp-adapter", "some-package"]);
+	assert.equal(after.theme, "Gentleman-Cute");
+	assert.equal(after.tuiMode, "fullscreen");
+	assert.deepEqual(after.telemetry, { enabled: true });
+	assert.deepEqual(after.images, { autoResize: true });
+	assert.equal(readFileSync(settingsPath, "utf8").endsWith("\n"), true);
+});
+
+test("a missing settings file is created with only the orchestrator keys", (t) => {
+	const { settingsPath } = fixture(t);
+	const result = applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" });
+	assert.equal(result.status, "written");
+	assert.equal(result.status === "written" ? result.previous : "sentinel", undefined);
+	assert.deepEqual(JSON.parse(readFileSync(settingsPath, "utf8")), {
+		defaultProvider: "nan",
+		defaultModel: "glm5.3",
+	});
+});
+
+test("an orchestrator entry without thinking clears a stale thinking level", (t) => {
+	const { settingsPath } = fixture(t);
+	writeFileSync(
+		settingsPath,
+		JSON.stringify({
+			defaultProvider: "nan",
+			defaultModel: "glm5.3",
+			defaultThinkingLevel: "high",
+		}),
+	);
+	const result = applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3-flash" });
+	assert.equal(result.status, "written");
+	const after = JSON.parse(readFileSync(settingsPath, "utf8"));
+	assert.equal(after.defaultModel, "glm5.3-flash");
+	assert.equal("defaultThinkingLevel" in after, false);
+});
+
+test("re-applying the same selection is a no-op", (t) => {
+	const { settingsPath } = fixture(t);
+	assert.equal(applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" }).status, "written");
+	const bytes = readFileSync(settingsPath, "utf8");
+	assert.deepEqual(applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" }), {
+		status: "unchanged",
+	});
+	assert.equal(readFileSync(settingsPath, "utf8"), bytes);
+});
+
+test("an unusable target is refused instead of being overwritten", (t) => {
+	const { settingsPath } = fixture(t);
+	const before = "{ this is not json\n";
+	writeFileSync(settingsPath, before);
+	const broken = applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" });
+	assert.equal(broken.status, "invalid");
+	assert.equal(readFileSync(settingsPath, "utf8"), before);
+
+	writeFileSync(settingsPath, "[]");
+	const notObject = applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" });
+	assert.equal(notObject.status, "invalid");
+	assert.equal(readFileSync(settingsPath, "utf8"), "[]");
+
+	// A model id that is not a provider/model pair is refused for the same reason:
+	// there is no provider to write, and guessing one would corrupt the selection.
+	writeFileSync(settingsPath, JSON.stringify({ theme: "Gentleman-Cute" }));
+	const noProvider = applyOrchestratorSettings(settingsPath, { model: "glm5.3" });
+	assert.equal(noProvider.status, "invalid");
+	assert.deepEqual(JSON.parse(readFileSync(settingsPath, "utf8")), { theme: "Gentleman-Cute" });
+});
+
+test("restoring returns the previous bytes, or removes a file the write created", (t) => {
+	const { root, settingsPath } = fixture(t);
+	const before = '{\n  "theme": "Gentleman-Cute"\n}\n';
+	writeFileSync(settingsPath, before);
+	const written = applyOrchestratorSettings(settingsPath, { model: "nan/glm5.3" });
+	assert.equal(written.status, "written");
+	restoreOrchestratorSettings(
+		settingsPath,
+		written.status === "written" ? written.previous : undefined,
+	);
+	assert.equal(readFileSync(settingsPath, "utf8"), before);
+
+	// A file the write created restores by disappearing, not by holding an empty object.
+	const createdPath = join(root, "created-settings.json");
+	const created = applyOrchestratorSettings(createdPath, { model: "nan/glm5.3" });
+	assert.equal(created.status, "written");
+	assert.equal(existsSync(createdPath), true);
+	restoreOrchestratorSettings(
+		createdPath,
+		created.status === "written" ? created.previous : undefined,
+	);
+	assert.equal(existsSync(createdPath), false);
+});