pi-goal-x 0.27.1 → 0.27.3

package/extensions/widgets/goal-widget.ts

@@ -134,6 +134,106 @@ function fit(value: string, width: number): string {
 	return visibleWidth(value) > width ? truncateToWidth(value, width, "…") : value;
 }
 
+// ── terminal-height bound (spec 2026-08-10-widget-height-bound-scrollback-fix) ──
+
+/**
+ * Minimum rows reserved below/around the widget so pi's frame stays usable
+ * when the widget is at its cap: status line (1) + editor minimum (3) +
+ * footer (1) + a chat row (1). With the widget capped at
+ * `terminalRows − WIDGET_HEIGHT_RESERVE`, the widget never fills the terminal:
+ * the chat row stays in the frame, the widget's top lines stay within the
+ * viewport (no pi-tui full-render scrollback wipe), and the editor/footer
+ * stay visible — the equal-height scroll-up failure is impossible. Kept at
+ * the minimum that still guarantees the chat row: a larger reserve would
+ * slice dashboards that genuinely fit (e.g. the expanded 24-line dashboard
+ * on a 30-row terminal renders unchanged at 24 + 5 chrome + 1 chat = 30).
+ */
+export const WIDGET_HEIGHT_RESERVE = 6;
+
+/**
+ * Deterministic height guard: cap rendered lines to the terminal height minus
+ * the reserved chrome. Head slice, because the dashboard's content priority
+ * is top-down (identity → status → progress → tasks → details → hints); the
+ * goal identity/status and the interactive task list stay in frame. Pure
+ * index function — stable across renders, so the widget never shrinks on its
+ * 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 sticky-cap bound
+ * (spec 2026-08-11-stable-widget-height) so the rendered height stays
+ * constant once the widget reaches the cap — see applyStableHeightBound.
+ */
+export function boundWidgetRenderLines(lines: string[], terminalRows: number | undefined): string[] {
+	if (!terminalRows || terminalRows <= 0) return lines;
+	const cap = Math.max(1, terminalRows - WIDGET_HEIGHT_RESERVE);
+	if (lines.length <= cap) return lines;
+	return lines.slice(0, cap);
+}
+
+/**
+ * Sticky-cap rendered height (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:
+ *
+ * - 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);
+ * - 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);
+ * - 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.
+ *
+ * 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 },
+	regime: string,
+): string[] {
+	if (!terminalRows || terminalRows <= 0) return lines;
+	const cap = Math.max(1, terminalRows - WIDGET_HEIGHT_RESERVE);
+	if (state.stickyTerminalRows !== terminalRows) {
+		// Terminal resized: adapt to the new height (grow/shrink to fit).
+		state.stickyCap = undefined;
+		state.stickyTerminalRows = terminalRows;
+	}
+	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 && 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;
+	}
+	// Fits case (natural ≤ cap, no latch): byte-identical to today.
+	return lines;
+}
+
 function heading(theme: Theme, width: number, left: string, right = ""): string {
 	if (!right) return fit(left, width);
 	const rightPart = ` ${right}`;
@@ -190,18 +290,18 @@ export function renderAuditResultCardView(
 	return renderAuditResultCard(deriveAuditResultCard(view.verdict, view.report), theme, width);
 }
 
-export function renderGoalWidgetLines(goal: GoalWidgetRecord | null, theme: Theme, width: number, options: { openGoalCount?: number; auditorProgress?: AuditorWidgetProgress | null; disableTasks?: boolean; stalled?: boolean; ledgerEvents?: GoalLedgerEvent[]; expanded?: boolean; debug?: boolean; model?: GoalDashboardModel | null; compactScrollOffset?: number; expandedScrollOffset?: number; expandedTaskRows?: number; keybindings?: GoalDashboardKeybindings } = {}): string[] {
+export function renderGoalWidgetLines(goal: GoalWidgetRecord | null, theme: Theme, width: number, options: { openGoalCount?: number; auditorProgress?: AuditorWidgetProgress | null; disableTasks?: boolean; stalled?: boolean; ledgerEvents?: GoalLedgerEvent[]; expanded?: boolean; debug?: boolean; model?: GoalDashboardModel | null; compactScrollOffset?: number; expandedScrollOffset?: number; expandedTaskRows?: number; keybindings?: GoalDashboardKeybindings; /** Terminal-height bound (see boundWidgetRenderLines); undefined = unbounded. */ terminalRows?: number } = {}): string[] {
 	// When auditor progress is active, show the structured audit dashboard
 	// instead of the normal goal widget (§15.3).
 	if (options.auditorProgress) {
-		return renderAuditorWidgetLines(options.auditorProgress, theme, width, {
+		return boundWidgetRenderLines(renderAuditorWidgetLines(options.auditorProgress, theme, width, {
 			showToolDetails: options.expanded === true || options.debug === true,
-		});
+		}), options.terminalRows);
 	}
 	const openGoalCount = options.openGoalCount ?? 0;
 	if (!goal) {
 		// Unfocused panel when open goals exist; nothing when the pool is empty.
-		return openGoalCount > 0 ? renderUnfocusedDashboard(openGoalCount, theme, width) : [];
+		return boundWidgetRenderLines(openGoalCount > 0 ? renderUnfocusedDashboard(openGoalCount, theme, width) : [], options.terminalRows);
 	}
 	const safeWidth = Math.max(1, width);
 	const otherCount = Math.max(0, openGoalCount - 1);
@@ -215,7 +315,7 @@ export function renderGoalWidgetLines(goal: GoalWidgetRecord | null, theme: Them
 	const lines = options.expanded
 		? renderExpandedDashboard(model, theme, safeWidth, { scrollOffset: options.expandedScrollOffset, rows: options.expandedTaskRows, keybindings: options.keybindings })
 		: renderCompactDashboard(model, theme, safeWidth, { scrollOffset: options.compactScrollOffset, keybindings: options.keybindings });
-	return clampLinesToWidth(lines, width);
+	return boundWidgetRenderLines(clampLinesToWidth(lines, width), options.terminalRows);
 }
 
 export class GoalWidgetComponent implements Component {
@@ -240,6 +340,16 @@ 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 } = {
+		stickyCap: undefined,
+		stickyRegime: undefined,
+		stickyTerminalRows: undefined,
+	};
+
 	constructor(options: GoalWidgetOptions) {
 		this.theme = options.theme;
 		this.tui = options.tui;
@@ -318,6 +428,26 @@ export class GoalWidgetComponent implements Component {
 	render(width: number): string[] {
 		const settings = this.getSettings();
 		this.lastRenderWidth = Math.max(1, width);
+		// Terminal-height bound (spec 2026-08-10): read pi's terminal rows at
+		// render time so the widget never fills the terminal — the chat/editor
+		// stay visible and scrollable and the widget can never trigger pi-tui's
+		// shrink full-render (\x1b[2J\x1b[H\x1b[3J) scrollback wipe. Same cast
+		// 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 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.
+		const natural = this.renderNatural(width);
+		const regime = this.stableHeightRegime();
+		return applyStableHeightBound(natural, terminalRows, this.stableHeightState, regime);
+	}
+
+	/** 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) {
@@ -332,7 +462,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,
@@ -352,6 +482,23 @@ export class GoalWidgetComponent implements Component {
 		return clampLinesToWidth(lines, width);
 	}
 
+	/**
+	 * Sticky-cap 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.
+	 */
+	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";
+		return [goal?.id ?? "∅", goal?.status ?? "∅", stateKind, String(this.getExpanded()), String(this.getDebugMode()), String(settings.disableTasks === true)].join("|");
+	}
+
 	/**
 	 * §9.6 re-anchor rule: when the goal changes or a new task completes (the
 	 * latest completedAt moves), reset both viewports to the anchored defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.27.1",
+  "version": "0.27.3",
   "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",