@xingular/harness 0.1.5 → 0.1.7

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

@@ -0,0 +1,313 @@
+import { type KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import { Input, KeybindingsManager as TuiKeybindingsManager, TuiMainScreen, TUI_KEYBINDINGS, stripTerminalSequences, visibleWidth, type AutocompleteProvider, type Component, type Terminal } from '@earendil-works/pi-tui'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { DialogPanel, SecretInput } from './dialogs'
+import { createHarnessTheme } from './theme'
+import { createTerminalUi, type TerminalUi } from './ui'
+
+const open: TerminalUi[] = []
+afterEach(() => { for (const ui of open.splice(0)) ui.dispose(); vi.useRealTimers() })
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+function setup() {
+  const terminal = { columns: 80, rows: 30, kittyProtocolActive: false, write: vi.fn(), hideCursor: vi.fn(), setTitle: vi.fn(), start: vi.fn(), stop: vi.fn() } as unknown as Terminal
+  const tui = new TuiMainScreen(terminal)
+  vi.spyOn(tui, 'requestRender').mockImplementation(() => {})
+  const originalInput = new Input()
+  const original = Object.assign(originalInput, { getText: () => originalInput.getValue(), setText: (value: string) => originalInput.setValue(value) })
+  tui.addChild(original)
+  tui.setFocus(original)
+  const callbacks = {
+    changed: vi.fn(), notify: vi.fn(), setEditor: vi.fn(), getEditorText: vi.fn(() => 'draft'), setEditorText: vi.fn(),
+    setStatus: vi.fn(), setWidget: vi.fn(), setHeader: vi.fn(), setFooter: vi.fn(), themeChanged: vi.fn(), setToolsExpanded: vi.fn()
+  }
+  const host = createTerminalUi({ tui, theme, keybindings: new TuiKeybindingsManager(TUI_KEYBINDINGS) as KeybindingsManager, ...callbacks, getEditor: () => original })
+  open.push(host)
+  return { host, tui, terminal, original, callbacks }
+}
+function key(tui: TuiMainScreen, data: string): void { tui.getFocusedComponent()?.handleInput?.(data) }
+
+function plain(component: Component, width = 80): string[] { return component.render(width).map(stripTerminalSequences) }
+
+describe('the complete terminal extension UI host', () => {
+  it('selects original option values and restores the actual TUI focus', async () => {
+    const { host, tui, original } = setup()
+    const promise = host.select('Choose account', ['First', 'Second\noriginal'])
+    expect(tui.hasOverlay()).toBe(true)
+    key(tui, '\x1b[B')
+    key(tui, '\r')
+    expect(await promise).toBe('Second\noriginal')
+    expect(tui.getFocusedComponent()).toBe(original)
+    expect(tui.hasOverlay()).toBe(false)
+  })
+
+  it('resolves confirmation cancellation false, supports input and multiline editor values', async () => {
+    const { host, tui } = setup()
+    const confirmation = host.confirm('Delete credential?', 'Remove only this account')
+    key(tui, '\x1b')
+    expect(await confirmation).toBe(false)
+    const input = host.input('Account label', 'Personal')
+    key(tui, 'Work')
+    key(tui, '\r')
+    expect(await input).toBe('Work')
+    const editor = host.editor('Edit prompt', 'Line 1')
+    key(tui, '\n')
+    key(tui, 'Line 2')
+    key(tui, '\r')
+    expect(await editor).toBe('Line 1\nLine 2')
+  })
+
+  it('dismisses aborted and timed dialogs, shows countdowns and removes every timer', async () => {
+    vi.useFakeTimers()
+    const { host, tui, original } = setup()
+    const controller = new AbortController()
+    controller.abort()
+    expect(await host.input('Already cancelled', undefined, { signal: controller.signal })).toBeUndefined()
+    expect(tui.hasOverlay()).toBe(false)
+    const active = new AbortController()
+    const cancelled = host.select('Choice', ['One'], { signal: active.signal })
+    active.abort()
+    expect(await cancelled).toBeUndefined()
+    expect(tui.getFocusedComponent()).toBe(original)
+    const timed = host.input('Expires', undefined, { timeout: 1000 })
+    expect(plain(tui.getFocusedComponent()!).join('\n')).toContain('1s')
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(await timed).toBeUndefined()
+    expect(tui.getFocusedComponent()).toBe(original)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('masks credentials while retaining exact pasted and edited values', async () => {
+    const { host, tui } = setup()
+    const result = host.secretInput('API key')
+    key(tui, '\x1b[200~secret_日本語_credential\x1b[201~')
+    const component = tui.getFocusedComponent()!
+    expect(plain(component).join('\n')).not.toContain('secret')
+    expect(plain(component).join('\n')).not.toContain('credential')
+    expect(plain(component).join('\n')).toContain('•')
+    key(tui, '\r')
+    expect(await result).toBe('secret_日本語_credential')
+    const direct = new SecretInput({ prompt: '' })
+    direct.setValue('private 🧠 secret')
+    direct.focused = true
+    for (let width = 1; width < 40; width++) {
+      for (const row of direct.render(width)) {
+        expect(row).not.toContain('private')
+        expect(row).not.toContain('secret')
+        expect(visibleWidth(row)).toBeLessThanOrEqual(width)
+      }
+    }
+  })
+
+  it('mounts trusted custom overlays and disposes them exactly once after done', async () => {
+    const { host, tui, original, terminal } = setup()
+    let finish: (value: string) => void = () => {}
+    const custom = { render: () => ['Custom component'], invalidate() {}, dispose: vi.fn() }
+    const onHandle = vi.fn()
+    const factory = vi.fn((_tui, _theme, _keys, done) => { finish = done; return custom })
+    const result = host.custom<string>(factory, { overlay: true, overlayOptions: () => ({ width: '50%', anchor: 'center' }), onHandle })
+    await vi.waitFor(() => expect(onHandle).toHaveBeenCalledOnce())
+    expect(factory.mock.calls[0][0]).toBe(tui)
+    expect(factory.mock.calls[0][1]).toBe(theme)
+    expect(tui.getFocusedComponent()).toBe(custom)
+    finish('selected')
+    finish('duplicate')
+    expect(await result).toBe('selected')
+    expect(custom.dispose).toHaveBeenCalledOnce()
+    expect(tui.getFocusedComponent()).toBe(original)
+    expect(terminal.start).not.toHaveBeenCalled()
+    expect(terminal.stop).not.toHaveBeenCalled()
+  })
+
+  it('handles synchronous completion and async rejection without leaked focus or mounts', async () => {
+    const { host, tui, original } = setup()
+    const custom = { render: () => ['Custom'], invalidate() {}, dispose: vi.fn() }
+    expect(await host.custom<string>((_tui, _theme, _keys, done) => { done('early'); return custom })).toBe('early')
+    await Promise.resolve()
+    expect(custom.dispose).toHaveBeenCalledOnce()
+    await expect(host.custom(async () => { throw new Error('extension failed') })).rejects.toThrow('extension failed')
+    expect(tui.getFocusedComponent()).toBe(original)
+    expect(tui.hasOverlay()).toBe(false)
+  })
+
+  it('preserves trusted factories and forwards widgets, statuses, notifications and editor operations', () => {
+    const { host, callbacks, original, terminal } = setup()
+    const factory = vi.fn(() => original)
+    host.setWidget('stats', factory, { placement: 'belowEditor' })
+    host.setHeader(factory)
+    host.setFooter(factory)
+    host.setStatus('custom', 'Ready')
+    host.notify('Loaded', 'info')
+    host.pasteToEditor('inserted')
+    host.setEditorText('replacement')
+    host.setEditorComponent(factory)
+    expect(host.getEditorComponent()).toBe(factory)
+    expect(callbacks.setWidget).toHaveBeenCalledWith('stats', factory, 'belowEditor')
+    expect(callbacks.setHeader).toHaveBeenCalledWith(factory)
+    expect(callbacks.setFooter).toHaveBeenCalledWith(factory)
+    expect(callbacks.setEditor).toHaveBeenCalledWith(factory)
+    expect(callbacks.setStatus).toHaveBeenCalledWith('custom', 'Ready')
+    expect(callbacks.notify).toHaveBeenCalledWith('Loaded', 'info')
+    expect(original.getValue()).toBe('inserted')
+    expect(callbacks.setEditorText).toHaveBeenCalledWith('replacement')
+    expect(host.getEditorText()).toBe('draft')
+    host.setTitle('Session\x1b]2;bad\x07\nname')
+    expect(terminal.setTitle).toHaveBeenCalledWith('Session name')
+  })
+
+  it('retains theme, working indicator and output expansion state with actual callbacks', () => {
+    const { host, callbacks } = setup()
+    host.setWorkingMessage('Inspecting')
+    host.setWorkingVisible(false)
+    host.setWorkingIndicator({ frames: ['●'], intervalMs: 500 })
+    host.setHiddenThinkingLabel('Reasoning')
+    host.setToolsExpanded(true)
+    expect(host.state).toMatchObject({ workingMessage: 'Inspecting', workingVisible: false, workingIndicator: { frames: ['●'], intervalMs: 500 }, hiddenThinkingLabel: 'Reasoning' })
+    expect(host.getToolsExpanded()).toBe(true)
+    expect(callbacks.setToolsExpanded).toHaveBeenCalledWith(true)
+    expect(host.getAllThemes()).toEqual([{ name: 'harness-titanium', path: undefined }])
+    expect(host.getTheme('harness-titanium')).toBe(theme)
+    expect(host.setTheme('missing').success).toBe(false)
+    expect(host.setTheme(theme)).toEqual({ success: true })
+    expect(callbacks.themeChanged).toHaveBeenCalledWith(theme)
+    expect(host.theme).toBe(theme)
+  })
+
+  it('stacks autocomplete wrappers over the original provider and preserves input listener cleanup', () => {
+    const { host, tui } = setup()
+    const provider: AutocompleteProvider = { getSuggestions: async () => null, applyCompletion: (lines, cursorLine, cursorCol) => ({ lines, cursorLine, cursorCol }) }
+    const first = vi.fn((base: AutocompleteProvider) => ({ ...base, triggerCharacters: ['@'] }))
+    const second = vi.fn((base: AutocompleteProvider) => ({ ...base, triggerCharacters: [...base.triggerCharacters!, '#'] }))
+    host.addAutocompleteProvider(first)
+    host.addAutocompleteProvider(second)
+    expect(host.wrapAutocomplete(provider).triggerCharacters).toEqual(['@', '#'])
+    const remove = vi.fn()
+    vi.spyOn(tui, 'addInputListener').mockReturnValue(remove)
+    const unsubscribe = host.onTerminalInput(() => ({ consume: true }))
+    unsubscribe()
+    unsubscribe()
+    host.dispose()
+    expect(remove).toHaveBeenCalledOnce()
+  })
+
+  it('resets session UI contributions and listeners while retaining a reusable UI object', async () => {
+    const { host, tui, callbacks } = setup()
+    const remove = vi.fn()
+    vi.spyOn(tui, 'addInputListener').mockReturnValue(remove)
+    host.onTerminalInput(() => undefined)
+    host.setStatus('session-status', 'Busy')
+    host.setWidget('session-widget', ['Temporary'])
+    host.setWorkingMessage('Old session')
+    host.setWorkingVisible(false)
+    host.setWorkingIndicator({ frames: ['●'] })
+    host.setHiddenThinkingLabel('Hidden')
+    host.setToolsExpanded(true)
+    host.addAutocompleteProvider(provider => provider)
+    const pending = host.input('Old session question')
+    host.reset()
+    expect(await pending).toBeUndefined()
+    expect(remove).toHaveBeenCalledOnce()
+    expect(callbacks.setStatus).toHaveBeenLastCalledWith('session-status', undefined)
+    expect(callbacks.setWidget).toHaveBeenLastCalledWith('session-widget', undefined)
+    expect(callbacks.setHeader).toHaveBeenLastCalledWith(undefined)
+    expect(callbacks.setFooter).toHaveBeenLastCalledWith(undefined)
+    expect(callbacks.setEditor).toHaveBeenLastCalledWith(undefined)
+    expect(host.state).toMatchObject({ workingVisible: true, toolsExpanded: false, autocompleteFactories: [] })
+    expect(host.state.workingMessage).toBeUndefined()
+    expect(host.state.workingIndicator).toBeUndefined()
+    expect(host.state.hiddenThinkingLabel).toBeUndefined()
+    const next = host.input('New session question')
+    key(tui, 'new session')
+    key(tui, '\r')
+    expect(await next).toBe('new session')
+  })
+
+  it('refreshes loaded theme identities without retaining removed resource themes', () => {
+    const { host } = setup()
+    const loaded = Object.create(theme) as Theme
+    Object.defineProperty(loaded, 'name', { value: 'plugin-theme' })
+    Object.defineProperty(loaded, 'sourcePath', { value: '/trusted/theme.json' })
+    host.setThemes([loaded])
+    expect(host.getAllThemes()).toContainEqual({ name: 'plugin-theme', path: '/trusted/theme.json' })
+    expect(host.getTheme('plugin-theme')).toBe(loaded)
+    host.setThemes([])
+    expect(host.getTheme('plugin-theme')).toBeUndefined()
+    expect(host.getTheme('harness-titanium')).toBe(theme)
+  })
+
+  it('filters long selectors by their labels and preserves real selection across terminal resizes', async () => {
+    const { host, tui, terminal } = setup()
+    const options = Array.from({ length: 30 }, (_, index) => `Provider model ${index}`)
+    options.push('Distinct 中文 model')
+    const selected = host.select('Models', options)
+    const panel = tui.getFocusedComponent()!
+    expect(plain(panel).join('\n')).toContain('Type to search')
+    key(tui, 'Distinct')
+    expect(plain(panel).join('\n')).toContain('Distinct 中文 model')
+    expect(plain(panel).join('\n')).not.toContain('Provider model')
+    Object.defineProperty(terminal, 'rows', { value: 8 })
+    for (let width = 0; width < 40; width++) {
+      for (const row of panel.render(width)) expect(visibleWidth(row)).toBeLessThanOrEqual(width)
+    }
+    key(tui, '\r')
+    expect(await selected).toBe('Distinct 中文 model')
+  })
+
+  it('keeps CJK multiline editors responsive even in one-column overlays', async () => {
+    const { host, tui } = setup()
+    const editing = host.editor('中文', '日本語 🧠\nSecond line')
+    const panel = tui.getFocusedComponent()!
+    for (const width of [0, 1, 2, 3, 4, 5, 10, 80]) {
+      for (const row of panel.render(width)) expect(visibleWidth(row), `width ${width}`).toBeLessThanOrEqual(width)
+    }
+    key(tui, '\r')
+    expect(await editing).toBe('日本語 🧠\nSecond line')
+  })
+
+  it('keeps approval choices and controls visible while every long action detail remains scrollable', async () => {
+    const { host, tui, terminal } = setup()
+    Object.defineProperty(terminal, 'rows', { value: 20 })
+    const message = Array.from({ length: 50 }, (_, index) => `Action detail ${index}: /important/path/file-${index}.txt`).join('\n')
+    const confirmation = host.confirm('Allow this action?', message)
+    const panel = tui.getFocusedComponent()!
+    const observed: string[] = []
+    for (let page = 0; page < 20; page++) {
+      const rows = plain(panel, 40)
+      expect(rows.length).toBeLessThanOrEqual(16)
+      expect(rows.join('\n')).toContain('❯ Yes')
+      expect(rows.join('\n')).toContain('No')
+      expect(rows.some(row => row.includes('PgUp/PgDn details') && row.includes('Enter'))).toBe(true)
+      observed.push(...rows)
+      key(tui, '\x1b[6~')
+    }
+    expect(observed.join('\n')).toContain('file-0.txt')
+    expect(observed.join('\n')).toContain('file-49.txt')
+    key(tui, '\r')
+    expect(await confirmation).toBe(true)
+  })
+
+  it('keeps the write-answer choice visible when a long question menu scrolls at 40 by 20', async () => {
+    const { host, tui, terminal } = setup()
+    Object.defineProperty(terminal, 'rows', { value: 20 })
+    const choices = [...Array.from({ length: 20 }, (_, index) => `Choice ${index}: description ${'long '.repeat(20)}`), 'Write an answer']
+    const selected = host.select('A question with long context', choices)
+    for (let index = 1; index < choices.length; index++) key(tui, '\x1b[B')
+    const rows = plain(tui.getFocusedComponent()!, 40)
+    expect(rows.length).toBeLessThanOrEqual(16)
+    expect(rows.join('\n')).toContain('❯ Write an answer')
+    key(tui, '\r')
+    expect(await selected).toBe('Write an answer')
+  })
+
+  it('cancels all pending dialogs on shutdown and keeps every dialog row within the terminal width', async () => {
+    const { host, tui } = setup()
+    const input = host.input('中文title', 'Placeholder')
+    const panel = tui.getFocusedComponent() as DialogPanel
+    for (let width = 0; width < 100; width++) {
+      for (const row of panel.render(width)) expect(visibleWidth(row), `width ${width}`).toBeLessThanOrEqual(width)
+    }
+    host.dispose()
+    expect(await input).toBeUndefined()
+    expect(tui.hasOverlay()).toBe(false)
+  })
+})

package/src/terminal/tui/ui.ts

@@ -0,0 +1,166 @@
+import { Theme, type AutocompleteProviderFactory, type ExtensionUIContext, type KeybindingsManager, type WorkingIndicatorOptions } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, type AutocompleteProvider, type EditorComponent, type TuiMainScreen } from '@earendil-works/pi-tui'
+
+import { TerminalDialogs } from './dialogs'
+
+type EditorFactory = Parameters<ExtensionUIContext['setEditorComponent']>[0]
+type HeaderFactory = Parameters<ExtensionUIContext['setHeader']>[0]
+type FooterFactory = Parameters<ExtensionUIContext['setFooter']>[0]
+type WidgetContent = string[] | ((...args: Parameters<NonNullable<HeaderFactory>>) => ReturnType<NonNullable<HeaderFactory>>) | undefined
+
+export interface TerminalUiState {
+  theme: Theme
+  workingMessage?: string
+  workingVisible: boolean
+  workingIndicator?: WorkingIndicatorOptions
+  hiddenThinkingLabel?: string
+  toolsExpanded: boolean
+  autocompleteFactories: AutocompleteProviderFactory[]
+}
+export interface TerminalUiOptions {
+  tui: TuiMainScreen
+  theme: Theme
+  keybindings: KeybindingsManager
+  changed(): void
+  notify(message: string, type?: string): void
+  setEditor(factory: EditorFactory): void
+  getEditorText(): string
+  setEditorText(value: string): void
+  setStatus(key: string, value: string | undefined): void
+  setWidget(key: string, content: WidgetContent, placement?: string): void
+  setHeader(factory: HeaderFactory): void
+  setFooter(factory: FooterFactory): void
+  getEditor?(): EditorComponent
+  getAutocompleteProvider?(): AutocompleteProvider
+  setAutocompleteProvider?(provider: AutocompleteProvider): void
+  themes?: Theme[]
+  themeChanged?(theme: Theme): void
+  getToolsExpanded?(): boolean
+  setToolsExpanded?(expanded: boolean): void
+}
+export interface TerminalUi extends ExtensionUIContext {
+  readonly state: TerminalUiState
+  secretInput: ExtensionUIContext['input']
+  wrapAutocomplete(provider: AutocompleteProvider): AutocompleteProvider
+  reset(): void
+  setThemes(themes: Theme[]): void
+  dispose(): void
+}
+
+/** UI adaptation only: the Application owns component mounting and terminal lifecycle. */
+export function createTerminalUi(options: TerminalUiOptions): TerminalUi {
+  const state: TerminalUiState = {
+    theme: options.theme, workingVisible: true, toolsExpanded: false, autocompleteFactories: []
+  }
+  const dialogs = new TerminalDialogs(options.tui, () => state.theme, options.keybindings, options.changed)
+  const inputSubscriptions = new Set<() => void>()
+  const builtInThemes = options.themes ?? []
+  const themes = new Map(builtInThemes.filter(theme => theme.name).map(theme => [theme.name!, theme]))
+  if (options.theme.name) themes.set(options.theme.name, options.theme)
+  const statusKeys = new Set<string>()
+  const widgetKeys = new Set<string>()
+  let editorFactory: EditorFactory
+  let disposed = false
+  const changed = () => { if (!disposed) options.changed() }
+  const wrapAutocomplete = (provider: AutocompleteProvider) => state.autocompleteFactories.reduce((current, factory) => factory(current), provider)
+  return {
+    state,
+    select: (title, items, opts) => dialogs.select(title, items, opts),
+    confirm: (title, message, opts) => dialogs.confirm(title, message, opts),
+    input: (title, placeholder, opts) => dialogs.input(title, placeholder, opts),
+    secretInput: (title, placeholder, opts) => dialogs.input(title, placeholder, opts, true),
+    editor: (title, prefill) => dialogs.editor(title, prefill),
+    custom: (factory, opts) => dialogs.custom(factory, opts),
+    notify: (message, type) => options.notify(message, type),
+    onTerminalInput(handler) {
+      if (disposed) return () => {}
+      const remove = options.tui.addInputListener(handler)
+      const unsubscribe = () => { if (inputSubscriptions.delete(unsubscribe)) remove() }
+      inputSubscriptions.add(unsubscribe)
+      return unsubscribe
+    },
+    setStatus(key, value) { if (value === undefined) statusKeys.delete(key); else statusKeys.add(key); options.setStatus(key, value); changed() },
+    setWorkingMessage(message) { state.workingMessage = message; changed() },
+    setWorkingVisible(visible) { state.workingVisible = visible; changed() },
+    setWorkingIndicator(indicator) {
+      state.workingIndicator = indicator ? { ...indicator, frames: indicator.frames?.slice() } : undefined
+      changed()
+    },
+    setHiddenThinkingLabel(label) { state.hiddenThinkingLabel = label; changed() },
+    setWidget(key, content, placement) { if (content === undefined) widgetKeys.delete(key); else widgetKeys.add(key); options.setWidget(key, content, placement?.placement); changed() },
+    setHeader(factory) { options.setHeader(factory); changed() },
+    setFooter(factory) { options.setFooter(factory); changed() },
+    setTitle(title) { options.tui.terminal.setTitle(stripTerminalSequences(title).replace(/[\x00-\x1f\x7f]/g, ' ')) },
+    pasteToEditor(text) {
+      const editor = options.getEditor?.()
+      if (editor) editor.handleInput(`\x1b[200~${text}\x1b[201~`)
+      else options.setEditorText(options.getEditorText() + text)
+      changed()
+    },
+    setEditorText(text) { options.setEditorText(text); changed() },
+    getEditorText: options.getEditorText,
+    addAutocompleteProvider(factory) {
+      state.autocompleteFactories.push(factory)
+      const base = options.getAutocompleteProvider?.()
+      if (base) options.setAutocompleteProvider?.(wrapAutocomplete(base))
+      changed()
+    },
+    wrapAutocomplete,
+    setEditorComponent(factory) { editorFactory = factory; options.setEditor(factory); changed() },
+    getEditorComponent: () => editorFactory,
+    get theme() { return state.theme },
+    getAllThemes: () => [...themes].map(([name, theme]) => ({ name, path: theme.sourcePath })),
+    getTheme: name => themes.get(name),
+    setTheme(themeOrName) {
+      const theme = typeof themeOrName === 'string' ? themes.get(themeOrName) : themeOrName
+      if (!(theme instanceof Theme)) return { success: false, error: `Unknown theme: ${String(themeOrName)}` }
+      state.theme = theme
+      if (theme.name) themes.set(theme.name, theme)
+      options.themeChanged?.(theme)
+      options.tui.invalidate()
+      changed()
+      return { success: true }
+    },
+    getToolsExpanded: () => options.getToolsExpanded?.() ?? state.toolsExpanded,
+    setToolsExpanded(expanded) { state.toolsExpanded = expanded; options.setToolsExpanded?.(expanded); changed() },
+    setThemes(loaded) {
+      themes.clear()
+      for (const theme of builtInThemes) if (theme.name) themes.set(theme.name, theme)
+      for (const theme of loaded) if (theme.name) themes.set(theme.name, theme)
+      if (options.theme.name && !themes.has(options.theme.name)) themes.set(options.theme.name, options.theme)
+      if (state.theme.name && !themes.has(state.theme.name)) themes.set(state.theme.name, state.theme)
+      changed()
+    },
+    reset() {
+      if (disposed) return
+      dialogs.reset()
+      for (const unsubscribe of [...inputSubscriptions]) unsubscribe()
+      inputSubscriptions.clear()
+      for (const key of statusKeys) options.setStatus(key, undefined)
+      for (const key of widgetKeys) options.setWidget(key, undefined)
+      statusKeys.clear()
+      widgetKeys.clear()
+      state.autocompleteFactories = []
+      state.workingMessage = undefined
+      state.workingVisible = true
+      state.workingIndicator = undefined
+      state.hiddenThinkingLabel = undefined
+      state.toolsExpanded = false
+      editorFactory = undefined
+      options.setHeader(undefined)
+      options.setFooter(undefined)
+      options.setEditor(undefined)
+      options.setToolsExpanded?.(false)
+      const base = options.getAutocompleteProvider?.()
+      if (base) options.setAutocompleteProvider?.(base)
+      changed()
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      dialogs.dispose()
+      for (const unsubscribe of [...inputSubscriptions]) unsubscribe()
+      inputSubscriptions.clear()
+    }
+  }
+}

package/src/terminal/tui/welcome.ts

@@ -0,0 +1,102 @@
+/*!
+ * Adapted from @oh-my-pi/pi-tui 18.11.3 (https://github.com/can1357/oh-my-pi).
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2025 Mario Zechner
+ * Copyright (c) 2025-2026 Can Bölük
+ * Copyright (c) 2026 Stencil Labs, Inc.
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { type Component, type TerminalColorMode, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui'
+
+import manifest from '../../../package.json'
+
+export const PI_LOGO = ['████████████', '   ██  ██   ', '   ██  ██   ', '   ▒▒  ██   ', '       ██   '] as const
+
+const GRADIENT_STOPS = [[248, 79, 204], [147, 98, 244], [0, 219, 228]] as const
+const GRADIENT_RAMP_256 = [206, 170, 134, 99, 69, 74, 44] as const
+const LOGO_WIDTH = 12
+const LOCKUP_GAP = 4
+const TIP_MEASURE = 72
+const TIP_MIN_COLUMNS = 50
+const DEFAULT_TIP = 'Use /accounts to manage sign-ins, /plugins to manage extensions, and /hub to browse reusable skills.'
+
+/** The upstream resting diagonal gradient, including its exact indexed-color fallback. */
+export function gradientLogo(lines: readonly string[], mode: TerminalColorMode): string[] {
+  const xSpan = Math.max(1, ...lines.map((line) => line.length - 1))
+  const ySpan = Math.max(1, lines.length - 1)
+  return lines.map((line, y) => [...line].map((glyph, x) => {
+    if (glyph === ' ') return glyph
+    const t = (x / xSpan + y / ySpan) / 2
+    let color: string
+    if (mode === 'truecolor') {
+      const segment = t * (GRADIENT_STOPS.length - 1)
+      const index = Math.min(GRADIENT_STOPS.length - 2, Math.floor(segment))
+      const fraction = segment - index
+      const from = GRADIENT_STOPS[index]
+      const to = GRADIENT_STOPS[index + 1]
+      const [r, g, b] = from.map((value, channel) => Math.round(value + (to[channel] - value) * fraction))
+      color = `\x1b[38;2;${r};${g};${b}m`
+    } else {
+      const index = Math.min(GRADIENT_RAMP_256.length - 1, Math.max(0, Math.floor(t * (GRADIENT_RAMP_256.length - 1) + 0.5)))
+      color = `\x1b[38;5;${GRADIENT_RAMP_256[index]}m`
+    }
+    return color + glyph + '\x1b[0m'
+  }).join(''))
+}
+
+function centerBlock(lines: readonly string[], width: number): string[] {
+  const widest = Math.max(0, ...lines.map((line) => visibleWidth(line)))
+  const indent = ' '.repeat(Math.max(0, Math.floor((width - widest) / 2)))
+  return lines.map((line) => indent + line)
+}
+
+export class HarnessWelcome implements Component {
+  constructor(
+    private readonly theme: Theme,
+    private readonly productName = 'Xingular Harness',
+    private readonly version = manifest.version,
+    private readonly tip = DEFAULT_TIP
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const room = width - 2
+    if (room < LOGO_WIDTH) return []
+    const logo = gradientLogo(PI_LOGO, this.theme.getColorMode())
+    const name = this.productName.replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+    const version = this.version.replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+    const labelWidth = Math.max(visibleWidth(name), visibleWidth(`v${version}`))
+    const lockupWidth = LOGO_WIDTH + LOCKUP_GAP + labelWidth
+    const beside = ['', this.theme.bold(this.theme.fg('text', name)), '', '', this.theme.fg('dim', `v${version}`)]
+    const art = room >= lockupWidth ? logo.map((line, index) => line + ' '.repeat(LOCKUP_GAP) + beside[index]) : logo
+    const lines = centerBlock(art, width)
+    if (width < TIP_MIN_COLUMNS || !this.tip) return lines
+    const label = 'Tip: '
+    const wrapped = wrapTextWithAnsi(label + this.tip, Math.min(room, TIP_MEASURE)).map((line) => line.trimEnd())
+    const tips = wrapped.map((line, index) => this.theme.italic(index === 0 && line.startsWith(label)
+      ? this.theme.fg('customMessageLabel', label) + this.theme.fg('muted', line.slice(label.length))
+      : this.theme.fg('muted', line)))
+    return [...lines, '', ...tips.flatMap((line) => centerBlock([line], width))]
+  }
+}

package/src/tools/askUser.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from 'vitest'
+
+import type { ActiveRun, QuestionInput } from '../sessions/registry'
+import { askUserTool, describeAnswer } from './askUser'
+
+test('ask_user requests one to five summarized questions and returns answers in order', async () => {
+  let requested: QuestionInput[] = []
+  const tool = askUserTool({
+    requestAnswers: async (questions: QuestionInput[]) => {
+      requested = questions
+      return [
+        { selected: ['Keyboard'], notes: { Keyboard: 'Keep it accessible.' } },
+        { selected: [], text: 'Next week' }
+      ]
+    }
+  } as unknown as ActiveRun)
+
+  const response = await tool.execute({ questions: [
+    { summary: 'Navigation style', question: 'Which navigation?', options: [{ label: 'Keyboard', description: 'Move through controls with keys.' }, { label: 'Pointer', description: 'Select controls with a mouse or trackpad.' }], multiSelect: true },
+    { summary: 'Delivery timing', question: 'When?', options: [{ label: 'Today', description: 'Start immediately.' }, { label: 'Next week', description: 'Start after the current week.' }], allowText: true }
+  ] })
+
+  expect(requested).toMatchObject([
+    { summary: 'Navigation style', question: 'Which navigation?', multiSelect: true, allowText: true },
+    { summary: 'Delivery timing', question: 'When?', multiSelect: false, allowText: true }
+  ])
+  expect(response).toContain('Navigation style: The user chose: Keyboard. Their note for Keyboard: Keep it accessible.')
+  expect(response).toContain('Delivery timing: The user answered: Next week')
+})
+
+test('ask_user rejects empty questions and summaries', async () => {
+  const tool = askUserTool({ requestAnswers: async () => [] } as unknown as ActiveRun)
+  await expect(tool.execute({ questions: [] })).resolves.toBe('Ask between one and five questions.')
+  await expect(tool.execute({ questions: [{ summary: '', question: 'Pick one' }] })).resolves.toBe('Each question needs a short summary of no more than 100 characters.')
+})
+
+test('ask_user requires a description for every choice', async () => {
+  let requested = false
+  const tool = askUserTool({ requestAnswers: async () => { requested = true; return [] } } as unknown as ActiveRun)
+  await expect(tool.execute({ questions: [{ summary: 'Plan choice', question: 'Which plan?', options: [{ label: 'Plan A' }] }] }))
+    .resolves.toBe('Every choice needs a short description. Aim for 25 words or fewer.')
+  expect(requested).toBe(false)
+})
+
+test('ask_user treats 25 words as guidance for questions and choice descriptions', async () => {
+  let requested: QuestionInput[] = []
+  const tool = askUserTool({
+    requestAnswers: async (questions: QuestionInput[]) => {
+      requested = questions
+      return [{ selected: ['Detailed'], notes: {} }]
+    }
+  } as unknown as ActiveRun)
+  const longQuestion = 'Which option should we choose after we consider the current project goals, delivery timing, team capacity, risks, dependencies, expected maintenance, and the needs of the people who will use the result every day?'
+  const longDescription = 'Choose this when the team wants a complete explanation with context, tradeoffs, implementation notes, assumptions, risks, and enough detail to share the decision with other reviewers.'
+  const response = await tool.execute({ questions: [{
+    summary: 'Reply detail',
+    question: longQuestion,
+    options: [{ label: 'Detailed', description: longDescription }]
+  }] })
+
+  expect(requested[0]).toMatchObject({ question: longQuestion, options: [{ label: 'Detailed', description: longDescription }] })
+  expect(response).toContain('Reply detail: The user chose: Detailed.')
+  expect(tool.description).toContain('aim to keep each question to 25 words or fewer')
+  expect(tool.description).toContain('every option must include a helpful description of 25 words or fewer')
+})
+
+test('describeAnswer includes choice-specific notes', () => {
+  expect(describeAnswer({ selected: ['A'], notes: { A: 'Keep this requirement.' } })).toBe('The user chose: A. Their note for A: Keep this requirement.')
+})