switchroom 0.5.0

package/telegram-plugin/tests/silent-reply-guard.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it, vi } from 'vitest'
+
+// Import directly from the helper module (not server.js), so this test
+// doesn't boot the full MCP server — server.ts has top-level side
+// effects (env load, TELEGRAM_BOT_TOKEN check, session-tail spawn) that
+// kill the test process when run under bun-test without a real env.
+import { guardSilentReply, isSilentReplyMarker } from '../silent-reply.js'
+
+/**
+ * Regression coverage for sprint1 review finding #6: the reply /
+ * stream_reply tool handlers must call `assertAllowedChat(chat_id)`
+ * BEFORE returning the silent-reply ack, so an unauthorised chat
+ * cannot bypass the outbound allowlist by having the agent emit
+ * `NO_REPLY` / `HEARTBEAT_OK`.
+ *
+ * We exercise the extracted `guardSilentReply` helper directly rather
+ * than the full MCP tool handler; the handler scaffolding (IPC + Bot
+ * harness + history DB) is heavy, and the ordering contract — "assert
+ * first, then ack" — lives entirely inside the helper.
+ */
+describe('guardSilentReply — allowlist ordering', () => {
+  it('asserts the allowlist BEFORE returning a silent ack (NO_REPLY)', () => {
+    const assertAllowed = vi.fn()
+    const result = guardSilentReply({
+      chat_id: '123',
+      text: 'NO_REPLY',
+      hasFiles: false,
+      assertAllowed,
+    })
+    expect(assertAllowed).toHaveBeenCalledOnce()
+    expect(assertAllowed).toHaveBeenCalledWith('123')
+    expect(result).toEqual({ kind: 'silent', markerText: 'NO_REPLY' })
+  })
+
+  it('recognises HEARTBEAT_OK as a silent marker and still gates on allowlist', () => {
+    const assertAllowed = vi.fn()
+    const result = guardSilentReply({
+      chat_id: '456',
+      text: '  heartbeat_ok  ',
+      hasFiles: false,
+      assertAllowed,
+    })
+    expect(assertAllowed).toHaveBeenCalledWith('456')
+    expect(result).toEqual({ kind: 'silent', markerText: 'heartbeat_ok' })
+  })
+
+  it('throws (does NOT return a silent ack) when the chat is disallowed', () => {
+    // This is the exact bypass the fix prevents: an unauthorised chat_id
+    // using NO_REPLY must NOT receive a successful silent-reply ack.
+    const assertAllowed = vi.fn((chat_id: string) => {
+      throw new Error(`chat ${chat_id} is not allowlisted`)
+    })
+    expect(() =>
+      guardSilentReply({
+        chat_id: '999',
+        text: 'NO_REPLY',
+        hasFiles: false,
+        assertAllowed,
+      }),
+    ).toThrow(/not allowlisted/)
+    expect(assertAllowed).toHaveBeenCalledOnce()
+  })
+
+  it('does not short-circuit (or call assertAllowed) when files are attached', () => {
+    // Silent-reply semantics are text-only; a NO_REPLY payload with files
+    // is a real send and must flow through the normal allowlist path
+    // inside the send codepath, not the silent short-circuit.
+    const assertAllowed = vi.fn()
+    const result = guardSilentReply({
+      chat_id: '123',
+      text: 'NO_REPLY',
+      hasFiles: true,
+      assertAllowed,
+    })
+    expect(assertAllowed).not.toHaveBeenCalled()
+    expect(result).toEqual({ kind: 'continue' })
+  })
+
+  it('does not short-circuit for normal prose that merely mentions the marker', () => {
+    const assertAllowed = vi.fn()
+    const result = guardSilentReply({
+      chat_id: '123',
+      text: 'the agent suggested NO_REPLY earlier',
+      hasFiles: false,
+      assertAllowed,
+    })
+    expect(assertAllowed).not.toHaveBeenCalled()
+    expect(result).toEqual({ kind: 'continue' })
+  })
+
+  it('does not short-circuit on undefined/empty text', () => {
+    const assertAllowed = vi.fn()
+    expect(
+      guardSilentReply({
+        chat_id: '123',
+        text: undefined,
+        hasFiles: false,
+        assertAllowed,
+      }),
+    ).toEqual({ kind: 'continue' })
+    expect(
+      guardSilentReply({
+        chat_id: '123',
+        text: '',
+        hasFiles: false,
+        assertAllowed,
+      }),
+    ).toEqual({ kind: 'continue' })
+    expect(assertAllowed).not.toHaveBeenCalled()
+  })
+
+  // Sanity: the helper the guard delegates to is exported for direct
+  // marker-recognition testing. Keep a thin smoke assertion so future
+  // marker-set tweaks break here rather than at the ordering layer.
+  it('isSilentReplyMarker recognises the documented marker set', () => {
+    expect(isSilentReplyMarker('NO_REPLY')).toBe(true)
+    expect(isSilentReplyMarker('HEARTBEAT_OK')).toBe(true)
+    expect(isSilentReplyMarker('no_reply')).toBe(true)
+    expect(isSilentReplyMarker('hello')).toBe(false)
+    expect(isSilentReplyMarker(undefined)).toBe(false)
+  })
+})

package/telegram-plugin/tests/slot-banner-driver.e2e.test.ts

@@ -0,0 +1,350 @@
+/**
+ * End-to-end tests for the slot-banner driver (#421).
+ *
+ * Drives `refreshBanner` against the chat-model-tracking
+ * `fake-bot-api` so we lock in the actual Bot API call sequence the
+ * gateway emits — not just the pure decision in `slot-banner.ts`.
+ *
+ * Each test walks one transition (no-banner → pinned, pinned → edited,
+ * pinned → unpinned) and asserts both the call shape and the returned
+ * BannerState the gateway will hold for the next refresh.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { refreshBanner } from '../slot-banner-driver.js';
+import type { BannerState } from '../slot-banner.js';
+import { createFakeBotApi, errors, type FakeBot } from './fake-bot-api.js';
+
+const OWNER = 'chat-owner';
+const AGENT = 'clerk';
+const DEFAULT = 'default';
+
+let bot: FakeBot;
+
+beforeEach(() => {
+  bot = createFakeBotApi({ startMessageId: 100 });
+});
+
+describe('refreshBanner — transitions from clean state', () => {
+  it('on default slot with no prior state, does nothing (no API calls, returns null)', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: DEFAULT,
+      defaultSlot: DEFAULT,
+      prevState: null,
+    });
+    expect(next).toBeNull();
+    expect(bot.api.sendMessage).not.toHaveBeenCalled();
+    expect(bot.api.pinChatMessage).not.toHaveBeenCalled();
+  });
+
+  it('on null active slot (failed to read), treats as default — no banner', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: null,
+      defaultSlot: DEFAULT,
+      prevState: null,
+    });
+    expect(next).toBeNull();
+    expect(bot.api.sendMessage).not.toHaveBeenCalled();
+  });
+
+  it('on non-default slot with no prior state, sends + pins, returns state', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: null,
+    });
+    expect(next).not.toBeNull();
+    expect(next?.slot).toBe('personal');
+    expect(next?.messageId).toBe(100);
+    // sendMessage + pinChatMessage called in that order.
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1);
+    expect(bot.api.pinChatMessage).toHaveBeenCalledTimes(1);
+    const sendArgs = bot.api.sendMessage.mock.calls[0];
+    expect(sendArgs[0]).toBe(OWNER);
+    expect(sendArgs[1]).toContain('clerk');
+    expect(sendArgs[1]).toContain('personal');
+    // Pin call should disable notifications so users don't get pinged.
+    const pinArgs = bot.api.pinChatMessage.mock.calls[0];
+    expect(pinArgs[2]).toMatchObject({ disable_notification: true });
+    // Chat model also reflects the pin.
+    expect(bot.isPinned(OWNER, 100)).toBe(true);
+  });
+});
+
+describe('refreshBanner — transitions from pinned state', () => {
+  // Seed the chat model with a real pin (matches gateway's first-pin path),
+  // then run subsequent transitions against it. Avoids the fake-bot's
+  // realistic "edit on unknown message_id throws not-found" behaviour
+  // that would fire if we hand-rolled a BannerState referencing an id
+  // the fake never saw.
+  let prior: BannerState;
+  beforeEach(async () => {
+    const seeded = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: null,
+    });
+    if (!seeded) throw new Error('failed to seed prior state');
+    prior = seeded;
+    // Reset the spy counts so the under-test transition starts from zero.
+    bot.api.sendMessage.mockClear();
+    bot.api.editMessageText.mockClear();
+    bot.api.pinChatMessage.mockClear();
+    bot.api.unpinChatMessage.mockClear();
+  });
+
+  it('same slot is a noop (no API calls, state preserved)', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: prior,
+    });
+    expect(next).toEqual(prior);
+    expect(bot.api.sendMessage).not.toHaveBeenCalled();
+    expect(bot.api.editMessageText).not.toHaveBeenCalled();
+    expect(bot.api.unpinChatMessage).not.toHaveBeenCalled();
+  });
+
+  it('different non-default slot edits in place, advances state', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'work',
+      defaultSlot: DEFAULT,
+      prevState: prior,
+    });
+    expect(next).toEqual({ messageId: prior.messageId, slot: 'work' });
+    expect(bot.api.editMessageText).toHaveBeenCalledTimes(1);
+    expect(bot.api.sendMessage).not.toHaveBeenCalled();
+    const editArgs = bot.api.editMessageText.mock.calls[0];
+    expect(editArgs[0]).toBe(OWNER);
+    expect(editArgs[1]).toBe(prior.messageId);
+    expect(editArgs[2]).toContain('work');
+  });
+
+  it('return to default slot unpins, clears state', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: DEFAULT,
+      defaultSlot: DEFAULT,
+      prevState: prior,
+    });
+    expect(next).toBeNull();
+    expect(bot.api.unpinChatMessage).toHaveBeenCalledTimes(1);
+    expect(bot.api.unpinChatMessage.mock.calls[0]).toEqual([OWNER, prior.messageId]);
+  });
+
+  it('null active slot (failure to read) also unpins', async () => {
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: null,
+      defaultSlot: DEFAULT,
+      prevState: prior,
+    });
+    expect(next).toBeNull();
+    expect(bot.api.unpinChatMessage).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('refreshBanner — full lifecycle (sequenced)', () => {
+  it('walks no-banner → personal → work → default → noop', async () => {
+    let state: BannerState | null = null;
+
+    // 1. Initial — quota fired, swapped to personal.
+    state = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: state,
+    });
+    expect(state?.slot).toBe('personal');
+
+    // 2. Slot moved again (manual /auth use work).
+    state = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'work',
+      defaultSlot: DEFAULT,
+      prevState: state,
+    });
+    expect(state?.slot).toBe('work');
+    expect(state?.messageId).toBe(100); // edited in place, same id
+
+    // 3. Operator returned to default.
+    state = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: DEFAULT,
+      defaultSlot: DEFAULT,
+      prevState: state,
+    });
+    expect(state).toBeNull();
+
+    // 4. Repeat default → still noop.
+    state = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: DEFAULT,
+      defaultSlot: DEFAULT,
+      prevState: state,
+    });
+    expect(state).toBeNull();
+
+    // Final tally on the chat model.
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1);
+    expect(bot.api.editMessageText).toHaveBeenCalledTimes(1);
+    expect(bot.api.unpinChatMessage).toHaveBeenCalledTimes(1);
+    expect(bot.api.pinChatMessage).toHaveBeenCalledTimes(1);
+    // After unpin, isPinned returns false.
+    expect(bot.isPinned(OWNER, 100)).toBe(false);
+  });
+});
+
+describe('refreshBanner — error paths', () => {
+  it('pinChatMessage failure after sendMessage success preserves prior state', async () => {
+    // Why: gateway must not claim a message_id it never managed to pin —
+    // the next refresh would think a banner exists and try to edit it.
+    bot.faults.next('pinChatMessage', errors.badRequest('chat not found', 'pinChatMessage'));
+    const onError = vi.fn();
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: null,
+      onError,
+    });
+    expect(next).toBeNull(); // prior state was null, preserved
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1);
+    expect(bot.api.pinChatMessage).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith('pin', expect.any(Error));
+  });
+
+  it('sendMessage failure surfaces but does not throw', async () => {
+    bot.faults.next('sendMessage', errors.forbidden('sendMessage'));
+    const onError = vi.fn();
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: null,
+      onError,
+    });
+    expect(next).toBeNull();
+    expect(onError).toHaveBeenCalledWith('pin', expect.any(Error));
+    // pinChatMessage never reached because sendMessage failed first.
+    expect(bot.api.pinChatMessage).not.toHaveBeenCalled();
+  });
+
+  it('editMessageText failure preserves prior state (next refresh tries again)', async () => {
+    const PRIOR: BannerState = { messageId: 7, slot: 'personal' };
+    bot.faults.next('editMessageText', errors.messageToEditNotFound());
+    const onError = vi.fn();
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'work',
+      defaultSlot: DEFAULT,
+      prevState: PRIOR,
+      onError,
+    });
+    expect(next).toEqual(PRIOR); // unchanged
+    expect(onError).toHaveBeenCalledWith('edit', expect.any(Error));
+  });
+
+  it('unpinChatMessage failure still drops the claim (returns null)', async () => {
+    // Out-of-band unpin (operator did it) is the most common cause —
+    // re-pinning would surprise the user.
+    const PRIOR: BannerState = { messageId: 7, slot: 'personal' };
+    bot.faults.next('unpinChatMessage', errors.badRequest('message to unpin not found', 'unpinChatMessage'));
+    const onError = vi.fn();
+    const next = await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: DEFAULT,
+      defaultSlot: DEFAULT,
+      prevState: PRIOR,
+      onError,
+    });
+    expect(next).toBeNull();
+    expect(onError).toHaveBeenCalledWith('unpin', expect.any(Error));
+  });
+});
+
+describe('refreshBanner — banner content', () => {
+  it('contains agent name, current slot, and failover-from default', async () => {
+    await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: 'klanker',
+      currentSlot: 'backup',
+      defaultSlot: 'default',
+      prevState: null,
+    });
+    const text = bot.api.sendMessage.mock.calls[0][1] as string;
+    expect(text).toContain('klanker');
+    expect(text).toContain('backup');
+    expect(text).toContain('default');
+    expect(text.toLowerCase()).toMatch(/failover/);
+  });
+
+  it('escapes HTML in agent and slot names (no XSS via slot rename)', async () => {
+    await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: '<bad>',
+      currentSlot: '"hax"',
+      defaultSlot: '&def',
+      prevState: null,
+    });
+    const text = bot.api.sendMessage.mock.calls[0][1] as string;
+    expect(text).not.toContain('<bad>');
+    expect(text).toContain('&lt;bad&gt;');
+    expect(text).toContain('&quot;hax&quot;');
+    expect(text).toContain('&amp;def');
+  });
+
+  it('uses HTML parse_mode + disables link preview', async () => {
+    await refreshBanner({
+      bot,
+      ownerChatId: OWNER,
+      agentName: AGENT,
+      currentSlot: 'personal',
+      defaultSlot: DEFAULT,
+      prevState: null,
+    });
+    const opts = bot.api.sendMessage.mock.calls[0][2] as Record<string, unknown>;
+    expect(opts.parse_mode).toBe('HTML');
+    expect(opts.link_preview_options).toEqual({ is_disabled: true });
+  });
+});

package/telegram-plugin/tests/slot-banner.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { decideBannerAction, formatBannerHtml, type BannerState } from '../slot-banner';
+
+const DEFAULT = 'default';
+
+describe('decideBannerAction — default state', () => {
+  it('noop when on default and nothing pinned', () => {
+    const action = decideBannerAction(null, DEFAULT, 'clerk', DEFAULT);
+    expect(action.kind).toBe('noop');
+  });
+
+  it('noop when slot is null and nothing pinned', () => {
+    const action = decideBannerAction(null, null, 'clerk', DEFAULT);
+    expect(action.kind).toBe('noop');
+  });
+
+  it('unpins existing banner when slot returns to default', () => {
+    const prev: BannerState = { messageId: 42, slot: 'personal' };
+    const action = decideBannerAction(prev, DEFAULT, 'clerk', DEFAULT);
+    expect(action).toEqual({ kind: 'unpin', messageId: 42 });
+  });
+
+  it('unpins existing banner when active slot becomes null', () => {
+    const prev: BannerState = { messageId: 7, slot: 'work' };
+    const action = decideBannerAction(prev, null, 'clerk', DEFAULT);
+    expect(action).toEqual({ kind: 'unpin', messageId: 7 });
+  });
+});
+
+describe('decideBannerAction — non-default state', () => {
+  it('pins fresh banner when nothing currently pinned', () => {
+    const action = decideBannerAction(null, 'personal', 'clerk', DEFAULT);
+    expect(action.kind).toBe('pin');
+    if (action.kind === 'pin') {
+      expect(action.slot).toBe('personal');
+      expect(action.text).toContain('clerk');
+      expect(action.text).toContain('personal');
+      expect(action.text).toContain('default');
+    }
+  });
+
+  it('edits when banner exists for a different slot', () => {
+    const prev: BannerState = { messageId: 99, slot: 'personal' };
+    const action = decideBannerAction(prev, 'work', 'clerk', DEFAULT);
+    expect(action.kind).toBe('edit');
+    if (action.kind === 'edit') {
+      expect(action.messageId).toBe(99);
+      expect(action.slot).toBe('work');
+      expect(action.text).toContain('work');
+    }
+  });
+
+  it('noops when banner already reflects current slot', () => {
+    const prev: BannerState = { messageId: 12, slot: 'personal' };
+    const action = decideBannerAction(prev, 'personal', 'clerk', DEFAULT);
+    expect(action.kind).toBe('noop');
+  });
+});
+
+describe('formatBannerHtml', () => {
+  it('escapes HTML in agent and slot names', () => {
+    const text = formatBannerHtml('<bad>', '"hax"', '&def');
+    expect(text).not.toContain('<bad>');
+    expect(text).toContain('&lt;bad&gt;');
+    expect(text).toContain('&quot;hax&quot;');
+    expect(text).toContain('&amp;def');
+  });
+
+  it('mentions the failover-from default for context', () => {
+    const text = formatBannerHtml('clerk', 'personal', 'default');
+    expect(text).toMatch(/failover from/i);
+    expect(text).toContain('default');
+  });
+});

package/telegram-plugin/tests/snapshot-serializer.ts

@@ -0,0 +1,79 @@
+/**
+ * Normalizing serializer for HTML / progress-card snapshot tests.
+ *
+ * Problem: the raw progress-card render contains
+ *   - elapsed-time strings like "12s elapsed" / "1m34s"
+ *   - ISO timestamps like "2026-04-18T12:34:56.789Z"
+ *   - message-ids, toolUseIds, runtime-generated UUIDs
+ *
+ * Any of these flip on every test run, so a naive snapshot rots the
+ * moment it lands. This serializer canonicalizes those fields to stable
+ * tokens (`<ELAPSED>`, `<TIME>`, `<ID>`, `<TOOL_USE_ID>`) so the
+ * snapshot diff reflects *semantic* changes only.
+ *
+ * Use by passing `snapshotSerializer` to vitest's `expect.addSnapshotSerializer`
+ * in a test's `beforeAll`, or globally via `vitest.config.ts`
+ * (`test.snapshotSerializers`).
+ */
+
+const PATTERNS: Array<{ re: RegExp; replacement: string }> = [
+  // ISO8601 timestamps
+  { re: /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z\b/g, replacement: '<TIME>' },
+  // Unix seconds (10 digits) — only within JSON-like contexts, prefixed by `date":` or `"date":`
+  { re: /"date"\s*:\s*\d{10}\b/g, replacement: '"date":<UNIX_SEC>' },
+  // Elapsed-time strings rendered by progress-card (hhh? mm ss).
+  // Match "NNs elapsed", "NNmNNs", "NNhNNm".
+  { re: /\b\d+m\d+s\b/g, replacement: '<ELAPSED>' },
+  { re: /\b\d+h\d+m\b/g, replacement: '<ELAPSED>' },
+  { re: /\b\d+s\s+elapsed\b/g, replacement: '<ELAPSED> elapsed' },
+  // Claude Code tool_use ids: `toolu_01ABC...` (base62, 20+ chars).
+  { re: /\btoolu_[A-Za-z0-9_]{10,}\b/g, replacement: '<TOOL_USE_ID>' },
+  // grammy/telegram file_ids: long alphanumerics starting with AgACAgI / BQACAgI etc.
+  { re: /\b(?:AgAC|BQAC|CQAC|DQAC)[A-Za-z0-9_-]{10,}\b/g, replacement: '<FILE_ID>' },
+  // UUIDs
+  { re: /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/g, replacement: '<UUID>' },
+]
+
+/**
+ * Apply all normalizing replacements. Safe to call on any string —
+ * non-matching content passes through unchanged.
+ */
+export function normalizeSnapshot(input: string): string {
+  let out = input
+  for (const { re, replacement } of PATTERNS) {
+    out = out.replace(re, replacement)
+  }
+  return out
+}
+
+/**
+ * Vitest snapshot serializer compatible with `expect.addSnapshotSerializer`.
+ *
+ * Only applies to string values that clearly look like HTML / Telegram
+ * rendered content. Everything else passes through without interference
+ * so we don't accidentally mangle unrelated assertions.
+ */
+export const snapshotSerializer = {
+  test(val: unknown): boolean {
+    if (typeof val !== 'string') return false
+    // Cheap pre-filter: only normalize when at least one pattern would hit.
+    for (const { re } of PATTERNS) {
+      re.lastIndex = 0
+      if (re.test(val)) {
+        re.lastIndex = 0
+        return true
+      }
+      re.lastIndex = 0
+    }
+    return false
+  },
+  serialize(val: unknown): string {
+    return JSON.stringify(normalizeSnapshot(val as string))
+  },
+}
+
+/** Convenience: normalize + stringify with stable indent. Good for
+ *  inline-snapshot-style assertions without invoking the serializer. */
+export function stableHtmlSnapshot(html: string): string {
+  return normalizeSnapshot(html)
+}

package/telegram-plugin/tests/spawn-detached-cgroup-escape.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Regression test for #177: detached spawns from the gateway must escape
+ * the gateway's cgroup so a gateway restart (kicked off by the same
+ * detached child as part of /new or auto-failover) doesn't cgroup-kill
+ * the child mid-flight before it can reach the second systemctl call.
+ *
+ * The fix wraps every spawn through `systemd-run --user --scope --collect`
+ * when systemd-run is available, falling back to direct spawn on hosts
+ * without it (dev containers, CI without systemd-user).
+ *
+ * This is a structural source-grep test rather than a runtime exercise
+ * because spawnSwitchroomDetached isn't exported and exercising the
+ * actual cgroup behaviour requires a real systemd session.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const TEST_DIR = resolve(fileURLToPath(import.meta.url), '..')
+const REPO_ROOT = resolve(TEST_DIR, '..', '..')
+
+describe('spawnSwitchroomDetached cgroup-escape (#177)', () => {
+  const src = readFileSync(
+    join(REPO_ROOT, 'telegram-plugin/gateway/gateway.ts'),
+    'utf-8',
+  )
+
+  it('declares a resolveSystemdRunPath helper', () => {
+    expect(src).toContain('function resolveSystemdRunPath(')
+  })
+
+  it('uses --scope --collect via systemd-run when available', () => {
+    expect(src).toContain("'--user', '--scope', '--collect'")
+  })
+
+  it('uses --quiet so the wrapper does not log a banner per spawn', () => {
+    expect(src).toMatch(/'--user',\s*'--scope',\s*'--collect',\s*'--quiet'/)
+  })
+
+  it('falls back to direct spawn when systemd-run is unavailable', () => {
+    // The fallback path should still pass SWITCHROOM_CLI as the spawn
+    // binary; the systemd-run path adds it as an arg via `--`.
+    expect(src).toMatch(/spawnBin\s*=\s*systemdRun\s*\?\?\s*SWITCHROOM_CLI/)
+  })
+
+  it('caches the resolution per process (no command -v on every spawn)', () => {
+    expect(src).toContain('let _systemdRunPath')
+    expect(src).toMatch(/if\s*\(_systemdRunPath\s*!==\s*undefined\)\s*return/)
+  })
+})