switchroom 0.19.40 → 0.19.41

package/telegram-plugin/gateway/checklist-fallback.ts

@@ -0,0 +1,370 @@
+/**
+ * Checklist send/update with graceful degradation.
+ *
+ * Telegram's native `sendChecklist` / `editMessageChecklist` (Bot API 9.1)
+ * are **Business-account-only**: both REQUIRE a `business_connection_id`,
+ * and the payload nests `title`/`tasks` inside a single `checklist` object
+ * (`InputChecklist`) whose tasks each carry a REQUIRED integer `id` and NO
+ * completion flag (`InputChecklistTask = { id, text }` — a native checklist
+ * cannot be pre-marked done). The original wrapper sent a FLAT
+ * `{ chat_id, title, tasks: [{ text, is_completed? }] }` payload, which
+ * Telegram rejected with `400: parameter "checklist" is required` — and even
+ * a well-formed payload fails for ordinary bot DMs/groups (no business
+ * connection), which is every chat this fleet uses.
+ *
+ * So the tool degrades gracefully instead of surfacing a raw 400:
+ *   1. If a business connection id is configured AND the Bot API supports
+ *      checklists → build the CORRECT native payload and send natively.
+ *   2. Otherwise (the normal case) → render the checklist as a formatted
+ *      text message (bold title + ✅/⬜ task lines — text CAN show the
+ *      `done` flag) and send via the normal message path. The tool result
+ *      carries `degraded: "text"` so the caller knows it is not interactive.
+ *   3. A failed native attempt falls back to text rather than erroring.
+ *
+ * Updates work against a per-message in-memory state store (the gateway has
+ * no other record of a text-rendered checklist's tasks): a patch is applied
+ * to the stored state and the message is edited (natively or as text to
+ * match how it was sent). State is process-local — after a gateway restart
+ * an update to a pre-restart checklist returns a graceful
+ * `unknown_checklist` result unless the patch itself carries a full
+ * replacement (title + all task texts), never a raw Telegram error.
+ *
+ * Pure/deps-injected so the orchestration is unit-testable without a bot
+ * (same pattern as checklist-message-handler.ts).
+ */
+
+export interface ChecklistTaskState {
+  /** 1-based sequential id assigned at send time (mirrors the native API's
+   *  required per-task integer id; doubles as the patch handle in text mode). */
+  id: number
+  text: string
+  done: boolean
+}
+
+export interface ChecklistState {
+  title: string
+  tasks: ChecklistTaskState[]
+  /** How the message was actually delivered — updates must match it. */
+  mode: 'native' | 'text'
+}
+
+export interface ChecklistPatchTask {
+  id?: string | number
+  text?: string
+  done?: boolean
+}
+
+export interface ChecklistPatch {
+  title?: string
+  tasks?: ChecklistPatchTask[]
+}
+
+export const CHECKLIST_MAX_TASKS = 30
+
+/** Assign sequential 1-based ids and normalize the `done` flag. */
+export function buildChecklistTasks(
+  tasks: ReadonlyArray<{ text: string; done?: boolean }>,
+): ChecklistTaskState[] {
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return tasks.map((t, i) => ({ id: i + 1, text: t.text, done: t.done === true }))
+}
+
+/**
+ * Render a checklist as a text message: title header + one ✅/⬜ line per
+ * task. Rich (default) output is GFM markdown for `richMessage()`; pass
+ * `literal: true` when the access config pins `parseMode: 'text'` (plain
+ * sends, no markdown parsing) so the title doesn't ship raw asterisks.
+ */
+export function renderChecklistText(
+  cl: { title: string; tasks: ReadonlyArray<{ text: string; done: boolean }> },
+  opts?: { literal?: boolean },
+): string {
+  const header = opts?.literal ? cl.title : `**${cl.title}**`
+  const lines = cl.tasks.map((t) => `${t.done ? '✅' : '⬜'} ${t.text}`)
+  return [header, ...lines].join('\n')
+}
+
+/**
+ * Apply an update_checklist patch: `title` replaces the title; a task with
+ * an `id` matching an existing task updates its text/done in place; a task
+ * without an `id` (or with an unknown id) is appended. Returns a NEW state
+ * (input untouched). Removal is not supported by the patch shape.
+ */
+export function applyChecklistPatch(
+  cl: { title: string; tasks: ReadonlyArray<ChecklistTaskState> },
+  patch: ChecklistPatch,
+): { title: string; tasks: ChecklistTaskState[] } {
+  const tasks = cl.tasks.map((t) => ({ ...t }))
+  for (const p of patch.tasks ?? []) {
+    const pid = p.id != null ? Number(p.id) : undefined
+    const existing = pid != null ? tasks.find((t) => t.id === pid) : undefined
+    if (existing) {
+      if (p.text != null) existing.text = p.text
+      if (p.done != null) existing.done = p.done
+    } else {
+      const nextId = pid != null && Number.isFinite(pid)
+        ? pid
+        : tasks.reduce((m, t) => Math.max(m, t.id), 0) + 1
+      tasks.push({ id: nextId, text: p.text ?? '', done: p.done === true })
+    }
+  }
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return { title: patch.title ?? cl.title, tasks }
+}
+
+/**
+ * Build a CORRECT native `sendChecklist` payload per Bot API 9.1:
+ * `business_connection_id` is required, `title`/`tasks` nest inside a single
+ * `checklist` object (`InputChecklist`), each task carries its integer `id`,
+ * and there is NO completion field (`InputChecklistTask` has none).
+ */
+export function buildNativeChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+  replyToMessageId?: number
+  protectContent?: boolean
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+    ...(p.replyToMessageId != null ? { reply_parameters: { message_id: p.replyToMessageId } } : {}),
+    ...(p.protectContent === true ? { protect_content: true } : {}),
+  }
+}
+
+/**
+ * Build a native `editMessageChecklist` payload. The native edit REPLACES
+ * the whole checklist, so the FULL post-patch state is sent; reusing the
+ * stored task ids preserves user tick state for unchanged tasks.
+ */
+export function buildNativeEditChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  messageId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    message_id: p.messageId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+  }
+}
+
+/** Bounded per-message checklist state store (insertion-order eviction). */
+export interface ChecklistStore {
+  get(key: string): ChecklistState | undefined
+  set(key: string, state: ChecklistState): void
+}
+
+export function createChecklistStore(cap = 500): ChecklistStore {
+  const map = new Map<string, ChecklistState>()
+  return {
+    get: (key) => map.get(key),
+    set: (key, state) => {
+      if (map.has(key)) map.delete(key) // refresh insertion order
+      map.set(key, state)
+      while (map.size > cap) {
+        const oldest = map.keys().next().value as string | undefined
+        if (oldest == null) break
+        map.delete(oldest)
+      }
+    },
+  }
+}
+
+export function checklistStoreKey(chatId: string, messageId: string | number): string {
+  return `${chatId}:${messageId}`
+}
+
+// ─── Orchestration (deps-injected, unit-testable) ─────────────────────────
+
+export interface SendChecklistDeps {
+  /** Business connection id, when the operator has one configured. Native
+   *  checklists are impossible without it (required API parameter). */
+  businessConnectionId: string | undefined
+  /** Boot-probe result: the connected grammY/Bot API exposes sendChecklist. */
+  nativeAvailable: boolean
+  sendNative: (payload: Record<string, unknown>) => Promise<{ message_id: number }>
+  sendText: (text: string) => Promise<{ message_id: number }>
+  /** access.parseMode === 'text' — render without markdown. */
+  literalText: boolean
+  log: (line: string) => void
+}
+
+export interface SendChecklistResult {
+  message_id: number
+  mode: 'native' | 'text'
+  state: ChecklistState
+}
+
+/**
+ * Send a checklist: natively when possible, degrading to a formatted text
+ * message otherwise. NEVER lets a native-send failure escape — the fallback
+ * is the text render. (A text-send failure still throws: there is nothing
+ * further to degrade to, and the caller's normal error path applies.)
+ */
+export async function performSendChecklist(
+  deps: SendChecklistDeps,
+  args: {
+    title: string
+    tasks: ReadonlyArray<{ text: string; done?: boolean }>
+    chatId: number
+    replyToMessageId?: number
+    protectContent?: boolean
+  },
+): Promise<SendChecklistResult> {
+  const tasks = buildChecklistTasks(args.tasks)
+  if (deps.nativeAvailable && deps.businessConnectionId) {
+    try {
+      const sent = await deps.sendNative(buildNativeChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: args.chatId,
+        title: args.title,
+        tasks,
+        replyToMessageId: args.replyToMessageId,
+        protectContent: args.protectContent,
+      }))
+      return {
+        message_id: sent.message_id,
+        mode: 'native',
+        state: { title: args.title, tasks, mode: 'native' },
+      }
+    } catch (err) {
+      deps.log(`native sendChecklist failed — falling back to text render: ${err}\n`)
+    }
+  }
+  const text = renderChecklistText({ title: args.title, tasks }, { literal: deps.literalText })
+  const sent = await deps.sendText(text)
+  return {
+    message_id: sent.message_id,
+    mode: 'text',
+    state: { title: args.title, tasks, mode: 'text' },
+  }
+}
+
+/** Tool-result text for send_checklist. The degraded shape carries
+ *  `degraded: "text"` + a note so the calling agent knows the checklist is a
+ *  formatted message, not a natively tickable one. */
+export function sendChecklistToolText(r: SendChecklistResult): string {
+  return JSON.stringify(
+    r.mode === 'native'
+      ? { ok: true, message_id: r.message_id, mode: 'native' }
+      : {
+          ok: true,
+          message_id: r.message_id,
+          mode: 'text',
+          degraded: 'text',
+          note: 'rendered as a formatted text message (native Telegram checklists require a Business connection) — tasks are not tappable; use update_checklist with task ids 1..N to tick them',
+        },
+  )
+}
+
+export interface UpdateChecklistDeps {
+  /** Stored state for this chat:message, if the gateway still has it. */
+  state: ChecklistState | undefined
+  businessConnectionId: string | undefined
+  nativeAvailable: boolean
+  editNative: (payload: Record<string, unknown>) => Promise<void>
+  editText: (text: string) => Promise<void>
+  literalText: boolean
+  log: (line: string) => void
+  chatId: number
+  messageId: number
+}
+
+export type UpdateChecklistResult =
+  | { ok: true; mode: 'native' | 'text'; state: ChecklistState }
+  | { ok: false; reason: 'unknown_checklist' | 'edit_failed'; hint: string }
+
+/**
+ * Update a checklist message. Applies the patch to the stored state and
+ * re-renders in the mode the message was originally sent in. Failures come
+ * back as structured `{ ok: false, reason, hint }` results — never a raw
+ * Telegram error thrown at the caller.
+ */
+export async function performUpdateChecklist(
+  deps: UpdateChecklistDeps,
+  patch: ChecklistPatch,
+): Promise<UpdateChecklistResult> {
+  let base = deps.state
+  if (!base) {
+    // State lost (gateway restart / evicted). If the patch is a full
+    // replacement — a title plus tasks that all carry text — we can rebuild
+    // and edit as text (the fleet-normal mode). Otherwise we cannot know
+    // the existing tasks; degrade gracefully.
+    const fullReplacement =
+      patch.title != null &&
+      (patch.tasks?.length ?? 0) > 0 &&
+      (patch.tasks ?? []).every((t) => t.text != null)
+    if (!fullReplacement) {
+      return {
+        ok: false,
+        reason: 'unknown_checklist',
+        hint: 'no stored state for this checklist (gateway restarted?). Re-send it with send_checklist, or pass a full replacement (title + every task\'s text) to update_checklist.',
+      }
+    }
+    base = { title: patch.title!, tasks: [], mode: 'text' }
+  }
+  let next: { title: string; tasks: ChecklistTaskState[] }
+  try {
+    next = applyChecklistPatch(base, patch)
+  } catch (err) {
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+  const state: ChecklistState = { title: next.title, tasks: next.tasks, mode: base.mode }
+  if (base.mode === 'native') {
+    // A native checklist message cannot be edited into plain text — there is
+    // no text fallback here; a failure surfaces as a structured result.
+    if (!deps.nativeAvailable || !deps.businessConnectionId) {
+      return {
+        ok: false,
+        reason: 'edit_failed',
+        hint: 'this checklist was sent natively but the business connection / checklist API is no longer available.',
+      }
+    }
+    try {
+      await deps.editNative(buildNativeEditChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: deps.chatId,
+        messageId: deps.messageId,
+        title: state.title,
+        tasks: state.tasks,
+      }))
+      return { ok: true, mode: 'native', state }
+    } catch (err) {
+      deps.log(`native editMessageChecklist failed: ${err}\n`)
+      return { ok: false, reason: 'edit_failed', hint: String(err) }
+    }
+  }
+  try {
+    await deps.editText(renderChecklistText(state, { literal: deps.literalText }))
+    return { ok: true, mode: 'text', state }
+  } catch (err) {
+    deps.log(`checklist text edit failed: ${err}\n`)
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+}
+
+/** Tool-result text for update_checklist — structured for both outcomes. */
+export function updateChecklistToolText(r: UpdateChecklistResult, messageId: number): string {
+  return JSON.stringify(
+    r.ok
+      ? { ok: true, message_id: messageId, mode: r.mode, ...(r.mode === 'text' ? { degraded: 'text' } : {}) }
+      : { ok: false, reason: r.reason, hint: r.hint },
+  )
+}

package/telegram-plugin/gateway/gateway.ts

@@ -35,6 +35,7 @@ import {
   type AskUserOutcome,
 } from '../ask-user.js'
 import { redactAskUserFields, redactChecklistFields } from '../outbound-field-redact.js'
+import { createChecklistStore, checklistStoreKey, performSendChecklist, performUpdateChecklist, sendChecklistToolText, updateChecklistToolText } from './checklist-fallback.js'
 import { parseInterruptMarker } from '../interrupt-marker.js'
 import {
   ToolFlightTracker,
@@ -1383,65 +1384,29 @@ let _rawEditMessageChecklist: unknown
 /** True when the connected Telegram Bot API supports native checklists. Set in initGatewayBot() (#2996 P0b). */
 let CHECKLIST_API_AVAILABLE = false
 
-/**
- * Send a native Telegram checklist message.
- * Wraps bot.api.raw.sendChecklist with string→number coercion (chat_id) and
- * a 30-task cap enforced before the API call.
- */
-async function rawSendChecklist(args: {
-  chat_id: string
-  title: string
-  tasks: Array<{ text: string; done?: boolean }>
-  message_thread_id?: number
-  reply_to_message_id?: number
-  protect_content?: boolean
-}): Promise<{ message_id: number }> {
-  if (!CHECKLIST_API_AVAILABLE) {
-    throw new Error('sendChecklist is not available in this grammY/Telegram Bot API version')
-  }
-  const MAX_TASKS = 30
-  if (args.tasks.length > MAX_TASKS) {
-    throw new Error(`checklist exceeds ${MAX_TASKS}-task limit (got ${args.tasks.length})`)
-  }
-  const result = await (_rawSendChecklist as (p: Record<string, unknown>) => Promise<{ message_id: number }>)({
-    chat_id: Number(args.chat_id),
-    title: args.title,
-    tasks: args.tasks.map(t => ({ text: t.text, ...(t.done != null ? { is_completed: t.done } : {}) })),
-    ...(args.message_thread_id != null ? { message_thread_id: args.message_thread_id } : {}),
-    ...(args.reply_to_message_id != null ? { reply_to_message_id: args.reply_to_message_id } : {}),
-    ...(args.protect_content === true ? { protect_content: true } : {}),
-  })
+/** bot.api.raw.sendChecklist with a payload pre-built by checklist-fallback.ts
+ *  (nested `checklist` object, per-task integer ids, business_connection_id —
+ *  the old flat shape got `400: parameter "checklist" is required`). */
+async function rawSendChecklist(payload: Record<string, unknown>): Promise<{ message_id: number }> {
+  if (!CHECKLIST_API_AVAILABLE) throw new Error('sendChecklist is not available in this grammY/Telegram Bot API version')
+  const result = await (_rawSendChecklist as (p: Record<string, unknown>) => Promise<{ message_id: number }>)(payload)
   return { message_id: result.message_id }
 }
 
-/**
- * Edit (patch) an existing Telegram checklist message.
- * Supports updating title, adding/removing tasks, and marking tasks done/undone.
- * Task objects with an `id` field target existing tasks; those without are added.
- */
-async function rawEditMessageChecklist(args: {
-  chat_id: string
-  message_id: string
-  title?: string
-  tasks?: Array<{ id?: string; text?: string; done?: boolean }>
-}): Promise<void> {
-  if (!CHECKLIST_API_AVAILABLE) {
-    throw new Error('editMessageChecklist is not available in this grammY/Telegram Bot API version')
-  }
-  await (_rawEditMessageChecklist as (p: Record<string, unknown>) => Promise<unknown>)({
-    chat_id: Number(args.chat_id),
-    message_id: Number(args.message_id),
-    ...(args.title != null ? { title: args.title } : {}),
-    ...(args.tasks != null
-      ? {
-          tasks: args.tasks.map(t => ({
-            ...(t.id != null ? { id: Number(t.id) } : {}),
-            ...(t.text != null ? { text: t.text } : {}),
-            ...(t.done != null ? { is_completed: t.done } : {}),
-          })),
-        }
-      : {}),
-  })
+/** bot.api.raw.editMessageChecklist with a pre-built payload (the native edit REPLACES the whole checklist, so checklist-fallback.ts sends full state). */
+async function rawEditMessageChecklist(payload: Record<string, unknown>): Promise<void> {
+  if (!CHECKLIST_API_AVAILABLE) throw new Error('editMessageChecklist is not available in this grammY/Telegram Bot API version')
+  await (_rawEditMessageChecklist as (p: Record<string, unknown>) => Promise<unknown>)(payload)
+}
+
+/** Per-message checklist state — update_checklist re-renders from it (process-local; post-restart updates degrade gracefully). */
+const checklistStore = createChecklistStore()
+
+/** Native checklists are Telegram-Business-only (sendChecklist REQUIRES a business_connection_id).
+ *  No fleet config plumbing exists yet; this env var is the opt-in — unset (the normal case) means text fallback. */
+function resolveBusinessConnectionId(): string | undefined {
+  const v = process.env.SWITCHROOM_TELEGRAM_BUSINESS_CONNECTION_ID?.trim()
+  return v ? v : undefined
 }
 
 const chatLock = createChatLock()
@@ -5038,7 +5003,7 @@ function emitTurnRecord(turn: CurrentTurn, endedAt: number): void {
             startedAt: turn.startedAt,
             toolCallCount: turn.toolCallCount ?? 0,
             turnId: turn.turnId,
-            finalAnswerDelivered: turn.finalAnswerDelivered,
+            finalAnswerDelivered: turn.finalAnswerDelivered, replyCalled: turn.replyCalled, // replyCalled: honest delivery-route signal (turn-record-status.ts computeTurnRoute)
             deliveryOutcome: turn.deliveryOutcome, landedUnconfirmed: turn.landedUnconfirmed,
           },
           endedAt,
@@ -12083,17 +12048,35 @@ async function executeSendChecklist(args: Record<string, unknown>): Promise<{ co
     (t) => redactOutboundText(t, 'send_checklist'),
   )
 
-  const sent = await rawSendChecklist({
-    chat_id,
-    title: redactedTitle!,
-    tasks: redactedTasks!,
+  // Graceful degradation: native sendChecklist is Business-account-only, so
+  // ordinary chats (the fleet norm) get a formatted text render instead of a
+  // raw Telegram 400 (rationale + orchestration in checklist-fallback.ts).
+  const literal = (loadAccess().parseMode ?? 'html') === 'text'
+  const sendOpts = {
     ...(threadId != null ? { message_thread_id: threadId } : {}),
-    ...(replyTo != null ? { reply_to_message_id: replyTo } : {}),
+    ...(replyTo != null ? { reply_parameters: { message_id: replyTo } } : {}),
     ...(protectContent ? { protect_content: true } : {}),
-  })
+  }
+  const result = await performSendChecklist({
+    businessConnectionId: resolveBusinessConnectionId(),
+    nativeAvailable: CHECKLIST_API_AVAILABLE,
+    sendNative: rawSendChecklist,
+    sendText: (text) => robustApiCall(
+      (): Promise<{ message_id: number }> =>
+        literal
+          // allow-raw-bot-api: literal checklist text-fallback send routed through robustApiCall
+          ? lockedBot.api.sendMessage(chat_id, text, sendOpts as never)
+          // allow-raw-bot-api: checklist text-fallback send routed through robustApiCall
+          : lockedBot.api.sendRichMessage(chat_id, richMessage(text), sendOpts as never),
+      { verb: 'sendMessage', chat_id, threadId },
+    ),
+    literalText: literal,
+    log: (l) => process.stderr.write(`telegram gateway: ${l}`),
+  }, { title: redactedTitle!, tasks: redactedTasks!, chatId: Number(chat_id), replyToMessageId: replyTo, protectContent })
 
-  process.stderr.write(`telegram gateway: send_checklist: sent chatId=${chat_id} messageId=${sent.message_id} tasks=${tasks.length}\n`)
-  return { content: [{ type: 'text', text: `checklist sent (id: ${sent.message_id})` }] }
+  checklistStore.set(checklistStoreKey(chat_id, result.message_id), result.state)
+  process.stderr.write(`telegram gateway: send_checklist: sent chatId=${chat_id} messageId=${result.message_id} tasks=${tasks.length} mode=${result.mode}\n`)
+  return { content: [{ type: 'text', text: sendChecklistToolText(result) }] }
 }
 
 /**
@@ -12180,10 +12163,27 @@ async function executeUpdateChecklist(args: Record<string, unknown>): Promise<{
     (t) => redactOutboundText(t, 'update_checklist'),
   )
 
-  await rawEditMessageChecklist({ chat_id, message_id, title: redactedTitle, tasks: redactedTasks })
-
-  process.stderr.write(`telegram gateway: update_checklist: updated chatId=${chat_id} messageId=${message_id}\n`)
-  return { content: [{ type: 'text', text: `checklist updated (id: ${message_id})` }] }
+  // Graceful degradation (checklist-fallback.ts): the patch is applied to the
+  // stored per-message state and the message re-rendered in the mode it was
+  // sent in. Failures come back structured, never as a raw Telegram 400.
+  const literal = (loadAccess().parseMode ?? 'html') === 'text'
+  const key = checklistStoreKey(chat_id, message_id)
+  const result = await performUpdateChecklist({
+    state: checklistStore.get(key),
+    businessConnectionId: resolveBusinessConnectionId(),
+    nativeAvailable: CHECKLIST_API_AVAILABLE,
+    editNative: rawEditMessageChecklist,
+    // allow-raw-bot-api: checklist text-fallback edit routed through robustApiCall
+    editText: async (text) => { await robustApiCall(() => lockedBot.api.editMessageText(chat_id, Number(message_id), literal ? text : richMessage(text))) },
+    literalText: literal,
+    log: (l) => process.stderr.write(`telegram gateway: ${l}`),
+    chatId: Number(chat_id),
+    messageId: Number(message_id),
+  }, { title: redactedTitle, tasks: redactedTasks })
+
+  if (result.ok) checklistStore.set(key, result.state)
+  process.stderr.write(`telegram gateway: update_checklist: ${result.ok ? `updated mode=${result.mode}` : `failed reason=${result.reason}`} chatId=${chat_id} messageId=${message_id}\n`)
+  return { content: [{ type: 'text', text: updateChecklistToolText(result, Number(message_id)) }] }
 }
 
 /**

package/telegram-plugin/gateway/turn-record-status.ts

@@ -27,6 +27,38 @@ export type DeliveryOutcome = 'delivered' | 'failed' | 'suppressed'
 /** The status strings written to turns.jsonl. `send_failed` is new in PR B. */
 export type TurnStatus = 'complete' | 'no_reply' | 'send_failed'
 
+/**
+ * How this turn's answer actually reached (or failed to reach) the user — the
+ * honest delivery route, recorded alongside `status` so the fleet-health
+ * detector can tell a flush-recovered turn apart from a genuine silent no-op.
+ *
+ * - `reply`  — the reply tool delivered the answer (the normal path), OR the
+ *              flush short-circuited because reply had already delivered.
+ * - `stream` — the answer landed via the streaming/draft path without a reply
+ *              tool call (final answer delivered, `replyCalled` false).
+ * - `flush`  — a turn-flush / outbox-sweep backstop delivered the answer after
+ *              the reply tool was bypassed (terminal prose, `tools:0`). This is
+ *              the case that used to masquerade as a silent no-op.
+ * - `none`   — nothing reached the user (send failed, or a genuine no-reply).
+ */
+export type TurnRoute = 'reply' | 'stream' | 'flush' | 'none'
+
+/**
+ * Epoch of when the honest `route` field shipped on turns.jsonl rows — a FIXED
+ * literal cutoff the fleet-health detector uses to age out the pre-route legacy
+ * backlog (rows written before this field existed carry no `route`, so the
+ * detector cannot classify them and must not escalate them as silent no-ops).
+ *
+ * UNIX SECONDS, not milliseconds: turns.jsonl `ts` is written as
+ * `Math.floor(endedAt / 1000)` (see `buildTurnRecord`), and the detector
+ * compares this constant against that seconds-valued `ts`. It intentionally
+ * mirrors the units of `SILENT_NOOP_FLOOR_TS` in `src/fleet-health/detect.ts`.
+ *
+ * Value = 2026-07-31T00:00:00Z (`date -u -d @1785456000`). Fixed, not rolling:
+ * a rolling window would hide a genuine ongoing regression that drops the field.
+ */
+export const ROUTE_FIELD_SHIP_TS = 1_785_456_000
+
 /**
  * Derive the recorded turn status from the turn's flags.
  *
@@ -58,6 +90,41 @@ export function computeTurnStatus(turn: {
   }
 }
 
+/**
+ * Derive the honest delivery `route` from the SAME resolved delivery state
+ * `computeTurnStatus` reads — never speculative. `deliveryOutcome` (when
+ * present) is authoritative; when absent we fall back to the legacy
+ * `finalAnswerDelivered` / `replyCalled` reading, exactly as `computeTurnStatus`
+ * does for `status`.
+ *
+ *   failed              → none    (nothing reached the user)
+ *   delivered           → flush   (a backstop send delivered the answer)
+ *   suppressed          → reply   (flush short-circuited; reply already delivered)
+ *   undefined (legacy)  → finalAnswerDelivered
+ *                            ? (replyCalled ? reply : stream)
+ *                            : none
+ */
+export function computeTurnRoute(turn: {
+  finalAnswerDelivered: boolean
+  replyCalled: boolean
+  deliveryOutcome?: DeliveryOutcome
+}): TurnRoute {
+  switch (turn.deliveryOutcome) {
+    case 'failed':
+      return 'none'
+    case 'delivered':
+      return 'flush'
+    case 'suppressed':
+      return 'reply'
+    default:
+      return turn.finalAnswerDelivered
+        ? turn.replyCalled
+          ? 'reply'
+          : 'stream'
+        : 'none'
+  }
+}
+
 /**
  * Resolve a backstop send's outcome from what actually happened on the wire.
  * A throw is a failure; a no-throw send that delivered fewer chunks than it
@@ -148,6 +215,13 @@ export interface TurnRecordRow {
   tools: number
   status: TurnStatus
   turn_id: string
+  /**
+   * The honest delivery route for this turn (see `TurnRoute`). Recorded on every
+   * row so the fleet-health detector can distinguish a flush-recovered turn
+   * (`route: 'flush'`, answer delivered by a backstop after the reply tool was
+   * bypassed) from a genuine silent no-op (`route: 'none'`). Always emitted.
+   */
+  route: TurnRoute
   /**
    * How many landed message ids of this turn's backstop delivery the read-back
    * probe never corroborated (`sentIds` minus the confirmed subset). OMITTED
@@ -178,6 +252,7 @@ export function buildTurnRecord(
     toolCallCount: number
     turnId: string
     finalAnswerDelivered: boolean
+    replyCalled?: boolean
     deliveryOutcome?: DeliveryOutcome
     landedUnconfirmed?: number
   },
@@ -190,6 +265,11 @@ export function buildTurnRecord(
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,
+    route: computeTurnRoute({
+      finalAnswerDelivered: turn.finalAnswerDelivered,
+      replyCalled: turn.replyCalled ?? false,
+      deliveryOutcome: turn.deliveryOutcome,
+    }),
     // Emitted ONLY when non-zero (see `TurnRecordRow.landed_unconfirmed`).
     ...(turn.landedUnconfirmed != null && turn.landedUnconfirmed > 0
       ? { landed_unconfirmed: turn.landedUnconfirmed }