typeclaw 0.28.0 → 0.28.2

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,
@@ -1365,8 +1422,44 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         unsubTypingActivity: null,
         unsubTodoOutcome: null,
       }
+      // Tracks the `turnSeq` a provider-error notice was last POSTED for, so the
+      // channel surfaces at most one notice per turn. The upstream SDK retries
+      // internally, and each retry emits its own `message_end` with
+      // `stopReason: 'error'` — without this gate a single failing turn posts N
+      // identical "⚠️ upstream provider failed" notices (one per retry). Logs
+      // still record every attempt; only the user-facing notice is deduped.
+      let lastProviderErrorNoticeTurn: number | undefined
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+        // Suppress duplicate notices for the SAME turn (retry storm). Set the
+        // marker BEFORE the async send so a synchronous burst of retry events
+        // can't each slip past the check and enqueue their own notice.
+        if (lastProviderErrorNoticeTurn === live.turnSeq) return
+        lastProviderErrorNoticeTurn = live.turnSeq
+        // 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 +1889,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 +2672,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 +2962,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 +3565,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerReviewThreadResolver,
     unregisterReviewThreadResolver,
     resolveReviewThread,
+    registerReviewStateResolver,
+    unregisterReviewStateResolver,
+    getReviewState,
     lookupInboundAttachment,
     listInboundAttachmentIds,
     executeCommand,
@@ -4109,6 +4279,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/schema.ts

@@ -192,8 +192,9 @@ export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
 // prefix is implied by this field living under the review config); `off` is the
 // disable sentinel, matching the `engagement.stickiness: 'off'` convention:
 //   - 'review_requested' — review only when the bot is requested (default)
-//   - 'opened'           — review every non-draft PR as soon as it opens; draft
-//                          PRs are skipped until an explicit review_requested
+//   - 'opened'           — review every non-draft PR as soon as it opens; a draft
+//                          PR wakes no session and is reviewed once it turns ready
+//                          (ready_for_review) or the bot is explicitly requested
 //   - 'off'              — disable code review entirely
 export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
 

package/src/channels/types.ts

@@ -382,6 +382,42 @@ 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 for re-reviews: 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).
+// `reviewDecision` is GitHub's aggregate PR review status when GraphQL can
+// provide it; REVIEW_REQUIRED means an approval-shaped flat comment would still
+// leave the PR awaiting a formal review. `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; reviewDecision?: GithubReviewDecision }
+  | { ok: false; error: string; code?: 'unsupported' | 'not-found' | 'permission-denied' | 'transient' }
+
+export type GithubReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED'
+
+// 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/skills/typeclaw-channel-github/SKILL.md

@@ -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). **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`.)
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **Post the `<summary>` verbatim — do not pad it back into a play-by-play.** The reviewer's contract already makes the summary a terse, author-facing verdict justification (no process narration, no "I loaded the X skill", no recap of what the PR does); your job is to forward it, not re-expand it. **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.
 

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