@web-auto/webauto 0.1.13 → 0.1.15

package/README.md

@@ -0,0 +1,137 @@
+# @web-auto/webauto
+
+Windows 优先的 WebAuto CLI + Desktop UI 使用说明。
+
+## 1. 安装（Windows）
+
+要求：
+- Node.js 18+（建议 20+）
+- npm 可用
+
+全局安装：
+
+```bat
+npm install -g @web-auto/webauto
+```
+
+验证：
+
+```bat
+webauto --help
+```
+
+## 2. 直接启动 UI
+
+最直接方式：
+
+```bat
+webauto ui console
+```
+
+或用 UI CLI 自动拉起（适合脚本化）：
+
+```bat
+webauto ui cli start --json
+webauto ui cli status --json
+```
+
+说明：
+- 首次启动会自动准备 Desktop runtime 依赖（Electron），不需要手工安装。
+- 启动成功后，UI CLI bridge 默认端口是 `7716`。
+
+## 3. UI CLI 常用命令（模拟真实 UI 操作）
+
+```bat
+webauto ui cli --help
+
+:: 切换到任务页
+webauto ui cli tab --tab tasks --json
+
+:: 输入任务参数
+webauto ui cli input --selector "#task-keyword" --value "deepseek" --json
+webauto ui cli input --selector "#task-target" --value "20" --json
+
+:: 点击执行
+webauto ui cli click --selector "#task-run-ephemeral-btn" --json
+
+:: 读取当前 UI 快照
+webauto ui cli status --json
+webauto ui cli snapshot --json
+
+:: 元素探测
+webauto ui cli probe --selector "#task-likes" --json
+```
+
+任务状态查看（后端状态）：
+
+```bat
+webauto xhs status --json
+webauto xhs status --run-id <runId> --json
+```
+
+## 4. Windows 路径与设置
+
+默认数据目录（未设置环境变量时）：
+- 有 `D:` 盘：`D:\webauto`
+- 无 `D:` 盘：`%USERPROFILE%\.webauto`
+
+可选环境变量：
+- `WEBAUTO_HOME`：显式指定数据根目录（推荐）
+- `WEBAUTO_ROOT` / `WEBAUTO_PORTABLE_ROOT`：兼容旧变量（会归一化到 `.webauto`）
+
+PowerShell 设置示例：
+
+```powershell
+$env:WEBAUTO_HOME = "D:\webauto"
+webauto ui console
+```
+
+CMD 设置示例：
+
+```bat
+set WEBAUTO_HOME=D:\webauto
+webauto ui console
+```
+
+不设置也可以直接用，系统会按默认规则落盘。
+
+## 5. 首次安装常见问题
+
+### 5.1 `Lock file can not be created` / 启动失败
+
+说明：通常是残留的 Electron/Node 进程占用。
+
+```bat
+taskkill /F /IM electron.exe /T
+taskkill /F /IM node.exe /T
+webauto ui console
+```
+
+### 5.2 `ui cli fetch failed`
+
+先确认 UI 已启动并就绪：
+
+```bat
+webauto ui cli start --json
+webauto ui cli status --json
+```
+
+若仍失败，前台启动看日志：
+
+```bat
+webauto ui console --no-daemon
+```
+
+## 6. 资源检查/安装
+
+```bat
+webauto xhs install --check --json
+webauto xhs install --download-browser --json
+webauto xhs install --download-geoip --json
+```
+
+## 7. 开发者（仓库模式）
+
+在仓库中开发请看：
+- `apps/desktop-console/README.md`
+

package/apps/desktop-console/dist/main/index.mjs

@@ -272,14 +272,14 @@ import { spawn } from "child_process";
 import path2 from "path";
 import { existsSync as existsSync3 } from "fs";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
 var REPO_ROOT = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "../../../..");
 var UNIFIED_API_HEALTH_URL = "http://127.0.0.1:7701/health";
 var CAMO_RUNTIME_HEALTH_URL = "http://127.0.0.1:7704/health";
 var CORE_HEALTH_URLS = [UNIFIED_API_HEALTH_URL, CAMO_RUNTIME_HEALTH_URL];
 var START_API_SCRIPT = path2.join(REPO_ROOT, "runtime", "infra", "utils", "scripts", "service", "start-api.mjs");
 var STOP_API_SCRIPT = path2.join(REPO_ROOT, "runtime", "infra", "utils", "scripts", "service", "stop-api.mjs");
-var DIST_UNIFIED_ENTRY = path2.join(REPO_ROOT, "dist", "apps", "webauto", "server.js");
-var fallbackUnifiedApiPid = null;
+var requireFromRepo = createRequire(path2.join(REPO_ROOT, "package.json"));
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -292,13 +292,6 @@ function resolveNodeBin() {
   if (fromPath) return fromPath;
   return process.execPath;
 }
-function resolveNpxBin() {
-  const fromPath = resolveOnPath(
-    process.platform === "win32" ? ["npx.cmd", "npx.exe", "npx.bat", "npx.ps1"] : ["npx"]
-  );
-  if (fromPath) return fromPath;
-  return process.platform === "win32" ? "npx.cmd" : "npx";
-}
 function resolveOnPath(candidates) {
   const pathEnv = process.env.PATH || process.env.Path || "";
   const dirs = pathEnv.split(path2.delimiter).filter(Boolean);
@@ -310,10 +303,15 @@ function resolveOnPath(candidates) {
   }
   return null;
 }
-function quoteCmdArg(value) {
-  if (!value) return '""';
-  if (!/[\s"]/u.test(value)) return value;
-  return `"${value.replace(/"/g, '""')}"`;
+function resolveCamoCliEntry() {
+  const direct = path2.join(REPO_ROOT, "node_modules", "@web-auto", "camo", "bin", "camo.mjs");
+  if (existsSync3(direct)) return direct;
+  try {
+    const resolved = requireFromRepo.resolve("@web-auto/camo/bin/camo.mjs");
+    if (resolved && existsSync3(resolved)) return resolved;
+  } catch {
+  }
+  return null;
 }
 async function checkHttpHealth(url) {
   try {
@@ -327,156 +325,100 @@ async function areCoreServicesHealthy() {
   const health = await Promise.all(CORE_HEALTH_URLS.map((url) => checkHttpHealth(url)));
   return health.every(Boolean);
 }
-async function isUnifiedApiHealthy() {
-  return checkHttpHealth(UNIFIED_API_HEALTH_URL);
-}
-async function runNodeScript(scriptPath, timeoutMs) {
-  return new Promise((resolve) => {
-    const nodeBin = resolveNodeBin();
-    const child = spawn(nodeBin, [scriptPath], {
-      cwd: REPO_ROOT,
-      stdio: "ignore",
-      windowsHide: true,
-      detached: false,
-      env: {
-        ...process.env,
-        BROWSER_SERVICE_AUTO_EXIT: "0"
-      }
-    });
-    const timer = setTimeout(() => {
-      try {
-        child.kill("SIGTERM");
-      } catch {
-      }
-      resolve(false);
-    }, timeoutMs);
-    child.once("error", () => {
-      clearTimeout(timer);
-      resolve(false);
-    });
-    child.once("exit", (code) => {
-      clearTimeout(timer);
-      resolve(code === 0);
-    });
-  });
-}
-async function runLongLivedNodeScript(scriptPath) {
+async function runNodeScript(scriptPath, timeoutMs, args = [], envExtra = {}) {
   return new Promise((resolve) => {
     const nodeBin = resolveNodeBin();
-    const child = spawn(nodeBin, [scriptPath], {
+    const child = spawn(nodeBin, [scriptPath, ...args], {
       cwd: REPO_ROOT,
-      stdio: "ignore",
+      stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
       detached: false,
       env: {
         ...process.env,
-        WEBAUTO_RUNTIME_MODE: "unified"
+        ...envExtra
       }
     });
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      fallbackUnifiedApiPid = typeof child.pid === "number" ? child.pid : null;
-      resolve(true);
-    }, 200);
-    child.once("error", () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(false);
+    const stderrLines = [];
+    const stdoutLines = [];
+    child.stdout?.on("data", (chunk) => {
+      const text = String(chunk || "").trim();
+      if (!text) return;
+      stdoutLines.push(text);
+      if (stdoutLines.length > 6) stdoutLines.shift();
     });
-    child.once("exit", () => {
-      if (!settled) {
-        settled = true;
-        clearTimeout(timer);
-        resolve(false);
-        return;
-      }
-      if (fallbackUnifiedApiPid && child.pid === fallbackUnifiedApiPid) {
-        fallbackUnifiedApiPid = null;
-      }
-    });
-  });
-}
-async function runCommand(command, args, timeoutMs) {
-  return new Promise((resolve) => {
-    const lower = String(command || "").toLowerCase();
-    let spawnCommand2 = command;
-    let spawnArgs = args;
-    if (process.platform === "win32" && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-      spawnCommand2 = "cmd.exe";
-      const cmdLine = [quoteCmdArg(command), ...args.map(quoteCmdArg)].join(" ");
-      spawnArgs = ["/d", "/s", "/c", cmdLine];
-    } else if (process.platform === "win32" && lower.endsWith(".ps1")) {
-      spawnCommand2 = "powershell.exe";
-      spawnArgs = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", command, ...args];
-    }
-    const child = spawn(spawnCommand2, spawnArgs, {
-      cwd: REPO_ROOT,
-      stdio: "ignore",
-      windowsHide: true,
-      detached: false,
-      env: {
-        ...process.env
-      }
+    child.stderr?.on("data", (chunk) => {
+      const text = String(chunk || "").trim();
+      if (!text) return;
+      stderrLines.push(text);
+      if (stderrLines.length > 6) stderrLines.shift();
     });
+    const summarize = (prefix) => {
+      const stderr = stderrLines.join("\n").trim();
+      const stdout = stdoutLines.join("\n").trim();
+      if (stderr) return `${prefix}: ${stderr}`;
+      if (stdout) return `${prefix}: ${stdout}`;
+      return prefix;
+    };
     const timer = setTimeout(() => {
       try {
         child.kill("SIGTERM");
       } catch {
       }
-      resolve(false);
+      resolve({ ok: false, code: null, error: summarize("timeout") });
     }, timeoutMs);
-    child.once("error", () => {
+    child.once("error", (err) => {
       clearTimeout(timer);
-      resolve(false);
+      resolve({ ok: false, code: null, error: summarize(err?.message || "spawn_error") });
     });
     child.once("exit", (code) => {
       clearTimeout(timer);
-      resolve(code === 0);
+      if (code === 0) {
+        resolve({ ok: true, code, error: "" });
+        return;
+      }
+      resolve({ ok: false, code, error: summarize(`exit ${code ?? "null"}`) });
     });
   });
 }
 async function startCoreDaemon() {
   if (await areCoreServicesHealthy()) return true;
-  const startedApi = existsSync3(START_API_SCRIPT) ? await runNodeScript(START_API_SCRIPT, 4e4) : existsSync3(DIST_UNIFIED_ENTRY) ? await runLongLivedNodeScript(DIST_UNIFIED_ENTRY) : false;
-  if (!startedApi) {
-    console.error("[CoreDaemonManager] Failed to start unified API service");
+  if (!existsSync3(START_API_SCRIPT)) {
+    console.error("[CoreDaemonManager] Unified API start script not found");
     return false;
   }
-  const startedBrowser = await runCommand(
-    resolveNpxBin(),
-    ["--yes", "--package=@web-auto/camo", "camo", "init"],
-    4e4
-  );
-  if (!startedBrowser) {
-    console.warn("[CoreDaemonManager] Failed to start camo browser backend, continue in degraded mode");
+  const startedApi = await runNodeScript(START_API_SCRIPT, 4e4, [], {
+    BROWSER_SERVICE_AUTO_EXIT: "0"
+  });
+  if (!startedApi.ok) {
+    console.error(`[CoreDaemonManager] Failed to start unified API service (${startedApi.error || "unknown"})`);
+    return false;
+  }
+  const camoEntry = resolveCamoCliEntry();
+  if (!camoEntry) {
+    console.error("[CoreDaemonManager] Camo CLI entry not found: @web-auto/camo/bin/camo.mjs");
+    return false;
+  }
+  const startedBrowser = await runNodeScript(camoEntry, 6e4, ["init"]);
+  if (!startedBrowser.ok) {
+    console.error(`[CoreDaemonManager] Failed to start camo browser backend (${startedBrowser.error || "unknown"})`);
+    return false;
   }
   for (let i = 0; i < 60; i += 1) {
-    const [allHealthy, unifiedHealthy] = await Promise.all([
-      areCoreServicesHealthy(),
-      isUnifiedApiHealthy()
-    ]);
+    const allHealthy = await areCoreServicesHealthy();
     if (allHealthy) return true;
-    if (unifiedHealthy) return true;
     await sleep(500);
   }
-  console.error("[CoreDaemonManager] Unified API still unhealthy after start");
+  console.error("[CoreDaemonManager] Core services still unhealthy after start");
   return false;
 }
 async function stopCoreDaemon() {
-  if (fallbackUnifiedApiPid) {
-    try {
-      process.kill(fallbackUnifiedApiPid, "SIGTERM");
-    } catch {
-    }
-    fallbackUnifiedApiPid = null;
+  if (!existsSync3(STOP_API_SCRIPT)) {
+    console.error("[CoreDaemonManager] Unified API stop script not found");
+    return false;
   }
-  if (!existsSync3(STOP_API_SCRIPT)) return true;
   const stoppedApi = await runNodeScript(STOP_API_SCRIPT, 2e4);
-  if (!stoppedApi) {
-    console.error("[CoreDaemonManager] Failed to stop core services");
+  if (!stoppedApi.ok) {
+    console.error(`[CoreDaemonManager] Failed to stop core services (${stoppedApi.error || "unknown"})`);
     return false;
   }
   return true;
@@ -813,22 +755,6 @@ function resolveWebautoRoot() {
   }
   return path4.join(os3.homedir(), ".webauto");
 }
-function resolveNpxBin2() {
-  if (process.platform !== "win32") return "npx";
-  const resolved = resolveOnPath2(["npx.cmd", "npx.exe", "npx.bat", "npx.ps1"]);
-  return resolved || "npx.cmd";
-}
-function resolveOnPath2(candidates) {
-  const pathEnv = process.env.PATH || process.env.Path || "";
-  const dirs = pathEnv.split(path4.delimiter).filter(Boolean);
-  for (const dir of dirs) {
-    for (const name of candidates) {
-      const full = path4.join(dir, name);
-      if (existsSync4(full)) return full;
-    }
-  }
-  return null;
-}
 function resolveCamoVersionFromText(stdout, stderr) {
   const merged = `${String(stdout || "")}
 ${String(stderr || "")}`.trim();
@@ -841,7 +767,7 @@ ${String(stderr || "")}`.trim();
   }
   return "unknown";
 }
-function quoteCmdArg2(value) {
+function quoteCmdArg(value) {
   if (!value) return '""';
   if (!/[\s"]/u.test(value)) return value;
   return `"${value.replace(/"/g, '""')}"`;
@@ -851,7 +777,7 @@ function runVersionCheck(command, args, explicitPath) {
     const lower = String(command || "").toLowerCase();
     let ret;
     if (process.platform === "win32" && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-      const cmdLine = [quoteCmdArg2(command), ...args.map(quoteCmdArg2)].join(" ");
+      const cmdLine = [quoteCmdArg(command), ...args.map(quoteCmdArg)].join(" ");
       ret = spawnSync("cmd.exe", ["/d", "/s", "/c", cmdLine], {
         encoding: "utf8",
         timeout: 8e3,
@@ -920,15 +846,9 @@ async function checkCamoCli() {
       if (ret.installed) return ret;
     }
   }
-  const npxCheck = runVersionCheck(
-    resolveNpxBin2(),
-    ["--yes", "--package=@web-auto/camo", "camo", "help"],
-    "npx:@web-auto/camo"
-  );
-  if (npxCheck.installed) return npxCheck;
   return {
     installed: false,
-    error: "camo not found in PATH/local bin, and npx @web-auto/camo failed"
+    error: "camo not found in PATH/local bin"
   };
 }
 async function checkServices() {
@@ -943,12 +863,10 @@ async function checkFirefox() {
   const candidates = process.platform === "win32" ? [
     { command: "camoufox", args: ["path"] },
     { command: "python", args: ["-m", "camoufox", "path"] },
-    { command: "py", args: ["-3", "-m", "camoufox", "path"] },
-    { command: resolveNpxBin2(), args: ["--yes", "--package=camoufox", "camoufox", "path"] }
+    { command: "py", args: ["-3", "-m", "camoufox", "path"] }
   ] : [
     { command: "camoufox", args: ["path"] },
-    { command: "python3", args: ["-m", "camoufox", "path"] },
-    { command: resolveNpxBin2(), args: ["--yes", "--package=camoufox", "camoufox", "path"] }
+    { command: "python3", args: ["-m", "camoufox", "path"] }
   ];
   for (const candidate of candidates) {
     try {
@@ -982,7 +900,7 @@ async function checkEnvironment() {
     checkFirefox(),
     checkGeoIP()
   ]);
-  const browserReady = Boolean(firefox.installed || services.camoRuntime);
+  const browserReady = Boolean(services.camoRuntime);
   const missing = {
     core: !services.unifiedApi,
     runtimeService: !services.camoRuntime,
@@ -990,7 +908,7 @@ async function checkEnvironment() {
     runtime: !browserReady,
     geoip: !geoip.installed
   };
-  const allReady = camo.installed && services.unifiedApi && browserReady;
+  const allReady = camo.installed && services.unifiedApi && services.camoRuntime;
   return { camo, services, firefox, geoip, browserReady, missing, allReady };
 }
 
@@ -2822,16 +2740,30 @@ app.on("will-quit", () => {
 });
 app.whenReady().then(async () => {
   startCoreServiceHeartbeat();
-  const started = await startCoreDaemon().catch(() => false);
+  const started = await startCoreDaemon().catch((err) => {
+    console.error("[desktop-console] core services startup failed", err);
+    return false;
+  });
   if (!started) {
-    console.warn("[desktop-console] core services are not healthy at startup");
+    console.error("[desktop-console] core services are not healthy at startup; exiting");
+    await ensureAppExitCleanup("core_startup_failed", { stopStateBridge: true }).catch(() => null);
+    app.exit(1);
+    return;
   }
   markUiHeartbeat("main_ready");
   ensureHeartbeatWatchdog();
   createWindow();
-  await uiCliBridge.start().catch((err) => {
-    console.warn("[desktop-console] ui-cli bridge start failed", err);
-  });
+  try {
+    await uiCliBridge.start();
+  } catch (err) {
+    console.error("[desktop-console] ui-cli bridge start failed", err);
+    await ensureAppExitCleanup("ui_cli_bridge_start_failed", { stopStateBridge: true }).catch(() => null);
+    app.exit(1);
+  }
+}).catch(async (err) => {
+  console.error("[desktop-console] fatal startup error", err);
+  await ensureAppExitCleanup("startup_exception", { stopStateBridge: true }).catch(() => null);
+  app.exit(1);
 });
 ipcMain2.on("preload:test", () => {
   console.log("[preload-test] window.api OK");

package/apps/desktop-console/dist/renderer/index.js

@@ -1582,7 +1582,7 @@ function renderSetupWizard(root, ctx2) {
       <div class="env-item" id="env-browser" style="display:flex; align-items:center; justify-content:space-between; gap:8px;">
         <span style="display:flex; align-items:center; gap:8px; min-width:0;">
           <span class="icon" style="color: var(--text-4);">\u25CB</span>
-          <span class="env-label">Camo Runtime Service (7704\uFF0C\u53EF\u9009)</span>
+          <span class="env-label">Camo Runtime Service (7704)</span>
         </span>
         <button id="repair-core2-btn" class="secondary" style="display:none; flex:0 0 auto;">\u4E00\u952E\u4FEE\u590D</button>
       </div>
@@ -1862,13 +1862,8 @@ function renderSetupWizard(root, ctx2) {
         if (missingFlags.core) missing.push("unified-api");
         if (missingFlags.runtime) missing.push("browser-kernel");
         setupStatusText.textContent = `\u5B58\u5728\u5F85\u4FEE\u590D\u9879: ${missing.join(", ")}`;
-        if (missingFlags.runtimeService) {
-          setupStatusText.textContent += "\uFF08camo-runtime \u672A\u5C31\u7EEA\uFF0C\u5F53\u524D\u4E3A\u53EF\u9009\uFF09";
-        }
       } else if (!snapshot?.geoip?.installed) {
         setupStatusText.textContent = "\u73AF\u5883\u5C31\u7EEA\uFF08GeoIP \u53EF\u9009\uFF0C\u672A\u5B89\u88C5\u4E0D\u5F71\u54CD\u4F7F\u7528\uFF09";
-      } else if (!snapshot?.services?.camoRuntime) {
-        setupStatusText.textContent = "\u73AF\u5883\u5C31\u7EEA\uFF08camo-runtime \u672A\u5C31\u7EEA\uFF0C\u5F53\u524D\u4E0D\u963B\u585E\uFF09";
       }
     } catch (err) {
       console.error("Environment check failed:", err);
@@ -4094,7 +4089,7 @@ function renderAccountManager(root, ctx2) {
       </div>
       <div class="env-item" id="env-browser">
         <span class="icon" style="color: var(--text-4);">\u25CB</span>
-        <span>Camo Runtime Service (7704\uFF0C\u53EF\u9009)</span>
+        <span>Camo Runtime Service (7704)</span>
       </div>
       <div class="env-item" id="env-firefox">
         <span class="icon" style="color: var(--text-4);">\u25CB</span>

package/apps/desktop-console/entry/ui-console.mjs

@@ -94,6 +94,45 @@ function checkBuildStatus() {
   return existsSync(DIST_MAIN);
 }
 
+function quotePsSingle(value) {
+  return String(value || '').replace(/'/g, "''");
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForCoreServicesHealthy(timeoutMs = 90000) {
+  const startedAt = Date.now();
+  while ((Date.now() - startedAt) <= timeoutMs) {
+    try {
+      const [coreRes, runtimeRes] = await Promise.all([
+        fetch('http://127.0.0.1:7701/health', { signal: AbortSignal.timeout(1500) }),
+        fetch('http://127.0.0.1:7704/health', { signal: AbortSignal.timeout(1500) }),
+      ]);
+      if (coreRes.ok && runtimeRes.ok) return true;
+    } catch {
+      // keep polling
+    }
+    await sleep(500);
+  }
+  return false;
+}
+
+function terminateProcessTree(pid) {
+  const target = Number(pid || 0);
+  if (!Number.isFinite(target) || target <= 0) return;
+  try {
+    if (process.platform === 'win32') {
+      spawn('taskkill', ['/PID', String(target), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      return;
+    }
+    process.kill(target, 'SIGTERM');
+  } catch {
+    // ignore cleanup errors
+  }
+}
+
 async function build() {
   return new Promise((resolve, reject) => {
     console.log('[ui-console] Building...');
@@ -131,23 +170,60 @@ async function startConsole(noDaemon = false) {
   }
 
   console.log('[ui-console] Starting Desktop Console...');
-  const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
   const env = { ...process.env };
   if (noDaemon) env.WEBAUTO_NO_DAEMON = '1';
   const detached = !noDaemon;
   const stdio = detached ? 'ignore' : 'inherit';
-
-  const useCmd = process.platform === 'win32';
-  const spawnCmd = useCmd ? 'cmd.exe' : npxBin;
-  const spawnArgs = useCmd
-    ? ['/d', '/s', '/c', npxBin, 'electron', DIST_MAIN]
-    : ['electron', DIST_MAIN];
+  const electronBin = process.platform === 'win32'
+    ? path.join(APP_ROOT, 'node_modules', 'electron', 'dist', 'electron.exe')
+    : path.join(APP_ROOT, 'node_modules', 'electron', 'dist', 'electron');
+  if (!existsSync(electronBin)) {
+    throw new Error(`electron binary not found: ${electronBin}`);
+  }
+  const spawnCmd = electronBin;
+  const spawnArgs = [DIST_MAIN];
+
+  if (process.platform === 'win32' && detached) {
+    const filePath = electronBin;
+    const argList = [DIST_MAIN];
+    const psArgList = argList.map((item) => `'${quotePsSingle(item)}'`).join(',');
+    const psScript = `$p = Start-Process -FilePath '${quotePsSingle(filePath)}' -ArgumentList @(${psArgList}) -WorkingDirectory '${quotePsSingle(APP_ROOT)}' -PassThru; Write-Output $p.Id`;
+    const pid = await new Promise((resolve, reject) => {
+      const child = spawn('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', psScript], {
+        cwd: APP_ROOT,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      let stdout = '';
+      let stderr = '';
+      child.stdout.on('data', (chunk) => { stdout += String(chunk || ''); });
+      child.stderr.on('data', (chunk) => { stderr += String(chunk || ''); });
+      child.on('error', reject);
+      child.on('close', (code) => {
+        if (code === 0) {
+          const pid = String(stdout || '').trim().split(/\s+/).pop();
+          resolve(pid || 'unknown');
+        } else {
+          reject(new Error(`Start-Process failed (${code}): ${stderr.trim() || stdout.trim() || 'unknown error'}`));
+        }
+      });
+    });
+    const healthy = await waitForCoreServicesHealthy();
+    if (!healthy) {
+      terminateProcessTree(pid);
+      throw new Error('desktop console started but core services did not become healthy');
+    }
+    console.log(`[ui-console] Started (PID: ${pid || 'unknown'})`);
+    return;
+  }
 
   const child = spawn(spawnCmd, spawnArgs, {
     cwd: APP_ROOT,
     env,
     stdio,
-    detached
+    detached,
+    windowsHide: true,
   });
 
   if (noDaemon) {
@@ -156,6 +232,11 @@ async function startConsole(noDaemon = false) {
       process.exit(code);
     });
   } else {
+    const healthy = await waitForCoreServicesHealthy();
+    if (!healthy) {
+      terminateProcessTree(child.pid);
+      throw new Error('desktop console started but core services did not become healthy');
+    }
     child.unref();
     console.log(`[ui-console] Started (PID: ${child.pid})`);
   }