@nklisch/pi-enhanced 0.1.0

package/node_modules/@ff-labs/pi-fff/src/query.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+export function normalizePathConstraint(
+  pathConstraint: string,
+  cwd = process.cwd(),
+): string | null {
+  let trimmed = pathConstraint.trim();
+  if (!trimmed) return trimmed;
+
+  if (path.isAbsolute(trimmed)) {
+    const relative = path.relative(cwd, trimmed).replaceAll(path.sep, "/");
+    if (relative === "") return null;
+    if (
+      relative.startsWith("../") ||
+      relative === ".." ||
+      path.isAbsolute(relative)
+    ) {
+      throw new Error(
+        `Path constraint must be relative to the workspace: ${pathConstraint}`,
+      );
+    }
+    trimmed = relative;
+  }
+
+  if (trimmed === "." || trimmed === "./") return null;
+  // Strip a leading `./` so `./**/*.rs` and `**/*.rs` behave identically.
+  if (trimmed.startsWith("./")) trimmed = trimmed.slice(2);
+
+  // wif we left with the ** it means anything so treat it as a cwd path
+  if (trimmed === "**" || trimmed === "**/" || trimmed === "**/*") return null;
+
+  // FFF's glob matcher can treat a hidden directory root glob such as
+  // `.agents/**` as empty, while the tool contract says this means "inside
+  // this directory". Collapse simple trailing recursive directory globs to the
+  // directory-prefix constraint understood by the parser. Keep real file globs
+  // such as `src/**/*.ts` unchanged.
+  const recursiveDir = trimmed.match(/^(.*)\/\*\*(?:\/\*)?$/);
+  if (recursiveDir) {
+    const dir = recursiveDir[1];
+    if (dir && !/[*?[{]/.test(dir)) return `${dir}/`;
+  }
+
+  // Already signals path-constraint syntax to the parser.
+  if (trimmed.startsWith("/") || trimmed.endsWith("/")) return trimmed;
+  // Globs (`*.ts`, `src/**/*.cc`, `{src,lib}`) are handled by the parser.
+  if (/[*?[{]/.test(trimmed)) return trimmed;
+  // Filename with extension (`main.rs`, `config.json`) → FilePath constraint.
+  const lastSegment = trimmed.split("/").pop() ?? "";
+  if (/\.[a-zA-Z][a-zA-Z0-9]{0,9}$/.test(lastSegment)) return trimmed;
+  // Bare directory prefix → append `/` so the parser sees a PathSegment.
+  return `${trimmed}/`;
+}
+
+// Exclusions are emitted as `!<constraint>` tokens, which the Rust parser
+// understands (crates/fff-query-parser/src/parser.rs). We normalize each one
+// the same way as the include path so bare dirs become PathSegment excludes.
+// Tolerate callers passing already-negated forms like `!src/` by stripping
+// the leading `!` before normalizing so we never double-negate (`!!src/`).
+export function normalizeExcludes(
+  exclude: string | string[] | undefined,
+  cwd = process.cwd(),
+): string[] {
+  if (!exclude) return [];
+  const list = Array.isArray(exclude) ? exclude : [exclude];
+  const out: string[] = [];
+  for (const raw of list) {
+    const parts = raw
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const p of parts) {
+      const stripped = p.startsWith("!") ? p.slice(1) : p;
+      const normalized = normalizePathConstraint(stripped, cwd);
+      if (normalized) out.push(`!${normalized}`);
+    }
+  }
+  return out;
+}
+
+export function buildQuery(
+  path: string | undefined,
+  pattern: string,
+  exclude?: string | string[],
+  cwd = process.cwd(),
+): string {
+  const parts: string[] = [];
+  if (path) {
+    const pathConstraint = normalizePathConstraint(path, cwd);
+    if (pathConstraint) parts.push(pathConstraint);
+  }
+  parts.push(...normalizeExcludes(exclude, cwd));
+  parts.push(pattern);
+  return parts.join(" ");
+}

package/node_modules/@ff-labs/pi-fff/src/sdk.ts

@@ -0,0 +1,29 @@
+import type { FileFinderApi, InitOptions, Result } from "@ff-labs/fff-node";
+
+export const SCAN_TIMEOUT_MS = 15_000;
+
+/** pi can be run either under node or sdk, we resolve correct SDK version at runtime */
+export type FileFinderStatic = {
+  create(options: InitOptions): Result<FileFinderApi>;
+};
+
+let sdkPromise: Promise<{ FileFinder: FileFinderStatic }> | null = null;
+
+function detectRuntime(): "bun" | "node" {
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") return "bun";
+  if (
+    typeof process !== "undefined" &&
+    (process as { versions?: { bun?: string } }).versions?.bun
+  )
+    return "bun";
+  return "node";
+}
+
+export function loadSdk(): Promise<{ FileFinder: FileFinderStatic }> {
+  if (sdkPromise) return sdkPromise;
+
+  // default to node as it seems like default option
+  const pkg = detectRuntime() === "bun" ? "@ff-labs/fff-bun" : "@ff-labs/fff-node";
+  sdkPromise = import(pkg) as Promise<{ FileFinder: FileFinderStatic }>;
+  return sdkPromise;
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,91 @@
+# @juicesharp/rpiv-ask-user-question
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-ask-user-question.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<div align="center">
+  <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question">
+    <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/cover.png" alt="rpiv-ask-user-question cover: a tabbed terminal questionnaire asking Which real development task are we planning right now?, with numbered options — Bug fix, New feature, Refactor — each under a one-line description, and a footer of key hints" width="50%">
+  </a>
+</div>
+
+Let the model ask you instead of guessing. This extension gives [Pi Agent](https://github.com/badlogic/pi-mono) one tool — `ask_user_question` — that opens a terminal dialog of up to four questions with written-out options, and hands your choices back as structured data. Install it if you would rather spend fifteen seconds picking than an hour undoing a wrong assumption.
+
+## Install
+
+```sh
+pi install npm:@juicesharp/rpiv-ask-user-question
+```
+
+Restart your Pi session.
+
+## Quick start
+
+Nothing to set up — the tool is live as soon as Pi restarts. Hand the model a task with a real decision buried in it:
+
+> Add caching to the API client.
+
+Rather than picking a strategy on your behalf, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `↑`/`↓`, choose with `Enter`, press `n` to attach a note, or land on the `Type something.` row to answer in your own words. `Esc` abandons the questionnaire entirely.
+
+![Single question in the dialog: the tab strip reads Feature Type, Design Tab, Testing, Release, Submit; the question Which real development task are we planning right now? sits above four numbered options — Bug fix (Recommended), New feature, Refactor, Perf tuning — each with a one-line description, followed by the appended Type something. row](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/single-question.jpg)
+
+When the model asks several things at once, `Tab` moves between them and a Submit tab reviews everything before it goes back:
+
+![Submit tab of a four-question dialog: a Review your answers list showing Feature Type set to Bug fix and Testing set to Unit tests plus Integration tests, a warning naming Design Tab and Release as still unanswered, and a picker offering Submit answers or Cancel](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/submit-tab.jpg)
+
+## What you get
+
+- **Typed options instead of a wall of prose** — each question carries 2-4 authored choices, and every choice comes with a description of what it means or what it costs you.
+- **You can always answer in your own words** — a `Type something.` row is appended to every question, single- or multi-select, and widens to the full pane while you type.
+- **Compare real artifacts, not just labels** — an option can carry a markdown `preview` (ASCII mockup, code, diagram, config) that renders in a bordered box beside the option list.
+- **One interruption, not five** — up to four questions arrive in a single tabbed dialog, and the Submit tab lists your answers and names anything still blank before you commit.
+- **Notes on any answer** — `n` opens a note editor on any question tab; the note travels back to the model alongside the choice without marking the question answered.
+- **Read the transcript behind the dialog** — `Ctrl+]` collapses the overlay so you can scroll the conversation, then brings it back with your answers intact.
+- **Works outside the terminal too** — in RPC and ACP hosts such as the VS Code pendant or Zed the questionnaire walks through the host's native dialogs, and in non-interactive runs the tool is removed from the model's tool list instead of failing every call.
+
+## Configuration
+
+Optional. Settings live in `~/.config/rpiv-ask-user-question/config.json`; the file is read, never written.
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog. Accepts Pi keybinding ids such as `alt+o`; `"off"` disables the shortcut. | `"ctrl+]"` |
+| `guidance.promptSnippet` | One-line description of the tool in the system prompt — tune how eagerly the model asks. | built-in snippet |
+| `guidance.promptGuidelines` | Usage guidelines given to the model, as a list of strings. | 4 built-in guidelines |
+
+```json
+{ "collapseKey": "alt+o" }
+```
+
+Malformed JSON falls back to the defaults with a warning; an individual unusable value is silently dropped back to its default. Never an error.
+
+## Reference
+
+- [Tool schema](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/tool-schema.md) — parameters, limits, reserved labels, validation errors, the result envelope, and the `rpiv:ask-user:prompt` event.
+- [Keyboard and layout](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/keyboard.md) — every key, the rows the dialog appends, notes, collapse mode, and how previews and overflow adapt to terminal size.
+- [Configuration](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/configuration.md) — file lookup and `XDG_CONFIG_HOME`, the `collapseKey` grammar, the `guidance.*` prompt overrides, and how invalid values are handled.
+- [Hosts and runtime behavior](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/hosts.md) — terminal vs RPC vs non-interactive, what degrades in each, and the load-failure envelopes.
+- [Localization](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/docs/localization.md) — the nine shipped languages, how the locale is chosen, and how to add one.
+
+## Requirements
+
+- Node.js 22 or newer.
+- Pi Agent, with an interactive terminal or an RPC/ACP host. Non-interactive runs never see the tool.
+- A terminal at least 100 columns wide for side-by-side previews; narrower terminals stack the preview under the options.
+
+No native dependencies, no compiler, no API keys — the extension makes no model calls of its own.
+
+## Troubleshooting
+
+**The model says the questionnaire UI failed to load and asks its questions as chat text.** The dialog's modules were replaced on disk while Pi was running, usually by a package-manager install touching the store. Repair the install if it is broken, then restart Pi; the failure is not recoverable inside the running process.
+
+**`Ctrl+]` does nothing.** On keyboard layouts where `]` sits on the shifted layer (Latin American among them) the default is unreachable. Set `collapseKey` to something you can type, for example `"alt+o"`.
+
+## Related
+
+- [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) — optional; installing it renders the dialog chrome in your language and adds `/languages`.
+- [`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) — the umbrella package whose workflow skills use `ask_user_question` as their developer checkpoint. `/rpiv-setup` offers to install this extension.
+
+## License
+
+MIT — see [LICENSE](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-ask-user-question/LICENSE).

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

@@ -0,0 +1,296 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import { loadConfig, resolveCollapseKey, validateGuidanceFields } from "./config.js";
+import {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+} from "./events.js";
+// Static import is fine — rpc-fallback pulls only types + the i18n bridge,
+// none of the ~560ms TUI render graph that QuestionnaireSession lazy-loads.
+import { hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
+import { displayLabel } from "./state/i18n-bridge.js";
+import { sentinelsToAppend } from "./state/row-intent.js";
+import { buildQuestionnaireResponse, buildToolResult } from "./tool/response-envelope.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	type QuestionData,
+	type QuestionnaireError,
+	type QuestionnaireResult,
+	type QuestionParams,
+	QuestionParamsSchema,
+} from "./tool/types.js";
+import { validateQuestionnaire } from "./tool/validate-questionnaire.js";
+import type { WrappingSelectItem } from "./view/components/wrapping-select.js";
+
+function emitAskUserPromptEvent(pi: ExtensionAPI, params: QuestionParams): void {
+	const payload: AskUserPromptEventPayload = {
+		questions: params.questions.map((q) => ({
+			question: q.question,
+			header: q.header,
+			multiSelect: q.multiSelect ?? false,
+			options: q.options.map((o) => ({
+				label: o.label,
+				description: o.description,
+				hasPreview: typeof o.preview === "string" && o.preview.length > 0,
+			})),
+		})),
+	};
+	pi.events.emit(ASK_USER_PROMPT_EVENT, payload);
+}
+
+function emitAskUserBlockedEvent(pi: ExtensionAPI, active: boolean): void {
+	const payload: AskUserBlockedEventPayload = { active };
+	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
+}
+
+/** Canonical tool name — single source of truth shared with the reconcile module. */
+export const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+
+const ERROR_NO_UI = "Error: UI not available (running in non-interactive mode)";
+
+const ERROR_NO_CUSTOM_UI =
+	"Error: this client cannot render the questionnaire (custom UI is unavailable, e.g. RPC/ACP hosts such as Zed or Paseo). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.";
+
+const ERROR_SESSION_LOAD_FAILED =
+	"Error: the questionnaire UI failed to load — the host's installed dependencies were likely replaced or removed on disk while Pi was running (e.g. a package-manager install touched the store). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user that restoring this tool requires repairing the install if needed and restarting Pi.";
+
+const ERROR_STALE_MODULE_CACHE =
+	"Error: the questionnaire UI cannot load — the host's module cache went stale after an earlier failed load (typically dependencies replaced on disk mid-session). This is unrecoverable within the current Pi process. The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user to restart Pi to restore this tool.";
+
+/** Delay before the background session-graph pre-warm; mirrors rpiv-workflow's /wf prewarm. */
+export const PREWARM_DELAY_MS = 2000;
+
+type SessionModule = typeof import("./state/questionnaire-session.js");
+
+type SessionLoad =
+	| { ok: true; module: SessionModule }
+	| { ok: false; error: Extract<QuestionnaireError, "session_load_failed" | "stale_module_cache">; message: string };
+
+/**
+ * Lazy-load the ~560ms QuestionnaireSession view/TUI render graph, guarding
+ * the two failure shapes of issue #107. Pi's jiti loader registers a module in
+ * its graph cache BEFORE evaluating the body and does not evict it when
+ * evaluation throws (jiti 2.7.0), so one failed load — e.g. `pnpm install
+ * --force` replacing the store entry mid-session — leaves every later import
+ * of this specifier resolving to a namespace without the class. That state is
+ * unrecoverable in-process (cache-busting specifiers fail jiti resolution);
+ * both branches therefore return an LLM-facing envelope that names the restart
+ * requirement instead of leaking a bare "not a constructor" TypeError.
+ */
+export async function loadQuestionnaireSession(): Promise<SessionLoad> {
+	let mod: SessionModule;
+	try {
+		mod = await import("./state/questionnaire-session.js");
+	} catch (e) {
+		const cause = e instanceof Error ? e.message : String(e);
+		return { ok: false, error: "session_load_failed", message: `${ERROR_SESSION_LOAD_FAILED} (cause: ${cause})` };
+	}
+	if (typeof mod.QuestionnaireSession !== "function") {
+		const keys = JSON.stringify(Object.keys(mod));
+		return {
+			ok: false,
+			error: "stale_module_cache",
+			message: `${ERROR_STALE_MODULE_CACHE} (resolved namespace keys: ${keys})`,
+		};
+	}
+	return { ok: true, module: mod };
+}
+
+export function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {
+	const items: WrappingSelectItem[] = question.options.map((o) => ({
+		kind: "option",
+		label: o.label,
+		description: o.description,
+	}));
+	for (const kind of sentinelsToAppend(question)) {
+		items.push({ kind, label: displayLabel(kind) });
+	}
+	return items;
+}
+
+export const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;
+export const DEFAULT_PROMPT_GUIDELINES: string[] = [
+	`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+	`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended "Type something." row on every question, or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.`,
+	`Set multiSelect: true when multiple answers are valid. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. The "Type something." row is appended to every question; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column. If you recommend a specific option, make that the first option and append "(Recommended)" to its label.`,
+	"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.",
+];
+
+export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
+	const guidance = validateGuidanceFields(loadConfig().guidance);
+	pi.registerTool({
+		name: ASK_USER_QUESTION_TOOL_NAME,
+		label: "Ask User Question",
+		description: `Ask the user one or more structured questions during execution. Use when you need to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take
+
+Usage notes:
+- Users can type a custom answer via the automatically appended "Type something." row on every question or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- Use multiSelect: true when multiple answers are valid. The "Type something." row is available on every question, including when options carry a \`preview\`; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column.
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label.
+
+Preview feature:
+Use the optional \`preview\` field on options when presenting concrete artifacts that users need to visually compare:
+- ASCII mockups of UI layouts or components
+- Code snippets showing different implementations
+- Diagram variations
+- Configuration examples
+
+Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,
+		promptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,
+		promptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,
+		parameters: QuestionParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typed = params as unknown as QuestionParams;
+			if (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+
+			const validation = validateQuestionnaire(typed);
+			if (!validation.ok) {
+				return buildToolResult(validation.message, {
+					answers: [],
+					cancelled: true,
+					error: validation.error,
+				});
+			}
+
+			// Emit event for external listeners (e.g., notification plugins)
+			emitAskUserPromptEvent(pi, typed);
+
+			// RPC hosts (VSCode pendant, ACP clients like Zed/Paseo — issue #78):
+			// ui.custom() cannot render there, but the select/input dialog
+			// sub-protocol works. Hosts that advertise ctx.mode (pi ≥0.79) route to
+			// the sequential dialog walker up front, skipping the TUI render-graph
+			// import entirely; RPC builds that predate ctx.mode are caught by the
+			// custom()-resolved-undefined backstop below. See ./rpc-fallback.ts.
+			if ((ctx as { mode?: string }).mode === "rpc" && hasDialogUI(ctx.ui)) {
+				emitAskUserBlockedEvent(pi, true);
+				try {
+					return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+				} finally {
+					emitAskUserBlockedEvent(pi, false);
+				}
+			}
+
+			const itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));
+
+			// Lazy — QuestionnaireSession pulls the ~560ms view/TUI render graph;
+			// load it only when the tool runs, not at extension registration.
+			const sessionLoad = await loadQuestionnaireSession();
+			if (!sessionLoad.ok) {
+				return buildToolResult(sessionLoad.message, { answers: [], cancelled: true, error: sessionLoad.error });
+			}
+			const { QuestionnaireSession } = sessionLoad.module;
+			// Resolve the collapse/expand key spec from config. Default is `ctrl+]`; users
+			// with non-US layouts (e.g. Latin American, where `]` is shifted) can override
+			// via the `collapseKey` config field. `resolveCollapseKey` also accepts the
+			// sentinel value `"off"` to disable the shortcut entirely.
+			const collapseKey = resolveCollapseKey(loadConfig());
+
+			// Capture the overlay handle so the session can call `setHidden()` when the
+			// user toggles collapse, and register a raw terminal input listener for the
+			// same key so the toggle still works while the overlay is hidden (pi-tui does
+			// not route input to a hidden overlay's `component.handleInput`).
+			const sessionRef: {
+				current: import("./state/questionnaire-session.js").QuestionnaireSession | null;
+			} = { current: null };
+			const overlayHandleRef: { current: import("@earendil-works/pi-tui").OverlayHandle | undefined } = {
+				current: undefined,
+			};
+			let hasAnnouncedHide = false;
+			let removeOverlayInputListener: (() => void) | undefined;
+
+			if (collapseKey !== "off" && typeof ctx.ui.onTerminalInput === "function") {
+				removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
+					const handle = overlayHandleRef.current;
+					if (!handle) return undefined;
+					// Only act while the questionnaire is hidden (its handleInput is
+					// unreachable) or actually focused. When some other overlay is on
+					// top (e.g. `/btw`), leave the keystroke to that overlay instead of
+					// toggling the questionnaire from underneath it.
+					if (!handle.isHidden() && !handle.isFocused()) return undefined;
+					if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) return undefined;
+					// Kitty-protocol terminals report press, repeat, and release separately.
+					// Toggle only on the initial press so a tap does not immediately reopen
+					// the overlay and a held key does not toggle it repeatedly.
+					if (isKeyRelease(data) || isKeyRepeat(data)) return { consume: true };
+					sessionRef.current?.toggleCollapsedExternal();
+					if (handle.isHidden() && !hasAnnouncedHide) {
+						hasAnnouncedHide = true;
+						ctx.ui.notify?.(`ask_user_question hidden — press ${collapseKey} to reopen`, "info");
+					}
+					return { consume: true };
+				});
+			}
+
+			emitAskUserBlockedEvent(pi, true);
+			try {
+				const result = await ctx.ui.custom<QuestionnaireResult>(
+					(tui, theme, _kb, done) => {
+						const session = new QuestionnaireSession({
+							tui,
+							theme,
+							params: typed,
+							itemsByTab,
+							done,
+							collapseKey,
+						});
+						sessionRef.current = session;
+						return session.component;
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							anchor: "bottom-center",
+							width: "100%",
+							maxHeight: "100%",
+							margin: { left: 0, right: 0, bottom: 0 },
+						},
+						onHandle: (handle) => {
+							overlayHandleRef.current = handle;
+							sessionRef.current?.setOverlayHandle(handle);
+						},
+					},
+				);
+
+				// A TUI questionnaire ALWAYS resolves a QuestionnaireResult (cancel
+				// included — state-reducer emits `{ answers, cancelled }`), so
+				// `undefined` uniquely means "host cannot render", never "user
+				// declined". RPC builds that predate ctx.mode land here: run the
+				// dialog walker when the host has the primitives; otherwise tell the
+				// model the user never saw the questions.
+				if (result === undefined) {
+					if (hasDialogUI(ctx.ui)) {
+						return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+					}
+					return buildToolResult(ERROR_NO_CUSTOM_UI, { answers: [], cancelled: true, error: "no_custom_ui" });
+				}
+
+				return buildQuestionnaireResponse(result, typed);
+			} finally {
+				removeOverlayInputListener?.();
+				emitAskUserBlockedEvent(pi, false);
+			}
+		},
+	});
+
+	// Pre-warm the lazy session graph once startup settles (#107). A graph
+	// evaluated while the paths Pi resolved at boot still exist stays in memory
+	// for the process lifetime, so later on-disk dependency churn (e.g. `pnpm
+	// install --force` replacing the store mid-session) can no longer poison
+	// jiti's graph cache. Swallowed failure is safe: the first real call
+	// re-imports and surfaces it through loadQuestionnaireSession's structured
+	// envelope. unref keeps the timer from holding a non-TUI embedder's process
+	// open.
+	const timer = setTimeout(() => void loadQuestionnaireSession().catch(() => undefined), PREWARM_DELAY_MS);
+	timer.unref?.();
+}
+
+export { buildQuestionnaireResponse, buildToolResult };

package/node_modules/@juicesharp/rpiv-ask-user-question/config.ts

@@ -0,0 +1,75 @@
+import type { GuidanceFields } from "@juicesharp/rpiv-config";
+import { loadJsonConfigWithLegacyFallback, validateGuidanceFields } from "@juicesharp/rpiv-config";
+
+/** Key spec for the overlay collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+export type CollapseKeySpec = string;
+
+export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+]";
+export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
+
+export interface AskUserQuestionConfig {
+	guidance?: GuidanceFields;
+	/**
+	 * Key spec for the collapse/expand shortcut, in the same format as pi-coding-agent
+	 * keybinding ids (`modifier+key`, e.g. `ctrl+]`, `alt+o`, `ctrl+shift+h`). Defaults
+	 * to `"ctrl+]"`. Set this to a key that is reachable on your keyboard layout — Latin
+	 * American layouts (where `]` is on the shifted layer) often want `"ctrl+}"` instead.
+	 * Pass `"off"` to disable the collapse shortcut entirely.
+	 */
+	collapseKey?: CollapseKeySpec;
+}
+
+// Named keys accepted by pi-tui's `matchesKey` (keys.js switch on the parsed base key).
+// parseKeyId lowercases the id before matching, so lowercase spellings are canonical.
+const SPECIAL_KEYS = new Set([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+function isValidCollapseKeySpec(spec: string): boolean {
+	// Mirror pi-tui's KeyId grammar strictly: zero or more distinct modifiers, then a
+	// base key that is a single printable character or a named special key. A loose
+	// check is not enough — pi-tui's `parseKeyId` takes the LAST `+`-part as the key
+	// and ignores unknown parts, so a typo like `ctr+]` would silently match every
+	// bare `]` keypress (and the raw terminal listener would consume them globally).
+	if (!spec) return false;
+	if (spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+	const parts = spec.split("+");
+	const base = parts[parts.length - 1] ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (modifiers.length !== new Set(modifiers).size) return false;
+	if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+	return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+
+export function resolveCollapseKey(config: Pick<AskUserQuestionConfig, "collapseKey">): CollapseKeySpec {
+	const raw = config.collapseKey?.trim().toLowerCase();
+	if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
+	if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+	return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+
+export function loadConfig(): AskUserQuestionConfig {
+	return loadJsonConfigWithLegacyFallback<AskUserQuestionConfig>("rpiv-ask-user-question");
+}
+
+export { validateGuidanceFields };