@schlessera/brain-ui-server 0.15.0 → 0.17.0

package/src/config/env.ts

@@ -15,19 +15,31 @@
 
 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;
 }
 
@@ -63,6 +75,44 @@ 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:
+      "Sustained inbound WebSocket frames per second per connection. 0 " +
+      "disables metering entirely.",
+    default: "20",
+    required: false,
+  },
+  {
+    name: "BRAIN_UI_WS_BURST",
+    description:
+      "Inbound WebSocket frames absorbable in one burst before the sustained " +
+      "rate applies. Opening the app legitimately fires several at once.",
+    default: "60",
+    required: false,
+  },
+  {
+    name: "BRAIN_UI_LOG_LEVEL",
+    description:
+      "Minimum severity the console log consumer emits: TRACE, DEBUG, INFO, " +
+      "WARN, ERROR or FATAL. Case-insensitive; an unrecognised value falls " +
+      "back to the default rather than silencing the server.",
+    default: "INFO",
+    required: false,
+  },
   {
     name: "SOURCE_COMMIT",
     description: "Git SHA reported by /api/status (baked at image build time).",
@@ -279,6 +329,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. */
@@ -305,6 +360,10 @@ export interface ServerConfig {
   sourceCommit: string;
   allowedOrigins: string[];
   maxConcurrentSessions: number;
+  /** Threshold for the console log consumer (BRAIN_UI_LOG_LEVEL). */
+  logLevel: Severity;
+  /** Inbound WebSocket frame metering, per connection. */
+  wsRate: { ratePerSecond: number; burst: number };
   auth: AuthConfig;
   webauthn: WebAuthnConfig;
   agent: AgentConfig;
@@ -322,8 +381,47 @@ function list(raw: string | undefined): string[] {
     .filter(Boolean);
 }
 
-function flag(raw: string | undefined): boolean {
-  return raw === "1";
+/**
+ * A log threshold, defaulting to INFO.
+ *
+ * An unrecognised value falls back rather than throwing: a typo in a log level
+ * must never be the reason a server refuses to boot, and silently emitting
+ * nothing would be worse than emitting too much.
+ */
+/** A non-negative number, falling back rather than throwing on nonsense. */
+function positiveNumber(raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  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 ?? "")
+    ? (upper as Severity)
+    : "INFO";
 }
 
 const AUTH_MODES: readonly AuthModeName[] = ["password", "tailscale", "proxy", "none"];
@@ -338,10 +436,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;
@@ -358,11 +453,11 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
       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",
@@ -370,16 +465,22 @@ 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,
       modelDiscovery,
       modelTtlMs: ttlHours * 60 * 60 * 1000,
     },
+    logLevel: parseSeverity(env.BRAIN_UI_LOG_LEVEL),
+    wsRate: {
+      ratePerSecond: positiveNumber(env.BRAIN_UI_WS_RATE, 20),
+      burst: positiveNumber(env.BRAIN_UI_WS_BURST, 60),
+    },
     voice: {
       provider: env.VOICE_PROVIDER?.trim().toLowerCase() || null,
       deepgramApiKey: env.DEEPGRAM_API_KEY || null,

package/src/cron/scheduler.ts

@@ -1,10 +1,12 @@
 import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
 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<{
@@ -22,11 +24,53 @@ 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;
+  /** Where run outcomes are reported; absent means silence. */
+  log?: Logger;
 }): CronScheduler {
-  const { db, brain } = deps;
+  const { db, brain, log } = deps;
 
   const jobs: CronJob[] = [
     {
@@ -46,25 +90,26 @@ 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);
-      console.log(`[cron] ${job.name} completed in ${durationMs}ms`);
+      record.finish();
+      log?.emit({
+        severityText: "INFO",
+        body: "job completed",
+        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);
-      console.error(`[cron] ${job.name} failed: ${message}`);
+      record.finish(message);
+      log?.emit({
+        severityText: "ERROR",
+        body: "job failed",
+        attributes: { job: job.name, error: message },
+      });
     }
   }
 

package/src/db/client.ts

@@ -2,6 +2,8 @@ import { Database } from "bun:sqlite";
 import { readdirSync, readFileSync } from "fs";
 import { join } from "path";
 
+import type { Logger } from "@opentelemetry/api-logs";
+
 /**
  * The UI's OWN SQLite database (sessions, passkeys, settings, cron runs) —
  * distinct from the brain database, which is opened read-only via
@@ -11,15 +13,24 @@ import { join } from "path";
  * it to every consumer, so two apps with different configuration can coexist
  * in one process and a test gets an isolated database by construction.
  */
-export function createUiDb(dbPath: string): Database {
+export interface CreateUiDbOptions {
+  /**
+   * Where migration progress is reported. Optional so a test can open a
+   * database without wiring observability; absent means silence, never
+   * console output.
+   */
+  log?: Logger;
+}
+
+export function createUiDb(dbPath: string, options: CreateUiDbOptions = {}): Database {
   const db = new Database(dbPath, { create: true });
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
-  runMigrations(db);
+  runMigrations(db, options.log);
   return db;
 }
 
-function runMigrations(database: Database) {
+function runMigrations(database: Database, log?: Logger) {
   // Ensure _migrations table exists
   database.exec(`
     CREATE TABLE IF NOT EXISTS _migrations (
@@ -39,7 +50,7 @@ function runMigrations(database: Database) {
       .filter((f) => f.endsWith(".sql"))
       .sort();
   } catch {
-    console.warn("[db] No migrations directory found, skipping migrations");
+    log?.emit({ severityText: "WARN", body: "no migrations directory; skipping migrations" });
     return;
   }
 
@@ -53,7 +64,7 @@ function runMigrations(database: Database) {
   for (const file of files) {
     if (applied.has(file)) continue;
 
-    console.log(`[db] Applying migration: ${file}`);
+    log?.emit({ severityText: "INFO", body: "applying migration", attributes: { file } });
     const sql = readFileSync(join(migrationsDir, file), "utf-8");
 
     database.transaction(() => {

package/src/db/settings.ts

@@ -6,11 +6,12 @@
 // corrupt row degrades to the caller's fallback rather than throwing, because
 // a bad preference must never take a route down.
 
+import type { Logger } from "@opentelemetry/api-logs";
 import type { Database } from "bun:sqlite";
 
 const HIDDEN_MODELS_KEY = "models.hidden";
 
-export function getSetting<T>(db: Database, key: string, fallback: T): T {
+export function getSetting<T>(db: Database, key: string, fallback: T, log?: Logger): T {
   const row = db
     .query("SELECT value FROM settings WHERE key = ?")
     .get(key) as { value: string } | null;
@@ -18,7 +19,11 @@ export function getSetting<T>(db: Database, key: string, fallback: T): T {
   try {
     return JSON.parse(row.value) as T;
   } catch {
-    console.warn(`[settings] Corrupt JSON for "${key}"; using fallback`);
+    log?.emit({
+      severityText: "WARN",
+      body: "corrupt JSON in settings; using fallback",
+      attributes: { key },
+    });
     return fallback;
   }
 }
@@ -31,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,
@@ -58,8 +59,12 @@ export {
 
 // WebSocket internals for embedders and tests.
 export { WsHost, type WsHostOptions } from "./ws/host.js";
-export { createWsUpgrade, websocket } from "./ws/connection.js";
-export { handleClientMessage } from "./ws/dispatch.js";
+export { createWsUpgrade, createWsHandlers, websocket } from "./ws/connection.js";
+export {
+  handleClientMessage,
+  turnIdMatches,
+  type ConnectionState,
+} from "./ws/dispatch.js";
 export { resolveTurnTarget } from "./ws/routing.js";
 export {
   createSessionCatalog,
@@ -70,10 +75,46 @@ 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";
 
+// Observability: the producing side is the OpenTelemetry API, the consuming
+// side is ours. Swap the consumer to change where a deployment reports; a test
+// swaps in the recording one and asserts on what the server actually said.
+export {
+  createObservability,
+  createRecordingObservability,
+  createSilentObservability,
+  createConsoleLoggerProvider,
+  createRecordingLoggerProvider,
+  createSilentLoggerProvider,
+  createInMemoryMeterProvider,
+  SEVERITIES,
+  severityRank,
+  seriesKey,
+} from "./observability/index.js";
+export type {
+  Observability,
+  ObservabilityOptions,
+  RecordingObservability,
+  RecordingLoggerProvider,
+  InMemoryMeterProvider,
+  LogReader,
+  LogWriter,
+  MetricsReader,
+  Severity,
+  CapturedLog,
+  LogQuery,
+  MetricPoint,
+  MetricSnapshot,
+} from "./observability/index.js";
+
 // Voice keyterm cache rebuild (used by deployments after `brain sync`).
 export {
   buildKeyterms,

package/src/middleware/auth.ts

@@ -1,3 +1,5 @@
+import type { Counter } from "@opentelemetry/api";
+import type { Logger } from "@opentelemetry/api-logs";
 import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
 import { getSignedCookie, setSignedCookie, deleteCookie } from "hono/cookie";
@@ -48,12 +50,14 @@ const LOGIN_RATE_WINDOW_MS = 60_000; // per minute
 // attacker could weaponize to deny the owner access.
 export const GLOBAL_LOGIN_RATE_LIMIT = 20; // attempts per window, all IPs combined
 
-export function resolveAuthMode(auth: AuthRuntime): AuthMode {
+export function resolveAuthMode(auth: AuthRuntime, log?: Logger): AuthMode {
   if (auth.mode) return auth.mode;
   if (auth.invalidMode) {
-    console.warn(
-      `[auth] Unknown AUTH_MODE="${auth.invalidMode}"; auto-detecting instead.`
-    );
+    log?.emit({
+      severityText: "WARN",
+      body: "unknown AUTH_MODE; auto-detecting instead",
+      attributes: { requested: auth.invalidMode },
+    });
   }
   if (auth.passwordHash) return "password";
   return "tailscale";
@@ -63,7 +67,7 @@ export function resolveAuthMode(auth: AuthRuntime): AuthMode {
  * Validate the auth configuration at startup. Throws (refusing to boot) on an
  * unsafe or unusable configuration.
  */
-export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
+export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime, log?: Logger): void {
   const host = auth.host;
   const loopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
 
@@ -87,11 +91,17 @@ export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
   // exposed to the network".
   if (mode === "none" && !loopback) {
     if (auth.dangerouslyDisableAuth) {
-      console.warn(
-        "[auth] AUTH_MODE=none on a non-loopback host, allowed by " +
+      // ERROR, not WARN: this is a safety that has been deliberately switched
+      // off, and the severity must survive any sane BRAIN_UI_LOG_LEVEL. A log
+      // threshold must never be the reason nobody saw this.
+      log?.emit({
+        severityText: "ERROR",
+        body:
+          "AUTH_MODE=none on a non-loopback host, allowed by " +
           "BRAIN_UI_DANGEROUSLY_DISABLE_AUTH=1 — every network peer has full " +
-          "agent access. Do not run this on anything but a trusted network."
-      );
+          "agent access. Do not run this on anything but a trusted network.",
+        attributes: { "auth.mode": "none", host },
+      });
     } else {
       throw new Error(
         "AUTH_MODE=none refuses to start unless HOST is loopback " +
@@ -112,13 +122,20 @@ export function assertAuthConfig(mode: AuthMode, auth: AuthRuntime): void {
           "any client-supplied copy. Set TRUST_PROXY=1 once that holds."
       );
     }
-    console.log(
-      `[auth] mode: proxy (trusting header "${auth.proxyAuthHeader}"; ensure your ` +
-        "upstream proxy sets it and strips any client-supplied copy)"
-    );
+    log?.emit({
+      severityText: "INFO",
+      body:
+        "auth mode resolved: proxy — ensure the upstream proxy sets this header " +
+        "and strips any client-supplied copy",
+      attributes: { "auth.mode": "proxy", header: auth.proxyAuthHeader },
+    });
     return;
   }
-  console.log(`[auth] mode: ${mode}`);
+  log?.emit({
+    severityText: "INFO",
+    body: "auth mode resolved",
+    attributes: { "auth.mode": mode },
+  });
 }
 
 /** Middleware guarding /api/* according to the resolved mode. */
@@ -273,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") {
@@ -286,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);
     }
 
@@ -306,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 });
   });