gentle-pi 4.3.0 → 4.4.0

package/runtime/native-review-cli.mjs

@@ -203,10 +203,10 @@ export const NATIVE_REVIEW_MODE_SCOPE = {
 // stream while still succeeding. That last qualifier is what keeps this list
 // honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
 // on by default; this was never explicitly chosen. ..."), which used to ride
-// with the skip notice whenever the resolved mode source was `default`. Under
-// opt-in receipt-driven development a default-source clone is refused long
-// before the consent ceremony runs, so the pinned binary can no longer emit
-// that line and it is removed here rather than left as dead tolerance. Multi-
+// with the skip notice whenever the resolved mode source was `default`. Reviews
+// are on by default again since gentle-ai v4.0.0, but the pinned binary no
+// longer has that function and cannot emit the line, so it is removed here
+// rather than left as dead tolerance. Multi-
 // line stderr is still expected in principle — these are separate Fprintln
 // calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
@@ -1091,6 +1091,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
 	// No new negotiated capability identity is asserted.
 	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.3.1 repeats 4.2.0: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2, and the provider contract
+	// stays at 1.4.0, with published tarball SHA-256
+	// 58450471280aeb357443d6a28c819132d8c8eb78dd25b12bac64296b2f8c27c2.
+	// The v4.3.0 tag has no release and is never pinned.
+	// No new negotiated capability identity is asserted.
+	"4.3.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 

package/scripts/bundled-engram-migration.mjs

@@ -43,12 +43,6 @@ function coreHelp(core, env) {
 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;

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.2.0";
+export const INSTALLER_VERSION = "4.3.1";
 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.2.0`
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v4@v4.3.1`
 // with GOSUMDB=sum.golang.org reports this exact module SumDB checksum, and the
-// tag resolves to commit 4acaf4241beae1e0c977c92dfe406a270f8d40de, the published v4.2.0 release head.
+// tag resolves to commit 2dba7784114fff57864519c4c0d067e952a8c98b, the published v4.3.1 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:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=";
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:00p8dnjJrhYFq1Qikk2oY6K/UXIty9A/IBUUOUiX9XA=";
 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.2.0 digests are pinned from the published release:
+// still holds it. The v4.3.1 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.2.0 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v4.3.1 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.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"),
+	"darwin/amd64": asset("gentle-ai_4.3.1_darwin_amd64.tar.gz", "6cf57fee0574daef2abed07f54a355fec3b93ac8f01733dc6c4d3674f1746112", "ca44c3fce186b63a7e7ad455c338133ba1982f4a13485301ce4d66edb73d2928", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_4.3.1_darwin_arm64.tar.gz", "13e8828447f9081465ee0c35a61b24fb49296d51a310c6999227e2aed178956b", "749d08062b0dec13681678a1a1c018613d223ddcca47b5f27681b1d8ab5d14c2", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_4.3.1_linux_amd64.tar.gz", "04ec685c56b42c29dff6db10fc7dc2c730217dc9c96736e53ad2acf3226dafb7", "86248792bde3fe5e9ca93b128c07e7caa6a5b31fac0f9fc84b5b3011b123cb90", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_4.3.1_linux_arm64.tar.gz", "99e7d313a2ff85eaf23a6415e9b3aae67bf74c2fa169b21b93070ada7613f6a0", "df3580506bb5ea63cc4ef5ccebe8b68cfedf66b72f3b51f84ff393183d8cea2b", "gentle-ai"),
 });
 
 // A pinned asset is either a signed archive or, for a prerelease pin only,

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.4.0",
+	version: "3.5.2",
 	redirectHosts: Object.freeze(["objects.githubusercontent.com", "release-assets.githubusercontent.com"]),
 	archives: Object.freeze({
-		"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],
+		"darwin-arm64": ["darwin_arm64.tar.gz", "43d398b2fe3327a4a6436c26b2a17d3285ba80bf2f11a22d0796ea2a7fd2b78c", 7749520],
+		"darwin-x64": ["darwin_amd64.tar.gz", "aea28ebf461a4ea86c52b793c29311539d7123875354ed7411eae982fc82ec87", 8181300],
+		"linux-x64": ["linux_amd64.tar.gz", "106a43ca8f43a27c2c260a6787151c3be6d91c5ed3d5e454e6140527adf92e01", 8064598],
+		"linux-arm64": ["linux_arm64.tar.gz", "b0ba49cf5a7d5af436c9744a9a0d638b3f9ebb2a7321c8736d30e96305c2993c", 7472279],
+		"win32-x64": ["windows_amd64.zip", "ba56a36d37b2da85fcb1581bbdbed9ae1ee690e642aab8dbe1e18209bf264afe", 8272809],
+		"win32-arm64": ["windows_arm64.zip", "df5acc5dd6ee407d484074e570c77a79567c0b8dccf55e25ae25a644c1e7db5f", 7530282],
 	}),
 });
 /** The Engram version the bundled install publishes under runtime/. */

package/scripts/installer-preflight.mjs

@@ -248,9 +248,11 @@ export function planPreflight(inventory, { channel = "release" } = {}) {
 	record("gentleAi", classify(inventory.gentleAi, requirements.gentleAi, (o) => o.compatible, true), requirements.gentleAi);
 	const needsNative = tools.gentleAi.status === "unavailable";
 	// The main channel builds Gentle AI from source on every platform.
-	// gentle-pi's postinstall may build Gentle AI from source on Windows, so a
-	// Windows release update needs Go like an installation; main always does.
-	const windowsBuild = platform === "win32" && (update !== null || (needsNative && !npmCurrent));
+	// gentle-pi's postinstall always builds Gentle AI from source on Windows, even
+	// next to an installed gentle-ai, so installing or updating the Shell needs Go,
+	// as does provisioning a missing native binary; main always does.
+	const installsShell = tools.shell.status === "unavailable";
+	const windowsBuild = platform === "win32" && (update !== null || (!npmCurrent && (installsShell || needsNative)));
 	const goStatus = windowsBuild || main ? classify(inventory.go, requirements.go) : "not-required";
 	if (goStatus === "unavailable" || goStatus === "incompatible" || goStatus === "unknown") {
 		// A missing, older or unreadable Go is left as it is: the build gets the

package/scripts/installer-windows.mjs

@@ -107,6 +107,36 @@ function exists(path) {
 	try { lstatSync(path); return true; }
 	catch (error) { if (error.code === "ENOENT") return false; throw error; }
 }
+// Failure-only diagnostics, in UTF-16 code units. Suppress entire sensitive
+// streams (including continuation lines), and individual path/SID/opaque lines.
+// This is conservative diagnostic filtering, not a general-purpose secret parser.
+function processDiagnosticText(value, limit) {
+	if (typeof value !== "string") return "";
+	if (/(?:^|[^a-z0-9])(?:authorization|bearer|token|password|passphrase|secret|credential|api[_-]?key|access[_-]?key|cookie)(?:$|[^a-z0-9])/i.test(value)) return "[redacted]";
+	return value.split(/\r\n?|\n/).map(line =>
+		/[A-Za-z]:[\\/]|\\|(?:^|[\s"'=])\/\S+|\bS-\d-(?:\d+-)+\d+\b|unsafe:[^|]*\||[A-Za-z0-9+/=_-]{64,}|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/i.test(line) ? "[redacted]" : line
+	).join("\n").slice(0, limit);
+}
+function prerequisiteProcessCause(result) {
+	const failure = result.error;
+	const code = processDiagnosticText(failure?.code, 64);
+	const details = {
+		status: Number.isSafeInteger(result.status) ? result.status : null,
+		signal: processDiagnosticText(result.signal, 32) || null,
+		error: failure ? {
+			code, name: processDiagnosticText(failure.name, 64),
+			// Spawn text may contain a bare private executable name, not just paths.
+			message: /^E[A-Z0-9_]+$/.test(code) ? `Windows prerequisite process error: ${code}` : "Windows prerequisite process error",
+			errno: Number.isSafeInteger(failure.errno) ? failure.errno : processDiagnosticText(failure.errno, 64),
+		} : null,
+		stdout: processDiagnosticText(result.stdout, 1024), stderr: processDiagnosticText(result.stderr, 1024),
+	};
+	const cause = Object.assign(new Error("Windows prerequisite process diagnostics"), details);
+	// Existing evidence consumers read cause.stack only; omit local callsites and
+	// never attach the raw spawn Error (which carries command/path/argv fields).
+	cause.stack = `Error: ${cause.message}\n${JSON.stringify(details)}`.slice(0, 8192);
+	return cause;
+}
 export function windowsProcessCheck(command, args, env) {
 	// Owned direct children only, not a tree/global kill. Descendant-held stdio
 	// is outside this guarantee. Never execute .cmd through a command interpreter.
@@ -114,7 +144,7 @@ export function windowsProcessCheck(command, args, env) {
 	// A neutral cwd: inside a project (the bundle itself), pnpm 11 reports, and may
 	// fetch, the version that project's packageManager pins instead of its own.
 	const result = spawnSync(command, args, { cwd: parse(command).root || undefined, env, shell: false, encoding: "utf8", timeout: 15000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, windowsHide: true });
-	if (result.error || result.status !== 0) throw new Error("Windows prerequisite process failed");
+	if (result.error || result.status !== 0) throw new Error("Windows prerequisite process failed", { cause: prerequisiteProcessCause(result) });
 	return result.stdout.trim();
 }
 
@@ -151,9 +181,9 @@ try {
   $depth = 0;
   while ($path) {
     $role = 'ancestor'; if ($depth -eq 0) { $role = 'target' } elseif ($depth -eq 1) { $role = 'parent' };
-    $item = Get-Item -LiteralPath $path -Force;
-    if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };
-    if ($item.PSIsContainer) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };
+    $attributes = [IO.File]::GetAttributes($path);
+    if ($attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };
+    if ($attributes -band [IO.FileAttributes]::Directory) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };
     $owner = $acl.GetOwner([Security.Principal.SecurityIdentifier]);
     if ($trusted -notcontains $owner.Value) { $detail = $path + '|' + $owner.Value + '|' + (& $account $owner) + '|'; throw ($role + '-owner') };
     $allowedRights = 0x1200a9; if ($depth -ge 2) { $allowedRights = 0x1200ad };
@@ -186,9 +216,9 @@ foreach ($start in $env:GENTLE_WINDOWS_CHECKS.Split('|')) {
     $depth = 0;
     while ($path) {
       $role = 'ancestor'; if ($depth -eq 0) { $role = 'target' } elseif ($depth -eq 1) { $role = 'parent' };
-      $item = Get-Item -LiteralPath $path -Force;
-      if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };
-      if ($item.PSIsContainer) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };
+      $attributes = [IO.File]::GetAttributes($path);
+      if ($attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };
+      if ($attributes -band [IO.FileAttributes]::Directory) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };
       $owner = $acl.GetOwner([Security.Principal.SecurityIdentifier]);
       if ($trusted -notcontains $owner.Value) { $detail = $path + '|' + $owner.Value + '|' + (& $account $owner) + '|'; throw ($role + '-owner') };
       $allowedRights = 0x1200a9; if ($depth -ge 2) { $allowedRights = 0x1200ad };

package/scripts/main-channel.mjs

@@ -4,9 +4,11 @@
 // an exact commit SHA resolved at install or upgrade time:
 //   - Gentle AI: `go install <module>@<sha>` in a sealed Go environment, so the
 //     module source is verified by Go's checksum database (sum.golang.org), as
-//     the Windows release build already is. The binary must report a version
-//     naming that commit, then it is activated through the existing dev-binary
-//     override, which never falls back to the pinned binary silently.
+//     the Windows release build already is. Go must resolve the commit to a
+//     module version (a tag or a pseudo-version) whose origin is that commit,
+//     and the binary must embed that version and report it, then it is
+//     activated through the existing dev-binary override, which never falls
+//     back to the pinned binary silently.
 //   - Gentle Shell: the exact commit's source tarball, versioned
 //     `<version>-main.<sha12>` and packed without `prepack` (which runs the full
 //     test suite), then installed globally like any local tarball.
@@ -18,13 +20,14 @@ import { goAcquisition, pnpmGlobalBin, requirements } from "./installer-prefligh
 
 export const SHELL_REPOSITORY = "Gentleman-Programming/gentle-shell";
 export const GENTLE_AI_REPOSITORY = "Gentleman-Programming/gentle-ai";
+export const GENTLE_AI_MODULE = "github.com/gentleman-programming/gentle-ai/v4";
 export const GENTLE_AI_MAIN_PACKAGE = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
 export const CHANNEL_SCHEMA = "gentle-shell.channel/v1";
 export const CHANNELS = Object.freeze(["release", "main"]);
 
 const SHA = /^[0-9a-f]{40}$/;
 const MINUTE = 60_000;
-const deadlines = Object.freeze({ build: 15 * MINUTE, version: 30_000, extract: 2 * MINUTE, pack: 5 * MINUTE });
+const deadlines = Object.freeze({ build: 15 * MINUTE, resolve: 2 * MINUTE, version: 30_000, extract: 2 * MINUTE, pack: 5 * MINUTE });
 const MAX_SOURCE_BYTES = 100 * 1024 * 1024;
 
 export class MainChannelError extends Error {
@@ -136,23 +139,57 @@ export async function buildMainGentleAi({ commit, ctx, platform, goPath, run, fs
 	const executable = platform === "win32" ? "gentle-ai.exe" : "gentle-ai";
 	const directory = join(configHome(ctx), "main", "gentle-ai", commit);
 	const buildDirectory = join(configHome(ctx), "main", ".build");
+	// Verified in the work folder before it replaces anything, so a failed rebuild of
+	// an already registered commit never touches the override; the final move stays
+	// on one filesystem, and uninstall already accepts a leftover .build.
+	const staging = join(buildDirectory, commit);
 	await fs.rm(buildDirectory, { recursive: true, force: true });
 	const env = sealedGoEnvironment(goPath, buildDirectory, platform);
 	for (const path of [env.GOBIN, env.GOPATH, env.GOMODCACHE, env.GOCACHE, join(buildDirectory, "tmp")]) await fs.mkdir(path, { recursive: true });
 	try {
 		const install = await run(goPath, ["install", `${GENTLE_AI_MAIN_PACKAGE}@${commit}`], { env, cwd: buildDirectory, deadlineMs: deadlines.build, stderrTail: 4096 });
 		if (!succeeded(install)) throw new MainChannelError("main-gentle-ai-build-failed", `go install ${GENTLE_AI_MAIN_PACKAGE}@${commit} failed`, stderrCause(install));
-		await fs.mkdir(directory, { recursive: true });
-		const binaryPath = join(directory, executable);
-		await fs.copyFile(join(env.GOBIN, executable), binaryPath);
-		if (platform !== "win32") await fs.chmod(binaryPath, 0o755);
-		// Go stamps the module pseudo-version, whose suffix is the commit's first 12 characters.
-		const probe = await run(binaryPath, ["version"], { env: { PATH: env.PATH }, deadlineMs: deadlines.version });
+		await fs.mkdir(staging, { recursive: true });
+		const stagedPath = join(staging, executable);
+		await fs.copyFile(join(env.GOBIN, executable), stagedPath);
+		if (platform !== "win32") await fs.chmod(stagedPath, 0o755);
+		const reject = async (message, cause) => {
+			throw new MainChannelError("main-gentle-ai-unverified", message, cause);
+		};
+		const short = commit.slice(0, 12);
+		const goOptions = { env, cwd: buildDirectory, deadlineMs: deadlines.version, stderrTail: 4096 };
+		// Go resolves the commit through the proxy and checksum database: a tag commit is
+		// stamped with its tag, any other with a pseudo-version, so the version is not guessed.
+		// Resolving may reach the proxy, so it gets a network deadline, not the local one.
+		const listed = await run(goPath, ["list", "-m", "-json", `${GENTLE_AI_MODULE}@${commit}`], { ...goOptions, deadlineMs: deadlines.resolve });
+		if (!succeeded(listed)) return await reject(`Go could not resolve Gentle AI commit ${short}`, stderrCause(listed));
+		let resolved = null;
+		try {
+			resolved = JSON.parse(String(listed.stdout ?? ""));
+		} catch {
+			return await reject(`Go returned unreadable module information for Gentle AI commit ${short}`);
+		}
+		const resolvedVersion = typeof resolved?.Version === "string" ? resolved.Version : "";
+		const originHash = resolved?.Origin?.Hash;
+		if (resolvedVersion === "") return await reject(`Go resolved Gentle AI commit ${short} to no module version`);
+		if (originHash !== commit) {
+			return await reject(`Go resolved Gentle AI commit ${short} to ${originHash ? `commit ${originHash}` : "no commit"}, not the requested commit`);
+		}
+		const embedded = await run(goPath, ["version", "-m", stagedPath], goOptions);
+		if (!succeeded(embedded)) return await reject("the built Gentle AI's embedded module version could not be read", stderrCause(embedded));
+		const modLine = String(embedded.stdout ?? "").split(/\r?\n/).map((line) => line.trim().split(/\s+/)).find((fields) => fields[0] === "mod" && fields[1] === GENTLE_AI_MODULE);
+		if (modLine?.[2] !== resolvedVersion) {
+			return await reject(`the built Gentle AI embeds module version ${modLine?.[2] ?? "none"}, expected ${resolvedVersion} for commit ${short}`);
+		}
+		const probe = await run(stagedPath, ["version"], { env: { PATH: env.PATH }, deadlineMs: deadlines.version });
 		const match = succeeded(probe) && /^gentle-ai (\S+)$/m.exec(String(probe.stdout ?? ""));
-		if (!match || !match[1].endsWith(`-${commit.slice(0, 12)}`)) {
-			await fs.rm(directory, { recursive: true, force: true });
-			throw new MainChannelError("main-gentle-ai-unverified", `the built Gentle AI does not report commit ${commit.slice(0, 12)}`);
+		const expectedVersion = resolvedVersion.replace(/^v/, "");
+		if (!match || match[1] !== expectedVersion) {
+			return await reject(`the built Gentle AI reports version ${match ? match[1] : "none"}, expected ${expectedVersion} for commit ${short}`);
 		}
+		await fs.mkdir(directory, { recursive: true });
+		const binaryPath = join(directory, executable);
+		await fs.rename(stagedPath, binaryPath);
 		registerGentleAiDevBinary(binaryPath, ctx, platform);
 		return { binaryPath, version: match[1] };
 	} finally {
@@ -387,6 +424,21 @@ async function mainGo({ userGo, pinnedGo, acquire, run }) {
 	}
 }
 
+/** A thrown value's message when it has one (an Error or not), otherwise the value as text. */
+function describe(error) {
+	return typeof error?.message === "string" ? error.message : String(error);
+}
+
+/** `error` with `detail` appended to its message, keeping its code and cause; any
+ * other error becomes `main-upgrade-incomplete` with its message and itself as cause. */
+function withDetail(error, detail) {
+	if (!(error instanceof MainChannelError)) {
+		return new MainChannelError("main-upgrade-incomplete", `${describe(error)}; ${detail}`, error);
+	}
+	const message = error.message.slice(`${error.code}: `.length);
+	return new MainChannelError(error.code, `${message}; ${detail}`, error.cause);
+}
+
 /**
  * Updates Gentle Shell along its recorded channel (or the one `--channel` selects):
  * release goes to the latest npm release, main to the latest `main` commits of
@@ -441,11 +493,33 @@ export async function runUpgrade({ args, ctx, platform, arch = process.arch, pac
 		out(`gentle-shell is already at the latest main: ${summary}.`);
 		return 0;
 	}
-	if (!aiCurrent) await buildMainGentleAi({ commit: gentleAiCommit, ctx, platform, goPath: await mainGo({ userGo, pinnedGo, acquire, run }), run, fs });
+	// Fail forward (#2356): a Gentle AI step that fails still installs a main Shell that
+	// moved, so the retry runs the new Shell's code; the channel is recorded only when
+	// both steps succeed, so that retry rebuilds Gentle AI. Verification stays fail-closed.
+	// A flag, not the caught value: a rejection may be any value, even a falsy one.
+	let aiFailed = false;
+	let aiError;
+	if (!aiCurrent) {
+		try {
+			await buildMainGentleAi({ commit: gentleAiCommit, ctx, platform, goPath: await mainGo({ userGo, pinnedGo, acquire, run }), run, fs });
+		} catch (error) {
+			if (shellCurrent) throw error;
+			aiFailed = true;
+			aiError = error;
+		}
+	}
 	if (!shellCurrent) {
-		const manager = await ownerManager({ ctx, platform, packageRoot, adapters });
-		const tgz = await packMainShell({ commit: shellCommit, ctx, fetch, run, pnpm, fs, platform });
-		await installGlobal(manager, tgz, run);
+		try {
+			const manager = await ownerManager({ ctx, platform, packageRoot, adapters });
+			const tgz = await packMainShell({ commit: shellCommit, ctx, fetch, run, pnpm, fs, platform });
+			await installGlobal(manager, tgz, run);
+		} catch (error) {
+			throw aiFailed ? withDetail(error, `Gentle AI was not updated either (${describe(aiError)})`) : error;
+		}
+	}
+	if (aiFailed) {
+		out(`Updated Gentle Shell to the latest main (${shellCommit.slice(0, 12)}); Gentle AI was not updated.`);
+		throw withDetail(aiError, `Gentle Shell was updated to main ${shellCommit.slice(0, 12)} but Gentle AI was not: run gentle-shell upgrade --channel main to finish`);
 	}
 	await writeChannel(ctx, { channel: "main", shellCommit, gentleAiCommit }, fs);
 	out(`Updated to the latest main: ${summary}.`);

package/scripts/pi-update.mjs

@@ -1,6 +1,7 @@
 // Narrow update ownership proof. Deliberately independent of Shell upgrade/uninstall.
 import { posix, win32 } from 'node:path';
 import { bundledUpdatePlan } from '../runtime/gentle-shell-bundled.mjs';
+import { setupErrorDetail } from './installer-runner.mjs';
 
 const PI = '@earendil-works/pi-coding-agent';
 const SHELL = 'gentle-pi';
@@ -8,6 +9,9 @@ const object = value => value !== null && typeof value === 'object' && !Array.is
 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;
+// A main-channel Shell (`<version>-main.<sha12>`, scripts/main-channel.mjs
+// mainVersion) is never published; it exists only as the packed tarball.
+const MAIN_BUILD = /^[0-9A-Za-z.+-]+-main\.[0-9a-f]{12}$/;
 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
@@ -136,7 +140,19 @@ async function listedEntries(groups, {adapters, path, key, canonical}) {
  * 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}) {
+/** Where `gentle-shell upgrade --channel main` packed this Shell version: the
+ * same config home as scripts/main-channel.mjs configHome. A relative config
+ * home is refused, not resolved: `upgrade` resolved it from its own working
+ * directory, so it names no single folder, and the package manager runs from
+ * the neutral cwd.
+ */
+function mainBuildTarball(version, {env, home, path}) {
+ const config = env?.GENTLE_PI_CONFIG_HOME || (typeof home === 'string' ? path.join(home, '.pi', 'gentle-ai') : null);
+ if (!config || !path.isAbsolute(config)) throw refusal('cannot locate the main-channel build without an absolute config home');
+ return path.join(config, 'main', 'packages', `${SHELL}-${version}.tgz`);
+}
+
+export async function resolveUpdateOwner({runtime, packageRoot, platform = process.platform, adapters, cwd, env, home}) {
  const {path, key} = pathsFor(platform);
  const canonical = canonicalWith(adapters, path);
  const selected = await selectedCliOf(runtime, {adapters, path, canonical});
@@ -154,7 +170,7 @@ export async function resolveUpdateOwner({runtime, packageRoot, platform = proce
    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;
+   let cli, spec, artifact = false;
    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));
@@ -169,11 +185,12 @@ export async function resolveUpdateOwner({runtime, packageRoot, platform = proce
     // 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}`;
+    artifact = MAIN_BUILD.test(manifest.version);
+    spec = artifact ? mainBuildTarball(manifest.version, {env, home, path}) : `${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});
+   candidates.push({name, ...invocation, package:pkg, spec, artifact});
   }
  }
  if (candidates.length !== 1) throw refusal(candidates.length > 1 ? 'is ambiguous' : 'could not be verified from global listings');
@@ -207,11 +224,22 @@ 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'); }
+ if (owner.artifact) {
+  try { await input.adapters.fs.realpath(owner.spec); }
+  catch { throw new Error(`gentle-shell update: the main-channel build ${owner.spec} is missing, and this unpublished build cannot be reinstalled from the registry; run 'gentle-shell upgrade --channel release' and then 'gentle-shell upgrade --channel main' to rebuild it. No installation changed.`); }
+ }
  // 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 result = await input.adapters.run(owner.command, [...owner.prefix, ...args], {deadlineMs:20 * 60_000, cwd: input.cwd, stderrTail:4096});
+ if (!succeeded(result)) {
+  // One sanitized line of the manager's own error: npm prints it on stderr,
+  // pnpm 11 prints ERR_PNPM_* on stdout. Read as one text, stderr last, an
+  // error line in either stream wins over a stderr warning, stderr's on a tie.
+  const output = [result?.stdout, result?.stderrTail].filter(text => typeof text === 'string').join('\n');
+  const detail = setupErrorDetail(output, input.home, input.platform);
+  throw new Error(`gentle-shell update: ${owner.name} (${[owner.command, ...owner.prefix].join(' ')}) could not install ${owner.spec}${detail ? `\n${detail}` : ''}`);
+ }
  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.`);

package/scripts/verify-package-files.mjs

@@ -50,6 +50,29 @@ export const requiredPaths = [
   "assets/sounds/LICENSE.md",
   "docs/sound-notifications.md",
   "docs/sound-notifications-proposal.md",
+  "extensions/gentle-voice.ts",
+  "lib/voice-artifacts.ts",
+  "lib/voice-command.ts",
+  "lib/voice-install.ts",
+  "lib/voice-platform.ts",
+  "lib/voice-session.ts",
+  "lib/voice-ui.ts",
+  // The dictation worker is spawned by path, never imported, so nothing else
+  // would notice it missing from the packed tarball.
+  "scripts/voice-worker.cjs",
+  "docs/voice.md",
+  "extensions/gentle-design.ts",
+  "lib/gentle-design.ts",
+  // The design canvas server reads its page and scripts from assets/ by path.
+  "lib/design-canvas-server.ts",
+  "lib/design-open-browser.ts",
+  "lib/design-comments.ts",
+  "lib/design-handoffs.ts",
+  "lib/design-sources.ts",
+  "assets/design-canvas/index.html",
+  "assets/design-canvas/canvas.js",
+  "assets/design-canvas/canvas.css",
+  "assets/design-canvas/inspector.js",
   "scripts/npm-pack-result.mjs",
   "assets/orchestrator.md",
   "assets/orchestrator-delegation.md",
@@ -154,6 +177,7 @@ export const requiredPaths = [
   "skills/chained-pr/SKILL.md",
   "skills/cognitive-doc-design/SKILL.md",
   "skills/comment-writer/SKILL.md",
+  "skills/design/SKILL.md",
   "skills/gentle-ai/SKILL.md",
   "skills/issue-creation/SKILL.md",
   "skills/judgment-day/SKILL.md",
@@ -401,7 +425,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.2.0 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.3.1 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);
   }
@@ -446,7 +470,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.2.0 runtime).`);
+  console.log(`gentle-pi package resource check passed (${requiredPaths.length} files; ${Object.keys(contractHashes).length} exact byte-pinned contract artifacts for the v4.3.1 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;