gentle-pi 4.2.0 → 4.4.0

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 {
@@ -35,9 +38,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");
@@ -135,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 {
@@ -386,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
@@ -440,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/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

@@ -50,9 +50,33 @@ 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",
+  "assets/orchestrator-delegation-reference.md",
   "assets/orchestrator-tracking.md",
   "assets/orchestrator-verification.md",
   "assets/orchestrator-writer.md",
@@ -81,6 +105,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 +115,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 +124,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 +134,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,23 +159,25 @@ 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",
   "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",
@@ -395,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.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.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);
   }
@@ -440,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.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.3.1 runtime).`);
 }
 
 const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;