pi-goal-x 0.27.2 → 0.27.4

package/extensions/widgets/goal-widget.ts

@@ -159,6 +159,11 @@ export const WIDGET_HEIGHT_RESERVE = 6;
  * own and can never trigger pi-tui's clearOnShrink full-render
  * (`\x1b[2J\x1b[H\x1b[3J` scrollback wipe). No-op (unbounded) when
  * terminalRows is missing (mock TUI, headless contexts, /goal-status text).
+ *
+ * This pure head-slice is the terminal bound for direct callers. The live
+ * component additionally applies the stable-height bound
+ * (spec 2026-08-11-stable-widget-height) so the rendered height stays
+ * constant within each regime — see applyStableHeightBound.
  */
 export function boundWidgetRenderLines(lines: string[], terminalRows: number | undefined): string[] {
 	if (!terminalRows || terminalRows <= 0) return lines;
@@ -167,6 +172,83 @@ export function boundWidgetRenderLines(lines: string[], terminalRows: number | u
 	return lines.slice(0, cap);
 }
 
+/**
+ * Stable rendered height per regime (spec 2026-08-11-stable-widget-height).
+ *
+ * The widget's natural (unbounded) height varies with goal state — activity
+ * feed growth, current-task contract/evidence wrapping, verification text,
+ * budget, task growth (measured 4..31 lines on a 24-row terminal). Every
+ * natural-height change alters the dock height → the terminal buffer's line
+ * count changes → the terminal scrolls to the bottom and the user cannot hold
+ * a scroll position to read the chat. The latch makes the rendered height
+ * invariant to goal-state changes in EVERY case (fits and capped):
+ *
+ * - the first render of each regime commits the rendered height
+ *   (min(natural, cap)) and every later render of that regime renders exactly
+ *   that many lines — growth is head-sliced, shrink is blank-padded, the
+ *   height never changes;
+ * - resizing the terminal clears the latch and re-evaluates
+ *   min(natural, newCap): growing the terminal reveals more of the widget,
+ *   shrinking re-caps;
+ * - a regime change (goal id/status, widget state kind, compact↔expanded,
+ *   debug mode, tasks disabled, first task appearing) clears the latch so the
+ *   new mode starts from its own natural height.
+ *
+ * Pure given the persisted latch state: deterministic, no timers, no
+ * randomness — the same goal state on the same terminal renders the same
+ * lines on every render.
+ */
+export function applyStableHeightBound(
+	lines: string[],
+	terminalRows: number | undefined,
+	state: { stickyCap: number | undefined; stickyRegime: string | undefined; stickyTerminalRows: number | undefined; stickyReserve?: number },
+	regime: string,
+	reserve: number = WIDGET_HEIGHT_RESERVE,
+): string[] {
+	if (!terminalRows || terminalRows <= 0) return lines;
+	const cap = Math.max(1, terminalRows - reserve);
+	if (state.stickyTerminalRows !== terminalRows) {
+		// Terminal resized: adapt to the new height (grow/shrink to fit).
+		state.stickyCap = undefined;
+		state.stickyTerminalRows = terminalRows;
+	}
+	if (state.stickyReserve !== reserve) {
+		// The chrome below the widget changed (editor grew/shrunk, status,
+		// footer, pending): re-evaluate so the widget's block plus the chrome
+		// never exceeds the terminal — otherwise the chat's appended lines
+		// and the status line land above pi-tui's viewport top and every
+		// agent write triggers a 2J+3J scrollback wipe (spec 2026-08-11).
+		state.stickyCap = undefined;
+		state.stickyReserve = reserve;
+	}
+	if (state.stickyRegime !== regime) {
+		// Mode/state changed: the latch belongs to one regime.
+		state.stickyCap = undefined;
+		state.stickyRegime = regime;
+	}
+	if (state.stickyCap === undefined) {
+		// First render of the regime: latch the height — the natural height
+		// when it fits, else the cap. Constant from here on, fits AND capped.
+		state.stickyCap = Math.min(lines.length, cap);
+	}
+	if (lines.length > state.stickyCap) {
+		// Growth past the committed height: head-slice (the dashboard's
+		// content priority is top-down), so the buffer line count never
+		// changes.
+		return lines.slice(0, state.stickyCap);
+	}
+	if (lines.length < state.stickyCap) {
+		// Natural dipped below the committed height: pad deterministically so
+		// the buffer line count never changes. Blank rows after the box footer
+		// — honest filler (the …/↑ N more markers are only for hidden content).
+		const padded = lines.slice();
+		while (padded.length < state.stickyCap) padded.push("");
+		return padded;
+	}
+	// Exactly the committed height: unchanged.
+	return lines;
+}
+
 function heading(theme: Theme, width: number, left: string, right = ""): string {
 	if (!right) return fit(left, width);
 	const rightPart = ` ${right}`;
@@ -273,6 +355,19 @@ export class GoalWidgetComponent implements Component {
 	private lastSeenGoalId: string | undefined;
 	private lastSeenLatestCompletedAt: string | undefined;
 
+	// Stable-height latch (spec 2026-08-11-stable-widget-height): the first
+	// render of each regime commits the rendered height (natural when it fits,
+	// else the cap); the height stays constant (head-slice growth, pad shrink)
+	// until the regime, the terminal size, or the measured dock chrome changes,
+	// so the buffer line count never changes and the terminal stops jumping to
+	// the bottom.
+	private stableHeightState: { stickyCap: number | undefined; stickyRegime: string | undefined; stickyTerminalRows: number | undefined; stickyReserve?: number } = {
+		stickyCap: undefined,
+		stickyRegime: undefined,
+		stickyTerminalRows: undefined,
+		stickyReserve: undefined,
+	};
+
 	constructor(options: GoalWidgetOptions) {
 		this.theme = options.theme;
 		this.tui = options.tui;
@@ -358,10 +453,92 @@ export class GoalWidgetComponent implements Component {
 		// pattern as the questionnaire churn guard; mock TUIs without a
 		// `terminal` render unbounded.
 		const terminalRows = (this.tui as unknown as { terminal?: { rows?: number } }).terminal?.rows;
+		// Render the current branch unbounded (natural), then apply the
+		// stable-height bound (spec 2026-08-11): the rendered height latches at
+		// the first render of each regime and stays constant (fits and capped),
+		// so the dock height / buffer line count stop changing and the
+		// terminal stops jumping to the bottom.
+		const natural = this.renderNatural(width);
+		const regime = this.stableHeightRegime();
+		// Reserve adapted to the actual dock chrome (status + editor + footer +
+		// pending): the widget's block plus the chrome must never exceed the
+		// terminal, or the chat's appended lines and the status line land above
+		// pi-tui's viewport top and every agent write wipes the scrollback.
+		const reserve = this.measureDockReserve(width) ?? WIDGET_HEIGHT_RESERVE;
+		return applyStableHeightBound(natural, terminalRows, this.stableHeightState, regime, reserve);
+	}
+
+	/**
+	 * Measure the rendered height of the dock chrome around the widget
+	 * (pending + status + editor + widgetBelow + footer) at the current width,
+	 * so the widget can size itself so its block plus the chrome never exceeds
+	 * the terminal (spec 2026-08-11): pi-tui full-renders (2J+3J, scrollback
+	 * wipe) whenever the first changed line is above its tracked viewport top
+	 * (`previousBufferLength − terminalRows`); when the widget's block pushes
+	 * the chat's append point and the status line above that, every agent
+	 * write wipes the terminal scrollback and the user is forced to the
+	 * bottom. Returns undefined (→ the static WIDGET_HEIGHT_RESERVE fallback)
+	 * when the TUI exposes no measurable dock (mock TUIs, headless).
+	 */
+	private measureDockReserve(width: number): number | undefined {
+		type DockChild = { children?: DockChild[]; render?: (w: number) => string[] };
+		const tui = this.tui as unknown as { children?: DockChild[] };
+		const top = tui.children;
+		if (!Array.isArray(top) || top.length < 2) return undefined;
+		// Locate the dock list and the widget's own container:
+		// regular mode — top-level [document, pending, status, widgetAbove,
+		//   editor, widgetBelow, footer] with the widget directly inside
+		//   widgetContainerAbove;
+		// fullscreen mode — top-level [transcript, dock] with the widget
+		//   inside widgetContainerAbove inside the dock VStack.
+		let dockList: typeof top | undefined;
+		let widgetContainer: (typeof top)[number] | undefined;
+		for (const c of top) {
+			const kids = Array.isArray(c.children) ? c.children : undefined;
+			if (kids?.includes(this)) {
+				dockList = top;
+				widgetContainer = c;
+				break;
+			}
+			const nested = kids?.find((cc) => Array.isArray(cc.children) && cc.children!.includes(this)) as (typeof top)[number] | undefined;
+			if (nested) {
+				dockList = kids!;
+				widgetContainer = nested;
+				break;
+			}
+		}
+		if (!dockList || !widgetContainer) return undefined;
+		let total = 0;
+		for (let i = 0; i < dockList.length; i++) {
+			const c = dockList[i]!;
+			// Skip the document container / transcript (its height cancels out
+			// of the viewport math: it sits above both the chat's append point
+			// and the viewport top) and the widget's own container.
+			if (dockList === top && i === 0) continue;
+			if (c === widgetContainer) continue;
+			if (typeof c?.render !== "function") continue;
+			try {
+				const lines = c.render(width);
+				if (Array.isArray(lines)) total += lines.length;
+			} catch {
+				// A sibling render failure must never break the widget; fall
+				// back to the static reserve.
+				return undefined;
+			}
+		}
+		// +1 slack so the strictest safety condition (chat append point below
+		// the viewport top) holds even at the boundary.
+		return total + 1;
+	}
+
+	/** The current widget branch rendered unbounded (no terminal-height bound). */
+	private renderNatural(width: number): string[] {
+		const settings = this.getSettings();
+		const safeWidth = Math.max(1, width);
 		// §15.4: a finished audit shows its result card until cleared.
 		const auditResult = this.getAuditResult();
 		if (auditResult) {
-			return boundWidgetRenderLines(clampLinesToWidth(renderAuditResultCardView(auditResult, this.theme, width), width), terminalRows);
+			return clampLinesToWidth(renderAuditResultCardView(auditResult, this.theme, width), width);
 		}
 		const goal = this.getGoal();
 		const otherCount = Math.max(0, this.getOpenGoalCount() - 1);
@@ -372,7 +549,7 @@ export class GoalWidgetComponent implements Component {
 			tasksDisabled: settings.disableTasks === true,
 		}) : null;
 		this.maybeReanchor(model);
-		let lines = renderGoalWidgetLines(this.getGoal(), this.theme, width, {
+		const lines = renderGoalWidgetLines(this.getGoal(), this.theme, safeWidth, {
 			openGoalCount: this.getOpenGoalCount(),
 			auditorProgress: this.getAuditorProgress(),
 			disableTasks: settings.disableTasks,
@@ -385,12 +562,32 @@ export class GoalWidgetComponent implements Component {
 			expandedScrollOffset: this.expandedScrollOffset,
 			expandedTaskRows: expandedTaskViewportRows(this.lastRenderWidth),
 			keybindings: settings.keybindings?.dashboard,
-			terminalRows,
 		});
 		if (this.getDebugMode()) {
 			lines.push(...this.renderDebugPanel(width));
 		}
-		return boundWidgetRenderLines(clampLinesToWidth(lines, width), terminalRows);
+		return clampLinesToWidth(lines, width);
+	}
+
+	/**
+	 * Stable-height regime key: the latch belongs to one goal, goal status,
+	 * widget state kind (focused / audit / result / unfocused / none),
+	 * expansion mode, debug mode, task setting, and task presence — a change
+	 * clears the latch so the new mode starts from its own natural height.
+	 * Task presence re-latches a structurally empty goal (0 tasks → tiny
+	 * dashboard) when its first task appears — a rare structural jump, not
+	 * steady-state churn.
+	 */
+	private stableHeightRegime(): string {
+		const settings = this.getSettings();
+		const goal = this.getGoal();
+		let stateKind: string;
+		if (this.getAuditResult()) stateKind = "result";
+		else if (this.getAuditorProgress()) stateKind = "audit";
+		else if (goal) stateKind = "focused";
+		else stateKind = this.getOpenGoalCount() > 0 ? "unfocused" : "none";
+		const hasTasks = (goal?.taskList?.tasks?.length ?? 0) > 0;
+		return [goal?.id ?? "∅", goal?.status ?? "∅", stateKind, String(this.getExpanded()), String(this.getDebugMode()), String(settings.disableTasks === true), String(hasTasks)].join("|");
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "Goal mode extension for pi: durable long-running objectives, five model tools, structured tasks, independent completion audit, Sisyphus mode, auto-continue, and a status overlay.",
   "license": "MIT",
   "author": "pi-goal-x contributors",
@@ -66,6 +66,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
     "@eslint/js": "^9.39.5",
+    "@xterm/headless": "^6.0.0",
     "eslint": "^9.39.5",
     "globals": "^15.15.0",
     "typebox": "^1.3.11",