@xingular/harness 2.1.1 → 3.0.0

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

@@ -3,7 +3,17 @@ import { stripTerminalSequences } from '@earendil-works/pi-tui'
 import { describe, expect, it, vi } from 'vitest'
 
 vi.mock('../control', () => ({ controlCall: vi.fn(async () => ({})) }))
+vi.mock('./piAdapter', async importOriginal => ({
+  ...await importOriginal<typeof import('./piAdapter')>(),
+  loadPiAdapter: vi.fn()
+}))
+vi.mock('./clipboardFiles', async importOriginal => ({
+  ...await importOriginal<typeof import('./clipboardFiles')>(),
+  stageClipboardFiles: vi.fn()
+}))
 import { controlCall } from '../control'
+import { loadPiAdapter, type PiAdapter } from './piAdapter'
+import { stageClipboardFiles } from './clipboardFiles'
 import { TerminalApplication } from './application'
 import { createTerminalCommands } from './commands'
 import type { TerminalDecision } from './runtime'
@@ -62,6 +72,54 @@ function setup() {
 }
 
 describe('the owned terminal application', () => {
+  it('pastes staged Finder image paths and removes their temporary files on shutdown', async () => {
+    const { application, app, ui } = setup()
+    const paths = ['/Photos/portrait.heic', '/work/notes.md']
+    const pasteToEditor = vi.fn()
+    const shutdownOrder: string[] = []
+    const cleanup = vi.fn(async () => { shutdownOrder.push('clipboard files removed') })
+    const adapter = {
+      builtins: [], setTheme: vi.fn(), withBuiltInRenderers: vi.fn(),
+      readClipboardText: vi.fn(async () => null), readClipboardFilePaths: vi.fn(async () => paths),
+      readClipboardImage: vi.fn(async () => null), extensionForImageMimeType: vi.fn(() => null)
+    }
+    Object.assign(ui, { pasteToEditor })
+    vi.mocked(loadPiAdapter).mockResolvedValue(adapter as unknown as PiAdapter)
+    vi.mocked(stageClipboardFiles).mockResolvedValue({ paths: ['/tmp/prepared.png', paths[1]!], cleanup })
+    app.runtime.dispose.mockImplementation(async () => { shutdownOrder.push('runtime disposed') })
+
+    await (application as unknown as { pasteClipboard(): Promise<void> }).pasteClipboard()
+
+    expect(stageClipboardFiles).toHaveBeenCalledWith(paths)
+    expect(adapter.readClipboardImage).not.toHaveBeenCalled()
+    expect(pasteToEditor).toHaveBeenCalledWith(`/tmp/prepared.png\n${paths[1]}`)
+    await application.shutdown()
+    expect(cleanup).toHaveBeenCalledOnce()
+    expect(shutdownOrder).toEqual(['runtime disposed', 'clipboard files removed'])
+  })
+
+  it('leaves the prompt unchanged and reports an error when clipboard staging fails', async () => {
+    const { application, app, ui } = setup()
+    const message = 'Could not prepare HEIC image "portrait.heic" for the terminal.'
+    const adapter = {
+      builtins: [], setTheme: vi.fn(), withBuiltInRenderers: vi.fn(),
+      readClipboardText: vi.fn(async () => null), readClipboardFilePaths: vi.fn(async () => ['/Photos/portrait.heic']),
+      readClipboardImage: vi.fn(async () => null), extensionForImageMimeType: vi.fn(() => null)
+    }
+    const pasteToEditor = vi.fn()
+    const notice = vi.spyOn(app.transcript, 'notice')
+    Object.assign(ui, { pasteToEditor })
+    vi.mocked(loadPiAdapter).mockResolvedValue(adapter as unknown as PiAdapter)
+    vi.mocked(stageClipboardFiles).mockRejectedValueOnce(new Error(message))
+    const pasteClipboard = (application as unknown as { pasteClipboard(): Promise<void> }).pasteClipboard.bind(application)
+    ;(application as unknown as { attempt(action: () => Promise<void>): void }).attempt(() => pasteClipboard())
+
+    await vi.waitFor(() => expect(notice).toHaveBeenCalledWith(message, 'error'))
+
+    expect(pasteToEditor).not.toHaveBeenCalled()
+    await application.shutdown()
+  })
+
   it('shows a stable animated verb, then keeps completion status until the next turn', async () => {
     const { application, app } = setup()
     let now = 1000

package/src/terminal/tui/application.ts

@@ -24,7 +24,9 @@ import { createTerminalUi, type TerminalUi } from './ui'
 import { chooseWorkingVerb, createCompletionStatus, getWorkingSpinnerFrames, SPINNER_INTERVAL_MS, spinnerFrameAt } from './workingStatus'
 import { HarnessWelcome } from './welcome'
 import { answerTerminalQuestion } from './questions'
+import { stageClipboardFiles } from './clipboardFiles'
 import type { QuestionAnswer } from '../../sessions/registry'
+import { readHarnessLogSnapshot, type HarnessLogChunk, type HarnessLogInfo } from '../logs'
 import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
 
 const exec = promisify(execFile)
@@ -113,7 +115,7 @@ export class TerminalApplication {
   private failure?: Error
   private finish!: () => void
   private done = new Promise<void>(resolve => { this.finish = resolve })
-  private cleanup: (() => void)[] = []
+  private cleanup: (() => void | Promise<void>)[] = []
   private finalCleanup: (() => void)[] = []
   private draftSync = Promise.resolve()
   private lastInput = ''
@@ -190,6 +192,10 @@ export class TerminalApplication {
         plan: brief => this.enqueuePlan(brief),
         copyText: copyToClipboard, openExternal,
         changed: this.change,
+        logs: { read: () => readHarnessLogSnapshot(
+          () => controlCall<HarnessLogInfo>('terminal.logs.info'),
+          (snapshotSize, offset) => controlCall<HarnessLogChunk>('terminal.logs.read', { snapshotSize, offset })
+        ) },
         trajectory: {
           list: async () => (await controlCall<{ runs: TerminalTrajectoryRun[] }>('terminal.trajectory.list')).runs,
           read: (runId, afterSequence) => controlCall<TerminalTrajectorySnapshot>('terminal.trajectory.events', { runId, ...(afterSequence === undefined ? {} : { afterSequence }) })
@@ -643,7 +649,9 @@ export class TerminalApplication {
     const files = await adapter.readClipboardFilePaths()
     if (files?.length) {
       if (files.some(file => /[\x00-\x1f\x7f]/.test(file))) throw new Error('Clipboard file paths contain control characters.')
-      this.ui.pasteToEditor(files.join('\n'))
+      const staged = await stageClipboardFiles(files)
+      if (staged.cleanup) this.cleanup.push(staged.cleanup)
+      this.ui.pasteToEditor(staged.paths.join('\n'))
       return
     }
     const image = await adapter.readClipboardImage()
@@ -651,7 +659,7 @@ export class TerminalApplication {
       const directory = await mkdtemp(join(tmpdir(), 'harness-clipboard-'))
       const file = join(directory, `${randomUUID()}.${adapter.extensionForImageMimeType(image.mimeType) ?? 'png'}`)
       await writeFile(file, image.bytes, { mode: 0o600 })
-      this.cleanup.push(() => { void rm(directory, { recursive: true, force: true }) })
+      this.cleanup.push(() => rm(directory, { recursive: true, force: true }))
       this.ui.pasteToEditor(file)
       return
     }
@@ -684,12 +692,15 @@ export class TerminalApplication {
       this.stopped = true
       protect(() => this.pendingAbort?.abort())
       protect(() => this.ui?.dispose())
-      for (const cleanup of this.cleanup.splice(0)) protect(cleanup)
       // Captured while the runtime and its components still exist; written only after the alternate screen is left.
       const scrollback = this.exitScrollback()
       try { await this.runtime?.dispose() }
       catch (error) { this.failure ??= error instanceof Error ? error : new Error(String(error)) }
       finally {
+        for (const cleanup of this.cleanup.splice(0)) {
+          try { await cleanup() }
+          catch (error) { this.failure ??= error instanceof Error ? error : new Error(String(error)) }
+        }
         await this.terminal.drainInput(200, 30).catch(() => {})
         protect(() => this.tui.stop())
         if (scrollback) protect(() => writeScrollback(this.terminal, scrollback))

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

@@ -0,0 +1,94 @@
+import { execFile } from 'node:child_process'
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { promisify } from 'node:util'
+import { describe, expect, it, vi } from 'vitest'
+import { stageClipboardFiles } from './clipboardFiles'
+
+const exec = promisify(execFile)
+const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+async function createRoot() {
+  const root = await mkdtemp(join(tmpdir(), 'harness-heic-test-'))
+  return root
+}
+
+describe('clipboard image files', () => {
+  it('converts HEIC and HEIF paths to private PNGs while preserving order and other paths', async () => {
+    const root = await createRoot()
+    const convert = vi.fn(async (_source: string, output: string) => { await writeFile(output, pngSignature) })
+    const staged = await stageClipboardFiles([
+      '/Photos/first photo.HEIC',
+      '/work/notes.md',
+      '/Photos/second.heif'
+    ], { platform: 'darwin', tempRoot: root, convert })
+
+    expect(staged.paths).toHaveLength(3)
+    expect(staged.paths[0]).toMatch(/\.png$/)
+    expect(staged.paths[1]).toBe('/work/notes.md')
+    expect(staged.paths[2]).toMatch(/\.png$/)
+    expect(convert.mock.calls.map(([source]) => source)).toEqual(['/Photos/first photo.HEIC', '/Photos/second.heif'])
+    expect(await readFile(staged.paths[0])).toEqual(pngSignature)
+    expect(await readFile(staged.paths[2])).toEqual(pngSignature)
+
+    await staged.cleanup?.()
+    await expect(readdir(dirname(staged.paths[0]))).rejects.toThrow()
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('leaves clipboard paths unchanged on non-macOS platforms', async () => {
+    const convert = vi.fn(async () => {})
+    const paths = ['/Photos/portrait.heic', '/work/notes.md']
+
+    const staged = await stageClipboardFiles(paths, { platform: 'linux', convert })
+
+    expect(staged.paths).toEqual(paths)
+    expect(staged.cleanup).toBeUndefined()
+    expect(convert).not.toHaveBeenCalled()
+  })
+
+  it('cleans staged files and rejects the whole paste if conversion fails', async () => {
+    const root = await createRoot()
+    const convert = vi.fn(async (source: string, output: string) => {
+      if (source.endsWith('broken.heic')) throw new Error('decode failed')
+      await writeFile(output, pngSignature)
+    })
+
+    await expect(stageClipboardFiles([
+      '/Photos/valid.heic',
+      '/Photos/broken.heic'
+    ], { platform: 'darwin', tempRoot: root, convert })).rejects.toThrow('Could not prepare HEIC image "broken.heic" for the terminal.')
+    expect(await readdir(root)).toEqual([])
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it('rejects an empty or non-PNG conversion result', async () => {
+    const root = await createRoot()
+    await expect(stageClipboardFiles(['/Photos/invalid.heic'], {
+      platform: 'darwin',
+      tempRoot: root,
+      convert: async (_source, output) => { await writeFile(output, 'not a PNG') }
+    })).rejects.toThrow('Could not prepare HEIC image "invalid.heic" for the terminal.')
+    expect(await readdir(root)).toEqual([])
+    await rm(root, { recursive: true, force: true })
+  })
+
+  it.skipIf(process.platform !== 'darwin')('converts a real HEIC file with macOS sips without changing the original', async () => {
+    const root = await createRoot()
+    const sourcePng = join(root, 'pixel.png')
+    const sourceHeic = join(root, 'portrait.heic')
+    await writeFile(sourcePng, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64'))
+    await exec('/usr/bin/sips', ['-s', 'format', 'heic', sourcePng, '--out', sourceHeic])
+    const original = await readFile(sourceHeic)
+
+    const staged = await stageClipboardFiles([sourceHeic], { tempRoot: root })
+    expect(staged.paths[0]).not.toBe(sourceHeic)
+    expect((await readFile(staged.paths[0]!)).subarray(0, 8)).toEqual(pngSignature)
+    expect(await readFile(sourceHeic)).toEqual(original)
+
+    await staged.cleanup?.()
+    expect((await readdir(root)).sort()).toEqual(['pixel.png', 'portrait.heic'])
+    await rm(root, { recursive: true, force: true })
+  })
+})

package/src/terminal/tui/clipboardFiles.ts

@@ -0,0 +1,86 @@
+import { execFile } from 'node:child_process'
+import { chmod, mkdtemp, open, rm, stat } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { promisify } from 'node:util'
+
+const exec = promisify(execFile)
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+export interface ClipboardFileOptions {
+  platform?: NodeJS.Platform
+  tempRoot?: string
+  convert?: (source: string, output: string) => Promise<void>
+}
+
+export interface StagedClipboardFiles {
+  paths: string[]
+  cleanup?: () => Promise<void>
+}
+
+function isHeicPath(path: string): boolean {
+  return /\.hei[cf]$/i.test(path)
+}
+
+async function convertWithSips(source: string, output: string): Promise<void> {
+  await exec('/usr/bin/sips', ['-s', 'format', 'png', source, '--out', output], {
+    timeout: 30_000,
+    maxBuffer: 1024 * 1024
+  })
+}
+
+async function assertPng(path: string): Promise<void> {
+  const info = await stat(path)
+  if (!info.isFile() || info.size < PNG_SIGNATURE.length) throw new Error('Conversion did not create an image.')
+
+  const file = await open(path, 'r')
+  try {
+    const signature = Buffer.alloc(PNG_SIGNATURE.length)
+    const { bytesRead } = await file.read(signature, 0, signature.length, 0)
+    if (bytesRead !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) throw new Error('Conversion did not create a PNG image.')
+  } finally {
+    await file.close()
+  }
+}
+
+/** Convert Finder-copied HEIC/HEIF paths to images that Pi's terminal reader can consume. */
+export async function stageClipboardFiles(paths: string[], options: ClipboardFileOptions = {}): Promise<StagedClipboardFiles> {
+  const platform = options.platform ?? process.platform
+  if (platform !== 'darwin' || !paths.some(isHeicPath)) return { paths }
+
+  let directory: string | undefined
+  try {
+    directory = await mkdtemp(join(options.tempRoot ?? tmpdir(), 'harness-clipboard-'))
+    const stagedPaths: string[] = []
+    for (const [index, path] of paths.entries()) {
+      if (!isHeicPath(path)) {
+        stagedPaths.push(path)
+        continue
+      }
+
+      const output = join(directory, `${index}-${randomUUID()}.png`)
+      try {
+        await (options.convert ?? convertWithSips)(path, output)
+        await chmod(output, 0o600)
+        await assertPng(output)
+      } catch {
+        throw new Error(`Could not prepare HEIC image "${basename(path)}" for the terminal.`)
+      }
+      stagedPaths.push(output)
+    }
+
+    let cleaned = false
+    return {
+      paths: stagedPaths,
+      cleanup: async () => {
+        if (cleaned || !directory) return
+        cleaned = true
+        await rm(directory, { recursive: true, force: true })
+      }
+    }
+  } catch (error) {
+    if (directory) await rm(directory, { recursive: true, force: true }).catch(() => {})
+    throw error
+  }
+}

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

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

package/src/terminal/tui/commands.ts

@@ -6,6 +6,7 @@ import { promisify } from 'node:util'
 import { ModelSelectorComponent, TreeSelectorComponent, SessionManager, type AgentSession, type ExtensionUIContext } from '@earendil-works/pi-coding-agent'
 import { SettingsPanel, type TerminalSettingItem } from './settings'
 import { DialogPanel, SearchableSelect } from './dialogs'
+import { LogPanel, formatRunEventLog } from './logPanel'
 import { TrajectoryPanel } from './trajectoryPanel'
 import { expandSkillInvocation, type SkillEntry } from './skillInvocation'
 import manifest from '../../../package.json'
@@ -30,6 +31,7 @@ export interface TerminalCommandHost {
   suspend?(): Promise<void>
   hotkeys?(): string
   changelog?(): Promise<string>
+  logs: { read(): Promise<string> }
   trajectory: {
     list(): Promise<TerminalTrajectoryRun[]>
     read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>
@@ -54,6 +56,7 @@ const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'name', description: 'Name the current session' },
   { name: 'session', description: 'Current session statistics' },
   { name: 'trajectory', description: 'Inspect recorded runs for this native session' },
+  { name: 'log', description: 'View Harness diagnostics and this conversation run events' },
   { name: 'compact', description: 'Compact the current context' },
   { name: 'reload', description: 'Reload trusted resources and keyboard bindings' },
   { name: 'trust', description: 'Review plugin code and project trust' },
@@ -230,6 +233,18 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '90%' } })
   }
 
+  async function logs() {
+    const [diagnostics, runs] = await Promise.all([host.logs.read(), host.trajectory.list()])
+    const snapshots = await Promise.all(runs.map(run => host.trajectory.read(run.id)))
+    const sections = [
+      { title: 'Harness diagnostics', text: diagnostics || 'No Harness diagnostics have been captured by this host.' },
+      { title: 'Conversation run events', text: formatRunEventLog(snapshots) }
+    ]
+    await host.ui.custom<void>((tui, theme, _keys, done) => new LogPanel({
+      tui, theme, sections, close: () => done(undefined), changed: host.changed
+    }), { overlay: true, overlayOptions: { width: '100%', maxHeight: '100%', anchor: 'top-left' } })
+  }
+
   async function permissions() {
     for (;;) {
       const runtime = host.runtime()
@@ -387,6 +402,7 @@ export function createTerminalCommands(host: TerminalCommandHost) {
         }
         case 'session': notify(JSON.stringify(session.getSessionStats(), null, 2)); break
         case 'trajectory': await trajectory(argument); break
+        case 'log': await logs(); break
         case 'compact': await session.compact(argument || undefined); break
         case 'reload': await host.runtime().reload(); notify('Trusted resources reloaded'); break
         case 'trust': {

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

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

package/src/terminal/tui/logPanel.ts

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