@sfmc-bds/cli 0.2.0-beta.8 → 0.2.0

package/dist/services.d.ts

@@ -1,3 +1,19 @@
+/**
+ * services.ts — CLI 进程编排与服务生命周期管理
+ *
+ * 核心管理对象（ServiceName）：
+ * - `bds`：Minecraft 基岩版服务端（支持 stdin 管道指令交互与优雅停服）
+ * - `db`：db-server SQLite HTTP 服务（端口健康检查与 loopback 探活）
+ * - `tunnel`：云端 QQ Webhook 到本机 db-server 的 SSH 反向隧道
+ * - `qq`：qq-bridge 消息网桥服务（支持官方 Bot 与 LLBot 双后端）
+ * - `llbot`：LLBot 独立机器人进程（条件启动）
+ *
+ * 核心能力：
+ * - 进程生命周期：按依赖次序编排服务启动（db → qq → bds）、优雅停止与异常自动拉起
+ * - 多源探活感知：自动探测托管进程与外部独立进程状态
+ * - 日志流统一聚合：捕获并归一化各服务的 stdout / stderr 数据流
+ */
+import type { QQBackend } from "@sfmc-bds/sdk/node/config";
 import { type ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { type ServiceId } from "./runtime.js";
@@ -7,8 +23,31 @@ export interface LogLine {
     text: string;
     stream: "stdout" | "stderr";
 }
-export type ServiceName = "bds" | "db" | "qq" | "llbot";
+/** 子进程输出分行：过滤空串以及 Windows CRLF 拆分后残留的纯空白行。 */
+export declare function nonBlankOutputLines(text: string): string[];
+export type ServiceName = "bds" | "db" | "tunnel" | "qq" | "llbot";
 export declare const SERVICE_NAMES: ServiceName[];
+export declare function setArgvDaemonize(on: boolean): void;
+/** 单服务 start 结果：optional 服务 validate 失败记为 skipped，不抛错 */
+export type StartOutcome = {
+    status: "started";
+} | {
+    status: "already";
+} | {
+    status: "skipped";
+    reason: string;
+};
+export interface StartAllResult {
+    started: ServiceName[];
+    skipped: Array<{
+        name: ServiceName;
+        reason: string;
+    }>;
+    failed: Array<{
+        name: ServiceName;
+        reason: string;
+    }>;
+}
 export interface ServiceStatus {
     name: ServiceName;
     title: string;
@@ -17,6 +56,7 @@ export interface ServiceStatus {
     uptime: string;
     ownership?: "managed" | "external";
 }
+export declare function getQqBackendMode(): QQBackend;
 interface ServiceDef {
     name: ServiceName;
     title: string;
@@ -29,9 +69,16 @@ interface ServiceDef {
     stopTimeout: number;
     autoRestart: boolean;
     restartDelay: number;
+    /**
+     * 可选服务：validate 失败时 start 返回 skipped（startAll 不当作失败）。
+     * 用于 official 下跳过 llbot、以及 qq_enabled=false。
+     */
+    optional?: boolean;
     validate?: () => string | null;
     /** 启动前钩子(如 BDS 装载一致性校验);失败则禁止 spawn */
     beforeStart?: () => Promise<void>;
+    /** 原始日志行观察器，不得阻塞子进程输出。 */
+    onLogLine?: (line: string) => void;
 }
 declare class Service {
     name: ServiceName;
@@ -44,13 +91,19 @@ declare class Service {
     events: EventEmitter<any>;
     private def;
     private manualStop;
+    private updateInProgress;
+    private restartTimer;
     constructor(def: ServiceDef);
     get uptime(): string;
     pushLog(text: string, stream: "stdout" | "stderr"): void;
-    start(): Promise<void>;
+    start(): Promise<StartOutcome>;
+    private scheduleRestart;
+    /** 更新器独立进程停服时，禁止将计划内退出当作崩溃并自动拉起。 */
+    beginUpdate(): void;
+    endUpdate(): void;
     stop(): Promise<void>;
     forceStop(): void;
-    restart(): Promise<void>;
+    restart(): Promise<StartOutcome>;
     getRecentLogs(n: number): LogLine[];
     /**
      * 探测发现进程已死后回写本地状态（不设 manualStop，以便 exit 回调仍可按需 autoRestart）。
@@ -61,7 +114,7 @@ declare class Service {
 export declare let services: Record<ServiceName, Service>;
 export declare function refreshServices(): void;
 export declare const START_ORDER: ServiceName[];
-export declare function startAll(): Promise<void>;
+export declare function startAll(): Promise<StartAllResult>;
 export declare function stopAll(): Promise<void>;
 export declare function forceStopAll(): void;
 export type ServiceStateEvent = {
@@ -73,7 +126,7 @@ export type ServiceStateEvent = {
 export declare function onServiceStateChange(fn: (ev: ServiceStateEvent) => void): () => void;
 /**
  * 统一运行态查询（权威入口）：OS/健康探测 + 回写 Service 内存标志。
- * status / Tab 发送目标 / remote / reload 等均应走此接口，勿直接读 `service.running`。
+ * status / Tab 发送目标 / reload 等均应走此接口，勿直接读 `service.running`。
  */
 export declare function queryServicesRuntime(): Promise<ServiceStatus[]>;
 /** 单服务是否在跑（含外部实例） */

package/dist/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"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"}

package/dist/services.js

@@ -1,10 +1,13 @@
 import {
-  ensureCoreConfigs,
-  loadEnsuredConfig,
   DEFAULT_BDS_UPDATER_CONFIG,
   DEFAULT_DB_CONFIG,
-  DEFAULT_QQ_CONFIG
+  DEFAULT_QQ_CONFIG,
+  ensureCoreConfigs,
+  loadEnsuredConfig,
+  qqRuntimeStatusPath,
+  readJson
 } from "@sfmc-bds/sdk/node/config";
+import { bdsExePath, bdsSpawnEnvExtra, ensureBdsExecutable } from "@sfmc-bds/bds-tools/host-platform";
 import {
   clearBdsPidFile,
   isProcessAlive,
@@ -12,17 +15,33 @@ import {
   readBdsPidFile,
   writeBdsPidFile
 } from "@sfmc-bds/bds-tools/process-probe";
+import { postBdsLifecycleEvent } from "@sfmc-bds/bds-tools/qq-events-notify";
 import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";
 import path from "node:path";
+import { t } from "./i18n/index.js";
+import { resolveLlbotLaunch } from "./llbot-launch.js";
 import { inferLevel, pushLog as pushUnifiedLog } from "./logs.js";
-import { ROOT, spawnService } from "./runtime.js";
+import { findNodeServicePids } from "./node-service-probe.js";
 import { ensurePackUpdateConfigFile } from "./pack-update/index.js";
-import { t } from "./i18n/index.js";
+import { recordBdsVersion } from "./bds-runtime-version.js";
+import { reportBdsPlayerSession } from "./player-session.js";
+import { ROOT, spawnService } from "./runtime.js";
 import { ROOT as ROOT2 } from "./runtime.js";
-const SERVICE_NAMES = ["bds", "db", "qq", "llbot"];
+function nonBlankOutputLines(text) {
+  return text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+}
+const SERVICE_NAMES = ["bds", "db", "tunnel", "qq", "llbot"];
+let argvDaemonize = false;
+function setArgvDaemonize(on) {
+  argvDaemonize = on;
+}
 let dbHealthPort = 3001;
+let qqBackendMode = "official";
+function getQqBackendMode() {
+  return qqBackendMode;
+}
 async function probeDbHealth(port) {
   try {
     const res = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(2e3) });
@@ -31,6 +50,28 @@ async function probeDbHealth(port) {
     return false;
   }
 }
+async function probeQqRuntime() {
+  const status = readJson(qqRuntimeStatusPath(ROOT));
+  if (!status?.pid || status.pid <= 0) return { alive: false, pid: 0 };
+  if (!await isProcessAlive(status.pid)) return { alive: false, pid: 0 };
+  return { alive: true, pid: status.pid };
+}
+const tunnelRuntimePath = path.join(ROOT, ".sfmc", "tunnel.runtime.json");
+async function probeTunnelRuntime() {
+  const pid = readJson(tunnelRuntimePath)?.pid;
+  return typeof pid === "number" && pid > 0 && await isProcessAlive(pid) ? pid : 0;
+}
+function writeTunnelRuntime(pid) {
+  fs.mkdirSync(path.dirname(tunnelRuntimePath), { recursive: true });
+  fs.writeFileSync(tunnelRuntimePath, JSON.stringify({ pid, startedAt: Date.now() }) + "\n");
+}
+function clearTunnelRuntime(pid) {
+  if (readJson(tunnelRuntimePath)?.pid !== pid) return;
+  try {
+    fs.unlinkSync(tunnelRuntimePath);
+  } catch {
+  }
+}
 class Service {
   name;
   title;
@@ -42,10 +83,17 @@ class Service {
   events = new EventEmitter();
   def;
   manualStop = false;
+  updateInProgress = false;
+  restartTimer = null;
   constructor(def) {
     this.name = def.name;
     this.title = def.title;
     this.def = def;
+    if (def.name === "tunnel") {
+      this.events.on("output", (text, level) => {
+        pushUnifiedLog(text, "tunnel", level);
+      });
+    }
   }
   get uptime() {
     if (!this.startTime || !this.running) return "\u2014";
@@ -63,31 +111,50 @@ class Service {
     this.events.emit("log", line);
     const level = stream === "stderr" ? "error" : inferLevel(text);
     pushUnifiedLog(text, this.name, level);
+    this.def.onLogLine?.(text);
   }
   async start() {
-    if (this.running) return;
+    if (this.updateInProgress) throw new Error("BDS \u6B63\u5728\u66F4\u65B0\uFF0C\u6682\u4E0D\u53EF\u542F\u52A8");
+    if (this.running) return { status: "already" };
     if (this.name === "bds") {
       const probe = await probeBdsStatus({ rootDir: ROOT });
       if (probe.state !== "stopped") {
         throw new Error(
-          t("svc.bdsAlreadyRunning", { pid: String(probe.pid), kind: t(probe.state === "managed" ? "svc.running" : "svc.runningExternal") })
+          t("svc.bdsAlreadyRunning", {
+            pid: String(probe.pid),
+            kind: t(probe.state === "managed" ? "svc.running" : "svc.runningExternal")
+          })
         );
       }
     }
+    if (this.name === "db" || this.name === "qq") {
+      const external = await findNodeServicePids(this.name);
+      if (external.length > 0) {
+        return { status: "already" };
+      }
+    }
+    if (this.name === "tunnel" && await probeTunnelRuntime()) return { status: "already" };
     if (this.def.validate) {
       const v = this.def.validate();
-      if (v) throw new Error(v);
+      if (v) {
+        if (this.def.optional) return { status: "skipped", reason: v };
+        throw new Error(v);
+      }
     }
     if (this.def.beforeStart) {
       await this.def.beforeStart();
     }
+    if (this.updateInProgress) throw new Error("BDS \u6B63\u5728\u66F4\u65B0\uFF0C\u6682\u4E0D\u53EF\u542F\u52A8");
     this.manualStop = false;
+    const daemonize = argvDaemonize && process.platform !== "win32";
     const spawnOpts = {
       cwd: this.def.cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-      env: this.def.env ? { ...process.env, ...this.def.env } : process.env
+      stdio: daemonize ? "ignore" : ["pipe", "pipe", "pipe"],
+      env: this.def.env ? { ...process.env, ...this.def.env } : process.env,
+      detached: daemonize
     };
     const child = this.def.service ? spawnService(this.def.service, this.def.args ?? [], spawnOpts) : spawn(this.def.cmd, this.def.args ?? [], spawnOpts);
+    if (daemonize) child.unref();
     this.proc = child;
     this.pid = child.pid ?? 0;
     this.running = true;
@@ -95,35 +162,86 @@ class Service {
     if (this.name === "bds" && this.pid > 0) {
       writeBdsPidFile(this.pid, ROOT);
     }
+    if (this.name === "tunnel" && this.pid > 0) writeTunnelRuntime(this.pid);
     this.events.emit("output", `started (PID ${this.pid})`, "info");
     this.events.emit("state", { name: this.name, running: true, pid: this.pid });
+    let lifecycleReported = false;
+    const reportExit = (code) => {
+      if (this.name !== "bds" || lifecycleReported) return;
+      lifecycleReported = true;
+      const planned = this.manualStop || this.updateInProgress;
+      void postBdsLifecycleEvent(planned ? "stop" : "crash", planned ? void 0 : `code=${code ?? "?"}`, {
+        port: dbHealthPort
+      });
+    };
+    if (this.name === "bds") {
+      child.once("spawn", () => {
+        void postBdsLifecycleEvent("start", void 0, { port: dbHealthPort });
+      });
+    }
     child.on("error", (e) => {
       this.events.emit("output", `process error: ${e.message}`, "error");
+      reportExit();
       this.cleanup();
+      this.scheduleRestart();
     });
+    let versionLineBuffer = "";
     child.stdout?.on("data", (d) => {
-      for (const line of d.toString().split("\n").filter(Boolean)) {
+      if (this.name === "bds" && this.startTime) {
+        versionLineBuffer += d.toString();
+        const versionLines = versionLineBuffer.split(/\r?\n/);
+        versionLineBuffer = (versionLines.pop() ?? "").slice(-4096);
+        for (const versionLine of versionLines) recordBdsVersion(ROOT, versionLine, this.pid, this.startTime.getTime());
+      }
+      for (const line of nonBlankOutputLines(d.toString())) {
         this.pushLog(line, "stdout");
       }
     });
     child.stderr?.on("data", (d) => {
-      for (const line of d.toString().split("\n").filter(Boolean)) {
+      for (const line of nonBlankOutputLines(d.toString())) {
         this.pushLog(line, "stderr");
       }
     });
     child.on("exit", (code) => {
+      if (this.proc && this.proc !== child) return;
       this.events.emit("output", `exited (code: ${code})`, "info");
+      reportExit(code);
       this.cleanup();
-      if (!this.manualStop && this.def.autoRestart) {
-        setTimeout(() => {
-          void this.start();
-        }, this.def.restartDelay);
-      }
+      this.scheduleRestart();
     });
+    return { status: "started" };
+  }
+  scheduleRestart() {
+    if (this.manualStop || this.updateInProgress || !this.def.autoRestart || this.restartTimer) return;
+    this.restartTimer = setTimeout(() => {
+      this.restartTimer = null;
+      if (!this.updateInProgress && !this.manualStop && !this.running) {
+        void this.start().catch((e) => {
+          this.events.emit("output", `restart failed: ${e.message}`, "error");
+        });
+      }
+    }, this.def.restartDelay);
+  }
+  /** 更新器独立进程停服时，禁止将计划内退出当作崩溃并自动拉起。 */
+  beginUpdate() {
+    if (this.name !== "bds") return;
+    if (this.updateInProgress) throw new Error("BDS \u66F4\u65B0\u5DF2\u5728\u8FDB\u884C\u4E2D");
+    this.updateInProgress = true;
+    if (this.restartTimer) {
+      clearTimeout(this.restartTimer);
+      this.restartTimer = null;
+    }
+  }
+  endUpdate() {
+    this.updateInProgress = false;
   }
   async stop() {
-    if (!this.proc || !this.running) return;
     this.manualStop = true;
+    if (this.restartTimer) {
+      clearTimeout(this.restartTimer);
+      this.restartTimer = null;
+    }
+    if (!this.proc || !this.running) return;
     this.events.emit("output", "stopping...", "info");
     if (this.def.stopCommand && this.proc.stdin) {
       this.proc.stdin.write(this.def.stopCommand + "\n");
@@ -150,6 +268,10 @@ class Service {
   forceStop() {
     const child = this.proc;
     this.manualStop = true;
+    if (this.restartTimer) {
+      clearTimeout(this.restartTimer);
+      this.restartTimer = null;
+    }
     this.cleanup();
     if (!child) return;
     try {
@@ -159,7 +281,7 @@ class Service {
   }
   async restart() {
     await this.stop();
-    await this.start();
+    return this.start();
   }
   getRecentLogs(n) {
     return this.logs.slice(-n);
@@ -184,6 +306,7 @@ class Service {
         clearBdsPidFile(ROOT);
       }
     }
+    if (this.name === "tunnel" && exitingPid > 0) clearTunnelRuntime(exitingPid);
     if (wasRunning) {
       this.events.emit("state", { name: this.name, running: false, pid: 0 });
     }
@@ -192,31 +315,26 @@ class Service {
 function createServices() {
   ensureCoreConfigs(ROOT, ["bds_updater", "qq_config", "db_config"]);
   ensurePackUpdateConfigFile();
-  const bdsCfg = loadEnsuredConfig(
-    ROOT,
-    "bds_updater.json",
-    "bds_updater",
-    { ...DEFAULT_BDS_UPDATER_CONFIG }
-  );
-  const qqCfg = loadEnsuredConfig(
-    ROOT,
-    "qq_config.json",
-    "qq_config",
-    { ...DEFAULT_QQ_CONFIG }
-  );
-  const dbCfg = loadEnsuredConfig(
-    ROOT,
-    "db_config.json",
-    "db_config",
-    { ...DEFAULT_DB_CONFIG }
-  );
+  const bdsCfg = loadEnsuredConfig(ROOT, "bds_updater.json", "bds_updater", { ...DEFAULT_BDS_UPDATER_CONFIG });
+  const qqCfg = loadEnsuredConfig(ROOT, "qq_config.json", "qq_config", { ...DEFAULT_QQ_CONFIG });
+  const dbCfg = loadEnsuredConfig(ROOT, "db_config.json", "db_config", { ...DEFAULT_DB_CONFIG });
   const bdsPath = bdsCfg.bds_path ?? ROOT;
-  const llbotEnabled = qqCfg.llbot_enabled !== false;
-  const llbotPath = qqCfg.llbot_path ?? "D:\\LLBot-CLI-win-x64\\llbot.exe";
-  const llbotCwd = qqCfg.llbot_cwd ?? "D:\\LLBot-CLI-win-x64";
+  const useLlbotBackend = qqCfg.qq_backend === "llbot";
+  const qqEnabled = qqCfg.qq_enabled !== false;
+  const qqExternal = !useLlbotBackend && qqCfg.official?.transport === "webhook";
+  const tunnelCfg = qqCfg.official?.tunnel;
+  const tunnelEnabled = qqEnabled && qqExternal && tunnelCfg?.enabled === true;
+  const tunnelHost = String(tunnelCfg?.host ?? "").trim();
+  const tunnelRemotePort = tunnelCfg?.remotePort ?? 13001;
+  const llbotEnabled = qqCfg.llbot?.enabled !== false;
+  const llbotLaunch = resolveLlbotLaunch(qqCfg.llbot?.path, qqCfg.llbot?.cwd);
+  const llbotPath = llbotLaunch.exe;
+  const llbotCwd = llbotLaunch.cwd;
   const dbPort = dbCfg.db_port ?? 3001;
   dbHealthPort = dbPort;
-  const bdsExe = path.resolve(bdsPath, "bedrock_server.exe");
+  qqBackendMode = useLlbotBackend ? "llbot" : "official";
+  const bdsExe = bdsExePath(path.resolve(bdsPath));
+  const qqTitle = useLlbotBackend ? "QQ (llbot)" : "QQ (official)";
   return {
     bds: new Service({
       name: "bds",
@@ -224,6 +342,7 @@ function createServices() {
       cmd: bdsExe,
       args: [],
       cwd: bdsPath,
+      env: bdsSpawnEnvExtra(bdsPath),
       stopCommand: "stop",
       stopTimeout: 3e4,
       autoRestart: bdsCfg.crash_restart !== false,
@@ -233,13 +352,18 @@ function createServices() {
         return null;
       },
       beforeStart: async () => {
+        ensureBdsExecutable(bdsExe);
         const { scanAndInstallInbox } = await import("./world-packs.js");
         await scanAndInstallInbox({ interactive: false });
         const { runPackUpdatesOnBdsStart } = await import("./pack-update/index.js");
         await runPackUpdatesOnBdsStart();
         const { ensurePacksReady } = await import("./pack-lifecycle.js");
         await ensurePacksReady();
-      }
+      },
+      onLogLine: (line) => reportBdsPlayerSession(line, {
+        port: dbPort,
+        ...dbCfg.http_auth ? { authToken: dbCfg.http_auth } : {}
+      })
     }),
     db: new Service({
       name: "db",
@@ -251,14 +375,61 @@ function createServices() {
       restartDelay: 3e3,
       env: { DB_PORT: String(dbPort) }
     }),
+    tunnel: new Service({
+      name: "tunnel",
+      title: "QQ SSH Tunnel",
+      cmd: "ssh",
+      args: [
+        "-N",
+        "-T",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        "ConnectTimeout=10",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        "-o",
+        "ServerAliveInterval=30",
+        "-o",
+        "ServerAliveCountMax=3",
+        "-R",
+        `127.0.0.1:${tunnelRemotePort}:127.0.0.1:${dbPort}`,
+        tunnelHost
+      ],
+      cwd: ROOT,
+      stopTimeout: 1e4,
+      autoRestart: true,
+      restartDelay: 5e3,
+      optional: !tunnelEnabled,
+      validate: () => {
+        if (!tunnelEnabled) return "QQ tunnel disabled (official webhook tunnel.enabled=false)";
+        if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(tunnelHost)) return "invalid official.tunnel.host";
+        if (!Number.isInteger(tunnelRemotePort) || tunnelRemotePort < 1 || tunnelRemotePort > 65535) {
+          return "invalid official.tunnel.remotePort";
+        }
+        return null;
+      }
+    }),
     qq: new Service({
       name: "qq",
-      title: "QQ Bridge",
+      title: qqTitle,
       service: "qq",
       cwd: ROOT,
       stopTimeout: 1e4,
+      // 缺凭据时 validate 拦下，不会 spawn→exit(1)→autoRestart 死循环
       autoRestart: true,
-      restartDelay: 3e3
+      restartDelay: 3e3,
+      optional: !qqEnabled || qqExternal,
+      validate: () => {
+        if (!qqEnabled) return "QQ bridge disabled (qq_enabled=false)";
+        if (qqExternal) return "QQ bridge runs externally (official.transport=webhook)";
+        if (!useLlbotBackend) {
+          if (!String(qqCfg.official?.app_id ?? "").trim() || !String(qqCfg.official?.app_secret ?? "").trim()) {
+            return "missing official.app_id / official.app_secret";
+          }
+        }
+        return null;
+      }
     }),
     llbot: new Service({
       name: "llbot",
@@ -269,8 +440,11 @@ function createServices() {
       stopTimeout: 1e4,
       autoRestart: false,
       restartDelay: 5e3,
+      // official 或未启用时真正 skip，不 throw
+      optional: !useLlbotBackend || !llbotEnabled,
       validate: () => {
-        if (!llbotEnabled) return "LLBot disabled (llbot_enabled=false)";
+        if (!useLlbotBackend) return "LLBot skipped (qq_backend!=llbot)";
+        if (!llbotEnabled) return "LLBot disabled (llbot.enabled=false)";
         if (!fs.existsSync(llbotPath)) return `not found: ${llbotPath}`;
         return null;
       }
@@ -282,20 +456,30 @@ function refreshServices() {
   forceStopAll();
   services = createServices();
 }
-const START_ORDER = ["db", "qq", "llbot", "bds"];
+const START_ORDER = ["db", "tunnel", "qq", "llbot", "bds"];
 async function startAll() {
+  const result = { started: [], skipped: [], failed: [] };
   for (const name of START_ORDER) {
     const svc = services[name];
     if (!svc) continue;
     try {
-      await svc.start();
+      const outcome = await svc.start();
+      if (outcome.status === "skipped") {
+        result.skipped.push({ name, reason: outcome.reason });
+        svc.events.emit("output", `skipped: ${outcome.reason}`, "info");
+      } else {
+        result.started.push(name);
+      }
     } catch (e) {
-      svc.events.emit("output", `start error: ${e.message}`, "error");
+      const reason = e.message;
+      result.failed.push({ name, reason });
+      svc.events.emit("output", `start error: ${reason}`, "error");
     }
   }
+  return result;
 }
 async function stopAll() {
-  const pending = [...START_ORDER].reverse().map((name) => services[name]).filter((service) => Boolean(service?.running)).map((service) => service.stop());
+  const pending = [...START_ORDER].reverse().map((name) => services[name]).filter((service) => Boolean(service)).map((service) => service.stop());
   await Promise.allSettled(pending);
 }
 function forceStopAll() {
@@ -366,6 +550,42 @@ async function queryServicesRuntime() {
         } else if (await probeDbHealth(dbHealthPort)) {
           running = true;
           ownership = "external";
+          const pids = await findNodeServicePids("db");
+          pid = pids[0] ?? 0;
+        }
+      } else if (name === "qq") {
+        const managed = await reconcileManagedAlive(service);
+        if (managed) {
+          running = true;
+          pid = service.pid;
+          uptime = service.uptime;
+          ownership = "managed";
+        } else {
+          const probe = await probeQqRuntime();
+          if (probe.alive) {
+            running = true;
+            pid = probe.pid;
+            ownership = "external";
+          } else {
+            const pids = await findNodeServicePids("qq");
+            if (pids.length > 0) {
+              running = true;
+              pid = pids[0];
+              ownership = "external";
+            }
+          }
+        }
+      } else if (name === "tunnel") {
+        const managed = await reconcileManagedAlive(service);
+        if (managed) {
+          running = true;
+          pid = service.pid;
+          uptime = service.uptime;
+          ownership = "managed";
+        } else {
+          pid = await probeTunnelRuntime();
+          running = pid > 0;
+          if (running) ownership = "external";
         }
       } else {
         const managed = await reconcileManagedAlive(service);
@@ -396,11 +616,14 @@ export {
   SERVICE_NAMES,
   START_ORDER,
   forceStopAll,
+  getQqBackendMode,
   isServiceRunning,
+  nonBlankOutputLines,
   onServiceStateChange,
   queryServicesRuntime,
   refreshServices,
   services,
+  setArgvDaemonize,
   startAll,
   stopAll
 };