gentle-pi 4.0.0 → 4.2.0

package/scripts/pi-update.mjs

@@ -0,0 +1,223 @@
+// Narrow update ownership proof. Deliberately independent of Shell upgrade/uninstall.
+import { posix, win32 } from 'node:path';
+import { bundledUpdatePlan } from '../runtime/gentle-shell-bundled.mjs';
+
+const PI = '@earendil-works/pi-coding-agent';
+const SHELL = 'gentle-pi';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const succeeded = result => result?.code === 0 && !result.timedOut && result.signal == null;
+const refusal = detail => new Error(`gentle-shell update: ownership ${detail}; update Pi with the package manager or source checkout that supplies the selected runtime. No installation changed.`);
+const LINKED = /^(?:file|link|workspace):/i;
+const CLI_TAIL = /[\\/]dist[\\/]bundle[\\/]cli\.js$/i;
+// A quoted cli.js target inside a package-manager shim: pnpm's POSIX shim
+// (`"$basedir/../global/.../cli.js"`), its `.CMD`/npm's `.cmd` shim
+// (`"%~dp0\\...\\cli.js"`, `"%dp0%\\...\\cli.js"`) or an absolute path.
+const SHIM_TARGET = /"((?:\$basedir[\\/]|%~?dp0%?[\\/])?[^"]*?[\\/]dist[\\/]bundle[\\/]cli\.js)"/g;
+
+export function managedUpdatePlan(args) {
+ // The legacy extension-only alias must never trigger self-update.
+ if (args.includes('--extensions-only')) return {self:false, piArgs:args};
+ return bundledUpdatePlan(args);
+}
+
+function pathsFor(platform) {
+ const path = platform === 'win32' ? win32 : posix;
+ const key = value => platform === 'win32' ? path.normalize(value).toLowerCase() : path.normalize(value);
+ return {path, key};
+}
+
+function canonicalWith(adapters, path) {
+ return async value => {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) throw refusal('has no absolute package path');
+  const result = await adapters.fs.realpath(value);
+  if (typeof result !== 'string' || !path.isAbsolute(result)) throw refusal('has an invalid canonical path');
+  return result;
+ };
+}
+
+/** The cli.js a selected PATH or GENTLE_SHELL_PI executable runs: itself when
+ * it is the entry (npm's bin symlink resolves there), otherwise the single
+ * target its shim names, relative to the shim's directory. Anything else
+ * cannot be matched against a listed package and is refused.
+ */
+async function selectedCliOf(runtime, {adapters, path, canonical}) {
+ if (runtime.kind === 'bundled') return canonical(runtime.args[0]);
+ const file = await canonical(runtime.args.length ? runtime.args[0] : runtime.command);
+ if (CLI_TAIL.test(file)) return file;
+ let text;
+ try { text = String(await adapters.fs.readFile(file, 'utf8')); } catch { throw refusal('cannot read the selected executable'); }
+ const targets = new Set();
+ for (const [, quoted] of text.matchAll(SHIM_TARGET)) {
+  const relative = /^(?:\$basedir|%~?dp0%?)[\\/]/.exec(quoted);
+  const target = relative ? path.join(path.dirname(file), quoted.slice(relative[0].length)) : quoted;
+  if (!path.isAbsolute(target)) throw refusal('selected shim names a relative target');
+  targets.add(path.normalize(target));
+ }
+ if (targets.size !== 1) throw refusal(targets.size === 0 ? 'selected executable is not a Pi entry or shim' : 'selected shim names several targets');
+ return canonical([...targets][0]);
+}
+
+async function manifestOf(adapters, path, root) {
+ return JSON.parse(await adapters.fs.readFile(path.join(root, 'package.json'), 'utf8'));
+}
+
+/** The Pi package a canonical Shell root runs as its adjacent peer, as
+ * { root, manifest, cli }, or null when none resolves. pnpm's linked store
+ * places the peer beside the Shell package (`<...>/node_modules/<PI>`), npm
+ * nests it (`<shell>/node_modules/<PI>`); the global group's own
+ * `node_modules` is the last place a peer link can live.
+ */
+async function adjacentPeer({shellRoot, groupRoot, adapters, path, key, canonical}) {
+ const places = [path.join(shellRoot, 'node_modules', PI), path.join(path.dirname(shellRoot), PI)];
+ if (groupRoot) places.push(path.join(groupRoot, PI));
+ for (const place of places) {
+  let root;
+  try { root = await canonical(place); } catch { continue; }
+  const manifest = await manifestOf(adapters, path, root);
+  if (manifest.name !== PI || manifest.bin?.pi !== 'dist/bundle/cli.js') throw refusal('adjacent Pi identity differs');
+  const cli = await canonical(path.join(root, manifest.bin.pi));
+  // The canonical package root must supply its own CLI file, not a link elsewhere.
+  if (key(cli) !== key(path.join(root, manifest.bin.pi))) throw refusal('adjacent Pi package root does not supply its CLI');
+  return {root, manifest, cli};
+ }
+ return null;
+}
+
+// Package managers run from a neutral directory: inside a project, pnpm
+// honors that project's `packageManager` pin and may download another pnpm
+// before answering, and the global installation does not depend on the cwd.
+async function globalListing(name, invocation, adapters, cwd) {
+ const argv = name === 'pnpm' ? ['list', '-g', '--depth', '0', '--json'] : ['ls', '-g', '--depth=0', '--json', '--long'];
+ const result = await adapters.run(invocation.command, [...invocation.prefix, ...argv], {deadlineMs:30_000, cwd});
+ if (!succeeded(result)) throw refusal('listing failed');
+ const json = JSON.parse(result.stdout);
+ const groups = name === 'pnpm' ? json : [json];
+ if (!Array.isArray(groups) || groups.length === 0) throw refusal('listing is malformed');
+ return groups;
+}
+
+async function invocationFor(name, adapters, platform) {
+ const invocation = adapters.invocation ? await adapters.invocation(name) : await adapters.which(name).then(command => command ? {command, prefix:[]} : null);
+ if (!invocation) return null;
+ if (platform === 'win32' && /\.(cmd|bat)$/i.test(invocation.command)) throw refusal(`cannot run ${name} without its shell shim`);
+ return invocation;
+}
+
+/** Every listed top-level Pi or Shell package of one manager, with the
+ * canonical global group it links from and that group's member names.
+ */
+async function listedEntries(groups, {adapters, path, key, canonical}) {
+ const entries = [];
+ const members = new Map();
+ for (const group of groups) {
+  if (!object(group) || typeof group.path !== 'string' || !object(group.dependencies)) throw refusal('listing is malformed');
+  for (const [pkg, dependency] of Object.entries(group.dependencies)) {
+   if (!object(dependency) || !/^(?:@[^/\\]+\/)?[^/\\]+$/.test(pkg)) throw refusal('listing is malformed');
+   // pnpm's JSON may aggregate several global groups. The dependency's
+   // listed link location, not the aggregate group.path or canonical store
+   // package root, identifies which old group `add -g` would replace.
+   const listed = dependency.path;
+   if (typeof listed !== 'string' || !path.isAbsolute(listed)) throw refusal('listed package path is missing');
+   const modules = pkg.startsWith('@') ? path.dirname(path.dirname(listed)) : path.dirname(listed);
+   if (path.basename(modules) !== 'node_modules' || key(path.join(modules, pkg)) !== key(listed)) throw refusal('listed top-level group is unknown');
+   const groupRoot = await canonical(modules);
+   const set = members.get(key(groupRoot)) ?? new Set();
+   set.add(pkg);
+   members.set(key(groupRoot), set);
+   if (pkg === PI || pkg === SHELL) entries.push({pkg, dependency, groupRoot});
+  }
+ }
+ return {entries, members};
+}
+
+/** A single listed package must supply the exact selected executable.
+ * pnpm v11 lists separate global groups whose packages resolve into a linked
+ * store outside PNPM_HOME. Neither containment nor a package name proves
+ * ownership. An adjacent runtime is owned by the Shell group that resolved
+ * it: updating a separate global Pi never changes what that Shell runs.
+ */
+export async function resolveUpdateOwner({runtime, packageRoot, platform = process.platform, adapters, cwd}) {
+ const {path, key} = pathsFor(platform);
+ const canonical = canonicalWith(adapters, path);
+ const selected = await selectedCliOf(runtime, {adapters, path, canonical});
+ const shellRoot = await canonical(packageRoot);
+ const adjacent = runtime.kind === 'bundled';
+ const candidates = [];
+ for (const name of ['pnpm', 'npm']) {
+  const invocation = await invocationFor(name, adapters, platform);
+  if (!invocation) continue;
+  const groups = await globalListing(name, invocation, adapters, cwd);
+  const {entries, members} = await listedEntries(groups, {adapters, path, key, canonical});
+  for (const {pkg, dependency, groupRoot} of entries) {
+   if ((pkg === SHELL) !== adjacent) continue;
+   if (dependency.link === true || [dependency.resolved, dependency.version].some(value => typeof value === 'string' && LINKED.test(value))) throw refusal('listed supplier is a source or linked package');
+   const root = await canonical(dependency.path);
+   const manifest = await manifestOf(adapters, path, root);
+   if (manifest.name !== pkg) throw refusal('listed package identity differs');
+   let cli, spec;
+   if (pkg === PI) {
+    if (manifest.bin?.pi !== 'dist/bundle/cli.js') throw refusal('listed Pi bin is unsupported');
+    cli = await canonical(path.join(root, manifest.bin.pi));
+    if (key(cli) !== key(path.join(root, manifest.bin.pi))) throw refusal('listed Pi package root does not supply its CLI');
+    spec = `${PI}@latest`;
+   } else {
+    // Only the Shell package this launcher runs from can own its peer.
+    if (key(root) !== key(shellRoot)) continue;
+    const peer = await adjacentPeer({shellRoot: root, groupRoot, adapters, path, key, canonical});
+    if (!peer) continue;
+    cli = peer.cli;
+    // Reinstalling the same Shell version re-resolves its peer; `update`
+    // never upgrades Shell itself (that is `gentle-shell upgrade`).
+    if (typeof manifest.version !== 'string') throw refusal('listed Shell version is missing');
+    spec = `${SHELL}@${manifest.version}`;
+   }
+   if (key(cli) !== key(selected)) continue;
+   if (name === 'pnpm' && members.get(key(groupRoot)).size !== 1) throw refusal('selected supplier shares its global install group');
+   candidates.push({name, ...invocation, package:pkg, spec});
+  }
+ }
+ if (candidates.length !== 1) throw refusal(candidates.length > 1 ? 'is ambiguous' : 'could not be verified from global listings');
+ return candidates[0];
+}
+
+/** The Pi version the owner's package now supplies, read back from a fresh
+ * listing after the install; null when it cannot be read.
+ */
+async function suppliedPiVersion(owner, {platform, adapters, cwd}) {
+ const {path, key} = pathsFor(platform);
+ const canonical = canonicalWith(adapters, path);
+ try {
+  const groups = await globalListing(owner.name, owner, adapters, cwd);
+  const {entries} = await listedEntries(groups, {adapters, path, key, canonical});
+  for (const {pkg, dependency, groupRoot} of entries) {
+   if (pkg !== owner.package) continue;
+   const root = await canonical(dependency.path);
+   if (pkg === PI) return (await manifestOf(adapters, path, root)).version ?? null;
+   if ((await manifestOf(adapters, path, root)).name !== SHELL) continue;
+   const peer = await adjacentPeer({shellRoot: root, groupRoot, adapters, path, key, canonical});
+   if (peer) return peer.manifest.version ?? null;
+  }
+ } catch {
+  return null;
+ }
+ return null;
+}
+
+export async function updateSelectedPi(input) {
+ let owner;
+ try { owner = await resolveUpdateOwner(input); }
+ catch (error) { throw error.message?.includes('ownership') ? error : refusal('could not be resolved'); }
+ // Exactly one approved package per command; never create a comma group or
+ // reinstall arbitrary dependencies merely because they share a store.
+ const args = owner.name === 'pnpm' ? ['add', '-g', owner.spec, ...(owner.package === SHELL ? ['--allow-build=gentle-pi'] : [])] : ['install', '-g', owner.spec, ...(owner.package === PI ? ['--ignore-scripts'] : [])];
+ const result = await input.adapters.run(owner.command, [...owner.prefix, ...args], {deadlineMs:20 * 60_000, cwd: input.cwd});
+ if (!succeeded(result)) throw new Error(`gentle-shell update: ${owner.name} could not install ${owner.spec}${result?.stderrTail ? `\n${result.stderrTail}` : ''}`);
+ const after = await suppliedPiVersion(owner, input);
+ const before = input.currentVersion;
+ if (after === null) input.out?.(`${owner.name} installed ${owner.spec}. The Pi version it now supplies could not be read back; run 'gentle-shell --version' to check it.`);
+ else if (before !== undefined && after === before) {
+  input.out?.(`${owner.name} installed ${owner.spec}, and the selected Pi is still ${after}.`);
+  if (owner.name === 'pnpm') input.out?.('pnpm installs only releases older than its minimumReleaseAge setting (pnpm 11 defaults to 4320 minutes); a newer Pi release is picked up once it is old enough.');
+ } else input.out?.(`${owner.name} installed ${owner.spec}; the selected Pi is now ${after}${before !== undefined ? ` (was ${before})` : ''}.`);
+ return 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

@@ -10,7 +10,9 @@
 // POSIX and Windows CI.
 
 import { spawn } from "node:child_process";
-import { readFileSync, realpathSync } from "node:fs";
+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([
@@ -20,14 +22,26 @@ export const DEFAULT_STAGES = Object.freeze([
 ]);
 
 export async function runStage(stage) {
-	return await new Promise((resolve) => {
-		const child = spawn(stage.command, { shell: true, stdio: "inherit" });
-		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 });
+	// 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) } = {}) {