@cspeach/cli 0.9.0 → 1.1.0

package/dist/ui/text-input.js

@@ -0,0 +1,214 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * PasteSafeTextInput — drop-in replacement for `ink-text-input` (D29,
+ * "chewed words" during seed-session paste; 2026-06-12).
+ *
+ * ROOT CAUSE of the chewing, verified by repro test: Ink's App drains ALL
+ * pending stdin chunks in one synchronous loop (components/App.js
+ * `handleReadable`: `while ((chunk = stdin.read()) !== null) emit('input')`),
+ * and a large terminal paste arrives as MULTIPLE chunks. ink-text-input
+ * computes `nextValue = value.slice(0, cursor) + input + …` from the
+ * `value` PROP of the last committed render — a stale closure for every
+ * chunk after the first in the same tick. With chunks A then B, B's
+ * handler still sees the pre-A value, so A is silently dropped:
+ * `stdin.write('hello '); stdin.write('world')` → value `"world"`.
+ *
+ * FIX: mirror value + cursor in refs that are updated SYNCHRONOUSLY inside
+ * the input handler, so consecutive same-tick chunks compound. The refs
+ * re-sync from props on commit, so external value pushes (submit-clear,
+ * palette prefill) still win between keystrokes. This also fixes the
+ * sibling hazard: an Enter that lands in the same drain as the paste tail
+ * now submits the COMPLETE value instead of the stale prop.
+ *
+ * Rendering, cursor drawing, placeholder, and mask behaviour are vendored
+ * verbatim from ink-text-input v6 (MIT, © Vadim Demedes) minus
+ * `highlightPastedText` (Footer never used it).
+ */
+import { useState, useEffect, useRef } from 'react';
+import { Text, useInput } from 'ink';
+import chalk from 'chalk';
+/**
+ * Pure windowing core (exported for tests). Given the value length, the
+ * cursor position, the display budget (character cells) and whether the
+ * fake cursor is rendered, return the [start, end) slice of the value to
+ * display. Invariants:
+ *  - (end - start) + (cursor-at-end cell ? 1 : 0) <= budget
+ *  - start <= cursorOffset <= start + budget - 1 (cursor always visible)
+ *  - tail-biased: typing at the end shows the end of the value.
+ */
+export function computeDisplayWindow(valueLength, cursorOffset, budget, cursorVisible) {
+    if (!budget || budget <= 0)
+        return { start: 0, end: valueLength };
+    const virtualLength = valueLength + (cursorVisible ? 1 : 0); // trailing cursor cell
+    if (virtualLength <= budget)
+        return { start: 0, end: valueLength };
+    let start = virtualLength - budget; // default: show the tail
+    if (cursorOffset < start)
+        start = cursorOffset; // scrolled left past the window
+    const end = Math.min(valueLength, start + budget);
+    return { start, end };
+}
+export function PasteSafeTextInput({ value: originalValue, placeholder = '', focus = true, mask, showCursor = true, onChange, onSubmit, onPasteLines, maxDisplayWidth, }) {
+    const [cursorOffset, setCursorOffset] = useState((originalValue || '').length);
+    // The paste-safety core: synchronous mirrors of value + cursor. The
+    // input handler reads/writes THESE, never the (possibly stale) props.
+    const valueRef = useRef(originalValue);
+    const cursorRef = useRef(cursorOffset);
+    // Values we've sent through onChange whose prop echo hasn't been
+    // observed yet. Needed because passive effects flush LATE: with N
+    // same-tick chunks, the echo effect for chunk k can run AFTER the
+    // handler for chunk k+1, and blindly assigning `valueRef.current =
+    // originalValue` would rewind the mirror to a stale value (observed in
+    // the repro as words landing out of order). An echo — even a stale
+    // one — must never overwrite the mirror; only EXTERNAL pushes may.
+    const pendingEchoes = useRef([]);
+    // Re-sync the mirrors on EXTERNAL value pushes only (parent setValue('')
+    // after submit, palette prefill). Echoes of our own onChange — current
+    // or stale — are recognised via pendingEchoes and skipped: the mirror
+    // is already at or ahead of them.
+    useEffect(() => {
+        const echoIdx = pendingEchoes.current.indexOf(originalValue);
+        if (echoIdx !== -1) {
+            pendingEchoes.current.splice(0, echoIdx + 1);
+            return;
+        }
+        pendingEchoes.current = [];
+        valueRef.current = originalValue;
+        if (cursorRef.current > originalValue.length) {
+            cursorRef.current = originalValue.length;
+            setCursorOffset(originalValue.length);
+        }
+    }, [originalValue]);
+    // Clamp rendered cursor when the value shrinks under it (vendored
+    // semantic from ink-text-input's first effect).
+    useEffect(() => {
+        if (!focus || !showCursor)
+            return;
+        setCursorOffset((previous) => previous > originalValue.length ? originalValue.length : previous);
+    }, [originalValue, focus, showCursor]);
+    const value = mask ? mask.repeat(originalValue.length) : originalValue;
+    // Wave1 live-fix (Bug 1) — display-only horizontal window + control-char
+    // flattening. The mirrors, the props, and every handler above operate on
+    // the FULL value; only what's painted is windowed, so the row can never
+    // soft-wrap in the terminal (see maxDisplayWidth doc). Tabs are flattened
+    // to one space IN THE DISPLAY ONLY: string-width measures '\t' as 0 while
+    // terminals render up to 8 cells — the exact measurement drift that broke
+    // Ink's erase accounting live.
+    const cursorRendered = showCursor && focus;
+    const win = computeDisplayWindow(value.length, cursorOffset, maxDisplayWidth, cursorRendered);
+    const displayCursor = cursorOffset - win.start; // may equal display length (end cell)
+    // Left-clip marker: swap the first visible char for '…' (same cell
+    // count, so the budget still holds) unless the cursor sits on that cell.
+    const clipMarker = win.start > 0 && displayCursor !== 0;
+    const displayValue = (clipMarker ? '…' : '') +
+        value.slice(win.start + (clipMarker ? 1 : 0), win.end).replace(/\t/g, ' ');
+    let renderedValue = displayValue;
+    let renderedPlaceholder = placeholder ? chalk.grey(placeholder) : undefined;
+    // Fake cursor — vendored rendering from ink-text-input v6, over the
+    // windowed display string.
+    if (cursorRendered) {
+        renderedPlaceholder =
+            placeholder.length > 0
+                ? chalk.inverse(placeholder[0]) + chalk.grey(placeholder.slice(1))
+                : chalk.inverse(' ');
+        renderedValue = displayValue.length > 0 ? '' : chalk.inverse(' ');
+        let i = 0;
+        for (const char of displayValue) {
+            renderedValue += i === displayCursor ? chalk.inverse(char) : char;
+            i++;
+        }
+        if (displayValue.length > 0 && displayCursor === displayValue.length) {
+            renderedValue += chalk.inverse(' ');
+        }
+    }
+    useInput((input, key) => {
+        if (key.upArrow ||
+            key.downArrow ||
+            (key.ctrl && input === 'c') ||
+            key.tab ||
+            (key.shift && key.tab)) {
+            return;
+        }
+        if (key.return) {
+            // valueRef (not the prop) — so an Enter in the same stdin drain as
+            // the paste tail submits the complete line.
+            if (onSubmit)
+                onSubmit(valueRef.current);
+            return;
+        }
+        const currentValue = valueRef.current;
+        let nextCursorOffset = cursorRef.current;
+        let nextValue = currentValue;
+        // Task 7 — complete lines carved out of a newline-bearing paste
+        // chunk; reported to the parent AFTER the mirrors are updated.
+        let pasteLines = null;
+        if (key.leftArrow) {
+            if (showCursor)
+                nextCursorOffset--;
+        }
+        else if (key.rightArrow) {
+            if (showCursor)
+                nextCursorOffset++;
+        }
+        else if (key.backspace || key.delete) {
+            if (cursorRef.current > 0) {
+                nextValue =
+                    currentValue.slice(0, cursorRef.current - 1) +
+                        currentValue.slice(cursorRef.current, currentValue.length);
+                nextCursorOffset--;
+            }
+        }
+        else if (onPasteLines && (input.includes('\n') || input.includes('\r'))) {
+            // Task 7 — multi-line paste chunk. Normalise CRLF / bare CR
+            // (Windows Terminal converts pasted newlines to \r in raw mode),
+            // insert at the cursor as usual, then split at the LAST newline:
+            // everything before it is complete lines for the parent's
+            // continuation buffer; the tail fragment becomes the new value.
+            // Because the fragment (not the full paste) lands in the
+            // synchronous mirror, a follow-up chunk of the same drain
+            // compounds on the fragment — duplicate delivery of a completed
+            // line is structurally impossible, and every D29 mirror/echo
+            // mechanism below operates exactly as for a plain insert.
+            const cleanInput = input.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+            const combined = currentValue.slice(0, cursorRef.current) +
+                cleanInput +
+                currentValue.slice(cursorRef.current, currentValue.length);
+            const lastNl = combined.lastIndexOf('\n');
+            pasteLines = combined.slice(0, lastNl).split('\n');
+            nextValue = combined.slice(lastNl + 1);
+            // Cursor lands where the insertion ended, mapped into the fragment
+            // (0 when the paste ended on the newline itself).
+            nextCursorOffset = Math.max(0, cursorRef.current + cleanInput.length - (lastNl + 1));
+        }
+        else {
+            nextValue =
+                currentValue.slice(0, cursorRef.current) +
+                    input +
+                    currentValue.slice(cursorRef.current, currentValue.length);
+            nextCursorOffset += input.length;
+        }
+        if (nextCursorOffset < 0)
+            nextCursorOffset = 0;
+        if (nextCursorOffset > nextValue.length)
+            nextCursorOffset = nextValue.length;
+        // Synchronous mirror update FIRST — the next same-tick chunk builds
+        // on this, not on the stale render.
+        valueRef.current = nextValue;
+        cursorRef.current = nextCursorOffset;
+        setCursorOffset(nextCursorOffset);
+        if (pasteLines)
+            onPasteLines?.(pasteLines);
+        if (nextValue !== currentValue) {
+            // Register the outgoing value so its (possibly late) prop echo is
+            // recognised and never rewinds the mirror.
+            pendingEchoes.current.push(nextValue);
+            onChange(nextValue);
+        }
+    }, { isActive: focus });
+    return (_jsx(Text, { children: placeholder
+            ? value.length > 0
+                ? renderedValue
+                : renderedPlaceholder
+            : renderedValue }));
+}
+export default PasteSafeTextInput;

package/dist/ui/todo-emitter.js

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'node:events';
+/**
+ * UX Wave 2 / Task 4 — singleton update channel from the `todo_set` tool
+ * (producer) to `<App>` (consumer, Task 5: Ctrl+T panel + turn-status
+ * strip). Mirror of approvalEmitter: the tool emits, App subscribes in a
+ * useEffect and pushes the list into its state.
+ *
+ * Event contract (Task 5 renders from this):
+ *   todoEmitter.emit('update', todos)   // todos: TodoItem[]
+ *
+ * Fire-and-forget by design — unlike askQuestionEmitter there is no
+ * resolve callback because nothing about the tool result depends on the
+ * UI. The tool reaches this singleton via `ctx.todoEmitter` (Task 5):
+ * top-level entry points (repl.tsx, one-shot.ts) wire it into their
+ * ToolContext; agent_run's child ctx DELIBERATELY omits it — same seam
+ * as chunkEmitter — so a subagent's todo_set is fully suppressed and can
+ * never clobber the parent's panel. With no emitter on the ctx, or no
+ * listener attached (classic REPL, one-shot, headless), the tool behaves
+ * identically: state still lands on session.todos, only the live panel
+ * is absent.
+ *
+ * Never spawn a sibling Ink root for the panel — that fights the main
+ * <App> for stdout and corrupts the Ink frame.
+ */
+export const todoEmitter = new EventEmitter();

package/dist/ui/todo-panel.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+/**
+ * TodoPanel — UX Wave 2 / Task 5. The Ctrl+T overlay rendering the
+ * model-maintained task list (`todo_set` tool → session.todos). House
+ * style follows SessionTimeline: bordered box mounted above the Footer
+ * by <App>, closes on Esc / q — plus Ctrl+T itself (toggle; App's
+ * open-handler goes inactive while the panel is up, so the chord cannot
+ * double-fire).
+ *
+ * Row glyphs: ▣ completed (dim) · ▶ in_progress (peach, bold) ·
+ * □ pending. Every row is wrap="truncate-end" — Wave-1 rule: no
+ * dynamic-frame row may ever soft-wrap (wrapped rows break Ink's erase
+ * accounting and leak stale rows into scrollback).
+ *
+ * Lists longer than TODO_VISIBLE_ROWS get a scrolling window
+ * (CommandPalette pattern): ↑/↓ move the window, hidden counts show as
+ * "↑ N more" / "↓ N more". The initial window anchors the in_progress
+ * item ~3 rows from the top so the current step is visible on open.
+ */
+const PEACH = '#FFCBA4';
+export const TODO_VISIBLE_ROWS = 12;
+/** Pure header-counts formatter, exported for tests. */
+export function formatTodoCounts(todos) {
+    const done = todos.filter((t) => t.status === 'completed').length;
+    const active = todos.filter((t) => t.status === 'in_progress').length;
+    const open = todos.filter((t) => t.status === 'pending').length;
+    return `Tasks — ${done} done · ${active} active · ${open} open`;
+}
+export function TodoPanel({ todos, onClose }) {
+    const maxOffset = Math.max(0, todos.length - TODO_VISIBLE_ROWS);
+    // Anchor the initial window so the in_progress item sits ~3 rows from
+    // the top (CommandPalette's cursor rule, with the active item as cursor).
+    const [offset, setOffset] = useState(() => {
+        const idx = todos.findIndex((t) => t.status === 'in_progress');
+        if (idx <= 3)
+            return 0;
+        return Math.min(idx - 3, maxOffset);
+    });
+    useInput((input, key) => {
+        if (key.escape || input === 'q' || (key.ctrl && (input === 't' || input === 'T'))) {
+            onClose();
+            return;
+        }
+        if (key.upArrow)
+            setOffset((o) => Math.max(0, o - 1));
+        if (key.downArrow)
+            setOffset((o) => Math.min(maxOffset, o + 1));
+    });
+    const clamped = Math.min(offset, maxOffset);
+    const visible = todos.slice(clamped, clamped + TODO_VISIBLE_ROWS);
+    const below = Math.max(0, todos.length - (clamped + TODO_VISIBLE_ROWS));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 2, paddingY: 1, width: 72, children: [_jsx(Text, { bold: true, color: "cyan", wrap: "truncate-end", children: formatTodoCounts(todos) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [todos.length === 0 && (_jsx(Text, { dimColor: true, children: "(no tasks yet \u2014 the model maintains this list on multi-step work)" })), clamped > 0 && _jsxs(Text, { dimColor: true, children: ["  \u2191 ", clamped, " more"] }), visible.map((t, i) => {
+                        const key = `${clamped + i}`;
+                        if (t.status === 'completed') {
+                            return _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["\u25A3 ", t.text] }, key);
+                        }
+                        if (t.status === 'in_progress') {
+                            return _jsxs(Text, { color: PEACH, bold: true, wrap: "truncate-end", children: ["\u25B6 ", t.text] }, key);
+                        }
+                        return _jsxs(Text, { wrap: "truncate-end", children: ["\u25A1 ", t.text] }, key);
+                    }), below > 0 && _jsxs(Text, { dimColor: true, children: ["  \u2193 ", below, " more"] })] }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [todos.length > TODO_VISIBLE_ROWS ? '↑↓ scroll · ' : '', "Esc/q/Ctrl+T to close"] }) })] }));
+}

package/dist/ui/turn-status-emitter.js

@@ -12,9 +12,48 @@
 // listeners, and every call is a no-op.
 import { EventEmitter } from 'node:events';
 class TurnStatusEmitter extends EventEmitter {
-    state = { active: false, paused: false, label: '', startedAt: 0 };
+    state = { active: false, reserved: false, paused: false, label: '', startedAt: 0 };
+    /**
+     * BUG-3 (2026-07-05 live smoke) — the row vanished WHILE the model still
+     * worked. Root cause was the twin-turn overlap (BUG-2): turn 1 finished
+     * and its stop() cleared `active` while turn 2 was still running, because
+     * start/stop toggled a single boolean with no nesting. A depth counter
+     * makes stop() clear the row only when the OUTERMOST turn ends. In the
+     * BUG-2-fixed world turns are strictly sequential (depth only ever 0↔1),
+     * so this is defense-in-depth: any residual overlap (e.g. the /reroute
+     * mini-turn, or a future concurrency path) now degrades gracefully instead
+     * of blanking the liveness row.
+     */
+    depth = 0;
+    /**
+     * BUG-2b — mark a dispatch in-flight before the async pre-turn work runs.
+     * Invisible (no spinner); isBusy() reports it so the submit guard can
+     * queue a concurrent line as steering instead of starting a twin turn.
+     */
+    reserve() {
+        if (this.state.reserved)
+            return;
+        this.state = { ...this.state, reserved: true };
+        this.emit('change', this.state);
+    }
+    /** BUG-2b — release the pre-turn reservation (dispatch lifecycle ended). */
+    release() {
+        if (!this.state.reserved)
+            return;
+        this.state = { ...this.state, reserved: false };
+        this.emit('change', this.state);
+    }
+    /** "A turn is running OR imminent" — the predicate the submit/live-trigger
+     *  guards must use so the async pre-turn window (BUG-2b) is covered. */
+    isBusy() {
+        return this.state.active || this.state.reserved;
+    }
     start(label = 'thinking') {
-        this.state = { active: true, paused: false, label, startedAt: Date.now() };
+        // BUG-3 — nest instead of replace so an overlapping stop() can't blank
+        // the row (see the `depth` field doc). `...this.state` preserves the
+        // reserved flag set by reserve() at dispatch start.
+        this.depth++;
+        this.state = { ...this.state, active: true, paused: false, label, startedAt: Date.now() };
         this.emit('change', this.state);
     }
     /** Update the activity label; ignored when no turn is active. Clears pause —
@@ -40,9 +79,16 @@ class TurnStatusEmitter extends EventEmitter {
         this.emit('change', this.state);
     }
     stop() {
-        if (!this.state.active)
+        // BUG-3 — decrement the nesting depth; only clear the row when the
+        // outermost turn ends. Guard on depth (not `active`) and clamp at 0 so a
+        // spurious extra stop() is a harmless no-op. `reserved` is intentionally
+        // NOT cleared here — release() owns the pre-turn reservation lifecycle.
+        if (this.depth === 0)
+            return;
+        this.depth--;
+        if (this.depth > 0)
             return;
-        this.state = { active: false, paused: false, label: '', startedAt: 0 };
+        this.state = { ...this.state, active: false, paused: false, label: '', startedAt: 0 };
         this.emit('change', this.state);
     }
     snapshot() {

package/dist/ui/turn-status.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useEffect } from 'react';
 import { Text } from 'ink';
 import { turnStatusEmitter } from './turn-status-emitter.js';
@@ -11,6 +11,17 @@ function fmtElapsed(ms) {
         return `${s}s`;
     return `${Math.floor(s / 60)}m ${s % 60}s`;
 }
+/**
+ * Task 5 (ux-wave2) — cap for the in-progress-todo strip appended to the
+ * status row. The row already carries spinner + label + elapsed + hint;
+ * 40 chars of todo text keeps the whole line comfortably inside a normal
+ * terminal (and wrap="truncate-end" clips the rest regardless).
+ */
+export const TODO_STRIP_MAX = 40;
+/** ≤40 chars, '…' as the 40th when clipped. Exported for tests. */
+export function truncateTodoStrip(text) {
+    return text.length > TODO_STRIP_MAX ? `${text.slice(0, TODO_STRIP_MAX - 1)}…` : text;
+}
 /**
  * Persistent turn-status row (2026-06-07) — lives in the DYNAMIC Ink
  * frame just above the Footer, so it repaints with the frame and
@@ -27,7 +38,7 @@ function fmtElapsed(ms) {
  * cursor #25 class of bug came from a raw-stdout spinner; this
  * component cannot reproduce it). Guard: ink-cursor-invariant test.
  */
-export function TurnStatus() {
+export function TurnStatus({ inProgressTodo } = {}) {
     const [state, setState] = useState(turnStatusEmitter.snapshot());
     const [frame, setFrame] = useState(0);
     const [now, setNow] = useState(Date.now());
@@ -55,5 +66,9 @@ export function TurnStatus() {
     }, [state.active, state.paused]);
     if (!state.active || state.paused)
         return null;
-    return (_jsxs(Text, { children: [_jsxs(Text, { color: PEACH, children: [FRAMES[frame], " "] }), _jsx(Text, { children: state.label }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", fmtElapsed(now - state.startedAt), " \u00B7 ctrl+c to interrupt"] })] }));
+    // wrap="truncate-end" (wave1 live-fix, Bug 1): this row sits in the
+    // dynamic frame too — a long tool label must clip, never soft-wrap
+    // (wrapped dynamic-frame rows break Ink's erase accounting and leak
+    // stale rows into scrollback).
+    return (_jsxs(Text, { wrap: "truncate-end", children: [_jsxs(Text, { color: PEACH, children: [FRAMES[frame], " "] }), _jsx(Text, { children: state.label }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", fmtElapsed(now - state.startedAt), " \u00B7 ctrl+c to interrupt"] }), inProgressTodo ? (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: " \u00B7 " }), _jsxs(Text, { color: PEACH, children: ["\u25B6 ", truncateTodoStrip(inProgressTodo)] })] })) : null] }));
 }

package/dist/ui/widgets/ask-form.js

@@ -0,0 +1,242 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AskForm — UX Wave 2 / Task 2: the multi-question Ink form for
+ * ask_question v2 batched requests (the CC-parity flagship interaction).
+ *
+ * One request = 1..4 questions answered in a single visit. Visual
+ * de-clutter pass (2026-07, product-owner review): no border box — the
+ * chip row + indentation is the form's identity; the approval modal keeps
+ * its border deliberately (danger checkpoint):
+ *
+ *    ✓ env  name  style                       ← chips (two-space gaps)
+ *
+ *    Which naming style?
+ *    Used for every generated object
+ *    ▸ snake_case    lv_/lt_ prefixes
+ *      CamelCase     modern style
+ *      ✎ Other (type your own)
+ *      [ Submit ]                             ← ONLY once all answered
+ *    Enter pick · Tab next · Esc cancel       ← one context-sensitive hint
+ *
+ * Binding rules (Task-2 brief + de-clutter pass):
+ *  - Chips: one per question (`header`), two-space gaps (no pipes);
+ *    current = peach + bold, answered = dim with `✓ ` prefix,
+ *    unanswered = dim. ONE blank line separates the chip row from the
+ *    question text. Tab/→ next, Shift+Tab/← previous — all INSIDE the
+ *    form; App's global handlers (mode-cycle, `?`, `/`, `@`) are already
+ *    gated off by askQuestionPending.
+ *  - Options: arrow-key list, label + dim description, CommandPalette-style
+ *    scroll window; multiSelect ⇒ Space toggles ▣/□, Enter confirms the
+ *    set; single ⇒ Enter picks. ALWAYS a final `✎ Other (type your own)`
+ *    row → inline windowed TextInput; a typed answer flags `custom: true`.
+ *    freeText questions render the input directly (no escape row, and the
+ *    typed answer is the EXPECTED path — no custom flag, per the Task-1
+ *    AskFormAnswer contract: custom marks the Other ESCAPE only).
+ *  - Answering advances to the next UNANSWERED question (wrapping); when
+ *    none remain, focus lands on [ Submit ]. Enter there resolves ALL
+ *    answers at once, in question order. Tab back re-answers freely.
+ *    Single-question forms (n === 1) auto-submit on answer — no extra
+ *    Enter vs the v1 modal; the Submit affordance is multi-question
+ *    review only (review round M2).
+ *  - Esc — DELIBERATE DEVIATION from the brief's "Esc anywhere cancels",
+ *    reviewer-accepted (review round I1): on an OPTIONED question with
+ *    the Other input focused, Esc first returns focus to the options
+ *    list (the typed draft is KEPT in otherDrafts); Esc at options
+ *    level — and anywhere else, including freeText questions (no inner
+ *    level) — cancels the WHOLE form → { formId, answers: [],
+ *    cancelled: true } (v1 cancel contract shape per Task 1).
+ *  - Dynamic-frame safety (Wave-1 lesson): every row truncates (NOTHING
+ *    may wrap), options scroll, total height ≤ MAX_FORM_ROWS.
+ *  - No React state keyed on formId (collision caveat from review) — all
+ *    per-question state lives in arrays keyed by question INDEX within
+ *    this request object.
+ */
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+// Wave-1 windowed input — display can never wrap the row (D29 paste-safe).
+import TextInput from '../text-input.js';
+import { askHelpLine, useReclaimRawStdin } from './ask-question-modal.js';
+const PEACH = '#FFCBA4';
+/** Option rows visible at once — the rest scroll (CommandPalette style). */
+export const VISIBLE_OPTION_ROWS = 5;
+/**
+ * Hard cap on total rendered rows — pinned by test. Re-derived for the
+ * de-clutter pass (border gone = −2 rows; blank chip-gap row = +1; the
+ * Submit row only renders once all questions are answered).
+ *
+ * Worst case — all answered, user Tabbed BACK into a scrolled optioned
+ * question for review (Submit row visible below it):
+ *   chips + blank + question + context + "↑ more" + VISIBLE_OPTION_ROWS
+ *   + "↓ more" + Other + Submit + help = 14.
+ * Pre-completion the Submit row is absent → 13.
+ */
+export const MAX_FORM_ROWS = 14;
+/** Display window for the Other/freeText input — the row must never wrap. */
+const OTHER_INPUT_WIDTH = 50;
+export function AskForm({ request, onResolve }) {
+    useReclaimRawStdin();
+    const questions = request.questions;
+    const n = questions.length;
+    // Focus slots: 0..n-1 = questions, n = the [ Submit ] row (reachable
+    // only once every question has an answer).
+    const [focus, setFocus] = useState(0);
+    // Per-question state, keyed by question INDEX (never formId): option
+    // cursor (0..options.length — the last row is Other), multi-select
+    // sets, Other draft text, and the committed answer.
+    const [cursors, setCursors] = useState(() => questions.map(() => 0));
+    const [multiSel, setMultiSel] = useState(() => questions.map(() => new Set()));
+    const [otherDrafts, setOtherDrafts] = useState(() => questions.map(() => ''));
+    const [answers, setAnswers] = useState(() => questions.map(() => null));
+    const isSubmit = focus === n;
+    const q = isSubmit ? undefined : questions[focus];
+    const otherRow = q ? q.options.length : 0;
+    const cursor = isSubmit ? 0 : cursors[focus];
+    // The inline TextInput owns typing whenever the question is freeText or
+    // the cursor sits on the Other row. While it does, the form-level
+    // handler must NOT interpret space/Enter/←/→ (Ink delivers every key to
+    // every active useInput — there is no stopPropagation).
+    const otherFocused = q != null && (q.freeText || cursor === otherRow);
+    const allAnswered = answers.every((a) => a !== null);
+    const cancel = () => onResolve({ formId: request.formId, answers: [], cancelled: true });
+    const submit = (finalAnswers) => onResolve({
+        formId: request.formId,
+        // Question order, always — regardless of the order the user
+        // actually answered in.
+        answers: questions.map((qq, i) => ({
+            id: qq.id,
+            answer: finalAnswers[i]?.answer ?? null,
+            ...(finalAnswers[i]?.custom ? { custom: true } : {}),
+        })),
+    });
+    /**
+     * Commit an answer, then advance to the next UNANSWERED question
+     * (wrapping past the end); none left → focus [ Submit ] — except
+     * single-question forms, which resolve immediately (M2: no extra Enter
+     * vs the v1 modal).
+     */
+    const answerAndAdvance = (i, value, custom) => {
+        const next = answers.map((a, j) => j === i ? { answer: value, ...(custom ? { custom: true } : {}) } : a);
+        for (let step = 1; step <= n; step++) {
+            const j = (i + step) % n;
+            if (next[j] === null) {
+                setAnswers(next);
+                setFocus(j);
+                return;
+            }
+        }
+        if (n === 1) {
+            submit(next);
+            return;
+        }
+        setAnswers(next);
+        setFocus(n);
+    };
+    useInput((input, key) => {
+        if (key.escape) {
+            // Two-level Esc (I1, documented deviation — see file header): the
+            // Other input focused on an OPTIONED question → back to the options
+            // list, draft kept. freeText has no inner level; the options level
+            // cancels the whole form.
+            if (q && !q.freeText && otherFocused) {
+                setCursors((prev) => prev.map((c, j) => (j === focus ? otherRow - 1 : c)));
+                return;
+            }
+            cancel();
+            return;
+        }
+        // Chip navigation. Tab/Shift+Tab always work (TextInput ignores tab);
+        // ←/→ only while the inline text input doesn't own horizontal cursor
+        // movement.
+        const maxSlot = allAnswered ? n : n - 1;
+        if ((key.tab && !key.shift) || (!otherFocused && key.rightArrow)) {
+            setFocus((f) => (f >= maxSlot ? 0 : f + 1));
+            return;
+        }
+        if ((key.tab && key.shift) || (!otherFocused && key.leftArrow)) {
+            setFocus((f) => (f <= 0 ? maxSlot : f - 1));
+            return;
+        }
+        if (isSubmit) {
+            if (key.return && allAnswered)
+                submit(answers);
+            return;
+        }
+        if (!q)
+            return;
+        // ↑/↓ move the option cursor — also FROM the Other row back into the
+        // list (TextInput ignores vertical arrows, so no conflict).
+        if (!q.freeText) {
+            if (key.upArrow) {
+                setCursors((prev) => prev.map((c, j) => (j === focus ? Math.max(0, c - 1) : c)));
+                return;
+            }
+            if (key.downArrow) {
+                setCursors((prev) => prev.map((c, j) => (j === focus ? Math.min(otherRow, c + 1) : c)));
+                return;
+            }
+        }
+        // Everything below is typing territory while the Other input has focus.
+        if (otherFocused)
+            return;
+        if (q.multiSelect && input === ' ') {
+            const opt = q.options[cursor];
+            if (opt) {
+                setMultiSel((prev) => prev.map((s, j) => {
+                    if (j !== focus)
+                        return s;
+                    const nextSet = new Set(s);
+                    if (nextSet.has(opt.value))
+                        nextSet.delete(opt.value);
+                    else
+                        nextSet.add(opt.value);
+                    return nextSet;
+                }));
+            }
+            return;
+        }
+        if (key.return) {
+            if (q.multiSelect) {
+                const values = q.options
+                    .filter((o) => multiSel[focus].has(o.value))
+                    .map((o) => o.value);
+                if (values.length === 0)
+                    return; // nothing toggled yet — toggle or use Other
+                answerAndAdvance(focus, values.join(','));
+            }
+            else {
+                const opt = q.options[cursor];
+                if (opt)
+                    answerAndAdvance(focus, opt.value);
+            }
+        }
+    }, { isActive: true });
+    // CommandPalette-style scroll window over the options (the Other row is
+    // rendered separately and is always visible).
+    const opts = q?.options ?? [];
+    const winStart = Math.max(0, Math.min(cursor - 3, opts.length - VISIBLE_OPTION_ROWS));
+    const visible = opts.slice(winStart, winStart + VISIBLE_OPTION_ROWS);
+    const below = Math.max(0, opts.length - (winStart + VISIBLE_OPTION_ROWS));
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, flexShrink: 0, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { wrap: "truncate-end", children: questions.map((qq, i) => {
+                        const cur = i === focus;
+                        const done = answers[i] !== null;
+                        return (_jsxs(Text, { color: cur ? PEACH : undefined, bold: cur, dimColor: !cur, children: [i > 0 ? '  ' : '', done ? '✓ ' : '', qq.header ?? qq.id] }, qq.id));
+                    }) }) }), isSubmit ? (_jsx(Text, { dimColor: true, wrap: "truncate-end", children: "All questions answered \u2014 Tab/\u2190 to review, Enter to submit \u00B7 Esc cancel" })) : q ? (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, wrap: "truncate-end", children: q.question }), q.context && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: q.context }), !q.freeText && (_jsxs(_Fragment, { children: [winStart > 0 && _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u2191 ", winStart, " more"] }), visible.map((o, vi) => {
+                                const idx = winStart + vi;
+                                const isCur = !otherFocused && idx === cursor;
+                                const mark = q.multiSelect
+                                    ? (multiSel[focus].has(o.value) ? '▣ ' : '□ ')
+                                    : '';
+                                // v1 never renders the `recommended` flag — the convention
+                                // is skills writing "(recommended)" INTO the label. Render
+                                // the same dim convention only when the label lacks it.
+                                const rec = o.recommended === true && !/\brecommended\b/i.test(o.label);
+                                return (_jsxs(Text, { wrap: "truncate-end", color: isCur ? PEACH : undefined, bold: isCur, children: [isCur ? '▸ ' : '  ', mark, o.label, rec && _jsx(Text, { dimColor: true, children: " (recommended)" }), o.description && _jsxs(Text, { dimColor: true, children: ["  ", o.description] })] }, o.value));
+                            }), below > 0 && _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u2193 ", below, " more"] })] })), _jsxs(Box, { children: [q.freeText ? (_jsx(Text, { color: PEACH, wrap: "truncate-end", children: '> ' })) : (_jsxs(Text, { color: otherFocused ? PEACH : undefined, bold: otherFocused, wrap: "truncate-end", children: [otherFocused ? '▸ ' : '  ', "\u270E Other (type your own)", otherFocused ? ': ' : ''] })), otherFocused && (_jsx(TextInput, { value: otherDrafts[focus], onChange: (v) => setOtherDrafts((prev) => prev.map((d, j) => (j === focus ? v : d))), onSubmit: (v) => {
+                                    const trimmed = v.trim();
+                                    if (trimmed.length === 0)
+                                        return; // nothing typed — ignore
+                                    // custom marks the Other ESCAPE on an optioned question;
+                                    // freeText typing is the expected path (Task-1 contract).
+                                    answerAndAdvance(focus, trimmed, !q.freeText);
+                                }, maxDisplayWidth: OTHER_INPUT_WIDTH }))] })] })) : null, allAnswered && (_jsxs(Text, { wrap: "truncate-end", color: isSubmit ? PEACH : undefined, bold: isSubmit, dimColor: !isSubmit, children: [isSubmit ? '▸ ' : '  ', "[ Submit ]"] })), q && (_jsx(Text, { dimColor: true, wrap: "truncate-end", children: askHelpLine(q.freeText ? 'freeText' : q.multiSelect ? 'multi' : 'pick', { single: n === 1 }) }))] }));
+}