@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/channels/telegram/inbound/file.js

@@ -1,8 +1,9 @@
 // Inbound Telegram FILES: document, video, video_note, animation.
 //
 // Same shape as ./photo.js and ./audio.js — take the poller (`self`) plus the
-// parsed update, download and archive the file, and return the (rewritten)
-// `text` the rest of the pipeline runs with.
+// parsed update, download the file, and return the (rewritten) `text` the rest
+// of the pipeline runs with plus the metadata dispatch folds into the one
+// record it writes for this update.
 //
 // Why this exists: dispatch only recognised photo and voice/audio. Every other
 // attachment fell through to `text = msg.caption || ""`, and a file sent with
@@ -13,8 +14,6 @@
 // The reply is model-authored, as everywhere else: the marker states what
 // arrived and where it landed, and the agent puts that in its own words. No
 // canned "file received" string.
-import { appendGlobalMessage } from "#core/stores/messages.js";
-import { CHANNELS } from "#core/constants/channels.js";
 import { resolveBotToken, telegramMediaDir } from "../helpers.js";
 import { downloadTelegramFile } from "../media.js";
 
@@ -49,10 +48,10 @@ function humanSize(bytes) {
 
 /**
  * @param {object} self  poller instance (uses self.log, self.channel)
- * @param {object} ctx   { msg, u, author, chat_id, text, incoming }
- * @returns {Promise<{ text: string }>}
+ * @param {object} ctx   { text, incoming }
+ * @returns {Promise<{ text: string, media: object }>}
  */
-export async function handleIncomingFile(self, { msg, u, author, chat_id, text, incoming }) {
+export async function handleIncomingFile(self, { text, incoming }) {
   const { file, label, type } = incoming;
   const token = resolveBotToken(self.channel);
   const mediaDir = telegramMediaDir();
@@ -72,30 +71,6 @@ export async function handleIncomingFile(self, { msg, u, author, chat_id, text,
     self.log(`telegram[${self.channel.name}] ${label} download failed: ${e.message}`);
   }
 
-  // Archive regardless of download outcome, so the history records the file
-  // even when the fetch failed.
-  appendGlobalMessage({
-    channel: CHANNELS.TELEGRAM,
-    direction: "in",
-    type,
-    actor_id: msg.from?.id ? String(msg.from.id) : author,
-    external_id: String(u.update_id),
-    author,
-    body: text || `[${label}]`,
-    meta: {
-      chat_id,
-      user_id: msg.from?.id || null,
-      message_id: msg.message_id,
-      tg_channel: self.channel.name,
-      local_path: localPath,
-      file_id: file.file_id,
-      file_name: declaredName || null,
-      mime_type: file.mime_type || null,
-      file_size: file.file_size || null,
-      duration: file.duration || null,
-    },
-  });
-
   const bits = [declaredName || label];
   const size = humanSize(file.file_size);
   if (size) bits.push(size);
@@ -104,5 +79,20 @@ export async function handleIncomingFile(self, { msg, u, author, chat_id, text,
     ? `[${label} received: ${bits.join(", ")} — saved to ${localPath}. You can open it with your file tools.]`
     : `[${label} received: ${bits.join(", ")} — the download FAILED (${failure || "unknown error"}), so there is no local copy. Say so; files over 20 MB cannot be fetched by a bot.]`;
 
-  return { text: text ? `${marker} ${text}` : marker };
+  return {
+    text: text ? `${marker} ${text}` : marker,
+    // Reported regardless of download outcome, so the stored turn records the
+    // file even when the fetch failed.
+    media: {
+      kind: type,
+      meta: {
+        local_path: localPath,
+        file_id: file.file_id,
+        file_name: declaredName || null,
+        mime_type: file.mime_type || null,
+        file_size: file.file_size || null,
+        duration: file.duration || null,
+      },
+    },
+  };
 }

package/src/core/channels/telegram/inbound/photo.js

@@ -10,19 +10,23 @@
 // with its tools. The marker also guarantees a no-caption photo never produces
 // an empty turn — the reply is always model-authored, never canned. Mirrors the
 // `[audio]` marker convention.
+//
+// The record itself is written by dispatch, once per update: this handler used
+// to append its own row while also rewriting `text`, so a photo turn was stored
+// twice. It now hands the file metadata back instead.
 import fs from "node:fs";
 import path from "node:path";
-import { appendGlobalMessage } from "#core/stores/messages.js";
-import { CHANNELS } from "#core/constants/channels.js";
 import { resolveBotToken, telegramMediaDir } from "../helpers.js";
 import { downloadTelegramFile } from "../media.js";
 
 /**
  * @param {object} self  poller instance (uses self.log, self.channel)
- * @param {object} ctx   { msg, u, author, chat_id, text }
- * @returns {Promise<{ text: string }>}  text to continue the pipeline with
+ * @param {object} ctx   { msg, text }
+ * @returns {Promise<{ text: string, attachment: object|null, media: object }>}
+ *   text to continue the pipeline with, the pixels for a multimodal engine, and
+ *   what was archived for the inbound record
  */
-export async function handleIncomingPhoto(self, { msg, u, author, chat_id, text }) {
+export async function handleIncomingPhoto(self, { msg, text }) {
   // Telegram sends multiple sizes; pick the largest.
   const bestPhoto = msg.photo.reduce((a, b) => (b.file_size > a.file_size ? b : a));
   const token = resolveBotToken(self.channel);
@@ -36,28 +40,6 @@ export async function handleIncomingPhoto(self, { msg, u, author, chat_id, text
     self.log(`telegram[${self.channel.name}] photo download failed: ${e.message}`);
   }
 
-  // Archive the inbound photo regardless of download outcome, so chat history
-  // records it even if the file fetch failed.
-  appendGlobalMessage({
-    channel: CHANNELS.TELEGRAM,
-    direction: "in",
-    type: "photo",
-    actor_id: msg.from?.id ? String(msg.from.id) : author,
-    external_id: String(u.update_id),
-    author,
-    body: text || "[photo]",
-    meta: {
-      chat_id,
-      user_id: msg.from?.id || null,
-      message_id: msg.message_id,
-      tg_channel: self.channel.name,
-      local_path: localPath,
-      file_id: bestPhoto.file_id,
-      width: bestPhoto.width,
-      height: bestPhoto.height,
-    },
-  });
-
   // Hand the pixels to the turn. A multimodal engine (Gemini) renders them as
   // an inlineData part; the others ignore the field and still have the marker
   // and the path, so nothing regresses for them.
@@ -81,7 +63,21 @@ export async function handleIncomingPhoto(self, { msg, u, author, chat_id, text
   const marker = localPath
     ? `[image attached — saved to ${localPath}]`
     : "[image attached — the download failed, there is no local copy]";
-  return { text: text ? `${marker} ${text}` : marker, attachment };
+  return {
+    text: text ? `${marker} ${text}` : marker,
+    attachment,
+    // Reported regardless of download outcome, so the stored turn records what
+    // arrived even when the fetch failed.
+    media: {
+      kind: "photo",
+      meta: {
+        local_path: localPath,
+        file_id: bestPhoto.file_id,
+        width: bestPhoto.width,
+        height: bestPhoto.height,
+      },
+    },
+  };
 }
 
 function mimeFromPath(p) {

package/src/core/channels/telegram/progress-gate.js

@@ -0,0 +1,76 @@
+// One notice, then the work, then the answer — the message budget for a
+// Telegram turn.
+//
+// Model prose is the ONLY thing Telegram ever receives mid-turn: tool names are
+// not sent (see reply.js), so this gate is not trimming a second channel of
+// activity — it is the whole of what the owner sees between "on it" and the
+// answer. That is why it opens rather than staying shut: hold the first line too
+// and a turn that takes four minutes of tool work looks like nothing happened.
+//
+// So this gate decides which stream events become chat messages:
+//
+//   - The FIRST line the model writes goes out as the turn opener. A turn whose
+//     model skips prose entirely and dives straight into tools stays silent —
+//     the typing indicator carries it, and nothing is invented on the agent's
+//     behalf.
+//   - Everything after it is held. The turn goes quiet — the typing indicator
+//     keeps ticking (poller._startTyping re-pings every 4s) — until the closing
+//     message the caller always sends.
+//   - Except on a long job: after `everyMs` of silence ONE more note is let
+//     through, so a four-minute turn still shows a sign of life instead of
+//     looking hung. `everyMs: 0` turns that off — strictly notice, work, answer.
+//
+// What is NOT gated here: the final reply. sendFinalReply always speaks, and
+// the never-silent floor still applies — a turn can lose its progress notes,
+// never its conclusion.
+//
+// Pure and clock-injectable: no I/O, no globals. The caller sends and logs.
+
+/** Seconds of silence before one more progress note is allowed through. */
+export const DEFAULT_PROGRESS_EVERY_S = 90;
+
+/**
+ * Read the knob: `super_agent.telegram_progress_every_s`.
+ * Unset → the built-in default. 0 (or anything unusable) → no mid-turn notes.
+ * @returns {number} milliseconds; 0 means "opening notice and closing only"
+ */
+export function progressEveryMs(globalConfig) {
+  const raw = globalConfig?.super_agent?.telegram_progress_every_s;
+  const secs = raw === undefined || raw === null || raw === "" ? DEFAULT_PROGRESS_EVERY_S : Number(raw);
+  if (!Number.isFinite(secs) || secs <= 0) return 0;
+  return Math.round(secs * 1000);
+}
+
+/**
+ * @param {{everyMs?: number, now?: () => number}} opts
+ * @returns {{ text: () => "send"|"hold", sinceLastMs: () => number }}
+ */
+export function createProgressGate({ everyMs = 0, now = Date.now } = {}) {
+  let opened = false;
+  let lastSentAt = 0;
+  const markSent = () => {
+    opened = true;
+    lastSentAt = now();
+  };
+  return {
+    /**
+     * The model produced a text segment ahead of its tool calls.
+     * "send" → it's the opening notice, or the heartbeat is due.
+     */
+    text() {
+      if (!opened) {
+        markSent();
+        return "send";
+      }
+      if (everyMs > 0 && now() - lastSentAt >= everyMs) {
+        markSent();
+        return "send";
+      }
+      return "hold";
+    },
+    /** Milliseconds since the last message we let through (for logging). */
+    sinceLastMs() {
+      return opened ? now() - lastSentAt : 0;
+    },
+  };
+}

package/src/core/channels/telegram/reply.js

@@ -11,57 +11,81 @@ import { stripThinking, stripReasoning } from "#core/util/thinking.js";
 import { appendGlobalMessage, getRecentTelegramTurnsFromFs } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
 import { summarizeToolTrace } from "#core/agent/tool-summary.js";
+import { authorLine } from "#core/agent/author-line.js";
+import { closingFloorLine } from "#core/agent/closing-floor.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
 import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
 import { t, resolveLang } from "#core/i18n/index.js";
 import { buildTelegramMeta, resolveBotToken } from "./helpers.js";
+import { createProgressGate, progressEveryMs } from "./progress-gate.js";
+import { deliverVoiceReply, mobilityVoiceActive } from "./voice-note.js";
 
 /**
- * Build the streaming event handler for a Telegram super-agent turn. Sends a
- * one-shot localized heads-up the moment real work starts (first tool), streams
- * each assistant-text iteration as its own chat message, and logs tool calls
- * (audit trail / other channels — never sent to Telegram). Returns the handler
- * plus a live `state` the caller reads AFTER the run to drive the final send.
+ * Build the streaming event handler for a Telegram super-agent turn. ONE notice
+ * goes out when work starts — the model's own opening line, the one the
+ * two-segment discipline has it write before the first tool — and the rest of
+ * the turn stays quiet until the caller sends the closing message. Nothing is
+ * ever written on the agent's behalf: a turn that opens straight into a tool
+ * stays quiet until the model itself speaks. The progress notes it writes
+ * before each later step are held back (see ./progress-gate.js for why, and for
+ * the long-job heartbeat that lets one through every N seconds).
+ *
+ * TOOL NAMES NEVER GO TO TELEGRAM. For one turn they did — a `⚙️ run_shell`
+ * line per tool start — and it was wrong on three counts. Telegram is a
+ * conversation, and "⚙️ run_shell" is not something a person says; it is
+ * untranslated machine vocabulary in a channel whose whole contract is natural
+ * prose. It also pushed a phone notification per tool step, so one turn buzzed
+ * a pocket ten times. And it was recorded as an agent-voiced outbound message,
+ * which is the shape that teaches a weak fallback model to WRITE tool names
+ * instead of calling tools — the failure stores/messages.js keeps out of the
+ * rolling history, precisely because history in the agent's own voice is what
+ * gets imitated.
+ *
+ * What shows activity instead is the model's own opening line plus the typing
+ * indicator, which the caller holds open for the whole turn (_startTyping) and
+ * this handler refreshes at each tool start. Tool calls are still logged in
+ * full for the audit trail and the other channels — see the `tool_result`
+ * branch, which records tool, args and result for every call.
+ *
+ * Returns the handler plus a live `state` the caller reads AFTER the run to
+ * drive the final send.
  *
  * `state.model` tracks the model actually answering RIGHT NOW (it can rotate
  * mid-turn on a fallback), so every record this handler writes is stamped with
  * the model that produced it — not with the one the turn happened to end on.
  *
- * @returns {{ onEvent: Function, state: { streamedCount: number, lastStreamedText: string, model: string } }}
+ * @returns {{ onEvent: Function, state: { streamedCount: number, lastStreamedText: string, heldCount: number, model: string } }}
  */
 export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
-  const state = { streamedCount: 0, lastStreamedText: "", sentHeadsUp: false, model: "" };
+  const state = { streamedCount: 0, lastStreamedText: "", heldCount: 0, model: "" };
+  const gate = createProgressGate({ everyMs: progressEveryMs(self.globalConfig) });
   const onEvent = async (ev) => {
     try {
       if ((ev.type === "model_start" || ev.type === "model_routed" || ev.type === "final_wrapup") && ev.model) {
         state.model = ev.model;
       }
-      if (ev.type === "tool_start" && !state.sentHeadsUp && state.streamedCount === 0) {
-        state.sentHeadsUp = true;
-        const heads = t("telegram.heads_up", { lang: resolveLang(self.globalConfig) });
-        await self._send({ chat_id, text: heads });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "agent",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          agent_slug: SUPERAGENT_ACTOR_ID,
-          author: agentDisplay,
-          body: heads,
-          meta: { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, heads_up: true, ...(state.model ? { model: state.model } : {}) },
-        });
-        return;
-      }
       if (ev.type === "assistant_text" && ev.text) {
         // Untagged planning is suppressed mid-stream too, or the user
         // watches the model think in real time.
         const piece = stripReasoning(ev.text).answer.trim();
         if (!piece) return;
+        if (gate.text() === "hold") {
+          // Held, not lost: it was a pre-tool filler line, and the closing
+          // message carries the result. Logged by size only — the ledger
+          // records what the user actually received, and the daemon log is
+          // not the place to copy conversation text.
+          state.heldCount += 1;
+          self.log(
+            `telegram[${self.channel.name}] progress note held ` +
+            `(#${state.heldCount}, ${piece.length} chars, ${Math.round(gate.sinceLastMs() / 1000)}s of quiet)`
+          );
+          return;
+        }
         await self._send({ chat_id, text: piece });
         state.lastStreamedText = piece;
         state.streamedCount += 1;
+        // attribution-exempt: mid-stream segment — token usage is only known at turn end; the final row carries model+usage.
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
           direction: "out",
@@ -73,6 +97,17 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
           body: piece,
           meta: { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, streamed: true, iteration: ev.iteration, ...(state.model ? { model: state.model } : {}) },
         });
+      } else if (ev.type === "tool_start" && ev.trace) {
+        // Nothing is SENT here — see the note on this function about why a tool
+        // name is not something Telegram should ever receive. The call is
+        // recorded on `tool_result`, which has the result as well as the args.
+        //
+        // The typing indicator is what the owner sees instead, and every caller
+        // that runs a turn already holds it open on a 4s timer (_startTyping).
+        // This extra ping is belt-and-braces: it costs one best-effort
+        // sendChatAction and guarantees the indicator is fresh at the moment a
+        // slow tool begins, whatever the caller did.
+        await self._typing?.(chat_id);
       } else if (ev.type === "tool_result" && ev.trace) {
         // Logged for the audit trail / other channels — NOT sent to Telegram.
         const tr = ev.trace;
@@ -86,6 +121,22 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
           body: `${tr.tool}(${JSON.stringify(tr.args || {}).slice(0, 200)})`,
           meta: { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, tool: tr.tool, args: tr.args, result: tr.result, iteration: ev.iteration, ...(state.model ? { model: state.model } : {}) },
         });
+      } else if (ev.type === "judge_verdict") {
+        // Why a turn kept going after it looked done. Logged, never sent: the
+        // continuation shows up as the work itself, not as a status report.
+        self.log(
+          `telegram[${self.channel.name}] judge round ${ev.iteration}: ` +
+          `${Math.round((ev.score ?? 0) * 100)}% ${ev.passed ? "→ done" : "→ continuing"}` +
+          `${ev.reasoning ? ` (${ev.reasoning})` : ""}`
+        );
+      } else if (ev.type === "judge_budget_exhausted") {
+        // The judge wanted another round and the turn had no budget left to
+        // give it. Logged because the alternative reading — "the judge passed
+        // it" — is wrong, and the trail alone doesn't distinguish the two.
+        self.log(
+          `telegram[${self.channel.name}] judge round ${ev.iteration} skipped: ` +
+          `tool budget spent (${ev.spent}/${ev.budget})`
+        );
       } else if (ev.type === "engine_failed") {
         // A model in the fallback chain errored; the loop is rotating to the
         // next one. Log so a mid-turn provider failure is diagnosable.
@@ -132,13 +183,20 @@ export function runTelegramSuperAgent(self, {
     relationshipBlock,
     allowedTools,
     contextNote: contextNote || undefined,
-    channelMeta: buildTelegramMeta({
-      channelName: self.channel.name,
-      author,
-      chatId: chat_id,
-      target,
-      routeToAgent: self.channel.route_to_agent,
-    }),
+    channelMeta: {
+      ...buildTelegramMeta({
+        channelName: self.channel.name,
+        author,
+        chatId: chat_id,
+        target,
+        routeToAgent: self.channel.route_to_agent,
+      }),
+      // Driving flips this turn into voice mode, which is what actually makes
+      // the reply short (prompts/modes/voice.md + mobility.md). Doing it here
+      // rather than at send time is the whole point: you cannot shorten a
+      // paragraph after the model has written it, you can only truncate it.
+      ...(mobilityVoiceActive(self.globalConfig) ? { voice: true, mobility: true } : {}),
+    },
     signal,
     onEvent,
     requestConfirmation: confirmAdapter.requestConfirmation,
@@ -226,6 +284,7 @@ export async function runFollowupTurn(self, {
       saTrace,
       streamedCount: state.streamedCount,
       lastStreamedText: state.lastStreamedText,
+      heldCount: state.heldCount,
       agentDisplay,
       extraMeta: { a2a_relay: true },
     });
@@ -244,16 +303,21 @@ export function telegramErrorText(self, e) {
 }
 
 /**
- * Send the final reply for a turn and log it. The intermediate prose was already
- * streamed, so we only send `replyText` if it's non-empty AND not a duplicate of
- * the last streamed piece. Never ends on silence: a turn that streamed/acted but
- * produced no closing gets a neutral "continue?"; a pure chit-chat turn that did
- * nothing gets a short ack. Caller stops the typing indicator before calling.
+ * Send the final reply for a turn and log it. The opening notice was already
+ * sent, so we only send `replyText` if it's non-empty AND not a duplicate of
+ * the last piece that went out. This is the message the whole turn is for: with
+ * mid-turn notes held back, it's the only place the result can arrive — hence
+ * the never-silent floor. When the closing comes back empty the model is asked
+ * to write it from what the turn did (closing-floor.js), and only if THAT is
+ * empty too — usually because the engine is down, which is why the turn is
+ * empty in the first place — does the canned line go out. Never silent beats
+ * never canned, in that order.
+ * Caller stops the typing indicator before calling.
  */
 export async function sendFinalReply(self, {
   chat_id, update_id, replyText, replyAuthor, replyActorId, replyKind,
   saUsage = null, saModel = null, saTrace = null, streamedCount = 0, lastStreamedText = "",
-  agentDisplay, extraMeta = {},
+  heldCount = 0, agentDisplay, extraMeta = {}, authorLineFn = authorLine,
 }) {
   // A model that dumps raw planning must never have it forwarded. When that
   // happens the answer comes back empty and the existing never-silent fallback
@@ -268,22 +332,62 @@ export async function sendFinalReply(self, {
       `chain-of-thought is not usable on a user-facing channel.`
     );
   }
+  const toolSummary = summarizeToolTrace(saTrace);
   let toSend = "";
   if (finalClean && finalClean !== lastStreamedText) {
     toSend = finalClean;
   } else if (!finalClean) {
-    const lang = resolveLang(self.globalConfig);
-    toSend = streamedCount === 0
-      ? t("telegram.fallback_listo", { lang })
-      : t("telegram.fallback_continue", { lang });
+    // The shared floor (core/agent/closing-floor.js): one cheap tool-free call
+    // for a closing the model words itself, and the canned line only if that
+    // comes back empty too. `worked` is either half: prose the owner already
+    // read (streamedCount), or tools that ran without a word going out with
+    // them (toolSummary) — a silent turn that did real work still closes by
+    // saying where it got to, not with a bare acknowledgement.
+    const { text, authored } = await closingFloorLine({
+      globalConfig: self.globalConfig,
+      worked: streamedCount > 0 || Boolean(toolSummary),
+      lastText: lastStreamedText,
+      toolSummary,
+      authorLineFn,
+    });
+    toSend = text;
+    if (!authored) self.log(`telegram[${self.channel.name}] closing floor: the model could not write it either`);
   }
   if (!toSend) return; // everything was already streamed — nothing left to send
 
   const actorId = replyActorId || SUPERAGENT_ACTOR_ID;
   const kind = replyKind || "superagent";
   try {
-    await self._send({ chat_id, text: toSend });
+    // Driving: the answer goes out spoken first, then as its own transcript.
+    // A failed voice attempt falls through to the plain send below — the
+    // upgrade is allowed to fail, the message is not.
+    const spoken = mobilityVoiceActive(self.globalConfig)
+      ? await deliverVoiceReply({
+          io: {
+            send: (args) => self._send(args),
+            sendVoice: (args) => self._sendVoice(args),
+          },
+          chat_id,
+          text: toSend,
+          globalConfig: self.globalConfig,
+          log: (line) => self.log(`telegram[${self.channel.name}] ${line}`),
+        })
+      : { voice: false, reason: "not-driving" };
+    if (!spoken.voice) {
+      if (spoken.reason !== "not-driving") {
+        self.log(`telegram[${self.channel.name}] voice reply unavailable (${spoken.reason}) — sending text`);
+      }
+      await self._send({ chat_id, text: toSend });
+    }
     const meta = { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, final: true, ...extraMeta };
+    if (spoken.voice) {
+      // The row keeps the WORDS as its body (that is what search and the next
+      // turn's history need) and names the audio in meta, so the thread can
+      // play back exactly what the owner heard.
+      meta.voice_note = true;
+      meta.tts_provider = spoken.provider;
+      Object.assign(meta, spoken.media || {});
+    }
     if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
     if (stripped.leaked) meta.reasoning_leak_suppressed = true;
     if (saUsage) meta.usage = saUsage;
@@ -292,8 +396,12 @@ export async function sendFinalReply(self, {
     // and would bloat the day-file for a detail nobody reads back. What is
     // worth recovering later is "it read three files and sent a message", and
     // whether any of it failed.
-    const toolSummary = summarizeToolTrace(saTrace);
     if (toolSummary) meta.tool_summary = toolSummary;
+    // How many progress notes the gate held back. The ledger stays a record of
+    // what the user RECEIVED; this number is how you tell, after the fact, that
+    // a quiet turn was quiet on purpose.
+    if (heldCount > 0) meta.progress_held = heldCount;
+    // attribution: model+usage were stamped on `meta` above (saModel/saUsage) — the final row the user received.
     appendGlobalMessage({
       channel: CHANNELS.TELEGRAM,
       direction: "out",