typeclaw 0.25.0 → 0.27.0

package/src/container/logs.ts

@@ -44,27 +44,48 @@ export async function logs({
       return { ok: false, reason: `Container ${plan.containerName} not found. Run \`typeclaw start\` first.` }
     }
 
-    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdout: 'pipe', stderr: 'pipe' })
+    // stdin:'ignore' — `docker logs` never reads stdin, and letting the child
+    // hold the TTY breaks the viewer's raw-mode keypress listener (esc/q/ctrl-c
+    // stop reaching it, freezing the logs view with no way out).
+    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
 
+    // `docker logs -f` never exits on its own; aborting the signal must kill it
+    // so the pumps' stream readers end. Escalate to SIGKILL if SIGTERM is
+    // ignored, otherwise Promise.all(pumps) could hang until the pipes close.
+    let killTimer: ReturnType<typeof setTimeout> | undefined
     const onAbort = (): void => {
       try {
         proc.kill('SIGTERM')
+        killTimer = setTimeout(() => {
+          try {
+            proc.kill('SIGKILL')
+          } catch {
+            // already exited
+          }
+        }, 2_000)
       } catch {
         // already exited
       }
     }
     signal?.addEventListener('abort', onAbort, { once: true })
+    // The signal may already be aborted before we attached the listener (esc
+    // pressed during container existence check); addEventListener would then
+    // never fire, leaving docker logs -f running forever.
+    if (signal?.aborted === true) onAbort()
 
-    const colorOut = useColor ?? supportsColor(out)
-    const colorErr = useColor ?? supportsColor(err)
-    await Promise.all([
-      pumpWithTimestamps(proc.stdout, out, makeLogTimestampReformatter(undefined, { color: colorOut })),
-      pumpWithTimestamps(proc.stderr, err, makeLogTimestampReformatter(undefined, { color: colorErr })),
-    ])
-    const exitCode = await proc.exited
-    signal?.removeEventListener('abort', onAbort)
-
-    return { ok: true, containerName: plan.containerName, exitCode }
+    try {
+      const colorOut = useColor ?? supportsColor(out)
+      const colorErr = useColor ?? supportsColor(err)
+      await Promise.all([
+        pumpWithTimestamps(proc.stdout, out, makeLogTimestampReformatter(undefined, { color: colorOut }), signal),
+        pumpWithTimestamps(proc.stderr, err, makeLogTimestampReformatter(undefined, { color: colorErr }), signal),
+      ])
+      const exitCode = await proc.exited
+      return { ok: true, containerName: plan.containerName, exitCode }
+    } finally {
+      if (killTimer !== undefined) clearTimeout(killTimer)
+      signal?.removeEventListener('abort', onAbort)
+    }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
@@ -101,30 +122,57 @@ export function buildDockerLogsCmd(plan: LogsPlan): string[] {
 
 // Exported for `compose/logs.ts` so the multi-agent path reuses the same
 // reformatter and stays consistent with single-agent output.
+//
+// Abort handling is load-bearing for the interactive logs viewer: killing
+// `docker logs -f` does NOT reliably make Bun's pending `reader.read()` resolve
+// (the killed child may not promptly EOF its piped stdout — see the OrbStack
+// /proc quirk). Without cancelling the reader on abort, esc would hang forever.
+// So on abort we cancel the reader, which unblocks the pending read; the caller
+// still kills the process for OS-side cleanup.
 export async function pumpWithTimestamps(
   stream: ReadableStream<Uint8Array>,
   sink: NodeJS.WritableStream,
   reformatter: TimestampReformatter = makeLogTimestampReformatter(),
+  signal?: AbortSignal,
 ): Promise<void> {
   const decoder = new TextDecoder()
   const reader = stream.getReader()
+  let aborted = signal?.aborted === true
+  const onAbort = (): void => {
+    aborted = true
+    void reader.cancel().catch(() => {})
+  }
+  if (aborted) onAbort()
+  else signal?.addEventListener('abort', onAbort, { once: true })
+
   try {
     while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      if (value && value.byteLength > 0) {
-        const out = reformatter.write(decoder.decode(value, { stream: true }))
+      if (aborted) break
+      const chunk = await reader.read().catch((error: unknown) => {
+        if (aborted || signal?.aborted === true) return null
+        throw error
+      })
+      if (chunk === null || chunk.done || aborted) break
+      if (chunk.value && chunk.value.byteLength > 0) {
+        const out = reformatter.write(decoder.decode(chunk.value, { stream: true }))
         if (out.length > 0) sink.write(out)
       }
     }
-    const tail = decoder.decode()
-    if (tail.length > 0) {
-      const out = reformatter.write(tail)
-      if (out.length > 0) sink.write(out)
+    if (!aborted) {
+      const tail = decoder.decode()
+      if (tail.length > 0) {
+        const out = reformatter.write(tail)
+        if (out.length > 0) sink.write(out)
+      }
+      const flushed = reformatter.flush()
+      if (flushed.length > 0) sink.write(flushed)
     }
-    const flushed = reformatter.flush()
-    if (flushed.length > 0) sink.write(flushed)
   } finally {
-    reader.releaseLock()
+    signal?.removeEventListener('abort', onAbort)
+    try {
+      reader.releaseLock()
+    } catch {
+      // harmless if cancel/abort raced with stream teardown
+    }
   }
 }

package/src/init/index.ts

@@ -3,7 +3,6 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { DEFAULT_GITHUB_EVENT_ALLOWLIST } from '@/channels/schema'
 import { config, configSchema, migrateLegacyConfigShape, type Config } from '@/config'
 import {
   DEFAULT_MODEL_REF,
@@ -1167,10 +1166,12 @@ async function mergeChannelIntoConfig(cwd: string, options: AddChannelOptions):
 }
 
 function buildGithubChannelConfig(options: Extract<AddChannelOptions, { channel: 'github' }>): Record<string, unknown> {
+  // Do NOT write eventAllowlist: the schema defaults it at parse time, so
+  // omitting it lets the user's config track the shipped default across
+  // releases instead of freezing the list captured at `channel add` time.
   return {
     ...(options.webhookUrl !== undefined ? { webhookUrl: options.webhookUrl } : {}),
     webhookPort: options.webhookPort ?? 8975,
-    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
     repos: options.repos,
   }
 }
@@ -1246,7 +1247,6 @@ async function writeGithubChannelForInit(cwd: string, credentials: GithubInitCre
   existingChannels.github = {
     ...(credentials.webhookUrl !== undefined ? { webhookUrl: credentials.webhookUrl } : {}),
     webhookPort: credentials.webhookPort ?? 8975,
-    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
     repos: credentials.repos,
   }
   parsed.channels = existingChannels

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 {