dsh-code 0.4.0 → 0.5.0

package/src/kernel-panels.ts

@@ -0,0 +1,254 @@
+/** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
+
+import { createElement, useEffect, useMemo, useRef, useState, type ReactElement } from 'react'
+import { Box, Text, useInput, useStdout } from 'ink'
+import type { PresetRow } from './presets.ts'
+import type { PluginRow } from './plugin-inventory.ts'
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts'
+import { panelViewport, revealRow } from './render/inspector.ts'
+import { textLines } from './render/lines.ts'
+import { singleLineText, truncateColumns } from './render/text.ts'
+import { TUI_RGB } from './theme.ts'
+
+function color(rgb: readonly [number, number, number]): string {
+  return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`
+}
+
+interface ListFrameProps {
+  readonly title: string
+  readonly rows: readonly { readonly key: string; readonly text: string; readonly disabled?: boolean }[]
+  readonly cursor: number
+  readonly loading: boolean
+  readonly error?: string
+  readonly query: string
+  readonly footer: string
+}
+
+function ListFrame(props: ListFrameProps): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
+  if (viewport.compact) {
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns(`${props.title} · esc close`, viewport.contentColumns))
+  }
+  const stateRows = props.loading
+    ? [{ key: 'loading', text: '  loading…' }]
+    : props.error !== undefined
+      ? [{ key: 'error', text: `  ${singleLineText(props.error)}` }]
+      : props.rows.length === 0
+        ? [{ key: 'empty', text: '  no matching entries' }]
+        : props.rows
+  const bodyRows = Math.max(1, viewport.bodyRows - 1)
+  const offset = revealRow(0, props.cursor, stateRows.length, bodyRows)
+  const visible = stateRows.slice(offset, offset + bodyRows)
+  return createElement(
+    Box,
+    { borderStyle: 'round', borderColor: color(TUI_RGB.dim), flexDirection: 'column', paddingX: 1 },
+    createElement(Text, { color: color(TUI_RGB.brandBright), wrap: 'truncate-end' }, truncateColumns(props.title, viewport.contentColumns)),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(`search: ${props.query === '' ? 'type to filter' : props.query}`, viewport.contentColumns)),
+    ...visible.map((row, index) => {
+      const absolute = offset + index
+      const selected = !props.loading && props.error === undefined && props.rows.length > 0 && absolute === props.cursor
+      return createElement(Text, {
+        key: row.key,
+        color: selected ? color(TUI_RGB.brandBright) : row.disabled ? color(TUI_RGB.dim) : undefined,
+        dimColor: row.disabled,
+        wrap: 'truncate-end',
+      }, truncateColumns(`${selected ? '› ' : '  '}${row.text}`, viewport.contentColumns))
+    }),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(props.footer, viewport.contentColumns)),
+  )
+}
+
+function editQuery(query: string, input: string, key: { backspace?: boolean; delete?: boolean }): string | undefined {
+  if (key.backspace || key.delete) return query.slice(0, -1)
+  if (input.length === 1 && input >= ' ' && input !== '\x7f') return query + input
+  return undefined
+}
+
+export function ModePanel({ current, load, select, close }: {
+  current: string
+  load(): Promise<readonly PresetRow[]>
+  select(id: string): void
+  close(): void
+}): ReactElement {
+  const [rows, setRows] = useState<readonly PresetRow[]>([])
+  const [query, setQuery] = useState('')
+  const [cursor, setCursor] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string>()
+  const refresh = (): void => {
+    setLoading(true); setError(undefined)
+    Promise.resolve().then(load).then(value => { setRows(value); setLoading(false) }, reason => {
+      setError(reason instanceof Error ? reason.message : String(reason)); setLoading(false)
+    })
+  }
+  useEffect(refresh, [])
+  const visible = useMemo(() => rows.filter(row => `${row.id} ${row.name ?? ''} ${row.description ?? ''}`.toLowerCase().includes(query.toLowerCase())), [rows, query])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, visible.length - 1))), [visible.length])
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (input === 'r' && query === '') return refresh()
+    if (key.upArrow) return setCursor(value => visible.length === 0 ? 0 : (value + visible.length - 1) % visible.length)
+    if (key.downArrow) return setCursor(value => visible.length === 0 ? 0 : (value + 1) % visible.length)
+    if (key.return && visible[cursor]?.broken === undefined) return select(visible[cursor]!.id)
+    const next = editQuery(query, input, key)
+    if (next !== undefined) { setQuery(next); setCursor(0) }
+  })
+  return createElement(ListFrame, {
+    title: `/mode · current ${current}`,
+    rows: visible.map(row => ({ key: row.id, disabled: row.broken !== undefined, text: `${row.id === current ? '●' : '○'} ${row.name ?? row.id} · ${row.description ?? row.trust}${row.broken === undefined ? '' : ` · broken: ${row.broken}`}` })),
+    cursor, loading, error, query, footer: '↑↓ choose · enter switch · r refresh · esc close',
+  })
+}
+
+export function PluginPanel({ load, close, initialQuery = '' }: { load(): readonly PluginRow[]; close(): void; initialQuery?: string }): ReactElement {
+  const [epoch, setEpoch] = useState(0)
+  const [query, setQuery] = useState(initialQuery)
+  const [cursor, setCursor] = useState(0)
+  const [expanded, setExpanded] = useState(false)
+  const rows = useMemo(() => load().filter(row => `${row.entryId} ${row.moduleName} ${row.phase ?? ''}`.toLowerCase().includes(query.toLowerCase())), [epoch, query])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, rows.length - 1))), [rows.length])
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (input === 'r' && query === '') return setEpoch(value => value + 1)
+    if (key.upArrow) return setCursor(value => rows.length === 0 ? 0 : (value + rows.length - 1) % rows.length)
+    if (key.downArrow) return setCursor(value => rows.length === 0 ? 0 : (value + 1) % rows.length)
+    if (key.return) return setExpanded(value => !value)
+    const next = editQuery(query, input, key)
+    if (next !== undefined) { setQuery(next); setCursor(0) }
+  })
+  return createElement(ListFrame, {
+    title: '/plugin · loader inspector',
+    rows: rows.map((row, index) => ({
+      key: row.entryId,
+      disabled: !row.enabled,
+      text: `${row.enabled ? '●' : '○'} ${row.entryId} · ${row.phase ?? 'not mounted'}${expanded && index === cursor ? ` · ${row.moduleName}` : ''}`,
+    })), cursor, loading: false, query, footer: '↑↓ inspect · enter details · r refresh · esc close',
+  })
+}
+
+export function ResumePanel({ currentCwd, load, readTranscript, select, close }: {
+  currentCwd: string
+  load(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>
+  readTranscript(id: string, signal?: AbortSignal): Promise<string>
+  select(row: SessionRow): void
+  close(): void
+}): ReactElement {
+  const [options, setOptions] = useState<SessionDirectoryOptions>({ sessions: 'roots', cwd: 'all', sort: 'newest', currentCwd, query: '' })
+  const [focus, setFocus] = useState(0)
+  const [density, setDensity] = useState<'comfortable' | 'dense'>('comfortable')
+  const [rows, setRows] = useState<readonly SessionRow[]>([])
+  const [cursor, setCursor] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string>()
+  const [expanded, setExpanded] = useState<string>()
+  const [transcript, setTranscript] = useState<{ id: string; text?: string; error?: string }>()
+  const transcriptLoad = useRef<AbortController>()
+  useEffect(() => () => transcriptLoad.current?.abort(), [])
+  useEffect(() => {
+    const controller = new AbortController()
+    setLoading(true); setError(undefined)
+    Promise.resolve().then(() => load(options, controller.signal)).then(value => {
+      if (!controller.signal.aborted) { setRows(value); setLoading(false) }
+    }, reason => {
+      if (!controller.signal.aborted) { setError(reason instanceof Error ? reason.message : String(reason)); setLoading(false) }
+    })
+    return () => controller.abort()
+  }, [options])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, rows.length - 1))), [rows.length])
+  const cycle = (): void => {
+    if (focus === 3) {
+      setDensity(current => current === 'comfortable' ? 'dense' : 'comfortable')
+      return
+    }
+    setOptions(value => {
+      if (focus === 0) return { ...value, sessions: value.sessions === 'roots' ? 'all' : 'roots' }
+      if (focus === 1) return { ...value, cwd: value.cwd === 'all' ? 'current' : 'all' }
+      return { ...value, sort: value.sort === 'newest' ? 'oldest' : 'newest' }
+    })
+  }
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (key.tab) return setFocus(value => (value + (key.shift ? 3 : 1)) % 4)
+    if (key.leftArrow) return cycle()
+    if (key.rightArrow) return cycle()
+    if (key.upArrow) return setCursor(value => rows.length === 0 ? 0 : Math.max(0, value - 1))
+    if (key.downArrow) return setCursor(value => rows.length === 0 ? 0 : Math.min(rows.length - 1, value + 1))
+    if (key.pageUp) return setCursor(value => Math.max(0, value - 8))
+    if (key.pageDown) return setCursor(value => Math.min(rows.length - 1, value + 8))
+    if (input === 'g') return setCursor(0)
+    if (input === 'G') return setCursor(Math.max(0, rows.length - 1))
+    if (input === 'd') return setDensity(value => value === 'comfortable' ? 'dense' : 'comfortable')
+    if (input === 'e' && rows[cursor] !== undefined) {
+      return setExpanded(value => value === rows[cursor]!.id ? undefined : rows[cursor]!.id)
+    }
+    if (input === 't' && rows[cursor] !== undefined) {
+      const row = rows[cursor]!
+      transcriptLoad.current?.abort()
+      setTranscript({ id: row.id })
+      const controller = new AbortController()
+      transcriptLoad.current = controller
+      Promise.resolve().then(() => readTranscript(row.id, controller.signal)).then(
+        text => { if (!controller.signal.aborted) setTranscript({ id: row.id, text }) },
+        reason => { if (!controller.signal.aborted) setTranscript({ id: row.id, error: reason instanceof Error ? reason.message : String(reason) }) },
+      )
+      return
+    }
+    if (key.return && rows[cursor]?.resumable === true) return select(rows[cursor]!)
+    const next = editQuery(options.query, input, key)
+    if (next !== undefined) { setOptions(value => ({ ...value, query: next })); setCursor(0) }
+  }, { isActive: transcript === undefined })
+  if (transcript !== undefined) {
+    return createElement(DocumentPanel, {
+      title: `transcript · ${transcript.id}`,
+      text: transcript.text,
+      error: transcript.error,
+      close: () => { transcriptLoad.current?.abort(); setTranscript(undefined) },
+    })
+  }
+  const toolbar = `[${focus === 0 ? '>' : ''}${options.sessions}] [${focus === 1 ? '>' : ''}${options.cwd} cwd] [${focus === 2 ? '>' : ''}${options.sort}] [${focus === 3 ? '>' : ''}${density}]`
+  return createElement(ListFrame, {
+    title: `/resume · ${toolbar}`,
+    rows: rows.map(row => ({
+      key: row.id,
+      disabled: !row.resumable,
+      text: `${row.subagent ? '↳' : '○'} ${row.title ?? row.id.slice(-12)}${density === 'comfortable' ? ` · ${row.workspace} · ${row.preset}` : ''}${row.live ? ' · live' : ''}${expanded === row.id ? ` · ${row.id} · ${row.cwd}${row.parent === undefined ? '' : ` · parent ${row.parent}`}` : ''}`,
+    })), cursor, loading, error, query: options.query,
+    footer: 'type search · tab/←→ filters · ↑↓/pg navigate · e details · t transcript · enter resume',
+  })
+}
+
+function DocumentPanel({ title, text, error, close }: {
+  title: string
+  text?: string
+  error?: string
+  close(): void
+}): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  const [scroll, setScroll] = useState(0)
+  const lines = useMemo(() => text === undefined ? [] : textLines(text, viewport.contentColumns).map(line => line.segments.map(segment => segment.text).join('')), [text, viewport.contentColumns])
+  useInput((input, key) => {
+    if (key.escape || input === 'q' || input === 't') return close()
+    if (key.upArrow) return setScroll(value => Math.max(0, value - 1))
+    if (key.downArrow) return setScroll(value => Math.min(Math.max(0, lines.length - viewport.bodyRows), value + 1))
+    if (key.pageUp) return setScroll(value => Math.max(0, value - Math.max(1, viewport.bodyRows - 1)))
+    if (key.pageDown) return setScroll(value => Math.min(Math.max(0, lines.length - viewport.bodyRows), value + Math.max(1, viewport.bodyRows - 1)))
+    if (input === 'g') return setScroll(0)
+    if (input === 'G') return setScroll(Math.max(0, lines.length - viewport.bodyRows))
+  })
+  if (viewport.compact) return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('transcript · esc close', viewport.contentColumns))
+  const body = error !== undefined
+    ? [`error: ${singleLineText(error)}`]
+    : text === undefined
+      ? ['loading transcript…']
+      : lines.slice(scroll, scroll + viewport.bodyRows)
+  return createElement(
+    Box,
+    { borderStyle: 'round', borderColor: color(TUI_RGB.dim), flexDirection: 'column', paddingX: 1 },
+    createElement(Text, { color: color(TUI_RGB.brandBright), wrap: 'truncate-end' }, truncateColumns(title, viewport.contentColumns)),
+    ...body.map((line, index) => createElement(Text, { key: `${scroll}-${index}`, wrap: 'truncate-end' }, truncateColumns(line, viewport.contentColumns))),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(`lines ${lines.length === 0 ? 0 : scroll + 1}-${Math.min(lines.length, scroll + viewport.bodyRows)}/${lines.length} · ↑↓/pg/g/G · t/esc close`, viewport.contentColumns)),
+  )
+}

package/src/plugin-inventory.ts

@@ -0,0 +1,47 @@
+/** Read-only projection of Cordis Loader entries for /plugin. */
+
+import type { Context, FiberState } from '@deepseek-ai/cordis'
+
+export type PluginPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null
+
+export interface PluginRow {
+  readonly entryId: string
+  readonly moduleName: string
+  readonly enabled: boolean
+  readonly phase: PluginPhase
+}
+
+const PHASES: Record<number, PluginPhase> = {
+  0: 'pending',
+  1: 'loading',
+  2: 'active',
+  3: 'failed',
+  4: null,
+  5: 'unloading',
+}
+
+interface LoaderEntry {
+  readonly id: string
+  readonly disabled: boolean
+  readonly options: { readonly group?: boolean; readonly name: string }
+  readonly fiber?: { readonly state: FiberState }
+}
+
+/** Snapshot the live Loader; group-only rows are composition containers, not plugins. */
+export function listPluginRows(ctx: Context): PluginRow[] {
+  const loader = (ctx as unknown as { get(name: string): unknown }).get('loader') as
+    | { entries(): Iterable<LoaderEntry> }
+    | undefined
+  if (loader === undefined) return []
+  const rows: PluginRow[] = []
+  for (const entry of loader.entries()) {
+    if (entry.options.group === true) continue
+    rows.push({
+      entryId: entry.id,
+      moduleName: entry.options.name,
+      enabled: !entry.disabled,
+      phase: entry.fiber === undefined ? null : PHASES[entry.fiber.state] ?? null,
+    })
+  }
+  return rows
+}

package/src/presets.ts

@@ -0,0 +1,64 @@
+/** Agent-preset policy kept independent from the Ink surface. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** One discoverable agent composition. */
+export interface PresetRow {
+  readonly id: string
+  readonly trust: 'system' | 'user'
+  readonly name?: string
+  readonly description?: string
+  readonly order?: number
+  readonly broken?: string
+}
+
+/** Structural boundary for the optional upstream AgentPresets service. */
+export interface AgentPresetsService {
+  readonly defaultId: string
+  list(): Promise<PresetRow[]>
+  resolve(id?: string): Promise<PresetRow>
+  mount(agentCtx: Context, id?: string): Promise<PresetRow>
+  recompose(agentCtx: Context, id: string): Promise<PresetRow>
+  composedPreset(agentCtx: Context): string | undefined
+}
+
+/** Read an optional Cordis service without requiring its package at build time. */
+export function agentPresetsFrom(ctx: Context): AgentPresetsService | undefined {
+  return (ctx as unknown as { get(name: string): unknown }).get('agentPresets') as AgentPresetsService | undefined
+}
+
+/** A preset may change only before the first durable turn begins. */
+export function isBlankSession(events: readonly SessionEvent[]): boolean {
+  return !events.some(event => event.type === 'turn/start')
+}
+
+/** Latest logged selection wins; legacy sessions deliberately fall back to standard. */
+export function resolvePreset(session: Pick<Session, 'header' | 'events'>): string {
+  for (let index = session.events.length - 1; index >= 0; index -= 1) {
+    const event = session.events[index] as unknown as { type: string; data?: { agentPreset?: string } }
+    if (event.type === 'agent-preset/selected' && event.data?.agentPreset !== undefined) {
+      return event.data.agentPreset
+    }
+  }
+  return session.header.agentPreset ?? 'standard'
+}
+
+/** Recompose atomically from the caller's perspective, logging only success. */
+export async function switchPreset(
+  service: AgentPresetsService,
+  agent: Agent,
+  presetId: string,
+): Promise<PresetRow> {
+  if (!isBlankSession(agent.session.events)) {
+    throw new Error('mode is locked after the first turn; use /new <mode>')
+  }
+  const preset = await service.recompose(agent.ctx, presetId)
+  const writable = agent.session as unknown as { append(type: string, data: unknown): void }
+  writable.append('agent-preset/selected', { agentPreset: preset.id })
+  return preset
+}
+
+/** Minimal handle shape used by lifecycle tests without exposing Agent internals. */
+export type OwnedAgent = Pick<AgentHandle, 'agent' | 'dispose'>

package/src/render/inspector.ts

@@ -6,14 +6,21 @@ export interface InspectorViewport {
   maxHeight: number
   /** Rows available to the selected entry after border, title, and footer. */
   bodyRows: number
+  /** Optional blank rows separating title/body/footer on roomy terminals. */
+  gapRows: 0 | 2
   /** Columns available inside the horizontal border and padding. */
   contentColumns: number
   /** Tiny terminals use a borderless one-line close hint. */
   compact: boolean
 }
 
-/** The three-row read-only composer frame plus its one-row status footer. */
-const INSPECTOR_CHROME_ROWS = 4
+/** Composer/status chrome plus one optional, fixed-height local notice row. */
+const INSPECTOR_CHROME_ROWS = 5
+
+/** One transcript-to-composer gutter, collapsed on short terminals. */
+export function layoutGutterRows(rows: number): 0 | 1 {
+  return Math.max(1, Math.floor(rows)) >= 14 ? 1 : 0
+}
 
 /**
  * Keep the inspector plus its persistent status/composer chrome below
@@ -27,13 +34,15 @@ export function panelViewport(columns: number, rows: number): InspectorViewport
   // scrollback into a tall dynamic panel. A one-row margin is insufficient:
   // the transition can still take the full-terminal rewrite path at rows - 1.
   const maxHeight = Math.max(0, Math.min(
-    safeRows - 2 - INSPECTOR_CHROME_ROWS,
+    safeRows - 2 - INSPECTOR_CHROME_ROWS - layoutGutterRows(safeRows),
     Math.floor(safeRows / 2),
   ))
   const compact = maxHeight < 5 || safeColumns < 8
+  const gapRows = !compact && maxHeight >= 7 ? 2 : 0
   return {
     maxHeight,
-    bodyRows: compact ? 0 : maxHeight - 4,
+    bodyRows: compact ? 0 : maxHeight - 4 - gapRows,
+    gapRows,
     contentColumns: compact ? Math.max(1, safeColumns - 1) : Math.max(1, safeColumns - 4),
     compact,
   }

package/src/render/markdown.ts

@@ -166,11 +166,18 @@ const ORDERED = /^\s*(\d+)[.)]\s+(.*)$/u
 /** Render markdown text into styled lines of at most `width` columns. */
 export function renderMarkdown(text: string, width: number): readonly MdLine[] {
   const lines: MdLine[] = []
+  let separatorPending = false
   const push = (segments: readonly MdSegment[]): void => {
     for (const wrapped of wrapSegments(segments, Math.max(10, width))) {
       lines.push({ segments: merge(wrapped) })
     }
   }
+  const startBlock = (): void => {
+    if (separatorPending && lines.length > 0 && lines.at(-1)?.segments.length !== 0) {
+      lines.push({ segments: [] })
+    }
+    separatorPending = false
+  }
   const raw = text.replaceAll('\r', '')
   const source = raw.split('\n')
   let index = 0
@@ -178,6 +185,14 @@ export function renderMarkdown(text: string, width: number): readonly MdLine[] {
     const line = source[index] ?? ''
     index += 1
 
+    // Preserve one deliberate row between source blocks. Repeated blank
+    // lines collapse, and leading/trailing whitespace never grows output.
+    if (line.trim() === '') {
+      separatorPending = lines.length > 0
+      continue
+    }
+    startBlock()
+
     // Fenced code block: verbatim lines in code style, language label first.
     const fence = FENCE.exec(line)
     if (fence !== null) {
@@ -191,7 +206,6 @@ export function renderMarkdown(text: string, width: number): readonly MdLine[] {
       continue
     }
 
-    if (line.trim() === '') continue
     if (RULE.test(line.trim())) {
       push([seg(`  ${'─'.repeat(Math.max(1, Math.floor(width / 4)))}`, 'dim')])
       continue

package/src/render/status.ts

@@ -63,6 +63,8 @@ export function cacheHitPercent(usage: TranscriptStats['usage']): number | null
 export interface StatusFacts {
   /** `provider/model` selection serving this session. */
   model: string
+  /** Agent preset composing this session. */
+  mode?: string
   /** Working-directory basename the session serves. */
   cwd: string
   /** Git branch name, empty outside a repository or on a detached HEAD file. */
@@ -96,6 +98,7 @@ export function buildStatusGroups(facts: StatusFacts, stats: TranscriptStats): s
     facts.plan ? '⧉ plan' : undefined,
   ].filter(part => part !== undefined && part !== '')
   if (identity.length > 0) groups.push(identity.join(' · '))
+  if (facts.mode !== undefined && facts.mode !== '') groups.push(`mode ${facts.mode}`)
   if (stats.turns > 0 || stats.steps > 0) {
     groups.push(`T${stats.turns} · S${stats.steps}`)
     const durations: string[] = []

package/src/render/text.ts

@@ -23,12 +23,9 @@ export function displayText(text: string): string {
   return text.replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
 
-/** A display-safe suffix bounded by terminal rows and columns. */
-export interface DisplayTail {
-  /** Sanitized suffix suitable for direct terminal rendering. */
-  text: string
-  /** Whether content before the returned suffix was omitted. */
-  truncated: boolean
+/** Collapse external text to one terminal-safe logical row. */
+export function singleLineText(text: string): string {
+  return displayText(text).replace(/\r?\n/gu, ' ↵ ').replace(/\t/gu, '  ')
 }
 
 /** Terminal-cell width matching the TUI's existing CJK-aware wrapping rule. */
@@ -40,6 +37,37 @@ function cellWidth(text: string): number {
   return columns
 }
 
+/**
+ * Truncate one display-safe row without ever exceeding its physical-column
+ * budget. The ellipsis is included inside the budget, matching Codex's popup
+ * truncation contract; the previous app-local helper appended it after the
+ * row was already full and could force an extra terminal wrap.
+ */
+export function truncateColumns(text: string, columns: number): string {
+  const limit = Math.max(0, Math.floor(columns))
+  if (limit === 0) return ''
+  if (cellWidth(text) <= limit) return text
+
+  const contentLimit = limit - 1
+  let used = 0
+  let result = ''
+  for (const char of text) {
+    const width = cellWidth(char)
+    if (used + width > contentLimit) break
+    result += char
+    used += width
+  }
+  return `${result}…`
+}
+
+/** A display-safe suffix bounded by terminal rows and columns. */
+export interface DisplayTail {
+  /** Sanitized suffix suitable for direct terminal rendering. */
+  text: string
+  /** Whether content before the returned suffix was omitted. */
+  truncated: boolean
+}
+
 /** Read one Unicode character immediately before `end`. */
 function previousCharacter(text: string, end: number): { char: string; start: number } {
   const last = text.charCodeAt(end - 1)

package/src/session-directory.ts

@@ -0,0 +1,102 @@
+/** Lightweight session-directory projection for the /resume picker. */
+
+import { basename, resolve } from 'node:path'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+
+export interface SessionRecord {
+  readonly header: SessionHeader
+  readonly live: boolean
+  readonly persisted: boolean
+}
+
+export interface TitleObservationResult {
+  readonly sessionId: string
+  readonly status: 'fulfilled' | 'rejected'
+  readonly value?: { readonly title?: { readonly title?: string; readonly text?: string } }
+}
+
+export interface SessionLogSnapshot {
+  readonly session: SessionHeader
+  readonly events: SessionEvent[]
+}
+
+/** Structural upstream SessionQuery surface used by the TUI. */
+export interface SessionQueryService {
+  listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+  readTitleSnapshots(ids: readonly string[], signal?: AbortSignal): Promise<TitleObservationResult[]>
+  readSession(id: string, signal?: AbortSignal): Promise<SessionLogSnapshot>
+}
+
+export type SessionScope = 'roots' | 'all'
+export type CwdScope = 'all' | 'current'
+export type SessionSort = 'newest' | 'oldest'
+
+export interface SessionDirectoryOptions {
+  readonly sessions: SessionScope
+  readonly cwd: CwdScope
+  readonly sort: SessionSort
+  readonly currentCwd: string
+  readonly query: string
+}
+
+export interface SessionRow {
+  readonly id: string
+  readonly createdAt: number
+  readonly cwd: string
+  readonly workspace: string
+  readonly parent?: string
+  readonly subagent: boolean
+  readonly resumable: boolean
+  readonly live: boolean
+  readonly persisted: boolean
+  readonly preset: string
+  readonly title?: string
+}
+
+function samePath(left: string | undefined, right: string): boolean {
+  if (left === undefined) return false
+  return resolve(left).toLowerCase() === resolve(right).toLowerCase()
+}
+
+/** Filter/sort header-only records. No session log is loaded here. */
+export function projectSessionRows(records: readonly SessionRecord[], options: SessionDirectoryOptions): SessionRow[] {
+  const needle = options.query.trim().toLowerCase()
+  return records
+    .filter(record => options.sessions === 'all'
+      || (record.header.parentSession === undefined && record.header.origin !== 'subagent'))
+    .filter(record => options.cwd === 'all' || samePath(record.header.cwd, options.currentCwd))
+    .map(record => {
+      const cwd = record.header.cwd ?? ''
+      const subagent = record.header.origin === 'subagent' || record.header.parentSession !== undefined
+      return {
+        id: record.header.id,
+        createdAt: record.header.createdAt,
+        cwd,
+        workspace: cwd === '' ? '(no workspace)' : basename(cwd),
+        parent: record.header.parentSession,
+        subagent,
+        resumable: !subagent,
+        live: record.live,
+        persisted: record.persisted,
+        preset: record.header.agentPreset ?? 'standard',
+      }
+    })
+    .filter(row => needle === '' || `${row.id} ${row.cwd} ${row.workspace} ${row.preset}`.toLowerCase().includes(needle))
+    .sort((left, right) => options.sort === 'newest'
+      ? right.createdAt - left.createdAt
+      : left.createdAt - right.createdAt)
+}
+
+/** Merge page-local title observations without disturbing directory order. */
+export function mergeSessionTitles(
+  rows: readonly SessionRow[],
+  observations: readonly TitleObservationResult[],
+): SessionRow[] {
+  const titles = new Map<string, string>()
+  for (const observation of observations) {
+    if (observation.status !== 'fulfilled') continue
+    const title = observation.value?.title?.title ?? observation.value?.title?.text
+    if (title !== undefined && title.trim() !== '') titles.set(observation.sessionId, title)
+  }
+  return rows.map(row => titles.has(row.id) ? { ...row, title: titles.get(row.id) } : row)
+}