@xingular/harness 0.1.7 → 2.0.0

package/src/terminal/tui/status.ts

@@ -1,7 +1,6 @@
-// Presentation adapted from Oh My Pi 18.11.3's band composer and status line.
+// Presentation adapted from Oh My Pi 18.11.3's status line; it sits in the footer below the prompt frame.
 // Upstream MIT license and evidence are recorded in NOTICE.md and docs/terminal-tui.md.
-import { homedir } from 'node:os'
-import { isAbsolute, relative, sep } from 'node:path'
+import { basename, sep } from 'node:path'
 import type { Theme } from '@earendil-works/pi-coding-agent'
 import { parseColor, stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
 
@@ -13,14 +12,9 @@ export interface BandState {
   thinkingLevel: string
   branch: string | null
   account?: string
-  contextPercent: number | null
-  contextWindow: number
-  costUsd: number
-  subscription: boolean
-  running: boolean
-  elapsedMs: number
-  hiddenAbove?: number
-  hiddenBelow?: number
+  inputTokens: number
+  outputTokens: number
+  tokensPerSecond: number | null
 }
 
 // OMP's shipped light theme supplies status colors separately from transcript colors.
@@ -30,80 +24,59 @@ const LIGHT_STATUS = {
 }
 const palette = (theme: Theme) => theme.appearance === 'light' ? LIGHT_STATUS : TITANIUM
 
-const EFFORT: Record<string, string> = { off: '⦸', minimal: '○', low: '◔', medium: '◑', high: '◒', xhigh: '◕', max: '◉' }
-const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+type StatusPart = { text: string; color: string }
 
 export function singleLine(text: string): string {
   return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/ +/g, ' ').trim()
 }
 
-export function displayPath(cwd: string, home = homedir()): string {
-  const inside = relative(home, cwd)
-  if (inside === '') return '~'
-  return inside !== '..' && !inside.startsWith(`..${sep}`) && !isAbsolute(inside) ? `~${sep}${inside}` : cwd
+export function displayProjectName(cwd: string): string {
+  return singleLine(basename(cwd) || cwd || sep)
 }
 
-export function formatContextWindow(tokens: number): string {
-  if (tokens >= 1_000_000) return `${Number((tokens / 1_000_000).toFixed(1))}M`
-  if (tokens >= 1000) return `${Number((tokens / 1000).toFixed(1))}K`
-  return String(Math.max(0, Math.round(tokens)))
+function tokenCount(value: number): string {
+  return Math.max(0, Number.isFinite(value) ? Math.round(value) : 0).toLocaleString('en-US')
 }
 
-function elapsed(milliseconds: number): string {
-  const seconds = Math.max(0, Math.floor(milliseconds / 1000))
-  return seconds >= 60 ? `${Math.floor(seconds / 60)}m ${seconds % 60}s` : `${seconds}s`
+function fitParts(parts: StatusPart[], width: number): StatusPart[] {
+  const fitted = parts.map(part => ({ ...part }))
+  const separator = ' | '
+  const plain = () => fitted.map(part => part.text).join(separator)
+  while (fitted.length > 1 && visibleWidth(plain()) > width) {
+    const last = fitted[fitted.length - 1]
+    const otherWidth = visibleWidth(plain()) - visibleWidth(separator) - visibleWidth(last.text)
+    const available = width - otherWidth - visibleWidth(separator)
+    if (available > 0 && available < visibleWidth(last.text)) {
+      last.text = truncateToWidth(last.text, available, '', false)
+      if (visibleWidth(plain()) <= width) return fitted
+    }
+    fitted.pop()
+  }
+  if (fitted.length && visibleWidth(plain()) > width) {
+    fitted[0].text = truncateToWidth(fitted[0].text, width, '', false)
+  }
+  return fitted
 }
 
 function color(theme: Theme, hex: string, text: string): string {
   return theme.style(text, { fg: parseColor(hex) })
 }
 
-export function contextGauge(width: number, percent: number | null, window: number, theme: Theme): string {
-  const colors = palette(theme)
-  const size = Math.max(0, Math.floor(width))
-  if (!size) return ''
-  const bounded = percent === null || !Number.isFinite(percent) ? null : Math.max(0, Math.min(100, percent))
-  const used = window > 0 ? Math.min(size, Math.max(1, Math.round((bounded ?? 0) / 100 * size))) : 0
-  const cells = Array.from({ length: size }, () => '─')
-  const percentLabel = bounded === null ? '' : `${Math.round(bounded)}%`
-  const windowLabel = window > 0 ? formatContextWindow(window) : ''
-  const end = size - windowLabel.length - 1
-  const start = Math.min(used, Math.max(1, end - percentLabel.length - 1))
-  if (percentLabel && start + percentLabel.length < end) cells.splice(start, percentLabel.length, ...percentLabel)
-  if (windowLabel && end > percentLabel.length + 2) cells.splice(end, windowLabel.length, ...windowLabel)
-  return cells.map((cell, index) => color(theme, index < used ? colors.electricBlue : colors.subtleGray, cell)).join('')
-}
-
 export function renderStatusBand(state: BandState, width: number, theme: Theme): string {
-  const colors = palette(theme)
   const size = Math.max(0, Math.floor(width))
   if (!size) return ''
-  const model = state.model
-  const effort = model?.reasoning ? EFFORT[state.thinkingLevel] ?? '○' : '⬢'
-  const name = model ? singleLine(model.name).replace(/^Claude /, '') : 'no-model'
-  const modelText = color(theme, colors.electricBlue, `${effort} ${name}`)
-  const brand = color(theme, state.running ? colors.electricBlue : '#6b7280', state.running
-    ? `${SPINNER[Math.floor(state.elapsedMs / 80) % SPINNER.length]} ${elapsed(state.elapsedMs)}` : 'π')
-  const path = singleLine(displayPath(state.cwd))
-  const separator = ` ${color(theme, colors.subtleGray, '>')} `
-  const account = state.account ? color(theme, colors.brightAluminum, singleLine(state.account)) : null
-  const branch = state.branch ? color(theme, colors.readoutGreen, `⑂ ${singleLine(state.branch)}`) : null
-  const cost = state.costUsd > 0 || state.subscription
-    ? color(theme, colors.titaniumGold, `$${state.costUsd.toFixed(2)}${state.subscription ? ' (sub)' : ''}`) : null
-  const overflow = [state.hiddenAbove ? `↑ ${state.hiddenAbove} more` : '', state.hiddenBelow ? `↓ ${state.hiddenBelow} more` : ''].filter(Boolean).join(' ')
-  const extra = overflow ? color(theme, '#6b7280', overflow) : null
-  let pathWidth = Math.min(40, visibleWidth(path))
-  let parts = [brand, modelText, color(theme, colors.brightAluminum, `📁 ${truncateToWidth(path, pathWidth)}`), account, branch, cost, extra].filter((part): part is string => part !== null)
-  const minimumGauge = state.contextWindow > 0 ? Math.min(12, Math.floor(size / 3)) : 1
-  const groupSize = () => visibleWidth(parts.join(separator)) + 3
-  while (groupSize() + minimumGauge > size && pathWidth > 8) {
-    pathWidth -= 1
-    parts[2] = color(theme, colors.brightAluminum, `📁 ${truncateToWidth(path, pathWidth)}`)
-  }
-  while (groupSize() + minimumGauge > size && parts.length > 2) parts.pop()
-  if (groupSize() + minimumGauge > size) parts = [modelText]
-  const group = truncateToWidth(` ${parts.join(separator)} `, Math.max(0, size - 1), '', false)
-  const cap = color(theme, colors.darkTitanium, '▶')
-  const gauge = contextGauge(Math.max(0, size - visibleWidth(group) - 1), state.contextPercent, state.contextWindow, theme)
-  return theme.style(group, { bg: parseColor(colors.darkTitanium) }) + cap + gauge
+  const colors = palette(theme)
+  const model = state.model ? singleLine(state.model.name).replace(/^Claude /, '') || 'no-model' : 'no-model'
+  const account = singleLine(state.account ?? '') || 'account unknown'
+  const effort = singleLine(state.thinkingLevel) || 'off'
+  const rate = state.tokensPerSecond === null || !Number.isFinite(state.tokensPerSecond)
+    ? '— tok/s' : `${Math.max(0, Math.round(state.tokensPerSecond))} tok/s`
+  const parts = fitParts([
+    { text: displayProjectName(state.cwd), color: colors.brightAluminum },
+    { text: singleLine(state.branch ?? '') || '—', color: colors.readoutGreen },
+    { text: `${account} · ${model} · ${effort}`, color: colors.electricBlue },
+    { text: `${rate} in ${tokenCount(state.inputTokens)} out ${tokenCount(state.outputTokens)}`, color: colors.titaniumGold }
+  ], size)
+  const separator = color(theme, colors.subtleGray, ' | ')
+  return parts.map(part => color(theme, part.color, part.text)).join(separator)
 }

package/src/terminal/tui/theme.ts

@@ -2,21 +2,21 @@
  * 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
@@ -27,6 +27,8 @@
  */
 import { Theme, type ThemeBg, type ThemeColor } from '@earendil-works/pi-coding-agent'
 
+const orange = { dark: '#ffb347', light: '#9a7326' } as const
+
 export const TITANIUM = {
   brushedTitanium: '#151820',
   darkTitanium: '#0f1216',
@@ -35,7 +37,7 @@ export const TITANIUM = {
   titaniumGold: '#d4c090',
   brightAluminum: '#e8ecf4',
   dimAluminum: '#9ca3b0',
-  warningAmber: '#ffb347',
+  warningAmber: orange.dark,
   readoutGreen: '#00ff88',
   alertRed: '#ff4757',
   subtleGray: '#2a3038'
@@ -48,7 +50,7 @@ const foreground = {
   borderMuted: '#1f252d',
   success: '#00ff88',
   error: '#ff4757',
-  warning: '#ffb347',
+  warning: orange.dark,
   muted: '#9ca3b0',
   dim: '#6b7280',
   text: '',
@@ -114,7 +116,7 @@ const lightForeground = {
   borderMuted: '#b0b0b0',
   success: '#588458',
   error: '#aa5555',
-  warning: '#9a7326',
+  warning: orange.light,
   muted: '#6c6c6c',
   dim: '#767676',
   text: '',
@@ -172,3 +174,12 @@ const lightBackground = {
 export function createHarnessLightTheme(base: Theme): Theme {
   return new Theme(lightForeground, lightBackground, base.getColorMode(), { name: 'light', appearance: 'light' })
 }
+
+// The composer keeps its neutral frame; the slash completion divider uses warning amber.
+export function composerRuleColor(theme: Theme): string {
+  return theme.appearance === 'light' ? '#8a8a8a' : '#888888'
+}
+
+export function autocompleteRuleColor(theme: Theme): string {
+  return theme.appearance === 'light' ? orange.light : orange.dark
+}

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

@@ -0,0 +1,99 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { stripTerminalSequences, visibleWidth, type TUI } from '@earendil-works/pi-tui'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
+import { TrajectoryPanel } from './trajectoryPanel'
+import { createHarnessTheme } from './theme'
+
+const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+const run = (id: string, status = 'completed'): TerminalTrajectoryRun => ({
+  id, mode: 'code', goal: `Goal for ${id}`, startedAt: '2026-10-18T00:00:00.000Z', endedAt: status === 'running' ? null : '2026-10-18T00:00:02.000Z', status
+})
+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 setup(options: { runs?: TerminalTrajectoryRun[]; snapshot?: TerminalTrajectorySnapshot; read?: (runId: string, afterSequence?: number) => Promise<TerminalTrajectorySnapshot>; rows?: number } = {}) {
+  const events = [
+    event(0, 'context.snapshot', { systemPrompt: 'prompt', tools: [{ name: 'read' }] }),
+    event(1, 'tool.started', { toolCallId: 'tool-1', name: 'read', input: '{"path":"README.md"}' }),
+    event(2, 'tool.completed', { toolCallId: 'tool-1', name: 'read', output: 'file contents', ok: true })
+  ]
+  const runs = options.runs ?? [run('run-1')]
+  const initial = options.snapshot ?? { run: runs[0]!, events }
+  const read = options.read ?? vi.fn(async () => initial)
+  const copy = vi.fn(async (_text: string) => {})
+  const changed = vi.fn()
+  const notify = vi.fn()
+  const close = vi.fn()
+  const panel = new TrajectoryPanel({
+    tui: { terminal: { rows: options.rows ?? 28 } } as unknown as TUI,
+    theme, runs, initialIndex: 0, initial, read, copy, changed, notify, close
+  })
+  return { panel, events, runs, read, copy, changed, notify, close }
+}
+
+afterEach(() => vi.useRealTimers())
+
+describe('the terminal Trajectory panel', () => {
+  it('shows run usage, a selectable event ledger, and the selected event payload', () => {
+    const { panel } = setup()
+    const text = panel.render(100).map(stripTerminalSequences).join('\n')
+    expect(text).toContain('Run 1/1 · run-1 · completed')
+    expect(text).toContain('context.snapshot')
+    expect(text).toContain('tool.completed')
+    expect(text).toContain('file contents')
+    expect(panel.selectedEvent?.sequence).toBe(2)
+
+    panel.handleInput('\x1b[A')
+    expect(panel.selectedEvent?.sequence).toBe(1)
+    expect(panel.render(100).map(stripTerminalSequences).join('\n')).toContain('README.md')
+  })
+
+  it('moves between runs, closes, and copies the selected event', async () => {
+    const first = run('run-1')
+    const second = run('run-2')
+    const secondSnapshot = { run: second, events: [event(0, 'message.completed', { role: 'assistant', text: 'Second run' })] }
+    const { panel, read, copy, close } = setup({ runs: [first, second], read: vi.fn(async (id) => id === 'run-2' ? secondSnapshot : { run: first, events: [] }) })
+    panel.handleInput('\x1b[D')
+    await vi.waitFor(() => expect(panel.selectedRunId).toBe('run-2'))
+    expect(read).toHaveBeenCalledWith('run-2')
+    expect(panel.selectedEvent?.type).toBe('message.completed')
+    panel.handleInput('c')
+    await vi.waitFor(() => expect(copy).toHaveBeenCalledOnce())
+    expect(JSON.parse(copy.mock.calls[0]![0])).toMatchObject({ type: 'message.completed', sequence: 0 })
+    panel.handleInput('\x1b')
+    expect(close).toHaveBeenCalledOnce()
+    panel.dispose()
+  })
+
+  it('refreshes active runs and stops polling when disposed', async () => {
+    vi.useFakeTimers()
+    const active = run('run-1', 'running')
+    const completed = run('run-1')
+    const initial = { run: active, events: [event(0, 'started', {})] }
+    const updated = { run: completed, events: [event(1, 'completed', {})] }
+    const read = vi.fn(async (_id: string, afterSequence?: number) => afterSequence === 0 ? updated : initial)
+    const { panel } = setup({ snapshot: initial, read })
+    await vi.advanceTimersByTimeAsync(2_000)
+    expect(read).toHaveBeenCalledWith('run-1', 0)
+    expect(panel.render(100).map(stripTerminalSequences).join('\n')).toContain('completed')
+    const calls = read.mock.calls.length
+    panel.dispose()
+    await vi.advanceTimersByTimeAsync(4_000)
+    expect(read).toHaveBeenCalledTimes(calls)
+  })
+
+  it('bounds output to narrow terminals and handles runs without recorded events', () => {
+    const { panel } = setup({ snapshot: { run: run('run-1'), events: [] }, rows: 10 })
+    const rows = panel.render(24)
+    expect(rows.length).toBeLessThanOrEqual(5)
+    for (const row of rows) expect(visibleWidth(row)).toBeLessThanOrEqual(24)
+    expect(rows.map(stripTerminalSequences).join('\n')).toContain('No recorded events')
+    panel.handleInput('\x1b[B')
+    expect(panel.selectedEvent).toBeUndefined()
+    panel.dispose()
+  })
+})

package/src/terminal/tui/trajectoryPanel.ts

@@ -0,0 +1,226 @@
+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 type { RunEvent } from '../../sessions/contracts'
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
+
+const ACTIVE = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input'])
+type Payload = Record<string, unknown>
+
+const payloadOf = (event: RunEvent): Payload => event.payload && typeof event.payload === 'object' ? event.payload as Payload : {}
+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(value: string): string {
+  return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ')
+}
+
+function timeOf(value: string): string {
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? new Date(parsed).toLocaleTimeString() : value
+}
+
+function eventDescription(event: RunEvent): string {
+  const payload = payloadOf(event)
+  switch (event.type) {
+    case 'message.completed':
+    case 'message.delta':
+      return `${stringOf(payload.role) ?? 'message'}: ${stringOf(payload.text)?.replace(/\s+/g, ' ').slice(0, 90) ?? ''}`
+    case 'tool.started':
+    case 'tool.completed':
+      return `${stringOf(payload.name) ?? 'tool'}${stringOf(payload.summary) ? ` · ${stringOf(payload.summary)}` : ''}`
+    case 'usage.updated': {
+      const request = payload.request && typeof payload.request === 'object' ? payload.request as Payload : {}
+      return `${stringOf(request.model) ?? stringOf(payload.model) ?? 'model'} · request ${numberOf(request.index) ?? numberOf(payload.requests) ?? '?'} · ${numberOf(request.durationMs) ?? 0} ms`
+    }
+    case 'status.changed':
+      return stringOf(payload.status) ?? 'status update'
+    case 'retry.started':
+    case 'retry.ended':
+      return `attempt ${numberOf(payload.attempt) ?? 1}${stringOf(payload.error) ? ` · ${stringOf(payload.error)}` : ''}`
+    case 'compaction.started':
+    case 'compaction.ended':
+      return stringOf(payload.reason) ?? 'context compaction'
+    case 'extension.notice':
+      return stringOf(payload.text) ?? 'extension notice'
+    case 'context.snapshot':
+      return 'Recorded prompt and tool definitions'
+    case 'failed':
+      return stringOf(payload.message) ?? stringOf(payload.code) ?? 'run failed'
+    default:
+      return stringOf(payload.text) ?? stringOf(payload.name) ?? ''
+  }
+}
+
+function usageLine(events: readonly RunEvent[]): string {
+  const event = [...events].reverse().find(item => item.type === 'usage.updated')
+  if (!event) return 'Usage not recorded'
+  const payload = payloadOf(event)
+  const tokens = (name: string) => numberOf(payload[name])?.toLocaleString() ?? '—'
+  const cost = numberOf(payload.costUsd)
+  const requests = numberOf(payload.requests)
+  return `Input ${tokens('inputTokens')} · Output ${tokens('outputTokens')} · Cache read ${tokens('cacheReadTokens')} · ${requests ?? 0} requests · ${cost === undefined ? 'cost —' : `$${cost.toFixed(4)}`}`
+}
+
+function durationLine(run: TerminalTrajectoryRun): string {
+  const start = Date.parse(run.startedAt)
+  const end = run.endedAt ? Date.parse(run.endedAt) : Date.now()
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return run.startedAt
+  return `${((Math.max(0, end - start)) / 1000).toFixed(1)} s · ${timeOf(run.startedAt)}`
+}
+
+export interface TrajectoryPanelOptions {
+  tui: TUI
+  theme: Theme
+  runs: TerminalTrajectoryRun[]
+  initialIndex: number
+  initial: TerminalTrajectorySnapshot
+  read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>
+  copy(text: string): Promise<void>
+  close(): void
+  changed(): void
+  notify(message: string, type?: string): void
+}
+
+/** Read-only view of saved run evidence, scoped by its source before it reaches this component. */
+export class TrajectoryPanel implements Component, Focusable {
+  private runIndex: number
+  private run: TerminalTrajectoryRun
+  private events: RunEvent[]
+  private selected = 0
+  private detailOffset = 0
+  private focusedValue = false
+  private loading = false
+  private disposed = false
+  private timer: ReturnType<typeof setInterval>
+  private error?: string
+
+  constructor(private readonly options: TrajectoryPanelOptions) {
+    this.runIndex = Math.max(0, Math.min(options.runs.length - 1, options.initialIndex))
+    this.run = options.initial.run
+    this.events = options.initial.events.slice().sort((left, right) => left.sequence - right.sequence)
+    this.selected = Math.max(0, this.events.length - 1)
+    this.timer = setInterval(() => { void this.refresh() }, 2_000)
+    this.timer.unref?.()
+  }
+
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value }
+  get selectedRunId(): string { return this.run.id }
+  get selectedEvent(): RunEvent | undefined { return this.events[this.selected] }
+
+  invalidate(): void { this.options.changed() }
+
+  private async refresh(): Promise<void> {
+    if (this.disposed || this.loading || !ACTIVE.has(this.run.status)) return
+    this.loading = true
+    const lastSequence = this.events.at(-1)?.sequence
+    const followedLatest = this.selected === this.events.length - 1
+    try {
+      const snapshot = await this.options.read(this.run.id, lastSequence)
+      if (this.disposed) return
+      this.run = snapshot.run
+      if (lastSequence === undefined) this.events = snapshot.events.slice().sort((left, right) => left.sequence - right.sequence)
+      else {
+        const existing = new Set(this.events.map(event => event.sequence))
+        this.events = [...this.events, ...snapshot.events.filter(event => !existing.has(event.sequence))].sort((left, right) => left.sequence - right.sequence)
+      }
+      if (followedLatest && this.events.length) this.selected = this.events.length - 1
+      this.error = undefined
+    } catch (error) {
+      if (!this.disposed) this.error = error instanceof Error ? error.message : String(error)
+    } finally {
+      this.loading = false
+      if (!this.disposed) this.options.changed()
+    }
+  }
+
+  private async changeRun(direction: -1 | 1): Promise<void> {
+    const next = this.runIndex + direction
+    if (next < 0 || next >= this.options.runs.length || this.loading) return
+    this.runIndex = next
+    this.run = this.options.runs[next]!
+    this.events = []
+    this.selected = 0
+    this.detailOffset = 0
+    this.error = undefined
+    this.options.changed()
+    this.loading = true
+    try {
+      const snapshot = await this.options.read(this.run.id)
+      if (this.disposed || this.run.id !== snapshot.run.id) return
+      this.run = snapshot.run
+      this.events = snapshot.events.slice().sort((left, right) => left.sequence - right.sequence)
+      this.selected = Math.max(0, this.events.length - 1)
+    } catch (error) {
+      if (!this.disposed) this.error = error instanceof Error ? error.message : String(error)
+    } finally {
+      this.loading = false
+      if (!this.disposed) this.options.changed()
+    }
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) { this.options.close(); return }
+    if (matchesKey(data, 'left')) { void this.changeRun(1); return }
+    if (matchesKey(data, 'right')) { void this.changeRun(-1); return }
+    if (matchesKey(data, 'up')) { this.selected = Math.max(0, this.selected - 1); this.detailOffset = 0; this.options.changed(); return }
+    if (matchesKey(data, 'down')) { this.selected = this.events.length ? Math.min(this.events.length - 1, this.selected + 1) : 0; this.detailOffset = 0; this.options.changed(); return }
+    if (matchesKey(data, 'pageUp')) { this.detailOffset = Math.max(0, this.detailOffset - 8); this.options.changed(); return }
+    if (matchesKey(data, 'pageDown')) { this.detailOffset += 8; this.options.changed(); return }
+    if (data.toLowerCase() === 'c' && this.selectedEvent) {
+      const text = JSON.stringify(this.selectedEvent, null, 2)
+      void this.options.copy(text).then(() => this.options.notify('Copied selected trajectory event')).catch(error => this.options.notify(String(error), 'error'))
+    }
+  }
+
+  render(width: number): string[] {
+    width = Math.max(0, Math.trunc(width))
+    const bodyRows = Math.max(0, Math.floor(this.options.tui.terminal.rows * 0.8) - 3)
+    if (!width || !bodyRows) return []
+    const { theme } = this.options
+    const runPosition = `${this.runIndex + 1}/${this.options.runs.length}`
+    const modelEvent = [...this.events].reverse().find(event => event.type === 'usage.updated')
+    const usage = modelEvent ? payloadOf(modelEvent) : {}
+    const model = stringOf(usage.model) ?? 'model unavailable'
+    const lines = [theme.bold(theme.fg('accent', `Run ${runPosition} · ${this.run.id} · ${this.run.status}${this.loading ? ' · loading' : ''}`))]
+    if (bodyRows >= 9) {
+      lines.push(theme.fg('muted', `${model} · ${durationLine(this.run)} · ${this.run.mode}`))
+      lines.push(theme.fg('muted', usageLine(this.events)))
+      lines.push(this.run.goal ? theme.fg('dim', `Prompt: ${this.run.goal.replace(/\s+/g, ' ').slice(0, 140)}`) : theme.fg('dim', 'Prompt text unavailable'))
+    } else if (bodyRows >= 6) {
+      lines.push(theme.fg('muted', `${model} · ${durationLine(this.run)}`))
+    }
+
+    lines.push(theme.bold('Events'))
+    if (this.error) lines.push(theme.fg('error', `Read error: ${this.error}`))
+    if (!this.events.length) lines.push(theme.fg('dim', this.loading ? 'Loading recorded events…' : 'No recorded events'))
+    const structural = lines.length + 2
+    const available = Math.max(0, bodyRows - structural - 1)
+    const ledgerBudget = this.events.length ? Math.min(this.events.length, Math.max(1, Math.floor(available * 0.4))) : 0
+    const detailBudget = Math.max(0, available - ledgerBudget)
+    const firstEvent = Math.max(0, Math.min(this.events.length - ledgerBudget, this.selected - Math.floor(ledgerBudget / 2)))
+    for (let offset = 0; offset < ledgerBudget; offset++) {
+      const index = firstEvent + offset
+      const event = this.events[index]!
+      const prefix = index === this.selected ? '❯' : ' '
+      const label = `${prefix} ${timeOf(event.timestamp)}  ${event.type}  ${eventDescription(event)}`
+      lines.push(index === this.selected ? theme.bg('selectedBg', theme.fg('text', label)) : theme.fg('muted', label))
+    }
+
+    const selected = this.selectedEvent
+    lines.push(theme.bold(selected ? `Selected event · ${selected.type} · #${selected.sequence}` : 'Selected event'))
+    if (selected) {
+      const details = wrapTextWithAnsi(safe(JSON.stringify({ payload: selected.payload, type: selected.type, sequence: selected.sequence, timestamp: selected.timestamp }, null, 2)), width)
+      const maxOffset = Math.max(0, details.length - detailBudget)
+      this.detailOffset = Math.min(this.detailOffset, maxOffset)
+      lines.push(...details.slice(this.detailOffset, this.detailOffset + detailBudget).map(line => theme.fg('dim', line)))
+    }
+    return lines.slice(0, bodyRows).map(line => truncateToWidth(line, width, ''))
+  }
+
+  dispose(): void {
+    this.disposed = true
+    clearInterval(this.timer)
+  }
+}

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

@@ -23,3 +23,17 @@ it('detaches all custom transcript components before their session is invalidate
   transcript.clearSession()
   expect(second.dispose).toHaveBeenCalledOnce()
 })
+
+it('keeps notices in the conversation order and drops them with the session', () => {
+  const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
+  const transcript = new TerminalTranscript({} as TUI, () => theme, () => undefined)
+  transcript.notice('Plan mode: only read-only tools are available.', 'info')
+  transcript.notice('Plan mode could not start.', 'error')
+  transcript.notice('Plan mode could not start.', 'error')
+  const lines = transcript.render(80).map(line => line.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean)
+  expect(lines).toEqual(['Plan mode: only read-only tools are available.', 'Plan mode could not start.'])
+  transcript.notice('Plan mode: only read-only tools are available.', 'info')
+  expect(transcript.render(80).map(line => line.replace(/\x1b\[[0-9;]*m/g, '').trim()).filter(Boolean)).toHaveLength(3)
+  transcript.clearSession()
+  expect(transcript.render(80)).toEqual([])
+})

package/src/terminal/tui/transcript.ts

@@ -13,6 +13,7 @@ export class TerminalTranscript extends Container {
   private hideThinking = false
   private expanded = false
   private hiddenLabel = 'Thinking…'
+  private lastNotice?: { component: Component; text: string; type: string }
 
   constructor(private readonly tui: TUI, private readonly theme: () => Theme, private readonly builtinRenderers: BuiltinRenderers) { super() }
 
@@ -26,6 +27,16 @@ export class TerminalTranscript extends Container {
     this.session = undefined
   }
 
+  /** A line of terminal feedback, such as a mode change or an error. It sits in the conversation where it happened, not in the session. */
+  notice(text: string, type: string): void {
+    // A failure that repeats with nothing after it, such as a draft that cannot be saved on each keystroke, is shown once.
+    const last = this.lastNotice
+    if (last && last.text === text && last.type === type && this.children.at(-1) === last.component) return
+    const component = new Text(this.theme().fg(type === 'error' ? 'error' : type === 'warning' ? 'warning' : 'muted', text), 1, 1)
+    this.addChild(component)
+    this.lastNotice = { component, text, type }
+  }
+
   bind(session: AgentSession): void {
     this.clearSession()
     this.session = session

package/src/terminal/tui/ui.ts

@@ -1,5 +1,5 @@
 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 { stripTerminalSequences, type AutocompleteProvider, type EditorComponent, type TUI } from '@earendil-works/pi-tui'
 
 import { TerminalDialogs } from './dialogs'
 
@@ -18,7 +18,7 @@ export interface TerminalUiState {
   autocompleteFactories: AutocompleteProviderFactory[]
 }
 export interface TerminalUiOptions {
-  tui: TuiMainScreen
+  tui: TUI
   theme: Theme
   keybindings: KeybindingsManager
   changed(): void

package/src/terminal/tui/welcome.ts

@@ -2,21 +2,21 @@
  * 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