fix(dashboard): use lightweight ping endpoint for MaintenanceBanner (fixes #3040) (#3043)

Integrated into release/v3.8.8. Applied review fixes: moved the SELECT 1 into a pingDb() db helper (no raw SQL in route, Hard Rule #5) + the 503 catch no longer leaks err.message (Hard Rule #12). Thanks @herjarsa!

CHANGELOG.md

@@ -292,6 +292,14 @@
 
 - **mcp:** move `enforceScopes` guard before `MCP_TOOL_MAP` lookup, add inline `scopes` parameter to `withScopeEnforcement()`, and declare scopes on all 24 dynamic tool definitions (memory, skills, plugins, gamification, compression) to fix scope enforcement for dynamic MCP tool groups (#2958)
 
+### ✨ New Features
+
+- **notion:** add Notion as an MCP context source — 6 tools (`notion_search`, `notion_list_databases`, `notion_get_database`, `notion_query_database`, `notion_read`, `notion_append_blocks`) scoped under `read:notion` / `write:notion`, with dashboard "Context Sources" tab, settings API, and token persistence in `key_value` table (#2959)
+
+### 🔧 Bug Fixes
+
+- **mcp:** move `enforceScopes` guard before `MCP_TOOL_MAP` lookup, add inline `scopes` parameter to `withScopeEnforcement()`, and declare scopes on all 24 dynamic tool definitions (memory, skills, plugins, gamification, compression) to fix scope enforcement for dynamic MCP tool groups (#2958)
+
 ---
 
 ## [3.8.7] — 2026-05-29

src/app/api/health/ping/route.ts

@@ -0,0 +1,48 @@
+import { NextResponse } from "next/server";
+import { pingDb } from "@/lib/db/core";
+
+/**
+ * GET /api/health/ping — Lightweight liveness probe
+ *
+ * Delegates to `pingDb()` (Hard Rule #5: no raw SQL in routes) to confirm
+ * the server process is alive and the database is responsive. Intended
+ * for high-frequency polling (e.g. MaintenanceBanner) where the heavy
+ * `/api/monitoring/health` observability snapshot is too expensive.
+ *
+ * Returns `{ status: "ok", timestamp, latencyMs }` on success, or HTTP 503 on failure.
+ * No auth required — this is a public liveness signal.
+ */
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const startedAt = Date.now();
+  try {
+    const alive = pingDb();
+    if (!alive) {
+      return NextResponse.json(
+        { status: "error", error: "db_query_failed" },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      {
+        status: "ok",
+        timestamp: new Date().toISOString(),
+        latencyMs: Date.now() - startedAt,
+      },
+      {
+        status: 200,
+        headers: {
+          "Cache-Control": "no-store, no-cache, must-revalidate",
+        },
+      }
+    );
+  } catch (error) {
+    console.error("[ping] Unexpected error in GET /api/health/ping:", error);
+    return NextResponse.json(
+      { status: "error", error: "ping_failed" },
+      { status: 503 }
+    );
+  }
+}

src/lib/db/core.ts

@@ -1372,6 +1372,20 @@ export function getDbInstance(): SqliteDatabase {
   return db;
 }
 
+/**
+ * Lightweight liveness probe — runs `SELECT 1` against the singleton DB.
+ * Returns `true` if the database is reachable, `false` on any error.
+ * Intended for use by the `/api/health/ping` route (Hard Rule #5: no raw SQL in routes).
+ */
+export function pingDb(): boolean {
+  try {
+    const result = getDbInstance().prepare("SELECT 1 AS ok").get() as { ok: number } | undefined;
+    return result?.ok === 1;
+  } catch {
+    return false;
+  }
+}
+
 export function closeDbInstance(options?: { checkpointMode?: CheckpointMode | null }): boolean {
   clearDbHealthCheckScheduler();
   const db = getDb();

src/shared/components/MaintenanceBanner.tsx

@@ -24,7 +24,11 @@ export default function MaintenanceBanner() {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort("Health check timeout"), 8000);
       try {
-        const res = await fetch("/api/monitoring/health", {
+        // Use lightweight liveness probe (single SELECT 1) instead of the
+        // heavy /api/monitoring/health observability endpoint. The heavy
+        // endpoint can exceed the 8s client timeout under normal load
+        // (e.g. Logs page 3s polling), causing false-positive banners.
+        const res = await fetch("/api/health/ping", {
           signal: controller.signal,
           cache: "no-store",
         });

tests/unit/health-ping-route.test.ts

@@ -0,0 +1,51 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Isolated data dir so the test does not touch the user's real DB.
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-health-ping-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.API_KEY_SECRET = process.env.API_KEY_SECRET || "task-303-ping-secret";
+
+// Reset before importing so the singleton binds to the temp DATA_DIR.
+const core = await import("../../src/lib/db/core.ts");
+core.resetDbInstance();
+
+const routeModule = await import("../../src/app/api/health/ping/route.ts");
+
+test.after(() => {
+  core.resetDbInstance();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+});
+
+test("GET /api/health/ping returns 200 with status ok and ISO timestamp", async () => {
+  const res = await routeModule.GET();
+  assert.equal(res.status, 200, "expected HTTP 200");
+
+  const body = await res.json();
+  assert.equal(body.status, "ok");
+  assert.ok(typeof body.timestamp === "string", "timestamp must be a string");
+  assert.ok(!Number.isNaN(Date.parse(body.timestamp)), "timestamp must be ISO parseable");
+  assert.ok(typeof body.latencyMs === "number", "latencyMs must be a number");
+  assert.ok(body.latencyMs >= 0, "latencyMs must be non-negative");
+});
+
+test("GET /api/health/ping sets no-store cache headers", async () => {
+  const res = await routeModule.GET();
+  const cacheControl = res.headers.get("Cache-Control");
+  assert.ok(cacheControl, "Cache-Control header must be set");
+  assert.match(cacheControl, /no-store/i);
+});
+
+test("GET /api/health/ping is fast (under 500ms for trivial SELECT 1)", async () => {
+  // Warmup so the first-call cost (better-sqlite3 native binding init) is amortized.
+  await routeModule.GET();
+  const res = await routeModule.GET();
+  const body = await res.json();
+  assert.ok(
+    body.latencyMs < 500,
+    `expected latencyMs < 500, got ${body.latencyMs}ms — endpoint is no longer lightweight`
+  );
+});