switchroom 0.17.10 → 0.18.6

package/telegram-plugin/render/render.ts

@@ -0,0 +1,440 @@
+// IR -> Telegram rich-markdown renderer for the Telegram HTML render engine
+// (name kept for continuity with render/ir.ts + render/parse.ts; the actual
+// wire format is GFM markdown, NOT HTML — see the note below).
+//
+// Increment 2 of the render pipeline: takes the typed IR produced by
+// `parse.ts` (per `ir.ts`) and emits a string suitable for the `markdown`
+// field of `InputRichMessageMarkdown` (`telegram-plugin/rich-send.ts`).
+//
+// IMPORTANT — why this emits markdown, not HTML:
+// `ir.ts`'s block-type doc comment (written during Increment 1) sketches an
+// HTML tag mapping "for the next increment." That comment predates the Bot
+// API 10.1 migration (#2669, `telegram-plugin/rich-send.ts`) becoming the
+// live send path: `sendRichMessage` / `editMessageText` are called with
+// `{ markdown: string }` — raw GFM markdown — not with `{ text, parse_mode:
+// "HTML" }`. There is no HTML anywhere on the current outbound path (see
+// `reference/telegram-formatting-guide.md`). This renderer therefore targets
+// the ACTUAL contract: GFM markdown with the Bot API 10.1 extensions
+// documented in the formatting guide (expandable blockquote via `**> `,
+// spoiler via `||…||`, GFM pipe tables, etc). This module is NOT wired into
+// the live send path yet — that is a later increment, per the RFC's phased
+// rollout (rich rendering stays gated off by default until then).
+//
+// Round-trip note: `parse.ts` folds inline text (`PlainNode.text`,
+// `CodeNode.text`, `code-block` `text`, link `href`) into DECODED strings —
+// entity references and escapes are already resolved by mdast. Rendering
+// back to markdown therefore re-escapes GFM-special characters in prose
+// context with `escapeMarkdown` (same helper `format.ts` uses for
+// dynamic-content interpolation) and re-defuses embedded backticks in code
+// spans with `codeSpanSafe`, so the emitted markdown parses back to
+// equivalent entities rather than accidentally re-triggering formatting or
+// breaking out of a code span.
+
+import { escapeMarkdown, codeSpanSafe, RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import type {
+  Block,
+  BlockquoteNode,
+  CodeBlockNode,
+  Document,
+  Inline,
+  ListItem,
+  ListNode,
+  TableNode,
+  TableRow,
+} from "./ir.js";
+
+// ---------------------------------------------------------------------------
+// Inline rendering
+// ---------------------------------------------------------------------------
+
+function renderInline(node: Inline): string {
+  switch (node.type) {
+    case "plain":
+      return escapeMarkdown(node.text);
+    case "bold":
+      return `**${renderInlineChildren(node.children)}**`;
+    case "italic":
+      return `*${renderInlineChildren(node.children)}*`;
+    case "underline":
+      return `__${renderInlineChildren(node.children)}__`;
+    case "strike":
+      return `~~${renderInlineChildren(node.children)}~~`;
+    case "spoiler":
+      return `||${renderInlineChildren(node.children)}||`;
+    case "highlight":
+      return `==${renderInlineChildren(node.children)}==`;
+    case "code":
+      return `\`${codeSpanSafe(node.text)}\``;
+    case "link":
+      return `[${renderInlineChildren(node.children)}](${node.href})`;
+    default: {
+      // Exhaustiveness guard — the IR union is closed; a new variant must be
+      // handled above rather than silently dropped.
+      const _exhaustive: never = node;
+      return escapeMarkdown((_exhaustive as Inline & { text?: string }).text ?? "");
+    }
+  }
+}
+
+function renderInlineChildren(children: Inline[]): string {
+  return children.map(renderInline).join("");
+}
+
+// ---------------------------------------------------------------------------
+// Block rendering
+// ---------------------------------------------------------------------------
+
+/** Prefix every line of `text` with `prefix` (used for blockquote nesting). */
+function prefixLines(text: string, prefix: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length > 0 ? `${prefix}${line}` : prefix.trimEnd()))
+    .join("\n");
+}
+
+function renderBlockquote(node: BlockquoteNode): string {
+  const inner = renderBlocks(node.children);
+  // Bot API 10.1 expandable blockquote: `**> ` on the first quoted line.
+  // Plain blockquote: `> ` on every line.
+  if (node.expandable) {
+    const lines = inner.split("\n");
+    return lines
+      .map((line, i) => {
+        const marker = i === 0 ? "**> " : "> ";
+        return line.length > 0 ? `${marker}${line}` : marker.trimEnd();
+      })
+      .join("\n");
+  }
+  return prefixLines(inner, "> ");
+}
+
+function renderCodeBlock(node: CodeBlockNode): string {
+  const lang = node.language ?? "";
+  // Fenced code content is verbatim per the formatting guide; the only
+  // hazard is an embedded ``` closing the fence early. Widen the fence to a
+  // run of backticks one longer than the longest run already present in the
+  // content, mirroring the guide's `preBlock` defusal strategy.
+  const longestRun = Math.max(
+    0,
+    ...(node.text.match(/`+/g) ?? []).map((run) => run.length),
+  );
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return `${fence}${lang}\n${node.text}\n${fence}`;
+}
+
+function renderListItem(item: ListItem, ordered: boolean, index: number): string {
+  const checkbox =
+    item.checked === null ? "" : item.checked ? "[x] " : "[ ] ";
+  const marker = ordered ? `${index}. ` : "- ";
+  // Tight item (spread=false): join the item's block children with a single
+  // newline so a paragraph and its nested sub-list stay adjacent — no spurious
+  // blank line injected before the sub-list. Loose item (spread=true): keep the
+  // blank-line separation the source author intended.
+  const body = renderBlocksJoined(item.children, item.spread ? "\n\n" : "\n");
+  const lines = body.split("\n");
+  const first = `${marker}${checkbox}${lines[0] ?? ""}`;
+  const contIndent = " ".repeat(marker.length);
+  const rest = lines
+    .slice(1)
+    .map((line) => (line.length > 0 ? `${contIndent}${line}` : line));
+  return [first, ...rest].join("\n");
+}
+
+function renderList(node: ListNode): string {
+  const start = node.startNumber ?? 1;
+  // Loose list (spread=true): a blank line between top-level items, as the
+  // source author wrote them. Tight list (spread=false, the common case and
+  // all nested sub-lists): siblings on adjacent lines, single newline.
+  const sep = node.spread ? "\n\n" : "\n";
+  return node.items
+    .map((item, i) => renderListItem(item, node.ordered, start + i))
+    .join(sep);
+}
+
+/** Render a single cell's inline content for a table (no line breaks — GFM
+ *  table cells can't contain them; pipes are escaped defensively). */
+function renderTableCell(cells: TableRow["cells"][number]): string {
+  return renderInlineChildren(cells.children).replace(/\n+/g, " ");
+}
+
+function alignSeparator(align: TableNode["align"][number]): string {
+  switch (align) {
+    case "left":
+      return ":---";
+    case "right":
+      return "---:";
+    case "center":
+      return ":---:";
+    default:
+      return "---";
+  }
+}
+
+function renderTable(node: TableNode): string {
+  const headerCells = node.header.cells.map(renderTableCell);
+  const colCount = headerCells.length;
+  const align = node.align.length > 0 ? node.align : new Array(colCount).fill(null);
+  const headerLine = `| ${headerCells.join(" | ")} |`;
+  const sepLine = `| ${align
+    .slice(0, colCount)
+    .map(alignSeparator)
+    .join(" | ")} |`;
+  const bodyLines = node.rows.map(
+    (row) => `| ${row.cells.map(renderTableCell).join(" | ")} |`,
+  );
+  return [headerLine, sepLine, ...bodyLines].join("\n");
+}
+
+function renderBlock(node: Block): string {
+  switch (node.type) {
+    case "paragraph":
+      return renderInlineChildren(node.children);
+    case "heading":
+      return `${"#".repeat(node.level)} ${renderInlineChildren(node.children)}`;
+    case "blockquote":
+      return renderBlockquote(node);
+    case "code-block":
+      return renderCodeBlock(node);
+    case "list":
+      return renderList(node);
+    case "thematic-break":
+      return "---";
+    case "table":
+      return renderTable(node);
+    default: {
+      const _exhaustive: never = node;
+      return escapeMarkdown((_exhaustive as Block & { text?: string }).text ?? "");
+    }
+  }
+}
+
+/** Join a run of blocks with an explicit separator. Blockquote children and
+ *  the top-level document use a blank line (`\n\n`); tight list items pass a
+ *  single newline so a nested sub-list stays adjacent to its item's paragraph
+ *  (see `renderListItem`). */
+function renderBlocksJoined(blocks: Block[], sep: string): string {
+  return blocks.map(renderBlock).join(sep);
+}
+
+function renderBlocks(blocks: Block[]): string {
+  return renderBlocksJoined(blocks, "\n\n");
+}
+
+/** Render a full IR `Document` to Bot API 10.1 rich GFM markdown. */
+export function render(doc: Document): string {
+  return renderBlocks(doc.blocks);
+}
+
+// ---------------------------------------------------------------------------
+// Construct allowlist (gap #2: escape/degrade anything unsupported)
+// ---------------------------------------------------------------------------
+
+// The IR node types this renderer emits NATIVE Telegram markup for. The IR
+// union is closed and TypeScript's exhaustiveness `default` branches in
+// `renderInline` / `renderBlock` already escape any unknown variant to literal
+// text rather than emitting a broken tag — so the allowlist is enforced at
+// COMPILE time. These runtime constants make the allowlist inspectable (and
+// unit-testable: a test asserts every IR `type` appears here, so adding an IR
+// node without teaching the renderer to render it fails the build), which is
+// the concrete "construct-allowlist validator" that pairs with the expandable-
+// blockquote / spoiler / underline additions.
+export const SUPPORTED_INLINE = [
+  "plain",
+  "bold",
+  "italic",
+  "underline",
+  "strike",
+  "spoiler",
+  "highlight",
+  "code",
+  "link",
+] as const;
+
+export const SUPPORTED_BLOCK = [
+  "paragraph",
+  "heading",
+  "blockquote",
+  "code-block",
+  "list",
+  "thematic-break",
+  "table",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Oversized / malformed-content safe fallback
+// ---------------------------------------------------------------------------
+
+/** Which construct degraded. `document` = the whole message fell back to
+ *  plain text. */
+export type DegradationConstruct = "table" | "code-block" | "blockquote" | "document";
+
+/** Why a construct could not be emitted as a proper rich construct.
+ *   - `table-malformed`    : the table's structure is not renderable as a rich
+ *                            GFM table (e.g. no columns, ragged rows); emitted
+ *                            as a preformatted code fence instead.
+ *   - `oversize`           : a single atomic block alone exceeds the wire cap;
+ *                            emitted as plain source text.
+ *   - `document-oversize`  : the whole document still exceeds the cap after
+ *                            per-block substitution; sent as plain text with no
+ *                            rich wrapper. */
+export type DegradationReason = "table-malformed" | "oversize" | "document-oversize";
+
+/** A tracked degradation — WHY a construct fell back from its native rich form
+ *  to a plain/code rendering. Returned on `RenderResult` so the caller can log
+ *  / surface it instead of the fallback happening silently. */
+export interface Degradation {
+  construct: DegradationConstruct;
+  reason: DegradationReason;
+  /** Human-readable detail for logs / telemetry. */
+  detail: string;
+}
+
+export interface RenderResult {
+  /** The rendered text to send. */
+  text: string;
+  /** "markdown": send as rich `{ markdown }`. "plain": send as a literal
+   *  string with no rich wrapper (structure stripped, content preserved). */
+  mode: "markdown" | "plain";
+  /** Constructs that could not be emitted in their native rich form, each with
+   *  a tracked reason. Empty when everything rendered natively. Never silently
+   *  degrade — a caller can log/telemeter these. */
+  degradations: Degradation[];
+}
+
+/**
+ * Classify a table that cannot render as a proper rich GFM table. Returns a
+ * human-readable reason string, or null when the table is well-formed.
+ *
+ * mdast normally normalises tables, but a table folded from degraded/adversarial
+ * source (or a future IR producer) can still be structurally unrenderable — no
+ * header columns, or body rows whose cell count doesn't match the header. Such a
+ * table would emit pipes that Telegram renders as broken/literal text, so we
+ * catch it here and fall back to a preformatted code fence (content preserved,
+ * degradation tracked) rather than shipping a broken row.
+ */
+function tableDegradationReason(node: TableNode): string | null {
+  const cols = node.header.cells.length;
+  if (cols === 0) return "table has no header columns";
+  for (let i = 0; i < node.rows.length; i++) {
+    const n = node.rows[i].cells.length;
+    if (n !== cols) {
+      return `row ${i + 1} has ${n} cell(s), expected ${cols} to match the header`;
+    }
+  }
+  return null;
+}
+
+/** Wrap a block's raw source text in a widened preformatted code fence — the
+ *  degraded rendering for a malformed table (content verbatim, no broken
+ *  markup). Fence-widening mirrors `renderCodeBlock`. */
+function degradeToCodeFence(source: string, node: Block): string {
+  const raw = source.slice(node.start, node.end);
+  const longestRun = Math.max(0, ...(raw.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return `${fence}\n${raw}\n${fence}`;
+}
+
+/**
+ * A block is "atomic" for chunking purposes when splitting it mid-construct
+ * would break the wire format — an unterminated fence, a half table row, or
+ * a blockquote whose closing marker got separated from its opener. These are
+ * exactly the constructs `splitMarkdownChunks` (format.ts) already knows how
+ * to avoid bisecting for a MULTI-block body, but a SINGLE such block that by
+ * itself exceeds the cap has nowhere left to cut without breaking mid-tag —
+ * that's the case this module must catch before send.
+ */
+function isAtomicBlock(node: Block): boolean {
+  return (
+    node.type === "code-block" ||
+    node.type === "table" ||
+    node.type === "blockquote"
+  );
+}
+
+/** Render `node`'s raw source text as a plain literal (escaped so none of
+ *  the source's own markdown-special characters accidentally re-trigger
+ *  formatting when sent WITHOUT the rich wrapper — a plain send has no
+ *  parser, but downstream literal display should still show the author's
+ *  intended characters, not stray backslashes, so we use the raw slice
+ *  as-is: a plain send does not interpret markdown at all). */
+function plainSlice(source: string, node: Block): string {
+  return source.slice(node.start, node.end);
+}
+
+/**
+ * Render `doc` to Bot API 10.1 rich markdown, honoring the wire cap
+ * (`RICH_MESSAGE_MAX_CHARS` by default). Behaviour:
+ *
+ *   1. If the full rendered markdown fits under `maxLen`, return it as-is
+ *      (`mode: "markdown"`).
+ *   2. Otherwise, any individual ATOMIC block (table / code-block /
+ *      blockquote — constructs that cannot be safely bisected without
+ *      producing a broken tag/fence/row) whose OWN rendered form alone
+ *      exceeds `maxLen` is replaced by its raw plain-text source slice
+ *      instead of being emitted as rich markdown that a later chunker would
+ *      have to cut mid-construct.
+ *   3. If the document *still* exceeds `maxLen` after that per-block
+ *      substitution (i.e. the oversized content isn't isolated to one
+ *      swappable block, or the whole document is one giant atomic
+ *      construct), the ENTIRE document falls back to plain text — the raw
+ *      source, verbatim, sent with no rich wrapper at all. This never
+ *      truncates: the caller's ordinary length-based chunker
+ *      (`splitMarkdownChunks` and `hardSliceToCap`) is what applies size
+ *      limits to plain text before send; this function's only job is to
+ *      guarantee it is never handed a rich-markdown body with a mid-tag cut.
+ */
+export function renderSafe(
+  doc: Document,
+  source: string,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  const degradations: Degradation[] = [];
+
+  // Per-block render, degrading a MALFORMED table (any size) to a preformatted
+  // code fence up front so a structurally-unrenderable table never ships as
+  // broken pipes — and the reason is recorded, not swallowed.
+  const rendered = doc.blocks.map((block) => {
+    if (block.type === "table") {
+      const reason = tableDegradationReason(block);
+      if (reason != null) {
+        degradations.push({ construct: "table", reason: "table-malformed", detail: reason });
+        return { block, text: degradeToCodeFence(source, block) };
+      }
+    }
+    return { block, text: renderBlock(block) };
+  });
+
+  const full = rendered.map((r) => r.text).join("\n\n");
+  if (full.length <= maxLen) {
+    return { text: full, mode: "markdown", degradations };
+  }
+
+  // Oversized: swap any atomic block whose OWN rendered form alone exceeds the
+  // cap for its raw plain-text source (a construct that can't be safely
+  // bisected), recording an `oversize` degradation for each.
+  const swapped = rendered.map(({ block, text }) => {
+    if (isAtomicBlock(block) && text.length > maxLen) {
+      degradations.push({
+        construct: block.type as DegradationConstruct,
+        reason: "oversize",
+        detail: `${block.type} of ${text.length} chars exceeds the ${maxLen}-char cap; sent as plain source text`,
+      });
+      return escapeMarkdown(plainSlice(source, block));
+    }
+    return text;
+  });
+  const patched = swapped.join("\n\n");
+  if (patched.length <= maxLen) {
+    return { text: patched, mode: "markdown", degradations };
+  }
+
+  // Still oversized (or a giant atomic block never fit even as plain text) —
+  // fall all the way back to plain text for the whole document. Never
+  // truncate here; that is the length-based chunker's job downstream.
+  degradations.push({
+    construct: "document",
+    reason: "document-oversize",
+    detail: `rendered document of ${patched.length} chars exceeds the ${maxLen}-char cap; sent as plain text without the rich wrapper`,
+  });
+  return { text: source, mode: "plain", degradations };
+}

package/telegram-plugin/render/rich-render.ts

@@ -0,0 +1,72 @@
+// Flag-gated wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts)
+// into the live outbound send path.
+//
+// The renderer (`render/render.ts`, PR #2930) and parser (`render/parse.ts`)
+// have full unit coverage but were, until this module, wired into NOTHING —
+// no outbound message ever flowed through them. This module is the single,
+// feature-flagged bridge: the gateway's rich send path (stream-controller.ts)
+// runs the assistant's raw markdown through `parse → renderSafe` before it
+// reaches `sendRichMessage`, but ONLY when the flag is on.
+//
+// Feature flag — `SWITCHROOM_RICH_RENDER`, default OFF:
+//   Mirrors the `SWITCHROOM_VISIBLE_ANSWER_STREAM` convention
+//   (`answer-stream-flag.ts`): an env var read at runtime, default off, opted
+//   in PER AGENT via the `env:` block in `switchroom.yaml` (propagated into
+//   the container `environment:` by `src/agents/compose.ts`). When off,
+//   `maybeRenderOutbound` returns the input untouched, so the live send path
+//   is byte-for-byte unchanged — no agent's behaviour moves until an operator
+//   explicitly flips the flag for a specific agent. Accepts `1/true/on/yes`.
+//
+// Why route through `renderSafe` and not bare `render`:
+//   `renderSafe` guarantees the returned body is never a rich-markdown string
+//   with a mid-construct cut, and degrades a document it can't safely fit to
+//   plain-text mode (structure stripped, content preserved). The send path
+//   honours that `mode` — a `plain` result is sent WITHOUT the rich wrapper.
+
+import { parse } from "./parse.js";
+import { renderSafe, type RenderResult } from "./render.js";
+import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+
+/** Parse the `SWITCHROOM_RICH_RENDER` flag value. Default OFF; accepts the
+ *  same truthy tokens as the other switchroom env flags. Pure so the default
+ *  + parsing are unit-testable. */
+export function parseRichRenderEnabled(raw: string | undefined): boolean {
+  if (raw == null) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "on" || v === "yes";
+}
+
+/** Is the rich renderer enabled in this process? Reads the env flag live so a
+ *  test can set/unset it per-case; defaults OFF. */
+export function richRenderEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return parseRichRenderEnabled(env.SWITCHROOM_RICH_RENDER);
+}
+
+/** Unconditionally run `text` through `parse → renderSafe` (ignores the flag).
+ *  Exposed for tests and callers that have already gated on the flag. */
+export function renderOutbound(
+  text: string,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  return renderSafe(parse(text), text, maxLen);
+}
+
+/**
+ * Flag-gated transform for the live send path.
+ *
+ *   - flag OFF (default): returns the input untouched, `mode: "markdown"` —
+ *     identical to the pre-existing behaviour (raw transcript markdown sent
+ *     straight to `sendRichMessage`). No behavioural change for any agent.
+ *   - flag ON: returns `parse → renderSafe` output. `mode: "plain"` signals
+ *     the caller to send WITHOUT the rich wrapper (oversized/unsafe content).
+ */
+export function maybeRenderOutbound(
+  text: string,
+  env: NodeJS.ProcessEnv = process.env,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  if (!richRenderEnabled(env)) return { text, mode: "markdown", degradations: [] };
+  return renderOutbound(text, maxLen);
+}

package/telegram-plugin/stream-controller.ts

@@ -21,6 +21,7 @@
 
 import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
+import { maybeRenderOutbound } from './render/rich-render.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -224,12 +225,22 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // control previews via entity detection), so strip it for the rich path.
   const doSend = (text: string, opts: StreamSendOpts) => {
     if (literalText) return bot.api.sendMessage(chatId, text, opts)
+    // Flag-gated rich render (`SWITCHROOM_RICH_RENDER`, default OFF — returns
+    // the text untouched as markdown when off, so this is a no-op for every
+    // agent until an operator opts in). A `plain` result (oversized/unsafe
+    // content renderSafe declined to emit as rich) sends WITHOUT the wrapper.
+    const rendered = maybeRenderOutbound(text)
+    if (rendered.mode === 'plain') return bot.api.sendMessage(chatId, rendered.text, opts)
     const richOpts = { ...opts }
     delete richOpts.link_preview_options
-    return bot.api.sendRichMessage(chatId, richMessage(text), richOpts)
+    return bot.api.sendRichMessage(chatId, richMessage(rendered.text), richOpts)
+  }
+  const doEdit = (id: number, text: string, opts: StreamSendOpts) => {
+    if (literalText) return bot.api.editMessageText(chatId, id, text, opts)
+    const rendered = maybeRenderOutbound(text)
+    if (rendered.mode === 'plain') return bot.api.editMessageText(chatId, id, rendered.text, opts)
+    return bot.api.editMessageText(chatId, id, richMessage(rendered.text), opts)
   }
-  const doEdit = (id: number, text: string, opts: StreamSendOpts) =>
-    bot.api.editMessageText(chatId, id, literalText ? text : richMessage(text), opts)
 
   return createDraftStream(
     async (text) => {

package/telegram-plugin/subagent-watcher.ts

@@ -918,8 +918,8 @@ export function readSubTail(
       // (stage-on-text, resolve-on-tool/turn_end) can replay a previously
       // pending block exactly once. `latestSummary` carries the worker's
       // narrative result (entry.lastResultText), never tool labels.
-      const fireNarrativeProgress = (): void => {
-        if (onProgress == null || entry.state !== 'running' || entry.historical) return
+      const fireNarrativeProgress = (): boolean => {
+        if (onProgress == null || entry.state !== 'running' || entry.historical) return false
         try {
           onProgress({
             agentId: entry.agentId,
@@ -933,8 +933,10 @@ export function readSubTail(
             lastTool: entry.lastTool,
             toolCount: entry.toolCount,
           })
+          return true
         } catch (cbErr) {
           log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${(cbErr as Error).message}`)
+          return false
         }
       }
       // Resolve a pending sub-agent narrative against a lookahead event.
@@ -952,21 +954,27 @@ export function readSubTail(
       //     compare the trailing block against the worker's last reply text
       //     (`entry.lastReplyText`) and suppress a draft. Background workers
       //     never set lastReplyText, so their trailing narration still SHOWs.
+      // Returns true iff a narrative onProgress cue actually fired this
+      // call — callers use this to skip a redundant/clobbering tool-label
+      // onProgress cue for the SAME tick (see #1042 below: without this,
+      // the tool-description onProgress unconditionally fires right after
+      // and its replace-on-write onProgress always wins, so the narration
+      // shown here is never actually visible on the pinned card).
       const resolvePendingSubNarrative = (
         toolName: string | null,
         toolInput: Record<string, unknown> | undefined,
-      ): void => {
-        if (entry.pendingNarrative == null) return
+      ): boolean => {
+        if (entry.pendingNarrative == null) return false
         const pending = entry.pendingNarrative
         entry.pendingNarrative = null
         if (toolName != null && REPLY_TOOLS.has(toolName)) {
           const replyText = typeof toolInput?.text === 'string' ? (toolInput.text as string) : ''
-          if (isDraftOfReply(pending.text, replyText)) return // draft of the reply → SUPPRESS
+          if (isDraftOfReply(pending.text, replyText)) return false // draft of the reply → SUPPRESS
         } else if (toolName == null && entry.lastReplyText != null && entry.lastReplyText.length > 0) {
           // turn_end path: suppress a trailing draft of the delivered answer.
-          if (isDraftOfReply(pending.text, entry.lastReplyText)) return
+          if (isDraftOfReply(pending.text, entry.lastReplyText)) return false
         }
-        fireNarrativeProgress()
+        return fireNarrativeProgress()
       }
       for (const ev of events) {
         const idleSecBeforeBump = Math.round((now - entry.lastActivityAt) / 1000)
@@ -1012,7 +1020,7 @@ export function readSubTail(
           // this tool is the lookahead that decides it (SHOW unless it drafts
           // a reply tool's text). Runs before the tool's own progress cue so
           // a working preamble surfaces just ahead of its tool step.
-          resolvePendingSubNarrative(ev.toolName, ev.input)
+          const narrativeJustFired = resolvePendingSubNarrative(ev.toolName, ev.input)
           // NIT 3: capture a foreground sub-agent's actual reply text so the
           // turn_end path can suppress a trailing draft of it (see
           // resolvePendingSubNarrative). Only REPLY_TOOLS carry the answer.
@@ -1039,7 +1047,17 @@ export function readSubTail(
           // stays the worker's narrative result (never polluted with tool
           // labels — the handback payload depends on it). Pure jsonl-tail →
           // render, no model call.
-          if (onProgress != null && entry.state === 'running' && !entry.historical) {
+          //
+          // Clobber guard: if a pending narrative just fired an onProgress
+          // cue THIS SAME tick (above), skip this one — replace-on-write
+          // rendering means whichever onProgress call fires last wins, so
+          // firing both back-to-back always threw away the narration in
+          // favour of the generic tool label. Narration already told the
+          // user what's happening for this tick; the label is redundant
+          // here. When nothing preceded this tool call (no pending
+          // narrative), this still fires — that's the named foreground
+          // blindspot fix, unchanged.
+          if (onProgress != null && entry.state === 'running' && !entry.historical && !narrativeJustFired) {
             const toolLine = describeToolUse(ev.toolName, ev.input ?? {})
             if (toolLine != null && toolLine.length > 0) {
               try {