switchroom 0.7.15 → 0.10.0

package/telegram-plugin/uat/scenarios/secret-redaction-deletes-original-dm.test.ts

@@ -0,0 +1,123 @@
+/**
+ * UAT scenario — operator pastes a real-shaped secret into the bot's
+ * DM; bot detects, deletes the original, posts a redaction card.
+ *
+ * Part of: secret-redaction bug class reported 2026-05-12 (Bug A —
+ * sometimes the original message isn't actually deleted from chat
+ * history despite the bot claiming it was).
+ *
+ * **Skipped by default.** To unskip:
+ *
+ * 1. Run the standard UAT preflight (uat/SETUP.md §5-6) so the
+ *    test-harness agent is live and the driver session is auth'd.
+ *
+ * 2. Verify the test-harness chat has secret-detect enabled. The
+ *    agent's switchroom.yaml `access.json` must include the driver
+ *    in `allowFrom` so the driver's paste is treated as a real
+ *    operator message (not silently ignored). Existing UAT setup
+ *    already covers this for the smoke scenario.
+ *
+ * 3. Confirm a vault passphrase is cached in the test-harness chat
+ *    so the high-confidence-stored branch fires (not the
+ *    no-passphrase deferred branch). Easiest: send `/vault unlock`
+ *    + passphrase as the driver once before running this scenario.
+ *    Without a cached passphrase the assertion changes — the bot
+ *    posts the "🔒 caught a secret. tap below to unlock the vault
+ *    and save it" card instead of "🔒 captured N secrets:". Both
+ *    paths MUST delete the original; the matcher here is loose
+ *    enough to accept either.
+ *
+ * 4. Remove the `describe.skip` below.
+ *
+ * Why skipped: sends a real-shaped (but synthetic) secret-pattern
+ * string into Telegram. The pattern doesn't unlock any actual
+ * secret, but committing the scenario unskipped would also commit
+ * the test fixture into git history where secretlint pre-commit
+ * hooks might flag it. Generated at runtime to dodge the scan.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+describe.skip("uat: secret-redaction deletes the original message (Bug A 2026-05-12)", () => {
+  it(
+    "paste a real-shaped secret; bot deletes the original from chat history",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        // Build a real-shaped (but synthetic) ANTHROPIC_API_KEY value
+        // at runtime so the source file doesn't trip Push Protection.
+        // Same idiom as telegram-plugin/tests/secret-detect-secretlint.test.ts:1.
+        const fakeApiKey =
+          `sk-ant-` + "a1b2c3d4".repeat(4) + "_test_synthetic";
+        const inboundText = `set ANTHROPIC_API_KEY=${fakeApiKey}`;
+
+        // Send the secret-bearing message. Capture the messageId we
+        // sent so we can later assert it's gone from history.
+        const sent = await sc.sendDM(inboundText);
+        const sentMessageId = sent.messageId;
+
+        // The bot should reply with either:
+        //   - "🔒 captured N secret(s):" (high-confidence stored
+        //     path, requires cached passphrase)
+        //   - "🔒 caught a secret. we deleted it from chat. tap
+        //     below to unlock the vault..." (deferred path)
+        // OR the new fail-loud variant (if delete failed):
+        //   - "⚠️ Could not auto-delete message containing your ..."
+        // The contract this test pins is: ONE of the first two
+        // success messages appears AND the original message is
+        // actually gone from history.
+        const reply = await sc.expectMessage(
+          /🔒 (captured|caught)/,
+          { from: "bot", timeout: 30_000 },
+        );
+        expect(reply.text).toMatch(/deleted (it )?from chat|captured/i);
+
+        // The load-bearing assertion: the original message is
+        // unreachable in chat history. driver.getMessage returns
+        // null for deleted messages (driver.ts:525-534).
+        //
+        // Pre-2026-05-12 fix: this would sometimes pass when delete
+        // succeeded and silently leave the message behind when it
+        // failed (Telegram rate limits, network blip, message was
+        // edited mid-delete, etc.) — and the operator would never
+        // know.
+        //
+        // Post-fix: deleteSensitiveMessage either deletes
+        // successfully OR posts an in-chat warning "⚠️ Could not
+        // auto-delete..." which we'd see as a SECOND bot message.
+        // The assertion here is the strict "actually gone" version.
+        // chat_id for the driver's view of a DM = the partner's
+        // (bot's) user_id.
+        const stillThere = await sc.driver.getMessage(sc.botUserId, sentMessageId);
+        expect(
+          stillThere,
+          `original secret-bearing message ${sentMessageId} was NOT deleted — Telegram history still has it`,
+        ).toBeNull();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    120_000,
+  );
+
+  it(
+    "when delete fails (simulated by editing the message just before delete), the bot posts a warning naming the leaked msg_id",
+    async () => {
+      // This case is harder to repro without a fault-injection
+      // hook — Telegram doesn't let us "make deleteMessage fail
+      // deterministically" from the driver side. The contract is
+      // pinned by the unit test at
+      // telegram-plugin/tests/secret-detect-delete-must-surface-failures.test.ts
+      // (deleteSensitiveMessage helper still logs SECURITY: …
+      // FAILED + posts an in-chat warning on its catch path).
+      // This UAT slot stays skipped pending a fault-injection
+      // affordance in the driver — tracked as a TODO on the
+      // harness roadmap.
+      const _ = await spinUp({ agent: "test-harness" });
+      void _;
+      expect(true).toBe(true);
+    },
+    60_000,
+  );
+});

package/telegram-plugin/uat/scenarios/secret-redaction-no-false-positive-dm.test.ts

@@ -0,0 +1,87 @@
+/**
+ * UAT scenario — operator chats casually about secrets/tokens
+ * (mentioning the words, not pasting actual credentials); bot
+ * MUST NOT redact the operator's question.
+ *
+ * Part of: secret-redaction bug class reported 2026-05-12 (Bug B —
+ * false positive on the word "secret"/"token" or on
+ * code-shaped-but-placeholder values like `MY_TOKEN=hello`).
+ *
+ * **Skipped by default.** Unskip after the standard UAT preflight
+ * (uat/SETUP.md §5-6). No host-state mutations.
+ *
+ * The unit-shape contract is pinned in
+ * `telegram-plugin/tests/secret-detect-false-positives.test.ts` —
+ * which runs every CI cycle. This UAT scenario adds the
+ * end-to-end Telegram round-trip so a future regression in the
+ * gateway integration (not the detector) would also surface.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const CASUAL_MENTIONS = [
+  "what's my fatsecret token?",
+  "delete that secret you sent earlier",
+  "the FATSECRET_TOKEN env var is missing",
+  "set MY_TOKEN=hello and try again",
+  "I keep forgetting my password again",
+];
+
+describe.skip("uat: secret-redaction does NOT fire on casual mentions (Bug B 2026-05-12)", () => {
+  for (const text of CASUAL_MENTIONS) {
+    it(
+      `does not redact: ${JSON.stringify(text)}`,
+      async () => {
+        const sc = await spinUp({ agent: "test-harness" });
+        try {
+          const sent = await sc.sendDM(text);
+
+          // Wait a short period for any (incorrect) redaction reply
+          // to arrive. If the bot's gonna fire the redaction
+          // pipeline, it does so synchronously in handleInbound —
+          // well under 10s.
+          //
+          // The assertion: we should NOT see a "🔒 captured" or
+          // "🔒 caught a secret" reply. If we do, the false
+          // positive is back.
+          //
+          // We tolerate the bot's normal Claude reply (which is
+          // unrelated content). Pin only the absence of the
+          // redaction marker.
+          let sawRedaction = false;
+          try {
+            await sc.expectMessage(/🔒 (captured|caught)/, {
+              from: "bot",
+              timeout: 10_000,
+            });
+            sawRedaction = true;
+          } catch {
+            // Expected: timeout means no redaction fired.
+          }
+          expect(
+            sawRedaction,
+            `false-positive redaction fired on casual chat: ${JSON.stringify(text)}`,
+          ).toBe(false);
+
+          // The original message must remain visible — the
+          // operator asked a real question and the bot deleted
+          // it would be terrible UX.
+          // chat_id for the driver's view of a DM = the partner's
+          // (bot's) user_id.
+          const stillThere = await sc.driver.getMessage(
+            sc.botUserId,
+            sent.messageId,
+          );
+          expect(
+            stillThere,
+            `the bot deleted the operator's question (false positive on '${text}')`,
+          ).not.toBeNull();
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      60_000,
+    );
+  }
+});

package/telegram-plugin/uat/scenarios/silence-poke-soft-dm.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Silence-poke soft-fire end-to-end scenario.
+ *
+ * Goal context: cause class CC-3 in `docs/status-ask-cause-classes.md`
+ * — the L3 safety net. Unit tests (`silence-poke.test.ts`) cover the
+ * state machine: tick semantics, ladder thresholds, success measurement.
+ * They DO NOT cover the wire path between `consumeArmedPoke()` (in
+ * `silence-poke.ts`) and the model actually receiving the
+ * `[silence-poke]` system-reminder block on its next tool result.
+ *
+ * The wire path lives at `gateway.ts:2740`:
+ *
+ *   onToolCall → executeToolCall(...) → consumeArmedPoke() →
+ *   append `<system-reminder>[silence-poke] ...</system-reminder>`
+ *   to the tool-result text.
+ *
+ * If that integration ever breaks — a refactor swaps `executeToolCall`
+ * for a path that doesn't call `consumeArmedPoke`, the result-content
+ * shape mutation gets dropped, MCP framing changes — the unit tests
+ * still pass but the model never sees the nudge, the user goes silent
+ * past 75s, and `inbound_status_query` ticks. This UAT closes that
+ * regression window end-to-end.
+ *
+ * ## Strategy
+ *
+ * Force the agent into a stretch of silent tool churn that exceeds the
+ * 75s soft threshold without the model emitting any outbound `reply`.
+ * The conversational-pacing prompt instructs the model to soft-commit
+ * fast turns, so we have to explicitly suppress that:
+ *
+ *   - Prompt instructs three sequential 30s `sleep` Bash calls, NO
+ *     mid-turn replies, single final reply when done.
+ *   - Total silent stretch is ~90s + tool overhead, comfortably past
+ *     the 75s soft threshold.
+ *   - If the silence-poke wire works: the model sees the
+ *     `[silence-poke]` system-reminder appended to the result of the
+ *     first or second sleep, breaks the no-reply rule, sends a brief
+ *     update. We observe a reply in the [70s, 200s] window.
+ *   - If the wire is broken: model never receives the nudge, no
+ *     reply until the third sleep ends at ~90s+, OR the framework
+ *     fallback at 300s fires. We catch the latter as a separate
+ *     failure (the framework fallback is the FLOOR, not the goal).
+ *
+ * ## Tolerances
+ *
+ * Real-Telegram UAT against a real Claude model has variability:
+ *
+ *   - Model may insert one soft-commit "on it" reply at start; that
+ *     resets the silence clock. Three 30s sleeps still pushes the
+ *     post-commit silence past 75s as long as the commit lands
+ *     within the first ~10s. We tolerate this.
+ *   - Model may decline to follow the "no replies" instruction and
+ *     send updates organically; if the FIRST reply still lands in
+ *     [70s, 200s], the conversational pacing layer is doing its job
+ *     and the test passes regardless of whether silence-poke
+ *     specifically fired.
+ *   - Window is generous (70-200s) to absorb 5s poll interval,
+ *     mtcute receive lag, Telegram delivery jitter.
+ *
+ * ## Failure shapes the assertion catches
+ *
+ *   1. Wire path broken — first reply lands >200s after sendDM
+ *      because the framework fallback (300s) is the only thing that
+ *      eventually breaks the silence.
+ *   2. Soft poke armed but not drained — first reply lands at >200s
+ *      similarly.
+ *   3. Model misbehavior — first reply is the FINAL answer (long
+ *      text after all three sleeps complete at ~90s+); strictly that
+ *      passes the window check, but the test also asserts the first
+ *      reply is brief (<400 chars) as a sanity floor on "this is
+ *      actually a poke response, not the final answer." Skip strict
+ *      length if the prompt happens to be so simple the final
+ *      answer IS brief.
+ *
+ * Requires the same env as `smoke-dm-reply.test.ts` (see
+ * `uat/SETUP.md` §6). Long-running: outer budget 4 min.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const SOFT_WINDOW_MIN_MS = 70_000;
+const SOFT_WINDOW_MAX_MS = 200_000;
+
+// Explicit instruction shape. Mirrors the `BG_DISPATCH_PROMPT` pattern
+// in `bg-sub-agent-dispatch-dm.test.ts` — pin the tool + the sequence
+// so behaviour is deterministic enough to test the *infra*, not the
+// model's free-form judgement.
+const SILENT_CHURN_PROMPT =
+  "I need you to test something. Run THREE separate Bash tool calls " +
+  "in sequence: first `sleep 30`, then `sleep 30`, then `sleep 30`. " +
+  "Critical: do NOT send any `reply` or `stream_reply` between or " +
+  "during the sleeps — no soft commit, no progress updates, no " +
+  "narration. Just the three Bash calls back-to-back. Once all three " +
+  "complete, send ONE brief final reply saying 'done' so I know " +
+  "you're back.";
+
+describe("uat: silence-poke soft fires + reaches the model wire", () => {
+  it(
+    "agent breaks self-imposed silence in [70s, 200s] window via silence-poke",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const sendStart = Date.now();
+        await sc.sendDM(SILENT_CHURN_PROMPT);
+
+        // Wait for the FIRST reply. If silence-poke + the wire path
+        // are working, this lands between ~75s and ~110s as the
+        // model responds to the [silence-poke] system-reminder
+        // appended to the first or second sleep's tool result.
+        const firstReply = await sc.expectMessage(/\S/, {
+          from: "bot",
+          timeout: SOFT_WINDOW_MAX_MS + 20_000,
+        });
+        const elapsed = Date.now() - sendStart;
+
+        expect(firstReply.text.length).toBeGreaterThan(0);
+
+        // Primary window assertion.
+        expect(
+          elapsed,
+          `first bot reply lands at ${elapsed}ms (target window ` +
+            `[${SOFT_WINDOW_MIN_MS}, ${SOFT_WINDOW_MAX_MS}]). ` +
+            `Reply text: ${JSON.stringify(firstReply.text.slice(0, 200))}.`,
+        ).toBeGreaterThanOrEqual(SOFT_WINDOW_MIN_MS);
+        expect(
+          elapsed,
+          `first bot reply lands at ${elapsed}ms — above ${SOFT_WINDOW_MAX_MS}ms ` +
+            `ceiling. Either silence-poke wire is broken (poke armed but ` +
+            `not drained at gateway.ts:onToolCall) or the framework ` +
+            `fallback at 300s was the first thing to break silence. ` +
+            `Reply text: ${JSON.stringify(firstReply.text.slice(0, 200))}.`,
+        ).toBeLessThanOrEqual(SOFT_WINDOW_MAX_MS);
+
+        // Sanity floor: the first reply should be brief — proves it's
+        // a poke-driven update, not the final "done" answer after all
+        // three sleeps finished naturally. ~400 char ceiling allows a
+        // verbose model to add a sentence of context. Bump this if it
+        // flakes on perfectly valid short answers.
+        if (firstReply.text.length > 400) {
+          console.warn(
+            `[silence-poke] first reply at ${elapsed}ms is ${firstReply.text.length} ` +
+              `chars — longer than expected for a poke-driven update. The ` +
+              `window assertion still passed, but consider whether the model ` +
+              `bypassed the silence stretch (e.g. ran the sleeps in one ` +
+              `Bash call, dodging the per-call result poke chokepoint).`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    240_000,
+  );
+});

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

@@ -0,0 +1,95 @@
+/**
+ * Silent-end recovery scenario — the regression PR3 (#1126) introduced
+ * and PR1129 fixed.
+ *
+ * The bug: PR3 deleted the progress-card driver, and with it the
+ * `onSilentEnd` callback that wrote
+ * $TELEGRAM_STATE_DIR/silent-end-pending.json. The Stop hook
+ * (`silent-end-interrupt-stop.mjs`) reads that file to decide whether
+ * to block-and-re-prompt. With the writer gone, the hook always read
+ * "no silent-end pending" and allowed the stop. The model would
+ * produce an answer in its CLI session but never call `reply`, and
+ * the user got nothing back.
+ *
+ * This UAT exercises the outcome side directly: send a DM that
+ * SHOULD produce a reply, assert that a reply lands within a budget
+ * that covers (a) normal turn latency, (b) one Stop-hook re-prompt
+ * cycle (the agent goes silent → hook blocks → re-prompted → calls
+ * reply), and (c) worst-case framework fallback at 5 min.
+ *
+ * Why this scenario specifically:
+ * - The bug surfaced as "user gets no reply at all." The most
+ *   defensible UAT assertion is "after asking, the user gets SOME
+ *   reply within a reasonable bound." Anything that breaks this
+ *   contract — silent-end gap, scaffold staleness, hook misconfig,
+ *   gateway crash — fails this test.
+ * - Unlike `smoke-dm-reply.test.ts` (trivial inbound, fast reply),
+ *   this scenario uses a tool-heavy prompt that pushes the model
+ *   into the silent-end zone (lots of tool churn, easy to forget to
+ *   call reply afterward). It's the actual JTBD-failure shape.
+ *
+ * Budget: 6 min outer, 5 min for the reply itself. Covers the
+ * 5-min framework fallback floor.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+// The prompt pushes the model into a tool-heavy state where it has
+// produced "an answer" internally but hasn't yet realised it must
+// surface that via `reply`. This is the shape of the gymbro
+// regression: the model did the work (cat, pip install, garmin-pull,
+// etc), produced a summary, then ended the turn without `reply`.
+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", () => {
+  it(
+    "user asks → agent always replies (the gymbro regression must not return)",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const { messageId: inboundId } = await sc.sendDM(TOOL_HEAVY_PROMPT);
+        expect(inboundId).toBeGreaterThan(0);
+
+        // The core assertion: SOMETHING comes back from the bot
+        // within 5min. That covers the worst case of the
+        // silent-end-recovery ladder:
+        //   t=0:    inbound
+        //   t<30s:  normal reply if all is well
+        //   t=75s:  silence-poke #1 fires (model re-prompted)
+        //   t=180s: silence-poke #2 fires
+        //   t=300s: framework fallback ("still working… (no update
+        //           from agent in 5 min)") fires from the gateway.
+        // If we still get nothing by 300s+slack the bug is back.
+        const reply = await sc.expectMessage(/\S/, {
+          from: "bot",
+          timeout: 320_000,
+        });
+
+        expect(reply.text.length).toBeGreaterThan(0);
+        expect(reply.senderUserId).toBe(sc.botUserId);
+
+        // Subtler regression catch: if the reply is the framework
+        // fallback wording ("still working… (no update from agent
+        // in N min)") that means the silent-end loop fired AND the
+        // model didn't recover. Acceptable outcome — the user got
+        // something — but a design-health alarm. Log it.
+        if (/no update from agent/i.test(reply.text)) {
+          console.warn(
+            `[silent-end-recovery] reply was the framework fallback — `
+            + `model never replied on its own. Reply text: ${JSON.stringify(reply.text.slice(0, 200))}`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // Outer budget = inner deadline (320s) + spinUp overhead
+    // (~12s mtcute connect + DEFAULT_SETTLE_MS) + headroom.
+    360_000,
+  );
+});

package/telegram-plugin/uat/scenarios/smoke-dm-reply.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Smoke scenario — driver DMs the test bot, bot replies.
+ *
+ * Part of: https://github.com/switchroom/switchroom/issues/866
+ *
+ * Runs against real Telegram. Requires:
+ *   - test-harness agent running (see uat/SETUP.md §5)
+ *   - TELEGRAM_API_ID / TELEGRAM_API_HASH / TELEGRAM_UAT_DRIVER_SESSION
+ *     in the env (operator script in SETUP.md §6)
+ *   - TELEGRAM_TEST_BOT_USERNAME (defaults to `meken_switchroom_test_bot`)
+ *
+ * Invoke via `bun run test:uat` from `telegram-plugin/`. Default
+ * `bun test` / vitest do NOT discover this file — see
+ * vitest.config.ts.
+ *
+ * This is intentionally the simplest possible end-to-end check —
+ * just confirms the DM round-trip works. Richer assertions
+ * (reactions, progress card, edits) roll in with #866 Phase 2b.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+const SMOKE_INBOUND = `uat-smoke ${new Date().toISOString()}`;
+
+describe("uat: DM round-trip smoke", () => {
+  it(
+    "driver DMs the test bot and observes a bot reply",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+
+      try {
+        await sc.sendDM(SMOKE_INBOUND);
+
+        // 90s wall-clock budget: tolerates one rate-limit retry on the
+        // bot side + a normal Claude turn. If the agent is healthy the
+        // reply arrives in <20s.
+        const reply = await sc.expectMessage(/.+/, {
+          from: "bot",
+          timeout: 90_000,
+        });
+
+        expect(reply.text.length).toBeGreaterThan(0);
+        expect(reply.senderUserId).toBe(sc.botUserId);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // Per-test budget — must exceed the 90s inner expectMessage
+    // deadline plus spinUp overhead (~3s mtcute connect +
+    // DEFAULT_SETTLE_MS gap + unpin), so add ~12s of headroom on top
+    // for symmetry with progress-card-dm. bun:test's default of 5s
+    // would otherwise cut the test off on any turn that takes longer
+    // than a few seconds.
+    110_000,
+  );
+});

package/telegram-plugin/uat/scenarios/subagent-watcher-no-rerun-dm.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Issue #1116 — subagent-watcher must not re-fire "✓ Worker done"
+ * after the terminal-cleanup grace window elapses.
+ *
+ * Pre-fix repro (validated by RCA on `clerk` DM, 2026-05-12): once a
+ * background sub-agent completed, `cleanupTerminalAgent` ran ~30s
+ * later, deleting the agent's filePath from `knownFiles` and its row
+ * from `registry`. The JSONL itself stayed on disk, so the next
+ * `rescanSubagentDirs` poll rediscovered it, re-registered the agent
+ * with `completionNotified=false`, read the terminal `turn_duration`
+ * line, and emitted a fresh `✓ Worker done: …` notification. The loop
+ * ran indefinitely — operator saw the same 4 sub-agents (30/2/15/105
+ * tools) re-announcing completion every ~6 minutes.
+ *
+ * Post-fix invariant: each completed sub-agent emits exactly ONE
+ * `✓ Worker done` notification for the lifetime of the gateway.
+ *
+ * As a side-benefit, this scenario also catches the original RFC's
+ * "raw HTML tags rendered in card text" symptom (Bug C in the RCA):
+ * any bot message containing a literal `<b>` / `<i>` / `<code>`
+ * substring during the window is flagged. The watcher's own
+ * notification path is HTML-correct on `main`, so this assertion is
+ * a regression detector — if a future change starts leaking raw
+ * tags via a fall-through send site, this scenario goes red.
+ *
+ * Requires the same env as the other DM scenarios (see SETUP.md §6)
+ * and the test-harness override `progress_card.delay_ms: 1000` so a
+ * short DM turn actually pins a card (SETUP.md §5).
+ *
+ * Time budget: the bg sub-agent does two ~10s sleeps (~20s total)
+ * + we listen for an extra 75s post-completion (>30s grace +
+ * generous rescan slack) to catch a rerun. Plus parent-turn ack
+ * latency and Telegram-edit settle. Outer cap 240s.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+// Same Option-1 explicit-dispatch prompt as bg-sub-agent-dispatch-dm.test.ts
+// — naming the tool + run_in_background flag keeps the model
+// deterministic. The inner sleeps are shorter here (3×10s = ~30s
+// background phase) so the outer budget stays sane: we only need
+// the sub-agent to *complete* once. The duplicate-detection window
+// is what makes the test meaningful, not the bg phase duration.
+const BG_DISPATCH_PROMPT =
+  `Use the Agent tool with subagent_type "general-purpose" and ` +
+  `run_in_background: true to dispatch a worker with this exact task: ` +
+  `"Run \`sleep 10\` via the Bash tool, then \`echo step1\`, then ` +
+  `\`sleep 10\` again, then \`echo step2\`, then \`echo done\`. ` +
+  `That's two separate Bash sleeps and three echoes." After ` +
+  `dispatching, send a brief reply saying you've kicked off the ` +
+  `background worker so I can watch the progress card.`;
+
+const WORKER_DONE_RE = /✓\s*Worker done/;
+const RAW_HTML_TAG_RE = /<\/?(b|i|code|pre|strong|em)>/i;
+
+describe("uat: issue #1116 — subagent-watcher does not re-fire Worker done", () => {
+  it(
+    "emits exactly one ✓ Worker done per bg sub-agent and no raw HTML leaks",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        await sc.sendDM(BG_DISPATCH_PROMPT);
+
+        // Wait for the bg sub-agent to complete — the watcher's
+        // `✓ Worker done: …` notification is what we're locking
+        // behaviour around. Generous timeout: parent ack + bg sleeps
+        // + completion plumbing.
+        const firstDone = await sc.expectMessage(WORKER_DONE_RE, {
+          from: "bot",
+          timeout: 120_000,
+        });
+        expect(firstDone.text).toMatch(WORKER_DONE_RE);
+
+        // Snapshot bot-side messages observed after the first done.
+        // Pre-fix the same notification re-fired every ~30s
+        // (TERMINAL_CLEANUP_GRACE_MS + rescan). 75s gives us a
+        // comfortable >2 grace windows worth of observation.
+        const collected: Array<{ text: string; messageId: number }> = [];
+        const observer = sc.driver
+          .observeMessages(sc.botUserId)
+          [Symbol.asyncIterator]();
+        const deadline = Date.now() + 75_000;
+        try {
+          while (Date.now() < deadline) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) break;
+            const winner = await Promise.race([
+              observer.next(),
+              new Promise<{ value?: undefined; done: true }>((resolve) =>
+                setTimeout(() => resolve({ done: true }), remaining),
+              ),
+            ]);
+            if (winner.done) break;
+            const msg = winner.value;
+            if (!msg) continue;
+            // Only count bot-sent messages (filter out anything the
+            // driver itself echoed in this window).
+            if (msg.fromUserId === sc.driverUserId) continue;
+            collected.push({ text: msg.text ?? "", messageId: msg.messageId });
+          }
+        } finally {
+          // Closing the iterator unregisters the mtcute listeners.
+          await observer.return?.();
+        }
+
+        // Invariant 1: no DUPLICATE Worker-done with the same shape
+        // as the first one. We compare text rather than message_id
+        // because the bug emits FRESH messages (not edits), so each
+        // re-fire has a new message_id but identical text.
+        const reruns = collected.filter((m) => WORKER_DONE_RE.test(m.text));
+        expect(
+          reruns,
+          `Expected zero re-fires of "Worker done" in the ${75}s post-completion window, got ${reruns.length}: ${JSON.stringify(reruns.slice(0, 4).map((r) => r.text.slice(0, 80)))}`,
+        ).toHaveLength(0);
+
+        // Invariant 2: no raw HTML tags in any bot text — including
+        // the original `firstDone` notification. Catches Bug C
+        // (RCA's third symptom) as a regression detector.
+        const allBotTexts = [firstDone.text, ...collected.map((m) => m.text)];
+        for (const text of allBotTexts) {
+          expect(
+            text,
+            `Raw HTML tag leaked into bot text: ${text.slice(0, 120)}`,
+          ).not.toMatch(RAW_HTML_TAG_RE);
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // Outer budget: 120s wait-for-done + 75s observation window +
+    // ~12s spinUp settle + slack. Round up.
+    240_000,
+  );
+});