switchroom 0.19.41 → 0.19.43

package/telegram-plugin/shared/bot-runtime.ts

@@ -5,8 +5,8 @@
  * standalone foreman bot before its retirement.
  *
  * What lives here:
- *   - `createRobustApiCall` — thin re-export of createRetryApiCall pre-wired
- *     with stderr logging (mirrors how gateway.ts constructs `robustApiCall`).
+ *   - `installTgPostLogger` / `installRichMarkdownGuard` — the grammy API
+ *     transformers every outbound call transits.
  *   - `makeSwitchroomExec` / `makeSwitchroomExecCombined` — factory fns for
  *     the switchroom CLI exec helpers (callers pass their own CLI path / config
  *     env so each process can be configured independently).
@@ -28,8 +28,7 @@ import { execFileSync, spawnSync } from 'child_process'
 import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
-import { createRetryApiCall, classifyBenignTelegram400 } from '../retry-api-call.js'
-import { makeFloodWaitRecorder, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
+import { classifyBenignTelegram400, willRetryTelegramFailure } from '../retry-api-call.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { shouldEmitTgPost, type TgPostStatus } from './gw-trace-gate.js'
 import { guardAccidentalFormatting } from '../rich-send.js'
@@ -102,7 +101,7 @@ function shortDesc(raw: string | undefined): string {
  *
  * Log shape (one line per POST, on both success and failure):
  *
- *   tg-post method=<m> chat=<id> thread=<id|-> parse_mode=<HTML|MarkdownV2|none> bytes=<n> hash=<sha1-12> status=<ok|benign|err> err=<class-or--> code=<http-or--> desc=<short|-->
+ *   tg-post method=<m> chat=<id> thread=<id|-> parse_mode=<HTML|MarkdownV2|none> bytes=<n> hash=<sha1-12> status=<ok|benign|retry|err> err=<class-or--> code=<http-or--> desc=<short|-->
  *
  * TRUTHFULNESS (#3927): grammY resolves the transformer chain with the raw
  * `ApiResponse`, and only converts `{ok:false}` into a thrown `GrammyError`
@@ -127,6 +126,17 @@ function shortDesc(raw: string | undefined): string {
  * instead, so promoting real rejections out of `status=ok` doesn't bury
  * `grep status=err` under high-volume card-repaint no-ops.
  *
+ * ATTEMPT vs OUTCOME (#3931): this transformer runs INSIDE `fn()`, i.e. below
+ * the retry policy, so it sees each attempt separately. A 429 that
+ * `createRetryApiCall` sleeps and then retries successfully is not a delivery
+ * failure — but it used to write `status=err`, and fleet-health's
+ * `reply-delivery-failure` detector (`src/fleet-health/detect.ts`) matches per
+ * LINE, so every retried-and-DELIVERED reply raised a severity-3 alert. The
+ * retry policy now publishes its attempt context (`_getTgAttemptContext`), and
+ * a failure the policy is about to retry is logged `status=retry` instead.
+ * `status=err` is therefore an OUTCOME: the logical send is over and nothing
+ * landed. Nothing is hidden — the retry lines are still emitted verbatim.
+ *
  * Body content is never logged — only its length and a 12-char sha1 prefix
  * so we can recognise repeated identical sends without leaking PII. The
  * `code` field carries the Telegram error_code (400/403/429/etc.) on
@@ -164,12 +174,27 @@ export function installTgPostLogger(bot: Bot): void {
       // converts `{ok:false}` to a thrown GrammyError only after this chain
       // returns (see the docblock). Same defensive shape as the edit fuse's
       // `runObserved` (edit-flood-fuse.ts).
-      const r = res as unknown as { ok?: boolean; error_code?: number; description?: string }
+      const r = res as unknown as {
+        ok?: boolean
+        error_code?: number
+        description?: string
+        parameters?: { retry_after?: number }
+      }
       if (r != null && typeof r === 'object' && r.ok === false) {
         const code = r.error_code
         const benign = classifyBenignTelegram400(code, r.description)
+        // #3931 — an attempt the enclosing retry policy is about to repeat is
+        // not an outcome; label it `retry` so it is never read as a delivery
+        // failure. Terminal rejections keep `status=err`.
+        const retrying =
+          benign === null &&
+          willRetryTelegramFailure({
+            errorCode: code ?? null,
+            retryAfterSec: r.parameters?.retry_after ?? null,
+            message: r.description ?? null,
+          })
         emit(
-          benign !== null ? 'benign' : 'err',
+          benign !== null ? 'benign' : retrying ? 'retry' : 'err',
           `telegram_${code ?? 'unknown'}`,
           code != null ? String(code) : '-',
           shortDesc(r.description),
@@ -186,7 +211,26 @@ export function installTgPostLogger(bot: Bot): void {
       const rawDesc = err instanceof GrammyError
         ? (err as GrammyError).description
         : (err instanceof Error ? err.message : '')
-      emit('err', errClass, code, shortDesc(rawDesc))
+      // #3931 — same attempt-vs-outcome rule as the resolved-rejection branch
+      // above. This branch carries the transport (`HttpError`) failures, whose
+      // transient members the retry policy backs off and repeats.
+      //
+      // #4123 — pass `cause`, not just `message`. grammy rewrites every
+      // transport failure's message to `Network request for '<method>' failed!`,
+      // so a message-only shape classified EVERY transport blip as terminal and
+      // wrote `status=err` — which fleet-health escalates as a
+      // `reply-delivery-failure` even when the next attempt delivers. The
+      // predicate needs the error itself to classify by type.
+      const retrying = willRetryTelegramFailure({
+        errorCode: err instanceof GrammyError ? (err as GrammyError).error_code : null,
+        retryAfterSec:
+          err instanceof GrammyError
+            ? ((err as GrammyError).parameters?.retry_after ?? null)
+            : null,
+        message: err instanceof Error ? err.message : String(err ?? ''),
+        cause: err,
+      })
+      emit(retrying ? 'retry' : 'err', errClass, code, shortDesc(rawDesc))
       throw err
     }
   })
@@ -248,32 +292,23 @@ export function installRichMarkdownGuard(bot: Bot): void {
   })
 }
 
-// ─── robustApiCall factory ────────────────────────────────────────────────
-
-/**
- * Creates a robust API call wrapper pre-wired with stderr logging.
- * This is exactly how gateway.ts constructs its `robustApiCall`.
- *
- * Usage:
- *   const robustApiCall = createRobustApiCall()
- */
-export function createRobustApiCall(opts: { floodStatePath?: string } = {}) {
-  return createRetryApiCall({
-    log: (line) => process.stderr.write(line),
-    // #2923: persist every observed 429 flood-wait window so a restart during
-    // the ban can suppress non-essential sends (boot cards) instead of feeding
-    // the per-bot flood counter and prolonging the ban.
-    // #3084: and refuse to issue a call while that window is still open —
-    // otherwise the card heartbeats re-drive a request into the ban every
-    // few seconds once the policy stops sleeping long waits.
-    ...(opts.floodStatePath
-      ? {
-          onFloodWait: makeFloodWaitRecorder(opts.floodStatePath),
-          floodWaitRemainingMs: makeFloodWaitProbe(opts.floodStatePath),
-        }
-      : {}),
-  })
-}
+// ─── robustApiCall factory: REMOVED (#3863) ───────────────────────────────
+//
+// `createRobustApiCall` used to live here as a second `createRetryApiCall`
+// wiring "pre-wired with stderr logging", kept for a standalone foreman bot
+// that was retired. It had ZERO production callers, and its breaker hooks were
+// OPTIONAL (`floodStatePath` defaulted to absent), so the one thing a second
+// wiring must never be — a send path blind to the shared flood window — was
+// its default. Docblocks in `flood-circuit-breaker.ts` and `flood-429-ledger.ts`
+// cited it as a live wiring, which is how a dead function became load-bearing
+// documentation for the breaker's completeness argument.
+//
+// There is one retry wiring per process, built at its own callsite with both
+// breaker hooks (`gateway.ts`'s `robustApiCall`, `outbox-sweep.ts`'s sweep
+// caller) and enforced by `scripts/check-retry-flood-hooks.mjs`. Do not
+// reintroduce a convenience factory here: it re-creates the hook-optional
+// default this deletion removed. `tests/no-robust-api-call-factory.test.ts`
+// guards that.
 
 // ─── Markdown escape helpers (#2669) ──────────────────────────────────────
 

package/telegram-plugin/shared/gw-trace-gate.ts

@@ -68,8 +68,18 @@ const ZERO_SIGNAL_POLL_METHODS = new Set(['getUpdates', 'getMe'])
  * `status=err` signal in high-volume card-repaint no-ops: `grep status=err`
  * stays a list of real failures, and the benign lines are still there,
  * honestly labelled, for anyone who wants them.
+ *
+ * `retry` (#3931) is a REJECTED call that the enclosing retry policy is about
+ * to attempt AGAIN — a 429 under the in-process sleep ceiling, or a transient
+ * transport error with attempts left. It is not an outcome: the logical send
+ * may still be delivered by the next attempt, and usually is. It exists
+ * because `status=err` is consumed as a delivery FAILURE by fleet-health's
+ * `reply-delivery-failure` detector (`src/fleet-health/detect.ts`), which
+ * matches per LINE — so labelling a survivable attempt `err` escalated
+ * successfully delivered replies. Post-#3931 a `status=err` line means the
+ * logical send is over and it did not land.
  */
-export type TgPostStatus = 'ok' | 'benign' | 'err'
+export type TgPostStatus = 'ok' | 'benign' | 'err' | 'retry'
 
 /**
  * Decide whether a `tg-post` line should be written.
@@ -79,6 +89,8 @@ export type TgPostStatus = 'ok' | 'benign' | 'err'
  *
  * Always emitted:
  *   - any `status=err` (real failures — the whole point of the log),
+ *   - any `status=retry` (the survivable attempts behind a flood episode —
+ *     suppressing them would hide the run-up to a ban, #3931),
  *   - every other method's `ok` line (sendMessage/editMessageText/... are
  *     genuine outbound observability, #656/#657),
  *   - `status=benign` on any non-poll method — same volume as the
@@ -90,7 +102,7 @@ export function shouldEmitTgPost(
   verbose: boolean = gwTraceVerbose,
 ): boolean {
   if (verbose) return true
-  if (status === 'err') return true
+  if (status === 'err' || status === 'retry') return true
   return !ZERO_SIGNAL_POLL_METHODS.has(method)
 }
 

package/telegram-plugin/silent-end.ts

@@ -66,6 +66,22 @@ export interface SilentEndState {
    * absent for the zero-prose (genuinely empty) silent-end.
    */
   pendingText?: string
+  /**
+   * W1-d follow-up (#4141) — one of THIS turn's reply-tool calls came back
+   * `is_error: true`, so `pendingText` is prose the model wrote *after* its
+   * delivery attempt failed, not text it chose to send as the answer.
+   *
+   * Stamped by the Stop hook's single-writer election
+   * (`silent-end-interrupt-stop.mjs` → `buildNextState`), the only component
+   * that can see the transcript; the gateway's own `writeSilentEndState` never
+   * sets it. Consumed by `deliverCapturedProse`, which prefixes a one-line
+   * provenance banner so the recipient is told the text was scraped off a
+   * failed turn rather than sent as an answer.
+   *
+   * Optional and only ever `true`: absent means "no positive evidence of a
+   * throw", which delivers exactly as before. It never suppresses.
+   */
+  replyToolThrewThisTurn?: boolean
 }
 
 export interface SilentEndDeps {
@@ -320,8 +336,16 @@ export const CAPTURED_PROSE_MIN_CHARS = 200
 export interface CapturedProseDecision {
   /** True → the gateway should deliver `text` directly on this silent-end. */
   deliver: boolean
-  /** The prose to deliver; present iff `deliver === true`. */
+  /** The prose to deliver; present iff `deliver === true`. RAW — never framed
+   *  here, so the caller's dedup and journal keys stay computed on the same
+   *  bytes the sweep path uses (#4141). */
   text?: string
+  /**
+   * #4141 — the persisted record says this turn's reply tool threw. Surfaced
+   * (not acted on) so `deliverCapturedProse` can state the prose's provenance.
+   * `true` only on positive evidence; never affects `deliver`.
+   */
+  replyToolThrewThisTurn?: boolean
   /** Machine-readable reason (for logs / tests). */
   reason:
     | 'captured-prose'
@@ -394,7 +418,15 @@ export function decideCapturedProseDelivery(
   if (deps?.backstopDeliveredNonceHit?.(state.turnId) === true) {
     return { deliver: false, reason: 'already-delivered' }
   }
-  return { deliver: true, text, reason: 'captured-prose' }
+  return {
+    deliver: true,
+    text,
+    reason: 'captured-prose',
+    // #4141: pass the hook's raw signal through untouched. Deliberately placed
+    // AFTER every `deliver:false` gate above — the banner is a labelling
+    // concern, and must never become an input to whether we deliver at all.
+    ...(state.replyToolThrewThisTurn === true ? { replyToolThrewThisTurn: true } : {}),
+  }
 }
 
 /**

package/telegram-plugin/status-no-truncate.ts

@@ -60,23 +60,38 @@ export const STATUS_LINE_MAX = 200
 export const STATUS_CARD_CHAR_BUDGET = RICH_MESSAGE_MAX_CHARS
 
 /**
- * Indent marker for a nested (foreground sub-agent) step line.
- *
- * NOTE: the three leading spaces here are ASCII, which Telegram's server-side
- * markdown parser DROPS — the visible nesting cue on this surface is the `↳`
- * glyph, not the indent. That is a known latent wart, deliberately left alone
- * — it needs its own live render check on the single-worker / agent card,
- * tracked in #3668. It is NOT broken by the #3662 mechanism (nothing here
- * depends on the ASCII run being visible), so it is not fixed here. If #3668
- * ever does make it a real indent, use U+2800 — NOT U+00A0, which was tried in
- * #3662 and renders flat. Do NOT copy this string as the idiom for a real
- * indent.
- *
- * @see WORKER_STEP_INDENT — the U+2800 indent used for actual left-nesting on
- * the combined (2+ worker) card, and the evidence for why ASCII (and U+00A0)
- * cannot work.
+ * Indent marker for a nested (foreground sub-agent) step line: three U+2800
+ * BRAILLE PATTERN BLANK, then the `↳` glyph.
+ *
+ * Until #3668 the indent was three ASCII spaces, which Telegram's server-side
+ * markdown parser LEFT-TRIMS off a content line — so the child block rendered
+ * FLAT against its parent steps and the only surviving nesting cue was the `↳`
+ * glyph. This constant now uses the SAME idiom as {@link WORKER_STEP_INDENT}
+ * for exactly the same reason, and there is only one indent idiom on the card
+ * surfaces again.
+ *
+ * The evidence is not an inference about Telegram's parser: U+2800 is general
+ * category So (Symbol, other), not Zs, so no whitespace-trimming rule — ASCII
+ * `\s`, Unicode `White_Space`, or `Zs` — can classify it as whitespace, yet it
+ * renders as blank width. It is ALSO live-verified: on 2026-07-26 four
+ * candidates were sent to a real phone in one message — three U+00A0 rendered
+ * FLAT (the #3662 failure), three U+2800 INDENTED CORRECTLY, a leading `↳ `
+ * rendered as visible ink, and a leading `· ` was promoted into a real list
+ * bullet. See {@link WORKER_STEP_INDENT}'s comment for the full record.
+ *
+ * The `↳ ` glyph is KEPT: it is what distinguishes a foreground sub-agent's
+ * step from the parent's own steps on a card where both appear, and the
+ * indent is what makes the block read as nested. The blanks lead so the
+ * glyph is not the thing being trimmed.
+ *
+ * Guard: `nested-prefix-indent.test.ts` asserts the PROPERTY (no character of
+ * the indent is whitespace under any of the three rules), not just the bytes —
+ * a byte-only assertion is what let #3662 ship green and inert.
+ *
+ * @see WORKER_STEP_INDENT — the same U+2800 idiom for the combined
+ * (2+ worker) card, and the full evidence for why ASCII and U+00A0 cannot work.
  */
-export const NESTED_PREFIX = '   ↳ '
+export const NESTED_PREFIX = '\u2800\u2800\u2800↳ '
 
 /**
  * Left indent for a step line rendered UNDER a worker header on the combined

package/telegram-plugin/stream-controller.ts

@@ -27,6 +27,12 @@ import {
 import { richMessage, isParseEntitiesError } from './rich-send.js'
 import { renderOutboundChunks } from './render/rich-render.js'
 import { isSendGateShed, type SendGateOpts } from './send-gate.js'
+import {
+  buildReplyParameters,
+  dropQuoteFromSendOpts,
+  isQuoteRejectionError,
+  sendOptsHaveQuote,
+} from './reply-quote.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -59,8 +65,14 @@ export interface StreamSendOpts {
    * message. Only meaningful on the initial `sendMessage` — `editMessageText`
    * cannot add a quote reference to an existing message, so the controller
    * strips this from edit opts internally.
+   *
+   * `quote` is a Bot API **String** — the quoted substring itself. The optional
+   * offset is a SIBLING `quote_position` Integer, which this plugin
+   * deliberately never emits. Typing it as an object is what produced
+   * `400 field "quote" must be of type String` on every quoted reply; see
+   * `reply-quote.ts`.
    */
-  reply_parameters?: { message_id: number; quote?: { text: string; position: number } }
+  reply_parameters?: { message_id: number; quote?: string }
   /**
    * Inline keyboard markup. Included in both sendMessage and editMessageText
    * so that inline buttons persist through text edits. Without this,
@@ -121,7 +133,10 @@ export interface StreamControllerConfig {
   /**
    * Optional quote text for surgical quoting. When set along with
    * `replyToMessageId`, the initial send includes
-   * `reply_parameters: { message_id, quote: { text, position: 0 } }`.
+   * `reply_parameters: { message_id, quote }` — `quote` is a Bot API String
+   * (see `reply-quote.ts`). A quote Telegram cannot find in the replied-to
+   * message is dropped and the send retried unquoted, so the answer still
+   * lands.
    */
   quoteText?: string
   /**
@@ -222,14 +237,16 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     ...(disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
     ...(replyMarkup != null ? { reply_markup: replyMarkup } : {}),
   }
-  const sendOpts: StreamSendOpts = {
+  // `let`, not `const`: a quote Telegram cannot find in the replied-to message
+  // is stripped ONCE for the whole stream (see sendPieceWithQuoteFallback) —
+  // re-attaching it to the next piece would just 400 again.
+  let sendOpts: StreamSendOpts = {
     ...baseOpts,
     ...(replyToMessageId != null
       ? {
-          reply_parameters: {
-            message_id: replyToMessageId,
-            ...(quoteText != null ? { quote: { text: quoteText, position: 0 } } : {}),
-          },
+          // `quote` is a Bot API String; `quote_position` is a separate sibling
+          // Integer we deliberately don't emit. See reply-quote.ts.
+          reply_parameters: buildReplyParameters(replyToMessageId, quoteText),
         }
       : {}),
     ...(protectContent === true ? { protect_content: true } : {}),
@@ -263,6 +280,24 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     delete richOpts.link_preview_options
     return bot.api.sendRichMessage(chatId, richMessage(piece.text), richOpts)
   }
+  // Send a piece, degrading gracefully when the SURGICAL QUOTE is the thing
+  // Telegram rejected. `reply_parameters.quote` must be an exact substring of
+  // the replied-to message; when it isn't, the 400 kills a perfectly good
+  // answer. Drop the highlight (for this send and every later one on this
+  // stream) and re-send — the reply still lands, still threaded under the same
+  // message.
+  const sendPieceWithQuoteFallback = async (piece: { text: string; rich: boolean }) => {
+    try {
+      return await sendPiece(piece, sendOpts)
+    } catch (err) {
+      if (!isQuoteRejectionError(err) || !sendOptsHaveQuote(sendOpts)) throw err
+      warn?.(
+        `stream-controller: quote not found in the replied-to message — re-sending without the quote (${err instanceof Error ? err.message : String(err)})`,
+      )
+      sendOpts = dropQuoteFromSendOpts(sendOpts)
+      return await sendPiece(piece, sendOpts)
+    }
+  }
   const editPiece = (id: number, piece: { text: string; rich: boolean }, opts: StreamSendOpts) => {
     if (!piece.rich) return bot.api.editMessageText(chatId, id, piece.text, opts)
     return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
@@ -395,7 +430,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     }
     // First emission of this tail piece → a fresh follow-up message.
     try {
-      const sent = await retry(() => sendPiece(piece, sendOpts), { threadId, chat_id: chatId })
+      const sent = await retry(() => sendPieceWithQuoteFallback(piece), { threadId, chat_id: chatId })
       tailIds[ti] = sent.message_id
       tailLastText[ti] = piece.text
       onSend?.(sent.message_id, piece.text.length)
@@ -435,7 +470,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       let anchorId: number | undefined
       try {
         const sent = await retry(
-          () => sendPiece(head, sendOpts),
+          () => sendPieceWithQuoteFallback(head),
           { threadId, chat_id: chatId },
         )
         anchorId = sent.message_id

package/telegram-plugin/stream-reply-handler.ts

@@ -109,9 +109,11 @@ export interface StreamReplyArgs {
   disable_notification?: boolean
   /**
    * Optional surgical quote text. When set along with `reply_to`, the initial
-   * send includes `reply_parameters: { message_id, quote: { text, position: 0 } }`
-   * so Telegram highlights the specific quoted sentence rather than the whole
-   * referenced message. Ignored when `reply_to` is absent.
+   * send includes `reply_parameters: { message_id, quote }` — `quote` is a Bot
+   * API String (see `reply-quote.ts`) — so Telegram highlights the specific
+   * quoted sentence rather than the whole referenced message. It must be an
+   * exact substring of the referenced message; one Telegram cannot find is
+   * dropped and the send retried unquoted. Ignored when `reply_to` is absent.
    */
   quote_text?: string
   /**

package/telegram-plugin/tests/boot-card-render.test.ts

@@ -14,6 +14,7 @@
 
 import { describe, it, expect } from 'vitest'
 import { renderBootCard, resolvePersonaName } from '../gateway/boot-card.js'
+import { NESTED_PREFIX } from '../status-no-truncate.js'
 
 describe('renderBootCard — quiet by default', () => {
   it('returns one-line ack with default ✅ when no probes and no restart reason', () => {
@@ -153,7 +154,7 @@ describe('renderBootCard — degraded conditions', () => {
       },
     })
     expect(out).toContain('🟡 **Skills**  10/10 dangling')
-    expect(out).toContain('    ↳ Run `switchroom agent reconcile lawgpt` to rebuild symlinks')
+    expect(out).toContain(`${NESTED_PREFIX}Run \`switchroom agent reconcile lawgpt\` to rebuild symlinks`)
   })
 
   it('crash row carries a tail-logs next-step', () => {

package/telegram-plugin/tests/card-budget-never-overflows.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest'
+import { renderStatusCard, renderCombinedWorkerFeed } from '../tool-activity-summary.js'
+import { fitCardToBudget, hardTruncateCard, renderCardSpec } from '../card-layout.js'
+import { STATUS_CARD_CHAR_BUDGET } from '../status-no-truncate.js'
+
+/**
+ * #3833 (and its duplicate #3682) — a rendered card must NEVER exceed
+ * `STATUS_CARD_CHAR_BUDGET`. An over-budget card is not a cosmetic problem: it
+ * is rejected by the Bot API, so the user's progress card simply does not
+ * appear (or stops updating) for the whole turn.
+ *
+ * Two defects produced over-budget cards, and both are asserted here:
+ *
+ *  1. UNDER-COUNTED FIXED COST. The deepest shrink level charged its
+ *     header/footer as `[...chrome, ...footer].join('\n')`, but cards are
+ *     rendered by `stackCard`, which emits a collapse separator plus a
+ *     two-space GFM hard break at every line boundary — 4 chars per boundary,
+ *     not 1 — and it also charges the collapsed parent-marker line. The budget
+ *     the fitter handed the body was therefore too generous and the card came
+ *     out a few chars over.
+ *
+ *  2. NO RE-CHECK ON THE LAST RESORT. `fitCardToBudget` returned the deepest
+ *     render unmeasured. When the FIXED chrome alone is over budget (the #3682
+ *     repro: a 40k-char worker description), no shrink level can help — every
+ *     level keeps the chrome — so a 40k-char card went to the wire.
+ */
+
+const HEADER = { emoji: '🛠', label: 'Worker', elapsedMs: 61_000, toolCount: 7, state: 'running' as const }
+
+function card(opts: { desc?: string; steps?: string[]; children?: string[]; final?: boolean; result?: string }): string {
+  return renderStatusCard({
+    header: { ...HEADER, description: opts.desc ?? 'a task', state: opts.final === true ? 'done' : 'running' },
+    steps: opts.steps ?? ['step one'],
+    childSteps: opts.children,
+    final: opts.final ?? false,
+    stepCount: 3,
+    result: opts.result != null ? { emoji: '✅', text: opts.result } : undefined,
+  })!
+}
+
+describe('a rendered card never exceeds the char budget (#3833 / #3682)', () => {
+  it('the #3682 repro — a 40k-char description — comes back under budget', () => {
+    // Fail-before: 40069 chars against a 32768 budget on origin/main.
+    const out = card({ desc: 'd'.repeat(40_000), steps: ['x'.repeat(4_000)], children: ['y'.repeat(4_000)] })
+    expect(out.length).toBeLessThanOrEqual(STATUS_CARD_CHAR_BUDGET)
+    // And it is still a card, not an empty string.
+    expect(out.length).toBeGreaterThan(100)
+    expect(out.startsWith('🛠')).toBe(true)
+  })
+
+  it('the join-cost under-count boundary — every description length near the budget fits', () => {
+    // Fail-before: on origin/main the lengths 32693…32800 each rendered 1…98
+    // chars OVER budget. That band is exactly the fixed-cost under-count: the
+    // renderer's per-boundary separator + hard break, which the arithmetic
+    // estimate charged as one newline.
+    const over: Array<{ n: number; by: number }> = []
+    for (let n = 32_600; n <= 32_900; n++) {
+      const out = card({ desc: 'd'.repeat(n), steps: ['a', 'b', 'c'], result: 'done' })
+      if (out.length > STATUS_CARD_CHAR_BUDGET) over.push({ n, by: out.length - STATUS_CARD_CHAR_BUDGET })
+    }
+    expect(over).toEqual([])
+  })
+
+  it('PROPERTY: no combination of description / steps / children / result overflows', () => {
+    // A deterministic sweep over the shape space rather than a handful of
+    // hand-picked cases: the guarantee is universal, so the test is too.
+    //
+    // Fillers matter as much as sizes — escaping EXPANDS text (`&` → `&amp;`
+    // is 5×, markdown specials are 2×), which is what the fitter's clip loop
+    // has to converge against, and `👍` is astral so a naive slice could split
+    // a surrogate pair.
+    //
+    // Every filler is swept at the small/medium sizes; the huge sizes (where a
+    // single render costs seconds purely in `escapeMarkdown`, unchanged by this
+    // PR) are swept with the cheap-but-still-expanding fillers.
+    const cases: Array<{ size: number; fill: string }> = []
+    for (const size of [0, 1, 7, 200, 4_000, 16_000]) {
+      for (const fill of ['x', '&', '_*[`', '👍', 'é']) cases.push({ size, fill })
+    }
+    for (const size of [32_700, 33_000, 90_000]) {
+      for (const fill of ['x', '&', '👍']) cases.push({ size, fill })
+    }
+    for (const { size, fill } of cases) {
+      const blob = fill.repeat(Math.ceil(size / fill.length)).slice(0, size)
+      for (const final of [false, true]) {
+        for (const withChildren of [false, true]) {
+          const out = renderStatusCard({
+            header: { ...HEADER, description: blob, state: final ? 'done' : 'running' },
+            steps: [blob, blob, 'plain step'],
+            childSteps: withChildren ? [blob, blob] : undefined,
+            final,
+            liveSuffix: ' · 22s',
+            stepCount: 12,
+            result: { emoji: '✅', text: blob },
+          })
+          if (out == null) continue
+          expect(
+            out.length,
+            `over budget: size=${size} fill=${JSON.stringify(fill)} final=${final} children=${withChildren}`,
+          ).toBeLessThanOrEqual(STATUS_CARD_CHAR_BUDGET)
+          // Never blanked, and never sliced through a surrogate pair.
+          expect(out.length).toBeGreaterThan(0)
+          expect(/[\uD800-\uDBFF]$/.test(out)).toBe(false)
+        }
+      }
+    }
+  }, 60_000)
+
+  it('PROPERTY: the combined worker card also stays under budget for any fan-out', () => {
+    for (const rows of [1, 2, 6, 25]) {
+      for (const size of [50, 5_000, 40_000]) {
+        const out = renderCombinedWorkerFeed(
+          Array.from({ length: rows }, (_, i) => ({
+            ordinal: i + 1,
+            description: 'w'.repeat(size),
+            currentStep: 's'.repeat(size),
+            historyLines: ['h'.repeat(size), 'h2'],
+            elapsedMs: 60_000,
+            toolCount: 3,
+          })),
+          { maxRows: 8 },
+        )!
+        expect(out.length, `rows=${rows} size=${size}`).toBeLessThanOrEqual(STATUS_CARD_CHAR_BUDGET)
+      }
+    }
+  })
+
+  it('fitCardToBudget itself guarantees the budget even when every level overflows', () => {
+    // The mechanism, isolated from any particular card: a build function whose
+    // deepest level is still hopeless. Fail-before: this returned the raw
+    // 50k-char render.
+    const huge = 'q'.repeat(50_000)
+    const out = fitCardToBudget(() => ({ spec: { chrome: [huge], sections: [], footer: [] } }), 3)
+    expect(out.length).toBeLessThanOrEqual(STATUS_CARD_CHAR_BUDGET)
+    expect(out.length).toBeGreaterThan(0)
+  })
+
+  it('fitCardToBudget still returns the FIRST fitting level untouched', () => {
+    // The backstop must not change the normal path: a level that fits is
+    // returned byte-for-byte, and deeper levels are never built.
+    const built: number[] = []
+    const spec = { chrome: ['🛠 **Worker**'], sections: [], footer: ['_✓ 3 steps_'] }
+    const out = fitCardToBudget((level) => {
+      built.push(level)
+      return { spec }
+    }, 5)
+    expect(built).toEqual([0])
+    expect(out).toBe(renderCardSpec(spec))
+  })
+
+  it('hardTruncateCard cuts at a line boundary and never returns invalid UTF-16', () => {
+    const lines = ['aaaa', 'bbbb', 'cccc'].join('  \n')
+    // Budget lands inside the third line → cut back to the second boundary.
+    const cut = hardTruncateCard(lines, 12)
+    expect(cut.length).toBeLessThanOrEqual(12)
+    expect(cut).toBe('aaaa  \nbbbb')
+    // Under budget → identity.
+    expect(hardTruncateCard(lines, 1000)).toBe(lines)
+    // A single over-long line with an astral char at the cut → no lone surrogate.
+    const astral = '👍'.repeat(50)
+    const sliced = hardTruncateCard(astral, 11)
+    expect(sliced.length).toBeLessThanOrEqual(11)
+    expect(/[\uD800-\uDBFF]$/.test(sliced)).toBe(false)
+  })
+})