switchroom 0.16.38 → 0.16.47

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

@@ -0,0 +1,169 @@
+/**
+ * JTBD scenario — a reply too long for one rich message renders correctly
+ * across BOTH chunks.
+ *
+ * Serves the same trust contract as `jtbd-rich-formatting-render-dm.test.ts`
+ * (`reference/jobs/know-what-my-agent-is-doing.md`): what the agent posts must
+ * render on the user's phone. That sibling proves single-message render
+ * fidelity. THIS scenario proves the MULTI-PART path: when a reply exceeds the
+ * Bot API 10.1 rich-message wire cap (`RICH_MESSAGE_MAX_CHARS` = 32768,
+ * `telegram-plugin/format.ts`), the gateway splits it into ordered chunks
+ * (`splitMarkdownChunks`) — and each chunk must still be a self-contained,
+ * correctly-parsed rich message. A split that bisects a formatting construct
+ * (an unterminated bold, a half-open code fence) produces a chunk Telegram
+ * renders wrong; this closes that loop against Telegram's REAL renderer via
+ * the mtcute driver, the same way the single-message scenario does.
+ *
+ * NOTE: switchroom has NO streaming-edit reply path — a long reply is sent as
+ * discrete chunk messages, not progressive edits. This scenario asserts on
+ * those discrete parts. It is deliberately NOT a streaming test.
+ *
+ * ## What it asserts
+ *
+ *   1. TWO distinct bot messages arrive (the reply chunked — not one).
+ *   2. The FIRST part carries the head marker and renders a formatting entity
+ *      (bold) — formatting survived in chunk 1.
+ *   3. The LAST part carries the tail marker and renders a formatting entity
+ *      (bold) — formatting survived across the split into chunk 2.
+ *   4. Neither part decoded as the `\x01` unsupported-media sentinel.
+ *
+ * ## Status: ARMED, not yet wired into the uat-gate
+ *
+ * A first live attempt on the uat-host (PR #2745) timed out at the HEAD-marker
+ * poll: coaxing a model turn to emit ~40k chars of verbatim padding is not
+ * reliable — the agent summarizes/truncates or blows the turn budget, so no
+ * >32768-char reply is produced and the gateway never chunks. The chunker
+ * itself (`splitMarkdownChunks`) is unit-tested deterministically in
+ * `telegram-plugin/tests/`; what this scenario needs to prove live is the
+ * end-to-end SEND of an already-oversized reply, which a prompt can't force.
+ *
+ * So this scenario is deliberately NOT in the `uat-gate` step list — it would
+ * red the gate on the model's refusal to pad, not on a real render regression.
+ * It self-skips green in ordinary CI (no driver creds) and is kept as the
+ * armed harness for a future deterministic oversized-send hook (e.g. a driver
+ * that posts a pre-composed >32k body directly, bypassing the model turn).
+ *
+ * ## Self-skip
+ *
+ * Same gating as every scenario here: needs the driver session
+ * (`TELEGRAM_UAT_DRIVER_SESSION`, gated to the CI uat-host). Self-skips green
+ * when creds are absent.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+import { RICH_MESSAGE_MAX_CHARS } from "../../format.js";
+
+const AGENT = "test-harness";
+
+const HAS_DRIVER_CREDS =
+  (process.env.TELEGRAM_UAT_DRIVER_SESSION ?? "").length > 0 &&
+  (process.env.TELEGRAM_API_HASH ?? "").length > 0 &&
+  Number.isFinite(Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10)) &&
+  (process.env.TELEGRAM_TEST_BOT_USERNAME ?? "").length > 0;
+
+// Head + tail markers, uppercase+digit so a voice/dash scrub leaves them
+// intact. HEAD must land in chunk 1, TAIL in the final chunk.
+const HEAD = "MULTIHEAD3";
+const TAIL = "MULTITAIL9";
+
+// We need the composed reply to exceed the 32768-char cap so the gateway
+// chunks it. Asking a model to emit ~40k literal chars is flaky (it'll
+// summarize or truncate). Instead we ask it to REPEAT a fixed, cheap-to-
+// generate padding block a deterministic number of times — a task an agent
+// reliably obeys because it's mechanical, not generative.
+const PAD_LINE = "The quick brown fox jumps over the lazy dog. ";
+// Overshoot the cap by a comfortable margin so a slightly-short reply still
+// splits: (cap / line) rounded up, times a 1.3 safety factor.
+const REPEATS = Math.ceil((RICH_MESSAGE_MAX_CHARS / PAD_LINE.length) * 1.3);
+
+const PROMPT = [
+  `I need a LONG reply to test message chunking. Do EXACTLY this, nothing else:`,
+  ``,
+  `1. Start your reply with: ${HEAD}: **head bold marker**`,
+  `2. Then output this exact sentence ${REPEATS} times, each on its own line:`,
+  `   "${PAD_LINE.trim()}"`,
+  `3. End your reply with: ${TAIL}: **tail bold marker**`,
+  ``,
+  `Do not summarize or shorten. Emit all ${REPEATS} repetitions verbatim.`,
+].join("\n");
+
+function kinds(msg: ObservedMessage): Set<string> {
+  return new Set(msg.entities.map((e) => e.kind));
+}
+
+(HAS_DRIVER_CREDS ? describe : describe.skip)(
+  "uat: a long reply chunks over the wire cap and both parts render",
+  () => {
+    it(
+      "first + last chunk each decode to real text with formatting intact",
+      async () => {
+        const sc = await spinUp({ agent: AGENT });
+        try {
+          await sc.sendDM(PROMPT);
+
+          // Chunk 1: the part carrying the HEAD marker.
+          const first = await sc.expectMessage(
+            (m: ObservedMessage) => m.text.includes(HEAD) || m.text === "\x01",
+            { from: "bot", timeout: 120_000 },
+          );
+          // Chunk 2 (final): the part carrying the TAIL marker. This is a
+          // DIFFERENT message than `first` — if the reply hadn't chunked,
+          // TAIL would be in the same message and this poll would time out,
+          // failing loudly (which is the correct signal: no split happened).
+          const last = await sc.expectMessage(
+            (m: ObservedMessage) =>
+              (m.text.includes(TAIL) || m.text === "\x01") &&
+              m.messageId !== first.messageId,
+            { from: "bot", timeout: 120_000 },
+          );
+
+          // (4) Neither part is the unsupported-media sentinel.
+          expect(
+            first.text,
+            "first chunk decoded as \\x01 sentinel — rich decode failed",
+          ).not.toBe("\x01");
+          expect(
+            last.text,
+            "last chunk decoded as \\x01 sentinel — rich decode failed",
+          ).not.toBe("\x01");
+
+          // (1) They are genuinely two distinct messages.
+          expect(
+            last.messageId,
+            "TAIL marker landed in the SAME message as HEAD — the reply did " +
+              "not chunk (was it under the 32768-char cap?)",
+          ).not.toBe(first.messageId);
+
+          // (2) Head marker + a bold entity present in chunk 1.
+          expect(first.text).toContain(HEAD);
+          expect(
+            kinds(first).has("bold"),
+            "no bold entity in the first chunk — formatting stripped on the " +
+              "wire for chunk 1",
+          ).toBe(true);
+
+          // (3) Tail marker + a bold entity present in the final chunk — the
+          // load-bearing assertion: formatting survived the split boundary.
+          expect(last.text).toContain(TAIL);
+          expect(
+            kinds(last).has("bold"),
+            "no bold entity in the last chunk — a split boundary corrupted " +
+              "the formatting of chunk 2",
+          ).toBe(true);
+
+          console.info(
+            `[uat] multipart render: first msg=${first.messageId} ` +
+              `(${first.text.length} chars, kinds=${[...kinds(first)].join(",")}) ` +
+              `last msg=${last.messageId} ` +
+              `(${last.text.length} chars, kinds=${[...kinds(last)].join(",")})`,
+          );
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      180_000,
+    );
+  },
+);

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

@@ -0,0 +1,134 @@
+/**
+ * JTBD scenario — narration-quality: a plain-language intent line before
+ * a silent tool stretch.
+ *
+ * Serves "know what my agent is actually doing"
+ * (`reference/jobs/know-what-my-agent-is-doing.md`) beat 3, and the
+ * thinking-visibility work (Option 2). With extended-thinking text
+ * server-redacted for the current flagship models (they emit
+ * `thinking` → `tool_use` → `reply` with no interstitial prose, see the
+ * PIVOT in `reference/rfcs/draft-mirror-preview.md`), the model's OWN
+ * plain-language intent narration is the only compliant carrier for
+ * "what am I doing / why" during a silent tool burst. The pacing prompt
+ * (scaffold.ts `TELEGRAM_GUIDANCE` beat 2 + the per-turn `<turn-pacing>`
+ * directive) now instructs the model to drop ONE intent line as ordinary
+ * working text before a tool stretch. This scenario pins the CARRIER: a
+ * leading `text` block surfaces as working narration (not suppressed as a
+ * draft-of-reply, not sent as a chat message) BEFORE the silent tool
+ * stretch, and the Bash `description` is the visible activity label.
+ *
+ * Why a projection-kernel scenario, not a live mtcute harness: the
+ * intent line lives in the ephemeral compose-area draft, and mtcute
+ * "CANNOT observe drafts or reactions" (CLAUDE.md, UAT caveat) — a live
+ * harness structurally cannot see this surface. The same reasoning made
+ * `jtbd-reflective-status-reaction-dm` a controller-level scenario. The
+ * deterministic assertion here (over the exact JSONL the model emits) is
+ * strictly more powerful than a flaky "did the model narrate this run"
+ * live check. The prompt that MAKES the model narrate is pinned by
+ * `tests/scaffold.test.ts` ("intent-narration carrier").
+ */
+
+import { describe, it, expect } from "vitest";
+import { projectTranscriptLine } from "../../session-tail.js";
+import { isDraftOfReply } from "../../narrative-dedup.js";
+import { toolLabel } from "../../tool-labels.js";
+
+/** The plain-language intent the pacing prompt asks for before a burst. */
+const INTENT =
+  "Now checking the gateway logs to find why the turn stalled.";
+
+/** A multi-tool assistant message: intent line, then a SILENT tool burst
+ *  (no reply among the tools). This is the exact shape beat 2 describes —
+ *  one intent line, then heads-down work. */
+function multiToolTurnLine(): string {
+  return JSON.stringify({
+    type: "assistant",
+    message: {
+      content: [
+        { type: "text", text: INTENT },
+        {
+          type: "tool_use",
+          id: "toolu_01",
+          name: "Bash",
+          input: {
+            command: "grep -n stall /var/log/switchroom/gateway.log | tail",
+            description: "Search the gateway log for the stall",
+          },
+        },
+        {
+          type: "tool_use",
+          id: "toolu_02",
+          name: "Read",
+          input: { file_path: "/state/agent/home/gateway.ts" },
+        },
+        {
+          type: "tool_use",
+          id: "toolu_03",
+          name: "Grep",
+          input: { pattern: "activeTurnStartedAt", path: "src/" },
+        },
+      ],
+    },
+  });
+}
+
+describe("uat-jtbd: narration intent before a silent tool stretch", () => {
+  it("a multi-tool turn surfaces at least one plain-language intent line before the burst", () => {
+    const events = projectTranscriptLine(multiToolTurnLine());
+
+    // The intent narration is projected as a `text` event.
+    const textEvents = events.filter((e) => e.kind === "text");
+    expect(textEvents.length).toBeGreaterThanOrEqual(1);
+    const intentEv = textEvents[0];
+    expect(intentEv.kind === "text" && intentEv.text).toBe(INTENT);
+
+    // It is PLAIN LANGUAGE, not a raw tool name / debug dump. (Bad-list:
+    // "calling Bash", "Read(x)", raw commands must never be the carrier.)
+    const t = (intentEv as { text: string }).text;
+    expect(t).not.toMatch(/calling \w+|Read\(|Bash\(|grep -n|\bnull\b/);
+    expect(t.length).toBeLessThan(160); // one line, phone-readable
+
+    // The intent line comes BEFORE the silent stretch: its projected
+    // position precedes every tool_use event in source order.
+    const firstToolIdx = events.findIndex((e) => e.kind === "tool_use");
+    const intentIdx = events.findIndex((e) => e.kind === "text");
+    expect(intentIdx).toBeGreaterThanOrEqual(0);
+    expect(firstToolIdx).toBeGreaterThan(intentIdx);
+
+    // And it really is a SILENT stretch — a burst of >1 tool with no reply
+    // tool interleaved. The narration is the ONLY signal the user gets.
+    const toolCount = events.filter((e) => e.kind === "tool_use").length;
+    expect(toolCount).toBeGreaterThan(1);
+    const replyToolFired = events.some(
+      (e) => e.kind === "tool_use" && /^(reply|stream_reply)$/.test(e.toolName),
+    );
+    expect(replyToolFired).toBe(false);
+  });
+
+  it("the intent line is working-narration (surfaced), not a draft-of-reply (suppressed)", () => {
+    // The reducer-side dedup gate SUPPRESSES a text block only when it is
+    // the model composing its answer just before `reply`. An intent line
+    // that names what it's about to DO shares no prefix with the eventual
+    // answer, so the gate SHOWS it. Pin both sides.
+    const laterAnswer =
+      "The turn stalled because the typing loop was never cleared on error.";
+    expect(isDraftOfReply(INTENT, laterAnswer)).toBe(false);
+
+    // Control: a genuine draft-then-send IS suppressed, so we know the gate
+    // is live and the assertion above isn't vacuously true.
+    const draft = laterAnswer + " (composing…)";
+    expect(isDraftOfReply(draft, laterAnswer)).toBe(true);
+  });
+
+  it("the Bash description — not the raw command — is the visible activity label", () => {
+    // The compose-area draft renders `input.description` for Bash (never
+    // the raw `command`). This is why the prompt tells the model to always
+    // give Bash a plain-English description: it IS the visible carrier.
+    const label = toolLabel("Bash", {
+      command: "grep -n stall /var/log/switchroom/gateway.log | tail",
+      description: "Search the gateway log for the stall",
+    });
+    expect(label).toBe("Search the gateway log for the stall");
+    expect(label).not.toContain("grep");
+  });
+});

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

@@ -0,0 +1,254 @@
+/**
+ * JTBD scenario — the real account SEES rendered rich formatting.
+ *
+ * Serves: `reference/jobs/know-what-my-agent-is-doing.md` — the trust
+ * contract that what the agent posts renders correctly on the user's
+ * phone. Phase 1 (PR #2741, `formatting-parse-regression.test.ts`) pins
+ * this at the PARSE level (our emitted markdown parses to the intended
+ * entity structure, checked by an independent oracle). This scenario is
+ * the higher-fidelity RENDER-level layer: it drives a REAL agent turn
+ * through a REAL bot into a REAL chat, then reads back — via the mtcute
+ * MTProto driver — the entity structure Telegram ACTUALLY parsed and will
+ * render. It closes the loop the unit suite can't: it proves Telegram's
+ * own renderer agrees with our oracle, not just that our oracle agrees
+ * with our formatter.
+ *
+ * ## Why this needs the mtcute upgrade (issue #2739)
+ *
+ * On the pinned mtcute (0.27.x) a Bot API 10.1 rich message
+ * (`sendMessage` with `{ markdown }`) decoded as `messageMediaUnsupported`
+ * with empty text — so the driver saw NEITHER text NOR entities and
+ * substituted a `\x01` sentinel. With mtcute >=0.30 the message decodes to
+ * real text + entities, and `toObserved()` now surfaces both
+ * `ObservedMessage.entities` and the `t.me` permalink (`.link`). This test
+ * asserts on that real, decoded structure. If the sentinel ever reappears
+ * (`text === "\x01"`, `entities === []`) the assertions fail LOUDLY rather
+ * than silently pass — it is the regression gate for the decode itself.
+ *
+ * ## What it asserts
+ *
+ * The agent is asked to reply with a small, unambiguous formatting sample
+ * (bold / italic / inline code / a fenced code block / an inline link)
+ * anchored by a stable marker token so the reply is findable in the stream.
+ * We then assert, on the observed bot reply:
+ *
+ *   1. The body decoded to real text (NOT the `\x01` unsupported-media
+ *      sentinel) — the core decode regression gate.
+ *   2. Telegram parsed the expected entity KINDS (membership, not exact
+ *      spans — a model reply is not byte-deterministic, so we mirror
+ *      Phase 1's "these entities are PRESENT" philosophy rather than an
+ *      exact-echo assertion).
+ *   3. The link entity carries the right destination URL.
+ *   4. A `t.me/c/<chat>/<msgid>` (or `t.me/<user>`) permalink is captured
+ *      and logged for human eyeball reference (best-effort — private DMs
+ *      don't support message links, so this is logged, not asserted).
+ *
+ * ## Self-skip
+ *
+ * Like every scenario in this dir, it needs the driver session
+ * (`TELEGRAM_UAT_DRIVER_SESSION`, vault key `telegram-uat-driver-session`,
+ * gated to the CI uat-host runner / test-harness agent). It self-skips
+ * green when those creds are absent so a fork PR / un-wired host never
+ * reds — the `uat/**` tree is excluded from gating CI anyway; the
+ * `uat-gate` sentinel owns the real run.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+
+// 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 =
+  (process.env.TELEGRAM_UAT_DRIVER_SESSION ?? "").length > 0 &&
+  (process.env.TELEGRAM_API_HASH ?? "").length > 0 &&
+  Number.isFinite(Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10)) &&
+  (process.env.TELEGRAM_TEST_BOT_USERNAME ?? "").length > 0;
+
+// A stable marker so the reply is unambiguously findable in the observed
+// stream (the agent is told to include it verbatim). Uppercase + digit so
+// it survives any voice/dash scrub untouched.
+const MARKER = "RICHFMT7";
+
+// The formatting sample the agent is asked to reproduce. Kept small and
+// unambiguous: one entity of each kind we care about, plus a link with a
+// known destination.
+const LINK_URL = "https://github.com/switchroom/switchroom";
+const SAMPLE_LINES = [
+  `Reply with EXACTLY this, including the marker ${MARKER} verbatim, and NOTHING else:`,
+  "",
+  `${MARKER}: here is **a bold phrase**, some *italic words*, an inline \`code_token\`, ` +
+    `some ~~struck text~~, a ||hidden spoiler||, and a link to [the repo](${LINK_URL}).`,
+  "",
+  "## A heading line",
+  "",
+  "> a blockquoted line",
+  "",
+  "- first bullet",
+  "- second bullet",
+  "",
+  "1. ordered one",
+  "2. ordered two",
+  "",
+  "Then, on new lines, a fenced code block:",
+  "```bash",
+  'echo "hello from the torture set"',
+  "```",
+].join("\n");
+
+/**
+ * mtcute entity kinds we HARD-ASSERT Telegram parsed from the sample. Phase 2
+ * extends the original bold/italic/code/pre/text_link set with strikethrough
+ * and blockquote — both confirmed to survive the live send→IV→decode round
+ * 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.
+ *
+ * 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.
+ */
+const EXPECTED_KINDS = [
+  "bold",
+  "italic",
+  "code",
+  "pre",
+  "text_link",
+  "strikethrough",
+  "blockquote",
+] as const;
+
+/** Soft-observed only (see note above) — logged, never fails the gate. */
+const SOFT_KINDS = ["spoiler"] as const;
+
+function kindsPresent(msg: ObservedMessage): Set<string> {
+  return new Set(msg.entities.map((e) => e.kind));
+}
+
+(HAS_DRIVER_CREDS ? describe : describe.skip)(
+  "uat: real account sees rendered rich formatting (entities + permalink)",
+  () => {
+    it(
+      "bot reply decodes to real text + expected entity kinds; permalink captured",
+      async () => {
+        const sc = await spinUp({ agent: AGENT });
+        try {
+          await sc.sendDM(SAMPLE_LINES);
+
+          // Find the bot reply carrying our marker. The reply may be
+          // streamed/split; we want the chunk that actually holds the
+          // formatting sample (the one with the marker token).
+          const reply = await sc.expectMessage(
+            (m: ObservedMessage) =>
+              m.text.includes(MARKER) || m.text === "\x01",
+            { from: "bot", timeout: 90_000 },
+          );
+
+          // (1) Decode regression gate: the body must be REAL text, not the
+          // unsupported-media sentinel. If this fails, mtcute is not
+          // decoding the rich message — the whole point of the upgrade.
+          expect(
+            reply.text,
+            "bot reply decoded as the \\x01 unsupported-media sentinel — " +
+              "mtcute is NOT decoding the Bot API rich message (issue #2739 regression)",
+          ).not.toBe("\x01");
+          expect(reply.text).toContain(MARKER);
+
+          // (2) Telegram must have parsed at least SOME entities — a reply
+          // that carries the marker but zero entities means formatting was
+          // stripped on the wire (or decode silently dropped entities).
+          const present = kindsPresent(reply);
+          expect(
+            reply.entities.length,
+            `observed reply had zero entities (kinds=${[...present].join(",")}) — ` +
+              "formatting did not survive the render round-trip",
+          ).toBeGreaterThan(0);
+
+          // (3) Entity-kind membership. We assert PRESENCE of each expected
+          // kind, not exact spans (model replies aren't byte-deterministic,
+          // and streaming may split the sample across chunks — this mirrors
+          // Phase 1's membership philosophy). A missing kind is a real
+          // render-fidelity regression for that construct.
+          const missing = EXPECTED_KINDS.filter((k) => !present.has(k));
+          expect(
+            missing,
+            `expected entity kinds missing from the rendered reply: ${missing.join(", ")} ` +
+              `(present: ${[...present].join(", ")})`,
+          ).toEqual([]);
+
+          // Soft-observed constructs (e.g. spoiler) — logged, never fail the
+          // gate. See EXPECTED_KINDS note for why spoiler is soft.
+          for (const k of SOFT_KINDS) {
+            console.info(
+              `[uat] soft-observed construct '${k}': ` +
+                (present.has(k) ? "PRESENT on the wire" : "absent (expected — not gated)"),
+            );
+          }
+
+          // (4) The link entity must carry the right destination.
+          const link = reply.entities.find((e) => e.kind === "text_link");
+          expect(link, "no text_link entity found in the reply").toBeDefined();
+          expect(link?.url).toBe(LINK_URL);
+
+          // (5) Lists and dividers have NO first-class Bot API entity — the
+          // decoder renders them into TEXT (bulleted "• ", numbered "N. ").
+          // Assert the decoded body carries a bullet and an ordinal marker so
+          // a regression that drops list structure (back to bare inline text)
+          // reds here. Model replies aren't byte-deterministic, so we check
+          // for the STRUCTURE markers, not exact list wording.
+          expect(
+            reply.text,
+            "decoded reply carried no bullet marker — pageBlockList decode " +
+              "regressed to flat text",
+          ).toContain("• ");
+          expect(
+            reply.text,
+            "decoded reply carried no ordinal marker — pageBlockOrderedList " +
+              "decode regressed to flat text",
+          ).toMatch(/\b1\.\s/);
+
+          // Permalink capture — best-effort human-eyeball reference. Private
+          // DMs don't support message links (mtcute's .link getter throws
+          // there; toObserved swallows it), so we LOG rather than assert.
+          if (reply.link) {
+            console.info(
+              `[uat] rich-formatting reply permalink: ${reply.link} ` +
+                `(chat=${reply.chatId} msg=${reply.messageId})`,
+            );
+          } else {
+            console.info(
+              `[uat] rich-formatting reply had no permalink ` +
+                `(expected for a private DM) — chat=${reply.chatId} msg=${reply.messageId}`,
+            );
+          }
+
+          // Forensic dump of the exact entity structure Telegram returned —
+          // this is the render-fidelity evidence the parse-level suite can't
+          // produce (it's what Telegram PARSED, not what we EMITTED).
+          console.info(
+            "[uat] rendered entity structure: " +
+              JSON.stringify(
+                reply.entities.map((e) => ({
+                  kind: e.kind,
+                  text: e.text,
+                  ...(e.url ? { url: e.url } : {}),
+                  ...(e.language ? { language: e.language } : {}),
+                })),
+              ),
+          );
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      120_000,
+    );
+  },
+);

package/telegram-plugin/uat/scenarios/jtbd-status-phase-transitions-dm.test.ts

@@ -0,0 +1,109 @@
+/**
+ * JTBD scenario — the status reaction moves through DISTINCT phases across
+ * a turn: acknowledged → thinking → working/editing → done.
+ *
+ * Serves "know what my agent is actually doing"
+ * (`reference/jobs/know-what-my-agent-is-doing.md`): the "Good looks like"
+ * line — "that signal distinguishes phases at a glance: acknowledged,
+ * thinking or working, actively editing. It stays present from receipt to
+ * turn end and never disappears mid-turn." The reflective controller test
+ * (`jtbd-reflective-status-reaction-dm`) pins the #1713 non-event/
+ * bidirectional rules; THIS scenario pins the complementary contract the
+ * job cares about most: over a realistic full turn the phases actually
+ * FIRE, in order, and are visibly DIFFERENT emoji families (not one
+ * undifferentiated "working" blob — an explicit bad-list item).
+ *
+ * Simulated (not live mtcute): real Bot-API reactions expose only the
+ * CURRENT emoji, never the transition trail, so the controller-level
+ * assertion over the whole sequence is strictly more powerful — the same
+ * reasoning documented in `jtbd-reflective-status-reaction-dm`.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { StatusReactionController } from "../../status-reactions.js";
+
+async function flush(): Promise<void> {
+  for (let i = 0; i < 8; i++) await Promise.resolve();
+}
+
+// Phase families the JOB cares about (job spec "Good looks like"). Emoji
+// membership is pinned by status-reactions.ts; we assert the family a
+// glance would read, so a palette retune that preserves the phase meaning
+// doesn't false-fail this behavioural scenario.
+const ACK = new Set(["👀", "🤔", "🤓"]); // received / acknowledged
+const THINKING = new Set(["🤔", "🤓"]); // generating
+const WORKING = new Set(["✍", "⚡", "👌", "👨‍💻", "🗜"]); // tools / editing / coding
+const DONE = new Set(["👍", "💯", "🎉"]); // turn over
+
+describe("uat-jtbd: status reaction phase transitions across a turn", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("acknowledged → thinking → working/editing → done all fire, in order, as distinct phases", async () => {
+    const calls: string[] = [];
+    const ctrl = new StatusReactionController(async (e: string) => {
+      calls.push(e);
+    });
+
+    // A realistic turn: inbound arrives, model thinks, then reads/edits
+    // (a silent tool stretch), then the turn ends with an answer.
+    ctrl.setQueued(); // acknowledged
+    await flush();
+
+    ctrl.setThinking(); // thinking
+    vi.advanceTimersByTime(3500);
+    await flush();
+
+    ctrl.setTool("Read"); // working — coding family
+    vi.advanceTimersByTime(3500);
+    await flush();
+
+    ctrl.setTool("Edit"); // still working — actively editing
+    vi.advanceTimersByTime(3500);
+    await flush();
+
+    ctrl.finalize("done"); // turn_end — done
+    await flush();
+
+    // Each phase fired at least once.
+    expect(calls.some((e) => ACK.has(e))).toBe(true);
+    expect(calls.some((e) => THINKING.has(e))).toBe(true);
+    expect(calls.some((e) => WORKING.has(e))).toBe(true);
+    expect(calls.some((e) => DONE.has(e))).toBe(true);
+
+    // They fired IN ORDER: first ack, a working beat before the terminal,
+    // and done strictly last.
+    const firstWorkingIdx = calls.findIndex((e) => WORKING.has(e));
+    const doneIdx = calls.findIndex((e) => DONE.has(e));
+    expect(firstWorkingIdx).toBeGreaterThan(0); // ack precedes working
+    expect(doneIdx).toBe(calls.length - 1); // done is terminal + last
+    expect(firstWorkingIdx).toBeLessThan(doneIdx); // work before done
+
+    // The phases are VISIBLY DIFFERENT — thinking and working are not the
+    // same emoji (the "one undifferentiated working signal" bad-list item).
+    const thinkingEmoji = calls.find((e) => THINKING.has(e))!;
+    const workingEmoji = calls.find((e) => WORKING.has(e))!;
+    expect(thinkingEmoji).not.toBe(workingEmoji);
+
+    // Liveness never disappears mid-turn: 👍 appears exactly once, only at
+    // the end — the signal is present from receipt to terminal state.
+    expect(calls.filter((e) => DONE.has(e)).length).toBe(1);
+  });
+
+  it("a trivial turn still acknowledges before it finishes (never a silent gap)", async () => {
+    // "A trivial ask just gets the answer" — but even then the inbound is
+    // acknowledged (👀) before the turn finalizes; the ack is never skipped.
+    const calls: string[] = [];
+    const ctrl = new StatusReactionController(async (e: string) => {
+      calls.push(e);
+    });
+
+    ctrl.setQueued();
+    await flush();
+    ctrl.finalize("done");
+    await flush();
+
+    expect(ACK.has(calls[0])).toBe(true);
+    expect(DONE.has(calls[calls.length - 1])).toBe(true);
+  });
+});