@polderlabs/bizar-plugin 0.6.2 → 0.8.0

package/index.ts

@@ -98,6 +98,7 @@ import type { Plugin, Hooks, PluginInput, PluginOptions } from "@opencode-ai/plu
 import { createLogger, type Logger } from "./src/logger.js";
 import { decide, isLogOnlyWarn } from "./src/loop.js";
 import { fingerprint } from "./src/fingerprint.js";
+import { createDashboardPublisher, type DashboardPublisher } from "./src/dashboard-client.js";
 import { StateStore, type SessionState } from "./src/state.js";
 import { LogWriter } from "./src/report.js";
 import {
@@ -244,6 +245,10 @@ interface RuntimeContext {
   seenMessageIds: Map<string, Set<string>>;
   /** sessionID → pending system-transform message, set at warn/escalate. */
   pendingInjections: Map<string, string>;
+  /** v0.7.0-alpha.1 — Dashboard publisher (or null if disabled/not started).
+   *  Used by the `event` hook to forward opencode session lifecycle
+   *  events to the v2 dashboard via the @polderlabs/bizar-sdk. */
+  dashboardPublisher: DashboardPublisher | null;
 }
 
 /**
@@ -333,10 +338,11 @@ async function init(
 
   // --- Background agents (v0.4.2) -----------------------------------------
 
-  let instanceManager: InstanceManager | null = null;
-  let serve: ServeLifecycle | null = null;
-  let stream: EventStream | null = null;
-  let bgAvailable = false;
+let instanceManager: InstanceManager | null = null;
+let serve: ServeLifecycle | null = null;
+let stream: EventStream | null = null;
+let dashboardPublisher: DashboardPublisher | null = null;
+let bgAvailable = false;
 
   if (readServeDisabled()) {
     logger.info("bizar: background agents disabled via BIZAR_SERVE_DISABLE=1");
@@ -394,6 +400,44 @@ async function init(
       });
       streamHandle = stream;
 
+      // v0.7.0-alpha.1 — Wire dashboard publisher to the EventStream so
+      // every opencode SSE event is also published to the v2 dashboard.
+      // The publisher gracefully degrades if the dashboard is unreachable
+      // (queues, retries, warns; never throws into the plugin).
+      try {
+        const pub = createDashboardPublisher({
+          logger,
+        });
+        await pub.start();
+        dashboardPublisher = pub;
+        stream.onEvent((event) => {
+          // Translate opencode StreamEvent → DashboardEvent shape.
+          // The dashboard only cares about the wire-level (type, properties)
+          // so we forward { type, properties } directly. Cast through
+          // `unknown` because the opencode event shape doesn't exactly
+          // match the SDK's discriminated DashboardEvent — it's a
+          // forward-compatible passthrough.
+          const dashEvent = {
+            type: event.type,
+            properties: { ...event },
+          } as unknown as Parameters<DashboardPublisher["publish"]>[0];
+          void pub.publish(dashEvent);
+        });
+        // Stop the publisher when the stream is disposed.
+        const origDisconnect = stream.disconnect.bind(stream);
+        stream.disconnect = async () => {
+          await origDisconnect();
+          pub.stop();
+        };
+        logger.info("bizar: dashboard publisher wired to EventStream (v2 protocol)");
+      } catch (err) {
+        logger.warn(
+          `bizar: dashboard publisher failed to start: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+
       instanceManager = new InstanceManager({
         stateStore: bgStateStore,
         maxConcurrent,
@@ -469,6 +513,7 @@ async function init(
     directory: input.directory,
     seenMessageIds: new Map(),
     pendingInjections: new Map(),
+    dashboardPublisher,
   };
 
   return buildHooks(ctx, { instanceManager, bgAvailable });
@@ -772,9 +817,13 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
   const tools = bg.instanceManager
     ? {
         ...basePlanTools,
+        // v0.8.0 — bg-spawn no longer needs the HTTP client. It
+        // spawns an `opencode run` subprocess per agent (see
+        // src/opencode-runner.ts). The serve child is still
+        // available for the dashboard's v2 protocol and for any
+        // TUI/web client that wants to attach to it.
         bizar_spawn_background: createBgSpawnTool({
           instanceManager: bg.instanceManager,
-          http: (bg.instanceManager as unknown as { http: HttpClient }).http,
           worktree: ctx.worktree,
           logger: ctx.logger,
         }),
@@ -859,10 +908,37 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
     // `chat.message` seed, per spec §4.5.1).
     event: async ({ event }) => {
       try {
-        const ev = event as { type?: string; sessionID?: string };
+        // v0.7.0-alpha.1 — opencode's event object has { type: string,
+        // properties: { sessionID: string, ... } }. The legacy plugin
+        // assumed `event.sessionID` was top-level (which is wrong), so
+        // the hook returned early for every event. We extract from
+        // BOTH locations to be robust across opencode versions, and
+        // publish to the dashboard regardless.
+        const ev = event as {
+          type?: string;
+          sessionID?: string;
+          properties?: { sessionID?: string; [k: string]: unknown };
+        };
         const type = ev.type;
-        const sessionID = ev.sessionID;
-        if (!type || !sessionID) return;
+        const sessionID = ev.sessionID ?? ev.properties?.sessionID;
+        if (!type) return;
+
+        // v0.7.0-alpha.1 — Forward every opencode event to the dashboard.
+        // The plugin SDK does NOT translate opencode events to the SDK's
+        // discriminated DashboardEvent shape (it's a forward-compatible
+        // passthrough — the dashboard is happy with any {type, properties}
+        // event object). The publish is fire-and-forget; failures are
+        // logged and swallowed inside the publisher.
+        if (ctx.dashboardPublisher !== null) {
+          const dashEvent = {
+            type,
+            properties: { ...ev },
+          } as unknown as Parameters<DashboardPublisher["publish"]>[0];
+          void ctx.dashboardPublisher.publish(dashEvent);
+        }
+
+        // Legacy logic below: only runs when we have a sessionID.
+        if (!sessionID) return;
 
         if (type === "session.deleted") {
           await ctx.stateStore.withLock(sessionID, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar-plugin",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Bizar opencode plugin — loop detection, status reporting, handoff signal, background agents, and slash commands + visual plan flow for subagent activity",
   "type": "module",
   "main": "./index.ts",
@@ -26,6 +26,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@polderlabs/bizar-sdk": "*",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/background-state.ts

@@ -107,8 +107,32 @@ export type BackgroundStatus =
  *   - `restartCount` — number of times this instance has been
  *     auto-restarted (not including the original spawn). Default 0.
  *   - `maxRestarts` — cap; default 3.
- *   - `lastRestartAt` — epoch ms of the most recent auto-restart.
- */
+   * - `lastRestartAt` — epoch ms of the most recent auto-restart.
+   * - `processId` (v0.8.0) — PID of the opencode run subprocess. Set
+   *   by the opencode-runner after `Bun.spawn` returns. Optional
+   *   for backward compat.
+   * - `exitCode` (v0.8.0) — exit code of the opencode run
+   *   subprocess. Populated when the process exits.
+   * - `runnerState` (v0.8.0) — free-form status from the runner
+   *   ("starting" | "running" | "done" | "failed" | "killed").
+   *   Allows the dashboard to show runner-level state separately
+   *   from the higher-level `status`.
+   * - `runnerError` (v0.8.0) — opencode run subprocess error (e.g.
+   *   "opencode run exited with code 1").
+   * - `spawnMessage` (v0.8.0) — "you can continue" message returned
+   *   to the LLM by the spawn tool. Surfaces in the dashboard.
+   * - `spawnNextSteps` (v0.8.0) — list of next-step hints returned
+   *   to the LLM by the spawn tool.
+   * - `sessionIdAt` (v0.8.0) — when the opencode sessionId was
+   *   first observed in the subprocess stderr.
+   * - `runnerStartedAt` / `runnerEndedAt` — when the subprocess
+   *   started / ended (subset of `startedAt`/`completedAt`).
+   * - `spawnedAt` — when the bg-spawn tool recorded the instance.
+   *   Distinct from `startedAt` because the runner starts a
+   *   tick or two later.
+   * - `exitSignal` — exit signal name (e.g. "SIGTERM",
+   *   "SIGKILL") if the subprocess was killed.
+   */
 export interface BackgroundState {
   instanceId: string;
   sessionId: string;
@@ -153,6 +177,18 @@ export interface BackgroundState {
    * `{ ok: false }`. Cleared on a successful restart.
    */
   restartError?: string;
+  // v0.8.0 — process tracking (see opencode-runner.ts).
+  processId?: number;
+  exitCode?: number;
+  runnerState?: string;
+  runnerError?: string;
+  spawnMessage?: string;
+  spawnNextSteps?: string[];
+  sessionIdAt?: number;
+  runnerStartedAt?: number;
+  runnerEndedAt?: number;
+  spawnedAt?: number;
+  exitSignal?: string;
 }
 
 /**

package/src/background.ts

@@ -866,6 +866,19 @@ export class InstanceManager {
     }
   }
 
+  /**
+   * v0.8.0 — Public version of `_maybeAutoRestart`. The opencode-runner
+   * (see src/opencode-runner.ts) calls this from its onExit callback
+   * when a `bizar_spawn_background` subprocess exits. Without this,
+   * persistent instances would never auto-restart under the new
+   * subprocess-based path (the SSE event handler that previously
+   * triggered auto-restart is no longer wired up because we don't
+   * subscribe to per-session events anymore).
+   */
+  async maybeAutoRestart(instanceId: string): Promise<void> {
+    await this._maybeAutoRestart(instanceId);
+  }
+
   /** v0.5.5 — Attempt an auto-restart for a persistent failed instance. */
   private async _maybeAutoRestart(instanceId: string): Promise<void> {
     const inst = this.instances.get(instanceId);

package/src/commands.ts

@@ -314,7 +314,7 @@ function handleVisualPlan(arg: string, ctx: ParseContext): SlashCommandResult {
     // No argument — return current state as a dialog
     return {
       handled: true,
-      response: "",
+      response: `Visual plan mode is currently ${currentEnabled ? "on" : "off"}.`,
       dialog: {
         id: generateId(),
         title: "Visual Plan",
@@ -334,7 +334,7 @@ function handleVisualPlan(arg: string, ctx: ParseContext): SlashCommandResult {
   if (lc === "on" || lc === "true" || lc === "1" || lc === "enable") {
     return {
       handled: true,
-      response: "",
+      response: `Visual plan mode is now on.`,
       settingsPatch: { visualPlanEnabled: true },
       dialog: {
         id: generateId(),
@@ -353,7 +353,7 @@ function handleVisualPlan(arg: string, ctx: ParseContext): SlashCommandResult {
   if (lc === "off" || lc === "false" || lc === "0" || lc === "disable") {
     return {
       handled: true,
-      response: "",
+      response: `Visual plan mode is now off.`,
       settingsPatch: { visualPlanEnabled: false },
       dialog: {
         id: generateId(),
@@ -372,7 +372,7 @@ function handleVisualPlan(arg: string, ctx: ParseContext): SlashCommandResult {
   if (lc === "status" || lc === "state" || lc === "?") {
     return {
       handled: true,
-      response: "",
+      response: `Visual plan mode is currently ${currentEnabled ? "on" : "off"}.`,
       dialog: {
         id: generateId(),
         title: "Visual Plan",
@@ -444,7 +444,7 @@ function handlePlan(arg: string, ctx: ParseContext): SlashCommandResult {
 function helpPlan(): SlashCommandResult {
   return {
     handled: true,
-    response: "",
+    response: "Plan commands: /plan new <slug> [template] | /plan list | /plan open <slug> | /plan get <slug> | /plan add <slug> | /plan update <slug> <id> | /plan delete <slug> <id> | /plan comment <slug> [id] \"text\" | /plan comments <slug> [id] | /plan status <slug> <status> | /plan wait <slug> [--timeout N]. Run /plan <subcommand> for details.",
     dialog: {
       id: generateId(),
       title: "Plan Commands",
@@ -477,7 +477,7 @@ function handlePlanNew(args: string[], ctx: ParseContext): SlashCommandResult {
   if (args.length === 0 || args[0] === "") {
     return {
       handled: true,
-      response: "",
+      response: "Usage: /plan new <slug> [template]. Available templates: " + KNOWN_TEMPLATES.join(", ") + ".",
       dialog: {
         id: generateId(),
         title: "Create New Plan",
@@ -520,7 +520,7 @@ function handlePlanNew(args: string[], ctx: ParseContext): SlashCommandResult {
 
   return {
     handled: true,
-    response: "",
+    response: `Created plan "${titleCase(slug)}" with the "${resolvedTemplate}" template. Use /plan open ${slug} to open it.`,
     sideEffect: {
       kind: "create_plan",
       slug,
@@ -544,9 +544,26 @@ function handlePlanNew(args: string[], ctx: ParseContext): SlashCommandResult {
 
 function handlePlanList(ctx: ParseContext): SlashCommandResult {
   const slugs = ctx.availablePlanSlugs ?? [];
+  if (slugs.length === 0) {
+    return {
+      handled: true,
+      response: "No plans found in the current worktree. Use /plan new <slug> to create one.",
+      sideEffect: { kind: "list_plans" },
+      dialog: {
+        id: generateId(),
+        title: "Plans",
+        command: "/plan list",
+        component: "plan-list",
+        data: {
+          plans: slugs,
+          count: slugs.length,
+        },
+      },
+    };
+  }
   return {
     handled: true,
-    response: "",
+    response: `Found ${slugs.length} plan(s) (${slugs.length}): ${slugs.join(", ")}.`,
     sideEffect: { kind: "list_plans" },
     dialog: {
       id: generateId(),
@@ -584,7 +601,7 @@ function handlePlanOpen(args: string[], ctx: ParseContext): SlashCommandResult {
 
   return {
     handled: true,
-    response: "",
+    response: `Opening plan "${slug}" at ${url}.`,
     settingsPatch: { lastUsedSlug: slug },
     sideEffect: {
       kind: "open_plan_url",
@@ -618,7 +635,7 @@ function handlePlanGet(args: string[]): SlashCommandResult {
   }
   return {
     handled: true,
-    response: "",
+    response: `Fetching canvas for plan "${slug}"…`,
     sideEffect: {
       kind: "tool_invocation",
       toolName: "bizar_plan_action",
@@ -1078,7 +1095,7 @@ function handleBizar(arg: string, ctx: ParseContext): SlashCommandResult {
 function helpResult(): SlashCommandResult {
   return {
     handled: true,
-    response: "",
+    response: "Available commands: /visual-plan [on|off|status], /plan new <slug> [template], /plan list, /plan open <slug>, /plan get <slug>, /plan add <slug>, /plan update <slug> <id>, /plan delete <slug> <id>, /plan comment <slug> [id] \"text\", /plan comments <slug> [id], /plan status <slug> <status>, /plan wait <slug> [--timeout N], /bizar, /bizar <args>, /help. See the dialog for full descriptions.",
     dialog: {
       id: generateId(),
       title: "Bizar Commands",

package/src/dashboard-client.ts

@@ -0,0 +1,235 @@
+/**
+ * dashboard-client.ts
+ *
+ * v0.7.0-alpha.1 — Plugin-side bridge to the Bizar dashboard via the
+ * @polderlabs/bizar-sdk. Replaces (does not remove) the file-based
+ * `serve-info.ts` bridge.
+ *
+ * Usage:
+ *   import { createDashboardPublisher } from "./dashboard-client.js";
+ *
+ *   const publisher = createDashboardPublisher({
+ *     logger: myLogger,
+ *   });
+ *   await publisher.start();
+ *   publisher.publish({
+ *     type: "session.created",
+ *     properties: { sessionId: "ses_1", agent: "mimir" },
+ *   });
+ *
+ * Behavior:
+ *   - Reads `BIZAR_DASHBOARD_URL` (default http://127.0.0.1:4098).
+ *   - Reads `BIZAR_DASHBOARD_PASSWORD` first, then falls back to
+ *     `~/.cache/bizarharness/dash-auth.json` (the file written by the
+ *     dashboard on first start).
+ *   - `publish()` is fire-and-forget: returns a Promise that resolves
+ *     after one HTTP round-trip or rejects on failure. NEVER throws
+ *     into the caller — failures are logged and swallowed (the plugin
+ *     must keep running even when the dashboard is down).
+ *   - `publish()` queues events if the dashboard is unreachable and
+ *     drains the queue on reconnect (best-effort).
+ */
+
+import {
+  createBizarClient,
+  isBizarError,
+  type BizarClient,
+  type DashboardEvent,
+} from "@polderlabs/bizar-sdk";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const DEFAULT_DASHBOARD_URL = "http://127.0.0.1:4098";
+const DEFAULT_AUTH_FILE_PATHS = [
+  join(homedir(), ".cache", "bizarharness", "dash-auth.json"),
+  join(homedir(), ".cache", "bizar", "dash-auth.json"),
+];
+/**
+ * The auth file paths to search. Override at test-time via
+ * `process.env.BIZAR_DASHBOARD_AUTH_FILE` (single file) or
+ * `process.env.BIZAR_DASHBOARD_AUTH_FILES` (colon-separated list).
+ */
+function getAuthFilePaths(): string[] {
+  const single = process.env.BIZAR_DASHBOARD_AUTH_FILE;
+  if (single) return [single];
+  const multi = process.env.BIZAR_DASHBOARD_AUTH_FILES;
+  if (multi) return multi.split(":").filter(Boolean);
+  return DEFAULT_AUTH_FILE_PATHS;
+}
+
+export interface Logger {
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+export interface DashboardPublisherOptions {
+  logger: Logger;
+  baseUrl?: string;
+  password?: string;
+  /** Disable the publisher entirely (e.g. BIZAR_DASHBOARD_DISABLE=1). */
+  disabled?: boolean;
+  /** Max queued events while the dashboard is unreachable. */
+  queueLimit?: number;
+}
+
+/**
+ * Read the dashboard auth record from one of the candidate paths.
+ * Returns null if no usable file exists. Never throws.
+ */
+function readDashboardAuth(): { password: string; baseUrl?: string; port?: number } | null {
+  for (const candidate of getAuthFilePaths()) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const raw = readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw) as {
+        password?: unknown;
+        baseUrl?: unknown;
+        port?: unknown;
+      };
+      if (typeof parsed.password !== "string" || parsed.password.length < 16) continue;
+      return {
+        password: parsed.password,
+        baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : undefined,
+        port: typeof parsed.port === "number" ? parsed.port : undefined,
+      };
+    } catch {
+      // ignore malformed file
+    }
+  }
+  return null;
+}
+
+export interface DashboardPublisher {
+  start(): Promise<void>;
+  publish(event: DashboardEvent): Promise<void>;
+  stop(): void;
+  /** Whether the publisher is currently configured and ready. */
+  isReady(): boolean;
+}
+
+export function createDashboardPublisher(
+  options: DashboardPublisherOptions,
+): DashboardPublisher {
+  const { logger, disabled = false, queueLimit = 100 } = options;
+
+  let client: BizarClient | null = null;
+  const queue: DashboardEvent[] = [];
+  let flushing = false;
+
+  function resolveConfig(): { baseUrl: string; password: string } | null {
+    let baseUrl = options.baseUrl ?? process.env.BIZAR_DASHBOARD_URL;
+    if (!baseUrl) {
+      const port = process.env.BIZAR_DASHBOARD_PORT;
+      baseUrl = port ? `http://127.0.0.1:${port}` : DEFAULT_DASHBOARD_URL;
+    }
+    const password =
+      options.password ??
+      process.env.BIZAR_DASHBOARD_PASSWORD ??
+      readDashboardAuth()?.password;
+
+    if (!password) {
+      return null;
+    }
+    return { baseUrl, password };
+  }
+
+  function isReady(): boolean {
+    return client !== null;
+  }
+
+  async function start(): Promise<void> {
+    if (disabled) {
+      logger.debug("bizar: dashboard publisher disabled by config");
+      return;
+    }
+    const cfg = resolveConfig();
+    if (!cfg) {
+      logger.debug(
+        "bizar: dashboard publisher not started (no password in env or auth file)",
+      );
+      return;
+    }
+    client = createBizarClient({
+      baseUrl: cfg.baseUrl,
+      password: cfg.password,
+    });
+    logger.info(
+      `bizar: dashboard publisher started (url=${cfg.baseUrl}, password len=${cfg.password.length})`,
+    );
+
+    // Verify the dashboard is reachable. Non-fatal — publish() will retry
+    // and surface connection errors as warnings.
+    try {
+      const health = await client.health.check();
+      if (isBizarError(health)) {
+        logger.warn(
+          `bizar: dashboard unreachable at ${cfg.baseUrl} (${health.name}); publish events will be queued`,
+        );
+      }
+    } catch (err) {
+      logger.warn(
+        `bizar: dashboard health check failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    void flushQueue();
+  }
+
+  async function publish(event: DashboardEvent): Promise<void> {
+    if (!client) {
+      logger.debug(
+        `bizar: dashboard publisher not ready — dropping event ${event.type}`,
+      );
+      return;
+    }
+    if (queue.length >= queueLimit) {
+      queue.shift();
+      logger.warn(
+        `bizar: dashboard publisher queue full (${queueLimit}); dropping oldest event`,
+      );
+    }
+    queue.push(event);
+    if (!flushing) {
+      void flushQueue();
+    }
+  }
+
+  async function flushQueue(): Promise<void> {
+    if (flushing || !client) return;
+    flushing = true;
+    try {
+      while (queue.length > 0 && client) {
+        const next = queue.shift()!;
+        try {
+          const result = await client.events.publish(next);
+          if (isBizarError(result)) {
+            logger.warn(
+              `bizar: dashboard publish failed (${result.name}); requeueing ${next.type}`,
+            );
+            queue.unshift(next);
+            break;
+          }
+        } catch (err) {
+          logger.warn(
+            `bizar: dashboard publish threw: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          queue.unshift(next);
+          break;
+        }
+      }
+    } finally {
+      flushing = false;
+    }
+  }
+
+  function stop(): void {
+    client = null;
+    queue.length = 0;
+    logger.debug("bizar: dashboard publisher stopped");
+  }
+
+  return { start, publish, stop, isReady };
+}

package/src/event-stream.ts

@@ -120,6 +120,8 @@ export class EventStream {
   private _logger: Logger;
   private _http: HttpClient;
   private _handlers = new Map<string, Set<SessionEventHandler>>();
+  /** Global handler invoked for every event regardless of session (v0.7.0). */
+  private _globalHandler: SessionEventHandler | null = null;
   private _connected = false;
   private _aborted = false;
   private _abortController: AbortController | null = null;
@@ -128,6 +130,21 @@ export class EventStream {
   private _reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private _connectPromise: Promise<void> | null = null;
 
+  /**
+   * Register a global handler invoked for every event (regardless of
+   * session). Used to forward events to the dashboard publisher. Returns
+   * an unsubscribe function. (v0.7.0-alpha.1 — wired into the v2
+   * SDK dashboard-client.ts bridge.)
+   */
+  onEvent(handler: SessionEventHandler): () => void {
+    this._globalHandler = handler;
+    return () => {
+      if (this._globalHandler === handler) {
+        this._globalHandler = null;
+      }
+    };
+  }
+
   constructor(opts: {
     baseUrl: string;
     directory: string;
@@ -439,6 +456,21 @@ export class EventStream {
   }
 
   private dispatchToHandlers(sessionID: string, event: StreamEvent): void {
+    // v0.7.0-alpha.1 — Forward every event to the global handler
+    // (typically the dashboard publisher) BEFORE the per-session dispatch.
+    // Failures here are isolated so one bad handler doesn't break the
+    // dispatch chain for other subscribers.
+    if (this._globalHandler) {
+      try {
+        this._globalHandler(event);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this._logger.warn(
+          `bizar: SSE global handler threw for session ${sessionID} (type=${event.type}): ${msg}`,
+        );
+      }
+    }
+
     const set = this._handlers.get(sessionID);
     if (!set || set.size === 0) {
       this._logger.debug(