gentle-pi 3.7.0 → 4.1.0

package/scripts/render-cache-performance-worker.mjs

@@ -0,0 +1,205 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+
+const config = JSON.parse(process.argv[2]);
+const piVersion = JSON.parse(readFileSync(resolve(config.piRoot, "package.json"), "utf8")).version;
+const tuiVersion = JSON.parse(readFileSync(resolve(config.piRoot, "node_modules/@earendil-works/pi-tui/package.json"), "utf8")).version;
+assert.equal(piVersion, "1.1.0", "private frame API audited only on Pi 1.1.0");
+assert.equal(tuiVersion, piVersion, "host TUI package must match");
+const hostImport = (path) => import(pathToFileURL(resolve(config.piRoot, "dist", path)).href);
+const { createJiti } = await hostImport("core/extensions/jiti-loader.js");
+const { VIRTUAL_MODULES } = await hostImport("core/extensions/virtual-modules.js");
+const pi = VIRTUAL_MODULES["@earendil-works/pi-coding-agent"];
+const { Container, TuiAltScreen } = VIRTUAL_MODULES["@earendil-works/pi-tui"];
+const nativeTheme = await hostImport("modes/interactive/theme/theme.js");
+const { KeybindingsManager } = await hostImport("core/keybindings.js");
+const { ToolExecutionComponent } = await hostImport("modes/interactive/components/tool-execution.js");
+const { UserMessageComponent } = await hostImport("modes/interactive/components/user-message.js");
+const { AssistantMessageComponent } = await hostImport("modes/interactive/components/assistant-message.js");
+const { createChatViewport } = await hostImport("modes/interactive/chat-viewport.js");
+const loader = createJiti(import.meta.url, { moduleCache: false, fsCache: false, virtualModules: VIRTUAL_MODULES, tryNative: false });
+const source = (path) => loader.import(resolve(config.root, path));
+const shell = await source("extensions/gentle-shell.ts");
+const quiet = await source("extensions/quiet-tools.ts");
+const bar = await source("lib/shell-bar.ts");
+const sidebar = await source("lib/shell-sidebar.ts");
+const layout = await source("lib/shell-sidebar-layout.ts");
+const cards = await source("lib/shell-card.ts");
+assert.equal(Object.getPrototypeOf(shell.GentlePromptEditor.prototype), pi.CustomEditor.prototype, "editor must extend this exact host class");
+const memory = () => Object.fromEntries(Object.entries(process.memoryUsage()).map(([key, bytes]) => [key, bytes / 1024 / 1024]));
+const digest = (lines) => createHash("sha256").update(lines.join("\n")).digest("hex");
+const usage = { input: 100, output: 20, cacheRead: 0, cacheWrite: 0, totalTokens: 120, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.001 } };
+
+function fixture(spec, live = false) {
+	pi.initTheme("dark");
+	cards.setCardStyle(spec.style);
+	const counts = { paints: 0, projections: 0, entries: 0, requests: 0, pulses: 0, bytes: 0 };
+	const theme = { fg: (...args) => nativeTheme.theme.fg(...args), bg: (...args) => nativeTheme.theme.bg(...args), bold: (text) => nativeTheme.theme.bold(text) };
+	const toolTheme = { ...theme, fg: (...args) => { counts.paints++; return theme.fg(...args); }, bg: (...args) => { counts.paints++; return theme.bg(...args); } };
+	const geometry = { columns: spec.width, rows: 32 };
+	let inputHandler;
+	const terminal = {
+		start(onInput) { inputHandler = onInput; }, stop() {}, async drainInput() {}, write(text) { counts.bytes += Buffer.byteLength(text); },
+		get columns() { return geometry.columns; }, get rows() { return geometry.rows; },
+		moveBy() {}, hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {}, clearScreen() {},
+		setTitle() {}, setProgress() {}, kittyProtocolActive: false, getBufferedInput() { return ""; }, hasPendingInput() { return false; },
+	};
+	const tui = new TuiAltScreen(terminal, false);
+	const manager = pi.SessionManager.inMemory("/performance", { id: "performance-session" });
+	const getEntries = manager.getEntries.bind(manager);
+	manager.getEntries = () => { counts.entries++; return getEntries(); };
+	const model = { id: "synthetic-model", provider: "synthetic", reasoning: true, contextWindow: 200000 };
+	const ctx = { model, sessionManager: manager, modelRegistry: { isUsingOAuth: () => false },
+		getContextUsage() { counts.projections++; return pi.AgentSession.prototype.getContextUsage.call({ sessionManager: manager, _limitsModel: () => model }); } };
+	const api = { getThinkingLevel: () => "high" };
+	const footerData = { getGitBranch: () => "performance", getExtensionStatuses: () => new Map(), onBranchChange: () => () => {} };
+	let clock = 0;
+	const editor = new shell.GentlePromptEditor(tui, nativeTheme.getEditorTheme(), new KeybindingsManager(), {
+		...theme, pending: () => false, now: () => live ? Date.now() : clock, doubleEscCancelEnabled: () => false,
+		dispatchQueuedText() {}, requestRender() { counts.requests++; if (live) tui.requestRender(); },
+	});
+	let pulse = () => {};
+	if (live) editor.setWorking(true);
+	else {
+		// Capture the actual quality interval callback, not a reimplementation.
+		const original = globalThis.setInterval;
+		try { globalThis.setInterval = (fn, ms) => { assert.equal(ms, 80); pulse = () => { counts.pulses++; fn(); }; return { unref() {} }; }; editor.setWorking(true); }
+		finally { globalThis.setInterval = original; }
+	}
+	const document = new Container();
+	const renderer = quiet.createQuietToolRenderer("read");
+	const definition = { ...renderer, renderCall: (args, _theme, context) => renderer.renderCall(args, toolTheme, context),
+		renderResult: (result, options, _theme, context) => renderer.renderResult(result, options, toolTheme, context) };
+	let toolCount = 0;
+	let latest;
+	const append = () => {
+		const id = `tool-${toolCount++}`;
+		const args = { path: `src/file-${id}.ts` };
+		const text = `Inspect **${id}** with Unicode 広い and ANSI-safe content.`;
+		manager.appendMessage({ role: "user", content: text, timestamp: 1 });
+		const assistant = { role: "assistant", content: [{ type: "text", text: "Checking `source` and a **settled** paragraph." }, { type: "toolCall", id, name: "read", arguments: args }],
+			api: "openai-responses", provider: "synthetic", model: model.id, stopReason: "toolUse", timestamp: 1, usage };
+		manager.appendMessage(assistant);
+		const result = { content: [{ type: "text", text: `Result ${id}\nconst answer = 42;\n${"long wrapped output ".repeat(12)}` }], details: {}, isError: false };
+		manager.appendMessage({ ...result, role: "toolResult", toolCallId: id, toolName: "read", timestamp: 1 });
+		document.addChild(new UserMessageComponent(text));
+		document.addChild(new AssistantMessageComponent(assistant));
+		latest = new ToolExecutionComponent("read", id, args, {}, definition, tui, "/performance");
+		latest.setArgsComplete(); latest.updateResult(result); document.addChild(latest);
+	};
+	for (let index = 0; index < spec.tools; index++) append();
+	const footer = new Container();
+	const modelForFrame = () => shell.buildShellBarModel(api, ctx, footerData);
+	const bottom = shell.createShellBarComponent(api, ctx, tui, theme, footerData);
+	footer.addChild(sidebar.sidebarPart(tui, "footer", bottom, {
+		digest: () => JSON.stringify(modelForFrame()), render: (width) => bar.renderShellSidebarBar(modelForFrame(), theme, width), invalidate() {},
+	}));
+	const disposeHeader = sidebar.sidebarHeader(tui, { digest: () => JSON.stringify(modelForFrame()),
+		render: (width) => bar.renderShellHeaderChrome(bar.buildShellHeaderModel(modelForFrame()), theme, width).rows, invalidate() {} });
+	const viewport = createChatViewport({ document, pendingMessages: new Container(), status: new Container(), widgetsAbove: new Container(),
+		editor, widgetsBelow: new Container(), footer, scrollbar: "hidden" });
+	tui.setLayoutRoot(viewport.root); tui.setFocus(editor);
+	let uninstall = layout.installSidebar(tui, theme);
+	tui.start();
+	const render = () => {
+		tui.doRender();
+		assert.equal(sidebar.sidebarState(tui).active, geometry.columns >= layout.SIDEBAR_BREAKPOINT, "sidebar must really own wide frames");
+		assert.equal(cards.cardStyle(), spec.style);
+		return [...tui.previousScreen];
+	};
+	return { tui, editor, manager, counts, render, input: (data) => inputHandler(data),
+		advance() { clock += 80; pulse(); },
+		apply(scenario, index) {
+			if (scenario === "scroll") { if (index % 2) viewport.transcript.scrollToEnd(); else viewport.transcript.scrollTo(0, { disableFollow: true }); }
+			if (scenario === "typing") { const text = editor.getText(); editor.handleInput("x"); assert.equal(editor.getText(), text + "x"); }
+			if (scenario === "stream") latest.updateResult({ content: [{ type: "text", text: `stream ${index} ${"partial ".repeat(index + 1)}` }], details: {} }, true);
+			if (scenario === "append") append();
+			if (scenario === "resize") { const previous = geometry.columns; geometry.columns = index % 2 ? spec.width : Math.max(40, spec.width - 60); assert.notEqual(geometry.columns, previous); }
+			if (scenario === "theme") {
+				const previous = theme.bg("toolSuccessBg", "");
+				pi.initTheme(index % 2 ? "dark" : "light");
+				assert.notEqual(theme.bg("toolSuccessBg", ""), previous);
+				document.invalidate(); editor.invalidate();
+				uninstall(); uninstall = layout.installSidebar(tui, { ...theme });
+			}
+		},
+		close() { editor.dispose(); disposeHeader(); uninstall(); bottom.dispose(); tui.stop(); },
+	};
+}
+
+function controlled(spec) {
+	globalThis.gc();
+	const idleMemory = memory();
+	const buildStart = performance.now();
+	const scene = fixture(spec);
+	const buildMs = performance.now() - buildStart;
+	assert.equal(scene.counts.projections, 0, "first frame must not already have rendered");
+	const coldStart = performance.now();
+	const coldLines = scene.render();
+	const coldMs = performance.now() - coldStart;
+	const coldScreen = digest(coldLines);
+	for (let index = 0; index < config.warmup; index++) { scene.advance(); scene.render(); }
+	globalThis.gc();
+	const warmMemory = memory();
+	const initial = { ...scene.counts };
+	const result = { spec, buildMs, coldMs, coldScreen, idleMemory, warmMemory, wallMs: [], cpuMs: [], screens: [] };
+	const samples = ["resize", "theme"].includes(spec.scenario) ? Math.min(8, config.samples) : config.samples;
+	try {
+		for (let index = 0; index < samples; index++) {
+			const cpu = process.cpuUsage();
+			const start = performance.now();
+			scene.advance(); scene.apply(spec.scenario, index);
+			const screen = scene.render();
+			result.wallMs.push(performance.now() - start);
+			const used = process.cpuUsage(cpu);
+			result.cpuMs.push((used.user + used.system) / 1000);
+			result.screens.push(digest(screen));
+		}
+		result.counters = Object.fromEntries(Object.entries(scene.counts).map(([key, value]) => [key, value - initial[key]]));
+		assert.equal(result.counters.pulses, samples, "every controlled frame advances the real quality pulse");
+	} finally { scene.close(); }
+	return result;
+}
+
+async function live(spec) {
+	const scene = fixture(spec, true);
+	for (let index = 0; index < config.warmup; index++) scene.render();
+	scene.editor.setWorking(false); scene.editor.setWorking(true); // Align real pulse onset after warmup.
+	const original = scene.tui.doRender.bind(scene.tui);
+	const result = { spec, durationMs: config.liveMs, frameMs: [], inputToFrameMs: [], inputTimerDriftMs: [] };
+	const started = performance.now();
+	const initial = { ...scene.counts };
+	let pendingInput;
+	let expected = started + 100;
+	scene.tui.doRender = () => {
+		const start = performance.now(); original();
+		result.frameMs.push(performance.now() - start);
+		if (pendingInput !== undefined) { result.inputToFrameMs.push(performance.now() - pendingInput); pendingInput = undefined; }
+	};
+	const input = setInterval(() => {
+		result.inputTimerDriftMs.push(performance.now() - expected); expected += 100;
+		pendingInput ??= performance.now(); scene.input("x");
+	}, 100);
+	try { await new Promise((resolve) => setTimeout(resolve, config.liveMs)); }
+	finally { clearInterval(input); scene.close(); }
+	result.actualDurationMs = performance.now() - started;
+	result.counters = Object.fromEntries(Object.entries(scene.counts).map(([key, value]) => [key, value - initial[key]]));
+	return result;
+}
+
+const cases = [];
+for (const tools of config.counts) for (const width of config.widths) for (const style of config.styles) {
+	for (const scenario of ["pulse", "scroll", "typing", "stream", "append", "resize", "theme"]) {
+		const result = controlled({ tools, width, style, scenario });
+		// WeakRef keep-alive lasts until the job boundary; collect only after it.
+		await new Promise((resolve) => setImmediate(resolve)); globalThis.gc(); result.closedMemory = memory(); cases.push(result);
+	}
+}
+const liveRuns = config.liveMs ? [await live({ tools: Math.max(...config.counts), width: Math.max(...config.widths), style: config.styles[0], scenario: "real-quality-timers-and-typing" })] : [];
+const metadata = { piVersion, tuiVersion,
+	editorIdentityVerified: true, animation: "quality/80ms", terminal: "in-memory ANSI sink; no emulator", scheduler: "controlled quality callback; separate real-timer run" };
+console.log(JSON.stringify({ metadata, cases, live: liveRuns }));

package/scripts/render-cache-performance.mjs

@@ -0,0 +1,115 @@
+// Diagnostic comparison, not a speed gate. Run each source in a fresh process.
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, ftruncateSync, openSync, readFileSync, readdirSync, realpathSync, writeSync } from "node:fs";
+import { cpus, loadavg } from "node:os";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function percentile(values, fraction) {
+	if (!values.length) return null;
+	const sorted = [...values].sort((a, b) => a - b);
+	const position = (sorted.length - 1) * fraction;
+	const low = Math.floor(position);
+	return sorted[low] + (sorted[Math.ceil(position)] - sorted[low]) * (position - low);
+}
+export function summarize(values) {
+	return { count: values.length, median: percentile(values, 0.5), p95: percentile(values, 0.95), max: values.length ? Math.max(...values) : null };
+}
+export function compare(before, after) {
+	assert.deepEqual(after.metadata, before.metadata, "host and scheduler must match");
+	assert.equal(before.cases.length, after.cases.length);
+	return before.cases.map((original, index) => {
+		const candidate = after.cases[index];
+		assert.deepEqual(candidate.spec, original.spec);
+		assert.equal(candidate.coldScreen, original.coldScreen, "cold visible output differs");
+		assert.deepEqual(candidate.screens, original.screens, `visible output differs: ${JSON.stringify(original.spec)}`);
+		return { spec: original.spec, before: summarize(original.wallMs), after: summarize(candidate.wallMs),
+			speedup: percentile(original.wallMs, 0.5) / percentile(candidate.wallMs, 0.5) };
+	});
+}
+function hashFiles(root, paths) {
+	const hash = createHash("sha256");
+	for (const path of paths.sort()) hash.update(path + "\0").update(readFileSync(resolve(root, path))).update("\0");
+	return hash.digest("hex");
+}
+function fingerprint(root) {
+	const paths = execFileSync("git", ["-C", root, "ls-files", "-z"], { encoding: "utf8" }).split("\0").filter(Boolean);
+	return { root, head: execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" }).trim(), sourceSha256: hashFiles(root, paths) };
+}
+function hostFingerprint(root) {
+	const packages = [root, ...["pi-tui", "pi-ai", "pi-agent-core", "jiti"].map((name) => resolve(root, "node_modules", name === "jiti" ? name : `@earendil-works/${name}`))];
+	return packages.map((path) => {
+		const packageRoot = realpathSync(path);
+		const files = readdirSync(packageRoot, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => relative(packageRoot, resolve(entry.parentPath, entry.name)));
+		return { root: packageRoot, package: JSON.parse(readFileSync(resolve(path, "package.json"), "utf8")).version, sha256: hashFiles(packageRoot, files) };
+	});
+}
+export function outputDescriptor(output, protectedRoots) {
+	const canonical = resolve(realpathSync(dirname(resolve(output))), basename(output));
+	for (const root of protectedRoots) {
+		const path = relative(realpathSync(root), canonical);
+		assert.ok(path && (isAbsolute(path) || path === ".." || path.startsWith(".." + sep)), "output must be outside source, harness and host roots");
+	}
+	return openSync(canonical, "wx", 0o600);
+}
+async function main() {
+	const options = Object.fromEntries(process.argv.slice(2).map((arg) => {
+		assert.match(arg, /^--[a-z-]+=.+$/, "use --name=value arguments");
+		const split = arg.indexOf("="); return [arg.slice(2, split), arg.slice(split + 1)];
+	}));
+	for (const key of ["baseline-root", "candidate-root", "pi-root", "output"]) assert.ok(options[key], `--${key} is required`);
+	const roots = { before: resolve(options["baseline-root"]), after: resolve(options["candidate-root"]) };
+	const initial = Object.fromEntries(Object.entries(roots).map(([key, root]) => [key, fingerprint(root)]));
+	assert.equal(initial.before.head, initial.after.head, "compare worktrees based on the same commit");
+	const numeric = (name, fallback, min) => { const value = Number(options[name] ?? fallback); assert.ok(Number.isInteger(value) && value >= min, `invalid --${name}`); return value; };
+	const list = (name, fallback) => (options[name] ?? fallback).split(",").map(Number);
+	const config = { piRoot: resolve(options["pi-root"]), counts: list("counts", "100,1000,5000"), widths: list("widths", "100,160"),
+		styles: (options.styles ?? "float,neon").split(","), samples: numeric("samples", 50, 2), warmup: 5, liveMs: numeric("live-ms", 6000, 0) };
+	assert.ok([...config.counts, ...config.widths].every((value) => Number.isInteger(value) && value > 0));
+	assert.ok(config.styles.length <= 2 && config.styles.every((style) => ["float", "neon"].includes(style)));
+	assert.ok(config.widths.every((width) => width > 40), "resize scenarios need widths above 40");
+	const repetitions = numeric("repetitions", 4, 1);
+	assert.ok(repetitions <= 20 && config.samples <= 2000 && config.liveMs <= 60000);
+	assert.ok(config.counts.length <= 4 && config.widths.length <= 4 && Math.max(...config.counts) <= 20000 && Math.max(...config.widths) <= 300);
+	const report = { schema: "gentle-shell.render-performance/v1", started: new Date().toISOString(), node: process.version,
+		cpu: cpus()[0]?.model, loadAtStart: loadavg(), sources: initial, config, runs: [], comparisons: [] };
+	const worker = fileURLToPath(new URL("render-cache-performance-worker.mjs", import.meta.url));
+	const instrumentationHash = () => createHash("sha256").update(readFileSync(fileURLToPath(import.meta.url))).update(readFileSync(worker)).digest("hex");
+	report.instrumentationSha256 = instrumentationHash();
+	report.host = hostFingerprint(config.piRoot);
+	const fd = outputDescriptor(options.output, [...Object.values(roots), config.piRoot, ...report.host.map((entry) => entry.root), resolve(dirname(fileURLToPath(import.meta.url)), "..")]);
+	const persist = () => {
+		const data = Buffer.from(JSON.stringify(report, null, 2) + "\n");
+		ftruncateSync(fd, 0);
+		let offset = 0;
+		while (offset < data.length) {
+			const written = writeSync(fd, data, offset, data.length - offset, offset);
+			assert.ok(written > 0); offset += written;
+		}
+	};
+	try {
+		for (let repetition = 0; repetition < repetitions; repetition++) {
+			const pair = {};
+			for (const variant of repetition % 2 ? ["after", "before"] : ["before", "after"]) {
+				console.log(`replica ${repetition + 1}/${repetitions}: ${variant}`);
+				const output = execFileSync(process.execPath, ["--expose-gc", "--experimental-strip-types", worker,
+					JSON.stringify({ ...config, root: roots[variant], repetition })], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 1_200_000 });
+				pair[variant] = JSON.parse(output);
+				report.runs.push({ repetition, variant, ...pair[variant] });
+				persist();
+			}
+			report.comparisons.push({ repetition, cases: compare(pair.before, pair.after) });
+			persist();
+		}
+		for (const [key, root] of Object.entries(roots)) assert.deepEqual(fingerprint(root), initial[key], "source changed during measurement");
+		assert.equal(instrumentationHash(), report.instrumentationSha256, "instrumentation changed during measurement");
+		assert.deepEqual(hostFingerprint(config.piRoot), report.host, "host runtime changed during measurement");
+		report.finished = new Date().toISOString();
+		report.loadAtEnd = loadavg();
+		persist();
+	} finally { closeSync(fd); }
+	console.log(`PASS: ${report.comparisons[0].cases.length} equivalent cases × ${repetitions} paired replicas; raw report: ${resolve(options.output)}`);
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/run-test-suite.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Sequential test-suite runner for `pnpm test` (gentle-pi#1285).
+//
+// `pnpm test` used to chain its three stages with `&&`, so any stage-1
+// failure — including a known-flaky unit test — silently suppressed the
+// provider-contract check and the runtime harness while reporting a plain
+// "test failed". This runner executes every stage unconditionally, prints a
+// per-stage header and a final summary, and exits non-zero when any stage
+// fails. Stages are plain shell commands, so behavior stays identical on
+// POSIX and Windows CI.
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_STAGES = Object.freeze([
+	{ name: "unit-tests", command: "node --experimental-strip-types --test tests/*.test.ts" },
+	{ name: "provider-contract", command: "pnpm run check:provider-contract" },
+	{ name: "runtime-harness", command: "pnpm run test:harness" },
+]);
+
+export async function runStage(stage) {
+	// Unit fixtures must not inherit the terminal's Git overrides, child-session
+	// identity, or personal guardrails. Other stages retain their existing env.
+	const configHome = stage.name === "unit-tests" ? mkdtempSync(join(tmpdir(), "gentle-pi-unit-config-")) : undefined;
+	const env = configHome ? Object.fromEntries(Object.entries(process.env).filter(([key]) => {
+		const normalizedKey = key.toUpperCase();
+		return !normalizedKey.startsWith("GIT_") && !normalizedKey.startsWith("GENTLE_PI_AGENTS_") && normalizedKey !== "GENTLE_PI_CONFIG_HOME";
+	})) : process.env;
+	if (configHome) env.GENTLE_PI_CONFIG_HOME = configHome;
+	try {
+		return await new Promise((resolve) => {
+			const child = spawn(stage.command, { shell: true, stdio: "inherit", env });
+			child.on("close", (code) => resolve({ name: stage.name, code: code ?? 1 }));
+			child.on("error", (error) => {
+				console.error(`\n[${stage.name}] spawn failed: ${error.message}`);
+				resolve({ name: stage.name, code: 1 });
+			});
+		});
+	} finally {
+		if (configHome) rmSync(configHome, { recursive: true, force: true });
+	}
+}
+
+export async function runTestSuite(stages = DEFAULT_STAGES, { runStageImpl = runStage, write = (line) => console.log(line) } = {}) {
+	const results = [];
+	for (const stage of stages) {
+		write(`\n=== [${stage.name}] ${stage.command} ===`);
+		results.push(await runStageImpl(stage));
+	}
+	write("\n=== test suite summary ===");
+	for (const result of results) write(`${result.code === 0 ? "PASS" : "FAIL"}  ${result.name}`);
+	const failures = results.filter((result) => result.code !== 0);
+	write(failures.length === 0 ? "all stages passed" : `${failures.length} stage(s) failed: ${failures.map((f) => f.name).join(", ")}`);
+	return results;
+}
+
+function readStagesFromJsonPath(jsonPath) {
+	const stages = JSON.parse(readFileSync(jsonPath, "utf8"));
+	if (!Array.isArray(stages) || stages.some((stage) => typeof stage?.name !== "string" || typeof stage?.command !== "string")) {
+		throw new Error(`stages file must be an array of { name, command } objects: ${jsonPath}`);
+	}
+	return stages;
+}
+
+// Direct-invocation detection must survive symlinks: Node real-paths
+// `import.meta.url` but keeps `process.argv[1]` logical, so a plain equality
+// check silently no-ops the whole runner (zero stages run, exit 0) when the
+// script is reached through a file symlink.
+function isDirectRun(argv1) {
+	if (!argv1) return false;
+	try {
+		return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+	} catch {
+		return false;
+	}
+}
+
+if (isDirectRun(process.argv[1])) {
+	try {
+		const stages = process.argv[2] ? readStagesFromJsonPath(process.argv[2]) : DEFAULT_STAGES;
+		const results = await runTestSuite(stages);
+		process.exitCode = results.some((result) => result.code !== 0) ? 1 : 0;
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	}
+}

package/scripts/test-installer-acceptance.sh

@@ -0,0 +1,161 @@
+#!/bin/sh
+# Opt-in Linux clean-machine acceptance for the browser installation wizard.
+# Runs the real bootstrap and wizard inside a disposable debian:bookworm-slim
+# container as a non-root user. Network access happens only inside that
+# container; nothing reads or writes the host HOME. Not part of CI.
+#
+# Usage: sh scripts/test-installer-acceptance.sh [--worktree]
+#   default     bundle = `git archive HEAD`
+#   --worktree  bundle = tracked files as they are in the working tree,
+#               including uncommitted modifications (untracked files excluded)
+# GENTLE_ACCEPTANCE_KEEP=1 keeps a failed run's container for inspection.
+set -eu
+fail() { printf 'acceptance: %s\n' "$1" >&2; exit 1; }
+note() { printf 'acceptance: %s\n' "$1"; }
+source_mode='head'
+case $# in
+    0) ;;
+    1) [ "$1" = --worktree ] || fail "unknown argument: $1"; source_mode=worktree;;
+    *) fail 'usage: sh scripts/test-installer-acceptance.sh [--worktree]';;
+esac
+image=debian:bookworm-slim
+# Upper bound for the whole installation inside the container.
+install_limit=${GENTLE_ACCEPTANCE_INSTALL_SECONDS:-1500}
+case $install_limit in ''|*[!0-9]*) fail 'GENTLE_ACCEPTANCE_INSTALL_SECONDS must be a whole number';; esac
+command -v docker >/dev/null 2>&1 || fail 'Docker is required; refusing to run anything on the host'
+docker info >/dev/null 2>&1 || fail 'Docker daemon is unavailable; refusing to run anything on the host'
+command -v git >/dev/null 2>&1 || fail 'git is required to package the bundle'
+repo=$(git rev-parse --show-toplevel) || fail 'run from inside the repository'
+started=$(date +%s)
+elapsed() { printf '%ss' "$(( $(date +%s) - started ))"; }
+name=gentle-install-acceptance-$$-$started
+container=
+passed=0
+cleanup() {
+    if [ -n "$container" ] && [ "$passed" = 0 ] && [ "${GENTLE_ACCEPTANCE_KEEP:-}" = 1 ]; then
+        printf 'acceptance: kept %s; inspect with: docker exec -it -u tester %s bash; remove with: docker rm -f %s\n' "$container" "$container" "$container" >&2
+    elif [ -n "$container" ]; then
+        docker rm -f "$container" >/dev/null 2>&1 || printf 'acceptance: could not remove container %s\n' "$container" >&2
+    fi
+}
+trap cleanup EXIT
+trap 'exit 1' HUP INT TERM
+
+note "image $image, bundle from $source_mode"
+docker run -d --name "$name" --pull missing "$image" sleep infinity >/dev/null || fail 'cannot start the container'
+container=$name
+# Clean machine: no Node, npm, pnpm, Pi or Gentle Shell. curl and CA roots are
+# bootstrap prerequisites that a stock Debian desktop already has.
+docker exec "$container" sh -c 'export DEBIAN_FRONTEND=noninteractive
+    apt-get update -qq >/dev/null && apt-get install -y -qq --no-install-recommends ca-certificates curl >/dev/null
+    useradd --create-home --shell /bin/bash tester
+    mkdir /opt/bundle
+    for tool in node npm pnpm pi gentle-shell; do if command -v "$tool" >/dev/null; then echo "unexpected $tool" >&2; exit 1; fi; done' \
+    || fail 'container preparation failed'
+# gentle-shell setup makes 2 anonymous GitHub API requests (upstream Gentle AI's
+# latest-engram lookup), limited to 60 per hour per public IP. /rate_limit does
+# not consume quota. Stop early instead of failing deep inside setup.
+quota=$(docker exec "$container" sh -c 'curl -fsS --max-time 20 -H "Accept: application/vnd.github+json" https://api.github.com/rate_limit' | tr -d ' \n') \
+    || fail 'cannot query the GitHub API rate limit from the container'
+rate=$(printf '%s' "$quota" | sed -n 's/.*"rate":{\([^}]*\)}.*/\1/p')
+remaining=$(printf '%s' "$rate" | sed -n 's/.*"remaining":\([0-9]*\).*/\1/p')
+reset=$(printf '%s' "$rate" | sed -n 's/.*"reset":\([0-9]*\).*/\1/p')
+[ -n "$remaining" ] && [ -n "$reset" ] || fail 'unexpected GitHub rate limit response'
+reset_at=$(date -u -d "@$reset" '+%Y-%m-%d %H:%M:%S UTC' 2>/dev/null || date -u -r "$reset" '+%Y-%m-%d %H:%M:%S UTC' 2>/dev/null || printf 'epoch %s' "$reset")
+if [ "$remaining" -lt 5 ]; then
+    fail "only $remaining anonymous GitHub API requests remain on this network (setup needs 2); the quota resets at $reset_at. Not starting."
+fi
+note "GitHub API quota: $remaining anonymous requests left (resets at $reset_at)"
+if [ "$source_mode" = head ]; then
+    git -C "$repo" archive --format=tar HEAD
+else
+    git -C "$repo" ls-files -z | tar -C "$repo" --null -T - -cf -
+fi | docker exec -i "$container" tar --no-same-owner -xf - -C /opt/bundle || fail 'cannot copy the bundle'
+note "prepared in $(elapsed)"
+
+bootstrap_started=$(date +%s)
+# A terminal session exports SHELL (the user's login shell); docker exec does
+# not. pnpm setup needs it to pick the profile to edit, and fails with
+# ERR_PNPM_UNKNOWN_SHELL without it.
+docker exec -d -u tester -w /home/tester -e SHELL=/bin/bash "$container" sh -c \
+    'sh /opt/bundle/scripts/bootstrap.sh > "$HOME/bootstrap.log" 2>&1; echo $? > "$HOME/bootstrap.status"' \
+    || fail 'cannot start the bootstrap'
+
+# Headless browser stand-in: the same requests the wizard page makes.
+driver=$(cat <<'DRIVER'
+set -eu
+log=$HOME/bootstrap.log
+say() { printf 'driver: %s\n' "$1"; }
+stop() { say "$1"; cat "$log" 2>/dev/null || :; exit 1; }
+waited=0
+while :; do
+    url=$(grep -o 'http://127\.0\.0\.1:[0-9]*/session?code=[A-Za-z0-9_-]*' "$log" 2>/dev/null | head -n 1) || url=
+    [ -z "$url" ] || break
+    [ ! -f "$HOME/bootstrap.status" ] || stop 'bootstrap exited before printing the session URL'
+    waited=$((waited + 1)); [ "$waited" -lt 600 ] || stop 'no session URL after 600 s'
+    sleep 1
+done
+say "session URL after ${waited}s"
+origin=${url%%/session*}
+jar=$HOME/acceptance-cookies
+curl -fsS -c "$jar" -b "$jar" -o /dev/null "$url" || stop 'session redemption failed'
+api() { curl -fsS -b "$jar" -H 'X-Gentle-Install: 1' "$@"; }
+post() { api -X POST -H "Origin: $origin" -H 'Content-Type: application/json' --data "$1" "$origin$2"; }
+plan=$(api "$origin/api/plan") || stop 'plan request failed'
+case $plan in *'"blockers":[]'*) ;; *) stop "plan has blockers: $plan";; esac
+plan_id=$(printf '%s' "$plan" | sed -n 's/.*"planId":"\([^"]*\)".*/\1/p')
+[ -n "$plan_id" ] || stop "plan has no planId: $plan"
+say "plan: $(printf '%s' "$plan" | grep -o '"actions":\[[^]]*\]' | grep -o '"id":"[^"]*"' | cut -d'"' -f4 | tr '\n' ' ')"
+post "{\"planId\":\"$plan_id\",\"consent\":true}" /api/install >/dev/null || stop 'install request rejected'
+seq=0
+polls=0
+while :; do
+    progress=$(api "$origin/api/progress?after=$seq") || stop 'progress request failed'
+    printf '%s' "$progress" | grep -o '"step":"[^"]*","status":"[^"]*"' | sed 's/"step":"\([^"]*\)","status":"\([^"]*\)"/  step \1: \2/' || :
+    last=$(printf '%s' "$progress" | grep -o '"seq":[0-9]*' | tail -n 1 | cut -d: -f2) || last=
+    [ -z "$last" ] || seq=$last
+    case $progress in *'"running":false'*'"outcome":{'*) break;; esac
+    polls=$((polls + 1)); [ "$polls" -lt "$INSTALL_LIMIT" ] || stop "installation still running after $INSTALL_LIMIT s"
+    sleep 1
+done
+outcome=$(printf '%s' "$progress" | sed -n 's/.*"outcome":{"outcome":"\([a-z-]*\)".*/\1/p')
+say "outcome: $outcome"
+post '{}' /api/shutdown >/dev/null || stop 'shutdown request rejected'
+waited=0
+until [ -f "$HOME/bootstrap.status" ]; do
+    waited=$((waited + 1)); [ "$waited" -lt 60 ] || stop 'bootstrap still running 60 s after shutdown'
+    sleep 1
+done
+status=$(cat "$HOME/bootstrap.status")
+say "bootstrap exit status: $status"
+cat "$log"
+case $outcome in ready|terminal-action-required) [ "$status" = 0 ] || exit 1;; *) exit 1;; esac
+DRIVER
+)
+printf '%s\n' "$driver" | docker exec -i -u tester -w /home/tester -e INSTALL_LIMIT="$install_limit" "$container" sh -s \
+    || fail "wizard flow failed after $(elapsed)"
+note "bootstrap and wizard finished in $(( $(date +%s) - bootstrap_started ))s"
+
+# A fresh interactive shell must find the persisted stack; the bootstrap tools
+# must be gone. bash -i without a terminal warns about job control; harmless.
+checks=$(cat <<'CHECKS'
+set -eu
+for tool in node npm pnpm gentle-shell; do printf '%s -> %s\n' "$tool" "$(command -v "$tool")"; done
+printf 'node %s, npm %s, pnpm %s\n' "$(node --version)" "$(npm --version)" "$(pnpm --version)"
+gentle-shell --version
+for dir in "$HOME"/.gentle-shell-bootstrap-tools.*; do
+    if [ -e "$dir" ] || [ -L "$dir" ]; then echo "bootstrap tools left behind: $dir" >&2; exit 1; fi
+done
+echo 'bootstrap tools removed'
+CHECKS
+)
+docker exec -u tester -w /home/tester "$container" bash -ic "$checks" || fail "fresh-terminal checks failed after $(elapsed)"
+# Informational: pnpm setup edits only ~/.bashrc, which non-interactive login
+# shells skip on Debian (see docs/install-wizard.md).
+if docker exec -u tester -w /home/tester "$container" bash -lc 'command -v gentle-shell' >/dev/null 2>&1; then
+    note 'bash -lc resolves gentle-shell'
+else
+    note 'bash -lc does not resolve gentle-shell (expected: ~/.profile is not edited)'
+fi
+passed=1
+note "PASS in $(elapsed)"