switchroom 0.19.3 → 0.19.5

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

@@ -55,6 +55,9 @@
 // (`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.
+import { statSync } from 'node:fs'
+import { join } from 'node:path'
+
 const REPLY_TOOLS = new Set([
   'mcp__switchroom-telegram__reply',
   'mcp__switchroom-telegram__stream_reply',
@@ -97,6 +100,68 @@ export function endsWithSilentMarker(text) {
   return SILENT_MARKER_RE.test(lines[lines.length - 1])
 }
 
+// ── Narration heuristics — ported from `turn-flush-safety.ts:198-274` ──
+//
+// Kept byte-parallel with `selectFlushDeliveryText` / `isNarrationBlock` so
+// the JOINED multi-block prose the scan persists as `pendingText` (for the
+// capture-divergence corner) matches what the gateway flush would itself have
+// delivered. The scan has no structural `followedByToolUse` provenance, so it
+// uses the opener/trailer heuristic fallback (the same branch the TS side
+// takes when the flag is absent). MUST stay in sync with the TS source; a
+// drift only affects the rare capture-empty corner, never the primary flush.
+const NARRATION_OPENER =
+  /^(let me\b|lemme\b|i'?ll\b|i will\b|i am going to\b|i'?m going to\b|i'?m about to\b|going to\b|first,?\s+(?:let me|i'?ll|i will)\b|now,?\s+(?:let me|i'?ll|i will)\b|next,?\s+(?:let me|i'?ll|i will)\b|let'?s\b)/i
+const NARRATION_TRAILER = /(?:\.{3}|…|:)\s*$/
+
+function isTrailingNarrationLine(block) {
+  const t = block.trim()
+  if (t.length === 0 || t.length >= FINAL_ANSWER_MIN_CHARS) return false
+  if (t.includes('\n')) return false
+  return NARRATION_TRAILER.test(t)
+}
+
+function isNarrationBlock(block) {
+  return NARRATION_OPENER.test(block.trimStart()) || isTrailingNarrationLine(block)
+}
+
+/**
+ * Choose the prose the captured-prose bridge should deliver from the trailing
+ * text blocks in the ZERO-reply case, mirroring `selectFlushDeliveryText`
+ * (`turn-flush-safety.ts:198-232`). `texts` are already trimmed non-empty.
+ *
+ *   - 0 blocks   → undefined (nothing to deliver).
+ *   - 1 block    → that block (the real single-block short-answer shape;
+ *                  persisted even below the substance floor so the lowered-
+ *                  floor capture-divergence corner can deliver it).
+ *   - ≥2 blocks  → strip leading narration exactly as the flush does: if EVERY
+ *                  preceding block is narration, deliver only the terminal
+ *                  block; otherwise JOIN all blocks with a paragraph break (a
+ *                  genuine multi-paragraph answer split across blocks). When
+ *                  the result is narration-only (terminal block is itself
+ *                  narration AND all preceding are narration) → undefined, so a
+ *                  pure narration run never masquerades as an answer (#3228
+ *                  Finding 2 parity).
+ *
+ * @param {string[]} texts
+ * @returns {string | undefined}
+ */
+export function selectBridgePendingText(texts) {
+  const candidates = texts.map((t) => t.trim()).filter((t) => t.length > 0)
+  if (candidates.length === 0) return undefined
+  if (candidates.length === 1) return candidates[0]
+  const answer = candidates[candidates.length - 1]
+  const preceding = candidates.slice(0, -1)
+  const allPrecedingNarration = preceding.every((b) => isNarrationBlock(b))
+  if (allPrecedingNarration) {
+    // Deliver only the terminal block — unless it too is pure narration, in
+    // which case the whole run is narration and there is no answer to bridge.
+    return isNarrationBlock(answer) ? undefined : answer
+  }
+  // A preceding block carries real content → keep the whole answer joined so a
+  // multi-block answer is never truncated to its last paragraph.
+  return candidates.join('\n\n')
+}
+
 /**
  * Predicate ported from `telegram-plugin/final-answer-detect.ts:78-83`.
  * Kept in this .mjs so the hook is fully self-contained (no TS import).
@@ -193,8 +258,16 @@ function buildTurnId(chatId, threadId, messageId) {
  *   clears the substance floor, so the gateway never re-delivers a short
  *   trailing pleasantry. Omitted entirely otherwise.
  */
-function buildBlockResult(envelope, reason, pendingText) {
+function buildBlockResult(envelope, reason, pendingText, hasTrailingProse) {
   const block = { decided: 'block', reason }
+  // Single-writer election input (#duplicate-message fix): does ANY
+  // non-empty, non-silent trailing text block exist after the last
+  // delivery event? The zero-reply election allows only when this is
+  // true — `decideTurnFlush` has no length floor, so any non-empty
+  // non-silent captured text WILL flush; but a turn with NO trailing
+  // prose at all (tool calls only) has nothing for any delivery
+  // machine to send and must keep blocking.
+  if (hasTrailingProse === true) block.hasTrailingProse = true
   if (envelope.chatId) {
     block.chatId = envelope.chatId
     block.threadId = envelope.threadId
@@ -432,6 +505,32 @@ export function scanTurnForFinalReply(jsonl) {
     substantiveBlocks.length > 0
       ? substantiveBlocks[substantiveBlocks.length - 1].text
       : undefined
+  const trailingTextBlocks = undeliveredSlice.filter(
+    (b) => b.kind === 'text' && typeof b.text === 'string' && b.text.length > 0,
+  )
+  const hasTrailingProse = trailingTextBlocks.length > 0
+  // Capture-divergence bridge (#duplicate-message fix): in the ZERO-reply
+  // case, persist the last trailing block even when no single block clears
+  // the 200-char substance floor. The gateway's flush normally delivers any
+  // non-empty captured text, but when the gateway's own capture diverged
+  // (captured empty) the captured-prose bridge is the only delivery machine
+  // left, and it reads `pendingText` — the gateway lowers `minChars` for
+  // exactly this corner (`capturedProseMinCharsFor`, silent-end.ts). The
+  // interim-ack case (`trailing-text-after-reply`) keeps the substantive
+  // floor unchanged — a short closer after a real reply is not a dropped
+  // answer.
+  //
+  // Multi-block corner (review item 3): a real answer split across ≥2
+  // individually-sub-200 blocks (e.g. two ~150-char paragraphs) would
+  // otherwise yield NO pendingText — and in the capture-divergence-empty
+  // corner (gateway `capturedText` empty → flush skips 'empty-text') the
+  // bridge would then have nothing to deliver and the hook already allowed the
+  // stop: a DROPPED ANSWER. `selectBridgePendingText` mirrors the flush's own
+  // `selectFlushDeliveryText` narration-strip/join, so the bridge delivers the
+  // joined prose (with the lowered `minChars`) instead of dropping. The #3228
+  // Finding 2 guard is preserved: a pure narration run still yields undefined.
+  const zeroReplyPendingText =
+    pendingText ?? selectBridgePendingText(trailingTextBlocks.map((b) => b.text))
 
   if (lastAllowBlockIdx === -1) {
     // No qualifying delivery/silence event anywhere in the turn.
@@ -444,7 +543,7 @@ export function scanTurnForFinalReply(jsonl) {
     if (envelope.source === 'cron') {
       return { decided: 'allow', reason: 'cron-source' }
     }
-    return buildBlockResult(envelope, 'no-final-reply', pendingText)
+    return buildBlockResult(envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse)
   }
 
   if (sawUndeliveredTextAfterAllow) {
@@ -453,8 +552,169 @@ export function scanTurnForFinalReply(jsonl) {
     // 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', pendingText)
+    return buildBlockResult(envelope, 'trailing-text-after-reply', pendingText, hasTrailingProse)
   }
 
   return { decided: 'allow', reason: lastAllowReason }
 }
+
+// ── Single-writer election (duplicate-message fix) ───────────────────
+//
+// RCA: when a turn ends with its final answer as plain transcript text,
+// TWO uncoordinated recovery paths both fire — (A) the gateway's
+// deterministic turn-end flush (`decideTurnFlush` /
+// `answer-ready-flush.ts`) delivers the captured transcript prose, AND
+// (B) this Stop hook blocks and re-prompts the model, which regenerates
+// a REWORDED reply that defeats the exact-match dedup
+// (`flushed-turn-supersede.ts` `flushedAnswerMatchesReply`). The user
+// gets two near-identical messages.
+//
+// Fix: the Stop hook is the single elector. On a would-BLOCK scan it
+// ALLOWS the stop (still persisting the state file so the gateway's
+// delivery machines have their input) IFF it can PROVE a gateway
+// delivery machine will handle the trailing prose. Every gate below
+// exists to prevent a DROP (worse than a duplicate):
+//
+//   1. deliverable trailing prose exists AND the right machine covers it
+//      - zero-reply (`no-final-reply`): ANY non-empty non-silent
+//        trailing prose — `decideTurnFlush` has no length floor and
+//        flushes any non-empty non-silent captured text. (No 200-char
+//        floor here.)
+//      - interim-ack (`trailing-text-after-reply`, replyCalled=true):
+//        ONLY the captured-prose bridge delivers there (the flush skips
+//        on reply-called), and its floor is 200 — so short trailing
+//        text after a real reply keeps BLOCKING (no duplicate exists in
+//        that case today).
+//   2. the governing delivery flag is enabled (read by the hook from
+//      its own env): zero-reply needs the turn-flush-safety flag AND
+//      the captured-prose flag (the bridge is the capture-divergence
+//      backstop when the gateway captured empty); interim-ack needs the
+//      captured-prose flag. Flag off → the machine won't fire → BLOCK.
+//   3. retryCount === 0 — a prior failed delivery must fall back to
+//      today's BLOCK, preserving the #3228 send-failure recovery net.
+//   4. gateway liveness — the gateway heartbeat file must be FRESH.
+//      Allowing into a dead gateway is the one drop worse than a
+//      duplicate; when liveness can't be established, BLOCK.
+//
+// Pure and deterministic: the hook wrapper does the IO (env read, stat,
+// state-file write) and maps this verdict to exit-0-allow vs
+// decision:block.
+
+/**
+ * @param {{
+ *   scan: ReturnType<typeof scanTurnForFinalReply>,
+ *   retryCount: number,
+ *   turnFlushSafetyEnabled: boolean,
+ *   capturedProseDeliveryEnabled: boolean,
+ *   gatewayLive: boolean,
+ * }} input
+ * @returns {{ action: 'allow-scan' | 'allow-elected' | 'block', reason: string }}
+ */
+export function decideStopHookDisposition(input) {
+  const {
+    scan,
+    retryCount,
+    turnFlushSafetyEnabled,
+    capturedProseDeliveryEnabled,
+    gatewayLive,
+  } = input
+  if (scan == null || scan.decided !== 'block') {
+    return { action: 'allow-scan', reason: `scan-${scan?.decided ?? 'unknown'}` }
+  }
+  // Gate 4 — never allow into a possibly-dead gateway.
+  if (gatewayLive !== true) {
+    return { action: 'block', reason: 'gateway-liveness-not-fresh' }
+  }
+  // Gate 3 — a retry ladder already in flight means a prior delivery
+  // attempt failed; today's BLOCK is the recovery net (#3228).
+  if (retryCount !== 0) {
+    return { action: 'block', reason: 'retry-ladder-in-flight' }
+  }
+  if (scan.reason === 'no-final-reply') {
+    // Gate 2 (zero-reply): the turn-end flush is the delivery machine;
+    // the captured-prose bridge is the capture-divergence backstop.
+    if (!turnFlushSafetyEnabled) {
+      return { action: 'block', reason: 'turn-flush-flag-disabled' }
+    }
+    if (!capturedProseDeliveryEnabled) {
+      return { action: 'block', reason: 'captured-prose-flag-disabled' }
+    }
+    // Gate 1 (zero-reply): any non-empty non-silent trailing prose.
+    if (scan.hasTrailingProse !== true) {
+      return { action: 'block', reason: 'no-trailing-prose' }
+    }
+    return { action: 'allow-elected', reason: 'flush-will-deliver' }
+  }
+  if (scan.reason === 'trailing-text-after-reply') {
+    // Gate 2 (interim-ack): only the captured-prose bridge delivers here.
+    if (!capturedProseDeliveryEnabled) {
+      return { action: 'block', reason: 'captured-prose-flag-disabled' }
+    }
+    // Gate 1 (interim-ack): the bridge's substance floor is 200 chars
+    // (CAPTURED_PROSE_MIN_CHARS, silent-end.ts). Below it the bridge
+    // will NOT deliver — keep blocking (matches today: no duplicate
+    // exists for short trailing text after a real reply).
+    if (
+      typeof scan.pendingText !== 'string' ||
+      scan.pendingText.trim().length < FINAL_ANSWER_MIN_CHARS
+    ) {
+      return { action: 'block', reason: 'short-trailing-after-reply' }
+    }
+    return { action: 'allow-elected', reason: 'bridge-will-deliver' }
+  }
+  // Unknown block reason — conservatively keep today's behaviour.
+  return { action: 'block', reason: `unrecognized-scan-reason-${scan.reason}` }
+}
+
+/**
+ * Mirror of `isTurnFlushSafetyEnabled` (`turn-flush-safety.ts:392-400`).
+ * Kept in this .mjs so the hook is self-contained (no TS import); MUST
+ * stay in sync — default ON, disabled by `0` / `false` / `off` / `no`.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isTurnFlushSafetyEnabledEnv(env) {
+  const raw = env.SWITCHROOM_TG_TURN_FLUSH_SAFETY
+  if (raw == null) return true
+  const v = raw.trim().toLowerCase()
+  return !(v === '0' || v === 'false' || v === 'off' || v === 'no')
+}
+
+/**
+ * Mirror of `CAPTURED_PROSE_DELIVERY_ENABLED` (`gateway/gateway.ts` —
+ * `SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY !== '0'`). MUST stay in sync.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isCapturedProseDeliveryEnabledEnv(env) {
+  return env.SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY !== '0'
+}
+
+// MUST stay in sync with gateway/gateway-heartbeat.ts (the hook is a
+// standalone .mjs and can't import the TS module). The gateway touches
+// the file every GATEWAY_HEARTBEAT_INTERVAL_MS (15s); freshness bound is
+// 4 intervals — conservative against scheduler jitter, small enough that
+// a dead gateway is detected before its stale heartbeat can swallow more
+// than one turn's election.
+export const GATEWAY_HEARTBEAT_FILE = 'gateway-heartbeat'
+export const GATEWAY_HEARTBEAT_FRESH_MS = 60_000
+
+/**
+ * Gate 4 IO helper: is the gateway heartbeat file fresh? Missing,
+ * unstattable, or stale ⇒ false (BLOCK — never allow into a possibly-
+ * dead gateway).
+ *
+ * @param {string} stateDir
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function isGatewayHeartbeatFresh(stateDir, now = Date.now()) {
+  try {
+    const st = statSync(join(stateDir, GATEWAY_HEARTBEAT_FILE))
+    return now - st.mtimeMs <= GATEWAY_HEARTBEAT_FRESH_MS
+  } catch {
+    return false
+  }
+}

package/telegram-plugin/render/line-start-guard.ts

@@ -43,11 +43,20 @@
 // punctuation may be backslash-escaped" rule; Telegram's rich parser strips
 // the backslash the same way `escapeMarkdown` relies on for `~ = | * _`.
 //
+// ── Accidental heading (`#3460`, `#foo`) — guarded by guardAccidentalHeading ─
+//   Telegram's Bot API rich-markdown parser is NON-spec: it promotes ANY
+//   line-leading `#{1,6}` run to a heading even WITHOUT the CommonMark-required
+//   trailing space (`#3460 done` renders as a huge heading). This is
+//   deterministically disambiguable: a `#{1,6}` run followed by a space,
+//   another `#`, or end-of-line is an INTENDED heading (or ambiguous) and is
+//   LEFT ALONE; a run glued to a non-space, non-`#` char (`#3460`, `#foo`,
+//   `###x`) is the accidental Telegram-only heading and IS escaped. See
+//   `guardAccidentalHeading` below — it mirrors the render.ts:escapeLineLeadingHash
+//   fix (#3306) but runs at the universal wire seam, independent of the
+//   SWITCHROOM_RICH_RENDER kill-switch, so cards/banners/status/approval sends
+//   (which bypass the rich renderer) are also covered.
+//
 // ── What is DEFERRED (left to the rich-formatting workstream) ────────────
-//   • Heading `# ` (with the required space): indistinguishable from an
-//     INTENDED heading. `#1` / `#foo` (NO space) is not a GFM heading at all
-//     (ATX headings require `#`+space) → Telegram renders it literally → no
-//     guard needed. So there is no safely-guardable heading sub-case.
 //   • Bullet lists `-`/`+`/`*` + space (`- 5 degrees`): genuinely ambiguous
 //     with the heavily-used bullet construct; the glued form `-5` (no space)
 //     is not a list item → already literal → no guard needed. Escaping the
@@ -165,3 +174,66 @@ export function guardAccidentalBlockConstructs(text: string): string {
 
   return out;
 }
+
+/** Line-start `#{1,6}` run glued DIRECTLY to a non-space, non-`#` char — the
+ *  Telegram-non-spec accidental heading (`#3460`, `#foo`, `###x`). The negative
+ *  lookahead `(?=[^\s#])` requires a following char that is neither whitespace,
+ *  a `#`, nor end-of-line, so an intended `# Title` / `## Sub` (space-delimited)
+ *  and a bare `#` / `##` (end-of-line) are NEVER matched. Up to 3 leading spaces
+ *  are permitted (4+ is indented code, and the `{0,3}` bound then leaves a space
+ *  before the `#`, so it correctly does not match). Only the first `#` of the run
+ *  is backslash-escaped, which is sufficient to stop Telegram promoting the line
+ *  to a heading. Idempotent: an already-escaped `\#3460` starts with `\`, so the
+ *  `#{1,6}` no longer sits at the (post-indent) line start. */
+const ACCIDENTAL_HEADING = /^([ \t]{0,3})(#{1,6})(?=[^\s#])/;
+
+/**
+ * Escape the accidental heading trigger at the start of ONE line (the string
+ * must NOT contain a newline; the caller guarantees a true line start). A no-op
+ * unless the line begins with a `#{1,6}` run glued to a non-space, non-`#` char.
+ */
+function escapeAccidentalHeadingLine(line: string): string {
+  return line.replace(ACCIDENTAL_HEADING, "$1\\$2");
+}
+
+/**
+ * Neutralise accidental line-start HEADING promotion (`#3460 done` → giant
+ * heading) on the FINAL rendered rich-markdown string. Telegram's Bot API
+ * parser promotes a line-leading `#{1,6}` run to a heading even without the
+ * CommonMark-required trailing space; this escapes ONLY the space-less,
+ * non-`#`-adjacent form and leaves genuine `# Title` / `## Sub` headings
+ * untouched. Code spans / fenced blocks / link destinations / table rows are
+ * never touched (shared `splitProtectedSegments`). Idempotent and a strict
+ * no-op absent a real signal. Mirrors render.ts:escapeLineLeadingHash (#3306)
+ * but runs at the universal wire seam, so it also covers the card / banner /
+ * status / approval sends that bypass the rich renderer.
+ */
+export function guardAccidentalHeading(text: string): string {
+  // Cheap short-circuit: no `#` at all => no-op.
+  if (!text.includes("#")) return text;
+
+  const segments = splitProtectedSegments(text);
+  let out = "";
+  // True at text start and immediately after any emitted `\n`.
+  let atLineStart = true;
+
+  for (const seg of segments) {
+    if (seg.code) {
+      out += seg.text;
+      atLineStart = seg.text.endsWith("\n");
+      continue;
+    }
+    const lines = seg.text.split("\n");
+    for (let k = 0; k < lines.length; k++) {
+      // A prose segment can begin MID-LINE (right after an inline code span),
+      // so its first line is a real line start only if the running flag says so.
+      const lineIsAtStart = k === 0 ? atLineStart : true;
+      const processed = lineIsAtStart ? escapeAccidentalHeadingLine(lines[k]) : lines[k];
+      out += processed;
+      if (k < lines.length - 1) out += "\n";
+    }
+    atLineStart = seg.text.endsWith("\n");
+  }
+
+  return out;
+}

package/telegram-plugin/rich-send.ts

@@ -20,7 +20,7 @@
 import { GrammyError } from 'grammy'
 import { guardDollarMath } from './render/dollar-math-guard.js'
 import { guardAccidentalEmphasis } from './render/emphasis-guard.js'
-import { guardAccidentalBlockConstructs } from './render/line-start-guard.js'
+import { guardAccidentalBlockConstructs, guardAccidentalHeading } from './render/line-start-guard.js'
 import { guardAccidentalInlinePairs } from './render/inline-pairs-guard.js'
 
 /** The `InputRichMessage` shape grammy 1.44 accepts on send AND edit. */
@@ -36,6 +36,12 @@ export interface InputRichMessageMarkdown {
  * idempotent and safe to apply once per send.
  *
  * ── Ordering (deliberate, not arbitrary) ──────────────────────────────────
+ * `guardAccidentalHeading` runs right after emphasis and before block-constructs.
+ * It only ever inserts `\` before a line-leading `#{1,6}` run; `#` is inspected
+ * and inserted by no other guard (disjoint char set), so its position among the
+ * siblings is order-independent — it neither creates nor destroys a signal for
+ * any of them.
+ *
  * `guardDollarMath` runs LAST. It backslash-escapes `$` → `\$`, and the
  * inline-pairs guard's approximation-tilde signal is `~(?=\$?\.?\d)` — a `~`
  * glued to a `$digit`. If the dollar guard ran first, a body like
@@ -51,6 +57,7 @@ export interface InputRichMessageMarkdown {
 export function guardAccidentalFormatting(markdown: string): string {
   let out = markdown
   out = guardAccidentalEmphasis(out)
+  out = guardAccidentalHeading(out)
   out = guardAccidentalBlockConstructs(out)
   out = guardAccidentalInlinePairs(out)
   out = guardDollarMath(out)

package/telegram-plugin/tests/command-format.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Direct unit tests for `gateway/command-format.ts` — the pure
+ * slash-command formatting/keyboard helpers extracted from gateway.ts
+ * in switchroom#3461 (testability win tracked by #3460).
+ *
+ * These assert real rendered outcomes (exact strings, keyboard shapes,
+ * thrown errors), not just that the code runs.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  formatSwitchroomOutput,
+  stripAnsi,
+  escapeHtmlForTg,
+  preBlock,
+  getCommandArgs,
+  hasDemoFlag,
+  assertSafeAgentName,
+  formatAuthOutputForTelegram,
+  buildAuthUrlKeyboard,
+  buildDeferredSecretKeyboard,
+  renderVaultOpFailure,
+  statusIcon,
+  renderAuthCodeOutcome,
+  buildDoctorScopeKeyboard,
+  formatDoctorReport,
+} from '../gateway/command-format.js'
+import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import type { Context } from 'grammy'
+
+describe('formatSwitchroomOutput', () => {
+  it('trims and passes short output through unchanged', () => {
+    expect(formatSwitchroomOutput('  hello\nworld  ')).toBe('hello\nworld')
+  })
+  it('truncates past the rich-message cap with a marker', () => {
+    const big = 'x'.repeat(RICH_MESSAGE_MAX_CHARS + 100)
+    const out = formatSwitchroomOutput(big)
+    expect(out.endsWith('\n... (truncated)')).toBe(true)
+    expect(out.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS)
+  })
+  it('honours an explicit maxLen', () => {
+    expect(formatSwitchroomOutput('abcdefghij'.repeat(10), 50)).toBe(
+      'abcdefghij'.repeat(10).slice(0, 30) + '\n... (truncated)',
+    )
+  })
+})
+
+describe('stripAnsi', () => {
+  it('removes CSI escape sequences and keeps text', () => {
+    expect(stripAnsi('\x1b[31mred\x1b[0m plain')).toBe('red plain')
+  })
+})
+
+describe('escapeHtmlForTg', () => {
+  it('backslash-escapes GFM specials', () => {
+    expect(escapeHtmlForTg('a*b_c`d[e]f|g~h=i\\j')).toBe(
+      'a\\*b\\_c\\`d\\[e\\]f\\|g\\~h\\=i\\\\j',
+    )
+  })
+  it('leaves ordinary text alone', () => {
+    expect(escapeHtmlForTg('hello world 123')).toBe('hello world 123')
+  })
+})
+
+describe('preBlock', () => {
+  it('wraps content in a fenced code block', () => {
+    expect(preBlock('ls -la')).toBe('```\nls -la\n```')
+  })
+  it('defuses embedded triple-backticks so the fence cannot break', () => {
+    const out = preBlock('a```b')
+    expect(out.startsWith('```\n')).toBe(true)
+    expect(out.endsWith('\n```')).toBe(true)
+    // interior fence broken up (zero-width space injected)
+    expect(out.slice(4, -4)).not.toContain('```')
+  })
+})
+
+describe('getCommandArgs', () => {
+  it('prefers ctx.match when present', () => {
+    const ctx = { match: '  foo bar  ', msg: { text: '/cmd other' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('foo bar')
+  })
+  it('falls back to parsing the message text', () => {
+    const ctx = { match: undefined, msg: { text: '/restart alpha beta' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('alpha beta')
+  })
+  it('returns empty string for a bare command', () => {
+    const ctx = { match: '', msg: { text: '/status' } } as unknown as Context
+    expect(getCommandArgs(ctx)).toBe('')
+  })
+})
+
+describe('hasDemoFlag', () => {
+  it('matches trailing demo token case-insensitively', () => {
+    expect(hasDemoFlag('demo')).toBe(true)
+    expect(hasDemoFlag('show DEMO')).toBe(true)
+  })
+  it('does not match demo as a prefix of another token', () => {
+    expect(hasDemoFlag('demo-foo')).toBe(false)
+    expect(hasDemoFlag('demo mid')).toBe(false)
+  })
+})
+
+describe('assertSafeAgentName', () => {
+  it('accepts alphanumeric/hyphen/underscore names and the all keyword', () => {
+    expect(() => assertSafeAgentName('my-agent_01')).not.toThrow()
+    expect(() => assertSafeAgentName('all')).not.toThrow()
+  })
+  it('rejects shell metacharacters and over-long names', () => {
+    expect(() => assertSafeAgentName('a;rm -rf')).toThrow(/invalid agent name/)
+    expect(() => assertSafeAgentName('x'.repeat(65))).toThrow(/invalid agent name/)
+  })
+})
+
+describe('formatAuthOutputForTelegram', () => {
+  it('returns a plain pre-block when no URL is present', () => {
+    const { text, url } = formatAuthOutputForTelegram('\x1b[32mno link here\x1b[0m')
+    expect(url).toBeNull()
+    expect(text).toBe('```\nno link here\n```')
+  })
+  it('extracts the URL, drops CLI hint lines, and appends mobile guidance', () => {
+    const raw = [
+      'Started Claude auth for agent overlord',
+      'Open this URL to authorize:',
+      'https://claude.ai/oauth/authorize?code=abc123',
+      'switchroom auth code overlord <code>',
+      'Cancel with: switchroom auth cancel overlord',
+    ].join('\n')
+    const { text, url } = formatAuthOutputForTelegram(raw)
+    expect(url).toBe('https://claude.ai/oauth/authorize?code=abc123')
+    expect(text).not.toContain('switchroom auth code')
+    expect(text).not.toContain('Cancel with:')
+    expect(text).toContain('**Started Claude auth for agent overlord**')
+    expect(text).toContain('_Open this URL to authorize:_')
+    expect(text.trimEnd().endsWith(url as string)).toBe(true)
+  })
+})
+
+describe('keyboards', () => {
+  it('buildAuthUrlKeyboard produces a single url button', () => {
+    const kb = buildAuthUrlKeyboard('https://example.com/x')
+    const rows = kb.inline_keyboard
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toHaveLength(1)
+    expect(rows[0][0]).toMatchObject({ text: '🔐 Open Claude auth', url: 'https://example.com/x' })
+  })
+  it('buildDeferredSecretKeyboard encodes unlock/cancel callback_data', () => {
+    const kb = buildDeferredSecretKeyboard('123:456')
+    const row = kb.inline_keyboard[0]
+    expect(row.map(b => (b as { callback_data?: string }).callback_data)).toEqual([
+      'vd:unlock:123:456',
+      'vd:cancel:123:456',
+    ])
+  })
+  it('buildDeferredSecretKeyboard throws on a 64-byte callback_data overflow', () => {
+    expect(() => buildDeferredSecretKeyboard('9'.repeat(80))).toThrow(/callback_data overflow/)
+  })
+  it('buildDoctorScopeKeyboard offers fleet and self scopes', () => {
+    const row = buildDoctorScopeKeyboard().inline_keyboard[0]
+    expect(row.map(b => (b as { callback_data?: string }).callback_data)).toEqual([
+      'dr:fleet',
+      'dr:self',
+    ])
+  })
+})
+
+describe('renderVaultOpFailure', () => {
+  it('falls back to a raw pre-block for unrecognised CLI output', () => {
+    const out = renderVaultOpFailure('get', 'some random failure', 'mykey')
+    expect(out).toBe('**vault get failed:**\n```\nsome random failure\n```')
+  })
+  it('routes recognised broker-denied markers through the structured renderer', () => {
+    const out = renderVaultOpFailure('get', 'VAULT-BROKER-DENIED: no grant for key', 'mykey')
+    expect(out).not.toContain('**vault get failed:**')
+    expect(out.length).toBeGreaterThan(0)
+  })
+})
+
+describe('statusIcon', () => {
+  it('maps statuses to glyphs', () => {
+    expect(statusIcon('running')).toBe('🟢')
+    expect(statusIcon('active')).toBe('🟢')
+    expect(statusIcon('stopped')).toBe('🔴')
+    expect(statusIcon('failed')).toBe('⚠️')
+    expect(statusIcon('whatever')).toBe('⚪')
+  })
+})
+
+describe('renderAuthCodeOutcome', () => {
+  it('returns null for success or missing outcome', () => {
+    expect(renderAuthCodeOutcome(null)).toBeNull()
+    expect(renderAuthCodeOutcome({ kind: 'success' } as never)).toBeNull()
+  })
+  it('renders invalid-code with escaped pane tail', () => {
+    const out = renderAuthCodeOutcome({ kind: 'invalid-code', paneTailText: 'bad*code' } as never)
+    expect(out).toContain('Code rejected by Claude')
+    expect(out).toContain('bad\\*code')
+  })
+  it('renders pane-not-ready and timeout variants', () => {
+    expect(renderAuthCodeOutcome({ kind: 'pane-not-ready' } as never)).toContain('Auth pane not ready')
+    expect(renderAuthCodeOutcome({ kind: 'timeout' } as never)).toContain('Still waiting after 2 min')
+  })
+})
+
+describe('formatDoctorReport', () => {
+  it('swaps check glyphs for traffic lights inside a pre block', () => {
+    const raw = '\x1b[32m✓ ok check\x1b[0m\n✗ bad check\n! warn check'
+    expect(formatDoctorReport(raw)).toBe('```\n🟢 ok check\n🔴 bad check\n🟡 warn check\n```')
+  })
+  it('handles empty output', () => {
+    expect(formatDoctorReport('  \x1b[0m ')).toBe('doctor: no output')
+  })
+})