gentle-pi 2.5.0 → 2.6.0

package/lib/shell-sidebar-banner.ts

@@ -0,0 +1,11 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { ShellBarTheme } from "./shell-bar.ts";
+
+export function renderSidebarBanner(theme: ShellBarTheme, width: number): string[] {
+	const label = "✿ Gentle-Pi ✿";
+	const space = width - visibleWidth(label);
+	if (space < 0) return [];
+	// Gentleman's accent is pink; card titles use a separate champagne role.
+	const title = theme.fg("accent", "✿") + " " + theme.fg("text", "Gentle-Pi") + " " + theme.fg("accent", "✿");
+	return [" ".repeat(Math.floor(space / 2)) + title + " ".repeat(Math.ceil(space / 2))];
+}

package/lib/shell-sidebar-layout.ts

@@ -0,0 +1,213 @@
+import { ScrollView, visibleWidth, type Component, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { sidebarState, type SidebarRail } from "./shell-sidebar.ts";
+import type { ShellBarTheme } from "./shell-bar.ts";
+import { renderSidebarBanner } from "./shell-sidebar-banner.ts";
+
+export const SIDEBAR_BREAKPOINT = 140;
+const RAIL_WIDTH = 50;
+const RAIL_PADDING = 1;
+const GAP = 3;
+// Experimental Pi 0.85.1 internals. Only the fullscreen layout tree is adapted;
+// regular mode keeps native scrollback and the original bottom components.
+const NODE = Symbol.for("@earendil-works/pi-tui/layout-node");
+type LayoutNode = { type: string; entries?: unknown[]; gap?: number; align?: string };
+type LayoutRoot = Component & { [NODE]?: () => LayoutNode };
+type Host = TUI & { mode?: string; layoutRoot?: LayoutRoot };
+type SidebarCache = { revision: number };
+type RailHit = { key: string; component: Component; startY: number; height: number; width: number };
+type SidebarPresentation = { scrollTop: number; output: LayoutNode };
+type PreparedRail = {
+	revision: number;
+	width: number;
+	mode: string | undefined;
+	root: LayoutRoot;
+	theme: ShellBarTheme;
+	parts: Array<[string, SidebarRail]>;
+	digests: Array<string | undefined>;
+	contentWidth: number;
+	active: boolean;
+	lines: string[];
+	hits: RailHit[];
+	presentation?: SidebarPresentation;
+};
+const CACHE = Symbol.for("gentle-pi.experimental-sidebar.cache");
+
+function sidebarCache(tui: TUI): SidebarCache {
+	const terminal = tui.terminal as unknown as Record<symbol, SidebarCache>;
+	return terminal[CACHE] ??= { revision: 0 };
+}
+
+/** Mark terminal-owned fullscreen sidebar output stale after a part state change. */
+export function invalidateSidebar(tui: TUI): void {
+	if (tui.terminal) sidebarCache(tui).revision++;
+}
+
+// The memo keys on part identity and an explicit revision, neither of which can
+// see live session state read inside a rail's render closure: a model switch, a
+// new context percentage or an extension status change leaves the prepared lines
+// intact. A rail that paints such state declares a digest of it, so the memo can
+// notice by itself; a throwing digest degrades that rail to invalidation-only
+// rather than taking the whole sidebar down with it.
+function railDigest(rail: SidebarRail): string | undefined {
+	try {
+		return rail.digest?.();
+	} catch {
+		return undefined;
+	}
+}
+
+export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
+	if (!tui.terminal) return () => {};
+	const host = tui as Host;
+	const state = sidebarState(tui);
+	const cache = sidebarCache(tui);
+	const cleanups: Array<() => void> = [];
+	const roots = new Set<LayoutRoot>();
+	let stopped = false;
+	let failed = false;
+	let railLines: string[] = [];
+	let prepared: PreparedRail | undefined;
+	state.active = false;
+	state.ownsHost = () => !stopped && host.mode === "fullscreen" && !!host.layoutRoot && roots.has(host.layoutRoot);
+	const rail: Component = {
+		render: () => railLines,
+		invalidate() {
+			invalidateSidebar(tui);
+			for (const part of state.parts.values()) part.invalidate();
+		},
+	};
+	const scroll = new ScrollView(rail, {
+		follow: "none",
+		primary: false,
+		overscroll: "contain",
+		scrollbar: "always",
+		scrollbarTrackStyle: (text) => theme.fg("border", text),
+		scrollbarThumbStyle: (text) => theme.fg("accent", text),
+	});
+	const nativeMouse = scroll.handleMouse.bind(scroll);
+	const dispatchPartMouse = (event: TuiMouseEvent) => {
+		const current = prepared;
+		if (!current || stopped || failed || !current.active || current.revision !== cache.revision ||
+			host.mode !== "fullscreen" || tui.terminal.columns !== current.width || host.layoutRoot !== current.root ||
+			scroll.getContentWidth(event.width) !== current.contentWidth || event.x < RAIL_PADDING ||
+			event.x >= current.contentWidth || event.y < 0 || event.y >= event.height) return undefined;
+		const contentY = scroll.scrollTop + event.y;
+		const hit = current.hits.find((candidate) => contentY >= candidate.startY && contentY < candidate.startY + candidate.height);
+		if (!hit || state.parts.get(hit.key) !== hit.component || event.x >= RAIL_PADDING + hit.width) return undefined;
+		return hit.component.handleMouse?.({
+			...event,
+			x: event.x - RAIL_PADDING,
+			y: contentY - hit.startY,
+			width: hit.width,
+			height: hit.height,
+		});
+	};
+	scroll.handleMouse = (event) => {
+		if (event.type === "wheel") {
+			// Consume even at the boundary or over blank rail space: Pi 0.85.1
+			// can send unconsumed delta to the primary transcript despite containment.
+			scroll.scrollBy(event.wheelDelta ?? 0);
+			return {
+				handled: true,
+				render: true,
+				target: { component: scroll, originX: event.screenX - event.x, originY: event.screenY - event.y, width: event.width, height: event.height },
+			};
+		}
+		return dispatchPartMouse(event) ?? nativeMouse(event);
+	};
+	const prepare = (width: number, root: LayoutRoot): boolean => {
+		state.active = false;
+		if (stopped || failed || host.mode !== "fullscreen" || width < SIDEBAR_BREAKPOINT) {
+			prepared = undefined;
+			return false;
+		}
+		const parts = [...state.parts.entries()];
+		const digests = parts.map(([, rail]) => railDigest(rail));
+		const unchanged = prepared?.revision === cache.revision &&
+			prepared.width === width && prepared.mode === host.mode && prepared.root === root && prepared.theme === theme &&
+			prepared.parts.length === parts.length && prepared.parts.every(([key, part], index) => parts[index]?.[0] === key && parts[index]?.[1] === part) &&
+			prepared.digests.length === digests.length && prepared.digests.every((digest, index) => digest === digests[index]);
+		if (unchanged) {
+			railLines = prepared.lines;
+			state.active = prepared.active;
+			return prepared.active;
+		}
+		try {
+			const contentWidth = scroll.getContentWidth(RAIL_WIDTH);
+			const sections = ["footer", "changes", "agents", "todo"].map((key) => {
+				const component = state.parts.get(key);
+				const lines = [...(component?.render(contentWidth - RAIL_PADDING * 2) ?? [])];
+				while (lines.length && lines[lines.length - 1]?.trim() === "") lines.pop();
+				return { key, component, lines };
+			}).filter((section) => section.component !== undefined && section.lines.length > 0) as Array<{ key: string; component: Component; lines: string[] }>;
+			const branding = renderSidebarBanner(theme, contentWidth - RAIL_PADDING * 2);
+			const hits: RailHit[] = [];
+			railLines = [];
+			if (sections.length && branding.length) {
+				railLines.push(...branding.map((line) => " ".repeat(RAIL_PADDING) + line + " ".repeat(RAIL_PADDING)));
+			}
+			for (const section of sections) {
+				if (railLines.length > 0) railLines.push("");
+				const startY = railLines.length;
+				railLines.push(...section.lines.map((line) => " ".repeat(RAIL_PADDING) + line + " ".repeat(RAIL_PADDING)));
+				hits.push({ key: section.key, component: section.component, startY, height: section.lines.length, width: contentWidth - RAIL_PADDING * 2 });
+			}
+			// Height is owned by the native ScrollView, never by the transcript.
+			const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
+			prepared = { revision: cache.revision, width, mode: host.mode, root, theme, parts, digests, contentWidth, active, lines: railLines, hits };
+			state.active = active;
+			return active;
+		} catch {
+			failed = true;
+			return false;
+		}
+	};
+	const attach = () => {
+		if (stopped || failed) return;
+		if (host.mode !== "fullscreen") { state.active = false; return; }
+		try {
+			const root = host.layoutRoot;
+			if (!root || typeof root[NODE] !== "function") { state.active = false; return; }
+			if (roots.has(root)) return;
+			const original = root[NODE]!;
+			const descriptor = Object.getOwnPropertyDescriptor(root, NODE);
+			const left = { render: (width: number) => root.render(width), invalidate() {}, [NODE]: () => original.call(root) };
+			const replacement = () => {
+				if (!prepare(tui.terminal.columns, root)) return original.call(root);
+				const current = prepared!;
+				if (current.presentation?.scrollTop === scroll.scrollTop) return current.presentation.output;
+				return (current.presentation = {
+					scrollTop: scroll.scrollTop,
+					output: { type: "hstack", gap: GAP, align: "stretch", entries: [
+						{ component: left, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+						{ component: scroll, basis: RAIL_WIDTH, grow: 0, shrink: 0, minSize: RAIL_WIDTH },
+					] },
+				}).output;
+			};
+			root[NODE] = replacement;
+			roots.add(root);
+			tui.requestRender();
+			cleanups.push(() => {
+				if (root[NODE] !== replacement) return;
+				if (descriptor) Object.defineProperty(root, NODE, descriptor);
+				else Reflect.deleteProperty(root, NODE);
+			});
+		} catch {
+			failed = true;
+			state.active = false;
+		}
+	};
+	attach();
+	// Pi replaces renderers without a session event. Rebind only that transition;
+	// resize and scroll remain owned by Pi's native layout/render loop.
+	const timer = setInterval(attach, 100);
+	timer.unref();
+	return () => {
+		stopped = true;
+		state.active = false;
+		clearInterval(timer);
+		scroll.hideTransientScrollbar();
+		for (const cleanup of cleanups.reverse()) cleanup();
+		tui.requestRender();
+	};
+}

package/lib/shell-sidebar.ts

@@ -0,0 +1,41 @@
+import type { Component, TUI } from "@earendil-works/pi-tui";
+
+// Store on the terminal, not a module singleton: extension loaders may isolate
+// modules, while Pi keeps this terminal across regular/fullscreen transitions.
+const STATE = Symbol.for("gentle-pi.experimental-sidebar.state");
+export interface SidebarState {
+	active: boolean;
+	ownsHost?: () => boolean;
+	parts: Map<string, SidebarRail>;
+}
+
+/** A rail slot in the fullscreen sidebar. */
+export interface SidebarRail extends Component {
+	/**
+	 * Cheap digest of the live state this rail paints. The fullscreen layout memo
+	 * re-renders a part only when its digest changes, so a rail that reads session
+	 * data (model, thinking level, context, cost, extension statuses) must declare
+	 * one; explicit invalidateSidebar() stays for discrete state changes.
+	 */
+	digest?(): string;
+}
+export function sidebarState(tui: TUI): SidebarState {
+	const terminal = tui.terminal as unknown as Record<symbol, SidebarState>;
+	return terminal[STATE] ??= { active: false, parts: new Map() };
+}
+
+/** Keep the original bottom component mounted, suppressing only its paint. */
+export function sidebarPart<T extends Component & { dispose?(): void }>(tui: TUI, key: string, bottom: T, rail: SidebarRail = bottom): T {
+	// Minimal extension hosts cannot share terminal-owned layout state.
+	if (!tui.terminal) return bottom;
+	const state = sidebarState(tui);
+	state.parts.set(key, rail);
+	return {
+		...bottom,
+		render: (width: number) => state.active && state.ownsHost?.() ? [] : bottom.render(width),
+		dispose() {
+			if (state.parts.get(key) === rail) state.parts.delete(key);
+			bottom.dispose?.();
+		},
+	};
+}

package/lib/shell-todo.ts

@@ -1,4 +1,5 @@
-import { CARD_TONE, renderCard, type CardTheme } from "./shell-card.ts";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CARD_TONE, cardInnerWidth, renderCard, type CardTheme } from "./shell-card.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 
 // Gentle Todo: the task list the model keeps while it works. Everything here
@@ -71,6 +72,8 @@ export interface TodoTheme extends CardTheme {
 }
 
 export interface TodoRenderOptions {
+	/** A scrollable host supplies the height bound instead of folding tasks. */
+	scrollable?: boolean;
 	collapsed: boolean;
 	staleTurns: number;
 	collapseKey?: string;
@@ -238,29 +241,38 @@ export function todoPromptBlock(state: TodoState, stale: number): string | undef
 	].join("\n") + staleLine;
 }
 
-function taskRow(task: TodoTask, theme: TodoTheme): string {
-	const title = task.status === TODO_STATUS.DONE ? theme.strikethrough(task.title) : task.title;
+function taskRow(task: TodoTask, theme: TodoTheme, width: number): string {
+	if (task.status === TODO_STATUS.DONE) {
+		// Wrap before applying SGR 9: every physical title closes its own style
+		// before renderCard adds padding and rails.
+		return wrapTextWithAnsi(task.title, Math.max(1, cardInnerWidth(width) - 2))
+			.map((line, index) => `${index === 0 ? theme.fg(GLYPH_ROLE[task.status], STATUS_GLYPH[task.status]) : " "} ${theme.fg(STATUS_ROLE[task.status], theme.strikethrough(line))}`)
+			.join("\n");
+	}
+	const title = task.title;
 	const note = task.status === TODO_STATUS.IN_PROGRESS && task.note ? ` ${theme.fg(NOTE_ROLE, "·")} ${theme.fg(NOTE_ROLE, task.note)}` : "";
 	return `${theme.fg(GLYPH_ROLE[task.status], STATUS_GLYPH[task.status])} ${theme.fg(STATUS_ROLE[task.status], title)}${note}`;
 }
 
 // Long lists keep the card short: done tasks fold into "✓ N done" and the
 // open ones fill the remaining rows, with a trailing count for the rest.
-function bodyRows(state: TodoState, theme: TodoTheme): string[] {
-	if (state.tasks.length <= ROW_CAP) return state.tasks.map((task) => taskRow(task, theme));
+function bodyRows(state: TodoState, theme: TodoTheme, width: number): string[] {
+	if (state.tasks.length <= ROW_CAP) return state.tasks.map((task) => taskRow(task, theme, width));
 	const { done } = todoSummary(state);
 	const open = state.tasks.filter((task) => task.status !== TODO_STATUS.DONE);
 	const rows: string[] = [];
 	if (done > 0) rows.push(`${theme.fg(GLYPH_ROLE[TODO_STATUS.DONE], STATUS_GLYPH[TODO_STATUS.DONE])} ${theme.fg(NOTE_ROLE, `${done} done`)}`);
 	const room = ROW_CAP - rows.length - (open.length > ROW_CAP - rows.length ? 1 : 0);
-	for (const task of open.slice(0, room)) rows.push(taskRow(task, theme));
+	for (const task of open.slice(0, room)) rows.push(taskRow(task, theme, width));
 	if (open.length > room) rows.push(theme.fg(NOTE_ROLE, `… ${open.length - room} more`));
 	return rows;
 }
 
-function collapsedRow(state: TodoState, theme: TodoTheme): string {
+function collapsedRow(state: TodoState, theme: TodoTheme, width: number): string {
 	const active = state.tasks.find((task) => task.status === TODO_STATUS.IN_PROGRESS);
-	if (active) return taskRow(active, theme);
+	if (active) return taskRow(active, theme, width);
+	const pending = state.tasks.find((task) => task.status === TODO_STATUS.PENDING);
+	if (pending) return taskRow(pending, theme, width);
 	const { open } = todoSummary(state);
 	return `${theme.fg(GLYPH_ROLE[TODO_STATUS.PENDING], STATUS_GLYPH[TODO_STATUS.PENDING])} ${theme.fg(NOTE_ROLE, `${open} open`)}`;
 }
@@ -269,10 +281,15 @@ export function renderTodoCard(state: TodoState, theme: TodoTheme, width: number
 	if (state.tasks.length === 0) return [];
 	const { done, total } = todoSummary(state);
 	const stale = options.staleTurns >= STALE_AFTER_TURNS;
-	const hint = stale ? `stale · ${options.staleTurns} turns` : options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : undefined;
-	const body = options.collapsed ? [collapsedRow(state, theme)] : bodyRows(state, theme);
+	const action = options.collapsed ? "expand" : "collapse";
+	const actionLabel = action[0]!.toUpperCase() + action.slice(1);
+	const icon = options.collapsed ? "▸" : "▾";
+	const control = `${icon} ${width >= 28 ? actionLabel : ""}`.trimEnd();
+	const hint = options.collapseKey ? `${options.collapseKey} ${action}` : undefined;
+	const rows = options.collapsed ? [collapsedRow(state, theme, width)] : options.scrollable ? state.tasks.map((task) => taskRow(task, theme, width)) : bodyRows(state, theme, width);
+	const body = stale ? [theme.fg(NOTE_ROLE, `stale · ${options.staleTurns} turns`), ...rows] : rows;
 	return renderCard(
-		{ title: "Todos", subtitle: `${done} of ${total}`, body, tone: stale ? CARD_TONE.WARNING : CARD_TONE.INFO, glyph: TODO_GLYPH },
+		{ title: `Todos ${theme.fg("accent", control)}`, subtitle: `${done} of ${total}`, body, tone: stale ? CARD_TONE.WARNING : CARD_TONE.INFO, glyph: TODO_GLYPH },
 		theme,
 		width,
 		{ expanded: true, hint },

package/lib/telemetry-trigger.ts

@@ -89,6 +89,7 @@ export interface TelemetryTriggerSpawnOptions {
 	cwd: string;
 	env: NodeJS.ProcessEnv;
 	detached: boolean;
+	windowsHide: boolean;
 	stdio: "ignore";
 }
 
@@ -129,6 +130,7 @@ export function spawnTelemetryTrigger(options: SpawnTelemetryTriggerOptions): Te
 			cwd: options.cwd,
 			env: options.env,
 			detached: true,
+			windowsHide: true,
 			stdio: "ignore",
 		});
 		child.on("error", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gentle-pi",
-	"version": "2.5.0",
+	"version": "2.6.0",
 	"description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
 	"license": "MIT",
 	"type": "module",
@@ -48,7 +48,8 @@
 		"check:runtime-modules": "node scripts/build-runtime-modules.mjs --check",
 		"test:packed-package": "node scripts/test-packed-runner.mjs",
 		"prepack": "pnpm test && pnpm run check:runtime-modules && node scripts/verify-package-files.mjs",
-		"prepublishOnly": "pnpm test && pnpm run check:runtime-modules && node scripts/verify-package-files.mjs && pnpm run test:packed-package"
+		"prepublishOnly": "pnpm test && pnpm run check:runtime-modules && node scripts/verify-package-files.mjs && pnpm run test:packed-package",
+		"typecheck": "node scripts/check-types.mjs"
 	},
 	"pi": {
 		"image": "https://cdn.jsdelivr.net/npm/gentle-pi/assets/gentle-logo-only.png",
@@ -79,7 +80,9 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.85.1"
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@types/node": "^24.13.3",
+		"typescript": "^5.9.3"
 	},
 	"packageManager": "pnpm@11.1.1"
 }

package/runtime/gentle-ai-binary.mjs

@@ -17,6 +17,8 @@ import {
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
+export const GENTLE_AI_INSTALL_RECOVERY_COMMAND = "node scripts/install-gentle-ai.mjs";
+export const GENTLE_AI_INSTALL_RECOVERY_INSTRUCTIONS = `If GENTLE_PI_SKIP_GENTLE_AI_INSTALL is set, remove or unset it before changing to the installed gentle-pi package directory and running \`${GENTLE_AI_INSTALL_RECOVERY_COMMAND}\`.`;
 // Derived from the one authoritative pinned version in
 // scripts/gentle-ai-installer.mjs rather than repeating the literal here, so
 // the two can never independently drift apart the way they once did.
@@ -26,7 +28,7 @@ export class PackageLocalGentleAiBinaryMissingError extends Error {
 	         code = GENTLE_AI_BINARY_MISSING_CODE;
 	constructor(path        ) {
 		super(
-			`${GENTLE_AI_BINARY_MISSING_CODE}: Gentle AI v${GENTLE_AI_VERSION} is not installed at ${path}. Reinstall gentle-pi, or use GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1 only for development/offline installs.`,
+			`${GENTLE_AI_BINARY_MISSING_CODE}: Gentle AI v${GENTLE_AI_VERSION} is not installed at ${path}. ${GENTLE_AI_INSTALL_RECOVERY_INSTRUCTIONS} A missing binary can result from skipped lifecycle scripts, but does not prove install lifecycle scripts were disabled.`,
 		);
 		this.name = "PackageLocalGentleAiBinaryMissingError";
 	}