fix: log friendly message when OpenCode server is offline

Author: grinev

src/session/cache-manager.ts

@@ -31,6 +31,12 @@ const SYNC_SAFETY_WINDOW_MS = 60_000;
 const SYNC_COOLDOWN_MS = 60_000;
 const STORAGE_FALLBACK_SCAN_LIMIT = 200;
 const SQLITE_FALLBACK_QUERY_LIMIT = 200;
+const SERVER_UNAVAILABLE_ERROR_MARKERS = [
+  "fetch failed",
+  "econnrefused",
+  "connection refused",
+  "connect refused",
+];
 
 const EMPTY_CACHE: SessionDirectoryCacheData = {
   version: CACHE_VERSION,
@@ -203,6 +209,69 @@ function createVirtualProjectId(worktree: string): string {
   return `dir_${hash}`;
 }
 
+function hasServerUnavailableMarker(value: string): boolean {
+  const lower = value.toLowerCase();
+  return SERVER_UNAVAILABLE_ERROR_MARKERS.some((marker) => lower.includes(marker));
+}
+
+function isServerUnavailableError(error: unknown): boolean {
+  const queue: unknown[] = [error];
+  const seen = new Set<unknown>();
+
+  while (queue.length > 0) {
+    const current = queue.pop();
+
+    if (!current || seen.has(current)) {
+      continue;
+    }
+
+    seen.add(current);
+
+    if (typeof current === "string") {
+      if (hasServerUnavailableMarker(current)) {
+        return true;
+      }
+
+      continue;
+    }
+
+    if (current instanceof Error) {
+      if (hasServerUnavailableMarker(`${current.name}: ${current.message}`)) {
+        return true;
+      }
+
+      const errorWithCause = current as Error & { cause?: unknown };
+      if (errorWithCause.cause) {
+        queue.push(errorWithCause.cause);
+      }
+
+      continue;
+    }
+
+    if (typeof current === "object") {
+      const value = current as {
+        code?: unknown;
+        message?: unknown;
+        cause?: unknown;
+      };
+
+      if (typeof value.code === "string" && hasServerUnavailableMarker(value.code)) {
+        return true;
+      }
+
+      if (typeof value.message === "string" && hasServerUnavailableMarker(value.message)) {
+        return true;
+      }
+
+      if (value.cause) {
+        queue.push(value.cause);
+      }
+    }
+  }
+
+  return false;
+}
+
 async function runSync(): Promise<void> {
   await ensureCacheLoaded();
 
@@ -494,7 +563,12 @@ export async function syncSessionDirectoryCache(options?: { force?: boolean }):
       lastSyncAttemptAt = Date.now();
     })
     .catch((error) => {
-      logger.warn("[SessionCache] Failed to sync sessions cache", error);
+      if (isServerUnavailableError(error)) {
+        logger.warn("[SessionCache] OpenCode server is not running. Start it with: opencode serve");
+      } else {
+        logger.warn("[SessionCache] Failed to sync sessions cache", error);
+      }
+
       lastSyncAttemptAt = 0;
     })
     .finally(() => {

tests/session/cache-manager.test.ts

@@ -12,9 +12,14 @@ import {
   warmupSessionDirectoryCache,
 } from "../../src/session/cache-manager.js";
 
-const { sessionListMock } = vi.hoisted(() => ({
-  sessionListMock: vi.fn(),
-}));
+const { sessionListMock, loggerWarnMock, loggerDebugMock, loggerInfoMock, loggerErrorMock } =
+  vi.hoisted(() => ({
+    sessionListMock: vi.fn(),
+    loggerWarnMock: vi.fn(),
+    loggerDebugMock: vi.fn(),
+    loggerInfoMock: vi.fn(),
+    loggerErrorMock: vi.fn(),
+  }));
 
 vi.mock("../../src/opencode/client.js", () => ({
   opencodeClient: {
@@ -24,6 +29,15 @@ vi.mock("../../src/opencode/client.js", () => ({
   },
 }));
 
+vi.mock("../../src/utils/logger.js", () => ({
+  logger: {
+    debug: loggerDebugMock,
+    info: loggerInfoMock,
+    warn: loggerWarnMock,
+    error: loggerErrorMock,
+  },
+}));
+
 function createSession(directory: string, updated: number) {
   return {
     id: `ses_${updated}`,
@@ -48,6 +62,7 @@ describe("session/cache-manager", () => {
     setRuntimeMode("installed");
     await loadSettings();
     sessionListMock.mockReset();
+    loggerWarnMock.mockReset();
     __resetSessionDirectoryCacheForTests();
   });
 
@@ -118,6 +133,20 @@ describe("session/cache-manager", () => {
     expect(directories.map((item) => item.worktree)).toEqual(["D:/repo-c", "D:/repo-a"]);
   });
 
+  it("logs friendly message when server is not running during warmup sync", async () => {
+    sessionListMock.mockResolvedValueOnce({
+      data: null,
+      error: new TypeError("fetch failed"),
+    });
+
+    await warmupSessionDirectoryCache();
+
+    expect(loggerWarnMock).toHaveBeenCalledTimes(1);
+    expect(loggerWarnMock).toHaveBeenCalledWith(
+      "[SessionCache] OpenCode server is not running. Start it with: opencode serve",
+    );
+  });
+
   it("updates existing directory with newer timestamp", async () => {
     await upsertSessionDirectory("D:/repo-a", 1_700_000_000_100);
     await upsertSessionDirectory("D:/repo-a", 1_700_000_000_900);