switchroom 0.13.14 → 0.13.16

package/dist/cli/switchroom.js

@@ -47331,8 +47331,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.14";
-var COMMIT_SHA = "0cf961a6";
+var VERSION = "0.13.16";
+var COMMIT_SHA = "6c71b36b";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.14",
+  "version": "0.13.16",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -48154,10 +48154,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.14";
-var COMMIT_SHA = "0cf961a6";
-var COMMIT_DATE = "2026-05-23T01:15:10Z";
-var LATEST_PR = 1670;
+var VERSION = "0.13.16";
+var COMMIT_SHA = "6c71b36b";
+var COMMIT_DATE = "2026-05-23T03:56:34Z";
+var LATEST_PR = 1675;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -49857,6 +49857,7 @@ var STREAM_THROTTLE_MS_OVERRIDE = (() => {
   return Number.isFinite(n) && n >= 0 ? n : undefined;
 })();
 var TURN_FLUSH_SAFETY_ENABLED = isTurnFlushSafetyEnabled();
+var ANSWER_STREAM_VISIBLE_ENABLED = process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === "1" || process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === "true";
 var progressDriver = null;
 var unpinProgressCardForChat = null;
 var getPinnedProgressCardMessageId = null;
@@ -50616,7 +50617,19 @@ async function executeReply(args) {
   const configParseMode = access.parseMode ?? "html";
   const format = args.format ?? configParseMode;
   const disableLinkPreview = args.disable_web_page_preview != null ? Boolean(args.disable_web_page_preview) : access.disableLinkPreview ?? true;
-  const disableNotification = args.disable_notification === true;
+  let disableNotification = args.disable_notification === true;
+  {
+    const turn2 = currentTurn;
+    if (turn2 != null && !disableNotification) {
+      if (turn2.firstPingAt != null) {
+        process.stderr.write(`telegram gateway: reply over-ping safety net \u2014 ` + `downgrading disable_notification:false \u2192 true ` + `(chat=${chat_id} thread=${args.message_thread_id ?? "-"} firstPingAt=${turn2.firstPingAt} sinceFirstPing_ms=${Date.now() - turn2.firstPingAt})
+`);
+        disableNotification = true;
+      } else {
+        turn2.firstPingAt = Date.now();
+      }
+    }
+  }
   const tg = access.telegraph;
   const tgThreshold = tg?.threshold ?? 3000;
   if (tg?.enabled && files.length === 0 && text.length > tgThreshold) {
@@ -51765,6 +51778,7 @@ function handleSessionEvent(ev) {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           finalAnswerDelivered: false,
+          firstPingAt: null,
           capturedText: [],
           orphanedReplyTimeoutId: null,
           registryKey: null,
@@ -51854,7 +51868,7 @@ function handleSessionEvent(ev) {
             chatId: turn.sessionChatId,
             isPrivateChat: turn.isDm,
             threadId: turn.sessionThreadId,
-            sendMessageDraft: sendMessageDraftFn,
+            ...ANSWER_STREAM_VISIBLE_ENABLED ? { minInitialChars: 1 } : { sendMessageDraft: sendMessageDraftFn },
             sendMessage: async (chatId, text, params) => {
               const tid = params?.message_thread_id;
               const msg = await robustApiCall(() => bot.api.sendMessage(chatId, text, {
@@ -51976,20 +51990,45 @@ function handleSessionEvent(ev) {
         turn.orphanedReplyTimeoutId = null;
       }
       preambleSuppressor.flushNow();
+      let streamFinalizedAsAnswer = false;
       if (turn?.answerStream != null) {
         const stream = turn.answerStream;
-        turn.answerStream = null;
-        stream.retract().catch((err) => {
-          process.stderr.write(`telegram gateway: answer-stream retract failed: ${err instanceof Error ? err.message : String(err)}
+        const streamedMsgId = stream.messageId();
+        const streamedFinalText = turn.capturedText.join("").trim();
+        if (ANSWER_STREAM_VISIBLE_ENABLED && !turn.replyCalled && streamedMsgId != null && streamedFinalText.length > 0) {
+          turn.answerStream = null;
+          stream.stop();
+          streamFinalizedAsAnswer = true;
+          turn.finalAnswerDelivered = true;
+          try {
+            outboundDedup.record(turn.sessionChatId, turn.sessionThreadId, streamedFinalText, Date.now());
+          } catch {}
+          if (HISTORY_ENABLED) {
+            try {
+              recordOutbound({
+                chat_id: turn.sessionChatId,
+                thread_id: turn.sessionThreadId ?? null,
+                message_ids: [streamedMsgId],
+                texts: [streamedFinalText]
+              });
+            } catch {}
+          }
+          process.stderr.write(`telegram gateway: answer-stream finalized as answer chat=${turn.sessionChatId} msg=${streamedMsgId} chars=${streamedFinalText.length}
 `);
-        });
+        } else {
+          turn.answerStream = null;
+          stream.retract().catch((err) => {
+            process.stderr.write(`telegram gateway: answer-stream retract failed: ${err instanceof Error ? err.message : String(err)}
+`);
+          });
+        }
       }
       if (turn == null)
         return;
       const chatId = turn.sessionChatId;
       const threadId = turn.sessionThreadId;
       const ctrl = activeStatusReactions.get(statusKey(chatId, threadId));
-      const flushDecision = decideTurnFlush({
+      const flushDecision = streamFinalizedAsAnswer ? { kind: "skip", reason: "reply-called" } : decideTurnFlush({
         chatId: turn.sessionChatId,
         replyCalled: turn.replyCalled,
         capturedText: turn.capturedText,

package/telegram-plugin/gateway/gateway.ts

@@ -1206,6 +1206,17 @@ type CurrentTurn = {
   // even though `replyCalled` is true — the #1664 case where the real answer
   // ended up as plain transcript text rendered into an ephemeral draft.
   finalAnswerDelivered: boolean
+  // #1675 (over-ping safety net): wall-clock ms of the first reply
+  // this turn that landed with `disable_notification: false` (a real
+  // device ping). The conversational-pacing contract
+  // (`reference/conversational-pacing.md` beat 5) says EXACTLY ONE
+  // ping per turn — the final answer. When the model violates that
+  // (sends a substantive answer pinged + a wrap-up "Delivered…" or
+  // meta-narration also pinged), subsequent reply calls with
+  // `disable_notification: false` are auto-downgraded to silent by
+  // the framework. Null until the first ping lands. Reset on every
+  // fresh-turn enqueue.
+  firstPingAt: number | null
   capturedText: string[]
   orphanedReplyTimeoutId: ReturnType<typeof setTimeout> | null
   registryKey: string | null
@@ -2855,6 +2866,42 @@ const STREAM_THROTTLE_MS_OVERRIDE: number | undefined = (() => {
   return Number.isFinite(n) && n >= 0 ? n : undefined
 })()
 const TURN_FLUSH_SAFETY_ENABLED = isTurnFlushSafetyEnabled()
+
+// #869-Phase1 / openclaw-pattern. When SET, the answer-lane stream
+// (telegram-plugin/answer-stream.ts) renders the model's transcript
+// text as a USER-VISIBLE edit-in-place message instead of writing to
+// Telegram's invisible compose-box draft (which is the default and
+// supports the #1664 "retract + re-prompt" contract). With this flag
+// on:
+//   1. createAnswerStream is instantiated without `sendMessageDraft`,
+//      so it falls back to `sendMessage` + `editMessageText` for a
+//      real chat-timeline message (`answer-stream.ts:212-214`).
+//   2. minInitialChars is set to 1 — the first text chunk pushes a
+//      visible message immediately (TTFO under 5s for short turns).
+//   3. At turn_end, if the model never called reply / stream_reply
+//      AND the streamed message has substantive captured text, the
+//      gateway DOES NOT retract (which would delete a user-visible
+//      message the user has been reading live); it calls
+//      `stream.stop()` to freeze the current text as the final
+//      answer, records the message in dedup + history, and marks
+//      `turn.finalAnswerDelivered = true` so the #1664 silent-end
+//      re-prompt does not fire. Turn-flush is suppressed for this
+//      branch — its job (deliver captured text) is structurally
+//      already done by the visible stream.
+//   4. The reply-tool / stream_reply path is unchanged — when the
+//      model uses an explicit reply tool the prior streamed message
+//      is retracted (delete) and the reply takes over as before.
+// Trade-off: a stream-as-final-answer turn does NOT push a device
+// notification (Telegram does not notify on edits, and we choose
+// not to send a duplicate fresh message for the ping). For short
+// turns where the user is actively watching, this is the right
+// shape — they see the answer materialise live. For longer waits,
+// the cross-turn pending-progress system (#1445/#1669) is the
+// canonical surface and DOES ping at the appropriate boundaries.
+// Default OFF; flip per-agent via env to canary the new behaviour.
+const ANSWER_STREAM_VISIBLE_ENABLED =
+  process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === '1'
+  || process.env.SWITCHROOM_VISIBLE_ANSWER_STREAM === 'true'
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const progressDriver: any = null
 const unpinProgressCardForChat: ((chatId: string, threadId: number | undefined) => void) | null = null
@@ -4172,7 +4219,43 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // so only the final answer pings the device. Default false (pings) so
   // existing call-sites and the typical "final answer" reply keep their
   // current behaviour without an explicit flag.
-  const disableNotification = args.disable_notification === true
+  let disableNotification = args.disable_notification === true
+
+  // #1675 over-ping safety net. The conversational-pacing contract
+  // (`reference/conversational-pacing.md` beat 5) says EXACTLY ONE
+  // device ping per turn — the final answer. The model sometimes
+  // violates this by sending a substantive answer pinged + a wrap-up
+  // ("Delivered all three steps…", "Sent.", or meta-narration) ALSO
+  // pinged. Both messages then fire notifications. The fleet UAT on
+  // 2026-05-23 reproduced this (Step 3 + Delivered both pinged, two
+  // beeps for a turn that should have produced one). Framework owns
+  // the safety net: once the turn has emitted ONE pinged reply, every
+  // subsequent reply call in the same turn auto-downgrades to silent
+  // (disable_notification: true). Model intent ("I want this loud")
+  // is honoured for the first ping; subsequent pings are demoted with
+  // a stderr log so operators can see the safety net engage.
+  //
+  // The slot is claimed BEFORE the actual send to keep the logic
+  // sequential — a send that fails part-way leaves firstPingAt set
+  // and subsequent pings would be silenced. Acceptable trade-off (a
+  // failed first ping is an edge case; the alternative — claim after
+  // send — races concurrent reply calls).
+  {
+    const turn = currentTurn
+    if (turn != null && !disableNotification) {
+      if (turn.firstPingAt != null) {
+        process.stderr.write(
+          `telegram gateway: reply over-ping safety net — ` +
+          `downgrading disable_notification:false → true ` +
+          `(chat=${chat_id} thread=${args.message_thread_id ?? '-'} ` +
+          `firstPingAt=${turn.firstPingAt} sinceFirstPing_ms=${Date.now() - turn.firstPingAt})\n`,
+        )
+        disableNotification = true
+      } else {
+        turn.firstPingAt = Date.now()
+      }
+    }
+  }
 
   // Telegraph publish (#579). When the reply text is long enough AND
   // the agent has telegraph enabled in access.json, publish to
@@ -5841,6 +5924,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           finalAnswerDelivered: false,
+          firstPingAt: null,
           capturedText: [],
           orphanedReplyTimeoutId: null,
           registryKey: null,
@@ -5986,7 +6070,13 @@ function handleSessionEvent(ev: SessionEvent): void {
             chatId: turn.sessionChatId,
             isPrivateChat: turn.isDm,
             threadId: turn.sessionThreadId,
-            sendMessageDraft: sendMessageDraftFn,
+            // #869-Phase1 visible-answer-stream: omit the draft API so
+            // the lane uses the real sendMessage / editMessageText path
+            // and edits a user-visible chat-timeline message instead
+            // of the invisible compose-box draft.
+            ...(ANSWER_STREAM_VISIBLE_ENABLED
+              ? { minInitialChars: 1 }
+              : { sendMessageDraft: sendMessageDraftFn }),
             // #1075: route through robustApiCall so flood-wait,
             // benign-400, and THREAD_NOT_FOUND are handled uniformly
             // instead of crashing the answer-stream loop on a deleted
@@ -6189,20 +6279,71 @@ function handleSessionEvent(ev: SessionEvent): void {
       // (regression for short no-tool replies). Order matters here: this
       // call must come before the retract/null block.
       preambleSuppressor.flushNow()
-      // #656: always retract the answer-lane stream at turn_end. Turn-flush
-      // (gateway.ts ~3475) is the sole canonical emitter for no-reply turns —
-      // it runs markdownToHtml and records to outboundDedup. Materializing
-      // here would race turn-flush and post raw model text (no HTML conv).
+      // #656: by default we ALWAYS retract the answer-lane stream at
+      // turn_end. Turn-flush is the canonical emitter for no-reply
+      // turns; materialising here would race it and post raw model
+      // text (no HTML conv).
+      //
+      // #869-Phase1 override: when `ANSWER_STREAM_VISIBLE_ENABLED` is
+      // on, the stream is rendering a USER-VISIBLE message in the
+      // chat timeline. Retracting (delete) destroys content the user
+      // has been reading live — the worst possible UX flicker. So
+      // when the stream is the de-facto final answer (model never
+      // called reply, captured text is substantive) we instead call
+      // `stream.stop()` to freeze it as the final state, record the
+      // outbound for history + dedup, mark the turn answered, and
+      // suppress the turn-flush IIFE downstream.
+      let streamFinalizedAsAnswer = false
       if (turn?.answerStream != null) {
         const stream = turn.answerStream
-        turn.answerStream = null
-        void stream.retract().catch((err) => {
+        const streamedMsgId = stream.messageId()
+        const streamedFinalText = turn.capturedText.join('').trim()
+        if (
+          ANSWER_STREAM_VISIBLE_ENABLED
+          && !turn.replyCalled
+          && streamedMsgId != null
+          && streamedFinalText.length > 0
+        ) {
+          turn.answerStream = null
+          stream.stop()
+          streamFinalizedAsAnswer = true
+          turn.finalAnswerDelivered = true
+          // Record as canonical outbound so retries dedup against it
+          // and the SQLite history can surface it. Mirrors the
+          // hooks turn-flush + reply both run.
+          try {
+            outboundDedup.record(
+              turn.sessionChatId,
+              turn.sessionThreadId,
+              streamedFinalText,
+              Date.now(),
+            )
+          } catch { /* best-effort */ }
+          if (HISTORY_ENABLED) {
+            try {
+              recordOutbound({
+                chat_id: turn.sessionChatId,
+                thread_id: turn.sessionThreadId ?? null,
+                message_ids: [streamedMsgId],
+                texts: [streamedFinalText],
+              })
+            } catch { /* best-effort */ }
+          }
           process.stderr.write(
-            `telegram gateway: answer-stream retract failed: ${
-              err instanceof Error ? err.message : String(err)
-            }\n`,
+            `telegram gateway: answer-stream finalized as answer ` +
+            `chat=${turn.sessionChatId} msg=${streamedMsgId} ` +
+            `chars=${streamedFinalText.length}\n`,
           )
-        })
+        } else {
+          turn.answerStream = null
+          void stream.retract().catch((err) => {
+            process.stderr.write(
+              `telegram gateway: answer-stream retract failed: ${
+                err instanceof Error ? err.message : String(err)
+              }\n`,
+            )
+          })
+        }
       }
       if (turn == null) return
       const chatId = turn.sessionChatId
@@ -6214,12 +6355,19 @@ function handleSessionEvent(ev: SessionEvent): void {
       // surface to recover from. The decideTurnFlush 'empty-text'
       // path now relies on capturedText alone.
 
-      const flushDecision = decideTurnFlush({
-        chatId: turn.sessionChatId,
-        replyCalled: turn.replyCalled,
-        capturedText: turn.capturedText,
-        flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
-      })
+      // #869-Phase1: when the answer-stream finalised as the answer
+      // above, skip the turn-flush IIFE entirely — its job (deliver
+      // captured text) is already done by the visible stream, and
+      // running it would race a duplicate fresh-sendMessage against
+      // the user-visible edited message.
+      const flushDecision = streamFinalizedAsAnswer
+        ? ({ kind: 'skip', reason: 'reply-called' } as ReturnType<typeof decideTurnFlush>)
+        : decideTurnFlush({
+            chatId: turn.sessionChatId,
+            replyCalled: turn.replyCalled,
+            capturedText: turn.capturedText,
+            flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
+          })
       if (flushDecision.kind === 'skip' && flushDecision.reason !== 'reply-called') {
         process.stderr.write(
           `telegram gateway: turn-flush skipped — reason=${flushDecision.reason}\n`,

package/telegram-plugin/uat/scenarios/cross-turn-pending-progress-dm.test.ts

@@ -57,17 +57,19 @@ import type { ObservedMessage } from "../driver.js";
 
 const SLEEP_SECONDS = 350;
 
+// Engineered to elicit the natural production pattern: the model
+// sends a quick ack reply ("on it — background sleep running"),
+// dispatches the sleep as a background Bash, ends its turn, then
+// returns with "done" once the sleep completes. The framework
+// fix-under-test owns the in-between ambient.
 const PROMPT =
-  `This is an instrumented stress test of cross-turn pending-async ` +
-  `progress. Please run exactly this command via the Bash tool, and ` +
-  `ONLY this command, as a SINGLE call with run_in_background=true ` +
-  `(do not break it up, do not send any further reply until it ` +
-  `completes):\n\n` +
-  "```bash\n" +
-  `sleep ${SLEEP_SECONDS}\n` +
-  "```\n\n" +
-  `After the bash command returns, send exactly the single word ` +
-  `"done" as your final reply.`;
+  `Please run \`sleep ${SLEEP_SECONDS}\` in the background using the ` +
+  `Bash tool with \`run_in_background: true\` — this is a stress ` +
+  `test of the cross-turn ambient progress surface, so the sleep ` +
+  `duration matters. Send a brief one-line acknowledgement that ` +
+  `you've dispatched it (your natural beat-1 ack is fine), then ` +
+  `wait for it to complete. When it finishes, reply with exactly ` +
+  `the single word "done".`;
 
 const OVERALL_DEADLINE_MS = (SLEEP_SECONDS + 240) * 1000;
 

package/telegram-plugin/uat/scenarios/visible-answer-stream-dm.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Conversational pacing UAT — measures the END-TO-END user-perceived
+ * turn UX on a multi-step prompt.
+ *
+ * Original framing was "validate the visible-answer-stream path
+ * activates." Live research on test-harness with the
+ * `SWITCHROOM_VISIBLE_ANSWER_STREAM=1` flag showed that modern Claude
+ * 2.1.x on this fleet does NOT emit transcript text events between
+ * tool calls — it consistently calls the `reply` MCP tool directly
+ * for every user-visible chunk (beat 1 ack, then per-step beat 3
+ * updates). So the visible-answer-stream code path (which renders
+ * `text` session events into a chat-timeline message) doesn't
+ * activate; the answer-stream lane stays idle while the model uses
+ * `reply` calls instead.
+ *
+ * That's actually FINE — the model is correctly following the
+ * five-beat conversational-pacing contract (`reference/conversational-
+ * pacing.md`): one silent ack at the start, silent updates per step,
+ * one pinged final answer. This UAT now validates THAT — the pacing
+ * the user actually experiences — rather than the answer-stream code
+ * path specifically.
+ *
+ * The flag `SWITCHROOM_VISIBLE_ANSWER_STREAM=1` is still set on
+ * test-harness for ongoing observation; if a future model version
+ * starts emitting transcript text, the lane will surface it visibly
+ * instead of writing to the invisible compose-box draft (the prior
+ * default).
+ *
+ * ## What this asserts
+ *
+ *   1. First user-visible bot message lands within `TTFO_BUDGET_MS`
+ *      (default 15 s) of the inbound — covers beat 1 ack OR straight-
+ *      to-content depending on the model's pacing choice.
+ *   2. Multiple distinct bot messages land per turn for the multi-
+ *      step prompt — proving the model isn't collapsing everything
+ *      into a single pinged dump.
+ *   3. All but at most one message is silent (`disable_notification:
+ *      true`). Only the final answer should ping — anything earlier
+ *      pinging is a beat-3 contract violation.
+ *
+ * ## Wall-clock budget
+ *
+ * ~90 s.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+
+const TTFO_BUDGET_MS = 15_000;
+const OVERALL_DEADLINE_MS = 90_000;
+const QUIESCENCE_MS = 12_000;
+
+// Multi-step investigation prompt — designed to make the model emit
+// transcript text BETWEEN tool calls, which is the assistant-content
+// `text` block shape session-tail surfaces via the `text` event the
+// answer-stream lane consumes. With the visible-answer-stream flag
+// ON, those text events should become user-visible edit-in-place
+// chat-timeline updates.
+//
+// We choose a research-style task because that pattern reliably
+// emits `text` chunks (the model thinks out loud between Read /
+// Bash steps) on most Claude versions. A pure-answer prompt (the
+// previous version of this scenario) tended to make modern Claude
+// jump straight to a single `reply` tool-call with no intermediate
+// text — exercising the wrong path.
+const PROMPT =
+  `Investigate this step by step:\n\n` +
+  `1. Read \`/etc/hostname\` and tell me what host this is — write a ` +
+  `sentence about it.\n` +
+  `2. Then read \`/etc/os-release\` and tell me what OS family / version.\n` +
+  `3. Then read \`/proc/cpuinfo\` (head it), and tell me the CPU model + ` +
+  `core count.\n` +
+  `4. Wrap up with a one-line summary of all three.\n\n` +
+  `Between each step, narrate what you're finding in plain prose ` +
+  `(not just bullet outputs). Don't batch all your observations into ` +
+  `one final reply — talk as you investigate.`;
+
+interface TrailEntry {
+  relMs: number;
+  kind: "fresh" | "edit";
+  silent: boolean;
+  messageId: number;
+  textPreview: string;
+  textLength: number;
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+describe("uat: conversational pacing on a multi-step turn", () => {
+  it(
+    "first message lands within TTFO_BUDGET_MS; multiple silent messages; final answer pings",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const startedAt = Date.now();
+        await sc.sendDM(PROMPT);
+        console.log(`[visible-answer-stream] t=0 prompt sent`);
+
+        const trail: TrailEntry[] = [];
+        let firstAnchorMsgId: number | null = null;
+        let quiescenceDeadline = startedAt + 30_000;
+        const overallDeadline = startedAt + OVERALL_DEADLINE_MS;
+
+        while (Date.now() < overallDeadline) {
+          const remaining = Math.min(
+            quiescenceDeadline - Date.now(),
+            overallDeadline - Date.now(),
+          );
+          if (remaining <= 0) break;
+          try {
+            const msg = await sc.expectMessage(
+              (m: ObservedMessage) => m.fromBot,
+              { from: "bot", timeout: remaining },
+            );
+            const rel = Date.now() - startedAt;
+            const entry: TrailEntry = {
+              relMs: rel,
+              kind: msg.edited ? "edit" : "fresh",
+              silent: msg.silent,
+              messageId: msg.messageId,
+              textPreview: msg.text
+                .slice(0, 120)
+                .replace(/\n/g, " ⏎ "),
+              textLength: msg.text.length,
+            };
+            trail.push(entry);
+            if (firstAnchorMsgId == null && entry.kind === "fresh") {
+              firstAnchorMsgId = entry.messageId;
+            }
+            console.log(
+              `[visible-answer-stream] +${(rel / 1000).toFixed(1)}s ` +
+                `${entry.kind.toUpperCase()} msg=${entry.messageId} ` +
+                `silent=${entry.silent} len=${entry.textLength} ` +
+                `text=${JSON.stringify(entry.textPreview)}`,
+            );
+            quiescenceDeadline = Date.now() + QUIESCENCE_MS;
+          } catch {
+            break;
+          }
+        }
+
+        console.log("\n========== VISIBLE-ANSWER-STREAM TRAIL ==========");
+        console.log(`total bot messages observed: ${trail.length}`);
+        console.log(`first anchor messageId: ${firstAnchorMsgId}`);
+        console.log("");
+        console.log("  rel(s)   kind   silent  msg          len   text");
+        console.log("  -------  -----  ------  -----------  ----  ----");
+        for (const e of trail) {
+          console.log(
+            `  ${pad((e.relMs / 1000).toFixed(1) + "s", 8)} ` +
+              `${pad(e.kind, 6)} ${pad(String(e.silent), 7)} ` +
+              `${pad(String(e.messageId), 12)} ${pad(String(e.textLength), 5)} ` +
+              `${e.textPreview}`,
+          );
+        }
+        console.log("=================================================\n");
+
+        // ── Pacing assertions ─────────────────────────────────────
+
+        // (1) at least one bot message landed
+        expect(
+          trail.length,
+          `no bot replies observed — the agent isn't responding.`,
+        ).toBeGreaterThanOrEqual(1);
+
+        // (2) first message landed within TTFO budget
+        const ttfoMs = trail[0].relMs;
+        expect(
+          ttfoMs,
+          `TTFO ${ttfoMs}ms exceeded the budget of ${TTFO_BUDGET_MS}ms.`,
+        ).toBeLessThanOrEqual(TTFO_BUDGET_MS);
+
+        // (3) multiple messages landed — proves the model is pacing,
+        // not dumping a single big reply
+        expect(
+          trail.length,
+          `only ${trail.length} message(s) observed — the model ` +
+            `collapsed this multi-step prompt into a single dump. ` +
+            `Beat 3 pacing (per-step updates) requires multiple ` +
+            `messages. Either the model didn't follow the prompt ` +
+            `or quiescence bailed early.`,
+        ).toBeGreaterThanOrEqual(2);
+
+        // (4) at most one message pinged the user — beat-3 contract
+        // says only the FINAL answer pings; mid-turn updates pass
+        // `disable_notification: true`.
+        const pingedMessages = trail.filter((e) => !e.silent);
+        expect(
+          pingedMessages.length,
+          `${pingedMessages.length} message(s) pinged the device — ` +
+            `the conversational-pacing contract allows AT MOST 1 ` +
+            `(the final answer). Mid-turn updates must be silent. ` +
+            `Pinged messages at: ${pingedMessages
+              .map((m) => `+${(m.relMs / 1000).toFixed(0)}s`)
+              .join(", ")}`,
+        ).toBeLessThanOrEqual(1);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_DEADLINE_MS + 30_000,
+  );
+});