typeclaw 0.26.0 → 0.28.0

package/src/cron/index.ts

@@ -1,17 +1,10 @@
 import { existsSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { SubagentRegistry } from '@/agent/subagents'
-import { commitSystemFile } from '@/git/system-commit'
 
-import {
-  buildCronMigrationCommitMessage,
-  type CronFile,
-  type CronMigrationStep,
-  migrateLegacyCronShape,
-  parseCronFile,
-} from './schema'
+import { type CronFile, parseCronFile } from './schema'
 
 export { createCronReloadable, type CreateCronReloadableOptions } from './reloadable'
 export {
@@ -31,16 +24,12 @@ export {
 } from './scheduler'
 export { aggregateCronList, type CronListEntry, type CronListSource } from './list'
 export {
-  buildCronMigrationCommitMessage,
   cronFileSchema,
   cronJobSchema,
   type CronFile,
   type CronJob,
-  type CronMigrationResult,
-  type CronMigrationStep,
   type ExecJob,
   type HandlerJob,
-  migrateLegacyCronShape,
   parseCronJson,
   type ParseCronJsonOptions,
   type ParseCronResult,
@@ -54,12 +43,6 @@ export type LoadCronResult = { ok: true; file: CronFile | null } | { ok: false;
 
 export type LoadCronOptions = {
   subagents?: SubagentRegistry
-  // When true (the default), legacy-shape migrations are written back
-  // to cron.json on disk and committed by the system-commit helper.
-  // Read-only inspection callers must pass `false` so an unaware
-  // `typeclaw cron list` against a legacy file does not produce a
-  // commit on whatever branch the user happens to be on.
-  persistMigrations?: boolean
 }
 
 export async function loadCron(agentDir: string, options: LoadCronOptions = {}): Promise<LoadCronResult> {
@@ -80,36 +63,12 @@ export async function loadCron(agentDir: string, options: LoadCronOptions = {}):
     return { ok: false, reason: `cron.json is not valid JSON: ${errorMessage(err)}` }
   }
 
-  const migrated = migrateLegacyCronShape(parsed)
-  const persistMigrations = options.persistMigrations ?? true
-  if (migrated.changed && persistMigrations) {
-    await persistMigratedCron(path, migrated.json, agentDir, migrated.applied)
-  }
-
-  const result = parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  const result = parseCronFile(parsed, options.subagents !== undefined ? { subagents: options.subagents } : {})
   if (!result.ok) return { ok: false, reason: result.reason }
 
   return { ok: true, file: result.file }
 }
 
-async function persistMigratedCron(
-  path: string,
-  json: unknown,
-  agentDir: string,
-  applied: readonly CronMigrationStep[],
-): Promise<void> {
-  try {
-    await writeFile(path, `${JSON.stringify(json, null, 2)}\n`)
-  } catch {
-    return
-  }
-
-  const message = buildCronMigrationCommitMessage(applied)
-  if (message !== null) {
-    await commitSystemFile(agentDir, CRON_FILE, message)
-  }
-}
-
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/cron/schema.ts

@@ -64,99 +64,7 @@ export type ParseCronOptions = {
   subagents?: SubagentRegistry
 }
 
-// One-shot rewrite for cron.json files that predate PR #171, when
-// `scheduledByRole` became mandatory on every job. The schema gate
-// (`parseCronFile`) rejects legacy entries with a precise remediation
-// message, but rejecting on every container boot is a stuck state for
-// the user — the agent crashes in a tight restart loop with no path
-// forward except hand-editing cron.json.
-//
-// The migration stamps `scheduledByRole: 'owner'` on every job that's
-// missing it. `owner` is the right default for two reasons:
-//   1. Before #171 there was no role concept; every cron job ran with
-//      the same (effectively-owner) privileges the agent had.
-//   2. The schema gate's own error message tells users to add
-//      `"scheduledByRole": "owner"` for manually-authored entries —
-//      we just do it for them.
-//
-// Mirrors `migrateLegacyConfigShape` in src/config/config.ts: pure
-// function, returns the rewritten JSON plus an `applied` array so
-// callers can build a meaningful commit message. Returns `changed:
-// false` on canonical input so the persist + commit path stays
-// untouched on the happy path.
-export type CronMigrationStep = { kind: 'stamp-scheduled-by-role-owner'; jobIds: string[] }
-
-export type CronMigrationResult = { json: unknown; changed: boolean; applied: CronMigrationStep[] }
-
-export function migrateLegacyCronShape(json: unknown): CronMigrationResult {
-  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
-    return { json, changed: false, applied: [] }
-  }
-
-  const obj = json as Record<string, unknown>
-  const jobs = obj.jobs
-  if (!Array.isArray(jobs)) {
-    return { json, changed: false, applied: [] }
-  }
-
-  const stampedIds: string[] = []
-  const nextJobs = jobs.map((job) => {
-    if (typeof job !== 'object' || job === null || Array.isArray(job)) return job
-    const record = job as Record<string, unknown>
-    if ('scheduledByRole' in record) return job
-    const id = typeof record.id === 'string' ? record.id : '<unknown>'
-    stampedIds.push(id)
-    return { ...record, scheduledByRole: 'owner' }
-  })
-
-  if (stampedIds.length === 0) {
-    return { json, changed: false, applied: [] }
-  }
-
-  return {
-    json: { ...obj, jobs: nextJobs },
-    changed: true,
-    applied: [{ kind: 'stamp-scheduled-by-role-owner', jobIds: stampedIds }],
-  }
-}
-
-// Builds a one-line git commit subject (plus enumerating body) for a
-// cron.json migration. Returns null when no steps were applied — callers
-// should not commit in that case. Mirrors `buildConfigMigrationCommitMessage`
-// in src/config/config.ts.
-export function buildCronMigrationCommitMessage(applied: readonly CronMigrationStep[]): string | null {
-  const first = applied[0]
-  if (first === undefined) return null
-
-  const subject =
-    applied.length === 1
-      ? `cron.json: ${shortCronStepLabel(first)}`
-      : `cron.json: migrate legacy shape (${applied.length} steps)`
-
-  const bodyLines: string[] = applied.map((step) => `- ${describeCronStep(step)}`)
-  return `${subject}\n\n${bodyLines.join('\n')}\n`
-}
-
-function shortCronStepLabel(step: CronMigrationStep): string {
-  switch (step.kind) {
-    case 'stamp-scheduled-by-role-owner':
-      return `stamp scheduledByRole: "owner" on ${step.jobIds.length} legacy job${step.jobIds.length === 1 ? '' : 's'}`
-  }
-}
-
-function describeCronStep(step: CronMigrationStep): string {
-  switch (step.kind) {
-    case 'stamp-scheduled-by-role-owner':
-      return `stamp scheduledByRole: "owner" on jobs without provenance (PR #171 backfill): ${step.jobIds.join(', ')}`
-  }
-}
-
-export type ParseCronJsonOptions = ParseCronOptions & {
-  // Apply `migrateLegacyCronShape` before schema validation. Defaults to true
-  // so the guard accepts the same legacy shapes `loadCron` would auto-migrate
-  // on disk; pass false to validate the exact bytes (used in tests).
-  migrate?: boolean
-}
+export type ParseCronJsonOptions = ParseCronOptions
 
 export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}): ParseCronResult {
   let json: unknown
@@ -166,9 +74,7 @@ export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}):
     return { ok: false, reason: `cron.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
   }
 
-  const shouldMigrate = options.migrate ?? true
-  const migrated = shouldMigrate ? migrateLegacyCronShape(json) : { json, changed: false, applied: [] }
-  return parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  return parseCronFile(json, options.subagents !== undefined ? { subagents: options.subagents } : {})
 }
 
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {

package/src/init/gitignore.ts

@@ -38,8 +38,7 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 #
 # auth.json is the pre-rename name for secrets.json; kept here permanently
 # as a safety net so an agent folder cloned from a pre-rename machine never
-# stages credentials by accident, even if its agent boot hasn't yet run the
-# auth.json -> secrets.json migration.
+# stages credentials by accident.
 #
 # .typeclaw/home/ is the persistent-$HOME overlay populated by the
 # entrypoint shim's \`link_persistent_home_files\` (see

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 {