typeclaw 0.9.1 → 0.10.0

package/src/channels/router.ts

@@ -11,6 +11,7 @@ import { createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
+import type { Stream } from '@/stream'
 
 import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
 import {
@@ -28,7 +29,11 @@ import {
   saveChannelSessions,
   type ChannelSessionRecord,
 } from './persistence'
-import type { ChannelAdapterConfig } from './schema'
+import {
+  DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS,
+  QUOTED_REPLY_EXCERPT_MAX_CHARS,
+  type ChannelAdapterConfig,
+} from './schema'
 import type {
   ChannelHistoryMessage,
   ChannelKey,
@@ -301,6 +306,15 @@ type LiveSession = {
   // future hard cap without picking a threshold out of thin air.
   sendTimestamps: Map<string, number[]>
   successfulChannelSends: number
+  // Captured by drain() at batch dequeue; read+cleared by send() on the
+  // first tool-source send of the turn. The anchor decision (delay
+  // threshold + intervening-observed check) is evaluated at SEND time
+  // against this snapshot — not at drain time — because the relevant
+  // signal is how long the user waited from inbound to seeing the reply
+  // land, which only the send-side clock knows. Cleared after first
+  // consumption so multi-part replies anchor only on chunk 1. A new
+  // batch overwrites unconditionally.
+  pendingQuoteCandidate: QuoteAnchorCandidate | null
   // Loop-guard state. See PEER_BOT_TURNS_WINDOW_MS / MAX_* constants
   // above. Updated in route() on every engaged peer-bot inbound, reset on
   // any human inbound. The two axes (window ring buffer + since-human
@@ -505,6 +519,14 @@ export type CreateChannelRouterOptions = {
   // back over the same chat, or null to fall through to normal routing
   // when no pending claim window matches.
   claimHandler?: ClaimHandler
+  // Optional in-process Stream. When set, every inbound the router sees
+  // is published as a tagged broadcast (`kind: 'channel-inbound'`) so the
+  // `/inspect` WS endpoint can surface it live and `stream.scan()` can
+  // backfill it on subscribe. Decoupled from the routing decision: even
+  // permission-denied and role-claim inbounds publish, so the operator
+  // can diagnose silent drops from `typeclaw inspect` alone. Omitted in
+  // tests that don't care about inspect surfacing.
+  stream?: Stream
 }
 
 export type ClaimHandlerInput = {
@@ -539,6 +561,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS
   const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
   const claimHandler = options.claimHandler
+  const stream = options.stream
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
@@ -713,7 +736,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const existing = liveSessions.get(keyId)
     if (existing && !existing.destroyed) {
       const idleMs = now() - existing.lastInboundAt
-      if (idleMs > SESSION_FRESHNESS_TTL_MS) {
+      // `lastInboundAt` is only bumped on engaged inbounds (see route()),
+      // so a session whose drain loop has been compiling a slow reply for
+      // 5+ minutes off a single inbound looks "idle" by this clock even
+      // though `session.prompt()` is mid-flight. Aborting that prompt to
+      // re-cold-start on the next user message wipes the in-flight work
+      // (observed against `openai-codex/gpt-5.5` in PR #359's incident:
+      // a 285s + 227s turn pair lost the second turn entirely to
+      // `tearDownLive` → `session.abort()` triggered by the user's
+      // follow-up at 5min idle). The `runIdleGc` path already skips
+      // draining sessions for the same reason; rollover must match.
+      // The skip is bounded: when the in-flight prompt completes or its
+      // own provider/transport timeout fires, `draining` clears and the
+      // next inbound's idle check picks up rollover normally.
+      if (idleMs > SESSION_FRESHNESS_TTL_MS && !existing.draining) {
         logger.info(`[channels] ${keyId}: stale-rollover (live: ${idleMs}ms idle)`)
         await tearDownLive(existing)
         liveSessions.delete(keyId)
@@ -890,6 +926,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         lastSentText: new Map(),
         sendTimestamps: new Map(),
         successfulChannelSends: 0,
+        pendingQuoteCandidate: null,
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
@@ -1190,6 +1227,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
           live.consecutiveSends.clear()
           live.lastSentText.clear()
+          live.pendingQuoteCandidate = captureQuoteCandidate(batch, observed)
         } else if (live.lastTurnAuthorId !== null) {
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
           // restore the author identity from the prior turn so author-
@@ -1277,6 +1315,33 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }, wait)
   }
 
+  const publishInbound = (event: InboundMessage, decision: 'engage' | 'observe' | 'denied' | 'claim'): void => {
+    if (stream === undefined) return
+    try {
+      stream.publish({
+        target: { kind: 'broadcast' },
+        payload: {
+          kind: 'channel-inbound',
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          authorId: event.authorId,
+          authorName: event.authorName,
+          authorIsBot: event.authorIsBot,
+          isDm: event.isDm,
+          isBotMention: event.isBotMention,
+          text: event.text,
+          externalMessageId: event.externalMessageId,
+          ts: event.ts,
+          decision,
+        },
+      })
+    } catch (err) {
+      logger.warn(`[channels] inbound stream publish failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   const route = async (event: InboundMessage): Promise<void> => {
     const adapterConfig = options.configForAdapter(event.adapter)
     if (!adapterConfig) return
@@ -1290,10 +1355,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     // Role-claim intercept runs BEFORE the channel.respond gate so the
     // operator can bootstrap permissions on a fresh agent that has no
-    // role match rules yet. Cheap pre-check: only DMs whose text contains
-    // a `claim-` prefix can be claim attempts, and only when a handler
+    // role match rules yet. Cheap pre-check: any inbound whose text
+    // contains a `claim-` prefix is a candidate, and only when a handler
     // is registered. Everything else falls straight through to the gate.
-    if (claimHandler !== undefined && event.isDm && extractClaimCode(event.text) !== null) {
+    // Claims are accepted from any chat (DM, group, thread) because the
+    // resulting match rule is platform-wide + author-scoped — see
+    // src/role-claim/match-rule.ts.
+    if (claimHandler !== undefined && extractClaimCode(event.text) !== null) {
       const outcome = await claimHandler({
         adapter: event.adapter,
         workspace: event.workspace,
@@ -1303,6 +1371,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         text: event.text,
       })
       if (outcome.kind !== 'fallthrough') {
+        publishInbound(event, 'claim')
         logger.info(
           `[channels] ${channelKeyId(key)}: claim ${outcome.kind} author=${event.authorId} id=${event.externalMessageId}`,
         )
@@ -1321,6 +1390,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
 
     if (isChannelRespondDenied(event)) {
+      publishInbound(event, 'denied')
       logger.info(
         `[channels] ${channelKeyId(key)}: denied by permissions (channel.respond) author=${event.authorId} id=${event.externalMessageId}`,
       )
@@ -1388,6 +1458,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     })
 
     if (decision === 'observe') {
+      publishInbound(event, 'observe')
       // Log every observe so an unanswered mention is diagnosable from logs
       // alone instead of "routed but no prompting" silence. The bracketed
       // shape mirrors `prompting batch=` so log scraping can pair them.
@@ -1396,6 +1467,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    publishInbound(event, 'engage')
+
     updateLoopGuard(live, event)
 
     enqueue(live, event)
@@ -1637,6 +1710,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     })
     const live = liveSessions.get(keyId)
     const sendKey = consecutiveSendKey(msg.chat, msg.thread)
+    // Tool-source sends consume the captured quote candidate exactly
+    // once per turn — the decision (delay threshold + intervening-
+    // observed check) runs HERE against the live clock so the relevant
+    // signal is real wall-time between inbound and reply landing, not
+    // drain-vs-send timing artifacts. System sources (recovery, role-
+    // claim) skip so they can't accidentally swallow the candidate
+    // before the model's own first reply lands. Even when the decision
+    // returns null (delay below threshold, nothing intervened), the
+    // candidate is cleared — a multi-part reply that crosses the
+    // threshold mid-flight must not retroactively anchor chunk 2.
+    if (live && source === 'tool' && live.pendingQuoteCandidate !== null) {
+      const anchor = decideQuoteAnchor(live.pendingQuoteCandidate, now(), options.configForAdapter(msg.adapter))
+      if (anchor !== null) msg = { ...msg, text: prependQuoteAnchor(msg.text ?? '', anchor) }
+      live.pendingQuoteCandidate = null
+    }
     const text = normalizeSendText(msg.text)
 
     // Central enforcement. Tool-initiated sends are subject to two policies:
@@ -1739,8 +1827,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
-    const assistantText = latestAssistantText(live.session)
-    if (assistantText === null) return
+    const candidate = recoverableAssistantText(live.session)
+    if (candidate === null) {
+      // Observability: previously a silent bail-out. The most common cause is a
+      // turn that ends mid-loop with NO assistant message at all (leaf is a
+      // session header / model_change / similar non-message entry, or a session
+      // that just started). Logged at debug-level info so operators can grep for
+      // unexpected silent turns; not warn-level because legitimate empty-state
+      // sessions hit this on every TUI-only check before the first user prompt.
+      logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+      return
+    }
+
+    const { text: assistantText, source } = candidate
 
     if (endsWithNoReplySignal(assistantText)) {
       const leakedReasoning = !isNoReplySignal(assistantText)
@@ -1760,8 +1859,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    // `source` distinguishes the two recovery shapes for log triage:
+    //   - 'leaf': the assistant message IS the leaf (existing behavior; model
+    //     ended its turn with text but forgot to call channel_reply).
+    //   - 'pre-tool': the leaf is a toolResult (or other non-assistant entry)
+    //     and the assistant message lives upstream in the branch. This is the
+    //     Kimi-on-Fireworks `kimi-k2p6-turbo` failure mode where the post-tool
+    //     follow-up LLM call never produced a persisted assistant message, so
+    //     the model's pre-tool commentary is the only user-facing text we have.
+    //     Recovering it means the user gets *something* — strictly better than
+    //     the historical silent drop.
     logger.warn(
-      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
+      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool source=${source} text_len=${assistantText.length}`,
     )
     const result = await send(
       {
@@ -2153,6 +2262,95 @@ function formatAuthorLine(
   return `${stamp}<@${authorId}> (${authorName})${tag}: ${text}`
 }
 
+export type QuoteAnchorSource = {
+  authorName: string
+  text: string
+}
+
+// Renders the single-line `> @name: excerpt` blockquote prepended to
+// outbound replies when the router decides the reply needs an anchor.
+// Collapses newlines to spaces so a multi-line user message renders on
+// one quoted line (markdown blockquote semantics: a blank line ends the
+// quote, and `> foo\nbar` would split the quote and the reply); strips
+// existing leading `>` so a quote-of-a-quote stays single-level. Empty
+// inbound text (mention-only inbounds like `<@bot>`) falls back to a
+// generic marker so the user still sees "the bot saw your ping".
+export function renderQuoteAnchor(source: QuoteAnchorSource): string {
+  const collapsed = source.text
+    .replace(/\s+/g, ' ')
+    .replace(/^>+\s*/, '')
+    .trim()
+  const excerpt =
+    collapsed === ''
+      ? '(no text)'
+      : collapsed.length > QUOTED_REPLY_EXCERPT_MAX_CHARS
+        ? `${collapsed.slice(0, QUOTED_REPLY_EXCERPT_MAX_CHARS - 1)}…`
+        : collapsed
+  return `> @${source.authorName}: ${excerpt}`
+}
+
+export function prependQuoteAnchor(replyText: string, source: QuoteAnchorSource): string {
+  const anchor = renderQuoteAnchor(source)
+  if (replyText === '') return anchor
+  return `${anchor}\n${replyText}`
+}
+
+type QuoteAnchorBatchEntry = {
+  text: string
+  authorName: string
+  authorIsBot: boolean
+  receivedAt: number
+}
+
+type QuoteAnchorObservedEntry = {
+  receivedAt: number
+}
+
+export type QuoteAnchorCandidate = {
+  source: QuoteAnchorSource
+  primaryReceivedAt: number
+  hadInterveningObserved: boolean
+}
+
+// Snapshot the primary inbound + observed-buffer state at drain time so
+// the send-side decision has the data it needs without holding a
+// reference to the batch arrays. Returns null when there's nothing
+// anchorable (empty batch, primary is a bot).
+export function captureQuoteCandidate(
+  batch: readonly QuoteAnchorBatchEntry[],
+  observed: readonly QuoteAnchorObservedEntry[],
+): QuoteAnchorCandidate | null {
+  if (batch.length === 0) return null
+  const primary = batch[batch.length - 1]!
+  if (primary.authorIsBot) return null
+  const hadInterveningObserved = observed.some((o) => o.receivedAt >= primary.receivedAt)
+  return {
+    source: { authorName: primary.authorName, text: primary.text },
+    primaryReceivedAt: primary.receivedAt,
+    hadInterveningObserved,
+  }
+}
+
+// Send-time decision: given a captured candidate and the current clock,
+// returns the source to anchor against or null. Skips when:
+//   - quotedReply is disabled in config
+//   - delay is under threshold AND no observed messages came between
+//     primary inbound and now (the "felt instantaneous" path)
+// A null candidate (no batch yet, or batch was bot-only) always skips.
+export function decideQuoteAnchor(
+  candidate: QuoteAnchorCandidate | null,
+  nowMs: number,
+  adapterConfig: ChannelAdapterConfig | undefined,
+): QuoteAnchorSource | null {
+  if (candidate === null) return null
+  const config = adapterConfig?.quotedReply
+  if (config !== undefined && config.enabled === false) return null
+  const threshold = config?.queueDelayMs ?? DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS
+  const delay = nowMs - candidate.primaryReceivedAt
+  if (delay < threshold && !candidate.hadInterveningObserved) return null
+  return candidate.source
+}
+
 type Sliced = { kind: 'message'; message: ChannelHistoryMessage } | { kind: 'elision'; elidedCount: number }
 
 export function sliceHeadTail(messages: readonly ChannelHistoryMessage[], head: number, tail: number): Sliced[] {
@@ -2306,12 +2504,67 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
   }
 }
 
-function latestAssistantText(session: AgentSession): string | null {
-  const entry = session.sessionManager.getLeafEntry()
-  if (entry?.type !== 'message') return null
-  if (entry.message.role !== 'assistant') return null
-  if (entry.message.stopReason !== 'stop') return null
-  return visibleAssistantText(entry.message)
+// Walks the session branch backward from the leaf to find a recoverable
+// assistant message — i.e., text the user should see but didn't, because the
+// model failed to call `channel_reply`/`channel_send` before its turn ended.
+//
+// Two recovery shapes:
+//
+//   - source: 'leaf'
+//     The leaf entry IS an assistant message with `stopReason === 'stop'`.
+//     The model finished its turn with visible text but never called a channel
+//     tool. Pre-existing behavior; this is what the historical
+//     `latestAssistantText` covered.
+//
+//   - source: 'pre-tool'
+//     The leaf is a `toolResult` and the immediately-prior assistant message
+//     has `stopReason === 'toolUse'` (it called the tool that produced this
+//     toolResult). The upstream pi-agent-core loop SHOULD have made a
+//     follow-up LLM call after the tool returned, but that call either never
+//     happened or produced no persisted message. Recovers the assistant's
+//     pre-tool commentary so the user gets *something* — observed against
+//     Fireworks' `accounts/fireworks/routers/kimi-k2p6-turbo` on 2026-05-26.
+//
+// Returns null when no recovery is appropriate:
+//   - No leaf, no messages in branch, branch is malformed
+//   - Leaf is an assistant with non-'stop' stopReason (e.g. mid-stream error)
+//     and is NOT preceded by a toolResult pattern — we don't recover partial
+//     errored output because it's typically a truncation, not a deliberate
+//     reply
+//   - Leaf is a user/system message (model hasn't responded yet)
+//
+// `visibleAssistantText` returning '' (empty string) is a valid recovery
+// target — the caller's downstream guards (`endsWithNoReplySignal('')` returns
+// true) handle the no-content case explicitly via the `no_reply` log.
+function recoverableAssistantText(session: AgentSession): { text: string; source: 'leaf' | 'pre-tool' } | null {
+  const leaf = session.sessionManager.getLeafEntry()
+  if (!leaf) return null
+
+  if (leaf.type === 'message' && leaf.message.role === 'assistant') {
+    if (leaf.message.stopReason !== 'stop') return null
+    return { text: visibleAssistantText(leaf.message), source: 'leaf' }
+  }
+
+  // Pre-tool recovery: the leaf must be a toolResult message, and walking
+  // back through parentId chain must land on an assistant message before any
+  // user message (otherwise we'd be recovering text from a turn the user
+  // already saw a reply to). Bounded walk with a depth guard so a malformed
+  // session can't infinite-loop.
+  if (!(leaf.type === 'message' && leaf.message.role === 'toolResult')) return null
+
+  let cursor: { parentId: string | null } | undefined = leaf
+  for (let depth = 0; depth < 32 && cursor?.parentId; depth++) {
+    const parent = session.sessionManager.getEntry(cursor.parentId)
+    if (!parent) return null
+    if (parent.type === 'message') {
+      if (parent.message.role === 'assistant') {
+        return { text: visibleAssistantText(parent.message), source: 'pre-tool' }
+      }
+      if (parent.message.role === 'user') return null
+    }
+    cursor = parent
+  }
+  return null
 }
 
 function visibleAssistantText(message: AssistantMessage): string {

package/src/channels/schema.ts

@@ -19,7 +19,7 @@ const stickinessSchema = z.union([
   }),
 ])
 
-export const STICKY_DEFAULT_WINDOW_MS = 5 * 60 * 1000
+export const STICKY_DEFAULT_WINDOW_MS = 15 * 60 * 1000
 
 const engagementSchema = z
   .object({
@@ -87,6 +87,26 @@ const historySchema = z
     },
   })
 
+// When the agent's first send of a turn lands ≥ this many ms after the
+// inbound was received, OR there were intervening observed messages
+// between the inbound and the reply, the router prepends a `> @author:
+// ...` blockquote line referencing the inbound so the user can see which
+// message the reply is anchored to even after the channel has scrolled.
+// 10s is the empirical "felt instantaneous" ceiling — anything faster
+// reads as real-time and needs no anchor.
+export const DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS = 10_000
+
+// Long enough to disambiguate; short enough that a multi-paragraph user
+// message doesn't visually dominate the reply.
+export const QUOTED_REPLY_EXCERPT_MAX_CHARS = 100
+
+const quotedReplySchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    queueDelayMs: z.number().int().min(0).default(DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS),
+  })
+  .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
@@ -97,6 +117,7 @@ const adapterSchema = z.object({
   engagement: engagementSchema,
   history: historySchema,
   enabled: z.boolean().default(true),
+  quotedReply: quotedReplySchema.optional(),
 })
 
 export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [

package/src/cli/compose.ts

@@ -12,11 +12,12 @@ import {
   type ComposeDoctorReport,
 } from '@/compose'
 import { config } from '@/config'
+import { parseTailValue } from '@/container'
 import { formatJson, formatReport } from '@/doctor'
 
 import { formatComposeStatus } from './compose-status'
 import { formatComposeUsage, formatComposeUsageJson } from './compose-usage'
-import { c, spinner } from './ui'
+import { c, errorLine, spinner } from './ui'
 import { parseSince, parseUntil } from './usage-args'
 
 const startSub = defineCommand({
@@ -144,8 +145,23 @@ const logsSub = defineCommand({
       description: 'stream new log output as it arrives',
       default: false,
     },
+    tail: {
+      type: 'string',
+      alias: 'n',
+      description: 'number of lines to show from the end of each agent\'s logs (non-negative integer or "all")',
+    },
   },
   async run({ args }) {
+    let tail: string | undefined
+    if (args.tail !== undefined) {
+      const parsed = parseTailValue(args.tail)
+      if (!parsed.ok) {
+        console.error(errorLine(parsed.reason))
+        process.exit(2)
+      }
+      tail = parsed.value
+    }
+
     const controller = new AbortController()
     const onSig = (): void => controller.abort()
     process.once('SIGINT', onSig)
@@ -156,7 +172,12 @@ const logsSub = defineCommand({
       } else {
         console.log(c.dim('Showing logs for all agents.'))
       }
-      const result = await composeLogs({ rootCwd: process.cwd(), follow: args.follow, signal: controller.signal })
+      const result = await composeLogs({
+        rootCwd: process.cwd(),
+        follow: args.follow,
+        tail,
+        signal: controller.signal,
+      })
       if (result.agents.length === 0) {
         console.log(c.dim('No typeclaw agents found in immediate subdirectories of cwd.'))
         return

package/src/cli/cron.ts

@@ -38,7 +38,7 @@ const listSub = defineCommand({
     }
 
     let url: string | undefined = args.url
-    if (url === undefined) {
+    if (url === undefined && process.env.TYPECLAW_CONTAINER_NAME === undefined) {
       const precheck = await requireContainerRunning({ cwd })
       if (!precheck.ok) {
         console.error(errorLine(precheck.reason))

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