pi-goal-x 0.27.0 → 0.27.2

package/README.md

@@ -376,6 +376,22 @@ Settings are stored in:
 
 Use `/goal-settings` to configure task lists, verification contracts, subtask depth, automatic goal selection, and completion auditing. Goal objectives have no hard length limit by default; set `objectiveMaxChars` (or `PI_GOAL_OBJECTIVE_MAX_CHARS`, `0` = no limit) to cap objective length across `create_goal`, `propose_goal_draft`, and `/goal-tweak`.
 
+Configure the task shortcuts in the same file when the terminal captures the defaults:
+
+```json
+{
+  "keybindings": {
+    "dashboard": {
+      "toggleExpand": "ctrl+shift+t",
+      "scrollUp": "ctrl+shift+up",
+      "scrollDown": "ctrl+shift+down"
+    }
+  }
+}
+```
+
+The default task bindings are `ctrl+shift+t`, `ctrl+shift+up`, and `ctrl+shift+down`. Use pi key names such as `ctrl+shift+up`.
+
 ## License
 
 MIT

package/docs/unified-dashboard.md

@@ -227,6 +227,11 @@ auditor's findings, and returns to the normal dashboard so work can continue.
 | `Esc` | Collapse the expanded dashboard; otherwise pause the goal |
 | `Esc` (during audit) | Stop the audit and choose to continue working or complete without audit |
 
+Configure the three task shortcuts with `keybindings.dashboard.toggleExpand`,
+`keybindings.dashboard.scrollUp`, and `keybindings.dashboard.scrollDown` in
+`.pi/pi-goal-x-settings.json`. The defaults are `ctrl+shift+t`,
+`ctrl+shift+up`, and `ctrl+shift+down`.
+
 ## Width behavior
 
 Layout modes (§5.5):

package/extensions/goal-commands.ts

@@ -382,7 +382,9 @@ export function registerGoalCommands(core: GoalCore): void {
 		if (key === "subtaskDepth") return config.subtaskDepth !== undefined ? String(config.subtaskDepth) : "1";
 		if (key === "stallTimeoutMinutes") return config.stallTimeoutMinutes !== undefined ? String(config.stallTimeoutMinutes) : "0";
 		if (key === "objectiveMaxChars") return config.objectiveMaxChars !== undefined ? String(config.objectiveMaxChars) : "0";
-		return config[key] ?? "(default)";
+		if (key === "keybindings") return config.keybindings ? `${config.keybindings.dashboard.toggleExpand}, ${config.keybindings.dashboard.scrollUp}, ${config.keybindings.dashboard.scrollDown}` : "(default)";
+		const value = config[key];
+		return typeof value === "string" ? value : "(default)";
 	}
 
 	function settingsLines(config: GoalSettings): string[] {

package/extensions/goal-questionnaire.ts

@@ -344,12 +344,18 @@ export async function runGoalQuestionnaire(ctx: ExtensionContext, rawQuestions:
 		let optionIndex = 0;
 		let inputMode = false;
 		let inputQuestionId: string | null = null;
+		// Focusable container state: the TUI sets `focused` when the dialog has
+		// focus; we propagate it to the embedded Editor while in input mode so
+		// the editor emits CURSOR_MARKER and the hardware cursor is positioned
+		// for IME input (pi docs/tui.md — Focusable Interface).
+		let dialogFocused = false;
 		let cachedLines: string[] | undefined;
 		let optionsStartIndex = -1;
 		// §options-scroll viewport state (select-mode + submit tabs only).
 		let scrollTop = 0;
 		let needsFollow = false;
 		let optionRanges: Array<[number, number]> = [];
+		let questionBlockEnd = -1;
 		let auditorEnabled = auditorToggleInit?.defaultEnabled ?? true;
 		const answers = new Map<string, GoalQuestionnaireAnswer>();
 		const drafts = new Map<string, string>();
@@ -406,6 +412,9 @@ export async function runGoalQuestionnaire(ctx: ExtensionContext, rawQuestions:
 				inputMode = true;
 				inputQuestionId = q.id;
 				editor.setText(draft ?? (existing?.wasCustom ? existing.answer : ""));
+				// Anchor the editor while the dialog has focus (see enterInputMode).
+				editor.focused = dialogFocused;
+				tui.setShowHardwareCursor(dialogFocused);
 			} else if (existing?.wasCustom) {
 				optionIndex = q.options.length;
 			} else if (existing && !existing.wasCustom) {
@@ -441,6 +450,89 @@ function advanceAfterAnswer() {
 			answers.set(qId, { id: qId, question: q?.question ?? qId, answer: value, wasCustom });
 		}
 
+		/**
+		 * Activate the answer editor for a question: position the hardware
+		 * cursor and mark the Editor focused (emits CURSOR_MARKER for IME).
+		 */
+		/**
+	 * §options-first fit: every option line always stays in frame. When the
+	 * question + context + options exceed the bound, the question/context
+	 * section yields first (it remains in the agent transcript): middle lines
+	 * (blanks, auditor, "Current:", context) drop before the question block
+	 * and the footer hint, and the tail slack (blank/footer) gives way before
+	 * the question. Returns null when even the option block + borders cannot
+	 * fit (pathological) so the caller falls back to the scroll viewport.
+	 */
+	function fitOptionsInFrame(
+		lines: string[],
+		maxDialogLines: number,
+		questionBlockEnd: number,
+		optionsStart: number,
+		lastOptionLine: number,
+	): string[] | null {
+		if (maxDialogLines <= 0 || lines.length <= maxDialogLines) return lines;
+		if (optionsStart < 0 || lastOptionLine < optionsStart) return null;
+		const head = lines.slice(0, Math.max(questionBlockEnd, 1));
+		const middle = lines.slice(Math.max(questionBlockEnd, 1), optionsStart);
+		const tail = lines.slice(optionsStart);
+		const optionsBlockLen = lastOptionLine - optionsStart + 1;
+		// The option block + bottom border must fit on their own; otherwise the
+		// scroll viewport is the last resort (nothing is ever hidden).
+		if (optionsBlockLen + 1 > maxDialogLines) return null;
+		// Shrink the middle from its end: blanks first, then auditor/Current/
+		// context lines — the question block is untouched.
+		const mid = middle.slice();
+		while (head.length + mid.length + tail.length > maxDialogLines && mid.length > 0) {
+			let blankIdx = -1;
+			for (let i = mid.length - 1; i >= 0; i--) {
+				if (mid[i]!.trim() === "") { blankIdx = i; break; }
+			}
+			if (blankIdx >= 0) mid.splice(blankIdx, 1);
+			else mid.pop();
+		}
+		// Still over: the tail gives its slack (blank between options and
+		// footer, then the footer hint) before the question block does. Never
+		// drop the option block or the bottom border.
+		const tailKept = tail.slice();
+		while (head.length + mid.length + tailKept.length > maxDialogLines && tailKept.length > optionsBlockLen + 1) {
+			// Prefer removing a blank line (never the options or the border),
+			// then the line just above the bottom border (the footer hint).
+			let tailBlank = -1;
+			for (let i = tailKept.length - 2; i >= 1; i--) {
+				if (tailKept[i]!.trim() === "") { tailBlank = i; break; }
+			}
+			if (tailBlank >= 1) tailKept.splice(tailBlank, 1);
+			else tailKept.splice(tailKept.length - 2, 1);
+		}
+		// Still over: give the question block's trailing wrap lines (then the
+		// question itself) before giving up — options + borders always stay.
+		const headKept = head.slice();
+		while (head.length + mid.length + tailKept.length > maxDialogLines && headKept.length > 1) {
+			headKept.pop();
+		}
+		if (headKept.length + mid.length + tailKept.length > maxDialogLines) return null;
+		return [...headKept, ...mid, ...tailKept];
+	}
+
+	function enterInputMode(qId: string) {
+			inputMode = true;
+			inputQuestionId = qId;
+			const draft = drafts.get(qId);
+			const existing = answers.get(qId);
+			editor.setText(draft ?? (existing?.wasCustom ? existing.answer : ""));
+			editor.focused = dialogFocused;
+			tui.setShowHardwareCursor(dialogFocused);
+		}
+
+		/** Deactivate the answer editor: release the cursor and clear the editor. */
+		function leaveInputMode() {
+			inputMode = false;
+			inputQuestionId = null;
+			editor.focused = false;
+			tui.setShowHardwareCursor(false);
+			editor.setText("");
+		}
+
 		editor.onSubmit = (value) => {
 			if (!inputQuestionId) return;
 			const trimmed = value.trim();
@@ -450,9 +542,7 @@ function advanceAfterAnswer() {
 			}
 			drafts.delete(inputQuestionId);
 			saveAnswer(inputQuestionId, trimmed, true);
-			inputMode = false;
-			inputQuestionId = null;
-			editor.setText("");
+			leaveInputMode();
 			advanceAfterAnswer();
 		};
 
@@ -462,9 +552,7 @@ function advanceAfterAnswer() {
 				if (text.trim()) drafts.set(inputQuestionId, text);
 				else drafts.delete(inputQuestionId);
 			}
-			inputMode = false;
-			inputQuestionId = null;
-			editor.setText("");
+			leaveInputMode();
 		}
 
 		enterQuestion(questions[0]!);
@@ -573,11 +661,7 @@ function advanceAfterAnswer() {
 
 			if (matchesKey(data, Key.enter) && q) {
 				if (q.options.length === 0 || opts[optionIndex]?.isCustom) {
-					inputMode = true;
-					inputQuestionId = q.id;
-					const draft = drafts.get(q.id);
-					const existing = answers.get(q.id);
-					editor.setText(draft ?? (existing?.wasCustom ? existing.answer : ""));
+					enterInputMode(q.id);
 					refresh();
 					return;
 				}
@@ -768,6 +852,7 @@ function advanceAfterAnswer() {
 				add(allAnswered() ? theme.fg("success", " Press Enter to submit") : theme.fg("warning", ` Unanswered: ${questions.filter((qq) => !answers.has(qq.id)).map((qq) => qq.id).join(", ")}`));
 			} else if (q) {
 				addWrapped(theme.fg("text", ` ${q.question}`));
+				questionBlockEnd = lines.length;
 				protectedCount = lines.length;
 				if (q.context) renderContextLines(q.context);
 				// Auditor toggle line between context and options
@@ -811,24 +896,55 @@ function advanceAfterAnswer() {
 				const proposalSegments = !inputMode && currentTab !== questions.length && !!q && q.context
 					? findProposalPresentationSegments(lines, optionsStartIndex)
 					: null;
-				// §options-scroll: select-mode question tabs and the submit summary
-				// are a viewport over the full content (never truncated); input
-				// mode keeps the legacy tail-keep so the editor stays the priority.
-				let scrollState: DialogScrollState | null = null;
-				if (!inputMode) {
-					scrollState = { scrollTop, needsFollow, optionRanges, followIndex: optionIndex };
-				}
-				lines = fitDialogLines(lines, maxDialogLines, protectedCount, proposalSegments, scrollState, (s) => theme.fg("dim", s));
-				if (scrollState) {
-					scrollTop = scrollState.scrollTop;
-					needsFollow = scrollState.needsFollow;
+				if (proposalSegments) {
+					// Proposal confirmations keep their segment protection (tasks +
+					// auditor + options within the bound; the objective-box middle
+					// stays in the scrollback presentation).
+					lines = fitDialogLines(lines, maxDialogLines, protectedCount, proposalSegments);
+				} else if (!inputMode && currentTab !== questions.length && questionBlockEnd >= 0) {
+					// Plain select-mode question tab: all options in frame;
+					// question/context yields first (it stays in the transcript).
+					const fitted = fitOptionsInFrame(lines, maxDialogLines, questionBlockEnd, optionsStartIndex, optionRanges[optionRanges.length - 1]?.[1] ?? -1);
+					if (fitted) {
+						lines = fitted;
+						scrollTop = 0;
+						needsFollow = false;
+					} else {
+						// Pathological: options alone overflow the bound — scroll
+						// viewport is the last resort (nothing ever hidden).
+						const scrollState = { scrollTop, needsFollow, optionRanges, followIndex: optionIndex };
+						lines = fitDialogLines(lines, maxDialogLines, protectedCount, null, scrollState, (s) => theme.fg("dim", s));
+						scrollTop = scrollState.scrollTop;
+						needsFollow = scrollState.needsFollow;
+					}
+				} else {
+					// Input mode, submit tab: legacy tail-keep / viewport behavior.
+					const scrollState = !inputMode ? { scrollTop, needsFollow, optionRanges, followIndex: optionIndex } : null;
+					lines = fitDialogLines(lines, maxDialogLines, protectedCount, null, scrollState, (s) => theme.fg("dim", s));
+					if (scrollState) {
+						scrollTop = scrollState.scrollTop;
+						needsFollow = scrollState.needsFollow;
+					}
 				}
 			}
 			cachedLines = lines;
 			return lines;
 		}
 
-		return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+		return {
+			render,
+			invalidate: () => { cachedLines = undefined; },
+			handleInput,
+			// Focusable (pi docs/tui.md): propagate focus to the embedded Editor
+			// so it emits CURSOR_MARKER and the hardware cursor is positioned
+			// correctly for IME input while the answer editor is active.
+			get focused(): boolean { return dialogFocused; },
+			set focused(v: boolean) {
+				dialogFocused = v;
+				editor.focused = v && inputMode;
+				tui.setShowHardwareCursor(v && inputMode);
+			},
+		};
 	});
 }
 

package/extensions/goal-settings.ts

@@ -9,16 +9,56 @@
  *
  * The file may contain:
  *   disableTasks, disableContracts, subtaskDepth,
- *   provider, model, thinkingLevel, disabled, objectiveMaxChars
+ *   provider, model, thinkingLevel, disabled, objectiveMaxChars, keybindings
+ *
+ * `keybindings.dashboard` accepts `toggleExpand`, `scrollUp`, and `scrollDown`.
  *
  * additionalProperties: false — unknown keys are rejected.
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { KeyId } from "@earendil-works/pi-tui";
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
+export interface GoalDashboardKeybindings {
+	toggleExpand: KeyId;
+	scrollUp: KeyId;
+	scrollDown: KeyId;
+}
+
+export interface GoalKeybindings {
+	dashboard: GoalDashboardKeybindings;
+}
+
+export const DEFAULT_GOAL_KEYBINDINGS: GoalKeybindings = {
+	dashboard: {
+		toggleExpand: "ctrl+shift+t",
+		scrollUp: "ctrl+shift+up",
+		scrollDown: "ctrl+shift+down",
+	},
+};
+
+export function formatGoalKeybinding(key: string): string {
+	return key.split("+").map((part) => ({
+		ctrl: "Ctrl",
+		control: "Ctrl",
+		shift: "Shift",
+		alt: "Alt",
+		up: "↑",
+		down: "↓",
+		left: "←",
+		right: "→",
+		pageup: "PageUp",
+		pagedown: "PageDown",
+		home: "Home",
+		end: "End",
+		enter: "Enter",
+		escape: "Esc",
+	}[part.toLowerCase()] ?? part.toUpperCase())).join("+");
+}
+
 export interface GoalSettings {
 	disableTasks?: boolean;
 	disableContracts?: boolean;
@@ -38,6 +78,8 @@ export interface GoalSettings {
 	 * /goal-tweak).
 	 */
 	objectiveMaxChars?: number;
+	/** Keyboard shortcuts for the compact task list and dashboard expansion. */
+	keybindings?: GoalKeybindings;
 }
 
 export const PI_GOAL_SETTINGS_FILE_ENV = "PI_GOAL_SETTINGS_FILE";
@@ -84,8 +126,12 @@ const ALLOWED_SETTINGS_KEYS = new Set([
 	"auditorProjectResources",
 	"stallTimeoutMinutes",
 	"objectiveMaxChars",
+	"keybindings",
 ]);
 
+const ALLOWED_KEYBINDING_KEYS = new Set(["dashboard"]);
+const ALLOWED_DASHBOARD_KEYBINDING_KEYS = new Set(["toggleExpand", "scrollUp", "scrollDown"]);
+
 /**
  * Resolve the path to the unified settings file.
  * Uses `PI_GOAL_SETTINGS_FILE` env var if set (relative to cwd or absolute).
@@ -128,6 +174,31 @@ function asNonNegativeInt(value: unknown): number | undefined {
 	return undefined;
 }
 
+function asKeybinding(value: unknown): KeyId | undefined {
+	const key = asNonEmptyString(value);
+	if (!key) return undefined;
+	return key as KeyId;
+}
+
+function parseKeybindings(value: unknown): GoalKeybindings | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const unknownKeys = Object.keys(record).filter((key) => !ALLOWED_KEYBINDING_KEYS.has(key));
+	if (unknownKeys.length > 0) throw new Error(`Unknown keybindings key(s): ${unknownKeys.join(", ")}`);
+	const dashboard = record.dashboard;
+	if (!dashboard || typeof dashboard !== "object" || Array.isArray(dashboard)) return undefined;
+	const dashboardRecord = dashboard as Record<string, unknown>;
+	const unknownDashboardKeys = Object.keys(dashboardRecord).filter((key) => !ALLOWED_DASHBOARD_KEYBINDING_KEYS.has(key));
+	if (unknownDashboardKeys.length > 0) throw new Error(`Unknown dashboard keybinding(s): ${unknownDashboardKeys.join(", ")}`);
+	return {
+		dashboard: {
+			toggleExpand: asKeybinding(dashboardRecord.toggleExpand) ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.toggleExpand,
+			scrollUp: asKeybinding(dashboardRecord.scrollUp) ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollUp,
+			scrollDown: asKeybinding(dashboardRecord.scrollDown) ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollDown,
+		},
+	};
+}
+
 function asThinkingLevel(value: unknown): ThinkingLevel | undefined {
 	const text = asNonEmptyString(value);
 	return text && THINKING_LEVELS.has(text) ? text as ThinkingLevel : undefined;
@@ -164,6 +235,8 @@ export function parseGoalSettings(raw: unknown): GoalSettings {
 	if (stallTimeoutMinutes !== undefined) settings.stallTimeoutMinutes = stallTimeoutMinutes;
 	const objectiveMaxChars = asNonNegativeInt(record.objectiveMaxChars);
 	if (objectiveMaxChars !== undefined) settings.objectiveMaxChars = objectiveMaxChars;
+	const keybindings = parseKeybindings(record.keybindings);
+	if (keybindings) settings.keybindings = keybindings;
 	return settings;
 }
 
@@ -207,6 +280,7 @@ export function loadGoalSettings(cwd: string, env: NodeJS.ProcessEnv = process.e
 		auditorProjectResources: fileConfig.auditorProjectResources ?? false,
 		stallTimeoutMinutes: fileConfig.stallTimeoutMinutes,
 		objectiveMaxChars: asNonNegativeInt(env.PI_GOAL_OBJECTIVE_MAX_CHARS) ?? fileConfig.objectiveMaxChars,
+		keybindings: fileConfig.keybindings ?? DEFAULT_GOAL_KEYBINDINGS,
 	};
 }
 
@@ -250,6 +324,7 @@ export function effectiveSettingsReport(cwd: string, env: NodeJS.ProcessEnv = pr
 		{ key: "auditorProjectResources", label: "auditor project resources", format: (v) => (v.auditorProjectResources === true ? "true" : "false") },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", format: (v) => String(v.stallTimeoutMinutes ?? 0) },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", format: (v) => String(v.objectiveMaxChars ?? 0) },
+		{ key: "keybindings", label: "dashboard keybindings", format: (v) => `${v.keybindings?.dashboard.toggleExpand ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.toggleExpand}, ${v.keybindings?.dashboard.scrollUp ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollUp}, ${v.keybindings?.dashboard.scrollDown ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollDown}` },
 	];
 	for (const row of rows) {
 		const envVar = envOverrideFor(row.key, env);
@@ -286,6 +361,7 @@ export function saveGoalSettingsFileConfig(cwd: string, settings: GoalSettings):
 	if (settings.auditorProjectResources === true) clean.auditorProjectResources = true;
 	if (settings.stallTimeoutMinutes !== undefined) clean.stallTimeoutMinutes = settings.stallTimeoutMinutes;
 	if (settings.objectiveMaxChars !== undefined) clean.objectiveMaxChars = settings.objectiveMaxChars;
+	if (settings.keybindings) clean.keybindings = parseKeybindings(settings.keybindings);
 	const configPath = goalSettingsPath(cwd);
 	fs.mkdirSync(path.dirname(configPath), { recursive: true });
 	settingsFileCache.delete(configPath);
@@ -301,6 +377,7 @@ export function saveGoalSettingsFileConfig(cwd: string, settings: GoalSettings):
 	if (settings.auditorProjectResources === true) persisted.auditorProjectResources = true;
 	if (clean.stallTimeoutMinutes !== undefined) persisted.stallTimeoutMinutes = clean.stallTimeoutMinutes;
 	if (clean.objectiveMaxChars !== undefined) persisted.objectiveMaxChars = clean.objectiveMaxChars;
+	if (clean.keybindings) persisted.keybindings = clean.keybindings;
 	fs.writeFileSync(configPath, `${JSON.stringify(persisted, null, 2)}\n`, "utf8");
 	return clean;
 }

package/extensions/goal-widget.ts

@@ -2,7 +2,7 @@ import { matchesKey } from "@earendil-works/pi-tui";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { cloneGoal, createGoal, nowIso, type GoalTask } from "./goal-record.ts";
 import { checkSubtasksComplete, findTaskInTree } from "./goal-policy.ts";
-import { loadGoalSettings } from "./goal-settings.ts";
+import { DEFAULT_GOAL_KEYBINDINGS, loadGoalSettings } from "./goal-settings.ts";
 import { serializeGoalFile } from "./storage/goal-files.ts";
 import type { AuditorWidgetProgress } from "./widgets/goal-widget.ts";
 import type { GoalCore } from "./goal-state.ts";
@@ -111,6 +111,8 @@ export async function toggleTaskViaService(core: GoalCore, ctx: ExtensionContext
 export function syncTerminalInputPause(core: GoalCore, ctx: ExtensionContext): void {
 		if (!ctx.hasUI) return;
 		core.terminalInputUnsubscribe?.();
+		const settings = loadGoalSettings(typeof ctx.cwd === "string" ? ctx.cwd : process.cwd());
+		const keybindings = settings.keybindings?.dashboard ?? DEFAULT_GOAL_KEYBINDINGS.dashboard;
 		core.terminalInputUnsubscribe = ctx.ui.onTerminalInput((data) => {
 			// If an audit is running, Escape aborts the audit instead of pausing.
 			// Must return { consume: true } so the TUI doesn't also process the key
@@ -157,7 +159,7 @@ export function syncTerminalInputPause(core: GoalCore, ctx: ExtensionContext): v
 			// Ctrl+Shift+T — toggle the unified dashboard between compact and
 			// expanded task views (the task-list overlay is merged into the
 			// dashboard; §10).
-			if (matchesKey(data, "ctrl+shift+t")) {
+			if (matchesKey(data, keybindings.toggleExpand)) {
 				core.toggleDashboardExpanded();
 				return { consume: true };
 			}
@@ -182,8 +184,8 @@ export function syncTerminalInputPause(core: GoalCore, ctx: ExtensionContext): v
 					return { consume: true };
 				}
 			}
-			if (matchesKey(data, "ctrl+shift+up") || matchesKey(data, "ctrl+shift+down") || matchesKey(data, "ctrl+shift+pageUp") || matchesKey(data, "ctrl+shift+pageDown") || matchesKey(data, "ctrl+shift+home") || matchesKey(data, "ctrl+shift+end")) {
-				const key = matchesKey(data, "ctrl+shift+up") ? "up" : matchesKey(data, "ctrl+shift+down") ? "down" : matchesKey(data, "ctrl+shift+pageUp") ? "pageUp" : matchesKey(data, "ctrl+shift+pageDown") ? "pageDown" : matchesKey(data, "ctrl+shift+home") ? "home" : "end";
+			if (matchesKey(data, keybindings.scrollUp) || matchesKey(data, keybindings.scrollDown) || matchesKey(data, "ctrl+shift+pageUp") || matchesKey(data, "ctrl+shift+pageDown") || matchesKey(data, "ctrl+shift+home") || matchesKey(data, "ctrl+shift+end")) {
+				const key = matchesKey(data, keybindings.scrollUp) ? "up" : matchesKey(data, keybindings.scrollDown) ? "down" : matchesKey(data, "ctrl+shift+pageUp") ? "pageUp" : matchesKey(data, "ctrl+shift+pageDown") ? "pageDown" : matchesKey(data, "ctrl+shift+home") ? "home" : "end";
 				if (core.goalWidgetComponentRef?.current?.handleCompactScrollKey(key)) {
 					return { consume: true };
 				}

package/extensions/widgets/goal-dashboard-renderer.ts

@@ -26,6 +26,7 @@ import {
 } from "./goal-dashboard-model.ts";
 import type { GoalActivityItem } from "../goal-activity.ts";
 import { truncateText } from "../goal-core.ts";
+import { DEFAULT_GOAL_KEYBINDINGS, formatGoalKeybinding, type GoalDashboardKeybindings } from "../goal-settings.ts";
 
 // mdLink is deliberately excluded: the chrome must stay neutral gray, not
 // blue-tinged ("more grey than blue").
@@ -291,7 +292,7 @@ export function renderCompactDashboard(
 	model: GoalDashboardModel,
 	theme: Theme,
 	width: number,
-	opts: { footerHint?: string; scrollOffset?: number } = {},
+	opts: { footerHint?: string; scrollOffset?: number; keybindings?: GoalDashboardKeybindings } = {},
 ): string[] {
 	const safeWidth = Math.max(10, width);
 	const mode = layoutMode(safeWidth);
@@ -397,14 +398,22 @@ export function renderCompactDashboard(
 		lines.push(boxLine(theme, safeWidth, `${dim(theme, `File     ${model.filePath}`)}`));
 	}
 
+	const keybindings = opts.keybindings ?? DEFAULT_GOAL_KEYBINDINGS.dashboard;
+	const toggleShortcut = formatGoalKeybinding(keybindings.toggleExpand);
+	const scrollShortcut = `${formatGoalKeybinding(keybindings.scrollUp)}/${formatGoalKeybinding(keybindings.scrollDown)}`;
+	const usesDefaultScrollKeys = keybindings.scrollUp === DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollUp && keybindings.scrollDown === DEFAULT_GOAL_KEYBINDINGS.dashboard.scrollDown;
+	const scrollHint = usesDefaultScrollKeys
+		? mode === "minimal" ? "↑↓" : "Ctrl+Shift+↑↓"
+		: scrollShortcut;
+	const expandHint = mode === "wide" || mode === "medium"
+		? `${toggleShortcut}: expand tasks`
+		: `${toggleShortcut}: expand`;
 	const footerHint = opts.footerHint
 		?? (listOverflows
-			? mode === "minimal"
-				? "↑↓: scroll"
-				: mode === "narrow"
-					? "Ctrl+Shift+↑↓: scroll"
-					: "Ctrl+Shift+T: expand · Ctrl+Shift+↑↓: scroll"
-			: spec.footerHint);
+			? mode === "wide" || mode === "medium"
+				? `${toggleShortcut}: expand · ${scrollHint}: scroll`
+				: `${scrollHint}: scroll`
+			: expandHint);
 	// The auditor dot sits at the bottom-right of the border: green when the
 	// focused goal's independent auditor is on, muted gray when off. In
 	// wide/medium a right-aligned note (same frame tone as the hint) explains
@@ -434,7 +443,7 @@ export function renderExpandedDashboard(
 	model: GoalDashboardModel,
 	theme: Theme,
 	width: number,
-	opts: { scrollOffset?: number; rows?: number } = {},
+	opts: { scrollOffset?: number; rows?: number; keybindings?: GoalDashboardKeybindings } = {},
 ): string[] {
 	const safeWidth = Math.max(10, width);
 	const mode = layoutMode(safeWidth);
@@ -497,7 +506,8 @@ export function renderExpandedDashboard(
 		lines.push(...renderActivityBlock(model.recentActivity, theme, safeWidth));
 	}
 
-	lines.push(boxFooter(theme, safeWidth, "Esc/Ctrl+Shift+T: collapse"));
+	const toggleShortcut = formatGoalKeybinding(opts.keybindings?.toggleExpand ?? DEFAULT_GOAL_KEYBINDINGS.dashboard.toggleExpand);
+	lines.push(boxFooter(theme, safeWidth, `Esc/${toggleShortcut}: collapse`));
 	return lines;
 }
 

package/extensions/widgets/goal-widget.ts

@@ -9,7 +9,7 @@ import {
 	type GoalDisplayRecordLike,
 } from "../goal-core.ts";
 import type { GoalRecord, GoalTask, GoalTaskList, TaskStatus } from "../goal-record.ts";
-import type { GoalSettings } from "../goal-settings.ts";
+import type { GoalDashboardKeybindings, GoalSettings } from "../goal-settings.ts";
 import { sisyphusStepProgress } from "../goal-policy.ts";
 import type { GoalLedgerEvent } from "../goal-ledger.ts";
 import {
@@ -134,6 +134,39 @@ 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).
+ */
+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);
+}
+
 function heading(theme: Theme, width: number, left: string, right = ""): string {
 	if (!right) return fit(left, width);
 	const rightPart = ` ${right}`;
@@ -190,18 +223,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 } = {}): 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);
@@ -213,9 +246,9 @@ export function renderGoalWidgetLines(goal: GoalWidgetRecord | null, theme: Them
 	});
 	if (!model) return [];
 	const lines = options.expanded
-		? renderExpandedDashboard(model, theme, safeWidth, { scrollOffset: options.expandedScrollOffset, rows: options.expandedTaskRows })
-		: renderCompactDashboard(model, theme, safeWidth, { scrollOffset: options.compactScrollOffset });
-	return clampLinesToWidth(lines, width);
+		? renderExpandedDashboard(model, theme, safeWidth, { scrollOffset: options.expandedScrollOffset, rows: options.expandedTaskRows, keybindings: options.keybindings })
+		: renderCompactDashboard(model, theme, safeWidth, { scrollOffset: options.compactScrollOffset, keybindings: options.keybindings });
+	return boundWidgetRenderLines(clampLinesToWidth(lines, width), options.terminalRows);
 }
 
 export class GoalWidgetComponent implements Component {
@@ -318,10 +351,17 @@ 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;
 		// §15.4: a finished audit shows its result card until cleared.
 		const auditResult = this.getAuditResult();
 		if (auditResult) {
-			return clampLinesToWidth(renderAuditResultCardView(auditResult, this.theme, width), width);
+			return boundWidgetRenderLines(clampLinesToWidth(renderAuditResultCardView(auditResult, this.theme, width), width), terminalRows);
 		}
 		const goal = this.getGoal();
 		const otherCount = Math.max(0, this.getOpenGoalCount() - 1);
@@ -344,11 +384,13 @@ export class GoalWidgetComponent implements Component {
 			compactScrollOffset: this.compactScrollOffset,
 			expandedScrollOffset: this.expandedScrollOffset,
 			expandedTaskRows: expandedTaskViewportRows(this.lastRenderWidth),
+			keybindings: settings.keybindings?.dashboard,
+			terminalRows,
 		});
 		if (this.getDebugMode()) {
 			lines.push(...this.renderDebugPanel(width));
 		}
-		return clampLinesToWidth(lines, width);
+		return boundWidgetRenderLines(clampLinesToWidth(lines, width), terminalRows);
 	}
 
 	/**

package/package.json

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