@xingular/harness 2.1.0 → 2.1.2

package/src/terminal/tui/commands.ts

@@ -6,6 +6,7 @@ import { promisify } from 'node:util'
 import { ModelSelectorComponent, TreeSelectorComponent, SessionManager, type AgentSession, type ExtensionUIContext } from '@earendil-works/pi-coding-agent'
 import { SettingsPanel, type TerminalSettingItem } from './settings'
 import { DialogPanel, SearchableSelect } from './dialogs'
+import { LogPanel, formatRunEventLog } from './logPanel'
 import { TrajectoryPanel } from './trajectoryPanel'
 import { expandSkillInvocation, type SkillEntry } from './skillInvocation'
 import manifest from '../../../package.json'
@@ -21,8 +22,7 @@ export interface TerminalCommandHost {
   sessionDirectory(): string
   refresh(): void
   changed(): void
-  planMode(): boolean
-  setPlanMode(enabled: boolean): void
+  plan(brief: string): void
   shutdown(): void
   setEditorText(text: string): void
   copyText(text: string): Promise<void>
@@ -31,6 +31,7 @@ export interface TerminalCommandHost {
   suspend?(): Promise<void>
   hotkeys?(): string
   changelog?(): Promise<string>
+  logs: { read(): Promise<string> }
   trajectory: {
     list(): Promise<TerminalTrajectoryRun[]>
     read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>
@@ -41,7 +42,7 @@ export interface TerminalCommandCompletion { name: string; description?: string
 
 const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'help', description: 'Available terminal commands' },
-  { name: 'plan', description: 'Toggle read-only plan mode' },
+  { name: 'plan', description: 'Run one read-only plan request: /plan <brief>' },
   { name: 'new', description: 'Start a new session' },
   { name: 'resume', description: 'Resume a session in this account and folder' },
   { name: 'tree', description: 'Navigate the session tree' },
@@ -55,6 +56,7 @@ const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'name', description: 'Name the current session' },
   { name: 'session', description: 'Current session statistics' },
   { name: 'trajectory', description: 'Inspect recorded runs for this native session' },
+  { name: 'log', description: 'View Harness diagnostics and this conversation run events' },
   { name: 'compact', description: 'Compact the current context' },
   { name: 'reload', description: 'Reload trusted resources and keyboard bindings' },
   { name: 'trust', description: 'Review plugin code and project trust' },
@@ -231,6 +233,18 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '90%' } })
   }
 
+  async function logs() {
+    const [diagnostics, runs] = await Promise.all([host.logs.read(), host.trajectory.list()])
+    const snapshots = await Promise.all(runs.map(run => host.trajectory.read(run.id)))
+    const sections = [
+      { title: 'Harness diagnostics', text: diagnostics || 'No Harness diagnostics have been captured by this host.' },
+      { title: 'Conversation run events', text: formatRunEventLog(snapshots) }
+    ]
+    await host.ui.custom<void>((tui, theme, _keys, done) => new LogPanel({
+      tui, theme, sections, close: () => done(undefined), changed: host.changed
+    }), { overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', anchor: 'top-left' } })
+  }
+
   async function permissions() {
     for (;;) {
       const runtime = host.runtime()
@@ -290,10 +304,8 @@ export function createTerminalCommands(host: TerminalCommandHost) {
       switch (name) {
         case 'help': notify(completions().map(item => `/${item.name}  ${item.description ?? ''}`).join('\n')); break
         case 'plan': {
-          const current = host.planMode()
-          const next = !argument || argument === 'toggle' ? !current : argument === 'on' ? true : argument === 'off' ? false : null
-          if (next === null) throw new Error('Use /plan, /plan on, /plan off, or /plan toggle.')
-          host.setPlanMode(next)
+          if (!argument || ['on', 'off', 'toggle'].includes(argument.toLowerCase())) throw new Error('Use /plan <plan brief>.')
+          host.plan(argument)
           break
         }
         case 'quit': host.shutdown(); break
@@ -390,6 +402,7 @@ export function createTerminalCommands(host: TerminalCommandHost) {
         }
         case 'session': notify(JSON.stringify(session.getSessionStats(), null, 2)); break
         case 'trajectory': await trajectory(argument); break
+        case 'log': await logs(); break
         case 'compact': await session.compact(argument || undefined); break
         case 'reload': await host.runtime().reload(); notify('Trusted resources reloaded'); break
         case 'trust': {

package/src/terminal/tui/logPanel.test.ts

@@ -0,0 +1,61 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, type TUI } from '@earendil-works/pi-tui'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectorySnapshot } from '../trajectory'
+import { formatRunEventLog, LogPanel } from './logPanel'
+import { createHarnessTheme } from './theme'
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const event = (sequence: number, type: string, payload: unknown): RunEvent => ({
+  id: `event-${sequence}`, runId: 'run-1', sessionId: 'terminal-1', sequence,
+  timestamp: `2026-10-18T00:00:0${sequence}.000Z`, type: type as RunEvent['type'], payload
+})
+
+function plain(panel: LogPanel): string {
+  return panel.render(80).map(stripTerminalSequences).join('\n')
+}
+
+describe('terminal log viewer', () => {
+  it('shows diagnostic run events without prompt or successful response content', () => {
+    const snapshot: TerminalTrajectorySnapshot = {
+      run: { id: 'run-1', mode: 'code', goal: 'Private prompt', startedAt: '2026-10-18T00:00:00.000Z', endedAt: '2026-10-18T00:00:02.000Z', status: 'failed' },
+      events: [
+        event(0, 'context.snapshot', { systemPrompt: 'Private prompt' }),
+        event(1, 'tool.completed', { name: 'web_fetch', ok: true, output: JSON.stringify({ url: 'https://example.com/?token=private', status: 404, error: 'Page missing', text: 'Private response body' }) }),
+        event(2, 'failed', { code: 'network', message: 'Failed at https://example.com/path?token=private' })
+      ]
+    }
+    const text = formatRunEventLog([snapshot])
+    expect(text).toContain('HTTP 404: Page missing')
+    expect(text).toContain('network')
+    expect(text).not.toContain('Private prompt')
+    expect(text).not.toContain('Private response body')
+    expect(text).not.toContain('private')
+  })
+
+  it('opens at the newest lines, pages through the snapshot, switches sources, and closes on Escape', () => {
+    const close = vi.fn()
+    const changed = vi.fn()
+    const panel = new LogPanel({
+      tui: { terminal: { rows: 8 } } as unknown as TUI,
+      theme,
+      sections: [
+        { title: 'Harness diagnostics', text: Array.from({ length: 20 }, (_, index) => `line ${index + 1}`).join('\n') },
+        { title: 'Conversation run events', text: 'run event' }
+      ],
+      close, changed
+    })
+
+    expect(plain(panel)).toContain('line 20')
+    panel.handleInput('\x1b[5~')
+    expect(plain(panel)).toContain('line 11')
+    expect(plain(panel)).not.toContain('line 20')
+    panel.handleInput('\t')
+    expect(plain(panel)).toContain('Conversation run events')
+    panel.handleInput('\x1b')
+    expect(close).toHaveBeenCalledOnce()
+    expect(changed).toHaveBeenCalled()
+  })
+})

package/src/terminal/tui/logPanel.ts

@@ -0,0 +1,175 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { matchesKey, stripTerminalSequences, truncateToWidth, wrapTextWithAnsi, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui'
+
+import { redactLogText } from '../../core/bus'
+import type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectorySnapshot } from '../trajectory'
+
+export interface LogSection {
+  title: string
+  text: string
+}
+
+const payloadOf = (event: RunEvent): Record<string, unknown> =>
+  event.payload && typeof event.payload === 'object' ? event.payload as Record<string, unknown> : {}
+const stringOf = (value: unknown): string | undefined => typeof value === 'string' ? value : undefined
+const numberOf = (value: unknown): number | undefined => typeof value === 'number' && Number.isFinite(value) ? value : undefined
+
+function safe(text: string): string {
+  return redactLogText(stripTerminalSequences(text)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ').replace(/\t/g, '    ')
+}
+
+function timeOf(value: string): string {
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? new Date(parsed).toLocaleTimeString() : value
+}
+
+function webError(output: string): string | undefined {
+  try {
+    const value = JSON.parse(output) as Record<string, unknown>
+    if (typeof value.error !== 'string') return undefined
+    const status = numberOf(value.status)
+    return `${status === undefined ? '' : `HTTP ${status}: `}${value.error}`
+  } catch {
+    return /^(?:The page could not be read:|The search could not be completed:)/.test(output) ? output : undefined
+  }
+}
+
+function eventDetail(event: RunEvent): string[] {
+  const payload = payloadOf(event)
+  switch (event.type) {
+    case 'context.snapshot':
+      return ['prompt and tool definitions omitted']
+    case 'message.delta':
+    case 'message.completed':
+    case 'message.steered':
+      return ['message content omitted']
+    case 'tool.started':
+      return [`tool ${stringOf(payload.name) ?? 'unknown'} started; inputs omitted`]
+    case 'tool.completed': {
+      const name = stringOf(payload.name) ?? 'unknown'
+      const duration = numberOf(payload.durationMs)
+      const result = [`tool ${name} ${payload.ok === false ? 'failed' : 'completed'}${duration === undefined ? '' : ` · ${duration} ms`}`]
+      const output = stringOf(payload.output)
+      const webFailure = (name === 'web_fetch' || name === 'web_search') && output ? webError(output) : undefined
+      if (webFailure) result.push(`  ${webFailure}`)
+      else if (payload.ok === false && output) result.push(`  ${output}`)
+      if (payload.outputTruncated === true) result.push('  recorded output was truncated')
+      return result
+    }
+    case 'retry.started':
+    case 'retry.ended':
+      return [`attempt ${numberOf(payload.attempt) ?? '?'}${numberOf(payload.maxAttempts) === undefined ? '' : ` of ${numberOf(payload.maxAttempts)}`}${numberOf(payload.delayMs) === undefined ? '' : ` · retry delay ${numberOf(payload.delayMs)} ms`}`, ...(stringOf(payload.error) ? [`  ${payload.error}`] : [])]
+    case 'compaction.ended':
+      return [payload.aborted === true ? 'compaction aborted' : 'compaction completed', ...(stringOf(payload.error) ? [`  ${payload.error}`] : [])]
+    case 'extension.notice':
+      return payload.kind === 'error' || payload.level === 'error' ? [stringOf(payload.text) ?? 'extension error'] : ['non-error extension notice omitted']
+    case 'account.status': {
+      const message = stringOf(payload.message)
+      return [stringOf(payload.category) ?? 'account status', ...(message ? [message] : [])]
+    }
+    case 'status.changed': {
+      const reason = stringOf(payload.reason)
+      return [stringOf(payload.status) ?? 'status changed', ...(reason ? [reason] : [])]
+    }
+    case 'failed': {
+      const message = stringOf(payload.message)
+      return [stringOf(payload.code) ?? 'run failed', ...(message ? [message] : [])]
+    }
+    case 'usage.updated': {
+      const request = payload.request && typeof payload.request === 'object' ? payload.request as Record<string, unknown> : {}
+      return [`${stringOf(request.provider) ?? stringOf(payload.provider) ?? 'provider'}/${stringOf(request.model) ?? stringOf(payload.model) ?? 'model'} · request ${numberOf(request.index) ?? numberOf(payload.requests) ?? '?'}`]
+    }
+    case 'approval.requested':
+    case 'approval.resolved':
+      return [`tool ${stringOf(payload.target) ?? ''} · decision ${stringOf(payload.decision) ?? 'pending'}; action details omitted`]
+    case 'question.requested':
+    case 'question.answered':
+      return ['question content omitted']
+    default:
+      return []
+  }
+}
+
+export function formatRunEventLog(snapshots: TerminalTrajectorySnapshot[]): string {
+  if (!snapshots.length) return 'No run events recorded for this conversation.'
+  const sections: string[] = []
+  for (const snapshot of snapshots) {
+    sections.push(`Run ${snapshot.run.id} · ${snapshot.run.status} · ${snapshot.run.mode}`)
+    const events = snapshot.events.slice().sort((left, right) => left.sequence - right.sequence)
+    if (!events.length) sections.push('  No recorded events')
+    for (const event of events) {
+      sections.push(`${timeOf(event.timestamp)}  #${event.sequence}  ${event.type}`)
+      sections.push(...eventDetail(event).map(detail => `  ${detail}`))
+    }
+    sections.push('')
+  }
+  return safe(sections.join('\n').trimEnd())
+}
+
+export interface LogPanelOptions {
+  tui: TUI
+  theme: Theme
+  sections: LogSection[]
+  close(): void
+  changed(): void
+}
+
+/** A static, full-screen view of the diagnostic snapshot taken when /log was opened. */
+export class LogPanel implements Component, Focusable {
+  private source = 0
+  private offset = 0
+  private atEnd = true
+  private maxOffset = 0
+  private focusedValue = false
+
+  constructor(private readonly options: LogPanelOptions) {}
+
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value }
+  invalidate(): void {}
+
+  private changeSource(direction: number): void {
+    const count = this.options.sections.length
+    if (!count) return
+    this.source = (this.source + direction + count) % count
+    this.offset = 0
+    this.atEnd = true
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) { this.options.close(); return }
+    if (matchesKey(data, 'left') || matchesKey(data, 'shift+tab')) this.changeSource(-1)
+    else if (matchesKey(data, 'right') || matchesKey(data, 'tab')) this.changeSource(1)
+    else if (matchesKey(data, 'home')) { this.offset = 0; this.atEnd = false }
+    else if (matchesKey(data, 'end')) this.atEnd = true
+    else if (matchesKey(data, 'up')) { this.offset = Math.max(0, this.currentOffset() - 1); this.atEnd = false }
+    else if (matchesKey(data, 'down')) { this.offset = this.currentOffset() + 1; this.atEnd = false }
+    else if (matchesKey(data, 'pageUp')) { this.offset = Math.max(0, this.currentOffset() - this.pageSize()); this.atEnd = false }
+    else if (matchesKey(data, 'pageDown')) { this.offset = this.currentOffset() + this.pageSize(); this.atEnd = false }
+    this.options.changed()
+  }
+
+  private pageSize(): number { return Math.max(1, this.options.tui.terminal.rows - 4) }
+  private currentOffset(): number { return this.atEnd ? this.maxOffset : this.offset }
+
+  render(width: number): string[] {
+    width = Math.max(1, Math.trunc(width))
+    const rows = Math.max(1, Math.trunc(this.options.tui.terminal.rows))
+    const section = this.options.sections[this.source] ?? { title: 'Logs', text: 'No log sources are available.' }
+    const bodyRows = Math.max(0, rows - 2)
+    const contentWidth = Math.max(1, width)
+    const raw = safe(section.text).split('\n')
+    const lines = raw.flatMap(line => line ? wrapTextWithAnsi(line, contentWidth) : [''])
+    const maxOffset = Math.max(0, lines.length - bodyRows)
+    this.maxOffset = maxOffset
+    if (this.atEnd) this.offset = maxOffset
+    else this.offset = Math.max(0, Math.min(maxOffset, this.offset))
+    const first = this.offset
+    const last = Math.min(lines.length, first + bodyRows)
+    const position = `${this.source + 1}/${Math.max(1, this.options.sections.length)} · lines ${lines.length ? first + 1 : 0}-${last}/${lines.length}`
+    const title = this.options.theme.bold(this.options.theme.fg('accent', `${section.title} · ${position}`))
+    const footer = this.options.theme.fg('dim', '↑/↓ scroll · PgUp/PgDn page · ←/→ source · Esc close')
+    return [title, ...lines.slice(first, last), footer].slice(0, rows).map(line => truncateToWidth(line, width, ''))
+  }
+}

package/src/terminal/tui/questionPicker.ts

@@ -0,0 +1,168 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { SelectList, stripTerminalSequences, truncateToWidth, visibleWidth, type Component, type Focusable, type SelectListTheme, type TUI } from '@earendil-works/pi-tui'
+
+import type { QuestionOption } from '../../sessions/contracts'
+import { DialogPanel } from './dialogs'
+
+const RECOMMENDED = '(Recommended)'
+
+type DisplayOption = { option: QuestionOption; index: number }
+
+export type QuestionPickerResult =
+  | { type: 'answer'; selected: string[] }
+  | { type: 'text'; selected: string[] }
+  | { type: 'cancel' }
+
+export function questionOptionsInDisplayOrder(options: readonly QuestionOption[]): DisplayOption[] {
+  const indexed = options.map((option, index) => ({ option, index }))
+  return [...indexed.filter(({ option }) => option.recommended), ...indexed.filter(({ option }) => !option.recommended)]
+}
+
+function recommendedSelectTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: text => theme.fg('accent', text),
+    selectedText: text => {
+      const marker = text.lastIndexOf(RECOMMENDED)
+      if (marker < 0) return theme.fg('accent', text.replace(/^→/, '❯'))
+      const afterMarker = marker + RECOMMENDED.length
+      return theme.fg('accent', text.slice(0, marker).replace(/^→/, '❯')) + theme.fg('warning', RECOMMENDED) + theme.fg('accent', text.slice(afterMarker))
+    },
+    description: text => theme.fg('muted', text),
+    scrollInfo: text => theme.fg('dim', text),
+    noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+  }
+}
+
+class QuestionPickerContent implements Component, Focusable {
+  private list!: SelectList
+  private selectedIndexes: number[]
+  private focusedValue = false
+  private readonly displayOptions: DisplayOption[]
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly options: readonly QuestionOption[],
+    private readonly multiSelect: boolean,
+    private readonly allowText: boolean,
+    selected: readonly string[],
+    private readonly done: (result: QuestionPickerResult) => void
+  ) {
+    this.displayOptions = questionOptionsInDisplayOrder(options)
+    this.selectedIndexes = []
+    const remaining = [...selected]
+    options.forEach((option, index) => {
+      const selectedIndex = remaining.indexOf(option.label)
+      if (selectedIndex >= 0) {
+        this.selectedIndexes.push(index)
+        remaining.splice(selectedIndex, 1)
+      }
+    })
+    this.rebuild()
+  }
+
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value }
+
+  private labels(): string[] {
+    return this.selectedIndexes.map(index => this.options[index]!.label)
+  }
+
+  private rebuild(): void {
+    const selectedValue = this.list?.getSelectedItem()?.value
+    const items = this.displayOptions.map(({ option }, displayIndex) => ({
+      value: `option:${displayIndex}`,
+      label: `${displayIndex + 1}. ${this.selectedIndexes.includes(this.displayOptions[displayIndex]!.index) ? '✓ ' : ''}${option.label}${option.recommended ? ` ${RECOMMENDED}` : ''}`,
+      description: option.description
+    }))
+    if (this.allowText) items.push({ value: 'write', label: 'Write an answer', description: undefined })
+    if (this.multiSelect) items.push({ value: 'submit', label: 'Submit choices', description: undefined })
+
+    const maxVisible = Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.6) - 5))
+    const theme = recommendedSelectTheme(this.theme)
+    this.list = new SelectList(items, maxVisible, theme, {
+      minPrimaryColumnWidth: 1,
+      maxPrimaryColumnWidth: 60,
+      truncatePrimary: ({ text, maxWidth, isSelected }) => {
+        const marker = text.lastIndexOf(RECOMMENDED)
+        if (marker < 0) return truncateToWidth(text, maxWidth, '')
+        const label = text.slice(0, marker).trimEnd()
+        const suffix = text.slice(marker)
+        const suffixWidth = visibleWidth(suffix)
+        const shortened = suffixWidth >= maxWidth ? truncateToWidth(suffix, maxWidth, '') : `${truncateToWidth(label, Math.max(1, maxWidth - suffixWidth), '…')} ${suffix}`
+        if (isSelected) return shortened
+        const shortenedMarker = shortened.lastIndexOf(RECOMMENDED)
+        return shortenedMarker < 0
+          ? shortened
+          : shortened.slice(0, shortenedMarker) + this.theme.fg('warning', shortened.slice(shortenedMarker))
+      }
+    })
+    if (selectedValue) {
+      const index = items.findIndex(item => item.value === selectedValue)
+      if (index >= 0) this.list.setSelectedIndex(index)
+    }
+    this.list.onSelect = item => {
+      if (item.value === 'write') {
+        this.done({ type: 'text', selected: this.labels() })
+        return
+      }
+      if (item.value === 'submit') {
+        this.done({ type: 'answer', selected: this.labels() })
+        return
+      }
+      const displayIndex = Number(item.value.slice('option:'.length))
+      const originalIndex = this.displayOptions[displayIndex]?.index
+      if (originalIndex === undefined) return
+      if (!this.multiSelect) {
+        this.done({ type: 'answer', selected: [this.options[originalIndex]!.label] })
+        return
+      }
+      const selectedIndex = this.selectedIndexes.indexOf(originalIndex)
+      if (selectedIndex >= 0) this.selectedIndexes.splice(selectedIndex, 1)
+      else this.selectedIndexes.push(originalIndex)
+      this.rebuild()
+      this.tui.requestRender()
+    }
+    this.list.onCancel = () => this.done({ type: 'cancel' })
+  }
+
+  invalidate(): void { this.list.invalidate() }
+  handleInput(data: string): void {
+    if (/^[1-9]$/.test(data)) {
+      const index = Number(data) - 1
+      if (index >= 0 && index < this.displayOptions.length) {
+        this.list.setSelectedIndex(index)
+        this.list.handleInput('\r')
+        return
+      }
+    }
+    this.list.handleInput(data === 'j' ? '\x1b[B' : data === 'k' ? '\x1b[A' : data)
+  }
+
+  render(width: number): string[] {
+    return this.list.render(width).map(line => {
+      const bounded = truncateToWidth(line, width, '')
+      return stripTerminalSequences(line).startsWith('❯')
+        ? this.theme.bg('selectedBg', bounded + ' '.repeat(Math.max(0, width - visibleWidth(bounded))))
+        : bounded
+    })
+  }
+}
+
+export function createQuestionPicker(
+  tui: TUI,
+  theme: Theme,
+  title: string,
+  question: string | undefined,
+  options: readonly QuestionOption[],
+  multiSelect: boolean,
+  allowText: boolean,
+  selected: readonly string[],
+  done: (result: QuestionPickerResult) => void
+): DialogPanel {
+  const content = new QuestionPickerContent(tui, theme, options, multiSelect, allowText, selected, done)
+  const hint = multiSelect ? '↑/↓ select · Enter toggle · Submit choices · Esc cancel' : '↑/↓ select · Enter choose · Esc cancel'
+  const panel = new DialogPanel(title, content, () => theme, hint, question)
+  panel.maxRows = () => Math.max(3, Math.floor(tui.terminal.rows * 0.8))
+  return panel
+}

package/src/terminal/tui/questions.test.ts

@@ -1,41 +1,108 @@
-import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionUIContext, KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import type { Component, TUI } from '@earendil-works/pi-tui'
+import { stripTerminalSequences } from '@earendil-works/pi-tui'
 import { describe, expect, it, vi } from 'vitest'
 import { answerTerminalQuestion } from './questions'
 
 function fixture() {
-  const ui = { select: vi.fn(), input: vi.fn() }
-  return { ui, context: ui as unknown as ExtensionUIContext, signal: new AbortController().signal }
+  const tui = { terminal: { rows: 24 }, requestRender: vi.fn() } as unknown as TUI
+  const theme = {
+    fg: (color: string, text: string) => color === 'warning' ? `\x1b[33m${text}\x1b[39m` : text,
+    bg: (_color: string, text: string) => text,
+    bold: (text: string) => text
+  } as unknown as Theme
+  let active: Component | undefined
+  const custom = vi.fn((factory: Parameters<ExtensionUIContext['custom']>[0]) => new Promise<unknown>((resolve) => {
+    active = factory(tui, theme, {} as KeybindingsManager, resolve) as Component
+  }))
+  const ui = { custom, input: vi.fn() }
+  return { ui, context: ui as unknown as ExtensionUIContext, signal: new AbortController().signal, getActive: () => active }
 }
 
 describe('terminal question answers', () => {
   it('keeps action-like option labels distinct from dialog actions', async () => {
-    const { ui, context, signal } = fixture()
-    ui.select.mockResolvedValue('1. Write an answer — Actual choice')
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'Write an answer', description: 'Actual choice' }] }, signal)).toEqual({ selected: ['Write an answer'] })
+    const { ui, context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'Write an answer', description: 'Actual choice' }] }, signal)
+    expect(stripTerminalSequences(getActive()!.render(80).join('\n'))).toContain('1. Write an answer')
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['Write an answer'] })
     expect(ui.input).not.toHaveBeenCalled()
   })
 
-  it('returns to choices when text entry is cancelled and retains multiple selections', async () => {
-    const { ui, context, signal } = fixture()
-    ui.select.mockResolvedValueOnce('1. A').mockResolvedValueOnce('Write an answer').mockResolvedValueOnce('Submit choices')
+  it('returns the original label when a recommended choice is selected', async () => {
+    const { context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'Plan A' }, { label: 'Plan B', recommended: true }], allowText: false
+    }, signal)
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['Plan B'] })
+  })
+
+  it('keeps numeric choice shortcuts aligned with the displayed recommendation-first order', async () => {
+    const { context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'Plan A' }, { label: 'Plan B', recommended: true }], allowText: false
+    }, signal)
+    getActive()!.handleInput?.('2')
+    await expect(answer).resolves.toEqual({ selected: ['Plan A'] })
+  })
+
+  it('returns to choices after text entry is cancelled and retains multiple selections', async () => {
+    const { ui, context, signal, getActive } = fixture()
     ui.input.mockResolvedValue(undefined)
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'A' }], multiSelect: true }, signal)).toEqual({ selected: ['A'] })
-    expect(ui.select).toHaveBeenCalledTimes(3)
-    expect(ui.select.mock.calls[2][1]).toContain('1. ✓ A')
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'A' }], multiSelect: true
+    }, signal)
+    getActive()!.handleInput?.('\r')
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\r')
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(ui.custom).toHaveBeenCalledTimes(2)
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['A'] })
+  })
+
+  it('shows recommended options first with a yellow marker, without modifying the labels', async () => {
+    const controller = new AbortController()
+    const { ui, context, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [
+        { label: 'Plan A' },
+        { label: 'Plan B', recommended: true },
+        { label: 'Plan C', recommended: true }
+      ], multiSelect: true
+    }, controller.signal)
+    const rendered = getActive()!.render(100).join('\n')
+    const plain = stripTerminalSequences(rendered)
+    expect(plain.indexOf('Plan B')).toBeLessThan(plain.indexOf('Plan A'))
+    expect(plain.indexOf('Plan C')).toBeLessThan(plain.indexOf('Plan A'))
+    expect(rendered).toContain('\x1b[33m(Recommended)\x1b[39m')
+    controller.abort()
+    await expect(answer).resolves.toBeUndefined()
+    expect(ui.custom).toHaveBeenCalledOnce()
   })
 
-  it('shows real batch progress and returns cancellation without inventing an answer', async () => {
+  it('shows batch progress and the full question in text entry', async () => {
     const { ui, context, signal } = fixture()
     ui.input.mockResolvedValue(undefined)
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Why?', summary: 'Reason', batchId: 'batch', batchIndex: 2, batchCount: 3 }, signal)).toBeUndefined()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Why?', summary: 'Reason', batchId: 'batch', batchIndex: 2, batchCount: 3
+    }, signal)
+    await expect(answer).resolves.toBeUndefined()
     expect(ui.input).toHaveBeenCalledWith('2 of 3 · Reason: Why?', undefined, { signal })
   })
 
-  it('honors text restrictions and ignores answers after expiry', async () => {
-    const { ui, context } = fixture()
+  it('honors text restrictions and cancels the picker when the question expires', async () => {
     const controller = new AbortController()
-    ui.select.mockImplementation(async () => { controller.abort(); return '1. A' })
-    expect(await answerTerminalQuestion(context, { requestId: 'q', options: [{ label: 'A' }], allowText: false }, controller.signal)).toBeUndefined()
-    expect(ui.select.mock.calls[0][1]).toEqual(['1. A'])
+    const { ui, context, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', options: [{ label: 'A' }], allowText: false
+    }, controller.signal)
+    expect(stripTerminalSequences(getActive()!.render(80).join('\n'))).not.toContain('Write an answer')
+    controller.abort()
+    await expect(answer).resolves.toBeUndefined()
+    expect(ui.custom).toHaveBeenCalledOnce()
   })
 })