typeclaw 0.26.0 → 0.27.0

package/src/inspect/index.ts

@@ -16,8 +16,26 @@ export { replayJsonl } from './replay'
 export { streamLive } from './live'
 export { parseDuration, parseFilter } from './types'
 export type { InspectCategory, InspectEvent, InspectFilter } from './types'
-export { runInspectLoop } from './loop'
-export type { RunInspectLoopOptions } from './loop'
+export { runInspectLoop, runViewerLoop } from './loop'
+export type {
+  OpenItem,
+  OpenItemContext,
+  RunInspectLoopOptions,
+  RunViewerLoopOptions,
+  SelectItem,
+  TailController,
+} from './loop'
+export type { ViewerItem } from './item'
+export { isWritable, itemKey } from './item'
+export { listViewerItems } from './item-list'
+export type { ListViewerItemsOptions, ViewerList } from './item-list'
+export { openViewerItem } from './open-item'
+export type { OpenViewerDeps } from './open-item'
+export { runTuiViewer } from './tui-item'
+export type { RunTuiViewerOptions } from './tui-item'
+export { streamLogs } from './logs-item'
+export { createTranscriptView } from './transcript-view'
+export type { TranscriptViewOptions, TranscriptViewOutcome } from './transcript-view'
 
 export type RunInspectOptions = {
   agentDir: string
@@ -51,7 +69,7 @@ export type LiveSourceFactory = (opts: {
 }) => AsyncIterable<InspectEvent>
 
 export type RunInspectResult =
-  | { ok: true; exitCode: 0; escToPicker?: boolean }
+  | { ok: true; exitCode: number; escToPicker?: boolean }
   | { ok: false; exitCode: number; reason: string }
 
 export type InspectTarget = {
@@ -164,51 +182,58 @@ async function chooseSession(
   return { ok: true, summary: picked }
 }
 
-async function streamSession(opts: {
+// Lifecycle phases surfaced to a consumer so renderers can react (e.g. batch a
+// pi-tui render at replay-end, announce a live divider). `sessionLive` on
+// 'live-start' is the registry hit/miss from the live source's onSubscribed.
+export type StreamPhase =
+  | { phase: 'replay-end' }
+  | { phase: 'replay-only-idle' }
+  | { phase: 'live-start'; sessionLive: boolean }
+  | { phase: 'end' }
+
+export type StreamSessionEventsOptions = {
   summary: SessionSummary
   filter: InspectFilter
   sinceMs: number | undefined
-  json: boolean
-  color: boolean
-  stdout: (line: string) => void
-  stderr: (line: string) => void
+  onEvent: (event: InspectEvent) => void
+  onPhase?: (phase: StreamPhase) => void
+  onWarn?: (msg: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
-  liveHint?: string
-  interactive?: boolean
-}): Promise<{ escToPicker: boolean }> {
-  if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
-  const emit = (event: InspectEvent): void => {
+  // When true and replay-only with a signal, block until aborted instead of
+  // returning immediately — a stable interactive viewer that esc/q dismisses.
+  blockWhenReplayOnly?: boolean
+}
+
+// The read path shared by the line renderer and the pi-tui transcript view:
+// replay the JSONL transcript, then optionally live-tail, applying since/filter
+// and honoring signal.aborted (-> escToPicker). Knows nothing about rendering —
+// it just delivers ordered, filtered InspectEvents to onEvent and announces
+// phase transitions via onPhase.
+export async function streamSessionEvents(opts: StreamSessionEventsOptions): Promise<{ escToPicker: boolean }> {
+  const aborted = (): boolean => opts.signal?.aborted === true
+  const deliver = (event: InspectEvent): void => {
     if (opts.sinceMs !== undefined && event.ts > 0 && event.ts < opts.sinceMs) return
     if (!matchesFilter(event, opts.filter)) return
-    if (opts.json) {
-      opts.stdout(JSON.stringify({ sessionId: opts.summary.sessionId, ...event }))
-    } else {
-      opts.stdout(renderEvent(event, { color: opts.color }))
-    }
+    opts.onEvent(event)
   }
 
-  const aborted = (): boolean => opts.signal?.aborted === true
-
-  for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
+  for await (const event of replayJsonl(
+    opts.summary.sessionFile,
+    opts.onWarn !== undefined ? { onWarn: opts.onWarn } : {},
+  )) {
     if (aborted()) return { escToPicker: true }
-    emit(event)
+    deliver(event)
   }
+  opts.onPhase?.({ phase: 'replay-end' })
 
   if (opts.liveSource === undefined) {
-    if (!opts.json) opts.stdout('─── end of transcript ───')
-    // Already aborted during replay (user pressed esc/q): honor it, don't lose the keystroke.
     if (aborted()) return { escToPicker: true }
-    // Interactive replay-only: hold a stable viewer like `dreams` instead of
-    // bouncing straight back to the picker. Block until the tail scope aborts
-    // (esc → back, q/ctrl-c → exit). Never block without a signal (non-TTY has
-    // no listener and would hang) or in json/non-interactive mode (scriptability).
-    if (opts.interactive === true && !opts.json && opts.signal !== undefined) {
-      if (opts.liveHint !== undefined && opts.liveHint !== '') {
-        opts.stdout(divider(opts.color, opts.liveHint))
-      }
+    if (opts.blockWhenReplayOnly === true && opts.signal !== undefined) {
+      opts.onPhase?.({ phase: 'replay-only-idle' })
       await waitForAbort(opts.signal)
     }
+    opts.onPhase?.({ phase: 'end' })
     return { escToPicker: aborted() }
   }
 
@@ -227,24 +252,85 @@ async function streamSession(opts: {
   let liveAnnounced = false
   try {
     for await (const event of liveIter) {
-      if (!liveAnnounced && !opts.json) {
-        opts.stdout(
-          divider(opts.color, sessionLive ? '─── live ───' : '─── live (session not in registry; broadcasts only) ───'),
-        )
-        if (opts.liveHint !== undefined && opts.liveHint !== '') {
-          opts.stdout(divider(opts.color, opts.liveHint))
-        }
+      if (!liveAnnounced) {
+        opts.onPhase?.({ phase: 'live-start', sessionLive })
         liveAnnounced = true
       }
-      emit(event)
+      deliver(event)
     }
   } catch (err) {
-    opts.stderr(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
+    opts.onWarn?.(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
   }
-  if (!opts.json) opts.stdout('─── end of transcript ───')
+  opts.onPhase?.({ phase: 'end' })
   return { escToPicker: aborted() }
 }
 
+// Line/JSON renderer: the original streamSession behavior, now expressed as a
+// streamSessionEvents consumer. Preserves the exact header/divider output and
+// scriptable stdout/JSON contract.
+async function streamSession(opts: {
+  summary: SessionSummary
+  filter: InspectFilter
+  sinceMs: number | undefined
+  json: boolean
+  color: boolean
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  liveSource?: LiveSourceFactory
+  signal?: AbortSignal
+  liveHint?: string
+  interactive?: boolean
+}): Promise<{ escToPicker: boolean }> {
+  if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
+
+  const onEvent = (event: InspectEvent): void => {
+    if (opts.json) opts.stdout(JSON.stringify({ sessionId: opts.summary.sessionId, ...event }))
+    else opts.stdout(renderEvent(event, { color: opts.color }))
+  }
+
+  const emitHint = (): void => {
+    if (!opts.json && opts.liveHint !== undefined && opts.liveHint !== '') {
+      opts.stdout(divider(opts.color, opts.liveHint))
+    }
+  }
+
+  // Replay-only prints the end-of-transcript footer once at the idle point (the
+  // viewer then blocks); the terminal 'end' phase must not print it a second
+  // time. Live mode skips the idle phase and prints the footer only at 'end'.
+  let footerPrinted = false
+  const printFooter = (): void => {
+    opts.stdout('─── end of transcript ───')
+    footerPrinted = true
+  }
+
+  const onPhase = (p: StreamPhase): void => {
+    if (opts.json) return
+    if (p.phase === 'replay-only-idle') {
+      printFooter()
+      emitHint()
+    } else if (p.phase === 'live-start') {
+      opts.stdout(
+        divider(opts.color, p.sessionLive ? '─── live ───' : '─── live (session not in registry; broadcasts only) ───'),
+      )
+      emitHint()
+    } else if (p.phase === 'end' && !footerPrinted) {
+      printFooter()
+    }
+  }
+
+  return streamSessionEvents({
+    summary: opts.summary,
+    filter: opts.filter,
+    sinceMs: opts.sinceMs,
+    onEvent,
+    onPhase,
+    onWarn: opts.stderr,
+    ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    blockWhenReplayOnly: opts.interactive === true && !opts.json,
+  })
+}
+
 function divider(color: boolean, text: string): string {
   if (color) return `\u001b[2m${text}\u001b[0m`
   return text

package/src/inspect/item-list.ts

@@ -0,0 +1,44 @@
+import type { ViewerItem } from './item'
+import { listSessions, type ListSessionsOptions, type SessionSummary } from './session-list'
+
+export type ListViewerItemsOptions = ListSessionsOptions & {
+  containerRunning: boolean
+  includeLogs?: boolean
+  // Defaults to true. The detach-to-list path (after `typeclaw tui` esc) sets
+  // this false: detaching ENDS the server-side session, so the just-killed
+  // (most-recent) tui transcript — and any older tui transcript the heuristic
+  // would otherwise promote — must NOT be offered as a writable live row.
+  allowWritable?: boolean
+}
+
+export type ViewerList = {
+  items: ViewerItem[]
+  writableSessionId: string | null
+}
+
+// Builds the session-viewer list. The writable TUI row is a heuristic, not an
+// authoritative query: when the container is up, the single most-recent
+// tui-origin session becomes the read+write `tui` item; every other session is
+// read-only. With the container down there is no live session to drive, so all
+// sessions are read-only. The `logs` row is appended last (container stdout,
+// available offline) so it sits below the divider in the picker.
+export async function listViewerItems(opts: ListViewerItemsOptions): Promise<ViewerList> {
+  const sessions = await listSessions(opts)
+  const allowWritable = opts.allowWritable !== false
+  const writableSessionId = opts.containerRunning && allowWritable ? pickWritableSession(sessions) : null
+
+  const items: ViewerItem[] = sessions.map((summary) =>
+    summary.sessionId === writableSessionId
+      ? { kind: 'tui', summary, writable: true }
+      : { kind: 'session', summary, writable: false },
+  )
+
+  if (opts.includeLogs !== false) items.push({ kind: 'logs' })
+
+  return { items, writableSessionId }
+}
+
+function pickWritableSession(sessions: SessionSummary[]): string | null {
+  const tuiSession = sessions.find((s) => s.origin?.kind === 'tui')
+  return tuiSession?.sessionId ?? null
+}

package/src/inspect/item.ts

@@ -0,0 +1,17 @@
+import type { SessionSummary } from './session-list'
+
+// At most one item is `writable` (the live TUI session); every other session is
+// read-only. `logs` carries no session — it is container stdout, available even
+// when the agent server is down.
+export type ViewerItem =
+  | { kind: 'session'; summary: SessionSummary; writable: false }
+  | { kind: 'tui'; summary: SessionSummary; writable: true }
+  | { kind: 'logs' }
+
+export function isWritable(item: ViewerItem): item is Extract<ViewerItem, { kind: 'tui' }> {
+  return item.kind === 'tui'
+}
+
+export function itemKey(item: ViewerItem): string {
+  return item.kind === 'logs' ? 'logs' : item.summary.sessionId
+}

package/src/inspect/label.ts

@@ -17,7 +17,7 @@ export function originLabel(origin: MinimalSessionOrigin): string {
     case 'cron':
       return `Cron ${origin.jobId} (${origin.jobKind})`
     case 'subagent':
-      return `Subagent ${origin.subagent} ← ${shortSessionId(origin.parentSessionId)}`
+      return `Subagent ${origin.subagent}`
     case 'channel':
       return channelLabel(origin)
     case 'system':

package/src/inspect/logs-item.ts

@@ -0,0 +1,79 @@
+import { logs } from '@/container'
+
+export type StreamLogsOptions = {
+  cwd: string
+  color: boolean
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  signal?: AbortSignal
+  liveHint?: string
+}
+
+export type StreamLogsResult = { escToPicker: boolean }
+
+// Interactive container-logs viewer for the session-viewer list. Unlike the raw
+// `logs` pump (host-stage, used for `typeclaw logs | grep`), this one runs under
+// the loop's tail scope: aborting the signal (esc/q/ctrl-c) kills `docker logs`
+// and returns control to the picker. Works with the agent server down — it only
+// needs the container to exist.
+export async function streamLogs(opts: StreamLogsOptions): Promise<StreamLogsResult> {
+  const aborted = (): boolean => opts.signal?.aborted === true
+  if (aborted()) return { escToPicker: true }
+
+  opts.stdout(divider(opts.color, '─── container logs ───'))
+  if (opts.liveHint !== undefined && opts.liveHint !== '') {
+    opts.stdout(divider(opts.color, opts.liveHint))
+  }
+
+  const out = lineSink(opts.stdout)
+  const err = lineSink(opts.stderr)
+
+  const result = await logs({
+    cwd: opts.cwd,
+    follow: true,
+    out,
+    err,
+    useColor: opts.color,
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+  })
+
+  if (!result.ok) {
+    opts.stderr(result.reason)
+    return { escToPicker: aborted() }
+  }
+  return { escToPicker: aborted() }
+}
+
+function divider(color: boolean, text: string): string {
+  if (color) return `\u001b[2m${text}\u001b[0m`
+  return text
+}
+
+// `logs` writes pre-formatted chunks (already newline-terminated) to a
+// WritableStream; the loop's sink wants newline-free lines. Buffer partial
+// lines and forward complete ones so a chunk split mid-line never emits a
+// truncated row.
+function lineSink(emit: (line: string) => void): NodeJS.WritableStream {
+  let buffer = ''
+  const flushLines = (): void => {
+    let idx = buffer.indexOf('\n')
+    while (idx !== -1) {
+      emit(buffer.slice(0, idx))
+      buffer = buffer.slice(idx + 1)
+      idx = buffer.indexOf('\n')
+    }
+  }
+  return {
+    write(chunk: string | Uint8Array): boolean {
+      buffer += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk)
+      flushLines()
+      return true
+    },
+    end(): void {
+      if (buffer.length > 0) {
+        emit(buffer)
+        buffer = ''
+      }
+    },
+  } as unknown as NodeJS.WritableStream
+}

package/src/inspect/loop.ts

@@ -6,6 +6,80 @@ export type TailController = {
   dispose: () => void
 }
 
+export type OpenItemContext = {
+  createTailScope: () => TailController
+}
+
+export type SelectItem<TItem> = (items: TItem[], opts: { initialKey?: string }) => Promise<TItem | null>
+
+export type OpenItemResult = {
+  result: RunInspectResult
+  // True only when the viewer that just closed ended a writable (live TUI)
+  // session — i.e. a tui detach. Logs and read-only transcripts return
+  // escToPicker WITHOUT this, so they must not suppress the writable row.
+  endedWritableSession?: boolean
+}
+
+export type OpenItem<TItem> = (item: TItem, ctx: OpenItemContext) => Promise<OpenItemResult>
+
+export type ListItemsContext = {
+  // False once the user has returned to the picker from any viewer: the prior
+  // viewer interaction ended, so there is no proof of a still-live writable
+  // session — a detached tui session must not be re-promoted as writable.
+  allowWritable: boolean
+}
+
+export type RunViewerLoopOptions<TItem> = {
+  listItems: (ctx: ListItemsContext) => Promise<TItem[]>
+  keyOf: (item: TItem) => string
+  preselectKey?: string
+  selectItem: SelectItem<TItem>
+  openItem: OpenItem<TItem>
+  createTailScope: () => TailController
+  onEmpty: () => RunInspectResult
+}
+
+// The session-viewer state machine: pick an item → open it → on back, re-open
+// the picker; on exit, return. `openItem` owns the per-branch lifecycle and
+// decides whether to request a tail scope (session/logs do; tui does not, since
+// it owns its own raw-mode terminal). When used, the tail scope is created
+// inside `openItem` AFTER the picker resolves and disposed before the picker
+// re-opens, so clack always owns a clean cooked-mode stdin.
+export async function runViewerLoop<TItem>(opts: RunViewerLoopOptions<TItem>): Promise<RunInspectResult> {
+  let preselectKey = opts.preselectKey
+  let lastPickedKey: string | undefined
+  // Writable is only safe on the very first list. Returning to the picker means
+  // a viewer was just opened and left — any writable session it might represent
+  // is gone (detach ends the live session), so subsequent refreshes are
+  // read-only.
+  let allowWritable = true
+
+  while (true) {
+    const items = await opts.listItems({ allowWritable })
+    if (items.length === 0) return opts.onEmpty()
+
+    let chosen: TItem | null
+    if (preselectKey !== undefined) {
+      chosen = items.find((i) => opts.keyOf(i) === preselectKey) ?? null
+      preselectKey = undefined
+      if (chosen === null) return opts.onEmpty()
+    } else {
+      const hint = lastPickedKey
+      chosen = await opts.selectItem(items, hint !== undefined ? { initialKey: hint } : {})
+      if (chosen === null) return { ok: false, exitCode: 130, reason: 'cancelled' }
+      lastPickedKey = opts.keyOf(chosen)
+    }
+
+    const opened = await opts.openItem(chosen, { createTailScope: opts.createTailScope })
+    const result = opened.result
+    if (!result.ok) return result
+    if (result.escToPicker !== true) return result
+    // Only a writable (tui) detach ends the live session; leaving logs or a
+    // read-only transcript leaves it untouched, so the writable row stays.
+    if (opened.endedWritableSession === true) allowWritable = false
+  }
+}
+
 export type RunInspectLoopOptions = Omit<RunInspectOptions, 'signal'> & {
   // Builds a fresh interaction scope for ONE live-tail attempt: a new
   // AbortController plus a temporary raw-mode listener. The loop creates it
@@ -30,12 +104,9 @@ export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunIn
     if (sessionArg !== undefined) resolveOpts.sessionIdOrPrefix = sessionArg
     else delete (resolveOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
 
-    // Picker phase: cooked-mode stdin, no tail scope alive.
     const resolved = await resolveInspectTarget(resolveOpts)
     if (!resolved.ok) return resolved
 
-    // Streaming phase: scope owns raw-mode stdin start-to-dispose, never
-    // spanning the picker above or the next iteration's picker below.
     const scope = opts.createTailScope()
     let result: RunInspectResult
     try {

package/src/inspect/open-item.ts

@@ -0,0 +1,100 @@
+import type { LiveSourceFactory, RunInspectResult } from './index'
+import { createTranscriptView, streamInspectTarget } from './index'
+import type { ViewerItem } from './item'
+import { streamLogs } from './logs-item'
+import type { OpenItemContext, OpenItemResult, TailController } from './loop'
+import { runTuiViewer } from './tui-item'
+import type { InspectFilter } from './types'
+
+export type OpenViewerDeps = {
+  cwd: string
+  filter: InspectFilter
+  sinceMs: number | undefined
+  json: boolean
+  color: boolean
+  interactive: boolean
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  liveSource?: LiveSourceFactory
+  liveHint?: string
+  resolveTuiUrl: () => Promise<string>
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}
+
+// Dispatches a selected list item to its viewer. The tui branch and the
+// interactive read-only transcript view each own their own raw-mode pi-tui
+// terminal, so they run WITHOUT the loop's tail scope (two raw-stdin owners
+// would corrupt input). The line/JSON session path and logs run UNDER the tail
+// scope, which owns the raw-mode esc/q/ctrl-c handling.
+export function openViewerItem(deps: OpenViewerDeps) {
+  return async (item: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+    if (item.kind === 'tui') {
+      const result = await runTuiViewer({
+        resolveUrl: deps.resolveTuiUrl,
+        stderr: deps.stderr,
+        ...(deps.expectedVersion !== undefined ? { expectedVersion: deps.expectedVersion } : {}),
+        ...(deps.onVersionMismatch !== undefined ? { onVersionMismatch: deps.onVersionMismatch } : {}),
+      })
+      // Detaching the writable tui viewer ends the live session — the only path
+      // that should suppress the writable row on the next list refresh.
+      return { result, endedWritableSession: result.ok && result.escToPicker === true }
+    }
+
+    // Interactive-TTY read-only session -> rich pi-tui transcript view. Owns its
+    // own terminal, so it bypasses the tail scope. JSON/non-TTY falls through to
+    // the scriptable line renderer below. Read-only: esc does NOT end a live
+    // session, so endedWritableSession stays unset.
+    if (item.kind === 'session' && deps.interactive && !deps.json) {
+      const view = createTranscriptView({
+        summary: item.summary,
+        filter: deps.filter,
+        sinceMs: deps.sinceMs,
+        ...(deps.liveSource !== undefined ? { liveSource: deps.liveSource } : {}),
+      })
+      const outcome = await view.run()
+      const result: RunInspectResult =
+        outcome.reason === 'back' ? { ok: true, exitCode: 0, escToPicker: true } : { ok: true, exitCode: 0 }
+      return { result }
+    }
+
+    const scope = ctx.createTailScope()
+    try {
+      if (item.kind === 'logs') {
+        const logsResult = await streamLogs({
+          cwd: deps.cwd,
+          color: deps.color,
+          stdout: deps.stdout,
+          stderr: deps.stderr,
+          signal: scope.signal,
+          ...(deps.liveHint !== undefined ? { liveHint: deps.liveHint } : {}),
+        })
+        // Logs esc does NOT touch the live session — no endedWritableSession.
+        return { result: toResult(logsResult.escToPicker, scope) }
+      }
+
+      const sessionResult = await streamInspectTarget({
+        agentDir: deps.cwd,
+        target: { summary: item.summary, filter: deps.filter, sinceMs: deps.sinceMs },
+        json: deps.json,
+        color: deps.color,
+        stdout: deps.stdout,
+        stderr: deps.stderr,
+        signal: scope.signal,
+        ...(deps.liveSource !== undefined ? { liveSource: deps.liveSource } : {}),
+        ...(deps.liveHint !== undefined ? { liveHint: deps.liveHint } : {}),
+        ...(deps.interactive ? { interactive: true } : {}),
+      })
+      const escToPicker = sessionResult.ok && sessionResult.escToPicker === true
+      return { result: toResult(escToPicker, scope) }
+    } finally {
+      scope.dispose()
+    }
+  }
+}
+
+function toResult(escToPicker: boolean, scope: TailController): RunInspectResult {
+  if (scope.intent() === 'exit') return { ok: true, exitCode: 0 }
+  if (escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
+  return { ok: true, exitCode: 0 }
+}

package/src/inspect/preview.ts

@@ -0,0 +1,106 @@
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+// Builds the one-line session-list hint from a session's first user turn.
+// User turns are wrapped in runtime-injected preamble (<current-time>, role
+// anchors, SYSTEM MESSAGE fences, channel context sections, …) that grows over
+// time. Rather than chase every block, this keys off stable semantic
+// boundaries and prefers null over a misleading hint — it is a cosmetic glance,
+// not a faithful reconstruction.
+export function previewForHint(origin: MinimalSessionOrigin | null, text: string): string | null {
+  // A subagent's first message is a machine payload (Parent session:, …) and
+  // the row label already names the subagent.
+  if (origin?.kind === 'subagent') return null
+  if (origin?.kind === 'channel') return channelPreview(text)
+  return structuralPreview(text)
+}
+
+// `[ISO] <@authorId> (authorName) [bot]: actual text` — the only line carrying
+// human-typed text in a channel turn. The stamp is omitted when ts<=0, so it is
+// optional here; name and bot tag are also optional.
+const AUTHOR_LINE = /^(?:\[[^\]]+\]\s+)?<[^>]+>(?:\s+\([^)]+\))?(?:\s+\[bot\])?:\s*(.*)$/
+
+const CURRENT_MESSAGE_HEADER = /^## Current messages? \(addressed to you\)\s*$/
+
+// Channel preview: extract ONLY from the "## Current message(s) (addressed to
+// you)" section — never the "## Recent context" section above it, which is other
+// people's messages the agent was only made aware of. Returns null if no
+// addressed message is found.
+function channelPreview(text: string): string | null {
+  const lines = text.split('\n')
+  const headerIdx = lines.findIndex((l) => CURRENT_MESSAGE_HEADER.test(l))
+  if (headerIdx === -1) return null
+
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    const match = AUTHOR_LINE.exec(lines[i]!)
+    if (match === null) continue
+    const payload = collectMessage(match[1] ?? '', lines, i + 1)
+    const trimmed = payload.trim()
+    return trimmed.length > 0 ? trimmed : null
+  }
+  return null
+}
+
+// An author line's text plus any continuation lines (a multi-line message
+// continues without the author prefix) until the next author line, a structural
+// boundary (## / ---), or a quote anchor (>).
+function collectMessage(first: string, lines: string[], start: number): string {
+  const parts = [first]
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]!
+    if (AUTHOR_LINE.test(line) || line.startsWith('## ') || line.startsWith('---') || line.startsWith('>')) break
+    parts.push(line)
+  }
+  return parts.join(' ')
+}
+
+// Origin-agnostic fallback (TUI, cron, system, unknown): skip leading injected
+// structure — XML-tag blocks, `--- … ---` SYSTEM MESSAGE fences, `## …`
+// sections, and blank lines — then take the first remaining real line. This
+// degrades gracefully as new runtime notices (which follow the same framing
+// conventions) are added, without needing per-block updates.
+function structuralPreview(text: string): string | null {
+  const lines = text.split('\n')
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    const trimmed = line.trim()
+    if (trimmed === '') {
+      i++
+    } else if (trimmed.startsWith('<')) {
+      i = skipXmlOrTagLine(lines, i)
+    } else if (trimmed.startsWith('---')) {
+      i = skipFence(lines, i)
+    } else if (trimmed.startsWith('#')) {
+      i++
+    } else {
+      return looksInjected(trimmed) ? null : trimmed
+    }
+  }
+  return null
+}
+
+// Skips a leading XML block. If the opening tag closes on the same line or
+// spans lines, advance past the matching close tag; otherwise skip just the one
+// line (a stray `<…>` shouldn't swallow the rest).
+function skipXmlOrTagLine(lines: string[], start: number): number {
+  const open = /^<([a-zA-Z][\w-]*)/.exec(lines[start]!.trim())
+  if (open === null) return start + 1
+  const close = `</${open[1]}>`
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i]!.includes(close)) return i + 1
+  }
+  return start + 1
+}
+
+// Skips a `---` fenced block (SYSTEM MESSAGE framing): from the opening `---`
+// to the next standalone `---`.
+function skipFence(lines: string[], start: number): number {
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i]!.trim() === '---') return i + 1
+  }
+  return start + 1
+}
+
+function looksInjected(line: string): boolean {
+  return line.startsWith('**[SYSTEM') || line.startsWith('[security/')
+}