switchroom 0.18.23 → 0.18.25

package/telegram-plugin/registry/turns-schema.ts

@@ -120,6 +120,26 @@ export interface Turn {
    * Null for turns that were never resumed.
    */
   resumed_at: number | null
+  /**
+   * The claude session id (the `<sessionId>.jsonl` transcript stem) that
+   * produced this turn's assistant output, stamped DURING the turn as soon as
+   * the first session event is observed (see `stampTurnSessionId`). Crash-
+   * survival redelivery uses this to resolve the EXACT transcript file for an
+   * interrupted turn, instead of `findActiveSessionFile`'s most-recent-mtime
+   * heuristic — which can shadow the new boot session's own transcript. Null
+   * until the turn produces its first session event (or for pre-migration rows).
+   */
+  session_id: string | null
+  /**
+   * Ms epoch at which the interrupted turn's captured-but-undelivered final
+   * answer was re-sent to the user at boot (crash-survival redelivery). This is
+   * the at-most-once ledger for redelivery — first-write-wins via
+   * `WHERE answer_redelivered_at IS NULL` (see `markAnswerRedelivered`). Kept on
+   * a SEPARATE marker from `resumed_at` because the two concerns have different
+   * correctness contracts (resume = at-most-once side-effect replay; redelivery
+   * = at-most-once answer send) and a turn can be both. Null until redelivered.
+   */
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -190,6 +210,15 @@ const PHASE3_MIGRATIONS = [
   `ALTER TABLE turns ADD COLUMN resumed_at INTEGER`,
 ]
 
+// Columns added for crash-survival redelivery. `session_id` pins the exact
+// transcript file for an interrupted turn (so redelivery never resolves the
+// wrong session via a most-recent-file heuristic); `answer_redelivered_at` is
+// the at-most-once redelivery ledger (stamped synchronously with the re-send).
+const PHASE4_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN session_id TEXT`,
+  `ALTER TABLE turns ADD COLUMN answer_redelivered_at INTEGER`,
+]
+
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
@@ -206,7 +235,7 @@ function applySchema(db: SqliteDatabase): void {
   // Run migrations. SQLite doesn't support "ADD COLUMN IF NOT EXISTS", so
   // we swallow the "duplicate column" error to stay idempotent on
   // pre-existing registry.db files.
-  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS]) {
+  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS, ...PHASE4_MIGRATIONS]) {
     try {
       db.exec(sql)
     } catch (err) {
@@ -283,6 +312,8 @@ interface RawTurnRow {
   tool_call_count: number | null
   interrupt_reason: string | null
   resumed_at: number | null
+  session_id: string | null
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -304,6 +335,8 @@ function mapRow(row: RawTurnRow): Turn {
     tool_call_count: row.tool_call_count,
     interrupt_reason: row.interrupt_reason,
     resumed_at: row.resumed_at,
+    session_id: row.session_id ?? null,
+    answer_redelivered_at: row.answer_redelivered_at ?? null,
     created_at: row.created_at,
     updated_at: row.updated_at,
   }
@@ -692,6 +725,61 @@ export function markTurnResumed(
   `).run(now, now, turnKey)
 }
 
+/**
+ * Stamp the claude `session_id` (the `<sessionId>.jsonl` transcript stem) on a
+ * turn the FIRST time it is observed, DURING the turn. First-write-wins via
+ * `WHERE session_id IS NULL` so the hot session-event path can call this on
+ * every event cheaply and idempotently. This must run while the turn is live
+ * (before any crash) so crash-survival redelivery can resolve the exact
+ * transcript file for an interrupted turn — never the most-recent-mtime file,
+ * which a fresh boot session would shadow. No-ops if `turnKey` is not found.
+ */
+export function stampTurnSessionId(
+  db: SqliteDatabase,
+  turnKey: string,
+  sessionId: string,
+  now: number = Date.now(),
+): void {
+  if (!sessionId) return
+  db.prepare(`
+    UPDATE turns
+    SET session_id = ?,
+        updated_at = ?
+    WHERE turn_key = ? AND session_id IS NULL
+  `).run(sessionId, now, turnKey)
+}
+
+/**
+ * Stamp `answer_redelivered_at` on an interrupted turn at the moment its
+ * captured-but-undelivered final answer has been re-sent at boot (crash-
+ * survival redelivery). This is the at-most-once ledger for redelivery: once
+ * stamped, the redelivery decision skips the turn on any later restart.
+ *
+ * Ordering: the caller stamps SYNCHRONOUSLY with the send (immediately after
+ * the send resolves), the same discipline as `markTurnResumed`. A residual
+ * race remains — the window between the Telegram send completing and this row
+ * (plus the send's own `role='assistant'` history row) becoming durable. A
+ * crash landing in that window could re-send on the next boot; the durable
+ * text-identity delivery oracle (matching the projected answer text against
+ * delivered `messages` rows) is what CATCHES that duplicate, so redelivery is
+ * at-most-once modulo detection, never a silent double-send of a fresh answer.
+ *
+ * Idempotent and first-write-wins (`WHERE answer_redelivered_at IS NULL`).
+ * No-ops if `turnKey` is not found.
+ */
+export function markAnswerRedelivered(
+  db: SqliteDatabase,
+  turnKey: string,
+  now: number = Date.now(),
+): void {
+  db.prepare(`
+    UPDATE turns
+    SET answer_redelivered_at = ?,
+        updated_at            = ?
+    WHERE turn_key = ? AND answer_redelivered_at IS NULL
+  `).run(now, now, turnKey)
+}
+
 /**
  * Return the single most-recently-started turn IFF it was interrupted
  * (`ended_at IS NULL`, or `ended_via` in {restart, sigterm, timeout,

package/telegram-plugin/reply-owner-resolve.ts

@@ -0,0 +1,160 @@
+/**
+ * Reply owner-turn resolution + answer-delivered latch decision
+ * (2026-07 double-reply-on-DM fix — completes the #3236 turnId-keyed dedup for
+ * the late-reply / DM path).
+ *
+ * ## The bug this closes
+ *
+ * On a DM agent a turn double-sent: the answer-ready quiescence flush posted the
+ * composed terminal answer as message A (no quote), then the model's REAL `reply`
+ * tool call landed a moment later and sent message B (quoted). The user should
+ * have received exactly ONE message (the quoted reply).
+ *
+ * #3236 shipped `flushed-turn-supersede.ts` — a turnId-identity-keyed dedup that
+ * is text-agnostic BY DESIGN. It missed here not because of the text rewording
+ * but because the reply's owner turn resolved to `null` on the late path:
+ *
+ *   - At reply consumption the gateway resolved the owner turn as
+ *     `currentTurn ?? findTurnByOriginId(origin_turn_id) ?? null`.
+ *   - `currentTurn` was already nulled by the flush's synthetic turn_end.
+ *   - `origin_turn_id` is a forum-supergroup field, ABSENT in DMs, so
+ *     `findTurnByOriginId` returned null.
+ *   - ⇒ the resolved live turnId was `null`, and `decideSupersede` deliberately
+ *     never lets a null live turn supersede a turnId-bearing flush record. No
+ *     supersede fired → message A survived AND the reply sent message B.
+ *
+ * The DECISIVE divergence: the gateway's *thread-routing* path DID recover the
+ * owner turn for the same late reply — via `findTurnByQuotedMessageId` (the
+ * framework-owned default quote target) and `findLatestEndedTurnForChat` (the
+ * chat's most-recently-ended turn). The supersede resolver chain omitted BOTH
+ * recoveries, so the two resolvers disagreed on who owned the reply. This module
+ * unifies them onto ONE precedence so they can never diverge again.
+ *
+ * ## Why a pure module
+ *
+ * `gateway.ts` is not importable in tests (heavy top-level side effects), so the
+ * repo's convention — `decideTurnFlush`, `decideSupersede`,
+ * `decideCapturedProseDelivery` — is to extract the decision core into a pure,
+ * unit-testable function and have the gateway run the EXACT code the regression
+ * tests exercise. The gateway performs the four turn lookups (currentTurn,
+ * findTurnByOriginId, findTurnByQuotedMessageId, findLatestEndedTurnForChat) and
+ * feeds their resolved turnIds here; the precedence lives in one place.
+ */
+
+/**
+ * The four owner-turn candidate ids, in the gateway's resolution precedence.
+ * Each is the `turnId` of the turn a given lookup resolved, or null when that
+ * lookup found nothing.
+ */
+export interface ReplyOwnerCandidates {
+  /** The LIVE `currentTurn` at reply-consumption time (null once the flush's
+   *  synthetic turn_end has torn the atom down — the late-reply case). */
+  liveTurnId: string | null
+  /** `findTurnByOriginId(origin_turn_id)` — the turn the model echoed back.
+   *  Null in DMs (no `origin_turn_id`) and when the model omitted the echo. */
+  originTurnId: string | null
+  /** `findTurnByQuotedMessageId(chat_id, reply_to)` — the framework-owned
+   *  quoted message id, resolved with NO model thread assertion. */
+  quotedTurnId: string | null
+  /** `findLatestEndedTurnForChat(chat_id)` — the chat's most-recently-ended
+   *  turn. The deterministic late-reply fallback (the DM path's recovery). */
+  latestEndedTurnId: string | null
+  /** Age (ms) of the latest-ended turn — `now - turn.endedAt`. The latest-ended
+   *  tier carries DESTRUCTIVE authority (it drives supersede deletion), so it is
+   *  honoured ONLY when the turn ended within `latestEndedTtlMs` (the supersede
+   *  TTL). Without the bound, a late reply belonging to an OLDER turn could
+   *  resolve its owner to a NEWER turn now sitting at the registry tail and
+   *  delete THAT turn's legit answer. Undefined/null ⇒ unbounded (back-compat:
+   *  callers that don't supply an age keep the pre-F2 behaviour). */
+  latestEndedAgeMs?: number | null
+  /** The supersede TTL bound applied to `latestEndedAgeMs`. Undefined ⇒
+   *  unbounded. */
+  latestEndedTtlMs?: number
+}
+
+/**
+ * Whether the latest-ended candidate is fresh enough to carry supersede
+ * (deletion) authority. A missing age or TTL means unbounded (back-compat).
+ */
+function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
+  if (candidates.latestEndedTurnId == null) return false
+  const age = candidates.latestEndedAgeMs
+  const ttl = candidates.latestEndedTtlMs
+  if (age == null || ttl == null) return true
+  return age <= ttl
+}
+
+/**
+ * Resolve the turnId that OWNS a landing reply, using the SAME full chain the
+ * thread-router uses. Precedence, first non-null wins:
+ *
+ *   1. the live `currentTurn`;
+ *   2. the model-echoed `origin_turn_id` turn;
+ *   3. the framework-owned quoted-message turn;
+ *   4. the chat's most-recently-ended turn.
+ *
+ * Returns null only when EVERY lookup missed (a genuinely unattributable reply),
+ * in which case `decideSupersede` keeps its null-safety semantics and declines
+ * to delete any turnId-bearing flush record.
+ */
+export function resolveReplyOwnerTurnId(candidates: ReplyOwnerCandidates): string | null {
+  return (
+    candidates.liveTurnId ??
+    candidates.originTurnId ??
+    candidates.quotedTurnId ??
+    (latestEndedAccepted(candidates) ? candidates.latestEndedTurnId : null) ??
+    null
+  )
+}
+
+/**
+ * The answer-delivered latch inputs (Part 2 — the race backstop).
+ *
+ * The unified resolver (Part 1) closes the common late-reply case where the
+ * flush fully COMPLETED (recorded its supersede entry) before the reply landed:
+ * supersede then deletes message A and the reply delivers as the single clean
+ * message B. But a residual race remains — a reply whose supersede `take()` runs
+ * in the window AFTER the flush FIRED but BEFORE it recorded its message ids.
+ * There `flushed-turn-supersede` finds no record (nothing to delete yet) and the
+ * reply would ship message B as a duplicate of the flush's message A.
+ *
+ * The latch closes that window: the gateway sets `answerDelivered = true` on the
+ * turn atom SYNCHRONOUSLY at flush-fire time — before the ~500 ms async send and
+ * before the record — and the flag persists on the ended turn (readable via the
+ * unified resolver after `currentTurn` is null). A reply landing in the race
+ * window then sees the latch already set and suppresses itself.
+ */
+export interface AnswerLatchSuppressInput {
+  /** True when Part 1's supersede already fired for THIS reply (message A was
+   *  deleted and this reply IS the sanctioned replacement). The latch must NOT
+   *  then also suppress — that would leave the turn with ZERO messages. */
+  superseded: boolean
+  /** True when the landing reply is a substantive terminal answer (the same
+   *  ≥200-char `FINAL_ANSWER_MIN_CHARS` floor the flush latch is scoped to).
+   *  A sub-floor interim ack (short, `disable_notification`) is never a final
+   *  answer, so it neither sets nor trips the latch. */
+  replySubstantive: boolean
+  /** True when this is a LATE reply — `currentTurn` was already null at
+   *  consumption. The flush-duplicate ALWAYS lands late (the flush's synthetic
+   *  turn_end nulled the atom); scoping suppression to the late path leaves a
+   *  legitimate second in-turn substantive reply (a genuine multi-message
+   *  answer, live currentTurn) untouched. */
+  isLateReply: boolean
+  /** The resolved owner turn's `answerDelivered` latch. */
+  ownerAnswerDelivered: boolean
+}
+
+/**
+ * Decide whether the answer-delivered latch suppresses a landing reply.
+ *
+ * Suppress IFF: Part 1 did NOT already supersede, the reply is a substantive
+ * final answer, it is a late reply (no live turn), AND the owner turn's latch is
+ * already set (the flush delivered the same substantive answer as message A in
+ * the pre-record race window). Otherwise the reply sends.
+ */
+export function decideAnswerLatchSuppression(input: AnswerLatchSuppressInput): boolean {
+  if (input.superseded) return false
+  if (!input.replySubstantive) return false
+  if (!input.isLateReply) return false
+  return input.ownerAnswerDelivered
+}

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

package/telegram-plugin/subagent-watcher.ts

@@ -125,6 +125,19 @@ export interface WorkerEntry {
   lastActivityAt: number
   /** Number of tool calls seen so far. */
   toolCount: number
+  /**
+   * Running TOTAL tokens across every assistant message the worker has emitted
+   * (input + output + cache_creation, summed via sumUsageTokens; cache_read is
+   * excluded — replayed cached context, not new work).
+   * Accumulated from `sub_agent_usage` events, deduped by `seenUsageMessageIds`
+   * so the multi-line split-message shape (one logical message persisted as
+   * several JSONL lines sharing one `message.id` + identical `usage`) counts
+   * once. Rendered on the worker card's metrics line. 0 for a worker that never
+   * emitted a usage block (e.g. a non-Claude/litellm transcript).
+   */
+  totalTokens: number
+  /** message.id set already folded into `totalTokens` (usage dedup). */
+  seenUsageMessageIds: Set<string>
   /** True once a stall notification has been sent (suppresses repeat). */
   stallNotified: boolean
   /**
@@ -557,6 +570,9 @@ export interface SubagentWatcherConfig {
     state: WorkerState
     outcome: 'completed' | 'failed' | 'orphan'
     toolCount: number
+    /** Final running TOTAL tokens across the worker's whole life
+     *  (`WorkerEntry.totalTokens`). For the terminal worker-feed card. */
+    totalTokens: number
     durationMs: number
     /** Dispatch-time task description, for the handback envelope. */
     description: string
@@ -615,6 +631,10 @@ export interface SubagentWatcherConfig {
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Running TOTAL tokens across the worker's assistant messages so far
+     *  (`WorkerEntry.totalTokens`). Threaded onto the worker/nested card's
+     *  metrics line. 0 for a worker that has emitted no usage yet / ever. */
+    totalTokens: number
     /** Friendly display line for THIS tick. Set on `sub_agent_tool_use`
      *  events to a `describeToolUse` label ("Reading X", "Running a
      *  command") so a foreground sub-agent that runs tools without
@@ -1089,6 +1109,8 @@ export function readSubTail(
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Running total tokens so far (see SubagentWatcherConfig.onProgress). */
+    totalTokens: number
     /** Friendly display line for THIS tick (set on tool ticks; see the
      *  SubagentWatcherConfig.onProgress doc). */
     progressLine?: string
@@ -1179,6 +1201,7 @@ export function readSubTail(
               },
               lastTool: entry.lastTool,
               toolCount: entry.toolCount,
+              totalTokens: entry.totalTokens,
               model: entry.currentModel,
               skeleton: true,
             })
@@ -1320,6 +1343,7 @@ export function readSubTail(
               },
               lastTool: entry.lastTool,
               toolCount: entry.toolCount,
+              totalTokens: entry.totalTokens,
               model: entry.currentModel,
             })
             return true
@@ -1502,6 +1526,22 @@ export function readSubTail(
           }
           continue
         }
+        if (ev.kind === 'sub_agent_usage') {
+          // Accumulate the worker's running total tokens, deduped by
+          // message.id: the ≥2.1.x split-message shape stamps the SAME `usage`
+          // block on every JSONL line of one logical assistant message, so
+          // counting each line would 2-3x over-count. A null messageId is
+          // un-dedupable (older/edge shapes) — count it as-is (its usage is
+          // real). No card render here; the total rides the next onProgress
+          // tick's payload like the model does.
+          if (ev.messageId == null) {
+            entry.totalTokens += ev.totalTokens
+          } else if (!entry.seenUsageMessageIds.has(ev.messageId)) {
+            entry.seenUsageMessageIds.add(ev.messageId)
+            entry.totalTokens += ev.totalTokens
+          }
+          continue
+        }
         if (ev.kind === 'sub_agent_tool_use') {
           // Narrative-dedup gate step 2: a sub_agent_text block was pending;
           // this tool is the lookahead that decides it (SHOW unless it drafts
@@ -1567,6 +1607,7 @@ export function readSubTail(
                   },
                   lastTool: entry.lastTool,
                   toolCount: entry.toolCount,
+                  totalTokens: entry.totalTokens,
                   progressLine: toolLine,
                   model: entry.currentModel,
                 })
@@ -1892,6 +1933,8 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       dispatchedAt: n,
       lastActivityAt: n,
       toolCount: 0,
+      totalTokens: 0,
+      seenUsageMessageIds: new Set<string>(),
       stallNotified: false,
       stalledAt: null,
       completionNotified: false,
@@ -2157,6 +2200,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             // registerAgent's short-circuit + Gap 1 promotion).
             outcome: entry.errored ? 'failed' : entry.historical ? 'orphan' : 'completed',
             toolCount: entry.toolCount,
+            totalTokens: entry.totalTokens,
             durationMs: nowFn() - entry.dispatchedAt,
             description: entry.description,
             // For a failure, fall back to the error detail when the worker
@@ -2184,6 +2228,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             state: entry.state,
             outcome: 'failed',
             toolCount: entry.toolCount,
+            totalTokens: entry.totalTokens,
             durationMs: nowFn() - entry.dispatchedAt,
             description: entry.description,
             resultText: entry.lastResultText,