fix(restart-sentinel): log DB errors instead of silently swallowing them

zenglingbiao · zenglingbiao · commit e088bb5c1638 · 2026-07-14T07:40:21.000+08:00
Replace empty catch blocks in clearRestartSentinel, readRestartSentinel,
and hasRestartSentinel with sentinelLog.warn(...) calls so SQLite errors
are visible in diagnostics while preserving best-effort fallback semantics.

Tests use deterministic fault injection via vi.mock on openclaw-state-db.js
with hoisted throw flags, replacing the previous non-deterministic state-dir
removal approach. Each error path asserts both the warning message and the
correct fallback return value.
diff --git a/src/infra/restart-sentinel.test.ts b/src/infra/restart-sentinel.test.ts
@@ -1,7 +1,35 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 // Covers restart sentinel persistence, summaries, and messages.
+
+const { mockWarn, mockThrowOpen, mockThrowWrite } = vi.hoisted(() => ({
+  mockWarn: vi.fn(),
+  mockThrowOpen: vi.fn(),
+  mockThrowWrite: vi.fn(),
+}));
+
+vi.mock("../logging/subsystem.js", () => ({
+  createSubsystemLogger: () => ({ warn: mockWarn }),
+}));
+
+vi.mock("../state/openclaw-state-db.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../state/openclaw-state-db.js")>();
+  return {
+    ...actual,
+    openOpenClawStateDatabase: (...args: Parameters<typeof actual.openOpenClawStateDatabase>) => {
+      mockThrowOpen();
+      return actual.openOpenClawStateDatabase(...args);
+    },
+    runOpenClawStateWriteTransaction: (
+      ...args: Parameters<typeof actual.runOpenClawStateWriteTransaction>
+    ) => {
+      mockThrowWrite();
+      return actual.runOpenClawStateWriteTransaction(...args);
+    },
+  };
+});
+
 import type { DB as OpenClawStateKyselyDatabase } from "../state/openclaw-state-db.generated.js";
 import {
   closeOpenClawStateDatabaseForTest,
@@ -34,6 +62,12 @@ import {
 } from "./update-control-plane-sentinel.js";
 import { buildUpdateRestartSentinelPayload } from "./update-restart-sentinel-payload.js";
 
+beforeEach(() => {
+  mockWarn.mockClear();
+  mockThrowOpen.mockReset();
+  mockThrowWrite.mockReset();
+});
+
 async function withRestartSentinelStateDir(run: () => Promise<void>): Promise<void> {
   await withTempDir({ prefix: "openclaw-sentinel-" }, async (tempDir) => {
     try {
@@ -462,6 +496,59 @@ describe("restart sentinel", () => {
   });
 });
 
+describe("restart sentinel error visibility", () => {
+  afterEach(() => {
+    mockWarn.mockClear();
+    mockThrowOpen.mockReset();
+    mockThrowWrite.mockReset();
+  });
+
+  it("logs a warning when clearRestartSentinel DB write fails", async () => {
+    mockThrowWrite.mockImplementationOnce(() => {
+      throw new Error("SQLITE_IOERR: disk I/O error");
+    });
+
+    await withRestartSentinelStateDir(async () => {
+      await expect(clearRestartSentinel()).resolves.toBeUndefined();
+
+      expect(mockWarn).toHaveBeenCalledTimes(1);
+      expect(mockWarn).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to clear restart sentinel"),
+      );
+    });
+  });
+
+  it("logs a warning and returns null when readRestartSentinel DB read fails", async () => {
+    mockThrowOpen.mockImplementationOnce(() => {
+      throw new Error("SQLITE_CORRUPT: database disk image is malformed");
+    });
+
+    await withRestartSentinelStateDir(async () => {
+      await expect(readRestartSentinel()).resolves.toBeNull();
+
+      expect(mockWarn).toHaveBeenCalledTimes(1);
+      expect(mockWarn).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to read restart sentinel"),
+      );
+    });
+  });
+
+  it("logs a warning and returns false when hasRestartSentinel DB read fails", async () => {
+    mockThrowOpen.mockImplementationOnce(() => {
+      throw new Error("SQLITE_BUSY: database is locked");
+    });
+
+    await withRestartSentinelStateDir(async () => {
+      await expect(hasRestartSentinel()).resolves.toBe(false);
+
+      expect(mockWarn).toHaveBeenCalledTimes(1);
+      expect(mockWarn).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to check restart sentinel"),
+      );
+    });
+  });
+});
+
 describe("restart success continuation", () => {
   it("does not infer an agent turn from session context alone", () => {
     expect(buildRestartSuccessContinuation({ sessionKey: "agent:main:main" })).toBeNull();
diff --git a/src/infra/restart-sentinel.ts b/src/infra/restart-sentinel.ts
@@ -5,33 +5,37 @@ import { isRecord as isPlainRecord } from "@openclaw/normalization-core/record-c
 import { sliceUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { formatCliCommand } from "../cli/command-format.js";
 import { resolveStateDir } from "../config/paths.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import type { DB as OpenClawStateKyselyDatabase } from "../state/openclaw-state-db.generated.js";
 import {
   openOpenClawStateDatabase,
   runOpenClawStateWriteTransaction,
 } from "../state/openclaw-state-db.js";
 import { resolveRuntimeServiceVersion } from "../version.js";
+import { formatErrorMessage } from "./errors.js";
 import {
   executeSqliteQuerySync,
   executeSqliteQueryTakeFirstSync,
   getNodeSqliteKysely,
 } from "./kysely-sync.js";
 
-type RestartSentinelLog = {
+const sentinelLog = createSubsystemLogger("restart-sentinel");
+
+export type RestartSentinelLog = {
   stdoutTail?: string | null;
   stderrTail?: string | null;
   exitCode?: number | null;
 };
 
-type RestartSentinelStep = {
+export type RestartSentinelStep = {
   name: string;
   command: string;
   cwd?: string | null;
   durationMs?: number | null;
   log?: RestartSentinelLog | null;
 };
 
-type RestartSentinelStats = {
+export type RestartSentinelStats = {
   mode?: string;
   root?: string;
   requiresRestart?: boolean;
@@ -72,7 +76,7 @@ export type RestartSentinelPayload = {
   stats?: RestartSentinelStats | null;
 };
 
-type RestartSentinel = {
+export type RestartSentinel = {
   version: 1;
   payload: RestartSentinelPayload;
 };
@@ -225,7 +229,11 @@ export async function clearRestartSentinel(env: NodeJS.ProcessEnv = process.env)
       },
       { env },
     );
-  } catch {}
+  } catch (err) {
+    // Clearing the sentinel is best-effort during shutdown/cleanup, but a
+    // failure here may leave the gateway believing a restart is still pending.
+    sentinelLog.warn(`Failed to clear restart sentinel: ${formatErrorMessage(err)}`);
+  }
   await removeLegacyRestartSentinel(env);
 }
 
@@ -298,7 +306,8 @@ export async function readRestartSentinel(
       return null;
     }
     return { version: 1, payload };
-  } catch {
+  } catch (err) {
+    sentinelLog.warn(`Failed to read restart sentinel: ${formatErrorMessage(err)}`);
     return null;
   }
 }
@@ -318,7 +327,8 @@ export async function hasRestartSentinel(env: NodeJS.ProcessEnv = process.env):
       return true;
     }
     return Boolean(await importLegacyRestartSentinel(env));
-  } catch {
+  } catch (err) {
+    sentinelLog.warn(`Failed to check restart sentinel: ${formatErrorMessage(err)}`);
     return false;
   }
 }
