gentle-pi 4.1.0 → 4.3.0

package/tests/package-manifest.test.ts

@@ -133,13 +133,13 @@ test("public docs and metadata advertise ODD and review without retired phase wo
 
 test("technical reference declares the tested Pi minimum required for agent_settled", () => {
 	const manifest = readPackageJson();
-	assert.equal(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"], ">=0.99.1");
-	assert.equal(manifest.devDependencies?.["@earendil-works/pi-coding-agent"], ">=1.0.0");
+	assert.equal(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"], ">=1.2.0");
+	assert.equal(manifest.devDependencies?.["@earendil-works/pi-coding-agent"], ">=1.2.0");
 	assert.equal(manifest.peerDependenciesMeta?.["@earendil-works/pi-coding-agent"]?.optional, true);
 	assert.equal(manifest.engines?.node, ">=22.19.0");
 	for (const path of ["docs/readme-reference.md", "docs/gentle-shell.md"]) {
 		const source = readFileSync(join(PACKAGE_ROOT, path), "utf8");
-		assert.match(source, /Pi 0\.99\.1 or newer/, path);
+		assert.match(source, /Pi 1\.2\.0 or newer/, path);
 		assert.match(source, /open `>=1\.0\.0` development range/, path);
 		assert.doesNotMatch(source, /development tests pin Pi/, path);
 		// Docs name exactly the audited Vim editor releases, never a future one.
@@ -162,7 +162,7 @@ test("packed runtime uses optional Pi host peers with one open development range
 	// one exact release shared by every Pi host package.
 	const installed = new Set<string>();
 	for (const name of ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui"]) {
-		assert.equal(manifest.devDependencies?.[name], ">=1.0.0", name);
+		assert.equal(manifest.devDependencies?.[name], ">=1.2.0", name);
 		const metadata = JSON.parse(readFileSync(join(PACKAGE_ROOT, "node_modules", name, "package.json"), "utf8")) as { name: string; version: string };
 		assert.equal(metadata.name, name);
 		installed.add(metadata.version);
@@ -232,7 +232,7 @@ test("package verification excludes the retired init extension while retaining O
 	assert.equal(existsSync(join(PACKAGE_ROOT, "extensions", "sdd-init.ts")), false);
 	assert.doesNotMatch(verifier, /^\s*"extensions\/sdd-init\.ts",?$/m);
 	assert.match(verifier, /existsSync\(join\(root, "extensions\/sdd-init\.ts"\)\)/);
-	for (const resource of ["extensions/gentle-ai.ts", "extensions/skill-registry.ts", "assets/orchestrator.md", "assets/orchestrator-delegation.md", "assets/agents/gentle-ai-worker.md", "assets/agents/review-risk.md", "assets/chains/4r-review.chain.md"]) {
+	for (const resource of ["extensions/gentle-ai.ts", "extensions/skill-registry.ts", "assets/orchestrator.md", "assets/orchestrator-delegation.md", "assets/orchestrator-delegation-reference.md", "assets/agents/gentle-ai-worker.md", "assets/agents/review-risk.md", "assets/chains/4r-review.chain.md"]) {
 		assert.ok(verifier.includes(`"${resource}"`), `${resource} must remain required`);
 	}
 });
@@ -431,20 +431,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v4.1.1 runtime pin", () => {
+test("package verification binds the published Gentle AI v4.2.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 = "4\.1\.1"/);
+	assert.match(installer, /INSTALLER_VERSION = "4\.2\.0"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:\+WmZ2IvIOiJ8qtHa7wsjnYKNasem\+PByeOZ6HIjoAL8="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:J8EluS7QrfM\+m3vmQlF26B\/shZRjD6rBfsKtrABL5mc="/);
 	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, /v4\.1\.1/);
+	assert.match(verifier, /v4\.2\.0/);
 });
 
 
@@ -1722,27 +1722,29 @@ test("normal and forced installation copy generic agents with complete role cont
 });
 
 test("bounded implementation routing resolves the explicit canonical fallback reference", () => {
-	const routing = readFileSync(
-		join(PACKAGE_ROOT, "assets", "orchestrator-delegation.md"),
-		"utf8",
-	);
-	const reference = "For bounded writes, follow the canonical Writer rule under Mandatory Delegation Triggers.";
+	// S11 T2: the Delegation Triggers live in the delegation card and the Work Routing Ladder (with its
+	// Simple Delegation pointer back to them) in the reference, so the pointer resolves across both files.
+	const routing = ["orchestrator-delegation.md", "orchestrator-delegation-reference.md"]
+		.map((file) => readFileSync(join(PACKAGE_ROOT, "assets", file), "utf8"))
+		.join("\n\n");
+	// S9 canon change (gentle-ai 87a3b2eb): the canonical heading is "Delegation Triggers" (no "Mandatory").
+	const reference = "For bounded writes, follow the canonical Writer rule under Delegation Triggers.";
 	const resolveSimpleDelegation = (source: string): string => {
 		const simpleDelegation = readMarkdownSection(source, "2. Simple Delegation");
 		assert.ok(simpleDelegation.split("\n").includes(reference), "Simple Delegation must name the exact canonical Writer rule");
-		const canonical = readMarkdownSection(source, "Mandatory Delegation Triggers");
+		const canonical = readMarkdownSection(source, "Delegation Triggers");
 		assertWorkerFallbackRouting(canonical, "resolved Simple Delegation");
 		return canonical;
 	};
-	const mandatoryDelegation = readMarkdownSection(routing, "Mandatory Delegation Triggers");
+	const delegationTriggers = readMarkdownSection(routing, "Delegation Triggers");
 
 	assertWorkerFallbackRouting(resolveSimpleDelegation(routing), "Simple Delegation");
-	assertWorkerFallbackRouting(mandatoryDelegation, "Mandatory Delegation Triggers");
+	assertWorkerFallbackRouting(delegationTriggers, "Delegation Triggers");
 	assert.throws(() => resolveSimpleDelegation(routing.replace(reference, "")), /must name the exact canonical Writer rule/);
-	assert.throws(() => resolveSimpleDelegation(routing.replace(reference, reference.replace("Mandatory Delegation Triggers", "Other Rule"))),
+	assert.throws(() => resolveSimpleDelegation(routing.replace(reference, reference.replace("Delegation Triggers", "Other Rule"))),
 		/must name the exact canonical Writer rule/);
-	assert.throws(() => resolveSimpleDelegation(routing.replace("#### Mandatory Delegation Triggers", "#### Missing Canonical Rule")),
-		/exactly one Mandatory Delegation Triggers section/);
+	assert.throws(() => resolveSimpleDelegation(routing.replace("#### Delegation Triggers", "#### Missing Canonical Rule")),
+		/exactly one Delegation Triggers section/);
 	assert.throws(() => resolveSimpleDelegation(routing.replace("user-configured `worker`", "unspecified worker")),
 		/must prefer the package-owned worker before a user-configured worker/);
 	assert.doesNotMatch(
@@ -1758,8 +1760,10 @@ test("bounded implementation routing resolves the explicit canonical fallback re
 });
 
 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");
+	// S11 T2: the explorer fallback binding moved from the delegation card to its reference; the card and
+	// the reference together are the lazy delegation route.
+	for (const files of [["orchestrator.md"], ["orchestrator-delegation.md", "orchestrator-delegation-reference.md"]]) {
+		const routing = files.map((file) => readFileSync(join(PACKAGE_ROOT, "assets", file), "utf8")).join("\n\n");
 		assert.match(routing, /`gentle-ai-explore`/);
 		assert.match(routing, /`gentle-ai-worker`/);
 		assert.match(routing, /`gentle-ai-verify`/);
@@ -1789,9 +1793,9 @@ test("pi-pretty wrapper uses cached ESM loading for compiled and pnpm symlink in
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("Gentle Shell v4.1.0 package manifest declares the release version", () => {
+test("Gentle Shell v4.3.0 package manifest declares the release version", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "4.1.0", "the release manifest must be explicitly pinned to v4.1.0");
+	assert.equal(packageJson.version, "4.3.0", "the release manifest must be explicitly pinned to v4.3.0");
 	assert.equal(packageJson.scripts?.test, "node scripts/run-test-suite.mjs");
 	assert.ok(packageJson.files?.includes("assets/"));
 	assert.ok(packageJson.files?.includes("contracts/"));

package/tests/pi-update-launcher.test.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+
+const PI = '@earendil-works/pi-coding-agent';
+// A virtual symlink filesystem: listed global links point into a pnpm store.
+// The store's adjacent peer is a sibling, not Shell/node_modules/Pi.
+function launch(args: string[], scenario = 'owned', piVersion = '1.2.0') {
+ const adjacent = scenario.startsWith('adjacent');
+ const npm = scenario.startsWith('npm-');
+ const nodeModules = '/global/v11/selected/node_modules';
+ const shellRoot = '/store/shell-peer/node_modules/gentle-pi';
+ const piRoot = adjacent ? '/store/shell-peer/node_modules/' + PI : '/store/pi/node_modules/' + PI;
+ const target = adjacent ? 'gentle-pi' : PI;
+ const dependencies: Record<string, object> = {[target]:{path: `${nodeModules}/${target}`,
+  ...(scenario === 'npm-link' ? {link:true} : {}),
+  ...(scenario === 'npm-file' ? {resolved:'file:/source/pi'} : {})}};
+ if (scenario.endsWith('shared')) dependencies['unrelated'] = {path:`${nodeModules}/unrelated`};
+ if (scenario === 'separate') dependencies['unrelated'] = {path:'/global/v11/other/node_modules/unrelated'};
+ const groups = [{path:'/global/v11',dependencies}, ...(scenario === 'ambiguous' ? [{path:'/global/other',dependencies}] : [])];
+ const listing = scenario === 'malformed' ? '{' : JSON.stringify(npm ? groups[0] : groups);
+ // pnpm links only the top-level package into the global group; the peer
+ // is reachable solely as the Shell package's store sibling.
+ const links = {[`${nodeModules}/${target}`]:adjacent ? shellRoot : piRoot};
+ const roots = [nodeModules, '/global/v11/other/node_modules', shellRoot, piRoot, `${piRoot}/dist/bundle/cli.js`];
+ const bootstrap = `import { registerHooks } from 'node:module';
+ const original = ${JSON.stringify(new URL('../bin/gentle-shell.mjs', import.meta.url).href)};
+ registerHooks({load(url, context, next) {
+  if (url === original) {
+   let source = next(url, context).source.toString();
+   source = source.replace('const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));', ${JSON.stringify(`const packageRoot = '${shellRoot}';`)});
+   source = source.replace('const bundled = resolveBundledInstall({ packageRoot, platform: process.platform, fs: bundledFs, verifying });', 'const bundled = undefined;');
+   source = source.replace('runtime = resolvePiRuntime({', ${JSON.stringify(`runtime = ({ kind: '${adjacent ? 'bundled' : 'env'}', command: '${adjacent ? 'node' : piRoot + '/dist/bundle/cli.js'}', args: ${JSON.stringify(adjacent ? [piRoot + '/dist/bundle/cli.js'] : [])} }); /*`)}).replace('nodeExecPath: process.execPath,\\n\\t\\t});', 'nodeExecPath: process.execPath, */');
+   source = source.replace('const versionProbe = spawnSync(versionProbePlan.command, versionProbePlan.args, {', 'const versionProbe = { stdout: "${piVersion}" }; /*').replace('env: bundledEnv ?? process.env,\\n\\t});', 'env: bundledEnv ?? process.env, */');
+   source = source.replace('async function packageManagerAdapters() {', 'async function packageManagerAdapters() { return globalThis.fakeAdapters; } async function unusedAdapters() {');
+   source = source.replace('let homeHadContentBeforeBootstrap = false;', 'if (passthrough.length === 1) { console.error("error: pi cannot self-update this installation. This installation is not managed by a global pnpm install."); process.exitCode = 1; return; } console.log("FORWARD " + JSON.stringify(passthrough)); return; let homeHadContentBeforeBootstrap = false;');
+   return {format:'module', source, shortCircuit:true};
+  }
+  return next(url,context);
+ }});
+ const links = ${JSON.stringify(links)}, roots = ${JSON.stringify(roots)};
+ globalThis.fakeAdapters = {
+  fs: { realpath: async p => { if (links[p]) return links[p]; if (roots.includes(p)) return p; throw new Error('ENOENT ' + p); },
+   readFile: async p => { if (p === '${shellRoot}/package.json') return JSON.stringify({name:'gentle-pi',version:'4.1.0'}); if(p === '${piRoot}/package.json') return JSON.stringify({name:'${PI}',version:'1.2.0',bin:{pi:'dist/bundle/cli.js'}}); throw new Error('ENOENT ' + p); } },
+  which: async n => n === '${npm ? 'npm' : 'pnpm'}' ? '/fake/' + n : null,
+  run: async (cmd, args) => {
+   if(args.includes('list') || args.includes('ls')) return {code:0,stdout:${JSON.stringify(listing)}};
+   console.log('MUTATION ' + JSON.stringify(args)); return {code:0};
+  }
+ };
+ await import(original);`;
+ return spawnSync(process.execPath, ['--import', `data:text/javascript,${encodeURIComponent(bootstrap)}`, 'bin/gentle-shell.mjs', ...args], {encoding:'utf8'});
+}
+
+for (const scenario of ['owned','adjacent','separate']) test(`public linked-store update succeeds for ${scenario}`, () => {
+ const result = launch(['update'], scenario);
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(result.stdout, scenario === 'adjacent' ? /MUTATION \["add","-g","gentle-pi@4\.1\.0","--allow-build=gentle-pi"\]/ : /MUTATION \["add","-g","@earendil-works\/pi-coding-agent@latest"\]/);
+ assert.doesNotMatch(result.stdout, /FORWARD/);
+ // The fake manager changes nothing, so the readback reports the same version and pnpm's release-age rule.
+ assert.match(result.stdout, /the selected Pi is still 1\.2\.0\./);
+ assert.match(result.stdout, /minimumReleaseAge/);
+ assert.equal(result.stderr, '');
+});
+
+test('public all updates only its owner and then forwards extension updates', () => {
+ const result = launch(['update', '--all']);
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(result.stdout, /MUTATION .*add.*@earendil-works\/pi-coding-agent@latest/);
+ assert.match(result.stdout, /FORWARD \["update","--extensions"\]/);
+ assert.equal(result.stderr, '');
+});
+
+for (const scenario of ['ambiguous', 'malformed', 'npm-link', 'npm-file', 'shared', 'adjacent-shared']) test(`public update rejects ${scenario} ownership without mutation`, () => {
+ const result = launch(['update'], scenario);
+ assert.equal(result.status, 1, result.stdout);
+ assert.equal(result.stdout, '');
+ assert.match(result.stderr, /ownership/);
+ assert.doesNotMatch(result.stdout + result.stderr, /MUTATION/);
+});
+
+// `update` is how an old Pi gets replaced, so the minimum-version gate must not block it.
+test('public update replaces a Pi older than the required minimum', () => {
+ const result = launch(['update'], 'owned', '1.1.0');
+ assert.equal(result.status, 0, result.stderr);
+ assert.match(result.stdout, /MUTATION \["add","-g","@earendil-works\/pi-coding-agent@latest"\]/);
+ assert.doesNotMatch(result.stdout + result.stderr, /older than the required minimum/);
+ assert.equal(result.stderr, '');
+});
+
+test('an old Pi still fails the minimum-version gate outside a self update', () => {
+ for (const args of [['list'], ['update', '--extensions-only']]) {
+  const result = launch(args, 'owned', '1.1.0');
+  assert.equal(result.status, 1, result.stdout);
+  assert.equal(result.stdout, '');
+  assert.match(result.stderr, /pi version 1\.1\.0 is older than the required minimum 1\.2\.0\./);
+  assert.doesNotMatch(result.stdout, /MUTATION/);
+ }
+});
+
+test('public extensions-only update preserves the forwarded command', () => {
+ const result = launch(['update', '--extensions-only']);
+ assert.equal(result.status, 0, result.stderr);
+ assert.equal(result.stdout, 'FORWARD ["update","--extensions-only"]\n');
+ assert.equal(result.stderr, '');
+});

package/tests/pi-update.test.ts

@@ -0,0 +1,186 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { managedUpdatePlan, updateSelectedPi } from '../scripts/pi-update.mjs';
+import { bundledUpdatePlan, bundledUpdateNext } from '../runtime/gentle-shell-bundled.mjs';
+
+const PI = '@earendil-works/pi-coding-agent';
+const CLI = 'dist/bundle/cli.js';
+
+// The layouts pnpm v11 and npm really produce. pnpm links each top-level
+// package from its own global group into the linked store, where Shell's
+// peer is a sibling of the Shell package; a separate global Pi links to the
+// same store entry. npm nests the peer under the Shell package.
+function fixture({windows = false, npm = false, runtime = 'adjacent', groups = 'both', peerAfter = '1.2.0', shellVersion = '4.1.0',
+ badManifest = false, failed = false, mismatch = false, linked = false, readback = true, unrelatedPeer = false, shim = ''} = {}) {
+ const base = windows ? 'C:/pnpm' : '/pnpm';
+ const storePi = (version: string) => `${base}/store/links/@earendil-works/pi-coding-agent/${version}/h/node_modules/${PI}`;
+ const shellModules = npm ? `${base}/npm/lib/node_modules` : `${base}/store/links/@/gentle-pi/4.1.0/h1/node_modules`;
+ const shell = `${shellModules}/gentle-pi`;
+ const nestedPeer = `${shell}/node_modules/${PI}`;
+ const g1 = npm ? shellModules : `${base}/global/v11/g1/node_modules`;
+ const g2 = npm ? shellModules : `${base}/global/v11/g2/node_modules`;
+ const g3 = `${base}/global/v11/g3/node_modules`;
+ const state = {peer: '1.1.0', group: '1.1.0'};
+ const peerRoot = () => npm ? nestedPeer : storePi(state.peer);
+ const selectedCli = `${npm ? (runtime === 'adjacent' ? nestedPeer : `${shellModules}/${PI}`) : storePi('1.1.0')}/${CLI}`;
+ // A package-manager shim on PATH: its text names the global Pi group's cli.js.
+ const shimFile = `${base}/bin/pi${windows ? '.CMD' : ''}`;
+ const shimText = shim === 'posix' ? `#!/bin/sh\nbasedir=$(dirname "$0")\nexec node  "$basedir/../global/v11/g2/node_modules/${PI}/${CLI}" "$@"\n`
+  : shim === 'windows' ? `@"%~dp0\\..\\global\\v11\\g2\\node_modules\\@earendil-works\\pi-coding-agent\\dist\\bundle\\cli.js" %*\r\n`
+  : shim === 'two' ? `"$basedir/../a/dist/bundle/cli.js" "$basedir/../b/dist/bundle/cli.js"` : shim === 'none' ? '#!/bin/sh\nexec something\n' : '';
+ const mutations: string[][] = [];
+ const out: string[] = [];
+ const cwds: unknown[] = [];
+ const entry = (pkg: string, modules: string, extra = {}) => ({[pkg]: {path: `${modules}/${pkg}`, ...extra}});
+ const shellEntry = entry('gentle-pi', g1, linked ? {link: true} : {});
+ const piEntry = entry(PI, g2, linked ? {resolved: 'file:/src/pi'} : {});
+ const listing = () => {
+  const deps = {...(groups !== 'pi' ? shellEntry : {}), ...(groups !== 'shell' ? piEntry : {}),
+   ...(groups === 'shared' ? entry('unrelated-tool', g1) : {}), ...(groups === 'separate' ? entry('unrelated-tool', g3) : {})};
+  const group = {path: npm ? shellModules : `${base}/global/v11`, dependencies: deps};
+  return npm ? group : [group];
+ };
+ const exists = (n: string) => [g1, g2, g3, shellModules, shell, storePi(state.peer), storePi(state.group), storePi('1.1.0'), nestedPeer]
+  .some(root => n === root || n.startsWith(root + '/'));
+ const realpath = async (value: string) => {
+  const n = value.replaceAll('\\', '/');
+  if (n === shimFile) return n;
+  // Symlinked components inside a longer path resolve like the real filesystem does.
+  if (n.startsWith(`${g2}/${PI}/`)) return (npm ? `${g2}/${PI}` : storePi(state.group)) + n.slice(`${g2}/${PI}`.length);
+  if (n === `${g1}/gentle-pi` || n === `${g1}/unrelated-tool` || n === `${g3}/unrelated-tool`) return n === `${g1}/gentle-pi` ? shell : n;
+  if (n === `${g2}/${PI}`) return npm ? n : storePi(state.group);
+  if (!npm && n === `${shellModules}/${PI}`) return storePi(state.peer);
+  if (!npm && n === nestedPeer) throw new Error('ENOENT nested peer');
+  // Only joined (backslash) paths mismatch: the selected CLI itself stays canonical.
+  if (mismatch && n.endsWith(CLI) && value.includes('\\')) return `${base}/other/cli.js`;
+  if (exists(n)) return n;
+  throw new Error(`ENOENT ${n}`);
+ };
+ const readFile = async (value: string) => {
+  const n = value.replaceAll('\\', '/');
+  if (n === shimFile) return shimText;
+  if (n === `${shell}/package.json`) return JSON.stringify({name: 'gentle-pi', ...(shellVersion ? {version: shellVersion} : {})});
+  if (n === `${g1}/unrelated-tool/package.json`) return JSON.stringify({name: 'unrelated-tool'});
+  const version = n.startsWith(nestedPeer) ? state.peer : /pi-coding-agent\/([\d.]+)\/h\//.exec(n)?.[1];
+  if (badManifest || unrelatedPeer) return JSON.stringify({name: unrelatedPeer ? 'other' : PI, version});
+  return JSON.stringify({name: PI, version, bin: {pi: CLI}});
+ };
+ const run = async (_command: string, args: string[], options?: {cwd?: unknown}) => {
+  cwds.push(options?.cwd);
+  if (args.includes('list') || args.includes('ls')) return {code: failed ? 1 : 0, stdout: readback || mutations.length === 0 ? JSON.stringify(listing()) : '{'};
+  mutations.push(args);
+  if (args.some(arg => arg.startsWith('gentle-pi@'))) state.peer = peerAfter;
+  if (args.some(arg => arg.startsWith(PI + '@'))) state.group = peerAfter;
+  return {code: 0};
+ };
+ return {mutations, out, cwds, state, shell, selectedCli, input: {platform: windows ? 'win32' : 'linux', packageRoot: `${g1}/gentle-pi`, currentVersion: '1.1.0', cwd: '/neutral',
+  runtime: runtime === 'adjacent' ? {kind: 'bundled', command: 'node', args: [selectedCli]} : {kind: runtime, command: shim ? shimFile : selectedCli, args: []},
+  out: (line: string) => out.push(line),
+  adapters: {which: async (name: string) => name === (npm ? 'npm' : 'pnpm') ? `/fake/${name}` : null, fs: {realpath, readFile}, run}}};
+}
+
+test('prefix distribution still redirects self update and forwards only extensions for all', () => {
+ assert.deepEqual(bundledUpdatePlan(['update']), {self: true});
+ assert.deepEqual(bundledUpdateNext(bundledUpdatePlan(['update']), 0), {exitCode: 0});
+ assert.deepEqual(bundledUpdatePlan(['update', '--all']), {self: true, piArgs: ['update', '--extensions']});
+ assert.deepEqual(bundledUpdatePlan(['update', '--extensions-only']), {self: false, piArgs: ['update', '--extensions-only']});
+});
+
+for (const args of [['update', '--extensions-only'], ['update', '--extensions'], ['update', 'npm:custom'], ['update', '--models'], ['update', '--help'], ['update', '--unknown']]) test(`no ownership interception for ${args.join(' ')}`, () => {
+ assert.deepEqual(managedUpdatePlan(args), {self: false, piArgs: args});
+});
+
+test('all strips only self update before forwarding extension flags', () => {
+ assert.deepEqual(managedUpdatePlan(['update', '--all', '--approve']), {self: true, piArgs: ['update', '--extensions', '--approve']});
+});
+
+for (const windows of [false, true]) test(`an adjacent peer is refreshed by reinstalling its Shell package at the same version, never the separate global Pi (windows: ${windows})`, async () => {
+ const f = fixture({windows});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', 'gentle-pi@4.1.0', '--allow-build=gentle-pi']]);
+ assert.deepEqual(f.out, ['pnpm installed gentle-pi@4.1.0; the selected Pi is now 1.2.0 (was 1.1.0).']);
+ assert.equal(f.state.group, '1.1.0');
+});
+
+for (const runtime of ['path', 'env']) test(`a ${runtime} runtime sharing the store entry is updated through its own global Pi package`, async () => {
+ const f = fixture({runtime});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', `${PI}@latest`]]);
+ assert.deepEqual(f.out, [`pnpm installed ${PI}@latest; the selected Pi is now 1.2.0 (was 1.1.0).`]);
+ assert.equal(f.state.peer, '1.1.0');
+});
+
+test('npm nests the peer under Shell and reinstalls Shell for it', async () => {
+ const f = fixture({npm: true});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['install', '-g', 'gentle-pi@4.1.0']]);
+ assert.deepEqual(f.out, ['npm installed gentle-pi@4.1.0; the selected Pi is now 1.2.0 (was 1.1.0).']);
+});
+
+test('an npm PATH runtime updates the global Pi without its scripts', async () => {
+ const f = fixture({npm: true, runtime: 'path'});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['install', '-g', `${PI}@latest`, '--ignore-scripts']]);
+});
+
+test('an unchanged pnpm result names the minimum-release-age rule instead of claiming latest', async () => {
+ const f = fixture({peerAfter: '1.1.0'});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.equal(f.out[0], 'pnpm installed gentle-pi@4.1.0, and the selected Pi is still 1.1.0.');
+ assert.match(f.out[1], /minimumReleaseAge/);
+ assert.equal(f.out.length, 2);
+});
+
+test('every package manager call runs from the neutral directory, never the project cwd', async () => {
+ const f = fixture();
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.cwds, ['/neutral', '/neutral', '/neutral']);
+});
+
+test('an unreadable readback is reported, not invented', async () => {
+ const f = fixture({readback: false});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.out, ['pnpm installed gentle-pi@4.1.0. The Pi version it now supplies could not be read back; run \'gentle-shell --version\' to check it.']);
+});
+
+test('separate aggregated groups do not block the Shell reinstall', async () => {
+ const f = fixture({groups: 'separate'});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', 'gentle-pi@4.1.0', '--allow-build=gentle-pi']]);
+});
+
+for (const [name, options] of Object.entries({
+ 'listing failed': {failed: true},
+ 'peer identity differs': {badManifest: true},
+ 'peer package is not Pi': {unrelatedPeer: true},
+ 'selected CLI mismatches on Windows': {windows: true, mismatch: true},
+ 'linked or file suppliers': {linked: true},
+ 'Shell shares its global group': {groups: 'shared'},
+ 'Shell version is missing': {shellVersion: ''},
+ 'only a separate global Pi is listed for an adjacent runtime': {groups: 'pi'},
+ 'only Shell is listed for a PATH runtime': {runtime: 'path', groups: 'shell'},
+})) test(`ownership rejects without mutation when ${name}`, async () => {
+ const f = fixture(options);
+ await assert.rejects(updateSelectedPi(f.input), /ownership/);
+ assert.deepEqual(f.mutations, []);
+ assert.deepEqual(f.out, []);
+});
+
+for (const [name, options] of Object.entries({'pnpm POSIX shim': {shim: 'posix', runtime: 'path'}, 'Windows .CMD shim': {shim: 'windows', runtime: 'path', windows: true}, 'GENTLE_SHELL_PI shim override': {shim: 'posix', runtime: 'env'}})) test(`a ${name} resolves to the global Pi it runs`, async () => {
+ const f = fixture(options);
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', `${PI}@latest`]]);
+});
+
+for (const [name, shim] of Object.entries({'names several targets': 'two', 'is not a Pi entry': 'none'})) test(`a shim that ${name} is refused without mutation`, async () => {
+ const f = fixture({shim, runtime: 'path'});
+ await assert.rejects(updateSelectedPi(f.input), /ownership/);
+ assert.deepEqual(f.mutations, []);
+});
+
+test('an unrelated selected override cannot authorize the adjacent Shell group', async () => {
+ const f = fixture();
+ f.input.runtime = {kind: 'env', command: '/unrelated/pi', args: []};
+ await assert.rejects(updateSelectedPi(f.input), /ownership/);
+ assert.deepEqual(f.mutations, []);
+});

package/tests/primary-session-prompt.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after, before } from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+// gentle-ai R3 (odd/tasks/pi-routing-from-bundle.md): the harness ODD step
+// lines 1-7, the phase-reporting line, and the resume line come from the
+// mirrored provider contract bundle's routing/pi.md instead of a hand-copied
+// literal, and the rendered primary-session prompt stays byte-identical.
+//
+// The golden was captured from the base commit (main 4372ff2d, after R1) before the steps moved into the
+// bundle, with the inputs below and the package assets root normalized. When a
+// prompt change is intended, regenerate it with
+// UPDATE_PRIMARY_SESSION_PROMPT_GOLDEN=1 and review the golden diff.
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const GOLDEN_PATH = join(REPO_ROOT, "tests", "fixtures", "primary-session-prompt", "gentleman.golden.md");
+const ACTIVE_TOOLS = ["read", "bash", "edit", "write", "subagent_run"] as const;
+const MIRROR_ROOT = join(REPO_ROOT, "contracts", "review-provider-contract-mirror");
+
+let scratch: string;
+const previousEnvironment = new Map<string, string | undefined>();
+before(() => {
+	scratch = mkdtempSync(join(tmpdir(), "gentle-pi-primary-prompt-"));
+	for (const key of ["GENTLE_PI_CONFIG_HOME", "GENTLE_PI_BACKGROUND_SUBAGENTS"]) previousEnvironment.set(key, process.env[key]);
+	process.env.GENTLE_PI_CONFIG_HOME = join(scratch, "config");
+	delete process.env.GENTLE_PI_BACKGROUND_SUBAGENTS;
+});
+after(() => {
+	for (const [key, value] of previousEnvironment) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	rmSync(scratch, { recursive: true, force: true });
+});
+
+function renderPrimaryPrompt(): string {
+	const prompt = __testing.buildGentlePrompt("gentleman", join(scratch, "project"), ACTIVE_TOOLS);
+	return prompt.replaceAll(join(REPO_ROOT, "assets"), "{{GENTLE_PI_ASSETS_ROOT}}");
+}
+
+function mirroredRoutingText(): string {
+	const lock = JSON.parse(readFileSync(join(MIRROR_ROOT, "provider-contract.lock.json"), "utf8")) as { contract_semver: string };
+	return readFileSync(join(MIRROR_ROOT, `v${lock.contract_semver}`, "bundle", "routing", "pi.md"), "utf8");
+}
+
+// Writes a one-file mirror whose lock records `entrySha256` for routing/pi.md.
+function tempRoutingMirror(text: string, entrySha256 = createHash("sha256").update(text, "utf8").digest("hex")): string {
+	const root = mkdtempSync(join(scratch, "mirror-"));
+	const routingDir = join(root, "v9.9.9", "bundle", "routing");
+	mkdirSync(routingDir, { recursive: true });
+	writeFileSync(join(routingDir, "pi.md"), text, "utf8");
+	writeFileSync(join(root, "provider-contract.lock.json"), JSON.stringify({ contract_semver: "9.9.9", entries: { "routing/pi.md": entrySha256 } }), "utf8");
+	return root;
+}
+
+test("the rendered primary-session prompt is byte-identical to the golden captured from the base", () => {
+	const rendered = renderPrimaryPrompt();
+	if (process.env.UPDATE_PRIMARY_SESSION_PROMPT_GOLDEN === "1") writeFileSync(GOLDEN_PATH, rendered, "utf8");
+	assert.equal(rendered, readFileSync(GOLDEN_PATH, "utf8"));
+});
+
+test("the ODD steps, phase reporting, and resume lines come from the mirrored routing/pi.md without its blank lines", () => {
+	const routing = mirroredRoutingText();
+	const section = routing.slice(routing.indexOf("### ODD protocol"), routing.indexOf("\n### Task Size"));
+	const expected = section.split("\n").slice(1).filter((line) => line !== "");
+	assert.equal(expected.length, 9);
+	assert.equal(__testing.readMirroredOddProtocolSteps(), expected.join("\n"));
+	assert.ok(renderPrimaryPrompt().includes(`Run these steps in this order on every request:\n${expected.join("\n")}\n\nHarness principles:`));
+	assert.ok(routing.includes(`${expected[6]}\n\n${expected[7]}\n\n${expected[8]}`), "the bundle separates step 7, phase reporting, and resume with blank lines");
+});
+
+test("extensions/gentle-ai.ts no longer carries the ODD step lines as string literals", () => {
+	const source = readFileSync(join(REPO_ROOT, "extensions", "gentle-ai.ts"), "utf8");
+	for (const literal of ["1. **Authorize.**", "5. **Track before the first write.**", "7. **Close.**", "Phase reporting: the Gentle Shell prompt label", "Resume an interrupted feature with"]) {
+		assert.ok(!source.includes(literal), `extensions/gentle-ai.ts still hard-codes ${JSON.stringify(literal)}`);
+	}
+});
+
+test("a changed mirrored routing block changes the rendered steps", () => {
+	const routing = mirroredRoutingText().replace("1. **Authorize.** ", "1. **Authorize.** Changed upstream. ");
+	const mirror = tempRoutingMirror(routing);
+	assert.match(__testing.readMirroredOddProtocolSteps(mirror), /^1\. \*\*Authorize\.\*\* Changed upstream\. /);
+});
+
+test("a tampered or missing mirrored routing/pi.md fails closed with an explicit error", () => {
+	const unavailable = /Gentle Shell cannot render its ODD steps: the mirrored provider bundle's routing\/pi\.md is missing, unreadable, or fails digest verification/;
+	assert.throws(() => __testing.readMirroredOddProtocolSteps(tempRoutingMirror(mirroredRoutingText(), "0".repeat(64))), unavailable);
+	assert.throws(() => __testing.readMirroredOddProtocolSteps(join(scratch, "absent-mirror")), unavailable);
+});
+
+test("a routing block whose ODD protocol section changed shape fails closed", () => {
+	const unexpectedShape = /routing\/pi\.md ODD protocol section has an unexpected shape/;
+	const withoutResume = mirroredRoutingText().replace(/\nResume an interrupted feature[^\n]*\n/, "\n");
+	assert.throws(() => __testing.readMirroredOddProtocolSteps(tempRoutingMirror(withoutResume)), unexpectedShape);
+	const withoutSection = mirroredRoutingText().replace("### ODD protocol (MANDATORY, in this order, on every request)", "### ODD protocol");
+	assert.throws(() => __testing.readMirroredOddProtocolSteps(tempRoutingMirror(withoutSection)), unexpectedShape);
+});