@cspeach/cli 0.9.0 → 1.0.0

package/dist/renderer/notices.js

@@ -0,0 +1,64 @@
+/**
+ * Notice rendering — the 'warn' / 'info' side-channel (battery B2 fix).
+ *
+ * Tool handlers emit user-facing notices on the SAME EventEmitter that
+ * carries 'chunk' stream data:
+ *
+ *   ctx.chunkEmitter?.emit('warn', msg)   — user-actionable notices
+ *                                           (e.g. "ignoring transport=X,
+ *                                           object locked in Y")
+ *   ctx.chunkEmitter?.emit('info', msg)   — dim, non-fatal diagnostics
+ *                                           (e.g. "snapshot ✓", lookup
+ *                                           fallback traces)
+ *
+ * Before this module existed those events were NO-OPS in the live REPL:
+ * the Ink Body only consumed 'chunk', and the classic/one-shot paths never
+ * put a chunkEmitter on the ToolContext at all. resolveWriteTransport's
+ * carefully-worded Rule 9 notices (D15/D20) were invisible.
+ *
+ * Two consumers, one formatter:
+ *   - Ink:      ui/body.tsx subscribes 'warn'/'info' and pushes
+ *                formatNoticeLine(...) through the SAME chunk batcher, so
+ *                ordering relative to surrounding chunks is preserved.
+ *   - classic / one-shot: createClassicOutputEmitter() returns an emitter
+ *                whose listeners write straight to stdout. repl.tsx
+ *                (classic branch) and one-shot.ts put it on ctx.chunkEmitter.
+ *
+ * Deliberately NOT wired for subagents (tools/subagent/agent_run.ts):
+ * their ctx.chunkEmitter stays undefined so child-turn notices remain
+ * muted — exactly the pre-existing contract pinned in agent_run.test.ts.
+ */
+import chalk from 'chalk';
+import { EventEmitter } from 'node:events';
+/**
+ * Format one notice as a single terminal line (trailing newline included).
+ * Multi-line messages are collapsed to one line — notices are glanceable
+ * margin notes, not documents; anything long belongs in the tool result.
+ *
+ *   warn → yellow  "  ⚠ message"
+ *   info → dim     "  · message"
+ */
+export function formatNoticeLine(level, message) {
+    const oneLine = message.replace(/\s*\r?\n\s*/g, ' ').trim();
+    if (level === 'warn')
+        return chalk.yellow(`  ⚠ ${oneLine}`) + '\n';
+    return chalk.dim(`  · ${oneLine}`) + '\n';
+}
+/**
+ * Build the output emitter for the NON-Ink paths (classic REPL, one-shot).
+ *
+ * Listeners:
+ *   'chunk' → written verbatim (already-formatted stream text — e.g. the
+ *             verify-chain line emitted by write tools)
+ *   'warn'  → formatNoticeLine('warn', …)
+ *   'info'  → formatNoticeLine('info', …)
+ *
+ * The `write` sink defaults to process.stdout — injectable for tests.
+ */
+export function createClassicOutputEmitter(write = (s) => process.stdout.write(s)) {
+    const emitter = new EventEmitter();
+    emitter.on('chunk', (s) => write(s));
+    emitter.on('warn', (msg) => write(formatNoticeLine('warn', msg)));
+    emitter.on('info', (msg) => write(formatNoticeLine('info', msg)));
+    return emitter;
+}

package/dist/renderer/progress-chatter.js

@@ -92,6 +92,10 @@ const MESSAGES = {
         'Reserving a transport request…',
         'Asking SAP for a fresh TR…',
     ],
+    sap_transport_for_object: [
+        'Checking who owns {object_name}…',
+        'Looking for an owning transport…',
+    ],
     sap_transport_list: [
         'Listing open transports…',
         'Finding modifiable TRs…',
@@ -156,6 +160,10 @@ const MESSAGES = {
         'Publishing service binding…',
         'Asking SAP to expose the OData endpoint…',
     ],
+    sap_service_binding_unpublish: [
+        'Unpublishing service binding…',
+        'Asking SAP to remove the OData endpoint…',
+    ],
 };
 const FALLBACK_MESSAGES = [
     'Working on it…',

package/dist/renderer/tool-widget.js

@@ -61,7 +61,7 @@ export function renderToolCallTop(params) {
         else
             process.stdout.write(s);
     };
-    const summary = argSummary(name, args);
+    const summary = summariseToolArgs(name, args);
     const wrapped = summary ? chalk.gray('(') + chalk.gray(summary) + chalk.gray(')') : '';
     const line = `${peach('⏺')} ${chalk.bold(name)}${wrapped}`;
     write('\n' + line + '\n');
@@ -136,7 +136,7 @@ function startSpinnerWithVerbs(params, verbs, defaultVerb) {
     return { stop: stopFn };
 }
 export function renderToolCallBottom(params) {
-    const { durationMs, isError, resultSummary, chunkEmitter } = params;
+    const { durationMs, isError, resultSummary, chunkEmitter, name, args } = params;
     const write = (s) => {
         if (chunkEmitter)
             chunkEmitter.emit('chunk', s);
@@ -144,15 +144,26 @@ export function renderToolCallBottom(params) {
             process.stdout.write(s);
     };
     const icon = isError ? chalk.red('✗') : chalk.green('✓');
+    // Label: plain (not bold — the top line keeps visual primacy) name +
+    // dim arg summary, mirroring the top-line shape so orphaned rows still
+    // read as "which tool, on what object".
+    let label = '';
+    if (name) {
+        const summary = summariseToolArgs(name, args ?? {});
+        const wrapped = summary ? chalk.gray('(') + chalk.gray(summary) + chalk.gray(')') : '';
+        label = ` ${name}${wrapped}`;
+    }
     const detailRaw = resultSummary ? truncate(resultSummary, RESULT_SUMMARY_MAX) : '';
     const detail = detailRaw
         ? (isError ? chalk.red(detailRaw) : chalk.gray(detailRaw))
         : '';
     const timing = chalk.dim(formatDuration(durationMs));
     const sep = chalk.dim('·');
-    let line = `  ${peach('⎿')} ${icon}`;
+    let line = `  ${peach('⎿')} ${icon}${label}`;
     if (detail)
         line += ` ${detail} ${sep} ${timing}`;
+    else if (label)
+        line += ` ${sep} ${timing}`;
     else
         line += ` ${timing}`;
     write(line + '\n');
@@ -162,8 +173,11 @@ export function renderToolCallBottom(params) {
  * arguments. Per-tool aware: pulls LLM-supplied summary first, then the
  * common (name, type, package) triple, then specific keys for known tools.
  * Falls back to a truncated JSON dump.
+ *
+ * Exported (D29) so the bottom result row can self-identify with the same
+ * summary the top line used.
  */
-function argSummary(toolName, args) {
+export function summariseToolArgs(toolName, args) {
     if (!args || Object.keys(args).length === 0)
         return '';
     const a = args;

package/dist/renderer/tty.js

@@ -25,6 +25,36 @@ export function setRenderingOverride(mode) {
 export function getRenderingOverride() {
     return renderingOverride;
 }
+/**
+ * B5 (2026-06-11) — headless answer policy signal.
+ *
+ * "Headless" means NO human can answer a prompt: stdin will never deliver
+ * an answer, so any inquirer/readline wait blocks forever (battery S2 Pass A
+ * stalled on exactly this — defect D1). Consumers (ask_question, the save
+ * hook, request_approval) branch to auto-answer / fail-fast policies instead
+ * of prompting.
+ *
+ * Decision order:
+ *   1. Explicit override — runOneShot() sets `true` at startup because
+ *      one-shot is a single non-interactive turn by design (CI parity:
+ *      the same invocation must behave identically piped or from a
+ *      terminal). Tests set/clear it directly.
+ *   2. Fallback — stdin is not a TTY. Covers piped/redirected invocations
+ *      that never went through runOneShot. stdin (not stdout) is the right
+ *      floor: prompts BLOCK on stdin; piping only stdout still leaves a
+ *      human able to answer.
+ */
+let headlessOverride = null;
+/** Set (or clear with null) the explicit headless override. */
+export function setHeadlessOverride(v) {
+    headlessOverride = v;
+}
+/** True when no human can answer prompts — see setHeadlessOverride. */
+export function isHeadless() {
+    if (headlessOverride !== null)
+        return headlessOverride;
+    return process.stdin.isTTY !== true;
+}
 /**
  * True when the Ink UI frame should be mounted.
  *
@@ -32,8 +62,17 @@ export function getRenderingOverride() {
  *   1. If override === 'classic', never use Ink (explicit opt-out)
  *   2. If override === 'ink', use Ink when a TTY is available; otherwise
  *      fall back — Ink cannot render on a pipe regardless of user preference
- *   3. If override === 'auto' (default), use Ink when interactive TTY +
- *      not one-shot + CI=unset
+ *   3. If override === 'auto' (default), use Ink when interactive TTY on
+ *      BOTH stdout and stdin + not one-shot + CI=unset
+ *
+ * UX-5 review C1 (2026-06-12): the auto branch must also require
+ * `process.stdin.isTTY` — Ink mounts raw-mode key handling on stdin, and a
+ * piped stdin (`"/cost`n/exit" | cspeach`) cannot enter raw mode. Worse,
+ * mounting Ink there bypassed the classic loop's early-line buffer
+ * (UX-5 #5), so every piped line was dropped. Piped-stdin invocations now
+ * take the classic path even when stdout is a terminal. The explicit
+ * `ui.rendering = 'ink'` override (branch 2) deliberately keeps its
+ * stdout-only floor — that's the user's explicit choice.
  *
  * v0.3+: pipeline.ts and approvals/render.ts branch on this.
  */
@@ -42,8 +81,8 @@ export function shouldUseInk() {
         return false;
     if (renderingOverride === 'ink')
         return isTTY();
-    // auto
-    return isTTY() && !isOneShot() && !process.env['CI'];
+    // auto — stdin must be a TTY too (raw-mode capable, no piped lines to drop)
+    return isTTY() && process.stdin.isTTY === true && !isOneShot() && !process.env['CI'];
 }
 /**
  * Stub for v0.3 Windows ConPTY / CI TTY hinting.

package/dist/renderer/verify-chain.js

@@ -0,0 +1,77 @@
+/**
+ * Verify-chain line — one compact row per completed SAP write summarizing
+ * the Forge-Rule pipeline the tool actually ran (tour slide-7 alignment):
+ *
+ *   ① snapshot ✓ ② written ✓ ③ syntax ✓ ④ activate pending
+ *
+ * HONESTY CONTRACT: every segment is derived from the tool's real result —
+ * never synthesized. States render truthfully:
+ *   - snapshot 'new_object'  → "① snapshot – (new object)" (genuine ADT 404 —
+ *     nothing to save; NEVER used for other read failures)
+ *   - snapshot 'source_read_failed' → "① snapshot – (no source read: <msg>)" —
+ *     the pre-write read failed for a non-404 reason; the object may exist
+ *     but there is no recovery copy. Hard-gate tools block instead of
+ *     emitting this; it only appears on soft (best-effort) gates.
+ *   - snapshot 'best_effort_failed' → "① snapshot – (skipped)" (write tools
+ *     where the gate is soft, e.g. class includes)
+ *   - syntax fail → "③ syntax ✗ (L12: MESSAGE …)" AND no ④ at all —
+ *     activation is blocked, so we don't show a fake pending step
+ *   - syntax 'not_checked' → "③ syntax – (checked at activation)" —
+ *     sap_set_class_include has no standalone syntax gate
+ *   - ④ is always 'pending', never '✓': activation is a SEPARATE tool call
+ *     (sap_activate); these write tools never activate.
+ *
+ * Consumed by the write tools in tools/sap-write.ts, emitted on the
+ * 'chunk' channel so it lands between the ⏺ dispatch line and the ⎿
+ * result row in both renderers.
+ */
+import chalk from 'chalk';
+const pass = (s) => `${s} ${chalk.green('✓')}`;
+const fail = (s, detail) => `${s} ${chalk.red('✗')}${detail ? ' ' + chalk.red(`(${detail})`) : ''}`;
+const skip = (s, why) => chalk.dim(`${s} – (${why})`);
+const ERROR_DETAIL_MAX = 60;
+const SNAPSHOT_DETAIL_MAX = 40;
+const truncate = (s, max) => {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.substring(0, max - 1) + '…' : flat;
+};
+/**
+ * Build the chain line (no trailing newline). Returns the full line
+ * including the two-space indent that aligns with the ⎿ result row.
+ */
+export function buildWriteChainLine(input) {
+    const parts = [];
+    // ① snapshot
+    if (input.snapshot === 'taken')
+        parts.push(pass('① snapshot'));
+    else if (input.snapshot === 'new_object')
+        parts.push(skip('① snapshot', 'new object'));
+    else if (input.snapshot === 'source_read_failed') {
+        // Honest: the read failed — we do NOT know the object is new, and there
+        // is no recovery copy. Never render this as "(new object)".
+        const why = input.snapshotDetail
+            ? `no source read: ${truncate(input.snapshotDetail, SNAPSHOT_DETAIL_MAX)}`
+            : 'no source read';
+        parts.push(skip('① snapshot', why));
+    }
+    else
+        parts.push(skip('① snapshot', 'skipped'));
+    // ② written
+    parts.push(input.written ? pass('② written') : fail('② written'));
+    // ③ syntax (+ ④ activate, which only exists when activation is possible)
+    if (input.syntax === 'not_checked') {
+        parts.push(skip('③ syntax', 'checked at activation'));
+        parts.push(chalk.dim('④ activate pending'));
+    }
+    else if (input.syntax.ok) {
+        parts.push(pass('③ syntax'));
+        parts.push(chalk.dim('④ activate pending'));
+    }
+    else {
+        const first = (input.syntax.errors[0] ?? 'syntax errors').replace(/\s+/g, ' ').trim();
+        const detail = first.length > ERROR_DETAIL_MAX ? first.substring(0, ERROR_DETAIL_MAX - 1) + '…' : first;
+        parts.push(fail('③ syntax', detail));
+        // No ④ — activation is blocked; rendering a pending step would lie.
+    }
+    return '  ' + parts.join('  ');
+}

package/dist/repl/at-picker.js

@@ -17,24 +17,75 @@
  * without screen takeover, Enter when they want a full search-as-you-type
  * picker. Same backing data, different UI.
  */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { search } from '@inquirer/prompts';
 import { withInquirer } from './inquirer-guard.js';
 import { inquirerTheme } from './inquirer-theme.js';
-import { ensureWorkspaceSync, listProjectFilesSync } from '../projects/workspace.js';
+import { ensureWorkspaceSync, listProjectFilesSync, isAttachableFilename } from '../projects/workspace.js';
 const CANCEL_VALUE = '__cspeach_cancel__';
 /**
  * 2026-06-06 (Ink picker parity): workspace listing + substring filter,
  * exported so the Ink FilePalette shares the same data + seeding
  * semantics as this classic inquirer picker.
+ *
+ * Bug #4 (2026-06-15): the listing is the UNION of
+ *   - all workspace files (.cspeach.json envelopes + .txt/.md/.docx/.pdf), AND
+ *   - top-level .txt/.md/.docx/.pdf files in the current working directory.
+ * A spec file dropped next to the project (the common case) lives in the
+ * cwd, never in .cspeach/, so without the cwd half the picker was empty.
+ *
+ * Deduped by filename — when a name exists in both, the workspace entry
+ * wins. Non-recursive over the cwd; the .cspeach subfolder and any
+ * dotfiles/dirs are skipped. SYNCHRONOUS by contract (the Ink palette and
+ * pendingAtTokenPrefix call it sync). `cwd` / `workspace` are injectable
+ * for tests; the zero-arg call resolves both from the environment.
  */
-export function listWorkspaceFileChoices() {
+export function listWorkspaceFileChoices(opts) {
+    const out = [];
+    const seen = new Set();
+    // Workspace half (takes precedence on name collisions).
+    try {
+        const ws = opts?.workspace ?? ensureWorkspaceSync();
+        for (const f of listProjectFilesSync(ws)) {
+            if (seen.has(f.filename))
+                continue;
+            seen.add(f.filename);
+            out.push({ filename: f.filename, mtimeMs: f.mtimeMs });
+        }
+    }
+    catch {
+        // fall through — still return whatever the cwd half yields
+    }
+    // cwd half — top-level .txt/.md/.docx/.pdf only. Never throws.
+    const cwd = opts?.cwd ?? process.cwd();
     try {
-        const ws = ensureWorkspaceSync();
-        return listProjectFilesSync(ws).map((f) => ({ filename: f.filename, mtimeMs: f.mtimeMs }));
+        for (const name of readdirSync(cwd)) {
+            if (name.startsWith('.'))
+                continue; // dotfiles/dirs (incl. .cspeach)
+            if (!isAttachableFilename(name))
+                continue;
+            if (seen.has(name))
+                continue; // workspace already has it
+            const full = join(cwd, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            seen.add(name);
+            out.push({ filename: name, mtimeMs: stat.mtimeMs });
+        }
     }
     catch {
-        return [];
+        // unreadable cwd — return just the workspace list
     }
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return out;
 }
 /** Substring filter; empty prefix returns everything. */
 export function filterFileChoices(prefix, all) {
@@ -126,8 +177,10 @@ export function pendingAtTokenPrefix(trimmed, knownFilenames) {
         }
         else {
             try {
-                const ws = ensureWorkspaceSync();
-                const files = listProjectFilesSync(ws);
+                // Bug #4: check the MERGED listing (workspace + cwd text files),
+                // not workspace-only, so an exact `@spec.txt` for a cwd file
+                // submits directly instead of re-opening the picker.
+                const files = listWorkspaceFileChoices();
                 const exact = files.some((f) => f.filename === prefix);
                 if (exact)
                     return null;

package/dist/repl/builtin-commands.js

@@ -0,0 +1,37 @@
+/**
+ * Built-in (non-skill) slash commands — the single source of truth.
+ *
+ * Extracted from slash-picker.ts (2026-06-11) so the router layer
+ * (src/router/classifier.ts) can distinguish "user typed a builtin with
+ * arguments" (e.g. `/help me`) from "user typed an unknown skill"
+ * WITHOUT importing the inquirer-backed picker module. Pure data — no
+ * runtime dependencies.
+ */
+export const BUILTIN_ENTRIES = [
+    { name: '/cancel', description: 'Cancel the current pre-filled command, return to a clean prompt' },
+    { name: '/cost', description: 'Show this session\'s API spend so far ($ + token breakdown)' },
+    { name: '/compact', description: 'Summarise older turns into a compact context block — cuts subsequent turn cost by 80-90%' },
+    { name: '/exit', description: 'Exit CSPeach' },
+    { name: '/quit', description: 'Exit CSPeach (alias)' },
+    { name: '/help', description: 'Show all skills and commands' },
+    { name: '/skills', description: 'Show all skills (alias)' },
+    { name: '/new', description: 'Reset routing — next prompt is classified afresh' },
+    { name: '/reset', description: 'Reset routing (alias)' },
+    { name: '/ui', description: 'View or change rendering mode (auto / ink / classic)' },
+    { name: '/reroute', description: 'Re-dispatch the previous prompt to a different skill' },
+    { name: '/transport', description: 'View or set the active transport for this session' },
+    { name: '/safety-mode', description: 'Toggle structured Forge Rule confirmation cards (on / off / status)' },
+];
+/**
+ * Builtin command heads for routing checks. Superset of BUILTIN_ENTRIES:
+ * `/files` is a real REPL builtin (repl.tsx handles it in both paths) but
+ * is deliberately absent from the picker catalogue, so it's added here.
+ */
+const BUILTIN_HEADS = new Set([
+    ...BUILTIN_ENTRIES.map((e) => e.name),
+    '/files',
+]);
+/** True when `head` (e.g. '/help', as typed, any case) is a builtin command. */
+export function isBuiltinCommandHead(head) {
+    return BUILTIN_HEADS.has(head.toLowerCase());
+}

package/dist/repl/early-line-buffer.js

@@ -0,0 +1,68 @@
+/**
+ * Early-line buffer for piped-stdin REPL runs — UX-5 #5 (2026-06-12).
+ *
+ * The bug (found 2026-06-11): lines piped into the classic REPL
+ * (`"/cost`n/exit" | cspeach`) arrive on the readline BEFORE the loop's
+ * first rl.question() is pending. Node's readline only routes a line to a
+ * question callback when one is registered; otherwise it emits the 'line'
+ * EVENT — which nobody consumed, so every early line was silently dropped
+ * (even /cost never dispatched). stdin EOF then closed the readline and
+ * the old 'close' handler hard-exited. This blocked CI-driven multi-phase
+ * plan runs entirely.
+ *
+ * Fix shape:
+ *   - attach a 'line' listener at readline creation that QUEUES lines
+ *     arriving while no question is pending (readline emits 'line' only
+ *     in that case — a pending question consumes the line directly);
+ *   - the REPL loop drains this queue before calling rl.question;
+ *   - on stdin EOF ('close') the buffer flips `closed` and the loop keeps
+ *     processing queued lines before exiting (the repl.tsx close handler
+ *     no longer hard-exits in piped mode);
+ *   - the FIRST piped line gets a UTF-8 BOM strip — PowerShell pipes
+ *     inject one, which used to corrupt the first command head.
+ *
+ * Only attached when stdin is NOT a TTY (see repl.tsx): in interactive
+ * mode, type-ahead during a turn should keep its existing
+ * behaviour rather than silently becoming queued commands.
+ */
+/** Strip a single leading UTF-8 BOM (PowerShell pipes inject one). */
+export function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+/**
+ * Attach the queueing listeners to `rl` and return the buffer handle.
+ * Call once, immediately after readline creation, BEFORE any awaits —
+ * piped data starts flowing on the next tick.
+ */
+export function attachEarlyLineBuffer(rl) {
+    const queue = [];
+    let firstLine = true;
+    let isClosed = false;
+    rl.on('line', (l) => {
+        let line = String(l);
+        if (firstLine) {
+            line = stripBom(line);
+            firstLine = false;
+        }
+        queue.push(line);
+    });
+    rl.on('close', () => {
+        isClosed = true;
+    });
+    return {
+        size: () => queue.length,
+        shift: () => queue.shift(),
+        closed: () => isClosed,
+    };
+}
+/**
+ * Inert buffer for interactive (TTY) runs — keeps the repl.tsx loop free
+ * of `isTTY` branches at every drain site.
+ */
+export function noopEarlyLineBuffer() {
+    return {
+        size: () => 0,
+        shift: () => undefined,
+        closed: () => false,
+    };
+}

package/dist/repl/inquirer-guard.js

@@ -28,6 +28,50 @@
  */
 import { clearActiveSpinner } from '../renderer/tool-widget.js';
 let state = null;
+/**
+ * UX-5 #4 (2026-06-12) — sequence-scoped (debounced) release.
+ *
+ * Failure mode this fixes: between BACK-TO-BACK inquirer prompts fired by
+ * the SAME handler (safety-confirm's two-step select, ask_question's
+ * select → custom-input follow-up, /files step 1 → step 2), the old
+ * per-prompt release resumed the outer readline the instant prompt N
+ * finished — readline repainted its prompt with a stale history/buffer
+ * entry for a frame — and then prompt N+1 paused it again. The user saw
+ * the old line flash between the two pickers.
+ *
+ * Scope note (M1, 2026-06-12): consecutive ask_question TOOL calls are
+ * separated by a full LLM round-trip (seconds apart) — the 50ms debounce
+ * neither covers nor needs to cover those; readline legitimately resumes
+ * between turns. The debounce only spans same-handler prompt sequences.
+ *
+ * Fix shape: the release (rl.resume + suppress-clear) is DEFERRED by
+ * RELEASE_DEBOUNCE_MS. If another withInquirer starts inside that window
+ * (an ask SEQUENCE), the pending release is cancelled and the outer
+ * prompt stays parked across the whole sequence — no repaint between
+ * prompts. Only the final prompt's release actually fires.
+ *
+ * Note: this is a CLASSIC-path concern only. Under Ink, ask_question /
+ * approval render through the Ink-native emitter modals (see
+ * tools/ask-question.ts shouldUseInk branch) and registerReadline is
+ * never called, so withInquirer is a pass-through there.
+ *
+ * The suppress flag intentionally stays TRUE during the debounce window —
+ * any spurious 'close' inquirer emits on release is still swallowed,
+ * which is strictly safer than the old nextTick clearing.
+ */
+// 50ms (M4 rationale): covers same-tick and next-macrotask prompt chaining
+// with ~3 frames of margin (one terminal frame ≈ 16ms) while staying far
+// below human-perceptible delay before the outer prompt repaints.
+export const RELEASE_DEBOUNCE_MS = 50;
+let pendingRelease = null;
+/** Re-entrancy depth — release is scheduled only when the OUTERMOST call exits. */
+let activeDepth = 0;
+function cancelPendingRelease() {
+    if (pendingRelease) {
+        clearTimeout(pendingRelease);
+        pendingRelease = null;
+    }
+}
 /**
  * Called by repl.tsx once the main readline is created. The `setSuppress`
  * callback must flip the same boolean the readline 'close' handler
@@ -38,6 +82,8 @@ export function registerReadline(rl, setSuppress) {
 }
 /** Clear the guard — call when the REPL is shutting down. */
 export function unregisterReadline() {
+    cancelPendingRelease();
+    activeDepth = 0;
     state = null;
 }
 /**
@@ -66,6 +112,12 @@ export async function withInquirer(fn) {
     // which collides with inquirer's prompt rendering — visible as ghost-text
     // and a cursor that hides under the rotating frame while the user types.
     clearActiveSpinner();
+    // UX-5 #4 — continuing an ask SEQUENCE: a release from the previous
+    // prompt is still pending, so cancel it. The readline stays parked
+    // (paused + close-suppressed) across the gap — no stale-line repaint
+    // between consecutive prompts.
+    cancelPendingRelease();
+    activeDepth++;
     // 2026-05-08: snapshot stdin 'data' / 'keypress' listeners BEFORE the
     // inquirer prompt runs. Some inquirer widgets (notably `search`, used
     // by /files step 1) strip ALL listeners on cleanup — including
@@ -120,11 +172,24 @@ export async function withInquirer(fn) {
         // Order matters here:
         //  1. resume stdin so the event loop stays referenced (otherwise the
         //     next rl.question prints its prompt and the process exits).
-        //  2. resume the readline so it accepts new input.
-        //  3. defer the suppress-clear so the spurious 'close' that inquirer
-        //     synchronously emits on release is still ignored.
+        //  2. SCHEDULE the readline resume + suppress-clear instead of doing
+        //     them inline (UX-5 #4). If another inquirer prompt opens within
+        //     RELEASE_DEBOUNCE_MS — an ask sequence — the entry above cancels
+        //     this timer and the outer readline never repaints between
+        //     prompts. The timer is deliberately NOT unref'd: it must hold
+        //     the event loop open across the gap.
+        //  3. inside the deferred release, still defer the suppress-clear by
+        //     one tick so the spurious 'close' that inquirer synchronously
+        //     emits on release is ignored.
         process.stdin.resume();
-        rl.resume();
-        process.nextTick(() => setSuppress(false));
+        activeDepth = Math.max(0, activeDepth - 1);
+        if (activeDepth === 0) {
+            cancelPendingRelease();
+            pendingRelease = setTimeout(() => {
+                pendingRelease = null;
+                rl.resume();
+                process.nextTick(() => setSuppress(false));
+            }, RELEASE_DEBOUNCE_MS);
+        }
     }
 }