typeclaw 0.25.0 → 0.27.0

package/src/inspect/open-item.ts

@@ -0,0 +1,100 @@
+import type { LiveSourceFactory, RunInspectResult } from './index'
+import { createTranscriptView, streamInspectTarget } from './index'
+import type { ViewerItem } from './item'
+import { streamLogs } from './logs-item'
+import type { OpenItemContext, OpenItemResult, TailController } from './loop'
+import { runTuiViewer } from './tui-item'
+import type { InspectFilter } from './types'
+
+export type OpenViewerDeps = {
+  cwd: string
+  filter: InspectFilter
+  sinceMs: number | undefined
+  json: boolean
+  color: boolean
+  interactive: boolean
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  liveSource?: LiveSourceFactory
+  liveHint?: string
+  resolveTuiUrl: () => Promise<string>
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}
+
+// Dispatches a selected list item to its viewer. The tui branch and the
+// interactive read-only transcript view each own their own raw-mode pi-tui
+// terminal, so they run WITHOUT the loop's tail scope (two raw-stdin owners
+// would corrupt input). The line/JSON session path and logs run UNDER the tail
+// scope, which owns the raw-mode esc/q/ctrl-c handling.
+export function openViewerItem(deps: OpenViewerDeps) {
+  return async (item: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+    if (item.kind === 'tui') {
+      const result = await runTuiViewer({
+        resolveUrl: deps.resolveTuiUrl,
+        stderr: deps.stderr,
+        ...(deps.expectedVersion !== undefined ? { expectedVersion: deps.expectedVersion } : {}),
+        ...(deps.onVersionMismatch !== undefined ? { onVersionMismatch: deps.onVersionMismatch } : {}),
+      })
+      // Detaching the writable tui viewer ends the live session — the only path
+      // that should suppress the writable row on the next list refresh.
+      return { result, endedWritableSession: result.ok && result.escToPicker === true }
+    }
+
+    // Interactive-TTY read-only session -> rich pi-tui transcript view. Owns its
+    // own terminal, so it bypasses the tail scope. JSON/non-TTY falls through to
+    // the scriptable line renderer below. Read-only: esc does NOT end a live
+    // session, so endedWritableSession stays unset.
+    if (item.kind === 'session' && deps.interactive && !deps.json) {
+      const view = createTranscriptView({
+        summary: item.summary,
+        filter: deps.filter,
+        sinceMs: deps.sinceMs,
+        ...(deps.liveSource !== undefined ? { liveSource: deps.liveSource } : {}),
+      })
+      const outcome = await view.run()
+      const result: RunInspectResult =
+        outcome.reason === 'back' ? { ok: true, exitCode: 0, escToPicker: true } : { ok: true, exitCode: 0 }
+      return { result }
+    }
+
+    const scope = ctx.createTailScope()
+    try {
+      if (item.kind === 'logs') {
+        const logsResult = await streamLogs({
+          cwd: deps.cwd,
+          color: deps.color,
+          stdout: deps.stdout,
+          stderr: deps.stderr,
+          signal: scope.signal,
+          ...(deps.liveHint !== undefined ? { liveHint: deps.liveHint } : {}),
+        })
+        // Logs esc does NOT touch the live session — no endedWritableSession.
+        return { result: toResult(logsResult.escToPicker, scope) }
+      }
+
+      const sessionResult = await streamInspectTarget({
+        agentDir: deps.cwd,
+        target: { summary: item.summary, filter: deps.filter, sinceMs: deps.sinceMs },
+        json: deps.json,
+        color: deps.color,
+        stdout: deps.stdout,
+        stderr: deps.stderr,
+        signal: scope.signal,
+        ...(deps.liveSource !== undefined ? { liveSource: deps.liveSource } : {}),
+        ...(deps.liveHint !== undefined ? { liveHint: deps.liveHint } : {}),
+        ...(deps.interactive ? { interactive: true } : {}),
+      })
+      const escToPicker = sessionResult.ok && sessionResult.escToPicker === true
+      return { result: toResult(escToPicker, scope) }
+    } finally {
+      scope.dispose()
+    }
+  }
+}
+
+function toResult(escToPicker: boolean, scope: TailController): RunInspectResult {
+  if (scope.intent() === 'exit') return { ok: true, exitCode: 0 }
+  if (escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
+  return { ok: true, exitCode: 0 }
+}

package/src/inspect/preview.ts

@@ -0,0 +1,106 @@
+import type { MinimalSessionOrigin } from '@/agent/session-meta'
+
+// Builds the one-line session-list hint from a session's first user turn.
+// User turns are wrapped in runtime-injected preamble (<current-time>, role
+// anchors, SYSTEM MESSAGE fences, channel context sections, …) that grows over
+// time. Rather than chase every block, this keys off stable semantic
+// boundaries and prefers null over a misleading hint — it is a cosmetic glance,
+// not a faithful reconstruction.
+export function previewForHint(origin: MinimalSessionOrigin | null, text: string): string | null {
+  // A subagent's first message is a machine payload (Parent session:, …) and
+  // the row label already names the subagent.
+  if (origin?.kind === 'subagent') return null
+  if (origin?.kind === 'channel') return channelPreview(text)
+  return structuralPreview(text)
+}
+
+// `[ISO] <@authorId> (authorName) [bot]: actual text` — the only line carrying
+// human-typed text in a channel turn. The stamp is omitted when ts<=0, so it is
+// optional here; name and bot tag are also optional.
+const AUTHOR_LINE = /^(?:\[[^\]]+\]\s+)?<[^>]+>(?:\s+\([^)]+\))?(?:\s+\[bot\])?:\s*(.*)$/
+
+const CURRENT_MESSAGE_HEADER = /^## Current messages? \(addressed to you\)\s*$/
+
+// Channel preview: extract ONLY from the "## Current message(s) (addressed to
+// you)" section — never the "## Recent context" section above it, which is other
+// people's messages the agent was only made aware of. Returns null if no
+// addressed message is found.
+function channelPreview(text: string): string | null {
+  const lines = text.split('\n')
+  const headerIdx = lines.findIndex((l) => CURRENT_MESSAGE_HEADER.test(l))
+  if (headerIdx === -1) return null
+
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    const match = AUTHOR_LINE.exec(lines[i]!)
+    if (match === null) continue
+    const payload = collectMessage(match[1] ?? '', lines, i + 1)
+    const trimmed = payload.trim()
+    return trimmed.length > 0 ? trimmed : null
+  }
+  return null
+}
+
+// An author line's text plus any continuation lines (a multi-line message
+// continues without the author prefix) until the next author line, a structural
+// boundary (## / ---), or a quote anchor (>).
+function collectMessage(first: string, lines: string[], start: number): string {
+  const parts = [first]
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]!
+    if (AUTHOR_LINE.test(line) || line.startsWith('## ') || line.startsWith('---') || line.startsWith('>')) break
+    parts.push(line)
+  }
+  return parts.join(' ')
+}
+
+// Origin-agnostic fallback (TUI, cron, system, unknown): skip leading injected
+// structure — XML-tag blocks, `--- … ---` SYSTEM MESSAGE fences, `## …`
+// sections, and blank lines — then take the first remaining real line. This
+// degrades gracefully as new runtime notices (which follow the same framing
+// conventions) are added, without needing per-block updates.
+function structuralPreview(text: string): string | null {
+  const lines = text.split('\n')
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    const trimmed = line.trim()
+    if (trimmed === '') {
+      i++
+    } else if (trimmed.startsWith('<')) {
+      i = skipXmlOrTagLine(lines, i)
+    } else if (trimmed.startsWith('---')) {
+      i = skipFence(lines, i)
+    } else if (trimmed.startsWith('#')) {
+      i++
+    } else {
+      return looksInjected(trimmed) ? null : trimmed
+    }
+  }
+  return null
+}
+
+// Skips a leading XML block. If the opening tag closes on the same line or
+// spans lines, advance past the matching close tag; otherwise skip just the one
+// line (a stray `<…>` shouldn't swallow the rest).
+function skipXmlOrTagLine(lines: string[], start: number): number {
+  const open = /^<([a-zA-Z][\w-]*)/.exec(lines[start]!.trim())
+  if (open === null) return start + 1
+  const close = `</${open[1]}>`
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i]!.includes(close)) return i + 1
+  }
+  return start + 1
+}
+
+// Skips a `---` fenced block (SYSTEM MESSAGE framing): from the opening `---`
+// to the next standalone `---`.
+function skipFence(lines: string[], start: number): number {
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i]!.trim() === '---') return i + 1
+  }
+  return start + 1
+}
+
+function looksInjected(line: string): boolean {
+  return line.startsWith('**[SYSTEM') || line.startsWith('[security/')
+}

package/src/inspect/session-list.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import type { MinimalSessionOrigin } from '@/agent/session-meta'
 
+import { previewForHint } from './preview'
 import { replayJsonl } from './replay'
 
 export type SessionSummary = {
@@ -139,18 +140,29 @@ async function peekSession(
   onWarn?: (msg: string) => void,
 ): Promise<{ origin: MinimalSessionOrigin | null; firstPrompt: string | null }> {
   let origin: MinimalSessionOrigin | null = null
-  let firstPrompt: string | null = null
+  const userTexts: string[] = []
   let bytesRead = 0
   for await (const event of replayJsonl(path, onWarn !== undefined ? { onWarn } : {})) {
     if (event.cat === 'meta' && origin === null) origin = event.origin
-    if (event.cat === 'user' && firstPrompt === null) firstPrompt = event.text
-    if (origin !== null && firstPrompt !== null) break
+    if (event.cat === 'user' && userTexts.length < MAX_PREVIEW_CANDIDATES) userTexts.push(event.text)
+    if (origin !== null && userTexts.length >= MAX_PREVIEW_CANDIDATES) break
     bytesRead += approximateSize(event)
     if (bytesRead > PREVIEW_MAX_BYTES) break
   }
+  // Resolve the hint after the loop so origin (which selects the extraction
+  // strategy) is known even if a user event precedes the meta event. A turn
+  // that is pure injected preamble yields null, so fall through to the next user
+  // turn for a useful glance.
+  let firstPrompt: string | null = null
+  for (const text of userTexts) {
+    firstPrompt = previewForHint(origin, text)
+    if (firstPrompt !== null) break
+  }
   return { origin, firstPrompt }
 }
 
+const MAX_PREVIEW_CANDIDATES = 5
+
 function approximateSize(event: { ts: number }): number {
   return JSON.stringify(event).length
 }

package/src/inspect/transcript-view.ts

@@ -0,0 +1,182 @@
+import {
+  Key,
+  Markdown,
+  matchesKey,
+  ProcessTerminal,
+  type Component,
+  type Terminal,
+  Text,
+  TUI,
+} from '@mariozechner/pi-tui'
+
+import { formatToolEnd, formatToolStart, formatUserPromptHistory } from '@/tui/format'
+import { colors, markdownTheme } from '@/tui/theme'
+
+import { streamSessionEvents, type LiveSourceFactory, type StreamPhase } from './index'
+import { originLabel, shortSessionId } from './label'
+import type { SessionSummary } from './session-list'
+import type { InspectEvent, InspectFilter } from './types'
+
+export type TranscriptViewOutcome = { reason: 'back' | 'exit' }
+
+export type TranscriptViewOptions = {
+  summary: SessionSummary
+  filter: InspectFilter
+  sinceMs: number | undefined
+  liveSource?: LiveSourceFactory
+  createTerminal?: () => Terminal
+}
+
+// Read-only pi-tui transcript viewer: the rich counterpart to the line
+// renderer, matching the live TUI's look (markdown assistant blocks, formatted
+// tool panels) but with NO editor and NO websocket writes. It owns its own
+// raw-mode terminal, so the caller must NOT wrap it in a tail scope (a second
+// raw-stdin owner would corrupt input — same rule as the writable tui branch).
+// esc -> back to the list; q / ctrl-c -> exit.
+export function createTranscriptView(opts: TranscriptViewOptions) {
+  async function run(): Promise<TranscriptViewOutcome> {
+    const terminal = (opts.createTerminal ?? (() => new ProcessTerminal()))()
+    const tui = new TUI(terminal)
+
+    const status = new Text(statusLine('replay'), 0, 0)
+    tui.addChild(new Text(header(opts.summary), 0, 0))
+    tui.addChild(status)
+    tui.start()
+    tui.requestRender()
+
+    // The status line is pinned last (no editor to pin, unlike createTui). Each
+    // appended history entry is inserted before it: strip status, add entry,
+    // re-add status.
+    const append = (component: Component): void => {
+      tui.removeChild(status)
+      tui.addChild(component)
+      tui.addChild(status)
+    }
+
+    let settle: ((o: TranscriptViewOutcome) => void) | null = null
+    const outcome = new Promise<TranscriptViewOutcome>((resolve) => {
+      settle = resolve
+    })
+    const finish = (reason: TranscriptViewOutcome['reason']): void => {
+      if (settle === null) return
+      const fn = settle
+      settle = null
+      tui.stop()
+      fn({ reason })
+    }
+
+    tui.addInputListener((data) => {
+      if (matchesKey(data, Key.ctrl('c')) || data === 'q') {
+        finish('exit')
+        return { consume: true }
+      }
+      if (matchesKey(data, Key.escape)) {
+        finish('back')
+        return { consume: true }
+      }
+      return undefined
+    })
+
+    const abort = new AbortController()
+    // Drive the shared read pipeline into the component tree. Batch renders
+    // during replay (one render at replay-end) to avoid redraw storms on long
+    // transcripts; render per event once live.
+    let live = false
+    const onEvent = (event: InspectEvent): void => {
+      append(componentFor(event))
+      if (live) tui.requestRender()
+    }
+    const onPhase = (phase: StreamPhase): void => {
+      if (phase.phase === 'replay-end') {
+        tui.requestRender()
+      } else if (phase.phase === 'live-start') {
+        append(new Text(divider(phase.sessionLive ? 'live' : 'live (broadcasts only)'), 0, 0))
+        live = true
+        tui.requestRender()
+      }
+    }
+
+    const pump = streamSessionEvents({
+      summary: opts.summary,
+      filter: opts.filter,
+      sinceMs: opts.sinceMs,
+      onEvent,
+      onPhase,
+      signal: abort.signal,
+      ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
+      blockWhenReplayOnly: true,
+    })
+
+    const result = await outcome
+    // The viewer was dismissed: stop the pipeline (replay-only idle wait, or a
+    // live tail) so it does not run past the closed terminal.
+    abort.abort()
+    await pump.catch(() => {})
+    return result
+  }
+
+  return { run }
+}
+
+export function componentFor(event: InspectEvent): Component {
+  switch (event.cat) {
+    case 'assistant':
+      return new Markdown(event.text, 0, 0, markdownTheme)
+    case 'user':
+      return new Text(formatUserPromptHistory(event.text), 0, 0)
+    case 'tool':
+      return new Text(
+        event.phase === 'start'
+          ? formatToolStart(event.name, event.args)
+          : formatToolEnd(event.name, event.isError === true, event.result, event.durationMs ?? 0),
+        0,
+        0,
+      )
+    case 'thinking':
+      return new Text(colors.gray(event.redacted === true ? '[redacted thinking]' : event.text), 0, 0)
+    case 'meta':
+      return new Text(colors.dim(`origin: ${originLabel(event.origin)}`), 0, 0)
+    case 'error':
+      return new Text(
+        event.stopReason === 'aborted' ? colors.yellow(event.message) : colors.red(`error: ${event.message}`),
+        0,
+        0,
+      )
+    case 'done':
+      return new Text(colors.dim(doneSummary(event)), 0, 0)
+    case 'broadcast':
+      return new Text(colors.dim(`broadcast: ${compact(event.payload)}`), 0, 0)
+    case 'cron-fire':
+      return new Text(colors.dim(`cron ${event.jobId} fired`), 0, 0)
+    case 'inbound':
+      return new Text(colors.cyan(`[${event.decision}] ${event.authorName}: ${event.text}`), 0, 0)
+  }
+}
+
+function doneSummary(event: Extract<InspectEvent, { cat: 'done' }>): string {
+  const parts = [`${event.input} in / ${event.output} out tok`, `$${event.cost.toFixed(4)}`]
+  if (event.stopReason !== undefined) parts.push(`stop=${event.stopReason}`)
+  return parts.join(' · ')
+}
+
+function compact(payload: unknown): string {
+  if (payload !== null && typeof payload === 'object' && 'kind' in payload) {
+    return String((payload as { kind: unknown }).kind)
+  }
+  const s = JSON.stringify(payload) ?? String(payload)
+  return s.length > 200 ? `${s.slice(0, 200)}…` : s
+}
+
+function header(summary: SessionSummary): string {
+  const id = shortSessionId(summary.sessionId)
+  const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)
+  return colors.dim(`─── ${id} · ${label} ───`)
+}
+
+function statusLine(_phase: 'replay'): string {
+  return colors.dim('── read-only · esc to return to list · q to quit ──')
+}
+
+function divider(text: string): string {
+  return colors.dim(`─── ${text} ───`)
+}

package/src/inspect/tui-item.ts

@@ -0,0 +1,97 @@
+import { createTui, type TuiRunResult } from '@/tui'
+
+import type { RunInspectResult } from './index'
+
+export type TuiRunner = (opts: {
+  url: string
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}) => Promise<TuiRunResult>
+
+export type RunTuiViewerOptions = {
+  resolveUrl: () => Promise<string>
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+  stderr: (line: string) => void
+  runTui?: TuiRunner
+  reconnectMaxAttempts?: number
+  reconnectBackoffMs?: number
+  sleep?: (ms: number) => Promise<void>
+}
+
+const DEFAULT_RECONNECT_MAX_ATTEMPTS = 30
+const DEFAULT_RECONNECT_BACKOFF_MS = 1_000
+
+// The interactive read+write viewer branch. Unlike session/logs, this does NOT
+// run under the loop's tail scope: createTui owns its own raw-mode pi-tui
+// terminal and esc/ctrl-c handling, so a second raw-stdin owner would corrupt
+// input. The branch maps createTui's outcome into the loop's result contract:
+// detach → back to the list (escToPicker), exit → terminate, lostConnection →
+// reconnect (the self-restart case), connectFailed → error result.
+export async function runTuiViewer(opts: RunTuiViewerOptions): Promise<RunInspectResult> {
+  const runTui = opts.runTui ?? defaultRunTui
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const maxAttempts = opts.reconnectMaxAttempts ?? DEFAULT_RECONNECT_MAX_ATTEMPTS
+  const backoffMs = opts.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS
+
+  let initialPrompt = opts.initialPrompt
+  let attempt = 0
+
+  while (true) {
+    let url: string
+    try {
+      url = await opts.resolveUrl()
+    } catch (err) {
+      return { ok: false, exitCode: 1, reason: errorMessage(err) }
+    }
+
+    let result: TuiRunResult
+    try {
+      result = await runTui({
+        url,
+        ...(initialPrompt !== undefined ? { initialPrompt } : {}),
+        ...(opts.expectedVersion !== undefined ? { expectedVersion: opts.expectedVersion } : {}),
+        ...(opts.onVersionMismatch !== undefined ? { onVersionMismatch: opts.onVersionMismatch } : {}),
+      })
+    } catch (err) {
+      return { ok: false, exitCode: 1, reason: errorMessage(err) }
+    }
+
+    if (result.reason === 'detach') return { ok: true, exitCode: 0, escToPicker: true }
+    if (result.reason === 'exit') return { ok: true, exitCode: result.exitCode }
+    if (result.reason === 'connectFailed') return { ok: false, exitCode: 1, reason: 'connection failed' }
+
+    // lostConnection: the WS dropped post-handshake (self-restart, network
+    // blip). Re-resolve the URL because the host port can change across
+    // container lifecycles, then reconnect. Clear the initial prompt so a
+    // reconnect resuming the same session does not re-send it to the LLM.
+    initialPrompt = undefined
+    attempt += 1
+    if (attempt > maxAttempts) {
+      return { ok: false, exitCode: 1, reason: `disconnected; gave up after ${maxAttempts} reconnect attempts` }
+    }
+    opts.stderr(`reconnecting (attempt ${attempt}/${maxAttempts})...`)
+    await sleep(backoffMs)
+  }
+}
+
+function defaultRunTui(opts: {
+  url: string
+  initialPrompt?: string
+  expectedVersion?: string
+  onVersionMismatch?: (info: { expected: string; actual: string }) => void
+}): Promise<TuiRunResult> {
+  return createTui({
+    url: opts.url,
+    exit: () => {},
+    ...(opts.initialPrompt !== undefined ? { initialPrompt: opts.initialPrompt } : {}),
+    ...(opts.expectedVersion !== undefined ? { expectedVersion: opts.expectedVersion } : {}),
+    ...(opts.onVersionMismatch !== undefined ? { onVersionMismatch: opts.onVersionMismatch } : {}),
+  }).run()
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -20,7 +20,7 @@ Before you pick an action, classify the inbound. Skipping this step is how a PR
 
 1. **Is this a PR, and do I have an unresolved blocking obligation on it?** On any `pr:N` inbound, before anything else, check whether you owe this PR a verdict you have not yet landed. Check **both** signals below — checking only formal review state misses the very failure this gate exists to catch, because a prior block may never have become formal state:
    - **Formal review state.** Run the step-1 re-review query in the PR review flow (`gh api --paginate --slurp /repos/owner/repo/pulls/<N>/reviews --jq '…'` filtered to `{CHANGES_REQUESTED, APPROVED}`). If your latest **blocking decision** is `CHANGES_REQUESTED`, you have a live sticky block.
-   - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`.
+   - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`. **A courtesy acknowledgement is not a retraction.** A reply you posted like "nice, that closes the hole" / "thanks, looks good" / "✅" does **not** supersede or retract a blocker you raised — it is a chat ack, not a verdict, and it carries no review state. The blocker stays binding until you land a **formal** `APPROVE`/`REQUEST_CHANGES` (or dismiss your prior review). So when an earlier "✅ thanks" of yours is the only thing between your blocker and the author's address-comment, the blocker is **still live** and this inbound is a re-review — do not let your own ack downgrade it.
 
    If **either** signal shows an unresolved blocker you raised, this inbound is a **re-review** — go to the **PR review flow** regardless of how it is phrased. An author commenting "fixed both issues" / "addressed your feedback" / "pushed a fix" is a re-review trigger, **not** a thread-resolve trigger. A re-review is closed by re-deciding the verdict and landing a **formal** review via `POST /pulls/<N>/reviews`: `APPROVE` clears a sticky `CHANGES_REQUESTED`; a comment or a flat reply clears neither a formal block nor a flat-comment blocker — it just strands the verdict again, which is the original bug.
 
@@ -189,7 +189,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
-- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
 - `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 
@@ -201,6 +201,8 @@ A review you posted leaves inline comment threads open on the PR. When one of **
 
 **The base principle: whoever opened the thread closes it.** Resolve only threads whose root comment **you** authored. Never resolve a human reviewer's thread on your behalf — that erases their open question. The thread you can resolve is the one you started; the inbound that brings you here is a **review-thread reply on `pr:N` with `thread` set**, replying inside a thread you opened.
 
+> **Thread cleanup is not the same as discharging a PR-level block.** Resolving an inline thread closes that one thread; it carries **no** review state and does **not** clear a PR-level blocking obligation (a sticky `CHANGES_REQUESTED`, or a flat blocker you authored on the PR conversation). Those are two separate duties. If triage #1 found a live PR-level block, that inbound is a **re-review** and the PR review flow wins over this section — you owe a formal `APPROVE`/`REQUEST_CHANGES`, and resolving threads (or a chat ✅) must **not** be your final response. Reach this section only for a thread-scoped reply on a PR where you owe no PR-level verdict (triage #1 came back clean). When in doubt, re-run triage #1 first.
+
 ### When a thread counts as addressed
 
 Do not resolve on a bare "done" claim. A reply that says "fixed" is a prompt to check, not proof. Before resolving, **verify the fix at the PR's current head SHA**: