gentle-pi 4.2.0 → 4.4.0

package/tests/orchestrator-state.test.ts

@@ -74,6 +74,35 @@ test("alias identity preserves status age, validates data, and rejects stale bra
 	assert.deepEqual(cache.get(manager)?.aliases, valid.aliases);
 });
 
+test("explicit work topic refreshes the current alias when no subject is declared (#2553)", () => {
+	const cache = new OrchestratorStateCache();
+	const entries: { type: string; customType: string; data: unknown }[] = [];
+	const manager = { getSessionId: () => "owner", getCwd: () => "/repo", getBranch: () => entries };
+	const append = (customType: string, data: unknown) => entries.push({ type: "custom", customType, data });
+	cache.load(manager);
+	const work = { area: "gentle-shell", topic: "pr-2509-followup" };
+	cache.publish(manager, { work }, append, 10);
+	assert.deepEqual(cache.get(manager)?.aliases, { initialAlias: "pr-2509-followup", currentAlias: "pr-2509-followup" });
+	// Fresh topic on a later publication updates Current; Initial is retained.
+	cache.publish(manager, { work: { area: "gentle-shell", topic: "ci-watch" } }, append, 20);
+	assert.deepEqual(cache.get(manager)?.aliases, { initialAlias: "pr-2509-followup", currentAlias: "ci-watch" });
+	// A state-only refresh never re-derives the alias from stored work.
+	cache.publish(manager, undefined, append, 30);
+	assert.deepEqual(cache.get(manager)?.aliases, { initialAlias: "pr-2509-followup", currentAlias: "ci-watch" });
+	// An explicit subject in the same publication wins over the topic.
+	cache.publish(manager, { work }, append, 40, "declared-task");
+	assert.deepEqual(cache.get(manager)?.aliases, { initialAlias: "pr-2509-followup", currentAlias: "declared-task" });
+	// Legacy records without aliases: topic refreshes Current, Initial stays unknown.
+	const legacy = [{ type: "custom", customType: ORCHESTRATOR_STATE_ENTRY, data: {
+		schema: 1, sessionId: "owner", recordedAt: 1, cwd: "/repo", source: "owner-curated",
+		ownerReply: false, authority: "none", state: null } }];
+	const legacyManager = { getSessionId: () => "owner", getCwd: () => "/repo", getBranch: () => legacy };
+	const legacyCache = new OrchestratorStateCache();
+	legacyCache.load(legacyManager);
+	legacyCache.publish(legacyManager, { work }, append, 50);
+	assert.deepEqual(legacyCache.get(legacyManager)?.aliases, { initialAlias: null, currentAlias: "pr-2509-followup" });
+});
+
 test("recorded cwd preserves only unambiguous native absolute paths", () => {
 	const separators = [0x00a0, ...Array.from({ length: 11 }, (_, i) => 0x2000 + i), 0x202f, 0x205f, 0x3000];
 	const invalid = ["relative/repo", "/repo\nother", "/repo\ud800", "/" + "x".repeat(1024),

package/tests/orchestrator-status-publication-contract.test.ts

@@ -8,16 +8,20 @@ const source = readFileSync(join(root, "extensions/gentle-agents.ts"), "utf8");
 const sessionTool = source.match(/name: "orchestrator_session_id",\s*label: "[^"]+",\s*description: ("(?:[^"\\]|\\.)*")/);
 assert.ok(sessionTool, "Registered session tool exposes its publication contract");
 const description: string = JSON.parse(sessionTool[1]);
-const guidance = readFileSync(join(root, "assets/orchestrator-delegation.md"), "utf8");
+// S11 T2: state publication is reference material; the delegation card only points at it.
+const guidance = readFileSync(join(root, "assets/orchestrator-delegation-reference.md"), "utf8");
 const docs = readFileSync(join(root, "docs/gentle-agents-activity.md"), "utf8");
 
-test("shipped guidance publishes status before work and refreshes task transitions", () => {
-	assert.match(description, /For work beyond small direct tasks, publish subject and current\/next status here; refresh at task changes\/completion/);
+// Harness roadmap T6: the runtime publishes todo progress, so guidance stops
+// asking the model to refresh status at every task transition.
+test("shipped guidance declares a subject and leaves progress to the todo list", () => {
+	assert.match(description, /Progress is published automatically from the todo list/);
+	assert.doesNotMatch(description, /refresh at task changes/);
 	assert.doesNotMatch(description, /Before meaningful work, publish subject/);
-	assert.match(guidance, /Before work beyond small direct tasks, publish own `state` with `subject`/);
+	assert.match(guidance, /Progress is published automatically from the todo list: never call `orchestrator_session_id` just to report status/);
+	assert.match(guidance, /Before work beyond small direct tasks, declare a `subject`/);
 	assert.doesNotMatch(guidance, /Before meaningful work or delegation, publish own `state`/);
-	assert.match(guidance, /current\/next scope and status/);
-	assert.match(guidance, /Refresh at task changes\/completion/);
+	assert.doesNotMatch(guidance, /Refresh at task changes\/completion/);
 	assert.doesNotMatch(guidance, /when helpful, publish short explicit own `state`/);
 	assert.match(guidance, /Do not require a subject declaration for small direct tasks/);
 	assert.match(guidance, /no extra model turn, repeated reads or per-token\/tool updates/);
@@ -25,10 +29,10 @@ test("shipped guidance publishes status before work and refreshes task transitio
 });
 
 test("hub documentation separates busy-owner snapshots from replies and negative ownership claims", () => {
-	assert.match(docs, /before work beyond small direct tasks/);
+	assert.match(docs, /before work beyond\s+small direct tasks/);
 	assert.match(docs, /while the owner is busy/);
 	assert.match(docs, /current and next scope/);
-	assert.match(docs, /update at task changes and completion/);
+	assert.match(docs, /Progress is published automatically: after each todo write/);
 	assert.match(docs, /A search with no matches does not establish that nobody else is working on the feature/);
 	assert.match(docs, /state `recordedAt` and scope `resolvedAt` keep their historical meaning/);
 });

package/tests/package-files.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { missingRequiredPaths, requiredPaths } from "../scripts/verify-package-files.mjs";
+
+// The voice worker is spawned by path and never imported, so only the package
+// check keeps it in the published tarball next to the modules that launch it.
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+
+test("the package check requires the voice command, its modules and the worker script", () => {
+	const voice = ["extensions/gentle-voice.ts", "lib/voice-command.ts", "lib/voice-session.ts", "lib/voice-ui.ts", "scripts/voice-worker.cjs", "docs/voice.md"];
+	for (const path of voice) assert.ok(requiredPaths.includes(path), `${path} is required`);
+	assert.deepEqual(missingRequiredPaths(root, voice), []);
+});
+
+// The canvas server reads its page and scripts from assets/ by path, never by import.
+const designCanvas = [
+	"lib/design-canvas-server.ts",
+	"lib/design-open-browser.ts",
+	"lib/design-comments.ts",
+	"lib/design-handoffs.ts",
+	"assets/design-canvas/index.html",
+	"assets/design-canvas/canvas.js",
+	"assets/design-canvas/canvas.css",
+	"assets/design-canvas/inspector.js",
+];
+
+// The design command names its skill file by path when Pi has not loaded it.
+test("the package check requires the design command, its helpers and its skill", () => {
+	const design = ["extensions/gentle-design.ts", "lib/gentle-design.ts", "lib/design-sources.ts", "skills/design/SKILL.md", ...designCanvas];
+	for (const path of design) assert.ok(requiredPaths.includes(path), `${path} is required`);
+	assert.deepEqual(missingRequiredPaths(root, design), []);
+});

package/tests/package-manifest.test.ts

@@ -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.3.1 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\.3\.1"/);
 	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:00p8dnjJrhYFq1Qikk2oY6K\/UXIty9A\/IBUUOUiX9XA="/);
 	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\.3\.1/);
 });
 
 
@@ -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.2.0 package manifest declares the release version", () => {
+test("Gentle Shell v4.4.0 package manifest declares the release version", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "4.2.0", "the release manifest must be explicitly pinned to v4.2.0");
+	assert.equal(packageJson.version, "4.4.0", "the release manifest must be explicitly pinned to v4.4.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/permission-mode-policy.test.ts

@@ -7,7 +7,7 @@ import { syncBuiltinESMExports } from "node:module";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerYoloSessionPolicy, discoverYoloUiAdapter } from "../lib/yolo-session-policy.ts";
-import { parsePermissionModePolicyFile, resolvePermissionModePolicy, writePermissionModePolicy, permissionModePolicyFile, PERMISSION_MODE_SCHEMA } from "../lib/permission-mode-policy.ts";
+import { isPermissionMode, parsePermissionModePolicyFile, resolvePermissionModePolicy, writePermissionModePolicy, permissionModePolicyFile, PERMISSION_MODE_SCHEMA } from "../lib/permission-mode-policy.ts";
 
 function fixture(t: test.TestContext) {
  const home = mkdtempSync(join(tmpdir(), "gentle-mode-"));
@@ -192,3 +192,12 @@ test("stale pending activation, scope loss and malformed preference remain close
  assert.equal(await h.controller.saveDefault("yolo", h.context), false);
  assert.equal(readFileSync(permissionModePolicyFile(options), "utf8"), "{");
 });
+
+test("super-yolo is a valid saved and parsed permission mode", t => {
+ const options = fixture(t);
+ assert.equal(isPermissionMode("super-yolo"), true);
+ assert.equal(isPermissionMode("superyolo"), false);
+ const path = writePermissionModePolicy("super-yolo", options);
+ assert.equal(parsePermissionModePolicyFile(readFileSync(path, "utf8")), "super-yolo");
+ assert.equal(resolvePermissionModePolicy(options).mode, "super-yolo");
+});

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

@@ -5,7 +5,7 @@ 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') {
+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';
@@ -31,7 +31,7 @@ function launch(args: string[], scenario = 'owned') {
    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: "1.2.0" }; /*').replace('env: bundledEnv ?? process.env,\\n\\t});', 'env: bundledEnv ?? process.env, */');
+   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};
@@ -79,6 +79,25 @@ for (const scenario of ['ambiguous', 'malformed', 'npm-link', 'npm-file', 'share
  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);

package/tests/pi-update.test.ts

@@ -11,8 +11,12 @@ const CLI = 'dist/bundle/cli.js';
 // 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 = ''} = {}) {
+ badManifest = false, failed = false, mismatch = false, linked = false, readback = true, unrelatedPeer = false, shim = '',
+ artifact = true, configHome = '', installFailure = undefined as undefined | {stdout?: string, stderrTail?: string}} = {}) {
  const base = windows ? 'C:/pnpm' : '/pnpm';
+ const home = windows ? 'C:/Users/u' : '/home/u';
+ // The tarball `gentle-shell upgrade --channel main` packs, named after its version.
+ const tarball = `${configHome || `${home}/.pi/gentle-ai`}/main/packages/gentle-pi-${shellVersion}.tgz`;
  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`;
@@ -31,6 +35,7 @@ function fixture({windows = false, npm = false, runtime = 'adjacent', groups = '
  const mutations: string[][] = [];
  const out: string[] = [];
  const cwds: unknown[] = [];
+ const runOptions: 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'} : {});
@@ -41,7 +46,7 @@ function fixture({windows = false, npm = false, runtime = 'adjacent', groups = '
   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 + '/'));
+  .some(root => n === root || n.startsWith(root + '/')) || (artifact && n === tarball);
  const realpath = async (value: string) => {
   const n = value.replaceAll('\\', '/');
   if (n === shimFile) return n;
@@ -69,11 +74,14 @@ function fixture({windows = false, npm = false, runtime = 'adjacent', groups = '
   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;
+  runOptions.push(options);
+  if (installFailure) return {code: 1, stdout: installFailure.stdout ?? '', ...('stderrTail' in installFailure ? {stderrTail: installFailure.stderrTail} : {})};
+  if (args.some(arg => arg.startsWith('gentle-pi@') || arg.endsWith('.tgz'))) 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',
+ return {mutations, out, cwds, runOptions, state, shell, selectedCli, tarball, input: {platform: windows ? 'win32' : 'linux', packageRoot: `${g1}/gentle-pi`, currentVersion: '1.1.0', cwd: '/neutral',
+  home, env: configHome ? {GENTLE_PI_CONFIG_HOME: configHome} : {},
   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}}};
@@ -117,6 +125,60 @@ test('npm nests the peer under Shell and reinstalls Shell for it', async () => {
  assert.deepEqual(f.out, ['npm installed gentle-pi@4.1.0; the selected Pi is now 1.2.0 (was 1.1.0).']);
 });
 
+// #2324: main-channel Shell versions are never published; only the tarball
+// `gentle-shell upgrade --channel main` packed can reinstall that exact build.
+const MAIN = '4.2.0-main.fb5e731119a7';
+const native = (path: string, windows: boolean) => windows ? path.replaceAll('/', '\\') : path;
+
+for (const windows of [false, true]) test(`a main-channel Shell is reinstalled from its recorded tarball, never from the registry (windows: ${windows})`, async () => {
+ const f = fixture({windows, shellVersion: MAIN});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', native(f.tarball, windows), '--allow-build=gentle-pi']]);
+ assert.deepEqual(f.out, [`pnpm installed ${native(f.tarball, windows)}; the selected Pi is now 1.2.0 (was 1.1.0).`]);
+ assert.equal(f.state.group, '1.1.0');
+});
+
+test('npm reinstalls a main-channel Shell from its recorded tarball', async () => {
+ const f = fixture({npm: true, shellVersion: MAIN});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['install', '-g', f.tarball]]);
+});
+
+test('a main-channel tarball is found under GENTLE_PI_CONFIG_HOME', async () => {
+ const f = fixture({shellVersion: MAIN, configHome: '/custom/config'});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', '/custom/config/main/packages/gentle-pi-4.2.0-main.fb5e731119a7.tgz', '--allow-build=gentle-pi']]);
+});
+
+test('a missing main-channel tarball names the rebuild command and installs nothing', async () => {
+ const f = fixture({shellVersion: MAIN, artifact: false});
+ await assert.rejects(updateSelectedPi(f.input), {message: `gentle-shell update: the main-channel build ${f.tarball} is missing, and this unpublished build cannot be reinstalled from the registry; run 'gentle-shell upgrade --channel release' and then 'gentle-shell upgrade --channel main' to rebuild it. No installation changed.`});
+ assert.deepEqual(f.mutations, []);
+ assert.deepEqual(f.out, []);
+});
+
+// A relative config home names different folders for `upgrade` and `update`
+// run from different directories, and npm/pnpm resolve it from the neutral cwd.
+test('a relative GENTLE_PI_CONFIG_HOME is refused for a main-channel Shell without mutation', async () => {
+ const f = fixture({shellVersion: MAIN, configHome: 'relative/config'});
+ await assert.rejects(updateSelectedPi(f.input), /ownership cannot locate the main-channel build without an absolute config home/);
+ assert.deepEqual(f.mutations, []);
+ assert.deepEqual(f.out, []);
+});
+
+test('a main-channel Shell without a home directory is refused without mutation', async () => {
+ const f = fixture({shellVersion: MAIN});
+ delete (f.input as {home?: string}).home;
+ await assert.rejects(updateSelectedPi(f.input), /ownership cannot locate the main-channel build without an absolute config home/);
+ assert.deepEqual(f.mutations, []);
+});
+
+for (const runtime of ['path', 'env']) test(`a main-channel Shell never redirects the update of a selected ${runtime} Pi`, async () => {
+ const f = fixture({runtime, shellVersion: MAIN, artifact: false});
+ assert.equal(await updateSelectedPi(f.input), 0);
+ assert.deepEqual(f.mutations, [['add', '-g', `${PI}@latest`]]);
+});
+
 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);
@@ -184,3 +246,36 @@ test('an unrelated selected override cannot authorize the adjacent Shell group',
  await assert.rejects(updateSelectedPi(f.input), /ownership/);
  assert.deepEqual(f.mutations, []);
 });
+
+// #2371: a failed install shows the package manager it ran and one sanitized
+// line of its own output; pnpm 11 prints ERR_PNPM_* on stdout, npm on stderr.
+test('a failed pnpm install names the pnpm it ran and its ERR_PNPM line from stdout', async () => {
+ const f = fixture({shellVersion: MAIN, installFailure: {stderrTail: '',
+  stdout: `Progress: resolved 1\n\u001b[31m[ERR_PNPM_INVALID_VERSION_UNION]\u001b[39m Invalid versions union. Found: "gentle-pi@file:/home/u/x.tgz". Use exact versions only.\nDone\n`}});
+ await assert.rejects(updateSelectedPi(f.input), {message: `gentle-shell update: pnpm (/fake/pnpm) could not install ${f.tarball}\n[ERR_PNPM_INVALID_VERSION_UNION] Invalid versions union. Found: "gentle-pi@file:~/x.tgz". Use exact versions only.`});
+ assert.deepEqual(f.runOptions, [{deadlineMs: 20 * 60_000, cwd: '/neutral', stderrTail: 4096}]);
+ assert.deepEqual(f.out, []);
+});
+
+test('a failed npm install shows its stderr error line before stdout', async () => {
+ const f = fixture({npm: true, installFailure: {stdout: 'unrelated', stderrTail: 'npm error code EACCES\nnpm error Error: EACCES: permission denied\nnpm error A complete log is in /home/u/.npm/x.log\n'}});
+ await assert.rejects(updateSelectedPi(f.input), {message: 'gentle-shell update: npm (/fake/npm) could not install gentle-pi@4.1.0\nnpm error Error: EACCES: permission denied'});
+ assert.deepEqual(f.out, []);
+});
+
+test('a failed install without output keeps the single line, naming the command it ran', async () => {
+ const f = fixture({installFailure: {}});
+ await assert.rejects(updateSelectedPi(f.input), {message: 'gentle-shell update: pnpm (/fake/pnpm) could not install gentle-pi@4.1.0'});
+ assert.deepEqual(f.mutations, [['add', '-g', 'gentle-pi@4.1.0', '--allow-build=gentle-pi']]);
+});
+
+test('a stderr warning never hides the ERR_PNPM line pnpm printed on stdout', async () => {
+ const f = fixture({installFailure: {stderrTail: '(node:1) [DEP0040] DeprecationWarning: The `punycode` module is deprecated.\n',
+  stdout: '[ERR_PNPM_INVALID_VERSION_UNION] Invalid versions union.\n'}});
+ await assert.rejects(updateSelectedPi(f.input), {message: 'gentle-shell update: pnpm (/fake/pnpm) could not install gentle-pi@4.1.0\n[ERR_PNPM_INVALID_VERSION_UNION] Invalid versions union.'});
+});
+
+test('without any error line the last stderr line is shown', async () => {
+ const f = fixture({installFailure: {stderrTail: 'killed\n', stdout: 'Progress: resolved 1\n'}});
+ await assert.rejects(updateSelectedPi(f.input), {message: 'gentle-shell update: pnpm (/fake/pnpm) could not install gentle-pi@4.1.0\nkilled'});
+});

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);
+});