switchroom 0.19.48 → 0.20.0

package/telegram-plugin/gateway/gateway.ts

@@ -87,6 +87,7 @@ import {
 import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { FlushedTurnSupersedeRegistry } from '../flushed-turn-supersede.js'
 import { resolveReplyOwnerTurnWith, SUPERSEDE_OPEN_CAP_MS, SUPERSEDE_GRACE_MS } from './reply-owner-wiring.js'
+import { getBuzzMirror, maybeBootBuzzMirror } from './buzz-mirror.js'
 import { subagentReplyAuthority } from './subagent-reply-authority.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import {
@@ -410,6 +411,7 @@ import {
 import { createMcpFailureHook } from './mcp-failure-hook.js'
 import { pendingUserNoticeGate } from '../pending-user-notice.js'
 import { recordOperatorEvent } from '../operator-events-history.js'
+import { emitTransportTransientEvent, flushDeferredUserNotices, type UserFailureNoticeDeps } from './user-failure-notices.js'
 import {
   parseLlmError,
   renderLlmErrorSafe,
@@ -960,6 +962,8 @@ import {
   buildResumeDeferredReportInbound,
   decideBootResumeKind,
 } from './resume-inbound-builder.js'
+import { maybeQueueBootBriefing } from './boot-briefing-wiring.js'
+import { writePendingTurnEnv } from './pending-turn-env.js'
 import {
   createBridgeDeadWatchdog,
   consumeBridgeDeadEscalationMarker,
@@ -2034,35 +2038,9 @@ if (isGatewayMain) try {  // #2996 P0c: gated — opens bun:sqlite + writes .pen
 
   // Diagnostic env file (one-shot, sourced by start.sh) — kept for the
   // wake-audit context. The injected inbound above is the real wake signal;
-  // these vars are passive context only.
-  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=`,
-      ]
-      // Atomic write: tmp + rename. Without this, a crash mid-write
-      // (power loss, OOM, panic) leaves a truncated `.pending-turn.env`
-      // that start.sh `source`s — partial SWITCHROOM_PENDING_* vars
-      // or a malformed line break shell parsing inside the source.
-      const pendingEnvTmp = `${pendingEnvPath}.tmp-${process.pid}`
-      writeFileSync(pendingEnvTmp, lines.join('\n') + '\n', { mode: 0o600 })
-      renameSync(pendingEnvTmp, pendingEnvPath)
-      process.stderr.write(`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 })
-      process.stderr.write(`telegram gateway: pending-turn env cleared (clean previous shutdown)\n`)
-    }
-  } catch (err) {
-    process.stderr.write(`telegram gateway: pending-turn env write failed (${(err as Error).message})\n`)
-  }
+  // these vars are passive context only. Extracted to pending-turn-env.ts
+  // (atomic tmp+rename writer; never throws).
+  writePendingTurnEnv(agentDir, pending)
 } catch (err) {
   process.stderr.write(`telegram gateway: turn-registry init failed (${(err as Error).message}) — turn tracking disabled\n`)
   turnsDb = null
@@ -3690,7 +3668,7 @@ export type CurrentTurn = {
   // registry's older entries (and any hand-built test turn) tolerate its
   // absence; `emissionAuthorityFor` lazily backfills one when missing.
   emissionAuthority?: EmissionAuthority
-}
+  readonly originChannel: 'telegram' | 'buzz'; readonly buzzCoords?: { channelId: string; eventId: string; threadRoot: string } } // Buzz Phase 2a/2b: origin provenance stamped ONCE at the turn ctor via parseChannelOrigin(ev.rawContent) (channel-route.ts); buzzCoords present IFF originChannel==='buzz'. `readonly` enforces single-writer immutability (MINOR-2) — no `.originChannel=`/`.buzzCoords=` reassignment compiles. Types inlined + brace merged to hold gateway.ts at its zero-headroom ratchet (switchroom#2996); structurally identical to channel-route.ts Channel/BuzzCoords (type-identity asserted in channel-route.ts, MINOR-3).
 
 // PR-4e — the singleton `currentTurn` is RETAINED as (a) the flag-OFF store and
 // (b) the flag-ON "most-recent-set" MIRROR. Every GLOBAL-liveness read in this
@@ -7886,6 +7864,14 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   // 429 metrics — defense in depth, no secret survives in ANY downstream sink.
   event = { ...event, detail: redactOutboundText(event.detail, 'operator_event') }
 
+  // transport-transient (mid-response stream abort — `server_error`/`api_error`
+  // with no HTTP status): no broadcast card, no Reauth; record + deferred user
+  // notice, burst escalates. Orchestration in user-failure-notices.ts.
+  if (kind === 'transport-transient') {
+    emitTransportTransientEvent(event, userFailureNoticeDeps())
+    return
+  }
+
   // ── 429 throttle tier (operator spec: "retry in place under 5 min, else
   // mark + failover, honest reset messaging") ────────────────────────────
   // A terminal TRANSIENT ACCOUNT-scoped 429 — kind `rate-limited` carrying
@@ -8269,56 +8255,47 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // liveness only THAT topic's turn end resolves it (full rationale on
     // `PendingUserNotice.key`). `undefined` (no live turn — the event is
     // agent-level, empty wire chatId) keeps the legacy agent-wide resolution.
-    const liveTurn = currentTurn
-    const noticeKey =
-      liveTurn != null ? statusKey(liveTurn.sessionChatId, liveTurn.sessionThreadId) : undefined
-    pendingUserNoticeGate.schedule({
-      chatIds: userNoticeChats,
-      text: renderUserFacingFailureNotice(),
-      agent,
-      kind,
-      atMs: Date.now(),
-      key: noticeKey,
-    })
+    const noticeDeps = userFailureNoticeDeps()
+    const noticeKey = noticeDeps.liveTurnKey()
+    noticeDeps.scheduleUserNotice({ chatIds: userNoticeChats, agent, kind, key: noticeKey, atMs: Date.now() })
     process.stderr.write(
       `telegram gateway: operator-event user-notice deferred to turn-end agent=${agent} kind=${kind} chats=${userNoticeChats.length} topic=${noticeKey ?? '-'}\n`,
     )
   }
 }
 
+/**
+ * Live gateway deps for the plain user-failure-notice subsystem
+ * (`user-failure-notices.ts`): transport-transient handling AND the turn-end
+ * flush share this one wiring. Every side effect is a closure over live state.
+ */
+function userFailureNoticeDeps(): UserFailureNoticeDeps {
+  return {
+    now: () => Date.now(),
+    allowFrom: () => loadAccess().allowFrom,
+    liveTurnKey: () => currentTurn != null ? statusKey(currentTurn.sessionChatId, currentTurn.sessionThreadId) : undefined,
+    record: (e) => { try { recordOperatorEvent(e) } catch { /* history best-effort */ } },
+    scheduleUserNotice: (i) => pendingUserNoticeGate.schedule({ ...i, text: renderUserFacingFailureNotice() }),
+    resolveNotices: (delivered, key) => pendingUserNoticeGate.resolveTurnEnd(key, delivered),
+    send: (chat_id, text, keyboard) => {
+      const thread = topicForRecipient({ recipientChatId: chat_id, resolvedTopic: resolveAgentOutboundTopic({ kind: 'compact-watchdog' }), supergroupChatId: resolveAgentSupergroupChatId() })
+      const opts = { ...(keyboard ? { reply_markup: keyboard } : {}), ...(thread != null ? { message_thread_id: thread } : {}) }
+      // allow-raw-bot-api: user-failure-notice / transport escalation send; topic-aware opts
+      void bot.api.sendRichMessage(chat_id, richMessage(text), opts as never).catch((e) => process.stderr.write(`telegram gateway: user-failure-notice send to ${chat_id} failed: ${e}\n`))
+    },
+    log: (m) => process.stderr.write(`telegram gateway: ${m}\n`),
+  }
+}
+
 /**
  * Turn-end resolution of deferred user failure notices (#3293 finding 1).
  * Called from `endCurrentTurnAtomic` — the ONE funnel every turn-end path
  * passes through. `turnDeliveredReply` is `finalAnswerDelivered || replyCalled`
  * (the model explicitly replied → the turn recovered → notices are dropped by
- * the gate). Only a reply-less turn end flushes the pending notices to the
- * non-operator chats, so the user notice fires IFF the turn genuinely died.
- * `turnKey` (#3294) scopes resolution to the ending turn's topic — a concurrent
- * topic's pending notice is left for its own turn end under keyed liveness.
+ * the gate). The send loop lives in `user-failure-notices.ts`.
  */
 function flushPendingUserFailureNotices(turnDeliveredReply: boolean, turnKey: string): void {
-  const notices = pendingUserNoticeGate.resolveTurnEnd(turnKey, turnDeliveredReply)
-  if (notices.length === 0) return
-  const noticeTopic = resolveAgentOutboundTopic({ kind: 'compact-watchdog' })
-  const noticeSupergroup = resolveAgentSupergroupChatId()
-  for (const notice of notices) {
-    process.stderr.write(
-      `telegram gateway: user-notice flush (turn died reply-less) agent=${notice.agent} kind=${notice.kind} chats=${notice.chatIds.length}\n`,
-    )
-    for (const chat_id of notice.chatIds) {
-      const thread = topicForRecipient({ recipientChatId: chat_id, resolvedTopic: noticeTopic, supergroupChatId: noticeSupergroup })
-      const opts = {
-        ...(thread != null ? { message_thread_id: thread } : {}),
-      }
-      // allow-raw-bot-api: deferred user-notice flush loop; topic-aware opts
-      void bot.api.sendRichMessage(chat_id, richMessage(notice.text), opts as never)
-        .catch(e => {
-          process.stderr.write(
-            `telegram gateway: user-notice send to ${chat_id} failed agent=${notice.agent} kind=${notice.kind}: ${e}\n`,
-          )
-        })
-    }
-  }
+  flushDeferredUserNotices(turnDeliveredReply, turnKey, userFailureNoticeDeps())
 }
 
 /**
@@ -10196,6 +10173,22 @@ if (isGatewayMain && !STATIC && OBLIGATION_LEDGER_ENABLED) {
   setInterval(obligationSweep, OBLIGATION_SWEEP_MS).unref()
 }
 
+// Gateway boot briefing (session_continuity.briefing: gateway — default
+// legacy/off): a surface-scoped reorientation turn assembled from the durable
+// history DB and delivered as <channel source="boot_briefing"> over the spool
+// transport. Queued BEFORE the resume inbound below so a session that has
+// both reorients first, then resumes. All decision/build logic (flag,
+// --continue suppression, resume-window dedup, budget) lives in
+// boot-briefing-wiring.ts / boot-briefing-builder.ts; never throws.
+if (isGatewayMain && HISTORY_ENABLED) {
+  maybeQueueBootBriefing({
+    env: process.env,
+    stateDir: STATE_DIR,
+    resumeMsg: bootResumeInbound?.msg ?? null,
+    put: (agent, msg) =>
+      inboundSpool != null ? inboundSpool.put(agent, msg) : pendingInboundBuffer.push(agent, msg),
+  })
+}
 // Honest-restart-resume: inject the boot resume/report inbound built by the
 // registry classifier above. When the spool exists we only PUT it (the
 // boot-replay loop below pulls it into the in-memory buffer exactly once via
@@ -11760,8 +11753,12 @@ if (isGatewayMain) ipcServer = createIpcServer({
     )
   },
 
+  // Buzz Phase 2b: the duplex peer's advisory publish outcome — no-op unless the hub mirror booted.
+  onBuzzPublishResult: (_c, m) => getBuzzMirror()?.onPublishResult(m),
   log: (msg) => process.stderr.write(`telegram gateway: ipc — ${msg}\n`),
 })
+// Buzz Phase 2b: boot the hub mirror (dark unless channels.buzz.enabled + mode both); wires the peer transport, else a no-op.
+if (isGatewayMain) maybeBootBuzzMirror((msg) => ipcServer.sendToBuzzPeer(msg))
 
 // ─── Webhook ingest server (RFC webhook-via-gateway-socket) ───────────────
 // Under the Docker runtime the host-side web receiver runs as the operator
@@ -12504,21 +12501,15 @@ async function executeReply(
 function gatewaySendReplyDeps(): SendReplyGatewayDeps {
   return {
     // the ONE live instances (Amendment 1/9 — never re-new in a module)
-    outboundDedup,
-    flushedTurnSupersede,
-    firstTextReplyLogged,
-    suppressPtyPreview,
-    activeDraftStreams,
-    lastPtyPreviewByChat,
-    voiceOnDemandCache,
-    voicePreSynthQueue,
-    pendingProgress,
-    signalTracker,
+    outboundDedup, flushedTurnSupersede,
+    firstTextReplyLogged, suppressPtyPreview,
+    activeDraftStreams, lastPtyPreviewByChat,
+    voiceOnDemandCache, voicePreSynthQueue,
+    pendingProgress, signalTracker,
     silencePoke,
     getCurrentTurn: () => currentTurn,
     getLastActiveTurnChatId: () => lastActiveTurnChatId,
-    HISTORY_ENABLED,
-    TURN_ORIGIN_ROUTING_ENABLED,
+    HISTORY_ENABLED, TURN_ORIGIN_ROUTING_ENABLED,
     AUTOCLASSIFY_MIDTURN_SHADOW,
     MAX_ATTACHMENT_BYTES,
     MAX_CHUNK_LIMIT,
@@ -12533,8 +12524,7 @@ function gatewaySendReplyDeps(): SendReplyGatewayDeps {
     statusKey,
     streamKey,
     resolveReplyOwnerTurn,
-    findTurnByOriginId,
-    findTurnByQuotedMessageId,
+    findTurnByOriginId, findTurnByQuotedMessageId, findLatestTurnForChat,
     resolveAnswerThreadWithLog,
     resolveThreadId,
     getLatestInboundMessageId,
@@ -13282,6 +13272,8 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
       process.stderr.write(`telegram gateway: history recordEdit failed: ${err}\n`)
     }
   }
+  // Buzz Phase 2b: mirror the edit as a debounced Buzz correction keyed on the edited id — no-op when Buzz is dark or the message was never published; post-delivery, never throws.
+  getBuzzMirror()?.mirrorCorrection({ telegramMessageKey: `${String(args.chat_id ?? '')}:${Number(args.message_id)}`, scrubbedText: editRawText })
   return { content: [{ type: 'text', text: `edited (id: ${id})` }] }
 }
 

package/telegram-plugin/gateway/inbound-spool.ts

@@ -96,6 +96,15 @@ export function spoolId(msg: InboundMessage): string {
   ) {
     return `s:resume:${msg.meta.resume_turn_key}`
   }
+  // Gateway boot briefing (session_continuity.briefing: gateway): keyed
+  // per chat, NOT per boot — the synthetic messageId is the boot's ts, so
+  // without this a multi-restart sequence would stack one briefing per
+  // boot. One live briefing per chat at a time; once delivered (acked) a
+  // later boot can mint a fresh one. Staleness is separately bounded by
+  // the entry's meta.expiresAt TTL (see liveEntries).
+  if (msg.meta?.source === 'boot_briefing') {
+    return `s:boot-briefing:${msg.chatId}`
+  }
   // Cron BOOT-REPLAY (#2793 part B): a scheduled fire that the boot
   // replay re-injects because it was missed across a restart. Keyed on
   // the minute-aligned fire it is replaying (`replay_fire_ms`) plus the
@@ -488,7 +497,30 @@ export function createInboundSpool(opts: InboundSpoolOptions): InboundSpool {
   return {
     put(agent, msg) {
       const id = spoolId(msg)
-      if (live.has(id)) return false // dedup: already spooled & un-acked
+      const existing = live.get(id)
+      if (existing != null) {
+        // Dedup: the same logical event is already spooled and un-acked, so
+        // by default drop the duplicate (retried synthetics of one event).
+        //
+        // Exception (#4246): a boot_briefing is keyed per chat, NOT per boot
+        // (spoolId `s:boot-briefing:<chatId>`), so a LATER boot re-puts a
+        // FRESHER briefing under the same id. The strict-dedup path kept
+        // boot-1's now-stale text, so a boot-2 delivery carried boot-1's
+        // briefing (only self-corrected by the 60-min TTL). Refresh the
+        // entry's payload in place so the newest briefing wins, keeping the
+        // original firstAt so escalation timing isn't reset by repeated
+        // restarts. The refreshed put is re-appended durably (hydrate's
+        // "last put for an id wins" restores it across a crash). No new live
+        // entry is created, so this can never double-deliver.
+        if (msg.meta?.source === 'boot_briefing') {
+          existing.agent = agent
+          existing.msg = msg
+          appendRecord({ t: 'put', id, agent, msg, firstAt: existing.firstAt })
+          maybeCompact()
+          return true
+        }
+        return false
+      }
       const firstAt = now()
       live.set(id, { agent, msg, firstAt })
       appendRecord({ t: 'put', id, agent, msg, firstAt })

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;