gentle-pi 4.0.0 → 4.2.0

package/tests/jobs-view.test.ts

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { JobRecord } from "../lib/background-jobs.ts";
+import { JobsView } from "../lib/jobs-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+const theme = { fg: (_role: string, text: string) => text };
+
+function job(overrides: Partial<JobRecord> & Pick<JobRecord, "id">): JobRecord {
+	return {
+		kind: "command",
+		label: overrides.id,
+		command: `run ${overrides.id}`,
+		cwd: "/repo",
+		ownerSessionId: "s1",
+		outputPath: `/tmp/jobs/${overrides.id}.log`,
+		startedAt: 0,
+		status: "running",
+		tail: [],
+		...overrides,
+	};
+}
+
+function harness(jobs: JobRecord[], rows = 14) {
+	const stopped: string[] = [];
+	let closed = 0;
+	let renders = 0;
+	const view = new JobsView({
+		theme,
+		rows: () => rows,
+		jobs: () => jobs,
+		now: () => 125_000,
+		onStop: (selected) => { stopped.push(selected.id); },
+		onClose: () => { closed += 1; },
+		requestRender: () => { renders += 1; },
+	});
+	const screen = (width = 100) => view.render(width).map(stripAnsi);
+	return { view, screen, stopped, closed: () => closed, renders: () => renders };
+}
+
+test("the split view lists this session's jobs beside the selected job's details and output tail", () => {
+	const h = harness([
+		job({ id: "job-1", label: "CI for PR 1834", command: "gh run watch 42 --exit-status", tail: ["check lint: pass", "check test: pending"] }),
+		job({ id: "job-2", label: "build", status: "exited", exitCode: 1, endedAt: 4_000 }),
+	]);
+	try {
+		const lines = h.screen();
+		assert.equal(lines.length, 14, "the overlay fills the terminal height");
+		for (const line of lines) assert.equal(visibleWidth(line), 100, "every row spans the full width");
+		const text = lines.join("\n");
+		assert.match(lines[0]!, /Jobs · 1 running · 1 finished/);
+		assert.match(text, /◐ CI for PR 1834 +2m 5s/);
+		assert.match(text, /✗ build +4s/);
+		assert.match(text, /gh run watch 42 --exit-status/);
+		assert.match(text, /running/);
+		assert.match(text, /\/tmp\/jobs\/job-1\.log/);
+		assert.match(text, /check test: pending/);
+		assert.match(lines.at(-2)!, /s Stop/);
+	} finally { h.view.dispose(); }
+});
+
+test("j/k move the selection, s stops only a running job, and q closes", () => {
+	const h = harness([job({ id: "job-1" }), job({ id: "job-2", status: "exited", exitCode: 0, endedAt: 1_000, tail: ["done"] })]);
+	try {
+		h.view.handleInput("j");
+		const text = h.screen().join("\n");
+		assert.match(text, /exited with code 0/);
+		assert.match(text, /done/);
+		assert.doesNotMatch(h.screen().at(-2)!, /s Stop/, "a finished job offers no stop");
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, []);
+		h.view.handleInput("k");
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, ["job-1"]);
+		h.view.handleInput("q");
+		assert.equal(h.closed(), 1);
+	} finally { h.view.dispose(); }
+});
+
+test("jobs show running first and newest first within each group without changing source order", () => {
+	const jobs = [
+		job({ id: "old-finished", status: "exited", exitCode: 0, startedAt: 1_000, endedAt: 2_000 }),
+		job({ id: "old-running", startedAt: 3_000 }),
+		job({ id: "new-finished", status: "stopped", startedAt: 9_000, endedAt: 10_000 }),
+		job({ id: "new-running", startedAt: 5_000 }),
+	];
+	const h = harness(jobs);
+	try {
+		const lines = h.screen();
+		const names = ["new-running", "old-running", "new-finished", "old-finished"];
+		const positions = names.map((name) => lines.findIndex((line) => line.includes(name)));
+		assert.ok(positions.every((index, i) => index > 0 && (i === 0 || index > positions[i - 1]!)));
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, ["new-running"], "the default selection follows display order");
+		h.view.handleInput("j");
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, ["new-running", "old-running"], "navigation follows the same sorted order");
+		jobs.push(job({ id: "latest-running", startedAt: 11_000 }));
+		assert.match(h.screen().join("\n"), /› ◐ old-running/, "a new job preserves selection by ID");
+		assert.deepEqual(jobs.map((entry) => entry.id), ["old-finished", "old-running", "new-finished", "new-running", "latest-running"]);
+	} finally { h.view.dispose(); }
+});
+
+test("initial selection survives new jobs and completion before any keyboard navigation", () => {
+	const first = job({ id: "job-A", startedAt: 1_000 });
+	const jobs = [first];
+	const h = harness(jobs);
+	try {
+		assert.match(h.screen().join("\n"), /› ◐ job-A/);
+		jobs.push(job({ id: "job-B", startedAt: 2_000 }));
+		assert.match(h.screen().join("\n"), /› ◐ job-A/, "a newly started job does not steal selection");
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, ["job-A"], "stop still targets the initially selected job");
+		first.status = "exited";
+		first.exitCode = 0;
+		first.endedAt = 3_000;
+		assert.match(h.screen().join("\n"), /› ✓ job-A/, "completion does not steal selection");
+		assert.match(h.screen().join("\n"), /exited with code 0/);
+		h.view.handleInput("s");
+		assert.deepEqual(h.stopped, ["job-A"], "stop on a finished selection does not target another running job");
+		assert.deepEqual(jobs.map((entry) => entry.id), ["job-A", "job-B"]);
+	} finally { h.view.dispose(); }
+});
+
+test("an empty session says so", () => {
+	const h = harness([]);
+	try {
+		const text = h.screen().join("\n");
+		assert.match(text, /Jobs · 0 running · 0 finished/);
+		assert.match(text, /No background jobs in this session/);
+	} finally { h.view.dispose(); }
+});
+
+test("a narrow terminal shows the list, and tab toggles the selected job's details", () => {
+	const h = harness([job({ id: "job-1", label: "ci", command: "gh run watch 7", tail: ["waiting"] })]);
+	try {
+		let text = h.screen(40).join("\n");
+		assert.match(text, /◐ ci/);
+		assert.doesNotMatch(text, /gh run watch 7/);
+		h.view.handleInput("\t");
+		text = h.screen(40).join("\n");
+		assert.match(text, /gh run watch 7/);
+		assert.match(text, /waiting/);
+		h.view.handleInput("\u001b");
+		assert.equal(h.closed(), 0, "escape from details goes back to the list first");
+		assert.doesNotMatch(h.screen(40).join("\n"), /gh run watch 7/);
+		h.view.handleInput("\u001b");
+		assert.equal(h.closed(), 1);
+	} finally { h.view.dispose(); }
+});
+
+test("a monitor shows its kind and event count in the list and details", () => {
+	const h = harness([job({ id: "job-1", kind: "monitor", label: "errors", command: "tail -f app.log | grep ERROR", events: 3, tail: ["ERROR x"] })]);
+	try {
+		const text = h.screen().join("\n");
+		assert.match(text, /◉ errors/);
+		assert.match(text, /Status +running · .* · 3 events/);
+	} finally { h.view.dispose(); }
+});

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

@@ -0,0 +1,395 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+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 { requirements } from "../scripts/installer-preflight.mjs";
+
+const AI_SHA = "1f9d5e6423e37f7d2316859045f379ba9b5d8c3a";
+const SHELL_SHA = "6e7e3a18f794223396527a54c7c36d19c7d236c6";
+const NEW_AI = "2222222222222222222222222222222222222222";
+const NEW_SHELL = "3333333333333333333333333333333333333333";
+const posixOnly = { skip: process.platform === "win32" };
+type Call = { command: string; argv: string[] };
+type Invocation = { command: string; prefix: string[] } | null;
+
+/** A sandboxed home with a pnpm- or npm-owned package root and fake network/processes.
+ * `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 } = {}) {
+	// 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");
+	const pnpmHome = join(root, "pnpm");
+	const npmRoot = join(root, "npm", "lib", "node_modules");
+	mkdirSync(npmRoot, { recursive: true });
+	const packageRoot = owner === "pnpm" ? join(pnpmHome, "global", "v11", "x", "node_modules", "gentle-pi")
+		: owner === "npm" ? join(npmRoot, "gentle-pi") : join(root, "checkout");
+	mkdirSync(packageRoot, { recursive: true });
+	mkdirSync(home);
+	const ctx = { env: { PNPM_HOME: pnpmHome }, home };
+	const calls: Call[] = [];
+	const lines: string[] = [];
+	const fetches: string[] = [];
+	const fetch = async (url: string) => {
+		fetches.push(url);
+		if (url === "https://registry.npmjs.org/gentle-pi/latest") return { ok: latest !== "", status: latest ? 200 : 503, json: async () => ({ version: latest }) };
+		if (url.endsWith("/gentle-ai/commits/main")) return { ok: true, status: 200, text: async () => commits.ai };
+		if (url.endsWith("/gentle-shell/commits/main")) return { ok: true, status: 200, text: async () => commits.shell };
+		if (url.startsWith("https://codeload.github.com/")) return { ok: true, status: 200, arrayBuffer: async () => new TextEncoder().encode("src").buffer };
+		throw new Error(`unexpected fetch ${url}`);
+	};
+	const roots: Call[] = [];
+	const run = async (command: string, argv: string[], options: { env?: Record<string, string>; cwd?: string }) => {
+		if (argv.slice(-2).join(" ") === "root -g") {
+			roots.push({ command, argv });
+			return command === "/usr/bin/npm" || command.endsWith("node.exe") ? { code: 0, stdout: `${npmRoot}\n` } : { code: 1, stdout: "" };
+		}
+		calls.push({ command, argv });
+		if (argv[0] === "install" && argv[1]?.includes("gentle-ai/v4/cmd/gentle-ai@")) {
+			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`) {
+			return { code: 0, stdout: `go version go${requirements.go} ${platform}/amd64\n` };
+		}
+		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` };
+		}
+		if (command === "tar" || command.endsWith("tar.exe")) {
+			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 (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");
+		}
+		return { code: 0, stdout: "" };
+	};
+	const which = async (name: string) => (tools.includes(name) ? `${bin}/${name}${name === "go" ? "" : suffix}` : null);
+	const upgrade = (args: string[], currentVersion = "4.0.0") => runUpgrade({ args, ctx, platform, packageRoot, currentVersion,
+		adapters: { fetch, run, fs, which,
+			acquireGo: async () => { throw new Error("Unexpected Go acquisition in sandboxed upgrade fixture"); },
+			...(invocation ? { invocation } : {}), ...(migrate ? { migrate } : {}) }, out: (line: string) => lines.push(line) });
+	const installs = () => calls.filter((call) => call.argv.some((arg) => ["add", "install"].includes(arg)) && !call.argv.some((arg) => arg.includes("cmd/gentle-ai@")))
+		.map((call) => `${call.command} ${call.argv.join(" ")}`);
+	const manager = (command?: string) => ownerManager({ ctx, platform, packageRoot, adapters: { fs, run, which, ...(invocation ? { invocation } : {}) },
+		...(command === undefined ? {} : { command }) });
+	return { root, home, ctx, calls, roots, lines, fetches, upgrade, installs, manager, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+
+test("a release install that is already the latest release changes nothing", async () => {
+	const w = world({ latest: "4.0.0" });
+	try {
+		assert.equal(await w.upgrade([]), 0);
+		assert.deepEqual(w.lines, ["gentle-shell 4.0.0 is already the latest release."]);
+		assert.deepEqual(w.calls, []);
+		assert.deepEqual(w.fetches, ["https://registry.npmjs.org/gentle-pi/latest"]);
+	} finally { w.cleanup(); }
+});
+
+test("a release install updates to the latest release with the package manager that owns it", async () => {
+	for (const [owner, expected] of [["pnpm", "/usr/bin/pnpm add -g gentle-pi@4.1.0 --allow-build=gentle-pi"], ["npm", "/usr/bin/npm install -g gentle-pi@4.1.0"]]) {
+		const w = world({ owner });
+		try {
+			assert.equal(await w.upgrade([]), 0);
+			assert.deepEqual(w.installs(), [expected]);
+			assert.deepEqual(w.lines, ["Updated gentle-shell 4.0.0 to 4.1.0 (release)."]);
+			assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "release" });
+		} finally { w.cleanup(); }
+	}
+});
+
+test("a pnpm upgrade adds only gentle-pi, in its own pnpm group: a Pi installed with pnpm is never read or replaced", async () => {
+	// A separate add keeps `pi update` (which replaces Pi's own group) from removing gentle-pi.
+	const w = world();
+	try {
+		assert.equal(await w.upgrade([]), 0);
+		assert.deepEqual(w.calls.map((call) => `${call.command} ${call.argv.join(" ")}`), ["/usr/bin/pnpm add -g gentle-pi@4.1.0 --allow-build=gentle-pi"]);
+	} finally { w.cleanup(); }
+});
+
+test("a Gentle Shell that neither pnpm nor npm owns, such as an npm-linked checkout, is never reinstalled", async () => {
+	const w = world({ owner: "linked" });
+	try {
+		await assert.rejects(w.upgrade([]), (error: MainChannelError) => error.code === "upgrade-owner-unknown");
+		assert.deepEqual(w.installs(), []);
+	} finally { w.cleanup(); }
+});
+
+test("self-uninstall resolves the owning package manager with its own refusals", async () => {
+	for (const [owner, expected] of [["pnpm", { name: "pnpm", command: "/usr/bin/pnpm", prefix: [] }], ["npm", { name: "npm", command: "/usr/bin/npm", prefix: [] }]] as const) {
+		const w = world({ owner });
+		try {
+			assert.deepEqual(await w.manager("uninstall"), expected);
+		} finally { w.cleanup(); }
+	}
+	const linked = world({ owner: "linked" });
+	try {
+		await assert.rejects(linked.manager("uninstall"), (error: MainChannelError) =>
+			error.code === "uninstall-owner-unknown" && /remove it the way you installed it/.test(error.message));
+	} finally { linked.cleanup(); }
+	const missing = world({ tools: ["npm"] });
+	try {
+		await assert.rejects(missing.manager("uninstall"), (error: MainChannelError) => error.code === "uninstall-manager-missing");
+	} finally { missing.cleanup(); }
+});
+
+test("upgrade keeps its owner refusals unchanged", async () => {
+	const linked = world({ owner: "linked" });
+	try {
+		await assert.rejects(linked.manager(), (error: MainChannelError) =>
+			error.code === "upgrade-owner-unknown" && /update it the way you installed it/.test(error.message));
+	} finally { linked.cleanup(); }
+	const missing = world({ tools: ["npm"] });
+	try {
+		await assert.rejects(missing.manager(), (error: MainChannelError) =>
+			error.code === "upgrade-manager-missing" && /which owns this Gentle Shell installation, is not on PATH/.test(error.message));
+		await assert.rejects(missing.upgrade([]), (error: MainChannelError) => error.code === "upgrade-manager-missing");
+		assert.deepEqual(missing.installs(), []);
+	} finally { missing.cleanup(); }
+});
+
+test("an unreachable registry fails without installing anything", async () => {
+	const w = world({ latest: "" });
+	try {
+		await assert.rejects(w.upgrade([]), (error: MainChannelError) => error.code === "latest-release-unavailable");
+		assert.deepEqual(w.calls, []);
+	} finally { w.cleanup(); }
+});
+
+test("a main install already at both latest main commits changes nothing", async () => {
+	const w = world();
+	try {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		assert.equal(await w.upgrade([], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.deepEqual(w.lines, ["gentle-shell is already at the latest main: Gentle Shell 6e7e3a18f794, Gentle AI 1f9d5e6423e3."]);
+		assert.deepEqual(w.calls, []);
+	} finally { w.cleanup(); }
+});
+
+test("a main install rebuilds only what moved on main and records the new commits", posixOnly, async () => {
+	const w = world({ commits: { ai: NEW_AI, shell: NEW_SHELL } });
+	try {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		assert.equal(await w.upgrade([], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.ok(w.calls.some((call) => call.argv.join(" ") === `install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@${NEW_AI}`));
+		const tgz = join(w.home, ".pi", "gentle-ai", "main", "packages", "gentle-pi-4.1.0-main.333333333333.tgz");
+		assert.deepEqual(w.installs(), [`/usr/bin/pnpm add -g ${tgz} --allow-build=gentle-pi`]);
+		assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "main", shellCommit: NEW_SHELL, gentleAiCommit: NEW_AI });
+		assert.deepEqual(w.lines, ["Updated to the latest main: Gentle Shell 333333333333, Gentle AI 222222222222."]);
+	} 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 {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		assert.equal(await w.upgrade([], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.equal(w.calls.some((call) => call.argv[1]?.includes("cmd/gentle-ai@")), false);
+		assert.equal(w.installs().length, 1);
+	} finally { w.cleanup(); }
+});
+
+test("--channel main switches a release install to both latest main commits", posixOnly, async () => {
+	const w = world();
+	try {
+		assert.equal(await w.upgrade(["--channel", "main"]), 0);
+		assert.ok(w.calls.some((call) => call.argv[1] === `github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@${AI_SHA}`));
+		assert.equal(w.installs().length, 1);
+		assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA });
+		assert.deepEqual(JSON.parse(readFileSync(join(w.home, ".pi", "gentle-ai", "dev-binary.json"), "utf8")).path,
+			join(w.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA, "gentle-ai"));
+	} finally { w.cleanup(); }
+});
+
+test("--channel release switches a main install back and removes only the main override", async () => {
+	const w = world();
+	try {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		const registration = join(w.home, ".pi", "gentle-ai", "dev-binary.json");
+		writeFileSync(registration, JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: join(w.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA, "gentle-ai") }));
+		assert.equal(await w.upgrade(["--channel=release"], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.deepEqual(w.installs(), ["/usr/bin/pnpm add -g gentle-pi@4.1.0 --allow-build=gentle-pi"]);
+		assert.equal(existsSync(registration), false);
+		assert.deepEqual(JSON.parse(readFileSync(join(w.home, ".pi", "gentle-ai", "channel.json"), "utf8")), { schema: CHANNEL_SCHEMA, channel: "release" });
+	} finally { w.cleanup(); }
+});
+
+test("switching to release keeps a dev binary the user registered themselves", async () => {
+	const w = world();
+	try {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		const registration = join(w.home, ".pi", "gentle-ai", "dev-binary.json");
+		writeFileSync(registration, JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: "/Users/me/src/gentle-ai/gentle-ai" }));
+		assert.equal(await w.upgrade(["--channel", "release"], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.equal(existsSync(registration), true);
+	} finally { w.cleanup(); }
+});
+
+// A missing Go is not a blocker: the build downloads the pinned Go (main-channel.test.ts).
+test("main needs pnpm on PATH", async () => {
+	const w = world({ tools: ["go", "npm"] });
+	try {
+		await assert.rejects(w.upgrade(["--channel", "main"]), (error: MainChannelError) => error.code === "main-requires-tools");
+		assert.deepEqual(w.calls, []);
+	} finally { w.cleanup(); }
+});
+
+// S8: on Windows npm and pnpm are `.cmd` shims, which cannot run with shell:false.
+// The host's invocation adapter says how each one runs (node.exe plus its JS entry).
+const NODE_EXE = "C:\\nodejs\\node.exe";
+const NPM_CLI = "C:\\nodejs\\node_modules\\npm\\bin\\npm-cli.js";
+const PNPM_ENTRY = "C:\\tools\\pnpm\\package\\bin\\pnpm.mjs";
+const windowsInvocations = async (name: string): Promise<Invocation> => (name === "npm" ? { command: NODE_EXE, prefix: [NPM_CLI] }
+	: name === "pnpm" ? { command: NODE_EXE, prefix: [PNPM_ENTRY] } : null);
+// This host's sandbox paths, read as Windows paths (backslashes), still resolve.
+const windowsFs = { ...fsPromises, realpath: (path: string) => fsPromises.realpath(path.replaceAll("\\", "/")) } as typeof fsPromises;
+const windowsWorld = (options: Parameters<typeof world>[0] = {}) => world({ platform: "win32", bin: "C:/nodejs", suffix: ".cmd", invocation: windowsInvocations, fs: windowsFs, ...options });
+
+test("Windows: a release update runs npm or pnpm through the host's invocation, never a .cmd", async () => {
+	for (const [owner, expected] of [["pnpm", `${NODE_EXE} ${PNPM_ENTRY} add -g gentle-pi@4.1.0 --allow-build=gentle-pi`], ["npm", `${NODE_EXE} ${NPM_CLI} install -g gentle-pi@4.1.0`]]) {
+		const w = windowsWorld({ owner });
+		try {
+			assert.equal(await w.upgrade([]), 0);
+			assert.deepEqual(w.installs(), [expected]);
+			assert.deepEqual(w.roots.map((call) => `${call.command} ${call.argv.join(" ")}`), [`${NODE_EXE} ${NPM_CLI} root -g`]);
+			assert.equal([...w.calls, ...w.roots].some((call) => /\.(cmd|bat)$/i.test(call.command)), false);
+		} finally { w.cleanup(); }
+	}
+});
+
+test("Windows: a main update packs and installs with the host's pnpm invocation", posixOnly, async () => {
+	const w = windowsWorld();
+	try {
+		assert.equal(await w.upgrade(["--channel", "main"]), 0);
+		const pack = w.calls.find((call) => call.argv.includes("pack"));
+		assert.deepEqual([pack?.command, pack?.argv.slice(0, 2)], [NODE_EXE, [PNPM_ENTRY, "pack"]]);
+		assert.deepEqual(w.installs().map((line) => line.split(" ").slice(0, 4).join(" ")), [`${NODE_EXE} ${PNPM_ENTRY} add -g`]);
+		assert.equal(w.calls.some((call) => /\.(cmd|bat)$/i.test(call.command)), false);
+	} finally { w.cleanup(); }
+});
+
+test("Windows: a package manager that resolves only to a .cmd, or not at all, is missing and nothing runs", async () => {
+	for (const invocation of [undefined, async () => null]) {
+		for (const owner of ["pnpm", "npm"]) {
+			const w = windowsWorld({ owner, invocation });
+			try {
+				await assert.rejects(w.upgrade([]), (error: MainChannelError) => error.code === (owner === "npm" ? "upgrade-owner-unknown" : "upgrade-manager-missing"));
+				assert.deepEqual([w.calls, w.roots], [[], []]);
+			} finally { w.cleanup(); }
+		}
+		const main = windowsWorld({ invocation });
+		try {
+			await assert.rejects(main.upgrade(["--channel", "main"]), (error: MainChannelError) => error.code === "main-requires-tools");
+			assert.deepEqual(main.calls, []);
+		} finally { main.cleanup(); }
+	}
+});
+
+test("Windows: self-uninstall resolves npm and pnpm through the host's invocation, never a .cmd", async () => {
+	for (const [owner, expected] of [["pnpm", { name: "pnpm", command: NODE_EXE, prefix: [PNPM_ENTRY] }], ["npm", { name: "npm", command: NODE_EXE, prefix: [NPM_CLI] }]] as const) {
+		const w = windowsWorld({ owner });
+		try {
+			assert.deepEqual(await w.manager("uninstall"), expected);
+			assert.deepEqual(w.roots.map((call) => `${call.command} ${call.argv.join(" ")}`), [`${NODE_EXE} ${NPM_CLI} root -g`]);
+		} finally { w.cleanup(); }
+	}
+	for (const invocation of [undefined, async () => null]) {
+		for (const owner of ["pnpm", "npm"]) {
+			const w = windowsWorld({ owner, invocation });
+			try {
+				await assert.rejects(w.manager("uninstall"), (error: MainChannelError) => error.code === (owner === "npm" ? "uninstall-owner-unknown" : "uninstall-manager-missing"));
+				assert.deepEqual([w.calls, w.roots], [[], []]);
+			} finally { w.cleanup(); }
+		}
+	}
+});
+
+test("POSIX: without an invocation adapter the package managers `which` finds run as they are, with no prefix", posixOnly, async () => {
+	for (const [owner, args] of [["npm", []], ["pnpm", []], ["pnpm", ["--channel", "main"]]] as const) {
+		const w = world({ owner, platform: "linux" });
+		try {
+			assert.equal(await w.upgrade([...args]), 0);
+			assert.deepEqual(w.roots.map((call) => `${call.command} ${call.argv.join(" ")}`), ["/usr/bin/npm root -g"]);
+			assert.ok(w.installs().every((line) => line.startsWith(`/usr/bin/${owner} ${owner === "npm" ? "install" : "add"} -g `)), w.installs().join("\n"));
+			if (args.length > 0) assert.equal(w.calls.find((call) => call.argv[0] === "pack")?.command, "/usr/bin/pnpm");
+		} finally { w.cleanup(); }
+	}
+});
+
+test("unknown upgrade arguments are a usage error", async () => {
+	for (const args of [["--channel"], ["--channel", "nightly"], ["--force"], ["main"]]) {
+		const w = world();
+		try {
+			await assert.rejects(w.upgrade(args), (error: MainChannelError) => error.code === "upgrade-usage");
+			assert.deepEqual(w.calls, []);
+			assert.deepEqual(w.fetches, []);
+		} finally { w.cleanup(); }
+	}
+});
+
+// T3 (S4): the release branch first offers the migration to the bundled install.
+test("a release upgrade that migrates installs nothing globally, records the release channel and removes only the main override", async () => {
+	const seen: { latest: string; owner: unknown }[] = [];
+	const w = world({ migrate: async ({ latest, owner }) => { seen.push({ latest, owner: await owner() }); return { code: 0, installed: true }; } });
+	try {
+		await writeChannel(w.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		const registration = join(w.home, ".pi", "gentle-ai", "dev-binary.json");
+		writeFileSync(registration, JSON.stringify({ schema: "gentle-pi.dev-binary/v1", path: join(w.home, ".pi", "gentle-ai", "main", "gentle-ai", AI_SHA, "gentle-ai") }));
+		assert.equal(await w.upgrade(["--channel", "release"], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.deepEqual(seen, [{ latest: "4.1.0", owner: { name: "pnpm", command: "/usr/bin/pnpm", prefix: [] } }]);
+		assert.deepEqual(w.installs(), []);
+		assert.equal(existsSync(registration), false);
+		assert.deepEqual(await readChannel(w.ctx, fsPromises), { channel: "release" });
+	} finally { w.cleanup(); }
+	// A migration whose removal failed keeps the bundled install: its exit code, and the release channel recorded.
+	const kept = world({ migrate: async () => ({ code: 1, installed: true }) });
+	try {
+		assert.equal(await kept.upgrade([]), 1);
+		assert.deepEqual(kept.installs(), []);
+		assert.equal(existsSync(join(kept.home, ".pi", "gentle-ai", "channel.json")), true);
+	} finally { kept.cleanup(); }
+	// B3: a migration that failed (it printed why and returns null) leaves this run to the global update.
+	const failed = world({ migrate: async () => null });
+	try {
+		assert.equal(await failed.upgrade([]), 0);
+		assert.deepEqual(failed.installs(), ["/usr/bin/pnpm add -g gentle-pi@4.1.0 --allow-build=gentle-pi"]);
+	} finally { failed.cleanup(); }
+});
+
+test("a release upgrade the migration declines keeps the current path, and main never asks", async () => {
+	let asked = 0;
+	const w = world({ migrate: async () => { asked += 1; return null; } });
+	try {
+		assert.equal(await w.upgrade([]), 0);
+		assert.deepEqual(w.installs(), ["/usr/bin/pnpm add -g gentle-pi@4.1.0 --allow-build=gentle-pi"]);
+		assert.deepEqual(w.lines, ["Updated gentle-shell 4.0.0 to 4.1.0 (release)."]);
+		assert.equal(asked, 1);
+	} finally { w.cleanup(); }
+	// The migration's owner check keeps the current refusals for an npm link.
+	const linked = world({ owner: "linked", migrate: async ({ owner }) => owner().then(() => ({ code: 0, installed: true }), () => null) });
+	try {
+		await assert.rejects(linked.upgrade([]), (error: MainChannelError) => error.code === "upgrade-owner-unknown");
+	} finally { linked.cleanup(); }
+	const main = world({ migrate: async () => { asked += 1; return { code: 0, installed: true }; } });
+	try {
+		await writeChannel(main.ctx, { channel: "main", shellCommit: SHELL_SHA, gentleAiCommit: AI_SHA }, fsPromises);
+		assert.equal(await main.upgrade([], "4.0.0-main.6e7e3a18f794"), 0);
+		assert.equal(asked, 1);
+	} finally { main.cleanup(); }
+});
+
+test("removeGlobalShell removes gentle-pi with the manager that owns it, through its verified invocation", async () => {
+	const calls: string[] = [];
+	const run = async (command: string, argv: string[]) => { calls.push(`${command} ${argv.join(" ")}`); return { code: calls.length === 3 ? 1 : 0, stdout: "" }; };
+	assert.equal(await removeGlobalShell({ name: "pnpm", command: "/usr/bin/pnpm", prefix: [] }, run), true);
+	assert.equal(await removeGlobalShell({ name: "npm", command: "C:\\nodejs\\node.exe", prefix: ["C:\\nodejs\\npm-cli.js"] }, run), true);
+	assert.equal(await removeGlobalShell({ name: "npm", command: "/usr/bin/npm", prefix: [] }, run), false);
+	assert.deepEqual(calls, ["/usr/bin/pnpm remove -g gentle-pi", "C:\\nodejs\\node.exe C:\\nodejs\\npm-cli.js uninstall -g gentle-pi", "/usr/bin/npm uninstall -g gentle-pi"]);
+});