pi-goal-x 0.27.3 → 0.27.4

package/extensions/widgets/goal-widget.ts

@@ -161,9 +161,9 @@ export const WIDGET_HEIGHT_RESERVE = 6;
  * 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 sticky-cap bound
+ * component additionally applies the stable-height bound
  * (spec 2026-08-11-stable-widget-height) so the rendered height stays
- * constant once the widget reaches the cap — see applyStableHeightBound.
+ * constant within each regime — see applyStableHeightBound.
  */
 export function boundWidgetRenderLines(lines: string[], terminalRows: number | undefined): string[] {
 	if (!terminalRows || terminalRows <= 0) return lines;
@@ -173,26 +173,26 @@ export function boundWidgetRenderLines(lines: string[], terminalRows: number | u
 }
 
 /**
- * Sticky-cap rendered height (spec 2026-08-11-stable-widget-height).
+ * 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). When the
- * widget is taller than the 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 sticky cap makes the rendered height invariant to goal-state
- * changes while the widget is at the cap:
+ * 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):
  *
- * - once natural > cap in the current regime, render exactly `cap` lines on
- *   every later render of that regime (head slice when natural > cap, blank
- *   padding when natural dips below — the height never changes);
+ * - 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;
- *   once it fits, everything renders (the fits case stays byte-identical);
+ *   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) clears the latch so the new mode starts from
- *   its own natural height.
+ *   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
@@ -201,28 +201,43 @@ export function boundWidgetRenderLines(lines: string[], terminalRows: number | u
 export function applyStableHeightBound(
 	lines: string[],
 	terminalRows: number | undefined,
-	state: { stickyCap: number | undefined; stickyRegime: string | undefined; stickyTerminalRows: 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 - WIDGET_HEIGHT_RESERVE);
+	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 (lines.length > cap) {
-		// At the cap: latch the rendered height and head-slice (the dashboard's
-		// content priority is top-down).
-		state.stickyCap = cap;
-		return lines.slice(0, cap);
+	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 (state.stickyCap !== undefined && lines.length < 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).
@@ -230,7 +245,7 @@ export function applyStableHeightBound(
 		while (padded.length < state.stickyCap) padded.push("");
 		return padded;
 	}
-	// Fits case (natural ≤ cap, no latch): byte-identical to today.
+	// Exactly the committed height: unchanged.
 	return lines;
 }
 
@@ -340,14 +355,17 @@ export class GoalWidgetComponent implements Component {
 	private lastSeenGoalId: string | undefined;
 	private lastSeenLatestCompletedAt: string | undefined;
 
-	// Sticky-cap latch (spec 2026-08-11-stable-widget-height): once the widget
-	// reaches the terminal cap in a regime, its rendered height stays constant
-	// (cap lines) until the regime or the terminal size 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 } = {
+	// 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) {
@@ -436,12 +454,81 @@ export class GoalWidgetComponent implements Component {
 		// `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 is constant
-		// while the widget is at the cap, so the dock height / buffer line count
-		// stop changing and the terminal stops jumping to the bottom.
+		// 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();
-		return applyStableHeightBound(natural, terminalRows, this.stableHeightState, regime);
+		// 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). */
@@ -483,10 +570,13 @@ export class GoalWidgetComponent implements Component {
 	}
 
 	/**
-	 * Sticky-cap regime key: the latch belongs to one goal, goal status,
+	 * Stable-height regime key: the latch belongs to one goal, goal status,
 	 * widget state kind (focused / audit / result / unfocused / none),
-	 * expansion mode, debug mode, and task setting — a change clears the latch
-	 * so the new mode starts from its own natural height.
+	 * 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();
@@ -496,7 +586,8 @@ export class GoalWidgetComponent implements Component {
 		else if (this.getAuditorProgress()) stateKind = "audit";
 		else if (goal) stateKind = "focused";
 		else stateKind = this.getOpenGoalCount() > 0 ? "unfocused" : "none";
-		return [goal?.id ?? "∅", goal?.status ?? "∅", stateKind, String(this.getExpanded()), String(this.getDebugMode()), String(settings.disableTasks === true)].join("|");
+		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.3",
+  "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",