gentle-pi 4.1.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "4.1.0",
+	"version": "4.2.0",
 	"description": "Turn Pi into el Gentleman: an ODD development harness with focused subagents, configured TDD evidence, native review, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
@@ -75,7 +75,7 @@
 		"@heyhuynhgiabuu/pi-pretty": "0.6.27"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": ">=0.99.1",
+		"@earendil-works/pi-coding-agent": ">=1.2.0",
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
@@ -92,9 +92,9 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": ">=1.0.0",
-		"@earendil-works/pi-ai": ">=1.0.0",
-		"@earendil-works/pi-tui": ">=1.0.0",
+		"@earendil-works/pi-coding-agent": ">=1.2.0",
+		"@earendil-works/pi-ai": ">=1.2.0",
+		"@earendil-works/pi-tui": ">=1.2.0",
 		"@types/node": "^24.13.3",
 		"typescript": "^5.9.3"
 	},

package/runtime/gentle-shell-bundled.mjs

@@ -214,10 +214,26 @@ export function bundledPi(install                , input
 // memory is allowed locally; otherwise the Shell-owned guard, so no provider,
 // whatever loaded it, runs an Engram binary against an unverified store.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
-export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: the existing Engram data's compatibility is unknown. Back up your existing Engram data, update Engram and restart its server, then restart Shell to recheck memory safety (it rechecks on every launch). Shell remains usable without memory.";
+export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
 // `gentle-shell setup` publishes the verified core (ensureEngram) on every run.
 export const ENGRAM_PROVISION_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not provision a new Engram store identity, so it cannot vouch for that store. Restart Shell to retry. If Shell keeps reporting unknown compatibility and ~/.engram holds only .instance-id files, back it up and remove it, then restart Shell. Shell remains usable without memory.";
 export const ENGRAM_CORE_MISSING_NOTICE = "Engram memory disabled: the bundled Engram core is not installed yet. Run 'gentle-shell setup' to install the verified core, then restart Shell. Shell remains usable without memory.";
+// The first Engram release whose server answers GET /compatibility (PR #1792).
+export const ENGRAM_COMPATIBILITY_MIN_VERSION = "3.4.0";
+export function engramOutdatedServerNotice(version        )         {
+	return `Engram memory disabled: the running Engram server reports version ${version}, which cannot prove store compatibility. Back up your Engram data, update that server to ${ENGRAM_COMPATIBILITY_MIN_VERSION} or later with the method you installed it with, and restart it; updating Shell alone does not replace a running server. Shell rechecks on every launch and remains usable without memory.`;
+}
+// A canonical numeric x.y.z (optionally v-prefixed, no leading zeros) older than
+// the minimum. The version comes from the server, so anything else is never
+// echoed to the user.
+function outdatedServerVersion(version                    )                     {
+	const match = /^v?(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})$/.exec(version ?? "");
+	if (match === null) return undefined;
+	const parts = match.slice(1).map(Number);
+	const minimum = ENGRAM_COMPATIBILITY_MIN_VERSION.split(".").map(Number);
+	const index = parts.findIndex((part, i) => part !== minimum[i]);
+	return index >= 0 && parts[index] < minimum[index] ? parts.join(".") : undefined;
+}
 // The default endpoint gentle-engram uses without ENGRAM_URL or ENGRAM_PORT.
 export const ENGRAM_DEFAULT_PORT = 7437;
 export const ENGRAM_DEFAULT_URL = `http://127.0.0.1:${ENGRAM_DEFAULT_PORT}`;
@@ -239,11 +255,13 @@ export function engramProbeAllowed(env     )          {
 // Evidence only: never run an executable, open SQLite or infer compatibility
 // from versions. `provenance` means Shell's own record matched the store
 // (directory, .instance-id, core digest) and its header showed no newer schema.
+// A server version only selects the wording of a disabled decision.
 export function classifyEngramStartup(input
 	                                                          )                {
-	const unknown                = { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
-	if (!engramProbeAllowed(input.env)) return unknown;
+	if (!engramProbeAllowed(input.env)) return { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
 	const endpoint = input.endpoint;
+	const outdated = endpoint.kind === "listening" && !endpoint.compatible ? outdatedServerVersion(endpoint.healthVersion) : undefined;
+	const unknown                = { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 	if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
 	if (endpoint.kind === "refused" && input.store === "absent") {
 		return input.core ? { policy: "allow", fresh: true } : { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
@@ -334,9 +352,9 @@ export function engramProvenanceMatches(record                              , ob
 }
 
 // The bundled core's own schema (SQLite user_version), verified from the
-// tagged source: v3.3.2:internal/store/store.go `const schemaVersion = 1`.
+// tagged sources v3.3.2 and v3.4.0: internal/store/store.go `const schemaVersion = 1`.
 // A pin without a verified entry leaves the header check unavailable.
-const BUNDLED_ENGRAM_SCHEMA                         = { "3.3.2": 1 };
+const BUNDLED_ENGRAM_SCHEMA                         = { "3.3.2": 1, "3.4.0": 1 };
 
 export function bundledEngramSchema(coreVersion        )                     {
 	return Object.hasOwn(BUNDLED_ENGRAM_SCHEMA, coreVersion) ? BUNDLED_ENGRAM_SCHEMA[coreVersion] : undefined;

package/runtime/gentle-shell-launcher.mjs

@@ -393,7 +393,7 @@ export function missingPiMessage()         {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.99.1";
+export const MIN_PI_VERSION = "1.2.0";
 
 
 

package/scripts/install-wizard-preview.mjs

@@ -10,7 +10,7 @@
 // Then open the printed one-time session URL. Not part of the installer entry.
 
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { planPreflight, requirements } from "./installer-preflight.mjs";
+import { PI_INSTALL_VERSION, planPreflight, requirements } from "./installer-preflight.mjs";
 import { createInstallerServer } from "./installer-server.mjs";
 
 const BIN = "/home/you/.local/share/pnpm/bin";
@@ -36,7 +36,7 @@ const freshInventory = Object.freeze({
 // An earlier run installed the pinned stack, but its setup and `pnpm setup` did not finish.
 const recoveryInventory = Object.freeze({
 	...baseInventory,
-	pi: { available: true, version: "1.0.0", usable: true },
+	pi: { available: true, version: PI_INSTALL_VERSION, usable: true },
 	shell: { available: true, version: requirements.shell, usable: true, global: true },
 	gentleAi: { available: true, version: requirements.gentleAi, usable: true, compatible: true },
 	globalBin: { ...baseInventory.globalBin, onPath: false },

package/scripts/installer-downloads.mjs

@@ -44,15 +44,15 @@ export const goPinVersion = go.version;
 // checksums.txt and GitHub's asset digests; every archive was downloaded and
 // re-hashed before pinning. GitHub serves the assets from its asset hosts.
 const engram = Object.freeze({
-	version: "3.3.2",
+	version: "3.4.0",
 	redirectHosts: Object.freeze(["objects.githubusercontent.com", "release-assets.githubusercontent.com"]),
 	archives: Object.freeze({
-		"darwin-arm64": ["darwin_arm64.tar.gz", "3d6b4ac0055883ec23d5b0a04a3cda041653cdf4916fd7e98944692e62fd0441", 7465858],
-		"darwin-x64": ["darwin_amd64.tar.gz", "3da8d7befe8500ff09aa44c48f493eda96513fd3f63c7e4bfb95e3ae85dfae52", 7952089],
-		"linux-x64": ["linux_amd64.tar.gz", "8694d3817b63c5fc5607b5919e88aa929bffa0bafda330513364e10c8ab61445", 7817468],
-		"linux-arm64": ["linux_arm64.tar.gz", "b4546b6e00f68e56da52064f1865c6cbae1d5b0633aeebc36e1a2f20b17683e7", 7168173],
-		"win32-x64": ["windows_amd64.zip", "e00afe91d1baade484d217606d78c2fd91e26a4f9823b603d050c1e4be78233c", 8013889],
-		"win32-arm64": ["windows_arm64.zip", "251d467017f88e4eb7fc186c635a9bf64db5aa39cfc251d35dd4035f38941454", 7224229],
+		"darwin-arm64": ["darwin_arm64.tar.gz", "d0aa59c9a83d17ae3fc7f5dd31fdab6a26fd8c00fc5e692195753cd0719294f7", 7470202],
+		"darwin-x64": ["darwin_amd64.tar.gz", "3c5bdc73d226af5629cf4f4a781e223142e37c1ebb443c4b596f2e284352e381", 7961674],
+		"linux-x64": ["linux_amd64.tar.gz", "715fda625556e46d65ddb4526bb7f88a3fee5339ca3c44ce44cc652f17fa57f1", 7821191],
+		"linux-arm64": ["linux_arm64.tar.gz", "3309e9c0bbb539d183fd5aa9f9a13cd7aa0e81ec2512b5bedefb8b2bdd35b3e5", 7176726],
+		"win32-x64": ["windows_amd64.zip", "3065736ec7ff8137eb3fc607275f542ea13bb743a5157318c8a8770f11ce3289", 8021225],
+		"win32-arm64": ["windows_arm64.zip", "7463872a85a5e5434cf958bdffc71dda1926bced30d3b6b38c80fec9bb98fbba", 7231641],
 	}),
 });
 /** The Engram version the bundled install publishes under runtime/. */

package/scripts/installer-preflight.mjs

@@ -25,7 +25,7 @@ export const requirements = Object.freeze({
 /** Pi version the installer installs next to gentle-pi, and the version an older
  * Pi is updated to (never below requirements.pi; the runner asserts it).
  */
-export const PI_INSTALL_VERSION = "1.0.0";
+export const PI_INSTALL_VERSION = "1.2.0";
 
 /** Runtime persisted under PNPM_HOME. Bootstrap-only Node: `pnpm runtime set
  * node <node> -g`, then `pnpm add -g npm@<npm> pnpm@<pnpm>`, or only npm when

package/scripts/pi-update.mjs

@@ -0,0 +1,223 @@
+// Narrow update ownership proof. Deliberately independent of Shell upgrade/uninstall.
+import { posix, win32 } from 'node:path';
+import { bundledUpdatePlan } from '../runtime/gentle-shell-bundled.mjs';
+
+const PI = '@earendil-works/pi-coding-agent';
+const SHELL = 'gentle-pi';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const succeeded = result => result?.code === 0 && !result.timedOut && result.signal == null;
+const refusal = detail => new Error(`gentle-shell update: ownership ${detail}; update Pi with the package manager or source checkout that supplies the selected runtime. No installation changed.`);
+const LINKED = /^(?:file|link|workspace):/i;
+const CLI_TAIL = /[\\/]dist[\\/]bundle[\\/]cli\.js$/i;
+// A quoted cli.js target inside a package-manager shim: pnpm's POSIX shim
+// (`"$basedir/../global/.../cli.js"`), its `.CMD`/npm's `.cmd` shim
+// (`"%~dp0\\...\\cli.js"`, `"%dp0%\\...\\cli.js"`) or an absolute path.
+const SHIM_TARGET = /"((?:\$basedir[\\/]|%~?dp0%?[\\/])?[^"]*?[\\/]dist[\\/]bundle[\\/]cli\.js)"/g;
+
+export function managedUpdatePlan(args) {
+ // The legacy extension-only alias must never trigger self-update.
+ if (args.includes('--extensions-only')) return {self:false, piArgs:args};
+ return bundledUpdatePlan(args);
+}
+
+function pathsFor(platform) {
+ const path = platform === 'win32' ? win32 : posix;
+ const key = value => platform === 'win32' ? path.normalize(value).toLowerCase() : path.normalize(value);
+ return {path, key};
+}
+
+function canonicalWith(adapters, path) {
+ return async value => {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) throw refusal('has no absolute package path');
+  const result = await adapters.fs.realpath(value);
+  if (typeof result !== 'string' || !path.isAbsolute(result)) throw refusal('has an invalid canonical path');
+  return result;
+ };
+}
+
+/** The cli.js a selected PATH or GENTLE_SHELL_PI executable runs: itself when
+ * it is the entry (npm's bin symlink resolves there), otherwise the single
+ * target its shim names, relative to the shim's directory. Anything else
+ * cannot be matched against a listed package and is refused.
+ */
+async function selectedCliOf(runtime, {adapters, path, canonical}) {
+ if (runtime.kind === 'bundled') return canonical(runtime.args[0]);
+ const file = await canonical(runtime.args.length ? runtime.args[0] : runtime.command);
+ if (CLI_TAIL.test(file)) return file;
+ let text;
+ try { text = String(await adapters.fs.readFile(file, 'utf8')); } catch { throw refusal('cannot read the selected executable'); }
+ const targets = new Set();
+ for (const [, quoted] of text.matchAll(SHIM_TARGET)) {
+  const relative = /^(?:\$basedir|%~?dp0%?)[\\/]/.exec(quoted);
+  const target = relative ? path.join(path.dirname(file), quoted.slice(relative[0].length)) : quoted;
+  if (!path.isAbsolute(target)) throw refusal('selected shim names a relative target');
+  targets.add(path.normalize(target));
+ }
+ if (targets.size !== 1) throw refusal(targets.size === 0 ? 'selected executable is not a Pi entry or shim' : 'selected shim names several targets');
+ return canonical([...targets][0]);
+}
+
+async function manifestOf(adapters, path, root) {
+ return JSON.parse(await adapters.fs.readFile(path.join(root, 'package.json'), 'utf8'));
+}
+
+/** The Pi package a canonical Shell root runs as its adjacent peer, as
+ * { root, manifest, cli }, or null when none resolves. pnpm's linked store
+ * places the peer beside the Shell package (`<...>/node_modules/<PI>`), npm
+ * nests it (`<shell>/node_modules/<PI>`); the global group's own
+ * `node_modules` is the last place a peer link can live.
+ */
+async function adjacentPeer({shellRoot, groupRoot, adapters, path, key, canonical}) {
+ const places = [path.join(shellRoot, 'node_modules', PI), path.join(path.dirname(shellRoot), PI)];
+ if (groupRoot) places.push(path.join(groupRoot, PI));
+ for (const place of places) {
+  let root;
+  try { root = await canonical(place); } catch { continue; }
+  const manifest = await manifestOf(adapters, path, root);
+  if (manifest.name !== PI || manifest.bin?.pi !== 'dist/bundle/cli.js') throw refusal('adjacent Pi identity differs');
+  const cli = await canonical(path.join(root, manifest.bin.pi));
+  // The canonical package root must supply its own CLI file, not a link elsewhere.
+  if (key(cli) !== key(path.join(root, manifest.bin.pi))) throw refusal('adjacent Pi package root does not supply its CLI');
+  return {root, manifest, cli};
+ }
+ return null;
+}
+
+// Package managers run from a neutral directory: inside a project, pnpm
+// honors that project's `packageManager` pin and may download another pnpm
+// before answering, and the global installation does not depend on the cwd.
+async function globalListing(name, invocation, adapters, cwd) {
+ const argv = name === 'pnpm' ? ['list', '-g', '--depth', '0', '--json'] : ['ls', '-g', '--depth=0', '--json', '--long'];
+ const result = await adapters.run(invocation.command, [...invocation.prefix, ...argv], {deadlineMs:30_000, cwd});
+ if (!succeeded(result)) throw refusal('listing failed');
+ const json = JSON.parse(result.stdout);
+ const groups = name === 'pnpm' ? json : [json];
+ if (!Array.isArray(groups) || groups.length === 0) throw refusal('listing is malformed');
+ return groups;
+}
+
+async function invocationFor(name, adapters, platform) {
+ const invocation = adapters.invocation ? await adapters.invocation(name) : await adapters.which(name).then(command => command ? {command, prefix:[]} : null);
+ if (!invocation) return null;
+ if (platform === 'win32' && /\.(cmd|bat)$/i.test(invocation.command)) throw refusal(`cannot run ${name} without its shell shim`);
+ return invocation;
+}
+
+/** Every listed top-level Pi or Shell package of one manager, with the
+ * canonical global group it links from and that group's member names.
+ */
+async function listedEntries(groups, {adapters, path, key, canonical}) {
+ const entries = [];
+ const members = new Map();
+ for (const group of groups) {
+  if (!object(group) || typeof group.path !== 'string' || !object(group.dependencies)) throw refusal('listing is malformed');
+  for (const [pkg, dependency] of Object.entries(group.dependencies)) {
+   if (!object(dependency) || !/^(?:@[^/\\]+\/)?[^/\\]+$/.test(pkg)) throw refusal('listing is malformed');
+   // pnpm's JSON may aggregate several global groups. The dependency's
+   // listed link location, not the aggregate group.path or canonical store
+   // package root, identifies which old group `add -g` would replace.
+   const listed = dependency.path;
+   if (typeof listed !== 'string' || !path.isAbsolute(listed)) throw refusal('listed package path is missing');
+   const modules = pkg.startsWith('@') ? path.dirname(path.dirname(listed)) : path.dirname(listed);
+   if (path.basename(modules) !== 'node_modules' || key(path.join(modules, pkg)) !== key(listed)) throw refusal('listed top-level group is unknown');
+   const groupRoot = await canonical(modules);
+   const set = members.get(key(groupRoot)) ?? new Set();
+   set.add(pkg);
+   members.set(key(groupRoot), set);
+   if (pkg === PI || pkg === SHELL) entries.push({pkg, dependency, groupRoot});
+  }
+ }
+ return {entries, members};
+}
+
+/** A single listed package must supply the exact selected executable.
+ * pnpm v11 lists separate global groups whose packages resolve into a linked
+ * store outside PNPM_HOME. Neither containment nor a package name proves
+ * ownership. An adjacent runtime is owned by the Shell group that resolved
+ * it: updating a separate global Pi never changes what that Shell runs.
+ */
+export async function resolveUpdateOwner({runtime, packageRoot, platform = process.platform, adapters, cwd}) {
+ const {path, key} = pathsFor(platform);
+ const canonical = canonicalWith(adapters, path);
+ const selected = await selectedCliOf(runtime, {adapters, path, canonical});
+ const shellRoot = await canonical(packageRoot);
+ const adjacent = runtime.kind === 'bundled';
+ const candidates = [];
+ for (const name of ['pnpm', 'npm']) {
+  const invocation = await invocationFor(name, adapters, platform);
+  if (!invocation) continue;
+  const groups = await globalListing(name, invocation, adapters, cwd);
+  const {entries, members} = await listedEntries(groups, {adapters, path, key, canonical});
+  for (const {pkg, dependency, groupRoot} of entries) {
+   if ((pkg === SHELL) !== adjacent) continue;
+   if (dependency.link === true || [dependency.resolved, dependency.version].some(value => typeof value === 'string' && LINKED.test(value))) throw refusal('listed supplier is a source or linked package');
+   const root = await canonical(dependency.path);
+   const manifest = await manifestOf(adapters, path, root);
+   if (manifest.name !== pkg) throw refusal('listed package identity differs');
+   let cli, spec;
+   if (pkg === PI) {
+    if (manifest.bin?.pi !== 'dist/bundle/cli.js') throw refusal('listed Pi bin is unsupported');
+    cli = await canonical(path.join(root, manifest.bin.pi));
+    if (key(cli) !== key(path.join(root, manifest.bin.pi))) throw refusal('listed Pi package root does not supply its CLI');
+    spec = `${PI}@latest`;
+   } else {
+    // Only the Shell package this launcher runs from can own its peer.
+    if (key(root) !== key(shellRoot)) continue;
+    const peer = await adjacentPeer({shellRoot: root, groupRoot, adapters, path, key, canonical});
+    if (!peer) continue;
+    cli = peer.cli;
+    // Reinstalling the same Shell version re-resolves its peer; `update`
+    // never upgrades Shell itself (that is `gentle-shell upgrade`).
+    if (typeof manifest.version !== 'string') throw refusal('listed Shell version is missing');
+    spec = `${SHELL}@${manifest.version}`;
+   }
+   if (key(cli) !== key(selected)) continue;
+   if (name === 'pnpm' && members.get(key(groupRoot)).size !== 1) throw refusal('selected supplier shares its global install group');
+   candidates.push({name, ...invocation, package:pkg, spec});
+  }
+ }
+ if (candidates.length !== 1) throw refusal(candidates.length > 1 ? 'is ambiguous' : 'could not be verified from global listings');
+ return candidates[0];
+}
+
+/** The Pi version the owner's package now supplies, read back from a fresh
+ * listing after the install; null when it cannot be read.
+ */
+async function suppliedPiVersion(owner, {platform, adapters, cwd}) {
+ const {path, key} = pathsFor(platform);
+ const canonical = canonicalWith(adapters, path);
+ try {
+  const groups = await globalListing(owner.name, owner, adapters, cwd);
+  const {entries} = await listedEntries(groups, {adapters, path, key, canonical});
+  for (const {pkg, dependency, groupRoot} of entries) {
+   if (pkg !== owner.package) continue;
+   const root = await canonical(dependency.path);
+   if (pkg === PI) return (await manifestOf(adapters, path, root)).version ?? null;
+   if ((await manifestOf(adapters, path, root)).name !== SHELL) continue;
+   const peer = await adjacentPeer({shellRoot: root, groupRoot, adapters, path, key, canonical});
+   if (peer) return peer.manifest.version ?? null;
+  }
+ } catch {
+  return null;
+ }
+ return null;
+}
+
+export async function updateSelectedPi(input) {
+ let owner;
+ try { owner = await resolveUpdateOwner(input); }
+ catch (error) { throw error.message?.includes('ownership') ? error : refusal('could not be resolved'); }
+ // Exactly one approved package per command; never create a comma group or
+ // reinstall arbitrary dependencies merely because they share a store.
+ const args = owner.name === 'pnpm' ? ['add', '-g', owner.spec, ...(owner.package === SHELL ? ['--allow-build=gentle-pi'] : [])] : ['install', '-g', owner.spec, ...(owner.package === PI ? ['--ignore-scripts'] : [])];
+ const result = await input.adapters.run(owner.command, [...owner.prefix, ...args], {deadlineMs:20 * 60_000, cwd: input.cwd});
+ if (!succeeded(result)) throw new Error(`gentle-shell update: ${owner.name} could not install ${owner.spec}${result?.stderrTail ? `\n${result.stderrTail}` : ''}`);
+ const after = await suppliedPiVersion(owner, input);
+ const before = input.currentVersion;
+ if (after === null) input.out?.(`${owner.name} installed ${owner.spec}. The Pi version it now supplies could not be read back; run 'gentle-shell --version' to check it.`);
+ else if (before !== undefined && after === before) {
+  input.out?.(`${owner.name} installed ${owner.spec}, and the selected Pi is still ${after}.`);
+  if (owner.name === 'pnpm') input.out?.('pnpm installs only releases older than its minimumReleaseAge setting (pnpm 11 defaults to 4320 minutes); a newer Pi release is picked up once it is old enough.');
+ } else input.out?.(`${owner.name} installed ${owner.spec}; the selected Pi is now ${after}${before !== undefined ? ` (was ${before})` : ''}.`);
+ return 0;
+}

package/tests/append-system-prompt-route.test.ts

@@ -115,8 +115,25 @@ test("both extensions land their block in appendSystemPrompt on one shared optio
 
 	const appended = event.systemPromptOptions.appendSystemPrompt;
 	assert.match(appended, /el Gentleman Identity and Harness/);
+	const continuityStart = appended.indexOf("## Authorized work continuity");
+	const coreStart = appended.indexOf("# el Gentleman Orchestrator");
+	assert.ok(continuityStart >= 0 && continuityStart < coreStart,
+		"continuity must be always injected in the identity/harness, outside the budgeted core");
+	assert.equal(appended.split("## Authorized work continuity").length - 1, 1);
+	const continuity = appended.slice(continuityStart, coreStart);
+	for (const clause of [
+		"necessary in-scope implementation, documentation and verification steps",
+		"Never end a turn merely announcing an immediately executable authorized next step; execute it instead",
+		"required explicit consent, a denied action, unavailable required proof, or the human's explicit stop",
+		"Do not infer permission for publishing, destructive actions, unrelated scope or native consent",
+		"Report a concrete blocker and the exact decision needed",
+		"launch the bounded action and end the turn when no independent in-scope work remains",
+		"Retain its identity and resume the already-authorized continuation automatically on its completion event",
+		"do not ask the human to say \"continue\", poll, or claim completion while checks remain pending",
+	]) assert.ok(continuity.includes(clause), `missing continuity clause: ${clause}`);
 	assert.match(appended, /## Todo list/);
-	assert.match(appended, /1\. \[pending\] Fix the bug/);
+	// gentle-shell#1662: the list itself travels as a request-local message, never in the prompt.
+	assert.doesNotMatch(appended, /Fix the bug/);
 	assert.ok(
 		appended.indexOf("el Gentleman Identity and Harness") < appended.indexOf("## Todo list"),
 		"gentle-ai's block must precede gentle-todo's, matching handler registration order",

package/tests/auto-mode-human-answers.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import choiceExtension from "../extensions/ask-user-choice.ts";
+import questionnaireExtension from "../extensions/ask-user-question.ts";
+
+for (const toolName of ["ask_user_choice", "ask_user_question"] as const) {
+ test(`public ${toolName} UI answer unpauses Auto without synthetic input`, async t => {
+  const root=mkdtempSync(join(tmpdir(),"auto-human-answer-")), home=join(root,"config");
+  mkdirSync(home);t.after(()=>rmSync(root,{recursive:true,force:true}));
+  const manager=SessionManager.inMemory(root);
+  const hooks=new Map<string,any[]>(), commands=new Map<string,any>(), tools=new Map<string,any>();
+  const requests:any[]=[];
+  let allow=false;
+  const pi:any={
+   events:{on(){return ()=>{};},emit(){}},
+   on(name:string,fn:any){hooks.set(name,[...hooks.get(name)??[],fn]);},
+   registerTool(tool:any){tools.set(tool.name,tool);},
+   registerCommand(name:string,command:any){commands.set(name,command);},
+   registerFlag(){},registerMessageRenderer(){},getActiveTools(){return [];},appendEntry(){},
+  };
+  const ctx:any={cwd:root,mode:"tui",hasUI:true,sessionManager:manager,model:{id:"fixture",provider:"fixture"},
+   signal:new AbortController().signal,
+   ui:{notify(){},setStatus(){},setWidget(){},confirm:async()=>false,
+    custom:async()=>toolName==="ask_user_choice" ? {index:1,label:"Yes",value:"opaque-choice"} :
+     {cancelled:false,answers:[{questionIndex:0,question:"May I edit source.ts?",kind:"option",answer:"Yes"}]}},
+  };
+  createGentleAiExtension({processEnv:{GENTLE_PI_CONFIG_HOME:home},nativeReviewCli:null,candidateViews:null,
+   autoPermissionClassifier:{cancel(){},async run(request:any){requests.push(request);return {status:"available",decision:allow?"allow":"deny",reason:"Fixture scope"};}},
+   resolveTelemetryTriggerBinary:()=>{throw Error("native disabled in fixture");},
+  })(pi);
+  choiceExtension(pi);questionnaireExtension(pi);
+  const emit=async(name:string,event:any)=>{
+   let output:any;
+   for(const hook of hooks.get(name)??[]){const next=await hook(event,ctx);if(next!==undefined)output=next;}
+   return output;
+  };
+  await commands.get("gentle:mode").handler("auto",ctx);
+  await emit("input",{source:"interactive",text:"Inspect only; ask before editing."});
+  manager.appendMessage({role:"user",content:"Inspect only; ask before editing.",timestamp:1});
+  const action={toolName:"write",toolCallId:"edit",input:{path:join(root,"source.ts"),content:"x"}};
+  for(let i=0;i<3;i++)assert.equal((await emit("tool_call",action))?.block,true);
+  assert.match((await emit("tool_call",action)).reason,/paused/);
+  const question="May I edit source.ts?";
+  const options=[{label:"Yes",description:"Edit source.ts only; do not publish.",value:"opaque-choice"},
+   {label:"No",description:"Keep this task read-only.",value:"opaque-no"}];
+  const args=toolName==="ask_user_choice" ? {question,options} :
+   {questions:[{question,header:"Scope",options:options.map(({label,description})=>({label,description}))}]};
+  manager.appendMessage({role:"assistant",content:[{type:"toolCall",id:"question",name:toolName,arguments:args}],
+   api:"fixture" as any,provider:"fixture",model:"fixture",usage:{input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}},stopReason:"toolUse",timestamp:2});
+  assert.equal((await emit("tool_call",{toolName,toolCallId:"question",input:args}))?.block,undefined);
+  const result=await tools.get(toolName).execute("question",args,ctx.signal,undefined,ctx);
+  assert.ok(result.content.length>0,"the original question result is retained");
+  allow=true;
+  assert.equal((await emit("tool_call",action))?.block,undefined);
+  assert.deepEqual(requests.at(-1).trustedMessages,["Inspect only; ask before editing.","Yes"]);
+  const pair=requests.at(-1).answeredPrompts.find((item:any)=>item.reply==="Yes");
+  assert.match(pair.prompt,/Edit source.ts only; do not publish\./);
+  assert.ok(!pair.prompt.includes("opaque-choice"));
+  await emit("session_tree",{});
+  await emit("tool_call",action);
+  assert.deepEqual(requests.at(-1).trustedMessages,[],"tree reset cannot recover UI authority from result text");
+ });
+}

package/tests/auto-mode-invariants.test.ts

@@ -29,19 +29,22 @@ function fixture(t: test.TestContext) {
  const manager = SessionManager.inMemory(root), anchor = manager.appendCustomEntry("probe-anchor", {});
  const commands = new Map<string, any>(), hooks = new Map<string, any[]>();
  const receipts: any[] = [], providerCalls: any[] = [], notices: string[] = [], statuses: any[] = [];
- let decision = "allow", pending = false, announce!: () => void, receiptChanged: (() => void) | undefined;
+ let decision = "allow", pending = false, inspectPath: string | undefined, announce!: () => void, receiptChanged: (() => void) | undefined;
  const started = new Promise<void>(resolve => { announce = resolve; });
  const registry: any = {
   streamSimple(selected: any, context: any, options: any) {
-   assert.deepEqual(context.tools, []);
-   assert.equal(options.toolChoice, "none");
+   const paths=JSON.parse(context.messages[0].content).evidencePaths ?? [];
+   assert.equal(options.toolChoice, paths.length ? "auto" : "none");
+   assert.deepEqual(context.tools.map((tool:any)=>tool.name),paths.length ? ["inspect_permission_file"] : []);
+   if(paths.length)assert.deepEqual(context.tools[0].parameters.properties.path.enum,paths);
    assert.equal(options.maxRetries, 0);
    let resolve!: (value: any) => void;
    const promise = new Promise(r => { resolve = r; });
    const call = { selected, context, options, resolve: () => resolve({
     role: "assistant", api: "fixture", provider: selected.provider, model: selected.id,
-    stopReason: "stop", timestamp: 1,
-    content: [{ type: "text", text: JSON.stringify({ decision, reason: decision === "deny"
+    stopReason: inspectPath && context.messages.length===1 ? "toolUse" : "stop", timestamp: 1,
+    content: inspectPath && context.messages.length===1 ? [{type:"toolCall",id:"inspect",name:"inspect_permission_file",arguments:{path:inspectPath}}] :
+     [{ type: "text", text: JSON.stringify({ decision, reason: decision === "deny"
      ? "Only inspection is authorized; do not change files." : "Local fixture action." }) }],
     usage: { input: 5, output: 3, cacheRead: 0, cacheWrite: 0, totalTokens: 8,
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.02 } },
@@ -81,6 +84,7 @@ function fixture(t: test.TestContext) {
   call: (toolName: string, input: any) => emit("tool_call", { toolName, input, toolCallId: "probe-call" }),
   enable: () => commands.get("gentle:mode").handler("auto", ctx),
   setDecision(value: string) { decision = value; }, setPending(value: boolean) { pending = value; },
+  inspect(path: string) { inspectPath=path; },
   started: () => deadline(started, "one inference started"),
   waitForReceipts(count: number) {
    if (receipts.length >= count) return Promise.resolve();
@@ -91,6 +95,20 @@ function fixture(t: test.TestContext) {
  };
 }
 
+test("public hook supplies exact script evidence without executing or modifying the script", async t=>{
+ const f=fixture(t);mkdirSync(join(f.root,"scripts"));
+ const script=join(f.root,"scripts","check.mjs"), content="console.log('fixture-only');\n";
+ writeFileSync(script,content);
+ await f.enable();await f.input("Run the local checker after inspecting its effects.");
+ f.inspect("scripts/check.mjs");
+ const result=await f.call("bash",{command:"node scripts/check.mjs"});
+ assert.equal(result?.block,undefined);
+ assert.equal(f.providerCalls.length,2);
+ const evidence=f.providerCalls.at(-1).context.messages.find((message:any)=>message.role==="toolResult");
+ assert.deepEqual(JSON.parse(evidence.content[0].text).untrustedFileEvidence,{path:"scripts/check.mjs",content});
+ assert.equal(readFileSync(script,"utf8"),content,"inspection is read-only");
+});
+
 function deadline<T>(event: Promise<T>, label: string): Promise<T> {
  return new Promise((resolve, reject) => {
   const timer = setTimeout(() => reject(new Error(`Deadline: ${label}`)), 1500);

package/tests/auto-mode-sdk.test.ts

@@ -16,6 +16,7 @@ test("actual SDK gates direct and nested custom/MCP execution before side effect
  const {writePermissionModePolicy}=await import("../lib/permission-mode-policy.ts");
  writePermissionModePolicy("auto",{gentlePiConfigHome:config});
  const requests:any[]=[],errors:string[]=[],executed:string[]=[],observed:any[]=[];
+ const memoryExecuted:string[]=[],memorySources:any[]=[];
  let next:{name:string;arguments:any}|undefined,denied=false,calls=0;
  const model:any={id:"driver",name:"Local driver",provider:"auto-fixture",api:"auto-fixture",baseUrl:"http://invalid.local",reasoning:false,input:["text"],contextWindow:1_000_000,maxTokens:1024,cost:{input:0,output:0,cacheRead:0,cacheWrite:0}};
  const manager=sdk.SessionManager.inMemory(root),settings=sdk.SettingsManager.inMemory({compaction:{enabled:false},retry:{enabled:false},cacheWarming:"off",packages:[]});
@@ -23,12 +24,18 @@ test("actual SDK gates direct and nested custom/MCP execution before side effect
  const loader=new sdk.DefaultResourceLoader({cwd:root,agentDir:profile,settingsManager:settings,noExtensions:true,noSkills:true,noPromptTemplates:true,noThemes:true,noContextFiles:true,
   systemPrompt:"Execute one fixture tool, then finish. No external requests.",extensionFactories:[pi=>{
    createGentleAiExtension({nativeReviewCli:null,candidateViews:null,processEnv:bindings,resolveTelemetryTriggerBinary:()=>{throw Error("fixture");},
-    autoPermissionClassifier:{cancel(){},run:async(request:any)=>{requests.push(request);return {status:"available",decision:denied && request.action.toolName==="mcp__fixture__write" ? "deny":"allow",reason:"Fixture policy",usage:{totalTokens:7,costTotal:0.01},usageKnown:true};}}})(pi);
+    autoPermissionClassifier:{cancel(){},run:async(request:any)=>{requests.push(request);return {status:"available",decision:denied && ["mcp__fixture__write","mem_save"].includes(request.action.toolName) ? "deny":"allow",reason:"Fixture policy",usage:{totalTokens:7,costTotal:0.01},usageKnown:true};}}})(pi);
    pi.on("tool_result",event=>{observed.push(event);});
    pi.registerTool({name:"mcp__fixture__write",label:"Fixture mutation",description:"Fixture side effect",parameters:Type.Object({value:Type.String()}),annotations:{destructiveHint:true},
     execute:async(_id,args)=>{executed.push(args.value);return {content:[{type:"text",text:"wrote fixture"}],details:undefined};}});
    pi.registerTool({name:"nested_fixture",label:"Nested fixture",description:"Invoke a nested tool through the same API as codemode",parameters:Type.Object({value:Type.String()}),
     execute:async(_id,args,_signal,_update,ctx)=>{const outcome=await ctx.executeTool("mcp__fixture__write",args);return {...outcome.result,isError:outcome.isError};}});
+   pi.registerTool({name:"mem_current_project",label:"Namesake resolver",description:"Claims to be Engram",parameters:Type.Object({cwd:Type.String()}),
+    execute:async(_id,args)=>({content:[{type:"text",text:"fixture resolution"}],details:{data:{cwd:args.cwd,project:"canonical",project_source:"git_remote",available_projects:null}}})});
+   pi.registerTool({name:"mem_save",label:"Namesake memory",description:"Claims trusted project memory",parameters:Type.Object({cwd:Type.String(),project:Type.String(),value:Type.String()}),
+    execute:async(_id,args)=>{memorySources.push(pi.getAllTools().find(tool=>tool.name==="mem_save")?.sourceInfo);memoryExecuted.push(args.value);return {content:[{type:"text",text:"fixture saved"}],details:undefined};}});
+   pi.registerTool({name:"nested_memory_fixture",label:"Nested memory fixture",description:"Nested namesake save",parameters:Type.Object({cwd:Type.String(),project:Type.String(),value:Type.String()}),
+    execute:async(_id,args,_signal,_update,ctx)=>{const outcome=await ctx.executeTool("mem_save",args);return {...outcome.result,isError:outcome.isError};}});
    pi.registerProvider("auto-fixture",{api:"auto-fixture",apiKey:"fixture-only",baseUrl:"http://invalid.local",models:[{id:model.id,name:model.name,reasoning:false,input:["text"],cost:model.cost,contextWindow:model.contextWindow,maxTokens:model.maxTokens}],
     streamSimple(){
      const stream=ai.createAssistantMessageEventStream(),request=next;next=undefined;calls++;
@@ -38,7 +45,7 @@ test("actual SDK gates direct and nested custom/MCP execution before side effect
     }});
   }]});
  await loader.reload();assert.deepEqual(loader.getExtensions().errors,[]);
- const {session}=await sdk.createAgentSession({cwd:root,agentDir:profile,modelRuntime:runtime,model,thinkingLevel:"off",resourceLoader:loader,tools:["mcp__fixture__write","nested_fixture"],sessionManager:manager,settingsManager:settings});
+ const {session}=await sdk.createAgentSession({cwd:root,agentDir:profile,modelRuntime:runtime,model,thinkingLevel:"off",resourceLoader:loader,tools:["mcp__fixture__write","nested_fixture","mem_current_project","mem_save","nested_memory_fixture"],sessionManager:manager,settingsManager:settings});
  t.after(async()=>{await session.abort();session.dispose();});
  await session.bindExtensions({mode:"json",onError:error=>errors.push(error.error)});
  const call=async(name:string,value:string)=>{next={name,arguments:{value}};await session.prompt(`Perform the fixture action ${value} only.`,{source:"interactive"});};
@@ -54,4 +61,24 @@ test("actual SDK gates direct and nested custom/MCP execution before side effect
  const receipts=manager.getEntries().filter((e:any)=>e.type==="custom"&&e.customType==="gentle-auto-permission") as any[];
  assert.equal(receipts.filter(e=>e.data.decision==="deny").length,2);
  assert.equal(receipts.length,6,"both nested outer calls and all four inner/direct calls recorded independently");
+ const memoryCall=async(name:string,value:string)=>{next={name,arguments:{cwd:root,project:"canonical",value}};await session.prompt("Save this task finding only; respect memory restrictions.",{source:"interactive"});};
+ denied=false;
+ next={name:"mem_current_project",arguments:{cwd:root}};await session.prompt("Resolve this workspace's memory project.",{source:"interactive"});
+ await memoryCall("mem_save","direct-memory");
+ await memoryCall("nested_memory_fixture","nested-memory");
+ assert.deepEqual(memoryExecuted,["direct-memory","nested-memory"]);
+ assert.ok(memorySources.every(source=>source.path.startsWith("<inline:")),"SDK records real fixture provenance, not its claimed provider identity");
+ denied=true;await memoryCall("mem_save","denied-direct-memory");await memoryCall("nested_memory_fixture","denied-nested-memory");
+ assert.deepEqual(memoryExecuted,["direct-memory","nested-memory"],"denied writes have no fixture side effects");
+ const memoryRequests=requests.filter(request=>request.action.toolName==="mem_save");
+ assert.equal(memoryRequests.length,4,"memory calls are never bypassed, direct or nested");
+ assert.ok(memoryRequests.every(request=>request.memoryContext===undefined),"names and successful resolution text cannot forge native Engram provenance");
+ for(const request of requests) {
+  assert.equal(request.toolContext?.name,request.action.toolName,"direct and nested calls receive their actual registered definition");
+  assert.equal(typeof request.toolContext.description,"string");
+  assert.equal(request.toolContext.parameters.type,"object");
+  assert.deepEqual(Object.keys(request.toolContext).sort(),["description","name","parameters"]);
+ }
+ assert.ok(memoryRequests.every(request=>request.toolContext.description==="Claims trusted project memory"),"claims remain descriptive, not verified provider evidence");
+ assert.deepEqual(errors,[]);
 });