gentle-pi 4.1.0 → 4.3.0

package/scripts/bundled-engram-migration.mjs

@@ -0,0 +1,125 @@
+// Explicit bundled-store recovery. The provider owns catalog validation and
+// migration; Shell owns promotion and its core-bound provenance. Never called
+// from ordinary startup or upgrade.
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { engramProbeAllowed, engramProvenancePath, parseEngramProvenance } from "../runtime/gentle-shell-bundled.mjs";
+
+export const MIGRATION_USAGE = "Usage: gentle-shell memory migrate --confirm-quiescent\nStop every Engram client before running this command.\n";
+export const MIGRATION_PENDING_NOTICE = "Engram memory disabled: an incomplete memory migration needs recovery. Keep every Engram client stopped, retain the original backup, and follow docs/bundled-install.md#recovering-an-interrupted-migration. Do not remove the migration marker or create a new store before recovery.";
+export const migrationMarkerPath = (prefix) => join(prefix, "config", "engram-migration.json");
+export function migrationPending(prefix) {
+	try { lstatSync(migrationMarkerPath(prefix)); return true; }
+	catch (error) { return error.code !== "ENOENT"; }
+}
+function regularText(path, limit) {
+	const info = lstatSync(path);
+	if (!info.isFile() || info.size > limit) throw new Error("unsafe migration metadata");
+	return readFileSync(path, "utf8");
+}
+const digest = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+// Durably record a file or a directory entry change. Windows cannot open a
+// directory for fsync; there NTFS metadata journaling covers the renames.
+function syncPath(path, directory = false) {
+	if (directory && process.platform === "win32") return;
+	const fd = openSync(path, "r");
+	try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+function coreHelp(core, env) {
+	// Older cores route unknown commands through legacy startup. Inspect their
+	// config-free help in an isolated home, never try an unknown data command.
+	const scratch = mkdtempSync(join(tmpdir(), "gentle-engram-capability-"));
+	try {
+		const probe = spawnSync(core, ["--help"], {
+			cwd: scratch, env: { ...env, HOME: scratch, USERPROFILE: scratch, ENGRAM_DATA_DIR: join(scratch, "store") },
+			encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000, maxBuffer: 65536, windowsHide: true,
+		});
+		return !probe.error && !probe.signal && probe.status === 0 && probe.stderr === "" ? probe.stdout.split("\n").map((line) => line.trim()) : [];
+	} finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+function supportsMigration(core, env) {
+	return coreHelp(core, env).includes("migrate-copy --data-dir <absolute-source> --output-dir <new-absolute-destination> --confirm-quiescent --json");
+}
+export function supportsBundledSessionOwned(core, env) {
+	if (!core) return false;
+	const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("ENGRAM_") && key !== "GH_TOKEN" && key !== "GITHUB_TOKEN"));
+	try { return coreHelp(core, { ...clean, ENGRAM_NO_UPDATE_CHECK: "1" }).some((line) => /^serve --session-owned(?:\s|$)/.test(line)); }
+	catch { return false; }
+}
+
+export function migrateBundledEngram({ prefix, core, home, env }) {
+	let markerOwned = false;
+	let promotionStarted = false;
+	let output;
+	let backup;
+	try {
+		if (!core) throw new Error("the verified bundled core is unavailable; run gentle-shell setup first");
+		if (!engramProbeAllowed(env)) throw new Error("explicit Engram selections or a disabled startup policy must be resolved before bundled migration");
+		if (migrationPending(prefix)) throw new Error(MIGRATION_PENDING_NOTICE);
+		const source = join(realpathSync(home), ".engram");
+		if (!lstatSync(source).isDirectory() || realpathSync(source) !== source) throw new Error("the source must be a regular default store directory");
+		const provenancePath = engramProvenancePath(prefix);
+		const original = regularText(provenancePath, 4096);
+		const record = parseEngramProvenance(original);
+		const identity = regularText(join(source, ".instance-id"), 128).trim();
+		if (!record || record.dataDir !== source || record.instanceId !== identity) throw new Error("the store does not match Shell's recorded identity; it cannot be adopted");
+		const coreHash = digest(core);
+		const childEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("ENGRAM_") && key !== "GH_TOKEN" && key !== "GITHUB_TOKEN"));
+		childEnv.ENGRAM_NO_UPDATE_CHECK = "1";
+		if (!supportsMigration(core, childEnv)) throw new Error("the bundled core does not support migrate-copy; wait for a supporting published bundle. The source and provenance are unchanged");
+		const suffix = randomUUID();
+		output = `${source}.migrating-${suffix}`;
+		backup = `${source}.before-${suffix}`;
+		const marker = migrationMarkerPath(prefix);
+		mkdirSync(dirname(marker), { recursive: true, mode: 0o700 });
+		// A recorded refusal precedes copying/promotion. A killed launcher must not
+		// mistake the rename gap for a fresh install and provision an empty store.
+		writeFileSync(marker, `${JSON.stringify({ source, output, backup, originalProvenance: record })}\n`, { flag: "wx", mode: 0o600 });
+		markerOwned = true;
+		syncPath(marker);
+		syncPath(dirname(marker), true);
+		const result = spawnSync(core, ["migrate-copy", "--data-dir", source, "--output-dir", output, "--confirm-quiescent", "--json"], {
+			env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000, maxBuffer: 16384, windowsHide: true,
+		});
+		if (result.error || result.signal) throw new Error("the provider failed or timed out; no source promotion was attempted");
+		if (result.status !== 0) throw new Error(`the provider rejected migration (exit ${result.status}): ${result.stderr.trim().slice(0, 2048) || "no diagnostic"}`);
+		if (result.stderr !== "") throw new Error("unexpected provider diagnostic with success evidence");
+		let proof;
+		try { proof = JSON.parse(result.stdout); } catch { throw new Error("invalid provider migration evidence"); }
+		if (!proof || proof.migration_completed !== true || proof.source_dir !== source || proof.output_dir !== output || proof.instance_id !== identity) {
+			throw new Error("provider migration evidence does not match the requested store and copy");
+		}
+		if (!lstatSync(output).isDirectory() || realpathSync(output) !== output ||
+			regularText(join(output, ".instance-id"), 128).trim() !== identity ||
+			regularText(join(source, ".instance-id"), 128).trim() !== identity ||
+			regularText(provenancePath, 4096) !== original || digest(core) !== coreHash) {
+			throw new Error("store, provenance or bundled core changed during migration");
+		}
+		// The original is retained, not deleted. From this point any failure keeps
+		// the marker: recovery must reconcile both paths before another launch.
+		promotionStarted = true;
+		renameSync(source, backup);
+		renameSync(output, source);
+		syncPath(dirname(source), true);
+		const temporary = `${provenancePath}.${suffix}.tmp`;
+		writeFileSync(temporary, `${JSON.stringify({ schema: 1, dataDir: source, instanceId: identity, coreSha256: coreHash })}\n`, { flag: "wx", mode: 0o600 });
+		syncPath(temporary);
+		renameSync(temporary, provenancePath);
+		syncPath(dirname(provenancePath), true);
+		// Only a durable promotion and provenance may release the fail-closed marker.
+		rmSync(marker);
+		// The migration is complete; a failed final sync must not report failure.
+		try { syncPath(dirname(marker), true); } catch { /* Best effort. */ }
+		return { code: 0, stdout: `${JSON.stringify({ status: "migrated", instance_id: identity, backup_dir: backup })}\n`, stderr: "" };
+	} catch (error) {
+		if (markerOwned && !promotionStarted) {
+			try { rmSync(migrationMarkerPath(prefix)); } catch { /* Keep the fail-closed marker. */ }
+		}
+		const retained = output ? ` Any partial copy at ${output} is retained; do not use it.` : "";
+		const recovery = promotionStarted ? ` Promotion may be incomplete; original backup: ${backup}. ${MIGRATION_PENDING_NOTICE}` : "";
+		return { code: 1, stdout: "", stderr: `gentle-shell: memory migration failed: ${error.message}.${retained}${recovery}\n` };
+	}
+}

package/scripts/gentle-ai-installer.mjs

@@ -37,7 +37,7 @@ const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 // version check below) derives from this constant instead of repeating the
 // literal, so a pin bump cannot leave a stale copy behind. See
 // scripts/install-gentle-ai.mjs for the incident that motivated this.
-export const INSTALLER_VERSION = "4.1.1";
+export const INSTALLER_VERSION = "4.2.0";
 export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
@@ -46,11 +46,11 @@ export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v4";
 export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.1.1`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.2.0`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 898d3976e8049a7238eaa7de60bff325c30d2b3d, the published v4.1.1 release head.
+// tag resolves to commit 4acaf4241beae1e0c977c92dfe406a270f8d40de, the published v4.2.0 release head.
 // v4.0.0 moved the Go module path to the /v4 major-version suffix.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:+WmZ2IvIOiJ8qtHa7wsjnYKNasem+PByeOZ6HIjoAL8=";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -69,7 +69,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v4.1.1 digests are pinned from the published release:
+// still holds it. The v4.2.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -111,15 +111,15 @@ async function downloadPinnedGentleAiAsset(asset, destination, options) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v4.1.1 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.2.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_4.1.1_darwin_amd64.tar.gz", "f2e9aebfba3056e88a8d7c7193e4e8c04282dc126d5eaa2216bc807deadecffd", "82351dd86bf7323c6a5b9e9e68b3cc2893a65a4df04fbdf1ef1801cabf5d2338", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_4.1.1_darwin_arm64.tar.gz", "8093dced37130cb26534d81663013f81d9039342e33f00b8c85aa5319aa7eea9", "6362e3641b87ae2b41a8dd7695dad4cf47457ee86c9f63792e474476bfdb6b6a", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_4.1.1_linux_amd64.tar.gz", "57869ebcdba5ba9942493ab413bbc15d146e2451c4dca3eaafcf163fcbd646b4", "7c638c8467efc7036e0ec6b8a1d9080a5e9a64f7ae6cbc6074fce577f789b7fe", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_4.1.1_linux_arm64.tar.gz", "5f8fa38573eea0f2110902f0996aa0b008aac58dc0f9a6abbdf301dcbc93f4eb", "76a36a73d6905a16221496ffe9a193bd79e17951463d711cd03abf370349ef55", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_4.2.0_darwin_amd64.tar.gz", "8f6a91e0f99cac3aea138705d7d222ea342f53a47602d48cb01488952a1c12f8", "784855e99f1bc45579f01420c923b7dc1dc6d63492cdc0174a9a32e611849e57", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.2.0_darwin_arm64.tar.gz", "d5e9a6521de5f08a393635f083f64dc7afc1b8e97884f7aab5ae5eb1f17c7f37", "8ea490287ef796848b0d305cf2b26265e360d3f400efc016972844498fb87097", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.2.0_linux_amd64.tar.gz", "552c1642fd10f5d96cfe9bb1cc3b66b30eb47d3074cc7ca0559b598eb086defc", "9212c7b16ea9abfe93e3a16b29d8390e7762b5c07730cf05df1f3e7892ff96a4", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.2.0_linux_arm64.tar.gz", "2bebe91b8808ce48d86c4d3700d098e37cb6b0658f196c666d9deeeb7c7c1a7a", "e1b88bd3dcdc8a15ddbcaf8731fd44561f05b06fbcb59d9385bbe82c4b96b5c4", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

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/installer-server.mjs

@@ -170,6 +170,9 @@ export const guidance = Object.freeze({
 	setupRateLimit: "`gentle-shell setup` could not finish because GitHub's limit for anonymous API requests was reached on this network. Wait up to an hour, then run the installer again.",
 	// A failed acquire-go whose detail names a Go folder the installer did not publish.
 	goDestinationConflict: `A Go folder from an earlier, interrupted installer run is in the way, and the installer never replaces a folder it cannot prove it published. Remove that folder (shown below), then run the installer again. Nothing was installed.`,
+	// A failed install whose detail shows Windows refused to start the gentle-ai.exe gentle-pi's postinstall built.
+	codeIntegrityBlocked: "Windows refused to run the Gentle AI program (gentle-ai.exe) that the installation builds on this computer, most likely because Smart App Control or another code integrity policy blocks unsigned programs. " +
+		"Windows offers no exception for a single program. Keep using Gentle Shell in WSL, or turn Smart App Control off in Windows Security and run the installer again; on Windows 11 it cannot be turned back on without reinstalling Windows.",
 	// A failed persist-path whose detail shows pnpm could not tell the shell (POSIX SHELL missing or unsupported).
 	persistPathShell: "`pnpm setup` could not tell which shell profile to edit because the SHELL environment variable is missing or names an unsupported shell. Open a regular terminal and run the installer again, or add `$PNPM_HOME/bin` to your PATH yourself.",
 	fallback: "The installation stopped for an unexpected reason. Nothing else will run; check the terminal and run the installer again.",
@@ -186,16 +189,20 @@ function setupDetail(value) {
 const rateLimited = (detail) => /rate limit/i.test(detail) || (/GitHub API/i.test(detail) && /\b403\b/.test(detail));
 const unknownShell = (detail) => /ERR_PNPM_(?:UNKNOWN|UNSUPPORTED)_SHELL/.test(detail);
 const goConflict = (detail) => detail.startsWith("Conflicting Go destination: ");
+// libuv reports a CreateProcess refusal it has no code for, such as a Windows code integrity block
+// (Smart App Control, event 3077), as spawn UNKNOWN.
+const codeIntegrityBlocked = (detail) => /\bspawn UNKNOWN\b/.test(detail);
 // The main channel's typed error when GitHub refused the latest main commit with HTTP 403.
 const githubLimited = (detail) => rateLimited(detail) || (/\bmain-commit-unavailable\b/.test(detail) && /\bHTTP 403\b/.test(detail));
 // Fixed steps whose sanitized last error line may reach the browser.
 // The bundled steps send a detail only for a migration (its error message); a new install's send none.
 const bundledDetail = Object.fromEntries(["claim-prefix", "copy-npm-settings", "install-runtime", "activate-version", "write-launcher", "verify-launcher", "bundled-path"]
 	.map((step) => [step, () => false]));
-const detailSteps = Object.freeze({ ...bundledDetail, "shell-setup": rateLimited, "install-version": () => false, "persist-path": unknownShell, "acquire-go": goConflict,
-	"install-global": githubLimited, "install-shell-main": githubLimited, "build-gentle-ai-main": githubLimited, "update-shell": githubLimited });
+const detailSteps = Object.freeze({ ...bundledDetail, "shell-setup": rateLimited, "install-version": codeIntegrityBlocked, "persist-path": unknownShell, "acquire-go": goConflict,
+	"install-global": (detail) => githubLimited(detail) || codeIntegrityBlocked(detail), "install-shell-main": githubLimited, "build-gentle-ai-main": githubLimited, "update-shell": githubLimited });
+// A step whose detail can match more than one pattern names its guidance by detail.
 const detailGuidance = Object.freeze({ "shell-setup": "setupRateLimit", "persist-path": "persistPathShell", "acquire-go": "goDestinationConflict",
-	"install-global": "githubRateLimit", "install-shell-main": "githubRateLimit", "build-gentle-ai-main": "githubRateLimit", "update-shell": "githubRateLimit" });
+	"install-version": "codeIntegrityBlocked", "install-global": (detail) => (githubLimited(detail) ? "githubRateLimit" : "codeIntegrityBlocked"), "install-shell-main": "githubRateLimit", "build-gentle-ai-main": "githubRateLimit", "update-shell": "githubRateLimit" });
 
 const ID = /^[a-z][a-z0-9-]{0,63}$/;
 function identifier(value, fallback = "unknown") {
@@ -543,7 +550,10 @@ function outcomeView(result) {
 		const detail = step ? setupDetail(result.detail) : null;
 		if (detail) {
 			view.detail = detail;
-			if (detailSteps[step](detail)) view.guidance = guidance[detailGuidance[step]];
+			if (detailSteps[step](detail)) {
+				const key = detailGuidance[step];
+				view.guidance = guidance[typeof key === "function" ? key(detail) : key];
+			}
 		}
 	} else {
 		view.guidance = guidance.outcomes[result.outcome];

package/scripts/main-channel.mjs

@@ -35,9 +35,10 @@ export class MainChannelError extends Error {
 	}
 }
 
-/** Same config home as the dev-binary override: GENTLE_PI_CONFIG_HOME or ~/.pi/gentle-ai. */
+/** Same config home as the dev-binary override: a nonempty GENTLE_PI_CONFIG_HOME or ~/.pi/gentle-ai.
+ * Install-level state, so never the standalone launcher's per-home marker (#2201). */
 export function configHome({ env, home }) {
-	return env.GENTLE_PI_CONFIG_HOME ?? join(home, ".pi", "gentle-ai");
+	return env.GENTLE_PI_CONFIG_HOME || join(home, ".pi", "gentle-ai");
 }
 export function channelStatePath(ctx) {
 	return join(configHome(ctx), "channel.json");

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/scripts/run-test-suite.mjs

@@ -30,6 +30,10 @@ export async function runStage(stage) {
 		return !normalizedKey.startsWith("GIT_") && !normalizedKey.startsWith("GENTLE_PI_AGENTS_") && normalizedKey !== "GENTLE_PI_CONFIG_HOME";
 	})) : process.env;
 	if (configHome) env.GENTLE_PI_CONFIG_HOME = configHome;
+	// Unit fixtures also get a private temp dir, removed with the stage, so a
+	// fixture that leaves a subagent unfinished cannot leave its TMPDIR behind.
+	const unitTmp = configHome ? mkdtempSync(join(tmpdir(), "gentle-pi-unit-tmp-")) : undefined;
+	if (unitTmp) env.TMPDIR = unitTmp;
 	try {
 		return await new Promise((resolve) => {
 			const child = spawn(stage.command, { shell: true, stdio: "inherit", env });
@@ -41,6 +45,7 @@ export async function runStage(stage) {
 		});
 	} finally {
 		if (configHome) rmSync(configHome, { recursive: true, force: true });
+		if (unitTmp) rmSync(unitTmp, { recursive: true, force: true });
 	}
 }
 

package/scripts/verify-package-files.mjs

@@ -53,6 +53,7 @@ export const requiredPaths = [
   "scripts/npm-pack-result.mjs",
   "assets/orchestrator.md",
   "assets/orchestrator-delegation.md",
+  "assets/orchestrator-delegation-reference.md",
   "assets/orchestrator-tracking.md",
   "assets/orchestrator-verification.md",
   "assets/orchestrator-writer.md",
@@ -81,6 +82,7 @@ export const requiredPaths = [
   "docs/review-integration.md",
   "extensions/gentle-ai.ts",
   "extensions/resume-hint.ts",
+  "extensions/session-scratch.ts",
   "extensions/skill-registry.ts",
   "lib/child-package-injection.ts",
   "lib/gentle-ai-binary.ts",
@@ -90,6 +92,7 @@ export const requiredPaths = [
   "lib/gentle-shell-update-panel.ts",
   "lib/gentle-shell-startup-flow.ts",
   "lib/gentle-shell-resume-hint.ts",
+  "lib/gentle-shell-import-pi.ts",
   "lib/native-review-cli.ts",
   "lib/status-timing-diagnostics.ts",
   "lib/provider-contract-bundle.ts",
@@ -98,6 +101,7 @@ export const requiredPaths = [
   "lib/review-relay-contract.ts",
   "lib/agent-assets.ts",
   "lib/telemetry-trigger.ts",
+  "lib/session-scratch.ts",
 	"runtime/child-package-injection.mjs",
 	"runtime/gentle-ai-binary.mjs",
 	"runtime/gentle-shell-launcher.mjs",
@@ -107,6 +111,7 @@ export const requiredPaths = [
 	"runtime/gentle-shell-startup-flow.mjs",
 	"runtime/gentle-shell-resume-hint.mjs",
 	"runtime/gentle-shell-uninstall.mjs",
+	"runtime/gentle-shell-import-pi.mjs",
 	"runtime/native-review-cli.mjs",
 	"runtime/status-timing-diagnostics.mjs",
 	"runtime/review-integration-v2.mjs",
@@ -131,17 +136,18 @@ export const requiredPaths = [
   // exact bytes are pinned by the lock-driven scripts/check-provider-contract.mjs
   // drift check, which runs in the same pnpm test flow.
   "contracts/review-provider-contract-mirror/provider-contract.lock.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/README.md",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/manifest.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/orchestration/pi.md",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/lens.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/refuter.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/schemas/targeted-validator.schema.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/lens.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/refuter.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/bundle/vectors/targeted-validator.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-capabilities.baseline.json",
-  "contracts/review-provider-contract-mirror/v1.3.0/generated/provider-roles.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/README.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/manifest.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/orchestration/pi.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/routing/pi.md",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/lens.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/refuter.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/schemas/targeted-validator.schema.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/lens.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/refuter.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/bundle/vectors/targeted-validator.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/generated/provider-capabilities.baseline.json",
+  "contracts/review-provider-contract-mirror/v1.4.0/generated/provider-roles.baseline.json",
   "prompts/skill-creation.md",
   "skills/_shared/review-ledger-contract.md",
   "skills/branch-pr/SKILL.md",
@@ -395,7 +401,7 @@ async function main() {
   });
 
   if (driftedContracts.length > 0) {
-    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.1.1 runtime's vendored Gentle AI contract artifacts:");
+    console.error("gentle-pi packaged review-integration/v1 and review-integration/v2 contract bytes drifted from the pinned v4.2.0 runtime's vendored Gentle AI contract artifacts:");
     for (const drift of driftedContracts) console.error(`- ${drift.relativePath}: expected ${drift.expected}, got ${drift.actual}`);
     process.exit(1);
   }
@@ -440,7 +446,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.1.1 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.2.0 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;