switchroom 0.18.3 → 0.18.6

package/telegram-plugin/gateway/resolve-person.ts

@@ -0,0 +1,304 @@
+/**
+ * Boot-time-only, chat-scoped resolution of a raw Telegram id/username into
+ * a human `person_id` (e.g. "Lisa") for display in the `<channel>` tag's
+ * `user` attribute.
+ *
+ * Design (converged after adversarial review — see the PR description for
+ * the tradeoffs, do not re-litigate here):
+ *
+ *   - No MCP tool. Not callable by agents — display-only, gateway-internal.
+ *   - No hot-reload. `PersonDirectory` is built ONCE at gateway boot from
+ *     the static in-memory `people.json` the scaffold projected from
+ *     `switchroom.yaml`'s `users:` block. A config change requires an agent
+ *     restart to take effect — this file never re-reads anything.
+ *   - `access.json` (the fail-CLOSED allow-list) is a completely separate
+ *     concern and is never touched here. This feature is fail-OPEN: an
+ *     unresolved id/username falls back to today's behavior (the caller
+ *     keeps using the raw id/username) — it never blocks or denies
+ *     anything.
+ *   - Chat-scoped: a resolved name is only ever returned for a chat/group
+ *     the person is actually a member of. In a DM the chat IS the sender,
+ *     so resolution always applies. In a group, resolution only applies if
+ *     the sender's id or username is explicitly present in that group's
+ *     `allowFrom` (read from the EXISTING `access.json`/`loadAccess()`
+ *     data — no new membership source). An empty/unset group `allowFrom`
+ *     means membership can't be positively confirmed, so we conservatively
+ *     do NOT resolve (the raw id/username is shown instead) — a name safe
+ *     in a 1:1 DM could be a bigger leak in a shared group.
+ *   - Per-entry validation: a malformed `users:` entry (duplicate
+ *     `person_id` claimed by two different keys, empty/invalid
+ *     `person_id`, no `telegram_ids`) drops ONLY that one entry — it never
+ *     blanks resolution for the whole fleet. `buildPersonDirectory` never
+ *     throws; every failure mode is reported via its `dropped` return
+ *     value instead, so the caller can route it through the existing
+ *     fleet-alert path (`emitGatewayOperatorEvent` in gateway.ts) at
+ *     low/config severity — this must never page like a real outage.
+ *
+ * Fix note (accepted soft mitigation — see docs/configuration.md): there is
+ * no automated enforcement that a configured `person_id` stays safe to show
+ * if a group's membership changes AFTER the entry is written. This is an
+ * operator-discipline convention, not a closed gap. Low severity today —
+ * only two `person_id`s are configured fleet-wide.
+ */
+
+export interface RawPersonEntry {
+  /** The `users:` map key (e.g. "lisa") — carried through for alert text. */
+  key: string
+  person_id: string
+  telegram_ids: string[]
+}
+
+export interface PersonDirectoryEntry {
+  key: string
+  personId: string
+  /** Normalized (lowercased, no leading "@") telegram ids/usernames. */
+  telegramKeys: string[]
+}
+
+export interface PersonDirectory {
+  /** normalized telegram id/username -> directory entry */
+  byTelegramKey: Record<string, PersonDirectoryEntry>
+}
+
+export interface DroppedPersonEntry {
+  key: string
+  reason: string
+  /**
+   * Name-scrubbed reason CLASS — the same rejection without the embedded
+   * `person_id` human-name value or the colliding telegram id. Used to
+   * build the broadcast `alertDetail` so a config-warning card (which
+   * `emitGatewayOperatorEvent` sends to EVERY `allowFrom` chat, including
+   * group chats where the named person may NOT be a member) never surfaces
+   * a human name that the display path (`resolvePersonName`) deliberately
+   * chat-scopes. The verbose `reason` is still carried for the operator's
+   * own stderr `logLine` (private, not broadcast).
+   */
+  reasonClass: string
+}
+
+export interface BuildPersonDirectoryResult {
+  directory: PersonDirectory
+  dropped: DroppedPersonEntry[]
+}
+
+/** Normalize a telegram id or @username for keying: trim, strip a leading
+ * "@", lowercase (Telegram usernames are case-insensitive). */
+function normalizeTelegramKey(raw: string): string {
+  return raw.trim().replace(/^@/, '').toLowerCase()
+}
+
+/**
+ * Validate and dedupe raw `users:` `person_id` entries into a lookup
+ * directory. Never throws — every rejection is reported via `dropped`
+ * instead, per the fail-open / drop-only-that-entry design.
+ *
+ * Drop reasons:
+ *   - missing/blank `key` or `person_id`
+ *   - `telegram_ids` missing or empty (nothing to key the entry by)
+ *   - `person_id` already claimed by an earlier (different) entry key —
+ *     first-declared entry wins, the later duplicate is dropped whole
+ *     (not just the colliding id) so the alert is unambiguous about which
+ *     entry lost
+ *   - a `telegram_id`/username already claimed by an earlier (different)
+ *     entry key — same first-declared-wins convention: the later duplicate
+ *     is dropped whole so the alert is unambiguous about which entry lost
+ *     and we never silently last-write-wins a numeric id into the wrong
+ *     person's name
+ */
+export function buildPersonDirectory(entries: readonly RawPersonEntry[]): BuildPersonDirectoryResult {
+  const byTelegramKey: Record<string, PersonDirectoryEntry> = {}
+  const dropped: DroppedPersonEntry[] = []
+  const personIdOwner = new Map<string, string>() // person_id (lowercased) -> owning entry key
+  const telegramKeyOwner = new Map<string, string>() // normalized telegram id/username -> owning entry key
+
+  for (const raw of entries) {
+    const key = typeof raw.key === 'string' ? raw.key.trim() : ''
+    const personId = typeof raw.person_id === 'string' ? raw.person_id.trim() : ''
+
+    if (key.length === 0) {
+      dropped.push({ key: raw.key || '(unknown)', reason: 'missing users: map key', reasonClass: 'missing users: map key' })
+      continue
+    }
+    if (personId.length === 0) {
+      dropped.push({ key, reason: 'empty or missing person_id', reasonClass: 'empty or missing person_id' })
+      continue
+    }
+    if (!Array.isArray(raw.telegram_ids) || raw.telegram_ids.length === 0) {
+      dropped.push({ key, reason: 'no telegram_ids to resolve against', reasonClass: 'no telegram_ids to resolve against' })
+      continue
+    }
+
+    const personIdLower = personId.toLowerCase()
+    const existingOwner = personIdOwner.get(personIdLower)
+    if (existingOwner != null && existingOwner !== key) {
+      dropped.push({
+        key,
+        // Verbose reason (stderr logLine only — private to the operator):
+        // names the person_id value + the owning config key.
+        reason: `duplicate person_id "${personId}" already claimed by users.${existingOwner}`,
+        // reasonClass (broadcast alertDetail): scrubs the human-name
+        // person_id value; keeps the entry key + collision class. A
+        // config-warning card fans out to every allowFrom chat, so the
+        // name must not travel further than the display path allows.
+        reasonClass: `duplicate person_id already claimed by users.${existingOwner}`,
+      })
+      continue
+    }
+    personIdOwner.set(personIdLower, key)
+
+    const telegramKeys = [...new Set(raw.telegram_ids.map(normalizeTelegramKey).filter((k) => k.length > 0))]
+    if (telegramKeys.length === 0) {
+      dropped.push({ key, reason: 'telegram_ids contained no usable id/username', reasonClass: 'telegram_ids contained no usable id/username' })
+      personIdOwner.delete(personIdLower)
+      continue
+    }
+
+    const collidingTelegramKey = telegramKeys.find((tk) => {
+      const existingTkOwner = telegramKeyOwner.get(tk)
+      return existingTkOwner != null && existingTkOwner !== key
+    })
+    if (collidingTelegramKey != null) {
+      const existingTkOwner = telegramKeyOwner.get(collidingTelegramKey)
+      dropped.push({
+        key,
+        reason: `duplicate telegram_id "${collidingTelegramKey}" already claimed by users.${existingTkOwner}`,
+        // Scrub the colliding telegram id/username from the broadcast
+        // reason; keep the owning config key (operator-chosen slug).
+        reasonClass: `duplicate telegram_id already claimed by users.${existingTkOwner}`,
+      })
+      personIdOwner.delete(personIdLower)
+      continue
+    }
+
+    const entry: PersonDirectoryEntry = { key, personId, telegramKeys }
+    for (const tk of telegramKeys) {
+      telegramKeyOwner.set(tk, key)
+      byTelegramKey[tk] = entry
+    }
+  }
+
+  return { directory: { byTelegramKey }, dropped }
+}
+
+export interface PersonDirectoryBootResult {
+  directory: PersonDirectory
+  /** Non-null when the caller should route an alert through the fleet
+   * alert path (`emitGatewayOperatorEvent`, kind: 'config-warning'). */
+  alertDetail: string | null
+  /** Always present — one human-readable line for stderr. */
+  logLine: string
+}
+
+/**
+ * Orchestrate the ONE-TIME boot-time check (requirement: boot-time-only,
+ * NOT periodic — call this exactly once, at gateway boot, never on a
+ * timer/interval). Extracted as a pure(ish) function — taking the file
+ * read as an injected dependency and RETURNING what to log/alert rather
+ * than performing the I/O itself — so it's unit-testable without booting
+ * the real gateway process.
+ *
+ * Dead-man's-switch: wraps the whole check in try/catch. If anything
+ * throws before completing (including `readEntries` itself), that failure
+ * is ALSO surfaced via `alertDetail` — mirrors a past incident where
+ * `access.json` validation failed silently in the wrong (fail-open)
+ * direction, undetected for hours. `PERSON_DIRECTORY` falls back to an
+ * empty directory on crash (fail-open: raw ids/usernames keep showing).
+ */
+export function runPersonDirectoryBootCheck(readEntries: () => RawPersonEntry[]): PersonDirectoryBootResult {
+  try {
+    const rawEntries = readEntries()
+    const { directory, dropped } = buildPersonDirectory(rawEntries)
+
+    if (dropped.length > 0) {
+      // Broadcast-safe summary for `alertDetail` (fans out to EVERY
+      // allowFrom chat via emitGatewayOperatorEvent, including group chats
+      // where the named person may not be a member): built from
+      // `reasonClass`, which scrubs the embedded person_id human-name
+      // value and the colliding telegram id. The verbose `reason`
+      // (names the values) is kept for the operator's own stderr
+      // `logLine` — private, never broadcast.
+      const alertSummary = dropped.map((d) => `${d.key} (${d.reasonClass})`).join('; ')
+      const logSummary = dropped.map((d) => `${d.key} (${d.reason})`).join('; ')
+      const plural = dropped.length === 1 ? 'y' : 'ies'
+      return {
+        directory,
+        alertDetail: `person_id: dropped ${dropped.length} malformed users: entr${plural} at boot — ${alertSummary}`,
+        logLine: `telegram gateway: person_id boot validation dropped ${dropped.length} entr${plural}: ${logSummary}`,
+      }
+    }
+
+    return {
+      directory,
+      alertDetail: null,
+      logLine: rawEntries.length > 0
+        ? `telegram gateway: person_id boot validation ok — ${Object.keys(directory.byTelegramKey).length} telegram id/username(s) resolved`
+        : `telegram gateway: person_id boot validation ok — no person_id entries configured`,
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      directory: { byTelegramKey: {} },
+      // Crash alertDetail scrubs the raw error message too — it can
+      // carry a filesystem path or other host detail that shouldn't fan
+      // out to every allowFrom chat. The full message stays in logLine.
+      alertDetail: `person_id boot validation crashed — name resolution disabled this boot (fail-open, raw ids/usernames will show); see gateway stderr for detail`,
+      logLine: `telegram gateway: person_id boot validation CRASHED (name resolution disabled this boot, raw ids will show — fail-open): ${msg}`,
+    }
+  }
+}
+
+export interface ResolvePersonOptions {
+  telegramId: string
+  username?: string | undefined
+  isDm: boolean
+  /** That chat's/group's configured allowFrom, if any (from access.json). */
+  groupAllowFrom?: readonly string[] | undefined
+}
+
+/**
+ * Resolve a sender's display name for THIS chat, chat-scoped per the
+ * module doc above. Returns undefined (fall back to raw id/username) when
+ * unresolved OR when membership in a group chat can't be positively
+ * confirmed.
+ */
+export function resolvePersonName(directory: PersonDirectory, opts: ResolvePersonOptions): string | undefined {
+  const idKey = normalizeTelegramKey(opts.telegramId)
+  const usernameKey = opts.username ? normalizeTelegramKey(opts.username) : undefined
+
+  const entry = directory.byTelegramKey[idKey] ?? (usernameKey ? directory.byTelegramKey[usernameKey] : undefined)
+  if (!entry) return undefined
+
+  // DM: the chat IS the sender, so resolution always applies.
+  if (opts.isDm) return entry.personId
+
+  // Group: only resolve if the sender is explicitly present in that
+  // chat's allowFrom (the existing membership source) — conservative
+  // fallback (undefined) otherwise, since we can't positively confirm
+  // membership from an empty/unset list.
+  const allowFrom = opts.groupAllowFrom ?? []
+  const allowFromNormalized = allowFrom.map(normalizeTelegramKey)
+  const memberConfirmed =
+    allowFromNormalized.includes(idKey) || (usernameKey != null && allowFromNormalized.includes(usernameKey))
+  return memberConfirmed ? entry.personId : undefined
+}
+
+/**
+ * Fail-open call-site wrapper around `resolvePersonName`, for use at the
+ * `handleInbound` call site (gateway.ts). This feature's whole design
+ * point is "never blocks or denies anything" (module doc above) — a throw
+ * from resolution must fall back to the raw id/username, not abort message
+ * handling. Mirrors the same defensive pattern already used for
+ * `readPeopleFile` (gateway.ts) and `runPersonDirectoryBootCheck` (this
+ * file): catch, fall back, never propagate.
+ */
+export function safeResolvePersonName(
+  directory: PersonDirectory,
+  opts: ResolvePersonOptions,
+  rawFallback: string,
+): string {
+  try {
+    return resolvePersonName(directory, opts) ?? rawFallback
+  } catch {
+    return rawFallback
+  }
+}

package/telegram-plugin/gateway/unhandled-rejection-policy.ts

@@ -126,7 +126,27 @@ export function classifyRejection(
     // handler shut the process down. reconcileStatusPin now absorbs its own
     // errors (primary fix); this entry is defense-in-depth so ANY leaked
     // pin-rights 400 from any path is log-only, not fatal.
-    desc.includes('not enough rights')
+    desc.includes('not enough rights') ||
+    // 'group chat was upgraded to a supergroup chat' fires when a send
+    // targets a basic-group chat_id that Telegram has since migrated to
+    // a supergroup (new id format -100xxxxxxxxxx). Telegram sometimes
+    // surfaces the replacement id via `error.parameters.migrate_to_chat_id`
+    // but not reliably for every send method, so this handler can't always
+    // auto-repair the stale id — it can only make the failure non-fatal.
+    // This crashed marko's gateway on 2026-07-09 (and recurred from the
+    // same stale-id root cause on 2026-06-07 and 2026-06-09): a send to an
+    // old pre-migration group id crashed the WHOLE gateway process for
+    // every agent/chat, not just the one stale chat. A single unmigrated
+    // chat_id in cached state must never be fatal — log it so the stale id
+    // can be tracked down and fixed, but keep serving every other chat.
+    desc.includes('group chat was upgraded to a supergroup chat') ||
+    // Broader class: any 400 whose description signals the target
+    // chat_id itself is no longer valid (migrated, deactivated, or
+    // otherwise unresolvable). These are all "this one destination is
+    // broken", never "the gateway is broken" — same log-only posture as
+    // 'chat not found' above.
+    desc.includes('chat_id is empty') ||
+    desc.includes('group chat was deactivated')
   ) {
     return 'log_only'
   }

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -33,6 +33,28 @@
  * delivery obligation.
  */
 
+// Verified complete (2026-07-09, adversarial-review follow-up): `reply`
+// and `stream_reply` are the ONLY two MCP tools whose payload is the
+// model's free-text final-answer content reaching the user — the exact
+// scope `final-answer-detect.ts`'s own docstring claims ("plain assistant
+// transcript text instead of a `reply` / `stream_reply` tool call").
+// Cross-checked the full tool surface in `telegram-plugin/bridge/bridge.ts`
+// (`TOOL_SCHEMAS`, kept in sync with `gateway/gateway.ts`): `edit_message`
+// explicitly does NOT ping/deliver a fresh answer (its own description says
+// "send a new reply when a long task completes"); `react`, `pin_message`,
+// `delete_message`, `forward_message`, `send_typing`, `download_attachment`,
+// `get_recent_messages` carry no model-authored answer text at all;
+// `send_checklist` / `send_sticker` / `send_gif` / `ask_user` /
+// `update_checklist` deliver structured/templated content, not the turn's
+// prose answer, and are intentionally a different interaction pattern (a
+// question or a fixed artifact, not "the answer"). `stream_reply` sends its
+// FULL cumulative text snapshot on every call (not incremental chunks —
+// see `stream-reply-handler.ts` docstring), and each call is its own
+// `tool_use` block in the transcript in chronological order, so the
+// "last delivery event wins" walk below already treats a stream's final
+// (`done:true`) call as the qualifying one regardless of how many
+// intermediate non-final `stream_reply` calls preceded it. No gap found;
+// re-verify only if a new outbound-delivery tool is added to bridge.ts.
 const REPLY_TOOLS = new Set([
   'mcp__switchroom-telegram__reply',
   'mcp__switchroom-telegram__stream_reply',
@@ -126,24 +148,47 @@ function buildTurnKey(chatId, threadId) {
   return `${chatId}:${threadId == null || threadId === 0 ? '_' : threadId}`
 }
 
+/**
+ * Build the `{ decided: 'block', ... }` result shape, populating
+ * `turnKey`/`chatId`/`threadId` from the enqueue envelope when
+ * available. Shared by both block branches below.
+ *
+ * @param {ReturnType<typeof parseChannelEnvelope>} envelope
+ * @param {string} reason
+ */
+function buildBlockResult(envelope, reason) {
+  const block = { decided: 'block', reason }
+  if (envelope.chatId) {
+    block.chatId = envelope.chatId
+    block.threadId = envelope.threadId
+    block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+  }
+  return block
+}
+
 /**
  * Scan a JSONL transcript and decide whether the current turn ended
  * with a final reply delivered.
  *
  * Returns:
- *   { decided: 'allow', reason }    — qualifying reply OR silent marker found
+ *   { decided: 'allow', reason }    — qualifying reply OR silent marker found,
+ *                                     and nothing undelivered was written
+ *                                     after it
  *   { decided: 'block', reason, turnKey?, chatId?, threadId? }
- *                                   — turn-start found, no qualifying reply,
- *                                     no marker. `turnKey`/`chatId`/`threadId`
- *                                     populated from the enqueue's channel
- *                                     envelope so the hook can write a state
- *                                     file shape that matches what the
- *                                     gateway's `recordSilentTurnEnd` would
- *                                     write — keeping the retry-count
- *                                     preservation gate at
- *                                     `silent-end.ts:114` happy when the
- *                                     gateway's later write reads back the
- *                                     hook's state.
+ *                                   — turn-start found, no qualifying reply
+ *                                     delivered (or a qualifying reply
+ *                                     happened, but the model kept writing
+ *                                     plain-text content afterward that was
+ *                                     never sent through a delivery tool).
+ *                                     `turnKey`/`chatId`/`threadId` populated
+ *                                     from the enqueue's channel envelope so
+ *                                     the hook can write a state file shape
+ *                                     that matches what the gateway's
+ *                                     `recordSilentTurnEnd` would write —
+ *                                     keeping the retry-count preservation
+ *                                     gate at `silent-end.ts:114` happy when
+ *                                     the gateway's later write reads back
+ *                                     the hook's state.
  *   { decided: 'unknown', reason }  — couldn't locate turn-start; caller fail-open
  *
  * Turn-start anchor: the most recent `queue-operation`/`enqueue` line
@@ -154,6 +199,38 @@ function buildTurnKey(chatId, threadId) {
  * edge case where the model replied combined ahead of the second
  * enqueue's append; accepted residual.)
  *
+ * IMPORTANT — trailing-content check (fixes the "at least once" bug):
+ * a naive scan that returns 'allow' on the FIRST qualifying reply it
+ * finds is wrong. A turn can legitimately call `reply` early (e.g. a
+ * notification-bearing interim ack — `disable_notification` unset/false
+ * always qualifies as "final" under `isFinalAnswerReply`, regardless of
+ * how short the text is) and then keep working, eventually writing a
+ * SUBSTANTIVE plain-text verdict that never goes through `reply` again.
+ * The early ack satisfied "reply was called somewhere in this turn",
+ * but the user never saw the actual answer. So this scan does NOT
+ * short-circuit on the first match: it walks the ENTIRE turn in
+ * chronological order, remembers the position of the LAST qualifying
+ * delivery event (a final-answer reply/stream_reply call, or an
+ * explicit silent-marker), and then checks whether any plain assistant
+ * text block appears AFTER that position. If one does, that content was
+ * written but never delivered — block, same as the zero-reply case.
+ *
+ * This deliberately does NOT flag a turn that ends on a delivery
+ * tool_use with nothing after it (the normal, healthy shape), nor a
+ * turn where all assistant text precedes the final delivering reply
+ * (the model narrating before it sends) — only text that comes AFTER
+ * the last delivery event counts as a drop.
+ *
+ * Substance floor (#2956 review): the trailing-text check only BLOCKS
+ * when the trailing text is SUBSTANTIVE — at least FINAL_ANSWER_MIN_CHARS
+ * (the same bar `isFinalAnswerReply` uses to recognise a real answer). A
+ * SHORT trailing pleasantry / closer after a delivered reply ("Let me
+ * know if you need anything else.") is not a dropped answer and must not
+ * trigger a re-prompt (no-spam / single-answer invariant). A long
+ * trailing verdict the model forgot to send still blocks. The floor keeps
+ * the "at least once" guarantee for real dropped answers while stopping a
+ * false-positive that burned retry budget on healthy turns.
+ *
  * @param {string} jsonl
  * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, chatId?: string, threadId?: number | null }}
  */
@@ -178,8 +255,13 @@ export function scanTurnForFinalReply(jsonl) {
     return { decided: 'unknown', reason: 'no-turn-start' }
   }
 
-  // 2. Scan forward from the turn start; look for qualifying tool_use
-  //    or silent-marker text.
+  // 2. Flatten every assistant content block (text and tool_use) from
+  //    the turn into a single chronologically-ordered list. Classify
+  //    each block as it's collected: a "delivery" event (qualifying
+  //    final-answer reply/stream_reply, or an explicit silent marker —
+  //    whether emitted as plain text or as a reply-tool payload) or
+  //    plain undelivered text.
+  const blocks = []
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
@@ -193,16 +275,28 @@ export function scanTurnForFinalReply(jsonl) {
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
     for (const c of content) {
-      // Plain assistant text carve-out (#2053): a turn that ends with a
-      // trailing bare NO_REPLY / HEARTBEAT_OK line — emitted as plain
-      // transcript text, NOT through the reply tool — is the model
-      // explicitly signalling "intentionally silent". The anchored
-      // SILENT_MARKER_RE below only fires when the ENTIRE reply-tool
-      // text is the bare marker, so a plain-text prose+NO_REPLY turn
-      // matched nothing here → block → nag → sentinel leak. Treat a
-      // trailing-marker text block as a valid silent end.
-      if (c?.type === 'text' && endsWithSilentMarker(String(c.text ?? ''))) {
-        return { decided: 'allow', reason: 'silent-marker-text' }
+      if (c?.type === 'text') {
+        // Plain assistant text carve-out (#2053): a turn that ends with
+        // a trailing bare NO_REPLY / HEARTBEAT_OK line — emitted as
+        // plain transcript text, NOT through the reply tool — is the
+        // model explicitly signalling "intentionally silent". Treat a
+        // trailing-marker text block as a delivery/silence event;
+        // anything else is candidate undelivered content.
+        if (endsWithSilentMarker(String(c.text ?? ''))) {
+          blocks.push({ kind: 'deliver', reason: 'silent-marker-text' })
+        } else if (String(c.text ?? '').trim().length > 0) {
+          // Carry the trimmed char count so the trailing-content check
+          // (step 3) can apply a substance floor: a SHORT trailing text
+          // after a delivered reply (a pleasantry / closer like "Let me
+          // know if you need anything else.") is NOT a dropped answer and
+          // must not trigger a re-prompt (no-spam invariant). Only
+          // SUBSTANTIVE trailing text — at least FINAL_ANSWER_MIN_CHARS,
+          // the same bar `isFinalAnswerReply` uses to recognise a real
+          // answer — counts as "undelivered content the user was waiting
+          // on". #2956 review finding.
+          blocks.push({ kind: 'text', chars: String(c.text ?? '').trim().length })
+        }
+        continue
       }
       if (c?.type !== 'tool_use') continue
       if (!REPLY_TOOLS.has(c.name)) continue
@@ -214,33 +308,63 @@ export function scanTurnForFinalReply(jsonl) {
       // prose+trailing-marker shape (#2053). Same posture as the
       // gateway's silent-marker suppression at gateway.ts:6692.
       if (SILENT_MARKER_RE.test(text.trim()) || endsWithSilentMarker(text)) {
-        return { decided: 'allow', reason: 'silent-marker' }
+        blocks.push({ kind: 'deliver', reason: 'silent-marker' })
+        continue
       }
       if (isFinalAnswerReply({
         text,
         disableNotification: input.disable_notification === true,
         done: input.done === true,
       })) {
-        return { decided: 'allow', reason: 'final-reply' }
+        blocks.push({ kind: 'deliver', reason: 'final-reply' })
+        continue
       }
+      // Non-qualifying reply call (interim ack) — delivered to the
+      // user, but not a "final answer". It's neither a delivery event
+      // nor undelivered text, so it doesn't affect the decision either
+      // way; simply not pushed.
     }
   }
 
-  // Cron-fired turns (#2053): a scheduled turn that produced no
-  // qualifying reply is NOT a delivery failure the user is waiting on —
-  // nagging it only pushes the model to escape the loop by shoving a
-  // NO_REPLY sentinel through the reply tool, which leaks to chat. A
-  // cron turn that genuinely needs to speak will have called reply
-  // (caught above); otherwise let it end silently.
-  if (envelope.source === 'cron') {
-    return { decided: 'allow', reason: 'cron-source' }
+  // 3. Find the LAST delivery event's position, then check whether any
+  //    plain-text block appears strictly after it. This is the fix for
+  //    the "at least once" bug: a naive scan that stops at the FIRST
+  //    qualifying reply misses substantive content the model wrote
+  //    afterward and never (re-)sent.
+  let lastAllowBlockIdx = -1
+  let lastAllowReason = null
+  for (let i = 0; i < blocks.length; i++) {
+    if (blocks[i].kind === 'deliver') {
+      lastAllowBlockIdx = i
+      lastAllowReason = blocks[i].reason
+    }
   }
+  const sawUndeliveredTextAfterAllow = blocks
+    .slice(lastAllowBlockIdx + 1)
+    .some((b) => b.kind === 'text' && (b.chars ?? 0) >= FINAL_ANSWER_MIN_CHARS)
 
-  const block = { decided: 'block', reason: 'no-final-reply' }
-  if (envelope.chatId) {
-    block.chatId = envelope.chatId
-    block.threadId = envelope.threadId
-    block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+  if (lastAllowBlockIdx === -1) {
+    // No qualifying delivery/silence event anywhere in the turn.
+    // Cron-fired turns (#2053): a scheduled turn that produced no
+    // qualifying reply is NOT a delivery failure the user is waiting
+    // on — nagging it only pushes the model to escape the loop by
+    // shoving a NO_REPLY sentinel through the reply tool, which leaks
+    // to chat. A cron turn that genuinely needs to speak will have
+    // called reply (caught above); otherwise let it end silently.
+    if (envelope.source === 'cron') {
+      return { decided: 'allow', reason: 'cron-source' }
+    }
+    return buildBlockResult(envelope, 'no-final-reply')
   }
-  return block
+
+  if (sawUndeliveredTextAfterAllow) {
+    // A qualifying delivery DID happen somewhere in the turn, but the
+    // model kept writing after it and that trailing content was never
+    // sent through a delivery tool. This is the "at least once" bug:
+    // an early ack (or any qualifying reply) must not amnesty
+    // everything written afterward.
+    return buildBlockResult(envelope, 'trailing-text-after-reply')
+  }
+
+  return { decided: 'allow', reason: lastAllowReason }
 }

package/telegram-plugin/operator-events.ts

@@ -26,6 +26,7 @@ export type OperatorEventKind =
   | 'agent-restarted-unexpectedly'
   | 'unknown-4xx'
   | 'unknown-5xx'
+  | 'config-warning'
 
 export interface OperatorEvent {
   kind: OperatorEventKind
@@ -375,6 +376,26 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
           ],
         },
       }
+
+    // Deliberately low-severity framing (ℹ️, Dismiss-only — no Restart /
+    // Reauth / Show-logs actions): config-warning is for boot-time config
+    // problems (e.g. a dropped `person_id` entry) that must be visible to
+    // the operator but MUST NOT read like a real outage or page anyone.
+    case 'config-warning':
+      return {
+        text: [
+          `ℹ️ **Config warning** for **${agent}**.`,
+          detail ? `_${detail}_` : '',
+          `Non-urgent — config will keep working with today's fallback behavior.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
   }
 }