@schlessera/brain-ui-server 0.16.0 → 0.18.0

package/src/config/env.ts

@@ -16,20 +16,30 @@
 import { join } from "path";
 
 import { SEVERITIES, type Severity } from "../observability/types.js";
+import { envFlag } from "./env-core.js";
 
 // --- descriptor -------------------------------------------------------------
 
+/**
+ * The shared descriptor contract (sync-enforced copy in ./env-core.ts),
+ * under the name this package has always exported. This package's entries
+ * use the `string` arm of `required` for conditionally-required variables
+ * (e.g. "AUTH_MODE=password") and `null` for "no default".
+ */
+/**
+ * One environment variable the server reads.
+ *
+ * Deliberately LOCAL and narrower than env-core's EnvVarSpec: this is the
+ * package's published descriptor shape, and widening it to the shared
+ * union would be a breaking change for typed consumers of ENV_VARS.
+ */
 export interface EnvVarDescriptor {
-  /** The environment variable, exactly as read. */
+  /** Variable name as it appears in the environment. */
   name: string;
   /** What it controls. */
   description: string;
   /** Human-readable default applied when unset, or null when there is none. */
   default: string | null;
-  /**
-   * `false` when optional; otherwise a human-readable statement of the
-   * condition under which boot fails without it.
-   */
   required: false | string;
 }
 
@@ -65,6 +75,19 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "(empty)",
     required: false,
   },
+  {
+    name: "BRAIN_UI_CONFIRM_BASH",
+    description:
+      "JSON array of regex sources; a Bash command matching any of them raises " +
+      "a confirmation card before it runs. Unset uses the shipped defaults " +
+      "(brain archive, rm -r, git push --force, git reset --hard, git clean -f, " +
+      "git checkout -- ). An empty array [] disables the confirmation. Not a " +
+      "security boundary — an agent with Bash can reach the same effect another " +
+      "way; it stops a destructive command you did not intend, not one that is " +
+      "trying to get past you.",
+    default: "the shipped pattern set",
+    required: false,
+  },
   {
     name: "BRAIN_UI_WS_RATE",
     description:
@@ -109,6 +132,13 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "3",
     required: false,
   },
+  {
+    name: "BRAIN_UI_TURN_TIMEOUT_MS",
+    description:
+      "Hard per-turn timeout in ms; the host aborts a turn that runs past it. Raise for agent-heavy research work (e.g. 1800000 for 30 minutes).",
+    default: "600000 (10 minutes)",
+    required: false,
+  },
   // auth
   {
     name: "AUTH_MODE",
@@ -306,6 +336,11 @@ export interface WebAuthnConfig {
 export interface AgentConfig {
   /** Trimmed, lowercased AGENT_BACKEND; null when unset (defaults to claude). */
   backend: string | null;
+  /**
+   * Bash-confirmation regex sources; null means "use the backend's defaults".
+   * An empty array is a deliberate opt-out and is passed through as such.
+   */
+  confirmBashPatterns: string[] | null;
   claudeCodePath: string;
   defaultModel: string;
   /** Raw BRAIN_UI_CLAUDE_PROFILES JSON, parsed lazily by the registry. */
@@ -332,6 +367,11 @@ export interface ServerConfig {
   sourceCommit: string;
   allowedOrigins: string[];
   maxConcurrentSessions: number;
+  /**
+   * Per-turn timeout in ms (BRAIN_UI_TURN_TIMEOUT_MS), or null to use the
+   * WsHost default (10 minutes). An explicit createApp option still wins.
+   */
+  turnTimeoutMs: number | null;
   /** Threshold for the console log consumer (BRAIN_UI_LOG_LEVEL). */
   logLevel: Severity;
   /** Inbound WebSocket frame metering, per connection. */
@@ -353,10 +393,6 @@ function list(raw: string | undefined): string[] {
     .filter(Boolean);
 }
 
-function flag(raw: string | undefined): boolean {
-  return raw === "1";
-}
-
 /**
  * A log threshold, defaulting to INFO.
  *
@@ -371,6 +407,28 @@ function positiveNumber(raw: string | undefined, fallback: number): number {
   return Number.isFinite(n) && n >= 0 ? n : fallback;
 }
 
+/**
+ * Parse BRAIN_UI_CONFIRM_BASH into pattern sources.
+ *
+ * Unset or unparseable → null, meaning the backend's shipped defaults. An
+ * explicit `[]` is honoured as "no confirmation": disabling the seatbelt is a
+ * choice a deployment is allowed to make, and silently re-enabling it would be
+ * worse than obeying. Malformed JSON falls back to the defaults rather than
+ * throwing — a typo here must not stop the server booting, and the safe
+ * direction to fail is "more confirmation", not less.
+ */
+function parseConfirmBash(raw: string | undefined): string[] | null {
+  const text = raw?.trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed)) return null;
+    return parsed.filter((p): p is string => typeof p === "string");
+  } catch {
+    return null;
+  }
+}
+
 function parseSeverity(raw: string | undefined): Severity {
   const upper = raw?.trim().toUpperCase();
   return (SEVERITIES as readonly string[]).includes(upper ?? "")
@@ -390,10 +448,7 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
   const rawAuthMode = env.AUTH_MODE?.trim().toLowerCase() || null;
   const validMode = AUTH_MODES.find((mode) => mode === rawAuthMode) ?? null;
 
-  const rawDiscovery = env.BRAIN_UI_MODEL_DISCOVERY?.trim().toLowerCase();
-  const modelDiscovery = rawDiscovery
-    ? !(rawDiscovery === "0" || rawDiscovery === "off" || rawDiscovery === "false")
-    : env.NODE_ENV !== "test";
+  const modelDiscovery = envFlag(env.BRAIN_UI_MODEL_DISCOVERY, env.NODE_ENV !== "test");
 
   const rawTtl = Number(env.BRAIN_UI_MODEL_TTL_HOURS);
   const ttlHours = Number.isFinite(rawTtl) && rawTtl > 0 ? rawTtl : 24;
@@ -405,16 +460,23 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
     sourceCommit: env.SOURCE_COMMIT ?? "dev",
     allowedOrigins: list(env.ALLOWED_ORIGINS),
     maxConcurrentSessions: Math.max(1, Number(env.MAX_CONCURRENT_SESSIONS) || 3),
+    // Positive integer or null — 0, negatives, and garbage all mean "unset",
+    // so a typo degrades to the safe default instead of an instant timeout.
+    turnTimeoutMs:
+      Number.isFinite(Number(env.BRAIN_UI_TURN_TIMEOUT_MS)) &&
+      Number(env.BRAIN_UI_TURN_TIMEOUT_MS) > 0
+        ? Math.floor(Number(env.BRAIN_UI_TURN_TIMEOUT_MS))
+        : null,
     auth: {
       mode: validMode,
       invalidMode: validMode ? null : rawAuthMode,
       passwordHash: env.BRAIN_UI_PASSWORD_HASH || null,
       cookieSecret: env.COOKIE_SECRET || null,
-      trustProxy: flag(env.TRUST_PROXY),
+      trustProxy: envFlag(env.TRUST_PROXY, false),
       trustProxyHops: Math.max(1, Number(env.TRUST_PROXY_HOPS) || 1),
       proxyAuthHeader: (env.PROXY_AUTH_HEADER || "x-forwarded-user").toLowerCase(),
-      dangerouslyDisableAuth: flag(env.BRAIN_UI_DANGEROUSLY_DISABLE_AUTH),
-      allowPassword: flag(env.BRAIN_UI_ALLOW_PASSWORD),
+      dangerouslyDisableAuth: envFlag(env.BRAIN_UI_DANGEROUSLY_DISABLE_AUTH, false),
+      allowPassword: envFlag(env.BRAIN_UI_ALLOW_PASSWORD, false),
     },
     webauthn: {
       rpName: env.WEBAUTHN_RP_NAME || "Brain UI",
@@ -422,10 +484,11 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
       userId: env.WEBAUTHN_USER_ID || "brain-ui-owner",
       rpId: env.WEBAUTHN_RP_ID || null,
       origins: list(env.WEBAUTHN_ORIGINS),
-      allowLoopbackOrigin: flag(env.BRAIN_UI_ALLOW_LOOPBACK_ORIGIN),
+      allowLoopbackOrigin: envFlag(env.BRAIN_UI_ALLOW_LOOPBACK_ORIGIN, false),
     },
     agent: {
       backend: env.AGENT_BACKEND?.trim().toLowerCase() || null,
+      confirmBashPatterns: parseConfirmBash(env.BRAIN_UI_CONFIRM_BASH),
       claudeCodePath: env.CLAUDE_CODE_PATH || "/usr/local/bin/claude",
       defaultModel: env.BRAIN_UI_CLAUDE_DEFAULT_MODEL?.trim() || "claude-sonnet-4-6",
       profilesJson: env.BRAIN_UI_CLAUDE_PROFILES?.trim() || null,

package/src/cron/scheduler.ts

@@ -5,7 +5,8 @@ import type { BrainClient } from "../brain/client.js";
 // Scheduling is owned by the container crontab (config/crontab) — sync at
 // 02:00, validate at 03:00, job scrape at 04:00. This module only provides
 // manual triggers (triggerJob) and run history for the /api/status endpoint.
-// Runs started by the crontab do not appear here; they log to syslog.
+// Runs started by the crontab report themselves via recordCronRun below;
+// their stdout/stderr still goes to syslog.
 
 export interface CronScheduler {
   getCronStatus(): Array<{
@@ -23,6 +24,46 @@ interface CronJob {
   handler: () => Promise<void>;
 }
 
+/** One in-flight job run being recorded into `cron_runs`. */
+export interface CronRunRecord {
+  /** Mark the run finished: success without an argument, error with one. */
+  finish(error?: string): void;
+}
+
+/**
+ * Record a job run in the `cron_runs` history that `/api/status` serves
+ * (`cronJobs`, via {@link CronScheduler.getCronStatus}).
+ *
+ * The scheduler in this module only writes the table for its own manual
+ * triggers; in the shipped deployment the jobs are executed by the container
+ * crontab, whose runs were invisible to `/api/status`. An external scheduler's
+ * wrapper calls this before the job and `finish()` after, writing exactly the
+ * rows the in-process runner writes. A run whose process died before
+ * `finish()` stays in status "running" — itself a signal.
+ */
+export function recordCronRun(db: Database, jobName: string): CronRunRecord {
+  const startedAt = Date.now();
+  db.prepare(
+    "INSERT INTO cron_runs (job_name, started_at, status) VALUES (?, ?, 'running')"
+  ).run(jobName, startedAt);
+
+  return {
+    finish(error?: string) {
+      const finishedAt = Date.now();
+      const durationMs = finishedAt - startedAt;
+      if (error === undefined) {
+        db.prepare(
+          "UPDATE cron_runs SET status = 'success', finished_at = ?, duration_ms = ? WHERE job_name = ? AND started_at = ?"
+        ).run(finishedAt, durationMs, jobName, startedAt);
+      } else {
+        db.prepare(
+          "UPDATE cron_runs SET status = 'error', finished_at = ?, duration_ms = ?, error_message = ? WHERE job_name = ? AND started_at = ?"
+        ).run(finishedAt, durationMs, error, jobName, startedAt);
+      }
+    },
+  };
+}
+
 export function createCronScheduler(deps: {
   db: Database;
   brain: BrainClient;
@@ -49,28 +90,21 @@ export function createCronScheduler(deps: {
 
   async function runJob(job: CronJob) {
     const startedAt = Date.now();
-
-    db.prepare(
-      "INSERT INTO cron_runs (job_name, started_at, status) VALUES (?, ?, 'running')"
-    ).run(job.name, startedAt);
+    // Same recorder the external-scheduler path uses, so the two can never
+    // drift in what a cron_runs row looks like.
+    const record = recordCronRun(db, job.name);
 
     try {
       await job.handler();
-      const durationMs = Date.now() - startedAt;
-      db.prepare(
-        "UPDATE cron_runs SET status = 'success', finished_at = ?, duration_ms = ? WHERE job_name = ? AND started_at = ?"
-      ).run(Date.now(), durationMs, job.name, startedAt);
+      record.finish();
       log?.emit({
         severityText: "INFO",
         body: "job completed",
-        attributes: { job: job.name, "duration.ms": durationMs },
+        attributes: { job: job.name, "duration.ms": Date.now() - startedAt },
       });
     } catch (err) {
-      const durationMs = Date.now() - startedAt;
       const message = err instanceof Error ? err.message : String(err);
-      db.prepare(
-        "UPDATE cron_runs SET status = 'error', finished_at = ?, duration_ms = ?, error_message = ? WHERE job_name = ? AND started_at = ?"
-      ).run(Date.now(), durationMs, message, job.name, startedAt);
+      record.finish(message);
       log?.emit({
         severityText: "ERROR",
         body: "job failed",

package/src/db/settings.ts

@@ -36,8 +36,8 @@ export function setSetting(db: Database, key: string, value: unknown): void {
 }
 
 /** Profile ids the user keeps out of the model picker. */
-export function getHiddenModelIds(db: Database): string[] {
-  const value = getSetting<unknown>(db, HIDDEN_MODELS_KEY, []);
+export function getHiddenModelIds(db: Database, log?: Logger): string[] {
+  const value = getSetting<unknown>(db, HIDDEN_MODELS_KEY, [], log);
   if (!Array.isArray(value)) return [];
   return value.filter((id): id is string => typeof id === "string");
 }

package/src/index.ts

@@ -34,6 +34,7 @@ export {
   assertBackendResolvable,
   createBackendRegistry,
   createStaticBackendRegistry,
+  type BackendLogFn,
   type BackendRegistry,
   type ModelDiscoverySource,
   type ModelDiscoveryState,
@@ -74,6 +75,11 @@ export {
 // their own routes on top.
 export { createBrainClient, type BrainClient } from "./brain/client.js";
 
+// Cron run history. Scheduling belongs to the deployment (container crontab);
+// an external scheduler's wrapper records each run here so /api/status's
+// `cronJobs` reflects what actually ran.
+export { recordCronRun, type CronRunRecord } from "./cron/scheduler.js";
+
 // Share staging: a deployment can sweep expired staging dirs at boot; the
 // intake route also sweeps opportunistically on every share.
 export { pruneShareStaging, shareStagingRoot } from "./share/staging.js";

package/src/middleware/auth.ts

@@ -1,3 +1,4 @@
+import type { Counter } from "@opentelemetry/api";
 import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
@@ -289,9 +290,14 @@ export function authRoutes(
      * of WebAuthn concerns.
      */
     passwordDisabled?: (c: Context) => boolean;
+    /** Where login outcomes are reported; absent means silence. */
+    log?: Logger;
+    /** Failed-login counter — the same `auth.failures` instrument passkeys use. */
+    failures?: Counter;
   } = {}
 ): Hono {
   const app = new Hono();
+  const { log, failures } = deps;
 
   app.post("/auth/login", async (c) => {
     if (mode !== "password") {
@@ -302,6 +308,12 @@ export function authRoutes(
     const perIpOk = consumeLoginToken(`ip:${key}`, LOGIN_RATE_LIMIT);
     const globalOk = consumeLoginToken("global", GLOBAL_LOGIN_RATE_LIMIT);
     if (!perIpOk || !globalOk) {
+      failures?.add(1, { reason: "rate_limited", method: "password" });
+      log?.emit({
+        severityText: "WARN",
+        body: "login rate limited",
+        attributes: { ip: key, limit: perIpOk ? "global" : "ip" },
+      });
       return c.json({ error: "Too many attempts. Try again in a minute." }, 429);
     }
 
@@ -322,15 +334,52 @@ export function authRoutes(
     }
     const password = typeof body.password === "string" ? body.password : "";
     if (!password || !hash || !secret) {
+      failures?.add(1, { reason: "invalid_password", method: "password" });
+      log?.emit({
+        severityText: "WARN",
+        body: "login failed",
+        attributes: { ip: key },
+      });
       return c.json({ error: "Invalid credentials" }, 401);
     }
 
-    const ok = await Bun.password.verify(password, hash).catch(() => false);
+    // A verify that THROWS is not a wrong password — it is a hash Bun cannot
+    // parse (a corrupt BRAIN_UI_PASSWORD_HASH locks the owner out of every
+    // login), and collapsing it into "invalid credentials" hid exactly that.
+    let ok = false;
+    let verifyError: unknown = null;
+    try {
+      ok = await Bun.password.verify(password, hash);
+    } catch (err) {
+      verifyError = err;
+    }
+    if (verifyError) {
+      failures?.add(1, { reason: "verify_error", method: "password" });
+      log?.emit({
+        severityText: "ERROR",
+        body: "password verification errored — check BRAIN_UI_PASSWORD_HASH",
+        attributes: {
+          error: verifyError instanceof Error ? verifyError.message : String(verifyError),
+        },
+      });
+      return c.json({ error: "Invalid credentials" }, 401);
+    }
     if (!ok) {
+      failures?.add(1, { reason: "invalid_password", method: "password" });
+      log?.emit({
+        severityText: "WARN",
+        body: "login failed",
+        attributes: { ip: key },
+      });
       return c.json({ error: "Invalid credentials" }, 401);
     }
 
     await issueSessionCookie(c, auth);
+    log?.emit({
+      severityText: "INFO",
+      body: "login succeeded",
+      attributes: { ip: key },
+    });
     return c.json({ ok: true });
   });
 

package/src/routes/health.ts

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import type { Database } from "bun:sqlite";
 
 import type { MetricSnapshot } from "../observability/index.js";
 
@@ -7,13 +8,28 @@ const startTime = Date.now();
 // Public liveness probe. Deliberately minimal: no version/commit, no cron
 // detail, no session oracle — this route sits in front of the auth guard and
 // is reachable by anyone on the origin.
-export const healthRoutes = new Hono().get("/health", (c) => {
-  return c.json({
-    status: "healthy",
-    uptime: Date.now() - startTime,
-    timestamp: new Date().toISOString(),
+//
+// "Healthy" means the app's own SQLite handle answers a real read, not merely
+// that the process accepts connections: the Docker healthcheck gates on this
+// route, and a wedged database previously kept reporting healthy while every
+// stateful route failed. The probe reads sqlite_master rather than a bare
+// SELECT 1 — a constant expression touches no page of the database file, so it
+// cannot notice a locked or corrupted one. The unhealthy body carries no
+// detail — the route is public.
+export function createHealthRoutes(deps: { db: Database }): Hono {
+  return new Hono().get("/health", (c) => {
+    try {
+      deps.db.query("SELECT name FROM sqlite_master LIMIT 1").get();
+    } catch {
+      return c.json({ status: "unhealthy" }, 503);
+    }
+    return c.json({
+      status: "healthy",
+      uptime: Date.now() - startTime,
+      timestamp: new Date().toISOString(),
+    });
   });
-});
+}
 
 export interface StatusDeps {
   /** Git SHA baked at build time (SOURCE_COMMIT), "dev" when unset. */

package/src/routes/share.ts

@@ -118,7 +118,7 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
     lastPrune = now;
     // Deliberately not awaited: pruning is housekeeping, and the client is
     // waiting on the staging result, not on it.
-    void pruneShareStaging(brainRoot).catch((err) => {
+    void pruneShareStaging(brainRoot, Date.now(), log).catch((err) => {
       log?.emit({ severityText: "ERROR", body: "share staging prune failed", attributes: { error: err instanceof Error ? err.message : String(err) } });
     });
   }
@@ -167,12 +167,16 @@ export function createShareRoutes(deps: ShareRoutesDeps): Hono {
 
   inFlight += 1;
   try {
-    const result = await stageShare(brainRoot, {
-      title: firstString(form, "title"),
-      text: firstString(form, "text"),
-      url: firstString(form, "url"),
-      files,
-    });
+    const result = await stageShare(
+      brainRoot,
+      {
+        title: firstString(form, "title"),
+        text: firstString(form, "text"),
+        url: firstString(form, "url"),
+        files,
+      },
+      log
+    );
 
     maybePrune();
     return c.json(result, 201);

package/src/voice/keyterm-builder.ts

@@ -405,7 +405,7 @@ export function buildKeyterms(settings: KeytermSettings): KeytermsCache {
         keyterms,
         generatedAt: Date.now(),
         count: keyterms.length,
-        overrides: loadOverrides(brainPath),
+        overrides: loadOverrides(brainPath, log),
       };
     });
   } catch (err) {
@@ -429,7 +429,7 @@ export function buildKeyterms(settings: KeytermSettings): KeytermsCache {
         keyterms: [],
         generatedAt: Date.now(),
         count: 0,
-        overrides: loadOverrides(brainPath),
+        overrides: loadOverrides(brainPath, log),
         degraded: true,
       };
     }

package/src/ws/bridge.ts

@@ -38,10 +38,30 @@ export function makeBridge(
       }
       host.sendToClients(withTurnScope(msg, turn, turnId));
       if (msg.type === "result") {
+        // Only the live turn's own result may set its disposition — a late
+        // frame through a previous turn's bridge must not relabel this one.
+        if (turn.turnId === turnId) {
+          turn.lastResult =
+            msg.isError || msg.outcome === "error"
+              ? "error"
+              : msg.outcome === "cancelled"
+                ? "cancelled"
+                : "success";
+        }
         catalog.persistSession(msg, promptText, turn.providerId, backendId);
       }
     },
     requestPermission: (req) => {
+      if (!host.clients.hasClients()) {
+        // Not a failure — the card is parked and re-delivered on reconnect
+        // (see resendPendingInteractive) — but the wait was invisible before
+        // this line existed, and it is bounded only by the turn timeout.
+        host.log.emit({
+          severityText: "WARN",
+          body: "approval requested with no client connected; holding for reconnect",
+          attributes: { "tool.name": req.toolName, "toolUse.id": req.toolUseId },
+        });
+      }
       host.sendToClients(
         withTurnScope(
           {
@@ -67,7 +87,7 @@ export function makeBridge(
           resolve({ behavior: "deny", message: "Duplicate tool-approval id" });
           return;
         }
-        coordinator.pendingApprovals.set(req.toolUseId, { turn, turnId, resolve });
+        coordinator.pendingApprovals.set(req.toolUseId, { turn, turnId, request: req, resolve });
       });
     },
     askUser: (requestId, questions) => {
@@ -86,7 +106,14 @@ export function makeBridge(
           reject(new Error("Duplicate ask-user request id"));
           return;
         }
-        coordinator.pendingAskUser.set(requestId, { turn, turnId, resolve, reject });
+        coordinator.pendingAskUser.set(requestId, {
+          turn,
+          turnId,
+          requestId,
+          questions,
+          resolve,
+          reject,
+        });
       });
     },
     getLocation: (options) => {
@@ -144,8 +171,10 @@ export function makeBridge(
 
 export function emitTurnError(host: WsHost, turn: RunningTurn, err: unknown): void {
   // startTurn resolves for runtime failures (it emits its own error frame); it
-  // only rejects for caller errors.
+  // only rejects for caller errors. Each rejection is reported server-side
+  // too — the frame alone leaves no trace once the browser tab is gone.
   if (err instanceof BackendBusyError) {
+    host.reportTurnFailed("SESSION_BUSY", turn);
     host.sendToClients(
       withTurnScope(
         { type: "error", code: "SESSION_BUSY", message: "That session already has a running turn." },
@@ -153,15 +182,15 @@ export function emitTurnError(host: WsHost, turn: RunningTurn, err: unknown): vo
       )
     );
   } else if (err instanceof BackendRequestError) {
+    host.reportTurnFailed("BACKEND_REQUEST_ERROR", turn, err.message);
     host.sendToClients(
       withTurnScope({ type: "error", code: "BACKEND_REQUEST_ERROR", message: err.message }, turn)
     );
   } else {
+    const message = err instanceof Error ? err.message : String(err);
+    host.reportTurnFailed("BACKEND_ERROR", turn, message);
     host.sendToClients(
-      withTurnScope(
-        { type: "error", code: "BACKEND_ERROR", message: err instanceof Error ? err.message : String(err) },
-        turn
-      )
+      withTurnScope({ type: "error", code: "BACKEND_ERROR", message }, turn)
     );
   }
 }

package/src/ws/clients.ts

@@ -1,8 +1,15 @@
 import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
 import { shrinkForReplication } from "./shrink.js";
 
-/** Minimal structural view of a live socket — all we need to write to it. */
-export type WSContext = { send: (data: string) => void };
+/**
+ * Minimal structural view of a live socket — all we need to write to it.
+ * `raw` is the underlying Bun ServerWebSocket when hono's Bun adapter built
+ * the context; its `send` RETURNS a status instead of throwing.
+ */
+export type WSContext = {
+  send: (data: string) => void;
+  raw?: { send?: (data: string) => number } | undefined;
+};
 
 /** Serialize + size-bound a frame, then send it to one specific socket. */
 export function sendTo(ws: WSContext, msg: ServerMessage): void {
@@ -38,16 +45,27 @@ export class ClientSet {
   /**
    * Broadcast a frame to every attached client. Serializes once. A failing
    * socket is skipped (its `onClose` will prune it) so one dead peer can't
-   * block delivery to the others.
+   * block delivery to the others; `onSendError` lets the owner count the skip.
    */
-  broadcast(msg: ServerMessage): void {
+  broadcast(msg: ServerMessage, onSendError?: (err: unknown) => void): void {
     if (this.clients.size === 0) return;
     const payload = JSON.stringify(shrinkForReplication(msg));
     for (const ws of this.clients) {
       try {
-        ws.send(payload);
-      } catch {
+        // Bun's ServerWebSocket reports a dropped write by RETURNING 0 (closed
+        // connection) rather than throwing, and hono's WSContext.send discards
+        // that status — so write through the raw socket where one exists. -1
+        // is backpressure: the frame is queued, not lost.
+        if (typeof ws.raw?.send === "function") {
+          if (ws.raw.send(payload) === 0) {
+            onSendError?.(new Error("send dropped: connection closed"));
+          }
+        } else {
+          ws.send(payload);
+        }
+      } catch (err) {
         // Drop; the socket's onClose handler removes it from the set.
+        onSendError?.(err);
       }
     }
   }