switchroom 0.17.6 → 0.18.3

package/telegram-plugin/uat/scenarios/jtbd-liveness-narration-channel.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Narrated mid-turn work still shows words on the card — CHANNEL twin of
+ * `jtbd-liveness-narration-dm.test.ts` (Phase 4a, `deterministic-turn-liveness.md`).
+ *
+ * Surface parity bar per the job spec. Like the DM twin (and unlike the
+ * previous version of this file), it also asserts the no-mid-turn-ping
+ * invariant inline — the RFC and job spec claim the ping-free assertion is
+ * baked into EVERY liveness scenario, DM and channel alike. Self-skips green
+ * when no test supergroup is wired.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import { isActivityFeedMessage, isFrameworkFallbackText } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+const SUPERGROUP_ID = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID ?? "", 10);
+const OVERALL_BUDGET_MS = 150_000;
+
+const NARRATED_WORK_PROMPT =
+  "Do four short steps, ONE AT A TIME. Before EACH step, write a brief " +
+  'one-sentence narration of what you are about to do (e.g. "Checking the ' +
+  'hostname now.") — this is not a reply, just your normal narration — then ' +
+  "run the step via Bash (`sleep 3` is fine as the step body). After all " +
+  "four steps, send a one-line final summary reply.";
+
+/** Body (narration/tool) lines of a card, minus header + climb placeholder.
+ *  Mirrors the DM twin's `narratedBodyLines`. */
+function narratedBodyLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .map((l) => l.replace(/^[→✓↳]+\s*/u, "").trim())
+    .filter(
+      (l) =>
+        l.length > 0 &&
+        !/^(?:🤖|🛠[️]?|⚙[️]?)\s/u.test(l) &&
+        !/^(?:(?:\d+m)?\d+s\s*·\s*\d+\s+tools?|(?:done|failed)\s*·)/iu.test(l) &&
+        !/^Working(?:\s*[·…]|$)/i.test(l) &&
+        !/^\+?\d+\s+earlier/i.test(l),
+    );
+}
+
+describe("uat: deterministic turn liveness — narration lands mid-turn (channel parity)", () => {
+  it(
+    "the model's own words appear on the activity card mid-turn in a supergroup, with no mid-turn ping",
+    async () => {
+      if (!Number.isFinite(SUPERGROUP_ID)) {
+        console.warn("[liveness-narration-channel] SWITCHROOM_UAT_CHAT_ID unset — skipping");
+        return;
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        await sc.driver.primeDialogs();
+        if (!(await sc.driver.canResolve(SUPERGROUP_ID))) {
+          console.warn(`[liveness-narration-channel] supergroup ${SUPERGROUP_ID} not resolvable — skipping`);
+          return;
+        }
+
+        const iter = sc.driver
+          .observeMessages(SUPERGROUP_ID)
+          [Symbol.asyncIterator]();
+
+        await sc.driver.sendText(SUPERGROUP_ID, NARRATED_WORK_PROMPT);
+        const sentAt = Date.now();
+
+        const narrationSamples: string[] = [];
+        let answer: ObservedMessage | null = null;
+        let otherLoudMessage: ObservedMessage | null = null;
+
+        const deadline = Date.now() + 100_000;
+        while (Date.now() < deadline) {
+          if (answer) break;
+          const remaining = deadline - Date.now();
+          const next = await Promise.race([
+            iter.next(),
+            new Promise<{ done: true; value: undefined }>((r) =>
+              setTimeout(() => r({ done: true, value: undefined }), Math.max(0, remaining)),
+            ),
+          ]);
+          if (next.done || next.value == null) break;
+          const m = next.value as ObservedMessage;
+          if (m.senderUserId === sc.driverUserId) continue;
+
+          if (isActivityFeedMessage(m)) {
+            const narrated = narratedBodyLines(m.text);
+            if (narrated.length > 0) {
+              narrationSamples.push(narrated.join(" | "));
+              console.log(
+                `[liveness-narration-channel] narrated card content at +${Date.now() - sentAt}ms: ` +
+                  JSON.stringify(narrated.join(" | ").slice(0, 140)),
+              );
+            }
+            if (m.edited && m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (m.edited) continue;
+          if (isFrameworkFallbackText(m.text)) {
+            otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (!answer && m.text.trim().length > 0) {
+            answer = m;
+            continue;
+          }
+          if (m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+        }
+        await iter.return?.();
+
+        // No-mid-turn-ping invariant, inline in the channel twin too.
+        expect(
+          otherLoudMessage,
+          `a mid-turn message eroded the ping-free/edit-only guarantee in the supergroup: ` +
+            JSON.stringify(otherLoudMessage?.text?.slice(0, 120)),
+        ).toBeNull();
+
+        if (narrationSamples.length === 0) {
+          console.warn(
+            "[liveness-narration-channel] INCONCLUSIVE — no narrated content observed on the " +
+              "card (model may have batched steps or the turn was too fast).",
+          );
+        }
+
+        expect(
+          answer,
+          "FAIL — no answer (distinct from the activity card) arrived within budget; the turn may be wedged.",
+        ).not.toBeNull();
+        expect(answer?.chatId).toBe(SUPERGROUP_ID);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_BUDGET_MS,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-liveness-narration-dm.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Narrated mid-turn work still shows words on the card (Phase 4a,
+ * `deterministic-turn-liveness.md`) — DM.
+ *
+ * The Phase-1 climb fills the GAPS the model leaves; it must never regress
+ * the pre-existing narration path (session-tail → gateway `case 'text'` →
+ * `stagePendingNarrative` → `showNarrativeStep` → `appendActivityLabel`).
+ * This scenario proves the model's own narrated steps still land on the
+ * card mid-turn, chronologically interleaved with the climb, when the model
+ * DOES talk (the complement of `jtbd-liveness-climb-dm`, which forces the
+ * model silent).
+ *
+ * IMPORTANT: switchroom has no streaming REPLY path. The words asserted here
+ * land on the pre-existing activity/liveness card (a card-edit surface), not
+ * a streamed reply — the final reply is still sent whole.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import { isActivityFeedMessage, isFrameworkFallbackText } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+/**
+ * Extract the narration/tool body lines of an activity card, dropping the
+ * two-line header (`🤖 Agent` / `<elapsed> · <N> tools`) and the bare
+ * `Working…` placeholder the 0-label climb paints. Whatever remains is
+ * model-authored narration or tool labels — the content this scenario proves
+ * still lands on the card mid-turn.
+ */
+function narratedBodyLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    // strip glyphs so a `→ Working…` placeholder compares as `Working…`
+    .map((l) => l.replace(/^[→✓↳]+\s*/u, "").trim())
+    .filter(
+      (l) =>
+        l.length > 0 &&
+        // header line 1 (emoji + label, optional description)
+        !/^(?:🤖|🛠[️]?|⚙[️]?)\s/u.test(l) &&
+        // header line 2 (elapsed · tools, running or done)
+        !/^(?:(?:\d+m)?\d+s\s*·\s*\d+\s+tools?|(?:done|failed)\s*·)/iu.test(l) &&
+        // the bare climb placeholder is NOT narration
+        !/^Working(?:\s*[·…]|$)/i.test(l) &&
+        // rolling-overflow header is not narration
+        !/^\+?\d+\s+earlier/i.test(l),
+    );
+}
+
+const OVERALL_BUDGET_MS = 130_000;
+
+const NARRATED_WORK_PROMPT =
+  "Do four short steps, ONE AT A TIME. Before EACH step, write a brief " +
+  'one-sentence narration of what you are about to do (e.g. "Checking the ' +
+  'hostname now.") — this is not a reply, just your normal narration — then ' +
+  "run the step via Bash (`sleep 3` is fine as the step body). After all " +
+  "four steps, send a one-line final summary reply.";
+
+describe("uat: deterministic turn liveness — narration lands mid-turn (DM)", () => {
+  it(
+    "the model's own words appear on the activity card mid-turn (narration not regressed)",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const iter = sc.driver
+          .observeMessages(sc.botUserId)
+          [Symbol.asyncIterator]();
+
+        await sc.sendDM(NARRATED_WORK_PROMPT);
+        const sentAt = Date.now();
+        console.log("[liveness-narration-dm] prompt sent; watching for narrated card content…");
+
+        const narrationSamples: string[] = [];
+        let answer: ObservedMessage | null = null;
+        let otherLoudMessage: ObservedMessage | null = null;
+
+        const deadline = Date.now() + 90_000;
+        while (Date.now() < deadline) {
+          if (answer) break;
+          const remaining = deadline - Date.now();
+          const next = await Promise.race([
+            iter.next(),
+            new Promise<{ done: true; value: undefined }>((r) =>
+              setTimeout(() => r({ done: true, value: undefined }), Math.max(0, remaining)),
+            ),
+          ]);
+          if (next.done || next.value == null) break;
+          const m = next.value as ObservedMessage;
+          if (m.senderUserId === sc.driverUserId) continue;
+
+          if (isActivityFeedMessage(m)) {
+            // The card carries the two-line header + (climb placeholder |
+            // narrated body). Any body line that ISN'T the header or the bare
+            // "Working…" placeholder is model narration landing mid-turn.
+            const narrated = narratedBodyLines(m.text);
+            if (narrated.length > 0) {
+              narrationSamples.push(narrated.join(" | "));
+              console.log(
+                `[liveness-narration-dm] narrated card content at +${Date.now() - sentAt}ms: ` +
+                  JSON.stringify(narrated.join(" | ").slice(0, 140)),
+              );
+            }
+            if (m.edited && m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (m.edited) continue;
+          // A framework fallback TEXT send is a mid-turn erosion, not the
+          // answer — reject it from the answer lane so it trips the assertion.
+          if (isFrameworkFallbackText(m.text)) {
+            otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (!answer && m.text.trim().length > 0) {
+            answer = m;
+            continue;
+          }
+          if (m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+        }
+        await iter.return?.();
+
+        expect(
+          otherLoudMessage,
+          `a mid-turn message pinged the user's device: ${JSON.stringify(otherLoudMessage?.text?.slice(0, 120))}`,
+        ).toBeNull();
+
+        if (narrationSamples.length === 0) {
+          console.warn(
+            "[liveness-narration-dm] INCONCLUSIVE — no narrated content observed on the " +
+              "card (model may have batched steps or the turn was too fast). Not " +
+              "necessarily a regression — but worth a human look if this recurs.",
+          );
+        }
+        // (No tautological `expect(narrationSamples.length).toBeGreaterThan(0)`
+        //  in the else-branch — it was asserting a condition the branch already
+        //  guarantees. The meaningful signals are the ping-free assertion above
+        //  and the answer-arrived assertion below; narration presence is
+        //  logged, not force-asserted, since a live model may legitimately
+        //  batch its steps.)
+
+        expect(answer, "FAIL — no answer arrived within budget; the turn may be wedged.").not.toBeNull();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_BUDGET_MS,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-memory-legibility-channel.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Sparse chat-legible memory in a SUPERGROUP (#2849, hindsight Phase 4) — UAT.
+ *
+ * Channel twin of `jtbd-memory-legibility-dm`. A directive stored while the
+ * conversation is happening in a supergroup must surface its `📌 remembered:`
+ * line IN the supergroup — never the operator DM (the known status-routing
+ * bug class). Proves the memory-legibility status surface has DM/channel
+ * parity: it routes on the ORIGINATING topic (`turn.sessionChatId` /
+ * `sessionThreadId`), not the owner DM.
+ *
+ * Self-skips green when no test supergroup is wired (SWITCHROOM_UAT_CHAT_ID
+ * unset or not resolvable). Uses the General topic (mtcute here has no
+ * forum-topic create API).
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import { expectMessage } from "../assertions.js";
+
+const AGENT = "test-harness";
+const SUPERGROUP_ID = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID ?? "", 10);
+
+const REMEMBER_PROMPT =
+  `Persist this as a standing directive using the ` +
+  `mcp__hindsight__create_directive tool, with the directive content set ` +
+  `to exactly: "Always greet me as Captain at the start of a reply". ` +
+  `Name the directive "greeting-captain". After creating it, send a brief ` +
+  `one-line confirmation.`;
+
+const REMEMBERED_RE = /📌\s*remembered/i;
+
+describe("uat: sparse chat-legible memory in a supergroup (#2849 channel parity)", () => {
+  it(
+    "surfaces the 📌 remembered line IN the supergroup, not the DM",
+    async () => {
+      if (!Number.isFinite(SUPERGROUP_ID)) {
+        console.warn("[memory-legibility channel UAT] SWITCHROOM_UAT_CHAT_ID unset — skipping");
+        return;
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        await sc.driver.primeDialogs();
+        if (!(await sc.driver.canResolve(SUPERGROUP_ID))) {
+          console.warn(`[memory-legibility channel UAT] supergroup ${SUPERGROUP_ID} not resolvable — skipping`);
+          return;
+        }
+        await sc.driver.sendText(SUPERGROUP_ID, REMEMBER_PROMPT);
+
+        const line = await expectMessage(sc.driver, SUPERGROUP_ID, REMEMBERED_RE, {
+          timeout: 90_000,
+          senderFilter: { notUserId: sc.driverUserId },
+        });
+        console.log(
+          `[memory-legibility channel UAT] remembered line (id=${line.messageId}, chat=${line.chatId}): ${JSON.stringify(line.text)}`,
+        );
+        expect(line.chatId).toBe(SUPERGROUP_ID); // parity proof: in the channel, not the DM
+        expect(line.fromBot).toBe(true);
+        expect(line.messageId).toBeGreaterThan(0);
+        expect(line.text).toMatch(/Captain/i);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    180_000,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-memory-legibility-dm.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Sparse chat-legible memory (#2849, hindsight Phase 4) — DM UAT.
+ *
+ * Serves the `remember-across-sessions` job. When the interactive session
+ * stores a new standing directive, ONE terse line must surface in the
+ * originating chat: `📌 remembered: "<directive>"`. It's a REAL message
+ * (sendMessage, not a draft/reaction) so mtcute can observe it. The line
+ * is sparse + material-only — ordinary recall never surfaces one — and is
+ * ON by default (kill-switch SWITCHROOM_MEMORY_LEGIBILITY=0).
+ *
+ * This scenario asks the agent to persist an explicit standing rule via
+ * the create_directive tool, then asserts the 📌 remembered line appears
+ * from the bot in the DM.
+ *
+ * Note: the model must actually call `mcp__hindsight__create_directive`.
+ * The prompt names the tool + the rule verbatim to make the tool call
+ * deterministic. Requires the test-harness agent running an image that
+ * includes #2849.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const REMEMBER_PROMPT =
+  `Persist this as a standing directive using the ` +
+  `mcp__hindsight__create_directive tool, with the directive content set ` +
+  `to exactly: "Always greet me as Captain at the start of a reply". ` +
+  `Name the directive "greeting-captain". After creating it, send a brief ` +
+  `one-line confirmation.`;
+
+// The legibility line: `📌 remembered: "<directive body, truncated>"`.
+const REMEMBERED_RE = /📌\s*remembered/i;
+
+describe("uat: sparse chat-legible memory — remembered line (#2849)", () => {
+  it(
+    "surfaces a 📌 remembered line in the DM when a directive is created",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        await sc.sendDM(REMEMBER_PROMPT);
+
+        // The 📌 remembered line — a real bot message in this DM. May arrive
+        // alongside/near the agent's confirmation reply; generous budget for
+        // the tool round-trip + transcript flush.
+        const line = await sc.expectMessage(REMEMBERED_RE, {
+          from: "bot",
+          timeout: 90_000,
+        });
+        console.log(
+          `[memory-legibility UAT] remembered line (id=${line.messageId}): ${JSON.stringify(line.text)}`,
+        );
+        expect(line.messageId).toBeGreaterThan(0);
+        // The directive body should ride along in the line.
+        expect(line.text).toMatch(/Captain/i);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    180_000,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-rich-formatting-render-dm.test.ts

@@ -56,9 +56,20 @@
 import { describe, it, expect } from "vitest";
 import { spinUp } from "../harness.js";
 import type { ObservedMessage } from "../driver.js";
+import { richRenderEnabled } from "../../render/rich-render.js";
 
 const AGENT = "test-harness";
 
+// The rich-render wiring (parse -> IR -> renderSafe -> sendRichMessage) is
+// gated behind `SWITCHROOM_RICH_RENDER` (default OFF). The expandable /
+// collapsible round-trip proof below only runs when BOTH the driver creds AND
+// the flag are present — the flag must be set in the gateway process under
+// test for the renderer to actually shape the outbound message, so gating the
+// scenario on the same flag keeps it honest (no false green when the wiring
+// isn't live). When the flag is off, this scenario self-skips green exactly
+// like the credential-less case.
+const RICH_RENDER_ON = richRenderEnabled();
+
 // The driver session is the load-bearing credential. Absent it, spinUp()
 // throws in resolveConfig — so guard at describe level and self-skip green.
 const HAS_DRIVER_CREDS =
@@ -105,13 +116,18 @@ const SAMPLE_LINES = [
  * trip on the uat-host (PR #2745 first live run: present set was
  * `bold, italic, code, strikethrough, text_link, blockquote, pre`).
  *
- * `spoiler` is deliberately NOT hard-asserted: on the live wire the `||…||`
- * span did NOT surface as a `spoiler`/`textMarked` entity (the model either
- * dropped the syntax or Telegram's chat-message GFM parser doesn't map it the
- * way the IV table-of-contents `textMarked` node does). Rather than red the
- * whole render gate on a construct the round trip doesn't reliably produce, we
- * observe spoiler softly (logged below). The decoder's `textMarked → spoiler`
- * mapping is still pinned deterministically by the hosted unit suite.
+ * `spoiler` is soft-observed HERE only because of THIS harness's decode path:
+ * the `||…||` span did NOT reliably surface as a `spoiler`/`textMarked` entity
+ * through the MTProto send→IV→decode round trip the UAT driver uses. This is a
+ * harness-decoder limitation, NOT a wire failure: a 2026-07 direct probe of the
+ * Bot API `sendRichMessage` endpoint (the actual production send path) confirmed
+ * `||spoiler||` DOES parse to a `spoiler` entity and `==highlight==` to `marked`
+ * on the live wire — see `reference/rfcs/telegram-native-formatting.md` §6a.
+ * Spoiler ships default-on; it stays soft here purely so this MTProto-decode
+ * gate doesn't red on its own decode gap. (Underline `__…__`, by contrast, is a
+ * genuine wire exclusion — it parses as bold; see §6a.) The decoder's
+ * `textMarked → spoiler` mapping is still pinned deterministically by the
+ * hosted unit suite.
  *
  * Lists and dividers carry no first-class Bot API entity (they render as
  * bulleted/numbered/rule TEXT), so they are asserted on `reply.text` below.
@@ -252,3 +268,79 @@ function kindsPresent(msg: ObservedMessage): Set<string> {
     );
   },
 );
+
+// ---------------------------------------------------------------------------
+// Rich-render wiring proof — expandable / collapsible content round-trip.
+//
+// This is the piece the unit suite CANNOT prove: that a REAL markdown reply
+// carrying the Bot API 10.1 expandable-blockquote marker (`**> `) flows
+// through the live send path — parse.ts (marker -> IR `expandable: true`) ->
+// render.ts (IR -> `**> ` markdown) -> renderSafe -> sendRichMessage — and
+// that Telegram actually parses it back to a blockquote entity on the wire.
+//
+// Runs ONLY when the rich-render flag is on in this process (see
+// RICH_RENDER_ON) AND the driver creds are present; self-skips green
+// otherwise, so default CI (flag off) never reds on it.
+// ---------------------------------------------------------------------------
+
+const EXP_MARKER = "COLLAPSE9";
+const EXPANDABLE_SAMPLE = [
+  `Reply with EXACTLY this and NOTHING else, keeping ${EXP_MARKER} verbatim:`,
+  "",
+  `${EXP_MARKER}: here is a collapsible section.`,
+  "",
+  "**> first hidden line of the expandable quote",
+  "> second hidden line",
+  "> third hidden line",
+].join("\n");
+
+(HAS_DRIVER_CREDS && RICH_RENDER_ON ? describe : describe.skip)(
+  "uat: expandable/collapsible content round-trips through the live renderer",
+  () => {
+    it(
+      "a `**>` reply parses -> renders -> sends -> decodes as a blockquote entity",
+      async () => {
+        const sc = await spinUp({ agent: AGENT });
+        try {
+          await sc.sendDM(EXPANDABLE_SAMPLE);
+
+          const reply = await sc.expectMessage(
+            (m: ObservedMessage) =>
+              m.text.includes(EXP_MARKER) || m.text === "\x01",
+            { from: "bot", timeout: 90_000 },
+          );
+
+          // Decode regression gate (same as the primary scenario).
+          expect(
+            reply.text,
+            "expandable reply decoded as the \\x01 unsupported-media sentinel",
+          ).not.toBe("\x01");
+          expect(reply.text).toContain(EXP_MARKER);
+
+          // The collapsible construct must survive as a real blockquote entity
+          // on the wire — proof the parse->render->send path produced valid
+          // Bot API 10.1 markdown, not stray `**>` literal text.
+          const present = kindsPresent(reply);
+          expect(
+            [...present],
+            `expandable quote did not decode as a blockquote entity ` +
+              `(present kinds: ${[...present].join(", ")})`,
+          ).toContain("blockquote");
+
+          // The quoted body text must round-trip (content never lost).
+          expect(reply.text).toContain("first hidden line");
+
+          console.info(
+            "[uat] expandable round-trip entity structure: " +
+              JSON.stringify(
+                reply.entities.map((e) => ({ kind: e.kind, text: e.text })),
+              ),
+          );
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      120_000,
+    );
+  },
+);

package/telegram-plugin/uat/scenarios/silent-end-recovery-channel.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Silent-end recovery — CHANNEL twin of `silent-end-recovery-dm.test.ts`
+ * (Phase 4a, `deterministic-turn-liveness.md`: the dark-turn guard must
+ * deliver exactly one fallback message on the real surface, in a DM AND a
+ * forum topic alike).
+ *
+ * Phase 2 (already shipped) hardens `recordUndeliveredTurnEnd` /
+ * `SILENT_END_FALLBACK_TEXT` as the ONE deterministic guard for a turn that
+ * ends having delivered no reply. This scenario proves it fires — at most
+ * once — for the same tool-heavy prompt shape, in a supergroup, AND that no
+ * mid-turn device ping is emitted before the terminal reply/fallback (the
+ * ping-free invariant the RFC/job spec claim is inline in every scenario).
+ * The terminal dark-turn fallback itself is a sanctioned loud unwedge send, so
+ * only pings STRICTLY BEFORE the terminal message count as erosion.
+ *
+ * Self-skips green when no test supergroup is wired.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+import { expectMessage, isActivityFeedMessage } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+const SUPERGROUP_ID = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID ?? "", 10);
+
+const TOOL_HEAVY_PROMPT =
+  "Pick a directory under /tmp that doesn't exist yet. Create it. " +
+  "List its contents (should be empty). Write a small file in it. " +
+  "List again. Then report what you did in a one-line reply.";
+
+describe("uat: silent-end recovery (channel parity)", () => {
+  it(
+    "user asks in a supergroup → agent replies exactly once via the fallback ladder if needed, no mid-turn ping",
+    async () => {
+      if (!Number.isFinite(SUPERGROUP_ID)) {
+        console.warn("[silent-end-recovery-channel] SWITCHROOM_UAT_CHAT_ID unset — skipping");
+        return;
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        await sc.driver.primeDialogs();
+        if (!(await sc.driver.canResolve(SUPERGROUP_ID))) {
+          console.warn(`[silent-end-recovery-channel] supergroup ${SUPERGROUP_ID} not resolvable — skipping`);
+          return;
+        }
+
+        const iter = sc.driver
+          .observeMessages(SUPERGROUP_ID)
+          [Symbol.asyncIterator]();
+
+        await sc.driver.sendText(SUPERGROUP_ID, TOOL_HEAVY_PROMPT);
+        const sentAt = Date.now();
+
+        // Same budget rationale as the DM twin: covers normal latency, one
+        // Stop-hook re-prompt cycle, and the worst-case 300s framework
+        // fallback. We observe the whole window so we can assert the ping-free
+        // invariant BEFORE the terminal reply, not just wait for the reply.
+        let reply: ObservedMessage | null = null;
+        let midTurnPing: ObservedMessage | null = null;
+
+        const deadline = Date.now() + 320_000;
+        while (Date.now() < deadline) {
+          if (reply) break;
+          const remaining = deadline - Date.now();
+          const next = await Promise.race([
+            iter.next(),
+            new Promise<{ done: true; value: undefined }>((r) =>
+              setTimeout(() => r({ done: true, value: undefined }), Math.max(0, remaining)),
+            ),
+          ]);
+          if (next.done || next.value == null) break;
+          const m = next.value as ObservedMessage;
+          if (m.senderUserId === sc.driverUserId) continue;
+
+          // Card edits are the sanctioned mid-turn liveness surface (silent by
+          // construction) — skip them from the ping accounting.
+          if (isActivityFeedMessage(m)) {
+            if (m.edited && m.silent === false) midTurnPing = midTurnPing ?? m;
+            continue;
+          }
+          if (m.edited) continue;
+          // First substantive non-card bot message is the terminal reply
+          // (model answer OR the dark-turn fallback — both terminal, both may
+          // legitimately ping).
+          if (m.text.trim().length > 0) {
+            reply = m;
+            continue;
+          }
+        }
+
+        expect(
+          midTurnPing,
+          `a mid-turn message pinged the device BEFORE the terminal reply in the supergroup: ` +
+            JSON.stringify(midTurnPing?.text?.slice(0, 120)),
+        ).toBeNull();
+
+        expect(reply, "FAIL — no reply arrived within budget; the silent-end guard may have regressed.").not.toBeNull();
+        expect(reply!.text.length).toBeGreaterThan(0);
+        expect(reply!.chatId).toBe(SUPERGROUP_ID);
+        console.log(`[silent-end-recovery-channel] reply at +${Date.now() - sentAt}ms.`);
+
+        if (/no update from agent|didn't send a reply/i.test(reply!.text)) {
+          console.warn(
+            "[silent-end-recovery-channel] reply was the framework/dark-turn fallback — " +
+              `model never replied on its own. Reply text: ${JSON.stringify(reply!.text.slice(0, 200))}`,
+          );
+
+          // Exactly-once proof: no SECOND fallback-shaped message should
+          // follow within a short window (the `exhausted` latch).
+          let secondFallback: ObservedMessage | null = null;
+          try {
+            secondFallback = await expectMessage(
+              sc.driver,
+              SUPERGROUP_ID,
+              /no update from agent|didn't send a reply/i,
+              { timeout: 15_000, senderFilter: { notUserId: sc.driverUserId } },
+            );
+          } catch {
+            // Timeout is the expected/good outcome — no second fallback fired.
+          }
+          expect(
+            secondFallback,
+            "the dark-turn/framework fallback fired MORE than once for the same turn " +
+              "(the `exhausted` latch should give fire-once)",
+          ).toBeNull();
+        }
+
+        await iter.return?.();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    360_000,
+  );
+});