@xingular/harness 2.1.1 → 2.1.2

package/src/terminal/terminal.test.ts

@@ -15,6 +15,7 @@ import { rootWithProject, writeFile } from '../../tests/helpers'
 import { parseCli } from './cli'
 import { SOCKET_ENV, TOKEN_ENV, socketCall, type SocketConnection } from './client'
 import { SessionSocket } from './socket'
+import { LOG_READ_CHUNK_BYTES } from './logs'
 
 const open: Harness[] = []
 afterEach(async () => {
@@ -467,6 +468,25 @@ describe('decisions in the Harness-owned frontend', () => {
     await expect(socketCall(connection, 'terminal.trajectory.list', {}, 1000, key)).resolves.toEqual({ runs: [] })
   })
 
+  it('serves a bounded diagnostic snapshot only through the private terminal control channel', async () => {
+    const { connection, harness } = await setup()
+    await expect(socketCall(connection, 'terminal.logs.info')).rejects.toMatchObject({ code: 'unauthorized' })
+    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
+    await expect(socketCall(connection, 'terminal.logs.info', {}, 1000, key)).resolves.toEqual({ size: null })
+    await expect(socketCall(connection, 'terminal.logs.read', { snapshotSize: 1, offset: 0 }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+
+    const text = `${'a'.repeat(LOG_READ_CHUNK_BYTES - 1)}🧠tail`
+    writeFileSync(join(harness.stateDir, 'harness.log'), text)
+    const { size } = await socketCall<{ size: number }>(connection, 'terminal.logs.info', {}, 1000, key)
+    expect(size).toBe(Buffer.byteLength(text))
+    await expect(socketCall(connection, 'terminal.logs.read', { snapshotSize: size, offset: size }, 1000, key)).rejects.toMatchObject({ code: 'invalid_request' })
+    const first = await socketCall<{ data: string; nextOffset: number }>(connection, 'terminal.logs.read', { snapshotSize: size, offset: 0 }, 1000, key)
+    const second = await socketCall<{ data: string; nextOffset: number }>(connection, 'terminal.logs.read', { snapshotSize: size, offset: first.nextOffset }, 1000, key)
+    expect(first.nextOffset).toBe(LOG_READ_CHUNK_BYTES)
+    expect(second.nextOffset).toBe(size)
+    expect(Buffer.concat([Buffer.from(first.data, 'base64'), Buffer.from(second.data, 'base64')]).toString('utf8')).toBe(text)
+  })
+
   it('requires the private input-owner key for pending decisions and exact draft state', async () => {
     const { connection, harness, tell } = await setup()
     await tell('ready', { nativeSessionId: '/native.jsonl' })

package/src/terminal/terminals.ts

@@ -43,6 +43,7 @@ import { SOCKET_ENV, TOKEN_ENV } from './client'
 import { TerminalController, type PolicyReply } from './controller'
 import { resolvePiCommand, terminalCommandFiles } from './launch'
 import { SessionSocket, socketPath } from './socket'
+import { harnessLogInfo, readHarnessLogChunk } from './logs'
 import { listTerminalTrajectoryRuns, readTerminalTrajectory } from './trajectory'
 
 /** Identity of the exact resource decision that this terminal was prepared with. */
@@ -543,6 +544,16 @@ export class Terminals {
         broker,
         terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
           if (call.startsWith('terminal.subagents.')) return this.subagentsCall(live, call, params)
+          if (call === 'terminal.logs.info') return harnessLogInfo(this.options.stateDir)
+          if (call === 'terminal.logs.read') {
+            const { snapshotSize, offset } = params
+            if (typeof snapshotSize !== 'number' || !Number.isSafeInteger(snapshotSize) || snapshotSize < 0 || typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0 || offset >= snapshotSize) {
+              throw invalid('A valid diagnostics snapshot size and byte offset are required.')
+            }
+            const current = harnessLogInfo(this.options.stateDir).size
+            if (current === null || snapshotSize > current) throw invalid('The diagnostics snapshot is no longer available.')
+            return readHarnessLogChunk(this.options.stateDir, snapshotSize, offset)
+          }
           if (call.startsWith('terminal.trajectory.')) return this.trajectoryCall(live, call, params)
           if (call === 'terminal.permissions.get') {
             const policy = this.options.approvals.read()

package/src/terminal/tui/application.ts

@@ -25,6 +25,7 @@ import { chooseWorkingVerb, createCompletionStatus, getWorkingSpinnerFrames, SPI
 import { HarnessWelcome } from './welcome'
 import { answerTerminalQuestion } from './questions'
 import type { QuestionAnswer } from '../../sessions/registry'
+import { readHarnessLogSnapshot, type HarnessLogChunk, type HarnessLogInfo } from '../logs'
 import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
 
 const exec = promisify(execFile)
@@ -190,6 +191,10 @@ export class TerminalApplication {
         plan: brief => this.enqueuePlan(brief),
         copyText: copyToClipboard, openExternal,
         changed: this.change,
+        logs: { read: () => readHarnessLogSnapshot(
+          () => controlCall<HarnessLogInfo>('terminal.logs.info'),
+          (snapshotSize, offset) => controlCall<HarnessLogChunk>('terminal.logs.read', { snapshotSize, offset })
+        ) },
         trajectory: {
           list: async () => (await controlCall<{ runs: TerminalTrajectoryRun[] }>('terminal.trajectory.list')).runs,
           read: (runId, afterSequence) => controlCall<TerminalTrajectorySnapshot>('terminal.trajectory.events', { runId, ...(afterSequence === undefined ? {} : { afterSequence }) })

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

@@ -33,6 +33,7 @@ function setup() {
     refresh: vi.fn(), changed: vi.fn(), shutdown: vi.fn(), setEditorText: vi.fn(), copyText: vi.fn(async () => {}),
     plan: vi.fn(),
     hotkeys: () => 'Escape: interrupt', changelog: async () => 'Harness release notes',
+    logs: { read: vi.fn(async () => '[harness] diagnostic') },
     trajectory: {
       list: vi.fn(async () => [trajectoryRun]),
       read: vi.fn(async () => ({ run: trajectoryRun, events: [] }))
@@ -59,7 +60,7 @@ describe('owned terminal commands', () => {
   it('populates completion from builtins and loaded resources', () => {
     const { commands } = setup()
     const names = commands.completions().map(item => item.name)
-    expect(names).toEqual(expect.arrayContaining(['model', 'resume', 'accounts', 'review', 'effort', 'trajectory', 'permissions']))
+    expect(names).toEqual(expect.arrayContaining(['model', 'resume', 'accounts', 'review', 'effort', 'trajectory', 'log', 'permissions']))
     expect(names).not.toContain('thinking')
     expect(names).not.toContain('skill:diagnose')
     expect(new Set(names).size).toBe(names.length)
@@ -172,6 +173,17 @@ describe('owned terminal commands', () => {
     expect(host.trajectory.read).toHaveBeenLastCalledWith('run-1')
   })
 
+  it('opens a full-screen snapshot combining diagnostics and current-conversation run events', async () => {
+    const { commands, host, ui } = setup()
+    await commands.execute('/log')
+    expect(host.logs.read).toHaveBeenCalledOnce()
+    expect(host.trajectory.list).toHaveBeenCalledOnce()
+    expect(host.trajectory.read).toHaveBeenCalledWith('run-1')
+    expect(ui.custom).toHaveBeenCalledWith(expect.any(Function), {
+      overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', anchor: 'top-left' }
+    })
+  })
+
   it('shows shared tool grants and confirms Full Permission before enabling it', async () => {
     const { commands, host, runtime, ui } = setup()
     vi.mocked(ui.custom).mockImplementationOnce(async () => 'tool:bash' as never)

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'
@@ -30,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>
@@ -54,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' },
@@ -230,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()
@@ -387,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
+}