@beeos-ai/cli 1.0.18 → 1.0.20

package/dist/index.js

@@ -746,26 +746,40 @@ var init_keypair = __esm({
 });
 
 // ../core/dist/platform/client.js
+async function bindHttpError(resp, op) {
+  const body = await resp.text().catch(() => "");
+  const code = resp.status === 401 || resp.status === 403 ? "platform_unauthorized" : resp.status === 429 ? "platform_rate_limited" : resp.status >= 500 ? "platform_unavailable" : "platform_bind_failed";
+  const hint = code === "platform_unauthorized" ? "Re-run `beeos init` and complete the OAuth flow again." : code === "platform_rate_limited" ? "Wait a minute and try again." : code === "platform_unavailable" ? "The platform is having trouble. Retry in a moment; if it persists, check status.beeos.ai." : "Re-run the command. If it still fails, contact support with the http_status.";
+  return new BeeosError({
+    code,
+    message: `Platform ${op} request failed: HTTP ${resp.status}${body ? ` \u2014 ${body.slice(0, 200)}` : ""}`,
+    hint,
+    details: { http_status: resp.status, op, body: body.slice(0, 1e3) }
+  });
+}
 function buildBindUrl(dashboardBaseUrl, bindId) {
   const base = dashboardBaseUrl.replace(/\/+$/, "");
   return `${base}/bind/${bindId}`;
 }
-async function agentBind(apiUrl, publicKey, fingerprint2, agentFramework, hostname) {
+async function agentBind(apiUrl, publicKey, fingerprint2, agentFramework, hostname, osType) {
   const p = getPlatformAdapter();
   const url = `${apiUrl}/api/v1/agent/bind`;
+  const body = {
+    public_key: publicKey,
+    fingerprint: fingerprint2,
+    agent_framework: agentFramework,
+    hostname
+  };
+  if (osType && osType.length > 0) {
+    body.os_type = osType;
+  }
   const resp = await p.fetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      public_key: publicKey,
-      fingerprint: fingerprint2,
-      agent_framework: agentFramework,
-      hostname
-    })
+    body: JSON.stringify(body)
   });
   if (!resp.ok) {
-    const text = await resp.text().catch(() => "");
-    throw new Error(`agent bind failed (${resp.status}): ${text}`);
+    throw await bindHttpError(resp, "bind");
   }
   return await resp.json();
 }
@@ -776,7 +790,7 @@ async function pollBind(apiUrl, bindId) {
     signal: AbortSignal.timeout(35e3)
   });
   if (!resp.ok) {
-    throw new Error(`bind poll failed: ${resp.status}`);
+    throw await bindHttpError(resp, "poll");
   }
   return await resp.json();
 }
@@ -811,7 +825,7 @@ async function getBindStatus(apiUrl, bindId) {
     signal: AbortSignal.timeout(5e3)
   });
   if (!resp.ok) {
-    throw new Error(`bind status check failed: ${resp.status}`);
+    throw await bindHttpError(resp, "status");
   }
   return await resp.json();
 }
@@ -820,6 +834,7 @@ var init_client = __esm({
     "use strict";
     init_platform_adapter();
     init_keypair();
+    init_errors();
   }
 });
 
@@ -914,7 +929,7 @@ async function bindAgent(opts) {
   const pollTimeoutMs = opts.pollTimeoutMs ?? 6e5;
   let resp;
   try {
-    resp = await agentBind(opts.apiUrl, opts.publicKey, opts.fingerprint, opts.agentFramework, opts.hostname);
+    resp = await agentBind(opts.apiUrl, opts.publicKey, opts.fingerprint, opts.agentFramework, opts.hostname, opts.osType);
   } catch (e) {
     if (isNetworkError(e) && opts.cachedBinding && opts.cachedBinding.fingerprint === opts.fingerprint) {
       return {
@@ -925,9 +940,20 @@ async function bindAgent(opts) {
     throw e;
   }
   if (resp.status === "bound") {
+    if (!resp.instance_id) {
+      throw new BeeosError({
+        code: "platform_protocol_violation",
+        message: "Platform returned status='bound' but no instance_id.",
+        hint: "This indicates a platform bug. Re-run `beeos init`; if it persists, open a support ticket with the fingerprint below.",
+        details: {
+          fingerprint: opts.fingerprint,
+          response: resp
+        }
+      });
+    }
     return {
       status: "bound",
-      instanceId: resp.instance_id ?? "",
+      instanceId: resp.instance_id,
       source: "already_bound"
     };
   }
@@ -939,8 +965,10 @@ async function bindAgent(opts) {
       return { status: "bound", instanceId, source: "fresh" };
     }
     await presentBindUrl(bindUrl, opts.headless ?? false, log);
+    const expiryMinutes = Math.round(pollTimeoutMs / 6e4);
+    log(`  Press Ctrl+C to cancel; the bind session expires in ${expiryMinutes} minutes if not approved.`);
     try {
-      const instanceId = await pollUntilBound(opts.apiUrl, bindId, pollTimeoutMs);
+      const instanceId = await pollUntilBound(opts.apiUrl, bindId, pollTimeoutMs, log);
       return { status: "bound", instanceId, source: "fresh" };
     } catch (e) {
       if (e instanceof BeeosError && e.code === "bind_pending_expired") {
@@ -980,8 +1008,10 @@ async function presentBindUrl(bindUrl, forceHeadless, log = console.log) {
     log("  -----------------------------------------------------");
   }
 }
-async function pollUntilBound(apiUrl, bindId, timeoutMs) {
+async function pollUntilBound(apiUrl, bindId, timeoutMs, log = () => void 0) {
   const deadline = Date.now() + timeoutMs;
+  let lastTick = Date.now();
+  const TICK_INTERVAL_MS = 3e4;
   while (true) {
     if (Date.now() > deadline) {
       throw new BeeosError({
@@ -991,10 +1021,23 @@ async function pollUntilBound(apiUrl, bindId, timeoutMs) {
         details: { source: "client_timeout", bindId }
       });
     }
+    if (Date.now() - lastTick >= TICK_INTERVAL_MS) {
+      const remainingSec = Math.max(0, Math.round((deadline - Date.now()) / 1e3));
+      log(`  Still waiting for confirmation... (${remainingSec}s remaining)`);
+      lastTick = Date.now();
+    }
     try {
       const resp = await pollBind(apiUrl, bindId);
       if (resp.status === "bound") {
-        return resp.instance_id ?? "";
+        if (!resp.instance_id) {
+          throw new BeeosError({
+            code: "platform_protocol_violation",
+            message: "Platform poll returned status='bound' but no instance_id.",
+            hint: "This indicates a platform bug. Re-run `beeos init`; if it persists, open a support ticket with the bind_id below.",
+            details: { bindId, response: resp }
+          });
+        }
+        return resp.instance_id;
       }
       if (resp.status === "expired") {
         throw new BeeosError({
@@ -1005,7 +1048,7 @@ async function pollUntilBound(apiUrl, bindId, timeoutMs) {
         });
       }
     } catch (e) {
-      if (e instanceof BeeosError && e.code === "bind_pending_expired") {
+      if (e instanceof BeeosError && (e.code === "bind_pending_expired" || e.code === "platform_protocol_violation" || e.code === "platform_unauthorized")) {
         throw e;
       }
       await sleep(2e3);
@@ -3205,6 +3248,74 @@ var init_agent_status = __esm({
   }
 });
 
+// ../core/dist/openclaw/desktop-detect.js
+function printMacosDesktopHint() {
+  for (const line of MACOS_DESKTOP_HINT_LINES)
+    console.log(line);
+}
+function readEnv(name) {
+  return globalThis.process?.env?.[name];
+}
+async function probeLocalVnc(opts = {}) {
+  if (readEnv("BEEOS_NO_DESKTOP") === "1")
+    return null;
+  const p = getPlatformAdapter();
+  const platform = p.platform();
+  if (platform !== "darwin" && platform !== "linux") {
+    return null;
+  }
+  const host = "127.0.0.1";
+  const timeoutMs = 200;
+  if (platform === "darwin") {
+    const ok2 = await p.tcpProbe(host, 5900, timeoutMs).catch(() => false);
+    if (ok2) {
+      return { kind: "macos", host, port: 5900, osType: "macos-desktop" };
+    }
+    return null;
+  }
+  const ok = await p.tcpProbe(host, 5901, timeoutMs).catch(() => false);
+  if (ok) {
+    return { kind: "linux", host, port: 5901, osType: "linux-desktop" };
+  }
+  if (opts.ttyHints) {
+    for (const line of LINUX_VNC_HINT_LINES)
+      console.log(line);
+  }
+  return null;
+}
+var MACOS_DESKTOP_HINT_LINES, MACOS_DESKTOP_DOCTOR_HINT_LINES, LINUX_VNC_HINT_LINES;
+var init_desktop_detect = __esm({
+  "../core/dist/openclaw/desktop-detect.js"() {
+    "use strict";
+    init_platform_adapter();
+    MACOS_DESKTOP_HINT_LINES = [
+      "Detected macOS Screen Sharing on :5900. Starting vnc-bridge...",
+      "  If desktop view shows a black screen / connection error on the dashboard:",
+      "    \u2022 System Settings \u2192 General \u2192 Sharing \u2192 Screen Sharing must be enabled",
+      "    \u2022 System Settings \u2192 Privacy & Security \u2192 Screen Recording must grant",
+      "      permission to the macOS Screen Sharing process",
+      "    \u2022 If a VNC password was set, export BEEOS_VNC_PASSWORD=<password>",
+      "      before re-running `beeos init`."
+    ];
+    MACOS_DESKTOP_DOCTOR_HINT_LINES = [
+      "vnc-bridge-openclaw is failing on macOS. Likely causes:",
+      "  \u2022 System Settings \u2192 General \u2192 Sharing \u2192 Screen Sharing turned off",
+      "  \u2022 System Settings \u2192 Privacy & Security \u2192 Screen Recording missing",
+      "    permission for the macOS Screen Sharing process",
+      "  \u2022 A VNC password is set; export BEEOS_VNC_PASSWORD=<password>",
+      "    before `beeos start openclaw --force` to retry."
+    ];
+    LINUX_VNC_HINT_LINES = [
+      "Tip: no VNC server detected on :5901. To enable BeeOS desktop streaming:",
+      "  Debian/Ubuntu:  sudo apt install tigervnc-standalone-server",
+      "  RHEL/Fedora:    sudo dnf install tigervnc-server",
+      "  Arch:           sudo pacman -S tigervnc",
+      "Then run `vncserver :1` and re-run `beeos start openclaw`.",
+      "Set BEEOS_NO_DESKTOP=1 to suppress this hint."
+    ];
+  }
+});
+
 // ../core/dist/detect.js
 async function detectExistingInstall() {
   const p = getPlatformAdapter();
@@ -3381,7 +3492,7 @@ function initDecisionLabel(decision) {
     case "rebind":
       return "Re-bind (keep key, refresh binding \u2014 same instance)";
     case "reset-all":
-      return "Reset everything (NEW key, NEW instance \u2014 for compromised key)";
+      return "Reset everything (NEW key, NEW instance \u2014 old instance becomes orphaned on dashboard, delete it manually if needed; use this only when the key is compromised)";
     case "skip":
       return "Skip (do nothing)";
   }
@@ -3447,12 +3558,20 @@ function buildVncBridgeTargetSpec(binary, opts) {
     label: `vnc-bridge (${opts.serial})`
   };
 }
+function buildOpenclawDesktopVncBridgeSpec(binary, opts) {
+  return buildVncBridgeTargetSpec(binary, {
+    ...opts,
+    serial: OPENCLAW_VNC_BRIDGE_SERIAL
+  });
+}
+var OPENCLAW_VNC_BRIDGE_SERIAL;
 var init_target_spec = __esm({
   "../core/dist/services/target-spec.js"() {
     "use strict";
     init_scrcpy_bridge();
     init_vnc_bridge();
     init_spawn_env2();
+    OPENCLAW_VNC_BRIDGE_SERIAL = "openclaw";
   }
 });
 
@@ -4953,7 +5072,7 @@ function getCliVersion(moduleUrl, distTag) {
   return { version, distTag: safeTag, display };
 }
 function resolveActiveDistTag() {
-  const envTag = readEnv("BEEOS_CLI_TAG");
+  const envTag = readEnv2("BEEOS_CLI_TAG");
   if (envTag && envTag.trim())
     return envTag.trim();
   const baked = readBakedDistTag();
@@ -4961,7 +5080,7 @@ function resolveActiveDistTag() {
     return baked.trim();
   return "latest";
 }
-function readEnv(key) {
+function readEnv2(key) {
   const env = globalThis.process?.env;
   return env?.[key];
 }
@@ -5051,6 +5170,7 @@ var init_dist = __esm({
     init_driver2();
     init_constants();
     init_agent_status();
+    init_desktop_detect();
     init_detect();
     init_registry();
     init_target_spec();
@@ -6744,8 +6864,10 @@ async function run(agentFramework, options) {
   };
   const launchOutcome = await driver.launch(ctx, reporter);
   const spec = launchOutcome.spec;
-  const launchWarnings = launchOutcome.warnings;
+  const launchWarnings = [...launchOutcome.warnings];
   reporter.stop();
+  const ttyHints = !options.json && process.stdin.isTTY === true;
+  const vncEndpoint = agentFramework === OPENCLAW_ID ? await probeLocalVnc({ ttyHints }) : null;
   const hostname = buildHostname();
   const cachedBinding = await loadBindingInfo();
   const outcome = await bindAgent({
@@ -6755,6 +6877,7 @@ async function run(agentFramework, options) {
     fingerprint: fp,
     agentFramework,
     hostname,
+    osType: vncEndpoint?.osType,
     headless: options.browser === false,
     cachedBinding: cachedBinding ? {
       fingerprint: cachedBinding.fingerprint,
@@ -6813,11 +6936,28 @@ async function run(agentFramework, options) {
   const isRebind = !isOffline && cachedBinding !== null && cachedBinding.instance_id !== boundInstanceId;
   const mgr = await getServiceManager();
   maybePrintFallbackBanner(mgr.kind);
-  let status2 = await mgr.install(spec);
+  let status2;
+  try {
+    status2 = await mgr.install(spec);
+  } catch (err) {
+    throw wrapServiceInstallFailure(err, {
+      stage: "install",
+      instanceId: boundInstanceId,
+      driverId: driver.id
+    });
+  }
   if (isRebind) {
-    await mgr.restart(spec.id);
-    const refreshed = await mgr.status(spec.id);
-    if (refreshed) status2 = refreshed;
+    try {
+      await mgr.restart(spec.id);
+      const refreshed = await mgr.status(spec.id);
+      if (refreshed) status2 = refreshed;
+    } catch (err) {
+      throw wrapServiceInstallFailure(err, {
+        stage: "restart",
+        instanceId: boundInstanceId,
+        driverId: driver.id
+      });
+    }
   }
   if (spec.healthcheck) {
     try {
@@ -6829,15 +6969,32 @@ async function run(agentFramework, options) {
           throw new BeeosError({
             code: "service_install_failed",
             message: diag.reason,
-            hint: diag.hints.length > 0 ? diag.hints.map((h) => `\u2022 ${h}`).join("\n  ") : void 0,
+            hint: `Binding to instance ${boundInstanceId} is intact on disk. Re-run \`beeos start ${agentFramework} --force\` to retry from this step. ` + (diag.hints.length > 0 ? "Diagnostics: " + diag.hints.map((h) => `\u2022 ${h}`).join("; ") : ""),
             cause: err,
-            details: { driver: driver.id }
+            details: { driver: driver.id, instance_id: boundInstanceId }
           });
         }
       }
-      throw err;
+      throw wrapServiceInstallFailure(err, {
+        stage: "healthcheck",
+        instanceId: boundInstanceId,
+        driverId: driver.id
+      });
     }
   }
+  if (vncEndpoint && !isOffline) {
+    if (vncEndpoint.kind === "macos" && ttyHints) {
+      printMacosDesktopHint();
+    }
+    const desktopWarning = await tryAttachOpenclawDesktopBridge({
+      vncEndpoint,
+      instanceId: boundInstanceId,
+      keyFile,
+      agentGatewayUrl,
+      mgr
+    });
+    if (desktopWarning) launchWarnings.push(desktopWarning);
+  }
   const gatewayPid = status2.pid ?? void 0;
   emit(options.json, {
     status: isOffline ? "bound_offline" : "bound",
@@ -6850,11 +7007,52 @@ async function run(agentFramework, options) {
   }, isOffline ? `Agent running (offline, cached instance: ${boundInstanceId})` : `Agent bound to instance: ${boundInstanceId}`);
   if (!options.json) printLaunchWarnings(launchWarnings);
 }
+async function tryAttachOpenclawDesktopBridge(params) {
+  const reporter = new CliReporter();
+  let binary = null;
+  try {
+    binary = await vncBridgeRuntime.ensureInstalled(reporter);
+  } catch (e) {
+    reporter.stop();
+    const reason = e instanceof Error ? e.message : String(e);
+    return `vnc-bridge install failed: ${reason}; OpenClaw is bound but desktop streaming is unavailable.`;
+  }
+  reporter.stop();
+  if (!binary) {
+    return `vnc-bridge binary unavailable (download or PATH lookup failed); OpenClaw is bound but desktop streaming is unavailable. Set BEEOS_VNC_BRIDGE_BIN to override.`;
+  }
+  const spec = buildOpenclawDesktopVncBridgeSpec(binary, {
+    deviceId: params.instanceId,
+    vncHost: params.vncEndpoint.host,
+    vncPort: params.vncEndpoint.port,
+    agentGatewayUrl: params.agentGatewayUrl,
+    bridgePrivateKeyFile: params.keyFile,
+    bridgePublicKeyFile: params.keyFile
+  });
+  try {
+    await params.mgr.install(spec);
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    return `vnc-bridge service install failed: ${reason}; OpenClaw is bound but desktop streaming is unavailable. Re-run \`beeos start openclaw --force\` to retry.`;
+  }
+  return null;
+}
 function buildHostname() {
   const machine = os6.hostname();
   const user = process.env.USER || process.env.USERNAME || "";
   return user ? `${user}@${machine}` : machine;
 }
+function wrapServiceInstallFailure(err, ctx) {
+  if (err instanceof BeeosError) return err;
+  const msg = err instanceof Error ? err.message : String(err);
+  return new BeeosError({
+    code: "service_install_failed",
+    message: `Bind succeeded (instance ${ctx.instanceId}) but service ${ctx.stage} failed: ${msg}`,
+    hint: `Local binding.json is intact. Re-run \`beeos start ${ctx.driverId} --force\` to retry from the service-${ctx.stage} step \u2014 you do NOT need to bind again.`,
+    cause: err,
+    details: { stage: ctx.stage, instance_id: ctx.instanceId, driver: ctx.driverId }
+  });
+}
 function emit(json, payload, human) {
   if (json) {
     emitJsonEnvelope(jsonOk(payload));
@@ -7063,644 +7261,656 @@ init_device2();
 // src/commands/init.ts
 init_dist();
 import readline3 from "readline";
-
-// src/commands/doctor.ts
-init_dist();
-init_json_envelope();
-import fs9 from "fs/promises";
-import path9 from "path";
-var LOG_SIZE_WARN_BYTES = 50 * 1024 * 1024;
+init_attach();
+init_progress2();
+init_fallback_banner();
+init_instance_picker();
 async function run7(options) {
-  const state = await detectExistingInstall();
-  const cfg = await loadOrCreateConfig();
-  const p = getPlatformAdapter();
-  const mgr = await getServiceManager();
-  const fallbackReason2 = activeFallbackReason();
-  const serviceCheck = await mgr.selfCheck();
-  let services = [];
-  try {
-    services = await mgr.list();
-  } catch {
-  }
-  const resolvedAgentGatewayUrl = resolveAgentGatewayUrl(cfg);
-  const agentGatewayHealth = await probeAgentGateway(resolvedAgentGatewayUrl);
-  const tools = await collectToolStatus();
-  const hasBoundDevices = state.devices.entries.length > 0;
-  const shimReport = await collectShimReport(hasBoundDevices);
-  const warnings = [];
-  const hints = [];
-  if (!state.hasIdentity) {
-    warnings.push("identity keypair missing \u2014 will be generated on next bind");
-  }
-  if (state.openclaw.gatewayRunning && !state.openclaw.found) {
-    warnings.push("port 18789 is in use but no OpenClaw install detected \u2014 another app may conflict");
+  await ensureDirs();
+  if (options.device) {
+    const { attach: attach2 } = await Promise.resolve().then(() => (init_device2(), device_exports));
+    await attach2({});
+    return;
   }
-  if (state.openclaw.found && state.openclaw.pluginInstalled === false) {
-    warnings.push(
-      `OpenClaw is installed at ${state.openclaw.home ?? "?"} but the beeos-claw plugin is not registered. BeeOS-specific tools may be unavailable to agents until this is fixed.`
-    );
-    hints.push(
-      "re-run `beeos start openclaw --force` to re-install the plugin, or check ~/.beeos/logs/services/openclaw.log for the original failure"
-    );
+  const state = await detectExistingInstall();
+  if (!options.json) {
+    printBanner();
+    for (const line of summarizeExistingInstall(state)) {
+      console.log(`  ${line}`);
+    }
+    if (state.supervisor.targets.length > 0 || state.supervisor.ipcReachable) {
+      console.log("");
+      console.log(
+        "  Legacy Node supervisor state detected. Run `beeos migrate` to convert it to OS-native services."
+      );
+    }
+    console.log("");
   }
-  if (state.devices.entries.length > 0 && services.length === 0) {
-    warnings.push(
-      "devices tracked via legacy devices.json \u2014 no OS services registered. Re-run `beeos device attach` to migrate them to the OS service manager."
-    );
+  const decision = await decideAction(state, options);
+  if (decision === "skip") {
+    console.log("Nothing to do. Run `beeos init` again or `beeos device attach` when ready.");
+    return;
   }
-  if (state.supervisor.targets.length > 0 || state.supervisor.ipcReachable) {
-    warnings.push(
-      "legacy Node supervisor state detected \u2014 run `beeos migrate` to convert it to OS-native services."
-    );
+  if (decision === "upgrade") {
+    if (await shouldUpgradeBeeosSuite(options)) {
+      const exited = await upgradeAndMaybeExit(options);
+      if (exited) return;
+    }
+    console.log("Ensuring OpenClaw is running...\n");
   }
-  if (agentGatewayHealth.status !== "ok") {
-    warnings.push(
-      `Agent Gateway unreachable at ${resolvedAgentGatewayUrl}: ${agentGatewayHealth.detail}. Binding and task delivery will fail until this resolves.`
-    );
-    hints.push(
-      "check BEEOS_AGENT_GATEWAY_URL / platform.agent_gateway_url in ~/.beeos/config.toml"
-    );
+  if (decision === "rebind") {
+    await removeBindingInfo();
   }
-  if (fallbackReason2) {
-    warnings.push(
-      `No native OS service manager available (${fallbackReason2}) \u2014 using fallback, services WON'T persist across reboots.`
-    );
+  if (decision === "reset-all") {
+    await rotateIdentity();
+    await removeBindingInfo();
   }
-  for (const w of serviceCheck.warnings) warnings.push(w);
-  for (const h of serviceCheck.hints) hints.push(h);
-  for (const s of services) {
-    if (!s.running && s.installed) {
-      warnings.push(
-        `service '${s.id}' is installed but not running \u2014 see log ${s.logFile}`
-      );
+  if (decision === "fresh" && !options.framework && !options.yes && !options.json && process.stdin.isTTY) {
+    const sel = await pickFreshInstance(options);
+    if (sel.kind === "skip") {
+      console.log("Skipped. Re-run `beeos init` or `beeos device attach` whenever ready.");
+      return;
     }
-    if (s.lastExitCode !== null && s.lastExitCode !== 0) {
-      warnings.push(
-        `service '${s.id}' last exited with code ${s.lastExitCode} \u2014 see log ${s.logFile}`
-      );
+    if (sel.kind === "device") {
+      await attach({ serial: sel.serial });
+      return;
+    }
+    const descriptor2 = frameworkById(sel.id);
+    if (!descriptor2 || descriptor2.status !== "available") {
+      throw new BeeosError({
+        code: "framework_unavailable",
+        message: `Agent framework '${sel.id}' is not available.`,
+        hint: "Pick a different framework or reinstall the CLI.",
+        details: { requested: sel.id, available: availableFrameworks().map((f) => f.id) }
+      });
+    }
+    await run(descriptor2.id, {
+      force: true,
+      json: options.json,
+      browser: options.browser !== false
+    });
+    if (!options.json && !options.skipServicePrompt) {
+      await maybePromptServiceInstall();
+    }
+    if (!options.json) {
+      printNextSteps();
     }
+    return;
   }
-  if (!tools.adb.path) {
-    warnings.push(
-      "adb not found \u2014 `beeos device attach` will download Android platform-tools on first use"
-    );
+  const frameworkId = await decideFramework(state, decision, options);
+  const descriptor = frameworkById(frameworkId);
+  if (!descriptor || descriptor.status !== "available") {
+    const avail = availableFrameworks().map((f) => f.id).join(", ");
+    throw new BeeosError({
+      code: "framework_unavailable",
+      message: `Agent framework '${frameworkId}' is not available. Available: ${avail}.`,
+      hint: avail.length > 0 ? `Re-run with --framework <one-of-the-above>` : "No frameworks are registered \u2014 reinstall the CLI.",
+      details: { requested: frameworkId, available: availableFrameworks().map((f) => f.id) }
+    });
   }
-  for (const e of shimReport.entries) {
-    if (e.outcome === "outdated") {
-      warnings.push(
-        `${e.pkg}: installed ${e.installed ?? "(missing)"}, npm latest ${e.latest}.`
-      );
-    } else if (e.outcome === "missing") {
-      warnings.push(`${e.pkg}: not installed globally \u2014 run 'beeos init' to install.`);
-    } else if (e.outcome === "error" || e.outcome === "not_installed_yet") {
-    }
+  await run(descriptor.id, {
+    force: true,
+    json: options.json,
+    browser: options.browser !== false
+  });
+  if (!options.json && !options.skipServicePrompt) {
+    await maybePromptServiceInstall();
   }
-  if (shimReport.entries.some((e) => e.outcome === "outdated" || e.outcome === "missing")) {
-    hints.push(
-      "run `beeos init` and pick option [1] to upgrade CLI + agents to the latest npm release"
-    );
+  if (!options.json) {
+    printNextSteps();
   }
-  const bloatedLogs = await checkLogFileSizes();
-  for (const l of bloatedLogs) {
-    warnings.push(
-      `Service log large: ${path9.basename(l.path)} = ${formatBytes(l.size)}`
-    );
-    hints.push(`truncate safely: : > ${l.path}`);
+}
+async function decideAction(state, options) {
+  const choice = inferInitChoices(state);
+  if (choice.options.length === 1) {
+    return choice.defaultDecision;
   }
-  if (options.json) {
-    emitJsonEnvelope(
-      jsonOk({
-        platform: p.platform(),
-        arch: process.arch,
-        node: process.version,
-        beeosHome: state.beeosHome,
-        config: cfg,
-        state,
-        serviceManager: {
-          kind: mgr.kind,
-          available: serviceCheck.available,
-          fallbackReason: fallbackReason2,
-          services
-        },
-        agentGateway: agentGatewayHealth,
-        tools,
-        npmShims: shimReport,
-        warnings,
-        hints
-      })
-    );
-    return;
+  if (options.yes || options.json) {
+    return choice.defaultDecision;
   }
+  if (!process.stdin.isTTY) {
+    return choice.defaultDecision;
+  }
+  console.log("Detected existing install. Choose an action:");
+  choice.options.forEach((d, i) => {
+    const marker = d === choice.defaultDecision ? "*" : " ";
+    console.log(`  ${marker} [${i + 1}] ${initDecisionLabel(d)}`);
+  });
   console.log("");
-  console.log(`  OS/Arch  : ${p.platform()}/${process.arch}`);
-  console.log(`  Node.js  : ${process.version}`);
-  console.log(`  API URL  : ${cfg.platform.api_url}`);
-  console.log(
-    `  AgentGw  : ${resolvedAgentGatewayUrl} [${formatAgentGatewayStatus(agentGatewayHealth)}]`
-  );
-  console.log("");
-  for (const line of summarizeExistingInstall(state)) {
-    console.log(`  ${line}`);
+  const answer = await prompt(`Choose [1-${choice.options.length}] (default ${choice.options.indexOf(choice.defaultDecision) + 1}): `);
+  const trimmed = answer.trim();
+  if (!trimmed) return choice.defaultDecision;
+  const idx = parseInt(trimmed, 10);
+  if (!Number.isFinite(idx) || idx < 1 || idx > choice.options.length) {
+    return choice.defaultDecision;
   }
-  console.log(
-    `  Service manager: ${mgr.kind}${fallbackReason2 ? " (fallback)" : ""} \u2014 ${services.length} service(s) registered`
-  );
-  for (const s of services) {
-    const status2 = s.running ? "running" : s.installed ? "stopped" : "uninstalled";
-    const pid = s.pid != null ? ` pid=${s.pid}` : "";
-    console.log(`    - ${s.id.padEnd(28)} ${status2}${pid}`);
+  return choice.options[idx - 1];
+}
+async function decideFramework(state, decision, options) {
+  if (options.framework && options.framework.trim()) {
+    return options.framework.trim();
   }
-  console.log(`  adb          : ${tools.adb.path ?? "not found"}`);
-  console.log(`  scrcpy-bridge: ${tools.scrcpyBridge.path ?? "not installed (auto on attach)"}`);
-  console.log(`  vnc-bridge   : ${tools.vncBridge.path ?? "not installed (auto on --vnc-host)"}`);
-  console.log("");
-  console.log("  npm shims:");
-  for (const e of shimReport.entries) {
-    const marker = shimMarker(e.outcome);
-    const installed = e.installed ?? "(missing)";
-    const latest = e.latest ?? "(unknown)";
-    console.log(
-      `    ${marker} ${e.pkg.padEnd(34)} installed=${installed.padEnd(8)} npm=${latest}`
-    );
+  if (state.binding && decision === "upgrade") {
+    const persisted = state.binding.framework?.trim();
+    if (persisted) return persisted;
+    return defaultFrameworkId();
   }
-  console.log("");
-  if (warnings.length > 0) {
-    console.log("  Warnings:");
-    for (const w of warnings) {
-      console.log(`    - ${w}`);
-    }
-    console.log("");
-  } else {
-    console.log("  No warnings \u2014 machine looks good.\n");
+  if (options.yes || options.json || !process.stdin.isTTY) {
+    return defaultFrameworkId();
   }
-  if (hints.length > 0) {
-    console.log("  Hints:");
-    for (const h of hints) {
-      console.log(`    $ ${h}`);
+  const all = listFrameworks();
+  const avail = availableFrameworks();
+  if (avail.length <= 1) {
+    const only = avail[0];
+    if (only) {
+      console.log(`Installing ${only.displayName} (only available framework).`);
+      return only.id;
     }
-    console.log("");
+    return defaultFrameworkId();
+  }
+  console.log("");
+  console.log("Choose agent framework:");
+  const def = defaultFrameworkId();
+  all.forEach((f, i) => {
+    const marker = f.id === def ? "*" : " ";
+    const tag = f.status === "coming-soon" ? "  [coming soon]" : "";
+    const padName = f.displayName.padEnd(12);
+    console.log(`  ${marker} [${i + 1}] ${padName} ${f.description}${tag}`);
+  });
+  console.log("");
+  const defaultIdx = all.findIndex((f) => f.id === def) + 1;
+  const answer = await prompt(`Choose [1-${all.length}] (default ${defaultIdx}): `);
+  const trimmed = answer.trim();
+  if (!trimmed) return def;
+  const idx = parseInt(trimmed, 10);
+  if (!Number.isFinite(idx) || idx < 1 || idx > all.length) {
+    return def;
+  }
+  const picked = all[idx - 1];
+  if (picked.status !== "available") {
+    console.log(
+      `  ${picked.displayName} is not yet available. Falling back to ${def}.`
+    );
+    return def;
   }
+  return picked.id;
 }
-async function collectToolStatus() {
-  const [adbPath, scrcpyPath, vncPath] = await Promise.all([
-    findAdb().catch(() => null),
-    scrcpyBridgeRuntime.findBinary().catch(() => null),
-    vncBridgeRuntime.findBinary().catch(() => null)
-  ]);
-  return {
-    adb: { path: adbPath },
-    scrcpyBridge: { path: scrcpyPath },
-    vncBridge: { path: vncPath }
-  };
+async function safeListAdbDevices() {
+  const adbPath = await findAdb().catch(() => null);
+  if (!adbPath) return [];
+  try {
+    return await deviceRuntime.listAdbDevices();
+  } catch {
+    return [];
+  }
 }
-async function collectShimReport(hasBoundDevices) {
-  const sources = readPinSourcesFromEnv();
-  const deviceSuite = /* @__PURE__ */ new Set([
-    NPM_PKGS.DEVICE_AGENT,
-    NPM_PKGS.DEVICE_MCP_SERVER
-  ]);
-  const entries = await Promise.all(
-    ALL_BEEOS_PKGS.map(async (pkg) => {
-      const spec = resolveInstallSpec(pkg, sources);
-      const [installed, latest] = await Promise.all([
-        npmGlobalVersion(pkg).catch(() => null),
-        npmRegistryVersion(spec).catch(() => null)
-      ]);
-      let outcome;
-      if (latest === null) outcome = "error";
-      else if (installed === null) {
-        outcome = deviceSuite.has(pkg) && !hasBoundDevices ? "not_installed_yet" : "missing";
-      } else if (installed === latest) outcome = "ok";
-      else outcome = "outdated";
-      if (pkg === NPM_PKGS.CLI && installed === null) {
-        outcome = "missing";
-      }
-      return { pkg, installed, latest, spec, outcome };
-    })
-  );
-  return { entries };
+async function pickFreshInstance(_opts) {
+  const frameworks = availableFrameworks().map((f) => ({
+    kind: "framework",
+    id: f.id,
+    label: f.displayName,
+    description: f.description,
+    isDefault: f.id === defaultFrameworkId()
+  }));
+  const devices = (await safeListAdbDevices()).map((d) => ({
+    kind: "device",
+    serial: d.serial,
+    status: d.status
+  }));
+  return pickInstanceInteractive([...frameworks, ...devices], {
+    caller: "init"
+  });
 }
-function shimMarker(outcome) {
-  switch (outcome) {
-    case "ok":
-      return "\u2713";
-    case "outdated":
-      return "\u2191";
-    case "missing":
-      return "\u2717";
-    case "not_installed_yet":
-      return "\xB7";
-    case "error":
-      return "?";
+async function maybePromptServiceInstall() {
+  try {
+    const mgr = await getServiceManager();
+    maybePrintFallbackBanner(mgr.kind);
+    const check = await mgr.selfCheck();
+    if (!check.available) {
+      console.log(`  \u26A0 Service manager '${mgr.kind}' is not fully available \u2014 persistence limited.`);
+    }
+    for (const w of check.warnings) console.log(`  ! ${w}`);
+    for (const h of check.hints) console.log(`  $ ${h}`);
+  } catch (e) {
+    console.log(`  (service-manager self-check skipped: ${e instanceof Error ? e.message : String(e)})`);
   }
 }
-async function checkLogFileSizes() {
-  const dir = path9.join(beeoHome(), "logs", "services");
-  let entries;
+async function rotateIdentity() {
+  const p = getPlatformAdapter();
+  const home = beeoHome();
+  const identityDir = p.joinPath(home, "identity");
+  const keypair = p.joinPath(identityDir, "keypair.json");
+  const fp = p.joinPath(identityDir, "fingerprint");
+  if (!await p.exists(keypair)) return;
+  const ts = Math.floor(Date.now() / 1e3);
+  const backup = p.joinPath(identityDir, `keypair.json.backup-${ts}`);
   try {
-    entries = await fs9.readdir(dir);
+    await p.copyFile(keypair, backup);
   } catch {
-    return [];
   }
-  const bloated = [];
-  for (const name of entries) {
-    if (!name.endsWith(".log")) continue;
-    const full = path9.join(dir, name);
-    try {
-      const st = await fs9.stat(full);
-      if (st.isFile() && st.size >= LOG_SIZE_WARN_BYTES) {
-        bloated.push({ path: full, size: st.size });
-      }
-    } catch {
-    }
+  try {
+    await p.rm(keypair);
+  } catch {
   }
-  return bloated;
+  try {
+    await p.rm(fp);
+  } catch {
+  }
+  console.log(`Rotated identity. Previous keypair saved at ${backup}`);
 }
-function formatBytes(n) {
-  if (n >= 1024 * 1024 * 1024) return `${(n / (1024 * 1024 * 1024)).toFixed(1)}GB`;
-  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(0)}MB`;
-  if (n >= 1024) return `${(n / 1024).toFixed(0)}KB`;
-  return `${n}B`;
+function printBanner() {
+  console.log("");
+  console.log("  BeeOS init");
+  console.log("");
 }
-async function probeAgentGateway(baseUrl) {
-  const url = joinHealthzUrl(baseUrl);
-  const started = Date.now();
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), 3e3);
-  try {
-    const res = await fetch(url, {
-      method: "GET",
-      signal: ac.signal,
-      headers: { accept: "application/json, text/plain;q=0.9, */*;q=0.1" }
-    });
-    const latency = Date.now() - started;
-    if (res.ok) {
-      return {
-        url,
-        status: "ok",
-        httpStatus: res.status,
-        latencyMs: latency,
-        detail: `HTTP ${res.status} in ${latency}ms`
-      };
-    }
-    return {
-      url,
-      status: "unhealthy",
-      httpStatus: res.status,
-      latencyMs: latency,
-      detail: `HTTP ${res.status} in ${latency}ms`
-    };
-  } catch (err) {
-    const latency = Date.now() - started;
-    const msg = err instanceof Error ? err.message : String(err);
-    const timedOut = ac.signal.aborted;
-    return {
-      url,
-      status: "unreachable",
-      httpStatus: null,
-      latencyMs: latency,
-      detail: timedOut ? "timeout after 3s" : msg
-    };
-  } finally {
-    clearTimeout(timer);
-  }
+function printNextSteps() {
+  console.log("");
+  console.log("Next steps:");
+  console.log("  beeos status                  # show running agents");
+  console.log("  beeos device attach           # bind a physical Android device");
+  console.log("  beeos doctor                  # health check & diagnostics");
+  console.log("");
 }
-function joinHealthzUrl(base) {
-  const trimmed = base.replace(/\/+$/, "");
-  return `${trimmed}/healthz`;
+function prompt(question) {
+  const rl = readline3.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
 }
-function formatAgentGatewayStatus(h) {
-  if (h.status === "ok") return `ok ${h.latencyMs}ms`;
-  if (h.status === "unhealthy") return `HTTP ${h.httpStatus ?? "?"}`;
-  return h.detail;
+async function shouldUpgradeBeeosSuite(options) {
+  if (options.headless) return false;
+  if (process.env.BEEOS_INIT_SKIP_NPM_UPGRADE === "1") return false;
+  return true;
 }
-
-// src/commands/init.ts
-init_attach();
-init_progress2();
-init_fallback_banner();
-init_instance_picker();
-async function run8(options) {
-  await ensureDirs();
-  if (options.device) {
-    const { attach: attach2 } = await Promise.resolve().then(() => (init_device2(), device_exports));
-    await attach2({});
-    return;
-  }
-  const state = await detectExistingInstall();
+async function upgradeAndMaybeExit(options) {
   if (options.json) {
-    await run7({ json: true });
-  } else {
-    printBanner();
-    for (const line of summarizeExistingInstall(state)) {
-      console.log(`  ${line}`);
-    }
-    if (state.supervisor.targets.length > 0 || state.supervisor.ipcReachable) {
-      console.log("");
-      console.log(
-        "  Legacy Node supervisor state detected. Run `beeos migrate` to convert it to OS-native services."
-      );
-    }
-    console.log("");
-  }
-  const decision = await decideAction(state, options);
-  if (decision === "skip") {
-    console.log("Nothing to do. Run `beeos init` again or `beeos device attach` when ready.");
-    return;
+    return false;
   }
-  if (decision === "upgrade") {
-    if (await shouldUpgradeBeeosSuite(options)) {
-      const exited = await upgradeAndMaybeExit(options);
-      if (exited) return;
-    }
-    console.log("Ensuring OpenClaw is running...\n");
+  const packages = await pickInstalledPackages();
+  console.log("Checking for newer @beeos-ai/cli on npm...");
+  const reporter = new CliReporter();
+  let outcome;
+  try {
+    outcome = await upgradeBeeosSuite({
+      packages,
+      progress: reporter
+    });
+  } catch (e) {
+    reporter.stop();
+    console.log(
+      `  (upgrade skipped \u2014 ${e instanceof Error ? e.message : String(e)})
+  Tip: re-run \`npm install -g @beeos-ai/cli\` manually. The device
+  suite (device-agent + device-mcp-server) will be auto-installed
+  on the next \`beeos device attach\`.`
+    );
+    return false;
   }
-  if (decision === "rebind") {
-    await removeBindingInfo();
+  reporter.stop();
+  if (outcome.anyFailed) {
+    const failed = outcome.packages.find((p) => p.failed)?.failed ?? "unknown error";
+    console.log(`  \u26A0 npm install failed: ${failed}`);
+    console.log(
+      "    Manual fix:\n      npm i -g @beeos-ai/cli\n    (the device suite is auto-installed on `beeos device attach`)\n"
+    );
+    return false;
   }
-  if (decision === "reset-all") {
-    await rotateIdentity();
-    await removeBindingInfo();
+  if (!outcome.anyChanged) {
+    console.log("  All BeeOS npm packages are up to date.\n");
+    return false;
   }
-  if (decision === "fresh" && !options.framework && !options.yes && !options.json && process.stdin.isTTY) {
-    const sel = await pickFreshInstance(options);
-    if (sel.kind === "skip") {
-      console.log("Skipped. Re-run `beeos init` or `beeos device attach` whenever ready.");
-      return;
-    }
-    if (sel.kind === "device") {
-      await attach({ serial: sel.serial });
-      return;
-    }
-    const descriptor2 = frameworkById(sel.id);
-    if (!descriptor2 || descriptor2.status !== "available") {
-      throw new BeeosError({
-        code: "framework_unavailable",
-        message: `Agent framework '${sel.id}' is not available.`,
-        hint: "Pick a different framework or reinstall the CLI.",
-        details: { requested: sel.id, available: availableFrameworks().map((f) => f.id) }
-      });
-    }
-    await run(descriptor2.id, {
-      force: true,
-      json: options.json,
-      browser: options.browser !== false
-    });
-    if (!options.json && !options.skipServicePrompt) {
-      await maybePromptServiceInstall();
-    }
-    if (!options.json) {
-      printNextSteps();
+  for (const pkg of outcome.packages) {
+    if (pkg.changed) {
+      console.log(`  ${pkg.pkg}: ${pkg.before ?? "(none)"} \u2192 ${pkg.after}`);
     }
-    return;
   }
-  const frameworkId = await decideFramework(state, decision, options);
-  const descriptor = frameworkById(frameworkId);
-  if (!descriptor || descriptor.status !== "available") {
-    const avail = availableFrameworks().map((f) => f.id).join(", ");
-    throw new BeeosError({
-      code: "framework_unavailable",
-      message: `Agent framework '${frameworkId}' is not available. Available: ${avail}.`,
-      hint: avail.length > 0 ? `Re-run with --framework <one-of-the-above>` : "No frameworks are registered \u2014 reinstall the CLI.",
-      details: { requested: frameworkId, available: availableFrameworks().map((f) => f.id) }
-    });
-  }
-  await run(descriptor.id, {
-    force: true,
-    json: options.json,
-    browser: options.browser !== false
-  });
-  if (!options.json && !options.skipServicePrompt) {
-    await maybePromptServiceInstall();
+  const cliEntry = outcome.packages.find((p) => p.pkg === NPM_PKGS.CLI);
+  if (cliEntry?.changed) {
+    console.log("");
+    console.log("  CLI itself was upgraded \u2014 please re-run `beeos init` to continue");
+    console.log("  with the new code. The current process is still running the old version.");
+    console.log("");
+    return true;
   }
-  if (!options.json) {
-    printNextSteps();
+  console.log("  Agents updated. Continuing init...\n");
+  return false;
+}
+async function pickInstalledPackages() {
+  const packages = [NPM_PKGS.CLI];
+  for (const pkg of [NPM_PKGS.DEVICE_AGENT, NPM_PKGS.DEVICE_MCP_SERVER]) {
+    const installed = await npmGlobalVersion(pkg).catch(() => null);
+    if (installed !== null) packages.push(pkg);
   }
+  return packages;
 }
-async function decideAction(state, options) {
-  const choice = inferInitChoices(state);
-  if (choice.options.length === 1) {
-    return choice.defaultDecision;
+
+// src/commands/doctor.ts
+init_dist();
+init_json_envelope();
+import fs9 from "fs/promises";
+import path9 from "path";
+var LOG_SIZE_WARN_BYTES = 50 * 1024 * 1024;
+async function run8(options) {
+  const state = await detectExistingInstall();
+  const cfg = await loadOrCreateConfig();
+  const p = getPlatformAdapter();
+  const mgr = await getServiceManager();
+  const fallbackReason2 = activeFallbackReason();
+  const serviceCheck = await mgr.selfCheck();
+  let services = [];
+  try {
+    services = await mgr.list();
+  } catch {
   }
-  if (options.yes || options.json) {
-    return choice.defaultDecision;
+  const resolvedAgentGatewayUrl = resolveAgentGatewayUrl(cfg);
+  const agentGatewayHealth = await probeAgentGateway(resolvedAgentGatewayUrl);
+  const tools = await collectToolStatus();
+  const hasBoundDevices = state.devices.entries.length > 0;
+  const shimReport = await collectShimReport(hasBoundDevices);
+  const warnings = [];
+  const hints = [];
+  if (!state.hasIdentity) {
+    warnings.push("identity keypair missing \u2014 will be generated on next bind");
   }
-  if (!process.stdin.isTTY) {
-    return choice.defaultDecision;
+  if (state.openclaw.gatewayRunning && !state.openclaw.found) {
+    warnings.push("port 18789 is in use but no OpenClaw install detected \u2014 another app may conflict");
   }
-  console.log("Detected existing install. Choose an action:");
-  choice.options.forEach((d, i) => {
-    const marker = d === choice.defaultDecision ? "*" : " ";
-    console.log(`  ${marker} [${i + 1}] ${initDecisionLabel(d)}`);
-  });
-  console.log("");
-  const answer = await prompt(`Choose [1-${choice.options.length}] (default ${choice.options.indexOf(choice.defaultDecision) + 1}): `);
-  const trimmed = answer.trim();
-  if (!trimmed) return choice.defaultDecision;
-  const idx = parseInt(trimmed, 10);
-  if (!Number.isFinite(idx) || idx < 1 || idx > choice.options.length) {
-    return choice.defaultDecision;
+  if (state.openclaw.found && state.openclaw.pluginInstalled === false) {
+    warnings.push(
+      `OpenClaw is installed at ${state.openclaw.home ?? "?"} but the beeos-claw plugin is not registered. BeeOS-specific tools may be unavailable to agents until this is fixed.`
+    );
+    hints.push(
+      "re-run `beeos start openclaw --force` to re-install the plugin, or check ~/.beeos/logs/services/openclaw.log for the original failure"
+    );
   }
-  return choice.options[idx - 1];
-}
-async function decideFramework(state, decision, options) {
-  if (options.framework && options.framework.trim()) {
-    return options.framework.trim();
+  if (state.devices.entries.length > 0 && services.length === 0) {
+    warnings.push(
+      "devices tracked via legacy devices.json \u2014 no OS services registered. Re-run `beeos device attach` to migrate them to the OS service manager."
+    );
   }
-  if (state.binding && decision === "upgrade") {
-    const persisted = state.binding.framework?.trim();
-    if (persisted) return persisted;
-    return defaultFrameworkId();
+  if (state.supervisor.targets.length > 0 || state.supervisor.ipcReachable) {
+    warnings.push(
+      "legacy Node supervisor state detected \u2014 run `beeos migrate` to convert it to OS-native services."
+    );
   }
-  if (options.yes || options.json || !process.stdin.isTTY) {
-    return defaultFrameworkId();
+  if (agentGatewayHealth.status !== "ok") {
+    warnings.push(
+      `Agent Gateway unreachable at ${resolvedAgentGatewayUrl}: ${agentGatewayHealth.detail}. Binding and task delivery will fail until this resolves.`
+    );
+    hints.push(
+      "check BEEOS_AGENT_GATEWAY_URL / platform.agent_gateway_url in ~/.beeos/config.toml"
+    );
   }
-  const all = listFrameworks();
-  const avail = availableFrameworks();
-  if (avail.length <= 1) {
-    const only = avail[0];
-    if (only) {
-      console.log(`Installing ${only.displayName} (only available framework).`);
-      return only.id;
+  if (fallbackReason2) {
+    warnings.push(
+      `No native OS service manager available (${fallbackReason2}) \u2014 using fallback, services WON'T persist across reboots.`
+    );
+  }
+  for (const w of serviceCheck.warnings) warnings.push(w);
+  for (const h of serviceCheck.hints) hints.push(h);
+  for (const s of services) {
+    if (!s.running && s.installed) {
+      warnings.push(
+        `service '${s.id}' is installed but not running \u2014 see log ${s.logFile}`
+      );
+    }
+    if (s.lastExitCode !== null && s.lastExitCode !== 0) {
+      warnings.push(
+        `service '${s.id}' last exited with code ${s.lastExitCode} \u2014 see log ${s.logFile}`
+      );
+      if (s.lastExitCode === 127) {
+        hints.push(
+          `service '${s.id}' looks like its Node binary moved (exit 127). Re-run \`beeos start ${s.id} --force\` to refresh the service definition with the current node path.`
+        );
+      }
+      if (s.id === `vnc-bridge-${OPENCLAW_VNC_BRIDGE_SERIAL}`) {
+        if (process.platform === "darwin") {
+          for (const line of MACOS_DESKTOP_DOCTOR_HINT_LINES) {
+            hints.push(line);
+          }
+        } else {
+          hints.push(
+            `vnc-bridge-${OPENCLAW_VNC_BRIDGE_SERIAL} is failing \u2014 see ${s.logFile} for the underlying error. Common causes: VNC server moved port, BEEOS_VNC_PASSWORD missing/incorrect, network blocking outbound MQTT.`
+          );
+        }
+      }
+    }
+  }
+  if (!tools.adb.path) {
+    warnings.push(
+      "adb not found \u2014 `beeos device attach` will download Android platform-tools on first use"
+    );
+  }
+  for (const e of shimReport.entries) {
+    if (e.outcome === "outdated") {
+      warnings.push(
+        `${e.pkg}: installed ${e.installed ?? "(missing)"}, npm latest ${e.latest}.`
+      );
+    } else if (e.outcome === "missing") {
+      warnings.push(`${e.pkg}: not installed globally \u2014 run 'beeos init' to install.`);
+    } else if (e.outcome === "error" || e.outcome === "not_installed_yet") {
     }
-    return defaultFrameworkId();
+  }
+  if (shimReport.entries.some((e) => e.outcome === "outdated" || e.outcome === "missing")) {
+    hints.push(
+      "run `beeos init` and pick option [1] to upgrade CLI + agents to the latest npm release"
+    );
+  }
+  const bloatedLogs = await checkLogFileSizes();
+  for (const l of bloatedLogs) {
+    warnings.push(
+      `Service log large: ${path9.basename(l.path)} = ${formatBytes(l.size)}`
+    );
+    hints.push(`truncate safely: : > ${l.path}`);
+  }
+  if (options.json) {
+    emitJsonEnvelope(
+      jsonOk({
+        platform: p.platform(),
+        arch: process.arch,
+        node: process.version,
+        beeosHome: state.beeosHome,
+        config: cfg,
+        state,
+        serviceManager: {
+          kind: mgr.kind,
+          available: serviceCheck.available,
+          fallbackReason: fallbackReason2,
+          services
+        },
+        agentGateway: agentGatewayHealth,
+        tools,
+        npmShims: shimReport,
+        warnings,
+        hints
+      })
+    );
+    return;
   }
   console.log("");
-  console.log("Choose agent framework:");
-  const def = defaultFrameworkId();
-  all.forEach((f, i) => {
-    const marker = f.id === def ? "*" : " ";
-    const tag = f.status === "coming-soon" ? "  [coming soon]" : "";
-    const padName = f.displayName.padEnd(12);
-    console.log(`  ${marker} [${i + 1}] ${padName} ${f.description}${tag}`);
-  });
+  console.log(`  OS/Arch  : ${p.platform()}/${process.arch}`);
+  console.log(`  Node.js  : ${process.version}`);
+  console.log(`  API URL  : ${cfg.platform.api_url}`);
+  console.log(
+    `  AgentGw  : ${resolvedAgentGatewayUrl} [${formatAgentGatewayStatus(agentGatewayHealth)}]`
+  );
   console.log("");
-  const defaultIdx = all.findIndex((f) => f.id === def) + 1;
-  const answer = await prompt(`Choose [1-${all.length}] (default ${defaultIdx}): `);
-  const trimmed = answer.trim();
-  if (!trimmed) return def;
-  const idx = parseInt(trimmed, 10);
-  if (!Number.isFinite(idx) || idx < 1 || idx > all.length) {
-    return def;
+  for (const line of summarizeExistingInstall(state)) {
+    console.log(`  ${line}`);
   }
-  const picked = all[idx - 1];
-  if (picked.status !== "available") {
+  console.log(
+    `  Service manager: ${mgr.kind}${fallbackReason2 ? " (fallback)" : ""} \u2014 ${services.length} service(s) registered`
+  );
+  for (const s of services) {
+    const status2 = s.running ? "running" : s.installed ? "stopped" : "uninstalled";
+    const pid = s.pid != null ? ` pid=${s.pid}` : "";
+    console.log(`    - ${s.id.padEnd(28)} ${status2}${pid}`);
+  }
+  console.log(`  adb          : ${tools.adb.path ?? "not found"}`);
+  console.log(`  scrcpy-bridge: ${tools.scrcpyBridge.path ?? "not installed (auto on attach)"}`);
+  console.log(`  vnc-bridge   : ${tools.vncBridge.path ?? "not installed (auto on --vnc-host)"}`);
+  console.log("");
+  console.log("  npm shims:");
+  for (const e of shimReport.entries) {
+    const marker = shimMarker(e.outcome);
+    const installed = e.installed ?? "(missing)";
+    const latest = e.latest ?? "(unknown)";
     console.log(
-      `  ${picked.displayName} is not yet available. Falling back to ${def}.`
+      `    ${marker} ${e.pkg.padEnd(34)} installed=${installed.padEnd(8)} npm=${latest}`
     );
-    return def;
   }
-  return picked.id;
+  console.log("");
+  if (warnings.length > 0) {
+    console.log("  Warnings:");
+    for (const w of warnings) {
+      console.log(`    - ${w}`);
+    }
+    console.log("");
+  } else {
+    console.log("  No warnings \u2014 machine looks good.\n");
+  }
+  if (hints.length > 0) {
+    console.log("  Hints:");
+    for (const h of hints) {
+      console.log(`    $ ${h}`);
+    }
+    console.log("");
+  }
 }
-async function safeListAdbDevices() {
-  const adbPath = await findAdb().catch(() => null);
-  if (!adbPath) return [];
-  try {
-    return await deviceRuntime.listAdbDevices();
-  } catch {
-    return [];
-  }
+async function collectToolStatus() {
+  const [adbPath, scrcpyPath, vncPath] = await Promise.all([
+    findAdb().catch(() => null),
+    scrcpyBridgeRuntime.findBinary().catch(() => null),
+    vncBridgeRuntime.findBinary().catch(() => null)
+  ]);
+  return {
+    adb: { path: adbPath },
+    scrcpyBridge: { path: scrcpyPath },
+    vncBridge: { path: vncPath }
+  };
 }
-async function pickFreshInstance(_opts) {
-  const frameworks = availableFrameworks().map((f) => ({
-    kind: "framework",
-    id: f.id,
-    label: f.displayName,
-    description: f.description,
-    isDefault: f.id === defaultFrameworkId()
-  }));
-  const devices = (await safeListAdbDevices()).map((d) => ({
-    kind: "device",
-    serial: d.serial,
-    status: d.status
-  }));
-  return pickInstanceInteractive([...frameworks, ...devices], {
-    caller: "init"
-  });
+async function collectShimReport(hasBoundDevices) {
+  const sources = readPinSourcesFromEnv();
+  const deviceSuite = /* @__PURE__ */ new Set([
+    NPM_PKGS.DEVICE_AGENT,
+    NPM_PKGS.DEVICE_MCP_SERVER
+  ]);
+  const entries = await Promise.all(
+    ALL_BEEOS_PKGS.map(async (pkg) => {
+      const spec = resolveInstallSpec(pkg, sources);
+      const [installed, latest] = await Promise.all([
+        npmGlobalVersion(pkg).catch(() => null),
+        npmRegistryVersion(spec).catch(() => null)
+      ]);
+      let outcome;
+      if (latest === null) outcome = "error";
+      else if (installed === null) {
+        outcome = deviceSuite.has(pkg) && !hasBoundDevices ? "not_installed_yet" : "missing";
+      } else if (installed === latest) outcome = "ok";
+      else outcome = "outdated";
+      if (pkg === NPM_PKGS.CLI && installed === null) {
+        outcome = "missing";
+      }
+      return { pkg, installed, latest, spec, outcome };
+    })
+  );
+  return { entries };
 }
-async function maybePromptServiceInstall() {
-  try {
-    const mgr = await getServiceManager();
-    maybePrintFallbackBanner(mgr.kind);
-    const check = await mgr.selfCheck();
-    if (!check.available) {
-      console.log(`  \u26A0 Service manager '${mgr.kind}' is not fully available \u2014 persistence limited.`);
-    }
-    for (const w of check.warnings) console.log(`  ! ${w}`);
-    for (const h of check.hints) console.log(`  $ ${h}`);
-  } catch (e) {
-    console.log(`  (service-manager self-check skipped: ${e instanceof Error ? e.message : String(e)})`);
+function shimMarker(outcome) {
+  switch (outcome) {
+    case "ok":
+      return "\u2713";
+    case "outdated":
+      return "\u2191";
+    case "missing":
+      return "\u2717";
+    case "not_installed_yet":
+      return "\xB7";
+    case "error":
+      return "?";
   }
 }
-async function rotateIdentity() {
-  const p = getPlatformAdapter();
-  const home = beeoHome();
-  const identityDir = p.joinPath(home, "identity");
-  const keypair = p.joinPath(identityDir, "keypair.json");
-  const fp = p.joinPath(identityDir, "fingerprint");
-  if (!await p.exists(keypair)) return;
-  const ts = Math.floor(Date.now() / 1e3);
-  const backup = p.joinPath(identityDir, `keypair.json.backup-${ts}`);
-  try {
-    await p.copyFile(keypair, backup);
-  } catch {
-  }
+async function checkLogFileSizes() {
+  const dir = path9.join(beeoHome(), "logs", "services");
+  let entries;
   try {
-    await p.rm(keypair);
+    entries = await fs9.readdir(dir);
   } catch {
+    return [];
   }
-  try {
-    await p.rm(fp);
-  } catch {
+  const bloated = [];
+  for (const name of entries) {
+    if (!name.endsWith(".log")) continue;
+    const full = path9.join(dir, name);
+    try {
+      const st = await fs9.stat(full);
+      if (st.isFile() && st.size >= LOG_SIZE_WARN_BYTES) {
+        bloated.push({ path: full, size: st.size });
+      }
+    } catch {
+    }
   }
-  console.log(`Rotated identity. Previous keypair saved at ${backup}`);
-}
-function printBanner() {
-  console.log("");
-  console.log("  BeeOS init");
-  console.log("");
-}
-function printNextSteps() {
-  console.log("");
-  console.log("Next steps:");
-  console.log("  beeos status                  # show running agents");
-  console.log("  beeos device attach           # bind a physical Android device");
-  console.log("  beeos doctor                  # health check & diagnostics");
-  console.log("");
-}
-function prompt(question) {
-  const rl = readline3.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer);
-    });
-  });
+  return bloated;
 }
-async function shouldUpgradeBeeosSuite(options) {
-  if (options.headless) return false;
-  if (process.env.BEEOS_INIT_SKIP_NPM_UPGRADE === "1") return false;
-  return true;
+function formatBytes(n) {
+  if (n >= 1024 * 1024 * 1024) return `${(n / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(0)}MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(0)}KB`;
+  return `${n}B`;
 }
-async function upgradeAndMaybeExit(options) {
-  if (options.json) {
-    return false;
-  }
-  const packages = await pickInstalledPackages();
-  console.log("Checking for newer @beeos-ai/cli on npm...");
-  const reporter = new CliReporter();
-  let outcome;
+async function probeAgentGateway(baseUrl) {
+  const url = joinHealthzUrl(baseUrl);
+  const started = Date.now();
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), 3e3);
   try {
-    outcome = await upgradeBeeosSuite({
-      packages,
-      progress: reporter
+    const res = await fetch(url, {
+      method: "GET",
+      signal: ac.signal,
+      headers: { accept: "application/json, text/plain;q=0.9, */*;q=0.1" }
     });
-  } catch (e) {
-    reporter.stop();
-    console.log(
-      `  (upgrade skipped \u2014 ${e instanceof Error ? e.message : String(e)})
-  Tip: re-run \`npm install -g @beeos-ai/cli\` manually. The device
-  suite (device-agent + device-mcp-server) will be auto-installed
-  on the next \`beeos device attach\`.`
-    );
-    return false;
-  }
-  reporter.stop();
-  if (outcome.anyFailed) {
-    const failed = outcome.packages.find((p) => p.failed)?.failed ?? "unknown error";
-    console.log(`  \u26A0 npm install failed: ${failed}`);
-    console.log(
-      "    Manual fix:\n      npm i -g @beeos-ai/cli\n    (the device suite is auto-installed on `beeos device attach`)\n"
-    );
-    return false;
-  }
-  if (!outcome.anyChanged) {
-    console.log("  All BeeOS npm packages are up to date.\n");
-    return false;
-  }
-  for (const pkg of outcome.packages) {
-    if (pkg.changed) {
-      console.log(`  ${pkg.pkg}: ${pkg.before ?? "(none)"} \u2192 ${pkg.after}`);
+    const latency = Date.now() - started;
+    if (res.ok) {
+      return {
+        url,
+        status: "ok",
+        httpStatus: res.status,
+        latencyMs: latency,
+        detail: `HTTP ${res.status} in ${latency}ms`
+      };
     }
+    return {
+      url,
+      status: "unhealthy",
+      httpStatus: res.status,
+      latencyMs: latency,
+      detail: `HTTP ${res.status} in ${latency}ms`
+    };
+  } catch (err) {
+    const latency = Date.now() - started;
+    const msg = err instanceof Error ? err.message : String(err);
+    const timedOut = ac.signal.aborted;
+    return {
+      url,
+      status: "unreachable",
+      httpStatus: null,
+      latencyMs: latency,
+      detail: timedOut ? "timeout after 3s" : msg
+    };
+  } finally {
+    clearTimeout(timer);
   }
-  const cliEntry = outcome.packages.find((p) => p.pkg === NPM_PKGS.CLI);
-  if (cliEntry?.changed) {
-    console.log("");
-    console.log("  CLI itself was upgraded \u2014 please re-run `beeos init` to continue");
-    console.log("  with the new code. The current process is still running the old version.");
-    console.log("");
-    return true;
-  }
-  console.log("  Agents updated. Continuing init...\n");
-  return false;
 }
-async function pickInstalledPackages() {
-  const packages = [NPM_PKGS.CLI];
-  for (const pkg of [NPM_PKGS.DEVICE_AGENT, NPM_PKGS.DEVICE_MCP_SERVER]) {
-    const installed = await npmGlobalVersion(pkg).catch(() => null);
-    if (installed !== null) packages.push(pkg);
-  }
-  return packages;
+function joinHealthzUrl(base) {
+  const trimmed = base.replace(/\/+$/, "");
+  return `${trimmed}/healthz`;
+}
+function formatAgentGatewayStatus(h) {
+  if (h.status === "ok") return `ok ${h.latencyMs}ms`;
+  if (h.status === "unhealthy") return `HTTP ${h.httpStatus ?? "?"}`;
+  return h.detail;
 }
 
 // src/commands/service.ts
@@ -7924,8 +8134,8 @@ setPlatformAdapter(new NodePlatformAdapter());
 var program = new Command();
 var cliVersion = getCliVersion(import.meta.url, resolveActiveDistTag());
 program.name("beeos").version(cliVersion.display).description("BeeOS \u2014 run AI agents from your desktop");
-program.command("init").description("One-shot install + bind flow (default entry from the curl installer)").option("--framework <name>", "Agent framework to install (default: openclaw)").option("--yes", "Non-interactive \u2014 accept the default action", false).option("--json", "Output machine-readable JSON (implies --yes)", false).option("--no-browser", "Don't auto-open a browser for bind confirmation").option("--headless", "Never open a browser (use terminal QR only)", false).option("--skip-service-prompt", "Skip the system-service install prompt", false).option("--device", "Jump straight into `beeos device attach` instead", false).action((opts) => run8(opts));
-program.command("doctor").description("Inspect local BeeOS state (install, binding, services, warnings)").option("--json", "Output machine-readable JSON", false).action((opts) => run7(opts));
+program.command("init").description("One-shot install + bind flow (default entry from the curl installer)").option("--framework <name>", "Agent framework to install (default: openclaw)").option("--yes", "Non-interactive \u2014 accept the default action", false).option("--json", "Output machine-readable JSON (implies --yes)", false).option("--no-browser", "Don't auto-open a browser for bind confirmation").option("--headless", "Never open a browser (use terminal QR only)", false).option("--skip-service-prompt", "Skip the system-service install prompt", false).option("--device", "Jump straight into `beeos device attach` instead", false).action((opts) => run7(opts));
+program.command("doctor").description("Inspect local BeeOS state (install, binding, services, warnings)").option("--json", "Output machine-readable JSON", false).action((opts) => run8(opts));
 program.command("migrate").description("Migrate legacy Node supervisor state to OS-native services (one-shot)").option("--json", "Output machine-readable JSON", false).action((opts) => run9(opts));
 program.command("logs").description(
   "Tail logs for a BeeOS service. Pass an ADB serial or service id; omit to list every registered service's log file path."