switchroom 0.13.35 → 0.13.36

package/telegram-plugin/gateway/config-approval-handler.ts

@@ -7,6 +7,7 @@ import type {
   RequestConfigApprovalMessage,
   RequestConfigFinalizeMessage,
 } from "./ipc-protocol.js";
+import { truncateRawToFit } from "./oversize-card-body.js";
 
 /** Pending approval state — in-memory only (no SQLite per RFC §3.4). */
 interface PendingConfigApproval {
@@ -50,6 +51,18 @@ export interface ConfigApprovalHandlerDeps {
     messageId: number;
     text: string;
   }) => Promise<void>;
+  /**
+   * Send the full diff as a `.patch` document attachment when the
+   * card body exceeds Telegram's 4096-char sendMessage limit
+   * (#1762). Best-effort — failures are logged and do NOT block the
+   * approval flow (the truncated card is still actionable).
+   */
+  postAttachment?: (args: {
+    chatId: number | string;
+    threadId?: number;
+    filename: string;
+    content: string;
+  }) => Promise<void>;
   log?: (msg: string) => void;
 }
 
@@ -59,19 +72,107 @@ export interface ConfigApprovalHandlerDeps {
  * diffs may be truncated by the API; the validator already caps
  * unified_diff at ~63 KiB so practical fleet edits fit comfortably.
  */
+/**
+ * Truncate a unified diff for inline display in the card body when
+ * the full diff would exceed Telegram's 4096-char sendMessage limit.
+ * Caps at `maxLines` lines AND at `maxChars` *raw* characters
+ * (whichever trips first), then appends a sentinel pointing to the
+ * attached `.patch` document. (#1762)
+ *
+ * NOTE: This is a *raw-input* cap. HTML escaping happens downstream
+ * and can inflate by up to 5x per char (`&` → `&amp;`). The
+ * load-bearing post-escape cap lives in `buildConfigApprovalCardBody`
+ * (rendered-body cap), which re-truncates the raw diff if escaping
+ * blew past Telegram's 4096 sendMessage limit. This function is the
+ * cheap fast-path for the common case.
+ */
+export function truncateDiffForCard(
+  unifiedDiff: string,
+  maxLines = 50,
+  maxChars = 3000,
+): string {
+  const sentinel = "\n[… diff continues, see attached file]";
+  const lines = unifiedDiff.split("\n");
+  let out: string;
+  if (lines.length <= maxLines) {
+    out = unifiedDiff;
+  } else {
+    out = lines.slice(0, maxLines).join("\n");
+  }
+  if (out.length > maxChars) {
+    // Snap to the last complete line within the cap, falling back to
+    // a hard char cut if a single line exceeds maxChars.
+    const cap = out.slice(0, maxChars);
+    const lastNl = cap.lastIndexOf("\n");
+    out = lastNl > 0 ? cap.slice(0, lastNl) : cap;
+  }
+  return out === unifiedDiff ? out : out + sentinel;
+}
+
+/**
+ * Telegram `sendMessage` hard limit. We render with `parse_mode=HTML`,
+ * so the limit applies to the rendered (escaped) body, NOT the raw
+ * pre-escape source. Worst-case escape is `&` → `&amp;` (5x).
+ */
+const TELEGRAM_SENDMESSAGE_LIMIT = 4096;
+/** Safety margin under the hard limit for invisible framing wobble. */
+const RENDERED_BODY_CAP = 3900;
+/** Operator-supplied `reason` is unbounded at the wire — clip it. */
+const REASON_MAX_CHARS = 500;
+const REASON_ELLIPSIS = "…";
+/**
+ * Sentinel appended to a truncated diff in the inline card body when
+ * the full diff ships separately as a `.patch` attachment. Exported
+ * so the dispatcher can key oversize detection off the
+ * `{truncated}` flag returned by `buildConfigApprovalCardBody`
+ * instead of substring-matching this string.
+ */
+export const DIFF_SENTINEL = "\n[… diff continues, see attached file]";
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function clipReason(reason: string): string {
+  if (reason.length <= REASON_MAX_CHARS) return reason;
+  return reason.slice(0, REASON_MAX_CHARS - REASON_ELLIPSIS.length) +
+    REASON_ELLIPSIS;
+}
+
+/**
+ * Render the card body, guaranteeing the result fits under Telegram's
+ * 4096-char sendMessage limit even when HTML escaping inflates the
+ * raw diff up to 5x (worst case: all `&`). Strategy:
+ *
+ *   1. Clip `reason` (user-supplied, unbounded) to REASON_MAX_CHARS.
+ *   2. Render with the (already line/char-capped) diff.
+ *   3. If the rendered body still exceeds RENDERED_BODY_CAP, binary-
+ *      shrink the raw diff and re-render until it fits. Truncation
+ *      happens on the RAW diff (then re-escaped), so we never cut
+ *      mid-entity like `&am|p;`.
+ *
+ * The full diff still ships as a `.patch` attachment — this cap only
+ * shrinks the inline preview.
+ */
 export function buildConfigApprovalCardBody(args: {
   agentName: string;
   reason: string;
   unifiedDiff: string;
-}): string {
-  const esc = (s: string) =>
-    s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-  return (
+}): { body: string; truncated: boolean } {
+  const safeReason = clipReason(args.reason);
+  const render = (diff: string): string =>
     `🛠 <b>Config edit proposed</b>\n` +
-    `Agent: <code>${esc(args.agentName)}</code>\n` +
-    `Reason: ${esc(args.reason)}\n\n` +
-    `<pre>${esc(args.unifiedDiff)}</pre>`
-  );
+    `Agent: <code>${escapeHtml(args.agentName)}</code>\n` +
+    `Reason: ${escapeHtml(safeReason)}\n\n` +
+    `<pre>${escapeHtml(diff)}</pre>`;
+
+  return truncateRawToFit({
+    raw: args.unifiedDiff,
+    render,
+    cap: RENDERED_BODY_CAP,
+    sentinel: DIFF_SENTINEL,
+    hardLimit: TELEGRAM_SENDMESSAGE_LIMIT,
+  });
 }
 
 /**
@@ -85,6 +186,7 @@ export async function handleRequestConfigApproval(
   const reply = (
     verdict: "approve" | "deny" | "timeout",
     reason?: string,
+    denySource?: "operator" | "dispatch_failure",
   ) => {
     try {
       client.send({
@@ -92,6 +194,7 @@ export async function handleRequestConfigApproval(
         requestId: msg.requestId,
         verdict,
         ...(reason ? { reason } : {}),
+        ...(denySource ? { denySource } : {}),
       });
     } catch (err) {
       deps.log?.(
@@ -101,21 +204,44 @@ export async function handleRequestConfigApproval(
   };
 
   if (msg.agentName !== deps.agentName) {
-    reply("deny", `gateway serves '${deps.agentName}', not '${msg.agentName}'`);
+    reply(
+      "deny",
+      `gateway serves '${deps.agentName}', not '${msg.agentName}'`,
+      "dispatch_failure",
+    );
     return;
   }
 
   const target = deps.loadTargetChat();
   if (target === null) {
-    reply("deny", "no target chat available — operator not paired?");
+    reply(
+      "deny",
+      "no target chat available — operator not paired?",
+      "dispatch_failure",
+    );
     return;
   }
 
-  const body = buildConfigApprovalCardBody({
+  // Pre-flight oversize handling (#1762). Telegram caps sendMessage
+  // at 4096 chars and we render with parse_mode=HTML, so the limit
+  // applies to the rendered (escaped) body — worst-case `&` → `&amp;`
+  // inflates 5x. Fast-path with a cheap raw-input cap, then let
+  // buildConfigApprovalCardBody enforce the post-escape rendered cap
+  // (which re-truncates the diff if escaping blew past the limit). We
+  // ship the full diff as a `.patch` attachment whenever truncation
+  // happens in either layer.
+  const prelim = truncateDiffForCard(msg.unifiedDiff);
+  const built = buildConfigApprovalCardBody({
     agentName: msg.agentName,
     reason: msg.reason,
-    unifiedDiff: msg.unifiedDiff,
+    unifiedDiff: prelim,
   });
+  const body = built.body;
+  // Oversize iff EITHER the cheap raw fast-path trimmed lines OR the
+  // post-escape rendered cap had to re-truncate. Keyed off the
+  // builder's structured `truncated` flag instead of substring-
+  // matching the sentinel string (#1767 nit).
+  const oversize = prelim !== msg.unifiedDiff || built.truncated;
   const replyMarkup = deps.buildKeyboard(msg.requestId);
 
   const posted = await deps.postCard({
@@ -125,9 +251,12 @@ export async function handleRequestConfigApproval(
     replyMarkup,
   });
   if (posted === null) {
-    reply("deny", "Telegram sendMessage failed");
+    reply("deny", "Telegram sendMessage failed", "dispatch_failure");
     return;
   }
+  if (oversize) {
+    await maybePostAttachment(deps, target, msg);
+  }
 
   const entry: PendingConfigApproval = {
     requestId: msg.requestId,
@@ -245,8 +374,34 @@ export async function handleRequestConfigFinalize(
   }
 }
 
-function escapeHtml(s: string): string {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+ * Best-effort attachment of the full diff as a `.patch` document.
+ * Logged-and-swallowed on failure — the truncated card body remains
+ * actionable even without the attachment. (#1762)
+ */
+async function maybePostAttachment(
+  deps: ConfigApprovalHandlerDeps,
+  target: { chatId: number | string; threadId?: number },
+  msg: RequestConfigApprovalMessage,
+): Promise<void> {
+  if (deps.postAttachment === undefined) {
+    deps.log?.(
+      `oversize config approval card but no postAttachment dep wired (requestId=${msg.requestId})`,
+    );
+    return;
+  }
+  try {
+    await deps.postAttachment({
+      chatId: target.chatId,
+      ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+      filename: `config-edit-${msg.requestId}.patch`,
+      content: msg.unifiedDiff,
+    });
+  } catch (err) {
+    deps.log?.(
+      `config approval attachment failed (requestId=${msg.requestId}): ${(err as Error).message}`,
+    );
+  }
 }
 
 // Test-only: clear the in-memory pending map between cases.

package/telegram-plugin/gateway/diff-preview-card.test.ts

@@ -111,7 +111,7 @@ describe("buildDiffPreviewCard — input validation", () => {
     const preview = buildDiffPreview(baseInput());
     expect(() =>
       buildDiffPreviewCard({ preview, suggestRequestId: "not-hex" }),
-    ).toThrow(/8 hex chars/);
+    ).toThrow(/32 hex chars/);
   });
 
   it("throws on a malformed writeRequestId", () => {
@@ -122,7 +122,7 @@ describe("buildDiffPreviewCard — input validation", () => {
         suggestRequestId: "aabbccddaabbccddaabbccddaabbccdd",
         writeRequestId: "ABCDEF01", // wrong case
       }),
-    ).toThrow(/8 hex chars/);
+    ).toThrow(/32 hex chars/);
   });
 });
 

package/telegram-plugin/gateway/diff-preview-card.ts

@@ -73,12 +73,12 @@ export function buildDiffPreviewCard(
 ): BuiltDiffPreviewCard {
   if (!REQUEST_ID_RE.test(input.suggestRequestId)) {
     throw new Error(
-      `buildDiffPreviewCard: suggestRequestId must be 8 hex chars (got '${input.suggestRequestId}')`,
+      `buildDiffPreviewCard: suggestRequestId must be 32 hex chars (got '${input.suggestRequestId}')`,
     );
   }
   if (input.writeRequestId !== undefined && !REQUEST_ID_RE.test(input.writeRequestId)) {
     throw new Error(
-      `buildDiffPreviewCard: writeRequestId must be 8 hex chars (got '${input.writeRequestId}')`,
+      `buildDiffPreviewCard: writeRequestId must be 32 hex chars (got '${input.writeRequestId}')`,
     );
   }
 

package/telegram-plugin/gateway/drive-write-approval.test.ts

@@ -279,6 +279,76 @@ describe("handleRequestDriveApproval — TTL clamping", () => {
   });
 });
 
+// ────────────────────────────────────────────────────────────────────────
+// Oversize-body fit (#1767)
+// ────────────────────────────────────────────────────────────────────────
+
+describe("handleRequestDriveApproval — oversize card body fit (#1767)", () => {
+  it("truncates the rendered text under 4096 chars before posting", async () => {
+    const spy = makeSpy();
+    // buildCard returns a body well past Telegram's 4096-char limit
+    // (simulates a docTitle / anchor / summary whose HTML-escape
+    // inflated past the limit). Handler must shrink it before postCard.
+    const giantText =
+      "<b>Title</b>\n" +
+      Array.from({ length: 200 }, (_, i) => `line-${i}-${"x".repeat(40)}`).join(
+        "\n",
+      );
+    expect(giantText.length).toBeGreaterThan(4096);
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({
+        spy,
+        buildCard: () => ({ text: giantText, reply_markup: { stub: true } }),
+      }),
+    );
+    expect(spy.posted).toHaveLength(1);
+    expect(spy.posted[0]!.text.length).toBeLessThanOrEqual(4096);
+    expect(spy.posted[0]!.text).toContain("preview truncated");
+    // Card was successfully posted → ok:true response went back.
+    expect(spy.sent[0]?.ok).toBe(true);
+    // The log line surfaces the truncation event.
+    expect(
+      spy.logs.some((l) => l.includes("oversize-truncated")),
+    ).toBe(true);
+  });
+
+  it("does not touch the body when it already fits", async () => {
+    const spy = makeSpy();
+    const small = "<b>Small</b>\nline 1\nline 2";
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({
+        spy,
+        buildCard: () => ({ text: small, reply_markup: { stub: true } }),
+      }),
+    );
+    expect(spy.posted[0]!.text).toBe(small);
+    expect(
+      spy.logs.some((l) => l.includes("oversize-truncated")),
+    ).toBe(false);
+  });
+
+  it("post failure after truncation surfaces a structured reason", async () => {
+    const spy = makeSpy();
+    const giantText =
+      "<b>Title</b>\n" + "x".repeat(8000);
+    await handleRequestDriveApproval(
+      clientFor(spy),
+      msgFor(),
+      deps({
+        spy,
+        buildCard: () => ({ text: giantText, reply_markup: { stub: true } }),
+        postCard: async () => null,
+      }),
+    );
+    expect(spy.sent[0]?.ok).toBe(false);
+    expect(spy.sent[0]?.reason).toMatch(/oversize-body truncation/);
+  });
+});
+
 // ────────────────────────────────────────────────────────────────────────
 // Always responds (no path drops the response)
 // ────────────────────────────────────────────────────────────────────────

package/telegram-plugin/gateway/drive-write-approval.ts

@@ -30,6 +30,7 @@ import type {
   DriveApprovalPostedEvent,
   RequestDriveApprovalMessage,
 } from "./ipc-protocol.js";
+import { truncateRawToFit } from "./oversize-card-body.js";
 
 // ────────────────────────────────────────────────────────────────────────
 // Injected deps — caller (gateway.ts) wires these from the existing
@@ -100,6 +101,18 @@ const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const MIN_TTL_MS = 30 * 1000; // 30 seconds
 
+/**
+ * Telegram `sendMessage` hard limit. `buildDiffPreviewCard` HTML-
+ * escapes the docTitle + every body line with no upstream length
+ * cap, so an adversarial or just-unusually-long docTitle / anchor
+ * displayName / agent-supplied summary can render past 4096 once
+ * `&` / `<` / `>` inflate up to 5x. We rebuild a truncated body
+ * keyed off the wrapper-attested fields when that happens. (#1767)
+ */
+const TELEGRAM_SENDMESSAGE_LIMIT = 4096;
+const RENDERED_BODY_CAP = 3900;
+const OVERSIZE_SENTINEL = "\n[… preview truncated; open in Drive for full context]";
+
 /**
  * Top-level handler called by ipc-server's onRequestDriveApproval.
  * Always sends a single `drive_approval_posted` reply (success or
@@ -204,20 +217,56 @@ export async function handleRequestDriveApproval(
     });
     return;
   }
+  // Oversize guard (#1767). buildDiffPreviewCard renders title +
+  // every body line HTML-escaped with no length cap. Worst-case `&`
+  // / `<` / `>` inflate 5x — a long docTitle or anchor displayName
+  // pushes past Telegram's 4096-char sendMessage limit and the API
+  // returns a generic 400 that surfaces as a silent E_DENIED. Cap
+  // the rendered body BEFORE posting.
+  let cardText = card.text;
+  let truncatedForFit = false;
+  if (cardText.length > RENDERED_BODY_CAP) {
+    const fit = truncateRawToFit({
+      raw: card.text,
+      // The "raw" here is the already-escaped card text — we don't
+      // have access to pre-escape source at this layer because
+      // buildDiffPreviewCard owns escaping. Line-snap is the safe
+      // granularity: HTML entities like `&amp;` never span `\n`, so
+      // truncating at a newline boundary can't bisect an entity.
+      // The defensive single-long-line fallback may char-cut into an
+      // entity, but the drive-preview lines are short (anchor name,
+      // metrics, capped 200-char summary) so this is unreachable
+      // unless a multi-KB docTitle slipped through Drive itself.
+      render: (slice) => slice,
+      cap: RENDERED_BODY_CAP,
+      sentinel: OVERSIZE_SENTINEL,
+      hardLimit: TELEGRAM_SENDMESSAGE_LIMIT,
+    });
+    cardText = fit.body;
+    truncatedForFit = fit.truncated;
+  }
+
   const posted = await deps.postCard({
     chatId: target.chatId,
     ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
-    text: card.text,
+    text: cardText,
     replyMarkup: card.reply_markup,
   });
   if (posted === null) {
     reply({
       correlationId: msg.correlationId,
       ok: false,
-      reason: "Telegram sendMessage failed",
+      reason: truncatedForFit
+        ? "Telegram sendMessage failed even after oversize-body truncation"
+        : "Telegram sendMessage failed",
     });
     return;
   }
+  if (truncatedForFit) {
+    deps.log?.(
+      `drive_approval_posted oversize-truncated correlation=${msg.correlationId} original_len=${card.text.length} rendered_len=${cardText.length}`,
+    );
+  }
 
   deps.log?.(
     `drive_approval_posted ok correlation=${msg.correlationId} request_id=${registered.request_id} file=${fileId}`,

package/telegram-plugin/gateway/gateway.ts

@@ -3438,6 +3438,14 @@ pendingProgress.startTimer({
     )
   },
   emitMetric: (event) => emitRuntimeMetric(event),
+  // #1760 defense-in-depth: if a newer turn for this chat is active at
+  // tick time, the prior turn's pending-progress is stale (the
+  // canonical teardown was missed). Drop the ticker instead of editing
+  // the old anchor — see pending-work-progress.ts's docblock.
+  isActiveTurnNewerThan: (key, activatedAt) => {
+    const turnStartedAt = activeTurnStartedAt.get(key)
+    return turnStartedAt != null && turnStartedAt > activatedAt
+  },
 })
 
 // Per-agent buffer for synthetic inbounds the gateway couldn't deliver
@@ -4113,6 +4121,24 @@ const ipcServer: IpcServer = createIpcServer({
           )
         }
       },
+      // #1762: send the full diff as a `.patch` attachment when the
+      // card body would exceed Telegram's 4096-char sendMessage limit.
+      postAttachment: async (args) => {
+        const input = new InputFile(Buffer.from(args.content, 'utf8'), args.filename)
+        await robustApiCall(
+          () =>
+            bot.api.sendDocument(args.chatId, input, {
+              ...(args.threadId !== undefined
+                ? { message_thread_id: args.threadId }
+                : {}),
+            }),
+          {
+            chat_id: String(args.chatId),
+            verb: 'config-approval-attachment',
+            ...(args.threadId !== undefined ? { threadId: args.threadId } : {}),
+          },
+        )
+      },
       log: (m) =>
         process.stderr.write(`telegram gateway: config-approval — ${m}\n`),
     })
@@ -4693,6 +4719,10 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
           //   - #1664 silent-end re-prompt fires even when the
           //     accumulated silent content qualifies as substantive;
           //   - retries within the dedup window may double-send.
+          // #1760 primary fix — clear any stale prior-turn ticker
+          // before re-anchoring on this silent-reply edit. See the
+          // matching comment at the executeReply finalize site below.
+          pendingProgress.clearPending(statusKey(chat_id, threadId), 'reply_finalize')
           pendingProgress.noteOutbound(statusKey(chat_id, threadId), {
             messageId: decision.messageId,
             text: decision.mergedText,
@@ -4886,6 +4916,14 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   if (sentIds.length === chunks.length && chunks.length > 0) {
     const anchorMsgId = sentIds[chunks.length - 1]
     if (typeof anchorMsgId === 'number') {
+      // #1760 primary fix — clear any stale prior-turn ticker BEFORE
+      // re-anchoring. The canonical teardown wires (turn_end,
+      // subagent_handback, inbound) can be missed (e.g. SDK turn_end
+      // event dropped, as in the #1760 live evidence). Tearing down on
+      // every reply-finalize is idempotent and resilient: it's a no-op
+      // when nothing is active, and drops a stale ambient before the
+      // new turn captures its anchor.
+      pendingProgress.clearPending(statusKey(chat_id, threadId), 'reply_finalize')
       pendingProgress.noteOutbound(statusKey(chat_id, threadId), {
         messageId: anchorMsgId,
         text: chunks[chunks.length - 1],
@@ -5323,6 +5361,10 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       streamFormat === 'html' ? 'HTML'
       : streamFormat === 'markdownv2' ? 'MarkdownV2'
       : undefined
+    // #1760 primary fix — clear any stale prior-turn ticker before
+    // re-anchoring on stream_reply done. See the matching comment at
+    // the executeReply finalize site.
+    pendingProgress.clearPending(statusKey(sChatId, sThreadId), 'reply_finalize')
     pendingProgress.noteOutbound(statusKey(sChatId, sThreadId), {
       messageId: result.messageId,
       text: args.text as string,

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -107,8 +107,17 @@ export interface ConfigApprovalResolvedEvent {
   /** Echoes the requestId from the originating request_config_approval. */
   requestId: string;
   verdict: "approve" | "deny" | "timeout";
-  /** Diagnostic detail when present (currently unused; reserved). */
+  /** Diagnostic detail when present. */
   reason?: string;
+  /**
+   * Distinguishes an actual operator tap-deny (`"operator"`) from a
+   * gateway-side dispatch failure that auto-denied because the card
+   * never reached the operator (`"dispatch_failure"`). Only set on
+   * `verdict: "deny"` events. Caller (hostd) maps `dispatch_failure`
+   * to a distinct error code so the failure isn't misattributed to
+   * the operator. Issue #1762.
+   */
+  denySource?: "operator" | "dispatch_failure";
 }
 
 export type GatewayToClient =

package/telegram-plugin/gateway/oversize-card-body.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for the shared truncateRawToFit helper (#1767).
+ *
+ * Covers:
+ *   - No-op when the rendered body already fits.
+ *   - Binary-search shrinks the raw slice; result fits under `cap`.
+ *   - Line-snap when newlines exist; sentinel appended.
+ *   - Char-truncation fallback when a single unbroken line exceeds
+ *     the budget (no `\n` to snap to).
+ *   - Defensive hard-cut when even the framing-alone overflows.
+ */
+
+import { describe, it, expect } from "vitest";
+import { truncateRawToFit } from "./oversize-card-body.js";
+
+const SENTINEL = "\n[… truncated]";
+
+function frame(escapeMultiplier: number) {
+  // Render closure that mimics a `<pre>`-wrapped HTML-escaped body
+  // where every `&` inflates `escapeMultiplier`-fold.
+  return (raw: string) => {
+    const inflated = raw.replace(/&/g, "&".repeat(escapeMultiplier));
+    return `<b>Hdr</b>\n<pre>${inflated}</pre>`;
+  };
+}
+
+describe("truncateRawToFit", () => {
+  it("returns the full body unchanged when it fits under cap", () => {
+    const raw = "small content";
+    const { body, truncated } = truncateRawToFit({
+      raw,
+      render: (s) => `<pre>${s}</pre>`,
+      cap: 100,
+      sentinel: SENTINEL,
+    });
+    expect(truncated).toBe(false);
+    expect(body).toBe("<pre>small content</pre>");
+  });
+
+  it("shrinks raw via binary-search until the rendered body fits the cap (5x escape inflation)", () => {
+    const raw = "&".repeat(2000); // 2000 chars raw, 10000 after 5x inflate
+    const { body, truncated } = truncateRawToFit({
+      raw,
+      render: frame(5),
+      cap: 1000,
+      sentinel: SENTINEL,
+    });
+    expect(truncated).toBe(true);
+    expect(body.length).toBeLessThanOrEqual(1000);
+    expect(body).toContain("truncated");
+  });
+
+  it("snaps to the last newline within the chosen raw prefix (no mid-line cut)", () => {
+    const raw = ["line-a", "line-b", "line-c", "line-d", "line-e"]
+      .map((l) => l.repeat(50))
+      .join("\n");
+    const { body, truncated } = truncateRawToFit({
+      raw,
+      render: (s) => `<pre>${s}</pre>`,
+      cap: 600,
+      sentinel: SENTINEL,
+    });
+    expect(truncated).toBe(true);
+    // The portion before the sentinel must end at a complete line —
+    // no partial `line-?` suffix mid-word.
+    const beforeSentinel = body.slice(
+      0,
+      body.length - SENTINEL.length - "</pre>".length,
+    );
+    // Every line in the source repeated its label 50x — assert the
+    // tail of the kept content ends with a full repeated block, not
+    // a chopped one. Easiest check: the body must not end mid-word
+    // like `line-` (the dash followed by no letter).
+    expect(beforeSentinel).not.toMatch(/line-$/);
+  });
+
+  it("falls through to char-truncation when a single unbroken line exceeds cap", () => {
+    const raw = "x".repeat(5000); // no newlines at all
+    const { body, truncated } = truncateRawToFit({
+      raw,
+      render: (s) => `<pre>${s}</pre>`,
+      cap: 500,
+      sentinel: SENTINEL,
+    });
+    expect(truncated).toBe(true);
+    expect(body.length).toBeLessThanOrEqual(500);
+    // Some of the line content survives — the helper shouldn't
+    // collapse to "<pre>" + sentinel only.
+    expect(body).toMatch(/x{100,}/);
+    expect(body).toContain("truncated");
+  });
+
+  it("hard-cuts at hardLimit when framing alone overflows (defensive)", () => {
+    // Framing-alone is 5000 chars (way past cap), and the renderer
+    // ignores its input — so no slice of raw can ever fit. The
+    // helper should hard-cut to hardLimit rather than loop forever.
+    const huge = "Z".repeat(5000);
+    const { body, truncated } = truncateRawToFit({
+      raw: "ignored",
+      render: () => huge,
+      cap: 1000,
+      sentinel: SENTINEL,
+      hardLimit: 1100,
+    });
+    expect(truncated).toBe(true);
+    expect(body.length).toBeLessThanOrEqual(1100);
+  });
+});