@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/hosts.md

@@ -43,6 +43,9 @@ TUI produces. Trade-offs inherent to the native primitives:
 - No side-by-side preview pane. Previews are folded into the dialog title instead,
   truncated at 600 characters each.
 - No tab bar and no Submit review tab — one dialog per question, in order.
+- No notes. Both note kinds — per-question `n` on a question tab and global `n` on the
+  Submit tab — are terminal-only; the host's native `select` and `input` primitives carry
+  no note field.
 - Multi-select is a free-text input: type the option numbers, comma-separated
   (`1,3`). Any token that is not a valid option index is treated as a typed custom answer,
   which is how the `Type something.` escape survives. An empty input commits an empty
@@ -64,7 +67,8 @@ Some parts of the dialog exist only under the right conditions:
 | `Type something.` row | Always |
 | Side-by-side preview | An option carries a `preview`, and terminal and pane are both ≥ 100 columns |
 | Preview pane at all | Single-select questions only |
-| Collapse shortcut | `collapseKey` is not `"off"` and the host exposes raw terminal input |
+| Collapse shortcut | `collapseKey` is not `"off"` |
+| Full overlay hide on collapse | The host also exposes raw terminal input (the only path that can reopen a hidden overlay); without it, collapsing shrinks the dialog to a visible one-line row instead |
 | Localized chrome | `@juicesharp/rpiv-i18n` is installed |
 
 ## Loading and startup cost

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/keyboard.md

@@ -13,7 +13,7 @@ adapts to the size of your terminal.
 | `Esc` | Cancel the whole questionnaire. | Everywhere except the notes editor, where it closes notes |
 | `Tab` / `Shift+Tab` | Next / previous tab, wrapping. `→` / `←` do the same. | Multi-question dialogs only |
 | `Space` | Toggle the focused checkbox. | Multi-select questions |
-| `n` | Open the notes editor for the current question. | Every question tab |
+| `n` | Open the notes editor for the focused question — or, on the Submit tab, the global note for the whole questionnaire. | Every question tab; the Submit tab in multi-question dialogs |
 | `Ctrl+G` | Open Pi's configured external editor with the current custom-answer draft. | `Type something.` input |
 | `Ctrl+U` | Clear the current custom-answer draft. | `Type something.` input |
 | `Ctrl+]` | Collapse or expand the dialog. Configurable via `collapseKey`. | Everywhere, including while collapsed |
@@ -62,6 +62,11 @@ side-band keyed by tab index, not inside the answer, so writing a note does not
 question as answered — the Submit tab still lists it as outstanding. The note merges into
 the answer when you confirm it, and reaches the model as `user notes: <text>`.
 
+On the Submit tab, `n` opens the global note editor instead — one note covering the whole
+questionnaire. It lives outside every answer, so it survives tab switches and never marks
+a question as answered; it reaches the model as `global note: <text>`, and submitting with
+nothing but a global note still returns an answered result rather than a decline.
+
 Inside the editor, `Shift+Enter` inserts a newline, while `Esc` and `Enter` close it; other
 keystrokes edit the buffer, so `n` types an `n`. Pasted line breaks are preserved.
 
@@ -98,6 +103,9 @@ content above, `↓` for content below, `↕` for both.
 
 The footer hint line adapts to context — it drops the notes hint and appends the
 `Shift+Enter` newline hint whenever a text editor has the keyboard, with `Ctrl+U` still at
-the far right for custom answers. It adds the tab hint only in multi-question dialogs.
+the far right for custom answers. It adds the tab hint only in multi-question dialogs. The
+Submit tab follows the same idiom: its bottom hint row sits below the picker and carries
+an `n to add a note` part that gives way to the `Shift+Enter` newline hint while the
+global-note editor is open; a committed note shows as a `Note` entry in the review list.
 `Ctrl+G` remains Pi's global external-editor shortcut and is not repeated there. On narrow
 terminals the right edge clips with `…` so the core hints survive.

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/localization.md

@@ -52,11 +52,13 @@ Nine locale files ship in `locales/`:
 ## What is translated, and what is not
 
 Translation covers the chrome you read: the `Type something.` and `Next` sentinel rows,
-the footer hint segments (including the collapsed-state line), the Submit picker labels,
-the review-tab heading with its submit-readiness prompt and incomplete-answers warning, the
-preview pane's empty and notes-affordance lines, the notes header, the external-editor
-failure notification, and the two RPC dialog prompts. Twenty-three keys in total, all under the namespace
-`@juicesharp/rpiv-ask-user-question`.
+the footer hint segments (including the collapsed-state line and the Submit tab's
+`n to add a note` hint), the Submit picker labels, the review-tab heading with its
+submit-readiness prompt, incomplete-answers warning, and committed-note `Note` label, the
+preview pane's empty and notes-affordance lines, the notes header and the global-note
+header on the Submit tab, the
+external-editor failure notification, and the two RPC dialog prompts. Twenty-six keys in total,
+all under the namespace `@juicesharp/rpiv-ask-user-question`.
 
 Everything the *model* reads stays English by design: the tool description, the parameter
 schema descriptions, error messages, and the reserved-label list. Those are prompt inputs,
@@ -71,7 +73,9 @@ No code change is required.
 1. Copy `locales/en.json` to `locales/<code>.json`, where `<code>` is a locale the SDK
    supports.
 2. Translate the values. Keep every key, and keep the placeholders and leading symbols
-   (`↑/↓`, `⚠`) intact.
+   (`↑/↓`, `⚠`) intact. `hint.collapse` and `hint.expand_line` contain a literal `{key}`
+   placeholder that is replaced at render time with the user's configured `collapseKey` —
+   keep it verbatim, positioned wherever your language's word order wants the key name.
 3. Restart Pi and select the language with `/languages`.
 
 The loader iterates the SDK's supported-locale list over this directory at startup, so a

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/tool-schema.md

@@ -83,6 +83,7 @@ code. The `content[0].text` string is written for the model, not for a log.
       preview?: string,            // echoed back when the chosen option carried a preview
     }>,
     cancelled: boolean,
+    globalNote?: string,          // Submit-tab note; present even when cancelled is true
     error?: QuestionnaireError,    // one of the codes above
   }
 }
@@ -92,11 +93,16 @@ code. The `content[0].text` string is written for the model, not for a log.
 
 On success the text reads `User has answered your questions: "<question>"="<answer>". …
 You can now continue with the user's answers in mind.` A chosen option's `preview` is
-appended as `selected preview: <markdown>`, and a note as `user notes: <text>`.
-
-Cancelling, and any result that produces no answer segments, both collapse to the single
-string `User declined to answer questions` so the model sees one canonical signal.
-Partial submission is allowed: unanswered questions simply contribute no segment.
+appended as `selected preview: <markdown>`, a per-question note as `user notes: <text>`,
+and the Submit tab's global note as a trailing `global note: <text>` segment. A global
+note alone still yields the answered envelope — it counts as an answer even when every
+question is blank.
+
+Cancelling, and any result with neither answer segments nor a global note, both collapse
+to the single string `User declined to answer questions` so the model sees one canonical
+signal. Partial submission is allowed: unanswered questions simply contribute no segment.
+A cancelled result always reads as the decline in text; its note, if any, survives only
+in `details.globalNote`.
 
 ## Event contract
 

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/en.json

@@ -12,17 +12,20 @@
   "hint.toggle": "Space to toggle",
   "hint.notes": "n to add notes",
   "hint.tab": "Tab to switch questions",
-  "hint.collapse": "Ctrl+] to collapse",
-  "hint.expand_line": "Ctrl+] to expand · Esc to cancel",
+  "hint.collapse": "{key} to collapse",
+  "hint.expand_line": "{key} to expand · Esc to cancel",
   "hint.cancel": "Esc to cancel",
 
   "review.heading": "Review your answers",
   "review.ready": "Ready to submit your answers?",
   "review.incomplete": "⚠ Answer remaining questions before submitting:",
+  "review.global_hint": "n to add a note",
+  "review.note_label": "Note",
 
   "preview.no_preview": "No preview available",
   "preview.notes_affordance": "Notes: press n to add notes",
   "notes.header": "Notes:",
+  "notes.global_header": "Global note:",
 
   "editor.failed": "External editor failed",
 

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/zh.json

@@ -14,8 +14,8 @@
   "hint.toggle": "空格切换",
   "hint.notes": "按 n 添加备注",
   "hint.tab": "Tab 切换问题",
-  "hint.collapse": "Ctrl+] 折叠",
-  "hint.expand_line": "Ctrl+] 展开 · Esc 取消",
+  "hint.collapse": "{key} 折叠",
+  "hint.expand_line": "{key} 展开 · Esc 取消",
   "hint.cancel": "Esc 取消",
 
   "review.heading": "检查你的答案",

package/node_modules/@juicesharp/rpiv-ask-user-question/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-ask-user-question",
-	"version": "2.6.0",
+	"version": "2.7.0",
 	"description": "Pi extension. A structured questionnaire the model can put to you when it would otherwise guess, with typed options instead of free-form replies.",
 	"keywords": [
 		"pi-package",
@@ -78,6 +78,7 @@
 		"view/tab-content-strategy.ts"
 	],
 	"pi": {
+		"image": "https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/cover.png",
 		"extensions": [
 			"./index.ts"
 		]
@@ -93,7 +94,7 @@
 		}
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^2.6.0",
+		"@juicesharp/rpiv-config": "^2.7.0",
 		"typebox": "^1.1.24"
 	}
 }

package/node_modules/@juicesharp/rpiv-ask-user-question/state/build-questionnaire.ts

@@ -40,6 +40,13 @@ export interface QuestionnaireBuildConfig {
 	isMulti: boolean;
 	initialState: QuestionnaireState;
 	getCurrentTab: () => number;
+	/**
+	 * Resolved collapse key spec (`"ctrl+]"`, `"alt+o"`, or `"off"`). Threaded to
+	 * `DialogConfig` as construction-time config so the footer hint can name the
+	 * real key — deliberately NOT part of `QuestionnaireState`, which stays free
+	 * of runtime context.
+	 */
+	collapseKey: string;
 }
 
 export interface QuestionnaireBuilt {
@@ -109,6 +116,7 @@ class QuestionnaireBuilder {
 	private readonly isMulti: boolean;
 	private readonly initialState: QuestionnaireState;
 	private readonly getCurrentTab: () => number;
+	private readonly collapseKey: string;
 
 	private readonly selectTheme: WrappingSelectTheme;
 	private readonly markdownTheme = getMarkdownTheme();
@@ -125,6 +133,7 @@ class QuestionnaireBuilder {
 		this.isMulti = config.isMulti;
 		this.initialState = config.initialState;
 		this.getCurrentTab = config.getCurrentTab;
+		this.collapseKey = config.collapseKey;
 
 		this.selectTheme = this.makeSelectTheme();
 		const textEditorTheme = editorTheme(this.theme);
@@ -258,6 +267,7 @@ class QuestionnaireBuilder {
 				getBodyHeight: heights.global,
 				getCurrentBodyHeight: heights.current,
 				getTerminalRows: this.getTerminalRows,
+				collapseKey: this.collapseKey,
 			},
 			{ state: this.initialState, activePreviewPane: this.pickInitialActivePreview(tabs) },
 		);

package/node_modules/@juicesharp/rpiv-ask-user-question/state/key-router.ts

@@ -150,6 +150,135 @@ function prevNavOnUp(state: QuestionnaireState, runtime: QuestionnaireRuntime):
 	};
 }
 
+// Collapsed-mode lockout: while collapsed, swallow every keystroke except cancel so
+// the user can read the now-uncovered transcript without accidentally mutating
+// answers or notes. The collapse toggle itself is already handled above.
+function routeCollapsed(kb: QuestionnaireKeybindings, data: string): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
+function routeNotesMode(kb: QuestionnaireKeybindings, data: string): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "notes_exit" };
+	if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "notes_forward", data };
+	if (isConfirm(kb, data)) return { kind: "notes_exit" };
+	return { kind: "notes_forward", data };
+}
+
+function routeInputMode(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	// Newline takes precedence over confirmation if a user configuration binds
+	// the same physical key to both semantic actions.
+	if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "ignore" };
+	if (isConfirm(kb, data)) {
+		const answer = buildSingleSelectAnswer(state, runtime);
+		if (!answer) return { kind: "ignore" };
+		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+	}
+	// Treat Pi's Ctrl+U line-kill binding as an explicit whole-draft clear,
+	// independent of the current cursor position.
+	if (kb.matches(data, KEYBIND_CLEAR)) return { kind: "input_clear" };
+	if (kb.matches(data, KEYBIND_EXTERNAL_EDITOR)) return { kind: "input_edit", value: runtime.inputBuffer };
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	if (kb.matches(data, KEYBIND_EDITOR_UP) && runtime.canMoveInputUp) return { kind: "ignore" };
+	if (kb.matches(data, KEYBIND_EDITOR_DOWN) && runtime.canMoveInputDown) return { kind: "ignore" };
+	if (kb.matches(data, KEYBIND_UP)) return prevNavOnUp(state, runtime);
+	if (kb.matches(data, KEYBIND_DOWN)) return nextNavOnDown(state, runtime);
+	return { kind: "ignore" };
+}
+
+function routeSubmitTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	const tab = tabSwitchAction(data, state, runtime);
+	if (tab) return tab;
+	if (kb.matches(data, KEYBIND_UP) || kb.matches(data, KEYBIND_DOWN)) {
+		const delta = kb.matches(data, KEYBIND_DOWN) ? 1 : -1;
+		const next = wrapTab(state.submitChoiceIndex + delta, 2);
+		return { kind: "submit_nav", nextIndex: (next === 1 ? 1 : 0) as 0 | 1 };
+	}
+	if (isConfirm(kb, data)) {
+		// D1 (revised): Submit always submits; Cancel always cancels. The warning header
+		// is informational only — `allAnswered(state)` no longer gates submission. Partial
+		// answers flow through `orderedAnswers()` in the host.
+		return state.submitChoiceIndex === 1 ? { kind: "cancel" } : { kind: "submit" };
+	}
+	// Global note (#182): `n` on the Submit tab opens the notes editor scoped to the whole
+	// questionnaire at the pseudo-index (`questions.length` in notesByTab). Reachable only
+	// with the editor closed — `routeKey` dispatches notesVisible traffic to
+	// `routeNotesMode` before the submit-tab block runs. The branch shadows nothing above
+	// it (cancel, tab switch, submit-nav, confirm): a literal `n` byte matches none of them
+	// under default bindings, and a user who deliberately binds one of those actions to
+	// `n` keeps that mapping because the earlier branch still wins (Enter still submits).
+	if (data === NOTES_ACTIVATE_KEY) {
+		return { kind: "notes_enter" };
+	}
+	return { kind: "ignore" };
+}
+
+function routeMultiSelectTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	const focusedKind = runtime.currentItem?.kind;
+	const focusedMeta = focusedKind ? ROW_INTENT_META[focusedKind] : undefined;
+	// Space toggles the focused row's checkbox. Suppressed on rows whose META declares
+	// `blocksMultiToggle` (the Next sentinel) or `activatesInputMode` (the "Type
+	// something." row — it is an inline input, not a checkable option).
+	if (data === SPACE_KEY) {
+		if (focusedMeta?.blocksMultiToggle) return { kind: "ignore" };
+		if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+		return { kind: "toggle", index: state.optionIndex };
+	}
+	if (isConfirm(kb, data)) {
+		// Enter on the "Type something." row is handled by the inputMode block above
+		// (→ confirm kind:"custom"). Defensive: never enter the toggle/multi_confirm
+		// path for an inputMode-activating row.
+		if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+		// Enter on a regular row toggles (matching Space) — committing the question is now
+		// gated behind explicit focus on a row whose META declares `autoSubmitsInMulti`
+		// (the Next sentinel), so Enter on options is a no-cost way to flip checkboxes
+		// without leaving the keyboard home row.
+		if (!focusedMeta?.autoSubmitsInMulti) return { kind: "toggle", index: state.optionIndex };
+		// Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
+		// multi-question mode, OR submit the dialog in single-question mode
+		// (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
+		// question would have no way to commit at all.
+		return {
+			kind: "multi_confirm",
+			selected: buildMultiSelected(state, runtime),
+			autoAdvanceTab: computeAutoAdvanceTab(state, runtime),
+		};
+	}
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
+function routeSingleSelectTab(
+	kb: QuestionnaireKeybindings,
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction {
+	if (isConfirm(kb, data)) {
+		const answer = buildSingleSelectAnswer(state, runtime);
+		if (!answer) return { kind: "ignore" };
+		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+	}
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}
+
 export function routeKey(data: string, state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
 	const kb = runtime.keybindings;
 
@@ -174,7 +303,9 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 	// replaces the lazily imported QuestionnaireSession graph on disk. Passing
 	// undefined into matchesKey reaches parseKeyId().toLowerCase() and crashes the
 	// entire host process, so keep the runtime boundary defensive even though the
-	// TypeScript contract requires a string.
+	// TypeScript contract requires a string. The "off" literal is deliberate:
+	// importing COLLAPSE_KEY_OFF would pull ../config.js (and its rpiv-config
+	// loader graph) into this pure module for a string that cannot change.
 	if (
 		typeof runtime.collapseKey === "string" &&
 		runtime.collapseKey !== "off" &&
@@ -183,60 +314,11 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 		return { kind: "toggle_collapsed" };
 	}
 
-	// Collapsed-mode lockout: while collapsed, swallow every keystroke except cancel so
-	// the user can read the now-uncovered transcript without accidentally mutating
-	// answers or notes. The collapse toggle itself is already handled above.
-	if (state.collapsed) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		return { kind: "ignore" };
-	}
-
-	if (state.notesVisible) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "notes_exit" };
-		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "notes_forward", data };
-		if (isConfirm(kb, data)) return { kind: "notes_exit" };
-		return { kind: "notes_forward", data };
-	}
-
-	if (state.inputMode) {
-		// Newline takes precedence over confirmation if a user configuration binds
-		// the same physical key to both semantic actions.
-		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "ignore" };
-		if (isConfirm(kb, data)) {
-			const answer = buildSingleSelectAnswer(state, runtime);
-			if (!answer) return { kind: "ignore" };
-			return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
-		}
-		// Treat Pi's Ctrl+U line-kill binding as an explicit whole-draft clear,
-		// independent of the current cursor position.
-		if (kb.matches(data, KEYBIND_CLEAR)) return { kind: "input_clear" };
-		if (kb.matches(data, KEYBIND_EXTERNAL_EDITOR)) return { kind: "input_edit", value: runtime.inputBuffer };
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		if (kb.matches(data, KEYBIND_EDITOR_UP) && runtime.canMoveInputUp) return { kind: "ignore" };
-		if (kb.matches(data, KEYBIND_EDITOR_DOWN) && runtime.canMoveInputDown) {
-			return { kind: "ignore" };
-		}
-		if (kb.matches(data, KEYBIND_UP)) return prevNavOnUp(state, runtime);
-		if (kb.matches(data, KEYBIND_DOWN)) return nextNavOnDown(state, runtime);
-		return { kind: "ignore" };
-	}
-
+	if (state.collapsed) return routeCollapsed(kb, data);
+	if (state.notesVisible) return routeNotesMode(kb, data);
+	if (state.inputMode) return routeInputMode(kb, data, state, runtime);
 	if (runtime.isMulti && state.currentTab === runtime.questions.length) {
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		const tab = tabSwitchAction(data, state, runtime);
-		if (tab) return tab;
-		if (kb.matches(data, KEYBIND_UP) || kb.matches(data, KEYBIND_DOWN)) {
-			const delta = kb.matches(data, KEYBIND_DOWN) ? 1 : -1;
-			const next = wrapTab(state.submitChoiceIndex + delta, 2);
-			return { kind: "submit_nav", nextIndex: (next === 1 ? 1 : 0) as 0 | 1 };
-		}
-		if (isConfirm(kb, data)) {
-			// D1 (revised): Submit always submits; Cancel always cancels. The warning header
-			// is informational only — `allAnswered(state)` no longer gates submission. Partial
-			// answers flow through `orderedAnswers()` in the host.
-			return state.submitChoiceIndex === 1 ? { kind: "cancel" } : { kind: "submit" };
-		}
-		return { kind: "ignore" };
+		return routeSubmitTab(kb, data, state, runtime);
 	}
 
 	const tab = tabSwitchAction(data, state, runtime);
@@ -249,7 +331,8 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 	// (single- or multi-select, preview or no-preview). The blocks above already
 	// swallow `n` when it should NOT reach here — notesVisible forwards to the
 	// notes Input, inputMode forwards to the inline Input, the submit-tab block
-	// ignores it, and tabSwitchAction ignores it — so by the time we reach this
+	// activates it via its own branch (the global note, ahead of its ignore
+	// fall-through), and tabSwitchAction ignores it — so by the time we reach this
 	// gate, `n` is unambiguously a notes-enter request. Row intent (Next sentinel,
 	// "Type something.") is irrelevant: the gate sits ABOVE the multi-select
 	// toggle block and the Next sentinel never activates inputMode, so `n` is
@@ -265,46 +348,6 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 		return nextNavOnDown(state, runtime);
 	}
 
-	if (q.multiSelect) {
-		const focusedKind = runtime.currentItem?.kind;
-		const focusedMeta = focusedKind ? ROW_INTENT_META[focusedKind] : undefined;
-		// Space toggles the focused row's checkbox. Suppressed on rows whose META declares
-		// `blocksMultiToggle` (the Next sentinel) or `activatesInputMode` (the "Type
-		// something." row — it is an inline input, not a checkable option).
-		if (data === SPACE_KEY) {
-			if (focusedMeta?.blocksMultiToggle) return { kind: "ignore" };
-			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
-			return { kind: "toggle", index: state.optionIndex };
-		}
-		if (isConfirm(kb, data)) {
-			// Enter on the "Type something." row is handled by the inputMode block above
-			// (→ confirm kind:"custom"). Defensive: never enter the toggle/multi_confirm
-			// path for an inputMode-activating row.
-			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
-			// Enter on a regular row toggles (matching Space) — committing the question is now
-			// gated behind explicit focus on a row whose META declares `autoSubmitsInMulti`
-			// (the Next sentinel), so Enter on options is a no-cost way to flip checkboxes
-			// without leaving the keyboard home row.
-			if (!focusedMeta?.autoSubmitsInMulti) return { kind: "toggle", index: state.optionIndex };
-			// Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
-			// multi-question mode, OR submit the dialog in single-question mode
-			// (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
-			// question would have no way to commit at all.
-			return {
-				kind: "multi_confirm",
-				selected: buildMultiSelected(state, runtime),
-				autoAdvanceTab: computeAutoAdvanceTab(state, runtime),
-			};
-		}
-		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-		return { kind: "ignore" };
-	}
-
-	if (isConfirm(kb, data)) {
-		const answer = buildSingleSelectAnswer(state, runtime);
-		if (!answer) return { kind: "ignore" };
-		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
-	}
-	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
-	return { kind: "ignore" };
+	if (q.multiSelect) return routeMultiSelectTab(kb, data, state, runtime);
+	return routeSingleSelectTab(kb, data, state, runtime);
 }

package/node_modules/@juicesharp/rpiv-ask-user-question/state/questionnaire-session.ts

@@ -1,10 +1,11 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Editor, OverlayHandle, TUI } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF, formatKeySpecForDisplay } from "../config.js";
 import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/types.js";
 import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
-import { COLLAPSED_HINT } from "../view/dialog-builder.js";
+import { COLLAPSED_HINT_TEMPLATE, HINT_PART_CANCEL, KEY_PLACEHOLDER } from "../view/dialog-builder.js";
 import type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
-import { buildQuestionnaire } from "./build-questionnaire.js";
+import { buildQuestionnaire, type QuestionnaireBuilt } from "./build-questionnaire.js";
 import { t } from "./i18n-bridge.js";
 import { type QuestionnaireAction, routeKey } from "./key-router.js";
 import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
@@ -21,6 +22,14 @@ export interface QuestionnaireSessionConfig {
 	editInput: (value: string) => Promise<string | undefined>;
 	/** Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
 	collapseKey: string;
+	/**
+	 * True iff `execute()` registered the raw `ctx.ui.onTerminalInput` listener — the only
+	 * path that can reach a hidden overlay. Gates the `set_overlay_hidden` effect: a host
+	 * that delivers an `OverlayHandle` but no raw terminal input must fall back to the
+	 * visible one-line collapsed row (which keeps focus and input routing), or collapsing
+	 * would hide the overlay into a state nothing can reopen.
+	 */
+	canReopenWhileHidden: boolean;
 }
 
 export interface QuestionnaireSessionComponent {
@@ -64,6 +73,7 @@ export class QuestionnaireSession {
 	private readonly keybindings: QuestionnaireRuntime["keybindings"];
 	private readonly editInput: QuestionnaireSessionConfig["editInput"];
 	private readonly collapseKey: string;
+	private readonly canReopenWhileHidden: boolean;
 	private inputEditorOpen = false;
 
 	/**
@@ -86,6 +96,7 @@ export class QuestionnaireSession {
 		this.keybindings = config.keybindings;
 		this.editInput = config.editInput;
 		this.collapseKey = config.collapseKey;
+		this.canReopenWhileHidden = config.canReopenWhileHidden;
 
 		const built = buildQuestionnaire({
 			tui: this.tui,
@@ -95,29 +106,45 @@ export class QuestionnaireSession {
 			isMulti: this.isMulti,
 			initialState: this.state,
 			getCurrentTab: () => this.state.currentTab,
+			collapseKey: this.collapseKey,
 		});
 
 		this.notesInput = built.notesInput;
 		this.inlineInput = built.inlineInput;
 		this.viewAdapter = built.adapter;
 
-		const theme = config.theme;
-		// Collapsed render: a single dim row at the bottom of the overlay. pi-tui sizes
-		// the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
-		// the bottom-anchored overlay from full-height to one row and the transcript
-		// behind it becomes readable (#47). The overlay stays focused and in the
-		// stack, so Ctrl+] still routes here to expand.
-		const collapsedRender = (_width: number): string[] => [
-			theme.fg("dim", ` ${t("hint.expand_line", COLLAPSED_HINT)} `),
-		];
-
-		this.component = {
+		this.component = this.assembleComponent(built, config.theme);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private assembleComponent(built: QuestionnaireBuilt, theme: Theme): QuestionnaireSessionComponent {
+		const collapsedRender = this.buildCollapsedRender(theme);
+		return {
 			render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
 			invalidate: built.invalidate,
 			handleInput: (data) => this.dispatch(data),
 		};
+	}
 
-		this.viewAdapter.apply(this.state);
+	/**
+	 * Collapsed render: a single dim row at the bottom of the overlay. pi-tui sizes
+	 * the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
+	 * the bottom-anchored overlay from full-height to one row and the transcript
+	 * behind it becomes readable (#47). The overlay stays focused and in the
+	 * stack, so the collapse key still routes here to expand. `t` stays inside the
+	 * closure (live locale updates); the key display is static per session.
+	 *
+	 * With collapseKey "off" the router and raw listener never toggle `collapsed`,
+	 * but `toggleCollapsedExternal()` is a public ungated entry — fall back to the
+	 * cancel-only line rather than rendering a literal "Off to expand".
+	 */
+	private buildCollapsedRender(theme: Theme): (width: number) => string[] {
+		const collapseKeyDisplay = formatKeySpecForDisplay(this.collapseKey);
+		const collapsedHintLine = (): string =>
+			this.collapseKey === COLLAPSE_KEY_OFF
+				? t("hint.cancel", HINT_PART_CANCEL)
+				: t("hint.expand_line", COLLAPSED_HINT_TEMPLATE).replace(KEY_PLACEHOLDER, collapseKeyDisplay);
+		return (_width: number): string[] => [theme.fg("dim", ` ${collapsedHintLine()} `)];
 	}
 
 	dispatch(data: string): void {
@@ -154,18 +181,7 @@ export class QuestionnaireSession {
 				this.inlineInput.setText("");
 				return;
 			case "open_input_editor":
-				if (this.inputEditorOpen) return;
-				this.inputEditorOpen = true;
-				void this.editInput(effect.value).then(
-					(value) => {
-						this.inputEditorOpen = false;
-						if (value !== undefined) this.commit({ kind: "input_replace", value });
-					},
-					() => {
-						// The host callback reports launch errors; retain the draft and restore input handling.
-						this.inputEditorOpen = false;
-					},
-				);
+				this.openInputEditorAsync(effect.value);
 				return;
 			case "set_notes_value":
 				this.notesInput.setText(effect.value);
@@ -178,8 +194,11 @@ export class QuestionnaireSession {
 				return;
 			case "set_overlay_hidden":
 				// No-op until `setOverlayHandle` has been called (the handle arrives via
-				// `ctx.ui.custom`'s `onHandle` right after the overlay is shown).
-				this.overlayHandle?.setHidden(effect.hidden);
+				// `ctx.ui.custom`'s `onHandle` right after the overlay is shown), and
+				// suppressed entirely when no raw terminal listener exists — hiding would
+				// then be irreversible (pi-tui routes no input to a hidden overlay), so the
+				// visible one-line collapsed row serves as the fallback rendering instead.
+				if (this.canReopenWhileHidden) this.overlayHandle?.setHidden(effect.hidden);
 				return;
 			case "done":
 				this.done(effect.result);
@@ -187,6 +206,22 @@ export class QuestionnaireSession {
 		}
 	}
 
+	/** Opens Pi's configured external editor; on success commits the replacement buffer, on reported failure retains the draft. */
+	private openInputEditorAsync(value: string): void {
+		if (this.inputEditorOpen) return;
+		this.inputEditorOpen = true;
+		void this.editInput(value).then(
+			(edited) => {
+				this.inputEditorOpen = false;
+				if (edited !== undefined) this.commit({ kind: "input_replace", value: edited });
+			},
+			() => {
+				// The host callback reports launch errors; retain the draft and restore input handling.
+				this.inputEditorOpen = false;
+			},
+		);
+	}
+
 	/**
 	 * Per-keystroke `ignore` fast path: delegates text editing to Pi's headless
 	 * multiline `Editor`, including paste, undo, cursor movement, and configured