typeclaw 0.9.2 → 0.10.0

package/src/cli/inspect.ts

@@ -2,15 +2,17 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runInspect, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
+import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { cancel, c, errorLine, isCancel } from './ui'
 
+const ESC_LISTEN_DELAY_MS = 50
+
 export const inspectCommand = defineCommand({
   meta: {
     name: 'inspect',
-    description: 'replay a session transcript and tail live activity (host stage)',
+    description: 'observe a session: replay the transcript, then tail live activity (host stage)',
   },
   args: {
     session: {
@@ -32,12 +34,6 @@ export const inspectCommand = defineCommand({
       description: 'emit one JSON event per line; requires an explicit session id',
       default: false,
     },
-    follow: {
-      type: 'boolean',
-      description:
-        'tail live activity after replay (default: true when the container is running); pass --no-follow to replay-then-exit',
-      default: true,
-    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
@@ -45,26 +41,39 @@ 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 follow = args.follow !== false
 
     const isJson = args.json === true
-    const liveSource = !follow || isJson ? undefined : await buildLiveSource(cwd)
+    const liveSource = isJson ? undefined : await buildLiveSource(cwd)
     const signal = installSigintAbort()
+    const escListener = isJson ? null : createEscListener()
+    const liveHint = escListener === null ? undefined : escHintLine(color)
 
-    const result = await runInspect({
+    const result = await runInspectLoop({
       agentDir: cwd,
       ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
       ...(filterArg !== undefined ? { filter: filterArg } : {}),
       ...(sinceArg !== undefined ? { since: sinceArg } : {}),
       json: isJson,
       color,
-      selectSession: clackSelect,
+      selectSession: (sessions) => {
+        escListener?.pause()
+        return clackSelect(sessions).finally(() => {
+          escListener?.resume()
+        })
+      },
       ...(liveSource !== undefined ? { liveSource } : {}),
       signal,
+      newEscSignal: () => {
+        if (escListener === null) return new AbortController().signal
+        return escListener.armForStream()
+      },
+      ...(liveHint !== undefined ? { liveHint } : {}),
       stdout: (line) => process.stdout.write(`${line}\n`),
       stderr: (line) => process.stderr.write(`${line}\n`),
     })
 
+    escListener?.stop()
+
     if (!result.ok) {
       process.stderr.write(`${errorLine(result.reason)}\n`)
       process.exit(result.exitCode)
@@ -104,6 +113,90 @@ function installSigintAbort(): AbortSignal {
   return ctrl.signal
 }
 
+type EscListener = {
+  armForStream: () => AbortSignal
+  pause: () => void
+  resume: () => void
+  stop: () => void
+}
+
+function createEscListener(): EscListener | null {
+  const stdin = process.stdin
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
+
+  let currentCtrl: AbortController | null = null
+  let pendingEsc: ReturnType<typeof setTimeout> | null = null
+  let active = false
+
+  const onData = (chunk: Buffer): void => {
+    if (chunk.length === 0) return
+    const first = chunk[0]
+    if (first === 0x03) {
+      process.kill(process.pid, 'SIGINT')
+      return
+    }
+    if (chunk.length === 1 && first === 0x1b) {
+      if (pendingEsc !== null) clearTimeout(pendingEsc)
+      pendingEsc = setTimeout(() => {
+        pendingEsc = null
+        currentCtrl?.abort()
+      }, ESC_LISTEN_DELAY_MS)
+      return
+    }
+    if (pendingEsc !== null) {
+      clearTimeout(pendingEsc)
+      pendingEsc = null
+    }
+  }
+
+  const start = (): void => {
+    if (active) return
+    active = true
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+  }
+  const stop = (): void => {
+    if (!active) return
+    active = false
+    stdin.off('data', onData)
+    try {
+      stdin.setRawMode(false)
+    } catch {
+      /* terminal already torn down */
+    }
+    stdin.pause()
+    if (pendingEsc !== null) {
+      clearTimeout(pendingEsc)
+      pendingEsc = null
+    }
+  }
+
+  return {
+    armForStream: () => {
+      currentCtrl = new AbortController()
+      start()
+      return currentCtrl.signal
+    },
+    pause: () => {
+      stop()
+    },
+    resume: () => {
+      currentCtrl = new AbortController()
+      start()
+    },
+    stop: () => {
+      currentCtrl = null
+      stop()
+    },
+  }
+}
+
+function escHintLine(color: boolean): string {
+  const text = '(press esc to return to session list)'
+  return color ? `\u001b[2m${text}\u001b[0m` : text
+}
+
 function useColor(): boolean {
   if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
   if (process.env.FORCE_COLOR === '0') return false

package/src/cli/role.ts

@@ -11,7 +11,7 @@ const claimSub = defineCommand({
   meta: {
     name: 'claim',
     description:
-      'claim a channel identity (Slack/Discord/etc.) for a role on this agent. Sends a code via the host CLI; you DM that code back to the bot to prove control of the channel account.',
+      'claim a channel identity (Slack/Discord/etc.) for a role on this agent. Sends a code via the host CLI; you send that code back to the bot from any chat (DM, group, channel) to prove control of the channel account. The resulting match rule grants the role to your author identity across every chat on that platform.',
   },
   args: {
     as: {
@@ -57,7 +57,7 @@ const claimSub = defineCommand({
         s.stop('Ready.')
         const expiresInSec = Math.max(0, Math.round((payload.expiresAt - Date.now()) / 1000))
         const lines = [
-          `Send this message to your bot as a DM:`,
+          `Send this message to your bot from any chat (DM, group, or channel):`,
           '',
           `  ${c.bold(payload.code)}`,
           '',

package/src/config/providers.ts

@@ -465,6 +465,24 @@ export function providerForModelRef(ref: KnownModelRef): KnownProviderId {
   throw new Error(`Unknown provider in model ref: ${ref}`)
 }
 
+// Per-provider default for pi-coding-agent's `thinkingLevel` knob. Returning
+// `undefined` defers to the SDK default (`medium`); returning a level pins it
+// to that value at session-creation time.
+//
+// OpenAI-family providers (`openai`, `openai-codex`) pin to `low`: GPT-5.x at
+// `medium` pads reasoning tokens on routine tool-driven turns (code edits,
+// channel replies, cron prompts) with no observable quality delta on this
+// codebase's workloads. Applies to every session that resolves to a GPT model
+// regardless of profile, so the saving is uniform.
+//
+// Anthropic, GLM, and Kimi don't share the padding behavior, so they keep the
+// SDK default.
+export function defaultThinkingLevelForRef(ref: KnownModelRef): 'low' | undefined {
+  const providerId = providerForModelRef(ref)
+  if (providerId === 'openai' || providerId === 'openai-codex') return 'low'
+  return undefined
+}
+
 // `as const satisfies` narrows each entry's `auth` to a tuple of its specific
 // literal values, which makes `provider.auth.includes('oauth')` fail to
 // compile on api-key-only entries (because TS thinks the array can never

package/src/cron/bridge.ts

@@ -1,10 +1,14 @@
-import { resolveHostPort, resolveTuiToken } from '@/container'
+import { CONTAINER_PORT, resolveHostPort, resolveTuiToken } from '@/container'
 import type { ClientMessage, CronListEntryPayload, ServerMessage } from '@/shared'
 
 export type CronListBridgeOptions = {
   cwd: string
   url?: string
   timeoutMs?: number
+  // Injected for tests so the in-container short-circuit can be exercised
+  // without polluting process.env. Production callers omit this and the
+  // bridge reads from process.env directly.
+  env?: NodeJS.ProcessEnv
 }
 
 export type CronListBridgeResult =
@@ -34,9 +38,7 @@ async function dial(opts: CronListBridgeOptions): Promise<DialResult> {
   let url = opts.url
   if (url === undefined) {
     try {
-      const port = await resolveHostPort({ cwd: opts.cwd })
-      const token = await resolveTuiToken({ cwd: opts.cwd })
-      url = buildBridgeUrl(port, token)
+      url = resolveInContainerUrl(opts.env ?? process.env) ?? (await resolveHostUrl(opts.cwd))
     } catch (err) {
       return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
     }
@@ -115,6 +117,25 @@ async function awaitReply(ws: WebSocket, timeoutMs: number, requestId: string):
   })
 }
 
+// In-container short-circuit: when typeclaw runs `docker run`, it sets
+// TYPECLAW_CONTAINER_NAME (always) and TYPECLAW_TUI_TOKEN (when configured).
+// Inside the container, docker is not on $PATH, so the host-side discovery
+// path (resolveHostPort/resolveTuiToken — both shell out to `docker`) fails
+// with "docker: command not found". We don't need docker here: the agent's
+// WS server is listening on CONTAINER_PORT on the container's loopback, and
+// the token is already in our env. Skip docker entirely and dial directly.
+export function resolveInContainerUrl(env: NodeJS.ProcessEnv): string | null {
+  if (env.TYPECLAW_CONTAINER_NAME === undefined) return null
+  const token = env.TYPECLAW_TUI_TOKEN ?? ''
+  return buildBridgeUrl(CONTAINER_PORT, token !== '' ? token : null)
+}
+
+async function resolveHostUrl(cwd: string): Promise<string> {
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  return buildBridgeUrl(port, token)
+}
+
 function buildBridgeUrl(port: number, token: string | null): string {
   const url = new URL(`ws://127.0.0.1:${port}`)
   if (token !== null) url.searchParams.set('token', token)

package/src/hostd/daemon.ts

@@ -69,7 +69,7 @@ export type RestartPreflight = (input: {
 }) => Promise<RpcResponse | null>
 
 export type PortbrokerCallbacks = {
-  start: (input: PortbrokerStartInput) => void
+  start: (input: PortbrokerStartInput) => Promise<void>
   stop: (containerName: string, reason: 'deregistered' | 'broker-stopped') => Promise<void>
   // Returns ports the broker is currently exposing on the host for this
   // container. Empty array when the container is unregistered, when the broker
@@ -157,8 +157,10 @@ function isValidRestoredPayload(value: unknown, expectedName: string): value is
 }
 
 async function restorePersistedRegistrations(
-  apply: (payload: RestoredPayload) => void,
+  apply: (payload: RestoredPayload) => Promise<void>,
   log: (event: DaemonLogEvent | SupervisorLogEvent) => void,
+  probe: (name: string) => Promise<'alive' | 'gone' | 'unknown'>,
+  removeFile: (name: string) => Promise<void>,
 ): Promise<void> {
   let entries: string[]
   try {
@@ -181,7 +183,23 @@ async function restorePersistedRegistrations(
       log({ kind: 'registration-skipped', containerName: expectedName, reason: 'schema mismatch' })
       continue
     }
-    apply(parsed)
+    // Probe before reviving. A registration file for a container that no
+    // longer exists is a leftover from a daemon that died ungracefully
+    // (crash, `kill -9`, OS reboot) before deregister could clean up.
+    // Reviving its broker would create a stale T_old broker that races a
+    // subsequent `register` call's T_new broker — see portbroker-manager.ts
+    // start() for the swap-race description. `unknown` (docker probe call
+    // failed) errs toward restore: the existing GC tick will tear down the
+    // registration if the container is genuinely gone, and we'd rather pay
+    // one swap-race attempt than tear down a live registration on a flaky
+    // `docker ps`.
+    const status = await probe(expectedName)
+    if (status === 'gone') {
+      await removeFile(expectedName)
+      log({ kind: 'registration-skipped', containerName: expectedName, reason: 'container not running' })
+      continue
+    }
+    await apply(parsed)
   }
 }
 
@@ -267,7 +285,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
     } catch {}
   }
 
-  const applyRegistration = (payload: RegisterPayload): void => {
+  const applyRegistration = async (payload: RegisterPayload): Promise<void> => {
     const alreadyRegistered = cwds.has(payload.containerName)
     cwds.set(payload.containerName, payload.cwd)
     if (payload.restartToken) restartTokens.set(payload.containerName, payload.restartToken)
@@ -281,7 +299,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
       payload.portForward !== undefined &&
       payload.brokerToken !== undefined
     ) {
-      opts.portbroker.start({
+      await opts.portbroker.start({
         containerName: payload.containerName,
         cwd: payload.cwd,
         policy: payload.portForward,
@@ -308,7 +326,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
           reason: `failed to persist registration: ${error instanceof Error ? error.message : String(error)}`,
         }
       }
-      applyRegistration(req)
+      await applyRegistration(req)
       return { ok: true }
     })
   }
@@ -528,12 +546,31 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
   httpPort = httpServer.port ?? 0
   log({ kind: 'daemon-http-listening', host: httpHostname, port: httpPort })
 
+  // GC tick distinguishes "container confirmed gone" from "docker call failed":
+  // a `docker ps` blip should not deregister a live container registration, so
+  // we require gcMissesToDeregister consecutive confirmed absences. Boot-time
+  // restore reuses the same probe but with a stricter policy — see
+  // restorePersistedRegistrations.
+  const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
+    try {
+      const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
+      if (result.exitCode !== 0) return 'unknown'
+      const names = result.stdout
+        .trim()
+        .split('\n')
+        .filter((s) => s.length > 0)
+      return names.includes(name) ? 'alive' : 'gone'
+    } catch {
+      return 'unknown'
+    }
+  }
+
   // Boot-time restore: replay every persisted registration into the in-memory
   // maps and revive portbroker for it. Runs before Bun.listen so the socket
   // is never accepting RPCs against a half-restored registry. A bad file
   // (parse error, schema mismatch) is logged-and-skipped — one corrupt
   // registration must not gate every other container's recovery.
-  await restorePersistedRegistrations(applyRegistration, log)
+  await restorePersistedRegistrations(applyRegistration, log, probeContainerAlive, removeRegistrationFile)
 
   const listener: UnixSocketListener<ServerState> = Bun.listen<ServerState>({
     unix: path,
@@ -550,23 +587,6 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
   await chmod(path, 0o600).catch(() => {})
   log({ kind: 'daemon-listening', socket: path })
 
-  // GC tick distinguishes "container confirmed gone" from "docker call failed":
-  // a `docker ps` blip should not deregister a live container registration, so
-  // we require gcMissesToDeregister consecutive confirmed absences.
-  const probeContainerAlive = async (name: string): Promise<'alive' | 'gone' | 'unknown'> => {
-    try {
-      const result = await exec(['ps', '-a', '--filter', `name=^${name}$`, '--format', '{{.Names}}'])
-      if (result.exitCode !== 0) return 'unknown'
-      const names = result.stdout
-        .trim()
-        .split('\n')
-        .filter((s) => s.length > 0)
-      return names.includes(name) ? 'alive' : 'gone'
-    } catch {
-      return 'unknown'
-    }
-  }
-
   const runGc = async (): Promise<void> => {
     for (const name of Array.from(cwds.keys())) {
       const status = await probeContainerAlive(name)

package/src/hostd/portbroker-manager.ts

@@ -26,15 +26,31 @@ export function createPortbrokerManager(opts: PortbrokerManagerOptions = {}): Po
   const brokerFactory = opts.createBrokerFor ?? createBroker
 
   return {
-    start(input: PortbrokerStartInput) {
+    // start() awaits the previous broker's stop before constructing the new
+    // one. The fire-and-forget shape this replaced let a stale T_old broker
+    // win the race to send broker-hello against a brand-new container that
+    // expects T_new, producing a one-shot `auth-failed: token mismatch`
+    // broadcast at every re-register that arrived while the old broker was
+    // still mid-stop. The race window was narrow but reproducible across
+    // hostd-respawn-after-ungraceful-death + typeclaw restart, because the
+    // restored T_old broker is alive for the duration of the register RPC.
+    // Awaiting collapses the window to zero — by the time the T_new broker's
+    // first connect() fires, the T_old broker has set stopped=true, cleared
+    // its reconnect timer, and closed its WS.
+    async start(input: PortbrokerStartInput) {
       const existing = brokers.get(input.containerName)
       if (existing) {
-        void existing.stop().catch(() => {})
+        brokers.delete(input.containerName)
+        try {
+          await existing.stop()
+        } catch {}
       }
       const existingTailscale = tailscaleManagers.get(input.containerName)
       if (existingTailscale) {
         tailscaleManagers.delete(input.containerName)
-        void existingTailscale.stopAll().catch(() => {})
+        try {
+          await existingTailscale.stopAll()
+        } catch {}
       }
       const tailscale = createTailscaleServeManager({
         containerName: input.containerName,

package/src/init/dockerfile.ts

@@ -281,6 +281,56 @@ set -eu
 #   -nolisten tcp           refuse TCP connections (Unix socket only).
 #                           Defense-in-depth — we are in a netns with
 #                           no inbound exposure anyway.
+# link_persistent_home_files symlinks credential files that tools write
+# to $HOME into a bind-mounted location so they survive container
+# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
+# rewrites the file in place to rotate OAuth tokens, and the official
+# CI/CD guidance is to persist auth.json so refresh-token state
+# compounds across runs. The container's $HOME (/root by default) lives
+# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
+# cycle, so without this symlink the operator would have to re-paste
+# auth.json after every restart.
+#
+# The persist root lives under /agent/.typeclaw/home/ (bind-mounted
+# from the agent folder via the -v <cwd>:/agent flag in start.ts).
+# Namespacing under .typeclaw/ keeps the agent's top-level layout clean and reserves
+# a system-owned subtree we can extend later (e.g. ~/.gemini/,
+# ~/.config/<tool>/) without colliding with user files. The directory
+# is gitignored by buildGitignore() so credentials never enter history.
+#
+# Three invariants this function enforces:
+#
+# 1. Symlink is unconditional and idempotent. We never check whether
+#    auth.json exists before linking — \`ln -sfn\` creates a dangling
+#    symlink on first boot, and the first \`codex login\` write goes
+#    through it to land at the persistent location. -f replaces an
+#    existing symlink; -n stops ln from dereferencing into a directory
+#    if a previous container life happened to write a real ~/.codex/
+#    dir before this code shipped.
+#
+# 2. We symlink the FILE, not the directory. Codex writes other state
+#    to ~/.codex/ over time (history.jsonl, log/, config.toml). Linking
+#    only auth.json keeps the persistence scope tight to credentials;
+#    history/logs stay ephemeral by design. Future credentials get
+#    added file-by-file here, not by widening to a directory link.
+#
+# 3. We mkdir -p the target's parent on every boot. /agent is bind-
+#    mounted, so the host-side path may exist or not depending on
+#    whether the operator ever started the container before this code
+#    shipped. mkdir -p is idempotent and cheap.
+#
+# 4. The root is overridable via TYPECLAW_PERSIST_HOME_ROOT, which only
+#    the shim's executable tests set. Production never sets it, so the
+#    in-container path is always /agent/.typeclaw/home/. The override
+#    lets the shim's behavioral tests verify symlink semantics against
+#    a real tmpdir on the host without touching /agent (which doesn't
+#    exist on developer machines and CI runners).
+link_persistent_home_files() {
+  persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
+  mkdir -p "$persist_root/.codex" "$HOME/.codex"
+  ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+}
+
 start_xvfb() {
   if ! command -v Xvfb >/dev/null 2>&1; then
     return 0
@@ -314,6 +364,7 @@ start_xvfb() {
 }
 
 if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
+  link_persistent_home_files
   start_xvfb
   exec bun run typeclaw "$@"
 fi
@@ -359,6 +410,7 @@ ip6tables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
 ip6tables -A OUTPUT -o lo -j ACCEPT
 ${ipv6Rules.join('\n')}
 
+link_persistent_home_files
 start_xvfb
 exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
 `

package/src/init/gitignore.ts

@@ -17,10 +17,18 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 # 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.
+#
+# .typeclaw/home/ is the persistent-$HOME overlay populated by the
+# entrypoint shim's \`link_persistent_home_files\` (see
+# src/init/dockerfile.ts). It mirrors selected files from the container's
+# $HOME (e.g. ~/.codex/auth.json) into the bind-mounted agent folder so
+# tool credentials survive container restarts. Always credentials; never
+# commit.
 .env
 .env.local
 secrets.json
 auth.json
+.typeclaw/home/
 node_modules/
 packages/*/node_modules/
 workspace/

package/src/inspect/index.ts

@@ -16,6 +16,8 @@ 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 type RunInspectOptions = {
   agentDir: string
@@ -29,6 +31,10 @@ export type RunInspectOptions = {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
+  // Aborting escSignal (and only escSignal) returns escToPicker=true so a
+  // caller-side loop can re-open the picker; signal still means process exit.
+  escSignal?: AbortSignal
+  liveHint?: string
 }
 
 export type SelectSession = (sessions: SessionSummary[]) => Promise<SessionSummary | null>
@@ -40,7 +46,9 @@ export type LiveSourceFactory = (opts: {
   onSubscribed?: (sessionLive: boolean) => void
 }) => AsyncIterable<InspectEvent>
 
-export type RunInspectResult = { ok: true; exitCode: 0 } | { ok: false; exitCode: number; reason: string }
+export type RunInspectResult =
+  | { ok: true; exitCode: 0; escToPicker?: boolean }
+  | { ok: false; exitCode: number; reason: string }
 
 export async function runInspect(opts: RunInspectOptions): Promise<RunInspectResult> {
   const filterResult = parseFilter(opts.filter)
@@ -59,7 +67,7 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
   const summary = await chooseSession(opts, sessionsDir, sinceMs)
   if (!summary.ok) return summary
 
-  await streamSession({
+  const streamResult = await streamSession({
     summary: summary.summary,
     filter,
     sinceMs,
@@ -69,7 +77,10 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
     stderr: opts.stderr,
     ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
     ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    ...(opts.escSignal !== undefined ? { escSignal: opts.escSignal } : {}),
+    ...(opts.liveHint !== undefined ? { liveHint: opts.liveHint } : {}),
   })
+  if (streamResult.escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
   return { ok: true, exitCode: 0 }
 }
 
@@ -132,7 +143,9 @@ async function streamSession(opts: {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
-}): Promise<void> {
+  escSignal?: AbortSignal
+  liveHint?: string
+}): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
   const emit = (event: InspectEvent): void => {
     if (opts.sinceMs !== undefined && event.ts > 0 && event.ts < opts.sinceMs) return
@@ -144,20 +157,26 @@ async function streamSession(opts: {
     }
   }
 
+  const escAborted = (): boolean => opts.escSignal?.aborted === true
+
   for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
+    if (escAborted()) return { escToPicker: true }
     emit(event)
   }
 
   if (opts.liveSource === undefined) {
     if (!opts.json) opts.stdout('─── end of transcript ───')
-    return
+    return { escToPicker: escAborted() }
   }
 
+  if (escAborted()) return { escToPicker: true }
+
+  const combinedSignal = combineSignals(opts.signal, opts.escSignal)
   let sessionLive = false
   const liveIter = opts.liveSource({
     sessionId: opts.summary.sessionId,
     ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
-    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    ...(combinedSignal !== undefined ? { signal: combinedSignal } : {}),
     onSubscribed: (live) => {
       sessionLive = live
     },
@@ -170,6 +189,9 @@ async function streamSession(opts: {
         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))
+        }
         liveAnnounced = true
       }
       emit(event)
@@ -178,6 +200,21 @@ async function streamSession(opts: {
     opts.stderr(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
   }
   if (!opts.json) opts.stdout('─── end of transcript ───')
+  return { escToPicker: escAborted() && opts.signal?.aborted !== true }
+}
+
+function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
+  if (a === undefined) return b
+  if (b === undefined) return a
+  if (a.aborted) return a
+  if (b.aborted) return b
+  const ctrl = new AbortController()
+  const onAbort = (): void => {
+    ctrl.abort()
+  }
+  a.addEventListener('abort', onAbort, { once: true })
+  b.addEventListener('abort', onAbort, { once: true })
+  return ctrl.signal
 }
 
 function divider(color: boolean, text: string): string {

package/src/inspect/loop.ts

@@ -0,0 +1,20 @@
+import { runInspect, type RunInspectOptions, type RunInspectResult } from './index'
+
+export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
+  newEscSignal: () => AbortSignal
+}
+
+export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
+  let sessionArg = opts.sessionIdOrPrefix
+  while (true) {
+    const escSignal = opts.newEscSignal()
+    const callOpts: RunInspectOptions = { ...opts, escSignal }
+    if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
+    else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
+
+    const result = await runInspect(callOpts)
+    if (!result.ok) return result
+    if (result.escToPicker !== true) return result
+    sessionArg = undefined
+  }
+}