typeclaw 0.28.0 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/provider-error.ts

@@ -13,7 +13,39 @@ import type { AgentSession } from './index'
 // not by this helper.
 
 export type DetectedProviderError = {
+  // Raw provider text. Safe for logs and operator-only surfaces (TUI,
+  // `typeclaw logs`), but NOT for channels — see `safeMessage`.
   message: string
+  // Redacted, user-facing variant for public/multi-user channels. Known-safe
+  // operational classes (rate/usage limit, billing/quota) map to a canonical
+  // sentence; everything else (malformed-response SDK dumps, unknown failures)
+  // collapses to a generic notice so provider response bodies, URLs, or tokens
+  // can never leak to a channel.
+  safeMessage: string
+}
+
+const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can check `typeclaw logs` for details.'
+
+// Each entry pairs a narrow matcher against the raw provider text with the
+// canonical, leak-free sentence shown in channels. Matchers are intentionally
+// specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
+// text, so adding a new class is opt-in and never widens what we expose.
+const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
+  {
+    match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
+    safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
+  },
+  {
+    match: /\b(billing|quota|insufficient.*(credit|fund|balance)|payment|account is not active)\b/i,
+    safe: 'The upstream LLM provider rejected the request for a billing/quota reason. Operators can check `typeclaw logs` for details.',
+  },
+]
+
+function toSafeMessage(raw: string): string {
+  for (const { match, safe } of SAFE_CLASSES) {
+    if (match.test(raw)) return safe
+  }
+  return GENERIC_SAFE_NOTICE
 }
 
 export function detectProviderError(message: unknown): DetectedProviderError | null {
@@ -25,7 +57,7 @@ export function detectProviderError(message: unknown): DetectedProviderError | n
   // ignore aborts (no surface to render them on).
   if (m.stopReason !== 'error') return null
   const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
-  return { message: text }
+  return { message: text, safeMessage: toSafeMessage(text) }
 }
 
 export type ProviderErrorListener = (error: DetectedProviderError) => void

package/src/agent/tools/channel-reply.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
 import {
   containsKimiToolDelimiter,
   isNoReplySignal,
@@ -159,6 +160,27 @@ export function createChannelReplyTool({
       }
       const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
 
+      // Re-review stranding guard: block a thread close-out / verdict ack while
+      // the bot still holds its own CHANGES_REQUESTED on this PR, so it can't
+      // silently leave the PR blocked (PR #644). Runs before the resolve so a
+      // blocked close-out never mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        text,
+        wantsResolve: params.resolve_review_thread === true,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_reply', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
       // Resolve BEFORE posting: a successful channel_reply ends the turn, so a
       // resolve attempted "after" the ack would never run (the exact bug this
       // flag fixes). Resolve-failure blocks the reply so the agent never posts

package/src/agent/tools/channel-send.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
 import { recordResolvedThread } from '@/channels/github-review-turn-ledger'
 import {
   containsKimiToolDelimiter,
@@ -176,6 +177,26 @@ export function createChannelSendTool({
       }
       const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
 
+      // Re-review stranding guard (mirrors channel_reply): block a thread
+      // close-out / verdict ack while the bot still holds its own
+      // CHANGES_REQUESTED on this PR, before the resolve mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter,
+        workspace: params.workspace,
+        chat: params.chat,
+        thread: params.thread ?? null,
+        text: bodyText,
+        wantsResolve,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_send', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
       // Resolve BEFORE posting (mirrors channel_reply): a failed resolve must
       // block the acknowledgement so the bot never posts "addressed — resolving"
       // next to a still-open thread. The router enforces that only the bot's own

package/src/channels/adapters/github/index.ts

@@ -21,6 +21,7 @@ import {
   parseListHooksPermissionStatus,
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
+import { createGithubReviewStateResolver } from './review-state'
 import { createGithubReviewThreadResolver } from './review-thread-resolver'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
@@ -143,6 +144,12 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfLogin: () => selfLogin,
     fetchImpl,
   })
+  const reviewStateResolver = createGithubReviewStateResolver({
+    token: authToken,
+    selfLogin: () => selfLogin,
+    approve: () => options.configRef().review.approve,
+    fetchImpl,
+  })
   const channelNameResolver = createGithubChannelNameResolver({ token: authToken, fetchImpl })
   // GitHub addresses by `@login`, not the numeric id, so `username` carries
   // the login the model should type; the id is kept for completeness.
@@ -195,6 +202,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.registerChannelNameResolver('github', channelNameResolver)
       options.router.registerSelfIdentity('github', selfIdentityResolver)
       options.router.registerReviewThreadResolver('github', reviewThreadResolver)
+      options.router.registerReviewStateResolver('github', reviewStateResolver)
       options.router.registerFetchAttachment('github', fetchAttachment)
       try {
         server = (options.httpListenImpl ?? listenWithBun)(options.configRef().webhookPort, handler)
@@ -210,6 +218,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         options.router.unregisterChannelNameResolver('github', channelNameResolver)
         options.router.unregisterSelfIdentity('github', selfIdentityResolver)
         options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
+        options.router.unregisterReviewStateResolver('github', reviewStateResolver)
         options.router.unregisterFetchAttachment('github', fetchAttachment)
         await auth.dispose()
         delete process.env.GH_TOKEN
@@ -334,6 +343,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.unregisterChannelNameResolver('github', channelNameResolver)
       options.router.unregisterSelfIdentity('github', selfIdentityResolver)
       options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
+      options.router.unregisterReviewStateResolver('github', reviewStateResolver)
       options.router.unregisterFetchAttachment('github', fetchAttachment)
       await server?.stop()
       // Detach hooks AFTER closing the listener so any in-flight deliveries

package/src/channels/adapters/github/review-state.ts

@@ -0,0 +1,137 @@
+import type { ReviewStateResolver, ReviewStateResult } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// Answers the re-review stranding guard's question: is the bot's latest
+// EFFECTIVE formal review on this PR a sticky CHANGES_REQUESTED? GitHub clears a
+// same-reviewer CHANGES_REQUESTED only with a later APPROVED or DISMISSED from
+// the same reviewer — a later COMMENTED review does NOT clear it (the PR #644
+// trap). So we walk the bot's own reviews in chronological order, ignore
+// COMMENTED/PENDING, and read the last decisive one.
+export function createGithubReviewStateResolver(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  selfLogin: () => string | null
+  approve: () => boolean
+  fetchImpl?: typeof fetch
+}): ReviewStateResolver {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReviewStateResult> => {
+    const approve = deps.approve()
+    if (req.adapter !== 'github') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = parseTarget(req.workspace, req.chat)
+    if (target === null) {
+      return { ok: false, error: `unparseable github PR target (chat=${req.chat})`, code: 'transient' }
+    }
+    const selfLogin = deps.selfLogin()
+    if (selfLogin === null) {
+      return { ok: false, error: 'github self-identity not resolved; cannot read review state', code: 'transient' }
+    }
+
+    const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
+    const reviews = await fetchSelfReviews(fetchImpl, token, target, selfLogin)
+    if (!reviews.ok) return { ok: false, error: reviews.error, code: reviews.code }
+
+    const lastDecisive = reviews.states.filter(isDecisive).at(-1) ?? null
+    return { ok: true, selfBlocking: lastDecisive === 'CHANGES_REQUESTED', approve }
+  }
+}
+
+type Target = { owner: string; repo: string; prNumber: number }
+
+function parseTarget(workspace: string, chat: string): Target | null {
+  const [owner, repo, ...rest] = workspace.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  const m = /^pr:(\d+)$/.exec(chat)
+  if (m === null) return null
+  const prNumber = Number(m[1])
+  if (!Number.isSafeInteger(prNumber) || prNumber <= 0) return null
+  return { owner, repo, prNumber }
+}
+
+type SelfReviewsResult =
+  | { ok: true; states: string[] }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
+async function fetchSelfReviews(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: Target,
+  selfLogin: string,
+): Promise<SelfReviewsResult> {
+  const states: string[] = []
+  let url: string | null =
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/pulls/${target.prNumber}/reviews?per_page=100`
+  while (url !== null) {
+    let response: Response
+    try {
+      response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => '')
+      return {
+        ok: false,
+        error: `GitHub reviews ${response.status}${text !== '' ? `: ${text}` : ''}`,
+        code: classifyStatus(response.status),
+      }
+    }
+    const page = (await response.json().catch(() => null)) as ReviewRow[] | null
+    if (page === null) return { ok: false, error: 'GitHub reviews returned non-JSON', code: 'transient' }
+    for (const row of page) {
+      if (typeof row.state !== 'string') continue
+      const login = row.user?.login ?? null
+      if (login === null) continue
+      const isBot = row.user?.type === 'Bot'
+      if (!isSelfReviewer(login, isBot, selfLogin)) continue
+      states.push(row.state)
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return { ok: true, states }
+}
+
+// A formal CHANGES_REQUESTED is sticky until a later APPROVED/DISMISSED; only
+// these three states decide the block. COMMENTED and PENDING are non-deciding
+// noise that must NOT shadow an earlier CHANGES_REQUESTED.
+const DECISIVE = new Set(['CHANGES_REQUESTED', 'APPROVED', 'DISMISSED'])
+
+function isDecisive(state: string): boolean {
+  return DECISIVE.has(state)
+}
+
+// A GitHub App's own login differs across REST (`slug[bot]`) and GraphQL (bare
+// `slug`). The REST reviews endpoint returns `slug[bot]` for the App, but the
+// suffix-strip must be gated on the reviewer actually being a Bot: a human User
+// can own the bare slug as a login, and stripping `[bot]` off the App's
+// selfLogin to match a human would wrongly attribute their review to the bot.
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+function isSelfReviewer(login: string, isBot: boolean, selfLogin: string): boolean {
+  if (isBot) return normalizeBotLogin(login) === normalizeBotLogin(selfLogin)
+  return login === selfLogin
+}
+
+function normalizeBotLogin(login: string): string {
+  return login.endsWith(BOT_LOGIN_SUFFIX) ? login.slice(0, -BOT_LOGIN_SUFFIX.length) : login
+}
+
+function nextLink(linkHeader: string | null): string | null {
+  if (linkHeader === null) return null
+  for (const part of linkHeader.split(',')) {
+    const m = /<([^>]+)>;\s*rel="next"/.exec(part)
+    if (m !== null) return m[1] ?? null
+  }
+  return null
+}
+
+function classifyStatus(status: number): 'not-found' | 'permission-denied' | 'transient' {
+  if (status === 401 || status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  return 'transient'
+}
+
+type ReviewRow = { id?: number; state?: unknown; user?: { login?: string; type?: string } }

package/src/channels/github-rereview-guard.ts

@@ -0,0 +1,76 @@
+import { classifyReviewClaim } from './github-review-claim'
+import type { ReviewStateResult } from './types'
+
+// The re-review stranding guard. A bot that resolves a review thread (or posts a
+// close-out ack) while it still holds its own sticky CHANGES_REQUESTED leaves the
+// PR blocked forever — the resolve/ack carries no review state, so GitHub's
+// reviewDecision never clears (PR #644). This guard blocks that close-out and
+// tells the model to land a formal APPROVE / dismissal first.
+//
+// It is the same enforcement seam as the false-receipt guard and the
+// resolve-thread author check: BLOCK and instruct, never act on the model's
+// behalf — the runtime cannot prove a semantic approval from "one thread closed".
+
+export type RereviewGuardInput = {
+  adapter: string
+  chat: string
+  thread: string | null
+  text: string | undefined
+  wantsResolve: boolean
+  getReviewState: (req: { adapter: 'github'; workspace: string; chat: string }) => Promise<ReviewStateResult>
+  workspace: string
+}
+
+export type RereviewGuardDecision = { block: false } | { block: true; reason: string }
+
+const ALLOW: RereviewGuardDecision = { block: false }
+
+export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<RereviewGuardDecision> {
+  if (input.adapter !== 'github') return ALLOW
+  if (!/^pr:\d+$/.test(input.chat)) return ALLOW
+  // No `thread === null` exemption: a top-level PR comment carries no thread but
+  // a close-out ack in it ("Verified — that closes it") strands the block just
+  // as a thread reply would. Only the resolve ACTION needs a thread; the
+  // text-claim path fires regardless (caught by isCloseoutAttempt below).
+  if (!isCloseoutAttempt(input.wantsResolve, input.thread, input.text)) return ALLOW
+
+  const state = await input.getReviewState({ adapter: 'github', workspace: input.workspace, chat: input.chat })
+
+  // Fail closed: an unverifiable review state is treated as a live block, so the
+  // bot never strands a re-review on a transient API failure.
+  if (!state.ok) return { block: true, reason: unverifiableReason(state.error) }
+  if (!state.selfBlocking) return ALLOW
+
+  return { block: true, reason: state.approve ? STICKY_BLOCK_APPROVE_ENABLED : STICKY_BLOCK_APPROVE_DISABLED }
+}
+
+// Trigger when the model asks to resolve a thread (only meaningful with a
+// thread), OR when its reply reads as a close-out/verdict claim — the latter
+// strands the block whether or not it sits in a thread, so it fires for any PR
+// chat. Plain discussion replies (ignore/warn) do not fire.
+function isCloseoutAttempt(wantsResolve: boolean, thread: string | null, text: string | undefined): boolean {
+  if (wantsResolve && thread !== null) return true
+  const claim = classifyReviewClaim(text ?? '')
+  return claim === 'block-resolve' || claim === 'block-approve'
+}
+
+function unverifiableReason(error: string): string {
+  return (
+    'Could not verify whether your prior CHANGES_REQUESTED on this PR is still live ' +
+    `(${error}). Refusing to close out the thread while the block state is unknown — ` +
+    'retry once the GitHub API is reachable, or land a formal review verdict first.'
+  )
+}
+
+const STICKY_BLOCK_APPROVE_ENABLED =
+  'You still hold a CHANGES_REQUESTED on this PR. Resolving the thread (or posting a close-out ack) ' +
+  'does NOT clear it — only a fresh formal review does. Submit `APPROVE` via ' +
+  '`gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` (event: APPROVE) if the blockers are fixed, ' +
+  'or `REQUEST_CHANGES` if not, THEN resolve the thread / reply.'
+
+const STICKY_BLOCK_APPROVE_DISABLED =
+  'You still hold a CHANGES_REQUESTED on this PR and resolving the thread does NOT clear it. ' +
+  'Approval is disabled for this agent (channels.github.review.approve: false), so you cannot APPROVE — ' +
+  'dismiss your prior review via ' +
+  '`gh api -X PUT /repos/<owner>/<repo>/pulls/<N>/reviews/<review_id>/dismissals -f message="..." -f event=DISMISS` ' +
+  'if the blockers are fixed (or submit REQUEST_CHANGES if not), THEN resolve the thread / reply.'

package/src/channels/github-review-claim.ts

@@ -24,15 +24,16 @@ const BLOCK_REQUEST_CHANGES: readonly RegExp[] = [
   /\bthis is blocked\b/,
 ]
 
-// Only consulted by the caller when thread!=null (a review thread). Bare
-// "resolved" is intentionally NOT here — it collides with the warn-tier "looks
-// resolved?"; resolve claims must carry a definite marker (marked/that/this/
-// thanks) or a verify clause.
+// Bare "resolved" is intentionally NOT here — it collides with the warn-tier
+// "looks resolved?"; resolve claims must carry a definite marker (marked/that/
+// this/thanks) or a verify clause. "that/this closes it" is the canonical PR
+// #644 incident phrasing and must classify as a close-out claim.
 const BLOCK_RESOLVE: readonly RegExp[] = [
   /\bmarked resolved\b/,
   /\bthread resolved\b/,
   /\bthat resolves it\b/,
   /\bthis resolves it\b/,
+  /\b(that|this) closes it\b/,
   /\bclosing this out\b/,
   /\bconfirmed fixed\b/,
   // verify clause + a fix/resolve verb, allowing a short gap ("verified at <sha>, that fixes it").

package/src/channels/router.ts

@@ -75,6 +75,9 @@ import type {
   ReactionRequest,
   ReactionResult,
   ResolvedChannelNames,
+  ReviewStateRequest,
+  ReviewStateResolver,
+  ReviewStateResult,
   ReviewThreadResolveRequest,
   ReviewThreadResolveResult,
   ReviewThreadResolver,
@@ -178,6 +181,44 @@ export const MAX_POLICY_DENIED_CHANNEL_SENDS_PER_TURN = 3
 // including reasoning). Deliberately NOT lowered in `providers.ts`, where
 // `maxTokens` is the model's true capability that compaction math reads.
 export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
+// Ceiling on automatic re-prompts for a turn that ended with NO user-facing
+// reply AND no attempted send — the pure "the model burned its budget thinking
+// and produced nothing" failure. The canonical trigger is Fireworks'
+// kimi-k2p6-turbo spiraling into a long reasoning loop on an ambiguous request
+// until it hits CHANNEL_MAX_OUTPUT_TOKENS (`stopReason: 'length'`); the same
+// path also catches a provider/router `aborted` leaf that left no recoverable
+// prose. Each retry injects EMPTY_TURN_RETRY_NUDGE as a reminder-only turn (no
+// new inbound) so `drain()` re-runs `session.prompt()` against the same branch.
+// Bounded because a genuinely stuck model would otherwise re-loop forever; on
+// exhaustion the user gets EMPTY_TURN_FALLBACK_TEXT instead of dead air. Reset
+// at turn start alongside `turnSeq`. Deliberately NOT applied to turns that
+// ATTEMPTED a send this turn (skip-locked or policy-denied) — those already
+// thrashed the send path, so a re-prompt would just re-thrash; they skip
+// straight to the fallback. See validateChannelTurn's candidate===null branch.
+export const MAX_EMPTY_TURN_RETRIES = 2
+// Reminder-only nudge injected before an empty-turn retry. Uses the repo's
+// SYSTEM MESSAGE framing (see composeTurnPrompt) so persona-rich models do not
+// reply to the notice itself. Neutral by design: it asks for a direct reply
+// without prescribing length or tone, matching the chosen "just retry" posture.
+export const EMPTY_TURN_RETRY_NUDGE = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Your previous turn ended without sending any reply to the channel. This is',
+  'an automated signal from the channel router, not a message from anyone in',
+  'the chat. **Do not acknowledge or reply to this notice itself.**',
+  '',
+  'Respond to the last user message now with a direct answer via your channel',
+  'reply tool. If you genuinely have nothing to say, reply with `NO_REPLY`.',
+  '',
+  '---',
+].join('\n')
+// Posted to the channel (via the `source:'system'` one-shot bypass) when an
+// empty turn cannot be recovered AND retries are exhausted (or are skipped
+// because the turn thrashed the send path). Replaces the historical silent
+// drop so the human is never left staring at dead air after a degenerate turn.
+export const EMPTY_TURN_FALLBACK_TEXT =
+  "⚠️ I got stuck putting together a reply and couldn't finish. Could you rephrase or try again?"
 // Rolling window for outbound send-rate telemetry. 5s matches Discord's
 // rate-limit shape (5 msg / 5 s / channel) and comfortably covers Slack's
 // 1 msg/s sustained. The window is observational; exceeding the burst
@@ -481,6 +522,14 @@ type LiveSession = {
   // livelock the byte-identical loop-guard misses. Reset at turn start and
   // cleared per-target on a successful delivery to that target.
   policyDeniedToolSendsThisTurn: Map<string, number>
+  // Count of automatic empty-turn re-prompts already spent on the CURRENT
+  // logical turn, bounded by `MAX_EMPTY_TURN_RETRIES`. A "logical turn" spans
+  // the original user batch plus any router-injected retry nudges, so this is
+  // reset only when a real user/reminder batch starts a fresh turn — NOT on the
+  // reminder-only iterations the retry itself queues. `validateChannelTurn`
+  // increments it before injecting EMPTY_TURN_RETRY_NUDGE and reads it to decide
+  // retry-vs-fallback. See the candidate===null branch.
+  emptyTurnRetries: number
   // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
   // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
   // if it matches the just-completed turn, recovery is skipped entirely
@@ -635,6 +684,12 @@ export type ChannelRouter = {
   registerReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
   unregisterReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
   resolveReviewThread: (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
+  // Re-review stranding guard support: answers whether the bot still holds a
+  // blocking CHANGES_REQUESTED on a PR. Opt-in per adapter like the thread
+  // resolver; `getReviewState` answers `unsupported` when none is registered.
+  registerReviewStateResolver: (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver) => void
+  unregisterReviewStateResolver: (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver) => void
+  getReviewState: (req: ReviewStateRequest) => Promise<ReviewStateResult>
   lookupInboundAttachment: (args: ChannelKey & { id: number }) => InboundAttachment | null
   listInboundAttachmentIds: (args: ChannelKey) => readonly number[]
   // Execute a command by name against an existing live session, bypassing
@@ -905,6 +960,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
   const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
   const reviewThreadResolvers = new Map<ChannelKey['adapter'], ReviewThreadResolver>()
+  const reviewStateResolvers = new Map<ChannelKey['adapter'], ReviewStateResolver>()
   const stickyLedger = new StickyLedger()
   // The /help handler reads the live registry to enumerate commands, so it
   // forward-references `commands`. Safe at runtime — the handler only runs on
@@ -1352,6 +1408,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         successfulSendsAtTurnStart: 0,
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
+        emptyTurnRetries: 0,
         skippedTurn: null,
         skipLockedSendTurn: null,
         pendingQuoteCandidate: null,
@@ -1367,6 +1424,30 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+        // A provider soft-error (rate/usage limit, billing, malformed response)
+        // ends the turn with no assistant text, so the human otherwise sees
+        // silence. Surface the REDACTED `safeMessage` (never the raw provider
+        // text, which can carry response bodies / URLs / tokens) via a 'system'
+        // send — the same one-shot bypass path validateChannelTurn uses, so it
+        // lands regardless of per-turn send caps and skips the duplicate guard.
+        void send(
+          {
+            adapter: live.key.adapter,
+            workspace: live.key.workspace,
+            chat: live.key.chat,
+            thread: live.key.thread,
+            text: `⚠️ ${err.safeMessage}`,
+          },
+          { source: 'system' },
+        )
+          .then((result) => {
+            if (!result.ok) {
+              logger.warn(`[channels] ${live.keyId}: provider-error notice send failed: ${result.error}`)
+            }
+          })
+          .catch((sendErr) => {
+            logger.warn(`[channels] ${live.keyId}: provider-error notice send threw: ${describe(sendErr)}`)
+          })
       })
       live.unsubTodoOutcome = created.session.subscribe((event: unknown) => {
         const usage = extractTurnUsage(event)
@@ -1796,6 +1877,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
+          // A real user batch starts a fresh logical turn → restore the full
+          // empty-turn retry budget. Reset here (batch.length > 0) and NOT in
+          // the per-prompt block below, so the reminder-only iterations the
+          // retry itself queues do not refill the budget and loop forever.
+          live.emptyTurnRetries = 0
         } else if (live.lastTurnAuthorId !== null) {
           live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
@@ -2574,6 +2660,26 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     )
   }
 
+  const registerReviewStateResolver = (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver): void => {
+    reviewStateResolvers.set(adapter, resolver)
+  }
+
+  const unregisterReviewStateResolver = (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver): void => {
+    if (reviewStateResolvers.get(adapter) === resolver) {
+      reviewStateResolvers.delete(adapter)
+    }
+  }
+
+  const getReviewState = async (req: ReviewStateRequest): Promise<ReviewStateResult> => {
+    const resolver = reviewStateResolvers.get(req.adapter)
+    if (resolver === undefined) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support review-state lookup`, code: 'unsupported' }
+    }
+    return await resolver(req).catch(
+      (err): ReviewStateResult => ({ ok: false, error: describe(err), code: 'transient' }),
+    )
+  }
+
   const lookupInboundAttachment = (args: ChannelKey & { id: number }): InboundAttachment | null => {
     const live = liveSessions.get(channelKeyId(args))
     if (live === undefined) return null
@@ -2844,15 +2950,64 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
+    const postEmptyTurnFallback = async (cause: string): Promise<void> => {
+      logger.warn(`[channels] ${live.keyId} empty_turn_fallback cause=${cause}`)
+      const result = await send(
+        {
+          adapter: live.key.adapter,
+          workspace: live.key.workspace,
+          chat: live.key.chat,
+          thread: live.key.thread,
+          text: EMPTY_TURN_FALLBACK_TEXT,
+        },
+        { source: 'system' },
+      )
+      if (!result.ok) {
+        logger.warn(`[channels] ${live.keyId}: empty-turn fallback send failed: ${result.error}`)
+      }
+    }
+
     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`)
+      // No recoverable assistant prose: the turn ended with no usable reply.
+      // Two distinct shapes, handled differently (Option B):
+      //
+      //   1. The model THRASHED the send path this turn — it tried to send but
+      //      every attempt was denied (skip-locked, or policy-denied/duplicate/
+      //      cap, tracked on skipLockedSendTurn / policyDeniedToolSendsThisTurn).
+      //      Re-prompting would just re-thrash, so skip retry and post the
+      //      user-facing fallback once.
+      //
+      //   2. The PURE reasoning-loop — no send was ever attempted; the model
+      //      burned its budget thinking and produced nothing (the canonical
+      //      kimi `stopReason: 'length'` / `aborted` degeneration). Re-prompt up
+      //      to MAX_EMPTY_TURN_RETRIES with a neutral nudge; on exhaustion, fall
+      //      back. The nudge is injected as a reminder-only turn so drain()'s
+      //      while-loop re-runs session.prompt() against the same branch.
+      //
+      // The legitimate empty-state case (a TUI-only check before any user
+      // prompt, no inbound this turn) is excluded: no batch means no real turn
+      // to retry or apologize for — keep the historical silent bail there.
+      const attemptedSendThisTurn =
+        live.skipLockedSendTurn === live.turnSeq || live.policyDeniedToolSendsThisTurn.size > 0
+
+      // Only a TRUNCATED assistant leaf (length/error/aborted) from a real
+      // conversational turn is a degeneration worth retrying. A cold/empty turn
+      // (no inbound author, or no assistant message at all) keeps the historical
+      // silent bail — re-prompting it would manufacture replies to nothing.
+      if (live.currentTurnAuthorId === null || !assistantLeafTruncated(live.session)) {
+        logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+        return
+      }
+      if (!attemptedSendThisTurn && live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
+        live.emptyTurnRetries++
+        logger.warn(
+          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES}`,
+        )
+        live.pendingSystemReminders.push(EMPTY_TURN_RETRY_NUDGE)
+        return
+      }
+      await postEmptyTurnFallback(attemptedSendThisTurn ? 'send_thrash' : 'retries_exhausted')
       return
     }
 
@@ -3398,6 +3553,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerReviewThreadResolver,
     unregisterReviewThreadResolver,
     resolveReviewThread,
+    registerReviewStateResolver,
+    unregisterReviewStateResolver,
+    getReviewState,
     lookupInboundAttachment,
     listInboundAttachmentIds,
     executeCommand,
@@ -4109,6 +4267,20 @@ function recoverableAssistantText(
   return null
 }
 
+// True only when the leaf is an assistant message that was CUT OFF mid-output:
+// `length` (hit the token cap — the canonical kimi reasoning-loop), `error`, or
+// `aborted`. This is the precise signature of "the model was producing but got
+// truncated", as distinct from a turn that produced no assistant message at all
+// (leaf undefined / a non-assistant entry), which is a benign empty/cold turn —
+// NOT something to re-prompt. The empty-turn retry guard keys off this so it
+// fires for real degenerations and stays silent for cold sessions.
+function assistantLeafTruncated(session: AgentSession): boolean {
+  const leaf = session.sessionManager.getLeafEntry()
+  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return false
+  const stop = leaf.message.stopReason
+  return stop === 'length' || stop === 'error' || stop === 'aborted'
+}
+
 function visibleAssistantText(message: AssistantMessage): string {
   return message.content
     .filter((block) => block.type === 'text')

package/src/channels/types.ts

@@ -382,6 +382,37 @@ export type ReviewThreadResolveResult =
 // support review threads never register one; the router answers `unsupported`.
 export type ReviewThreadResolver = (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
 
+// A query for "does the bot still owe this PR a verdict?" — i.e. is the bot's
+// latest formal review on the PR a sticky CHANGES_REQUESTED that no later
+// APPROVE/dismissal has cleared. Used by the re-review stranding guard to stop
+// the bot from resolving a thread / posting a close-out ack while it still
+// holds a blocking review (the PR #644 failure: thread resolved + chat ack, but
+// reviewDecision stuck at CHANGES_REQUESTED because neither carries review
+// state). `workspace` is the repo slug `owner/name`; `chat` is `pr:<N>`.
+export type ReviewStateRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+}
+
+// `selfBlocking` is the answer the guard acts on: true means the bot's latest
+// effective formal review is its own CHANGES_REQUESTED (COMMENTED reviews are
+// ignored — they never clear the sticky block, GitHub's own rule). `approve`
+// mirrors `channels.github.review.approve` so the guard's denial text can tell
+// the model whether to land a fresh APPROVE or to DISMISS its prior review.
+//
+// On `ok: false` the caller MUST fail closed: an unverifiable review state is
+// treated like a live block, so the bot never claims close-out when the runtime
+// could not confirm the platform-side verdict.
+export type ReviewStateResult =
+  | { ok: true; selfBlocking: boolean; approve: boolean }
+  | { ok: false; error: string; code?: 'unsupported' | 'not-found' | 'permission-denied' | 'transient' }
+
+// Registered per-adapter on the ChannelRouter, last-write-wins like the
+// review-thread resolver. Adapters that never register one make `getReviewState`
+// answer `unsupported`.
+export type ReviewStateResolver = (req: ReviewStateRequest) => Promise<ReviewStateResult>
+
 export function channelKeyId(key: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
   return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
 }

package/src/inspect/transcript-view.ts

@@ -83,6 +83,7 @@ export function createTranscriptView(opts: TranscriptViewOptions) {
     // transcripts; render per event once live.
     let live = false
     const onEvent = (event: InspectEvent): void => {
+      append(new Text(formatEventTime(event.ts), 0, 0))
       append(componentFor(event))
       if (live) tui.requestRender()
     }
@@ -167,6 +168,15 @@ function compact(payload: unknown): string {
   return s.length > 200 ? `${s.slice(0, 200)}…` : s
 }
 
+function formatEventTime(ts: number): string {
+  if (ts === 0) return colors.dim('--:--:--')
+  const d = new Date(ts)
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  const ss = String(d.getSeconds()).padStart(2, '0')
+  return colors.dim(`${hh}:${mm}:${ss}`)
+}
+
 function header(summary: SessionSummary): string {
   const id = shortSessionId(summary.sessionId)
   const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)

package/src/server/index.ts

@@ -199,8 +199,18 @@ export function safeWsSend(ws: { send: (data: string) => void }, msg: ServerMess
   }
 }
 
+const TIMESTAMPED_SERVER_MESSAGES: ReadonlySet<ServerMessage['type']> = new Set([
+  'text_delta',
+  'tool_start',
+  'tool_end',
+  'done',
+  'error',
+  'prompt_started',
+])
+
 function send(ws: Ws, msg: ServerMessage): boolean {
-  return safeWsSend(ws, msg)
+  const stamped = TIMESTAMPED_SERVER_MESSAGES.has(msg.type) ? { ...msg, ts: Date.now() } : msg
+  return safeWsSend(ws, stamped)
 }
 
 function sendTunnelLog(ws: TunnelLogsWs, msg: TunnelLogsServerMessage): boolean {

package/src/shared/protocol.ts

@@ -202,22 +202,34 @@ export type ClaimErrorPayload = {
   reason: string
 }
 
+// `ts` (ms since epoch) is the server send time, stamped centrally in `send()`,
+// for the variants the TUI renders into scrollback. Optional on the wire so an
+// old CLI parses a new server's frames; control frames the TUI never timestamps
+// (queue_state, doctor, tunnel, claim, command_*) omit it by design.
 export type ServerMessage =
   // serverVersion is optional so an old CLI talking to a new server still
   // parses cleanly. The server impl always emits it; consumers that care
   // about host/agent skew (the TUI command in particular) read it to warn
   // the user when their CLI is on a different version than the container.
   | { type: 'connected'; sessionId: string; serverVersion?: string }
-  | { type: 'text_delta'; delta: string }
-  | { type: 'tool_start'; toolCallId: string; name: string; args: unknown }
-  | { type: 'tool_end'; toolCallId: string; name: string; error: boolean; result: unknown; durationMs: number }
-  | { type: 'done' }
-  | { type: 'error'; message: string }
+  | { type: 'text_delta'; delta: string; ts?: number }
+  | { type: 'tool_start'; toolCallId: string; name: string; args: unknown; ts?: number }
+  | {
+      type: 'tool_end'
+      toolCallId: string
+      name: string
+      error: boolean
+      result: unknown
+      durationMs: number
+      ts?: number
+    }
+  | { type: 'done'; ts?: number }
+  | { type: 'error'; message: string; ts?: number }
   | { type: 'reload_result'; results: ReloadResultPayload[] }
   | { type: 'restart_result'; status: 'accepted' | 'failed'; message?: string; error?: string }
   | { type: 'notification'; payload: unknown; replyTo?: string; meta?: Record<string, string> }
   | { type: 'queue_state'; pending: QueueStateItem[] }
-  | { type: 'prompt_started'; messageId: string; text: string }
+  | { type: 'prompt_started'; messageId: string; text: string; ts?: number }
   | { type: 'doctor_result'; requestId: DoctorRequestId; checks: DoctorCheckPayload[] }
   | { type: 'doctor_fix_result'; requestId: DoctorRequestId; result: DoctorFixPayload }
   | { type: 'cron_list_result'; requestId: CronListRequestId; result: CronListResultPayload }

package/src/tui/format.ts

@@ -24,6 +24,19 @@ export function formatUserPromptHistory(text: string): string {
     .join('\n')
 }
 
+export function formatTimestamp(ts: number | undefined): string {
+  if (ts === undefined || ts === 0) return colors.dim('--:--:--')
+  const d = new Date(ts)
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  const ss = String(d.getSeconds()).padStart(2, '0')
+  return colors.dim(`${hh}:${mm}:${ss}`)
+}
+
+export function withTimestamp(ts: number | undefined, body: string): string {
+  return `${formatTimestamp(ts)} ${body}`
+}
+
 function stripHiddenBlocks(text: string): string {
   return text.replace(/<hatching>[\s\S]*?<\/hatching>\s*/g, '').trimStart()
 }

package/src/tui/index.ts

@@ -3,7 +3,14 @@ import { Editor, Key, Markdown, matchesKey, ProcessTerminal, type Terminal, Text
 import { parseCommand } from '@/commands'
 
 import { createClient as createClientDefault, type Client } from './client'
-import { formatQueuePanel, formatToolEnd, formatToolStart, formatUserPromptHistory } from './format'
+import {
+  formatQueuePanel,
+  formatTimestamp,
+  formatToolEnd,
+  formatToolStart,
+  formatUserPromptHistory,
+  withTimestamp,
+} from './format'
 import { colors, editorTheme, markdownTheme } from './theme'
 
 export type ClientFactory = (url: string) => Promise<Client>
@@ -173,8 +180,13 @@ export function createTui({
       onReplyDone = null
     }
 
-    const ensureAssistantBlock = (): Markdown => {
+    // A Markdown block can't carry an ANSI timestamp prefix (it'd be parsed as
+    // markdown), so the assistant turn's timestamp is a separate dim Text line
+    // emitted just above the block when it's first created — stamped with the
+    // first delta's server `ts`.
+    const ensureAssistantBlock = (ts: number | undefined): Markdown => {
       if (currentAssistant) return currentAssistant
+      appendHistory(new Text(formatTimestamp(ts), 0, 0))
       const md = new Markdown('', 0, 0, markdownTheme)
       currentAssistant = md
       currentAssistantText = ''
@@ -185,12 +197,12 @@ export function createTui({
     client.onMessage((msg) => {
       switch (msg.type) {
         case 'prompt_started': {
-          appendHistory(new Text(formatUserPromptHistory(msg.text), 0, 0))
+          appendHistory(new Text(withTimestamp(msg.ts, formatUserPromptHistory(msg.text)), 0, 0))
           tui.requestRender()
           break
         }
         case 'text_delta': {
-          const block = ensureAssistantBlock()
+          const block = ensureAssistantBlock(msg.ts)
           currentAssistantText += msg.delta
           block.setText(currentAssistantText)
           tui.requestRender()
@@ -198,13 +210,15 @@ export function createTui({
         }
         case 'tool_start': {
           sealAssistantBlock()
-          appendHistory(new Text(formatToolStart(msg.name, msg.args), 0, 0))
+          appendHistory(new Text(withTimestamp(msg.ts, formatToolStart(msg.name, msg.args)), 0, 0))
           tui.requestRender()
           break
         }
         case 'tool_end': {
           sealAssistantBlock()
-          appendHistory(new Text(formatToolEnd(msg.name, msg.error, msg.result, msg.durationMs), 0, 0))
+          appendHistory(
+            new Text(withTimestamp(msg.ts, formatToolEnd(msg.name, msg.error, msg.result, msg.durationMs)), 0, 0),
+          )
           tui.requestRender()
           break
         }
@@ -214,7 +228,7 @@ export function createTui({
           break
         }
         case 'error': {
-          appendHistory(new Text(colors.red(`error: ${msg.message}`), 0, 0))
+          appendHistory(new Text(withTimestamp(msg.ts, colors.red(`error: ${msg.message}`)), 0, 0))
           finishAssistantTurn()
           tui.requestRender()
           break