switchroom 0.18.24 → 0.18.26

package/telegram-plugin/render/inline-pairs-guard.ts

@@ -0,0 +1,171 @@
+// Outbound guard against ACCIDENTAL inline-pair typesetting — the sibling of the
+// dollar-math guard (#3252 follow-up). Mirrors that guard's doctrine exactly.
+//
+// ── Root cause (same seam, same class of bug) ─────────────────────────────
+// Since the Bot API 10.1 migration (#2669) every assistant reply is sent to
+// Telegram as RAW GFM markdown via `sendRichMessage({ markdown })`; Telegram
+// parses it server-side. Telegram's rich GFM parser honours several PAIRED
+// inline-formatting delimiters that ordinary prose can form by accident:
+//
+//   • `~text~` / `~~text~~`  → strikethrough
+//   • `==text==`             → highlight / "marked" (Telegram 10.1 supports it)
+//   • `||text||`             → spoiler
+//   • `` `text` ``           → code span
+//
+// switchroom's `escapeMarkdown` (format.ts) backslash-escapes exactly these
+// trigger chars (`` ` `` `*` `_` `~` `=` `|` `[` `]`) for DYNAMIC card content —
+// which is our IN-REPO EVIDENCE that Telegram's rich parser genuinely INTERPRETS
+// `~ = |` and `` ` `` as formatting (otherwise escaping them would be pointless).
+// But the assistant's free-form reply body is NOT run through escapeMarkdown
+// (that would nuke the agent's DELIBERATE `~~strike~~` / `||spoiler||` /
+// `` `code` `` formatting — Ken's rich-formatting directive). So an ordinary
+// reply like "trims it to ~10 units, down from ~20" can accidentally form a
+// `~…~` strikethrough span across "10 units, down from ".
+//
+// ── Which of the four we actually guard (and why) ─────────────────────────
+// Ranked by real-world likelihood in normal agent prose:
+//
+//  1. TILDE  `~`  — HIGH. Approximation tildes on numbers ("~10", "~$5M",
+//     "~.5s") are extremely common in agent prose and two of them form a
+//     strikethrough pair. GUARDED.
+//  2. MARK   `==` — MEDIUM. Equality/comparison operators in prose ("x==y",
+//     "if a==b and c==d") sit word-flanked and two of them form a highlight
+//     span. GUARDED.
+//  3. SPOILER `||` — LOW. Logical-OR in prose ("a||b || c||d"). Rare but the
+//     same word-flanked shape, same fix. GUARDED (cheap, precise).
+//  4. BACKTICK `` ` `` — SKIPPED as effectively-literal. A TRULY unpaired
+//     backtick renders LITERALLY per CommonMark (a backtick run with no
+//     equal-length closer is left as text — this is exactly what
+//     `findClosingBackticks` returns -1 for, so `splitCodeSegments` already
+//     leaves it in a PROSE segment untouched). The only case a stray backtick
+//     "mis-renders" is an ODD count where an earlier pair swallows prose into a
+//     code span — but that is INDISTINGUISHABLE from an intended `` `code` ``
+//     span plus a separate literal backtick, and the agent uses `` `code` ``
+//     deliberately. Per the false-negative-beats-false-positive rule we leave
+//     it. (Neutralising it would risk mangling real code spans, which the task
+//     forbids.) See the design note for the full verification.
+//
+// ── The heuristic — precision over recall, never touch intended formatting ──
+// The hard constraint: the agent DELIBERATELY emits `~~strike~~`, `||spoiler||`
+// and `` `code` `` as wanted formatting. We must neutralise ONLY the
+// unmistakably-accidental shape and leave every intended span byte-identical.
+//
+//  • TILDE: a `~` is accidental only when it is DIGIT-ADJACENT — immediately
+//    followed by an optional `$`/`.` and a digit (`~10`, `~$5`, `~.5`). Intended
+//    strikethrough wraps WORDS (`~~deprecated~~`, `~struck~`) → its tildes are
+//    letter-adjacent, never matched. We arm only when 2+ such digit-adjacent
+//    tildes exist in prose (one alone can never form a pair), then escape them.
+//    This also catches the inner tilde of a `~~10` double-open.
+//
+//  • MARK / SPOILER: the delimiter is accidental only when it is a binary
+//    OPERATOR — i.e. flanked by a word char on BOTH sides (`x==y`, `a||b`).
+//    An INTENDED `==mark==` / `||spoiler||` has its opening delimiter preceded
+//    by whitespace/line-start and its closing delimiter followed by
+//    whitespace/line-end, so it is NEVER word-flanked on both sides. We arm only
+//    when 2+ such both-word-flanked operators exist (a lone one cannot form a
+//    span, and a space-flanked `a == b` cannot open a span under CommonMark
+//    left/right-flanking rules, so both are correctly left alone), then escape.
+//
+// When in doubt we LEAVE IT: a missed neutralisation (reader sees an accidental
+// strike) is strictly better than shredding the agent's intended formatting.
+//
+// ── Mechanics (identical to the dollar guard) ─────────────────────────────
+//  • Code-span/fence aware: reuses `splitCodeSegments` from dollar-math-guard so
+//    NOTHING inside a `` `code` `` span or fenced block is ever touched.
+//  • Deterministic pure string transform; strict NO-OP unless a real signal is
+//    present (2+ of a construct in prose).
+//  • Idempotent: escaped output (`\~`, `\=\=`, `\|\|`) can never re-match the
+//    triggers (the `~` case uses a `(?<!\\)` negative-lookbehind; the `==`/`||`
+//    cases can't recur because the escaped form no longer contains two
+//    consecutive `=`/`|`), so running the guard twice is byte-for-byte stable.
+//
+// ── Telegram assumptions requiring live UAT (Vitest CANNOT cover these) ────
+//  (a) That Telegram's rich parser CONSUMES the backslash so the reader sees a
+//      literal `~` / `=` / `|` (not a visible `\`). Asserted by analogy to
+//      `escapeMarkdown`, which backslash-escapes these very chars and which the
+//      whole card system depends on Telegram stripping.
+//  (b) Whether a SINGLE `~` renders strikethrough on the rich path (GitHub GFM
+//      needs `~~`; Telegram MarkdownV2 uses single `~`). Our digit-adjacent
+//      heuristic is correct under BOTH readings, but the *likelihood* ranking of
+//      the tilde case depends on it.
+//  (c) That `==` highlight and `||` spoiler render for the word-flanked operator
+//      shape (left/right-flanking behaviour).
+// Send real prose through a live agent and confirm literal glyphs before merge.
+
+// `splitProtectedSegments` skips code spans/fences AND markdown link
+// destinations / autolinks / GFM table rows verbatim — so a `~`/`==`/`||` that
+// is STRUCTURAL (in a URL query like `?a==1`, or a table's empty cell `|a||b|`)
+// is never escaped. See code-segments.ts.
+import { splitProtectedSegments } from './code-segments.js'
+
+/** Digit-adjacent tilde: `~` directly before an optional `$`/`.` and a digit
+ *  (`~10`, `~$5`, `~.5`). The `(?<!\\)` keeps it idempotent — an already-escaped
+ *  `\~` is never re-escaped. Global: used for both counting and replacement. */
+const TILDE_APPROX = /(?<!\\)~(?=\$?\.?\d)/g
+
+/** A `==` acting as a binary operator: word char on BOTH sides (`x==y`). Never
+ *  matches an intended `==mark==` (whose delimiters are whitespace-flanked on
+ *  the outside). Idempotency is structural — the escaped `\=\=` holds no two
+ *  consecutive `=`, so it can never re-match. Global. */
+const MARK_OP = /(?<=\w)==(?=\w)/g
+
+/** A `||` acting as a binary operator: word char on BOTH sides (`a||b`). Never
+ *  matches an intended `||spoiler||`. Structurally idempotent like `MARK_OP`.
+ *  Global. */
+const SPOILER_OP = /(?<=\w)\|\|(?=\w)/g
+
+/** Count matches of a global regex in a string (throwaway, resets lastIndex via
+ *  match). */
+function countMatches(text: string, re: RegExp): number {
+  return text.match(re)?.length ?? 0
+}
+
+/**
+ * Neutralise ACCIDENTAL inline-pair formatting (`~…~` strikethrough,
+ * `==…==` highlight, `||…||` spoiler) that Telegram's rich GFM parser would
+ * typeset from ordinary prose.
+ *
+ * Operates on the FINAL rendered rich-markdown string (post-`render`), at the
+ * same `richMessage()` seam as `guardDollarMath`. A strict NO-OP unless the
+ * prose (non-code) content holds 2+ of a construct in its clearly-accidental
+ * shape (digit-adjacent tildes; word-flanked `==`/`||` operators). Code spans /
+ * fenced blocks are NEVER touched, and the agent's DELIBERATE `~~strike~~` /
+ * `||spoiler||` / `==mark==` / `` `code` `` formatting passes through untouched.
+ * Deterministic and idempotent.
+ */
+export function guardAccidentalInlinePairs(text: string): string {
+  // Fast bail: none of the guarded trigger chars are present.
+  if (!/[~=|]/.test(text)) return text
+
+  const segments = splitProtectedSegments(text)
+
+  // Arm each construct independently, counting only PROSE (never code). A single
+  // occurrence can never form a pair, so the threshold is 2.
+  let tildes = 0
+  let marks = 0
+  let spoilers = 0
+  for (const seg of segments) {
+    if (seg.code) continue
+    tildes += countMatches(seg.text, TILDE_APPROX)
+    marks += countMatches(seg.text, MARK_OP)
+    spoilers += countMatches(seg.text, SPOILER_OP)
+  }
+
+  const armTilde = tildes >= 2
+  const armMark = marks >= 2
+  const armSpoiler = spoilers >= 2
+  if (!armTilde && !armMark && !armSpoiler) return text
+
+  return segments
+    .map((seg) => {
+      if (seg.code) return seg.text
+      let out = seg.text
+      // `\~` — first tilde of an accidental pair can no longer pair.
+      if (armTilde) out = out.replace(TILDE_APPROX, () => '\\~')
+      // `\=\=` / `\|\|` — the operator can no longer open/close a span.
+      if (armMark) out = out.replace(MARK_OP, () => '\\=\\=')
+      if (armSpoiler) out = out.replace(SPOILER_OP, () => '\\|\\|')
+      return out
+    })
+    .join('')
+}

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

@@ -0,0 +1,167 @@
+// Outbound guard against accidental LINE-START BLOCK CONSTRUCTS (issue #3252,
+// sibling of dollar-math-guard.ts).
+//
+// ── Root cause ───────────────────────────────────────────────────────────
+// Since the Bot API 10.1 migration (#2669) every assistant reply is sent to
+// Telegram as RAW GFM markdown via `sendRichMessage({ markdown })`. Telegram
+// parses that markdown server-side with a CommonMark/GFM-family parser. That
+// means a line of ordinary PROSE that merely happens to START with a markdown
+// block-construct trigger (`#`, `>`, `-`/`+`/`*`, or `N.`) can be silently
+// promoted to a heading / blockquote / bullet / ordered-list item the model
+// never intended:
+//   "> 50% of users"  → blockquote        ">2x faster" → blockquote
+//   "# of items"      → heading           "#1 priority" → (see below)
+//   "- 5 degrees"     → bullet            "2026. was a great year" → ol item
+//
+// ── Why this is the HARD, AMBIGUOUS guard family ─────────────────────────
+// Unlike the `$…$` currency case (where math typesetting of a two-dollar span
+// is NEVER wanted), the agent DELIBERATELY emits headings, bullets, ordered
+// lists and blockquotes — Ken's rich-formatting directive treats them as a
+// wanted feature. The SAME leading character means "format this" (intended)
+// or "literal prose" (accidental) depending purely on authorial intent, which
+// is not recoverable from the bytes. A blanket line-start escape would DESTROY
+// intended formatting and is unacceptable. So this guard is deliberately
+// CONSERVATIVE: it escapes ONLY the narrow sub-patterns that are unmistakably
+// accidental and can be disambiguated DETERMINISTICALLY from the byte stream,
+// and it leaves every plausibly-intended construct byte-for-byte untouched.
+// Everything that cannot be made safe is DEFERRED (see the block comment on
+// `escapeAccidentalLineStart` and guard-linestart-note.md), NOT guessed at.
+//
+// ── What this guard ACTUALLY escapes (the safe subset) ───────────────────
+//   1. Blockquote comparison-operator: a line-start `>` glued DIRECTLY to a
+//      digit or `=` (`>2x`, `>50%`, `>=3`). An INTENDED blockquote is always
+//      written `> ` WITH a space; `>` glued to a digit/`=` is a "greater than"
+//      comparison in prose, never a blockquote. Escaping only the no-space,
+//      digit/`=`-adjacent form leaves every real `> quoted line` untouched.
+//   2. Ordered-list with a 4+ digit "number": a line starting `2026. ` /
+//      `1999) ` — i.e. a YEAR or other 4+ digit integer followed by `.`/`)`
+//      and a space. No real numbered list is authored starting at item 2026;
+//      4+ digit leading integers are effectively always accidental years/
+//      quantities. Real lists (`1.`–`999.`) are LEFT ALONE.
+// Both are backslash-escaped (`\>`, `2026\.`) exactly like the dollar guard —
+// `>`, `.`, `)` are ASCII punctuation, escapable per CommonMark's "any ASCII
+// punctuation may be backslash-escaped" rule; Telegram's rich parser strips
+// the backslash the same way `escapeMarkdown` relies on for `~ = | * _`.
+//
+// ── 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
+//     spaced form would eat intended bullets, so the whole family is deferred.
+//   • Ordered-list with 1–3 digit numbers (`1. `, `42. `): ambiguous with a
+//     real numbered list. Decimals (`3.14`) have no space after the dot → not
+//     a list item → already literal.
+//
+// ── Where this runs ──────────────────────────────────────────────────────
+// Same seam as the dollar guard: `richMessage()` (rich-send.ts) — the ONE
+// adapter every `{ markdown }` wire send funnels through. Integration of this
+// function into that seam is done SEPARATELY by the integrator; this file only
+// exports the pure transform + its helpers. `plain`-mode degradations bypass
+// `richMessage` (no markdown parsing) and are correctly untouched.
+//
+// Idempotent: an already-escaped `\>` / `2026\.` no longer matches the
+// accidental patterns (the leading char is now `\`), so re-running is a strict
+// no-op. Code spans / fenced code blocks and 4-space indented code lines are
+// NEVER touched.
+//
+// ── Telegram-parser assumptions requiring live UAT (see note) ────────────
+// Vitest cannot cover server-side Telegram rendering. The two claims this
+// guard rests on — (a) Telegram promotes `>2x` (no space) and `2026. ` to
+// blockquote/ordered-list, and (b) it CONSUMES the escaping backslash so the
+// reader sees a literal `>` / `.` (not `\>` / `\.`) — are asserted by analogy
+// to CommonMark + the `escapeMarkdown` chars Telegram demonstrably strips.
+// Both need a live round-trip before merge. See guard-linestart-note.md.
+
+// Segment splitting is shared across all #3252 guards — one source of truth in
+// render/code-segments.ts. `splitProtectedSegments` skips code spans/fences AND
+// link destinations / autolinks / GFM table rows verbatim.
+import { splitProtectedSegments } from "./code-segments.js";
+
+/** Line-start `>` glued directly to a digit or `=` — the "greater than"
+ *  comparison-operator prose that Telegram wrongly quotes. NOT matched when a
+ *  space follows the `>` (that is an intended blockquote). */
+const ACCIDENTAL_BLOCKQUOTE = /^>[0-9=]/;
+
+/** Line-start 4+ digit integer followed by `.`/`)` then a space or end-of-line
+ *  — a year/quantity Telegram wrongly promotes to an ordered-list item. Real
+ *  lists (1–3 digit markers) are excluded by the `{4,}` bound. */
+const ACCIDENTAL_ORDERED_LIST = /^(\d{4,})([.)])(\s|$)/;
+
+/**
+ * Escape the accidental block-construct trigger at the start of ONE line
+ * (the string must NOT contain a newline). Applies only when the line is a
+ * true line start (the caller guarantees this). A no-op unless the line begins
+ * with one of the narrow, deterministically-accidental patterns above.
+ *
+ * Lines indented 4+ spaces are an indented-code context in CommonMark and are
+ * left verbatim.
+ */
+function escapeAccidentalLineStart(line: string): string {
+  const indent = /^ */.exec(line)![0];
+  // 4+ leading spaces => indented code block; never a block construct here.
+  if (indent.length >= 4) return line;
+  const rest = line.slice(indent.length);
+
+  // 1. Accidental blockquote (`>2x`, `>50%`, `>=3`). Idempotent: an already
+  //    escaped `\>` starts with `\`, so `rest` no longer starts with `>`.
+  if (ACCIDENTAL_BLOCKQUOTE.test(rest)) {
+    return indent + "\\" + rest;
+  }
+
+  // 2. Accidental ordered-list from a 4+ digit number (`2026. was`).
+  //    Idempotent: `2026\.` has a `\` where the delimiter was, so the
+  //    `(\d{4,})([.)])` shape no longer matches.
+  const ol = ACCIDENTAL_ORDERED_LIST.exec(rest);
+  if (ol) {
+    const digits = ol[1];
+    const delim = ol[2];
+    return indent + digits + "\\" + delim + rest.slice(digits.length + 1);
+  }
+
+  return line;
+}
+
+/**
+ * Neutralise accidental line-start block constructs (heading / blockquote /
+ * bullet / ordered-list promotion of prose) on the FINAL rendered rich-markdown
+ * string (post-`render`). CONSERVATIVE and deterministic: escapes ONLY the two
+ * unmistakably-accidental patterns documented above and leaves all plausibly
+ * intended formatting untouched. Code spans / fenced blocks / 4-space indented
+ * code are never touched. Idempotent and a strict no-op absent a real signal.
+ */
+export function guardAccidentalBlockConstructs(text: string): string {
+  // Cheap short-circuit: no `>` and no plausible 4+ digit list marker => no-op.
+  if (!text.includes(">") && !/\d{4,}[.)]/.test(text)) 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;
+      // Code spans never contain a newline; fenced blocks end on backticks, not
+      // a newline. Either way the next char is on the same line unless the code
+      // text itself ends with a newline.
+      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 ? escapeAccidentalLineStart(lines[k]) : lines[k];
+      out += processed;
+      if (k < lines.length - 1) out += "\n";
+    }
+    atLineStart = seg.text.endsWith("\n");
+  }
+
+  return out;
+}

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

@@ -67,6 +67,13 @@ export function renderOutbound(
   maxLen: number = RICH_MESSAGE_MAX_CHARS,
 ): RenderResult {
   return renderSafe(parse(text), text, maxLen);
+  // #3252 note: the `$…$` currency-math neutraliser (`guardDollarMath`) is NOT
+  // applied here. It lives at the single wire seam — `richMessage()` in
+  // rich-send.ts — through which EVERY `{ markdown }` send funnels (the
+  // reply-tool final answer, the draft-stream previews this renderer feeds,
+  // cards, approvals). Applying it there guards every markdown-parsed outbound
+  // exactly once (F1), and `plain`-mode degradations correctly bypass it. See
+  // dollar-math-guard.ts for the rationale.
 }
 
 /**

package/telegram-plugin/rich-send.ts

@@ -18,15 +18,61 @@
  */
 
 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 { guardAccidentalInlinePairs } from './render/inline-pairs-guard.js'
 
 /** The `InputRichMessage` shape grammy 1.44 accepts on send AND edit. */
 export interface InputRichMessageMarkdown {
   markdown: string
 }
 
-/** Wrap raw GFM markdown into the rich-message input object. */
+/**
+ * Neutralise ALL accidental Telegram markdown typesetting in one composed pass
+ * (#3252). Each sub-guard targets a DISJOINT set of trigger characters, skips
+ * code spans / fenced blocks verbatim (shared `splitCodeSegments`), is a strict
+ * no-op absent a real signal, and is idempotent — so the composition is itself
+ * idempotent and safe to apply once per send.
+ *
+ * ── Ordering (deliberate, not arbitrary) ──────────────────────────────────
+ * `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
+ * `~$5M and ~$10M` would become `~\$5M …`, and the interposed `\` would hide
+ * the digit-adjacent tildes from `guardAccidentalInlinePairs`, leaving the
+ * accidental `~…~` strikethrough pair un-neutralised (a false negative /
+ * residual bug). Running inline-pairs FIRST escapes the tildes (`\~$5M`), then
+ * the dollar guard escapes the `$` — both spans are killed. Every other pair of
+ * guards is disjoint in the characters it inspects AND the characters it
+ * inserts (`\_ \* \> \. \~ \=\= \|\|` vs `\$`), so no other insertion can
+ * create or destroy a signal for a sibling. Verified by composition tests.
+ */
+export function guardAccidentalFormatting(markdown: string): string {
+  let out = markdown
+  out = guardAccidentalEmphasis(out)
+  out = guardAccidentalBlockConstructs(out)
+  out = guardAccidentalInlinePairs(out)
+  out = guardDollarMath(out)
+  return out
+}
+
+/**
+ * Wrap raw GFM markdown into the rich-message input object.
+ *
+ * This is the ONE adapter every `{ markdown }` wire send funnels through
+ * (`sendRichMessage` / `editMessageText({ markdown })`) — the reply-tool final
+ * answer, draft-stream previews, cards, approvals, banners. It is therefore the
+ * single deterministic seam for the #3252 accidental-formatting guards (F1):
+ * applying `guardAccidentalFormatting` here guards EVERY markdown-parsed
+ * outbound exactly once, without touching `plain`-mode degradations (which
+ * bypass this wrapper and go straight to `sendMessage`, where no markdown
+ * parsing happens). The composed guard is a strict no-op for any body without
+ * an accidental-formatting signal and is idempotent, so callers that already
+ * ran it (or the streaming path that renders then re-wraps) stay byte-identical.
+ */
 export function richMessage(markdown: string): InputRichMessageMarkdown {
-  return { markdown }
+  return { markdown: guardAccidentalFormatting(markdown) }
 }
 
 /**

package/telegram-plugin/session-tail.ts

@@ -118,6 +118,17 @@ export type SessionEvent =
   // and reserved for a future staging-skip optimization; do not assume the
   // gate keys on it.
   | { kind: 'text'; text: string; blockIndex: number; lastInMessage: boolean }
+  // Per-assistant-message token usage for the MAIN agent, extracted from
+  // `message.usage` on each `type:"assistant"` transcript line. `totalTokens`
+  // is the NEW-work delta for THIS message (input + output + cache_creation,
+  // via sumUsageTokens; cache_read is deliberately excluded — replayed cached
+  // context, not new work). `messageId` is `message.id` —
+  // REQUIRED for dedup: Claude Code persists one logical assistant message as
+  // MULTIPLE JSONL lines sharing one `message.id`, each stamped with the SAME
+  // `usage` block, so the accumulator must count a given `messageId` only once
+  // (naive summing across lines over-counts). Null messageId → un-dedupable,
+  // counted as-is. Mirrors `sub_agent_usage` but for the parent's OWN tokens.
+  | { kind: 'usage'; messageId: string | null; totalTokens: number }
   | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
   // `reason` is set ONLY by an internal gateway-synthesized turn_end (never by
   // the JSONL projection). `answer-ready-quiescence` (PR A) marks the positive
@@ -134,6 +145,17 @@ export type SessionEvent =
   // `model` kind (sentinel-filtered, emitted first) but agent-scoped so the
   // watcher can track it per WorkerEntry and thread it onto the worker card.
   | { kind: 'sub_agent_model'; agentId: string; model: string }
+  // Per-assistant-message token usage for a SUB-AGENT, extracted from
+  // `message.usage` on each `type:"assistant"` transcript line. `totalTokens`
+  // is the NEW-work delta for THIS message (input + output + cache_creation;
+  // cache_read is deliberately excluded — replayed cached context, not new
+  // work). `messageId` is `message.id` — REQUIRED for dedup: Claude
+  // Code ≥2.1.x persists one logical assistant message as MULTIPLE JSONL lines
+  // sharing one `message.id`, each stamped with the SAME `usage` block, so the
+  // watcher must count a given `messageId` only once (naive summing across
+  // lines 2-3x over-counts; verified against live worker jsonl — 131 usage
+  // lines / 59 unique ids). Null messageId → un-dedupable, counted as-is.
+  | { kind: 'sub_agent_usage'; agentId: string; messageId: string | null; totalTokens: number }
   | { kind: 'sub_agent_tool_use'; agentId: string; toolUseId: string | null; toolName: string; input?: Record<string, unknown>; precomputedLabel?: string }
   // Same shared contract as the main-agent `text` kind — see its doc above
   // (including the `lastInMessage` projection-artifact note). The wire-kind
@@ -283,6 +305,34 @@ export function projectAssistantTextBlocks(
  * projectSubagentLine). A thinking-only or empty line returns false; the real
  * terminal rides the following content line, which also carries `end_turn`.
  */
+/**
+ * Sum the NEW token work carried by a single assistant message's `usage`
+ * object: `input_tokens + output_tokens + cache_creation_input_tokens`. Every
+ * field is guarded with `?? 0` — Claude Code omits fields that are zero/absent
+ * on some messages. A non-object (or missing) usage returns 0 so the caller
+ * can skip a no-usage line.
+ *
+ * `cache_read_input_tokens` is DELIBERATELY EXCLUDED. On a prompt-cached turn
+ * it is replayed context (billed at ~10% and doing no new work), and it
+ * dominates the raw total — including it made the displayed number 2-5x bigger
+ * than the actual work done this turn and misread as a cost/effort figure. The
+ * three fields kept here represent new tokens processed this turn: fresh input,
+ * generated output, and newly-written cache. The nested `iterations` /
+ * `cache_creation` breakdowns are subsets already reflected in the top-level
+ * fields — never add them, that double-counts. Verified against live worker
+ * jsonl.
+ */
+export function sumUsageTokens(usage: unknown): number {
+  if (usage == null || typeof usage !== 'object') return 0
+  const u = usage as Record<string, unknown>
+  const n = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+  return (
+    n(u.input_tokens) +
+    n(u.output_tokens) +
+    n(u.cache_creation_input_tokens)
+  )
+}
+
 export function assistantLineCarriesAnswerSurface(
   content: Array<Record<string, unknown>> | undefined,
 ): boolean {
@@ -303,6 +353,108 @@ export function assistantLineCarriesAnswerSurface(
   return false
 }
 
+export interface TrailingAnswer {
+  /** Concatenated trailing assistant text of the last turn (after the last
+   *  tool_use / turn boundary). Empty when there is none to redeliver. */
+  text: string
+  /** True iff the last content-bearing event of the transcript was text — i.e.
+   *  the turn ended on an answer, not a dangling tool_use (mid-stream). Bounds
+   *  the preamble-vs-final ambiguity for crash-survival redelivery. */
+  trailingIsText: boolean
+}
+
+/**
+ * Re-project the TRAILING assistant answer of the last turn from a claude
+ * session transcript's full text. Pure — reuses the same `projectTranscriptLine`
+ * kernel the live tail uses, so it inherits the `isApiErrorMessage` suppression
+ * (a usage-limit error line is NEVER resurfaced as an answer) and the empty-block
+ * drop. Used by crash-survival redelivery to recover the finished-but-never-sent
+ * answer from disk after a pre-flush crash.
+ *
+ * Semantics: walk the event stream in order; the "answer buffer" accumulates
+ * `text` events and is RESET by any `tool_use` (the answer-so-far was a preamble
+ * to a tool call) or by a turn boundary. What remains at end-of-file is the
+ * trailing answer of the last turn. `trailingIsText` is true only when the final
+ * content-bearing event was that text (not a tool_use), so a turn killed mid-tool
+ * never redelivers a stale preamble as an answer.
+ *
+ * TURN BOUNDARY (diff-review defect #2). A boundary is BOTH an `enqueue`
+ * queue-operation AND a real `type:"user"` message line. The kernel
+ * (`projectTranscriptLine`) emits nothing for a plain user text line — it only
+ * projects `tool_result` blocks out of `type:"user"` — so relying on `enqueue`
+ * alone would let two turns separated by a plain user line (no intervening
+ * tool_use) CONCATENATE. `isRealUserTurnBoundary` detects that separator
+ * directly so only the LAST turn's trailing text is projected.
+ */
+export function projectTrailingAnswerFromTranscript(transcriptText: string): TrailingAnswer {
+  const buf: string[] = []
+  let lastMeaningful: 'text' | 'tool_use' | null = null
+  for (const rawLine of transcriptText.split('\n')) {
+    const line = rawLine.trim()
+    if (!line) continue
+    if (isRealUserTurnBoundary(line)) {
+      // A real user message opens a new turn — discard any prior turn's tail.
+      buf.length = 0
+      lastMeaningful = null
+      continue
+    }
+    for (const ev of projectTranscriptLine(line)) {
+      if (ev.kind === 'enqueue') {
+        // New inbound turn — any prior turn's trailing text is not this turn's.
+        buf.length = 0
+        lastMeaningful = null
+      } else if (ev.kind === 'tool_use') {
+        buf.length = 0
+        lastMeaningful = 'tool_use'
+      } else if (ev.kind === 'text') {
+        const t = (ev as { text?: string }).text ?? ''
+        if (t.trim().length > 0) {
+          buf.push(t)
+          lastMeaningful = 'text'
+        }
+      }
+      // thinking / model / dequeue / tool_result etc. do not affect the answer.
+    }
+  }
+  const text = buf.join('').trim()
+  return { text, trailingIsText: lastMeaningful === 'text' && text.length > 0 }
+}
+
+/**
+ * Detect a real inbound-user turn separator in a claude session JSONL.
+ *
+ * A `type:"user"` line is EITHER a genuine user message (its `message.content`
+ * is a string, or an array carrying a `{type:"text"}` block) OR a tool_result
+ * carrier (`message.content` is an array of `{type:"tool_result"}` blocks only).
+ * Only the former opens a new turn. The main projection kernel emits NO event
+ * for a genuine user text line (it projects tool_result blocks only), so the
+ * trailing-answer projector needs this to break turns that are separated by a
+ * plain user line rather than an interleaved `enqueue` queue-operation. Pure.
+ */
+export function isRealUserTurnBoundary(line: string): boolean {
+  let obj: Record<string, unknown>
+  try {
+    obj = JSON.parse(line)
+  } catch {
+    return false
+  }
+  if (obj.type !== 'user') return false
+  const message = obj.message as Record<string, unknown> | undefined
+  const content = message?.content
+  if (typeof content === 'string') return content.trim().length > 0
+  if (Array.isArray(content)) {
+    // A genuine user message carries a text block; a tool_result carrier does
+    // not. Presence of any text block ⇒ real user turn.
+    for (const c of content) {
+      if (typeof c === 'object' && c != null && (c as Record<string, unknown>).type === 'text') {
+        const t = String((c as Record<string, unknown>).text ?? '')
+        if (t.trim().length > 0) return true
+      }
+    }
+  }
+  return false
+}
+
 /**
  * Project a single transcript line into a SessionEvent (or null if it's
  * uninteresting noise). Caller is responsible for the JSON parse — if a
@@ -364,6 +516,23 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     if (typeof mainModel === 'string' && !isModelSentinel(mainModel)) {
       events.push({ kind: 'model', model: mainModel })
     }
+    // Per-message token usage (MAIN tier): surface the summed delta so the
+    // gateway can accumulate the parent's OWN running total for the turn card's
+    // metrics line. `messageId` (message.id) rides along so the accumulator
+    // dedups the multi-line split-message shape (one logical message → many
+    // JSONL lines, one shared `usage`). Emitted only when a usage object with a
+    // non-zero total exists — a no-usage line contributes nothing and is
+    // skipped. Mirrors the sub-agent emit below; this counts the parent alone
+    // (sub-agents report their own tokens on their worker-feed rows).
+    const mainUsageTotal = sumUsageTokens(message?.usage)
+    if (mainUsageTotal > 0) {
+      const mainMsgId = message?.id
+      events.push({
+        kind: 'usage',
+        messageId: typeof mainMsgId === 'string' ? mainMsgId : null,
+        totalTokens: mainUsageTotal,
+      })
+    }
     // Text→narrative projection comes from the ONE shared kernel
     // (projectAssistantTextBlocks): it owns the empty-drop + blockIndex +
     // lastInMessage contract. We emit its events at their source positions
@@ -518,6 +687,22 @@ export function projectSubagentLine(
     if (typeof subModel === 'string' && !isModelSentinel(subModel)) {
       events.push({ kind: 'sub_agent_model', agentId, model: subModel })
     }
+    // Per-message token usage: surface the summed delta so the watcher can
+    // accumulate a running total for the worker-activity card's metrics line.
+    // `messageId` (message.id) rides along so the watcher dedups the multi-line
+    // split-message shape (one logical message → many JSONL lines, one shared
+    // `usage`). Emitted only when a usage object with a non-zero total exists —
+    // a no-usage line contributes nothing and is skipped here.
+    const subUsageTotal = sumUsageTokens(message?.usage)
+    if (subUsageTotal > 0) {
+      const subMsgId = message?.id
+      events.push({
+        kind: 'sub_agent_usage',
+        agentId,
+        messageId: typeof subMsgId === 'string' ? subMsgId : null,
+        totalTokens: subUsageTotal,
+      })
+    }
     // Text→narrative projection comes from the SAME shared kernel as the
     // main agent (projectAssistantTextBlocks): one source for the empty-drop
     // + blockIndex + lastInMessage contract. The `make` adapter only changes