@garygentry/feature-forge 0.2.13 → 0.3.0

package/adapters/pi/extensions/ask-user-question/state/key-router.ts

@@ -0,0 +1,277 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/key-router.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import type { QuestionAnswer } from "../tool/types.js";
+import { ROW_INTENT_META } from "./row-intent.js";
+import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
+
+const KEYBIND_UP = "tui.select.up";
+const KEYBIND_DOWN = "tui.select.down";
+const KEYBIND_CONFIRM = "tui.select.confirm";
+const KEYBIND_CANCEL = "tui.select.cancel";
+
+const NOTES_ACTIVATE_KEY = "n";
+const SPACE_KEY = " ";
+
+export type QuestionnaireAction =
+	| { kind: "nav"; nextIndex: number }
+	| { kind: "tab_switch"; nextTab: number }
+	| { kind: "confirm"; answer: QuestionAnswer; autoAdvanceTab?: number }
+	| { kind: "toggle"; index: number }
+	| { kind: "multi_confirm"; selected: string[]; autoAdvanceTab?: number }
+	| { kind: "cancel" }
+	| { kind: "notes_enter" }
+	| { kind: "notes_exit" }
+	| { kind: "submit" }
+	| { kind: "submit_nav"; nextIndex: 0 | 1 }
+	| { kind: "notes_forward"; data: string }
+	/** Flip `state.collapsed`. Always available, regardless of inner mode (see top intercept in `routeKey`). */
+	| { kind: "toggle_collapsed" }
+	| { kind: "ignore" };
+
+export interface QuestionnaireKeybindings {
+	matches(data: string, name: string): boolean;
+}
+
+export function wrapTab(index: number, total: number): number {
+	if (total <= 0) return 0;
+	return ((index % total) + total) % total;
+}
+
+export function allAnswered(state: QuestionnaireState, runtime: QuestionnaireRuntime): boolean {
+	if (runtime.questions.length === 0) return false;
+	for (let i = 0; i < runtime.questions.length; i++) {
+		if (!state.answers.has(i)) return false;
+	}
+	return true;
+}
+
+function totalTabs(runtime: QuestionnaireRuntime): number {
+	return runtime.isMulti ? runtime.questions.length + 1 : 1;
+}
+
+function computeAutoAdvanceTab(state: QuestionnaireState, runtime: QuestionnaireRuntime): number | undefined {
+	if (!runtime.isMulti) return undefined;
+	if (state.currentTab < runtime.questions.length - 1) return state.currentTab + 1;
+	return runtime.questions.length;
+}
+
+function buildSingleSelectAnswer(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionAnswer | null {
+	const q = runtime.questions[state.currentTab];
+	if (!q) return null;
+
+	const item = runtime.currentItem;
+
+	if (state.inputMode) {
+		const label = runtime.inputBuffer;
+		return {
+			questionIndex: state.currentTab,
+			question: q.question,
+			kind: "custom",
+			answer: label.length > 0 ? label : null,
+		};
+	}
+	if (!item) return null;
+	if (item.kind === "other") {
+		return null;
+	}
+	if (item.kind === "next") {
+		return null;
+	}
+	return {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "option",
+		answer: item.label,
+	};
+}
+
+function buildMultiSelected(state: QuestionnaireState, runtime: QuestionnaireRuntime): string[] {
+	const q = runtime.questions[state.currentTab];
+	if (!q) return [];
+	const out: string[] = [];
+	for (let i = 0; i < q.options.length; i++) {
+		if (state.multiSelectChecked.has(i)) {
+			const label = q.options[i]?.label;
+			if (typeof label === "string") out.push(label);
+		}
+	}
+	return out;
+}
+
+function tabSwitchAction(
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction | null {
+	if (!runtime.isMulti) return null;
+	const total = totalTabs(runtime);
+	if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+		return { kind: "tab_switch", nextTab: wrapTab(state.currentTab + 1, total) };
+	}
+	if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+		return { kind: "tab_switch", nextTab: wrapTab(state.currentTab - 1, total) };
+	}
+	return null;
+}
+
+// DOWN at the last item wraps to the first (cycle through [option0, …, optionLast]).
+function nextNavOnDown(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	return { kind: "nav", nextIndex: wrapTab(state.optionIndex + 1, Math.max(1, runtime.items.length)) };
+}
+
+// UP at the first item wraps to the last (symmetric with nextNavOnDown).
+function prevNavOnUp(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	return { kind: "nav", nextIndex: wrapTab(state.optionIndex - 1, Math.max(1, runtime.items.length)) };
+}
+
+export function routeKey(data: string, state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	const kb = runtime.keybindings;
+
+	// Collapse/expand toggle is a UI-level affordance — intercepted at the top so it
+	// works from every inner state (notes, inputMode, submit tab, multi-select)
+	// without reaching any branch that would otherwise consume the keystroke. The
+	// questionnaire overlay is fully hidden via `OverlayHandle.setHidden(true)` while
+	// collapsed; pi-tui's overlay stack updates accordingly, so overlay-aware consumers
+	// (e.g. `pi-station`) see no visible modal and chat scroll resumes. The toggle key is
+	// also captured at the raw terminal level via `ctx.ui.onTerminalInput` so it still
+	// routes here when the overlay is hidden (pi-tui does not deliver input to a hidden
+	// overlay's `component.handleInput`).
+	//
+	// The default `ctrl+]` is free in every mainstream macOS terminal (Terminal.app,
+	// iTerm2, Warp), every multiplexer (tmux, zellij, screen — none use it as a prefix),
+	// and the legacy telnet/ssh escape role doesn't apply because our overlay runs
+	// in-process. It is, however, awkward on keyboard layouts where `]` is on the
+	// shifted layer (Latin American `es-AR`/`es-MX` require `Ctrl+Shift+}` for `Ctrl+]`)
+	// — use the `collapseKey` config field to override.
+	// Treat a missing/non-string key as disabled. This can occur at runtime when
+	// a long-lived Pi process retains an older outer module while a package update
+	// 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.
+	if (
+		typeof runtime.collapseKey === "string" &&
+		runtime.collapseKey !== "off" &&
+		matchesKey(data, runtime.collapseKey as Parameters<typeof matchesKey>[1])
+	) {
+		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_CONFIRM)) return { kind: "notes_exit" };
+		return { kind: "notes_forward", data };
+	}
+
+	if (state.inputMode) {
+		if (kb.matches(data, KEYBIND_CONFIRM)) {
+			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" };
+		if (kb.matches(data, KEYBIND_UP)) {
+			return prevNavOnUp(state, runtime);
+		}
+		if (kb.matches(data, KEYBIND_DOWN)) {
+			return nextNavOnDown(state, runtime);
+		}
+		return { kind: "ignore" };
+	}
+
+	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 (kb.matches(data, KEYBIND_CONFIRM)) {
+			// 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" };
+	}
+
+	const tab = tabSwitchAction(data, state, runtime);
+	if (tab) return tab;
+
+	const q = runtime.questions[state.currentTab];
+	if (!q) return { kind: "ignore" };
+
+	// Universal `n` activation (FR-1): the notes editor opens on every question tab
+	// (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
+	// 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
+	// neither swallowed earlier nor blocked by `blocksMultiToggle`.
+	if (data === NOTES_ACTIVATE_KEY) {
+		return { kind: "notes_enter" };
+	}
+
+	if (kb.matches(data, KEYBIND_UP)) {
+		return prevNavOnUp(state, runtime);
+	}
+	if (kb.matches(data, KEYBIND_DOWN)) {
+		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 (kb.matches(data, KEYBIND_CONFIRM)) {
+			// 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 (kb.matches(data, KEYBIND_CONFIRM)) {
+		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" };
+}

package/adapters/pi/extensions/ask-user-question/state/questionnaire-session.ts

@@ -0,0 +1,234 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/questionnaire-session.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, type Input, type OverlayHandle } from "@earendil-works/pi-tui";
+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 type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
+import { buildQuestionnaire } 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";
+import { type ApplyContext, type Effect, reduce } from "./state-reducer.js";
+
+// Module-level constant; reused for cursor-end mutations after setValue rehydration.
+// Ctrl-E → tui.editor.cursorLineEnd (public path; pi-tui keybindings.js:25-28).
+const CURSOR_END = "\x05";
+
+export interface QuestionnaireSessionConfig {
+	tui: { terminal: { columns: number; rows: number }; requestRender(): void };
+	theme: Theme;
+	params: QuestionParams;
+	itemsByTab: WrappingSelectItem[][];
+	done: (result: QuestionnaireResult) => void;
+	/** Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+	collapseKey: string;
+}
+
+export interface QuestionnaireSessionComponent {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+}
+
+function initialState(): QuestionnaireState {
+	return {
+		currentTab: 0,
+		optionIndex: 0,
+		inputMode: false,
+		notesVisible: false,
+		answers: new Map(),
+		multiSelectChecked: new Set(),
+		notesByTab: new Map(),
+		submitChoiceIndex: 0,
+		notesDraft: "",
+		collapsed: false,
+	};
+}
+
+/**
+ * Slim runtime: owns the canonical state cell, the input-buffer cell, the
+ * two-pass `notesVisible` dispatch loop, and the effect runner. State
+ * transitions go through the pure `reduce` reducer; UI fan-out goes through
+ * the `QuestionnairePropsAdapter` produced by `buildQuestionnaire`.
+ */
+export class QuestionnaireSession {
+	private state: QuestionnaireState = initialState();
+
+	private readonly questions: readonly QuestionData[];
+	private readonly isMulti: boolean;
+	private readonly itemsByTab: WrappingSelectItem[][];
+
+	private readonly notesInput: Input;
+	private readonly inlineInput: Input;
+	private readonly viewAdapter: QuestionnairePropsAdapter;
+	private readonly collapseKey: string;
+
+	/**
+	 * Overlay handle captured by `ctx.ui.custom`'s `onHandle` callback. Lets the session
+	 * call `setHidden(true/false)` so pi-tui's overlay stack reflects the collapsed state
+	 * and overlay-aware consumers (e.g. `pi-station`) can resume normal behaviour.
+	 */
+	private overlayHandle: OverlayHandle | undefined;
+
+	private readonly tui: QuestionnaireSessionConfig["tui"];
+	private readonly done: QuestionnaireSessionConfig["done"];
+	readonly component: QuestionnaireSessionComponent;
+
+	constructor(config: QuestionnaireSessionConfig) {
+		this.tui = config.tui;
+		this.done = config.done;
+		this.questions = config.params.questions;
+		this.isMulti = this.questions.length > 1;
+		this.itemsByTab = config.itemsByTab;
+		this.collapseKey = config.collapseKey;
+
+		const built = buildQuestionnaire({
+			tui: this.tui,
+			theme: config.theme,
+			questions: this.questions,
+			itemsByTab: this.itemsByTab,
+			isMulti: this.isMulti,
+			initialState: this.state,
+			getCurrentTab: () => this.state.currentTab,
+		});
+
+		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 = {
+			render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
+			invalidate: built.invalidate,
+			handleInput: (data) => this.dispatch(data),
+		};
+
+		this.viewAdapter.apply(this.state);
+	}
+
+	dispatch(data: string): void {
+		const action = routeKey(data, this.state, this.runtime());
+		if (action.kind === "ignore") {
+			this.handleIgnoreInline(data);
+			return;
+		}
+		this.commit(action);
+	}
+
+	private commit(action: QuestionnaireAction): void {
+		const result = reduce(this.state, action, this.applyContext());
+		this.state = result.state;
+		for (const effect of result.effects) this.runEffect(effect);
+		this.state = this.mirrorNotesDraft(this.state);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private mirrorNotesDraft(s: QuestionnaireState): QuestionnaireState {
+		const draft = this.notesInput.getValue();
+		return s.notesDraft === draft ? s : { ...s, notesDraft: draft };
+	}
+
+	private runEffect(effect: Effect): void {
+		switch (effect.kind) {
+			case "set_input_buffer":
+				this.inlineInput.setValue(effect.value);
+				this.inlineInput.handleInput(CURSOR_END);
+				return;
+			case "clear_input_buffer":
+				this.inlineInput.setValue("");
+				return;
+			case "set_notes_value":
+				this.notesInput.setValue(effect.value);
+				return;
+			case "set_notes_focused":
+				this.notesInput.focused = effect.focused;
+				return;
+			case "forward_notes_keystroke":
+				this.notesInput.handleInput(effect.data);
+				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);
+				return;
+			case "done":
+				this.done(effect.result);
+				return;
+		}
+	}
+
+	/**
+	 * Per-keystroke `ignore` fast path: delegates to the headless `inlineInput`
+	 * Input so bracketed-paste accumulator (`input.js:33-63`) and Kitty CSI-u
+	 * decode (`input.js:155-163`) take effect. Cursor is NOT force-reset here —
+	 * doing so would corrupt split-chunk pastes (a `\x05` byte mid-paste lands
+	 * verbatim in `pasteBuffer` and survives `handlePaste`'s narrow strip).
+	 * Cursor advances naturally via `insertCharacter` on typing/paste; cursor-
+	 * movement keys (Left/Right/Home/End/word-jumps) are now functional, with
+	 * the always-end visual cursor marker drawn independently by
+	 * `WrappingSelect.renderInlineInputRow`. `viewAdapter.apply` is called
+	 * directly without a reducer round-trip — preserves the D3 fast-path
+	 * latency profile from Phase 11.
+	 */
+	private handleIgnoreInline(data: string): void {
+		if (!this.state.inputMode) return;
+		this.inlineInput.handleInput(data);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private runtime(): QuestionnaireRuntime {
+		return {
+			keybindings: getKeybindings(),
+			inputBuffer: this.inlineInput.getValue(),
+			questions: this.questions,
+			isMulti: this.isMulti,
+			currentItem: this.currentItem(),
+			items: this.itemsByTab[this.state.currentTab] ?? [],
+			collapseKey: this.collapseKey,
+		};
+	}
+
+	private applyContext(): ApplyContext {
+		return {
+			questions: this.questions,
+			itemsByTab: this.itemsByTab,
+		};
+	}
+
+	private currentItem(): WrappingSelectItem | undefined {
+		const arr = this.itemsByTab[this.state.currentTab] ?? [];
+		return this.state.optionIndex < arr.length ? arr[this.state.optionIndex] : undefined;
+	}
+
+	/**
+	 * Setter for the overlay handle, called by `ctx.ui.custom`'s `onHandle` callback once
+	 * the TUI has created the overlay. Until this is called, `set_overlay_hidden` effects
+	 * are no-ops — the session still tracks `state.collapsed` for the view layer.
+	 */
+	setOverlayHandle(handle: OverlayHandle): void {
+		this.overlayHandle = handle;
+	}
+
+	/**
+	 * Public toggle used by the raw terminal input listener registered in `execute()`.
+	 * pi-tui does not route input to a hidden overlay's `component.handleInput`, so the
+	 * raw listener (which fires for terminal data regardless of overlay visibility)
+	 * reaches the session through this method instead of the dispatch path. Routed
+	 * through `commit` so the transition stays in the reducer and the overlay hide
+	 * happens via the `set_overlay_hidden` effect like every other side effect.
+	 */
+	toggleCollapsedExternal(): void {
+		this.commit({ kind: "toggle_collapsed" });
+	}
+}

package/adapters/pi/extensions/ask-user-question/state/row-intent.ts

@@ -0,0 +1,145 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/row-intent.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { QuestionData } from "../tool/types.js";
+import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
+
+/**
+ * Row kind discriminator. Single source of truth — derived from the runtime
+ * `WrappingSelectItem` union (`wrapping-select.ts:18-22`) so adding a new
+ * variant there forces a `ROW_INTENT_META` entry here (compile-time
+ * exhaustiveness via `Record<RowKind, …>`).
+ */
+export type RowKind = WrappingSelectItem["kind"];
+
+/**
+ * Sentinel kinds — the subset of `RowKind` representing protocol-driven rows
+ * (vs author-defined `option` rows). The auto-append walker, the reserved-label
+ * derivation, and `LABELS_BY_KIND` consumers iterate this list.
+ */
+export type SentinelKind = Exclude<RowKind, "option">;
+export const SENTINEL_KINDS: readonly SentinelKind[] = ["other", "next"];
+
+/**
+ * Per-kind static metadata. Pure data — no closures, no per-kind handler
+ * functions. Behavior-bearing branches (answer construction in
+ * `key-router.ts:69-99`, the Next-row render block in `multi-select-view.ts`,
+ * and the inline-Input render branch in `wrapping-select.ts`) keep their
+ * exhaustive switches and READ flags from this table.
+ *
+ * Adding a new sentinel:
+ *   1. Add the variant to `WrappingSelectItem` (`wrapping-select.ts:18-22`).
+ *   2. Add an entry here. Compile fails until both edits are present.
+ *   3. (If user-facing) author wherever the row is synthesized — typically
+ *      `buildItemsForQuestion` for main-list residents.
+ *
+ * Field semantics:
+ * - `label` — user-facing string. For `option` it's an empty placeholder
+ *   (per-instance labels come from `QuestionData.options[i].label`); every
+ *   sentinel uses its META entry as the single source of truth.
+ * - `reserved` — author-facing labels matching this string trigger
+ *   `reserved_label` at validation time. `RESERVED_LABEL_SET` is derived.
+ * - `livesInMainList` — true iff the row appears in `itemsByTab[i]`. Every
+ *   current sentinel lives in the main list (the `next` row is synthesized by
+ *   `sentinelsToAppend`).
+ * - `numbered` — true iff the row contributes to the main-list numbering.
+ *   Multi-select Next is the only `numbered=false` row that lives in the list.
+ * - `activatesInputMode` — true iff focusing the row should toggle
+ *   `state.inputMode = true`. Read by `state-reducer.ts` `nav` case.
+ * - `blocksMultiToggle` — in multiSelect mode, Space (and Enter-as-toggle)
+ *   on this row is suppressed. The Next sentinel is the only true.
+ * - `autoSubmitsInMulti` — in multiSelect mode, Enter on this row commits
+ *   the question (emits `multi_confirm`). The Next sentinel is the only true.
+ * - `autoAppendOnSingleSelect` — `buildItemsForQuestion` appends
+ *   this row when the question is single-select, regardless of whether any
+ *   option carries a `preview`. The "other" sentinel is the only true.
+ * - `autoAppendOnMultiSelect` — `buildItemsForQuestion` appends this row
+ *   when the question is multi-select. The `other` and `next` sentinels are both true.
+ */
+export interface RowIntentMeta {
+	label: string;
+	reserved: boolean;
+	livesInMainList: boolean;
+	numbered: boolean;
+	activatesInputMode: boolean;
+	blocksMultiToggle: boolean;
+	autoSubmitsInMulti: boolean;
+	autoAppendOnSingleSelect: boolean;
+	autoAppendOnMultiSelect: boolean;
+}
+
+export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
+	option: {
+		label: "",
+		reserved: false,
+		livesInMainList: true,
+		numbered: true,
+		activatesInputMode: false,
+		blocksMultiToggle: false,
+		autoSubmitsInMulti: false,
+		autoAppendOnSingleSelect: false,
+		autoAppendOnMultiSelect: false,
+	},
+	other: {
+		label: "Type something.",
+		reserved: true,
+		livesInMainList: true,
+		numbered: true,
+		activatesInputMode: true,
+		blocksMultiToggle: false,
+		autoSubmitsInMulti: false,
+		autoAppendOnSingleSelect: true,
+		autoAppendOnMultiSelect: true,
+	},
+	next: {
+		label: "Next",
+		reserved: true,
+		livesInMainList: true,
+		numbered: false,
+		activatesInputMode: false,
+		blocksMultiToggle: true,
+		autoSubmitsInMulti: true,
+		autoAppendOnSingleSelect: false,
+		autoAppendOnMultiSelect: true,
+	},
+};
+
+/**
+ * Kind-keyed label view. `option` is excluded — its label is per-instance,
+ * not per-kind. `types.ts#SENTINEL_LABELS` re-sources from here.
+ */
+export const LABELS_BY_KIND: { readonly [K in SentinelKind]: string } = {
+	other: ROW_INTENT_META.other.label,
+	next: ROW_INTENT_META.next.label,
+};
+
+/**
+ * Reserved-label set for runtime validation. Includes "Other" (a model-conditioned
+ * label that has no runtime kind) plus every sentinel with `reserved: true`.
+ */
+export const RESERVED_LABEL_SET: ReadonlySet<string> = new Set<string>([
+	"Other",
+	...SENTINEL_KINDS.filter((k) => ROW_INTENT_META[k].reserved).map((k) => ROW_INTENT_META[k].label),
+]);
+
+/**
+ * Walk the META table to synthesize sentinel rows for one question. The two
+ * append predicates are mutually exclusive in practice (`multiSelect` vs
+ * single-select) but the walker doesn't enforce that — adding a third bucket
+ * only requires a new META flag.
+ *
+ * Returns sentinel descriptors in declaration order of `SENTINEL_KINDS`. The
+ * caller wraps each with the `WrappingSelectItem` shape (kind + label).
+ */
+export function sentinelsToAppend(question: QuestionData): SentinelKind[] {
+	const out: SentinelKind[] = [];
+	for (const k of SENTINEL_KINDS) {
+		const meta = ROW_INTENT_META[k];
+		if (!meta.livesInMainList) continue;
+		if (question.multiSelect === true) {
+			if (meta.autoAppendOnMultiSelect) out.push(k);
+		} else {
+			if (meta.autoAppendOnSingleSelect) out.push(k);
+		}
+	}
+	return out;
+}

package/adapters/pi/extensions/ask-user-question/state/selectors/contract.ts

@@ -0,0 +1,26 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/state/selectors/contract.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { QuestionData } from "../../tool/types.js";
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { WrappingSelectItem } from "../../view/components/wrapping-select.js";
+import type { ActiveView, StatefulView } from "../../view/stateful-view.js";
+import type { TabComponents } from "../../view/tab-components.js";
+import type { QuestionnaireState } from "../state.js";
+
+export interface BindingContext {
+	readonly questions: readonly QuestionData[];
+	readonly itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+	readonly totalQuestions: number;
+	readonly activeView: ActiveView;
+	readonly inputBuffer: string;
+	readonly inputCursorOffset: number | undefined;
+	readonly activePreviewPane: StatefulView<PreviewPaneProps>;
+}
+
+export interface PerTabBindingContext extends BindingContext {
+	readonly tab: TabComponents;
+	readonly i: number;
+}
+
+export type GlobalSelector<P> = (state: QuestionnaireState, ctx: BindingContext) => P;
+export type PerTabSelector<P> = (state: QuestionnaireState, ctx: PerTabBindingContext) => P;