typeclaw 0.26.0 → 0.27.0

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 {

package/src/cli/tui.ts

@@ -3,14 +3,16 @@ import { defineCommand } from 'citty'
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { CLI_VERSION } from '@/init/cli-version'
-import { createTui, formatVersionMismatchWarning } from '@/tui'
+import { runTuiViewer } from '@/inspect'
+import { formatVersionMismatchWarning } from '@/tui'
 
+import { runInspectViewer } from './inspect'
 import { errorLine } from './ui'
 
 export const tui = defineCommand({
   meta: {
     name: 'tui',
-    description: 'start the tui client',
+    description: 'open the live agent session in the read+write viewer (host stage)',
   },
   args: {
     prompt: {
@@ -25,50 +27,42 @@ export const tui = defineCommand({
     },
   },
   async run({ args }) {
-    const resolveUrl: () => Promise<string> = args.url !== undefined ? async () => args.url as string : defaultUrl
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const resolveUrl: () => Promise<string> =
+      args.url !== undefined ? async () => args.url as string : () => defaultUrl(cwd)
 
-    let initialPrompt: string | undefined = args.prompt
-    let attempt = 0
-    const RECONNECT_MAX_ATTEMPTS = 30
-    const RECONNECT_BACKOFF_MS = 1_000
+    const result = await runTuiViewer({
+      resolveUrl,
+      ...(args.prompt !== undefined ? { initialPrompt: args.prompt } : {}),
+      expectedVersion: CLI_VERSION,
+      onVersionMismatch: (info) => {
+        process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
+      },
+      stderr: (line) => process.stderr.write(`${line}\n`),
+    })
 
-    while (true) {
-      const url = await resolveUrl()
-      const tui = createTui({
-        url,
-        ...(initialPrompt !== undefined ? { initialPrompt } : {}),
-        expectedVersion: CLI_VERSION,
-        onVersionMismatch: (info) => {
-          process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
-        },
-      })
-      const outcome = await tui.run()
-      if (!outcome.lostConnection) return
-      // The TUI lost its WS post-handshake (container restart, network blip,
-      // hostd hiccup). Re-resolve the URL because the host port can change
-      // across container lifecycles (see resolveHostPort), then reconnect.
-      // The initial prompt is intentionally cleared after the first cycle:
-      // on a reconnect, the agent is resuming the same session — replaying
-      // the prompt would re-send it to the LLM.
-      initialPrompt = undefined
-      attempt += 1
-      if (attempt > RECONNECT_MAX_ATTEMPTS) {
-        console.error(errorLine(`disconnected; gave up after ${RECONNECT_MAX_ATTEMPTS} reconnect attempts`))
-        process.exit(1)
-      }
-      process.stderr.write(`reconnecting (attempt ${attempt}/${RECONNECT_MAX_ATTEMPTS})...\n`)
-      await new Promise((resolve) => setTimeout(resolve, RECONNECT_BACKOFF_MS))
+    // Esc detached from the live session: drop into the viewer list so the user
+    // can pick another session or the container logs — `tui` is just a deep-link
+    // into the session viewer, pre-opened on the live session. allowWritable
+    // is false because detaching ended the live session, so no row may be
+    // offered as a writable "live TUI" anymore.
+    if (result.ok && result.escToPicker === true) {
+      const viewerExit = await runInspectViewer({ cwd, allowWritable: false })
+      process.exit(viewerExit)
+      return
     }
+
+    if (!result.ok) {
+      process.stderr.write(`${errorLine(result.reason)}\n`)
+      process.exit(result.exitCode)
+    }
+    process.exit(result.exitCode)
   },
 })
 
-async function defaultUrl(): Promise<string> {
-  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+async function defaultUrl(cwd: string): Promise<string> {
   const precheck = await requireContainerRunning({ cwd })
-  if (!precheck.ok) {
-    console.error(errorLine(precheck.reason))
-    process.exit(1)
-  }
+  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}`)

package/src/compose/logs.ts

@@ -100,7 +100,7 @@ export async function composeLogs({
       follow,
       ...(tail !== undefined ? { tail } : {}),
     })
-    const proc = bun.spawn({ cmd, stdout: 'pipe', stderr: 'pipe' })
+    const proc = bun.spawn({ cmd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
     return { agent, proc }
   })
 

package/src/container/logs.ts

@@ -44,27 +44,48 @@ export async function logs({
       return { ok: false, reason: `Container ${plan.containerName} not found. Run \`typeclaw start\` first.` }
     }
 
-    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdout: 'pipe', stderr: 'pipe' })
+    // stdin:'ignore' — `docker logs` never reads stdin, and letting the child
+    // hold the TTY breaks the viewer's raw-mode keypress listener (esc/q/ctrl-c
+    // stop reaching it, freezing the logs view with no way out).
+    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
 
+    // `docker logs -f` never exits on its own; aborting the signal must kill it
+    // so the pumps' stream readers end. Escalate to SIGKILL if SIGTERM is
+    // ignored, otherwise Promise.all(pumps) could hang until the pipes close.
+    let killTimer: ReturnType<typeof setTimeout> | undefined
     const onAbort = (): void => {
       try {
         proc.kill('SIGTERM')
+        killTimer = setTimeout(() => {
+          try {
+            proc.kill('SIGKILL')
+          } catch {
+            // already exited
+          }
+        }, 2_000)
       } catch {
         // already exited
       }
     }
     signal?.addEventListener('abort', onAbort, { once: true })
+    // The signal may already be aborted before we attached the listener (esc
+    // pressed during container existence check); addEventListener would then
+    // never fire, leaving docker logs -f running forever.
+    if (signal?.aborted === true) onAbort()
 
-    const colorOut = useColor ?? supportsColor(out)
-    const colorErr = useColor ?? supportsColor(err)
-    await Promise.all([
-      pumpWithTimestamps(proc.stdout, out, makeLogTimestampReformatter(undefined, { color: colorOut })),
-      pumpWithTimestamps(proc.stderr, err, makeLogTimestampReformatter(undefined, { color: colorErr })),
-    ])
-    const exitCode = await proc.exited
-    signal?.removeEventListener('abort', onAbort)
-
-    return { ok: true, containerName: plan.containerName, exitCode }
+    try {
+      const colorOut = useColor ?? supportsColor(out)
+      const colorErr = useColor ?? supportsColor(err)
+      await Promise.all([
+        pumpWithTimestamps(proc.stdout, out, makeLogTimestampReformatter(undefined, { color: colorOut }), signal),
+        pumpWithTimestamps(proc.stderr, err, makeLogTimestampReformatter(undefined, { color: colorErr }), signal),
+      ])
+      const exitCode = await proc.exited
+      return { ok: true, containerName: plan.containerName, exitCode }
+    } finally {
+      if (killTimer !== undefined) clearTimeout(killTimer)
+      signal?.removeEventListener('abort', onAbort)
+    }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
@@ -101,30 +122,57 @@ export function buildDockerLogsCmd(plan: LogsPlan): string[] {
 
 // Exported for `compose/logs.ts` so the multi-agent path reuses the same
 // reformatter and stays consistent with single-agent output.
+//
+// Abort handling is load-bearing for the interactive logs viewer: killing
+// `docker logs -f` does NOT reliably make Bun's pending `reader.read()` resolve
+// (the killed child may not promptly EOF its piped stdout — see the OrbStack
+// /proc quirk). Without cancelling the reader on abort, esc would hang forever.
+// So on abort we cancel the reader, which unblocks the pending read; the caller
+// still kills the process for OS-side cleanup.
 export async function pumpWithTimestamps(
   stream: ReadableStream<Uint8Array>,
   sink: NodeJS.WritableStream,
   reformatter: TimestampReformatter = makeLogTimestampReformatter(),
+  signal?: AbortSignal,
 ): Promise<void> {
   const decoder = new TextDecoder()
   const reader = stream.getReader()
+  let aborted = signal?.aborted === true
+  const onAbort = (): void => {
+    aborted = true
+    void reader.cancel().catch(() => {})
+  }
+  if (aborted) onAbort()
+  else signal?.addEventListener('abort', onAbort, { once: true })
+
   try {
     while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      if (value && value.byteLength > 0) {
-        const out = reformatter.write(decoder.decode(value, { stream: true }))
+      if (aborted) break
+      const chunk = await reader.read().catch((error: unknown) => {
+        if (aborted || signal?.aborted === true) return null
+        throw error
+      })
+      if (chunk === null || chunk.done || aborted) break
+      if (chunk.value && chunk.value.byteLength > 0) {
+        const out = reformatter.write(decoder.decode(chunk.value, { stream: true }))
         if (out.length > 0) sink.write(out)
       }
     }
-    const tail = decoder.decode()
-    if (tail.length > 0) {
-      const out = reformatter.write(tail)
-      if (out.length > 0) sink.write(out)
+    if (!aborted) {
+      const tail = decoder.decode()
+      if (tail.length > 0) {
+        const out = reformatter.write(tail)
+        if (out.length > 0) sink.write(out)
+      }
+      const flushed = reformatter.flush()
+      if (flushed.length > 0) sink.write(flushed)
     }
-    const flushed = reformatter.flush()
-    if (flushed.length > 0) sink.write(flushed)
   } finally {
-    reader.releaseLock()
+    signal?.removeEventListener('abort', onAbort)
+    try {
+      reader.releaseLock()
+    } catch {
+      // harmless if cancel/abort raced with stream teardown
+    }
   }
 }