gentle-pi 4.0.0 → 4.2.0

package/tests/permission-mode-policy.test.ts

@@ -0,0 +1,194 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, readFileSync, statSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import fsPromises from "node:fs/promises";
+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";
+
+function fixture(t: test.TestContext) {
+ const home = mkdtempSync(join(tmpdir(), "gentle-mode-"));
+ t.after(() => rmSync(home, { recursive: true, force: true }));
+ return { gentlePiConfigHome: home };
+}
+function host(home: string, env: NodeJS.ProcessEnv = {}, onChange?: () => void) {
+ const commands = new Map<string, { handler(args: string, context: ExtensionContext): Promise<void> }>();
+ const listeners = new Map<string, (value: unknown) => void>();
+ const notices: string[] = [];
+ const statuses = new Map<string, string | undefined>();
+ let sessionId = "first";
+ const context = { cwd: home, mode: "tui", hasUI: true,
+  sessionManager: { getSessionId: () => sessionId },
+  ui: { notify: (s: string) => notices.push(s), setStatus: (k: string, s?: string) => statuses.set(k, s), setWidget() {} },
+ } as unknown as ExtensionContext;
+ const pi = { registerCommand: (n: string, c: { handler(args: string, context: ExtensionContext): Promise<void> }) => commands.set(n, c),
+  events: { on: (n: string, fn: (value: unknown) => void) => listeners.set(n, fn), emit: (n: string, v: unknown) => listeners.get(n)?.(v) },
+ } as unknown as ExtensionAPI;
+ const controller = registerYoloSessionPolicy(pi, { ...env, GENTLE_PI_CONFIG_HOME: home }, { onChange });
+ return { controller, context, pi, commands, notices, statuses, next: () => { sessionId = "next"; } };
+}
+
+test("superseded YOLO enables stay silent while genuine activation failure warns", async t => {
+ const options = fixture(t), h = host(options.gentlePiConfigHome);
+ const original = fsPromises.realpath;
+ const captures: Array<{ release(): void }> = [];
+ let captured!: () => void;
+ const firstCaptured = new Promise<void>(resolve => { captured = resolve; });
+ t.mock.method(fsPromises, "realpath", async (path: string) => {
+  await new Promise<void>(resolve => { captures.push({ release: resolve }); captured(); });
+  return original(path);
+ });
+ syncBuiltinESMExports();
+ t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+ const older = h.controller.humanAction("on", h.context);
+ await firstCaptured;
+ const newer = h.controller.humanAction("on", h.context);
+ assert.equal(captures.length, 2);
+ captures[1].release(); await newer;
+ captures[0].release(); await older;
+ assert.deepEqual(h.notices, ["🚀 YOLO ON 🔥 — destructive confirmations remain"]);
+ t.mock.restoreAll(); syncBuiltinESMExports();
+ assert.equal(await h.controller.mode(h.context), "yolo");
+ Object.assign(h.context, { hasUI: false, mode: "json" });
+ await h.controller.humanAction("on", h.context);
+ assert.deepEqual(h.notices, ["🚀 YOLO ON 🔥 — destructive confirmations remain",
+  "YOLO OFF — activation requires an interactive primary TUI session and an identifiable workspace."]);
+});
+
+test("strict global policy defaults Normal; round trips all modes atomically and privately", t => {
+ const options = fixture(t);
+ assert.equal(resolvePermissionModePolicy(options).mode, "normal");
+ for (const mode of ["normal", "auto", "yolo"] as const) {
+  const path = writePermissionModePolicy(mode, options);
+  assert.equal(path, permissionModePolicyFile(options));
+  assert.equal(resolvePermissionModePolicy(options).mode, mode);
+  assert.equal(statSync(path).mode & 0o777, 0o600);
+  assert.deepEqual(readdirSync(options.gentlePiConfigHome), ["permission-mode.json"]);
+  assert.equal(parsePermissionModePolicyFile(readFileSync(path, "utf8")), mode);
+ }
+});
+
+test("malformed, extra-field, invalid and unreadable preferences fail Normal and refuse overwrite", t => {
+ const options = fixture(t);
+ for (const raw of ["{", "null", "[]", JSON.stringify({ schema: PERMISSION_MODE_SCHEMA, mode: "AUTO" }), JSON.stringify({ schema: PERMISSION_MODE_SCHEMA, mode: "yolo", extra: true })]) {
+  writeFileSync(permissionModePolicyFile(options), raw);
+  assert.equal(resolvePermissionModePolicy(options).mode, "normal");
+  assert.equal(resolvePermissionModePolicy(options).malformed, true);
+  assert.throws(() => writePermissionModePolicy("auto", options));
+  assert.equal(readFileSync(permissionModePolicyFile(options), "utf8"), raw);
+ }
+ assert.throws(() => writePermissionModePolicy("invalid" as "normal", options));
+ assert.equal(resolvePermissionModePolicy({ gentlePiConfigHome: permissionModePolicyFile(options) }).mode, "normal");
+});
+
+test("non-Git primary uses exclusive live modes; saved defaults affect fresh sessions only", async t => {
+ const options = fixture(t), h = host(options.gentlePiConfigHome);
+ assert.equal(await h.controller.mode(h.context), "normal");
+ assert.equal(await h.controller.saveDefault("auto", h.context), true);
+ assert.match(h.notices.at(-1)!, /additional model calls.*separate usage/i);
+ assert.equal(await h.controller.mode(h.context), "normal");
+ assert.equal(await h.controller.setMode("yolo", h.context), true);
+ assert.equal(await h.controller.active(h.context), true);
+ assert.equal(await h.controller.setMode("auto", h.context), true);
+ assert.equal(await h.controller.active(h.context), false);
+ assert.match(h.statuses.get("gentle:mode")!, /AUTO/);
+ assert.equal(await h.controller.setMode("normal", h.context), true);
+ assert.equal(await h.controller.mode(h.context), "normal");
+ h.next(); h.controller.reset(h.context);
+ assert.equal(await h.controller.mode(h.context), "auto");
+ h.controller.reset(h.context);
+ assert.equal(await h.controller.mode(h.context), "normal", "same-session revocation does not replay defaults");
+ const fresh = host(options.gentlePiConfigHome);
+ assert.equal(await fresh.controller.mode(fresh.context), "auto");
+ assert.equal(fresh.notices.length, 0, "saved preference does not repeatedly prompt");
+});
+
+test("trusted defaults support headless primary but never children or headless mutation", async t => {
+ const options = fixture(t);
+ writePermissionModePolicy("yolo", options);
+ const h = host(options.gentlePiConfigHome);
+ Object.assign(h.context, { hasUI: false, mode: "json" });
+ assert.equal(await h.controller.mode(h.context), "yolo");
+ assert.equal(await h.controller.setMode("auto", h.context), false);
+ assert.equal(await h.controller.saveDefault("normal", h.context), false);
+ assert.equal(h.controller.defaultMode(), "yolo");
+ const child = host(options.gentlePiConfigHome, { GENTLE_PI_AGENTS_CHILD: "1" });
+ assert.equal(await child.controller.mode(child.context), "normal");
+ assert.equal(await child.controller.saveDefault("auto", child.context), false);
+});
+
+test("slash and optional adapter operations share mode state; invalid arguments do not mutate", async t => {
+ const options = fixture(t), h = host(options.gentlePiConfigHome);
+ const command = h.commands.get("gentle:mode"); assert.ok(command);
+ await command.handler("auto", h.context);
+ assert.equal(await h.controller.mode(h.context), "auto");
+ await command.handler("default yolo", h.context);
+ assert.equal(h.controller.defaultMode(), "yolo");
+ assert.equal(await h.controller.mode(h.context), "auto");
+ await command.handler("invalid", h.context);
+ assert.equal(await h.controller.mode(h.context), "auto");
+ const adapter = await discoverYoloUiAdapter(h.pi, h.context); assert.ok(adapter);
+ assert.equal(await adapter.readMode!(), "auto");
+ assert.equal(await adapter.setMode!("normal"), true);
+ assert.equal(await adapter.read(), "OFF");
+ await adapter.toggle(); assert.equal(await adapter.read(), "ON");
+ const epoch = h.controller.epoch();
+ h.next();
+ assert.equal(await adapter.setMode!("auto"), false);
+ assert.equal(await adapter.saveDefault!("normal"), false);
+ assert.equal(await adapter.read(), "UNAVAILABLE");
+ h.controller.reset(h.context); assert.ok(h.controller.epoch() > epoch);
+ adapter.dispose();
+});
+
+test("disposing the UI adapter during pending activation discards its mode choice", async t => {
+ const options = fixture(t), h = host(options.gentlePiConfigHome);
+ const adapter = await discoverYoloUiAdapter(h.pi, h.context); assert.ok(adapter);
+ const pending = adapter.setMode!("auto");
+ adapter.dispose();
+ assert.equal(await pending, false);
+ assert.equal(await h.controller.mode(h.context), "normal");
+});
+
+test("reset during initial default capture revokes without replaying that session default", async t => {
+ const options = fixture(t);
+ writePermissionModePolicy("auto", options);
+ const h = host(options.gentlePiConfigHome);
+ const pending = h.controller.mode(h.context);
+ h.controller.reset(h.context);
+ assert.equal(await pending, "normal");
+ assert.equal(await h.controller.mode(h.context), "normal");
+});
+
+test("a concurrent mode switch during default-save initialization discards the stale save", async t => {
+ const options = fixture(t);
+ let once = true;
+ let superseding: Promise<boolean> | undefined;
+ const h = host(options.gentlePiConfigHome, {}, () => {
+  if (!once) return;
+  once = false;
+  superseding = h.controller.setMode("normal", h.context);
+ });
+ assert.equal(await h.controller.saveDefault("yolo", h.context), false);
+ await superseding;
+ assert.equal(h.controller.defaultMode(), "normal");
+});
+
+test("stale pending activation, scope loss and malformed preference remain closed", async t => {
+ const options = fixture(t), h = host(options.gentlePiConfigHome);
+ const pending = h.controller.setMode("auto", h.context);
+ h.controller.reset(h.context);
+ assert.equal(await pending, false);
+ assert.equal(await h.controller.mode(h.context), "normal");
+ assert.equal(await h.controller.setMode("auto", h.context), true);
+ Object.assign(h.context, { cwd: "/" });
+ assert.equal(await h.controller.mode(h.context), "normal");
+ Object.assign(h.context, { cwd: options.gentlePiConfigHome });
+ assert.equal(await h.controller.mode(h.context), "normal", "revoked modes do not resurrect");
+ writeFileSync(permissionModePolicyFile(options), "{");
+ assert.equal(await h.controller.saveDefault("yolo", h.context), false);
+ assert.equal(readFileSync(permissionModePolicyFile(options), "utf8"), "{");
+});

package/tests/persona-single-channel.test.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { __testing } from "../extensions/gentle-ai.ts";
+import { readDelegationDetail } from "./support/orchestrator-modules.ts";
 
 // ---------------------------------------------------------------------------
 // persona-single-channel migration test
@@ -328,10 +329,7 @@ test("Table B rule: LB2 subagent-English delegation kept verbatim in orchestrato
 	// assets/orchestrator-delegation.md (delegation-scoped rule); the always-on
 	// combined injection now only carries a pointer to it. Union read so this
 	// assertion is repointed, not weakened.
-	const delegationDetail = readFileSync(
-		fileURLToPath(new URL("../assets/orchestrator-delegation.md", import.meta.url)),
-		"utf8",
-	);
+	const delegationDetail = readDelegationDetail();
 	for (const persona of ["gentleman", "neutral"] as const) {
 		const prompt = __testing.buildGentlePrompt(persona) + delegationDetail;
 		assert.match(
@@ -369,10 +367,7 @@ test("Table B rule: LB5 exceptions kept verbatim in orchestrator (unique)", () =
 	// assets/orchestrator-delegation.md (delegation-scoped exceptions); the
 	// always-on combined injection now only carries a pointer to it. Union
 	// read so this assertion is repointed, not weakened.
-	const delegationDetail = readFileSync(
-		fileURLToPath(new URL("../assets/orchestrator-delegation.md", import.meta.url)),
-		"utf8",
-	);
+	const delegationDetail = readDelegationDetail();
 	for (const persona of ["gentleman", "neutral"] as const) {
 		const prompt = __testing.buildGentlePrompt(persona) + delegationDetail;
 		assert.match(
@@ -456,10 +451,7 @@ test("dup guard (exact-string): LB2/LB3/LB4 each occur exactly once", () => {
 	// the always-on combined injection by design — see "No Double-Delivery").
 	// LB3/LB4 stay verbatim in the always-on core. Union read for LB2 so the
 	// "exactly once" guard is repointed to its new home, not weakened.
-	const delegationDetail = readFileSync(
-		fileURLToPath(new URL("../assets/orchestrator-delegation.md", import.meta.url)),
-		"utf8",
-	);
+	const delegationDetail = readDelegationDetail();
 	const lb2 =
 		"Subagent-facing prompts should be written in English by default, even when the user speaks Spanish.";
 	const lb3 =

package/tests/pi-pretty.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import pretty from "../extensions/pi-pretty.ts";
+import { setBundledInstallForTesting } from "../lib/gentle-shell-bundled.ts";
 
 test("bundled pretty cannot replace or restore an editor owned by the host", async () => {
 	const handlers = new Map<string, Function[]>();
@@ -42,9 +43,64 @@ test("bundled pretty cannot replace or restore an editor owned by the host", asy
 	assert.equal(message, undefined);
 });
 
+test("bundled pretty keeps Pi's native Working row inside Herdr", async () => {
+	const handlers = new Map<string, Function[]>();
+	const pi = { on(name: string, handler: Function) { handlers.set(name, [...(handlers.get(name) ?? []), handler]); } };
+	let visible: boolean | undefined;
+	const ctx = { mode: "tui", ui: { setWorkingVisible(value: boolean) { visible = value; } } };
+	await pretty(pi, undefined, async () => {}, { HERDR_ENV: "1" });
+	for (const handler of handlers.get("session_start") ?? []) await handler({}, ctx);
+	assert.notEqual(visible, false, "Herdr's native Pi detection reads the standard Working row");
+});
+
 test("disabled shell leaves bundled editor behavior untouched", async () => {
 	let received: unknown;
 	const pi = {};
 	await pretty(pi, undefined, async (api: unknown) => { received = api; }, { GENTLE_PI_SHELL: "0" });
 	assert.equal(received, pi);
 });
+
+// gentle-shell#1690: a delegated child has no shell (shellEnabled is false),
+// so the upstream fallback would start FFF indexing in every child.
+test("delegated children never load upstream pi-pretty", async () => {
+	let loaded = false;
+	const pi = {};
+	const result = await pretty(pi, undefined, async () => { loaded = true; }, { GENTLE_PI_AGENTS_CHILD: "1" });
+	assert.equal(loaded, false);
+	assert.equal(result, undefined);
+});
+
+// S9: outside a bundled install Pi's deps reach pi-pretty unchanged, so its
+// FFF store stays where it always was ($HOME/.pi/agent, or none without HOME).
+test("outside a bundled install pi-pretty gets Pi's deps unchanged", async () => {
+	const given = { TextComponent: "text" };
+	for (const env of [{}, { PI_CODING_AGENT_DIR: "/agent-home" }, { PI_CODING_AGENT_DIR: "/agent-home", GENTLE_PI_SHELL: "0" }, { GENTLE_SHELL_PREFIX: "/not-ours" }]) {
+		for (const deps of [undefined, given]) {
+			let received: unknown = "unset";
+			await pretty({ on() {} }, deps, async (_api: unknown, forwarded: unknown) => { received = forwarded; }, env);
+			assert.equal(received, deps, JSON.stringify(env));
+		}
+	}
+});
+
+// In a bundled install the FFF store follows the agent home. The testing
+// overlay stands in for this package running from a prefix; the current
+// folder serves as one because the prefix must exist.
+test("in a bundled install pi-pretty gets the agent home and Pi's tool factories through deps.sdk", async (t) => {
+	setBundledInstallForTesting({ root: process.cwd() });
+	t.after(() => setBundledInstallForTesting(undefined));
+	const factories = ["createReadToolDefinition", "createBashToolDefinition", "createLsToolDefinition", "createFindToolDefinition", "createGrepToolDefinition"];
+	const bundledEnv = { GENTLE_SHELL_PREFIX: process.cwd(), PI_CODING_AGENT_DIR: "/agent-home" };
+	for (const env of [bundledEnv, { ...bundledEnv, GENTLE_PI_SHELL: "0" }]) {
+		let received: any;
+		await pretty({ on() {} }, { TextComponent: "text" }, async (_api: unknown, deps: unknown) => { received = deps; }, env);
+		assert.equal(received.TextComponent, "text", "the host's other deps are kept");
+		assert.equal(received.sdk.getAgentDir(), "/agent-home");
+		for (const name of factories) assert.equal(typeof received.sdk[name], "function", name);
+	}
+	// A host that already passes its own sdk keeps it.
+	const sdk = { getAgentDir: () => "/host" };
+	let kept: any;
+	await pretty({ on() {} }, { sdk }, async (_api: unknown, deps: unknown) => { kept = deps; }, bundledEnv);
+	assert.equal(kept.sdk, sdk);
+});

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

@@ -0,0 +1,87 @@
+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') {
+ 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: "1.2.0" }; /*').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/);
+});
+
+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/provider-defect-handoff.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import test from "node:test";
+import { readDelegationDetail } from "./support/orchestrator-modules.ts";
 
 // ---------------------------------------------------------------------------
 // Provider Defect Handoff — structural readback tests (issue #256, track 5)
@@ -16,8 +17,8 @@ import test from "node:test";
 // ---------------------------------------------------------------------------
 
 const REPO_ROOT = join(import.meta.dirname, "..");
-const DELEGATION_PATH = join(REPO_ROOT, "assets", "orchestrator-delegation.md");
-const DELEGATION = readFileSync(DELEGATION_PATH, "utf8");
+// gentle-shell#1494: the handoff now lives in assets/orchestrator-prompts.md; the union keeps it pinned.
+const DELEGATION = readDelegationDetail();
 
 const CHOICE_TOKENS = ["report_and_continue", "continue_without_reporting", "stop_here"] as const;
 
@@ -92,7 +93,7 @@ test("orchestrator-delegation.md states the admissibility-before-relay rule", ()
 });
 
 test("orchestrator-delegation.md excludes local consent lifecycle outcomes from provider-defect reporting", () => {
-	assert.match(DELEGATION, /`consent-binding-expired` and `consent-binding-already-consumed` are local lifecycle outcomes, not Gentle AI provider defects/i);
+	assert.match(DELEGATION, /Pending consent has no response deadline\. `consent-binding-already-consumed` is a local lifecycle outcome, not a Gentle AI provider defect/i);
 	assert.match(DELEGATION, /An unknown consent binding is reportable only when independent evidence proves a fresh, same-session, unconsumed binding was lost/i);
 	assert.match(DELEGATION, /Never infer that evidence from the old combined stale-binding message/i);
 });