@remnic/server 9.35.3 → 9.35.5

package/dist/index.d.ts

@@ -16,6 +16,37 @@ declare function envOverrides(): Partial<ServerConfig["server"]> & {
     remnic?: Record<string, unknown>;
 };
 
+interface StartupReadinessState {
+    ready: boolean;
+    warmupAttempts: number;
+    lastError?: string | null;
+    /** True when the gate opened before search warm-up completed (issue #2215). */
+    degraded?: boolean;
+}
+type StartupReadinessOutcome = "warmed" | "cancelled" | "overridden" | "search-disabled";
+declare function runStartupSearchWarmup(options: {
+    signal: AbortSignal;
+    isAvailable: () => boolean;
+    search: (onDegradation: (code: string) => void) => Promise<unknown>;
+}): Promise<void>;
+declare function completeStartupReadiness(options: {
+    deferredReady: Promise<void>;
+    warmup: (signal: AbortSignal) => Promise<unknown>;
+    prepareWarmup?: (signal: AbortSignal) => Promise<boolean>;
+    state: StartupReadinessState;
+    timeoutMs?: number;
+    retryIntervalMs?: number;
+    /** Failed attempts before the gate opens degraded; 0 disables (strict gate). */
+    degradedAfterAttempts?: number;
+    override?: boolean;
+    skipWarmup?: () => boolean;
+    openGate: () => void;
+    shutdownSignal?: AbortSignal;
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+    error?: (message: string) => void;
+}): Promise<StartupReadinessOutcome>;
+
 /**
  * @remnic/server
  *
@@ -46,6 +77,12 @@ interface ServerConfig {
         adminConsolePublicDir?: string;
         adminConsolePrefillToken?: boolean;
         readinessOverride?: boolean;
+        /**
+         * Failed search warm-up attempts before the init gate opens in degraded
+         * mode (issue #2215). 0 keeps the strict gate (health stays 503 until
+         * warm-up completes).
+         */
+        readinessDegradedAfterAttempts?: unknown;
         /** OAuth authorization-server facade for ChatGPT dev-mode apps (parsed by oauth.ts). */
         oauth?: unknown;
     };
@@ -62,6 +99,7 @@ interface ParsedServerConfig {
     adminConsolePublicDir?: string;
     adminConsolePrefillToken: boolean;
     readinessOverride: boolean;
+    readinessDegradedAfterAttempts: number;
 }
 declare function parseServerConfig(raw: Partial<ServerConfig["server"]>, options?: {
     portSource?: string;
@@ -69,32 +107,6 @@ declare function parseServerConfig(raw: Partial<ServerConfig["server"]>, options
 declare function loadConfigFile(configPath: string): ServerConfig;
 declare function mergeRemnicConfigForServer(fileRemnic: Record<string, unknown>, envRemnic: Record<string, unknown> | undefined): Record<string, unknown>;
 declare function createAdminControls(configPath: string, config: PluginConfig, serverConfig: ParsedServerConfig): RemnicAdminControls;
-interface StartupReadinessState {
-    ready: boolean;
-    warmupAttempts: number;
-    lastError?: string | null;
-}
-type StartupReadinessOutcome = "warmed" | "cancelled" | "overridden" | "search-disabled";
-declare function runStartupSearchWarmup(options: {
-    signal: AbortSignal;
-    isAvailable: () => boolean;
-    search: (onDegradation: (code: string) => void) => Promise<unknown>;
-}): Promise<void>;
-declare function completeStartupReadiness(options: {
-    deferredReady: Promise<void>;
-    warmup: (signal: AbortSignal) => Promise<unknown>;
-    prepareWarmup?: (signal: AbortSignal) => Promise<boolean>;
-    state: StartupReadinessState;
-    timeoutMs?: number;
-    retryIntervalMs?: number;
-    override?: boolean;
-    skipWarmup?: () => boolean;
-    openGate: () => void;
-    shutdownSignal?: AbortSignal;
-    warn?: (message: string) => void;
-    info?: (message: string) => void;
-    error?: (message: string) => void;
-}): Promise<StartupReadinessOutcome>;
 interface ServerResult {
     config: PluginConfig;
     service: EngramAccessService;

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import fs from "fs";
 import path from "path";
-import { parseConfig, isOpenaiApiKeyDisabled, resolveRemnicConfigRecord, Orchestrator, EngramAccessService, EngramAccessHttpServer, initLogger, log as log2, getAllValidTokens, getAllValidTokenEntriesCached, expandTildePath } from "@remnic/core";
+import { parseConfig, isOpenaiApiKeyDisabled, resolveRemnicConfigRecord, Orchestrator, EngramAccessService, EngramAccessHttpServer, initLogger, log as log3, getAllValidTokens, getAllValidTokenEntriesCached, expandTildePath } from "@remnic/core";
 import { probeBetterSqlite3Driver } from "@remnic/core/runtime/better-sqlite";
 
 // src/oauth.ts
@@ -696,6 +696,10 @@ function envOverrides() {
   const adminConsolePublicDir = readCompatEnv("REMNIC_ADMIN_CONSOLE_PUBLIC_DIR", "ENGRAM_ADMIN_CONSOLE_PUBLIC_DIR");
   const adminConsolePrefillToken = readCompatEnv("REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN", "ENGRAM_ADMIN_CONSOLE_PREFILL_TOKEN");
   const readinessOverride = process.env.REMNIC_READY_OVERRIDE;
+  const readinessDegradedAfterAttempts = readCompatEnv(
+    "REMNIC_READY_DEGRADED_AFTER_ATTEMPTS",
+    "ENGRAM_READY_DEGRADED_AFTER_ATTEMPTS"
+  );
   const writeRateLimitMaxRequests = readCompatEnv(
     "REMNIC_WRITE_RATE_LIMIT_MAX_REQUESTS",
     "ENGRAM_WRITE_RATE_LIMIT_MAX_REQUESTS"
@@ -711,6 +715,7 @@ function envOverrides() {
   if (adminConsolePublicDir) overrides.adminConsolePublicDir = adminConsolePublicDir;
   if (adminConsolePrefillToken) overrides.adminConsolePrefillToken = adminConsolePrefillToken;
   if (readinessOverride !== void 0) overrides.readinessOverride = readinessOverride;
+  if (readinessDegradedAfterAttempts !== void 0) overrides.readinessDegradedAfterAttempts = readinessDegradedAfterAttempts;
   if (writeRateLimitMaxRequests !== void 0) overrides.writeRateLimitMaxRequests = writeRateLimitMaxRequests;
   if (writeRateLimitWindowMs !== void 0) overrides.writeRateLimitWindowMs = writeRateLimitWindowMs;
   if (process.env.OPENAI_API_KEY) remnic.openaiApiKey = process.env.OPENAI_API_KEY;
@@ -719,6 +724,161 @@ function envOverrides() {
   return { ...overrides, ...Object.keys(remnic).length > 0 ? { remnic } : {} };
 }
 
+// src/startup-readiness.ts
+import { log as log2 } from "@remnic/core";
+function abortableDelay(ms, signal) {
+  if (signal.aborted) return Promise.resolve();
+  const { promise, resolve } = Promise.withResolvers();
+  const timer = setTimeout(resolve, ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    resolve();
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return promise.finally(() => signal.removeEventListener("abort", onAbort));
+}
+var STARTUP_WARMUP_TIMEOUT_MS = 2e4;
+var STARTUP_WARMUP_RETRY_INTERVAL_MS = 3e4;
+var STARTUP_DEGRADED_AFTER_ATTEMPTS = 3;
+var StartupWarmupDegradationError = class extends Error {
+  constructor(code) {
+    super(`startup search degraded: ${code}`);
+    this.name = "StartupWarmupDegradationError";
+  }
+};
+var StartupSyncPendingError = class extends Error {
+  constructor() {
+    super("startup search sync is not complete");
+    this.name = "StartupSyncPendingError";
+  }
+};
+async function runStartupSearchWarmup(options) {
+  let degradationCode;
+  await options.search((code) => {
+    degradationCode = code;
+  });
+  if (options.signal.aborted) return;
+  if (degradationCode) throw new StartupWarmupDegradationError(degradationCode);
+  if (!options.isAvailable()) {
+    throw new StartupWarmupDegradationError("backend_unavailable");
+  }
+}
+async function completeStartupReadiness(options) {
+  const timeoutMs = options.timeoutMs ?? STARTUP_WARMUP_TIMEOUT_MS;
+  const retryIntervalMs = options.retryIntervalMs ?? STARTUP_WARMUP_RETRY_INTERVAL_MS;
+  const degradedAfterAttempts = options.degradedAfterAttempts ?? STARTUP_DEGRADED_AFTER_ATTEMPTS;
+  const warn = options.warn ?? ((message) => log2.warn(message));
+  const info = options.info ?? ((message) => log2.info(message));
+  const error = options.error ?? ((message) => log2.error(message));
+  options.state.ready = false;
+  options.state.lastError = null;
+  options.state.degraded = false;
+  if (options.override) {
+    options.openGate();
+    options.state.ready = true;
+    error(
+      "CRITICAL: emergency readiness override enabled; exposing a cold search backend to traffic"
+    );
+    return "overridden";
+  }
+  if (options.skipWarmup?.()) {
+    options.openGate();
+    options.state.ready = true;
+    info("Standalone init gate opened without search warm-up (search intentionally disabled)");
+    return "search-disabled";
+  }
+  let removeDeferredShutdownListener = () => void 0;
+  const deferredShutdown = new Promise((resolve) => {
+    if (options.shutdownSignal?.aborted) {
+      resolve("shutdown");
+      return;
+    }
+    const onDeferredShutdown = () => resolve("shutdown");
+    options.shutdownSignal?.addEventListener("abort", onDeferredShutdown, { once: true });
+    removeDeferredShutdownListener = () => options.shutdownSignal?.removeEventListener("abort", onDeferredShutdown);
+  });
+  try {
+    const deferredOutcome = await Promise.race([
+      options.deferredReady.then(() => "ready"),
+      deferredShutdown
+    ]);
+    if (deferredOutcome === "shutdown") return "cancelled";
+  } catch (err) {
+    if (options.shutdownSignal?.aborted) return "cancelled";
+    options.state.lastError = err instanceof Error ? err.name : typeof err;
+    warn(`Standalone deferred initialization failed; warm-up retries will continue: ${err}`);
+  } finally {
+    removeDeferredShutdownListener();
+  }
+  if (options.shutdownSignal?.aborted) return "cancelled";
+  const lifecycleAbort = new AbortController();
+  const onShutdown = () => lifecycleAbort.abort(options.shutdownSignal?.reason);
+  options.shutdownSignal?.addEventListener("abort", onShutdown, { once: true });
+  try {
+    while (!lifecycleAbort.signal.aborted) {
+      if (options.skipWarmup?.()) {
+        options.state.degraded = false;
+        options.openGate();
+        options.state.ready = true;
+        info("Standalone init gate opened without search warm-up (search intentionally disabled)");
+        return "search-disabled";
+      }
+      options.state.warmupAttempts += 1;
+      const warmupAbort = new AbortController();
+      const onLifecycleAbort = () => warmupAbort.abort(lifecycleAbort.signal.reason);
+      lifecycleAbort.signal.addEventListener("abort", onLifecycleAbort, { once: true });
+      const timeout = Promise.withResolvers();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        warmupAbort.abort();
+        timeout.reject(new Error(`startup warm-up timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      timer.unref();
+      try {
+        const attempt = async () => {
+          if (options.prepareWarmup && !await options.prepareWarmup(warmupAbort.signal)) {
+            throw new StartupSyncPendingError();
+          }
+          return options.warmup(warmupAbort.signal);
+        };
+        await Promise.race([attempt(), timeout.promise]);
+        if (lifecycleAbort.signal.aborted) return "cancelled";
+        const recovered = options.state.degraded === true;
+        options.state.lastError = null;
+        options.state.degraded = false;
+        options.openGate();
+        options.state.ready = true;
+        info(
+          `Standalone init gate opened after search warm-up attempt ${options.state.warmupAttempts}${recovered ? " (recovered from degraded mode)" : ""}`
+        );
+        return "warmed";
+      } catch (err) {
+        if (lifecycleAbort.signal.aborted) return "cancelled";
+        options.state.lastError = timedOut ? "TimeoutError" : err instanceof Error ? err.name : typeof err;
+        warn(
+          timedOut ? `Standalone startup warm-up attempt ${options.state.warmupAttempts} timed out after ${timeoutMs}ms; retrying in ${retryIntervalMs}ms` : `Standalone startup warm-up attempt ${options.state.warmupAttempts} failed (${options.state.lastError}); retrying in ${retryIntervalMs}ms`
+        );
+        if (degradedAfterAttempts > 0 && !options.state.ready && options.state.warmupAttempts >= degradedAfterAttempts) {
+          options.state.degraded = true;
+          options.openGate();
+          options.state.ready = true;
+          warn(
+            `Standalone init gate opened in DEGRADED mode after ${options.state.warmupAttempts} failed search warm-up attempts (${options.state.lastError}); recall keeps serving via fallback retrieval and warm-up retries continue in the background`
+          );
+        }
+      } finally {
+        clearTimeout(timer);
+        lifecycleAbort.signal.removeEventListener("abort", onLifecycleAbort);
+      }
+      await abortableDelay(retryIntervalMs, lifecycleAbort.signal);
+    }
+    return "cancelled";
+  } finally {
+    options.shutdownSignal?.removeEventListener("abort", onShutdown);
+  }
+}
+
 // src/index.ts
 function parseServerPort(value, source) {
   const port = typeof value === "string" ? Number(value.trim()) : value;
@@ -760,6 +920,14 @@ function parseOptionalBoolean(value, source) {
   }
   throw new Error(`Invalid ${source}: expected a boolean`);
 }
+function parseOptionalNonNegativeInteger(value, source) {
+  if (value === void 0) return void 0;
+  const parsed = typeof value === "string" ? value.trim() === "" ? Number.NaN : Number(value.trim()) : value;
+  if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`Invalid ${source}: expected a non-negative integer`);
+  }
+  return parsed;
+}
 function parseServerConfig(raw, options) {
   return {
     host: parseOptionalNonEmptyString(raw.host, "server.host") ?? "127.0.0.1",
@@ -778,7 +946,11 @@ function parseServerConfig(raw, options) {
     adminConsoleEnabled: parseOptionalBoolean(raw.adminConsoleEnabled, "server.adminConsoleEnabled") ?? false,
     adminConsolePublicDir: parseOptionalString(raw.adminConsolePublicDir, "server.adminConsolePublicDir"),
     adminConsolePrefillToken: parseOptionalBoolean(raw.adminConsolePrefillToken, "server.adminConsolePrefillToken") ?? false,
-    readinessOverride: parseOptionalBoolean(raw.readinessOverride, "server.readinessOverride") ?? false
+    readinessOverride: parseOptionalBoolean(raw.readinessOverride, "server.readinessOverride") ?? false,
+    readinessDegradedAfterAttempts: parseOptionalNonNegativeInteger(
+      raw.readinessDegradedAfterAttempts,
+      "server.readinessDegradedAfterAttempts"
+    ) ?? STARTUP_DEGRADED_AFTER_ATTEMPTS
   };
 }
 function resolveUserPath(value) {
@@ -1229,154 +1401,16 @@ function createAdminControls(configPath, config, serverConfig) {
     }
   };
 }
-function abortableDelay(ms, signal) {
-  if (signal.aborted) return Promise.resolve();
-  const { promise, resolve } = Promise.withResolvers();
-  const timer = setTimeout(resolve, ms);
-  const onAbort = () => {
-    clearTimeout(timer);
-    resolve();
-  };
-  signal.addEventListener("abort", onAbort, { once: true });
-  return promise.finally(() => signal.removeEventListener("abort", onAbort));
-}
-var STARTUP_WARMUP_TIMEOUT_MS = 2e4;
-var STARTUP_WARMUP_RETRY_INTERVAL_MS = 3e4;
-var StartupWarmupDegradationError = class extends Error {
-  constructor(code) {
-    super(`startup search degraded: ${code}`);
-    this.name = "StartupWarmupDegradationError";
-  }
-};
-var StartupSyncPendingError = class extends Error {
-  constructor() {
-    super("startup search sync is not complete");
-    this.name = "StartupSyncPendingError";
-  }
-};
-async function runStartupSearchWarmup(options) {
-  let degradationCode;
-  await options.search((code) => {
-    degradationCode = code;
-  });
-  if (options.signal.aborted) return;
-  if (degradationCode) throw new StartupWarmupDegradationError(degradationCode);
-  if (!options.isAvailable()) {
-    throw new StartupWarmupDegradationError("backend_unavailable");
-  }
-}
-async function completeStartupReadiness(options) {
-  const timeoutMs = options.timeoutMs ?? STARTUP_WARMUP_TIMEOUT_MS;
-  const retryIntervalMs = options.retryIntervalMs ?? STARTUP_WARMUP_RETRY_INTERVAL_MS;
-  const warn = options.warn ?? ((message) => log2.warn(message));
-  const info = options.info ?? ((message) => log2.info(message));
-  const error = options.error ?? ((message) => log2.error(message));
-  options.state.ready = false;
-  options.state.lastError = null;
-  if (options.override) {
-    options.openGate();
-    options.state.ready = true;
-    error(
-      "CRITICAL: emergency readiness override enabled; exposing a cold search backend to traffic"
-    );
-    return "overridden";
-  }
-  if (options.skipWarmup?.()) {
-    options.openGate();
-    options.state.ready = true;
-    info("Standalone init gate opened without search warm-up (search intentionally disabled)");
-    return "search-disabled";
-  }
-  let removeDeferredShutdownListener = () => void 0;
-  const deferredShutdown = new Promise((resolve) => {
-    if (options.shutdownSignal?.aborted) {
-      resolve("shutdown");
-      return;
-    }
-    const onDeferredShutdown = () => resolve("shutdown");
-    options.shutdownSignal?.addEventListener("abort", onDeferredShutdown, { once: true });
-    removeDeferredShutdownListener = () => options.shutdownSignal?.removeEventListener("abort", onDeferredShutdown);
-  });
-  try {
-    const deferredOutcome = await Promise.race([
-      options.deferredReady.then(() => "ready"),
-      deferredShutdown
-    ]);
-    if (deferredOutcome === "shutdown") return "cancelled";
-  } catch (err) {
-    if (options.shutdownSignal?.aborted) return "cancelled";
-    options.state.lastError = err instanceof Error ? err.name : typeof err;
-    warn(`Standalone deferred initialization failed; warm-up retries will continue: ${err}`);
-  } finally {
-    removeDeferredShutdownListener();
-  }
-  if (options.shutdownSignal?.aborted) return "cancelled";
-  const lifecycleAbort = new AbortController();
-  const onShutdown = () => lifecycleAbort.abort(options.shutdownSignal?.reason);
-  options.shutdownSignal?.addEventListener("abort", onShutdown, { once: true });
-  try {
-    while (!lifecycleAbort.signal.aborted) {
-      if (options.skipWarmup?.()) {
-        options.openGate();
-        options.state.ready = true;
-        info("Standalone init gate opened without search warm-up (search intentionally disabled)");
-        return "search-disabled";
-      }
-      options.state.warmupAttempts += 1;
-      const warmupAbort = new AbortController();
-      const onLifecycleAbort = () => warmupAbort.abort(lifecycleAbort.signal.reason);
-      lifecycleAbort.signal.addEventListener("abort", onLifecycleAbort, { once: true });
-      const timeout = Promise.withResolvers();
-      let timedOut = false;
-      const timer = setTimeout(() => {
-        timedOut = true;
-        warmupAbort.abort();
-        timeout.reject(new Error(`startup warm-up timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
-      timer.unref();
-      try {
-        const attempt = async () => {
-          if (options.prepareWarmup && !await options.prepareWarmup(warmupAbort.signal)) {
-            throw new StartupSyncPendingError();
-          }
-          return options.warmup(warmupAbort.signal);
-        };
-        await Promise.race([attempt(), timeout.promise]);
-        if (lifecycleAbort.signal.aborted) return "cancelled";
-        options.state.lastError = null;
-        options.openGate();
-        options.state.ready = true;
-        info(
-          `Standalone init gate opened after search warm-up attempt ${options.state.warmupAttempts}`
-        );
-        return "warmed";
-      } catch (err) {
-        if (lifecycleAbort.signal.aborted) return "cancelled";
-        options.state.lastError = timedOut ? "TimeoutError" : err instanceof Error ? err.name : typeof err;
-        warn(
-          timedOut ? `Standalone startup warm-up attempt ${options.state.warmupAttempts} timed out after ${timeoutMs}ms; retrying in ${retryIntervalMs}ms` : `Standalone startup warm-up attempt ${options.state.warmupAttempts} failed (${options.state.lastError}); retrying in ${retryIntervalMs}ms`
-        );
-      } finally {
-        clearTimeout(timer);
-        lifecycleAbort.signal.removeEventListener("abort", onLifecycleAbort);
-      }
-      await abortableDelay(retryIntervalMs, lifecycleAbort.signal);
-    }
-    return "cancelled";
-  } finally {
-    options.shutdownSignal?.removeEventListener("abort", onShutdown);
-  }
-}
 async function cleanupFailedStartup(orchestrator, httpServer) {
   try {
     await httpServer.stop();
   } catch (err) {
-    log2.warn(`HTTP startup failure cleanup could not stop server: ${err}`);
+    log3.warn(`HTTP startup failure cleanup could not stop server: ${err}`);
   }
   try {
     await orchestrator.destroy();
   } catch (err) {
-    log2.warn(`HTTP startup failure cleanup could not destroy orchestrator: ${err}`);
+    log3.warn(`HTTP startup failure cleanup could not destroy orchestrator: ${err}`);
   }
 }
 async function startServer(options) {
@@ -1385,7 +1419,7 @@ async function startServer(options) {
   if (!driverProbe.ok) {
     const detailSuffix = driverProbe.detail ? ` (${driverProbe.detail})` : "";
     const abiSuffix = driverProbe.nativeBindingMismatch ? " \u2014 the binding was built for a different Node.js ABI; rebuild it (`node scripts/ensure-better-sqlite3.mjs` or `pnpm rebuild better-sqlite3`)" : "";
-    log2.error(
+    log3.error(
       `better-sqlite3 native driver failed to load under the running process${detailSuffix}${abiSuffix}. SQLite-backed features (memory projection) will fall back to slower full-corpus scans until fixed.`
     );
   }
@@ -1407,14 +1441,14 @@ async function startServer(options) {
   const parsedServerConfig = parseServerConfig(serverConfig, { portSource });
   const config = parseConfig(remnicConfig);
   initLogger(void 0, config.debug);
-  log2.debug(`debug logging enabled from config (${resolvedConfigPath.source})`);
+  log3.debug(`debug logging enabled from config (${resolvedConfigPath.source})`);
   const orchestrator = new Orchestrator(config);
   await orchestrator.initialize();
   const service = new EngramAccessService(orchestrator);
-  const readiness = { ready: false, warmupAttempts: 0, lastError: null };
+  const readiness = { ready: false, warmupAttempts: 0, lastError: null, degraded: false };
   const authToken = parsedServerConfig.authToken ?? readCompatEnv("REMNIC_AUTH_TOKEN", "ENGRAM_AUTH_TOKEN") ?? "";
   if (!authToken && getAllValidTokens().length === 0) {
-    log2.warn("No auth token set \u2014 server will reject all requests. Set REMNIC_AUTH_TOKEN, server.authToken in config, or generate tokens with 'remnic token generate'.");
+    log3.warn("No auth token set \u2014 server will reject all requests. Set REMNIC_AUTH_TOKEN, server.authToken in config, or generate tokens with 'remnic token generate'.");
   }
   const oauthConfig = applyOAuthEnvOverrides(serverConfig.oauth);
   const oauthRequestHandler = buildOAuthRequestHandler(oauthConfig);
@@ -1494,6 +1528,7 @@ async function startServer(options) {
     prepareWarmup: ensureStartupSync,
     state: readiness,
     override: parsedServerConfig.readinessOverride,
+    degradedAfterAttempts: parsedServerConfig.readinessDegradedAfterAttempts,
     skipWarmup: () => orchestrator.qmd.debugStatus() === "backend=noop",
     openGate: () => {
       readiness.ready = true;
@@ -1523,47 +1558,47 @@ async function startServer(options) {
   httpServer.stop = stop;
   orchestrator.deferredReady.then(() => {
     if (startupSyncAbort.signal.aborted) {
-      log2.debug("QMD startup-sync: cancelled before deferred init completed");
+      log3.debug("QMD startup-sync: cancelled before deferred init completed");
       return;
     }
     if (!config.qmdEnabled || orchestrator.qmd.debugStatus() === "backend=noop") {
-      log2.debug("QMD startup-sync: search disabled or noop backend, skipping retries");
+      log3.debug("QMD startup-sync: search disabled or noop backend, skipping retries");
       return;
     }
     const needsRetry = !orchestrator.qmd.isAvailable() || !orchestrator.deferredSyncSucceeded;
     if (!needsRetry) {
-      log2.debug("QMD startup-sync: deferred init completed successfully, no retries needed");
+      log3.debug("QMD startup-sync: deferred init completed successfully, no retries needed");
       return;
     }
     const RETRY_DELAYS_MS = [5e3, 15e3, 3e4, 6e4, 12e4];
     if (startupSyncAbort.signal.aborted) {
-      log2.debug("QMD startup-sync retry: cancelled before retry task started");
+      log3.debug("QMD startup-sync retry: cancelled before retry task started");
       return;
     }
     (async () => {
       for (const delay of RETRY_DELAYS_MS) {
         await abortableDelay(delay, startupSyncAbort.signal);
         if (startupSyncAbort.signal.aborted) {
-          log2.debug("QMD startup-sync retry: cancelled by shutdown");
+          log3.debug("QMD startup-sync retry: cancelled by shutdown");
           return;
         }
         const synced = await ensureStartupSync(startupSyncAbort.signal);
         if (!synced) {
           if (orchestrator.qmd.debugStatus() === "backend=noop") {
-            log2.debug("QMD startup-sync retry: search intentionally disabled; stopping retries");
+            log3.debug("QMD startup-sync retry: search intentionally disabled; stopping retries");
             return;
           }
-          log2.debug(`QMD startup-sync retry: not available yet (next retry in ${RETRY_DELAYS_MS[RETRY_DELAYS_MS.indexOf(delay) + 1] ?? "n/a"}ms)`);
+          log3.debug(`QMD startup-sync retry: not available yet (next retry in ${RETRY_DELAYS_MS[RETRY_DELAYS_MS.indexOf(delay) + 1] ?? "n/a"}ms)`);
           continue;
         }
         return;
       }
-      log2.warn("QMD startup-sync retry: exhausted all retries; search index may be stale");
+      log3.warn("QMD startup-sync retry: exhausted all retries; search index may be stale");
     })().catch((err) => {
-      log2.warn(`QMD startup-sync retry: unexpected error: ${err}`);
+      log3.warn(`QMD startup-sync retry: unexpected error: ${err}`);
     });
   }).catch((err) => {
-    log2.warn(`Deferred init error: ${err}`);
+    log3.warn(`Deferred init error: ${err}`);
   });
   return { config, service, httpServer, host, port, stop, cancelStartupSync: () => startupSyncAbort.abort(), abortDeferredInit: () => orchestrator.abortDeferredInit() };
 }