gentle-pi 4.3.0 → 4.5.0

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

@@ -1054,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.
@@ -1197,8 +1246,9 @@ 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));" ^';
@@ -1317,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");

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/jobs-widget.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import test, { after, before } from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { JOBS_GLYPH, renderJobsCard, widgetJobs } from "../lib/jobs-widget.ts";
+import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// The Jobs sidebar card replaces the Jobs group the Status card used to print.
+// Rendering is pure, so it verifies without a TUI: newest job first, one row
+// per running job with its elapsed time, collapsible like Agents and Todos.
+
+// Width math counts every painted character, so these assertions use a plain
+// theme; colored roles are covered by the widget's paint calls, not here.
+const plainTheme = {
+	fg(_color: string, text: string) {
+		return text;
+	},
+	bold(text: string) {
+		return text;
+	},
+};
+
+const jobs = [
+	{ id: "job-2", label: "Watcher CI ronda 2", startedAt: 40_000 },
+	{ id: "job-1", label: "Build runtime", startedAt: 10_000 },
+];
+
+// The card style defaults to float; these assertions pin the outlined (neon)
+// panels unless a test switches the style itself.
+const initialCardStyle = cardStyle();
+before(() => setCardStyle(CARD_STYLE.NEON));
+after(() => setCardStyle(initialCardStyle));
+
+test("the jobs card lists running jobs newest first with elapsed time", () => {
+	const lines = renderJobsCard(jobs, plainTheme, 50, 100_000, { collapsed: false, collapseControl: true });
+	const text = lines.join("\n");
+	assert.match(text, new RegExp(`${JOBS_GLYPH} Jobs`));
+	assert.match(text, /2 running/);
+	const watcher = text.indexOf("Watcher CI ronda 2");
+	const build = text.indexOf("Build runtime");
+	assert.ok(watcher >= 0, "the newest job paints");
+	assert.ok(build > watcher, "newest first, matching the /gentle:jobs running group");
+	assert.match(text, /1m 0s/, "the 60s job shows its elapsed time");
+	assert.match(text, /1m 30s/, "the 90s job shows its elapsed time");
+	assert.match(text, /▾ Collapse/);
+	for (const line of lines) assert.ok(visibleWidth(stripAnsi(line)) <= 50, `row fits: ${stripAnsi(line)}`);
+});
+
+test("an empty job list paints nothing", () => {
+	assert.deepEqual(renderJobsCard([], plainTheme, 50, 100_000, { collapsed: false }), []);
+});
+
+test("a collapsed jobs card keeps the newest job and folds the rest", () => {
+	// Wide enough for the header to also fit the "ctrl+shift+j expand" hint.
+	const lines = renderJobsCard(jobs, plainTheme, 64, 100_000, { collapsed: true, collapseKey: "ctrl+shift+j", collapseControl: true });
+	const text = lines.join("\n");
+	assert.match(text, /Watcher CI ronda 2/);
+	assert.doesNotMatch(text, /Build runtime/);
+	assert.match(text, /… 1 more/);
+	assert.match(text, /ctrl\+shift\+j expand/);
+	assert.match(text, /▸ Expand/);
+});
+
+test("the collapse control is opt-in and the sort never mutates the snapshot", () => {
+	const snapshot = [{ id: "job-1", label: "Build runtime", startedAt: 10_000 }];
+	const lines = renderJobsCard(snapshot, plainTheme, 50, 100_000, { collapsed: false });
+	assert.doesNotMatch(lines.join("\n"), /Collapse|Expand/);
+	const sorted = widgetJobs(snapshot, 100_000);
+	assert.deepEqual(snapshot, [{ id: "job-1", label: "Build runtime", startedAt: 10_000 }]);
+	assert.equal(sorted[0]?.id, "job-1");
+});
+
+// Finished tails mirror the Agents card's results: an exit lingers for a
+// minute with the /gentle:jobs outcome glyph, its elapsed frozen at the end.
+
+const exitedJob = { id: "job-1", label: "Build runtime", startedAt: 10_000, status: "exited" as const, endedAt: 70_000, exitCode: 0 as number | null };
+
+function finishedJobs(): Array<typeof exitedJob> {
+	return [1, 2, 3, 4].map((n) => ({ ...exitedJob, id: `job-${n}`, label: `Job ${n}`, startedAt: n * 1_000, endedAt: 100_000 + n * 1_000 }));
+}
+
+test("a finished job lingers with a ✓ row and its elapsed frozen at the end", () => {
+	const lines = renderJobsCard([exitedJob], plainTheme, 50, 100_000, { collapsed: false });
+	const text = lines.join("\n");
+	assert.match(text, /✓\s+Build runtime/);
+	assert.match(text, /1m 0s/, "elapsed freezes at endedAt instead of ticking to 1m 30s");
+	assert.match(text, /1 finished/);
+	for (const line of lines) assert.ok(visibleWidth(stripAnsi(line)) <= 50, `row fits: ${stripAnsi(line)}`);
+});
+
+test("a nonzero exit paints ✗ and a stopped job paints –", () => {
+	const lines = renderJobsCard([
+		{ ...exitedJob, exitCode: 1 },
+		{ id: "job-2", label: "Watcher CI", startedAt: 5_000, status: "stopped", endedAt: 60_000 },
+	], plainTheme, 50, 100_000, { collapsed: false });
+	const text = lines.join("\n");
+	assert.match(text, /✗\s+Build runtime/);
+	assert.match(text, /–\s+Watcher CI/);
+	assert.match(text, /2 finished/);
+});
+
+test("a failed job rides the tail with the ✗ glyph", () => {
+	const lines = renderJobsCard([{ ...exitedJob, status: "failed" as const }], plainTheme, 50, 100_000, { collapsed: false });
+	const text = lines.join("\n");
+	assert.match(text, /✗\s+Build runtime/);
+	assert.match(text, /1m 0s/, "elapsed freezes at endedAt like the other outcomes");
+	assert.match(text, /1 finished/);
+});
+
+test("finished jobs past the TTL paint nothing", () => {
+	// now - endedAt lands exactly on the TTL: not fresh anymore.
+	assert.deepEqual(renderJobsCard([{ ...exitedJob, endedAt: 40_000 }], plainTheme, 50, 100_000, { collapsed: false }), []);
+});
+
+test("at most the three newest finished jobs survive", () => {
+	const jobs = finishedJobs();
+	const shown = widgetJobs(jobs, 105_000);
+	assert.deepEqual(shown.map((job) => job.id), ["job-4", "job-3", "job-2"]);
+	assert.deepEqual(jobs, finishedJobs(), "the TTL filter never mutates the snapshot");
+});
+
+test("running entries sort before the finished tail and never expire", () => {
+	const snapshot = [
+		{ ...exitedJob, id: "done", label: "Old build", startedAt: 1_000 },
+		{ id: "old", label: "Old run", startedAt: 1_000 },
+		{ id: "new", label: "New run", startedAt: 50_000 },
+	];
+	const shown = widgetJobs(snapshot, 100_000);
+	assert.deepEqual(shown.map((job) => job.id), ["new", "old", "done"]);
+});
+
+test("the subtitle mixes running and finished counts", () => {
+	const lines = renderJobsCard([
+		{ id: "job-1", label: "New run", startedAt: 50_000 },
+		{ id: "job-2", label: "Watcher CI", startedAt: 5_000, status: "stopped", endedAt: 60_000 },
+	], plainTheme, 50, 100_000, { collapsed: false });
+	assert.match(lines.join("\n"), /1 running · 1 finished/);
+});

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 {