switchroom 0.19.48 → 0.20.1

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -169,6 +169,43 @@ export interface PreApprovedResultEvent {
   preApproved: boolean;
 }
 
+/**
+ * Buzz co-channel — Phase 2b. Gateway → Buzz-sidecar peer: a request to
+ * publish (or correct) a Nostr channel message. Sent ONLY to the single
+ * duplex peer client that announced itself via `hello_buzz_peer`, never to a
+ * registered agent bridge. The sidecar's `publisher.ts` is the sole content-
+ * signer: it re-scrubs `payload.text` through `detectSecrets` before signing
+ * and answers with a `buzz_publish_result` carrying the same `correlationId`.
+ *
+ * `payload.kind` is restricted to `message` | `correction` in Phase 2b
+ * (reaction / approval / patch are deferred per design §3.1 / F4 — the Buzz
+ * desktop renders only a fixed content-kind allowlist). A `correction`
+ * carries the `targetEventId` of the already-published event it supersedes.
+ */
+export interface OutboundToBuzzMessage {
+  type: "outbound_to_buzz";
+  /** Caller-generated id, echoed back in `buzz_publish_result`. */
+  correlationId: string;
+  /**
+   * The publishing agent. Validated for wire SHAPE only (AGENT_NAME_RE in
+   * `isValidClientToGateway`) and stamped by the hub itself (buzz-mirror sets it
+   * from its own `agentName`), so it is diagnostic here — the gateway does NOT
+   * cross-check it against a configured own-name (createIpcServer holds no such
+   * name). Impersonation is prevented structurally instead: only the registered
+   * duplex peer connection receives `outbound_to_buzz` and may answer it.
+   */
+  agentName: string;
+  /** Target NIP-29 channel (group) id, `["h", …]`. */
+  channelId: string;
+  /** NIP-10 reply target (the Buzz event being answered), when threading. */
+  replyToEventId?: string;
+  /** NIP-10 thread root, when threading into an existing conversation. */
+  threadRootId?: string;
+  payload:
+    | { kind: "message"; text: string }
+    | { kind: "correction"; text: string; targetEventId: string };
+}
+
 export type GatewayToClient =
   | InboundMessage
   | PermissionEvent
@@ -181,7 +218,8 @@ export type GatewayToClient =
   | RolloutStatusPostedEvent
   | RolloutStatusEditedEvent
   | PendingPermissionStatusEvent
-  | PreApprovedResultEvent;
+  | PreApprovedResultEvent
+  | OutboundToBuzzMessage;
 
 // === Bridge (Client) -> Gateway messages ===
 
@@ -671,6 +709,45 @@ export interface CheckPreApprovedMessage {
   unifiedDiff: string;
 }
 
+/**
+ * Buzz co-channel — Phase 2b. The Buzz sidecar's one-time announcement that
+ * this connection is the DUPLEX publish peer, not an agent bridge. It carries
+ * NO `agentIndex` claim and NEVER registers a topic: the gateway parks it in a
+ * dedicated `buzzPeerClient` slot, marks it watchdog-exempt (it has no live
+ * `agentName`), and refuses a subsequent `register` on the same connection
+ * (and, conversely, refuses `hello_buzz_peer` on a client that already
+ * `register`ed) — the peer role and the agent-bridge role are mutually
+ * exclusive per design §3.2 / S7. `agentName` here is the fleet agent whose
+ * outbound this peer publishes; it is validated for wire SHAPE only
+ * (AGENT_NAME_RE) and used for logging — the gateway does NOT cross-check it
+ * against a configured own-name (it holds none). The peer role is secured
+ * structurally: a live peer cannot be displaced by a fresh hello, and only the
+ * peer connection may send `buzz_publish_result`.
+ */
+export interface HelloBuzzPeerMessage {
+  type: "hello_buzz_peer";
+  agentName: string;
+}
+
+/**
+ * Buzz co-channel — Phase 2b. The sidecar's reply to an `outbound_to_buzz`:
+ * the outcome of the publish attempt. Advisory ONLY under `both` mode — the
+ * Telegram copy is the guaranteed delivery, so a `buzz_publish_result` with
+ * `ok: false` never fails or retries the answer, it only feeds the hub's
+ * correlation map (freeing the pending slot, logging, and — on success —
+ * recording the published `eventId` so a later `correction` can target it).
+ */
+export interface BuzzPublishResultMessage {
+  type: "buzz_publish_result";
+  /** Echoes the `correlationId` from the originating `outbound_to_buzz`. */
+  correlationId: string;
+  ok: boolean;
+  /** The locally-computed (`getEventHash`) id of the signed event, on success. */
+  eventId?: string;
+  /** Diagnostic detail on failure (never carries scrubbed content). */
+  error?: string;
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -692,4 +769,6 @@ export type ClientToGateway =
   | RolloutStatusPostMessage
   | RolloutStatusEditMessage
   | QueryPendingPermissionMessage
-  | CheckPreApprovedMessage;
+  | CheckPreApprovedMessage
+  | HelloBuzzPeerMessage
+  | BuzzPublishResultMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -23,6 +23,9 @@ import type {
   SessionEventForward,
   ToolCallMessage,
   ToolCallResult,
+  HelloBuzzPeerMessage,
+  OutboundToBuzzMessage,
+  BuzzPublishResultMessage,
 } from "./ipc-protocol.js";
 import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
 import { OPERATOR_EVENT_KINDS } from "../operator-events.js";
@@ -160,6 +163,16 @@ export interface IpcServerOptions {
     client: IpcClient,
     msg: RolloutStatusEditMessage,
   ) => void | Promise<void>;
+  /**
+   * Buzz co-channel Phase 2b — the duplex Buzz peer's advisory publish outcome
+   * (`buzz_publish_result`). Handler feeds the buzz-mirror hub's correlation
+   * map: it frees the pending slot and, on success, records the published
+   * eventId so a later `correction` can target it. Fire-and-forget — under
+   * `both` mode the Telegram copy is the guaranteed delivery, so a failed
+   * publish never fails or retries the answer. Optional; a gateway without Buzz
+   * wired simply drops the message.
+   */
+  onBuzzPublishResult?: (client: IpcClient, msg: BuzzPublishResultMessage) => void;
   log?: (msg: string) => void;
   /**
    * How long (in ms) to wait without a heartbeat before force-closing the
@@ -178,6 +191,15 @@ export interface IpcClient {
   id: string;
   agentName: string | null;
   topicId: number | null;
+  /**
+   * Buzz co-channel Phase 2b (S7). True IFF this connection announced itself
+   * as the duplex Buzz publish peer via `hello_buzz_peer`. A peer NEVER holds
+   * an `agentName`/`agentIndex` slot; the flag makes the peer and agent-bridge
+   * roles mutually exclusive (a `register` is refused on a peer connection and
+   * vice-versa) and is what keeps the peer connection watchdog-exempt (it rides
+   * the existing `agentName === null` exemption — the peer has no heartbeat).
+   */
+  isBuzzPeer: boolean;
   send(msg: GatewayToClient): void;
   close(): void;
   isAlive(): boolean;
@@ -190,6 +212,14 @@ export interface IpcServer {
   broadcast(msg: GatewayToClient): void;
   getClient(agentName: string): IpcClient | undefined;
   clientCount(): number;
+  /**
+   * Buzz co-channel Phase 2b. Send an `outbound_to_buzz` request to the single
+   * duplex Buzz peer, if one is currently connected. Returns false (no send)
+   * when no peer has announced itself — the caller (buzz-mirror hub) treats a
+   * false return as "Buzz unreachable" and simply drops the mirror; the
+   * guaranteed Telegram copy already went out, so nothing fails or retries.
+   */
+  sendToBuzzPeer(msg: OutboundToBuzzMessage): boolean;
   close(): Promise<void>;
 }
 
@@ -493,6 +523,25 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
         || (m.text as string).length > RICH_MESSAGE_MAX_CHARS) return false;
       return true;
     }
+    case "hello_buzz_peer": {
+      // Buzz co-channel Phase 2b — the sidecar's one-time duplex-peer
+      // announcement. Wire shape only; the handler parks it in the dedicated
+      // buzzPeerClient slot and enforces role-disjointness with `register`.
+      return typeof m.agentName === "string"
+        && AGENT_NAME_RE.test(m.agentName as string);
+    }
+    case "buzz_publish_result": {
+      // Buzz co-channel Phase 2b — the sidecar's advisory publish outcome.
+      if (typeof m.correlationId !== "string"
+        || (m.correlationId as string).length === 0
+        || (m.correlationId as string).length > 64) return false;
+      if (typeof m.ok !== "boolean") return false;
+      if (m.eventId !== undefined
+        && (typeof m.eventId !== "string" || (m.eventId as string).length > 128)) return false;
+      if (m.error !== undefined
+        && (typeof m.error !== "string" || (m.error as string).length > 500)) return false;
+      return true;
+    }
     default:
       return false;
   }
@@ -522,10 +571,45 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onRequestConfigFinalize,
     onRolloutStatusPost,
     onRolloutStatusEdit,
+    onBuzzPublishResult,
     log = () => {},
     heartbeatTimeoutMs = 30_000,
   } = options;
 
+  // Buzz co-channel Phase 2b (S7) — the single duplex Buzz publish peer's
+  // connection, or null when none is connected. Parked here (never in
+  // agentIndex) so `outbound_to_buzz` addresses exactly one peer and the peer
+  // never shadows an agent-bridge slot. Nulled in removeClient on disconnect.
+  let buzzPeerClient: IpcClientImpl | null = null;
+
+  // Hub-side dedup ring for Buzz injects (fable MAJOR-2). The Buzz sidecar's
+  // durable journal covers the normal case, but a crash AFTER the gateway
+  // injects but BEFORE the sidecar records dedup would re-fire the turn on
+  // restart. This bounded in-memory ring drops a re-injected duplicate at the
+  // hub, keyed on the stable Buzz event id.
+  //
+  // SCOPE — buzz ONLY. This is the shared inject hot path (cron, reactions,
+  // resume, etc.). The check below fires exclusively for injects whose
+  // `inbound.meta.source === "buzz"` AND that carry a `buzz_event_id`; every
+  // other inject source flows through untouched, byte-identical to before. A
+  // buzz inject without a stable id (should not happen — inbound-map always
+  // stamps one) also flows through untouched rather than being dropped blind.
+  const BUZZ_INJECT_RING_MAX = 1024;
+  const buzzInjectSeen = new Set<string>();
+  const buzzInjectOrder: string[] = [];
+  /** Return true if this buzz event id was already injected (drop it); else
+   *  record it and return false. Bounded FIFO eviction at RING_MAX entries. */
+  const buzzInjectIsDuplicate = (eventId: string): boolean => {
+    if (buzzInjectSeen.has(eventId)) return true;
+    buzzInjectSeen.add(eventId);
+    buzzInjectOrder.push(eventId);
+    if (buzzInjectOrder.length > BUZZ_INJECT_RING_MAX) {
+      const evicted = buzzInjectOrder.shift();
+      if (evicted !== undefined) buzzInjectSeen.delete(evicted);
+    }
+    return false;
+  };
+
   // Race-safe cleanup: rename the live socket to a .bak sidecar rather than
   // unlinking it. If the old gateway's delayed shutdown-cleanup later tries to
   // rename again, it targets .bak (already-moved) not the freshly-bound file.
@@ -565,6 +649,10 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     if (client.topicId != null && topicIndex.get(client.topicId) === client) {
       topicIndex.delete(client.topicId);
     }
+    // Buzz co-channel Phase 2b — release the duplex peer slot if this was it,
+    // identity-checked (a fast peer reconnect may have already installed a new
+    // peer before this old connection's close runs).
+    if (buzzPeerClient === client) buzzPeerClient = null;
     loggedLegacyUpdatePlaceholder.delete(client.id);
     onClientDisconnected(client);
     log(`client disconnected: ${client.id} (agent=${client.agentName})`);
@@ -623,9 +711,22 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       case "pty_partial":
         if (onPtyPartial) onPtyPartial(client, msg as PtyPartialForward);
         break;
-      case "inject_inbound":
-        if (onInjectInbound) onInjectInbound(client, msg as InjectInboundMessage);
+      case "inject_inbound": {
+        const injectMsg = msg as InjectInboundMessage;
+        // Hub-side Buzz dedup ring (fable MAJOR-2) — scoped strictly to
+        // meta.source==="buzz". A duplicate buzz event id (a re-inject after a
+        // crash between inject and the sidecar's dedup record) is dropped here;
+        // every non-buzz inject is unaffected.
+        const injMeta = (injectMsg.inbound as { meta?: Record<string, unknown> } | undefined)?.meta;
+        if (injMeta && injMeta.source === "buzz" && typeof injMeta.buzz_event_id === "string") {
+          if (buzzInjectIsDuplicate(injMeta.buzz_event_id)) {
+            log(`inject_inbound: dropped duplicate buzz event ${injMeta.buzz_event_id.slice(0, 12)} (hub dedup ring)`);
+            break;
+          }
+        }
+        if (onInjectInbound) onInjectInbound(client, injectMsg);
         break;
+      }
       case "send_outbound":
         if (onSendOutbound) onSendOutbound(client, msg as SendOutboundMessage);
         break;
@@ -831,6 +932,28 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
         // The handler replies `rollout_status_edited` (#4065) when it can; an
         // unwired gateway sends nothing and hostd's bounded wait expires.
         break;
+      case "hello_buzz_peer":
+        handleHelloBuzzPeer(client, msg as HelloBuzzPeerMessage);
+        break;
+      case "buzz_publish_result":
+        // Confused-deputy close (MAJOR-1a): ONLY the registered duplex Buzz peer
+        // may report a publish outcome. Without this gate any client (an agent
+        // MCP bridge, or a fresh anonymous connection) could forge a
+        // `buzz_publish_result` carrying a valid-looking correlationId and a
+        // foreign eventId, poisoning the hub's correlation map so a later
+        // correction signs against an arbitrary Nostr event. The peer→agent
+        // direction is already fenced (register-after-hello refused above); this
+        // mirrors that rigor on the agent→peer surface.
+        if (!client.isBuzzPeer) {
+          log(
+            `SECURITY: rejecting buzz_publish_result from non-peer connection ` +
+            `(agent=${client.agentName ?? "anonymous"} id=${client.id}) — only the ` +
+            `registered Buzz publish peer may report publish outcomes; dropped`,
+          );
+          break;
+        }
+        if (onBuzzPublishResult) onBuzzPublishResult(client, msg as BuzzPublishResultMessage);
+        break;
       case "update_placeholder":
         // Legacy recall.py IPC — placeholder UX was removed in #553 PR 5.
         // Soft-accepted so recall.py keeps working without modifying
@@ -846,7 +969,72 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     }
   }
 
+  /**
+   * Buzz co-channel Phase 2b (S7). Accept a `hello_buzz_peer` announcement,
+   * parking the connection as the single duplex Buzz publish peer. Enforces
+   * role-disjointness as a CODE mechanism, not sidecar self-discipline:
+   *   - a connection that already `register`ed (agentName set) or already
+   *     announced as a peer is refused (close+drop);
+   *   - the reciprocal refusal — a `register` on a peer connection — lives in
+   *     handleRegister below.
+   * The peer NEVER touches agentIndex/topicIndex and carries no heartbeat, so
+   * it rides the watchdog's existing `agentName === null` exemption untouched.
+   */
+  function handleHelloBuzzPeer(client: IpcClientImpl, msg: HelloBuzzPeerMessage) {
+    if (client.agentName !== null || client.isBuzzPeer) {
+      log(
+        `rejecting hello_buzz_peer: connection already has a role ` +
+        `(agent=${client.agentName ?? "none"} isBuzzPeer=${client.isBuzzPeer}) — close+drop client=${client.id}`,
+      );
+      try { client.close(); } catch { /* nothing to do */ }
+      return;
+    }
+    // Impersonation guard (MAJOR-1b): a fresh connection must NOT be able to
+    // DISPLACE a LIVE Buzz peer. Without this an anonymous client could send
+    // `hello_buzz_peer`, replace the real sidecar in the buzzPeerClient slot,
+    // then receive every `outbound_to_buzz` and answer with forged
+    // `{ok:true, eventId:<foreign>}` results — poisoning `msgToBuzz` so a later
+    // edit_message signs a correction targeting an arbitrary foreign event.
+    //
+    // A legitimate sidecar reconnect is still honored: it only ever happens
+    // AFTER the prior socket dropped, at which point the socket `close` handler
+    // has run removeClient (nulling buzzPeerClient), OR — in the brief window
+    // before that fires — the prior client is already `close()`d so isAlive()
+    // is false. So we refuse displacement ONLY while the existing peer
+    // connection is still alive; a dead/closed prior peer is freely replaceable.
+    if (buzzPeerClient && buzzPeerClient !== client && buzzPeerClient.isAlive()) {
+      log(
+        `SECURITY: rejecting hello_buzz_peer — a LIVE Buzz peer is already ` +
+        `connected (live_id=${buzzPeerClient.id} rejected_id=${client.id}); ` +
+        `refusing displacement, close+drop`,
+      );
+      try { client.close(); } catch { /* nothing to do */ }
+      return;
+    }
+    // Replace a dead/closed prior peer connection (e.g. a sidecar reconnect
+    // whose predecessor's socket already dropped) cleanly.
+    if (buzzPeerClient && buzzPeerClient !== client) {
+      log(`hello_buzz_peer: replacing prior (dead) buzz peer (prior_id=${buzzPeerClient.id} new_id=${client.id})`);
+      try { buzzPeerClient.close(); } catch { /* nothing to do */ }
+    }
+    client.isBuzzPeer = true;
+    buzzPeerClient = client;
+    log(`registered buzz publish peer for agent=${msg.agentName} id=${client.id}`);
+  }
+
   function handleRegister(client: IpcClientImpl, msg: RegisterMessage) {
+    // Buzz co-channel Phase 2b (S7) — reciprocal role-disjointness: a
+    // connection that announced itself as the duplex Buzz peer must never be
+    // allowed to claim an agentIndex slot. Refuse server-side (a code check,
+    // not sidecar self-discipline).
+    if (client.isBuzzPeer) {
+      log(
+        `rejecting register: connection is the Buzz publish peer, not an agent bridge ` +
+        `(close+drop client=${client.id})`,
+      );
+      try { client.close(); } catch { /* nothing to do */ }
+      return;
+    }
     // Defence in depth for #430. The bridge refuses to register
     // without SWITCHROOM_AGENT_NAME (set in start.sh per agent), but
     // an older bridge or a third-party caller could still send the
@@ -919,6 +1107,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     id: string;
     agentName: string | null = null;
     topicId: number | null = null;
+    isBuzzPeer = false;
     lastHeartbeat: number = Date.now();
     _socket: import("bun").Socket<SocketData>;
     private _closed = false;
@@ -1055,6 +1244,12 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       return clients.size;
     },
 
+    sendToBuzzPeer(msg: OutboundToBuzzMessage): boolean {
+      if (!buzzPeerClient || !buzzPeerClient.isAlive()) return false;
+      buzzPeerClient.send(msg);
+      return true;
+    },
+
     async close(): Promise<void> {
       // Stop the heartbeat watchdog before closing clients so it doesn't
       // log spurious evictions during planned shutdown.

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -69,6 +69,7 @@ import {
 } from '../hooks/audience-classify.mjs'
 import { queueFloodBlockedReply } from './flood-reply-queue.js'
 import { resolveChatIdFallback } from './chat-id-fallback.js'
+import { getBuzzMirror } from './buzz-mirror.js'
 import { isFinalAnswerReply, isSubstantiveFinalReply, shouldJournalReplySiteDelivery } from '../final-answer-detect.js'
 import { decideOverPing, type OverPingDecision } from '../over-ping-safety-net.js'
 import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
@@ -756,6 +757,30 @@ export interface VoiceOutPlan {
   ttsChunks: string[]
 }
 
+/**
+ * Resolve the Buzz-mirror NIP-10 antecedent key for an outbound answer, or
+ * `undefined` to mirror FLAT. Pure + deterministic so the gating is testable
+ * without the full send harness. Returns `${chatId}:${replyTo}` only when a
+ * genuine, renderable reply antecedent exists; `undefined` when:
+ *  - there is no antecedent (`replyTo == null`), or
+ *  - `replyTo` is not a finite number (a non-numeric model `reply_to` coerces to
+ *    `NaN`; #4301 — never build a bogus `chat:NaN` key the mirror logs as a
+ *    real miss), or
+ *  - `replyMode === 'off'` (#4300 — the Telegram copy renders NO reply, so the
+ *    Buzz mirror must stay flat too; without this the Buzz copy visibly threads
+ *    while the Telegram copy does not — a surface divergence).
+ */
+export function resolveMirrorAntecedentKey(
+  chatId: string,
+  replyTo: number | undefined,
+  replyMode: string,
+): string | undefined {
+  if (replyTo == null || !Number.isFinite(replyTo) || replyMode === 'off') {
+    return undefined
+  }
+  return `${chatId}:${replyTo}`
+}
+
 export interface SendReplyRequest {
   /** Raw `reply` tool args, exactly as the MCP dispatch received them. */
   args: Record<string, unknown>
@@ -834,6 +859,10 @@ export interface SendReplyGatewayDeps {
   resolveReplyOwnerTurn(liveTurn: CurrentTurn | null, chatId: string, args: Record<string, unknown>): { turn: CurrentTurn | null; tier: ReplyOwnerTier; candidates: ReplyOwnerCandidates }
   findTurnByOriginId(originTurnId: string | null | undefined): CurrentTurn | null
   findTurnByQuotedMessageId(chatId: string, replyTo: unknown): CurrentTurn | null
+  /** Buzz co-channel Phase 2b (S1) — the same chat-wide latest-ended lookup the
+   *  owner-resolution wiring uses. Read here ONLY to compute the S1 owner-guard
+   *  input `hasRecentDifferentOriginTurn`; a no-op when Buzz mirroring is off. */
+  findLatestTurnForChat(chatId: string, opts: { endedOnly: boolean }): CurrentTurn | null
   resolveAnswerThreadWithLog(
     chatId: string,
     explicitThreadId: number | undefined,
@@ -913,7 +942,7 @@ export async function sendReply(
     lockedBot, robustApiCall, swallowingApiCall,
     loadAccess, redactOutboundText, assertAllowedChat, assertSendable,
     statusKey, streamKey,
-    resolveReplyOwnerTurn, findTurnByOriginId, findTurnByQuotedMessageId,
+    resolveReplyOwnerTurn, findTurnByOriginId, findTurnByQuotedMessageId, findLatestTurnForChat,
     resolveAnswerThreadWithLog, resolveThreadId,
     getLatestInboundMessageId, getLastSubagentHandbackAt, subagentReplyAuthority, recordOutbound,
     emissionAuthorityFor, clearActivitySummary,
@@ -1540,10 +1569,19 @@ export async function sendReply(
     )
   }
 
+  // #4301: track whether `reply_to` came from the quote-opt-in DEFAULT (the
+  // latest inbound user message) rather than an explicit/model-supplied value.
+  // The default antecedent is never in the Buzz correlation store, so its mirror
+  // lookup always misses — passing this flag lets the mirror log that expected
+  // flat fallback quietly instead of as an eviction "MISS".
+  let antecedentFromQuoteOptInDefault = false
   if (reply_to == null && quoteOptIn && HISTORY_ENABLED) {
     try {
       const latest = getLatestInboundMessageId(chat_id, threadId ?? null)
-      if (latest != null) reply_to = latest
+      if (latest != null) {
+        reply_to = latest
+        antecedentFromQuoteOptInDefault = true
+      }
     } catch (err) {
       process.stderr.write(`telegram gateway: quote-reply lookup failed: ${(err as Error).message}\n`)
     }
@@ -2585,6 +2623,51 @@ export async function sendReply(
     if (shouldJournalReplySiteDelivery({ text: rawText, disableNotification: modelDisableNotification })) {
       journalExternalDelivery({ turnNonce: t?.turnId ?? null, text, tgMessageId: sentIds[sentIds.length - 1], replyAlreadyDeliveredThisTurn: true })
     }
+    // ── Buzz co-channel Phase 2b mirror hook (S1/S4) ─────────────────────────
+    // STRICTLY downstream of the guaranteed Telegram delivery above: this runs
+    // only inside `sentIds.length > 0` (a Telegram copy landed) and is a
+    // byte-identical no-op when Buzz is disabled (`getBuzzMirror()` is null).
+    // Never throws — the hub swallows its own errors — so a Buzz mirror can
+    // never fail, delay, or alter the Telegram answer (the core invariant), and
+    // the tool result the model sees reflects the Telegram copy only (S4).
+    const buzzMirror = getBuzzMirror()
+    if (buzzMirror !== null) {
+      const { turn: mOwnerTurn, tier: mOwnerTier } = resolveReplyOwnerTurn(turn, chat_id, args)
+      const ownerOrigin = mOwnerTurn?.originChannel ?? 'telegram'
+      const ownerTurnId = mOwnerTurn?.turnId ?? null
+      // S1 inputs. ownerEchoed: the reply positively echoed the owner turn's id
+      // (the `origin` tier is the only one that binds by `origin_turn_id`).
+      const ownerEchoed = mOwnerTier === 'origin'
+      // hasRecentDifferentOriginTurn: is there a recent turn of a DIFFERENT
+      // origin than the resolved owner (the live turn, or the chat's latest
+      // ended turn) that this reply could otherwise have belonged to? Deterministic.
+      const latestEnded = findLatestTurnForChat(chat_id, { endedOnly: true })
+      const hasRecentDifferentOriginTurn = [turn, latestEnded].some(
+        (c) => c != null && c.turnId !== ownerTurnId && c.originChannel !== ownerOrigin,
+      )
+      buzzMirror.mirrorReplyDelivered({
+        scrubbedText: text,
+        ownerOriginChannel: ownerOrigin,
+        ownerBuzzCoords: mOwnerTurn?.buzzCoords,
+        ownerEchoed,
+        hasRecentDifferentOriginTurn,
+        telegramMessageKeys: sentIds.map((id) => `${chat_id}:${id}`),
+        // NIP-10 outbound thread continuity: the Telegram message THIS answer
+        // replied to (its finalized `reply_to`, whether model-supplied or the
+        // quote-opt-in default). The mirror resolves it against the durable
+        // correlation store and threads under it only on a HIT (a previously-
+        // mirrored answer); a user inbound / evicted key misses → flat.
+        //
+        // Guards:
+        //  - #4300: when `replyMode === 'off'` the Telegram copy renders NO
+        //    reply, so DON'T stamp the antecedent — keep the Buzz copy flat too
+        //    (surface parity; no threading the Buzz copy visibly threads on).
+        //  - #4301: `Number.isFinite` drops a non-numeric `reply_to` (→ `NaN`)
+        //    so it never becomes a bogus `chat:NaN` key that logs as a real miss.
+        antecedentTelegramMessageKey: resolveMirrorAntecedentKey(chat_id, reply_to, replyMode),
+        antecedentIsQuoteOptInDefault: antecedentFromQuoteOptInDefault,
+      })
+    }
   }
   return { content: [{ type: 'text', text: result }] }
 }

package/telegram-plugin/gateway/pending-turn-env.ts

@@ -0,0 +1,70 @@
+/**
+ * Writer for the one-shot `.pending-turn.env` diagnostic file (Stage 4 of
+ * simplify-restart, #250) — extracted verbatim from gateway.ts (#2996
+ * ratchet discipline: new inline code must not land in gateway.ts).
+ *
+ * The gateway writes `<agentDir>/.pending-turn.env` at boot when the
+ * previous shutdown left an interrupted turn; start.sh sources and then
+ * consumes it. These vars are PASSIVE forensic context for the wake-audit
+ * / "why did you restart" protocols — the real wake signal is the
+ * synthesized resume inbound, not this file.
+ */
+
+import { existsSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Turn } from '../registry/turns-schema.js'
+
+/**
+ * Write (or clear) the pending-turn env file. Atomic tmp+rename: a crash
+ * mid-write must never leave a truncated file that start.sh `source`s —
+ * partial SWITCHROOM_PENDING_* vars or a malformed line would break shell
+ * parsing inside the source. Never throws (logs via `log`).
+ */
+export function writePendingTurnEnv(
+  agentDir: string,
+  pending: Turn | null,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const pendingEnvPath = join(agentDir, '.pending-turn.env')
+  try {
+    if (pending != null) {
+      const lines = [
+        `SWITCHROOM_PENDING_TURN=true`,
+        `SWITCHROOM_PENDING_TURN_KEY=${pending.turn_key}`,
+        `SWITCHROOM_PENDING_CHAT_ID=${pending.chat_id}`,
+        // Tri-state thread signal for the handoff-briefing scope resolver.
+        // A pending Turn ALWAYS knows its thread: a numbered forum topic, or
+        // NULL (a DM / forum General topic). Emit the numeric id for a topic,
+        // and the literal sentinel `NULL` when the thread is genuinely null —
+        // so bin/handoff-briefing.sh scopes the reorientation to `thread_id IS
+        // NULL` instead of falling back to chat-only (all-threads) scope. An
+        // empty value is reserved for "thread unknown"; the writer never emits
+        // it, but an older gateway would, and the resolver treats empty as the
+        // safe chat-only fallback.
+        pending.thread_id != null
+          ? `SWITCHROOM_PENDING_THREAD_ID=${pending.thread_id}`
+          : `SWITCHROOM_PENDING_THREAD_ID=NULL`,
+        pending.last_user_msg_id != null
+          ? `SWITCHROOM_PENDING_USER_MSG_ID=${pending.last_user_msg_id}`
+          : `SWITCHROOM_PENDING_USER_MSG_ID=`,
+        `SWITCHROOM_PENDING_ENDED_VIA=${pending.ended_via ?? 'unknown'}`,
+        `SWITCHROOM_PENDING_STARTED_AT=${pending.started_at}`,
+        pending.interrupt_reason != null
+          ? `SWITCHROOM_PENDING_INTERRUPT_REASON=${pending.interrupt_reason}`
+          : `SWITCHROOM_PENDING_INTERRUPT_REASON=`,
+      ]
+      const pendingEnvTmp = `${pendingEnvPath}.tmp-${process.pid}`
+      writeFileSync(pendingEnvTmp, lines.join('\n') + '\n', { mode: 0o600 })
+      renameSync(pendingEnvTmp, pendingEnvPath)
+      log(
+        `telegram gateway: pending-turn env written to ${pendingEnvPath} ` +
+          `turnKey=${pending.turn_key} endedVia=${pending.ended_via ?? 'open'}\n`,
+      )
+    } else if (existsSync(pendingEnvPath)) {
+      rmSync(pendingEnvPath, { force: true })
+      log(`telegram gateway: pending-turn env cleared (clean previous shutdown)\n`)
+    }
+  } catch (err) {
+    log(`telegram gateway: pending-turn env write failed (${(err as Error).message})\n`)
+  }
+}

package/telegram-plugin/gateway/stream-render.ts

@@ -77,6 +77,7 @@ import { FlushCompletionTracker } from '../flushed-turn-supersede.js'
 import { subagentReplyAuthority } from './subagent-reply-authority.js'
 import { sessionConsumeSignal } from './session-consume-signal.js'
 import { decideTerminalReason, deriveTurnRole } from '../turn-liveness-floor.js'
+import { parseChannelOrigin, isBuzzTurnRoutingEnabled } from './channel-route.js'
 import { chatKey, chatKeyWithSuffix } from './chat-key.js'
 import { deriveTurnId } from './derive-turn-id.js'
 import { EMISSION_AUTHORITY_ENABLED, EmissionAuthority } from './emission-authority.js'
@@ -151,6 +152,17 @@ const QUEUED_CARD_HTML = '⏳ Queued — waiting for the current task to finish
 const QUEUED_CARD_FOLDED_HTML = '✅ Folded into the current task.'
 const QUEUED_CARD_EXPIRED_HTML = '⚠️ This queued message timed out before it could start.'
 
+// Buzz co-channel — Phase 2a origin stamp gate (Finding 10). The per-turn
+// `parseChannelOrigin` call is invoked ONLY when BOTH hold:
+//   · BUZZ_ENABLED — the per-agent projection `src/agents/compose.ts` sets in
+//     the container env ONLY when `channels.buzz.enabled === true`; absent for
+//     every Telegram-only agent.
+//   · SWITCHROOM_BUZZ_TURN_ROUTING !== '0' — the Phase 2a kill switch.
+// When either is off, the ctor stamps a plain Telegram origin without ever
+// calling the parser, so the Telegram-only hot path is byte-for-byte unchanged.
+const BUZZ_ENABLED = process.env.BUZZ_ENABLED === '1' || process.env.BUZZ_ENABLED === 'true'
+const BUZZ_ORIGIN_STAMP_ACTIVE = BUZZ_ENABLED && isBuzzTurnRoutingEnabled()
+
 /** The `enqueue` envelope fields `beginTurn` needs — the SessionEvent minus its
  *  discriminant. A parked entry additionally carries `parkedAt` for the TTL. */
 export interface TurnStartEnvelope {
@@ -576,6 +588,15 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
       gatewayReceiveAt: startedAt,
       // #2527 — stamp the loop role once, from the enqueue envelope.
       role: deriveTurnRole(ev.rawContent),
+      // Buzz co-channel — Phase 2a. Stamp the immutable origin provenance once,
+      // from the same enqueue envelope. Gated (Finding 10): when Buzz is off for
+      // this agent (or the kill switch is set) the parser is never called and
+      // the turn defaults to a plain Telegram origin — no coords, hot path
+      // untouched. When active, `parseChannelOrigin` reads the outer channel
+      // tag's meta-hoisted `source="buzz"` + coords (see `channel-route.ts`).
+      ...(BUZZ_ORIGIN_STAMP_ACTIVE
+        ? parseChannelOrigin(ev.rawContent)
+        : { originChannel: 'telegram' as const }),
       // PR1 (cross-turn stale-card guard, §9 lever 4 / race C/D). Only a
       // synthetic represent/owed-reply turn carries this; a foreground turn
       // leaves it undefined and the cross-turn card-OPEN gate is inert.

package/telegram-plugin/gateway/subagent-handback-marker.ts

@@ -176,6 +176,18 @@ export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion
   mental_model_proposal_failed: { decoupledCompletion: false },
   webhook: { decoupledCompletion: false },
   linear: { decoupledCompletion: false },
+  // Buzz co-channel (Phase 1): a Nostr kind:9 group message the buzz sidecar
+  // injects onto the gateway IPC queue as its OWN live inbound turn (anonymous
+  // inject, `meta.source="buzz"`) — never a decoupled completion resolving a
+  // different ended turn, so it must NOT stamp.
+  buzz: { decoupledCompletion: false },
+  // Gateway boot briefing (session_continuity.briefing: gateway): a synthetic
+  // FIRST user turn the gateway assembles from durable history and injects over
+  // the spool (`<channel source="boot_briefing">`, boot-briefing-builder.ts).
+  // Like the resume_* synthetics it lands as its OWN live inbound turn — its
+  // briefing reply resolves the live tier for its own turnId and cannot
+  // supersede a different ended turn's record — so it must NOT stamp.
+  boot_briefing: { decoupledCompletion: false },
 }
 
 /**