switchroom 0.20.0 → 0.20.1

package/bin/handoff-briefing.sh

@@ -47,7 +47,29 @@ HINDSIGHT_BANK="${HINDSIGHT_BANK_ID:-}"
 AGENT_DIR="${AGENT_DIR:-}"
 WORKSPACE_DIR="${WORKSPACE_DIR:-$AGENT_DIR}"
 MAX_MESSAGES="${HANDOFF_BRIEFING_MAX_MESSAGES:-20}"
-HINDSIGHT_TIMEOUT="${HANDOFF_BRIEFING_HINDSIGHT_TIMEOUT:-4}"
+# Hindsight is the only network hop; cap it at 3s so it finishes well inside
+# start.sh's outer `timeout 10` kill budget (was 4s under a 5s outer, which
+# left almost no margin — a slow recall could be killed mid-write). Local
+# SQLite + daily-memory reads are sub-second, so 3s is the whole network cost.
+HINDSIGHT_TIMEOUT="${HANDOFF_BRIEFING_HINDSIGHT_TIMEOUT:-3}"
+
+# Chat/thread scope for the recent-conversation section (#continuity). A
+# forum/group agent's history.db holds messages from many topics; an unscoped
+# "last 20" briefing pollutes the reorientation with unrelated threads. Prefer
+# the surface that was mid-turn when the prior session ended (exported by
+# start.sh from the pending-turn env on an interrupted boot); otherwise the
+# python fallback derives the single most-recently-active (chat_id, thread_id)
+# surface straight from the DB. Empty chat ⇒ let python derive it.
+#
+# TARGET_THREAD_ID is tri-state: a numbered thread scopes to that topic; the
+# literal sentinel `NULL` means the surface's thread is genuinely NULL (a DM /
+# forum General topic) and scopes with `thread_id IS NULL`; empty means the
+# thread is UNKNOWN and falls back to chat-only scope (all threads). The
+# pending-turn env writer emits `NULL` when it knows the interrupted turn's
+# thread was null, so a General-topic interrupt reboots correctly scoped
+# instead of pulling in every other topic's messages.
+TARGET_CHAT_ID="${SWITCHROOM_PENDING_CHAT_ID:-}"
+TARGET_THREAD_ID="${SWITCHROOM_PENDING_THREAD_ID:-}"
 
 # Determine output mode
 STDOUT_MODE=0
@@ -61,28 +83,119 @@ if [ -n "$TELEGRAM_STATE" ] && [ -d "$TELEGRAM_STATE" ]; then
   HISTORY_DB="$TELEGRAM_STATE/history.db"
   if [ -f "$HISTORY_DB" ] && command -v python3 >/dev/null 2>&1; then
     # Use python3's stdlib sqlite3 — no bun:sqlite, no extra deps.
-    # Query the most recent $MAX_MESSAGES rows ordered by ts DESC, then
-    # reverse for chronological display. We skip system messages (role NULL).
-    TELEGRAM_ROWS=$(python3 - "$HISTORY_DB" "$MAX_MESSAGES" 2>/dev/null <<'PYEOF'
+    # Query the most recent $MAX_MESSAGES rows for the ACTIVE surface only
+    # (chat/thread-scoped, see above), ordered by ts DESC, then reverse for
+    # chronological display. We skip system messages (role NULL). The scope
+    # source is logged to stderr for boot diagnostics.
+    # python stderr is NOT suppressed: the script's only stderr output is the
+    # intentional scope breadcrumb + a single graceful line on any caught error
+    # (every DB path is wrapped in try/except → sys.exit(0)). start.sh runs this
+    # under `2>/dev/null`, so the breadcrumb is a debug/manual-run diagnostic.
+    TELEGRAM_ROWS=$(python3 - "$HISTORY_DB" "$MAX_MESSAGES" "$TARGET_CHAT_ID" "$TARGET_THREAD_ID" <<'PYEOF'
 import sys, sqlite3, datetime
 
 db_path = sys.argv[1]
 limit = int(sys.argv[2])
+target_chat = sys.argv[3] if len(sys.argv) > 3 else ""
+target_thread = sys.argv[4] if len(sys.argv) > 4 else ""
 
 try:
     conn = sqlite3.connect(db_path)
     conn.row_factory = sqlite3.Row
     cur = conn.cursor()
-    # Fetch most recent rows; reverse for chronological output.
+
+    # Resolve the surface to scope to.
+    #  - explicit env target (pending-turn chat/thread) wins — UNLESS that chat
+    #    has zero rows (rotated/fresh DB), in which case we fall through to
+    #    db-latest so a stale env target doesn't yield an empty section;
+    #  - else derive the single most-recently-active (chat_id, thread_id).
+    # thread is tri-state: a real value, NULL (DM / general), or unknown.
+    #  - target_thread == "NULL" (sentinel from start.sh / pending-turn-env)
+    #    means the surface's thread is GENUINELY NULL (DM / general topic) —
+    #    scope with `thread_id IS NULL`, do NOT pull in numbered-thread rows.
+    #  - target_thread == "" (empty) means UNKNOWN — chat-only scope (all
+    #    threads), the safe backward-compatible fallback.
+    scope_chat = None
+    scope_thread = None          # int thread id
+    scope_thread_known = False   # True once we know the exact thread (incl. NULL)
+    scope_thread_is_null = False # True when the surface's thread is NULL
+    scope_source = "unscoped"
+
+    def _chat_has_rows(chat_id):
+        cur.execute(
+            "SELECT 1 FROM messages WHERE role IN ('user', 'assistant') "
+            "AND chat_id = ? LIMIT 1",
+            [chat_id],
+        )
+        return cur.fetchone() is not None
+
+    def _derive_db_latest():
+        # The single most-recently-active (chat_id, thread_id) surface.
+        cur.execute(
+            """
+            SELECT chat_id, thread_id
+            FROM messages
+            WHERE role IN ('user', 'assistant')
+            ORDER BY ts DESC
+            LIMIT 1
+            """
+        )
+        return cur.fetchone()
+
+    # Env target — accept it only when its chat actually has rows (2b). A
+    # rotated/fresh DB can leave a pending-turn chat with no persisted
+    # messages; scoping to it would silently emit an empty section, so we
+    # fall through to db-latest instead.
+    if target_chat and _chat_has_rows(target_chat):
+        scope_chat = target_chat
+        scope_source = "env"
+        if target_thread == "NULL":
+            scope_thread_is_null = True
+            scope_thread_known = True
+        elif target_thread != "":
+            try:
+                scope_thread = int(target_thread)
+                scope_thread_known = True
+            except ValueError:
+                scope_thread = None  # unparseable → chat-only scope
+        # else: unknown thread → chat-only scope (all threads of the chat)
+
+    if scope_chat is None:
+        latest = _derive_db_latest()
+        if latest is not None:
+            scope_chat = latest["chat_id"]
+            scope_source = "db-latest"
+            scope_thread_known = True
+            if latest["thread_id"] is None:
+                scope_thread_is_null = True
+            else:
+                scope_thread = latest["thread_id"]
+
+    if scope_chat is None:
+        # Empty DB (nothing to scope) — nothing to show.
+        sys.stderr.write("handoff-briefing: no messages to scope; empty section\n")
+        sys.exit(0)
+
+    where = ["role IN ('user', 'assistant')", "chat_id = ?"]
+    params = [scope_chat]
+    if scope_thread_known:
+        if scope_thread_is_null:
+            where.append("thread_id IS NULL")
+        else:
+            where.append("thread_id = ?")
+            params.append(scope_thread)
+    params.append(limit)
+
+    sys.stderr.write(
+        "handoff-briefing: scoping recent conversation to chat=%s thread=%s (source=%s)\n"
+        % (scope_chat, "NULL" if scope_thread_is_null else (scope_thread if scope_thread_known else "any"), scope_source)
+    )
+
     cur.execute(
-        """
-        SELECT role, user, ts, text
-        FROM messages
-        WHERE role IN ('user', 'assistant')
-        ORDER BY ts DESC
-        LIMIT ?
-        """,
-        (limit,),
+        "SELECT role, user, ts, text FROM messages WHERE "
+        + " AND ".join(where)
+        + " ORDER BY ts DESC LIMIT ?",
+        params,
     )
     rows = list(reversed(cur.fetchall()))
     conn.close()
@@ -110,6 +223,70 @@ $TELEGRAM_ROWS"
   fi
 fi
 
+# ── Header (cheap, no network) — computed early so the recent-conversation
+# section can be flushed to disk BEFORE the slow Hindsight hop. ──────────────
+# Restart timestamp — model-facing: it lands in the resume-turn system prompt
+# via --append-system-prompt ("You just restarted at …"). Render the agent's
+# LOCAL am/pm wall clock, NOT UTC, so the restart turn never sees a competing
+# UTC "now". Same SWITCHROOM_TIMEZONE → TZ → UTC cascade the daily section uses.
+_TZ_VAL="${SWITCHROOM_TIMEZONE:-${TZ:-UTC}}"
+TIMESTAMP=$(TZ="$_TZ_VAL" date '+%A %Y-%m-%d %I:%M %p %Z' 2>/dev/null || date '+%A %Y-%m-%d %I:%M %p %Z')
+RESTART_REASON="unknown"
+if [ -n "$AGENT_DIR" ] && [ -f "$AGENT_DIR/.restart-reason" ]; then
+  RESTART_REASON=$(cat "$AGENT_DIR/.restart-reason" 2>/dev/null | head -1 | tr -d '\r\n')
+fi
+if [ -n "${SWITCHROOM_PENDING_ENDED_VIA:-}" ]; then
+  RESTART_REASON="$SWITCHROOM_PENDING_ENDED_VIA"
+fi
+BRIEFING_HEADER="You just restarted at ${TIMESTAMP}. Previous session ended via: ${RESTART_REASON}. Consult this briefing before responding."
+
+# Resolve the output destination up front (file mode only).
+OUTPUT_FILE=""
+OUTPUT_TMP=""
+if [ "$STDOUT_MODE" != "1" ] && [ -n "$AGENT_DIR" ]; then
+  OUTPUT_FILE="$AGENT_DIR/.handoff-briefing.md"
+  OUTPUT_TMP="${OUTPUT_FILE}.tmp.$$"
+fi
+
+# Incremental emit (#continuity). Sections are flushed to the output file as
+# each source resolves — the recent-conversation section (the highest-value,
+# always-local part) is written BEFORE the network-bound Hindsight hop. So a
+# late-stage kill (e.g. start.sh's outer `timeout`, SIGTERM by default) mid-Hindsight still
+# leaves the recent conversation on disk instead of nothing. The first flush
+# writes header+section atomically via tmp+mv; later sections append. In
+# stdout/no-AGENT_DIR mode we buffer and print once at the end instead.
+FILE_STARTED=0
+STDOUT_BUFFER=""
+emit_section() {
+  # $1 = section content (assumed non-empty)
+  section="$1"
+  if [ -n "$OUTPUT_FILE" ]; then
+    if [ "$FILE_STARTED" = "0" ]; then
+      # First section: header + divider + section, written atomically.
+      printf '%s\n\n---\n\n%s' "$BRIEFING_HEADER" "$section" > "$OUTPUT_TMP" \
+        && mv -f "$OUTPUT_TMP" "$OUTPUT_FILE"
+      FILE_STARTED=1
+    else
+      printf '\n\n---\n\n%s' "$section" >> "$OUTPUT_FILE"
+    fi
+  else
+    if [ -z "$STDOUT_BUFFER" ]; then
+      STDOUT_BUFFER="$section"
+    else
+      STDOUT_BUFFER="$STDOUT_BUFFER
+
+---
+
+$section"
+    fi
+  fi
+}
+
+# Flush the recent-conversation section NOW, before Hindsight.
+if [ -n "$TELEGRAM_SECTION" ]; then
+  emit_section "$TELEGRAM_SECTION"
+fi
+
 # ── Source 2: Hindsight recall ──────────────────────────────────────────────────
 HINDSIGHT_SECTION=""
 if [ -n "$HINDSIGHT_URL" ] && [ -n "$HINDSIGHT_BANK" ] && command -v curl >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
@@ -133,14 +310,16 @@ $RECALL_TEXT"
     fi
   fi
 fi
+if [ -n "$HINDSIGHT_SECTION" ]; then
+  emit_section "$HINDSIGHT_SECTION"
+fi
 
 # ── Source 3: Today's daily memory ─────────────────────────────────────────────
-# Resolve "today" in the agent's LOCAL time — NOT the process default (UTC on
-# most hosts/CI). TODAY keys the daily-memory lookup (memory/${TODAY}.md); using
-# UTC here would look up the wrong day's file during the window where the local
-# date is ahead of/behind UTC, silently dropping today's memory. Same
-# SWITCHROOM_TIMEZONE → TZ → UTC cascade the restart-timestamp render below uses.
-_TZ_VAL="${SWITCHROOM_TIMEZONE:-${TZ:-UTC}}"
+# TODAY keys the daily-memory lookup (memory/${TODAY}.md) in the agent's LOCAL
+# time (_TZ_VAL, resolved in the header block above) — NOT the process default
+# (UTC on most hosts/CI). Using UTC here would look up the wrong day's file
+# during the window where the local date is ahead of/behind UTC, silently
+# dropping today's memory.
 DAILY_SECTION=""
 TODAY=$(TZ="$_TZ_VAL" date +%Y-%m-%d 2>/dev/null || date +%Y-%m-%d 2>/dev/null || true)
 if [ -n "$TODAY" ] && [ -n "$WORKSPACE_DIR" ]; then
@@ -154,66 +333,26 @@ $DAILY_CONTENT"
     fi
   fi
 fi
-
-# ── Assemble briefing ───────────────────────────────────────────────────────────
-# Restart timestamp — model-facing: it lands in the resume-turn system prompt
-# via --append-system-prompt ("You just restarted at …"). Render the agent's
-# LOCAL am/pm wall clock, NOT UTC, so the restart turn never sees a competing
-# UTC "now" (the whole point of the deterministic-local-time work). Same
-# SWITCHROOM_TIMEZONE → TZ → UTC cascade and `%A %Y-%m-%d %I:%M %p %Z` am/pm
-# format the UserPromptSubmit local-time hook (bin/timezone-hook.sh) uses.
-# (_TZ_VAL is computed once above, in the daily-memory section.)
-TIMESTAMP=$(TZ="$_TZ_VAL" date '+%A %Y-%m-%d %I:%M %p %Z' 2>/dev/null || date '+%A %Y-%m-%d %I:%M %p %Z')
-
-# Determine restart reason if available
-RESTART_REASON="unknown"
-if [ -n "$AGENT_DIR" ] && [ -f "$AGENT_DIR/.restart-reason" ]; then
-  RESTART_REASON=$(cat "$AGENT_DIR/.restart-reason" 2>/dev/null | head -1 | tr -d '\r\n')
+if [ -n "$DAILY_SECTION" ]; then
+  emit_section "$DAILY_SECTION"
 fi
-# Also check SWITCHROOM_PENDING_ENDED_VIA if set by start.sh
-if [ -n "${SWITCHROOM_PENDING_ENDED_VIA:-}" ]; then
-  RESTART_REASON="$SWITCHROOM_PENDING_ENDED_VIA"
-fi
-
-# Build the briefing body
-SECTIONS=""
-for section in "$TELEGRAM_SECTION" "$HINDSIGHT_SECTION" "$DAILY_SECTION"; do
-  if [ -n "$section" ]; then
-    if [ -n "$SECTIONS" ]; then
-      SECTIONS="$SECTIONS
-
----
 
-$section"
-    else
-      SECTIONS="$section"
-    fi
+# ── Finalize ────────────────────────────────────────────────────────────────────
+# Every section was flushed as it resolved (emit_section). Here we only close
+# out the chosen sink. An all-empty briefing wrote nothing — leave it that way
+# so start.sh skips the --append-system-prompt arg.
+if [ -n "$OUTPUT_FILE" ]; then
+  # File mode. FILE_STARTED=1 means at least one section was written atomically
+  # (header+first) with the rest appended; add the trailing newline the
+  # single-shot writer used to emit. If nothing was written, no file exists.
+  if [ "$FILE_STARTED" = "1" ]; then
+    printf '\n' >> "$OUTPUT_FILE"
   fi
-done
-
-# Empty briefing — nothing to inject
-if [ -z "$SECTIONS" ]; then
-  exit 0
-fi
-
-BRIEFING="You just restarted at ${TIMESTAMP}. Previous session ended via: ${RESTART_REASON}. Consult this briefing before responding.
-
----
-
-${SECTIONS}"
-
-# ── Output ──────────────────────────────────────────────────────────────────────
-if [ "$STDOUT_MODE" = "1" ]; then
-  printf '%s\n' "$BRIEFING"
 else
-  if [ -z "$AGENT_DIR" ]; then
-    # Fallback: write to stdout if AGENT_DIR is not set
-    printf '%s\n' "$BRIEFING"
-    exit 0
+  # stdout / no-AGENT_DIR mode — buffered; print the whole briefing once.
+  if [ -n "$STDOUT_BUFFER" ]; then
+    printf '%s\n\n---\n\n%s\n' "$BRIEFING_HEADER" "$STDOUT_BUFFER"
   fi
-  OUTPUT_FILE="$AGENT_DIR/.handoff-briefing.md"
-  OUTPUT_TMP="${OUTPUT_FILE}.tmp.$$"
-  printf '%s\n' "$BRIEFING" > "$OUTPUT_TMP" && mv -f "$OUTPUT_TMP" "$OUTPUT_FILE"
 fi
 
 exit 0

package/dist/agent-scheduler/index.js

@@ -11362,7 +11362,7 @@ var BuzzChannelSchema = exports_external.object({
   default_channel_id: exports_external.string().describe("Relay-minted group UUID (the NIP-29 `h` tag) the sidecar subscribes " + "to and stamps on injected turns."),
   channel_map: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional map of extra group UUIDs → friendly labels."),
   pubkey_names: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional petnames: hex/npub pubkey → display name, used to label " + "the sender on injected turns."),
-  pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). The compat-check warns on mismatch; " + "advisory in Phase 1.")
+  pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). RESERVED — no consumer of this field " + "exists; the existing compat-check (compat-check.ts) validates only " + "the wire contract (AUTH kind, message kind, tag names) and does not " + "read this field. Kept in the schema so the intended digest-pin can " + "be wired without a config shape change.")
 }).strict();
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema,

package/dist/auth-broker/index.js

@@ -11387,7 +11387,7 @@ var init_schema = __esm(() => {
     default_channel_id: exports_external.string().describe("Relay-minted group UUID (the NIP-29 `h` tag) the sidecar subscribes " + "to and stamps on injected turns."),
     channel_map: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional map of extra group UUIDs → friendly labels."),
     pubkey_names: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional petnames: hex/npub pubkey → display name, used to label " + "the sender on injected turns."),
-    pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). The compat-check warns on mismatch; " + "advisory in Phase 1.")
+    pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). RESERVED — no consumer of this field " + "exists; the existing compat-check (compat-check.ts) validates only " + "the wire contract (AUTH kind, message kind, tag names) and does not " + "read this field. Kept in the schema so the intended digest-pin can " + "be wired without a config shape change.")
   }).strict();
   ChannelsSchema = exports_external.object({
     telegram: TelegramChannelSchema,

package/dist/buzz-gateway/index.js

@@ -1,5 +1,5 @@
 // src/buzz-gateway/index.ts
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 
 // node_modules/.bun/@noble+hashes@2.0.1/node_modules/@noble/hashes/utils.js
 /*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
@@ -8874,6 +8874,20 @@ async function publishOutbound(req, secretKey, transport, nowSec) {
   }
   return { ok: true, eventId: signed.eventId };
 }
+async function publishOutboundTallied(req, secretKey, transport, tally, nowSec) {
+  let result;
+  try {
+    result = await publishOutbound(req, secretKey, transport, nowSec);
+  } catch {
+    tally.failed += 1;
+    return { ok: false, error: "publish failed: transport threw" };
+  }
+  if (result.ok)
+    tally.ok += 1;
+  else
+    tally.failed += 1;
+  return result;
+}
 
 // src/buzz-gateway/inbound-map.ts
 var BUZZ_MESSAGE_KIND = 9;
@@ -8898,6 +8912,22 @@ function resolveThreadRoot(ev) {
     return eTags[0][1];
   return ev.id;
 }
+function resolveReplyParent(ev) {
+  const eTags = ev.tags.filter((t) => t[0] === "e" && typeof t[1] === "string");
+  if (eTags.length === 0)
+    return;
+  const hasMarkers = eTags.some((t) => t[3] === "root" || t[3] === "reply" || t[3] === "mention");
+  if (hasMarkers) {
+    const reply = eTags.find((t) => t[3] === "reply");
+    if (reply)
+      return reply[1];
+    const root = eTags.find((t) => t[3] === "root");
+    if (root)
+      return root[1];
+    return;
+  }
+  return eTags[eTags.length - 1][1];
+}
 function resolveChannelId(ev, fallback) {
   const h = ev.tags.find((t) => t[0] === "h" && typeof t[1] === "string");
   return h ? h[1] : fallback;
@@ -8907,14 +8937,16 @@ function mapBuzzEvent(ev, ctx) {
     return null;
   const channelId = resolveChannelId(ev, ctx.groupId);
   const threadRoot = resolveThreadRoot(ev);
+  const replyTo = resolveReplyParent(ev);
   const user = senderLabel(ev.pubkey, ctx.pubkeyNames);
-  const text = `<channel source="buzz" ` + `buzz_channel_id="${escapeAttr(channelId)}" ` + `buzz_event_id="${escapeAttr(ev.id)}" ` + `buzz_pubkey="${escapeAttr(ev.pubkey)}" ` + `buzz_thread_root="${escapeAttr(threadRoot)}" ` + `user="${escapeAttr(user)}">` + escapeBody(ev.content) + `</channel>`;
+  const text = `<channel source="buzz" ` + `buzz_channel_id="${escapeAttr(channelId)}" ` + `buzz_event_id="${escapeAttr(ev.id)}" ` + `buzz_pubkey="${escapeAttr(ev.pubkey)}" ` + `buzz_thread_root="${escapeAttr(threadRoot)}" ` + (replyTo !== undefined ? `buzz_reply_to="${escapeAttr(replyTo)}" ` : "") + `user="${escapeAttr(user)}">` + escapeBody(ev.content) + `</channel>`;
   const meta = {
     source: "buzz",
     buzz_channel_id: channelId,
     buzz_event_id: ev.id,
     buzz_pubkey: ev.pubkey,
     buzz_thread_root: threadRoot,
+    ...replyTo !== undefined ? { buzz_reply_to: replyTo } : {},
     user
   };
   return {
@@ -9052,6 +9084,110 @@ function createRetryQueue(deps) {
   };
 }
 
+// src/buzz-gateway/heartbeat.ts
+import {
+  mkdirSync as realMkdirSync,
+  writeFileSync as realWriteFileSync
+} from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+var BUZZ_HEARTBEAT_SUBDIR = "buzz";
+var BUZZ_HEARTBEAT_FILE = "buzz-sidecar.heartbeat.json";
+var BUZZ_HEARTBEAT_INTERVAL_MS = 60 * 1000;
+var BUZZ_HEARTBEAT_STALE_MULTIPLIER = 3;
+var BUZZ_HEARTBEAT_STALE_MS = BUZZ_HEARTBEAT_INTERVAL_MS * BUZZ_HEARTBEAT_STALE_MULTIPLIER;
+var BUZZ_HEARTBEAT_MAX_INTERVAL_MS = BUZZ_HEARTBEAT_STALE_MS / BUZZ_HEARTBEAT_STALE_MULTIPLIER;
+function resolveStatsIntervalMs(raw) {
+  const requested = Number(raw);
+  if (!Number.isFinite(requested) || requested <= 0) {
+    return BUZZ_HEARTBEAT_INTERVAL_MS;
+  }
+  return Math.min(requested, BUZZ_HEARTBEAT_MAX_INTERVAL_MS);
+}
+function buzzHeartbeatStatePath(stateDir) {
+  return join2(stateDir, BUZZ_HEARTBEAT_SUBDIR, BUZZ_HEARTBEAT_FILE);
+}
+function writeBuzzHeartbeat(path, hb, io = {}) {
+  const mkdir = io.mkdirSync ?? realMkdirSync;
+  const write = io.writeFileSync ?? realWriteFileSync;
+  mkdir(dirname2(path), { recursive: true });
+  write(path, JSON.stringify(hb));
+}
+
+// src/buzz-gateway/stats.ts
+var REJECT_PREFIX = "rejected:";
+function summarizePipeline(pumpStats, mirror) {
+  let received = 0;
+  let authFailures = 0;
+  for (const [key, count] of Object.entries(pumpStats)) {
+    received += count;
+    if (key.startsWith(REJECT_PREFIX))
+      authFailures += count;
+  }
+  return {
+    received,
+    injected: pumpStats.injected ?? 0,
+    duplicate: pumpStats.duplicate ?? 0,
+    queued: pumpStats.queued ?? 0,
+    injectFailed: pumpStats.inject_failed ?? 0,
+    droppedByKind: pumpStats.unmapped ?? 0,
+    channelOff: pumpStats.channel_off ?? 0,
+    authFailures,
+    mirrorOk: mirror.ok,
+    mirrorFailed: mirror.failed
+  };
+}
+function formatStatsLine(s) {
+  return `buzz stats: received=${s.received} injected=${s.injected} ` + `duplicate=${s.duplicate} queued=${s.queued} inject_failed=${s.injectFailed} ` + `dropped_by_kind=${s.droppedByKind} channel_off=${s.channelOff} ` + `auth_failures=${s.authFailures} mirror_ok=${s.mirrorOk} mirror_failed=${s.mirrorFailed}`;
+}
+function createStatsReporter(deps) {
+  const intervalMs = deps.intervalMs && deps.intervalMs > 0 ? deps.intervalMs : 60000;
+  const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((t) => clearTimeout(t));
+  let timer = null;
+  let stopped = false;
+  let lastLine = null;
+  function tick() {
+    const sample = deps.sample();
+    const line = formatStatsLine(sample.summary);
+    if (line !== lastLine) {
+      deps.emit(line);
+      lastLine = line;
+    }
+    try {
+      deps.persist?.(sample);
+    } catch {}
+  }
+  function schedule() {
+    if (stopped)
+      return;
+    timer = setTimer(() => {
+      timer = null;
+      if (stopped)
+        return;
+      tick();
+      schedule();
+    }, intervalMs);
+    if (timer && typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  return {
+    start() {
+      stopped = false;
+      tick();
+      schedule();
+    },
+    stop() {
+      stopped = true;
+      if (timer !== null) {
+        clearTimer(timer);
+        timer = null;
+      }
+    },
+    tick
+  };
+}
+
 // src/buzz-gateway/index.ts
 function log(msg) {
   process.stderr.write(`buzz-gateway: ${msg}
@@ -9123,8 +9259,8 @@ async function main() {
   const agentPubkey = getPublicKey(secretKey).toLowerCase();
   log(`booted agent=${config.agentName} relay=${config.relayUrl} group=${config.groupId} allowlist=${config.authorized.size}`);
   const stateDir = process.env.TELEGRAM_STATE_DIR ?? "/state/agent/telegram";
-  const socketPath = process.env.SWITCHROOM_GATEWAY_SOCKET ?? join2(stateDir, "gateway.sock");
-  const journalPath = process.env.BUZZ_JOURNAL_PATH ?? join2(stateDir, "buzz", "journal.jsonl");
+  const socketPath = process.env.SWITCHROOM_GATEWAY_SOCKET ?? join3(stateDir, "gateway.sock");
+  const journalPath = process.env.BUZZ_JOURNAL_PATH ?? join3(stateDir, "buzz", "journal.jsonl");
   const dedup = createDedupStore({ journalPath, log });
   const ipcClient = createInjectIpcClient({ socketPath, log });
   const inject = makeInject(ipcClient, config.agentName);
@@ -9158,16 +9294,17 @@ async function main() {
     log
   });
   const publishTransport = (event, timeoutMs) => nostr.publish(event, timeoutMs);
+  const mirror = { ok: 0, failed: 0 };
   const buzzPeer = createBuzzPeerClient({
     socketPath,
     agentName: config.agentName,
     onOutbound: async (req) => {
-      const result = await publishOutbound({
+      const result = await publishOutboundTallied({
         channelId: req.channelId,
         replyToEventId: req.replyToEventId,
         threadRootId: req.threadRootId,
         payload: req.payload
-      }, secretKey, publishTransport);
+      }, secretKey, publishTransport, mirror);
       return {
         type: "buzz_publish_result",
         correlationId: req.correlationId,
@@ -9178,8 +9315,30 @@ async function main() {
     },
     log
   });
+  const bootTs = Date.now();
+  const heartbeatPath = buzzHeartbeatStatePath(stateDir);
+  const statsIntervalMs = resolveStatsIntervalMs(process.env.BUZZ_STATS_INTERVAL_MS);
+  const statsReporter = createStatsReporter({
+    intervalMs: statsIntervalMs,
+    sample: () => ({
+      summary: summarizePipeline(pump.stats, mirror),
+      subscribed: nostr.isSubscribed()
+    }),
+    emit: (line) => log(line),
+    persist: (sample) => writeBuzzHeartbeat(heartbeatPath, {
+      v: 1,
+      agent: config.agentName,
+      ts: Date.now(),
+      bootTs,
+      subscribed: sample.subscribed,
+      stats: sample.summary
+    })
+  });
   const shutdown = () => {
     log("shutting down");
+    try {
+      statsReporter.stop();
+    } catch {}
     try {
       nostr.stop();
     } catch {}
@@ -9200,6 +9359,7 @@ async function main() {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
   nostr.start();
+  statsReporter.start();
 }
 main().catch((err) => {
   log(`FATAL: ${err.message}`);

package/dist/cli/notion-write-pretool.mjs

@@ -12123,7 +12123,7 @@ var BuzzChannelSchema = exports_external.object({
   default_channel_id: exports_external.string().describe("Relay-minted group UUID (the NIP-29 `h` tag) the sidecar subscribes " + "to and stamps on injected turns."),
   channel_map: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional map of extra group UUIDs \u2192 friendly labels."),
   pubkey_names: exports_external.record(exports_external.string(), exports_external.string()).default({}).describe("Optional petnames: hex/npub pubkey \u2192 display name, used to label " + "the sender on injected turns."),
-  pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). The compat-check warns on mismatch; " + "advisory in Phase 1.")
+  pinned_relay_digest: exports_external.string().optional().describe("Pinned relay image digest (M4). RESERVED \u2014 no consumer of this field " + "exists; the existing compat-check (compat-check.ts) validates only " + "the wire contract (AUTH kind, message kind, tag names) and does not " + "read this field. Kept in the schema so the intended digest-pin can " + "be wired without a config shape change.")
 }).strict();
 var ChannelsSchema = exports_external.object({
   telegram: TelegramChannelSchema,