gentle-pi 4.2.0 → 4.4.0

package/tests/installer-windows-bootstrap.test.ts

@@ -653,13 +653,14 @@ test("native Windows entry: spaces, Unicode, CMD metacharacters and early missin
 		const scripts = join(f.root, "scripts"); mkdirSync(scripts);
 		// Observe the copied production entry's first PowerShell handle so the
 		// existing ownership-checked guard can reap it if the fixture times out.
-		writeFileSync(join(scripts, "bootstrap.cmd"), observeStage(readFileSync(new URL("../scripts/bootstrap.cmd", import.meta.url), "utf8")));
+		writeFileSync(join(scripts, "bootstrap.cmd"), observeStage(readFileSync(new URL("../scripts/bootstrap.cmd", import.meta.url), "utf8"), true));
 		const local = join(f.root, "home"); mkdirSync(local);
 		const env = { ...nativeEnv(f.root), LOCALAPPDATA: local };
 		// The same outer bound as every other production fragment (nativeCmd): a cold
 		// cmd.exe plus Windows PowerShell 5.1 start can exceed 5 s while the CI step runs
 		// the installer suites in parallel. The bundle stage itself has no deadline.
 		console.error("WINDOWS_ENTRY_PROBE_START timeoutMs=14000");
+		const startedAt = Date.now();
 		const started = performance.now();
 		const result = await nativeCmdFile(f.root, "scripts\\bootstrap.cmd", env, 14000);
 		console.error("WINDOWS_ENTRY_PROBE_RESULT", JSON.stringify({ elapsedMs: performance.now() - started, status: result.status, guardKilled: result.guardKilled, expectedDiagnostic: /No acquisition attempted/.test(result.stderr) }));
@@ -668,6 +669,8 @@ test("native Windows entry: spaces, Unicode, CMD metacharacters and early missin
 		assertNative(result, 1);
 		assert.match(result.stderr, /No acquisition attempted/);
 		assert.match(readFileSync(join(f.root, "process-records"), "utf8").trim(), /^[1-9][0-9]*\|[1-9][0-9]*$/, "the copied entry must expose its first PowerShell handle to fixture cleanup");
+		const readyMs = Number(readFileSync(join(f.root, "powershell-ready-ms"), "utf8"));
+		assert.ok(Number.isSafeInteger(readyMs) && readyMs >= startedAt && readyMs <= Date.now(), "the fixture must timestamp PowerShell executing its body");
 		assert.deepEqual(readdirSync(local), []);
 	} finally {
 		try { cleanNativeProcesses(f.root); } finally { f.cleanup(); }
@@ -1051,6 +1054,55 @@ test("the one-launch walk applies the single-path walk, per path, with its own f
 	assert.doesNotMatch(many, /Invoke-Expression|\biex\b|ScriptBlock\]::Create|EncodedCommand/);
 });
 
+test("storage metadata public adapters preserve verdicts and unexpected failures", () => {
+	const path = "D:\\metadata fixture\\tool.exe";
+	const env = { SystemRoot: "C:\\Windows" };
+	let calls = 0;
+	const single = (output: string) => verifyWindowsStorage(path, env, (_command: string, _args: string[], data: Record<string, string>) => {
+		calls++; assert.equal(data.GENTLE_WINDOWS_CHECK, path); return output;
+	});
+	if (process.platform === "win32") {
+		assert.equal(single("safe"), undefined);
+		for (const check of ["target-reparse", "parent-owner", "ancestor-acl-mask"]) {
+			assert.throws(() => single(`unsafe:${check}|${encoded(`${path}|||`)}`), (error: Error & { check?: string; detail?: { at: string } }) => error.check === check && error.detail?.at === path);
+		}
+		assert.throws(() => single("malformed"), /Windows ACL evidence rejected/);
+		assert.equal(calls, 5);
+		const failure = Object.assign(new Error("metadata read failed"), { code: "EACCES" });
+		assert.throws(() => verifyWindowsStorage(path, env, () => { throw failure; }), (error: unknown) => error === failure);
+	} else {
+		assert.throws(() => single("safe"), /Native Windows storage verification unavailable/);
+		assert.equal(calls, 0, "unsupported platforms reject before invoking the runner");
+	}
+	const paths = [path, "D:\\metadata fixture\\next.cmd"];
+	assert.deepEqual(windowsModule.verifyWindowsStorageMany(paths, env, { platform: "win32", processAdapter: (_command: string, _args: string[], data: Record<string, string>) => {
+		assert.equal(data.GENTLE_WINDOWS_CHECKS, paths.join("|")); return "unknown\nsafe";
+	} }), [{ check: "unchecked", at: path }, null]);
+});
+
+// Inspect scripts through the public process seam; never execute PowerShell.
+for (const mode of ["single", "batch"] as const) {
+	test(`storage metadata ${mode} uses throwing static attributes before ACL reads`, { skip: mode === "single" && process.platform !== "win32" ? "single-path script requires the real Windows platform" : false }, () => {
+		let script = "";
+		const processAdapter = (_command: string, args: string[], env: Record<string, string>) => {
+			script = args[4];
+			assert.equal(env[mode === "single" ? "GENTLE_WINDOWS_CHECK" : "GENTLE_WINDOWS_CHECKS"], "C:\\metadata\\node.exe");
+			return "safe";
+		};
+		if (mode === "single") verifyWindowsStorage("C:\\metadata\\node.exe", { SystemRoot: "C:\\Windows" }, processAdapter);
+		else windowsModule.verifyWindowsStorageMany(["C:\\metadata\\node.exe"], { SystemRoot: "C:\\Windows" }, { platform: "win32", processAdapter });
+		assert.ok(script.includes("$attributes = [IO.File]::GetAttributes($path);"));
+		const reparse = "if ($attributes -band [IO.FileAttributes]::ReparsePoint) { $detail = $path + '|||'; throw ($role + '-reparse') };";
+		const branch = "if ($attributes -band [IO.FileAttributes]::Directory) { $acl = [IO.Directory]::GetAccessControl($path) } else { $acl = [IO.File]::GetAccessControl($path) };";
+		assert.ok(script.includes(reparse));
+		assert.ok(script.includes(branch));
+		assert.ok(script.indexOf("GetAttributes($path)") < script.indexOf(reparse));
+		assert.ok(script.indexOf(reparse) < script.indexOf(branch));
+		assert.doesNotMatch(script, /Get-Item|\[IO\.(?:File|Directory)\]::Exists|FileInfo|DirectoryInfo|Refresh/);
+		assert.ok(script.includes(mode === "single" ? "} else { throw } }" : "} else { 'unknown' } }"));
+	});
+}
+
 // S6 decision fixtures: an in-memory folder tree and an injected walk verdict per
 // path, the same way the helper tests inject storage. `weak` maps a walked path
 // to the check its walk fails; every other walk passes.
@@ -1194,16 +1246,20 @@ test("production and fixture PowerShell never depend on autoloading Microsoft.Po
 		assert.match(source, /\[IO\.Directory\]::SetAccessControl\(/);
 	}
 	// Walks that may reach a file read it as a file, never through a directory API.
-	for (const source of [productionAclSources()[1], productionAclSources()[2]]) {
-		assert.match(source, /if \(\$item\.PSIsContainer\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
+	assert.match(productionAclSources()[1], /if \(\$item\.PSIsContainer\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
+	for (const source of [productionAclSources()[2], manyCheck()]) {
+		assert.match(source, /if \(\$attributes -band \[IO\.FileAttributes\]::Directory\) \{ \$acl = \[IO\.Directory\]::GetAccessControl\(\$path\) \} else \{ \$acl = \[IO\.File\]::GetAccessControl\(\$path\) \}/);
 	}
 });
 const psRecordLine = '  "$record = [Diagnostics.Process]::GetCurrentProcess(); [IO.File]::AppendAllText($env:GENTLE_FIXTURE_RECORDS,([string]$record.Id + [char]124 + [string]$record.StartTime.ToUniversalTime().Ticks + [Environment]::NewLine));" ^';
-function observeStage(stage: string) {
+// Entry-only telemetry: this timestamps execution of the PowerShell body, not
+// merely process creation. Keep it separate from the guard's PID/ticks records.
+const psReadyLine = '  "[IO.File]::WriteAllText([IO.Path]::Combine($env:GENTLE_FIXTURE_ROOT,\'powershell-ready-ms\'),[string][DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds());" ^';
+function observeStage(stage: string, entryReadiness = false) {
 	const lines = stage.split("\n");
 	const index = lines.findIndex((line) => line.includes("LanguageMode"));
 	assert.ok(index >= 0);
-	lines.splice(index + 1, 0, psRecordLine);
+	lines.splice(index + 1, 0, psRecordLine, ...(entryReadiness ? [psReadyLine] : []));
 	return lines.join("\n");
 }
 function cmdComposition(stages: string[]) {
@@ -1234,6 +1290,16 @@ test("native entry observation preserves the complete production batch", () => {
 	assert.equal(observed.filter((line) => line !== psRecordLine).join("\n"), source);
 });
 
+test("native entry readiness observation is opt-in and preserves production and ownership records", () => {
+	const source = readFileSync(new URL("../scripts/bootstrap.cmd", import.meta.url), "utf8");
+	const observed = observeStage(source, true).split("\n");
+	assert.equal(observed.filter((line) => line.includes("powershell-ready-ms")).length, 1);
+	assert.equal(observed.filter((line) => line === psRecordLine).length, 1);
+	assert.equal(observed.filter((line) => line !== psRecordLine && !line.includes("powershell-ready-ms")).join("\n"), source);
+	assert.doesNotMatch(observeStage(source), /powershell-ready-ms/);
+	assert.ok(observed.findIndex((line) => line.includes("powershell-ready-ms")) > observed.indexOf(psRecordLine));
+});
+
 test("native fixture compositions retain exact production fragments and no transport command", () => {
 	for (const marker of Object.values(stageMarkers)) {
 		const original = cmdStage(marker);
@@ -1301,9 +1367,17 @@ if (Test-Path -LiteralPath $env:GENTLE_FIXTURE_RECORDS) {
 if ($reaped) { [Console]::WriteLine('fixture guard reaped residual owned process') };
 exit 0;
 `;
+const GUARD_TIMEOUT_MS = 5000;
 function cleanNativeProcesses(root: string) {
 	const ps = join(process.env.SystemRoot!, "System32/WindowsPowerShell/v1.0/powershell.exe");
-	const result = spawnSync(ps, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", guardCommand], { env: nativeEnv(root), timeout: 5000, killSignal: "SIGKILL", encoding: "utf8", maxBuffer: 65536 });
+	const spawnGuard = (timeoutMs: number) => spawnSync(ps, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", guardCommand], { env: nativeEnv(root), timeout: timeoutMs, killSignal: "SIGKILL", encoding: "utf8", maxBuffer: 65536 });
+	// A hosted Windows runner can cold-start PowerShell slower than any fixed
+	// bound under load (run 40000806368: ETIMEDOUT at 5s, same commit green on
+	// rerun). The guard's job is cleanup, not a load measurement, and the guard
+	// is idempotent — it kills only verified owned processes and exits 0 — so a
+	// timeout is retried once with a wider bound before failing the fixture.
+	let result = spawnGuard(GUARD_TIMEOUT_MS);
+	if ((result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT") result = spawnGuard(GUARD_TIMEOUT_MS * 4);
 	assert.equal(result.error, undefined, "fixture guard must be bounded and available");
 	assert.equal(result.status, 0, `fixture guard must only clean verified owned processes: ${(result.stderr ?? "").slice(0, 4000)}`);
 	assert.ok(["", "fixture guard reaped residual owned process"].includes(result.stdout.trim()), "unexpected fixture guard output");
@@ -1314,10 +1388,22 @@ async function nativeCmd(root: string, stages: string[], env: NodeJS.ProcessEnv
 	return nativeCmdFile(root, "fixture.cmd", env, limit);
 }
 async function nativeCmdFile(root: string, file: string, env: NodeJS.ProcessEnv, limit = 5000): Promise<NativeResult> {
+	const startedAt = Date.now();
 	const started = performance.now();
 	const trace = (phase: string, detail: Record<string, unknown> = {}) => {
 		if (file === "scripts\\bootstrap.cmd") console.error("WINDOWS_ENTRY_PHASE", JSON.stringify({ phase, elapsedMs: performance.now() - started, limit, ...detail }));
 	};
+	// Wall-clock timestamps share an epoch with PowerShell. These measurements
+	// are diagnostic only; the monotonic outer deadline is never reset. Emit
+	// the split before synchronous guard cleanup can inflate execution time.
+	const traceEntryTiming = () => {
+		if (file !== "scripts\\bootstrap.cmd") return;
+		const readyPath = join(root, "powershell-ready-ms");
+		const finishedAt = Date.now();
+		const readyMs = existsSync(readyPath) ? Number(readFileSync(readyPath, "utf8")) : NaN;
+		const valid = Number.isSafeInteger(readyMs) && readyMs >= startedAt && readyMs <= finishedAt;
+		trace("entry-timing", { readyObserved: valid, startupMs: valid ? readyMs - startedAt : null, executionMs: valid ? finishedAt - readyMs : null });
+	};
 	trace("spawn-request");
 	const child = spawn(join(process.env.SystemRoot!, "System32/cmd.exe"), ["/d", "/c", file], { cwd: root, env, stdio: ["ignore", "pipe", "pipe"] });
 	let stdout = ""; let stderr = ""; let guardKilled = false;
@@ -1327,6 +1413,7 @@ async function nativeCmdFile(root: string, file: string, env: NodeJS.ProcessEnv,
 	const result = await new Promise<NativeResult>((resolveChild, reject) => {
 		const timer = setTimeout(() => {
 			guardKilled = true;
+			traceEntryTiming();
 			trace("guard-fired", { recordExists: existsSync(join(root, "process-records")), diagnosticSeen: /No acquisition attempted/.test(stderr) });
 			try { cleanNativeProcesses(root); } catch (error) { guardError = error; }
 			child.kill("SIGKILL");
@@ -1341,7 +1428,7 @@ async function nativeCmdFile(root: string, file: string, env: NodeJS.ProcessEnv,
 			if (!/No acquisition attempted/.test(before) && /No acquisition attempted/.test(stderr)) trace("missing-bundle-diagnostic");
 			if (stderr.length > 1048576) { guardError = new Error("Fixture output limit"); child.kill("SIGKILL"); } });
 		child.once("error", (error) => { clearTimeout(timer); reject(error); });
-		child.once("close", (status) => { trace("cmd-close", { status, guardKilled }); clearTimeout(timer); resolveChild({ status, stdout, stderr, guardKilled }); });
+		child.once("close", (status) => { if (!guardKilled) traceEntryTiming(); trace("cmd-close", { status, guardKilled }); clearTimeout(timer); resolveChild({ status, stdout, stderr, guardKilled }); });
 	});
 	const residualReaped = cleanNativeProcesses(root);
 	assert.equal(residualReaped, false, "production must reap its own recorded children; fixture cleanup cannot mask a failure");

package/tests/installer-windows-diagnostics.test.ts

@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
+import { getSystemErrorName } from 'node:util';
+import { windowsProcessCheck, windowsBootstrapReason } from '../scripts/installer-windows.mjs';
+
+// Only owned inert Node children. Never invoke PowerShell, ACL/storage or setup.
+const base = resolve('odd/checks/issue-1921-windows-prerequisite-diagnostics');
+mkdirSync(base, { recursive: true });
+const root = mkdtempSync(join(base, 'inert-'));
+const fixture = join(root, 'child.mjs');
+writeFileSync(fixture, `import { writeSync } from 'node:fs';
+const mode = process.argv[2];
+if (mode === 'cap') { writeSync(2, 'overflow fixture\\n'); writeSync(1, 'x'.repeat(2*1024*1024)); }
+else if (mode === 'success') { writeSync(1, '  ' + JSON.stringify({cwd:process.cwd()}) + ' \\n'); }
+else { writeSync(1, process.argv[3]); writeSync(2, process.argv[4] ?? ''); process.exit(7); }
+`);
+const env = { SystemRoot: process.env.SystemRoot ?? process.env.SYSTEMROOT ?? 'C:\\Windows',
+  PATH: dirname(process.execPath), DIAGNOSTIC_SECRET: 'must-not-retain-env' };
+function failure(command: string, args: string[]): any {
+  let caught: any;
+  try { windowsProcessCheck(command, args, env); } catch (error) { caught = error; }
+  assert.equal(caught?.message, 'Windows prerequisite process failed');
+  assert.equal(windowsBootstrapReason(caught, 'tools-storage'), 'process-failed (tools-storage)');
+  return caught;
+}
+function causeOf(error: any): any {
+  assert.ok(error.cause instanceof Error, 'standard cause Error must survive existing cause.stack observer');
+  const cause = error.cause;
+  assert.deepEqual(Object.keys(cause).sort(), ['error', 'signal', 'status', 'stderr', 'stdout']);
+  assert.ok(cause.stack.length <= 8192);
+  assert.ok(cause.stdout.length <= 1024 && cause.stderr.length <= 1024);
+  assert.ok(!cause.stack.includes(root) && !cause.stack.includes('installer-windows.mjs'));
+  assert.ok(!cause.error?.message?.includes(root));
+  assert.ok(!JSON.stringify(cause).includes(env.DIAGNOSTIC_SECRET));
+  return cause;
+}
+
+test('metadata: nonzero exit keeps bounded streams and usable cause.stack', () => {
+  const args = [fixture, 'text', 'controlled stdout\n', 'controlled stderr\n', 'private-argv-sentinel'];
+  const before = structuredClone({ args, env });
+  const error = failure(process.execPath, args), cause = causeOf(error);
+  assert.equal(cause.status, 7); assert.equal(cause.signal, null); assert.equal(cause.error, null);
+  assert.equal(cause.stdout, 'controlled stdout\n'); assert.equal(cause.stderr, 'controlled stderr\n');
+  assert.match(error.cause?.stack, /"status":7/);
+  assert.match(error.cause?.stack, /controlled stderr/);
+  assert.ok(!JSON.stringify(cause).includes('private-argv-sentinel'));
+  assert.deepEqual({ args, env }, before);
+});
+
+test('metadata: missing synthetic executable preserves ENOENT without raw spawn error', () => {
+  const cause = causeOf(failure(join(root, 'missing.exe'), ['private-argv-sentinel']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, null);
+  assert.deepEqual(Object.keys(cause.error).sort(), ['code', 'errno', 'message', 'name']);
+  assert.equal(cause.error.code, 'ENOENT'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOENT');
+  assert.ok(cause.error.message.length <= 256);
+  assert.equal(cause.stdout, ''); assert.equal(cause.stderr, '');
+  assert.match(cause.stack, /ENOENT/);
+});
+
+test('metadata: output overflow preserves ENOBUFS and actual kill signal without waiting15s', () => {
+  const cause = causeOf(failure(process.execPath, [fixture, 'cap']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, 'SIGKILL');
+  assert.equal(cause.error.code, 'ENOBUFS'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOBUFS');
+  assert.equal(cause.stderr, 'overflow fixture\n');
+  assert.match(cause.stack, /ENOBUFS/);
+});
+
+test('privacy: private paths, SID/encoded ACL detail and sensitive output are suppressed; caps hold', () => {
+  const privateLines = ['visible', 'C:\\Users\\Synthetic Person\\private.txt', '/home/synthetic/private.txt',
+    'S-1-5-21-111-222-333-1001', 'DOMAIN\\synthetic', 'unsafe:target-owner|YWJjZA=='];
+  const cause = causeOf(failure(process.execPath, [fixture, 'text', privateLines.join('\n'),
+    'Authorization: Bearer synthetic-secret\ncontinuation-must-not-survive']));
+  assert.match(cause.stdout, /visible/);
+  for (const value of privateLines.slice(1)) assert.ok(!cause.stdout.includes(value));
+  assert.ok(!cause.stack.includes('synthetic-secret') && !cause.stack.includes('continuation-must-not-survive'));
+  const bounded = causeOf(failure(process.execPath, [fixture, 'text', 'safe line\n'.repeat(300), 'safe error\n'.repeat(300)]));
+  assert.equal(bounded.stdout.length, 1024); assert.equal(bounded.stderr.length, 1024);
+});
+
+test('PR privacy: credential markers recognize underscore separators without changing API_KEY handling', () => {
+  for (const marker of ['GITHUB_TOKEN', 'PREFIX_API_KEY_SUFFIX', 'AWS_ACCESS_KEY_ID', 'API_KEY', 'access_key']) {
+    const payload = `${marker}=synthetic-value-1921\ncontinuation-value-1921`;
+    assert.equal(payload.includes('\\'), false, 'actual argv bytes must not trigger the path filter');
+    const cause = causeOf(failure(process.execPath,
+      ['-e', 'process.stderr.write(process.argv[1]);process.exit(7)', payload]));
+    assert.equal(cause.status, 7);
+    assert.equal(cause.stderr, '[redacted]');
+    assert.ok(!cause.stack.includes('synthetic-value-1921') && !cause.stack.includes('continuation-value-1921'));
+  }
+});
+
+test('PR privacy: missing bare executable identity never enters cause message or stack', () => {
+  const command = `fixture-private-executable-1921-${basename(root)}`;
+  assert.equal(parse(command).root, '', 'a path-based probe would miss the bare-name leak');
+  const cause = causeOf(failure(command, ['private-argv-sentinel']));
+  assert.equal(cause.status, null); assert.equal(cause.signal, null);
+  assert.equal(cause.error.code, 'ENOENT'); assert.equal(cause.error.name, 'Error');
+  assert.equal(getSystemErrorName(cause.error.errno), 'ENOENT');
+  assert.ok(!JSON.stringify(cause).includes(command) && !cause.stack.includes(command));
+  assert.match(cause.error.message, /ENOENT/);
+});
+
+test('legacy: neutral cwd, trimmed success and pre-spawn CMD/BAT rejection stay exact', () => {
+  assert.equal(windowsProcessCheck(process.execPath, [fixture, 'success'], env), JSON.stringify({ cwd: parse(process.execPath).root }));
+  for (const suffix of ['.CMD', '.bat']) assert.throws(() => windowsProcessCheck(join(root, `absent${suffix}`), [], env),
+    error => error instanceof Error && error.message === 'Unproven command interpreter target' && error.cause === undefined);
+});

package/tests/main-channel-upgrade.test.ts

@@ -4,7 +4,7 @@ import * as fsPromises from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { CHANNEL_SCHEMA, MainChannelError, ownerManager, readChannel, removeGlobalShell, runUpgrade, writeChannel } from "../scripts/main-channel.mjs";
+import { CHANNEL_SCHEMA, GENTLE_AI_MODULE, MainChannelError, ownerManager, readChannel, removeGlobalShell, runUpgrade, writeChannel } from "../scripts/main-channel.mjs";
 import { requirements } from "../scripts/installer-preflight.mjs";
 
 const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
@@ -19,7 +19,8 @@ type Invocation = { command: string; prefix: string[] } | null;
  * `which` finds `<bin>/<name><suffix>`; `invocation`, when given, is the host's adapter. */
 function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell: SHELL_SHA }, tools = ["go", "pnpm", "npm"], platform = "darwin",
 	bin = "/usr/bin", suffix = "", invocation = undefined as ((name: string) => Promise<Invocation>) | undefined, fs = fsPromises as typeof fsPromises,
-	migrate = undefined as ((input: { latest: string; owner: () => Promise<unknown> }) => Promise<unknown>) | undefined } = {}) {
+	migrate = undefined as ((input: { latest: string; owner: () => Promise<unknown> }) => Promise<unknown>) | undefined,
+	failGoInstall = false, failShellInstall = false } = {}) {
 	// owner "linked": `npm link` of a source checkout, so npm's global entry points outside npm's root.
 	const root = realpathSync(mkdtempSync(join(tmpdir(), "upgrade-")));
 	const home = join(root, "home");
@@ -50,13 +51,22 @@ function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell
 		}
 		calls.push({ command, argv });
 		if (argv[0] === "install" && argv[1]?.includes("gentle-ai/v4/cmd/gentle-ai@")) {
+			if (failGoInstall) return { code: 1, stdout: "" };
 			mkdirSync(options.env!.GOBIN, { recursive: true });
 			for (const name of ["gentle-ai", "gentle-ai.exe"]) writeFileSync(join(options.env!.GOBIN, name), "#!/bin/sh\n", { mode: 0o755 });
 			return { code: 0, stdout: "" };
 		}
 		if (argv[0] === "version" && command === `${bin}/go`) {
+			if (argv[1] === "-m") {
+				const commit = String(argv[2] ?? "").split("/").at(-2) ?? "";
+				return { code: 0, stdout: `${command} (binary)\n\tmod\t${GENTLE_AI_MODULE}\tv4.0.1-0.20261008202137-${commit.slice(0, 12)}\th1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=\n` };
+			}
 			return { code: 0, stdout: `go version go${requirements.go} ${platform}/amd64\n` };
 		}
+		if (argv[0] === "list" && command === `${bin}/go`) {
+			const commit = String(argv[3] ?? "").slice(`${GENTLE_AI_MODULE}@`.length);
+			return { code: 0, stdout: JSON.stringify({ Path: GENTLE_AI_MODULE, Version: `v4.0.1-0.20261008202137-${commit.slice(0, 12)}`, Origin: { VCS: "git", URL: "https://github.com/gentleman-programming/gentle-ai", Hash: commit } }) };
+		}
 		if (argv[0] === "version") {
 			const sha = command.split("/").at(-2) ?? "";
 			return { code: 0, stdout: `gentle-ai 4.0.1-0.20261008202137-${sha.slice(0, 12)}\n` };
@@ -65,6 +75,7 @@ function world({ owner = "pnpm", latest = "4.1.0", commits = { ai: AI_SHA, shell
 			writeFileSync(join(argv[argv.indexOf("-C") + 1], "package.json"), JSON.stringify({ name: "gentle-pi", version: "4.1.0", scripts: { prepack: "x" } }));
 			return { code: 0, stdout: "" };
 		}
+		if (failShellInstall && argv.includes("-g") && argv.some((arg) => arg.endsWith(".tgz"))) return { code: 1, stdout: "" };
 		if (argv.includes("pack")) {
 			const version = JSON.parse(readFileSync(join(options.cwd!, "package.json"), "utf8")).version;
 			writeFileSync(join(argv[argv.indexOf("--pack-destination") + 1], `gentle-pi-${version}.tgz`), "tgz");
@@ -186,6 +197,225 @@ test("a main install rebuilds only what moved on main and records the new commit
 	} finally { w.cleanup(); }
 });
 
+// #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 succeed.
+const GO_INSTALL_FAILED = `main-gentle-ai-build-failed: go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@${NEW_AI} failed`;
+const PRIOR_REGISTRATION = JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: "/prior/main/gentle-ai" });
+const NEW_SHELL_TGZ = (home: string) => join(home, ".pi", "gentle-ai", "main", "packages", "gentle-pi-4.1.0-main.333333333333.tgz");
+async function onPriorMain(w: ReturnType<typeof world>) {
+	await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+	writeFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), PRIOR_REGISTRATION);
+	return () => ({ channel: readFileSync(join(w.home, ".pi", "gentle-ai", "channel.json"), "utf8"), registration: readFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8") });
+}
+
+test("a failed Gentle AI build still installs the main Shell that moved, records no channel and names the retry", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, failGoInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-gentle-ai-build-failed");
+			assert.equal(error.message, `${GO_INSTALL_FAILED}; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish`);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+		assert.deepEqual(JSON.parse(before.registration), JSON.parse(PRIOR_REGISTRATION));
+	} finally { w.cleanup(); }
+});
+
+test("a Go that cannot be obtained for the Gentle AI build still installs the main Shell that moved", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, tools: ["pnpm", "npm"] });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-requires-tools");
+			assert.match(error.message, /^main-requires-tools: the main channel builds Gentle AI with Go .*Unexpected Go acquisition in sandboxed upgrade fixture.*; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish$/);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("after a fail-forward, the retry from the new Shell builds Gentle AI and records both commits", posixOnly, async () => {
+	// The first copy of the built binary fails (as a rejected build would); the retry's succeeds.
+	let copies = 0;
+	const fs = { ...fsPromises, copyFile: async (...args: Parameters<typeof fsPromises.copyFile>) => {
+		if (copies++ === 0) throw new MainChannelError("main-gentle-ai-unverified", "first attempt rejected");
+		return fsPromises.copyFile(...args);
+	} } as typeof fsPromises;
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => error.code === "main-gentle-ai-unverified");
+		assert.deepEqual(files(), before);
+		// The retry is simulated as the new Shell's run: the same runUpgrade with the new
+		// version (the installed package itself is not executed). No channel was recorded,
+		// so it rebuilds Gentle AI and repacks the Shell before recording both commits.
+		w.lines.length = 0;
+		assert.equal(await w.upgrade([], "4.1.0-main.333333333333"), 0);
+		assert.deepEqual(w.lines, ["Updated to the latest main: Gentle Shell 333333333333, Gentle AI 222222222222."]);
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`, `/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "main", shellCommit: NEW_SHELL, gentleAiCommit: NEW_AI });
+		assert.equal(JSON.parse(readFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8")).path,
+			join(w.home, ".pi", "gentle-ai", "main", "gentle-ai", NEW_AI, "gentle-ai"));
+		// A third run is a no-op: both commits are current.
+		w.lines.length = 0;
+		assert.equal(await w.upgrade([], "4.1.0-main.333333333333"), 0);
+		assert.deepEqual(w.lines, ["gentle-shell is already at the latest main: Gentle Shell 333333333333, Gentle AI 222222222222."]);
+	} finally { w.cleanup(); }
+});
+
+test("a failed Gentle AI build with the main Shell already current fails as before: nothing installed or recorded", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: SHELL_SHA }, failGoInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "main-gentle-ai-build-failed");
+			assert.equal(error.message, GO_INSTALL_FAILED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("when the Gentle AI build and the Shell install both fail, the Shell failure is reported with the Gentle AI one", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, failGoInstall: true, failShellInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "upgrade-install-failed");
+			assert.equal(error.message, `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (${GO_INSTALL_FAILED})`);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+// An ordinary failure that is not a MainChannelError (EACCES) keeps the retry advice and both errors.
+const eacces = (what: string) => Object.assign(new Error(`EACCES: permission denied, ${what}`), { code: "EACCES" });
+const COPY_DENIED = eacces("copyfile");
+const MANIFEST_DENIED = eacces("open package.json");
+const deniedFs = ({ copy = false, manifest = false }) => ({ ...fsPromises,
+	copyFile: async (...args: Parameters<typeof fsPromises.copyFile>) => { if (copy) throw COPY_DENIED; return fsPromises.copyFile(...args); },
+	readFile: (async (path: string, options?: unknown) => {
+		if (manifest && String(path).endsWith(join(".source", "src", "package.json"))) throw MANIFEST_DENIED;
+		return fsPromises.readFile(path, options as never);
+	}) as typeof fsPromises.readFile }) as typeof fsPromises;
+
+test("an ordinary error in the Gentle AI step still installs the main Shell that moved and names the retry", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: deniedFs({ copy: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.ok(error instanceof MainChannelError);
+			assert.equal(error.code, "main-upgrade-incomplete");
+			assert.equal(error.message, "main-upgrade-incomplete: EACCES: permission denied, copyfile; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish");
+			assert.equal(error.cause, COPY_DENIED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+		assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("ordinary errors in both steps report the Shell error with the Gentle AI one", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: deniedFs({ copy: true, manifest: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.ok(error instanceof MainChannelError);
+			assert.equal(error.code, "main-upgrade-incomplete");
+			assert.equal(error.message, "main-upgrade-incomplete: EACCES: permission denied, open package.json; Gentle AI was not updated either (EACCES: permission denied, copyfile)");
+			assert.equal(error.cause, MANIFEST_DENIED);
+			return true;
+		});
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+test("an ordinary error in the Gentle AI step with the main Shell already current is rethrown unchanged", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: SHELL_SHA }, fs: deniedFs({ copy: true }) });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: Error) => error === COPY_DENIED);
+		assert.deepEqual(w.installs(), []);
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
+// A rejection that is not an Error, even a falsy one, is still a failed Gentle AI step.
+const rejectingCopy = (value: unknown) => ({ ...fsPromises, copyFile: async () => { throw value; } }) as typeof fsPromises;
+
+test("a falsy rejection in the Gentle AI step still records no channel and names the retry", posixOnly, async () => {
+	for (const value of [undefined, null, 0, false]) {
+		const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy(value) });
+		try {
+			const files = await onPriorMain(w);
+			const before = files();
+			await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+				assert.ok(error instanceof MainChannelError);
+				assert.equal(error.code, "main-upgrade-incomplete");
+				assert.equal(error.message, `main-upgrade-incomplete: ${String(value)}; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish`);
+				return true;
+			});
+			assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${NEW_SHELL_TGZ(w.home)} --allow-build=gentle-pi`]);
+			assert.deepEqual(w.lines, ["Updated Gentle Shell to the latest main (333333333333); Gentle AI was not updated."]);
+			assert.deepEqual(files(), before);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("a rejection that is not an Error but has a message keeps that message", posixOnly, async () => {
+	for (const failShellInstall of [false, true]) {
+		const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy({ message: "EACCES: copy denied", code: "EACCES" }), failShellInstall });
+		try {
+			const files = await onPriorMain(w);
+			const before = files();
+			await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+				assert.equal(error.message, failShellInstall
+					? `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (EACCES: copy denied)`
+					: "main-upgrade-incomplete: EACCES: copy denied; Gentle Shell was updated to main 333333333333 but Gentle AI was not: run gentle-shell upgrade --channel main to finish");
+				return true;
+			});
+			assert.deepEqual(files(), before);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("a null rejection in the Gentle AI step is kept when the Shell install fails too", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL }, fs: rejectingCopy(null), failShellInstall: true });
+	try {
+		const files = await onPriorMain(w);
+		const before = files();
+		await assert.rejects(w.upgrade([], "4.0.0-main.6e7e3a18f794"), (error: MainChannelError) => {
+			assert.equal(error.code, "upgrade-install-failed");
+			assert.equal(error.message, `upgrade-install-failed: pnpm could not install ${NEW_SHELL_TGZ(w.home)}; Gentle AI was not updated either (null)`);
+			return true;
+		});
+		assert.deepEqual(w.lines, []);
+		assert.deepEqual(files(), before);
+	} finally { w.cleanup(); }
+});
+
 test("a main install whose Gentle AI did not move rebuilds only Gentle Shell", posixOnly, async () => {
 	const w = world({ commits: { ai: AI_SHA, shell: NEW_SHELL } });
 	try {