@xingular/harness 0.1.6 → 2.0.0

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 TUI } 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: TUI
+  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/terminal/tui/workingStatus.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  chooseCompletionVerb,
+  chooseWorkingVerb,
+  COMPLETION_VERBS,
+  createCompletionStatus,
+  formatWorkingDuration,
+  getWorkingSpinnerFrames,
+  SPINNER_INTERVAL_MS,
+  spinnerFrameAt,
+  WORKING_VERBS
+} from './workingStatus'
+
+describe('Claude-style working status', () => {
+  it('keeps the full default verb set and selects a stable value from one random sample', () => {
+    expect(WORKING_VERBS).toHaveLength(188)
+    expect(WORKING_VERBS).toContain('Thundering')
+    expect(WORKING_VERBS).toContain('Wandering')
+    expect(chooseWorkingVerb(() => 0)).toBe('Accomplishing')
+    expect(chooseWorkingVerb(() => 1)).toBe('Zigzagging')
+  })
+
+  it('animates the same glyph sequence, with the Ghostty-compatible ending', () => {
+    expect(getWorkingSpinnerFrames()).toEqual(['·', '✢', '✳', '✶', '✻', '✽', '✽', '✻', '✶', '✳', '✢', '·'])
+    expect(getWorkingSpinnerFrames('xterm-ghostty')).toEqual(['·', '✢', '✳', '✶', '✻', '✻', '✻', '✻', '✶', '✳', '✢', '·'])
+    const frames = getWorkingSpinnerFrames()
+    expect(SPINNER_INTERVAL_MS).toBe(80)
+    expect(spinnerFrameAt(0, frames)).toBe('·')
+    expect(spinnerFrameAt(80, frames)).toBe('✢')
+    expect(spinnerFrameAt(12 * SPINNER_INTERVAL_MS, frames)).toBe('·')
+    expect(spinnerFrameAt(-1, frames)).toBe('·')
+    expect(spinnerFrameAt(0, [])).toBe('')
+  })
+
+  it('keeps the completion verb deterministic and formats elapsed time', () => {
+    const turnId = 'turn-uuid'
+    expect(COMPLETION_VERBS).toHaveLength(8)
+    expect(chooseCompletionVerb(turnId)).toBe(chooseCompletionVerb(turnId))
+    expect(formatWorkingDuration(65_900)).toBe('1m 5s')
+    expect(formatWorkingDuration(-100)).toBe('0s')
+    expect(createCompletionStatus(turnId, 65_900)).toBe('✻ ' + chooseCompletionVerb(turnId) + ' for 1m 5s')
+  })
+})