pi-cockpit 0.24.2 → 0.24.4

package/README.md

@@ -2,7 +2,7 @@
 
 A responsive **agent cockpit** for [Pi](https://pi.dev): wide terminals get a docked Maestro operations sidebar, narrow terminals automatically fall back to the existing Todo and Agent widgets, and every layout keeps the Starship-style footer.
 
-It is the third plugin of the `pi-maestro-flow` project (alongside `pi-maestro-flow` and `pi-maestro-teammate`). It is installed and registered with `pi-maestro-flow`, but it also runs standalone. Current version: **0.24.2**.
+It is the third plugin of the `pi-maestro-flow` project (alongside `pi-maestro-flow` and `pi-maestro-teammate`). It is installed and registered with `pi-maestro-flow`, but it also runs standalone. Current version: **0.24.3**, with optional Teammate peer `^2.8.1` and Node.js minimum 22.19.0; Settings-Core 0.2.3 is unchanged. See [RELEASE.md](../../RELEASE.md) for suite dependency changes and verification scope.
 
 The dock is a non-capturing top-right overlay. Cockpit reserves its columns by wrapping the active TUI renderer at runtime, so the Pi workspace reflows instead of rendering underneath it. No Pi source files are modified.
 
@@ -25,7 +25,7 @@ The dock is a non-capturing top-right overlay. Cockpit reserves its columns by w
 `pi-cockpit` comes automatically with the orchestration layer — installing `pi-maestro-flow` pulls `pi-cockpit` and registers it into `settings.packages` on postinstall, no manual setup required. To use it on its own:
 
 ```bash
-pi install npm:pi-cockpit@0.24.2     # standalone from npm
+pi install npm:pi-cockpit@0.24.3     # standalone from npm
 # or, for one run:
 pi -e ./packages/pi-cockpit
 ```

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "pi-cockpit",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "description": "Responsive Maestro operations sidebar, fallback status widgets, and footer for Pi.",
   "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -18,7 +21,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/ui-ownership-runtime.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/compaction-style.test.ts tests/quiet-tools.test.ts tests/native-host.test.ts tests/native-host-entry.test.ts tests/native-host-quiet.test.ts tests/edit-guard.test.ts tests/agents-store.test.ts tests/endpoint-store.test.ts tests/session-ui-state.test.ts tests/session-tabs.test.ts tests/agent-bar.test.ts tests/supervision-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/todo-overlay.test.ts tests/agent-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/agent-scroll.test.ts tests/session-bar.test.ts tests/session-detail.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/teammate-message.test.ts tests/input-routing.test.ts tests/input-history-store.test.ts tests/unified-editor.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/zen-render.test.ts tests/zen-browse.test.ts tests/zen-sheet.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/model-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/tui-i18n.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts tests/ui-primitives.test.ts tests/settings-shell-secret.test.ts tests/settings-shell-listcrud.test.ts tests/capturing-overlay.test.ts tests/claude-editor.test.ts tests/fullscreen-controller.test.ts tests/transcript-selection.test.ts tests/terminal-cleanup.test.ts tests/terminal-capability.test.ts tests/usage-core.test.ts tests/usage-extension.test.ts tests/usage-history.test.ts tests/usage-sparkline.test.ts tests/patch-health.test.ts",
+    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/ui-ownership-runtime.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/terminal-emulator.test.ts tests/compaction-style.test.ts tests/quiet-tools.test.ts tests/native-host.test.ts tests/native-host-entry.test.ts tests/native-host-quiet.test.ts tests/edit-guard.test.ts tests/agents-store.test.ts tests/endpoint-store.test.ts tests/session-ui-state.test.ts tests/session-tabs.test.ts tests/agent-bar.test.ts tests/supervision-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/todo-overlay.test.ts tests/agent-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/agent-scroll.test.ts tests/session-bar.test.ts tests/session-detail.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/teammate-message.test.ts tests/input-routing.test.ts tests/input-history-store.test.ts tests/unified-editor.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/zen-render.test.ts tests/zen-browse.test.ts tests/zen-sheet.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/model-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/tui-i18n.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts tests/ui-primitives.test.ts tests/settings-shell-secret.test.ts tests/settings-shell-listcrud.test.ts tests/capturing-overlay.test.ts tests/claude-editor.test.ts tests/fullscreen-controller.test.ts tests/transcript-selection.test.ts tests/terminal-cleanup.test.ts tests/terminal-capability.test.ts tests/usage-core.test.ts tests/usage-extension.test.ts tests/usage-history.test.ts tests/usage-sparkline.test.ts tests/patch-health.test.ts",
     "typecheck": "tsc --noEmit",
     "prepack": "node ../../scripts/bundle-settings-core.mjs",
     "postpack": "node ../../scripts/bundle-settings-core.mjs --clean"
@@ -43,7 +46,7 @@
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "pi-maestro-teammate": "^2.5.0",
+    "pi-maestro-teammate": "^2.8.1",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
@@ -72,7 +75,7 @@
     "@earendil-works/pi-coding-agent": "0.99.0",
     "@earendil-works/pi-tui": "0.99.0",
     "@types/node": "^22.0.0",
-    "pi-maestro-teammate": "2.8.0",
+    "pi-maestro-teammate": "2.8.1",
     "typebox": "1.3.27",
     "typescript": "^5.5.0"
   },

package/src/agents-store.ts

@@ -169,6 +169,13 @@ class RuntimeReadModelProjectionV2 {
 
 	get cursor(): number { return this.#cursor; }
 
+	clear(): void {
+		this.#agents.clear();
+		this.#cursor = 0;
+		this.#source = { streamId: "uninitialized", revision: 1, generation: 1 };
+		this.#initialized = false;
+	}
+
 	applySnapshot(input: unknown): boolean {
 		const snapshot = parseRuntimeReadModelSnapshotV2(input);
 		if (!snapshot) return false;
@@ -817,12 +824,21 @@ export class AgentsStore {
 				changed = true;
 			}
 		}
+		// Do not delete raw V2 entities here: their generation fences and parent
+		// relationships belong to the source stream, not the display TTL. A later
+		// delta may wake the same logical agent. Only source tombstones, replacement
+		// snapshots and clear() can safely release that canonical history.
 		for (const [id, at] of this.completedAt) {
 			if (now - at >= COMPLETED_TOMBSTONE_MS) this.completedAt.delete(id);
 		}
 		return changed;
 	}
 
+	/** Tombstones need cleanup even after the last visible terminal row expires. */
+	hasPendingCleanup(): boolean {
+		return this.completedAt.size > 0 || this.hasLingering();
+	}
+
 	/** True while a terminal row is counting down, so the redraw loop can expire it. */
 	hasLingering(): boolean {
 		for (const row of this.roster.values()) {
@@ -1025,6 +1041,7 @@ export class AgentsStore {
 
 	clear(): void {
 		this.roster.clear();
+		this.runtimeProjection.clear();
 		this.completedAt.clear();
 		this.canonicalRoster = false;
 		this.viewingId = undefined;
@@ -1149,6 +1166,17 @@ export class AgentReadStoreRouter {
 		return this.applyRuntimeDeltaResult(payload) === "applied";
 	}
 
+	/** Cleanup is independent of which read source is rendered. Never prune on event ingestion. */
+	prune(now = Date.now()): boolean {
+		const legacyChanged = this.legacy.prune(now);
+		const runtimeChanged = this.runtime.prune(now);
+		return legacyChanged || runtimeChanged;
+	}
+
+	hasPendingCleanup(): boolean {
+		return this.legacy.hasPendingCleanup() || this.runtime.hasPendingCleanup();
+	}
+
 	fallback(): void {
 		this.active = this.legacy;
 	}

package/src/footer.ts

@@ -34,6 +34,7 @@ export interface FooterParts {
 	currencyRate?: number;
 	git?: string;
 	agentSummary?: string;
+	bashBgStatus?: string;
 	workflowStatus?: string;
 	/** Maestro workflow session/run snapshot from the UI projection channel. */
 	maestroWorkflow?: MaestroWorkflowV1 | null;
@@ -469,6 +470,9 @@ export function renderFooter(p: FooterParts): string[] {
 
 	const line1 = alignRight(fittedLeft.join(identitySeparator), right1, width, utils.measure);
 	const lines = [utils.clip(line1, width, ell)];
+	if (p.bashBgStatus) {
+		lines.push(utils.clip(p.bashBgStatus, width, ell));
+	}
 	if (p.usageStatus) {
 		lines.push(utils.clip(p.usageStatus, width, ell));
 	}

package/src/fullscreen-controller.ts

@@ -6,7 +6,7 @@ import {
 	createTranscriptSelectionController,
 	type TranscriptSelectionController,
 } from "./transcript-selection.ts";
-import { registerTerminalCleanup } from "./terminal-cleanup.ts";
+import { ensureProcessTerminalCleanup } from "./terminal-cleanup.ts";
 import { readStableReference } from "./stable-reference.ts";
 
 export const COCKPIT_FULLSCREEN_WIDGET_KEY = "cockpit-fullscreen-anchor";
@@ -280,12 +280,10 @@ export function createFullscreenController(options: FullscreenControllerOptions
 		} catch (error) {
 			reportError(error);
 		}
-		// Crash safety: restore the terminal if the process dies while the alternate
-		// screen is active (reload/exit/SIGINT). Ref-counted owner; kept for the
-		// process lifetime so the comprehensive restore also covers graceful exits
-		// where pi's own restore may be incomplete.
+		// Crash/graceful-exit safety survives UI disposal through one stdout writer,
+		// not one closure retaining each attached TUI and its render history.
 		try {
-			registerTerminalCleanup((sequence) => nextTui.terminal.write(sequence));
+			ensureProcessTerminalCleanup();
 		} catch (error) {
 			reportError(error);
 		}
@@ -341,11 +339,8 @@ export function createFullscreenController(options: FullscreenControllerOptions
 				unsubscribeInput = undefined;
 			}
 			if (tui) flushMouseReportingWrites(tui);
-			// Keep the terminal cleanup registered for the process lifetime. On a
-			// graceful exit, dispose runs BEFORE process.exit, so releasing the
-			// cleanup here would remove the comprehensive exit-flush (kitty/mouse/
-			// raw restore) that must run as a safety net in case pi's own restore is
-			// incomplete on the user's terminal.
+			// The singleton process-output cleanup survives dispose, which runs before
+			// exit. Preserve that comprehensive kitty/mouse/raw restore safety net.
 			selection.clear();
 			// Leaving the alternate screen returns to the main screen; force a full
 			// redraw so the main-screen document is repainted instead of diffed

package/src/index.ts

@@ -46,6 +46,7 @@ import {
 	type FullscreenController,
 } from "./fullscreen-controller.ts";
 import { BashBgOverlay } from "./bash-bg-overlay.ts";
+import { renderBashBgSummary } from "./bash-bg-widget.ts";
 import { TodoOverlay } from "./todo-overlay.ts";
 import { AgentOverlay } from "./agent-overlay.ts";
 import { registerQuietTools } from "./quiet-tools.ts";
@@ -697,7 +698,7 @@ export default function (pi: ExtensionAPI): void {
 		running,
 		agentActive: agents.hasActive(),
 		bashActive: bashBg.hasActive(),
-		lingering: agents.hasLingering(),
+		lingering: agentReads.hasPendingCleanup(),
 		ticking: tick !== undefined,
 	});
 	// True only while a redraw loop is actually running; widgets use it to avoid
@@ -715,13 +716,11 @@ export default function (pi: ExtensionAPI): void {
 			const now = Date.now();
 			nowSnapshot = now;
 			activeBashBgOverlay?.tick(now);
-			const agentCountBeforePrune = agents.size;
-			agents.snapshot(now);
-			const agentsPruned = agents.size !== agentCountBeforePrune;
+			const agentsPruned = agentReads.prune(now);
 			if (agentsPruned) endpoints.refreshLegacy();
 			if (needsTick()) {
 				// Static mode keeps the loop alive only so lingering rows can expire
-				// (prune is read-driven). The rows themselves are static, so skip the
+				// (including the hidden shadow and tombstones). The rows are static, so skip the
 				// full repaint and repaint just once when a prune removed something.
 				if (config.staticMode) {
 					if (agentsPruned) req();
@@ -1574,6 +1573,19 @@ export default function (pi: ExtensionAPI): void {
 					const branch = footerData.getGitBranch();
 					const extensionStatuses = collectExtensionStatuses(footerData.getExtensionStatuses());
 					const glyphs = resolveGlyphs(config.icons.mode);
+					const now = nowSnapshot;
+					const bashBgStatus = renderBashBgSummary(
+						bashBg.snapshot(),
+						Math.max(1, width - 1),
+						theme,
+						FOOTER_UTILS,
+						{
+							glyphs,
+							spin: spinFrame(glyphs, now, isAnimating()),
+							now,
+							hideLiveDuration: config.staticMode,
+						},
+					)[0];
 					const totals = getUsageTotals(ctx.sessionManager.getEntries());
 					const usageStatus = config.usage.enabled && config.usage.footer
 						? usageSubsystem?.getStatus(theme, config.usage.barWidth)
@@ -1587,7 +1599,7 @@ export default function (pi: ExtensionAPI): void {
 						formatCwd(ctx.sessionManager.getCwd()),
 						cu?.percent ?? 0, cu?.tokens ?? 0, cu?.contextWindow ?? ctx.model?.contextWindow ?? 0,
 						refId(totals), config.currency ?? "", config.currencyRate ?? "",
-						branch ?? "", usageStatus ?? "",
+						branch ?? "", bashBgStatus ?? "", usageStatus ?? "",
 						extensionStatuses.map((status) => `${status.key}:${status.text}`).join("|"),
 						refId(maestroWorkflow), maestro.contentRevision,
 					].join(";");
@@ -1604,6 +1616,7 @@ export default function (pi: ExtensionAPI): void {
 						currency: config.currency,
 						currencyRate: config.currencyRate,
 						git: branch ?? undefined,
+						bashBgStatus,
 						usageStatus,
 						workflowStatus: extensionStatuses.find((status) => status.key === WORKFLOW_STATUS_KEY)?.text,
 						maestroWorkflow,
@@ -1856,31 +1869,30 @@ export default function (pi: ExtensionAPI): void {
 				// session_start broadcast (and its query may have raced startup).
 				publishUiOwnership();
 				if (!isStartedPayload(payload) || !agentReads.applyLegacyStarted(payload)) return;
+				syncTick();
 				if (usingRuntimeV2) return;
 				agents = agentReads.current;
 				endpoints.refreshLegacy();
 				if (!syncActiveAgentSurface()) return;
-				syncTick();
 				req();
 			}),
 			pi.events.on(TEAMMATE_MESSAGE_EVENT, (payload) => {
 				if (!isProgressPayload(payload) || !agentReads.applyLegacyMessage(payload)) return;
+				syncTick();
 				if (usingRuntimeV2) return;
 				agents = agentReads.current;
 				endpoints.refreshLegacy();
 				if (!syncActiveAgentSurface()) return;
-				syncTick();
 				req();
 			}),
 			pi.events.on(TEAMMATE_COMPLETE_EVENT, (payload) => {
+				// Hidden legacy completions still need row/tombstone expiry while V2 renders.
 				if (!isCompletePayload(payload) || !agentReads.applyLegacyComplete(payload)) return;
+				syncTick();
 				if (usingRuntimeV2) return;
 				agents = agentReads.current;
 				endpoints.refreshLegacy();
 				if (!syncActiveAgentSurface()) return;
-				// A failure that arrives after the session went idle still needs a loop to
-				// expire it, so the tick is re-evaluated rather than assumed to be running.
-				syncTick();
 				req();
 			}),
 			pi.events.on(RUNTIME_READ_MODEL_SNAPSHOT_EVENT, (payload) => {

package/src/quiet-tools.ts

@@ -483,6 +483,8 @@ export function toolResultCard(
 	o: {
 		name: string;
 		ok?: boolean;
+		/** Pre-colored glyph overriding the ✓/✗ status mark (e.g. "←" for incoming messages). */
+		mark?: string;
 		arg?: string;
 		summary?: string;
 		rows?: string[];
@@ -493,9 +495,9 @@ export function toolResultCard(
 	const bold = theme.bold ?? ((text: string) => text);
 	return {
 		render(width: number): string[] {
-			const mark = o.ok === false
+			const mark = o.mark ?? (o.ok === false
 				? theme.fg("error", quietStatusMark("failure"))
-				: theme.fg("success", quietStatusMark("success"));
+				: theme.fg("success", quietStatusMark("success")));
 			const safeWidth = Math.max(1, width);
 			if (safeWidth <= 1) return [];
 			const label = `${mark} ${theme.fg("toolTitle", bold(o.name))}${o.arg ? ` ${theme.fg("accent", o.arg)}` : ""}${o.summary ? ` ${theme.fg("dim", `· ${o.summary}`)}` : ""}`;

package/src/teammate-message.ts

@@ -1,7 +1,8 @@
 import { stripVTControlCharacters } from "node:util";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import { Box, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
 import { tuiT } from "./tui-i18n.ts";
+import { toolResultCard } from "./quiet-tools.ts";
 
 export const TEAMMATE_MESSAGE_CUSTOM_TYPE = "teammate-message";
 
@@ -93,27 +94,6 @@ function kindLabel(kind: string | undefined): string | undefined {
 	return key ? tuiT(key) : kind;
 }
 
-const COLLAPSED_BODY_LINES = 2;
-
-function collapsedBody(value: string, width: number): string {
-	const text = value.replace(/\s+/g, " ").trim();
-	if (!text) return "";
-	const lineWidth = Math.max(1, width);
-	const lines = wrapTextWithAnsi(text, lineWidth);
-	if (lines.length <= COLLAPSED_BODY_LINES) return lines.join("\n");
-
-	const preview = lines.slice(0, COLLAPSED_BODY_LINES);
-	const last = preview.length - 1;
-	const ellipsisWidth = Math.max(1, visibleWidth("…"));
-	const prefix = truncateToWidth(
-		preview[last] ?? "",
-		Math.max(0, lineWidth - ellipsisWidth),
-		"",
-	);
-	preview[last] = `${prefix}…`;
-	return preview.join("\n");
-}
-
 export function renderIncomingTeammateMessage(
 	message: { content: MessageContent; details?: TeammateMessageDetails },
 	options: { expanded: boolean; outputPad: number },
@@ -121,26 +101,19 @@ export function renderIncomingTeammateMessage(
 ): Component {
 	const envelope = parseTeammateMessageEnvelope(message.content, message.details);
 	const kind = kindLabel(envelope.kind);
-	const header = [
-		`${theme.fg("accent", "←")} ${theme.bold(tuiT("message.receivedFrom", { sender: envelope.sender }))}`,
-		kind ? theme.fg("muted", `· ${kind}`) : "",
-	].filter(Boolean).join(" ");
-	const box = new Box(options.outputPad, 1, (text) => theme.bg("customMessageBg", text));
-	box.addChild({
-		render(width: number): string[] {
-			const sections = [header];
-			if (options.expanded && envelope.guidance) sections.push(theme.fg("dim", envelope.guidance));
-			if (envelope.body) {
-				const body = options.expanded ? envelope.body : collapsedBody(envelope.body, width);
-				sections.push(theme.fg("text", body));
-			} else if (!options.expanded && envelope.guidance) {
-				sections.push(theme.fg("text", collapsedBody(envelope.guidance, width)));
-			}
-			return new Text(sections.join("\n"), 0, 0).render(width);
-		},
-		invalidate(): void {},
+	const groups: string[][] = [];
+	if (options.expanded && envelope.guidance) {
+		groups.push(envelope.guidance.split("\n").map((line) => theme.fg("dim", line)));
+	}
+	const bodySource = envelope.body || (!options.expanded ? envelope.guidance : "");
+	if (bodySource) groups.push(bodySource.split("\n"));
+	return toolResultCard(theme, {
+		name: tuiT("message.receivedFrom", { sender: envelope.sender }),
+		mark: theme.fg("accent", "←"),
+		...(kind ? { summary: kind } : {}),
+		groups,
+		maxBodyRows: options.expanded ? undefined : 8,
 	});
-	return box;
 }
 
 export function registerTeammateMessageRenderer(

package/src/terminal-cleanup.ts

@@ -11,7 +11,7 @@
  * host; unknown modes are ignored by terminals.
  *
  * Exactly one owner registers the handlers; they are removed when the last
- * consumer unregisters. SIGKILL / power loss cannot run any code — the
+ * consumer unregisters unless the bounded process-output fallback is retained. SIGKILL / power loss cannot run any code — the
  * documented recovery for that physical case is `reset` / `stty sane`.
  */
 
@@ -32,6 +32,17 @@ export const TERMINAL_RESTORE_SEQUENCE =
 const writers = new Set<WriteFn>();
 let handlersInstalled = false;
 
+// Pi's ProcessTerminal writes to stdout. This singleton references only the
+// process output capability, never a controller/TUI or its render history.
+const writeProcessOutput: WriteFn = (sequence) => { process.stdout.write(sequence); };
+
+/** Keep one comprehensive exit/crash fallback across fullscreen recreation.
+ * Unlike consumer leases, this process-lifetime writer survives UI disposal. */
+export function ensureProcessTerminalCleanup(): void {
+	writers.add(writeProcessOutput);
+	install();
+}
+
 /** Restore raw mode to cooked, unconditionally. Primary path is Node's stream
  * API; `stty sane` is a best-effort fallback for platforms where the console
  * state is not fully reflected by setRawMode (e.g. Windows). */
@@ -100,7 +111,8 @@ function uninstall(): void {
 /**
  * Register a terminal whose alternate-screen state must be restored on process
  * exit or external SIGINT. Returns an idempotent disposer; the process handlers
- * are installed on first use and removed once the last consumer unregisters.
+ * are installed on first use and removed once the last consumer unregisters
+ * (unless the process-output fallback is retained).
  */
 export function registerTerminalCleanup(write: WriteFn): () => void {
 	writers.add(write);

package/src/viewport-stability.ts

@@ -1,11 +1,28 @@
-import type { TUI } from "@earendil-works/pi-tui";
+import { Container, type TUI } from "@earendil-works/pi-tui";
 import { readStableReference } from "./stable-reference.ts";
 
 const VIEWPORT_STABILITY_MARKER = Symbol.for("pi-cockpit.viewport-stability");
 
 type ApplyLineResets = (lines: string[]) => string[];
 
-interface ViewportTuiInternals {
+interface ComponentLayout {
+	width: number;
+	children: Array<{ component: LayoutComponent; height: number }>;
+}
+
+interface LayoutComponent {
+	render?: (width: number) => string[];
+	children?: LayoutComponent[];
+	mouseLayout?: ComponentLayout;
+}
+
+interface HiddenComponent {
+	component: LayoutComponent;
+	start: number;
+	end: number;
+}
+
+interface ViewportTuiInternals extends LayoutComponent {
 	applyLineResets?: ApplyLineResets;
 	previousLines?: string[];
 	previousViewportTop?: number;
@@ -51,67 +68,48 @@ function isKittyImageLine(line: string | undefined): boolean {
 	return typeof line === "string" && line.includes("\x1b_G");
 }
 
-const ANSI_ESCAPE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g;
-
-function plainLine(line: string | undefined): string {
-	return line?.replace(ANSI_ESCAPE, "").trim() ?? "";
+// Container records these heights during the actual render. Never render a
+// component twice or infer row identity from its changing text.
+function measuredComponents(
+	root: LayoutComponent,
+	lineCount: number,
+	width: number,
+): HiddenComponent[] | undefined {
+	if (root.render !== Container.prototype.render) return undefined;
+	const result: HiddenComponent[] = [];
+	const seen = new Set<LayoutComponent>();
+	const walk = (node: LayoutComponent, start: number, height: number): boolean => {
+		if (height === 0) return true;
+		if (seen.has(node)) return false;
+		seen.add(node);
+		const layout = node.mouseLayout;
+		if (node.render === Container.prototype.render && Array.isArray(node.children)) {
+			if (!layout || layout.width !== width || layout.children.length !== node.children.length) return false;
+			let total = 0;
+			for (let index = 0; index < layout.children.length; index += 1) {
+				const child = layout.children[index]!;
+				if (child.component !== node.children[index] || !Number.isSafeInteger(child.height) || child.height < 0) return false;
+				total += child.height;
+			}
+			if (total !== height) return false;
+			let offset = start;
+			for (const child of layout.children) {
+				if (!walk(child.component, offset, child.height)) return false;
+				offset += child.height;
+			}
+			return true;
+		}
+		result.push({ component: node, start, end: start + height });
+		return true;
+	};
+	return Array.isArray(root.children) && walk(root, 0, lineCount) ? result : undefined;
 }
 
-function lineCounts(lines: readonly string[], start: number, end: number): Map<string, number> {
-	const counts = new Map<string, number>();
-	const lo = Math.max(0, start);
-	const hi = Math.min(end, lines.length);
-	for (let index = lo; index < hi; index += 1) {
-		const key = plainLine(lines[index]);
-		if (!key) continue;
-		counts.set(key, (counts.get(key) ?? 0) + 1);
-	}
-	return counts;
-}
-
-function mutableLineIdentity(line: string | undefined): string {
-	return plainLine(line).toLowerCase().replace(/\d+(?:\.\d+)?/g, "#");
-}
-
-function mutableRowsCrossViewportBoundary(
-	previousLines: readonly string[],
-	nextLines: readonly string[],
-	hiddenEnd: number,
-): boolean {
-	if (hiddenEnd <= 0 || hiddenEnd >= previousLines.length || hiddenEnd >= nextLines.length) return false;
-	const previousHidden = mutableLineIdentity(previousLines[hiddenEnd - 1]);
-	const previousVisible = mutableLineIdentity(previousLines[hiddenEnd]);
-	const nextHidden = mutableLineIdentity(nextLines[hiddenEnd - 1]);
-	const nextVisible = mutableLineIdentity(nextLines[hiddenEnd]);
-	return previousHidden !== ""
-		&& previousVisible !== ""
-		&& previousHidden !== previousVisible
-		&& previousHidden === nextVisible
-		&& previousVisible === nextHidden;
-}
-
-function crossesViewportBoundary(
-	previousLines: readonly string[],
-	nextLines: readonly string[],
-	hiddenEnd: number,
-): boolean {
-	if (mutableRowsCrossViewportBoundary(previousLines, nextLines, hiddenEnd)) return true;
-	// A row crosses the boundary when its hidden- and visible-side counts move
-	// in opposite directions (net flow across). Counting both regions — rather
-	// than tracking unique positions — detects crossings for duplicated lines
-	// (identical agent rows, separators) that a position map silently drops,
-	// while in-place edits of hidden rows change only one side and stay frozen.
-	const prevHidden = lineCounts(previousLines, 0, hiddenEnd);
-	const prevVisible = lineCounts(previousLines, hiddenEnd, previousLines.length);
-	const nextHidden = lineCounts(nextLines, 0, hiddenEnd);
-	const nextVisible = lineCounts(nextLines, hiddenEnd, nextLines.length);
-	const keys = new Set([...prevHidden.keys(), ...prevVisible.keys(), ...nextHidden.keys(), ...nextVisible.keys()]);
-	for (const key of keys) {
-		const hiddenDelta = (nextHidden.get(key) ?? 0) - (prevHidden.get(key) ?? 0);
-		const visibleDelta = (nextVisible.get(key) ?? 0) - (prevVisible.get(key) ?? 0);
-		if (hiddenDelta !== 0 && visibleDelta !== 0 && Math.sign(hiddenDelta) !== Math.sign(visibleDelta)) return true;
-	}
-	return false;
+function sameHiddenComponents(previous: readonly HiddenComponent[], next: readonly HiddenComponent[]): boolean {
+	return previous.length === next.length && previous.every((span, index) => {
+		const other = next[index]!;
+		return span.component === other.component && span.start === other.start && span.end === other.end;
+	});
 }
 
 function prototypeMethodSlot(target: object): ApplyLineResetsSlot | undefined {
@@ -164,10 +162,9 @@ function resolveApplyLineResetsSlot(internals: ViewportTuiInternals): ApplyLineR
 }
 
 /**
- * Treats the hidden viewport prefix as immutable scrollback while frame size is
- * stable. The next frame keeps the terminal's actual hidden text, so visible
- * changes can use pi-tui's differential path instead of clearing and replaying
- * the screen. Structural, resize and image changes retain the native path.
+ * Preserves fully hidden components only while their instances and measured
+ * positions stay unchanged. Boundary-spanning components, missing layout
+ * evidence, structural changes, resize and images retain the native path.
  */
 export function attachViewportStability(tui: TUI): ViewportStabilityPatch {
 	try {
@@ -183,11 +180,17 @@ export function attachViewportStability(tui: TUI): ViewportStabilityPatch {
 		if (existing) return { active: true, detach: existing.retain() };
 
 		let dispatches = 0;
+		const frames = new WeakMap<ViewportTuiInternals, { baseline: string[]; spans: HiddenComponent[] }>();
 		const wrapped: ApplyLineResets = function (this: ViewportTuiInternals, lines: string[]): string[] {
 			dispatches += 1;
 			const nextLines = original.call(this, lines);
 			const previousLines = this.previousLines;
 			const viewportTop = this.previousViewportTop;
+			const hiddenEnd = typeof viewportTop === "number" && Number.isFinite(viewportTop)
+				? Math.max(0, Math.min(nextLines.length, Math.trunc(viewportTop)))
+				: 0;
+			const spans = measuredComponents(this, nextLines.length, this.terminal?.columns ?? 0);
+			const previousFrame = frames.get(this);
 			if (
 				Array.isArray(previousLines)
 					&& previousLines.length === nextLines.length
@@ -196,20 +199,30 @@ export function attachViewportStability(tui: TUI): ViewportStabilityPatch {
 					&& viewportTop > 0
 					&& this.previousHeight === this.terminal?.rows
 					&& this.previousWidth === this.terminal?.columns
+					&& spans && previousFrame?.baseline === previousLines
+					&& sameHiddenComponents(previousFrame.spans, spans)
 			) {
-				const hiddenEnd = Math.min(previousLines.length, Math.trunc(viewportTop));
-				const hiddenHasKittyImage = previousLines.slice(0, hiddenEnd).some(isKittyImageLine)
-					|| nextLines.slice(0, hiddenEnd).some(isKittyImageLine);
-				// Equal total height does not prove row identity. If a stable row crossed
-				// the viewport boundary, freezing by index would duplicate it across the
-				// hidden and visible regions; retain pi-tui's canonical full redraw instead.
-				if (!hiddenHasKittyImage && !crossesViewportBoundary(previousLines, nextLines, hiddenEnd)) {
-					for (let index = 0; index < hiddenEnd; index += 1) {
-						const previous = previousLines[index];
-						if (previous !== undefined) nextLines[index] = previous;
+				let hiddenHasKittyImage = false;
+				for (let index = 0; index < hiddenEnd; index += 1) {
+					if (isKittyImageLine(previousLines[index]) || isKittyImageLine(nextLines[index])) {
+						hiddenHasKittyImage = true;
+						break;
+					}
+				}
+				if (!hiddenHasKittyImage) {
+					for (const span of spans) {
+						if (span.end > hiddenEnd) break;
+						for (let index = span.start; index < span.end; index += 1) nextLines[index] = previousLines[index]!;
 					}
 				}
 			}
+			if (spans) {
+				// The native no-change path keeps the old array rather than adopting
+				// nextLines. Track the exact baseline it will retain in either case.
+				const unchanged = previousLines?.length === nextLines.length
+					&& nextLines.every((line, index) => line === previousLines[index]);
+				frames.set(this, { baseline: unchanged ? previousLines! : nextLines, spans });
+			} else frames.delete(this);
 			return nextLines;
 		};
 		let references = 1;