switchroom 0.19.48 → 0.20.0

package/telegram-plugin/gateway/buzz-mirror.ts

@@ -0,0 +1,329 @@
+/**
+ * Buzz co-channel — Phase 2b hub-side mirror module.
+ *
+ * This is the gateway-side half of "the part that actually sends". It sits
+ * strictly DOWNSTREAM of a successful Telegram delivery: `sendReply` calls
+ * `mirrorReplyDelivered(...)` only AFTER the Telegram copy has landed, and
+ * `executeEditMessage` calls `mirrorCorrection(...)` after a Telegram edit
+ * lands. Every Buzz publish is fire-and-forget — a failure or absence of the
+ * Buzz peer NEVER fails, delays, or retries the Telegram answer (the core
+ * invariant). There is no agent-facing Buzz-only send path: the ONLY way a
+ * Buzz event is ever emitted is as a mirror of an already-delivered Telegram
+ * message.
+ *
+ * Content signing lives in the sidecar (`src/buzz-gateway/publisher.ts`, the
+ * sole content-signer, S3). The hub only decides ROUTE + OWNER SAFETY and hands
+ * already-Telegram-scrubbed text (layer-1 redaction, via `normalizeOutboundBody`
+ * upstream) to the peer as an `outbound_to_buzz` request; the sidecar re-scrubs
+ * through `detectSecrets` (layer-2) before it ever reaches `finalizeEvent`.
+ *
+ * Dark by default: `getBuzzMirror()` returns null until `initBuzzMirror(...)`
+ * is called, which the gateway does ONLY when `channels.buzz.enabled === true`.
+ * With Buzz disabled the hook sites are `getBuzzMirror()?.…` — a byte-identical
+ * no-op on the hot path.
+ */
+
+import { randomUUID } from "crypto";
+import type { OutboundToBuzzMessage } from "./ipc-protocol.js";
+import {
+  resolveRoute,
+  isBuzzThreadedPublishSafe,
+  parseConfiguredMirrorMode,
+  type BuzzCoords,
+  type Channel,
+} from "./channel-route.js";
+
+export type BuzzPeerSender = (msg: OutboundToBuzzMessage) => boolean;
+
+export interface BuzzMirrorConfig {
+  /** Configured mode, ALREADY narrowed to both|off (S2) by the caller. */
+  mode: "both" | "off";
+  /** This gateway's agent name — stamped on every outbound_to_buzz. */
+  agentName: string;
+  /**
+   * The relay-minted group UUID a TELEGRAM-origin answer is mirrored to as a
+   * fresh top-level post (`channels.buzz.default_channel_id`). Empty string ⇒
+   * telegram-origin mirroring is disabled (no channel to post into); buzz-origin
+   * threaded replies still work (they carry their own channelId).
+   */
+  defaultChannelId: string;
+  /** Optional log sink (defaults to a no-op). */
+  log?: (msg: string) => void;
+}
+
+export interface MirrorReplyInput {
+  /** The answer text AFTER layer-1 Telegram scrub (normalizeOutboundBody). */
+  scrubbedText: string;
+  /** Resolved reply-owner turn's origin channel. */
+  ownerOriginChannel: Channel;
+  /** Owner turn's Buzz coordinates, when it originated on Buzz. */
+  ownerBuzzCoords?: BuzzCoords;
+  /** True IFF the reply positively echoed the owner turn's id (S1). */
+  ownerEchoed: boolean;
+  /** True IFF a live/recent turn of a DIFFERENT origin exists (S1). */
+  hasRecentDifferentOriginTurn: boolean;
+  /**
+   * `${chatId}:${messageId}` keys of the Telegram messages this answer was
+   * delivered as. Recorded so a later `edit_message` on any of them can find
+   * the published Buzz event to correct.
+   */
+  telegramMessageKeys: string[];
+}
+
+export interface MirrorCorrectionInput {
+  /** `${chatId}:${messageId}` of the edited Telegram message. */
+  telegramMessageKey: string;
+  /** The edit text AFTER layer-1 Telegram scrub. */
+  scrubbedText: string;
+}
+
+/** F6 — coalesce a burst of edits into a single correction event. */
+export const CORRECTION_DEBOUNCE_MS = 30_000;
+
+/** Bound the in-memory correlation / message maps (FIFO eviction). */
+const MAX_TRACKED = 4096;
+
+interface PendingPublish {
+  channelId: string;
+  telegramMessageKeys: string[];
+}
+
+class BuzzMirror {
+  private readonly cfg: BuzzMirrorConfig;
+  private readonly log: (msg: string) => void;
+  private sender: BuzzPeerSender | null = null;
+
+  /** correlationId → in-flight publish awaiting its buzz_publish_result. */
+  private readonly pending = new Map<string, PendingPublish>();
+  private readonly pendingOrder: string[] = [];
+
+  /** `${chatId}:${messageId}` → the published Buzz event it maps to. */
+  private readonly msgToBuzz = new Map<string, { eventId: string; channelId: string }>();
+  private readonly msgOrder: string[] = [];
+
+  /** `${chatId}:${messageId}` → live correction debounce timer. */
+  private readonly correctionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(cfg: BuzzMirrorConfig) {
+    this.cfg = cfg;
+    this.log = cfg.log ?? (() => {});
+  }
+
+  /** Register the transport to the duplex Buzz peer (ipcServer.sendToBuzzPeer). */
+  attachSender(sender: BuzzPeerSender): void {
+    this.sender = sender;
+  }
+
+  private evict<T>(map: Map<string, T>, order: string[]): void {
+    while (order.length > MAX_TRACKED) {
+      const k = order.shift();
+      if (k !== undefined) map.delete(k);
+    }
+  }
+
+  /**
+   * Mirror a just-delivered Telegram answer to Buzz, if the route calls for it
+   * and the owner binding is safe (S1). No-op when Buzz is not in the route.
+   * Never throws — a mirror failure must never disturb the Telegram answer.
+   */
+  mirrorReplyDelivered(input: MirrorReplyInput): void {
+    try {
+      // buzzEnabled is implied — this instance only exists when enabled.
+      const route = resolveRoute(input.ownerOriginChannel, this.cfg.mode, true);
+      const buzzInRoute =
+        route.primary === "buzz" || route.mirrors.includes("buzz");
+      if (!buzzInRoute) return;
+
+      let channelId: string;
+      let replyToEventId: string | undefined;
+      let threadRootId: string | undefined;
+
+      if (input.ownerOriginChannel === "buzz" && input.ownerBuzzCoords) {
+        // THREADED reply into an existing Buzz conversation — the ONLY path the
+        // S1 owner guard gates. Fail safe to Telegram-only on an ambiguous bind.
+        if (
+          !isBuzzThreadedPublishSafe({
+            ownerEchoed: input.ownerEchoed,
+            hasRecentDifferentOriginTurn: input.hasRecentDifferentOriginTurn,
+          })
+        ) {
+          this.log(
+            "buzz-mirror: S1 guard blocked a threaded publish on an ambiguous " +
+              "owner binding (un-echoed reply + a recent different-origin turn) " +
+              "— delivered Telegram-only",
+          );
+          return;
+        }
+        channelId = input.ownerBuzzCoords.channelId;
+        replyToEventId = input.ownerBuzzCoords.eventId;
+        threadRootId = input.ownerBuzzCoords.threadRoot;
+      } else {
+        // TELEGRAM-origin → fresh top-level post to the configured channel. Not
+        // an owner-bound thread, so the S1 guard does not apply (design §3.3).
+        if (!this.cfg.defaultChannelId) return; // no channel to post into
+        channelId = this.cfg.defaultChannelId;
+      }
+
+      this.publish(
+        {
+          channelId,
+          replyToEventId,
+          threadRootId,
+          payload: { kind: "message", text: input.scrubbedText },
+        },
+        input.telegramMessageKeys,
+      );
+    } catch (err) {
+      this.log(`buzz-mirror: mirrorReplyDelivered threw (ignored): ${String(err)}`);
+    }
+  }
+
+  /**
+   * Debounced correction: an `edit_message` on a Telegram message that was
+   * mirrored to Buzz publishes a superseding `correction` event 30s after the
+   * last edit (F6 CORRECTION_DEBOUNCE_MS). No-op when the edited message was
+   * never mirrored (no Buzz event to correct). Never throws.
+   */
+  mirrorCorrection(input: MirrorCorrectionInput): void {
+    try {
+      const target = this.msgToBuzz.get(input.telegramMessageKey);
+      if (!target) return; // this Telegram message was never mirrored to Buzz
+
+      const existing = this.correctionTimers.get(input.telegramMessageKey);
+      if (existing) clearTimeout(existing);
+
+      const timer = setTimeout(() => {
+        this.correctionTimers.delete(input.telegramMessageKey);
+        // Re-read: the mapping may have advanced (a later publish), but the
+        // targetEventId to supersede is the one current at fire time.
+        const t = this.msgToBuzz.get(input.telegramMessageKey);
+        if (!t) return;
+        this.publish(
+          {
+            channelId: t.channelId,
+            replyToEventId: t.eventId,
+            threadRootId: t.eventId,
+            payload: {
+              kind: "correction",
+              text: input.scrubbedText,
+              targetEventId: t.eventId,
+            },
+          },
+          [], // a correction is not itself re-correctable via a Telegram edit
+        );
+      }, CORRECTION_DEBOUNCE_MS);
+      if (typeof (timer as { unref?: () => void }).unref === "function") {
+        (timer as { unref: () => void }).unref();
+      }
+      this.correctionTimers.set(input.telegramMessageKey, timer);
+    } catch (err) {
+      this.log(`buzz-mirror: mirrorCorrection threw (ignored): ${String(err)}`);
+    }
+  }
+
+  /** Handle the sidecar's advisory publish outcome (buzz_publish_result). */
+  onPublishResult(msg: {
+    correlationId: string;
+    ok: boolean;
+    eventId?: string;
+    error?: string;
+  }): void {
+    const p = this.pending.get(msg.correlationId);
+    this.pending.delete(msg.correlationId);
+    if (!p) return;
+    if (!msg.ok || !msg.eventId) {
+      this.log(
+        `buzz-mirror: publish failed (correlationId=${msg.correlationId.slice(0, 8)}` +
+          `${msg.error ? ` error=${msg.error}` : ""}) — Telegram copy already delivered`,
+      );
+      return;
+    }
+    // Record the published event against each Telegram message it mirrored, so
+    // a later edit_message on any of them can target it for a correction.
+    for (const key of p.telegramMessageKeys) {
+      this.msgToBuzz.set(key, { eventId: msg.eventId, channelId: p.channelId });
+      this.msgOrder.push(key);
+    }
+    this.evict(this.msgToBuzz, this.msgOrder);
+  }
+
+  private publish(
+    fields: Omit<OutboundToBuzzMessage, "type" | "correlationId" | "agentName">,
+    telegramMessageKeys: string[],
+  ): void {
+    if (!this.sender) {
+      this.log("buzz-mirror: no Buzz peer connected — mirror dropped (Telegram copy delivered)");
+      return;
+    }
+    const correlationId = randomUUID();
+    const msg: OutboundToBuzzMessage = {
+      type: "outbound_to_buzz",
+      correlationId,
+      agentName: this.cfg.agentName,
+      ...fields,
+    };
+    const sent = this.sender(msg);
+    if (!sent) {
+      this.log("buzz-mirror: Buzz peer send returned false — mirror dropped (Telegram copy delivered)");
+      return;
+    }
+    this.pending.set(correlationId, {
+      channelId: fields.channelId,
+      telegramMessageKeys,
+    });
+    this.pendingOrder.push(correlationId);
+    this.evict(this.pending, this.pendingOrder);
+  }
+}
+
+let singleton: BuzzMirror | null = null;
+
+/**
+ * Initialize the hub mirror. Called by the gateway ONLY when
+ * `channels.buzz.enabled === true`. Idempotent-ish: a second call replaces the
+ * instance (used by tests). When never called, `getBuzzMirror()` stays null and
+ * every hook site is a no-op.
+ */
+export function initBuzzMirror(cfg: BuzzMirrorConfig): BuzzMirror {
+  singleton = new BuzzMirror(cfg);
+  return singleton;
+}
+
+export function getBuzzMirror(): BuzzMirror | null {
+  return singleton;
+}
+
+/**
+ * Boot the hub mirror from env at gateway startup — the single wiring seam the
+ * gateway calls. DARK BY DEFAULT and by construction: returns null (leaving
+ * `getBuzzMirror()` null, every hook site a no-op) unless BOTH hold —
+ *   (1) `BUZZ_ENABLED` is truthy, AND
+ *   (2) the S2-narrowed mode (`parseConfiguredMirrorMode`) is `both`;
+ *       a configured `origin`/`off` degrades to dark, never a half-live mirror.
+ * The Buzz env vars are UNSET everywhere in this branch (projection deferred),
+ * so in practice this is inert. `sender` is the transport to the duplex peer
+ * (`ipcServer.sendToBuzzPeer`). Returns the booted instance for tests.
+ */
+export function maybeBootBuzzMirror(
+  sender: BuzzPeerSender,
+  env: Record<string, string | undefined> = process.env,
+): BuzzMirror | null {
+  if (env.BUZZ_ENABLED !== "1" && env.BUZZ_ENABLED !== "true") return null;
+  const mode = parseConfiguredMirrorMode(env.BUZZ_MIRROR);
+  if (mode !== "both") return null;
+  const bm = initBuzzMirror({
+    mode,
+    agentName: env.SWITCHROOM_AGENT_NAME?.trim() ?? "",
+    defaultChannelId: env.BUZZ_CHANNEL_IDS?.trim() ?? "",
+    log: (m) => process.stderr.write(`telegram gateway: buzz-mirror — ${m}\n`),
+  });
+  bm.attachSender(sender);
+  return bm;
+}
+
+/** Test-only: tear down the singleton so cases don't leak state into each other. */
+export function __resetBuzzMirrorForTests(): void {
+  singleton = null;
+}
+
+export type { BuzzMirror };

package/telegram-plugin/gateway/buzz-type-guards.ts

@@ -0,0 +1,34 @@
+/**
+ * Buzz co-channel — compile-time type-identity guards (2a MINOR-3).
+ *
+ * `gateway.ts` INLINES the `CurrentTurn.buzzCoords` shape
+ * (`{ channelId; eventId; threadRoot }`) rather than importing the canonical
+ * `BuzzCoords` from `channel-route.ts`, purely to hold gateway.ts at its
+ * zero-headroom line-ratchet (switchroom#2996). That inlining is a drift hazard:
+ * nothing structurally ties the two shapes together, so an edit to one could
+ * silently diverge from the other.
+ *
+ * This file closes that hazard with a strict, invariant type-equality assertion
+ * that makes `tsc --noEmit` (the lint gate) FAIL the moment the shapes differ.
+ * Both imports are `import type` — fully erased at runtime, so this introduces
+ * NO runtime dependency and NO module-load side effect (in particular it does
+ * NOT load gateway.ts, which binds a UDS listener at import under prod). The
+ * file is imported by nothing; it exists only to be type-checked.
+ */
+
+import type { CurrentTurn } from "./gateway.js";
+import type { BuzzCoords } from "./channel-route.js";
+
+/**
+ * Invariant type equality: `true` IFF `A` and `B` are mutually assignable with
+ * identical `readonly`/optional modifiers (the `(<T>() => …)` wrapper defeats
+ * the bivariant/structural leniency a plain `extends` pair would allow).
+ */
+type TypeEq<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+
+// `buzzCoords` is optional on CurrentTurn; compare its PRESENT shape to the
+// canonical BuzzCoords. If these ever drift, `TypeEq<…>` becomes `false` and the
+// `= true` initializer is a hard `tsc` error — the intended build break.
+const _buzzCoordsIdentity: TypeEq<NonNullable<CurrentTurn["buzzCoords"]>, BuzzCoords> = true;
+void _buzzCoordsIdentity;

package/telegram-plugin/gateway/channel-route.ts

@@ -0,0 +1,272 @@
+/**
+ * Buzz co-channel — Phase 2a pure routing core.
+ *
+ * Two pure, side-effect-free (bar one fail-safe stderr breadcrumb) functions
+ * plus a flag reader. NO network sends, NO gateway state: this module is
+ * unit-testable without booting the gateway, mirroring the `chat-id-fallback.ts`
+ * pure-module precedent.
+ *
+ *   1. `parseChannelOrigin(rawContent)` — decides whether a turn originated on
+ *      Telegram or Buzz, purely from the turn constructor's view of the inbound
+ *      (`ev.rawContent`), and lifts the Buzz coordinates when it did.
+ *
+ *   2. `resolveRoute(originChannel, mode, buzzEnabled)` — the exhaustive 12-row
+ *      routing table: given a turn's origin, the configured mirror mode, and
+ *      whether Buzz is enabled at all, returns the primary channel plus any
+ *      mirror channels an answer should also be copied to. Pure lookup — Phase
+ *      2a wires no senders to it (that is Phase 2b).
+ *
+ *   3. `isBuzzTurnRoutingEnabled(env)` — the feature flag reader.
+ *
+ * ── Why `parseChannelOrigin` reads the OUTER opening tag's LAST `source=` ──
+ *
+ * GATE-0 (see `buzz-phase2-design.md` §2.1) established the live transport
+ * shape. The Buzz sidecar's `mapBuzzEvent` (`src/buzz-gateway/inbound-map.ts`)
+ * pre-renders a FULL `<channel source="buzz" buzz_channel_id=… buzz_event_id=…
+ * buzz_thread_root=… …>body</channel>` envelope into the inbound's `text`, AND
+ * mirrors those same fields into the inbound's `meta`. The native Claude Code
+ * channel renderer then wraps that inbound again: it emits an OUTER
+ * `<channel source="switchroom-telegram" … source="buzz" buzz_channel_id=…
+ * buzz_event_id=… buzz_thread_root=… …>` opening tag — hoisting every `meta`
+ * key onto the outer tag as an attribute (so `meta.source="buzz"` appears as a
+ * SECOND `source=` after the renderer's own `source="switchroom-telegram"`) —
+ * and renders the sidecar's pre-rendered envelope VERBATIM in the body (the
+ * "double-wrap": a nested `<channel>` inside the body).
+ *
+ * The authoritative provenance signal is therefore the OUTER opening tag, and
+ * within it the LAST `source=` (the meta-hoisted one). This is exactly how
+ * `deriveTurnRole` (`telegram-plugin/turn-liveness-floor.ts`) already
+ * classifies the loop role in production for cron / synthetic inbounds — it
+ * matches the first `<channel …>` opening tag and reads the LAST `source=`
+ * within it via the greedy `/<channel[^>]*\bsource="([^"]+)"/`. We deliberately
+ * mirror that regex byte-for-byte so Buzz turns classify identically. Reading
+ * the FIRST `source=` (the renderer's `switchroom-telegram`) — or reading the
+ * inner nested envelope — would silently misclassify every Buzz turn as
+ * Telegram. The Buzz coordinates are likewise lifted from that same outer
+ * meta-hoisted opening tag, never the inner nested envelope.
+ *
+ * Every failure path is fail-safe to Telegram: a non-string input, no channel
+ * tag, a non-buzz last source, or any missing/empty coordinate all yield
+ * `{ originChannel: 'telegram' }`. A Buzz origin is only ever returned with a
+ * complete, non-empty coordinate triple.
+ */
+
+export type Channel = 'telegram' | 'buzz'
+
+/**
+ * Configured mirror mode for the fleet's Buzz co-channel:
+ *   - `both`   — answer on the origin channel AND mirror a copy to the other.
+ *   - `origin` — answer only on the channel the turn came in on.
+ *   - `off`    — Buzz routing is dormant; everything resolves to Telegram.
+ */
+export type MirrorMode = 'both' | 'origin' | 'off'
+
+export interface BuzzCoords {
+  channelId: string
+  eventId: string
+  threadRoot: string
+}
+
+export interface ChannelOrigin {
+  originChannel: Channel
+  buzzCoords?: BuzzCoords
+}
+
+export interface Route {
+  primary: Channel
+  mirrors: Channel[]
+}
+
+// Frozen shared fail-safe result. `parseChannelOrigin` never attaches
+// `buzzCoords` to a Telegram origin, so a single immutable instance is safe to
+// return from every fail-safe path.
+const TELEGRAM_ONLY: ChannelOrigin = Object.freeze({ originChannel: 'telegram' })
+
+/**
+ * Greedy match of the FIRST `<channel …>` opening tag's LAST `source=`.
+ *
+ * Byte-for-byte identical to `deriveTurnRole`'s regex in
+ * `turn-liveness-floor.ts`: `[^>]*` cannot cross the tag's closing `>`, so the
+ * match is confined to the first opening tag, and its greediness backtracks to
+ * the LAST `source="…"` within it — the meta-hoisted `source="buzz"` on a Buzz
+ * turn, or the renderer's own `source="switchroom-telegram"` on a Telegram one.
+ */
+const OUTER_LAST_SOURCE = /<channel[^>]*\bsource="([^"]+)"/
+
+// Isolates the first opening tag (up to its closing `>`), matching the same
+// `[^>]*` boundary the source regex uses. Coordinates are read from this
+// substring so the inner nested (double-wrapped) envelope can never be mistaken
+// for the outer meta-hoisted tag.
+const OUTER_OPEN_TAG = /<channel[^>]*>/
+
+/**
+ * Reverse of the sidecar/renderer XML-attribute escaping (`&amp; &quot; &lt;
+ * &gt;`). Buzz coordinates are hex/uuid in practice (no special chars, so this
+ * is usually a pass-through), but the native renderer's exact escaping of
+ * hoisted `meta` values is not contractually guaranteed, so we unescape
+ * defensively. `&amp;` is applied LAST so a literal `&amp;lt;` in the source
+ * decodes to `&lt;`, not `<`.
+ */
+function unescapeXmlAttr(s: string): string {
+  return s
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+/**
+ * Reads a named attribute's value from a single opening-tag substring.
+ * Returns the unescaped value, or `null` when the attribute is absent or its
+ * value is empty (an empty coordinate is treated as missing → fail-safe).
+ */
+function readAttr(openTag: string, name: string): string | null {
+  const m = openTag.match(new RegExp(`\\b${name}="([^"]*)"`))
+  if (m == null) return null
+  const value = unescapeXmlAttr(m[1])
+  return value.length > 0 ? value : null
+}
+
+/**
+ * Classify a turn's origin channel purely from the turn constructor's view of
+ * the inbound (`ev.rawContent`). Fail-safe to Telegram on every deviation. See
+ * the module header for why this reads the outer opening tag's LAST `source=`.
+ */
+export function parseChannelOrigin(rawContent: string | null | undefined): ChannelOrigin {
+  if (typeof rawContent !== 'string') return TELEGRAM_ONLY
+
+  const sourceMatch = rawContent.match(OUTER_LAST_SOURCE)
+  if (sourceMatch == null || sourceMatch[1] !== 'buzz') return TELEGRAM_ONLY
+
+  // Coordinates live on the SAME outer, meta-hoisted opening tag. Isolate it so
+  // the inner nested envelope (which carries its own buzz_* attrs) can never be
+  // read by mistake.
+  const openMatch = rawContent.match(OUTER_OPEN_TAG)
+  if (openMatch == null) return TELEGRAM_ONLY
+  const openTag = openMatch[0]
+
+  const channelId = readAttr(openTag, 'buzz_channel_id')
+  const eventId = readAttr(openTag, 'buzz_event_id')
+  const threadRoot = readAttr(openTag, 'buzz_thread_root')
+
+  if (channelId == null || eventId == null || threadRoot == null) {
+    // A turn whose outer tag says source="buzz" but is missing a coordinate is
+    // structurally malformed. Degrade to Telegram rather than emit a Buzz
+    // origin we cannot address — a breadcrumb so the gap is diagnosable.
+    process.stderr.write(
+      'telegram gateway: buzz-origin turn missing coordinate ' +
+        `(channel_id=${channelId != null} event_id=${eventId != null} ` +
+        `thread_root=${threadRoot != null}) — routing as telegram\n`,
+    )
+    return TELEGRAM_ONLY
+  }
+
+  return { originChannel: 'buzz', buzzCoords: { channelId, eventId, threadRoot } }
+}
+
+/**
+ * The exhaustive 12-row routing table (origin × mode × enabled). Pure lookup.
+ *
+ * Semantics (Finding 6):
+ *   - `primary` is Buzz  IFF the turn ORIGINATED on Buzz and Buzz is live
+ *     (enabled AND mode ≠ off); otherwise Telegram.
+ *   - a MIRROR is emitted only under `mode === 'both'` while Buzz is live:
+ *       · Telegram-origin → mirror to Buzz  (reach Buzz readers with the answer)
+ *       · Buzz-origin     → mirror to Telegram (the guaranteed Telegram copy)
+ *   - under `origin`, `off`, or Buzz-disabled, there are no mirrors and the
+ *     primary collapses to Telegram unless the turn genuinely originated on a
+ *     live Buzz channel.
+ *
+ * "Buzz is live" = `buzzEnabled && mode !== 'off'`. When Buzz is not live, a
+ * Buzz-origin turn still resolves to a Telegram primary (fail-safe: we never
+ * route to a channel that is switched off).
+ */
+export function resolveRoute(
+  originChannel: Channel,
+  mode: MirrorMode,
+  buzzEnabled: boolean,
+): Route {
+  const buzzLive = buzzEnabled && mode !== 'off'
+
+  const primary: Channel = originChannel === 'buzz' && buzzLive ? 'buzz' : 'telegram'
+
+  let mirrors: Channel[] = []
+  if (buzzLive && mode === 'both') {
+    mirrors = originChannel === 'telegram' ? ['buzz'] : ['telegram']
+  }
+
+  return { primary, mirrors }
+}
+
+/**
+ * Buzz co-channel — Phase 2b, safety correction S2. The ONLY mirror modes that
+ * ship live in 2b are `both` and `off`. `origin` is DEFERRED: the mirror hook
+ * lives exclusively in `sendReply`, so the `stream_reply` / turn-flush answer
+ * paths bypass it — `origin`'s "answer only on the origin channel" contract
+ * cannot be honored soundly (a buzz-origin turn under `origin` would still get
+ * a Telegram copy from those bypassing paths, and could NOT get a reliable
+ * buzz-only answer). Rather than half-honor it, degrade a configured `origin`
+ * to `off` (dark) deterministically here — a code mechanism, not a runtime
+ * assumption. Absent/`both` ⇒ `both`; `off`/`origin` ⇒ `off`.
+ */
+export function parseConfiguredMirrorMode(raw: string | undefined): 'both' | 'off' {
+  // Absent ⇒ the schema default (`both`). The ONLY value that ships live is an
+  // explicit `both`; `off`/`origin` (S2 deferred) go dark. LOW-1: ANY other
+  // value — a typo like `BUZZ_MIRROR=of` set directly in env, unreachable via
+  // the schema enum but possible via raw env — fails DARK rather than silently
+  // going live. Only an explicit `both` (or absence) is live.
+  if (raw === undefined) return 'both'
+  if (raw === 'both') return 'both'
+  return 'off'
+}
+
+/**
+ * Buzz co-channel — Phase 2b, safety correction S1 (the misroute fix).
+ *
+ * DETERMINISTIC pre-publish owner guard for the ONE dangerous path: a THREADED
+ * publish into an existing Buzz conversation (a reply whose resolved owner turn
+ * originated on Buzz, so the answer would be signed and posted using that turn's
+ * Buzz coordinates). This is a code mechanism, never prompt discipline.
+ *
+ * The hazard (S1): in a Telegram DM the reply tool omits `origin_turn_id`, so
+ * reply-owner resolution falls through to the live-turn tier. Without a guard, a
+ * late or extra reply that actually belonged to an EARLIER Telegram DM turn can
+ * bind to a concurrently-live Buzz turn and be published as a signed public
+ * Nostr event addressed into a stranger's thread — a cross-channel misroute.
+ *
+ * The guard is consulted ONLY on the buzz-origin threaded-publish decision (the
+ * buzz-mirror hub gates its call on `ownerOriginChannel === 'buzz'`). It is NOT
+ * applied to the telegram-origin→Buzz top-level mirror under `both` mode: that
+ * path binds to no Buzz owner turn and no Buzz coordinates (it is a fresh
+ * top-level post the operator consented to by enabling `both`), so there is no
+ * owner binding to misresolve. See design §3.3 for why the two paths are
+ * separated (and the reconciliation note recorded there against S1's wording).
+ *
+ * Safe to publish the threaded Buzz reply IFF EITHER:
+ *   - the reply POSITIVELY echoed the owner turn's id (`origin_turn_id`
+ *     round-tripped and matched) — an explicit, forge-checked binding; OR
+ *   - there is NO live/recent turn of a DIFFERENT origin within the supersede
+ *     window that the reply could otherwise have belonged to — so the live-tier
+ *     binding to the Buzz turn is unambiguous.
+ * Otherwise fail safe: the buzz-mirror hub drops the Buzz publish entirely and
+ * the answer is delivered Telegram-only. The guarantee is never to sign+publish
+ * a Buzz event on an ambiguous owner binding.
+ */
+export function isBuzzThreadedPublishSafe(input: {
+  ownerEchoed: boolean
+  hasRecentDifferentOriginTurn: boolean
+}): boolean {
+  return input.ownerEchoed || !input.hasRecentDifferentOriginTurn
+}
+
+/**
+ * Phase 2a feature flag. Default ON (escape-hatch convention, mirroring the
+ * fleet's other `SWITCHROOM_*` module flags): only an explicit `'0'` disables.
+ * Reads from an injected env map so the flag is unit-testable without mutating
+ * `process.env`.
+ */
+export function isBuzzTurnRoutingEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  return env.SWITCHROOM_BUZZ_TURN_ROUTING !== '0'
+}