typeclaw 0.22.0 → 0.24.0

package/src/channels/schema.ts

@@ -131,11 +131,26 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request_review.submitted',
 ] as const
 
+// Which pull_request webhook action triggers an agent code review. The two
+// event values are GitHub's bare PR action names (the `pull_request.` event
+// prefix is implied by this field living under the review config); `off` is the
+// disable sentinel, matching the `engagement.stickiness: 'off'` convention:
+//   - 'review_requested' — review only when the bot is requested (default)
+//   - 'opened'           — review every PR as soon as it opens
+//   - 'off'              — disable code review entirely
+export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
+
+export type GithubReviewOn = (typeof GITHUB_REVIEW_ON_VALUES)[number]
+
+export const DEFAULT_GITHUB_REVIEW_ON: GithubReviewOn = 'review_requested'
+
 // PR-review policy knobs. Grouped under `review` so future toggles
-// (`requestChanges`, auto-review-on-request, severity thresholds) cluster
-// here instead of flattening onto the channel root.
+// (`requestChanges`, severity thresholds) cluster here instead of flattening
+// onto the channel root.
+//
+// `on` gates which pull_request action triggers a code review (see values above).
 //
-// `approve` gates whether the agent may submit a formal review with
+// `approve` gates *whether* the agent may submit a formal review with
 // `event: APPROVE`. When `false`, the adapter appends an operator-policy note
 // to inbounds and the `typeclaw-channel-github` skill downgrades an `approve`
 // verdict to a `COMMENT` review (findings still posted, no formal approval).
@@ -144,9 +159,10 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
 // temp file the command interceptor never sees.
 const githubReviewSchema = z
   .object({
+    on: z.enum(GITHUB_REVIEW_ON_VALUES).default(DEFAULT_GITHUB_REVIEW_ON),
     approve: z.boolean().default(true),
   })
-  .default({ approve: true })
+  .default({ on: DEFAULT_GITHUB_REVIEW_ON, approve: true })
 
 const githubChannelSchema = adapterSchema.extend({
   // Optional now (PR 2): when omitted and a `tunnels[]` entry with

package/src/channels/types.ts

@@ -52,6 +52,9 @@ export type InboundMessage = {
   chat: string
   thread: string | null
   text: string
+  // Prompt-only context for replied-to / quoted / linked messages. Kept out
+  // of `text` so the engagement gate sees only the human-authored body.
+  referenceContext?: InboundReferenceContext
   // Non-text attachments the user sent on this inbound. Empty / omitted
   // when the message is text-only. The router carries these through to
   // the live session's promptQueue/contextBuffer so channel tools can
@@ -94,6 +97,15 @@ export type InboundMessage = {
   // means "unknown" — the formatter renders such lines without a
   // timestamp prefix instead of stamping them with the wrong clock.
   ts: number
+  // Platform-native anchor for showing a typing/status indicator, kept
+  // SEPARATE from `thread` on purpose: `thread` drives reply threading,
+  // this drives ONLY the typing surface. Slack's `assistant.threads.
+  // setStatus` (the bot's only typing signal) requires a real message ts
+  // even in a flat DM, where `thread` is null because replies stay top-
+  // level. The classifier sets this to the inbound message ts for DMs so
+  // the status can render without forcing the reply into a thread. Omitted
+  // for non-DM inbounds, where the typing path falls back to `thread`.
+  typingThread?: string
   // Opaque, adapter-owned handle for the entity an emoji reaction would
   // attach to. The classifier stamps it because only there is the platform-
   // side target type still known (GitHub: issue body vs issue-comment vs
@@ -183,6 +195,10 @@ export type OutboundMessage = {
   // `uploadFile` does not accept a content body or a thread id, see the
   // adapter for the workaround details.
   attachments?: OutboundAttachment[]
+  // Typing-only anchor (see InboundMessage.typingThread), stamped by the
+  // router from the live session so the adapter can CLEAR the status after a
+  // flat DM send — where `thread` is null and would otherwise no-op the clear.
+  typingThread?: string
   // Set by the router (native render mode + anchor fired) so an adapter can
   // reply to the inbound it answers. Telegram/Discord consume `externalMessageId`;
   // `quote`-mode adapters never see this (the router prepends the blockquote into
@@ -207,6 +223,11 @@ export type QuoteAnchorSource = {
   text: string
 }
 
+export type InboundReferenceContext = {
+  kind: 'reply' | 'quote' | 'link'
+  sources: readonly QuoteAnchorSource[]
+}
+
 export type SendErrorCode =
   | 'duplicate'
   | 'turn-cap'
@@ -224,6 +245,10 @@ export type TypingTarget = {
   workspace: string
   chat: string
   thread?: string | null
+  // Typing-only anchor (see InboundMessage.typingThread). An adapter whose
+  // typing surface needs a message ts even when `thread` is null (Slack DMs)
+  // reads this first and falls back to `thread`. Never used for reply routing.
+  typingThread?: string
   // 'tick' is the heartbeat fired during debouncing/generation; adapters
   // should set the indicator visible. 'stop' is fired exactly once when the
   // router decides the turn is over (drain finally, /stop command, or
@@ -243,6 +268,33 @@ export type ResolvedChannelNames = {
 
 export type ChannelNameResolver = (key: ChannelKey) => Promise<ResolvedChannelNames>
 
+// The bot's OWN identity on a platform, surfaced into the channel system
+// prompt so the model recognizes mentions of itself. The engagement gate
+// already knows this id (it sets `isBotMention`), but the model only knows
+// its NAME (from identity files) — not its platform user id. Without this,
+// a message addressed to `<@U0ABFG8TYN7>` (the bot's own Slack id) reads to
+// the model as "addressed to someone else" and it skips a turn it was
+// correctly engaged for.
+//
+// - `id` is the raw platform user id (Slack `U…`, Discord snowflake,
+//   Telegram numeric id as string, GitHub numeric id as string). For
+//   angle-id platforms this is what appears inside `<@…>`.
+// - `username` is the human-typed handle used for at-mentions on platforms
+//   where the id is NOT what gets typed (Telegram `@username`, GitHub
+//   `@login`). Omitted when the platform mentions by id, or when the
+//   account simply has no username.
+export type ChannelSelfIdentity = {
+  id: string
+  username?: string
+}
+
+// Resolves the bot's own identity for a given workspace. `workspace` is
+// passed because identity is conceptually per-workspace (Slack team); most
+// adapters serve a single identity and ignore the argument. Returns null
+// when identity is not yet resolved (startup race) or unknown — callers
+// MUST treat null as "omit the self-mention prompt line", never as an error.
+export type ChannelSelfIdentityResolver = (workspace: string) => ChannelSelfIdentity | null
+
 // History entries are intentionally distinct from InboundMessage:
 // `InboundMessage` carries router-classification fields (`isBotMention`,
 // `isDm`) that are turn-delivery concerns, not history concerns. History
@@ -253,6 +305,7 @@ export type ChannelHistoryMessage = {
   authorId: string
   authorName: string
   text: string
+  referenceContext?: InboundReferenceContext
   attachments?: readonly InboundAttachment[]
   ts: number
   isBot: boolean
@@ -287,6 +340,48 @@ export type FetchAttachmentResult =
 
 export type FetchAttachmentCallback = (args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
 
+// A request to resolve (close out) a review-comment thread the bot itself
+// opened, after the author addressed it. Adapter-specific: only the github
+// adapter registers a resolver today. The router carries the request through
+// to that resolver, which is responsible for the platform-side authorship
+// check — `resolveReviewThread` MUST only close a thread whose root comment
+// the bot authored, never a human reviewer's thread. The address fields below
+// are the same ones a `channel_reply` origin carries: `workspace` is the repo
+// slug `owner/name`, `chat` is `pr:<N>`, and `rootCommentId` is the numeric id
+// of the thread's root comment (the `thread` value the inbound carried).
+export type ReviewThreadResolveRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  rootCommentId: string
+}
+
+// `already-resolved` is a success-shaped no-op: the thread was closed before we
+// got here (a duplicate turn, a manual resolve), so the desired end state holds
+// and the caller should treat it like `ok: true`. `not-author` is a hard
+// refusal: the root comment is not the bot's, so resolving would erase a
+// human's open question — the caller must NOT proceed as if it closed the loop.
+//
+// `no-match` is the ONLY non-blocking failure: the PR's threads listed cleanly
+// but none is rooted at this comment (already deleted, or the wrong target),
+// so there is genuinely nothing to close and an acknowledgement may still post.
+// Every other code is a hard failure — `not-found` here means an HTTP 404 from
+// the API (a real problem, e.g. wrong repo/PR), NOT "no such thread"; a caller
+// must treat it as blocking so it never claims a thread is settled on a failed
+// or misdirected lookup.
+export type ReviewThreadResolveResult =
+  | { ok: true; alreadyResolved?: boolean }
+  | {
+      ok: false
+      error: string
+      code?: 'not-author' | 'no-match' | 'not-found' | 'unsupported' | 'permission-denied' | 'transient'
+    }
+
+// Registered per-adapter on the ChannelRouter, last-write-wins like the
+// self-identity resolver (one bot account per adapter). Adapters that do not
+// support review threads never register one; the router answers `unsupported`.
+export type ReviewThreadResolver = (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
+
 export function channelKeyId(key: ChannelKey): string {
   return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
 }

package/src/cli/inspect-controller.ts

@@ -14,6 +14,8 @@ export type EscController = {
   dispose: () => void
 }
 
+const QUIT_KEY = 0x71
+
 export function createEscController({ debounceMs }: { debounceMs: number }): EscController {
   let currentCtrl: AbortController | null = null
   let pendingEsc: ReturnType<typeof setTimeout> | null = null
@@ -64,3 +66,100 @@ export function createEscController({ debounceMs }: { debounceMs: number }): Esc
     },
   }
 }
+
+export type TailIntent = 'back' | 'exit'
+
+export type TailScope = {
+  signal: AbortSignal
+  // null when the tail ended on its own (stream closed / replay-only); the loop
+  // treats null the same as 'back'. The stream only ever sees signal.aborted —
+  // intent is read by the loop, keeping abort decoupled from what abort meant.
+  intent: () => TailIntent | null
+  dispose: () => void
+}
+
+type RawInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume' | 'on' | 'off'>
+
+type ProcessSignals = Pick<NodeJS.Process, 'once' | 'off'>
+
+// One disposable interaction scope per live-tail iteration. Creates a FRESH
+// AbortController, installs a temporary raw-mode 'data' listener plus
+// SIGINT/SIGTERM handlers, and tears all of it down on dispose(). This mirrors
+// the `dreams` viewer-key pattern: raw mode is scoped to a single tail attempt
+// and never survives into the clack picker, which removes the pause/resume
+// state machine that made the old inspect listener fragile.
+export function createTailScope(opts: { debounceMs: number; input?: RawInput; proc?: ProcessSignals }): TailScope {
+  const stdin = opts.input ?? process.stdin
+  const proc = opts.proc ?? process
+  const controller = new AbortController()
+  let intent: TailIntent | null = null
+  let disposed = false
+
+  const settle = (next: TailIntent): void => {
+    if (intent === null) intent = next
+    controller.abort()
+  }
+
+  const onSigExit = (): void => {
+    settle('exit')
+  }
+
+  const isTty = Boolean(stdin.isTTY) && typeof stdin.setRawMode === 'function'
+  const esc = isTty ? createEscController({ debounceMs: opts.debounceMs }) : null
+  const escSignal = esc?.armForStream()
+  // A bare ESC fires through the debounce controller, not the 'data' handler:
+  // route its abort into 'back' intent here so the loop can re-open the picker.
+  const onEscAbort = (): void => settle('back')
+
+  const onData = (chunk: Buffer): void => {
+    if (esc === null) return
+    if (chunk[0] === QUIT_KEY) {
+      // q mirrors dreams' quit key and is symmetric with Ctrl-C in live tail.
+      settle('exit')
+      return
+    }
+    const { sigint } = esc.onChunk(chunk)
+    if (sigint) settle('exit')
+  }
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    proc.off('SIGINT', onSigExit)
+    proc.off('SIGTERM', onSigExit)
+    escSignal?.removeEventListener('abort', onEscAbort)
+    if (esc !== null) {
+      stdin.off('data', onData)
+      esc.dispose()
+      try {
+        stdin.setRawMode(false)
+      } catch {
+        /* terminal already torn down */
+      }
+      // Deliberately NOT stdin.pause(): a paused process.stdin does not reliably
+      // re-flow into the next clack picker under Bun (same reason as
+      // prepareStdinForClack / dreams' waitForViewerKey). Leave it flowing.
+    }
+    // Abort last so a stream still awaiting on this signal unblocks during
+    // teardown rather than hanging.
+    controller.abort()
+  }
+
+  proc.once('SIGINT', onSigExit)
+  proc.once('SIGTERM', onSigExit)
+
+  if (esc !== null && escSignal !== undefined) {
+    escSignal.addEventListener('abort', onEscAbort, { once: true })
+    stdin.setRawMode(true)
+    // Attach the data handler before resume() so no raw-mode keystroke slips
+    // through between resuming the stream and registering the listener.
+    stdin.on('data', onData)
+    stdin.resume()
+  }
+
+  return {
+    signal: controller.signal,
+    intent: () => intent,
+    dispose,
+  }
+}

package/src/cli/inspect.ts

@@ -5,10 +5,10 @@ import { findAgentDir } from '@/init'
 import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
 import { originLabel, shortSessionId } from '@/inspect/label'
 
-import { createEscController } from './inspect-controller'
+import { createTailScope } from './inspect-controller'
 import { cancel, c, errorLine, isCancel, prepareStdinForClack } from './ui'
 
-const ESC_LISTEN_DELAY_MS = 50
+const ESC_DEBOUNCE_MS = 50
 
 export const inspectCommand = defineCommand({
   meta: {
@@ -45,46 +45,24 @@ export const inspectCommand = defineCommand({
 
     const isJson = args.json === true
     const liveSource = isJson ? undefined : await buildLiveSource(cwd)
-    const signalCtrl = installSigintAbort()
-    const signal = signalCtrl.signal
-    // Raw-mode Ctrl-C arrives as byte 0x03 and must abort the exit controller
-    // directly: under Bun a self-issued process.kill(SIGINT) does not reliably
-    // re-enter our process.once('SIGINT') handler, so the live tail never exits.
-    const escListener = isJson ? null : createEscListener(() => signalCtrl.abort())
-    const liveHint = escListener === null ? undefined : escHintLine(color)
-
-    // try/finally so a thrown loop never leaves the terminal stuck in raw mode.
-    let result: Awaited<ReturnType<typeof runInspectLoop>>
-    try {
-      result = await runInspectLoop({
-        agentDir: cwd,
-        ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
-        ...(filterArg !== undefined ? { filter: filterArg } : {}),
-        ...(sinceArg !== undefined ? { since: sinceArg } : {}),
-        json: isJson,
-        color,
-        selectSession: (sessions, selectOpts) => {
-          escListener?.pause()
-          return clackSelect(sessions, selectOpts?.initialSessionId).finally(() => {
-            escListener?.resume()
-          })
-        },
-        ...(liveSource !== undefined ? { liveSource } : {}),
-        signal,
-        newEscSignal: () => {
-          if (escListener === null) return new AbortController().signal
-          return escListener.armForStream()
-        },
-        afterEscStream: () => {
-          escListener?.pause()
-        },
-        ...(liveHint !== undefined ? { liveHint } : {}),
-        stdout: (line) => process.stdout.write(`${line}\n`),
-        stderr: (line) => process.stderr.write(`${line}\n`),
-      })
-    } finally {
-      escListener?.stop()
-    }
+    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`)
@@ -115,88 +93,8 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
     })
 }
 
-function installSigintAbort(): AbortController {
-  const ctrl = new AbortController()
-  const onSig = (): void => {
-    ctrl.abort()
-  }
-  process.once('SIGINT', onSig)
-  process.once('SIGTERM', onSig)
-  return ctrl
-}
-
-type EscListener = {
-  armForStream: () => AbortSignal
-  pause: () => void
-  resume: () => void
-  stop: () => void
-}
-
-type RawInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume' | 'pause' | 'on' | 'off'>
-
-export function createEscListener(onSigint: () => void, input: RawInput = process.stdin): EscListener | null {
-  const stdin = input
-  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
-
-  const ctrl = createEscController({ debounceMs: ESC_LISTEN_DELAY_MS })
-  let active = false
-
-  const onData = (chunk: Buffer): void => {
-    const { sigint } = ctrl.onChunk(chunk)
-    if (sigint) onSigint()
-  }
-
-  const start = (): void => {
-    if (active) return
-    active = true
-    stdin.setRawMode(true)
-    // Attach the data handler before resume() so no raw-mode keystroke can slip
-    // through between resuming the stream and registering the listener.
-    stdin.on('data', onData)
-    stdin.resume()
-  }
-  const stop = (): void => {
-    if (!active) return
-    active = false
-    stdin.off('data', onData)
-    try {
-      stdin.setRawMode(false)
-    } catch {
-      /* terminal already torn down */
-    }
-    // Do NOT pause stdin here: this teardown hands control to the clack picker,
-    // and under Bun clack does not reliably re-flow a previously paused
-    // process.stdin, so its keypresses never arrive and arrow keys echo as raw
-    // bytes. Leaving the stream flowing lets clack own raw mode during the picker.
-    ctrl.clearPending()
-  }
-
-  return {
-    armForStream: () => {
-      const signal = ctrl.armForStream()
-      start()
-      return signal
-    },
-    pause: () => {
-      stop()
-    },
-    resume: () => {
-      // Resume the listener WITHOUT replacing the AbortController.
-      // The signal returned by armForStream() is held by the live source
-      // through streamSession's combinedSignal; replacing the controller
-      // here would orphan that signal so a subsequent ESC press could
-      // not abort the live tail.
-      start()
-    },
-    stop: () => {
-      ctrl.dispose()
-      stop()
-    },
-  }
-}
-
 function escHintLine(color: boolean): string {
-  const text = '(press esc to return to session list)'
+  const text = '(esc to return to session list · q to quit)'
   return color ? `\u001b[2m${text}\u001b[0m` : text
 }
 

package/src/commands/index.ts

@@ -25,6 +25,13 @@ export type Command<Context> = {
   description: string
   permission?: CommandPermission
   requiresLiveSession?: boolean
+  // Resolve an existing live session into the handler context WITHOUT failing
+  // when none exists (distinct from `requiresLiveSession`, which aborts the
+  // command if no session is live). Used by /restart: it must bounce the
+  // container even from a cold channel, but when a session IS live it needs
+  // that session's identity to write a resume handoff. Ignored when
+  // `requiresLiveSession` is true (that path already resolves the session).
+  wantsLiveSession?: boolean
   handler: CommandHandler<Context>
 }
 
@@ -42,6 +49,7 @@ export type CommandInfo = {
   description: string
   permission: CommandPermission
   requiresLiveSession: boolean
+  wantsLiveSession: boolean
 }
 
 export type CommandResult =
@@ -74,6 +82,7 @@ export function createCommandRegistry<Context>(commands: readonly Command<Contex
     description: command.description,
     permission: command.permission ?? 'session.control',
     requiresLiveSession: command.requiresLiveSession ?? true,
+    wantsLiveSession: command.wantsLiveSession ?? false,
   })
 
   return {

package/src/init/gitignore.ts

@@ -32,16 +32,19 @@ auth.json
 node_modules/
 packages/*/node_modules/
 workspace/
+public/
 mounts/
 Dockerfile
 .DS_Store
 
 # System-managed: gitignored by default so the agent never stages them by hand,
-# but TypeClaw force-commits them on its own schedule (sessions/ via auto-backup,
-# memory/ via the dreaming subagent). Treat them as runtime-owned, not agent-owned.
+# but TypeClaw force-commits them on its own schedule (sessions/ + todo/ via
+# auto-backup, memory/ via the dreaming subagent). Treat them as runtime-owned,
+# not agent-owned.
 sessions/
 memory/
 channels/
+todo/
 `
 }
 

package/src/inspect/index.ts

@@ -30,11 +30,11 @@ export type RunInspectOptions = {
   stdout: (line: string) => void
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
+  // Aborting this signal stops the live tail and returns escToPicker=true; the
+  // caller's loop inspects its own scope intent to tell back from exit.
   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
+  interactive?: boolean
 }
 
 export type SelectSessionOptions = {
@@ -81,8 +81,8 @@ 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 } : {}),
+    ...(opts.interactive === true ? { interactive: true } : {}),
   })
   if (streamResult.escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
   return { ok: true, exitCode: 0 }
@@ -147,8 +147,8 @@ async function streamSession(opts: {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
-  escSignal?: AbortSignal
   liveHint?: string
+  interactive?: boolean
 }): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
   const emit = (event: InspectEvent): void => {
@@ -161,26 +161,37 @@ async function streamSession(opts: {
     }
   }
 
-  const escAborted = (): boolean => opts.escSignal?.aborted === true
+  const aborted = (): boolean => opts.signal?.aborted === true
 
   for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
-    if (escAborted()) return { escToPicker: true }
+    if (aborted()) return { escToPicker: true }
     emit(event)
   }
 
   if (opts.liveSource === undefined) {
     if (!opts.json) opts.stdout('─── end of transcript ───')
-    return { escToPicker: escAborted() }
+    // 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))
+      }
+      await waitForAbort(opts.signal)
+    }
+    return { escToPicker: aborted() }
   }
 
-  if (escAborted()) return { escToPicker: true }
+  if (aborted()) 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 } : {}),
-    ...(combinedSignal !== undefined ? { signal: combinedSignal } : {}),
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     onSubscribed: (live) => {
       sessionLive = live
     },
@@ -204,21 +215,7 @@ 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
+  return { escToPicker: aborted() }
 }
 
 function divider(color: boolean, text: string): string {
@@ -226,6 +223,13 @@ function divider(color: boolean, text: string): string {
   return text
 }
 
+export async function waitForAbort(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return
+  await new Promise<void>((resolve) => {
+    signal.addEventListener('abort', () => resolve(), { once: true })
+  })
+}
+
 function writeHeader(summary: SessionSummary, color: boolean, stdout: (line: string) => void): void {
   const id = shortSessionId(summary.sessionId)
   const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)