typeclaw 0.26.0 → 0.28.0

package/src/channels/router.ts

@@ -32,6 +32,7 @@ import {
   StickyLedger,
   type EngagementDecision,
 } from './engagement'
+import { resetReviewTurn } from './github-review-turn-ledger'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
   type MembershipCount,
@@ -1844,6 +1845,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         live.skipLockedSendTurn = null
         live.policyDeniedToolSendsThisTurn.clear()
+        resetReviewTurn(live.sessionId)
         const isRealUserTurn = batch.length > 0
         await fireSessionTurnStart(live, text)
         try {
@@ -2854,7 +2856,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
-    const { text: assistantText, source } = candidate
+    const { text: candidateText, source } = candidate
+    let assistantText = candidateText
 
     if (endsWithNoReplySignal(assistantText)) {
       const leakedReasoning = !isNoReplySignal(assistantText)
@@ -2874,10 +2877,49 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
-    if (isLikelyPlainTextChannelToolCall(assistantText)) {
-      logger.warn(`[channels] ${live.keyId}: suppressed plain_text_channel_tool_call text_len=${assistantText.length}`)
+    // Plain-text tool-call leak: the model serialized a channel tool call as
+    // ordinary prose instead of producing a real tool call (a Kimi-on-Fireworks
+    // failure mode — see `isLikelyPlainTextChannelToolCall`). We can't post the
+    // raw `channel_reply({...})` serialization to the channel, but for
+    // reply/send the model's *intent* is unambiguous: deliver the `text` arg.
+    // Extract it and recover the actual message. `skip_response` is the
+    // opposite — a genuine decline — so it stays suppressed.
+    const plainTextToolCallKind = getPlainTextChannelToolCallKind(assistantText)
+    if (plainTextToolCallKind === 'skip') {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed plain_text_channel_skip_response text_len=${assistantText.length}`,
+      )
       return
     }
+    if (plainTextToolCallKind !== null) {
+      const extracted = extractPlainTextChannelToolCallText(assistantText)
+      // Unextractable (no `text` arg, empty value, or fully-truncated): fall
+      // back to the historical safe behavior — drop it rather than leak plumbing.
+      if (extracted === null) {
+        logger.warn(
+          `[channels] ${live.keyId}: suppressed unextractable_plain_text_channel_tool_call text_len=${assistantText.length}`,
+        )
+        return
+      }
+      // The extracted value is still untrusted model output: if it is itself a
+      // no-reply signal, an empty-response sentinel, or another (nested) leaked
+      // tool call, suppress it through the same guards rather than re-leaking.
+      if (
+        endsWithNoReplySignal(extracted) ||
+        isUpstreamEmptyResponseSentinel(extracted) ||
+        isLikelyKimiChannelToolLeak(extracted) ||
+        isLikelyPlainTextChannelToolCall(extracted)
+      ) {
+        logger.warn(
+          `[channels] ${live.keyId}: suppressed plain_text_channel_tool_call (unsafe extracted text) text_len=${extracted.length}`,
+        )
+        return
+      }
+      logger.warn(
+        `[channels] ${live.keyId}: recovered plain_text_channel_tool_call kind=${plainTextToolCallKind} text_len=${extracted.length}`,
+      )
+      assistantText = extracted
+    }
 
     // `source` distinguishes the three recovery shapes for log triage:
     //   - 'leaf': the assistant message IS the leaf with stopReason 'stop'
@@ -4233,8 +4275,12 @@ export function isLikelyKimiChannelToolLeak(text: string): boolean {
 //
 // Structural-only detection (NOT a substring search): the trimmed text must
 // *start* with `channel_reply(`, `channel_send(`, or `skip_response(`, and
-// that opening paren must enclose at least one `"` (the serialized argument).
-// This deliberately matches the leak shape while letting prose that merely
+// that opening paren must enclose at least one quote — `"` or `'` (the
+// serialized argument). The single-quote arm matters because the extractor
+// recovers single-quoted values too; if the classifier only matched `"`, a
+// single-quoted leak like `channel_reply({text: 'hi'})` would bypass the
+// extractor and post raw plumbing. This deliberately matches the leak shape
+// while letting prose that merely
 // *mentions* a tool name (e.g. "I would normally call channel_reply here
 // but...") reach the user — that false-positive class is already locked in by
 // the `still recovers prose that mentions channel_reply` test.
@@ -4242,12 +4288,150 @@ export function isLikelyKimiChannelToolLeak(text: string): boolean {
 // The trailing close paren is NOT required: the model sometimes truncates
 // mid-serialization, and a half-leaked `channel_reply({"text":"..."` is
 // just as user-hostile as the full shape.
-const PLAIN_TEXT_CHANNEL_TOOL_CALL_RE = /^(?:channel_(?:reply|send)|skip_response)\s*\(\s*[^)]*"/
+const PLAIN_TEXT_CHANNEL_TOOL_CALL_RE = /^(channel_reply|channel_send|skip_response)\s*\(\s*[^)]*["']/
+
+export type PlainTextChannelToolCallKind = 'reply' | 'send' | 'skip'
+
+export function getPlainTextChannelToolCallKind(text: string): PlainTextChannelToolCallKind | null {
+  const match = PLAIN_TEXT_CHANNEL_TOOL_CALL_RE.exec(text.trim())
+  if (match === null) return null
+  switch (match[1]) {
+    case 'channel_reply':
+      return 'reply'
+    case 'channel_send':
+      return 'send'
+    case 'skip_response':
+      return 'skip'
+    default:
+      return null
+  }
+}
 
 export function isLikelyPlainTextChannelToolCall(text: string): boolean {
-  return PLAIN_TEXT_CHANNEL_TOOL_CALL_RE.test(text.trim())
+  return getPlainTextChannelToolCallKind(text) !== null
+}
+
+// Tolerant single-purpose scanner that pulls the `text` argument out of a
+// plain-text-serialized `channel_reply(...)` / `channel_send(...)` leak. A
+// single regex covering every shape (double/single/unquoted keys, escaped
+// quotes, mid-serialization truncation) is fragile, so this walks the string
+// once and extracts only the first string-valued `text` property. `channel_send`
+// also carries `adapter`/`chat`/`thread`, which are intentionally ignored —
+// recovery always routes back through the current channel, never a
+// model-supplied destination. Returns null when no recoverable, non-empty
+// `text` value is present so the caller can fall back to suppression.
+export function extractPlainTextChannelToolCallText(text: string): string | null {
+  const trimmed = text.trim()
+  if (!/^(?:channel_reply|channel_send)\s*\(/.test(trimmed)) return null
+
+  // Walk the serialization once, honoring a `text` key only at the top level of
+  // the argument object (braceDepth 1, outside any array). Two failure classes
+  // motivate the bookkeeping: a `text:` inside an earlier quoted value, e.g.
+  // `channel_send({ reason: "see text: here", text: "real" })`, and a `text:`
+  // inside a *nested* object, e.g. `channel_reply({ meta: { text: "x" }, text:
+  // "real" })`. Skipping string literals defeats the first; tracking
+  // brace/bracket depth and matching keys only at top level defeats the second.
+  // Either way the scanner lands on the real reply instead of leaking the wrong
+  // value or dropping the message.
+  let braceDepth = 0
+  let bracketDepth = 0
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i]!
+
+    if (ch === '"' || ch === "'") {
+      i = skipStringLiteral(trimmed, i, ch)
+      continue
+    }
+
+    if (ch === '{') {
+      braceDepth++
+      if (braceDepth === 1 && bracketDepth === 0) {
+        const value = readTextKeyValueAt(trimmed, i + 1)
+        if (value !== undefined) return value
+      }
+      continue
+    }
+    if (ch === '}') {
+      if (braceDepth > 0) braceDepth--
+      continue
+    }
+    if (ch === '[') {
+      bracketDepth++
+      continue
+    }
+    if (ch === ']') {
+      if (bracketDepth > 0) bracketDepth--
+      continue
+    }
+
+    if (ch === ',' && braceDepth === 1 && bracketDepth === 0) {
+      const value = readTextKeyValueAt(trimmed, i + 1)
+      if (value !== undefined) return value
+    }
+  }
+
+  return null
+}
+
+// Returns the recovered value (string or null) when a `text` key starts at
+// `from`, or undefined when no `text` key is present there so the scanner keeps
+// walking. The null/undefined split lets a malformed `text` value short-circuit
+// to suppression while a non-`text` delimiter is simply skipped.
+function readTextKeyValueAt(s: string, from: number): string | null | undefined {
+  const afterKey = matchTextKey(s, from)
+  if (afterKey === null) return undefined
+
+  const quote = s[afterKey]
+  if (quote !== '"' && quote !== "'") return null
+  return readStringValue(s, afterKey + 1, quote)
+}
+
+// Returns the closing-quote index, or the last index when the literal is
+// truncated, so the caller's `i++` resumes past the consumed string.
+function skipStringLiteral(s: string, openIdx: number, quote: string): number {
+  let escaped = false
+  for (let i = openIdx + 1; i < s.length; i++) {
+    const ch = s[i]!
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (ch === '\\') {
+      escaped = true
+      continue
+    }
+    if (ch === quote) return i
+  }
+  return s.length
+}
+
+function matchTextKey(s: string, from: number): number | null {
+  const m = /^\s*(?:"text"|'text'|text)\s*:\s*/.exec(s.slice(from))
+  return m === null ? null : from + m[0].length
 }
 
+function readStringValue(s: string, from: number, quote: string): string | null {
+  let value = ''
+  let escaped = false
+  for (let i = from; i < s.length; i++) {
+    const ch = s[i]!
+    if (escaped) {
+      value += ESCAPE_REPLACEMENTS[ch] ?? ch
+      escaped = false
+      continue
+    }
+    if (ch === '\\') {
+      escaped = true
+      continue
+    }
+    if (ch === quote) break
+    value += ch
+  }
+  return value.trim().length > 0 ? value : null
+}
+
+const ESCAPE_REPLACEMENTS: Record<string, string> = { n: '\n', r: '\r', t: '\t' }
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/channels/schema.ts

@@ -107,11 +107,9 @@ const quotedReplySchema = z
   .default({ enabled: true, queueDelayMs: DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS })
 
 // Deliberately non-strict: a stale on-disk file may still carry the
-// legacy `allow` field (`migrateLegacyConfigShape` lifts it into
-// `roles.member.match[]` on load, but a between-reload window can
-// briefly contain both). Zod silently drops unknown keys here, which is
-// exactly what we want — a hard `.strict()` reject would brick recovery
-// for any user mid-migration.
+// legacy `allow` field. Zod silently drops unknown keys here, which is
+// exactly what we want — the field is ignored, not translated, and a hard
+// `.strict()` reject would brick recovery for any user with an old config.
 const adapterSchema = z.object({
   engagement: engagementSchema,
   history: historySchema,
@@ -128,6 +126,7 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request.ready_for_review',
   'pull_request.review_requested',
   'pull_request.review_request_removed',
+  'pull_request.synchronize',
   'discussion.created',
   'pull_request_review.submitted',
 ] as const
@@ -158,6 +157,21 @@ const GITHUB_EVENT_ALLOWLIST_V2 = [
   'discussion.created',
   'pull_request_review.submitted',
 ] as const
+//   - v3: added ready_for_review, shipped 0.12.0+ (the default just before
+//     synchronize was added). Snapshotted here so configs seeded with the
+//     pre-synchronize default unfreeze and re-track the new default.
+const GITHUB_EVENT_ALLOWLIST_V3 = [
+  'issue_comment.created',
+  'pull_request_review_comment.created',
+  'discussion_comment.created',
+  'issues.opened',
+  'pull_request.opened',
+  'pull_request.ready_for_review',
+  'pull_request.review_requested',
+  'pull_request.review_request_removed',
+  'discussion.created',
+  'pull_request_review.submitted',
+] as const
 
 // Every event-allowlist that `channel add` / `init` has ever seeded verbatim
 // into typeclaw.json, oldest first, current default last. The legacy-shape
@@ -169,6 +183,7 @@ const GITHUB_EVENT_ALLOWLIST_V2 = [
 export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
   GITHUB_EVENT_ALLOWLIST_V1,
   GITHUB_EVENT_ALLOWLIST_V2,
+  GITHUB_EVENT_ALLOWLIST_V3,
   DEFAULT_GITHUB_EVENT_ALLOWLIST,
 ]
 

package/src/cli/channel.ts

@@ -629,8 +629,9 @@ async function promptGithubCredentials(cwd: string): Promise<{
     message: 'GitHub authentication type',
     options: [
       { value: 'pat', label: 'Fine-grained personal access token' },
-      { value: 'app', label: 'GitHub App installation token' },
+      { value: 'app', label: 'GitHub App installation token (recommended)' },
     ],
+    initialValue: 'app',
   })
   if (isCancel(authType)) {
     cancel('Aborted.')

package/src/cli/init.ts

@@ -1182,8 +1182,9 @@ async function runGithubFlow(cwd: string): Promise<StepResult<CollectedInputs['c
     message: 'GitHub authentication type',
     options: [
       { value: 'pat', label: 'Fine-grained personal access token' },
-      { value: 'app', label: 'GitHub App installation token' },
+      { value: 'app', label: 'GitHub App installation token (recommended)' },
     ],
+    initialValue: 'app',
   })
   if (isCancel(authType)) return back()
   const auth = authType === 'pat' ? await promptGithubPatAuth() : await promptGithubAppAuth()

package/src/cli/inspect.ts

@@ -2,7 +2,19 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
+import {
+  listViewerItems,
+  openViewerItem,
+  parseDuration,
+  parseFilter,
+  resolveSession,
+  runInspectLoop,
+  runViewerLoop,
+  streamLive,
+  type LiveSourceFactory,
+  type SessionSummary,
+  type ViewerItem,
+} from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createTailScope } from './inspect-controller'
@@ -13,12 +25,12 @@ const ESC_DEBOUNCE_MS = 50
 export const inspectCommand = defineCommand({
   meta: {
     name: 'inspect',
-    description: 'observe a session: replay the transcript, then tail live activity (host stage)',
+    description: 'session viewer: pick a session, the live TUI, or container logs to observe (host stage)',
   },
   args: {
     session: {
       type: 'positional',
-      description: 'session id or short prefix (omit to pick from a list)',
+      description: 'session id or short prefix (omit to pick from the list)',
       required: false,
     },
     filter: {
@@ -42,42 +54,175 @@ export const inspectCommand = defineCommand({
     const sessionArg = typeof args.session === 'string' ? args.session : undefined
     const filterArg = typeof args.filter === 'string' ? args.filter : undefined
     const sinceArg = typeof args.since === 'string' ? args.since : undefined
-
     const isJson = args.json === true
-    const liveSource = isJson ? undefined : await buildLiveSource(cwd)
-    const interactive = !isJson && Boolean(process.stdin.isTTY)
-    const liveHint = interactive ? escHintLine(color) : undefined
-
-    const result = await runInspectLoop({
-      agentDir: cwd,
-      ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
-      ...(filterArg !== undefined ? { filter: filterArg } : {}),
-      ...(sinceArg !== undefined ? { since: sinceArg } : {}),
-      json: isJson,
-      color,
-      selectSession: (sessions, selectOpts) => clackSelect(sessions, selectOpts?.initialSessionId),
-      ...(liveSource !== undefined ? { liveSource } : {}),
-      createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
-      ...(interactive ? { interactive: true } : {}),
-      ...(liveHint !== undefined ? { liveHint } : {}),
-      stdout: (line) => process.stdout.write(`${line}\n`),
-      stderr: (line) => process.stderr.write(`${line}\n`),
-    })
 
-    if (!result.ok) {
-      process.stderr.write(`${errorLine(result.reason)}\n`)
-      process.exit(result.exitCode)
+    // JSON mode stays the scriptable, session-only path: no list, no logs/tui
+    // rows, explicit session id required. Behavior is unchanged from before the
+    // viewer merge.
+    if (isJson) {
+      const result = await runInspectLoop({
+        agentDir: cwd,
+        ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
+        ...(filterArg !== undefined ? { filter: filterArg } : {}),
+        ...(sinceArg !== undefined ? { since: sinceArg } : {}),
+        json: true,
+        color,
+        selectSession: (sessions, selectOpts) => clackSelectSession(sessions, selectOpts?.initialSessionId),
+        createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+        stdout: (line) => process.stdout.write(`${line}\n`),
+        stderr: (line) => process.stderr.write(`${line}\n`),
+      })
+      finish(result)
+      return
     }
-    process.exit(result.exitCode)
+
+    const exitCode = await runInspectViewer({
+      cwd,
+      ...(sessionArg !== undefined ? { sessionArg } : {}),
+      ...(filterArg !== undefined ? { filterArg } : {}),
+      ...(sinceArg !== undefined ? { sinceArg } : {}),
+      color,
+    })
+    process.exit(exitCode)
   },
 })
 
-async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
-  const precheck = await requireContainerRunning({ cwd })
-  if (!precheck.ok) {
-    process.stderr.write(`${c.yellow('⚠')} ${precheck.reason}; tailing live events disabled\n`)
-    return undefined
+export type RunInspectViewerOptions = {
+  cwd: string
+  sessionArg?: string
+  filterArg?: string
+  sinceArg?: string
+  color?: boolean
+  // Set false by the `tui` detach handoff: the live session was just ended, so
+  // no row should be offered as writable (see listViewerItems).
+  allowWritable?: boolean
+}
+
+// The interactive session-viewer: list → open → back to list. Shared by the
+// `inspect` command and `tui`'s esc-detach fallthrough. Returns an exit code
+// instead of calling process.exit so callers can chain (e.g. tui drops here).
+export async function runInspectViewer(opts: RunInspectViewerOptions): Promise<number> {
+  const { cwd } = opts
+  const color = opts.color ?? useColor()
+
+  const filterResult = parseFilter(opts.filterArg)
+  if (!filterResult.ok) {
+    process.stderr.write(`${errorLine(filterResult.reason)}\n`)
+    return 2
+  }
+  let sinceMs: number | undefined
+  if (opts.sinceArg !== undefined) {
+    const d = parseDuration(opts.sinceArg)
+    if (!d.ok) {
+      process.stderr.write(`${errorLine(d.reason)}\n`)
+      return 2
+    }
+    sinceMs = Date.now() - d.ms
+  }
+
+  const containerRunning = (await requireContainerRunning({ cwd })).ok
+  if (!containerRunning) {
+    process.stderr.write(`${c.yellow('⚠')} container not running; showing read-only history and logs only\n`)
+  }
+
+  const sessionsDir = `${cwd}/sessions`
+
+  // Resolve a session arg (id or short prefix) to a full session id BEFORE the
+  // loop: runViewerLoop matches preselectKey against exact itemKeys, so a bare
+  // prefix would otherwise miss every row and report "no sessions". 'logs' is a
+  // reserved key, not a session, so it bypasses resolution.
+  let preselectKey: string | undefined
+  if (opts.sessionArg !== undefined && opts.sessionArg !== 'logs') {
+    const resolved = await resolveSession(sessionsDir, opts.sessionArg, (l) => process.stderr.write(`${l}\n`))
+    if (!resolved.ok) {
+      const reason =
+        resolved.reason === 'ambiguous'
+          ? `Ambiguous session prefix "${opts.sessionArg}" matches ${resolved.matches.length} sessions. Use a longer prefix or run \`typeclaw inspect\` without args.`
+          : `No session matching "${opts.sessionArg}" in ${sessionsDir}/`
+      process.stderr.write(`${errorLine(reason)}\n`)
+      return resolved.reason === 'ambiguous' ? 2 : 1
+    }
+    preselectKey = resolved.summary.sessionId
+  } else if (opts.sessionArg === 'logs') {
+    preselectKey = 'logs'
+  }
+
+  const interactive = Boolean(process.stdin.isTTY)
+  const liveHint = interactive ? escHintLine(color) : undefined
+  const liveSource = containerRunning ? await buildLiveSource(cwd) : undefined
+
+  const stdout = (line: string): void => {
+    process.stdout.write(`${line}\n`)
+  }
+  const stderr = (line: string): void => {
+    process.stderr.write(`${line}\n`)
+  }
+
+  const open = openViewerItem({
+    cwd,
+    filter: filterResult.filter,
+    sinceMs,
+    json: false,
+    color,
+    interactive,
+    stdout,
+    stderr,
+    resolveTuiUrl: () => resolveTuiUrl(cwd),
+    ...(liveSource !== undefined ? { liveSource } : {}),
+    ...(liveHint !== undefined ? { liveHint } : {}),
+  })
+
+  const cliAllowWritable = opts.allowWritable !== false
+  const result = await runViewerLoop<ViewerItem>({
+    listItems: async ({ allowWritable: loopAllowWritable }) => {
+      const listOpts: Parameters<typeof listViewerItems>[0] = {
+        sessionsDir,
+        containerRunning,
+        // Compose the CLI-level permission (false on tui detach handoff) with
+        // the loop-level one (false after returning to the picker from a viewer).
+        allowWritable: cliAllowWritable && loopAllowWritable,
+        limit: 20,
+        onWarn: stderr,
+      }
+      if (sinceMs !== undefined) listOpts.sinceMs = sinceMs
+      return (await listViewerItems(listOpts)).items
+    },
+    keyOf: (item) => (item.kind === 'logs' ? 'logs' : item.summary.sessionId),
+    ...(preselectKey !== undefined ? { preselectKey } : {}),
+    selectItem: (items, selectOpts) => clackSelectItem(items, selectOpts.initialKey),
+    openItem: open,
+    createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+    onEmpty: () => ({
+      ok: false,
+      exitCode: 1,
+      reason: `No sessions found in ${sessionsDir}/.\nStart a session with \`typeclaw tui\` or send a message from a configured channel.`,
+    }),
+  })
+
+  if (!result.ok && result.reason !== undefined) {
+    process.stderr.write(`${errorLine(result.reason)}\n`)
+  }
+  return result.exitCode
+}
+
+function finish(result: { ok: boolean; exitCode: number; reason?: string }): void {
+  if (!result.ok && result.reason !== undefined) {
+    process.stderr.write(`${errorLine(result.reason)}\n`)
   }
+  process.exit(result.exitCode)
+}
+
+async function resolveTuiUrl(cwd: string): Promise<string> {
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) throw new Error(precheck.reason)
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const baseUrl = new URL(`ws://127.0.0.1:${port}/inspect`)
@@ -94,7 +239,7 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
 }
 
 function escHintLine(color: boolean): string {
-  const text = '(esc to return to session list · q to quit)'
+  const text = '(esc to return to the list · q to quit)'
   return color ? `\u001b[2m${text}\u001b[0m` : text
 }
 
@@ -105,7 +250,29 @@ function useColor(): boolean {
   return Boolean(process.stdout.isTTY)
 }
 
-async function clackSelect(
+async function clackSelectItem(items: ViewerItem[], initialKey: string | undefined): Promise<ViewerItem | null> {
+  const { select } = await import('@clack/prompts')
+  prepareStdinForClack()
+  const keyOf = (item: ViewerItem): string => (item.kind === 'logs' ? 'logs' : item.summary.sessionId)
+  const preferred =
+    initialKey !== undefined && items.some((i) => keyOf(i) === initialKey) ? initialKey : keyOf(items[0]!)
+  const picked = await select<string>({
+    message: `Pick what to view (showing ${items.length})`,
+    options: items.map((item) => ({
+      value: keyOf(item),
+      label: itemLabel(item),
+      ...itemHint(item),
+    })),
+    initialValue: preferred,
+  })
+  if (isCancel(picked)) {
+    cancel('Cancelled.')
+    return null
+  }
+  return items.find((i) => keyOf(i) === picked) ?? null
+}
+
+async function clackSelectSession(
   sessions: SessionSummary[],
   initialSessionId: string | undefined,
 ): Promise<SessionSummary | null> {
@@ -119,7 +286,7 @@ async function clackSelect(
     message: `Pick a session to inspect (showing ${sessions.length})`,
     options: sessions.map((s) => ({
       value: s.sessionId,
-      label: formatRowLabel(s),
+      label: sessionRowLabel(s),
       ...(s.firstPrompt !== null ? { hint: truncate(s.firstPrompt, 60) } : { hint: '(no prompt)' }),
     })),
     initialValue: preferred,
@@ -131,7 +298,20 @@ async function clackSelect(
   return sessions.find((s) => s.sessionId === picked) ?? null
 }
 
-function formatRowLabel(s: SessionSummary): string {
+function itemLabel(item: ViewerItem): string {
+  if (item.kind === 'logs') return `${c.dim('▤')} container logs`
+  if (item.kind === 'tui') return `${c.green('●')} ${c.bold('live TUI')}  ${sessionRowLabel(item.summary)}`
+  return `${c.dim('○')} ${sessionRowLabel(item.summary)}`
+}
+
+function itemHint(item: ViewerItem): { hint: string } {
+  if (item.kind === 'logs') return { hint: 'read-only · works offline' }
+  if (item.kind === 'tui') return { hint: 'read+write · esc detaches and ends the live session' }
+  if (item.summary.firstPrompt !== null) return { hint: truncate(item.summary.firstPrompt, 60) }
+  return { hint: '(no prompt)' }
+}
+
+function sessionRowLabel(s: SessionSummary): string {
   const id = shortSessionId(s.sessionId)
   const label = s.origin === null ? '(unknown origin)' : originLabel(s.origin)
   const when = formatRelative(s.mtimeMs)

package/src/cli/logs.ts

@@ -3,6 +3,7 @@ import { defineCommand } from 'citty'
 import { logs, parseTailValue } from '@/container'
 import { findAgentDir } from '@/init'
 
+import { runInspectViewer } from './inspect'
 import { c, errorLine } from './ui'
 
 export const logsCommand = defineCommand({
@@ -22,6 +23,11 @@ export const logsCommand = defineCommand({
       alias: 'n',
       description: 'number of lines to show from the end of the logs (non-negative integer or "all")',
     },
+    list: {
+      type: 'boolean',
+      description: 'open the session viewer on the logs entry instead of dumping logs',
+      default: false,
+    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
@@ -36,6 +42,15 @@ export const logsCommand = defineCommand({
       tail = parsed.value
     }
 
+    // The viewer is strictly opt-in via --list, so the default `typeclaw logs`
+    // (piped, redirected, -f, or a plain TTY dump) keeps the raw `docker logs`
+    // pump that `typeclaw logs | grep` and CI depend on. --list drops into the
+    // session viewer pre-opened on the logs entry, where esc returns to the list.
+    if (args.list) {
+      const exitCode = await runInspectViewer({ cwd, sessionArg: 'logs' })
+      process.exit(exitCode)
+    }
+
     if (args.follow) {
       console.log(c.cyan('Streaming container logs...'))
     } else {