switchroom 0.19.48 → 0.20.0

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'
@@ -834,6 +835,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 +918,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,
@@ -2585,6 +2590,37 @@ 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}`),
+      })
+    }
   }
   return { content: [{ type: 'text', text: result }] }
 }

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

@@ -0,0 +1,61 @@
+/**
+ * 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}`,
+        pending.thread_id != null
+          ? `SWITCHROOM_PENDING_THREAD_ID=${pending.thread_id}`
+          : `SWITCHROOM_PENDING_THREAD_ID=`,
+        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 },
 }
 
 /**

package/telegram-plugin/gateway/user-failure-notices.ts

@@ -0,0 +1,172 @@
+/**
+ * user-failure-notices.ts — gateway-side handling of the plain-language
+ * "couldn't complete that" user notice, plus the `transport-transient`
+ * classifier kind (a mid-response stream abort reaching Anthropic).
+ *
+ * Two concerns, one subsystem (the plain user-failure-notice send side):
+ *
+ *  1. `emitTransportTransientEvent` — the calm path for a `transport-transient`
+ *     operator event. Claude Code emits `error: "server_error"` with NO HTTP
+ *     status on a mid-response stream abort; that is a transport failure, not an
+ *     account/auth/quota fault, and Claude retries it internally. So there is NO
+ *     broadcast card (a Reauth card would be the wrong remedy and reach every
+ *     chat). Instead: record for `/status` history, and DEFER one plain user
+ *     notice to the turn-end gate (`pending-user-notice.ts`) so a genuinely
+ *     reply-less dead turn still gets one calm line while a recovered retry
+ *     sends nothing. A BURST — >=3 terminal transport-transient events for one
+ *     agent within ~10min — escalates to exactly ONE operator-only, Dismiss-only
+ *     card ("repeated stream failures reaching Anthropic"), so honest
+ *     suppression never hides a genuinely degraded pipe.
+ *
+ *  2. `flushDeferredUserNotices` — the turn-end send loop for notices the gate
+ *     released (moved here from the gateway; see #3293 finding 1).
+ *
+ * Pure orchestration: every side effect (record, schedule, resolve, send, log,
+ * clock) crosses in through `UserFailureNoticeDeps`, so the outcomes are
+ * unit-testable with fakes and no gateway/grammy/IPC coupling leaks in.
+ */
+
+import { escapeMarkdown } from '../format.js'
+import type { InlineKeyboardMarkup, OperatorEvent } from '../operator-events.js'
+import type { PendingUserNotice } from '../pending-user-notice.js'
+
+// ─── transport-transient escalation counter (pure) ───────────────────────────
+
+const ESCALATION_WINDOW_MS = 10 * 60_000
+const ESCALATION_THRESHOLD = 3
+
+/** Per-agent sliding window of terminal transport-transient event timestamps. */
+const transportEscalation = new Map<string, number[]>()
+
+/**
+ * Record one terminal transport-transient event for `agent` at `now` and decide
+ * whether it crosses the escalation threshold. Returns `true` at most once per
+ * burst: crossing the threshold RESETS the window so a sustained outage emits
+ * one operator card per ~`windowMs`, not one per event.
+ */
+export function noteTransportTransientAndShouldEscalate(
+  agent: string,
+  now: number,
+  opts?: { windowMs?: number; threshold?: number },
+): boolean {
+  const windowMs = opts?.windowMs ?? ESCALATION_WINDOW_MS
+  const threshold = opts?.threshold ?? ESCALATION_THRESHOLD
+  const recent = (transportEscalation.get(agent) ?? []).filter((t) => now - t < windowMs)
+  recent.push(now)
+  if (recent.length >= threshold) {
+    transportEscalation.set(agent, [])
+    return true
+  }
+  transportEscalation.set(agent, recent)
+  return false
+}
+
+/** Test/reauth-recovery helper: forget the escalation window (all or one agent). */
+export function resetTransportTransientEscalation(agent?: string): void {
+  if (agent == null) transportEscalation.clear()
+  else transportEscalation.delete(agent)
+}
+
+/**
+ * The ONE operator-only card a transport-transient BURST escalates to. Dismiss-
+ * only — no Reauth (a dropped stream is not a credential fault), no failover
+ * (every account hits the same degraded pipe).
+ */
+export function renderTransportEscalationCard(agent: string): {
+  text: string
+  keyboard: InlineKeyboardMarkup
+} {
+  const a = escapeMarkdown(agent)
+  return {
+    text: [
+      `🔌 **Repeated stream failures** reaching Anthropic for **${a}**.`,
+      `3+ mid-response aborts within ~10 min. Turns retry automatically; if this persists, Anthropic's API may be degraded.`,
+    ].join('\n'),
+    keyboard: {
+      inline_keyboard: [
+        [{ text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(agent)}` }],
+      ],
+    },
+  }
+}
+
+// ─── Deps + orchestration ────────────────────────────────────────────────────
+
+export interface UserFailureNoticeDeps {
+  /** Injectable clock. */
+  now(): number
+  /** Allowlist chats (broadcast audience). */
+  allowFrom(): readonly string[]
+  /** Topic key of the live turn, or undefined (agent-level / between turns). */
+  liveTurnKey(): string | undefined
+  /** Persist to /status history (best-effort — must swallow its own errors). */
+  record(event: OperatorEvent): void
+  /** Schedule the turn-end-gated plain user notice for `chatIds`. */
+  scheduleUserNotice(input: {
+    chatIds: string[]
+    agent: string
+    kind: string
+    key: string | undefined
+    atMs: number
+  }): void
+  /** Release the notices resolved by this turn end (may be empty). */
+  resolveNotices(turnDeliveredReply: boolean, turnKey: string): PendingUserNotice[]
+  /** Topic-aware raw send (fire-and-forget). `keyboard` omitted → plain message. */
+  send(chatId: string, text: string, keyboard?: InlineKeyboardMarkup): void
+  /** stderr line (the gateway prefixes "telegram gateway: "). */
+  log(msg: string): void
+}
+
+/**
+ * Handle a `transport-transient` operator event: record it, defer the plain
+ * user notice to turn-end, and — on a burst — post exactly one operator-only
+ * escalation card. Never sends a broadcast card.
+ */
+export function emitTransportTransientEvent(
+  event: OperatorEvent,
+  deps: UserFailureNoticeDeps,
+): void {
+  const now = deps.now()
+  deps.record(event)
+  const escalate = noteTransportTransientAndShouldEscalate(event.agent, now)
+  deps.log(
+    `transport-transient agent=${event.agent} escalate=${escalate} ` +
+      `(no broadcast card; user-notice deferred to turn-end)`,
+  )
+  const allowFrom = deps.allowFrom()
+  if (allowFrom.length === 0) return
+  deps.scheduleUserNotice({
+    chatIds: [...allowFrom],
+    agent: event.agent,
+    kind: event.kind,
+    key: deps.liveTurnKey(),
+    atMs: now,
+  })
+  if (escalate) {
+    const card = renderTransportEscalationCard(event.agent)
+    deps.send(allowFrom[0], card.text, card.keyboard)
+  }
+}
+
+/**
+ * Turn-end resolution of deferred user failure notices (#3293 finding 1, moved
+ * out of gateway.ts). `turnDeliveredReply` is `finalAnswerDelivered ||
+ * replyCalled` — a delivered reply DROPS the notices (turn recovered); a
+ * reply-less end flushes them (turn genuinely died). `turnKey` scopes resolution
+ * to the ending turn's topic under keyed liveness.
+ */
+export function flushDeferredUserNotices(
+  turnDeliveredReply: boolean,
+  turnKey: string,
+  deps: UserFailureNoticeDeps,
+): void {
+  const notices = deps.resolveNotices(turnDeliveredReply, turnKey)
+  if (notices.length === 0) return
+  for (const notice of notices) {
+    deps.log(
+      `user-notice flush (turn died reply-less) agent=${notice.agent} ` +
+        `kind=${notice.kind} chats=${notice.chatIds.length}`,
+    )
+    for (const chatId of notice.chatIds) deps.send(chatId, notice.text)
+  }
+}

package/telegram-plugin/history.ts

@@ -373,6 +373,21 @@ export function verifyHistoryWritable(): { ok: boolean; error?: string } {
   }
 }
 
+/**
+ * Read-only handle for the gateway boot-briefing builder
+ * (`gateway/boot-briefing-wiring.ts`). Exposes only the `prepare(...).all`
+ * subset the builder's `BriefingDb` seam needs; returns null before
+ * `initHistory` (or when history is disabled) so the briefing degrades to
+ * empty instead of throwing. Do NOT use for writes — every write path goes
+ * through the record* functions above so redaction and validity checks
+ * cannot be bypassed.
+ */
+export function getHistoryDbForBriefing(): {
+  prepare(sql: string): { all(...params: unknown[]): unknown[] }
+} | null {
+  return db
+}
+
 /**
  * For tests — close the singleton and forget it. Production code never
  * needs this; the DB is held open for the lifetime of the process.